@bruc3van/dsh-doctor 0.5.5 → 0.5.7

package/README.en.md

@@ -2,19 +2,24 @@
 
 [中文](README.md) | English
 
-DSH Doctor helps an agent diagnose and upgrade DeepSeek Harness plugins: identify API changes between releases, modify code where the migration is known, point out semantic changes that need developer judgment, then rebuild and verify the plugin.
+DSH Doctor is an upgrade and troubleshooting tool for DSH plugin developers and agents. It finds what needs to change during an upgrade, handles changes that are known to be safe, and then checks dependencies, build output, installation, and activation.
 
-The current focus is:
+When a change depends on the plugin's business logic, Doctor calls it out for the agent or developer instead of guessing. Every edit is previewed and backed up first, and runtime checks use a temporary DSH environment rather than the developer's everyday profile.
 
-```text
-DSH 0.1.1 → DSH 0.1.2
-```
+> This is a community-maintained third-party project, not an official DeepSeek project. The current migration scope is DSH 0.1.1 → 0.1.2. The catalog exactly covers `dsh-v0.1.1-rc.2` → `dsh-v0.1.2-alpha.3` and retains the alpha.2 historical rules. Differences outside those catalogs still require a separate investigation and are not proven compatible by the catalog.
 
-The project also diagnoses DSH profiles and installed plugins, checks for compatible versions, and performs safety checks before quarantine or removal.
+## What it helps with
+
+| Scenario | What DSH Doctor provides |
+|---|---|
+| Upgrade a plugin | Scans source, dependencies, manifest, client graph, patches, and build output; applies exact catalog-confirmed migrations and leaves semantic work to the agent |
+| Verify a migration | Runs static reanalysis, dependency synchronization, build/test scripts, real tarball packaging, and temporary-profile installation and activation checks |
+| Diagnose a DSH environment | Checks profile layers, plugin versions and peers, lockfile, bundles, patches, client contracts, duplicate mounts, and DSH CLI/Harness version drift |
+| Recover safely | Compares before/after baselines, checks compatible updates, generates and verifies quarantine overlays, and records dependency and configuration impact before removal |
 
-> This is a community-maintained third-party project, not an official DeepSeek project. The current catalog uses `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.2` as the reference points for the 0.1.1-to-0.1.2 changes. An agent should still check actual differences when a plugin uses another patch or prerelease.
+Agents can orchestrate these capabilities through the skill, while other tools can integrate the same structured CLI workflows.
 
-## Upgrade a plugin with the skill
+## Recommended: use the skill with an agent
 
 Install the repository's [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) skill:
 
@@ -29,219 +34,110 @@ Upgrade this plugin from DSH 0.1.1 to DSH 0.1.2.
 Analyze compatibility first, modify the code, then complete build and runtime verification.
 ```
 
-An upgrade request does not itself authorize dropping the old runtime. If the developer has not said, the skill explicitly asks whether the same upgraded plugin release must still support DSH 0.1.1 before any migration write, dependency installation, build, or runtime command. When compatibility must be preserved, the agent designs a dual-version approach first and verifies 0.1.1 and 0.1.2 separately; one successful 0.1.2 run is not dual-version evidence.
+The skill guides the agent to:
 
-The skill reminds the agent to work in this order:
+1. establish the plugin, actual DSH installation, Harness checkout, package manager, and usable DSH Doctor;
+2. analyze source, dependencies, configuration, patches, and existing artifacts;
+3. confirm whether the upgraded plugin release targets only 0.1.2 or must remain compatible with 0.1.1;
+4. preview and apply exact changes allowed by that compatibility strategy, then handle semantic migrations that require business context;
+5. rebuild and report static, artifact, isolated-runtime, and business-behavior evidence separately;
+6. commit or publish through the plugin repository's own process only when the developer explicitly requests it.
 
-1. inspect the plugin root, Harness checkout, package manager, and available DSH Doctor;
-2. analyze source, type imports, dependencies, manifest, client graph, patches, and build output;
-3. confirm whether the upgraded release targets only 0.1.2 or must remain compatible with 0.1.1;
-4. preview and apply code changes that are known to be equivalent under the selected compatibility strategy;
-5. use the new API owners to handle semantic changes that require understanding the plugin;
-6. rebuild the plugin and run static, build, and isolated runtime verification, covering both versions in dual-version mode;
-7. report the compatibility intent, changed files, remaining work, backups, and the verification level actually reached.
+`npx skills add` installs agent instructions only; it does not install DSH Doctor globally. The skill checks the local CLI and npm registry first. If the local version is unsuitable, it runs a pinned version through `npm exec` without changing the global installation.
 
-`npx skills add` installs agent instructions only. It does not install DSH Doctor globally. The skill checks the local CLI and npm registry first. If the local version is unsuitable, it uses a pinned `npx` version by default and does not change the global npm installation.
-
-After verification, the agent can follow the plugin repository's existing versioning and release process if requested. The skill itself does not commit or publish anything automatically.
+An upgrade request does not itself authorize dropping the old runtime. When compatibility intent is missing, the skill may perform read-only analysis but asks before migration writes, dependency installation, build, or runtime commands. Dual-version mode requires separate 0.1.1 and 0.1.2 evidence; one 0.1.2 smoke test is not dual-version proof.
 
 ## How it works
 
-DSH Doctor has three parts:
+DSH Doctor has three parts that constrain one another:
 
-- **Skill**: tells the agent which steps to follow, which actions need confirmation, and what to report;
-- **CLI**: scans the plugin, lists problems, changes deterministic code, and runs verification;
-- **Migration catalog**: records known package, API, Service, configuration, and behavior changes between the two DSH versions.
+- **Skill**: defines investigation steps, the compatibility decision, confirmation gates, and reporting standards for the agent;
+- **CLI**: provides read-only analysis, safe edits, diagnosis, baselines, recovery, and staged verification;
+- **Migration catalog**: stores exact DSH tags/commits and known package, symbol, Service, configuration, and behavior changes.
 
-The workflow is:
+The plugin migration workflow is:
 
 ```text
