@homeflare/config 0.5.0 → 0.7.0

package/src/repo-shape/drift.ts

@@ -0,0 +1,130 @@
+/**
+ * The drift check: re-render, compare, and say what to run.
+ *
+ * ★ WHAT MAKES THIS DIFFERENT FROM A LINT RULE. It does not describe good workflows; it
+ *   asserts that this repository's committed files ARE the rendered ones. A hand edit
+ *   fails here before it can spread, which is the mechanism — not the convention — that
+ *   keeps fourteen repositories the same.
+ *
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR, exactly like `checkProject` in this package. A check
+ *   that silently rewrote the working tree would erase the evidence of what someone
+ *   changed, and the one case worth catching — a deliberate edit that should have been an
+ *   exception — is the case it would erase. `refresh.ts` is the separate, explicit writer.
+ *
+ * ⚠️ EVERY COMPARISON IS EXACT TEXT, NOT STRUCTURE. `checkProject` compares parsed values
+ *   because a project may reformat its copy of a preset. Here the file IS generated, so
+ *   any difference at all — including a reflowed comment — means the file did not come
+ *   out of the renderer, and reformatting it would defeat the point of generating it.
+ *   The one exception is line endings, normalised so a CRLF checkout is not "drift".
+ */
+import { type RenderedRepo, renderRepoShape } from './render.ts';
+import type { RenderedPath, RepoShape, RepoShapeException } from './shape.ts';
+
+/** One thing to fix, in the imperative — the same `Problem` shape `./check` reports. */
+export type Problem = string;
+
+/** The command that makes a difference go away. Printed with every drift problem. */
+export const REFRESH_COMMAND = 'bun run repo-shape:refresh';
+
+function normalize(text: string): string {
+  return text.replaceAll('\r\n', '\n');
+}
+
+async function readIfPresent(path: string): Promise<string | undefined> {
+  const file = Bun.file(path);
+  return (await file.exists()) ? normalize(await file.text()) : undefined;
+}
+
+/**
+ * ⛔ AN EXCEPTION FOR A FILE THE SHAPE DOES NOT RENDER IS ITSELF A PROBLEM. Otherwise a
+ *   repository that moved from the mini to GitHub-hosted runners would keep a stale
+ *   `.github/actionlint.yaml` exception forever, and the exception list — the one place
+ *   that is supposed to hold every deviation — would be lying about one of them.
+ */
+function staleExceptions(
+  rendered: RenderedRepo,
+  exceptions: readonly RepoShapeException[],
+): Problem[] {
+  return exceptions
+    .filter((exception) => rendered.files[exception.file] === undefined)
+    .map(
+      (exception) =>
+        `${exception.file}: excepted (since ${exception.since}) but this shape renders no such file — drop the exception`,
+    );
+}
+
+/**
+ * ⚠️ A DUPLICATE EXCEPTION HIDES A REASON. Two `except()` entries for one file means one
+ *   of the two reasons is never read, and the one that loses is arbitrary. Refuse both.
+ */
+function duplicateExceptions(exceptions: readonly RepoShapeException[]): Problem[] {
+  const seen = new Set<RenderedPath>();
+  const duplicated = new Set<RenderedPath>();
+  for (const exception of exceptions) {
+    if (seen.has(exception.file)) duplicated.add(exception.file);
+    seen.add(exception.file);
+  }
+  return [...duplicated].map(
+    (file) => `${file}: declared as an exception more than once — keep one, with one reason`,
+  );
+}
+
+export interface DriftReport {
+  /** Empty when the committed files are the rendered ones. */
+  readonly problems: readonly Problem[];
+  /** Paths whose committed text differs from the render, excluding excepted files. */
+  readonly drifted: readonly string[];
+  /** Paths the repository declared it owns, with the reason it gave. */
+  readonly excepted: readonly RepoShapeException[];
+}
+
+/**
+ * Compare a repository's committed tooling files against its declared shape.
+ *
+ *     const report = await driftInRepoShape(process.cwd(), shape);
+ *     expect(report.problems).toEqual([]);
+ *
+ * A declared exception passes. An undeclared difference fails, and so does a missing file.
+ */
+export async function driftInRepoShape(projectDir: string, shape: RepoShape): Promise<DriftReport> {
+  const rendered = renderRepoShape(shape);
+  const exceptions = shape.exceptions ?? [];
+  const excepted = new Map(exceptions.map((exception) => [exception.file as string, exception]));
+  const problems: Problem[] = [
+    ...duplicateExceptions(exceptions),
+    ...staleExceptions(rendered, exceptions),
+  ];
+  const drifted: string[] = [];
+
+  for (const [path, expected] of Object.entries(rendered.files)) {
+    if (excepted.has(path)) continue;
+    const actual = await readIfPresent(`${projectDir}/${path}`);
+    if (actual === undefined) {
+      problems.push(`${path}: missing — run \`${REFRESH_COMMAND}\``);
+      drifted.push(path);
+      continue;
+    }
+    if (actual !== normalize(expected)) {
+      drifted.push(path);
+      problems.push(
+        `${path}: differs from what @homeflare/config renders for this shape. ` +
+          `Run \`${REFRESH_COMMAND}\` to take the standard, ` +
+          `or declare it with except({ file: '${path}', reason: '…', since: '…' }) in repo-shape.ts.`,
+      );
+    }
+  }
+
+  return { drifted, excepted: exceptions, problems };
+}
+
+/**
+ * Every rendered path that is NOT compared, with why. For a report, not for a gate.
+ * ★ Printed by `refresh --check` so a passing run still names what it did not check.
+ *   An exception that stops being visible is an exception that stops being reconsidered.
+ */
+export function exceptionSummary(shape: RepoShape): readonly string[] {
+  return (shape.exceptions ?? []).map(
+    (exception) =>
+      `${exception.file}: not checked — ${exception.reason} (since ${exception.since})`,
+  );
+}

