@ultimat3/cli 29.4.0 → 30.1.0

package/src/exercise-registration.ts

@@ -0,0 +1,58 @@
+// A generator's entries in `apps/web/exercise.ts`: what `x g sign-in` writes that the exercise pass
+// cannot run as generated, each turned off with its reason, so the app's next `x verify` is green.
+// An entry the app already declares is the app's and is never touched.
+
+import { exerciseFiles } from './templates/scaffold-exercise';
+
+export const EXERCISE_FILE = 'apps/web/exercise.ts';
+
+/**
+ * The password sign-in's two actions the pass cannot drive, by the file that declares each. One line
+ * each in the app's file, inside Biome's 100 columns: `login()` refuses the drawn address and password.
+ */
+const SIGN_IN_OFF: ReadonlyMap<string, readonly [string, string]> = new Map([
+  [
+    'apps/web/app/auth/actions/create-session.ts',
+    ['createSession', 'needs a real password; the pass draws one no account holds'],
+  ],
+  [
+    'apps/web/app/auth/actions/confirm-session.ts',
+    ['confirmSession', 'answers the challenge createSession holds; the pass holds none'],
+  ],
+]);
+
+/** The `off` entries the written files are owed, by primitive name. */
+export const signInExerciseEntries = (
+  written: readonly string[],
+): readonly (readonly [string, string])[] =>
+  written.flatMap((path) => {
+    const entry = SIGN_IN_OFF.get(path);
+    return entry === undefined ? [] : [entry];
+  });
+
+const DEFINE = 'defineExercise({';
+
+/**
+ * `source` with each entry not already named in it inserted at the top of `defineExercise({ … })`;
+ * `undefined` when there is no file, which starts from `x new`'s. A file with no `defineExercise({`
+ * is the app's own shape and is left as it is.
+ */
+export function exerciseWithEntries(
+  source: string | undefined,
+  entries: readonly (readonly [string, string])[],
+): string {
+  const base = source ?? String(exerciseFiles()[0]?.contents ?? '');
+  const at = base.indexOf(DEFINE);
+  if (at === -1) return base;
+  const missing = entries.filter(([name]) => !new RegExp(`\\b${name}\\s*:`).test(base));
+  if (missing.length === 0) return base;
+  const lines = missing.map(([name, why]) => `  ${name}: { off: ${singleQuoted(why)} },`);
+  const after = at + DEFINE.length;
+  // `defineExercise({})` — the scaffold's — opens onto its own close: the close gets its own line.
+  const rest = base.slice(after);
+  return `${base.slice(0, after)}\n${lines.join('\n')}${rest.startsWith('}') ? '\n' : ''}${rest}`;
+}
+
+/** A single-quoted TypeScript string literal, Biome's own quote style. */
+const singleQuoted = (text: string): string =>
+  `'${text.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;

package/src/exercise-static.ts

@@ -0,0 +1,88 @@
+// The static half of the tenant proof, under the `exercise` step: an entity with no tenant column
+// whose references reach one that has a tenant, and no `shared` reason, is a row of one tenant
+// readable by id from another — the guard scopes only tables that carry the column. Pure:
+// descriptions in, findings out (the tenant columns default to the registry's own projection).
+
+import type { EntityDescription, TenantColumnDescription } from '@ultimat3/entity';
+import { describeTenancy } from '@ultimat3/entity';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** `"<table>.<column>"` → the table. Physical names hold no `.`, so the first one splits it. */
+const targetTable = (reference: string): string => reference.slice(0, reference.indexOf('.'));
+
+/**
+ * The tenant ROOTS: each table a tenant column of `entities` references (`orgs`, for
+ * `orgId -> orgs.id`). It carries no tenant column because it IS the tenant — `seedGraph` holds one
+ * row of it per tenant (`seed-graph.ts`'s `roots`, the same rule over entity objects).
+ */
+const tenantRoots = (
+  byTable: ReadonlyMap<string, EntityDescription>,
+  tenancy: readonly TenantColumnDescription[],
+): ReadonlySet<string> => {
+  const roots = new Set<string>();
+  for (const { table, column } of tenancy) {
+    const reference = byTable.get(table)?.columns.find((c) => c.column === column)?.references;
+    if (reference === null || reference === undefined) continue;
+    if (targetTable(reference) !== table) roots.add(targetTable(reference));
+  }
+  return roots;
+};
+
+/**
+ * The shortest reference path from `start` to a tenant-columned entity or a tenant root, or
+ * `null`. A `shared` entity is not walked through: its rows belong to no tenant by declaration, so
+ * what hangs off it hangs off a global row. Either kind of tenant ends the walk, found.
+ */
+const pathToTenant = (
+  start: EntityDescription,
+  byTable: ReadonlyMap<string, EntityDescription>,
+  roots: ReadonlySet<string>,
+): readonly string[] | null => {
+  const seen = new Set([start.table]);
+  const queue: (readonly EntityDescription[])[] = [[start]];
+  for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+    const here = path[path.length - 1];
+    for (const column of here?.columns ?? []) {
+      if (column.references === null) continue;
+      const next = byTable.get(targetTable(column.references));
+      if (next === undefined || seen.has(next.table)) continue;
+      seen.add(next.table);
+      if (next.orgScoped || roots.has(next.table)) {
+        return [...path, next].map((entity) => entity.name);
+      }
+      if (next.shared === undefined) queue.push([...path, next]);
+    }
+  }
+  return null;
+};
+
+const finding = (entity: EntityDescription, path: readonly string[], root: boolean): Finding => ({
+  code: 'X_ENTITY_TENANT_UNDECLARED',
+  cause: `${entity.name} has no tenant column and references ${path.join(' -> ')}, ${root ? 'the tenant root' : 'which has one'}, and declares no shared reason: a row of one tenant is readable by id from another. Add a tenant column to its columns, or declare why it belongs to no tenant`,
+  fix: `orgId: uuid().tenant()   # in entity('${entity.name}', { columns }), then x db gen ${quoteArg(`${entity.table} tenant`)}; or shared: '<why it belongs to no tenant>' in that entity()`,
+  // The registry records no declaring file, so the entity's name is the locator.
+  at: entity.name,
+});
+
+/**
+ * `tenancy` is which column scopes each tenant table — the description does not say — and only
+ * rows naming a table in `entities` count, so a registered entity outside the set roots nothing.
+ */
+export function entityTenantFindings(
+  entities: readonly EntityDescription[],
+  tenancy: readonly TenantColumnDescription[] = describeTenancy(),
+): readonly Finding[] {
+  const byTable = new Map(entities.map((entity) => [entity.table, entity]));
+  const roots = tenantRoots(byTable, tenancy);
+  const byName = new Map(entities.map((entity) => [entity.name, entity]));
+  return [...entities]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .flatMap((entity) => {
+      if (entity.orgScoped || entity.shared !== undefined || roots.has(entity.table)) return [];
+      const path = pathToTenant(entity, byTable, roots);
+      if (path === null) return [];
+      const end = byName.get(path[path.length - 1] ?? '');
+      return [finding(entity, path, end !== undefined && !end.orgScoped)];
+    });
+}

