@homeflare/config 0.9.0 → 0.11.0

package/src/hooks/push-range.ts

@@ -0,0 +1,177 @@
+/**
+ * What a push changes: the base it is measured from, and the files between that base and
+ * the commit being pushed.
+ *
+ * ★ THE BASE COMES FROM GIT, NOT FROM A GUESS. A pre-push hook reads
+ *   `<local ref> <local sha> <remote ref> <remote sha>` on stdin. The remote sha is exactly
+ *   "what the remote has now", so a second push to a branch checks only what is new.
+ * 🔴 A BRANCH-NAME BASE IS VACUOUS ON THE BASE BRANCH. Measured in the house monorepo
+ *   2026-09-08: `turbo --affected` compares against `main`, so on `main` itself it selected
+ *   zero packages and a real two-commit push ran zero tests. Taking the base from stdin
+ *   cannot do that — the remote sha is never the commit being pushed.
+ * ⛔ AN UNKNOWN BASE WIDENS, IT NEVER NARROWS TO NOTHING. No merge base (a shallow clone, a
+ *   rewritten history), no remote-tracking branch: every lane runs, tests in full. A gate
+ *   whose base is unusable must do MORE work, never quietly run nothing.
+ */
+import { probe } from './report.ts';
+
+/** One line of git's pre-push stdin. */
+export type PushRef = {
+  readonly localRef: string;
+  readonly localSha: string;
+  readonly remoteRef: string;
+  readonly remoteSha: string;
+};
+
+export type PushScope =
+  /** The push changes no file (a deletion, or a branch at its base): nothing to check. */
+  | { readonly kind: 'empty'; readonly why: string }
+  /** Measured from `base`: `changed` is every path that differs between it and the tip. */
+  | {
+      readonly kind: 'scoped';
+      readonly base: string;
+      readonly changed: readonly string[];
+      readonly why: string;
+    }
+  /** No usable base: run every lane, tests in full. */
+  | { readonly kind: 'unscoped'; readonly why: string }
+  /** The pushed commit is not what is checked out, so the working tree cannot vouch for it. */
+  | { readonly kind: 'elsewhere'; readonly why: string };
+
+/** git's "no such ref" sentinel — 40 zeros (64 under SHA-256). */
+const ZERO = /^0+$/;
+
+export function parsePushRefs(stdin: string): readonly PushRef[] {
+  const refs: PushRef[] = [];
+  for (const line of stdin.split('\n')) {
+    const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+    if (localRef && localSha && remoteRef && remoteSha) {
+      refs.push({ localRef, localSha, remoteRef, remoteSha });
+    }
+  }
+  return refs;
+}
+
+const short = (sha: string): string => sha.slice(0, 9);
+
+async function ok(root: string, args: readonly string[]): Promise<boolean> {
+  return (await probe(['git', '-C', root, ...args])).code === 0;
+}
+
+async function out(root: string, args: readonly string[]): Promise<string | undefined> {
+  const result = await probe(['git', '-C', root, ...args]);
+  return result.code === 0 ? result.stdout.trim() : undefined;
+}
+
+/**
+ * The remote's default branch as a local ref: `<remote>/HEAD` when the clone recorded it,
+ * else `<remote>/main`, else `<remote>/master`.
+ * ⚠️ `refs/remotes/<remote>/HEAD` IS OFTEN ABSENT — `git clone` sets it, `git init` plus
+ *   `git remote add` does not — so the fallbacks are the common path, not the rare one.
+ */
+async function defaultBranch(root: string, remote: string): Promise<string | undefined> {
+  const head = await out(root, ['symbolic-ref', '--quiet', `refs/remotes/${remote}/HEAD`]);
+  if (head !== undefined && head !== '') return head;
+  for (const name of ['main', 'master']) {
+    const ref = `refs/remotes/${remote}/${name}`;
+    if (await ok(root, ['rev-parse', '--verify', '--quiet', ref])) return ref;
+  }
+  return undefined;
+}
+
+/**
+ * Where the pushed commit is measured from.
+ *
+ * ★ A FAST-FORWARD IS MEASURED FROM THE REMOTE SHA — only what this push adds.
+ * ⚠️ ANYTHING ELSE IS MEASURED FROM THE MERGE BASE WITH THE DEFAULT BRANCH: a new branch
+ *   (zero remote sha), a remote sha this clone has not fetched, or a force-push after a
+ *   rebase — where diffing against the old tip would drag in everything `main` gained since.
+ */
+async function baseFor(
+  root: string,
+  remote: string,
+  ref: PushRef,
+): Promise<{ base: string; why: string } | { why: string }> {
+  const { localSha, remoteSha } = ref;
+  if (
+    !ZERO.test(remoteSha) &&
+    (await ok(root, ['cat-file', '-e', `${remoteSha}^{commit}`])) &&
+    (await ok(root, ['merge-base', '--is-ancestor', remoteSha, localSha]))
+  ) {
+    return { base: remoteSha, why: `since ${short(remoteSha)}, what ${remote} has now` };
+  }
+  const branch = await defaultBranch(root, remote);
+  if (branch === undefined) return { why: `no ${remote}/main or ${remote}/master to measure from` };
+  const mergeBase = await out(root, ['merge-base', localSha, branch]);
+  if (mergeBase === undefined || mergeBase === '') {
+    return { why: `no merge base with ${branch} (a shallow clone, or unrelated history)` };
+  }
+  const name = branch.replace(/^refs\/remotes\//, '');
+  return { base: mergeBase, why: `since ${short(mergeBase)}, where this branch left ${name}` };
+}
+
+/**
+ * Resolve the push git described on stdin. With no stdin (a manual run) the push is
+ * `HEAD` to a new branch — measured from the merge base with the default branch.
+ * 🔴 THE LANES RUN ON THE WORKING TREE, SO ONLY A PUSH OF `HEAD` CAN BE CHECKED HERE. Found
+ *   in review 2026-09-23 and reproduced: `git push origin broken` from a clean `main`
+ *   measured the right files, then ran `bun test --changed` against `main`'s tree, found
+ *   nothing, and printed "passed". A ref that is not checked out now comes back
+ *   `elsewhere`, which the caller reports as NOT CHECKED — never as a pass. (The old
+ *   whole-`check` hook had the same blind spot; it just ran unrelated tests while in it.)
+ * ⚠️ WITH SEVERAL REFS, THE ONE AT `HEAD` IS MEASURED and the rest are named as unchecked.
+ */
+export async function pushScope(
+  root: string,
+  remote: string,
+  refs: readonly PushRef[],
+): Promise<PushScope> {
+  const pushed = refs.filter((ref) => !ZERO.test(ref.localSha));
+  if (refs.length > 0 && pushed.length === 0) {
+    return { kind: 'empty', why: 'this push only deletes refs' };
+  }
+  const head = await out(root, ['rev-parse', 'HEAD']);
+  const atHead = pushed.find((ref) => ref.localSha === head);
+  const others = pushed.filter((ref) => ref !== atHead).map((ref) => ref.localRef);
+  if (pushed.length > 0 && atHead === undefined) {
+    return {
+      kind: 'elsewhere',
+      why: `pushing ${others.join(', ')}, but the checkout is at ${short(head ?? '?')}`,
+    };
+  }
+  const ref = atHead ?? {
+    localRef: 'HEAD',
+    localSha: head ?? 'HEAD',
+    remoteRef: '',
+    remoteSha: '0'.repeat(40),
+  };
+  const found = await baseFor(root, remote, ref);
+  const also = others.length > 0 ? `; ${others.join(', ')} not checked here` : '';
+  if (!('base' in found)) return { kind: 'unscoped', why: `${found.why}${also}` };
+
+  const diff = await probe([
+    'git',
+    '-C',
+    root,
+    'diff',
+    '--name-only',
+    '-z',
+    found.base,
+    ref.localSha,
+  ]);
+  if (diff.code !== 0) return { kind: 'unscoped', why: `git diff ${short(found.base)} failed` };
+  const changed = diff.stdout.split('\0').filter((path) => path !== '');
+  if (changed.length === 0) return { kind: 'empty', why: `no file differs ${found.why}${also}` };
+  return { kind: 'scoped', base: found.base, changed, why: `${found.why}${also}` };
+}
+
+/**
+ * A path that changes what EVERY test runs on: a manifest, a lockfile, Bun's config, a
+ * tsconfig. Bun's `--changed` follows imports and none of these is imported — measured
+ * 2026-09-23, editing package.json selected 0 of 246 test files — so a push touching one
+ * runs the tests in full rather than none of them.
+ */
+export function changesEverything(path: string): boolean {
+  const name = path.split('/').pop() ?? '';
+  return /^(package\.json|bun\.lockb?|bunfig\.toml|tsconfig.*\.json)$/.test(name);
+}

package/src/hooks/report.ts

@@ -28,7 +28,7 @@ const BYPASS: Record<Hook, string> = {
  * ⛔ 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> {
+export function withoutGitEnv(): Record<string, string | undefined> {
   return Object.fromEntries(
     Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
   );
@@ -49,10 +49,34 @@ export async function run(cmd: readonly string[], isolated = false): Promise<num
 
 /** Capture a command's stdout. Used for git plumbing only. */
 export async function capture(cmd: readonly string[]): Promise<string> {
+  return (await probe(cmd)).stdout;
+}
+
+/** Capture a command's stdout AND its exit code — git plumbing that answers by status. */
+export async function probe(cmd: readonly string[]): Promise<{ code: number; stdout: string }> {
   const proc = Bun.spawn([...cmd], { stdout: 'pipe', stderr: 'ignore' });
-  const text = await new Response(proc.stdout).text();
-  await proc.exited;
-  return text;
+  const stdout = await new Response(proc.stdout).text();
+  return { code: await proc.exited, stdout };
+}
+
+/**
+ * Run one pre-push lane through `sh -c` at `root`, as `bun run` would run a script line.
+ *
+ * ⚠️ `node_modules/.bin` FIRST ON PATH, because a lane opened up from a script is no longer
+ *   run by `bun run`, which is what used to put it there — `vitest` or `oxfmt` in an expanded
+ *   script would otherwise be "command not found" on a machine without a global copy.
+ * 🔴 AND WITHOUT THE HOOK'S `GIT_*` — see `withoutGitEnv`.
+ */
+export async function runLane(command: string, root: string): Promise<number> {
+  const env = withoutGitEnv();
+  env['PATH'] = `${root}/node_modules/.bin:${env['PATH'] ?? ''}`;
+  const proc = Bun.spawn(['sh', '-c', command], {
+    cwd: root,
+    env,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  return await proc.exited;
 }
 
 /**
@@ -60,8 +84,9 @@ export async function capture(cmd: readonly string[]): Promise<string> {
  *
  * ⚠️ 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.
+ *   Git runs the hook with the caller's PATH, which has no `node_modules/.bin` (husky
+ *   used to add it; the hooks no longer run through husky), 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}`;

package/src/hooks/secrets.ts

@@ -0,0 +1,42 @@
+/**
+ * Refuse to commit anything that looks like a credential.
+ *
+ * ⛔ FIRST GATE, ALWAYS. A secret that reaches a public repository is compromised the moment
+ *   it is pushed — rotating it is the only remedy, and rewriting history does not help
+ *   because the object is already fetched and mirrored. Every other check can be fixed
+ *   after the fact; this one cannot. Moved here from homeflare-kit's own
+ *   scripts/hooks/secrets.ts (2026-09-23) so every repository commits under it, not one.
+ * ★ gitleaks IS THE TOOL, not a hand-rolled regex list. It ships hundreds of maintained rules
+ *   and an entropy engine, and it reads the repository's own `.gitleaks.toml` when there is
+ *   one; a homegrown pattern set covers the token shapes its author thought of.
+ * ⚠️ IT IS A GO BINARY, NOT AN npm PACKAGE — nothing in package.json can install it, so a
+ *   missing binary is explained rather than surfacing as "command not found".
+ * ⚠️ `git --staged`, NOT `protect`. Measured 2026-09-15 on gitleaks 8.30.1: `protect` still
+ *   runs, but the documented surface is `gitleaks git` / `dir` / `stdin`.
+ */
+import { fail, ok, run } from './report.ts';
+
+const INSTALL = 'brew install gitleaks — Linux: https://github.com/gitleaks/gitleaks/releases';
+
+export async function scanStagedSecrets(): Promise<void> {
+  // ⛔ NOT A SILENT SKIP. A secret scan that quietly does nothing is worse than none: it
+  //   reads, in a log and in a reviewer's head, as coverage that does not exist.
+  if (Bun.which('gitleaks') === null) {
+    fail(
+      'pre-commit',
+      'gitleaks is not installed, so the staged changes were NOT scanned',
+      INSTALL,
+    );
+  }
+  // `--redact`, so a real finding never prints the secret into a scrollback, a CI log, or an
+  // agent's context.
+  const code = await run(['gitleaks', 'git', '--staged', '--redact', '--no-banner', '.']);
+  if (code !== 0) {
+    fail(
+      'pre-commit',
+      'gitleaks found a secret in the staged changes',
+      'remove it, then ROTATE it — assume anything committed is already compromised',
+    );
+  }
+  ok('pre-commit: gitleaks found no secret in the staged changes');
+}

package/src/hooks.ts

@@ -6,43 +6,59 @@
  *   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".
+ * ★ TRACKED `.husky/`, RUN BY GIT THROUGH `core.hooksPath` — NOT husky's `.husky/_`. Since
+ *   2026-09-23 the mechanism is the one that reaches every worktree; activate.ts has the
+ *   measurement. The files keep the directory name the estate already uses.
+ * ★ PRE-PUSH IS SCOPED TO THE PUSH (push-range.ts, push-plan.ts): the repository's own
+ *   `check`, with `bun test` narrowed to the tests the pushed files can reach and the build
+ *   and smoke test left to CI. Many agents push to many repositories at once; a pre-push
+ *   that re-ran every suite was the one people learned to skip.
  *
  * Usage from a hook file — see `HUSKY_HOOK`:
  *
  *     bun node_modules/@homeflare/config/bin/hooks.ts pre-commit
  */
+import { activateHooks } from './hooks/activate.ts';
 import { preCommit, prePush } from './hooks/gates.ts';
-import { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks } from './hooks/install.ts';
+import { HOOK_NAMES, HUSKY_HOOK, PREPARE, installHooks, problemsInHooks } from './hooks/install.ts';
+import { type Lane, planLanes } from './hooks/push-plan.ts';
 import { type Hook, note, ok } from './hooks/report.ts';
 
-export { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks };
-export type { Hook };
+export { HOOK_NAMES, HUSKY_HOOK, PREPARE, activateHooks, installHooks, planLanes, problemsInHooks };
+export type { Hook, Lane };
 
 /** The commands `bin/hooks.ts` accepts. */
-export type Command = Hook | 'install';
+export type Command = Hook | 'install' | 'activate';
 
 export function isCommand(value: string): value is Command {
-  return value === 'pre-commit' || value === 'pre-push' || value === 'install';
+  return ['pre-commit', 'pre-push', 'install', 'activate'].includes(value);
 }
 
 /**
- * Run one hook, or install the wrappers.
+ * Run one hook, write the wrappers, or activate them.
  *
+ * `args` are git's own hook arguments (for `pre-push`: the remote name and URL) and
+ * `stdin` is what git wrote to the hook (for `pre-push`: the refs being pushed).
  * ⛔ 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> {
+export async function runCommand(
+  command: Command,
+  root: string,
+  args: readonly string[] = [],
+  stdin = '',
+): 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)');
+    note(`then set "prepare": "${PREPARE}" so every install activates them`);
+    return;
+  }
+  if (command === 'activate') {
+    const result = await activateHooks(root);
+    (result.active ? ok : note)(`homeflare hooks: ${result.message}`);
     return;
   }
   if (command === 'pre-commit') return await preCommit(root);
-  return await prePush(root);
+  return await prePush(root, args, stdin);
 }

package/src/repo-shape/automerge.ts

@@ -0,0 +1,144 @@
+/**
+ * `.github/workflows/dependabot-automerge.yml`, rendered.
+ *
+ * ★ THE OTHER HALF OF THE `homeflare` GROUP. Dependabot opens the bump; this arms GitHub's
+ *   own auto-merge on it; the branch ruleset's required checks (`ci`, `secret scan`)
+ *   decide whether it ever merges. Nothing here merges anything itself, and a merge
+ *   deploys nothing — every stack in the estate is deployed by hand.
+ *
+ * ⛔ `gh pr merge --auto` IS NOT ALWAYS "ARM". When the pull request is already CLEAN,
+ *   UNSTABLE or HAS_HOOKS it merges AT ONCE instead (cli/cli `pkg/cmd/pr/merge/merge.go`,
+ *   `isImmediatelyMergeable`, read at v2.101.0 — the version the mini's job image ships).
+ *   UNSTABLE is "mergeable, with a non-passing status", which is every pull request on a
+ *   branch whose rules require no check: before `check` has run, and even after it failed.
+ *   So the step reads the base branch's active rules first and refuses — a red check, never
+ *   a merge — when none requires a status check. Measured 2026-09-22: homeflare-builds (its
+ *   ruleset not deployed yet) and homeflare-desktop have none.
+ *
+ * ⛔ FIRST-PARTY ONLY: A `run:` STEP AND THE GitHub CLI, NO `uses:` AT ALL. GitHub's own
+ *   example ("Automating Dependabot with GitHub Actions") identifies the update with
+ *   `dependabot/fetch-metadata`, which the same page marks as "not certified by GitHub".
+ *   The group is identified by the branch Dependabot gives it instead, whose format is
+ *   dependabot-core's (`branch_namer/dependency_group_strategy.rb`, read at v0.397.0):
+ *   `<prefix>/<package manager>/<directory>/<group>-<10 hex MD5 digest>`, with the root
+ *   directory collapsing to nothing.
+ */
+import { HOMEFLARE_GROUP } from './dependabot.ts';
+import type { RepoShape } from './shape.ts';
+import { runsOn } from './shape.ts';
+import { renderSteps } from './yaml.ts';
+
+/**
+ * The branch prefix a job-level `if:` can test with `startsWith`. GitHub's expression
+ * language has no regex, so this is the cheap filter that keeps every other pull request
+ * from taking a runner slot; `GROUP_BRANCH` is the exact test inside the step.
+ */
+export const GROUP_BRANCH_PREFIX: string = `dependabot/bun/${HOMEFLARE_GROUP}-`;
+
+/**
+ * ⛔ EXACT, AND FAILS CLOSED. A solo update of `@homeflare/config` is
+ *   `dependabot/bun/homeflare/config-0.9.0` and a package named `homeflare-x` would be
+ *   `dependabot/bun/homeflare-x-1.2.3`; neither matches. If Dependabot ever changes its
+ *   format, the symptom is a bump that waits for a person — never one merged by mistake.
+ */
+export const GROUP_BRANCH: string = `^${GROUP_BRANCH_PREFIX}[0-9a-f]{10}$`;
+
+const HEADER = `# Arms auto-merge on Dependabot's @homeflare/* group, and on nothing else.
+#
+# 🤖 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\`.
+#
+# ★ HOW A KIT RELEASE ARRIVES: the \`${HOMEFLARE_GROUP}\` group in .github/dependabot.yml opens one
+#   pull request; this arms GitHub's auto-merge on it; the ruleset's required checks decide.
+#   Nothing here merges anything itself, and merging deploys nothing.
+# ⛔ NO THIRD-PARTY ACTION. GitHub's own example uses dependabot/fetch-metadata, which its
+#   docs mark "not certified by GitHub"; the group is recognised by its branch name instead.
+# ⛔ NO REQUIRED CHECK ON THE BASE BRANCH, NO ARMING: there \`gh pr merge --auto\` would merge
+#   at once, unchecked. The job fails instead, so the pull request waits for a person.
+# ⚠️ A RENDERER CHANGE STILL NEEDS A PERSON. When a kit release changes what @homeflare/config
+#   renders, the bump fails \`check\` (the drift test) and never goes green. Run
+#   \`bun run repo-shape:refresh\` on Dependabot's branch and push. ⛔ This workflow does not do
+#   it for you: a push made with GITHUB_TOKEN starts no workflow run, so a refreshed commit
+#   would never get the required checks and the pull request would wait forever.
+`;
+
+const TRIGGER = `name: dependabot auto-merge
+
+on:
+  pull_request:
+
+# ⛔ NOTHING AT THE TOP; the one job asks for exactly what \`gh pr merge --auto\` needs.
+permissions: {}
+
+concurrency:
+  group: automerge-\${{ github.ref }}
+  cancel-in-progress: true
+`;
+
+const JOB_NOTE = `  # ⛔ BOTH LOGINS, NOT EITHER. \`user.login\` is who opened the pull request; \`github.actor\` is
+  #   who started this run. A person pushing to Dependabot's branch changes the actor, so
+  #   their commit never arms anything; only Dependabot's own rebases do.`;
+
+const PERMISSIONS_NOTE = `    # ★ WHAT GitHub'S OWN EXAMPLE GRANTS FOR THIS STEP, AND NO MORE. A run Dependabot starts gets
+    #   a read-only GITHUB_TOKEN unless the workflow raises it ("Troubleshooting Dependabot on
+    #   GitHub Actions" → "Changing GITHUB_TOKEN permissions").`;
+
+const ARM = `set -euo pipefail
+if [[ ! "$HEAD_REF" =~ ${GROUP_BRANCH} ]]; then
+  echo "::notice::$HEAD_REF is not the ${HOMEFLARE_GROUP} group's branch; auto-merge not armed"
+  exit 0
+fi
+# ⛔ gh merges a CLEAN or UNSTABLE pull request at once rather than arming it. Only a branch
+#   rule that requires a status check keeps it BLOCKED until the checks have passed.
+required=$(gh api "repos/$GITHUB_REPOSITORY/rules/branches/$BASE_REF" \\
+  --jq '[.[] | select(.type == "required_status_checks")] | length')
+if [ "$required" = 0 ]; then
+  echo "::error::$BASE_REF requires no status check, so gh would merge at once; auto-merge not armed"
+  exit 1
+fi
+# ★ --squash: the house repositories allow squash merges only (declareRepoPolicy).
+gh pr merge --auto --squash "$PR_URL"`;
+
+/** The whole `dependabot-automerge.yml` for a shape. */
+export function renderAutomerge(shape: RepoShape): string {
+  // ⚠️ GitHub ACTIONS EXPRESSIONS, NOT TEMPLATE LITERALS: the runner interpolates `${{ … }}`
+  //   at job time, so they must reach the file verbatim (see security.ts for the same note).
+  // oxlint-disable-next-line no-template-curly-in-string
+  const headRef = '${{ github.head_ref }}';
+  // oxlint-disable-next-line no-template-curly-in-string
+  const baseRef = '${{ github.base_ref }}';
+  // oxlint-disable-next-line no-template-curly-in-string
+  const prUrl = '${{ github.event.pull_request.html_url }}';
+  // oxlint-disable-next-line no-template-curly-in-string
+  const token = '${{ secrets.GITHUB_TOKEN }}';
+  const condition = [
+    "github.event.pull_request.user.login == 'dependabot[bot]'",
+    "github.actor == 'dependabot[bot]'",
+    `startsWith(github.head_ref, '${GROUP_BRANCH_PREFIX}')`,
+  ].join(' && ');
+
+  return `${HEADER}
+${TRIGGER}
+jobs:
+${JOB_NOTE}
+  arm:
+    name: arm auto-merge
+    if: ${condition}
+    runs-on: ${runsOn(shape.runner)}
+${PERMISSIONS_NOTE}
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+${renderSteps(
+  [
+    {
+      env: { BASE_REF: baseRef, GH_TOKEN: token, HEAD_REF: headRef, PR_URL: prUrl },
+      name: 'Arm auto-merge on the homeflare group',
+      run: ARM,
+    },
+  ],
+  3,
+)}
+`;
+}

package/src/repo-shape/ci.ts

@@ -10,8 +10,8 @@
  *   `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 type { ExtraJob, JobStep, RepoShape } from './shape.ts';
+import { nodeMajor, runsOn } from './shape.ts';
 import { renderSteps } from './yaml.ts';
 
 /** Bun the whole estate is pinned to. One line, one place. */
@@ -21,6 +21,7 @@ export const ACTIONLINT_VERSION = '1.7.12';
 
 const CHECKOUT = 'actions/checkout@v7';
 const SETUP_BUN = 'oven-sh/setup-bun@v2';
+const SETUP_NODE = 'actions/setup-node@v6';
 
 function runnerNote(shape: RepoShape): string {
   if (shape.runner !== 'mini') {
@@ -148,31 +149,49 @@ const VERIFY = `if [ "\${{ contains(needs.*.result, 'failure') }}" = "true" ] ||
   exit 1
 fi`;
 
-function prologue(): string {
-  return renderSteps(
-    [
-      { uses: CHECKOUT },
-      { uses: SETUP_BUN, with: { 'bun-version': BUN_VERSION } },
-      { run: 'bun install --frozen-lockfile' },
-    ],
-    3,
-  );
+const NODE_NOTE = `      # ⛔ REAL NODE, NOT BUN'S SHIM, AND ONLY WHERE THE GATE NEEDS IT. The mini's job
+      #   image has no node on PATH (ubuntu-latest always did), so a repository whose own
+      #   \`check\` spawns \`node\` — or whose framework demands a Node runtime — fails with
+      #   \`Executable not found in $PATH: "node"\` without this. Declared as \`node:\` in
+      #   repo-shape.ts, so it is one input rather than a hand-edited block per repository.
+      # ⚠️ NO PACKAGE-MANAGER CACHE: bun does the installing, so priming npm's cache costs
+      #   time and caches nothing anything here reads.`;
+
+function prologue(shape: RepoShape): string {
+  const node = nodeMajor(shape);
+  const bun: JobStep[] = [
+    { uses: SETUP_BUN, with: { 'bun-version': BUN_VERSION } },
+    { run: 'bun install --frozen-lockfile' },
+  ];
+  if (node === undefined) return renderSteps([{ uses: CHECKOUT }, ...bun], 3);
+  return [
+    renderSteps([{ uses: CHECKOUT }], 3),
+    NODE_NOTE,
+    renderSteps(
+      [{ uses: SETUP_NODE, with: { 'node-version': node, 'package-manager-cache': 'false' } }],
+      3,
+    ),
+    renderSteps(bun, 3),
+  ].join('\n');
 }
 
-function renderExtraJob(job: ExtraJob, on: string): string {
+function renderExtraJob(job: ExtraJob, shape: RepoShape, on: string): string {
   const needs =
     (job.needs ?? []).length === 0 ? '' : `    needs: [${(job.needs ?? []).join(', ')}]\n`;
+  // ★ A TIMEOUT IS THE JOB'S, NOT THE SHAPE'S. Only a job that starts something with its
+  //   own wait needs one, and it is rendered where a reader looks for it.
+  const timeout = job.timeout === undefined ? '' : `    timeout-minutes: ${job.timeout}\n`;
   const steps =
     job.bun === false
       ? renderSteps([{ uses: CHECKOUT }, ...job.steps], 3)
-      : [prologue(), renderSteps(job.steps, 3)].join('\n');
+      : [prologue(shape), 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:
+${timeout}    steps:
 ${steps}
 `;
 }
@@ -190,7 +209,7 @@ ${CHECK_NOTE}
     name: check
     runs-on: ${on}
     steps:
-${prologue()}
+${prologue(shape)}
 ${renderSteps([{ run: 'bun run check' }], 3)}
 
 ${WORKFLOWS_NOTE}
@@ -203,7 +222,7 @@ ${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}
+${extras.map((job) => `${renderExtraJob(job, shape, on)}\n`).join('')}${AGGREGATE_NOTE}
   ci:
     name: ci
     if: always()