@homeflare/config 0.11.1 → 0.12.1

package/src/repo-shape/refresh.ts

@@ -12,9 +12,17 @@
  * ⚠️ 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.
+ *
+ * ⚠️ IT DELETES A RETIRED FILE ONLY WHEN IT CAN PROVE IT RENDERED IT. `RETIRED_FILES`
+ *   (`retired.ts`) names every path this package used to render; `wasRenderedByUs` is the
+ *   proof — the file still carries the generated-file header. A retired path present
+ *   without that header is left alone and reported as refused, on the same reasoning as
+ *   never overwriting an excepted file: this writer only ever removes what it is sure is
+ *   its own.
  */
 import { REFRESH_COMMAND, driftInRepoShape, exceptionSummary } from './drift.ts';
 import { renderRepoShape } from './render.ts';
+import { RETIRED_FILES, wasRenderedByUs } from './retired.ts';
 import { type RepoShape, isExcepted } from './shape.ts';
 import type { RenderedPath } from './shape.ts';
 
@@ -25,9 +33,13 @@ export interface RefreshResult {
   readonly unchanged: readonly string[];
   /** Paths skipped because the shape declares an exception for them. */
   readonly skipped: readonly string[];
+  /** Retired paths deleted because they still carried the generated-file header. */
+  readonly removed: readonly string[];
+  /** Retired paths left alone because they did not — provably hand-written, not ours. */
+  readonly refused: readonly string[];
 }
 
