@paths.design/caws-cli 8.2.3 → 9.0.0

package/dist/commands/parallel.js

@@ -0,0 +1,238 @@
+/**
+ * @fileoverview CAWS Parallel CLI Command
+ * Orchestrates parallel multi-agent workspaces
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const {
+  loadPlan,
+  setupParallel,
+  getParallelStatus,
+  mergeParallel,
+  teardownParallel,
+} = require('../parallel/parallel-manager');
+
+/**
+ * Handle parallel subcommands
+ * @param {string} subcommand - Subcommand name
+ * @param {Object} options - Command options
+ */
+async function parallelCommand(subcommand, options = {}) {
+  try {
+    switch (subcommand) {
+      case 'setup':
+        return handleSetup(options);
+      case 'status':
+        return handleStatus();
+      case 'merge':
+        return handleMerge(options);
+      case 'teardown':
+        return handleTeardown(options);
+      default:
+        console.error(chalk.red(`Unknown parallel subcommand: ${subcommand}`));
+        console.log(chalk.blue('Available: setup, status, merge, teardown'));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`${error.message}`));
+    process.exit(1);
+  }
+}
+
+function handleSetup(options) {
+  const { planFile, baseBranch } = options;
+
+  if (!planFile) {
+    console.error(chalk.red('Plan file is required'));
+    console.log(chalk.blue('Usage: caws parallel setup <plan-file> [--base-branch <branch>]'));
+    process.exit(1);
+  }
+
+  const planPath = path.resolve(planFile);
+  console.log(chalk.cyan(`Loading plan: ${planFile}`));
+
+  const plan = loadPlan(planPath);
+
+  // Allow CLI --base-branch to override plan file
+  if (baseBranch) {
+    plan.baseBranch = baseBranch;
+  }
+
+  console.log(chalk.cyan(`Setting up ${plan.agents.length} parallel worktree(s)...`));
+  const results = setupParallel(plan);
+
+  console.log(chalk.green(`\nParallel workspace created`));
+  console.log(chalk.gray(`   Base branch: ${results[0] ? results[0].baseBranch : plan.baseBranch || 'main'}`));
+  console.log(chalk.gray(`   Strategy:    ${plan.mergeStrategy}`));
+  console.log('');
+
+  // Print table
+  console.log(
+    chalk.bold(
+      'Agent'.padEnd(20) +
+        'Branch'.padEnd(25) +
+        'Scope'
+    )
+  );
+  console.log(chalk.gray('-'.repeat(70)));
+
+  for (const entry of results) {
+    console.log(
+      entry.name.padEnd(20) +
+        chalk.cyan(entry.branch.padEnd(25)) +
+        chalk.gray(entry.scope || '(all)')
+    );
+  }
+
+  console.log('');
+  console.log(chalk.blue('Direct each agent to its worktree:'));
+  for (const entry of results) {
+    console.log(chalk.gray(`   ${entry.name}: cd ${entry.path}`));
+  }
+  console.log('');
+  console.log(chalk.blue('Monitor progress: caws parallel status'));
+}
+
+function handleStatus() {
+  const status = getParallelStatus();
+
+  if (!status) {
+    console.log(chalk.gray('No active parallel run.'));
+    console.log(chalk.blue('Start one with: caws parallel setup <plan-file>'));
+    return;
+  }
+
+  console.log(chalk.bold.cyan('CAWS Parallel Status'));
+  console.log(chalk.cyan('='.repeat(70)));
+  console.log(chalk.gray(`   Base branch: ${status.baseBranch}`));
+  console.log(chalk.gray(`   Strategy:    ${status.mergeStrategy}`));
+  console.log(chalk.gray(`   Created:     ${status.createdAt}`));
+  console.log('');
+
+  // Agent table
+  console.log(
+    chalk.bold(
+      'Agent'.padEnd(18) +
+        'Status'.padEnd(10) +
+        'Branch'.padEnd(22) +
+        'Commits'.padEnd(9) +
+        'Dirty'.padEnd(7) +
+        'Scope'
+    )
+  );
+  console.log(chalk.gray('-'.repeat(80)));
+
+  for (const agent of status.agents) {
+    const statusColor =
+      agent.status === 'active'
+        ? chalk.green
+        : agent.status === 'missing'
+        ? chalk.red
+        : chalk.yellow;
+
+    console.log(
+      agent.name.padEnd(18) +
+        statusColor(agent.status.padEnd(10)) +
+        agent.branch.padEnd(22) +
+        String(agent.commitCount).padEnd(9) +
+        (agent.dirty ? chalk.yellow('yes') : chalk.gray('no')).padEnd(7 + 10) + // +10 for chalk color codes
+        chalk.gray(agent.scope || '(all)')
+    );
+  }
+
+  // Show conflicts
+  if (status.conflicts.length > 0) {
+    console.log('');
+    console.log(chalk.yellow(`WARNING: ${status.conflicts.length} file-level conflict(s) detected:`));
+    for (const conflict of status.conflicts) {
+      console.log(chalk.yellow(`   ${conflict.file} -- modified by: ${conflict.agents.join(', ')}`));
+    }
+    console.log(chalk.blue('   These files were modified by multiple agents and may cause merge conflicts.'));
+  }
+
+  console.log('');
+}
+
+function handleMerge(options) {
+  const { strategy, dryRun, force } = options;
+
+  if (dryRun) {
+    console.log(chalk.cyan('Dry run: previewing merge...'));
+  } else {
+    console.log(chalk.cyan('Merging parallel branches back to base...'));
+  }
+
+  const result = mergeParallel({ strategy, dryRun, force });
+
+  // Show conflicts
+  if (result.conflicts.length > 0) {
+    console.log(chalk.yellow(`\n${result.conflicts.length} file-level conflict(s) detected:`));
+    for (const conflict of result.conflicts) {
+      console.log(chalk.yellow(`   ${conflict.file} -- ${conflict.agents.join(', ')}`));
+    }
+
+    if (!force && !dryRun) {
+      console.log('');
+      console.log(chalk.red('Merge aborted due to conflicts.'));
+      console.log(chalk.blue('   Review conflicts, then: caws parallel merge --force'));
+      return;
+    }
+  }
+
+  if (dryRun) {
+    console.log(chalk.green(`\nWould merge ${result.merged.length} branch(es):`));
+    for (const name of result.merged) {
+      console.log(chalk.gray(`   - ${name}`));
+    }
+    return;
+  }
+
+  if (result.merged.length > 0) {
+    console.log(chalk.green(`\nMerged ${result.merged.length} branch(es):`));
+    for (const name of result.merged) {
+      console.log(chalk.gray(`   - ${name}`));
+    }
+  }
+
+  if (result.failed.length > 0) {
+    console.log(chalk.red(`\nFailed to merge ${result.failed.length} branch(es):`));
+    for (const fail of result.failed) {
+      console.log(chalk.red(`   - ${fail.name}: ${fail.error}`));
+    }
+  }
+
+  if (result.merged.length > 0 && result.failed.length === 0) {
+    console.log('');
+    console.log(chalk.blue('Clean up with: caws parallel teardown --delete-branches'));
+  }
+}
+
+function handleTeardown(options) {
+  const { deleteBranches, force } = options;
+
+  console.log(chalk.cyan('Tearing down parallel worktrees...'));
+  const result = teardownParallel({ deleteBranches, force });
+
+  if (result.destroyed.length > 0) {
+    console.log(chalk.green(`Destroyed ${result.destroyed.length} worktree(s):`));
+    for (const name of result.destroyed) {
+      console.log(chalk.gray(`   - ${name}`));
+    }
+  }
+
+  if (result.failed.length > 0) {
+    console.log(chalk.red(`Failed to destroy ${result.failed.length} worktree(s):`));
+    for (const fail of result.failed) {
+      console.log(chalk.red(`   - ${fail.name}: ${fail.error}`));
+    }
+    console.log(chalk.blue('   Use --force to override'));
+  }
+
+  if (deleteBranches) {
+    console.log(chalk.gray('   Branches also deleted'));
+  }
+}
+
+module.exports = { parallelCommand };