package/src/exercise-subject.ts

@@ -0,0 +1,69 @@
+// The subject proof under the `exercise` step. Static: every `defineSubject()` planned against
+// every registered entity — a table keyed to the subject with no treatment is
+// `X_SUBJECT_TABLE_UNDECLARED` naming it, so "you forgot last month's table" is a red gate.
+// Dynamic: `subjectProof` erases one generated person and searches every table for them.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { identifier, sql } from '@ultimat3/db';
+import type { EntityCore, RegistryEntry } from '@ultimat3/entity';
+import type { Subject } from '@ultimat3/jobs';
+import { planSubject } from '@ultimat3/jobs';
+import { entitySeedWriter, subjectProof } from '@ultimat3/testing';
+import type { Finding } from './output';
+
+export function subjectFindings(
+  subjects: readonly Subject<never>[],
+  entries: readonly RegistryEntry[],
+): readonly Finding[] {
+  return subjects.flatMap((subject) =>
+    planSubject({
+      subject: subject.entity,
+      tables: subject.init.tables,
+      columns: subject.init.columns,
+      entries,
+    }).problems.flatMap((problem): Finding[] =>
+      isUltimateError(problem)
+        ? [{ code: problem.code, cause: problem.cause, fix: problem.fix, at: subject.entity }]
+        : [],
+    ),
+  );
+}
+
+/**
+ * The dynamic half: each declared subject erased on its own generated graph, on the pass's scratch
+ * database, and every table searched (`subjectProof`). A seed of its own, so the proof's rows never
+ * collide with the pass's.
+ */
+export async function subjectProofFindings(
+  subjects: readonly Subject<never>[],
+  cores: Readonly<Record<string, EntityCore>>,
+  client: DbClient,
+): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for (const [index, subject] of subjects.entries()) {
+    // A plan the static half refused is reported there, once; an erase that throws is a finding.
+    const problems = await subjectProof(subject, {
+      entities: Object.values(cores),
+      writer: entitySeedWriter({ entities: cores, client }),
+      read: (entity) =>
+        client.query<Record<string, unknown>>(sql`select * from ${identifier(entity.$table)}`),
+      seed: SUBJECT_PROOF_SEED + index,
+    }).then(
+      (result) => result.problems.filter((p) => p.code === 'X_SUBJECT_ERASE_INCOMPLETE'),
+      (error: unknown) => (isUltimateError(error) ? [error] : Promise.reject(error)),
+    );
+    for (const problem of problems) {
+      findings.push({
+        code: problem.code,
+        cause: problem.cause,
+        fix: problem.fix,
+        at: subject.entity,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Far from the small seeds a developer passes to `x exercise --seed`. */
+const SUBJECT_PROOF_SEED = 0x5ab1ec7;

package/src/failure-capture-boot.ts

@@ -0,0 +1,30 @@
+// Single responsibility: arming failure capture for a booted role. `failureCapture.enabled` in
+// `app.config.ts` installs the Postgres bundle store (`x_failures`, applied by the boot's framework
+// schema); `x dev` arms it whatever the file says. Off, nothing is installed and `invoke` runs bare.
+
+import type { AppConfig } from '@ultimat3/core';
+import { FAILURE_CAPTURE_DEFAULTS, setFailureStore, settleFailureCaptures } from '@ultimat3/core';
+import { postgresFailureStore } from '@ultimat3/db';
+
+export interface ArmFailureCaptureOptions {
+  /** `x dev`: on whatever `app.config.ts` says — a development process's input is the developer's. */
+  readonly force?: boolean | undefined;
+}
+
+/** Install the store when capture is on; answer the undo, which settles in-flight saves first. */
+export function armFailureCapture(
+  config: AppConfig | undefined,
+  options: ArmFailureCaptureOptions = {},
+): () => Promise<void> {
+  const block = config?.failureCapture ?? FAILURE_CAPTURE_DEFAULTS;
+  if (!block.enabled && options.force !== true) return async () => undefined;
+  const previous = setFailureStore(postgresFailureStore(), {
+    perHour: block.perHour,
+    maxRows: block.maxRows,
+    maxBytes: block.maxBytes,
+  });
+  return async () => {
+    await settleFailureCaptures();
+    setFailureStore(previous);
+  };
+}

package/src/framework-env.ts

@@ -43,6 +43,12 @@ export const namedDeployed = (env: EnvTable): boolean => {
   return environment === 'staging' || environment === 'production';
 };
 
+/** Does `env` name no environment? The boot then reads it as production, and `x env check` says so. */
+export const namesNoEnvironment = (env: EnvTable): boolean =>
+  // Core's reading, twice: only a table that names nothing answers with whichever fallback it got.
+  tryResolveEnvironment({ env, fallback: 'production' }) !==
+  tryResolveEnvironment({ env, fallback: 'development' });
+
 /**
  * What the app's `app.config.ts` decides about which framework keys it owes — read by the caller,
  * which has the root (`appSecretFacts`). `x doctor` asks of no config and passes `NO_APP_FACTS`.
@@ -99,7 +105,7 @@ export const FRAMEWORK_SECRETS: readonly FrameworkSecret[] = [
     why: 'Signs upload grants on the embedded disk. Unset, every role refuses to boot (X_ENV_MISSING).',
     condition: 'Not read when S3_ENDPOINT and S3_BUCKET select object storage.',
     cause: `${STORAGE_SIGNING_SECRET_KEY} is unset or holds the shipped development key, so a local-disk deploy would accept forged upload grants that override its own uploadPolicy`,
-    fix: `export ${STORAGE_SIGNING_SECRET_KEY}="$(openssl rand -hex 32)"`,
+    fix: `openssl rand -hex 32   # put the output in this deploy's secret store as ${STORAGE_SIGNING_SECRET_KEY}; this machine: ULTIMATE_ENV=development x env check`,
     // The boot's own storage choice (`runtime-bindings.ts`), never restated. NOT "the app declares
     // no storage": the boot builds its disk before any app module loads, and an app reaches it
     // through a bare `disk()` with no `defineStorage` of its own

package/src/framework-schema.ts

@@ -6,16 +6,31 @@
 // A framework table an app has to install by hand is a table that will be missing in production on
 // the one code path that needs it, and it surfaces as a Postgres `42P01` from inside a worker.
 
-import { SQL_AUDIT_TABLE, SQL_IDEMPOTENCY_TABLE } from '@ultimat3/action';
-import { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from '@ultimat3/admin/schema';
-import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
+import { SQL_AUDIT_TABLE, SQL_IDEMPOTENCY_TABLE, SQL_METER_TABLE } from '@ultimat3/action';
+import {
+  ADMIN_AUDIT_TABLE,
+  ERROR_GROUPS_TABLE,
+  SQL_ADMIN_AUDIT_TABLE,
+  SQL_ERROR_GROUPS_TABLE,
+} from '@ultimat3/admin/schema';
+import {
+  AUTH_SERVER_TABLES,
+  AUTH_TABLE_NAMES,
+  AUTH_TABLES,
+  SQL_AUTH_LIMIT_TABLES,
+  SQL_AUTH_SERVER_TABLES,
+  SQL_TOTP_REPLAY_TABLE,
+} from '@ultimat3/auth';
+import { FAILURES_TABLE, SQL_FAILURES_TABLE } from '@ultimat3/db';
 import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
 import { MCP_CONFIRMATIONS_TABLE, SQL_MCP_CONFIRMATIONS_TABLE } from '@ultimat3/mcp/schema';
 import {
+  PUSH_DEVICES_TABLE,
   SQL_NOTIFY_DELIVERIES_TABLE,
   SQL_NOTIFY_DIGESTS_TABLE,
   SQL_NOTIFY_INBOX_TABLE,
+  SQL_PUSH_DEVICES_TABLE,
 } from '@ultimat3/notify';
 import { PUSH_SUBSCRIPTIONS_TABLE, SQL_PUSH_SUBSCRIPTIONS_TABLE } from '@ultimat3/pwa/schema';
 import { FrameworkSchemaFailedError } from './schema-errors';
@@ -75,6 +90,13 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_audit']),
     ddl: Object.freeze([SQL_AUDIT_TABLE]),
   }),
+  // The counters behind `meter:`. One row per tenant × meter × period declaration, rolled over in
+  // place, so it ships no purge: the table is bounded by its subjects, never by time.
+  Object.freeze({
+    pkg: '@ultimat3/action',
+    tables: Object.freeze(['x_meter']),
+    ddl: Object.freeze([SQL_METER_TABLE]),
+  }),
   Object.freeze({
     pkg: '@ultimat3/http',
     tables: Object.freeze(['x_rate_limit']),
@@ -85,8 +107,14 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_auth_lockouts']),
     ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
   }),
+  // Spent TOTP steps, so a code is single-use across the fleet rather than per replica.
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: Object.freeze(['x_totp_steps']),
+    ddl: Object.freeze([SQL_TOTP_REPLAY_TABLE]),
+  }),
   /**
-   * The five tables `PostgresAuthAdapter` reads, and the oldest hole in this list.
+   * The eight tables `PostgresAuthAdapter` reads, and the oldest hole in this list.
    *
    * Until this row nothing applied them, in dev or in production: they are not `entity()`
    * declarations, so `x db gen` never saw them, and an app was left to paste per-table exports
@@ -94,7 +122,7 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
    * exports are gone; `AUTH_TABLES` is the whole DDL, the 1.3 `x_users` upgrade included, applied
    * here on exactly the rule the rate-limit and audit rows already follow.
    *
-   * `AUTH_TABLE_NAMES` rather than five literals: @ultimat3/auth already publishes the list, and a
+   * `AUTH_TABLE_NAMES` rather than eight literals: @ultimat3/auth already publishes the list, and a
    * second copy is a second thing to keep right when a table is added.
    */
   Object.freeze({
@@ -102,6 +130,16 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: AUTH_TABLE_NAMES,
     ddl: AUTH_TABLES,
   }),
+  /**
+   * `authorizationServer()`'s clients, codes, grants, tokens and device codes — what
+   * `postgresAuthServerStore()` reads. Applied whether or not the app runs a server, for every
+   * row's reason: enabling it must not be the deploy that discovers the tables were never created.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: AUTH_SERVER_TABLES,
+    ddl: Object.freeze([SQL_AUTH_SERVER_TABLES]),
+  }),
   /**
    * The delivery ledger is what stops a replayed notifier job sending twice, and it is the entry
    * whose absence is least visible: without the table the ledger's first `claim` raises `42P01`
@@ -126,6 +164,14 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_notify_digests']),
     ddl: Object.freeze([SQL_NOTIFY_DIGESTS_TABLE]),
   }),
+  // `postgresPushDeviceStore`'s native registrations — what `pushRegister()` writes and
+  // `nativePush()` reads. Installed whether or not the app ships a native client, for every row's
+  // reason: shipping one must not be the deploy whose first registration meets `42P01`.
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze([PUSH_DEVICES_TABLE]),
+    ddl: Object.freeze([SQL_PUSH_DEVICES_TABLE]),
+  }),
   /**
    * The admin's durable audit trail — what `postgresAuditLog()` writes and every detail page's
    * history card reads. Without this row an app that chose the durable log met `42P01` on the
@@ -137,6 +183,27 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze([ADMIN_AUDIT_TABLE]),
     ddl: Object.freeze([SQL_ADMIN_AUDIT_TABLE]),
   }),
+  /**
+   * `errorGroupsSink`'s table — one row per error fingerprint, what `/admin/errors` lists and
+   * `postgresErrorGroupsStore()` upserts. Applied whether or not the app installs the sink, for
+   * every row's reason: turning it on must not be the deploy whose first error meets `42P01` —
+   * and a sink write that fails is only logged, so that outage would be silent. Same leaf subpath.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/admin',
+    tables: Object.freeze([ERROR_GROUPS_TABLE]),
+    ddl: Object.freeze([SQL_ERROR_GROUPS_TABLE]),
+  }),
+  /**
+   * `failureCapture`'s bundles — what `postgresFailureStore()` writes on a 5xx and `x repro` reads.
+   * Applied whether or not capture is on, for every row's reason: turning it on must not be the
+   * deploy whose first failure meets `42P01`, and a capture write that fails is only logged.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/db',
+    tables: Object.freeze([FAILURES_TABLE]),
+    ddl: Object.freeze([SQL_FAILURES_TABLE]),
+  }),
   /**
    * `mcpConfirmations`' pending rows — what `postgresConfirmationStore()` reads and writes. Without
    * this row the first gated `tools/call` met `42P01`. Through `@ultimat3/mcp/schema`, a leaf

package/src/generate-catalog-locales.ts

@@ -77,3 +77,22 @@ export async function localiseCatalogs(
     return { ...file, contents: serializeCatalog(seedCatalog(loadCatalog(generated))) };
   });
 }
+
+/**
+ * `--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.
+ */
+export 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;
+    }
+  });
+}

