forge-workflow 0.0.6 → 0.0.7

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,
+};

package/lib/workflow/state.js

@@ -0,0 +1,332 @@
+'use strict';
+
+const {
+  WORKFLOW_CLASSIFICATIONS,
+  STAGE_IDS,
+  STAGE_MODEL,
+  getWorkflowPath,
+  normalizeStageId,
+} = require('./stages.js');
+
+const WORKFLOW_STATE_SCHEMA_VERSION = 2;
+const LEGACY_STANDARD_VERIFY = Symbol('legacy-standard-verify');
+const LEGACY_STANDARD_WORKFLOW_PATH = Object.freeze([
+  'plan',
+  'dev',
+  'validate',
+  'ship',
+  'review',
+  'premerge',
+  'verify',
+]);
+const LEGACY_WORKFLOW_STATE_OPTIONS = Object.freeze({
+  allowLegacyDefaultClassification: true,
+  allowLegacyStandardVerify: true,
+  allowLegacyOverrideRecords: true,
+});
+
+function normalizeString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeBoolean(value) {
+  return value === true || value === 1 || value === '1' || value === 'true';
+}
+
+function normalizeStageList(stages) {
+  if (!Array.isArray(stages)) {
+    return [];
+  }
+
+  const normalized = [];
+  for (const stage of stages) {
+    const stageId = normalizeStageId(stage);
+    if (!stageId || normalized.includes(stageId)) {
+      continue;
+    }
+    normalized.push(stageId);
+  }
+
+  return normalized;
+}
+
+function normalizeParallelTrack(track) {
+  if (!track || typeof track !== 'object' || Array.isArray(track)) {
+    return null;
+  }
+
+  const normalized = {
+    name: normalizeString(track.name),
+    agent: normalizeString(track.agent),
+    status: normalizeString(track.status),
+  };
+
+  if (track.worktree && typeof track.worktree === 'object' && !Array.isArray(track.worktree)) {
+    normalized.worktree = {
+      path: normalizeString(track.worktree.path),
+      branch: normalizeString(track.worktree.branch),
+    };
+  }
+
+  return normalized;
+}
+
+function normalizeOverrideRecord(override = {}, options = {}) {
+  const type = normalizeString(override.type || override.kind) || 'manual';
+  const fromStage = override.fromStage == null ? null : normalizeStageId(override.fromStage);
+  const toStage = override.toStage == null ? null : normalizeStageId(override.toStage);
+  const reason = normalizeString(override.reason);
+  const actor = normalizeString(override.actor) || 'unknown';
+  const recordedAt = normalizeString(override.recordedAt || override.at || override.timestamp) || new Date().toISOString();
+
+  if (!type) {
+    throw new Error('Override record must include a type');
+  }
+
+  if (!options.allowLegacyOverrideRecords && (!fromStage || !toStage || !reason)) {
+    throw new Error('Override record must include fromStage, toStage, and a non-empty reason');
+  }
+
+  return {
+    type,
+    fromStage,
+    toStage,
+    reason,
+    actor,
+    userOverride: normalizeBoolean(override.userOverride),
+    recordedAt,
+  };
+}
+
+function normalizeWorkflowOverrides(value = {}, options = {}) {
+  const overrides = Array.isArray(value.overrides)
+    ? value.overrides.map(override => normalizeOverrideRecord(override, options))
+    : [];
+  const userOverride = normalizeBoolean(value.userOverride);
+
+  if (userOverride && overrides.length === 0) {
+    throw new Error('workflowDecisions.userOverride requires at least one override record');
+  }
+
+  return {
+    overrides,
+    userOverride: overrides.length > 0 || userOverride,
+  };
+}
+
+function buildWorkflowDecisions(classification, value, overrideState) {
+  return {
+    classification,
+    reason: normalizeString(value.reason),
+    userOverride: overrideState.userOverride,
+    overrides: overrideState.overrides,
+  };
+}
+
+function normalizeWorkflowDecisions(value = {}, options = {}) {
+  const hasClassification = value && typeof value === 'object'
+    ? Object.hasOwn(value, 'classification')
+    : false;
+  const classification = normalizeString(value.classification);
+  const overrideState = normalizeWorkflowOverrides(value, options);
+
+  if (!classification) {
+    if (options.allowLegacyDefaultClassification && !hasClassification) {
+      return buildWorkflowDecisions('standard', value, overrideState);
+    }
+
+    throw new Error(
+      'Workflow state is missing a classification field. Delete .forge-state.json to reset, or add "classification": "standard" manually.'
+    );
+  }
+
+  if (!WORKFLOW_CLASSIFICATIONS.includes(classification)) {
+    throw new Error(
+      `Invalid workflow classification: ${value.classification}. Expected one of: ${WORKFLOW_CLASSIFICATIONS.join(', ')}`
+    );
+  }
+
+  return buildWorkflowDecisions(classification, value, overrideState);
+}
+
+function shouldUseLegacyStandardVerifyPath(classification, input, options = {}) {
+  const legacyBySchema = input.schemaVersion == null
+    ? options.treatMissingSchemaAsCurrent !== true
+    : input.schemaVersion < WORKFLOW_STATE_SCHEMA_VERSION;
+
+  return (
+    options.allowLegacyStandardVerify === true &&
+    classification === 'standard' &&
+    (
+      input[LEGACY_STANDARD_VERIFY] === true ||
+      legacyBySchema
+    )
+  );
+}
+
+function assertWorkflowPathTransition(previousStage, currentStage, workflowPath, classification) {
+  const previousIndex = workflowPath.indexOf(previousStage);
+  const currentIndex = workflowPath.indexOf(currentStage);
+  const allowed = previousIndex === -1 || previousIndex === workflowPath.length - 1
+    ? []
+    : [workflowPath[previousIndex + 1]];
+
+  if (previousIndex !== -1 && currentIndex === previousIndex + 1) {
+    return true;
+  }
+
+  const suffix = allowed.length > 0 ? ` Allowed next stages: ${allowed.join(', ')}.` : '';
+  throw new Error(
+    `Invalid workflow transition: ${previousStage} -> ${currentStage} for ${classification} workflow.${suffix}`
+  );
+}
+
+function normalizeWorkflowState(input = {}, options = {}) {
+  const currentStage = normalizeStageId(input.currentStage);
+  if (!currentStage) {
+    throw new Error(`Invalid current stage: ${input.currentStage}`);
+  }
+
+  const workflowDecisions = normalizeWorkflowDecisions(input.workflowDecisions || {}, options);
+  const useLegacyStandardVerify = shouldUseLegacyStandardVerifyPath(
+    workflowDecisions.classification,
+    input,
+    options
+  );
+  const workflowPath = useLegacyStandardVerify
+    ? LEGACY_STANDARD_WORKFLOW_PATH
+    : getWorkflowPath(workflowDecisions.classification);
+
+  const previousStage = input.previousStage == null ? null : normalizeStageId(input.previousStage);
+  if (input.previousStage != null && !previousStage) {
+    throw new Error(`Invalid previous stage: ${input.previousStage}`);
+  }
+
+  if (!workflowPath.includes(currentStage)) {
+    throw new Error(`Stage ${currentStage} is not valid for ${workflowDecisions.classification} workflow`);
+  }
+
+  if (previousStage) {
+    assertWorkflowPathTransition(previousStage, currentStage, workflowPath, workflowDecisions.classification);
+  }
+
+  const completedStages = normalizeStageList(input.completedStages);
+  const skippedStages = normalizeStageList(input.skippedStages);
+  const invalidCompletedStage = completedStages.find(stage => !workflowPath.includes(stage));
+  if (invalidCompletedStage) {
+    throw new Error(`Completed stage ${invalidCompletedStage} is not valid for ${workflowDecisions.classification} workflow`);
+  }
+  const invalidSkippedStage = skippedStages.find(stage => !workflowPath.includes(stage));
+  if (invalidSkippedStage) {
+    throw new Error(`Skipped stage ${invalidSkippedStage} is not valid for ${workflowDecisions.classification} workflow`);
+  }
+  const parallelTracks = Array.isArray(input.parallelTracks)
+    ? input.parallelTracks.map(normalizeParallelTrack).filter(Boolean)
+    : [];
+
+  const payload = {
+    schemaVersion: useLegacyStandardVerify ? 1 : WORKFLOW_STATE_SCHEMA_VERSION,
+    currentStage,
+    completedStages,
+    skippedStages,
+    workflowDecisions,
+    parallelTracks,
+  };
+
+  if (useLegacyStandardVerify) {
+    Object.defineProperty(payload, LEGACY_STANDARD_VERIFY, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+
+  return payload;
+}
+
+function serializeWorkflowState(input) {
+  return normalizeWorkflowState(input, {
+    ...LEGACY_WORKFLOW_STATE_OPTIONS,
+    treatMissingSchemaAsCurrent: true,
+  });
+}
+
+function readWorkflowState(source) {
+  if (source == null) {
+    return null;
+  }
+
+  if (typeof source === 'string') {
+    try {
+      return normalizeWorkflowState(JSON.parse(source), LEGACY_WORKFLOW_STATE_OPTIONS);
+    } catch (error) {
+      throw new Error(`Failed to parse workflow state: ${error.message}`);
+    }
+  }
+
+  if (typeof source !== 'object') {
+    throw new Error('Workflow state source must be a string or object');
+  }
+
+  if (source.schemaVersion === WORKFLOW_STATE_SCHEMA_VERSION || source.currentStage) {
+    return normalizeWorkflowState(source, LEGACY_WORKFLOW_STATE_OPTIONS);
+  }
+
+  if (source.workflowState) {
+    return normalizeWorkflowState(source.workflowState, LEGACY_WORKFLOW_STATE_OPTIONS);
+  }
+
+  if (source.metadata && source.metadata.workflowState) {
+    return normalizeWorkflowState(source.metadata.workflowState, LEGACY_WORKFLOW_STATE_OPTIONS);
+  }
+
+  return normalizeWorkflowState(source, LEGACY_WORKFLOW_STATE_OPTIONS);
+}
+
+function writeWorkflowState(input) {
+  const payload = serializeWorkflowState(input);
+
+  return JSON.stringify(payload, null, 2);
+}
+
+function getWorkflowPathForState(workflowState) {
+  if (!workflowState || typeof workflowState !== 'object') {
+    return Object.freeze([]);
+  }
+
+  return workflowState[LEGACY_STANDARD_VERIFY]
+    ? LEGACY_STANDARD_WORKFLOW_PATH
+    : getWorkflowPath(workflowState.workflowDecisions?.classification);
+}
+
+function getAllowedTransitionsForWorkflowState(workflowState) {
+  const currentStage = normalizeStageId(workflowState?.currentStage);
+  if (!currentStage) {
+    return Object.freeze([]);
+  }
+
+  const workflowPath = getWorkflowPathForState(workflowState);
+  const currentIndex = workflowPath.indexOf(currentStage);
+  if (currentIndex === -1 || currentIndex === workflowPath.length - 1) {
+    return Object.freeze([]);
+  }
+
+  return Object.freeze([workflowPath[currentIndex + 1]]);
+}
+
+module.exports = {
+  getAllowedTransitionsForWorkflowState,
+  getWorkflowPathForState,
+  LEGACY_STANDARD_VERIFY,
+  WORKFLOW_STATE_SCHEMA_VERSION,
+  WORKFLOW_CLASSIFICATIONS,
+  normalizeOverrideRecord,
+  normalizeWorkflowDecisions,
+  normalizeWorkflowState,
+  serializeWorkflowState,
+  readWorkflowState,
+  writeWorkflowState,
+  STAGE_IDS,
+  STAGE_MODEL,
+};