@ultimat3/cli 1.2.0 → 2.0.0

package/src/island-bundle.ts

@@ -0,0 +1,166 @@
+// The island chunk table: every `*.island.tsx` in the app compiled as its OWN bundle entry point,
+// content-hashed, plus the resolver that turns a page's `src` specifier into the URL its
+// `data-x-entry` carries. One entry point per island is axiom 6 made mechanical — the page's graph
+// never reaches an island, so a `site/` document stays at 0kb whatever the island imports.
+
+// Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
+// POSIX by construction), `join`/`basename` the filesystem side.
+import { basename, join, posix, relative, sep } from 'node:path';
+import {
+  contentHash,
+  ISLAND_EXTENSION,
+  IslandInvalidError,
+  islandModuleId,
+} from '@ultimat3/render';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * Where a chunk is served from, in `x dev`, in the container and in a static export — one base
+ * path, because the URL is minted by one resolver and baked into the document. Sits beside
+ * `ICON_BASE_PATH` and `MEDIA_BASE_PATH`, deliberately outside the dev-only `/_x` namespace.
+ */
+export const ISLAND_BASE_PATH = '/islands';
+
+/**
+ * `shared/` is in and `api/` is out: an island is markup, and an API route has no document to put
+ * it in. The glob is the whole discovery rule — a file ships to the browser if and only if its
+ * name says so, which is what makes "what ships JS?" answerable without opening a file.
+ */
+export const ISLAND_GLOB = `apps/*/{site,app,shared}/**/*${ISLAND_EXTENSION}`;
+
+export interface IslandChunk {
+  /** App-root-relative POSIX path of the client entry it was built from. */
+  readonly file: string;
+  /** `islandModuleId` of the filename — the id the document, the budget and a finding all name. */
+  readonly moduleId: string;
+  /** Immutable, content-addressed URL. What `data-x-entry` carries and what a route serves. */
+  readonly url: string;
+  /** The built JavaScript. Held in memory so `x dev` and the container serve without a disk hop. */
+  readonly code: string;
+  readonly bytes: number;
+}
+
+export interface IslandBundle {
+  readonly chunks: readonly IslandChunk[];
+  /**
+   * The `resolve` a collector is built with, bound to the route file the specifier is relative to.
+   * Every island on that page goes through it, so an unbuildable specifier fails the render rather
+   * than emitting a `data-x-entry` no browser can import.
+   */
+  resolverFor(routeFile: string): (src: string) => string;
+  /** The chunk a URL names — for serving it, and for naming the island a budget finding blames. */
+  chunkAt(url: string): IslandChunk | undefined;
+}
+
+/** App-root-relative POSIX paths of every client entry, sorted, so a build is reproducible. */
+export async function discoverIslands(root: string): Promise<readonly string[]> {
+  const files: string[] = [];
+  for await (const absolute of new Bun.Glob(ISLAND_GLOB).scan({ cwd: root, absolute: true })) {
+    if (absolute.includes('node_modules')) continue;
+    files.push(relative(root, absolute).split(sep).join('/'));
+  }
+  return files.sort();
+}
+
+/**
+ * One `Bun.build` per island, never one call with N entry points: splitting is off, so each chunk
+ * is self-contained and its size is the whole answer to "what does booting this island cost?" —
+ * a shared chunk would make the honest number a graph walk, and the budget compares against bytes.
+ */
+async function buildOne(root: string, file: string): Promise<IslandChunk> {
+  // `Bun.build` REJECTS on a failed bundle, it does not answer `success: false` — so the catch is
+  // the real path here and the `success` test below is the belt for a future default.
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [join(root, file)],
+      target: 'browser',
+      format: 'esm',
+      splitting: false,
+      minify: true,
+    });
+  } catch (error) {
+    throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
+  }
+  const output = built.outputs.find((artifact) => artifact.kind === 'entry-point');
+  if (!built.success || output === undefined) {
+    throw new IslandBuildFailedError({
+      file,
+      logs: built.logs.map((log) => String(log)).join('; '),
+    });
+  }
+  const code = await output.text();
+  const moduleId = islandModuleId(basename(file));
+  return {
+    file,
+    moduleId,
+    // Hashed with the framework's own `contentHash`, the function that already stamps an ETag and
+    // a precache revision — one identity for a byte string, not a third.
+    url: `${ISLAND_BASE_PATH}/${moduleId}-${contentHash(code)}.js`,
+    code,
+    bytes: new TextEncoder().encode(code).byteLength,
+  };
+}
+
+/**
+ * The bundler's own diagnostics, kept verbatim. An `AggregateError` holds one entry per unresolved
+ * import or syntax error, and flattening them is what puts the line number in the cause instead of
+ * the word "Bundle failed".
+ */
+function describeBuildError(error: unknown): string {
+  if (error instanceof AggregateError) {
+    return error.errors.map((one: unknown) => String(one)).join('; ');
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Build every island in the app. An app with none returns an empty bundle and costs one glob. */
+export async function buildIslands(root: string): Promise<IslandBundle> {
+  const files = await discoverIslands(root);
+  const chunks = await Promise.all(files.map((file) => buildOne(root, file)));
+  return islandBundle(chunks);
+}
+
+export function islandBundle(chunks: readonly IslandChunk[]): IslandBundle {
+  const byFile = new Map(chunks.map((chunk) => [chunk.file, chunk]));
+  const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));
+  return {
+    chunks,
+    resolverFor(routeFile: string): (src: string) => string {
+      const dir = posix.dirname(routeFile);
+      return (src: string): string => {
+        const target = posix.normalize(posix.join(dir, src));
+        const chunk = byFile.get(target);
+        if (chunk === undefined) throw entryMissing(routeFile, src, target, chunks);
+        return chunk.url;
+      };
+    },
+    chunkAt: (url: string): IslandChunk | undefined => byUrl.get(url),
+  };
+}
+
+/**
+ * The specifier named no file the build could bundle. `X_ISLAND_INVALID` is render's and is
+ * borrowed rather than renamed here: "this src cannot become a client entry" is the condition that
+ * code already means, and a second name for it is a second thing to look up.
+ */
+function entryMissing(
+  routeFile: string,
+  src: string,
+  target: string,
+  chunks: readonly IslandChunk[],
+): IslandInvalidError {
+  const known = chunks.map((chunk) => chunk.file);
+  return new IslandInvalidError(
+    `${routeFile} declares island src ${JSON.stringify(src)}, which resolves to ${target} — a ` +
+      `file this build did not bundle (${known.length === 0 ? 'it found no islands at all' : `it found ${known.join(', ')}`})`,
+    `x g island ${posix.basename(target, ISLAND_EXTENSION)} --at ${posix.dirname(target)}`,
+  );
+}
+
+/** Write every chunk under the static export, at the same URL the documents already carry. */
+export async function writeIslands(bundle: IslandBundle, out: string): Promise<void> {
+  for (const chunk of bundle.chunks) {
+    await Bun.write(join(out, chunk.url.slice(1)), chunk.code);
+  }
+}

