@krapwoo/ds-viewer 0.3.0 → 0.4.1

package/dist/cli/githubAction.js

@@ -1,5 +1,6 @@
 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
@@ -20,21 +21,17 @@ function pnpmVersion(projectRoot) {
 }
 // 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`. A v1 lockfile's own first line
-// is always exactly `# yarn lockfile v1`; anything else (Berry's own header/`__metadata`) is Berry.
-function yarnInstallStep(projectRoot) {
-    const firstLine = readFileSync(path.join(projectRoot, 'yarn.lock'), 'utf8').split('\n', 1)[0];
-    if (firstLine === '# yarn lockfile v1')
-        return '      - run: yarn install --frozen-lockfile\n';
-    return '      - run: corepack enable\n      - run: yarn install --immutable\n';
-}
+// first, since `actions/setup-node` ships Yarn 1 on `ubuntu-latest`.
 function installStep(projectRoot) {
-    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+    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 (existsSync(path.join(projectRoot, 'yarn.lock')))
-        return `${setupNode}${yarnInstallStep(projectRoot)}`;
+    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.

package/dist/cli/init.js

@@ -6,6 +6,7 @@ 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.
@@ -37,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
@@ -208,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,5 +1,4 @@
 #!/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";
@@ -8,6 +7,11 @@ 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:
@@ -18,6 +22,8 @@ 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)
@@ -25,24 +31,25 @@ Commands:
            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
