@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/commands/quality-monitor.js

@@ -8,9 +8,8 @@
  */
 
 const chalk = require('chalk');
-const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
+const { resolveSpec } = require('../utils/spec-resolver');
 
 /**
  * Analyze quality impact of an action
@@ -79,52 +78,58 @@ function analyzeQualityImpact(action, files = [], context = {}) {
       analysis.recommendations = ['Run CAWS evaluation to assess impact'];
   }
 
-  // Load working spec to check risk tier
-  try {
-    const specPath = path.join(process.cwd(), '.caws/working-spec.yaml');
-    if (fs.existsSync(specPath)) {
-      const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
-      const projectTier = spec.risk_tier;
-
-      analysis.project_tier = projectTier;
-
-      // Add context-specific recommendations for high-risk projects
-      if (projectTier <= 2) {
-        analysis.recommendations.unshift(
-          'High-risk project (Tier ' + projectTier + '): Run comprehensive validation'
-        );
-        if (analysis.risk_level === 'low') {
-          analysis.risk_level = 'medium';
-        } else if (analysis.risk_level === 'medium') {
-          analysis.risk_level = 'high';
-        }
-      }
+  // Add context-based recommendations
+  if (context.project_tier) {
+    analysis.project_tier = context.project_tier;
+  }
 
-      // Add tier-specific quality gates
-      if (projectTier === 1) {
-        analysis.quality_gates = [
-          'Branch coverage ≥ 90%',
-          'Mutation score ≥ 70%',
-          'All contract tests passing',
-          'Manual code review required',
-        ];
-      } else if (projectTier === 2) {
-        analysis.quality_gates = [
-          'Branch coverage ≥ 80%',
-          'Mutation score ≥ 50%',
-          'Contract tests passing (if applicable)',
-        ];
-      } else {
-        analysis.quality_gates = ['Branch coverage ≥ 70%', 'Mutation score ≥ 30%'];
-      }
+  return analysis;
+}
+
+/**
+ * Enrich analysis with project tier and resolved spec metadata.
+ * @param {Object} analysis
+ * @param {Object|null} resolvedSpec
+ * @returns {Object}
+ */
+function applySpecContext(analysis, resolvedSpec) {
+  if (!resolvedSpec?.spec) {
+    return analysis;
+  }
+
+  const projectTier = resolvedSpec.spec.risk_tier;
+  analysis.project_tier = projectTier;
+  analysis.spec_id = resolvedSpec.spec.id || null;
+  analysis.spec_path = resolvedSpec.path
+    ? path.relative(process.cwd(), resolvedSpec.path)
+    : null;
+
+  if (projectTier <= 2) {
+    analysis.recommendations.unshift(
+      'High-risk project (Tier ' + projectTier + '): Run comprehensive validation'
+    );
+    if (analysis.risk_level === 'low') {
+      analysis.risk_level = 'medium';
+    } else if (analysis.risk_level === 'medium') {
+      analysis.risk_level = 'high';
     }
-  } catch (error) {
-    // Ignore if we can't load spec
   }
 
-  // Add context-based recommendations
-  if (context.project_tier) {
-    analysis.project_tier = context.project_tier;
+  if (projectTier === 1) {
+    analysis.quality_gates = [
+      'Branch coverage ≥ 90%',
+      'Mutation score ≥ 70%',
+      'All contract tests passing',
+      'Manual code review required',
+    ];
+  } else if (projectTier === 2) {
+    analysis.quality_gates = [
+      'Branch coverage ≥ 80%',
+      'Mutation score ≥ 50%',
+      'Contract tests passing (if applicable)',
+    ];
+  } else {
+    analysis.quality_gates = ['Branch coverage ≥ 70%', 'Mutation score ≥ 30%'];
   }
 
   return analysis;
@@ -170,7 +175,18 @@ async function qualityMonitorCommand(action, options = {}) {
     }
 
     // Analyze quality impact
-    const analysis = analyzeQualityImpact(action, files, context);
+    let analysis = analyzeQualityImpact(action, files, context);
+
+    try {
+      const resolved = await resolveSpec({
+        specId: options.specId,
+        warnLegacy: false,
+        interactive: false,
+      });
+      analysis = applySpecContext(analysis, resolved);
+    } catch {
+      // Best-effort enrichment only
+    }
 
     // Display results
     console.log(chalk.bold('\nCAWS Quality Monitor\n'));
@@ -219,6 +235,9 @@ async function qualityMonitorCommand(action, options = {}) {
     // Project tier
     if (analysis.project_tier) {
       console.log(chalk.bold(`\nProject Tier: ${analysis.project_tier}`));
+      if (analysis.spec_id) {
+        console.log(chalk.gray(`Spec: ${analysis.spec_id}${analysis.spec_path ? ` (${analysis.spec_path})` : ''}`));
+      }
     }
 
     // Quality gates

package/dist/commands/scope.js

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview CAWS Scope CLI Command
+ * Inspects and displays effective scope boundaries for the current context
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const {
+  getRepoRoot,
+  loadRegistry,
+  findFeatureSpecPath,
+  WORKTREES_DIR,
+} = require('../worktree/worktree-manager');
+
+/**
+ * Handle scope subcommands
+ * @param {string} subcommand - Subcommand name
+ * @param {Object} options - Command options
+ */
+async function scopeCommand(subcommand, options = {}) {
+  try {
+    switch (subcommand) {
+      case 'show':
+        return handleShow(options);
+      default:
+        console.error(chalk.red(`Unknown scope subcommand: ${subcommand}`));
+        console.log(chalk.blue('Available: show'));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Detect if current working directory is inside a worktree
+ * @param {string} root - Repository root
+ * @returns {{ inWorktree: boolean, worktreeName: string|null }}
+ */
+function detectWorktreeContext(root) {
+  const cwd = process.cwd();
+  const worktreesBase = path.join(root, WORKTREES_DIR);
+
+  if (!cwd.startsWith(worktreesBase + path.sep) && cwd !== worktreesBase) {
+    return { inWorktree: false, worktreeName: null };
+  }
+
+  // Extract worktree name: first path segment after the worktrees dir
+  const relative = path.relative(worktreesBase, cwd);
+  const worktreeName = relative.split(path.sep)[0];
+
+  if (!worktreeName) {
+    return { inWorktree: false, worktreeName: null };
+  }
+
+  return { inWorktree: true, worktreeName };
+}
+
+/**
+ * Load a spec file and return its parsed contents
+ * @param {string} specPath - Absolute path to spec YAML
+ * @returns {Object|null}
+ */
+function loadSpec(specPath) {
+  try {
+    if (!fs.existsSync(specPath)) return null;
+    const content = fs.readFileSync(specPath, 'utf8');
+    return yaml.load(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find all active spec files in .caws/specs/
+ * @param {string} root - Repository root
+ * @returns {Array<{ id: string, path: string, data: Object }>}
+ */
+function findAllActiveSpecs(root) {
+  const specsDir = path.join(root, '.caws', 'specs');
+  if (!fs.existsSync(specsDir)) return [];
+
+  const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  const specs = [];
+
+  for (const file of files) {
+    const specPath = path.join(specsDir, file);
+    const data = loadSpec(specPath);
+    if (!data) continue;
+
+    // Skip closed/archived specs
+    const status = (data.status || '').toLowerCase();
+    if (status === 'closed' || status === 'archived') continue;
+
+    const id = path.basename(file, path.extname(file));
+    specs.push({ id, path: specPath, data });
+  }
+
+  return specs;
+}
+
+/**
+ * Print scope patterns for a spec
+ * @param {Object} data - Parsed spec YAML
+ * @param {string} indent - Indentation prefix
+ */
+function printScopePatterns(data, indent = '   ') {
+  const scope = data.scope || {};
+  const scopeIn = scope.in || scope.include || [];
+  const scopeOut = scope.out || scope.exclude || [];
+
+  if (scopeIn.length > 0) {
+    console.log(chalk.green(`${indent}scope.in:`));
+    for (const pattern of scopeIn) {
+      console.log(chalk.gray(`${indent}  - ${pattern}`));
+    }
+  } else {
+    console.log(chalk.yellow(`${indent}scope.in: (none defined)`));
+  }
+
+  if (scopeOut.length > 0) {
+    console.log(chalk.red(`${indent}scope.out:`));
+    for (const pattern of scopeOut) {
+      console.log(chalk.gray(`${indent}  - ${pattern}`));
+    }
+  } else {
+    console.log(chalk.gray(`${indent}scope.out: (none)`));
+  }
+}
+
+/**
+ * Handle the 'show' subcommand
+ * @param {Object} options - Command options
+ */
+function handleShow(_options) {
+  const root = getRepoRoot();
+  const { inWorktree, worktreeName } = detectWorktreeContext(root);
+
+  console.log(chalk.bold.cyan('CAWS Scope Inspector'));
+  console.log(chalk.cyan('='.repeat(50)));
+  console.log('');
+
+  if (inWorktree) {
+    return handleAuthoritativeMode(root, worktreeName);
+  } else {
+    return handleUnionMode(root);
+  }
+}
+
+/**
+ * Handle authoritative mode: agent is inside a worktree with a bound spec
+ * @param {string} root - Repository root
+ * @param {string} worktreeName - Name of the worktree
+ */
+function handleAuthoritativeMode(root, worktreeName) {
+  console.log(chalk.white(`Worktree: ${chalk.bold(worktreeName)}`));
+
+  const registry = loadRegistry(root);
+  const entry = registry.worktrees ? registry.worktrees[worktreeName] : null;
+
+  if (!entry) {
+    console.log(chalk.red(`Worktree '${worktreeName}' not found in registry.`));
+    console.log(chalk.yellow('The scope guard is operating in union mode (all active specs).'));
+    return handleUnionMode(root);
+  }
+
+  const specId = entry.specId;
+
+  if (!specId) {
+    console.log(chalk.yellow('Mode: union (no spec bound to this worktree)'));
+    console.log('');
+    console.log(chalk.yellow('This worktree has no spec binding. The scope guard checks'));
+    console.log(chalk.yellow('against the union of all active specs.'));
+    console.log('');
+    console.log(chalk.blue('To bind a spec: caws worktree bind <spec-id>'));
+    console.log('');
+    return handleUnionMode(root);
+  }
+
+  // Load the spec
+  const specPath = findFeatureSpecPath(root, specId);
+  if (!specPath) {
+    console.log(chalk.red(`Bound spec '${specId}' not found on disk.`));
+    console.log(chalk.yellow('Fix: recreate the spec or rebind with a valid spec ID.'));
+    console.log(chalk.blue(`  caws worktree bind <valid-spec-id>`));
+    return;
+  }
+
+  const specData = loadSpec(specPath);
+  if (!specData) {
+    console.log(chalk.red(`Failed to parse spec file: ${specPath}`));
+    return;
+  }
+
+  console.log(chalk.green(`Mode: authoritative (single bound spec)`));
+  console.log(chalk.white(`Spec: ${chalk.bold(specId)}`));
+  if (specData.title) {
+    console.log(chalk.gray(`Title: ${specData.title}`));
+  }
+  console.log('');
+
+  // Print scope patterns
+  printScopePatterns(specData);
+  console.log('');
+
+  // Check binding health: mutual reference
+  const specWorktreeRef = specData.worktree || null;
+  const registrySpecRef = specId;
+
+  if (specWorktreeRef !== worktreeName) {
+    console.log(chalk.yellow('Binding health: BROKEN'));
+    console.log(chalk.yellow(`  Registry points to spec '${registrySpecRef}'`));
+    console.log(chalk.yellow(`  Spec 'worktree' field: ${specWorktreeRef || '(missing)'} (expected: ${worktreeName})`));
+    console.log('');
+    console.log(chalk.blue(`Fix: caws worktree bind ${specId}`));
+  } else {
+    console.log(chalk.green('Binding health: OK'));
+    console.log(chalk.gray(`  Registry -> spec: ${registrySpecRef}`));
+    console.log(chalk.gray(`  Spec -> worktree: ${specWorktreeRef}`));
+  }
+}
+
+/**
+ * Handle union mode: no worktree or no spec binding
+ * @param {string} root - Repository root
+ */
+function handleUnionMode(root) {
+  const specs = findAllActiveSpecs(root);
+
+  if (specs.length === 0) {
+    console.log(chalk.gray('Mode: union (no active specs found)'));
+    console.log('');
+    console.log(chalk.gray('No active feature specs in .caws/specs/.'));
+    console.log(chalk.gray('The scope guard has no patterns to enforce.'));
+    console.log('');
+    console.log(chalk.blue('Create a spec: caws specs create <id> --title "description"'));
+    return;
+  }
+
+  console.log(chalk.white('Mode: union (checking all active specs)'));
+  console.log(chalk.gray(`Active specs: ${specs.length}`));
+  console.log('');
+
+  for (const spec of specs) {
+    const statusLabel = spec.data.status || 'draft';
+    console.log(chalk.white(`  ${chalk.bold(spec.id)} [${statusLabel}]`));
+    if (spec.data.title) {
+      console.log(chalk.gray(`  Title: ${spec.data.title}`));
+    }
+    printScopePatterns(spec.data, '    ');
+
+    // Check if this spec has a worktree binding
+    if (spec.data.worktree) {
+      console.log(chalk.gray(`    worktree: ${spec.data.worktree}`));
+    }
+    console.log('');
+  }
+}
+
+module.exports = { scopeCommand };

package/dist/commands/sidecar.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview CAWS Sidecar Command
+ * CLI interface for bounded governance sidecars — advisory analysis modules
+ * that consume working state and produce structured recommendations.
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const { resolveSpec } = require('../utils/spec-resolver');
+// EVLOG-002 Phase 2 read flip: sidecars read state from the event log via the
+// pure renderer. loadStateFromEvents matches loadState's null contract exactly,
+// so the existing "state may be null — sidecars handle that" behavior stays.
+const { loadStateFromEvents } = require('../utils/event-renderer');
+const { commandWrapper } = require('../utils/command-wrapper');
+const { SIDECARS, formatSidecarText } = require('../sidecars');
+
+/**
+ * Run a sidecar analysis.
+ * @param {string} subcommand - Sidecar name (drift, gaps, waiver-draft, provenance)
+ * @param {Object} options - Command options
+ * @param {string} [options.specId] - Target spec ID
+ * @param {boolean} [options.json] - Output as JSON
+ * @param {string} [options.gate] - Gate name filter (waiver-draft only)
+ */
+async function sidecarCommand(subcommand, options = {}) {
+  return commandWrapper(
+    async () => {
+      const sidecar = SIDECARS[subcommand];
+      if (!sidecar) {
+        const available = Object.keys(SIDECARS).join(', ');
+        console.error(chalk.red(`Unknown sidecar: ${subcommand}`));
+        console.error(chalk.yellow(`Available: ${available}`));
+        process.exit(1);
+      }
+
+      // Resolve spec
+      let spec = null;
+      try {
+        const resolved = await resolveSpec({
+          specId: options.specId,
+          warnLegacy: false,
+          quiet: Boolean(options.json),
+        });
+        spec = resolved.spec;
+      } catch (err) {
+        console.error(chalk.red(`Could not resolve spec: ${err.message}`));
+        console.error(chalk.yellow('Use --spec-id <id> to target a specific spec.'));
+        process.exit(1);
+      }
+
+      // Load working state (may be null — sidecars handle that; EVLOG-002: from event log)
+      const state = loadStateFromEvents(spec.id);
+
+      // Build sidecar-specific options
+      const sidecarOptions = {};
+      if (options.gate) sidecarOptions.gateName = options.gate;
+
+      // Run sidecar
+      const result = sidecar.fn(state, spec, sidecarOptions);
+
+      // Output
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatSidecarText(result));
+      }
+
+      return result;
+    },
+    { commandName: `sidecar ${subcommand}` }
+  );
+}
+
+module.exports = { sidecarCommand };