dsh-wsl-tool 1.8.0 → 1.8.1

package/PUBLISHING.md

@@ -0,0 +1,161 @@
+# Publishing
+
+Maintainer notes for releasing this plugin. Four channels carry the same commit
+and they are not interchangeable.
+
+| Channel | What it is | What ships it |
+|---|---|---|
+| GitHub Release asset | what the plugin market installs from | `.github/workflows/release.yml`, on a `v*` tag |
+| npm | the package `dsh-wsl-tool` | the same workflow, as its last step |
+| Catalog entry | the listing line and the install command the market shows | a PR to `awesome-dsh-plugin/awesome-dsh-plugin` |
+| Your working profile | the copy DSH actually loads | `npm run sync`, then a DSH restart |
+
+## The name split is deliberate
+
+The npm package is **`dsh-wsl-tool`**, not `dsh-wsl`. The registry answers
+
+```
+403 Forbidden - PUT https://registry.npmjs.org/dsh-wsl -
+Package name too similar to existing package is-wsl
+```
+
+for the repository name. A name policy is not a permission problem: no token, no
+2FA bypass, and no scope changes it, and the name stays unclaimable. The
+repository, the plugin (`tool-wsl`), and the market listing keep the `dsh-wsl`
+name.
+
+Nothing else depends on that name, because `cordis.patch.yml` names its entry by
+**relative path**:
+
+```yaml
+- insert:
+    - id: tool-wsl
+      name: './index.js'
+```
+
+DSH anchors a relative `name:` beside the patch file that declared it
+(`anchorInsertedPluginNames` in `@deepseek-ai/dsh-app-boot`), so this row loads
+this bundle's own `index.js` whatever the install folder is called —
+`node_modules/dsh-wsl-tool` from npm, `node_modules/dsh-wsl` in a local `file:`
+profile. A bare package name would resolve in only one of those layouts, and
+would silently couple this file to the registry name. `test/smoke.mjs` asserts
+both that the entry stays relative and that it resolves.
+
+## Release checklist
+
+1. Green locally:
+
+   ```sh
+   npm test                                           # shim backend, real WSL
+   DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+   ```
+
+2. Bump, sync, commit, tag, push:
+
+   ```sh
+   npm version <x.y.z> --no-git-tag-version
+   npm run sync                 # into the profile copy DSH loads
+   git add -A && git commit -m "..."
+   git tag -a v<x.y.z> -m "..."
+   git push origin main && git push origin v<x.y.z>
+   ```
+
+   `npm run sync` defaults to
+   `%USERPROFILE%/.dsh/profiles/web/node_modules/dsh-wsl` — the folder the
+   profile's dependency key created, which need not match the npm name. Pass a
+   path to target another profile. Restart DSH afterwards: the plugin is imported
+   once at load.
+
+3. The tag runs the pipeline. The order is deliberate — the release asset goes
+   **first** because it is the market's critical path, then npm, so a failing npm
+   publish fails the run loudly without withholding the release.
+
+   The build step asks `npm pack --silent` for the tarball name (it follows
+   `package.json`, so it is `dsh-wsl-tool-<version>.tgz`) and copies it to
+   `dsh-wsl.tgz`, which is the fixed name the catalog's URL points at. Never
+   rename that copy: the market install breaks the moment the asset is not called
+   `dsh-wsl.tgz`, and `--latest` is what keeps `releases/latest` resolving to it.
+
+4. Verify each channel.
+
+   **CI** — a check annotation is readable anonymously, unlike the job log:
+
+   ```sh
+   curl -s "https://api.github.com/repos/XINY11451/dsh-wsl/actions/runs?per_page=5"
+   curl -s "https://api.github.com/repos/XINY11451/dsh-wsl/check-runs/<id>/annotations"
+   ```
+
+   A successful publish leaves `published <version> to npm`; a failure leaves
+   `npm publish failed: <the npm error lines>`, which is why the workflow turns
+   npm's stderr into `::error::` instead of only printing it.
+
+   **npm**:
+
+   ```sh
+   curl -s https://registry.npmjs.org/dsh-wsl-tool      # dist-tags.latest
+   npm view dsh-wsl-tool version --registry https://registry.npmjs.org
+   ```
+
+   Fetching `dist.tarball` and unpacking it is the honest check — it proves the
+   artifact, not just the metadata. Scripted requests to `npmjs.com`'s HTML hit a
+   Cloudflare challenge; the registry API is the source of truth.
+
+   **Market asset** (this is what users install, and it is independent of npm):
+
+   ```sh
+   curl -sL -o /tmp/a.tgz https://github.com/XINY11451/dsh-wsl/releases/latest/download/dsh-wsl.tgz
+   tar -xzOf /tmp/a.tgz package/package.json | grep '"version"'
+   ```
+
+   **Catalog**: the catalog's generated data is at
+   <https://awesome-dsh-plugin.com/plugins.json> — look up `dsh-wsl` and read
+   `npm`, `version`, `downloads`, `install`, `tarball`.
+
+## The catalog entry
+
+The listing lives at `data/plugins/XINY11451__dsh-wsl.yml` in
+`awesome-dsh-plugin/awesome-dsh-plugin`, one file per plugin. Only
+`description.en` is required; `description.zh` is optional. Edit it through a
+one-file PR (the web UI's pencil button forks and proposes the change).
+
+Two of its keys are hand-written and must stay:
+
+- `tarball:` — the fixed release URL above. It is what the market's `install`
+  command points at today.
+- `url` / `name` / `category` — `category: wsl`.
+
+Everything else about the entry is **generated** and must never be written by
+hand: `npm`, `version`, `downloads`, `screenshots`, and `install`. In particular
+`scripts/probe-npm.mjs` reads `package.json`'s `name` from the repository's
+`HEAD`, then accepts the package only when the registry document's
+`versions[latest].repository.url` contains `<owner>/<repo>`
+(case-insensitively — that check is what stops name squatting). So keep
+`repository` in `package.json` accurate, or the catalog stops discovering the npm
+package. "Not published" verdicts are re-probed daily, so a freshly published
+version can take a day to appear; when it does, `install` switches from the
+tarball URL to `dsh plugin --profile web add dsh-wsl-tool`.
+
+## Things that bite
+
+- **A tag event runs the workflow from the tag's commit.** To change the
+  pipeline you must commit *and cut a new tag*; re-running an old run reuses the
+  workflow it was created with, and moving a tag is not a fix.
+- **Job logs need authentication; annotations do not.** There is no `gh` and no
+  `GITHUB_TOKEN` on the maintainer machine, so anything that must be diagnosable
+  without a credential belongs in an annotation.
+- **An interactive `npm publish` asks for a one-time password** and cannot be
+  driven from an unattended run. CI authenticates with a granular token that may
+  bypass 2FA, stored as the `NPM_TOKEN` secret; with the secret absent the step
+  skips with a notice instead of failing. Now that the package exists, OIDC
+  trusted publishing is the better replacement.
+- **`publishConfig.registry` in `package.json` wins** over a developer's
+  `~/.npmrc` mirror, so a mirror configured for reads cannot intercept a publish.
+- **The profile's dependency key is not the package name** (`dsh-wsl` versus
+  `dsh-wsl-tool`). Do not "fix" that by hand: the profile is managed by pnpm, and
+  its `pnpm-lock.yaml`, `node_modules/.modules.yaml`, and
+  `node_modules/.package-map.json` all record the key. The relative patch entry
+  means the difference costs nothing.
+- **Short unscoped names ending in `-wsl` are a minefield.** `dsh-wsl` collides
+  with `is-wsl`; longer suffixed names such as `dsh-wsl-workspace` are published
+  by other authors and pass. Prefer npm's suggestion (a scope) or a clearly
+  suffixed name, and check the registry before tagging.

