@grimoire-rs/indexer 0.2.2 → 0.3.0

package/README.md

@@ -6,20 +6,33 @@ servers, and bundles available in one or more OCI registries.
 
 ## Subcommands
 
-- `grim-indexer init` — scaffold a new index repo (`index/**` content
-  tree, Astro site config, CI workflow).
+- `grim-indexer init` — scaffold a new index repo: the `index/**` content
+  tree, site config, a `package.json` that pins this package, and the CI
+  its forge runs.
+- `grim-indexer dev` — serve the index locally, through the same renderer
+  `build` uses. The review loop for an entry or a branding change.
 - `grim-indexer enrich` — refresh `enrich/**` from the registry: READMEs,
   changelogs, logos, versions and tag lists. The only step that goes
   online, and the only one that needs `grim` on `PATH`.
 - `grim-indexer build` — render `index/**` into a static site.
 - `grim-indexer validate` — CI gate for contribution PRs/MRs against an
   index repo.
+- `grim-indexer ci` — render the index repo's workflows from the `ci`
+  block of its `index.config.json`; `--check` verifies the committed ones
+  still match and exits 65 on drift.
+
+A scaffolded index owns its CI: the workflow files are committed in that
+repository and run `npm ci` against its own lockfile, so nothing is
+fetched from here at run time and the version that builds an index is the
+one that repo has locked. The generated `verify-ci` job re-renders and
+diffs on every push, which is what keeps a hand-edit from silently
+forking the pipeline.
 
 An index stores nothing but pointers — a ref and who owns it. Everything a
 reader looks at lives in the registry, so an index that never runs `enrich`
 renders a catalogue of names with *No README available* on every page. The
-scaffolded CI runs it before each build; set `enrich: false` (GitHub) or
-`GRIM_INDEXER_ENRICH: "false"` (GitLab) for a pointers-only site.
+scaffolded CI runs it before each build; set `"enrich": false` in the `ci`
+block for a pointers-only site.
 
 ## Install
 
@@ -30,10 +43,19 @@ npm install --save-dev @grimoire-rs/indexer
 ## Usage
 
 ```sh
-npx @grimoire-rs/indexer init
-npx @grimoire-rs/indexer enrich   # needs `grim` on PATH
-npx @grimoire-rs/indexer build
-npx @grimoire-rs/indexer validate
+npx @grimoire-rs/indexer init     # scaffold; writes package.json + lockfile
+```
+
+Everything after that runs through the scaffolded repo's own scripts, so it
+uses the version that repo locked:
+
+```sh
+npm run dev        # local preview
+npm run build      # index/** -> dist/
+npm run enrich     # needs `grim` on PATH
+npm run validate   # the contribution gate
+npm run ci         # re-render CI after editing index.config.json
+npm run ci:check   # fail on drift (what the verify-ci job runs)
 ```
 
 As an Astro integration:
@@ -60,9 +82,11 @@ unreachable OCI ref, unowned namespace).
 
 Two things that trial settled, both worth knowing before you scaffold:
 
-- **Requiring the gate needs the check named `validate / validate`**, not
-  `validate`. Requiring a context that never reports blocks every PR
-  forever and looks exactly like the gate rejecting your contribution.
+- **Require the check named `validate`.** It was `validate / validate`
+  while the scaffold emitted thin callers of reusable workflows; the
+  workflow is now committed in the index repo, so the context is just the
+  job key. Requiring a context that never reports blocks every PR forever
+  and looks exactly like the gate rejecting your contribution.
 - **In the combined (`--with-skills`) layout the gate does not cover your
   own CI's announce.** GitHub runs no workflows on a PR opened with
   `secrets.GITHUB_TOKEN`, so that PR arrives ungated — review it by hand.
@@ -70,8 +94,8 @@ Two things that trial settled, both worth knowing before you scaffold:
   requests" enabled, which is off by default and which also lets
   workflows approve PRs.
 
