@ultimat3/cli 1.0.0

package/src/cmd-registries.ts

@@ -0,0 +1,195 @@
+// `x actions`, `x queries`, `x entities` — the declaration registries as a table or as JSON.
+// Replaces grepping a source tree, which is what an agent does when the framework has no answer
+// to "what actions/queries/entities exist". One table, one generic command body: the three
+// commands differ only in which registry they read, a row's columns, and (for a query only) the
+// one extra field `describe` surfaces that its descriptor does not already carry.
+
+import type { ActionDescriptor, AnyAction } from '@ultimat3/action';
+import { describeActions, getAction, jsonSchemaOf } from '@ultimat3/action';
+import type { EntityDescription, RegistryEntry } from '@ultimat3/entity';
+import { describeEntities, getEntity } from '@ultimat3/entity';
+import type { AnyQuery, QueryDescriptor } from '@ultimat3/query';
+import { describeQueries, getQuery } from '@ultimat3/query';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, DeclarationUnknownError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import type { CommandSpec } from './parse';
+import { nearest } from './parse';
+import { renderTable } from './table';
+
+/**
+ * A descriptor is plain JSON by construction; only its `unknown`-typed schema fields need this
+ * cast to satisfy `JsonValue` — same idiom as `@ultimat3/manifest`'s `asJson`.
+ */
+const asJson = (value: object): Record<string, JsonValue> => value as Record<string, JsonValue>;
+
+const formatValue = (value: JsonValue): string =>
+  typeof value === 'string' ? value : JSON.stringify(value);
+
+/** One `key: value` line per top-level field — generic across all three descriptor shapes. */
+const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly string[] =>
+  Object.entries(payload).map(([key, value]) => `  ${key}: ${formatValue(value)}`);
+
+/**
+ * One config per registry: how `list` renders a row, and what `describe` adds beyond the
+ * descriptor itself — only a query's input schema does (`QUERIES.extra`); `ActionDescriptor`
+ * already carries `input`/`output`, and an entity has no invocation shape to surface.
+ */
+interface RegistryKind<D extends { readonly name: string }, Raw extends { describe(): D }> {
+  readonly kind: 'actions' | 'queries' | 'entities';
+  readonly singular: string;
+  readonly spec: CommandSpec;
+  readonly header: readonly string[];
+  list(): readonly D[];
+  find(name: string): Raw | undefined;
+  row(item: D): readonly string[];
+  extra(raw: Raw): Readonly<Record<string, JsonValue>>;
+}
+
+const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
+  kind: 'actions',
+  singular: 'action',
+  spec: {
+    name: 'actions',
+    summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
+    usage: 'x actions [list|describe <name>] [--json]',
+    subcommands: ['list', 'describe'],
+    requiresApp: true,
+  },
+  header: ['name', 'verb', 'resource', 'path', 'capability', 'mcp'],
+  list: describeActions,
+  find: getAction,
+  row: (a) => [a.name, a.verb, a.resource, a.path, a.capability, a.mcp.expose ? 'yes' : 'no'],
+  extra: () => ({}),
+};
+
+const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
+  kind: 'queries',
+  singular: 'query',
+  spec: {
+    name: 'queries',
+    summary: 'the query registry: schema, policy, live, cache tags',
+    usage: 'x queries [list|describe <name>] [--json]',
+    subcommands: ['list', 'describe'],
+    requiresApp: true,
+  },
+  header: ['name', 'live', 'capability', 'tags', 'ttlMs'],
+  list: describeQueries,
+  find: getQuery,
+  row: (q) => [
+    q.name,
+    q.live ? 'yes' : 'no',
+    q.capability,
+    q.tags.length === 0 ? '-' : q.tags.join(','),
+    q.ttlMs === null ? '-' : String(q.ttlMs),
+  ],
+  // The descriptor carries no input shape at all; the JSON-schema view of it is cheap and is
+  // exactly what an agent needs before it can call `x dev`'s query endpoint correctly.
+  extra: (raw) => ({ input: asJson(jsonSchemaOf(raw.input)) }),
+};
+
+const ENTITIES: RegistryKind<EntityDescription, RegistryEntry> = {
+  kind: 'entities',
+  singular: 'entity',
+  spec: {
+    name: 'entities',
+    summary: 'the entity registry: columns, invariants, indexes, tenancy',
+    usage: 'x entities [list|describe <name>] [--json]',
+    subcommands: ['list', 'describe'],
+    requiresApp: true,
+  },
+  header: ['name', 'table', 'columns', 'invariants', 'indexes', 'orgScoped'],
+  list: describeEntities,
+  find: getEntity,
+  row: (e) => [
+    e.name,
+    e.table,
+    String(e.columns.length),
+    String(e.invariants.length),
+    String(e.indexes.length),
+    e.orgScoped ? 'yes' : 'no',
+  ],
+  extra: () => ({}),
+};
+
+function listResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
+  kind: RegistryKind<D, Raw>,
+  findings: readonly Finding[],
+): CommandResult {
+  const items = kind.list();
+  return {
+    ok: findings.length === 0,
+    command: kind.kind,
+    summary: msg('cli.registry.count', { count: items.length, kind: kind.kind }),
+    lines:
+      items.length === 0
+        ? []
+        : renderTable(kind.header, items.map(kind.row)).map((line) => `  ${line}`),
+    findings,
+    data: items.map((item) => asJson(item)),
+  };
+}
+
+function describeResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
+  kind: RegistryKind<D, Raw>,
+  ctx: CommandContext,
+  findings: readonly Finding[],
+): CommandResult {
+  const name = ctx.args.positionals[0];
+  if (name === undefined) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: kind.kind,
+      reason: `x ${kind.kind} describe <name> needs a name`,
+      fix: `x ${kind.kind} list --json`,
+    });
+  }
+  const raw = kind.find(name);
+  if (raw === undefined) {
+    const known = kind.list().map((item) => item.name);
+    const suggestion = nearest(name, known);
+    throw new DeclarationUnknownError(
+      suggestion === undefined
+        ? { kind: kind.kind, singular: kind.singular, name, known }
+        : { kind: kind.kind, singular: kind.singular, name, known, suggestion },
+    );
+  }
+  const payload: Record<string, JsonValue> = { ...asJson(raw.describe()), ...kind.extra(raw) };
+  return {
+    ok: findings.length === 0,
+    command: kind.kind,
+    summary: msg('cli.registry.described', { kind: kind.singular, name }),
+    lines: detailLines(payload),
+    findings,
+    data: payload,
+  };
+}
+
+async function runRegistryCommand<
+  D extends { readonly name: string },
+  Raw extends { describe(): D },
+>(kind: RegistryKind<D, Raw>, ctx: CommandContext): Promise<CommandResult> {
+  const root = requireAppRoot(kind.kind, ctx.cwd).dir;
+  const { findings } = await loadApp(root);
+  return ctx.args.subcommand === 'describe'
+    ? describeResult(kind, ctx, findings)
+    : listResult(kind, findings);
+}
+
+export const actionsCommand: CliCommand = {
+  spec: ACTIONS.spec,
+  run: (ctx) => runRegistryCommand(ACTIONS, ctx),
+};
+
+export const queriesCommand: CliCommand = {
+  spec: QUERIES.spec,
+  run: (ctx) => runRegistryCommand(QUERIES, ctx),
+};
+
+export const entitiesCommand: CliCommand = {
+  spec: ENTITIES.spec,
+  run: (ctx) => runRegistryCommand(ENTITIES, ctx),
+};

