@paths.design/caws-cli 8.0.1 → 8.1.0

package/dist/scaffold/claude-hooks.js

@@ -0,0 +1,316 @@
+/**
+ * @fileoverview Claude Code Hooks Scaffolding
+ * Functions for setting up Claude Code hooks for CAWS projects
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+// Import detection utilities
+const { detectCAWSSetup, findPackageRoot } = require('../utils/detection');
+
+/**
+ * Scaffold Claude Code hooks for a CAWS project
+ * Creates .claude/settings.json with hooks and .claude/hooks/ directory with scripts
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string[]} levels - Hook levels to enable: 'safety', 'quality', 'scope', 'audit'
+ */
+async function scaffoldClaudeHooks(projectDir, levels = ['safety', 'quality', 'scope', 'audit']) {
+  try {
+    const claudeDir = path.join(projectDir, '.claude');
+    const claudeHooksDir = path.join(claudeDir, 'hooks');
+
+    // Create .claude directory structure
+    await fs.ensureDir(claudeDir);
+    await fs.ensureDir(claudeHooksDir);
+
+    // Determine template directory - prefer bundled templates
+    const setup = detectCAWSSetup(projectDir);
+
+    // Find package root using shared utility
+    const packageRoot = findPackageRoot(__dirname);
+
+    // Try templates relative to package root first (works in both dev and global install)
+    const bundledTemplateDir = path.join(packageRoot, 'templates');
+    const fallbackTemplateDir = path.join(__dirname, '../../templates');
+    const templateDir = fs.existsSync(bundledTemplateDir)
+      ? bundledTemplateDir
+      : fs.existsSync(fallbackTemplateDir)
+      ? fallbackTemplateDir
+      : setup.templateDir || path.resolve(__dirname, '../templates');
+
+    const claudeTemplateDir = path.join(templateDir, '.claude');
+    const claudeHooksTemplateDir = path.join(claudeTemplateDir, 'hooks');
+
+    if (!fs.existsSync(claudeTemplateDir)) {
+      console.warn(chalk.yellow('⚠️  Claude Code hooks templates not found'));
+      console.warn(chalk.blue('💡 Skipping Claude Code hooks setup'));
+      return;
+    }
+
+    // Map levels to hook scripts
+    const hookMapping = {
+      safety: ['block-dangerous.sh', 'scan-secrets.sh'],
+      quality: ['quality-check.sh', 'validate-spec.sh'],
+      scope: ['scope-guard.sh', 'naming-check.sh'],
+      audit: ['audit.sh'],
+    };
+
+    // Determine which hooks to enable
+    const enabledHooks = new Set();
+    levels.forEach((level) => {
+      const hooks = hookMapping[level] || [];
+      hooks.forEach((hook) => enabledHooks.add(hook));
+    });
+
+    // Always enable audit.sh if any hooks are enabled
+    if (enabledHooks.size > 0) {
+      enabledHooks.add('audit.sh');
+    }
+
+    // Copy enabled hook scripts
+    const allHookScripts = [
+      'audit.sh',
+      'validate-spec.sh',
+      'quality-check.sh',
+      'scan-secrets.sh',
+      'block-dangerous.sh',
+      'scope-guard.sh',
+      'naming-check.sh',
+    ];
+
+    for (const script of allHookScripts) {
+      if (enabledHooks.has(script)) {
+        const sourcePath = path.join(claudeHooksTemplateDir, script);
+        const destPath = path.join(claudeHooksDir, script);
+
+        if (fs.existsSync(sourcePath)) {
+          await fs.copy(sourcePath, destPath);
+          // Make executable
+          await fs.chmod(destPath, 0o755);
+        }
+      }
+    }
+
+    // Generate settings.json with hooks configuration
+    const settings = generateClaudeSettings(levels, enabledHooks);
+
+    // Check for existing settings and merge
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      try {
+        const existingSettings = await fs.readJSON(settingsPath);
+        // Merge hooks, preserving existing non-hook settings
+        settings.hooks = {
+          ...existingSettings.hooks,
+          ...settings.hooks,
+        };
+        // Preserve other settings
+        Object.keys(existingSettings).forEach((key) => {
+          if (key !== 'hooks' && !(key in settings)) {
+            settings[key] = existingSettings[key];
+          }
+        });
+      } catch (error) {
+        console.warn(chalk.yellow('⚠️  Could not merge existing settings:'), error.message);
+      }
+    }
+
+    // Write settings.json
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+
+    // Copy README if it exists
+    const readmePath = path.join(claudeTemplateDir, 'README.md');
+    if (fs.existsSync(readmePath)) {
+      await fs.copy(readmePath, path.join(claudeDir, 'README.md'));
+    }
+
+    console.log(chalk.green('✅ Claude Code hooks configured'));
+    console.log(chalk.gray(`   Enabled: ${levels.join(', ')}`));
+    console.log(
+      chalk.gray(`   Scripts: ${Array.from(enabledHooks).length} hook scripts installed`)
+    );
+    console.log(chalk.blue('💡 Hooks will activate on next Claude Code session'));
+  } catch (error) {
+    console.error(chalk.yellow('⚠️  Failed to setup Claude Code hooks:'), error.message);
+    console.log(chalk.blue('💡 You can manually copy .claude/ directory later'));
+  }
+}
+
+/**
+ * Generate Claude Code settings with hooks configuration
+ * @param {string[]} levels - Enabled hook levels
+ * @param {Set<string>} enabledHooks - Set of enabled hook script names
+ * @returns {Object} Settings object for settings.json
+ */
+function generateClaudeSettings(levels, _enabledHooks) {
+  const settings = {
+    hooks: {},
+  };
+
+  // Build hooks configuration based on enabled levels
+  // Claude Code uses different event names and matcher patterns
+
+  if (levels.includes('safety')) {
+    // Block dangerous bash commands
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+    settings.hooks.PreToolUse.push({
+      matcher: 'Bash',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/block-dangerous.sh',
+          timeout: 10,
+        },
+      ],
+    });
+
+    // Scan for secrets on file read
+    settings.hooks.PreToolUse.push({
+      matcher: 'Read',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/scan-secrets.sh',
+          timeout: 10,
+        },
+      ],
+    });
+  }
+
+  if (levels.includes('quality')) {
+    // Run quality checks after file edits
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+    settings.hooks.PostToolUse.push({
+      matcher: 'Write|Edit',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/quality-check.sh',
+          timeout: 30,
+        },
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/validate-spec.sh',
+          timeout: 15,
+        },
+      ],
+    });
+  }
+
+  if (levels.includes('scope')) {
+    // Scope guard before file writes
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+    settings.hooks.PreToolUse.push({
+      matcher: 'Write|Edit',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/scope-guard.sh',
+          timeout: 10,
+        },
+      ],
+    });
+
+    // Naming check after edits
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+    settings.hooks.PostToolUse.push({
+      matcher: 'Write|Edit',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/naming-check.sh',
+          timeout: 10,
+        },
+      ],
+    });
+  }
+
+  if (levels.includes('audit')) {
+    // Session audit logging
+    settings.hooks.SessionStart = settings.hooks.SessionStart || [];
+    settings.hooks.SessionStart.push({
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/audit.sh session-start',
+          timeout: 5,
+        },
+      ],
+    });
+
+    settings.hooks.Stop = settings.hooks.Stop || [];
+    settings.hooks.Stop.push({
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/audit.sh stop',
+          timeout: 5,
+        },
+      ],
+    });
+
+    // Audit tool usage
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+    settings.hooks.PostToolUse.push({
+      matcher: 'Write|Edit|Bash',
+      hooks: [
+        {
+          type: 'command',
+          command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/audit.sh tool-use',
+          timeout: 5,
+        },
+      ],
+    });
+  }
+
+  return settings;
+}
+
+/**
+ * Check if Claude Code hooks are already configured
+ * @param {string} projectDir - Project directory
+ * @returns {boolean} True if hooks are configured
+ */
+function hasClaudeHooks(projectDir) {
+  const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return false;
+  }
+
+  try {
+    const settings = fs.readJSONSync(settingsPath);
+    return settings.hooks && Object.keys(settings.hooks).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List configured Claude Code hooks
+ * @param {string} projectDir - Project directory
+ * @returns {Object} Hook configuration or null
+ */
+function getClaudeHooksConfig(projectDir) {
+  const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return null;
+  }
+
+  try {
+    const settings = fs.readJSONSync(settingsPath);
+    return settings.hooks || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  scaffoldClaudeHooks,
+  generateClaudeSettings,
+  hasClaudeHooks,
+  getClaudeHooksConfig,
+};

package/dist/scaffold/index.js

@@ -16,6 +16,9 @@ const { detectsPublishing } = require('../utils/project-analysis');
 const { scaffoldGitHooks } = require('./git-hooks');
 const { updateGitignore } = require('../utils/gitignore-updater');
 
+// Import Claude Code hooks scaffolding
+const { scaffoldClaudeHooks } = require('./claude-hooks');
+
 // CLI version from package.json
 const CLI_VERSION = require('../../package.json').version;
 
@@ -120,8 +123,22 @@ async function scaffoldIDEIntegrations(targetDir, options) {
       dest: '.cursor/README.md',
       desc: 'Cursor integration documentation',
     },
+
+    // Claude Code hooks
+    {
+      src: '.claude/README.md',
+      dest: '.claude/README.md',
+      desc: 'Claude Code integration documentation',
+    },
   ];
 