-Not yet proven live: the GitLab leg (hermetic tests only; the
-`include: remote:` URL is verified to resolve), and the cross-repository
+Not yet proven live: the GitLab leg (hermetic unit tests only - no live
+GitLab pipeline has run the rendered CI), and the cross-repository
 announce, which needs a credential beyond the CI token.
 
 Two things are frozen and safe to build on: the published URL layout
@@ -83,13 +107,22 @@ is deliberately no component-override API yet — publishing one would
 freeze a prop contract per slot, and that is not a promise worth making
 this early.
 
-> **Use `0.1.4` or later.** `0.1.0` installs without an executable — npm
+> **Use `0.1.4` or later.** `0.1.0` installs without an executable - npm
 > silently stripped its `bin` entry at publish time. `0.1.1` and `0.1.2`
 > scaffold CI that points at reusable workflows those tags do not contain,
-> so the first push to a scaffolded index fails before any job runs. An
-> index already scaffolded against `0.1.1`/`0.1.2` is fixed by bumping the
-> `@v0.1.x` refs in `.github/workflows/{pages,validate}.yml` — no
-> re-scaffold needed.
+> so the first push to a scaffolded index fails before any job runs.
+>
+> An index already scaffolded against a reusable-workflow version keeps
+> working as long as its pinned `uses:`/`include:` refs stay on an existing
+> tag - old tags are not deleted, so that resolution does not break on its
+> own. It breaks the moment something bumps the pinned ref, because `main`
+> no longer defines any reusable workflow or remote include for it to
+> resolve to: a Renovate update of an `@grimoire-rs/indexer` action ref
+> will now fail hard. Fix it before that happens by re-scaffolding the CI -
+> `npx @grimoire-rs/indexer init . --force` and commit the result, or, if
+> you would rather not touch anything else `init` writes, add a
+> `package.json` pinning this package (if the old scaffold has none) and
+> run `npm run ci` to re-render just the workflow files.
 >
 > Through `0.1.3`, `init --with-skills` wrote a `publish.toml` with no
 > `[announce]` table, so `grim publish --announce` in a combined-layout

package/dist/ci.d.ts