-analyze
-  → change deterministic code
+investigate the actual environment
+  → catalog-driven analysis
+  → reviewed-plan exact changes
   → agent handles semantic changes
-  → rebuild
-  → static verification
+  → build and artifact verification
   → temporary-profile installation and activation
-  → publish through the plugin's own release process
+  → plugin business-behavior verification
 ```
 
-The CLI only auto-edits migrations marked `exact` by the catalog. Ownership and lifecycle changes involving Session, Workspace, Conversation, and pending interactions are reported as `MIG_SEMANTIC_API_CHANGE`. The agent must handle them in the context of the plugin instead of applying a mechanical replacement.
-
-## Why versioned rules are needed
-
-DSH 0.1.2 changes more than package versions:
+DSH 0.1.2 changes more than package versions. Legacy owners such as `dsh-client-runtime` and `dsh-host-apiproxy` were split, while Session, Workspace, Conversation, pending interaction, and Settings capabilities moved to new controllers, UI packages, or Services. The CLI only auto-edits relationships marked `exact`; ownership, lifecycle, and business-call changes are reported as `MIG_SEMANTIC_API_CHANGE`.
 
-- `@deepseek-ai/dsh-client-runtime` was removed and has no single aggregate replacement;
-- store features moved to `dsh-client-store`;
-- Session, Workspace, Conversation, and pending interactions moved to separate controllers or UI packages;
-- `@deepseek-ai/dsh-host-apiproxy` was removed, so browser calls move to the appropriate business Remote;
-- client graph, platform externals, exports, and some profile patch targets also changed.
+With an exact Harness checkout, Doctor also verifies the commits behind the two catalog tags and compares entry ids in the target web profile. After the additional source interval has been investigated, `--target-version` can bind dependencies and runtime checks to a newer 0.1.2 target, but it does not extend the catalog's API claims.
 
-The migration catalog stores source/target tags and Git commits together with package, symbol, Service, and configuration rules. With `--harness-root`, the CLI verifies the commits behind both tags and compares entry ids in the target web profile. This gives the agent concrete version differences instead of making it guess the new API.
+## Core capabilities
 
-## Coverage
-
-| Area | How Doctor and the agent handle it |
+| Area | How it is handled |
 |---|---|
-| JS/TS imports, including type-only, aliased, and mixed imports | Analyzed with the TypeScript AST; symbols with a known equivalent can be rewritten |
-| Removed or added DSH packages | Checked in source and manifest; dependencies are updated only when no remaining reference blocks the change |
-| DSH/Cordis version ranges | Checks dependencies, devDependencies, and peerDependencies; existing peer ranges are not widened automatically |
-| Session, Workspace, Conversation, and other semantic changes | Reports the new owner and reason; the agent modifies the business code |
+| JS/TS imports and named re-exports | Uses the TypeScript AST for type-only, aliased, and mixed imports; rewrites only known equivalent symbols |
+| Removed packages and retained-package API changes | Checks source and manifest, preserves exports that still exist, and reports symbols that need semantic migration |
+| DSH/Cordis version ranges | Checks dependencies, devDependencies, peerDependencies, and resolved versions; existing peer ranges are not widened automatically |
 | `dsh.client` and client exports | Checks inject, external, platform, immediately, and `exports["./client"]` |
-| Harness patch targets | Compares old and new entries when an exact Harness checkout is available |
-| Build output | Scans `lib`, `dist`, `build`, and `out` for old APIs |
-| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; build or pack:check is required for artifact verification |
+| Harness patch targets | Compares old and new bundle entries when an exact Harness checkout is available |
+| Build output | Scans `lib`, `dist`, `build`, and `out` for source/artifact drift |
+| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; test/typecheck alone cannot establish artifact verification |
 | Installation and activation | Packs the real tarball and installs it into a fresh web profile under a temporary `DSH_HOME` |
-| UI and business behavior | Not decided by Doctor; the agent or developer runs plugin-specific checks |
+| Profile diagnosis | Composes bundle, profile, home, and CLI overlays in DSH order while preserving field provenance |
+| Update, quarantine, and removal | Verifies versions, dependencies, configuration layers, and dependents before producing an explicit operation plan; updates, persistent quarantine, and removal need explicit confirmation |
 
-Source analysis uses the TypeScript AST and is cross-checked against the manifest, client graph, and build output. A bundle without an old string does not prove that source code is compatible, and a successful compile does not prove that the published artifact or runtime is compatible.
+No legacy string in source, a successful compile, an installable tarball, and correct business behavior are different evidence levels. Doctor does not present one as proof of another.
 
-## Safety
+## Safety and evidence
 
 - `diagnose`, `migrate analyze`, and static verification are read-only and do not load or execute the inspected plugin;
-- `migrate apply` requires `--safe --plan-file`; preview only creates a new plan outside the plugin root, never overwrites an existing file, and persists the complete analysis plus every input-file hash; `--yes` applies only that same reviewed plan;
-- only `exact` migrations are auto-edited; semantic changes are not guessed;
-- SHA-256 is checked before writing, so a file changed after preview is rejected;
-- existing files receive timestamped backups and are replaced atomically through a temporary file;
-- build and runtime verification synchronize dependencies and execute plugin scripts, so they require explicit `--yes --install`; install lifecycle scripts are disabled and lockfile plus resolved-version evidence is recorded;
-- runtime verification uses a temporary `DSH_HOME`, not the normal `~/.dsh`;
-- JSON, baselines, and recovery snapshots redact plugin configuration and common secret/token/password/key fields;
-- global CLI installation, persistent quarantine, plugin removal, and publishing are never performed automatically by the skill.
-
-## Use the migration CLI manually
+- only migrations marked `exact` by the catalog can be changed automatically; semantic changes are not guessed mechanically;
+- `migrate apply` uses a reviewed plan outside the plugin root and binds the full analysis, actual target version, and every input-file hash;
+- SHA-256 is rechecked before writes, input drift rejects the apply, and existing files receive timestamped backups;
+- build/runtime commands require explicit confirmation and synchronize dependencies with lifecycle scripts disabled;
+- runtime verification uses a temporary `DSH_HOME` instead of installing into the developer's normal `~/.dsh`;
+- JSON, baselines, and recovery snapshots redact common secret, token, password, and key fields;
+- global CLI installation, persistent quarantine, plugin removal, commits, and publication are never implicit actions.
 
-Node.js `^22.19.0` or `>=24.0.0` is required.
+## Boundaries
 
-First confirm that the CLI contains the required migration:
+- Doctor can report a new API owner and migration reason, but it cannot replace understanding the plugin's business logic;
+- named imports and named re-exports from retained packages are recognized, while property access through namespace imports still needs manual investigation;
+- `runtime-verified` proves packaging, installation, and basic activation, not UI, Service lifecycle, or business-flow correctness;
+- DSH patches or prereleases outside the catalog require investigation of the additional source interval;
+- static diagnosis cannot establish dynamic Service dependencies or whether plugin-owned external data is safe to delete.
 
-```sh
-npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
-  dsh-doctor migrations list
-```
+## CLI quick reference
 
-### 1. Analyze
-
-```sh
-dsh-doctor migrate analyze /path/to/plugin \
-  --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.2 \
-  --harness-root /path/to/deepseek-harness \
-  --json
-```
-
-Analysis checks source, dependencies, manifest, client graph, patch targets, and existing build output without executing plugin code.
-
-### 2. Apply
-
-```sh
-# Preview
-dsh-doctor migrate apply /path/to/plugin --safe \
-  --plan-file /temporary/path/reviewed-migration-plan.json \
-  --harness-root /path/to/deepseek-harness --json
-
-# Write after confirmation
-dsh-doctor migrate apply /path/to/plugin --safe --yes \
-  --plan-file /temporary/path/reviewed-migration-plan.json \
-  --harness-root /path/to/deepseek-harness --json
-```
-
-The plan must stay outside the plugin root so it is not analyzed as plugin input. Apply checks the plan digest, every analyzed input, and each edit's before/after hashes; source, manifest, or other analyzed-input changes require a new reviewed plan. Deterministic dependency edits use catalog-owned Client/Host and peer/dev policies instead of inheriting the removed package's dependency section. Every changed file receives a backup.
-
-### 3. Verify
-
-```sh
-dsh-doctor migrate verify /path/to/plugin --level static \
-  --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level build --yes --install \
-  --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level runtime --yes --install \
-  --harness-root /path/to/deepseek-harness --json
-```
-
-| Level | What it checks |
-|---|---|
-| `static` | Rechecks source, manifest, client graph, patches, and artifacts |
-| `build` | Synchronizes and verifies target dependencies and the lockfile, then runs build/test scripts and scans output again |
-| `runtime` | After dependency and build gates, packs the real tarball and checks target DSH, installed package, bundle, and effective configuration in a temporary profile |
-
-Verification states are:
-
-```text
-analyzed → source-migrated → artifact-verified → runtime-verified
-```
-
-`runtime-verified` means that packing, installation, and basic activation passed. It does not replace real UI, Service lifecycle, and business-flow testing.
-
-## Diagnose DSH and installed plugins
-
-Global installation:
+Requires Node.js `^22.19.0` or `>=24.0.0`.
 
 ```sh
