@ultimat3/cli 1.0.0

package/src/cmd-i18n.ts

@@ -0,0 +1,212 @@
+// `x i18n check|add <locale>|sync <locale>` — the command every X_LOCALE_UNSUPPORTED,
+// X_CATALOG_MISSING_KEYS and X_CATALOG_INVALID fix line already names. CLI wiring only: the
+// facts come from `i18n-audit.ts`, the audit itself from `@ultimat3/i18n`'s own `auditCatalogs`.
+
+// `node:` and not Bun: Bun has no exclusive-create write, and `open(path, 'wx')` is the only one
+// there is — `Bun.write` overwrites, so an existence check before it is a race a second `x i18n
+// add` wins. `mkdir` comes with it because `open` does not create the parent directory `Bun.write`
+// would, and `node:path` because Bun exposes no path API to build what either of them takes.
+import { type FileHandle, mkdir, open } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { catalogKeys, catalogMissingKeys } from '@ultimat3/i18n';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, CatalogExistsError } from './errors';
+import {
+  auditApp,
+  loadCatalogs,
+  resolveDefaultLocale,
+  seedCatalog,
+  serializeCatalog,
+  syncCatalog,
+} from './i18n-audit';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+import { renderTable } from './table';
+import { catalogPath, resolveLocales } from './templates/locales';
+
+export const I18N_SUBCOMMANDS = ['check', 'add', 'sync'] as const;
+
+/** `ExtractReport` is plain JSON by construction — same idiom as `cmd-registries.ts`'s `asJson`. */
+const asJson = (value: object): Record<string, JsonValue> => value as Record<string, JsonValue>;
+
+/** `open`'s failure when the file is already there — the one errno this command translates. */
+const isAlreadyExists = (error: unknown): boolean =>
+  typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
+
+/**
+ * The exclusive half of the create: `wx` fails rather than truncates, so an existing catalog is
+ * refused by the write itself. An `existsSync` before a `Bun.write` is the same answer with a
+ * window in it, and what falls through that window is a translator's work.
+ */
+async function openExclusive(absolute: string, locale: string): Promise<FileHandle> {
+  try {
+    return await open(absolute, 'wx');
+  } catch (error) {
+    if (isAlreadyExists(error)) throw new CatalogExistsError({ locale, path: catalogPath(locale) });
+    throw error;
+  }
+}
+
+/** `x i18n add`'s only write. `catalogs/` may not exist yet, and `open` never creates it. */
+async function writeNewCatalog(absolute: string, locale: string, contents: string): Promise<void> {
+  await mkdir(dirname(absolute), { recursive: true });
+  const handle = await openExclusive(absolute, locale);
+  try {
+    await handle.writeFile(contents);
+  } finally {
+    await handle.close();
+  }
+}
+
+function requireLocalePositional(ctx: CommandContext, sub: string): string {
+  const raw = ctx.args.positionals[0];
+  if (raw === undefined) {
+    throw new BadFlagError({
+      flag: 'locale',
+      command: 'i18n',
+      reason: `"x i18n ${sub}" needs a locale: x i18n ${sub} <locale>`,
+    });
+  }
+  return raw;
+}
+
+/**
+ * Validates + canonicalizes the positional locale — `resolveLocales`'s own BCP-47/escape checks
+ * do the refusing, against this command's context rather than the generic `x g --locales` default:
+ * the cause names `--locale on "x i18n"` and the fix is `x i18n add es` / `x i18n sync es`.
+ */
+function resolveOneLocale(ctx: CommandContext, sub: string): string {
+  const raw = requireLocalePositional(ctx, sub);
+  const resolved = resolveLocales([raw], {
+    fix: `x i18n ${sub} es`,
+    command: 'i18n',
+    flag: 'locale',
+  });
+  const locale = resolved[0];
+  if (locale === undefined) {
+    // Unreachable in practice — resolveLocales only returns [] for zero requested entries, and
+    // this always passes exactly one. Guarded rather than cast past, for noUncheckedIndexedAccess.
+    throw new BadFlagError({
+      flag: 'locale',
+      command: 'i18n',
+      reason: 'could not resolve a locale',
+    });
+  }
+  return locale;
+}
+
+async function runCheck(root: string): Promise<CommandResult> {
+  const { report, catalogs } = await auditApp(root);
+
+  const findings: Finding[] = report.locales
+    .filter((audit) => audit.missing.length > 0)
+    .map((audit) => ({
+      ...findingFrom(catalogMissingKeys(audit.locale, audit.missing)),
+      at: catalogPath(audit.locale),
+    }));
+
+  const header = ['locale', 'keys', 'missing', 'unused'];
+  const rows = report.locales.map((audit) => [
+    audit.locale,
+    String(catalogKeys(catalogs[audit.locale] ?? {}).length),
+    String(audit.missing.length),
+    String(audit.unused.length),
+  ]);
+  const lines = renderTable(header, rows).map((line) => `  ${line}`);
+
+  for (const audit of report.locales) {
+    if (audit.unused.length === 0) continue;
+    lines.push(`  ${msg('cli.i18n.unused', { count: audit.unused.length, locale: audit.locale })}`);
+    for (const key of audit.unused) lines.push(`    ${key}`);
+  }
+  if (report.dynamic.length > 0) {
+    lines.push(`  ${msg('cli.i18n.dynamic', { count: report.dynamic.length })}`);
+    for (const entry of report.dynamic) {
+      // A multi-line argument (a ternary over string literals) is one finding, so it is one line —
+      // an entry that wrapped would break the indented list it belongs to.
+      const expression = entry.expression.replace(/\s+/g, ' ');
+      lines.push(`    ${entry.file}:${entry.line}:${entry.column}  ${expression}`);
+    }
+  }
+
+  const gapLocales = report.locales.filter((audit) => audit.missing.length > 0).length;
+  const missingTotal = report.locales.reduce((sum, audit) => sum + audit.missing.length, 0);
+  const summary = report.ok
+    ? msg('cli.i18n.ok', { locales: report.locales.length, keys: report.used.length })
+    : msg('cli.i18n.gaps', { missing: missingTotal, locales: gapLocales });
+
+  return { ok: report.ok, command: 'i18n', summary, lines, findings, data: asJson(report) };
+}
+
+async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult> {
+  const locale = resolveOneLocale(ctx, 'add');
+  const path = catalogPath(locale);
+  const app = await loadApp(root);
+  const catalogs = await loadCatalogs(root);
+  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const seeded = seedCatalog(from === undefined ? {} : (catalogs[from] ?? {}));
+  await writeNewCatalog(join(root, path), locale, serializeCatalog(seeded));
+
+  const keys = catalogKeys(seeded).length;
+  return {
+    // The catalog is on disk, so the command did what it was asked. `loadApp`'s findings ride along
+    // rather than flip that: a `packages/i18n/src/index.ts` that would not import is why `from` may
+    // be the framework's `en` instead of the app's own default, and silence there is the bug.
+    ok: true,
+    command: 'i18n',
+    summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
+    findings: app.findings,
+    data: { locale, from: from ?? locale, keys, path },
+  };
+}
+
+async function runSync(root: string, ctx: CommandContext): Promise<CommandResult> {
+  const locale = resolveOneLocale(ctx, 'sync');
+  const catalogs = await loadCatalogs(root);
+  const target = catalogs[locale];
+  if (target === undefined) {
+    throw new BadFlagError({
+      flag: 'locale',
+      command: 'i18n',
+      reason: `no catalog for "${locale}" at ${catalogPath(locale)}`,
+      fix: `x i18n add ${locale}`,
+    });
+  }
+
+  const app = await loadApp(root);
+  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const source = from === undefined ? {} : (catalogs[from] ?? {});
+  const { merged, added } = syncCatalog(target, source);
+  if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
+
+  const total = catalogKeys(merged).length;
+  return {
+    // Same as `runAdd`: the merge landed, and `loadApp`'s findings say whether `from` is the app's
+    // own default or the framework's fallback standing in for an i18n module that would not import.
+    ok: true,
+    command: 'i18n',
+    summary: msg('cli.i18n.synced', { locale, from: from ?? locale, added: added.length, total }),
+    findings: app.findings,
+    data: { locale, from: from ?? locale, added, total, path: catalogPath(locale) },
+  };
+}
+
+export const i18nCommand: CliCommand = {
+  spec: {
+    name: 'i18n',
+    summary: 'catalogs: add a locale, sync keys, check for gaps',
+    usage: 'x i18n [check|add <locale>|sync <locale>] [--json]',
+    requiresApp: true,
+    subcommands: I18N_SUBCOMMANDS,
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('i18n', ctx.cwd).dir;
+    const sub = ctx.args.subcommand ?? 'check';
+    if (sub === 'add') return runAdd(root, ctx);
+    if (sub === 'sync') return runSync(root, ctx);
+    return runCheck(root);
+  },
+};

