Merge remote-tracking branch 'origin/main' into feat/optimize-biome-hooks

# Conflicts: # tests/hooks/hooks.test.js # tests/run-all.js
2026-03-31 14:13:27 +08:00 · 2026-03-10 20:25:22 -07:00
parent 67841042d6 0c2954565d
commit d239d873d8
29 changed files with 2705 additions and 167 deletions
--- a/scripts/ci/catalog.js
+++ b/scripts/ci/catalog.js
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Catalog agents, commands, and skills from the repo.
+ * Outputs JSON with counts and lists for CI/docs sync.
+ *
+ * Usage: node scripts/ci/catalog.js [--json|--md]
+ * Default: --json to stdout
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '../..');
+const AGENTS_DIR = path.join(ROOT, 'agents');
+const COMMANDS_DIR = path.join(ROOT, 'commands');
+const SKILLS_DIR = path.join(ROOT, 'skills');
+
+function listAgents() {
+  if (!fs.existsSync(AGENTS_DIR)) return [];
+  try {
+    return fs.readdirSync(AGENTS_DIR)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3))
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read agents directory (${AGENTS_DIR}): ${error.message}`);
+  }
+}
+
+function listCommands() {
+  if (!fs.existsSync(COMMANDS_DIR)) return [];
+  try {
+    return fs.readdirSync(COMMANDS_DIR)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3))
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read commands directory (${COMMANDS_DIR}): ${error.message}`);
+  }
+}
+
+function listSkills() {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  try {
+    const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    return entries
+      .filter(e => e.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
+      .map(e => e.name)
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read skills directory (${SKILLS_DIR}): ${error.message}`);
+  }
+}
+
+function run() {
+  const agents = listAgents();
+  const commands = listCommands();
+  const skills = listSkills();
+
+  const catalog = {
+    agents: { count: agents.length, list: agents },
+    commands: { count: commands.length, list: commands },
+    skills: { count: skills.length, list: skills }
+  };
+
+  const format = process.argv[2] === '--md' ? 'md' : 'json';
+  if (format === 'md') {
+    console.log('# ECC Catalog (generated)\n');
+    console.log(`- **Agents:** ${catalog.agents.count}`);
+    console.log(`- **Commands:** ${catalog.commands.count}`);
+    console.log(`- **Skills:** ${catalog.skills.count}\n`);
+    console.log('## Agents\n');
+    catalog.agents.list.forEach(a => { console.log(`- ${a}`); });
+    console.log('\n## Commands\n');
+    catalog.commands.list.forEach(c => { console.log(`- ${c}`); });
+    console.log('\n## Skills\n');
+    catalog.skills.list.forEach(s => { console.log(`- ${s}`); });
+  } else {
+    console.log(JSON.stringify(catalog, null, 2));
+  }
+}
+
+run();
--- a/scripts/ci/validate-hooks.js
+++ b/scripts/ci/validate-hooks.js
@@ -1,14 +1,45 @@
 #!/usr/bin/env node
 /**
- * Validate hooks.json schema
+ * Validate hooks.json schema and hook entry rules.
 */

 const fs = require('fs');
 const path = require('path');
 const vm = require('vm');
+const Ajv = require('ajv');

 const HOOKS_FILE = path.join(__dirname, '../../hooks/hooks.json');
-const VALID_EVENTS = ['PreToolUse', 'PostToolUse', 'PreCompact', 'SessionStart', 'SessionEnd', 'Stop', 'Notification', 'SubagentStop'];
+const HOOKS_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks.schema.json');
+const VALID_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'SubagentStart',
+  'Stop',
+  'SubagentStop',
+  'PreCompact',
+  'InstructionsLoaded',
+  'TeammateIdle',
+  'TaskCompleted',
+  'ConfigChange',
+  'WorktreeCreate',
+  'WorktreeRemove',
+  'SessionEnd',
+];
+const VALID_HOOK_TYPES = ['command', 'http', 'prompt', 'agent'];
+const EVENTS_WITHOUT_MATCHER = new Set(['UserPromptSubmit', 'Notification', 'Stop', 'SubagentStop']);
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(item => isNonEmptyString(item));
+}

 /**
 * Validate a single hook entry has required fields and valid inline JS
@@ -22,32 +53,72 @@ function validateHookEntry(hook, label) {
  if (!hook.type || typeof hook.type !== 'string') {
    console.error(`ERROR: ${label} missing or invalid 'type' field`);
    hasErrors = true;
-  }
-
-  // Validate optional async and timeout fields
-  if ('async' in hook && typeof hook.async !== 'boolean') {
-    console.error(`ERROR: ${label} 'async' must be a boolean`);
+  } else if (!VALID_HOOK_TYPES.includes(hook.type)) {
+    console.error(`ERROR: ${label} has unsupported hook type '${hook.type}'`);
    hasErrors = true;
  }
+
  if ('timeout' in hook && (typeof hook.timeout !== 'number' || hook.timeout < 0)) {
    console.error(`ERROR: ${label} 'timeout' must be a non-negative number`);
    hasErrors = true;
  }

-  if (!hook.command || (typeof hook.command !== 'string' && !Array.isArray(hook.command)) || (typeof hook.command === 'string' && !hook.command.trim()) || (Array.isArray(hook.command) && (hook.command.length === 0 || !hook.command.every(s => typeof s === 'string' && s.length > 0)))) {
-    console.error(`ERROR: ${label} missing or invalid 'command' field`);
-    hasErrors = true;
-  } else if (typeof hook.command === 'string') {
-    // Validate inline JS syntax in node -e commands
-    const nodeEMatch = hook.command.match(/^node -e "(.*)"$/s);
-    if (nodeEMatch) {
-      try {
-        new vm.Script(nodeEMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"').replace(/\\n/g, '\n').replace(/\\t/g, '\t'));
-      } catch (syntaxErr) {
-        console.error(`ERROR: ${label} has invalid inline JS: ${syntaxErr.message}`);
-        hasErrors = true;
+  if (hook.type === 'command') {
+    if ('async' in hook && typeof hook.async !== 'boolean') {
+      console.error(`ERROR: ${label} 'async' must be a boolean`);
+      hasErrors = true;
+    }
+
+    if (!isNonEmptyString(hook.command) && !isNonEmptyStringArray(hook.command)) {
+      console.error(`ERROR: ${label} missing or invalid 'command' field`);
+      hasErrors = true;
+    } else if (typeof hook.command === 'string') {
+      const nodeEMatch = hook.command.match(/^node -e "(.*)"$/s);
+      if (nodeEMatch) {
+        try {
+          new vm.Script(nodeEMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"').replace(/\\n/g, '\n').replace(/\\t/g, '\t'));
+        } catch (syntaxErr) {
+          console.error(`ERROR: ${label} has invalid inline JS: ${syntaxErr.message}`);
+          hasErrors = true;
+        }
      }
    }
+
+    return hasErrors;
+  }
+
+  if ('async' in hook) {
+    console.error(`ERROR: ${label} 'async' is only supported for command hooks`);
+    hasErrors = true;
+  }
+
+  if (hook.type === 'http') {
+    if (!isNonEmptyString(hook.url)) {
+      console.error(`ERROR: ${label} missing or invalid 'url' field`);
+      hasErrors = true;
+    }
+
+    if ('headers' in hook && (typeof hook.headers !== 'object' || hook.headers === null || Array.isArray(hook.headers) || !Object.values(hook.headers).every(value => typeof value === 'string'))) {
+      console.error(`ERROR: ${label} 'headers' must be an object with string values`);
+      hasErrors = true;
+    }
+
+    if ('allowedEnvVars' in hook && (!Array.isArray(hook.allowedEnvVars) || !hook.allowedEnvVars.every(value => isNonEmptyString(value)))) {
+      console.error(`ERROR: ${label} 'allowedEnvVars' must be an array of strings`);
+      hasErrors = true;
+    }
+
+    return hasErrors;
+  }
+
+  if (!isNonEmptyString(hook.prompt)) {
+    console.error(`ERROR: ${label} missing or invalid 'prompt' field`);
+    hasErrors = true;
+  }
+
+  if ('model' in hook && !isNonEmptyString(hook.model)) {
+    console.error(`ERROR: ${label} 'model' must be a non-empty string`);
+    hasErrors = true;
  }

  return hasErrors;
@@ -67,6 +138,20 @@ function validateHooks() {
    process.exit(1);
  }

+  // Validate against JSON schema
+  if (fs.existsSync(HOOKS_SCHEMA_PATH)) {
+    const schema = JSON.parse(fs.readFileSync(HOOKS_SCHEMA_PATH, 'utf-8'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const valid = validate(data);
+    if (!valid) {
+      for (const err of validate.errors) {
+        console.error(`ERROR: hooks.json schema: ${err.instancePath || '/'} ${err.message}`);
+      }
+      process.exit(1);
+    }
+  }
+
  // Support both object format { hooks: {...} } and array format
  const hooks = data.hooks || data;
  let hasErrors = false;
@@ -94,9 +179,12 @@ function validateHooks() {
          hasErrors = true;
          continue;
        }
-        if (!matcher.matcher) {
+        if (!('matcher' in matcher) && !EVENTS_WITHOUT_MATCHER.has(eventType)) {
          console.error(`ERROR: ${eventType}[${i}] missing 'matcher' field`);
          hasErrors = true;
+        } else if ('matcher' in matcher && typeof matcher.matcher !== 'string' && (typeof matcher.matcher !== 'object' || matcher.matcher === null)) {
+          console.error(`ERROR: ${eventType}[${i}] has invalid 'matcher' field`);
+          hasErrors = true;
        }
        if (!matcher.hooks || !Array.isArray(matcher.hooks)) {
          console.error(`ERROR: ${eventType}[${i}] missing 'hooks' array`);
@@ -116,9 +204,12 @@ function validateHooks() {
    // Array format (legacy)
    for (let i = 0; i < hooks.length; i++) {
      const hook = hooks[i];
-      if (!hook.matcher) {
+      if (!('matcher' in hook)) {
        console.error(`ERROR: Hook ${i} missing 'matcher' field`);
        hasErrors = true;
+      } else if (typeof hook.matcher !== 'string' && (typeof hook.matcher !== 'object' || hook.matcher === null)) {
+        console.error(`ERROR: Hook ${i} has invalid 'matcher' field`);
+        hasErrors = true;
      }
      if (!hook.hooks || !Array.isArray(hook.hooks)) {
        console.error(`ERROR: Hook ${i} missing 'hooks' array`);