speccrew 0.6.69 → 0.7.0

package/lib/commands/validate.js

@@ -0,0 +1,565 @@
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceTemplatePath } = require('../utils');
+
+/**
+ * Validate command - Validates AgentFlow XML files
+ * Usage: speccrew validate [path] [--format json|text] [--strict]
+ */
+
+// Valid block types per specification
+const VALID_BLOCK_TYPES = [
+  'input',
+  'output',
+  'task',
+  'gateway',
+  'loop',
+  'event',
+  'error-handler',
+  'checkpoint',
+  'rule'
+];
+
+// Built-in variables that don't need prior definition
+const BUILTIN_VARIABLES = [
+  'workspace',
+  'platform',
+  'timestamp',
+  'workflow.id',
+  'workflow.status'
+];
+
+/**
+ * Get line number for a position in content
+ * @param {string} content - File content
+ * @param {number} position - Character position
+ * @returns {number} Line number (1-based)
+ */
+function getLineNumber(content, position) {
+  const lines = content.substring(0, position).split('\n');
+  return lines.length;
+}
+
+/**
+ * Extract all block elements from XML content
+ * @param {string} content - XML content
+ * @returns {Array} Array of block objects with metadata
+ */
+function extractBlocks(content) {
+  const blocks = [];
+  const blockRegex = /<block\s+([^>]+)>/g;
+  let match;
+
+  while ((match = blockRegex.exec(content)) !== null) {
+    const attrsString = match[1];
+    const startPos = match.index;
+    const line = getLineNumber(content, startPos);
+
+    // Parse attributes
+    const attrs = {};
+    const attrRegex = /(\w+)=["']([^"']*)["']/g;
+    let attrMatch;
+    while ((attrMatch = attrRegex.exec(attrsString)) !== null) {
+      attrs[attrMatch[1]] = attrMatch[2];
+    }
+
+    blocks.push({
+      line,
+      position: startPos,
+      attributes: attrs,
+      raw: match[0]
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * Extract branch elements from XML content
+ * @param {string} content - XML content
+ * @returns {Array} Array of branch objects
+ */
+function extractBranches(content) {
+  const branches = [];
+  const branchRegex = /<branch\s+([^>]*)>/g;
+  let match;
+
+  while ((match = branchRegex.exec(content)) !== null) {
+    const attrsString = match[1];
+    const line = getLineNumber(content, match.index);
+
+    const attrs = {};
+    const attrRegex = /(\w+)=["']([^"']*)["']/g;
+    let attrMatch;
+    while ((attrMatch = attrRegex.exec(attrsString)) !== null) {
+      attrs[attrMatch[1]] = attrMatch[2];
+    }
+
+    branches.push({
+      line,
+      attributes: attrs,
+      raw: match[0]
+    });
+  }
+
+  return branches;
+}
+
+/**
+ * Check if XML has proper structure
+ * @param {string} content - XML content
+ * @returns {Array} Array of error objects
+ */
+function validateXmlStructure(content) {
+  const errors = [];
+
+  // Check for workflow root element
+  const workflowMatch = content.match(/<workflow\s+[^>]*>/);
+  if (!workflowMatch) {
+    errors.push({
+      line: 1,
+      rule: 'root-element',
+      message: 'Missing root element <workflow>'
+    });
+  }
+
+  // Check for unclosed tags (basic check)
+  const openTags = content.match(/<block\s+[^>]*>/g) || [];
+  const closeTags = content.match(/<\/block>/g) || [];
+  const selfClosingBlocks = content.match(/<block\s+[^>]*\/>/g) || [];
+  const nonSelfClosingBlocks = openTags.length - selfClosingBlocks.length;
+
+  if (nonSelfClosingBlocks !== closeTags.length) {
+    errors.push({
+      line: 1,
+      rule: 'unclosed-tags',
+      message: `Block tag mismatch: ${openTags.length} opening, ${closeTags.length} closing tags`
+    });
+  }
+
+  // Check for unquoted attributes
+  const unquotedAttrRegex = /<block\s+[^>]*\w+=[^"'][^>]*>/g;
+  let match;
+  while ((match = unquotedAttrRegex.exec(content)) !== null) {
+    const line = getLineNumber(content, match.index);
+    errors.push({
+      line,
+      rule: 'unquoted-attribute',
+      message: 'Attribute values must be quoted'
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Validate block types
+ * @param {Array} blocks - Extracted blocks
+ * @returns {Array} Array of error objects
+ */
+function validateBlockTypes(blocks) {
+  const errors = [];
+
+  for (const block of blocks) {
+    const type = block.attributes.type;
+    if (!type) {
+      errors.push({
+        line: block.line,
+        rule: 'missing-type',
+        message: 'Block is missing required "type" attribute'
+      });
+    } else if (!VALID_BLOCK_TYPES.includes(type)) {
+      errors.push({
+        line: block.line,
+        rule: 'invalid-type',
+        message: `Invalid block type "${type}". Valid types: ${VALID_BLOCK_TYPES.join(', ')}`
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate block ID uniqueness
+ * @param {Array} blocks - Extracted blocks
+ * @returns {Array} Array of error objects
+ */
+function validateUniqueIds(blocks) {
+  const errors = [];
+  const idMap = new Map();
+
+  for (const block of blocks) {
+    const id = block.attributes.id;
+    if (id) {
+      if (idMap.has(id)) {
+        errors.push({
+          line: block.line,
+          rule: 'unique-id',
+          message: `Duplicate block id "${id}" (first defined at line ${idMap.get(id)})`
+        });
+      } else {
+        idMap.set(id, block.line);
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate required attributes for each block type
+ * @param {Array} blocks - Extracted blocks
+ * @returns {Array} Array of error objects
+ */
+function validateRequiredAttributes(blocks) {
+  const errors = [];
+
+  for (const block of blocks) {
+    const type = block.attributes.type;
+    const id = block.attributes.id;
+
+    // All blocks must have id
+    if (!id) {
+      errors.push({
+        line: block.line,
+        rule: 'missing-id',
+        message: 'Block is missing required "id" attribute'
+      });
+    }
+
+    // Type-specific required attributes
+    if (type === 'task') {
+      if (!block.attributes.action) {
+        errors.push({
+          line: block.line,
+          rule: 'missing-action',
+          message: 'Task block is missing required "action" attribute'
+        });
+      }
+      if (!block.attributes.desc) {
+        errors.push({
+          line: block.line,
+          rule: 'missing-desc',
+          message: 'Task block is missing required "desc" attribute'
+        });
+      }
+    }
+
+    if (type === 'input' || type === 'output') {
+      if (!block.attributes.desc) {
+        errors.push({
+          line: block.line,
+          rule: 'missing-desc',
+          message: `${type} block is missing required "desc" attribute`
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate next references
+ * @param {string} content - XML content
+ * @param {Array} blocks - Extracted blocks
+ * @returns {Array} Array of error objects
+ */
+function validateNextReferences(content, blocks) {
+  const errors = [];
+  const validIds = new Set(blocks.map(b => b.attributes.id).filter(Boolean));
+
+  // Check field name="next" references
+  const fieldRegex = /<field\s+name=["']next["'][^>]*>([^<]*)<\/field>/g;
+  let match;
+
+  while ((match = fieldRegex.exec(content)) !== null) {
+    const nextId = match[1].trim();
+    const line = getLineNumber(content, match.index);
+
+    if (nextId && !validIds.has(nextId)) {
+      errors.push({
+        line,
+        rule: 'invalid-next-ref',
+        message: `Reference to undefined block id "${nextId}"`
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate variable references
+ * @param {string} content - XML content
+ * @param {Array} blocks - Extracted blocks
+ * @returns {Array} Array of warning objects
+ */
+function validateVariableRefs(content, blocks) {
+  const warnings = [];
+  const definedVars = new Set(BUILTIN_VARIABLES);
+
+  // Collect output variables from blocks
+  for (const block of blocks) {
+    const blockEndPos = content.indexOf('</block>', block.position);
+    const blockContent = content.substring(block.position, blockEndPos > 0 ? blockEndPos : block.position + 500);
+
+    // Check for output var attribute
+    const outputMatch = blockContent.match(/<field[^>]*\s+var=["']([^"']+)["']/);
+    if (outputMatch) {
+      definedVars.add(outputMatch[1]);
+    }
+
+    // Check for output field in task blocks
+    const outputFieldMatch = blockContent.match(/<field\s+name=["']output["'][^>]*\s+var=["']([^"']+)["']/);
+    if (outputFieldMatch) {
+      definedVars.add(outputFieldMatch[1]);
+    }
+
+    // Loop variables
+    if (block.attributes.type === 'loop') {
+      const asAttr = block.attributes.as;
+      if (asAttr) {
+        definedVars.add(asAttr);
+      }
+    }
+  }
+
+  // Check all variable references
+  const varRegex = /\$\{([^}]+)\}/g;
+  let match;
+
+  while ((match = varRegex.exec(content)) !== null) {
+    const fullVar = match[1];
+    const baseVar = fullVar.split('.')[0].split('[')[0];
+    const line = getLineNumber(content, match.index);
+
+    if (!definedVars.has(baseVar) && !BUILTIN_VARIABLES.includes(baseVar)) {
+      const parentVar = fullVar.split('.')[0];
+      if (!definedVars.has(parentVar)) {
+        warnings.push({
+          line,
+          rule: 'var-ref',
+          message: `Variable "${baseVar}" may not be defined before use`
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Validate a single AgentFlow XML file
+ * @param {string} filePath - Path to the XML file
+ * @returns {Object} Validation result
+ */
+function validateFile(filePath) {
+  const result = {
+    file: filePath,
+    errors: [],
+    warnings: [],
+    summary: {
+      blocks: 0,
+      errors: 0,
+      warnings: 0
+    }
+  };
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Extract all blocks
+    const blocks = extractBlocks(content);
+    result.summary.blocks = blocks.length;
+
+    // Run all validations
+    result.errors.push(...validateXmlStructure(content));
+    result.errors.push(...validateBlockTypes(blocks));
+    result.errors.push(...validateUniqueIds(blocks));
+    result.errors.push(...validateRequiredAttributes(blocks));
+    result.errors.push(...validateNextReferences(content, blocks));
+    result.warnings.push(...validateVariableRefs(content, blocks));
+
+    // Update summary
+    result.summary.errors = result.errors.length;
+    result.summary.warnings = result.warnings.length;
+
+  } catch (error) {
+    result.errors.push({
+      line: 0,
+      rule: 'file-error',
+      message: `Failed to read file: ${error.message}`
+    });
+    result.summary.errors = 1;
+  }
+
+  return result;
+}
+
+/**
+ * Find all .agentflow.xml files in a directory recursively
+ * @param {string} dir - Directory to search
+ * @returns {Array} Array of file paths
+ */
+function findAgentFlowFiles(dir) {
+  const files = [];
+
+  function scan(directory) {
+    if (!fs.existsSync(directory)) return;
+
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        scan(fullPath);
+      } else if (entry.name.endsWith('.agentflow.xml')) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  scan(dir);
+  return files;
+}
+
+/**
+ * Parse command arguments
+ * @param {Array} args - Command arguments
+ * @returns {Object} Parsed options
+ */
+function parseOptions(args) {
+  const options = {
+    format: 'text',
+    strict: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--format' && i + 1 < args.length) {
+      options.format = args[i + 1];
+      i++;
+    } else if (arg === '--strict') {
+      options.strict = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Format output as text
+ * @param {Array} results - Validation results
+ * @param {boolean} strict - Treat warnings as errors
+ * @returns {string} Formatted text output
+ */
+function formatTextOutput(results, strict) {
+  const lines = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalBlocks = 0;
+
+  for (const result of results) {
+    lines.push('');
+    lines.push(result.file);
+
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+      lines.push('  PASS  No issues found');
+    } else {
+      for (const error of result.errors) {
+        lines.push(`  ERROR  Line ${error.line}: [${error.rule}] ${error.message}`);
+      }
+      for (const warning of result.warnings) {
+        const label = strict ? 'ERROR' : 'WARN';
+        lines.push(`  ${label}   Line ${warning.line}: [${warning.rule}] ${warning.message}`);
+      }
+    }
+
+    totalErrors += result.summary.errors;
+    totalWarnings += result.summary.warnings;
+    totalBlocks += result.summary.blocks;
+  }
+
+  lines.push('');
+  lines.push('─'.repeat(50));
+  lines.push(`Summary: ${results.length} file(s), ${totalBlocks} block(s), ${totalErrors} error(s), ${totalWarnings} warning(s)`);
+
+  if (strict) {
+    const totalIssues = totalErrors + totalWarnings;
+    lines.push(`Strict mode: ${totalIssues} total issue(s)`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Main run function
+ * @param {string} projectRoot - Project root directory
+ * @param {Array} args - Command arguments
+ */
+function run(projectRoot, args) {
+  console.log('SpecCrew AgentFlow Validator\n');
+
+  const options = parseOptions(args);
+
+  // Determine target path
+  let targetPath = null;
+  for (const arg of args) {
+    if (!arg.startsWith('--')) {
+      targetPath = arg;
+      break;
+    }
+  }
+
+  // Default to speccrew-workspace
+  if (!targetPath) {
+    targetPath = path.join(projectRoot, 'speccrew-workspace');
+  } else {
+    targetPath = path.resolve(projectRoot, targetPath);
+  }
+
+  // Check if target exists
+  if (!fs.existsSync(targetPath)) {
+    console.error(`Error: Path not found: ${targetPath}`);
+    process.exit(1);
+  }
+
+  // Collect files to validate
+  let files = [];
+  const stats = fs.statSync(targetPath);
+  if (stats.isDirectory()) {
+    files = findAgentFlowFiles(targetPath);
+  } else if (targetPath.endsWith('.agentflow.xml')) {
+    files = [targetPath];
+  }
+
+  if (files.length === 0) {
+    console.log(`No .agentflow.xml files found in ${targetPath}`);
+    return true;
+  }
+
+  // Validate all files
+  const results = files.map(file => validateFile(file));
+
+  // Calculate totals
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  for (const result of results) {
+    totalErrors += result.summary.errors;
+    totalWarnings += result.summary.warnings;
+  }
+
+  // Output results
+  if (options.format === 'json') {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatTextOutput(results, options.strict));
+  }
+
+  // Return success/failure
+  const hasErrors = totalErrors > 0 || (options.strict && totalWarnings > 0);
+  return !hasErrors;
+}
+
+module.exports = { run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.6.69",
+  "version": "0.7.0",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {

package/workspace-template/docs/rules/{xml-workflow-spec.md → agentflow-spec.md}

@@ -1,6 +1,6 @@
-# XML Workflow Specification
+# AgentFlow Specification
 
-> This document defines the XML Block workflow format used in SpecCrew skill and agent definitions.
+> This document defines the AgentFlow XML Block workflow format used in SpecCrew skill and agent definitions.
 > **MANDATORY**: Any agent or worker that encounters XML `<workflow>` blocks MUST read and understand this specification before execution.
 
 ## Execution Model
@@ -346,7 +346,7 @@ Dispatch skills (naming pattern: `*-dispatch-xml`) are **orchestration playbooks
 When Team Leader loads a dispatch skill via `action="run-skill"`:
 
 1. **Load**: Team Leader invokes the Skill tool with the dispatch skill name (e.g., `speccrew-knowledge-bizs-dispatch-xml`)
-2. **Parse**: Read and understand the complete XML workflow in the loaded SKILL.md
+2. **Parse**: Read and understand the complete AgentFlow XML workflow in the loaded SKILL.md
 3. **Execute block-by-block**: Walk through each Stage's blocks in document order, mapping each `action` attribute to the correct IDE tool:
 
 | Block Action | What Team Leader MUST Do |
@@ -484,7 +484,7 @@ Team Leader executes:
 
 ### Strict Block Adherence
 
-When executing an XML workflow, the Agent MUST strictly follow the block sequence defined in the workflow:
+When executing an AgentFlow XML workflow, the Agent MUST strictly follow the block sequence defined in the workflow:
 
 1. **Only perform actions defined by blocks** — Every action the Agent takes must correspond to a specific block in the workflow. The Agent MUST NOT perform any actions not defined by the blocks.
 2. **Prohibited extra actions** include but are not limited to:
@@ -509,5 +509,5 @@ Before executing each `<block>`, the agent MUST announce the block being execute
 3. For `<block type="loop">` blocks, announce the loop entry with iteration context (e.g., "Loop [S2-L2] — Iterating over ${batch}, 5 items, parallel=true").
 4. For `<block type="checkpoint">` blocks, announce the checkpoint and its validation result.
 5. For `<block type="rule">` blocks, announce the rule being applied.
-6. This protocol applies to ALL agents executing XML workflows — both orchestrating agents (Team Leader) and worker agents.
+6. This protocol applies to ALL agents executing AgentFlow XML workflows — both orchestrating agents (Team Leader) and worker agents.
 7. Nested blocks inside loops should also be announced for each iteration.