+# Global installation
 npm install --global @bruc3van/dsh-doctor
-dsh-doctor diagnose
-```
-
-Temporary use:
-
-```sh
-npx @bruc3van/dsh-doctor diagnose
-```
-
-The default target is `$DSH_HOME/profiles/web`, falling back to `~/.dsh`.
-
-```sh
-dsh-doctor diagnose
-dsh-doctor diagnose --json
-dsh-doctor diagnose --check-updates
-```
 
-Diagnosis composes configuration in DSH order:
-
-```text
-bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
+# Or run one pinned version without changing the global installation
+npm exec --yes --package=@bruc3van/dsh-doctor@<version> -- dsh-doctor --help
 ```
 
-It checks plugin versions and peers, Node engines, installation and lockfile state, bundles and patches, client contracts, duplicate mounts, higher-layer overrides, and DSH CLI/Harness version drift. Normal diagnosis does not use the network. Only `--check-updates` and recovery operations contact the npm registry.
-
-## Recovery operations
-
-```sh
-# Check and install the highest manifest-declared compatible version
-dsh-doctor recover @scope/plugin --action check-update
-dsh-doctor recover @scope/plugin --action update
-dsh-doctor recover @scope/plugin --action update --yes
-
-# Create a temporary quarantine overlay
-dsh-doctor recover @scope/plugin --action quarantine \
-  --output ./plugin-quarantine.yml
-
-# Persist it only after testing the temporary overlay
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
-
-# Removal is always separate
-dsh-doctor recover @scope/plugin --action remove
-dsh-doctor recover @scope/plugin --action remove --yes
-```
-
-Before quarantine or removal, Doctor checks entry ownership, configuration layers, direct dependencies, core bundles, lockfile state, manual mounts, and known client dependents. Static checks cannot prove dynamic Service dependencies or external data safety, so restart the profile and test its main features afterwards.
-
-You can also save and compare a baseline around an upgrade:
+| Command | Purpose |
+|---|---|
+| `dsh-doctor diagnose [--json] [--check-updates]` | Diagnose the current profile and installed plugins; normal diagnosis does not use the network |
+| `dsh-doctor migrations list` | List the exact migration catalogs bundled with the current CLI |
+| `dsh-doctor migrate analyze` / `apply` / `verify` | Analyze a migration, apply a reviewed plan, or run static/build/runtime verification |
+| `dsh-doctor baseline create` / `compare` | Save or compare a redacted before/after diagnostic baseline |
+| `dsh-doctor recover <package> --action <action>` | Check updates, generate/persist/roll back quarantine, or enter the separate removal workflow |
 
-```sh
-dsh-doctor baseline create
-dsh-doctor baseline compare
-```
+Use `dsh-doctor --help` for full options and confirmation requirements. Migration orchestration and semantic-investigation rules live in [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) and its references.
 
 ## Output and exit codes
 
-Text output supports Chinese and English. `--json` uses stable English codes and keeps redacted structured evidence.
+Text output supports Chinese and English. `--json` uses stable English codes and preserves redacted structured evidence.
 
 | Exit code | Meaning |
 |---|---|
-| `0` | No blocker remains, or the action completed and passed its verification |
-| `1` | Compatibility issues, semantic migration, or verification work remains |
-| `2` | Argument, environment, or action-execution failure |
+| `0` | No blocking error, or the operation completed and passed its verification level |
+| `1` | Compatibility issues, semantic migration work, or incomplete verification remains |
+| `2` | Argument, environment, or operation failure |
 
 ## Development
 
@@ -251,6 +147,6 @@ npm run check
 npm pack --dry-run
 ```
 
-Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery operations. CI tests Node.js `22.19` and `24` on macOS, Ubuntu, and Windows.
+Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery. CI runs on macOS, Ubuntu, and Windows with Node.js `22.19` and `24`.
 
 Local development, the skill, and the CLI never commit, tag, or publish automatically.