@ultimat3/cli 22.11.0 → 22.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.11.0",
+  "version": "22.12.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.11.0",
-    "@ultimat3/admin": "22.11.0",
-    "@ultimat3/ai": "22.11.0",
-    "@ultimat3/auth": "22.11.0",
-    "@ultimat3/cache": "22.11.0",
-    "@ultimat3/core": "22.11.0",
-    "@ultimat3/db": "22.11.0",
-    "@ultimat3/entity": "22.11.0",
-    "@ultimat3/flags": "22.11.0",
-    "@ultimat3/http": "22.11.0",
-    "@ultimat3/i18n": "22.11.0",
-    "@ultimat3/jobs": "22.11.0",
-    "@ultimat3/mail": "22.11.0",
-    "@ultimat3/manifest": "22.11.0",
-    "@ultimat3/mcp": "22.11.0",
-    "@ultimat3/money": "22.11.0",
-    "@ultimat3/notify": "22.11.0",
-    "@ultimat3/policy": "22.11.0",
-    "@ultimat3/pwa": "22.11.0",
-    "@ultimat3/query": "22.11.0",
-    "@ultimat3/realtime": "22.11.0",
-    "@ultimat3/render": "22.11.0",
-    "@ultimat3/schema": "22.11.0",
-    "@ultimat3/seo": "22.11.0",
-    "@ultimat3/storage": "22.11.0",
-    "@ultimat3/testing": "22.11.0",
-    "@ultimat3/time": "22.11.0",
+    "@ultimat3/action": "22.12.0",
+    "@ultimat3/admin": "22.12.0",
+    "@ultimat3/ai": "22.12.0",
+    "@ultimat3/auth": "22.12.0",
+    "@ultimat3/cache": "22.12.0",
+    "@ultimat3/core": "22.12.0",
+    "@ultimat3/db": "22.12.0",
+    "@ultimat3/entity": "22.12.0",
+    "@ultimat3/flags": "22.12.0",
+    "@ultimat3/http": "22.12.0",
+    "@ultimat3/i18n": "22.12.0",
+    "@ultimat3/jobs": "22.12.0",
+    "@ultimat3/mail": "22.12.0",
+    "@ultimat3/manifest": "22.12.0",
+    "@ultimat3/mcp": "22.12.0",
+    "@ultimat3/money": "22.12.0",
+    "@ultimat3/notify": "22.12.0",
+    "@ultimat3/policy": "22.12.0",
+    "@ultimat3/pwa": "22.12.0",
+    "@ultimat3/query": "22.12.0",
+    "@ultimat3/realtime": "22.12.0",
+    "@ultimat3/render": "22.12.0",
+    "@ultimat3/schema": "22.12.0",
+    "@ultimat3/seo": "22.12.0",
+    "@ultimat3/storage": "22.12.0",
+    "@ultimat3/testing": "22.12.0",
+    "@ultimat3/time": "22.12.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-reload-graph.ts

@@ -16,7 +16,9 @@
 // A module that DEFINES a primitive is PINNED and never leaves the registry: its exports are held
 // by every importer and by a registry that refuses a second definition of one name (an entity is
 // `X_ENTITY_DUPLICATE`; a second action instance is a handler nobody routes to). The closure stops
-// at a pinned module, and an edit to one still needs a restart — exactly what it needed before.
+// at a pinned module — and RECORDS it (`takeStalePins`): a pinned module above a change still holds
+// the old instance of what changed (a slice's service under its query, an admin page's view under
+// `defineAdmin`), so only a new process serves the save. `x dev` restarts on it (`dev-supervisor.ts`).
 
 // why: Bun ships no path API; import specifiers resolve against the importing file's directory.
 import { dirname, resolve } from 'node:path';
@@ -37,6 +39,27 @@ const nodes = new Map<string, Node>();
 /** Reverse edges: file → the files that import it. */
 const importers = new Map<string, Set<string>>();
 const pinned = new Set<string>();
