@ultimat3/cli 1.0.0

package/src/jobs-json.ts

@@ -0,0 +1,134 @@
+// Every `--json` projection behind `x jobs`, and nothing else. Split out of `jobs-report.ts`:
+// `data` must be plain JSON — no `undefined`, no bare `unknown` — and that rule is only
+// enforceable if the projections sit together where one missing `?? null` is visible.
+
+import type {
+  DeadLetterEntry,
+  JobRecord,
+  JobTrace,
+  QueueDepthReport,
+  QueueStats,
+  StepTrace,
+} from '@ultimat3/jobs';
+import type { DrainFailure, DrainSkip } from './jobs-drain';
+import type { JsonValue } from './output';
+
+function stepTraceToJson(step: StepTrace): JsonValue {
+  return {
+    name: step.name,
+    status: step.status,
+    startedAt: step.startedAt,
+    completedAt: step.completedAt,
+    wakeAt: step.wakeAt,
+    durationMs: step.durationMs,
+    attempts: step.attempts,
+    error: step.error,
+  };
+}
+
+export function jobTraceToJson(trace: JobTrace): JsonValue {
+  return {
+    id: trace.id,
+    name: trace.name,
+    queue: trace.queue,
+    state: trace.state,
+    attempt: trace.attempt,
+    maxAttempts: trace.maxAttempts,
+    idempotencyKey: trace.idempotencyKey,
+    runId: trace.runId,
+    runAt: trace.runAt,
+    lastError: trace.lastError,
+    tenantId: trace.tenantId,
+    steps: trace.steps.map(stepTraceToJson),
+    retryDelaysMs: trace.retryDelaysMs.map((ms) => ms),
+  };
+}
+
+/**
+ * `input` is deliberately excluded: it is `unknown` at the driver boundary (an app-defined
+ * payload, not something this package can prove is JSON-safe), and `JobTrace` already sets the
+ * precedent of leaving it out of every JSON-facing projection.
+ */
+export function jobRecordToJson(record: JobRecord): JsonValue {
+  return {
+    id: record.id,
+    name: record.name,
+    queue: record.queue,
+    state: record.state,
+    attempt: record.attempt,
+    maxAttempts: record.maxAttempts,
+    idempotencyKey: record.idempotencyKey,
+    runId: record.runId,
+    runAt: record.runAt,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    tenantId: record.tenantId ?? null,
+    lastError: record.lastError ?? null,
+    claimedBy: record.claimedBy ?? null,
+    visibleAt: record.visibleAt ?? null,
+  };
+}
+
+function queueStatsToJson(stats: QueueStats): JsonValue {
+  return {
+    queue: stats.queue,
+    ready: stats.ready,
+    delayed: stats.delayed,
+    running: stats.running,
+    suspended: stats.suspended,
+    dead: stats.dead,
+    oldestReadyMs: stats.oldestReadyMs,
+  };
+}
+
+export function depthToJson(depth: QueueDepthReport): JsonValue {
+  return {
+    driver: depth.driver,
+    queues: depth.queues.map(queueStatsToJson),
+    totals: {
+      ready: depth.totals.ready,
+      delayed: depth.totals.delayed,
+      running: depth.totals.running,
+      suspended: depth.totals.suspended,
+      dead: depth.totals.dead,
+    },
+    oldestReadyMs: depth.oldestReadyMs,
+  };
+}
+
+export function deadLetterToJson(entry: DeadLetterEntry): JsonValue {
+  return {
+    id: entry.id,
+    name: entry.name,
+    queue: entry.queue,
+    attempt: entry.attempt,
+    lastError: entry.lastError,
+    failedAt: entry.failedAt,
+    retryCommand: entry.retryCommand,
+  };
+}
+
+export function drainFailureToJson(failure: DrainFailure): JsonValue {
+  return {
+    id: failure.id,
+    name: failure.name,
+    finding: {
+      code: failure.finding.code,
+      cause: failure.finding.cause,
+      fix: failure.finding.fix,
+      docs: failure.finding.docs ?? null,
+      at: failure.finding.at ?? null,
+    },
+  };
+}
+
+/** A candidate the drain refused to touch, and why — the half of the outcome `moved` cannot show. */
+export function drainSkipToJson(skip: DrainSkip): JsonValue {
+  return {
+    id: skip.id,
+    name: skip.name,
+    queue: skip.queue,
+    state: skip.state,
+    reason: skip.reason,
+  };
+}

