@homeflare/config 0.9.0 → 0.11.0

package/src/repo-shape/companions.ts

@@ -1,6 +1,6 @@
 /**
- * The three smaller rendered files: actionlint's config, the changeset config, and
- * Dependabot.
+ * The two smaller rendered files: actionlint's config and the changeset config.
+ * (Dependabot was the third; it grew a group and a schedule rule, so it is `dependabot.ts`.)
  *
  * ★ 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
@@ -10,8 +10,6 @@
  *     · `.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';
 
@@ -76,76 +74,3 @@ self-hosted-runner:
     - 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]
-`;
-}

package/src/repo-shape/dependabot.ts

@@ -0,0 +1,136 @@
+/**
+ * `.github/dependabot.yml`, rendered — and the one group that carries kit releases.
+ *
+ * ★ MEASURED BEFORE IT WAS RENDERED (2026-09-22): 1 of 14 repositories had a Dependabot
+ *   config. Twelve took no dependency or Action updates at all, and nothing said so.
+ *
+ * ★ THE `homeflare` GROUP IS HOW A KIT RELEASE REACHES A CONSUMER (Tim, 2026-09-23:
+ *   "Dependabot, grouped", checked daily, merged on green). Measured the same day, the
+ *   leg nobody automated had drifted: proxmox and mini pinned `@homeflare/alchemy` 0.13.0
+ *   while the kit had published 0.19.1. `automerge.ts` renders the workflow that arms
+ *   auto-merge on this group's pull request and on nothing else.
+ *
+ * Every Dependabot claim below was read from GitHub's docs or dependabot-core's source on
+ * 2026-09-22 (dependabot-core v0.397.0); `docs/repo-shape-dependabot.md` has the citations.
+ */
+import type { RepoShape } from './shape.ts';
+
+/**
+ * The group's identifier. ⛔ IT IS ALSO HALF OF A BRANCH NAME the auto-merge workflow
+ *   matches — dependabot-core names a group's branch `dependabot/bun/<group>-<10 hex>`
+ *   (branch_namer/dependency_group_strategy.rb) — so it is exported, not retyped there.
+ *   Dependabot requires an identifier that starts and ends with a letter.
+ */
+export const HOMEFLARE_GROUP = 'homeflare';
+
+/** The first-party scope. Every package the kit publishes is under it. */
+export const HOMEFLARE_PATTERN = '@homeflare/*';
+
+/**
+ * ★ SEVEN DAYS FOR THIRD-PARTY VERSIONS. The bun block has to run daily for the kit's sake
+ *   (see below), so the weekly pace the estate had for everything else is kept by age
+ *   instead of by calendar: a third-party release is proposed once it is a week old. That
+ *   is also the supply-chain half — a compromised release is usually yanked within days.
+ */
+export const THIRD_PARTY_COOLDOWN_DAYS = 7;
+
+/** `.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.
+#
+# ★ THE BILLING LOCK DOES NOT STOP THIS FILE. Dependabot runs as a GitHub-hosted "dynamic"
+#   workflow that GitHub's docs say "does not count towards your included GitHub Actions
+#   minutes"; measured 2026-09-22, a private estate repository's Dependabot job got a hosted
+#   runner 86 minutes after that account's ordinary hosted jobs were refused for billing.
+#   It cannot use the mini anyway: a self-hosted Dependabot runner must be Linux x64 with
+#   Docker, and the mini's runners are arm64 containers with no Docker socket.
+version: 2
+
+updates:
+  # ── The toolchain (bun.lock) ────────────────────────────────────────────────
+  # ⚠️ BLOCKED UPSTREAM, 2026-09-22: bun 1.4 writes bun.lock \`lockfileVersion\` 2 and
+  #   Dependabot's updater bundles bun 1.3.14, which reads up to 1, so this block fails in
+  #   every estate repository with "Unsupported bun.lock 'lockfileVersion' 2". The fix is
+  #   dependabot/dependabot-core pull request 16071. The github-actions block is unaffected.
+  # ⛔ ONE BUN BLOCK, SO ONE SCHEDULE. Dependabot refuses two blocks for one ecosystem and
+  #   target branch whose directories overlap, so the \`homeflare\` group cannot be daily
+  #   while the rest stays weekly. The block is daily; \`cooldown\` slows the rest.
+  - package-ecosystem: bun
+    directories:
+${bunDirs.map((dir) => `      - ${dir}`).join('\n')}
+    schedule:
+      # ⚠️ Dependabot's \`daily\` is Monday to Friday; a weekend kit release lands on Monday.
+      interval: daily
+      time: '09:00'
+      timezone: America/New_York
+    # ⛔ THE EXCLUDE IS NOT OPTIONAL. Dependabot applies a 3-day cooldown to every version
+    #   update even when this key is absent, so without it a kit release would wait three
+    #   days before its bump opened — and "daily" would quietly mean "three days late".
+    cooldown:
+      default-days: ${THIRD_PARTY_COOLDOWN_DAYS}
+      exclude: ['${HOMEFLARE_PATTERN}']
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: 'chore'
+      include: scope
+    labels: [dependencies]
+    groups:
+      # ★ FIRST, AND EVERY UPDATE TYPE. A kit release is one set of packages built to work
+      #   together, so they move as one pull request; \`bun run check\` is what reads it, and
+      #   .github/workflows/dependabot-automerge.yml merges it when that is green.
+      #   ⚠️ A release that changes what @homeflare/config renders fails the drift test here
+      #   by design; \`bun run repo-shape:refresh\` on the branch is the one-command fix.
+      ${HOMEFLARE_GROUP}:
+        patterns: ['${HOMEFLARE_PATTERN}']
+
+      # 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]
+`;
+}

package/src/repo-shape/guards.ts

@@ -0,0 +1,68 @@
+/**
+ * The runtime guards `repo-shape` needs and its types cannot express.
+ *
+ * ★ EXTRACTED FROM `shape.ts`, NOT INVENTED HERE. The types carry one half of the
+ *   contract — `Stated<R>` refuses an empty or computed reason at compile time — and
+ *   these carry the other half: the cases a literal type still lets through. Keeping
+ *   them in one file is what lets `shape.ts` stay the declaration and nothing else.
+ *
+ * ⚠️ EVERY MESSAGE STARTS `repo-shape:` AND NAMES THE FIELD. These throw at render or at
+ *   declaration, far from the workflow file they would otherwise break at job time, so
+ *   the message is the only thing pointing back at the call that caused it.
+ */
+
+const SENTENCE = 12;
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+/**
+ * ⛔ A MAJOR, NOT A RANGE, AND NOT A FLOAT. `actions/setup-node` takes `node-version: 24`
+ *   and resolves the newest 24.x; a fractional or negative value renders YAML the action
+ *   accepts and then fails to resolve, mid-job, on the runner.
+ */
+export function requireMajor(value: number): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`repo-shape: node must be a positive integer major, got ${value}`);
+  }
+  return value;
+}
+
+/** `timeout-minutes` must be a positive whole number of minutes. */
+export function requireMinutes(value: number): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`repo-shape: timeout must be a positive whole minute count, got ${value}`);
+  }
+  return value;
+}
+
+export 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;
+}

