forge-workflow 0.0.5 → 0.0.7

package/lib/task-ownership.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * Parse a task list markdown file and validate file ownership.
+ * Within each wave, no two tasks may own the same file.
+ * Cross-wave ownership is allowed (sequential execution prevents conflicts).
+ *
+ * @param {string} content - task list markdown content
+ * @returns {{ valid: boolean, violations: Array<{wave: number, task1: number, task2: number, file: string}> }}
+ */
+function validateOwnership(content) {
+  const lines = content.split('\n');
+  const violations = [];
+
+  const wavePattern = /^## Wave (\d+)/;
+  const taskPattern = /^### Task (\d+)/;
+  const ownsPattern = /\*\*OWNS\*\*:\s*(.+)/;
+
+  let currentWave = null;
+  let currentTask = null;
+  // Map: wave number -> Map of file -> first task number that owns it
+  const waveOwnership = new Map();
+
+  for (const line of lines) {
+    const parsed = parseWaveAndTask(line, wavePattern, taskPattern, currentWave, currentTask, waveOwnership);
+    if (parsed.matched) {
+      currentWave = parsed.currentWave;
+      currentTask = parsed.currentTask;
+      continue;
+    }
+
+    if (currentWave !== null && currentTask !== null) {
+      const ownedFiles = extractOwnedFiles(line, ownsPattern);
+      if (ownedFiles) {
+        checkOwnership(ownedFiles, waveOwnership.get(currentWave), currentWave, currentTask, violations);
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * Parse a line for wave or task headers and update state accordingly.
+ * @param {string} line - Current line of markdown
+ * @param {RegExp} wavePattern - Pattern to match wave headers
+ * @param {RegExp} taskPattern - Pattern to match task headers
+ * @param {number|null} currentWave - Current wave number
+ * @param {number|null} currentTask - Current task number
+ * @param {Map} waveOwnership - Wave ownership map to initialize new waves
+ * @returns {{ matched: boolean, currentWave: number|null, currentTask: number|null }}
+ */
+function parseWaveAndTask(line, wavePattern, taskPattern, currentWave, currentTask, waveOwnership) {
+  const waveMatch = wavePattern.exec(line);
+  if (waveMatch) {
+    const wave = Number.parseInt(waveMatch[1], 10);
+    if (!waveOwnership.has(wave)) {
+      waveOwnership.set(wave, new Map());
+    }
+    return { matched: true, currentWave: wave, currentTask: null };
+  }
+
+  const taskMatch = taskPattern.exec(line);
+  if (taskMatch) {
+    return { matched: true, currentWave, currentTask: Number.parseInt(taskMatch[1], 10) };
+  }
+
+  return { matched: false, currentWave, currentTask };
+}
+
+/**
+ * Extract owned file paths from an OWNS line.
+ * @param {string} line - Current line of markdown
+ * @param {RegExp} ownsPattern - Pattern to match OWNS declarations
+ * @returns {string[]|null} Array of file paths, or null if line is not an OWNS line
+ */
+function extractOwnedFiles(line, ownsPattern) {
+  const ownsMatch = ownsPattern.exec(line);
+  if (!ownsMatch) return null;
+
+  const filesRaw = ownsMatch[1];
+  const fileMatches = filesRaw.match(/`([^`]+)`/g);
+  if (!fileMatches) return null;
+
+  return fileMatches.map((f) => f.replaceAll('`', ''));
+}
+
+/**
+ * Check for ownership violations and record them.
+ * @param {string[]} files - Files declared as owned
+ * @param {Map<string, number>} ownership - File-to-task ownership map for the current wave
+ * @param {number} currentWave - Current wave number
+ * @param {number} currentTask - Current task number
+ * @param {Array} violations - Array to push violations into
+ */
+function checkOwnership(files, ownership, currentWave, currentTask, violations) {
+  for (const file of files) {
+    if (ownership.has(file)) {
+      const firstTask = ownership.get(file);
+      if (firstTask !== currentTask) {
+        violations.push({
+          wave: currentWave,
+          task1: firstTask,
+          task2: currentTask,
+          file,
+        });
+      }
+    } else {
+      ownership.set(file, currentTask);
+    }
+  }
+}
+
+module.exports = { validateOwnership };

package/lib/ui-utils.js

@@ -0,0 +1,43 @@
+/**
+ * UI prompt and display utilities
+ * Extracted from bin/forge.js for reuse and testability
+ * @module lib/ui-utils
+ */
+
+/**
+ * Yes/No prompt helper.
+ * @param {Function} question - Async function that prompts user and returns their answer string
+ * @param {string} prompt - The prompt text to display
+ * @param {boolean} [defaultNo=true] - Whether the default answer is "no"
+ * @param {boolean} [nonInteractive=false] - If true, returns default without prompting
+ * @returns {Promise<boolean>} User's answer
+ */
+async function askYesNo(question, prompt, defaultNo = true, nonInteractive = false) {
+  // Non-interactive mode: return default without prompting
+  if (nonInteractive) {
+    const defaultValue = !defaultNo;
+    console.log(`  Non-interactive mode: ${prompt} -> ${defaultValue ? 'yes' : 'no'} (default)`);
+    return defaultValue;
+  }
+  const defaultText = defaultNo ? '[n]' : '[y]';
+  while (true) {
+    const answer = await question(`${prompt} (y/n) ${defaultText}: `);
+    const normalized = answer.trim().toLowerCase();
+
+    // Handle empty input (use default)
+    if (normalized === '') return !defaultNo;
+
+    // Accept yes variations
+    if (normalized === 'y' || normalized === 'yes') return true;
+
+    // Accept no variations
+    if (normalized === 'n' || normalized === 'no') return false;
+
+    // Invalid input - re-prompt
+    console.log('  Please enter y or n');
+  }
+}
+
+module.exports = {
+  askYesNo
+};

package/lib/validation-utils.js

@@ -0,0 +1,163 @@
+/**
+ * Input validation utilities
+ * Extracted from bin/forge.js for reuse and testability
+ * @module lib/validation-utils
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Run common security checks on input.
+ * Checks for shell injection, URL encoding attacks, and non-ASCII characters.
+ * @param {string} input - Input string to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateCommonSecurity(input) {
+  // Shell injection check - common shell metacharacters
+  if (/[;|&$`()<>\r\n]/.test(input)) {
+    return { valid: false, error: 'Invalid characters detected (shell metacharacters)' };
+  }
+
+  // URL encoding check - prevent encoded path traversal
+  if (/%2[eE]|%2[fF]|%5[cC]/.test(input)) {
+    return { valid: false, error: 'URL-encoded characters not allowed' };
+  }
+
+  // ASCII-only check - prevent unicode attacks
+  if (!/^[\x20-\x7E]+$/.test(input)) {
+    return { valid: false, error: 'Only ASCII printable characters allowed' };
+  }
+
+  return { valid: true }; // No security issues found
+}
+
+/**
+ * Validate user input against security patterns.
+ * Prevents shell injection, path traversal, and unicode attacks.
+ * @param {string} input - User input to validate
+ * @param {string} type - Input type: 'path', 'agent', 'hash', 'directory_path'
+ * @param {string} [projectRoot] - Project root path (required for 'path' type)
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateUserInput(input, type, projectRoot) {
+  // Common security checks first
+  const securityResult = validateCommonSecurity(input);
+  if (!securityResult.valid) return securityResult;
+
+  // Type-specific validation - delegated to helpers
+  switch (type) {
+    case 'path':
+      return validatePathInput(input, projectRoot);
+    case 'directory_path':
+      return validateDirectoryPathInput(input);
+    case 'agent':
+      return validateAgentInput(input);
+    case 'hash':
+      return validateHashInput(input);
+    default:
+      return { valid: true };
+  }
+}
+
+/**
+ * Validate 'path' type input - ensures path stays within project root.
+ * @param {string} input - Path to validate
+ * @param {string} projectRoot - Project root directory
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validatePathInput(input, projectRoot) {
+  const resolved = path.resolve(projectRoot, input);
+  const resolvedRoot = path.resolve(projectRoot);
+  if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {
+    return { valid: false, error: 'Path outside project root' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate 'directory_path' type input - blocks system directories.
+ * @param {string} input - Directory path to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateDirectoryPathInput(input) {
+  // Block null bytes
+  if (input.includes('\0')) {
+    return { valid: false, error: 'Null bytes not allowed in path' };
+  }
+
+  // Block absolute paths to sensitive system directories
+  const resolved = path.resolve(input);
+  const normalizedResolved = path.normalize(resolved).toLowerCase();
+
+  // Get platform-specific blocked paths
+  const blockedPaths = process.platform === 'win32'
+    ? [String.raw`c:\windows`, String.raw`c:\program files`, String.raw`c:\program files (x86)`]
+    : ['/etc', '/bin', '/sbin', '/boot', '/sys', '/proc', '/dev'];
+  const errorMsg = process.platform === 'win32'
+    ? 'Cannot target Windows system directories'
+    : 'Cannot target system directories';
+
+  if (blockedPaths.some(blocked => normalizedResolved.startsWith(blocked))) {
+    return { valid: false, error: errorMsg };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate 'agent' type input - lowercase alphanumeric with hyphens only.
+ * @param {string} input - Agent name to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateAgentInput(input) {
+  if (!/^[a-z0-9-]+$/.test(input)) {
+    return { valid: false, error: 'Agent name must be lowercase alphanumeric with hyphens' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate 'hash' type input - git commit hash (4-40 hex chars).
+ * @param {string} input - Hash to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateHashInput(input) {
+  if (!/^[0-9a-f]{4,40}$/i.test(input)) {
+    return { valid: false, error: 'Invalid commit hash format (must be 4-40 hex chars)' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Check write permission to a directory or file.
+ * @param {string} filePath - Path to check
+ * @returns {{writable: boolean, error?: string}}
+ */
+function _checkWritePermission(filePath) {
+  try {
+    const dir = fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
+    const testFile = path.join(dir, `.forge-write-test-${Date.now()}`);
+    fs.writeFileSync(testFile, 'test');
+    fs.unlinkSync(testFile);
+    return { writable: true };
+  } catch (err) {
+    if (err.code === 'EACCES' || err.code === 'EPERM') {
+      const fix = process.platform === 'win32'
+        ? 'Run Command Prompt as Administrator'
+        : 'Try: sudo npx forge setup';
+      return { writable: false, error: `No write permission to ${filePath}. ${fix}` };
+    }
+    return { writable: false, error: err.message };
+  }
+}
+
+module.exports = {
+  validateCommonSecurity,
+  validateUserInput,
+  validatePathInput,
+  validateDirectoryPathInput,
+  validateAgentInput,
+  validateHashInput,
+  _checkWritePermission
+};

package/lib/workflow/enforce-stage.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { repairWorkflowRuntimeAssets } = require('../commands/setup');
+const { checkRuntimeHealth } = require('../runtime-health');
+const { normalizeStageId } = require('./stages');
+const {
+  getAllowedTransitionsForWorkflowState,
+  normalizeOverrideRecord,
+  readWorkflowState,
+} = require('./state');
+
+const WORKFLOW_STATE_FILENAME = '.forge-state.json';
+
+function getOverrideInput(flags = {}) {
+  if (Object.hasOwn(flags, 'overrideStage')) {
+    return flags.overrideStage;
+  }
+  if (Object.hasOwn(flags, '--override-stage')) {
+    return flags['--override-stage'];
+  }
+  return null;
+}
+
+function getCliFlagValue(flagName, args = []) {
+  if (!Array.isArray(args)) {
+    return null;
+  }
+
+  const prefix = `${flagName}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === flagName) {
+      return index + 1 < args.length ? args[index + 1] : null;
+    }
+    if (typeof arg === 'string' && arg.startsWith(prefix)) {
+      return arg.slice(prefix.length);
+    }
+  }
+
+  return null;
+}
+
+function resolveOverrideInput(flags = {}, args = []) {
+  return getOverrideInput(flags) || getCliFlagValue('--override-stage', args);
+}
+
+function parseOverride(flags = {}, args = []) {
+  const input = resolveOverrideInput(flags, args);
+  if (!input) {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = typeof input === 'string' ? JSON.parse(input) : input;
+  } catch (error) {
+    throw new Error(`Invalid JSON in override-stage flag: ${error.message}`);
+  }
+  return normalizeOverrideRecord(parsed);
+}
+
+function readWorkflowStateFile(projectRoot) {
+  if (!projectRoot) {
+    return null;
+  }
+
+  const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(statePath, 'utf8');
+}
+
+function resolveWorkflowStateInput(workflowState, flags = {}, args = [], projectRoot) {
+  return workflowState
+    || flags.workflowState
+    || flags['--workflow-state']
+    || getCliFlagValue('--workflow-state', args)
+    || readWorkflowStateFile(projectRoot);
+}
+
+function readWorkflowStateInput(input) {
+  if (!input) {
+    return null;
+  }
+
+  return readWorkflowState(input);
+}
+
+function formatDiagnostics(diagnostics = []) {
+  return diagnostics
+    .map(diagnostic => `${diagnostic.code}: ${diagnostic.message}`)
+    .join('; ');
+}
+
+async function enforceStageEntry({ commandName, args = [], flags = {}, projectRoot, workflowState, health, repairRuntime } = {}) {
+  const stageId = normalizeStageId(commandName);
+  if (!stageId) {
+    return { allowed: true };
+  }
+
+  if (projectRoot) {
+    repairWorkflowRuntimeAssets(projectRoot);
+  }
+
+  let runtimeHealth = health || checkRuntimeHealth(projectRoot);
+  if (runtimeHealth.hardStop && typeof repairRuntime === 'function') {
+    const repairedHealth = await repairRuntime({
+      commandName,
+      flags,
+      projectRoot,
+      workflowState,
+      health: runtimeHealth,
+    });
+    if (repairedHealth) {
+      runtimeHealth = repairedHealth;
+    }
+  }
+  if (runtimeHealth.hardStop) {
+    throw new Error(`Stage ${stageId} blocked by runtime prerequisites: ${formatDiagnostics(runtimeHealth.diagnostics)}`);
+  }
+
+  const stateInput = resolveWorkflowStateInput(workflowState, flags, args, projectRoot);
+  const currentState = readWorkflowStateInput(stateInput);
+  if (!currentState) {
+    if (stageId === 'plan') {
+      return { allowed: true, stage: stageId, workflowState: null };
+    }
+
+    throw new Error(
+      `Stage ${stageId} requires authoritative workflow state. ` +
+      `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing.`
+    );
+  }
+
+  const currentStage = currentState.currentStage;
+  const classification = currentState.workflowDecisions?.classification;
+  if (!currentStage || !classification || stageId === currentStage) {
+    return { allowed: true, stage: stageId, workflowState: currentState };
+  }
+
+  const allowedTransitions = getAllowedTransitionsForWorkflowState(currentState);
+  if (allowedTransitions.includes(stageId)) {
+    return { allowed: true, stage: stageId, workflowState: currentState };
+  }
+
+  const override = parseOverride(flags, args);
+  if (!override) {
+    throw new Error(
+      `Stage ${stageId} is blocked from ${currentStage}. ` +
+      `Provide an explicit override payload via overrideStage or --override-stage.`
+    );
+  }
+
+  if (override.fromStage !== currentStage || override.toStage !== stageId) {
+    throw new Error(
+      `Stage override does not match workflow state. Expected ${currentStage} -> ${stageId}.`
+    );
+  }
+
+  return {
+    allowed: true,
+    stage: stageId,
+    workflowState: currentState,
+    override,
+  };
+}
+
+module.exports = {
+  enforceStageEntry,
+  getCliFlagValue,
+  parseOverride,
+  resolveWorkflowStateInput,
+  readWorkflowStateFile,
+};

package/lib/workflow/stages.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const WORKFLOW_CLASSIFICATIONS = Object.freeze([
+	'critical',
+	'standard',
+	'refactor',
+	'simple',
+	'hotfix',
+	'docs',
+]);
+
+const STAGE_IDS = Object.freeze([
+	'plan',
+	'dev',
+	'validate',
+	'ship',
+	'review',
+	'premerge',
+	'verify',
+]);
+
+const STAGE_LABELS = Object.freeze({
+	plan: 'Plan',
+	dev: 'Dev',
+	validate: 'Validate',
+	ship: 'Ship',
+	review: 'Review',
+	premerge: 'Premerge',
+	verify: 'Verify',
+});
+
+const STAGE_COMMANDS = Object.freeze({
+	plan: '/plan',
+	dev: '/dev',
+	validate: '/validate',
+	ship: '/ship',
+	review: '/review',
+	premerge: '/premerge',
+	verify: '/verify',
+});
+
+const WORKFLOW_STAGE_MATRIX = Object.freeze({
+	critical: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'premerge', 'verify']),
+	standard: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'premerge']),
+	refactor: Object.freeze(['plan', 'dev', 'validate', 'ship', 'premerge']),
+	simple: Object.freeze(['dev', 'validate', 'ship']),
+	hotfix: Object.freeze(['dev', 'validate', 'ship']),
+	// Docs-only work intentionally reuses /verify as a pre-ship content check to
+	// keep the existing lightweight docs path, even though /verify is post-merge
+	// everywhere else in the full workflow.
+	docs: Object.freeze(['verify', 'ship']),
+});
+
+const WORKFLOW_TERMINAL_STAGES = Object.freeze(Object.entries(WORKFLOW_STAGE_MATRIX).reduce((accumulator, [classification, path]) => {
+	accumulator[classification] = path.at(-1);
+	return accumulator;
+}, {}));
+
+function normalizeClassification(classification) {
+	return typeof classification === 'string' && Object.hasOwn(WORKFLOW_STAGE_MATRIX, classification)
+		? classification
+		: null;
+}
+
+function normalizeStageId(stageId) {
+	return typeof stageId === 'string' && Object.hasOwn(STAGE_LABELS, stageId)
+		? stageId
+		: null;
+}
+
+function isCanonicalStageId(stageId) {
+	return normalizeStageId(stageId) !== null;
+}
+
+function getWorkflowPath(classification) {
+	const normalized = normalizeClassification(classification);
+	return normalized ? WORKFLOW_STAGE_MATRIX[normalized] : Object.freeze([]);
+}
+
+function getStageWorkflow(stageId, classification) {
+	const normalizedStage = normalizeStageId(stageId);
+	const normalizedClassification = normalizeClassification(classification);
+
+	if (!normalizedStage || !normalizedClassification) {
+		return null;
+	}
+
+	const path = WORKFLOW_STAGE_MATRIX[normalizedClassification];
+	const order = path.indexOf(normalizedStage);
+
+	if (order === -1) {
+		return null;
+	}
+
+	const nextStages = order < path.length - 1 ? Object.freeze([path[order + 1]]) : Object.freeze([]);
+
+	return {
+		classification: normalizedClassification,
+		order: order + 1,
+		nextStages,
+		terminal: order === path.length - 1,
+	};
+}
+
+function getAllowedTransitions(stageId, classification) {
+	const workflow = getStageWorkflow(stageId, classification);
+	return workflow ? workflow.nextStages : Object.freeze([]);
+}
+
+function canTransition(fromStageId, toStageId, classification) {
+	const normalizedClassification = normalizeClassification(classification);
+	const fromStage = normalizeStageId(fromStageId);
+	const toStage = normalizeStageId(toStageId);
+
+	if (!normalizedClassification || !fromStage || !toStage) {
+		return false;
+	}
+
+	const path = WORKFLOW_STAGE_MATRIX[normalizedClassification];
+	const fromIndex = path.indexOf(fromStage);
+	if (fromIndex === -1 || fromIndex === path.length - 1) {
+		return false;
+	}
+
+	return path[fromIndex + 1] === toStage;
+}
+
+function isTerminalStage(stageId, classification) {
+	const workflow = getStageWorkflow(stageId, classification);
+	return workflow ? workflow.terminal : false;
+}
+
+function assertTransitionAllowed(fromStageId, toStageId, classification) {
+	if (canTransition(fromStageId, toStageId, classification)) {
+		return true;
+	}
+
+	const fromStage = normalizeStageId(fromStageId) || String(fromStageId);
+	const toStage = normalizeStageId(toStageId) || String(toStageId);
+	const normalizedClassification = normalizeClassification(classification) || 'unknown';
+	const allowed = getAllowedTransitions(fromStageId, classification);
+	const suffix = allowed.length > 0 ? ` Allowed next stages: ${allowed.join(', ')}.` : '';
+
+	throw new Error(`Invalid workflow transition: ${fromStage} -> ${toStage} for ${normalizedClassification} workflow.${suffix}`);
+}
+
+const STAGE_MODEL = Object.freeze(STAGE_IDS.reduce((accumulator, stageId) => {
+	const workflows = {};
+
+	for (const classification of WORKFLOW_CLASSIFICATIONS) {
+		const workflow = getStageWorkflow(stageId, classification);
+		if (!workflow) {
+			continue;
+		}
+
+		workflows[classification] = Object.freeze({
+			order: workflow.order,
+			nextStages: workflow.nextStages,
+			terminal: workflow.terminal,
+		});
+	}
+
+	accumulator[stageId] = Object.freeze({
+		id: stageId,
+		label: STAGE_LABELS[stageId],
+		command: STAGE_COMMANDS[stageId],
+		workflows: Object.freeze(workflows),
+	});
+
+	return accumulator;
+}, {}));
+
+const STAGE_TRANSITIONS = Object.freeze(STAGE_IDS.reduce((accumulator, stageId) => {
+	accumulator[stageId] = Object.freeze(
+		WORKFLOW_CLASSIFICATIONS.reduce((workflowMap, classification) => {
+			workflowMap[classification] = getAllowedTransitions(stageId, classification);
+			return workflowMap;
+		}, {}),
+	);
+	return accumulator;
+}, {}));
+
+module.exports = {
+	WORKFLOW_CLASSIFICATIONS,
+	STAGE_IDS,
+	STAGE_LABELS,
+	STAGE_COMMANDS,
+	WORKFLOW_STAGE_MATRIX,
+	WORKFLOW_TERMINAL_STAGES,
+	STAGE_TRANSITIONS,
+	STAGE_MODEL,
+	normalizeClassification,
+	normalizeStageId,
+	isCanonicalStageId,
+	getWorkflowPath,
+	getStageWorkflow,
+	getAllowedTransitions,
+	canTransition,
+	isTerminalStage,
+	assertTransitionAllowed,
+};