package/src/generate-chart-alerts.ts

@@ -0,0 +1,156 @@
+// `x g chart-alerts`: the chart's two monitoring templates written into an app whose chart predates
+// them, plus the `values.yaml` blocks it lacks — appended, never rewritten, so a deliberate
+// `enabled: false` stays. `--print` is the same rule table as plain Prometheus rule groups, for a
+// rule loader outside Kubernetes. No `<name>`: an app has one chart, and `Chart.yaml` names it.
+
+import { stringField, UltimateError } from '@ultimat3/core';
+import { generateSpec } from './cmd-generate-spec';
+import type { CommandContext } from './command';
+import { invocationOf } from './command';
+import { BadFlagError } from './errors';
+import { generate } from './generate-files';
+import type { Generator } from './generate-kinds';
+import { containedPath, planWrites, writeFiles } from './generate-write';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool } from './parse';
+import type { GeneratedFile } from './templates';
+import { ALERTS_VALUES, SERVICE_MONITOR_VALUES } from './templates/scaffold-helm';
+import { alertRuleGroups, CHART_ALERTS } from './templates/scaffold-helm-alerts';
+
+export const CHART_FILE = 'docker/helm/Chart.yaml';
+export const VALUES_FILE = 'docker/helm/values.yaml';
+
+/** A chart is not there to write into. Its fix is the half that needs none. */
+export class ChartMissingError extends UltimateError {
+  constructor(reason: string) {
+    super({
+      code: 'X_CHART_MISSING',
+      cause: `${CHART_FILE} ${reason}, so there is no chart for the monitoring templates to join`,
+      fix: 'x g chart-alerts --print --json',
+    });
+  }
+}
+
+/** `--print` is this generator's, and on any other one it would be a flag accepted and ignored. */
+export function refuseChartAlertsFlags(kind: Generator, args: ParsedArgs): void {
+  if (kind === 'chart-alerts' || !args.flags.has('print')) return;
+  throw new BadFlagError({
+    flag: 'print',
+    command: `g ${kind}`,
+    reason: "--print is the chart-alerts generator's",
+    fix: 'x g chart-alerts --print',
+  });
+}
+
+/** The flags this generator reads; any other set to something but its default is refused. */
+const READS = new Set(['print', 'force', 'dry-run']);
+
+function refuseUnreadFlags(args: ParsedArgs): void {
+  const named = args.positionals[1];
+  if (named !== undefined) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'g chart-alerts',
+      reason: `takes no <name> and got "${named}": an app has one chart, and Chart.yaml names it`,
+      fix: 'x g chart-alerts',
+    });
+  }
+  for (const flag of generateSpec.flags ?? []) {
+    if (READS.has(flag.name)) continue;
+    const value = args.flags.get(flag.name);
+    if (value === undefined || value === flag.default) continue;
+    throw new BadFlagError({
+      flag: flag.name,
+      command: 'g chart-alerts',
+      reason: `the chart-alerts generator does not read --${flag.name}, so it would change nothing`,
+      fix: 'x g chart-alerts',
+    });
+  }
+}
+
+/** The chart's `name`, which its helpers (`<name>.fullname`, `<name>.labels`) are named after. */
+export async function chartName(root: string): Promise<string> {
+  const file = Bun.file(containedPath(root, CHART_FILE));
+  if (!(await file.exists())) throw new ChartMissingError('does not exist');
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(await file.text());
+  } catch {
+    throw new ChartMissingError('does not parse as YAML');
+  }
+  const name = stringField(parsed, 'name');
+  if (name === undefined || !/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    throw new ChartMissingError('declares no chart name of lowercase letters, digits and hyphens');
+  }
+  return name;
+}
+
+/**
+ * The blocks `values.yaml` lacks, by top-level key. A key already there is the app's — whatever it
+ * says — and the templates read a missing one as `auto`, so a values file this never touches works.
+ */
+export function missingValueBlocks(values: string): string {
+  const has = (key: string) => new RegExp(`^${key}\\s*:`, 'm').test(values);
+  return [
+    ...(has('serviceMonitor') ? [] : [SERVICE_MONITOR_VALUES]),
+    ...(has('alerts') ? [] : [ALERTS_VALUES]),
+  ].join('');
+}
+
+/** `values` with `blocks` appended after one blank line. */
+const appended = (values: string, blocks: string): string =>
+  `${values.trimEnd()}\n\n${blocks.trimEnd()}\n`;
+
+export async function runChartAlerts(ctx: CommandContext, root: string): Promise<CommandResult> {
+  refuseUnreadFlags(ctx.args);
+  if (flagBool(ctx.args, 'print')) {
+    const rules = alertRuleGroups();
+    return {
+      ok: true,
+      command: 'g',
+      summary: msg('cli.generate.chartAlertsPrinted', { count: CHART_ALERTS.length }),
+      data: { rules },
+      lines: rules.trimEnd().split('\n'),
+    };
+  }
+  const name = await chartName(root);
+  const force = flagBool(ctx.args, 'force');
+  // Without --force a template already there is kept, never a conflict: it is the app's, and this
+  // run's job is the files the chart lacks. --force rewrites both from the current table.
+  const files = generate({ kind: 'chart-alerts', name }).map(
+    (file): GeneratedFile =>
+      force || typeof file.contents !== 'string'
+        ? file
+        : { path: file.path, contents: file.contents, merge: 'if-absent' },
+  );
+  const valuesPath = containedPath(root, VALUES_FILE);
+  const valuesFile = Bun.file(valuesPath);
+  const values = (await valuesFile.exists()) ? await valuesFile.text() : undefined;
+  const blocks = values === undefined ? '' : missingValueBlocks(values);
+  const edited = blocks === '' ? [] : [VALUES_FILE];
+  const invocation = `${invocationOf(ctx, 'g')} chart-alerts`;
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const report = dryRun
+    ? await planWrites(root, files, force, invocation)
+    : await writeFiles(root, files, force, invocation);
+  if (!dryRun && values !== undefined && blocks !== '') {
+    await Bun.write(valuesPath, appended(values, blocks));
+  }
+  const touched = [...report.written, ...edited];
+  // Zero files is a run like any other: a chart that holds both templates and both values blocks.
+  const summary = msg(dryRun ? 'cli.generate.planned' : 'cli.generate.wrote', {
+    count: touched.length,
+    kind: 'chart-alerts',
+    name,
+  });
+  return {
+    ok: report.conflicts.length === 0,
+    command: 'g',
+    summary,
+    data: { files: touched, edits: edited, ...(dryRun ? { dryRun: true } : {}) },
+    lines: touched.map((path) => msg('cli.file.added', { path })),
+    findings: report.conflicts,
+  };
+}

