@ultimat3/cli 1.2.0 → 3.0.0

package/src/db-destructive.ts

@@ -0,0 +1,29 @@
+// The destructive-SQL rail at the gate: an `up` that drops, truncates or retypes must declare it.
+// Files, not the database, so the rail fires in CI rather than first in a release phase.
+// `@ultimat3/db` owns the classifier `x db gen` wrote the marker from — the generator and the gate
+// cannot disagree about one file.
+
+import { destructiveStatements, hasDestructiveMarker, migrationDestructive } from '@ultimat3/db';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
+import { type Finding, findingFrom } from './output';
+
+/**
+ * One finding per migration, never one per statement: the marker declares the whole file, so a
+ * second finding would repeat the instruction the first already gave. The count still rides along
+ * in `cause`, because "and 3 more" is the difference between a typo and a rewrite.
+ *
+ * `readMigrations` is the reader `x db migrate` applies from, and only its `up` half is judged —
+ * a rail checking a list the migrator does not run, or SQL the migrator never sends, enforces
+ * nothing. An app with no migrations directory has nothing to declare and reports nothing.
+ */
+export async function checkDestructiveMigrations(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for (const migration of await readMigrations(root)) {
+    if (hasDestructiveMarker(migration.up)) continue;
+    const [first, ...rest] = destructiveStatements(migration.up);
+    if (first === undefined) continue;
+    const file = `${MIGRATIONS_DIR}/${migration.id}.sql`;
+    findings.push({ ...findingFrom(migrationDestructive(file, first, rest.length)), at: file });
+  }
+  return findings;
+}

package/src/db-finding.ts

@@ -0,0 +1,28 @@
+// One rule for turning a thrown value into a `Finding` on the `x db` path, shared by every
+// subcommand: a framework error reaches the caller verbatim, and anything else is named by the
+// step that failed. Its own module because `cmd-db.ts` and `cmd-db-branch.ts` both need it and
+// neither may import the other.
+
+import { renderThrowable } from '@ultimat3/core';
+import type { Finding } from './output';
+import { findingFrom, isUltimateErrorShape } from './output';
+
+/**
+ * The engine names its own failures — `X_MIGRATION_CONFLICT` carries the ledger row that disagrees,
+ * `X_MIGRATION_IRREVERSIBLE` carries the exact `--allow-destructive` line to rerun, and
+ * `X_BRANCH_EXISTS` carries the `x db branch drop` that clears it — so those reach the caller
+ * verbatim. `X_DB_GEN_FAILED` / `X_DB_MIGRATE_FAILED` / `X_DB_BRANCH_FAILED` are what is left: the
+ * step failed for a reason no framework error claimed, and the raw message is all there is.
+ */
+export const stepFinding = (error: unknown, code: string): Finding =>
+  isUltimateErrorShape(error)
+    ? findingFrom(error)
+    : {
+        code,
+        // The engine may throw a non-Error, and an Error whose `message` is a getter: core's
+        // `renderThrowable` reads both without trusting either, so the refusal cannot be lost to
+        // a TypeError raised while reporting it.
+        cause: renderThrowable(error),
+        fix: 'x doctor --json',
+        docs: `https://ultimate.dev/errors/${code}`,
+      };

package/src/db-generate.ts

@@ -0,0 +1,144 @@
+// `x db gen`, on the framework's own engine. The app's registered entities diffed against what the
+// migration files already declare, written as one reversible `.sql` plus the two sidecars the gate
+// reads back — the snapshot the next generation diffs against, and the schema hash `drift` checks.
+
+// `node:path` — Bun ships no path joiner of its own, and these paths are built, not opened.
+import { join } from 'node:path';
+import type { GeneratedMigration } from '@ultimat3/db';
+import {
+  DESTRUCTIVE_MARKER,
+  declaredSchema,
+  generateMigration,
+  migrationSnapshotMissing,
+  snapshotJson,
+} from '@ultimat3/db';
+import { describeEntities } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+import { reconcileSchemaHash, writeSchemaHash } from './drift';
+import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
+import type { Finding } from './output';
+
+export interface GenerateMigrationOptions {
+  readonly name: string;
+  /** `x db gen "…" --allow-destructive`. A DROP whose `down` cannot restore the rows. */
+  readonly allowDestructive?: boolean | undefined;
+}
+
+/**
+ * What this run actually did — four different things, and `--json` has to tell them apart. A
+ * `hash-recorded` run wrote a file and generated no migration; reporting it as `generated` would
+ * claim a migration nobody can apply, and reporting it as `unchanged` would hide the one write.
+ */
+export type GenerateOutcome = 'generated' | 'hash-recorded' | 'unchanged' | 'blocked';
+
+export interface GeneratedFiles {
+  readonly outcome: GenerateOutcome;
+  /** Absent unless `outcome` is `generated` — the other three write no migration. */
+  readonly migration?: GeneratedMigration | undefined;
+  /** App-root-relative paths written, in write order. Empty when there was nothing to write. */
+  readonly files: readonly string[];
+  /** What the source hashes to, whenever this run was in a position to record it. */
+  readonly schemaHash?: string | undefined;
+  /** Modules that would not load. Non-empty means nothing was generated. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * The header every generated migration carries. It names the id rather than interpolating the
+ * caller's own message: a `name` is free text from argv, and a newline in it would end the comment
+ * and turn prose into SQL.
+ *
+ * A destructive `up` carries the marker `x verify` demands, written here rather than hand-added
+ * later: the marker is part of the SQL the checksum covers, so a migration that earns it after it
+ * has been applied is an edited migration and `X_MIGRATION_CONFLICT` — correctly — says so.
+ */
+export function migrationSql(migration: GeneratedMigration): string {
+  return [
+    `-- ${migration.id}`,
+    "-- 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.up,
+    '',
+    '-- down',
+    migration.down,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generation reads source and writes files; it never opens a database. The previous migration's
+ * snapshot is what it diffs against (`declaredSchema`), so `x db gen` answers the same in CI, on a
+ * laptop with no Postgres running, and against a database three migrations behind.
+ *
+ * An app that would not load generates nothing. `describeEntities()` is the registry a failed
+ * import leaves short, and a diff against a short registry is a migration that drops the tables
+ * whose module happened to throw — the one destructive edit no `--allow-destructive` was asked for.
+ */
+export async function generateAppMigration(
+  root: string,
+  options: GenerateMigrationOptions,
+): Promise<GeneratedFiles> {
+  const app = await loadApp(root);
+  if (app.findings.length > 0) return { outcome: 'blocked', files: [], findings: app.findings };
+
+  const migrations = await readMigrations(root);
+  const current = declaredSchema(migrations);
+  // Refused, never defaulted to the empty schema: with nothing to diff against, every table the
+  // database already holds looks new and the generated `up` is `create table` for all of them.
+  if (current === undefined) {
+    const newest = migrations[migrations.length - 1];
+    const id = newest?.id ?? '';
+    throw migrationSnapshotMissing(id, join(MIGRATIONS_DIR, snapshotFileName(id)));
+  }
+
+  const migration = generateMigration({
+    entities: describeEntities(),
+    current,
+    name: options.name,
+    ...(options.allowDestructive === true ? { allowDestructive: 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
+  // sidecar instead, and that is what makes `X_DB_DRIFT`'s `fix:` a real instruction: the hash
+  // covers every non-test file under `packages/db/src`, so editing a seed or a helper moves it with
+  // no DDL behind it, and the command the error names used to write nothing at all.
+  //
+  // Nothing is masked, because of what has already been proved above: `loadApp` reported no
+  // findings, so the registry is whole rather than short; `declaredSchema` returned a real snapshot
+  // rather than `undefined`, so the diff had something to run against; and the emptiness is the
+  // generator's OWN verdict — the same call, the same classifier — as the written path. A DDL
+  // change that reaches here is a `generateMigration` that missed it, and the sidecar was never the
+  // thing that caught that: an author following the fix simply stayed red with nothing left to run.
+  if (migration.up.trim().length === 0) {
+    const newest = migrations[migrations.length - 1];
+    // No migration to record against, which in this branch means no entity is declared either —
+    // a registry against zero migrations is `create table` for all of it, never an empty diff.
+    if (newest === undefined) return { outcome: 'unchanged', files: [], findings: [] };
+    const reconciled = await reconcileSchemaHash(root, newest.id);
+    return {
+      outcome: reconciled.written ? 'hash-recorded' : 'unchanged',
+      schemaHash: reconciled.hash,
+      files: reconciled.written ? [`${MIGRATIONS_DIR}/${hashFileName(newest.id)}`] : [],
+      findings: [],
+    };
+  }
+
+  const dir = join(root, MIGRATIONS_DIR);
+  const sql = `${migration.id}.sql`;
+  const snapshot = snapshotFileName(migration.id);
+  await Bun.write(join(dir, sql), migrationSql(migration));
+  // `snapshotJson`, never `JSON.stringify`: the sidecar is the one migration artefact a scaffolded
+  // app's `biome check .` reads, and its bytes carry their own trailing newline.
+  await Bun.write(join(dir, snapshot), snapshotJson(migration.snapshot));
+  const schemaHash = await writeSchemaHash(root, migration.id);
+
+  return {
+    outcome: 'generated',
+    migration,
+    schemaHash,
+    files: [sql, snapshot, hashFileName(migration.id)].map((file) => `${MIGRATIONS_DIR}/${file}`),
+    findings: [],
+  };
+}

package/src/db-seed.ts

@@ -0,0 +1,294 @@
+// `x db seed`, everything except the argv: where a seed is declared, which tier this environment
+// takes, and what one pass reports. A driver plus plain strings in, plain rows out — the
+// `db-backfill.ts` split repeated, so every rule here is testable with no `ParsedArgs` and no boot.
+//
+// The decisions a seed itself owns are `@ultimat3/entity`'s: `seedTiersFor` is the one table saying
+// which tiers an environment runs, and two copies of "may this seed run" would be two answers.
+
+// `node:path` for the joiner and the app-root-relative spelling every finding is keyed by; Bun
+// exposes neither.
+import { relative, sep } from 'node:path';
+import type { Environment } from '@ultimat3/core';
+import { UltimateError } from '@ultimat3/core';
+import type { Driver, Seed, SeedTier } from '@ultimat3/entity';
+import { isSeed, SEED_TIERS, seedTiersFor } from '@ultimat3/entity';
+import { docsFor } from './error-codes';
+import { BadFlagError } from './errors';
+import type { Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+import { renderTable } from './table';
+
+/**
+ * Where an app keeps seeds: a `seeds` directory in a package, or a `seed*.ts` beside its entities —
+ * the two layouts the tracked apps already use, and nothing wider. `loadApp`'s whole-src glob was
+ * the alternative and it is the wrong tool here: importing every module of every package to find a
+ * fixture graph makes an unrelated module that will not import into a failed seed run.
+ * `apps/` is deliberately absent: a fixture graph is data, and data lives in a package.
+ */
+export const SEED_GLOBS = ['packages/*/seeds/**/*.ts', 'packages/*/src/seed*.ts'] as const;
+
+/**
+ * `x db seed <name>` named a seed no module declared. `X_DECLARATION_UNKNOWN` is the code the
+ * registries already answer this with — a seed is a declaration, and a second code for "no such
+ * name" is the synonym the registry exists to prevent. The known names ARE listed, unlike
+ * `DeclarationUnknownError`'s count: an app has one to five seeds, not two hundred actions, and
+ * picking another one is the entire remedy.
+ *
+ * Both classes live HERE rather than in `errors.ts` for one reason, stated so nobody has to guess:
+ * that file is at the 500-line ceiling `x verify`'s `filesize` step enforces, and these two are
+ * `x db seed`'s alone. The codes stay CLI-owned in `error-codes.ts`, as every code does.
+ */
+export class SeedUnknownError extends UltimateError {
+  constructor(input: { name: string; known: readonly string[] }) {
+    super({
+      code: 'X_DECLARATION_UNKNOWN',
+      cause:
+        input.known.length === 0
+          ? `no seed named "${input.name}" — this app declares none (a seed is an exported defineSeed() in packages/<pkg>/seeds or packages/<pkg>/src/seed.ts)`
+          : `no seed named "${input.name}" is declared (known: ${input.known.join(', ')})`,
+      // A dry run, never a bare `x db seed`: the command that answers "which seeds are there" must
+      // not be the command that writes them.
+      fix: 'x db seed --dry-run --json',
+      docs: docsFor('X_DECLARATION_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * The seed's tier is not one this environment runs. `dev` fixtures reaching production is the one
+ * irreversible mistake `x db seed` can make, so it is refused rather than confirmed.
+ *
+ * `X_SEED_ENVIRONMENT` is its own code, not `X_CLI_BAD_FLAG`: the argv was well formed and the
+ * answer is still no. A flag code says "you typed it wrong" and sends the reader to `x help`; this
+ * says "this environment does not run that tier", whose one remedy is naming the tier. The env var
+ * is named in the cause and not in the `fix:`, because a `fix:` is one pasteable line and a
+ * container with a fixed command line is the case that needs the other half.
+ */
+export class SeedEnvironmentError extends UltimateError {
+  constructor(input: {
+    seed: string;
+    tier: string;
+    environment: string;
+    tiers: readonly string[];
+  }) {
+    super({
+      code: 'X_SEED_ENVIRONMENT',
+      cause: `seed "${input.seed}" is tier ${input.tier} and ULTIMATE_ENV resolved ${input.environment}, where x db seed runs ${input.tiers.join(', ')} — ULTIMATE_SEED_TIER=${input.tier} says this deploy takes it anyway`,
+      fix: `x db seed ${input.seed} --tier ${input.tier} --json`,
+      docs: docsFor('X_SEED_ENVIRONMENT'),
+    });
+  }
+}
+
+export interface DiscoveredSeed {
+  readonly seed: Seed;
+  /** App-root-relative POSIX path of the module that declared it. */
+  readonly file: string;
+}
+
+export interface SeedDiscovery {
+  readonly seeds: readonly DiscoveredSeed[];
+  /** Modules that would not import. Reported, never swallowed: one of them may hold the seed. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * Every seed the app declares, by importing the modules that declare them — the same rule
+ * `loadApp` follows, because importing IS the declaration. Sorted by file, so a run's order is the
+ * one a reader can predict from the tree (`01_orgs.ts` before `02_posts.ts`) rather than the one a
+ * glob happened to yield.
+ */
+export async function discoverSeeds(root: string): Promise<SeedDiscovery> {
+  const seeds: DiscoveredSeed[] = [];
+  const findings: Finding[] = [];
+  const seen = new Set<string>();
+  for (const pattern of SEED_GLOBS) {
+    for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
+      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      if (seen.has(absolute)) continue;
+      seen.add(absolute);
+      const file = relative(root, absolute).split(sep).join('/');
+      let module: Record<string, unknown>;
+      try {
+        module = (await import(absolute)) as Record<string, unknown>;
+      } catch (error) {
+        findings.push({ ...findingFrom(error), at: file });
+        continue;
+      }
+      for (const value of Object.values(module)) {
+        if (isSeed(value)) seeds.push({ seed: value, file });
+      }
+    }
+  }
+  return {
+    seeds: seeds.toSorted((left, right) => left.file.localeCompare(right.file)),
+    findings,
+  };
+}
+
+/** `--tier`, or `ULTIMATE_SEED_TIER` for a container whose command line is fixed. */
+export function parseSeedTierFlag(value: string | undefined): SeedTier | undefined {
+  if (value === undefined || value === '') return undefined;
+  if ((SEED_TIERS as readonly string[]).includes(value)) return value as SeedTier;
+  throw new BadFlagError({
+    flag: 'tier',
+    command: 'db seed',
+    reason: `unknown tier "${value}" (known: ${SEED_TIERS.join(', ')})`,
+    fix: 'x db seed --dry-run --json',
+  });
+}
+
+export interface SeedSelection {
+  readonly discovered: readonly DiscoveredSeed[];
+  /** The positional. Absent runs every seed whose tier this environment takes. */
+  readonly name?: string | undefined;
+  readonly environment: Environment;
+  readonly requested?: SeedTier | undefined;
+}
+
+/**
+ * Which seeds this invocation runs, and the two refusals that are not a run.
+ *
+ * The environment check is HERE and again in `cmd-db.ts` before the driver is booted, on purpose:
+ * seeding is the one irreversible thing this command does, and the layer that boots a connection
+ * to production must not be the only layer that decided it was allowed to.
+ */
+export function selectSeeds(input: SeedSelection): readonly DiscoveredSeed[] {
+  const tiers = seedTiersFor(input.environment, input.requested);
+  const known = input.discovered.map((entry) => entry.seed.name);
+  if (input.name === undefined) {
+    return input.discovered.filter((entry) => tiers.includes(entry.seed.tier));
+  }
+  const chosen = input.discovered.filter((entry) => entry.seed.name === input.name);
+  const first = chosen[0];
+  if (first === undefined) throw new SeedUnknownError({ name: input.name, known });
+  if (chosen.length > 1) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'db seed',
+      reason: `"${input.name}" names ${chosen.length} seeds (${chosen.map((entry) => entry.file).join(', ')}) — a seed name is how a run is asked for, so two of them make the ask unanswerable`,
+      fix: 'x db seed --dry-run --json',
+    });
+  }
+  if (!tiers.includes(first.seed.tier)) {
+    throw new SeedEnvironmentError({
+      seed: first.seed.name,
+      tier: first.seed.tier,
+      environment: input.environment,
+      tiers,
+    });
+  }
+  return chosen;
+}
+
+export type SeedStatus = 'ok' | 'failed';
+
+export interface SeedPassRow {
+  readonly file: string;
+  readonly name: string;
+  readonly tier: SeedTier;
+  readonly status: SeedStatus;
+  readonly ms: number;
+  readonly inserted: number;
+  readonly updated: number;
+  readonly skipped: number;
+  readonly finding: Finding | null;
+}
+
+export interface SeedPassOptions {
+  readonly seeds: readonly DiscoveredSeed[];
+  readonly driver: Driver;
+  readonly dryRun: boolean;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /**
+   * One transaction PER SEED, never one around the run: a seed that fails must not roll back the
+   * ones that already succeeded, and a fixture graph half-written is worse than one not written.
+   * Injected so this stays testable with no database; `cmd-db.ts` passes `withTransaction`.
+   */
+  readonly transaction: <T>(work: () => Promise<T>) => Promise<T>;
+}
+
+/** Each seed, in file order, each isolated from the next. Never throws — a failure is a row. */
+export async function runSeeds(options: SeedPassOptions): Promise<readonly SeedPassRow[]> {
+  const rows: SeedPassRow[] = [];
+  for (const entry of options.seeds) {
+    const started = Bun.nanoseconds();
+    const elapsed = (): number => Math.round((Bun.nanoseconds() - started) / 1_000_000);
+    try {
+      const run = await options.transaction(() =>
+        entry.seed.run({ driver: options.driver, dryRun: options.dryRun, env: options.env }),
+      );
+      rows.push({
+        file: entry.file,
+        name: run.name,
+        tier: run.tier,
+        status: 'ok',
+        ms: elapsed(),
+        ...run.metrics,
+        finding: null,
+      });
+    } catch (error) {
+      rows.push({
+        file: entry.file,
+        name: entry.seed.name,
+        tier: entry.seed.tier,
+        status: 'failed',
+        ms: elapsed(),
+        inserted: 0,
+        updated: 0,
+        skipped: 0,
+        finding: { ...findingFrom(error), at: entry.file },
+      });
+    }
+  }
+  return rows;
+}
+
+export interface SeedTotals {
+  readonly inserted: number;
+  readonly updated: number;
+  readonly skipped: number;
+  readonly failed: number;
+}
+
+export const seedTotals = (rows: readonly SeedPassRow[]): SeedTotals => ({
+  inserted: rows.reduce((sum, row) => sum + row.inserted, 0),
+  updated: rows.reduce((sum, row) => sum + row.updated, 0),
+  skipped: rows.reduce((sum, row) => sum + row.skipped, 0),
+  failed: rows.filter((row) => row.status === 'failed').length,
+});
+
+/**
+ * Slowest first, in both renderers: a seed run that got slow is diagnosed by which FILE took the
+ * time, and a list in run order buries that under whatever happens to be alphabetically first.
+ */
+const slowestFirst = (rows: readonly SeedPassRow[]): readonly SeedPassRow[] =>
+  rows.toSorted((left, right) => right.ms - left.ms);
+
+export const seedPassToJson = (rows: readonly SeedPassRow[]): JsonValue => ({
+  seeds: slowestFirst(rows).map((row) => ({
+    file: row.file,
+    name: row.name,
+    tier: row.tier,
+    status: row.status,
+    ms: row.ms,
+    inserted: row.inserted,
+    updated: row.updated,
+    skipped: row.skipped,
+  })),
+  totals: { ...seedTotals(rows) },
+});
+
+export const renderSeedTable = (rows: readonly SeedPassRow[]): readonly string[] =>
+  renderTable(
+    ['seed', 'tier', 'status', 'ms', 'inserted', 'updated', 'skipped'],
+    slowestFirst(rows).map((row) => [
+      row.name,
+      row.tier,
+      row.status,
+      String(row.ms),
+      String(row.inserted),
+      String(row.updated),
+      String(row.skipped),
+    ]),
+  );

package/src/db-snapshot.ts

@@ -0,0 +1,24 @@
+// `x db gen`'s own precondition, asked as a diagnostic rather than met as a throw: a newest
+// migration with no `.snapshot.json` leaves the next generation nothing to diff against, so it
+// refuses before writing anything. `@ultimat3/db` owns both the condition (`declaredSchema`) and
+// the wording, so this check and that refusal cannot disagree about one directory.
+
+import { declaredSchema, migrationSnapshotMissing } from '@ultimat3/db';
+import { MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
+import { type Finding, findingFrom } from './output';
+
+/**
+ * Empty result = the next `x db gen` has something to start from. An app with no migrations at all
+ * reports nothing: `declaredSchema([])` is the empty schema, which is a real answer and the state a
+ * freshly scaffolded app is in before its first generation.
+ *
+ * One finding, never one per file. Only the NEWEST snapshot is what a diff starts from, so an older
+ * migration missing one is a fact about history and not something the author can act on.
+ */
+export async function checkMigrationSnapshots(root: string): Promise<readonly Finding[]> {
+  const migrations = await readMigrations(root);
+  if (declaredSchema(migrations) !== undefined) return [];
+  const id = migrations[migrations.length - 1]?.id ?? '';
+  const file = `${MIGRATIONS_DIR}/${snapshotFileName(id)}`;
+  return [{ ...findingFrom(migrationSnapshotMissing(id, file)), at: file }];
+}