@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/scripts/run-e2e-scenarios.js

@@ -2,30 +2,12 @@
 "use strict";
 
 /**
- * scripts/run-e2e-scenarios.js
+ * Drives the scenario harness under tests/e2e-scenarios/. A scenario directory
+ * stages a synthetic file tree plus an evidence.json and an expect.json; each
+ * one runs in its own temp copy against the real CLI.
  *
- * Drives the end-to-end scenario harness under tests/e2e-scenarios/. Each
- * scenario directory stages a synthetic file tree (real IoC patterns the
- * playbooks check for) + an evidence.json + an expect.json. The runner:
- *
- *   1. mkdtemp a working dir
- *   2. recursive-copy fixtures/ into it
- *   3. recursive-copy any evidence.json next to scenario.json into it
- *   4. cd into the working dir
- *   5. spawnSync the CLI with the scenario's verb + args
- *   6. parse stdout as JSON
- *   7. diff against expect.json (path-based assertions)
- *
- * Container parity: this script is invoked unchanged inside the Docker
- * `e2e` target (npm run test:docker:e2e). The container only adds Linux
- * file-permission realism and Node version pinning; the script itself
- * runs identically on host + container.
- *
- * Release gate: .github/workflows/release.yml runs this BEFORE
- * `npm publish` so a regression that breaks any playbook detection
- * blocks the release.
- *
- * Zero npm deps. Node 24 stdlib only.
+ * The Docker `e2e` target and release.yml run this script unchanged, so host and
+ * container behaviour must not diverge. Node stdlib only, zero npm deps.
  */
 
 const fs = require("fs");
@@ -55,11 +37,8 @@ function getJsonPath(obj, dotted) {
   return dotted.split(".").reduce((acc, key) => acc?.[key], obj);
 }
 
