@ultimat3/cli 24.0.0 → 25.0.0

package/src/jobs-drain.ts

@@ -1,230 +0,0 @@
-// `x jobs drain`: moving in-flight work from one queue driver onto another. Its own file because
-// it is the only command here that WRITES to two drivers at once, and the ordering rule that makes
-// that safe — lease, copy steps, enqueue, then ack — has to be readable in one screen.
-
-import { logger, uuid } from '@ultimat3/core';
-import type { ClaimedJob, JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
-import { claimOf, inspectJobList, jobCursor, MAX_JOB_PAGE } from '@ultimat3/jobs';
-import type { Finding } from './output';
-import { findingFrom } from './output';
-
-/** `running` is deliberately excluded: a job a worker is mid-execution on is not "pending". */
-const PENDING_STATES: readonly JobState[] = ['ready', 'delayed', 'suspended'];
-
-/**
- * The lease has to outlive the transfer of the whole BATCH it covers: a batch is claimed up front,
- * and a lease expiring mid-batch would hand a half-transferred job back to a source worker. A
- * batch is at most `MAX_JOB_PAGE` rows, so this is a ceiling over a couple of hundred sequential
- * enqueues rather than a guess about however many the queue holds.
- */
-const DRAIN_LEASE_MS = 300_000;
-
-const NO_LEASE = 'no lease could be taken — not yet due, or a worker is already running it';
-
-export interface DrainFailure {
-  readonly id: string;
-  readonly name: string;
-  readonly finding: Finding;
-}
-
-/** A candidate the drain deliberately left alone, because it could not prove it owned the job. */
-export interface DrainSkip {
-  readonly id: string;
-  readonly name: string;
-  readonly queue: string;
-  readonly state: JobState;
-  readonly reason: string;
-}
-
-export interface DrainOutcome {
-  readonly from: string;
-  readonly to: string;
-  readonly dryRun: boolean;
-  readonly candidates: readonly JobRecord[];
-  readonly moved: readonly JobRecord[];
-  readonly skipped: readonly DrainSkip[];
-  readonly failures: readonly DrainFailure[];
-}
-
-/**
- * The lease IS the proof of ownership. `ack()` takes only a job id, so a drain that ack'd rows
- * off a snapshot could acknowledge a job a source worker claimed and is executing right now —
- * the target would then run a duplicate of a job still in flight. One batch claim over the
- * candidates' own queues; whatever comes back is the drain's to move, and everything else is
- * left alone. `queues` is always explicit because the pg driver reads an empty list as
- * `['default']` rather than as "every queue".
- */
-function leaseBatch(
-  source: JobDriver,
-  candidates: readonly JobRecord[],
-  limit: number,
-): Promise<readonly ClaimedJob[]> {
-  if (candidates.length === 0 || limit <= 0) return Promise.resolve([]);
-  return source.claim({
-    queues: [...new Set(candidates.map((record) => record.queue))],
-    limit,
-    visibilityTimeoutMs: DRAIN_LEASE_MS,
-    workerId: `x-jobs-drain:${uuid()}`,
-    // A claim BURIES a row whose lease lapsed on its final attempt, whoever makes it — this one
-    // too. The drain is an operator's tool with no worker context, so it runs no `onSettled`
-    // (at most once across a crash, as documented) and names no `dropExhausted`: said out loud
-    // here, because an unlistened burial is a row that went `dead` with nothing anywhere saying so.
-    onExhausted: (dead) => {
-      for (const row of dead) {
-        logger.error('jobs.claim.exhausted', {
-          workerId: 'x-jobs-drain',
-          job: row.name,
-          jobId: row.id,
-          attempt: row.attempt,
-          maxAttempts: row.maxAttempts,
-          error: row.lastError ?? '',
-        });
-      }
-    },
-  });
-}
-
-/**
- * Every row in `state`, page by page on the keyset cursor until a short page: one page was the
- * drivers' default 100, so a drain of 350 ready jobs moved 100 and left 250 on the source.
- */
-async function everyRow(source: JobDriver, state: JobState): Promise<readonly JobRecord[]> {
-  const rows: JobRecord[] = [];
-  let after: string | undefined;
-  for (;;) {
-    const page = await inspectJobList(source, {
-      state,
-      limit: MAX_JOB_PAGE,
-      ...(after === undefined ? {} : { after }),
-    });
-    rows.push(...page);
-    const last = page.at(-1);
-    if (page.length < MAX_JOB_PAGE || last === undefined) return rows;
-    after = jobCursor(last);
-  }
-}
-
-/** Steps carry their own `runId`, so a copy lands under the same key the target job resumes on. */
-async function copySteps(source: JobDriver, target: JobDriver, runId: string): Promise<void> {
-  for (const record of await source.steps.list(runId)) await target.steps.put(record);
-}
-
-/**
- * Hand a leased job back exactly as the drain found it. `countsAsAttempt: false` is the point:
- * a transfer that failed is not a failed attempt, and burning one per `x jobs drain` retry would
- * dead-letter a job nobody ever ran.
- *
- * It returns to `ready`, which is what "as the drain found it" means — the drain leased a ready
- * job and could not move it. It used to land in `suspended`, not by intent but because
- * `countsAsAttempt: false` was the only bit the drivers had and `step.sleep` had claimed it;
- * `NackOptions.park` now carries the suspension, so the two callers no longer share one meaning.
- */
-async function releaseLease(source: JobDriver, leased: ClaimedJob): Promise<void> {
-  try {
-    // Fenced on the drain's own claim, like every settle: a lease that lapsed is not handed back.
-    await source.nack(leased.id, {
-      ...claimOf(leased),
-      delayMs: 0,
-      countsAsAttempt: false,
-    });
-  } catch {
-    // The lease expires on its own. Masking the transfer's real error with this one helps nobody.
-  }
-}
-
-const toSkip = (record: JobRecord): DrainSkip => ({
-  id: record.id,
-  name: record.name,
-  queue: record.queue,
-  state: record.state,
-  reason: NO_LEASE,
-});
-
-/**
- * Move every pending job the drain can take a lease on from `source` onto `target`. `--dry-run`
- * reports the candidate list, takes no lease and enqueues nothing. Per-record try/catch, not a
- * batch operation: one record that cannot enqueue on the target (a redis/nats stub, a transient
- * error) must not stop the rest from moving, and the caller reports each failure on its own.
- */
-export async function drainJobs(
-  source: JobDriver,
-  target: JobDriver,
-  dryRun: boolean,
-): Promise<DrainOutcome> {
-  const lists = await Promise.all(PENDING_STATES.map((state) => everyRow(source, state)));
-  const candidates = lists.flat();
-  const base = { from: source.name, to: target.name, candidates };
-  if (dryRun) return { ...base, dryRun: true, moved: [], skipped: [], failures: [] };
-
-  const found = new Map(candidates.map((record) => [record.id, record]));
-  const held = new Set<string>();
-  const moved: JobRecord[] = [];
-  const failures: DrainFailure[] = [];
-  // Batch by batch, each under its own lease, until the claims stop or the snapshot's count is
-  // spent — a claim may lease a row enqueued after the snapshot, and that row spends the budget
-  // too, so a queue that keeps filling cannot keep the drain running.
-  let budget = candidates.length;
-  while (budget > 0) {
-    const leased = await leaseBatch(source, candidates, Math.min(budget, MAX_JOB_PAGE));
-    if (leased.length === 0) break;
-    // A row the target already refused is tried once per drain: handed straight back, spending
-    // no budget and adding no second failure for the same id.
-    const refused = new Set(failures.map((failure) => failure.id));
-    const fresh = leased.filter((record) => !refused.has(record.id));
-    for (const record of leased) if (refused.has(record.id)) await releaseLease(source, record);
-    if (fresh.length === 0) break;
-    budget -= fresh.length;
-    for (const record of fresh) held.add(record.id);
-    const before = moved.length;
-    await transfer(source, target, fresh, found, moved, failures);
-    // A batch that moved nothing handed its leases back, and the next claim would take the same
-    // rows to the same refusing target: stop, and let the failures already counted say why.
-    if (moved.length === before) break;
-  }
-  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
-  return { ...base, dryRun: false, moved, skipped, failures };
-}
-
-/** One leased batch onto the target: steps, then the job, then the ack — per record. */
-async function transfer(
-  source: JobDriver,
-  target: JobDriver,
-  leased: readonly ClaimedJob[],
-  found: ReadonlyMap<string, JobRecord>,
-  moved: JobRecord[],
-  failures: DrainFailure[],
-): Promise<void> {
-  for (const record of leased) {
-    let enqueued = false;
-    try {
-      // Steps BEFORE the job: a worker on the target must never be able to claim a run whose
-      // checkpoint has not landed, or it repeats completed steps or loses them outright.
-      await copySteps(source, target, record.runId);
-      await target.enqueue({
-        name: record.name,
-        queue: record.queue,
-        input: record.input,
-        idempotencyKey: record.idempotencyKey,
-        runId: record.runId,
-        maxAttempts: record.maxAttempts,
-        runAt: record.runAt,
-        ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
-      });
-      enqueued = true;
-      // Only now is the ack the drain's to make: the lease proves no source worker holds this
-      // job, and the target already has both the row and its steps. A crash between the two
-      // leaves the job live on both drivers, where `idempotencyKey` dedupes it.
-      // `counted: false`: the row is finished HERE because it left, and a job that was moved is
-      // not a job that completed — it must add nothing to the source's `done` history.
-      await source.ack(record.id, { ...claimOf(record), counted: false });
-      // Report the row as the drain FOUND it: `claim()` returns it mid-lease (`running`, one
-      // attempt higher), a state nothing on either driver is in once this returns.
-      moved.push(found.get(record.id) ?? record);
-    } catch (error) {
-      // A failed enqueue left nothing on the target, so the lease goes back. A failed ack did
-      // not: the job is already live there, and releasing it would race the target's worker.
-      if (!enqueued) await releaseLease(source, record);
-      failures.push({ id: record.id, name: record.name, finding: findingFrom(error) });
-    }
-  }
-}

package/src/scaffold-typecheck.ts

@@ -1,227 +0,0 @@
-// Typechecks what `x new` and `x g` write, the way the user's own `tsc` will: real files on disk,
-// the real workspace packages, the real compiler. A template that merely parses has not been
-// checked — it has moved its failure from this gate to the first command the user runs.
-
-// `node:` and not Bun: Bun has no API for a temporary directory (`mkdtempSync` + `tmpdir`), for a
-// symlink (`symlinkSync`, how the sandbox borrows the workspace's node_modules), or for a
-// recursive delete (`rmSync`). `node:path` comes with them — `Bun.write` takes the joined path,
-// but only `resolve`/`sep` can prove that path stayed inside the sandbox.
-import { mkdtempSync, rmSync, symlinkSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve, sep } from 'node:path';
-import { ScaffoldPathEscapeError } from './errors';
-import type { Runner } from './exec';
-import { exec } from './exec';
-import { FIXTURE_APP, scaffoldFixture } from './scaffold-fixture';
-import type { GeneratedFile } from './templates';
-
-/** Derived from this file, never from cwd, so the harness works from any working directory. */
-export const workspaceRoot = (): string => resolve(import.meta.dir, '..', '..', '..');
-
-export interface TypeDiagnostic {
-  /** Sandbox-relative path, or '' for a diagnostic the compiler raised about the project itself. */
-  readonly file: string;
-  readonly line: number;
-  readonly code: string;
-  readonly message: string;
-}
-
-const AT_FILE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
-const PROJECT_WIDE = /^error (TS\d+): (.*)$/;
-
-/**
- * Config errors carry no file, so both shapes are collected: a silent harness is a green lie.
- * Split on `\r?\n`, because a trailing `\r` lands inside the message capture and no `KNOWN_GAPS`
- * entry would match it — a CRLF `tsc` would turn every pinned gap into an unexplained failure.
- */
-export function parseDiagnostics(output: string): readonly TypeDiagnostic[] {
-  const found: TypeDiagnostic[] = [];
-  for (const line of output.split(/\r?\n/)) {
-    const at = AT_FILE.exec(line);
-    if (at !== null) {
-      found.push({
-        file: at[1] ?? '',
-        line: Number.parseInt(at[2] ?? '0', 10),
-        code: at[4] ?? '',
-        message: at[5] ?? '',
-      });
-      continue;
-    }
-    const wide = PROJECT_WIDE.exec(line.trim());
-    if (wide !== null)
-      found.push({ file: '', line: 0, code: wide[1] ?? '', message: wide[2] ?? '' });
-  }
-  return found;
-}
-
-export interface KnownGap {
-  /** `ScaffoldVariant.name`. A pin bought by one invocation may not excuse another. */
-  readonly variant: string;
-  readonly code: string;
-  /** Exact sandbox-relative path. A pattern would absolve the same bug in a file nobody pinned. */
-  readonly file: string;
-  /** Exact `tsc` message. Matched literally so a near-miss regression is not absorbed. */
-  readonly message: string;
-  /** Who fixes it, and why the template cannot. */
-  readonly owner: string;
-}
-
-/**
- * Diagnostics a template cannot fix, pinned one occurrence at a time. Pinned, never ignored:
- * `unexpectedIn` fails on anything not listed here — including a second copy of a listed
- * diagnostic, because each entry is consumed by exactly one match — and `staleGapsIn` fails when
- * a listed entry stops reproducing, so an entry cannot outlive the bug it describes.
- *
- * Empty, and that is the point: `invariants:` is one callback over the whole list, so `c` is typed
- * from the entity's own columns and the six `TS18048 'c.title' is possibly 'undefined'` pins this
- * list used to carry are gone. A new entry here is a template shipping a diagnostic, which needs
- * an owner who can remove it — not a permanent exemption.
- */
-export const KNOWN_GAPS: readonly KnownGap[] = [];
-
-/**
- * The pins one invocation may spend. Another variant's pins are not its to spend. `gaps` is a
- * parameter for the same reason it is on `unexpectedIn` and `staleGapsIn`: with `KNOWN_GAPS`
- * legitimately empty, the bookkeeping is only testable against a list a test supplies.
- */
-export const gapsFor = (
-  variant: string,
-  gaps: readonly KnownGap[] = KNOWN_GAPS,
-): readonly KnownGap[] => gaps.filter((gap) => gap.variant === variant);
-
-const matches = (diagnostic: TypeDiagnostic, gap: KnownGap): boolean =>
-  diagnostic.code === gap.code &&
-  diagnostic.file === gap.file &&
-  diagnostic.message === gap.message;
-
-export interface GapPartition {
-  /** Diagnostics no unconsumed `KNOWN_GAPS` entry accounts for. */
-  readonly unexpected: readonly TypeDiagnostic[];
-  /** Entries that found no match — the bug is fixed and the pin has to go. */
-  readonly stale: readonly KnownGap[];
-}
-
-/**
- * One pass, first-fit, each pin spent once. Counting matters: two occurrences of a diagnostic
- * pinned once means a new regression is hiding behind an old bug, so the surplus is unexpected.
- */
-export function partitionDiagnostics(
-  diagnostics: readonly TypeDiagnostic[],
-  gaps: readonly KnownGap[] = KNOWN_GAPS,
-): GapPartition {
-  const budget = gaps.map((gap) => ({ gap, spent: false }));
-  const unexpected: TypeDiagnostic[] = [];
-  for (const entry of diagnostics) {
-    const slot = budget.find((pin) => !pin.spent && matches(entry, pin.gap));
-    if (slot === undefined) unexpected.push(entry);
-    else slot.spent = true;
-  }
-  return { unexpected, stale: budget.filter((pin) => !pin.spent).map((pin) => pin.gap) };
-}
-
-/** Everything the gate refuses: a diagnostic no unconsumed `KNOWN_GAPS` entry accounts for. */
-export const unexpectedIn = (
-  diagnostics: readonly TypeDiagnostic[],
-  gaps: readonly KnownGap[] = KNOWN_GAPS,
-): readonly TypeDiagnostic[] => partitionDiagnostics(diagnostics, gaps).unexpected;
-
-/** Entries that no longer reproduce — the bug is fixed and the pin has to go. */
-export const staleGapsIn = (
-  diagnostics: readonly TypeDiagnostic[],
-  gaps: readonly KnownGap[] = KNOWN_GAPS,
-): readonly KnownGap[] => partitionDiagnostics(diagnostics, gaps).stale;
-
-/** Written beside the app's own tsconfig so the gate inherits every flag the app ships with. */
-const OVERLAY = 'tsconfig.scaffold-check.json';
-
-/**
- * The one thing the sandbox may change about the generated project: where its imports resolve.
- * `@ultimat3/*` points at workspace source instead of a published tarball, and the app's own
- * workspace packages resolve without a `bun install` that a sealed test could never run.
- */
-const overlay = (root: string, app: string): string =>
-  `${JSON.stringify(
-    {
-      extends: './tsconfig.json',
-      compilerOptions: {
-        noEmit: true,
-        paths: {
-          // The subpath exports a generated app reaches for, spelled the way the packages' own
-          // `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a package
-          // name, and `cli/serve` as `packages/cli/serve`. Longest prefix wins, so these are
-          // consulted first. `@ultimat3/cli/serve` is what `x new`'s `apps/web/server.ts` imports.
-          '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
-          '@ultimat3/query/client': [`${root}/packages/query/src/client`],
-          '@ultimat3/render/server': [`${root}/packages/render/src/server`],
-          '@ultimat3/cli/serve': [`${root}/packages/cli/src/serve-entry`],
-          '@ultimat3/testing/test-types': [`${root}/packages/testing/src/test-types`],
-          '@ultimat3/*': [`${root}/packages/*/src`],
-          [`@${app}/web/*`]: ['./apps/web/*'],
-          [`@${app}/admin/*`]: ['./apps/admin/*'],
-          [`@${app}/*`]: ['./packages/*/src'],
-        },
-      },
-    },
-    null,
-    2,
-  )}\n`;
-
-export interface TypecheckOptions {
-  readonly files?: readonly GeneratedFile[];
-  readonly app?: string;
-  readonly runner?: Runner;
-  /** Leave the sandbox on disk. For debugging a red gate by hand, never for the gate itself. */
-  readonly keep?: boolean;
-}
-
-export interface TypecheckReport {
-  readonly dir: string;
-  readonly fileCount: number;
-  readonly diagnostics: readonly TypeDiagnostic[];
-  readonly output: string;
-}
-
-/**
- * `GeneratedFile.path` is documented as relative-POSIX, not enforced as it. A `..` segment would
- * put template output on the developer's real disk, so the sandbox proves containment before it
- * writes rather than after.
- */
-export function sandboxPath(dir: string, path: string): string {
-  const target = resolve(dir, path);
-  if (target !== dir && !target.startsWith(`${dir}${sep}`))
-    throw new ScaffoldPathEscapeError({ path, dir });
-  return target;
-}
-
-export async function typecheckScaffold(options: TypecheckOptions = {}): Promise<TypecheckReport> {
-  const root = workspaceRoot();
-  const app = options.app ?? FIXTURE_APP;
-  const files = options.files ?? scaffoldFixture();
-  const dir = mkdtempSync(join(tmpdir(), 'x-scaffold-'));
-  try {
-    for (const file of files) await Bun.write(sandboxPath(dir, file.path), file.contents);
-    // The sandbox borrows the workspace's installed dependencies. The gate is about the
-    // templates; whether a registry install succeeds is a different question, and a sealed
-    // test cannot ask it.
-    symlinkSync(join(root, 'node_modules'), join(dir, 'node_modules'), 'dir');
-    await Bun.write(join(dir, OVERLAY), overlay(root, app));
-    const result = await (options.runner ?? exec)(
-      [join(root, 'node_modules', '.bin', 'tsc'), '--noEmit', '--pretty', 'false', '-p', OVERLAY],
-      { cwd: dir },
-    );
-    const output = [result.stdout, result.stderr].filter((part) => part.length > 0).join('\n');
-    return { dir, fileCount: files.length, diagnostics: parseDiagnostics(output), output };
-  } finally {
-    if (options.keep !== true) rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-/** One diagnostic per line, in the shape `tsc` prints — a failed gate is a runnable bug report. */
-export const formatDiagnostics = (diagnostics: readonly TypeDiagnostic[]): string =>
-  diagnostics
-    .map((entry) =>
-      entry.file === ''
-        ? `error ${entry.code}: ${entry.message}`
-        : `${entry.file}:${entry.line} ${entry.code}: ${entry.message}`,
-    )
-    .join('\n');

package/src/thrown-by.ts

@@ -1,24 +0,0 @@
-// One `thrownBy` for every test in this package. What a caller acts on is the thrown *shape* —
-// the code, the cause and the fix — never the class, so a test that asserts on the class would
-// pass while the fix line rots. Shared rather than copied: a second copy asserts less, silently.
-
-import { expect } from 'bun:test';
-
-/** The three fields every `UltimateError` carries, as a test reads them off the thrown value. */
-export interface ThrownShape {
-  readonly code?: string;
-  readonly cause?: string;
-  readonly fix?: string;
-}
-
-export function thrownBy(call: () => unknown): ThrownShape {
-  try {
-    call();
-  } catch (error) {
-    return error as ThrownShape;
-  }
-  // Not `throw new Error(...)`: a bare throw carries no code and no fix, and this is the one
-  // failure a test author most needs named. `expect.unreachable` fails through the runner, which
-  // prints the assertion the caller wrote instead of a stack from inside this helper.
-  return expect.unreachable('expected a throw');
-}