package/README.md

@@ -96,18 +96,33 @@ specifier you install under.
    or `dsh plugin add --profile <profile> file:<path-to-this-repo>` from a
    checkout (which names the dependency after this package).
 
-2. Add a `tool-wsl` row to an agent preset's `agent.cordis.yml`:
+2. Nothing else. The package's `cordis.patch.yml` inserts the `tool-wsl` row
+   itself when the bundle is loaded, process-wide, so the three tools are
+   available to every agent preset without further wiring.
 
-   ```yaml
-   - id: tool-wsl
-     name: 'dsh-wsl-tool'
-   ```
-
-   `name` is the installed package name — use your own dependency key if you
-   installed under a different one.
+   Do **not** also list `tool-wsl` in a preset: DSH registers tools by name, and
+   the second registration fails with
+   `tool "wsl" is already registered in this scope`. One row, from the bundle.
 
 3. Restart DSH.
 
+## Compatibility
+
+Verified against DSH **0.1.7-rc.2** (and 0.1.5-rc.2 before it): the tool schemas
+pass DSH's own `assertSupportedJsonSchema`, the subprocess seam is exercised
+against the real provider rather than a shim, and the background-job path is
+checked against the real job registry, including the session-id ownership fence
+that 0.1.7 tightened. `test/real-seam.mjs` is that check and it re-verifies a host
+in about a minute, so point it at any DSH installation after an upgrade:
+
+```sh
+DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+```
+
+A background job is owned by the calling session (`owner: exec.agent.id`), which
+is what lets the model read it back with `job_output`/`job_kill` and what keeps
+other sessions out; an execution with no agent starts the job unowned.
+
 ## `wsl` parameters
 
 | Param | Required | Type | Notes |