-/** Write a repository's rendered files into `projectDir`. */
+/** Write a repository's rendered files into `projectDir`, and clear its rendered fossils. */
 export async function refreshRepoShape(
   projectDir: string,
   shape: RepoShape,
@@ -52,7 +64,36 @@ export async function refreshRepoShape(
     written.push(path);
   }
 
-  return { skipped, unchanged, written };
+  const { refused, removed } = await clearRetiredFiles(projectDir);
+
+  return { refused, removed, skipped, unchanged, written };
+}
+
+/**
+ * Delete every retired path this package can prove it rendered; leave every other one, and
+ * say so. A path absent from `projectDir` is neither removed nor refused — there is
+ * nothing there to have an opinion about.
+ */
+async function clearRetiredFiles(
+  projectDir: string,
+): Promise<{ removed: string[]; refused: string[] }> {
+  const removed: string[] = [];
+  const refused: string[] = [];
+
+  for (const retiredFile of RETIRED_FILES) {
+    const target = `${projectDir}/${retiredFile.path}`;
+    const file = Bun.file(target);
+    if (!(await file.exists())) continue;
+
+    if (wasRenderedByUs(await file.text())) {
+      await file.delete();
+      removed.push(retiredFile.path);
+    } else {
+      refused.push(retiredFile.path);
+    }
+  }
+
+  return { refused, removed };
 }
 
 /**
@@ -108,6 +149,18 @@ export async function repoShapeCli(
     ...result.written.map((path) => `wrote    ${path}`),
     ...result.unchanged.map((path) => `ok       ${path}`),
     ...result.skipped.map((path) => `excepted ${path}`),
+    ...result.removed.map((path) => `removed  ${path} (retired; carried our header)`),
   ]);
+  // ★ ON ITS OWN LINE, TO STDERR: a refused retired file is the one outcome here that
+  //   still needs a person. `--check` (above) keeps failing on it — it reports any retired
+  //   path that is present, proof or not — so this is not the only place it is said, but
+  //   it is the only place that says WHY refresh did not just fix it.
+  await say(
+    Bun.stderr,
+    result.refused.map(
+      (path) =>
+        `refused  ${path} — present but not provably ours; not deleted. See docs/repo-shape-retired.md.`,
+    ),
+  );
   return 0;
 }

package/src/repo-shape/render.ts

@@ -20,7 +20,6 @@
  *     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 } from './companions.ts';
 import { renderDependabot } from './dependabot.ts';
@@ -68,7 +67,6 @@ 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),
   };
 
@@ -87,6 +85,5 @@ 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/retired.ts

@@ -0,0 +1,113 @@
+/**
+ * Rendered paths this package stopped rendering — the "no fossils" list.
+ *
+ * ★ WHY THIS EXISTS. `renderRepoShape` only emits the files a shape asks for today; it
+ *   never says what it used to emit, and `refreshRepoShape` only writes what it renders —
+ *   so a file retired from the renderer was never deleted by a refresh. It just stopped
+ *   being updated, silently, forever, in every repository that had already taken it.
+ *
+ *   MEASURED 2026-09-24: `@homeflare/config` 0.12.0 (kit PR 199) stopped rendering
+ *   `.github/workflows/dependabot-automerge.yml`. Every consumer that had refreshed to
+ *   0.12.0 before this module existed (homeflare-wiki bump PR 19, homeflare-mini bump
+ *   PR 47) kept the dead file, and `driftInRepoShape` never said so — it only compares
+ *   paths the CURRENT shape renders, and a retired path is not one of those.
+ *
+ * ⛔ RETIRING A PATH IS A ONE-WAY DOOR, NOT A RENAME. Once a path is here it can never
+ *   become a `RenderedPath` again: `render.ts` would start writing a file this module is
+ *   also trying to delete, and every refresh would fight itself. Give the replacement a
+ *   new path instead. `repo-shape-retired.test.ts` asserts the two lists never overlap.
+ *
+ * ⚠️ DELETION IS GATED ON PROOF, NOT ON THE PATH ALONE. A repository can have a
+ *   hand-written file sitting at the exact path a retired renderer used to own — a fork of
+ *   the old rendered file, kept on purpose, or unrelated content that just landed there.
+ *   `wasRenderedByUs` is the proof: every renderer in this directory writes the
+ *   `🤖 RENDERED BY @homeflare/config` line into its header (grep the directory for it),
+ *   and that line is the one thing a hand-written file has no reason to contain.
+ *   `refreshRepoShape` deletes a retired path only when the line is present; otherwise it
+ *   refuses and reports the path, the same way it refuses to overwrite an excepted file.
+ */
+import { requireSemver, requireSentence } from './guards.ts';
+
+/**
+ * A path `@homeflare/config` no longer renders, but may still find committed in a
+ * repository that refreshed before the retirement. Extend this union at the same time a
+ * path is added to `RETIRED_FILES` below — never reuse one already there.
+ */
+export type RetiredPath = '.github/workflows/dependabot-automerge.yml';
+
+export interface RetiredFile {
+  /** The path this package rendered, once. */
+  readonly path: RetiredPath;
+  /** The `@homeflare/config` version whose release stopped rendering it. */
+  readonly retiredIn: string;
+  /** Why, and which kit change did it — written at the retirement, like `except()`'s reason. */
+  readonly reason: string;
+}
+
+function retire(file: RetiredFile): RetiredFile {
+  return {
+    path: file.path,
+    reason: requireSentence('retired reason', file.reason),
+    retiredIn: requireSemver(file.retiredIn),
+  };
+}
+
+/** Every path `@homeflare/config` used to render, oldest retirement first. */
+export const RETIRED_FILES: readonly RetiredFile[] = [
+  retire({
+    path: '.github/workflows/dependabot-automerge.yml',
+    reason:
+      'kit PR 199 retired the Dependabot @homeflare group; taslabs-net/homeflare-bumper ' +
+      "carries a kit release into each consumer now, over the kit's own release workflow",
+    retiredIn: '0.12.0',
+  }),
+];
+
+/**
+ * The substring every generated file's header has carried since this package's first
+ * renderer. Kept independent of the four current renderers' own copies of this text
+ * (`ci.ts`, `security.ts`, `dependabot.ts`, `companions.ts`) on purpose: a future wording
+ * change to the live header must not stop this module recognising a file rendered under
+ * the old one.
+ */
+export const GENERATED_FILE_MARKER = '🤖 RENDERED BY @homeflare/config';
+
+/**
+ * Whether `content` is provably a file this package once wrote.
+ *
+ * ⚠️ THE MARKER HAS TO START A LINE OF ITS OWN, NOT MERELY OCCUR SOMEWHERE IN THE TEXT.
+ *   Every real header carries it as a whole comment line — `# 🤖 RENDERED BY
+ *   @homeflare/config — DO NOT EDIT…`, third line in every renderer in this directory, so
+ *   this does not require it to be the FIRST line — but a bare `content.includes(...)`
+ *   would also match a hand-written file that merely *talks about* the marker, e.g. a
+ *   comment reading "this file used to be 🤖 RENDERED BY @homeflare/config before it was
+ *   retired; keeping it by hand now" — adversarial review, 2026-09-24, caught this exact
+ *   case before it shipped. Requiring the marker at the start of a trimmed line is what a
+ *   sentence built around it, rather than a header line consisting of it, cannot satisfy.
+ *   `repo-shape-retired.test.ts` asserts the mid-sentence form stays refused.
+ *
+ * ⚠️ STILL A PREFIX CHECK ON THAT LINE, NOT A FULL-LINE EXACT MATCH. The retired renderer
+ *   varied its trailing header prose by `shape.runner` and by repository name, and a
+ *   future wording change to what follows the marker on a live renderer's header must not
+ *   stop this recognising a file rendered under the old wording — only the marker itself,
+ *   `🤖 RENDERED BY @homeflare/config`, has been constant across every renderer this
+ *   package has ever shipped.
+ */
+export function wasRenderedByUs(content: string): boolean {
+  return content
+    .split('\n')
+    .some((line) => line.trimStart().startsWith(`# ${GENERATED_FILE_MARKER}`));
+}
+
+/**
+ * The message `driftInRepoShape` reports for a retired path that is still present, and
+ * `repoShapeCli --check` prints verbatim. Names the fix command either way — whether that
+ * command can actually remove the file depends on `wasRenderedByUs`, which only
+ * `refreshRepoShape` (holding the file's contents) can decide.
+ */
+export function retiredFileProblem(file: RetiredFile): string {
+  return (
+    `${file.path}: retired in @homeflare/config@${file.retiredIn} (${file.reason}) ` +
+    'but still present — run `bun run repo-shape:refresh` to remove it'
+  );
+}