package/dist/commands/specs.js

@@ -363,6 +363,16 @@ async function updateSpec(id, updates = {}) {
     return false;
   }
 
+  // Validate status if being updated
+  if (updates.status) {
+    const { SPEC_STATUSES } = require('../constants/spec-types');
+    if (!SPEC_STATUSES[updates.status]) {
+      throw new Error(
+        `Invalid status '${updates.status}'. Valid values: ${Object.keys(SPEC_STATUSES).join(', ')}`
+      );
+    }
+  }
+
   // Apply updates
   const updatedSpec = {
     ...spec,
@@ -536,6 +546,30 @@ async function deleteSpec(id) {
   return true;
 }
 
+/**
+ * Close a spec (sets status to 'closed', removing scope enforcement).
+ * @param {string} id - Spec identifier
+ * @returns {Promise<boolean>} Success status
+ */
+async function closeSpec(id) {
+  const spec = await loadSpec(id);
+  if (!spec) {
+    return false;
+  }
+
+  const currentStatus = spec.status || 'draft';
+  if (currentStatus === 'closed') {
+    console.log(chalk.yellow(`Spec '${id}' is already closed.`));
+    return true;
+  }
+  if (currentStatus === 'archived') {
+    console.log(chalk.yellow(`Spec '${id}' is archived and cannot be closed.`));
+    return false;
+  }
+
+  return await updateSpec(id, { status: 'closed' });
+}
+
 /**
  * Display specs in a formatted table
  * @param {Array} specs - Array of spec objects
@@ -554,7 +588,7 @@ function displaySpecsTable(specs) {
   console.log(chalk.gray('-'.repeat(80)));
 
   // Sort specs by type and status priority
-  const statusPriority = { active: 0, draft: 1, completed: 2, archived: 3 };
+  const statusPriority = { active: 0, draft: 1, completed: 2, closed: 3, archived: 4 };
   const sortedSpecs = specs.sort((a, b) => {
     const typeDiff = a.type.localeCompare(b.type);
     if (typeDiff !== 0) return typeDiff;
@@ -1001,6 +1035,24 @@ async function specsCommand(action, options = {}) {
           });
         }
 
+        case 'close': {
+          if (!options.id) {
+            throw new Error('Spec ID is required. Usage: caws specs close <id>');
+          }
+
+          const closed = await closeSpec(options.id);
+          if (!closed) {
+            throw new Error(`Could not close spec '${options.id}'`);
+          }
+
+          console.log(chalk.green(`Closed spec: ${options.id} -- scope restrictions removed`));
+
+          return outputResult({
+            command: 'specs close',
+            spec: options.id,
+          });
+        }
+
         case 'types': {
           console.log(chalk.bold.cyan('\nAvailable Spec Types'));
           console.log(chalk.cyan('==============================================\n'));
@@ -1019,7 +1071,7 @@ async function specsCommand(action, options = {}) {
 
         default:
           throw new Error(
-            `Unknown specs action: ${action}. Use: list, create, show, update, delete, conflicts, migrate, types`
+            `Unknown specs action: ${action}. Use: list, create, show, update, delete, close, conflicts, migrate, types`
           );
       }
     },
@@ -1037,6 +1089,7 @@ module.exports = {
   loadSpec,
   updateSpec,
   deleteSpec,
+  closeSpec,
   displaySpecsTable,
   displaySpecDetails,
   askConflictResolution,

package/dist/commands/status.js

@@ -510,9 +510,10 @@ async function displayVisualStatus(data, currentMode) {
     console.log(chalk.green(`Specs System (${specs.length} specs)`));
 
     // Show active specs first
-    const activeSpecs = specs.filter((s) => s.status === 'active');
+    const activeSpecs = specs.filter((s) => s.status === 'active' || s.status === 'in_progress');
     const draftSpecs = specs.filter((s) => s.status === 'draft');
     const completedSpecs = specs.filter((s) => s.status === 'completed');
+    const closedSpecs = specs.filter((s) => s.status === 'closed' || s.status === 'archived');
 
     if (activeSpecs.length > 0) {
       console.log(
@@ -543,10 +544,19 @@ async function displayVisualStatus(data, currentMode) {
         });
       }
     }
+    if (closedSpecs.length > 0) {
+      console.log(
+        chalk.gray(
+          `   Closed: ${closedSpecs.length} spec${closedSpecs.length > 1 ? 's' : ''}`
+        )
+      );
+    }
 
-    // Overall specs progress
+    // Overall specs progress (completed + closed both count as done)
     const totalSpecs = specs.length;
-    const completedSpecsCount = specs.filter((s) => s.status === 'completed').length;
+    const completedSpecsCount = specs.filter((s) =>
+      s.status === 'completed' || s.status === 'closed' || s.status === 'archived'
+    ).length;
     const activeSpecsCount = specs.filter((s) => s.status === 'active').length;
     const progressPercentage =
       totalSpecs > 0 ? Math.round((completedSpecsCount / totalSpecs) * 100) : 0;

package/dist/constants/spec-types.js

@@ -1,6 +1,6 @@
 /**
- * @fileoverview Spec Types Constants
- * Defines spec types and their metadata for consistent display
+ * @fileoverview Spec Types and Status Constants
+ * Defines spec types, statuses, and their metadata for consistent display
  * @author @darianrosebrook
  */
 
@@ -37,6 +37,29 @@ const SPEC_TYPES = {
   },
 };
 
