Dsh Upgrade Audit

English | 简体中文

dsh-upgrade-audit

Audit every change observable by consumers outside the repository between two DSH versions, and produce the set of reports the user expects. The fixed form of this problem: relative to from, does to contain more changes or reverts? — "more changes" means externally visible breakage (removed exports, renamed wire error codes, data formats refused on read); "revert" means behavior present in from deliberately withdrawn by a revert within the interval. Both need evidence: commit messages and subagent summaries are claims — only conclusions drawn after reading both trees (source files or published packages) count as evidence.

External compatibility = everything observable by consumers outside the repository: the npm package public API (exports, types, signatures, dependency surface), the dsh CLI (commands, flags, profiles, config keys), the wire protocol (SDK JSON-RPC, remote gateway/BFF, ACP, hooks), session data on disk (JSONL logs, SQLite stores and their version guards), the model-visible surface (tool names/schemas, system-prompt output), and the Python SDK's expectations. Internal refactors are background, not findings — aggregate and count them.

Note: report language follows the user's language (see "Output contract" below); the existing sample report under examples/ is in English by historical convention.

Phase 0 — Parse input and choose a mode

Input: two version identifiers (accepts 0.1.2-alpha.2, dsh-v0.1.2-alpha.2, dist-tags alpha/latest/next). Choose the analysis mode by specificity, high to low:

1. Context path — the user named a deepseek-harness checkout directory in the message. Verify: root package.json + packages/ + AGENTS.md all present.
2. DSH_SOURCE_PATH environment variable — verify the same way. (Optional DSH_NPM_REGISTRY overrides the npm registry.)
3. CWD heuristic — the current directory is itself a deepseek-harness checkout (marked the same way).
4. npm mode — none of the above (the default path for third-party repos): download the published packages of the two versions for analysis.

Source mode audits git tags; npm mode audits published artifacts. The audit core (recon surface, classification, verification, reporting) is shared; only the materialization and some evidence sources differ. Know npm mode's boundaries before choosing it: the npm version set ≠ the git tag set (e.g. 0.1.2-alpha.1 is tagged but was never published — the materialization script exits with the published list, so present the gap to the user instead of silently substituting a version pair); the CLI closure does not include every publishable package (the SQLite persistence backend is not a CLI dependency; the script installs it as a supplement package).

Output contract

Everything lands in one directory: tmp/<fromNorm>-to-<toNorm>/ (normalization: strip dsh-v, strip dots in the prerelease segment — dsh-v0.1.2-alpha.1 → 0.1.2alpha1). Source mode creates it inside the checkout (gitignored); npm mode creates it inside the current project. If the target directory already exists it is most likely a previously hand-made report — stop and ask first; do not overwrite.

Report language follows the user's language (examples/ existing report is in English, a historical convention — not mandatory).

Phase 1 — Materialize the two trees

Source mode — verify purity first; a merge base that is not from itself means base drift: stop and report, never diff against a moving baseline:

git merge-base <from> <to>   # must equal <from>'s commit
node <skill-dir>/scripts/gen-artifacts.mjs <from> <to> tmp/<pair>

npm mode:

node <skill-dir>/scripts/materialize-npm.mjs <from> <to> tmp/<pair>

The script resolves both versions against the registry (missing → exit 1 with the published list — present the gap to the user), installs the @deepseek-ai/dsh dependency closure plus the SQLite supplement package into a/ and b/ with --ignore-scripts, produces manifest-diff.txt from per-package manifest diffs for every @deepseek-ai/* package, and enriches from the public GitHub repository (commits.txt, reverts.txt) — so revert detection works even without a source checkout.

Size the recon from the stats output: ≤40 non-merge commits → run the recon-surface checklist inline; 40–250 → merge 3–4 facades; more → all six facades. For density comparison, open the previous pair's commits.txt — the immediately preceding pair in chronological order, never just the newest directory in tmp/.