+  // Setup Claude Code hooks
+  try {
+    await scaffoldClaudeHooks(targetDir, ['safety', 'quality', 'scope', 'audit']);
+  } catch (error) {
+    console.log(chalk.yellow(`⚠️  Claude Code hooks setup failed: ${error.message}`));
+  }
+
   for (const template of ideTemplates) {
     const srcPath = path.join(templateDir, template.src);
     const destPath = path.join(targetDir, template.dest);
@@ -769,5 +786,6 @@ async function scaffoldProject(options) {
 module.exports = {
   scaffoldProject,
   scaffoldIDEIntegrations,
+  scaffoldClaudeHooks,
   setScaffoldDependencies,
 };

package/dist/templates/.claude/README.md

@@ -0,0 +1,190 @@
+# Claude Code Integration for CAWS
+
+This directory contains Claude Code hooks and configuration for CAWS (Coding Agent Working Standard) integration.
+
+## Overview
+
+CAWS hooks for Claude Code provide:
+
+- **Safety Gates**: Block dangerous commands and scan for secrets
+- **Quality Gates**: Run CAWS quality checks after file edits
+- **Scope Guards**: Validate edits against the working spec's scope
+- **Audit Logging**: Track agent actions for compliance
+
+## Directory Structure
+
+```
+.claude/
+├── settings.json      # Claude Code settings with hooks configuration
+├── hooks/             # Hook scripts
+│   ├── audit.sh           # Session and action logging
+│   ├── block-dangerous.sh # Block destructive commands
+│   ├── scan-secrets.sh    # Warn when reading sensitive files
+│   ├── quality-check.sh   # Run CAWS quality gates
+│   ├── validate-spec.sh   # Validate spec files
+│   ├── scope-guard.sh     # Check scope boundaries
+│   └── naming-check.sh    # Validate file naming conventions
+├── logs/              # Audit logs (gitignored)
+└── README.md          # This file
+```
+
+## Hook Events
+
+### PreToolUse Hooks
+
+Run before Claude executes a tool:
+
+| Hook | Matcher | Purpose |
+|------|---------|---------|
+| `block-dangerous.sh` | `Bash` | Block destructive shell commands |
+| `scan-secrets.sh` | `Read` | Warn when reading sensitive files |
+| `scope-guard.sh` | `Write\|Edit` | Check scope boundaries before edits |
+
+### PostToolUse Hooks
+
+Run after Claude executes a tool:
+
+| Hook | Matcher | Purpose |
+|------|---------|---------|
+| `quality-check.sh` | `Write\|Edit` | Run CAWS quality gates |
+| `validate-spec.sh` | `Write\|Edit` | Validate spec file changes |
+| `naming-check.sh` | `Write` | Check file naming conventions |
+| `audit.sh` | `Write\|Edit\|Bash` | Log tool usage |
+
+### Session Hooks
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `audit.sh session-start` | `SessionStart` | Log session start |
+| `audit.sh stop` | `Stop` | Log session end |
+
+## Configuration
+
+### Enable/Disable Hooks
+
+Edit `settings.json` to enable or disable specific hooks. Remove entries from the `hooks` object to disable them.
+
+### Hook Levels
+
+The scaffold supports four hook levels:
+
+- **safety**: Block dangerous commands, scan for secrets
+- **quality**: Run quality gates on file edits
+- **scope**: Validate edits against spec scope
+- **audit**: Log all agent actions
+
+Run `caws init --hooks=safety,quality` to enable specific levels.
+
+## Audit Logs
+
+Audit logs are written to `.claude/logs/`:
+
+- `audit.log` - All-time log (appended)
+- `audit-YYYY-MM-DD.log` - Daily logs
+
+Logs are JSON-formatted for easy parsing:
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "session_id": "abc123",
+  "event": "tool_use",
+  "tool": "Write",
+  "file": "src/index.ts",
+  "cwd": "/project"
+}
+```
+
+## Customization
+
+### Adding Custom Hooks
+
+1. Create a new script in `.claude/hooks/`
+2. Make it executable: `chmod +x .claude/hooks/my-hook.sh`
+3. Add it to `settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/my-hook.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook Input/Output
+
+Hooks receive JSON input via stdin:
+
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/path/to/file.ts",
+    "content": "..."
+  },
+  "tool_response": { "success": true }
+}
+```
+
+Hooks can output JSON to control Claude's behavior:
+
+```json
+{
+  "decision": "block",
+  "reason": "Quality gate failed: ..."
+}
+```
+
+Or add context:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Remember to update the tests."
+  }
+}
+```
+
+## Troubleshooting
+
+### Hooks Not Running
+
+1. Check `settings.json` syntax: `cat .claude/settings.json | jq .`
+2. Verify scripts are executable: `ls -la .claude/hooks/`
+3. Test hooks manually: `echo '{}' | .claude/hooks/audit.sh`
+
+### Permission Errors
+
+Make all hook scripts executable:
+
+```bash
+chmod +x .claude/hooks/*.sh
+```
+
+### Debug Hooks
+
+Run Claude Code with `--debug` to see hook execution details:
+
+```bash
+claude --debug
+```
+
+## Further Reading
+
+- [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
+- [CAWS Quality Gates](../../docs/quality-gates.md)
+- [CAWS Scope Management](../../docs/scope-management.md)

package/dist/templates/.claude/hooks/audit.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# CAWS Audit Hook for Claude Code
+# Logs agent actions for compliance and debugging
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Get event type from argument or input
+EVENT_TYPE="${1:-tool-use}"
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Parse common fields from Claude Code hook input
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+PERMISSION_MODE=$(echo "$INPUT" | jq -r '.permission_mode // "default"')
+
+# Ensure log directory exists
+LOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/logs"
+mkdir -p "$LOG_DIR"
+
+# Log file path
+LOG_FILE="$LOG_DIR/audit.log"
+DATE_LOG_FILE="$LOG_DIR/audit-$(date +%Y-%m-%d).log"
+
+# Timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Build log entry based on event type
+case "$EVENT_TYPE" in
+  session-start)
+    SOURCE=$(echo "$INPUT" | jq -r '.source // "unknown"')
+    MODEL=$(echo "$INPUT" | jq -r '.model // "unknown"')
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "session_start" \
+      --arg source "$SOURCE" \
+      --arg model "$MODEL" \
+      --arg cwd "$CWD" \
+      '{timestamp: $ts, session_id: $sid, event: $event, source: $source, model: $model, cwd: $cwd}')
+    ;;
+
+  stop)
+    STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "session_stop" \
+      --arg cwd "$CWD" \
+      --argjson hook_active "$STOP_HOOK_ACTIVE" \
+      '{timestamp: $ts, session_id: $sid, event: $event, cwd: $cwd, stop_hook_active: $hook_active}')
+    ;;
+
+  tool-use)
+    # Extract tool-specific info
+    TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
+    TOOL_RESPONSE=$(echo "$INPUT" | jq -c '.tool_response // {}')
+    TOOL_USE_ID=$(echo "$INPUT" | jq -r '.tool_use_id // ""')
+
+    # For file operations, extract the path
+    FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.file_path // ""')
+    COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // ""')
+
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "tool_use" \
+      --arg tool "$TOOL_NAME" \
+      --arg file "$FILE_PATH" \
+      --arg cmd "$COMMAND" \
+      --arg cwd "$CWD" \
+      --arg mode "$PERMISSION_MODE" \
+      '{timestamp: $ts, session_id: $sid, event: $event, tool: $tool, file: $file, command: $cmd, cwd: $cwd, permission_mode: $mode}')
+    ;;
+
+  *)
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "$EVENT_TYPE" \
+      --arg hook "$HOOK_EVENT" \
+      --arg cwd "$CWD" \
+      '{timestamp: $ts, session_id: $sid, event: $event, hook_event: $hook, cwd: $cwd}')
+    ;;
+esac
+
+# Append to log files
+echo "$LOG_ENTRY" >> "$LOG_FILE"
+echo "$LOG_ENTRY" >> "$DATE_LOG_FILE"
+
+# Success - allow operation to continue
+exit 0