dsh-plugin-upgrade 2.0.0 → 2.0.2

package/lib/route.mjs

@@ -39,7 +39,11 @@ export const CORRIDORS = [
   },
 ]
 
-/** Accepts a corridor id ('legC'), a full span, or a bare mention of a line. */
+/**
+ * Accepts a corridor id ('legC'), a full span, or a bare mention of a line.
+ * @param {string} id - the `--span` value, a corridor id, or a bare line mention.
+ * @returns {Corridor | undefined} the matching corridor, or undefined when nothing matches.
+ */
 export function corridorById(id) {
   if (typeof id !== 'string' || id.length === 0) return undefined
   const wanted = id.trim().toLowerCase()
@@ -90,7 +94,11 @@ export function resolveCorridor(input = {}) {
   return CORRIDORS.find(c => c.id === 'legAB')
 }
 
-/** Reads `--span <value>` out of an argv array without touching the other flags. */
+/**
+ * Reads `--span <value>` out of an argv array without touching the other flags.
+ * @param {string[]} argv - the raw CLI argument list (no `node`/script prefix).
+ * @returns {string | undefined} the span value, or undefined when the flag is absent.
+ */
 export function spanFromArgv(argv) {
   const index = argv.findIndex(a => a === '--span')
   if (index >= 0 && typeof argv[index + 1] === 'string' && !argv[index + 1].startsWith('--')) return argv[index + 1]
@@ -98,7 +106,11 @@ export function spanFromArgv(argv) {
   return inline ? inline.slice('--span='.length) : undefined
 }
 
-/** Reads `--repo <value>` (or `--repo=<value>`) out of an argv array. */
+/**
+ * Reads `--repo <value>` (or `--repo=<value>`) out of an argv array.
+ * @param {string[]} argv - the raw CLI argument list (no `node`/script prefix).
+ * @returns {string | undefined} the repo path, or undefined when the flag is absent.
+ */
 export function repoFromArgv(argv) {
   const index = argv.findIndex(a => a === '--repo')
   if (index >= 0 && typeof argv[index + 1] === 'string') return argv[index + 1]
@@ -106,7 +118,11 @@ export function repoFromArgv(argv) {
   return inline ? inline.slice('--repo='.length) : undefined
 }
 
-/** Loads the catalog module the corridor points at. */
+/**
+ * Loads the catalog module the corridor points at.
+ * @param {Corridor} corridor - the corridor whose `catalog` path is imported.
+ * @returns {Promise<any>} the catalog module namespace (`main`, `SEAMS`, `render`, …). `any` is the honest type here: the specifier is a runtime string, so the namespace shape is not knowable statically.
+ */
 export async function loadCatalog(corridor) {
   return import(new URL(corridor.catalog, import.meta.url).href)
 }

package/lib/scan-0.1.6.mjs

@@ -75,7 +75,17 @@ const SCAN_EXT = /\.(ts|tsx|mts|cts|mjs|cjs|js|jsx|json|yml|yaml)$/
  * @property {(line: string) => boolean} [lineFilter]
  * @property {(lines: string[], i: number) => boolean} [windowFilter]
  * @property {(text: string, file: string) => boolean} [fileCheck]
- * @property {(text: string, file: string) => boolean} [downgradeIf]  file-level guard recognition
+ * @property {(text: string) => boolean} [downgradeIf]  file-level guard recognition
+ */
+
+/**
+ * @typedef {object} Hit
+ * @property {string} seam
+ * @property {string} severity
+ * @property {string} file
+ * @property {number} line
+ * @property {string} snippet
+ * @property {string} detail
  */
 
 /** @type {Seam[]} */
@@ -145,6 +155,12 @@ const STRUCTURED = new Set(['E2'])
  */
 export const CARD_ONLY = SEAMS.filter(s => s.test === null && !STRUCTURED.has(s.id)).map(s => s.id)
 
+/**
+ * Yield every scannable file under `dir`, depth-limited and read-only.
+ * @param {string} dir
+ * @param {number} [depth]
+ * @returns {Generator<string, void, void>}
+ */
 function* walk(dir, depth = 0) {
   if (depth > 8) return
   let ents
@@ -159,7 +175,12 @@ function* walk(dir, depth = 0) {
   }
 }
 
-/** 1-based line number of the first line containing `needle`, or 1. */
+/**
+ * 1-based line number of the first line containing `needle`, or 1.
+ * @param {string} text
+ * @param {string} needle
+ * @returns {number}
+ */
 function lineOf(text, needle) {
   const lines = text.split(/\r?\n/)
   const i = lines.findIndex(l => l.includes(needle))
@@ -172,6 +193,9 @@ function lineOf(text, needle) {
  * registration call after it. `register()` return values are flagged regardless
  * of whether they reach `ctx.effect()`: the card instructs the author to hand
  * them to the effect.
+ * @param {string} text
+ * @param {string} file
+ * @returns {Hit[]}
  */
 function checkAsyncApply(text, file) {
   const lines = text.split(/\r?\n/)
@@ -224,7 +248,7 @@ function checkAsyncApply(text, file) {
  * Scan one repo.
  * @param {string} repoDir
  * @param {{ seams?: string[] }} [options]
- * @returns {{ repo: string, scannedAt: string, files: number, hits: any[], bySeam: Record<string, number> }}
+ * @returns {{ repo: string, scannedAt: string, files: number, hits: Hit[], bySeam: Record<string, number> }}
  */
 export function scanRepo(repoDir, options = {}) {
   const wanted = options.seams && options.seams.length ? new Set(options.seams) : null
@@ -257,12 +281,17 @@ export function scanRepo(repoDir, options = {}) {
     }
     if (!wanted || wanted.has('E2')) hits.push(...checkAsyncApply(text, file))
   }
+  /** @type {Record<string, number>} */
   const bySeam = {}
   for (const h of hits) bySeam[h.seam] = (bySeam[h.seam] || 0) + 1
   return { repo: repoDir, scannedAt: new Date().toISOString(), files, hits, bySeam }
 }
 
-/** Human-readable rendering. Order derives from the catalog, never a copy. */
+/**
+ * Human-readable rendering. Order derives from the catalog, never a copy.
+ * @param {{ repo: string, files: number, hits: Hit[] }} report
+ * @returns {string}
+ */
 export function render(report) {
   const L = []
   L.push(`# scan-0.1.6 · ${report.repo}`)
@@ -286,7 +315,13 @@ export function render(report) {
   return L.join('\n')
 }
 
+/**
+ * CLI entry point.
+ * @param {string[]} argv
+ * @returns {number} the process exit code.
+ */
 export function main(argv) {
+  /** @type {{ repo: string, json: string | null, seams: string[] | null, quiet: boolean }} */
   const args = { repo: process.cwd(), json: null, seams: null, quiet: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-upgrade",
-  "version": "2.0.0",
-  "description": "Plugin-author upgrade skill for DeepSeek Harness: the merged version-locked 0.1.3-alpha.1 -> 0.1.5-rc.1 corridor card plus a zero-dependency seam scanner over one 20-seam catalog — leg A (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false green) and leg B (the removed bare `conversation` client slot, the sidebar textpreview -> documentpreview package rename, the stale-type-line false green, the new global main-panel model and usePanelInfo standard prop, the new `present` tool key, two new session event types, and the peer-range trap where >=0.1.2-rc.1 <0.2.0 alone rejects 0.1.5-rc.1) — packaged as a bundle skill and an npx CLI.",
+  "version": "2.0.2",
+  "description": "Plugin-author upgrade skill for DeepSeek Harness: one package, one corridor index - the scanner detects the caller peer band and routes to the matching closed corridor card (0.1.3-alpha.1 -> 0.1.5-rc.1 as legs A+B, and 0.1.5-rc.2 -> 0.1.6-alpha.2 as leg C), with a zero-dependency seam scanner shipped as a bundle skill and an npx CLI.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/PerryLink/dsh-plugin-upgrade.git"
@@ -77,14 +77,16 @@
     "compatibility": {
       "dshVersions": [
         "0.1.2-rc.1",
-        "0.1.5-rc.2"
+        "0.1.5-rc.2",
+        "0.1.6-alpha.2",
+        "0.1.7-alpha.2"
       ]
     },
     "capability": {
       "id": "plugin-upgrade",
       "kind": "service",
       "invocation": "ctx.skills.get('plugin-upgrade') resolves a complete SkillDefinition",
-      "expected": "the session skill catalog lists plugin-upgrade and the loaded body carries the merged 0.1.3-alpha.1 -> 0.1.5-rc.1 corridor card with a directory resourceBase"
+      "expected": "the session skill catalog lists plugin-upgrade and the loaded body carries the corridor index (lib/route.mjs) with both closed corridor cards - legAB 0.1.3-alpha.1 -> 0.1.5-rc.1 and legC 0.1.5-rc.2 -> 0.1.6-alpha.2 - over a directory resourceBase"
     },
     "evidence": {
       "install": null,
@@ -112,13 +114,13 @@
   "packageManager": "pnpm@11.7.0",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0",
+    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-skill": "0.1.5-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-skill": "0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "@types/node": "^22.0.0",
     "typescript": "^5.9.0"
   },
@@ -126,6 +128,7 @@
     "test": "node --test \"test/*.test.mjs\"",
     "check": "tsc -p tsconfig.check.json",
     "typecheck:ci": "tsc -p tsconfig.check.ci.json",
+    "typecheck:checkout": "tsc -p tsconfig.checkout.json --noEmit",
     "scan": "node scripts/scan-0.1.5.mjs",
     "check:readmes": "node scripts/check-readme-sync.mjs",
     "verify:self-contained": "node scripts/verify-self-contained.mjs",

package/scripts/verify-artifacts.mjs

@@ -61,10 +61,11 @@ try {
     failures.push(`packaged entry failed to import: ${detail.slice(0, 200)}`)
   }
 
-  // The packaged SKILL.md must keep its merged-corridor frontmatter.
+  // The packaged SKILL.md must keep its corridor-index frontmatter (both corridors).
   const skill = readFileSync(join(pkgRoot, 'skills/plugin-upgrade/SKILL.md'), 'utf8')
   if (!/^name:\s*plugin-upgrade\s*$/m.test(skill)) failures.push('packaged SKILL.md lost its frontmatter name')
-  if (!/^  corridor:\s*"0\.1\.3-alpha\.1 -> 0\.1\.5-rc\.1"\s*$/m.test(skill)) failures.push('packaged SKILL.md lost its merged corridor frontmatter')
+  if (!/^  corridors:\s*"legAB `0\.1\.3-alpha\.1 -> 0\.1\.5-rc\.1`/m.test(skill)) failures.push('packaged SKILL.md lost its legAB corridor frontmatter')
+  if (!/legC `0\.1\.5-rc\.2 -> 0\.1\.6-alpha\.2`/m.test(skill)) failures.push('packaged SKILL.md lost its legC corridor frontmatter')
 
   // cordis.patch.yml must stay a top-level YAML ARRAY of loader patch entries:
   // a mapping (`insert:` at column 0) mounts nothing and dsh reports

package/skills/plugin-upgrade/SKILL.md

@@ -1,18 +1,17 @@
 ---
 name: plugin-upgrade
-description: Migrate a DeepSeek Harness plugin repo across the merged 0.1.3-alpha.1 -> 0.1.5-rc.1 corridor. Runs a zero-dependency seam scanner over one 20-seam catalog — leg A (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false green) plus leg B (the removed bare `conversation` client slot, the sidebar textpreview -> documentpreview package rename, the stale-type-line false green, the new global main-panel model and usePanelInfo standard prop, the new `present` tool key, two new session event types, and the peer-range trap) — then walks the fix-and-verify loop with a real-host smoke, a resume round-trip for log writers and a real browser assertion for a client half.
-whenToUse: Use when a DSH plugin must reach the DeepSeek Harness 0.1.5-rc.1 line (or any host line in >=0.1.2-rc.1 <0.2.0) while keeping the older peer band working. Read leg A first if the peer band is below 0.1.5-alpha.1 or the target is 0.1.5-alpha.1; read leg B if the target is 0.1.5-rc.1 or the plugin has a client/browser half. Not for 0.1.1 -> 0.1.2 migrations (use the community convergence skill), not for a hop after 0.1.5-rc.1 (a new corridor is a new package) and not for the DSH user-facing upgrade/repair path.
+description: Migrate a DeepSeek Harness plugin repo across one of the two closed corridors this package carries. A zero-dependency seam scanner reads the target repo's declared band and routes to the matching corridor, then you walk the fix-and-verify loop. Corridor `legAB` (`0.1.3-alpha.1 -> 0.1.5-rc.1`, 20 seams) holds leg A (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false green) plus leg B (the removed bare `conversation` client slot, the sidebar textpreview -> documentpreview package rename, the stale-type-line false green, the new global main-panel model and usePanelInfo standard prop, the new `present` tool key, two new session event types, and the peer-range trap). Corridor `legC` (`0.1.5-rc.2 -> 0.1.6-alpha.2`, 5 seams `E1`-`E5`) holds the `agent/created` listener-throw chain, the post-`await` apply race, the removed `settings.plugin.item` slot and `SessionListState.current`, the removed `sessions.open/openSubagent/clear` client API, and the removed model literals.
+whenToUse: Use when a DSH plugin must reach the DeepSeek Harness 0.1.5-rc.1 line (or any host line in >=0.1.2-rc.1 <0.2.0), or the 0.1.6-alpha.2 line, while keeping the older peer band working. Read leg A if the peer band is below 0.1.5-alpha.1 or the target is 0.1.5-alpha.1; read leg B if the target is 0.1.5-rc.1 or the plugin has a client/browser half; read leg C if the target band is 0.1.6-alpha.2 (or the repo already sits on 0.1.5-rc.2). Not for 0.1.1 -> 0.1.2 migrations (use the community convergence skill) and not for the DSH user-facing upgrade/repair path. A hop past every corridor carried here is a new corridor, not a wider card.
 metadata:
-  corridor: "0.1.3-alpha.1 -> 0.1.5-rc.1"
-  legs: "leg A 0.1.3-alpha.1 -> 0.1.5-alpha.1 (S1-S10, M1) · leg B 0.1.5-alpha.1 -> 0.1.5-rc.1 (C1, C2, C4, C5, H1-H4, P1); leg B's C3 is leg A's M1"
-  host-baseline: "0.1.5-rc.1 (tag dsh-v0.1.5-rc.1 = 183f08e9c6dde7e36cd2318eaee70b0da08fb35e); leg A baseline 0.1.5-alpha.1 (tag dsh-v0.1.5-alpha.1 = 5dda764ed3aa172535a7967b06ff95d9cbfe536a, checkout 19d2e38480)"
-  evidence: "leg A: 2026-09-09 wave over 40 plugin repos · leg B: tag-range diff + public slot/service catalogs re-read 2026-09-10; family workspace sweep (15 repos with a client half, 8 slot keys). Both recorded in docs/EVIDENCE.md"
+  corridors: "legAB `0.1.3-alpha.1 -> 0.1.5-rc.1` (leg A S1-S10 + M1 · leg B C1, C2, C4, C5, H1-H4, P1; leg B's C3 is leg A's M1) · legC `0.1.5-rc.2 -> 0.1.6-alpha.2` (E1-E5, all error)"
+  host-baseline: "0.1.5-rc.1 (tag dsh-v0.1.5-rc.1 = 183f08e9c6dde7e36cd2318eaee70b0da08fb35e) for legAB; 0.1.6-alpha.2 (tag dsh-v0.1.6-alpha.2) for legC. leg A baseline 0.1.5-alpha.1 (tag dsh-v0.1.5-alpha.1 = 5dda764ed3aa172535a7967b06ff95d9cbfe536a, checkout 19d2e38480)"
+  evidence: "leg A: 2026-09-09 wave over 40 plugin repos · leg B: tag-range diff + public slot/service catalogs re-read 2026-09-10; family workspace sweep (15 repos with a client half, 8 slot keys) · leg C: 2026-09-19 sweep, dsh-v0.1.6-alpha.2. All recorded in docs/EVIDENCE.md (sections A, 1-10 and 11)"
   status: "published"
-  supersedes: "the version-locked packages dsh-plugin-upgrade (leg A) and dsh-plugin-upgrade-rc1 (leg B)"
+  supersedes: "the retired version-locked packages dsh-plugin-upgrade (leg A) and dsh-plugin-upgrade-rc1 (leg B), plus the never-published dsh-plugin-upgrade-016 corridor now folded in as leg C; the two published retired names stay on the registry, deprecated"
 user-invocable: true
 ---
 
-# Plugin upgrade · 0.1.3-alpha.1 → 0.1.5-rc.1 (one package, two legs)
+# Plugin upgrade · one package, one corridor index (two closed corridors)
 
 You are migrating **one plugin repository** across the merged DSH span `0.1.3-alpha.1 → 0.1.5-rc.1`. The goal is not "make typecheck pass" — it is "prove the plugin still works on the target host". Local gates are necessary but not sufficient, and two classes of failure survive a green gate: **stale-type false green** (the local gate compiles an old type line) and **silent non-mount** (the host drops a contribution with no error, no log line and no failed build). Read the leg that matches your peer band; both legs share one scanner and one catalog.
 
@@ -82,7 +81,8 @@ Both legs' frontmatter `whenToUse` were routing hints; they cannot both live in
 
 ## 5. Reference
 
-- `./references/v0.1.3-alpha.1-to-v0.1.5-rc.1.md` — the merged version card: preamble, **§1 Leg A** (10 seams with host path + commit + minimal fix + regression, and the 4 that no community PR covers yet), **§2 Leg B** (the from→to mapping, the `conversation` → `main.conversation` rewrite recipe, the boundary list), **§3 the 20-seam merged index**.
-- `./scripts/scan-0.1.5.mjs` — the detector (zero dependency, `file:line`, exit 1 on error-severity hits, `--seams` to filter). It is a thin wrapper over the package's own `lib/scan.mjs`, shipped inside the skill directory so relative paths resolve.
-- The package's own test suite (`node --test`) — synthetic bad/good fixtures **for both legs** (`fixtures/leg-a-*` for leg A, `fixtures/bad-repo` / `fixtures/good-repo` for leg B), a card↔catalog id-parity gate, and a live negative on a family repo.
-- `docs/EVIDENCE.md` — the command→output record behind every card claim (§A is leg A's provenance, §1–§10 the leg-B records).
+- `./references/v0.1.3-alpha.1-to-v0.1.5-rc.1.md` — the `legAB` version card: preamble, **§1 Leg A** (10 seams with host path + commit + minimal fix + regression, and the 4 that no community PR covers yet), **§2 Leg B** (the from→to mapping, the `conversation` → `main.conversation` rewrite recipe, the boundary list), **§3 the 20-seam merged index**.
+- `./references/v0.1.5-rc.2-to-v0.1.6-alpha.2.md` — the `legC` version card: what breaks across `0.1.5-rc.2 → 0.1.6-alpha.2` (all silent or runtime-only), the five-seam index `E1`–`E5` with evidence and fix/verify recipes, and the family-side facts. `CARD_ONLY = []` there: every `legC` seam has a detector.
+- `./scripts/scan-0.1.5.mjs` — the router plus detector: it resolves the corridor through `lib/route.mjs` (declared band, or `--span legAB|legC|span`) and hands the same argv to that corridor's own catalog `main()` — `lib/scan.mjs` for `legAB`, `lib/scan-0.1.6.mjs` for `legC`. Zero dependency, `file:line` output, exit `1` on error-severity hits, `--seams` to filter. The file name is historical; it ships inside the skill directory so relative paths resolve.
+- The package's own test suite (`node --test`) — synthetic bad/good fixtures **for both `legAB` legs** (`fixtures/leg-a-*` for leg A, `fixtures/bad-repo` / `fixtures/good-repo` for leg B), a card↔catalog id-and-severity parity gate **for each corridor**, and a live negative on a family repo.
+- `docs/EVIDENCE.md` — the command→output record behind every card claim: §A is leg A's provenance, §1–§10 the leg-B records, §11 the `legC` records.

package/skills/plugin-upgrade/references/v0.1.5-rc.2-to-v0.1.6-alpha.2.md

@@ -1,7 +1,7 @@
 # 版本卡 · `0.1.5-rc.2` → `0.1.6-alpha.2`
 
-> 本卡只对 **`0.1.5-rc.2 → 0.1.6-alpha.2`** 这一个封闭走廊负责。上一个走廊（`0.1.3-alpha.1 → 0.1.5-rc.1`）由 `dsh-plugin-upgrade-015` 承担；本走廊是一个**新包**（`dsh-plugin-upgrade-016`），五条接缝与旧目录零交集，两包不共享任何 SEAMS 清单。
-> 走廊方法论不变：走廊永不加宽，一个 hop 加一条接缝就是一个新包。
+> 本卡只对 **`0.1.5-rc.2 → 0.1.6-alpha.2`** 这一个封闭走廊负责。走廊方法论不变：**走廊永不加宽**——一条走廊一张卡、一套证据、一套 fixture 与一个回滚点；绝不把卡撑成「所有版本」。
+> **归属（2026-09-19 业主决定，已取代旧规则）**：本走廊与上一个走廊（`0.1.3-alpha.1 → 0.1.5-rc.1`，`legAB`）现在由**同一个包** `dsh-plugin-upgrade` 通过走廊索引（`lib/route.mjs`）承担，本卡是它的第二条索引行（`legC`）。旧措辞「一个 hop 加一条接缝就是一个新包」与 `dsh-plugin-upgrade-016` 这个名字都已作废，`-016` 从未发布到 registry。两条走廊**不共享 SEAMS 清单**——本卡五条接缝与旧目录零交集，各自有独立的目录模块与 parity 门禁。
 
 ## 1. 这个跨度里什么会坏（全部是**静默**或**运行时**失效）