forge-workflow 0.0.5 → 0.0.7

package/lib/commands/_registry.js

@@ -0,0 +1,173 @@
+/**
+ * Command Registry — Auto-Discovery
+ *
+ * Scans a commands directory for .js files, validates each exports
+ * { name, description, handler }, and builds a routing Map.
+ *
+ * Follows the same fs.readdirSync() pattern as lib/plugin-manager.js.
+ *
+ * @module _registry
+ */
+
+const { existsSync, readdirSync } = require('node:fs');
+const path = require('node:path');
+const { normalizeStageId } = require('../workflow/stages');
+
+/**
+ * @typedef {Object} CommandModule
+ * @property {string} name - Command name used for routing
+ * @property {string} description - Human-readable description
+ * @property {function(Array, Object, string): Promise<*>} handler - Async command handler
+ * @property {string} [usage] - Usage string (optional)
+ * @property {Object<string, string>} [flags] - Flag descriptions (optional)
+ */
+
+/**
+ * Validate that a module exports the required command interface.
+ *
+ * @param {*} mod - The required module
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateCommand(mod) {
+  if (!mod || typeof mod !== 'object') {
+    return { valid: false, reason: 'module does not export an object' };
+  }
+  if (typeof mod.name !== 'string' || !mod.name) {
+    return { valid: false, reason: 'missing or invalid "name" export' };
+  }
+  if (typeof mod.description !== 'string' || !mod.description) {
+    return { valid: false, reason: 'missing or invalid "description" export' };
+  }
+  if (typeof mod.handler !== 'function') {
+    return { valid: false, reason: 'missing or invalid "handler" export' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Load and discover command modules from a directory.
+ *
+ * Scans `commandsDir` for `.js` files (excluding files starting with `_`),
+ * validates each module exports `{ name, description, handler }`, and builds
+ * a routing Map keyed by command name.
+ *
+ * Malformed modules are skipped with a `console.warn` — other commands
+ * continue loading. Duplicate command names warn and skip the later file.
+ *
+ * @param {string} commandsDir - Absolute path to the commands directory
+ * @returns {{ commands: Map<string, CommandModule>, getHelp: () => string }}
+ */
+function loadCommands(commandsDir) {
+  /** @type {Map<string, CommandModule>} */
+  const commands = new Map();
+
+  if (!commandsDir || !existsSync(commandsDir)) {
+    return {
+      commands,
+      getHelp: () => buildHelp(commands),
+    };
+  }
+
+  const files = readdirSync(commandsDir)
+    .filter(f => f.endsWith('.js') && !f.startsWith('_'))
+    .sort(); // deterministic order — first file wins on duplicates
+
+  for (const file of files) {
+    const filePath = path.join(commandsDir, file);
+
+    let mod;
+    try {
+      mod = require(filePath);
+    } catch (_err) {
+      console.warn(`[registry] Skipping ${file}: failed to load — ${_err.message}`);
+      continue;
+    }
+
+    const validation = validateCommand(mod);
+    if (!validation.valid) {
+      console.warn(`[registry] Skipping ${file}: ${validation.reason}`);
+      continue;
+    }
+
+    if (commands.has(mod.name)) {
+      console.warn(
+        `[registry] Skipping ${file}: duplicate command name "${mod.name}"`
+      );
+      continue;
+    }
+
+    commands.set(mod.name, mod);
+  }
+
+  return {
+    commands,
+    getHelp: () => buildHelp(commands),
+  };
+}
+
+/**
+ * Build a formatted help string from discovered commands.
+ *
+ * @param {Map<string, CommandModule>} commands
+ * @returns {string}
+ */
+function buildHelp(commands) {
+  if (commands.size === 0) {
+    return 'No commands available.';
+  }
+
+  const lines = ['Available commands:', ''];
+
+  // Find the longest name for alignment
+  let maxLen = 0;
+  for (const name of commands.keys()) {
+    if (name.length > maxLen) maxLen = name.length;
+  }
+
+  for (const [name, cmd] of commands) {
+    const padding = ' '.repeat(maxLen - name.length + 2);
+    lines.push(`  ${name}${padding}${cmd.description}`);
+  }
+
+  return lines.join('\n');
+}
+
+function isStageCommand(commandName) {
+  return normalizeStageId(commandName) !== null;
+}
+
+async function executeCommand(commands, commandName, args, flags, projectRoot, options = {}) {
+  const command = commands.get(commandName);
+  if (!command) {
+    return { success: false, error: `Unknown command: ${commandName}` };
+  }
+
+  try {
+    if (typeof options.enforceStage === 'function' && isStageCommand(commandName)) {
+      const enforcement = await options.enforceStage({
+        commandName,
+        args,
+        flags,
+        projectRoot,
+        command,
+      });
+
+      if (enforcement?.allowed === false) {
+        return {
+          success: false,
+          error: enforcement.error ?? `Stage ${commandName} is blocked.`,
+          enforcement,
+        };
+      }
+    }
+
+    return await command.handler(args, flags, projectRoot);
+  } catch (err) {
+    return {
+      success: false,
+      error: err?.message ?? `Failed to execute ${commandName}`,
+    };
+  }
+}
+
+module.exports = { loadCommands, validateCommand, executeCommand };

