agentic-forge 0.0.0

package/src/steps/ralph-loop-step.ts

@@ -0,0 +1,186 @@
+/** Ralph loop step executor. */
+
+import type { ConsoleOutput } from "../console.js";
+import { extractSummary } from "../console.js";
+import type { WorkflowLogger } from "../logging/logger.js";
+import { WORKFLOW_STATUS, updateStepCompleted, updateStepFailed } from "../progress.js";
+import {
+	buildRalphSystemMessage,
+	createRalphState,
+	deactivateRalphState,
+	detectCompletionPromise,
+	loadRalphState,
+	updateRalphIteration,
+} from "../ralph-loop.js";
+import { runClaude } from "../runner.js";
+import type { StepDefinition, WorkflowProgress } from "../types.js";
+import {
+	type StepContext,
+	StepExecutor,
+	type StepResult,
+	buildTemplateContext,
+	resolveModel,
+} from "./base.js";
+
+export class RalphLoopStepExecutor extends StepExecutor {
+	async execute(
+		step: StepDefinition,
+		progress: WorkflowProgress,
+		context: StepContext,
+		logger: WorkflowLogger,
+		console: ConsoleOutput,
+	): Promise<StepResult> {
+		const promptTemplate = step.prompt ?? "";
+		const templateContext = buildTemplateContext(context);
+
+		let completionPromise = step.completionPromise ?? "COMPLETE";
+		if (context.renderer.hasVariables(completionPromise)) {
+			completionPromise = context.renderer.renderString(completionPromise, templateContext);
+		}
+
+		// Handle max_iterations which may be a template string or integer
+		const maxIterationsRaw = step.maxIterations;
+		let maxIterations: number;
+		if (typeof maxIterationsRaw === "string" && context.renderer.hasVariables(maxIterationsRaw)) {
+			maxIterations = Number.parseInt(
+				context.renderer.renderString(maxIterationsRaw, templateContext),
+				10,
+			);
+		} else {
+			maxIterations = maxIterationsRaw ? Number.parseInt(String(maxIterationsRaw), 10) : 5;
+		}
+
+		const timeout = (step.stepTimeoutMinutes ?? 30) * 60;
+		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;
+
+		logger.info(step.name, `Starting Ralph loop (max ${maxIterations} iterations)`);
+		console.info(`Ralph loop starting (max ${maxIterations} iterations)`);
+
+		const allOutputs: string[] = [];
+
+		// Check for existing ralph state to resume from
+		const existingState = loadRalphState(progress.workflowId, step.name, context.repoRoot);
+		let startIteration: number;
+		if (existingState?.active) {
+			startIteration = existingState.iteration;
+			logger.info(step.name, `Resuming Ralph loop from iteration ${startIteration}`);
+			console.info(`Resuming Ralph loop from iteration ${startIteration}`);
+		} else {
+			startIteration = 1;
+		}
+
+		for (let iteration = startIteration; iteration <= maxIterations; iteration++) {
+			logger.info(step.name, `Ralph loop iteration ${iteration}/${maxIterations}`);
+
+			// Render prompt with iteration context
+			const iterationContext = {
+				...templateContext,
+				iteration,
+				max_iterations: maxIterations,
+			};
+			let prompt: string;
+			if (context.renderer.hasVariables(promptTemplate)) {
+				prompt = context.renderer.renderString(promptTemplate, iterationContext);
+			} else {
+				prompt = promptTemplate;
+			}
+
+			// Create ralph state on first iteration
+			if (iteration === startIteration && !existingState?.active) {
+				createRalphState(
+					progress.workflowId,
+					step.name,
+					prompt,
+					maxIterations,
+					completionPromise,
+					context.repoRoot,
+				);
+			}
+
+			const systemMessage = buildRalphSystemMessage(iteration, maxIterations, completionPromise);
+			const fullPrompt = `${systemMessage}${prompt}`;
+
+			// Display iteration header BEFORE running Claude
+			console.ralphIterationStart(step.name, iteration, maxIterations);
+
+			const result = await runClaude({
+				prompt: fullPrompt,
+				cwd: context.repoRoot,
+				model: resolveModel(context, step.model),
+				timeout,
+				printOutput,
+				skipPermissions: bypassPermissions,
+				allowedTools,
+				console,
+				workflowId: context.workflowId,
+			});
+
+			if (!result.success) {
+				const errorSummary = result.stderr ? extractSummary(result.stderr) : "Unknown error";
+				logger.warning(step.name, `Iteration ${iteration} failed: ${result.stderr}`);
+				console.ralphIteration(step.name, iteration, maxIterations, `Failed: ${errorSummary}`);
+				if (iteration < maxIterations) {
+					updateRalphIteration(progress.workflowId, step.name, context.repoRoot);
+					continue;
+				}
+				deactivateRalphState(progress.workflowId, step.name, context.repoRoot);
+				const errorMsg = `Ralph loop failed after ${maxIterations} iterations`;
+				console.stepFailed(step.name, errorMsg);
+				updateStepFailed(progress, step.name, errorMsg);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				return { success: false, error: errorMsg };
+			}
+
+			allOutputs.push(result.stdout);
+
+			// Print iteration summary
+			const iterationSummary = extractSummary(result.stdout);
+			console.ralphIteration(step.name, iteration, maxIterations, iterationSummary);
+
+			const completionResult = detectCompletionPromise(result.stdout, completionPromise);
+
+			// Check for failure signal first
+			if (completionResult.isFailed) {
+				const errorMsg = `Ralph loop failed: ${completionResult.failureReason}`;
+				logger.error(step.name, errorMsg);
+				deactivateRalphState(progress.workflowId, step.name, context.repoRoot);
+				const combinedOutput = allOutputs.join("\n\n---\n\n");
+				console.stepFailed(step.name, errorMsg);
+				updateStepFailed(progress, step.name, errorMsg);
+				progress.status = WORKFLOW_STATUS.FAILED;
+				return { success: false, error: errorMsg, fullOutput: combinedOutput };
+			}
+
+			if (completionResult.isComplete && completionResult.promiseMatched) {
+				logger.info(step.name, `Ralph loop completed at iteration ${iteration}`);
+				deactivateRalphState(progress.workflowId, step.name, context.repoRoot);
+				const combinedOutput = allOutputs.join("\n\n---\n\n");
+				const outputSummary = `Completed in ${iteration} iterations`;
+				updateStepCompleted(progress, step.name, outputSummary, combinedOutput);
+				console.ralphComplete(step.name, iteration, maxIterations);
+				return { success: true, outputSummary, fullOutput: combinedOutput };
+			}
+
+			if (iteration < maxIterations) {
+				updateRalphIteration(progress.workflowId, step.name, context.repoRoot);
+			}
+		}
+
+		logger.warning(
+			step.name,
+			`Ralph loop reached max iterations (${maxIterations}) without completion`,
+		);
+		deactivateRalphState(progress.workflowId, step.name, context.repoRoot);
+		const combinedOutput = allOutputs.join("\n\n---\n\n");
+		const outputSummary = `Max iterations (${maxIterations}) reached without completion promise`;
+		updateStepCompleted(progress, step.name, outputSummary, combinedOutput);
+		console.ralphMaxIterations(step.name, maxIterations);
+		return { success: true, outputSummary, fullOutput: combinedOutput };
+	}
+}

