agentic-forge 0.0.0

package/src/steps/base.ts

@@ -0,0 +1,71 @@
+/** Base class and types for step executors. */
+
+import type { ConsoleOutput } from "../console.js";
+import type { WorkflowLogger } from "../logging/logger.js";
+import type { TemplateRenderer } from "../renderer.js";
+import type { StepDefinition, WorkflowProgress, WorkflowSettings } from "../types.js";
+
+// --- Step context ---
+
+export interface StepContext {
+	repoRoot: string;
+	config: Record<string, unknown>;
+	renderer: TemplateRenderer;
+	workflowSettings: WorkflowSettings | null;
+	workflowId: string;
+	variables: Record<string, unknown>;
+	outputs: Record<string, unknown>;
+	cwdOverride?: string | null;
+}
+
+export function buildTemplateContext(context: StepContext): Record<string, unknown> {
+	return {
+		variables: context.variables,
+		outputs: context.outputs,
+		workflow_id: context.workflowId,
+		...(context.variables as Record<string, unknown>),
+	};
+}
+
+export function resolveModel(context: StepContext, stepModel?: string | null): string {
+	if (stepModel) {
+		return stepModel;
+	}
+	if (context.workflowSettings?.model) {
+		return context.workflowSettings.model;
+	}
+	const defaults = context.config.defaults as Record<string, unknown> | undefined;
+	return (defaults?.model as string) ?? "sonnet";
+}
+
+// --- Step result ---
+
+export interface StepResult {
+	success: boolean;
+	outputSummary?: string;
+	fullOutput?: string;
+	error?: string;
+}
+
+// --- Abstract base ---
+
+export abstract class StepExecutor {
+	abstract execute(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<StepResult>;
+}
+
+// --- Branch executor type ---
+
+/** Callable type for executing a single step within a composite executor. */
+export type BranchStepExecutor = (
+	step: StepDefinition,
+	progress: WorkflowProgress,
+	context: StepContext,
+	logger: WorkflowLogger,
+	console: ConsoleOutput,
+) => Promise<StepResult>;

package/src/steps/conditional-step.ts

@@ -0,0 +1,144 @@
+/** Conditional step executor. */
+
+import type { ConsoleOutput } from "../console.js";
+import type { WorkflowLogger } from "../logging/logger.js";
+import { WORKFLOW_STATUS, updateStepCompleted, updateStepFailed } from "../progress.js";
+import type { StepDefinition, WorkflowProgress } from "../types.js";
+import {
+	type BranchStepExecutor,
+	type StepContext,
+	StepExecutor,
+	type StepResult,
+	buildTemplateContext,
+} from "./base.js";
+
+export class ConditionalStepExecutor extends StepExecutor {
+	constructor(private branchExecutor: BranchStepExecutor) {
+		super();
+	}
+
+	async execute(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<StepResult> {
+		let condition = step.condition ?? "false";
+		logger.info(step.name, `Evaluating condition: ${condition}`);
+
+		const templateContext = buildTemplateContext(context);
+		if (context.renderer.hasVariables(condition)) {
+			condition = context.renderer.renderString(condition, templateContext);
+		}
+
+		const conditionResult = this.evaluateCondition(condition, templateContext);
+		logger.info(step.name, `Condition evaluated to: ${conditionResult}`);
+		console.info(`Conditional '${step.name}': ${condition} = ${conditionResult}`);
+
+		const stepsToRun = conditionResult ? step.thenSteps : step.elseSteps;
+		const branchName = conditionResult ? "then" : "else";
+
+		if (!stepsToRun || stepsToRun.length === 0) {
+			const outputSummary = `Condition ${conditionResult}, no '${branchName}' branch to execute`;
+			updateStepCompleted(progress, step.name, outputSummary);
+			console.stepComplete(step.name, outputSummary);
+			return { success: true, outputSummary };
+		}
+
+		logger.info(step.name, `Executing '${branchName}' branch with ${stepsToRun.length} steps`);
+
+		for (const subStep of stepsToRun) {
+			try {
+				const result = await this.branchExecutor(subStep, progress, context, logger, console);
+
+				if (!result.success) {
+					logger.warning(step.name, `Conditional '${branchName}' branch stopped due to failure`);
+					const errorMsg = `Step '${subStep.name}' failed: ${result.error}`;
+					updateStepFailed(progress, step.name, errorMsg);
+					console.stepFailed(step.name, `Step '${subStep.name}' failed`);
+					progress.status = WORKFLOW_STATUS.FAILED;
+					return { success: false, error: errorMsg };
+				}
+
+				if (progress.status === WORKFLOW_STATUS.FAILED) {
+					logger.warning(step.name, `Conditional '${branchName}' branch stopped due to failure`);
+					break;
+				}
+			} catch (e) {
+				const errStr = e instanceof Error ? e.message : String(e);
+				logger.error(subStep.name, `Step failed in conditional branch: ${errStr}`);
+				const errorMsg = `Step '${subStep.name}' failed: ${errStr}`;
+				updateStepFailed(progress, step.name, errorMsg);
+				console.stepFailed(step.name, `Step '${subStep.name}' failed`);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				return { success: false, error: errorMsg };
+			}
+		}
+
+		if (progress.status !== WORKFLOW_STATUS.FAILED) {
+			const outputSummary = `Executed '${branchName}' branch (${stepsToRun.length} steps)`;
+			updateStepCompleted(progress, step.name, outputSummary);
+			console.stepComplete(step.name, outputSummary);
+			logger.info(step.name, outputSummary);
+			return { success: true, outputSummary };
+		}
+
+		return { success: false, error: "Conditional execution failed" };
+	}
+
+	evaluateCondition(condition: string, context: Record<string, unknown>): boolean {
+		const trimmed = condition.trim();
+
+		if (["true", "1", "yes"].includes(trimmed.toLowerCase())) {
+			return true;
+		}
+		if (["false", "0", "no", "none", ""].includes(trimmed.toLowerCase())) {
+			return false;
+		}
+
+		if (trimmed.includes("!=")) {
+			const [left, right] = trimmed.split("!=", 2);
+			const leftVal = this.resolveValue(left.trim(), context);
+			const rightVal = this.resolveValue(right.trim(), context);
+			return leftVal !== rightVal;
+		}
+
+		if (trimmed.includes("==")) {
+			const [left, right] = trimmed.split("==", 2);
+			const leftVal = this.resolveValue(left.trim(), context);
+			const rightVal = this.resolveValue(right.trim(), context);
+			return leftVal === rightVal;
+		}
+
+		const value = this.resolveValue(trimmed, context);
+		return (
+			Boolean(value) && value !== "none" && value !== "None" && value !== "null" && value !== ""
+		);
+	}
+
+	resolveValue(expr: string, context: Record<string, unknown>): unknown {
+		const trimmed = expr.trim();
+
+		if (
+			(trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+			(trimmed.startsWith('"') && trimmed.endsWith('"'))
+		) {
+			return trimmed.slice(1, -1);
+		}
+
+		if (trimmed.startsWith("variables.")) {
+			const varName = trimmed.slice(10);
+			const vars = context.variables as Record<string, unknown> | undefined;
+			return vars?.[varName];
+		}
+
+		if (trimmed.startsWith("outputs.")) {
+			const outputName = trimmed.slice(8);
+			const outputs = context.outputs as Record<string, unknown> | undefined;
+			return outputs?.[outputName];
+		}
+
+		return (context as Record<string, unknown>)[trimmed] ?? trimmed;
+	}
+}

package/src/steps/index.ts

@@ -0,0 +1,15 @@
+/** Step executors for workflow execution. */
+
+export {
+	StepContext,
+	StepResult,
+	StepExecutor,
+	BranchStepExecutor,
+	buildTemplateContext,
+	resolveModel,
+} from "./base.js";
+export { PromptStepExecutor } from "./prompt-step.js";
+export { SerialStepExecutor } from "./serial-step.js";
+export { ConditionalStepExecutor } from "./conditional-step.js";
+export { RalphLoopStepExecutor } from "./ralph-loop-step.js";
+export { ParallelStepExecutor } from "./parallel-step.js";

package/src/steps/parallel-step.ts

@@ -0,0 +1,213 @@
+/** Parallel step executor. */
+
+import type { ConsoleOutput } from "../console.js";
+import { type Worktree, createWorktree, removeWorktree, runGit } from "../git/worktree.js";
+import type { WorkflowLogger } from "../logging/logger.js";
+import { WORKFLOW_STATUS, updateStepCompleted, updateStepFailed } from "../progress.js";
+import type { StepDefinition, WorkflowProgress } from "../types.js";
+import {
+	type BranchStepExecutor,
+	type StepContext,
+	StepExecutor,
+	type StepResult,
+} from "./base.js";
+
+export class ParallelStepExecutor extends StepExecutor {
+	constructor(private branchExecutor: BranchStepExecutor) {
+		super();
+	}
+
+	async execute(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<StepResult> {
+		if (!step.steps || step.steps.length === 0) {
+			logger.warning(step.name, "Parallel step has no sub-steps");
+			updateStepCompleted(progress, step.name, "No sub-steps to execute");
+			console.stepComplete(step.name, "No sub-steps to execute");
+			return { success: true, outputSummary: "No sub-steps to execute" };
+		}
+
+		const useWorktree = step.git?.worktree ?? false;
+
+		logger.info(step.name, `Starting parallel execution of ${step.steps.length} branches`);
+		if (useWorktree) {
+			console.info(`Parallel: starting ${step.steps.length} branches (worktree isolation)`);
+		} else {
+			console.info(`Parallel: starting ${step.steps.length} branches`);
+		}
+
+		// Register branches for parallel display
+		const branchNames = step.steps.map((s) => s.name);
+		console.registerParallelBranches(branchNames);
+		console.enterParallelMode();
+
+		const branchResults: Record<string, { success: boolean; output: string }> = {};
+		const failedBranches: string[] = [];
+		const worktrees: Record<string, Worktree> = {};
+
+		const executeBranch = async (
+			branchStep: StepDefinition,
+		): Promise<[string, boolean, string, Worktree | null]> => {
+			const branchContext: StepContext = {
+				...context,
+				variables: { ...context.variables },
+			};
+			let worktree: Worktree | null = null;
+
+			try {
+				console.setParallelBranch(branchStep.name);
+
+				if (useWorktree) {
+					worktree = createWorktree(
+						progress.workflowName,
+						branchStep.name,
+						undefined,
+						context.repoRoot,
+					);
+					logger.info(branchStep.name, `Created worktree: ${worktree.path}`);
+					console.info(`  Branch '${branchStep.name}' worktree: ${worktree.branch}`);
+					branchContext.cwdOverride = worktree.path;
+				}
+
+				const result = await this.branchExecutor(
+					branchStep,
+					progress,
+					branchContext,
+					logger,
+					console,
+				);
+
+				console.flushParallelBranch(branchStep.name);
+
+				return [branchStep.name, result.success, result.outputSummary ?? "", worktree];
+			} catch (e) {
+				const errStr = e instanceof Error ? (e.stack ?? e.message) : String(e);
+				logger.error(branchStep.name, `Branch failed with exception: ${errStr}`);
+				console.flushParallelBranch(branchStep.name);
+				return [branchStep.name, false, String(e), worktree];
+			}
+		};
+
+		// Execute branches with concurrency cap from config
+		const execution = context.config?.execution as Record<string, unknown> | undefined;
+		const maxWorkers = (execution?.maxWorkers as number) ?? 4;
+		const settled: PromiseSettledResult<[string, boolean, string, Worktree | null]>[] = [];
+		const branches = [...step.steps];
+		let idx = 0;
+
+		const runNext = async (): Promise<void> => {
+			while (idx < branches.length) {
+				const branchStep = branches[idx++];
+				try {
+					const value = await executeBranch(branchStep);
+					settled.push({ status: "fulfilled", value });
+				} catch (reason) {
+					settled.push({ status: "rejected", reason });
+				}
+			}
+		};
+
+		const workers = Array.from({ length: Math.min(maxWorkers, branches.length) }, () => runNext());
+		await Promise.all(workers);
+		const results = settled;
+
+		for (const result of results) {
+			if (result.status === "fulfilled") {
+				const [name, success, output, worktree] = result.value;
+				branchResults[name] = { success, output };
+				if (worktree) {
+					worktrees[name] = worktree;
+				}
+				if (success) {
+					console.info(`  Branch '${name}' completed`);
+				} else {
+					console.error(`  Branch '${name}' failed: ${output}`);
+					failedBranches.push(name);
+				}
+			} else {
+				// Promise rejected — should be rare since executeBranch catches errors
+				const reason = String(result.reason);
+				// We can't easily get the branch name from a rejected promise
+				// but this case is already handled by the try/catch inside executeBranch
+				logger.error(step.name, `Branch promise rejected: ${reason}`);
+			}
+		}
+
+		// Exit parallel mode
+		console.exitParallelMode();
+
+		// Handle merge modes
+		if (step.mergeMode === "merge" && Object.keys(worktrees).length > 0) {
+			this.mergeWorktreeBranches(step, worktrees, failedBranches, context, logger, console);
+		}
+
+		if (step.mergeMode === "independent" && Object.keys(worktrees).length > 0) {
+			for (const [name, worktree] of Object.entries(worktrees)) {
+				removeWorktree(worktree, context.repoRoot, false);
+				logger.info(name, `Worktree removed, branch preserved: ${worktree.branch}`);
+			}
+		}
+
+		// Handle completion based on merge strategy
+		if (step.mergeStrategy === "wait-all") {
+			if (failedBranches.length > 0 && step.mergeMode !== "independent") {
+				const errorMsg = `Parallel branches failed: ${failedBranches.join(", ")}`;
+				updateStepFailed(progress, step.name, errorMsg);
+				console.stepFailed(step.name, errorMsg);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				return { success: false, error: errorMsg };
+			}
+
+			const completed = step.steps.length - failedBranches.length;
+			let outputSummary = `Completed ${completed}/${step.steps.length} branches`;
+			if (failedBranches.length > 0) {
+				outputSummary += ` (failed: ${failedBranches.join(", ")})`;
+			}
+			updateStepCompleted(progress, step.name, outputSummary);
+			console.stepComplete(step.name, outputSummary);
+			logger.info(step.name, outputSummary);
+			return { success: true, outputSummary };
+		}
+
+		return { success: true, outputSummary: "Parallel execution completed" };
+	}
+
+	private mergeWorktreeBranches(
+		step: StepDefinition,
+		worktrees: Record<string, Worktree>,
+		failedBranches: string[],
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): void {
+		console.info("Merging parallel branches...");
+
+		for (const [name, worktree] of Object.entries(worktrees)) {
+			if (failedBranches.includes(name)) {
+				removeWorktree(worktree, context.repoRoot, true);
+				logger.info(name, "Failed branch worktree removed");
+				continue;
+			}
+
+			try {
+				runGit(["checkout", worktree.baseBranch], context.repoRoot);
+				runGit(
+					["merge", "--no-ff", "-m", `Merge parallel branch: ${name}`, worktree.branch],
+					context.repoRoot,
+				);
+				logger.info(name, `Merged branch ${worktree.branch} into ${worktree.baseBranch}`);
+				console.info(`  Merged '${name}'`);
+			} catch (e) {
+				logger.error(name, `Merge failed: ${e}`);
+				console.error(`  Merge failed for '${name}': ${e}`);
+			}
+
+			removeWorktree(worktree, context.repoRoot, true);
+			logger.info(name, "Worktree and branch cleaned up");
+		}
+	}
+}

package/src/steps/prompt-step.ts

@@ -0,0 +1,121 @@
+/** Prompt step executor. */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ConsoleOutput } from "../console.js";
+import { extractJson, extractSummary } from "../console.js";
+import type { WorkflowLogger } from "../logging/logger.js";
+import { WORKFLOW_STATUS, updateStepCompleted, updateStepFailed } from "../progress.js";
+import { runClaude } from "../runner.js";
+import type { StepDefinition, WorkflowProgress } from "../types.js";
+import {
+	type StepContext,
+	StepExecutor,
+	type StepResult,
+	buildTemplateContext,
+	resolveModel,
+} from "./base.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class PromptStepExecutor extends StepExecutor {
+	async execute(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<StepResult> {
+		let prompt = step.prompt ?? "";
+		const templateContext = buildTemplateContext(context);
+
+		if (context.renderer.hasVariables(prompt)) {
+			prompt = context.renderer.renderString(prompt, templateContext);
+		}
+
+		const cwd = context.cwdOverride ?? context.repoRoot;
+
+		// Load agent file if specified (fallback to bundled agents)
+		if (step.agent) {
+			let agentPath = path.join(context.repoRoot, step.agent);
+			if (!existsSync(agentPath)) {
+				agentPath = path.join(__dirname, "..", "agents", path.basename(step.agent));
+			}
+			if (existsSync(agentPath)) {
+				const agentContent = readFileSync(agentPath, "utf-8");
+				prompt = `${agentContent}\n\n${prompt}`;
+			}
+		}
+
+		const timeout = (step.stepTimeoutMinutes ?? 60) * 60;
+		const defaults = context.config.defaults as Record<string, unknown> | undefined;
+		const maxRetry = step.stepMaxRetry ?? (defaults?.maxRetry as number) ?? 3;
+		const bypassPermissions = context.workflowSettings?.bypassPermissions ?? false;
+		const allowedTools = context.workflowSettings?.requiredTools?.length
+			? context.workflowSettings.requiredTools
+			: null;
+
+		// Always enable streaming when console is provided
+		const printOutput = true;
+
+		for (let attempt = 0; attempt <= maxRetry; attempt++) {
+			const result = await runClaude({
+				prompt,
+				cwd,
+				model: resolveModel(context, step.model),
+				timeout,
+				printOutput,
+				skipPermissions: bypassPermissions,
+				allowedTools,
+				console,
+				workflowId: context.workflowId,
+			});
+
+			if (result.success) {
+				// Use session output context if available, fall back to extracted summary
+				const sessionOut = result.sessionOutput;
+				let outputSummary: string;
+				if (sessionOut.isSuccess && sessionOut.context) {
+					outputSummary = sessionOut.context;
+					if (sessionOut.sessionId) {
+						logger.info(step.name, `Session ID: ${sessionOut.sessionId}`);
+					}
+				} else {
+					outputSummary = result.stdout ? extractSummary(result.stdout) : "";
+				}
+
+				// Try to extract structured JSON from skill output
+				const stepOutput = result.stdout ? extractJson(result.stdout) : null;
+				const outputValue = stepOutput ?? result.stdout;
+
+				updateStepCompleted(progress, step.name, outputSummary, outputValue);
+				console.stepComplete(step.name, outputSummary);
+				logger.info(step.name, "Step completed successfully");
+				return { success: true, outputSummary, fullOutput: result.stdout };
+			}
+
+			if (attempt < maxRetry) {
+				const errorSummary = result.stderr ? extractSummary(result.stderr) : "Unknown error";
+				console.stepRetry(step.name, attempt + 1, maxRetry + 1, errorSummary);
+				logger.warning(step.name, `Attempt ${attempt + 1} failed, retrying...`, {
+					error: result.stderr,
+				});
+				if (progress.currentStep) {
+					(progress.currentStep as Record<string, unknown>).retry_count = attempt + 1;
+				}
+			} else {
+				const errorMsg = result.stderr || "Step failed";
+				const errorSummary = errorMsg ? extractSummary(errorMsg) : "Unknown error";
+				console.stepFailed(step.name, errorSummary);
+				updateStepFailed(progress, step.name, errorMsg);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				logger.error(step.name, `Step failed after ${maxRetry + 1} attempts`);
+				return { success: false, error: errorMsg };
+			}
+		}
+
+		return { success: false, error: "Unexpected exit from retry loop" };
+	}
+}