@homeflare/config 0.12.0 → 0.13.0

package/docs/repo-shape-retired.md

@@ -0,0 +1,75 @@
+# Retired rendered files — the fossil, and how it is cleared
+
+`renderRepoShape` only emits the files a shape asks for today. `refreshRepoShape` only
+writes what it renders. Put those two together and a file the renderer stops emitting is
+never deleted by a refresh — it just stops being updated, silently, in every repository
+that had already taken it. `RETIRED_FILES` in `src/repo-shape/retired.ts` is how that stops
+being permanent.
+
+## MEASURED 2026-09-24: the gap that motivated this
+
+`@homeflare/config` 0.12.0 ([kit PR 199](https://github.com/taslabs-net/homeflare-kit/pull/199))
+stopped rendering `.github/workflows/dependabot-automerge.yml` — `taslabs-net/homeflare-bumper`
+carries a kit release into a consumer now, over `workflow_dispatch`, so the workflow that used
+to arm auto-merge on Dependabot's `homeflare` group had nothing left to do.
+
+Every repository that had already refreshed to 0.12.0 before this module existed
+(`homeflare-wiki` bump PR 19, `homeflare-mini` bump PR 47) kept the dead file. Nothing said
+so: `driftInRepoShape` only ever compared the paths the **current** shape renders, and a
+retired path is not one of those, so it was invisible to the one check whose whole job is
+to say when a committed file and the renderer disagree.
+
+## The two halves
+
+**`driftInRepoShape` (`repo-shape check`) reports a retired path that is merely present.**
+It does not read the file to decide anything beyond "is it there" — proving the file is
+provably ours is `refreshRepoShape`'s decision to make, not the read-only check's. So
+`bun run repo-shape:refresh` fails on a retired fossil exactly the way it fails on ordinary
+drift:
+
+```
+✗ .github/workflows/dependabot-automerge.yml: retired in @homeflare/config@0.12.0
+  (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) but still
+  present — run `bun run repo-shape:refresh` to remove it
+```
+
+**`refreshRepoShape` deletes a retired path only when it can prove it rendered it.** The
+proof is the generated-file header: every renderer in `src/repo-shape/` writes
+`🤖 RENDERED BY @homeflare/config` into the file it emits, and `wasRenderedByUs` is nothing
+more than a check for that line. A retired path whose content carries it is deleted. A
+retired path whose content does not — a hand-written replacement, a fork of the old
+rendered file kept on purpose, or coincidental content that landed at the same name — is
+left exactly as it is, and reported back as `refused`, never `removed`.
+
+⚠️ **A refused file still fails `repo-shape check`.** The check does not know or care
+whether the file is provably ours; it only knows the retired path is present. There is no
+`except()` for a retired path — a repository that genuinely wants to keep a hand-written
+file at that exact name has to remove it or rename it itself; `repo-shape` will not delete
+someone else's file to make its own check pass.
+
+## Why the header, not a stored copy of the old rendered text
+
+The retired `dependabot-automerge.yml` varied by `shape.runner` and by repository name —
+there is no single byte-for-byte "the rendered form" to compare against across the estate's
+history, and a renderer that has been deleted cannot be asked to re-render its old output.
+The header line is the one thing every variant, in every repository, always carried.
+
+## Retiring a path, going forward
+
+Add an entry to `RETIRED_FILES` in `src/repo-shape/retired.ts`: the path, the
+`@homeflare/config` version whose release stops rendering it, and a written reason — same
+rule as `except()`, enforced the same way. Remove the path from `render.ts` in the same
+changeset. A path can never move back into `RenderedPath`; `repo-shape-retired.test.ts`
+asserts the two lists stay disjoint, because a path in both would have the renderer writing
+a file this module is also trying to delete, every single refresh.
+
+## How this reaches a consumer
+
+A patch release of `@homeflare/config` ships the new `RETIRED_FILES` entry.
+`taslabs-net/homeflare-bumper` opens the bump pull request in each consumer the way it
+always does. Its own `bun run repo-shape:refresh` — the same step every bump PR already
+needs, [documented here](./repo-shape.md#bumping-homeflareconfig-will-go-red-before-it-goes-green) — now also deletes
+the fossil, so the PR's diff touches `.github/workflows/`. **The bumper holds a PR that
+touches that directory for Tim rather than auto-merging it**, which is the correct,
+existing behavior for a workflow-file change — not something this module has to arrange.

package/docs/repo-shape.md

@@ -173,6 +173,17 @@ The alternative — a check that tolerated an older render — is a check that t
 drift, which is the thing this exists to stop. A loud, one-command failure is the better
 half of that trade, but it is a trade.
 
+## A file the renderer stops emitting is deleted, not left behind
+
+`renderRepoShape` only emits what a shape asks for today, and `refreshRepoShape` only
+writes what it renders — so on its own, a file the renderer retires would never get
+deleted by a refresh; it would just stop being updated, in every repository that already
+had it. `RETIRED_FILES` in `src/repo-shape/retired.ts` closes that gap: `repo-shape check`
+flags a retired path that is still present, and a refresh deletes it — but only when the
+file provably carries this package's generated-file header, never a hand-written file that
+happens to share the name. [repo-shape-retired.md](repo-shape-retired.md) has the mechanism
+and the measurement that found the first fossil.
+
 ## What this does not render yet
 
 `.github/workflows/release.yml`. Thirteen copies, 166–197 lines each, thirteen distinct

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/config",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Shared tsconfig, oxlint, oxfmt, and non-npm release helpers for HomeFlare projects.",
   "license": "MIT",
   "author": "Timothy Schneider",

package/src/repo-shape/ci.ts

@@ -74,6 +74,21 @@ permissions:
 concurrency:
   group: ci-\${{ github.ref }}
   cancel-in-progress: true
+
+# ⛔ SECOND GUARD, NOT THE FIRST ONE. The estate's primary Alchemy telemetry opt-out is the
+#   persisted \`~/.alchemy/telemetry-disabled\` file (Tim, 2026-09-26), which a CI runner never
+#   has — a self-hosted job starts a fresh container per run and a GitHub-hosted one is a fresh
+#   VM every time, so neither has read the file even if this estate's account somehow wrote it
+#   there. \`DO_NOT_TRACK\` is the opt-out alchemy's telemetry layer actually reads
+#   (\`!!process.env.DO_NOT_TRACK\`, alchemy \`src/Telemetry/Attributes.ts:126-129\`); this env
+#   applies to every job and step in this workflow. No repository's \`check\` invokes the Alchemy
+#   CLI today, measured 2026-09-26 (grepped every ci/security/release workflow for
+#   \`alchemy\`/\`bin/cli.js\`, zero hits), but alchemy's own \`Test\` helpers wire \`TelemetryLive\`
+#   into top-level \`deploy\`/\`destroy\` (\`src/Test/Core.ts:470,482\`), so a future kit test built on
+#   those (today's kit tests use only \`test.provider\` scratch stacks, which don't) would send
+#   telemetry from \`bun test\` without this guard — this closes that gap in advance.
+env:
+  DO_NOT_TRACK: '1'
 `;
 
 const CHECK_NOTE = `  # ── One job, one install ────────────────────────────────────────────────────

package/src/repo-shape/drift.ts

@@ -18,6 +18,7 @@
  *   The one exception is line endings, normalised so a CRLF checkout is not "drift".
  */
 import { type RenderedRepo, renderRepoShape } from './render.ts';
+import { RETIRED_FILES, retiredFileProblem } from './retired.ts';
 import type { RenderedPath, RepoShape, RepoShapeException } from './shape.ts';
 
 /** One thing to fix, in the imperative — the same `Problem` shape `./check` reports. */
@@ -69,8 +70,24 @@ function duplicateExceptions(exceptions: readonly RepoShapeException[]): Problem
   );
 }
 
+/**
+ * ★ A RETIRED PATH IS REPORTED WHETHER OR NOT IT IS PROVABLY OURS. This check only reads
+ *   the file to see if it is THERE — `wasRenderedByUs` is `refreshRepoShape`'s call to
+ *   make, because only the writer should decide whether to delete. Reporting here is what
+ *   makes a fossil visible even in a repository that only ever runs `--check` in CI.
+ */
+async function retiredFilesPresent(projectDir: string): Promise<Problem[]> {
+  const problems: Problem[] = [];
+  for (const file of RETIRED_FILES) {
+    if ((await readIfPresent(`${projectDir}/${file.path}`)) !== undefined) {
+      problems.push(retiredFileProblem(file));
+    }
+  }
+  return problems;
+}
+
 export interface DriftReport {
-  /** Empty when the committed files are the rendered ones. */
+  /** Empty when the committed files are the rendered ones and no retired path lingers. */
   readonly problems: readonly Problem[];
   /** Paths whose committed text differs from the render, excluding excepted files. */
   readonly drifted: readonly string[];
@@ -93,6 +110,7 @@ export async function driftInRepoShape(projectDir: string, shape: RepoShape): Pr
   const problems: Problem[] = [
     ...duplicateExceptions(exceptions),
     ...staleExceptions(rendered, exceptions),
+    ...(await retiredFilesPresent(projectDir)),
   ];
   const drifted: string[] = [];
 

package/src/repo-shape/guards.ts

@@ -36,6 +36,17 @@ export function requireIsoDate(value: string): string {
   return value;
 }
 
+/**
+ * A retired file names the `@homeflare/config` release that stopped rendering it, so
+ * anyone reading `retired.ts` can find the changeset that made the call.
+ */
+export function requireSemver(value: string): string {
+  if (!/^\d+\.\d+\.\d+$/.test(value)) {
+    throw new Error(`repo-shape: retiredIn must be a released x.y.z, 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

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/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.ts

@@ -54,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,