@bruc3van/dsh-doctor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Doctor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# DSH Doctor
+
+DSH Doctor 用来定位 DeepSeek Harness 无法启动、配置损坏和第三方插件不兼容等常见问题。默认运行完全只读；只有显式使用 `--fix`，查看精确的文件或命令计划并确认后，它才会实施可回滚的修复。
+
+这是社区维护的第三方工具，不属于 DeepSeek 官方项目。它不会加载或执行待检查插件的代码。
+
+## 安装
+
+需要 Node.js `22.19+` 或 `24+`：
+
+```sh
+npm install --global @bruc3van/dsh-doctor
+dsh-doctor
+```
+
+也可以临时运行：
+
+```sh
+npx @bruc3van/dsh-doctor
+```
+
+默认检查 `$DSH_HOME/profiles/web`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
+
+## 常用命令
+
+```sh
+# 只读诊断
+dsh-doctor
+dsh-doctor --profile web
+dsh-doctor --home /path/to/.dsh
+
+# 机器可读的只读报告，不显示提示
+dsh-doctor --json
+
+# 展示修复计划，确认后实施并重新诊断
+dsh-doctor --fix
+
+# 自动化环境中显式确认当前计划
+dsh-doctor --fix --yes --json
+```
+
+`--repair` 是 `--fix` 的别名。`--yes` 只有和 `--fix` 一起使用才有效。
+
+## 当前检查范围
+
+- profile `package.json` 的 JSON 根结构、依赖表、bundle 列表和 reload 生命周期
+- profile、home 和 bundle 的 `cordis.patch.yml` 语法与顶层结构，包括 `!!js` 表达式
+- `settings.yaml` 和 `.credentials.yaml` 的安全结构检查；凭据诊断不输出秘密值
+- profile 依赖、bundle 声明、patch 文件和 client bundle 是否存在
+- `dsh.client` 的 `platform`、`immediately`、`inject`、`external` 和 `./client` export contract
+- client bundle 中字面量 `require()` 与 external/module supplier 的一致性
+- 已删除的 Harness client package 引用
+- 第三方插件 peer range 与当前 Harness 实际版本的兼容性
+- Harness installation 优先于 profile 同名 bundle 的真实解析顺序
+
+## 修复安全边界
+
+每条可执行修复都包含稳定 ID、风险级别、说明和精确目标：
+
+- 文件修复在确认前展示路径，确认后再次校验 SHA-256 指纹。
+- 写入前创建 `.dsh-doctor-<timestamp>.bak` 备份，再通过同目录临时文件原子替换。
+- 外部命令使用固定 argv 调用，不拼接 shell 命令。
+- 任一步失败即停止后续修复，并保留已经创建的备份。
+- 完成后重新运行全部诊断，以最终状态决定退出码。
+
+首期只自动处理确定性操作，例如把已安装 bundle 恢复到 manifest 列表，或运行明确的 profile install/update。损坏 JSON/YAML、凭据值和插件移除只给建议，不猜测应该删除或改成什么。
+
+## 退出码
+
+- `0`：没有阻断错误；warning 仍会显示
+- `1`：发现可能阻断 Harness 启动的问题
+- `2`：参数、运行环境或修复执行失败
+
+## 当前限制
+
+- 静态扫描只识别代码中的字面量 `require("package")`；动态依赖需要未来的 bundle 元数据协议。
+- 配置检查覆盖语法和 Doctor 能稳定对齐的结构，但不执行 `!!js`，也不启动第三方插件。
+- 版本兼容以插件 `peerDependencies` 和当前可解析 Harness package 版本为依据；未声明兼容范围的插件只能做结构检查。
+- 真实启动探针尚未默认启用，因为启动第三方插件可能产生网络、进程或持久化副作用。优先使用只读配置组合检查。
+
+## 从源码开发
+
+```sh
+npm install
+npm run check
+node src/cli.mjs --help
+```
+
+新包需要先由 `@bruc3van` 对应的 npm 账号完成一次 `npm publish --access public`，创建公开包页面。然后在 npm 包设置中添加 GitHub Actions Trusted Publisher：Organization or user 为 `bruc3van`，Repository 为 `dsh-doctor`，Workflow filename 为 `release.yml`，Environment 留空，Allowed actions 只启用 `npm publish`。后续推送与 `package.json` 版本一致的 `vX.Y.Z` tag，workflow 会通过 OIDC 发布并由 npm 自动生成 provenance，不需要保存长期 npm token。

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bruc3van/dsh-doctor",
+  "version": "0.1.0",
+  "description": "Diagnostics and confirmed recovery for DeepSeek Harness profiles and third-party plugins",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bruc3van/dsh-doctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bruc3van/dsh-doctor/issues"
+  },
+  "homepage": "https://github.com/bruc3van/dsh-doctor#readme",
+  "bin": {
+    "dsh-doctor": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/cli.mjs && node --check src/doctor.mjs && node --check src/repair.mjs && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "js-yaml": "^4.2.0",
+    "semver": "^7.7.2",
+    "yaml": "^2.8.1"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import { formatReport, diagnose } from './doctor.mjs'
+import { applyRepairs, formatRepairPlan, repairsFromReport } from './repair.mjs'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+
+const HELP = `Usage: dsh-doctor [options]
+
+Diagnostics and confirmed recovery for a DeepSeek Harness profile.
+
+Options:
+  --profile <name>       profile to inspect (default: web)
+  --home <path>          Harness home (default: $DSH_HOME or ~/.dsh)
+  --harness-root <path>  active DeepSeek Harness source checkout
+  --json                 print machine-readable JSON
+  --fix, --repair        preview and apply available repairs after confirmation
+  --yes                  confirm the displayed repair plan non-interactively
+  -h, --help             show help
+  -v, --version          show version
+`
+
+function fail(message) {
+  process.stderr.write(`dsh-doctor: ${message}\n\n${HELP}`)
+  process.exitCode = 2
+}
+
+function valueAfter(args, index, name) {
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('-')) throw new Error(`${name} needs a value`)
+  return value
+}
+
+function parse(args) {
+  const options = {}
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--profile') options.profile = valueAfter(args, index++, arg)
+    else if (arg === '--home') options.home = valueAfter(args, index++, arg)
+    else if (arg === '--harness-root') options.harnessRoot = valueAfter(args, index++, arg)
+    else if (arg === '--json') options.json = true
+    else if (arg === '--fix' || arg === '--repair') options.fix = true
+    else if (arg === '--yes') options.yes = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else if (arg === '--version' || arg === '-v') options.version = true
+    else throw new Error(`unknown option ${arg}`)
+  }
+  return options
+}
+
+async function main() {
+  let options
+  try {
+    options = parse(process.argv.slice(2))
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error))
+    return
+  }
+  if (options.yes && !options.fix) throw new Error('--yes requires --fix')
+  if (options.json && options.fix && !options.yes) throw new Error('--json --fix requires --yes because a prompt would corrupt JSON output')
+  if (options.help) {
+    process.stdout.write(HELP)
+  } else if (options.version) {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const manifest = JSON.parse(readFileSync(resolve(here, '..', 'package.json'), 'utf8'))
+    process.stdout.write(`${manifest.version}\n`)
+  } else {
+    let report = diagnose(options)
+    let repairs = []
+    if (options.fix) {
+      const actions = repairsFromReport(report)
+      if (actions.length > 0) {
+        let confirmed = options.yes === true
+        if (!confirmed) {
+          if (!process.stdin.isTTY) throw new Error('--fix needs an interactive terminal or explicit --yes')
+          const prompt = formatRepairPlan(actions)
+          const reader = createInterface({ input: process.stdin, output: process.stderr })
+          const answer = await reader.question(prompt)
+          reader.close()
+          confirmed = /^y(?:es)?$/i.test(answer.trim())
+        }
+        if (confirmed) {
+          repairs = applyRepairs(actions)
+          if (repairs.every(item => item.status === 'applied')) report = diagnose(options)
+        }
+      }
+    }
+    const output = options.fix ? { ...report, repairs } : report
+    process.stdout.write(options.json
+      ? `${JSON.stringify(output, null, 2)}\n`
+      : `${formatReport(report, { color: process.stdout.isTTY })}${repairs.length > 0 ? `Repairs: ${JSON.stringify(repairs, null, 2)}\n` : ''}`)
+    process.exitCode = repairs.some(item => item.status === 'failed') ? 2 : report.summary.errors > 0 ? 1 : 0
+  }
+}
+
+try {
+  await main()
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  if (process.argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({ version: 1, operationalError: message }, null, 2)}\n`)
+  } else {
+    process.stderr.write(`dsh-doctor: ${message}\n`)
+  }
+  process.exitCode = 2
+}

package/src/doctor.mjs

@@ -0,0 +1,803 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import yaml from 'js-yaml'
+import semver from 'semver'
+import { parseDocument } from 'yaml'
+
+export const PLATFORM_MODULES = new Set([
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-store',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-ui-primitives',
+])
+
+const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 }
+const JS_EXPRESSION = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: value => typeof value === 'string' && value.trim().length > 0,
+  construct: value => value,
+})
+const PATCH_SCHEMA = yaml.DEFAULT_SCHEMA.extend([JS_EXPRESSION])
+
+function objectRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined
+}
+
+function finding(severity, code, message, options = {}) {
+  return {
+    severity,
+    code,
+    message,
+    ...options.package === undefined ? {} : { package: options.package },
+    ...options.evidence === undefined ? {} : { evidence: options.evidence },
+    ...options.suggestion === undefined ? {} : { suggestion: options.suggestion },
+    ...options.repair === undefined ? {} : { repair: options.repair },
+  }
+}
+
+function readJson(file, subject, findings) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    findings.push(finding('error', 'FILE_READ_FAILED', `Cannot read ${subject}.`, {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+    }))
+    return undefined
+  }
+  try {
+    const parsed = JSON.parse(text)
+    if (objectRecord(parsed) === undefined) {
+      findings.push(finding('error', 'INVALID_JSON_OBJECT', `${subject} must contain a JSON object.`, {
+        evidence: file,
+        suggestion: 'Restore a valid package manifest object before starting Harness.',
+      }))
+      return undefined
+    }
+    return parsed
+  } catch (error) {
+    findings.push(finding('error', 'INVALID_JSON', `${subject} is not valid JSON.`, {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Repair the JSON before starting this profile.',
+    }))
+    return undefined
+  }
+}
+
+function packagePathParts(name) {
+  if (name.startsWith('@')) {
+    const parts = name.split('/')
+    return parts.length === 2
+      && /^@[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(parts[0])
+      && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(parts[1])
+      ? parts
+      : undefined
+  }
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name) ? [name] : undefined
+}
+
+function packageManifestAt(directory, expectedName, findings, source) {
+  const file = join(directory, 'package.json')
+  if (!existsSync(file)) return undefined
+  const manifest = readJson(file, `${source} package manifest`, findings)
+  if (manifest === undefined) return undefined
+  if (manifest.name !== expectedName) {
+    findings.push(finding('warning', 'PACKAGE_NAME_MISMATCH', `${source} resolves to a package named ${JSON.stringify(manifest.name)}.`, {
+      package: expectedName,
+      evidence: file,
+      suggestion: 'Reinstall the dependency so its directory and package name agree.',
+    }))
+  }
+  return { directory, file, manifest }
+}
+
+function findHarnessRoot(start) {
+  let current = resolve(start)
+  while (true) {
+    if (existsSync(join(current, 'pnpm-workspace.yaml'))
+      && existsSync(join(current, 'packages'))
+      && existsSync(join(current, 'apps'))) return current
+    const parent = dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
+function workspacePackageDirectories(root) {
+  const directories = []
+  const addChildren = (parent) => {
+    if (!existsSync(parent)) return
+    for (const entry of readdirSync(parent, { withFileTypes: true })) {
+      if (entry.isDirectory()) directories.push(join(parent, entry.name))
+    }
+  }
+  for (const group of ['packages', 'vendor']) {
+    const groupRoot = join(root, group)
+    if (!existsSync(groupRoot)) continue
+    for (const entry of readdirSync(groupRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const first = join(groupRoot, entry.name)
+      if (existsSync(join(first, 'package.json'))) directories.push(first)
+      else addChildren(first)
+    }
+  }
+  addChildren(join(root, 'apps'))
+  return directories
+}
+
+function indexWorkspace(root, findings) {
+  const packages = new Map()
+  for (const directory of workspacePackageDirectories(root)) {
+    const file = join(directory, 'package.json')
+    if (!existsSync(file)) continue
+    const manifest = readJson(file, 'Harness workspace package manifest', findings)
+    if (typeof manifest?.name === 'string') packages.set(manifest.name, { directory, file, manifest })
+  }
+  return packages
+}
+
+function resolveHarnessContext(home, explicitRoot, findings) {
+  if (explicitRoot !== undefined) {
+    const root = resolve(explicitRoot)
+    if (!existsSync(join(root, 'package.json')) || !existsSync(join(root, 'packages'))) {
+      findings.push(finding('error', 'INVALID_HARNESS_ROOT', 'The configured Harness root is not a source checkout.', {
+        evidence: root,
+        suggestion: 'Pass the DeepSeek Harness repository root to --harness-root.',
+      }))
+      return { root, packages: new Map(), version: undefined, authoritative: true }
+    }
+    const manifest = readJson(join(root, 'package.json'), 'Harness root manifest', findings)
+    return { root, packages: indexWorkspace(root, findings), version: manifest?.version, authoritative: true }
+  }
+
+  const sharedDsh = join(home, 'profiles', 'node_modules', '@deepseek-ai', 'dsh')
+  if (existsSync(sharedDsh)) {
+    const canonical = realpathSync(sharedDsh)
+    const root = findHarnessRoot(canonical)
+    if (root !== undefined) {
+      const manifest = readJson(join(root, 'package.json'), 'Harness root manifest', findings)
+      return { root, packages: indexWorkspace(root, findings), version: manifest?.version, authoritative: true }
+    }
+    const manifest = readJson(join(canonical, 'package.json'), 'installed Harness manifest', findings)
+    return { root: canonical, packages: new Map(), version: manifest?.version, authoritative: false }
+  }
+
+  findings.push(finding('warning', 'HARNESS_INSTALLATION_UNKNOWN', 'Could not locate the Harness installation used by this home.', {
+    evidence: sharedDsh,
+    suggestion: 'Pass --harness-root when diagnosing a source checkout.',
+  }))
+  return { root: undefined, packages: new Map(), version: undefined, authoritative: false }
+}
+
+function packageResolver(profileDir, home, harnessPackages, findings) {
+  const cache = new Map()
+  return (name) => {
+    if (cache.has(name)) return cache.get(name)
+    const parts = packagePathParts(name)
+    if (parts === undefined) {
+      cache.set(name, undefined)
+      return undefined
+    }
+    const candidates = [
+      join(profileDir, 'node_modules', ...parts),
+      join(home, 'profiles', 'node_modules', ...parts),
+    ]
+    for (const candidate of candidates) {
+      if (!existsSync(join(candidate, 'package.json'))) continue
+      const resolved = packageManifestAt(candidate, name, findings, 'installed')
+      cache.set(name, resolved)
+      return resolved
+    }
+    const workspace = harnessPackages.get(name)
+    cache.set(name, workspace)
+    return workspace
+  }
+}
+
+function bundleResolver(profileDir, home, harnessPackages, findings) {
+  return (name) => {
+    const workspace = harnessPackages.get(name)
+    if (workspace !== undefined) return workspace
+    const parts = packagePathParts(name)
+    if (parts === undefined) return undefined
+    for (const candidate of [
+      join(home, 'profiles', 'node_modules', ...parts),
+      join(profileDir, 'node_modules', ...parts),
+    ]) {
+      if (!existsSync(join(candidate, 'package.json'))) continue
+      return packageManifestAt(candidate, name, findings, 'bundle')
+    }
+    return undefined
+  }
+}
+
+function clientExport(manifest) {
+  const value = manifest?.exports?.['./client']
+  if (typeof value === 'string') return value
+  if (value !== null && typeof value === 'object') {
+    if (typeof value.default === 'string') return value.default
+  }
+  return undefined
+}
+
+function dependencyEntries(value, field, file, findings) {
+  if (value === undefined) return []
+  const record = objectRecord(value)
+  if (record === undefined || Object.values(record).some(item => typeof item !== 'string')) {
+    findings.push(finding('error', 'INVALID_DEPENDENCY_MAP', `${field} must be an object of package names to string ranges.`, {
+      evidence: file,
+      suggestion: `Repair ${field} before managing or starting this profile.`,
+    }))
+    return []
+  }
+  return Object.entries(record)
+}
+
+function updateRepair(profile, name) {
+  return {
+    id: `update-package:${name}`,
+    kind: 'command',
+    risk: 'medium',
+    description: `Update ${name} in profile ${profile}.`,
+    command: ['dsh', 'plugin', '--profile', profile, 'update', name],
+  }
+}
+
+function safePackageFile(packageDir, exported) {
+  if (!exported.startsWith('./')) return undefined
+  const file = resolve(packageDir, exported)
+  const rel = relative(packageDir, file)
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined
+  return file
+}
+
+export function extractStaticRequires(source) {
+  const values = new Set()
+  const code = codePositions(source)
+  const pattern = /\brequire\s*\(\s*(['"])([^'"\\\r\n]+)\1\s*\)/g
+  for (const match of source.matchAll(pattern)) {
+    if (!code[match.index]) continue
+    const specifier = match[2]
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('node:')) continue
+    if (packagePathParts(specifier) !== undefined || specifier.startsWith('@')) values.add(specifier)
+  }
+  return [...values].sort()
+}
+
+function codePositions(source) {
+  const code = new Uint8Array(source.length)
+  let state = 'code'
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    const next = source[index + 1]
+    if (state === 'code') {
+      if (char === '/' && next === '/') {
+        state = 'line-comment'
+        index += 1
+      } else if (char === '/' && next === '*') {
+        state = 'block-comment'
+        index += 1
+      } else if (char === "'" || char === '"' || char === '`') {
+        state = char
+      } else {
+        code[index] = 1
+      }
+    } else if (state === 'line-comment') {
+      if (char === '\n') {
+        state = 'code'
+        code[index] = 1
+      }
+    } else if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        state = 'code'
+        index += 1
+      }
+    } else if (char === '\\') {
+      index += 1
+    } else if (char === state) {
+      state = 'code'
+    }
+  }
+  return code
+}
+
+function stripClientSuffix(specifier) {
+  return specifier.endsWith('/client') ? specifier.slice(0, -'/client'.length) : specifier
+}
+
+function stringArray(value) {
+  return Array.isArray(value) && value.every(item => typeof item === 'string') ? value : undefined
+}
+
+function inspectClientPackage(record, context) {
+  const {
+    findings, harnessPackages, harnessPackagesAuthoritative, profile, resolvePackage,
+  } = context
+  const name = record.manifest.name
+  const disableSuggestion = `Upgrade ${name}; if no compatible release exists, run dsh plugin --profile ${profile} remove ${name}.`
+  const declaration = record.manifest?.dsh?.client
+  if (declaration === undefined) return
+  if (declaration === null || typeof declaration !== 'object') {
+    findings.push(finding('error', 'INVALID_CLIENT_DECLARATION', `${name} has an invalid dsh.client declaration.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name),
+    }))
+    return
+  }
+
+  if (typeof declaration.platform !== 'string') {
+    findings.push(finding('error', 'INVALID_CLIENT_PLATFORM', `${name} dsh.client.platform must be a string.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name),
+    }))
+    return
+  }
+  if (declaration.immediately !== undefined && typeof declaration.immediately !== 'boolean') {
+    findings.push(finding('error', 'INVALID_CLIENT_IMMEDIATELY', `${name} dsh.client.immediately must be a boolean.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name),
+    }))
+  }
+  if (declaration.platform !== 'web') return
+
+  const external = stringArray(declaration.external)
+  const inject = stringArray(declaration.inject)
+  if (declaration.external !== undefined && external === undefined) {
+    findings.push(finding('error', 'INVALID_CLIENT_EXTERNAL', `${name} dsh.client.external must be a string array.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name),
+    }))
+  }
+  if (declaration.inject !== undefined && inject === undefined) {
+    findings.push(finding('error', 'INVALID_CLIENT_INJECT', `${name} dsh.client.inject must be a string array.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name),
+    }))
+  }
+
+  const exported = clientExport(record.manifest)
+  if (exported === undefined) {
+    findings.push(finding('error', 'CLIENT_EXPORT_MISSING', `${name} declares dsh.client but exports no ./client entry.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: disableSuggestion,
+    }))
+    return
+  }
+  const file = safePackageFile(record.directory, exported)
+  if (file === undefined || !existsSync(file) || !statSync(file).isFile()) {
+    findings.push(finding('error', 'CLIENT_BUNDLE_MISSING', `${name} client bundle is missing.`, {
+      package: name,
+      evidence: file ?? `${record.file}: exports["./client"] = ${JSON.stringify(exported)}`,
+      suggestion: `Reinstall or rebuild ${name}; if it remains broken, run dsh plugin --profile ${profile} remove ${name}.`,
+      repair: updateRepair(profile, name),
+    }))
+    return
+  }
+
+  let source
+  try {
+    source = readFileSync(file, 'utf8')
+  } catch (error) {
+    findings.push(finding('error', 'CLIENT_BUNDLE_UNREADABLE', `${name} client bundle cannot be read.`, {
+      package: name,
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+    }))
+    return
+  }
+
+  const declared = new Set(external ?? [])
+  for (const specifier of extractStaticRequires(source)) {
+    if (PLATFORM_MODULES.has(specifier) || specifier === name || stripClientSuffix(specifier) === name) continue
+    if (!declared.has(specifier)) {
+      findings.push(finding('error', 'UNDECLARED_CLIENT_REQUIRE', `${name} requires ${specifier} but does not declare it in dsh.client.external.`, {
+        package: name,
+        evidence: file,
+        suggestion: disableSuggestion,
+        repair: updateRepair(profile, name),
+      }))
+    }
+  }
+
+  for (const specifier of declared) {
+    if (PLATFORM_MODULES.has(specifier)) {
+      findings.push(finding('warning', 'REDUNDANT_CLIENT_EXTERNAL', `${name} declares platform module ${specifier} as an external.`, {
+        package: name,
+        evidence: record.file,
+        suggestion: 'The plugin author should remove this redundant dsh.client.external entry.',
+      }))
+      continue
+    }
+    const supplier = stripClientSuffix(specifier)
+    const supplied = harnessPackagesAuthoritative
+      ? harnessPackages.get(supplier)
+      : harnessPackages.get(supplier) ?? resolvePackage(supplier)
+    if (supplied === undefined || supplied.manifest?.dsh?.client === undefined) {
+      findings.push(finding('error', 'CLIENT_EXTERNAL_WITHOUT_SUPPLIER', `${name} requests ${specifier}, but the active Harness has no client module supplier.`, {
+        package: name,
+        evidence: record.file,
+        suggestion: disableSuggestion,
+        repair: updateRepair(profile, name),
+      }))
+    }
+  }
+
+  if (harnessPackagesAuthoritative) {
+    for (const dependency of inject ?? []) {
+      if (!dependency.startsWith('@deepseek-ai/dsh-')) continue
+      if (!harnessPackages.has(stripClientSuffix(dependency))) {
+        findings.push(finding('error', 'REMOVED_CLIENT_INJECT', `${name} injects ${dependency}, which is absent from the active Harness source tree.`, {
+          package: name,
+          evidence: record.file,
+          suggestion: disableSuggestion,
+          repair: updateRepair(profile, name),
+        }))
+      }
+    }
+
+    const legacyPeers = Object.keys(record.manifest.peerDependencies ?? {})
+      .filter(peer => peer.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(peer))
+      .sort()
+    if (legacyPeers.length > 0) {
+      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${name} still declares Harness packages that no longer exist in the active source tree.`, {
+        package: name,
+        evidence: legacyPeers.join(', '),
+        suggestion: 'Treat this plugin as compatibility-risky and update it before the next Harness upgrade.',
+      }))
+    }
+  }
+}
+
+function inspectBundle(name, record, findings) {
+  if (record === undefined) {
+    findings.push(finding('error', 'BUNDLE_NOT_INSTALLED', `Profile bundle ${name} is not installed.`, {
+      package: name,
+      suggestion: `Run dsh plugin --profile <profile> install, upgrade the bundle, or remove it from the profile.`,
+    }))
+    return
+  }
+  const patch = record.manifest?.dsh?.bundle?.patch
+  if (typeof patch !== 'string' || patch.length === 0) {
+    findings.push(finding('error', 'BUNDLE_DECLARATION_MISSING', `${name} is listed as a profile bundle but declares no dsh.bundle.patch.`, {
+      package: name,
+      evidence: record.file,
+      suggestion: 'Upgrade or remove this bundle from dsh.profile.bundles.',
+    }))
+    return
+  }
+  const file = safePackageFile(record.directory, patch)
+  if (file === undefined || !existsSync(file) || !statSync(file).isFile()) {
+    findings.push(finding('error', 'BUNDLE_PATCH_MISSING', `${name} bundle patch is missing.`, {
+      package: name,
+      evidence: file ?? `${record.file}: dsh.bundle.patch = ${JSON.stringify(patch)}`,
+      suggestion: 'Reinstall or upgrade this bundle, or remove it from the profile.',
+    }))
+  } else inspectPatchFile(file, `${name} bundle patch`, findings)
+}
+
+function inspectPatchFile(file, subject, findings) {
+  let parsed
+  try {
+    parsed = yaml.load(readFileSync(file, 'utf8'), { schema: PATCH_SCHEMA })
+  } catch (error) {
+    findings.push(finding('error', 'INVALID_PATCH_YAML', `${subject} cannot be parsed.`, {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Repair the YAML syntax before starting this profile.',
+    }))
+    return
+  }
+  if (!Array.isArray(parsed) || parsed.some(item => objectRecord(item) === undefined)) {
+    findings.push(finding('error', 'INVALID_PATCH_LIST', `${subject} must be a top-level YAML array of mappings.`, {
+      evidence: file,
+      suggestion: 'Repair the patch structure before starting this profile.',
+    }))
+  }
+}
+
+function inspectSettings(file, findings) {
+  if (!existsSync(file)) return
+  let root
+  try {
+    if (file.endsWith('.json')) root = JSON.parse(readFileSync(file, 'utf8'))
+    else {
+      const document = parseDocument(readFileSync(file, 'utf8'), { prettyErrors: true })
+      if (document.errors.length > 0) {
+        const positions = document.errors.map(error => {
+          const at = error.linePos?.[0]
+          return `${error.code}${at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`}`
+        })
+        throw new Error(positions.join('; '))
+      }
+      root = document.toJS() ?? {}
+    }
+  } catch (error) {
+    findings.push(finding('error', 'INVALID_SETTINGS_DOCUMENT', 'Harness settings cannot be parsed.', {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Repair the settings syntax; Doctor will not guess credential or model values.',
+    }))
+    return
+  }
+  if (objectRecord(root) === undefined) {
+    findings.push(finding('error', 'INVALID_SETTINGS_ROOT', 'Harness settings must be a map of namespace sections.', {
+      evidence: file,
+      suggestion: 'Replace the root scalar or array with a mapping.',
+    }))
+  }
+}
+
+function inspectCredentials(file, findings) {
+  if (!existsSync(file)) return
+  let root
+  try {
+    const document = parseDocument(readFileSync(file, 'utf8'), { prettyErrors: true, uniqueKeys: true })
+    if (document.errors.length > 0) {
+      const positions = document.errors.map(error => {
+        const at = error.linePos?.[0]
+        return `${error.code}${at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`}`
+      })
+      throw new Error(positions.join('; '))
+    }
+    root = document.toJS() ?? {}
+  } catch (error) {
+    findings.push(finding('error', 'INVALID_CREDENTIALS_DOCUMENT', 'Harness credentials cannot be parsed.', {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Repair only the reported structure; Doctor never prints or rewrites secret values.',
+    }))
+    return
+  }
+  const fields = objectRecord(root)
+  if (fields === undefined) {
+    findings.push(finding('error', 'INVALID_CREDENTIALS_ROOT', 'Harness credentials must be a mapping.', { evidence: file }))
+    return
+  }
+  const keys = Object.keys(fields)
+  if (keys.length === 0) return
+  if (fields.version !== 1 || keys.some(key => !['version', 'refs', 'records'].includes(key))) {
+    findings.push(finding('error', 'INVALID_CREDENTIALS_LAYOUT', 'Harness credentials do not use the supported version 1 layout.', {
+      evidence: file,
+      suggestion: 'Migrate the document structure without exposing or changing its secret values.',
+    }))
+  }
+}
+
+function inspectPatchFileIfPresent(file, subject, findings) {
+  if (existsSync(file)) inspectPatchFile(file, subject, findings)
+}
+
+function inspectCompatibility(record, context) {
+  const { findings, harnessPackages, profile, resolvePackage } = context
+  const peers = dependencyEntries(record.manifest.peerDependencies, 'peerDependencies', record.file, findings)
+  const mismatches = []
+  for (const [name, range] of peers) {
+    if (!name.startsWith('@deepseek-ai/') && name !== 'cordis') continue
+    const supplier = harnessPackages.get(name) ?? resolvePackage(name)
+    if (supplier === undefined) continue
+    const version = supplier.manifest?.version
+    if (typeof version !== 'string' || semver.valid(version) === null || semver.validRange(range) === null) continue
+    if (semver.satisfies(version, range, { includePrerelease: true })) continue
+    mismatches.push(`${name} ${range} (active ${version})`)
+  }
+  if (mismatches.length > 0) {
+    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${record.manifest.name} has Harness peer ranges that do not accept the active versions.`, {
+      package: record.manifest.name,
+      evidence: mismatches.join(', '),
+      suggestion: `Update ${record.manifest.name} to a release compatible with the active Harness.`,
+      repair: updateRepair(profile, record.manifest.name),
+    }))
+  }
+}
+
+export function defaultDshHome(env = process.env) {
+  const configured = env.DSH_HOME
+  if (configured !== undefined && configured.trim().length > 0) {
+    if (configured === '~') return homedir()
+    if (configured.startsWith('~/') || configured.startsWith('~\\')) return resolve(homedir(), configured.slice(2))
+    return resolve(configured)
+  }
+  return join(homedir(), '.dsh')
+}
+
+export function diagnose(options = {}) {
+  const findings = []
+  const home = resolve(options.home ?? defaultDshHome(options.env))
+  const profile = options.profile ?? 'web'
+  if (profile === '' || profile === '.' || profile === '..' || profile.includes('/') || profile.includes('\\')) {
+    findings.push(finding('error', 'INVALID_PROFILE_NAME', `Invalid profile name ${JSON.stringify(profile)}.`))
+    return finish({ home, profile, profileDir: undefined, harness: {}, packages: [] }, findings)
+  }
+  const profileDir = join(home, 'profiles', profile)
+  const profileManifestFile = join(profileDir, 'package.json')
+  if (!existsSync(profileManifestFile)) {
+    findings.push(finding('error', 'PROFILE_NOT_FOUND', `Profile ${profile} does not exist.`, {
+      evidence: profileDir,
+      suggestion: `Start the profile once or initialize it with dsh plugin --profile ${profile} install.`,
+    }))
+    return finish({ home, profile, profileDir, harness: {}, packages: [] }, findings)
+  }
+  const profileManifest = readJson(profileManifestFile, `profile ${profile} manifest`, findings)
+  if (profileManifest === undefined) {
+    return finish({ home, profile, profileDir, harness: {}, packages: [] }, findings)
+  }
+
+  const harness = resolveHarnessContext(home, options.harnessRoot, findings)
+  const resolvePackage = packageResolver(profileDir, home, harness.packages, findings)
+  const resolveBundle = bundleResolver(profileDir, home, harness.packages, findings)
+  const dependencyEntriesList = dependencyEntries(profileManifest.dependencies, 'dependencies', profileManifestFile, findings)
+  const dependencyNames = dependencyEntriesList.map(([name]) => name)
+  const bundles = profileManifest?.dsh?.profile?.bundles
+  if (bundles !== undefined && (!Array.isArray(bundles) || !bundles.every(item => typeof item === 'string'))) {
+    findings.push(finding('error', 'INVALID_BUNDLE_LIST', 'dsh.profile.bundles must be a string array.', {
+      evidence: profileManifestFile,
+      suggestion: 'Repair the profile manifest before starting Harness.',
+    }))
+  }
+  const bundleNames = Array.isArray(bundles) ? bundles.filter(item => typeof item === 'string') : []
+  const patchReload = profileManifest?.dsh?.profile?.patchReload
+  if (patchReload !== undefined && patchReload !== 'live' && patchReload !== 'startup') {
+    findings.push(finding('error', 'INVALID_PATCH_RELOAD', 'dsh.profile.patchReload must be "live" or "startup".', {
+      evidence: profileManifestFile,
+      suggestion: 'Choose the reload lifecycle intended for this profile.',
+    }))
+  }
+
+  const records = new Map()
+  for (const name of dependencyNames) {
+    const record = resolvePackage(name)
+    if (record !== undefined) records.set(name, record)
+  }
+  const bundleRecords = new Map()
+  for (const name of bundleNames) {
+    const record = resolveBundle(name)
+    if (record !== undefined) bundleRecords.set(name, record)
+  }
+  for (const name of dependencyNames) {
+    const record = records.get(name)
+    if (record === undefined) {
+      findings.push(finding('error', 'DEPENDENCY_NOT_INSTALLED', `Profile dependency ${name} is not installed.`, {
+        package: name,
+        evidence: profileManifestFile,
+        suggestion: `Run dsh plugin --profile ${profile} install.`,
+        repair: {
+          id: `install-profile:${profile}`,
+          kind: 'command',
+          risk: 'medium',
+          description: `Install the declared dependencies for profile ${profile}.`,
+          command: ['dsh', 'plugin', '--profile', profile, 'install'],
+        },
+      }))
+      continue
+    }
+    const declared = dependencyEntriesList.find(([dependency]) => dependency === name)?.[1]
+    const installed = record.manifest?.version
+    if (typeof declared === 'string' && typeof installed === 'string'
+      && semver.validRange(declared) !== null && semver.valid(installed) !== null
+      && !semver.satisfies(installed, declared, { includePrerelease: true })) {
+      findings.push(finding('warning', 'PROFILE_DEPENDENCY_VERSION_MISMATCH', `Profile requests ${name} ${declared}, but ${installed} is installed.`, {
+        package: name,
+        evidence: record.file,
+        suggestion: `Reconcile the profile installation with dsh plugin --profile ${profile} install.`,
+        repair: {
+          id: `install-profile:${profile}`,
+          kind: 'command',
+          risk: 'medium',
+          description: `Install the declared dependencies for profile ${profile}.`,
+          command: ['dsh', 'plugin', '--profile', profile, 'install'],
+        },
+      }))
+    }
+    if (record.manifest?.dsh?.bundle?.patch !== undefined && !bundleNames.includes(name)) {
+      findings.push(finding('warning', 'INSTALLED_BUNDLE_INACTIVE', `${name} is installed as a bundle but is absent from dsh.profile.bundles.`, {
+        package: name,
+        evidence: profileManifestFile,
+        suggestion: 'Re-run the matching dsh plugin add/update command or remove the unused dependency.',
+        repair: {
+          id: `activate-bundle:${name}`,
+          kind: 'json-edit',
+          risk: 'low',
+          description: `Add ${name} to dsh.profile.bundles.`,
+          file: profileManifestFile,
+          operation: { type: 'add-bundle', name },
+        },
+      }))
+    }
+  }
+  for (const name of bundleNames) inspectBundle(name, bundleRecords.get(name), findings)
+
+  inspectPatchFileIfPresent(join(profileDir, 'cordis.patch.yml'), 'profile patch', findings)
+  inspectPatchFileIfPresent(join(home, 'cordis.patch.yml'), 'home patch', findings)
+  inspectSettings(join(home, 'settings.yaml'), findings)
+  inspectCredentials(join(home, '.credentials.yaml'), findings)
+
+  const thirdPartyRecords = dependencyNames
+    .map(name => records.get(name))
+    .filter(record => record !== undefined)
+  for (const record of thirdPartyRecords) {
+    inspectClientPackage(record, {
+      findings,
+      harnessPackages: harness.packages,
+      harnessPackagesAuthoritative: harness.authoritative,
+      profile,
+      resolvePackage,
+    })
+    inspectCompatibility(record, {
+      findings,
+      profile,
+      resolvePackage,
+      harnessPackages: harness.packages,
+    })
+  }
+
+  return finish({
+    home,
+    profile,
+    profileDir,
+    harness: { root: harness.root, version: harness.version },
+    packages: thirdPartyRecords.map(record => ({
+      name: record.manifest.name,
+      version: record.manifest.version,
+      directory: record.directory,
+      client: record.manifest?.dsh?.client !== undefined,
+      bundle: record.manifest?.dsh?.bundle !== undefined,
+    })),
+  }, findings)
+}
+
+function finish(context, findings) {
+  findings.sort((left, right) => {
+    const severity = SEVERITY_ORDER[left.severity] - SEVERITY_ORDER[right.severity]
+    return severity || left.code.localeCompare(right.code) || left.message.localeCompare(right.message)
+  })
+  const summary = {
+    errors: findings.filter(item => item.severity === 'error').length,
+    warnings: findings.filter(item => item.severity === 'warning').length,
+    info: findings.filter(item => item.severity === 'info').length,
+  }
+  return { version: 1, ok: summary.errors === 0, context, summary, findings }
+}
+
+export function formatReport(report, options = {}) {
+  const color = options.color ?? false
+  const paint = (severity, value) => {
+    if (!color) return value
+    const code = severity === 'error' ? 31 : severity === 'warning' ? 33 : 36
+    return `\u001B[${code}m${value}\u001B[0m`
+  }
+  const lines = [
+    'DSH Doctor',
+    `Profile: ${report.context.profile}`,
+    `Home: ${report.context.home}`,
+    `Harness: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
+    `Checked third-party packages: ${String(report.context.packages.length)}`,
+    '',
+  ]
+  if (report.findings.length === 0) {
+    lines.push(paint('info', 'OK  No problems found by the MVP checks.'))
+  } else {
+    for (const item of report.findings) {
+      const label = item.severity === 'error' ? 'ERROR' : item.severity === 'warning' ? 'WARN ' : 'INFO '
+      lines.push(paint(item.severity, `${label} [${item.code}] ${item.message}`))
+      if (item.package !== undefined) lines.push(`      Package: ${item.package}`)
+      if (item.evidence !== undefined) lines.push(`      Evidence: ${item.evidence}`)
+      if (item.suggestion !== undefined) lines.push(`      Action: ${item.suggestion}`)
+      lines.push('')
+    }
+  }
+  lines.push(`Summary: ${String(report.summary.errors)} error(s), ${String(report.summary.warnings)} warning(s)`)
+  if (report.summary.errors > 0) lines.push('Harness may fail to start. Upgrade or disable the error-producing plugin first.')
+  return `${lines.join('\n')}\n`
+}

package/src/repair.mjs

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { copyFileSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import crossSpawn from 'cross-spawn'
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+export function repairsFromReport(report) {
+  const unique = new Map()
+  for (const item of report.findings) {
+    if (item.repair !== undefined && !unique.has(item.repair.id)) unique.set(item.repair.id, item.repair)
+  }
+  return [...unique.values()].sort((left, right) => {
+    if (left.kind === right.kind) return left.id.localeCompare(right.id)
+    return left.kind === 'json-edit' ? -1 : 1
+  }).map(action => {
+    if (action.kind !== 'json-edit') return action
+    const text = readFileSync(action.file, 'utf8')
+    return { ...action, expectedHash: hash(text) }
+  })
+}
+
+export function formatRepairPlan(actions) {
+  const lines = ['Proposed repairs:', '']
+  actions.forEach((action, index) => {
+    lines.push(`${String(index + 1)}. [${action.risk.toUpperCase()}] ${action.description}`)
+    if (action.kind === 'command') lines.push(`   Command: ${action.command.map(quoteArgument).join(' ')}`)
+    else lines.push(`   File: ${action.file}`, `   Backup: ${action.file}.dsh-doctor-<timestamp>.bak`)
+    lines.push('')
+  })
+  return `${lines.join('\n')}Apply these repairs? [y/N] `
+}
+
+function quoteArgument(value) {
+  return /^[a-zA-Z0-9_@./:-]+$/.test(value) ? value : JSON.stringify(value)
+}
+
+function applyJsonEdit(action) {
+  const current = readFileSync(action.file, 'utf8')
+  if (hash(current) !== action.expectedHash) {
+    throw new Error(`${action.file} changed after the repair preview; diagnose again before applying`)
+  }
+  const manifest = JSON.parse(current)
+  if (action.operation.type !== 'add-bundle') throw new Error(`unsupported JSON repair ${action.operation.type}`)
+  const bundles = manifest?.dsh?.profile?.bundles
+  if (!Array.isArray(bundles)) throw new Error(`${action.file} no longer has a valid dsh.profile.bundles array`)
+  if (!bundles.includes(action.operation.name)) bundles.push(action.operation.name)
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backup = `${action.file}.dsh-doctor-${stamp}.bak`
+  copyFileSync(action.file, backup)
+  const temporary = join(dirname(action.file), `.dsh-doctor-${process.pid}-${randomBytes(6).toString('hex')}.tmp`)
+  writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { mode: statSync(action.file).mode })
+  renameSync(temporary, action.file)
+  return { id: action.id, status: 'applied', backup }
+}
+
+function applyCommand(action) {
+  const [command, ...args] = action.command
+  const result = crossSpawn.sync(command, args, { stdio: 'inherit' })
+  if (result.error != null) throw result.error
+  if (result.status !== 0) throw new Error(`${command} exited with status ${String(result.status)}`)
+  return { id: action.id, status: 'applied' }
+}
+
+export function applyRepairs(actions) {
+  const results = []
+  for (const action of actions) {
+    try {
+      results.push(action.kind === 'json-edit' ? applyJsonEdit(action) : applyCommand(action))
+    } catch (error) {
+      results.push({
+        id: action.id,
+        status: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+      })
+      break
+    }
+  }
+  return results
+}