@ultimat3/cli 22.12.0 → 22.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.12.0",
+  "version": "22.13.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.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",
+    "@ultimat3/action": "22.13.0",
+    "@ultimat3/admin": "22.13.0",
+    "@ultimat3/ai": "22.13.0",
+    "@ultimat3/auth": "22.13.0",
+    "@ultimat3/cache": "22.13.0",
+    "@ultimat3/core": "22.13.0",
+    "@ultimat3/db": "22.13.0",
+    "@ultimat3/entity": "22.13.0",
+    "@ultimat3/flags": "22.13.0",
+    "@ultimat3/http": "22.13.0",
+    "@ultimat3/i18n": "22.13.0",
+    "@ultimat3/jobs": "22.13.0",
+    "@ultimat3/mail": "22.13.0",
+    "@ultimat3/manifest": "22.13.0",
+    "@ultimat3/mcp": "22.13.0",
+    "@ultimat3/money": "22.13.0",
+    "@ultimat3/notify": "22.13.0",
+    "@ultimat3/policy": "22.13.0",
+    "@ultimat3/pwa": "22.13.0",
+    "@ultimat3/query": "22.13.0",
+    "@ultimat3/realtime": "22.13.0",
+    "@ultimat3/render": "22.13.0",
+    "@ultimat3/schema": "22.13.0",
+    "@ultimat3/seo": "22.13.0",
+    "@ultimat3/storage": "22.13.0",
+    "@ultimat3/testing": "22.13.0",
+    "@ultimat3/time": "22.13.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets.ts