package/src/island-routes.ts

@@ -0,0 +1,50 @@
+// Serving the island chunks a build produced. `x dev` and the container mount the same route over
+// the same table, because a chunk URL is baked into the document by one resolver — a dev-only path
+// would be a page that boots in `x dev` and 404s in the image.
+
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { IslandBundle } from './island-bundle';
+import { ISLAND_BASE_PATH } from './island-bundle';
+
+/**
+ * A getter, not the bundle: `x dev` rebuilds the chunks on the same watcher tick that rebuilds the
+ * manifest, and a table captured when the route was mounted would serve the island as it was at
+ * boot for the rest of the session.
+ */
+export type IslandSource = () => IslandBundle;
+
+/**
+ * The URL is content-addressed, so the bytes behind it never change and the answer is immutable.
+ * A miss can only be a document older than this process's chunks — which is a fact worth stating,
+ * not a bare 404 whose meaning an agent has to guess.
+ */
+export function islandRoutes(source: IslandSource): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${ISLAND_BASE_PATH}/*file`,
+      meta: { name: 'assets.island', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const chunk = source().chunkAt(request.pathname);
+        if (chunk === undefined) {
+          return json(
+            {
+              ok: false,
+              error: {
+                code: 'X_ROUTE_NOT_FOUND',
+                cause: `no island chunk is built at ${request.pathname} — the document that asked for it was rendered against an older build`,
+                fix: 'x build --target static --json   # then reload, so the page carries this build’s chunk URLs',
+              },
+            },
+            { status: 404 },
+          );
+        }
+        return applyCacheHeaders(
+          new Response(chunk.code, { headers: { 'content-type': 'text/javascript' } }),
+          { mode: 'immutable' },
+        );
+      },
+    },
+  ];
+}

package/src/jobs-driver.ts

@@ -0,0 +1,33 @@
+// The one place a CLI command gets hold of the app's job queue. `x jobs` and `x db backfill`
+// both need a `JobDriver` and neither owns one — a second copy of this boot would be two answers
+// to "which queue is this command talking to", which is the drift axiom 1 refuses.
+
+import type { JobDriver } from '@ultimat3/jobs';
+import { jobDriver } from '@ultimat3/jobs';
+import type { CommandContext } from './command';
+import { startQueue } from './dev-queue';
+import { resolveServices } from './dev-services';
+import type { CommandResult } from './output';
+
+/**
+ * `x jobs` needs the app's real driver. Reuse an already-running one first — inside `x dev` or
+ * `x mcp serve`, `jobDriver()` is already set and booting a second queue on top of it would talk
+ * to the wrong database. Otherwise boot just the db + jobs half (`startQueue`, not the full
+ * `startServices`: these commands touch no transport, storage or mail) and always release it, or
+ * a CLI that exits holding the PGlite lock breaks the next command run against this app.
+ */
+export async function withJobDriver(
+  root: string,
+  ctx: CommandContext,
+  fn: (driver: JobDriver) => Promise<CommandResult>,
+): Promise<CommandResult> {
+  const ambient = jobDriver();
+  if (ambient !== undefined) return fn(ambient);
+  const services = resolveServices(root, ctx.env);
+  const queue = await startQueue(services);
+  try {
+    return await fn(queue.jobs);
+  } finally {
+    await queue.stop();
+  }
+}

