Contributing

Thanks for your interest in dsh-tool-git! This guide covers development setup, conventions, testing, and the contribution workflow.

Development setup

Requirements:

• Node.js ≥ 22
• pnpm ≥ 11 (the lockfile is generated by pnpm 11.3.0; pnpm install --frozen-lockfile is used in CI)
• git (obviously 😄)

git clone git@github.com:Huasfan/dsh-tool-git.git
cd dsh-tool-git
pnpm install        # all dev dependencies come from npm; no local dsh install needed
pnpm typecheck      # tsc --noEmit (strict)
pnpm test           # vitest — 28 tests
pnpm build          # esbuild bundle → lib/index.js

To try the plugin in a real harness:

# bundle layer
dsh --profile web --patch /abs/path/to/dsh-tool-git/cordis.patch.yml
# or load the TypeScript source directly (the loader supports .ts)
#   name: '/abs/path/to/dsh-tool-git/src/index.ts'

Repository layout

src/                plugin entry (index.ts), git runner (git.ts),
                    porcelain-v2 parser (status.ts), tool definitions (tools.ts)
tests/              vitest suites
scripts/build.mjs   prepare build (esbuild bundle)
cordis.patch.yml    dsh bundle layer

Conventions

• TypeScript, strict, erasable-only syntax (no enums / namespaces / parameter properties) — the source must stay loadable by Node's type stripping.
• Follow the tool contract (per the official tool authoring reference):
  • execute returns exactly one canonical JSON value declared by output.schema;
  • human-readable prose lives in output.render, never in the canonical value;
  • non-zero git exits are domain outcomes (ok: false + error), infrastructure failures throw;
  • honor exec.signal for cooperative cancellation.
• No shell interpolation — always pass argument arrays to execFile.
• Keep schemas, execute, and render in sync; add or update tests with every behavior change.

Testing

• Parser changes → unit tests in tests/status.test.ts (fixtures are real captured outputs).
• Tool behavior → integration tests in tests/tools.test.ts against throwaway repositories created in a temp directory.
• Never run git commands against a real working tree in tests. Always pass an explicit workdir pointing at the scratch repo — without it, git acts on the test process's cwd (this has bitten us before).
• Run the full suite before pushing: pnpm test must pass, plus pnpm typecheck and pnpm build.

Commit & pull request workflow

1. Create a branch: git checkout -b feat/your-change.
2. Make focused commits with clear messages (English preferred, conventional style: feat:, fix:, chore:, docs:, test:).
3. Update the bilingual READMEs / release notes if your change is user-facing (keep README.md and README.zh.md in sync).
4. Open a pull request against main; the CI checks (typecheck / test / build / real-harness load) must pass.
5. In the PR description, mention:
   • what the change does and why;
   • which dsh version you tested against;
   • any compatibility impact (dsh is in preview — interface changes are expected).

Compatibility policy

• dsh is still pre-1.0; peer/dev dependencies are pinned exactly to the packages shipped with the tested dsh version.
• When you upgrade the tested dsh version, bump the pins in package.json, update the Compatibility section in both READMEs, and re-run the full suite.
• If an upstream interface change breaks this plugin, prefer fixing here and documenting the required dsh version over silent workarounds.

Reporting issues

• Use GitHub Issues: include the dsh version, git version, OS, the exact steps to reproduce, and any relevant logs (e.g., the [git-tool] loaded line and tool errors from the dsh web terminal).
• Feature requests and discussions are welcome in Issues too.

License

By contributing you agree that your contributions are licensed under the MIT License (see LICENSE).