-// Evaluate the negative stderr guard against raw stderr text. Lives here, NOT
-// inside diffExpect, because the ban must hold regardless of whether stdout
-// parsed as JSON — a scenario whose stdout is a human banner (no JSON body,
-// only an expect_exit assertion) must still enforce a forbidden-token ban on
-// stderr. evaluateScenario calls this unconditionally.
+// Separate from diffExpect because the ban has to hold whether or not stdout
+// parsed as JSON; evaluateScenario calls it unconditionally.
 function stderrBanFailures(expect, stderr) {
   const failures = [];
   if (expect.stderr_must_not_match) {
@@ -72,10 +51,7 @@ function stderrBanFailures(expect, stderr) {
   return failures;
 }
 
-// Diff a parsed JSON body against the positive expect matchers. The negative
-// stderr guard is NOT evaluated here (see stderrBanFailures); this function
-// only inspects the JSON body so it cannot be silently skipped when stdout
-// fails to parse.
+// Positive matchers against the parsed JSON body only; the stderr ban is separate.
 function diffExpect(jsonBody, expect, ctx) {
   const failures = [];
   if (expect.json_path_equals) {
@@ -119,11 +95,8 @@ function tryParseJson(s) {
     const v = JSON.parse(s.trim());
     if (v && typeof v === "object") return v;
   } catch { /* ignore */ }
-  // Some verbs may emit trailing logs; pick the LAST complete JSON object or
-  // array on stdout. A verb envelope is always an object/array, so bare
-  // scalars (a trailing JSON-parseable "done"/42/true log line) are skipped —
-  // binding assertions against a trailing scalar would silently test the
-  // wrong value.
+  // Trailing logs are possible, so take the LAST complete object or array. A bare
+  // scalar is never a verb envelope; accepting one would bind to a log line.
   const lines = s.trim().split("\n");
   for (let i = lines.length - 1; i >= 0; i--) {
     try {
@@ -134,11 +107,8 @@ function tryParseJson(s) {
   return null;
 }
 
-// Evaluate a spawnSync result against a scenario's expectations. Pure: takes
-// the raw spawnSync result so the failure logic is unit-testable without
-// spawning a process. Surfaces spawn-level failures (timeout/launch error)
-// that res.status alone hides, and refuses to pass a scenario that binds no
-// assertion.
+// Pure over a raw spawnSync result, so the failure logic is testable without
+// spawning anything. Returns the list of failure strings; empty means pass.
 function evaluateScenario(scenario, expect, res) {
   const stdout = res.stdout || "";
   const stderr = res.stderr || "";
@@ -146,19 +116,14 @@ function evaluateScenario(scenario, expect, res) {
   const body = tryParseJson(stdout);
   const failures = [];
 
-  // spawnSync failure channels: a timeout sets res.error (ETIMEDOUT) +
-  // res.signal 'SIGTERM' with status null; a launch failure (ENOENT/EACCES)
-  // sets res.error with status null. Reading only res.status lets a killed-
-  // or-never-launched run masquerade as a plain non-zero exit or a JSON-parse
-  // failure, hiding the real cause.
+  // A timeout or launch failure sets res.error with status null, so reading only
+  // res.status lets a killed or never-launched run pass as a non-zero exit.
   if (res.error) failures.push(`spawn error: ${res.error.code || res.error.message}`);
   if (res.signal) failures.push(`killed by signal ${res.signal}${res.signal === "SIGTERM" ? " (likely the 60s timeout)" : ""}`);
 
-  // Assertion floor: every scenario must bind at least one positive check.
-  // Without an expect_exit or a json_path_* matcher, both gates below are
-  // skipped and the scenario would pass for ANY CLI behavior, including a
-  // crash. (stderr_must_not_match is a negative guard and cannot bind
-  // behavior on its own, so it does not satisfy the floor.)
+  // Every scenario must bind one positive check: with neither an expect_exit nor
+  // a json_path_* matcher, both gates below skip and the scenario passes for any
+  // behaviour at all. A negative guard like stderr_must_not_match binds nothing.
   const hasExitAssertion = typeof scenario.expect_exit === "number";
   const hasJsonAssertion = !!(expect.json_path_equals || expect.json_path_present || expect.json_path_min || expect.json_path_match);
   if (!hasExitAssertion && !hasJsonAssertion) {
@@ -173,10 +138,7 @@ function evaluateScenario(scenario, expect, res) {
   }
   if (body) failures.push(...diffExpect(body, expect, { stdout, stderr, status }));
 
-  // The forbidden-token ban on stderr runs unconditionally — it does not
-  // depend on stdout parsing as JSON. A scenario with only an expect_exit
-  // assertion (human-banner stdout) must still fail if stderr carries a banned
-  // token.
+  // Unconditional, outside every `if (body)` branch above.
   failures.push(...stderrBanFailures(expect, stderr));
   return failures;
 }
@@ -192,7 +154,6 @@ function runScenario(scenarioPath) {
     ? JSON.parse(fs.readFileSync(path.join(scenarioPath, "expect.json"), "utf8"))
     : {};
 
-  // Stage temp working dir
   const work = fs.mkdtempSync(path.join(os.tmpdir(), `e2e-${name}-`));
   try {
     const fixturesDir = path.join(scenarioPath, "fixtures");
@@ -202,7 +163,7 @@ function runScenario(scenarioPath) {
       fs.copyFileSync(evidenceSrc, path.join(work, "evidence.json"));
     }
 
-    // Resolve env. @@FIXTURE@@ in env values expands to ROOT/tests/fixtures.
+    // @@FIXTURE@@ inside an env value expands to ROOT/tests/fixtures.
     const env = { ...process.env, EXCEPTD_DEPRECATION_SHOWN: "1", EXCEPTD_UNSIGNED_WARNED: "1" };
     if (scenario.env) {
       for (const [k, v] of Object.entries(scenario.env)) {
@@ -210,18 +171,13 @@ function runScenario(scenarioPath) {
       }
     }
 
-    // Resolve args
     const args = (scenario.args || []).slice();
 
-    // Verb routing. `refresh` + `refresh-curate` are not the same as `run` —
-    // the dispatcher in bin/exceptd.js handles the translation, so we just
-    // pass the verb + args verbatim. `refresh-curate` is the internal name
-    // for `refresh --curate`; surfaced here for test directness.
+    // The verb and args pass through verbatim; bin/exceptd.js does the routing.
     const verb = scenario.verb;
     let cmd, cmdArgs;
     if (verb === "refresh-curate") {
-      // Invoke the curation helper directly. Production path is via the
-      // dispatcher in bin/exceptd.js (which dispatches refresh --curate).
+      // The curation helper direct; operators reach it as `refresh --curate`.
       cmd = process.execPath;
       cmdArgs = [path.join(ROOT, "lib", "cve-curation.js"), ...args];
     } else {
@@ -252,12 +208,9 @@ function runScenario(scenarioPath) {
   }
 }
 
-// Select scenario directories under SCENARIO_DIR, optionally narrowed by a
-// filter. The filter is matched as a plain substring (String.includes), NOT
-// compiled with new RegExp: a regex built from a CLI argument is a regex-
-// injection / ReDoS vector, and scenario names are literal NN-name strings, so
-// substring selection is behavior-equivalent for every legitimate filter
-// (e.g. --filter=library-author). Returns sorted basenames.
+// Sorted basenames. The filter is a plain substring, never `new RegExp`: a
+// pattern compiled from a CLI argument is a regex-injection and ReDoS vector,
+// and scenario names are literal NN-name strings anyway.
 function selectScenarios(filterStr, dir = SCENARIO_DIR) {
   return fs.readdirSync(dir)
     .filter(d => /^\d+-/.test(d))

package/scripts/sync-manifest-metadata.js

@@ -1,37 +1,16 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/sync-manifest-metadata.js
+ * Syncs the per-skill fields manifest.json caches from each skill's
+ * frontmatter, the authoritative source the linter and staleness gate read.
+ * Run it whenever frontmatter changes, then re-run sign-all — and, when a
+ * cross-ref array changed, refresh-reverse-refs + build-indexes.
  *
- * Several per-skill fields in manifest.json are a cache of the authoritative
- * values in each skill's frontmatter (the linter and the staleness gate read
- * frontmatter, so frontmatter is the single source of truth). Nothing kept
- * the cache in sync, so editing frontmatter left the manifest copy stale.
- *
- * Two sync disciplines, because the fields differ in kind:
- *
- *   - MIRROR (exact): `last_threat_review` (scalar) and `forward_watch`
- *     (array) are an exact copy of frontmatter. Synced by replace.
- *
- *   - COVER (union): the cross-reference arrays (`data_deps`,
- *     `framework_gaps`, `atlas_refs`, `attack_refs`, `rfc_refs`, `cwe_refs`,
- *     `d3fend_refs`) are an ENRICHED SUPERSET — the manifest may carry extra
- *     curated refs that the derived indexes (build-indexes) and the
- *     reverse-ref refresh (refresh-reverse-refs) read. The invariant is that
- *     every frontmatter-declared ref MUST appear in the manifest, or it
- *     silently vanishes from those surfaces. Synced by UNION (append the
- *     missing frontmatter refs, preserve the manifest's order + enrichment) —
- *     never by replace, which would drop curated refs.
- *
- * Run it whenever skill frontmatter changes, then re-run sign-all (and, when
- * cross-ref arrays changed, refresh-reverse-refs + build-indexes) so the
- * refreshed manifest is signed and the derived surfaces pick up the refs.
- *
- * tests/sync-manifest-metadata.test.js fails the suite if the cache ever
- * drifts again, so a missed run is caught before release rather than shipping
- * a manifest that contradicts its own skill bodies. It covers the fields named
- * above; `description` is cached in the manifest but is NOT one of them, so a
- * frontmatter description edit does not propagate and is not caught here.
+ * `last_threat_review` and `forward_watch` MIRROR frontmatter exactly and sync
+ * by replace. The cross-reference arrays are an enriched superset — the
+ * manifest carries curated refs frontmatter does not — so they sync by UNION;
+ * replacing them drops the curated refs build-indexes and refresh-reverse-refs
+ * read. `description` is cached in the manifest but is not synced here.
  *
  * Exit codes: 0 = wrote (or already in sync), 1 = a skill file was missing or
  * its frontmatter failed to parse.
@@ -44,12 +23,9 @@ const lint = require("../lib/lint-skills.js");
 const ROOT = path.resolve(__dirname, "..");
 const MANIFEST = path.join(ROOT, "manifest.json");
 
-// The frontmatter fields the manifest caches and must mirror verbatim.
 const MIRRORED_SCALAR = ["last_threat_review"];
 const MIRRORED_ARRAY = ["forward_watch"];
-// Cross-reference arrays: the manifest is an enriched superset, so sync by
-// UNION (cover) — append frontmatter refs the manifest is missing, keep the
-// manifest's own curated refs. See the header for why replace would regress.
+// Union, never replace — a replace drops the manifest's curated refs.
 const MIRRORED_COVER = ["data_deps", "framework_gaps", "atlas_refs", "attack_refs", "rfc_refs", "cwe_refs", "d3fend_refs"];
 
 function skillFrontmatter(id) {

package/scripts/sync-package-description.js

@@ -1,20 +1,12 @@
 'use strict';
 
 /**
- * scripts/sync-package-description.js
- *
- * Regenerate the count-bearing tokens embedded in package.json.description from
- * the live catalogs + manifest, so the description stays in sync when an
- * auto-refresh changes an entry count. refresh-sbom copies the description into
- * sbom.cdx.json, and check-sbom-currency validates every token against the live
- * counts — without this sync, the first refresh that changes a count would fail
- * the SBOM description-token gate on the auto-PR.
- *
- * Targeted, format-preserving: replaces only the integer in each known
- * "<N> <label>" token (skills / catalogs / jurisdictions / per-catalog entry
- * counts). Reuses check-sbom-currency's token table so the two can't drift.
- *
- * Run before refresh-sbom in the refresh apply path (and idempotent locally).
+ * Rewrites the count-bearing tokens in package.json.description from the live
+ * catalogs and manifest, replacing only the integer in each "<N> <label>" pair.
+ * refresh-sbom copies the description into sbom.cdx.json and
+ * check-sbom-currency validates every token against live counts, so this runs
+ * before refresh-sbom; it reads that gate's token table, so the two cannot
+ * drift. Idempotent.
  */
 
 const fs = require('fs');
@@ -39,9 +31,8 @@ function syncPackageDescription(root = path.join(__dirname, '..')) {
     liveJurisdictions = Object.keys(gf).filter((k) => !k.startsWith('_')).length;
   } catch { /* leave null — skip the jurisdiction token */ }
 
-  // Replace only the integer in "<N> <label>"; `labelRe` is the same (already
-  // regex-escaped) pattern check-sbom-currency matches, and $2 preserves the
-  // matched label text verbatim.
+  // `labelRe` arrives already regex-escaped from check-sbom-currency; $2
+  // preserves the matched label text verbatim.
   const sub = (n, labelRe) => {
     if (n == null) return;
     desc = desc.replace(new RegExp('(\\d+)(\\s+' + labelRe + '\\b)'), String(n) + '$2');

package/scripts/validate-vendor-online.js

@@ -1,33 +1,13 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/validate-vendor-online.js
+ * Network-touching companion to lib/validate-vendor.js: for every file in
+ * vendor/blamejs/_PROVENANCE.json, fetch the upstream blob at the pinned commit
+ * and compare its hash against the recorded `upstream_sha256_at_pin`.
  *
- * Optional, network-touching companion to lib/validate-vendor.js. For every
- * file recorded in vendor/blamejs/_PROVENANCE.json, fetches the upstream
- * blob from github.com/<source_repo>/blob/<pinned_commit>/<upstream_path>
- * (via the raw.githubusercontent.com mirror), hashes it, and compares the
- * result against the `upstream_sha256_at_pin` recorded in _PROVENANCE.json.
- *
- * This catches the class where _PROVENANCE.json was hand-edited to
- * advertise a `upstream_sha256_at_pin` that does not actually match what
- * upstream had at that commit. lib/validate-vendor.js only checks that the
- * local vendored file matches its own recorded hash — that's self-attesting.
- * This script extends the check to upstream, closing the gap.
- *
- * Not part of `npm run predeploy` by default — the predeploy gate sequence
- * must remain network-independent (offline gates only). Run manually:
- *
- *   node scripts/validate-vendor-online.js
- *   node scripts/validate-vendor-online.js --timeout 30000
- *   node scripts/validate-vendor-online.js --json
- *
- * Exit codes:
- *   0  every vendored file's upstream_sha256_at_pin matched upstream
- *   1  at least one mismatch
- *   2  runtime / network error
- *
- * Zero npm deps. Node 24 stdlib only.
+ * lib/validate-vendor.js is self-attesting — a hand-edited _PROVENANCE.json
+ * passes it. This reaches upstream, so it stays out of the offline-by-design
+ * `npm run predeploy`. Exit 0 on match, 1 on a mismatch, 2 on a runtime error.
  */
 
 const fs = require("fs");
@@ -58,18 +38,13 @@ function parseArgs(argv) {
 }
 
 function rawUrlForPin(sourceRepo, commit, upstreamPath) {
-  // Translate https://github.com/owner/repo → raw.githubusercontent.com/owner/repo
-  // sourceRepo may end in .git; strip it. Tolerate trailing slash.
+  // https://github.com/owner/repo → raw.githubusercontent.com/owner/repo.
   const m = (sourceRepo || "").match(
     /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/
   );
   if (!m) return null;
-  // Validate every file-derived component, then build the URL from the SAME
-  // validated bindings (cleanOwner/cleanRepo/cleanCommit/cleanPath) so a tampered
-  // _PROVENANCE.json cannot steer the request and no unguarded metadata value
-  // reaches the fetch: owner/repo are GitHub-name-shaped, the commit is a hex git
-  // object id, and the path is a relative, traversal-free repo path. With the host
-  // a string literal, the fetch destination is fully constrained.
+  // The URL is built from the same bindings that get validated below, so no
+  // unguarded value out of _PROVENANCE.json reaches the fetch.
   const cleanOwner = m[1];
   const cleanRepo = m[2];
   const cleanCommit = String(commit || "");
@@ -82,12 +57,9 @@ function rawUrlForPin(sourceRepo, commit, upstreamPath) {
 
 const MAX_REDIRECTS = 5;
 
-// Only GitHub-controlled hosts may be fetched. The initial URL is always a
-// raw.githubusercontent.com URL computed from the committed _PROVENANCE.json,
-// but redirects re-enter fetchBuffer with a server-supplied Location; pinning
-// the host to github.com / *.githubusercontent.com stops a redirect (or a
-// tampered provenance source_repo) from steering the fetch at an internal or
-// attacker-controlled address.
+// Redirects re-enter fetchBuffer with a server-supplied Location, so the host is
+// checked on every hop, not just the initial URL: that is what stops a redirect
+// or a tampered source_repo steering the fetch at an internal address.
 const ALLOWED_FETCH_HOST = /(?:^|\.)githubusercontent\.com$|^github\.com$/;
 
 function assertAllowedHost(url) {
@@ -103,10 +75,7 @@ function fetchBuffer(url, timeoutMs, redirectsLeft = MAX_REDIRECTS) {
   return new Promise((resolve, reject) => {
     try { assertAllowedHost(url); } catch (e) { return reject(e); }
     const req = https.get(url, (res) => {
-      // v0.12.14 (codex P2): cap redirect hops. A redirect loop (or a
-      // hostile / mis-configured upstream that keeps returning 3xx with
-      // Location pointing back to itself) used to recurse until stack
-      // overflow or hang. Now: count hops, fail clean on exhaustion.
+      // Hops are counted: a self-referential 3xx Location would recurse forever.
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
         res.resume();
         if (redirectsLeft <= 0) {