@homeflare/config 0.5.1 → 0.8.0

package/src/hooks/report.ts

@@ -0,0 +1,96 @@
+/**
+ * How a hook talks to whoever triggered it.
+ *
+ * ★ EVERY FAILURE PRINTS BOTH COMMANDS — the one that fixes it and the one that skips
+ *   it. A hook that exits non-zero and says nothing teaches `--no-verify` as a reflex,
+ *   and that switch turns off every check rather than the one that was wrong.
+ *
+ * ⚠️ Output goes to STDERR. Git hooks share stdout with porcelain in some flows, and a
+ *   hook that writes there can corrupt what a caller is parsing.
+ */
+
+/** The two hooks this package implements. Named exactly as the git hook files are. */
+export type Hook = 'pre-commit' | 'pre-push';
+
+const BYPASS: Record<Hook, string> = {
+  'pre-commit': 'git commit --no-verify',
+  'pre-push': 'git push --no-verify',
+};
+
+/**
+ * 🔴 A GIT HOOK EXPORTS `GIT_DIR` AND `GIT_INDEX_FILE`, AND EVERYTHING IT SPAWNS
+ *   INHERITS THEM. Measured 2026-09-22 at the cost of two junk files and a stray commit
+ *   on this repository's `main`: `pre-push` runs `bun run check`, `check` runs the test
+ *   suite, and a test that builds a throwaway git repository and commits in it commits
+ *   into THIS repository instead — `cwd` is ignored once `GIT_DIR` is set. The estate's
+ *   own `packages/site/tests/checkout.test.ts` already carried a comment warning about
+ *   exactly this, which is how much a convention is worth.
+ * ⛔ So the hook strips them rather than trusting fourteen test suites to remember. The
+ *   gate must see the repository through `cwd`, the way CI does.
+ */
+function withoutGitEnv(): Record<string, string | undefined> {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
+  );
+}
+
+/**
+ * Run a command, streaming its output. Returns its exit code.
+ * `isolated` drops the inherited `GIT_*` variables — see `withoutGitEnv`.
+ */
+export async function run(cmd: readonly string[], isolated = false): Promise<number> {
+  const proc = Bun.spawn([...cmd], {
+    stdout: 'inherit',
+    stderr: 'inherit',
+    ...(isolated ? { env: withoutGitEnv() } : {}),
+  });
+  return await proc.exited;
+}
+
+/** Capture a command's stdout. Used for git plumbing only. */
+export async function capture(cmd: readonly string[]): Promise<string> {
+  const proc = Bun.spawn([...cmd], { stdout: 'pipe', stderr: 'ignore' });
+  const text = await new Response(proc.stdout).text();
+  await proc.exited;
+  return text;
+}
+
+/**
+ * Resolve a dev tool to the project's own copy.
+ *
+ * ⚠️ NOT `bunx` BY DEFAULT. On a cache miss `bunx` downloads from the registry, and a
+ *   git hook that reaches the network mid-commit is a hang waiting for a flaky link.
+ *   husky puts `node_modules/.bin` on PATH, but this runs outside husky in tests, so
+ *   the local binary is named outright when it exists and `bunx` is only the fallback.
+ */
+export function tool(root: string, name: string): readonly string[] {
+  const local = `${root}/node_modules/.bin/${name}`;
+  return Bun.file(local).size > 0 ? [local] : ['bunx', name];
+}
+
+/**
+ * ⚠️ `process.stderr.write`, NOT `console`. Two reasons, and the lint rule is the lesser
+ *   one: a hook shares stdout with git porcelain in some flows, and a synchronous write
+ *   is the only kind guaranteed to land before `process.exit` below throws the buffer
+ *   away. Using `console.error` here would also make every consumer of this package
+ *   need a `no-console` exemption for code they never call directly.
+ */
+function line(text: string): void {
+  process.stderr.write(`${text}\n`);
+}
+
+export function ok(what: string): void {
+  line(`✓ ${what}`);
+}
+
+export function note(what: string): void {
+  line(`  ${what}`);
+}
+
+/** ⛔ ALWAYS GIVE THE FIX. "lint failed" is a dead end; the command that repairs it is not. */
+export function fail(hook: Hook, what: string, fix: string): never {
+  line(`\n✗ ${hook}: ${what}`);
+  line(`  fix:    ${fix}`);
+  line(`  bypass: ${BYPASS[hook]}  — CI still runs the real gate\n`);
+  process.exit(1);
+}

