@paths.design/caws-cli 3.2.4 → 3.3.0

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);
   }
 }
 

package/dist/utils/typescript-detector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Detect if project is using TypeScript
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} TypeScript detection result
+ */
+export function detectTypeScript(projectDir?: string): any;
+/**
+ * Detect testing framework in use
+ * @param {string} projectDir - Project directory path
+ * @param {Object} packageJson - Parsed package.json (optional)
+ * @returns {Object} Testing framework detection result
+ */
+export function detectTestFramework(projectDir?: string, packageJson?: any): any;
+/**
+ * Check if TypeScript project needs test configuration
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Configuration status
+ */
+export function checkTypeScriptTestConfig(projectDir?: string): any;
+/**
+ * Generate configuration recommendations
+ * @param {Object} tsDetection - TypeScript detection result
+ * @param {Object} testDetection - Test framework detection result
+ * @returns {string[]} Array of recommendations
+ */
+export function generateRecommendations(tsDetection: any, testDetection: any): string[];
+/**
+ * Display TypeScript detection results
+ * @param {Object} detection - Detection result from checkTypeScriptTestConfig
+ */
+export function displayTypeScriptDetection(detection: any): void;
+//# sourceMappingURL=typescript-detector.d.ts.map

package/dist/utils/typescript-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-detector.d.ts","sourceRoot":"","sources":["../../src/utils/typescript-detector.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,8CAHW,MAAM,OAkChB;AAED;;;;;GAKG;AACH,iDAJW,MAAM,0BAkDhB;AAED;;;;GAIG;AACH,uDAHW,MAAM,OAiBhB;AAED;;;;;GAKG;AACH,+EAFa,MAAM,EAAE,CAuBpB;AAED;;;GAGG;AACH,iEAoBC"}

