@paths.design/caws-cli 3.4.0 → 4.0.0

package/dist/commands/validate.js

@@ -10,10 +10,14 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 
 // Import validation functionality
-const { validateWorkingSpecWithSuggestions } = require('../validation/spec-validation');
+const {
+  validateWorkingSpecWithSuggestions,
+  getComplianceGrade,
+} = require('../validation/spec-validation');
 
 /**
  * Validate command handler
+ * Enhanced with JSON output format support
  * @param {string} specFile - Path to spec file
  * @param {Object} options - Command options
  */
@@ -22,55 +26,128 @@ async function validateCommand(specFile, options) {
     let specPath = specFile || path.join('.caws', 'working-spec.yaml');
 
     if (!fs.existsSync(specPath)) {
-      console.error(chalk.red(`❌ Spec file not found: ${specPath}`));
-      console.error(chalk.blue('💡 Run "caws init" first to create a working spec'));
+      if (options.format === 'json') {
+        console.log(
+          JSON.stringify(
+            {
+              passed: false,
+              verdict: 'fail',
+              errors: [
+                {
+                  field: 'spec_file',
+                  message: `Spec file not found: ${specPath}`,
+                  suggestion: 'Run "caws init" first to create a working spec',
+                },
+              ],
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.error(chalk.red(`❌ Spec file not found: ${specPath}`));
+        console.error(chalk.blue('💡 Run "caws init" first to create a working spec'));
+      }
       process.exit(1);
     }
 
     const specContent = fs.readFileSync(specPath, 'utf8');
     const spec = yaml.load(specContent);
 
-    console.log(chalk.cyan('🔍 Validating CAWS working spec...'));
+    if (options.format !== 'json') {
+      console.log(chalk.cyan('🔍 Validating CAWS working spec...'));
+    }
 
     const result = validateWorkingSpecWithSuggestions(spec, {
       autoFix: options.autoFix,
+      dryRun: options.dryRun,
       suggestions: !options.quiet,
       checkBudget: true,
       projectRoot: path.dirname(specPath),
     });
 
-    if (result.valid) {
-      console.log(chalk.green('✅ Working spec validation passed'));
-      if (!options.quiet) {
-        console.log(chalk.gray(`   Risk tier: ${spec.risk_tier}`));
-        console.log(chalk.gray(`   Mode: ${spec.mode}`));
-        if (spec.title) {
-          console.log(chalk.gray(`   Title: ${spec.title}`));
-        }
+    // Format output based on requested format
+    if (options.format === 'json') {
+      // Structured JSON output matching CAWSValidationResult
+      const jsonResult = {
+        passed: result.valid,
+        cawsVersion: '3.4.0',
+        timestamp: new Date().toISOString(),
+        verdict: result.valid ? 'pass' : 'fail',
+        spec: {
+          id: spec.id,
+          title: spec.title,
+          risk_tier: spec.risk_tier,
+          mode: spec.mode,
+        },
+        validation: {
+          errors: result.errors || [],
+          warnings: result.warnings || [],
+          fixes: result.fixes || [],
+        },
+        budgetCompliance: result.budget_check || null,
+      };
+
+      console.log(JSON.stringify(jsonResult, null, 2));
+
+      if (!result.valid) {
+        process.exit(1);
       }
     } else {
-      console.log(chalk.red('❌ Working spec validation failed'));
-
-      // Show errors
-      result.errors.forEach((error, index) => {
-        console.log(`   ${index + 1}. ${chalk.red(error.message)}`);
-        if (error.suggestion) {
-          console.log(`      ${chalk.blue('💡 ' + error.suggestion)}`);
+      // Human-readable text output
+      if (result.valid) {
+        console.log(chalk.green('✅ Working spec validation passed'));
+        if (!options.quiet) {
+          console.log(chalk.gray(`   Risk tier: ${spec.risk_tier}`));
+          console.log(chalk.gray(`   Mode: ${spec.mode}`));
+          if (spec.title) {
+            console.log(chalk.gray(`   Title: ${spec.title}`));
+          }
+          if (result.complianceScore !== undefined) {
+            const grade = getComplianceGrade(result.complianceScore);
+            const scorePercent = (result.complianceScore * 100).toFixed(0);
+            const scoreColor = result.complianceScore >= 0.9 ? 'green' : result.complianceScore >= 0.7 ? 'yellow' : 'red';
+            console.log(chalk[scoreColor](`   Compliance: ${scorePercent}% (Grade ${grade})`));
+          }
         }
-      });
+      } else {
+        console.log(chalk.red('❌ Working spec validation failed'));
 
-      // Show warnings
-      if (result.warnings && result.warnings.length > 0) {
-        console.log(chalk.yellow('\n⚠️  Warnings:'));
-        result.warnings.forEach((warning, index) => {
-          console.log(`   ${index + 1}. ${chalk.yellow(warning.message)}`);
+        // Show errors
+        result.errors.forEach((error, index) => {
+          console.log(`   ${index + 1}. ${chalk.red(error.message)}`);
+          if (error.suggestion) {
+            console.log(`      ${chalk.blue('💡 ' + error.suggestion)}`);
+          }
         });
-      }
 
-      process.exit(1);
+        // Show warnings
+        if (result.warnings && result.warnings.length > 0) {
+          console.log(chalk.yellow('\n⚠️  Warnings:'));
+          result.warnings.forEach((warning, index) => {
+            console.log(`   ${index + 1}. ${chalk.yellow(warning.message)}`);
+          });
+        }
+
+        process.exit(1);
+      }
     }
   } catch (error) {
-    console.error(chalk.red('❌ Error during validation:'), error.message);
+    if (options.format === 'json') {
+      console.log(
+        JSON.stringify(
+          {
+            passed: false,
+            verdict: 'fail',
+            error: error.message,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(chalk.red('❌ Error during validation:'), error.message);
+    }
     process.exit(1);
   }
 }

package/dist/index.js

@@ -117,6 +117,8 @@ program
   .argument('[spec-file]', 'Path to working spec file (default: .caws/working-spec.yaml)')
   .option('-q, --quiet', 'Suppress suggestions and warnings', false)
   .option('--auto-fix', 'Automatically fix safe validation issues', false)
+  .option('--dry-run', 'Preview auto-fixes without applying them', false)
+  .option('--format <format>', 'Output format (text, json)', 'text')
   .action(validateCommand);
 
 // Status command

package/dist/policy/PolicyManager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Policy Manager - Handles policy loading with intelligent caching
+ *
+ * Features:
+ * - TTL-based caching for performance
+ * - Graceful fallback to defaults when policy.yaml missing
+ * - Cache inspection and management API
+ * - Waiver validation and delta application
+ */
+export class PolicyManager {
+    constructor(options?: {});
+    enableCaching: any;
+    cacheTTL: any;
+    policyCache: Map<any, any>;
+    /**
+     * Load CAWS policy from policy.yaml with caching
+     *
+     * @param {string} projectRoot - Project root directory
+     * @param {Object} options - Loading options
+     * @param {boolean} options.useCache - Use cache if available (default: true)
+     * @param {number} options.cacheTTL - Cache TTL override in milliseconds
+     * @returns {Promise<Object>} Policy object
+     */
+    loadPolicy(projectRoot: string, options?: {
+        useCache: boolean;
+        cacheTTL: number;
+    }): Promise<any>;
+    /**
+     * Load a waiver document by ID
+     *
+     * @param {string} waiverId - Waiver ID (e.g., WV-0001)
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object|null>} Waiver document or null if not found
+     */
+    loadWaiver(waiverId: string, projectRoot: string): Promise<any | null>;
+    /**
+     * Check if a waiver is currently valid
+     *
+     * @param {Object} waiver - Waiver document
+     * @returns {boolean} True if waiver is valid and active
+     */
+    isWaiverValid(waiver: any): boolean;
+    /**
+     * Apply waivers to baseline budget
+     *
+     * @param {Object} baseline - Baseline budget from policy
+     * @param {string[]} waiverIds - Array of waiver IDs to apply
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object>} Effective budget with waivers applied
+     */
+    applyWaivers(baseline: any, waiverIds: string[], projectRoot: string): Promise<any>;
+    /**
+     * Validate policy structure
+     *
+     * @param {Object} policy - Policy to validate
+     * @throws {Error} If policy is invalid
+     */
+    validatePolicy(policy: any): void;
+    /**
+     * Get default CAWS policy
+     *
+     * Returns sensible defaults when policy.yaml doesn't exist.
+     *
+     * @returns {Object} Default policy configuration
+     */
+    getDefaultPolicy(): any;
+    /**
+     * Clear policy cache
+     *
+     * @param {string} [projectRoot] - Specific project to clear, or all if omitted
+     */
+    clearCache(projectRoot?: string): void;
+    /**
+     * Get cache status for a project
+     *
+     * @param {string} projectRoot - Project root directory
+     * @returns {Object} Cache status information
+     */
+    getCacheStatus(projectRoot: string): any;
+    /**
+     * Reload policy from disk (bypassing cache)
+     *
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object>} Fresh policy
+     */
+    reloadPolicy(projectRoot: string): Promise<any>;
+    /**
+     * Get all cached projects
+     *
+     * @returns {string[]} Array of project roots with cached policies
+     */
+    getCachedProjects(): string[];
+    /**
+     * Get cache statistics
+     *
+     * @returns {Object} Cache statistics
+     */
+    getCacheStats(): any;
+}
+export const defaultPolicyManager: PolicyManager;
+export declare function loadPolicy(projectRoot: any, options: any): Promise<any>;
+export declare function clearCache(projectRoot: any): void;
+export declare function getCacheStatus(projectRoot: any): any;
+//# sourceMappingURL=PolicyManager.d.ts.map

package/dist/policy/PolicyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyManager.d.ts","sourceRoot":"","sources":["../../src/policy/PolicyManager.js"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH;IACE,0BAIC;IAHC,mBAAkD;IAClD,cAA0C;IAC1C,2BAA4B;IAG9B;;;;;;;;OAQG;IACH,wBANW,MAAM,YAEd;QAAyB,QAAQ,EAAzB,OAAO;QACS,QAAQ,EAAxB,MAAM;KACd,GAAU,OAAO,KAAQ,CAuE3B;IAED;;;;;;OAMG;IACH,qBAJW,MAAM,eACN,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAchC;IAED;;;;;OAKG;IACH,4BAFa,OAAO,CA2BnB;IAED;;;;;;;OAOG;IACH,uCAJW,MAAM,EAAE,eACR,MAAM,GACJ,OAAO,KAAQ,CA2B3B;IAED;;;;;OAKG;IACH,kCA8BC;IAED;;;;;;OAMG;IACH,wBAoDC;IAED;;;;OAIG;IACH,yBAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,OAmBhB;IAED;;;;;OAKG;IACH,0BAHW,MAAM,GACJ,OAAO,KAAQ,CAK3B;IAED;;;;OAIG;IACH,qBAFa,MAAM,EAAE,CAIpB;IAED;;;;OAIG;IACH,qBA2BC;CACF;AAGD,iDAAiD;AAOnC,iFAA+E;AAC/E,2DAA6D;AACzD,8DAAiE"}

package/dist/policy/PolicyManager.js

@@ -0,0 +1,399 @@
+/**
+ * @fileoverview Policy Manager with Intelligent Caching
+ * Manages policy.yaml loading with caching, default fallback, and waiver validation.
+ * Ported from agent-agency v2 CAWS integration patterns.
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Policy Manager - Handles policy loading with intelligent caching
+ *
+ * Features:
+ * - TTL-based caching for performance
+ * - Graceful fallback to defaults when policy.yaml missing
+ * - Cache inspection and management API
+ * - Waiver validation and delta application
+ */
+class PolicyManager {
+  constructor(options = {}) {
+    this.enableCaching = options.enableCaching ?? true;
+    this.cacheTTL = options.cacheTTL ?? 300000; // 5 minutes default
+    this.policyCache = new Map(); // projectRoot -> { policy, cachedAt, ttl }
+  }
+
+  /**
+   * Load CAWS policy from policy.yaml with caching
+   *
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} options - Loading options
+   * @param {boolean} options.useCache - Use cache if available (default: true)
+   * @param {number} options.cacheTTL - Cache TTL override in milliseconds
+   * @returns {Promise<Object>} Policy object
+   */
+  async loadPolicy(projectRoot, options = {}) {
+    const useCache = options.useCache ?? this.enableCaching;
+    const cacheTTL = options.cacheTTL ?? this.cacheTTL;
+    const startTime = Date.now();
+
+    try {
+      // Check cache first
+      if (useCache && this.policyCache.has(projectRoot)) {
+        const cached = this.policyCache.get(projectRoot);
+        const cacheAge = Date.now() - cached.cachedAt;
+
+        if (cacheAge < cacheTTL) {
+          return {
+            ...cached.policy,
+            _cacheHit: true,
+            _loadDuration: Date.now() - startTime,
+          };
+        }
+      }
+
+      // Load from file
+      const policyPath = path.join(projectRoot, '.caws', 'policy.yaml');
+
+      try {
+        const content = await fs.readFile(policyPath, 'utf-8');
+        const policy = yaml.load(content);
+
+        // Validate policy structure
+        this.validatePolicy(policy);
+
+        // Update cache
+        if (this.enableCaching) {
+          this.policyCache.set(projectRoot, {
+            policy,
+            cachedAt: Date.now(),
+            ttl: cacheTTL,
+          });
+        }
+
+        return {
+          ...policy,
+          _cacheHit: false,
+          _loadDuration: Date.now() - startTime,
+        };
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          // Policy file doesn't exist - use default
+          const defaultPolicy = this.getDefaultPolicy();
+
+          if (this.enableCaching) {
+            this.policyCache.set(projectRoot, {
+              policy: defaultPolicy,
+              cachedAt: Date.now(),
+              ttl: cacheTTL,
+            });
+          }
+
+          return {
+            ...defaultPolicy,
+            _isDefault: true,
+            _cacheHit: false,
+            _loadDuration: Date.now() - startTime,
+          };
+        }
+        throw error;
+      }
+    } catch (error) {
+      throw new Error(`Policy load failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Load a waiver document by ID
+   *
+   * @param {string} waiverId - Waiver ID (e.g., WV-0001)
+   * @param {string} projectRoot - Project root directory
+   * @returns {Promise<Object|null>} Waiver document or null if not found
+   */
+  async loadWaiver(waiverId, projectRoot) {
+    try {
+      const waiverPath = path.join(projectRoot, '.caws', 'waivers', `${waiverId}.yaml`);
+
+      const content = await fs.readFile(waiverPath, 'utf-8');
+      return yaml.load(content);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+      throw new Error(`Failed to load waiver ${waiverId}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if a waiver is currently valid
+   *
+   * @param {Object} waiver - Waiver document
+   * @returns {boolean} True if waiver is valid and active
+   */
+  isWaiverValid(waiver) {
+    if (!waiver) {
+      return false;
+    }
+
+    // Check status
+    if (waiver.status !== 'active') {
+      return false;
+    }
+
+    // Check expiry
+    if (waiver.expires_at) {
+      const expiryDate = new Date(waiver.expires_at);
+      const now = new Date();
+      if (now > expiryDate) {
+        return false;
+      }
+    }
+
+    // Check if it has required approvals
+    if (!waiver.approvers || waiver.approvers.length === 0) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Apply waivers to baseline budget
+   *
+   * @param {Object} baseline - Baseline budget from policy
+   * @param {string[]} waiverIds - Array of waiver IDs to apply
+   * @param {string} projectRoot - Project root directory
+   * @returns {Promise<Object>} Effective budget with waivers applied
+   */
+  async applyWaivers(baseline, waiverIds, projectRoot) {
+    const effective = { ...baseline };
+    const applied = [];
+
+    for (const waiverId of waiverIds) {
+      const waiver = await this.loadWaiver(waiverId, projectRoot);
+
+      if (waiver && this.isWaiverValid(waiver)) {
+        // Apply additive delta
+        if (waiver.delta) {
+          if (waiver.delta.max_files) {
+            effective.max_files += waiver.delta.max_files;
+          }
+          if (waiver.delta.max_loc) {
+            effective.max_loc += waiver.delta.max_loc;
+          }
+        }
+        applied.push(waiverId);
+      }
+    }
+
+    return {
+      effective,
+      applied,
+    };
+  }
+
+  /**
+   * Validate policy structure
+   *
+   * @param {Object} policy - Policy to validate
+   * @throws {Error} If policy is invalid
+   */
+  validatePolicy(policy) {
+    if (!policy.version) {
+      throw new Error('Policy missing version field');
+    }
+
+    if (!policy.risk_tiers) {
+      throw new Error('Policy missing risk_tiers configuration');
+    }
+
+    // Validate all tiers have required fields
+    for (const tier of [1, 2, 3]) {
+      const budget = policy.risk_tiers[tier];
+      if (!budget) {
+        throw new Error(`Policy missing risk tier ${tier} configuration`);
+      }
+
+      if (typeof budget.max_files !== 'number' || typeof budget.max_loc !== 'number') {
+        throw new Error(`Risk tier ${tier} missing or invalid budget limits`);
+      }
+    }
+
+    // Validate edit rules if present
+    if (policy.edit_rules) {
+      if (typeof policy.edit_rules.policy_and_code_same_pr !== 'boolean') {
+        throw new Error('edit_rules.policy_and_code_same_pr must be boolean');
+      }
+      if (typeof policy.edit_rules.min_approvers_for_budget_raise !== 'number') {
+        throw new Error('edit_rules.min_approvers_for_budget_raise must be number');
+      }
+    }
+  }
+
+  /**
+   * Get default CAWS policy
+   *
+   * Returns sensible defaults when policy.yaml doesn't exist.
+   *
+   * @returns {Object} Default policy configuration
+   */
+  getDefaultPolicy() {
+    return {
+      version: 1,
+      risk_tiers: {
+        1: {
+          max_files: 25,
+          max_loc: 1000,
+          description: 'Critical changes requiring manual review',
+        },
+        2: {
+          max_files: 50,
+          max_loc: 2000,
+          description: 'Standard features with automated gates',
+        },
+        3: {
+          max_files: 100,
+          max_loc: 5000,
+          description: 'Low-risk changes with minimal oversight',
+        },
+      },
+      edit_rules: {
+        policy_and_code_same_pr: false,
+        min_approvers_for_budget_raise: 2,
+        require_signed_commits: true,
+      },
+      gates: {
+        budget_limit: {
+          enabled: true,
+          description: 'Enforce change budget limits',
+        },
+        spec_completeness: {
+          enabled: true,
+          description: 'Require complete working specifications',
+        },
+        contract_compliance: {
+          enabled: true,
+          description: 'Validate API contracts',
+        },
+        coverage_threshold: {
+          enabled: true,
+          description: 'Maintain test coverage requirements',
+        },
+        mutation_threshold: {
+          enabled: true,
+          description: 'Require mutation testing for T1/T2 changes',
+        },
+        security_scan: {
+          enabled: true,
+          description: 'Run security vulnerability scans',
+        },
+      },
+    };
+  }
+
+  /**
+   * Clear policy cache
+   *
+   * @param {string} [projectRoot] - Specific project to clear, or all if omitted
+   */
+  clearCache(projectRoot) {
+    if (projectRoot) {
+      this.policyCache.delete(projectRoot);
+    } else {
+      this.policyCache.clear();
+    }
+  }
+
+  /**
+   * Get cache status for a project
+   *
+   * @param {string} projectRoot - Project root directory
+   * @returns {Object} Cache status information
+   */
+  getCacheStatus(projectRoot) {
+    const cached = this.policyCache.get(projectRoot);
+
+    if (!cached) {
+      return {
+        cached: false,
+        ttl: this.cacheTTL,
+      };
+    }
+
+    return {
+      cached: true,
+      age: Date.now() - cached.cachedAt,
+      ttl: cached.ttl,
+      remainingTTL: Math.max(0, cached.ttl - (Date.now() - cached.cachedAt)),
+    };
+  }
+
+  /**
+   * Reload policy from disk (bypassing cache)
+   *
+   * @param {string} projectRoot - Project root directory
+   * @returns {Promise<Object>} Fresh policy
+   */
+  async reloadPolicy(projectRoot) {
+    this.clearCache(projectRoot);
+    return this.loadPolicy(projectRoot, { useCache: false });
+  }
+
+  /**
+   * Get all cached projects
+   *
+   * @returns {string[]} Array of project roots with cached policies
+   */
+  getCachedProjects() {
+    return Array.from(this.policyCache.keys());
+  }
+
+  /**
+   * Get cache statistics
+   *
+   * @returns {Object} Cache statistics
+   */
+  getCacheStats() {
+    const projects = this.getCachedProjects();
+    const now = Date.now();
+
+    const stats = {
+      totalCached: projects.length,
+      validCaches: 0,
+      expiredCaches: 0,
+      totalAge: 0,
+    };
+
+    for (const project of projects) {
+      const cached = this.policyCache.get(project);
+      const age = now - cached.cachedAt;
+
+      stats.totalAge += age;
+
+      if (age < cached.ttl) {
+        stats.validCaches++;
+      } else {
+        stats.expiredCaches++;
+      }
+    }
+
+    stats.averageAge = projects.length > 0 ? stats.totalAge / projects.length : 0;
+
+    return stats;
+  }
+}
+
+// Export singleton instance with default configuration
+const defaultPolicyManager = new PolicyManager();
+
+module.exports = {
+  PolicyManager,
+  defaultPolicyManager,
+
+  // Convenience exports for backward compatibility
+  loadPolicy: (projectRoot, options) => defaultPolicyManager.loadPolicy(projectRoot, options),
+  clearCache: (projectRoot) => defaultPolicyManager.clearCache(projectRoot),
+  getCacheStatus: (projectRoot) => defaultPolicyManager.getCacheStatus(projectRoot),
+};

package/dist/scaffold/cursor-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-hooks.d.ts","sourceRoot":"","sources":["../../src/scaffold/cursor-hooks.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,gDAHW,MAAM,WACN,MAAM,EAAE,iBAsIlB"}
+{"version":3,"file":"cursor-hooks.d.ts","sourceRoot":"","sources":["../../src/scaffold/cursor-hooks.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,gDAHW,MAAM,WACN,MAAM,EAAE,iBAqJlB"}