@homeflare/config 0.5.1 → 0.7.0

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

@@ -0,0 +1,19 @@
+/**
+ * `.github/workflows/security.yml`, rendered.
+ *
+ * ⛔ THIS FILE IS WHY THE RENDERER EXISTS. Measured across 13 repositories on 2026-09-22,
+ *   every one of these was a per-repo accident rather than a decision:
+ *     · `push: branches: [main]` still present in 5, removed in 8;
+ *     · the `concurrency:` block missing entirely in 5 — so a superseded scan ran to
+ *       completion holding one of the mini's 3 slots for a result nobody would read;
+ *     · `pull-requests: read` missing in 2, which makes every pull-request scan fail 403
+ *       before it inspects a single line;
+ *     · `gitleaks/gitleaks-action` pinned at `@v2` in 5 and `@v3` in 8, after GitHub
+ *       removed the Node 20 runtime v2 needs (2026-09-16);
+ *     · the weekly cron at three different minutes.
+ *   One renderer makes all thirteen the same file, and the next such fix is one commit.
+ */
+import type { RepoShape } from './shape.ts';
+/** The whole `security.yml` for a shape. */
+export declare function renderSecurity(shape: RepoShape): string;
+//# sourceMappingURL=security.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/repo-shape/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAmE5C,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAyBvD"}

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

