@ultimat3/cli 21.0.0 → 22.0.0

package/src/cdp-shot-page.ts

@@ -0,0 +1,230 @@
+// One `ShotPage` over one attached CDP session: navigate, read, act, photograph. The session is
+// the driver's (`cdp-shot-driver.ts`), the rings and the allow list are `cdp-shot-watch.ts`'s, and
+// what "ready to act on" means is `cdp-shot-element.ts`'s. Acts are real input — a click is a
+// mouse press at the element's centre, a keystroke is a key event — because an in-page `.click()`
+// skips `pointerdown`, which is what a dialog's backdrop listens to.
+import { assert, finiteCount, hostDecision } from '@ultimat3/core';
+import type { CdpConnection } from '@ultimat3/testing';
+import { CdpCallFailedError, CdpTimeoutError } from '@ultimat3/testing';
+import type {
+  ElementSnapshot,
+  ShotCapture,
+  ShotColorScheme,
+  ShotPage,
+  ShotSessionInit,
+  WaitOptions,
+} from './browser-launcher-port';
+import { axNodesFor } from './cdp-shot-a11y';
+import { awaitReady, parseSnapshots, snapshotExpression } from './cdp-shot-element';
+import { ShotHostRefusedError } from './cdp-shot-errors';
+import { characterFrames, chordFrames, parseKeyChord } from './cdp-shot-keys';
+import type { PageWatch } from './cdp-shot-watch';
+
+export const DEFAULT_ACCESSIBILITY_MAX = 25;
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/** What the page threw, when `Runtime.evaluate` answered with an exception rather than a value. */
+const thrownIn = (answer: Readonly<Record<string, unknown>> | undefined): string | undefined => {
+  const thrown = record(answer?.['exceptionDetails']);
+  if (thrown === undefined) return undefined;
+  const description = record(thrown['exception'])?.['description'];
+  if (typeof description === 'string') return description.split('\n')[0];
+  const text = thrown['text'];
+  return typeof text === 'string' ? text : 'the expression threw in the page';
+};
+
+const selectorArg = (selector: string): string => JSON.stringify(selector);
+
+export interface CdpShotPageInput {
+  readonly connection: CdpConnection;
+  readonly sessionId: string;
+  readonly init: ShotSessionInit;
+  readonly watch: PageWatch;
+}
+
+export function cdpShotPage(input: CdpShotPageInput): ShotPage {
+  const { connection, sessionId, init, watch } = input;
+  const defaultTimeout = finiteCount(init.name, 'timeoutMs', init.timeoutMs, 1);
+  const send = async (method: string, params: Record<string, unknown> = {}) =>
+    (await connection.send(method, params, sessionId)).result;
+  let current = 'about:blank';
+
+  const evaluate = async (expression: string): Promise<unknown> => {
+    const answer = await send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    const threw = thrownIn(answer);
+    if (threw !== undefined) {
+      throw new CdpCallFailedError({ method: 'Runtime.evaluate', detail: threw });
+    }
+    return record(answer?.['result'])?.['value'];
+  };
+
+  const query = async (selector: string): Promise<readonly ElementSnapshot[]> =>
+    parseSnapshots(await evaluate(snapshotExpression(selector)));
+
+  const ready = (
+    selector: string,
+    options: WaitOptions | undefined,
+    before?: () => Promise<unknown>,
+  ): Promise<ElementSnapshot> =>
+    awaitReady({
+      selector,
+      state: options?.state ?? 'actionable',
+      timeoutMs: finiteCount('page.waitFor', 'timeout', options?.timeout ?? defaultTimeout, 1),
+      clock: init.clock,
+      url: () => current,
+      snapshot: async () => {
+        await before?.();
+        return (await query(selector))[0];
+      },
+    });
+
+  const key = async (frame: Readonly<Record<string, unknown>>): Promise<void> => {
+    await send('Input.dispatchKeyEvent', { ...frame });
+  };
+
+  const focusOn = (selector: string): Promise<unknown> =>
+    evaluate(`document.querySelector(${selectorArg(selector)})?.focus()`);
+
+  return {
+    url: () => current,
+    async goto(url, options) {
+      if (!hostDecision(url, init.rules.allowHosts).allowed) {
+        throw new ShotHostRefusedError({ url, allowHosts: init.rules.allowHosts });
+      }
+      const timeoutMs = finiteCount('page.goto', 'timeout', options?.timeout ?? defaultTimeout, 1);
+      // The waiter goes up BEFORE the send, and the reply is raced rather than awaited: Chrome
+      // drops `Page.navigate`'s reply when the navigation swaps the render process
+      // (`@ultimat3/testing`'s `cdp-e2e-page.ts` measured it), and the load event still fires.
+      const loaded = connection.once('Page.loadEventFired', sessionId, timeoutMs);
+      const answered = send('Page.navigate', { url }).then(
+        (answer) => {
+          const failed = answer?.['errorText'];
+          return typeof failed === 'string' && failed !== '' ? failed : undefined;
+        },
+        () => undefined,
+      );
+      const first = await Promise.race([
+        loaded.then((fired) => ({ fired, failed: undefined })),
+        answered.then((failed) => ({ fired: undefined, failed })),
+      ]);
+      if (first.failed !== undefined) {
+        throw new CdpCallFailedError({ method: `Page.navigate to ${url}`, detail: first.failed });
+      }
+      const fired = first.fired ?? (await loaded);
+      // A same-document load may have fired before the waiter existed; the document is asked.
+      if (!fired && (await evaluate('document.readyState')) !== 'complete') {
+        throw new CdpTimeoutError({ method: `Page.navigate to ${url}`, timeoutMs });
+      }
+      const settled = await evaluate('location.href');
+      current = typeof settled === 'string' && settled !== '' ? settled : url;
+    },
+    waitFor: (selector, options) => ready(selector, options),
+    async click(selector, options) {
+      // Scrolled into view on every poll: `elementFromPoint` answers nothing off-screen, so an
+      // element below the fold would read as covered forever.
+      const target = await ready(selector, options, () =>
+        evaluate(
+          `document.querySelector(${selectorArg(selector)})?.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' })`,
+        ),
+      );
+      const box = target.box ?? { x: 0, y: 0, width: 0, height: 0 };
+      const at = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+      await send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...at });
+      const press = { ...at, button: 'left', clickCount: 1 };
+      await send('Input.dispatchMouseEvent', { type: 'mousePressed', buttons: 1, ...press });
+      await send('Input.dispatchMouseEvent', { type: 'mouseReleased', buttons: 0, ...press });
+    },
+    async type(selector, text, options) {
+      await ready(selector, options);
+      await focusOn(selector);
+      for (const character of text) {
+        for (const frame of characterFrames(character)) await key(frame);
+      }
+    },
+    async focus(selector, options) {
+      await ready(selector, options);
+      await focusOn(selector);
+    },
+    async press(chord) {
+      // Parsed before a key goes down: a refusal halfway would leave a modifier held.
+      const frames = chordFrames(parseKeyChord(chord));
+      for (const frame of frames) await key(frame);
+    },
+    accessibility: (selector, options) =>
+      axNodesFor(
+        send,
+        selector,
+        finiteCount('page.accessibility', 'max', options?.max ?? DEFAULT_ACCESSIBILITY_MAX, 1),
+      ),
+    query,
+    evaluate,
+    screenshot: (options?: ShotCapture) => capture(send, options ?? {}),
+    async colorScheme(scheme: ShotColorScheme) {
+      // An EMPTY list is CDP's reset; an explicit `no-preference` would be an override.
+      const features =
+        scheme === 'no-preference' ? [] : [{ name: 'prefers-color-scheme', value: scheme }];
+      await send('Emulation.setEmulatedMedia', { features });
+    },
+    async prepare(expression) {
+      await send('Page.addScriptToEvaluateOnNewDocument', { source: expression });
+    },
+    console: () => watch.console(),
+    pageErrors: () => watch.pageErrors(),
+    pageErrorsDropped: () => watch.pageErrorsDropped(),
+    network: () => watch.network(),
+    networkDropped: () => watch.networkDropped(),
+  };
+}
+
+type Send = (
+  method: string,
+  params?: Record<string, unknown>,
+) => Promise<Readonly<Record<string, unknown>> | undefined>;
+
+/**
+ * PNG bytes of the viewport, the whole document, or one clip — never both of the last two, which
+ * CDP would resolve silently in favour of one. A clip is CSS pixels in page coordinates.
+ */
+async function capture(send: Send, framing: ShotCapture): Promise<Uint8Array> {
+  const clip = framing.clip;
+  assert(
+    !(framing.fullPage === true && clip !== undefined),
+    'a screenshot was asked for the full page AND a clip, and a capture is one or the other',
+    'pass { clip } for one component or { fullPage: true } for the document, never both',
+  );
+  assert(
+    clip === undefined ||
+      ([clip.x, clip.y, clip.width, clip.height].every(Number.isFinite) &&
+        clip.width > 0 &&
+        clip.height > 0),
+    'a screenshot clip has no area or is not four finite numbers',
+    'pass a clip with a positive width and height: { clip: { x: 0, y: 0, width: 320, height: 200 } }',
+  );
+  let region = clip;
+  if (framing.fullPage === true) {
+    const metrics = record((await send('Page.getLayoutMetrics'))?.['cssContentSize']);
+    const width = metrics?.['width'];
+    const height = metrics?.['height'];
+    if (typeof width === 'number' && typeof height === 'number') {
+      region = { x: 0, y: 0, width: Math.ceil(width), height: Math.ceil(height) };
+    }
+  }
+  const answer = await send('Page.captureScreenshot', {
+    format: 'png',
+    ...(region === undefined ? {} : { clip: { ...region, scale: 1 }, captureBeyondViewport: true }),
+  });
+  const data = answer?.['data'];
+  if (typeof data !== 'string') {
+    throw new CdpCallFailedError({
+      method: 'Page.captureScreenshot',
+      detail: 'the browser answered no image data',
+    });
+  }
+  return Uint8Array.fromBase64(data);
+}