package/lib/commands/clean.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { stopDolt } = require('./worktree');
+
+/**
+ * Forge Clean Command
+ * Remove worktrees for merged branches, stopping Dolt servers first.
+ * Uses execFileSync (not execSync) to prevent command injection (OWASP A03).
+ *
+ * @module commands/clean
+ */
+
+/**
+ * Detect the default branch (main, master, develop, trunk).
+ * Tries origin/HEAD first, then probes common names.
+ * @param {Function} runFile - execFileSync-compatible function
+ * @returns {string} Default branch name
+ */
+function getDefaultBranch(runFile) {
+  try {
+    return runFile('git', ['rev-parse', '--abbrev-ref', 'origin/HEAD'], { stdio: 'pipe' })
+      .toString().trim().replace('origin/', '');
+  } catch (_e) { /* intentional: origin/HEAD not set, probe common names */ // NOSONAR S2486
+    for (const name of ['main', 'master', 'develop', 'trunk']) {
+      try {
+        runFile('git', ['rev-parse', '--verify', name], { stdio: 'pipe' });
+        return name;
+      } catch (_e2) { /* intentional: try next branch name */ } // NOSONAR S2486
+    }
+    return 'main';
+  }
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into a map of path -> branch.
+ * @param {string} output - Raw porcelain output
+ * @returns {Map<string, string>} Map of worktree path -> branch name
+ */
+function parseWorktreeList(output) {
+  const map = new Map();
+  const blocks = output.split('\n\n');
+  for (const block of blocks) {
+    const lines = block.trim().split('\n');
+    let wtPath = null;
+    let branch = null;
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) {
+        wtPath = line.slice('worktree '.length);
+      }
+      if (line.startsWith('branch ')) {
+        // branch refs/heads/feat/foo -> feat/foo
+        branch = line.slice('branch refs/heads/'.length);
+      }
+    }
+    if (wtPath && branch) {
+      map.set(wtPath, branch);
+    }
+  }
+  return map;
+}
+
+/**
+ * Clean a single worktree directory if its branch is merged.
+ * @param {string} dir - Directory name within .worktrees/
+ * @param {Map<string, string>} worktreeMap - Path-to-branch mapping
+ * @param {string[]} mergedBranches - List of merged branch names
+ * @param {string} worktreesDir - Absolute path to .worktrees/
+ * @param {boolean} dryRun - If true, skip actual removal
+ * @param {Function} runFile - execFileSync-compatible function
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {Promise<boolean>} True if the worktree was cleaned (or would be in dry-run)
+ */
+async function cleanWorktree(dir, worktreeMap, mergedBranches, worktreesDir, dryRun, runFile, fsApi) {
+  const wtPath = path.resolve(worktreesDir, dir);
+  const branch = worktreeMap.get(wtPath);
+
+  if (branch && mergedBranches.includes(branch)) {
+    if (!dryRun) {
+      const stopResult = stopDolt(wtPath, { _exec: runFile, _fs: fsApi });
+      if (stopResult.stopped) {
+        await new Promise(r => setTimeout(r, 500));
+      }
+      try {
+        runFile('git', ['worktree', 'remove', wtPath], { stdio: 'pipe' });
+      } catch (_removeErr) { /* intentional: worktree has uncommitted changes, skip */ // NOSONAR S2486
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Main handler for the clean command.
+ * @param {string[]} _args - Positional arguments (unused)
+ * @param {object} flags - CLI flags
+ * @param {string} projectRoot - Project root path
+ * @param {object} [opts] - Options for dependency injection
+ * @param {Function} [opts._exec] - Override for execFileSync (testing)
+ * @param {object} [opts._fs] - Override for fs module (testing)
+ * @returns {Promise<{ success: boolean, cleaned: number, active: number, dryRun: boolean }>}
+ */
+async function handler(_args, flags, projectRoot, opts = {}) {
+  const runFile = opts._exec || execFileSync;
+  const fsApi = opts._fs || fs;
+  const dryRun = !!(flags['--dry-run'] || flags.dryRun);
+
+  const worktreesDir = path.resolve(projectRoot, '.worktrees');
+
+  // If .worktrees/ doesn't exist, nothing to clean
+  if (!fsApi.existsSync(worktreesDir)) {
+    return { success: true, cleaned: 0, active: 0, dryRun };
+  }
+
+  // 1. List dirs in .worktrees/
+  const entries = fsApi.readdirSync(worktreesDir, { withFileTypes: true });
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+
+  if (dirs.length === 0) {
+    return { success: true, cleaned: 0, active: 0, dryRun };
+  }
+
+  // 2. Detect default branch, then get merged branches
+  const defaultBranch = getDefaultBranch(runFile);
+  let mergedBranches;
+  try {
+    const mergedOutput = runFile('git', ['branch', '--merged', defaultBranch], { stdio: 'pipe' });
+    mergedBranches = mergedOutput
+      .toString()
+      .split('\n')
+      .map(b => b.trim().replace(/^\*\s*/, ''))
+      .filter(b => b.length > 0);
+  } catch (_e) { /* intentional: fallback to empty list */ // NOSONAR S2486
+    mergedBranches = [];
+  }
+
+  // 3. Get worktree -> branch mapping from git
+  let worktreeMap;
+  try {
+    const listOutput = runFile('git', ['worktree', 'list', '--porcelain'], { stdio: 'pipe' });
+    worktreeMap = parseWorktreeList(listOutput.toString());
+  } catch (_e) { /* intentional: fallback to empty map */ // NOSONAR S2486
+    worktreeMap = new Map();
+  }
+
+  // 4. For each worktree dir, check if its branch is merged
+  let cleaned = 0;
+  let active = 0;
+
+  for (const dir of dirs) {
+    const wasCleaned = await cleanWorktree(dir, worktreeMap, mergedBranches, worktreesDir, dryRun, runFile, fsApi);
+    if (wasCleaned) {
+      cleaned++;
+    } else {
+      active++;
+    }
+  }
+
+  // Prune stale worktree refs to prevent bare repo state
+  if (!dryRun && cleaned > 0) {
+    try {
+      runFile('git', ['worktree', 'prune'], { stdio: 'pipe' });
+    } catch (_e) { /* intentional: prune is best-effort cleanup */ } // NOSONAR S2486
+  }
+
+  return { success: true, cleaned, active, dryRun };
+}
+
+module.exports = {
+  name: 'clean',
+  description: 'Remove worktrees for merged branches (stops Dolt servers)',
+  usage: 'forge clean [--dry-run]',
+  flags: {
+    '--dry-run': 'Show what would be cleaned without removing',
+  },
+  handler,
+};

package/lib/commands/commands-reset.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @module commands-reset
+ *
+ * Reset agent command files to match the canonical source (commands/*.md or .claude/commands/*.md).
+ * Rebuilds adapted files via sync-commands and optionally writes them.
+ *
+ * Used by `forge commands reset [--dry-run] [--all] [command-name]`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  syncCommands,
+  contentHash,
+  resolveCanonicalCommandsDir,
+  writeSyncManifest,
+} = require('../../scripts/sync-commands.js');
+
+function validateCommandName(commandName) {
+  if (commandName && !/^[a-z0-9-]+$/.test(commandName)) {
+    return [`Invalid command name: "${commandName}" - only lowercase letters, numbers, and hyphens allowed`];
+  }
+
+  return [];
+}
+
+function ensureCanonicalCommandExists(repoRoot, canonicalDir, commandName) {
+  if (!commandName) {
+    return [];
+  }
+
+  if (fs.existsSync(path.join(canonicalDir, `${commandName}.md`))) {
+    return [];
+  }
+
+  const canonicalLabel = path.relative(repoRoot, canonicalDir).replaceAll('\\', '/');
+  return [`Command not found: ${canonicalLabel}/${commandName}.md`];
+}
+
+function filterPlannedEntries(entries, commandName, all) {
+  if (commandName && all !== true) {
+    return entries.filter(entry =>
+      entry.filename.replaceAll('.prompt.md', '').replaceAll('.md', '') === commandName ||
+      entry.dir.includes(`/${commandName}/`)
+    );
+  }
+
+  return entries;
+}
+
+function recordEntryResult(entry, reset, skipped, dryRun) {
+  const relativeFile = path.join(entry.dir, entry.filename);
+
+  if (dryRun) {
+    if (fs.existsSync(entry.filePath)) {
+      const existing = fs.readFileSync(entry.filePath, 'utf8');
+      if (contentHash(existing) === contentHash(entry.content)) {
+        skipped.push({ agent: entry.agent, file: relativeFile });
+      } else {
+        reset.push({ agent: entry.agent, file: relativeFile });
+      }
+    } else {
+      reset.push({ agent: entry.agent, file: relativeFile });
+    }
+    return;
+  }
+
+  const targetDir = path.dirname(entry.filePath);
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  if (fs.existsSync(entry.filePath)) {
+    const existing = fs.readFileSync(entry.filePath, 'utf8');
+    if (contentHash(existing) === contentHash(entry.content)) {
+      skipped.push({ agent: entry.agent, file: relativeFile });
+      return;
+    }
+  }
+
+  fs.writeFileSync(entry.filePath, entry.content);
+  reset.push({ agent: entry.agent, file: relativeFile });
+}
+
+function resetCommands({ repoRoot, commandName, all, dryRun }) {
+  const errors = [];
+  const reset = [];
+  const skipped = [];
+
+  errors.push(...validateCommandName(commandName));
+  if (errors.length > 0) {
+    return { reset, skipped, errors };
+  }
+
+  const canonicalDir = resolveCanonicalCommandsDir(repoRoot);
+  if (!canonicalDir) {
+    errors.push('Canonical source directory not found: commands/ or .claude/commands/');
+    return { reset, skipped, errors };
+  }
+
+  errors.push(...ensureCanonicalCommandExists(repoRoot, canonicalDir, commandName));
+  if (errors.length > 0) {
+    return { reset, skipped, errors };
+  }
+
+  const result = syncCommands({ dryRun: true, check: false, repoRoot, canonicalDir });
+  if (!result.planned || result.planned.length === 0) {
+    return { reset, skipped, errors };
+  }
+
+  const entries = filterPlannedEntries(result.planned, commandName, all);
+  for (const entry of entries) {
+    recordEntryResult(entry, reset, skipped, dryRun);
+  }
+
+  if (!dryRun) {
+    // Refresh the manifest using the full expected sync set without rewriting
+    // unrelated command files that were intentionally excluded from this reset.
+    writeSyncManifest(repoRoot, result.planned);
+  }
+
+  return { reset, skipped, errors };
+}
+
+module.exports = {
+  name: 'commands-reset',
+  description: 'Reset generated agent command files to canonical content',
+  handler: async (args, flags, repoRoot) => {
+    const commandName = args.find(arg => !arg.startsWith('-'));
+    const result = resetCommands({
+      repoRoot,
+      commandName,
+      all: Boolean(flags.all),
+      dryRun: Boolean(flags.dryRun),
+    });
+
+    if (result.errors.length > 0) {
+      return { success: false, error: result.errors.join('; ') };
+    }
+
+    return { success: true, ...result };
+  },
+  resetCommands,
+  resolveCanonicalCommandsDir,
+};

package/lib/commands/dev.js

@@ -500,7 +500,90 @@ function calculateDecisionRoute(score, dimensions) {
 	return { route: DECISION_ROUTES.BLOCKED, score: effectiveScore };
 }
 
+/**
+ * Verify task completion and auto-commit changes if needed.
+ *
+ * Checks for uncommitted changes, stages only scoped files, commits,
+ * and returns the result. NEVER uses `git add -A` or `git add .`.
+ *
+ * Security: Uses execFileSync only (OWASP A03 — no shell injection).
+ *
+ * @param {string} taskTitle - The task title for the commit message
+ * @param {string[]|null|undefined} ownedFiles - Files this task owns (scoped staging). If falsy, stages tracked modified files only.
+ * @param {object} [opts] - Options
+ * @param {Function} [opts._exec] - Injected execFileSync for testing
+ * @returns {{committed: boolean, autoCommitted: boolean, commitSha: string|null, hasChanges: boolean}}
+ * @example
+ * const result = verifyTaskCompletion('add login form', ['lib/auth.js'], { _exec: mockExec });
+ */
+function verifyTaskCompletion(taskTitle, ownedFiles, opts = {}) {
+	const run = opts._exec || execFileSync;
+
+	// 1. Check for uncommitted changes
+	const status = run('git', ['status', '--porcelain']).toString().trim();
+
+	if (!status) {
+		return { committed: false, autoCommitted: false, commitSha: null, hasChanges: false };
+	}
+
+	// There are changes
+	let filesToStage = [];
+
+	if (ownedFiles && ownedFiles.length > 0) {
+		// 2. Stage only owned files — NEVER git add -A
+		filesToStage = ownedFiles;
+	} else {
+		// 3. Stage only tracked modified files from git diff --name-only
+		const diffOutput = run('git', ['diff', '--name-only']).toString().trim();
+		if (diffOutput) {
+			filesToStage = diffOutput.split('\n').filter(Boolean);
+		}
+	}
+
+	// If no files to stage, skip commit
+	if (filesToStage.length === 0) {
+		return { committed: false, autoCommitted: false, commitSha: null, hasChanges: true };
+	}
+
+	// Stage scoped files
+	run('git', ['add', ...filesToStage]);
+
+	// 4. Commit with standardized message
+	run('git', ['commit', '-m', `feat(task): ${taskTitle}`]);
+
+	// 5. Get commit sha
+	const commitSha = run('git', ['log', '-1', '--format=%H']).toString().trim();
+
+	return { committed: true, autoCommitted: true, commitSha, hasChanges: true };
+}
+
 module.exports = {
+	name: 'dev',
+	description: 'Run the TDD development stage with phase guidance',
+	handler: async (args, flags = {}) => {
+		const featureName = args[0] || 'feature';
+		const phaseInput = flags.phase || args[1];
+		const phase = typeof phaseInput === 'string' ? phaseInput.toUpperCase() : undefined;
+		if (phase && !['RED', 'GREEN', 'REFACTOR'].includes(phase)) {
+			return {
+				success: false,
+				error: `Invalid phase '${phaseInput}'. Valid phases: red, green, refactor`,
+			};
+		}
+
+		const result = await executeDev(featureName, phase ? { phase } : {});
+		if (!result.success) {
+			return result;
+		}
+
+		const lines = [`TDD Phase: ${result.phase || result.detectedPhase}`];
+		if (result.guidance) lines.push('', result.guidance);
+
+		return {
+			...result,
+			output: lines.join('\n'),
+		};
+	},
 	detectTDDPhase,
 	identifyFilePairs,
 	runTests,
@@ -510,4 +593,5 @@ module.exports = {
 	executeDev,
 	calculateDecisionRoute,
 	DECISION_ROUTES,
+	verifyTaskCompletion,
 };

package/lib/commands/plan.js

@@ -680,6 +680,24 @@ async function executePlan(featureName) { // NOSONAR S3776
 }
 
 module.exports = {
+	name: 'plan',
+	description: 'Create implementation plan from researched feature context',
+	handler: async (args) => {
+		const result = await executePlan(args[0]);
+		if (!result.success) {
+			return result;
+		}
+
+		const lines = [`Plan created: ${result.summary || result.branchName || args[0]}`];
+		if (result.beadsIssueId) lines.push(`Beads: ${result.beadsIssueId}`);
+		if (result.branchName) lines.push(`Branch: ${result.branchName}`);
+		if (result.nextCommand) lines.push(`Next: ${result.nextCommand}`);
+
+		return {
+			...result,
+			output: lines.join('\n'),
+		};
+	},
 	readResearchDoc,
 	detectScope,
 	createBeadsIssue,