@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/utils/finalization.js

@@ -1,230 +0,0 @@
-/**
- * @fileoverview Project Finalization Utilities
- * Functions for finalizing CAWS project setup
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-
-// CLI version from package.json
-const CLI_VERSION = require('../../package.json').version;
-
-// Import scaffold utilities
-const { scaffoldCursorHooks } = require('../scaffold/cursor-hooks');
-
-// Dependencies injected via setFinalizationDependencies()
-let languageSupport = null;
-let loadProvenanceTools = null;
-
-/**
- * Set dependencies for finalization utilities
- * @param {Object} deps - Dependencies object
- */
-function setFinalizationDependencies(deps) {
-  languageSupport = deps.languageSupport;
-  loadProvenanceTools = deps.loadProvenanceTools;
-}
-
-/**
- * Generate provenance manifest and git initialization (for both modes)
- * @param {string} projectName - Project name
- * @param {Object} options - Command options
- * @param {Object} answers - User answers
- */
-async function finalizeProject(projectName, options, answers) {
-  try {
-    // Detect and configure language support
-    if (languageSupport) {
-      console.log(chalk.cyan('Detecting project language...'));
-      const detectedLanguage = languageSupport.detectProjectLanguage();
-
-      if (detectedLanguage !== 'unknown') {
-        console.log(chalk.green(`Detected language: ${detectedLanguage}`));
-
-        // Generate language-specific configuration
-        try {
-          const langConfig = languageSupport.generateLanguageConfig(
-            detectedLanguage,
-            '.caws/language-config.json'
-          );
-
-          console.log(chalk.green('Generated language-specific configuration'));
-          console.log(`   Language: ${langConfig.name}`);
-          console.log(`   Tier: ${langConfig.tier}`);
-          console.log(
-            `   Thresholds: Branch ≥${langConfig.thresholds.min_branch * 100}%, Mutation ≥${langConfig.thresholds.min_mutation * 100}%`
-          );
-        } catch (langError) {
-          console.warn(chalk.yellow('Could not generate language config:'), langError.message);
-        }
-      } else {
-        console.log(
-          chalk.blue('Could not detect project language - using default configuration')
-        );
-      }
-    }
-
-    // Setup Cursor hooks if enabled
-    if (answers && answers.enableCursorHooks) {
-      console.log(chalk.cyan('Setting up Cursor hooks...'));
-      await scaffoldCursorHooks(
-        process.cwd(),
-        answers.cursorHookLevels || ['safety', 'quality', 'scope', 'audit']
-      );
-    }
-
-    // Generate provenance manifest
-    console.log(chalk.cyan('Generating provenance manifest...'));
-
-    const provenanceData = {
-      agent: 'caws-cli',
-      model: 'cli-interactive',
-      modelHash: CLI_VERSION,
-      toolAllowlist: [
-        'node',
-        'npm',
-        'git',
-        'fs-extra',
-        'inquirer',
-        'commander',
-        'js-yaml',
-        'ajv',
-        'chalk',
-      ],
-      prompts: Object.keys(answers),
-      commit: null, // Will be set after git init
-      artifacts: ['.caws/specs/', '.caws/working-spec.yaml'],
-      results: {
-        project_id: answers.projectId,
-        project_title: answers.projectTitle,
-        risk_tier: answers.riskTier,
-        mode: answers.projectMode,
-        change_budget: {
-          max_files: answers.maxFiles,
-          max_loc: answers.maxLoc,
-        },
-      },
-      approvals: [],
-    };
-
-    // Generate provenance if tools are available
-    const tools = loadProvenanceTools && loadProvenanceTools();
-    if (
-      tools &&
-      typeof tools.generateProvenance === 'function' &&
-      typeof tools.saveProvenance === 'function'
-    ) {
-      const provenance = tools.generateProvenance(provenanceData);
-      await tools.saveProvenance(provenance, '.agent/provenance.json');
-      console.log(chalk.green('Provenance manifest generated'));
-    } else {
-      console.log(
-        chalk.yellow('Provenance tools not available - skipping manifest generation')
-      );
-    }
-
-    // Initialize git repository
-    if (options.git) {
-      try {
-        console.log(chalk.cyan('Initializing git repository...'));
-
-        // Check if git is available
-        try {
-          require('child_process').execSync('git --version', { stdio: 'ignore' });
-        } catch (error) {
-          console.warn(chalk.yellow('Git not found. Skipping git initialization.'));
-          console.warn(chalk.blue('Install git to enable automatic repository setup.'));
-          return;
-        }
-
-        // Configure git author information
-        const gitConfig = answers.git_config || {};
-        const authorName = process.env.GIT_AUTHOR_NAME || gitConfig.author_name;
-        const authorEmail = process.env.GIT_AUTHOR_EMAIL || gitConfig.author_email;
-
-        if (authorName && authorEmail) {
-          require('child_process').execSync(`git config user.name "${authorName}"`, {
-            stdio: 'inherit',
-          });
-          require('child_process').execSync(`git config user.email "${authorEmail}"`, {
-            stdio: 'inherit',
-          });
-          console.log(chalk.green(`Git configured: ${authorName} <${authorEmail}>`));
-        }
-
-        require('child_process').execSync('git init', { stdio: 'inherit' });
-        require('child_process').execSync('git add .', { stdio: 'inherit' });
-        require('child_process').execSync('git commit -m "Initial CAWS project setup"', {
-          stdio: 'inherit',
-        });
-        console.log(chalk.green('Git repository initialized'));
-
-        // Update provenance with commit hash
-        const commitHash = require('child_process')
-          .execSync('git rev-parse HEAD', { encoding: 'utf8' })
-          .trim();
-        const currentProvenance = JSON.parse(fs.readFileSync('.agent/provenance.json', 'utf8'));
-        currentProvenance.commit = commitHash;
-        currentProvenance.hash = require('crypto')
-          .createHash('sha256')
-          .update(JSON.stringify(currentProvenance, Object.keys(currentProvenance).sort()))
-          .digest('hex');
-        await fs.writeFile('.agent/provenance.json', JSON.stringify(currentProvenance, null, 2));
-
-        console.log(chalk.green('Provenance updated with commit hash'));
-      } catch (error) {
-        console.warn(
-          chalk.yellow('Failed to initialize git repository:'),
-          error?.message || String(error)
-        );
-        console.warn(chalk.blue('You can initialize git manually later with:'));
-        console.warn("   git init && git add . && git commit -m 'Initial CAWS project setup'");
-      }
-    }
-  } catch (error) {
-    console.error(
-      chalk.red('Error during project finalization:'),
-      error?.message || String(error)
-    );
-  }
-}
-
-/**
- * Display success message after project initialization
- */
-function continueToSuccess() {
-  const isCurrentDir =
-    process.cwd() ===
-    path.resolve(process.argv[3] === '.' ? process.cwd() : process.argv[3] || 'caws-project');
-
-  console.log(chalk.green('\nCAWS project initialized successfully!'));
-
-  if (isCurrentDir) {
-    console.log(
-      `${chalk.cyan('Initialized in current directory')}: ${path.resolve(process.cwd())}`
-    );
-    console.log(chalk.gray('   (CAWS files added to your existing project)'));
-  } else {
-    console.log(`${chalk.cyan('Project location')}: ${path.resolve(process.cwd())}`);
-    console.log(chalk.gray('   (New subdirectory created with CAWS structure)'));
-  }
-
-  console.log(chalk.bold('\nNext steps:'));
-  console.log('1. Customize .caws/specs/<spec-id>.yaml');
-  console.log('2. Treat .caws/working-spec.yaml as a compatibility mirror');
-  console.log('3. Review added CAWS tools and documentation');
-  if (!isCurrentDir) {
-    console.log('4. Move CAWS files to your main project if needed');
-  }
-  console.log('5. npm install (if using Node.js)');
-  console.log('6. Set up your CI/CD pipeline');
-  console.log(chalk.blue('\nFor help: caws --help'));
-}
-
-module.exports = {
-  finalizeProject,
-  continueToSuccess,
-  setFinalizationDependencies,
-};

