@grimoire-rs/indexer 0.1.0

package/dist/validate/index.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+/**
+ * The index contribution gate.
+ *
+ * Runs from the TRUSTED base checkout (GitHub `pull_request_target`, or a
+ * GitLab pipeline with `scripts/` re-checked-out from the target branch). PR
+ * content is consumed as data only — never executed, never imported, never
+ * interpolated into a command.
+ *
+ * `eligible: true` means the change may be auto-merged. Anything else means a
+ * human looks at it: this gate never rejects a contribution, it only declines
+ * to wave it through. Callers map that to the exit contract — 0 for eligible,
+ * non-zero for manual review.
+ *
+ * Three separated concerns make auto-merging an untrusted PR safe:
+ *   identity      — the forge account that authored the PR; the forge proves it
+ *   authorization — the *numeric* namespace owner id, never the login string
+ *   verification  — the OCI ref re-checked against registry truth, not trusted
+ */
+import { createForge } from "./adapters/forge.js";
+import { readIndexFile } from "./adapters/files.js";
+import { refReachable } from "./adapters/registry.js";
+import { ownerLogin, parseMetadataJson, parseRef, registryHostReason, validateMetadata, } from "./core/metadata.js";
+import { parseIndexPath } from "./core/paths.js";
+import { botOwnsNamespace, findTrustedBot, namespaceOwned, } from "./core/ownership.js";
+const env = (name) => process.env[name] || undefined;
+function forgeHost(options) {
+    if (options.host)
+        return options.host;
+    return options.forge === "github" ? "github.com" : env("CI_SERVER_HOST");
+}
+function apiBase(options) {
+    if (options.apiBase)
+        return options.apiBase;
+    return options.forge === "github"
+        ? env("GITHUB_API_URL") ?? "https://api.github.com"
+        : env("CI_API_V4_URL");
+}
+function apiToken(options) {
+    if (options.token)
+        return options.token;
+    return options.forge === "github"
+        ? env("GH_TOKEN") ?? env("GITHUB_TOKEN")
+        : env("GRIM_INDEX_BOT_TOKEN");
+}
+function isHttps(url) {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export async function runValidate(options) {
+    try {
+        const reasons = await collectReasons(options);
+        return { eligible: reasons.length === 0, reasons };
+    }
+    catch (error) {
+        // Any unexpected failure is a manual review, never an approval.
+        return {
+            eligible: false,
+            reasons: [`unexpected error: ${error.message}`],
+        };
+    }
+}
+async function collectReasons(options) {
+    const host = forgeHost(options);
+    const api = apiBase(options);
+    if (!host)
+        return ["forge host is not configured"];
+    if (!api)
+        return ["forge API base URL is not configured"];
+    if (!isHttps(api))
+        return [`forge API base URL ${api} is not https`];
+    const changed = [...new Set(options.changedFiles.filter((file) => file !== ""))];
+    if (changed.length === 0)
+        return ["empty change set"];
+    // 1. Path gate. Nothing else runs until every path is in bounds — no forge
+    //    call, no registry call, no read of PR content.
+    const paths = [];
+    const pathReasons = [];
+    for (const file of changed) {
+        const parsed = parseIndexPath(file, options.forge, host);
+        if (parsed === null) {
+            pathReasons.push(`${file}: outside index/${host}/<ns>/<pkg>/metadata.json — manual review`);
+            continue;
+        }
+        paths.push(parsed);
+    }
+    if (pathReasons.length > 0)
+        return pathReasons;
+    // 2. Namespace ownership, once per namespace.
+    const forge = createForge(options.forge, {
+        apiBase: api,
+        token: apiToken(options),
+        minAccessLevel: options.minAccessLevel,
+    });
+    const identities = new Map();
+    const ownershipReasons = [];
+    const reserved = new Set((options.reservedNamespaces ?? []).map((name) => name.toLowerCase()));
+    for (const namespace of [...new Set(paths.map((p) => p.namespace))].sort()) {
+        if (reserved.has(namespace.toLowerCase())) {
+            ownershipReasons.push(`namespace ${JSON.stringify(namespace)} is reserved`);
+            continue;
+        }
+        const identity = await forge.namespaceIdentity(namespace);
+        if (identity === null) {
+            ownershipReasons.push(`namespace ${JSON.stringify(namespace)} does not exist on ${host}`);
+            continue;
+        }
+        identities.set(namespace, identity);
+        const bot = findTrustedBot(options.trustedBots, options.author.login);
+        const owned = bot !== null
+            ? // A login matching a trusted bot is never re-checked as a human: an
+                // impostor on that login is refused outright, not given a second path.
+                botOwnsNamespace(bot, namespace, options.author.id)
+            : namespaceOwned(namespace, identity, options.author, identity.kind === "user"
+                ? false
+                : await forge.isMember(namespace, options.author));
+        if (!owned) {
+            ownershipReasons.push(`namespace ${JSON.stringify(namespace)} is not owned by ${JSON.stringify(options.author.login)}`);
+        }
+    }
+    if (ownershipReasons.length > 0)
+        return ownershipReasons;
+    // 3. Per-file content checks.
+    const reasons = [];
+    for (const path of paths) {
+        const reason = await checkFile(path, identities, options);
+        if (reason !== null)
+            reasons.push(`${path.file}: ${reason}`);
+    }
+    return reasons;
+}
+async function checkFile(path, identities, options) {
+    const read = await readIndexFile(options.prTree, path.file);
+    // A path with no file in the PR tree is a deletion by the namespace owner,
+    // whose ownership was already established above.
+    if (read.kind === "missing")
+        return null;
+    if (read.kind === "error")
+        return read.reason;
+    const parsed = parseMetadataJson(read.text);
+    if (!parsed.ok)
+        return parsed.reason;
+    const checked = validateMetadata(parsed.value, path.pkg);
+    if (!checked.ok)
+        return checked.reason;
+    const meta = checked.value;
+    const identity = identities.get(path.namespace);
+    if (identity === undefined)
+        return "namespace identity is unknown";
+    const login = ownerLogin(meta.owner);
+    if (login.toLowerCase() !== path.namespace.toLowerCase()) {
+        return `owner login ${JSON.stringify(login)} != namespace ${JSON.stringify(path.namespace)}`;
+    }
+    if (String(meta.owner.id) !== identity.id) {
+        return `owner.id ${JSON.stringify(meta.owner.id)} != ${options.forge} id ${identity.id}`;
+    }
+    const continuity = await committedOwnerReason(path, meta, options.root);
+    if (continuity !== null)
+        return continuity;
+    const ref = parseRef(meta.ref);
+    if (!ref.ok)
+        return ref.reason;
+    // Host policy before the request — the ref is attacker-chosen input.
+    const hostReason = registryHostReason(ref.value.host, options.registryHosts);
+    if (hostReason !== null)
+        return hostReason;
+    const reachable = await refReachable(ref.value.host, ref.value.repository, {
+        auth: options.registryAuth ?? env("GRIM_INDEX_REGISTRY_AUTH"),
+        allowlist: options.registryHosts,
+    });
+    if (!reachable) {
+        return `ref ${JSON.stringify(meta.ref)} has no reachable tags — publish first`;
+    }
+    return null;
+}
+/**
+ * The committed entry is the authorization record: an existing package keeps
+ * the owner id it was published under. A namespace whose login was freed and
+ * re-registered resolves to a *different* account id on the forge, so this is
+ * what stops the new holder from inheriting the old holder's packages.
+ */
+async function committedOwnerReason(path, submitted, root) {
+    const read = await readIndexFile(root, path.file);
+    if (read.kind === "missing")
+        return null; // new package
+    if (read.kind === "error") {
+        return `cannot read the committed entry (${read.reason}) — manual review`;
+    }
+    const parsed = parseMetadataJson(read.text);
+    if (!parsed.ok)
+        return `committed entry is unreadable (${parsed.reason})`;
+    const committed = validateMetadata(parsed.value, path.pkg);
+    if (!committed.ok) {
+        return `committed entry is invalid (${committed.reason}) — manual review`;
+    }
+    if (committed.value.owner.id !== submitted.owner.id) {
+        return `owner.id ${JSON.stringify(submitted.owner.id)} != committed owner.id ${JSON.stringify(committed.value.owner.id)}`;
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map

package/dist/validate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validate/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAA0B,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAkB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,cAAc,GAEf,MAAM,qBAAqB,CAAC;AAuC7B,MAAM,GAAG,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;AAEjF,SAAS,SAAS,CAAC,OAAwB;IACzC,IAAI,OAAO,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC;IACtC,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,OAAO,CAAC,OAAwB;IACvC,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAC5C,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,wBAAwB;QACnD,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,QAAQ,CAAC,OAAwB;IACxC,IAAI,OAAO,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IACxC,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC;QACxC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAwB;IAExB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gEAAgE;QAChE,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,CAAC,qBAAsB,KAAe,CAAC,OAAO,EAAE,CAAC;SAC3D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAwB;IACpD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;IACnD,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,sCAAsC,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,sBAAsB,GAAG,eAAe,CAAC,CAAC;IAErE,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEtD,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,WAAW,CAAC,IAAI,CACd,GAAG,IAAI,mBAAmB,IAAI,2CAA2C,CAC1E,CAAC;YACF,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAE/C,8CAA8C;IAC9C,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE;QACvC,OAAO,EAAE,GAAG;QACZ,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;QACxB,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAA6B,CAAC;IACxD,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CACrE,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3E,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC1C,gBAAgB,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;YAC5E,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC1D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,gBAAgB,CAAC,IAAI,CACnB,aAAa,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,sBAAsB,IAAI,EAAE,CACnE,CAAC;YACF,SAAS;QACX,CAAC;QACD,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAEpC,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,KAAK,GACT,GAAG,KAAK,IAAI;YACV,CAAC,CAAC,oEAAoE;gBACpE,uEAAuE;gBACvE,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACrD,CAAC,CAAC,cAAc,CACZ,SAAS,EACT,QAAQ,EACR,OAAO,CAAC,MAAM,EACd,QAAQ,CAAC,IAAI,KAAK,MAAM;gBACtB,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CACpD,CAAC;QACR,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,gBAAgB,CAAC,IAAI,CACnB,aAAa,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACjG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAEzD,8BAA8B;IAC9B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,IAAe,EACf,UAA0C,EAC1C,OAAwB;IAExB,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,2EAA2E;IAC3E,iDAAiD;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,MAAM,CAAC;IAE9C,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACrC,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACzD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC;IAE3B,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,+BAA+B,CAAC;IAEnE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;QACzD,OAAO,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IAC/F,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,EAAE,EAAE,CAAC;QAC1C,OAAO,YAAY,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,OAAO,CAAC,KAAK,OAAO,QAAQ,CAAC,EAAE,EAAE,CAAC;IAC3F,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAE3C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC;IAC/B,qEAAqE;IACrE,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAE3C,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE;QACzE,IAAI,EAAE,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC,0BAA0B,CAAC;QAC7D,SAAS,EAAE,OAAO,CAAC,aAAa;KACjC,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,wCAAwC,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,oBAAoB,CACjC,IAAe,EACf,SAAmB,EACnB,IAAY;IAEZ,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,CAAC,cAAc;IACxD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,oCAAoC,IAAI,CAAC,MAAM,mBAAmB,CAAC;IAC5E,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,kCAAkC,MAAM,CAAC,MAAM,GAAG,CAAC;IAC1E,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3D,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO,+BAA+B,SAAS,CAAC,MAAM,mBAAmB,CAAC;IAC5E,CAAC;IACD,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACpD,OAAO,YAAY,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IAC5H,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@grimoire-rs/indexer",
+  "version": "0.1.0",
+  "description": "CLI + Astro integration for running your own grim package index",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "bin": {
+    "grim-indexer": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./integration": {
+      "types": "./dist/integration.d.ts",
+      "import": "./dist/integration.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && mkdir -p dist/renderer/astro dist/renderer/public && cp -r src/renderer/astro/. dist/renderer/astro/ && cp -r src/renderer/public/. dist/renderer/public/",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.14.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.8.0",
+    "js-yaml": "^4.1.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@astrojs/preact": "^6.0.1",
+    "@clack/prompts": "^1.7.0",
+    "astro": "^7.1.4",
+    "commander": "^15.0.0",
+    "preact": "^10.29.7"
+  }
+}

package/templates/README.md

@@ -0,0 +1,48 @@
+# {{title}}
+
+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}}.
+
+## Layout
+
+| 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-policy.json` | Committed allowlist of registry hosts contributions may point at |
+| `dist/` | Build output (`all.json`, per-path copies, the rendered site) — not committed |
+
+## 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.
+
+```json
+{
+  "schema": 1,
+  "name": "{{name}}-example",
+  "kind": "skill",
+  "ref": "{{registryHost}}/{{registryAlias}}/skills/{{name}}-example:1.0.0",
+  "description": "One line describing what this package does.",
+  "owner": { "id": 0, "github": "your-github-login" }
+}
+```
+
+The directory name must equal `name`, and `kind` is one of `skill`,
+`rule`, `agent`, `mcp`, `bundle`.
+
+## Local development
+
+```sh
+npx @grimoire-rs/indexer build      # index/** -> dist/
+npx @grimoire-rs/indexer validate   # run the contribution gate locally
+```
+
+## 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.

package/templates/github-pages.yml

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,36 @@
+# Contribution gate for pull requests against this index.
+#
+# Exit 0 = eligible for auto-merge, non-zero = manual review required.
+# Make `validate` a required status check in branch protection to enforce it.
+#
+# `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.
+#
+# 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/gitignore