+
+/** A pinned module that still holds the old instance of `changed` — or IS `changed`. */
+export interface StalePin {
+  /** The saved file, absolute. */
+  readonly changed: string;
+  /** The module that defines a primitive and was not re-evaluated, absolute. */
+  readonly pinned: string;
+}
+
+/** What the last rescans' closures stopped at, until `takeStalePins` reads it. */
+let stale: StalePin[] = [];
+
+/**
+ * Every pinned module a rescan since the last call could not refresh, sorted by pinned path, and
+ * forgets them. Empty: everything the saves reached was re-evaluated and the process serves it.
+ */
+export function takeStalePins(): readonly StalePin[] {
+  const taken = stale;
+  stale = [];
+  return taken;
+}
 /**
  * Edges cost a transpile scan and a resolve per import (~300 ms over notificado.co's 1200 modules),
  * so only the one process that rescans pays it: `x dev` turns this on before its first scan. Off,
@@ -54,6 +77,7 @@ export function resetReloadGraph(): void {
   nodes.clear();
   importers.clear();
   pinned.clear();
+  stale = [];
 }
 
 /** Marks a module that defines a primitive: never evicted, and the closure stops at it. */
@@ -185,18 +209,36 @@ async function changedFiles(root: string): Promise<string[]> {
   return changed;
 }
 
