@paths.design/caws-cli 3.1.0 → 3.2.0

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,iBAmIlB"}

package/dist/scaffold/cursor-hooks.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Cursor Hooks Scaffolding
+ * Functions for setting up Cursor IDE hooks for CAWS
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+// Import detection utilities
+const { detectCAWSSetup } = require('../utils/detection');
+
+/**
+ * Scaffold Cursor hooks for a CAWS project
+ * @param {string} projectDir - Project directory path
+ * @param {string[]} levels - Hook levels to enable
+ */
+async function scaffoldCursorHooks(projectDir, levels = ['safety', 'quality', 'scope', 'audit']) {
+  try {
+    const cursorDir = path.join(projectDir, '.cursor');
+    const cursorHooksDir = path.join(cursorDir, 'hooks');
+
+    // Create .cursor directory structure
+    await fs.ensureDir(cursorDir);
+    await fs.ensureDir(cursorHooksDir);
+    await fs.ensureDir(path.join(cursorDir, 'logs'));
+
+    // Determine template directory
+    const setup = detectCAWSSetup(projectDir);
+    const templateDir = setup.templateDir || path.resolve(__dirname, '../templates');
+
+    const cursorTemplateDir = path.join(templateDir, '.cursor');
+    const cursorHooksTemplateDir = path.join(cursorTemplateDir, 'hooks');
+
+    if (!fs.existsSync(cursorTemplateDir)) {
+      console.warn(chalk.yellow('⚠️  Cursor hooks templates not found'));
+      console.warn(chalk.blue('💡 Skipping Cursor hooks setup'));
+      return;
+    }
+
+    // Map levels to hook scripts
+    const hookMapping = {
+      safety: ['scan-secrets.sh', 'block-dangerous.sh'],
+      quality: ['format.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',
+      'format.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(cursorHooksTemplateDir, script);
+        const destPath = path.join(cursorHooksDir, script);
+
+        if (fs.existsSync(sourcePath)) {
+          await fs.copy(sourcePath, destPath);
+          // Make executable
+          await fs.chmod(destPath, 0o755);
+        }
+      }
+    }
+
+    // Generate hooks.json based on enabled hooks
+    const hooksConfig = {
+      version: 1,
+      hooks: {},
+    };
+
+    // Build hooks configuration based on enabled levels
+    if (levels.includes('safety')) {
+      hooksConfig.hooks.beforeShellExecution = [
+        { command: './.cursor/hooks/block-dangerous.sh' },
+        { command: './.cursor/hooks/audit.sh' },
+      ];
+      hooksConfig.hooks.beforeMCPExecution = [{ command: './.cursor/hooks/audit.sh' }];
+      hooksConfig.hooks.beforeReadFile = [{ command: './.cursor/hooks/scan-secrets.sh' }];
+    }
+
+    if (levels.includes('quality')) {
+      hooksConfig.hooks.afterFileEdit = hooksConfig.hooks.afterFileEdit || [];
+      hooksConfig.hooks.afterFileEdit.push(
+        { command: './.cursor/hooks/format.sh' },
+        { command: './.cursor/hooks/validate-spec.sh' }
+      );
+    }
+
+    if (levels.includes('scope')) {
+      hooksConfig.hooks.afterFileEdit = hooksConfig.hooks.afterFileEdit || [];
+      hooksConfig.hooks.afterFileEdit.push({ command: './.cursor/hooks/naming-check.sh' });
+      hooksConfig.hooks.beforeSubmitPrompt = [
+        { command: './.cursor/hooks/scope-guard.sh' },
+        { command: './.cursor/hooks/audit.sh' },
+      ];
+    }
+
+    if (levels.includes('audit')) {
+      // Add audit to all events
+      if (!hooksConfig.hooks.afterFileEdit) {
+        hooksConfig.hooks.afterFileEdit = [];
+      }
+      hooksConfig.hooks.afterFileEdit.push({ command: './.cursor/hooks/audit.sh' });
+
+      hooksConfig.hooks.stop = [{ command: './.cursor/hooks/audit.sh' }];
+    }
+
+    // Write hooks.json
+    await fs.writeFile(path.join(cursorDir, 'hooks.json'), JSON.stringify(hooksConfig, null, 2));
+
+    // Copy README
+    const readmePath = path.join(cursorTemplateDir, 'README.md');
+    if (fs.existsSync(readmePath)) {
+      await fs.copy(readmePath, path.join(cursorDir, 'README.md'));
+    }
+
+    console.log(chalk.green('✅ Cursor 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('💡 Restart Cursor to activate hooks'));
+  } catch (error) {
+    console.error(chalk.yellow('⚠️  Failed to setup Cursor hooks:'), error.message);
+    console.log(chalk.blue('💡 You can manually copy .cursor/ directory later'));
+  }
+}
+
+module.exports = {
+  scaffoldCursorHooks,
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 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>;
+//# 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":"AASA;;;;GAIG;AACH,6CAHW,MAAM;;;GAuGhB;AAgND;;;GAGG;AACH,2CAFW,MAAM,iBAkChB;AAED;;;GAGG;AACH,gDAFW,MAAM,iBAgDhB"}

package/dist/scaffold/git-hooks.js

@@ -0,0 +1,417 @@
+/**
+ * @fileoverview Git Hooks Scaffolding for CAWS Provenance
+ * Functions for setting up git hooks that automatically update provenance
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Scaffold git hooks for CAWS provenance tracking
+ * @param {string} projectDir - Project directory path
+ * @param {Object} options - Hook options
+ */
+async function scaffoldGitHooks(projectDir, options = {}) {
+  const { provenance = true, validation = true, qualityGates = true, force = false } = options;
+
+  console.log('🔗 Setting up Git hooks for CAWS provenance...');
+
+  const gitDir = path.join(projectDir, '.git');
+  const hooksDir = path.join(gitDir, 'hooks');
+
+  // Check if this is a git repository
+  if (!(await fs.pathExists(gitDir))) {
+    console.log('⚠️  Not a git repository - skipping git hooks setup');
+    console.log('💡 Initialize git first: git init');
+    return { added: 0, skipped: 0 };
+  }
+
+  // Ensure hooks directory exists
+  await fs.ensureDir(hooksDir);
+
+  let addedCount = 0;
+  let skippedCount = 0;
+
+  // Define hook configurations
+  const hooks = [
+    {
+      name: 'pre-commit',
+      description: 'Pre-commit validation and quality checks',
+      enabled: validation || qualityGates,
+      content: generatePreCommitHook({ validation, qualityGates }),
+    },
+    {
+      name: 'post-commit',
+      description: 'Post-commit provenance tracking',
+      enabled: provenance,
+      content: generatePostCommitHook(),
+    },
+    {
+      name: 'pre-push',
+      description: 'Pre-push comprehensive validation',
+      enabled: qualityGates,
+      content: generatePrePushHook(),
+    },
+    {
+      name: 'commit-msg',
+      description: 'Commit message validation',
+      enabled: validation,
+      content: generateCommitMsgHook(),
+    },
+  ];
+
+  for (const hook of hooks) {
+    if (!hook.enabled) continue;
+
+    const hookPath = path.join(hooksDir, hook.name);
+
+    try {
+      // Check if hook already exists
+      const exists = await fs.pathExists(hookPath);
+
+      if (exists && !force) {
+        // Check if it's already a CAWS hook
+        const content = await fs.readFile(hookPath, 'utf8');
+        if (content.includes('# CAWS Hook')) {
+          console.log(`⏭️  Skipped ${hook.description} (already configured)`);
+          skippedCount++;
+          continue;
+        } else {
+          console.log(`⚠️  ${hook.description} exists but not CAWS-managed`);
+          if (!options.backup) {
+            console.log(`💡 Use --force to replace, or --backup to preserve original`);
+            skippedCount++;
+            continue;
+          }
+        }
+      }
+
+      // Backup existing hook if requested
+      if (exists && options.backup) {
+        const backupPath = `${hookPath}.backup.${Date.now()}`;
+        await fs.copy(hookPath, backupPath);
+        console.log(`💾 Backed up existing ${hook.name} to ${path.basename(backupPath)}`);
+      }
+
+      // Write the hook
+      await fs.writeFile(hookPath, hook.content);
+      await fs.chmod(hookPath, 0o755);
+
+      console.log(`✅ Configured ${hook.description}`);
+      addedCount++;
+    } catch (error) {
+      console.log(`❌ Failed to configure ${hook.description}: ${error.message}`);
+    }
+  }
+
+  if (addedCount > 0) {
+    console.log(`\n🔗 Git hooks configured: ${addedCount} hooks active`);
+    console.log('💡 Hooks will run automatically on git operations');
+    console.log('💡 Use --no-verify to skip hooks: git commit --no-verify');
+  }
+
+  return { added: addedCount, skipped: skippedCount };
+}
+
+/**
+ * Generate pre-commit hook content
+ */
+function generatePreCommitHook(options) {
+  const { qualityGates = true } = options;
+
+  return `#!/bin/bash
+# CAWS Pre-commit Hook
+# Runs validation and quality checks before commits
+
+set -e
+
+echo "🔍 CAWS Pre-commit Validation"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Check if CAWS is initialized
+if [ ! -d ".caws" ]; then
+  echo "⚠️  CAWS not initialized - skipping validation"
+  exit 0
+fi
+
+# Run CAWS validation if available
+if command -v caws >/dev/null 2>&1; then
+  echo "📋 Running CAWS validation..."
+  if caws validate --quiet; then
+    echo "✅ CAWS validation passed"
+  else
+    echo "❌ CAWS validation failed"
+    echo "💡 Fix issues or use: git commit --no-verify"
+    exit 1
+  fi
+else
+  echo "⚠️  CAWS CLI not found - install with: npm install -g @paths.design/caws-cli"
+fi
+
+# Run quality gates if enabled
+${
+  qualityGates
+    ? `
+echo "🎯 Running quality gates..."
+if [ -f "package.json" ]; then
+  # Run linting if available
+  if [ -f "node_modules/.bin/eslint" ] || command -v eslint >/dev/null 2>&1; then
+    echo "🔍 Running ESLint..."
+    if npx eslint . --quiet; then
+      echo "✅ ESLint passed"
+    else
+      echo "❌ ESLint failed - fix issues or use --no-verify"
+      exit 1
+    fi
+  fi
+
+  # Run tests if available
+  if [ -f "package.json" ] && grep -q '"test"' package.json; then
+    echo "🧪 Running tests..."
+    if npm test; then
+      echo "✅ Tests passed"
+    else
+      echo "❌ Tests failed - fix issues or use --no-verify"
+      exit 1
+    fi
+  fi
+fi
+`
+    : ''
+}
+
+echo "🎉 Pre-commit checks passed!"
+`;
+}
+
+/**
+ * Generate post-commit hook content
+ */
+function generatePostCommitHook() {
+  return `#!/bin/bash
+# CAWS Post-commit Hook
+# Updates provenance tracking after successful commits
+
+# Run in background to avoid blocking git operations
+(
+  # Check if CAWS is initialized
+  if [ ! -d ".caws" ]; then
+    exit 0
+  fi
+
+  # Get the current commit hash
+  COMMIT_HASH=$(git rev-parse HEAD)
+
+  # Get commit details
+  COMMIT_MESSAGE=$(git log -1 --pretty=%B | head -1)
+  AUTHOR_NAME=$(git log -1 --pretty=%an)
+  AUTHOR_EMAIL=$(git log -1 --pretty=%ae)
+
+  # Update provenance if CAWS CLI is available
+  if command -v caws >/dev/null 2>&1; then
+    echo "📜 Updating CAWS provenance for commit \${COMMIT_HASH:0:8}..."
+
+    # Run provenance update in background
+    (
+      caws provenance update \\
+        --commit "$COMMIT_HASH" \\
+        --message "$COMMIT_MESSAGE" \\
+        --author "$AUTHOR_NAME <$AUTHOR_EMAIL>" \\
+        --quiet
+    ) &
+  fi
+) >/dev/null 2>&1 &
+`;
+}
+
+/**
+ * Generate pre-push hook content
+ */
+function generatePrePushHook() {
+  return `#!/bin/bash
+# CAWS Pre-push Hook
+# Runs comprehensive checks before pushing
+
+set -e
+
+echo "🚀 CAWS Pre-push Validation"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Check if CAWS is initialized
+if [ ! -d ".caws" ]; then
+  echo "⚠️  CAWS not initialized - skipping validation"
+  exit 0
+fi
+
+# Run full validation suite
+if command -v caws >/dev/null 2>&1; then
+  echo "📋 Running comprehensive CAWS validation..."
+  if caws validate --quiet; then
+    echo "✅ CAWS validation passed"
+  else
+    echo "❌ CAWS validation failed"
+    echo "💡 Fix issues or use: git push --no-verify"
+    exit 1
+  fi
+fi
+
+# Run security checks
+echo "🔒 Running security checks..."
+if [ -f "package.json" ]; then
+  # Check for vulnerabilities
+  if command -v npm >/dev/null 2>&1; then
+    echo "🔍 Checking for vulnerabilities..."
+    if npm audit --audit-level moderate >/dev/null 2>&1; then
+      echo "✅ Security audit passed"
+    else
+      echo "⚠️  Security vulnerabilities found"
+      echo "💡 Review with: npm audit"
+      echo "💡 Use --no-verify to push anyway"
+      # Don't fail on warnings, just warn
+    fi
+  fi
+fi
+
+echo "🎉 Pre-push checks completed!"
+`;
+}
+
+/**
+ * Generate commit-msg hook content
+ */
+function generateCommitMsgHook() {
+  return `#!/bin/bash
+# CAWS Commit Message Hook
+# Validates commit message format
+
+COMMIT_MSG_FILE=$1
+
+# Read the commit message
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Check if CAWS is initialized
+if [ ! -d ".caws" ]; then
+  exit 0
+fi
+
+# Basic commit message validation
+if [ \${#COMMIT_MSG} -lt 10 ]; then
+  echo "❌ Commit message too short (minimum 10 characters)"
+  echo "💡 Write descriptive commit messages"
+  exit 1
+fi
+
+# Check for conventional commit format (optional but encouraged)
+if [[ $COMMIT_MSG =~ ^(feat|fix|docs|style|refactor|test|chore)(.+)? ]]; then
+  echo "✅ Conventional commit format detected"
+else
+  echo "💡 Consider using conventional commit format:"
+  echo "   feat: add new feature"
+  echo "   fix: bug fix"
+  echo "   docs: documentation"
+  echo "   style: formatting"
+  echo "   refactor: code restructuring"
+  echo "   test: testing"
+  echo "   chore: maintenance"
+fi
+
+echo "✅ Commit message validation passed"
+`;
+}
+
+/**
+ * Remove CAWS git hooks
+ * @param {string} projectDir - Project directory path
+ */
+async function removeGitHooks(projectDir) {
+  console.log('🧹 Removing CAWS Git hooks...');
+
+  const hooksDir = path.join(projectDir, '.git', 'hooks');
+  const cawsHooks = ['pre-commit', 'post-commit', 'pre-push', 'commit-msg'];
+
+  let removedCount = 0;
+
+  for (const hookName of cawsHooks) {
+    const hookPath = path.join(hooksDir, hookName);
+
+    try {
+      if (await fs.pathExists(hookPath)) {
+        const content = await fs.readFile(hookPath, 'utf8');
+        if (content.includes('# CAWS Hook') || content.includes('# CAWS Pre-commit Hook')) {
+          await fs.remove(hookPath);
+          console.log(`✅ Removed ${hookName} hook`);
+          removedCount++;
+        } else {
+          console.log(`⏭️  Skipped ${hookName} (not CAWS-managed)`);
+        }
+      }
+    } catch (error) {
+      console.log(`❌ Failed to remove ${hookName}: ${error.message}`);
+    }
+  }
+
+  if (removedCount > 0) {
+    console.log(`🧹 Removed ${removedCount} CAWS git hooks`);
+  } else {
+    console.log('ℹ️  No CAWS git hooks found');
+  }
+}
+
+/**
+ * Check git hooks status
+ * @param {string} projectDir - Project directory path
+ */
+async function checkGitHooksStatus(projectDir) {
+  const hooksDir = path.join(projectDir, '.git', 'hooks');
+  const cawsHooks = ['pre-commit', 'post-commit', 'pre-push', 'commit-msg'];
+
+  console.log('🔍 Git Hooks Status:');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  let activeCount = 0;
+  let totalCount = 0;
+
+  for (const hookName of cawsHooks) {
+    totalCount++;
+    const hookPath = path.join(hooksDir, hookName);
+
+    try {
+      if (await fs.pathExists(hookPath)) {
+        const content = await fs.readFile(hookPath, 'utf8');
+        const isExecutable = (await fs.stat(hookPath)).mode & 0o111;
+
+        if (content.includes('# CAWS') && isExecutable) {
+          console.log(`✅ ${hookName}: Active`);
+          activeCount++;
+        } else if (content.includes('# CAWS')) {
+          console.log(`⚠️  ${hookName}: Configured but not executable`);
+        } else {
+          console.log(`❌ ${hookName}: Not CAWS-managed`);
+        }
+      } else {
+        console.log(`❌ ${hookName}: Not installed`);
+      }
+    } catch (error) {
+      console.log(`❌ ${hookName}: Error checking status`);
+    }
+  }
+
+  console.log('');
+  console.log(`📊 Status: ${activeCount}/${totalCount} CAWS hooks active`);
+
+  if (activeCount < totalCount) {
+    console.log('');
+    console.log('💡 To install missing hooks:');
+    console.log('   caws scaffold');
+    console.log('');
+    console.log('💡 To check detailed status:');
+    console.log('   ls -la .git/hooks/');
+  }
+}
+
+module.exports = {
+  scaffoldGitHooks,
+  removeGitHooks,
+  checkGitHooksStatus,
+};

package/dist/scaffold/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Scaffold existing project with CAWS components
+ * @param {Object} options - Scaffold options
+ */
+export function scaffoldProject(options: any): Promise<void>;
+/**
+ * Scaffold IDE integrations for comprehensive CAWS development experience
+ * @param {string} targetDir - Target directory for scaffolding
+ * @param {Object} options - Scaffold options
+ */
+export function scaffoldIDEIntegrations(targetDir: string, 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":"AAkKA;;;GAGG;AACH,6DAyTC;AA5cD;;;;GAIG;AACH,mDAHW,MAAM;;;GA8HhB;AAMD;;;GAGG;AACH,yDAGC"}