@krapwoo/ds-viewer 0.1.1 → 0.3.0

package/dist/cli/githubAction.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+// 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`. 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';
+}
+function installStep(projectRoot) {
+    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+        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)}`;
+    // `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/glob.js

@@ -30,6 +30,14 @@ function walk(root, segments, consumed) {
         }
     }
     const [segment, ...rest] = segments;
+    // `readdirSync` never returns "." or ".." as entries, so without this a config glob that climbs
+    // out of its own root (e.g. kit-host's `../starter-kit/components/*/index.ts`, Task 5) would
+    // regex-match against real directory entries and silently resolve to nothing. `path.join` below
+    // already collapses "." and ".." correctly once they're part of `consumed` — this just lets them
+    // reach it instead of being treated as a literal name to search for.
+    if (segment === '..' || segment === '.') {
+        return walk(root, rest, [...consumed, segment]);
+    }
     const dir = path.join(root, ...consumed);
     let entries;
     try {

package/dist/cli/init.js

@@ -1,8 +1,11 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 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";
 async function promptConfirm(message) {
     // A closed, non-interactive stdin (CI, piped npx) would reject `question` with an AbortError;
     // say how to proceed instead.
@@ -15,25 +18,28 @@ async function promptConfirm(message) {
     rl.close();
     return /^y(es)?$/i.test(answer.trim());
 }
-/** This package's own version — used as the `^x.y.z` devDependency version written below, since a
- *  project run via `npx @krapwoo/ds-viewer init` has no local copy to read its version from yet.
- *  Walks up from this file's own directory looking for the `package.json` named
- *  `@krapwoo/ds-viewer`, rather than a fixed relative path: this file sits one level under the
- *  repo root as `cli/init.ts` (how the test below runs it) but two levels under it once compiled,
- *  as `dist/cli/init.js` — a single `../..` would be wrong for one of the two. */
-function ownVersion() {
+/** This package's own installed root — needed both for `ownVersion()` below and (new in 0.2) to
+ *  find the bundled `starter-kit/` to copy from. Walks up from this file's own directory looking
+ *  for the `package.json` named `@krapwoo/ds-viewer`, rather than a fixed relative path: this file
+ *  sits one level under the repo root as `cli/init.ts` (how tests run it) but two levels under it
+ *  once compiled, as `dist/cli/init.js` — a single `../..` would be wrong for one of the two. */
+function packageRoot() {
     let dir = import.meta.dirname;
     for (let depth = 0; depth < 5; depth += 1) {
         const candidate = path.join(dir, 'package.json');
         if (existsSync(candidate)) {
             const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
             if (pkg.name === '@krapwoo/ds-viewer')
-                return pkg.version;
+                return dir;
         }
         dir = path.dirname(dir);
     }
     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;
+}
 /** 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
  *  spaces when nothing indented is found (e.g. a minified `package.json`). */
@@ -85,6 +91,25 @@ export async function initExistingProject(projectRoot, options = {}) {
             written.push(draftPath);
         }
     }
+    written.push(...ensureSharedProjectFiles(projectRoot));
+    const routerWarnings = componentFolders
+        .filter((folder) => folder.relativePath.split(path.sep)[0] === 'app')
+        .map((folder) => `Warning: ${folder.relativePath.split(path.sep).join('/')} is inside an Expo Router "app/" directory; its .catalog.tsx file will become a route.`);
+    const messages = [
+        ...warnings.map((issue) => `Warning: ${issue.package} not found. Run: ${issue.installCommand}`),
+        ...routerWarnings,
+        // "with catalog pages", not "with examples": this counts any existing `<Name>.catalog.tsx`,
+        // including init's own drafts, which explicitly say "Needs examples" — not real coverage yet.
+        `${componentFolders.length} components · ${withExamplesCount} with catalog pages`,
+        'Next: npm install, then npm run ds-viewer dev',
+    ];
+    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, 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');
     const packageJsonRaw = readFileSync(packageJsonPath, 'utf8');
     const packageJson = JSON.parse(packageJsonRaw);
@@ -106,26 +131,135 @@ export async function initExistingProject(projectRoot, options = {}) {
     const gitignorePath = path.join(projectRoot, '.gitignore');
     const gitignoreEntry = '.ds-viewer/';
     const existingGitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    // `\r\n` line endings leave a trailing `\r` on each split line, which never equals the entry —
-    // trim it per line so a CRLF .gitignore is recognized as already having the entry on a rerun.
     if (!existingGitignore.split('\n').some((line) => line.replace(/\r$/, '') === gitignoreEntry)) {
         const separator = existingGitignore === '' || existingGitignore.endsWith('\n') ? '' : '\n';
         writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
         written.push(gitignorePath);
     }
-    const routerWarnings = componentFolders
-        .filter((folder) => folder.relativePath.split(path.sep)[0] === 'app')
-        .map((folder) => `Warning: ${folder.relativePath.split(path.sep).join('/')} is inside an Expo Router "app/" directory; its .catalog.tsx file will become a route.`);
+    written.push(...ensureAgentsFileSection(projectRoot));
+    written.push(...ensureGithubAction(projectRoot));
+    return written;
+}
+const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];
+/** The starter kit's own intended sidebar order (the same list kit-host/ds-viewer.config.ts
+ *  declares, minus "Viewer" — that group only holds kit-host's own framework-docs pages under
+ *  `viewer-pages/`, which `init --new` never copies). Written into a fresh project's config so its
+ *  sidebar isn't left alphabetical (controller end-to-end finding E3). */
+const KIT_GROUP_ORDER = [
+    'Actions', 'Surfaces', 'Inputs', 'Controls', 'Selection', 'Feedback', 'Navigation',
+    'Overlays', 'Layout', 'Sub-Parts', 'Recipes', 'Tokens', 'Reference',
+];
+/** Default `installer` — a real `npx expo install`, run only for whichever of
+ *  `KIT_REQUIRED_PACKAGES` the project doesn't already depend on. Test-injected in every unit test
+ *  (this plan's Global Constraints: never run a real `expo install` in tests). */
+function defaultInstaller(projectRoot, missingPackages) {
+    if (missingPackages.length === 0)
+        return;
+    // Same `shell: process.platform === 'win32'` reasoning as `dev.ts`'s existing `spawn('npx', ...)`
+    // call: Windows resolves `npx` via `npx.cmd`, which `execFileSync` only finds through a shell.
+    execFileSync('npx', ['expo', 'install', ...missingPackages], { cwd: projectRoot, stdio: 'inherit', shell: process.platform === 'win32' });
+}
+/** Copies every file under `srcDir` into `destDir`, skipping any destination file that already
+ *  exists (design's "never overwrites user files" rule — Global Constraints) and reporting, not
+ *  throwing on, one unreadable source file (Error-handling rule). Also reports, rather than
+ *  throwing on, an unreadable nested folder — the same `readdirSync` call recurses, so wrapping it
+ *  here covers every depth — so files already copied before it are still returned, and skips a
+ *  symlinked entry (neither a plain file nor a directory `copyKitIfMissing` should recurse into)
+ *  instead of copying through it (Minor finding, Fable's implementation review,
+ *  cli/init.ts:205-224). Returns every path it wrote. */
+export function copyKitIfMissing(srcDir, destDir) {
+    const written = [];
+    mkdirSync(destDir, { recursive: true });
+    let entries;
+    try {
+        entries = readdirSync(srcDir, { withFileTypes: true });
+    }
+    catch (error) {
+        console.warn(`Could not read ${srcDir}: ${error.message}`);
+        return written;
+    }
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            written.push(...copyKitIfMissing(srcPath, destPath));
+            continue;
+        }
+        if (existsSync(destPath))
+            continue;
+        try {
+            copyFileSync(srcPath, destPath);
+            written.push(destPath);
+        }
+        catch (error) {
+            console.warn(`Could not copy ${path.relative(srcDir, srcPath)}: ${error.message}`);
+        }
+    }
+    return written;
+}
+function newProjectConfigContents(kitRoot, starterKitVersion) {
+    return `import { defineConfig } from '@krapwoo/ds-viewer/config';
+
+export default defineConfig({
+  name: 'My App',
+  components: ['${kitRoot}/components/*/index.ts'],
+  tokens: ['${kitRoot}/tokens/index.ts'],
+  pages: ['${kitRoot}/pages/*.catalog.tsx'],
+  groupOrder: ${JSON.stringify(KIT_GROUP_ORDER)},
+  starterKit: { version: '${starterKitVersion}' },
+});
+`;
+}
+/** The new-project half of `init` (design §2's "new project" column) — existing-project `init` is
+ *  `initExistingProject`, 0.1 scope. No confirmation prompt here: unlike the existing-project path,
+ *  there is nothing to detect or confirm — the kit root is the only user choice, and it's a flag. */
+export async function initNewProject(projectRoot, options = {}) {
+    const { errors, warnings } = preflight(projectRoot);
+    if (errors.length > 0) {
+        return { messages: errors.map((issue) => `Missing ${issue.package}. Run: ${issue.installCommand}`), written: [], exitCode: 1 };
+    }
+    const packageJson = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    const installedPackages = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    const missingKitPackages = KIT_REQUIRED_PACKAGES.filter((name) => !installedPackages[name]);
+    await (options.installer ?? defaultInstaller)(projectRoot, missingKitPackages);
+    const kitRoot = options.kitRoot ?? 'src/ds';
+    const written = copyKitIfMissing(path.join(packageRoot(), 'starter-kit'), path.join(projectRoot, kitRoot));
+    // Read before `ensureSharedProjectFiles`/the config write below add their own entries — this is
+    // only true when `copyKitIfMissing` itself wrote nothing, i.e. a rerun found every kit file
+    // already present (controller end-to-end finding E2: a second `init --new` claimed to have
+    // copied the kit even though nothing changed on disk).
+    const copiedKitFiles = written.length > 0;
+    const configPath = path.join(projectRoot, 'ds-viewer.config.ts');
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, newProjectConfigContents(kitRoot, ownVersion()));
+        written.push(configPath);
+    }
+    written.push(...ensureSharedProjectFiles(projectRoot));
     const messages = [
         ...warnings.map((issue) => `Warning: ${issue.package} not found. Run: ${issue.installCommand}`),
-        ...routerWarnings,
-        // "with catalog pages", not "with examples": this counts any existing `<Name>.catalog.tsx`,
-        // including init's own drafts, which explicitly say "Needs examples" — not real coverage yet.
-        `${componentFolders.length} components · ${withExamplesCount} with catalog pages`,
+        ...(missingKitPackages.length > 0 ? [`Installed ${missingKitPackages.join(', ')}.`] : []),
+        copiedKitFiles ? `Copied the starter kit into ${kitRoot}/.` : `Starter kit already present in ${kitRoot}/ — nothing copied.`,
         'Next: npm install, then npm run ds-viewer dev',
     ];
     return { messages, written };
 }
