@paths.design/caws-cli 8.1.0 → 8.2.0

package/dist/worktree/worktree-manager.js

@@ -0,0 +1,378 @@
+/**
+ * @fileoverview CAWS Git Worktree Manager
+ * Provides CRUD operations for git worktrees with scope isolation
+ * @author @darianrosebrook
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const WORKTREES_DIR = '.caws/worktrees';
+const REGISTRY_FILE = '.caws/worktrees.json';
+const BRANCH_PREFIX = 'caws/';
+
+/**
+ * Get the git repository root
+ * @returns {string} Absolute path to repo root
+ */
+function getRepoRoot() {
+  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+  }).trim();
+}
+
+/**
+ * Get current branch name
+ * @returns {string}
+ */
+function getCurrentBranch() {
+  return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+}
+
+/**
+ * Load the worktree registry
+ * @param {string} root - Repository root
+ * @returns {Object} Registry object
+ */
+function loadRegistry(root) {
+  const registryPath = path.join(root, REGISTRY_FILE);
+  try {
+    if (fs.existsSync(registryPath)) {
+      return JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    }
+  } catch {
+    // Corrupted registry, start fresh
+  }
+  return { version: 1, worktrees: {} };
+}
+
+/**
+ * Save the worktree registry
+ * @param {string} root - Repository root
+ * @param {Object} registry - Registry object
+ */
+function saveRegistry(root, registry) {
+  const registryPath = path.join(root, REGISTRY_FILE);
+  fs.ensureDirSync(path.dirname(registryPath));
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Create a new git worktree with scope isolation
+ * @param {string} name - Worktree name
+ * @param {Object} options - Creation options
+ * @param {string} [options.scope] - Sparse checkout pattern (e.g., "src/auth/**")
+ * @param {string} [options.baseBranch] - Base branch to create from
+ * @param {string} [options.specId] - Associated spec ID for standard+ modes
+ * @returns {Object} Created worktree info
+ */
+function createWorktree(name, options = {}) {
+  const root = getRepoRoot();
+  const { scope, baseBranch, specId } = options;
+
+  // Validate name
+  if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new Error('Worktree name must contain only letters, numbers, hyphens, and underscores');
+  }
+
+  const registry = loadRegistry(root);
+
+  // Check for duplicate
+  if (registry.worktrees[name]) {
+    throw new Error(`Worktree '${name}' already exists. Use 'caws worktree destroy ${name}' first.`);
+  }
+
+  const worktreePath = path.join(root, WORKTREES_DIR, name);
+  const branchName = BRANCH_PREFIX + name;
+  const base = baseBranch || getCurrentBranch();
+
+  // Create the worktree directory
+  fs.ensureDirSync(path.dirname(worktreePath));
+
+  // Create git worktree with new branch
+  try {
+    execFileSync('git', ['worktree', 'add', '-b', branchName, worktreePath, base], {
+      cwd: root,
+      stdio: 'pipe',
+    });
+  } catch (error) {
+    // Branch might already exist
+    if (error.message.includes('already exists')) {
+      execFileSync('git', ['worktree', 'add', worktreePath, branchName], {
+        cwd: root,
+        stdio: 'pipe',
+      });
+    } else {
+      throw new Error(`Failed to create worktree: ${error.message}`);
+    }
+  }
+
+  // Set up sparse checkout if scope is provided
+  if (scope) {
+    try {
+      execFileSync('git', ['sparse-checkout', 'init', '--cone'], {
+        cwd: worktreePath,
+        stdio: 'pipe',
+      });
+
+      // Parse scope patterns (comma-separated)
+      const patterns = scope.split(',').map((p) => p.trim());
+      execFileSync('git', ['sparse-checkout', 'set', ...patterns], {
+        cwd: worktreePath,
+        stdio: 'pipe',
+      });
+    } catch (error) {
+      console.warn(chalk.yellow(`⚠️  Sparse checkout setup failed: ${error.message}`));
+      console.warn(chalk.blue('💡 Worktree created but without sparse checkout'));
+    }
+  }
+
+  // Copy .caws/ config into worktree
+  const cawsSource = path.join(root, '.caws');
+  const cawsDest = path.join(worktreePath, '.caws');
+  if (fs.existsSync(cawsSource)) {
+    try {
+      fs.copySync(cawsSource, cawsDest, {
+        filter: (src) => {
+          // Don't copy worktrees directory or registry into the worktree
+          const rel = path.relative(cawsSource, src);
+          return !rel.startsWith('worktrees') && rel !== 'worktrees.json';
+        },
+      });
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // Generate working spec if in standard+ mode and specId provided
+  if (specId) {
+    try {
+      const { generateWorkingSpec } = require('../generators/working-spec');
+      const specContent = generateWorkingSpec({
+        projectId: specId,
+        projectTitle: `Worktree: ${name}`,
+        projectDescription: `Isolated worktree for ${name}`,
+        riskTier: 3,
+        projectMode: 'feature',
+        scopeIn: scope || 'src/',
+        scopeOut: 'node_modules/, dist/, build/',
+        maxFiles: 25,
+        maxLoc: 1000,
+        blastModules: scope || 'src',
+        dataMigration: false,
+        rollbackSlo: '5m',
+        projectThreats: '',
+        projectInvariants: 'System maintains data consistency',
+        acceptanceCriteria: 'Given current state, when action occurs, then expected result',
+        a11yRequirements: 'keyboard',
+        perfBudget: 250,
+        securityRequirements: 'validation',
+        contractType: '',
+        contractPath: '',
+        observabilityLogs: '',
+        observabilityMetrics: '',
+        observabilityTraces: '',
+        migrationPlan: '',
+        rollbackPlan: '',
+        needsOverride: false,
+        isExperimental: false,
+        aiConfidence: 0.8,
+        uncertaintyAreas: '',
+        complexityFactors: '',
+      });
+      const specPath = path.join(cawsDest, 'working-spec.yaml');
+      fs.ensureDirSync(path.dirname(specPath));
+      fs.writeFileSync(specPath, specContent);
+    } catch {
+      // Non-fatal: spec generation is optional
+    }
+  }
+
+  // Register worktree
+  const entry = {
+    name,
+    path: worktreePath,
+    branch: branchName,
+    baseBranch: base,
+    scope: scope || null,
+    specId: specId || null,
+    createdAt: new Date().toISOString(),
+    status: 'active',
+  };
+
+  registry.worktrees[name] = entry;
+  saveRegistry(root, registry);
+
+  return entry;
+}
+
+/**
+ * List all registered worktrees with filesystem validation
+ * @returns {Array} Worktree entries with status
+ */
+function listWorktrees() {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+
+  // Get actual git worktrees for validation
+  let gitWorktrees = [];
+  try {
+    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: root,
+      encoding: 'utf8',
+    });
+    gitWorktrees = output
+      .split('\n\n')
+      .filter(Boolean)
+      .map((block) => {
+        const lines = block.split('\n');
+        const worktreeLine = lines.find((l) => l.startsWith('worktree '));
+        return worktreeLine ? worktreeLine.replace('worktree ', '') : null;
+      })
+      .filter(Boolean);
+  } catch {
+    // Git worktree list failed
+  }
+
+  const entries = Object.values(registry.worktrees).map((entry) => {
+    const exists = fs.existsSync(entry.path);
+    const inGit = gitWorktrees.some(
+      (wt) => path.resolve(wt) === path.resolve(entry.path)
+    );
+
+    return {
+      ...entry,
+      status: exists && inGit ? 'active' : exists ? 'orphaned' : 'missing',
+    };
+  });
+
+  return entries;
+}
+
+/**
+ * Destroy a worktree
+ * @param {string} name - Worktree name
+ * @param {Object} options - Destruction options
+ * @param {boolean} [options.deleteBranch] - Also delete the branch
+ * @param {boolean} [options.force] - Force removal even if dirty
+ */
+function destroyWorktree(name, options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const { deleteBranch = false, force = false } = options;
+
+  const entry = registry.worktrees[name];
+  if (!entry) {
+    throw new Error(`Worktree '${name}' not found in registry`);
+  }
+
+  // Remove git worktree
+  try {
+    const args = ['worktree', 'remove'];
+    if (force) args.push('--force');
+    args.push(entry.path);
+    execFileSync('git', args, { cwd: root, stdio: 'pipe' });
+  } catch (error) {
+    if (force) {
+      // Force cleanup: remove directory manually
+      if (fs.existsSync(entry.path)) {
+        fs.removeSync(entry.path);
+      }
+      // Prune git worktree list
+      try {
+        execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
+      } catch {
+        // Non-fatal
+      }
+    } else {
+      throw new Error(`Failed to remove worktree: ${error.message}. Use --force to override.`);
+    }
+  }
+
+  // Optionally delete branch
+  if (deleteBranch && entry.branch) {
+    try {
+      execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
+    } catch {
+      if (force) {
+        try {
+          execFileSync('git', ['branch', '-D', entry.branch], { cwd: root, stdio: 'pipe' });
+        } catch {
+          // Non-fatal
+        }
+      }
+    }
+  }
+
+  // Update registry
+  registry.worktrees[name].status = 'destroyed';
+  registry.worktrees[name].destroyedAt = new Date().toISOString();
+  saveRegistry(root, registry);
+}
+
+/**
+ * Prune stale worktree entries
+ * @param {Object} options - Prune options
+ * @param {number} [options.maxAgeDays] - Remove entries older than this many days
+ * @returns {Array} Pruned entries
+ */
+function pruneWorktrees(options = {}) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const { maxAgeDays = 30 } = options;
+
+  const now = new Date();
+  const pruned = [];
+
+  for (const [name, entry] of Object.entries(registry.worktrees)) {
+    const created = new Date(entry.createdAt);
+    const ageDays = (now - created) / (1000 * 60 * 60 * 24);
+
+    const shouldPrune =
+      entry.status === 'destroyed' ||
+      (!fs.existsSync(entry.path) && ageDays > maxAgeDays) ||
+      (maxAgeDays === 0 && entry.status === 'destroyed');
+
+    if (shouldPrune) {
+      // Clean up filesystem if still exists
+      if (fs.existsSync(entry.path)) {
+        try {
+          execFileSync('git', ['worktree', 'remove', '--force', entry.path], {
+            cwd: root,
+            stdio: 'pipe',
+          });
+        } catch {
+          fs.removeSync(entry.path);
+        }
+      }
+      pruned.push(entry);
+      delete registry.worktrees[name];
+    }
+  }
+
+  // Prune git's worktree list
+  try {
+    execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
+  } catch {
+    // Non-fatal
+  }
+
+  saveRegistry(root, registry);
+  return pruned;
+}
+
+module.exports = {
+  createWorktree,
+  listWorktrees,
+  destroyWorktree,
+  pruneWorktrees,
+  loadRegistry,
+  getRepoRoot,
+  WORKTREES_DIR,
+  REGISTRY_FILE,
+  BRANCH_PREFIX,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {
@@ -51,6 +51,10 @@
     "url": "https://github.com/Paths-Design/coding-agent-working-standard.git",
     "directory": "packages/caws-cli"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "dependencies": {
     "chalk": "4.1.2",
     "commander": "^11.0.0",

package/templates/.caws/schemas/scope.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Lite Scope Configuration",
+  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs",
+  "type": "object",
+  "required": ["version", "allowedDirectories"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version"
+    },
+    "allowedDirectories": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Directories the agent is allowed to modify (e.g., src/, tests/)"
+    },
+    "bannedPatterns": {
+      "type": "object",
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns for banned file names (e.g., *-enhanced.*, *-final.*)"
+        },
+        "directories": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns for banned directory names (e.g., *venv*, .venv)"
+        },
+        "docs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns for banned doc file names (e.g., *-summary.md)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "maxNewFilesPerCommit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "Maximum number of new files allowed per commit (prevents file sprawl)"
+    },
+    "designatedVenvPath": {
+      "type": "string",
+      "description": "The only allowed virtual environment path (e.g., .venv)"
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -16,7 +16,7 @@
     "contracts"
   ],
   "properties": {
-    "id": { "type": "string", "pattern": "^(PROJ|FEAT|FIX|ARCH)-\\d{4}$" },
+    "id": { "type": "string", "pattern": "^[A-Z]{2,6}-\\d{3,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"] },

