dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/CONTRIBUTING.md

@@ -14,14 +14,22 @@ the conventions this repository uses.
 
 ## Toolchain
 
-The runtime package ships an empty `dependencies` object on purpose: it is
+The runtime package ships no `dependencies` field at all, on purpose: it is
 loaded into the DSH process and everything it needs arrives as a peer package.
 Running the plugin from a checkout has no install step.
 
-Developing and running the gates do have dependencies. The 0.7.x tests import
-pinned `@deepseek-ai/*` packages — the composition and boot tests run the
-loader's real patch algorithm — so a fresh checkout needs one `pnpm install`
-before the gates pass.
+Developing and running the gates do have dependencies. The tests import pinned
+`@deepseek-ai/*` packages — the composition test runs the loader's real patch
+algorithm, and the boot test starts a row through the real Loader — so a fresh
+checkout needs one `pnpm install` before the gates pass.
+
+Those pins are deliberate, and they move with the harness rather than on their
+own: the `@deepseek-ai/dsh-*` peers sit at `0.2.1-rc.2`, `@deepseek-ai/cordis`
+at `~4.0.5` and `@deepseek-ai/schemastery` at `~3.18.5`. The plugin subclasses
+peer classes and mirrors peer protocol, so raising one pin alone is how the
+seams drift: bump them in the commit that matches a harness release, re-run the
+comparison `docs/PEER-PARITY.md` describes, and let the gate chain and the
+probes confirm the result.
 
 pnpm runs the scripts in this repository, pinned through the `packageManager`
 field (corepack resolves it). Treat `pnpm run <script>` as the reference