package/src/repo-shape/refresh.ts

@@ -0,0 +1,113 @@
+/**
+ * The writer, and the CLI a repository wires to `repo-shape:refresh`.
+ *
+ * ⛔ SEPARATE FROM THE CHECK, ON PURPOSE. `drift.ts` never writes and this never gates;
+ *   a tool that did both would repair the working tree during CI and report green on a
+ *   repository whose committed files are still wrong.
+ *
+ * ★ IT ONLY WRITES WHAT CHANGED. An unchanged file keeps its mtime, so a refresh in a
+ *   watch-mode session does not restart anything, and `git status` after a no-op refresh
+ *   is empty rather than "14 files touched".
+ *
+ * ⚠️ IT NEVER WRITES AN EXCEPTED FILE. Refreshing a file the repository declared it owns
+ *   would overwrite the deviation the reason was written for — the one destructive thing
+ *   this could do, and the one it must not.
+ */
+import { REFRESH_COMMAND, driftInRepoShape, exceptionSummary } from './drift.ts';
+import { renderRepoShape } from './render.ts';
+import { type RepoShape, isExcepted } from './shape.ts';
+import type { RenderedPath } from './shape.ts';
+
+export interface RefreshResult {
+  /** Paths written because their content changed or they were absent. */
+  readonly written: readonly string[];
+  /** Paths already correct. */
+  readonly unchanged: readonly string[];
+  /** Paths skipped because the shape declares an exception for them. */
+  readonly skipped: readonly string[];
+}
+
+/** Write a repository's rendered files into `projectDir`. */
+export async function refreshRepoShape(
+  projectDir: string,
+  shape: RepoShape,
+): Promise<RefreshResult> {
+  const rendered = renderRepoShape(shape);
+  const written: string[] = [];
+  const unchanged: string[] = [];
+  const skipped: string[] = [];
+
+  for (const [path, contents] of Object.entries(rendered.files)) {
+    if (isExcepted(shape, path as RenderedPath)) {
+      skipped.push(path);
+      continue;
+    }
+    const target = `${projectDir}/${path}`;
+    const file = Bun.file(target);
+    if ((await file.exists()) && (await file.text()) === contents) {
+      unchanged.push(path);
+      continue;
+    }
+    await Bun.write(target, contents);
+    written.push(path);
+  }
+
+  return { skipped, unchanged, written };
+}
+
+/**
+ * ★ `Bun.write(Bun.stdout, …)` RATHER THAN `console.log`. Two reasons, and the lint rule
+ *   is the lesser: a CLI's output is a stream it owns, and writing to it explicitly is
+ *   what lets `repoShapeCli` be called in a test and in a `repo-shape.ts` without either
+ *   one inheriting a global. `console` in `src/` is also off-limits in the house preset —
+ *   allowed under `tests/**` and `scripts/**`, and this is neither.
+ */
+async function say(
+  stream: typeof Bun.stdout | typeof Bun.stderr,
+  lines: readonly string[],
+): Promise<void> {
+  if (lines.length === 0) return;
+  await Bun.write(stream, `${lines.join('\n')}\n`);
+}
+
+/**
+ * The `repo-shape:refresh` entry point. `--check` reports drift and exits non-zero
+ * instead of writing, which is what a repository puts in CI when it does not want the
+ * check inside `bun test`.
+ */
+export async function repoShapeCli(
+  projectDir: string,
+  shape: RepoShape,
+  argv: readonly string[],
+): Promise<number> {
+  if (argv.includes('--check')) {
+    const report = await driftInRepoShape(projectDir, shape);
+    // ★ The exceptions are printed on a PASSING run too. An exception that stops being
+    //   visible is an exception that stops being reconsidered.
+    await say(
+      Bun.stdout,
+      exceptionSummary(shape).map((note) => `· ${note}`),
+    );
+    if (report.problems.length === 0) {
+      const count = report.excepted.length;
+      await say(Bun.stdout, [
+        `repo shape: in step with @homeflare/config (${count} declared exception(s))`,
+      ]);
+      return 0;
+    }
+    await say(Bun.stderr, [
+      ...report.problems.map((problem) => `✗ ${problem}`),
+      '',
+      `Run \`${REFRESH_COMMAND}\`, or declare the deviation with a reason.`,
+    ]);
+    return 1;
+  }
+
+  const result = await refreshRepoShape(projectDir, shape);
+  await say(Bun.stdout, [
+    ...result.written.map((path) => `wrote    ${path}`),
+    ...result.unchanged.map((path) => `ok       ${path}`),
+    ...result.skipped.map((path) => `excepted ${path}`),
+  ]);
+  return 0;
+}