@@ -312,6 +327,9 @@ the folder name itself never matters.
 
 then restart DSH — the plugin is imported once at load.
 
+Releasing — the tag-triggered workflow, the npm name, and the catalog entry — is
+documented in [`PUBLISHING.md`](PUBLISHING.md).
+
 ## Listing
 
 The repository carries the `dsh-plugin` topic and is listed under the `wsl`

package/README.zh-CN.md

@@ -86,17 +86,29 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
    `dsh plugin add --profile <profile> file:<path-to-this-repo>` 从本地检出安装
    （依赖名会取本包自身的名字）。
 
-2. 在某个 agent preset 的 `agent.cordis.yml` 中加入 `tool-wsl` 行：
+2. 不必再做别的。本包的 `cordis.patch.yml` 会在组合包加载时**自己插入** `tool-wsl` 行
+   （进程级），因此三个工具对所有 agent preset 都可用，无需额外接线。
 
-   ```yaml
-   - id: tool-wsl
-     name: 'dsh-wsl-tool'
-   ```
-
-   `name` 即安装后的包名；若你用了别的依赖名，就填那个名字。
+   **不要**再在 preset 里列一遍 `tool-wsl`：DSH 按名字注册工具，第二次注册会直接失败
+   —— `tool "wsl" is already registered in this scope`。这一行只由组合包提供。
 
 3. 重启 DSH。
 
+## 兼容性
+
+已在 DSH **0.1.7-rc.2** 上验证（此前为 0.1.5-rc.2）：工具 schema 通过 DSH 自己的
+`assertSupportedJsonSchema`；subprocess 接缝是跑在**真实 provider** 上而非替身；后台任务
+路径跑在**真实 job 注册表**上，包含 0.1.7 收紧的「会话 id 属主围栏」。这套检查就是
+`test/real-seam.mjs`，约一分钟即可重验一个新宿主——升级后把它指向新的 DSH 安装即可：
+
+```sh
+DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
+```
+
+后台任务由**调用方会话**持有（`owner: exec.agent.id`），这既是模型能用
+`job_output`/`job_kill` 读回它的依据，也是其他会话读不到它的围栏；exec 里没有 agent 时
+任务则是无主的。
+
 ## `wsl` 参数
 
 | 参数 | 必填 | 类型 | 说明 |
@@ -299,6 +311,8 @@ npm run sync -- /path/to/profiles/<profile>/node_modules/<你的依赖名>
 
 然后重启 DSH——插件在加载时只导入一次。
 
+发版流程（tag 触发的流水线、npm 包名与目录条目）见 [`PUBLISHING.md`](PUBLISHING.md)。
+
 ## 收录
 
 本仓库带有 `dsh-plugin` topic，并已提交至 awesome-dsh-plugin 社区列表的 `wsl` 分类。

package/lib/tools/wsl.js

@@ -71,7 +71,15 @@ export function createWslTool({ ctx, config, runner }) {
         kind: 'wsl',
         label: jobLabel(command),
         outputLimitBytes: config.maxOutputBytes,
-        ...(exec?.agent === undefined ? {} : { owner: exec.agent }),
+        // `owner` is the owner's SESSION ID, not the Agent handle: the registry
+        // resolves it through the live-agent registry (`agents.get(sessionId)`)
+        // and fails with `session "…" has no live agent` for anything else. It
+        // is also the fence key — the model's `job_output`/`job_kill` reach this
+        // job by passing the same session id as their caller. Bound to
+        // `exec.agent.id` exactly as `dsh-tool-bash` and `dsh-tool-pwsh` do.
+        // An execution with no agent starts an unowned job, which is open to any
+        // caller but never listed for a session.
+        ...(exec?.agent === undefined ? {} : { owner: exec.agent.id }),
         // The spawn happens INSIDE run(): the contract says a throw leaves
         // nothing registered, so spawning first and registering second could
         // leak a process if registration failed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-tool",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Model-facing WSL tools for DeepSeek Harness: run Linux commands from Windows with background jobs, stdin, path translation, destructive-command guard and WSL capability diagnostics.",
   "type": "module",
   "main": "index.js",
@@ -29,6 +29,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.zh-CN.md",
+    "PUBLISHING.md",
     "screenshots.json",
     "assets",
     "LICENSE"