@paths.design/caws-cli 7.0.2 → 8.0.0

package/templates/.caws/tools/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,
+};

package/templates/.caws/tools-allow.json

@@ -0,0 +1,331 @@
+[
+  "node",
+  "npm",
+  "yarn",
+  "pnpm",
+  "git",
+  "docker",
+  "kubectl",
+  "aws",
+  "azure",
+  "gcloud",
+  "terraform",
+  "ansible",
+  "curl",
+  "wget",
+  "grep",
+  "sed",
+  "awk",
+  "bash",
+  "sh",
+  "zsh",
+  "fish",
+  "python",
+  "python3",
+  "pip",
+  "pip3",
+  "virtualenv",
+  "conda",
+  "java",
+  "javac",
+  "gradle",
+  "maven",
+  "go",
+  "gofmt",
+  "rust",
+  "cargo",
+  "rustfmt",
+  "clippy",
+  "ruby",
+  "gem",
+  "bundle",
+  "rbenv",
+  "php",
+  "composer",
+  "dotnet",
+  "nuget",
+  "swift",
+  "xcodebuild",
+  "make",
+  "cmake",
+  "ninja",
+  "gcc",
+  "clang",
+  "ld",
+  "ar",
+  "strip",
+  "objdump",
+  "nm",
+  "readelf",
+  "file",
+  "hexdump",
+  "xxd",
+  "base64",
+  "openssl",
+  "ssh",
+  "scp",
+  "rsync",
+  "tar",
+  "gzip",
+  "bzip2",
+  "xz",
+  "zip",
+  "unzip",
+  "7z",
+  "jq",
+  "yq",
+  "xmlstarlet",
+  "html-xml-utils",
+  "pandoc",
+  "asciidoc",
+  "rst2html",
+  "markdown",
+  "remark",
+  "prettier",
+  "eslint",
+  "tslint",
+  "stylelint",
+  "htmlhint",
+  "csslint",
+  "jsonlint",
+  "yamllint",
+  "shellcheck",
+  "hadolint",
+  "dockerfile_lint",
+  "markdownlint",
+  "proselint",
+  "vale",
+  "alex",
+  "write-good",
+  "textlint",
+  "redpen",
+  "languagetool",
+  "grammarly",
+  "codespell",
+  "typos",
+  "aspell",
+  "hunspell",
+  "sort",
+  "uniq",
+  "cut",
+  "paste",
+  "join",
+  "split",
+  "tr",
+  "column",
+  "fold",
+  "fmt",
+  "pr",
+  "head",
+  "tail",
+  "wc",
+  "nl",
+  "od",
+  "strings",
+  "iconv",
+  "dos2unix",
+  "unix2dos",
+  "mac2unix",
+  "unix2mac",
+  "pbcopy",
+  "pbpaste",
+  "xclip",
+  "xsel",
+  "tmux",
+  "screen",
+  "vim",
+  "nvim",
+  "emacs",
+  "nano",
+  "micro",
+  "code",
+  "atom",
+  "sublime",
+  "vimr",
+  "macvim",
+  "gvim",
+  "vscode",
+  "intellij",
+  "pycharm",
+  "webstorm",
+  "phpstorm",
+  "rubymine",
+  "clion",
+  "goland",
+  "rider",
+  "datagrip",
+  "android-studio",
+  "xcode",
+  "eclipse",
+  "netbeans",
+  "idea",
+  "studio",
+  "vs",
+  "visualstudio",
+  "monodevelop",
+  "xamarin",
+  "rider",
+  "resharper",
+  "testcafe",
+  "cypress",
+  "playwright",
+  "puppeteer",
+  "selenium",
+  "webdriver",
+  "jest",
+  "mocha",
+  "jasmine",
+  "karma",
+  "vitest",
+  "testing-library",
+  "enzyme",
+  "react-testing-library",
+  "vue-test-utils",
+  "angular-testing-library",
+  "svelte-testing-library",
+  "lit-testing-library",
+  "ember-testing",
+  "backbone-testing",
+  "jquery-testing",
+  "dojo-testing",
+  "dojo",
+  "mootools",
+  "prototype",
+  "yui",
+  "extjs",
+  "sencha",
+  "backbone",
+  "marionette",
+  "chaplin",
+  "thorax",
+  "handlebars",
+  "mustache",
+  "underscore",
+  "lodash",
+  "ramda",
+  "functional",
+  "lazy",
+  "bluebird",
+  "q",
+  "deferred",
+  "async",
+  "await",
+  "generator",
+  "co",
+  "redux",
+  "mobx",
+  "flux",
+  "reflux",
+  "alt",
+  "flummox",
+  "delorean",
+  "cerebral",
+  "kea",
+  "zustand",
+  "jotai",
+  "recoil",
+  "valtio",
+  "effector",
+  "xstate",
+  "robot",
+  "easy-peasy",
+  "pullstate",
+  "akita",
+  "ngrx",
+  "ngxs",
+  "akita",
+  "elf",
+  "pinia",
+  "overmind",
+  "stately",
+  "context",
+  "useContext",
+  "useReducer",
+  "useState",
+  "useEffect",
+  "useMemo",
+  "useCallback",
+  "useRef",
+  "useImperativeHandle",
+  "useLayoutEffect",
+  "useDebugValue",
+  "useDeferredValue",
+  "useTransition",
+  "useId",
+  "useSyncExternalStore",
+  "createContext",
+  "createElement",
+  "cloneElement",
+  "isValidElement",
+  "ReactDOM",
+  "render",
+  "hydrate",
+  "createRoot",
+  "unmountComponentAtNode",
+  "findDOMNode",
+  "createPortal",
+  "unstable_batchedUpdates",
+  "flushSync",
+  "React",
+  "Component",
+  "PureComponent",
+  "memo",
+  "lazy",
+  "Suspense",
+  "ErrorBoundary",
+  "Profiler",
+  "StrictMode",
+  "Fragment",
+  "createRef",
+  "forwardRef",
+  "createContext",
+  "createElement",
+  "cloneElement",
+  "isValidElement",
+  "Children",
+  "map",
+  "forEach",
+  "count",
+  "only",
+  "toArray",
+  "ReactDOM",
+  "render",
+  "hydrate",
+  "createRoot",
+  "unmountComponentAtNode",
+  "findDOMNode",
+  "createPortal",
+  "unstable_batchedUpdates",
+  "flushSync",
+  "React",
+  "Component",
+  "PureComponent",
+  "memo",
+  "lazy",
+  "Suspense",
+  "ErrorBoundary",
+  "Profiler",
+  "StrictMode",
+  "Fragment",
+  "createRef",
+  "forwardRef",
+  "createContext",
+  "createElement",
+  "cloneElement",
+  "isValidElement",
+  "Children",
+  "map",
+  "forEach",
+  "count",
+  "only",
+  "toArray",
+  "ReactDOM",
+  "render",
+  "hydrate",
+  "createRoot",
+  "unmountComponentAtNode",
+  "findDOMNode",
+  "createPortal",
+  "unstable_batchedUpdates",
+  "flushSync"
+]

