@bruc3van/dsh-doctor 0.5.1 → 0.5.2

package/README.en.md

@@ -96,7 +96,7 @@ Install it directly from the GitHub repository into a supported coding agent:
 npx skills add bruc3van/dsh-doctor
 ```
 
-The repository currently exposes one skill, so the `skills` CLI discovers and installs `dsh-plugin-upgrade`; add `--skill dsh-plugin-upgrade` to select it explicitly. This installs the agent skill, not a global DSH Doctor CLI. The skill uses an existing `dsh-doctor` command when available and falls back to the matching `npx @bruc3van/dsh-doctor` workflow when it is not installed.
+The repository currently exposes one skill, so the `skills` CLI discovers and installs `dsh-plugin-upgrade`; add `--skill dsh-plugin-upgrade` to select it explicitly. This installs the agent skill, not a global DSH Doctor CLI. The skill checks the local CLI version and target catalog, performs a read-only registry update check with `npm view`, and pins one exact npx version for all three phases when the local CLI is missing, outdated, or lacks the catalog. A global install or update always requires explicit user authorization.
 
 ---
 

package/README.md

@@ -96,7 +96,7 @@ dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
 npx skills add bruc3van/dsh-doctor
 ```
 
-仓库当前只提供一个 skill，`skills` CLI 会发现并安装 `dsh-plugin-upgrade`；需要显式选择时可加 `--skill dsh-plugin-upgrade`。该命令只安装 Agent skill，不会全局安装 DSH Doctor CLI；skill 会优先使用现有 `dsh-doctor`，不存在时按流程通过 `npx @bruc3van/dsh-doctor` 调用匹配的 CLI。
+仓库当前只提供一个 skill，`skills` CLI 会发现并安装 `dsh-plugin-upgrade`；需要显式选择时可加 `--skill dsh-plugin-upgrade`。该命令只安装 Agent skill，不会全局安装 DSH Doctor CLI。Skill 会检查本地 CLI 版本和目标 catalog，通过只读 `npm view` 检查 registry 更新；本地 CLI 缺失、过期或缺少 catalog 时，默认固定一个精确版本并通过 `npx` 完成三阶段。全局安装或更新始终需要用户明确授权。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Diagnose DSH upgrades, migrate plugins with safe codemods, and verify recovery decisions",
   "license": "MIT",
   "type": "module",

package/skills/dsh-plugin-upgrade/SKILL.md

@@ -15,6 +15,7 @@ Determine:
 - the plugin repository root;
 - the DSH Harness checkout when available;
 - whether the developer authorizes writes and project command execution;
+- whether the developer authorizes a global CLI install or update;
 - the plugin's package manager and build scripts.
 
 Use these fixed refs unless the user explicitly requests a supported alternative:
@@ -22,9 +23,11 @@ Use these fixed refs unless the user explicitly requests a supported alternative
 - source: `dsh-v0.1.1-rc.2`
 - target: `dsh-v0.1.2-alpha.2`
 
-Read [migration-map.md](references/migration-map.md) before making semantic changes. Read [verification.md](references/verification.md) before build or runtime verification.
+Read [cli-bootstrap.md](references/cli-bootstrap.md) before running any migration command, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before build or runtime verification.
 
-Before touching the plugin, run `dsh-doctor migrations list` and confirm this exact version pair is present. If `dsh-doctor` is not on `PATH`, use `npx --package=@bruc3van/dsh-doctor dsh-doctor migrations list` and confirm the same catalog before continuing; never silently use an older CLI that lacks the migration.
+Before touching the plugin, inspect the local CLI and perform the read-only registry update check described in `cli-bootstrap.md`. Select one exact DSH Doctor version, verify it exposes this migration catalog, and keep the same invocation for analyze, apply, and verify. Prefer an exact-version `npx` fallback over changing the developer's global installation. Never globally install or update the CLI without explicit authorization.
+
+The examples below use `dsh-doctor` for readability. When bootstrap selected an npx invocation, substitute the complete pinned prefix, `npx --yes --package=@bruc3van/dsh-doctor@<selected-version> dsh-doctor`, in every phase.
 
 ## Phase 1: analyze
 
