# Contribute to dsh-developer Use Node.js `^22.18.0 || >=24.11.0`. Install dependencies with `npm ci --ignore-scripts`, make a focused change, then run: ```sh node bin/dsh-developer.js run --source . --script validate npm pack --dry-run ``` The default suite is keyless and deterministic. Process fixtures can also be enabled with `DSH_DEVELOPER_PROCESS_TEST=1` (PowerShell: `$env:DSH_DEVELOPER_PROCESS_TEST='1'`). VM, browser and exact-runtime integration tests have separate opt-in flags; a skipped integration test is not a passing platform claim. Development CI also tests script arguments on pnpm 11.7.0, Yarn Classic 1.22.22 and Yarn 4.18.0. For the same local checks, enable `DSH_DEVELOPER_PNPM_TEST=1` with that pnpm on PATH and set `DSH_DEVELOPER_YARN_CLASSIC_ROOT` and `DSH_DEVELOPER_YARN_MODERN_ROOT` to disposable npm installation prefixes containing those exact packages. Then run `test:development` through the CLI. ## Check upstream API compatibility `npm run validate` includes strict, no-emit TypeScript checking of the JavaScript modules that integrate with DSH. These modules use `@ts-check` and upstream type imports; TypeScript is a development dependency, and installation still runs JavaScript directly without a build step. Run just the compiler check with `npm run typecheck`. To check the same implementation against another installed DSH dependency graph: ```sh npm run typecheck -- --runtime /path/to/dsh-installation ``` The directory must contain `node_modules/@deepseek-ai/dsh`. The checker uses that installation's declarations instead of the repository's pinned DSH development types, including the hot-reload provider declared by that CLI. CI runs it against both exact audit lanes and the moving `latest`, `next` and `alpha` installations, before their runtime checks. Release checks block CI; preview and alpha checks remain advisory. The checked scope is listed in `tsconfig.json`: plugin registration, native commands and tools, authority hooks, isolated Build context adapters, and disposable development probes. Add new DSH-facing modules there and mark them `@ts-check`. Derive service, event and callback contracts from upstream declarations; validate unknown inputs rather than casting away incompatibilities. Upstream declarations are checked too, so broken exported types cannot silently erase a boundary to `any`. Internal analysis engines are not yet fully type-checked. Static checking catches signature drift; runtime tests remain necessary for loading, cancellation, cleanup and behavior. ## Install the current checkout The README's `v0.1.4` Git tag is a published artifact, not this working tree. To exercise current changes from a checkout: ```sh npm ci --ignore-scripts dsh plugin --profile web add . --ignore-scripts ``` Restart DSH after Host code changes. Use a development profile for iteration; install into an existing personal profile only when that is intended. ## Test against DSH Use exact DSH `0.1.5-rc.2` for blocking checks and `0.1.6-alpha.2` for advisory checks. Select the intended installed entry with `--dsh`; do not infer a runtime from a tag name. With the blocking DSH on PATH: ```sh node bin/dsh-developer.js doctor --source . node bin/dsh-developer.js preflight --source . --profile headless node bin/dsh-developer.js preflight --source . --profile web ``` Doctor tests this product's plugin lifecycle in a disposable profile. An ordinary target plugin is inspected under the documented execution restrictions; a static audit is not proof that arbitrary code ran successfully. See the [development guide](development.md) for self-hosting and native-runtime tests, and [verification](verification.md) for results tied to their revision, runtime and host. Isolated providers need separate local infrastructure and admission. The [Mac integration suite](macos.md#enable-isolated-build-and-apply) passed 4/4 real checks on rc.2 with Apple silicon/macOS 26, Apple container 1.4.1 and the pinned image: native admission, VM Build/Apply, promotion, and sparse/churn cleanup. This does not prove alpha isolation. Windows provider tests use `DSH_DEVELOPER_WSL_CELL_TEST=1` and the configured WSL distribution. ## Keep the plugin current Treat an upstream update as one maintenance change across runtime constants, native registry/schema integration, Client contract tables, examples and their lockfiles, Creator exports, skill routes, documentation and CI. A version-string replacement alone is not an upgrade. Use `knowledge` against the exact installation and actual consuming package roots, check published package versions and peer closure, then install with scripts disabled and run example builds/tests through `dsh-developer run`. Exercise the compiled and packed artifacts where their behavior is claimed. Exact audit jobs must use `0.1.5-rc.2` as blocking and `0.1.6-alpha.2` as advisory. Their manifests and complete pnpm lockfiles live in `.github/dsh-runtimes/` and CI installs them with `--frozen-lockfile --ignore-scripts`. An exact launcher version alone is insufficient: its dependency ranges can select newer prerelease packages with incompatible exports. When advancing an audit target, retain the full tested graph in its own directory and review the resulting lockfile changes. Native development CI installs npm `latest`, `next` and `alpha` on each run and records the resolved package versions with the results. That moving matrix detects fresh-install drift; it does not silently change the reviewed audit targets or admit an isolated provider. Refresh front-door claims when contracts change. Keep English and Chinese entry points aligned, identify the tested revision/runtime/host, and distinguish source, published tag, native registry, rendered browser and isolated-provider results. Update only affected historical claims: the `0.1.1-rc.2` → `0.1.2-alpha.3` migration ledger remains a bounded historical contract. Hook Bridge Doctor pins exact current, alpha and historical bytes independently; advancing either contract requires its own evidence. Run documentation and skill-route checks after edits. The main skill owns the shared DeepSeek/GPT intent, implementation and proof decisions so repairs retain them when loading diagnostic support. Native mechanics stay in references. Each support route allows 11,350 UTF-8 bytes including transitive references; tested Build combinations (development with diagnostics, browser or provider support) allow 13,850 bytes. Checks cover both LF and CRLF representations. These are repository maintenance budgets, not token counts or DSH context limits. Moving the Build method into the main skill increases other routes' reading cost but reduces the complete development set. Keep one authoritative home per concern; do not raise budgets merely to retain redundant instructions. ## Change a boundary carefully Keep provider conformance, admission, actual execution, transfer, cleanup and the agent-facing workflow consistent. Add regression cases that reproduce consequential failures; include the host, runtime and provider versions with your results. Changes to isolated execution should exercise cancellation, controller termination and adversarial process/file behavior as well as a successful Build/Apply. Native Mac tests and Linux VM tests establish different things. Report them separately. Generated-plugin promotion must retain atomic no-replace semantics on the host filesystem. ## Work on DSH itself Follow the [upstream contributing guide](https://github.com/deepseek-ai/deepseek-harness#contributing) and the toolchain pinned by your checkout. The [Mac guide](macos.md#develop-dsh-itself) includes the source setup. Keep the upstream commit and native test results distinct from evidence about this repository's exact release lane.