package/src/cmd-routes.ts

@@ -0,0 +1,73 @@
+// `x routes` — the route table as a table, or as JSON. Replaces grepping a router directory, which
+// is what an agent does when the framework has no answer to "what URLs exist".
+//
+// The rows are `@ultimat3/render`'s own `describeRoutes()`: the CLI prints the route table, it
+// does not keep a second one.
+
+import type { RouteDescriptor } from '@ultimat3/render';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
+
+/** Fixed-width columns so the output diffs cleanly between runs and between machines. */
+export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
+  const rows = routes.map((route) => [
+    route.path,
+    route.surface,
+    route.mode,
+    route.hydrate,
+    route.offline,
+    route.file,
+  ]);
+  const header = ['path', 'surface', 'render', 'hydrate', 'offline', 'file'];
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...rows.map((row) => (row[index] ?? '').length)),
+  );
+  const line = (cells: readonly string[]): string =>
+    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
+  return [line(header), ...rows.map(line)];
+}
+
+const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
+  routes.map((route) => ({
+    path: route.path,
+    surface: route.surface,
+    file: route.file,
+    render: route.mode,
+    hydrate: route.hydrate,
+    offline: route.offline,
+    budget: { js: route.budgetJs, lcp: route.budgetLcp },
+  }));
+
+export const routesCommand: CliCommand = {
+  spec: {
+    name: 'routes',
+    summary: 'the route table: path, surface, render mode, hydrate, offline',
+    usage: 'x routes [--surface site|app] [--json]',
+    requiresApp: true,
+    flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('routes', ctx.cwd).dir;
+    const { findings } = await loadApp(root);
+    const surface = flagString(ctx.args, 'surface');
+    const routes = describeRoutes().filter(
+      (route) => surface === undefined || route.surface === surface,
+    );
+    return {
+      ok: findings.length === 0,
+      command: 'routes',
+      summary:
+        routes.length === 0
+          ? msg('cli.routes.empty')
+          : msg('cli.routes.count', { count: routes.length }),
+      lines: routes.length === 0 ? [] : renderRouteTable(routes).map((line) => `  ${line}`),
+      findings,
+      data: { routes: routeJson(routes) },
+    };
+  },
+};