package/src/hooks/staged.ts

@@ -0,0 +1,68 @@
+/**
+ * What git has staged, split by what the hook may safely touch.
+ *
+ * ⛔ A STAGED FILE THAT ALSO HAS UNSTAGED EDITS IS OFF LIMITS. Formatting it in place
+ *   and running `git add` would sweep the contributor's work-in-progress into a commit
+ *   they did not ask for — the single worst thing a hook can do. Those files are
+ *   reported and checked, never rewritten.
+ */
+import { capture } from './report.ts';
+
+/**
+ * ⚠️ `.md` IS IN THIS LIST ON PURPOSE. House `oxfmt` formats markdown, so a hook that
+ *   skipped it would let an unformatted changeset through and CI would fail a commit
+ *   that looked clean locally. A hook must check what CI checks or it trains distrust.
+ */
+const FORMATTABLE = /\.(ts|tsx|js|jsx|mjs|cjs|json|jsonc|md)$/;
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+
+export type Staged = {
+  /** Fully staged and formattable — safe to rewrite and restage. */
+  readonly formattable: readonly string[];
+  /** The subset of `formattable` that oxlint understands. */
+  readonly code: readonly string[];
+  /** Staged but also dirty in the worktree — checked, never rewritten. */
+  readonly partial: readonly string[];
+};
+
+/**
+ * 🔴 `-z`, AND SPLIT ON NUL. Measured 2026-09-22: without it git applies `core.quotePath`
+ *   and a file named `café .ts` comes back as the literal 12 characters
+ *   `"caf\303\251 .ts"` — quotes, backslashes and octal escapes. Passing that to oxfmt
+ *   names a file that does not exist, so every commit touching it fails with a message
+ *   about the wrong path, and the fix anyone would reach for is `--no-verify`.
+ */
+async function names(args: readonly string[]): Promise<readonly string[]> {
+  const out = await capture(['git', ...args, '-z']);
+  return out.split('\0').filter((line) => line.length > 0);
+}
+
+/** Classify the index. Deletions are excluded — there is nothing to format in them. */
+export async function staged(): Promise<Staged> {
+  const indexed = await names(['diff', '--cached', '--name-only', '--diff-filter=ACMR']);
+  const dirty = new Set(await names(['diff', '--name-only', '--diff-filter=ACMR']));
+  const candidates = indexed.filter((file) => FORMATTABLE.test(file));
+
+  return {
+    formattable: candidates.filter((file) => !dirty.has(file)),
+    code: candidates.filter((file) => !dirty.has(file) && CODE.test(file)),
+    partial: candidates.filter((file) => dirty.has(file)),
+  };
+}
+
+/**
+ * Content fingerprints, so only the files a formatter actually changed get restaged.
+ *
+ * ★ WHY NOT RESTAGE EVERYTHING. `git add` on an untouched file is harmless but noisy:
+ *   the hook would claim it rewrote files it left alone, and a hook that overstates
+ *   what it did is one nobody reads.
+ */
+export async function fingerprints(files: readonly string[]): Promise<ReadonlyMap<string, string>> {
+  const out = new Map<string, string>();
+  for (const file of files) {
+    const handle = Bun.file(file);
+    if (!(await handle.exists())) continue;
+    out.set(file, String(Bun.hash(await handle.arrayBuffer())));
+  }
+  return out;
+}

package/src/hooks.ts

