[idea] One-command environment doctor for fresh installs (dsh doctor)

[JZQiang]

Idea

A one-command environment doctor for fresh installs (dsh doctor / dsh diagnose), run pre-web and pre-build.

Motivation

A quick scan of recent discussions shows the same class of problems recurring — all environment/setup issues that a diagnostics command could catch instantly with actionable output:

• dsh web fails on Linux: node-pty native module pty.node missing (no linux-x64 prebuild, no build fallback) #605: dsh web fails on Linux — node-pty native module pty.node missing (no prebuild, no build fallback)
• Build fails on fresh clone: tsdown cannot load tsdown.config.ts because "unrun" is not installed #623: Build fails on fresh clone — tsdown cannot load config because unrun is not installed
• Firefox 无法打开，提示WebGL异常 #609: Firefox can't open — WebGL errors
• First-run Web UI appears stuck until API key and workspace are configured #619: First-run Web UI appears stuck until API key and workspace are configured
• 有人封装成独立桌面应用吗 #607: "has anyone packaged this as a standalone desktop app" (setup friction)

What it could check

• Node version vs engines (^22.19 || >=24), pnpm version vs packageManager, corepack state
• node_modules integrity: missing workspace deps / native modules (pty.node etc.), postinstall completeness, pnpm install freshness (lockfile drift)
• Web UI prerequisites: WebGL availability (headless/GPU-less environments), port 3080 conflicts, localhost bind
• First-run readiness: is an API key configured, is a workspace selected — with a pointer to the right config file instead of a stuck-looking UI
• Output as a checklist with ✅/❌ + exact fix commands per item (mirroring how scripts/run-gates.ts gates work but for user environments)

Why it helps

The project is pre-release with breaking changes weekly; the fastest-growing cost for new adopters is environment diagnosis, and most of these discussions could be closed with a single command's output. It also gives maintainers a standardized "attach your dsh doctor output" template for bug reports.

Happy to help spec or prototype it (as a plugin, naturally 😄).

[pingfanfan]

A community-side prototype for the beginner/runtime layer is now available:

• node scripts/beginner-doctor.mjs checks Node.js, npm, npx and the local exercise files without network access.
• node scripts/beginner-doctor.mjs --report prints a copy/paste diagnostic receipt with the local path redacted and explicit states for network, Web UI and plugin checks.
• The report does not read or upload credentials, and it does not call a model.
• node scripts/beginner-start.mjs keeps the DSH version fixed and separates network, Node-version and port failures from plugin failures.

Prototype and beginner quickstart:
https://github.com/pingfanfan/dsh-learn/blob/main/scripts/beginner-doctor.mjs
https://github.com/pingfanfan/dsh-learn/blob/main/content/channels/github/dsh-beginner-quickstart-rc6.md

This is community-side, not an official dsh doctor. It deliberately distinguishes not_checked from failed; WebGL, native-module/build, workspace and provider checks should remain separate layers in a future official command. The current local npm registry is unreachable, so I am not claiming a successful dynamic DSH/plugin run from this environment; the static validators and safe report path pass.