@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

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,

package/scripts/lint-legacy-dir-name.cjs

@@ -33,6 +33,7 @@
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 // Constructed with split to avoid self-match when this script is scanned.
 const FORBIDDEN = 'get-shit' + '-done';
@@ -90,67 +91,70 @@ function isBinary(fullPath) {
   }
 }
 
-// Enumerate tracked files via git ls-files so only committed/staged source is checked.
-let trackedFiles;
-try {
-  trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
-    .split('\n')
-    .map((f) => f.trim())
-    .filter(Boolean);
-} catch (err) {
-  process.stderr.write('ERROR lint-legacy-dir-name: git ls-files failed: ' + err.message + '\n');
-  process.exit(1);
-}
+function main() {
+  // Enumerate tracked files via git ls-files so only committed/staged source is checked.
+  let trackedFiles;
+  try {
+    trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-legacy-dir-name: git ls-files failed: ' + err.message);
+  }
 
-const violations = [];
+  const violations = [];
 
-for (const relPath of trackedFiles) {
-  if (isAllowlisted(relPath)) continue;
+  for (const relPath of trackedFiles) {
+    if (isAllowlisted(relPath)) continue;
 
-  const fullPath = path.join(REPO_ROOT, relPath);
+    const fullPath = path.join(REPO_ROOT, relPath);
 
-  // Skip this guard script itself.
-  if (path.resolve(fullPath) === SELF_PATH) continue;
+    // Skip this guard script itself.
+    if (path.resolve(fullPath) === SELF_PATH) continue;
 
-  if (isBinary(fullPath)) continue;
+    if (isBinary(fullPath)) continue;
 
-  let content;
-  try {
-    content = fs.readFileSync(fullPath, 'utf8');
-  } catch {
-    // Unreadable files (permissions, etc.) — skip silently.
-    continue;
-  }
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable files (permissions, etc.) — skip silently.
+      continue;
+    }
 
-  const lines = content.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    // Skip lines that carry the explicit allow marker.
-    if (line.includes(ALLOW_MARKER)) continue;
-
-    FORBIDDEN_RE.lastIndex = 0;
-    let match;
-    while ((match = FORBIDDEN_RE.exec(line)) !== null) {
-      violations.push({
-        file: relPath,
-        line: i + 1,
-        col: match.index + 1,
-        text: match[0],
-      });
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Skip lines that carry the explicit allow marker.
+      if (line.includes(ALLOW_MARKER)) continue;
+
+      FORBIDDEN_RE.lastIndex = 0;
+      let match;
+      while ((match = FORBIDDEN_RE.exec(line)) !== null) {
+        violations.push({
+          file: relPath,
+          line: i + 1,
+          col: match.index + 1,
+          text: match[0],
+        });
+      }
     }
   }
-}
 
-if (violations.length === 0) {
-  process.stdout.write('ok lint-legacy-dir-name: ' + trackedFiles.length + ' tracked file(s) checked, 0 violations\n');
-  process.exit(0);
-}
+  if (violations.length === 0) {
+    process.stdout.write('ok lint-legacy-dir-name: ' + trackedFiles.length + ' tracked file(s) checked, 0 violations\n');
+    return 0;
+  }
 
-process.stderr.write('\nERROR lint-legacy-dir-name: ' + violations.length + ' violation(s) found\n\n');
-for (const v of violations) {
-  process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n');
+  process.stderr.write('\nERROR lint-legacy-dir-name: ' + violations.length + ' violation(s) found\n\n');
+  for (const v of violations) {
+    process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n');
+  }
+  process.stderr.write('\n');
+  process.stderr.write('Fix: rename to gsd-core, or add `gsd-allow-legacy-name` marker on the line if the\n');
+  process.stderr.write('      use is intentional (migration modules, tests, guard, changeset).\n\n');
+  return 1;
 }
-process.stderr.write('\n');
-process.stderr.write('Fix: rename to gsd-core, or add `gsd-allow-legacy-name` marker on the line if the\n');
-process.stderr.write('      use is intentional (migration modules, tests, guard, changeset).\n\n');
-process.exit(1);
+
+runMain(main);

package/scripts/lint-pr-check-project-dir.cjs

