@paths.design/caws-cli 8.0.0 → 8.1.0

package/dist/minimal-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=minimal-cli.d.ts.map

package/dist/minimal-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minimal-cli.d.ts","sourceRoot":"","sources":["../src/minimal-cli.js"],"names":[],"mappings":""}

package/dist/minimal-cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Minimal CAWS CLI to test Chalk functionality
+ * @fileoverview Minimal CAWS CLI for testing and development
+ * Provides a lightweight CLI structure with version and help commands
+ * for quick verification of CLI functionality.
  * @author @darianrosebrook
  */
 

package/dist/policy/PolicyManager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Policy Manager - Handles policy loading with intelligent caching
+ *
+ * Features:
+ * - TTL-based caching for performance
+ * - Graceful fallback to defaults when policy.yaml missing
+ * - Cache inspection and management API
+ * - Waiver validation and delta application
+ */
+export class PolicyManager {
+    constructor(options?: {});
+    enableCaching: any;
+    cacheTTL: any;
+    policyCache: Map<any, any>;
+    /**
+     * Load CAWS policy from policy.yaml with caching
+     *
+     * @param {string} projectRoot - Project root directory
+     * @param {Object} options - Loading options
+     * @param {boolean} options.useCache - Use cache if available (default: true)
+     * @param {number} options.cacheTTL - Cache TTL override in milliseconds
+     * @returns {Promise<Object>} Policy object
+     */
+    loadPolicy(projectRoot: string, options?: {
+        useCache: boolean;
+        cacheTTL: number;
+    }): Promise<any>;
+    /**
+     * Load a waiver document by ID
+     *
+     * @param {string} waiverId - Waiver ID (e.g., WV-0001)
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object|null>} Waiver document or null if not found
+     */
+    loadWaiver(waiverId: string, projectRoot: string): Promise<any | null>;
+    /**
+     * Check if a waiver is currently valid
+     *
+     * @param {Object} waiver - Waiver document
+     * @returns {boolean} True if waiver is valid and active
+     */
+    isWaiverValid(waiver: any): boolean;
+    /**
+     * Apply waivers to baseline budget
+     *
+     * @param {Object} baseline - Baseline budget from policy
+     * @param {string[]} waiverIds - Array of waiver IDs to apply
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object>} Effective budget with waivers applied
+     */
+    applyWaivers(baseline: any, waiverIds: string[], projectRoot: string): Promise<any>;
+    /**
+     * Validate policy structure
+     *
+     * @param {Object} policy - Policy to validate
+     * @throws {Error} If policy is invalid
+     */
+    validatePolicy(policy: any): void;
+    /**
+     * Get default CAWS policy
+     *
+     * Returns sensible defaults when policy.yaml doesn't exist.
+     *
+     * @returns {Object} Default policy configuration
+     */
+    getDefaultPolicy(): any;
+    /**
+     * Clear policy cache
+     *
+     * @param {string} [projectRoot] - Specific project to clear, or all if omitted
+     */
+    clearCache(projectRoot?: string): void;
+    /**
+     * Get cache status for a project
+     *
+     * @param {string} projectRoot - Project root directory
+     * @returns {Object} Cache status information
+     */
+    getCacheStatus(projectRoot: string): any;
+    /**
+     * Reload policy from disk (bypassing cache)
+     *
+     * @param {string} projectRoot - Project root directory
+     * @returns {Promise<Object>} Fresh policy
+     */
+    reloadPolicy(projectRoot: string): Promise<any>;
+    /**
+     * Get all cached projects
+     *
+     * @returns {string[]} Array of project roots with cached policies
+     */
+    getCachedProjects(): string[];
+    /**
+     * Get cache statistics
+     *
+     * @returns {Object} Cache statistics
+     */
+    getCacheStats(): any;
+}
+export const defaultPolicyManager: PolicyManager;
+export declare function loadPolicy(projectRoot: any, options: any): Promise<any>;
+export declare function clearCache(projectRoot: any): void;
+export declare function getCacheStatus(projectRoot: any): any;
+//# sourceMappingURL=PolicyManager.d.ts.map