@@ -96,3 +99,4 @@ State the highest achieved gate exactly:
 - behavior verified separately with named evidence
 
 Do not call the plugin compatible while errors, semantic tasks, stale artifacts, or required behavior checks remain. Include backups and retained temporary directories in the handoff.
+Also report the selected DSH Doctor version and source (`local`, exact-version `npx`, or explicitly authorized global install), the registry version observed at bootstrap, and whether update status was current, outdated, missing, or unknown.

package/skills/dsh-plugin-upgrade/evals/evals.json

@@ -31,6 +31,18 @@
         "Uses a temporary DSH_HOME and reports retained failure state",
         "Keeps business behavior verification separate from activation smoke"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "帮我升级这个插件，但机器上的 dsh-doctor 是旧版，而且我没有授权修改全局 npm 包。请先检查有没有新版本，再继续迁移。",
+      "expected_output": "Checks the registry read-only, selects one exact-version npx CLI with the required catalog, avoids global installation, and reports the selected version and update status.",
+      "expectations": [
+        "Checks the local CLI version and exact migration catalog before use",
+        "Uses npm view as a read-only registry update check",
+        "Pins one resolved npx package version for all migration phases",
+        "Does not install or update a global CLI without explicit authorization",
+        "Reports local, registry, selected CLI, catalog, and update-status evidence"
+      ]
     }
   ]
 }

package/skills/dsh-plugin-upgrade/references/cli-bootstrap.md

@@ -0,0 +1,59 @@
+# DSH Doctor CLI bootstrap
+
+Choose the CLI once before analysis so every migration phase uses the same implementation and catalog.
+
+## 1. Inspect the environment
+
+Confirm Node.js satisfies the package engine (`^22.19.0` or `>=24.0.0`). When `dsh-doctor` is available, run:
+
+```sh
+dsh-doctor --version
+dsh-doctor migrations list --json
+```
+
+Record the local version and whether the exact `dsh-v0.1.1-rc.2` to `dsh-v0.1.2-alpha.2` catalog is present. A command that exists but lacks this catalog is not usable for this skill.
+
+## 2. Check the registry without changing the machine
+
+Query the official registry:
+
+```sh
+npm view @bruc3van/dsh-doctor version --registry=https://registry.npmjs.org
+```
+
+This is a read-only update check. If it fails because the registry is unavailable, report update status as `unknown`; do not describe the local CLI as current. An offline local CLI may still be used when it exposes the exact required catalog.
+
+## 3. Select and pin one invocation
+
+- When the local version equals the registry version and exposes the catalog, use `dsh-doctor` directly.
+- When the local CLI is missing, differs from the registry version, or lacks the catalog, prefer the registry version through exact-version npx. First verify that version exposes the required catalog:
+
+```sh
+npx --yes --package=@bruc3van/dsh-doctor@<registry-version> dsh-doctor migrations list --json
+```
+
+- When the registry is unavailable, use the local CLI only if its catalog check passed.
+- When neither candidate exposes the catalog, stop and report the missing prerequisite instead of guessing a compatible CLI.
+- Respect an explicit developer request to use a particular local or development CLI, but still record its version and verify the catalog.
+
+After selecting a version, replace `<registry-version>` with the resolved exact version in every npx command. Do not use `@latest` separately in analyze, apply, and verify because the resolved package could change during the migration.
+
+## 4. Keep global installation separately authorized
+
+The skill installation does not authorize system-wide npm changes. Only after the developer explicitly approves a global install or update may the agent run:
+
+```sh
+npm install --global @bruc3van/dsh-doctor@<selected-version>
+```
+
+Afterwards, re-run `dsh-doctor --version` and `dsh-doctor migrations list --json`. If either result differs from the selected version or required catalog, stop rather than falling back silently.
+
+## 5. Preserve evidence
+
+Include these fields in the handoff:
+
+- local CLI version or `missing`;
+- registry version or `unknown`;
+- selected exact version and invocation source (`local`, `npx`, or authorized `global-install`);
+- required catalog present or absent;
+- update status: `current`, `outdated`, `missing`, or `unknown`.