@paths.design/caws-cli 3.2.4 → 3.3.0

package/dist/commands/status.js

@@ -0,0 +1,276 @@
+/**
+ * @fileoverview CAWS Status Command
+ * Display project health overview
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+
+/**
+ * Load working specification
+ * @param {string} specPath - Path to working spec
+ * @returns {Promise<Object|null>} Parsed spec or null
+ */
+async function loadWorkingSpec(specPath = '.caws/working-spec.yaml') {
+  try {
+    if (!(await fs.pathExists(specPath))) {
+      return null;
+    }
+
+    const content = await fs.readFile(specPath, 'utf8');
+    return yaml.load(content);
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check Git hooks status
+ * @returns {Promise<Object>} Hooks status
+ */
+async function checkGitHooks() {
+  const hooksDir = '.git/hooks';
+
+  if (!(await fs.pathExists(hooksDir))) {
+    return {
+      installed: false,
+      count: 0,
+      active: [],
+    };
+  }
+
+  const cawsHooks = ['pre-commit', 'post-commit', 'pre-push', 'commit-msg'];
+  const activeHooks = [];
+
+  for (const hook of cawsHooks) {
+    const hookPath = path.join(hooksDir, hook);
+    if (await fs.pathExists(hookPath)) {
+      const content = await fs.readFile(hookPath, 'utf8');
+      if (content.includes('CAWS')) {
+        activeHooks.push(hook);
+      }
+    }
+  }
+
+  return {
+    installed: activeHooks.length > 0,
+    count: activeHooks.length,
+    active: activeHooks,
+    total: cawsHooks.length,
+  };
+}
+
+/**
+ * Load provenance chain
+ * @returns {Promise<Object>} Provenance status
+ */
+async function loadProvenanceChain() {
+  const chainPath = '.caws/provenance/chain.json';
+
+  if (!(await fs.pathExists(chainPath))) {
+    return {
+      exists: false,
+      count: 0,
+      lastUpdate: null,
+    };
+  }
+
+  try {
+    const chain = JSON.parse(await fs.readFile(chainPath, 'utf8'));
+    const lastEntry = chain.length > 0 ? chain[chain.length - 1] : null;
+
+    return {
+      exists: true,
+      count: chain.length,
+      lastUpdate: lastEntry?.timestamp || null,
+      lastCommit: lastEntry?.commit?.hash || null,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      count: 0,
+      lastUpdate: null,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Check quality gates status (simplified)
+ * @returns {Promise<Object>} Quality gates status
+ */
+async function checkQualityGates() {
+  // For now, return a placeholder
+  // In full implementation, this would run actual gate checks
+  return {
+    checked: false,
+    message: 'Run: node apps/tools/caws/gates.js for full gate status',
+  };
+}
+
+/**
+ * Get time since last update
+ * @param {string} timestamp - ISO timestamp
+ * @returns {string} Human-readable time
+ */
+function getTimeSince(timestamp) {
+  if (!timestamp) return 'never';
+
+  const now = new Date();
+  const then = new Date(timestamp);
+  const diffMs = now - then;
+
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins} minute${diffMins > 1 ? 's' : ''} ago`;
+  if (diffHours < 24) return `${diffHours} hour${diffHours > 1 ? 's' : ''} ago`;
+  return `${diffDays} day${diffDays > 1 ? 's' : ''} ago`;
+}
+
+/**
+ * Display project status
+ * @param {Object} data - Status data
+ */
+function displayStatus(data) {
+  const { spec, hooks, provenance, gates } = data;
+
+  console.log(chalk.bold.cyan('\n📊 CAWS Project Status'));
+  console.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+
+  // Working Spec Status
+  if (spec) {
+    console.log(chalk.green('✅ Working Spec'));
+    console.log(chalk.gray(`   ID: ${spec.id} | Tier: ${spec.risk_tier} | Mode: ${spec.mode}`));
+    console.log(chalk.gray(`   Title: ${spec.title}`));
+  } else {
+    console.log(chalk.red('❌ Working Spec'));
+    console.log(chalk.gray('   No working spec found'));
+    console.log(chalk.yellow('   💡 Run: caws init . to create one'));
+  }
+
+  console.log('');
+
+  // Git Hooks Status
+  if (hooks.installed) {
+    console.log(chalk.green(`✅ Git Hooks`));
+    console.log(chalk.gray(`   ${hooks.count}/${hooks.total} active: ${hooks.active.join(', ')}`));
+  } else {
+    console.log(chalk.yellow('⚠️  Git Hooks'));
+    console.log(chalk.gray('   No CAWS git hooks installed'));
+    console.log(chalk.yellow('   💡 Run: caws hooks install'));
+  }
+
+  console.log('');
+
+  // Provenance Status
+  if (provenance.exists) {
+    console.log(chalk.green('✅ Provenance'));
+    console.log(chalk.gray(`   Chain: ${provenance.count} entries`));
+    if (provenance.lastUpdate) {
+      console.log(chalk.gray(`   Last update: ${getTimeSince(provenance.lastUpdate)}`));
+    }
+  } else {
+    console.log(chalk.yellow('⚠️  Provenance'));
+    console.log(chalk.gray('   Provenance tracking not initialized'));
+    console.log(chalk.yellow('   💡 Run: caws provenance init'));
+  }
+
+  console.log('');
+
+  // Quality Gates Status
+  console.log(chalk.blue('ℹ️  Quality Gates'));
+  console.log(chalk.gray(`   ${gates.message}`));
+
+  // Suggestions
+  const suggestions = generateSuggestions(data);
+  if (suggestions.length > 0) {
+    console.log(chalk.bold.yellow('\n💡 Suggestions:'));
+    suggestions.forEach((suggestion) => {
+      console.log(chalk.yellow(`   ${suggestion}`));
+    });
+  }
+
+  // Quick Links
+  console.log(chalk.bold.blue('\n📚 Quick Links:'));
+  if (spec) {
+    console.log(chalk.blue('   View spec: .caws/working-spec.yaml'));
+  }
+  if (hooks.installed) {
+    console.log(chalk.blue('   View hooks: .git/hooks/'));
+  }
+  if (provenance.exists) {
+    console.log(chalk.blue('   View provenance: caws provenance show --format=dashboard'));
+  }
+  console.log(chalk.blue('   Full documentation: docs/agents/full-guide.md'));
+
+  console.log('');
+}
+
+/**
+ * Generate actionable suggestions based on status
+ * @param {Object} data - Status data
+ * @returns {string[]} Array of suggestions
+ */
+function generateSuggestions(data) {
+  const suggestions = [];
+
+  if (!data.spec) {
+    suggestions.push('Initialize CAWS: caws init .');
+  }
+
+  if (!data.hooks.installed) {
+    suggestions.push('Install Git hooks: caws hooks install');
+  }
+
+  if (!data.provenance.exists) {
+    suggestions.push('Initialize provenance tracking: caws provenance init');
+  }
+
+  if (data.spec && !data.hooks.installed && !data.provenance.exists) {
+    suggestions.push('Complete setup: caws scaffold');
+  }
+
+  return suggestions;
+}
+
+/**
+ * Status command handler
+ * @param {Object} options - Command options
+ */
+async function statusCommand(options = {}) {
+  try {
+    // Load all status data
+    const spec = await loadWorkingSpec(options.spec || '.caws/working-spec.yaml');
+    const hooks = await checkGitHooks();
+    const provenance = await loadProvenanceChain();
+    const gates = await checkQualityGates();
+
+    // Display status
+    displayStatus({
+      spec,
+      hooks,
+      provenance,
+      gates,
+    });
+  } catch (error) {
+    console.error(chalk.red('❌ Error checking project status:'), error.message);
+    console.error(chalk.yellow('\n💡 Try: caws validate to check your setup'));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  statusCommand,
+  loadWorkingSpec,
+  checkGitHooks,
+  loadProvenanceChain,
+  checkQualityGates,
+  displayStatus,
+  generateSuggestions,
+};

package/dist/commands/templates.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Templates command handler
+ * @param {string} subcommand - Subcommand (list, info)
+ * @param {Object} options - Command options
+ */
+export function templatesCommand(subcommand?: string, options?: any): Promise<void>;
+/**
+ * List all available templates
+ */
+export function listTemplates(): void;
+/**
+ * Show detailed template information
+ * @param {string} templateId - Template ID
+ */
+export function showTemplateInfo(templateId: string): void;
+/**
+ * Check which templates actually exist
+ * @returns {Object} Available templates
+ */
+export function getAvailableTemplates(): any;
+/**
+ * Built-in template definitions
+ */
+export const BUILTIN_TEMPLATES: {
+    'typescript-library': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+    'typescript-api': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+    'typescript-monorepo': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+    'javascript-package': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+    'react-component-lib': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+    'vscode-extension': {
+        name: string;
+        description: string;
+        category: string;
+        tier: number;
+        features: string[];
+        path: string;
+    };
+};
+//# sourceMappingURL=templates.d.ts.map

package/dist/commands/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/commands/templates.js"],"names":[],"mappings":"AAoMA;;;;GAIG;AACH,8CAHW,MAAM,gCA4BhB;AAvHD;;GAEG;AACH,sCAuCC;AAED;;;GAGG;AACH,6CAFW,MAAM,QAyChB;AA9GD;;;GAGG;AACH,6CAiBC;AA/FD;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDE"}

package/dist/commands/templates.js

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview CAWS Templates Command
+ * Discover and manage project templates
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Built-in template definitions
+ */
+const BUILTIN_TEMPLATES = {
+  'typescript-library': {
+    name: 'TypeScript Library',
+    description: 'Production-ready TypeScript library with Jest testing',
+    category: 'TypeScript',
+    tier: 2,
+    features: ['TypeScript', 'Jest', 'ESLint', 'Prettier', 'Publishing'],
+    path: 'templates/typescript/library',
+  },
+  'typescript-api': {
+    name: 'TypeScript API',
+    description: 'REST API with Express and TypeScript',
+    category: 'TypeScript',
+    tier: 1,
+    features: ['TypeScript', 'Express', 'Jest', 'OpenAPI', 'Docker'],
+    path: 'templates/typescript/api',
+  },
+  'typescript-monorepo': {
+    name: 'TypeScript Monorepo',
+    description: 'Multi-package TypeScript monorepo with Turbo',
+    category: 'TypeScript',
+    tier: 2,
+    features: ['TypeScript', 'Turborepo', 'Jest', 'Changesets'],
+    path: 'templates/typescript/monorepo',
+  },
+  'javascript-package': {
+    name: 'JavaScript Package',
+    description: 'NPM package with modern JavaScript',
+    category: 'JavaScript',
+    tier: 3,
+    features: ['JavaScript', 'Jest', 'ESLint', 'Publishing'],
+    path: 'templates/javascript/package',
+  },
+  'react-component-lib': {
+    name: 'React Component Library',
+    description: 'Reusable React component library with Storybook',
+    category: 'React',
+    tier: 2,
+    features: ['React', 'TypeScript', 'Storybook', 'Jest', 'Publishing'],
+    path: 'templates/react/component-library',
+  },
+  'vscode-extension': {
+    name: 'VS Code Extension',
+    description: 'VS Code extension with TypeScript',
+    category: 'Extension',
+    tier: 2,
+    features: ['TypeScript', 'VS Code API', 'Jest', 'Publishing'],
+    path: 'templates/vscode-extension',
+  },
+};
+
+/**
+ * Get template directory path
+ * @returns {string|null} Template directory path or null
+ */
+function getTemplateDir() {
+  const possiblePaths = [
+    path.join(__dirname, '../../templates'),
+    path.join(process.cwd(), 'packages/caws-cli/templates'),
+    path.join(process.cwd(), 'templates'),
+  ];
+
+  for (const testPath of possiblePaths) {
+    if (fs.existsSync(testPath)) {
+      return testPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check which templates actually exist
+ * @returns {Object} Available templates
+ */
+function getAvailableTemplates() {
+  const templateDir = getTemplateDir();
+  const available = {};
+
+  for (const [id, template] of Object.entries(BUILTIN_TEMPLATES)) {
+    const templatePath = templateDir
+      ? path.join(templateDir, template.path.replace('templates/', ''))
+      : null;
+
+    available[id] = {
+      ...template,
+      available: templatePath ? fs.existsSync(templatePath) : false,
+      fullPath: templatePath,
+    };
+  }
+
+  return available;
+}
+
+/**
+ * List all available templates
+ */
+function listTemplates() {
+  const templates = getAvailableTemplates();
+  const categories = {};
+
+  // Group by category
+  for (const [id, template] of Object.entries(templates)) {
+    if (!categories[template.category]) {
+      categories[template.category] = [];
+    }
+    categories[template.category].push({ id, ...template });
+  }
+
+  console.log(chalk.bold.cyan('\n📦 Available CAWS Templates\n'));
+
+  // Display by category
+  for (const [category, categoryTemplates] of Object.entries(categories)) {
+    console.log(chalk.bold.white(`${category}:`));
+
+    for (const template of categoryTemplates) {
+      const status = template.available ? chalk.green('✅') : chalk.gray('⏳');
+      console.log(`${status} ${chalk.bold(template.id.padEnd(25))} - ${template.description}`);
+      console.log(chalk.gray(`   Usage: caws init --template=${template.id} my-project`));
+      console.log(chalk.gray(`   Features: ${template.features.join(', ')}`));
+      console.log('');
+    }
+  }
+
+  const totalAvailable = Object.values(templates).filter((t) => t.available).length;
+  const totalTemplates = Object.keys(templates).length;
+
+  if (totalAvailable < totalTemplates) {
+    console.log(chalk.yellow(`\n⏳ ${totalTemplates - totalAvailable} templates coming soon`));
+  }
+
+  console.log(chalk.blue('\n📚 Learn more:'));
+  console.log(chalk.blue('   caws templates --help'));
+  console.log(chalk.blue('   docs/guides/template-usage.md'));
+
+  console.log('');
+}
+
+/**
+ * Show detailed template information
+ * @param {string} templateId - Template ID
+ */
+function showTemplateInfo(templateId) {
+  const templates = getAvailableTemplates();
+  const template = templates[templateId];
+
+  if (!template) {
+    console.error(chalk.red(`\n❌ Template not found: ${templateId}`));
+    console.error(chalk.yellow('\n💡 Available templates:'));
+    console.error(chalk.yellow(`   ${Object.keys(templates).join(', ')}`));
+    console.error(chalk.yellow('\n💡 Try: caws templates list'));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.cyan(`\n📦 Template: ${template.name}\n`));
+  console.log(chalk.white(`Description: ${template.description}`));
+  console.log(chalk.white(`Category: ${template.category}`));
+  console.log(chalk.white(`Risk Tier: ${template.tier}`));
+  console.log(
+    chalk.white(
+      `Status: ${template.available ? chalk.green('Available') : chalk.yellow('Coming Soon')}`
+    )
+  );
+
+  console.log(chalk.bold.white('\nFeatures:'));
+  template.features.forEach((feature) => {
+    console.log(chalk.gray(`   • ${feature}`));
+  });
+
+  console.log(chalk.bold.white('\nUsage:'));
+  console.log(chalk.cyan(`   caws init --template=${templateId} my-project`));
+  console.log(chalk.cyan(`   cd my-project`));
+  console.log(chalk.cyan(`   npm install`));
+  console.log(chalk.cyan(`   npm test`));
+
+  if (template.available && template.fullPath) {
+    console.log(chalk.bold.white('\nTemplate Location:'));
+    console.log(chalk.gray(`   ${template.fullPath}`));
+  }
+
+  console.log('');
+}
+
+/**
+ * Templates command handler
+ * @param {string} subcommand - Subcommand (list, info)
+ * @param {Object} options - Command options
+ */
+async function templatesCommand(subcommand = 'list', options = {}) {
+  try {
+    switch (subcommand) {
+      case 'list':
+        listTemplates();
+        break;
+
+      case 'info':
+        if (!options.name) {
+          console.error(chalk.red('\n❌ Template name required'));
+          console.error(chalk.yellow('💡 Usage: caws templates info <template-name>'));
+          console.error(chalk.yellow('💡 Try: caws templates list to see available templates'));
+          process.exit(1);
+        }
+        showTemplateInfo(options.name);
+        break;
+
+      default:
+        listTemplates();
+    }
+  } catch (error) {
+    console.error(chalk.red('\n❌ Error:'), error.message);
+    console.error(chalk.yellow('\n💡 Try: caws templates list'));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  templatesCommand,
+  listTemplates,
+  showTemplateInfo,
+  getAvailableTemplates,
+  BUILTIN_TEMPLATES,
+};

package/dist/error-handler.d.ts

@@ -32,9 +32,10 @@ export function safeAsync(operation: Function, context?: string): Promise<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, exit?: boolean): void;
+export function handleCliError(error: Error, context?: any, exit?: boolean): void;
 /**
  * Validate required environment and dependencies
  * @returns {Object} Validation result with any errors
@@ -44,7 +45,31 @@ 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): string[];
+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[];
+};
 //# sourceMappingURL=error-handler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.js"],"names":[],"mappings":"AA0GA;;GAEG;AACH;IACE,+DAKC;IAFC,cAAqD;IACrD,mBAA2F;CAE9F;;;;;;;;;;;AA9ED;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA+DlB;AAcD;;;;;GAKG;AACH,yDAHW,MAAM,GACJ,OAAO,CAAC,GAAG,CAAC,CAexB;AAkDD;;;;GAIG;AACH,sCAHW,KAAK,SACL,OAAO,QAyBjB;AAED;;;GAGG;AACH,2CAqBC;AAvGD;;;;;GAKG;AACH,8CAJW,KAAK,YACL,MAAM,GACJ,MAAM,EAAE,CA0CpB"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.js"],"names":[],"mappings":"AA0GA;;GAEG;AACH;IACE,+DAKC;IAFC,cAAqD;IACrD,mBAA2F;CAE9F;;;;;;;;;;;AA9ED;;;;GAIG;AACH,wCAHW,KAAK,GAAC,MAAM,GACV,MAAM,CA+DlB;AAcD;;;;;GAKG;AACH,yDAHW,MAAM,GACJ,OAAO,CAAC,GAAG,CAAC,CAexB;AA4ND;;;;;GAKG;AACH,sCAJW,KAAK,wBAEL,OAAO,QAsBjB;AAED;;;GAGG;AACH,2CAqBC;AAtJD;;;;;;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;AArFD;;GAEG;AACH;;;;;EA2DE"}