@krapwoo/ds-viewer 0.2.0 → 0.4.0

package/dist/cli/explain.js

@@ -0,0 +1,151 @@
+import path from 'node:path';
+import { readStaticPages } from "./staticPage.js";
+import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
+import { resolveGlob } from "./glob.js";
+import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
+import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
+function placeholderItem(item) {
+    return { key: item.key, name: item.name, node: null, group: item.group };
+}
+/** A throwaway `SectionDef` built from a `StaticPage` (Task 3) — every specimen's `node` is `null`
+ *  (design §4: specimen nodes are never evaluated), since none of the layout functions below ever
+ *  look at it; only the counts/keys/sizes they do look at are carried over. Every field Task 3
+ *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill` —
+ *  an earlier draft dropped these four, so `explain` reported different geometry than the real
+ *  viewer for any page that set one of them (25 kit pages set `itemsFill`; every `kit-host`
+ *  Viewer page sets `hide`). */
+function toSectionDef(page) {
+    const comparison = page.comparison && {
+        rowLabel: page.comparison.rowLabel ?? '',
+        columnLabel: page.comparison.columnLabel ?? '',
+        rows: page.comparison.rows.prop !== undefined ? { prop: page.comparison.rows.prop, items: page.comparison.rows.items } : page.comparison.rows.items,
+        columns: page.comparison.columns.prop !== undefined ? { prop: page.comparison.columns.prop, items: page.comparison.columns.items } : page.comparison.columns.items,
+        cells: [],
+        size: page.comparison.size,
+    };
+    return {
+        id: resolvePageId(page, page.file),
+        description: '',
+        path: page.file,
+        tokenGallery: page.tokenGallery,
+        fullWidthLabel: page.fullWidthLabel,
+        specimenSize: page.specimenSize,
+        previewWidths: page.previewWidths,
+        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, items: page.variantsItems.map(placeholderItem) } : undefined,
+        states: page.statesItems ? { itemsFill: page.statesItemsFill, items: page.statesItems.map(placeholderItem) } : undefined,
+        comparison,
+        render: page.hasRender ? () => null : undefined,
+        hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
+    };
+}
+function explainBlock(block) {
+    if (block.kind === 'grid') {
+        const rows = axisItems(block.comparison.rows).length;
+        const columns = axisItems(block.comparison.columns).length;
+        const limit = gridColumnLimit(block.size);
+        return {
+            kind: 'grid', title: block.title,
+            reason: `${rows} rows × ${columns} columns (${block.size}); ${columns} of ${limit} max ${block.size} columns used — ` +
+                `${columns <= limit ? 'fits' : 'does NOT fit'} a 1280px laptop.`,
+        };
+    }
+    if (block.kind === 'list') {
+        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size);
+        return {
+            kind: 'list', title: block.title,
+            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
+                (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.',
+        };
+    }
+    if (block.kind === 'grouped') {
+        return { kind: 'grouped', title: block.title, reason: `${block.groups.length} variant row(s), each with its own configurations.` };
+    }
+    if (block.kind === 'preview') {
+        const widths = block.widths === 'full' ? 'full width' : `${block.widths.join('/')}px`;
+        return { kind: 'preview', title: block.title, reason: `render() content at ${widths}.` };
+    }
+    return { kind: 'empty', title: block.title, reason: block.message };
+}
+/** Mirrors `native/catalog/SectionBlock.tsx`'s own `blockWidth` helper: a list block's width is its
+ *  own natural, content-hugging width (`listGeometry`'s `containerWidth`) — the real viewer only
+ *  ever moves a *second* block beside a *first* one when that first block doesn't already fill the
+ *  whole row, so `choosePlacement` only reads `first.width` (never `second.width`) — but it's
+ *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
+function toPlacementBlock(block, height, available) {
+    if (block.kind === 'list') {
+        return { kind: 'list', height, itemCount: block.items.length, size: block.size, width: listGeometry(block.items.length, available, block.size).containerWidth };
+    }
+    return { kind: block.kind, height };
+}
+/** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
+ *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
+ *  decision — undefined when no page resolves to that id. */
+export function explainPage(config, pageId, options = {}) {
+    // Same exclusion `cli/doctor.ts`'s `runDoctor` applies (mirroring `sync`) — an excluded folder's
+    // page should never resolve here either.
+    const excluded = new Set((config.exclude ?? []).flatMap((pattern) => resolveGlob(config.projectRoot, pattern)));
+    const componentFolders = [
+        ...new Set(config.components
+            .flatMap((pattern) => resolveGlob(config.projectRoot, pattern))
+            .filter((file) => !excluded.has(file))
+            .map((file) => path.dirname(file))),
+    ];
+    const pageFiles = discoverAllPageFiles({ componentFolders, standalonePageGlobs: config.pages ?? [], projectRoot: config.projectRoot });
+    const page = readStaticPages(pageFiles).find((p) => resolvePageId(p, p.file) === pageId);
+    if (!page)
+        return undefined;
+    // Important finding 4 (Fable's review): a page whose layout data isn't a literal (or that has a
+    // syntax error) must never be explained from partial/empty data — design §4 requires `explain`
+    // to never drift from what the viewer actually renders.
+    if (!page.checkable)
+        return { pageId, notCheckable: true, blocks: [] };
+    const def = toSectionDef(page);
+    const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
+    const explained = blocks.map(explainBlock);
+    let placement;
+    if (blocks.length === 2) {
+        if (options.heights) {
+            const [firstHeight, secondHeight] = options.heights;
+            const decision = choosePlacement({
+                available: MATRIX_LAYOUT.laptopContentWidth,
+                gap: CATALOG_LAYOUT.blockGap,
+                first: toPlacementBlock(blocks[0], firstHeight, MATRIX_LAYOUT.laptopContentWidth),
+                second: toPlacementBlock(blocks[1], secondHeight, MATRIX_LAYOUT.laptopContentWidth),
+            });
+            placement = {
+                decision,
+                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${MATRIX_LAYOUT.laptopContentWidth}px content width): ${decision}.`,
+            };
+        }
+        else {
+            placement = {
+                decision: 'decided-in-viewer',
+                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. Pass --heights <first>,<second> to check it here.",
+            };
+        }
+    }
+    return { pageId, blocks: explained, placement };
+}
+export function formatExplain(result) {
+    if (result.notCheckable) {
+        return `${result.pageId}\n\nPage not statically checkable — some of its layout data is not a literal doctor can read.`;
+    }
+    const lines = [result.pageId, ''];
+    for (const block of result.blocks) {
+        lines.push(block.title);
+        lines.push(`  ${block.reason}`);
+        lines.push('');
+    }
+    if (result.placement) {
+        lines.push('Placement');
+        lines.push(`  ${result.placement.reason}`);
+    }
+    return lines.join('\n').replace(/\n+$/, '');
+}
+/** `"80,300"` → `[80, 300]`; undefined for anything else (not exactly two positive numbers). */
+export function parseHeights(raw) {
+    const parts = raw.split(',').map((part) => Number(part.trim()));
+    if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n) || n <= 0))
+        return undefined;
+    return [parts[0], parts[1]];
+}

package/dist/cli/githubAction.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { detectPackageManager } from "./packageManager.js";
+// Design §4 "GitHub Action" + §5's lockfile-detection assumption. `checkout`/`setup-node` pins
+// reused verbatim from this repository's own `.github/workflows/ci.yml` (Global Constraints);
+// `pnpm/action-setup` is the one new SHA this plan resolves (`gh api
+// repos/pnpm/action-setup/git/refs/tags/v6.1.0`, dereferenced to its commit). `node-version: '20'`
+// matches the package's own published `engines` floor (`>=20.19.0`): a user's project only ever
+// runs the compiled `dist/cli/main.js` via `npx ds-viewer`, which needs no type-stripping (unlike
+// this repo's own CI, which type-strips its *source* and therefore needs Node 22).
+// Errata #5: `pnpm/action-setup` needs an explicit pnpm version — it has no lockfile to infer one
+// from. Read the project's own `packageManager` field (`"pnpm@9.1.0"`) when present; otherwise
+// default to 10, matching the pin's own major version line.
+function pnpmVersion(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return '10';
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const match = packageJson.packageManager?.match(/^pnpm@(\d+)/);
+    return match ? match[1] : '10';
+}
+// Important finding 6 (Fable's review): Yarn 1 (still the common Expo lockfile) has no
+// `--immutable` flag — its equivalent is `--frozen-lockfile`. Yarn Berry needs `corepack enable`
+// first, since `actions/setup-node` ships Yarn 1 on `ubuntu-latest`.
+function installStep(projectRoot) {
+    const pm = detectPackageManager(projectRoot);
+    if (pm === 'pnpm') {
+        return `      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0\n        with:\n          version: ${pnpmVersion(projectRoot)}\n      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0\n        with:\n          node-version: '20'\n      - run: pnpm install --frozen-lockfile\n`;
+    }
+    const setupNode = `      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0\n        with:\n          node-version: '20'\n`;
+    if (pm === 'yarn-classic')
+        return `${setupNode}      - run: yarn install --frozen-lockfile\n`;
+    if (pm === 'yarn-berry')
+        return `${setupNode}      - run: corepack enable\n      - run: yarn install --immutable\n`;
+    // `package-lock.json`, or no lockfile at all (a fresh project before its first commit) — `npm
+    // ci` is npm's own documented behavior for the latter: it installs from `package.json` and
+    // writes a fresh lockfile, exactly like a plain `npm install` would.
+    return `${setupNode}      - run: npm ci\n`;
+}
+function workflowContent(projectRoot) {
+    return `name: DS Viewer
+
+on:
+  pull_request:
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+${installStep(projectRoot)}      - run: npx ds-viewer doctor --ci
+`;
+}
+/** Design §4 "GitHub Action", §1 Ownership: written once, never overwritten — a user's own edits
+ *  to this file (or a differently-named workflow they wrote instead) are never touched again. The
+ *  install step is picked from whichever lockfile is present *right now*, at `init` time — never
+ *  re-picked later, since this function never runs again once the file exists. */
+export function ensureGithubAction(projectRoot) {
+    const workflowPath = path.join(projectRoot, '.github', 'workflows', 'ds-viewer.yml');
+    if (existsSync(workflowPath))
+        return [];
+    mkdirSync(path.dirname(workflowPath), { recursive: true });
+    writeFileSync(workflowPath, workflowContent(projectRoot));
+    return [workflowPath];
+}

package/dist/cli/init.js

@@ -4,6 +4,9 @@ import { createInterface } from 'node:readline/promises';
 import { execFileSync } from 'node:child_process';
 import { preflight } from "./preflight.js";
 import { detectComponentFolders, detectTokenFiles } from "./detect.js";
+import { ensureAgentsFileSection } from "./agentsFile.js";
+import { ensureGithubAction } from "./githubAction.js";
+import { readOwnVersion } from "./packageVersion.js";
 async function promptConfirm(message) {
     // A closed, non-interactive stdin (CI, piped npx) would reject `question` with an AbortError;
     // say how to proceed instead.
@@ -35,8 +38,7 @@ function packageRoot() {
     throw new Error("Could not find @krapwoo/ds-viewer's own package.json to read its version.");
 }
 function ownVersion() {
-    const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
-    return pkg.version;
+    return readOwnVersion(packageRoot());
 }
 /** Detects the existing indent of a JSON file's first indented line, so rewriting it (e.g.
  *  `package.json` below) doesn't reformat the user's own indentation style. Falls back to two
@@ -104,8 +106,8 @@ export async function initExistingProject(projectRoot, options = {}) {
     return { messages, written };
 }
 /** Design §2, "Both paths then write what is missing": `ds-viewer.config.ts` is written by each
- *  path separately (its contents differ), but the package script, the devDependency entry, and the
- *  `.gitignore` entry are identical either way. */
+ *  path separately (its contents differ), but the package script, the devDependency entry, the
+ *  `.gitignore` entry, and (from 0.3) the `AGENTS.md` section are identical either way. */
 function ensureSharedProjectFiles(projectRoot) {
     const written = [];
     const packageJsonPath = path.join(projectRoot, 'package.json');
@@ -134,6 +136,8 @@ function ensureSharedProjectFiles(projectRoot) {
         writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
         written.push(gitignorePath);
     }
+    written.push(...ensureAgentsFileSection(projectRoot));
+    written.push(...ensureGithubAction(projectRoot));
     return written;
 }
 const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];
@@ -204,7 +208,7 @@ export default defineConfig({
   tokens: ['${kitRoot}/tokens/index.ts'],
   pages: ['${kitRoot}/pages/*.catalog.tsx'],
   groupOrder: ${JSON.stringify(KIT_GROUP_ORDER)},
-  starterKit: { version: '${starterKitVersion}' },
+  starterKit: { version: '${starterKitVersion}', root: '${kitRoot}' },
 });
 `;
 }

package/dist/cli/kitDiff.js

@@ -0,0 +1,132 @@
+// cli/kitDiff.ts
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { resolveKitRoot } from "./kitRoot.js";
+function listFilesRecursively(dir, prefix = '') {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...listFilesRecursively(path.join(dir, entry.name), relative));
+        else if (entry.isFile())
+            out.push(relative);
+    }
+    return out;
+}
+function installedKitDir(projectRoot) {
+    return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'starter-kit');
+}
+/** Design §5 "Starter-kit changes": every kit file on both sides, compared by exact content —
+ *  never applied, only reported. `undefined` from `resolveKitRoot` (no `starterKit` configured at
+ *  all) means "not a kit project", not an error: `[]` either way (Task 9 reads this directly for
+ *  its `kitFilesDiffering` count, which is simply 0 for a non-kit project).
+ *
+ *  `compareDir` overrides the "other side" of the comparison — the currently-*installed* kit
+ *  (`node_modules/@krapwoo/ds-viewer/starter-kit`) by default, used by `kit diff`; `buildUpdatePlan`
+ *  (M4, Fable correction pass) instead passes the *downloaded target version's* own extracted
+ *  `starter-kit/`, matching its own copy ("differ from {latest}'s kit") and design §5. */
+export function listKitFileDiffs(config, compareDir) {
+    const kitRoot = resolveKitRoot(config);
+    if (!kitRoot)
+        return [];
+    const userDir = path.join(config.projectRoot, kitRoot);
+    const installedDir = compareDir ?? installedKitDir(config.projectRoot);
+    const userFiles = new Set(listFilesRecursively(userDir));
+    const installedFiles = new Set(listFilesRecursively(installedDir));
+    const diffs = [];
+    for (const relativePath of [...new Set([...userFiles, ...installedFiles])].sort()) {
+        if (userFiles.has(relativePath) && !installedFiles.has(relativePath)) {
+            diffs.push({ relativePath, status: 'user-only' });
+        }
+        else if (!userFiles.has(relativePath) && installedFiles.has(relativePath)) {
+            diffs.push({ relativePath, status: 'kit-only' });
+        }
+        else {
+            const same = readFileSync(path.join(userDir, relativePath), 'utf8') === readFileSync(path.join(installedDir, relativePath), 'utf8');
+            diffs.push({ relativePath, status: same ? 'identical' : 'modified' });
+        }
+    }
+    return diffs;
+}
+/** A plain LCS line diff, `-`/`+`/`  ` (two-space) prefixed — not a strict POSIX unified diff (no
+ *  `@@` hunk headers, no surrounding-context trimming): design §5 says `kit diff` "shows" the two
+ *  files against each other, and every kit file is already small enough that a full-file line diff
+ *  reads more plainly than hunk-trimmed context would. */
+export function diffLines(a, b) {
+    const aLines = a.split('\n');
+    const bLines = b.split('\n');
+    const m = aLines.length;
+    const n = bLines.length;
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i -= 1) {
+        for (let j = n - 1; j >= 0; j -= 1) {
+            lcs[i][j] = aLines[i] === bLines[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (aLines[i] === bLines[j]) {
+            out.push(`  ${aLines[i]}`);
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            out.push(`- ${aLines[i]}`);
+            i += 1;
+        }
+        else {
+            out.push(`+ ${bLines[j]}`);
+            j += 1;
+        }
+    }
+    while (i < m) {
+        out.push(`- ${aLines[i]}`);
+        i += 1;
+    }
+    while (j < n) {
+        out.push(`+ ${bLines[j]}`);
+        j += 1;
+    }
+    return out;
+}
+/** `npx ds-viewer kit diff <Component>` (design §5). `installed` is always the "before" (`-`) side
+ *  and `yours` the "after" (`+`) side — the installed kit is what shipped; the user's file is what
+ *  they changed it to. Exit code 1 only for a usage problem (no kit configured, unknown component);
+ *  a real diff is informational and exits 0. */
+export function runKitDiffCommand(config, componentName) {
+    const kitRoot = resolveKitRoot(config);
+    if (!kitRoot)
+        return { output: 'This project has no starter kit configured (no "starterKit" in ds-viewer.config.ts).', exitCode: 1 };
+    const diffs = listKitFileDiffs(config).filter((d) => d.relativePath.startsWith(`components/${componentName}/`));
+    if (diffs.length === 0) {
+        return { output: `No kit files found for "${componentName}" under ${kitRoot}/components/${componentName}/.`, exitCode: 1 };
+    }
+    const installedDir = installedKitDir(config.projectRoot);
+    const userDir = path.join(config.projectRoot, kitRoot);
+    const lines = [];
+    let anyDiff = false;
+    for (const diff of diffs) {
+        if (diff.status === 'identical')
+            continue;
+        anyDiff = true;
+        lines.push(`--- ${diff.relativePath} (installed kit)`, `+++ ${diff.relativePath} (yours)`);
+        if (diff.status === 'kit-only') {
+            lines.push('(only in the installed kit — you have not copied this file)', '');
+            continue;
+        }
+        if (diff.status === 'user-only') {
+            lines.push('(only in your project — not part of the installed kit)', '');
+            continue;
+        }
+        const installedContent = readFileSync(path.join(installedDir, diff.relativePath), 'utf8');
+        const userContent = readFileSync(path.join(userDir, diff.relativePath), 'utf8');
+        lines.push(...diffLines(installedContent, userContent), '');
+    }
+    if (!anyDiff)
+        return { output: `${componentName}'s kit files match the installed kit exactly.`, exitCode: 0 };
+    return { output: lines.join('\n'), exitCode: 0 };
+}

package/dist/cli/kitRoot.js

@@ -0,0 +1,20 @@
+// cli/kitRoot.ts
+import path from 'node:path';
+import { globBaseFolder } from "./glob.js";
+/** Design decision 6 (brief): `starterKit.root` when the config sets it (every config `init --new`
+ *  writes from 0.4 on); otherwise inferred from the first `components` glob's base folder's own
+ *  parent — `globBaseFolder('src/ds/components/*\/index.ts')` is `'src/ds/components'`, and the kit
+ *  root is always that folder's parent, since the starter kit's own fixed internal layout (design
+ *  §1) is `<kit root>/components`, `<kit root>/tokens`, `<kit root>/icons`. Returns `undefined` for
+ *  a project with no `starterKit` at all — an existing (non-kit) project has no kit root to find,
+ *  and `kit diff`/`update`'s kit-diff count both treat that as "0 kit files, nothing to compare." */
+export function resolveKitRoot(config) {
+    if (!config.starterKit)
+        return undefined;
+    if (config.starterKit.root)
+        return config.starterKit.root;
+    if (config.components.length === 0)
+        return undefined;
+    const base = globBaseFolder(config.components[0]);
+    return path.dirname(base).split(path.sep).join('/');
+}

package/dist/cli/main.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveConfig } from "./config.js";
 import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
 import { dev } from "./dev.js";
 import { sync } from "./sync.js";
+import { formatHuman, runDoctor, toDoctorJson } from "./doctor.js";
+import { explainPage, formatExplain, parseHeights } from "./explain.js";
+import { readOwnVersion } from "./packageVersion.js";
+import { checkForUpdate, isUpdateCheckEnabled } from "./updateCheck.js";
+import { runKitDiffCommand } from "./kitDiff.js";
+import { formatMigrateHuman, runMigrate } from "./migrate.js";
+import { runUpdate } from "./update.js";
 const USAGE = `Usage: ds-viewer <command>
 
 Commands:
@@ -16,24 +22,34 @@ Commands:
            --yes           accept the detected components and tokens without asking (--existing only)
   sync     Regenerate the component, props, token, and page data from source
   dev      Sync, then serve the catalog on a local web address and keep it current as files change
+           [--port <number>]
+           Pin the catalog (and its update endpoint's restart handoff) to this port
+  doctor   Check every page for drift and coverage gaps
+           --json          print the machine-readable report instead
+           --ci            exit 1 when any error was found (never on a warning alone)
+  explain <Page>
+           Print why a page's specimens are laid out the way they are
+           --heights <first>,<second>  check side-by-side placement with these measured heights
+           --json          print the machine-readable report instead
+  kit diff <Component>
+           Show the user's kit file(s) for <Component> against the installed kit's copy
+  migrate --from <version>
+           Run every migration introduced after <version>
+           --dry-run       report the changes without writing them
+           --json          print the machine-readable report instead
+  update  [--dry-run]     Build and show the update plan; stop without installing
+          [--yes]         Skip the confirmation prompt
+          [--force]       Install even if planned files have uncommitted changes
 
 Options:
   -h, --help     Show this help
   -v, --version  Show the installed version`;
-/** Walks up from this file (cli/ in source, dist/cli/ when installed) to the package's own package.json. */
 function packageVersion() {
-    let dir = path.dirname(fileURLToPath(import.meta.url));
-    while (true) {
-        const candidate = path.join(dir, 'package.json');
-        if (existsSync(candidate)) {
-            const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
-            if (pkg.name === '@krapwoo/ds-viewer' && pkg.version)
-                return pkg.version;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return 'unknown';
-        dir = parent;
+    try {
+        return readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
+    }
+    catch {
+        return 'unknown';
     }
 }
 /** `--kit-root`'s raw CLI value, normalized to a project-root-relative, forward-slash path — or an
@@ -95,6 +111,46 @@ export async function runInit(projectRoot, rest, options = {}) {
         ? initNewProject(projectRoot, { kitRoot, installer: options.installer })
         : initExistingProject(projectRoot, { yes: rest.includes('--yes'), confirm: options.confirm });
 }
+/** Pulled out of `main()` for the same reason `runInit` was in 0.1/0.2 (Fable's review): testable
+ *  without spawning a process. `--ci`'s exit code is read from `runDoctor`'s own `exitCode` — a
+ *  plain `doctor` (no `--ci`) always returns 0 here regardless of errors found. */
+export async function runDoctorCommand(projectRoot, rest, options = {}) {
+    const config = resolveConfig(projectRoot);
+    const result = runDoctor(config);
+    // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when
+    // `updateCheck` is otherwise enabled; `result.update` stays `null`.
+    if (!rest.includes('--ci') && isUpdateCheckEnabled(config, options.env ?? process.env)) {
+        const ownVersion = readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
+        const updateResult = await (options.checkForUpdate ?? checkForUpdate)(ownVersion);
+        if (updateResult) {
+            result.update = { current: updateResult.current, latest: updateResult.latest, breaking: updateResult.breaking };
+        }
+    }
+    // The human formatter (`formatHuman`, unchanged) knows nothing about updates — it predates this
+    // release and every other release's own doctor output; appending one line here, rather than
+    // threading `update` through `formatHuman`'s own signature, keeps that function's existing
+    // tests untouched (Minor finding, Fable correction pass: the human path previously said nothing
+    // about an update `--json` already reported).
+    const updateLine = result.update ? `\nUpdate available: ${result.update.current} → ${result.update.latest}` : '';
+    const output = rest.includes('--json') ? JSON.stringify(toDoctorJson(result), null, 2) : `${formatHuman(result)}${updateLine}`;
+    return { output, exitCode: rest.includes('--ci') ? result.exitCode : 0 };
+}
+/** Same "testable without spawning" shape as `runDoctorCommand` above. */
+export function runExplainCommand(projectRoot, pageId, rest) {
+    if (!pageId)
+        return { output: 'Usage: ds-viewer explain <Page> [--heights <first>,<second>] [--json]', exitCode: 1 };
+    const heightsIndex = rest.indexOf('--heights');
+    const heightsRaw = heightsIndex !== -1 ? rest[heightsIndex + 1] : undefined;
+    const heights = heightsRaw ? parseHeights(heightsRaw) : undefined;
+    if (heightsRaw && !heights) {
+        return { output: `--heights must be two comma-separated numbers, e.g. --heights 420,610 (got "${heightsRaw}")`, exitCode: 1 };
+    }
+    const config = resolveConfig(projectRoot);
+    const result = explainPage(config, pageId, { heights });
+    if (!result)
+        return { output: `No page named "${pageId}" was found.`, exitCode: 1 };
+    return { output: rest.includes('--json') ? JSON.stringify(result, null, 2) : formatExplain(result), exitCode: 0 };
+}
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const projectRoot = process.cwd();
@@ -122,9 +178,61 @@ async function main() {
         console.log(`Synced ${result.componentCount} components, ${result.pageCount} pages.`);
         return;
     }
+    if (command === 'doctor') {
+        const { output, exitCode } = await runDoctorCommand(projectRoot, rest);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
+    if (command === 'explain') {
+        const [pageId, ...explainRest] = rest;
+        const { output, exitCode } = runExplainCommand(projectRoot, pageId, explainRest);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
+    if (command === 'kit') {
+        const [sub, componentName] = rest;
+        if (sub !== 'diff' || !componentName) {
+            console.error(`Usage: ds-viewer kit diff <Component>\n\n${USAGE}`);
+            process.exitCode = 1;
+            return;
+        }
+        const config = resolveConfig(projectRoot);
+        const { output, exitCode } = runKitDiffCommand(config, componentName);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
+    if (command === 'migrate') {
+        const fromIndex = rest.indexOf('--from');
+        const fromVersion = fromIndex !== -1 ? rest[fromIndex + 1] : undefined;
+        if (!fromVersion) {
+            console.error(`Usage: ds-viewer migrate --from <version> [--dry-run] [--json]\n\n${USAGE}`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = runMigrate(projectRoot, fromVersion, { dryRun: rest.includes('--dry-run') });
+        console.log(rest.includes('--json') ? JSON.stringify(result, null, 2) : formatMigrateHuman(result));
+        return;
+    }
+    if (command === 'update') {
+        const config = resolveConfig(projectRoot);
+        const result = await runUpdate(config, { dryRun: rest.includes('--dry-run'), yes: rest.includes('--yes'), force: rest.includes('--force') });
+        console.log(result.output);
+        if (result.exitCode)
+            process.exitCode = result.exitCode;
+        return;
+    }
     if (command === 'dev') {
         const config = resolveConfig(projectRoot);
-        await dev(config);
+        const portIndex = rest.indexOf('--port');
+        const parsedPort = portIndex !== -1 ? Number(rest[portIndex + 1]) : undefined;
+        const pinnedPort = parsedPort !== undefined && Number.isInteger(parsedPort) ? parsedPort : undefined;
+        await dev(config, { pinnedPort });
         return;
     }
     console.error(`Unknown command "${command}".\n\n${USAGE}`);

package/dist/cli/migrate.js

@@ -0,0 +1,30 @@
+// cli/migrate.ts
+import { migrationsAfter } from "./migrations/index.js";
+import { compareVersions, parseVersion } from "./semver.js";
+/** Design §5 "`npx ds-viewer update`" step 4, and the endpoint's own call to the newly-downloaded
+ *  version's `migrate --from <installed> --dry-run --json` (Task 9's plan step). Runs every
+ *  applicable migration in order, concatenating each one's reported changes — one broken migration
+ *  still lets the rest report (design's Error-handling rule), though in practice a migration that
+ *  throws here means the whole upgrade fails loudly, since there is no "partial migration" state
+ *  worth leaving a project in; `cli/update.ts` (Task 10) treats any thrown error from this as the
+ *  "failure" result, not a silently-skipped migration. */
+export function runMigrate(projectRoot, fromVersion, options) {
+    // Always filter/sort by fromVersion here, even for an explicitly-injected `migrations` list —
+    // `migrationsAfter` already does this for the real registry, but a test-only injected list (out
+    // of order, including versions at or before fromVersion) needs the same treatment to match this
+    // function's documented "runs every migration after fromVersion, in order" contract.
+    const from = parseVersion(fromVersion);
+    const migrations = (options.migrations ?? migrationsAfter(fromVersion))
+        .filter((migration) => compareVersions(parseVersion(migration.version), from) > 0)
+        .sort((a, b) => compareVersions(parseVersion(a.version), parseVersion(b.version)));
+    const changes = [];
+    for (const migration of migrations) {
+        changes.push(...(options.dryRun ? migration.dryRun(projectRoot) : migration.apply(projectRoot)));
+    }
+    return { version: 1, from: fromVersion, changes, dryRun: options.dryRun };
+}
+export function formatMigrateHuman(result) {
+    if (result.changes.length === 0)
+        return `Nothing to migrate from ${result.from}.`;
+    return result.changes.map((change) => `${change.file}: ${change.change}`).join('\n');
+}

package/dist/cli/migrateEntry.js

@@ -0,0 +1,19 @@
+// cli/migrateEntry.ts
+//
+// A standalone, dependency-free CLI entry — imports only `migrate.ts` (and, transitively,
+// `migrations/`/`semver.ts`), never `main.ts` (whose `config.ts`/`doctor.ts`/`init.ts`/
+// `explain.ts` imports each pull in the `typescript` npm package at module load). `updatePlan.ts`
+// (Task 9) runs this file's own compiled `dist/cli/migrateEntry.js` directly from an `npm
+// pack`-extracted tarball, which has no `node_modules` of its own — `main.js` would fail there
+// with `ERR_MODULE_NOT_FOUND` for `'typescript'` (Critical finding, Fable correction pass, proven
+// for real in `spikes/migrate-entry/`: see this plan's own final report).
+import { formatMigrateHuman, runMigrate } from "./migrate.js";
+const args = process.argv.slice(2);
+const fromIndex = args.indexOf('--from');
+const fromVersion = fromIndex !== -1 ? args[fromIndex + 1] : undefined;
+if (!fromVersion) {
+    console.error('Usage: migrateEntry --from <version> [--dry-run] [--json]');
+    process.exit(1);
+}
+const result = runMigrate(process.cwd(), fromVersion, { dryRun: args.includes('--dry-run') });
+console.log(args.includes('--json') ? JSON.stringify(result) : formatMigrateHuman(result));