package/src/cmd-tasks.ts

@@ -0,0 +1,151 @@
+// `x tasks [list|show <name>]` — introspect scheduled cron tasks: cadence, timezone, the jobs
+// each enqueues, and real next-occurrence instants from `@ultimat3/time`'s cron math instead of
+// an agent reading `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in
+// `tasks-facts.ts` — the same split `cmd-jobs.ts` makes against `jobs-report.ts`.
+
+import { systemClock } from '@ultimat3/core';
+import type { TaskHandle } from '@ultimat3/jobs';
+import type { CronPhrases } from '@ultimat3/time';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, DeclarationUnknownError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { flagString, nearest } from './parse';
+import { renderTable } from './table';
+import {
+  findTaskHandle,
+  knownTaskNames,
+  listTaskFacts,
+  parseCountFlag,
+  type TaskFact,
+  taskShowFacts,
+} from './tasks-facts';
+
+const HEADER = ['name', 'cron', 'tz', 'catchUp', 'jobs', 'next'] as const;
+
+/**
+ * The vocabulary `describeCron` interpolates. The cron *math* stays in `tasks-facts.ts` — it is
+ * locale-neutral — but these are words `x tasks show` prints, so they come from the catalog like
+ * every other rendered string. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/`{months}`
+ * intact, which is what makes each value arrive as the template `describeCron` fills in.
+ */
+const cronPhrases = (): CronPhrases => ({
+  everyMinute: msg('cli.cron.everyMinute'),
+  everyNMinutes: msg('cli.cron.everyNMinutes'),
+  everyHour: msg('cli.cron.everyHour'),
+  everyNHours: msg('cli.cron.everyNHours'),
+  at: msg('cli.cron.at'),
+  andMore: msg('cli.cron.andMore'),
+  onDaysOfMonth: msg('cli.cron.onDaysOfMonth'),
+  onWeekdays: msg('cli.cron.onWeekdays'),
+  inMonths: msg('cli.cron.inMonths'),
+  everyDay: msg('cli.cron.everyDay'),
+});
+
+/** A descriptor/fact 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>;
+
+const formatValue = (value: JsonValue): string =>
+  typeof value === 'string' ? value : JSON.stringify(value);
+
+/** One `key: value` line per top-level field — same idiom as `cmd-registries.ts`'s `detailLines`. */
+const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly string[] =>
+  Object.entries(payload).map(([key, value]) => `  ${key}: ${formatValue(value)}`);
+
+const jobsCell = (jobs: readonly string[]): string => (jobs.length === 0 ? '-' : jobs.join(','));
+
+const row = (fact: TaskFact): readonly string[] => [
+  fact.name,
+  fact.cron,
+  fact.tz,
+  fact.catchUp,
+  jobsCell(fact.jobs),
+  fact.next,
+];
+
+function runList(nowMs: number, findings: readonly Finding[]): CommandResult {
+  const facts = listTaskFacts(nowMs);
+  return {
+    ok: findings.length === 0,
+    command: 'tasks',
+    summary: msg('cli.tasks.count', { count: facts.length }),
+    lines: facts.length === 0 ? [] : renderTable(HEADER, facts.map(row)).map((line) => `  ${line}`),
+    findings,
+    data: facts.map((fact) => asJson(fact)),
+  };
+}
+
+/** Resolves the `show <name>` positional to a handle, or throws — the two failure paths named
+ * in the brief: no positional at all, and a positional that names no registered task. */
+function requireHandle(ctx: CommandContext): TaskHandle {
+  const name = ctx.args.positionals[0];
+  if (name === undefined) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'tasks',
+      reason: 'x tasks show <name> needs a task name',
+      fix: 'x tasks list --json',
+    });
+  }
+  const handle = findTaskHandle(name);
+  if (handle !== undefined) return handle;
+  const known = knownTaskNames();
+  const suggestion = nearest(name, known);
+  throw new DeclarationUnknownError(
+    suggestion === undefined
+      ? { kind: 'tasks', singular: 'task', name, known, verb: 'show' }
+      : { kind: 'tasks', singular: 'task', name, known, suggestion, verb: 'show' },
+  );
+}
+
+function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[]): CommandResult {
+  const handle = requireHandle(ctx);
+  const count = parseCountFlag(flagString(ctx.args, 'count'));
+  const { descriptor, describe, upcoming } = taskShowFacts(handle, nowMs, count, cronPhrases());
+  const first = upcoming[0];
+  const lines = [
+    ...detailLines(asJson(descriptor)),
+    `  ${describe}`,
+    ...upcoming.map((occurrence) => `    ${occurrence.at}`),
+  ];
+  return {
+    ok: findings.length === 0,
+    command: 'tasks',
+    summary: msg('cli.tasks.shown', {
+      name: descriptor.name,
+      cron: descriptor.cron,
+      tz: descriptor.tz,
+      next: first === undefined ? '' : first.at,
+    }),
+    lines,
+    findings,
+    data: {
+      ...asJson(descriptor),
+      describe,
+      upcoming: upcoming.map((occurrence) => asJson(occurrence)),
+    },
+  };
+}
+
+export const tasksCommand: CliCommand = {
+  spec: {
+    name: 'tasks',
+    summary: 'cron tasks, their timezone and their next run',
+    usage: 'x tasks [list|show <name>] [--count n] [--json]',
+    requiresApp: true,
+    subcommands: ['list', 'show'],
+    flags: [
+      { name: 'count', type: 'string', summary: 'show: how many upcoming occurrences to list' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('tasks', ctx.cwd).dir;
+    const { findings } = await loadApp(root);
+    const nowMs = systemClock.now().getTime();
+    return ctx.args.subcommand === 'show'
+      ? runShow(ctx, nowMs, findings)
+      : runList(nowMs, findings);
+  },
+};

package/src/cmd-test.ts

@@ -0,0 +1,109 @@
+// `x test`'s command surface: the flags and the one positional it accepts, and the refusals that
+// happen before a single process starts. Which files run is test-select.ts, how they are split and
+// spawned is test-shards.ts — this file only turns argv into their inputs, so a parsing bug can
+// never be read as a sharding one.
+
+// Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
+import { cpus } from 'node:os';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, NoTestFilesError } from './errors';
+import type { CommandResult } from './output';
+import type { ParsedArgs } from './parse';
+import { flagString } from './parse';
+import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
+import { quoteArg, runShards } from './test-shards';
+import type { TestType } from './verify-tests';
+import { TEST_TYPES } from './verify-tests';
+
+/** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
+export function availableCpus(): number {
+  const hinted = typeof navigator === 'undefined' ? Number.NaN : navigator.hardwareConcurrency;
+  return Math.max(1, Number.isFinite(hinted) && hinted > 0 ? Math.trunc(hinted) : cpus().length);
+}
+
+function readIndex(args: ParsedArgs, name: string, min: number): number | undefined {
+  const raw = flagString(args, name);
+  if (raw === undefined) return undefined;
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value < min) {
+    throw new BadFlagError({
+      flag: name,
+      command: 'test',
+      reason: `expects an integer >= ${min}, got "${raw}"`,
+    });
+  }
+  return value;
+}
+
+/**
+ * One positional, and it is the type. `x test contract live` used to run `contract` and drop
+ * `live` on the floor, so a caller reading "contract passed" believed two suites had run. A path
+ * substring is what `--filter` is for, which is what the fix hands back.
+ */
+function readOnlyType(positionals: readonly string[]): TestType | undefined {
+  const [first, second] = positionals;
+  if (second === undefined) return readType(first);
+  const known: readonly string[] = TEST_TYPES;
+  const type = first !== undefined && known.includes(first) ? first : TEST_TYPES[0];
+  throw new BadFlagError({
+    flag: 'type',
+    command: 'test',
+    reason: `takes at most one test type, got ${positionals.length}: ${positionals.join(' ')}`,
+    fix: `x test ${type} --filter ${quoteArg(second)}`,
+  });
+}
+
+export const testCommand: CliCommand = {
+  spec: {
+    name: 'test',
+    summary:
+      'run one test type — or the whole suite — across N processes, one isolated database per worker',
+    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--workers N] [--worker I] [--json]`,
+    flags: [
+      { name: 'workers', type: 'string', summary: 'process count (default: available CPUs)' },
+      {
+        name: 'worker',
+        type: 'string',
+        summary: 'rerun only shard I of the same split — reproduces a CI worker failure locally',
+      },
+      { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
+      {
+        name: 'sample',
+        type: 'string',
+        summary:
+          'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
+      },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const type = readOnlyType(ctx.args.positionals);
+    const filter = flagString(ctx.args, 'filter');
+    const sample = readSample(ctx.args);
+    const discovered = await discoverTests(ctx.cwd, filter, type);
+    if (discovered.length === 0) {
+      throw new NoTestFilesError({ root: ctx.cwd, ...missingSelection(type, filter) });
+    }
+    const files = sample === undefined ? discovered : sampleFiles(discovered, sample);
+    const requested = readIndex(ctx.args, 'workers', 1) ?? availableCpus();
+    const workers = Math.max(1, Math.min(requested, files.length));
+    const only = readIndex(ctx.args, 'worker', 0);
+    if (only !== undefined && only >= workers) {
+      throw new BadFlagError({
+        flag: 'worker',
+        command: 'test',
+        reason: `shard ${only} does not exist in a ${workers}-worker split (0..${workers - 1})`,
+      });
+    }
+    return runShards({
+      root: ctx.cwd,
+      runner: ctx.runner,
+      files,
+      workers,
+      ...(only === undefined ? {} : { only }),
+      ...(filter === undefined ? {} : { filter }),
+      ...(type === undefined ? {} : { type }),
+      // `kept` is the corpus the split saw; a `--worker` rerun must name it, not its own shard.
+      ...(sample === undefined ? {} : { sample: { kept: files.length, total: discovered.length } }),
+    });
+  },
+};