@@ -107,10 +114,25 @@ export async function runInit(projectRoot, rest, options = {}) {
 /** 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 function runDoctorCommand(projectRoot, rest) {
+export async function runDoctorCommand(projectRoot, rest, options = {}) {
     const config = resolveConfig(projectRoot);
     const result = runDoctor(config);
-    const output = rest.includes('--json') ? JSON.stringify(toDoctorJson(result), null, 2) : formatHuman(result);
+    // 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. */
@@ -157,7 +179,7 @@ async function main() {
         return;
     }
     if (command === 'doctor') {
-        const { output, exitCode } = runDoctorCommand(projectRoot, rest);
+        const { output, exitCode } = await runDoctorCommand(projectRoot, rest);
         console.log(output);
         if (exitCode)
             process.exitCode = exitCode;
@@ -171,9 +193,46 @@ async function main() {
             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));

package/dist/cli/migrations/index.js

@@ -0,0 +1,14 @@
+// cli/migrations/index.ts
+import { compareVersions, parseVersion } from "../semver.js";
+/** The real, production migration registry. Empty in 0.4 — design §5 "Versioning": "From 0.4,
+ *  every breaking change ships an automatic migration" describes the *mechanism* this plan builds,
+ *  not a requirement to invent a breaking change 0.4 does not have. The framework itself is proven
+ *  by a test-only fixture migration (`cli/__tests__/migrate.test.ts`) that is never added here. */
+export const MIGRATIONS = [];
+/** Every migration after `fromVersion`, oldest first. */
+export function migrationsAfter(fromVersion) {
+    const from = parseVersion(fromVersion);
+    return MIGRATIONS
+        .filter((migration) => compareVersions(parseVersion(migration.version), from) > 0)
+        .sort((a, b) => compareVersions(parseVersion(a.version), parseVersion(b.version)));
+}

package/dist/cli/migrations/types.js

@@ -0,0 +1,9 @@
+// cli/migrations/types.ts
+//
+// This file, and every file `cli/migrateEntry.ts` transitively imports through `Migration` values
+// placed in `cli/migrations/index.ts` (`migrate.ts`, `migrations/index.ts`, `semver.ts`), must
+// never import the `typescript` npm package (directly or transitively) — `migrateEntry.ts` is the
+// one thing this plan runs from inside an `npm pack`-extracted tarball that has no `node_modules`
+// of its own, and `typescript` is a real `dependencies` entry (Task 9's own `buildUpdatePlan`,
+// spiked for real in `spikes/migrate-entry/`).
+export {};

package/dist/cli/packageManager.js

@@ -0,0 +1,40 @@
+// cli/packageManager.ts
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The same lockfile-sniffing `cli/githubAction.ts`'s own `installStep` already did inline (0.3)
+ *  — promoted here so `cli/update.ts` (Task 10) can detect the same thing without duplicating it.
+ *  A v1 yarn.lock's own first line is always exactly `# yarn lockfile v1`; anything else (Berry's
+ *  own header/`__metadata`) is Berry. */
+export function detectPackageManager(projectRoot) {
+    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    const yarnLockPath = path.join(projectRoot, 'yarn.lock');
+    if (existsSync(yarnLockPath)) {
+        const firstLine = readFileSync(yarnLockPath, 'utf8').split('\n', 1)[0];
+        return firstLine === '# yarn lockfile v1' ? 'yarn-classic' : 'yarn-berry';
+    }
+    return 'npm'; // package-lock.json, or no lockfile at all (npm's own documented default either way).
+}
+/** The one command `cli/update.ts`'s "Upgrades with the project's package manager" step (design
+ *  §5 "`npx ds-viewer update`" step 3) runs, for whichever manager `detectPackageManager` found.
+ *  Yarn (classic and Berry both) use the same `yarn add --dev` syntax for upgrading a single
+ *  package to an exact version. */
+export function installUpgradeCommand(pm, pkg, version) {
+    const spec = `${pkg}@${version}`;
+    if (pm === 'npm')
+        return { command: 'npm', args: ['install', '--save-dev', spec] };
+    if (pm === 'pnpm')
+        return { command: 'pnpm', args: ['add', '--save-dev', spec] };
+    return { command: 'yarn', args: ['add', '--dev', spec] };
+}
+const WINDOWS_SHIMS = new Set(['npm', 'npx', 'pnpm', 'yarn']);
+/** On Windows, `npm`, `npx`, `pnpm` and `yarn` are `.cmd` shims, which Node refuses to run
+ *  without a shell (the CVE-2024-27980 fix). With a shell, Node joins the arguments with spaces,
+ *  so any argument containing a space or a shell metacharacter (a temp folder under
+ *  `C:\Users\Jane Doe\…`) is wrapped in double quotes. Real executables (`node`, `tar`, `git`)
+ *  and every other platform keep running without a shell. */
+export function platformCommand(command, args, platform = process.platform) {
+    if (platform !== 'win32' || !WINDOWS_SHIMS.has(command))
+        return { command, args, shell: false };
+    return { command, args: args.map((arg) => (/[\s"&|<>^()]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg)), shell: true };
+}

package/dist/cli/packageVersion.js

@@ -0,0 +1,24 @@
+// cli/packageVersion.ts
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** Walks up from `startDir` looking for the `package.json` named `@krapwoo/ds-viewer` — needed
+ *  because this file sits one level under the repo root as `cli/packageVersion.ts` (how tests and
+ *  `init`/`main` run it from source) but two levels under it once compiled, as
+ *  `dist/cli/packageVersion.js`. Throws when it reaches the filesystem root without finding one,
+ *  which should never happen for a real install (`readOwnVersion` is only ever called from code
+ *  that is itself inside the installed/running package). */
+export function readOwnVersion(startDir) {
+    let dir = startDir;
+    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)
+            throw new Error("Could not find @krapwoo/ds-viewer's own package.json to read its version.");
+        dir = parent;
+    }
+}

package/dist/cli/semver.js

@@ -0,0 +1,26 @@
+// cli/semver.ts
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/;
+export function parseVersion(raw) {
+    const match = VERSION_RE.exec(raw.trim());
+    if (!match)
+        throw new Error(`Not a version: "${raw}"`);
+    const [, major, minor, patch, prerelease] = match;
+    return { major: Number(major), minor: Number(minor), patch: Number(patch), prerelease };
+}
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal — prerelease tags are ignored for
+ *  ordering (this package only ever compares a real installed version against a real registry
+ *  "latest", which is never a prerelease; the throwaway spike tag above is test-only). */
+export function compareVersions(a, b) {
+    for (const key of ['major', 'minor', 'patch']) {
+        if (a[key] !== b[key])
+            return a[key] < b[key] ? -1 : 1;
+    }
+    return 0;
+}
+/** Design §5 "Releasing" — "From 1.0, breaking changes only in major versions"; before that, this
+ *  plan still needs one consistent rule to decide the banner vs. the quiet footer line (design
+ *  §5 "Viewer notice"), and a major-version bump is the only rule that needs no per-release
+ *  judgment call. */
+export function isBreakingUpgrade(current, latest) {
+    return latest.major > current.major;
+}

package/dist/cli/update.js

@@ -0,0 +1,96 @@
+// cli/update.ts
+import { execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildUpdatePlan, isAlreadyUpToDate } from "./updatePlan.js";
+import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
+import { readOwnVersion } from "./packageVersion.js";
+import { lastSummaryLine } from "./doctor.js";
+function formatPlanHuman(plan) {
+    const lines = [`${plan.current} → ${plan.latest}${plan.breaking ? ' (major — includes breaking changes)' : ''}`];
+    if (plan.summary.length > 0)
+        lines.push('', "What's new:", ...plan.summary.map((line) => `  - ${line}`));
+    lines.push('', 'Files that would change:', ...plan.files.map((f) => `  ${f.path} (${f.dirty ? 'uncommitted' : f.reason})`));
+    if (plan.kitFilesDiffering > 0) {
+        lines.push('', `${plan.kitFilesDiffering} kit file${plan.kitFilesDiffering === 1 ? '' : 's'} differ from the installed kit's version. Compare with npx ds-viewer kit diff <Component>.`);
+    }
+    if (plan.outsideGitRepo)
+        lines.push('', '(Not a git repository — dirty-file detection was skipped; every file above is treated as not dirty.)');
+    return lines.join('\n');
+}
+async function defaultConfirm(message) {
+    if (!process.stdin.isTTY) {
+        console.log('Non-interactive stdin: rerun with --yes to accept.');
+        return false;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(message);
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+function installedMainJs(projectRoot) {
+    return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'dist', 'cli', 'main.js');
+}
+/** Design §5 "`npx ds-viewer update`", steps 1-6. */
+export async function runUpdate(config, options = {}) {
+    const currentVersion = options.currentVersion ?? readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
+    const plan = await (options.buildPlan ?? buildUpdatePlan)(config, currentVersion);
+    if ('error' in plan)
+        return { output: plan.error, exitCode: isAlreadyUpToDate(plan.error) ? 0 : 1 };
+    const planText = formatPlanHuman(plan);
+    if (options.dryRun)
+        return { output: planText, exitCode: 0 };
+    // Step 2: refuses on any dirty planned file, unless --force — checked before the confirmation
+    // prompt, so a script passing --yes without --force still gets refused instead of silently
+    // overwriting uncommitted work.
+    if (!options.force && plan.dirtyFiles.length > 0) {
+        return {
+            output: `${planText}\n\nRefusing: the following files have uncommitted changes:\n${plan.dirtyFiles.map((f) => `  ${f}`).join('\n')}\n\nCommit or stash them, or rerun with --force.`,
+            exitCode: 1,
+        };
+    }
+    if (!options.yes) {
+        const proceed = await (options.confirm ?? defaultConfirm)(`${planText}\n\nUpdate to ${plan.latest}? [y/N] `);
+        if (!proceed)
+            return { output: 'Aborted: nothing was changed.', exitCode: 0 };
+    }
+    const execImpl = options.execImpl ?? ((cmd, args, opts) => {
+        const run = platformCommand(cmd, args);
+        return execFileSync(run.command, run.args, { ...opts, encoding: 'utf8', shell: run.shell });
+    });
+    const { command, args } = installUpgradeCommand(detectPackageManager(config.projectRoot), '@krapwoo/ds-viewer', plan.latest);
+    try {
+        execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        return { output: `The update stopped while installing.\n${error.message}\n\nRecover with: npx ds-viewer update`, exitCode: 1 };
+    }
+    // Step 4: "Re-runs the newly installed binary" — the freshly-installed package's own
+    // `dist/cli/main.js`, never the one that is already running this process.
+    try {
+        execImpl('node', [installedMainJs(config.projectRoot), 'migrate', '--from', currentVersion], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        return {
+            output: `Installed ${plan.latest}, but migrate failed.\n${error.message}\n\nRecover with: npx ds-viewer migrate --from ${currentVersion}`,
+            exitCode: 1,
+        };
+    }
+    // M6 (Minor, Fable correction pass): the doctor step wasn't wrapped in try/catch — a crash here
+    // rejected `runUpdate` itself, losing the "installed and migrated successfully" context and
+    // leaving `main` to print only the raw error, mirroring `performUpdate`'s own identical guard.
+    let doctorOutput;
+    try {
+        doctorOutput = execImpl('node', [installedMainJs(config.projectRoot), 'doctor'], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        return {
+            output: `Installed and migrated to ${plan.latest}, but doctor failed to run.\n${error.message}\n\nRecover with: npx ds-viewer doctor`,
+            exitCode: 1,
+        };
+    }
+    // I5 (Important, raised from Minor by the controller): only the report's own last summary line —
+    // the mockup's success page shows one line, not the whole doctor report.
+    return { output: `Updated to ${plan.latest}. Changes are not committed — review them in your editor.\n\n${lastSummaryLine(doctorOutput)}`, exitCode: 0 };
+}