@@ -0,0 +1,48 @@
+/**
+ * The HomeFlare git hooks, as a package.
+ *
+ * ★ WHY THIS IS NOT A SCRIPT IN EVERY REPO. Fourteen copies of a hook script is the
+ *   exact drift `@homeflare/config` exists to prevent: the copies diverge, nobody
+ *   notices, and two repos disagree about what a commit must satisfy. Here the repo
+ *   commits a delegating wrapper and the behaviour ships with the package, so changing
+ *   the rule is one release and a version bump rather than fourteen edits.
+ *
+ * ⚠️ HUSKY, NOT lefthook OR A BARE `core.hooksPath`. It is already the estate's
+ *   mechanism in the repos that have working hooks, it installs from `prepare` on a
+ *   plain `bun install`, and it keeps the hook files tracked and reviewable. A second
+ *   mechanism alongside it would mean two ways to answer "are hooks on in this repo".
+ *
+ * Usage from a hook file — see `HUSKY_HOOK`:
+ *
+ *     bun node_modules/@homeflare/config/bin/hooks.ts pre-commit
+ */
+import { preCommit, prePush } from './hooks/gates.ts';
+import { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks } from './hooks/install.ts';
+import { type Hook, note, ok } from './hooks/report.ts';
+
+export { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks };
+export type { Hook };
+
+/** The commands `bin/hooks.ts` accepts. */
+export type Command = Hook | 'install';
+
+export function isCommand(value: string): value is Command {
+  return value === 'pre-commit' || value === 'pre-push' || value === 'install';
+}
+
+/**
+ * Run one hook, or install the wrappers.
+ *
+ * ⛔ Never exits non-zero for a reason the caller cannot act on: an unknown command is a
+ *   programming error in the wrapper and is reported as such, not as a failed commit.
+ */
+export async function runCommand(command: Command, root: string): Promise<void> {
+  if (command === 'install') {
+    const written = await installHooks(root);
+    ok(`wrote ${written.join(', ')} — commit them`);
+    note('they do nothing until `bun install` runs `prepare` (husky)');
+    return;
+  }
+  if (command === 'pre-commit') return await preCommit(root);
+  return await prePush(root);
+}

package/src/repo-shape/ci.ts

