@ultimat3/cli 29.4.0 → 30.0.0

package/src/dev-boot.ts

@@ -10,6 +10,7 @@ import { setStatementObserver } from '@ultimat3/db';
 import type { OverlayNotice, RequestContext } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import { loadSignInPath } from './app-auth';
+import { loadAppConfig } from './app-config-load';
 import { appManifest } from './app-manifest';
 import type { StalePin } from './app-reload-graph';
 import { enableReloadTracking } from './app-reload-graph';
@@ -23,11 +24,14 @@ import { devRebuilder } from './dev-rebuild';
 import { devRouteTable } from './dev-route-table';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
+import { armFailureCapture } from './failure-capture-boot';
 import { buildIslands } from './island-bundle';
 import { FRAME_STYLE } from './island-harness';
 import type { Finding } from './output';
+import { plainRoutes } from './plain-routes';
 import type { RunningRoles } from './role-start';
 import { DEV_ROLES, startRoles } from './role-start';
+import { armRowSecurity, rowSecurityDeclared } from './row-security-boot';
 import type { DevServices } from './runtime-bindings';
 import { resolveServices, withRealtimeEvents } from './runtime-bindings';
 import { attachedIsr } from './runtime-isr';
@@ -175,6 +179,16 @@ async function bootDev(
     appFindings: app.findings,
     islands: await buildIslands(options.root),
   };
+  // `serve-boot.ts`'s guard, at its point: after the app's modules, before any role serves. On
+  // PGlite the boot serves as `x_app`; on an external database a role that bypasses is refused.
+  const appConfig = await loadAppConfig(options.root);
+  acquired.push(
+    await armRowSecurity(rowSecurityDeclared(appConfig), {
+      embedded: services.db.mode === 'embedded',
+    }),
+  );
+  // ON in `x dev` whatever `app.config.ts` says: a 5xx here is one `x repro <requestId>` away.
+  acquired.push(armFailureCapture(appConfig, { force: true }));
   // The manifest's build id is a content hash of every fact below it, so a dev document's
   // `x-ultimate-build` header names the exact shape the client was served against. Pinned at
   // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