package/templates/.caws/waivers.yml

@@ -0,0 +1,19 @@
+waivers:
+  # Example waiver for urgent fixes
+  # - id: "HOTFIX-001"
+  #   description: "Urgent security fix - mutation testing waived"
+  #   gates: ["mutation", "coverage"]
+  #   reason: "urgent_fix"
+  #   approver: "senior-dev"
+  #   expires_at: "2025-10-07T10:00:00.000Z"
+  #   projects: ["FEAT-1234"]
+  #   max_trust_score: 79
+
+  # Example waiver for experimental features
+  # - id: "EXP-001"
+  #   description: "Experimental feature - relaxed testing"
+  #   gates: ["mutation", "contracts"]
+  #   reason: "experimental"
+  #   approver: "tech-lead"
+  #   expires_at: "2025-10-14T10:00:00.000Z"
+  #   max_trust_score: 75

package/templates/.cursor/hooks/scope-guard.sh

@@ -22,7 +22,7 @@ if [ ! -f ".caws/working-spec.yaml" ] && [ ! -f ".caws/working-spec.yml" ]; then
 fi
 
 # Check if scope-guard tool exists
-if [ -f "apps/tools/caws/scope-guard.js" ]; then
+if [ -f ".caws/tools/scope-guard.js" ]; then
   # Extract file paths from attachments
   FILE_PATHS=$(echo "$ATTACHMENTS" | jq -r '.[] | select(.type=="file") | .file_path' 2>/dev/null || echo "")
   
