@blamejs/exceptd-skills 0.9.1

package/scripts/predeploy.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * scripts/predeploy.js
+ *
+ * Local mirror of the CI pre-deployment gate sequence. Runs every gate
+ * the `.github/workflows/ci.yml` workflow runs, in order. Each gate is
+ * isolated — a failure does not short-circuit the rest, so a single run
+ * surfaces all problems instead of just the first one (matches the CI
+ * shape where each job runs independently).
+ *
+ * Run before pushing to main or opening a PR:
+ *   npm run predeploy
+ *
+ * Exit code:
+ *   0  — all gates passed
+ *   1  — one or more gates failed (per-gate output already printed)
+ *   2  — runner-level error (missing script, fork failure, etc.)
+ *
+ * Single-source-of-truth: the GATES list below mirrors the job sequence
+ * in .github/workflows/ci.yml. Test coverage in tests/predeploy.test.js
+ * asserts the two stay in sync.
+ */
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const ROOT = path.join(__dirname, "..");
+
+// Ordered list of CI gates. Each entry: { name, command, args, ciJobName }.
+// ciJobName matches the `name:` field of the corresponding job in
+// .github/workflows/ci.yml (or scorecard.yml). Used by the workflow-sync
+// test to assert the two never drift.
+const GATES = [
+  {
+    name: "Verify skill signatures (Ed25519)",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "verify.js")],
+    ciJobName: "Verify skill signatures (Ed25519)",
+    requiresKeys: true,
+  },
+  {
+    name: "Run tests (node:test)",
+    command: process.execPath,
+    // Glob form rather than a directory arg: Node 25.x on Windows
+    // resolves a bare directory path through the module loader before
+    // the test runner sees it, which fails for a working dir that
+    // sits inside a path containing parentheses (e.g. Dropbox).
+    //
+    // --test-concurrency=1 forces sequential file execution. Several
+    // test files (build-incremental, indexes-v070, refresh-*) touch
+    // shared filesystem state under data/_indexes/ + refresh-report.json
+    // + skill bodies; running in parallel produces flaky races. Sequential
+    // is ~1.5s slower locally but eliminates the false negative we hit
+    // on the Linux CI runner in the v0.9.0 release attempt.
+    args: ["--test", "--test-concurrency=1", "tests/*.test.js"],
+    ciJobName: "Tests",
+  },
+  {
+    name: "Validate CVE catalog schema + zero-day learning coverage",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "validate-cve-catalog.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Validate offline CVE catalog state",
+    command: process.execPath,
+    args: [
+      path.join(ROOT, "orchestrator", "index.js"),
+      "validate-cves",
+      "--offline",
+      "--no-fail",
+    ],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Validate offline RFC catalog state",
+    command: process.execPath,
+    args: [
+      path.join(ROOT, "orchestrator", "index.js"),
+      "validate-rfcs",
+      "--offline",
+      "--no-fail",
+    ],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Manifest snapshot gate (breaking-change detector)",
+    command: process.execPath,
+    args: [path.join(ROOT, "scripts", "check-manifest-snapshot.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Lint skill files",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "lint-skills.js")],
+    ciJobName: "Lint skill files",
+  },
+  {
+    // Informational only — surfaces the forward_watch horizon across all
+    // skills as a sanity signal. Emits the count but never fails the run;
+    // a parse problem is reported, not blocking.
+    name: "Forward-watch aggregator (informational)",
+    command: process.execPath,
+    args: [
+      path.join(ROOT, "orchestrator", "index.js"),
+      "watchlist",
+    ],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+    informational: true,
+  },
+  {
+    name: "Validate catalog _meta (tlp + source_confidence + freshness_policy)",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "validate-catalog-meta.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "SBOM currency check (sbom.cdx.json vs. live surface)",
+    command: process.execPath,
+    args: ["-e", sbomCurrencyChecker()],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Pre-computed indexes freshness (data/_indexes/ vs. live sources)",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "validate-indexes.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Vendor tree integrity (vendor/blamejs/ vs. _PROVENANCE.json)",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "validate-vendor.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+  {
+    name: "Publish tarball shape (npm pack --dry-run + file allowlist)",
+    command: process.execPath,
+    args: [path.join(ROOT, "lib", "validate-package.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
+];
+
+/* Inline checker, run as `node -e`, so the predeploy gate stays one
+ * file and the SBOM regen logic stays in scripts/refresh-sbom.js
+ * (single source of truth). Compares the persisted sbom.cdx.json
+ * against the live skill_count + catalog_count derived from
+ * manifest.json + data/. Exits nonzero on drift, with a hint to run
+ * `npm run refresh-sbom`. */
+function sbomCurrencyChecker() {
+  return [
+    "const fs=require('fs');const path=require('path');",
+    "const root=" + JSON.stringify(ROOT) + ";",
+    "const sbomPath=path.join(root,'sbom.cdx.json');",
+    "if(!fs.existsSync(sbomPath)){console.error('sbom.cdx.json not found — run `npm run refresh-sbom`.');process.exit(1);}",
+    "const sbom=JSON.parse(fs.readFileSync(sbomPath,'utf8'));",
+    "const manifest=JSON.parse(fs.readFileSync(path.join(root,'manifest.json'),'utf8'));",
+    "const dataDir=path.join(root,'data');",
+    "const liveCatalogs=fs.readdirSync(dataDir).filter(f=>f.endsWith('.json')).length;",
+    "const liveSkills=Array.isArray(manifest.skills)?manifest.skills.length:0;",
+    "const props=Object.fromEntries((sbom.metadata&&sbom.metadata.properties||[]).map(p=>[p.name,p.value]));",
+    "const sbomCatalogs=Number(props['exceptd:catalog:count']);",
+    "const sbomSkills=Number(props['exceptd:skill:count']);",
+    "let drift=false;",
+    "if(sbomCatalogs!==liveCatalogs){console.error(`SBOM catalog count ${sbomCatalogs} != live ${liveCatalogs}`);drift=true;}",
+    "if(sbomSkills!==liveSkills){console.error(`SBOM skill count ${sbomSkills} != live ${liveSkills}`);drift=true;}",
+    "if(sbom.bomFormat!=='CycloneDX'||sbom.specVersion!=='1.6'){console.error('SBOM is not CycloneDX 1.6');drift=true;}",
+    "if(drift){console.error('Run `npm run refresh-sbom` to regenerate sbom.cdx.json.');process.exit(1);}",
+    "console.log(`SBOM current — ${sbomSkills} skills, ${sbomCatalogs} catalogs.`);",
+  ].join("");
+}
+
+function runGate(gate) {
+  if (gate.requiresKeys) {
+    const pubKey = path.join(ROOT, "keys", "public.pem");
+    if (!fs.existsSync(pubKey)) {
+      return {
+        status: "skipped",
+        reason:
+          "keys/public.pem missing — run `npm run bootstrap` to generate keys + sign skills.",
+      };
+    }
+  }
+  try {
+    execFileSync(gate.command, gate.args, { stdio: "inherit", cwd: ROOT });
+    return { status: "passed" };
+  } catch (e) {
+    if (gate.informational) {
+      return {
+        status: "informational",
+        exitCode: e.status ?? null,
+        message: e.message,
+      };
+    }
+    return {
+      status: "failed",
+      exitCode: e.status ?? null,
+      message: e.message,
+    };
+  }
+}
+
+function main() {
+  const results = [];
+  for (const gate of GATES) {
+    process.stdout.write(`\n=== ${gate.name} ===\n`);
+    const outcome = runGate(gate);
+    results.push({ gate, outcome });
+    if (outcome.status === "skipped") {
+      process.stdout.write(`  ⊘ skipped — ${outcome.reason}\n`);
+    } else if (outcome.status === "passed") {
+      process.stdout.write(`  ✓ passed\n`);
+    } else if (outcome.status === "informational") {
+      process.stdout.write(
+        `  ℹ informational (exit ${outcome.exitCode ?? "?"}) — not failing the run\n`
+      );
+    } else {
+      process.stdout.write(
+        `  ✗ failed (exit ${outcome.exitCode ?? "?"}): ${outcome.message}\n`
+      );
+    }
+  }
+
+  // Summary table.
+  process.stdout.write("\n=== Pre-deploy summary ===\n");
+  const widest = results.reduce(
+    (n, r) => Math.max(n, r.gate.name.length),
+    0
+  );
+  for (const { gate, outcome } of results) {
+    const icon =
+      outcome.status === "passed"
+        ? "✓"
+        : outcome.status === "skipped"
+        ? "⊘"
+        : outcome.status === "informational"
+        ? "ℹ"
+        : "✗";
+    process.stdout.write(
+      `  ${icon} ${gate.name.padEnd(widest)}  ${outcome.status}\n`
+    );
+  }
+
+  const failures = results.filter((r) => r.outcome.status === "failed");
+  const skipped = results.filter((r) => r.outcome.status === "skipped");
+  const info = results.filter((r) => r.outcome.status === "informational");
+  process.stdout.write(
+    `\n${results.length - failures.length - skipped.length - info.length}/${results.length} gates passed` +
+      (skipped.length ? ` (${skipped.length} skipped)` : "") +
+      (info.length ? ` (${info.length} informational)` : "") +
+      (failures.length ? `, ${failures.length} failed` : "") +
+      ".\n"
+  );
+
+  process.exit(failures.length > 0 ? 1 : 0);
+}
+
+module.exports = { GATES };
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (e) {
+    console.error("[predeploy] runner error: " + ((e && e.stack) || e));
+    process.exit(2);
+  }
+}

package/scripts/refresh-manifest-snapshot.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * scripts/refresh-manifest-snapshot.js
+ *
+ * Captures the current public skill surface from manifest.json and
+ * writes it to manifest-snapshot.json. Run this AFTER an intentional
+ * surface change (added skill, renamed trigger, refreshed framework
+ * refs) and commit the new snapshot alongside the change.
+ *
+ * Do NOT run this to "fix" a failing check-manifest-snapshot.js gate
+ * blindly — read the breaking-change list first. A breaking change is
+ * a surface narrowing every downstream consumer needs to know about.
+ *
+ * Usage:
+ *   node scripts/refresh-manifest-snapshot.js
+ *   git add manifest-snapshot.json
+ *   git commit -m "refresh manifest snapshot: <what changed>"
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const MANIFEST_PATH = path.join(ROOT, "manifest.json");
+const SNAPSHOT_PATH = path.join(ROOT, "manifest-snapshot.json");
+
+function captureSurface(manifest) {
+  const skills = (manifest.skills || []).map(s => ({
+    name: s.name,
+    version: s.version || null,
+    triggers: [...(s.triggers || [])].sort(),
+    data_deps: [...(s.data_deps || [])].sort(),
+    atlas_refs: [...(s.atlas_refs || [])].sort(),
+    attack_refs: [...(s.attack_refs || [])].sort(),
+    framework_gaps: [...(s.framework_gaps || [])].sort(),
+    rfc_refs: [...(s.rfc_refs || [])].sort(),
+    cwe_refs: [...(s.cwe_refs || [])].sort(),
+    d3fend_refs: [...(s.d3fend_refs || [])].sort(),
+    dlp_refs: [...(s.dlp_refs || [])].sort(),
+  })).sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    _comment: "Auto-generated by scripts/refresh-manifest-snapshot.js — do not hand-edit. Public skill surface used by check-manifest-snapshot.js to detect breaking removals.",
+    _generated_at: new Date().toISOString(),
+    atlas_version: manifest.atlas_version || null,
+    skill_count: skills.length,
+    skills,
+  };
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
+const snapshot = captureSurface(manifest);
+
+fs.writeFileSync(SNAPSHOT_PATH, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+
+console.log(`[refresh-manifest-snapshot] wrote ${snapshot.skill_count} skills to manifest-snapshot.json`);
+console.log("[refresh-manifest-snapshot] commit this file alongside the surface change.");

package/scripts/refresh-sbom.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/*
+ * scripts/refresh-sbom.js — regenerate sbom.cdx.json.
+ *
+ * The exceptd repository is zero-runtime-dependency by design (see
+ * package.json `dependencies: {}`). The SBOM therefore documents the
+ * project as an application component with an empty `components` array
+ * and pulls live surface counts from manifest.json + data/*.json so the
+ * artifact never silently drifts when the surface changes.
+ *
+ * Generated fields:
+ *   - bomFormat / specVersion        CycloneDX 1.6
+ *   - serialNumber                   urn:uuid v4 derived from a stable
+ *                                    hash of (project name + version +
+ *                                    timestamp) so reruns produce a new
+ *                                    UUID per refresh.
+ *   - metadata.timestamp             ISO 8601 of generation
+ *   - metadata.tools                 hand-written generator
+ *   - metadata.component             application entry for exceptd-skills
+ *   - metadata.properties            catalog count, skill count, dataflow
+ *                                    inputs, and the per-skill Ed25519
+ *                                    integrity claim (lib/sign.js)
+ *   - components                     [] — zero npm runtime deps
+ *   - dependencies                   [] — nothing to depend on
+ *
+ * Run:   node scripts/refresh-sbom.js
+ *        npm run refresh-sbom
+ *
+ * No external dependencies. Node 24 stdlib only.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const process = require('node:process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PACKAGE_PATH = path.join(REPO_ROOT, 'package.json');
+const MANIFEST_PATH = path.join(REPO_ROOT, 'manifest.json');
+const DATA_DIR = path.join(REPO_ROOT, 'data');
+const SBOM_PATH = path.join(REPO_ROOT, 'sbom.cdx.json');
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function countDataCatalogs(dir) {
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .sort();
+}
+
+/* RFC 4122 v4 UUID derived deterministically from a seed string so a
+ * given (project, version, timestamp) triple maps to a stable UUID
+ * across observers. Uses crypto.randomUUID() fallback if no seed. */
+function uuidV4FromSeed(seed) {
+  const hash = crypto.createHash('sha256').update(seed).digest();
+  const b = Buffer.from(hash.subarray(0, 16));
+  b[6] = (b[6] & 0x0f) | 0x40; // version 4
+  b[8] = (b[8] & 0x3f) | 0x80; // RFC 4122 variant
+  const hex = b.toString('hex');
+  return (
+    hex.slice(0, 8) +
+    '-' +
+    hex.slice(8, 12) +
+    '-' +
+    hex.slice(12, 16) +
+    '-' +
+    hex.slice(16, 20) +
+    '-' +
+    hex.slice(20, 32)
+  );
+}
+
+function loadVendorProvenance() {
+  const p = path.join(REPO_ROOT, 'vendor', 'blamejs', '_PROVENANCE.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    return readJson(p);
+  } catch {
+    return null;
+  }
+}
+
+function vendorComponents(prov) {
+  if (!prov || !prov.files) return [];
+  const out = [];
+  for (const [name, info] of Object.entries(prov.files)) {
+    out.push({
+      'bom-ref': `vendor:blamejs:${name}`,
+      type: 'library',
+      name: `blamejs/${name}`,
+      version: prov.pinned_commit ? prov.pinned_commit.slice(0, 12) : 'unknown',
+      description: `Vendored from blamejs/lib/${name} (flattened + stripped). See vendor/blamejs/README.md.`,
+      licenses: [{ license: { id: prov.license || 'Apache-2.0' } }],
+      hashes: [{ alg: 'SHA-256', content: info.vendored_sha256 }],
+      externalReferences: [
+        { type: 'vcs', url: prov.source_repo || 'https://github.com/blamejs/blamejs' },
+        { type: 'distribution', url: `${prov.source_repo || 'https://github.com/blamejs/blamejs'}/blob/${prov.pinned_commit}/${info.upstream_path}` },
+      ],
+      properties: [
+        { name: 'exceptd:vendor:upstream_sha256_at_pin', value: info.upstream_sha256_at_pin || '' },
+        { name: 'exceptd:vendor:strip_summary', value: (info.stripped || []).join('; ') },
+      ],
+    });
+  }
+  return out;
+}
+
+function buildSbom() {
+  const pkg = readJson(PACKAGE_PATH);
+  const manifest = readJson(MANIFEST_PATH);
+  const catalogs = countDataCatalogs(DATA_DIR);
+  const timestamp = new Date().toISOString();
+  const skillCount = Array.isArray(manifest.skills) ? manifest.skills.length : 0;
+  const catalogCount = catalogs.length;
+  const vendorProv = loadVendorProvenance();
+  const vendoredComponents = vendorComponents(vendorProv);
+
+  const serialNumber =
+    'urn:uuid:' +
+    uuidV4FromSeed(`${pkg.name}@${pkg.version}@${timestamp}`);
+
+  const dataflowInput = catalogs
+    .map((c) => `data/${c}`)
+    .join(',');
+
+  const sbom = {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.6',
+    serialNumber: serialNumber,
+    version: 1,
+    metadata: {
+      timestamp: timestamp,
+      tools: [
+        {
+          name: 'hand-written',
+          version: '0.1.0',
+          description:
+            'SBOM generated from package.json + manual review (scripts/refresh-sbom.js).',
+        },
+      ],
+      component: {
+        // Switch from project: scheme to pkg:npm scheme post-v0.9.0 — the
+        // package is now published on npm with provenance attestation, so
+        // the CycloneDX bom-ref should reflect the canonical PURL.
+        'bom-ref': `pkg:npm/${pkg.name}@${pkg.version}`,
+        type: 'application',
+        name: pkg.name,
+        version: pkg.version,
+        description: pkg.description,
+        licenses: [{ license: { id: 'Apache-2.0' } }],
+        purl: `pkg:npm/${pkg.name.replace('@', '%40')}@${pkg.version}`,
+        externalReferences: [
+          { type: 'distribution', url: `https://www.npmjs.com/package/${pkg.name}/v/${pkg.version}` },
+          { type: 'vcs', url: (pkg.repository && pkg.repository.url) || 'https://github.com/blamejs/exceptd-skills' },
+        ],
+      },
+      properties: [
+        {
+          name: 'cyclonedx:dataflow:input',
+          value: dataflowInput,
+        },
+        {
+          name: 'exceptd:catalog:count',
+          value: String(catalogCount),
+        },
+        {
+          name: 'exceptd:skill:count',
+          value: String(skillCount),
+        },
+        {
+          name: 'exceptd:integrity:method',
+          value: 'Ed25519 per-skill (lib/sign.js)',
+        },
+        {
+          name: 'exceptd:runtime:dependency:count',
+          value: String(Object.keys(pkg.dependencies || {}).length),
+        },
+        {
+          name: 'exceptd:devDependency:count',
+          value: String(Object.keys(pkg.devDependencies || {}).length),
+        },
+        {
+          name: 'exceptd:vendor:count',
+          value: String(vendoredComponents.length),
+        },
+        {
+          name: 'exceptd:vendor:pin',
+          value: vendorProv?.pinned_commit
+            ? `${vendorProv.source_repo}@${vendorProv.pinned_commit}`
+            : 'none',
+        },
+      ],
+    },
+    components: vendoredComponents,
+    dependencies: [],
+  };
+
+  return sbom;
+}
+
+function main() {
+  const sbom = buildSbom();
+  const json = JSON.stringify(sbom, null, 2) + '\n';
+  fs.writeFileSync(SBOM_PATH, json, 'utf8');
+  const lines = json.split(/\r?\n/).length;
+  process.stdout.write(
+    `wrote sbom.cdx.json — CycloneDX 1.6, ${lines} lines, ` +
+      `${sbom.metadata.properties.length} metadata.properties, ` +
+      `${sbom.components.length} components, serial ${sbom.serialNumber}\n`,
+  );
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { buildSbom };