@ultimat3/cli 29.4.0 → 30.0.0

package/src/cmd-upgrade.ts

@@ -0,0 +1,274 @@
+// `x upgrade`: one major per run. Refuse a dirty tree, write exact pins and the Bun floor, install,
+// then let the CLI just installed run the gate. It never commits: git is the state between runs, so
+// a hop is one reviewable commit. No `await import()` anywhere below — `bun install` replaces this
+// very file under the running process when the app's own CLI is the one that was run.
+
+// why: Bun exposes no path-join primitive; the git root and the app root are joined with paths.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import { versionAtLeast } from './app-root';
+import { upgradeSpec } from './cmd-upgrade-spec';
+import type { CliCommand, CommandContext } from './command';
+import { failed, ok } from './command';
+import { BadFlagError, BunVersionError } from './errors';
+import type { Runner } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool, flagString } from './parse';
+import { posixRelative } from './posix-path';
+import { applyAgentsLink, planAgentsLink } from './upgrade-agents-link';
+import type { BunEdit, BunManual } from './upgrade-bun-floor';
+import { editBunSites, floorOf, isBunSite } from './upgrade-bun-floor';
+import { repoScripts, runHopGate, runRepoScripts } from './upgrade-gate';
+import { readManifests, readPins, rewritePins } from './upgrade-pins';
+import { planHop, releaseOf } from './upgrade-plan';
+import { publishedVersions, releaseBunRange } from './upgrade-registry';
+import type { PlannedWrites } from './upgrade-report';
+import { humanLines, NO_WRITES, report, thenLine } from './upgrade-report';
+import { findUpgradeRoot } from './upgrade-root';
+import { elapsedLabel, HEARTBEAT_MS } from './verify-progress';
+import { writeErrorLine } from './write-line';
+
+const readTarget = (ctx: CommandContext): string | undefined => {
+  const to = flagString(ctx.args, 'to');
+  if (to === undefined || releaseOf(to) !== undefined) return to;
+  throw new BadFlagError({
+    flag: 'to',
+    command: 'upgrade',
+    reason: `"${to}" is not an exact release, major.minor.patch`,
+    fix: 'bun pm view @ultimat3/cli versions --json   # then: x upgrade --to <one of them> --json',
+  });
+};
+
+/** The repository's root, or the refusal: git is the only record of where the walk stands. */
+async function requireCleanTree(runner: Runner, root: string): Promise<string> {
+  const top = await runner(['git', 'rev-parse', '--show-toplevel'], { cwd: root });
+  if (!top.ok) {
+    throw new UltimateError({
+      code: 'X_UPGRADE_DIRTY_TREE',
+      cause: `${root} is not a git repository, and a hop has to be one commit you can review or undo`,
+      fix: 'git init && git add -A && git commit -m "before x upgrade"   # then: x upgrade --json',
+    });
+  }
+  const status = await runner(['git', 'status', '--porcelain'], { cwd: root });
+  const changes = status.stdout.split('\n').filter((line) => line.trim().length > 0);
+  if (!status.ok || changes.length > 0) {
+    throw new UltimateError({
+      code: 'X_UPGRADE_DIRTY_TREE',
+      cause: `${String(changes.length)} uncommitted change(s), and a hop has to be one reviewable commit: ${changes.slice(0, 5).join('; ')}`,
+      fix: 'git status --short   # then commit or stash, and re-run: x upgrade --json',
+    });
+  }
+  return top.stdout.trim();
+}
+
+/** Everything the hop would write, decided before any of it is. `--dry-run` stops here. */
+async function planWrites(input: {
+  readonly runner: Runner;
+  readonly root: string;
+  readonly top: string;
+  readonly to: string;
+  readonly floor: string | undefined;
+  readonly manifests: readonly { readonly file: string; readonly text: string }[];
+}): Promise<PlannedWrites> {
+  const { runner, root, top, to, floor, manifests } = input;
+  const files = new Map<string, string>();
+  for (const { file, text } of manifests) {
+    const next = rewritePins(text, to);
+    if (next !== text) files.set(join(root, file), next);
+  }
+  if (floor === undefined) return { files, edited: [], manual: [] };
+
+  const tracked = await runner(['git', 'ls-files'], { cwd: top });
+  const edited: BunEdit[] = [];
+  const manual: BunManual[] = [];
+  for (const path of tracked.stdout.split('\n').filter(isBunSite)) {
+    const absolute = join(top, path);
+    // Tracked and absent is a sparse checkout: a site this tree does not hold is not this run's.
+    if (!files.has(absolute) && !(await Bun.file(absolute).exists())) continue;
+    const source = files.get(absolute) ?? (await Bun.file(absolute).text());
+    // Paths as the app reads them: a report's `path` is one its agent opens from the app root.
+    const shown = posixRelative(root, absolute);
+    const edit = editBunSites(shown, source, floor);
+    edited.push(...edit.edited);
+    manual.push(...edit.manual);
+    if (edit.text !== source) files.set(absolute, edit.text);
+  }
+  return { files, edited, manual };
+}
+
+/** `bun install`, or the refusal carrying the one command that undoes what was just written. */
+async function install(runner: Runner, root: string, to: string): Promise<void> {
+  const result = await runner([process.execPath, 'install'], { cwd: root });
+  if (result.ok) return;
+  throw new UltimateError({
+    code: 'X_UPGRADE_INSTALL_FAILED',
+    cause: `bun install exited ${String(result.code)} after pinning ${to}: ${execOutput(result).slice(-800) || 'no output'}`,
+    fix: 'git restore .   # undoes the pins, since the tree was clean; then fix what the cause names and re-run: x upgrade --json',
+  });
+}
+
+const stageLine = (stage: string): string => JSON.stringify({ upgrade: stage });
+
+/**
+ * Runs `work` with a line on stderr naming the stage every `HEARTBEAT_MS`: the gate's own progress
+ * is captured with the child, so a harness that kills on silence would otherwise kill a healthy hop.
+ */
+async function withHeartbeat<T>(
+  write: (line: string) => void,
+  work: (stageReached: (stage: string) => void) => Promise<T>,
+): Promise<T> {
+  let stage = 'install';
+  let began = performance.now();
+  const timer = setInterval(() => {
+    try {
+      write(
+        msg('cli.upgrade.stillRunning', {
+          stage,
+          elapsed: elapsedLabel(performance.now() - began),
+        }),
+      );
+    } catch {
+      // Stderr closed under the hop: nowhere left to say it, and the verdict still reaches stdout.
+    }
+  }, HEARTBEAT_MS);
+  timer.unref();
+  try {
+    return await work((next) => {
+      stage = next;
+      began = performance.now();
+      write(stageLine(next));
+    });
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+export const createUpgradeCommand = (write: (line: string) => void): CliCommand => ({
+  spec: upgradeSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const { dir: root, app } = await findUpgradeRoot(ctx.cwd);
+    const to = readTarget(ctx);
+    const dryRun = flagBool(ctx.args, 'dry-run');
+    const top = await requireCleanTree(ctx.runner, root);
+    const manifests = await readManifests(root);
+    const pins = readPins(manifests);
+    const versions = await publishedVersions(ctx.runner, root);
+    const hop = planHop({ pins, versions, ...(to === undefined ? {} : { to }) });
+
+    if (hop.atTarget) {
+      const then = thenLine({ hop, dryRun, app, gate: undefined, scripts: [] });
+      const summary =
+        hop.next === null
+          ? msg('cli.upgrade.atLatest', { version: hop.to })
+          : msg('cli.upgrade.atTarget', { version: hop.to, next: hop.next });
+      return ok('upgrade', summary, {
+        data: report({
+          hop,
+          done: true,
+          dryRun,
+          pins,
+          bunFrom: null,
+          bunTo: null,
+          writes: NO_WRITES,
+          app,
+          gate: undefined,
+          scripts: [],
+          then,
+        }),
+        lines: [msg('cli.upgrade.then', { then })],
+      });
+    }
+
+    const bunRange = await releaseBunRange(ctx.runner, root, hop.to);
+    const floor = floorOf(bunRange);
+    // Before any write: the CLI this hop installs refuses this Bun on its first line, so the pins
+    // would land and every later step would report the same `X_BUN_VERSION` as a hop gone red.
+    if (floor !== undefined && !versionAtLeast(ctx.bunVersion, floor)) {
+      throw new BunVersionError({ found: ctx.bunVersion, required: floor });
+    }
+    const writes = await planWrites({
+      runner: ctx.runner,
+      root,
+      top,
+      to: hop.to,
+      floor,
+      manifests,
+    });
+    const held = manifests.find((manifest) => manifest.file === 'package.json')?.text ?? '';
+    const bunFrom = /"engines"\s*:\s*\{[^}]*?"bun"\s*:\s*"([^"]*)"/.exec(held)?.[1] ?? null;
+    const agentsMd = await planAgentsLink(root);
+    const shared = { hop, pins, bunFrom, bunTo: bunRange ?? null, writes, app, agentsMd };
+    const scriptNames = app ? [] : repoScripts(held);
+
+    if (dryRun) {
+      const named = scriptNames.map((name) => ({ name, ok: null }));
+      const then = thenLine({ hop, dryRun: true, app, gate: undefined, scripts: named });
+      return ok('upgrade', msg('cli.upgrade.dryRun', { from: hop.from, to: hop.to }), {
+        data: report({
+          ...shared,
+          done: false,
+          dryRun: true,
+          gate: undefined,
+          scripts: named,
+          then,
+        }),
+        lines: humanLines({ hop, writes, gate: undefined, scripts: named, then, agentsMd }),
+      });
+    }
+
+    await Promise.all(
+      [...writes.files].map(async ([path, text]) => {
+        await Bun.write(path, text);
+      }),
+    );
+    await applyAgentsLink(root, agentsMd);
+    const { gate, scripts } = await withHeartbeat(write, async (stageReached) => {
+      stageReached('install');
+      await install(ctx.runner, root, hop.to);
+      if (!app) {
+        const names = scriptNames;
+        const ran = await runRepoScripts({
+          runner: ctx.runner,
+          root,
+          names,
+          onStage: stageReached,
+        });
+        return { gate: undefined, scripts: ran };
+      }
+      const hopGate = await runHopGate({ runner: ctx.runner, root, onStage: stageReached });
+      return { gate: hopGate, scripts: [] };
+    });
+
+    const redScripts = scripts.filter((script) => script.ok !== true).map((script) => script.name);
+    // With no script, nothing was checked, and that is never a green.
+    const done =
+      gate !== undefined ? gate.verify.ok : scripts.length > 0 && redScripts.length === 0;
+    const then = thenLine({ hop, dryRun: false, app, gate, scripts });
+    const extra = {
+      data: report({ ...shared, done, dryRun: false, gate, scripts, then }),
+      lines: humanLines({ hop, writes, gate, scripts, then, agentsMd }),
+    };
+    const span = { from: hop.from, to: hop.to };
+    if (gate !== undefined) {
+      return done
+        ? ok('upgrade', msg('cli.upgrade.done', span), extra)
+        : failed(
+            'upgrade',
+            msg('cli.upgrade.red', { ...span, summary: gate.verify.summary }),
+            extra,
+          );
+    }
+    if (scripts.length === 0) return failed('upgrade', msg('cli.upgrade.noApp.none', span), extra);
+    return done
+      ? ok('upgrade', msg('cli.upgrade.noApp.done', { ...span, count: scripts.length }), extra)
+      : failed(
+          'upgrade',
+          msg('cli.upgrade.noApp.red', { ...span, names: redScripts.join(', ') }),
+          extra,
+        );
+  },
+});
+
+export const upgradeCommand: CliCommand = createUpgradeCommand(writeErrorLine);