@@ -4,6 +4,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { runMain } = require('./lib/cli-exit.cjs');
+
 const ROOT = path.join(__dirname, '..');
 
 const DEFAULT_RELATIVE_FILES = [
@@ -84,7 +86,7 @@ function main(argv = process.argv.slice(2)) {
 }
 
 if (require.main === module) {
-  process.exit(main());
+  runMain(main);
 }
 
 module.exports = {

package/scripts/lint-shell-command-projection-drift.cjs

@@ -13,19 +13,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
-const targetArg = process.argv[2] || path.join(ROOT, 'bin', 'install.js');
-const target = path.resolve(targetArg);
-const rel = path.relative(ROOT, target);
-
-let content;
-try {
-  content = fs.readFileSync(target, 'utf8');
-} catch (error) {
-  process.stderr.write(`lint-shell-command-projection-drift: failed to read ${target}: ${error.message}\n`);
-  process.exit(1);
-}
 
 const forbidden = [
   {
@@ -42,16 +32,31 @@ const forbidden = [
   },
 ];
 
-const matches = forbidden.filter((rule) => rule.pattern.test(content));
-if (matches.length === 0) {
-  process.stdout.write(`ok shell-projection-drift: ${rel}\n`);
-  process.exit(0);
-}
+function main() {
+  const targetArg = process.argv[2] || path.join(ROOT, 'bin', 'install.js');
+  const target = path.resolve(targetArg);
+  const rel = path.relative(ROOT, target);
+
+  let content;
+  try {
+    content = fs.readFileSync(target, 'utf8');
+  } catch (error) {
+    throw new ExitError(1, `lint-shell-command-projection-drift: failed to read ${target}: ${error.message}`);
+  }
 
-process.stderr.write(`ERROR shell-projection-drift: inline serialized shim builders found in ${rel}\n`);
-for (const match of matches) {
-  process.stderr.write(`  - ${match.label}\n`);
+  const matches = forbidden.filter((rule) => rule.pattern.test(content));
+  if (matches.length === 0) {
+    process.stdout.write(`ok shell-projection-drift: ${rel}\n`);
+    return 0;
+  }
+
+  process.stderr.write(`ERROR shell-projection-drift: inline serialized shim builders found in ${rel}\n`);
+  for (const match of matches) {
+    process.stderr.write(`  - ${match.label}\n`);
+  }
+  process.stderr.write('Route shim/wrapper rendering through gsd-core/bin/lib/shell-command-projection.cjs\n');
+  process.stderr.write('Safe subprocess execution via spawnSync/execFileSync is intentionally allowed.\n');
+  return 1;
 }
-process.stderr.write('Route shim/wrapper rendering through gsd-core/bin/lib/shell-command-projection.cjs\n');
-process.stderr.write('Safe subprocess execution via spawnSync/execFileSync is intentionally allowed.\n');
-process.exit(1);
+
+runMain(main);

package/scripts/lint-skill-deps.cjs

@@ -25,6 +25,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { runMain } = require('./lib/cli-exit.cjs');
 
 const PROFILES_MODULE = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'install-profiles.cjs');
 const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE);
@@ -142,39 +143,43 @@ function checkProfileClosure(manifest) {
 // Main
 // ---------------------------------------------------------------------------
 
-const manifest = loadSkillsManifest(commandsDir);
-const allStems = new Set(
-  [...manifest.keys()].filter((k) => !k.startsWith('_calls_agents_'))
-);
+function main() {
+  const manifest = loadSkillsManifest(commandsDir);
+  const allStems = new Set(
+    [...manifest.keys()].filter((k) => !k.startsWith('_calls_agents_'))
+  );
 
-const consistencyViolations = checkFrontmatterBodyConsistency(manifest, allStems);
-const closureViolations = checkProfileClosure(manifest);
+  const consistencyViolations = checkFrontmatterBodyConsistency(manifest, allStems);
+  const closureViolations = checkProfileClosure(manifest);
 
-const totalViolations = consistencyViolations.length + closureViolations.length;
+  const totalViolations = consistencyViolations.length + closureViolations.length;
 
-if (totalViolations === 0) {
-  const checked = manifest.size;
-  process.stdout.write('ok lint-skill-deps: ' + checked + ' skill(s) checked, 0 violations\n');
-  process.exit(0);
-}
+  if (totalViolations === 0) {
+    const checked = manifest.size;
+    process.stdout.write('ok lint-skill-deps: ' + checked + ' skill(s) checked, 0 violations\n');
+    return 0;
+  }
 
-process.stderr.write('\nERROR lint-skill-deps: ' + totalViolations + ' violation(s) found\n\n');
+  process.stderr.write('\nERROR lint-skill-deps: ' + totalViolations + ' violation(s) found\n\n');
 
-if (consistencyViolations.length > 0) {
-  process.stderr.write('Frontmatter to body consistency violations (' + consistencyViolations.length + '):\n\n');
-  for (const v of consistencyViolations) {
-    process.stderr.write('  ' + v.filePath + '\n');
-    process.stderr.write('    ' + v.message + '\n\n');
+  if (consistencyViolations.length > 0) {
+    process.stderr.write('Frontmatter to body consistency violations (' + consistencyViolations.length + '):\n\n');
+    for (const v of consistencyViolations) {
+      process.stderr.write('  ' + v.filePath + '\n');
+      process.stderr.write('    ' + v.message + '\n\n');
+    }
+    process.stderr.write('Fix: add missing deps to requires: in the skill frontmatter.\n\n');
   }
-  process.stderr.write('Fix: add missing deps to requires: in the skill frontmatter.\n\n');
-}
 
-if (closureViolations.length > 0) {
-  process.stderr.write('Profile closure violations (' + closureViolations.length + '):\n\n');
-  for (const v of closureViolations) {
-    process.stderr.write('  ' + v.message + '\n');
+  if (closureViolations.length > 0) {
+    process.stderr.write('Profile closure violations (' + closureViolations.length + '):\n\n');
+    for (const v of closureViolations) {
+      process.stderr.write('  ' + v.message + '\n');
+    }
+    process.stderr.write('\nFix: add the missing skills to the profile base set in install-profiles.cjs.\n\n');
   }
-  process.stderr.write('\nFix: add the missing skills to the profile base set in install-profiles.cjs.\n\n');
+
+  return 1;
 }
 
-process.exit(1);
+runMain(main);

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

@@ -43,6 +43,7 @@
     },
     "milestone": {
       "files": [
+        "bug-730-milestone-phase-details-scope.test.cjs",
         "milestone-archive.test.cjs",
         "milestone-helper.test.cjs",
         "milestone-prefixed-convention.test.cjs",
@@ -120,6 +121,7 @@
     "install": {
       "files": [
         "bug-410-install-defaults-test-mode-guard.test.cjs",
+        "enh-776-install-gemini-hook-events.test.cjs",
         "install-minimal-hooks.test.cjs",
         "install-path-detection.test.cjs",
         "install-regressions.test.cjs",

package/scripts/lint-test-file-count.cjs

@@ -17,6 +17,7 @@
 const fs   = require('fs');
 const path = require('path');
 const { assertWithinAllowlist } = require('./lib/allowlist-ratchet.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
 
 const ROOT = path.join(__dirname, '..');
 const PROD_DIRS = [
@@ -201,14 +202,14 @@ function run() {
 
   if (jsonMode) {
     console.log(JSON.stringify({ ok: failures.length === 0, results, failures, hints: [] }, null, 2));
-    process.exit(failures.length > 0 ? 1 : 0);
+    return failures.length > 0 ? 1 : 0;
   }
 
   if (failures.length === 0) {
     const inAllowlist = results.filter(r => r.verdict === Verdict.OK_IN_ALLOWLIST).length;
     console.log(`ok lint-test-file-count: ${results.length} module(s) checked, 0 failures` +
       (inAllowlist > 0 ? `, ${inAllowlist} allowlisted` : ''));
-    process.exit(0);
+    return 0;
   }
 
   process.stderr.write(`\nERROR lint-test-file-count: ${failures.length} module(s) exceed the test-file limit\n\n`);
@@ -231,7 +232,7 @@ function run() {
   }
   process.stderr.write('\nFix: consolidate test files per module (one primary + one integration).\n');
   process.stderr.write('Or update scripts/lint-test-file-count.allowlist.json with PR justification.\n\n');
-  process.exit(1);
+  return 1;
 }
 
 module.exports = {
@@ -242,4 +243,4 @@ module.exports = {
   _loadAllowlist: loadAllowlist,
 };
 
-if (require.main === module) run();
+if (require.main === module) runMain(run);

package/scripts/mutation-matrix.cjs

@@ -32,6 +32,8 @@
 const { execFileSync } = require('child_process');
 const { readFileSync } = require('fs');
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 // ── Single source of truth: covered modules ───────────────────────────────────
 // Each entry: { cjs: '<built artifact>', tests: ['tests/...', ...] }
 // A module is "covered" iff its tests are wired into the Stryker command runner
@@ -121,7 +123,7 @@ function parseArgs(argv) {
         '  --base <ref>   Git ref to diff against (default: origin/${GITHUB_BASE_REF:-next})',
         '  --print        Human-readable output instead of JSON',
       ].join('\n'));
-      process.exit(0);
+      throw new ExitError(0);
     } else {
       throw new Error(`unknown argument: ${arg}`);
     }
@@ -211,9 +213,10 @@ function main() {
       console.log(JSON.stringify(result, null, 2));
     }
   } catch (err) {
+    if (err instanceof ExitError) throw err;
     console.error(`mutation-matrix: ${err.message}`);
-    process.exit(2);
+    throw new ExitError(2);
   }
 }
 
-main();
+runMain(main);

package/scripts/prompt-injection-scan.sh

@@ -83,7 +83,7 @@ ALLOWLIST=(
   # These files contain intentional injection examples / security-model prose
   # and are not attack vectors — they explain/demonstrate injection patterns.
   'TEST-EXAMPLES.md'
-  'docs/explanation/security-model.md'
+  'explanation/security-model.md'
 )
 
 is_allowlisted() {