package/dist/utils/git-lock.js

@@ -1,119 +0,0 @@
-/**
- * @fileoverview Git Lock Detection Utilities
- * Functions for detecting and handling git locks
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-
-/**
- * Check for git lock files
- * @param {string} projectRoot - Project root directory
- * @returns {Object} Lock status information
- */
-function checkGitLock(projectRoot) {
-  const lockFile = path.join(projectRoot, '.git', 'index.lock');
-  const headLockFile = path.join(projectRoot, '.git', 'HEAD.lock');
-
-  const result = {
-    locked: false,
-    stale: false,
-    lockFiles: [],
-    message: null,
-    suggestion: null,
-  };
-
-  // Check index.lock
-  if (fs.existsSync(lockFile)) {
-    const lockAge = Date.now() - fs.statSync(lockFile).mtimeMs;
-    const lockAgeMinutes = Math.floor(lockAge / 60000);
-
-    result.locked = true;
-    result.lockFiles.push({
-      path: '.git/index.lock',
-      age: lockAgeMinutes,
-      stale: lockAgeMinutes > 5,
-    });
-
-    if (lockAgeMinutes > 5) {
-      // Stale lock (older than 5 minutes)
-      result.stale = true;
-      result.message = `Stale git lock detected (${lockAgeMinutes} minutes old). This may indicate a crashed git process.`;
-      result.suggestion = 'Remove stale lock: rm .git/index.lock';
-    } else {
-      // Active lock
-      result.message =
-        'Git lock detected. Another git process may be running.';
-      result.suggestion =
-        'Wait for the other process to complete, or check for running git/editor processes';
-    }
-  }
-
-  // Check HEAD.lock
-  if (fs.existsSync(headLockFile)) {
-    const lockAge = Date.now() - fs.statSync(headLockFile).mtimeMs;
-    const lockAgeMinutes = Math.floor(lockAge / 60000);
-
-    result.locked = true;
-    result.lockFiles.push({
-      path: '.git/HEAD.lock',
-      age: lockAgeMinutes,
-      stale: lockAgeMinutes > 5,
-    });
-
-    if (lockAgeMinutes > 5) {
-      result.stale = true;
-      if (!result.message) {
-        result.message = `Stale git lock detected (${lockAgeMinutes} minutes old).`;
-        result.suggestion = 'Remove stale lock: rm .git/HEAD.lock';
-      }
-    }
-  }
-
-  return result;
-}
-
-/**
- * Format git lock error message
- * @param {Object} lockStatus - Lock status from checkGitLock
- * @returns {string} Formatted error message
- */
-function formatGitLockError(lockStatus) {
-  if (!lockStatus.locked) {
-    return null;
-  }
-
-  let message = 'Git lock detected\n';
-  message += `   ${lockStatus.message}\n`;
-
-  if (lockStatus.lockFiles.length > 0) {
-    message += '\n   Lock files:\n';
-    for (const lockFile of lockStatus.lockFiles) {
-      message += `   - ${lockFile.path} (${lockFile.age} minutes old)`;
-      if (lockFile.stale) {
-        message += ' [STALE]';
-      }
-      message += '\n';
-    }
-  }
-
-  if (lockStatus.suggestion) {
-    message += `\n   ${lockStatus.suggestion}\n`;
-  }
-
-  if (lockStatus.stale) {
-    message +=
-      '\n   Warning: Removing stale locks may cause data loss if another process is actually running.\n';
-    message += '   Check for running git/editor processes before removing locks.\n';
-  }
-
-  return message;
-}
-
-module.exports = {
-  checkGitLock,
-  formatGitLockError,
-};
-
-

