@paths.design/caws-cli 8.0.0 → 8.0.1

package/dist/constants/spec-types.d.ts

@@ -0,0 +1,41 @@
+export namespace SPEC_TYPES {
+    namespace feature {
+        let color: chalk.Chalk;
+        let icon: string;
+        let description: string;
+    }
+    namespace fix {
+        let color_1: chalk.Chalk;
+        export { color_1 as color };
+        let icon_1: string;
+        export { icon_1 as icon };
+        let description_1: string;
+        export { description_1 as description };
+    }
+    namespace refactor {
+        let color_2: chalk.Chalk;
+        export { color_2 as color };
+        let icon_2: string;
+        export { icon_2 as icon };
+        let description_2: string;
+        export { description_2 as description };
+    }
+    namespace chore {
+        let color_3: chalk.Chalk;
+        export { color_3 as color };
+        let icon_3: string;
+        export { icon_3 as icon };
+        let description_3: string;
+        export { description_3 as description };
+    }
+    namespace docs {
+        let color_4: chalk.Chalk;
+        export { color_4 as color };
+        let icon_4: string;
+        export { icon_4 as icon };
+        let description_4: string;
+        export { description_4 as description };
+    }
+}
+import chalk = require("chalk");
+//# sourceMappingURL=spec-types.d.ts.map

package/dist/constants/spec-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-types.d.ts","sourceRoot":"","sources":["../../src/constants/spec-types.js"],"names":[],"mappings":""}

