@opengsd/gsd-core 1.3.0 → 1.4.0-rc.1

package/scripts/gen-inventory-manifest.cjs

@@ -16,6 +16,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 const ROOT = path.resolve(__dirname, '..');
 const MANIFEST_PATH = path.join(ROOT, 'docs', 'INVENTORY-MANIFEST.json');
 
@@ -70,40 +72,44 @@ function buildManifest() {
   return manifest;
 }
 
-const [, , flag] = process.argv;
+function main() {
+  const [, , flag] = process.argv;
 
-if (flag === '--check') {
-  const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
-  const live = buildManifest();
-  // Strip the generated date for comparison
-  delete committed.generated;
-  delete live.generated;
-  const committedStr = JSON.stringify(committed, null, 2);
-  const liveStr = JSON.stringify(live, null, 2);
-  if (committedStr !== liveStr) {
-    process.stderr.write(
-      'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
-      '  node scripts/gen-inventory-manifest.cjs --write\n' +
-      'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
-    );
-    // Show diff-friendly output
-    for (const family of Object.keys(live.families)) {
-      const liveSet = new Set(live.families[family]);
-      const committedSet = new Set((committed.families || {})[family] || []);
-      for (const name of liveSet) {
-        if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
-      }
-      for (const name of committedSet) {
-        if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+  if (flag === '--check') {
+    const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+    const live = buildManifest();
+    // Strip the generated date for comparison
+    delete committed.generated;
+    delete live.generated;
+    const committedStr = JSON.stringify(committed, null, 2);
+    const liveStr = JSON.stringify(live, null, 2);
+    if (committedStr !== liveStr) {
+      process.stderr.write(
+        'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
+        '  node scripts/gen-inventory-manifest.cjs --write\n' +
+        'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
+      );
+      // Show diff-friendly output
+      for (const family of Object.keys(live.families)) {
+        const liveSet = new Set(live.families[family]);
+        const committedSet = new Set((committed.families || {})[family] || []);
+        for (const name of liveSet) {
+          if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
+        }
+        for (const name of committedSet) {
+          if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+        }
       }
+      throw new ExitError(1);
     }
-    process.exit(1);
+    process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
+  } else if (flag === '--write') {
+    const manifest = buildManifest();
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+    process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
   }
-  process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
-} else if (flag === '--write') {
-  const manifest = buildManifest();
-  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
-  process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
-} else {
-  process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
 }
+
+runMain(main);

package/scripts/gen-research-agents.cjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-research-agents.cjs — profile-driven drift guard for the 7 researcher agents.
+ *
+ * Usage:
+ *   node scripts/gen-research-agents.cjs           # same as --check
+ *   node scripts/gen-research-agents.cjs --check   # assert every agent matches its profile
+ *   node scripts/gen-research-agents.cjs --write   # regenerate frontmatter from profiles
+ *
+ * --check assertions per agent:
+ *   (a) frontmatter name/description/color/tools exactly match the profile
+ *   (b) every requiredInclude string is present in the body
+ *   (c) every requiredSeamCall string is present in the body
+ *   (d) every outputContract marker string is present in the body
+ *
+ * --write regenerates ONLY the opening `---\n...\n---` frontmatter block from the
+ * profile, leaving the body byte-identical. After --write, --check must pass and
+ * `git diff` must be empty (profiles were derived from current state).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { PROFILES } = require('./research-profiles.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const AGENTS_DIR = path.join(ROOT, 'agents');
+
+// ─── Frontmatter serialization ────────────────────────────────────────────────
+
+/**
+ * Build the frontmatter block for a profile.
+ *
+ * The agent files have two patterns for commented hooks:
+ *   - Agents with Write in tools (file-writers): include the commented hooks block
+ *   - The advisor-researcher (Read-only tools, no Write): no commented hooks
+ *
+ * We read the CURRENT commented-hooks block from the agent file and preserve it
+ * byte-for-byte; only name/description/tools/color are regenerated.
+ */
+function buildFrontmatter(profile, existingFrontmatter) {
+  // Extract the commented hooks section from the existing frontmatter, if any.
+  // The hooks block starts at `# hooks:` and runs to (but not including) the
+  // closing `---`. In the committed files there is NO blank line between
+  // `color:` and `# hooks:`, so we append it directly after the color line's `\n`.
+  const hooksMatch = existingFrontmatter.match(/(# hooks:[\s\S]*?)(?=\n---)/);
+  // hooksSuffix: if present, the block followed by a newline so `---` is on its own line;
+  // if absent, empty string (the closing `---` follows directly after color's `\n`).
+  const hooksSuffix = hooksMatch ? hooksMatch[1] + '\n' : '';
+
+  return (
+    '---\n' +
+    'name: ' + profile.name + '\n' +
+    'description: ' + profile.description + '\n' +
+    'tools: ' + profile.tools + '\n' +
+    'color: ' + profile.color + '\n' +
+    hooksSuffix +
+    '---'
+  );
+}
+
+// ─── Parse agent file ─────────────────────────────────────────────────────────
+
+/**
+ * Parse a .md file and return { frontmatterRaw, body, frontmatterFields }.
+ *
+ * frontmatterRaw: the raw text between the first and second `---` delimiters (exclusive)
+ * body: everything after the closing `---\n`
+ * frontmatterFields: { name, description, color, tools }
+ */
+function parseAgentFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // The frontmatter is between the first `---` line and the next `---` line.
+  const lines = raw.split('\n');
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      if (start === -1) {
+        start = i;
+      } else {
+        end = i;
+        break;
+      }
+    }
+  }
+
+  if (start === -1 || end === -1) {
+    throw new Error('No valid frontmatter delimiters found in ' + filePath);
+  }
+
+  const frontmatterLines = lines.slice(start + 1, end);
+  const frontmatterRaw = frontmatterLines.join('\n');
+  // body includes the closing `---` line and everything after
+  const fullFrontmatter = lines.slice(start, end + 1).join('\n');
+  const body = lines.slice(end + 1).join('\n');
+
+  const fields = {};
+  // Parse simple key: value pairs (not nested YAML, no multi-line values here)
+  for (const line of frontmatterLines) {
+    // Skip comment lines
+    if (line.trimStart().startsWith('#')) continue;
+    const m = line.match(/^(\w+):\s*(.*)/);
+    if (m) {
+      fields[m[1]] = m[2].trim();
+    }
+  }
+
+  return { raw, frontmatterRaw, fullFrontmatter, body, fields };
+}
+
+// ─── Check ────────────────────────────────────────────────────────────────────
+
+/**
+ * Check one profile against its agent file.
+ * Returns an array of failure strings (empty = pass).
+ */
+function checkAgent(profile) {
+  // Validate required array fields — return a clear failure rather than throwing TypeError.
+  for (const field of ['requiredIncludes', 'requiredSeamCalls', 'outputContract']) {
+    if (!Array.isArray(profile[field])) {
+      return ['profile ' + profile.name + ': missing required array field ' + field];
+    }
+  }
+
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const failures = [];
+
+  if (!fs.existsSync(agentPath)) {
+    return ['agent file not found: ' + agentPath];
+  }
+
+  const { fields } = parseAgentFile(agentPath);
+  const fullContent = fs.readFileSync(agentPath, 'utf8');
+
+  // (a) frontmatter fields
+  if (fields.name !== profile.name) {
+    failures.push(
+      'name mismatch: got "' + fields.name + '", want "' + profile.name + '"',
+    );
+  }
+  if (fields.description !== profile.description) {
+    failures.push(
+      'description mismatch:\n  got:  "' + fields.description + '"\n  want: "' + profile.description + '"',
+    );
+  }
+  if (fields.color !== profile.color) {
+    failures.push(
+      'color mismatch: got "' + fields.color + '", want "' + profile.color + '"',
+    );
+  }
+  if (fields.tools !== profile.tools) {
+    failures.push(
+      'tools mismatch:\n  got:  "' + fields.tools + '"\n  want: "' + profile.tools + '"',
+    );
+  }
+
+  // (b) requiredIncludes
+  for (const include of profile.requiredIncludes) {
+    if (!fullContent.includes(include)) {
+      failures.push('missing required include: ' + include);
+    }
+  }
+
+  // (c) requiredSeamCalls
+  for (const seam of profile.requiredSeamCalls) {
+    if (!fullContent.includes(seam)) {
+      failures.push('missing required seam call: ' + seam);
+    }
+  }
+
+  // (d) outputContract
+  for (const marker of profile.outputContract) {
+    if (!fullContent.includes(marker)) {
+      failures.push('missing output contract marker: ' + marker);
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Run --check for all profiles. Prints pass/fail per agent.
+ * Returns true if all pass, false otherwise.
+ */
+function runCheck() {
+  let allPassed = true;
+
+  for (const profile of PROFILES) {
+    const failures = checkAgent(profile);
+    if (failures.length === 0) {
+      process.stdout.write('  PASS  ' + profile.name + '\n');
+    } else {
+      process.stdout.write('  FAIL  ' + profile.name + '\n');
+      for (const f of failures) {
+        process.stdout.write('        ' + f.replace(/\n/g, '\n        ') + '\n');
+      }
+      allPassed = false;
+    }
+  }
+
+  return allPassed;
+}
+
+// ─── Write ────────────────────────────────────────────────────────────────────
+
+/**
+ * Regenerate the frontmatter block of one agent file from its profile.
+ * The body (everything after the closing ---) is preserved byte-for-byte.
+ */
+function writeAgent(profile) {
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const { fullFrontmatter, body } = parseAgentFile(agentPath);
+
+  const newFrontmatter = buildFrontmatter(profile, fullFrontmatter);
+  const newContent = newFrontmatter + '\n' + body;
+
+  fs.writeFileSync(agentPath, newContent, 'utf8');
+}
+
+function runWrite() {
+  for (const profile of PROFILES) {
+    const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+    if (!fs.existsSync(agentPath)) {
+      throw new ExitError(1, 'ERROR: agent file not found: ' + agentPath);
+    }
+    writeAgent(profile);
+    process.stdout.write('  wrote  ' + profile.name + '.md\n');
+  }
+  process.stdout.write('\nRun --check to verify:\n');
+  process.stdout.write('  node scripts/gen-research-agents.cjs --check\n');
+}
+
+// ─── Exports (for tests) ──────────────────────────────────────────────────────
+
+module.exports = { PROFILES, checkAgent, runCheck, parseAgentFile };
+
+// ─── CLI entry point ──────────────────────────────────────────────────────────
+
+function main() {
+  const flag = process.argv[2] || '--check';
+
+  if (flag === '--write') {
+    process.stdout.write('Writing frontmatter from profiles...\n');
+    runWrite();
+    process.stdout.write('\nVerifying...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nERROR: --check failed after --write. Fix serialization.\n');
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll agents match their profiles.\n');
+  } else if (flag === '--check') {
+    process.stdout.write('Checking research agent profiles...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nSome agents do not match their profiles.\n');
+      process.stdout.write(
+        '\nTo regenerate frontmatter from profiles:\n' +
+        '  node scripts/gen-research-agents.cjs --write\n',
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll 7 agents match their profiles.\n');
+  } else {
+    throw new ExitError(1, 'Unknown flag: ' + flag + '\nUsage: node scripts/gen-research-agents.cjs [--check|--write]');
+  }
+}
+
+if (require.main === module) {
+  runMain(main);
+}

package/scripts/lib/cli-exit.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Error that carries a process exit code. CLI logic throws this instead of
+ * calling process.exit() (banned by n/no-process-exit); runMain() translates it
+ * into process.exitCode at the entrypoint.
+ *
+ * @param {number} code  exit code (default 1)
+ * @param {string} [message]  optional human message; when set and code != 0 it is
+ *   written to stderr by runMain before the process exits.
+ */
+class ExitError extends Error {
+  constructor(code = 1, message) {
+    super(message === undefined ? `process exit ${code}` : message);
+    this.name = 'ExitError';
+    this.code = code;
+    // Whether runMain should print this.message to stderr (only when a real
+    // message was provided, not the synthetic default).
+    this.hasUserMessage = message !== undefined;
+  }
+}
+
+/**
+ * Run a CLI main function and translate its outcome into process.exitCode
+ * (never process.exit(), so n/no-process-exit stays satisfied). Supports sync or
+ * async main.
+ *   - main returns a number  -> process.exitCode = that number
+ *   - main throws/rejects ExitError -> process.exitCode = err.code, and if
+ *       err.hasUserMessage && err.code !== 0, err.message is written to stderr
+ *   - main throws/rejects anything else -> the stack is written to stderr and
+ *       process.exitCode = 1
+ * Letting the event loop drain (vs process.exit) means buffered stdout/stderr is
+ * flushed and process.on('exit') cleanup handlers still fire.
+ *
+ * @param {() => (number|void|Promise<number|void>)} main
+ */
+function runMain(main) {
+  Promise.resolve()
+    .then(() => main())
+    .then((code) => {
+      if (typeof code === 'number') process.exitCode = code;
+    })
+    .catch((err) => {
+      if (err instanceof ExitError) {
+        if (err.hasUserMessage && err.code !== 0) {
+          process.stderr.write(`${err.message}\n`);
+        }
+        process.exitCode = err.code;
+        return;
+      }
+      process.stderr.write(`${err && err.stack ? err.stack : String(err)}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { ExitError, runMain };

package/scripts/lint-command-contract.cjs

@@ -28,6 +28,8 @@ const {
   executionContextRefs: extractExecutionContextRefs,
 } = require('./command-contract-helpers.cjs');
 
+const { runMain } = require('./lib/cli-exit.cjs');
+
 // ─── check one file ───────────────────────────────────────────────────────────
 
 function check(filePath) {
@@ -79,30 +81,34 @@ function check(filePath) {
 
 // ─── run ─────────────────────────────────────────────────────────────────────
 
-const commandFiles = fs
-  .readdirSync(COMMANDS_DIR)
-  .filter(f => f.endsWith('.md'))
-  .map(f => path.join(COMMANDS_DIR, f));
+function main() {
+  const commandFiles = fs
+    .readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(COMMANDS_DIR, f));
 
-const results = commandFiles.map(check).filter(Boolean);
+  const results = commandFiles.map(check).filter(Boolean);
 
-if (results.length === 0) {
-  console.log(
-    `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
-  );
-  process.exit(0);
-}
+  if (results.length === 0) {
+    console.log(
+      `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
+    );
+    return 0;
+  }
 
-const total = results.reduce((n, r) => n + r.violations.length, 0);
-process.stderr.write(
-  `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
-);
-for (const r of results) {
-  process.stderr.write(`  ${r.file}\n`);
-  for (const v of r.violations) {
-    process.stderr.write(`    - ${v}\n`);
+  const total = results.reduce((n, r) => n + r.violations.length, 0);
+  process.stderr.write(
+    `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
+  );
+  for (const r of results) {
+    process.stderr.write(`  ${r.file}\n`);
+    for (const v of r.violations) {
+      process.stderr.write(`    - ${v}\n`);
+    }
+    process.stderr.write('\n');
   }
-  process.stderr.write('\n');
+  process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
+  return 1;
 }
-process.stderr.write('See docs/adr/0002-command-contract-validation-module.md for the contract spec.\n\n');
-process.exit(1);
+
+runMain(main);

package/scripts/lint-descriptions.cjs

@@ -15,6 +15,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const MAX_LENGTH = 100;
 const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
@@ -46,38 +47,41 @@ function getFiles() {
     .map(f => path.join(COMMANDS_DIR, f));
 }
 
-const files = getFiles();
-const violations = [];
+function main() {
+  const files = getFiles();
+  const violations = [];
 
-for (const filePath of files) {
-  let content;
-  try {
-    content = fs.readFileSync(filePath, 'utf-8');
-  } catch (err) {
-    process.stderr.write(`ERROR: Cannot read file: ${filePath}\n  ${err.message}\n`);
-    process.exit(1);
-  }
+  for (const filePath of files) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      throw new ExitError(1, `ERROR: Cannot read file: ${filePath}\n  ${err.message}`);
+    }
 
-  const description = parseDescription(content);
-  if (description === null) continue;
+    const description = parseDescription(content);
+    if (description === null) continue;
 
-  if (description.length > MAX_LENGTH) {
-    violations.push({ filePath, length: description.length, description });
+    if (description.length > MAX_LENGTH) {
+      violations.push({ filePath, length: description.length, description });
+    }
   }
-}
 
-if (violations.length === 0) {
-  const checked = files.length;
-  process.stdout.write(`ok lint-descriptions: ${checked} file(s) checked, 0 violations\n`);
-  process.exit(0);
-}
+  if (violations.length === 0) {
+    const checked = files.length;
+    process.stdout.write(`ok lint-descriptions: ${checked} file(s) checked, 0 violations\n`);
+    return 0;
+  }
 
-process.stderr.write(`\nERROR lint-descriptions: ${violations.length} violation(s) found\n\n`);
-for (const v of violations) {
-  const preview = v.description.length > 120 ? v.description.slice(0, 117) + '...' : v.description;
-  process.stderr.write(`  ${v.filePath}\n`);
-  process.stderr.write(`    Length : ${v.length} (max ${MAX_LENGTH})\n`);
-  process.stderr.write(`    Desc   : ${preview}\n\n`);
+  process.stderr.write(`\nERROR lint-descriptions: ${violations.length} violation(s) found\n\n`);
+  for (const v of violations) {
+    const preview = v.description.length > 120 ? v.description.slice(0, 117) + '...' : v.description;
+    process.stderr.write(`  ${v.filePath}\n`);
+    process.stderr.write(`    Length : ${v.length} (max ${MAX_LENGTH})\n`);
+    process.stderr.write(`    Desc   : ${preview}\n\n`);
+  }
+  process.stderr.write(`Trim descriptions to <= ${MAX_LENGTH} chars. Flag docs belong in argument-hint:.\n\n`);
+  return 1;
 }
-process.stderr.write(`Trim descriptions to <= ${MAX_LENGTH} chars. Flag docs belong in argument-hint:.\n\n`);
-process.exit(1);
+
+runMain(main);

package/scripts/lint-docs-required.cjs

@@ -14,6 +14,7 @@
  */
 
 const { parseFragment, FRAGMENT_ERROR } = require('./changeset/parse.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const LINT_REASON = Object.freeze({
   OK_NO_TRIGGERING_FRAGMENTS: 'ok_no_triggering_fragments',
@@ -161,8 +162,7 @@ function main() {
     );
     changedFiles = out.split('\n').filter(Boolean);
   } catch (e) {
-    process.stderr.write(`could not compute diff: ${e.message}\n`);
-    process.exit(2);
+    throw new ExitError(2, `could not compute diff: ${e.message}`);
   }
 
   const { fragments, malformed } = readFragmentsFromDisk(changedFiles, rootDir);
@@ -204,10 +204,10 @@ function main() {
       `exemption via \`<!-- docs-exempt: <reason> -->\` inside the fragment body also works.\n`,
     );
   }
-  process.exit(verdict.ok ? 0 : 1);
+  return verdict.ok ? 0 : 1;
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
 module.exports = {
   evaluateLint,