@@ -0,0 +1,215 @@
+/**
+ * `.github/workflows/ci.yml`, rendered.
+ *
+ * ★ THE COMMENTS ARE PART OF THE RENDER, NOT DECORATION. Thirteen repositories carried
+ *   thirteen hand-edited copies of the same reasoning; measured 2026-09-22, the header
+ *   comment alone had four different wordings and the actionlint block had three. Written
+ *   here once, every repository gets the same explanation, and correcting it is one edit.
+ *
+ * ⛔ THE AGGREGATE `ci` JOB IS THE ONLY REQUIRED CHECK. Every other job feeds it through
+ *   `needs`, so adding a job never means editing a branch ruleset. `repoShapeChecks()`
+ *   returns exactly `['ci', 'secret scan']`, which is what `declareRepoPolicy` requires.
+ */
+import type { ExtraJob, RepoShape } from './shape.ts';
+import { runsOn } from './shape.ts';
+import { renderSteps } from './yaml.ts';
+
+/** Bun the whole estate is pinned to. One line, one place. */
+export const BUN_VERSION = '1.4.0';
+/** actionlint the `workflow lint` job runs, and the mini's job image preloads. */
+export const ACTIONLINT_VERSION = '1.7.12';
+
+const CHECKOUT = 'actions/checkout@v7';
+const SETUP_BUN = 'oven-sh/setup-bun@v2';
+
+function runnerNote(shape: RepoShape): string {
+  if (shape.runner !== 'mini') {
+    return "# ⚠️ RUNS ON GitHub-HOSTED `ubuntu-latest`. Only a public repository should: hosted minutes\n#   are refused for this account's private repos (billing lock, 2026-09-22).\n";
+  }
+  return [
+    '# ⚠️ RUNS ON THE MINI (`[self-hosted, homeflare-mini]`): GitHub-hosted runners are refused for',
+    '#   this account (billing lock, 2026-09-22), so every job here runs in a one-job Linux arm64',
+    "#   container started by homeflare-mini's src/ci-runner (docs/ci-runner.md there). Each action",
+    `#   below was checked for linux/arm64. The job image preloads bun ${
+      BUN_VERSION
+    } where setup-bun`,
+    '#   looks, gh, actionlint, gitleaks, typos and shfmt; no node on PATH.',
+    '',
+  ].join('\n');
+}
+
+const HEADER = `# Pull requests: is this code correct?
+#
+# 🤖 RENDERED BY @homeflare/config — DO NOT EDIT THIS FILE BY HAND.
+#    Its input is this repository's \`repo-shape.ts\`. Change that, then:
+#        bun run repo-shape:refresh
+#    A hand edit is reverted by the next refresh and fails \`bun run check\` before that.
+#    A file this repository must own outright is declared as an \`except({...})\` with a
+#    reason, which stops the check from comparing it — see @homeflare/config/repo-shape.
+#
+# ★ SPLIT BY CONCERN, NOT ONE BIG JOB — AND NOT ONE JOB PER COMMAND EITHER: lanes that
+#   share a prologue are steps inside \`check\`, so the install is paid once.
+# ⛔ EVERY ACTION IS FIRST-PARTY OR THE VENDOR'S OWN, PINNED TO A MAJOR TAG.
+`;
+
+const TRIGGER = `name: ci
+
+on:
+  # ⛔ NO \`push: branches: [main]\`. Every commit reaches main through a pull request whose
+  #   \`ci\` had to be green — the branch ruleset requires it and carries no bypass actors —
+  #   so a second run on the squash commit recomputed an answer it already had. Measured
+  #   2026-09-15..22 across the estate: 613 of 619 main-push runs had a head_sha identical
+  #   to the merge_commit_sha of an already-green PR. That duplication was ~41% of the Mac
+  #   mini's entire CI load.
+  # ⚠️ WHAT THIS GIVES UP, SAID OUT LOUD: the ~4% of merges whose base DID move between the
+  #   PR run and the squash no longer get a post-merge re-test. That run gated nothing — it
+  #   reported after main already had the commit — and the next PR, which branches from the
+  #   merged main, is what actually catches a semantic conflict.
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-\${{ github.ref }}
+  cancel-in-progress: true
+`;
+
+const CHECK_NOTE = `  # ── One job, one install ────────────────────────────────────────────────────
+  # ★ WAS 3 SEPARATE JOBS: lint and format, types, tests. They shared an identical
+  #   prologue — checkout, setup-bun, \`bun install --frozen-lockfile\` — and the install,
+  #   not the check, was the cost: measured on the mini 2026-09-22, install p50 51s /
+  #   p90 81s against 1-3s for the command the install existed to enable. 3 jobs meant 3
+  #   installs and 3 containers to compute one answer, and on a 3-slot pool that was one
+  #   pull request asking for every slot to answer a single question.
+  # ⛔ ONE STEP: \`bun run check\`, THE REPOSITORY'S OWN GATE, NOT A COPY OF ITS LANES.
+  #   The house rule is that CI runs the same command a person runs, and a workflow that
+  #   re-lists \`lint\`, \`types\`, \`test\` is a second copy of that command which can quietly
+  #   check LESS than the local gate. Measured 2026-09-22: \`bun run check\` in homeflare-kit
+  #   is \`lint && types && build && test\`, and its tests/dist.test.ts SKIPS ITSELF when
+  #   dist/ is absent — so a workflow running lint/types/test without the build would drop
+  #   that test silently and still report green. homeflare-alerts' check runs
+  #   \`check:types\` and \`build:web\`; homeflare-subnet-calc's delegates to \`verify\`. All
+  #   fourteen repositories have a \`check\` script and every one is local-only — no network,
+  #   no deploy. Checked, not assumed.
+  # ★ THE SPLIT OF RESPONSIBILITY: this renderer owns the PLUMBING — triggers, permissions,
+  #   concurrency, runner, action versions, the aggregate gate — and the repository owns
+  #   WHAT ITS GATE RUNS, in package.json, where a change to it shows up in that
+  #   repository's own diff rather than in a workflow nobody reads.
+  # ⚠️ THE TRADE, STATED: a red X says \`check\` rather than naming the lane. \`bun run check\`
+  #   short-circuits on the first failure and its output names the lane, which is the same
+  #   signal a person gets locally.`;
+
+const WORKFLOWS_NOTE = `  # ★ \`workflow lint\` STAYS ITS OWN JOB on purpose: it needs no \`bun install\` at all
+  #   (actionlint is preloaded on the mini's job image — measured 5s end to end), so
+  #   folding it into \`check\` would make a YAML-only change pay the install for nothing.`;
+
+const ACTIONLINT_NOTE = `      # ⛔ THERE IS NO FIRST-PARTY actionlint ACTION, and the npm package by that name is
+      #   an unrelated wasm port with no \`bin\`. The vendor's own documented CI path is
+      #   \`download-actionlint.bash\` — but that script does NOT verify a checksum (read at
+      #   the v${ACTIONLINT_VERSION} tag, 2026-09-16: \`curl -L "$url" | tar xvz\`, no sha256sum anywhere).
+      #   rhysd's releases DO publish a \`_checksums.txt\` per version; this verifies against
+      #   that instead of trusting the tarball on receipt.
+      # ⚠️ ARCH FROM THE RUNNER, NOT HARD-CODED: the mini's runners are arm64, and an amd64
+      #   binary fails with "exec format error" (the checksum file lists both).`;
+
+const INSTALL_ACTIONLINT = `set -euo pipefail
+version=${ACTIONLINT_VERSION}
+if command -v actionlint >/dev/null 2>&1 &&
+  [ "$(actionlint -version 2>/dev/null | sed -n 1p)" = "\${version}" ]; then
+  cp "$(command -v actionlint)" ./actionlint
+  exit 0
+fi
+case "$(uname -m)" in
+  x86_64) arch=amd64 ;;
+  aarch64 | arm64) arch=arm64 ;;
+  *) echo "unsupported architecture $(uname -m)" >&2; exit 1 ;;
+esac
+file="actionlint_\${version}_linux_\${arch}.tar.gz"
+base="https://github.com/rhysd/actionlint/releases/download/v\${version}"
+curl -sSfLO "\${base}/\${file}"
+curl -sSfLO "\${base}/actionlint_\${version}_checksums.txt"
+grep " \${file}\\$" "actionlint_\${version}_checksums.txt" | sha256sum -c -
+tar xzf "\${file}" actionlint`;
+
+const AGGREGATE_NOTE = `  # ── The one check a branch rule can require ─────────────────────────────────
+  # ★ A single required check that depends on all of them. Without this, adding a job
+  #   means editing the branch ruleset too, and forgetting to means the new job is
+  #   advisory without anyone noticing.
+  # ⛔ FAILS ON ANYTHING OTHER THAN success, INCLUDING skipped. A job result has exactly
+  #   four values: success, failure, cancelled, skipped. Checking only the first two lets
+  #   a skipped job — a bad \`if:\` condition, a misconfigured dependency, a runner picking
+  #   up nothing — report this aggregate green with a required job never having run.`;
+
+const VERIFY = `if [ "\${{ contains(needs.*.result, 'failure') }}" = "true" ] || \\
+   [ "\${{ contains(needs.*.result, 'cancelled') }}" = "true" ] || \\
+   [ "\${{ contains(needs.*.result, 'skipped') }}" = "true" ]; then
+  echo "one or more required jobs did not succeed: \${{ toJSON(needs.*.result) }}" >&2
+  exit 1
+fi`;
+
+function prologue(): string {
+  return renderSteps(
+    [
+      { uses: CHECKOUT },
+      { uses: SETUP_BUN, with: { 'bun-version': BUN_VERSION } },
+      { run: 'bun install --frozen-lockfile' },
+    ],
+    3,
+  );
+}
+
+function renderExtraJob(job: ExtraJob, on: string): string {
+  const needs =
+    (job.needs ?? []).length === 0 ? '' : `    needs: [${(job.needs ?? []).join(', ')}]\n`;
+  const steps =
+    job.bun === false
+      ? renderSteps([{ uses: CHECKOUT }, ...job.steps], 3)
+      : [prologue(), renderSteps(job.steps, 3)].join('\n');
+  // ★ The stated reason is rendered into the file. A job nobody can explain is a job
+  //   nobody dares delete, so the explanation travels with it.
+  return `  # ★ NOT PART OF THE STANDARD SHAPE — ${job.reason}
+  ${job.id}:
+    name: ${job.name}
+${needs}    runs-on: ${on}
+    steps:
+${steps}
+`;
+}
+
+/** The whole `ci.yml` for a shape. */
+export function renderCi(shape: RepoShape): string {
+  const on = runsOn(shape.runner);
+  const extras = shape.extraJobs ?? [];
+  const needs = ['check', 'workflows', ...extras.map((job) => job.id)];
+
+  return `${HEADER}${runnerNote(shape)}${TRIGGER}
+jobs:
+${CHECK_NOTE}
+  check:
+    name: check
+    runs-on: ${on}
+    steps:
+${prologue()}
+${renderSteps([{ run: 'bun run check' }], 3)}
+
+${WORKFLOWS_NOTE}
+  workflows:
+    name: workflow lint
+    runs-on: ${on}
+    steps:
+${renderSteps([{ uses: CHECKOUT }], 3)}
+${ACTIONLINT_NOTE}
+${renderSteps([{ name: 'Install actionlint (checksum-verified)', run: INSTALL_ACTIONLINT }], 3)}
+${renderSteps([{ name: 'Lint workflows', run: './actionlint -color' }], 3)}
+
+${extras.map((job) => `${renderExtraJob(job, on)}\n`).join('')}${AGGREGATE_NOTE}
+  ci:
+    name: ci
+    if: always()
+    needs: [${needs.join(', ')}]
+    runs-on: ${on}
+    steps:
+${renderSteps([{ name: 'Verify every job succeeded', run: VERIFY }], 3)}
+`;
+}

