@paths.design/caws-cli 2.0.0 → 3.0.0

package/templates/apps/tools/caws/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["provenance.js"],"names":[],"mappings":";AAYA;;;;GAIG;AACH,uDAkCC;AAED;;;;GAIG;AACH,0DAFW,MAAM,QAShB"}

package/templates/apps/tools/caws/provenance.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview CAWS Provenance Tool
+ * @author @darianrosebrook
+ *
+ * Note: For enhanced TypeScript version with better error handling, use provenance.ts
+ * This .js version provides basic provenance for backward compatibility
+ */
+
+/**
+ * Generates provenance information for a CAWS project
+ * @returns {Object} Provenance data with metadata and artifacts
+ */
+function generateProvenance() {
+  try {
+    const fs = require('fs');
+    const crypto = require('crypto');
+
+    // Check if we're in a CAWS project
+    if (!fs.existsSync('.caws')) {
+      throw new Error('Not in a CAWS project directory');
+    }
+
+    const workingSpecPath = '.caws/working-spec.yaml';
+    if (!fs.existsSync(workingSpecPath)) {
+      throw new Error('Working specification file not found');
+    }
+
+    // Load working spec
+    const yaml = require('js-yaml');
+    const specContent = fs.readFileSync(workingSpecPath, 'utf8');
+    const spec = yaml.load(specContent);
+
+    // Generate provenance data
+    const provenance = {
+      agent: 'caws-cli',
+      model: 'cli-interactive',
+      modelHash: (() => {
+        try {
+          return require('../../../package.json').version || '1.0.0';
+        } catch (error) {
+          return '1.0.0'; // Fallback version if package.json not found
+        }
+      })(),
+      toolAllowlist: [
+        'node',
+        'npm',
+        'git',
+        'fs-extra',
+        'inquirer',
+        'commander',
+        'js-yaml',
+        'ajv',
+        'chalk',
+      ],
+      artifacts: ['.caws/working-spec.yaml'],
+      results: {
+        project_id: spec.id,
+        project_title: spec.title,
+        risk_tier: spec.risk_tier,
+        mode: spec.mode,
+        change_budget: spec.change_budget,
+        blast_radius: spec.blast_radius,
+        operational_rollback_slo: spec.operational_rollback_slo,
+      },
+      approvals: [],
+      timestamp: new Date().toISOString(),
+      version: '1.0.0',
+      hash: '', // Will be calculated below
+    };
+
+    // Calculate hash
+    provenance.hash = crypto
+      .createHash('sha256')
+      .update(JSON.stringify(provenance, Object.keys(provenance).sort()))
+      .digest('hex');
+
+    return provenance;
+  } catch (error) {
+    throw new Error(`Provenance generation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Saves provenance data to a file
+ * @param {Object} provenance - Provenance data to save
+ * @param {string} outputPath - Path where to save the provenance file
+ */
+function saveProvenance(provenance, outputPath) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+
+    // Ensure directory exists
+    const dir = path.dirname(outputPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Save provenance
+    fs.writeFileSync(outputPath, JSON.stringify(provenance, null, 2));
+    console.log(`✅ Provenance saved to ${outputPath}`);
+  } catch (error) {
+    throw new Error(`Failed to save provenance: ${error.message}`);
+  }
+}
+
+// Handle direct script execution
+if (require.main === module) {
+  const command = process.argv[2];
+
+  try {
+    if (command === 'generate') {
+      const provenance = generateProvenance();
+      const outputPath = process.argv[3] || '.agent/provenance.json';
+      saveProvenance(provenance, outputPath);
+      console.log('✅ Provenance generated successfully');
+    } else {
+      console.log('CAWS Provenance Tool');
+      console.log('');
+      console.log('Usage:');
+      console.log('  node provenance.js generate [output-path]');
+      console.log('');
+      console.log('Note: For enhanced features, use: npx tsx provenance.ts');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { generateProvenance, saveProvenance };

package/templates/apps/tools/caws/provenance.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env tsx
+
+/**
+ * CAWS Provenance Tool
+ * Enhanced provenance generation with metadata and hashing
+ *
+ * @author @darianrosebrook
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as yaml from 'js-yaml';
+import { CawsBaseTool } from './shared/base-tool.js';
+
+interface ProvenanceData {
+  agent: string;
+  model: string;
+  modelHash: string;
+  toolAllowlist: string[];
+  artifacts: string[];
+  results: Record<string, any>;
+  approvals: string[];
+  timestamp: string;
+  version: string;
+  hash: string;
+}
+
+class ProvenanceCLI extends CawsBaseTool {
+  /**
+   * Generate provenance information for a CAWS project
+   */
+  generateProvenance(): ProvenanceData {
+    try {
+      // Check if we're in a CAWS project
+      if (!this.pathExists('.caws')) {
+        throw new Error('Not in a CAWS project directory');
+      }
+
+      const workingSpecPath = '.caws/working-spec.yaml';
+      if (!this.pathExists(workingSpecPath)) {
+        throw new Error('Working specification file not found');
+      }
+
+      // Load working spec
+      const specContent = fs.readFileSync(workingSpecPath, 'utf8');
+      const spec = yaml.load(specContent) as any;
+
+      // Load package.json for version
+      let version = '1.0.0';
+      const packageJsonPath = path.join(process.cwd(), 'package.json');
+      if (this.pathExists(packageJsonPath)) {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        version = pkg.version || version;
+      }
+
+      // Generate provenance data
+      const provenance: ProvenanceData = {
+        agent: 'caws-cli',
+        model: process.env.CAWS_MODEL || 'cli-interactive',
+        modelHash: version,
+        toolAllowlist: [
+          'node',
+          'npm',
+          'git',
+          'fs-extra',
+          'inquirer',
+          'commander',
+          'js-yaml',
+          'ajv',
+          'chalk',
+          'tsx',
+          'typescript',
+        ],
+        artifacts: ['.caws/working-spec.yaml'],
+        results: {
+          project_id: spec.id || 'unknown',
+          project_title: spec.title || 'Unknown Project',
+          risk_tier: spec.risk_tier || 3,
+          mode: spec.mode || 'standard',
+          change_budget: spec.change_budget,
+          blast_radius: spec.blast_radius,
+          operational_rollback_slo: spec.operational_rollback_slo,
+          acceptance_criteria_count: spec.acceptance?.length || 0,
+          contracts_count: spec.contracts?.length || 0,
+        },
+        approvals: spec.approvals || [],
+        timestamp: new Date().toISOString(),
+        version: '1.0.0',
+        hash: '', // Will be calculated below
+      };
+
+      // Calculate hash
+      const hashContent = JSON.stringify(provenance, Object.keys(provenance).sort());
+      provenance.hash = crypto.createHash('sha256').update(hashContent).digest('hex');
+
+      return provenance;
+    } catch (error) {
+      throw new Error(`Provenance generation failed: ${error}`);
+    }
+  }
+
+  /**
+   * Save provenance data to a file
+   */
+  saveProvenance(provenance: ProvenanceData, outputPath: string): void {
+    try {
+      // Ensure directory exists
+      const dir = path.dirname(outputPath);
+      if (!this.pathExists(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      // Save provenance
+      fs.writeFileSync(outputPath, JSON.stringify(provenance, null, 2));
+      this.logSuccess(`Provenance saved to ${outputPath}`);
+    } catch (error) {
+      throw new Error(`Failed to save provenance: ${error}`);
+    }
+  }
+
+  /**
+   * Display provenance information
+   */
+  displayProvenance(provenance: ProvenanceData): void {
+    console.log('\n📋 CAWS Provenance');
+    console.log('='.repeat(50));
+    console.log(`Agent: ${provenance.agent}`);
+    console.log(`Model: ${provenance.model}`);
+    console.log(`Version: ${provenance.version}`);
+    console.log(`Timestamp: ${provenance.timestamp}`);
+    console.log(`Hash: ${provenance.hash.substring(0, 16)}...`);
+
+    console.log('\n📊 Project Results:');
+    Object.entries(provenance.results).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        console.log(`  ${key}: ${value}`);
+      }
+    });
+
+    console.log('\n🔧 Tool Allowlist:');
+    provenance.toolAllowlist.slice(0, 5).forEach((tool) => {
+      console.log(`  - ${tool}`);
+    });
+    if (provenance.toolAllowlist.length > 5) {
+      console.log(`  ... and ${provenance.toolAllowlist.length - 5} more`);
+    }
+
+    console.log('\n📦 Artifacts:');
+    provenance.artifacts.forEach((artifact) => {
+      console.log(`  - ${artifact}`);
+    });
+
+    if (provenance.approvals.length > 0) {
+      console.log('\n✅ Approvals:');
+      provenance.approvals.forEach((approval) => {
+        console.log(`  - ${approval}`);
+      });
+    }
+
+    console.log('='.repeat(50));
+  }
+}
+
+// Main CLI handler
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const command = process.argv[2];
+  const cli = new ProvenanceCLI();
+
+  try {
+    switch (command) {
+      case 'generate': {
+        const provenance = cli.generateProvenance();
+        const outputPath = process.argv[3] || '.agent/provenance.json';
+        cli.saveProvenance(provenance, outputPath);
+        cli.displayProvenance(provenance);
+        break;
+      }
+
+      case 'show': {
+        const filePath = process.argv[3] || '.agent/provenance.json';
+        if (!cli.pathExists(filePath)) {
+          console.error(`❌ Provenance file not found: ${filePath}`);
+          process.exit(1);
+        }
+
+        const content = fs.readFileSync(filePath, 'utf8');
+        const provenance = JSON.parse(content) as ProvenanceData;
+        cli.displayProvenance(provenance);
+        break;
+      }
+
+      default:
+        console.log('CAWS Provenance Tool');
+        console.log('');
+        console.log('Commands:');
+        console.log('  generate [output]  - Generate and save provenance data');
+        console.log('  show [file]        - Display provenance from file');
+        console.log('');
+        console.log('Examples:');
+        console.log('  provenance.ts generate .agent/provenance.json');
+        console.log('  provenance.ts show .agent/provenance.json');
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`❌ Error: ${error}`);
+    process.exit(1);
+  }
+}
+
+export { ProvenanceCLI };

package/templates/apps/tools/caws/schemas/waivers.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Waivers Configuration",
+  "type": "object",
+  "patternProperties": {
+    ".*": {
+      "type": "object",
+      "required": ["gate", "reason", "owner", "expiry"],
+      "properties": {
+        "gate": {
+          "type": "string",
+          "enum": ["coverage", "mutation", "contracts", "a11y", "perf", "security"]
+        },
+        "reason": { "type": "string", "minLength": 10 },
+        "owner": { "type": "string" },
+        "expiry": { "type": "string", "format": "date-time" },
+        "compensating_control": { "type": "string" },
+        "ticket_url": { "type": "string", "format": "uri" },
+        "approved_by": { "type": "string" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "status": {
+          "type": "string",
+          "enum": ["active", "expired", "revoked"],
+          "default": "active"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/apps/tools/caws/schemas/working-spec.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Working Spec",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "risk_tier",
+    "scope",
+    "invariants",
+    "acceptance",
+    "non_functional",
+    "contracts"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[A-Z]+-\\d+$" },
+    "title": { "type": "string", "minLength": 8 },
+    "risk_tier": { "type": "integer", "enum": [1, 2, 3] },
+    "scope": {
+      "type": "object",
+      "required": ["in", "out"],
+      "properties": {
+        "in": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "out": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "invariants": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "acceptance": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "given", "when", "then"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^A\\d+$" },
+          "given": { "type": "string" },
+          "when": { "type": "string" },
+          "then": { "type": "string" }
+        }
+      }
+    },
+    "non_functional": {
+      "type": "object",
+      "properties": {
+        "a11y": { "type": "array", "items": { "type": "string" } },
+        "perf": {
+          "type": "object",
+          "properties": {
+            "api_p95_ms": { "type": "integer", "minimum": 1 },
+            "lcp_ms": { "type": "integer", "minimum": 1 }
+          },
+          "additionalProperties": false
+        },
+        "security": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "contracts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "type": "string", "enum": ["openapi", "graphql", "proto", "pact"] },
+          "path": { "type": "string" }
+        }
+      }
+    },
+    "observability": {
+      "type": "object",
+      "properties": {
+        "logs": { "type": "array", "items": { "type": "string" } },
+        "metrics": { "type": "array", "items": { "type": "string" } },
+        "traces": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "migrations": { "type": "array", "items": { "type": "string" } },
+    "rollback": { "type": "array", "items": { "type": "string" } },
+    "experiment_mode": {
+      "type": "boolean",
+      "description": "Enables experimental mode with reduced requirements"
+    },
+    "timeboxed_hours": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Time limit for experimental features in hours"
+    },
+    "human_override": {
+      "type": "object",
+      "properties": {
+        "approved_by": { "type": "string" },
+        "reason": { "type": "string" },
+        "waived_requirements": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["mutation_testing", "contract_tests", "coverage", "manual_review"]
+          }
+        },
+        "expiry_date": { "type": "string", "format": "date-time" }
+      },
+      "required": ["approved_by", "reason"]
+    },
+    "ai_assessment": {
+      "type": "object",
+      "properties": {
+        "confidence_level": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "uncertainty_areas": { "type": "array", "items": { "type": "string" } },
+        "recommended_pairing": { "type": "boolean" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/apps/tools/caws/scope-guard.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview CAWS Scope Guard
+ * Enforces that experimental code stays within designated sandbox areas
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+/**
+ * Check if experimental code is properly contained
+ * @param {string} workingSpecPath - Path to working spec file
+ * @returns {Object} Scope validation results
+ */
+function checkExperimentalContainment(workingSpecPath = '.caws/working-spec.yaml') {
+  try {
+    if (!fs.existsSync(workingSpecPath)) {
+      console.error('❌ Working spec not found:', workingSpecPath);
+      return { valid: false, errors: ['Working spec not found'] };
+    }
+
+    const yaml = require('js-yaml');
+    const spec = yaml.load(fs.readFileSync(workingSpecPath, 'utf8'));
+
+    const results = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      experimentalFiles: [],
+      nonExperimentalFiles: [],
+    };
+
+    // Only check if experimental mode is enabled
+    if (!spec.experimental_mode?.enabled) {
+      console.log('ℹ️  Experimental mode not enabled - skipping containment check');
+      return results;
+    }
+
+    const sandboxLocation = spec.experimental_mode.sandbox_location || 'experimental/';
+    console.log(`🔍 Checking containment for experimental code in: ${sandboxLocation}`);
+
+    // Get list of changed files (this would typically come from git diff)
+    const changedFiles = getChangedFiles();
+
+    if (changedFiles.length === 0) {
+      console.log('ℹ️  No files changed - skipping scope check');
+      return results;
+    }
+
+    // Check each changed file
+    changedFiles.forEach((file) => {
+      const isInSandbox =
+        file.startsWith(sandboxLocation) ||
+        file.includes(`/${sandboxLocation}`) ||
+        file.includes(sandboxLocation);
+
+      if (isInSandbox) {
+        results.experimentalFiles.push(file);
+        console.log(`✅ Experimental file properly contained: ${file}`);
+      } else {
+        results.nonExperimentalFiles.push(file);
+        results.valid = false;
+        results.errors.push(`Experimental code found outside sandbox: ${file}`);
+        console.error(`❌ Experimental code outside sandbox: ${file}`);
+      }
+    });
+
+    // Check if experimental files actually exist
+    results.experimentalFiles.forEach((file) => {
+      if (!fs.existsSync(file)) {
+        results.warnings.push(`Experimental file not found (may have been deleted): ${file}`);
+        console.warn(`⚠️  Experimental file not found: ${file}`);
+      }
+    });
+
+    return results;
+  } catch (error) {
+    console.error('❌ Error checking experimental containment:', error.message);
+    return { valid: false, errors: [error.message] };
+  }
+}
+
+/**
+ * Get list of changed files from git
+ * @returns {Array} List of changed file paths
+ */
+function getChangedFiles() {
+  try {
+    // Get files that are staged or modified
+    const staged = execSync('git diff --cached --name-only', { encoding: 'utf8' })
+      .split('\n')
+      .filter((file) => file.trim());
+
+    const modified = execSync('git diff --name-only', { encoding: 'utf8' })
+      .split('\n')
+      .filter((file) => file.trim());
+
+    // Combine and deduplicate
+    const allFiles = [...new Set([...staged, ...modified])];
+
+    // Filter out deleted files (they might still be in the diff)
+    return allFiles.filter((file) => {
+      try {
+        return fs.existsSync(file);
+      } catch {
+        return false;
+      }
+    });
+  } catch (error) {
+    console.warn('⚠️  Could not get changed files from git:', error.message);
+    return [];
+  }
+}
+
+/**
+ * Validate that experimental code follows containment rules
+ * @param {string} workingSpecPath - Path to working spec file
+ */
+function validateExperimentalScope(workingSpecPath = '.caws/working-spec.yaml') {
+  console.log('🔍 Validating experimental code containment...');
+
+  const results = checkExperimentalContainment(workingSpecPath);
+
+  if (!results.valid) {
+    console.error('\n❌ Experimental containment validation failed:');
+    results.errors.forEach((error) => {
+      console.error(`   - ${error}`);
+    });
+
+    if (results.warnings.length > 0) {
+      console.warn('\n⚠️  Warnings:');
+      results.warnings.forEach((warning) => {
+        console.warn(`   - ${warning}`);
+      });
+    }
+
+    console.error('\n💡 To fix containment issues:');
+    console.error('   1. Move experimental code to the designated sandbox location');
+    console.error('   2. Update the sandbox_location in your working spec');
+    console.error('   3. Or disable experimental mode if this is production code');
+
+    process.exit(1);
+  }
+
+  if (results.warnings.length > 0) {
+    console.warn('\n⚠️  Experimental containment warnings:');
+    results.warnings.forEach((warning) => {
+      console.warn(`   - ${warning}`);
+    });
+  }
+
+  console.log('✅ Experimental code containment validated');
+  console.log(`   - Files in sandbox: ${results.experimentalFiles.length}`);
+  console.log(`   - Files outside sandbox: ${results.nonExperimentalFiles.length}`);
+}
+
+// CLI interface
+if (require.main === module) {
+  const command = process.argv[2];
+  const specPath = process.argv[3] || '.caws/working-spec.yaml';
+
+  switch (command) {
+    case 'validate':
+      validateExperimentalScope(specPath);
+      break;
+
+    case 'check':
+      const results = checkExperimentalContainment(specPath);
+      console.log('\n📊 Containment Check Results:');
+      console.log(`   Valid: ${results.valid}`);
+      console.log(`   Experimental files: ${results.experimentalFiles.length}`);
+      console.log(`   Non-experimental files: ${results.nonExperimentalFiles.length}`);
+      console.log(`   Errors: ${results.errors.length}`);
+      console.log(`   Warnings: ${results.warnings.length}`);
+
+      if (results.errors.length > 0) {
+        console.log('\n❌ Errors:');
+        results.errors.forEach((error) => console.log(`   - ${error}`));
+      }
+
+      if (results.warnings.length > 0) {
+        console.log('\n⚠️  Warnings:');
+        results.warnings.forEach((warning) => console.log(`   - ${warning}`));
+      }
+
+      process.exit(results.valid ? 0 : 1);
+      break;
+
+    default:
+      console.log('CAWS Scope Guard');
+      console.log('Usage:');
+      console.log('  node scope-guard.js validate [spec-path]');
+      console.log('  node scope-guard.js check [spec-path]');
+      console.log('');
+      console.log('Examples:');
+      console.log('  node scope-guard.js validate');
+      console.log('  node scope-guard.js check .caws/working-spec.yaml');
+      process.exit(1);
+  }
+}
+
+module.exports = {
+  checkExperimentalContainment,
+  validateExperimentalScope,
+  getChangedFiles,
+};