package/dist/utils/gitignore-updater.js

@@ -1,158 +0,0 @@
-/**
- * @fileoverview Gitignore Updater Utility
- * Updates .gitignore to properly handle CAWS runtime files vs source files
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-
-/**
- * CAWS .gitignore entries
- *
- * Strategy: Track shared/collaborative files, ignore local-only runtime data
- *
- * TRACKED (shared with team):
- * - .caws/working-spec.yaml (main spec)
- * - .caws/specs/*.yaml (feature specs)
- * - .caws/policy.yaml (team policy)
- * - .caws/waivers/*.yaml (project-wide waivers)
- * - .caws/provenance/ (audit trails for compliance)
- * - .caws/changes/ (change tracking for team visibility)
- * - .caws/archive/ (archived changes for history)
- * - .caws/plans/*.md (implementation plans)
- *
- * IGNORED (local-only):
- * - .agent/ (agent runtime tracking, local to each developer)
- * - Temporary files (*.tmp, *.bak)
- * - Logs (caws.log, debug logs)
- * - Local overrides (caws.local.*)
- */
-const CAWS_GITIGNORE_ENTRIES = `
-# CAWS Local Runtime Data (developer-specific, should not be tracked)
-# ====================================================================
-# Note: Specs, policy, waivers, provenance, and plans ARE tracked for team collaboration
-# Only local agent tracking, generated tools, and temporary files are ignored
-
-# Agent runtime tracking (local to each developer)
-.agent/
-
-# CAWS tools (now in .caws/tools/)
-.caws/tools/
-# Legacy location (for backward compatibility)
-apps/tools/caws/
-
-# Temporary CAWS files
-**/*.caws.tmp
-**/*.working-spec.bak
-.caws/*.tmp
-.caws/*.bak
-
-# CAWS logs (local debugging)
-caws-debug.log*
-**/caws.log
-.caws/*.log
-
-# Local development overrides (developer-specific)
-caws.local.*
-.caws/local.*
-
-# CAWS working state (runtime, not committed)
-.caws/state/
-
-# CAWS Worktrees (local, should not be tracked)
-.caws/worktrees/
-.caws/worktrees.json
-
-# Session transcripts (generated by session-log hook)
-tmp/
-`;
-
-/**
- * Update .gitignore to include CAWS runtime file exclusions
- * @param {string} projectRoot - Project root directory
- * @param {Object} options - Options
- * @param {boolean} options.force - Force update even if entries exist
- * @returns {Promise<boolean>} Whether .gitignore was updated
- */
-async function updateGitignore(projectRoot, options = {}) {
-  const { force = false } = options;
-  const gitignorePath = path.join(projectRoot, '.gitignore');
-
-  try {
-    // Read existing .gitignore or create empty
-    let existingContent = '';
-    if (await fs.pathExists(gitignorePath)) {
-      existingContent = await fs.readFile(gitignorePath, 'utf8');
-    }
-
-    // Check if CAWS entries already exist (check for either old or new header)
-    const hasCawsEntries =
-      existingContent.includes('# CAWS Local Runtime Data') ||
-      existingContent.includes('# CAWS Runtime Data');
-
-    if (hasCawsEntries && !force) {
-      // Already has CAWS entries, skip
-      return false;
-    }
-
-    // If old entries exist, replace them with new ones
-    if (existingContent.includes('# CAWS Runtime Data') && force) {
-      // Remove old CAWS entries (between "# CAWS Runtime Data" and next major section)
-      const lines = existingContent.split('\n');
-      const startIndex = lines.findIndex((line) => line.includes('# CAWS Runtime Data'));
-      if (startIndex !== -1) {
-        // Find the end of CAWS section (next major section starting with #)
-        let endIndex = startIndex + 1;
-        while (
-          endIndex < lines.length &&
-          (lines[endIndex].trim() === '' ||
-            lines[endIndex].startsWith('#') ||
-            lines[endIndex].startsWith('.caws/') ||
-            lines[endIndex].startsWith('.agent/') ||
-            lines[endIndex].includes('caws') ||
-            lines[endIndex].includes('CAWS'))
-        ) {
-          endIndex++;
-        }
-        // Remove old section and insert new one
-        const before = lines.slice(0, startIndex).join('\n');
-        const after = lines.slice(endIndex).join('\n');
-        existingContent = [before, after].filter(Boolean).join('\n');
-      }
-    }
-
-    // Append CAWS entries
-    const updatedContent = existingContent.trim() + '\n' + CAWS_GITIGNORE_ENTRIES.trim() + '\n';
-
-    await fs.writeFile(gitignorePath, updatedContent, 'utf8');
-
-    return true;
-  } catch (error) {
-    console.warn(chalk.yellow(`Could not update .gitignore: ${error.message}`));
-    return false;
-  }
-}
-
-/**
- * Verify .gitignore has proper CAWS entries
- * @param {string} projectRoot - Project root directory
- * @returns {Promise<boolean>} Whether .gitignore has CAWS entries
- */
-async function verifyGitignore(projectRoot) {
-  const gitignorePath = path.join(projectRoot, '.gitignore');
-
-  if (!(await fs.pathExists(gitignorePath))) {
-    return false;
-  }
-
-  const content = await fs.readFile(gitignorePath, 'utf8');
-  return content.includes('# CAWS Local Runtime Data') || content.includes('# CAWS Runtime Data');
-}
-
-module.exports = {
-  updateGitignore,
-  verifyGitignore,
-  CAWS_GITIGNORE_ENTRIES,
-};