package/src/jobs-report.ts

@@ -0,0 +1,132 @@
+// Pure, driver-injected job operations behind `x jobs`: flag parsing, plus ls / show / retry. No
+// CLI parsing, no process I/O, no rendering — a test drives every path with `createMemoryDriver()`
+// alone. Drain is `jobs-drain.ts`, the `--json` shapes `jobs-json.ts`, the table `jobs-table.ts`.
+
+import type {
+  DeadLetterEntry,
+  JobDriver,
+  JobFilter,
+  JobRecord,
+  JobState,
+  JobTrace,
+  QueueDepthReport,
+} from '@ultimat3/jobs';
+import {
+  inspectDeadLetters,
+  inspectJob,
+  inspectJobList,
+  inspectQueues,
+  retryFromStep,
+} from '@ultimat3/jobs';
+import { BadFlagError, JobUnknownError } from './errors';
+
+/** Mirrors `JobState` from `@ultimat3/jobs`, which exports the type but no runtime list. */
+export const JOB_STATES: readonly JobState[] = [
+  'ready',
+  'delayed',
+  'running',
+  'suspended',
+  'done',
+  'failed',
+  'dead',
+];
+
+const isJobState = (value: string): value is JobState =>
+  (JOB_STATES as readonly string[]).includes(value);
+
+export function parseStateFlag(value: string | undefined): JobState | undefined {
+  if (value === undefined) return undefined;
+  if (isJobState(value)) return value;
+  throw new BadFlagError({
+    flag: 'state',
+    command: 'jobs',
+    reason: `unknown state "${value}" (known: ${JOB_STATES.join(', ')})`,
+  });
+}
+
+/**
+ * A digit string is not yet a limit: past `Number.MAX_SAFE_INTEGER` the parse silently lands on a
+ * different integer, and `1e400`-shaped input yields `Infinity`. Either way the driver would be
+ * handed a bound other than the one typed, so the safe-integer check is the flag's real contract.
+ */
+export function parseLimitFlag(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const digits = value.trim();
+  const limit = /^\d+$/.test(digits) ? Number(digits) : Number.NaN;
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new BadFlagError({
+      flag: 'limit',
+      command: 'jobs',
+      reason: `expects an integer from 1 to ${Number.MAX_SAFE_INTEGER}, got "${value}"`,
+    });
+  }
+  return limit;
+}
+
+// ── ls ────────────────────────────────────────────────────────────────────
+
+export interface JobsListFilter {
+  readonly queue?: string | undefined;
+  readonly state?: string | undefined;
+  readonly name?: string | undefined;
+  readonly limit?: string | undefined;
+}
+
+export interface JobsListResult {
+  readonly depth: QueueDepthReport;
+  readonly rows: readonly JobRecord[];
+  readonly deadLetters: readonly DeadLetterEntry[];
+}
+
+/**
+ * The depth report AND the filtered rows, plus dead letters unconditionally: a dead job that a
+ * `--state ready` filter (or the default 100-row cap) pushes out of view is the exact failure
+ * mode this command exists to prevent.
+ */
+export async function listJobs(
+  driver: JobDriver,
+  filter: JobsListFilter = {},
+): Promise<JobsListResult> {
+  const state = parseStateFlag(filter.state);
+  const limit = parseLimitFlag(filter.limit);
+  const jobFilter: JobFilter = {
+    ...(filter.queue === undefined ? {} : { queue: filter.queue }),
+    ...(filter.name === undefined ? {} : { name: filter.name }),
+    ...(state === undefined ? {} : { state }),
+    ...(limit === undefined ? {} : { limit }),
+  };
+  const [depth, rows, deadLetters] = await Promise.all([
+    inspectQueues(driver),
+    inspectJobList(driver, jobFilter),
+    inspectDeadLetters(driver),
+  ]);
+  return { depth, rows, deadLetters };
+}
+
+// ── show ──────────────────────────────────────────────────────────────────
+
+export async function showJob(driver: JobDriver, id: string): Promise<JobTrace> {
+  const trace = await inspectJob(driver, id);
+  if (trace === undefined) throw new JobUnknownError({ id, driver: driver.name });
+  return trace;
+}
+
+// ── retry ─────────────────────────────────────────────────────────────────
+
+/**
+ * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: the
+ * concrete drivers (pg, memory) throw their own error from inside `requeue()` for a missing
+ * row, and that error is not this command's contract — `retryFromStep`'s documented `undefined`
+ * return is, and the driver never reaches it once the row is already known absent.
+ */
+export async function retryJob(
+  driver: JobDriver,
+  id: string,
+  fromStep?: string,
+): Promise<JobTrace> {
+  const existing = await inspectJob(driver, id);
+  if (existing === undefined) throw new JobUnknownError({ id, driver: driver.name });
+  const trace = await retryFromStep(driver, id, fromStep);
+  if (trace === undefined) throw new JobUnknownError({ id, driver: driver.name });
+  return trace;
+}

