agentic-forge 0.0.0

package/src/executor.ts

@@ -0,0 +1,354 @@
+/** Workflow executor for running workflows. */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadConfig } from "./config.js";
+import type { ConsoleOutput } from "./console.js";
+import { OutputLevel } from "./console.js";
+import { ConsoleOutput as ConsoleOutputClass } from "./console.js";
+import type { WorkflowLogger } from "./logging/logger.js";
+import { WorkflowLogger as WorkflowLoggerClass } from "./logging/logger.js";
+import {
+	STEP_STATUS,
+	WORKFLOW_STATUS,
+	createProgress,
+	generateWorkflowId,
+	saveProgress,
+	updateStepFailed,
+	updateStepStarted,
+} from "./progress.js";
+import { TemplateRenderer, buildTemplateContext, renderWorkflowOutput } from "./renderer.js";
+import { type StepContext, type StepResult, resolveModel } from "./steps/base.js";
+import { ConditionalStepExecutor } from "./steps/conditional-step.js";
+import { ParallelStepExecutor } from "./steps/parallel-step.js";
+import { PromptStepExecutor } from "./steps/prompt-step.js";
+import { RalphLoopStepExecutor } from "./steps/ralph-loop-step.js";
+import { SerialStepExecutor } from "./steps/serial-step.js";
+import type {
+	OutputDefinition,
+	StepDefinition,
+	StepType,
+	WorkflowDefinition,
+	WorkflowProgress,
+	WorkflowSettings,
+} from "./types.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class WorkflowExecutor {
+	repoRoot: string;
+	config: Record<string, unknown>;
+	strictMode: boolean;
+	renderer: TemplateRenderer;
+	workflowSettings: WorkflowSettings | null = null;
+	executors: Record<
+		string,
+		| PromptStepExecutor
+		| ParallelStepExecutor
+		| SerialStepExecutor
+		| ConditionalStepExecutor
+		| RalphLoopStepExecutor
+	>;
+
+	promptExecutor: PromptStepExecutor;
+	ralphLoopExecutor: RalphLoopStepExecutor;
+	parallelExecutor: ParallelStepExecutor;
+	serialExecutor: SerialStepExecutor;
+	conditionalExecutor: ConditionalStepExecutor;
+
+	constructor(repoRoot?: string, strictMode = false) {
+		this.repoRoot = repoRoot ?? process.cwd();
+		this.config = loadConfig(this.repoRoot);
+		this.strictMode = strictMode;
+		this.renderer = new TemplateRenderer(undefined, strictMode);
+
+		// Initialize step executors
+		this.promptExecutor = new PromptStepExecutor();
+		this.ralphLoopExecutor = new RalphLoopStepExecutor();
+
+		// Branch executor function for nested steps
+		const branchExecutors: Record<
+			string,
+			{
+				execute: (
+					step: StepDefinition,
+					progress: WorkflowProgress,
+					context: StepContext,
+					logger: WorkflowLogger,
+					console: ConsoleOutput,
+				) => Promise<StepResult>;
+			}
+		> = {
+			prompt: this.promptExecutor,
+			"ralph-loop": this.ralphLoopExecutor,
+		};
+
+		const branchExecute = async (
+			step: StepDefinition,
+			progress: WorkflowProgress,
+			context: StepContext,
+			logger: WorkflowLogger,
+			console: ConsoleOutput,
+		): Promise<StepResult> => {
+			const executor = branchExecutors[step.type] ?? this.executors[step.type];
+			if (!executor) {
+				throw new Error(`Step type not yet implemented: ${step.type}`);
+			}
+			return executor.execute(step, progress, context, logger, console);
+		};
+
+		this.parallelExecutor = new ParallelStepExecutor(branchExecute);
+		this.serialExecutor = new SerialStepExecutor(branchExecute);
+		this.conditionalExecutor = new ConditionalStepExecutor(branchExecute);
+
+		// Add complex executors to branch lookup
+		branchExecutors.serial = this.serialExecutor;
+		branchExecutors.conditional = this.conditionalExecutor;
+
+		this.executors = {
+			prompt: this.promptExecutor,
+			parallel: this.parallelExecutor,
+			serial: this.serialExecutor,
+			conditional: this.conditionalExecutor,
+			"ralph-loop": this.ralphLoopExecutor,
+			"wait-for-human": {
+				execute: async (
+					step: StepDefinition,
+					progress: WorkflowProgress,
+					_context: StepContext,
+					logger: WorkflowLogger,
+				): Promise<StepResult> => {
+					logger.info(step.name, `Waiting for human input: ${step.message}`);
+					progress.status = WORKFLOW_STATUS.PAUSED;
+					progress.currentStep = {
+						name: step.name,
+						type: "wait-for-human",
+						message: step.message,
+						started_at: new Date().toISOString(),
+						timeout_minutes: step.stepTimeoutMinutes ?? 5,
+						on_timeout: step.onTimeout,
+					};
+					return { success: true, outputSummary: "Paused for human input" };
+				},
+			},
+		};
+	}
+
+	async run(
+		workflow: WorkflowDefinition,
+		variables?: Record<string, unknown>,
+		fromStep?: string | null,
+		terminalOutput = "base",
+		workflowFile = "",
+		resumeProgress?: WorkflowProgress | null,
+	): Promise<WorkflowProgress> {
+		let vars = variables ? { ...variables } : {};
+		this.workflowSettings = workflow.settings;
+
+		// Update renderer with workflow's strict_mode setting
+		this.renderer = new TemplateRenderer(undefined, workflow.settings.strictMode);
+
+		// Create console output handler
+		const outputLevel = terminalOutput === "all" ? OutputLevel.ALL : OutputLevel.BASE;
+		const console = new ConsoleOutputClass(outputLevel);
+
+		let progress: WorkflowProgress;
+		let workflowId: string;
+
+		if (resumeProgress) {
+			progress = resumeProgress;
+			// Seed variables from stored progress, then overlay any new CLI vars
+			const merged = { ...progress.variables };
+			Object.assign(merged, vars);
+			vars = merged;
+			progress.variables = vars;
+			workflowId = progress.workflowId;
+			if (!progress.workflowFile && workflowFile) {
+				progress.workflowFile = workflowFile;
+			}
+		} else {
+			for (const v of workflow.variables) {
+				if (!(v.name in vars)) {
+					if (v.required && v.default === undefined) {
+						throw new Error(`Missing required variable: ${v.name}`);
+					}
+					vars[v.name] = v.default;
+				}
+			}
+
+			workflowId = generateWorkflowId(workflow.name);
+			const stepNames = workflow.steps.map((s) => s.name);
+			progress = createProgress(workflowId, workflow.name, stepNames, vars, workflowFile);
+		}
+
+		saveProgress(progress, this.repoRoot);
+
+		const logger = new WorkflowLoggerClass(workflowId, this.repoRoot);
+		logger.info("workflow", `Started workflow: ${workflow.name}`);
+
+		console.workflowStart(workflow.name, workflowId);
+
+		// Build set of completed step names to skip on resume
+		const completedStepNames = new Set(
+			progress.completedSteps
+				.filter((s) => s.status === STEP_STATUS.COMPLETED || s.status === STEP_STATUS.SKIPPED)
+				.map((s) => s.name),
+		);
+
+		let skipUntil = fromStep ?? null;
+
+		for (const step of workflow.steps) {
+			if (skipUntil) {
+				if (step.name === skipUntil) {
+					skipUntil = null;
+				} else {
+					continue;
+				}
+			}
+
+			// Skip steps already completed/skipped during resume
+			if (completedStepNames.has(step.name)) {
+				logger.info(step.name, `Skipping already completed step: ${step.name}`);
+				console.info(`Skipping completed step: ${step.name}`);
+				continue;
+			}
+
+			try {
+				await this.executeStep(step, progress, vars, logger, console);
+				saveProgress(progress, this.repoRoot);
+
+				if (progress.status === WORKFLOW_STATUS.FAILED) {
+					break;
+				}
+			} catch (e: unknown) {
+				const errorMsg = e instanceof Error ? e.message : String(e);
+				logger.error(step.name, `Step failed: ${errorMsg}`);
+				console.stepFailed(step.name, errorMsg);
+				updateStepFailed(progress, step.name, errorMsg);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				saveProgress(progress, this.repoRoot);
+				break;
+			}
+		}
+
+		if (progress.status === WORKFLOW_STATUS.RUNNING) {
+			progress.status = WORKFLOW_STATUS.COMPLETED;
+		}
+		progress.completedAt = new Date().toISOString();
+		saveProgress(progress, this.repoRoot);
+
+		this.renderOutputs(workflow, progress, vars, logger);
+
+		console.workflowComplete(workflow.name, progress.status);
+		logger.info("workflow", `Workflow ${progress.status}: ${workflow.name}`);
+		return progress;
+	}
+
+	private renderOutputs(
+		workflow: WorkflowDefinition,
+		progress: WorkflowProgress,
+		variables: Record<string, unknown>,
+		logger: WorkflowLogger,
+	): void {
+		if (!workflow.outputs || workflow.outputs.length === 0) {
+			return;
+		}
+
+		const stepOutputs: Record<string, Record<string, unknown>> = {};
+		for (const step of progress.completedSteps) {
+			const entry: Record<string, unknown> = {
+				status: step.status,
+				started_at: step.startedAt,
+				completed_at: step.completedAt,
+				output_summary: step.outputSummary,
+				error: step.error,
+			};
+			if (step.name in progress.stepOutputs) {
+				entry.output = progress.stepOutputs[step.name];
+			}
+			stepOutputs[step.name] = entry;
+		}
+
+		const context = buildTemplateContext(
+			workflow.name,
+			progress.workflowId,
+			progress.startedAt ?? "",
+			progress.completedAt,
+			stepOutputs,
+			[],
+			[],
+			[],
+			variables,
+		);
+
+		const pluginTemplates = path.join(__dirname, "templates");
+		const templateDirs = [pluginTemplates, this.repoRoot];
+
+		const outputDir = path.join(this.repoRoot, "agentic", "outputs", progress.workflowId);
+
+		for (const output of workflow.outputs) {
+			if (output.when === "completed" && progress.status !== WORKFLOW_STATUS.COMPLETED) {
+				continue;
+			}
+			if (output.when === "failed" && progress.status !== WORKFLOW_STATUS.FAILED) {
+				continue;
+			}
+
+			try {
+				let outputPathStr = output.path;
+				if (this.renderer.hasVariables(outputPathStr)) {
+					outputPathStr = this.renderer.renderString(outputPathStr, {
+						workflow_id: progress.workflowId,
+						...variables,
+					});
+				}
+				const outputPath = path.join(outputDir, outputPathStr);
+
+				renderWorkflowOutput(
+					output.template,
+					outputPath,
+					context,
+					templateDirs,
+					workflow.settings.strictMode,
+				);
+				logger.info("workflow", `Generated output: ${outputPath}`);
+			} catch (e: unknown) {
+				const errorMsg = e instanceof Error ? e.message : String(e);
+				logger.error("workflow", `Failed to render output '${output.name}': ${errorMsg}`);
+			}
+		}
+	}
+
+	async executeStep(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		variables: Record<string, unknown>,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<void> {
+		const context: StepContext = {
+			repoRoot: this.repoRoot,
+			config: this.config,
+			renderer: this.renderer,
+			workflowSettings: this.workflowSettings,
+			workflowId: progress.workflowId,
+			variables,
+			outputs: progress.stepOutputs,
+		};
+
+		const resolvedModel = resolveModel(context, step.model);
+
+		logger.info(step.name, `Starting step: ${step.name}`);
+		console.stepStart(step.name, step.type, resolvedModel);
+		updateStepStarted(progress, step.name);
+		saveProgress(progress, this.repoRoot);
+
+		const executor = this.executors[step.type];
+		if (!executor) {
+			throw new Error(`Step type not yet implemented: ${step.type}`);
+		}
+
+		await executor.execute(step, progress, context, logger, console);
+	}
+}

