@ultimat3/cli 1.0.0

package/src/parse.ts

@@ -0,0 +1,243 @@
+// Argument parsing for the whole `x` binary — one parser, so every command accepts flags the
+// same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
+// access, so the parser is unit-testable and the dispatcher owns all side effects.
+
+import { BadFlagError, UnknownCommandError } from './errors';
+
+export type FlagValue = string | boolean;
+
+export interface FlagSpec {
+  readonly name: string;
+  readonly type: 'boolean' | 'string';
+  readonly summary: string;
+  readonly short?: string;
+  readonly default?: FlagValue;
+}
+
+export interface CommandSpec {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage: string;
+  readonly aliases?: readonly string[];
+  readonly subcommands?: readonly string[];
+  readonly flags?: readonly FlagSpec[];
+  /** Command needs an app root (`app.config.ts`) — the dispatcher enforces it. */
+  readonly requiresApp?: boolean;
+}
+
+export interface ParsedArgs {
+  readonly command: string;
+  readonly subcommand: string | undefined;
+  readonly positionals: readonly string[];
+  readonly flags: ReadonlyMap<string, FlagValue>;
+  readonly json: boolean;
+  readonly help: boolean;
+  /** Everything after a bare `--`, handed to the underlying tool verbatim. */
+  readonly passthrough: readonly string[];
+}
+
+/** Accepted by every command. `--json` is axiom 4: the feedback loop is machine-readable. */
+export const GLOBAL_FLAGS: readonly FlagSpec[] = [
+  { name: 'json', type: 'boolean', summary: 'machine-readable output', short: 'j' },
+  { name: 'help', type: 'boolean', summary: 'usage for this command', short: 'h' },
+  { name: 'cwd', type: 'string', summary: 'run as if started in this directory' },
+  { name: 'verbose', type: 'boolean', summary: 'include step output on success' },
+];
+
+const HELP_ALIASES = new Set(['--help', '-h', 'help']);
+const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
+
+function distance(a: string, b: string): number {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const grid: number[] = new Array<number>(rows * cols).fill(0);
+  const at = (r: number, c: number): number => grid[r * cols + c] ?? 0;
+  for (let r = 0; r < rows; r += 1) grid[r * cols] = r;
+  for (let c = 0; c < cols; c += 1) grid[c] = c;
+  for (let r = 1; r < rows; r += 1) {
+    for (let c = 1; c < cols; c += 1) {
+      const cost = a[r - 1] === b[c - 1] ? 0 : 1;
+      grid[r * cols + c] = Math.min(at(r - 1, c) + 1, at(r, c - 1) + 1, at(r - 1, c - 1) + cost);
+    }
+  }
+  return at(rows - 1, cols - 1);
+}
+
+/** Nearest known name within an edit distance of 3, so the error can suggest a retry. */
+export function nearest(input: string, candidates: readonly string[]): string | undefined {
+  let best: string | undefined;
+  let bestScore = 4;
+  for (const candidate of candidates) {
+    const score = distance(input, candidate);
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+function resolveCommand(token: string, specs: readonly CommandSpec[]): CommandSpec {
+  const found = specs.find((spec) => spec.name === token || (spec.aliases ?? []).includes(token));
+  if (found !== undefined) return found;
+  const names = specs.map((spec) => spec.name);
+  const suggestion = nearest(token, names);
+  throw new UnknownCommandError(
+    suggestion === undefined
+      ? { path: token, known: names }
+      : { path: token, known: names, suggestion },
+  );
+}
+
+function findFlag(name: string, spec: CommandSpec): FlagSpec | undefined {
+  const all = [...GLOBAL_FLAGS, ...(spec.flags ?? [])];
+  return all.find((flag) => flag.name === name || flag.short === name);
+}
+
+function defaults(spec: CommandSpec): Map<string, FlagValue> {
+  const out = new Map<string, FlagValue>();
+  for (const flag of [...GLOBAL_FLAGS, ...(spec.flags ?? [])]) {
+    if (flag.default !== undefined) out.set(flag.name, flag.default);
+  }
+  return out;
+}
+
+/**
+ * Parse `x` arguments against the command registry. Throws `X_CLI_UNKNOWN_COMMAND` or
+ * `X_CLI_BAD_FLAG` — never returns a partially-valid result, because a command that guesses
+ * what you meant is a command an agent cannot reason about.
+ */
+export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]): ParsedArgs {
+  const tokens = [...argv];
+  const cut = tokens.indexOf('--');
+  const passthrough = cut === -1 ? [] : tokens.splice(cut + 1);
+  if (cut !== -1) tokens.pop();
+
+  if (tokens.length === 0) return blank('help', specs, false);
+  const first = tokens[0] ?? '';
+  // `help` and `version` short-circuit the flag loop below, so `--json` has to be read here or the
+  // two commands silently print prose to an agent that asked for JSON — and every `fix:` naming
+  // `x help --json` would be a command that does not do what it says.
+  const json = tokens.some((token) => token === '--json' || token === '-j');
+  if (VERSION_ALIASES.has(first)) return blank('version', specs, json);
+  if (HELP_ALIASES.has(first)) {
+    const rest = tokens.slice(1).filter((token) => !token.startsWith('-'));
+    return { ...blank('help', specs, json), positionals: rest };
+  }
+
+  const spec = resolveCommand(first, specs);
+  const flags = defaults(spec);
+  const positionals: string[] = [];
+  let index = 1;
+
+  while (index < tokens.length) {
+    const token = tokens[index] ?? '';
+    index += 1;
+    if (!token.startsWith('-') || token === '-') {
+      positionals.push(token);
+      continue;
+    }
+    const negated = token.startsWith('--no-');
+    const raw = negated ? token.slice(5) : token.replace(/^--?/, '');
+    const [name, inlineValue] = splitInline(raw);
+    const flag = findFlag(name, spec);
+    if (flag === undefined) {
+      const known = [...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((entry) => entry.name);
+      const suggestion = nearest(name, known);
+      throw new BadFlagError({
+        flag: name,
+        command: spec.name,
+        reason:
+          suggestion === undefined
+            ? `unknown flag (known: ${known.join(', ')})`
+            : `unknown flag — did you mean --${suggestion}?`,
+      });
+    }
+    if (flag.type === 'boolean') {
+      if (inlineValue !== undefined) {
+        throw new BadFlagError({
+          flag: flag.name,
+          command: spec.name,
+          reason: 'boolean flag takes no value',
+        });
+      }
+      flags.set(flag.name, !negated);
+      continue;
+    }
+    const value = inlineValue ?? tokens[index];
+    if (value === undefined || value.startsWith('--')) {
+      throw new BadFlagError({
+        flag: flag.name,
+        command: spec.name,
+        reason: 'expects a value',
+      });
+    }
+    if (inlineValue === undefined) index += 1;
+    flags.set(flag.name, value);
+  }
+
+  const subcommand = readSubcommand(spec, positionals);
+  return {
+    command: spec.name,
+    subcommand,
+    positionals: subcommand === undefined ? positionals : positionals.slice(1),
+    flags,
+    json: flags.get('json') === true,
+    help: flags.get('help') === true,
+    passthrough,
+  };
+}
+
+function splitInline(raw: string): [string, string | undefined] {
+  const eq = raw.indexOf('=');
+  if (eq === -1) return [raw, undefined];
+  return [raw.slice(0, eq), raw.slice(eq + 1)];
+}
+
+function readSubcommand(spec: CommandSpec, positionals: readonly string[]): string | undefined {
+  const allowed = spec.subcommands;
+  if (allowed === undefined || allowed.length === 0) return undefined;
+  const token = positionals[0];
+  if (token === undefined) return allowed[0];
+  if (allowed.includes(token)) return token;
+  const suggestion = nearest(token, allowed);
+  throw new UnknownCommandError(
+    suggestion === undefined
+      ? { path: `${spec.name} ${token}`, known: allowed }
+      : { path: `${spec.name} ${token}`, known: allowed, suggestion: `${spec.name} ${suggestion}` },
+  );
+}
+
+function blank(command: string, specs: readonly CommandSpec[], json: boolean): ParsedArgs {
+  const spec = specs.find((entry) => entry.name === command);
+  const flags = spec === undefined ? new Map<string, FlagValue>() : defaults(spec);
+  // Set on both, because `flagBool(args, 'json')` and `args.json` are the same fact read two ways.
+  flags.set('json', json);
+  return {
+    command,
+    subcommand: undefined,
+    positionals: [],
+    flags,
+    json,
+    help: false,
+    passthrough: [],
+  };
+}
+
+export function flagString(args: ParsedArgs, name: string): string | undefined {
+  const value = args.flags.get(name);
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function flagBool(args: ParsedArgs, name: string): boolean {
+  return args.flags.get(name) === true;
+}
+
+export function flagList(args: ParsedArgs, name: string): readonly string[] {
+  const value = flagString(args, name);
+  if (value === undefined || value.length === 0) return [];
+  return value
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}

package/src/policy-facts.ts

@@ -0,0 +1,196 @@
+// Pure fact-gathering behind `x policy`: every declared permission projected against the roles
+// that grant it and the declarations that enforce it, plus the per-role allow/deny matrix behind
+// `explain`. No CLI shapes, no `msg()` — testable with real registries and no app to load.
+
+import type { AnyAction } from '@ultimat3/action';
+import { describeActions, getAction } from '@ultimat3/action';
+import type { MatrixRow, Policy } from '@ultimat3/policy';
+import { knownPermissions, policyMatrix, roleDefinitions, rolesGranting } from '@ultimat3/policy';
+import type { AnyQuery } from '@ultimat3/query';
+import { describeQueries, getQuery } from '@ultimat3/query';
+import { devActors } from './dev-policy';
+
+const isDefined = <T>(value: T | undefined): value is T => value !== undefined;
+
+/** Descriptor names whose `capability` is exactly this permission — shared by list and explain. */
+const namesEnforcing = <D extends { readonly name: string; readonly capability: string }>(
+  descriptors: readonly D[],
+  permission: string,
+): readonly string[] =>
+  descriptors.filter((descriptor) => descriptor.capability === permission).map((d) => d.name);
+
+// ── list ──────────────────────────────────────────────────────────────────
+
+export interface PermissionRow {
+  readonly permission: string;
+  readonly roles: readonly string[];
+  readonly actions: readonly string[];
+  readonly queries: readonly string[];
+}
+
+export interface PolicyListFacts {
+  readonly rows: readonly PermissionRow[];
+  readonly roleCount: number;
+  readonly enforcedCount: number;
+  /** Permissions no action or query enforces — a grant that does nothing. */
+  readonly unenforced: readonly string[];
+}
+
+export function listPolicy(): PolicyListFacts {
+  const actionDescriptors = describeActions();
+  const queryDescriptors = describeQueries();
+  const rows = knownPermissions().map(
+    (permission): PermissionRow => ({
+      permission,
+      roles: rolesGranting(permission),
+      actions: namesEnforcing(actionDescriptors, permission),
+      queries: namesEnforcing(queryDescriptors, permission),
+    }),
+  );
+  const unenforced = rows
+    .filter((row) => row.actions.length === 0 && row.queries.length === 0)
+    .map((row) => row.permission);
+  return {
+    rows,
+    roleCount: Object.keys(roleDefinitions()).length,
+    enforcedCount: rows.length - unenforced.length,
+    unenforced,
+  };
+}
+
+// ── explain ───────────────────────────────────────────────────────────────
+
+export type DeclarationKind = 'action' | 'query';
+export type SubjectKind = 'permission' | DeclarationKind;
+
+export interface DeclarationExplanation {
+  readonly name: string;
+  readonly kind: DeclarationKind;
+  readonly capability: string;
+  readonly label: string;
+  /**
+   * Whether this policy can be decided at all outside a request. `false` when evaluating it
+   * with no request input threw — a predicate dereferencing `input.post.id` has nothing to
+   * dereference here — and `rows` is then empty, because a partial matrix reads as a verdict.
+   */
+  readonly decidable: boolean;
+  readonly rows: readonly MatrixRow[];
+}
+
+export interface SubjectExplanation {
+  readonly subject: string;
+  readonly kind: SubjectKind;
+  readonly grantingRoles: readonly string[];
+  readonly declarations: readonly DeclarationExplanation[];
+}
+
+/** The matrix half of a declaration: the rows, and whether they mean anything at all. */
+type DeclarationMatrix = Pick<DeclarationExplanation, 'decidable' | 'rows'>;
+
+/**
+ * One `testActor` per declared role plus the anonymous caller — the same actor set the `/_x`
+ * policy panel asks about (`devActors`, `dev-policy.ts`). Reusing it is the point: a second
+ * "every role plus anonymous" builder here is the duplicate axiom 1 bans, and it would drift
+ * from the panel's own set the first time a role is renamed.
+ *
+ * Actor by actor inside a `try`, because there is no request input outside a request and
+ * `policyMatrix` does not catch: a predicate reading `input.post.id` threw a bare `TypeError`
+ * straight out of `x policy explain`. One throw makes the whole declaration undecidable rather
+ * than half-reported — the rows a synthetic `{}` did produce are not the request's verdicts.
+ * `policyMatrix` stays the only decider; nothing here re-derives one.
+ */
+const matrixFor = (policy: Policy): DeclarationMatrix => {
+  const rows: MatrixRow[] = [];
+  for (const actor of devActors()) {
+    try {
+      rows.push(...policyMatrix(policy, { actors: [actor], input: {} }).rows);
+    } catch {
+      return { decidable: false, rows: [] };
+    }
+  }
+  return { decidable: true, rows };
+};
+
+const explainAction = (action: AnyAction): DeclarationExplanation => {
+  const descriptor = action.describe();
+  return {
+    name: descriptor.name,
+    kind: 'action',
+    capability: descriptor.capability,
+    label: action.policy.label,
+    ...matrixFor(action.policy),
+  };
+};
+
+const explainQuery = (query: AnyQuery): DeclarationExplanation => {
+  const descriptor = query.describe();
+  return {
+    name: descriptor.name,
+    kind: 'query',
+    capability: descriptor.capability,
+    label: query.policy.label,
+    ...matrixFor(query.policy),
+  };
+};
+
+type Resolved =
+  | { readonly kind: 'permission'; readonly permission: string }
+  | { readonly kind: 'action'; readonly action: AnyAction }
+  | { readonly kind: 'query'; readonly query: AnyQuery };
+
+/** Priority order from the brief: a known permission, then an action, a query, an action path. */
+function resolveSubject(name: string): Resolved | undefined {
+  if (knownPermissions().includes(name)) return { kind: 'permission', permission: name };
+  const action = getAction(name);
+  if (action !== undefined) return { kind: 'action', action };
+  const query = getQuery(name);
+  if (query !== undefined) return { kind: 'query', query };
+  const byPath = describeActions().find((descriptor) => descriptor.path === name);
+  const pathAction = byPath === undefined ? undefined : getAction(byPath.name);
+  return pathAction === undefined ? undefined : { kind: 'action', action: pathAction };
+}
+
+/** Every string `x policy explain` accepts — permissions, then action/query names, then paths. */
+export function knownPolicySubjects(): readonly string[] {
+  const actions = describeActions();
+  return [
+    ...knownPermissions(),
+    ...actions.map((descriptor) => descriptor.name),
+    ...describeQueries().map((descriptor) => descriptor.name),
+    ...actions.map((descriptor) => descriptor.path),
+  ];
+}
+
+export function explainPolicy(name: string): SubjectExplanation | undefined {
+  const resolved = resolveSubject(name);
+  if (resolved === undefined) return undefined;
+  if (resolved.kind === 'permission') {
+    const { permission } = resolved;
+    const declarations = [
+      ...describeActions()
+        .filter((descriptor) => descriptor.capability === permission)
+        .map((descriptor) => getAction(descriptor.name))
+        .filter(isDefined)
+        .map(explainAction),
+      ...describeQueries()
+        .filter((descriptor) => descriptor.capability === permission)
+        .map((descriptor) => getQuery(descriptor.name))
+        .filter(isDefined)
+        .map(explainQuery),
+    ];
+    return {
+      subject: name,
+      kind: 'permission',
+      grantingRoles: rolesGranting(permission),
+      declarations,
+    };
+  }
+  const declaration =
+    resolved.kind === 'action' ? explainAction(resolved.action) : explainQuery(resolved.query);
+  return {
+    subject: name,
+    kind: resolved.kind,
+    grantingRoles: rolesGranting(declaration.capability),
+    declarations: [declaration],
+  };
+}

package/src/policy-fixture.ts

@@ -0,0 +1,71 @@
+// The one policy declaration set both `x policy` test files run against. Shared rather than
+// copied, for the reason `thrown-by.ts` gives: every count in both files' assertions is read off
+// THIS set, so a second copy drifts and each file keeps passing while they stop agreeing.
+
+import { action, registerActions, t } from '@ultimat3/action';
+import { and, can, definePermissions, defineRoles } from '@ultimat3/policy';
+import { from, query, registerQuery } from '@ultimat3/query';
+
+/**
+ * The row the fixture's two reads return, over an empty source: `x policy` describes a query and
+ * evaluates its policy, it never executes one, so the rows are the one fact that may be missing.
+ */
+interface PostRow {
+  readonly id: string;
+}
+
+/**
+ * Three permissions, three roles, two actions and two queries — each fact earning its place.
+ *
+ * `post:read` is declared but enforced by nothing: `archivePost`'s policy grants that permission
+ * to its second clause, but the compound policy's own capability is `and(post:publish, post:read)`
+ * — a different string — so `post:read` alone stays unenforced. `post:publish` is enforced by an
+ * action AND a query at once, so the aggregation across declarations has something to aggregate.
+ *
+ * Registers only; the registries are process-global, so the caller clears them first.
+ */
+export function registerPolicyFixture(): void {
+  definePermissions(['post:publish', 'post:read', 'feed:read'] as const);
+  defineRoles({
+    admin: { grants: ['post:publish', 'post:read', 'feed:read'] },
+    editor: { grants: ['post:publish', 'post:read'] },
+    reader: { grants: ['post:read', 'feed:read'] },
+  });
+  registerActions({
+    publishPost: action({
+      input: t.object({}),
+      output: t.object({}),
+      policy: can('post:publish'),
+      async handle() {
+        return {};
+      },
+    }),
+    archivePost: action({
+      input: t.object({}),
+      output: t.object({}),
+      policy: and(
+        can('post:publish'),
+        can('post:read', ({ actor }) => actor?.id === 'admin'),
+      ),
+      async handle() {
+        return {};
+      },
+    }),
+  });
+  registerQuery(
+    'postFeed',
+    query({
+      input: t.object({}),
+      policy: can('feed:read'),
+      sql: () => from<PostRow>('posts', []).orderBy('id').limit(10),
+    }),
+  );
+  registerQuery(
+    'publishedPosts',
+    query({
+      input: t.object({}),
+      policy: can('post:publish'),
+      sql: () => from<PostRow>('posts', []).orderBy('id').limit(10),
+    }),
+  );
+}

package/src/registry.ts

@@ -0,0 +1,73 @@
+// The command registry: the one list the parser, the help catalogue and the dispatcher all read.
+// A command that is not here does not exist — there is no second place to register one.
+
+import { buildCommand } from './cmd-build';
+import { dbCommand } from './cmd-db';
+import { deployCommand } from './cmd-deploy';
+import { devCommand } from './cmd-dev';
+import { doctorCommand } from './cmd-doctor';
+import { errorsCommand } from './cmd-errors';
+import { fixCommand } from './cmd-fix';
+import { generateCommand } from './cmd-generate';
+import { createHelpCommand, createVersionCommand } from './cmd-help';
+import { i18nCommand } from './cmd-i18n';
+import { jobsCommand } from './cmd-jobs';
+import { manifestCommand } from './cmd-manifest';
+import { mcpCommand } from './cmd-mcp';
+import { newCommand } from './cmd-new';
+import { plannedCommands } from './cmd-planned';
+import { policyCommand } from './cmd-policy';
+import { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
+import { routesCommand } from './cmd-routes';
+import { tasksCommand } from './cmd-tasks';
+import { testCommand } from './cmd-test';
+import { verifyCommand } from './cmd-verify';
+import type { CliCommand } from './command';
+import type { CommandSpec } from './parse';
+import { loadVersion } from './version-loader';
+
+/** Single source of truth for the framework version — loaded from root package.json. */
+export const CLI_VERSION = loadVersion();
+
+const CORE: readonly CliCommand[] = [
+  newCommand,
+  devCommand,
+  buildCommand,
+  testCommand,
+  verifyCommand,
+  generateCommand,
+  dbCommand,
+  mcpCommand,
+  doctorCommand,
+  deployCommand,
+  manifestCommand,
+  routesCommand,
+  actionsCommand,
+  queriesCommand,
+  entitiesCommand,
+  jobsCommand,
+  tasksCommand,
+  policyCommand,
+  i18nCommand,
+  errorsCommand,
+  fixCommand,
+];
+
+/**
+ * Planned last, so `x help` reads shipped-first and the tail is honestly labelled. They are in the
+ * registry rather than absent from it because "not built yet" and "not a command" are different
+ * facts, and only one of them is true — see `cmd-planned.ts`.
+ */
+export const COMMANDS: readonly CliCommand[] = [
+  ...CORE,
+  ...plannedCommands(),
+  createHelpCommand(() => SPECS),
+  createVersionCommand(CLI_VERSION),
+];
+
+export const SPECS: readonly CommandSpec[] = COMMANDS.map((command) => command.spec);
+
+export const commandFor = (name: string): CliCommand | undefined =>
+  COMMANDS.find(
+    (command) => command.spec.name === name || (command.spec.aliases ?? []).includes(name),
+  );

package/src/scaffold-fixture.ts

@@ -0,0 +1,69 @@
+// What the scaffold drift gate compiles: every documented `x new` invocation, with every `x g`
+// generator run on top of the one that carries an app. Separate from the compiler harness next to
+// it, because "which scaffolds exist" is a fact about the CLI's surface, not about running `tsc`.
+
+import type { GenerateOptions } from './cmd-generate';
+import { dedupe, generate } from './cmd-generate';
+import { planNewApp } from './cmd-new';
+import type { GeneratedFile } from './templates';
+
+/** The app the fixture scaffolds. Kebab, multi-word: single-word names hide casing bugs. */
+export const FIXTURE_APP = 'ledger-demo';
+
+/**
+ * One realistic invocation of every generator, on top of `x new --example`. Names differ from
+ * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
+ * import, and a fixture that trips over its own naming stops testing the templates.
+ *
+ * `admin: true` on the resource is not decoration: `apps/web/app/<name>/admin/resource.ts` and its
+ * test are templates no other invocation emits, and they cost nothing extra here because they land
+ * in a sandbox that is compiled anyway.
+ */
+export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
+  { kind: 'resource', name: 'invoice', admin: true },
+  { kind: 'entity', name: 'credit-note', feature: 'credit-note' },
+  { kind: 'policy', name: 'credit-note', feature: 'credit-note' },
+  { kind: 'action', name: 'send-invoice', feature: 'invoice' },
+  { kind: 'mutator', name: 'rename-invoice', feature: 'invoice' },
+  { kind: 'query', name: 'invoice-search', feature: 'invoice' },
+  { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
+  { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
+  { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
+  { kind: 'route', name: 'pricing', surface: 'site' },
+  { kind: 'route', name: 'billing', surface: 'app' },
+];
+
+/** The whole scaffolded surface: a new app, then every generator run inside it. */
+export function scaffoldFixture(): readonly GeneratedFile[] {
+  return dedupe([
+    ...planNewApp({ name: FIXTURE_APP, example: true }),
+    ...FIXTURE_GENERATORS.flatMap((options) => generate(options)),
+  ]);
+}
+
+export interface ScaffoldVariant {
+  /** Names the invocation in a failure, so a red gate says which `x new` broke. */
+  readonly name: string;
+  /** What this variant emits that no other one does — why it earns its own compile. */
+  readonly why: string;
+  readonly files: readonly GeneratedFile[];
+}
+
+/**
+ * Every scaffold a user can ask for, each compiled on its own. One variant per *file set*, not per
+ * flag: `--no-example` writes a different `packages/db` than `--example` does, and compiling only
+ * the example app is what let `x new --no-example` ship a `schema.ts` importing a slice that
+ * invocation never writes.
+ */
+export const scaffoldVariants = (): readonly ScaffoldVariant[] => [
+  {
+    name: 'x new',
+    why: 'the example slice, plus one run of every generator on top of it',
+    files: scaffoldFixture(),
+  },
+  {
+    name: 'x new --no-example',
+    why: 'an empty app/: no entity, so schema, seed and the initial migration have nothing to name',
+    files: planNewApp({ name: FIXTURE_APP, example: false }),
+  },
+];