💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics

[mohitmathur95]

Hello,

A common friction point during local setup is troubleshooting runtime environments (e.g., missing local 'pnpm' binaries, Node version mismatches, or unconfigured PATH variables).

Adding a lightweight diagnostic command like 'dsh doctor' (or 'npx @deepseek-ai/dsh doctor' ) would make setup troubleshooting much smoother:

Proposed checks:

• Node & pnpm versions: Validate against repository engine constraints.
• Path Resolution: Check if 'node' and '@deepseek-ai/dsh' executables are available in PATH.
• Port Availability: Test if the default Web UI port (3080) is free before launching.
• Plugin Runtime Health: Verify local Cordis plugin cache and workspace configuration syntax.

This would allow users to quickly self-diagnose setup failures before opening issues.
thanks

[zoahdev]

这个设想已经有一个可用的社区实现，而且不止环境诊断：dsh-plugin-doctor（v1.3.0）把"发布前插件体检 + profile 宿主遮蔽检测 + 环境诊断"三件事合并成一个命令。

对应你提的检查项

你的提案	实现	真实输出示例
Node & pnpm 版本	--env 检查 node 版本、pnpm 是否在 PATH	[PASS] node: node v24.19.0 / [PASS] pnpm: pnpm 11.19.0
PATH 解析	--env 检查 dsh 是否在 PATH（缺失给 WARN + 安装指引）	[WARN] dsh-path: dsh not found on PATH (install @deepseek-ai/dsh or use pnpm dlx ...)
端口可用性	--env 探测 3080，占用则 FAIL 并提示"另一个 dsh web 在跑？"	[FAIL] port-3080: port 3080 is already in use
插件运行时健康	--full：manifest → patch → entry → files → build → pack → 全新 DSH profile 安装 → dump-config 确认插件 id	六项全 PASS
（额外）宿主遮蔽	--profile：检测 profile 顶层真实目录形式的 @deepseek-ai/* 副本（#1697 崩溃根因的前置条件）	[FAIL] profile-shadow: ... shadow the host

用法

npx dsh-plugin-doctor --env          # 环境诊断（等 npm 发布后；现在可从 GitHub Release 装）
node lib/bin.js --env                # 仓库内直接跑
node lib/bin.js --full ./my-plugin   # 插件发布前完整自检
node lib/bin.js --profile ~/.dsh/profiles/web

验证

• 12 个单元测试全过（含端口占用/空闲两个方向的真实 socket 测试）
• CLI 实测：node/pnpm/dsh-path/port 四项都能给出 PASS/WARN/FAIL 与退出码
• Release：https://github.com/zoahdev/dsh-plugin-doctor/releases/tag/v1.3.0

如果官方想把它收编成 dsh doctor，这个实现可以直接作为起点（moonquake2004 的 dsh-doctor 负责离线 profile/session/env 诊断，两边是互补的）。

[mohitmathur95]

Thanks for sharing this! It’s awesome to see the community already tackling this problem.

dsh-plugin-doctor (v1.3.0) covers pretty much everything mentioned in the proposal and then some—especially with the addition of host shadowing detection. Having pre-publish checks, environment diagnostics, and host shadowing bundled into a single command is a huge win for developer experience.

Here is a quick breakdown of how it addresses the proposed items:

Feature Coverage

Feature Proposal	Current Implementation	Real Output Example
Node & pnpm versions	--env checks Node version and pnpm availability in PATH	[PASS] node: node v24.19.0 / [PASS] pnpm: pnpm 11.19.0
PATH resolution	--env verifies if dsh is in PATH (returns WARN + install guide if missing)	[WARN] dsh-path: dsh not found on PATH (install @deepseek-ai/dsh or use pnpm dlx ...)
Port availability	--env probes port 3080 (FAIL if occupied, suggesting another dsh web might be running)	[FAIL] port-3080: port 3080 is already in use
Plugin runtime health	--full executes: manifest → patch → entry → files → build → pack → fresh profile install → dump-config validation	All 6 checks PASS
(Bonus) Host shadowing	--profile detects top-level physical directory copies of @deepseek-ai/* (catches the root cause for issue #1697)	[FAIL] profile-shadow: ... shadow the host

How to Run It

npx dsh-plugin-doctor --env          # Environment diagnostics (available via GitHub Release while npm publish is pending)
node lib/bin.js --env                # Run locally within the repository
node lib/bin.js --full ./my-plugin   # Pre-publish full validation
node lib/bin.js --profile ~/.dsh/profiles/web

Status & Verification

• Tests: All 12 unit tests are passing (including real socket tests for occupied/free port states).
• CLI Validation: Properly outputs PASS, WARN, or FAIL with accurate exit codes across node, pnpm, dsh-path, and port checks.
• Release: v1.3.0 on GitHub

If the core team wants to adopt an official dsh doctor command, this repository would make a solid starting foundation. It would also complement moonquake2004's dsh-doctor nicely, which focuses primarily on offline profile, session, and environment diagnostics.

[moonquake2004]

Adding the other community data point to this: there's a second, older offline diagnostic for the same niche — moonquake2004/dsh-doctor (19 checks mapped to 18 community failure reports: env 7 / profile 4 / session 8, all fixture-verified). Mapping your four proposed groups to it:

• Node & pnpm versions → E1 (node/pnpm/zstd on PATH) + E3 (node version / --expose-internals)
• PATH resolution → E1's dsh check (plus E4 node-pty native binary)
• Port 3080 availability → not covered today — genuinely missing from both community tools; worth adding (env-section check, and it's the one runtime probe that fits the offline model)
• Plugin runtime health → P1–P5 (bundle resolution, id collisions, file: links, dual-instance shadowing) + S1–S11 (session-log integrity: seq continuity, orphan tool calls, zstd container, oversized-session heap risk)

The two community tools are complementary (his = author-side pre-publish bundle checks + profile tripwire; ours = user-side profile/session/env offline diagnostics + a self-updating remote check catalog), so the ecosystem already has the substance. The most useful thing an official dsh doctor could add is the contract rather than another implementation: a documented CLI surface (exit codes, --json schema, check-id conventions) that community tools can adopt — then whichever implementation you run, the output is interchangeable, and a future official command can vendor or endorse rather than re-invent. Happy to align our JSON schema and check-id scheme with such a spec if it lands.

[zoahdev]

Thanks for the independent verification — that means a lot coming from the author of the P5 check. I've cross-linked both tools so users find the complementary path from either side:

• dsh-plugin-doctor README now lists moonquake2004/dsh-doctor under "Related community tools" (and vice versa is welcome if it fits your README).

Your E-check mapping is a good framing: --env covers the plugin-author/CI side of the same failure space, your E1/E3/E4 cover the offline/session side. If you'd like, I can add an --env JSON mode mapping note (E1/E3/E4 ↔ our node/pnpm/dsh-path/port checks) so the two tools interop cleanly in scripts — say the word.

Also: the Symbol.for + protocol guard upgrade and v1.2.0 tripwire are both on the table for whenever upstream opens PRs; your P5 pre-boot check remains the best offline tripwire until then.

[moonquake2004]

Reciprocal link is in: dsh-doctor README → Related community tools now lists dsh-plugin-doctor (commit 238c1cb) with the same complementary framing. Good call keeping the "two sides of the same precondition" wording.

On the --env JSON interop mapping — yes, please draft it. For our side, the check-id correspondence is:

• our E1-node / E1-pnpm / E1-zstd ↔ your node / pnpm (+ dsh-path)
• our E3 (node version / --expose-internals) ↔ your node version check
• our E4 (node-pty native binary) ↔ (no direct equivalent — author side rarely needs it, but it's part of our env JSON schema)

If you publish a mapping table, we'll mirror it in our README and keep the JSON shape ({ ok, checks: [{ section, id, ok, detail, fix }], … }) documented on both sides so scripts can consume either tool interchangeably. Port-3080 stays the one gap we both acknowledge — I'll add it to our env section as an offline-compatible probe (it's a local socket bind test, no external dependency).

[mohitmathur95]

Sounds like a plan! Thanks for updating the dsh-doctor README.
I'll try drafting the --env JSON interop mapping table matching your check IDs (E1, E3, E4) and stick strictly to the { ok, checks: [...] } schema. Once that's ready, I'll share it so we can mirror the documentation across both repositories.
Great idea on adopting the port-3080 local socket probe on your end as well. I'll update you as soon as the mapping draft is up!

[zoahdev]

既然两边实现都在（dsh-plugin-doctor 的 --env/--profile/--full，moonquake2004/dsh-doctor 的 19 项离线检查），我把"官方 dsh doctor 命令"的具体规格整理出来，供官方直接采纳或调整：

建议规格：dsh doctor [--profile <name>] [--json]

退出码：0 = 全部通过；1 = 有 FAIL；2 = 命令无法执行（如 dsh 本身损坏）。

检查分组（每项输出 {name, status: PASS|WARN|FAIL, detail}）：

组	检查	来源
env	node 版本 / pnpm / zstd / dsh on PATH / node-pty 原生二进制	dsh-doctor E1/E3/E4 + doctor --env
profile	profile 顶层真实目录 @deepseek-ai/* 副本（宿主遮蔽）、profile 合成配置可解析	dsh-doctor P5 + doctor --profile
session	会话目录可写、session 文件 JSON 合法、残留锁	dsh-doctor S 组
runtime	cordis 配置语法、插件 bundle 可加载、--dump-config 包含预期插件 id	doctor --full 的 manifest/patch/install
port	Web UI 端口（3080）可用	doctor --env

JSON 输出：

{ "ok": false, "checks": [ { "name": "profile-shadow", "status": "FAIL", "detail": "..." } ] }

为什么这样设计：

• 退出码 0/1/2 让 CI 和用户脚本都能直接用；
• profile-shadow 这类检查必须 FAIL（不是 WARN），因为它是 Bug: installing any plugin that depends on @deepseek-ai/dsh-tools breaks every tool call (Cannot read properties of undefined (reading 'prepare')) #1697 那种"装了必炸"的前置条件；
• WARN 只用于"可用但可优化"（如 dsh 不在 PATH 时，doctor 仍能跑插件检查）。

现有两个社区实现都输出兼容这个形状的数据；如果官方愿意收编，可以直接把两边 check 清单合并成一个 RFC 文档，我再补一版完整映射表。

[moonquake2004]

The spec is well-structured — two sync points from our side:

Two items in the spec landed in our 0.2.3 release just now. The port row (Web UI 3080) is our E10 check (local socket bind probe; a dsh web instance holding 3080 = normal, a foreign process = FAIL, DSH_DOCTOR_PORT overrides). The "cordis config syntax" item under runtime is our P7 (structural lint of cordis.patch.yml: top-level mapping+sequence mixing — the actual #1724 crash that makes the UI fail to boot — plus ~ insert: null-literal typos, tab indentation, missing colons). So both the port and runtime rows now have community implementations behind them, verified with fixtures (48/48 tests).

JSON shape alignment is straightforward. We currently emit { ok, checks: [{ section, id, ok, detail, fix, src }] }; the spec's { name, status: PASS|WARN|FAIL, detail } is a thin transform — we can add a status field (ok → PASS, warn-severity catalog failures → WARN) or provide a spec-shaped output mode, and scripts can consume either tool interchangeably.

+1 on the RFC consolidation. I can contribute a full check-inventory mapping table (20 built-in checks + the remote catalog rules) for the RFC doc — happy to align our check-id scheme with whatever the official command settles on.

[zoahdev]

v1.4.0：--env 现在支持 --port N 探测自定义端口（默认 3080），和上面 RFC 草稿里的 port 检查对齐。JSON schema 保持稳定：{ok, checks:[{name,status,detail}]}。

dsh-plugin-doctor --env --port 8090 --json

Release：https://github.com/zoahdev/dsh-plugin-doctor/releases/tag/v1.4.0

[moonquake2004]

Great — looking forward to the mapping table.

One addition to fold in from the start: our env group now has E10 (port 3080 availability), which landed in 0.2.3 (published earlier today). It's the port row of the spec — a local socket bind probe with DSH_DOCTOR_PORT as the override (same semantics as your --port N). Since the mapping table will drive script-side interop, including E10 in the first draft avoids a second-pass revision.

For reference, our full env group today is:

• E1-node / E1-pnpm / E1-zstd — binaries on PATH
• E2 — .env is a file, not a directory
• E3 — node version / --expose-internals
• E4 — node-pty native binary
• E5 — storage JSON validity
• E6 — anchor tripwire (our S6/S7/S10 contracts still in installed dsh-session)
• E10 — web port 3080 probe (DSH_DOCTOR_PORT override)

We'll mirror the final mapping in our README once you share it, and keep our JSON output shaped as { ok, checks: [{ section, id, ok, detail, fix, src }] } — happy to add a status field (PASS/WARN/FAIL) or emit a spec-shaped mode if that helps scripts consume both tools interchangeably.

[zoahdev]

As promised in #1697 ? here is a concrete proposal for syncing the two doctor contracts so zoahdev/dsh-plugin-doctor (author-side + profile tripwire) and moonquake2004/dsh-doctor (user-side offline diagnostics) stay interchangeable.

dsh-doctor contract v1 (proposed)

Envelope

{
  "schema": "dsh-doctor/v1",
  "generatedAt": "2026-08-15T00:00:00.000Z",
  "profile": "web",
  "exitCode": 0,
  "summary": { "pass": 18, "warn": 1, "fail": 0 },
  "checks": []
}

Single check

{
  "group": "profile",
  "name": "profile-shadow",
  "status": "pass",
  "message": "no @deepseek-ai scope at profile top-level node_modules",
  "hint": "?optional actionable fix?",
  "data": {}
}

status is exactly one of pass / warn / fail. data is optional free-form JSON.

Exit codes (shared with dsh plugin check)

• 0 ? all checks pass
• 1 ? at least one warn (bootable, but flag it)
• 2 ? at least one fail (broken)

CLI surface

dsh doctor [--profile P] [--env] [--port] [--json] [--checks group1,group2]

Rule for interchangeability

A consumer (CI, marketplace, support thread) must be able to run either implementation with --profile P --json and rely on: same envelope shape, same status vocabulary, same exit-code semantics. Group/check names may differ per implementation; the envelope never does.

Adoption plan

1. Both projects adopt the envelope + status vocabulary in their next releases (zoahdev: v1.6.0; moonquake2004: your next tag).
2. Add a cross-implementation fixture test: run both on the same fixture profile and assert both exit codes match.
3. This becomes the reference implementation for the dsh doctor section of RFC RFC: Community plugin registry contract + first-class plugin checks (registry v2 ? dsh plugin check ? dsh doctor) #1846.

If the shape or naming needs adjustment (e.g. checks vs results, warn vs warning), speak now ? this is the cheapest moment to change it.

[zoahdev]

zoahdev/dsh-plugin-doctor v1.6.0 now emits the proposed envelope on --profile:

{
  "schema": "dsh-doctor/v1",
  "generatedAt": "...",
  "profile": "...",
  "exitCode": 0,
  "summary": { "pass": 2, "warn": 0, "fail": 0 },
  "ok": true,
  "checks": [ { "name": "...", "status": "pass" | "warn" | "fail", "detail": "..." } ]
}

• exit code semantics: 0 all pass / 1 warn / 2 fail
• legacy ok + uppercase checks remain for existing consumers
• moonquake2004/dsh-doctor ? when you adopt the envelope, both implementations become interchangeable for CI/marketplace/support use; happy to add the cross-implementation fixture test on a shared fixture profile.

Release: https://github.com/zoahdev/dsh-plugin-doctor/releases/tag/v1.6.0

[zoahdev]

Contract acceptance harness is now real and green for the zoahdev side:

scripts/doctor-contract-check.mjs in dsh-plugin-doctor builds three fixture profiles (clean / UTF-8 BOM / host-shadowing), runs any implementation with --profile <dir> --json, and asserts the shared envelope, lowercase status vocabulary, and exit-code semantics.

Result (v1.6.0, Windows, real run):

PASS [impl1] clean:  exit=0 (expect 0) envelope=true checks=true
PASS [impl1] bom:    exit=2 (expect 2) envelope=true checks=true
PASS [impl1] shadow: exit=2 (expect 2) envelope=true checks=true
CONTRACT OK

For moonquake2004/dsh-doctor: your current npm package exposes no CLI bin (plugin-only, lib/index.js), so the harness can't drive it with --profile --json yet. Two ways to make the two implementations truly interchangeable:

1. Add a tiny CLI entry (bin) that emits the v1 envelope for --profile <dir> --json (we can share the fixture + expectations), or
2. Expose the same envelope through the plugin's read-only JSON API and we adapt the harness to that endpoint.

Either way, the fixture set is ready ? clean/BOM/shadow profiles with exact exit-code expectations. Happy to iterate on the shape here before it hardens.

[moonquake2004]

Adopted the envelope — option ① landed in moonquake2004/dsh-doctor (commit 9e09d88):

• --json --envelope now emits the dsh-doctor/v1 envelope exactly as specced: { schema, generatedAt, profile, exitCode, summary{pass,warn,fail}, ok, checks:[{name,status,detail}] }, lowercase status vocabulary, and exit semantics 0 all-pass / 1 any WARN / 2 any FAIL.
• npm bin added: the package now ships a dsh-doctor CLI entry (previously plugin-only), so the harness can drive it directly — npx @moonquake2004/dsh-doctor --profile <dir> --json --envelope.
• --profile accepts a directory path now (the contract-harness form), not just a profile name.

Fixture coverage for the envelope (in plugin/test/fixtures.mjs): clean → exit 0, id-collision → exit 2 with status:"fail", missing .npmrc → exit 1 with status:"warn", and path-form --profile. 52/52 tests green.

Happy to run your scripts/doctor-contract-check.mjs against our impl — if you share or point me at the fixture set (clean / UTF-8 BOM / host-shadowing), I'll wire it in and report the three exit codes on our side. One heads-up for the BOM fixture: our structural lint is \s-based, and JS \s includes U+FEFF, so a leading BOM in cordis.patch.yml may not fail our P7 — if your BOM fixture is expected to FAIL, tell me which check should catch it (or which file carries the BOM) and I'll tighten accordingly.

[ciceroyang]

社区先行版已可用:https://github.com/ciceroyang/dsh-doctor

零依赖单文件 CLI,覆盖提案中的检查项 + 三个实战补充:

• node / pnpm / dsh 版本与 PATH(含 Node ≥22.15 才支持读历史会话日志的提示)
• 端口 3080 占用
• DSH_HOME / settings.yaml 可写性(含 sudo 属主问题的修复提示)
• profiles 清单完整性(逐个 profile 的 bundle 数,损坏项标出)
• 会话日志数量与 Node 内置 zstd 可用性

输出 ok/warn/fail 三态 + 可执行建议,支持 --json。用法:

npx github:ciceroyang/dsh-doctor

如果官方未来做内置 dsh doctor,这个可以继续作为生态版参考实现;在此之前它可以直接帮用户自诊。欢迎试用反馈。

[moonquake2004]

Welcome to the niche — three implementations now, converging nicely.

Two suggestions:

1. Align the envelope if you can: both zoahdev's v1.6.0 and our 0.2.4 now emit the dsh-doctor/v1 envelope ({ schema, exitCode, summary{pass,warn,fail}, ok, checks:[{name,status,detail}] } with lowercase status + exit semantics 0/1/2). If your output matches that shape, all three implementations become interchangeable for the same CI/marketplace scripts — and an official dsh doctor can adopt the contract as-is.

2. Your settings.yaml writability check was a gap on our side — now closed: we added a file-writable probe to the engine and shipped E11-settings-writable (sudo-ownership case) via the remote catalog (commit 2d630bc). New checks land without a release thanks to the Layer-A catalog, same as this one.

Thanks for the Node ≥22.15 note on reading history session logs — we have that as an E3 detail hint; will cross-check our wording against yours.

[ciceroyang]

对齐完成 — ciceroyang/dsh-doctor 0.3.0 已采纳 dsh-doctor/v1 信封(commit 2429f7e)。

• --json --envelope 输出:{ schema: "dsh-doctor/v1", generatedAt, profile, exitCode, summary{pass,warn,fail}, ok, checks:[{name,status,detail}] }
• status 小写词汇 + 退出码 0 全过 / 1 有 warn / 2 有 fail
• 新增 --profile <目录> 路径形式(兼容契约形态的调用)
• 10/10 测试,含信封形状与退出码语义的固定断言

关于 BOM fixture:我方目前没有 cordis.patch.yml 的结构化 lint(P7 级别的检查不在当前检查项内),所以 BOM 场景不在我方断言范围——如果契约里 BOM 需要 FAIL,建议在信封标准里明确"哪个检查、针对哪个文件",三方一起实现,避免各家语义漂移。

三方实现现在可互换了:CI/marketplace 脚本用同一个信封驱动。如果官方未来内置 dsh doctor,这个契约可以直接接管。