package/dist/utils/ide-detection.js

@@ -1,133 +0,0 @@
-/**
- * @fileoverview IDE Detection and Selection Utilities
- * Detects active IDEs from environment variables and provides
- * selection/parsing helpers for the --ide CLI flag.
- * @author @darianrosebrook
- */
-
-const chalk = require('chalk');
-
-/**
- * Registry of supported IDE integrations.
- * Each entry maps an ID to its display name, description, and detection env vars.
- */
-const IDE_REGISTRY = {
-  cursor: {
-    id: 'cursor',
-    name: 'Cursor',
-    description: 'AI-first IDE with hooks, rules, and audit logs',
-    envVars: ['CURSOR_TRACE_DIR'],
-  },
-  claude: {
-    id: 'claude',
-    name: 'Claude Code',
-    description: 'Claude Code with safety hooks and settings',
-    envVars: ['CLAUDE_PROJECT_DIR'],
-  },
-  vscode: {
-    id: 'vscode',
-    name: 'VS Code',
-    description: 'Visual Studio Code settings and debug configs',
-    envVars: ['VSCODE_PID', 'VSCODE_IPC_HOOK'],
-  },
-  intellij: {
-    id: 'intellij',
-    name: 'IntelliJ IDEA',
-    description: 'IntelliJ run configurations for CAWS',
-    envVars: ['IDEA_INITIAL_DIRECTORY'],
-  },
-  windsurf: {
-    id: 'windsurf',
-    name: 'Windsurf',
-    description: 'Windsurf workflow for CAWS-guided development',
-    envVars: ['WINDSURF_WORKSPACE'],
-  },
-  copilot: {
-    id: 'copilot',
-    name: 'GitHub Copilot',
-    description: 'GitHub Copilot CAWS integration instructions',
-    envVars: [], // No reliable env var; paired with vscode
-  },
-  junie: {
-    id: 'junie',
-    name: 'JetBrains Junie',
-    description: 'Junie AI agent guidelines for JetBrains IDEs',
-    envVars: [], // Paired with intellij
-  },
-};
-
-const ALL_IDE_IDS = Object.keys(IDE_REGISTRY);
-
-/**
- * Detect currently active IDEs from environment variables.
- * @returns {string[]} Array of detected IDE identifiers
- */
-function detectActiveIDEs() {
-  const detected = [];
-  for (const [id, config] of Object.entries(IDE_REGISTRY)) {
-    if (config.envVars.length > 0 && config.envVars.some((v) => process.env[v])) {
-      detected.push(id);
-    }
-  }
-  return detected;
-}
-
-/**
- * Get recommended IDE set based on detection and natural pairings.
- * - Cursor detected -> also recommend Claude Code
- * - VS Code detected -> also recommend Copilot
- * - Nothing detected -> default to cursor + claude (AI-first set)
- * @returns {string[]} Array of recommended IDE identifiers
- */
-function getRecommendedIDEs() {
-  const detected = detectActiveIDEs();
-
-  if (detected.length > 0) {
-    const recommended = new Set(detected);
-    if (detected.includes('cursor')) recommended.add('claude');
-    if (detected.includes('vscode')) recommended.add('copilot');
-    if (detected.includes('intellij')) recommended.add('junie');
-    return Array.from(recommended);
-  }
-
-  return ['cursor', 'claude'];
-}
-
-/**
- * Parse an IDE selection from a CLI flag value or prompt answer.
- * @param {string|string[]} input - Comma-separated string or array of IDE ids
- * @returns {string[]} Normalized, validated array of IDE identifiers
- */
-function parseIDESelection(input) {
-  if (!input) return [];
-
-  let ids;
-  if (typeof input === 'string') {
-    ids = input.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
-  } else if (Array.isArray(input)) {
-    ids = input.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
-  } else {
-    return [];
-  }
-
-  if (ids.includes('all')) return [...ALL_IDE_IDS];
-  if (ids.includes('none')) return [];
-
-  const valid = ids.filter((id) => id in IDE_REGISTRY);
-  const invalid = ids.filter((id) => !(id in IDE_REGISTRY));
-
-  if (invalid.length > 0) {
-    console.warn(chalk.yellow(`Warning: Unknown IDE identifiers: ${invalid.join(', ')}`));
-    console.warn(chalk.blue(`Valid options: ${ALL_IDE_IDS.join(', ')}, all, none`));
-  }
-
-  return valid;
-}
-
-module.exports = {
-  IDE_REGISTRY,
-  ALL_IDE_IDS,
-  detectActiveIDEs,
-  getRecommendedIDEs,
-  parseIDESelection,
-};