package/dist/policy/PolicyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyManager.d.ts","sourceRoot":"","sources":["../../src/policy/PolicyManager.js"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH;IACE,0BAIC;IAHC,mBAAkD;IAClD,cAA0C;IAC1C,2BAA4B;IAG9B;;;;;;;;OAQG;IACH,wBANW,MAAM,YAEd;QAAyB,QAAQ,EAAzB,OAAO;QACS,QAAQ,EAAxB,MAAM;KACd,GAAU,OAAO,KAAQ,CAuG3B;IAED;;;;;;OAMG;IACH,qBAJW,MAAM,eACN,MAAM,GACJ,OAAO,CAAC,MAAO,IAAI,CAAC,CAchC;IAED;;;;;OAKG;IACH,4BAFa,OAAO,CA2BnB;IAED;;;;;;;OAOG;IACH,uCAJW,MAAM,EAAE,eACR,MAAM,GACJ,OAAO,KAAQ,CA2B3B;IAED;;;;;OAKG;IACH,kCA8BC;IAED;;;;;;OAMG;IACH,wBAoDC;IAED;;;;OAIG;IACH,yBAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,OAmBhB;IAED;;;;;OAKG;IACH,0BAHW,MAAM,GACJ,OAAO,KAAQ,CAK3B;IAED;;;;OAIG;IACH,qBAFa,MAAM,EAAE,CAIpB;IAED;;;;OAIG;IACH,qBA2BC;CACF;AAGD,iDAAiD;AAOnC,iFAA+E;AAC/E,2DAA6D;AACzD,8DAAiE"}

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/cursor-hooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Scaffold Cursor hooks for a CAWS project
+ * @param {string} projectDir - Project directory path
+ * @param {string[]} levels - Hook levels to enable
+ */
+export function scaffoldCursorHooks(projectDir: string, levels?: string[]): Promise<void>;
+//# sourceMappingURL=cursor-hooks.d.ts.map

package/dist/scaffold/cursor-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-hooks.d.ts","sourceRoot":"","sources":["../../src/scaffold/cursor-hooks.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,gDAHW,MAAM,WACN,MAAM,EAAE,iBA6JlB"}

package/dist/scaffold/git-hooks.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Scaffold git hooks for CAWS provenance tracking
+ * @param {string} projectDir - Project directory path
+ * @param {Object} options - Hook options
+ */
+export function scaffoldGitHooks(projectDir: string, options?: any): Promise<{
+    added: number;
+    skipped: number;
+}>;
+/**
+ * Remove CAWS git hooks
+ * @param {string} projectDir - Project directory path
+ */
+export function removeGitHooks(projectDir: string): Promise<void>;
+/**
+ * Check git hooks status
+ * @param {string} projectDir - Project directory path
+ */
+export function checkGitHooksStatus(projectDir: string): Promise<void>;
+/**
+ * Generate pre-push hook content
+ * Blocks --no-verify to enforce quality gates before pushing
+ */
+export function generatePrePushHook(): string;
+/**
+ * Generate pre-commit hook content with staged file quality gates
+ * Implements fallback chain: Node script → CLI → Python scripts → Skip gracefully
+ */
+export function generatePreCommitHook(options: any): string;
+/**
+ * Generate post-commit hook content
+ */
+export function generatePostCommitHook(): string;
+/**
+ * Generate commit-msg hook content
+ */
+export function generateCommitMsgHook(): string;
+//# sourceMappingURL=git-hooks.d.ts.map

package/dist/scaffold/git-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-hooks.d.ts","sourceRoot":"","sources":["../../src/scaffold/git-hooks.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,6CAHW,MAAM;;;GAwGhB;AA4kBD;;;GAGG;AACH,2CAFW,MAAM,iBAkChB;AAED;;;GAGG;AACH,gDAFW,MAAM,iBAgDhB;AA9VD;;;GAGG;AACH,8CAqNC;AA7hBD;;;GAGG;AACH,4DAsRC;AAED;;GAEG;AACH,iDAmCC;AA6ND;;GAEG;AACH,gDAsCC"}

package/dist/scaffold/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Scaffold existing project with CAWS components
+ * @param {Object} options - Scaffold options
+ */
+export function scaffoldProject(options: any): Promise<void>;
+export function scaffoldIDEIntegrations(targetDir: any, options: any): Promise<{
+    added: number;
+    skipped: number;
+}>;
+/**
+ * Set dependencies for scaffold module
+ * @param {Object} deps - Dependencies object
+ */
+export function setScaffoldDependencies(deps: any): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/scaffold/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.js"],"names":[],"mappings":"AA6LA;;;GAGG;AACH,6DA6jBC;AA3sBD;;;GA2HC;AAMD;;;GAGG;AACH,yDAGC"}

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,
 };