cc4pm 1.8.0

package/schemas/plugin.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Plugin Configuration",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "name": { "type": "string" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "description": { "type": "string" },
+    "author": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "url": { "type": "string", "format": "uri" }
+          },
+          "required": ["name"]
+        }
+      ]
+    },
+    "homepage": { "type": "string", "format": "uri" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "agents": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "features": {
+      "type": "object",
+      "properties": {
+        "agents": { "type": "integer", "minimum": 0 },
+        "commands": { "type": "integer", "minimum": 0 },
+        "skills": { "type": "integer", "minimum": 0 },
+        "configAssets": { "type": "boolean" },
+        "hookEvents": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "customTools": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/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('# cc4pm 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();

package/scripts/ci/validate-agents.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Validate agent markdown files have required frontmatter
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '../../agents');
+const REQUIRED_FIELDS = ['model', 'tools'];
+const VALID_MODELS = ['haiku', 'sonnet', 'opus'];
+
+function extractFrontmatter(content) {
+  // Strip BOM if present (UTF-8 BOM: \uFEFF)
+  const cleanContent = content.replace(/^\uFEFF/, '');
+  // Support both LF and CRLF line endings
+  const match = cleanContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split(/\r?\n/);
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+  return frontmatter;
+}
+
+function validateAgents() {
+  if (!fs.existsSync(AGENTS_DIR)) {
+    console.log('No agents directory found, skipping validation');
+    process.exit(0);
+  }
+
+  const files = fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'));
+  let hasErrors = false;
+
+  for (const file of files) {
+    const filePath = path.join(AGENTS_DIR, file);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      console.error(`ERROR: ${file} - ${err.message}`);
+      hasErrors = true;
+      continue;
+    }
+    const frontmatter = extractFrontmatter(content);
+
+    if (!frontmatter) {
+      console.error(`ERROR: ${file} - Missing frontmatter`);
+      hasErrors = true;
+      continue;
+    }
+
+    for (const field of REQUIRED_FIELDS) {
+      if (!frontmatter[field] || (typeof frontmatter[field] === 'string' && !frontmatter[field].trim())) {
+        console.error(`ERROR: ${file} - Missing required field: ${field}`);
+        hasErrors = true;
+      }
+    }
+
+    // Validate model is a known value
+    if (frontmatter.model && !VALID_MODELS.includes(frontmatter.model)) {
+      console.error(`ERROR: ${file} - Invalid model '${frontmatter.model}'. Must be one of: ${VALID_MODELS.join(', ')}`);
+      hasErrors = true;
+    }
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  console.log(`Validated ${files.length} agent files`);
+}
+
+validateAgents();

package/scripts/ci/validate-commands.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Validate command markdown files are non-empty, readable,
+ * and have valid cross-references to other commands, agents, and skills.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.join(__dirname, '../..');
+const COMMANDS_DIR = path.join(ROOT_DIR, 'commands');
+const AGENTS_DIR = path.join(ROOT_DIR, 'agents');
+const SKILLS_DIR = path.join(ROOT_DIR, 'skills');
+
+function validateCommands() {
+  if (!fs.existsSync(COMMANDS_DIR)) {
+    console.log('No commands directory found, skipping validation');
+    process.exit(0);
+  }
+
+  const files = fs.readdirSync(COMMANDS_DIR).filter(f => f.endsWith('.md'));
+  let hasErrors = false;
+  let warnCount = 0;
+
+  // Build set of valid command names (without .md extension)
+  const validCommands = new Set(files.map(f => f.replace(/\.md$/, '')));
+
+  // Build set of valid agent names (without .md extension)
+  const validAgents = new Set();
+  if (fs.existsSync(AGENTS_DIR)) {
+    for (const f of fs.readdirSync(AGENTS_DIR)) {
+      if (f.endsWith('.md')) {
+        validAgents.add(f.replace(/\.md$/, ''));
+      }
+    }
+  }
+
+  // Build set of valid skill directory names
+  const validSkills = new Set();
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const f of fs.readdirSync(SKILLS_DIR)) {
+      const skillPath = path.join(SKILLS_DIR, f);
+      try {
+        if (fs.statSync(skillPath).isDirectory()) {
+          validSkills.add(f);
+        }
+      } catch {
+        // skip unreadable entries
+      }
+    }
+  }
+
+  for (const file of files) {
+    const filePath = path.join(COMMANDS_DIR, file);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      console.error(`ERROR: ${file} - ${err.message}`);
+      hasErrors = true;
+      continue;
+    }
+
+    // Validate the file is non-empty readable markdown
+    if (content.trim().length === 0) {
+      console.error(`ERROR: ${file} - Empty command file`);
+      hasErrors = true;
+      continue;
+    }
+
+    // Strip fenced code blocks before checking cross-references.
+    // Examples/templates inside ``` blocks are not real references.
+    const contentNoCodeBlocks = content.replace(/```[\s\S]*?```/g, '');
+
+    // Check cross-references to other commands (e.g., `/build-fix`)
+    // Skip lines that describe hypothetical output (e.g., "→ Creates: `/new-table`")
+    // Process line-by-line so ALL command refs per line are captured
+    // (previous anchored regex /^.*`\/...`.*$/gm only matched the last ref per line)
+    for (const line of contentNoCodeBlocks.split('\n')) {
+      if (/creates:|would create:/i.test(line)) continue;
+      const lineRefs = line.matchAll(/`\/([a-z][-a-z0-9]*)`/g);
+      for (const match of lineRefs) {
+        const refName = match[1];
+        if (!validCommands.has(refName)) {
+          console.error(`ERROR: ${file} - references non-existent command /${refName}`);
+          hasErrors = true;
+        }
+      }
+    }
+
+    // Check agent references (e.g., "agents/planner.md" or "`planner` agent")
+    const agentPathRefs = contentNoCodeBlocks.matchAll(/agents\/([a-z][-a-z0-9]*)\.md/g);
+    for (const match of agentPathRefs) {
+      const refName = match[1];
+      if (!validAgents.has(refName)) {
+        console.error(`ERROR: ${file} - references non-existent agent agents/${refName}.md`);
+        hasErrors = true;
+      }
+    }
+
+    // Check skill directory references (e.g., "skills/tdd-workflow/")
+    const skillRefs = contentNoCodeBlocks.matchAll(/skills\/([a-z][-a-z0-9]*)\//g);
+    for (const match of skillRefs) {
+      const refName = match[1];
+      if (!validSkills.has(refName)) {
+        console.warn(`WARN: ${file} - references skill directory skills/${refName}/ (not found locally)`);
+        warnCount++;
+      }
+    }
+
+    // Check agent name references in workflow diagrams (e.g., "planner -> tdd-guide")
+    const workflowLines = contentNoCodeBlocks.matchAll(/^([a-z][-a-z0-9]*(?:\s*->\s*[a-z][-a-z0-9]*)+)$/gm);
+    for (const match of workflowLines) {
+      const agents = match[1].split(/\s*->\s*/);
+      for (const agent of agents) {
+        if (!validAgents.has(agent)) {
+          console.error(`ERROR: ${file} - workflow references non-existent agent "${agent}"`);
+          hasErrors = true;
+        }
+      }
+    }
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  let msg = `Validated ${files.length} command files`;
+  if (warnCount > 0) {
+    msg += ` (${warnCount} warnings)`;
+  }
+  console.log(msg);
+}
+
+validateCommands();

package/scripts/ci/validate-hooks.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * 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 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
+ * @param {object} hook - Hook object with type and command fields
+ * @param {string} label - Label for error messages (e.g., "PreToolUse[0].hooks[1]")
+ * @returns {boolean} true if errors were found
+ */
+function validateHookEntry(hook, label) {
+  let hasErrors = false;
+
+  if (!hook.type || typeof hook.type !== 'string') {
+    console.error(`ERROR: ${label} missing or invalid 'type' field`);
+    hasErrors = true;
+  } 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.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;
+}
+
+function validateHooks() {
+  if (!fs.existsSync(HOOKS_FILE)) {
+    console.log('No hooks.json found, skipping validation');
+    process.exit(0);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(HOOKS_FILE, 'utf-8'));
+  } catch (e) {
+    console.error(`ERROR: Invalid JSON in hooks.json: ${e.message}`);
+    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;
+  let totalMatchers = 0;
+
+  if (typeof hooks === 'object' && !Array.isArray(hooks)) {
+    // Object format: { EventType: [matchers] }
+    for (const [eventType, matchers] of Object.entries(hooks)) {
+      if (!VALID_EVENTS.includes(eventType)) {
+        console.error(`ERROR: Invalid event type: ${eventType}`);
+        hasErrors = true;
+        continue;
+      }
+
+      if (!Array.isArray(matchers)) {
+        console.error(`ERROR: ${eventType} must be an array`);
+        hasErrors = true;
+        continue;
+      }
+
+      for (let i = 0; i < matchers.length; i++) {
+        const matcher = matchers[i];
+        if (typeof matcher !== 'object' || matcher === null) {
+          console.error(`ERROR: ${eventType}[${i}] is not an object`);
+          hasErrors = true;
+          continue;
+        }
+        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`);
+          hasErrors = true;
+        } else {
+          // Validate each hook entry
+          for (let j = 0; j < matcher.hooks.length; j++) {
+            if (validateHookEntry(matcher.hooks[j], `${eventType}[${i}].hooks[${j}]`)) {
+              hasErrors = true;
+            }
+          }
+        }
+        totalMatchers++;
+      }
+    }
+  } else if (Array.isArray(hooks)) {
+    // Array format (legacy)
+    for (let i = 0; i < hooks.length; i++) {
+      const hook = hooks[i];
+      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`);
+        hasErrors = true;
+      } else {
+        // Validate each hook entry
+        for (let j = 0; j < hook.hooks.length; j++) {
+          if (validateHookEntry(hook.hooks[j], `Hook ${i}.hooks[${j}]`)) {
+            hasErrors = true;
+          }
+        }
+      }
+      totalMatchers++;
+    }
+  } else {
+    console.error('ERROR: hooks.json must be an object or array');
+    process.exit(1);
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  console.log(`Validated ${totalMatchers} hook matchers`);
+}
+
+validateHooks();