@ultimat3/cli 21.0.0 → 22.1.0

package/src/cmd-shot-spec.ts

@@ -0,0 +1,53 @@
+// `x shot`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-shot.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const shotSpec: CommandSpec = {
+  name: 'shot',
+  summary: 'photograph one route, one island in a state it declares, or every island in the app',
+  usage:
+    'x shot <route> | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
+    { name: 'out', type: 'string', summary: 'where shot.png and verdict.json are written' },
+    { name: 'full', type: 'boolean', summary: 'whole page, not the fold', default: true },
+    { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
+    { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
+    { name: 'browser', type: 'string', summary: 'Chrome or Chromium binary to launch' },
+    {
+      name: 'cdp-url',
+      type: 'string',
+      summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
+    },
+    { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
+    {
+      name: 'theme',
+      type: 'string',
+      summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
+    },
+    // A FLAG on `x shot` and never a second command: photographing a route and photographing a
+    // component are one job with two subjects, and a parallel command would be the second path
+    // axiom 1 refuses.
+    {
+      name: 'island',
+      type: 'string',
+      summary: 'photograph one island in every state it declares',
+    },
+    {
+      name: 'state',
+      type: 'string',
+      summary: 'one declared state of that island, not all of them',
+    },
+    // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
+    // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
+    // reader could type that could not be read as a mistyped one. A boolean cannot be confused
+    // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
+    {
+      name: 'all-islands',
+      type: 'boolean',
+      summary: 'every island in the app, in every state it declares, plus an index.md',
+    },
+  ],
+};

package/src/cmd-shot.ts

@@ -8,10 +8,10 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ColorScheme, ScrapeDriver, ScrapePage, ScrapeSession } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
+import type { ShotColorScheme, ShotDriver, ShotPage, ShotSession } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS, systemShotClock } from './cdp-shot-clock';
 import {
   islandShot,
   islandShotResult,
@@ -22,6 +22,7 @@ import {
   refuseSweepWithRoute,
   refuseSweepWithState,
 } from './cmd-shot-island';
+import { shotSpec } from './cmd-shot-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
@@ -181,7 +182,7 @@ const intFlag = (
 export interface ShotRun {
   readonly route: string;
   readonly outDir: string;
-  readonly driver: ScrapeDriver;
+  readonly driver: ShotDriver;
   readonly boot: () => Promise<ShotServer>;
   readonly settleMs: number;
   readonly timeoutMs: number;
@@ -200,7 +201,7 @@ export interface ShotRun {
    * neither: the box's own preference and the app's own default — what `x shot` has always done,
    * and the point of `defaultMode` — and `ui.shot` names one explicitly for exactly that reason.
    */
-  readonly colorScheme?: ColorScheme | undefined;
+  readonly colorScheme?: ShotColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
   /**
    * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
@@ -209,7 +210,7 @@ export interface ShotRun {
    * caller who never calls it gets the count from the first settle.
    */
   readonly act?:
-    | ((page: ScrapePage, settle: () => Promise<IslandCount | null>) => Promise<void>)
+    | ((page: ShotPage, settle: () => Promise<IslandCount | null>) => Promise<void>)
     | undefined;
 }
 
@@ -226,7 +227,7 @@ const quietly = async (stop: () => Promise<void>): Promise<void> => {
  */
 export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   const server = await options.boot();
-  let session: ScrapeSession | undefined;
+  let session: ShotSession | undefined;
   try {
     const requestedUrl = new URL(options.route, server.url).toString();
     session = await options.driver.open({
@@ -235,7 +236,7 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       // inside your network is the widest SSRF surface an app can own, and a screenshot command is
       // not the place to open it by default. Every refusal lands in the verdict's `refused` count.
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
-      clock: systemScrapeClock,
+      clock: systemShotClock,
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
@@ -312,54 +313,7 @@ export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
 });
 
 export const shotCommand: CliCommand = {
-  spec: {
-    name: 'shot',
-    summary: 'photograph one route, one island in a state it declares, or every island in the app',
-    usage:
-      'x shot <route> | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
-      { name: 'out', type: 'string', summary: 'where shot.png and verdict.json are written' },
-      { name: 'full', type: 'boolean', summary: 'whole page, not the fold', default: true },
-      { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
-      { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
-      { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
-      {
-        name: 'cdp-url',
-        type: 'string',
-        summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
-      },
-      { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
-      {
-        name: 'theme',
-        type: 'string',
-        summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
-      },
-      // A FLAG on `x shot` and never a second command: photographing a route and photographing a
-      // component are one job with two subjects, and a parallel command would be the second path
-      // axiom 1 refuses.
-      {
-        name: 'island',
-        type: 'string',
-        summary: 'photograph one island in every state it declares',
-      },
-      {
-        name: 'state',
-        type: 'string',
-        summary: 'one declared state of that island, not all of them',
-      },
-      // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
-      // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
-      // reader could type that could not be read as a mistyped one. A boolean cannot be confused
-      // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
-      {
-        name: 'all-islands',
-        type: 'boolean',
-        summary: 'every island in the app, in every state it declares, plus an index.md',
-      },
-    ],
-  },
+  spec: shotSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('shot', ctx.cwd).dir;
     // Every value read before anything boots: a typo must not cost a browser and a dev server to
@@ -396,8 +350,7 @@ export const shotCommand: CliCommand = {
     // Which browser this run gets — start one here, or attach to one somebody else is running.
     // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
     // provider session exists to pay for a typo. It also PROBES for an installed Chrome and refuses
-    // when there is none: `puppeteer-core` bundles no browser, so a missing one used to surface as
-    // a library throw one embedded Postgres later.
+    // when there is none, so a missing browser costs no embedded Postgres boot.
     const { cdpUrl, executablePath } = shotBrowserChoice({
       cdpFlag: flagString(ctx.args, 'cdp-url'),
       browserFlag: flagString(ctx.args, 'browser'),
@@ -423,10 +376,8 @@ export const shotCommand: CliCommand = {
         await islandShot({ ...shared, island, ...(state === undefined ? {} : { state }) }),
       );
     }
-    // Resolved before the boot for the same reason: an app with no browser installed must not pay
-    // an embedded Postgres to be told to run `bun add -d puppeteer-core`.
+    // Built before the boot, for the same reason.
     const driver = await appBrowser({
-      root,
       ...(executablePath === undefined ? {} : { executablePath }),
       ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });

package/src/cmd-tasks-spec.ts

@@ -0,0 +1,21 @@
+// `x tasks`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-tasks.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const tasksSpec: CommandSpec = {
+  name: 'tasks',
+  summary: 'cron tasks, their timezone and their next run',
+  usage: 'x tasks [list|show <name>] [--count n] [--json]',
+  requiresApp: true,
+  subcommands: ['list', 'show'],
+  defaultSubcommand: 'list',
+  flags: [
+    {
+      name: 'count',
+      type: 'string',
+      summary: 'show: how many upcoming occurrences to list',
+      subcommands: ['show'],
+    },
+  ],
+};

package/src/cmd-tasks.ts

@@ -8,6 +8,7 @@ import type { TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { tasksSpec } from './cmd-tasks-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, DeclarationUnknownError } from './errors';
 import { msg } from './messages';
@@ -130,22 +131,7 @@ function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[
 }
 
 export const tasksCommand: CliCommand = {
-  spec: {
-    name: 'tasks',
-    summary: 'cron tasks, their timezone and their next run',
-    usage: 'x tasks [list|show <name>] [--count n] [--json]',
-    requiresApp: true,
-    subcommands: ['list', 'show'],
-    defaultSubcommand: 'list',
-    flags: [
-      {
-        name: 'count',
-        type: 'string',
-        summary: 'show: how many upcoming occurrences to list',
-        subcommands: ['show'],
-      },
-    ],
-  },
+  spec: tasksSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('tasks', ctx.cwd).dir;
     const { findings } = await loadApp(root);

package/src/cmd-test-spec.ts

@@ -0,0 +1,54 @@
+// `x test`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-test.ts`, which `registry.ts` imports only when the command runs.
+
+import { TEST_TYPES } from '@ultimat3/testing/test-types';
+import { DEFAULT_BASE } from './affected';
+import type { CommandSpec } from './parse';
+import { SERIAL_TYPES, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+
+export const testSpec: CommandSpec = {
+  name: 'test',
+  summary:
+    'run one test type — or the whole suite — across N workers, one isolated database per worker',
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
+  positionalChoices: TEST_TYPES,
+  // The one command that hands a tail to another tool — `bun test` — and the reason
+  // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
+  // dropped both, so a run that measured no coverage reported exactly what a coverage run does.
+  passthrough: true,
+  flags: [
+    {
+      name: 'workers',
+      type: 'string',
+      summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
+    },
+    {
+      name: 'worker',
+      type: 'string',
+      summary:
+        'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
+    },
+    { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
+    {
+      name: 'sample',
+      type: 'string',
+      summary:
+        'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
+    },
+    {
+      name: 'affected',
+      type: 'boolean',
+      summary: 'only the workspaces a diff touches, and everything that depends on one of them',
+    },
+    {
+      name: 'base',
+      type: 'string',
+      summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+    },
+    {
+      name: 'dirty',
+      type: 'boolean',
+      summary: '--affected: also count uncommitted work, whichever agent in this checkout made it',
+    },
+  ],
+};

package/src/cmd-test.ts

@@ -7,6 +7,7 @@
 
 import type { AffectedScope } from './affected';
 import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
+import { testSpec } from './cmd-test-spec';
 import type { CliCommand, CommandContext } from './command';
 import { ok } from './command';
 import { BadFlagError, NoTestFilesError } from './errors';
@@ -18,9 +19,9 @@ import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
 import { runShards } from './test-shards';
-import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { defaultWorkers, SERIAL_TYPES, WORKER_CEILING } from './test-workers';
 import type { TestType } from './verify-tests';
-import { SERIAL_TYPES, TEST_TYPES } from './verify-tests';
+import { TEST_TYPES } from './verify-tests';
 
 /**
  * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
@@ -100,53 +101,7 @@ const withScope = (result: CommandResult, scope: AffectedScope): CommandResult =
 });
 
 export const testCommand: CliCommand = {
-  spec: {
-    name: 'test',
-    summary:
-      'run one test type — or the whole suite — across N workers, one isolated database per worker',
-    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
-    positionalChoices: TEST_TYPES,
-    // The one command that hands a tail to another tool — `bun test` — and the reason
-    // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
-    // dropped both, so a run that measured no coverage reported exactly what a coverage run does.
-    passthrough: true,
-    flags: [
-      {
-        name: 'workers',
-        type: 'string',
-        summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
-      },
-      {
-        name: 'worker',
-        type: 'string',
-        summary:
-          'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
-      },
-      { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
-      {
-        name: 'sample',
-        type: 'string',
-        summary:
-          'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
-      },
-      {
-        name: 'affected',
-        type: 'boolean',
-        summary: 'only the workspaces a diff touches, and everything that depends on one of them',
-      },
-      {
-        name: 'base',
-        type: 'string',
-        summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
-      },
-      {
-        name: 'dirty',
-        type: 'boolean',
-        summary:
-          '--affected: also count uncommitted work, whichever agent in this checkout made it',
-      },
-    ],
-  },
+  spec: testSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const type = readOnlyType(ctx.args.positionals);
     const filter = flagString(ctx.args, 'filter');

package/src/cmd-verify-spec.ts

@@ -0,0 +1,28 @@
+// `x verify`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-verify.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+
+export const verifySpec: CommandSpec = {
+  name: 'verify',
+  summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
+  usage: 'x verify [--only <step>] [--workers N] [--json]',
+  requiresApp: true,
+  // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
+  // spread, never which steps run. `--only` runs one step and says so in both renderers —
+  // never silently, which is the whole of what makes it safe to have.
+  flags: [
+    {
+      name: 'workers',
+      type: 'string',
+      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+    },
+    {
+      name: 'only',
+      type: 'string',
+      summary:
+        'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
+    },
+  ],
+};

package/src/cmd-verify.ts

@@ -9,13 +9,14 @@
 
 import { nearestName } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
+import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
-import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
 import { runVerify } from './verify-run';
 import type { VerifyStepName } from './verify-step';
@@ -28,28 +29,7 @@ export { VERIFY_STEPS } from './verify-checks';
 export { runVerify } from './verify-run';
 
 export const verifyCommand: CliCommand = {
-  spec: {
-    name: 'verify',
-    summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-    usage: 'x verify [--only <step>] [--workers N] [--json]',
-    requiresApp: true,
-    // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
-    // spread, never which steps run. `--only` runs one step and says so in both renderers —
-    // never silently, which is the whole of what makes it safe to have.
-    flags: [
-      {
-        name: 'workers',
-        type: 'string',
-        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
-      },
-      {
-        name: 'only',
-        type: 'string',
-        summary:
-          'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
-      },
-    ],
-  },
+  spec: verifySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('verify', ctx.cwd).dir;
     // Both readers before the run: an unrunnable flag must be refused in milliseconds, not after

package/src/db-seed.ts

@@ -16,6 +16,7 @@ import { BadFlagError } from './errors';
 import type { Finding, JsonValue } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
 import { renderTable } from './table';
 
 /**
@@ -102,10 +103,11 @@ export async function discoverSeeds(root: string): Promise<SeedDiscovery> {
   const seen = new Set<string>();
   for (const pattern of SEED_GLOBS) {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
+      const file = relative(root, absolute).split(sep).join('/');
+      // Root-relative, as `loadApp` tests it: an absolute path under `my.test.app/` is no test.
+      if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
       if (seen.has(absolute)) continue;
       seen.add(absolute);
-      const file = relative(root, absolute).split(sep).join('/');
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;

package/src/dev-dashboard.ts

@@ -22,14 +22,14 @@ import { json as jsonResponse } from '@ultimat3/http';
 import type { MemoryMailDriver } from '@ultimat3/mail';
 import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
-import { checkAppBoundaries } from './app-boundaries';
 import { appManifest, readAppManifest } from './app-manifest';
+import { appBoundaryFindings } from './boundary-findings';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
-import type { RunningServices } from './dev-runtime';
-import type { DevServices } from './dev-services';
 import type { TraceRecorder } from './dev-traces';
 import type { Finding } from './output';
+import type { DevServices } from './runtime-bindings';
+import type { RunningServices } from './runtime-services';
 import { loopFacts } from './statement-loop';
 
 export interface DevStatus {
@@ -195,7 +195,7 @@ const boundariesPanel = (input: DevDashboardInput): DevPanel<BoundariesPanelData
   titleKey: 'dev.panel.boundaries.title',
   questionKey: 'dev.panel.boundaries.question',
   async data(): Promise<BoundariesPanelData> {
-    return { findings: await checkAppBoundaries(input.root) };
+    return { findings: await appBoundaryFindings(input.root) };
   },
 });
 

package/src/dev-lock.ts

@@ -14,7 +14,7 @@
 // The lock file is what makes the second one nameable at all: nothing else in the process can tell
 // "another dev server owns this directory" from "the database is broken".
 
-import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
@@ -75,11 +75,27 @@ export const isProcessAlive = (pid: number): boolean => {
   }
 };
 
+/**
+ * The lock a LIVE `x dev` holds on this state directory, or `undefined` — for a command that must
+ * not run beside one (`x db reset` deletes the data directory that process has open). A missing,
+ * unreadable or stale lock is no holder: only `preflight` may clear one.
+ */
+export const liveDevLock = (stateDir: string): DevLock | undefined => {
+  let raw: string;
+  try {
+    raw = readFileSync(lockPath(stateDir), 'utf-8');
+  } catch {
+    return undefined;
+  }
+  const lock = parseLock(raw);
+  return lock !== null && isProcessAlive(lock.pid) ? lock : undefined;
+};
+
 /**
  * Refused before boot, so the failure names the process holding the directory.
  *
  * The lock is on the CHECKOUT, not on the database, and the cause says so. `x dev` is one process
- * running every role (`dev-roles.ts`), so a second one is unsupported whatever the services are.
+ * running every role (`role-start.ts`), so a second one is unsupported whatever the services are.
  * The embedded-Postgres sentence is appended only when the database actually IS embedded — with an
  * external `DATABASE_URL` it would name a mechanism that is not in play, which is the same defect
  * as the message this whole module replaced.

package/src/dev-port.ts

@@ -0,0 +1,21 @@
+// Which port `x dev` binds: `--port`, else `PORT` from the environment, else 3000. The flag used to
+// declare `default: '3000'`, and a default is indistinguishable from a caller's value — so the
+// scaffold's own `.env.development` `PORT=` was read by nothing and every app booted on 3000.
+
+import { PORT_RANGE, readIntFlag } from './flag-number';
+import type { ParsedArgs } from './parse';
+import { portFromEnv } from './serve';
+
+export const DEFAULT_DEV_PORT = 3000;
+
+/** The `metricsPortFor` shape: an explicit value, then the env, then the constant. */
+export const devPortFor = (
+  args: ParsedArgs,
+  env: Readonly<Record<string, string | undefined>>,
+): number =>
+  readIntFlag(args, {
+    name: 'port',
+    command: 'dev',
+    ...PORT_RANGE,
+    example: `x dev --port ${DEFAULT_DEV_PORT}`,
+  }) ?? portFromEnv(env);

package/src/dev-route-table.ts

@@ -7,11 +7,8 @@ import { describeRoutes } from '@ultimat3/render';
 import type { Storage } from '@ultimat3/storage';
 import { apiRoutes } from './api-routes';
 import { mountAppMcp } from './app-mcp';
-import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput } from './dev-dashboard';
 import { devDashboardRoutes } from './dev-dashboard';
-import { appRoutes } from './dev-render';
-import { storageRoutes } from './dev-storage';
 import { errorPageStyleSources } from './error-page-csp';
 import type { IslandBundle } from './island-bundle';
 import { islandHarnessRoutes } from './island-harness-route';
@@ -19,6 +16,9 @@ import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import { storageRoutes } from './runtime-storage';
 import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';

package/src/dispatch.ts

@@ -16,6 +16,7 @@ import { exitCodeFor, findingFrom, render } from './output';
 import type { ParsedArgs } from './parse';
 import { parseArgs, wantsJson } from './parse';
 import { commandFor, SPECS } from './registry';
+import { rootEnvAdditions } from './root-env';
 
 export interface DispatchOptions {
   readonly argv: readonly string[];
@@ -120,14 +121,20 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     ? { ...args, command: 'help', positionals: [args.command] }
     : args;
 
+  const cwd = resolveCwd(
+    options.cwd,
+    typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
+  );
+  // The ROOT's `.env*`, not the cwd's: Bun loaded the cwd's at startup, and a command run from
+  // `apps/web` finds its root by walking up. Written into the process env too when that IS the env
+  // passed in, because a package reading `Bun.env` directly must see what the command sees.
+  const added = await rootEnvAdditions(cwd, options.env);
+  if (options.env === Bun.env) Object.assign(Bun.env, added);
   const ctx: CommandContext = {
     args: helpArgs,
-    cwd: resolveCwd(
-      options.cwd,
-      typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
-    ),
+    cwd,
     runner: options.runner ?? exec,
-    env: options.env,
+    env: options.env === Bun.env ? options.env : { ...added, ...options.env },
     bunVersion: options.bunVersion,
     ...(options.invocation === undefined ? {} : { invocation: options.invocation }),
   };

package/src/document-styles.ts

@@ -25,7 +25,7 @@ export const definesRootCustomProperties = (css: string): boolean => ROOT_CUSTOM
 
 export interface SurfaceDocument {
   readonly surface: Surface;
-  /** Exactly the CSS `dev-render.ts` would inline into a document on this surface. */
+  /** Exactly the CSS `runtime-render.ts` would inline into a document on this surface. */
   readonly css: string;
 }