+/** The one new-vs-existing question (design §2's "One question") — `--new`/`--existing` (wired in
+ *  `cli/main.ts`) skip it entirely; this is only reached with neither flag. */
+export async function promptInitMode() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('New or existing project? [new/existing] ');
+    rl.close();
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === 'new' || normalized === 'n')
+        return 'new';
+    if (normalized === 'existing' || normalized === 'e')
+        return 'existing';
+    return undefined;
+}
 function configFileContents(componentFolders, tokenFiles) {
     // Emits both `index.ts` and `index.tsx` globs for every detected parent folder whenever any
     // detected folder uses `.tsx` (`detect.ts` accepts either extension — Important: a project using

package/dist/cli/main.js

@@ -3,16 +3,28 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveConfig } from "./config.js";
-import { initExistingProject } from "./init.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";
 const USAGE = `Usage: ds-viewer <command>
 
 Commands:
-  init     Set up the viewer in this project: config, draft catalog pages, and an npm script
-           --yes  accept the detected components and tokens without asking
+  init     Set up the viewer in this project: config, catalog pages, and an npm script
+           --new           start from the starter kit (new project)
+           --existing      detect this project's own components/tokens (existing project)
+           --kit-root DIR  where to copy the starter kit (--new only; default src/ds)
+           --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
+  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
 
 Options:
   -h, --help     Show this help
@@ -33,6 +45,90 @@ function packageVersion() {
         dir = parent;
     }
 }
+/** `--kit-root`'s raw CLI value, normalized to a project-root-relative, forward-slash path — or an
+ *  error when the value can't be made into one. Without this: an absolute value was silently
+ *  relocated *under* the project root by `path.join` (which never does `path.resolve`'s "a later
+ *  absolute segment replaces everything before it" — it just concatenates), a trailing slash
+ *  produced a doubled-slash glob (`src/ds//components/*`), and a quote broke the generated
+ *  config's TypeScript string literal (Minor finding, Fable's implementation review,
+ *  cli/main.ts:59-60 & cli/init.ts:231-233,257). */
+export function parseKitRoot(projectRoot, rawValue) {
+    if (rawValue.includes("'") || rawValue.includes('"')) {
+        return { error: `--kit-root cannot contain a quote (got "${rawValue}")` };
+    }
+    const relative = path.relative(projectRoot, path.resolve(projectRoot, rawValue));
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return { error: `--kit-root must stay inside the project root (got "${rawValue}")` };
+    }
+    return { value: relative.split(path.sep).join('/') };
+}
+/** Parses `init`'s flags and dispatches to `initNewProject`/`initExistingProject` — pulled out of
+ *  `main` so the dispatch (which flags pick which project path, `--yes`'s 0.1-compatible default,
+ *  `--kit-root`'s normalization) is unit-testable with an injected installer, never a real `expo
+ *  install` (Minor finding, Fable's implementation review: "No CLI test covers `--yes` defaulting
+ *  to existing, `--kit-root` parsing, or `--new` dispatch"). */
+export async function runInit(projectRoot, rest, options = {}) {
+    const kitRootIndex = rest.indexOf('--kit-root');
+    // Validated, not just indexed: a bare trailing `--kit-root` (no value) or `--kit-root --yes`
+    // (the next token is itself a flag) would otherwise silently pass `undefined`/`'--yes'` as the
+    // kit root. Both are treated as "no value given", the same as omitting the flag entirely.
+    const kitRootValue = kitRootIndex !== -1 ? rest[kitRootIndex + 1] : undefined;
+    const kitRootRaw = kitRootValue && !kitRootValue.startsWith('--') ? kitRootValue : undefined;
+    let kitRoot;
+    if (kitRootRaw !== undefined) {
+        const parsed = parseKitRoot(projectRoot, kitRootRaw);
+        if (parsed.error)
+            return { messages: [parsed.error], written: [], exitCode: 1 };
+        kitRoot = parsed.value;
+    }
+    let mode = rest.includes('--new') ? 'new' : rest.includes('--existing') ? 'existing' : undefined;
+    // 0.1 had only one `init` path (today's `initExistingProject`) and no mode question at all —
+    // `--yes` alone must keep working exactly as it did for a 0.1 user or script, so `--yes` with
+    // neither `--new` nor `--existing` defaults to `existing`, the same path 0.1's `--yes` always
+    // ran, instead of prompting (which would hang/exit 1 on non-interactive stdin and break them).
+    if (!mode && rest.includes('--yes'))
+        mode = 'existing';
+    if (!mode)
+        mode = await (options.promptMode ?? promptInitMode)();
+    if (!mode) {
+        const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+        // A non-interactive stdin (CI, piped npx) never got to ask the question at all — but a TTY
+        // whose answer `promptInitMode` simply couldn't parse did ask, so it needs its own message,
+        // not the "non-interactive" one (Minor finding, Fable's implementation review).
+        const message = isTTY
+            ? 'Could not parse that answer. Specify --new or --existing directly.'
+            : 'Specify --new or --existing (non-interactive stdin cannot be asked).';
+        return { messages: [`${message}\n\n${USAGE}`], written: [], exitCode: 1 };
+    }
+    return mode === 'new'
+        ? 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 function runDoctorCommand(projectRoot, rest) {
+    const config = resolveConfig(projectRoot);
+    const result = runDoctor(config);
+    const output = rest.includes('--json') ? JSON.stringify(toDoctorJson(result), null, 2) : formatHuman(result);
+    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();
@@ -45,7 +141,7 @@ async function main() {
         return;
     }
     if (command === 'init') {
-        const result = await initExistingProject(projectRoot, { yes: rest.includes('--yes') });
+        const result = await runInit(projectRoot, rest);
         for (const message of result.messages)
             console.log(message);
         for (const file of result.written)
@@ -60,6 +156,21 @@ async function main() {
         console.log(`Synced ${result.componentCount} components, ${result.pageCount} pages.`);
         return;
     }
+    if (command === 'doctor') {
+        const { output, exitCode } = 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 === 'dev') {
         const config = resolveConfig(projectRoot);
         await dev(config);

package/dist/cli/pageIndex.js

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveGlob } from "./glob.js";
 /** Component pages: `<Export>.catalog.tsx` beside the component's entry file (design §2). A
@@ -10,6 +10,25 @@ export function discoverPages(input) {
     const standalonePages = input.standalonePageGlobs.flatMap((pattern) => resolveGlob(input.projectRoot, pattern));
     return [...componentPages, ...standalonePages].sort();
 }
+/** Every `*.catalog.tsx`/`.catalog.ts` file `doctor` should read — unlike `discoverPages`, this
+ *  also finds a page beside a component whose folder still exists but whose export was renamed or
+ *  removed (that page's file never changed, so it's still sitting right there). `componentFolders`
+ *  is every distinct folder containing a currently-resolved component entry file — `cli/doctor.ts`
+ *  derives it the same way `cli/sync.ts` does, by resolving `config.components` and taking each
+ *  match's `path.dirname`. A folder that was deleted entirely (not just renamed within) has nothing
+ *  left to find here, which is correct: there's no stale page file left on disk to warn about. */
+export function discoverAllPageFiles(input) {
+    const componentPages = input.componentFolders.flatMap((folder) => {
+        try {
+            return readdirSync(folder).filter((name) => /\.catalog\.tsx?$/.test(name)).map((name) => path.join(folder, name));
+        }
+        catch {
+            return [];
+        }
+    });
+    const standalonePages = input.standalonePageGlobs.flatMap((pattern) => resolveGlob(input.projectRoot, pattern));
+    return [...new Set([...componentPages, ...standalonePages])].sort();
+}
 /** Writes `.ds-viewer/generated/pages.ts`: imports every discovered page's default export,
  *  resolves each one's id (design §2 "Page id": `id ?? component ?? <file stem>` — a component
  *  page defaults to its export name, a standalone page to its own file's stem) and `file` (the
@@ -25,6 +44,13 @@ export function writePageIndex(generatedDir, pageFiles) {
     writeFileSync(outFile, `${importLines.join('\n')}\n\n${resolveLines.join('\n')}\n\n${exportLine}\n`);
     return outFile;
 }
+/** `page.id ?? page.component ?? <file's own stem>` (design §2 "Page id") — factored out of
+ *  `writePageIndex`'s own inline logic above so `cli/doctor.ts` resolves a page's id exactly the
+ *  same way, never a second, drifting copy of this rule. Takes the same two fields `StaticPage`
+ *  (Task 3) and the generated page index both already carry. */
+export function resolvePageId(page, file) {
+    return page.id ?? page.component ?? fileStem(file);
+}
 function toImportPath(fromDir, toFile) {
     const withoutExt = toFile.replace(/\.tsx?$/, '');
     const relativePath = path.relative(fromDir, withoutExt).split(path.sep).join('/');