package/src/repo-shape/companions.ts

@@ -0,0 +1,151 @@
+/**
+ * The three smaller rendered files: actionlint's config, the changeset config, and
+ * Dependabot.
+ *
+ * ★ EACH ONE WAS MEASURED BEFORE IT WAS RENDERED (2026-09-22, across 13 repositories):
+ *     · `.changeset/config.json` — byte-identical apart from the repository name in 11 of
+ *       13. The three that differed did so by accident: two pinned an older `$schema`
+ *       (3.1.4 against 4.0.1) and one used `@changesets/cli/changelog` instead of the
+ *       GitHub changelog everyone else had, which silently drops PR links from releases.
+ *     · `.github/actionlint.yaml` — 12 of 13 had it, with three wordings of one comment.
+ *       The one without it is the one repository still on `ubuntu-latest`, which is the
+ *       only case where it is genuinely not needed. That is an input, not an exception.
+ *     · `.github/dependabot.yml` — 1 of 14. Twelve repositories take no dependency or
+ *       Action updates at all, and nothing said so. Rendering it is the fix.
+ */
+import type { RepoShape } from './shape.ts';
+
+/**
+ * ⚠️ PINNED, NOT `latest`. `unpkg.com/@changesets/config@latest/schema.json` would change
+ *   what editors validate against without a commit, and the two repositories that drifted
+ *   here drifted by being pinned to different versions — not by being pinned.
+ */
+const CHANGESET_SCHEMA = '4.0.1';
+
+/**
+ * `.changeset/config.json`.
+ *
+ * ⛔ `privatePackages` IS WRITTEN ONLY FOR A REPOSITORY THAT DOES NOT PUBLISH, AND BOTH
+ *   OF ITS FIELDS ARE REQUIRED. `@changesets/cli` silently versions nothing when
+ *   `version` is absent, so a private repository without this key opens a Version
+ *   Packages PR that changes no version and tags no release — a release pipeline that
+ *   reports success and ships nothing.
+ */
+export function renderChangesetConfig(shape: RepoShape): string {
+  const config = {
+    $schema: `https://unpkg.com/@changesets/config@${CHANGESET_SCHEMA}/schema.json`,
+    // ★ `@changesets/changelog-github` over the built-in: it writes the pull request and
+    //   author into CHANGELOG.md, which is the difference between a changelog you can
+    //   audit and a list of sentences.
+    changelog: ['@changesets/changelog-github', { repo: `${shape.owner}/${shape.repository}` }],
+    commit: false,
+    fixed: [] as string[],
+    linked: [] as string[],
+    access: shape.publishes ? 'public' : 'restricted',
+    baseBranch: 'main',
+    updateInternalDependencies: 'patch',
+    ignore: [] as string[],
+    ...(shape.publishes ? {} : { privatePackages: { version: true, tag: false } }),
+  };
+  return `${JSON.stringify(config, undefined, 2)}\n`;
+}
+
+/**
+ * `.github/actionlint.yaml` — rendered only for a self-hosted runner.
+ *
+ * ★ DECLARED, NOT SUPPRESSED. actionlint's `runner-label` rule stays on, so a typo'd
+ *   label (`homeflare-mnii`) still fails the `workflow lint` job rather than silently
+ *   queueing a job no runner ever claims. Measured 2026-09-22 with actionlint 1.7.12: an
+ *   undeclared `homeflare-mini` is an error, not a warning, so this file is the reason
+ *   twelve repositories are green rather than a nicety.
+ */
+export function renderActionlintConfig(shape: RepoShape): string | undefined {
+  if (shape.runner !== 'mini') return undefined;
+  return `# actionlint's list of self-hosted runner labels (its \`runner-label\` check).
+#
+# 🤖 RENDERED BY @homeflare/config — DO NOT EDIT THIS FILE BY HAND.
+#    Refresh with \`bun run repo-shape:refresh\`.
+#
+# ★ DECLARED, NOT SUPPRESSED: the rule stays on, so a typo'd label (\`homeflare-mnii\`)
+#   still fails the \`workflow lint\` job rather than queueing a job no runner claims.
+#   \`homeflare-mini\` is the interim runner on the Mac mini (homeflare-mini's
+#   docs/ci-runner.md); setting this repository's shape to \`runner: 'github'\` removes
+#   this file with the \`runs-on\` that needed it.
+self-hosted-runner:
+  labels:
+    - homeflare-mini
+`;
+}
+
+/** `.github/dependabot.yml`. */
+export function renderDependabot(shape: RepoShape): string {
+  // ⚠️ `directories`, not `directory`, for bun: a workspace keeps a dependency in the
+  //   package that declares it, so pointing only at `/` leaves every `packages/*`
+  //   manifest unwatched — and the symptom is silence, not an error.
+  const bunDirs = shape.publishes ? ['/', '/packages/*'] : ['/'];
+  return `# Dependabot for ${shape.repository}.
+#
+# 🤖 RENDERED BY @homeflare/config — DO NOT EDIT THIS FILE BY HAND.
+#    Refresh with \`bun run repo-shape:refresh\`.
+#
+# ⛔ THIS FILE LIVES AT .github/dependabot.yml, NOT IN .github/workflows/. Dependabot is a
+#   platform feature, not an Action — a config placed among the workflows is silently
+#   ignored, and the symptom is simply that no pull requests ever arrive. Measured
+#   2026-09-22: 13 of 14 HomeFlare repositories had no dependabot config at all, so their
+#   Actions and their toolchain went stale invisibly, which is exactly how nothing fails.
+#
+# ★ WHY GROUPED RATHER THAN ONE PR PER DEPENDENCY. The default opens a pull request per
+#   outdated package; that is a trickle nobody reviews properly. Each group below is a set
+#   that is either safe to take together or needs deciding together.
+version: 2
+
+updates:
+  # ── The toolchain (bun.lock) ────────────────────────────────────────────────
+  - package-ecosystem: bun
+    directories:
+${bunDirs.map((dir) => `      - ${dir}`).join('\n')}
+    schedule:
+      interval: weekly
+      day: monday
+      time: '09:00'
+      timezone: America/New_York
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: 'chore'
+      include: scope
+    labels: [dependencies]
+    groups:
+      # oxfmt and oxlint move together and only affect style. Minor and patch bumps are
+      # noise unless they fail CI, which is what CI is for.
+      lint-and-format:
+        patterns: ['oxfmt', 'oxlint']
+        update-types: [minor, patch]
+
+      # ⚠️ MAJORS EXCLUDED DELIBERATELY. TypeScript majors change what typechecks;
+      #   changesets majors have renamed inputs and dropped compatibility (the action's v2
+      #   did both). These want reading, not merging on green.
+      build-tooling:
+        patterns: ['typescript', '@changesets/*', '@types/bun']
+        update-types: [minor, patch]
+
+  # ── The workflows themselves ────────────────────────────────────────────────
+  # ★ Actions go stale invisibly: nothing fails, they just keep running old code. The
+  #   estate's first workflows pinned checkout@v5 (current: v7) and changesets/action@v1
+  #   (current: v2, with every input renamed) — measured 2026-09-15.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '09:00'
+      timezone: America/New_York
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: 'ci'
+    labels: [dependencies, github-actions]
+    groups:
+      actions:
+        patterns: ['*']
+        update-types: [minor, patch]
+`;
+}