package/src/repo-shape/render.ts

@@ -20,8 +20,10 @@
  *     test lives in `packages/alchemy/tests/repo-shape-policy.test.ts`, which is the one
  *     place that imports both.
  */
+import { renderAutomerge } from './automerge.ts';
 import { renderCi } from './ci.ts';
-import { renderActionlintConfig, renderChangesetConfig, renderDependabot } from './companions.ts';
+import { renderActionlintConfig, renderChangesetConfig } from './companions.ts';
+import { renderDependabot } from './dependabot.ts';
 import { renderSecurity } from './security.ts';
 import type { RenderedPath, RepoShape } from './shape.ts';
 
@@ -66,6 +68,7 @@ export function renderRepoShape(shape: RepoShape): RenderedRepo {
     '.changeset/config.json': renderChangesetConfig(shape),
     '.github/dependabot.yml': renderDependabot(shape),
     '.github/workflows/ci.yml': renderCi(shape),
+    '.github/workflows/dependabot-automerge.yml': renderAutomerge(shape),
     '.github/workflows/security.yml': renderSecurity(shape),
   };
 
@@ -84,5 +87,6 @@ export const RENDERED_PATHS: readonly RenderedPath[] = [
   '.github/actionlint.yaml',
   '.github/dependabot.yml',
   '.github/workflows/ci.yml',
+  '.github/workflows/dependabot-automerge.yml',
   '.github/workflows/security.yml',
 ];

package/src/repo-shape/shape.ts

@@ -22,6 +22,15 @@
  *   has to be written at the exception. See `Stated`.
  */
 
+import {
+  requireIsoDate,
+  requireJobId,
+  requireMajor,
+  requireMinutes,
+  requireNonEmpty,
+  requireSentence,
+} from './guards.ts';
+
 /** Where a repository's jobs run. */
 export type RepoRunner =
   /**
@@ -77,6 +86,7 @@ export type RenderedPath =
   | '.github/actionlint.yaml'
   | '.github/dependabot.yml'
   | '.github/workflows/ci.yml'
+  | '.github/workflows/dependabot-automerge.yml'
   | '.github/workflows/security.yml';
 
 export interface RepoShapeException {
@@ -133,11 +143,23 @@ export interface ExtraJob {
   readonly needs?: readonly string[];
   /** `false` skips the rendered bun prologue — for a job that needs another toolchain. */
   readonly bun?: boolean;