package/src/steps/serial-step.ts

@@ -0,0 +1,84 @@
+/** Serial 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,
+} from "./base.js";
+
+export class SerialStepExecutor 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, "Serial 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" };
+		}
+
+		logger.info(step.name, `Starting serial execution of ${step.steps.length} steps`);
+		console.info(`Serial: executing ${step.steps.length} steps in sequence`);
+
+		let completedCount = 0;
+
+		for (const subStep of step.steps) {
+			try {
+				const result = await this.branchExecutor(subStep, progress, context, logger, console);
+
+				if (!result.success) {
+					logger.warning(
+						step.name,
+						`Serial block stopped at step '${subStep.name}' 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 };
+				}
+
+				completedCount++;
+
+				if (progress.status === WORKFLOW_STATUS.FAILED) {
+					logger.warning(
+						step.name,
+						`Serial block stopped at step '${subStep.name}' due to failure`,
+					);
+					break;
+				}
+			} catch (e) {
+				const errStr = e instanceof Error ? e.message : String(e);
+				logger.error(subStep.name, `Step failed in serial block: ${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 = `Completed ${completedCount}/${step.steps.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: "Serial execution failed" };
+	}
+}

package/src/templates/analysis/bug.md.j2

@@ -0,0 +1,35 @@
+# Bug Analysis Report
+
+Generated: {{ generated }}
+Scope: {{ scope }}
+
+## Summary
+
+Found {{ summary.total }} potential issues.
+
+| Severity | Count |
+|----------|-------|
+| Critical | {{ summary.critical }} |
+| Major | {{ summary.major }} |
+| Minor | {{ summary.minor }} |
+
+## Findings
+
+{% for finding in findings %}
+### {{ finding.id }}: {{ finding.title }}
+
+**Severity**: {{ finding.severity }}
+**Category**: {{ finding.category }}
+**File**: {{ finding.file }}:{{ finding.line }}
+
+{{ finding.description }}
+
+**Recommendation**: {{ finding.recommendation }}
+
+---
+
+{% endfor %}
+
+{% if not findings %}
+No potential bugs found.
+{% endif %}

package/src/templates/analysis/debt.md.j2

@@ -0,0 +1,38 @@
+# Technical Debt Analysis Report
+
+Generated: {{ generated }}
+Scope: {{ scope }}
+
+## Summary
+
+Found {{ summary.total }} technical debt items.
+
+| Priority | Count |
+|----------|-------|
+| High | {{ summary.high }} |
+| Medium | {{ summary.medium }} |
+| Low | {{ summary.low }} |
+
+## Findings
+
+{% for finding in findings %}
+### {{ finding.id }}: {{ finding.title }}
+
+**Priority**: {{ finding.priority }}
+**Category**: {{ finding.category }}
+**File**: {{ finding.file }}{% if finding.line %}:{{ finding.line }}{% endif %}
+
+{{ finding.description }}
+
+**Effort**: {{ finding.effort | default("Unknown") }}
+**Impact**: {{ finding.impact | default("Unknown") }}
+
+**Recommendation**: {{ finding.recommendation }}
+
+---
+
+{% endfor %}
+
+{% if not findings %}
+No technical debt issues found.
+{% endif %}

package/src/templates/analysis/doc.md.j2

@@ -0,0 +1,45 @@
+# Documentation Analysis Report
+
+Generated: {{ generated }}
+Scope: {{ scope }}
+
+## Summary
+
+Found {{ summary.total }} documentation issues.
+
+| Priority | Count |
+|----------|-------|
+| High | {{ summary.high }} |
+| Medium | {{ summary.medium }} |
+| Low | {{ summary.low }} |
+
+## Findings
+
+{% for finding in findings %}
+### {{ finding.id }}: {{ finding.title }}
+
+**Priority**: {{ finding.priority }}
+**Category**: {{ finding.category }}
+**File**: {{ finding.file }}{% if finding.line %}:{{ finding.line }}{% endif %}
+
+{{ finding.description }}
+
+**Recommendation**: {{ finding.recommendation }}
+
+---
+
+{% endfor %}
+
+{% if not findings %}
+No documentation issues found.
+{% endif %}
+
+## Coverage Overview
+
+{% if coverage %}
+| Metric | Value |
+|--------|-------|
+| Files with docs | {{ coverage.files_documented }} / {{ coverage.files_total }} |
+| Functions documented | {{ coverage.functions_documented }} / {{ coverage.functions_total }} |
+| Classes documented | {{ coverage.classes_documented }} / {{ coverage.classes_total }} |
+{% endif %}

package/src/templates/analysis/security.md.j2

@@ -0,0 +1,35 @@
+# Security Analysis Report
+
+Generated: {{ generated }}
+Scope: {{ scope }}
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | {{ summary.critical }} |
+| Major | {{ summary.major }} |
+| Minor | {{ summary.minor }} |
+| **Total** | {{ summary.total }} |
+
+## Findings
+
+{% for finding in findings %}
+### {{ finding.id }}: {{ finding.title }}
+
+**Severity**: {{ finding.severity | upper }}
+**Category**: {{ finding.category }}
+**File**: {{ finding.file }}:{{ finding.line }}
+{% if finding.cwe %}**CWE**: {{ finding.cwe }}{% endif %}
+
+{{ finding.description }}
+
+**Recommendation**: {{ finding.recommendation }}
+
+---
+
+{% endfor %}
+
+{% if not findings %}
+No security issues found.
+{% endif %}

package/src/templates/analysis/style.md.j2

@@ -0,0 +1,44 @@
+# Style Analysis Report
+
+Generated: {{ generated }}
+Scope: {{ scope }}
+
+## Summary
+
+Found {{ summary.total }} style issues.
+
+| Severity | Count |
+|----------|-------|
+| Major | {{ summary.major }} |
+| Minor | {{ summary.minor }} |
+| Info | {{ summary.info }} |
+
+## Findings
+
+{% for finding in findings %}
+### {{ finding.id }}: {{ finding.title }}
+
+**Severity**: {{ finding.severity }}
+**Category**: {{ finding.category }}
+**File**: {{ finding.file }}:{{ finding.line }}
+
+{{ finding.description }}
+
+**Expected**: `{{ finding.expected }}`
+**Actual**: `{{ finding.actual }}`
+
+---
+
+{% endfor %}
+
+{% if not findings %}
+No style issues found.
+{% endif %}
+
+## Patterns Checked
+
+{% if patterns %}
+{% for pattern in patterns %}
+- [{% if pattern.passed %}x{% else %} {% endif %}] {{ pattern.name }}
+{% endfor %}
+{% endif %}

package/src/templates/analysis-summary.md.j2

@@ -0,0 +1,58 @@
+# Analysis Summary
+
+Generated: {{ workflow.completed_at }}
+Workflow: {{ workflow.name }}
+
+## Overview
+
+This report summarizes the results of running {{ analysis_steps | length }} analysis types on the codebase.
+
+| Analysis | Status | Summary |
+|----------|--------|---------|
+{%- for step_name, step in analysis_steps.items() %}
+| {{ step_name | replace('analyze-', '') | title }} | {{ step.status }} | {{ step.output_summary | default('-') }} |
+{%- endfor %}
+
+## Analysis Details
+{% for step_name, step in analysis_steps.items() %}
+### {{ step_name | replace('analyze-', '') | title }} Analysis
+
+**Status**: {{ step.status }}
+{%- if step.output_summary %}
+
+**Summary**: {{ step.output_summary }}
+{%- endif %}
+
+Output: `agentic/analysis/{{ step_name | replace('analyze-', '') }}.md`
+
+---
+{%- endfor %}
+{% if inputs.autofix and inputs.autofix != 'none' %}
+
+## Autofix Summary
+
+Autofix was enabled at severity level: **{{ inputs.autofix }}**
+
+| Type | Fix Status |
+|------|------------|
+{%- for step_name, step in fix_steps.items() %}
+| {{ step_name | replace('fix-', '') | replace('apply-', '') | replace('-fixes', '') | title }} | {{ step.status }} |
+{%- endfor %}
+{% endif %}
+
+## Files Changed
+
+{% if files_changed -%}
+{% for file in files_changed %}
+- `{{ file }}`
+{% endfor %}
+{%- else -%}
+No files were changed during this analysis.
+{%- endif %}
+{% if pull_requests %}
+
+## Pull Requests
+{% for pr in pull_requests %}
+- [#{{ pr.number }}]({{ pr.url }})
+{%- endfor %}
+{% endif %}

package/src/templates/checkpoint.md.j2

@@ -0,0 +1,27 @@
+---
+checkpoint_id: {{ checkpoint_id }}
+step: {{ step }}
+created: {{ created }}
+workflow_id: {{ workflow_id }}
+status: {{ status }}
+---
+
+## Context
+
+{{ context }}
+
+## Progress
+
+{{ progress }}
+
+{% if notes %}
+## Notes for Next Session
+
+{{ notes }}
+{% endif %}
+
+{% if issues %}
+## Issues Discovered
+
+{{ issues }}
+{% endif %}

package/src/templates/implementation-report.md.j2

@@ -0,0 +1,81 @@
+# Implementation Report
+
+Generated: {{ workflow.completed_at }}
+Workflow: {{ workflow.name }}
+ID: {{ workflow.id | default(workflow.workflow_id, true) }}
+
+## Summary
+
+**Status**: {{ workflow.status | default('completed') }}
+**Started**: {{ workflow.started_at }}
+**Completed**: {{ workflow.completed_at }}
+
+## Task
+
+{% if inputs.task %}
+{{ inputs.task }}
+{% elif inputs.feature_name %}
+Feature: {{ inputs.feature_name }}
+{% elif inputs.description %}
+{{ inputs.description }}
+{% else %}
+_No task description provided_
+{% endif %}
+
+## Steps Completed
+
+| Step | Status | Summary |
+|------|--------|---------|
+{% for step_name, step in steps.items() %}
+| {{ step_name }} | {{ step.status }} | {{ step.output_summary | default('-') | truncate(50) }} |
+{% endfor %}
+
+## Files Changed
+
+{% if files_changed %}
+{% for file in files_changed %}
+- `{{ file }}`
+{% endfor %}
+{% else %}
+No files were changed during this workflow.
+{% endif %}
+
+{% if branches %}
+## Branches
+
+{% for branch in branches %}
+- `{{ branch }}`
+{% endfor %}
+{% endif %}
+
+{% if pull_requests %}
+## Pull Requests
+
+{% for pr in pull_requests %}
+- [#{{ pr.number }}]({{ pr.url }})
+{% endfor %}
+{% endif %}
+
+## Detailed Results
+
+{% for step_name, step in steps.items() %}
+### {{ step_name }}
+
+**Status**: {{ step.status }}
+{% if step.started_at %}**Started**: {{ step.started_at }}{% endif %}
+{% if step.completed_at %}**Completed**: {{ step.completed_at }}{% endif %}
+
+{% if step.output_summary %}
+{{ step.output_summary }}
+{% endif %}
+
+{% if step.files_changed %}
+Files changed:
+{% for file in step.files_changed %}
+- `{{ file }}`
+{% endfor %}
+{% endif %}
+
+---
+
+{% endfor %}

package/src/templates/memory.md.j2

@@ -0,0 +1,16 @@
+---
+id: {{ id }}
+created: {{ created }}
+category: {{ category }}
+tags: {{ tags | tojson }}
+{% if source %}
+source:
+  workflow: {{ source.workflow }}
+  step: {{ source.step }}
+{% endif %}
+relevance: {{ relevance }}
+---
+
+# {{ title }}
+
+{{ content }}

package/src/templates/plan-bug.md.j2

@@ -0,0 +1,42 @@
+# Bug Fix Plan: {{ title }}
+
+Created: {{ created }}
+Status: {{ status }}
+Workflow: {{ workflow_id }}
+
+## Bug Summary
+
+{{ summary }}
+
+## Root Cause Analysis
+
+{{ root_cause }}
+
+## Progress Tracker
+
+{% for milestone in milestones %}
+### Milestone {{ milestone.id }}: {{ milestone.title }}
+
+{% for task in milestone.tasks %}
+- [{% if task.completed %}x{% else %} {% endif %}] {{ task.id }}: {{ task.description }}
+{% endfor %}
+
+{% endfor %}
+
+## Affected Files
+
+{% for file in affected_files %}
+- {{ file }}
+{% endfor %}
+
+## Test Plan
+
+{% for test in test_plan %}
+- {{ test }}
+{% endfor %}
+
+## Verification Steps
+
+{% for step in verification_steps %}
+1. {{ step }}
+{% endfor %}