@paths.design/caws-cli 3.2.4 → 3.3.0

package/dist/error-handler.js

@@ -137,19 +137,152 @@ async function safeAsync(operation, context = '') {
   }
 }
 
+/**
+ * Command-specific error suggestions
+ */
+const COMMAND_SUGGESTIONS = {
+  'unknown option': (option, command) => {
+    const suggestions = [];
+
+    // Common typos and alternatives
+    const optionMap = {
+      '--suggestions': 'Validation includes suggestions by default. Try: caws validate',
+      '--suggest': 'Validation includes suggestions by default. Try: caws validate',
+      '--help': 'Try: caws --help or caws <command> --help',
+      '--json': 'For JSON output, try: caws provenance show --format=json',
+      '--dashboard': 'Try: caws provenance show --format=dashboard',
+    };
+
+    if (optionMap[option]) {
+      suggestions.push(optionMap[option]);
+    } else {
+      suggestions.push(`Try: caws ${command || ''} --help for available options`);
+    }
+
+    return suggestions;
+  },
+
+  'unknown command': (command) => {
+    const validCommands = [
+      'init',
+      'validate',
+      'scaffold',
+      'status',
+      'templates',
+      'provenance',
+      'hooks',
+      'burnup',
+      'tool',
+    ];
+    const similar = findSimilarCommand(command, validCommands);
+
+    const suggestions = [];
+    if (similar) {
+      suggestions.push(`Did you mean: caws ${similar}?`);
+    }
+    suggestions.push(
+      'Available commands: init, validate, scaffold, status, templates, provenance, hooks'
+    );
+    suggestions.push('Try: caws --help for full command list');
+
+    return suggestions;
+  },
+
+  'template not found': () => [
+    'Templates are bundled with CAWS CLI',
+    'Try: caws scaffold (should work automatically)',
+    'If issue persists: npm i -g @paths.design/caws-cli@latest',
+  ],
+
+  'not a caws project': () => [
+    'Initialize CAWS first: caws init .',
+    'Or create new project: caws init <project-name>',
+    'Check for .caws/working-spec.yaml file',
+  ],
+};
+
+/**
+ * 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
+ */
+function findSimilarCommand(input, validCommands) {
+  if (!input) return null;
+
+  let minDistance = Infinity;
+  let closestMatch = null;
+
+  for (const cmd of validCommands) {
+    const distance = levenshteinDistance(input.toLowerCase(), cmd.toLowerCase());
+    if (distance < minDistance && distance <= 2) {
+      minDistance = distance;
+      closestMatch = cmd;
+    }
+  }
+
+  return closestMatch;
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Edit distance
+ */
+function levenshteinDistance(a, b) {
+  const matrix = [];
+
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
 /**
  * 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
  */
-function getRecoverySuggestions(error, category) {
+function getRecoverySuggestions(error, category, context = {}) {
   const suggestions = [];
+  const errorMessage = error.message || '';
+
+  // Check for command-specific suggestions first
+  for (const [pattern, suggestionFn] of Object.entries(COMMAND_SUGGESTIONS)) {
+    if (errorMessage.toLowerCase().includes(pattern)) {
+      const commandSuggestions = suggestionFn(context.option, context.command);
+      suggestions.push(...commandSuggestions);
+      return suggestions;
+    }
+  }
 
+  // Fall back to category-based suggestions
   switch (category) {
     case ERROR_CATEGORIES.PERMISSION:
       suggestions.push('Try running the command with elevated privileges (sudo)');
-      suggestions.push('Check file/directory permissions with `ls -la`');
+      suggestions.push('Check file/directory permissions with: ls -la');
       break;
 
     case ERROR_CATEGORIES.FILESYSTEM:
@@ -163,52 +296,87 @@ function getRecoverySuggestions(error, category) {
       break;
 
     case ERROR_CATEGORIES.VALIDATION:
-      suggestions.push('Run `caws validate --suggestions` for detailed validation help');
-      suggestions.push('Check your working spec format against the documentation');
+      suggestions.push('Run: caws validate for detailed validation help');
+      suggestions.push('Check your working spec format against the schema');
+      suggestions.push('See: docs/api/schema.md for specification details');
       break;
 
     case ERROR_CATEGORIES.CONFIGURATION:
-      suggestions.push('Run `caws init --interactive` to reconfigure your project');
+      suggestions.push('Run: caws init --interactive to reconfigure');
       suggestions.push('Check your .caws directory and configuration files');
+      suggestions.push('Try: caws diagnose to identify configuration issues');
       break;
 
     case ERROR_CATEGORIES.NETWORK:
       suggestions.push('Check your internet connection');
       suggestions.push('Verify the URL/service is accessible');
+      suggestions.push('Try again in a few moments');
       break;
 
     default:
-      suggestions.push('Run the command with --help for usage information');
-      suggestions.push('Check the CAWS documentation at docs/README.md');
+      suggestions.push('Run: caws --help for usage information');
+      suggestions.push('See: docs/agents/full-guide.md for detailed documentation');
   }
 
   return suggestions;
 }
 
+/**
+ * Get documentation link for error category
+ * @param {string} category - Error category
+ * @param {Object} context - Additional context
+ * @returns {string} Documentation URL
+ */
+function getDocumentationLink(category, context = {}) {
+  const baseUrl = 'https://github.com/Paths-Design/coding-agent-working-standard/blob/main';
+
+  const categoryLinks = {
+    validation: `${baseUrl}/docs/api/schema.md`,
+    configuration: `${baseUrl}/docs/guides/caws-developer-guide.md`,
+    filesystem: `${baseUrl}/docs/agents/tutorial.md`,
+    permission: `${baseUrl}/SECURITY.md`,
+    network: `${baseUrl}/README.md#requirements`,
+  };
+
+  if (context.command) {
+    const commandLinks = {
+      init: `${baseUrl}/docs/agents/tutorial.md#initialization`,
+      validate: `${baseUrl}/docs/api/cli.md#validate`,
+      scaffold: `${baseUrl}/docs/api/cli.md#scaffold`,
+      provenance: `${baseUrl}/docs/api/cli.md#provenance`,
+      hooks: `${baseUrl}/docs/guides/hooks-and-agent-workflows.md`,
+    };
+
+    if (commandLinks[context.command]) {
+      return commandLinks[context.command];
+    }
+  }
+
+  return categoryLinks[category] || `${baseUrl}/docs/agents/full-guide.md`;
+}
+
 /**
  * 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)
  */
-function handleCliError(error, exit = true) {
+function handleCliError(error, context = {}, exit = true) {
   const category = error.category || getErrorCategory(error);
-  const suggestions = error.suggestions || getRecoverySuggestions(error, category);
+  const suggestions = error.suggestions || getRecoverySuggestions(error, category, context);
+  const docLink = getDocumentationLink(category, context);
 
   // Format error output
-  console.error(chalk.red(`\n❌ Error (${category}): ${error.message}`));
+  console.error(chalk.red(`\n❌ ${error.message}`));
 
   if (suggestions && suggestions.length > 0) {
     console.error(chalk.yellow('\n💡 Suggestions:'));
     suggestions.forEach((suggestion) => {
-      console.error(chalk.yellow(`   • ${suggestion}`));
+      console.error(chalk.yellow(`   ${suggestion}`));
     });
   }
 
-  console.error(
-    chalk.gray(
-      '\n📖 For more help, visit: https://github.com/Paths-Design/coding-agent-working-standard'
-    )
-  );
+  console.error(chalk.blue(`\n📚 Documentation: ${docLink}`));
 
   if (exit) {
     process.exit(1);
@@ -250,4 +418,7 @@ module.exports = {
   handleCliError,
   validateEnvironment,
   getRecoverySuggestions,
+  getDocumentationLink,
+  findSimilarCommand,
+  COMMAND_SUGGESTIONS,
 };

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/jest-config.js

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Jest Configuration Generator
+ * Generates Jest configuration for TypeScript projects
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Generate Jest configuration for TypeScript project
+ * @param {Object} options - Configuration options
+ * @returns {string} Jest configuration content
+ */
+function generateJestConfig(options = {}) {
+  const {
+    preset = 'ts-jest',
+    testEnvironment = 'node',
+    rootDir = '.',
+    testMatch = ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+    moduleFileExtensions = ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+    collectCoverageFrom = ['src/**/*.ts', '!src/**/*.d.ts', '!src/**/*.test.ts'],
+    coverageThreshold = {
+      global: {
+        branches: 80,
+        functions: 80,
+        lines: 80,
+        statements: 80,
+      },
+    },
+  } = options;
+
+  const config = {
+    preset,
+    testEnvironment,
+    rootDir,
+    testMatch,
+    moduleFileExtensions,
+    collectCoverageFrom,
+    coverageThreshold,
+    transform: {
+      '^.+\\.tsx?$': [
+        'ts-jest',
+        {
+          tsconfig: 'tsconfig.json',
+        },
+      ],
+    },
+    moduleNameMapper: {
+      '^@/(.*)$': '<rootDir>/src/$1',
+    },
+  };
+
+  return `module.exports = ${JSON.stringify(config, null, 2)};\n`;
+}
+
+/**
+ * Generate test setup file for TypeScript
+ * @returns {string} Setup file content
+ */
+function generateTestSetup() {
+  return `/**
+ * Jest setup file for TypeScript tests
+ * @author @darianrosebrook
+ */
+
+// Add custom matchers or global test setup here
+beforeAll(() => {
+  // Global setup
+});
+
+afterAll(() => {
+  // Global teardown
+});
+`;
+}
+
+/**
+ * Install Jest and TypeScript dependencies
+ * @param {string} projectDir - Project directory
+ * @param {Object} packageJson - Existing package.json
+ * @returns {Promise<Object>} Installation result
+ */
+async function installJestDependencies(projectDir, packageJson) {
+  const dependencies = ['jest', '@types/jest', 'ts-jest'];
+
+  // Check which dependencies are already installed
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  const toInstall = dependencies.filter((dep) => !(dep in allDeps));
+
+  if (toInstall.length === 0) {
+    return {
+      installed: false,
+      message: 'All Jest dependencies already installed',
+      dependencies: [],
+    };
+  }
+
+  return {
+    installed: false,
+    needsInstall: true,
+    dependencies: toInstall,
+    installCommand: `npm install --save-dev ${toInstall.join(' ')}`,
+  };
+}
+
+/**
+ * Configure Jest for TypeScript project
+ * @param {string} projectDir - Project directory path
+ * @param {Object} options - Configuration options
+ * @returns {Promise<Object>} Configuration result
+ */
+async function configureJestForTypeScript(projectDir = process.cwd(), options = {}) {
+  const { force = false, quiet = false } = options;
+
+  // Check if Jest config already exists
+  const jestConfigPath = path.join(projectDir, 'jest.config.js');
+  if (fs.existsSync(jestConfigPath) && !force) {
+    return {
+      configured: false,
+      skipped: true,
+      message: 'Jest configuration already exists',
+      path: jestConfigPath,
+    };
+  }
+
+  // Generate Jest config
+  const jestConfig = generateJestConfig();
+  await fs.writeFile(jestConfigPath, jestConfig);
+
+  if (!quiet) {
+    console.log(chalk.green('✅ Created jest.config.js'));
+  }
+
+  // Generate test setup file
+  const setupPath = path.join(projectDir, 'tests', 'setup.ts');
+  await fs.ensureDir(path.join(projectDir, 'tests'));
+  await fs.writeFile(setupPath, generateTestSetup());
+
+  if (!quiet) {
+    console.log(chalk.green('✅ Created tests/setup.ts'));
+  }
+
+  // Update package.json with test script if needed
+  const packageJsonPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
+    if (!packageJson.scripts) {
+      packageJson.scripts = {};
+    }
+
+    if (!packageJson.scripts.test) {
+      packageJson.scripts.test = 'jest';
+      packageJson.scripts['test:coverage'] = 'jest --coverage';
+      packageJson.scripts['test:watch'] = 'jest --watch';
+
+      await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+      if (!quiet) {
+        console.log(chalk.green('✅ Added test scripts to package.json'));
+      }
+    }
+  }
+
+  return {
+    configured: true,
+    files: [jestConfigPath, setupPath],
+    nextSteps: [
+      'Install dependencies: npm install --save-dev jest @types/jest ts-jest',
+      'Run tests: npm test',
+      'Run with coverage: npm run test:coverage',
+    ],
+  };
+}
+
+/**
+ * Get Jest configuration recommendations
+ * @param {string} projectDir - Project directory path
+ * @returns {Object} Recommendations
+ */
+function getJestRecommendations(projectDir = process.cwd()) {
+  const recommendations = [];
+  const hasJestConfig = fs.existsSync(path.join(projectDir, 'jest.config.js'));
+  const packageJsonPath = path.join(projectDir, 'package.json');
+
+  if (fs.existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const allDeps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+    };
+
+    if (!hasJestConfig && !('jest' in allDeps)) {
+      recommendations.push({
+        type: 'missing_framework',
+        severity: 'high',
+        message: 'No testing framework detected',
+        fix: 'Install Jest: npm install --save-dev jest @types/jest ts-jest',
+        autoFixable: false,
+      });
+    }
+
+    if ('typescript' in allDeps && 'jest' in allDeps && !('ts-jest' in allDeps)) {
+      recommendations.push({
+        type: 'missing_ts_jest',
+        severity: 'high',
+        message: 'TypeScript project with Jest but missing ts-jest',
+        fix: 'Install ts-jest: npm install --save-dev ts-jest',
+        autoFixable: false,
+      });
+    }
+
+    if (!hasJestConfig && 'jest' in allDeps) {
+      recommendations.push({
+        type: 'missing_config',
+        severity: 'medium',
+        message: 'Jest installed but not configured',
+        fix: 'Run: caws scaffold to generate Jest configuration',
+        autoFixable: true,
+      });
+    }
+  }
+
+  return {
+    hasIssues: recommendations.length > 0,
+    recommendations,
+  };
+}
+
+module.exports = {
+  configureJestForTypeScript,
+  generateJestConfig,
+  generateTestSetup,
+  installJestDependencies,
+  getJestRecommendations,
+};