pnpm peer-dependency warnings on dsh plugin add: which are safe to ignore and how to fix the rest

[stephenlzc]

Symptom

Running dsh plugin --profile web add <plugin> makes pnpm print a long list of ✕ missing peer warnings (@deepseek-ai/cordis, @deepseek-ai/dsh-*, react-dom, etc.), plus an Ignored build scripts notice at the end. It looks like a broken install, but most of these warnings are by design — only a couple of items actually need fixing. Posting my findings for anyone who runs into the same output.

Finding 1: most missing-peer warnings are by design and safe to ignore

The profile directory (e.g. ~/.dsh/profiles/web) deliberately sets autoInstallPeers: false in its pnpm-workspace.yaml. These peers are provided by the dsh host one level up, in ~/.dsh/profiles/node_modules — verified versions there:

• @deepseek-ai/cordis 4.0.1 (satisfies ^4.0.1)
• react / react-dom 18.3.1 (satisfies ^18.2.0)
• dsh-llm / dsh-tools / dsh-agent / dsh-client-* etc., all at 0.1.0-rc.6

At runtime, plugins resolve them through Node's upward node_modules lookup and share the host's singletons. Do not install these packages into the profile just to silence the warnings — that creates duplicate cordis / dsh-tools instances, which is exactly the root cause of the tool-scheduling crashes in #1849 and #2731. pnpm only looks inside the profile workspace and can't see the host's packages one level up, so the warnings will always appear.

Finding 2: the only real conflict is @xterm/addon-web-links — fixable with an override

dsh-plugin-terminal@0.1.13 pins @xterm/addon-web-links to 0.11.0, which declares a peer on @xterm/xterm@^5.0.0, while the plugin itself bundles @xterm/xterm@^6.0.0 (hence the unmet peer warning). @xterm/addon-web-links@0.12.0 is the release built for xterm 6 and no longer declares that peer. Add to the profile's pnpm-workspace.yaml:

overrides:
  '@xterm/addon-web-links': '0.12.0'

Then run pnpm install in that directory — the conflict warning is gone.

Finding 3: authorize the ignored build scripts via onlyBuiltDependencies

The build scripts of node-pty, ssh2, cpu-features, and cloudflared are blocked by pnpm's default policy, but the terminal/ssh plugins need them. Also in pnpm-workspace.yaml:

onlyBuiltDependencies:
  - cloudflared
  - cpu-features
  - node-pty
  - ssh2

After reinstalling, ssh2's crypto binding compiles successfully, and node-pty (via prebuilds) was verified working with a real spawned process.

Remaining issue (not fixable from the profile side)

@deepseek-ai/dsh-settings@0.1.0-rc.7 (a dependency of dsh-sight@0.3.1) expects dsh-brand / dsh-invariants@^0.1.0-rc.7, while the host currently ships rc.6, which doesn't satisfy that range. Runtime injection by the host generally still works, but if dsh-sight misbehaves, the likely cause is the host lagging behind — we can only wait for a host upgrade.

Two suggestions

1. The docs (or the output of dsh plugin add) could note that missing-peer warnings for host-provided packages are normal, or offer a way to suppress them, to avoid confusion.
2. Be aware that dsh plugin add/remove may rewrite pnpm-workspace.yaml and drop the manually added overrides / onlyBuiltDependencies sections. It would be more robust if the CLI preserved unknown fields or offered a profile-level pnpm config entry point.

Environment: pnpm 10.33.0, Node 22, macOS arm64.

[bevinkatti]

The distinction between “missing from the profile workspace” and “actually unavailable at runtime” is probably the key here.

Since the host intentionally provides these peers, I wonder if the cleaner long-term fix would be to make that host/profile dependency boundary explicit rather than relying on pnpm warnings being understood as benign. pnpm already has mechanisms like peerDependencyRules.ignoreMissing / allowedVersions, so the CLI could potentially generate or maintain targeted rules for host-provided packages instead of users having to manually add overrides.

For @xterm/addon-web-links, though, I agree that an override is more of a workaround — ideally dsh-plugin-terminal should declare the xterm-6-compatible addon version itself so the published dependency graph is accurate.