package/dist/utils/typescript-detector.js

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview TypeScript Project Detection and Configuration
+ * Auto-detects TypeScript projects and configures testing frameworks
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Detect if project is using TypeScript
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} TypeScript detection result
+ */
+function detectTypeScript(projectDir = process.cwd()) {
+  const tsconfigPath = path.join(projectDir, 'tsconfig.json');
+  const packageJsonPath = path.join(projectDir, 'package.json');
+
+  const hasTsConfig = fs.existsSync(tsconfigPath);
+
+  let hasTypeScriptDep = false;
+  let packageJson = null;
+
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+      };
+      hasTypeScriptDep = 'typescript' in allDeps;
+    } catch (error) {
+      // Ignore parse errors
+    }
+  }
+
+  const isTypeScript = hasTsConfig || hasTypeScriptDep;
+
+  return {
+    isTypeScript,
+    hasTsConfig,
+    hasTypeScriptDep,
+    packageJson,
+    tsconfigPath: hasTsConfig ? tsconfigPath : null,
+  };
+}
+
+/**
+ * Detect testing framework in use
+ * @param {string} projectDir - Project directory path
+ * @param {Object} packageJson - Parsed package.json (optional)
+ * @returns {Object} Testing framework detection result
+ */
+function detectTestFramework(projectDir = process.cwd(), packageJson = null) {
+  if (!packageJson) {
+    const packageJsonPath = path.join(projectDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    }
+  }
+
+  const hasJestConfig =
+    fs.existsSync(path.join(projectDir, 'jest.config.js')) ||
+    fs.existsSync(path.join(projectDir, 'jest.config.ts')) ||
+    fs.existsSync(path.join(projectDir, 'jest.config.json')) ||
+    packageJson?.jest;
+
+  const hasVitestConfig =
+    fs.existsSync(path.join(projectDir, 'vitest.config.js')) ||
+    fs.existsSync(path.join(projectDir, 'vitest.config.ts'));
+
+  const allDeps = {
+    ...packageJson?.dependencies,
+    ...packageJson?.devDependencies,
+  };
+
+  const hasJestDep = 'jest' in allDeps || '@types/jest' in allDeps;
+  const hasVitestDep = 'vitest' in allDeps;
+  const hasTsJest = 'ts-jest' in allDeps;
+
+  let framework = 'none';
+  let isConfigured = false;
+
+  if (hasJestConfig || hasJestDep) {
+    framework = 'jest';
+    isConfigured = hasJestConfig;
+  } else if (hasVitestConfig || hasVitestDep) {
+    framework = 'vitest';
+    isConfigured = hasVitestConfig;
+  }
+
+  return {
+    framework,
+    isConfigured,
+    hasJest: hasJestDep,
+    hasVitest: hasVitestDep,
+    hasTsJest,
+    needsTypeScriptConfig: false, // Will be set by checkTypeScriptTestConfig
+  };
+}
+
+/**
+ * Check if TypeScript project needs test configuration
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Configuration status
+ */
+function checkTypeScriptTestConfig(projectDir = process.cwd()) {
+  const tsDetection = detectTypeScript(projectDir);
+  const testDetection = detectTestFramework(projectDir, tsDetection.packageJson);
+
+  const needsConfig =
+    tsDetection.isTypeScript && testDetection.framework === 'jest' && !testDetection.hasTsJest;
+
+  return {
+    ...tsDetection,
+    testFramework: testDetection,
+    needsJestConfig: tsDetection.isTypeScript && !testDetection.isConfigured,
+    needsTsJest: needsConfig,
+    recommendations: generateRecommendations(tsDetection, testDetection),
+  };
+}
+
+/**
+ * Generate configuration recommendations
+ * @param {Object} tsDetection - TypeScript detection result
+ * @param {Object} testDetection - Test framework detection result
+ * @returns {string[]} Array of recommendations
+ */
+function generateRecommendations(tsDetection, testDetection) {
+  const recommendations = [];
+
+  if (tsDetection.isTypeScript && testDetection.framework === 'none') {
+    recommendations.push('No testing framework detected');
+    recommendations.push('Recommended: Install Jest with ts-jest');
+    recommendations.push('Run: npm install --save-dev jest @types/jest ts-jest');
+  }
+
+  if (tsDetection.isTypeScript && testDetection.framework === 'jest' && !testDetection.hasTsJest) {
+    recommendations.push('Jest detected but missing TypeScript support');
+    recommendations.push('Install ts-jest: npm install --save-dev ts-jest');
+    recommendations.push('Or run: caws diagnose to auto-configure');
+  }
+
+  if (tsDetection.isTypeScript && !testDetection.isConfigured) {
+    recommendations.push('Testing framework not configured');
+    recommendations.push('Run: caws scaffold to add test configuration');
+  }
+
+  return recommendations;
+}
+
+/**
+ * Display TypeScript detection results
+ * @param {Object} detection - Detection result from checkTypeScriptTestConfig
+ */
+function displayTypeScriptDetection(detection) {
+  if (!detection.isTypeScript) {
+    return;
+  }
+
+  console.log(chalk.cyan('\n📦 TypeScript Project Detected'));
+  console.log(chalk.gray(`   tsconfig.json: ${detection.hasTsConfig ? '✅' : '❌'}`));
+  console.log(chalk.gray(`   typescript dependency: ${detection.hasTypeScriptDep ? '✅' : '❌'}`));
+
+  if (detection.testFramework.framework !== 'none') {
+    console.log(chalk.gray(`   Test framework: ${detection.testFramework.framework}`));
+    console.log(chalk.gray(`   Configured: ${detection.testFramework.isConfigured ? '✅' : '❌'}`));
+  }
+
+  if (detection.recommendations.length > 0) {
+    console.log(chalk.yellow('\n💡 Recommendations:'));
+    detection.recommendations.forEach((rec) => {
+      console.log(chalk.yellow(`   ${rec}`));
+    });
+  }
+}
+
+module.exports = {
+  detectTypeScript,
+  detectTestFramework,
+  checkTypeScriptTestConfig,
+  generateRecommendations,
+  displayTypeScriptDetection,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "3.2.4",
+  "version": "3.3.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {