@ultimat3/cli 6.0.0 → 8.0.0

package/src/cmd-ci.ts

@@ -0,0 +1,273 @@
+// `x ci` — one command instead of three. `gh run view` prints a tree of ticks and one cross, and
+// the error is inside a per-job log that is mostly setup noise; for a `verify` job that log tail IS
+// the findings block, with its `X_*` codes and executable `fix:` lines already in it. So this
+// command fetches the runs, opens only the failed steps' log, and hands back the findings the gate
+// already wrote — in the same three-line shape every other Ultimate error is printed in.
+
+import { UltimateError } from '@ultimat3/core';
+import type { CiLogLine } from './ci-log';
+import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
+import type { CiJob, CiRun } from './ci-runs';
+import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
+import type { CliCommand, CommandContext } from './command';
+import { parseIntFlag } from './flag-number';
+import type { GhRepo } from './gh-target';
+import { currentBranch, resolveRepo } from './gh-target';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { flagBool, flagString } from './parse';
+
+/**
+ * Every catalog key this command renders, declared — `msg()` answers `⟦key⟧` for a key nobody
+ * added, which is loud in a terminal and SILENT to a build. `cmd-ci.test.ts` holds this list
+ * against the catalog, so a missing string is a failing test rather than a rendered artefact.
+ */
+export const CI_MESSAGE_KEYS = [
+  'cli.ci.failed',
+  'cli.ci.green',
+  'cli.ci.running',
+  'cli.ci.run',
+  'cli.ci.job',
+  'cli.ci.jobs.other',
+  'cli.ci.tail',
+  'cli.ci.pending',
+  'cli.ci.logs.empty',
+] as const;
+
+/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
+export const TAIL_LINES = 40;
+
+/** How far back a branch's run history is read before "the latest run of each workflow". */
+export const RUN_LOOKBACK = 20;
+
+/** No run to triage. The remedy is a branch that has one, or the id of the run in question. */
+export class CiRunNotFoundError extends UltimateError {
+  constructor(input: { branch: string; repo: string }) {
+    super({
+      code: 'X_CI_RUN_NOT_FOUND',
+      cause: `no workflow run on ${input.repo} for branch "${input.branch}"`,
+      fix: `x ci --branch main --repo ${input.repo} --json`,
+    });
+  }
+}
+
+const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 32484583944 --json' };
+const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
+
+export const ciCommand: CliCommand = {
+  spec: {
+    name: 'ci',
+    summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
+    usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+    flags: [
+      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+      { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
+      { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
+      {
+        name: 'tail',
+        type: 'string',
+        summary: `log lines kept per failed job (default ${TAIL_LINES})`,
+      },
+      { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
+    const rawRun = flagString(ctx.args, 'run');
+    const rawTail = flagString(ctx.args, 'tail');
+    const limit = flagBool(ctx.args, 'full')
+      ? Number.POSITIVE_INFINITY
+      : rawTail === undefined
+        ? TAIL_LINES
+        : parseIntFlag(rawTail, TAIL_FLAG);
+    if (rawRun !== undefined) {
+      const viewed = await viewRun(ctx, repo, parseIntFlag(rawRun, RUN_FLAG));
+      return report(repo, viewed.run.branch, [await inspect(ctx, repo, viewed, limit)]);
+    }
+    const branch = flagString(ctx.args, 'branch') ?? (await currentBranch(ctx));
+    const runs = latestPerWorkflow(await listRuns(ctx, repo, branch, RUN_LOOKBACK));
+    if (runs.length === 0) throw new CiRunNotFoundError({ branch, repo: repo.slug });
+    const inspected: RunReport[] = [];
+    for (const run of runs) {
+      // Only a failed run is opened. A green run's jobs are 35 rows saying `success`, and fetching
+      // them would turn the fast answer ("CI is green") into the slow one.
+      inspected.push(
+        isFailed(run) ? await inspect(ctx, repo, await viewRun(ctx, repo, run.id), limit) : { run },
+      );
+    }
+    return report(repo, branch, inspected);
+  },
+};
+
+interface JobFailure {
+  readonly job: string;
+  readonly conclusion: string;
+  readonly url: string;
+  readonly failedSteps: readonly string[];
+  readonly tail: readonly string[];
+}
+
+interface RunReport {
+  readonly run: CiRun;
+  readonly jobs?: readonly CiJob[];
+  readonly failures?: readonly JobFailure[];
+  readonly findings?: readonly Finding[];
+}
+
+const stepFailed = (conclusion: string | null): boolean =>
+  conclusion !== null && conclusion !== 'success' && conclusion !== 'skipped';
+
+/**
+ * One failed run, opened. The findings are attributed to the job whose lines produced them, and
+ * a job the log attributes nothing to falls back to the whole log — a format change on GitHub's
+ * side must cost the attribution, never the finding.
+ */
+async function inspect(
+  ctx: CommandContext,
+  repo: GhRepo,
+  viewed: { readonly run: CiRun; readonly jobs: readonly CiJob[] },
+  limit: number,
+): Promise<RunReport> {
+  const { run, jobs } = viewed;
+  if (!isFailed(run)) return { run, jobs };
+  const lines = parseLogLines(await failedLog(ctx, repo, run.id));
+  const failed = jobs.filter((job) => stepFailed(job.conclusion));
+  // A run can fail with no failed JOB — a startup failure, a cancelled matrix — and the log is
+  // then the only thing that knows which name to file it under.
+  const names = failed.length > 0 ? failed.map((job) => job.name) : jobsInLog(lines);
+  const failures: JobFailure[] = [];
+  const findings: Finding[] = [];
+  for (const name of names) {
+    const own = lines.filter((line) => line.job === name);
+    const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
+    const job = failed.find((candidate) => candidate.name === name);
+    for (const finding of findingsFrom(pool)) {
+      findings.push(finding.at === undefined ? { ...finding, at: name } : finding);
+    }
+    failures.push({
+      job: name,
+      conclusion: job?.conclusion ?? conclusionOf(run),
+      url: job?.url ?? run.url,
+      failedSteps: (job?.steps ?? [])
+        .filter((step) => stepFailed(step.conclusion))
+        .map((step) => step.name),
+      tail: tailOf(lines, name, limit),
+    });
+  }
+  return { run, jobs, failures, findings: dedupe(findings) };
+}
+
+/**
+ * The same block can be reached twice — once per job when the log attributes nothing, once per
+ * attempt when a run was re-run — and two copies of one finding read as two problems.
+ */
+function dedupe(findings: readonly Finding[]): readonly Finding[] {
+  const seen = new Set<string>();
+  return findings.filter((finding) => {
+    const key = `${finding.code} ${finding.cause}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+const conclusionOf = (run: CiRun): string => run.conclusion ?? msg('cli.ci.pending');
+
+function report(repo: GhRepo, branch: string, reports: readonly RunReport[]): CommandResult {
+  const failed = reports.filter((entry) => isFailed(entry.run));
+  const running = reports.filter((entry) => isRunning(entry.run));
+  const findings = dedupe(reports.flatMap((entry) => entry.findings ?? []));
+  return {
+    ok: failed.length === 0,
+    command: 'ci',
+    summary:
+      failed.length > 0
+        ? msg('cli.ci.failed', {
+            failed: failed.length,
+            runs: reports.length,
+            branch,
+            findings: findings.length,
+          })
+        : running.length > 0
+          ? msg('cli.ci.running', { running: running.length, runs: reports.length, branch })
+          : msg('cli.ci.green', { runs: reports.length, branch }),
+    findings,
+    lines: reports.flatMap(runLines),
+    data: {
+      repo: repo.slug,
+      branch,
+      counts: {
+        runs: reports.length,
+        failed: failed.length,
+        running: running.length,
+        findings: findings.length,
+      },
+      runs: reports.map(runJson),
+    },
+  };
+}
+
+function runLines(entry: RunReport): readonly string[] {
+  const out = [
+    msg('cli.ci.run', {
+      conclusion: conclusionOf(entry.run),
+      workflow: entry.run.workflow,
+      url: entry.run.url,
+    }),
+  ];
+  const failures = entry.failures ?? [];
+  for (const failure of failures) {
+    out.push(
+      msg('cli.ci.job', {
+        conclusion: failure.conclusion,
+        job: failure.job,
+        steps: failure.failedSteps.join(', '),
+      }),
+    );
+    if (failure.tail.length === 0) {
+      out.push(msg('cli.ci.logs.empty', { url: failure.url }));
+      continue;
+    }
+    out.push(msg('cli.ci.tail', { job: failure.job }));
+    for (const line of failure.tail) out.push(`      | ${line}`);
+  }
+  const jobs = entry.jobs;
+  if (jobs !== undefined && jobs.length > failures.length) {
+    out.push(msg('cli.ci.jobs.other', { count: jobs.length - failures.length }));
+  }
+  return out;
+}
+
+function runJson(entry: RunReport): JsonValue {
+  return {
+    id: entry.run.id,
+    workflow: entry.run.workflow,
+    status: entry.run.status,
+    conclusion: entry.run.conclusion,
+    title: entry.run.title,
+    url: entry.run.url,
+    createdAt: entry.run.createdAt,
+    // Absent rather than empty on a run that was never opened: `jobs: []` on a green run would
+    // claim the run has no jobs, which is a different statement from "nobody asked".
+    ...(entry.jobs === undefined
+      ? {}
+      : {
+          jobs: entry.jobs.map((job) => ({
+            name: job.name,
+            status: job.status,
+            conclusion: job.conclusion,
+            url: job.url,
+          })),
+        }),
+    ...(entry.failures === undefined
+      ? {}
+      : {
+          failures: entry.failures.map((failure) => ({
+            job: failure.job,
+            url: failure.url,
+            failedSteps: [...failure.failedSteps],
+            tail: [...failure.tail],
+          })),
+        }),
+  };
+}

package/src/cmd-db-backfill.ts

@@ -0,0 +1,240 @@
+// `x db backfill`'s wiring alone: which of the four shapes an invocation asked for, and the one
+// finding-and-table projection each answers with. Split from `cmd-db.ts` the way `cmd-db-branch.ts`
+// was — that file had reached the 500-line ceiling, and "which subcommand ran" and "what a sweep
+// pass reports" are two jobs. The facts live in `db-backfill.ts`; nothing here opens a database.
+
+import { resolveEnvironment } from '@ultimat3/core';
+import { BackfillPendingError } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
+import type { CommandContext } from './command';
+import type { BackfillAction, BackfillPlanRow } from './db-backfill';
+import {
+  listBackfills,
+  pendingReport,
+  pendingToJson,
+  planToJson,
+  readAppliedMigrations,
+  renderBackfillTable,
+  renderPendingTable,
+  renderPlanTable,
+  runBackfills,
+} from './db-backfill';
+import { BadFlagError } from './errors';
+import { withJobDriver } from './jobs-driver';
+import { backfillToJson } from './jobs-json';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { findingFrom } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+
+/** Which of the four questions an invocation asked. `pass` is `<name>` and `--all` both. */
+type BackfillShape = 'list' | 'pending' | 'pass';
+
+/**
+ * Every flag that belongs to exactly ONE shape — `x db backfill`'s own usage line, executable.
+ *
+ * `--name` is absent because it is two things: `--list`'s filter and the pass's target, decided by
+ * `readShape` below. Everything else reads for one shape and is ignored by the other two, which is
+ * the silence this table ends.
+ */
+const SHAPE_OF_FLAG = Object.freeze<Record<string, BackfillShape>>({
+  status: 'list',
+  limit: 'list',
+  write: 'pass',
+  force: 'pass',
+});
+
+/** One runnable line per shape, so a refusal hands back the invocation the caller meant. */
+const FIX_OF_SHAPE = Object.freeze<Record<BackfillShape, string>>({
+  list: 'x db backfill --list --json',
+  pending: 'x db backfill --pending --json',
+  pass: 'x db backfill --all --write --json',
+});
+
+const refuseShape = (flag: string, reason: string, fix: string): never => {
+  throw new BadFlagError({ flag, command: 'db', reason, fix });
+};
+
+/**
+ * Exactly one shape, and only the flags that shape reads — refused before anything opens a
+ * database, never resolved by precedence.
+ *
+ * Precedence is what this replaces, and it was silent in the dangerous direction:
+ * `x db backfill cleanup --all --write` took the `--all` branch and ENQUEUED every pending sweep
+ * while the operator had named one, and `--list --pending` reported the ledger for a command that
+ * asked what was unswept. Axiom 1 — one way to do each thing — makes a second reading of one argv
+ * a refusal rather than a choice the command makes on the caller's behalf.
+ */
+function readShape(args: ParsedArgs): { readonly shape: BackfillShape; readonly name?: string } {
+  const list = flagBool(args, 'list');
+  const positional = args.positionals[0];
+  const named = flagString(args, 'name');
+  // `--name` is a FILTER under `--list` and a target everywhere else, so it selects a shape only
+  // where `--list` is absent. Two spellings of one target are still two, and are refused.
+  const target = list ? undefined : (positional ?? named);
+  if (!list && positional !== undefined && named !== undefined) {
+    return refuseShape(
+      'name',
+      `x db backfill names two backfills ("${positional}" and "${named}") — a pass sweeps the positional or --name, never both`,
+      `x db backfill ${positional} --write --json`,
+    );
+  }
+  const asked = [
+    ...(list ? ['--list'] : []),
+    ...(flagBool(args, 'pending') ? ['--pending'] : []),
+    ...(flagBool(args, 'all') ? ['--all'] : []),
+    ...(target === undefined ? [] : [target]),
+  ];
+  if (asked.length > 1) {
+    // The SECOND shape is the one that would have been dropped, so it is the one the cause names:
+    // `--all` won over a named sweep and the operator was never told which of the two ran.
+    const second = asked[1] ?? '';
+    return refuseShape(
+      second.startsWith('--') ? second.slice(2) : 'name',
+      `x db backfill was asked for ${asked.join(' and ')} — one shape per invocation: --list, --pending, <name> or --all`,
+      `x db backfill ${asked[0]} --json`,
+    );
+  }
+  if (asked.length === 0) {
+    return refuseShape(
+      'list',
+      'x db backfill needs a shape: --list (the ledger), --pending (declared minus completed), <name> or --all (run one, or every pending one)',
+      'x db backfill --pending --json',
+    );
+  }
+  const shape: BackfillShape = list ? 'list' : flagBool(args, 'pending') ? 'pending' : 'pass';
+  for (const [flag, owner] of Object.entries(SHAPE_OF_FLAG)) {
+    if (owner === shape || !args.flags.has(flag)) continue;
+    refuseShape(
+      flag,
+      `x db backfill --${flag} belongs to ${owner === 'pass' ? 'a <name>/--all pass' : `--${owner}`}, and this invocation asked for ${asked[0]}`,
+      FIX_OF_SHAPE[owner],
+    );
+  }
+  return target === undefined ? { shape } : { shape, name: target };
+}
+
+/**
+ * Four shapes, one subcommand: `--list` reads the `x_backfills` ledger, `--pending` diffs it
+ * against what the app DECLARED, and `<name>` / `--all` gate a pass and put it on the queue. A
+ * bare `x db backfill` is still refused rather than defaulted — the four answer four different
+ * questions, and picking one for the operator is the ambiguity axiom 1 exists to refuse.
+ *
+ * An empty ledger is `ok: true`. "Nothing has swept this database yet" is an answer to the
+ * question asked, and a command that failed over it would be unrunnable on a fresh app.
+ */
+export async function runBackfillCommand(
+  ctx: CommandContext,
+  root: string,
+): Promise<CommandResult> {
+  const asked = readShape(ctx.args);
+  if (asked.shape === 'list') return runBackfillList(ctx, root);
+  if (asked.shape === 'pending') return runBackfillPending(ctx, root);
+  return runBackfillPass(ctx, root, asked.name === undefined ? 'all' : [asked.name]);
+}
+
+async function runBackfillList(ctx: CommandContext, root: string): Promise<CommandResult> {
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await listBackfills(driver, {
+      name: flagString(ctx.args, 'name'),
+      status: flagString(ctx.args, 'status'),
+      limit: flagString(ctx.args, 'limit'),
+    });
+    return {
+      ok: true,
+      command: 'db',
+      summary:
+        rows.length === 0
+          ? msg('cli.db.backfill.empty')
+          : msg('cli.db.backfill.listed', { count: rows.length }),
+      lines: rows.length === 0 ? [] : renderBackfillTable(rows).map((line) => `  ${line}`),
+      data: rows.map(backfillToJson),
+    };
+  });
+}
+
+/**
+ * The alarm the framework did not have. Non-zero when anything is unswept, so a cron or a deploy
+ * check can read the exit code — a `--json` nobody has to parse to know something is wrong.
+ * `loadApp` first: importing the app's modules IS the declaration, and a diff run without it
+ * would report a clean database against an empty declaration list.
+ */
+async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  return withJobDriver(root, ctx, async (driver) => {
+    const report = await pendingReport(driver, environment);
+    return {
+      ok: report.pending.length === 0,
+      command: 'db',
+      summary:
+        report.pending.length === 0
+          ? msg('cli.db.backfill.swept', { declared: report.rows.length })
+          : msg('cli.db.backfill.pending', {
+              count: report.pending.length,
+              declared: report.rows.length,
+            }),
+      findings: report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
+      data: pendingToJson(report),
+    };
+  });
+}
+
+/**
+ * DRY RUN by default: `--write` is never implied, because the alternative is a command whose
+ * inspection form writes to a production table. What `--write` does is ENQUEUE — the queue is a
+ * job's execution surface, so the sweep runs on the workers already serving the new release
+ * rather than inside this process.
+ */
+async function runBackfillPass(
+  ctx: CommandContext,
+  root: string,
+  names: readonly string[] | 'all',
+): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  const write = flagBool(ctx.args, 'write');
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await runBackfills({
+      driver,
+      names,
+      write,
+      force: flagBool(ctx.args, 'force'),
+      environment,
+      appliedMigrations: await readAppliedMigrations(),
+    });
+    return backfillPassResult(rows, write);
+  });
+}
+
+/**
+ * A blocked or deduped name is a finding and a non-zero exit, and every OTHER name still ran —
+ * that isolation is what stops one wedged cleanup blocking every later one forever.
+ */
+function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
+  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+  // Counted per action, never derived from the total: a deduped pass is neither enqueued nor
+  // blocked, and `rows.length - enqueued` reported it as blocked while `--json` reported it as
+  // deduped. `planToJson` is the same list, so the two renders now add up to the same run.
+  const tally = (action: BackfillAction): number =>
+    rows.filter((row) => row.action === action).length;
+  return {
+    ok: findings.length === 0,
+    command: 'db',
+    summary: write
+      ? msg('cli.db.backfill.planned', {
+          count: rows.length,
+          enqueued: tally('enqueued'),
+          deduped: tally('deduped'),
+          blocked: tally('blocked'),
+        })
+      : msg('cli.db.backfill.dryRun', { count: rows.length }),
+    findings,
+    lines: rows.length === 0 ? [] : renderPlanTable(rows).map((line) => `  ${line}`),
+    data: planToJson(rows),
+  };
+}

package/src/cmd-db-branch.ts

@@ -3,6 +3,7 @@
 // `x db branch ls` used to clone a database called `ls`, because the argument was the name.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
+import { nearestName } from '@ultimat3/core';
 import { createPostgresClient, type DbClient } from '@ultimat3/db';
 import type { CommandContext } from './command';
 import type { BranchRow } from './db-branch';
@@ -27,7 +28,7 @@ import { resolveServices } from './dev-services';
 import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString, nearest } from './parse';
+import { flagString } from './parse';
 import { portFromEnv } from './serve';
 import { renderTable } from './table';
 
@@ -46,7 +47,7 @@ const LIST_FIX = `x ${LIST_ARGV}`;
  * `x` excluded — the error class adds it.
  */
 function branchRetry(word: string, name: string | undefined): string {
-  const near = nearest(word, [...BRANCH_SUBCOMMANDS]);
+  const near = nearestName(word, [...BRANCH_SUBCOMMANDS]);
   if (near !== undefined) return name === undefined ? LIST_ARGV : `db branch ${near} ${name}`;
   return isBranchName(word) ? `db branch create ${word}` : LIST_ARGV;
 }