@@ -31,7 +31,7 @@ if [ -f "apps/tools/caws/scope-guard.js" ]; then
     OUT_OF_SCOPE=()
     while IFS= read -r file; do
       if [ -n "$file" ]; then
-        if ! node apps/tools/caws/scope-guard.js check "$file" 2>/dev/null; then
+        if ! node .caws/tools/scope-guard.js check "$file" 2>/dev/null; then
           OUT_OF_SCOPE+=("$file")
         fi
       fi

package/templates/.cursor/hooks/validate-spec.sh

@@ -14,27 +14,62 @@ INPUT=$(cat)
 # Extract file path from input
 FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // ""')
 
-# Only validate if working-spec.yaml was edited
-if [[ "$FILE_PATH" == *"working-spec.yaml"* ]] || [[ "$FILE_PATH" == *"working-spec.yml"* ]]; then
-  echo "🔍 Validating CAWS working spec..." >&2
+# Validate if any CAWS YAML file was edited (.caws/**/*.yaml or .caws/**/*.yml)
+if [[ "$FILE_PATH" == *".caws/"* ]] && ([[ "$FILE_PATH" == *.yaml ]] || [[ "$FILE_PATH" == *.yml ]]); then
+  echo "🔍 Validating CAWS spec file..." >&2
 
-  # Check if CAWS CLI is available
+  # First, validate YAML syntax
+  if command -v node >/dev/null 2>&1; then
+    # Check YAML syntax using Node.js
+    YAML_SYNTAX_VALID=$(node -e "
+      const yaml = require('js-yaml');
+      const fs = require('fs');
+      try {
+        const content = fs.readFileSync('$FILE_PATH', 'utf8');
+        yaml.load(content);
+        process.exit(0);
+      } catch (error) {
+        console.error('YAML syntax error:', error.message);
+        if (error.mark) {
+          console.error('Line:', error.mark.line + 1, 'Column:', error.mark.column + 1);
+        }
+        process.exit(1);
+      }
+    " 2>&1)
+
+    if [ $? -ne 0 ]; then
+      echo '{
+        "userMessage": "⚠️ YAML syntax error detected",
+        "agentMessage": "The spec file has invalid YAML syntax. Fix syntax errors before continuing.",
+        "suggestions": [
+          "Check indentation (YAML uses 2 spaces)",
+          "Ensure all array items use consistent format",
+          "Remove duplicate keys",
+          "Consider using '\''caws specs create <id>'\'' instead of manual creation"
+        ]
+      }' 2>/dev/null
+      exit 0
+    fi
+  fi
+
+  # Check if CAWS CLI is available for semantic validation
   if command -v caws &> /dev/null; then
     # Run CAWS validation with suggestions
     if VALIDATION=$(caws validate "$FILE_PATH" --quiet 2>&1); then
-      echo '{"userMessage":"✅ CAWS spec validation passed","agentMessage":"Working specification is valid and complete."}' 2>/dev/null
+      echo '{"userMessage":"✅ CAWS spec validation passed","agentMessage":"Specification is valid and complete."}' 2>/dev/null
     else
       # Get suggestions for fixing the spec
       SUGGESTIONS=$(caws validate "$FILE_PATH" --suggestions 2>/dev/null | head -5 | tr '\n' '; ' | sed 's/; $//' || echo "Run caws validate --suggestions for details")
 
       echo '{
         "userMessage": "⚠️ CAWS spec validation failed. Run: caws validate --suggestions",
-        "agentMessage": "The working-spec.yaml file has validation errors. Please review and fix before continuing.",
+        "agentMessage": "The spec file has validation errors. Please review and fix before continuing.",
         "suggestions": [
           "Run caws validate --suggestions for detailed error messages",
           "Check required fields: id, title, risk_tier, mode",
           "Ensure acceptance criteria are properly defined",
-          "Verify scope boundaries are appropriate"
+          "Verify scope boundaries are appropriate",
+          "Consider using '\''caws specs create <id>'\'' for proper structure"
         ]
       }' 2>/dev/null
     fi