@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/scripts/ci/check-skill-packs.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * check-skill-packs.mjs — integrity ratchet for the vendored design skill packs.
+ *
+ * WP-M7 ships four upstream skill packs inside the tarball
+ * (`plugins/maestro-skills/vendor/<pack>/`), and `global-setup` copies them into
+ * `~/.claude/skills/` on every seat. That makes them prompt content executed by
+ * every session on the fleet, sourced from repositories we do not control.
+ *
+ * **What this guard does and does not establish.** It cannot prove provenance:
+ * nothing offline can show that a vendored byte came from the pinned upstream
+ * commit, because `UPSTREAM.json` is written from the very bytes it records.
+ * What it establishes is that the vendored trees have not moved since a human
+ * reviewed them — and it makes moving them require editing a file OUTSIDE the
+ * vendored tree, so the change cannot hide inside a data blob. Re-verifying
+ * against upstream is a networked maintainer step:
+ * `node scripts/vendor/sync-skill-packs.mjs --all --dry-run`.
+ *
+ * Six assertions, per pack:
+ *
+ *   1. **Manifest fidelity.** Every path in `UPSTREAM.json` exists and hashes to
+ *      the recorded sha256, and no file exists in the pack that the manifest
+ *      does not list. A tampered byte and a smuggled extra file both go red.
+ *   2. **Content pin.** `manifestDigest(files)` matches the `contentSha256`
+ *      pinned for the pack in `scripts/vendor/skill-packs.mjs`. This is what
+ *      closes assertion 1's loop: a manifest rewritten to bless a new file is
+ *      self-consistent and would otherwise pass, and the pack's rules are
+ *      *patterns* (`reference/**.md`), so the allow-list alone admits a file
+ *      that never existed upstream. Adding one now also has to change a pinned
+ *      hex string in a reviewed source file.
+ *   3. **Allow-list.** Every vendored path is one the pack's rules admit — the
+ *      shape check that keeps a re-sync from widening what a pack may carry.
+ *   4. **No hooks, in manifest OR in machinery.** No vendored file is a hook
+ *      manifest (a `hooks.json`/`settings.json`, or JSON with a lifecycle-keyed
+ *      `hooks` object), and no vendored file is a hook installer or hook body by
+ *      name ({@link HOOK_SCRIPT_BASENAMES}). unlazy's Stop hook is not merely
+ *      "not installed": its two scripts are not vendored, because a file that
+ *      reaches the seat can be run whatever an executable bit says.
+ *   5. **Reviewed supply-chain surface.** Every fetch-and-execute instruction in
+ *      vendored prose — `curl … | sh`, a fetch to a non-GitHub host, `npx <pkg>`,
+ *      `npm install`, `pip install`, `git clone`, a remote script/asset URL in
+ *      sample markup — yields a token that must appear in the pack's
+ *      `acknowledged` list, and each acknowledgement's `covered` literal must
+ *      appear in the harmoniser skill. A re-sync that pulls in a NEW such
+ *      instruction stops until someone reviews it and says what to do instead.
+ *   6. **No executables** except where a pack declares one (unlazy's `scripts/`).
+ *
+ * Pure, dependency-light: Node builtins only. ESM.
+ *
+ * Usage: `node scripts/ci/check-skill-packs.mjs`  (exit 0 ok / 1 violations / 2 could not run)
+ * @module scripts/ci/check-skill-packs
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  PACKS, isAllowedDest, isExecAllowed, posix,
+  FETCH_HOST_ALLOWLIST, HOOK_SCRIPT_BASENAMES, manifestDigest,
+} from "../vendor/skill-packs.mjs";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Where vendored packs live, relative to the repo root. */
+export const VENDOR_REL = path.join("plugins", "maestro-skills", "vendor");
+
+/** The harmoniser skill, which every acknowledgement must be answered in. */
+export const HARMONISER_REL = path.join("plugins", "maestro-skills", "skills", "cohort-design.md");
+
+/** Claude Code lifecycle events; a JSON `hooks` object keyed by one is a manifest. */
+export const HOOK_EVENT_KEYS = Object.freeze([
+  "PreToolUse", "PostToolUse", "Stop", "SubagentStop", "SessionStart", "SessionEnd",
+  "UserPromptSubmit", "PreCompact", "Notification",
+]);
+
+/** Filenames that are hook/settings manifests whatever they contain. */
+export const MANIFEST_BASENAMES = Object.freeze(["hooks.json", "settings.json", "settings.local.json"]);
+
+/**
+ * The supply-chain rules. Each one names a way for vendored prose to tell a
+ * reader "retrieve something from the network and run it" — the capability the
+ * rule is about, not one command's spelling.
+ *
+ * This started as a single `curl|wget|fetch` regex, which was the wrong shape
+ * twice over: `npx some-package`, `pip install --index-url …`, `git clone` and
+ * a CDN `<script src>` all fetch and execute without matching it, and a
+ * `curl … | sh` whose URL is on `raw.githubusercontent.com` matched but was
+ * waved through, even though anyone may publish anything there.
+ *
+ * `host` names the capture group holding a URL (the token carries its host);
+ * `cap` names a group holding a package specifier; neither means the whole
+ * match is the token. `allowHost: false` means the GitHub allow-list does NOT
+ * apply — piping a download into a shell is the same act wherever it is hosted.
+ *
+ * @type {ReadonlyArray<{id:string, re:RegExp, host?:number, cap?:number, allowHost?:boolean, label:string}>}
+ */
+export const SUPPLY_CHAIN_RULES = Object.freeze([
+  {
+    id: "pipe-exec",
+    label: "downloads and pipes straight into a shell",
+    re: /\b(?:curl|wget)\b[^\n|]{0,200}?(https?:\/\/[^\s"'`)<>]+)[^\n|]{0,80}\|\s*(?:sudo\s+)?(?:sh|bash|zsh|node|python[23]?|ruby|perl)\b/gi,
+    host: 1,
+    allowHost: false,
+  },
+  {
+    id: "fetch-exec",
+    label: "fetches from a host outside GitHub",
+    re: /(?:\b(?:curl|wget)\b[^\n]{0,200}?|\bfetch\s*\(\s*["'`]|\bInvoke-(?:WebRequest|RestMethod)\b[^\n]{0,120}?)(https?:\/\/[^\s"'`)<>]+)/gi,
+    host: 1,
+  },
+  {
+    id: "git-clone",
+    label: "clones a repository",
+    re: /\bgit\s+clone\b[^\n]{0,160}?(https?:\/\/[^\s"'`)<>]+)/gi,
+    host: 1,
+  },
+  {
+    id: "npx",
+    label: "runs a package straight from a registry",
+    re: /\bnpx\s+(?:--?[\w-]+(?:[= ][^\s]+)?\s+)*(@?[\w.@/-]+)/gi,
+    cap: 1,
+  },
+  {
+    id: "pkg-install",
+    label: "installs a package from a registry",
+    re: /\b(?:npm|pnpm|yarn|bun)\s+(?:install|add)\b(?!\s*$)/gi,
+  },
+  {
+    id: "pip-install",
+    label: "installs a package from a registry",
+    re: /\bpip3?\s+install\b/gi,
+  },
+  {
+    id: "remote-asset",
+    label: "points shipped markup at a remote asset",
+    re: /(?:src\s*=\s*["'`]|url\s*\(\s*["'`]?)(https?:\/\/[^\s"'`)<>]+)/gi,
+    host: 1,
+  },
+  {
+    // A URL with an interpolation placeholder is not a citation — it is a
+    // template the reader is told to emit into code. That is what separates
+    // "https://picsum.photos/seed/{name}/1920/1080" from a link in prose.
+    id: "template-url",
+    label: "is a URL template for generated markup",
+    re: /(https?:\/\/[^\s"'`)<>]*\{[^\s"'`)<>]*)/gi,
+    host: 1,
+  },
+]);
+
+/**
+ * Wording that walks a reader through installing a hook, in a file that is not
+ * itself a manifest. `reference/hooks.md` is prose and so invisible to the
+ * no-manifest rule, but the shipped risk of a hook is the instruction to make
+ * one, not the JSON.
+ */
+const HOOK_DOC_RE = /(?:settings(?:\.local)?\.json|hooks\.json)/i;
+
+/** @param {string} u @returns {string|null} lowercased host, or null when unparseable */
+export function hostOf(u) {
+  try { return new URL(u.split("{")[0]).host.toLowerCase() || null; } catch { return null; }
+}
+
+/**
+ * Every supply-chain token in `body`, with an example of each. Pure.
+ *
+ * A token is coarse on purpose — `pkg-install`, `npx:<package>`,
+ * `remote-asset:<host>` — because the reviewable unit is the capability and its
+ * counterparty, not the twelve `npm install` lines a style guide happens to
+ * list.
+ *
+ * @param {string} body
+ * @param {string} [rel] the file's pack-relative path, for the hook-doc rule
+ * @returns {Array<{token:string, label:string, sample:string}>}
+ */
+export function findSupplyChainTokens(body, rel = "") {
+  const text = String(body || "");
+  const seen = new Map();
+  const add = (token, label, sample) => {
+    if (!seen.has(token)) seen.set(token, { token, label, sample: sample.slice(0, 90).replace(/\s+/g, " ") });
+  };
+  for (const rule of SUPPLY_CHAIN_RULES) {
+    rule.re.lastIndex = 0;
+    let m;
+    while ((m = rule.re.exec(text)) !== null) {
+      let token = rule.id;
+      if (rule.host != null) {
+        const host = hostOf(m[rule.host]);
+        if (!host) continue;
+        if (rule.allowHost !== false && FETCH_HOST_ALLOWLIST.includes(host)) continue;
+        token = `${rule.id}:${host}`;
+      } else if (rule.cap != null) {
+        token = `${rule.id}:${m[rule.cap]}`;
+      }
+      add(token, rule.label, m[0]);
+    }
+  }
+  if (/\.md$/i.test(posix(rel)) && HOOK_DOC_RE.test(text) && /\bhooks?\b/i.test(text)) {
+    const line = text.split("\n").find((l) => HOOK_DOC_RE.test(l)) || "";
+    add("hook-install-doc", "documents installing a hook into a settings file", line);
+  }
+  return [...seen.values()].sort((a, b) => (a.token < b.token ? -1 : 1));
+}
+
+/**
+ * Fetch instructions in `body` that point outside GitHub. Kept as the narrow
+ * predicate it always was; {@link findSupplyChainTokens} is the rule the guard
+ * runs. Pure.
+ * @param {string} body
+ * @returns {Array<{url:string, host:string}>}
+ */
+export function findForeignFetches(body) {
+  return findSupplyChainTokens(body)
+    .filter((t) => t.token.startsWith("fetch-exec:") || t.token.startsWith("pipe-exec:"))
+    .map((t) => ({ url: t.sample, host: t.token.slice(t.token.indexOf(":") + 1) }));
+}
+
+/**
+ * Is this file a hook manifest? Name-based for the well-known manifest files,
+ * content-based for any JSON carrying a lifecycle-keyed `hooks` object. Pure.
+ * @param {string} rel @param {string} body
+ * @returns {string|null} the reason, or null when clean
+ */
+export function hookManifestReason(rel, body) {
+  const base = posix(rel).split("/").pop();
+  if (MANIFEST_BASENAMES.includes(base)) return `${base} is a hook/settings manifest`;
+  // A hook INSTALLER on the seat is worse than a hook manifest in the tarball:
+  // it is one `node <path>` away from writing a Stop hook into the settings
+  // file every session reads, and the executable bit it does not need is the
+  // only thing the mode check would have looked at.
+  if (HOOK_SCRIPT_BASENAMES.includes(base)) return `${base} is hook machinery — vendor the prose, never the installer`;
+  if (!base.endsWith(".json")) return null;
+  let doc;
+  try { doc = JSON.parse(String(body)); } catch { return null; }
+  const hooks = doc && typeof doc === "object" ? doc.hooks : null;
+  if (!hooks || typeof hooks !== "object") return null;
+  const events = Object.keys(hooks).filter((k) => HOOK_EVENT_KEYS.includes(k));
+  if (events.length === 0) return null;
+  return `JSON carries a hooks manifest for ${events.join(", ")}`;
+}
+
+/** Recursively list files under `dir` relative to it (POSIX), sorted. */
+export function listFiles(dir, prefix = "") {
+  let out = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) out = out.concat(listFiles(path.join(dir, e.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/** Collapse runs of whitespace so a hard-wrapped sentence matches itself. Pure. */
+export function flatten(text) {
+  return String(text || "").replace(/\s+/g, " ").trim();
+}
+
+/** File extensions worth scanning for text rules. */
+const TEXT_EXT = new Set([".md", ".json", ".mjs", ".js", ".txt", ".yaml", ".yml", ".sh", ""]);
+
+/**
+ * Check every pack. Returns `{ok, checked, violations[]}` — never throws for a
+ * violation; a missing vendor tree IS a violation (the tarball would ship a
+ * global-setup step with nothing to install).
+ *
+ * @param {object} [o] @param {string} [o.repoRoot] @param {Array} [o.packs]
+ */
+export function checkSkillPacks(o = {}) {
+  const repoRoot = o.repoRoot || REPO_ROOT;
+  const packs = o.packs || PACKS;
+  const violations = [];
+  let checked = 0;
+  let harmoniser = null;
+  // Whitespace-flattened: the harmoniser is hard-wrapped markdown, so a phrase
+  // that reads as one sentence is two lines on disk. Matching the flattened
+  // text lets an acknowledgement quote the sentence, not a fragment that
+  // happens to fall between two wraps.
+  try { harmoniser = flatten(readFileSync(path.join(repoRoot, HARMONISER_REL), "utf8")); } catch { harmoniser = null; }
+  for (const pack of packs) {
+    const acknowledged = new Set((pack.acknowledged || []).map((a) => a && a.token));
+    const dir = path.join(repoRoot, VENDOR_REL, pack.id);
+    const add = (file, reason) => violations.push({ pack: pack.id, file, reason });
+    if (!existsSync(dir)) { add(`${VENDOR_REL}/${pack.id}`, "vendored pack directory is missing (run scripts/vendor/sync-skill-packs.mjs)"); continue; }
+    const manifestPath = path.join(dir, "UPSTREAM.json");
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    } catch (err) {
+      add("UPSTREAM.json", `unreadable or not JSON: ${err && err.message}`);
+      continue;
+    }
+    if (manifest.repo !== pack.repo) add("UPSTREAM.json", `repo ${manifest.repo} does not match the pinned ${pack.repo}`);
+    if (manifest.sha !== pack.sha) add("UPSTREAM.json", `sha ${manifest.sha} does not match the pinned ${pack.sha}`);
+    if (manifest.license !== pack.license) add("UPSTREAM.json", `license ${manifest.license} does not match the pinned ${pack.license}`);
+    if (!Array.isArray(manifest.files) || manifest.files.length === 0) { add("UPSTREAM.json", "files[] is empty — the manifest records nothing"); continue; }
+
+    // Assertion 2: the manifest as a whole is pinned in skill-packs.mjs, so a
+    // manifest rewritten to bless a file the *patterns* would admit still fails.
+    const digest = manifestDigest(manifest.files);
+    if (!pack.contentSha256) {
+      add("UPSTREAM.json", `pack declares no contentSha256 — pin ${digest} in scripts/vendor/skill-packs.mjs`);
+    } else if (digest !== pack.contentSha256) {
+      add("UPSTREAM.json", `manifest digest ${digest} does not match the pinned contentSha256 ${pack.contentSha256} — the vendored file list changed`);
+    }
+
+    const onDisk = listFiles(dir).filter((f) => f !== "UPSTREAM.json");
+    const listed = new Set();
+    for (const entry of manifest.files) {
+      const rel = posix(entry && entry.path);
+      if (!rel) { add("UPSTREAM.json", "files[] entry with no path"); continue; }
+      listed.add(rel);
+      const abs = path.join(dir, rel);
+      if (!existsSync(abs)) { add(rel, "listed in UPSTREAM.json but missing on disk"); continue; }
+      checked += 1;
+      const actual = createHash("sha256").update(readFileSync(abs)).digest("hex");
+      if (actual !== entry.sha256) add(rel, `sha256 mismatch: expected ${entry.sha256}, found ${actual}`);
+      if (!isAllowedDest(pack, rel)) add(rel, "outside the pack's allow-list in scripts/vendor/skill-packs.mjs");
+    }
+    for (const rel of onDisk) {
+      if (!listed.has(rel)) add(rel, "present in the vendored tree but not listed in UPSTREAM.json");
+      if (!isAllowedDest(pack, rel)) add(rel, "outside the pack's allow-list in scripts/vendor/skill-packs.mjs");
+    }
+
+    for (const rel of onDisk) {
+      const abs = path.join(dir, rel);
+      let st;
+      try { st = statSync(abs); } catch { continue; }
+      if ((st.mode & 0o111) !== 0 && !isExecAllowed(pack, rel)) add(rel, "carries an executable bit (vendored skill content is data, never a program)");
+      const ext = path.extname(rel).toLowerCase();
+      if (!TEXT_EXT.has(ext)) continue;
+      let body;
+      try { body = readFileSync(abs, "utf8"); } catch { continue; }
+      const hook = hookManifestReason(rel, body);
+      if (hook) add(rel, hook);
+      for (const t of findSupplyChainTokens(body, rel)) {
+        if (acknowledged.has(t.token)) continue;
+        add(rel, `unreviewed supply-chain instruction — it ${t.label}: "${t.sample}". Token: ${t.token}. Either the pack should not carry it, or add {token, why, covered} to this pack's acknowledged[] in scripts/vendor/skill-packs.mjs and say what to do instead in ${HARMONISER_REL}.`);
+      }
+    }
+
+    // Assertion 5b: an acknowledgement is only a review if the harmoniser tells
+    // a reader what to do instead. An `acknowledged` entry whose `covered`
+    // literal is absent from cohort-design.md is a note to nobody.
+    for (const a of pack.acknowledged || []) {
+      if (!a || !a.covered) { add("skill-packs.mjs", `acknowledged entry ${a && a.token} has no covered literal`); continue; }
+      if (harmoniser === null) continue; // reported once, below
+      if (!harmoniser.includes(flatten(a.covered))) {
+        add("cohort-design.md", `acknowledges ${a.token} but the harmoniser skill never says "${a.covered}" — a capability nobody was told to avoid is not reviewed`);
+      }
+    }
+  }
+  if (harmoniser === null && packs.some((p) => (p.acknowledged || []).length > 0)) {
+    violations.push({ pack: "-", file: "cohort-design.md", reason: "the harmoniser skill is missing or unreadable, so no acknowledgement can be checked against it" });
+  }
+  return { ok: violations.length === 0, checked, violations };
+}
+
+/** @param {string} [repoRoot] @returns {Promise<number>} */
+export async function run(repoRoot = REPO_ROOT) {
+  let result;
+  try {
+    result = checkSkillPacks({ repoRoot });
+  } catch (err) {
+    console.error(`check-skill-packs: ERROR — ${err && err.message ? err.message : err}`);
+    return 2;
+  }
+  if (result.ok) {
+    console.log(`check-skill-packs: OK (${PACKS.length} pack(s), ${result.checked} vendored file(s) verified against UPSTREAM.json)`);
+    return 0;
+  }
+  console.error("check-skill-packs: FAIL — vendored skill packs do not match their pinned manifests:");
+  for (const v of result.violations) console.error(`  ${v.pack}/${v.file} :: ${v.reason}`);
+  console.error("  Fix: re-run `node scripts/vendor/sync-skill-packs.mjs <pack>` and review the diff — never hand-edit a vendored tree.");
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().then((c) => process.exit(c)).catch((e) => { console.error("check-skill-packs: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}
+
+export default {
+  run, checkSkillPacks, findForeignFetches, findSupplyChainTokens, hookManifestReason,
+  listFiles, VENDOR_REL, HARMONISER_REL, SUPPLY_CHAIN_RULES,
+};