package/dist/error-handler.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Enhanced error class with category and recovery suggestions
+ */
+export class CAWSError extends Error {
+    constructor(message: any, category?: any, suggestions?: any[]);
+    category: any;
+    suggestions: any[];
+    timestamp: Date;
+    executionTime: any;
+}
+export namespace ERROR_CATEGORIES {
+    let VALIDATION: string;
+    let PERMISSION: string;
+    let FILESYSTEM: string;
+    let NETWORK: string;
+    let CONFIGURATION: string;
+    let USER_INPUT: string;
+    let DEPENDENCY: string;
+    let UNKNOWN: string;
+}
+/**
+ * Execution timing utilities
+ */
+export class ExecutionTimer {
+    startTime: bigint;
+    endTime: bigint;
+    start(): void;
+    end(): number;
+    getDuration(): number;
+    formatDuration(): string;
+}
+/**
+ * Get error category from error object or message
+ * @param {Error|string} error - Error object or message
+ * @returns {string} Error category
+ */
+export function getErrorCategory(error: Error | string): string;
+/**
+ * Wrap async operations with consistent error handling and timing
+ * @param {Function} operation - Async operation to wrap
+ * @param {string} context - Context for error messages
+ * @param {boolean} includeTiming - Whether to include timing in results
+ * @returns {Promise<any>} Operation result or throws handled error
+ */
+export function safeAsync(operation: Function, context?: string, includeTiming?: boolean): Promise<any>;
+/**
+ * Wrap sync operations with timing
+ * @param {Function} operation - Sync operation to wrap
+ * @param {string} context - Context for error messages
+ * @param {boolean} includeTiming - Whether to include timing in results
+ * @returns {any} Operation result or throws handled error
+ */
+export function safeSync(operation: Function, context?: string, includeTiming?: boolean): any;
+/**
+ * Handle CLI errors with consistent formatting and user guidance
+ * @param {Error} error - Error to handle
+ * @param {Object} context - Error context (command, option, etc.)
+ * @param {boolean} exit - Whether to exit the process (default: true)
+ */
+export function handleCliError(error: Error, context?: any, exit?: boolean): void;
+/**
+ * Validate required environment and dependencies
+ * @returns {Object} Validation result with any errors
+ */
+export function validateEnvironment(): any;
+/**
+ * Get recovery suggestions based on error category
+ * @param {Error} error - Original error
+ * @param {string} category - Error category
+ * @param {Object} context - Additional context (command, options, etc.)
+ * @returns {string[]} Array of recovery suggestions
+ */
+export function getRecoverySuggestions(error: Error, category: string, context?: any): string[];
+/**
+ * Get documentation link for error category
+ * @param {string} category - Error category
+ * @param {Object} context - Additional context
+ * @returns {string} Documentation URL
+ */
+export function getDocumentationLink(category: string, context?: any): string;
+/**
+ * Find similar command using Levenshtein distance
+ * @param {string} input - User's input command
+ * @param {string[]} validCommands - List of valid commands
+ * @returns {string|null} Most similar command or null
+ */
+export function findSimilarCommand(input: string, validCommands: string[]): string | null;
+/**
+ * Command-specific error suggestions
+ */
+export const COMMAND_SUGGESTIONS: {
+    'unknown option': (option: any, command: any) => any[];
+    'unknown command': (command: any) => string[];
+    'template not found': () => string[];
+    'not a caws project': () => string[];
+};
+/**
+ * JSON output formatter for programmatic use
+ * @param {Object} data - Data to format as JSON
+ * @param {boolean} pretty - Whether to pretty-print (default: true)
+ */
+export function formatJsonOutput(data: any, pretty?: boolean): string;
+/**
+ * Check if user requested JSON output
+ * @returns {boolean} True if --json flag is present
+ */
+export function isJsonOutput(): boolean;
+/**
+ * Output data in appropriate format (JSON or human-readable)
+ * @param {Object} data - Data to output
+ * @param {boolean} success - Whether this is a success response
+ */
+export function outputResult(data: any, success?: boolean): any;
+/**
+ * Troubleshooting guide system
+ */
+export const TROUBLESHOOTING_GUIDES: {
+    'coverage-report-not-found': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'mutation-report-not-found': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'working-spec-validation': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+    'monorepo-detection': {
+        title: string;
+        symptoms: string[];
+        rootCauses: string[];
+        solutions: string[];
+        commands: string[];
+    };
+};
+/**
+ * Get troubleshooting guide for a specific issue
+ * @param {string} issueKey - Key for the troubleshooting guide
+ * @returns {Object|null} Troubleshooting guide or null if not found
+ */
+export function getTroubleshootingGuide(issueKey: string): any | null;
+/**
+ * Get all available troubleshooting guides
+ * @returns {Object} All troubleshooting guides
+ */
+export function getAllTroubleshootingGuides(): any;
+/**
+ * Suggest troubleshooting guide based on error message
+ * @param {string} errorMessage - Error message to analyze
+ * @returns {string|null} Issue key if match found, null otherwise
+ */
+export function suggestTroubleshootingGuide(errorMessage: string): string | null;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.js"],"names":[],"mappings":"AA0GA;;GAEG;AACH;IACE,+DAOC;IAJC,cAAqD;IACrD,mBAA2F;IAC3F,gBAA2B;IAC3B,mBAAyB;CAE5B;;;;;;;;;;;AAED;;GAEG;AACH;IAEI,kBAAqB;IACrB,gBAAmB;IAGrB,cAEC;IAED,cAGC;IAED,sBAIC;IAED,yBAMC;CACF;AAjHD;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA+DlB;AAiDD;;;;;;GAMG;AACH,yDAJW,MAAM,kBACN,OAAO,GACL,OAAO,CAAC,GAAG,CAAC,CA8BxB;AAED;;;;;;GAMG;AACH,wDAJW,MAAM,kBACN,OAAO,GACL,GAAG,CA8Bf;AAgSD;;;;;GAKG;AACH,sCAJW,KAAK,wBAEL,OAAO,QAmDjB;AA0JD;;;GAGG;AACH,2CAqBC;AAnXD;;;;;;GAMG;AACH,8CALW,KAAK,YACL,MAAM,kBAEJ,MAAM,EAAE,CAwDpB;AAED;;;;;GAKG;AACH,+CAJW,MAAM,kBAEJ,MAAM,CA4BlB;AAxJD;;;;;GAKG;AACH,0CAJW,MAAM,iBACN,MAAM,EAAE,GACN,MAAM,GAAC,IAAI,CAiBvB;AAjHD;;GAEG;AACH;;;;;EAuFE;AA4JF;;;;GAIG;AACH,qDAFW,OAAO,UAIjB;AAED;;;GAGG;AACH,gCAFa,OAAO,CAQnB;AAED;;;;GAIG;AACH,kDAFW,OAAO,OAcjB;AA2DD;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0GE;AAEF;;;;GAIG;AACH,kDAHW,MAAM,GACJ,MAAO,IAAI,CAIvB;AAED;;;GAGG;AACH,mDAEC;AAED;;;;GAIG;AACH,0DAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB"}

