dsh-any-agent 0.1.1 → 0.1.2

package/README.md

@@ -134,13 +134,22 @@ dsh-any-agent-setup --yes --permission read-only
 dsh-any-agent-setup --remove --yes               # take it back out
 ```
 
-**From a local checkout**
+**What `setup` will and will not touch**
+
+It is additive. Verified against a real machine holding existing MCP servers (Cursor with four, Codex with two, Claude Code with five, Zed with 33 settings keys): every pre-existing entry survived unchanged, nothing was reformatted, and the only diff was one new key per client. Each of those four clients then answered an `initialize` handshake from the command written into its config.
+
+```
+Cursor       4 -> 5 entries   existing entries byte-identical
+Codex        2 -> 3 sections  node_repl and rea bodies unchanged
+Claude Code  5 -> 6 servers   all four originals still listed
+Zed          33 -> 33 keys    only context_servers gained a child
+```
 
-The `dsh-any-agent` executable is on your `PATH` after a global install, so every client below can call it by name. Otherwise point `command` at `node` and `args` at `<checkout>/server/bin/dsh-any-agent.mjs`.
+The one thing it does modify in place is the JSON formatting of `mcp.json` and `settings.json` (it re-serialises with 2-space indent). Values are preserved; whitespace is not guaranteed to be. A `.bak-dsh-<timestamp>` copy sits beside each file it touched.
 
 **From a local checkout**
 
-Clone or unzip anywhere, then point `command` at `node` and `args` at `<checkout>/server/bin/dsh-any-agent.mjs` (shown below).
+Clone or unzip anywhere, then point `command` at `node` and `args` at `<checkout>/bin/dsh-any-agent.mjs` (shown below).
 
 ---
 
@@ -463,6 +472,52 @@ When you first start this server it creates a DSH profile under `~/.dsh/profiles
 
 So the **product** is `dsh-any-agent`; the **persisted identifiers** keep the old name on purpose. This is a deliberate compatibility decision, not an oversight. If you are setting this up from scratch and want a different profile name, set `DSH_MCP_PROFILE` — the server will use whatever you give it.
 
+## 📦 Releasing
+
+Checklist for cutting a version. The ordering matters; two of these steps exist because skipping them shipped a broken release.
+
+```bash
+# 1. Bump the version. SERVER_VERSION reads package.json, so nothing else
+#    needs editing -- that duplication used to drift.
+npm version patch --no-git-tag-version
+#    then update CHANGELOG.md by hand: move [Unreleased] into a new section
+
+# 2. Prove it offline (same suites CI runs, no model, no DSH)
+node test/guards.mjs && node test/prune.mjs
+node test/approval-details.mjs && node test/setup.mjs
+node test/package-check.mjs
+
+# 3. Confirm the tarball itself: packs, installs, starts
+npm pack --dry-run
+#    then, in a scratch dir: npm install <tgz> && node_modules/.bin/dsh-any-agent --version
+
+# 4. Tag and push (CI must be green before publishing)
+git add -A && git commit -m "chore: release x.y.z"
+git tag vx.y.z && git push origin main --tags
+
+# 5. Publish
+npm publish
+```
+
+**Do not trust a 404 after publishing.** npm processes new versions asynchronously (`PUT 202`, not `200`). Querying the registry a few seconds later still returns 404 and looks like failure. Confirm success from the local npm debug log first:
+
+```
+grep 'http fetch PUT 202' "$LOCALAPPDATA/npm-cache/_logs/<latest>.log"
+```
+
+then wait a minute or two and check `npm view dsh-any-agent dist-tags`.
+
+**If a published version is broken, deprecate it — do not leave it installable.** `0.1.0` declared `node >=20` while actually requiring 22.15; anyone pinning it got a server that could not start:
+
+```bash
+npm deprecate "dsh-any-agent@0.1.0" \
+  "Node 20 cannot start this version. Upgrade to 0.1.1+ (requires Node >=22.15)."
+```
+
+`deprecate` prints a warning on install without unpublishing, which is the right tool: the tarball stays for anyone already depending on it. Note this needs an interactive OTP — granular access tokens with bypass-2FA are not allowed to perform it (npm restricted that in July 2026), so run it yourself rather than from CI.
+
+**Badges lag.** shields.io caches for five minutes (`max-age=300`), so a fresh publish shows the old version, the old `node` floor, and sometimes `license: package not found` — that last string is shields' generic failure text for a license it could not read, not a missing license. Wait and hard-refresh before assuming the metadata is wrong.
+
 ## 💬 Support
 
 - **Bug reports, feature requests, setup questions** — [open an issue](https://github.com/xmtlzzz/dsh-any-agent/issues); all of it is welcome there

package/README.zh.md

@@ -149,13 +149,22 @@ dsh-any-agent-setup --yes --permission read-only
 dsh-any-agent-setup --remove --yes               # 全部移除
 ```
 
-**从本地目录安装**
+**setup 会动什么、不会动什么**
+
+它只做新增。在真正装着别的 MCP 服务器的机器上验证过（Cursor 4 个、Codex 2 个段、Claude Code 5 个、Zed 33 个配置键）：所有既有条目原样保留，没有被重新格式化，唯一的差异是每个客户端多了一个键。之后这四个客户端都用配置里写入的命令真实跑通了一次 `initialize` 握手。
+
+```
+Cursor       4 -> 5 个条目   既有条目逐字节相同
+Codex        2 -> 3 个段     node_repl 与 rea 内容不变
+Claude Code  5 -> 6 个服务   原有四个都还在列表里
+Zed          33 -> 33 个键   只有 context_servers 多了个子项
+```
 
-全局安装后 `dsh-any-agent` 命令就在 `PATH` 上，下面每种客户端都可以直接按名字调用。否则把 `command` 指向 `node`、`args` 指向 `<解压目录>/server/bin/dsh-any-agent.mjs`。
+唯一会就地改动的是 `mcp.json` 和 `settings.json` 的**排版**（会按 2 空格缩进重新序列化）。值不变，但空白格式不保证原样。每个被改的文件旁边都留了 `.bak-dsh-<时间戳>` 备份。
 
 **从本地目录安装**
 
-解压到任意位置，把 `command` 指向 `node`、`args` 指向 `<解压目录>/server/bin/dsh-any-agent.mjs`（见下）。
+解压到任意位置，把 `command` 指向 `node`、`args` 指向 `<解压目录>/bin/dsh-any-agent.mjs`（见下）。
 
 ---
 
@@ -480,6 +489,52 @@ DSH 的会话有**跨进程写锁**：**持有者活着就永不过期，也没
 
 所以**产品名**是 `dsh-any-agent`，**持久标识**故意保留旧名。这是刻意的兼容决定，不是漏改。如果你是全新部署、想要别的 profile 名，直接设 `DSH_MCP_PROFILE` —— 服务会照你给的名字用。
 
+## 📦 发布流程
+
+发版清单。顺序有讲究 —— 其中两步是因为跳过它们发过一次坏版本才补上的。
+
+```bash
+# 1. 升版本号。SERVER_VERSION 读的是 package.json，别处不用改
+#    （以前这里有两份数字，漂移过）
+npm version patch --no-git-tag-version
+#    然后手工改 CHANGELOG.md：把 [Unreleased] 变成新版本一节
+
+# 2. 本地跑一遍离线套件（和 CI 相同，不花 token、不需要 DSH）
+node test/guards.mjs && node test/prune.mjs
+node test/approval-details.mjs && node test/setup.mjs
+node test/package-check.mjs
+
+# 3. 确认 tarball 本身：打得出来、装得上、起得来
+npm pack --dry-run
+#    再在临时目录里：npm install <tgz> && node_modules/.bin/dsh-any-agent --version
+
+# 4. 打 tag 并推送（CI 绿了再发）
+git add -A && git commit -m "chore: release x.y.z"
+git tag vx.y.z && git push origin main --tags
+
+# 5. 发布
+npm publish
+```
+
+**发布后看到 404，不要当成失败。** npm 对新版本是异步入库（返回 `PUT 202` 而不是 `200`），几秒后去查 registry 仍然是 404，看起来像没发成功。先确认本地 npm 日志里有这一行：
+
+```
+grep 'http fetch PUT 202' "$LOCALAPPDATA/npm-cache/_logs/<最新的>.log"
+```
+
+然后等一两分钟再查 `npm view dsh-any-agent dist-tags`。
+
+**已发布的版本如果有问题，用 deprecate 而不是放着不管。** `0.1.0` 声明 `node >=20` 但实际需要 22.15，锁版本装它的人会得到一个起不来的服务：
+
+```bash
+npm deprecate "dsh-any-agent@0.1.0" \
+  "Node 20 cannot start this version. Upgrade to 0.1.1+ (requires Node >=22.15)."
+```
+
+`deprecate` 只在安装时打印警告、不删包 —— 这是对的工具：已经依赖它的人仍然能装到那个 tarball。注意这条**需要交互式 OTP**：带 bypass-2FA 的 granular token 不允许执行（npm 2026 年 7 月收紧的），所以要你自己跑，别放在 CI 里。
+
+**徽章有延迟。** shields.io 缓存五分钟（`max-age=300`），所以刚发完会显示旧版本号、旧的 `node` 下限，有时还会显示 `license: package not found` —— 那个字符串是 shields 读不到 license 时的通用失败文案，不是真的没有 license。等一会并强制刷新，再判断元数据是不是错的。
+
 ## 💬 支持
 
 - **Bug、功能请求、部署提问** —— [提 issue](https://github.com/xmtlzzz/dsh-any-agent/issues)，都往这里放

package/bin/setup.mjs

@@ -159,7 +159,13 @@ const CLIENTS = [
       const { command, args } = launch();
       const envs = [];
       for (const [k, v] of Object.entries(desiredEnv())) envs.push('-e', k + '=' + v);
-      const r = run(['mcp', 'add', NAME, '-s', 'user', ...envs, '--', command, ...args]);
+      // On Windows the child is spawned through cmd (shell: true), so an
+      // argument containing spaces must be quoted or it is split: a command of
+      // "C:\Program Files\nodejs\node.exe" arrives as "C:\Program" plus a
+      // stray "Files\nodejs\node.exe" argument, and Claude Code then fails
+      // to connect with CONNECTION_CLOSED. Quote anything with a space.
+      const quote = (s) => (IS_WIN && /\s/.test(s) ? '"' + s + '"' : s);
+      const r = run(['mcp', 'add', NAME, '-s', 'user', ...envs, '--', quote(command), ...args.map(quote)]);
       if (r.status !== 0) {
         return { error: tried(r).trim().split('\n')[0] || 'claude exited ' + r.status };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drive DeepSeek Harness (DSH) as a long-lived coding agent from any MCP client — Claude Code, Codex, Cursor, or your own. Resume-aware, interruptible, approval-capable.",
   "type": "module",
   "license": "MIT",