@krapwoo/ds-viewer 0.3.0 → 0.4.0

package/README.md

@@ -286,6 +286,75 @@ either one only if it's missing (an `AGENTS.md` without the start marker counts
 section, even if the file already has other content) and never touches anything outside its own
 markers or its own file.
 
+## Updating
+
+A quiet line appears in the sidebar footer when a new version is published — a banner too, for a
+major version, dismissible per version. Either opens the update page (`#ds-viewer-update`), which
+shows what would change and one **Update now** button:
+
+```
+0.4.0 → 0.5.0  Minor
+You're on 0.4.0. Released 2 days ago.
+
+What's new
+  •  Faster sync for large kits
+  •  New Tabs component in the starter kit
+
+Files that would change
+  package.json               version
+  package-lock.json          version
+
+[ Update now ]  or run npx ds-viewer update
+```
+
+**Update now** asks the running `dev` process to apply the same steps `update` runs below, over a
+local endpoint that only ever answers the viewer's own page (random port, a per-run secret, exact
+origin match). The secret itself is baked into the generated viewer bundle alongside it — it's the
+endpoint's own Host and exact-Origin checks, not the secret being unguessable, that stop any other
+web page from using it. The viewer restarts itself on the new version and reloads automatically;
+nothing is committed.
+
+If any file the update would touch has uncommitted changes, the panel refuses and names them —
+there's no override in the viewer; commit or stash first, or use `update --force` below. Outside a
+git repository, every file is treated as not dirty (there's nothing to check).
+
+### `npx ds-viewer update`
+
+```
+npx ds-viewer update              # shows the plan, asks to confirm, then updates
+npx ds-viewer update --dry-run    # shows the plan and stops
+npx ds-viewer update --yes        # skip the confirmation prompt
+npx ds-viewer update --force      # update even with uncommitted changes in a planned file
+```
+
+Downloads the target version, runs its own `migrate --from <your version>`, upgrades with
+whichever package manager your lockfile names, re-runs `migrate` for real, then `doctor`. Changes
+are left uncommitted — review them like any other change.
+
+### `npx ds-viewer migrate --from <version>`
+
+Runs every migration introduced after `<version>` — `update` calls this for you; run it directly
+only to catch up a project that upgraded its `package.json` some other way. `--dry-run` reports the
+changes without writing them; `--json` for the machine-readable version. 0.4 ships this framework
+with an empty migration list — it introduces no breaking change of its own.
+
+### `npx ds-viewer kit diff <Component>`
+
+Starter-kit files are copied once by `init` and never touched again — not even by `update`, which
+only ever counts how many differ from the version you're installing. `kit diff <Component>` shows
+your copy against the installed kit's, as a plain diff:
+
+```
+npx ds-viewer kit diff Button
+--- components/Button/Button.catalog.tsx (installed kit)
++++ components/Button/Button.catalog.tsx (yours)
+  ...
+```
+
+Set `starterKit.root` in `ds-viewer.config.ts` if you moved the kit after `init --new` wrote it
+(default `src/ds`); a config from before 0.4 with no `root` field still works — it's inferred from
+your first `components` glob.
+
 ## What's included
 
 Tokens · Icons (45) · and generic components:

package/config/index.ts

@@ -16,8 +16,10 @@ export interface DsViewerConfig {
   pages?: string[];
   /** Sidebar group display order; groups not listed here follow alphabetically. */
   groupOrder?: string[];
-  /** Starter-kit projects only. */
-  starterKit?: { version: string };
+  /** Starter-kit projects only. `root` is the folder `init --new` copied the kit into (default
+   *  `src/ds`); absent on a config written before 0.4, in which case `cli/kitRoot.ts` infers it
+   *  from the first `components` glob instead. */
+  starterKit?: { version: string; root?: string };
   /** @default true */
   updateCheck?: boolean;
   /** `strict: true` promotes `doctor` warnings to errors. */

package/dist/cli/dev.js

@@ -1,11 +1,20 @@
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync, rmSync, watch, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
 import { writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
+import { checkForUpdate, isUpdateCheckEnabled, writeUpdateFile } from "./updateCheck.js";
+import { readOwnVersion } from "./packageVersion.js";
+import { createUpdateEndpoint } from "./endpoint.js";
+import { buildUpdatePlan } from "./updatePlan.js";
+import { lastSummaryLine } from "./doctor.js";
+import { detectPackageManager, installUpgradeCommand } from "./packageManager.js";
 export class LocalInstallMissingError extends Error {
 }
 const IGNORED_WATCH_SEGMENTS = new Set(['.ds-viewer', 'node_modules', '.git']);
@@ -49,26 +58,295 @@ export function watchTargetFolders(config) {
  *  workspace until `dev` was restarted, because `writeWorkspace` was never called again with the
  *  new value (controller end-to-end finding E1). Returns the freshly-resolved config so `dev` can
  *  keep watching with it. */
-export function reloadWorkspace(projectRoot) {
+export function reloadWorkspace(projectRoot, updateEndpoint) {
     const config = resolveConfig(projectRoot);
     sync(config);
-    writeWorkspace(config);
+    writeWorkspace(config, updateEndpoint);
     return config;
 }
+/** Design §5: `dev` writes `.ds-viewer/update.json` every run, from a fresh check (respecting the
+ *  24h cache inside `checkForUpdate`) or `null` when checks are disabled — never left unwritten,
+ *  since the generated entry file (Task 17) always imports it. Exported and test-only-injectable
+ *  the same way `reloadWorkspace` already is, so this plan never needs to test `dev()` itself
+ *  (which spawns a real Expo process) to prove this one behavior. */
+export async function refreshUpdateFile(config, ownVersion, options = {}) {
+    const result = isUpdateCheckEnabled(config, options.env ?? process.env)
+        ? await (options.checkForUpdate ?? checkForUpdate)(ownVersion)
+        : undefined;
+    writeUpdateFile(config.projectRoot, result);
+}
+// Promisified, not `execFileSync` — install/migrate/doctor each take real seconds, and this now
+// runs from inside the endpoint's own request-handling process, which must keep answering
+// `/update/status` polls throughout (Critical finding, Fable correction pass: the synchronous
+// version blocked the entire event loop until the whole update finished).
+const execFileAsync = promisify(execFile);
+const defaultExecImpl = async (command, args, options) => (await execFileAsync(command, args, options)).stdout;
+function installedMainJs(projectRoot) {
+    return path.join(projectRoot, 'node_modules', '@krapwoo', 'ds-viewer', 'dist', 'cli', 'main.js');
+}
+function packageManagerLabel(pm) {
+    return pm === 'npm' ? 'npm' : pm === 'pnpm' ? 'pnpm' : 'yarn';
+}
+/** Design §5 "`npx ds-viewer update`" steps 3-5, run from inside `dev` instead of a one-shot CLI
+ *  invocation — every external effect injected (Global Constraints), exactly like `cli/update.ts`'s
+ *  `runUpdate`. The plan's own dirty-file refusal already happened before this was ever called
+ *  (the endpoint, Task 12, refuses `POST /update` itself); this function only ever runs a plan it
+ *  has already been told is safe to apply. */
+export async function performUpdate(config, currentVersion, plan, deps) {
+    const migrationCount = plan.files.filter((f) => f.reason.startsWith('migration:')).length;
+    const pm = detectPackageManager(config.projectRoot);
+    // Names the detected package manager and the real migration count (Important finding, Fable
+    // correction pass: the approved mockup's own `updating` state reads "Installed with npm" and
+    // "Applying 1 migration…", never a generic placeholder). The install step carries its own
+    // present-tense `progressLabel` (Minor finding, Fable correction pass: the in-flight step
+    // previously read "Installed with npm…" — already past tense — while still running) and its own
+    // `failLabel` (the mockup's failure state reads "Install with npm failed", not "Installed with
+    // npm failed" — a different, plain-present phrasing from either the done or in-flight label).
+    const stepDefs = [
+        { label: `Downloaded ${plan.latest}` },
+        { label: `Installed with ${packageManagerLabel(pm)}`, progressLabel: `Installing with ${packageManagerLabel(pm)}`, failLabel: `Install with ${packageManagerLabel(pm)}` },
+        { label: migrationCount > 0 ? `Applying ${migrationCount} migration${migrationCount === 1 ? '' : 's'}` : 'No migrations to apply' },
+        { label: 'Checking pages (doctor)' },
+        { label: 'Restarting the viewer' },
+    ];
+    // `completedCount` steps are 'done', the next one is 'now' (in flight), the rest 'todo' — a
+    // three-way state, not a boolean (Important finding, Fable correction pass; Task 12/15 share
+    // this exact shape). Step 0 (download) is already done — `buildUpdatePlan` already downloaded
+    // the tarball while building the plan this function was handed.
+    const report = (completedCount) => deps.onStatus({
+        phase: 'updating',
+        steps: stepDefs.map((def, i) => ({
+            label: i === completedCount && def.progressLabel ? def.progressLabel : def.label,
+            state: i < completedCount ? 'done' : i === completedCount ? 'now' : 'todo',
+        })),
+    });
+    report(1);
+    const { command, args } = installUpgradeCommand(pm, '@krapwoo/ds-viewer', plan.latest);
+    try {
+        await deps.execImpl(command, args, { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[1].failLabel ?? stepDefs[1].label });
+        return;
+    }
+    report(2);
+    try {
+        await deps.execImpl('node', [installedMainJs(config.projectRoot), 'migrate', '--from', currentVersion], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[2].label });
+        return;
+    }
+    report(3);
+    let doctorOutput;
+    try {
+        doctorOutput = await deps.execImpl('node', [installedMainJs(config.projectRoot), 'doctor'], { cwd: config.projectRoot, encoding: 'utf8' });
+    }
+    catch (error) {
+        deps.onStatus({ phase: 'failure', log: error.message, failedStep: stepDefs[3].label });
+        return;
+    }
+    report(4);
+    // Fable Minor finding, raised to Important by the controller: the success page showed the whole
+    // doctor report (30+ lines for a real project) — the mockup's own success state shows one line.
+    const doctorSummary = lastSummaryLine(doctorOutput);
+    deps.onStatus({ phase: 'restarting' });
+    // Errata 2c: wait before actually restarting, so the browser's next `/update/status` poll can
+    // observe the `'restarting'` phase instead of the connection just dropping.
+    await new Promise((resolve) => setTimeout(resolve, deps.delayMs ?? 1500));
+    // `files` lets the `success` status (Task 12/15/16) show what changed after the reload, once
+    // `plan` itself is gone (Important finding, Fable correction pass). `latest` (Errata 1b) lets
+    // the panel render the success state once `update.json` has gone back to `null`.
+    await deps.restart({ doctorSummary, files: plan.files.map((f) => f.path), latest: plan.latest });
+}
+/** Errata 7c: Metro listens on `[::1]` only, so a plain `127.0.0.1` connect probe always reports
+ *  the port as free even while Metro is still bound to it (observed with `lsof`) — `findFreePort`
+ *  itself already tries to bind the port, which fails correctly either way. */
+function defaultProbePortFree(port) {
+    return findFreePort(port, port).then(() => true, () => false);
+}
+async function waitForPortFree(port, probe) {
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        if (await probe(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+/** Kills `pid`'s whole process group with `signal` — a negative pid, except on `win32` (Errata
+ *  7e), where there is no process-group concept and `child.kill(signal)` is the only option. */
+function killGroup(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            child.kill(signal);
+        }
+        else {
+            process.kill(-child.pid, signal);
+        }
+    }
+    catch {
+        // Already exited.
+    }
+}
+/** Design §5 "Restart handoff" steps 3-5, rewritten in full (Critical finding, Fable correction
+ *  pass — the original version was detached-but-unrefed-and-immediately-exited, which this
+ *  repository's own `scripts/checkCatalogConsole.mjs` already documents as leaving the Expo
+ *  grandchild running on the port): closes everything this `dev` process owns; kills the *whole
+ *  process group* Expo/Metro spawned into (`dev()`, below, now spawns it with `detached: true`,
+ *  the same convention `checkCatalogConsole.mjs`'s own `killDevGroup` already established — a
+ *  negative pid targets the group, not just the one pid `child.kill()` alone would reach); waits
+ *  for the old child to actually exit (or 10s, whichever comes first — Errata 7d) and the port to
+ *  actually free before re-spawning `dev --port <same port>` — this time *not* detached, with
+ *  inherited stdio, so this very process becomes a thin supervisor that forwards
+ *  `SIGINT`/`SIGTERM`/`SIGHUP` to the new child and exits with its code, printing a recovery
+ *  command (and the result this update already recorded) if it exits non-zero, or if anything in
+ *  this function itself throws. Has no unit test (see this task's own note) — proven end-to-end
+ *  in Task 20. */
+export async function performRestart(handoff, deps = {}) {
+    // Errata 7a: remove `dev()`'s own SIGINT/SIGTERM/SIGHUP listeners (Step 5, below) first, before
+    // anything else — otherwise a signal sent to this supervisor mid-restart exits through that old
+    // handler (which tries to kill the already-exiting old child and calls `process.exit(0)`),
+    // orphaning the restarted `dev` and its Metro. `targetChild` starts `undefined`; a signal
+    // delivered before `newChild` exists below used to be silently swallowed instead of cancelling
+    // the restart (Minor finding, Fable correction pass: Ctrl-C in that up-to-15s window brought the
+    // viewer back up instead of stopping it) — `cancelledBeforeSpawn` remembers it instead, so the
+    // new `dev` is never spawned once the old child is gone.
+    let targetChild;
+    let cancelledBeforeSpawn = false;
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+        process.removeAllListeners(signal);
+    const forward = (signal) => {
+        if (targetChild)
+            targetChild.kill(signal);
+        else
+            cancelledBeforeSpawn = true;
+    };
+    process.on('SIGINT', forward);
+    process.on('SIGTERM', forward);
+    process.on('SIGHUP', forward);
+    try {
+        for (const watcher of handoff.watchers)
+            watcher.close();
+        handoff.endpointServer.close();
+        killGroup(handoff.child, 'SIGTERM');
+        // Errata 7d: race the old child's exit against a 10s timer, then SIGKILL the group — a wedged
+        // Expo/Metro process must never block the restart forever.
+        const exited = await Promise.race([
+            new Promise((resolve) => {
+                if (handoff.child.exitCode !== null) {
+                    resolve(true);
+                    return;
+                }
+                handoff.child.once('exit', () => resolve(true));
+            }),
+            new Promise((resolve) => setTimeout(() => resolve(false), 10_000)),
+        ]);
+        if (!exited)
+            killGroup(handoff.child, 'SIGKILL');
+        await waitForPortFree(handoff.port, deps.probePortFree ?? defaultProbePortFree);
+        // The old child is gone and the port is free — if a signal arrived in the window above (before
+        // there was anything to forward it to), this restart is itself cancelled: the user asked to
+        // stop, not to come back up on the new version.
+        if (cancelledBeforeSpawn) {
+            process.exit(0);
+            return;
+        }
+        const newChild = spawn(process.execPath, [...process.execArgv, process.argv[1], 'dev', '--port', String(handoff.port)], { cwd: handoff.projectRoot, stdio: 'inherit' });
+        newChild.on('error', (error) => console.error(`Could not restart the viewer: ${error.message}`));
+        targetChild = newChild;
+        const exitCode = await new Promise((resolve) => newChild.on('exit', (code) => resolve(code ?? 0)));
+        if (exitCode !== 0) {
+            console.error(`The restarted viewer exited unexpectedly (code ${exitCode}).`);
+            console.error('Recover with: npx ds-viewer dev');
+            // Important finding, Fable correction pass: design §5 restart step 5 asks for "the recovery
+            // command and the result of the update" — previously only the recovery command printed here,
+            // losing the install/migrate/doctor result (never shown anywhere else; it ran in-process).
+            console.error(`The update itself finished: ${handoff.doctorSummary}; changed: ${handoff.files.join(', ') || '(none)'}.`);
+        }
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error(`Restart failed: ${error.message}`);
+        console.error('Recover with: npx ds-viewer dev');
+        console.error(`The update itself finished: ${handoff.doctorSummary}; changed: ${handoff.files.join(', ') || '(none)'}.`);
+        process.exit(1);
+    }
+}
 /** Design §2 "`dev`": checks the local install, runs `sync`, writes the workspace, starts Expo
  *  web on the first free port from 5181 bound to localhost only, and watches the project for
  *  component/token/page changes to re-run `sync`. Metro's own HMR updates the rendered component
  *  when its source changes, but not the generated props table or page list (Task 17 Step 4 relies
  *  on this: editing `Button.tsx` must update its props table, not just hot-reload the component). */
-export async function dev(initialConfig) {
+export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
+    const ownVersion = readOwnVersion(import.meta.dirname);
+    await refreshUpdateFile(initialConfig, ownVersion);
     let config = initialConfig;
     sync(config);
-    const workspace = writeWorkspace(config);
-    const port = await findFreePort(5181, 5199);
+    // Restart handoff step 2/4: a status file left by the *previous* `dev` process (right before it
+    // exited to restart) is read once, then deleted — a plain refresh afterward shows "idle"/"no
+    // update known" instead of replaying a stale success/failure forever.
+    const statusFile = path.join(config.projectRoot, '.ds-viewer', 'update-status.json');
+    let updateStatus = { phase: 'idle' };
+    if (existsSync(statusFile)) {
+        try {
+            updateStatus = JSON.parse(readFileSync(statusFile, 'utf8'));
+        }
+        catch {
+            // A partial/corrupt write from a process that crashed mid-write — stay idle.
+        }
+        rmSync(statusFile, { force: true });
+    }
+    const port = await findFreePort(devOptions.pinnedPort ?? 5181, devOptions.pinnedPort ?? 5199);
     console.log(`Starting the catalog at http://localhost:${port}`);
+    let watchersPaused = false;
+    // Metro's own child process doesn't exist yet — assigned below, well before this is ever read
+    // (performUpdate's `restart` callback, which is the only reader, can only run after a real
+    // browser has already loaded the page and clicked "Update now").
+    let child;
+    const secret = randomBytes(24).toString('hex');
+    const allowedOrigin = `http://localhost:${port}`;
+    const endpointDeps = {
+        secret,
+        allowedOrigin,
+        buildPlan: () => buildUpdatePlan(config, ownVersion),
+        startUpdate: (plan) => {
+            watchersPaused = true;
+            void performUpdate(config, ownVersion, plan, {
+                execImpl: defaultExecImpl,
+                onStatus: (status) => {
+                    updateStatus = status;
+                    if (status.phase === 'failure')
+                        watchersPaused = false; // the update stopped — keep developing on the old version.
+                },
+                restart: async (result) => {
+                    writeFileSync(statusFile, JSON.stringify({ phase: 'success', ...result }));
+                    await performRestart({ projectRoot: config.projectRoot, port, child, watchers, endpointServer, doctorSummary: result.doctorSummary, files: result.files });
+                },
+            }).catch((error) => {
+                // Minor finding, Fable correction pass: `performUpdate` only ever reports `'failure'` from
+                // its own guarded steps — a throw outside them (e.g. `writeFileSync(statusFile)` itself
+                // failing) previously became an unhandled rejection with nothing watching for it.
+                updateStatus = { phase: 'failure', log: error.message, failedStep: 'Updating' };
+                watchersPaused = false;
+            });
+        },
+        getStatus: () => updateStatus,
+    };
+    const endpointServer = createUpdateEndpoint(endpointDeps);
+    await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
+    const endpointPort = endpointServer.address().port;
+    // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
+    // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
+    // itself is never printed; the endpoint rejects anything that doesn't already have it.
+    console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
+    const updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+    const workspace = writeWorkspace(config, updateEndpoint);
     let debounceTimer;
     const onSourceChange = (_eventType, relativePath) => {
+        if (watchersPaused)
+            return;
         if (relativePath && !isWatchedPath(relativePath))
             return;
         clearTimeout(debounceTimer);
@@ -87,10 +365,12 @@ export async function dev(initialConfig) {
     // `entry.tsx`/`metro.config.js` until `dev` is restarted (controller end-to-end finding E1).
     let configDebounceTimer;
     const onConfigChange = () => {
+        if (watchersPaused)
+            return;
         clearTimeout(configDebounceTimer);
         configDebounceTimer = setTimeout(() => {
             try {
-                config = reloadWorkspace(config.projectRoot);
+                config = reloadWorkspace(config.projectRoot, updateEndpoint);
             }
             catch (error) {
                 console.warn(`Could not reload ds-viewer.config.ts after a change: ${error.message}`);
@@ -104,28 +384,45 @@ export async function dev(initialConfig) {
     for (const watcher of watchers) {
         watcher.on('error', (error) => console.warn(`File watcher error: ${error.message}`));
     }
-    const child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
+    child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
         cwd: workspace,
         stdio: 'inherit',
         shell: process.platform === 'win32',
+        detached: true,
     });
     child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
     child.on('exit', (code) => {
         for (const watcher of watchers)
             watcher.close();
+        endpointServer.close();
         process.exitCode = code ?? 0;
     });
-    // Node's default SIGTERM/SIGINT behavior exits this process without touching its children —
-    // left alone, a signal sent only to `dev`'s own pid (not its process group) would leave the
-    // spawned `expo start` running, still bound to its port (Important finding, Fable correction
-    // pass: this is exactly what would hang `check:catalog`'s driving script, Task 11, if `dev`
-    // didn't clean up on its own).
-    for (const signal of ['SIGTERM', 'SIGINT']) {
+    // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
+    // children — left alone, a signal sent only to `dev`'s own pid (not its process group) would
+    // leave the spawned `expo start` running, still bound to its port (Important finding, Fable
+    // correction pass: this is exactly what would hang `check:catalog`'s driving script, Task 11, if
+    // `dev` didn't clean up on its own). SIGHUP (Errata 7b) matters here too: detached Expo is in
+    // its own session, so closing the terminal otherwise leaves Metro bound to the port.
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
         process.on(signal, () => {
             for (const watcher of watchers)
                 watcher.close();
-            child.kill(signal);
+            endpointServer.close();
+            killGroup(child, signal);
             process.exit(0);
         });
     }
+    // Minor finding, Fable correction pass: with Expo now spawned `detached: true`, any uncaught
+    // throw or unhandled rejection in this process (outside the guarded steps above) would otherwise
+    // crash `dev` with no terminal left to send Metro a signal, leaving it bound to the port.
+    const killExpoAndExit = (error) => {
+        console.error(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+        for (const watcher of watchers)
+            watcher.close();
+        endpointServer.close();
+        killGroup(child, 'SIGTERM');
+        process.exit(1);
+    };
+    process.on('uncaughtException', killExpoAndExit);
+    process.on('unhandledRejection', killExpoAndExit);
 }

package/dist/cli/doctor.js

@@ -490,3 +490,13 @@ export function formatHuman(result) {
         `${components} components (${withExamples} with examples), ${unboundExamples} unbound examples.`);
     return lines.join('\n');
 }
+/** `formatHuman`'s own output always ends with its one summary line (design §4's own example: "0
+ *  errors, 15 warnings — 37 components (37 with examples), 130 unbound examples.") — every issue
+ *  and its fix come before it. Used by `dev.ts`/`update.ts` to shrink the `doctor` step's captured
+ *  stdout down to that one line for the update panel's success state (Minor finding, raised to
+ *  Important by the controller: the mockup's own success page shows one line, not the whole
+ *  report). Never throws on empty input — falls back to the trimmed input itself. */
+export function lastSummaryLine(output) {
+    const lines = output.split('\n').map((line) => line.trimEnd()).filter((line) => line.length > 0);
+    return lines.length > 0 ? lines[lines.length - 1] : output.trim();
+}

package/dist/cli/endpoint.js

@@ -0,0 +1,142 @@
+// cli/endpoint.ts
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { DS_VIEWER_SECRET_HEADER } from "../native/catalog/catalogNavigation.js";
+/** A constant-time secret compare (Minor finding, Fable correction pass; controller decision 1
+ *  makes this required, not optional) — `!==` on two strings short-circuits at the first
+ *  differing byte, which leaks the secret's length and prefix through response-timing one byte at
+ *  a time. Buffers of different lengths are rejected before ever reaching `timingSafeEqual`
+ *  (which throws, rather than returning `false`, when its two inputs aren't the same length). */
+function secretMatches(received, expected) {
+    if (typeof received !== 'string')
+        return false;
+    const receivedBuf = Buffer.from(received);
+    const expectedBuf = Buffer.from(expected);
+    return receivedBuf.length === expectedBuf.length && timingSafeEqual(receivedBuf, expectedBuf);
+}
+function sendJson(res, status, body, allowedOrigin) {
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': allowedOrigin });
+    res.end(JSON.stringify(body));
+}
+/** Design §5 "Local endpoint safeguards", every one of them, in the exact order this plan's own
+ *  `spikes/cors-endpoint/` spike proved: Origin (including `OPTIONS`) → secret → route. Does not
+ *  call `.listen()` itself — Task 18's `dev.ts` owns the real port (`0` → OS-assigned, `127.0.0.1`
+ *  only) and this task's own tests each pick their own ephemeral port the same way. */
+export function createUpdateEndpoint(deps) {
+    // Critical finding, Fable correction pass: the "one update at a time" refusal only ever checked
+    // `getStatus()`, which doesn't become `'updating'` until `startUpdate` runs — but `buildPlan`
+    // (re-downloading the tarball) can take seconds, and the panel leaves **Update now** enabled
+    // throughout, so a second click during that window passed the same check twice. This flag closes
+    // exactly that window: set synchronously before the plan is even (re-)built, reset on every path
+    // that does *not* hand the plan to `startUpdate` — the 502/409 refusals below. Once `startUpdate`
+    // is actually called, `getStatus()` already reports `'updating'` (set synchronously inside it, by
+    // every real caller), so resetting this flag right after is safe and lets a later retry (after a
+    // `'failure'`, in the same process) through again.
+    let starting = false;
+    return http.createServer(async (req, res) => {
+        // Controller decision 1 (required, not optional): reject a request whose `Host` header is not
+        // this very socket's own `127.0.0.1:<port>` — a DNS-rebinding defence, since `req.socket`'s own
+        // `localPort` is the port the OS actually accepted this connection on, never spoofable the way
+        // `Origin` (an ordinary request header) technically is from a non-browser client. Checked before
+        // everything else, including `OPTIONS`.
+        if (req.headers.host !== `127.0.0.1:${req.socket.localPort}`) {
+            res.writeHead(400).end('Invalid Host header.');
+            return;
+        }
+        const origin = req.headers.origin;
+        if (req.method === 'OPTIONS') {
+            // The browser's own preflight never attaches the app's custom header to itself — checking
+            // the secret here would make every state-changing request fail cross-origin before it ever
+            // got the chance to send one.
+            if (origin !== deps.allowedOrigin) {
+                res.writeHead(403).end();
+                return;
+            }
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': deps.allowedOrigin,
+                'Access-Control-Allow-Methods': 'POST, GET',
+                'Access-Control-Allow-Headers': DS_VIEWER_SECRET_HEADER,
+            });
+            res.end();
+            return;
+        }
+        if (origin === undefined) {
+            res.writeHead(400).end('Missing Origin header.');
+            return;
+        }
+        if (origin !== deps.allowedOrigin) {
+            res.writeHead(403).end('Origin rejected.');
+            return;
+        }
+        if (!secretMatches(req.headers[DS_VIEWER_SECRET_HEADER], deps.secret)) {
+            res.writeHead(401).end('Missing or wrong secret.');
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/plan') {
+            const plan = await deps.buildPlan();
+            sendJson(res, 200, plan, deps.allowedOrigin);
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/update') {
+            // "Runs one update at a time; further start requests are refused while one runs" (design
+            // §5) — checked before even building a fresh plan, so a second click never re-downloads
+            // anything while the first update is still in flight.
+            const status = deps.getStatus();
+            if (starting || status.phase === 'updating' || status.phase === 'restarting') {
+                sendJson(res, 409, { error: 'An update is already running.' }, deps.allowedOrigin);
+                return;
+            }
+            starting = true;
+            let plan;
+            try {
+                plan = await deps.buildPlan();
+            }
+            catch (error) {
+                // A rejected plan must not leave `starting` stuck, or every later Update now is refused.
+                starting = false;
+                sendJson(res, 502, { error: error.message }, deps.allowedOrigin);
+                return;
+            }
+            if ('error' in plan) {
+                starting = false;
+                sendJson(res, 502, { error: plan.error }, deps.allowedOrigin);
+                return;
+            }
+            // "Refuses with the plan's dirty-file list ... the panel offers no override" (design §5) —
+            // this is the one, authoritative refusal: even if the panel's own UI somehow let a dirty
+            // plan through, the endpoint itself still never starts.
+            if (plan.dirtyFiles.length > 0) {
+                starting = false;
+                sendJson(res, 409, { error: 'dirty-files', dirtyFiles: plan.dirtyFiles }, deps.allowedOrigin);
+                return;
+            }
+            // Sends 202 *before* ever calling `startUpdate` — install/migrate/doctor run as real child
+            // processes that can take seconds (Critical finding, Fable correction pass: calling
+            // `startUpdate` first, synchronously, blocked this response until the whole update finished,
+            // so the browser's `POST /update` saw a connection reset instead of 202, and every
+            // `/update/status` poll during the install went unanswered). `setImmediate` defers the actual
+            // work to the next turn of the event loop, after this response has already been written.
+            sendJson(res, 202, { started: true }, deps.allowedOrigin);
+            // Errata 3: `startUpdate` is wrapped here too — a synchronous throw inside `setImmediate`'s
+            // callback would otherwise become an unhandled exception on the whole process, since there is
+            // no request/response left at that point to carry the error back to.
+            setImmediate(() => {
+                try {
+                    deps.startUpdate(plan);
+                }
+                catch (error) {
+                    console.warn('Update could not start: ' + error.message);
+                }
+                finally {
+                    starting = false;
+                }
+            });
+            return;
+        }
+        if (req.method === 'GET' && req.url === '/update/status') {
+            sendJson(res, 200, deps.getStatus(), deps.allowedOrigin);
+            return;
+        }
+        res.writeHead(404).end('Not found.');
+    });
+}