package/dist/generators/jest-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Configure Jest for TypeScript project
+ * @param {string} projectDir - Project directory path
+ * @param {Object} options - Configuration options
+ * @returns {Promise<Object>} Configuration result
+ */
+export function configureJestForTypeScript(projectDir?: string, options?: any): Promise<any>;
+/**
+ * Generate Jest configuration for TypeScript project
+ * @param {Object} options - Configuration options
+ * @returns {string} Jest configuration content
+ */
+export function generateJestConfig(options?: any): string;
+/**
+ * Generate test setup file for TypeScript
+ * @returns {string} Setup file content
+ */
+export function generateTestSetup(): string;
+/**
+ * Install Jest and TypeScript dependencies
+ * @param {string} projectDir - Project directory
+ * @param {Object} packageJson - Existing package.json
+ * @returns {Promise<Object>} Installation result
+ */
+export function installJestDependencies(projectDir: string, packageJson: any): Promise<any>;
+/**
+ * Get Jest configuration recommendations
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Recommendations
+ */
+export function getJestRecommendations(projectDir?: string): any;
+//# sourceMappingURL=jest-config.d.ts.map

package/dist/generators/jest-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jest-config.d.ts","sourceRoot":"","sources":["../../src/generators/jest-config.js"],"names":[],"mappings":"AA+GA;;;;;GAKG;AACH,wDAJW,MAAM,kBAEJ,OAAO,KAAQ,CAgE3B;AAzKD;;;;GAIG;AACH,mDAFa,MAAM,CA0ClB;AAED;;;GAGG;AACH,qCAFa,MAAM,CAiBlB;AAED;;;;;GAKG;AACH,oDAJW,MAAM,qBAEJ,OAAO,KAAQ,CA2B3B;AAwED;;;;GAIG;AACH,oDAHW,MAAM,OAkDhB"}

package/dist/generators/working-spec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate working spec YAML with user input
+ * @param {Object} answers - User responses
+ * @returns {string} - Generated YAML content
+ */
+export function generateWorkingSpec(answers: any): string;
+/**
+ * Validate generated working spec against JSON schema
+ * @param {string} specContent - YAML spec content
+ * @param {Object} answers - User responses for error context
+ */
+export function validateGeneratedSpec(specContent: string, _answers: any): void;
+//# sourceMappingURL=working-spec.d.ts.map

package/dist/generators/working-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-spec.d.ts","sourceRoot":"","sources":["../../src/generators/working-spec.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,mDAFa,MAAM,CAsLlB;AAED;;;;GAIG;AACH,mDAHW,MAAM,uBA8BhB"}

package/dist/index-new.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { generateWorkingSpec } from "./generators/working-spec";
+import { validateGeneratedSpec } from "./generators/working-spec";
+export { generateWorkingSpec, validateGeneratedSpec };
+//# sourceMappingURL=index-new.d.ts.map

package/dist/index-new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-new.d.ts","sourceRoot":"","sources":["../src/index-new.js"],"names":[],"mappings":""}

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.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { generateWorkingSpec } from "./generators/working-spec";
+import { validateGeneratedSpec } from "./generators/working-spec";
+export { generateWorkingSpec, validateGeneratedSpec };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":""}

package/dist/index.js

@@ -142,6 +142,8 @@ program
     ''
   )
   .option('--fix', 'Attempt automatic fixes (experimental)', false)
+  .option('--context <context>', 'Execution context: commit (staged files), push (all tracked files), or ci (all tracked files)', 'commit')
+  .option('--all-files', 'Check all tracked files (equivalent to --context=ci)', false)
   .option('--help', 'Show detailed help and usage examples', false)
   .action(async (options) => {
     // Handle --help flag
@@ -161,6 +163,8 @@ OPTIONS:
   --json            Output machine-readable JSON to stdout
   --gates=<gates>   Run only specific gates (comma-separated)
   --fix             Attempt automatic fixes (experimental)
+  --context=<ctx>   Execution context: commit (staged files), push (all tracked), ci (all tracked)
+  --all-files       Check all tracked files (shortcut for --context=ci)
   --help            Show this help message
 
 VALID GATES:
@@ -182,6 +186,12 @@ EXAMPLES:
   # CI mode with JSON output
   caws quality-gates --ci --json
 
+  # Check all files in repository (not just staged)
+  caws quality-gates --all-files
+
+  # Use specific context
+  caws quality-gates --context=ci
+
   # Show detailed help
   caws quality-gates --help