package/src/jobs-json.ts

@@ -3,6 +3,7 @@
 // enforceable if the projections sit together where one missing `?? null` is visible.
 
 import type {
+  BackfillProgress,
   DeadLetterEntry,
   JobRecord,
   JobTrace,
@@ -26,6 +27,26 @@ function stepTraceToJson(step: StepTrace): JsonValue {
   };
 }
 
+/**
+ * One `x_backfills` row. Every absent value is already `null` at the source (`toBackfillProgress`
+ * makes it so), which is what lets this be a straight field list — and it is spelled out rather
+ * than spread so a field added upstream arrives here as a decision, not as untyped passthrough.
+ */
+export function backfillToJson(progress: BackfillProgress): JsonValue {
+  return {
+    runId: progress.runId,
+    name: progress.name,
+    status: progress.status,
+    checksum: progress.checksum,
+    appVersion: progress.appVersion,
+    rows: progress.rows,
+    cursor: progress.cursor,
+    startedAt: progress.startedAt,
+    completedAt: progress.completedAt,
+    durationMs: progress.durationMs,
+  };
+}
+
 export function jobTraceToJson(trace: JobTrace): JsonValue {
   return {
     id: trace.id,
@@ -41,6 +62,9 @@ export function jobTraceToJson(trace: JobTrace): JsonValue {
     tenantId: trace.tenantId,
     steps: trace.steps.map(stepTraceToJson),
     retryDelaysMs: trace.retryDelaysMs.map((ms) => ms),
+    // `null` for every job that is not a `backfill()` pass. Dropped, `x jobs show <id> --json`
+    // would answer "how far has it got" with silence for the one job kind that can say.
+    backfill: trace.backfill === null ? null : backfillToJson(trace.backfill),
   };
 }
 

package/src/jobs-report.ts

@@ -3,6 +3,7 @@
 // alone. Drain is `jobs-drain.ts`, the `--json` shapes `jobs-json.ts`, the table `jobs-table.ts`.
 
 import type {
+  BackfillProgress,
   DeadLetterEntry,
   JobDriver,
   JobFilter,
@@ -12,6 +13,7 @@ import type {
   QueueDepthReport,
 } from '@ultimat3/jobs';
 import {
+  inspectBackfills,
   inspectDeadLetters,
   inspectJob,
   inspectJobList,
@@ -48,15 +50,18 @@ export function parseStateFlag(value: string | undefined): JobState | undefined
  * A digit string is not yet a limit: past `Number.MAX_SAFE_INTEGER` the parse silently lands on a
  * different integer, and `1e400`-shaped input yields `Infinity`. Either way the driver would be
  * handed a bound other than the one typed, so the safe-integer check is the flag's real contract.
+ *
+ * `command` exists because `x db backfill --list` takes the same `--limit` and must not report it
+ * as a flag on `x jobs` — one parser, and the error still names the command that was typed.
  */
-export function parseLimitFlag(value: string | undefined): number | undefined {
+export function parseLimitFlag(value: string | undefined, command = 'jobs'): number | undefined {
   if (value === undefined) return undefined;
   const digits = value.trim();
   const limit = /^\d+$/.test(digits) ? Number(digits) : Number.NaN;
   if (!Number.isSafeInteger(limit) || limit <= 0) {
     throw new BadFlagError({
       flag: 'limit',
-      command: 'jobs',
+      command,
       reason: `expects an integer from 1 to ${Number.MAX_SAFE_INTEGER}, got "${value}"`,
     });
   }
@@ -76,12 +81,19 @@ export interface JobsListResult {
   readonly depth: QueueDepthReport;
   readonly rows: readonly JobRecord[];
   readonly deadLetters: readonly DeadLetterEntry[];
+  /** The sweeps still in flight — see below for why finished ones are not this command's answer. */
+  readonly backfills: readonly BackfillProgress[];
 }
 
 /**
  * The depth report AND the filtered rows, plus dead letters unconditionally: a dead job that a
  * `--state ready` filter (or the default 100-row cap) pushes out of view is the exact failure
  * mode this command exists to prevent.
+ *
+ * Backfills are read `running` only. `x jobs ls` is a LIVE view of the queue — a pass that
+ * finished last week is history, and `x db backfill --list` is where that question is asked and
+ * answered with the whole ledger. A driver with no ledger answers `[]` rather than throwing, so
+ * the queue view never fails over a fact nobody asked about.
  */
 export async function listJobs(
   driver: JobDriver,
@@ -95,12 +107,13 @@ export async function listJobs(
     ...(state === undefined ? {} : { state }),
     ...(limit === undefined ? {} : { limit }),
   };
-  const [depth, rows, deadLetters] = await Promise.all([
+  const [depth, rows, deadLetters, backfills] = await Promise.all([
     inspectQueues(driver),
     inspectJobList(driver, jobFilter),
     inspectDeadLetters(driver),
+    inspectBackfills(driver, { status: 'running' }),
   ]);
-  return { depth, rows, deadLetters };
+  return { depth, rows, deadLetters, backfills };
 }
 
 // ── show ──────────────────────────────────────────────────────────────────

package/src/mcp-db-target.ts

@@ -1,36 +1,64 @@
-// Which database the MCP dev host is pointed at, and whether that database is a branch. `db.migrate`
-// decides from this alone, so the reading has to be exact: a wrong `branch` is a migration against a
-// database somebody else is using.
+// Which database the MCP dev host is pointed at: whether it is a branch, and whether this is
+// production. `db.migrate` decides from these two alone, so both readings have to be exact — a
+// wrong `branch` is a migration against a database somebody else is using, and a `production` that
+// is always false is a refusal that never runs.
 
-import { basename, join } from 'node:path';
+// `node:path` for the joiner Bun has no equivalent of — the same reason `db-branch.ts` reaches for
+// it, and the state directory it builds a path under is a real one on disk.
+import { join } from 'node:path';
+import { tryResolveEnvironment } from '@ultimat3/core';
 import { pgliteDataDir } from '@ultimat3/db';
 import type { DatabaseTarget } from '@ultimat3/mcp';
-import type { DevServices } from './dev-services';
+import { branchNameOf, pgliteBranchName } from './db-branch';
+import type { DevServices, Env } from './dev-services';
+import { safeUrlLabel } from './safe-url-label';
 
 /**
- * `production` is always false: this target is whatever `x dev` resolved — embedded PGlite under
- * `.x/`, or the `DATABASE_URL` of a developer's shell. Production is reached through `ROLE=migrate`
- * in a deploy hook, never through MCP. What actually stops a migration against a shared database is
- * `branch`, which is null unless the name says otherwise.
+ * `production` was the literal `false` in both arms until `As of 2026-08`, and this is the only
+ * place a `DatabaseTarget` is ever built — so `assertBranchDatabase`'s FIRST refusal, the one
+ * meaning "production is never migratable from MCP at all", could not run for any database this
+ * CLI produced. A production database refused it only incidentally, because its name lacked
+ * `_branch_`; one named `shop_branch_hotfix`, or a container whose data directory is
+ * `pgdata-hotfix`, read as a branch and was migratable through an MCP tool call.
+ *
+ * The environment is read the way `x doctor` reads it (`cmd-doctor.ts`), through core's one key —
+ * so `production` is a fact about the deploy and `branch` stays a fact about the database, and
+ * `@ultimat3/mcp` keeps receiving two answers rather than re-deriving either.
  */
-export function databaseTarget(services: DevServices): DatabaseTarget {
+export function databaseTarget(services: DevServices, env: Env): DatabaseTarget {
   const url = services.db.url;
+  const production = isProduction(env);
   return services.db.mode === 'embedded'
-    ? { label: url, branch: pgliteBranch(url, services.stateDir), production: false }
-    : { label: safeLabel(url), branch: postgresBranch(url), production: false };
+    ? { label: url, branch: pgliteBranch(url, services.stateDir), production }
+    : {
+        // An external `DATABASE_URL` may carry credentials, and this string gets printed.
+        label: safeUrlLabel(url, 'external database'),
+        branch: postgresBranch(url),
+        production,
+      };
 }
 
-/** An external `DATABASE_URL` may carry credentials, and this string gets printed. */
-function safeLabel(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
-  } catch {
-    return 'external database';
-  }
-}
+/**
+ * The non-throwing read, because `ULTIMATE_ENV` is in no env schema — nothing validates it at boot,
+ * and a tool call is not where a typo should surface as a crash (`cmd-doctor.ts` chose the same
+ * variant for the same reason).
+ *
+ * `undefined` is answered **true**, and that is the whole point of using it here. It means exactly
+ * one thing: `ULTIMATE_ENV` is set to something that is not an environment. Reading a typo as "not
+ * production" would let the single misconfiguration this guard exists to survive defeat it — so an
+ * environment that cannot be read is treated as the most dangerous one it could be.
+ */
+const isProduction = (env: Env): boolean => {
+  const environment = tryResolveEnvironment({ env });
+  return environment === undefined || environment === 'production';
+};
 
-/** `x db branch <name>` names an external clone `<source>_branch_<name>` (`branchDatabaseName`). */
+/**
+ * `x db branch create <name>` names an external clone `<source>_branch_<name>`. Both readings come
+ * from `db-branch.ts` — the module that also WRITES those names — because a target that disagrees
+ * with `x db branch ls` about what a branch is would let `db.migrate` run against a shared
+ * database on the strength of a naming rule one of the two had drifted away from.
+ */
 function postgresBranch(url: string): string | null {
   let database: string;
   try {
@@ -38,13 +66,10 @@ function postgresBranch(url: string): string | null {
   } catch {
     return null;
   }
-  return /_branch_(.+)$/.exec(database)?.[1] ?? null;
+  return branchNameOf(database);
 }
 
 /** `branchPglite` copies `<stateDir>/pgdata` to `<stateDir>/pgdata-<name>`; the dev dir is no branch. */
 function pgliteBranch(url: string, stateDir: string): string | null {
-  const dir = pgliteDataDir(url);
-  const dev = join(stateDir, 'pgdata');
-  if (dir === dev || basename(dir) === basename(dev)) return null;
-  return dir.startsWith(`${dev}-`) ? dir.slice(dev.length + 1) : null;
+  return pgliteBranchName(pgliteDataDir(url), join(stateDir, 'pgdata'));
 }