@thanhvn14/csvibe 0.1.3 → 0.1.5

package/.github/agents/scripts/validate-agent-frontmatter.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Agent Frontmatter Validator
+ * Validates YAML frontmatter against JSON Schema
+ *
+ * Usage:
+ *   node validate-agent-frontmatter.js
+ *   node validate-agent-frontmatter.js --verbose
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import Ajv from 'ajv';
+import { parseFrontmatter } from './lib/parse-agent-file.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load schema
+const schema = JSON.parse(
+  readFileSync(join(__dirname, 'schemas/agent-frontmatter.schema.json'), 'utf8')
+);
+
+// Initialize validator
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile(schema);
+
+function validateAgentFile(filePath, verbose) {
+  const content = readFileSync(filePath, 'utf8');
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    return { file: filePath, skipped: true, reason: 'No frontmatter' };
+  }
+
+  const valid = validate(frontmatter);
+
+  return {
+    file: filePath,
+    agent: frontmatter.name || filePath.split(/[/\\]/).pop().replace('.agent.md', ''),
+    valid,
+    errors: valid ? [] : validate.errors.map(e => ({
+      path: e.instancePath || '/',
+      message: e.message,
+      params: e.params
+    }))
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const verbose = args.includes('--verbose');
+
+  const agentsDir = resolve(__dirname, '..');
+  const files = readdirSync(agentsDir)
+    .filter(f => f.endsWith('.agent.md'))
+    .map(f => join(agentsDir, f));
+
+  if (files.length === 0) {
+    console.log('No agent files found');
+    process.exit(0);
+  }
+
+  console.log(`Validating frontmatter in ${files.length} file(s)...\n`);
+
+  let hasErrors = false;
+  for (const file of files) {
+    const result = validateAgentFile(file, verbose);
+
+    if (result.skipped) {
+      console.log(`⚠️  ${file.split(/[/\\]/).pop()} - skipped (${result.reason})`);
+      continue;
+    }
+
+    if (result.valid) {
+      console.log(`✅ ${result.agent}`);
+    } else {
+      console.log(`❌ ${result.agent}`);
+      hasErrors = true;
+      for (const err of result.errors) {
+        console.log(`   • ${err.path}: ${err.message}`);
+      }
+    }
+  }
+
+  console.log('\n---');
+  process.exit(hasErrors ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+export { validateAgentFile };

package/.github/agents/scripts/validate-agent-handoffs.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Agent Handoffs Validator
+ * Validates cross-references between agents
+ *
+ * Usage:
+ *   node validate-agent-handoffs.js
+ *   node validate-agent-handoffs.js --verbose
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseFrontmatter } from './lib/parse-agent-file.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function buildAgentMap(agentsDir) {
+  const files = readdirSync(agentsDir).filter(f => f.endsWith('.agent.md'));
+  const map = new Map();
+
+  for (const file of files) {
+    const name = file.replace('.agent.md', '');
+    const content = readFileSync(join(agentsDir, file), 'utf8');
+    const fm = parseFrontmatter(content);
+
+    if (!fm) continue; // Skip files without frontmatter
+
+    map.set(name, {
+      file,
+      name: fm?.name || name,
+      handoffs: fm?.handoffs || []
+    });
+  }
+  return map;
+}
+
+function detectCircular(agentMap, startAgent, visited = new Set(), path = []) {
+  if (visited.has(startAgent)) {
+    return [...path, startAgent]; // Circular detected
+  }
+
+  const agent = agentMap.get(startAgent);
+  if (!agent) return null;
+
+  visited.add(startAgent);
+  path.push(startAgent);
+
+  for (const handoff of agent.handoffs) {
+    const circular = detectCircular(agentMap, handoff.agent, new Set(visited), [...path]);
+    if (circular) return circular;
+  }
+
+  return null;
+}
+
+function validateHandoffs(agentMap, verbose) {
+  const results = [];
+
+  for (const [name, agent] of agentMap) {
+    const errors = [];
+    const warnings = [];
+
+    for (const handoff of agent.handoffs) {
+      const targetName = handoff.agent;
+
+      // Check if target exists
+      if (!agentMap.has(targetName)) {
+        errors.push({
+          type: 'missing',
+          message: `Agent '${targetName}' not found`,
+          handoff: handoff.label
+        });
+        continue;
+      }
+
+      // Check self-reference
+      if (targetName === name) {
+        warnings.push({
+          type: 'self-reference',
+          message: `Hands off to itself`,
+          handoff: handoff.label
+        });
+      }
+    }
+
+    // Check circular references
+    const circular = detectCircular(agentMap, name);
+    if (circular && circular.length > 2) {
+      warnings.push({
+        type: 'circular',
+        message: `Circular: ${circular.join(' → ')}`,
+        handoff: 'chain'
+      });
+    }
+
+    results.push({
+      agent: agent.name,
+      file: agent.file,
+      handoffCount: agent.handoffs.length,
+      errors,
+      warnings,
+      valid: errors.length === 0
+    });
+  }
+
+  return results;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const verbose = args.includes('--verbose');
+
+  const agentsDir = resolve(__dirname, '..');
+  const agentMap = buildAgentMap(agentsDir);
+
+  if (agentMap.size === 0) {
+    console.log('No agent files found');
+    process.exit(0);
+  }
+
+  console.log(`Validating handoffs in ${agentMap.size} agent(s)...\n`);
+
+  const results = validateHandoffs(agentMap, verbose);
+
+  let hasErrors = false;
+  for (const result of results) {
+    if (result.handoffCount === 0) {
+      if (verbose) console.log(`⚪ ${result.agent} (no handoffs)`);
+      continue;
+    }
+
+    if (result.valid && result.warnings.length === 0) {
+      console.log(`✅ ${result.agent} (${result.handoffCount} handoffs)`);
+    } else if (result.valid) {
+      console.log(`⚠️  ${result.agent}`);
+      for (const w of result.warnings) {
+        console.log(`   ⚠ ${w.message}`);
+      }
+    } else {
+      console.log(`❌ ${result.agent}`);
+      hasErrors = true;
+      for (const e of result.errors) {
+        console.log(`   • ${e.handoff}: ${e.message}`);
+      }
+      for (const w of result.warnings) {
+        console.log(`   ⚠ ${w.message}`);
+      }
+    }
+  }
+
+  console.log('\n---');
+  const errorCount = results.filter(r => !r.valid).length;
+  if (errorCount > 0) {
+    console.log(`❌ ${errorCount} agent(s) have invalid handoffs`);
+    process.exit(1);
+  } else {
+    console.log('✅ All handoff references valid');
+    process.exit(0);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+export { buildAgentMap, validateHandoffs };

package/.github/agents/scripts/validate-agent-output.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Agent Output Validator
+ *
+ * Validates agent JSON output against schema with path pattern enforcement.
+ *
+ * Usage:
+ *   echo '{"agent":"scout",...}' | node validate-agent-output.js
+ *   node validate-agent-output.js --input output.json
+ *   node validate-agent-output.js --input output.json --verbose
+ *
+ * Exit codes:
+ *   0 - Validation passed
+ *   1 - Validation failed
+ */
+
+import Ajv from 'ajv';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Parse CLI arguments
+function parseArgs(args) {
+  const parsed = { input: null, verbose: false };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--input' && args[i + 1]) {
+      parsed.input = args[i + 1];
+      i++;
+    } else if (args[i] === '--verbose') {
+      parsed.verbose = true;
+    }
+  }
+
+  return parsed;
+}
+
+// Read from stdin
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => data += chunk);
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+// Path patterns for each agent
+const pathPatterns = {
+  scout: /^(plans\/reports\/scout-|\.csvibe\/state\/scout-).*$/,
+  brainstorm: /^(plans\/reports\/brainstorm-|\.csvibe\/state\/approaches).*$/
+};
+
+// Main validation function
+async function validate() {
+  const args = parseArgs(process.argv.slice(2));
+
+  try {
+    // Read input
+    const input = args.input
+      ? readFileSync(args.input, 'utf8')
+      : await readStdin();
+
+    if (!input || !input.trim()) {
+      console.error('Error: No input provided');
+      process.exit(1);
+    }
+
+    // Parse JSON
+    let output;
+    try {
+      output = JSON.parse(input);
+    } catch (err) {
+      console.error('Error: Invalid JSON');
+      if (args.verbose) console.error(err.message);
+      process.exit(1);
+    }
+
+    // Extract agent name
+    const agent = output.agent;
+    if (!agent) {
+      console.error('Error: Missing "agent" field in output');
+      process.exit(1);
+    }
+
+    // Load schema
+    const schemaPath = resolve(__dirname, `../schemas/${agent}-output.schema.json`);
+    let schema;
+    try {
+      schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+    } catch (err) {
+      console.error(`Error: Failed to load schema for agent "${agent}"`);
+      if (args.verbose) console.error(err.message);
+      process.exit(1);
+    }
+
+    // Load base schema if needed (for $ref support)
+    const baseSchemaPath = resolve(__dirname, '../schemas/base-output.schema.json');
+    const baseSchema = JSON.parse(readFileSync(baseSchemaPath, 'utf8'));
+
+    // Validate against schema
+    const ajv = new Ajv({
+      strict: false,
+      validateSchema: false,
+      allowUnionTypes: true
+    });
+
+    // Add base schema to Ajv instance
+    ajv.addSchema(baseSchema);
+
+    const validateSchema = ajv.compile(schema);
+
+    if (!validateSchema(output)) {
+      console.error('Schema validation failed:');
+      console.error(JSON.stringify(validateSchema.errors, null, 2));
+      process.exit(1);
+    }
+
+    // Extra path validation for artifacts
+    if (output.artifacts && Array.isArray(output.artifacts)) {
+      const pattern = pathPatterns[agent];
+
+      if (!pattern) {
+        console.error(`Warning: No path pattern defined for agent "${agent}"`);
+      } else {
+        for (const artifact of output.artifacts) {
+          if (artifact.path && !pattern.test(artifact.path)) {
+            console.error(`Invalid artifact path: ${artifact.path}`);
+            console.error(`Agent "${agent}" can only write to patterns matching: ${pattern}`);
+            process.exit(1);
+          }
+        }
+      }
+    }
+
+    // Success
+    console.log('Validation passed');
+    if (args.verbose) {
+      console.log(`Agent: ${agent}`);
+      console.log(`Artifacts: ${output.artifacts?.length || 0}`);
+    }
+    process.exit(0);
+
+  } catch (err) {
+    console.error('Unexpected error:', err.message);
+    if (args.verbose) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+// Run validation
+validate();

package/.github/agents/scripts/validate-agent-tools.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * Agent Tools Validator
+ *
+ * Validates that all tools specified in agent .agent.md files are valid
+ * VSCode Copilot tools.
+ *
+ * Usage:
+ *   node validate-agent-tools.js
+ *   node validate-agent-tools.js --verbose
+ *   node validate-agent-tools.js --fix (show suggestions)
+ *
+ * Exit codes:
+ *   0 - All tools valid
+ *   1 - Invalid tools found
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseFrontmatter } from './lib/parse-agent-file.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Valid VSCode Copilot Chat tools (as of 2026-01-18)
+// Source: github.copilot-chat extension package.json (languageModelTools)
+// Auto-updated from github.copilot-chat-0.37.2026011603
+const VALID_TOOLS = {
+  // Tool sets (groups) - these expand to multiple tools
+  toolSets: ["edit","search","read","web"],
+
+  // Namespaced tools (namespace/tool format)
+  namespaced: [
+      "edit/createFile",
+      "edit/createDirectory",
+      "edit/editFiles",
+      "edit/editNotebook",
+      "edit/insertEdit",
+      "edit/replaceString",
+      "edit/multiReplaceString",
+      "edit/applyPatch",
+      "search/fileSearch",
+      "search/textSearch",
+      "search/usages",
+      "search/codebase",
+      "search/symbols",
+      "read/readFile",
+      "read/listDirectory",
+      "web/fetch",
+      "web/githubRepo"
+  ],
+
+  // Standalone tools (from package.json toolReferenceName)
+  standalone: [
+      "codebase",
+      "searchSubagent",
+      "symbols",
+      "usages",
+      "vscodeAPI",
+      "fileSearch",
+      "textSearch",
+      "applyPatch",
+      "readFile",
+      "listDirectory",
+      "problems",
+      "changes",
+      "testFailure",
+      "updateUserPreferences",
+      "newWorkspace",
+      "getProjectSetupInfo",
+      "installExtension",
+      "runCommand",
+      "createJupyterNotebook",
+      "insertEdit",
+      "createFile",
+      "createDirectory",
+      "openSimpleBrowser",
+      "replaceString",
+      "multiReplaceString",
+      "editNotebook",
+      "runNotebookCell",
+      "getNotebookSummary",
+      "readNotebookCellOutput",
+      "fetch",
+      "findTestFiles",
+      "docInfo",
+      "searchResults",
+      "githubRepo",
+      "memory",
+      "editFiles"
+  ],
+
+  // Deprecated/renamed tools (for helpful error messages)
+  deprecated: {
+      "glob": "search/fileSearch",
+      "grep": "search/textSearch"
+  }
+};
+
+// Build flat set of all valid tools
+function buildValidToolSet() {
+  const valid = new Set();
+
+  // Add tool sets
+  VALID_TOOLS.toolSets.forEach(ts => valid.add(ts));
+
+  // Add namespaced tools
+  Object.keys(VALID_TOOLS).forEach(key => {
+    if (Array.isArray(VALID_TOOLS[key])) {
+      VALID_TOOLS[key].forEach(tool => valid.add(tool));
+    }
+  });
+
+  return valid;
+}
+
+// Validate a single agent file
+function validateAgentFile(filePath, validTools, verbose) {
+  const content = readFileSync(filePath, 'utf8');
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    return { file: filePath, error: 'No frontmatter found' };
+  }
+
+  const agentName = frontmatter.name || 'unknown';
+  const tools = frontmatter.tools || [];
+
+  const errors = [];
+  const warnings = [];
+
+  for (const tool of tools) {
+    if (!validTools.has(tool)) {
+      // Check if it's a deprecated tool
+      if (VALID_TOOLS.deprecated[tool]) {
+        errors.push({
+          tool,
+          message: `Tool '${tool}' has been renamed to '${VALID_TOOLS.deprecated[tool]}'`,
+          suggestion: VALID_TOOLS.deprecated[tool]
+        });
+      } else {
+        errors.push({
+          tool,
+          message: `Unknown tool '${tool}'`,
+          suggestion: findSimilarTool(tool, validTools)
+        });
+      }
+    }
+  }
+
+  return {
+    file: filePath,
+    agent: agentName,
+    tools,
+    errors,
+    warnings,
+    valid: errors.length === 0
+  };
+}
+
+// Find similar tool name (simple Levenshtein-like matching)
+function findSimilarTool(tool, validTools) {
+  const toolLower = tool.toLowerCase();
+
+  for (const valid of validTools) {
+    if (valid.toLowerCase().includes(toolLower) || toolLower.includes(valid.toLowerCase())) {
+      return valid;
+    }
+  }
+
+  // Check if adding namespace helps
+  const namespaces = ['edit', 'search', 'read', 'web'];
+  for (const ns of namespaces) {
+    const namespaced = `${ns}/${tool}`;
+    if (validTools.has(namespaced)) {
+      return namespaced;
+    }
+  }
+
+  return null;
+}
+
+// Main function
+async function main() {
+  const args = process.argv.slice(2);
+  const verbose = args.includes('--verbose');
+  const showFix = args.includes('--fix');
+
+  const validTools = buildValidToolSet();
+  const agentsDir = resolve(__dirname, '..');
+
+  // Find all .agent.md files
+  const files = readdirSync(agentsDir)
+    .filter(f => f.endsWith('.agent.md'))
+    .map(f => join(agentsDir, f));
+
+  if (files.length === 0) {
+    console.log('No agent files found in', agentsDir);
+    process.exit(0);
+  }
+
+  console.log(`Validating ${files.length} agent file(s)...\n`);
+
+  let hasErrors = false;
+  const results = [];
+
+  for (const file of files) {
+    const result = validateAgentFile(file, validTools, verbose);
+    results.push(result);
+
+    if (result.error) {
+      // Skip files without frontmatter (they're not VSCode agent files)
+      if (result.error === 'No frontmatter found') {
+        console.log(`\u26A0\uFE0F  ${result.file.split(/[/\\]/).pop()} - skipped (no YAML frontmatter)`);
+      } else {
+        console.log(`\u274C ${result.file}`);
+        console.log(`   Error: ${result.error}`);
+        hasErrors = true;
+      }
+      console.log('');
+      continue;
+    }
+
+    if (result.valid) {
+      console.log(`\u2705 ${result.agent} (${result.tools.length} tools)`);
+      if (verbose) {
+        console.log(`   Tools: ${result.tools.join(', ')}`);
+      }
+    } else {
+      console.log(`\u274C ${result.agent}`);
+      hasErrors = true;
+
+      for (const err of result.errors) {
+        console.log(`   \u2022 ${err.message}`);
+        if (showFix && err.suggestion) {
+          console.log(`     \u2192 Suggestion: use '${err.suggestion}'`);
+        }
+      }
+    }
+    console.log('');
+  }
+
+  // Summary
+  console.log('---');
+  // Only count files that have frontmatter (actual VSCode agent files)
+  const agentFiles = results.filter(r => !r.error || r.error !== 'No frontmatter found');
+  const skippedCount = results.length - agentFiles.length;
+  const validCount = agentFiles.filter(r => r.valid).length;
+  const invalidCount = agentFiles.filter(r => !r.valid && r.errors?.length > 0).length;
+
+  if (skippedCount > 0) {
+    console.log(`Skipped ${skippedCount} file(s) without YAML frontmatter`);
+  }
+
+  if (invalidCount > 0) {
+    console.log(`\u274C ${invalidCount}/${agentFiles.length} agent(s) have invalid tools`);
+    if (!showFix) {
+      console.log('   Run with --fix to see suggestions');
+    }
+    process.exit(1);
+  } else if (agentFiles.length > 0) {
+    console.log(`\u2705 All ${validCount} agent(s) have valid tools`);
+    process.exit(0);
+  } else {
+    console.log('No valid VSCode agent files found (with YAML frontmatter)');
+    process.exit(0);
+  }
+}
+
+// Export for testing
+export { VALID_TOOLS, buildValidToolSet };
+
+// Run
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});