package/src/jobs-table.ts

@@ -0,0 +1,34 @@
+// The `x jobs ls` terminal table, and nothing else. Split out of `jobs-report.ts` so that
+// deciding how a value LOOKS lives apart from deciding what the queue DOES: a rendering rule
+// (column order, padding, the run-at unit) is reviewed here, once, with no queue logic around it.
+
+import type { JobRecord } from '@ultimat3/jobs';
+
+const HEADER = ['id', 'name', 'queue', 'state', 'attempt', 'run-at-ms'] as const;
+
+/**
+ * Fixed-width columns, same padding idiom as `renderRouteTable` in `cmd-routes.ts`.
+ *
+ * `run-at-ms` is the raw epoch, deliberately NOT a formatted date. The repo forbids formatting a
+ * date without an explicit IANA `timeZone`, and not formatting at all is the one rendering with
+ * no zone to get wrong. Formatting it properly would mean `@ultimat3/time`, which is not a
+ * declared dependency of this package and whose formatters need a locale the CLI has no concept
+ * of — and its output would no longer sort. `--json` already emits `runAt` as this same number,
+ * so the two renders of one command stay comparable; `x jobs show <id>` is the readable view.
+ */
+export function renderJobTable(rows: readonly JobRecord[]): readonly string[] {
+  const body = rows.map((row) => [
+    row.id,
+    row.name,
+    row.queue,
+    row.state,
+    String(row.attempt),
+    String(row.runAt),
+  ]);
+  const widths = HEADER.map((title, index) =>
+    Math.max(title.length, ...body.map((row) => (row[index] ?? '').length)),
+  );
+  const line = (cells: readonly string[]): string =>
+    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
+  return [line(HEADER), ...body.map(line)];
+}

package/src/json-merge.ts

@@ -0,0 +1,40 @@
+// The one union behind every `merge: 'json'` generated file. Deep, because a catalog is authored
+// nested (`{ site: { home: { title } } }`) — a shallow spread of two generators' contributions
+// under the same top-level key drops one of them entirely, and neither generator can see the other.
+
+/** A parsed JSON object: the only shape a `merge: 'json'` file is ever allowed to hold. */
+export type JsonObject = Record<string, unknown>;
+
+const isObject = (value: unknown): value is JsonObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * `incoming` merged under `held`, leaf by leaf. `held` always wins — on disk it is the file a
+ * human may have translated, and in `dedupe` it is the contribution that got there first — so a
+ * merge only ever *adds* keys. A branch meeting a leaf is the same conflict either direction:
+ * `held` keeps its shape, because overwriting it is the data loss this never does.
+ *
+ * `gained` is whether anything was actually added, so a caller can leave a file untouched rather
+ * than rewrite it byte-identically and claim it as written.
+ */
+export function mergeJsonDeep(
+  held: JsonObject,
+  incoming: JsonObject,
+): { merged: JsonObject; gained: boolean } {
+  const merged: JsonObject = { ...held };
+  let gained = false;
+  for (const [key, value] of Object.entries(incoming)) {
+    if (!Object.hasOwn(held, key)) {
+      merged[key] = value;
+      gained = true;
+      continue;
+    }
+    const current = held[key];
+    if (!isObject(current) || !isObject(value)) continue;
+    const nested = mergeJsonDeep(current, value);
+    if (!nested.gained) continue;
+    merged[key] = nested.merged;
+    gained = true;
+  }
+  return { merged, gained };
+}

