@ultimat3/cli 29.4.0 → 30.0.0

package/src/cmd-exercise.ts

@@ -0,0 +1,129 @@
+// `x exercise [<name>] [--seed n]` — every action, query and job run once against generated rows,
+// with no test written: load the app, read `apps/web/exercise.ts`, run `@ultimat3/testing`'s pass
+// on a scratch database, write `.x/exercise.json`. CLI wiring only: the pass is testing's, the
+// verdict is `exercise-findings.ts`'s, so the gate step and this command read one rule.
+
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import { describeEntities, registeredEntities } from '@ultimat3/entity';
+import { registeredSubjects } from '@ultimat3/jobs';
+import type { NamedActor } from '@ultimat3/policy';
+import type { ExerciseRecord, SeedEntity } from '@ultimat3/testing';
+import {
+  entitySeedWriter,
+  planSweepLines,
+  runExercisePass,
+  tenantFindingLines,
+} from '@ultimat3/testing';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import { exerciseSpec } from './cmd-exercise-spec';
+import type { CliCommand, CommandContext } from './command';
+import { registeredEntityCores } from './db-seed-generate';
+import { devActors } from './dev-policy';
+import { withExerciseDatabase, withExerciseProcess } from './exercise-database';
+import {
+  crashFindingLines,
+  EXERCISE_REPORT_FILE,
+  exerciseFindings,
+  exerciseReport,
+  renderExerciseTable,
+} from './exercise-findings';
+import { readExerciseOverrides } from './exercise-overrides';
+import { entityTenantFindings } from './exercise-static';
+import { subjectFindings, subjectProofFindings } from './exercise-subject';
+import { readIntFlag } from './flag-number';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+
+/**
+ * The actors `x policy explain` evaluates — `devActors()`, the `/_x` panel's own set — each a
+ * member of `tenant`. Never a second "every role" builder: the pass picks among exactly these.
+ */
+export const exerciseRoles = (tenant: string): readonly NamedActor[] =>
+  devActors().map((named) =>
+    named.actor === null ? named : { ...named, actor: { ...named.actor, orgId: tenant } },
+  );
+
+const readSeed = (ctx: CommandContext): number | undefined =>
+  readIntFlag(ctx.args, {
+    name: 'seed',
+    command: 'exercise',
+    min: 0,
+    max: 2_147_483_647,
+    example: 'x exercise --seed 1 --json',
+  });
+
+export const exerciseCommand: CliCommand = {
+  spec: exerciseSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('exercise', ctx.cwd).dir;
+    const seed = readSeed(ctx);
+    return withExerciseProcess(root, ctx.env, () => exercise(ctx, root, seed));
+  },
+};
+
+async function exercise(
+  ctx: CommandContext,
+  root: string,
+  seed: number | undefined,
+): Promise<CommandResult> {
+  const only = ctx.args.positionals[0];
+  const loaded = await loadApp(root);
+  const overrides = await readExerciseOverrides(root);
+  const cores = registeredEntityCores();
+  const entities: readonly SeedEntity[] = Object.values(cores);
+  // Static before any row: a subject whose plan is refused is not proved, it is reported.
+  const subjectStatic =
+    only === undefined ? subjectFindings(registeredSubjects(), registeredEntities()) : [];
+  const proved = registeredSubjects().filter(
+    (subject) => only === undefined && !subjectStatic.some((f) => f.at === subject.entity),
+  );
+  const records: readonly ExerciseRecord[] = await withExerciseDatabase(root, ctx.env, (client) =>
+    runExercisePass({
+      entities,
+      writer: entitySeedWriter({ entities: cores, client }),
+      ...(seed === undefined ? {} : { seed }),
+      ...(overrides === undefined ? {} : { overrides }),
+      ...(only === undefined ? {} : { only }),
+      roles: exerciseRoles,
+    }),
+  );
+  // The subject proof (`exercise-subject.ts`) on a scratch database of its own: the pass's rows
+  // are committed, and a second seed graph beside them collides on every small unique domain.
+  const subjectProofs =
+    proved.length === 0
+      ? []
+      : await withExerciseDatabase(root, ctx.env, (client) =>
+          subjectProofFindings(proved, cores, client),
+        );
+  const report = exerciseReport(records, seed);
+  // The whole pass, not a one-primitive run's slice of it, is what the file is for — but a
+  // one-primitive run is still a fact worth keeping, so it is written either way.
+  await Bun.write(join(root, EXERCISE_REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
+  const findings = [
+    ...loaded.findings,
+    // The static half of the tenant proof (`exercise-static.ts`): the pass's own question,
+    // asked of the declarations before any row is written.
+    ...(only === undefined ? entityTenantFindings(describeEntities()) : []),
+    ...subjectStatic,
+    ...subjectProofs,
+    ...exerciseFindings(records),
+  ];
+  return {
+    ok: findings.length === 0,
+    command: 'exercise',
+    summary:
+      records.length === 0
+        ? msg('cli.exercise.none')
+        : msg('cli.exercise.summary', { ...report.counts, file: EXERCISE_REPORT_FILE }),
+    lines: [
+      ...renderExerciseTable(records),
+      ...tenantFindingLines(records),
+      ...crashFindingLines(records),
+      ...planSweepLines(records),
+    ].map((line) => `  ${line}`),
+    findings,
+    data: report as unknown as JsonValue,
+  };
+}

package/src/cmd-generate-spec.ts

@@ -11,7 +11,8 @@ export const generateSpec: CommandSpec = {
   // Projected from `GENERATORS`, never restated: the literal that used to live here had already
   // drifted — it omitted `backfill` — and a usage line that can disagree with the list it
   // describes is exactly the second source of truth axiom 2 forbids.
-  usage: `x g ${GENERATORS.join('|')} <name> [--feature f]`,
+  // `sign-in` and `chart-alerts` take no `<name>`, so each is spelled once, in its own clause.
+  usage: `x g ${GENERATORS.filter((kind) => kind !== 'sign-in' && kind !== 'chart-alerts').join('|')} <name> [--feature f] · x g sign-in --password|--oidc <provider> · x g chart-alerts [--print]`,
   // Declared from the SAME constant `readKind` validates against: without it `fix-command.ts`
   // has no set to judge the word after `x g`, and two shipped `@ultimat3/admin` fix lines said
   // `x g migration` — a generator that has never existed — straight through the `errors` gate.
@@ -25,6 +26,13 @@ export const generateSpec: CommandSpec = {
     { name: 'locales', type: 'string', summary: 'comma-separated locales, default en' },
     { name: 'at', type: 'string', summary: 'island, admin:page: directory to write into' },
     { name: 'permission', type: 'string', summary: 'admin:page: the permission it needs' },
+    { name: 'oidc', type: 'string', summary: 'sign-in: an OpenID Connect provider id' },
+    { name: 'password', type: 'boolean', summary: 'sign-in: an address and a password' },
+    {
+      name: 'print',
+      type: 'boolean',
+      summary: 'chart-alerts: print plain rule groups, write nothing',
+    },
     { name: 'force', type: 'boolean', summary: 'overwrite existing files' },
     { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
   ],

package/src/cmd-generate.ts

@@ -11,21 +11,25 @@ import { requireAppRoot } from './app-root';
 import { generateSpec } from './cmd-generate-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
-import { localiseCatalogs } from './generate-catalog-locales';
+import { localiseCatalogs, namedOrAppLocales } from './generate-catalog-locales';
+import { refuseChartAlertsFlags, runChartAlerts } from './generate-chart-alerts';
 import { appDisk, plannedDisk } from './generate-disk';
 import { assertFeatureExists } from './generate-feature';
+import { assertSliceToRead } from './generate-feature-required';
 import { generate, sliceDir } from './generate-files';
 import { followUpEdits } from './generate-follow-ups';
+import { formatWritten } from './generate-format-written';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { refusePluralTable } from './generate-plural';
 import { followReexports } from './generate-reexports';
 import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
 import { declaresOnlyOtherEntities } from './generate-sibling';
+import { runSignIn } from './generate-sign-in';
+import { refuseSignInFlags } from './generate-sign-in-mode';
 import { containedPath, planWrites, writeFiles } from './generate-write';
 import { resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
-import { catalogLocales } from './i18n-index';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -68,6 +72,12 @@ export const generateCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('g', ctx.cwd).dir;
     const kind = readKind(ctx.args.positionals[0]);
+    refuseSignInFlags(kind, ctx.args);
+    refuseChartAlertsFlags(kind, ctx.args);
+    // One sign-in per app, named by a flag rather than a `<name>`, and edits no other kind makes.
+    if (kind === 'sign-in') return await runSignIn(ctx, root);
+    // One chart per app, named by its `Chart.yaml`: the same shape, for the same reason.
+    if (kind === 'chart-alerts') return await runChartAlerts(ctx, root);
     const name = readName(ctx.args.positionals[1], kind);
     const featureFlag = readFeature(flagString(ctx.args, 'feature'), kind);
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
@@ -89,7 +99,15 @@ export const generateCommand: CliCommand = {
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
     const slice = sliceDir(surface, kebab(featureFlag ?? name));
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
-    assertFeatureExists(root, kind, featureFlag, slice);
+    assertFeatureExists(root, kind, featureFlag, slice, name);
+    // And a read with no table to read, never handed one (X_FEATURE_REQUIRED).
+    assertSliceToRead(root, {
+      kind,
+      name,
+      feature: featureFlag,
+      slice,
+      flags: reproducedFlags(generateCommand.spec, ctx.args),
+    });
     const sliceErrors = await readSliceErrors(root, kind, slice);
     // And its `policy.ts`, for the same two kinds and the same reason: the action imports from it.
     const slicePolicy = await followReexports(
@@ -162,7 +180,7 @@ export const generateCommand: CliCommand = {
     const force = flagBool(ctx.args, 'force');
     if (flagBool(ctx.args, 'dry-run')) {
       // The write plan, never the bare file list: what the real run would write, skip and refuse.
-      const plan = await planWrites(root, files, force, invocation);
+      const plan = await planWrites(root, files, force, invocation, name);
       const refused = [...plan.conflicts, ...bindings];
       // And the edits OUTSIDE the slice — role map, handle, API index, manifests, catalog index —
       // run for real against the plan held in memory: the same code, so the same list. A dry run
@@ -206,12 +224,15 @@ export const generateCommand: CliCommand = {
     const report =
       bindings.length > 0
         ? { written: [], conflicts: bindings }
-        : await writeFiles(root, files, force, invocation);
+        : await writeFiles(root, files, force, invocation, name);
     // The edits a generated primitive needs outside its own slice, performed rather than left as
     // findings (`generate-follow-ups.ts`). Before the manifest load below, so the projection sees
     // them all — a repo reading a table the handle lacks would not load at all.
     const follow = await followUpEdits(root, report.written, dbModule, appDisk(root));
     const edited = follow.edited;
+    // Before the manifest reads a byte of it. Only what this run created: an edited file is its
+    // author's, and a run that reformatted one would hand them a diff they never asked for.
+    await formatWritten(root, report.written, ctx.runner);
     // Facts, not prose: every `x g` run leaves the route/action/entity/job/policy table current,
     // the same guarantee `x manifest` makes on its own — an agent reading it after `x g` never
     // sees a resource that exists on disk but not in the manifest.
@@ -267,25 +288,6 @@ export const generateCommand: CliCommand = {
   },
 };
 
-/**
- * `--locales` when the caller named any, and otherwise every locale the app already has a catalog
- * for: a key written to `en` alone in an app that also ships `es` renders ⟦key⟧ for every Spanish
- * reader. A stem that is not a locale tag is some other JSON file, and not a catalog to write to.
- */
-async function namedOrAppLocales(
-  root: string,
-  named: readonly string[],
-): Promise<readonly string[]> {
-  if (named.length > 0) return named;
-  return (await catalogLocales(root)).filter((stem) => {
-    try {
-      return Intl.getCanonicalLocales(stem).length === 1;
-    } catch {
-      return false;
-    }
-  });
-}
-
 const isEntityKind = (kind: Generator): boolean => kind === 'entity' || kind === 'resource';
 
 /**
@@ -309,13 +311,16 @@ export function nextSteps(
     'bunx x db migrate',
     // A page that mounts an island has a byte budget only a build can weigh — measured on `x new`'s
     // app (`RESOURCE_PAGE_BUDGET`), and an app that charges more per document is over it on this
-    // run rather than on the next `bin/check`.
+    // run rather than on the next full gate. The step builds itself: the page is newer than the stats.
     ...(written.some((path) => path.endsWith('/page.tsx')) ? [MEASURE_PAGE] : []),
   ];
 }
 
-/** The two commands that weigh a page against its budget: the build writes the bytes it reads. */
-export const MEASURE_PAGE = 'bunx x build --target static && bunx x verify --only budgets';
+/**
+ * The command that weighs a page against its budget. One command: `budgets` runs the static build
+ * itself when the stats are older than the source, and a just-written page is (plan 101, 21).
+ */
+export const MEASURE_PAGE = 'bunx x verify --only budgets';
 
 /** The frame `x new` writes: a resource's page renders inside it when the app has one. */
 export const SHELL_MODULE = 'apps/web/shared/shell.tsx';

package/src/cmd-graph-load.ts

@@ -0,0 +1,97 @@
+// The app graph `x graph`, `x impact` and the dev MCP server's `graph.query` read: the app loaded
+// once (`appManifest`), its module graph scanned, and the last `x exercise` run's effects added as
+// `observed` edges. Rebuilt per call — a graph committed anywhere would churn on every import.
+
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import type { AppGraph, ObservedEdge } from '@ultimat3/manifest';
+import { buildGraph, findNode, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { appManifest } from './app-manifest';
+import { moduleFiles, primitiveFiles } from './app-module-graph';
+import type { Finding } from './output';
+
+/** Where `x exercise` writes what each primitive did. */
+export const EXERCISE_REPORT = '.x/exercise.json';
+
+interface ExerciseRecord {
+  readonly kind?: unknown;
+  readonly name?: unknown;
+  readonly effects?: unknown;
+}
+
+/**
+ * `.x/exercise.json` as edges: a primitive that wrote or read an entity's table, or enqueued a
+ * job. Ignored when it is older than `x.manifest.json` — the run described an earlier app — or
+ * unreadable: observed edges are a bonus over declared ones, never a requirement.
+ */
+export async function observedEdges(
+  root: string,
+  tables: ReadonlyMap<string, string>,
+): Promise<readonly ObservedEdge[]> {
+  const report = Bun.file(join(root, EXERCISE_REPORT));
+  const manifest = Bun.file(join(root, MANIFEST_FILENAME));
+  if (!(await report.exists())) return [];
+  if ((await manifest.exists()) && report.lastModified < manifest.lastModified) return [];
+  let parsed: unknown;
+  try {
+    parsed = await report.json();
+  } catch {
+    // A torn write from a run still in progress: no observed edges this time.
+    return [];
+  }
+  const records = (parsed as { readonly records?: unknown }).records;
+  if (!Array.isArray(records)) return [];
+  const edges: ObservedEdge[] = [];
+  for (const record of records as readonly ExerciseRecord[]) {
+    if (typeof record.kind !== 'string' || typeof record.name !== 'string') continue;
+    const from = `${record.kind}:${record.name}`;
+    for (const effect of Array.isArray(record.effects) ? record.effects : []) {
+      const { kind, entity, op, job } = effect as Readonly<Record<string, unknown>>;
+      if (kind === 'row' && typeof entity === 'string') {
+        const to = `entity:${tables.get(entity) ?? entity}`;
+        edges.push({ from, to, rel: op === 'select' ? 'reads' : 'writes' });
+      } else if (kind === 'enqueue' && typeof job === 'string') {
+        edges.push({ from, to: `job:${job}`, rel: 'enqueues' });
+      }
+    }
+  }
+  return edges;
+}
+
+export interface LoadedGraph {
+  readonly graph: AppGraph;
+  /** Modules that would not load: the graph describes what did. */
+  readonly findings: readonly Finding[];
+}
+
+export async function loadAppGraph(root: string): Promise<LoadedGraph> {
+  const { manifest, findings } = await appManifest(root);
+  const files = await moduleFiles(root);
+  const primitives = await primitiveFiles(
+    root,
+    files.map((file) => file.path),
+  );
+  const tables = new Map(manifest.entities.map((entity) => [entity.table, entity.name]));
+  const graph = buildGraph(manifest, { files, primitives }, await observedEdges(root, tables));
+  return { graph, findings };
+}
+
+/** A name that is no node of the graph, with the three nearest to pick from. */
+export class GraphNodeUnknownError extends UltimateError {
+  constructor(input: { readonly asked: string; readonly candidates: readonly string[] }) {
+    super({
+      code: 'X_GRAPH_NODE_UNKNOWN',
+      cause: `${renderCauseValue(input.asked)} is no node of the app graph (nearest: ${input.candidates.join(', ') || 'none'})`,
+      fix: 'x graph --json   # every node id is in data.nodes; pass one of them, a primitive name or a file path',
+      meta: { asked: input.asked, candidates: [...input.candidates] },
+    });
+  }
+}
+
+/** The node `text` names, or the refusal listing the nearest three. */
+export function resolveNode(graph: AppGraph, text: string): string {
+  const { id, candidates } = findNode(graph, text.replace(/^\.\//, ''));
+  if (id === undefined) throw new GraphNodeUnknownError({ asked: text, candidates });
+  return id;
+}

package/src/cmd-graph-spec.ts

@@ -0,0 +1,16 @@
+// `x graph`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-graph.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const graphSpec: CommandSpec = {
+  name: 'graph',
+  summary:
+    'the app as one typed graph: routes, primitives, tags, MCP tools, files and tests, each edge with its provenance',
+  usage: 'x graph [--from <node> --to <node>] [--json]',
+  requiresApp: true,
+  flags: [
+    { name: 'from', type: 'string', summary: 'a node id, primitive name or file path to start at' },
+    { name: 'to', type: 'string', summary: 'the node to explain a link to; needs --from' },
+  ],
+};

package/src/cmd-graph.ts

@@ -0,0 +1,73 @@
+// `x graph` — the app as one typed graph, or with `--from`/`--to` the chain of edges linking two
+// nodes. CLI wiring only: the graph is `@ultimat3/manifest`'s `buildGraph`, loaded by
+// `cmd-graph-load.ts`.
+
+import type { GraphNodeKind } from '@ultimat3/manifest';
+import { GRAPH_NODE_KINDS, pathBetween } from '@ultimat3/manifest';
+import { requireAppRoot } from './app-root';
+import { loadAppGraph, resolveNode } from './cmd-graph-load';
+import { graphSpec } from './cmd-graph-spec';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
+
+const asJson = (value: unknown): JsonValue => JSON.parse(JSON.stringify(value)) as JsonValue;
+
+export const graphCommand: CliCommand = {
+  spec: graphSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('graph', ctx.cwd).dir;
+    const from = flagString(ctx.args, 'from');
+    const to = flagString(ctx.args, 'to');
+    if ((from === undefined) !== (to === undefined)) {
+      throw new BadFlagError({
+        flag: from === undefined ? 'from' : 'to',
+        command: 'graph',
+        reason: '--from and --to name the two ends of one path, so each needs the other',
+        fix: 'x graph --from query:postById --to entity:posts --json',
+      });
+    }
+    const { graph, findings } = await loadAppGraph(root);
+    if (from !== undefined && to !== undefined) {
+      const path = pathBetween(graph, resolveNode(graph, from), resolveNode(graph, to));
+      return {
+        ok: true,
+        command: 'graph',
+        summary:
+          path.edges === null
+            ? msg('cli.graph.noPath', {
+                from: path.from,
+                to: path.to,
+                searched: path.searched.join(', '),
+              })
+            : msg('cli.graph.path', { from: path.from, to: path.to, steps: path.edges.length }),
+        lines: (path.edges ?? []).map((edge) =>
+          msg('cli.graph.pathStep', { ...edge, provenance: edge.provenance }),
+        ),
+        data: asJson(path),
+      };
+    }
+    const count = (kind: GraphNodeKind): number =>
+      graph.nodes.filter((n) => n.kind === kind).length;
+    const provenance = [...new Set(graph.edges.map((edge) => edge.provenance))].sort();
+    return {
+      ok: true,
+      command: 'graph',
+      summary: msg('cli.graph.summary', {
+        nodes: graph.nodes.length,
+        edges: graph.edges.length,
+        provenance: provenance.join(', '),
+        opaque: graph.opaque.length,
+      }),
+      lines: [
+        ...GRAPH_NODE_KINDS.filter((kind) => count(kind) > 0).map((kind) =>
+          msg('cli.graph.kind', { kind, count: count(kind) }),
+        ),
+        ...findings.map((finding) => `  ${finding.code} ${finding.at ?? ''}`),
+      ],
+      data: asJson(graph),
+    };
+  },
+};

package/src/cmd-i18n.ts

@@ -260,7 +260,10 @@ async function untranslatedKeys(
   locale: string,
 ): Promise<readonly string[]> {
   const extraction = await scanSource(root);
-  const report = withPlaceholdersMissing(auditCatalogs({ extraction, catalogs }), catalogs);
+  // `reference` as `auditApp` passes it: an app whose default is not `en` is told to sync its default
+  // over a key `en` holds alone, and this list is all that command can add.
+  const audit = auditCatalogs({ extraction, catalogs, reference: DEFAULT_LOCALE });
+  const report = withPlaceholdersMissing(audit, catalogs);
   return report.locales.find((audit) => audit.locale === locale)?.missing ?? [];
 }
 

package/src/cmd-impact-spec.ts

@@ -0,0 +1,13 @@
+// `x impact`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-impact.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const impactSpec: CommandSpec = {
+  name: 'impact',
+  summary:
+    'what an edit to a file, primitive or entity reaches: routes, actions, queries, jobs, MCP tools, published operations, tests, budgets',
+  usage: 'x impact <file|primitive|entity> [--json]',
+  requiresApp: true,
+  flags: [],
+};

package/src/cmd-impact.ts

@@ -0,0 +1,64 @@
+// `x impact <file|primitive|entity>` — what an edit reaches, before it is made: routes, actions,
+// queries, jobs, MCP tools, published operations, tests and budgets, each with the provenance of
+// the edges that reached it. The question an agent asks before an edit, answered in one call.
+
+// why: Bun ships no path API; a path argument is relative to where the command ran.
+import { join } from 'node:path';
+import type { Impact, ImpactEntry } from '@ultimat3/manifest';
+import { impactOf } from '@ultimat3/manifest';
+import { requireAppRoot } from './app-root';
+import { loadAppGraph, resolveNode } from './cmd-graph-load';
+import { impactSpec } from './cmd-impact-spec';
+import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { posixRelative } from './posix-path';
+
+const SECTIONS = ['routes', 'actions', 'queries', 'jobs', 'mcpTools', 'tests', 'budgets'] as const;
+
+const names = (entries: readonly ImpactEntry[]): string =>
+  entries.map((entry) => `${entry.name} [${entry.provenance.join('+')}]`).join(', ');
+
+const render = (impact: Impact): readonly string[] => [
+  ...(impact.publishedOperations.length === 0
+    ? []
+    : [msg('cli.impact.published', { operations: names(impact.publishedOperations) })]),
+  ...SECTIONS.filter((section) => impact[section].length > 0).map((section) =>
+    msg('cli.impact.section', { section, names: names(impact[section]) }),
+  ),
+];
+
+export const impactCommand: CliCommand = {
+  spec: impactSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('impact', ctx.cwd).dir;
+    const asked = ctx.args.positionals[0];
+    if (asked === undefined) {
+      throw new MissingPositionalError({
+        command: 'impact',
+        positional: 'file|primitive|entity',
+        example: 'x impact apps/web/app/posts/queries/post-by-id.ts --json',
+      });
+    }
+    const { graph } = await loadAppGraph(root);
+    // A path is read from where the command ran, and the graph keys files from the app root.
+    const onDisk = join(ctx.cwd, asked);
+    const named = (await Bun.file(onDisk).exists()) ? posixRelative(root, onDisk) : asked;
+    const impact = impactOf(graph, resolveNode(graph, named));
+    return {
+      ok: true,
+      command: 'impact',
+      summary: msg('cli.impact.summary', {
+        node: impact.node,
+        routes: impact.routes.length,
+        actions: impact.actions.length,
+        queries: impact.queries.length,
+        jobs: impact.jobs.length,
+        tests: impact.tests.length,
+      }),
+      lines: render(impact),
+      data: JSON.parse(JSON.stringify(impact)) as JsonValue,
+    };
+  },
+};

package/src/cmd-jobs-resolve.ts

@@ -0,0 +1,76 @@
+// `x jobs resolve-step <id> <step> --ran [--output <json>] | --not-ran` — a person's answer to
+// `X_STEP_OUTCOME_UNKNOWN`: a `once` step that started and never completed either happened (its
+// output is recorded, a replay returns it) or did not (`cleared`, the next run calls it again).
+// Then `x jobs retry <id>`. Split from `cmd-jobs.ts`, which is the dispatch.
+
+import type { JobDriver, StepResolution } from '@ultimat3/jobs';
+import { resolveJobStep } from '@ultimat3/jobs';
+import type { CommandContext } from './command';
+import { BadFlagError, MissingPositionalError } from './errors';
+import { jobTraceToJson } from './jobs-json';
+import { showJob } from './jobs-report';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool, flagString } from './parse';
+
+const EXAMPLE = "x jobs resolve-step <id> <step> --ran --output '{}' --json";
+
+/** Exactly one of `--ran` and `--not-ran`; `--output` is JSON, and only with `--ran`. */
+function resolutionOf(ctx: CommandContext): StepResolution {
+  const ran = flagBool(ctx.args, 'ran');
+  const notRan = flagBool(ctx.args, 'not-ran');
+  const output = flagString(ctx.args, 'output');
+  if (ran === notRan) {
+    throw new BadFlagError({
+      flag: ran ? 'not-ran' : 'ran',
+      command: 'jobs resolve-step',
+      reason: 'say whether the step ran: pass exactly one of --ran and --not-ran',
+      fix: EXAMPLE,
+    });
+  }
+  if (notRan) {
+    if (output !== undefined) {
+      throw new BadFlagError({
+        flag: 'output',
+        command: 'jobs resolve-step',
+        reason: 'a step that did not run has no output to record',
+        fix: 'x jobs resolve-step <id> <step> --not-ran --json',
+      });
+    }
+    return { ran: false };
+  }
+  if (output === undefined) return { ran: true, output: null };
+  try {
+    return { ran: true, output: JSON.parse(output) as unknown };
+  } catch {
+    throw new BadFlagError({
+      flag: 'output',
+      command: 'jobs resolve-step',
+      reason: 'the output is not JSON — it is what a replay of the step will return',
+      fix: EXAMPLE,
+    });
+  }
+}
+
+export async function runResolveStep(
+  driver: JobDriver,
+  ctx: CommandContext,
+  id: string,
+): Promise<CommandResult> {
+  const step = ctx.args.positionals[1];
+  if (step === undefined) {
+    throw new MissingPositionalError({
+      command: 'jobs resolve-step',
+      positional: 'step',
+      example: `x jobs show ${id} --json`,
+    });
+  }
+  const resolved = await resolveJobStep(driver, id, step, resolutionOf(ctx));
+  const trace = await showJob(driver, id);
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.stepResolved', { id, step, status: resolved.status }),
+    data: jobTraceToJson(trace),
+  };
+}