package/templates/.caws/schemas/worktrees.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Worktree Registry",
+  "description": "Registry of git worktrees managed by CAWS for agent scope isolation",
+  "type": "object",
+  "required": ["version", "worktrees"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "worktrees": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["name", "path", "branch", "baseBranch", "createdAt", "status"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
+          "path": { "type": "string" },
+          "branch": { "type": "string" },
+          "baseBranch": { "type": "string" },
+          "scope": { "type": ["string", "null"] },
+          "specId": { "type": ["string", "null"] },
+          "createdAt": { "type": "string", "format": "date-time" },
+          "destroyedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["active", "orphaned", "missing", "destroyed"]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/templates/.claude/hooks/block-dangerous.sh

@@ -65,11 +65,44 @@ DANGEROUS_PATTERNS=(
   'reboot'
   'init 0'
   'init 6'
+
+  # Git destructive operations
+  'git init'
+  'git reset --hard'
+  'git push --force'
+  'git push -f '
+  'git push --force-with-lease'
+  'git clean -f'
+  'git checkout \.'
+  'git restore \.'
+
+  # Virtual environment creation (prevents venv sprawl)
+  'python -m venv'
+  'python3 -m venv'
+  'virtualenv '
+  'conda create'
 )
 
 # Check command against dangerous patterns
 for pattern in "${DANGEROUS_PATTERNS[@]}"; do
   if echo "$COMMAND" | grep -qiE "$pattern"; then
+    # Allow git init in worktree context
+    if [[ "$pattern" == "git init" ]] && [[ "${CAWS_WORKTREE_CONTEXT:-0}" == "1" ]]; then
+      continue
+    fi
+
+    # Allow venv commands if target matches designated venv path from scope.json
+    if echo "$pattern" | grep -qE '(python.*venv|virtualenv|conda create)'; then
+      PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+      SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
+      if [[ -f "$SCOPE_FILE" ]] && command -v node >/dev/null 2>&1; then
+        DESIGNATED_VENV=$(node -e "try { const s = JSON.parse(require('fs').readFileSync('$SCOPE_FILE','utf8')); console.log(s.designatedVenvPath || ''); } catch(e) { console.log(''); }" 2>/dev/null || echo "")
+        if [[ -n "$DESIGNATED_VENV" ]] && echo "$COMMAND" | grep -qF "$DESIGNATED_VENV"; then
+          continue
+        fi
+      fi
+    fi
+
     # Output to stderr for Claude to see
     echo "BLOCKED: Command matches dangerous pattern: $pattern" >&2
     echo "Command was: $COMMAND" >&2

package/templates/.claude/hooks/lite-sprawl-check.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# CAWS Lite-Mode Sprawl Check Hook
+# Checks for file sprawl patterns (banned names, venv dirs, doc sprawl)
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Write operations (new file creation)
+if [[ "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
+
+# Only active in lite mode (scope.json present, no working-spec.yaml)
+if [[ ! -f "$SCOPE_FILE" ]]; then
+  exit 0
+fi
+
+# Get relative path
+# Get relative path (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+BASENAME=$(basename "$REL_PATH")
+
+# Use Node.js to check banned patterns
+if command -v node >/dev/null 2>&1; then
+  SPRAWL_CHECK=$(node -e "
+    const fs = require('fs');
+    const path = require('path');
+    try {
+      const scope = JSON.parse(fs.readFileSync('$SCOPE_FILE', 'utf8'));
+      const filePath = '$REL_PATH';
+      const basename = '$BASENAME';
+      const banned = scope.bannedPatterns || {};
+
+      function matchGlob(str, pattern) {
+        const regex = new RegExp('^' + pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.') + '$');
+        return regex.test(str);
+      }
+
+      // Check banned file patterns
+      for (const p of (banned.files || [])) {
+        if (matchGlob(basename, p)) {
+          console.log('banned_file:' + p);
+          process.exit(0);
+        }
+      }
+
+      // Check banned doc patterns
+      for (const p of (banned.docs || [])) {
+        if (matchGlob(basename, p)) {
+          console.log('banned_doc:' + p);
+          process.exit(0);
+        }
+      }
+
+      // Check banned directory patterns
+      const parts = filePath.split('/');
+      for (const part of parts) {
+        for (const p of (banned.directories || [])) {
+          if (matchGlob(part, p)) {
+            console.log('banned_dir:' + p + ':' + part);
+            process.exit(0);
+          }
+        }
+      }
+
+      console.log('ok');
+    } catch (error) {
+      console.log('error:' + error.message);
+    }
+  " 2>&1)
+
+  if [[ "$SPRAWL_CHECK" == banned_file:* ]]; then
+    PATTERN="${SPRAWL_CHECK#banned_file:}"
+    echo "BLOCKED: File name matches banned sprawl pattern: $PATTERN" >&2
+    echo "File: $REL_PATH" >&2
+    echo "Banned patterns prevent shadow files like *-enhanced.*, *-final.*, *-v2.*, *-copy.*" >&2
+    echo "Instead, modify the original file directly." >&2
+    exit 2
+  fi
+
+  if [[ "$SPRAWL_CHECK" == banned_doc:* ]]; then
+    PATTERN="${SPRAWL_CHECK#banned_doc:}"
+    echo "BLOCKED: Doc file matches banned sprawl pattern: $PATTERN" >&2
+    echo "File: $REL_PATH" >&2
+    echo "Avoid creating many summary/recap/plan files. Update existing documentation instead." >&2
+    exit 2
+  fi
+
+  if [[ "$SPRAWL_CHECK" == banned_dir:* ]]; then
+    IFS=':' read -r _ PATTERN DIR_NAME <<< "$SPRAWL_CHECK"
+    echo "BLOCKED: Directory matches banned pattern: $PATTERN (directory: $DIR_NAME)" >&2
+    echo "File: $REL_PATH" >&2
+    echo "Use the designated venv path instead of creating new virtual environments." >&2
+    exit 2
+  fi
+fi
+
+# Allow the operation
+exit 0