@@ -40,24 +48,24 @@ Exactly three dependencies run install scripts (`@deepseek-ai/dsh-subprocess-loc
 
 ## The type gate
 
-`lint:types` runs `tsc --noEmit` under `strict` with `checkJs`: the JavaScript
-in `lib/` is fully type-checked, and the types come from the peer packages'
-own `.d.ts` — nothing is invented twice. `types/dsh-services.d.ts` pulls in the
-`declare module '@deepseek-ai/cordis'` augmentations the service packages ship,
-so `ctx.fs`, `ctx.shell`, `ctx.sandboxPolicy` and friends are typed; it declares
-nothing itself and ships nowhere.
-
-The gate's scope is what is NOT generated: `test/**` (the probe scripts
-included) and the ambient service types the build shares. The sources under
-`src/` are checked by the build program itself (`strict`, `noEmitOnError`),
-which is strictly stronger than checking their emitted JavaScript. The shipped
-artifact was checked first because it is where protocol drift with the pinned
-peers hurts; the tests and probes came next, and the errors they surfaced were
-real — a test that pinned a raw number into an argv, a couple of hand-written
-JSDoc contracts wider than the code (`wslErrorCode`, `gitSpawnRewrite`) and
-narrower than their seams, and one accepted-but-never-enforced byte-window cap
-in the distro-routed file service, found because a fake hands the confinement
-seam an `"full"` enforcement the core itself never reports.
+`lint:types` runs `tsc --noEmit` under `strict` with `checkJs` over what is NOT
+generated — `test/**` and the ambient types — and the types come from the peer
+packages' own `.d.ts`: nothing is invented twice. `types/dsh-services.d.ts`
+pulls in the `declare module '@deepseek-ai/cordis'` augmentations the service
+packages ship, so `ctx.fs`, `ctx.shell`, `ctx.sandboxPolicy` and friends are
+typed; it declares nothing itself and ships nowhere.
+
+The probe scripts under `test/probe/` are inside the gate as well. The sources
+under `src/` are checked by the build program itself (`strict`,
+`noEmitOnError`), which is strictly stronger than checking their emitted
+JavaScript. The shipped artifact was checked first because it is where protocol
+drift with the pinned peers hurts; the tests and probes came next, and the
+errors they surfaced were real — a test that pinned a raw number into an argv,
+a couple of hand-written JSDoc contracts wider than the code (`wslErrorCode`,
+`gitSpawnRewrite`) and narrower than their seams, and one
+accepted-but-never-enforced byte-window cap in the distro-routed file service,
+found because a fake hands the confinement seam an `"full"` enforcement the core
+itself never reports.
 
 Three patterns keep the check honest:
 
@@ -69,9 +77,12 @@ Three patterns keep the check honest:
   at the injection point — the cast states which contract the double stands in
   for, instead of silencing the mismatch with `any`.
 - `@ts-expect-error` is allowed exactly when the suppressed error names a real
-  upstream seam gap, carries the reason inline, and the gap is written up in
-  `docs/UPSTREAM-*.md`. It is a published finding with a tracking doc, not a
-  silencer.
+  upstream seam gap, carries the reason inline, and the gap is written up — in a
+  `docs/UPSTREAM-*.md` tracking doc when the fix is an upstream ask (the
+  `LocalBashExecutor.spawnSpec` seam has one), or in the source comment itself
+  when the honest fix needs a protocol decision this package owns (the exit-4
+  relay's unknown entry kind is the other site, deliberately left visible). It
+  is a published finding, not a silencer.
 
 ## The build
 
@@ -119,15 +130,25 @@ Rules that keep this honest:
 2. `pnpm run build`, then `pnpm test`. There is no exclude list to maintain and
    no registration step: the build and `lint:build` derive everything from
    `src/`, and `lib/` is generated output — never edit it by hand.
+3. If the module gets a row of its own on the Plugins page, add its display
+   metadata as `locale/<name>/en.json` and `locale/<name>/zh.json` — a
+   `meta.title` / `meta.description` pair each — and expose both through
+   `exports` (`./<name>/locale/en.json`, `./<name>/locale/zh.json`), which is
+   what that page reads before falling back to the package `description`. The
+   bundle's own pair is `locale/en.json` / `locale/zh.json`, and `subprocess`,
+   `picker`, `shell-env` and `auto-preset` carry theirs; `files` already ships
+   `locale/**/*.json`, and `lint:style` fails an `exports` target that does not
+   exist.
 
 ## The development loop
 
 1. Clone the repository inside the distro. Most contributors develop there.
 2. Make the change.
 3. Run the gates below.
-4. Restart the DSH app before testing by hand, if you changed anything under
-   `lib/`. A running process caches ES modules, so it keeps the old code
-   otherwise.
+4. If you changed anything under `lib/`, run `pnpm run sync:windows` first and
+   then restart the DSH app. The app loads the Windows mirror (see below), so a
+   restart without the sync just reloads the old code; a running process also
+   caches ES modules.
 
 ### The runtime mirror
 
@@ -151,26 +172,28 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `pnpm test` | style checks, syntax pass, type check, and unit tests | no |
+| `pnpm test` | style checks, syntax pass, build consistency, type check, and unit tests | no |
 | `pnpm run test:coverage` | unit tests with coverage | no |
 | `pnpm run lint:style` | style and lint rules | no |
-| `pnpm run lint:types` | the TypeScript check over `lib/` (`tsc --noEmit`) | no |
+| `pnpm run lint:build` | the build-freshness check: every source has its artifacts and the committed bytes match a real build | no |
+| `pnpm run lint:types` | the TypeScript check over `test/**` and the ambient types (`tsc --noEmit`) | no |
 | `pnpm run probe` | filesystem behaviour against a real distro | yes |
 | `pnpm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `pnpm run probe:sandbox-shell` | the confined executor through a real boot | yes |
 | `pnpm run probe:terminal` | the terminal provider | yes |
-| `pnpm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
-| `pnpm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
-| `pnpm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
-| `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
+| `pnpm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | no; inside the distro |
+| `pnpm run probe:watch` | the in-distro watcher over a real directory | no; inside the distro |
+| `pnpm run probe:agent` | the resident-vs-one-shot fallback parity legs | no; inside the distro |
+| `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | no; inside the distro |
 | `pnpm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
 | `pnpm run probe:picker` | the picker's root level, its refusals and its cap | yes |
 | `pnpm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
 | `pnpm run probe:sandbox-off` | the documented opt-out on both providers | yes |
 
 Every script above is wired in `package.json`. `pnpm test` runs `lint:style`,
-`test:syntax`, `lint:types` and `test:unit` in that order. `prepublishOnly` runs `pnpm test` again
-at publish time, so a broken gate stops a release before the upload.
+`test:syntax`, `lint:build`, `lint:types` and `test:unit` in that order.
+`prepublishOnly` runs `pnpm test` again at publish time, so a broken gate stops a
+release before the upload.
 
 CI runs `pnpm test` on Node 22 and 24, on both `ubuntu-latest` and
 `windows-latest`, and `pnpm run test:coverage` on Node 24. The Windows runners are
@@ -181,6 +204,19 @@ The probes marked "yes" need Windows, WSL2, a mounted harness profile and a link
 checkout, which a hosted runner does not have. Run them on your own machine and
 paste the output into the pull request.
 
+The rows marked "no; inside the distro" (`substrate`, `watch`, `agent`, `exec`)
+still need Windows and WSL2, but no harness boot and no profile: run them from a
+distro terminal with Node available, and they reach `wsl.exe` through interop.
+
+Two conveniences for the real-machine set. `test/probe/run-all-when-closed.sh
+--include-fs` runs all twelve probes once the app has exited. And `ci.yml` has a
+`probes` job you dispatch by hand: `sandbox` runs whenever WSL is present, then
+`mode`, `terminal`, `picker` and `missing-wsl` where the harness app is
+installed. It is named for a self-hosted Windows runner although its `runs-on`
+carries the hosted `windows-latest` label, and it is not a green no-op on a
+hosted runner — the `sandbox` leg fails, not skips, where the default distro has
+no bubblewrap.
+
 ## Adding a test
 
 Choose the layer by what the test needs.
@@ -190,44 +226,70 @@ Choose the layer by what the test needs.
 | Unit test | `test/*.test.mjs` | pure logic: path translation, listing, shell argument building, terminal helpers |
 | Probe | `test/probe/` | behaviour that needs a real distro, a real profile, or bubblewrap |
 
-Unit tests run under `node --test`. A test that imports only this repository goes in
-both the `test:unit` and the `test:coverage` lists in `package.json`, which name
-their files explicitly. A test that needs a DSH peer — `test/sandbox.test.mjs`
-imports `lib/sandbox.js`, which imports `@deepseek-ai/dsh-sandbox` — goes in
-`test:unit` only and must skip itself when the peer is missing, because CI installs
-nothing: try the import, print a `SKIP` line, exit 0.
-
-Probes are shell scripts that mount a throwaway profile, plus the small plugin
-files they load. Those plugin files are the `*-probe.mjs` and `*-probe.yml` files
-in the same directory. The setup steps for the throwaway profile are in the header
-of `test/probe/run.sh`. `terminal.sh` and `sandbox-shell.sh` reuse it.
+Unit tests run under `node --test`. The `test:unit` and the `test:coverage` lists
+in `package.json` name their files explicitly; a test that only touches this
+repository belongs in both. Two lags in those lists today are hygiene to fix in
+passing, not a pattern to copy: each names one file twice
+(`test/fsio-text.test.mjs` in `test:unit`, `test/fs.boot.test.mjs` in
+`test:coverage`), and `test/fs-routing.test.mjs` is in neither
+(`docs/REQUIREMENTS.zh.md` tracks that as OI-7).
+
+A test that imports a pinned `@deepseek-ai/*` package goes in the same lists and
+needs no guarding — CI runs `pnpm install --frozen-lockfile` over the locked tree
+before `pnpm test`. Five files import such packages at runtime today —
+`test/provider.test.mjs` is what covers the assembled service rows, and
+`test/composition.test.mjs` runs the loader's real patch algorithm — and a sixth
+(`test/terminal-activity.test.mjs`) reaches a peer only through a JSDoc type
+import, which `checkJs` still resolves.
+
+Where a peer-free seam exists, prefer it. `test/sandbox.test.mjs` runs against
+`lib/sandbox-core.js`, with a stand-in for the peer's `SandboxUnavailableError`
+contract, which leaves only the one-line peer binding in `lib/sandbox.js`. That
+line is covered by the harness probes, which boot the plugin and so reach
+`WslSandbox` through `lib/index.js` — not by `probe:sandbox`, which reads only
+the argument builder out of `lib/bwrap.js`. A test that cannot run everywhere
+must skip itself — print a `SKIP` line and exit 0 — the way that file does on
+`win32`, where its fake `wsl.exe` (a POSIX script) cannot execute.
+
+Probes are shell scripts, plus the small plugin files they load: the `*-probe.mjs`
+and `*-probe.yml` files in the same directory. Two shapes. The harness probes
+(`run.sh`, `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `missing-wsl.sh`,
+`sandbox-off.sh`) boot a throwaway profile whose setup steps are in the header of
+`test/probe/run.sh`; the five others reuse the profile `run.sh` creates rather
+than making their own. The distro probes (`substrate.sh`, `watch.sh`, `agent.sh`,
+`exec.sh`) boot nothing: they run from a distro terminal and drive the resident
+agent through the `wsl.exe` interop transport. `sandbox.sh` and `mode.sh` sit
+outside both groups — no harness boot, no profile.
 
 Keep probe output idempotent. Several probes delete their scratch files at the
 start, because a leftover file from an earlier run changes the result.
 
 ## What has been verified
 
-`pnpm test` covers the pure modules and runs a `--check` pass over every shipped
-module. It cannot import the service modules, because those need DSH peer packages
-that a bare checkout does not have. Only booting the harness closes that gap, which
-is why the probes exist; the archived record's §15.4 documents the five rounds of
-misdiagnosis the gap once caused.
+`pnpm test` runs the whole unit suite once the one `pnpm install` above has
+fetched the pinned packages: the files that import them statically exercise the
+services through the loader and their declared types, and `test:syntax` keeps a
+`node --check` pass over every shipped module. What no test on a Linux leg can
+reach is the Windows-plus-WSL2 topology itself: a real `wsl.exe`, a real distro,
+a real harness boot. That is the gap the probes close; the archived record's
+§15.4 documents the five rounds of misdiagnosis it once caused.
 
 `test/probe/sandbox.sh` needs no harness: it uses the same arguments
 `lib/sandbox.js` builds and asserts what bubblewrap does and does not confine,
 recording the interop escape as `INFO` because a Linux sandbox cannot govern a
-Windows process. The other probes boot a throwaway profile bound to the distro:
+Windows process. The harness probes boot a throwaway profile bound to the distro:
 
 - the filesystem probe asserts the write path and the write checks — a write outside
   the policy root and a write in `read-only` mode both return `FS_SANDBOX_DENIED`,
-  while `danger-full-access` is not checked;
+  while `danger-full-access` is the approved escalation and its write is asserted
+  to land;
 - the shell probe drives all three modes through `ctx.shell` and checks the refusal
   classification the tool layer returns;
 - the terminal probe asserts the distro, the starting directory, and the `DSH_*`
   variables forwarded through `WSLENV`.
 
-The setup steps for the throwaway profile are in the header of `test/probe/run.sh`;
-`terminal.sh` and `sandbox-shell.sh` reuse it.
+The setup steps for that throwaway profile are in the header of
+`test/probe/run.sh`; the harness probes share the one profile it creates.
 
 On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
 
@@ -242,11 +304,12 @@ On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
   outside the session workspace is refused inside the distro and the following
   wider-permission request succeeds.
 
-Counts: 57 unit assertions on a bare checkout, plus 5 in `test/sandbox.test.mjs` which
-need the `dsh-sandbox` peer and skip themselves without it; 19 filesystem-probe
-assertions; 15 shell-probe checks; 9 picker checks; 6 missing-executable checks; 5 mode
-checks; 5 opt-out checks and 10 sandbox expectations plus the recorded escape; and 3
-terminal assertions.
+Counts: 28 unit test files under `test/` — 27 of them registered in the
+`test:unit` list, see the OI-7 note above — which need the pinned packages
+installed, and over 1000 `assert` call sites across them; 19 filesystem-probe
+assertions; 15 shell-probe checks; 9 picker checks; 6 missing-executable checks;
+5 mode checks; 5 opt-out checks and 10 sandbox expectations plus the recorded
+escape; and 3 terminal assertions.
 
 ## Commit and pull request conventions