@@ -0,0 +1,9 @@
+# Build output of `grim-indexer build`.
+dist/
+public/
+
+# Renderer scratch dir — removed on a clean build, left behind by a killed one.
+.index-*/
+
+node_modules/
+.DS_Store

package/templates/gitlab-ci.yml

@@ -0,0 +1,13 @@
+# 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/publish.toml

@@ -0,0 +1,17 @@
+# `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.
+#
+# The default layout is a standalone index repo instead: an index is a
+# distribution database that N separate skill repos announce into. Use
+# this combined form when one team owns both sides.
+#
+# Publish with `grim publish`, then announce into this index. Schema:
+# `grim schema --kind publish`.
+registry = "{{registryHost}}"
+version = "0.1.0"
+
+# One table per package. `repository` is the path under the registry host.
+#
+# [skills.example]
+# repository = "{{registryAlias}}/skills/example"

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

@@ -0,0 +1,61 @@
+# 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"
+
+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"
+  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"
+      git diff --name-only --diff-filter=ACMR "$CI_MERGE_REQUEST_DIFF_BASE_SHA" HEAD -- index > 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
+  script:
+    - npx --yes "@grimoire-rs/indexer@$GRIM_INDEXER_VERSION" build --out-dir "$GRIM_INDEXER_OUT_DIR"
+  artifacts:
+    paths:
+      - $GRIM_INDEXER_OUT_DIR