-/** `changed` and everything above it, stopping at — and excluding — every pinned module. */
+/**
+ * `changed` and everything above it, stopping at — and excluding — every pinned module. Each
+ * pinned module a walk stopped at is recorded against the change that reached it, once.
+ */
 function closure(changed: readonly string[]): Set<string> {
   const dirty = new Set<string>();
-  const stack = changed.filter((path) => !pinned.has(path));
-  while (stack.length > 0) {
-    const path = stack.pop();
-    if (path === undefined || dirty.has(path)) continue;
-    dirty.add(path);
-    for (const importer of importers.get(path) ?? []) {
-      if (!pinned.has(importer)) stack.push(importer);
+  const reached = new Map<string, string>();
+  for (const origin of changed) {
+    if (pinned.has(origin)) {
+      if (!reached.has(origin)) reached.set(origin, origin);
+      continue;
+    }
+    const seen = new Set<string>();
+    const stack = [origin];
+    while (stack.length > 0) {
+      const path = stack.pop();
+      if (path === undefined || seen.has(path)) continue;
+      seen.add(path);
+      dirty.add(path);
+      for (const importer of importers.get(path) ?? []) {
+        if (!pinned.has(importer)) stack.push(importer);
+        else if (!reached.has(importer)) reached.set(importer, origin);
+      }
     }
   }
+  const held = new Set(stale.map((entry) => entry.pinned));
+  const found = [...reached]
+    .filter(([module]) => !held.has(module))
+    .map(([module, origin]) => ({ changed: origin, pinned: module }));
+  stale = [...stale, ...found].sort((a, b) => (a.pinned < b.pinned ? -1 : 1));
   return dirty;
 }
 

package/src/bin.ts

@@ -33,6 +33,20 @@ if (local !== undefined) {
   process.exit(await child.exited);
 }
 
+// `x dev` supervises a child that serves (`dev-supervisor.ts`): a save that reaches a module which
+// defines a primitive is a restart, since no re-import in one process can serve it. After the
+// handoff above, so the supervisor and its children are the app's own CLI.
+// Imported only for `dev`: every other command's process must not load, or register, anything more.
+if (Bun.argv[2] === 'dev') {
+  const { devSupervision, freeDevPort, superviseDev } = await import('./dev-supervisor');
+  const supervision = devSupervision(Bun.argv.slice(2), Bun.env, freeDevPort);
+  if (supervision !== undefined) {
+    process.exit(
+      await superviseDev({ bin: import.meta.path, argv: supervision.argv, env: Bun.env }),
+    );
+  }
+}
+
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),

package/src/cmd-dev.ts

@@ -16,7 +16,8 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
-import { enableReloadTracking } from './app-reload-graph';
+import type { StalePin } from './app-reload-graph';
+import { enableReloadTracking, takeStalePins } from './app-reload-graph';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
 import { devSpec } from './cmd-dev-spec';
@@ -29,6 +30,7 @@ import { createStatementLedger } from './dev-n-plus-one';
 import { devPortFor } from './dev-port';
 import { coalesceReloads } from './dev-reload';
 import { devRouteTable } from './dev-route-table';
+import { childRestart, restartFinding } from './dev-supervisor';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
 import { holdUntilShutdown } from './hold';
@@ -108,6 +110,12 @@ export interface StartDevOptions {
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly roles?: readonly Role[];
   readonly onReload?: (file: string, durationMs: number) => void;
+  /**
+   * A save reached a module that defines a primitive, so this process cannot serve it
+   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
+   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
+   */
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
 }
 
 /**
@@ -294,8 +302,14 @@ async function bootDev(
       state.islands = islands;
       for (const path of isr.store().paths()) isr.store().delete(path);
       state.reloads += 1;
-      state.reloadFinding = undefined;
-      options.onReload?.(file, Math.round(performance.now() - started));
+      // Read on EVERY rebuild, so a pin one save reached is never reported against the next save.
+      const pins = takeStalePins();
+      state.reloadFinding =
+        pins.length > 0 && options.onRestart === undefined
+          ? restartFinding(options.root, pins)
+          : undefined;
+      if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
+      else options.onReload?.(file, Math.round(performance.now() - started));
     },
     // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
     // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
@@ -375,6 +389,7 @@ export const devCommand: CliCommand = {
     // The directory is CLAIMED from here down, so a boot that throws has to give it back — the
     // `releaseBoot` shape, with one acquisition. Without it the first failed `x dev` in a shell
     // refuses every later one with a pid that is no longer running.
+    const restart = childRestart(root, ctx.env);
     const server = await startDev({
       root,
       port,
@@ -384,6 +399,8 @@ export const devCommand: CliCommand = {
         if (!ctx.args.json)
           process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
       },
+      // Supervised, a save this process cannot serve is a drain and an exit for a fresh child.
+      ...restart.options,
     }).catch((error: unknown) => {
       release();
       throw error;
@@ -461,12 +478,17 @@ export const devCommand: CliCommand = {
     // directory locked by a process that no longer exists.
     return {
       ...result,
-      hold: holdUntilShutdown('dev', async () => {
-        // The lock first: a stop() that throws must not leave a file claiming this pid still owns
-        // the directory, because the next boot would then refuse for a process that is gone.
-        clearLock(services.stateDir);
-        await server.stop();
-      }),
+      hold: holdUntilShutdown(
+        'dev',
+        async () => {
+          // The lock first: a stop() that throws must not leave a file claiming this pid still owns
+          // the directory, because the next boot would then refuse for a process that is gone.
+          clearLock(services.stateDir);
+          await server.stop();
+        },
+        // Released — the port, the lock and the embedded database are free for the next child.
+        { exit: restart.exit },
+      ),
     };
   },
 };

package/src/dev-port.ts

@@ -4,7 +4,7 @@
 
 import { PORT_RANGE, readIntFlag } from './flag-number';
 import type { ParsedArgs } from './parse';
-import { portFromEnv } from './serve';
+import { portFromEnv } from './serve-env';
 
 export const DEFAULT_DEV_PORT = 3000;
 

package/src/dev-supervisor.ts

@@ -0,0 +1,178 @@
+// `x dev` as two processes: this one supervises, a child serves. A save that reaches a module which
+// DEFINES a primitive (`app-reload-graph.ts`'s pinned modules — a query over a slice's service, an
+// admin page's view under `defineAdmin`) cannot be served by re-importing: the registries and the
+// route table hold that module's first instance. The child exits `DEV_RESTART_EXIT_CODE` instead
+// of logging "reloaded" over stale code, and this loop boots a fresh one on the same port. Every
+// other save stays the in-process reload it was — a restart is paid only where nothing else works.
+
+// why: Bun has no path API; the restart line names files relative to the app root.
+import { relative } from 'node:path';
+import { drain } from '@ultimat3/core';
+import type { StalePin } from './app-reload-graph';
+import { devSpec } from './cmd-dev-spec';
+import { devPortFor } from './dev-port';
+import { msg } from './messages';
+import type { Finding } from './output';
+import { parseArgs } from './parse';
+
+/** Set on the child: it serves, and a pinned save makes it exit for a restart. */
+export const DEV_CHILD_ENV = 'ULTIMATE_DEV_CHILD';
+/** `EX_TEMPFAIL`: "try again" — the one exit code the supervisor answers with a new child. */
+export const DEV_RESTART_EXIT_CODE = 75;
+
+/** What the supervisor runs the child with: the argv, its port pinned. */
+export interface DevSupervision {
+  readonly argv: readonly string[];
+}
+
+/**
+ * Whether this `x …` invocation is a supervised `x dev`, and with what child argv. Not for the
+ * child itself, `--once` (it boots, reports and exits — nothing to restart), `--help`, or an argv
+ * the parse refuses (`dispatch` reports that, in the child's place). `--port 0` is pinned to one
+ * free port here, so a restarted child binds the address the first one printed.
+ */
+export function devSupervision(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  pickPort: () => number,
+): DevSupervision | undefined {
+  if (argv[0] !== 'dev' || env[DEV_CHILD_ENV] === '1') return undefined;
+  try {
+    const args = parseArgs(argv, [devSpec]);
+    if (args.help || args.flags.get('once') === true) return undefined;
+    return { argv: devPortFor(args, env) === 0 ? withPort(argv, pickPort()) : argv };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A port nothing holds right now, asked of the OS — what `--port 0` is pinned to. */
+export function freeDevPort(): number {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
+  const port = probe.port ?? 0;
+  probe.stop(true);
+  return port;
+}
+
+/** `argv` with every `--port` removed and `--port <port>` appended. */
+function withPort(argv: readonly string[], port: number): readonly string[] {
+  const out: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? '';
+    if (token === '--port') {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--port=')) continue;
+    out.push(token);
+  }
+  return [...out, '--port', String(port)];
+}
+
+/** The child as the loop sees it — `Bun.spawn`'s answer, narrowed so a test can hand one in. */
+export interface DevChild {
+  readonly exited: Promise<number>;
+  kill(signal: 'SIGINT' | 'SIGTERM'): void;
+}
+
+export interface SuperviseDevInput {
+  readonly bin: string;
+  readonly argv: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly spawn?: (
+    command: readonly string[],
+    env: Record<string, string | undefined>,
+  ) => DevChild;
+}
+
+const spawnInherited = (
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): DevChild =>
+  Bun.spawn([...command], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit', env });
+
+/**
+ * Runs children until one exits with anything but `DEV_RESTART_EXIT_CODE`, and answers that code.
+ * SIGINT and SIGTERM are forwarded — a terminal's Ctrl-C reaches the child on its own too, and its
+ * drain is idempotent — and once one arrived no child is started again: a Ctrl-C during a restart
+ * is a stop, never a respawn.
+ */
+export async function superviseDev(input: SuperviseDevInput): Promise<number> {
+  const spawn = input.spawn ?? spawnInherited;
+  let child: DevChild | undefined;
+  let stopping = false;
+  const forward = (signal: 'SIGINT' | 'SIGTERM') => (): void => {
+    stopping = true;
+    child?.kill(signal);
+  };
+  const onInt = forward('SIGINT');
+  const onTerm = forward('SIGTERM');
+  process.on('SIGINT', onInt);
+  process.on('SIGTERM', onTerm);
+  try {
+    for (;;) {
+      child = spawn([process.execPath, input.bin, ...input.argv], {
+        ...input.env,
+        [DEV_CHILD_ENV]: '1',
+      });
+      const code = await child.exited;
+      if (code !== DEV_RESTART_EXIT_CODE || stopping) return code;
+    }
+  } finally {
+    process.off('SIGINT', onInt);
+    process.off('SIGTERM', onTerm);
+  }
+}
+
+/** `apps/web/app/greet/service.ts under apps/web/app/greet/queries.ts`, one per pinned module. */
+export function restartReason(root: string, pins: readonly StalePin[]): string {
+  return pins
+    .map(({ changed, pinned }) =>
+      changed === pinned
+        ? relative(root, pinned)
+        : `${relative(root, changed)} under ${relative(root, pinned)}`,
+    )
+    .join(', ');
+}
+
+/** `/_x`'s finding for a process nothing supervises (an embedded `startDev()` with no `onRestart`). */
+export function restartFinding(root: string, pins: readonly StalePin[]): Finding {
+  const first = pins[0];
+  return {
+    code: 'X_DEV_RESTART_REQUIRED',
+    cause: `${restartReason(root, pins)} — a module that defines a primitive still holds the code before the save, and re-importing it would register a second definition`,
+    fix: 'restart x dev (a supervised `x dev` restarts itself; an embedded startDev() passes onRestart)',
+    at: first === undefined ? '' : relative(root, first.pinned),
+  };
+}
+
+/** The child's half: what `startDev` is handed, and what the hold calls once released. */
+export interface ChildRestart {
+  readonly options: { readonly onRestart?: (pins: readonly StalePin[]) => void };
+  readonly exit: (code: number) => void;
+}
+
+/**
+ * Only a supervised child restarts: it says why on stderr (fd 1 may be `--json`'s one document),
+ * starts core's drain — the hold then releases the lock, the port and the embedded database — and
+ * exits `DEV_RESTART_EXIT_CODE` once released. Anything else keeps the finding on `/_x`.
+ */
+export function childRestart(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): ChildRestart {
+  if (env[DEV_CHILD_ENV] !== '1') return { options: {}, exit: () => undefined };
+  let restarting = false;
+  return {
+    options: {
+      onRestart: (pins) => {
+        process.stderr.write(`${msg('cli.dev.restart', { reason: restartReason(root, pins) })}\n`);
+        restarting = true;
+        void drain('restart');
+      },
+    },
+    exit: () => {
+      if (restarting) process.exit(DEV_RESTART_EXIT_CODE);
+    },
+  };
+}

package/src/error-codes.ts

@@ -203,6 +203,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_VERIFY_MERGE_INCOMPLETE',
   'X_VERIFY_MERGE_INPUT',
   'X_SITEMAP_EXTRA_INVALID',
+  'X_DEV_RESTART_REQUIRED',
 ] as const;
 
 /**
@@ -355,6 +356,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_VERIFY_MERGE_INCOMPLETE: 'x verify merge was handed parts that do not add up to the whole gate',
   X_VERIFY_MERGE_INPUT: 'a part handed to x verify merge is not an x verify --json document',
   X_SITEMAP_EXTRA_INVALID: 'a seo.sitemap.extra path names no public page',
+  X_DEV_RESTART_REQUIRED:
+    'a save reached a module that defines a primitive; only a new process serves it',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/mcp-errors.ts

@@ -253,6 +253,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only budgets --json   # after moving each await in Page into export const load',
   X_SITEMAP_EXTRA_INVALID:
     'x routes --json   # then list in seo.sitemap.extra only a path a registered app/ route without a policy answers',
+  X_DEV_RESTART_REQUIRED:
+    'x dev --json   # a fresh process; the supervised x dev restarts itself on such a save',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -76,6 +76,7 @@ const CATALOG = {
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  'cli.dev.restart': 'restarting: {reason} — a module that defines a primitive holds the old code',
   // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
   // reader knows why the boot paused, and never a finding.
   'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',