@grimoire-rs/indexer 0.2.1 → 0.3.0

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"

package/templates/ci/gitlab-verify.yml

@@ -0,0 +1,16 @@
+
+# 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.
+grim-indexer:verify-ci:
+  stage: test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  before_script:
+    # Rendering needs no build toolchain, so nothing here runs a dependency's
+    # lifecycle script.
+    - npm ci --cache .npm --prefer-offline --ignore-scripts
+  script:
+    # Exits 65 on drift; the hint names the stale path and never its contents.
+    - npm run ci:check

package/templates/ci/header.txt

@@ -0,0 +1,19 @@
+# Generated by @grimoire-rs/indexer - DO NOT EDIT.
+#
+# This file is rendered from the `ci` block of index.config.json and committed
+# to this repository, which owns and runs it. To change what CI does, change
+# the config and re-render:
+#
+#     npm run ci
+#
+# The version that renders it is the one in package-lock.json, so CI runs
+# `npm ci` and never fetches a floating release. Bump the dependency the
+# ordinary npm way, then re-render.
+#
+# The `verify-ci` job re-renders and diffs on every push and pull request, so a
+# hand-edit fails CI rather than silently forking. Action pins are excluded
+# from that diff - Renovate may bump `uses: owner/action@<ref>` freely.
+#
+# To own these files by hand instead, set `"allowManualEdits": true` in the
+# `ci` block: the guard is then not emitted, and CI fixes stop arriving by
+# re-render.

package/templates/gitattributes

@@ -0,0 +1,4 @@
+# `npm run ci:check` compares the generated CI byte for byte, and the renderer
+# emits LF. Git for Windows installs with `core.autocrlf=true`, so without this
+# an untouched clone has CRLF on disk and every generated file reads as drift.
+* text=auto eol=lf

package/templates/gitignore

@@ -1,12 +1,17 @@
 # Build output of `grim-indexer build`.
 dist/
 
-# NOT ignored: `public/` is this index's own asset layer — the logo and
+# NOT ignored: `public/` is this index's own asset layer - the logo and
 # favicon `index.config.json` names live there, and the build copies it into
 # `dist/`. Ignoring it means the site references files the deploy never had.
 
-# Renderer scratch dir — removed on a clean build, left behind by a killed one.
+# Renderer scratch dir - removed on a clean build, left behind by a killed one.
 .index-*/
 
 node_modules/
+.npm/
+
+# NOT ignored: `package-lock.json` is what pins the renderer this index builds
+# and validates with. Committing it is what makes `npm ci` in CI reproducible.
+
 .DS_Store

package/templates/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.0",
+  "private": true,
+  "description": "{{titleJson}}, a Grimoire package index.",
+  "type": "module",
+  "scripts": {
+    "dev": "grim-indexer dev",
+    "build": "grim-indexer build",
+    "enrich": "grim-indexer enrich",
+    "validate": "grim-indexer validate",
+    "ci": "grim-indexer ci",
+    "ci:check": "grim-indexer ci --check"
+  },
+  "devDependencies": {
+    "@grimoire-rs/indexer": "^{{version}}"
+  }
+}

package/templates/publish.toml

@@ -1,4 +1,4 @@
-# `grim publish` manifest — this repo holds both its own skills (under
+# `grim publish` manifest - this repo holds both its own skills (under
 # `skills/`) and the index that lists them, the combined layout
 # `grim-indexer init --with-skills` scaffolds.
 #
@@ -18,7 +18,7 @@ version = "0.1.0"
 # do not own.
 #
 # `repository` is this repo's https clone URL. `namespace` is the
-# `index/<host>/<namespace>/` your entries land under — the contribution gate
+# `index/<host>/<namespace>/` your entries land under - the contribution gate
 # refuses a namespace whose forge owner is not you. A literal `REPLACE-ME`
 # means the scaffold had nothing to derive it from: `--announce` then stops
 # with "cannot derive the index host" rather than announcing anywhere.

package/templates/github-pages.yml

@@ -1,24 +0,0 @@
-# Builds this index and deploys it to GitHub Pages.
-#
-# Deliberately a thin caller: the job logic lives in a reusable workflow
-# grim-indexer owns, so upgrades arrive by bumping the pinned ref below
-# instead of re-scaffolding this repo over your edits. Renovate's
-# `github-actions` manager bumps it for you.
-name: pages
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions: {}
-
-jobs:
-  pages:
-    uses: grimoire-rs/indexer/.github/workflows/index-pages.yml@{{ref}}
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    with:
-      grim-indexer-version: "{{version}}"

package/templates/github-validate.yml