+/**
+ * Spec statuses and lifecycle metadata.
+ * Terminal statuses mean the spec is done — its scope restrictions
+ * should NOT be enforced by the scope guard.
+ */
+const SPEC_STATUSES = {
+  draft: { label: 'Draft', color: chalk.yellow, terminal: false },
+  active: { label: 'Active', color: chalk.green, terminal: false },
+  in_progress: { label: 'In Progress', color: chalk.green, terminal: false },
+  completed: { label: 'Completed', color: chalk.blue, terminal: true },
+  closed: { label: 'Closed', color: chalk.gray, terminal: true },
+  archived: { label: 'Archived', color: chalk.gray, terminal: true },
+};
+
+/**
+ * Status keys that indicate a spec is done (scope no longer enforced).
+ */
+const TERMINAL_STATUSES = Object.entries(SPEC_STATUSES)
+  .filter(([, v]) => v.terminal)
+  .map(([k]) => k);
+
 module.exports = {
   SPEC_TYPES,
+  SPEC_STATUSES,
+  TERMINAL_STATUSES,
 };

package/dist/index.js

@@ -51,6 +51,7 @@ const { tutorialCommand } = require('./commands/tutorial');
 const { planCommand } = require('./commands/plan');
 const { worktreeCommand } = require('./commands/worktree');
 const { sessionCommand } = require('./commands/session');