package/src/cmd-verify-spec.ts

@@ -2,7 +2,7 @@
 // read it without loading `cmd-verify.ts`, which `registry.ts` imports only when the command runs.
 
 import type { CommandSpec } from './parse';
-import { WORKER_BYTES, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
+import { BUDGET_RULE, WORKER_BYTES, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 
 /** `run` is the gate (and what a bare `x verify` means); `merge` folds CI parts into its verdict. */
 export const VERIFY_SUBCOMMANDS = ['run', 'merge'] as const;
@@ -24,7 +24,7 @@ export const verifySpec: CommandSpec = {
       name: 'workers',
       type: 'string',
       subcommands: ['run'],
-      summary: `test processes per parallel step (default: one per ${WORKER_BYTES / 2 ** 30} GiB of a min(4 GiB, max(2.75 GiB, 25% of RAM)) budget, at most one per core; ULTIMATE_TEST_MEMORY_BUDGET and ULTIMATE_TEST_MAX_WORKERS override; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      summary: `test processes per parallel step (default: one per ${WORKER_BYTES / 2 ** 30} GiB of a ${BUDGET_RULE} budget, at most one per core; ULTIMATE_TEST_MEMORY_BUDGET and ULTIMATE_TEST_MAX_WORKERS override; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
     },
     {
       name: 'only',
@@ -38,7 +38,7 @@ export const verifySpec: CommandSpec = {
       type: 'string',
       subcommands: ['run'],
       summary:
-        'with --only unit|contract|job: run shard i of an n-way split of each step’s sorted file list (round-robin), for one CI job; `x verify merge` checks all n',
+        'with --only unit|contract|job|live|e2e: run shard i of an n-way split of each step’s sorted file list (round-robin), for one CI job; `x verify merge` checks all n',
     },
     {
       name: 'timings',

package/src/db-backfill.ts

@@ -271,9 +271,15 @@ export async function runBackfills(input: BackfillRunInput): Promise<readonly Ba
   // mapped its rows instead, `--all` would have found zero targets, exited 0 and reported that
   // nothing needed sweeping — the silent success this slice exists to remove, reintroduced by an
   // identity check nobody could see from here.
+  //
+  // A scoped pass's rows are `<name>:<scope>`, and no declaration carries that name: the input its
+  // scope came from is on that run's queue row, so this command cannot enqueue it again — the
+  // retry is `x jobs retry <id>`, which `--pending` names by `last-run-id`. Kept out rather than
+  // reported as `X_BACKFILL_UNKNOWN` about a sweep that exists.
   const targets =
     input.names === 'all'
       ? report.rows
+          .filter((row) => byName.get(row.name)?.scoped === false)
           .filter((row) =>
             input.force ? row.state !== 'excluded' : isPendingBackfillState(row.state),
           )

package/src/db-diagnostics.ts

@@ -0,0 +1,106 @@
+// `x db diagnostics`: opens the app's database the way every role does, asks `@ultimat3/db`'s
+// `dbDiagnostics()` and renders one table per answered section. Facts, never a verdict: exit 0
+// whatever they say, and the one failure is a connection that never opens (`X_DB_UNAVAILABLE`).
+
+import {
+  type DbDiagnostics,
+  type DiagnosticSection,
+  dbDiagnostics,
+} from '@ultimat3/db/diagnostics';
+import type { CommandContext } from './command';
+import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
+import { readIntFlag } from './flag-number';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { resolveServices } from './runtime-bindings';
+import { startDb } from './runtime-queue';
+import { renderTable } from './table';
+
+type Cell = string | number | boolean | null;
+
+/** A row is a flat record of scalars by construction (`db-diagnostics-rows.ts`); read it as one. */
+const cells = (row: object): Readonly<Record<string, Cell>> =>
+  Object.fromEntries(
+    Object.entries(row).map(([key, value]) => [
+      key,
+      typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+        ? value
+        : null,
+    ]),
+  );
+
+/** `--json`'s `data`: the report as `dbDiagnostics` built it, re-typed for the JSON renderer. */
+export function diagnosticsJson(report: DbDiagnostics): JsonValue {
+  return Object.fromEntries(
+    Object.entries(report).map(([name, section]: [string, DiagnosticSection<object>]) => [
+      name,
+      section.available
+        ? { available: true, rows: section.rows.map((row) => ({ ...cells(row) })) }
+        : { available: false, code: section.code, reason: section.reason, fix: section.fix },
+    ]),
+  );
+}
+
+/** One heading and one table per answered section; an unavailable one is its reason and fix. */
+export function renderDiagnostics(report: DbDiagnostics): readonly string[] {
+  return Object.entries(report).flatMap(([name, section]: [string, DiagnosticSection<object>]) => {
+    if (!section.available) {
+      const { code, reason, fix } = section;
+      return [msg('cli.db.diagnostics.unavailable', { section: name, code, reason, fix }), ''];
+    }
+    const rows = section.rows.map(cells);
+    const header = Object.keys(rows[0] ?? {});
+    const table = renderTable(
+      header,
+      rows.map((row) => header.map((key) => String(row[key] ?? ''))),
+    );
+    const body = rows.length === 0 ? [] : table.map((line) => `  ${line}`);
+    return [msg('cli.db.diagnostics.section', { section: name, count: rows.length }), ...body, ''];
+  });
+}
+
+/**
+ * `startDb`, not `startQueue`: the queue's boot applies the framework tables, and a diagnostic
+ * must write nothing. An embedded database `x dev` holds is refused rather than opened twice:
+ * PGlite's data directory has one writer.
+ */
+export async function runDiagnostics(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const limit = readIntFlag(ctx.args, {
+    name: 'limit',
+    command: 'db diagnostics',
+    min: 1,
+    max: 1_000,
+    example: 'x db diagnostics --limit 20 --json',
+  });
+  const services = resolveServices(root, ctx.env);
+  if (services.db.mode === 'embedded') {
+    // Check-then-open, as `x db reset` does: an `x dev` starting between this read and `startDb`
+    // below is not seen. Narrow, and the same window every embedded `x db` subcommand has.
+    const holder = liveDevLock(services.stateDir);
+    if (holder !== undefined) {
+      throw new DevAlreadyRunningError({
+        lock: holder,
+        stateDir: services.stateDir,
+        embeddedDb: true,
+      });
+    }
+  }
+  const started = startDb(services, ctx.env);
+  try {
+    const report = await dbDiagnostics({ client: started.client, limit });
+    const sections = Object.values(report);
+    return {
+      ok: true,
+      command: 'db',
+      summary: msg('cli.db.diagnostics.done', {
+        available: sections.filter((section) => section.available).length,
+        total: sections.length,
+      }),
+      lines: renderDiagnostics(report),
+      data: diagnosticsJson(report),
+    };
+  } finally {
+    await started.client.close();
+    await started.replica?.close();
+  }
+}

package/src/db-generate.ts

@@ -10,6 +10,7 @@ import {
   declaredSchema,
   generateMigration,
   migrationSnapshotMissing,
+  ROLLING_UNSAFE_MARKER,
   snapshotJson,
 } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
@@ -19,11 +20,16 @@ import { replicaIdentityTables } from './db-subscribes';
 import { reconcileSchemaHash, writeSchemaHash } from './drift';
 import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
 import type { Finding } from './output';
+import { appRowSecurity, type RowSecurityWanted } from './row-security-wanted';
 
 export interface GenerateMigrationOptions {
   readonly name: string;
   /** `x db gen "…" --allow-destructive`. A DROP whose `down` cannot restore the rows. */
   readonly allowDestructive?: boolean | undefined;
+  /** `x db gen "…" --rolling-unsafe`. A drop never retired, for an app that stops before it starts. */
+  readonly rollingUnsafe?: boolean | undefined;
+  /** `database.rowSecurity` and the tenant columns. The app's own unless a test injects one. */
+  readonly rowSecurity?: RowSecurityWanted | undefined;
 }
 
 /**
@@ -68,6 +74,7 @@ export function migrationSql(migration: GeneratedMigration): string {
     "-- GENERATED by `x db gen` from the app's entities — do not edit.",
     '-- Editing an applied migration changes its checksum: X_MIGRATION_CONFLICT on the next apply.',
     ...(migration.destructive ? [DESTRUCTIVE_MARKER] : []),
+    ...(migration.rollingUnsafe === true ? [ROLLING_UNSAFE_MARKER] : []),
     '',
     migration.up,
     '',
@@ -124,7 +131,9 @@ export async function generateAppMigration(
     current,
     name: options.name,
     replicaIdentityFull,
+    rowSecurity: await (options.rowSecurity ?? appRowSecurity)(root),
     ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
+    ...(options.rollingUnsafe === true ? { rollingUnsafe: true } : {}),
   });
   // An empty diff writes no MIGRATION — one with no statement still takes a ledger row, a checksum
   // and a place in the apply order, a permanent record that nothing changed. It re-records the

package/src/db-reset-template.ts

@@ -4,7 +4,7 @@
 
 // The migrate that follows still runs and finds every migration in the ledger — so a template
 // that is missing something is completed by it, never trusted over it. Measured on
-// bank-integrations (33 migrations, a loaded 12-core box, 3 runs each): `x db reset` 8.7 s → 7.5 s.
+// one adopter's app (33 migrations, a loaded 12-core box, 3 runs each): `x db reset` 8.7 s → 7.5 s.
 // What is left is the CLI's boot, the migrator's no-op pass and the schema dump's own replay (~3 s,
 // `db-schema-refresh.ts`). The e2e step's app boots through exactly this reset, once per gate.
 

package/src/db-rolling.ts

@@ -0,0 +1,45 @@
+// The rolling-deploy rail at the gate: an `up` old pods would trip over must have retired first, or
+// say it stops before it starts. Files, not the database, so it fires in CI. `@ultimat3/db` owns the
+// classifier and the markers; this file owns the walk and the bound an app sets in `x.verify.json`.
+
+import {
+  hasRollingUnsafeMarker,
+  migrationRollingUnsafe,
+  retiredColumnsIn,
+  rollingUnsafeStatements,
+  unretiredColumnsIn,
+} from '@ultimat3/db';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
+import { type Finding, findingFrom } from './output';
+import { readVerifyFloor } from './verify-floor';
+
+/**
+ * Unset is silent and that is the promise: an applied migration cannot gain a marker (checksum), so
+ * an existing app could only ever clear this by rewriting history. `x doctor` reminds it instead.
+ *
+ * Every migration is walked for its retires, the bounded ones too: a retire shipped before the bound
+ * still earns the drop after it, and one taken back earns nothing. One finding per migration, as
+ * `checkDestructiveMigrations`.
+ */
+export async function checkRollingMigrations(root: string): Promise<readonly Finding[]> {
+  const since = (await readVerifyFloor(root))?.rollingSince;
+  if (since === undefined) return [];
+  const findings: Finding[] = [];
+  const retired = new Set<string>();
+  for (const migration of await readMigrations(root)) {
+    if (migration.id > since && !hasRollingUnsafeMarker(migration.up)) {
+      const [first, ...rest] = rollingUnsafeStatements(migration.up, retired);
+      if (first !== undefined) {
+        const file = `${MIGRATIONS_DIR}/${migration.id}.sql`;
+        findings.push({
+          ...findingFrom(migrationRollingUnsafe(file, first, rest.length)),
+          at: file,
+        });
+      }
+    }
+    // After the judging: a retire in the same file lands in the same deploy, so it is not earlier.
+    for (const key of retiredColumnsIn(migration.up)) retired.add(key);
+    for (const key of unretiredColumnsIn(migration.up)) retired.delete(key);
+  }
+  return findings;
+}