session-orchestrator 3.16.0

package/scripts/lib/validate/check-component-paths.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// check-component-paths.mjs — Validate plugin component path fields resolve to real locations.
+// Covers: commands, agents, hooks, mcpServers path resolution from plugin.json.
+// Usage: check-component-paths.mjs <plugin-root>
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ..."
+// Exit 0 = all checks passed; exit 1 = at least one failure.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const [, , pluginRoot] = process.argv;
+
+if (!pluginRoot) {
+  console.error('Usage: check-component-paths.mjs <plugin-root>');
+  process.exit(1);
+}
+
+const PLUGIN_JSON = join(pluginRoot, '.claude-plugin', 'plugin.json');
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) {
+  console.log(`  PASS: ${msg}`);
+  passed++;
+}
+
+function fail(msg) {
+  console.log(`  FAIL: ${msg}`);
+  failed++;
+}
+
+// ============================================================================
+// Check 4: Component path fields resolve to real files/directories
+// ============================================================================
+console.log('--- Check 4: component paths ---');
+
+// Load plugin.json — required for all checks below
+let json;
+try {
+  json = JSON.parse(readFileSync(PLUGIN_JSON, 'utf8'));
+} catch {
+  fail(`plugin.json not found or invalid JSON at ${PLUGIN_JSON}`);
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  process.exit(1);
+}
+
+// Conventional auto-discovery locations (relative to plugin root)
+const CONVENTIONAL = {
+  commands: 'commands',
+  agents: 'agents',
+  hooks: 'hooks/hooks.json',
+  mcpServers: '.mcp.json',
+};
+
+/**
+ * Strip a leading "./" from a path string.
+ * @param {string} p
+ * @returns {string}
+ */
+function stripLeadingDotSlash(p) {
+  return p.replace(/^\.\//, '');
+}
+
+/**
+ * Check that a component path field either resolves to a real path or
+ * falls back to a conventional location.
+ *
+ * @param {string} field        - JSON field name (e.g. "commands")
+ * @param {string} conventional - Conventional relative path under pluginRoot
+ * @param {boolean} optional    - If true, missing conventional path is a PASS
+ */
+function checkComponentPath(field, conventional, optional = false) {
+  const relPath = json[field] || '';
+
+  if (!relPath) {
+    // No explicit value — try conventional auto-discovery
+    const absPath = join(pluginRoot, conventional);
+    if (existsSync(absPath)) {
+      pass(`${field} auto-discovered at: ./${conventional}`);
+    } else if (optional) {
+      pass(`${field} not found at conventional location (optional, skipped)`);
+    } else {
+      fail(`${field} not found at conventional location: ./${conventional}`);
+    }
+    return;
+  }
+
+  // Explicit value — must start with "./"
+  if (!relPath.startsWith('./')) {
+    fail(`${field} path does not start with ./: ${relPath}`);
+    return;
+  }
+
+  const absPath = join(pluginRoot, stripLeadingDotSlash(relPath));
+  if (existsSync(absPath)) {
+    pass(`${field} resolves to: ${relPath}`);
+  } else {
+    fail(`${field} path does not exist: ${relPath} (resolved to ${absPath})`);
+  }
+}
+
+checkComponentPath('commands', CONVENTIONAL.commands);
+checkComponentPath('agents', CONVENTIONAL.agents);
+checkComponentPath('hooks', CONVENTIONAL.hooks);
+checkComponentPath('mcpServers', CONVENTIONAL.mcpServers, true);
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-dead-bridge.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// check-dead-bridge.mjs — Dead-bridge validator (dangling refs + bridge balance).
+//
+// Issue #671. Generalises the #618 baseline-fetch-bridge guard
+// (check-baseline-fetch-bridge.mjs) into a corpus-driven dead-bridge detector:
+// a "bridge" is a documented hand-off between two surfaces (a guard naming a
+// file, a doc pointer to a script, a Phase reference to a skill, …). A bridge
+// is DEAD when one end dangles — the referenced file/symbol no longer exists,
+// or the two ends of a documented pair are unbalanced.
+//
+// This module is the CLI ORCHESTRATOR. It owns the real-fs IO (RepoContext),
+// drives the FROZEN-contract detectors, prints PASS/FAIL lines, and sets the
+// exit code. The detection logic and the corpus of known bridges live in the
+// two sibling modules imported below.
+//
+// Usage: check-dead-bridge.mjs <plugin-root>
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ...".
+// Exit 0 = all bridges intact; 1 = at least one dead bridge; 2 = tool error
+// (a detector reported a `*-tool-error` rule — e.g. an unreadable surface).
+//
+// Import-safety: importing `runCheckDeadBridge` MUST NOT trigger any execution
+// or process.exit — the isMain guard at the bottom is the only side-effecting
+// path. The Quality wave imports runCheckDeadBridge directly for unit tests.
+
+import { pathToFileURL } from 'node:url';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { DETECTORS } from './dead-bridge-detectors.mjs';
+import * as corpus from './dead-bridge-corpus.mjs';
+
+const DEFAULT_EXTS = ['.mjs', '.md'];
+
+/**
+ * Recursively collect absolute paths under `absDir` whose extension is in
+ * `exts`. Returns [] when `absDir` is missing or not a directory. Defensive:
+ * an unreadable sub-directory is skipped rather than throwing, so a single bad
+ * entry never aborts the whole walk (tool-error surfacing is the detectors'
+ * job, via readText/exists on a specific surface).
+ *
+ * @param {string} absDir
+ * @param {string[] | null} exts  null/undefined → match every file
+ * @returns {string[]}
+ */
+function walk(absDir, exts) {
+  /** @type {string[]} */
+  const out = [];
+  let entries;
+  try {
+    if (!existsSync(absDir) || !statSync(absDir).isDirectory()) return out;
+    entries = readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const ent of entries) {
+    const full = path.join(absDir, ent.name);
+    let isDir;
+    let isFile;
+    try {
+      // Dirent gives the type directly; fall back to statSync for symlinks etc.
+      isDir = ent.isDirectory();
+      isFile = ent.isFile();
+      if (!isDir && !isFile && ent.isSymbolicLink()) {
+        const st = statSync(full);
+        isDir = st.isDirectory();
+        isFile = st.isFile();
+      }
+    } catch {
+      continue;
+    }
+    if (isDir) {
+      out.push(...walk(full, exts));
+    } else if (isFile) {
+      if (!exts || exts.includes(path.extname(full))) out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the RepoContext handed to every detector. All IO is real node:fs and
+ * lives ONLY here — detectors are pure functions of (ctx, corpus).
+ *
+ * @param {string} pluginRoot
+ * @returns {{
+ *   pluginRoot: string,
+ *   listMdFiles: (absDir: string) => string[],
+ *   listFiles: (absDir: string, exts?: string[]) => string[],
+ *   readText: (absPath: string) => string,
+ *   exists: (absPath: string) => boolean,
+ * }}
+ */
+export function buildRepoContext(pluginRoot) {
+  return {
+    pluginRoot,
+    listMdFiles: (absDir) => walk(absDir, ['.md']),
+    listFiles: (absDir, exts = DEFAULT_EXTS) => walk(absDir, exts),
+    readText: (absPath) => readFileSync(absPath, 'utf8'),
+    exists: (absPath) => existsSync(absPath),
+  };
+}
+
+/**
+ * Relativize an absolute path against the plugin root for human-readable
+ * output. Falls back to the raw path when it lies outside the root.
+ *
+ * @param {string} root
+ * @param {string} abs
+ * @returns {string}
+ */
+function relativize(root, abs) {
+  return path.relative(root, abs);
+}
+
+/**
+ * Run the dead-bridge validator against a plugin root. Drives every frozen
+ * detector, prints a PASS line per clean detector and a FAIL line per finding,
+ * then a Results summary. Returns the process exit code.
+ *
+ * @param {string} pluginRoot
+ * @returns {number} 0 = all bridges intact; 1 = dead bridge(s); 2 = tool error.
+ */
+export function runCheckDeadBridge(pluginRoot) {
+  const ctx = buildRepoContext(pluginRoot);
+
+  console.log('--- Check: dead-bridge validator (dangling refs + bridge balance) ---');
+
+  // Run every detector, collecting findings tagged by their producing detector.
+  /** @type {Array<{ rule: string, severity: string, file: string, line: number, message: string }>} */
+  const findings = [];
+  /** @type {Set<string>} */
+  const detectorsWithFindings = new Set();
+  /** @type {string[]} */
+  const allDetectorIds = [];
+  let toolError = false;
+
+  for (const { id, fn } of DETECTORS) {
+    allDetectorIds.push(id);
+    const out = fn(ctx, corpus) || [];
+    for (const f of out) {
+      findings.push(f);
+      detectorsWithFindings.add(id);
+      if (typeof f.rule === 'string' && f.rule.endsWith('-tool-error')) toolError = true;
+    }
+  }
+
+  // PASS line per detector that produced zero findings; FAIL line per finding.
+  // Detectors are processed in DETECTORS order; PASS lines are emitted first so
+  // the clean surfaces read before the failures (mirrors check-rules.mjs flow).
+  for (const id of allDetectorIds) {
+    if (!detectorsWithFindings.has(id)) {
+      console.log(`  PASS: ${id} — no dead bridges detected`);
+    }
+  }
+
+  for (const f of findings) {
+    const loc = f.file ? `${relativize(pluginRoot, f.file)}:${f.line} — ` : '';
+    console.log(`  FAIL: ${loc}${f.message}`);
+  }
+
+  const passed = allDetectorIds.length - detectorsWithFindings.size;
+  const failed = findings.length;
+
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+
+  if (toolError) return 2;
+  return failed > 0 ? 1 : 0;
+}
+
+// CLI entry — only when executed directly, never on import (keeps the exports
+// safe to import from tests without triggering process.exit).
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  const pluginRoot = process.argv[2];
+  if (!pluginRoot) {
+    console.error('Usage: check-dead-bridge.mjs <plugin-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckDeadBridge(pluginRoot));
+}

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// scripts/lib/validate/check-hooks-symmetry.mjs
+// Verify event-key + handler-file symmetry across hooks/{hooks,hooks-codex,hooks-cursor,hooks-pi}.json
+// Exit 0 = all checks pass, 1 = any check fails
+// Stdout: '  PASS: ...' / '  FAIL: ...' lines + 'Results: N passed, M failed'
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PLUGIN_ROOT = process.argv[2];
+if (!PLUGIN_ROOT) {
+  console.error('Usage: check-hooks-symmetry.mjs <plugin-root>');
+  process.exit(1);
+}
+
+const HOOKS_DIR = join(PLUGIN_ROOT, 'hooks');
+
+// Documented asymmetries — events expected to be missing from specific configs.
+// Anything NOT in this list that's asymmetric → FAIL (drift).
+const DOCUMENTED_ASYMMETRIES = {
+  // Events from hooks.json/hooks-codex.json that are intentionally absent in hooks-cursor.json
+  cursorMissingFromMain: ['SessionStart', 'SessionEnd', 'PostToolUse', 'PostToolUseFailure', 'PostToolBatch', 'Stop', 'SubagentStart', 'SubagentStop', 'CwdChanged', 'PreToolUse'],
+  // Events unique to hooks-cursor.json (Cursor IDE-specific)
+  cursorOnly: ['afterFileEdit', 'beforeShellExecution'],
+  // Claude/Codex events with no Pi-native v1 mapping yet.
+  piMissingFromMain: ['PostToolUseFailure', 'PostToolBatch', 'SubagentStart', 'SubagentStop', 'CwdChanged'],
+  // Pi-native extension events that map onto Claude/Codex hook events.
+  piEventMap: {
+    session_start: 'SessionStart',
+    session_shutdown: 'SessionEnd',
+    tool_call: 'PreToolUse',
+    tool_result: 'PostToolUse',
+    agent_end: 'Stop',
+  },
+};
+
+const REQUIRED_CODEX_EVENTS = [
+  'SessionStart',
+  'PreToolUse',
+  'PostToolUse',
+  'SubagentStart',
+  'SubagentStop',
+  'Stop',
+];
+const FORBIDDEN_CODEX_EVENTS = [
+  'SessionEnd',
+  'PostToolUseFailure',
+  'PostToolBatch',
+  'CwdChanged',
+];
+
+const REQUIRED_PI_TOOL_HANDLERS = {
+  bash: ['pre-bash-destructive-guard.mjs', 'enforce-commands.mjs'],
+  edit: ['enforce-scope.mjs', 'config-protection.mjs'],
+  write: ['enforce-scope.mjs', 'config-protection.mjs'],
+};
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed++; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed++; }
+
+// Step 1: Load JSON files — required files exit on error; cursor is optional (returns undefined)
+function loadJson(filePath, required = true) {
+  if (!required && !existsSync(filePath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    fail(`${filePath.split('/').pop()}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+const packageJson = loadJson(join(PLUGIN_ROOT, 'package.json'), false);
+const piPackageRequired = Boolean(packageJson?.pi);
+const claudeJson = loadJson(join(HOOKS_DIR, 'hooks.json'));
+const codexJson  = loadJson(join(HOOKS_DIR, 'hooks-codex.json'));
+const cursorJson = loadJson(join(HOOKS_DIR, 'hooks-cursor.json'), false);
+const piJson = loadJson(join(HOOKS_DIR, 'hooks-pi.json'), piPackageRequired);
+
+// Step 2: Extract event keys
+const claudeEvents = new Set(Object.keys(claudeJson.hooks || {}));
+const codexEvents  = new Set(Object.keys(codexJson.hooks || {}));
+const cursorEvents = cursorJson ? new Set(Object.keys(cursorJson.hooks || {})) : new Set();
+const piEvents = piJson ? new Set(Object.keys(piJson.hooks || {})) : new Set();
+
+// Step 3: Codex exposes a deliberate subset of the broader Claude event surface.
+console.log('--- Check 1: hooks-codex.json required/forbidden event surface ---');
+const missingRequiredCodex = REQUIRED_CODEX_EVENTS.filter((event) => !codexEvents.has(event));
+if (missingRequiredCodex.length === 0) {
+  pass(`required Codex event subset is present (${REQUIRED_CODEX_EVENTS.join(', ')})`);
+} else {
+  fail(`hooks-codex.json missing required events: ${missingRequiredCodex.join(', ')}`);
+}
+
+const forbiddenCodex = FORBIDDEN_CODEX_EVENTS.filter((event) => codexEvents.has(event));
+if (forbiddenCodex.length === 0) {
+  pass('hooks-codex.json excludes all forbidden Claude-only events');
+} else {
+  fail(`hooks-codex.json has forbidden unsupported events: ${forbiddenCodex.join(', ')}`);
+}
+
+// Step 4: cursor asymmetries must be documented
+console.log('');
+console.log('--- Check 2: hooks-cursor.json documented asymmetries ---');
+if (cursorJson) {
+  const cursorMissing = [...claudeEvents].filter((e) => !cursorEvents.has(e));
+  const undocumentedMissing = cursorMissing.filter((e) => !DOCUMENTED_ASYMMETRIES.cursorMissingFromMain.includes(e));
+  if (undocumentedMissing.length === 0) {
+    pass(`hooks-cursor.json missing events are all documented (${cursorMissing.length} events: ${cursorMissing.join(', ')})`);
+  } else {
+    fail(`hooks-cursor.json missing UNDOCUMENTED events: ${undocumentedMissing.join(', ')}`);
+  }
+
+  const cursorExtra = [...cursorEvents].filter((e) => !claudeEvents.has(e));
+  const undocumentedExtra = cursorExtra.filter((e) => !DOCUMENTED_ASYMMETRIES.cursorOnly.includes(e));
+  if (undocumentedExtra.length === 0) {
+    pass(`hooks-cursor.json cursor-only events are all documented (${cursorExtra.length} events: ${cursorExtra.join(', ')})`);
+  } else {
+    fail(`hooks-cursor.json has UNDOCUMENTED extra events: ${undocumentedExtra.join(', ')}`);
+  }
+} else {
+  pass(`hooks-cursor.json absent (optional config)`);
+}
+
+// Step 5: pi native-event mappings must cover all non-documented main events
+console.log('');
+console.log('--- Check 3: hooks-pi.json documented mappings ---');
+if (piJson) {
+  const piCoveredMainEvents = new Set();
+  for (const [piEvent, mainEvent] of Object.entries(DOCUMENTED_ASYMMETRIES.piEventMap)) {
+    if (piEvents.has(piEvent)) piCoveredMainEvents.add(mainEvent);
+  }
+
+  const piMissing = [...claudeEvents].filter((e) =>
+    !piCoveredMainEvents.has(e) && !DOCUMENTED_ASYMMETRIES.piMissingFromMain.includes(e));
+  if (piMissing.length === 0) {
+    pass(`hooks-pi.json covers mapped main events; missing events are documented (${DOCUMENTED_ASYMMETRIES.piMissingFromMain.join(', ')})`);
+  } else {
+    fail(`hooks-pi.json missing UNDOCUMENTED main-event mappings: ${piMissing.join(', ')}`);
+  }
+
+  const knownPiEvents = new Set(Object.keys(DOCUMENTED_ASYMMETRIES.piEventMap));
+  const piExtra = [...piEvents].filter((e) => !knownPiEvents.has(e));
+  if (piExtra.length === 0) {
+    pass(`hooks-pi.json pi-native events are all mapped (${piEvents.size} events)`);
+  } else {
+    fail(`hooks-pi.json has UNDOCUMENTED pi-native events: ${piExtra.join(', ')}`);
+  }
+
+  const missingToolHandlers = requiredPiToolHandlerGaps(piJson);
+  if (missingToolHandlers.length === 0) {
+    pass('hooks-pi.json wires required tool_call handlers for bash, edit, and write');
+  } else {
+    fail(`hooks-pi.json missing required tool_call handlers: ${missingToolHandlers.join('; ')}`);
+  }
+} else {
+  pass(`hooks-pi.json absent (optional config)`);
+}
+
+// Step 6: Extract handler-file refs from each config
+// Handles two shapes:
+//   Claude/Codex: hooks[event] = Array<{ hooks: Array<{ command: "node \"$CLAUDE_PLUGIN_ROOT/hooks/foo.mjs\"" }> }>
+//   Cursor:       hooks[event] = { script: "hooks/foo.mjs" }
+function extractHandlers(json) {
+  const handlers = new Set();
+  for (const event of Object.values(json.hooks || {})) {
+    const matchers = Array.isArray(event) ? event : [event];
+    for (const m of matchers) {
+      // Cursor shape: script field at matcher level
+      if (typeof m.script === 'string') {
+        const scriptMatch = m.script.match(/(?:hooks\/)([\w/-]+\.mjs)/);
+        if (scriptMatch) handlers.add(scriptMatch[1]);
+      }
+      // Claude/Codex shape: nested hooks array with command field
+      const hookList = m.hooks || [];
+      for (const h of hookList) {
+        const cmd = h.command || h.script || '';
+        const match = cmd.match(/(?:hooks\/|\$\{?CLAUDE_PLUGIN_ROOT\}?\/hooks\/|\$\{?CODEX_PLUGIN_ROOT\}?\/hooks\/|\$\{?PI_PLUGIN_ROOT\}?\/hooks\/)([\w/-]+\.mjs)/);
+        if (match) handlers.add(match[1]);
+      }
+    }
+  }
+  return handlers;
+}
+
+function matcherMatches(matcher, target) {
+  if (!matcher || matcher === '*') return true;
+  return matcher.split('|').map((p) => p.trim().toLowerCase()).includes(target);
+}
+
+function handlersForPiTool(json, toolName) {
+  const handlers = new Set();
+  const entries = Array.isArray(json.hooks?.tool_call) ? json.hooks.tool_call : [];
+  for (const entry of entries) {
+    const matcher = typeof entry.matcher === 'string' ? entry.matcher.toLowerCase() : '';
+    if (!matcherMatches(matcher, toolName)) continue;
+    for (const hook of Array.isArray(entry.hooks) ? entry.hooks : []) {
+      const cmd = hook.command || hook.script || '';
+      const match = cmd.match(/(?:hooks\/|\$\{?PI_PLUGIN_ROOT\}?\/hooks\/)([\w/-]+\.mjs)/);
+      if (match) handlers.add(match[1]);
+    }
+  }
+  return handlers;
+}
+
+function requiredPiToolHandlerGaps(json) {
+  const gaps = [];
+  for (const [toolName, requiredHandlers] of Object.entries(REQUIRED_PI_TOOL_HANDLERS)) {
+    const handlers = handlersForPiTool(json, toolName);
+    for (const required of requiredHandlers) {
+      if (!handlers.has(required)) gaps.push(`${toolName} → ${required}`);
+    }
+  }
+  return gaps;
+}
+const claudeHandlers = extractHandlers(claudeJson);
+const codexHandlers  = extractHandlers(codexJson);
+const cursorHandlers = cursorJson ? extractHandlers(cursorJson) : new Set();
+const piHandlers = piJson ? extractHandlers(piJson) : new Set();
+const allHandlers = new Set([...claudeHandlers, ...codexHandlers, ...cursorHandlers, ...piHandlers]);
+
+// Step 7: Verify each handler file exists on disk (skip _lib/* — those are library modules)
+console.log('');
+console.log('--- Check 4: handler files exist on disk ---');
+const missing = [];
+for (const h of allHandlers) {
+  if (h.startsWith('_lib/')) continue;  // library modules, not hook handlers
+  if (!existsSync(join(HOOKS_DIR, h))) {
+    missing.push(h);
+  }
+}
+if (missing.length === 0) {
+  pass(`all ${allHandlers.size} handler files exist on disk`);
+} else {
+  fail(`handler files referenced but missing: ${missing.join(', ')}`);
+}
+
+// Step 8: Reverse — find .mjs files in hooks/ that are NOT referenced anywhere (potential dead code)
+// (informational only — not a fail; ship as PASS noting count, with a stretch-goal output)
+console.log('');
+console.log('--- Check 5: no orphan .mjs files in hooks/ ---');
+let dirEntries = [];
+try { dirEntries = readdirSync(HOOKS_DIR); } catch { /* empty */ }
+const onDisk = dirEntries.filter((f) => f.endsWith('.mjs'));
+const unreferenced = onDisk.filter((f) => !allHandlers.has(f));
+if (unreferenced.length === 0) {
+  pass(`no orphan .mjs files in hooks/ (${onDisk.length} files all referenced)`);
+} else {
+  // INFO not FAIL — orphans are tolerated for now (e.g., _lib/ modules)
+  pass(`hooks/ has ${unreferenced.length} unreferenced .mjs files (allowed; they may be library helpers): ${unreferenced.join(', ')}`);
+}
+
+// Final
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-json-files.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// check-json-files.mjs — Validate hooks and mcpServers JSON file contents.
+// Usage: check-json-files.mjs <plugin-root>
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ..."
+// Exit 0 = all checks passed; exit 1 = at least one failure.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const [, , pluginRoot] = process.argv;
+
+if (!pluginRoot) {
+  console.error('Usage: check-json-files.mjs <plugin-root>');
+  process.exit(1);
+}
+
+const PLUGIN_JSON = join(pluginRoot, '.claude-plugin', 'plugin.json');
+const CONVENTIONAL_HOOKS = 'hooks/hooks.json';
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) {
+  console.log(`  PASS: ${msg}`);
+  passed++;
+}
+
+function fail(msg) {
+  console.log(`  FAIL: ${msg}`);
+  failed++;
+}
+
+function isValidJson(filePath) {
+  try {
+    JSON.parse(readFileSync(filePath, 'utf8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Read plugin.json to resolve configured paths
+let pluginData = {};
+if (existsSync(PLUGIN_JSON)) {
+  try {
+    pluginData = JSON.parse(readFileSync(PLUGIN_JSON, 'utf8'));
+  } catch {
+    // plugin.json invalid — proceed with empty data; path checks will use auto-discovery
+  }
+}
+
+// ============================================================================
+// Check 5: hooks file is valid JSON (if it's a .json file)
+// ============================================================================
+console.log('--- Check 5: hooks JSON validity ---');
+
+const hooksPath = pluginData.hooks ?? '';
+if (hooksPath && hooksPath.endsWith('.json')) {
+  const hooksAbs = join(pluginRoot, hooksPath.replace(/^\.\//, ''));
+  if (existsSync(hooksAbs)) {
+    if (isValidJson(hooksAbs)) {
+      pass('hooks file is valid JSON');
+    } else {
+      fail(`hooks file is not valid JSON: ${hooksPath}`);
+    }
+  } else {
+    fail('hooks file not found (already reported above)');
+  }
+} else {
+  const hooksAbs = join(pluginRoot, CONVENTIONAL_HOOKS);
+  if (existsSync(hooksAbs)) {
+    if (isValidJson(hooksAbs)) {
+      pass(`hooks file is valid JSON (auto-discovered at ./${CONVENTIONAL_HOOKS})`);
+    } else {
+      fail(`hooks file is not valid JSON: ./${CONVENTIONAL_HOOKS}`);
+    }
+  } else {
+    pass('hooks is not a JSON file or not specified (skipped)');
+  }
+}
+
+// ============================================================================
+// Check 5b: mcpServers file is valid JSON (if specified)
+// ============================================================================
+console.log('');
+console.log('--- Check 5b: mcpServers JSON validity ---');
+
+const mcpPath = pluginData.mcpServers ?? '';
+if (mcpPath && mcpPath.endsWith('.json')) {
+  const mcpAbs = join(pluginRoot, mcpPath.replace(/^\.\//, ''));
+  if (existsSync(mcpAbs)) {
+    if (isValidJson(mcpAbs)) {
+      pass('mcpServers file is valid JSON');
+    } else {
+      fail(`mcpServers file is not valid JSON: ${mcpPath}`);
+    }
+  } else {
+    fail('mcpServers file not found (already reported above)');
+  }
+} else {
+  const mcpAbs = join(pluginRoot, '.mcp.json');
+  if (existsSync(mcpAbs)) {
+    if (isValidJson(mcpAbs)) {
+      pass('mcpServers file is valid JSON (auto-discovered at ./.mcp.json)');
+    } else {
+      fail('mcpServers file is not valid JSON: ./.mcp.json');
+    }
+  } else {
+    pass('mcpServers not found at conventional location (optional, skipped)');
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+
+process.exit(failed > 0 ? 1 : 0);