@@ -1,51 +0,0 @@
-# Contribution gate for pull requests against this index.
-#
-# Exit 0 = eligible for auto-merge, non-zero = manual review required. To
-# enforce it, require the status check named `validate / validate` in branch
-# protection — NOT `validate`. A thin caller reports its check run as
-# `<job key here> / <job key in the called workflow>`, and both happen to be
-# `validate`; rename `jobs.validate` below and the required context moves
-# with it. Requiring a context that never reports blocks every PR forever,
-# and looks exactly like the gate rejecting the contribution.
-#
-# `pull_request_target` is deliberate and safe HERE, and only because of
-# what the called workflow does: it runs grim-indexer from npm against the
-# trusted base checkout, and reads the PR head as data in a separate
-# directory without ever executing, importing, or installing from it. The
-# gate needs a forge token to resolve numeric namespace-owner ids, which an
-# unprivileged `pull_request` job does not have.
-#
-# Do not switch this to run contributor code, and do not widen
-# `permissions:` here.
-#
-# 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 PR opened with
-# `secrets.GITHUB_TOKEN`, so `grim publish --announce` from CI lands an
-# effectively ungated PR — review it by hand. That PR 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 PRs too, so weigh it against your branch protection.
-#
-# Deliberately a thin caller: the job logic lives in a reusable workflow
-# grim-indexer owns, so upgrades arrive by bumping the pinned ref below
-# instead of re-scaffolding this repo over your edits.
-name: validate
-
-on:
-  pull_request_target:
-    paths:
-      - "index/**"
-      - "index-policy.json"
-
-permissions: {}
-
-jobs:
-  validate:
-    uses: grimoire-rs/indexer/.github/workflows/index-validate.yml@{{ref}}
-    permissions:
-      contents: read
-      pull-requests: read
-    with:
-      grim-indexer-version: "{{version}}"

package/templates/gitlab-ci.yml

@@ -1,13 +0,0 @@
-# Builds this index for GitLab Pages and gates merge requests.
-#
-# Deliberately a thin caller: the job logic lives in a file grim-indexer
-# owns, so upgrades arrive by bumping the pinned ref in the URL below
-# instead of re-scaffolding this repo over your edits.
-#
-# If your GitLab instance blocks remote includes, vendor the file locally
-# and switch to `- local: "ci/grim-indexer.yml"`.
-include:
-  - remote: "https://raw.githubusercontent.com/grimoire-rs/indexer/{{ref}}/templates/reusable/gitlab-index-ci.yml"
-
-variables:
-  GRIM_INDEXER_VERSION: "{{version}}"

package/templates/reusable/gitlab-index-ci.yml

@@ -1,125 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# Copyright 2026 The Grimoire Authors
-#
-# GitLab counterpart of the two reusable GitHub workflows: scaffolded index
-# repos pull this in with `include: remote:` so a fix here reaches them
-# without a re-scaffold. Override any variable below in the including
-# `.gitlab-ci.yml`.
-#
-# A private GitLab instance may refuse to fetch a remote include. The
-# fallback is to vendor this file into the index repo and switch the
-# include to `local:`.
-variables:
-  GRIM_INDEXER_VERSION: "latest"
-  GRIM_INDEXER_NODE_IMAGE: "node:22-alpine"
-  GRIM_INDEXER_OUT_DIR: "public"
-  # Refresh READMEs, changelogs, logos and version lists from the registry
-  # before building. Set to "false" for a pointers-only site that never
-  # leaves the runner.
-  GRIM_INDEXER_ENRICH: "true"
-  # grim release the enrichment step reads the registry with: "latest" or a tag.
-  GRIM_VERSION: "latest"
-
-stages:
-  - test
-  - deploy
-
-# 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 MR. So the target branch is checked
-# out into a sibling worktree and passed as `--root`, with the MR head
-# passed as `--pr-tree` and read as data only.
-#
-# RESIDUAL, and it is not fixable from this file: on GitLab the merge
-# request supplies its own `.gitlab-ci.yml`, so a contributor can delete
-# this job outright. Enforce it instance-side — a compliance pipeline, a
-# required merge check, or protected-branch approval rules — or treat the
-# GitLab gate as advisory.
-grim-indexer:validate:
-  stage: test
-  image: $GRIM_INDEXER_NODE_IMAGE
-  variables:
-    GIT_DEPTH: 0
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-  # The job image is picked for `npx`, 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 (overridable) 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 ${GRIM_INDEXER_NODE_IMAGE} has none" >&2
-        exit 1
-      }
-  script:
-    - |
-      set -eu
-      git fetch --quiet origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
-      git worktree add --detach ../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 an MR
-      # that adds a valid entry and edits this very file pass; dropping `D`
-      # would let one that deletes a stranger's entry pass.
-      git diff --name-only "$CI_MERGE_REQUEST_DIFF_BASE_SHA" HEAD > changed.txt
-      xargs -a changed.txt npx --yes "@grimoire-rs/indexer@$GRIM_INDEXER_VERSION" validate \
-        --forge gitlab --root ../base --pr-tree .
-
-# GitLab Pages serves whatever the `pages` job leaves in `public/`.
-pages:
-  stage: deploy
-  image: $GRIM_INDEXER_NODE_IMAGE
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-  # 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.
-  #
-  # 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 at all.
-  script:
-    - |
-      set -eu
-      if [ "$GRIM_INDEXER_ENRICH" = "true" ]; then
-        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
-        case "$GRIM_VERSION" in
-          latest) base=https://github.com/grimoire-rs/grimoire/releases/latest/download ;;
-          *) base="https://github.com/grimoire-rs/grimoire/releases/download/$GRIM_VERSION" ;;
-        esac
-        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" ) \
-          && npx --yes "@grimoire-rs/indexer@$GRIM_INDEXER_VERSION" enrich \
-          || echo "warning: enrich failed — building without READMEs, logos and version lists"
-      fi
-    - npx --yes "@grimoire-rs/indexer@$GRIM_INDEXER_VERSION" build --out-dir "$GRIM_INDEXER_OUT_DIR"
-  artifacts:
-    paths:
-      - $GRIM_INDEXER_OUT_DIR