@paths.design/caws-cli 3.5.0 → 4.1.0

package/dist/index-new.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview CAWS CLI - Scaffolding tool for Coding Agent Workflow System
+ * Provides commands to initialize new projects and scaffold existing ones with CAWS
+ * @author @darianrosebrook
+ */
+
+const { Command } = require('commander');
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+
+// Import configuration and utilities
+const {
+  CLI_VERSION,
+  initializeGlobalSetup,
+  loadProvenanceTools,
+  initializeLanguageSupport,
+} = require('./config');
+
+// Import command handlers
+const { initProject } = require('./commands/init');
+
+// Import scaffold functionality
+const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
+
+// Import validation functionality
+const { validateWorkingSpecWithSuggestions } = require('./validation/spec-validation');
+
+// Import finalization utilities
+const {
+  finalizeProject,
+  continueToSuccess,
+  setFinalizationDependencies,
+} = require('./utils/finalization');
+
+// Import generators
+const { generateWorkingSpec, validateGeneratedSpec } = require('./generators/working-spec');
+
+// Import tool system
+const ToolLoader = require('./tool-loader');
+const ToolValidator = require('./tool-validator');
+
+// Initialize global configuration
+const program = new Command();
+
+// Initialize global state
+const cawsSetup = initializeGlobalSetup();
+const languageSupport = initializeLanguageSupport();
+
+// Set up dependencies for modules that need them
+setScaffoldDependencies({
+  cawsSetup,
+  loadProvenanceTools,
+});
+
+setFinalizationDependencies({
+  languageSupport,
+  loadProvenanceTools,
+});
+
+// Tool system state
+let toolLoader = null;
+let toolValidator = null;
+
+/**
+ * Initialize tool system
+ */
+async function initializeToolSystem() {
+  if (toolLoader) return toolLoader;
+
+  try {
+    toolLoader = new ToolLoader({
+      toolsDir: path.join(process.cwd(), 'apps/tools/caws'),
+    });
+
+    toolValidator = new ToolValidator();
+
+    // Set up event listeners for tool system
+    toolLoader.on('discovery:complete', ({ tools: _tools, count }) => {
+      if (count > 0) {
+        console.log(chalk.blue(`🔧 Discovered ${count} tools`));
+      }
+    });
+
+    toolLoader.on('tool:loaded', ({ id, metadata }) => {
+      console.log(chalk.gray(`  ✓ Loaded tool: ${metadata.name} (${id})`));
+    });
+
+    toolLoader.on('tool:error', ({ id, error }) => {
+      console.warn(chalk.yellow(`⚠️  Failed to load tool ${id}: ${error}`));
+    });
+
+    // Auto-discover tools on initialization
+    await toolLoader.discoverTools();
+
+    return toolLoader;
+  } catch (error) {
+    console.warn(chalk.yellow('⚠️  Tool system initialization failed:'), error.message);
+    console.warn(chalk.blue('💡 Continuing without dynamic tools'));
+    return null;
+  }
+}
+
+/**
+ * Validate command handler
+ */
+async function validateCommand(specFile, options) {
+  try {
+    let specPath = specFile || path.join('.caws', 'working-spec.yaml');
+
+    if (!fs.existsSync(specPath)) {
+      console.error(chalk.red(`❌ Spec file not found: ${specPath}`));
+      console.error(chalk.blue('💡 Run "caws init" first to create a working spec'));
+      process.exit(1);
+    }
+
+    const specContent = fs.readFileSync(specPath, 'utf8');
+    const spec = yaml.load(specContent);
+
+    console.log(chalk.cyan('🔍 Validating CAWS working spec...'));
+
+    const result = validateWorkingSpecWithSuggestions(spec, {
+      autoFix: options.autoFix,
+      suggestions: !options.quiet,
+    });
+
+    if (result.valid) {
+      console.log(chalk.green('✅ Working spec validation passed'));
+      if (!options.quiet) {
+        console.log(chalk.gray(`   Risk tier: ${spec.risk_tier}`));
+        console.log(chalk.gray(`   Mode: ${spec.mode}`));
+        if (spec.title) {
+          console.log(chalk.gray(`   Title: ${spec.title}`));
+        }
+      }
+    } else {
+      console.log(chalk.red('❌ Working spec validation failed'));
+
+      // Show errors
+      result.errors.forEach((error, index) => {
+        console.log(`   ${index + 1}. ${chalk.red(error.message)}`);
+        if (error.suggestion) {
+          console.log(`      ${chalk.blue('💡 ' + error.suggestion)}`);
+        }
+      });
+
+      // Show warnings
+      if (result.warnings && result.warnings.length > 0) {
+        console.log(chalk.yellow('\n⚠️  Warnings:'));
+        result.warnings.forEach((warning, index) => {
+          console.log(`   ${index + 1}. ${chalk.yellow(warning.message)}`);
+        });
+      }
+
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red('❌ Error during validation:'), error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Tool execution command handler
+ */
+async function executeTool(toolId, options) {
+  try {
+    // Initialize tool system
+    const loader = await initializeToolSystem();
+
+    if (!loader) {
+      console.error(chalk.red('❌ Tool system not available'));
+      process.exit(1);
+    }
+
+    // Load all tools first
+    await loader.loadAllTools();
+    const tool = loader.getTool(toolId);
+
+    if (!tool) {
+      console.error(chalk.red(`❌ Tool '${toolId}' not found`));
+      console.log(chalk.blue('💡 Available tools:'));
+      const tools = loader.getAllTools();
+      for (const [id, t] of tools) {
+        console.log(`   - ${id}: ${t.metadata.name}`);
+      }
+      process.exit(1);
+    }
+
+    // Validate tool before execution
+    const validation = await toolValidator.validateTool(tool);
+    if (!validation.valid) {
+      console.error(chalk.red('❌ Tool validation failed:'));
+      validation.errors.forEach((error) => {
+        console.error(`   ${chalk.red('✗')} ${error}`);
+      });
+      process.exit(1);
+    }
+
+    // Parse parameters
+    let params = {};
+    if (options.params) {
+      try {
+        params = JSON.parse(options.params);
+      } catch (error) {
+        console.error(chalk.red('❌ Invalid JSON parameters:'), error.message);
+        process.exit(1);
+      }
+    }
+
+    console.log(chalk.blue(`🚀 Executing tool: ${tool.metadata.name}`));
+
+    // Execute tool
+    const result = await tool.module.execute(params, {
+      workingDirectory: process.cwd(),
+      timeout: options.timeout,
+    });
+
+    // Display results
+    if (result.success) {
+      console.log(chalk.green('✅ Tool execution successful'));
+      if (result.output && typeof result.output === 'object') {
+        console.log(chalk.gray('Output:'), JSON.stringify(result.output, null, 2));
+      }
+    } else {
+      console.error(chalk.red('❌ Tool execution failed'));
+      result.errors.forEach((error) => {
+        console.error(`   ${chalk.red('✗')} ${error}`);
+      });
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`❌ Error executing tool ${toolId}:`), error.message);
+    process.exit(1);
+  }
+}
+
+// Setup CLI program
+program.name('caws').description('CAWS - Coding Agent Workflow System CLI').version(CLI_VERSION);
+
+// Init command
+program
+  .command('init')
+  .description('Initialize a new project with CAWS')
+  .argument('[project-name]', 'Name of the project to create (use "." for current directory)')
+  .option('-i, --interactive', 'Run interactive setup wizard', true)
+  .option('--non-interactive', 'Skip interactive prompts (use defaults)', false)
+  .option('--template <template>', 'Use specific project template')
+  .action(initProject);
+
+// Scaffold command
+program
+  .command('scaffold')
+  .description('Add CAWS components to existing project')
+  .option('-f, --force', 'Overwrite existing files', false)
+  .option('--minimal', 'Only essential components', false)
+  .option('--with-codemods', 'Include codemod scripts', false)
+  .option('--with-oidc', 'Include OIDC trusted publisher setup', false)
+  .action(scaffoldProject);
+
+// Validate command
+program
+  .command('validate')
+  .description('Validate CAWS working spec with suggestions')
+  .argument('[spec-file]', 'Path to working spec file (default: .caws/working-spec.yaml)')
+  .option('-q, --quiet', 'Suppress suggestions and warnings', false)
+  .option('--auto-fix', 'Automatically fix safe validation issues', false)
+  .action(validateCommand);
+
+// Tool command
+program
+  .command('tool')
+  .description('Execute CAWS tools programmatically')
+  .argument('<tool-id>', 'ID of the tool to execute')
+  .option('-p, --params <json>', 'Parameters as JSON string', '{}')
+  .option('-t, --timeout <ms>', 'Execution timeout in milliseconds', parseInt, 30000)
+  .action(executeTool);
+
+// Error handling
+program.exitOverride((err) => {
+  if (
+    err.code === 'commander.help' ||
+    err.code === 'commander.version' ||
+    err.message.includes('outputHelp')
+  ) {
+    process.exit(0);
+  }
+  console.error(chalk.red('❌ Error:'), err.message);
+  process.exit(1);
+});
+
+// Parse and run
+if (require.main === module) {
+  try {
+    program.parse();
+  } catch (error) {
+    if (
+      error.code === 'commander.help' ||
+      error.code === 'commander.version' ||
+      error.message.includes('outputHelp')
+    ) {
+      process.exit(0);
+    } else {
+      console.error(chalk.red('❌ Error:'), error.message);
+      process.exit(1);
+    }
+  }
+}
+
+// Export functions for testing
+module.exports = {
+  generateWorkingSpec,
+  validateGeneratedSpec,
+};

package/dist/index.js

@@ -41,7 +41,13 @@ const { iterateCommand } = require('./commands/iterate');
 const { waiversCommand } = require('./commands/waivers');
 const { workflowCommand } = require('./commands/workflow');
 const { qualityMonitorCommand } = require('./commands/quality-monitor');
+const { qualityGatesCommand } = require('./commands/quality-gates');
 const { troubleshootCommand } = require('./commands/troubleshoot');
+const { archiveCommand } = require('./commands/archive');
+const { specsCommand } = require('./commands/specs');
+const { modeCommand } = require('./commands/mode');
+const { tutorialCommand } = require('./commands/tutorial');
+const { planCommand } = require('./commands/plan');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -113,20 +119,216 @@ program
 // Validate command
 program
   .command('validate')
-  .description('Validate CAWS working spec with suggestions')
-  .argument('[spec-file]', 'Path to working spec file (default: .caws/working-spec.yaml)')
+  .description('Validate CAWS spec with suggestions')
+  .argument('[spec-file]', 'Path to spec file (optional, uses spec resolution)')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth, FEAT-001)')
+  .option('-i, --interactive', 'Interactive spec selection when multiple specs exist', false)
   .option('-q, --quiet', 'Suppress suggestions and warnings', false)
   .option('--auto-fix', 'Automatically fix safe validation issues', false)
+  .option('--dry-run', 'Preview auto-fixes without applying them', false)
+  .option('--format <format>', 'Output format (text, json)', 'text')
   .action(validateCommand);
 
+// Quality Gates command
+program
+  .command('quality-gates')
+  .description('Run comprehensive quality gates (naming, duplication, god objects, documentation)')
+  .option('--ci', 'CI mode - exit with error code if violations found', false)
+  .option('--json', 'Output machine-readable JSON to stdout', false)
+  .option(
+    '--gates <gates>',
+    'Run only specific gates (comma-separated: naming,code_freeze,duplication,god_objects,documentation)',
+    ''
+  )
+  .option('--fix', 'Attempt automatic fixes (experimental)', false)
+  .option('--help', 'Show detailed help and usage examples', false)
+  .action(async (options) => {
+    // Handle --help flag
+    if (options.help) {
+      console.log(`
+CAWS Quality Gates - Enterprise Code Quality Enforcement
+
+USAGE:
+  caws quality-gates [options]
+
+DESCRIPTION:
+  Runs comprehensive quality gates to maintain code quality standards.
+  Supports selective gate execution, JSON output, and CI/CD integration.
+
+OPTIONS:
+  --ci              CI mode - exit with error code if violations found
+  --json            Output machine-readable JSON to stdout
+  --gates=<gates>   Run only specific gates (comma-separated)
+  --fix             Attempt automatic fixes (experimental)
+  --help            Show this help message
+
+VALID GATES:
+  naming           Check naming conventions and banned modifiers
+  code_freeze      Enforce code freeze compliance
+  duplication      Detect functional duplication
+  god_objects      Prevent oversized files
+  documentation    Check documentation quality
+
+EXAMPLES:
+  # Run all gates in development mode
+  caws quality-gates
+
+  # Run only specific gates
+  caws quality-gates --gates=naming,duplication
+
+  # CI mode with JSON output
+  caws quality-gates --ci --json
+
+  # Show detailed help
+  caws quality-gates --help
+
+OUTPUT:
+  - Console: Human-readable results with enforcement levels
+  - JSON: Machine-readable structured data (--json flag)
+  - Artifacts: docs-status/quality-gates-report.json
+  - GitHub Actions: Automatic step summaries when GITHUB_STEP_SUMMARY is set
+
+For more information, see: packages/quality-gates/README.md
+`);
+      process.exit(0);
+    }
+
+    // Call the actual quality gates runner
+    await qualityGatesCommand(options);
+  });
+
 // Status command
 program
   .command('status')
   .description('Show project health overview')
-  .option('-s, --spec <path>', 'Path to working spec file', '.caws/working-spec.yaml')
-  .option('--json', 'Output in JSON format', false)
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-s, --spec <path>', 'Path to spec file (explicit override)')
+  .option('--visual', 'Enhanced visual output with progress bars', false)
+  .option('--json', 'Output in JSON format for automation', false)
   .action(statusCommand);
 
+// Archive command
+program
+  .command('archive <change-id>')
+  .description('Archive completed change')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
+  .option('-f, --force', 'Force archive even if criteria not met', false)
+  .option('--dry-run', 'Preview archive without performing it', false)
+  .action(archiveCommand);
+
+// Specs command group
+const specsCmd = program.command('specs').description('Manage multiple CAWS spec files');
+
+// Specs subcommands
+specsCmd
+  .command('list')
+  .description('List all available specs')
+  .action(() => specsCommand('list', {}));
+
+specsCmd
+  .command('create <id>')
+  .description('Create a new spec (with conflict resolution)')
+  .option('-t, --type <type>', 'Spec type (feature, fix, refactor, chore, docs)', 'feature')
+  .option('--title <title>', 'Spec title')
+  .option('--tier <tier>', 'Risk tier (T1, T2, T3)', 'T3')
+  .option('--mode <mode>', 'Development mode', 'development')
+  .option('-f, --force', 'Override existing specs without confirmation', false)
+  .option('-i, --interactive', 'Ask for confirmation on conflicts', false)
+  .action((id, options) => specsCommand('create', { id, ...options }));
+
+specsCmd
+  .command('show <id>')
+  .description('Show detailed spec information')
+  .action((id) => specsCommand('show', { id }));
+
+specsCmd
+  .command('update <id>')
+  .description('Update spec properties')
+  .option('-s, --status <status>', 'Spec status (draft, active, completed)')
+  .option('--title <title>', 'Spec title')
+  .option('--description <desc>', 'Spec description')
+  .action((id, options) => specsCommand('update', { id, ...options }));
+
+specsCmd
+  .command('delete <id>')
+  .description('Delete a spec')
+  .action((id) => specsCommand('delete', { id }));
+
+specsCmd
+  .command('conflicts')
+  .description('Check for scope conflicts between specs')
+  .action(() => specsCommand('conflicts', {}));
+
+specsCmd
+  .command('migrate')
+  .description('Migrate from legacy working-spec.yaml to feature-specific specs')
+  .option('-i, --interactive', 'Interactive feature selection', false)
+  .option('-f, --features <features>', 'Comma-separated list of features to migrate', (value) =>
+    value.split(',')
+  )
+  .action((options) => specsCommand('migrate', options));
+
+specsCmd
+  .command('types')
+  .description('Show available spec types')
+  .action(() => specsCommand('types', {}));
+
+// Mode command group
+const modeCmd = program.command('mode').description('Manage CAWS complexity tiers');
+
+// Mode subcommands
+modeCmd
+  .command('current')
+  .description('Show current CAWS mode')
+  .action(() => modeCommand('current', {}));
+
+modeCmd
+  .command('set <mode>')
+  .description('Set CAWS complexity tier')
+  .action((mode) => modeCommand('set', { mode }));
+
+modeCmd
+  .command('set')
+  .description('Set CAWS complexity tier (interactive)')
+  .option('-i, --interactive', 'Interactive mode selection', false)
+  .option('-m, --mode <mode>', 'Specific mode to set')
+  .action((options) => modeCommand('set', options));
+
+modeCmd
+  .command('compare')
+  .description('Compare all available tiers')
+  .action(() => modeCommand('compare', {}));
+
+modeCmd
+  .command('recommend')
+  .description('Get tier recommendation for your project')
+  .option('--size <size>', 'Project size (small, medium, large)', 'medium')
+  .option('--team-size <size>', 'Team size (number)', '1')
+  .option('--compliance <required>', 'Compliance requirements (true/false)', 'false')
+  .option('--audit <required>', 'Audit requirements (true/false)', 'false')
+  .option('--details', 'Show detailed recommendation', false)
+  .action((options) => modeCommand('recommend', options));
+
+modeCmd
+  .command('details <mode>')
+  .description('Show detailed information about a specific tier')
+  .action((mode) => modeCommand('details', { mode }));
+
+// Tutorial command
+program
+  .command('tutorial [type]')
+  .description('Interactive guided learning for CAWS')
+  .action(tutorialCommand);
+
+// Plan command
+program
+  .command('plan <action>')
+  .description('Generate implementation plans')
+  .option('--spec-id <id>', 'Spec ID to generate plan for')
+  .option('--spec <id>', 'Alias for --spec-id')
+  .option('--output <path>', 'Output file path for the plan')
+  .action((action, options) => planCommand(action, options));
+
 // Templates command
 program
   .command('templates [subcommand]')
@@ -138,6 +340,7 @@ program
 program
   .command('diagnose')
   .description('Run health checks and suggest fixes')
+  .option('--spec-id <id>', 'Feature-specific spec ID')
   .option('--fix', 'Apply automatic fixes', false)
   .action(diagnoseCommand);
 
@@ -145,13 +348,15 @@ program
 program
   .command('evaluate [spec-file]')
   .description('Evaluate work against CAWS quality standards')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('-v, --verbose', 'Show detailed error information', false)
   .action(evaluateCommand);
 
 // Iterate command
 program
   .command('iterate [spec-file]')
-  .description('Get iterative development guidance based on current progress')
+  .description('Get iterative development guidance')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--current-state <json>', 'Current implementation state as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
   .action(iterateCommand);
@@ -200,7 +405,8 @@ waiversCmd
 // Workflow command group
 const workflowCmd = program
   .command('workflow <type>')
-  .description('Get workflow-specific guidance for development tasks')
+  .description('Get workflow-specific guidance')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--step <number>', 'Current step in workflow', '1')
   .option('--current-state <json>', 'Current implementation state as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
@@ -210,6 +416,7 @@ const workflowCmd = program
 program
   .command('quality-monitor <action>')
   .description('Monitor code quality impact in real-time')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .option('--files <files>', 'Files affected (comma-separated)')
   .option('--context <json>', 'Additional context as JSON', '{}')
   .option('-v, --verbose', 'Show detailed error information', false)
@@ -234,13 +441,12 @@ program
 // Test Analysis command
 program
   .command('test-analysis <subcommand> [options...]')
-  .description('Statistical analysis for budget prediction and test optimization')
+  .description('Statistical analysis for budget prediction')
+  .option('--spec-id <id>', 'Feature-specific spec ID (e.g., user-auth)')
   .action(testAnalysisCommand);
 
 // Provenance command group
-const provenanceCmd = program
-  .command('provenance')
-  .description('Manage CAWS provenance tracking and audit trails');
+const provenanceCmd = program.command('provenance').description('Manage CAWS provenance tracking');
 
 // Subcommands
 provenanceCmd
@@ -378,6 +584,11 @@ program.exitOverride((err) => {
       'validate',
       'scaffold',
       'status',
+      'archive',
+      'specs',
+      'mode',
+      'tutorial',
+      'plan',
       'templates',
       'diagnose',
       'evaluate',
@@ -473,6 +684,12 @@ if (require.main === module) {
         'init',
         'validate',
         'scaffold',
+        'status',
+        'archive',
+        'specs',
+        'mode',
+        'tutorial',
+        'plan',
         'provenance',
         'hooks',
         'burnup',