@thanhvn14/csvibe 0.1.3 → 0.1.5

package/.github/agents/scripts/lib/parse-agent-file.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * Agent File Parser Library
+ * Shared parsing utilities for agent validators
+ */
+
+import { readFileSync } from 'fs';
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * @param {string} content - Full file content
+ * @returns {object|null} - Parsed frontmatter or null
+ * @throws {TypeError} If content is not a string
+ */
+export function parseFrontmatter(content) {
+  // Input validation
+  if (typeof content !== 'string') {
+    throw new TypeError('content must be a string');
+  }
+  if (!content.trim()) {
+    return null;
+  }
+
+  // Normalize line endings (Windows uses \r\n)
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+
+  // Simple YAML parser for our use case
+  const lines = yaml.split('\n');
+  let currentKey = null;
+  let currentArray = null;
+  let currentObject = null;
+  let arrayOfObjects = null;
+
+  for (const line of lines) {
+    // Skip comments
+    if (line.trim().startsWith('#')) continue;
+
+    // Check for key: value
+    const keyMatch = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (keyMatch) {
+      currentKey = keyMatch[1];
+      const value = keyMatch[2].trim();
+
+      // Check if value is inline array ['a', 'b']
+      if (value.startsWith('[')) {
+        const arrayMatch = value.match(/\[(.*)\]/);
+        if (arrayMatch) {
+          result[currentKey] = arrayMatch[1]
+            .split(',')
+            .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
+            .filter(s => s);
+        }
+        currentArray = null;
+        currentObject = null;
+        arrayOfObjects = null;
+      } else if (value === '') {
+        // Could be start of array or object
+        currentArray = currentKey;
+        result[currentKey] = [];
+        currentObject = null;
+        arrayOfObjects = null;
+      } else if (value.startsWith('{')) {
+        // Inline object
+        try {
+          result[currentKey] = JSON.parse(value.replace(/'/g, '"'));
+        } catch {
+          result[currentKey] = value;
+        }
+        currentArray = null;
+        currentObject = null;
+        arrayOfObjects = null;
+      } else {
+        result[currentKey] = value.replace(/^['"]|['"]$/g, '');
+        currentArray = null;
+        currentObject = null;
+        arrayOfObjects = null;
+      }
+    } else if (currentArray && line.match(/^\s+-\s+/)) {
+      // Array item - could be string or object
+      const itemLine = line.replace(/^\s+-\s+/, '').trim();
+
+      // Check if it's an object property (has key:)
+      const objKeyMatch = itemLine.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+      if (objKeyMatch) {
+        // Start of object in array
+        if (currentObject) {
+          result[currentArray].push(currentObject);
+        }
+        currentObject = {};
+        arrayOfObjects = currentArray;
+        const key = objKeyMatch[1];
+        const val = objKeyMatch[2].trim().replace(/^['"]|['"]$/g, '');
+        currentObject[key] = val;
+      } else {
+        // Simple string item
+        const item = itemLine.replace(/^['"]|['"]$/g, '');
+        if (item) result[currentArray].push(item);
+      }
+    } else if (arrayOfObjects && line.match(/^\s{2,}\w[\w-]*\s*:/)) {
+      // Continuation of object in array (indented property)
+      const propMatch = line.trim().match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+      if (propMatch && currentObject) {
+        const key = propMatch[1];
+        const val = propMatch[2].trim().replace(/^['"]|['"]$/g, '');
+        // Handle boolean values
+        if (val === 'true') currentObject[key] = true;
+        else if (val === 'false') currentObject[key] = false;
+        else currentObject[key] = val;
+      }
+    }
+  }
+
+  // Push last object if exists
+  if (currentObject && arrayOfObjects) {
+    result[arrayOfObjects].push(currentObject);
+  }
+
+  return result;
+}
+
+/**
+ * Extract markdown body (after frontmatter)
+ * @param {string} content - Full file content
+ * @returns {string} - Body content
+ */
+export function extractBody(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1].trim() : content;
+}
+
+/**
+ * Parse body into sections by H2/H3 headers
+ * @param {string} body - Markdown body
+ * @returns {Array<{level: number, title: string, content: string}>}
+ */
+export function parseBodySections(body) {
+  const sections = [];
+  const lines = body.split('\n');
+  let currentSection = null;
+
+  for (const line of lines) {
+    const h2Match = line.match(/^## (.+)$/);
+    const h3Match = line.match(/^### (.+)$/);
+
+    if (h2Match) {
+      if (currentSection) sections.push(currentSection);
+      currentSection = { level: 2, title: h2Match[1].trim(), content: '' };
+    } else if (h3Match) {
+      if (currentSection) sections.push(currentSection);
+      currentSection = { level: 3, title: h3Match[1].trim(), content: '' };
+    } else if (currentSection) {
+      currentSection.content += line + '\n';
+    }
+  }
+  if (currentSection) sections.push(currentSection);
+  return sections;
+}
+
+/**
+ * Extract write/read permission patterns from body
+ * @param {string} body - Markdown body
+ * @returns {{write: string[], readForbidden: string[]}}
+ */
+export function extractPermissions(body) {
+  const sections = parseBodySections(body);
+  const result = { write: [], readForbidden: [] };
+
+  // Find WRITE PERMISSIONS section
+  const writeSection = sections.find(s =>
+    s.title.includes('WRITE PERMISSION') ||
+    s.title.includes('PATH RESTRICTION')
+  );
+
+  if (writeSection) {
+    // Extract glob patterns from bullet points and backticks
+    const patterns = writeSection.content.match(/[`"]([^`"]+)[`"]/g) || [];
+    result.write = patterns.map(p => p.replace(/[`"]/g, ''));
+  }
+
+  // Find READ section for forbidden patterns
+  const readSection = sections.find(s =>
+    s.title.includes('READ') && s.title.includes('FORBIDDEN')
+  );
+  if (readSection) {
+    const forbidden = readSection.content.match(/[`"]([^`"]+)[`"]/g) || [];
+    result.readForbidden = forbidden.map(p => p.replace(/[`"]/g, ''));
+  }
+
+  return result;
+}
+
+/**
+ * Extract artifact paths mentioned in body
+ * @param {string} body - Markdown body
+ * @returns {string[]} - File path patterns
+ */
+export function extractArtifactPaths(body) {
+  // Find paths in artifacts JSON examples and bullet lists
+  const pathPatterns = [
+    /"path":\s*"([^"]+)"/g,  // JSON path fields
+    /`([a-zA-Z0-9_./-]+\.(md|json|yaml|yml))`/g,  // Backtick paths
+  ];
+
+  const paths = new Set();
+  for (const pattern of pathPatterns) {
+    const matches = body.matchAll(pattern);
+    for (const match of matches) {
+      paths.add(match[1]);
+    }
+  }
+  return [...paths];
+}
+
+/**
+ * Extract tool references from body
+ * @param {string} body - Markdown body
+ * @returns {string[]} - Tool names found
+ */
+export function extractToolReferences(body) {
+  // Match tool patterns: namespace/tool or standalone
+  const toolPatterns = [
+    /`((?:edit|search|read|web)\/\w+)`/g,  // namespaced
+    /`(readFile|fileSearch|textSearch|createFile|editFiles|listDirectory|fetch)`/g,  // common standalone
+  ];
+
+  const tools = new Set();
+  for (const pattern of toolPatterns) {
+    const matches = body.matchAll(pattern);
+    for (const match of matches) {
+      tools.add(match[1]);
+    }
+  }
+  return [...tools];
+}
+
+/**
+ * Read and parse an agent file
+ * @param {string} filePath - Path to .agent.md file
+ * @returns {object} - {frontmatter, body, sections, permissions, artifacts, toolRefs}
+ * @throws {Error} If path is invalid or outside allowed directory
+ */
+export function parseAgentFile(filePath) {
+  // Security: Validate file path to prevent traversal attacks
+  if (typeof filePath !== 'string' || !filePath.trim()) {
+    throw new TypeError('filePath must be a non-empty string');
+  }
+
+  if (!filePath.endsWith('.agent.md')) {
+    throw new Error('Invalid file type: must be .agent.md');
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+
+  const frontmatter = parseFrontmatter(content);
+  const body = extractBody(content);
+  const sections = parseBodySections(body);
+  const permissions = extractPermissions(body);
+  const artifacts = extractArtifactPaths(body);
+  const toolRefs = extractToolReferences(body);
+
+  return {
+    frontmatter,
+    body,
+    sections,
+    permissions,
+    artifacts,
+    toolRefs
+  };
+}

package/.github/agents/scripts/package-lock.json

@@ -0,0 +1,78 @@
+{
+  "name": "agent-validator",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "agent-validator",
+      "version": "1.0.0",
+      "dependencies": {
+        "adm-zip": "^0.5.16",
+        "ajv": "^8.12.0"
+      }
+    },
+    "node_modules/adm-zip": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.5.16.tgz",
+      "integrity": "sha512-TGw5yVi4saajsSEgz25grObGHEUaDrniwvA2qwSC060KfqGPdglhvPMA2lPIoxs3PQIItj2iag35fONcQqgUaQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.17.1",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
+      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "license": "MIT"
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    }
+  }
+}

package/.github/agents/scripts/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "agent-validator",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Agent output validation for CSVibe engine",
+  "scripts": {
+    "validate:output": "node validate-agent-output.js",
+    "validate:tools": "node validate-agent-tools.js",
+    "validate:frontmatter": "node validate-agent-frontmatter.js",
+    "validate:handoffs": "node validate-agent-handoffs.js",
+    "validate:all": "node validate-agent-all.js",
+    "validate": "node validate-agent-all.js",
+    "validate:strict": "node validate-agent-all.js --strict",
+    "validate:verbose": "node validate-agent-all.js --verbose",
+    "fetch:tools": "node fetch-copilot-tools.js",
+    "update:tools": "node fetch-copilot-tools.js --update --verbose"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "ajv": "^8.12.0"
+  }
+}

package/.github/agents/scripts/schemas/agent-frontmatter.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent-frontmatter.schema.json",
+  "title": "VSCode Copilot Agent Frontmatter",
+  "description": "Schema for .agent.md YAML frontmatter",
+  "type": "object",
+  "required": ["description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Agent display name (defaults to filename)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Brief description shown in chat input"
+    },
+    "tools": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Available tools for this agent"
+    },
+    "model": {
+      "type": "string",
+      "description": "AI model to use"
+    },
+    "target": {
+      "type": "string",
+      "enum": ["vscode", "github-copilot"],
+      "description": "Target environment"
+    },
+    "infer": {
+      "type": "boolean",
+      "default": true,
+      "description": "Allow agent as subagent"
+    },
+    "argument-hint": {
+      "type": "string",
+      "description": "Guidance text in chat input"
+    },
+    "handoffs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label", "agent"],
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Handoff button text"
+          },
+          "agent": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Target agent name"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Prompt to send"
+          },
+          "send": {
+            "type": "boolean",
+            "default": false,
+            "description": "Auto-submit prompt"
+          },
+          "input": {
+            "type": "string",
+            "description": "Input file path for the handoff"
+          }
+        },
+        "additionalProperties": true
+      },
+      "description": "Handoff buttons to other agents"
+    },
+    "mcp-servers": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "MCP server configuration"
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Unified Agent Validator
+ * Runs all validation scripts in sequence
+ *
+ * Usage:
+ *   node validate-agent-all.js              # Run all
+ *   node validate-agent-all.js --strict     # Treat warnings as errors
+ *   node validate-agent-all.js --json       # JSON output
+ *   node validate-agent-all.js --verbose    # Detailed output
+ */
+
+import { spawn } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Validators in execution order (only implemented ones)
+const VALIDATORS = [
+  {
+    name: 'Frontmatter Schema',
+    script: 'validate-agent-frontmatter.js',
+    critical: true
+  },
+  {
+    name: 'Tools',
+    script: 'validate-agent-tools.js',
+    critical: true
+  },
+  {
+    name: 'Handoffs',
+    script: 'validate-agent-handoffs.js',
+    critical: true
+  }
+];
+
+/**
+ * Run a validator script
+ */
+function runValidator(script, args) {
+  return new Promise((resolve) => {
+    const proc = spawn('node', [script, ...args], {
+      cwd: __dirname,
+      stdio: ['inherit', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+      if (!args.includes('--json')) {
+        process.stdout.write(data);
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+      if (!args.includes('--json')) {
+        process.stderr.write(data);
+      }
+    });
+
+    proc.on('close', (code) => {
+      resolve({ code, stdout, stderr });
+    });
+
+    proc.on('error', (err) => {
+      resolve({ code: 2, stdout: '', stderr: err.message });
+    });
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const strict = args.includes('--strict');
+  const jsonOutput = args.includes('--json');
+  const verbose = args.includes('--verbose');
+
+  // Filter args to pass to child validators
+  const childArgs = args.filter(a => ['--verbose', '--fix'].includes(a));
+
+  const results = {
+    timestamp: new Date().toISOString(),
+    validators: [],
+    summary: { passed: 0, failed: 0, warnings: 0 }
+  };
+
+  if (!jsonOutput) {
+    console.log('='.repeat(50));
+    console.log('Agent Validation Suite');
+    console.log('='.repeat(50));
+    console.log('');
+  }
+
+  let hasErrors = false;
+
+  for (const validator of VALIDATORS) {
+    if (!jsonOutput) {
+      console.log(`\n>>> ${validator.name}`);
+      console.log('-'.repeat(40));
+    }
+
+    const result = await runValidator(validator.script, childArgs);
+
+    const validatorResult = {
+      name: validator.name,
+      script: validator.script,
+      exitCode: result.code,
+      critical: validator.critical,
+      passed: result.code === 0
+    };
+
+    results.validators.push(validatorResult);
+
+    if (result.code === 0) {
+      results.summary.passed++;
+    } else if (validator.critical) {
+      results.summary.failed++;
+      hasErrors = true;
+    } else {
+      results.summary.warnings++;
+      if (strict) {
+        hasErrors = true;
+      }
+    }
+  }
+
+  // Summary
+  if (!jsonOutput) {
+    console.log('\n' + '='.repeat(50));
+    console.log('Summary');
+    console.log('='.repeat(50));
+    console.log(`Passed:   ${results.summary.passed}`);
+    console.log(`Failed:   ${results.summary.failed}`);
+    console.log(`Warnings: ${results.summary.warnings}`);
+    console.log('');
+
+    if (hasErrors) {
+      console.log('❌ Validation FAILED');
+    } else {
+      console.log('✅ Validation PASSED');
+    }
+  } else {
+    results.passed = !hasErrors;
+    console.log(JSON.stringify(results, null, 2));
+  }
+
+  process.exit(hasErrors ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(2);
+});