@paths.design/caws-cli 7.0.3 → 8.0.0

package/dist/commands/quality-gates.js

@@ -44,14 +44,66 @@ async function qualityGatesCommand(options = {}) {
       const packagesDir = path.dirname(cliPackageDir);
       const monorepoRunner = path.join(packagesDir, 'quality-gates', 'run-quality-gates.mjs');
 
-      // Option 2: Check VS Code extension bundled (if running from extension context)
+      // Option 2: Check globally installed CLI for bundled quality gates
+      let globalCliPath = null;
+      try {
+        const { execSync } = require('child_process');
+        const whichCaws = execSync('which caws', { encoding: 'utf8', stdio: 'pipe' }).trim();
+        if (whichCaws) {
+          // Resolve symlink to actual path
+          const realPath = fs.realpathSync(whichCaws);
+          const globalCliDir = path.dirname(realPath);
+          // Check for bundled quality gates in global CLI installation
+          const possibleBundledPaths = [
+            path.join(
+              globalCliDir,
+              '..',
+              'lib',
+              'node_modules',
+              '@paths.design',
+              'caws-cli',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+            path.join(
+              globalCliDir,
+              '..',
+              'lib',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+            path.join(
+              globalCliDir,
+              '..',
+              'node_modules',
+              '@paths.design',
+              'quality-gates',
+              'run-quality-gates.mjs'
+            ),
+          ];
+          for (const bundledPath of possibleBundledPaths) {
+            if (fs.existsSync(bundledPath)) {
+              globalCliPath = bundledPath;
+              break;
+            }
+          }
+        }
+      } catch (e) {
+        // Ignore errors finding global CLI
+      }
+
+      // Option 3: Check VS Code extension bundled (if running from extension context)
       const vscodeExtensionPath =
         process.env.VSCODE_EXTENSION_PATH || process.env.VSCODE_EXTENSION_DIR;
       const bundledRunner = vscodeExtensionPath
         ? path.join(vscodeExtensionPath, 'bundled', 'quality-gates', 'run-quality-gates.mjs')
         : null;
 
-      // Option 3: Check node_modules for quality-gates package (prioritize published package)
+      // Option 4: Check node_modules for quality-gates package (prioritize published package)
       const nodeModulesPaths = [
         // Published npm package (priority)
         path.join(
@@ -69,6 +121,8 @@ async function qualityGatesCommand(options = {}) {
       // Try all possible paths in order
       if (fs.existsSync(monorepoRunner)) {
         qualityGatesRunner = monorepoRunner;
+      } else if (globalCliPath) {
+        qualityGatesRunner = globalCliPath;
       } else if (bundledRunner && fs.existsSync(bundledRunner)) {
         qualityGatesRunner = bundledRunner;
       } else {
@@ -132,14 +186,98 @@ async function qualityGatesCommand(options = {}) {
         }
       }
 
-      // If still no runner found, provide helpful error
+      // Option 5: Try npx (no installation required) - works if Node.js is available
       if (!qualityGatesRunner) {
-        const suggestions = [
-          'Install quality gates package: npm install -g @paths.design/quality-gates',
-          'Use Python script (if available): python3 scripts/simple_gates.py all --tier 2 --profile backend-api',
-          'Use Makefile target (if available): make caws-gates',
-          'Run from CAWS monorepo root',
-        ];
+        try {
+          const { execSync } = require('child_process');
+          // Check if npx is available
+          execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+
+          Output.info('Using npx to run quality gates (no installation required)...');
+
+          // Build npx command - the package exposes 'caws-quality-gates' bin command
+          // Use npx to download and run without installing
+          const npxArgs = ['npx', '--yes', '@paths.design/quality-gates'];
+
+          // Map CLI options to runner options
+          if (options.ci) {
+            npxArgs.push('--ci');
+          }
+          if (options.json) {
+            npxArgs.push('--json');
+          }
+          if (options.gates && options.gates.trim()) {
+            npxArgs.push('--gates', options.gates.trim());
+          }
+          if (options.fix) {
+            npxArgs.push('--fix');
+          }
+
+          Output.progress('Executing quality gates via npx...');
+          Output.info(`Command: ${npxArgs.join(' ')}`);
+
+          // Execute via npx
+          const { execSync: execSyncNpx } = require('child_process');
+          execSyncNpx(npxArgs.join(' '), {
+            stdio: 'inherit',
+            cwd: projectRoot,
+            env: {
+              ...process.env,
+              CAWS_CLI_INTEGRATION: 'true',
+              CAWS_CLI_VERSION: require(path.join(cliPackageDir, 'package.json')).version,
+            },
+          });
+
+          Output.success('Quality gates completed successfully');
+          return;
+        } catch (npxError) {
+          // npx not available or failed - continue to error message
+        }
+      }
+
+      // If still no runner found, provide helpful error with language-agnostic suggestions
+      if (!qualityGatesRunner) {
+        // Check if Node.js/npx is available (language-agnostic check)
+        let hasNodeJs = false;
+        try {
+          const { execSync } = require('child_process');
+          execSync('command -v node', { encoding: 'utf8', stdio: 'ignore' });
+          execSync('command -v npx', { encoding: 'utf8', stdio: 'ignore' });
+          hasNodeJs = true;
+        } catch (e) {
+          // Node.js/npx not available
+        }
+
+        const suggestions = [];
+
+        if (hasNodeJs) {
+          // Node.js available - suggest npx (works for any language, no installation)
+          suggestions.push(
+            'Use npx (no installation required): npx --yes @paths.design/quality-gates'
+          );
+          suggestions.push('Install globally: npm install -g @paths.design/quality-gates');
+          suggestions.push('Install locally: npm install --save-dev @paths.design/quality-gates');
+        } else {
+          // Node.js not available - suggest installation or alternatives
+          suggestions.push('Install Node.js to use quality gates: https://nodejs.org/');
+          suggestions.push(
+            'Then use: npx --yes @paths.design/quality-gates (no installation required)'
+          );
+          suggestions.push('Or install globally: npm install -g @paths.design/quality-gates');
+        }
+
+        // Language-agnostic fallback options (if they exist)
+        const pythonScript = path.join(projectRoot, 'scripts', 'simple_gates.py');
+        const makefile = path.join(projectRoot, 'Makefile');
+
+        if (fs.existsSync(pythonScript)) {
+          suggestions.push(`Use project script: python3 ${pythonScript} all --tier 2`);
+        }
+        if (fs.existsSync(makefile)) {
+          suggestions.push('Use Makefile target: make caws-gates');
+        }
+
+        suggestions.push('Run from CAWS monorepo root (if developing CAWS itself)');
 
         throw new Error(
           'Quality gates runner not found.\n\n' +

package/dist/commands/specs.js

@@ -154,9 +154,13 @@ async function createSpec(id, options = {}) {
         console.log(chalk.blue('ℹ️  Spec creation canceled.'));
         return null;
       } else if (answer === 'rename') {
-        // Generate new name with timestamp suffix
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-        const newId = `${id}-${timestamp}`;
+        // Generate new name with valid PREFIX-NUMBER format
+        // Extract prefix from existing ID or use default
+        const prefixMatch = id.match(/^([A-Z]+)-\d+$/);
+        const prefix = prefixMatch ? prefixMatch[1] : 'FEAT';
+        // Generate sequential number based on timestamp
+        const number = Date.now().toString().slice(-6); // Last 6 digits of timestamp
+        const newId = `${prefix}-${number}`;
         console.log(chalk.blue(`📝 Creating spec with new name: ${newId}`));
         return await createSpec(newId, { ...options, interactive: false });
       } else if (answer === 'merge') {
@@ -183,9 +187,10 @@ async function createSpec(id, options = {}) {
   // Ensure specs directory exists
   await fs.ensureDir(SPECS_DIR);
 
-  // Generate spec content
-  const specContent = {
-    id,
+  // Generate spec content with all required fields
+  // Merge template carefully to preserve required fields and structure
+  const defaultSpec = {
+    id, // Always use the provided id parameter
     type,
     title,
     status: 'draft',
@@ -193,8 +198,64 @@ async function createSpec(id, options = {}) {
     mode,
     created_at: new Date().toISOString(),
     updated_at: new Date().toISOString(),
-    acceptance_criteria: [],
+    // Required fields for validation
+    blast_radius: {
+      modules: [],
+      data_migration: false,
+    },
+    operational_rollback_slo: '5m',
+    scope: {
+      in: ['src/', 'tests/'],
+      out: ['node_modules/', 'dist/', 'build/'],
+    },
+    invariants: ['System maintains data consistency'],
+    acceptance: [], // Note: validation expects 'acceptance', not 'acceptance_criteria'
+    acceptance_criteria: [], // Keep for backward compatibility
+    non_functional: {
+      a11y: [],
+      perf: {},
+      security: [],
+    },
+    contracts: [],
+  };
+
+  // Merge template, but preserve required structure
+  // Map template.criteria to acceptance if present
+  const templateAcceptance = template?.criteria || template?.acceptance;
+
+  const specContent = {
+    ...defaultSpec,
     ...(template || {}),
+    // Always preserve these critical fields
+    id, // Never allow template to override id
+    // Map criteria to acceptance if template uses criteria
+    acceptance: templateAcceptance || defaultSpec.acceptance,
+    acceptance_criteria: templateAcceptance || defaultSpec.acceptance_criteria,
+    // Deep merge scope if template provides it
+    scope: template?.scope
+      ? {
+          in: template.scope.in || defaultSpec.scope.in,
+          out: template.scope.out || defaultSpec.scope.out,
+        }
+      : defaultSpec.scope,
+    // Deep merge blast_radius if template provides it
+    blast_radius: template?.blast_radius
+      ? {
+          modules: template.blast_radius.modules || defaultSpec.blast_radius.modules,
+          data_migration:
+            template.blast_radius.data_migration !== undefined
+              ? template.blast_radius.data_migration
+              : defaultSpec.blast_radius.data_migration,
+        }
+      : defaultSpec.blast_radius,
+    // Deep merge non_functional if template provides it
+    non_functional: template?.non_functional
+      ? {
+          a11y: template.non_functional.a11y || defaultSpec.non_functional.a11y,
+          perf: template.non_functional.perf || defaultSpec.non_functional.perf,
+          security: template.non_functional.security || defaultSpec.non_functional.security,
+        }
+      : defaultSpec.non_functional,
   };
 
   // Create file path
@@ -442,9 +503,10 @@ function displaySpecDetails(spec) {
 /**
  * Migrate from legacy working-spec.yaml to feature-specific specs
  * @param {Object} options - Migration options
+ * @param {Function} [createSpecFn] - Function to create specs (for testing)
  * @returns {Promise<Object>} Migration result
  */
-async function migrateFromLegacy(options = {}) {
+async function migrateFromLegacy(options = {}, createSpecFn = createSpec) {
   const fs = require('fs-extra');
   const path = require('path');
   const yaml = require('js-yaml');
@@ -461,6 +523,14 @@ async function migrateFromLegacy(options = {}) {
   const legacyContent = await fs.readFile(legacyPath, 'utf8');
   const legacySpec = yaml.load(legacyContent);
 
+  if (!legacySpec) {
+    throw new Error('Legacy working-spec.yaml is empty or invalid');
+  }
+
+  if (!legacySpec.acceptance || !Array.isArray(legacySpec.acceptance)) {
+    throw new Error('Legacy working-spec.yaml must have an acceptance array');
+  }
+
   // Suggest feature breakdown based on acceptance criteria
   const features = suggestFeatureBreakdown(legacySpec);
 
@@ -480,15 +550,32 @@ async function migrateFromLegacy(options = {}) {
   }
 
   if (options.features && options.features.length > 0) {
+    // Filter by original feature IDs (before transformation)
     selectedFeatures = features.filter((f) => options.features.includes(f.id));
-    console.log(chalk.blue(`\n📋 Migrating selected features: ${options.features.join(', ')}`));
+    if (selectedFeatures.length === 0) {
+      const errorMsg = `No features found matching: ${options.features.join(', ')}. Available features: ${features.map((f) => f.id).join(', ')}`;
+      console.log(chalk.yellow(`⚠️  ${errorMsg}`));
+      throw new Error(errorMsg);
+    } else {
+      console.log(chalk.blue(`\n📋 Migrating selected features: ${options.features.join(', ')}`));
+    }
   }
 
   // Create each feature spec
   const createdSpecs = [];
+  let featureCounter = 1;
   for (const feature of selectedFeatures) {
     try {
-      await createSpec(feature.id, {
+      // Transform feature ID to proper format (PREFIX-NUMBER) if needed
+      let specId = feature.id;
+      if (!/^[A-Z]+-\d+$/.test(specId)) {
+        // Convert 'auth' -> 'FEAT-001', 'payment' -> 'FEAT-002', etc.
+        const prefix = specId.toUpperCase().replace(/[^A-Z0-9]/g, '');
+        specId = `${prefix || 'FEAT'}-${String(featureCounter).padStart(3, '0')}`;
+        featureCounter++;
+      }
+
+      await createSpecFn(specId, {
         type: 'feature',
         title: feature.title,
         risk_tier: 'T3', // Default tier
@@ -496,10 +583,14 @@ async function migrateFromLegacy(options = {}) {
         template: feature,
       });
 
-      createdSpecs.push(feature.id);
-      console.log(chalk.green(`   ✅ Created spec: ${feature.id}`));
+      createdSpecs.push(specId);
+      console.log(chalk.green(`   ✅ Created spec: ${specId}`));
     } catch (error) {
+      // Log full error details for debugging
       console.log(chalk.red(`   ❌ Failed to create spec ${feature.id}: ${error.message}`));
+      if (process.env.DEBUG_MIGRATION) {
+        console.log(chalk.gray(`   Error details: ${error.stack}`));
+      }
     }
   }
 
@@ -628,7 +719,11 @@ async function specsCommand(action, options = {}) {
         }
 
         case 'migrate': {
-          const result = await migrateFromLegacy(options);
+          // Allow tests to inject createSpec function
+          const createSpecFn = options._createSpecFn || createSpec;
+          const migrationOptions = { ...options };
+          delete migrationOptions._createSpecFn; // Remove test-only option
+          const result = await migrateFromLegacy(migrationOptions, createSpecFn);
 
           return outputResult({
             command: 'specs migrate',

package/dist/commands/tool.js

@@ -4,7 +4,6 @@
  * @author @darianrosebrook
  */
 
-const path = require('path');
 const { commandWrapper, Output } = require('../utils/command-wrapper');
 
 // Import tool system