@grimoire-rs/indexer 0.2.2 → 0.3.0

package/templates/README.md

@@ -1,6 +1,6 @@
 # {{title}}
 
-A [Grimoire](https://github.com/grimoire-rs/grimoire) package index — a
+A [Grimoire](https://github.com/grimoire-rs/grimoire) package index - a
 static site listing the skills, rules, agents, mcp servers, and bundles
 available in `{{registryHost}}`, served at {{baseUrl}}.
 
@@ -8,41 +8,137 @@ available in `{{registryHost}}`, served at {{baseUrl}}.
 
 | Path | Purpose |
 |---|---|
-| `index/<namespace>/<package>/metadata.json` | One entry per package — the source of truth |
-| `index.config.json` | Site identity: title, base URL, registry, branding |
+| `index/<host>/<namespace>/<package>/metadata.json` | One entry per package - the source of truth |
+| `index.config.json` | Site identity, branding, and the `ci` block the workflows are rendered from |
 | `index-policy.json` | Committed allowlist of registry hosts contributions may point at |
-| `dist/` | Build output (`all.json`, per-path copies, the rendered site) — not committed |
+| `package.json` / `package-lock.json` | The renderer this index runs, pinned |
+| `dist/` | Build output (`all.json`, per-path copies, the rendered site) - not committed |
+
+## Getting set up
+
+```sh
+npm install
+```
+
+That is the whole toolchain. `package-lock.json` pins the exact renderer this
+index builds, validates and deploys with - commit it, because CI installs from
+it with `npm ci` and nothing is resolved on the runner.
+
+## Everyday workflow
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Serve the index locally with a live preview |
+| `npm run build` | Compile `index/**` into `dist/` and render the site |
+| `npm run validate` | Run the contribution gate over changed paths |
+| `npm run enrich` | Refresh READMEs, logos and version lists from the registry (needs `grim`) |
+| `npm run ci` | Re-render the CI workflows from `index.config.json` |
+| `npm run ci:check` | Fail if the committed workflows have drifted from the config |
+
+### Review a change locally
+
+```sh
+npm run dev
+```
+
+`dev` prints the URL to open once it is up - the site exactly as it deploys.
+A domain-rooted `site` serves at `http://localhost:4321`; a project-Pages
+`site` (`https://<owner>.github.io/<repo>`) serves under a `/<repo>` path
+segment instead, because that is Astro's `base` for that layout too.
+
+Entries under `index/` and the settings in `index.config.json` are read once,
+at start-up, so restart after editing them. The dev server renders through the
+same code path `npm run build` does: what you see is what deploys.
+
+### Test a contribution before you open the pull request
+
+`validate` is the same gate CI runs, and the same exit-code contract - 0
+means eligible for auto-merge, non-zero means a maintainer takes a look -
+but CI reads the forge identity and the PR tree off the platform, so a
+local run has to supply them by hand:
+
+```sh
+npm run validate -- \
+  --root . --pr-tree . \
+  --forge github --author-login <your-github-login> --author-id <your-numeric-id> \
+  -- index/<host>/<your-namespace>/<your-package>/metadata.json
+```
+
+`--root` and `--pr-tree` both point at your own checkout here; CI points
+them at two different checkouts (the trusted base and the PR head) so it
+can also catch a re-registered login trying to inherit someone else's
+package - fine to collapse for a solo sanity check, not something CI does.
+`--author-id` is your numeric forge account id, not your login - find yours
+at `https://api.github.com/users/<your-github-login>`. The gate makes real
+calls to the forge API and to the registry, so it needs network access and
+an entry that is actually yours to pass.
 
 ## Contributing a package
 
-Add `index/<namespace>/<package>/metadata.json`, then open a pull request.
-CI runs `grim-indexer validate` on it: a clean run means the entry is
-eligible for auto-merge, a failing one means a maintainer takes a look.
+Add `index/<host>/<your-namespace>/<your-package>/metadata.json` (`<host>`
+is the forge this repo is hosted on, e.g. `github.com`), then open a pull
+request.
 
 ```json
 {
   "schema": 1,
   "name": "{{name}}-example",
   "kind": "skill",
-  "ref": "{{registryHost}}/{{registryAlias}}/skills/{{name}}-example:1.0.0",
+  "ref": "{{registryHost}}/{{registryAlias}}/skills/{{name}}-example",
   "description": "One line describing what this package does.",
-  "owner": { "id": 0, "github": "your-github-login" }
+  "owner": { "id": 12345678, "github": "your-github-login" }
 }
 ```
 
 The directory name must equal `name`, and `kind` is one of `skill`,
-`rule`, `agent`, `mcp`, `bundle`.
+`rule`, `agent`, `mcp`, `bundle`. `ref` names a repository, not a tag or
+digest - the gate resolves it to whatever is published. `owner.id` must be
+your real numeric GitHub account id, not the placeholder above - find yours
+at `https://api.github.com/users/your-github-login`; the gate checks it
+against the forge, not the `github` login, since a login can be
+re-registered by someone else.
 
-## Local development
+## CI
+
+This repo owns and runs its own CI: the workflow files are committed here, not
+called from anywhere else. They are *rendered* from the `ci` block of
+`index.config.json`, so the way to change what CI does is to change the config
+and run `npm run ci`.
+
+| Key | Default | What it changes |
+|---|---|---|
+| `forge` | `github` | Which pipeline is rendered - `github` or `gitlab` |
+| `nodeVersion` | `22` | Node the jobs run on, and the GitLab image tag |
+| `enrich` | `true` | Pull READMEs, logos and version lists from the registry before building |
+| `grimVersion` | `latest` | grim release the enrichment step uses |
+| `autoMerge` | `false` | Squash-merge a pull request the gate passed, then deploy (GitHub only) |
+| `allowManualEdits` | `false` | Own the files by hand; drops the drift guard |
+
+`autoMerge` is off until you turn it on: merging an untrusted contribution
+unattended is your policy to set, not this package's to assume. It is GitHub
+only, and that is not an oversight - 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. On GitLab 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 wrote. Setting `autoMerge` with `forge: gitlab` is refused
+rather than rendered inert.
+
+A `verify-ci` job re-renders and diffs on every change that can produce
+drift - pushes and pull requests touching `index.config.json`,
+`package.json`, `package-lock.json`, or `.github/workflows/**` - so a
+hand-edit fails CI instead of silently forking. Action pins are excluded
+from that diff, so Renovate may bump `uses: owner/action@<ref>` freely.
+
+To pick up renderer fixes, bump `@grimoire-rs/indexer` the ordinary npm way and
+re-render:
 
 ```sh
-npx @grimoire-rs/indexer build      # index/** -> dist/
-npx @grimoire-rs/indexer validate   # run the contribution gate locally
+npm update @grimoire-rs/indexer
+npm run ci
 ```
 
-## Upgrading CI
-
-The workflows in this repo are thin callers of reusable workflows that
-[grim-indexer](https://github.com/grimoire-rs/indexer) owns. To
-pick up CI fixes, bump the pinned ref in the `uses:` line — nothing needs
-re-scaffolding, and your local edits are never overwritten.
+No CI *definitions* are fetched from outside this repo - no reusable
+workflow, no remote `include:` - so what you review in a diff is exactly
+what runs. The jobs themselves still reach the network: `npm ci` from the
+npm registry, `uses: actions/...@<sha>` from GitHub, and - with `enrich`
+on - a grim release tarball.

package/templates/ci/github-automerge.yml

@@ -0,0 +1,36 @@
+
+  # `needs: validate` is the entire safety condition. The gate's exit code is
+  # the authorization - 0 means "eligible for auto-merge" - and `needs:` is
+  # what turns that into "this job does not start". A cancelled or skipped
+  # gate is not a success either, so both also stop here.
+  #
+  # This job checks nothing out. Contributor content never touches the runner
+  # that holds the write token; the only thing it does with the pull request is
+  # name its number to `gh`.
+  #
+  # `--match-head-commit` closes the window between the two jobs: the gate
+  # judged one head sha, and without this a push landing while it ran would be
+  # what got merged - the contribution reviewed and the contribution merged
+  # would be different commits. Mismatch fails the job, and the next
+  # `synchronize` event re-runs the gate against the new head anyway.
+  automerge:
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write # dispatch pages.yml after the merge
+    steps:
+      - name: Merge and deploy
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          gh pr merge "$PR" --repo "$REPO" --squash --match-head-commit "$HEAD_SHA"
+          # A push made with GITHUB_TOKEN triggers no workflow, so the merge
+          # this job just made would never build the site. Dispatch it.
+          gh workflow run pages.yml --repo "$REPO" --ref "$BRANCH"

package/templates/ci/github-enrich.yml

@@ -0,0 +1,27 @@
+
+      # The index stores pointers; everything a reader looks at - README,
+      # changelog, logo, version list - lives in the registry, and grim is
+      # what reads a registry. `ci.grimVersion` pins the binary.
+      - name: Install grim
+        env:
+          # Resolved from `ci.grimVersion` when this file was rendered, so
+          # there is no version branch left to take at run time.
+          GRIM_RELEASE_BASE: "{{grimReleaseBase}}"
+        run: |
+          set -euo pipefail
+          tarball="grimoire-$(uname -m)-unknown-linux-gnu.tar.gz"
+          cd "$(mktemp -d)"
+          curl -fsSL --proto '=https' --tlsv1.2 \
+            -O "${GRIM_RELEASE_BASE}/${tarball}" -O "${GRIM_RELEASE_BASE}/${tarball}.sha256"
+          sha256sum -c "${tarball}.sha256"
+          tar -xzf "${tarball}" --strip-components=1 --wildcards -C /usr/local/bin '*/grim'
+          grim --version
+
+      # Enrichment is best-effort by design: a registry outage must degrade
+      # the site to pointers-only, never block a deploy that is otherwise
+      # ready. `enrich` itself keeps any sidecar it fails to refresh. Set
+      # `"enrich": false` in the `ci` block to drop these two steps entirely.
+      - name: Refresh package metadata
+        run: |
+          npm run enrich ||
+            echo "::warning::enrich failed - building without READMEs, logos and version lists"

package/templates/ci/github-pages.yml

@@ -0,0 +1,64 @@
+{{header}}
+# Builds this index and deploys it to GitHub Pages.
+#
+# Enable it once, in Settings -> Pages -> Source: "GitHub Actions". Until
+# that is set, this workflow runs green and deploys nothing.
+name: pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Default-deny at the top; every job pays for exactly what it needs.
+permissions: {}
+
+concurrency:
+  group: grim-indexer-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "{{nodeVersion}}"
+          cache: npm
+
+      # `npm ci` installs exactly package-lock.json, so which renderer builds
+      # this site is a reviewed fact in the repository, not a resolution that
+      # happens on the runner. `--ignore-scripts` because this job runs
+      # MERGED contributor content: a `prepare` script or a lock entry that
+      # arrived through an auto-merged pull request would otherwise execute
+      # here, in the job that publishes the site.
+      - name: Install
+        run: npm ci --ignore-scripts
+{{githubEnrichSteps}}
+      - name: Build index
+        run: npm run build
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

package/templates/ci/github-validate.yml

@@ -0,0 +1,157 @@
+{{header}}
+# Contribution gate for pull requests against this index.
+#
+# Exit 0 = eligible for auto-merge, non-zero = manual review required, so this
+# job's success IS the gate. To enforce it, require the status check named
+# `validate` in branch protection - the job key below is the context name, so
+# renaming the job moves the required context with it, and requiring a context
+# that never reports blocks every pull request forever.
+#
+# `pull_request_target` is deliberate and safe HERE, and only because of what
+# this job does: it runs the renderer this repository has locked, against the
+# TRUSTED base checkout, and reads the pull-request head as DATA ONLY in a
+# separate directory - nothing in it is executed, imported, installed, or
+# interpolated into a command. GitHub always runs the base branch's copy of a
+# `pull_request_target` workflow, so a contributor editing this file in their
+# pull request does not change the gate that judges it.
+#
+# The `npm ci` below installs the BASE checkout's package-lock.json, in the
+# base directory. That lock is maintainer-committed and reviewed like any
+# other file here. NEVER install, run, or `cd` into `pr-tree/`, and never add
+# a `run:` step that touches it - that would execute contributor code with a
+# token. `--ignore-scripts` holds the line one step further: the gate needs
+# nothing a dependency lifecycle script provides.
+#
+# Do not widen `permissions:`.
+#
+# This gate covers third-party contributions. It does NOT cover an announce
+# your own CI makes (the `--with-skills` layout, where this repo publishes into
+# its own index): GitHub runs no workflows on a pull request opened with
+# `secrets.GITHUB_TOKEN`, so `grim publish --announce` from CI lands an
+# effectively ungated pull request - review it by hand. That pull request also
+# needs "Allow GitHub Actions to create and approve pull requests"
+# (Settings -> Actions) turned on, off by default; without it grim only pushes
+# the branch and reports `outcome: "branch-pushed"`. Enabling it lets any
+# workflow in this repo approve pull requests too, so weigh it against your
+# branch protection.
+name: validate
+
+on:
+  pull_request_target:
+    paths:
+      - "index/**"
+      - index-policy.json
+
+permissions: {}
+
+# One gate run per pull request. Superseding a run cancels it, and a cancelled
+# run is not a success - so nothing downstream of the gate can act on a verdict
+# about a head that has already been replaced.
+concurrency:
+  group: grim-indexer-validate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      # Trusted: the committed state the pull request proposes to change.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Untrusted: the pull-request head, as data. `persist-credentials: false`
+      # keeps a token out of the tree the contributor controls.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: pr-tree
+          persist-credentials: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "{{nodeVersion}}"
+          cache: npm
+
+      - name: Install
+        run: npm ci --ignore-scripts
+
+      # Changed paths come from the API, not from a diff of the untrusted tree,
+      # and they reach the gate through a FILE - never through argv. They are
+      # attacker-controlled strings: appending them to the command line let a
+      # pull request that added an empty file named `-h` short-circuit the
+      # parser and exit 0, which this job's contract reads as "eligible for
+      # auto-merge". Do not reintroduce `xargs` here.
+      #
+      # EVERY changed path is passed through - no path filter, no status
+      # filter. Rejecting an out-of-bounds path is the gate's first job, and it
+      # ownership-checks a deletion before allowing it, so anything dropped
+      # here is dropped from the decision this job's exit code authorizes.
+      # Filtering to `^index/` would let a pull request that adds a valid entry
+      # and edits a workflow pass; filtering out `removed` would let one that
+      # adds its own entry and deletes a stranger's pass.
+      #
+      # The count cross-check is the same argument applied to pagination:
+      # `pulls/{n}/files` stops at 3000 files, so without it a large enough
+      # pull request pushes its interesting paths past the cap and the gate
+      # authorizes a change it never saw.
+      - name: Collect changed paths
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          files="repos/${REPO}/pulls/${PR}/files"
+
+          # ONE fetch, then every derivation from that one snapshot. Reading
+          # the endpoint once per derivation reads a mutable resource: a push
+          # landing between two calls left the count describing one head and
+          # the path list another, so the check certified a list it had never
+          # counted. `--paginate` emits one array per page; `-s add` makes them
+          # one array.
+          gh api --paginate "${files}" | jq -s 'add' > records.json
+
+          # Count RECORDS. The check exists because `pulls/{n}/files` stops at
+          # 3000 files - without it a large enough pull request pushes its
+          # interesting paths past the cap and the gate authorizes a change it
+          # never saw.
+          records=$(jq 'length' records.json)
+          declared=$(gh api "repos/${REPO}/pulls/${PR}" --jq '.changed_files')
+          if [ "${records}" -ne "${declared}" ]; then
+            echo "::error::collected ${records} of ${declared} changed files" \
+                 "- the gate cannot judge what it cannot see"
+            exit 1
+          fi
+
+          # A rename must contribute BOTH names, so a record that claims to be
+          # one without naming its source is refused rather than silently
+          # contributing only its destination - which is precisely the hole
+          # below closes.
+          orphans=$(jq '[.[] | select((.status == "renamed" or .status == "copied")
+                                      and ((.previous_filename // "") == ""))] | length' records.json)
+          if [ "${orphans}" -ne 0 ]; then
+            echo "::error::${orphans} renamed file(s) arrived with no previous_filename" \
+                 "- the source path cannot be checked"
+            exit 1
+          fi
+
+          # BOTH names of a rename. The API reports a rename as one record
+          # whose `filename` is the destination and whose `previous_filename`
+          # is the source; taking only the destination let a pull request copy
+          # a stranger's entry into its own namespace and delete the original,
+          # with the deletion never presented to the gate and no ownership
+          # check ever run on the victim's namespace.
+          jq -r '.[] | .filename, (.previous_filename // empty)' records.json > changed.txt
+
+      - name: Validate contribution
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          npm run validate -- \
+            --forge github --root . --pr-tree pr-tree --changed-from changed.txt
+{{githubAutoMergeJob}}

package/templates/ci/github-verify-ci.yml

@@ -0,0 +1,47 @@
+{{header}}
+# Fail closed when a generated CI file is hand-edited: this job re-renders from
+# index.config.json and diffs against what is committed. Fix drift by running
+# `npm run ci` locally and committing the result.
+#
+# It runs under `pull_request`, so it needs no secrets and never checks out a
+# trusted token. That also means a fork's copy of this file is what runs on
+# that fork's pull request - the guard is a maintenance check on the
+# repository's own history, not a trust boundary. The contribution gate
+# (validate.yml) is the trust boundary, and it rejects any pull request that
+# touches a path outside `index/<host>/<namespace>/<package>/`.
+name: verify-ci
+
+on:
+  pull_request:
+    paths:
+{{verifyPaths}}
+  push:
+    branches: [main]
+    paths:
+{{verifyPaths}}
+
+permissions: {}
+
+jobs:
+  verify-ci:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "{{nodeVersion}}"
+          cache: npm
+
+      # Rendering needs no build toolchain, so nothing here runs a dependency's
+      # lifecycle script.
+      - name: Install
+        run: npm ci --ignore-scripts
+
+      # Exits 65 on drift; the hint names the stale path and never its contents.
+      - name: Check the committed CI matches index.config.json
+        run: npm run ci:check

package/templates/ci/gitlab-ci.yml

@@ -0,0 +1,148 @@
+{{header}}
+# Builds this index for GitLab Pages and gates merge requests.
+
+stages:
+  - test
+  - deploy
+
+# `npm ci` installs exactly package-lock.json, so which renderer runs is a
+# reviewed fact in this repository rather than a resolution on the runner.
+default:
+  image: node:{{nodeVersion}}-alpine
+  cache:
+    key:
+      files:
+        - package-lock.json
+    paths:
+      - .npm/
+      - .npm-gate/
+
+# Contribution gate. Exit 0 = eligible for auto-merge, non-zero = manual
+# review required, so this job's status IS the gate.
+#
+# The gate must judge the change against the COMMITTED policy, not the policy
+# the merge request proposes - otherwise a contributor allowlists their own
+# registry host in the same merge request. So the target branch is checked out
+# into a sibling worktree and passed as `--root`, with the merge-request head
+# passed as `--pr-tree` and read as data only.
+#
+# The gate installs and runs from `../.gate-base`, the target branch's worktree -
+# never from the merge request's own checkout. Otherwise the contributor
+# supplies the lockfile that decides which validator judges them, and
+# `--ignore-scripts` alone does not fix that: the package it installs is still
+# theirs to choose. `--ignore-scripts` stays anyway, one layer further in.
+#
+# RESIDUAL, and it is not fixable from this file. Two ways, both structural:
+#
+#   1. The merge request supplies its own `.gitlab-ci.yml`, so a contributor
+#      can delete this job outright.
+#   2. GitLab runs a FORK merge request's pipeline in the source project, so
+#      `origin` is the fork. `origin/<target>` is then the fork's copy of the
+#      target branch, which means `../.gate-base` - and the `index-policy.json` and
+#      `package-lock.json` read from it - are contributor-controlled for a
+#      fork merge request. The `../.gate-base` install above is therefore defence in
+#      depth for same-project branches, not a trust boundary for forks.
+#
+# Enforce it instance-side - a compliance pipeline, a required merge check, or
+# protected-branch approval rules - or treat the GitLab gate as advisory. The
+# GitHub gate has no equivalent gap: `pull_request_target` always runs the base
+# branch's copy of the workflow, against the base checkout.
+grim-indexer:validate:
+  stage: test
+  variables:
+    GIT_DEPTH: 0
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  # The job image is picked for npm, and `node:*-alpine` ships no git - but
+  # this job diffs the merge request against its target branch, so git is not
+  # optional. GitLab's runner clones with a separate helper image, so nothing
+  # else puts git in here. Install it for whichever package manager the image
+  # has.
+  #
+  # The trailing check is the load-bearing part: the gate's contract is
+  # "exit 0 = eligible for auto-merge", so a missing or failed-to-install tool
+  # must fail the job, never silently skip validation.
+  before_script:
+    - |
+      set -eu
+      if ! command -v git >/dev/null 2>&1; then
+        if command -v apk >/dev/null 2>&1; then
+          apk add --no-cache git
+        elif command -v apt-get >/dev/null 2>&1; then
+          apt-get update -qq && apt-get install -y -qq --no-install-recommends git
+        fi
+      fi
+      command -v git >/dev/null 2>&1 || {
+        echo "grim-indexer: the gate needs git, and this image has none" >&2
+        exit 1
+      }
+  script:
+    - |
+      set -eu
+      git fetch --quiet origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+      # `../.gate-base` sits outside $CI_PROJECT_DIR, which is the part GitLab
+      # cleans. A leftover from an earlier run makes `git worktree add` fail
+      # and, under `set -eu`, fails the job permanently - fail-closed, but the
+      # shape that gets a gate switched off rather than fixed.
+      #
+      # The leading dot is load-bearing. `..` is the NAMESPACE directory,
+      # shared with every sibling project on this runner, and a GitLab project
+      # path must start with a letter or a digit - so no project can be named
+      # `.gate-base` and this `rm -rf` can never reach somebody else's
+      # checkout. It was `../base` for one revision, which a group holding a
+      # project called `base` would have had wiped on every gate run.
+      rm -rf ../.gate-base
+      git worktree prune
+      git worktree add --detach ../.gate-base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+      # Every changed path, with no pathspec and no diff filter: rejecting an
+      # out-of-bounds path is the gate's first job, and it ownership-checks a
+      # deletion before allowing it. Narrowing to `-- index` would let a merge
+      # request that adds a valid entry and edits this very file pass; dropping
+      # `D` would let one that deletes a stranger's entry pass.
+      #
+      # `--no-renames` is load-bearing. Git reports a rename as the DESTINATION
+      # path only, so copying a stranger's metadata.json into your own
+      # namespace and deleting the original was detected as a rename, the
+      # deletion never reached the gate, and no ownership check ever ran on the
+      # victim's namespace. With this flag both sides are listed.
+      #
+      # NEVER add `-C`. Copy detection re-collapses the pair to the
+      # destination in either flag order, which puts the hole straight back.
+      #
+      # `-z` and `--changed-from` keep these attacker-controlled strings off
+      # the command line and out of the shell's hands entirely: a path named
+      # `-h` used to make the parser print help and exit 0, which this job's
+      # contract reads as "eligible for auto-merge".
+      git diff -z --name-only --no-renames \
+        "$CI_MERGE_REQUEST_DIFF_BASE_SHA" HEAD > "$CI_PROJECT_DIR/changed.txt"
+      # Installed and run from the trusted target branch, never from the
+      # merge request's own lockfile. Its own cache directory, because the
+      # shared one is a path the merge request can commit into.
+      cd ../.gate-base
+      rm -rf "$CI_PROJECT_DIR/.npm-gate"
+      npm ci --cache "$CI_PROJECT_DIR/.npm-gate" --prefer-offline --ignore-scripts
+      npm run validate -- \
+        --forge gitlab --root . --pr-tree "$CI_PROJECT_DIR" \
+        --changed-from "$CI_PROJECT_DIR/changed.txt"
+{{gitlabVerifyJob}}
+# GitLab Pages serves whatever the `pages` job leaves in `public/`.
+pages:
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  before_script:
+    - npm ci --cache .npm --prefer-offline --ignore-scripts
+  script:
+    - |
+      set -eu
+{{gitlabEnrichScript}}
+    # Built into `dist/`, then moved. Building straight into `public/` was a
+    # data-loss bug: the compile step clears its output directory first, so it
+    # deleted this index's own committed asset layer (logo, favicon) before
+    # the renderer ever read it. `dist/` already contains those assets by the
+    # time this runs, so the replacement is complete.
+    - npm run build
+    - rm -rf public && mv dist public
+  artifacts:
+    paths:
+      - public

package/templates/ci/gitlab-enrich.sh

@@ -0,0 +1,26 @@
+      # The index stores pointers; README, changelog, logo and version list all
+      # live in the registry, and grim is what reads a registry. Best-effort by
+      # design - a registry outage degrades the site to pointers-only rather
+      # than blocking a deploy, so the failure is logged and the build
+      # continues. Set `"enrich": false` in the `ci` block to drop this block.
+      #
+      # Nothing is committed and no token is involved: the sidecars live only
+      # in this job's workspace, which is why this needs no CI variables.
+      if command -v apk >/dev/null 2>&1; then
+        apk add --no-cache curl tar
+      elif command -v apt-get >/dev/null 2>&1; then
+        apt-get update -qq && apt-get install -y -qq --no-install-recommends curl tar ca-certificates
+      fi
+      # Alpine is musl; everything else here is glibc.
+      if [ -f /etc/alpine-release ]; then libc=musl; else libc=gnu; fi
+      # Resolved from `ci.grimVersion` when this file was rendered, so there is
+      # no version branch left to take at run time.
+      base="{{grimReleaseBase}}"
+      tarball="grimoire-$(uname -m)-unknown-linux-$libc.tar.gz"
+      tmp="$(mktemp -d)"
+      ( cd "$tmp" \
+        && curl -fsSL --proto '=https' --tlsv1.2 -O "$base/$tarball" -O "$base/$tarball.sha256" \
+        && sha256sum -c "$tarball.sha256" \
+        && tar -xzf "$tarball" -C /usr/local/bin --strip-components=1 "${tarball%.tar.gz}/grim" ) \
+        && npm run enrich \
+        || echo "warning: enrich failed - building without READMEs, logos and version lists"