forge-workflow 0.0.5 → 0.0.7

package/lib/commands/ship.js

@@ -367,6 +367,26 @@ async function executeShip(options) {
 }
 
 module.exports = {
+	name: 'ship',
+	description: 'Create a pull request from validated feature work',
+	handler: async (args, flags = {}) => {
+		const result = await executeShip({
+			featureSlug: args[0],
+			title: args[1],
+			dryRun: Boolean(flags.dryRun || flags['--dry-run']),
+		});
+		if (!result.success) {
+			return result;
+		}
+
+		const lines = [result.message];
+		if (result.prUrl) lines.push(`PR: ${result.prUrl}`);
+
+		return {
+			...result,
+			output: lines.join('\n'),
+		};
+	},
 	extractKeyDecisions,
 	extractTestScenarios,
 	getTestCoverage,

package/lib/commands/status.js

@@ -3,6 +3,13 @@
  * Detects workflow stage (1-9) with confidence scoring
  */
 
+const { secureExecFileSync } = require('../shell-utils');
+const {
+	readWorkflowState,
+	getAllowedTransitionsForWorkflowState,
+} = require('../workflow/state');
+const { STAGE_IDS } = require('../workflow/stages');
+
 const WORKFLOW_STAGES = {
 	1: { name: 'Fresh Start', nextCommand: 'research' },
 	2: { name: 'Research', nextCommand: 'research' },
@@ -15,6 +22,16 @@ const WORKFLOW_STAGES = {
 	9: { name: 'Verification', nextCommand: 'verify' },
 };
 
+const AUTHORITATIVE_STAGE_NAMES = {
+	plan: 'Planning',
+	dev: 'Development',
+	validate: 'Validation',
+	ship: 'Shipping',
+	review: 'Review',
+	premerge: 'Premerge',
+	verify: 'Verification',
+};
+
 /**
  * Analyze branch state
  * @param {string} branch - Current branch name
@@ -302,63 +319,175 @@ function detectStage(context) {
 	};
 }
 
-/**
- * Format status output
- * @param {object} result - Detection result
- * @returns {string} Formatted output
- */
-function formatStatus(result) {
-	const lines = [];
+function parseStatusInputs(args = [], flags = {}) {
+	const statusArgs = Array.isArray(args) ? args : [];
+	const getNextValue = (flagName) => {
+		const index = statusArgs.indexOf(flagName);
+		if (index !== -1 && index + 1 < statusArgs.length) {
+			return statusArgs[index + 1];
+		}
+		return null;
+	};
+	const getInlineValue = (flagName) => {
+		const prefix = `${flagName}=`;
+		const match = statusArgs.find(arg => typeof arg === 'string' && arg.startsWith(prefix));
+		return match ? match.slice(prefix.length) : null;
+	};
 
-	// Header
-	lines.push('');
-	lines.push(`✓ Current Stage: ${result.stage} - ${result.stageName}`);
-	lines.push(`  Confidence: ${result.confidence.toUpperCase()} (${result.confidenceScore}%)`);
-	lines.push('');
+	return {
+		issueId: flags.issueId || flags['--issue-id'] || getInlineValue('--issue-id') || getNextValue('--issue-id'),
+		workflowState: flags.workflowState || flags['--workflow-state'] || getInlineValue('--workflow-state') || getNextValue('--workflow-state'),
+		bdComments: flags.bdComments || flags['--bd-comments'] || getInlineValue('--bd-comments') || getNextValue('--bd-comments'),
+	};
+}
 
-	// Completed checks
-	const completed = [];
-	if (result.factors.files.hasResearch) {
-		completed.push('✓ Research doc exists');
-	}
-	if (result.factors.files.hasPlan) {
-		completed.push('✓ Plan created');
-	}
-	if (result.factors.branch.onFeatureBranch) {
-		completed.push('✓ Feature branch created');
+function extractWorkflowStateFromComments(comments = '') {
+	const matches = String(comments).match(/^WorkflowState:\s*(\{.*\})$/gm);
+	if (!matches || matches.length === 0) {
+		return null;
 	}
-	if (result.factors.files.hasTests) {
-		completed.push('✓ Tests written');
+
+	const latest = matches.at(-1).replace(/^WorkflowState:\s*/, '');
+	return readWorkflowState(latest);
+}
+
+function readWorkflowStateFromBeads(issueId, options = {}) {
+	if (!issueId) {
+		return null;
 	}
-	if (result.factors.files.testsPass) {
-		completed.push('✓ Tests passing');
+
+	const comments = options.comments || secureExecFileSync('bd', ['comments', 'list', issueId], {
+		encoding: 'utf8',
+		stdio: ['pipe', 'pipe', 'pipe'],
+	}).trim();
+
+	if (!comments) {
+		return null;
 	}
-	if (result.factors.checks.allChecksPass) {
-		completed.push('✓ All checks passing');
+
+	return extractWorkflowStateFromComments(comments);
+}
+
+function resolveWorkflowState(inputs) {
+	try {
+		const workflowState = inputs.workflowState
+			? readWorkflowState(inputs.workflowState)
+			: readWorkflowStateFromBeads(inputs.issueId, { comments: inputs.bdComments });
+		return { workflowState, fallbackReason: null };
+	} catch (error) {
+		return {
+			workflowState: null,
+			fallbackReason: error instanceof Error ? error.message : String(error),
+		};
 	}
-	if (result.factors.pr.hasPR) {
-		completed.push(`✓ PR created (#${result.factors.pr.prNumber})`);
+}
+
+function buildAuthoritativeStatus(workflowState) {
+	const currentStage = workflowState.currentStage;
+	const stageIndex = STAGE_IDS.indexOf(currentStage);
+	const nextStages = getAllowedTransitionsForWorkflowState(workflowState);
+
+	return {
+		stage: stageIndex === -1 ? null : stageIndex + 1,
+		stageId: currentStage,
+		stageName: AUTHORITATIVE_STAGE_NAMES[currentStage] || currentStage,
+		confidence: 'high',
+		confidenceScore: 100,
+		runCommand: currentStage,
+		nextCommand: nextStages[0] || null,
+		nextStages,
+		authoritative: true,
+		workflowState,
+		factors: {
+			files: {
+				hasResearch: workflowState.completedStages.includes('plan'),
+				hasPlan: workflowState.completedStages.includes('plan') || currentStage !== 'plan',
+				testsPass: workflowState.completedStages.includes('validate'),
+			},
+			branch: {},
+			pr: {},
+			checks: { allChecksPass: workflowState.completedStages.includes('validate') },
+			beads: { hasActiveIssue: true },
+		},
+	};
+}
+
+function buildMissingWorkflowStateStatus() {
+	return {
+		stage: null,
+		stageId: null,
+		stageName: 'Unknown',
+		confidence: 'low',
+		confidenceScore: 0,
+		authoritative: false,
+		missingWorkflowState: true,
+		output: '\nNo authoritative workflow state available.\nProvide --workflow-state or --issue-id so /status can read recorded stage state.\n',
+	};
+}
+
+function buildHeaderLines(title, detailLines = []) {
+	return ['', title, ...detailLines, ''];
+}
+
+function buildSectionLines(title, items = []) {
+	if (items.length === 0) {
+		return [];
 	}
-	if (result.factors.pr.prApproved) {
-		completed.push('✓ PR approved');
+
+	return [title, ...items.map(item => `  ${item}`), ''];
+}
+
+function collectCompletedChecks(result) {
+	const completed = [];
+
+	if (result.factors.files.hasResearch) completed.push('Research doc exists');
+	if (result.factors.files.hasPlan) completed.push('Plan created');
+	if (result.factors.branch.onFeatureBranch) completed.push('Feature branch created');
+	if (result.factors.files.hasTests) completed.push('Tests written');
+	if (result.factors.files.testsPass) completed.push('Tests passing');
+	if (result.factors.checks.allChecksPass) completed.push('All checks passing');
+	if (result.factors.pr.hasPR) completed.push(`PR created (#${result.factors.pr.prNumber})`);
+	if (result.factors.pr.prApproved) completed.push('PR approved');
+	if (result.factors.pr.prMerged) completed.push('PR merged');
+
+	return completed;
+}
+
+function formatAuthoritativeStatus(result) {
+	const completedStages = result.workflowState.completedStages.map(stageId => stageId);
+	const allowedCommands = result.nextStages.map(stageId => '/' + stageId).join(', ');
+	const nextLines = [`Run now: /${result.runCommand}`];
+
+	if (result.nextCommand) {
+		nextLines.push(`Next after this: /${result.nextCommand}`);
 	}
-	if (result.factors.pr.prMerged) {
-		completed.push('✓ PR merged');
+	if (allowedCommands) {
+		nextLines.push(`Allowed after this: ${allowedCommands}`);
 	}
 
-	if (completed.length > 0) {
-		lines.push('Completed:');
-		completed.forEach(item => lines.push(`  ${item}`));
-		lines.push('');
-	}
+	return [
+		...buildHeaderLines(`Current Stage: ${result.stageId} - ${result.stageName}`, [
+			'  Source: authoritative workflow state',
+			`  Classification: ${result.workflowState.workflowDecisions.classification}`,
+		]),
+		...buildSectionLines('Completed stages:', completedStages),
+		...nextLines,
+		'',
+	].join('\n');
+}
 
-	// Next command
-	lines.push(`Next: /${result.nextCommand}`);
-	lines.push('');
+function formatHeuristicStatus(result) {
+	const lines = [
+		...buildHeaderLines(`Current Stage: ${result.stage} - ${result.stageName}`, [
+			`  Confidence: ${result.confidence.toUpperCase()} (${result.confidenceScore}%)`,
+		]),
+		...buildSectionLines('Completed:', collectCompletedChecks(result)),
+		`Next: /${result.nextCommand}`,
+		'',
+	];
 
-	// Low confidence warning
 	if (result.confidence === 'low') {
-		lines.push('⚠️  Low confidence - Manual verification suggested');
+		lines.push('Low confidence - Manual verification suggested');
 		lines.push('   Conflicting signals detected. Please verify current stage.');
 		lines.push('');
 	}
@@ -366,7 +495,44 @@ function formatStatus(result) {
 	return lines.join('\n');
 }
 
+/**
+ * Format status output
+ * @param {object} result - Detection result
+ * @returns {string} Formatted output
+ */
+function formatStatus(result) {
+	if (result.authoritative && result.workflowState) {
+		return formatAuthoritativeStatus(result);
+	}
+
+	return formatHeuristicStatus(result);
+}
+
+
 module.exports = {
+	name: 'status',
+	description: 'Intelligent stage detection with confidence scoring',
+	handler: async (args, flags, _projectRoot) => {
+		const inputs = parseStatusInputs(args, flags);
+		const { workflowState, fallbackReason } = resolveWorkflowState(inputs);
+
+		if (workflowState) {
+			const result = buildAuthoritativeStatus(workflowState);
+			return { success: true, output: formatStatus(result), ...result };
+		}
+
+		return {
+			success: true,
+			...buildMissingWorkflowStateStatus(),
+			...(fallbackReason ? { fallbackReason } : {}),
+		};
+	},
+	buildAuthoritativeStatus,
+	buildMissingWorkflowStateStatus,
+	extractWorkflowStateFromComments,
+	resolveWorkflowState,
+	parseStatusInputs,
+	readWorkflowStateFromBeads,
 	detectStage,
 	analyzeBranch,
 	analyzeFiles,

package/lib/commands/sync.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+function isRecoverableBeadsSyncError(error) {
+  const message = error?.message ?? String(error ?? '');
+  return (
+    message.includes('failed to open database') ||
+    message.includes('database not found') ||
+    message.includes('no beads configuration found')
+  );
+}
+
+/**
+ * Forge Sync Command
+ * Syncs Beads issue data by running dolt pull + push.
+ * Uses execFileSync (not execSync) to prevent command injection (OWASP A03).
+ *
+ * @module commands/sync
+ */
+module.exports = {
+  name: 'sync',
+  description: 'Sync Beads issue data (dolt pull + push)',
+  usage: 'forge sync',
+  flags: {},
+
+  /**
+   * Run beads dolt pull + push to sync issue data.
+   * @param {string[]} _args - Positional arguments (unused)
+   * @param {object} _flags - CLI flags (unused)
+   * @param {string} _projectRoot - Project root path (unused)
+   * @param {object} [opts] - Options for dependency injection
+   * @param {Function} [opts._exec] - Override for execFileSync (testing)
+   * @returns {Promise<{success: boolean, synced: boolean, message?: string, error?: string}>}
+   */
+  handler: async (_args, _flags, _projectRoot, opts = {}) => {
+    const exec = opts._exec || execFileSync;
+
+    // Step 1: Check if bd binary exists
+    try {
+      exec('bd', ['--version'], { stdio: 'pipe' });
+    } catch { /* intentional: bd not installed, skip sync gracefully */ // NOSONAR S2486
+      return {
+        success: true,
+        synced: false,
+        message: 'Beads not installed — nothing to sync',
+      };
+    }
+
+    // Step 2: Run dolt pull + push
+    try {
+      exec('bd', ['dolt', 'pull'], { stdio: 'pipe' });
+      exec('bd', ['dolt', 'push'], { stdio: 'pipe' });
+    } catch (syncErr) {
+      if (isRecoverableBeadsSyncError(syncErr)) {
+        return {
+          success: true,
+          synced: false,
+          message: 'Beads is installed but not initialized for sync in this worktree — skipping sync',
+        };
+      }
+      return {
+        success: false,
+        synced: false,
+        error: syncErr.message,
+      };
+    }
+
+    return { success: true, synced: true };
+  },
+};

package/lib/commands/team.js

@@ -0,0 +1,37 @@
+const { existsSync } = require('node:fs');
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+// Resolve bash binary from fixed, known locations only (no PATH search).
+// SonarCloud S4036: PATH must not be searched for OS commands.
+function _resolveBash() {
+  if (process.platform === 'win32') {
+    // Fixed locations for Git Bash on Windows (no PATH search)
+    const candidates = [
+      'C:\\Program Files\\Git\\bin\\bash.exe',
+      'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+      `${process.env.LOCALAPPDATA || ''}\\Programs\\Git\\bin\\bash.exe`,
+    ];
+    for (const p of candidates) {
+      if (p && existsSync(p)) return p;
+    }
+    // Fallback: assume Git Bash is in PATH (less secure but functional)
+    return 'bash';
+  }
+  return '/usr/bin/bash';
+}
+
+function handleTeam(args) {
+  const scriptPath = path.join(__dirname, '..', '..', 'scripts', 'forge-team', 'index.sh');
+  const bashPath = _resolveBash();
+
+  try {
+    execFileSync(bashPath, [scriptPath, ...args], {
+      stdio: 'inherit',
+    });
+  } catch (err) {
+    process.exit(err.status || 1);
+  }
+}
+
+module.exports = { handleTeam };

package/lib/commands/test.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * Test Command — Smart Test Runner
+ *
+ * Wraps test execution with smart defaults:
+ * - Auto-detects package manager from lockfiles
+ * - Checks Beads (Dolt) connectivity, sets BEADS_SKIP_TESTS if unavailable
+ * - Supports --affected flag to run only tests for changed files
+ *
+ * Security: Uses execFileSync for subprocess calls (OWASP A03)
+ *
+ * @module commands/test
+ */
+
+const { execFileSync: defaultExecFileSync, spawnSync: defaultSpawnSync } = require('node:child_process');
+const defaultFs = require('node:fs');
+const path = require('node:path');
+
+/** @type {Array<[string, string]>} Lockfile → package manager mapping (order matters) */
+const LOCKFILE_MAP = [
+	['bun.lockb', 'bun'],
+	['pnpm-lock.yaml', 'pnpm'],
+	['yarn.lock', 'yarn'],
+	['package-lock.json', 'npm'],
+];
+
+const DEFAULT_TIMEOUT = 120000;
+const BEADS_CHECK_TIMEOUT = 3000;
+
+/**
+ * Detect the package manager by checking which lockfile exists.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} fs - Injected fs module
+ * @returns {string} Package manager command ('bun' | 'pnpm' | 'yarn' | 'npm')
+ */
+function detectPackageManager(projectRoot, fs) {
+	for (const [lockfile, manager] of LOCKFILE_MAP) {
+		if (fs.existsSync(path.join(projectRoot, lockfile))) {
+			return manager;
+		}
+	}
+	return 'npm';
+}
+
+/**
+ * Check if Beads (bd CLI) is reachable.
+ *
+ * @param {Function} execFileSync - Injected execFileSync
+ * @returns {boolean} true if bd is available
+ */
+function checkBeadsConnectivity(execFileSync) {
+	try {
+		execFileSync('bd', ['list', '--limit=1'], { timeout: BEADS_CHECK_TIMEOUT });
+		return true;
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: bd not installed or unreachable */
+		return false;
+	}
+}
+
+/**
+ * Get changed files relative to main branch, mapped to test file paths.
+ *
+ * Falls back to `git diff --name-only HEAD` if merge-base fails.
+ *
+ * @param {string} _projectRoot - Project root (unused, git uses cwd)
+ * @param {Function} execFileSync - Injected execFileSync
+ * @returns {string[]} Array of test file paths (e.g. ['test/foo.test.js'])
+ */
+function getAffectedTestFiles(_projectRoot, execFileSync) {
+	let diffRef;
+
+	// Detect default branch, then try merge-base
+	let baseBranch = 'main';
+	try {
+		baseBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'origin/HEAD'], {
+			encoding: 'utf8', timeout: 3000,
+		}).trim().replace('origin/', '');
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: origin/HEAD not set, detect base branch manually */
+		for (const name of ['main', 'master']) {
+			try {
+				execFileSync('git', ['rev-parse', '--verify', name], { stdio: 'pipe', timeout: 3000 });
+				baseBranch = name;
+				break;
+			} catch (_e2) { /* intentional: branch doesn't exist, try next name */ } // NOSONAR S2486
+		}
+	}
+
+	try {
+		const mergeBase = execFileSync('git', ['merge-base', 'HEAD', baseBranch], {
+			encoding: 'utf8',
+			timeout: 5000,
+		}).trim();
+		diffRef = `${mergeBase}...HEAD`;
+	} catch (_e) { /* intentional: merge-base failed, fallback to diff against HEAD */ // NOSONAR S2486
+		diffRef = 'HEAD';
+	}
+
+	let output;
+	try {
+		output = execFileSync('git', ['diff', '--name-only', diffRef], {
+			encoding: 'utf8',
+			timeout: 5000,
+		}).trim();
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: git diff failed, no affected files to report */
+		return [];
+	}
+
+	if (!output) return [];
+
+	const changedFiles = output.split('\n').filter(Boolean);
+
+	// Map lib/*.js files to test/*.test.js
+	const testFiles = [];
+	for (const file of changedFiles) {
+		if (file.startsWith('lib/') && file.endsWith('.js')) {
+			const relative = file.slice('lib/'.length);
+			const testFile = `test/${relative.replace(/\.js$/, '.test.js')}`;
+			testFiles.push(testFile);
+		}
+	}
+
+	return testFiles;
+}
+
+module.exports = {
+	name: 'test',
+	description: 'Run tests with smart defaults (timeout, Beads skip, affected-only)',
+	usage: 'forge test [--affected]',
+	flags: {
+		'--affected': 'Run only tests for changed files',
+	},
+
+	/**
+	 * Run tests with smart defaults.
+	 *
+	 * @param {string[]} _args - Positional arguments (unused)
+	 * @param {Object} flags - Parsed flags ({ affected?: boolean })
+	 * @param {string} projectRoot - Absolute path to project root
+	 * @param {Object} [deps] - Dependency injection for testability
+	 * @param {Object} [deps.fs] - fs module
+	 * @param {Function} [deps.execFileSync] - child_process.execFileSync
+	 * @param {Function} [deps.spawnSync] - child_process.spawnSync
+	 * @returns {Promise<{ success: boolean, exitCode: number, beadsSkipped: boolean }>}
+	 */
+	async handler(_args, flags, projectRoot, deps = {}) {
+		const fs = deps.fs || defaultFs;
+		const execFileSync = deps.execFileSync || defaultExecFileSync;
+		const spawnSync = deps.spawnSync || defaultSpawnSync;
+
+		// 1. Detect package manager
+		const pkgManager = detectPackageManager(projectRoot, fs);
+
+		// 2. Read timeout from package.json or use default
+		let timeout = DEFAULT_TIMEOUT;
+		try {
+			const pkgPath = path.join(projectRoot, 'package.json');
+			const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+			const testScript = pkg.scripts?.test || '';
+			const timeoutMatch = testScript.match(/--timeout\s+(\d+)/);
+			if (timeoutMatch) {
+				timeout = Number.parseInt(timeoutMatch[1], 10);
+			}
+		} catch (_e) { /* intentional: package.json missing or unreadable, use default timeout */ } // NOSONAR S2486
+
+		// 3. Check Beads connectivity
+		const beadsAvailable = checkBeadsConnectivity(execFileSync);
+		const beadsSkipped = !beadsAvailable;
+
+		const extraEnv = {};
+		if (beadsSkipped) {
+			extraEnv.BEADS_SKIP_TESTS = '1';
+		}
+
+		// 4. Build test command args
+		let testArgs = ['run', 'test'];
+
+		// 5. --affected flag: find changed test files
+		if (flags['--affected'] || flags.affected) {
+			const affectedTests = getAffectedTestFiles(projectRoot, execFileSync);
+			if (affectedTests.length > 0) {
+				testArgs = ['run', 'test', ...affectedTests];
+			}
+			// If no affected tests found, fall back to running all tests
+		}
+
+		// 6. Run tests
+		const result = spawnSync(pkgManager, testArgs, {
+			env: { ...process.env, ...extraEnv },
+			timeout,
+			stdio: 'inherit',
+			shell: process.platform === 'win32',
+		});
+
+		const exitCode = result.status ?? 1;
+
+		return {
+			success: exitCode === 0,
+			exitCode,
+			beadsSkipped,
+		};
+	},
+};

package/lib/commands/validate.js

@@ -593,6 +593,19 @@ function executeDebugMode({ fixAttempts = 0, claim } = {}) {
 }
 
 module.exports = {
+	name: 'validate',
+	description: 'Run validation checks across type, lint, security, and tests',
+	handler: async () => {
+		const result = await executeValidate();
+		if (!result.success) {
+			return result;
+		}
+
+		return {
+			...result,
+			output: result.summary,
+		};
+	},
 	runTypeCheck,
 	runLint,
 	runSecurityScan,