@@ -0,0 +1,138 @@
+/**
+ * `RepoShape` — one HomeFlare repository's tooling, as a value.
+ *
+ * ★ WHY THIS TYPE EXISTS. Measured across the estate on 2026-09-22: 13 repositories each
+ *   carry a hand-written `.github/workflows/ci.yml`, `security.yml`, `.github/actionlint.yaml`
+ *   and `.changeset/config.json`. The changeset configs were byte-identical apart from the
+ *   repository name in 11 of 13. The security workflows were not: five still carried
+ *   `push: branches: [main]` that the other eight had removed, five were missing the
+ *   `concurrency:` block entirely, two were missing `pull-requests: read` (whose absence
+ *   makes every pull-request scan fail 403), the gitleaks action was pinned at `@v2` in
+ *   five and `@v3` in eight, and the weekly cron minute took three different values. Not
+ *   one of those differences was a decision. They are what happens when the same edit is
+ *   applied by hand thirteen times.
+ *
+ * ⛔ SO: A DIFFERENCE IS EITHER AN INPUT OR AN EXCEPTION. Nothing else. A repository that
+ *   needs something the standard does not give it either widens this type — and every
+ *   repository gets the widening — or declares an exception with a stated reason. There
+ *   is no third option where a file is quietly edited, because `drift.ts` fails on it.
+ *
+ * ⚠️ THE REASON IS ENFORCED BY THE COMPILER, NOT BY REVIEW. `except()` and `extraJob()`
+ *   below refuse an empty reason and refuse a reason read out of a variable, so the text
+ *   has to be written at the exception. See `Stated`.
+ */
+/** Where a repository's jobs run. */
+export type RepoRunner = 
+/**
+ * `[self-hosted, homeflare-mini]` — the interim Linux arm64 runner on the Mac mini.
+ * ⚠️ GitHub-hosted runners are refused for this account (billing lock, 2026-09-22).
+ */
+'mini'
+/** `ubuntu-latest`. Public repositories, where GitHub-hosted minutes are free. */
+ | 'github';
+/** One step in a rendered job. Either a `uses:` or a `run:`, never both. */
+export type JobStep = {
+    readonly name?: string;
+    readonly env?: Readonly<Record<string, string>>;
+} & ({
+    readonly uses: string;
+    readonly with?: Readonly<Record<string, string | number>>;
+    readonly run?: never;
+} | {
+    readonly run: string;
+    readonly uses?: never;
+    readonly with?: never;
+});
+/**
+ * ⛔ A REASON MUST BE WRITTEN, NOT COMPUTED. `'' extends R` is true for the empty literal
+ *   AND for the wide `string` type, so both collapse to `never` and fail to typecheck:
+ *   `reason: ''` is refused, and so is `reason: someVariable`. Only a string literal
+ *   written at the call site survives — which is the whole point, because a reason
+ *   assembled at runtime is a reason nobody reads in the diff.
+ *   Verified against TypeScript 7.0.2 on 2026-09-22; `tests/repo-shape-reason.test.ts`
+ *   compiles the refusals and asserts they still fail.
+ */
+export type Stated<R extends string> = '' extends R ? never : R;
+/** Paths this package renders. A deviation names one of these, not an arbitrary file. */
+export type RenderedPath = '.changeset/config.json' | '.github/actionlint.yaml' | '.github/dependabot.yml' | '.github/workflows/ci.yml' | '.github/workflows/security.yml';
+export interface RepoShapeException {
+    /** The rendered file this repository does not take from the renderer. */
+    readonly file: RenderedPath;
+    /** Why — written at the exception, in a sentence a stranger can act on. */
+    readonly reason: string;
+    /** `YYYY-MM-DD` the exception was taken, so a stale one is visible. */
+    readonly since: string;
+}
+interface ExceptionInput {
+    readonly file: RenderedPath;
+    readonly reason: string;
+    readonly since: string;
+}
+/**
+ * Declare that this repository keeps its own copy of a rendered file.
+ *
+ *     except({
+ *       file: '.github/workflows/ci.yml',
+ *       reason: 'Payload needs Node >=24.15, which the rendered job does not install',
+ *       since: '2026-09-22',
+ *     })
+ *
+ * ⛔ THE DRIFT CHECK STOPS CHECKING THAT FILE. That is the trade: an exception buys the
+ *   freedom to hand-edit one file and pays for it by losing the guarantee on that file.
+ *   Prefer widening `RepoShape` — then every repository benefits and nothing is lost.
+ */
+export declare function except<const E extends ExceptionInput>(exception: E & {
+    readonly reason: Stated<E['reason']>;
+}): RepoShapeException;
+export interface ExtraJob {
+    /** The job key in `jobs:`, e.g. `package`. Lower-case, dashes allowed. */
+    readonly id: string;
+    /**
+     * The job's `name:`, which is also the status-check context. It joins the `ci`
+     * aggregate's `needs`, so the branch ruleset still requires exactly one check.
+     */
+    readonly name: string;
+    /** Why this repository has a job the other twelve do not. */
+    readonly reason: string;
+    /** Steps after checkout. The prologue (checkout, bun, install) is rendered for you. */
+    readonly steps: readonly JobStep[];
+    /** Job ids this one waits for. Default: none, so it runs beside `check`. */
+    readonly needs?: readonly string[];
+    /** `false` skips the rendered bun prologue — for a job that needs another toolchain. */
+    readonly bun?: boolean;
+}
+interface ExtraJobInput extends Omit<ExtraJob, 'needs' | 'bun'> {
+    readonly needs?: readonly string[];
+    readonly bun?: boolean;
+}
+/**
+ * Declare a job this repository needs and the standard does not have.
+ * ⛔ Same rule as `except`: the reason is a written literal or it does not compile.
+ */
+export declare function extraJob<const J extends ExtraJobInput>(job: J & {
+    readonly reason: Stated<J['reason']>;
+}): ExtraJob;
+export interface RepoShape {
+    /** Repository owner — a user or organization login. */
+    readonly owner: string;
+    /** Repository name, which is also the checkout directory name. */
+    readonly repository: string;
+    /** Where its jobs run. */
+    readonly runner: RepoRunner;
+    /**
+     * `true` when the repository publishes an npm tarball. It decides `access` in the
+     * changeset config and whether `privatePackages` is written at all — the two keys
+     * that differ between `homeflare-kit` and every other repository.
+     */
+    readonly publishes: boolean;
+    /** 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[];
+}
+/** `runs-on:` for a runner. */
+export declare function runsOn(runner: RepoRunner): string;
+/** Whether a rendered path is excepted by this shape. */
+export declare function isExcepted(shape: RepoShape, file: RenderedPath): boolean;
+export {};
+//# sourceMappingURL=shape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shape.d.ts","sourceRoot":"","sources":["../../src/repo-shape/shape.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,18 @@
+/**
+ * The smallest YAML writer that renders a job's steps, and nothing else.
+ *
+ * ★ NOT A YAML LIBRARY, DELIBERATELY. A general serializer would take a dependency every
+ *   consumer of `@homeflare/config` inherits, and it would strip the comments — which in
+ *   this house are the product. The rendered workflows are written as text with holes;
+ *   only the step lists, whose shape varies per repository, go through here.
+ *
+ * ⚠️ Bun can PARSE YAML natively (`Bun.YAML.parse`) but does not stringify it, measured
+ *   against Bun 1.4.0 on 2026-09-22. The tests parse what this writes with `Bun.YAML.parse`
+ *   and compare structures, so a malformed emission fails rather than shipping.
+ */
+import type { JobStep } from './shape.ts';
+/** One step, as the lines of a `steps:` list item at `depth`. */
+export declare function renderStep(step: JobStep, depth: number): string[];
+/** A whole `steps:` list, already indented for a job at `depth`. */
+export declare function renderSteps(steps: readonly JobStep[], depth: number): string;
+//# sourceMappingURL=yaml.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../src/repo-shape/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAsD1C,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBjE;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5E"}

package/dist/repo-shape.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@homeflare/config/repo-shape` — the standard HomeFlare repository, as one declaration.
+ *
+ * A repository keeps a `repo-shape.ts` at its root:
+ *
+ *     import { except, repoShapeCli, type RepoShape } from '@homeflare/config/repo-shape';
+ *
+ *     export const shape: RepoShape = {
+ *       owner: 'taslabs-net',
+ *       repository: 'homeflare-proxmox',
+ *       runner: 'mini',
+ *       publishes: false,
+ *     };
+ *
+ *     if (import.meta.main) process.exit(await repoShapeCli(import.meta.dir, shape, Bun.argv.slice(2)));
+ *
+ * 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;
+ *   · 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
+ *                     requires exactly the checks these workflows report.
+ *
+ * ⛔ A DEVIATION IS DECLARED OR IT FAILS. `except({ file, reason, since })` refuses an
+ *   empty reason and refuses a reason read from a variable — the text has to be written
+ *   at the exception, in the diff, where someone will read it. Same for `extraJob()`.
+ *
+ * ★ WHY IT LIVES IN `@homeflare/config` RATHER THAN `@homeflare/alchemy`. Measured
+ *   2026-09-22: `@homeflare/config` is a dependency of 13 of 14 estate repositories and
+ *   `@homeflare/alchemy` of 4. The drift check has to run in every repository's own CI,
+ *   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 { renderCi, ACTIONLINT_VERSION, BUN_VERSION } from './repo-shape/ci.ts';
+export { renderActionlintConfig, renderChangesetConfig, renderDependabot, } from './repo-shape/companions.ts';
+export { type DriftReport, type Problem, driftInRepoShape, exceptionSummary, REFRESH_COMMAND, } from './repo-shape/drift.ts';
+export { type RefreshResult, refreshRepoShape, repoShapeCli } from './repo-shape/refresh.ts';
+export { type RenderedRepo, type RepoShapePolicy, RENDERED_PATHS, renderRepoShape, } from './repo-shape/render.ts';
+export { renderSecurity } from './repo-shape/security.ts';
+export { type ExtraJob, type JobStep, type RenderedPath, type RepoRunner, type RepoShape, type RepoShapeException, type Stated, except, extraJob, isExcepted, runsOn, } from './repo-shape/shape.ts';
+//# sourceMappingURL=repo-shape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repo-shape.d.ts","sourceRoot":"","sources":["../src/repo-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,cAAc,EACd,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,MAAM,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EACV,MAAM,GACP,MAAM,uBAAuB,CAAC"}