@ultimat3/cli 1.0.0

package/src/app-manifest.ts

@@ -0,0 +1,137 @@
+// `x.manifest.json`: the framework's registries projected by `@ultimat3/manifest`. The CLI
+// supplies the facts that package cannot reach for itself — the app's name and version, the route
+// table, which surface enforces each permission, the locales the app registered, and the error
+// codes its source declares.
+
+// Bun ships no `Bun.*` path API: `join` builds the host-separator path to `x.manifest.json`.
+import { join } from 'node:path';
+import { describeActions } from '@ultimat3/action';
+import { registeredLocales } from '@ultimat3/i18n';
+import { registeredTasks } from '@ultimat3/jobs';
+import type { Manifest, PolicyFact, RouteFact, TaskFact } from '@ultimat3/manifest';
+import {
+  buildManifest,
+  emitManifest,
+  frameworkSources,
+  MANIFEST_FILENAME,
+  readManifest,
+} from '@ultimat3/manifest';
+import { knownPermissions } from '@ultimat3/policy';
+import { describeQueries } from '@ultimat3/query';
+import type { RouteDescriptor } from '@ultimat3/render';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { AppPackageInvalidError } from './errors';
+import type { Finding } from './output';
+
+export interface AppManifest {
+  readonly manifest: Manifest;
+  /** Modules that would not load or register. The manifest describes what did.  */
+  readonly findings: readonly Finding[];
+}
+
+/** Load the app, then describe it. Every command that needs facts goes through here. */
+export async function appManifest(root: string): Promise<AppManifest> {
+  const loaded = await loadApp(root);
+  const manifest = buildManifest(
+    frameworkSources({
+      app: await appIdentity(root),
+      routes: routeFacts(),
+      policies: policyFacts(),
+      tasks: taskFacts(),
+      // The i18n registry, never a scan of `packages/i18n/catalogs/`: `loadApp` above has already
+      // imported every app module, so each `defineCatalogs()` has run and registered its locales.
+      // Counting catalog files instead would be a second answer, wrong the day the two disagree.
+      locales: registeredLocales(),
+      errorCodes: loaded.errorCodes,
+    }),
+  );
+  return { manifest, findings: loaded.findings };
+}
+
+export async function writeAppManifest(root: string, manifest: Manifest): Promise<string> {
+  const { path } = await emitManifest({ manifest, path: join(root, MANIFEST_FILENAME) });
+  return path;
+}
+
+/** The committed contract, or undefined when the app has never generated one. */
+export const readAppManifest = async (root: string): Promise<Manifest | undefined> =>
+  readManifest(join(root, MANIFEST_FILENAME));
+
+const jsonObject = async (file: Bun.BunFile): Promise<Record<string, unknown> | undefined> => {
+  const parsed: unknown = await file.json().catch(() => undefined);
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : undefined;
+};
+
+/**
+ * Name and version come from `package.json`: the manifest's version gate is a semver gate, so a
+ * default of `app@0.0.0` would silently overwrite the compatibility contract with an identity the
+ * app never claimed. Every way of not knowing fails here instead.
+ */
+async function appIdentity(root: string): Promise<{ name: string; version: string }> {
+  const path = join(root, 'package.json');
+  const file = Bun.file(path);
+  if (!(await file.exists())) throw new AppPackageInvalidError({ path, problem: 'does not exist' });
+  const parsed = await jsonObject(file);
+  if (parsed === undefined)
+    throw new AppPackageInvalidError({ path, problem: 'is not a JSON object' });
+  const { name, version } = parsed;
+  if (typeof name !== 'string')
+    throw new AppPackageInvalidError({ path, problem: 'has no string "name"' });
+  if (typeof version !== 'string')
+    throw new AppPackageInvalidError({ path, problem: 'has no string "version"' });
+  return { name, version };
+}
+
+type UrlRoute = RouteDescriptor & { readonly surface: 'site' | 'app' | 'api' };
+
+/** `shared/` is a leaf, never a URL — a descriptor there is a file naming mistake, not a route. */
+const hasUrl = (route: RouteDescriptor): route is UrlRoute => route.surface !== 'shared';
+
+const routeFacts = (): readonly RouteFact[] =>
+  describeRoutes()
+    .filter(hasUrl)
+    .map((route) => ({
+      url: route.path,
+      render: route.mode,
+      offline: route.offline,
+      hydrate: route.hydrate,
+      revalidateTags: route.revalidateTags,
+      surface: route.surface,
+      ...budgetOf(route),
+    }));
+
+function budgetOf(route: RouteDescriptor): { budget?: { js?: string; lcp?: number } } {
+  if (route.budgetJs === null && route.budgetLcp === null) return {};
+  return {
+    budget: {
+      ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
+      ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
+    },
+  };
+}
+
+/**
+ * One permission, N surfaces — `enforcedIn` is that list, derived from the actions and queries
+ * that actually assert it rather than declared a second time next to the policy.
+ */
+export function policyFacts(): readonly PolicyFact[] {
+  const enforced = new Map<string, string[]>();
+  const add = (permission: string, where: string): void => {
+    if (permission.length === 0) return;
+    enforced.set(permission, [...(enforced.get(permission) ?? []), where]);
+  };
+  for (const action of describeActions()) add(action.capability, `action:${action.name}`);
+  for (const query of describeQueries()) add(query.capability, `query:${query.name}`);
+
+  return [...new Set([...knownPermissions(), ...enforced.keys()])]
+    .sort()
+    .map((permission) => ({ permission, enforcedIn: enforced.get(permission) ?? [] }));
+}
+
+const taskFacts = (): readonly TaskFact[] =>
+  registeredTasks()
+    .map((handle) => handle.describe())
+    .map((task) => ({ name: task.name, cron: task.cron, tz: task.tz, enqueues: task.jobs }));

