@paths.design/caws-cli 7.0.2 → 8.0.0

package/dist/utils/yaml-validation.js

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview YAML Validation Utilities
+ * Functions for validating YAML syntax and structure
+ * @author @darianrosebrook
+ */
+
+const yaml = require('js-yaml');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Validate YAML syntax for a file
+ * @param {string} filePath - Path to YAML file
+ * @returns {Object} Validation result with valid flag and error details
+ */
+function validateYamlSyntax(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return {
+        valid: false,
+        error: `File not found: ${filePath}`,
+        line: null,
+        column: null,
+      };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    yaml.load(content); // Will throw if invalid
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error.message,
+      line: error.mark?.line ? error.mark.line + 1 : null, // Convert to 1-based
+      column: error.mark?.column ? error.mark.column + 1 : null, // Convert to 1-based
+      snippet: error.mark?.snippet || null,
+    };
+  }
+}
+
+/**
+ * Validate YAML syntax for multiple files
+ * @param {string[]} filePaths - Array of file paths to validate
+ * @returns {Object} Validation results with summary
+ */
+function validateYamlFiles(filePaths) {
+  const results = {
+    valid: true,
+    files: [],
+    errors: [],
+  };
+
+  for (const filePath of filePaths) {
+    const validation = validateYamlSyntax(filePath);
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    results.files.push({
+      path: relativePath,
+      ...validation,
+    });
+
+    if (!validation.valid) {
+      results.valid = false;
+      results.errors.push({
+        file: relativePath,
+        error: validation.error,
+        line: validation.line,
+        column: validation.column,
+        snippet: validation.snippet,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find all YAML files in .caws directory
+ * @param {string} projectRoot - Project root directory
+ * @returns {string[]} Array of YAML file paths
+ */
+function findCawsYamlFiles(projectRoot) {
+  const cawsDir = path.join(projectRoot, '.caws');
+  const yamlFiles = [];
+
+  if (!fs.existsSync(cawsDir)) {
+    return yamlFiles;
+  }
+
+  function walkDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walkDir(fullPath);
+      } else if (
+        entry.isFile() &&
+        (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))
+      ) {
+        yamlFiles.push(fullPath);
+      }
+    }
+  }
+
+  walkDir(cawsDir);
+  return yamlFiles;
+}
+
+/**
+ * Validate all CAWS YAML files in project
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Validation results
+ */
+function validateAllCawsYamlFiles(projectRoot) {
+  const yamlFiles = findCawsYamlFiles(projectRoot);
+  return validateYamlFiles(yamlFiles);
+}
+
+/**
+ * Format validation error for display
+ * @param {Object} error - Error object from validateYamlSyntax
+ * @param {string} filePath - File path
+ * @returns {string} Formatted error message
+ */
+function formatYamlError(error, filePath) {
+  const relativePath = path.relative(process.cwd(), filePath);
+  let message = `❌ Invalid YAML in ${relativePath}\n`;
+  message += `   Error: ${error.error}\n`;
+
+  if (error.line !== null) {
+    message += `   Line: ${error.line}`;
+    if (error.column !== null) {
+      message += `, Column: ${error.column}`;
+    }
+    message += '\n';
+  }
+
+  if (error.snippet) {
+    message += `   ${error.snippet}\n`;
+  }
+
+  return message;
+}
+
+module.exports = {
+  validateYamlSyntax,
+  validateYamlFiles,
+  findCawsYamlFiles,
+  validateAllCawsYamlFiles,
+  formatYamlError,
+};
+
+

package/dist/validation/spec-validation.js

@@ -238,6 +238,42 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate scope.out doesn't contain glob patterns
+    if (spec.scope && spec.scope.out && Array.isArray(spec.scope.out)) {
+      const globPatterns = spec.scope.out.filter(
+        (pattern) => pattern.includes('*') || pattern.includes('?')
+      );
+      if (globPatterns.length > 0) {
+        errors.push({
+          instancePath: '/scope/out',
+          message: `Unsupported glob patterns in scope.out: ${globPatterns.join(', ')}`,
+          suggestion:
+            'Use directory paths only (e.g., __pycache__/ instead of *.pyc or **/*.pyc). Python cache files are already covered by __pycache__/',
+          canAutoFix: true,
+        });
+
+        // Auto-fix: remove glob patterns and keep only directory paths
+        if (autoFix) {
+          const fixedOut = spec.scope.out
+            .filter((pattern) => !pattern.includes('*') && !pattern.includes('?'))
+            .map((pattern) => {
+              // Ensure directory paths end with /
+              if (!pattern.includes('.') && !pattern.endsWith('/')) {
+                return pattern + '/';
+              }
+              return pattern;
+            });
+
+          fixes.push({
+            field: 'scope.out',
+            value: fixedOut,
+            description: `Removed glob patterns from scope.out: ${globPatterns.join(', ')}`,
+            reason: 'Glob patterns are not supported in scope.out',
+          });
+        }
+      }
+    }
+
     // Auto-fix missing scope.out
     if (spec.scope && !spec.scope.out) {
       fixes.push({
@@ -329,7 +365,7 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
         const suggestion = isChoreMode
           ? 'For infrastructure/setup work, add a minimal project_setup contract or create a waiver'
           : 'Add API contracts (OpenAPI, GraphQL, etc.) or change mode to "chore" for maintenance work';
-        
+
         errors.push({
           instancePath: '/contracts',
           message: `Contracts required for Tier ${spec.risk_tier} changes`,
@@ -341,7 +377,8 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
                   {
                     type: 'project_setup',
                     path: '.caws/working-spec.yaml',
-                    description: 'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
+                    description:
+                      'Project-level CAWS configuration. Feature-specific contracts will be added as features are developed.',
                   },
                 ],
               }
@@ -392,6 +429,48 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
+    // Validate rollback format if present (for all tiers)
+    if (spec.rollback !== undefined) {
+      if (!Array.isArray(spec.rollback)) {
+        errors.push({
+          instancePath: '/rollback',
+          message: 'rollback must be an array of strings',
+          suggestion: 'Use format: ["Step 1", "Step 2", "Step 3"]',
+          canAutoFix: false,
+        });
+      } else {
+        // Check for duplicates
+        const uniqueSteps = [...new Set(spec.rollback)];
+        if (uniqueSteps.length !== spec.rollback.length) {
+          warnings.push({
+            instancePath: '/rollback',
+            message: 'Duplicate entries found in rollback array',
+            suggestion: 'Remove duplicate entries',
+          });
+
+          if (autoFix) {
+            fixes.push({
+              field: 'rollback',
+              value: uniqueSteps,
+              description: 'Removed duplicate rollback entries',
+              reason: 'Duplicate entries detected',
+            });
+          }
+        }
+
+        // Validate each entry is a string
+        const invalidEntries = spec.rollback.filter((entry) => typeof entry !== 'string');
+        if (invalidEntries.length > 0) {
+          errors.push({
+            instancePath: '/rollback',
+            message: `Invalid rollback entries (must be strings): ${invalidEntries.length}`,
+            suggestion: 'All rollback entries must be string descriptions',
+            canAutoFix: false,
+          });
+        }
+      }
+    }
+
     // Validate waiver_ids format if present
     if (spec.waiver_ids) {
       if (!Array.isArray(spec.waiver_ids)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "7.0.2",
+  "version": "8.0.0",
   "description": "CAWS CLI - Coding Agent Workflow System command line tools",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,7 @@
     "templates"
   ],
   "scripts": {
-    "build": "mkdir -p dist && cp -r src/* dist/",
+    "build": "mkdir -p dist && cp -r src/* dist/ && cp -r templates dist/ 2>/dev/null || true",
     "dev": "mkdir -p dist && cp -r src/* dist/ && node dist/index.js",
     "typecheck": "tsc --emitDeclarationOnly --outDir dist",
     "start": "node dist/index.js",

package/templates/.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/.caws/schemas/working-spec.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Working Spec",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "risk_tier",
+    "mode",
+    "blast_radius",
+    "operational_rollback_slo",
+    "scope",
+    "invariants",
+    "acceptance",
+    "non_functional",
+    "contracts"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^(PROJ|FEAT|FIX|ARCH)-\\d{4}$" },
+    "title": { "type": "string", "minLength": 10, "maxLength": 200 },
+    "risk_tier": { "type": ["integer", "string"], "enum": [1, 2, 3, "1", "2", "3"] },
+    "mode": { "type": "string", "enum": ["feature", "refactor", "fix", "doc", "chore"] },
+    "waiver_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^WV-\\d{4}$" },
+      "description": "IDs of active waivers applying to this spec"
+    },
+    "blast_radius": {
+      "type": "object",
+      "required": ["modules"],
+      "properties": {
+        "modules": { "type": "array", "items": { "type": "string" } },
+        "data_migration": { "type": "boolean" }
+      }
+    },
+    "operational_rollback_slo": { "type": "string" },
+    "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/.caws/templates/working-spec.template.yml

@@ -0,0 +1,74 @@
+id: '{{FEATURE_ID}}'
+title: '{{FEATURE_TITLE}}'
+risk_tier: { { TIER } }
+scope:
+  in:
+    - '{{SCOPE_ITEM_1}}'
+    - '{{SCOPE_ITEM_2}}'
+  out:
+    - '{{OUT_OF_SCOPE_ITEM_1}}'
+invariants:
+  - '{{BUSINESS_RULE_1}}'
+  - '{{BUSINESS_RULE_2}}'
+acceptance:
+  - id: A1
+    given: '{{GIVEN_CONDITION}}'
+    when: '{{WHEN_ACTION}}'
+    then: '{{THEN_OUTCOME}}'
+    status: pending # pending | in_progress | completed
+    # Optional: detailed progress tracking
+    # tests:
+    #   written: 0
+    #   passing: 0
+    # coverage: 0.0
+    # last_updated: '2025-10-09T14:30:00Z'
+  - id: A2
+    given: '{{GIVEN_CONDITION_2}}'
+    when: '{{WHEN_ACTION_2}}'
+    then: '{{THEN_OUTCOME_2}}'
+    status: pending # pending | in_progress | completed
+    # Optional: detailed progress tracking
+    # tests:
+    #   written: 0
+    #   passing: 0
+    # coverage: 0.0
+    # last_updated: '2025-10-09T14:30:00Z'
+non_functional:
+  a11y:
+    - '{{ACCESSIBILITY_REQUIREMENT}}'
+  perf:
+    api_p95_ms: { { PERF_BUDGET } }
+    lcp_ms: { { LCP_BUDGET } }
+  security:
+    - '{{SECURITY_REQUIREMENT}}'
+contracts:
+  - type: '{{CONTRACT_TYPE}}'
+    path: '{{CONTRACT_PATH}}'
+observability:
+  logs:
+    - '{{LOG_STATEMENT}}'
+  metrics:
+    - '{{METRIC_NAME}}'
+  traces:
+    - '{{TRACE_SPAN}}'
+migrations:
+  - '{{MIGRATION_DESCRIPTION}}'
+rollback:
+  - '{{ROLLBACK_STRATEGY}}'
+# Optional: Enable for experimental features with reduced requirements
+# experiment_mode: true
+# timeboxed_hours: 24
+
+# Optional: AI confidence assessment
+# ai_assessment:
+#   confidence_level: 8
+#   uncertainty_areas: ["complex business logic", "performance implications"]
+#   recommended_pairing: false
+
+# Optional: Human override for special cases (hotfixes, urgent changes)
+# human_override:
+#   approved_by: "senior-dev-username"
+#   reason: "Urgent production fix - bypassing mutation tests for immediate deployment"
+#   waived_requirements: ["mutation_testing", "manual_review"]
+#   expiry_date: "2025-10-01T00:00:00Z"
+

package/templates/.caws/tools/README.md

@@ -0,0 +1,21 @@
+# CAWS Tools
+
+This directory contains CAWS-specific tools that aren't available in the CLI.
+
+## scope-guard.js
+
+Enforces that experimental code stays within designated sandbox areas. Used by Cursor hooks for scope validation.
+
+```bash
+# Validate experimental code containment
+node .caws/tools/scope-guard.js validate
+
+# Check containment status
+node .caws/tools/scope-guard.js check .caws/working-spec.yaml
+```
+
+**Usage in Cursor Hooks:**
+
+The `.cursor/hooks/scope-guard.sh` hook automatically uses this tool to validate file attachments against working spec scope boundaries.
+
+