cap-pro 1.0.0

package/cap/bin/lib/cli/arg-helpers.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * CLI argument-parsing helpers shared across cap-tools router modules.
+ *
+ * Extracted from cap/bin/cap-tools.cjs as part of the router decomposition.
+ * Behavior is byte-identical to the originals — do not refactor signatures
+ * without auditing every router that imports them.
+ */
+
+/**
+ * Extract named --flag <value> pairs from an args array.
+ * Returns an object mapping flag names to their values (null if absent).
+ * Flags listed in `booleanFlags` are treated as boolean (no value consumed).
+ *
+ * parseNamedArgs(args, 'phase', 'plan')        → { phase: '3', plan: '1' }
+ * parseNamedArgs(args, [], ['amend', 'force'])  → { amend: true, force: false }
+ */
+function parseNamedArgs(args, valueFlags = [], booleanFlags = []) {
+  const result = {};
+  for (const flag of valueFlags) {
+    const idx = args.indexOf(`--${flag}`);
+    result[flag] = idx !== -1 && args[idx + 1] !== undefined && !args[idx + 1].startsWith('--')
+      ? args[idx + 1]
+      : null;
+  }
+  for (const flag of booleanFlags) {
+    result[flag] = args.includes(`--${flag}`);
+  }
+  return result;
+}
+
+/**
+ * Collect all tokens after --flag until the next --flag or end of args.
+ * Handles multi-word values like --name Foo Bar Version 1.
+ * Returns null if the flag is absent.
+ */
+function parseMultiwordArg(args, flag) {
+  const idx = args.indexOf(`--${flag}`);
+  if (idx === -1) return null;
+  const tokens = [];
+  for (let i = idx + 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) break;
+    tokens.push(args[i]);
+  }
+  return tokens.length > 0 ? tokens.join(' ') : null;
+}
+
+module.exports = { parseNamedArgs, parseMultiwordArg };