package/src/mcp-db-target.ts

@@ -0,0 +1,50 @@
+// Which database the MCP dev host is pointed at, and whether that database is a branch. `db.migrate`
+// decides from this alone, so the reading has to be exact: a wrong `branch` is a migration against a
+// database somebody else is using.
+
+import { basename, join } from 'node:path';
+import { pgliteDataDir } from '@ultimat3/db';
+import type { DatabaseTarget } from '@ultimat3/mcp';
+import type { DevServices } from './dev-services';
+
+/**
+ * `production` is always false: this target is whatever `x dev` resolved — embedded PGlite under
+ * `.x/`, or the `DATABASE_URL` of a developer's shell. Production is reached through `ROLE=migrate`
+ * in a deploy hook, never through MCP. What actually stops a migration against a shared database is
+ * `branch`, which is null unless the name says otherwise.
+ */
+export function databaseTarget(services: DevServices): DatabaseTarget {
+  const url = services.db.url;
+  return services.db.mode === 'embedded'
+    ? { label: url, branch: pgliteBranch(url, services.stateDir), production: false }
+    : { label: safeLabel(url), branch: postgresBranch(url), production: false };
+}
+
+/** An external `DATABASE_URL` may carry credentials, and this string gets printed. */
+function safeLabel(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    return 'external database';
+  }
+}
+
+/** `x db branch <name>` names an external clone `<source>_branch_<name>` (`branchDatabaseName`). */
+function postgresBranch(url: string): string | null {
+  let database: string;
+  try {
+    database = new URL(url).pathname.replace(/^\//, '');
+  } catch {
+    return null;
+  }
+  return /_branch_(.+)$/.exec(database)?.[1] ?? null;
+}
+
+/** `branchPglite` copies `<stateDir>/pgdata` to `<stateDir>/pgdata-<name>`; the dev dir is no branch. */
+function pgliteBranch(url: string, stateDir: string): string | null {
+  const dir = pgliteDataDir(url);
+  const dev = join(stateDir, 'pgdata');
+  if (dir === dev || basename(dir) === basename(dev)) return null;
+  return dir.startsWith(`${dev}-`) ? dir.slice(dev.length + 1) : null;
+}

package/src/mcp-errors.ts

@@ -0,0 +1,99 @@
+// `errors.explain`: one runnable command per error code. Its own file because the CLI's fix table
+// is a contract — a code without a command is the thing "errors are instructions" exists to
+// prevent, and the typed record below is what makes forgetting one a build error.
+
+import { describeErrorCode, hasErrorCode, listErrorCodes } from '@ultimat3/core';
+import type { ErrorExplanation } from '@ultimat3/mcp';
+import type { CliErrorCode } from './errors';
+import { CLI_ERROR_CODES, docsFor } from './errors';
+
+/**
+ * One runnable command per CLI code. Typed over `CliErrorCode`, so a new code fails the build.
+ *
+ * Every `x` invocation here carries `--json`, because that is the flag the whole CLI is built
+ * around (`GLOBAL_FLAGS` in `parse.ts`, axiom 4): the agent that was handed one of these fixes ran
+ * a machine-readable command to get here, and a fix that drops back to prose breaks the loop it is
+ * meant to close. `bun`, `bunx` and the gate scripts keep their own surfaces — `--json` is the
+ * `x` CLI's contract, not a universal one.
+ */
+const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
+  X_CLI_UNKNOWN_COMMAND: 'x help --json',
+  X_CLI_BAD_FLAG: 'x help <command> --json',
+  X_VERIFY_FAILED: 'x verify --json',
+  X_NOT_IN_APP: 'x new myapp --json && cd myapp',
+  X_BUN_VERSION: 'bun upgrade',
+  X_NOT_IMPLEMENTED: 'x doctor --json',
+  X_TEST_NO_FILES: 'x test --cwd <repo root> --json',
+  X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
+  X_SCAFFOLD_PATH_ESCAPE: 'x g route <name> --json   # a path with no ".." segment',
+  X_GENERATE_JSON_INVALID:
+    'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
+  X_APP_PACKAGE_INVALID: 'bun pm pkg set name=<app> version=0.1.0',
+  X_ERROR_CODE_UNKNOWN: 'x errors list --json',
+  X_DECLARATION_UNKNOWN: 'x actions list --json',
+  X_JOB_UNKNOWN: 'x jobs ls --json',
+  X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
+  X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
+  X_ERROR_CODE_UNDOCUMENTED: 'x verify --json   # the finding names the code and the missing page',
+  X_ERROR_CODE_UNREGISTERED:
+    'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
+  X_CLI_UNEXPECTED: 'x doctor --json',
+  X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
+  X_LINT_FAILED: 'bunx biome check --write .',
+  X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
+  X_FILE_TOO_LONG: 'x verify --json   # the finding names the file to split',
+  X_PACKAGE_SHAPE: 'bun run scripts/new-package.ts <pkg> --only <file>',
+  X_RELEASE_VERSION_SKEW: 'bun run scripts/release.ts --bump patch --dry-run --json',
+  X_MANIFEST_STALE: 'x manifest --json',
+  X_BUDGET_UNMEASURED: 'x build --json && x verify --json',
+  X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
+  X_DEPLOY_FAILED: 'x deploy --json   # the finding carries the command to re-run directly',
+  X_GENERATE_CONFLICT: 'x g <kind> <name> --force --json',
+  X_PORT_IN_USE: 'x dev --port 3001 --json',
+  // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
+  // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
+  // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.
+  X_DB_GEN_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
+  X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
+  X_DB_BRANCH_FAILED: 'x db branch ls --json',
+  X_DB_STUDIO_FAILED: 'x doctor --json',
+  X_BOUNDARY_SITE_TO_APP: 'x fix boundary <file> --json',
+  X_BOUNDARY_SHARED_LEAF: 'x fix boundary <file> --json',
+  X_BOUNDARY_APP_TO_API: 'x fix boundary <file> --json',
+  X_BOUNDARY_ROUTE_TO_DB: 'x fix boundary <file> --json',
+  X_BOUNDARY_SERVICE_TO_HTTP: 'x fix boundary <file> --json',
+};
+
+const isCliCode = (code: string): code is CliErrorCode =>
+  (CLI_ERROR_CODES as readonly string[]).includes(code);
+
+/**
+ * `undefined` for a code nobody registered — the tool then answers "unknown error code", which
+ * beats an invented explanation. The framework-wide registry holds a title and a docs URL but no
+ * fix (a thrown error carries its own), so a non-CLI code points at the gate that surfaces it.
+ */
+export function explainErrorCode(code: string): ErrorExplanation | undefined {
+  const cli = isCliCode(code);
+  if (!cli && !hasErrorCode(code)) return undefined;
+  const described = describeErrorCode(code);
+  return {
+    code,
+    cause: described.title,
+    fix: cli ? CLI_FIXES[code] : 'x verify --json',
+    docs: cli ? docsFor(code) : described.docs,
+  };
+}
+
+/**
+ * Every code an agent can be handed, in one sorted list. Reads the framework-wide registry rather
+ * than a second table: `errors.ts` registers the CLI's own titles at import, so a code that is
+ * missing here is a code nobody registered — which is exactly what the list should show.
+ */
+export function explainEveryErrorCode(): readonly ErrorExplanation[] {
+  const explained: ErrorExplanation[] = [];
+  for (const entry of listErrorCodes()) {
+    const explanation = explainErrorCode(entry.code);
+    if (explanation !== undefined) explained.push(explanation);
+  }
+  return explained;
+}