@paths.design/caws-cli 3.2.4 → 3.3.1

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

@@ -23,6 +23,9 @@ const {
   initializeLanguageSupport,
 } = require('./config');
 
+// Import error handling
+const { handleCliError, findSimilarCommand } = require('./error-handler');
+
 // Import command handlers
 const { initProject } = require('./commands/init');
 const { validateCommand } = require('./commands/validate');
@@ -30,6 +33,9 @@ const { burnupCommand } = require('./commands/burnup');
 const { testAnalysisCommand } = require('./test-analysis');
 const { provenanceCommand } = require('./commands/provenance');
 const { executeTool } = require('./commands/tool');
+const { statusCommand } = require('./commands/status');
+const { templatesCommand } = require('./commands/templates');
+const { diagnoseCommand } = require('./commands/diagnose');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -72,7 +78,11 @@ setFinalizationDependencies({
 });
 
 // Setup CLI program
-program.name('caws').description('CAWS - Coding Agent Workflow System CLI').version(CLI_VERSION);
+program
+  .name('caws')
+  .description('CAWS - Coding Agent Workflow System CLI')
+  .version(CLI_VERSION)
+  .showHelpAfterError(false); // We'll show better suggestions instead
 
 // Init command
 program
@@ -103,6 +113,27 @@ program
   .option('--auto-fix', 'Automatically fix safe validation issues', false)
   .action(validateCommand);
 
+// Status command
+program
+  .command('status')
+  .description('Show project health overview')
+  .option('-s, --spec <path>', 'Path to working spec file', '.caws/working-spec.yaml')
+  .action(statusCommand);
+
+// Templates command
+program
+  .command('templates [subcommand]')
+  .description('Discover and manage project templates')
+  .option('-n, --name <template>', 'Template name (for info subcommand)')
+  .action(templatesCommand);
+
+// Diagnose command
+program
+  .command('diagnose')
+  .description('Run health checks and suggest fixes')
+  .option('--fix', 'Apply automatic fixes', false)
+  .action(diagnoseCommand);
+
 // Tool command
 program
   .command('tool')
@@ -234,7 +265,14 @@ hooksCmd
   });
 
 // Error handling