@@ -210,19 +224,21 @@ async function bootDev(
   // ttl); attached, so a tag bust reaches it too. Released with the roles.
   const { isr, release: releaseIsr } = attachedIsr({ buildId });
   acquired.push(releaseIsr);
-  const { routes, theme, speculation, inlineStyles, mcpPath, mcpPaths } = await devRouteTable({
-    isr,
-    root: options.root,
-    env: options.env,
-    buildId,
-    storage: runtime.storage,
-    dashboard,
-    islands: () => state.islands,
-    realtime: runtime.realtime,
-    rateLimitStore: appRuntime?.rateLimitStore ?? runtime.rateLimitStore,
-    appRoutes: appRuntime?.routes,
-    images: appRuntime?.images,
-  });
+  const { routes, theme, speculation, zone, inlineStyles, mcpPath, mcpPaths } = await devRouteTable(
+    {
+      isr,
+      root: options.root,
+      env: options.env,
+      buildId,
+      storage: runtime.storage,
+      dashboard,
+      islands: () => state.islands,
+      realtime: runtime.realtime,
+      rateLimitStore: appRuntime?.rateLimitStore ?? runtime.rateLimitStore,
+      appRoutes: plainRoutes(appRuntime?.routes),
+      images: appRuntime?.images,
+    },
+  );
 
   // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
   // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
@@ -247,7 +263,11 @@ async function bootDev(
     // The `/_x` shell, the harness's frame, the app's own error pages and its brand — the inline
     // bodies this process serves; the app's surfaces are content-hashed files `'self'` admits.
     inlineStyles: [await devShellStyle(), FRAME_STYLE, ...inlineStyles],
-    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    inlineScripts: [
+      theme.cspSource,
+      ...(speculation === undefined ? [] : [speculation.cspSource]),
+      ...(zone === undefined ? [] : [zone.cspSource]),
+    ],
     // The overlay renders this request's own loops under the error it is already showing.
     // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
@@ -259,7 +279,7 @@ async function bootDev(
   });
   acquired.push(() => running.stop());
 
-  const rebuild = devRebuilder(options, state, isr);
+  const rebuild = devRebuilder(options, state, isr, () => running.refreshDevices());
   // Watched one directory at a time, so an ignored one costs no descriptor at all — `dev-watch.ts`
   // decides which, from the app's own `.gitignore`. A recursive watch on the root registered one
   // inotify descriptor per directory in the tree, `.git/`, `node_modules/` and the `.x/` this

package/src/dev-child-watch.ts

@@ -28,6 +28,13 @@ export const devHardExitMs = (): number => drainDeadlineMs() + MIN_RELEASE_MS +
 
 export type DevChildGone = 'supervisor' | 'root';
 
+/**
+ * Why a supervised child is leaving, as its restart bookkeeping records it: `signal` is a stop it
+ * was sent (SIGINT, SIGTERM, the supervisor's drain message — `x stop`), which a save landing during
+ * the drain must never turn into a restart.
+ */
+export type DevChildLeaving = DevChildGone | 'signal';
+
 export interface DevChildWatchInput {
   readonly root: string;
   readonly env: Readonly<Record<string, string | undefined>>;
@@ -169,16 +176,21 @@ export const signalExitCode = (signal: 'SIGINT' | 'SIGTERM'): number =>
 export function startDevChildWatch(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
-  onGone: (why: DevChildGone) => void,
+  onGone: (why: DevChildLeaving) => 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(signalExitCode('SIGINT')));
-  process.on('SIGTERM', () => stopping(signalExitCode('SIGTERM')));
+  // `onGone('signal')` first, so a save during this drain cannot become a restart (`childRestart`).
+  const stop = (signal: 'SIGINT' | 'SIGTERM'): void => {
+    onGone('signal');
+    stopping(signalExitCode(signal));
+  };
+  process.on('SIGINT', () => stop('SIGINT'));
+  process.on('SIGTERM', () => stop('SIGTERM'));
   // The supervisor's stop, on every platform: the same drain a signal begins, by message.
   process.on('message', (message: unknown) => {
     if (!isDevDrainMessage(message)) return;
-    stopping(signalExitCode(message.signal));
+    stop(message.signal);
     void drain(message.signal);
   });
   watchDevChild({

package/src/dev-dashboard-guard.ts

@@ -57,7 +57,14 @@ export function assertSameOrigin(request: UltimateRequest): void {
     listed: () => false,
     listName: 'no list — /_x admits its own origin only',
   });
-  if (!verdict.ok) throw csrfBlocked(request.pathname, verdict.reason, request.ctx.ip);
+  if (!verdict.ok) {
+    throw csrfBlocked(
+      request.pathname,
+      verdict.reason,
+      request.ctx.ip,
+      selfOrigin(request.url, request.ctx.https),
+    );
+  }
 }
 
 /** The SQL panel's one input, from a form or a JSON body — `request.body` parses either. */

package/src/dev-dashboard.ts

@@ -8,6 +8,7 @@ import type {
   DevSources,
   InvalidationFact,
   MailFact,
+  MailTemplateFact,
   ManifestFact,
   PolicyFact,
   RequestTrace,
@@ -25,12 +26,14 @@ import { recentInvalidations } from '@ultimat3/cache';
 import type { Role } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
 import { jsonResponse } from '@ultimat3/http';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { MemoryMailDriver } from '@ultimat3/mail';
 import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
 import { appManifest, readAppManifest } from './app-manifest';
 import { appBoundaryFindings } from './boundary-findings';
 import { assertSameOrigin, hostRefusal, SQL_BODY, sqlOnGet } from './dev-dashboard-guard';
+import { mailTemplateFacts } from './dev-mail-templates';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
 import type { TraceRecorder } from './dev-traces';
@@ -137,6 +140,10 @@ export function devSources(input: DevDashboardInput): DevSources {
       ...(outbox === undefined
         ? {}
         : { mail: (): Promise<readonly MailFact[]> => Promise.resolve(mailFacts(outbox)) }),
+      // Every declared mail's `preview`, rendered in every locale the app ships — independent of the
+      // transport, so a template is checked before anything is sent anywhere.
+      mailTemplates: async (): Promise<readonly MailTemplateFact[]> =>
+        mailTemplateFacts((await appLocaleSet(input.root)).locales),
       manifest: (): Promise<ManifestFact> => manifestFact(input.root),
       invalidations: (): Promise<readonly InvalidationFact[]> =>
         Promise.resolve(invalidationFacts()),

package/src/dev-lock-identity.ts

@@ -0,0 +1,61 @@
+// Which process a pid is, beyond the number: its start time, recorded in `.x/dev.lock` beside the
+// pid and compared before `x stop` signals. A kill -9 leaves the lock behind and the kernel reuses
+// pids, so a pid alone once named an unrelated process for `x stop` to end.
+
+// why: /proc files report size 0, and Bun.file reads a file by its size — it answers ''.
+import { readFile } from 'node:fs/promises';
+import type { DevLock } from './dev-lock';
+import type { Runner } from './exec';
+import { exec } from './exec';
+
+/** Field 22 of `/proc/<pid>/stat` (`starttime`), read past the `comm` field, which may hold `)`. */
+export function startFromProcStat(stat: string): string | undefined {
+  const close = stat.lastIndexOf(')');
+  if (close === -1) return undefined;
+  // Field 3 (`state`) is the first after the comm; `starttime` is field 22, so index 19 from it.
+  const start = stat
+    .slice(close + 1)
+    .trim()
+    .split(/\s+/)[19];
+  return start !== undefined && /^\d+$/.test(start) ? start : undefined;
+}
+
+/**
+ * The start time of `pid` as the OS reports it, or `undefined` when it will not say (no such
+ * process, or Windows, which has no `ps`). Linux reads `/proc`; elsewhere `ps -o lstart=`.
+ * Only ever compared for equality with a value this same function wrote.
+ */
+export async function processStartTime(
+  pid: number,
+  runner: Runner = exec,
+): Promise<string | undefined> {
+  if (!Number.isInteger(pid) || pid <= 0 || process.platform === 'win32') return undefined;
+  if (process.platform === 'linux') {
+    const stat = await readFile(`/proc/${String(pid)}/stat`, 'utf8').catch(() => undefined);
+    return stat === undefined ? undefined : startFromProcStat(stat);
+  }
+  try {
+    const ps = await runner(['ps', '-o', 'lstart=', '-p', String(pid)], { cwd: process.cwd() });
+    const text = ps.stdout.trim();
+    return ps.ok && text !== '' ? text : undefined;
+  } catch {
+    // `ps` missing is the same answer as a pid it will not describe: no identity to compare.
+    return undefined;
+  }
+}
+
+/**
+ * The lock's pid is alive but is not the process that wrote it: its start time differs from the one
+ * recorded. Compared only where both are known (no start time on Windows, or in a pre-30 lock).
+ */
+export const reusedPid = async (lock: DevLock): Promise<boolean> => {
+  if (lock.started === undefined) return false;
+  const now = await processStartTime(lock.pid);
+  return now !== undefined && now !== lock.started;
+};
+
+/** `{ started }` for `pid`, or nothing where the OS will not say (Windows). */
+export const startedOf = async (pid: number): Promise<{ readonly started?: string }> => {
+  const started = await processStartTime(pid);
+  return started === undefined ? {} : { started };
+};

package/src/dev-lock-port-holder.ts

@@ -0,0 +1,80 @@
+// Who holds a taken port, as far as the OS will say: `ss`, then `lsof`, then `netstat` + `tasklist`.
+// Split from `dev-lock.ts`, which re-exports it, so the lock file stays within the file ceiling.
+
+import { exec, type Runner } from './exec';
+
+/** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
+export interface PortHolder {
+  readonly pid?: number;
+  /** The process name, e.g. `bun`. Enough to recognise "that is my other project". */
+  readonly command?: string;
+}
+
+/**
+ * Who holds the port. `ss` first because it is present on every Linux box the framework targets and
+ * needs no elevation for your own processes; `lsof` is the macOS answer; `netstat -ano` plus
+ * `tasklist` the Windows one.
+ *
+ * Through `exec.ts`, like every other subprocess the CLI runs, so a test injects a fake `Runner`
+ * rather than racing a real socket.
+ *
+ * EVERY PROBE IS CAUGHT SEPARATELY. `exec` refuses a missing program with `X_CLI_UNEXPECTED`, and
+ * letting that escape would mean a box without `ss` gets the CLI's catch-all instead of
+ * `X_PORT_IN_USE` — the exact substitution this module exists to end. A missing `ss` must fall
+ * through to `lsof`, and a box with none still gets the refusal, just without a pid in it.
+ */
+export const portHolder = async (port: number, runner: Runner = exec): Promise<PortHolder> => {
+  const probe = async (command: readonly string[]): Promise<string> => {
+    try {
+      const result = await runner(command, { cwd: process.cwd() });
+      return result.stdout;
+    } catch {
+      return '';
+    }
+  };
+
+  const parsed = /users:\(\("([^"]+)",pid=(\d+)/.exec(
+    await probe(['ss', '-lptnH', `sport = :${port}`]),
+  );
+  const name = parsed?.[1];
+  if (parsed !== null && name !== undefined) return { command: name, pid: Number(parsed[2]) };
+
+  const lines = (
+    await probe(['lsof', '-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-Fpc'])
+  ).split('\n');
+  const pid = lines.find((line) => line.startsWith('p'))?.slice(1);
+  const command = lines.find((line) => line.startsWith('c'))?.slice(1);
+  if (pid !== undefined && /^\d+$/.test(pid)) {
+    return command === undefined ? { pid: Number(pid) } : { command, pid: Number(pid) };
+  }
+
+  // Windows has neither: `netstat -ano` names the listening pid, `tasklist` its image.
+  const listener = netstatListener(await probe(['netstat', '-ano', '-p', 'TCP']), port);
+  if (listener === undefined) return {};
+  const image = tasklistImage(
+    await probe(['tasklist', '/FI', `PID eq ${String(listener)}`, '/FO', 'CSV', '/NH']),
+  );
+  return image === undefined ? { pid: listener } : { command: image, pid: listener };
+};
+
+/**
+ * The pid `netstat -ano` reports LISTENING on `port`, any local address: `TCP 127.0.0.1:3000
+ * 0.0.0.0:0 LISTENING 4242`, and `[::1]:3000` for IPv6. The state column is the word Windows
+ * prints in English on every locale this was read on; an unrecognised line is skipped.
+ */
+export function netstatListener(text: string, port: number): number | undefined {
+  for (const line of text.split(/\r?\n/)) {
+    const [proto, local, , state, pid] = line.trim().split(/\s+/);
+    if (proto !== 'TCP' || state !== 'LISTENING' || pid === undefined || !/^\d+$/.test(pid)) {
+      continue;
+    }
+    if (local?.endsWith(`:${String(port)}`) === true) return Number(pid);
+  }
+  return undefined;
+}
+
+/** The image name off `tasklist /FO CSV /NH`'s one row — `"bun.exe","4242",…` — or `undefined`. */
+export function tasklistImage(text: string): string | undefined {
+  const name = /^"([^"]+)","\d+"/m.exec(text.trim())?.[1];
+  return name === undefined || name === '' ? undefined : name;
+}

