@ultimat3/cli 22.12.0 → 22.14.0

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-route-table.ts

@@ -58,8 +58,10 @@ export interface DevRouteTable {
   readonly theme: ThemeBoot;
   /** The app's own error pages' inline styles, admitted the same way. */
   readonly errorStyles: readonly string[];
-  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  /** Where the app's default MCP endpoint was mounted, or `null`. */
   readonly mcpPath: string | null;
+  /** Every mounted MCP endpoint's path, default first — one per population the app serves. */
+  readonly mcpPaths: readonly string[];
 }
 
 export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
@@ -156,5 +158,5 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
   ];
 
-  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+  return { routes, theme, errorStyles, mcpPath: mcpMount.path, mcpPaths: mcpMount.paths };
 }

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';