# Contributing

Thanks for your interest in dsh-intercom!

## Workflow

We use **trunk-based development**:

- `main` is always releasable. Work happens on short-lived branches.
- Open a pull request against `main`. A PR must:
  - pass CI (`lint`, `typecheck`, `build`, `test` on ubuntu/windows/macos × node 20/22, plus the `lib/` build-artifact consistency check),
  - get at least one review,
  - use a [Conventional Commits](https://www.conventionalcommits.org/) title (e.g. `feat: ...`, `fix: ...`, `chore: ...`) — commitlint enforces this on commit messages locally, and the PR title should follow the same convention.
- Squash-merge into `main`.

## Setup

```bash
pnpm install
pnpm setup-hooks   # once per clone: installs the git hooks below
```

Git hooks via simple-git-hooks: a pre-commit hook runs lint-staged (prettier +
oxlint on staged files) and a commit-msg hook runs commitlint. Hook install is
a manual step (not a `prepare` script) on purpose: a `prepare` script makes
pnpm block `dsh plugin add github:...` installs of this repo behind an
onlyBuiltDependencies allowlist, which would break the zero-friction install.

## Common commands

```bash
pnpm build       # tsdown → lib/ (committed build artifacts)
pnpm test        # tsx --test (node:test)
pnpm lint        # oxlint
pnpm format      # prettier --write
pnpm typecheck   # tsc --noEmit
pnpm changeset   # add a changeset for user-facing changes
```

## 如何跑验收 (Running the acceptance gate)

The full local acceptance gate, in order — everything must be green:

```bash
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm format && pnpm format:check
pnpm test          # unit + integration, incl. broker abuse tests and the
                   # README docs-as-tests check (tests/docs.test.ts)
pnpm build         # regenerate lib/ — commit the result (see below)
pnpm test:e2e      # real-dsh cross-process end-to-end (needs global dsh)
pnpm test:install  # install preview: pack → tarball inspection → install and
                   # boot in a scratch DSH_HOME with the real dsh CLI
```

`pnpm test:e2e` and `pnpm test:install` require a globally installed `dsh`
(resolved from `npm root -g`, or point `DSH_BIN` at
`.../@deepseek-ai/dsh/lib/bin.js`) and a built `lib/`. Both run entirely
against scratch `DSH_HOME` directories — the real `~/.dsh` is never touched.

## Build artifacts are committed

`lib/` is generated by `pnpm build` and **must be committed** together with any
source change: dsh installs plugins directly from GitHub without running a
build. CI fails if `lib/` is out of sync with the sources.

## Versioning & releases

We use [Changesets](https://github.com/changesets/changesets). Add a changeset
(`pnpm changeset`) for any user-facing change. Releases are cut from `main` by
the release workflow.

## Vendored code

`broker/`, `types.ts`, and `cwd.ts` are vendored from
[pi-intercom](https://github.com/nicobailon/pi-intercom) (MIT) — see
[NOTICE](NOTICE). Keep changes to vendored files minimal and documented in
NOTICE so future upstream syncs stay easy.

## Code of Conduct

Participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).