package/src/repo-shape/shape.ts

@@ -86,7 +86,6 @@ 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 {

package/src/repo-shape.ts

@@ -17,8 +17,7 @@
  * That one file gives the repository:
  *
  *   · its FILES     — `bun run repo-shape:refresh` writes ci.yml, security.yml,
- *                     dependabot-automerge.yml, actionlint.yaml, dependabot.yml and
- *                     the changeset config;
+ *                     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
@@ -34,11 +33,9 @@
  *   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 {
-  HOMEFLARE_GROUP,
   HOMEFLARE_PATTERN,
   renderDependabot,
   THIRD_PARTY_COOLDOWN_DAYS,
@@ -57,6 +54,14 @@ export {
   RENDERED_PATHS,
   renderRepoShape,
 } from './repo-shape/render.ts';
+export {
+  type RetiredFile,
+  type RetiredPath,
+  GENERATED_FILE_MARKER,
+  RETIRED_FILES,
+  retiredFileProblem,
+  wasRenderedByUs,
+} from './repo-shape/retired.ts';
 export { renderSecurity } from './repo-shape/security.ts';
 export {
   type ExtraJob,

package/dist/repo-shape/automerge.d.ts

@@ -1,17 +0,0 @@
-import type { RepoShape } from './shape.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 declare const GROUP_BRANCH_PREFIX: string;
-/**
- * ⛔ 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 declare const GROUP_BRANCH: string;
-/** The whole `dependabot-automerge.yml` for a shape. */
-export declare function renderAutomerge(shape: RepoShape): string;
-//# sourceMappingURL=automerge.d.ts.map

package/dist/repo-shape/automerge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"automerge.d.ts","sourceRoot":"","sources":["../../src/repo-shape/automerge.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAA6C,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAA+C,CAAC;AA0D3E,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAyCxD"}

package/src/repo-shape/automerge.ts

@@ -1,144 +0,0 @@
-/**
- * `.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,
-)}
-`;
-}