@opengsd/gsd-core 1.7.0-rc.5 → 1.7.0

package/scripts/gen-golden-install-parity-zcode.cjs

@@ -3,50 +3,29 @@
 /**
  * Standalone golden-fixture generator for tests/golden-install-parity.
  *
- * This is a BUILD-TIME generation script — NOT a test run. It replicates the
- * buildParityManifest logic from tests/golden-install-parity.test.cjs and
- * captures the zcode fixture so the parity test (which the gsd-test gate runs)
- * has a committed artifact to compare against. The authoritative test gate
- * remains `gsd-test run`, never a local `node --test`.
+ * This is a BUILD-TIME generation script — NOT a test run. It imports the
+ * canonical buildParityManifest builder from tests/helpers/install-shared.cjs
+ * (issue #2266 — single source of truth shared with
+ * tests/golden-install-parity.test.cjs) and captures the zcode fixture so the
+ * parity test (which the gsd-test gate runs) has a committed artifact to
+ * compare against. The authoritative test gate remains `gsd-test run`, never
+ * a local `node --test`.
  *
  * Usage: node scripts/gen-golden-install-parity-zcode.cjs
  */
 const fs = require('node:fs');
 const path = require('node:path');
-const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
 
 const ROOT = path.resolve(__dirname, '..');
-const { walk, runMinimalInstall, RUNTIME_META } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
-const PKG_VERSION = require(path.join(ROOT, 'package.json')).version;
+// buildParityManifest (and its exclusion constants) is the canonical single
+// source of truth in tests/helpers/install-shared.cjs (issue #2266) — the
+// generator no longer keeps its own inline copy, which had drifted from the
+// test harness's copy (missing the realpath/`<HOME>` normalization) and
+// mis-generated the claude-local fixture (#2100).
+const { runMinimalInstall, RUNTIME_META, buildParityManifest, BUILD_SCRIPT } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
 const FIXTURE_DIR = path.join(ROOT, 'tests', 'fixtures', 'golden-install-parity');
 
-const VOLATILE_FILES = new Set([
-  'gsd-file-manifest.json',
-  'gsd-install-state.json',
-  '.gsd-source',
-  'gsd-core/CHANGELOG.md',
-]);
-const HOOK_CONFIG_FILES = new Set(['settings.json', 'hooks.json']);
-const EXCLUDED_PREFIXES = ['gsd-core/bin/lib/'];
-
-function buildParityManifest(configDir, root) {
-  const allFiles = walk(configDir);
-  const unsorted = {};
-  for (const full of allFiles) {
-    const rel = path.relative(configDir, full).split(path.sep).join('/');
-    if (VOLATILE_FILES.has(rel)) continue;
-    if (HOOK_CONFIG_FILES.has(path.basename(rel))) continue;
-    if (EXCLUDED_PREFIXES.some((p) => rel.startsWith(p))) continue;
-    const content = fs.readFileSync(full);
-    const normalized = content.toString('utf8').split(root).join('<HOME>').split(PKG_VERSION).join('<VERSION>');
-    const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
-    unsorted[rel] = hash;
-  }
-  const sorted = {};
-  for (const key of Object.keys(unsorted).sort()) sorted[key] = unsorted[key];
-  return sorted;
-}
-
 function cleanup(root) {
   try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
 }