+  /**
+   * `timeout-minutes:` for this job. Omitted takes GitHub's 360-minute default.
+   *
+   * ⚠️ AN INPUT BECAUSE A HUNG JOB IS NOT A FAILED JOB. Measured 2026-09-22:
+   *   homeflare-blog's `runtime` job drives Playwright against a local workerd, and a
+   *   browser that never reaches its first paint holds a self-hosted slot for six hours
+   *   rather than reporting red. On a 3-slot pool that is the whole pool. Only a job
+   *   that starts something with its own wait — a browser, a server, a container — needs
+   *   this; `check` does not, because `bun run check` exits.
+   */
+  readonly timeout?: number;
 }
 
-interface ExtraJobInput extends Omit<ExtraJob, 'needs' | 'bun'> {
+interface ExtraJobInput extends Omit<ExtraJob, 'needs' | 'bun' | 'timeout'> {
   readonly needs?: readonly string[];
   readonly bun?: boolean;
+  readonly timeout?: number;
 }
 
 /**
@@ -160,6 +182,7 @@ export function extraJob<const J extends ExtraJobInput>(
     needs: [...(job.needs ?? [])],
     reason: requireSentence('reason', job.reason),
     steps: [...job.steps],
+    ...(job.timeout === undefined ? {} : { timeout: requireMinutes(job.timeout) }),
   };
 }
 
@@ -176,46 +199,39 @@ export interface RepoShape {
    * that differ between `homeflare-kit` and every other repository.
    */
   readonly publishes: boolean;
+  /**
+   * Node major to install before Bun, for a repository whose own gate needs a real
+   * `node` on `PATH`. Omit it — twelve of fourteen repositories are Bun-only.
+   *
+   * ⛔ AN INPUT, NOT AN EXCEPTION, AND THE MEASUREMENT SAYS WHY. The mini's job image
+   *   carries no node at all (ubuntu-latest always did), so a Bun-only prologue is right
+   *   for most of the estate and *silently wrong* for two repositories:
+   *     · homeflare-alerts — tests/alchemy-import.test.ts spawns `node` to prove the
+   *       modules load the way the Alchemy CLI (`node …/cli.js`) loads them. Without it,
+   *       three tests fail with `Executable not found in $PATH: "node"` (measured on the
+   *       runner, 2026-09-22).
+   *     · homeflare-blog — Payload requires Node >= 24.15, so every lane needs it.
+   *   Both repositories carried the same hand-written `actions/setup-node@v6` block
+   *   before this existed. Excepting `ci.yml` instead would hand the estate's two most
+   *   complicated CI files back to hand-editing, which is the opposite of the point.
+   *
+   * ⚠️ `package-manager-cache: false` IS RENDERED WITH IT. Bun does the installing here;
+   *   letting setup-node prime an npm cache costs time and caches nothing anyone reads.
+   */
+  readonly node?: number;
   /** 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;
+/**
+ * The validated Node major this shape asks for, or `undefined` for a Bun-only prologue.
+ * ★ `RepoShape` is a plain object, so this is where `node:` is checked — at render, not
+ *   at declaration. A bad value fails the refresh rather than the job.
+ */
+export function nodeMajor(shape: RepoShape): number | undefined {
+  return shape.node === undefined ? undefined : requireMajor(shape.node);
 }
 
 /** `runs-on:` for a runner. */

package/src/repo-shape.ts

@@ -17,7 +17,8 @@
  * That one file gives the repository:
  *
  *   · its FILES     — `bun run repo-shape:refresh` writes ci.yml, security.yml,
- *                     actionlint.yaml, dependabot.yml and the changeset config;
+ *                     dependabot-automerge.yml, actionlint.yaml, dependabot.yml and
+ *                     the changeset config;
  *   · its DRIFT GATE — a `bun:test` calling `driftInRepoShape` fails on a hand edit;
  *   · its SETTINGS  — `renderRepoShape(shape).policy` is the options object
  *                     `@homeflare/alchemy`'s `declareRepoPolicy` takes, so the ruleset
@@ -33,12 +34,15 @@
  *   including the ones with no Alchemy stack, so it belongs to the package they all
  *   already have — and it takes no dependency on Alchemy or Effect to get there.
  */
+export { GROUP_BRANCH, GROUP_BRANCH_PREFIX, renderAutomerge } from './repo-shape/automerge.ts';
 export { renderCi, ACTIONLINT_VERSION, BUN_VERSION } from './repo-shape/ci.ts';
+export { renderActionlintConfig, renderChangesetConfig } from './repo-shape/companions.ts';
 export {
-  renderActionlintConfig,
-  renderChangesetConfig,
+  HOMEFLARE_GROUP,
+  HOMEFLARE_PATTERN,
   renderDependabot,
-} from './repo-shape/companions.ts';
+  THIRD_PARTY_COOLDOWN_DAYS,
+} from './repo-shape/dependabot.ts';
 export {
   type DriftReport,
   type Problem,