The rc.6 vs rc.7 case also seems like something dsh plugin add could detect explicitly and report as a host/plugin compatibility mismatch, rather than leaving it mixed into the generic pnpm peer warnings.

[zoahdev]

你的 Finding 1-3 我对照当前 main HEAD 99f6f02 都确认了（profile 目录 autoInstallPeers: false + host 上层提供 peer + 重复安装正是 #1849/#2731 根因）。对"建议 2"补一个代码级核验结果：dsh 侧其实不会重写 pnpm-workspace.yaml——如果手写字段真的丢了，大概率不是 dsh plugin add/remove 干的。

当前 main 上的两条路径：

1. apps/cli/src/plugin.ts 是"薄 pnpm 转发器"：dsh plugin --profile <name> add/remove ... = initProfile() + spawnSync('pnpm', [...args]) + reconcilePlugins()。reconcilePlugins 只读写 profile 的 package.json（dsh.profile.bundles 列表），不碰 pnpm-workspace.yaml。
2. packages/boot/app-boot/src/profile.ts 的 initProfile()：pnpm-workspace.yaml 是仅缺失时写入（if (!existsSync(workspacePath)) writeFileSync(...)），已有文件绝不覆盖；注释也写明 "Existing files are never touched"。

所以手动加的 overrides / onlyBuiltDependencies 理论上在 dsh 侧是安全的。若实测中字段消失，建议按这个顺序排查：

• 你编辑的 yaml 与 pnpm 实际执行目录是不是同一个 profile（dsh plugin --profile web 的 web 与 resolveProfileDir 解析路径是否一致；macOS 上 ~/.dsh/profiles/<name> 可能被环境变量/参数覆盖）；
• 是否 pnpm 自身的行为（pnpm v10 起 pnpm config set 会写 pnpm-workspace.yaml，但普通 pnpm add/remove 不会改已有字段）；
• 是否误改了模板/别的 profile。

如果确实能稳定复现"字段消失"，值得单独开一帖带最小复现（哪个命令、哪个文件、前后 diff）——因为按当前源码路径，这个问题看起来不在 dsh 侧，别让维护者追一个不存在的写入点。

[bevinkatti]

Good catch on the pnpm-workspace.yaml point. If initProfile() only creates the file when it doesn't exist and reconcilePlugins() only updates package.json, then my concern about dsh plugin add/remove dropping unknown workspace fields doesn't apply to the current implementation.

That makes the reproducible case of those fields disappearing much more interesting — I'd agree that it should first be narrowed down to the exact profile path and pnpm behavior before attributing it to dsh.

好的，我是通过翻译工具理解你的回复的，如果有表达不准确的地方请见谅。

[denial123789]

The key classification is “missing from the profile workspace” versus “unavailable or incompatible at runtime.” In rc.7, the profile deliberately uses nodeLinker: hoisted plus autoInstallPeers: false. On launch, Harness heals $DSH_HOME/profiles/node_modules from the running installation’s dependency and peer-dependency closure, and Node’s parent walk lets out-of-tree plugins reach that fallback. This preserves one shared Cordis/DSH service identity.

I would apply four checks to every warning independently:

1. resolve the peer from the exact profile anchor and record whether it comes from profiles/<name>/node_modules, the maintained profiles/node_modules fallback, or nowhere;
2. compare the actual version with the plugin’s requested range—a found Host package can still be incompatible;
3. do not add Host-owned Cordis, React, or DSH service packages merely to silence pnpm, because a nearer duplicate can split registration and injection identity;
4. keep Ignored build scripts separate from peer resolution.

For the build-policy detail, follow the installed pnpm/DSH diagnostic rather than copying a generic list: rc.7’s Git-plugin path explicitly tells the user to add the exact identity pnpm printed under allowBuilds in that profile’s pnpm-workspace.yaml, review it, and rerun. An ignored native build needs a real PTY/SSH/module capability test afterward; warning disappearance is not sufficient.

Also confirmed from source: initProfile() writes the workspace YAML only when absent, while dsh plugin forwards to pnpm and reconciles only package.json bundle state. If fields disappear, capture the exact path and before/after diff before attributing the write to DSH.

I turned this into a source-linked warning router and 12-gate install checklist here: https://sandbaseai.github.io/deepseek-harness-handbook/plugin-peer-warnings.html