package/src/dev-lock-steal.ts

@@ -0,0 +1,124 @@
+// `x dev`'s stale-lock removal, under an exclusive guard: only the boot holding `dev.lock.steal`
+// may delete the lock, and only while it still holds the bytes that boot judged stale. An unlink by
+// path after an unguarded read deleted whatever was there by then, a rival's fresh claim included,
+// so two boots over one stale lock both won.
+
+// why: the guard and the take are synchronous syscalls (link, rename, unlink, stat) with no Bun
+// equivalent, and a sync read keeps the check and the act in one turn of the event loop.
+import { linkSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+
+/**
+ * `cleared`: the lock judged stale is gone, so the claim may be retried. `changed`: the lock there
+ * now is not the one judged, because another boot cleared it and claimed, so judge again.
+ * `busy`: another boot is clearing it right now.
+ */
+export type StealOutcome = 'cleared' | 'changed' | 'busy';
+
+/** The guard's suffix: `dev.lock.steal`, beside the lock it guards. */
+export const STEAL_GUARD_SUFFIX = '.steal';
+
+/**
+ * Past this age a guard is a crashed steal, whatever its pid says: the steal is three syscalls, and
+ * a pid the kernel reused would otherwise hold every later steal off forever.
+ */
+export const STEAL_GUARD_STALE_MS = 10_000;
+
+export interface StealInput {
+  /** The lock file. */
+  readonly path: string;
+  /** The lock's bytes as the caller read them and found them stale. */
+  readonly judged: string;
+  /** Create `path` exclusively, holding this process's lock record; `false` when it exists. */
+  readonly claim: (path: string) => boolean;
+  /** Whether a pid is a live process: the guard's holder is always a real one. */
+  readonly alive: (pid: number) => boolean;
+  /** Test seam for the guard's age. */
+  readonly now?: () => number;
+}
+
+const readText = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+};
+
+const discard = (path: string): void => {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone. Each caller below has already decided the file is its own to remove.
+  }
+};
+
+/**
+ * Remove `path` only if it still holds `judged`: renamed to a name unique to this call (one
+ * syscall, so of two boots exactly one gets the file), then compared, and linked back when it is
+ * not the one judged. Linked, never renamed back: a rename would overwrite a claim made meanwhile.
+ * `true` when the file judged is gone.
+ */
+function takeAway(path: string, judged: string): boolean {
+  const taken = `${path}.${process.pid}.${crypto.randomUUID().slice(0, 8)}.stale`;
+  try {
+    renameSync(path, taken);
+  } catch {
+    return true;
+  }
+  const found = readText(taken);
+  if (found !== judged) {
+    try {
+      linkSync(taken, path);
+    } catch {
+      // A claim landed on the emptied name in that instant; it is the one that stands.
+    }
+  }
+  discard(taken);
+  return found === judged;
+}
+
+/** A guard left by a steal that never finished: its pid is gone, it is too old, or unreadable. */
+function guardAbandoned(guard: string, held: string, input: StealInput): boolean {
+  let pid: unknown;
+  try {
+    pid = (JSON.parse(held) as { pid?: unknown }).pid;
+  } catch {
+    return true;
+  }
+  if (typeof pid !== 'number' || !input.alive(pid)) return true;
+  try {
+    return (input.now ?? Date.now)() - statSync(guard).mtimeMs > STEAL_GUARD_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function takeGuard(guard: string, input: StealInput): boolean {
+  if (input.claim(guard)) return true;
+  const held = readText(guard);
+  // Released between the claim and the read: the steal it guarded is over, so ask once more.
+  if (held === undefined) return input.claim(guard);
+  if (!guardAbandoned(guard, held, input)) return false;
+  // Two boots may both judge one guard abandoned: `takeAway` lets only the one that still finds
+  // THOSE bytes remove it, so the second never deletes the first's fresh guard.
+  return takeAway(guard, held) && input.claim(guard);
+}
+
+/**
+ * Delete the lock at `input.path` if it still holds `input.judged`, holding the guard throughout.
+ * Under the guard the check-then-act is safe: a lock that exists is removed only by the guard's
+ * holder, and its stale owner writes nothing, so the bytes read are the bytes unlinked.
+ */
+export function stealStale(input: StealInput): StealOutcome {
+  const guard = `${input.path}${STEAL_GUARD_SUFFIX}`;
+  if (!takeGuard(guard, input)) return 'busy';
+  try {
+    const found = readText(input.path);
+    if (found === undefined) return 'cleared';
+    if (found !== input.judged) return 'changed';
+    discard(input.path);
+    return 'cleared';
+  } finally {
+    discard(guard);
+  }
+}