agentic-forge 0.0.0

package/src/parser.ts

@@ -0,0 +1,225 @@
+/** YAML workflow parser. */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import type {
+	GitSettings,
+	OutputDefinition,
+	StepDefinition,
+	StepGitSettings,
+	StepType,
+	Variable,
+	WorkflowDefinition,
+	WorkflowSettings,
+} from "./types.js";
+import { VALID_STEP_TYPES } from "./types.js";
+
+export class WorkflowParseError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "WorkflowParseError";
+	}
+}
+
+export class WorkflowParser {
+	basePath: string;
+
+	constructor(basePath?: string) {
+		this.basePath = basePath ?? process.cwd();
+	}
+
+	parseFile(filePath: string): WorkflowDefinition {
+		if (!existsSync(filePath)) {
+			throw new WorkflowParseError(`Workflow file not found: ${filePath}`);
+		}
+
+		let data: unknown;
+		try {
+			const content = readFileSync(filePath, "utf-8");
+			data = yaml.load(content);
+		} catch (e) {
+			if (e instanceof WorkflowParseError) throw e;
+			throw new WorkflowParseError(`Invalid YAML: ${e}`);
+		}
+
+		this.basePath = path.dirname(filePath);
+		return this.parseDict(data);
+	}
+
+	parseString(content: string): WorkflowDefinition {
+		let data: unknown;
+		try {
+			data = yaml.load(content);
+		} catch (e) {
+			throw new WorkflowParseError(`Invalid YAML: ${e}`);
+		}
+		return this.parseDict(data);
+	}
+
+	parseDict(data: unknown): WorkflowDefinition {
+		if (!data || typeof data !== "object" || Array.isArray(data)) {
+			throw new WorkflowParseError("Workflow must be a dictionary");
+		}
+
+		const dict = data as Record<string, unknown>;
+		const name = this.required(dict, "name") as string;
+		const version = (dict.version as string) ?? "1.0";
+		const description = (dict.description as string) ?? "";
+
+		const settings = this.parseSettings((dict.settings as Record<string, unknown>) ?? {});
+		const variables = ((dict.variables as unknown[]) ?? []).map((v) =>
+			this.parseVariable(v as Record<string, unknown>),
+		);
+		const steps = ((dict.steps as unknown[]) ?? []).map((s) =>
+			this.parseStep(s as Record<string, unknown>),
+		);
+		const outputs = ((dict.outputs as unknown[]) ?? []).map((o) =>
+			this.parseOutput(o as Record<string, unknown>),
+		);
+
+		return { name, version, description, settings, variables, steps, outputs };
+	}
+
+	private required(data: Record<string, unknown>, key: string): unknown {
+		if (!(key in data)) {
+			throw new WorkflowParseError(`Missing required field: ${key}`);
+		}
+		return data[key];
+	}
+
+	private parseSettings(data: Record<string, unknown>): WorkflowSettings {
+		const gitData = (data.git as Record<string, unknown>) ?? {};
+		const git: GitSettings = {
+			enabled: (gitData.enabled as boolean) ?? false,
+			worktree: (gitData.worktree as boolean) ?? false,
+			autoCommit: (gitData["auto-commit"] as boolean) ?? true,
+			autoPr: (gitData["auto-pr"] as boolean) ?? true,
+			branchPrefix: (gitData["branch-prefix"] as string) ?? "agentic",
+		};
+		return {
+			maxRetry: (data["max-retry"] as number) ?? 3,
+			timeoutMinutes: (data["timeout-minutes"] as number) ?? 60,
+			trackProgress: (data["track-progress"] as boolean) ?? true,
+			autofix: (data.autofix as string) ?? "none",
+			terminalOutput: (data["terminal-output"] as string) ?? "base",
+			bypassPermissions: (data["bypass-permissions"] as boolean) ?? false,
+			strictMode: (data["strict-mode"] as boolean) ?? false,
+			model: (data.model as string) ?? null,
+			requiredTools: (data["required-tools"] as string[]) ?? [],
+			git,
+		};
+	}
+
+	private parseVariable(data: Record<string, unknown>): Variable {
+		return {
+			name: this.required(data, "name") as string,
+			type: (data.type as string) ?? "string",
+			required: (data.required as boolean) ?? true,
+			default: data.default,
+			description: (data.description as string) ?? "",
+		};
+	}
+
+	private parseStep(data: Record<string, unknown>, parentIsParallel = false): StepDefinition {
+		const name = this.required(data, "name") as string;
+		const typeStr = this.required(data, "type") as string;
+
+		if (!VALID_STEP_TYPES.includes(typeStr as StepType)) {
+			throw new WorkflowParseError(
+				`Invalid step type: ${typeStr}. Valid types: ${JSON.stringify(VALID_STEP_TYPES)}`,
+			);
+		}
+
+		const stepType = typeStr as StepType;
+
+		if (parentIsParallel && stepType === "parallel") {
+			throw new WorkflowParseError(
+				`Nested parallel steps are not allowed: '${name}' is a parallel step inside another parallel step`,
+			);
+		}
+
+		const step: StepDefinition = {
+			name,
+			type: stepType,
+			prompt: null,
+			agent: null,
+			steps: [],
+			mergeStrategy: "wait-all",
+			mergeMode: "independent",
+			condition: null,
+			thenSteps: [],
+			elseSteps: [],
+			maxIterations: 5,
+			completionPromise: null,
+			message: null,
+			pollingInterval: 15,
+			onTimeout: "abort",
+			model: null,
+			stepTimeoutMinutes: null,
+			stepMaxRetry: null,
+			onError: "retry",
+			checkpoint: false,
+			dependsOn: null,
+			git: null,
+		};
+
+		if (stepType === "prompt") {
+			step.prompt = (data.prompt as string) ?? null;
+			step.agent = (data.agent as string) ?? null;
+		} else if (stepType === "parallel") {
+			step.steps = ((data.steps as unknown[]) ?? []).map((s) =>
+				this.parseStep(s as Record<string, unknown>, true),
+			);
+			step.mergeStrategy = (data["merge-strategy"] as string) ?? "wait-all";
+			step.mergeMode = (data["merge-mode"] as string) ?? "independent";
+			const gitData = data.git as Record<string, unknown> | undefined;
+			if (gitData) {
+				step.git = {
+					worktree: (gitData.worktree as boolean) ?? false,
+					autoPr: (gitData["auto-pr"] as boolean) ?? false,
+					branchPrefix: (gitData["branch-prefix"] as string) ?? "agentic",
+				} satisfies StepGitSettings;
+			}
+		} else if (stepType === "serial") {
+			step.steps = ((data.steps as unknown[]) ?? []).map((s) =>
+				this.parseStep(s as Record<string, unknown>),
+			);
+		} else if (stepType === "conditional") {
+			step.condition = (data.condition as string) ?? null;
+			step.thenSteps = ((data.then as unknown[]) ?? []).map((s) =>
+				this.parseStep(s as Record<string, unknown>),
+			);
+			step.elseSteps = ((data.else as unknown[]) ?? []).map((s) =>
+				this.parseStep(s as Record<string, unknown>),
+			);
+		} else if (stepType === "ralph-loop") {
+			step.prompt = (data.prompt as string) ?? null;
+			step.maxIterations = (data["max-iterations"] as number) ?? 5;
+			step.completionPromise = (data["completion-promise"] as string) ?? null;
+		} else if (stepType === "wait-for-human") {
+			step.message = (data.message as string) ?? null;
+			step.pollingInterval = (data["polling-interval"] as number) ?? 15;
+			step.onTimeout = (data["on-timeout"] as string) ?? "abort";
+			step.stepTimeoutMinutes = (data["timeout-minutes"] as number) ?? 5;
+		}
+
+		step.model = (data.model as string) ?? null;
+		step.stepTimeoutMinutes = (data["timeout-minutes"] as number) ?? step.stepTimeoutMinutes;
+		step.stepMaxRetry = (data["max-retry"] as number) ?? null;
+		step.onError = (data["on-error"] as string) ?? "retry";
+		step.checkpoint = (data.checkpoint as boolean) ?? false;
+		step.dependsOn = (data["depends-on"] as string) ?? null;
+
+		return step;
+	}
+
+	private parseOutput(data: Record<string, unknown>): OutputDefinition {
+		return {
+			name: this.required(data, "name") as string,
+			template: this.required(data, "template") as string,
+			path: this.required(data, "path") as string,
+			when: (data.when as string) ?? "completed",
+		};
+	}
+}