package/src/cmd-jobs.ts

@@ -0,0 +1,237 @@
+// `x jobs ls|show|retry|drain` — introspect and recover the job queue, bound to `@ultimat3/jobs`'s
+// own introspection so the CLI, `/_x` and MCP report identically. This file is CLI wiring only:
+// the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
+// `jobs-table.ts`.
+
+import type { JobDriver } from '@ultimat3/jobs';
+import { createMemoryDriver, createNatsDriver, createRedisDriver, jobDriver } from '@ultimat3/jobs';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { startQueue } from './dev-queue';
+import { resolveServices } from './dev-services';
+import { BadFlagError } from './errors';
+import { drainJobs } from './jobs-drain';
+import {
+  deadLetterToJson,
+  depthToJson,
+  drainFailureToJson,
+  drainSkipToJson,
+  jobRecordToJson,
+  jobTraceToJson,
+} from './jobs-json';
+import { listJobs, retryJob, showJob } from './jobs-report';
+import { renderJobTable } from './jobs-table';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool, flagString } from './parse';
+
+export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'drain'] as const;
+
+const DRAIN_TARGETS = ['memory', 'redis', 'nats'] as const;
+
+/**
+ * `x jobs` needs the app's real driver. Reuse an already-running one first — inside `x dev` or
+ * `x mcp serve`, `jobDriver()` is already set and booting a second queue on top of it would talk
+ * to the wrong database. Otherwise boot just the db + jobs half (`startQueue`, not the full
+ * `startServices`: this command touches no transport, storage or mail) and always release it, or
+ * a CLI that exits holding the PGlite lock breaks the next command run against this app.
+ */
+async function withDriver(
+  root: string,
+  ctx: CommandContext,
+  fn: (driver: JobDriver) => Promise<CommandResult>,
+): Promise<CommandResult> {
+  const ambient = jobDriver();
+  if (ambient !== undefined) return fn(ambient);
+  const services = resolveServices(root, ctx.env);
+  const queue = await startQueue(services);
+  try {
+    return await fn(queue.jobs);
+  } finally {
+    await queue.stop();
+  }
+}
+
+function requireIdPositional(ctx: CommandContext, sub: string): string {
+  const id = ctx.args.positionals[0];
+  if (id === undefined) {
+    throw new BadFlagError({
+      flag: 'id',
+      command: 'jobs',
+      reason: `"x jobs ${sub}" needs a job id: x jobs ${sub} <id>`,
+    });
+  }
+  return id;
+}
+
+function requireEnvUrl(env: CommandContext['env'], name: string, target: string): string {
+  const value = env[name];
+  if (value === undefined || value.trim().length === 0) {
+    throw new BadFlagError({
+      flag: 'to',
+      command: 'jobs',
+      reason: `--to ${target} needs ${name} set in the environment`,
+    });
+  }
+  return value;
+}
+
+/**
+ * `redis`/`nats` are honest `X_NOT_IMPLEMENTED` stubs in `@ultimat3/jobs` — building one here is
+ * fine even though every `enqueue` on it will fail; `drainJobs` reports that per record.
+ * Exported so a test can drive the `--to`/env-var validation without a driver or a boot.
+ */
+export function buildDrainTarget(to: string | undefined, env: CommandContext['env']): JobDriver {
+  if (to === undefined || !(DRAIN_TARGETS as readonly string[]).includes(to)) {
+    throw new BadFlagError({
+      flag: 'to',
+      command: 'jobs',
+      reason: `expects one of: ${DRAIN_TARGETS.join(', ')}`,
+    });
+  }
+  if (to === 'memory') return createMemoryDriver();
+  if (to === 'redis') return createRedisDriver({ url: requireEnvUrl(env, 'REDIS_URL', 'redis') });
+  return createNatsDriver({ servers: [requireEnvUrl(env, 'NATS_URL', 'nats')] });
+}
+
+async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const result = await listJobs(driver, {
+    queue: flagString(ctx.args, 'queue'),
+    state: flagString(ctx.args, 'state'),
+    name: flagString(ctx.args, 'name'),
+    limit: flagString(ctx.args, 'limit'),
+  });
+  const lines = [`  ${msg('cli.jobs.listed', { count: result.rows.length })}`];
+  if (result.rows.length > 0) {
+    lines.push(...renderJobTable(result.rows).map((line) => `  ${line}`));
+  }
+  if (result.deadLetters.length > 0) {
+    lines.push(`  ${msg('cli.jobs.deadLetters', { count: result.deadLetters.length })}`);
+    for (const entry of result.deadLetters) {
+      const why = entry.lastError ?? msg('cli.jobs.noError');
+      lines.push(
+        `    ${entry.id}  ${entry.name}  (${entry.queue})  ${why}  — ${entry.retryCommand}`,
+      );
+    }
+  }
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.depth', {
+      ready: result.depth.totals.ready,
+      running: result.depth.totals.running,
+      delayed: result.depth.totals.delayed,
+      dead: result.depth.totals.dead,
+      queues: result.depth.queues.length,
+    }),
+    lines,
+    data: {
+      depth: depthToJson(result.depth),
+      rows: result.rows.map(jobRecordToJson),
+      deadLetters: result.deadLetters.map(deadLetterToJson),
+    },
+  };
+}
+
+async function runShow(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const trace = await showJob(driver, requireIdPositional(ctx, 'show'));
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.shown', {
+      id: trace.id,
+      state: trace.state,
+      attempt: trace.attempt,
+      attempts: trace.maxAttempts,
+    }),
+    data: jobTraceToJson(trace),
+  };
+}
+
+async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const id = requireIdPositional(ctx, 'retry');
+  const trace = await retryJob(driver, id, flagString(ctx.args, 'from-step'));
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.retried', { id: trace.id, state: trace.state }),
+    data: jobTraceToJson(trace),
+  };
+}
+
+/**
+ * A skipped candidate is not an error — a job whose `runAt` has not arrived is unclaimable by
+ * design — so it carries no `X_*` finding. It still fails the command: `x jobs drain` is run to
+ * empty a driver, and a partial move that exited 0 would read as "the queue is clear".
+ */
+async function runDrain(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const target = buildDrainTarget(flagString(ctx.args, 'to'), ctx.env);
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const outcome = await drainJobs(driver, target, dryRun);
+  const findings = outcome.failures.map((failure) => failure.finding);
+  const lines: string[] = [];
+  if (outcome.skipped.length > 0) {
+    const count = outcome.skipped.length;
+    lines.push(`  ${msg('cli.jobs.skipped', { count, from: outcome.from })}`);
+    for (const skip of outcome.skipped) {
+      lines.push(`    ${skip.id}  ${skip.name}  (${skip.queue})  ${skip.state}  ${skip.reason}`);
+    }
+  }
+  const partial = outcome.skipped.length > 0;
+  return {
+    ok: findings.length === 0 && !partial,
+    command: 'jobs',
+    summary: msg(partial ? 'cli.jobs.drainedPartial' : 'cli.jobs.drained', {
+      count: dryRun ? outcome.candidates.length : outcome.moved.length,
+      from: outcome.from,
+      to: outcome.to,
+      skipped: outcome.skipped.length,
+    }),
+    lines,
+    findings,
+    data: {
+      from: outcome.from,
+      to: outcome.to,
+      dryRun: outcome.dryRun,
+      candidates: outcome.candidates.map(jobRecordToJson),
+      moved: outcome.moved.map(jobRecordToJson),
+      skipped: outcome.skipped.map(drainSkipToJson),
+      failures: outcome.failures.map(drainFailureToJson),
+    },
+  };
+}
+
+export const jobsCommand: CliCommand = {
+  spec: {
+    name: 'jobs',
+    summary: 'list, show, retry and drain the job queue',
+    usage:
+      'x jobs [ls|show <id>|retry <id>|drain --to <driver>] [--queue q] [--state s] [--limit n] [--from-step name] [--to driver] [--dry-run] [--json]',
+    requiresApp: true,
+    subcommands: JOBS_SUBCOMMANDS,
+    flags: [
+      { name: 'queue', type: 'string', summary: 'filter by queue name' },
+      { name: 'state', type: 'string', summary: 'filter by job state' },
+      { name: 'limit', type: 'string', summary: 'max rows to return' },
+      { name: 'name', type: 'string', summary: 'filter by job name' },
+      { name: 'from-step', type: 'string', summary: 'retry: drop this step so it re-executes' },
+      { name: 'to', type: 'string', summary: 'drain target driver: memory, redis, nats' },
+      { name: 'dry-run', type: 'boolean', summary: 'drain: report the plan, move nothing' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('jobs', ctx.cwd).dir;
+    const sub = ctx.args.subcommand ?? 'ls';
+    return withDriver(root, ctx, (driver) => {
+      if (sub === 'show') return runShow(driver, ctx);
+      if (sub === 'retry') return runRetry(driver, ctx);
+      if (sub === 'drain') return runDrain(driver, ctx);
+      return runLs(driver, ctx);
+    });
+  },
+};
+
+export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
+export { drainJobs } from './jobs-drain';
+export type { JobsListFilter, JobsListResult } from './jobs-report';
+export { listJobs, retryJob, showJob } from './jobs-report';

package/src/cmd-manifest.ts

@@ -0,0 +1,97 @@
+// `x manifest` — regenerate x.manifest.json and openapi.json from the code. Facts are generated,
+// conventions are hand-written: nothing in this file writes prose, and nothing else in the app is
+// allowed to hand-edit these two files.
+
+import { join } from 'node:path';
+import type { Manifest } from '@ultimat3/manifest';
+import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { appManifest, writeAppManifest } from './app-manifest';
+import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+import { flagBool } from './parse';
+
+const countsOf = (manifest: Manifest): JsonValue => ({
+  routes: manifest.routes.length,
+  actions: manifest.actions.length,
+  mutators: manifest.actions.filter((action) => action.mutator === true).length,
+  queries: manifest.queries.length,
+  jobs: manifest.jobs.length,
+  tasks: manifest.tasks.length,
+  entities: manifest.entities.length,
+  policies: manifest.policies.length,
+});
+
+/**
+ * The identical comparison `x verify`'s `manifest` step makes, through the identical function.
+ * A buildId equality test here would answer "fresh" for a hand-edited file whose body no longer
+ * hashes to the id it carries — and two commands giving two answers about one file is itself the
+ * drift the manifest exists to prevent.
+ */
+async function staleness(root: string, manifest: Manifest): Promise<Finding | undefined> {
+  try {
+    await assertNoDrift({ manifest, path: join(root, MANIFEST_FILENAME) });
+    return undefined;
+  } catch (error) {
+    return { ...findingFrom(error), at: MANIFEST_FILENAME };
+  }
+}
+
+export const manifestCommand: CliCommand = {
+  spec: {
+    name: 'manifest',
+    summary: 'regenerate x.manifest.json and openapi.json from the code',
+    usage: 'x manifest [--check] [--json]',
+    requiresApp: true,
+    flags: [
+      { name: 'check', type: 'boolean', summary: 'fail if the committed files are stale' },
+      { name: 'openapi', type: 'boolean', summary: 'also write openapi.json', default: true },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('manifest', ctx.cwd).dir;
+    const { manifest, findings } = await appManifest(root);
+    const counts = countsOf(manifest);
+
+    if (flagBool(ctx.args, 'check')) {
+      const stale = await staleness(root, manifest);
+      return {
+        ok: stale === undefined && findings.length === 0,
+        command: 'manifest',
+        summary: stale === undefined ? msg('cli.manifest.fresh') : msg('cli.manifest.stale'),
+        findings: stale === undefined ? findings : [...findings, stale],
+        data: { buildId: manifest.buildId, counts },
+      };
+    }
+
+    // A module that would not load is omitted from the registries, so this projection describes a
+    // subset of the app — and `x.manifest.json` is the compatibility contract. Write nothing.
+    if (findings.length > 0) {
+      return {
+        ok: false,
+        command: 'manifest',
+        summary: msg('cli.manifest.blocked', { count: findings.length }),
+        findings,
+        data: { buildId: manifest.buildId, counts },
+      };
+    }
+
+    const path = await writeAppManifest(root, manifest);
+    if (ctx.args.flags.get('openapi') !== false) {
+      await Bun.write(join(root, OPENAPI_FILE), openApiJson(manifest));
+    }
+    return {
+      ok: true,
+      command: 'manifest',
+      summary: msg('cli.manifest.wrote', {
+        path: MANIFEST_FILENAME,
+        routes: manifest.routes.length,
+        actions: manifest.actions.length,
+      }),
+      data: { path, buildId: manifest.buildId, counts },
+    };
+  },
+};