package/src/repo-shape/render.ts

@@ -0,0 +1,88 @@
+/**
+ * `renderRepoShape` — one declaration, both halves of a standard repository.
+ *
+ * ★ THIS IS THE POINT OF THE WHOLE MODULE. A repository declares its shape once and gets
+ *   its FILES (here) and its GitHub SETTINGS (through `policy`, which is the options
+ *   object `@homeflare/alchemy`'s `declareRepoPolicy` takes). Before this, the workflow
+ *   that produces a status check and the ruleset that requires that status check were
+ *   written in two files by hand, and nothing connected them: renaming the aggregate job
+ *   would leave a required check that never reports, and a pull request would wait on it
+ *   forever with auto-merge armed. `checks` below is derived from the rendered workflows,
+ *   so the two cannot disagree.
+ *
+ * ⛔ NO IMPORT CROSSES BETWEEN THE PACKAGES, IN EITHER DIRECTION. `policy` is a plain
+ *   object that is structurally assignable to `RepoPolicyOptions`; `@homeflare/alchemy`
+ *   does not depend on `@homeflare/config` and this does not depend on Alchemy or Effect.
+ *   That matters because `@homeflare/config` is installed in 13 of 14 repositories and
+ *   `@homeflare/alchemy` in 4 — the drift check has to run everywhere, and it must not
+ *   drag a provider library into a repository that has no stack.
+ *   ⚠️ A structural seam is checked only where both sides are present: the assignability
+ *     test lives in `packages/alchemy/tests/repo-shape-policy.test.ts`, which is the one
+ *     place that imports both.
+ */
+import { renderCi } from './ci.ts';
+import { renderActionlintConfig, renderChangesetConfig, renderDependabot } from './companions.ts';
+import { renderSecurity } from './security.ts';
+import type { RenderedPath, RepoShape } from './shape.ts';
+
+/** The status-check contexts a rendered repository reports. */
+export interface RepoShapePolicy {
+  readonly owner: string;
+  readonly repository: string;
+  /**
+   * ⛔ EXACTLY THE AGGREGATES, NEVER THE LEAF JOBS. `ci` is `if: always()` and fails when
+   *   any job it needs did not succeed, so requiring it requires all of them. Requiring a
+   *   leaf job instead would mean a ruleset edit every time a job is added, and a context
+   *   that stops reporting leaves every pull request pending rather than failing.
+   */
+  readonly checks: readonly string[];
+}
+
+export interface RenderedRepo {
+  /** Every rendered file, by its path relative to the repository root. */
+  readonly files: Readonly<Record<string, string>>;
+  /**
+   * The options `declareRepoPolicy(id, { ...rendered.policy, settings })` takes.
+   * Squash-only, auto-merge, delete-branch-on-merge and the `main` ruleset come from
+   * there; the check names come from here.
+   */
+  readonly policy: RepoShapePolicy;
+}
+
+/**
+ * Render a repository's tooling files and the policy that matches them.
+ *
+ *     const rendered = renderRepoShape(shape);
+ *     rendered.files['.github/workflows/ci.yml']   // the file
+ *     rendered.policy.checks                        // ['ci', 'secret scan']
+ *
+ * ⚠️ EXCEPTED FILES ARE STILL RENDERED. `files` is what the standard says this repository
+ *   should have; `drift.ts` is what decides which of them are compared. Keeping them here
+ *   means `--show` can print the standard version of an excepted file, which is how
+ *   anyone judges whether the exception is still worth its reason.
+ */
+export function renderRepoShape(shape: RepoShape): RenderedRepo {
+  const files: Record<string, string> = {
+    '.changeset/config.json': renderChangesetConfig(shape),
+    '.github/dependabot.yml': renderDependabot(shape),
+    '.github/workflows/ci.yml': renderCi(shape),
+    '.github/workflows/security.yml': renderSecurity(shape),
+  };
+
+  const actionlint = renderActionlintConfig(shape);
+  if (actionlint !== undefined) files['.github/actionlint.yaml'] = actionlint;
+
+  return {
+    files,
+    policy: { checks: ['ci', 'secret scan'], owner: shape.owner, repository: shape.repository },
+  };
+}
+
+/** Every path this renderer can emit, whatever a given shape asks for. */
+export const RENDERED_PATHS: readonly RenderedPath[] = [
+  '.changeset/config.json',
+  '.github/actionlint.yaml',
+  '.github/dependabot.yml',
+  '.github/workflows/ci.yml',
+  '.github/workflows/security.yml',
+];