package/src/generate-feature-required.ts

@@ -0,0 +1,65 @@
+// `x g query` and `x g backfill` read a table, so a slice with no `entity.ts` is refused rather than
+// handed one. `x g query order` wrote 14 files and `next: x db gen "create orders"`: a read asked
+// for and a table delivered. Only `x g entity` and `x g resource` create a feature's data.
+
+import { existsSync } from 'node:fs'; // why: a synchronous file probe, as the slice's own guard.
+import { UltimateError } from '@ultimat3/core';
+import { commentSafe } from './comment-safe';
+import { closestSlice, slicesBeside } from './generate-feature';
+import type { Generator } from './generate-kinds';
+import { containedPath } from './generate-write';
+import { quoteArg } from './shell-quote';
+
+/** The generators whose whole body reads a table the slice declares. */
+const READS_A_TABLE: ReadonlySet<Generator> = new Set<Generator>(['query', 'backfill']);
+
+/** Declared beside its one thrower: `errors.ts` sits at its 500-line ceiling. */
+export class FeatureRequiredError extends UltimateError {
+  constructor(input: { readonly cause: string; readonly fix: string }) {
+    super({ code: 'X_FEATURE_REQUIRED', cause: input.cause, fix: input.fix });
+  }
+}
+
+export interface SliceToRead {
+  readonly kind: Generator;
+  /** The name as the caller spelled it, for the line the fix reproduces. */
+  readonly name: string;
+  readonly feature: string | undefined;
+  /** `sliceDir(surface, kebab(feature ?? name))`, relative to the app root. */
+  readonly slice: string;
+  /** `reproducedFlags`' spelling of what the caller set: a fix never loses `--live`. */
+  readonly flags: readonly string[];
+}
+
+/**
+ * Refuses a read with no table to read, for the two kinds whose body needs one. Runs after
+ * `assertFeatureExists`, so a `--feature` reaching here names a directory that is there.
+ *
+ * Named flags stay out of the leading line's `--feature`, which this fix supplies itself.
+ */
+export function assertSliceToRead(root: string, target: SliceToRead): void {
+  const { kind, name, feature, slice, flags } = target;
+  if (!READS_A_TABLE.has(kind)) return;
+  if (existsSync(containedPath(root, `${slice}/entity.ts`))) return;
+  if (feature !== undefined) {
+    throw new FeatureRequiredError({
+      cause: `x g ${kind} reads a table, and ${slice} holds no entity.ts — a generator writing into a slice never invents one`,
+      fix: `x g entity ${quoteArg(feature)}`,
+    });
+  }
+  const tables = slicesBeside(root, slice).filter((candidate) =>
+    existsSync(containedPath(root, `${slice}/../${candidate}/entity.ts`)),
+  );
+  const near = closestSlice(name, tables);
+  const named = quoteArg(name);
+  const listed = commentSafe(tables.join(', '));
+  throw new FeatureRequiredError({
+    cause: `x g ${kind} ${named} names no --feature and ${slice} holds no entity.ts (${tables.length === 0 ? 'no slice holds one yet' : `slices with one: ${listed}`}), and a read never creates the table it reads`,
+    fix:
+      near !== undefined
+        ? `${[`x g ${kind} ${named} --feature ${quoteArg(near)}`, ...flags].join(' ')}   # or x g resource ${named} for a new table`
+        : tables.length === 0
+          ? `x g resource ${named}   # a new table: x g ${kind} reads one, and none exists yet`
+          : `x g resource ${named}   # a new table, or x g ${kind} ${named} --feature <slice> to read one of: ${listed}`,
+  });
+}