package/src/progress.ts

@@ -0,0 +1,306 @@
+/** Workflow progress tracking. */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { lockSync } from "proper-lockfile";
+import type { ParallelBranch, StepProgress, WorkflowProgress } from "./types.js";
+
+// --- Constants ---
+
+export const WORKFLOW_STATUS = {
+	PENDING: "pending",
+	RUNNING: "running",
+	COMPLETED: "completed",
+	FAILED: "failed",
+	PAUSED: "paused",
+	CANCELED: "canceled",
+} as const;
+
+export const STEP_STATUS = {
+	PENDING: "pending",
+	RUNNING: "running",
+	COMPLETED: "completed",
+	FAILED: "failed",
+	SKIPPED: "skipped",
+} as const;
+
+// --- ID and path helpers ---
+
+export function generateWorkflowId(workflowName: string): string {
+	const now = new Date();
+	const pad = (n: number, len = 2) => String(n).padStart(len, "0");
+	const timestamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}-${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`;
+
+	let safeName = workflowName.toLowerCase().replace(/ /g, "-").replace(/_/g, "-");
+	safeName = safeName.replace(/[^a-z0-9-]/g, "");
+	return `${timestamp}-${safeName}`;
+}
+
+export function getProgressPath(workflowId: string, repoRoot?: string): string {
+	const root = repoRoot ?? process.cwd();
+	return path.join(root, "agentic", "outputs", workflowId, "progress.json");
+}
+
+// --- CRUD operations ---
+
+export function loadProgress(workflowId: string, repoRoot?: string): WorkflowProgress | null {
+	const progressPath = getProgressPath(workflowId, repoRoot);
+	if (!existsSync(progressPath)) {
+		return null;
+	}
+	const data = JSON.parse(readFileSync(progressPath, "utf-8"));
+	return dictToProgress(data);
+}
+
+export function saveProgress(progress: WorkflowProgress, repoRoot?: string): void {
+	const progressPath = getProgressPath(progress.workflowId, repoRoot);
+	const dir = path.dirname(progressPath);
+	mkdirSync(dir, { recursive: true });
+
+	// Ensure the file exists so proper-lockfile can resolve its path
+	if (!existsSync(progressPath)) {
+		writeFileSync(progressPath, "{}", "utf-8");
+	}
+
+	let release: (() => void) | undefined;
+	try {
+		release = lockSync(progressPath);
+		writeFileSync(progressPath, JSON.stringify(progressToDict(progress), null, 2), "utf-8");
+	} finally {
+		if (release) {
+			release();
+		}
+	}
+}
+
+export function createProgress(
+	workflowId: string,
+	workflowName: string,
+	stepNames: string[],
+	variables: Record<string, unknown>,
+	workflowFile = "",
+): WorkflowProgress {
+	return {
+		schemaVersion: "1.0",
+		workflowId,
+		workflowName,
+		status: WORKFLOW_STATUS.RUNNING,
+		startedAt: new Date().toISOString(),
+		completedAt: null,
+		currentStep: null,
+		completedSteps: [],
+		pendingSteps: [...stepNames],
+		runningSteps: [],
+		parallelBranches: [],
+		errors: [],
+		variables: { ...variables },
+		stepOutputs: {},
+		workflowFile,
+	};
+}
+
+// --- Step update functions ---
+
+export function updateStepStarted(progress: WorkflowProgress, stepName: string): void {
+	const pendingIdx = progress.pendingSteps.indexOf(stepName);
+	if (pendingIdx !== -1) {
+		progress.pendingSteps.splice(pendingIdx, 1);
+	}
+	if (!progress.runningSteps.includes(stepName)) {
+		progress.runningSteps.push(stepName);
+	}
+	progress.currentStep = {
+		name: stepName,
+		retry_count: 0,
+		started_at: new Date().toISOString(),
+	};
+}
+
+export function updateStepCompleted(
+	progress: WorkflowProgress,
+	stepName: string,
+	outputSummary = "",
+	output?: unknown,
+): void {
+	const runIdx = progress.runningSteps.indexOf(stepName);
+	if (runIdx !== -1) {
+		progress.runningSteps.splice(runIdx, 1);
+	}
+
+	let startedAt: string | null = null;
+	let retryCount = 0;
+	if (progress.currentStep) {
+		startedAt = (progress.currentStep.started_at as string) ?? null;
+		retryCount = (progress.currentStep.retry_count as number) ?? 0;
+	}
+
+	const step: StepProgress = {
+		name: stepName,
+		status: STEP_STATUS.COMPLETED,
+		startedAt,
+		completedAt: new Date().toISOString(),
+		retryCount,
+		outputSummary,
+		error: null,
+		humanInput: null,
+	};
+	progress.completedSteps.push(step);
+
+	if (output !== undefined) {
+		progress.stepOutputs[stepName] = output;
+	}
+
+	progress.currentStep = null;
+}
+
+export function updateStepFailed(
+	progress: WorkflowProgress,
+	stepName: string,
+	error: string,
+): void {
+	const runIdx = progress.runningSteps.indexOf(stepName);
+	if (runIdx !== -1) {
+		progress.runningSteps.splice(runIdx, 1);
+	}
+
+	let startedAt: string | null = null;
+	let retryCount = 0;
+	if (progress.currentStep) {
+		startedAt = (progress.currentStep.started_at as string) ?? null;
+		retryCount = (progress.currentStep.retry_count as number) ?? 0;
+	}
+
+	const step: StepProgress = {
+		name: stepName,
+		status: STEP_STATUS.FAILED,
+		startedAt,
+		completedAt: new Date().toISOString(),
+		retryCount,
+		error,
+		outputSummary: "",
+		humanInput: null,
+	};
+	progress.completedSteps.push(step);
+	progress.errors.push({ step: stepName, error });
+	progress.currentStep = null;
+}
+
+export function updateStepSkipped(progress: WorkflowProgress, stepName: string): void {
+	const pendingIdx = progress.pendingSteps.indexOf(stepName);
+	if (pendingIdx !== -1) {
+		progress.pendingSteps.splice(pendingIdx, 1);
+	}
+	const runIdx = progress.runningSteps.indexOf(stepName);
+	if (runIdx !== -1) {
+		progress.runningSteps.splice(runIdx, 1);
+	}
+
+	const step: StepProgress = {
+		name: stepName,
+		status: STEP_STATUS.SKIPPED,
+		startedAt: null,
+		completedAt: new Date().toISOString(),
+		retryCount: 0,
+		outputSummary: "",
+		error: null,
+		humanInput: null,
+	};
+	progress.completedSteps.push(step);
+	progress.currentStep = null;
+}
+
+export function prepareForResume(progress: WorkflowProgress): void {
+	if (progress.runningSteps.length > 0) {
+		progress.pendingSteps = [...progress.runningSteps, ...progress.pendingSteps];
+		progress.runningSteps = [];
+	}
+
+	if (progress.currentStep) {
+		const stepName = progress.currentStep.name as string | undefined;
+		if (stepName && !progress.pendingSteps.includes(stepName)) {
+			progress.pendingSteps.unshift(stepName);
+		}
+		progress.currentStep = null;
+	}
+
+	progress.status = WORKFLOW_STATUS.RUNNING;
+	progress.completedAt = null;
+}
+
+// --- Serialization helpers ---
+
+export function progressToDict(progress: WorkflowProgress): Record<string, unknown> {
+	return {
+		schema_version: progress.schemaVersion,
+		workflow_id: progress.workflowId,
+		workflow_name: progress.workflowName,
+		status: progress.status,
+		started_at: progress.startedAt,
+		completed_at: progress.completedAt,
+		current_step: progress.currentStep,
+		completed_steps: progress.completedSteps.map((s) => ({
+			name: s.name,
+			status: s.status,
+			started_at: s.startedAt,
+			completed_at: s.completedAt,
+			retry_count: s.retryCount,
+			output_summary: s.outputSummary,
+			error: s.error,
+			human_input: s.humanInput,
+		})),
+		pending_steps: progress.pendingSteps,
+		running_steps: progress.runningSteps,
+		parallel_branches: progress.parallelBranches.map((b) => ({
+			branch_id: b.branchId,
+			status: b.status,
+			worktree_path: b.worktreePath,
+			progress_file: b.progressFile,
+		})),
+		errors: progress.errors,
+		variables: progress.variables,
+		step_outputs: progress.stepOutputs,
+		workflow_file: progress.workflowFile,
+	};
+}
+
+export function dictToProgress(data: Record<string, unknown>): WorkflowProgress {
+	const completedSteps = ((data.completed_steps as Record<string, unknown>[]) ?? []).map(
+		(s): StepProgress => ({
+			name: (s.name as string) ?? "",
+			status: (s.status as string) ?? "pending",
+			startedAt: (s.started_at as string) ?? null,
+			completedAt: (s.completed_at as string) ?? null,
+			retryCount: (s.retry_count as number) ?? 0,
+			outputSummary: (s.output_summary as string) ?? "",
+			error: (s.error as string) ?? null,
+			humanInput: (s.human_input as string) ?? null,
+		}),
+	);
+
+	const parallelBranches = ((data.parallel_branches as Record<string, unknown>[]) ?? []).map(
+		(b): ParallelBranch => ({
+			branchId: (b.branch_id as string) ?? "",
+			status: (b.status as string) ?? "",
+			worktreePath: (b.worktree_path as string) ?? "",
+			progressFile: (b.progress_file as string) ?? "",
+		}),
+	);
+
+	return {
+		schemaVersion: (data.schema_version as string) ?? "1.0",
+		workflowId: (data.workflow_id as string) ?? "",
+		workflowName: (data.workflow_name as string) ?? "",
+		status: (data.status as string) ?? "pending",
+		startedAt: (data.started_at as string) ?? null,
+		completedAt: (data.completed_at as string) ?? null,
+		currentStep: (data.current_step as Record<string, unknown>) ?? null,
+		completedSteps,
+		pendingSteps: (data.pending_steps as string[]) ?? [],
+		runningSteps: (data.running_steps as string[]) ?? [],
+		parallelBranches,
+		errors: (data.errors as Record<string, unknown>[]) ?? [],
+		variables: (data.variables as Record<string, unknown>) ?? {},
+		stepOutputs: (data.step_outputs as Record<string, unknown>) ?? {},
+		workflowFile: (data.workflow_file as string) ?? "",
+	};
+}

package/src/prompts/agentic-system.md

@@ -0,0 +1,31 @@
+## Execution Context
+
+You are being executed in an agentic workflow without user interaction.
+
+**Constraints**:
+
+- You CANNOT ask user questions - make reasonable decisions autonomously
+- You CANNOT request additional permissions - if permissions are missing, end the session
+- You MUST complete the task or report failure with details
+
+## Required Output Format
+
+At the END of your session, you MUST output a JSON block. The block MUST contain these base keys:
+
+```json
+{
+  "sessionId": "<session-id-for-resume>",
+  "isSuccess": true|false,
+  "context": "2-5 sentence summary of what was done, any errors encountered, and important notes"
+}
+```
+
+**Base Keys** (REQUIRED in every output):
+
+- `sessionId`: The session ID for /resume capability
+- `isSuccess`: Boolean indicating if the task completed successfully
+- `context`: 2-5 sentence summary of what was done, errors if any, important notes
+
+**Additional Keys**: The prompt or command may require additional keys in the output JSON. Include any extra keys requested alongside the base keys.
+
+This JSON block is REQUIRED. Include it as the last thing in your output.