package/src/app-openapi.ts

@@ -0,0 +1,12 @@
+// `openapi.json`, projected from the action registry by `@ultimat3/action`. The CLI writes the
+// file and compares the bytes; it does not know how an operation is shaped, which is why there
+// is no second OpenAPI builder to drift from the one the server serves.
+
+import { buildOpenApi, serializeOpenApi } from '@ultimat3/action';
+import type { Manifest } from '@ultimat3/manifest';
+
+export const OPENAPI_FILE = 'openapi.json';
+
+/** The exact bytes on disk — deterministic, so `x verify` can compare them literally. */
+export const openApiJson = (manifest: Manifest): string =>
+  serializeOpenApi(buildOpenApi({ title: manifest.app.name, version: manifest.app.version }));

package/src/app-root.ts

@@ -0,0 +1,57 @@
+// Locating the app. `app.config.ts` is the one config file, so it is also the one root marker —
+// commands that need an app resolve it here and nowhere else, and the failure names the fix.
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { BunVersionError, NotInAppError } from './errors';
+
+export const APP_CONFIG_FILE = 'app.config.ts';
+export const MANIFEST_FILE = 'x.manifest.json';
+export const REQUIRED_BUN = '1.3.0';
+
+export interface AppRoot {
+  readonly dir: string;
+  readonly configPath: string;
+  readonly manifestPath: string;
+}
+
+/** Walk up from `from` looking for `app.config.ts`. Returns undefined outside an app. */
+export function findAppRoot(from: string): AppRoot | undefined {
+  let dir = resolve(from);
+  for (;;) {
+    const configPath = join(dir, APP_CONFIG_FILE);
+    if (existsSync(configPath)) {
+      return { dir, configPath, manifestPath: join(dir, MANIFEST_FILE) };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+export function requireAppRoot(command: string, from: string): AppRoot {
+  const root = findAppRoot(from);
+  if (root === undefined) throw new NotInAppError({ command, from: resolve(from) });
+  return root;
+}
+
+/** Semver-lite compare, sufficient because both sides are plain `major.minor.patch`. */
+export function versionAtLeast(found: string, required: string): boolean {
+  const parse = (input: string): readonly number[] =>
+    input
+      .split('-')[0]
+      ?.split('.')
+      .map((part) => Number.parseInt(part, 10) || 0) ?? [];
+  const a = parse(found);
+  const b = parse(required);
+  for (let i = 0; i < 3; i += 1) {
+    const left = a[i] ?? 0;
+    const right = b[i] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return true;
+}
+
+export function requireBunVersion(found: string, required: string = REQUIRED_BUN): void {
+  if (!versionAtLeast(found, required)) throw new BunVersionError({ found, required });
+}

package/src/bin.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+// The `x` entrypoint. Nothing lives here but argv, stdout and the exit code — every decision is in
+// dispatch.ts, so the whole CLI is testable without spawning a process.
+
+import { dispatch } from './dispatch';
+
+const code = await dispatch({
+  argv: Bun.argv.slice(2),
+  cwd: process.cwd(),
+  env: Bun.env,
+  bunVersion: Bun.version,
+  write: (line) => {
+    process.stdout.write(`${line}\n`);
+  },
+});
+
+process.exit(code);

package/src/boundary-cuts.ts

@@ -0,0 +1,219 @@
+// The pure planner behind `x fix boundary`: turns every `BoundaryViolation` chain that touches a
+// target file into a printable cut — the one edge to delete — and, when relocating a `shared/`
+// module is what removes that edge, the `git mv` plus every import specifier the move invalidates.
+// No I/O: the caller has already read the sources and built the graph.
+
+import type { BoundaryRule, BoundaryViolation, ImportGraph, Surface } from '@ultimat3/render';
+import { checkSurfaceBoundary, surfaceOf } from '@ultimat3/render';
+import type { BoundaryCode } from './app-boundaries';
+import { boundaryCodeOf, relativeSpecifier, resolveSpecifier } from './app-boundaries';
+
+/** One specifier the move invalidates: where it is written, what it names, what it must become. */
+export interface SpecifierEdit {
+  /** The file to edit, at the path it holds once the move is applied. */
+  readonly file: string;
+  /** The file the specifier resolves to today — how a caller finds it among that file's imports. */
+  readonly imported: string;
+  /** Its replacement, relative to `file`'s own directory after the move. */
+  readonly specifier: string;
+}
+
+/** Generated only when moving the module is what removes the violated edge. */
+export interface BoundarySplit {
+  readonly module: string;
+  readonly surface: Surface;
+  readonly to: string;
+  /** `git mv <module> <to>` — runnable as-is from the app root. */
+  readonly command: string;
+  /** Direct importers of `module` — the files whose specifier needs the new path. */
+  readonly importers: readonly string[];
+  /** The other half of the repair: every specifier `command` alone would leave dangling. */
+  readonly edits: readonly SpecifierEdit[];
+}
+
+export interface BoundaryCut {
+  readonly code: BoundaryCode;
+  readonly rule: BoundaryRule;
+  readonly entry: string;
+  /** The file to edit. */
+  readonly at: string;
+  /** The single edge a caller can delete to clear this violation. */
+  readonly edge: { readonly from: string; readonly to: string };
+  readonly chain: readonly string[];
+  readonly cause: string;
+  readonly edit: string;
+  readonly split: BoundarySplit | null;
+}
+
+const involves = (violation: BoundaryViolation, target: string): boolean =>
+  violation.entry === target || violation.importer === target || violation.chain.includes(target);
+
+function reverseGraph(graph: ImportGraph): ReadonlyMap<string, ReadonlySet<string>> {
+  const reverse = new Map<string, Set<string>>();
+  for (const [file, refs] of graph) {
+    for (const ref of refs) {
+      const predecessors = reverse.get(ref.file) ?? new Set<string>();
+      predecessors.add(file);
+      reverse.set(ref.file, predecessors);
+    }
+  }
+  return reverse;
+}
+
+/** Files with a specifier that resolves straight onto `module` — exactly who `git mv` breaks. */
+function directImporters(graph: ImportGraph, module: string): readonly string[] {
+  const found: string[] = [];
+  for (const [file, refs] of graph) {
+    if (refs.some((ref) => ref.file === module)) found.push(file);
+  }
+  return found.sort();
+}
+
+/**
+ * Every non-`shared/` surface that transitively reaches `module`, through any number of further
+ * `shared/` hops. That is what "actually reach" means: a `shared/` re-export only counts once
+ * the walk lands outside `shared/` entirely.
+ */
+function surfacesReaching(graph: ImportGraph, module: string): readonly Surface[] {
+  const reverse = reverseGraph(graph);
+  const seen = new Set<string>([module]);
+  const queue: string[] = [module];
+  const surfaces = new Set<Surface>();
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) break;
+    for (const predecessor of reverse.get(current) ?? []) {
+      const surface = surfaceOf(predecessor);
+      if (surface !== null && surface !== 'shared') surfaces.add(surface);
+      if (seen.has(predecessor)) continue;
+      seen.add(predecessor);
+      queue.push(predecessor);
+    }
+  }
+  return [...surfaces].sort();
+}
+
+/** `apps/web/shared/ui/panel.tsx` relocated under `app/` → `apps/web/app/ui/panel.tsx`. */
+const relocate = (path: string, surface: Surface): string =>
+  path.replace(/(^|\/)shared\//, `$1${surface}/`);
+
+/**
+ * Every specifier the move breaks: each direct importer's path onto `module`, and `module`'s own
+ * relative imports, which travel with the file and stop resolving from its new directory. A move
+ * published without them is a repair that leaves the tree not building.
+ */
+function specifierEdits(
+  graph: ImportGraph,
+  module: string,
+  to: string,
+  importers: readonly string[],
+): readonly SpecifierEdit[] {
+  const keys = new Set(graph.keys());
+  const edits: SpecifierEdit[] = importers.map((file) => ({
+    file,
+    imported: module,
+    specifier: relativeSpecifier(file, to),
+  }));
+  for (const ref of graph.get(module) ?? []) {
+    // Only edges that land on a scanned file: a bare package specifier does not move with the
+    // file, and the graph never held the text of one, so a rewrite for it would be a guess.
+    if (!keys.has(ref.file)) continue;
+    // Sibling surfaces sit at the same depth, so a `../` specifier survives the move untouched.
+    const written = relativeSpecifier(module, ref.file);
+    if (resolveSpecifier(to, written, keys) === ref.file) continue;
+    edits.push({ file: to, imported: ref.file, specifier: relativeSpecifier(to, ref.file) });
+  }
+  return edits;
+}
+
+/**
+ * A relocation repairs a violation only when the module lands on the same surface as the file it
+ * imports — that is what turns the flagged cross-surface edge into a legal same-surface one.
+ * `site-imports-app` never qualifies: a module `site/` reaches carries the identical `site/ →
+ * app/` edge into `site/` with it, so the move would relocate the file and fix nothing.
+ */
+const relocationRepairs = (violation: BoundaryViolation, surface: Surface): boolean =>
+  violation.rule === 'shared-is-a-leaf' && surfaceOf(violation.imported) === surface;
+
+/**
+ * The `shared/` fattening remedy. One surface reaching `module` means it was never shared, so
+ * the cut is mechanical. Two or more means it really is shared and a human has to decide which
+ * part goes where — never invent a split the graph cannot justify.
+ */
+function planSplit(
+  graph: ImportGraph,
+  violation: BoundaryViolation,
+  surfaces: readonly Surface[],
+): BoundarySplit | null {
+  if (surfaces.length !== 1) return null;
+  const [surface] = surfaces;
+  if (surface === undefined || !relocationRepairs(violation, surface)) return null;
+  const module = violation.importer;
+  const to = relocate(module, surface);
+  const importers = directImporters(graph, module);
+  return {
+    module,
+    surface,
+    to,
+    command: `git mv ${module} ${to}`,
+    importers,
+    edits: specifierEdits(graph, module, to, importers),
+  };
+}
+
+/** The move alone is half a repair, so it is published with every rewrite it forces. */
+const splitEdit = (split: BoundarySplit): string =>
+  split.edits.length === 0
+    ? split.command
+    : `${split.command}   # then ${split.edits
+        .map((edit) => `in ${edit.file}, ${edit.imported} → '${edit.specifier}'`)
+        .join('; ')}`;
+
+/**
+ * No relocation clears this one, so the instruction is the edit itself: which import to delete,
+ * and the two ways out — hoist what the module needs into the module, or invert the call so the
+ * surface that reaches it passes the value in.
+ */
+function manualEdit(violation: BoundaryViolation, surfaces: readonly Surface[]): string {
+  const reach = surfaces.length === 0 ? 'no surface' : surfaces.join(' and ');
+  return `${violation.importer} is reached by ${reach}, so relocating it keeps the edge: delete the import of ${violation.imported} in ${violation.importer} — move what it needs into ${violation.importer}, or have the caller pass it in`;
+}
+
+function editFor(
+  violation: BoundaryViolation,
+  split: BoundarySplit | null,
+  surfaces: readonly Surface[],
+): string {
+  if (split !== null) return splitEdit(split);
+  if (violation.rule === 'app-imports-api-at-runtime') return violation.fix;
+  if (surfaceOf(violation.importer) === 'shared') return manualEdit(violation, surfaces);
+  return `delete the import of ${violation.imported} in ${violation.importer}`;
+}
+
+function toCut(violation: BoundaryViolation, graph: ImportGraph): BoundaryCut {
+  const module = violation.importer;
+  const surfaces = surfaceOf(module) === 'shared' ? surfacesReaching(graph, module) : [];
+  const split = planSplit(graph, violation, surfaces);
+  return {
+    code: boundaryCodeOf(violation.rule),
+    rule: violation.rule,
+    entry: violation.entry,
+    at: violation.importer,
+    edge: { from: violation.importer, to: violation.imported },
+    chain: violation.chain,
+    cause: violation.cause,
+    edit: editFor(violation, split, surfaces),
+    split,
+  };
+}
+
+/**
+ * Every boundary violation that touches `target`, turned into a printable cut. Pure — the
+ * caller has already read the app's sources and built the graph (`readAppSources` +
+ * `appImportGraph`), so this runs the same way in a test as it does in the CLI.
+ */
+export function planBoundaryCuts(target: string, graph: ImportGraph): readonly BoundaryCut[] {
+  return checkSurfaceBoundary(graph)
+    .filter((violation) => involves(violation, target))
+    .map((violation) => toCut(violation, graph));
+}

package/src/budgets.ts

@@ -0,0 +1,92 @@
+// Per-route budgets. A blown budget is a build failure, not a Lighthouse report nobody read —
+// and the finding names the import chain that caused it, because "your bundle got bigger" is not
+// an actionable message for a human or an agent.
+//
+// Byte parsing and formatting come from `@ultimat3/render`, which owns the budget vocabulary the
+// routes are declared in. The one thing that lives here is the comparison against MEASURED bytes:
+// render checks a bundle graph, this checks what the build actually emitted.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Manifest, RouteFact } from '@ultimat3/manifest';
+import { formatBytes, parseByteBudget } from '@ultimat3/render';
+import type { Finding } from './output';
+
+export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
+
+export interface RouteStats {
+  readonly path: string;
+  readonly jsBytes: number;
+  readonly lcpMs?: number;
+  /** Import chain that pulled the heaviest module into this route. */
+  readonly heaviestChain?: readonly string[];
+}
+
+export interface BuildStats {
+  readonly routes: readonly RouteStats[];
+}
+
+const chainOf = (stats: RouteStats): string =>
+  stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
+
+const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.budget?.js);
+
+/** Which budgets the route declared, for a cause line that names what went unmeasured. */
+function declaredBudgets(js: number | null, lcp: number | undefined): string {
+  const labels: string[] = [];
+  if (js !== null) labels.push('JS');
+  if (lcp !== undefined) labels.push('LCP');
+  return labels.join(' and ');
+}
+
+/**
+ * Compare declared budgets against measured stats. A declared budget with no measurement is a
+ * finding, never a pass: a route that clears the gate without ever being weighed is exactly the
+ * false green axiom 5 exists to prevent. Only a route that declares nothing is skipped.
+ */
+export function checkBudgets(manifest: Manifest, stats: BuildStats): readonly Finding[] {
+  const byPath = new Map(stats.routes.map((route) => [route.path, route]));
+  const findings: Finding[] = [];
+  for (const route of manifest.routes) {
+    const measured = byPath.get(route.url);
+    const js = jsBudgetOf(route);
+    const lcp = route.budget?.lcp;
+    if (measured === undefined) {
+      if (js !== null || lcp !== undefined) {
+        findings.push({
+          code: 'X_BUDGET_UNMEASURED',
+          cause: `${route.url} declares a ${declaredBudgets(js, lcp)} budget but ${BUILD_STATS_FILE} has no entry for it`,
+          fix: 'x build && x verify',
+          docs: 'https://ultimate.dev/errors/X_BUDGET_UNMEASURED',
+          at: route.url,
+        });
+      }
+      continue;
+    }
+    if (js !== null && measured.jsBytes > js) {
+      findings.push({
+        code: 'X_BUDGET_EXCEEDED',
+        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
+        fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
+        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        at: route.url,
+      });
+    }
+    if (lcp !== undefined && measured.lcpMs !== undefined && measured.lcpMs > lcp) {
+      findings.push({
+        code: 'X_BUDGET_EXCEEDED',
+        cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
+        fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
+        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        at: route.url,
+      });
+    }
+  }
+  return findings;
+}
+
+export async function readBuildStats(root: string): Promise<BuildStats | undefined> {
+  const path = join(root, BUILD_STATS_FILE);
+  if (!existsSync(path)) return undefined;
+  return (await Bun.file(path).json()) as BuildStats;
+}

package/src/cmd-build.ts

@@ -0,0 +1,109 @@
+// `x build --target docker|binary|static` — three targets, no platform primitives. Deploy anywhere
+// means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
+
+import { join } from 'node:path';
+import { requireAppRoot } from './app-root';
+import { runVerify } from './cmd-verify';
+import type { CliCommand, CommandContext } from './command';
+import { UnknownCommandError } from './errors';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { flagString } from './parse';
+
+export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
+
+export type BuildTarget = (typeof BUILD_TARGETS)[number];
+
+export function readTarget(raw: string | undefined): BuildTarget {
+  const targets: readonly string[] = BUILD_TARGETS;
+  if (raw === undefined) return 'docker';
+  if (targets.includes(raw)) return raw as BuildTarget;
+  throw new UnknownCommandError({
+    path: `build --target ${raw}`,
+    known: BUILD_TARGETS,
+    suggestion: 'build --target docker',
+  });
+}
+
+/** 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, 'docker', 'Dockerfile'), '-t', tag, root];
+}
+
+export function binaryArgs(root: string, out: string): readonly string[] {
+  return [
+    'bun',
+    'build',
+    '--compile',
+    '--minify',
+    join(root, 'apps', 'web', 'server.ts'),
+    '--outfile',
+    out,
+  ];
+}
+
+export function staticArgs(root: string, out: string): readonly string[] {
+  return ['bun', 'run', join(root, 'apps', 'web', 'prerender.ts'), '--out', out];
+}
+
+export function argsFor(
+  target: BuildTarget,
+  paths: { readonly root: string; readonly tag: string; readonly out: string },
+): readonly string[] {
+  if (target === 'docker') return dockerArgs(paths.root, paths.tag);
+  if (target === 'binary') return binaryArgs(paths.root, paths.out);
+  return staticArgs(paths.root, paths.out);
+}
+
+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)' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('build', ctx.cwd).dir;
+    const target = readTarget(flagString(ctx.args, 'target'));
+
+    // Run static verify steps before building.
+    const staticSteps = ['typecheck', 'lint', 'boundaries', 'filesize', 'package-shape', 'errors'];
+    const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
+      staticSteps.includes(step.name),
+    );
+    const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner });
+    if (!verifyResult.ok) {
+      return verifyResult;
+    }
+
+    const out =
+      flagString(ctx.args, 'out') ?? join(root, '.x', target === 'static' ? 'static' : 'app');
+    const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
+    const command = argsFor(target, { root, tag, out });
+    const result = await ctx.runner(command, { cwd: root });
+    const findings: readonly Finding[] = result.ok
+      ? []
+      : [
+          {
+            code: 'X_BUILD_FAILED',
+            cause: `${command.join(' ')} exited ${result.code}`,
+            fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
+            docs: 'https://ultimate.dev/errors/X_BUILD_FAILED',
+          },
+        ];
+    return {
+      ok: result.ok,
+      command: 'build',
+      summary: msg('cli.build.done', { target }),
+      findings,
+      data: { target, artifact: target === 'docker' ? tag : out, durationMs: result.durationMs },
+      lines: result.ok ? [] : execOutput(result).split('\n'),
+    };
+  },
+};