Contributing

Thanks for helping. This page covers everything needed to go from a clone to a pull request. The user-facing documentation is in README.md.

The plugin is in beta: interfaces, stored formats and the tool contract may still change between pre-releases.

Setup

Requirements: Node ^22.19.0 || >=24, pnpm (the version is pinned in package.json → packageManager; corepack enable picks it up).

git clone https://github.com/KKL08/dsh-plastic-memory.git
cd dsh-plastic-memory
pnpm install --frozen-lockfile
pnpm typecheck && pnpm test && pnpm build

pnpm build compiles src/ to lib/ (git-ignored; that is what npm ships). Dev dependencies, including the @deepseek-ai/* host packages, come from npm at the exact versions the plugin is built against — no checkout of the host is needed.

Layout

Path	What it is
src/	The plugin. Each tool is a pure-logic module src/tools/<x>.ts plus a thin binding src/tools/<x>-tool.ts that calls the host's defineTool. Keep that split.
src/contract-codes.ts	The single list of machine-readable codes that tool results carry. Add a code here first, then use it.
tests/	vitest unit and integration tests (tests/helpers/ has shared fixtures).
scripts/host-smoke.sh	Installs the packed plugin into a fresh, pinned dsh host and checks it loads.
scripts/host-contract/	Boots that host with a verify plugin that drives the nine tools through the real tool registry.
docs/	Design notes referenced from source comments (docs/*.md). Not published yet; the contracts they describe are pinned by the tests and by src/contract-codes.ts.

Tests

Three layers, cheapest first. Run the first two on every change; the third before a release or when touching anything that talks to the host.

1. Unit and integration — pnpm test (add --coverage for a report under coverage/). Tests assert behavior through structured fields and codes, not through Chinese prose; one it checks one thing; fixtures come from tests/helpers/; nothing under ~/.dsh is touched. tests/bindings.spec.ts builds the tools with the real defineTool and checks every result against the host's lossless-JSON rule — keep it green when you change a result shape.
2. Install smoke — pnpm host:smoke. Builds and packs the published shape, installs the pinned dsh host into ~/.cache/dsh-plastic-memory (once; later runs take seconds), installs the tarball into a temporary DSH_HOME and checks the config layer and a plain-Node import. No API key.
3. Host contract — pnpm host:contract. Same fresh host plus a sibling verify plugin; nine checks need no key (tool registration, no-cwd rejection, fresh-library health advice, file layout, lossless outputs, rule scan, snapshot round trip, promote dismissal, dangling evidence anchor). Set DEEPSEEK_API_KEY to also run the two semantic-layer checks; the key is written only into the temporary DSH_HOME and never anywhere else.

Set HOST_SMOKE_KEEP=1 to keep the temporary directory (logs, DSH_HOME) of either host check for debugging.

Before opening a PR: write the failing test first when fixing a bug, list the edge cases when adding behavior, and run scripts/check-no-local-paths.sh — it rejects machine-local paths and hostnames in tracked files.

Host version

The plugin is built and tested against one DeepSeek Harness version, pinned by the @deepseek-ai/* dev dependencies (0.1.1-rc.2 today). peerDependencies stay open while the host is in pre-release because npm's semver treats pre-release ranges strictly. Upgrading the host is a deliberate change: bump the dev dependencies together, run all three test layers, and note anything that moved in the changelog.

Commits and pull requests

• Conventional Commits: type(scope): imperative summary (≤ 50 characters, no period), a body wrapped at 72 columns that says what and why.
• One concern per PR; keep the diff surgical and match the surrounding style.
• Update CHANGELOG.md under Unreleased for anything a user would notice.