@@ -59,6 +38,13 @@ function cleanup(root) {
 // With no args, regenerates ALL runtimes. With args, only the named runtimes.
 const targets = process.argv.slice(2).length > 0 ? process.argv.slice(2) : Object.keys(RUNTIME_META);
 fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+
+// Build hooks/dist before capturing so fixtures are complete even in a clean
+// checkout (hooks/dist is gitignored + built; DEFECT.HOOKS-DIST-SCOPED-CI). The
+// test harness's before() hook does the same; without it a fresh checkout omits
+// every hooks/* path and this generator silently writes short fixtures.
+execFileSync(process.execPath, [BUILD_SCRIPT], { stdio: 'pipe' });
+
 for (const runtime of targets) {
   if (!Object.prototype.hasOwnProperty.call(RUNTIME_META, runtime)) {
     process.stderr.write(`[gen] unknown runtime '${runtime}' (not in RUNTIME_META) — skipping\n`);
@@ -75,3 +61,17 @@ for (const runtime of targets) {
   fs.writeFileSync(fixturePath, JSON.stringify(actual, null, 2) + '\n', 'utf8');
   process.stdout.write(`[gen] ${runtime}: wrote ${Object.keys(actual).length} file hashes -> ${fixturePath}\n`);
 }
+
+// Also regenerate the claude LOCAL legacy-layout fixture (claude-local.json).
+// This layout is distinct from the global install (commands/gsd-*.md +
+// agents/gsd-*.md) and has its own parity assertion in the test harness.
+const { configDir: localConfigDir, root: localRoot } = runMinimalInstall({ runtime: 'claude', scope: 'local' });
+let localActual;
+try {
+  localActual = buildParityManifest(localConfigDir, localRoot);
+} finally {
+  cleanup(localRoot);
+}
+const localFixturePath = path.join(FIXTURE_DIR, 'claude-local.json');
+fs.writeFileSync(localFixturePath, JSON.stringify(localActual, null, 2) + '\n', 'utf8');
+process.stdout.write(`[gen] claude-local: wrote ${Object.keys(localActual).length} file hashes -> ${localFixturePath}\n`);

package/scripts/gen-install-tree-fixtures.cjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Standalone golden-fixture generator for tests/golden-install-tree (#2267 Phase 2).
+ *
+ * This is a BUILD-TIME generation script — NOT a test run. It imports the
+ * canonical buildInstallTree builder from tests/helpers/install-shared.cjs,
+ * which in turn reuses buildParityManifest's exact exclusion set (issue
+ * #2266) so the file-set fixtures here and the golden-install-parity content
+ * fixtures never diverge on which files they cover. The authoritative test
+ * gate remains `gsd-test run`, never a local `node --test`.
+ *
+ * Usage: node scripts/gen-install-tree-fixtures.cjs [runtime ...]
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+// buildInstallTree (and the exclusion constants it reuses from
+// buildParityManifest) is the canonical single source of truth in
+// tests/helpers/install-shared.cjs (issue #2266/#2267) — this generator does
+// not keep its own inline copy of the walk/exclusion logic.
+const { runMinimalInstall, RUNTIME_META, buildInstallTree, BUILD_SCRIPT } = require(path.join(ROOT, 'tests', 'helpers', 'install-shared.cjs'));
+const FIXTURE_DIR = path.join(ROOT, 'tests', 'fixtures', 'install-tree');
+
+function cleanup(root) {
+  try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+// Regenerate the fixture for every runtime in RUNTIME_META. Needed when a
+// SHARED gsd-core payload file (e.g. model-catalog.json, capability-registry)
+// changes content — its path appears in every runtime's manifest, so all
+// fixtures must be recaptured together. Usage:
+//   node scripts/gen-install-tree-fixtures.cjs [runtime ...]
+// With no args, regenerates ALL runtimes. With args, only the named runtimes.
+const targets = process.argv.slice(2).length > 0 ? process.argv.slice(2) : Object.keys(RUNTIME_META);
+fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+
+// Build hooks/dist before capturing so fixtures are complete even in a clean
+// checkout (hooks/dist is gitignored + built; DEFECT.HOOKS-DIST-SCOPED-CI). The
+// test harness's before() hook does the same; without it a fresh checkout omits
+// every hooks/* path and this generator silently writes short fixtures.
+execFileSync(process.execPath, [BUILD_SCRIPT], { stdio: 'pipe' });
+
+for (const runtime of targets) {
+  if (!Object.prototype.hasOwnProperty.call(RUNTIME_META, runtime)) {
+    process.stderr.write(`[gen] unknown runtime '${runtime}' (not in RUNTIME_META) — skipping\n`);
+    continue;
+  }
+  const { configDir, root } = runMinimalInstall({ runtime, scope: 'global' });
+  let actual;
+  try {
+    actual = buildInstallTree(configDir, root);
+  } finally {
+    cleanup(root);
+  }
+  const fixturePath = path.join(FIXTURE_DIR, `${runtime}.json`);
+  fs.writeFileSync(fixturePath, JSON.stringify(actual, null, 2) + '\n', 'utf8');
+  process.stdout.write(`[gen] ${runtime}: wrote ${actual.length} paths -> ${fixturePath}\n`);
+}
+
+// Also regenerate the claude LOCAL legacy-layout fixture (claude-local.json).
+// This layout is distinct from the global install (commands/gsd-*.md +
+// agents/gsd-*.md) and has its own snapshot assertion in the test harness.
+const { configDir: localConfigDir, root: localRoot } = runMinimalInstall({ runtime: 'claude', scope: 'local' });
+let localActual;
+try {
+  localActual = buildInstallTree(localConfigDir, localRoot);
+} finally {
+  cleanup(localRoot);
+}
+const localFixturePath = path.join(FIXTURE_DIR, 'claude-local.json');
+fs.writeFileSync(localFixturePath, JSON.stringify(localActual, null, 2) + '\n', 'utf8');
+process.stdout.write(`[gen] claude-local: wrote ${localActual.length} paths -> ${localFixturePath}\n`);

package/scripts/gen-registry.cjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/gen-registry.cjs — generates docs/registries/capability-registry.md
+ * (and, once PR2 ships docs/registries/eos.json, docs/registries/eos-registry.md)
+ * from the corresponding source JSON, via registry-schema.cjs#renderMarkdown.
+ * Issue #2182.
+ *
+ * NOT to be confused with `scripts/gen-capability-registry.cjs`: that script
+ * generates the RUNTIME capability manifest consumed by the host at runtime
+ * (`gsd-core/bin/lib/capability-registry.cjs`, built from every
+ * `capabilities/<id>/capability.json` declaration). THIS script instead
+ * generates the human-facing DOCUMENTATION catalog pages
+ * (`docs/registries/*.md`) from the third-party discoverability registry
+ * source JSON (`docs/registries/{capabilities,eos}.json`). The two pipelines
+ * are independent — do not conflate them.
+ *
+ * Usage:
+ *   node scripts/gen-registry.cjs              # print rendered markdown(s) to stdout
+ *   node scripts/gen-registry.cjs --write      # write the *-registry.md file(s)
+ *   node scripts/gen-registry.cjs --check      # exit 1 if a committed *-registry.md is stale
+ *
+ * Root is resolved from process.cwd() (not __dirname) — mirrors
+ * scripts/validate-registry.cjs so both are drivable as subprocesses against
+ * isolated temp-fixture directories via `cwd`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { renderMarkdown } = require('./registry-schema.cjs');
+
+const SOURCES = [
+  { type: 'capability', jsonFile: 'capabilities.json', mdFile: 'capability-registry.md' },
+  { type: 'eos', jsonFile: 'eos.json', mdFile: 'eos-registry.md' },
+];
+
+/**
+ * The generator always writes LF; a Windows checkout (autocrlf) may present
+ * committed files with CRLF. Normalize before comparing so `--check` only
+ * fails on real content drift, not checkout-introduced line-ending noise.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeLineEndings(content) {
+  return content.replace(/\r/g, '');
+}
+
+function getRegistriesDir() {
+  return path.join(process.cwd(), 'docs', 'registries');
+}
+
+/**
+ * Render the markdown for a single registry type from its committed source
+ * JSON.
+ *
+ * Only `eos.json` is optional (pre-PR2, before that source JSON ships) —
+ * an absent `eos.json` returns null and callers treat that as "nothing to
+ * do". `capabilities.json` is the primary registry source: a missing
+ * `capabilities.json` is ALWAYS an error (never a silent "up to date"
+ * pass), mirroring the type distinction in `scripts/validate-registry.cjs`
+ * (`type === 'eos' && !exists → continue`).
+ *
+ * @param {'capability'|'eos'} type
+ * @returns {string|null}
+ */
+function renderFor(type) {
+  const source = SOURCES.find((s) => s.type === type);
+  if (!source) throw new Error(`gen-registry: unknown registry type "${type}"`);
+
+  const jsonPath = path.join(getRegistriesDir(), source.jsonFile);
+  if (!fs.existsSync(jsonPath)) {
+    if (type === 'eos') return null;
+    throw new ExitError(
+      1,
+      `${source.jsonFile} does not exist at ${jsonPath}. Run:\n  node scripts/gen-registry.cjs --write\n(after adding docs/registries/${source.jsonFile})`,
+    );
+  }
+
+  const entries = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  return renderMarkdown(entries, { type, sourceFile: source.jsonFile });
+}
+
+function main() {
+  const [, , flag] = process.argv;
+  const registriesDir = getRegistriesDir();
+  let anyDrift = false;
+
+  for (const { type, mdFile } of SOURCES) {
+    const rendered = renderFor(type);
+    if (rendered === null) continue; // source JSON absent (eos.json before PR2)
+
+    const mdPath = path.join(registriesDir, mdFile);
+
+    if (flag === '--check') {
+      if (!fs.existsSync(mdPath)) {
+        process.stderr.write(`${mdFile} does not exist. Run:\n  node scripts/gen-registry.cjs --write\n`);
+        anyDrift = true;
+        continue;
+      }
+      const committed = fs.readFileSync(mdPath, 'utf8');
+      if (normalizeLineEndings(committed) !== normalizeLineEndings(rendered)) {
+        process.stderr.write(`${mdFile} is stale. Run:\n  node scripts/gen-registry.cjs --write\n`);
+        anyDrift = true;
+      }
+    } else if (flag === '--write') {
+      fs.mkdirSync(registriesDir, { recursive: true });
+      fs.writeFileSync(mdPath, rendered);
+      process.stdout.write(`Wrote ${mdPath}\n`);
+    } else {
+      process.stdout.write(rendered + '\n');
+    }
+  }
+
+  if (flag === '--check') {
+    if (anyDrift) throw new ExitError(1, 'registry markdown is stale');
+    process.stdout.write('docs/registries/*.md are up to date.\n');
+  }
+
+  return 0;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { main, renderFor, SOURCES, normalizeLineEndings };

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -99,7 +99,6 @@
   "tests/mcp-tool-inheritance.test.cjs :: source-text-is-the-product",
   "tests/milestone-summary.test.cjs :: source-text-is-the-product",
   "tests/milestone.test.cjs :: source-text-is-the-product",
-  "tests/milestone.test.cjs :: structural-regression-guard",
   "tests/model-catalog-runtime-defaults.test.cjs :: source-text-is-the-product",
   "tests/next-safety-gates.test.cjs :: source-text-is-the-product",
   "tests/next-up-clear-order.test.cjs :: source-text-is-the-product",

package/scripts/lint-table-schema-drift.cjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Table-schema drift lint (ADR-2143 §3 Generative-Fix-Divergence guard, §7
+ * "prohibition with teeth", epic #2143).
+ *
+ * `TABLE_SCHEMAS` (`src/markdown-table.cts`, compiled to
+ * `gsd-core/bin/lib/markdown-table.cjs`) is the single-source registry naming
+ * every canonical GSD pipe-table's column-header shape. Each registered
+ * variant's exact `| col | col |` header string MUST appear verbatim in the
+ * ONE template/workflow file that emits that table — otherwise the writer and
+ * the registry have silently drifted apart, the exact bug class this ADR
+ * closes (#2137 — reader hard-codes a shape the writer doesn't emit; #2133 —
+ * the `quick.md` writer and its shell guard disagree on column count; #2119 —
+ * dual SECURITY.md writers with conflicting shapes).
+ *
+ * Modeled on scripts/lint-phase-id-drift.cjs / scripts/lint-package-identity-drift.cjs:
+ * a standalone node script (not a node:test), wired into `lint:ci`, exit 0 clean /
+ * exit 1 + message on drift.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Schema id -> the ONE canonical template/workflow file that must emit every
+// variant's header verbatim (ADR-2143 §3).
+const SCHEMA_SOURCE_FILES = {
+  RoadmapProgress: path.join('gsd-core', 'templates', 'roadmap.md'),
+  RequirementsTraceability: path.join('gsd-core', 'templates', 'requirements.md'),
+  QuickTasks: path.join('gsd-core', 'workflows', 'quick.md'),
+  Security: path.join('gsd-core', 'templates', 'SECURITY.md'),
+};
+
+/** Build the exact `| a | b | c |` header line for one schema variant. */
+function buildHeader(variant) {
+  return `| ${variant.columns.join(' | ')} |`;
+}
+
+/** Normalize whitespace around pipes so template formatting quirks (extra
+ * spaces added by an editor, etc.) don't produce a false drift report. */
+function normalize(line) {
+  return line.replace(/[ \t]*\|[ \t]*/g, '|').trim();
+}
+
+/**
+ * Pure: given `schemas` (a `TABLE_SCHEMAS`-shaped object) and a
+ * `readFile(relPath) -> string|null` accessor, find every variant whose exact
+ * header does not appear verbatim (pipe-whitespace normalized) in its
+ * schema's registered source file. Returns
+ * `[{ schemaId, label, header, file, reason }]`; empty when clean.
+ */
+function findTableSchemaDrift(schemas, readFile, sourceFiles = SCHEMA_SOURCE_FILES) {
+  const violations = [];
+  for (const [schemaId, variants] of Object.entries(schemas)) {
+    const relPath = sourceFiles[schemaId];
+    if (!relPath) {
+      violations.push({
+        schemaId,
+        label: null,
+        header: null,
+        file: null,
+        reason: 'no canonical source file registered for this schema id in SCHEMA_SOURCE_FILES',
+      });
+      continue;
+    }
+
+    const content = readFile(relPath);
+    if (content == null) {
+      for (const variant of variants) {
+        violations.push({
+          schemaId,
+          label: variant.label,
+          header: buildHeader(variant),
+          file: relPath,
+          reason: 'source file not found or unreadable',
+        });
+      }
+      continue;
+    }
+
+    const normalizedLines = content.split(/\r?\n/).map(normalize);
+    for (const variant of variants) {
+      const expected = normalize(buildHeader(variant));
+      if (!normalizedLines.includes(expected)) {
+        violations.push({
+          schemaId,
+          label: variant.label,
+          header: buildHeader(variant),
+          file: relPath,
+          reason: 'header not found verbatim in source file',
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Load the built seam and scan the real repo tree. Returns the same shape as
+ * `findTableSchemaDrift`. If the seam hasn't been built yet (`npm run
+ * build:lib`), reports a single actionable violation rather than throwing.
+ */
+function scanRepo(root) {
+  const seamPath = path.join(root, 'gsd-core', 'bin', 'lib', 'markdown-table.cjs');
+  let seam;
+  try {
+    seam = require(seamPath);
+  } catch (e) {
+    return [{
+      schemaId: null,
+      label: null,
+      header: null,
+      file: null,
+      reason: `cannot load the markdown-table seam at ${path.relative(root, seamPath)} — run 'npm run build:lib' first (${e.message})`,
+    }];
+  }
+
+  const readFile = (relPath) => {
+    try {
+      return fs.readFileSync(path.join(root, relPath), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+
+  return findTableSchemaDrift(seam.TABLE_SCHEMAS, readFile);
+}
+
+function main() {
+  const root = path.join(__dirname, '..');
+  const violations = scanRepo(root);
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok table-schema-drift: every TABLE_SCHEMAS variant header appears verbatim in its canonical template/workflow\n',
+    );
+    return;
+  }
+  process.stderr.write(
+    'table-schema-drift: TABLE_SCHEMAS variant(s) whose header is absent from their canonical source file (ADR-2143 §3).\n',
+  );
+  process.stderr.write(
+    'Either update the template/workflow to emit the registered header verbatim, or update\n' +
+      'TABLE_SCHEMAS in src/markdown-table.cts to match — the two must never drift.\n',
+  );
+  for (const v of violations) {
+    const id = v.label ? `${v.schemaId}.${v.label}` : (v.schemaId ?? '?');
+    const loc = v.file ? ` (${v.file})` : '';
+    const expected = v.header ? ` — expected ${JSON.stringify(v.header)}` : '';
+    process.stderr.write(`  ${id}${loc}: ${v.reason}${expected}\n`);
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = { findTableSchemaDrift, scanRepo, buildHeader, normalize, SCHEMA_SOURCE_FILES };

package/scripts/lint-test-file-count.allowlist.json

@@ -50,11 +50,12 @@
     },
     "security": {
       "files": [
+        "security-dead-exports.regression.test.cjs",
         "security-prompt-injection.security.test.cjs",
         "security-scan.security.test.cjs",
         "security.test.cjs"
       ],
-      "issue": "TBD"
+      "issue": "2198"
     },
     "state": {
       "files": [