package/src/cdp-shot-watch.ts

@@ -0,0 +1,241 @@
+// What one shot page saw: its console, its uncaught exceptions and its requests, each in a BOUNDED
+// tail with a count of what the bound threw away. And the allow list, enforced in the browser:
+// every request is paused (`Fetch.requestPaused`) and refused unless its host is allowed, so an
+// injected `<img src="http://169.254.169.254/…">` never leaves — it is recorded as `refused`.
+import { hostDecision } from '@ultimat3/core';
+import type { CdpConnection } from '@ultimat3/testing';
+import type {
+  ConsoleLine,
+  NetworkEntry,
+  PageError,
+  ShotClock,
+  ShotResourceType,
+} from './browser-launcher-port';
+
+export const SHOT_RING_CAPACITY = 200;
+
+/** One `PageError` field's cap: one stack overflow's trace is thousands of frames. */
+export const MAX_PAGE_ERROR_CHARS = 4_000;
+
+const clamped = (text: string): string =>
+  text.length <= MAX_PAGE_ERROR_CHARS ? text : `${text.slice(0, MAX_PAGE_ERROR_CHARS - 1)}…`;
+
+/** A bounded, keyed tail: the oldest entry goes first, and every one that goes is counted. */
+class Tail<T> {
+  readonly #items = new Map<string, T>();
+  #dropped = 0;
+  #next = 0;
+
+  put(value: T, key = `#${String(this.#next++)}`): void {
+    this.#items.set(key, value);
+    while (this.#items.size > SHOT_RING_CAPACITY) {
+      const oldest = this.#items.keys().next().value;
+      if (oldest === undefined) break;
+      this.#items.delete(oldest);
+      this.#dropped += 1;
+    }
+  }
+  get(key: string): T | undefined {
+    return this.#items.get(key);
+  }
+  /** Move the entry under `key` to a key of its own at the end, freeing `key` for its successor. */
+  retire(key: string): void {
+    const held = this.#items.get(key);
+    if (held === undefined) return;
+    this.#items.delete(key);
+    this.put(held);
+  }
+  /** Re-set in place: `Map.set` on a present key keeps its position. */
+  update(key: string, value: T): void {
+    if (this.#items.has(key)) this.#items.set(key, value);
+  }
+  entries = (): readonly T[] => [...this.#items.values()];
+  dropped = (): number => this.#dropped;
+}
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+const LEVELS: ReadonlyMap<string, ConsoleLine['level']> = new Map([
+  ['warning', 'warn'],
+  ['error', 'error'],
+  ['assert', 'error'],
+  ['debug', 'debug'],
+  ['info', 'info'],
+]);
+
+const RESOURCE_TYPES: ReadonlyMap<string, ShotResourceType> = new Map([
+  ['Document', 'document'],
+  ['Stylesheet', 'stylesheet'],
+  ['Image', 'image'],
+  ['Media', 'media'],
+  ['Font', 'font'],
+  ['Script', 'script'],
+  ['XHR', 'xhr'],
+  ['Fetch', 'fetch'],
+  ['WebSocket', 'websocket'],
+]);
+
+const resourceType = (type: unknown): ShotResourceType =>
+  RESOURCE_TYPES.get(text(type) ?? '') ?? 'other';
+
+/** A console argument as the line a reader is shown: a value, else what the browser described. */
+const argText = (arg: unknown): string => {
+  const remote = record(arg);
+  const value = remote?.['value'];
+  if (typeof value === 'string') return value;
+  if (value !== undefined) return JSON.stringify(value) ?? '';
+  return text(remote?.['unserializableValue']) ?? text(remote?.['description']) ?? '';
+};
+
+/** `Runtime.exceptionThrown`'s details as a `PageError`: message without its `Name: `, stack whole. */
+export const pageErrorOf = (params: Readonly<Record<string, unknown>>, at: number): PageError => {
+  const details = record(params['exceptionDetails']);
+  const exception = record(details?.['exception']);
+  const description = text(exception?.['description']);
+  if (description === undefined) {
+    const thrown = exception?.['value'];
+    const message = thrown === undefined ? (text(details?.['text']) ?? '') : String(thrown);
+    return { message: clamped(message), at };
+  }
+  const first = description.split('\n')[0] ?? '';
+  const name = text(exception?.['className']);
+  const message =
+    name !== undefined && first.startsWith(`${name}: `) ? first.slice(name.length + 2) : first;
+  const stack = description.includes('\n') ? clamped(description) : undefined;
+  return { message: clamped(message), ...(stack === undefined ? {} : { stack }), at };
+};
+
+export interface PageWatch {
+  console(): readonly ConsoleLine[];
+  pageErrors(): readonly PageError[];
+  pageErrorsDropped(): number;
+  network(): readonly NetworkEntry[];
+  networkDropped(): number;
+  /** Stop listening. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Subscribe BEFORE the domains are enabled (the caller's order), so the first request of the first
+ * navigation is already counted. Only events on `sessionId` are read: a remote browser carries
+ * other people's pages.
+ */
+export function watchPage(input: {
+  readonly connection: CdpConnection;
+  readonly sessionId: string;
+  readonly clock: ShotClock;
+  readonly allowHosts: readonly string[];
+}): PageWatch {
+  const { connection, sessionId } = input;
+  const lines = new Tail<ConsoleLine>();
+  const errors = new Tail<PageError>();
+  const requests = new Tail<NetworkEntry>();
+  const now = (): number => input.clock.now().getTime();
+  const mine =
+    (listener: (params: Readonly<Record<string, unknown>>) => void) =>
+    (params: Record<string, unknown>, on: string | undefined): void => {
+      if (on === sessionId) listener(params);
+    };
+
+  const offs = [
+    connection.on(
+      'Runtime.consoleAPICalled',
+      mine((params) => {
+        const args = params['args'];
+        lines.put({
+          level: LEVELS.get(text(params['type']) ?? '') ?? 'log',
+          text: (Array.isArray(args) ? args : []).map(argText).join(' '),
+          at: now(),
+        });
+      }),
+    ),
+    connection.on(
+      'Runtime.exceptionThrown',
+      mine((params) => errors.put(pageErrorOf(params, now()))),
+    ),
+    connection.on(
+      'Network.requestWillBeSent',
+      mine((params) => {
+        const id = text(params['requestId']) ?? '';
+        const request = record(params['request']);
+        const held = requests.get(id);
+        const entry: NetworkEntry = {
+          method: text(request?.['method']) ?? 'GET',
+          url: text(request?.['url']) ?? '',
+          resourceType: resourceType(params['type']),
+          at: now(),
+          ...(held?.refused === undefined ? {} : { refused: held.refused }),
+        };
+        // A redirect re-sends under the SAME id: the hop before it is a request of its own,
+        // answered with the redirect's status.
+        const hop = record(params['redirectResponse'])?.['status'];
+        if (held !== undefined && held.refused === undefined && typeof hop === 'number') {
+          requests.update(id, { ...held, status: hop });
+          requests.retire(id);
+          requests.put(entry, id);
+        } else if (held === undefined) requests.put(entry, id);
+        else requests.update(id, entry);
+      }),
+    ),
+    connection.on(
+      'Network.responseReceived',
+      mine((params) => {
+        const id = text(params['requestId']) ?? '';
+        const status = record(params['response'])?.['status'];
+        const held = requests.get(id);
+        if (held !== undefined && typeof status === 'number')
+          requests.update(id, { ...held, status });
+      }),
+    ),
+    connection.on(
+      'Fetch.requestPaused',
+      mine((params) => {
+        const pausedId = text(params['requestId']) ?? '';
+        const request = record(params['request']);
+        const url = text(request?.['url']) ?? '';
+        if (hostDecision(url, input.allowHosts).allowed) {
+          void connection
+            .send('Fetch.continueRequest', { requestId: pausedId }, sessionId)
+            .catch(() => undefined);
+          return;
+        }
+        const id = text(params['networkId']) ?? pausedId;
+        const held = requests.get(id);
+        const refused: NetworkEntry = {
+          method: text(request?.['method']) ?? held?.method ?? 'GET',
+          url,
+          resourceType: resourceType(params['resourceType']),
+          at: held?.at ?? now(),
+          refused: 'host',
+        };
+        if (held === undefined) requests.put(refused, id);
+        else requests.update(id, refused);
+        void connection
+          .send(
+            'Fetch.failRequest',
+            { requestId: pausedId, errorReason: 'BlockedByClient' },
+            sessionId,
+          )
+          .catch(() => undefined);
+      }),
+    ),
+  ];
+
+  let stopped = false;
+  return {
+    console: () => lines.entries(),
+    pageErrors: () => errors.entries(),
+    pageErrorsDropped: () => errors.dropped(),
+    network: () => requests.entries(),
+    networkDropped: () => requests.dropped(),
+    stop(): void {
+      if (stopped) return;
+      stopped = true;
+      for (const off of offs) off();
+    },
+  };
+}

package/src/cmd-affected-spec.ts

@@ -0,0 +1,24 @@
+// `x affected`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-affected.ts`, which `registry.ts` imports only when the command runs.
+
+import { DEFAULT_BASE } from './affected';
+import type { CommandSpec } from './parse';
+
+export const affectedSpec: CommandSpec = {
+  name: 'affected',
+  summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
+  usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
+  flags: [
+    {
+      name: 'base',
+      type: 'string',
+      summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+    },
+    {
+      name: 'dirty',
+      type: 'boolean',
+      summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
+    },
+    { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
+  ],
+};

package/src/cmd-affected.ts

@@ -6,7 +6,8 @@
 // CLI wiring only. What a diff touches is `affected.ts`, what the workspaces are is
 // `workspace-graph.ts` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
 
-import { affectedScope, DEFAULT_BASE } from './affected';
+import { affectedScope } from './affected';
+import { affectedSpec } from './cmd-affected-spec';
 import type { CliCommand, CommandContext } from './command';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
@@ -33,24 +34,7 @@ export const AFFECTED_MESSAGE_KEYS = [
 ] as const;
 
 export const affectedCommand: CliCommand = {
-  spec: {
-    name: 'affected',
-    summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
-    usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
-    flags: [
-      {
-        name: 'base',
-        type: 'string',
-        summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
-      },
-      {
-        name: 'dirty',
-        type: 'boolean',
-        summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
-      },
-      { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
-    ],
-  },
+  spec: affectedSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     // The one resolver `x test --affected` narrows with, so this command reports exactly what that
     // one runs. It reads `--base` before git is spawned (a malformed ref must not cost a

package/src/cmd-build-spec.ts

@@ -0,0 +1,16 @@
+// `x build`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-build.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const buildSpec: CommandSpec = {
+  name: 'build',
+  summary: 'build a container image, a single binary, or a prerendered static site',
+  usage: 'x build --target docker|binary|static [--tag name] [--out path] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
+    { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
+    { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
+  ],
+};

package/src/cmd-build.ts

@@ -2,15 +2,17 @@
 // means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
 
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
+import { buildSpec } from './cmd-build-spec';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
 import { BuildEntryMissingError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
+import { prepareImage } from './image-prepare';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
@@ -56,9 +58,24 @@ export function requireEntry(root: string, target: BuildTarget): string {
   return absolute;
 }
 
-/** One image for every role; ROLE selects behaviour at start, so there is one artifact to promote. */
-export function dockerArgs(root: string, tag: string): readonly string[] {
-  return ['docker', 'build', '-f', join(root, BUILD_ENTRY.docker), '-t', tag, root];
+/**
+ * One image for every role; ROLE selects behaviour at start, so there is one artifact to promote.
+ * `BUILD_ID` is the manifest's own build id, passed as the build arg the scaffolded Dockerfile
+ * declares: without it the image's `BUILD_ID` was empty and every role computed one at boot, so
+ * two replicas of one image could disagree about the id their clients are served against.
+ */
+export function dockerArgs(root: string, tag: string, buildId: string): readonly string[] {
+  return [
+    'docker',
+    'build',
+    '-f',
+    join(root, BUILD_ENTRY.docker),
+    '--build-arg',
+    `BUILD_ID=${buildId}`,
+    '-t',
+    tag,
+    root,
+  ];
 }
 
 /**
@@ -93,9 +110,15 @@ export function staticArgs(root: string, out: string): readonly string[] {
 
 export function argsFor(
   target: BuildTarget,
-  paths: { readonly root: string; readonly tag: string; readonly out: string },
+  paths: {
+    readonly root: string;
+    readonly tag: string;
+    readonly out: string;
+    /** The docker target's `BUILD_ID` build arg — `appManifest(root)`'s own. */
+    readonly buildId?: string;
+  },
 ): readonly string[] {
-  if (target === 'docker') return dockerArgs(paths.root, paths.tag);
+  if (target === 'docker') return dockerArgs(paths.root, paths.tag, paths.buildId ?? 'dev');
   if (target === 'binary') return binaryArgs(paths.root, paths.out);
   return staticArgs(paths.root, paths.out);
 }
@@ -162,17 +185,7 @@ export function buildResult(input: {
 }
 
 export const buildCommand: CliCommand = {
-  spec: {
-    name: 'build',
-    summary: 'build a container image, a single binary, or a prerendered static site',
-    usage: 'x build --target docker|binary|static [--tag name] [--out path] [--json]',
-    requiresApp: true,
-    flags: [
-      { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
-      { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
-      { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
-    ],
-  },
+  spec: buildSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('build', ctx.cwd).dir;
     const target = readTarget(flagString(ctx.args, 'target'));
@@ -186,15 +199,28 @@ export const buildCommand: CliCommand = {
     const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
       staticSteps.includes(step.name),
     );
-    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner });
+    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner, env: ctx.env });
     if (!verifyResult.ok) {
       return preflightResult(verifyResult);
     }
 
+    // A relative `--out` is a path the caller typed from where they stand, so it resolves against
+    // the cwd — against the root it landed somewhere else whenever `x build` ran from `apps/web`.
+    const outFlag = flagString(ctx.args, 'out');
     const out =
-      flagString(ctx.args, 'out') ?? join(root, '.x', target === 'static' ? 'static' : 'app');
+      outFlag === undefined
+        ? join(root, '.x', target === 'static' ? 'static' : 'app')
+        : resolve(ctx.cwd, outFlag);
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
-    const command = argsFor(target, { root, tag, out });
+    // The docker target stamps the manifest's build id into the image, and writes the island
+    // chunks the image serves, so a container boot neither re-derives the one nor rebuilds the other.
+    const buildId = target === 'docker' ? await prepareImage(root) : undefined;
+    const command = argsFor(target, {
+      root,
+      tag,
+      out,
+      ...(buildId === undefined ? {} : { buildId }),
+    });
     // Removed BEFORE the builder runs, so a build that writes no inventory can never be reported
     // with the last one's: a stale emitted list is worse than none, because it reads as this run's.
     if (target === 'static') await removeStaticReport(root);