package/src/git/worktree.ts

@@ -0,0 +1,236 @@
+/** Git worktree management for parallel workflow execution. */
+
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { getExecutable } from "../runner.js";
+
+// --- Worktree data ---
+
+export interface Worktree {
+	path: string;
+	branch: string;
+	baseBranch: string;
+}
+
+// --- Git command helper ---
+
+export function runGit(
+	args: string[],
+	cwd?: string | null,
+	check = true,
+): { stdout: string; stderr: string; returncode: number } {
+	const gitPath = getExecutable("git");
+	const cmd = [gitPath, ...args];
+	try {
+		const stdout = execFileSync(gitPath, args, {
+			encoding: "utf-8",
+			cwd: cwd ?? undefined,
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		return { stdout, stderr: "", returncode: 0 };
+	} catch (e: unknown) {
+		const err = e as { stdout?: string; stderr?: string; status?: number };
+		if (check) {
+			throw new Error(`Git command failed: ${cmd.join(" ")}\n${err.stderr ?? ""}`);
+		}
+		return {
+			stdout: (err.stdout as string) ?? "",
+			stderr: (err.stderr as string) ?? "",
+			returncode: (err.status as number) ?? 1,
+		};
+	}
+}
+
+// --- Name helpers ---
+
+function truncate(name: string, maxLen = 30): string {
+	return name.length > maxLen ? name.slice(0, maxLen) : name;
+}
+
+function generateSuffix(): string {
+	return randomBytes(3).toString("hex");
+}
+
+function sanitizeName(name: string): string {
+	return name.replace(/\//g, "-").replace(/ /g, "-").replace(/_/g, "-").toLowerCase();
+}
+
+// --- Repository helpers ---
+
+export function getRepoRoot(cwd?: string | null): string {
+	const result = runGit(["rev-parse", "--show-toplevel"], cwd);
+	return result.stdout.trim();
+}
+
+export function getDefaultBranch(cwd?: string | null): string {
+	const result = runGit(["symbolic-ref", "refs/remotes/origin/HEAD"], cwd, false);
+	if (result.returncode === 0) {
+		const parts = result.stdout.trim().split("/");
+		return parts[parts.length - 1] ?? "main";
+	}
+	for (const branch of ["main", "master"]) {
+		const check = runGit(["rev-parse", "--verify", branch], cwd, false);
+		if (check.returncode === 0) {
+			return branch;
+		}
+	}
+	return "main";
+}
+
+export function getCurrentBranch(cwd?: string | null): string {
+	const result = runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+	return result.stdout.trim();
+}
+
+// --- Worktree operations ---
+
+export function createWorktree(
+	workflowName: string,
+	stepName: string,
+	baseBranch?: string | null,
+	repoRoot?: string | null,
+): Worktree {
+	const root = repoRoot || getRepoRoot();
+	const base = baseBranch || getDefaultBranch(root);
+
+	const suffix = generateSuffix();
+	const wfName = truncate(sanitizeName(workflowName));
+	const stName = truncate(sanitizeName(stepName));
+
+	const dirName = `agentic-${wfName}-${stName}-${suffix}`;
+	const branchName = `agentic/${wfName}-${stName}-${suffix}`;
+
+	const worktreePath = path.join(root, ".worktrees", dirName);
+	const parentDir = path.dirname(worktreePath);
+	mkdirSync(parentDir, { recursive: true });
+
+	if (existsSync(worktreePath)) {
+		rmSync(worktreePath, { recursive: true, force: true });
+		runGit(["worktree", "prune"], root, false);
+	}
+
+	runGit(["worktree", "add", "-b", branchName, worktreePath, base], root);
+
+	return { path: worktreePath, branch: branchName, baseBranch: base };
+}
+
+export function removeWorktree(
+	worktree: Worktree,
+	repoRoot?: string | null,
+	deleteBranch = true,
+): void {
+	const root = repoRoot || getRepoRoot();
+
+	const result = runGit(["worktree", "remove", "--force", worktree.path], root, false);
+
+	if (result.returncode !== 0 && existsSync(worktree.path)) {
+		rmSync(worktree.path, { recursive: true, force: true });
+		runGit(["worktree", "prune"], root, false);
+	}
+
+	if (deleteBranch && worktree.branch) {
+		runGit(["branch", "-D", worktree.branch], root, false);
+	}
+}
+
+export function listWorktrees(repoRoot?: string | null): Worktree[] {
+	const root = repoRoot || getRepoRoot();
+
+	const result = runGit(["worktree", "list", "--porcelain"], root);
+
+	const worktrees: Worktree[] = [];
+	let currentPath: string | null = null;
+	let currentBranch = "";
+
+	for (const line of result.stdout.trim().split("\n")) {
+		if (line.startsWith("worktree ")) {
+			currentPath = line.slice(9);
+		} else if (line.startsWith("branch ")) {
+			currentBranch = line.replace("branch refs/heads/", "");
+		} else if (line === "" && currentPath) {
+			worktrees.push({ path: currentPath, branch: currentBranch, baseBranch: "" });
+			currentPath = null;
+			currentBranch = "";
+		}
+	}
+
+	if (currentPath) {
+		worktrees.push({ path: currentPath, branch: currentBranch, baseBranch: "" });
+	}
+
+	return worktrees;
+}
+
+export function listAgenticWorktrees(repoRoot?: string | null): Worktree[] {
+	return listWorktrees(repoRoot).filter((wt) => wt.branch.startsWith("agentic/"));
+}
+
+export function pruneOrphaned(repoRoot?: string | null): number {
+	const root = repoRoot || getRepoRoot();
+
+	runGit(["worktree", "prune"], root, false);
+
+	let cleaned = 0;
+	const worktreesDir = path.join(root, ".worktrees");
+	if (existsSync(worktreesDir)) {
+		for (const entry of readdirSync(worktreesDir)) {
+			const wtDir = path.join(worktreesDir, entry);
+			if (statSync(wtDir).isDirectory() && entry.startsWith("agentic-")) {
+				const gitFile = path.join(wtDir, ".git");
+				if (!existsSync(gitFile)) {
+					rmSync(wtDir, { recursive: true, force: true });
+					cleaned++;
+				}
+			}
+		}
+	}
+
+	return cleaned;
+}
+
+// --- Branch operations ---
+
+export function createBranch(
+	branchName: string,
+	baseBranch?: string | null,
+	cwd?: string | null,
+): string {
+	const base = baseBranch || getDefaultBranch(cwd);
+	runGit(["checkout", "-b", branchName, base], cwd);
+	return branchName;
+}
+
+export function checkoutBranch(branchName: string, cwd?: string | null): void {
+	runGit(["checkout", branchName], cwd);
+}
+
+export function commitChanges(message: string, cwd?: string | null, addAll = true): boolean {
+	if (addAll) {
+		runGit(["add", "-A"], cwd);
+	}
+
+	const result = runGit(["status", "--porcelain"], cwd);
+	if (!result.stdout.trim()) {
+		return false;
+	}
+
+	runGit(["commit", "-m", message], cwd);
+	return true;
+}
+
+export function pushBranch(
+	branchName: string,
+	remote = "origin",
+	cwd?: string | null,
+	setUpstream = true,
+): void {
+	const args = ["push"];
+	if (setUpstream) {
+		args.push("-u", remote, branchName);
+	} else {
+		args.push(remote, branchName);
+	}
+	runGit(args, cwd);
+}

package/src/logging/logger.ts

@@ -0,0 +1,95 @@
+/** NDJSON structured logging for workflows. */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+// --- Log levels ---
+
+export const LOG_LEVEL = {
+	CRITICAL: "Critical",
+	ERROR: "Error",
+	WARNING: "Warning",
+	INFORMATION: "Information",
+} as const;
+
+export type LogLevel = (typeof LOG_LEVEL)[keyof typeof LOG_LEVEL];
+
+// --- Log entry ---
+
+export interface LogEntry {
+	timestamp: string;
+	level: string;
+	step: string;
+	message: string;
+	context: Record<string, unknown> | null;
+}
+
+// --- Logger class ---
+
+export class WorkflowLogger {
+	readonly workflowId: string;
+	readonly logPath: string;
+
+	constructor(workflowId: string, repoRoot?: string) {
+		this.workflowId = workflowId;
+		const root = repoRoot ?? process.cwd();
+		this.logPath = path.join(root, "agentic", "outputs", workflowId, "logs.ndjson");
+		mkdirSync(path.dirname(this.logPath), { recursive: true });
+	}
+
+	log(
+		level: LogLevel,
+		step: string,
+		message: string,
+		context?: Record<string, unknown> | null,
+	): void {
+		const entry: LogEntry = {
+			timestamp: new Date().toISOString(),
+			level,
+			step,
+			message,
+			context: context ?? null,
+		};
+		appendFileSync(this.logPath, `${JSON.stringify(entry)}\n`, "utf-8");
+	}
+
+	critical(step: string, message: string, context?: Record<string, unknown>): void {
+		this.log(LOG_LEVEL.CRITICAL, step, message, context || null);
+	}
+
+	error(step: string, message: string, context?: Record<string, unknown>): void {
+		this.log(LOG_LEVEL.ERROR, step, message, context || null);
+	}
+
+	warning(step: string, message: string, context?: Record<string, unknown>): void {
+		this.log(LOG_LEVEL.WARNING, step, message, context || null);
+	}
+
+	info(step: string, message: string, context?: Record<string, unknown>): void {
+		this.log(LOG_LEVEL.INFORMATION, step, message, context || null);
+	}
+}
+
+// --- Utility functions ---
+
+export function readLogs(workflowId: string, repoRoot?: string): LogEntry[] {
+	const logPath = getLogPath(workflowId, repoRoot);
+	if (!existsSync(logPath)) {
+		return [];
+	}
+
+	const content = readFileSync(logPath, "utf-8");
+	const entries: LogEntry[] = [];
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed) {
+			entries.push(JSON.parse(trimmed) as LogEntry);
+		}
+	}
+	return entries;
+}
+
+export function getLogPath(workflowId: string, repoRoot?: string): string {
+	const root = repoRoot ?? process.cwd();
+	return path.join(root, "agentic", "outputs", workflowId, "logs.ndjson");
+}