package/templates/reusable/index-pages.yml

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The Grimoire Authors
+#
+# Reusable workflow: build a grimoire index repo and publish it to GitHub
+# Pages. Scaffolded index repos call this by ref rather than inlining the
+# job logic, so a fix here reaches every downstream index without anyone
+# re-running `grim-indexer init` over their edits. Renovate's built-in
+# `github-actions` manager bumps the pinned ref in each caller.
+#
+# Copy this file to `.github/workflows/index-pages.yml` in this repo — a
+# reusable workflow must live directly in `.github/workflows/`, GitHub does
+# not resolve subdirectories.
+name: grim-indexer pages
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        description: Node.js version used to run grim-indexer.
+        type: string
+        required: false
+        default: "22"
+      grim-indexer-version:
+        description: npm version or range of grim-indexer to run.
+        type: string
+        required: false
+        default: latest
+      out-dir:
+        description: Directory `grim-indexer build` writes the site into.
+        type: string
+        required: false
+        default: dist
+
+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: ${{ inputs.node-version }}
+
+      # Inputs reach the shell through env vars, never through `run:`
+      # interpolation — a caller-supplied value must not be able to close
+      # the quoting and append a command.
+      - name: Build index
+        env:
+          VERSION: ${{ inputs.grim-indexer-version }}
+          OUT_DIR: ${{ inputs.out-dir }}
+        run: npx --yes "@grimoire-rs/indexer@${VERSION}" build --out-dir "${OUT_DIR}"
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: ${{ inputs.out-dir }}
+
+  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/reusable/index-validate.yml

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The Grimoire Authors
+#
+# Reusable workflow: the contribution gate for an index repo.
+#
+# Runs from the TRUSTED base checkout under `pull_request_target`, because
+# the gate needs a forge token to resolve numeric namespace-owner ids. The
+# PR head is checked out into a SEPARATE directory and consumed as DATA
+# ONLY — nothing in it is executed, imported, installed, or interpolated
+# into a command. `@grimoire-rs/indexer` itself comes from npm, never from the PR.
+#
+# Do not add a `run:` step that touches `pr-tree/`, and never add
+# `npm ci`/`npm install` — that would execute contributor code with a
+# write-capable token.
+#
+# The gate contract is the exit code of `grim-indexer validate`:
+#   0        -> eligible for auto-merge
+#   non-zero -> manual review required
+# so this job's success/failure IS the gate. Branch protection on the
+# calling repo turns that into a merge decision.
+#
+# Copy this file to `.github/workflows/index-validate.yml` in this repo — a
+# reusable workflow must live directly in `.github/workflows/`, GitHub does
+# not resolve subdirectories.
+name: grim-indexer validate
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        description: Node.js version used to run grim-indexer.
+        type: string
+        required: false
+        default: "22"
+      grim-indexer-version:
+        description: npm version or range of grim-indexer to run.
+        type: string
+        required: false
+        default: latest
+
+permissions: {}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      # Trusted: the committed state the PR proposes to change.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Untrusted: PR 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: ${{ inputs.node-version }}
+
+      # Changed paths come from the API, not from a diff of the untrusted
+      # tree. `jq -r` output is written to a file and passed via `xargs -a`
+      # so a crafted filename can never reach the shell as syntax.
+      - name: Collect changed paths
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          gh api --paginate "repos/${REPO}/pulls/${PR}/files" \
+            --jq '.[] | select(.status != "removed") | .filename' \
+            | grep -E '^index/' > changed.txt || : > changed.txt
+
+      - name: Validate contribution
+        env:
+          VERSION: ${{ inputs.grim-indexer-version }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          xargs -a changed.txt npx --yes "@grimoire-rs/indexer@${VERSION}" validate \
+            --forge github --root . --pr-tree pr-tree