forge-workflow 0.0.8 → 0.0.10

package/lib/status/beads-snapshot.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { secureExecFileSync } = require('../shell-utils.js');
+
+function getGitConfig(projectRoot, key) {
+	try {
+		return secureExecFileSync('git', ['config', key], {
+			encoding: 'utf8',
+			cwd: projectRoot,
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+	} catch (_error) {
+		return '';
+	}
+}
+
+function getDeveloperIdentity(projectRoot) {
+	return {
+		email: getGitConfig(projectRoot, 'user.email'),
+		name: getGitConfig(projectRoot, 'user.name'),
+	};
+}
+
+function normalizeEmail(value) {
+	return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+function readIssues(projectRoot) {
+	const issuesPath = path.join(projectRoot, '.beads', 'issues.jsonl');
+	if (!fs.existsSync(issuesPath)) {
+		return [];
+	}
+
+	const raw = fs.readFileSync(issuesPath, 'utf8');
+	const latestById = new Map();
+
+	for (const line of raw.split(/\r?\n/)) {
+		if (!line.trim()) {
+			continue;
+		}
+
+		try {
+			const issue = JSON.parse(line);
+			if (issue && issue.id) {
+				latestById.set(issue.id, issue);
+			}
+		} catch (_error) {
+			// Ignore malformed rows so one bad append does not break status.
+		}
+	}
+
+	return Array.from(latestById.values());
+}
+
+function isAssignedToDeveloper(issue, developer) {
+	if (!issue || !developer) {
+		return false;
+	}
+
+	if (issue.owner) {
+		const developerEmail = normalizeEmail(developer.email);
+		return developerEmail !== '' && normalizeEmail(issue.owner) === developerEmail;
+	}
+
+	return developer.name !== '' && issue.created_by === developer.name;
+}
+
+function parseTimestampOrZero(value) {
+	if (!value) {
+		return 0;
+	}
+
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function sortByUpdatedAtDesc(left, right) {
+	const leftTime = parseTimestampOrZero(left.updated_at);
+	const rightTime = parseTimestampOrZero(right.updated_at);
+	return rightTime - leftTime;
+}
+
+function readBeadsSnapshot(projectRoot) {
+	const developer = getDeveloperIdentity(projectRoot);
+	const issues = readIssues(projectRoot);
+
+	return {
+		developer,
+		issues,
+		activeAssigned: issues.filter(issue => issue.status === 'in_progress' && isAssignedToDeveloper(issue, developer)),
+		ready: issues.filter(issue => issue.status === 'open' && Number(issue.dependency_count || 0) === 0),
+		recentCompleted: issues.filter(issue => issue.status === 'closed').sort(sortByUpdatedAtDesc),
+	};
+}
+
+module.exports = {
+	getDeveloperIdentity,
+	isAssignedToDeveloper,
+	readBeadsSnapshot,
+};

package/lib/status/presenter.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const DEFAULT_SECTION_LIMIT = 5;
+
+function buildSection(title, items, options = {}) {
+	const lines = ['', title];
+	if (!items || items.length === 0) {
+		lines.push('  none', '');
+		return lines;
+	}
+
+	const limit = options.limit ?? null;
+	const visibleItems = limit ? items.slice(0, limit) : items;
+	lines.push(...visibleItems.map(item => `  ${item}`));
+
+	if (limit && items.length > limit) {
+		lines.push(`  ...and ${items.length - limit} more`);
+	}
+
+	lines.push('');
+	return lines;
+}
+
+function formatIssue(issue, options = {}) {
+	const status = options.includeStatus && issue.status ? ` [${issue.status}]` : '';
+	return `${issue.id} ${issue.title || '(untitled)'}${status}`;
+}
+
+function formatWorkflow(workflowResult) {
+	if (!workflowResult) {
+		return ['No active workflow state detected.'];
+	}
+
+	return [
+		`${workflowResult.stageName} (${workflowResult.stageId})`,
+		`Run now: /${workflowResult.runCommand}`,
+		workflowResult.nextCommand ? `Next after this: /${workflowResult.nextCommand}` : 'Next after this: none',
+	];
+}
+
+function formatZeroArgStatus({ context, snapshot, workflowResult = null }) {
+	const contextLines = [
+		`Branch: ${context.branch}`,
+		`Worktree: ${context.inWorktree ? 'linked' : 'main'}`,
+		`Path: ${context.worktreePath}`,
+	];
+
+	if (context.inWorktree && context.mainWorktree) {
+		contextLines.push(`Main worktree: ${context.mainWorktree}`);
+	}
+
+	contextLines.push(`Working tree: ${context.workingTree.summary}`);
+
+	return [
+		...buildSection('Context', contextLines),
+		...buildSection('Active Issues', (snapshot.activeAssigned || []).map(issue => formatIssue(issue, { includeStatus: true }))),
+		...buildSection('Ready', (snapshot.ready || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Recent Completions', (snapshot.recentCompleted || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Workflow', formatWorkflow(workflowResult)),
+	].join('\n');
+}
+
+module.exports = {
+	formatZeroArgStatus,
+};

package/lib/workflow/enforce-stage.js

@@ -1,8 +1,5 @@
 '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');
@@ -11,8 +8,9 @@ const {
   normalizeOverrideRecord,
   readWorkflowState,
 } = require('./state');
+const { loadState, WORKFLOW_STATE_FILENAME } = require('./state-manager');
 
-const WORKFLOW_STATE_FILENAME = '.forge-state.json';
+const STATELESS_ENTRY_STAGES = new Set(['plan', 'dev', 'validate', 'verify']);
 
 function getOverrideInput(flags = {}) {
   if (Object.hasOwn(flags, 'overrideStage')) {
@@ -67,6 +65,8 @@ function readWorkflowStateFile(projectRoot) {
     return null;
   }
 
+  const fs = require('node:fs');
+  const path = require('node:path');
   const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
   if (!fs.existsSync(statePath)) {
     return null;
@@ -76,11 +76,17 @@ function readWorkflowStateFile(projectRoot) {
 }
 
 function resolveWorkflowStateInput(workflowState, flags = {}, args = [], projectRoot) {
-  return workflowState
+  const inlineOrFlag = workflowState
     || flags.workflowState
     || flags['--workflow-state']
-    || getCliFlagValue('--workflow-state', args)
-    || readWorkflowStateFile(projectRoot);
+    || getCliFlagValue('--workflow-state', args);
+
+  if (inlineOrFlag) {
+    return inlineOrFlag;
+  }
+
+  const { state } = loadState(projectRoot);
+  return state;
 }
 
 function readWorkflowStateInput(input) {
@@ -127,7 +133,7 @@ async function enforceStageEntry({ commandName, args = [], flags = {}, projectRo
   const stateInput = resolveWorkflowStateInput(workflowState, flags, args, projectRoot);
   const currentState = readWorkflowStateInput(stateInput);
   if (!currentState) {
-    if (stageId === 'plan') {
+    if (STATELESS_ENTRY_STAGES.has(stageId)) {
       return { allowed: true, stage: stageId, workflowState: null };
     }
 

package/lib/workflow/state-manager.js

@@ -0,0 +1,349 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { secureExecFileSync } = require('../shell-utils.js');
+const { readWorkflowState, serializeWorkflowState, WORKFLOW_STATE_SCHEMA_VERSION, getAllowedTransitionsForWorkflowState } = require('./state.js');
+const { getWorkflowPath, WORKFLOW_CLASSIFICATIONS, normalizeStageId } = require('./stages.js');
+
+const WORKFLOW_STATE_FILENAME = '.forge-state.json';
+
+function parseRelaxedWorkflowStatePayload(payload = '') {
+  const currentStage = String(payload).match(/currentStage:([a-z]+)/)?.[1];
+  if (!currentStage) {
+    return null;
+  }
+
+  const completedStages = (String(payload).match(/completedStages:\[([^\]]*)\]/)?.[1] || '')
+    .split(',')
+    .map(stage => stage.trim())
+    .filter(Boolean);
+  const skippedStages = (String(payload).match(/skippedStages:\[([^\]]*)\]/)?.[1] || '')
+    .split(',')
+    .map(stage => stage.trim())
+    .filter(Boolean);
+  const classification = String(payload).match(/classification:([a-z]+)/)?.[1] || 'standard';
+  const reason = String(payload).match(/reason:([^,}\]]+)/)?.[1]?.trim() || 'legacy-comment';
+
+  return readWorkflowState(JSON.stringify({
+    currentStage,
+    completedStages,
+    skippedStages,
+    workflowDecisions: {
+      classification,
+      reason,
+      userOverride: false,
+      overrides: [],
+    },
+    parallelTracks: [],
+  }));
+}
+
+function extractWorkflowStateFromComments(comments = '') {
+  const matches = String(comments)
+    .split(/\r?\n/)
+    .filter(line => line.startsWith('WorkflowState:'));
+  if (!matches || matches.length === 0) {
+    return null;
+  }
+
+  for (const match of [...matches].reverse()) {
+    const payload = match.replace(/^WorkflowState:\s*/, '');
+    try {
+      return readWorkflowState(payload);
+    } catch (_strictError) {
+      try {
+        const relaxedState = parseRelaxedWorkflowStatePayload(payload);
+        if (relaxedState) {
+          return relaxedState;
+        }
+      } catch (_relaxedError) {
+        // Continue to any earlier payloads.
+      }
+    }
+  }
+
+  return null;
+}
+
+function extractWorkflowStateFromIssue(issue = {}) {
+  if (!issue || typeof issue !== 'object') {
+    return null;
+  }
+
+  if (typeof issue.comments === 'string') {
+    return extractWorkflowStateFromComments(issue.comments);
+  }
+
+  if (!Array.isArray(issue.comments) || issue.comments.length === 0) {
+    return null;
+  }
+
+  const mergedComments = issue.comments
+    .map(comment => {
+      if (typeof comment === 'string') {
+        return comment;
+      }
+
+      return comment && typeof comment === 'object' ? comment.text || '' : '';
+    })
+    .filter(Boolean)
+    .join('\n');
+
+  if (!mergedComments) {
+    return null;
+  }
+
+  return extractWorkflowStateFromComments(mergedComments);
+}
+
+function readBeadsIssue(issueId, options = {}) {
+  if (!issueId) {
+    return null;
+  }
+
+  try {
+    const { projectRoot, ...execOptions } = options;
+    const raw = secureExecFileSync('bd', ['show', issueId, '--json'], {
+      encoding: 'utf8',
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...execOptions,
+    }).trim();
+
+    if (!raw) {
+      return null;
+    }
+
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      return parsed[0] || null;
+    }
+
+    return parsed;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function readWorkflowStateFromBeads(issueId, options = {}) {
+  if (!issueId) {
+    return null;
+  }
+
+  if (options.issue) {
+    const state = extractWorkflowStateFromIssue(options.issue);
+    if (state) {
+      return state;
+    }
+  }
+
+  let comments = options.comments;
+  if (!comments) {
+    try {
+      const issue = readBeadsIssue(issueId, { projectRoot: options.projectRoot });
+      const state = extractWorkflowStateFromIssue(issue);
+      if (state) {
+        return state;
+      }
+    } catch (_error) {
+      // Fall through to comments-list fallback.
+    }
+  }
+
+  comments = comments || secureExecFileSync('bd', ['comments', 'list', issueId], {
+    encoding: 'utf8',
+    cwd: options.projectRoot,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+
+  if (!comments) {
+    return null;
+  }
+
+  return extractWorkflowStateFromComments(comments);
+}
+
+function loadStateFromBeads(options, projectRoot) {
+  if (options.comments) {
+    const state = extractWorkflowStateFromComments(options.comments);
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
+  if (options.issue) {
+    const state = extractWorkflowStateFromIssue(options.issue);
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
+  if (options.issueId) {
+    const state = readWorkflowStateFromBeads(options.issueId, {
+      comments: options.comments,
+      issue: options.issue,
+      projectRoot,
+    });
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
+  return null;
+}
+
+function loadState(projectRoot, options = {}) {
+  if (!projectRoot) {
+    const beadsResult = loadStateFromBeads(options, null);
+    return beadsResult || { state: null, source: null };
+  }
+
+  if (options.preferBeads && (options.comments || options.issue || options.issueId)) {
+    try {
+      const beadsResult = loadStateFromBeads(options, projectRoot);
+      if (beadsResult) {
+        return beadsResult;
+      }
+    } catch (error) {
+      if (typeof options.onBeadsError === 'function') {
+        options.onBeadsError(error);
+      }
+      // Fall through to the on-disk state file when Beads cannot be read.
+    }
+  }
+
+  const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
+  if (fs.existsSync(statePath)) {
+    try {
+      const raw = fs.readFileSync(statePath, 'utf8');
+      return { state: readWorkflowState(raw), source: 'file' };
+    } catch (_parseError) {
+      // File is malformed — fall through to Beads fallback
+    }
+  }
+
+  const beadsResult = loadStateFromBeads(options, projectRoot);
+  if (beadsResult) {
+    return beadsResult;
+  }
+
+  return { state: null, source: null };
+}
+
+function saveState(projectRoot, state) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new Error('saveState requires a valid projectRoot path');
+  }
+
+  const normalized = serializeWorkflowState(state);
+  const json = JSON.stringify(normalized, null, 2);
+  const tmpPath = path.join(projectRoot, `${WORKFLOW_STATE_FILENAME}.tmp`);
+  const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
+
+  fs.writeFileSync(tmpPath, json, 'utf8');
+  fs.renameSync(tmpPath, statePath);
+
+  return normalized;
+}
+
+function initializeState(projectRoot, classification, firstStage) {
+  if (!WORKFLOW_CLASSIFICATIONS.includes(classification)) {
+    throw new Error(`Invalid classification: ${classification}. Expected one of: ${WORKFLOW_CLASSIFICATIONS.join(', ')}`);
+  }
+
+  const workflowPath = getWorkflowPath(classification);
+  const currentStage = firstStage || workflowPath[0];
+
+  const state = {
+    schemaVersion: WORKFLOW_STATE_SCHEMA_VERSION,
+    currentStage,
+    completedStages: [],
+    skippedStages: [],
+    workflowDecisions: {
+      classification,
+      reason: 'initialized',
+      userOverride: false,
+      overrides: [],
+    },
+    parallelTracks: [],
+  };
+
+  return saveState(projectRoot, state);
+}
+
+function transitionStage(projectRoot, toStage, options = {}) {
+  const targetStage = normalizeStageId(toStage);
+  if (!targetStage) {
+    throw new Error(`Invalid target stage: ${toStage}`);
+  }
+
+  const { state: currentState } = loadState(projectRoot, options);
+  if (!currentState) {
+    throw new Error('No workflow state found. Initialize state first with initializeState().');
+  }
+
+  const previousState = JSON.parse(JSON.stringify(currentState));
+  const allowed = getAllowedTransitionsForWorkflowState(currentState);
+
+  if (!allowed.includes(targetStage)) {
+    if (!options.override) {
+      throw new Error(
+        `Transition from ${currentState.currentStage} to ${targetStage} is not allowed. ` +
+        `Allowed transitions: ${allowed.join(', ') || 'none'}. Provide an override to force.`
+      );
+    }
+  }
+
+  const completedStages = [...currentState.completedStages];
+  if (!completedStages.includes(currentState.currentStage)) {
+    completedStages.push(currentState.currentStage);
+  }
+
+  const overrides = [...(currentState.workflowDecisions.overrides || [])];
+  if (options.override) {
+    overrides.push({
+      type: options.override.type || 'manual',
+      fromStage: currentState.currentStage,
+      toStage: targetStage,
+      reason: options.override.reason || '',
+      actor: options.override.actor || 'unknown',
+      userOverride: true,
+      recordedAt: new Date().toISOString(),
+    });
+  }
+
+  const newStateInput = {
+    schemaVersion: currentState.schemaVersion || WORKFLOW_STATE_SCHEMA_VERSION,
+    currentStage: targetStage,
+    completedStages,
+    skippedStages: currentState.skippedStages || [],
+    workflowDecisions: {
+      ...currentState.workflowDecisions,
+      overrides,
+      userOverride: overrides.length > 0,
+    },
+    parallelTracks: currentState.parallelTracks || [],
+  };
+
+  const newState = saveState(projectRoot, newStateInput);
+
+  return {
+    previousState,
+    newState,
+    transitioned: true,
+  };
+}
+
+module.exports = {
+  WORKFLOW_STATE_FILENAME,
+  extractWorkflowStateFromComments,
+  extractWorkflowStateFromIssue,
+  initializeState,
+  loadState,
+  readBeadsIssue,
+  readWorkflowStateFromBeads,
+  saveState,
+  transitionStage,
+};

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",
+    "forge-workflow": "bin/forge.js",
     "forge-preflight": "bin/forge-preflight.js"
   },
   "workspaces": [
@@ -14,16 +15,23 @@
     "test:setup": "bash test-env/automation/setup-fixtures.sh",
     "test:all": "bun run test:setup && bun test",
     "test:coverage": "c8 --check-coverage bun test",
+    "test:ci:shard": "node scripts/test-ci-shard.js",
     "typecheck": "echo 'No TypeScript in project - skipping type check'",
     "lint": "eslint . --max-warnings 0",
-    "check": "bash scripts/validate.sh",
+    "check": "node scripts/validate.js",
     "prepare": "lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
     "setup": "node ./bin/forge.js setup",
     "help": "node ./bin/forge.js --help",
     "validate:yaml": "find . \\( -name '*.yml' -o -name '*.yaml' \\) | grep -v node_modules | while IFS= read -r file; do echo \"Checking $file...\" && bun x js-yaml \"$file\" > /dev/null || exit 1; done",
     "test:mutation": "npx stryker run",
-    "test:benchmark": "node scripts/benchmark.js",
-    "test:dashboard": "node scripts/test-dashboard.js"
+    "test:benchmark": "node scripts/benchmark.js --output test-results/benchmark-results.json --profile-dir test-results/benchmark-profiles",
+    "test:benchmark:full": "node scripts/benchmark.js --output test-results/benchmark-full-results.json --profile-dir test-results/benchmark-full-profiles --group full-suite --group validate",
+    "test:full:parallel": "node scripts/test-full-suite.js",
+    "test:dashboard": "node scripts/test-dashboard.js",
+    "test:profile": "node scripts/test-profile.js --input-dir test-results --output test-results/test-profile.json --label local",
+    "test:randomized": "bun test --randomize",
+    "test:rerun": "bun test --rerun-each 2",
+    "agentic:sync": "node scripts/sync-agentic-workflow.js"
   },
   "peerDependencies": {
     "lefthook": "^1.0.0"