package/src/repo-shape/security.ts

@@ -0,0 +1,109 @@
+/**
+ * `.github/workflows/security.yml`, rendered.
+ *
+ * ⛔ THIS FILE IS WHY THE RENDERER EXISTS. Measured across 13 repositories on 2026-09-22,
+ *   every one of these was a per-repo accident rather than a decision:
+ *     · `push: branches: [main]` still present in 5, removed in 8;
+ *     · the `concurrency:` block missing entirely in 5 — so a superseded scan ran to
+ *       completion holding one of the mini's 3 slots for a result nobody would read;
+ *     · `pull-requests: read` missing in 2, which makes every pull-request scan fail 403
+ *       before it inspects a single line;
+ *     · `gitleaks/gitleaks-action` pinned at `@v2` in 5 and `@v3` in 8, after GitHub
+ *       removed the Node 20 runtime v2 needs (2026-09-16);
+ *     · the weekly cron at three different minutes.
+ *   One renderer makes all thirteen the same file, and the next such fix is one commit.
+ */
+import type { RepoShape } from './shape.ts';
+import { runsOn } from './shape.ts';
+import { renderSteps } from './yaml.ts';
+
+/**
+ * ⚠️ Off the hour deliberately — `:00` is when every scheduled workflow on GitHub fires
+ *   at once, and queue time is the result. One minute for the whole estate: a repository
+ *   does NOT get its own, because "which minute is this repo on" is a question with no
+ *   useful answer and 13 repos produced 3 different ones by accident.
+ */
+const CRON = '41 6 * * 1';
+
+const HEADER = `# Secret scanning, on its own schedule and its own check.
+#
+# 🤖 RENDERED BY @homeflare/config — DO NOT EDIT THIS FILE BY HAND.
+#    Its input is this repository's \`repo-shape.ts\`; refresh with \`bun run repo-shape:refresh\`.
+#
+# ★ SEPARATE FROM ci.yml BY CONCERN. A secret scan answers a different question from "is
+#   this code correct", it runs on a schedule as well as on pull requests (a rule added
+#   tomorrow can find a secret committed today), and it needs full history, which the CI
+#   jobs deliberately do not fetch.
+`;
+
+const TRIGGER = `name: security
+
+on:
+  # ⛔ NO \`push: branches: [main]\`, for the reason ci.yml gives: main only moves by
+  #   squashing a pull request this same workflow already scanned, so the post-merge scan
+  #   re-read commits it had just cleared. The weekly cron is what covers "a rule added
+  #   tomorrow finds a secret committed today" — and it is the one that fetches full history.
+  pull_request:
+  schedule:
+    - cron: '${CRON}'
+
+permissions:
+  contents: read
+  # 🔴 gitleaks-action lists pull-request commits through GitHub's API before scanning,
+  #   and posts inline annotations. Without this, \`pull_request\` runs fail 403 before
+  #   inspecting any code. Two of thirteen repositories were missing it (2026-09-22).
+  pull-requests: read
+
+# ⛔ cancel-in-progress IS CONDITIONAL, NOT \`true\`. The scheduled run's ref is
+#   refs/heads/main; a plain \`true\` would let anything sharing that group kill the weekly
+#   full-history scan. Only pull-request runs are ever cancelled.
+concurrency:
+  group: security-\${{ github.ref }}
+  cancel-in-progress: \${{ github.event_name == 'pull_request' }}
+`;
+
+const FETCH_NOTE = `        with:
+          # ⛔ FULL HISTORY. A shallow clone scans only the tip, which misses the case that
+          #   matters most: a secret added and then removed in a later commit. It is still
+          #   in the history, still fetchable, and still compromised.
+          fetch-depth: 0`;
+
+const GITLEAKS_NOTE = `      # ⛔ v3, NOT v2. GitHub removed the Node 20 runtime from hosted runners on 2026-09-16
+      #   (gitleaks/gitleaks-action's own v3.0.0 migration notes, verified 2026-09-17), so
+      #   v2 (\`runs: node20\`) fails outright now, with no opt-out flag. v3 changes only the
+      #   runtime to node24 — inputs, outputs and behaviour are unchanged.
+      # ★ arm64-SAFE ON THE MINI, verified rather than assumed: v3's src/gitleaks.js builds
+      #   its download URL from \`process.arch\`, so the runner asks for
+      #   gitleaks_<version>_linux_arm64.tar.gz, an asset its default release publishes
+      #   (both read 2026-09-22). Nothing here is hard-coded to x64.
+      # ★ No \`GITLEAKS_LICENSE\`: that env var is required only for GitHub Organization
+      #   accounts, and \`taslabs-net\` is a personal User account (2026-09-17,
+      #   \`gh api users/taslabs-net --jq .type\` -> \`User\`).`;
+
+/** The whole `security.yml` for a shape. */
+export function renderSecurity(shape: RepoShape): string {
+  const on = runsOn(shape.runner);
+  // ⚠️ A GitHub ACTIONS EXPRESSION, NOT A TEMPLATE LITERAL. `${{ … }}` is interpolated by
+  //   the Actions runner at job time and must reach the file verbatim, so it is a regular
+  //   string on purpose — `no-template-curly-in-string` is warning about exactly the
+  //   confusion this comment resolves, and it is right to ask.
+  // oxlint-disable-next-line no-template-curly-in-string
+  const token = '${{ secrets.GITHUB_TOKEN }}';
+  const scheduled =
+    shape.runner === 'mini'
+      ? `\n    # ⛔ THE SCHEDULED RUN GOES TO THE MINI TOO: if the runner daemon is down this queues\n    #   rather than failing, so a missed weekly scan is silent. homeflare-mini's\n    #   \`ci-runner\` vmalert group is what notices that, not this workflow.`
+      : '';
+
+  return `${HEADER}${TRIGGER}
+jobs:
+  secrets:
+    name: secret scan${scheduled}
+    runs-on: ${on}
+    steps:
+${renderSteps([{ uses: 'actions/checkout@v7' }], 3)}
+${FETCH_NOTE}
+
+${GITLEAKS_NOTE}
+${renderSteps([{ uses: 'gitleaks/gitleaks-action@v3', env: { GITHUB_TOKEN: token } }], 3)}
+`;
+}