@@ -0,0 +1,115 @@
+import { CliError } from "./cli/exit.js";
+/**
+ * Forges CI can be rendered for. One repository is hosted on one forge, so
+ * this is a choice rather than a set — rendering both left every index with a
+ * pipeline it would never run, and a second gate to keep honest for nothing.
+ */
+export type Forge = "github" | "gitlab";
+/**
+ * The `ci` block of `index.config.json` — everything that varies the
+ * generated pipeline. Every key is optional; [`resolveCi`] fills the gaps.
+ */
+export interface CiConfig {
+    /** Which forge's CI to render. Default `github`. */
+    forge?: Forge;
+    /** Node.js the jobs run on — `setup-node` version, and the GitLab image tag. Default `22`. */
+    nodeVersion?: string;
+    /**
+     * Refresh READMEs, changelogs, logos and version lists from the registry
+     * before building. `false` renders the enrichment steps away entirely, for
+     * a pointers-only site whose build never leaves the runner. Default `true`.
+     */
+    enrich?: boolean;
+    /** grim release the enrichment step reads the registry with — `latest` or a tag. Default `latest`. */
+    grimVersion?: string;
+    /**
+     * Squash-merge a pull request the gate passed, then deploy. Default `false`:
+     * merging an untrusted contribution unattended is a policy this package will
+     * not assume on a repository's behalf.
+     *
+     * GitHub only, and deliberately. GitHub always runs the base branch's copy
+     * of a `pull_request_target` workflow, so the gate a pull request faces is
+     * one it cannot edit. GitLab has no equivalent — the merge request supplies
+     * its own `.gitlab-ci.yml`, and a fork's pipeline runs in the fork — so an
+     * auto-merge there would act on a verdict the contributor could write.
+     */
+    autoMerge?: boolean;
+    /**
+     * Own these files by hand. The `verify-ci` drift guard is then not emitted,
+     * `ci --check` is the only thing left that would notice an edit, and CI
+     * fixes stop arriving by re-render. Discouraged, and deliberately not the
+     * default — but it is the repository's CI, so it is the repository's call.
+     */
+    allowManualEdits?: boolean;
+}
+export type ResolvedCiConfig = Required<CiConfig>;
+/** Fill every gap from the defaults documented on [`CiConfig`]. */
+export declare function resolveCi(ci: CiConfig | undefined): ResolvedCiConfig;
+/** Validate the `ci` block of an already-parsed config object. */
+export declare function validateCi(raw: unknown): CiConfig;
+/** Read the `ci` block out of `index.config.json`. A missing file means defaults. */
+export declare function loadCiConfig(root: string): Promise<CiConfig>;
+/**
+ * First line of every file this renderer writes. Stale detection keys on it,
+ * so a repository's hand-written workflows are never mistaken for ours.
+ *
+ * Deliberately carries no version stamp. The version that renders these files
+ * is the one in the repository's own `package-lock.json`; stamping it here too
+ * would be a second copy that goes stale, and every dependency bump would red
+ * the drift guard until somebody re-rendered a file whose content had not
+ * changed.
+ */
+export declare const GENERATED_HEADER = "# Generated by @grimoire-rs/indexer";
+/**
+ * Render the complete CI file set. Nothing touches disk — the caller writes
+ * it or diffs it against what is committed.
+ */
+export declare function renderCi(ci: ResolvedCiConfig): Map<string, string>;
+/**
+ * Canonicalize a generated file for drift comparison.
+ *
+ * The index repository owns the *pin* on every `uses:` action reference —
+ * its own Renovate or Dependabot will bump `uses: owner/action@<ref>  # vX`,
+ * and the guard must not read that as a hand-edit. Only the `@<ref>` suffix
+ * and any trailing version comment are stripped; `owner/action` survives, so
+ * swapping in a different action still trips drift.
+ */
+export declare function normalizeForDrift(content: string): string;
+/**
+ * Files on disk that carry our header but that the current config no longer
+ * renders — a `forge` narrowed from `both`, or `allowManualEdits` turned on
+ * after a guard was already committed. Reported, never deleted: removing a
+ * file from somebody's repository is their call, not the renderer's.
+ */
+export declare function staleCi(root: string, files: Map<string, string>): Promise<string[]>;
+export interface CiOutcome {
+    path: string;
+    /** `written` on a render; `drift`/`stale`/`ok` on a check. */
+    status: "written" | "unchanged" | "ok" | "drift" | "stale";
+}
+/**
+ * Write the rendered set, overwriting whatever is there.
+ *
+ * "Whatever is there" is judged through [`normalizeForDrift`], the same lens
+ * the guard uses — not raw bytes. Otherwise the two disagreed: `ci --check`
+ * deliberately tolerates a bumped `uses: owner/action@<ref>`, while a plain
+ * `npm run ci` rewrote it back to the pin baked into this package, silently
+ * undoing every Renovate bump the repository is told it may make. The repo
+ * owns its pins; a render must not take them back.
+ */
+export declare function writeCi(root: string, files: Map<string, string>): Promise<CiOutcome[]>;
+/**
+ * Compare the rendered set against what is committed. Missing counts as
+ * drift; a generated file the config no longer renders counts as stale.
+ * Hints are path-only — the contents of a repository's CI never go to stderr.
+ */
+export declare function checkCi(root: string, files: Map<string, string>): Promise<CiOutcome[]>;
+/**
+ * The re-render command a drift message tells the reader to run. It is the
+ * repository's own npm script, so it runs the renderer the lock pins rather
+ * than whatever `npx` would fetch today.
+ */
+export declare const RE_RENDER_COMMAND = "npm run ci";
+/** Turn a failed check into the error the CLI exits on. */
+export declare function driftError(outcomes: CiOutcome[]): CliError;
+//# sourceMappingURL=ci.d.ts.map

package/dist/ci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../src/ci.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,QAAQ,EAAQ,MAAM,eAAe,CAAC;AAI/C;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAIxC;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sGAAsG;IACtG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAElD,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,GAAG,gBAAgB,CASpE;AAMD,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAiCjD;AAED,qFAAqF;AACrF,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkBlE;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AA2CtE;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuClE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBzF;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;CAC5D;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAc5F;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAW5F;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,QAAQ,CAO1D"}

package/dist/ci.js

@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// The CI renderer: `index.config.json`'s `ci` block in, complete workflow
+// files out. The index repository owns and commits what it runs — there is no
+// reusable workflow to call, no remote include to fetch, and nothing about the
+// pipeline that lives anywhere but in the repository being pushed.
+//
+// The trade that buys is the drift guard: because the files are generated,
+// `grim-indexer ci --check` can re-render and diff, and the generated
+// `verify-ci` job runs exactly that on every push and pull request. So a
+// hand-edit is caught rather than silently forked, while the repository keeps
+// full ownership of its own CI — set `allowManualEdits` and the guard is not
+// emitted at all.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CliError, EXIT } from "./cli/exit.js";
+import { CONFIG_FILE, SiteConfigError } from "./config.js";
+import { fromTemplate } from "./templates.js";
+const FORGES = ["github", "gitlab"];
+/** Fill every gap from the defaults documented on [`CiConfig`]. */
+export function resolveCi(ci) {
+    return {
+        forge: ci?.forge ?? "github",
+        nodeVersion: ci?.nodeVersion ?? "22",
+        enrich: ci?.enrich ?? true,
+        grimVersion: ci?.grimVersion ?? "latest",
+        allowManualEdits: ci?.allowManualEdits ?? false,
+        autoMerge: ci?.autoMerge ?? false,
+    };
+}
+function fail(msg) {
+    throw new SiteConfigError(`${CONFIG_FILE}: ci.${msg}`);
+}
+/** Validate the `ci` block of an already-parsed config object. */
+export function validateCi(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new SiteConfigError(`${CONFIG_FILE}: ci must be an object`);
+    }
+    const ci = raw;
+    if (ci.forge !== undefined && !FORGES.includes(ci.forge)) {
+        fail(`forge must be one of ${FORGES.join(", ")}`);
+    }
+    // These land inside a double-quoted shell word or a docker image tag in the
+    // generated YAML. The repository owner writes this file, so it is a paste
+    // guard rather than a trust boundary — but a value carrying a quote or a `$`
+    // would rewrite the command around it, and no version string needs either.
+    for (const key of ["nodeVersion", "grimVersion"]) {
+        const value = ci[key];
+        if (value !== undefined && typeof value !== "string")
+            fail(`${key} must be a string`);
+        if (typeof value === "string" && !/^[\w.@^~><=* +-]+$/.test(value)) {
+            fail(`${key} must be a plain version or range`);
+        }
+    }
+    for (const key of ["enrich", "allowManualEdits", "autoMerge"]) {
+        if (ci[key] !== undefined && typeof ci[key] !== "boolean")
+            fail(`${key} must be a boolean`);
+    }
+    // Refused rather than ignored. Rendering GitLab CI while the config asks for
+    // auto-merge would leave a repository believing contributions land by
+    // themselves, and the honest answer is that they cannot be made to safely
+    // there — see the field's doc comment.
+    if (ci.autoMerge === true && ci.forge === "gitlab") {
+        fail("autoMerge is github-only - the GitLab gate cannot be made tamper-proof");
+    }
+    return ci;
+}
+/** Read the `ci` block out of `index.config.json`. A missing file means defaults. */
+export async function loadCiConfig(root) {
+    let text;
+    try {
+        text = await fs.readFile(path.join(root, CONFIG_FILE), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new SiteConfigError(`${CONFIG_FILE}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SiteConfigError(`${CONFIG_FILE}: must contain a JSON object`);
+    }
+    return validateCi(parsed.ci);
+}
+// ── Rendering ────────────────────────────────────────────────────────────────
+/**
+ * First line of every file this renderer writes. Stale detection keys on it,
+ * so a repository's hand-written workflows are never mistaken for ours.
+ *
+ * Deliberately carries no version stamp. The version that renders these files
+ * is the one in the repository's own `package-lock.json`; stamping it here too
+ * would be a second copy that goes stale, and every dependency bump would red
+ * the drift guard until somebody re-rendered a file whose content had not
+ * changed.
+ */
+export const GENERATED_HEADER = "# Generated by @grimoire-rs/indexer";
+/**
+ * What CI scaffolded by a pre-header release (<= 0.2.2) looks like: a thin
+ * caller pointing back at this package's reusable workflow, or a GitLab
+ * remote include of the same. Those files carry no generated header, so
+ * without this the reaper was blind to exactly the repositories that most
+ * need telling — an index scaffolded with the old `--forge both` resolves to
+ * `forge: "github"` today (its config has no `ci` block at all) and would
+ * keep serving an orphaned `.gitlab-ci.yml` with nothing to say so.
+ */
+const LEGACY_SIGNATURE = /uses:\s*grimoire-rs\/indexer\/\.github\/workflows\/|raw\.githubusercontent\.com\/grimoire-rs\/indexer\//;
+/** Where each forge's files land. */
+const GITHUB_FILES = {
+    pages: ".github/workflows/pages.yml",
+    validate: ".github/workflows/validate.yml",
+    verify: ".github/workflows/verify-ci.yml",
+};
+const GITLAB_FILE = ".gitlab-ci.yml";
+/**
+ * Where the grim release tarball is fetched from. `latest` has its own URL
+ * shape on GitHub releases; anything else is a tag. Resolving it here rather
+ * than in the generated shell is the point of rendering CI from config: a
+ * value that is fixed at render time should not be a branch at run time.
+ */
+function grimReleaseBase(grimVersion) {
+    const releases = "https://github.com/grimoire-rs/grimoire/releases";
+    return grimVersion === "latest"
+        ? `${releases}/latest/download`
+        : `${releases}/download/${grimVersion}`;
+}
+/**
+ * `paths:` entries that must re-run the drift guard — every file it renders,
+ * plus the config they are rendered from. `package-lock.json` is in there
+ * because the lock is what decides which renderer produces them.
+ */
+const VERIFY_PATHS = [CONFIG_FILE, "package.json", "package-lock.json", ".github/workflows/**"];
+/**
+ * Render the complete CI file set. Nothing touches disk — the caller writes
+ * it or diffs it against what is committed.
+ */
+export function renderCi(ci) {
+    const base = {
+        nodeVersion: ci.nodeVersion,
+        grimVersion: ci.grimVersion,
+        grimReleaseBase: grimReleaseBase(ci.grimVersion),
+    };
+    // Rendered first: `render` is single-pass, so a block handed in as a value
+    // must already have its own placeholders resolved. The trailing newline is
+    // trimmed because the template supplies one on the placeholder's own line —
+    // keeping both would leave a stray blank line, or an empty block would not.
+    const block = (rel) => fromTemplate(rel, base).replace(/\n$/, "");
+    const vars = {
+        ...base,
+        header: fromTemplate("ci/header.txt", base),
+        githubEnrichSteps: ci.enrich ? block("ci/github-enrich.yml") : "",
+        gitlabEnrichScript: ci.enrich ? block("ci/gitlab-enrich.sh") : "",
+        verifyPaths: VERIFY_PATHS.map((entry) => `      - ${entry}`).join("\n"),
+        gitlabVerifyJob: ci.allowManualEdits ? "" : block("ci/gitlab-verify.yml"),
+        // GitHub only — `validateCi` refuses the GitLab combination outright, so
+        // there is no silently-inert case to render around here.
+        githubAutoMergeJob: ci.autoMerge ? block("ci/github-automerge.yml") : "",
+    };
+    // Exactly one trailing newline, whatever the placeholders resolved to. An
+    // optional block that renders empty at the end of a file otherwise leaves
+    // its own blank line behind, so the same config produced two shapes.
+    const file = (rel) => fromTemplate(rel, vars).replace(/\n*$/, "\n");
+    const files = new Map();
+    if (ci.forge === "github") {
+        files.set(GITHUB_FILES.pages, file("ci/github-pages.yml"));
+        files.set(GITHUB_FILES.validate, file("ci/github-validate.yml"));
+        if (!ci.allowManualEdits) {
+            files.set(GITHUB_FILES.verify, file("ci/github-verify-ci.yml"));
+        }
+    }
+    else {
+        files.set(GITLAB_FILE, file("ci/gitlab-ci.yml"));
+    }
+    return files;
+}
+/**
+ * Canonicalize a generated file for drift comparison.
+ *
+ * The index repository owns the *pin* on every `uses:` action reference —
+ * its own Renovate or Dependabot will bump `uses: owner/action@<ref>  # vX`,
+ * and the guard must not read that as a hand-edit. Only the `@<ref>` suffix
+ * and any trailing version comment are stripped; `owner/action` survives, so
+ * swapping in a different action still trips drift.
+ */
+export function normalizeForDrift(content) {
+    // Line endings first. Git for Windows installs with `core.autocrlf=true` by
+    // default, so an untouched clone has CRLF on disk while the renderer emits
+    // LF — every generated file read as drift, and `npm run ci` could not clear
+    // it because the rewrite was LF too. The scaffold ships a `.gitattributes`
+    // that prevents it; this unsticks the checkouts that already have it.
+    return content
+        .replace(/\r\n/g, "\n")
+        .replace(/^([ \t]*(?:-[ \t]+)?uses:[ \t]*[^@\s]+)@[^\s#]+(?:[ \t]*#[^\n]*)?$/gm, "$1");
+}
+/**
+ * Files on disk that carry our header but that the current config no longer
+ * renders — a `forge` narrowed from `both`, or `allowManualEdits` turned on
+ * after a guard was already committed. Reported, never deleted: removing a
+ * file from somebody's repository is their call, not the renderer's.
+ */
+export async function staleCi(root, files) {
+    const candidates = [GITLAB_FILE];
+    try {
+        for (const entry of await fs.readdir(path.join(root, ".github/workflows"))) {
+            if (/\.ya?ml$/.test(entry))
+                candidates.push(`.github/workflows/${entry}`);
+        }
+    }
+    catch {
+        /* no workflows directory — nothing of ours can be stale in it */
+    }
+    const stale = [];
+    for (const relative of candidates) {
+        if (files.has(relative))
+            continue;
+        const content = await fs.readFile(path.join(root, relative), "utf8").catch(() => null);
+        if (content === null)
+            continue;
+        if (content.startsWith(GENERATED_HEADER) || LEGACY_SIGNATURE.test(content)) {
+            stale.push(relative);
+        }
+    }
+    return stale.sort();
+}
+/**
+ * Write the rendered set, overwriting whatever is there.
+ *
+ * "Whatever is there" is judged through [`normalizeForDrift`], the same lens
+ * the guard uses — not raw bytes. Otherwise the two disagreed: `ci --check`
+ * deliberately tolerates a bumped `uses: owner/action@<ref>`, while a plain
+ * `npm run ci` rewrote it back to the pin baked into this package, silently
+ * undoing every Renovate bump the repository is told it may make. The repo
+ * owns its pins; a render must not take them back.
+ */
+export async function writeCi(root, files) {
+    const outcomes = [];
+    for (const [relative, content] of files) {
+        const abs = path.join(root, relative);
+        const current = await fs.readFile(abs, "utf8").catch(() => null);
+        if (current !== null && normalizeForDrift(current) === normalizeForDrift(content)) {
+            outcomes.push({ path: relative, status: "unchanged" });
+            continue;
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, content);
+        outcomes.push({ path: relative, status: "written" });
+    }
+    return outcomes;
+}
+/**
+ * Compare the rendered set against what is committed. Missing counts as
+ * drift; a generated file the config no longer renders counts as stale.
+ * Hints are path-only — the contents of a repository's CI never go to stderr.
+ */
+export async function checkCi(root, files) {
+    const outcomes = [];
+    for (const [relative, expected] of files) {
+        const actual = await fs.readFile(path.join(root, relative), "utf8").catch(() => null);
+        const same = actual !== null && normalizeForDrift(actual) === normalizeForDrift(expected);
+        outcomes.push({ path: relative, status: same ? "ok" : "drift" });
+    }
+    for (const relative of await staleCi(root, files)) {
+        outcomes.push({ path: relative, status: "stale" });
+    }
+    return outcomes;
+}
+/**
+ * The re-render command a drift message tells the reader to run. It is the
+ * repository's own npm script, so it runs the renderer the lock pins rather
+ * than whatever `npx` would fetch today.
+ */
+export const RE_RENDER_COMMAND = "npm run ci";
+/** Turn a failed check into the error the CLI exits on. */
+export function driftError(outcomes) {
+    const bad = outcomes.filter((outcome) => outcome.status !== "ok");
+    return new CliError(`${bad.length} generated CI file(s) do not match ${CONFIG_FILE} — ` +
+        `re-run \`${RE_RENDER_COMMAND}\` and commit the result`, EXIT.data);
+}
+//# sourceMappingURL=ci.js.map

package/dist/ci.js.map

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

package/dist/cli/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAQA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6B9E"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGhD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkB9E"}

package/dist/cli/build.js

@@ -4,17 +4,11 @@
 // site over it. Order is load-bearing: `compileIndex` clears `outDir` and
 // writes `all.json`, which the renderer then reads.
 import path from "node:path";
-import { CliError, EXIT } from "./exit.js";
+import { EXIT } from "./exit.js";
+import { resolveOutDir } from "./out_dir.js";
 export async function build(root, flags) {
     const rootDir = path.resolve(root);
-    const outDir = path.resolve(rootDir, flags.outDir ?? "dist");
-    // `compileIndex` starts by removing `outDir` outright, so an out-dir that
-    // is the repo root — or an ancestor of it — would delete the index it is
-    // about to compile.
-    if (outDir === rootDir || rootDir.startsWith(outDir + path.sep)) {
-        throw new CliError(`--out-dir ${JSON.stringify(outDir)} contains the index root ${JSON.stringify(rootDir)}; ` +
-            `the build would delete it`, EXIT.usage);
-    }
+    const outDir = resolveOutDir(rootDir, flags.outDir);
     const [{ loadConfig }, { compileIndex }, { buildSite }] = await Promise.all([
         import("../config.js"),
         import("../data/index.js"),

package/dist/cli/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC,0EAA0E;AAC1E,0EAA0E;AAC1E,oDAAoD;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAiB,MAAM,WAAW,CAAC;AAM1D,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY,EAAE,KAAiB;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC;IAE7D,0EAA0E;IAC1E,yEAAyE;IACzE,oBAAoB;IACpB,IAAI,MAAM,KAAK,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,QAAQ,CAChB,aAAa,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,4BAA4B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI;YACxF,2BAA2B,EAC7B,IAAI,CAAC,KAAK,CACX,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1E,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,sBAAsB,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEnD,OAAO,CAAC,GAAG,CACT,GAAG,KAAK,sBAAsB,UAAU,CAAC,MAAM,oBAAoB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CACpH,CAAC;IACF,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC,0EAA0E;AAC1E,0EAA0E;AAC1E,oDAAoD;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,IAAI,EAAiB,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAM7C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY,EAAE,KAAiB;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAEpD,MAAM,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1E,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,sBAAsB,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEnD,OAAO,CAAC,GAAG,CACT,GAAG,KAAK,sBAAsB,UAAU,CAAC,MAAM,oBAAoB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CACpH,CAAC;IACF,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC"}

package/dist/cli/ci.d.ts

@@ -0,0 +1,6 @@
+import { type ExitCode } from "./exit.js";
+export interface CiFlags {
+    check?: boolean;
+}
+export declare function ci(root: string, flags: CiFlags): Promise<ExitCode>;
+//# sourceMappingURL=ci.d.ts.map

package/dist/cli/ci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../../src/cli/ci.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD,wBAAsB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+BxE"}

package/dist/cli/ci.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// `grim-indexer ci` — render this repository's CI from `index.config.json`,
+// or (`--check`) verify that what is committed still matches. The generated
+// `verify-ci` job runs the second form, which is what keeps a hand-edit from
+// silently forking the pipeline.
+import path from "node:path";
+import { checkCi, driftError, loadCiConfig, renderCi, RE_RENDER_COMMAND, resolveCi, staleCi, writeCi, } from "../ci.js";
+import { CONFIG_FILE } from "../config.js";
+import { EXIT } from "./exit.js";
+function report(outcome) {
+    console.log(`  ${outcome.status.padEnd(12)}${outcome.path}`);
+}
+export async function ci(root, flags) {
+    const rootDir = path.resolve(root);
+    const resolved = resolveCi(await loadCiConfig(rootDir));
+    const files = renderCi(resolved);
+    if (flags.check) {
+        const outcomes = await checkCi(rootDir, files);
+        for (const outcome of outcomes) {
+            // Path-only, on stderr: the contents of a repository's CI are not this
+            // command's to print, and a log is the wrong place for them.
+            if (outcome.status !== "ok")
+                console.error(`${outcome.status}: ${outcome.path}`);
+        }
+        if (outcomes.some((outcome) => outcome.status !== "ok"))
+            throw driftError(outcomes);
+        console.log(`${files.size} generated CI file(s) match ${CONFIG_FILE}`);
+        return EXIT.ok;
+    }
+    const written = await writeCi(rootDir, files);
+    written.forEach(report);
+    const stale = await staleCi(rootDir, files);
+    for (const relative of stale) {
+        report({ path: relative, status: "stale" });
+    }
+    if (stale.length > 0) {
+        console.error(`\n${stale.length} generated file(s) are no longer rendered by ${CONFIG_FILE} — ` +
+            `delete them, or \`${RE_RENDER_COMMAND}:check\` keeps failing`);
+    }
+    return EXIT.ok;
+}
+//# sourceMappingURL=ci.js.map

package/dist/cli/ci.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.js","sourceRoot":"","sources":["../../src/cli/ci.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAC7E,iCAAiC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,OAAO,GAER,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAiB,MAAM,WAAW,CAAC;AAMhD,SAAS,MAAM,CAAC,OAAkB;IAChC,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC,IAAY,EAAE,KAAc;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEjC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,uEAAuE;YACvE,6DAA6D;YAC7D,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;gBAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC;YAAE,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,+BAA+B,WAAW,EAAE,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9C,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5C,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CACX,KAAK,KAAK,CAAC,MAAM,gDAAgD,WAAW,KAAK;YAC/E,qBAAqB,iBAAiB,wBAAwB,CACjE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC"}

package/dist/cli/dev.d.ts

@@ -0,0 +1,7 @@
+import { type ExitCode } from "./exit.js";
+export interface DevFlags {
+    outDir?: string;
+    port?: string;
+}
+export declare function dev(root: string, flags: DevFlags): Promise<ExitCode>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/cli/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AASA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1D,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgBD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoC1E"}