@@ -60,8 +60,9 @@ export interface BuildStats {
  * rule stops being read as a measurement. `.x/` survives across framework upgrades, and
  * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
  * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
+ * `3`: an island entry's imported chunks are charged, each once per document (shared chunks).
  */
-export const BUILD_STATS_RULES = 2;
+export const BUILD_STATS_RULES = 3;
 
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
@@ -252,6 +253,31 @@ const carriesJson = (attrs: string): boolean => {
  */
 const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
 
+/**
+ * Static imports and `import()` both. A chunk reached by `import()` was INLINED into its island
+ * before islands were split, so charging it keeps a route's number what it was; and it is fetched
+ * the moment the island needs it, which is before the page does what it was loaded for.
+ */
+const LOADS: ReadonlySet<string> = new Set(['import-statement', 'dynamic-import']);
+
+/** Same-origin paths `code`, served at `url`, makes the browser load. Cross-origin and bare are not this build's. */
+function loadedBy(url: string, code: string): readonly string[] {
+  let imports: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    imports = new Bun.Transpiler({ loader: 'js' }).scanImports(code);
+  } catch {
+    // A file that does not parse as JavaScript imports nothing this gate can name; its own bytes
+    // are already charged.
+    return [];
+  }
+  const base = new URL(url, 'https://artifact.invalid');
+  return imports
+    .filter((one) => LOADS.has(one.kind) && /^\.{0,2}\//.test(one.path))
+    .map((one) => new URL(one.path, base))
+    .filter((target) => target.origin === base.origin)
+    .map((target) => target.pathname);
+}
+
 /** One executable module the document names, and what it weighs on disk. */
 export interface MeasuredEntry {
   readonly url: string;
@@ -337,7 +363,8 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (!url.startsWith('/') || fetched.has(url)) return;
     fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
-    const bytes = (await file.exists()) ? file.size : 0;
+    const exists = await file.exists();
+    const bytes = exists ? file.size : 0;
     // Counted and set aside, not skipped: the bytes are real and a reader is owed the number.
     // Kept out of `entries` as well as out of `jsBytes`, because `entries` is what a finding reads
     // to name the heaviest import — and on a fresh scaffold every route's `heaviestChain` was
@@ -348,6 +375,12 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     }
     entries.push({ url, bytes });
     jsBytes += bytes;
+    // And every file THAT one loads: an island entry imports its shared chunks (`island-link.ts`),
+    // and each is a fetch the browser makes before the island is whole. Through `weigh`, so a chunk
+    // two islands share is charged once and a cycle ends at the first repeat.
+    if (exists) {
+      for (const next of loadedBy(url, await file.text())) await weigh(next);
+    }
   };
 
   for (const match of html.matchAll(SCRIPT_TAG)) {

package/src/dev-child-watch.ts

@@ -0,0 +1,144 @@
+// A supervised `x dev` child that outlives what it serves stops itself. Two facts nothing else in
+// the child watched: its SUPERVISOR is gone (SIGKILLed, so it forwarded nothing — the child was
+// reparented to init and served forever), and its APP ROOT is gone (the jobs worker, the outbox
+// relay and the scheduler then poll an embedded database whose directory no longer exists, at
+// 100% CPU, measured at ~50 MB/s of heap growth). Found on a laptop, 2026-09-29: two children of
+// `cmd-dev-restart.live.test.ts`, six hours old, ppid 1, cwd deleted, one at 7 GB.
+//
+// And a stop that does not finish is finished for it. A drain is bounded by core's deadline, but a
+// loop starved by a spin like the one above reaches its timers late or never, so every stop this
+// child begins — a signal, the watch below, a restart — carries a hard exit past that bound.
+
+import { existsSync } from 'node:fs'; // why: one synchronous stat per tick; Bun has no sync exists.
+import { drain, drainDeadlineMs, ERROR_DOCS_URL, finiteCount, logger } from '@ultimat3/core';
+import { MIN_RELEASE_MS } from './hold';
+
+/** Set on the child by the supervisor: its own pid, so a child started after it died still knows. */
+export const DEV_SUPERVISOR_PID_ENV = 'ULTIMATE_DEV_SUPERVISOR_PID';
+
+/** How often the child asks. A second: a dead supervisor's child is gone about a second later. */
+export const DEV_CHILD_WATCH_MS = 1_000;
+
+/** Past the drain's own deadline and `hold.ts`'s release floor, a stop is not going to finish. */
+export const devHardExitMs = (): number => drainDeadlineMs() + MIN_RELEASE_MS + 5_000;
+
+export type DevChildGone = 'supervisor' | 'root';
+
+export interface DevChildWatchInput {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Called once, when the child decides to leave. */
+  readonly leave: (why: DevChildGone) => void;
+  /** Test seams: the defaults read the process and the disk. */
+  readonly parentPid?: () => number;
+  readonly rootExists?: (root: string) => boolean;
+  readonly intervalMs?: number;
+}
+
+/** The supervisor's pid, or `undefined` when this process was not started by one. */
+export function supervisorPid(
+  env: Readonly<Record<string, string | undefined>>,
+): number | undefined {
+  const said = Number(env[DEV_SUPERVISOR_PID_ENV]);
+  return Number.isInteger(said) && said > 0 ? said : undefined;
+}
+
+/**
+ * Polls both facts until one fails, then calls `leave` once and stops. Answers the stop.
+ * `process.ppid` rather than a pipe from the supervisor: stdin is the terminal's (`inherit`), and
+ * a supervisor that died before the first tick is still caught — its pid is never ours again.
+ */
+export function watchDevChild(input: DevChildWatchInput): () => void {
+  const expected = supervisorPid(input.env);
+  const parent = input.parentPid ?? (() => process.ppid);
+  const exists = input.rootExists ?? existsSync;
+  let left = false;
+  const timer = setInterval(
+    () => {
+      if (left) return;
+      const why: DevChildGone | undefined =
+        expected !== undefined && parent() !== expected
+          ? 'supervisor'
+          : exists(input.root)
+            ? undefined
+            : 'root';
+      if (why === undefined) return;
+      left = true;
+      clearInterval(timer);
+      input.leave(why);
+    },
+    finiteCount('watchDevChild', 'intervalMs', input.intervalMs ?? DEV_CHILD_WATCH_MS, 1),
+  );
+  // Never the reason the process is alive — the hold is, and a watch outliving it would be a leak.
+  timer.unref();
+  return () => {
+    left = true;
+    clearInterval(timer);
+  };
+}
+
+/** The line the child leaves on stderr (fd 1 may be `--json`'s one document). */
+export function reportGone(root: string, why: DevChildGone): void {
+  if (why === 'root') {
+    logger.error('X_DEV_ROOT_GONE', {
+      code: 'X_DEV_ROOT_GONE',
+      cause: `${root}, the app root this x dev serves, no longer exists — nothing is left to serve, so it stops instead of polling a database whose directory is gone`,
+      fix: 'x dev   # from the app root, once it exists again (restored, re-cloned or moved back)',
+      docs: ERROR_DOCS_URL,
+    });
+    return;
+  }
+  logger.warn('dev.supervisor.gone', {
+    cause:
+      'the x dev supervisor that started this child exited without stopping it (a SIGKILL cannot be forwarded), so the child stops itself',
+  });
+}
+
+/**
+ * One hard exit, armed by the first stop and never disarmed: it is NOT unref'd, because it is the
+ * one timer that must still fire once everything else is done or stuck. `exit` is the test seam.
+ */
+export function hardExit(
+  exit: (code: number) => void,
+  afterMs: () => number = devHardExitMs,
+): (code: number) => void {
+  let armed = false;
+  return (code: number): void => {
+    if (armed) return;
+    armed = true;
+    const ms = afterMs();
+    setTimeout(() => {
+      logger.warn('dev.stop.forced', {
+        cause: `x dev was still stopping ${String(ms)}ms after it began, so it exits without finishing`,
+      });
+      exit(code);
+    }, ms);
+  };
+}
+
+/**
+ * The child's watch, wired to core's drain: the supervisor's death or the root's, and SIGINT or
+ * SIGTERM, each begin a stop that ends within `devHardExitMs` however the drain fares. `onGone`
+ * marks why, so the hold's exit can answer a code.
+ */
+export function startDevChildWatch(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  onGone: (why: DevChildGone) => void,
+): { readonly stopping: (code: number) => void } {
+  const stopping = hardExit((code) => process.exit(code));
+  // Beside core's own handlers, never instead of them: the drain is theirs, the deadline is this.
+  process.on('SIGINT', () => stopping(130));
+  process.on('SIGTERM', () => stopping(143));
+  watchDevChild({
+    root,
+    env,
+    leave: (why) => {
+      reportGone(root, why);
+      onGone(why);
+      stopping(why === 'root' ? 1 : 0);
+      void drain(why === 'root' ? 'dev-root-gone' : 'dev-supervisor-gone');
+    },
+  });
+  return { stopping };
+}

package/src/dev-live-fixture.ts

@@ -0,0 +1,122 @@
+// The `x dev` live tests' process discipline, in one place: spawn the supervisor, read its two
+// streams, and — on every path, a failing one included — reap every process it started and prove
+// none is left. Two children of `cmd-dev-restart.live.test.ts` ran for six hours with ppid 1 and a
+// deleted cwd because the test's `finally` SIGKILLed the supervisor, which cannot forward a signal
+// it never gets, and nothing then looked for what it had started (2026-09-29).
+
+import { readdirSync, readlinkSync } from 'node:fs'; // why: /proc is read synchronously; Bun has no readlink.
+
+/** One pump per stream — reading a stream twice closes its reader under the first `for await`. */
+export function pump(stream: ReadableStream<Uint8Array>): { seen: () => string } {
+  const decoder = new TextDecoder();
+  let seen = '';
+  void (async () => {
+    for await (const chunk of stream) seen += decoder.decode(chunk, { stream: true });
+  })();
+  return { seen: () => seen };
+}
+
+/** Poll the buffer until `marker` shows up. The caller's own timeout is the deadline. */
+export async function waitFor(output: { seen: () => string }, marker: string): Promise<string> {
+  for (;;) {
+    const seen = output.seen();
+    if (seen.includes(marker)) return seen;
+    await Bun.sleep(25);
+  }
+}
+
+/** Whether `pid` is still a process — signal 0 delivers nothing and only asks. */
+export function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every descendant of `pid`, depth first — asked while `pid` lives, or its children are init's. */
+export function descendantsOf(pid: number): readonly number[] {
+  const out = Bun.spawnSync(['pgrep', '-P', String(pid)]).stdout.toString();
+  const children = out
+    .split('\n')
+    .map((line) => Number(line.trim()))
+    .filter((child) => Number.isInteger(child) && child > 0);
+  return children.flatMap((child) => [child, ...descendantsOf(child)]);
+}
+
+/**
+ * Every process whose cwd is `dir` — a deleted one included, which Linux spells `<dir> (deleted)`.
+ * The one question that finds an orphan after its parent is gone, when no process tree reaches it.
+ * Empty where there is no `/proc` (macOS): the descendant walk is then the whole answer.
+ */
+export function processesIn(dir: string): readonly number[] {
+  let pids: readonly string[];
+  try {
+    pids = readdirSync('/proc').filter((name) => /^\d+$/.test(name));
+  } catch {
+    return [];
+  }
+  const found: number[] = [];
+  for (const pid of pids) {
+    try {
+      const cwd = readlinkSync(`/proc/${pid}/cwd`);
+      if (cwd === dir || cwd === `${dir} (deleted)`) found.push(Number(pid));
+    } catch {
+      // Gone between the listing and the read, or not ours to read.
+    }
+  }
+  return found;
+}
+
+/** Whether anything still answers on `port` at the loopback address `x dev` binds. */
+export async function listening(port: number): Promise<boolean> {
+  try {
+    const socket = await Bun.connect({
+      hostname: '127.0.0.1',
+      port,
+      socket: { data: () => undefined },
+    });
+    socket.end();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * SIGKILL `pids`, then wait until each is gone. A test's last resort, run in `finally` — by then
+ * every graceful stop the test meant to prove has had its chance. `performance.now()`, never
+ * `Date.now()`: the test preload freezes the wall clock, and a deadline read off it never arrives.
+ */
+export async function reap(pids: readonly number[], timeoutMs = 10_000): Promise<void> {
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // Already gone.
+    }
+  }
+  const until = performance.now() + timeoutMs;
+  while (pids.some(alive) && performance.now() < until) await Bun.sleep(25);
+}
+
+/** What was left: the pids still in `dir` and whether `port` still answers. Both empty is clean. */
+export async function leftovers(
+  dir: string,
+  port: number | undefined,
+): Promise<{ readonly pids: readonly number[]; readonly port: boolean }> {
+  return {
+    pids: processesIn(dir),
+    port: port === undefined ? false : await listening(port),
+  };
+}
+
+/**
+ * The net under a TIMED-OUT test: bun abandons its body without running `finally`, so an
+ * `afterEach` reaps whatever still runs in the fixture directory — the only handle left on an
+ * orphan whose parent is gone.
+ */
+export async function reapIn(dir: string): Promise<void> {
+  await reap(processesIn(dir));
+}

package/src/dev-supervisor.ts

@@ -10,6 +10,8 @@ import { relative } from 'node:path';
 import { drain } from '@ultimat3/core';
 import type { StalePin } from './app-reload-graph';
 import { devSpec } from './cmd-dev-spec';
+import type { DevChildGone } from './dev-child-watch';
+import { DEV_SUPERVISOR_PID_ENV, startDevChildWatch, supervisorPid } from './dev-child-watch';
 import { devPortFor } from './dev-port';
 import { msg } from './messages';
 import type { Finding } from './output';
@@ -96,10 +98,16 @@ const spawnInherited = (
  * 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.
+ *
+ * Every other way out stops the child too: an uncaught error or a `process.exit` here reaches the
+ * `exit` listener, which SIGTERMs a child still running. The one way no listener sees is a SIGKILL
+ * of this process — the child's own watch (`dev-child-watch.ts`) answers that, from its side, off
+ * the pid this loop hands it.
  */
 export async function superviseDev(input: SuperviseDevInput): Promise<number> {
   const spawn = input.spawn ?? spawnInherited;
   let child: DevChild | undefined;
+  let running = false;
   let stopping = false;
   const forward = (signal: 'SIGINT' | 'SIGTERM') => (): void => {
     stopping = true;
@@ -107,20 +115,28 @@ export async function superviseDev(input: SuperviseDevInput): Promise<number> {
   };
   const onInt = forward('SIGINT');
   const onTerm = forward('SIGTERM');
+  const onExit = (): void => {
+    if (running) child?.kill('SIGTERM');
+  };
   process.on('SIGINT', onInt);
   process.on('SIGTERM', onTerm);
+  process.on('exit', onExit);
   try {
     for (;;) {
       child = spawn([process.execPath, input.bin, ...input.argv], {
         ...input.env,
         [DEV_CHILD_ENV]: '1',
+        [DEV_SUPERVISOR_PID_ENV]: String(process.pid),
       });
+      running = true;
       const code = await child.exited;
+      running = false;
       if (code !== DEV_RESTART_EXIT_CODE || stopping) return code;
     }
   } finally {
     process.off('SIGINT', onInt);
     process.off('SIGTERM', onTerm);
+    process.off('exit', onExit);
   }
 }
 
@@ -156,23 +172,36 @@ export interface ChildRestart {
  * 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`.
+ *
+ * A child its supervisor named (`DEV_SUPERVISOR_PID_ENV`) also watches for that supervisor's death
+ * and its app root's, and stops on either — exit 1 for a root that is gone, which the supervisor,
+ * if it is still there, answers by stopping rather than respawning into nothing.
  */
 export function childRestart(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
+  watch: typeof startDevChildWatch = startDevChildWatch,
 ): ChildRestart {
   if (env[DEV_CHILD_ENV] !== '1') return { options: {}, exit: () => undefined };
-  let restarting = false;
+  let leaving: 'restart' | DevChildGone | undefined;
+  const watched =
+    supervisorPid(env) === undefined
+      ? undefined
+      : watch(root, env, (why) => {
+          leaving ??= why;
+        });
   return {
     options: {
       onRestart: (pins) => {
         process.stderr.write(`${msg('cli.dev.restart', { reason: restartReason(root, pins) })}\n`);
-        restarting = true;
+        leaving ??= 'restart';
+        watched?.stopping(DEV_RESTART_EXIT_CODE);
         void drain('restart');
       },
     },
     exit: () => {
-      if (restarting) process.exit(DEV_RESTART_EXIT_CODE);
+      if (leaving === 'restart') process.exit(DEV_RESTART_EXIT_CODE);
+      if (leaving === 'root') process.exit(1);
     },
   };
 }

package/src/error-codes.ts

@@ -204,6 +204,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_VERIFY_MERGE_INPUT',
   'X_SITEMAP_EXTRA_INVALID',
   'X_DEV_RESTART_REQUIRED',
+  'X_DEV_ROOT_GONE',
 ] as const;
 
 /**
@@ -358,6 +359,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   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',
+  X_DEV_ROOT_GONE: 'the app root x dev serves was deleted or moved',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/index.ts

@@ -107,7 +107,7 @@ export { ICON_BASE_PATH, ICON_SOURCE } from './icon-assets';
 // `@ultimat3/testing` takes this function as its `build` parameter (issue #260). `discoverIslands`,
 // `islandBundle`, `writeIslands`, `ISLAND_BASE_PATH` and `ISLAND_GLOB` stay internal: they are
 // `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
-export type { IslandChunk } from './island-bundle';
+export type { IslandChunk, SharedChunk } from './island-bundle';
 export { buildIslands } from './island-bundle';
 export { JOB_STATES } from './jobs-report';
 export { renderJobTable } from './jobs-table';