+const { parallelCommand } = require('./commands/parallel');
 
 // Import scaffold functionality
 const { scaffoldProject, setScaffoldDependencies } = require('./scaffold');
@@ -263,7 +264,7 @@ specsCmd
 specsCmd
   .command('update <id>')
   .description('Update spec properties')
-  .option('-s, --status <status>', 'Spec status (draft, active, completed)')
+  .option('-s, --status <status>', 'Spec status (draft, active, in_progress, completed, closed, archived)')
   .option('--title <title>', 'Spec title')
   .option('--description <desc>', 'Spec description')
   .action((id, options) => specsCommand('update', { id, ...options }));
@@ -273,6 +274,11 @@ specsCmd
   .description('Delete a spec')
   .action((id) => specsCommand('delete', { id }));
 
+specsCmd
+  .command('close <id>')
+  .description('Close a completed spec (removes scope enforcement)')
+  .action((id) => specsCommand('close', { id }));
+
 specsCmd
   .command('conflicts')
   .description('Check for scope conflicts between specs')
@@ -429,6 +435,37 @@ sessionCmd
   .description('Show session briefing for hooks/startup')
   .action(() => sessionCommand('briefing'));
 
+// Parallel command group
+const parallelCmd = program
+  .command('parallel')
+  .description('Orchestrate parallel multi-agent workspaces');
+
+parallelCmd
+  .command('setup <plan-file>')
+  .description('Create worktrees and sessions from a plan file')
+  .option('--base-branch <branch>', 'Base branch for all worktrees')
+  .action((planFile, options) => parallelCommand('setup', { planFile, ...options }));
+
+parallelCmd
+  .command('status')
+  .description('Show all active parallel worktrees and sessions')
+  .action(() => parallelCommand('status'));
+
+parallelCmd
+  .command('merge')
+  .description('Merge all parallel branches back to base')
+  .option('--strategy <strategy>', 'Merge strategy: rebase, merge, or squash', 'merge')
+  .option('--dry-run', 'Preview merge without executing', false)
+  .option('--force', 'Force merge even with detected conflicts', false)
+  .action((options) => parallelCommand('merge', options));
+
+parallelCmd
+  .command('teardown')
+  .description('Destroy all parallel worktrees')
+  .option('--delete-branches', 'Also delete associated branches', false)
+  .option('--force', 'Force removal even if worktrees are dirty', false)
+  .action((options) => parallelCommand('teardown', options));
+
 // Templates command
 program
   .command('templates [subcommand]')
@@ -699,6 +736,7 @@ program.exitOverride((err) => {
       'tool',
       'worktree',
       'session',
+      'parallel',
     ];
     const similar = findSimilarCommand(commandName, validCommands);
 
@@ -792,6 +830,9 @@ if (require.main === module) {
         'hooks',
         'burnup',
         'tool',
+        'worktree',
+        'session',
+        'parallel',
       ];
       const similar = findSimilarCommand(commandName, validCommands);
 
@@ -802,7 +843,7 @@ if (require.main === module) {
       }
 
       console.error(
-        chalk.yellow('Available commands: init, validate, scaffold, provenance, hooks')
+        chalk.yellow('Available commands: init, validate, scaffold, provenance, hooks, parallel')
       );
       console.error(chalk.yellow('Try: caws --help for full command list'));
       console.error(