package/cap/bin/lib/cli/frontmatter-router.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Frontmatter command router — dispatches `frontmatter <subcommand>` to
+ * lib/frontmatter.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const frontmatter = require('../frontmatter.cjs');
+const { error } = require('../core.cjs');
+const { parseNamedArgs } = require('./arg-helpers.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  const file = args[2];
+  if (subcommand === 'get') {
+    frontmatter.cmdFrontmatterGet(cwd, file, parseNamedArgs(args, ['field']).field, raw);
+  } else if (subcommand === 'set') {
+    const { field, value } = parseNamedArgs(args, ['field', 'value']);
+    frontmatter.cmdFrontmatterSet(cwd, file, field, value !== null ? value : undefined, raw);
+  } else if (subcommand === 'merge') {
+    frontmatter.cmdFrontmatterMerge(cwd, file, parseNamedArgs(args, ['data']).data, raw);
+  } else if (subcommand === 'validate') {
+    frontmatter.cmdFrontmatterValidate(cwd, file, parseNamedArgs(args, ['schema']).schema, raw);
+  } else {
+    error('Unknown frontmatter subcommand. Available: get, set, merge, validate');
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/init-router.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Init command router — dispatches `init <workflow>` to lib/init.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const init = require('../init.cjs');
+const { error } = require('../core.cjs');
+
+function dispatch(args, cwd, raw) {
+  const workflow = args[1];
+  switch (workflow) {
+    case 'execute-phase':
+      init.cmdInitExecutePhase(cwd, args[2], raw);
+      break;
+    case 'plan-phase':
+      init.cmdInitPlanPhase(cwd, args[2], raw);
+      break;
+    case 'new-project':
+      init.cmdInitNewProject(cwd, raw);
+      break;
+    case 'new-milestone':
+      init.cmdInitNewMilestone(cwd, raw);
+      break;
+    case 'quick':
+      init.cmdInitQuick(cwd, args.slice(2).join(' '), raw);
+      break;
+    case 'resume':
+      init.cmdInitResume(cwd, raw);
+      break;
+    case 'verify-work':
+      init.cmdInitVerifyWork(cwd, args[2], raw);
+      break;
+    case 'phase-op':
+      init.cmdInitPhaseOp(cwd, args[2], raw);
+      break;
+    case 'todos':
+      init.cmdInitTodos(cwd, args[2], raw);
+      break;
+    case 'milestone-op':
+      init.cmdInitMilestoneOp(cwd, raw);
+      break;
+    case 'map-codebase':
+      init.cmdInitMapCodebase(cwd, raw);
+      break;
+    case 'progress':
+      init.cmdInitProgress(cwd, raw);
+      break;
+    case 'manager':
+      init.cmdInitManager(cwd, raw);
+      break;
+    case 'new-workspace':
+      init.cmdInitNewWorkspace(cwd, raw);
+      break;
+    case 'list-workspaces':
+      init.cmdInitListWorkspaces(cwd, raw);
+      break;
+    case 'remove-workspace':
+      init.cmdInitRemoveWorkspace(cwd, args[2], raw);
+      break;
+    default:
+      error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, progress, manager, new-workspace, list-workspaces, remove-workspace`);
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/phase-router.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Phase / phases / roadmap / requirements / milestone command routers.
+ *
+ * Each command group has its own dispatch function. They are bundled in this
+ * single module because they all touch phase- or roadmap-level concepts and
+ * extracting them as separate files would proliferate tiny modules.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const phase = require('../phase.cjs');
+const roadmap = require('../roadmap.cjs');
+const milestone = require('../milestone.cjs');
+const { error } = require('../core.cjs');
+const { parseMultiwordArg } = require('./arg-helpers.cjs');
+
+function dispatchPhases(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'list') {
+    const typeIndex = args.indexOf('--type');
+    const phaseIndex = args.indexOf('--phase');
+    const options = {
+      type: typeIndex !== -1 ? args[typeIndex + 1] : null,
+      phase: phaseIndex !== -1 ? args[phaseIndex + 1] : null,
+      includeArchived: args.includes('--include-archived'),
+    };
+    phase.cmdPhasesList(cwd, options, raw);
+  } else {
+    error('Unknown phases subcommand. Available: list');
+  }
+}
+
+function dispatchPhase(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'next-decimal') {
+    phase.cmdPhaseNextDecimal(cwd, args[2], raw);
+  } else if (subcommand === 'add') {
+    let customId = null;
+    const descArgs = [];
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--id' && i + 1 < args.length) {
+        customId = args[i + 1];
+        i++; // skip value
+      } else {
+        descArgs.push(args[i]);
+      }
+    }
+    phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId);
+  } else if (subcommand === 'insert') {
+    phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
+  } else if (subcommand === 'remove') {
+    const forceFlag = args.includes('--force');
+    phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag }, raw);
+  } else if (subcommand === 'complete') {
+    phase.cmdPhaseComplete(cwd, args[2], raw);
+  } else {
+    error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+  }
+}
+
+function dispatchRoadmap(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'get-phase') {
+    roadmap.cmdRoadmapGetPhase(cwd, args[2], raw);
+  } else if (subcommand === 'analyze') {
+    roadmap.cmdRoadmapAnalyze(cwd, raw);
+  } else if (subcommand === 'update-plan-progress') {
+    roadmap.cmdRoadmapUpdatePlanProgress(cwd, args[2], raw);
+  } else {
+    error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress');
+  }
+}
+
+function dispatchRequirements(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'mark-complete') {
+    milestone.cmdRequirementsMarkComplete(cwd, args.slice(2), raw);
+  } else {
+    error('Unknown requirements subcommand. Available: mark-complete');
+  }
+}
+
+function dispatchMilestone(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'complete') {
+    const milestoneName = parseMultiwordArg(args, 'name');
+    const archivePhases = args.includes('--archive-phases');
+    milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases }, raw);
+  } else {
+    error('Unknown milestone subcommand. Available: complete');
+  }
+}
+
+module.exports = {
+  dispatchPhases,
+  dispatchPhase,
+  dispatchRoadmap,
+  dispatchRequirements,
+  dispatchMilestone,
+};

package/cap/bin/lib/cli/state-router.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * State command router — dispatches `state <subcommand>` to lib/state.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const state = require('../state.cjs');
+const { parseNamedArgs } = require('./arg-helpers.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'json') {
+    state.cmdStateJson(cwd, raw);
+  } else if (subcommand === 'update') {
+    state.cmdStateUpdate(cwd, args[2], args[3]);
+  } else if (subcommand === 'get') {
+    state.cmdStateGet(cwd, args[2], raw);
+  } else if (subcommand === 'patch') {
+    const patches = {};
+    for (let i = 2; i < args.length; i += 2) {
+      const key = args[i].replace(/^--/, '');
+      const value = args[i + 1];
+      if (key && value !== undefined) {
+        patches[key] = value;
+      }
+    }
+    state.cmdStatePatch(cwd, patches, raw);
+  } else if (subcommand === 'advance-plan') {
+    state.cmdStateAdvancePlan(cwd, raw);
+  } else if (subcommand === 'record-metric') {
+    const { phase: p, plan, duration, tasks, files } = parseNamedArgs(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+    state.cmdStateRecordMetric(cwd, { phase: p, plan, duration, tasks, files }, raw);
+  } else if (subcommand === 'update-progress') {
+    state.cmdStateUpdateProgress(cwd, raw);
+  } else if (subcommand === 'add-decision') {
+    const { phase: p, summary, 'summary-file': summary_file, rationale, 'rationale-file': rationale_file } = parseNamedArgs(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+    state.cmdStateAddDecision(cwd, { phase: p, summary, summary_file, rationale: rationale || '', rationale_file }, raw);
+  } else if (subcommand === 'add-blocker') {
+    const { text, 'text-file': text_file } = parseNamedArgs(args, ['text', 'text-file']);
+    state.cmdStateAddBlocker(cwd, { text, text_file }, raw);
+  } else if (subcommand === 'resolve-blocker') {
+    state.cmdStateResolveBlocker(cwd, parseNamedArgs(args, ['text']).text, raw);
+  } else if (subcommand === 'record-session') {
+    const { 'stopped-at': stopped_at, 'resume-file': resume_file } = parseNamedArgs(args, ['stopped-at', 'resume-file']);
+    state.cmdStateRecordSession(cwd, { stopped_at, resume_file: resume_file || 'None' }, raw);
+  } else if (subcommand === 'begin-phase') {
+    const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
+    state.cmdStateBeginPhase(cwd, p, name, plans !== null ? parseInt(plans, 10) : null, raw);
+  } else if (subcommand === 'signal-waiting') {
+    const { type, question, options, phase: p } = parseNamedArgs(args, ['type', 'question', 'options', 'phase']);
+    state.cmdSignalWaiting(cwd, type, question, options, p, raw);
+  } else if (subcommand === 'signal-resume') {
+    state.cmdSignalResume(cwd, raw);
+  } else {
+    state.cmdStateLoad(cwd, raw);
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/template-router.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * Template command router — dispatches `template <subcommand>` to lib/template.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const template = require('../template.cjs');
+const { error } = require('../core.cjs');
+const { parseNamedArgs } = require('./arg-helpers.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'select') {
+    template.cmdTemplateSelect(cwd, args[2], raw);
+  } else if (subcommand === 'fill') {
+    const templateType = args[2];
+    const { phase, plan, name, type, wave, fields: fieldsRaw } = parseNamedArgs(args, ['phase', 'plan', 'name', 'type', 'wave', 'fields']);
+    let fields = {};
+    if (fieldsRaw) {
+      const { safeJsonParse } = require('../security.cjs');
+      const result = safeJsonParse(fieldsRaw, { label: '--fields' });
+      if (!result.ok) error(result.error);
+      fields = result.value;
+    }
+    template.cmdTemplateFill(cwd, templateType, {
+      phase, plan, name, fields,
+      type: type || 'execute',
+      wave: wave || '1',
+    }, raw);
+  } else {
+    error('Unknown template subcommand. Available: select, fill');
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/uat-router.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * UAT command router — dispatches `uat <subcommand>` and the standalone
+ * `audit-uat` command to lib/uat.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const { error } = require('../core.cjs');
+const { parseNamedArgs } = require('./arg-helpers.cjs');
+
+function dispatchAuditUat(args, cwd, raw) {
+  const uat = require('../uat.cjs');
+  uat.cmdAuditUat(cwd, raw);
+}
+
+function dispatchUat(args, cwd, raw) {
+  const subcommand = args[1];
+  const uat = require('../uat.cjs');
+  if (subcommand === 'render-checkpoint') {
+    const options = parseNamedArgs(args, ['file']);
+    uat.cmdRenderCheckpoint(cwd, options, raw);
+  } else {
+    error('Unknown uat subcommand. Available: render-checkpoint');
+  }
+}
+
+module.exports = { dispatchAuditUat, dispatchUat };

package/cap/bin/lib/cli/validation-router.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Validation command router — dispatches `validate <subcommand>` to lib/verify.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const verify = require('../verify.cjs');
+const { error } = require('../core.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'consistency') {
+    verify.cmdValidateConsistency(cwd, raw);
+  } else if (subcommand === 'health') {
+    const repairFlag = args.includes('--repair');
+    verify.cmdValidateHealth(cwd, { repair: repairFlag }, raw);
+  } else if (subcommand === 'agents') {
+    verify.cmdValidateAgents(cwd, raw);
+  } else {
+    error('Unknown validate subcommand. Available: consistency, health, agents');
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/verification-router.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Verification command router — dispatches `verify <subcommand>` to lib/verify.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const verify = require('../verify.cjs');
+const { error } = require('../core.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'plan-structure') {
+    verify.cmdVerifyPlanStructure(cwd, args[2], raw);
+  } else if (subcommand === 'phase-completeness') {
+    verify.cmdVerifyPhaseCompleteness(cwd, args[2], raw);
+  } else if (subcommand === 'references') {
+    verify.cmdVerifyReferences(cwd, args[2], raw);
+  } else if (subcommand === 'commits') {
+    verify.cmdVerifyCommits(cwd, args.slice(2), raw);
+  } else if (subcommand === 'artifacts') {
+    verify.cmdVerifyArtifacts(cwd, args[2], raw);
+  } else if (subcommand === 'key-links') {
+    verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+  } else {
+    error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
+  }
+}
+
+module.exports = { dispatch };

package/cap/bin/lib/cli/workstream-router.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * Workstream command router — dispatches `workstream <subcommand>` to
+ * lib/workstream.cjs.
+ *
+ * Extracted from cap/bin/cap-tools.cjs. Behavior is byte-identical.
+ */
+
+const workstream = require('../workstream.cjs');
+const { error } = require('../core.cjs');
+
+function dispatch(args, cwd, raw) {
+  const subcommand = args[1];
+  if (subcommand === 'create') {
+    const migrateNameIdx = args.indexOf('--migrate-name');
+    const noMigrate = args.includes('--no-migrate');
+    workstream.cmdWorkstreamCreate(cwd, args[2], {
+      migrate: !noMigrate,
+      migrateName: migrateNameIdx !== -1 ? args[migrateNameIdx + 1] : null,
+    }, raw);
+  } else if (subcommand === 'list') {
+    workstream.cmdWorkstreamList(cwd, raw);
+  } else if (subcommand === 'status') {
+    workstream.cmdWorkstreamStatus(cwd, args[2], raw);
+  } else if (subcommand === 'complete') {
+    workstream.cmdWorkstreamComplete(cwd, args[2], {}, raw);
+  } else if (subcommand === 'set') {
+    workstream.cmdWorkstreamSet(cwd, args[2], raw);
+  } else if (subcommand === 'get') {
+    workstream.cmdWorkstreamGet(cwd, raw);
+  } else if (subcommand === 'progress') {
+    workstream.cmdWorkstreamProgress(cwd, raw);
+  } else {
+    error('Unknown workstream subcommand. Available: create, list, status, complete, set, get, progress');
+  }
+}
+
+module.exports = { dispatch };