package/src/repo-shape/shape.ts

@@ -0,0 +1,214 @@
+/**
+ * `RepoShape` — one HomeFlare repository's tooling, as a value.
+ *
+ * ★ WHY THIS TYPE EXISTS. Measured across the estate on 2026-09-22: 13 repositories each
+ *   carry a hand-written `.github/workflows/ci.yml`, `security.yml`, `.github/actionlint.yaml`
+ *   and `.changeset/config.json`. The changeset configs were byte-identical apart from the
+ *   repository name in 11 of 13. The security workflows were not: five still carried
+ *   `push: branches: [main]` that the other eight had removed, five were missing the
+ *   `concurrency:` block entirely, two were missing `pull-requests: read` (whose absence
+ *   makes every pull-request scan fail 403), the gitleaks action was pinned at `@v2` in
+ *   five and `@v3` in eight, and the weekly cron minute took three different values. Not
+ *   one of those differences was a decision. They are what happens when the same edit is
+ *   applied by hand thirteen times.
+ *
+ * ⛔ SO: A DIFFERENCE IS EITHER AN INPUT OR AN EXCEPTION. Nothing else. A repository that
+ *   needs something the standard does not give it either widens this type — and every
+ *   repository gets the widening — or declares an exception with a stated reason. There
+ *   is no third option where a file is quietly edited, because `drift.ts` fails on it.
+ *
+ * ⚠️ THE REASON IS ENFORCED BY THE COMPILER, NOT BY REVIEW. `except()` and `extraJob()`
+ *   below refuse an empty reason and refuse a reason read out of a variable, so the text
+ *   has to be written at the exception. See `Stated`.
+ */
+
+/** Where a repository's jobs run. */
+export type RepoRunner =
+  /**
+   * `[self-hosted, homeflare-mini]` — the interim Linux arm64 runner on the Mac mini.
+   * ⚠️ GitHub-hosted runners are refused for this account (billing lock, 2026-09-22).
+   */
+  | 'mini'
+  /** `ubuntu-latest`. Public repositories, where GitHub-hosted minutes are free. */
+  | 'github';
+
+/** One step in a rendered job. Either a `uses:` or a `run:`, never both. */
+export type JobStep = {
+  readonly name?: string;
+  readonly env?: Readonly<Record<string, string>>;
+} & (
+  | {
+      readonly uses: string;
+      readonly with?: Readonly<Record<string, string | number>>;
+      readonly run?: never;
+    }
+  | { readonly run: string; readonly uses?: never; readonly with?: never }
+);
+
+/**
+ * ⛔ A REASON MUST BE WRITTEN, NOT COMPUTED. `'' extends R` is true for the empty literal
+ *   AND for the wide `string` type, so both collapse to `never` and fail to typecheck:
+ *   `reason: ''` is refused, and so is `reason: someVariable`. Only a string literal
+ *   written at the call site survives — which is the whole point, because a reason
+ *   assembled at runtime is a reason nobody reads in the diff.
+ *   Verified against TypeScript 7.0.2 on 2026-09-22; `tests/repo-shape-reason.test.ts`
+ *   compiles the refusals and asserts they still fail.
+ */
+export type Stated<R extends string> = '' extends R ? never : R;
+
+/** Paths this package renders. A deviation names one of these, not an arbitrary file. */
+export type RenderedPath =
+  | '.changeset/config.json'
+  | '.github/actionlint.yaml'
+  | '.github/dependabot.yml'
+  | '.github/workflows/ci.yml'
+  | '.github/workflows/security.yml';
+
+export interface RepoShapeException {
+  /** The rendered file this repository does not take from the renderer. */
+  readonly file: RenderedPath;
+  /** Why — written at the exception, in a sentence a stranger can act on. */
+  readonly reason: string;
+  /** `YYYY-MM-DD` the exception was taken, so a stale one is visible. */
+  readonly since: string;
+}
+
+interface ExceptionInput {
+  readonly file: RenderedPath;
+  readonly reason: string;
+  readonly since: string;
+}
+
+/**
+ * Declare that this repository keeps its own copy of a rendered file.
+ *
+ *     except({
+ *       file: '.github/workflows/ci.yml',
+ *       reason: 'Payload needs Node >=24.15, which the rendered job does not install',
+ *       since: '2026-09-22',
+ *     })
+ *
+ * ⛔ THE DRIFT CHECK STOPS CHECKING THAT FILE. That is the trade: an exception buys the
+ *   freedom to hand-edit one file and pays for it by losing the guarantee on that file.
+ *   Prefer widening `RepoShape` — then every repository benefits and nothing is lost.
+ */
+export function except<const E extends ExceptionInput>(
+  exception: E & { readonly reason: Stated<E['reason']> },
+): RepoShapeException {
+  return {
+    file: exception.file,
+    reason: requireSentence('reason', exception.reason),
+    since: requireIsoDate(exception.since),
+  };
+}
+
+export interface ExtraJob {
+  /** The job key in `jobs:`, e.g. `package`. Lower-case, dashes allowed. */
+  readonly id: string;
+  /**
+   * The job's `name:`, which is also the status-check context. It joins the `ci`
+   * aggregate's `needs`, so the branch ruleset still requires exactly one check.
+   */
+  readonly name: string;
+  /** Why this repository has a job the other twelve do not. */
+  readonly reason: string;
+  /** Steps after checkout. The prologue (checkout, bun, install) is rendered for you. */
+  readonly steps: readonly JobStep[];
+  /** Job ids this one waits for. Default: none, so it runs beside `check`. */
+  readonly needs?: readonly string[];
+  /** `false` skips the rendered bun prologue — for a job that needs another toolchain. */
+  readonly bun?: boolean;
+}
+
+interface ExtraJobInput extends Omit<ExtraJob, 'needs' | 'bun'> {
+  readonly needs?: readonly string[];
+  readonly bun?: boolean;
+}
+
+/**
+ * Declare a job this repository needs and the standard does not have.
+ * ⛔ Same rule as `except`: the reason is a written literal or it does not compile.
+ */
+export function extraJob<const J extends ExtraJobInput>(
+  job: J & { readonly reason: Stated<J['reason']> },
+): ExtraJob {
+  if (job.steps.length === 0) {
+    throw new Error(`repo-shape: extra job "${job.id}" has no steps`);
+  }
+  return {
+    bun: job.bun ?? true,
+    id: requireJobId(job.id),
+    // ⚠️ A DISPLAY NAME IS NOT A SENTENCE. `build` and `consumer smoke test` are both
+    //   correct job names; only the REASON has to be prose, because only the reason is
+    //   there for a reader rather than for the checks list.
+    name: requireNonEmpty('name', job.name),
+    needs: [...(job.needs ?? [])],
+    reason: requireSentence('reason', job.reason),
+    steps: [...job.steps],
+  };
+}
+
+export interface RepoShape {
+  /** Repository owner — a user or organization login. */
+  readonly owner: string;
+  /** Repository name, which is also the checkout directory name. */
+  readonly repository: string;
+  /** Where its jobs run. */
+  readonly runner: RepoRunner;
+  /**
+   * `true` when the repository publishes an npm tarball. It decides `access` in the
+   * changeset config and whether `privatePackages` is written at all — the two keys
+   * that differ between `homeflare-kit` and every other repository.
+   */
+  readonly publishes: boolean;
+  /** Jobs beyond `check` and `workflows`. Each carries its own stated reason. */
+  readonly extraJobs?: readonly ExtraJob[];
+  /** Rendered files this repository keeps its own copy of, each with a reason. */
+  readonly exceptions?: readonly RepoShapeException[];
+}
+
+const SENTENCE = 12;
+
+function requireNonEmpty(field: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) throw new Error(`repo-shape: ${field} must not be blank`);
+  return trimmed;
+}
+
+function requireSentence(field: string, value: string): string {
+  const trimmed = value.trim();
+  // ⚠️ THE TYPE CANNOT CATCH `reason: '   '`. `'   '` is a non-empty literal, so `Stated`
+  //   lets it through and only this does not. Type and guard cover different halves.
+  if (trimmed.length < SENTENCE) {
+    throw new Error(`repo-shape: ${field} must be a sentence, got ${JSON.stringify(value)}`);
+  }
+  return trimmed;
+}
+
+function requireIsoDate(value: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new Error(`repo-shape: since must be YYYY-MM-DD, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+function requireJobId(value: string): string {
+  // ⛔ The id becomes a YAML key and a `needs:` entry. Anything else renders a workflow
+  //   GitHub rejects at parse time, which reports as "workflow file issue" with no line.
+  if (!/^[a-z][a-z0-9_-]*$/.test(value)) {
+    throw new Error(
+      `repo-shape: job id must match /^[a-z][a-z0-9_-]*$/, got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}
+
+/** `runs-on:` for a runner. */
+export function runsOn(runner: RepoRunner): string {
+  return runner === 'mini' ? '[self-hosted, homeflare-mini]' : 'ubuntu-latest';
+}
+
+/** Whether a rendered path is excepted by this shape. */
+export function isExcepted(shape: RepoShape, file: RenderedPath): boolean {
+  return (shape.exceptions ?? []).some((exception) => exception.file === file);
+}