+// Custom error event handler for better messages
+program.configureHelp({
+  // Override error display
+  showError: () => {}, // Suppress default error display
+});
+
 program.exitOverride((err) => {
+  // Handle help and version requests gracefully
   if (
     err.code === 'commander.help' ||
     err.code === 'commander.version' ||
@@ -242,7 +280,74 @@ program.exitOverride((err) => {
   ) {
     process.exit(0);
   }
-  console.error(chalk.red('❌ Error:'), err.message);
+
+  const commandName = process.argv[2];
+
+  // Check for unknown command
+  if (err.code === 'commander.unknownCommand') {
+    const validCommands = [
+      'init',
+      'validate',
+      'scaffold',
+      'status',
+      'templates',
+      'provenance',
+      'hooks',
+      'burnup',
+      'tool',
+    ];
+    const similar = findSimilarCommand(commandName, validCommands);
+
+    console.error(chalk.red(`\n❌ Unknown command: ${commandName}`));
+
+    if (similar) {
+      console.error(chalk.yellow(`\n💡 Did you mean: caws ${similar}?`));
+    }
+
+    console.error(
+      chalk.yellow('💡 Available commands: init, validate, scaffold, provenance, hooks')
+    );
+    console.error(chalk.yellow('💡 Try: caws --help for full command list'));
+    console.error(
+      chalk.blue(
+        '\n📚 Documentation: https://github.com/Paths-Design/coding-agent-working-standard/blob/main/docs/api/cli.md'
+      )
+    );
+
+    process.exit(1);
+  }
+
+  // Check for unknown option
+  if (err.code === 'commander.unknownOption' || err.message.includes('unknown option')) {
+    const optionMatch = err.message.match(/unknown option ['"]([^'"]+)['"]/i);
+    const option = optionMatch ? optionMatch[1] : '';
+
+    console.error(chalk.red(`\n❌ Unknown option: ${option}`));
+    console.error(chalk.yellow(`\n💡 Try: caws ${commandName || ''} --help for available options`));
+
+    // Provide specific suggestions for common mistakes
+    if (option === '--suggestions' || option === '--suggest') {
+      console.error(chalk.yellow('💡 Note: Validation includes suggestions by default'));
+      console.error(chalk.yellow('   Just run: caws validate'));
+    }
+
+    console.error(
+      chalk.blue(
+        '\n📚 Documentation: https://github.com/Paths-Design/coding-agent-working-standard/blob/main/docs/api/cli.md'
+      )
+    );
+
+    process.exit(1);
+  }
+
+  // Generic Commander error
+  console.error(chalk.red('\n❌ Error:'), err.message);
+  console.error(chalk.yellow('\n💡 Try: caws --help for usage information'));
+  console.error(
+    chalk.blue(
+      '\n📚 Documentation: https://github.com/Paths-Design/coding-agent-working-standard/blob/main/docs/agents/full-guide.md'
+    )
+  );
   process.exit(1);
 });
 
@@ -251,16 +356,81 @@ if (require.main === module) {
   try {
     program.parse();
   } catch (error) {
+    // Handle help and version requests gracefully
     if (
       error.code === 'commander.help' ||
       error.code === 'commander.version' ||
       error.message.includes('outputHelp')
     ) {
       process.exit(0);
-    } else {
-      console.error(chalk.red('❌ Error:'), error.message);
+    }
+
+    // Enhanced error handling for Commander.js errors
+    const commandName = process.argv[2];
+    const context = {
+      command: commandName,
+      option: process.argv[3],
+    };
+
+    // Check for unknown command
+    if (error.code === 'commander.unknownCommand') {
+      const validCommands = [
+        'init',
+        'validate',
+        'scaffold',
+        'provenance',
+        'hooks',
+        'burnup',
+        'tool',
+      ];
+      const similar = findSimilarCommand(commandName, validCommands);
+
+      console.error(chalk.red(`\n❌ Unknown command: ${commandName}`));
+
+      if (similar) {
+        console.error(chalk.yellow(`\n💡 Did you mean: caws ${similar}?`));
+      }
+
+      console.error(
+        chalk.yellow('💡 Available commands: init, validate, scaffold, provenance, hooks')
+      );
+      console.error(chalk.yellow('💡 Try: caws --help for full command list'));
+      console.error(
+        chalk.blue(
+          '\n📚 Documentation: https://github.com/Paths-Design/coding-agent-working-standard/blob/main/docs/api/cli.md'
+        )
+      );
+
       process.exit(1);
     }
+
+    // Check for unknown option
+    if (error.code === 'commander.unknownOption' || error.message.includes('unknown option')) {
+      const optionMatch = error.message.match(/unknown option ['"]([^'"]+)['"]/i);
+      const option = optionMatch ? optionMatch[1] : '';
+
+      console.error(chalk.red(`\n❌ Unknown option: ${option}`));
+      console.error(
+        chalk.yellow(`\n💡 Try: caws ${commandName || ''} --help for available options`)
+      );
+
+      // Provide specific suggestions for common mistakes
+      if (option === '--suggestions' || option === '--suggest') {
+        console.error(chalk.yellow('💡 Note: Validation includes suggestions by default'));
+        console.error(chalk.yellow('   Just run: caws validate'));
+      }
+
+      console.error(
+        chalk.blue(
+          '\n📚 Documentation: https://github.com/Paths-Design/coding-agent-working-standard/blob/main/docs/api/cli.md'
+        )
+      );
+
+      process.exit(1);
+    }
+
+    // Generic error with enhanced handling
+    handleCliError(error, context, true);
   }
 }