chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,476 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { STAGE_SEQUENCE, STAGE_SPECS } from './constants.js';
|
||||
import { determineBriefClass, stagesForClass } from './brief-classifier.js';
|
||||
import { ForgeCapabilityError, providerErrorCode } from './errors.js';
|
||||
import {
|
||||
blockedGateResults,
|
||||
evaluateStageGates,
|
||||
isCapabilityGate,
|
||||
simulatedGateResults,
|
||||
waitingGateResults,
|
||||
} from './outcomes.js';
|
||||
import { mapStageToTask } from './stage-adapter.js';
|
||||
import { createSimulatedExecutor } from './simulated-executor.js';
|
||||
import type {
|
||||
ForgeTask,
|
||||
ForgeTaskResult,
|
||||
PipelineOptions,
|
||||
PipelineResult,
|
||||
RunManifest,
|
||||
RunMode,
|
||||
StageStatus,
|
||||
TaskExecutor,
|
||||
} from './types.js';
|
||||
|
||||
/** Reason stamped on stages that complete under explicit simulation. */
|
||||
const SIMULATED_STAGE_REASON =
|
||||
'simulated execution (--simulate): stage was not executed by a real executor';
|
||||
|
||||
/**
|
||||
* Generate a timestamp-based run ID.
|
||||
*/
|
||||
export function generateRunId(): string {
|
||||
const now = new Date();
|
||||
const pad = (n: number, w = 2) => String(n).padStart(w, '0');
|
||||
return [
|
||||
now.getUTCFullYear(),
|
||||
pad(now.getUTCMonth() + 1),
|
||||
pad(now.getUTCDate()),
|
||||
'-',
|
||||
pad(now.getUTCHours()),
|
||||
pad(now.getUTCMinutes()),
|
||||
pad(now.getUTCSeconds()),
|
||||
].join('');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the ISO timestamp for now.
|
||||
*/
|
||||
function nowISO(): string {
|
||||
return new Date().toISOString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Create and persist a run manifest.
|
||||
*/
|
||||
function createManifest(opts: {
|
||||
runId: string;
|
||||
briefPath: string;
|
||||
codebase: string;
|
||||
briefClass: RunManifest['briefClass'];
|
||||
classSource: RunManifest['classSource'];
|
||||
forceBoard: boolean;
|
||||
mode: RunMode;
|
||||
runDir: string;
|
||||
}): RunManifest {
|
||||
const ts = nowISO();
|
||||
const manifest: RunManifest = {
|
||||
runId: opts.runId,
|
||||
brief: opts.briefPath,
|
||||
codebase: opts.codebase,
|
||||
briefClass: opts.briefClass,
|
||||
classSource: opts.classSource,
|
||||
forceBoard: opts.forceBoard,
|
||||
mode: opts.mode,
|
||||
createdAt: ts,
|
||||
updatedAt: ts,
|
||||
currentStage: '',
|
||||
status: 'in_progress',
|
||||
stages: {},
|
||||
};
|
||||
saveManifest(opts.runDir, manifest);
|
||||
return manifest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Save a manifest to disk.
|
||||
*/
|
||||
export function saveManifest(runDir: string, manifest: RunManifest): void {
|
||||
manifest.updatedAt = nowISO();
|
||||
const manifestPath = path.join(runDir, 'manifest.json');
|
||||
fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
|
||||
fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a manifest from disk.
|
||||
*/
|
||||
export function loadManifest(runDir: string): RunManifest {
|
||||
const manifestPath = path.join(runDir, 'manifest.json');
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error(`manifest.json not found: ${manifestPath}`);
|
||||
}
|
||||
return JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as RunManifest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Select and validate stages, optionally skipping to a specific stage.
|
||||
*/
|
||||
export function selectStages(stages?: string[], skipTo?: string): string[] {
|
||||
const selected = stages ?? [...STAGE_SEQUENCE];
|
||||
|
||||
const unknown = selected.filter((s) => !STAGE_SEQUENCE.includes(s));
|
||||
if (unknown.length > 0) {
|
||||
throw new Error(`Unknown Forge stages requested: ${unknown.join(', ')}`);
|
||||
}
|
||||
|
||||
if (!skipTo) return selected;
|
||||
|
||||
if (!selected.includes(skipTo)) {
|
||||
throw new Error(`skip_to stage '${skipTo}' is not present in the selected stage list`);
|
||||
}
|
||||
const skipIndex = selected.indexOf(skipTo);
|
||||
return selected.slice(skipIndex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fail closed when the required executor capability is missing (SDLC-D-035).
|
||||
*/
|
||||
function requireExecutor(executor: TaskExecutor | undefined, simulate: boolean): TaskExecutor {
|
||||
if (executor) return executor;
|
||||
if (simulate) return createSimulatedExecutor({ log: false });
|
||||
throw new ForgeCapabilityError(
|
||||
'FORGE_NO_EXECUTOR',
|
||||
'task-executor',
|
||||
'no task executor is wired; refusing to run the pipeline with a stub executor (fail closed). ' +
|
||||
'Pass --simulate to opt into explicitly simulated execution.',
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-flight a stage's gates in normal mode (fail closed, SDLC-D-035).
|
||||
*
|
||||
* - authority gates: record a typed `waiting-for-authority` stage result and
|
||||
* raise FORGE_AUTHORITY_REQUIRED — approval-based gates never pass vacuously.
|
||||
* - provider gates: record a typed `blocked` stage result and raise the typed
|
||||
* capability error for the missing provider.
|
||||
*
|
||||
* Returns the stage status to record when the pre-flight blocks, or undefined
|
||||
* when the stage may proceed.
|
||||
*/
|
||||
function preflightStageGates(
|
||||
stageName: string,
|
||||
manifest: RunManifest,
|
||||
): { status: StageStatus; error: ForgeCapabilityError } | undefined {
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
for (const gate of spec.qualityGates) {
|
||||
if (!isCapabilityGate(gate)) continue;
|
||||
|
||||
const startedAt = manifest.stages[stageName]?.startedAt;
|
||||
const completedAt = nowISO();
|
||||
|
||||
if (gate.kind === 'authority') {
|
||||
const reason = `gate '${gate.capability}' requires authority sign-off; no mechanical implementation exists (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'waiting-for-authority',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: waitingGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
'FORGE_AUTHORITY_REQUIRED',
|
||||
gate.capability,
|
||||
`stage '${stageName}' is blocked on authority gate '${gate.capability}': ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously. Record the approval out-of-band ' +
|
||||
'or run with --simulate for explicitly simulated execution.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
const reason = `gate '${gate.capability}' requires provider '${gate.capability}' and none is wired (${gate.reason})`;
|
||||
return {
|
||||
status: {
|
||||
status: 'blocked',
|
||||
reason,
|
||||
startedAt,
|
||||
completedAt,
|
||||
gateResults: blockedGateResults(spec.qualityGates, reason),
|
||||
},
|
||||
error: new ForgeCapabilityError(
|
||||
providerErrorCode(gate.capability),
|
||||
gate.capability,
|
||||
`stage '${stageName}' requires provider '${gate.capability}' which is not wired: ${gate.reason}. ` +
|
||||
'The pipeline fails closed instead of passing vacuously.',
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the given stage tasks sequentially, updating the manifest.
|
||||
*
|
||||
* Normal mode requires a real executor and evaluates every declared command
|
||||
* gate through the typed outcome model; any non-verified result fails closed.
|
||||
* Simulate mode types every stage and gate result as `simulated`.
|
||||
*/
|
||||
async function executeStages(opts: {
|
||||
manifest: RunManifest;
|
||||
runDir: string;
|
||||
tasks: ForgeTask[];
|
||||
stageNames: string[];
|
||||
executor: TaskExecutor;
|
||||
simulate: boolean;
|
||||
}): Promise<void> {
|
||||
const { manifest, runDir, tasks, stageNames, executor, simulate } = opts;
|
||||
|
||||
for (let i = 0; i < tasks.length; i++) {
|
||||
const task = tasks[i]!;
|
||||
const stageName = stageNames[i]!;
|
||||
const spec = STAGE_SPECS[stageName];
|
||||
if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
|
||||
|
||||
// Update manifest: stage in progress
|
||||
manifest.currentStage = stageName;
|
||||
manifest.stages[stageName] = {
|
||||
status: 'in_progress',
|
||||
startedAt: nowISO(),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
// Fail-closed pre-flight (normal mode only): authority/provider gates have
|
||||
// no mechanical implementation and must never pass vacuously.
|
||||
if (!simulate) {
|
||||
const blocked = preflightStageGates(stageName, manifest);
|
||||
if (blocked) {
|
||||
manifest.stages[stageName] = blocked.status;
|
||||
manifest.status =
|
||||
blocked.status.status === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw blocked.error;
|
||||
}
|
||||
}
|
||||
|
||||
let result: ForgeTaskResult;
|
||||
try {
|
||||
await executor.submitTask(task);
|
||||
result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
|
||||
} catch (error) {
|
||||
// Process errors (including timeouts) map to the fail-closed `error` outcome.
|
||||
const reason = error instanceof Error ? error.message : String(error);
|
||||
manifest.stages[stageName] = {
|
||||
status: 'error',
|
||||
reason: `executor error: ${reason}`,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: [],
|
||||
};
|
||||
manifest.status = 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw error instanceof Error ? error : new Error(reason);
|
||||
}
|
||||
|
||||
if (simulate) {
|
||||
manifest.stages[stageName] = {
|
||||
status: 'simulated',
|
||||
reason: SIMULATED_STAGE_REASON,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: simulatedGateResults(spec.qualityGates),
|
||||
};
|
||||
saveManifest(runDir, manifest);
|
||||
continue;
|
||||
}
|
||||
|
||||
const evaluation = evaluateStageGates(stageName, spec.qualityGates, result);
|
||||
manifest.stages[stageName] = {
|
||||
status: evaluation.outcome,
|
||||
reason: evaluation.reason,
|
||||
startedAt: manifest.stages[stageName]?.startedAt,
|
||||
completedAt: nowISO(),
|
||||
gateResults: evaluation.gateResults,
|
||||
};
|
||||
|
||||
if (evaluation.outcome !== 'passed') {
|
||||
manifest.status =
|
||||
evaluation.outcome === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
|
||||
saveManifest(runDir, manifest);
|
||||
throw new Error(`Stage ${stageName} ${evaluation.outcome}: ${evaluation.reason}`);
|
||||
}
|
||||
|
||||
saveManifest(runDir, manifest);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the Forge pipeline.
|
||||
*
|
||||
* 1. Fail closed unless a real executor is wired or simulation is explicit
|
||||
* 2. Classify the brief
|
||||
* 3. Generate a run ID and create run directory
|
||||
* 4. Map stages to tasks and submit to TaskExecutor
|
||||
* 5. Track manifest with typed stage outcomes
|
||||
* 6. Return pipeline result
|
||||
*/
|
||||
export async function runPipeline(
|
||||
briefPath: string,
|
||||
projectRoot: string,
|
||||
options: PipelineOptions,
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options.simulate ?? false;
|
||||
const executor = requireExecutor(options.executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const resolvedRoot = path.resolve(projectRoot);
|
||||
const resolvedBrief = path.resolve(briefPath);
|
||||
const briefContent = fs.readFileSync(resolvedBrief, 'utf-8');
|
||||
|
||||
// Classify brief
|
||||
const { briefClass, classSource } = determineBriefClass(briefContent, options.briefClass);
|
||||
|
||||
// Determine stages
|
||||
const classStages = options.stages ?? stagesForClass(briefClass, options.forceBoard);
|
||||
const selectedStages = selectStages(classStages, options.skipTo);
|
||||
|
||||
// Create run directory
|
||||
const runId = generateRunId();
|
||||
const runDir = path.join(resolvedRoot, '.forge', 'runs', runId);
|
||||
fs.mkdirSync(runDir, { recursive: true });
|
||||
|
||||
// Create manifest
|
||||
const manifest = createManifest({
|
||||
runId,
|
||||
briefPath: resolvedBrief,
|
||||
codebase: options.codebase ?? '',
|
||||
briefClass,
|
||||
classSource,
|
||||
forceBoard: options.forceBoard ?? false,
|
||||
mode,
|
||||
runDir,
|
||||
});
|
||||
|
||||
// Map stages to tasks
|
||||
const tasks: ForgeTask[] = [];
|
||||
for (let i = 0; i < selectedStages.length; i++) {
|
||||
const stageName = selectedStages[i]!;
|
||||
const task = mapStageToTask({
|
||||
stageName,
|
||||
briefContent,
|
||||
projectRoot: resolvedRoot,
|
||||
runId,
|
||||
runDir,
|
||||
});
|
||||
|
||||
// Override dependency chain for selected (possibly filtered) stages
|
||||
if (i > 0) {
|
||||
task.dependsOn = [tasks[i - 1]!.id];
|
||||
} else {
|
||||
delete task.dependsOn;
|
||||
}
|
||||
|
||||
tasks.push(task);
|
||||
}
|
||||
|
||||
// Execute stages
|
||||
await executeStages({ manifest, runDir, tasks, stageNames: selectedStages, executor, simulate });
|
||||
|
||||
// All stages reached a terminal state for this mode
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
runId,
|
||||
briefPath: resolvedBrief,
|
||||
projectRoot: resolvedRoot,
|
||||
runDir,
|
||||
taskIds: tasks.map((t) => t.id),
|
||||
stages: selectedStages,
|
||||
manifest,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Resume a pipeline from the last non-passed stage.
|
||||
*/
|
||||
export async function resumePipeline(
|
||||
runDir: string,
|
||||
executor?: TaskExecutor,
|
||||
options?: { simulate?: boolean },
|
||||
): Promise<PipelineResult> {
|
||||
const simulate = options?.simulate ?? false;
|
||||
const wiredExecutor = requireExecutor(executor, simulate);
|
||||
const mode: RunMode = simulate ? 'simulated' : 'normal';
|
||||
|
||||
const manifest = loadManifest(runDir);
|
||||
const resolvedRoot = path.dirname(path.dirname(path.dirname(runDir))); // .forge/runs/{id} → project root
|
||||
|
||||
const briefContent = fs.readFileSync(manifest.brief, 'utf-8');
|
||||
const allStages = stagesForClass(manifest.briefClass, manifest.forceBoard);
|
||||
|
||||
manifest.mode = mode;
|
||||
|
||||
// Find first non-satisfying stage (only a verified `passed` counts as done;
|
||||
// simulated and waiting-for-authority stages are re-run).
|
||||
const resumeFrom = allStages.find((s) => manifest.stages[s]?.status !== 'passed');
|
||||
if (!resumeFrom) {
|
||||
manifest.status = mode === 'simulated' ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
return {
|
||||
runId: manifest.runId,
|
||||
briefPath: manifest.brief,
|
||||
projectRoot: resolvedRoot,
|
||||
runDir,
|
||||
taskIds: [],
|
||||
stages: allStages,
|
||||
manifest,
|
||||
};
|
||||
}
|
||||
|
||||
const remainingStages = selectStages(allStages, resumeFrom);
|
||||
manifest.status = 'in_progress';
|
||||
|
||||
const tasks: ForgeTask[] = [];
|
||||
for (let i = 0; i < remainingStages.length; i++) {
|
||||
const stageName = remainingStages[i]!;
|
||||
const task = mapStageToTask({
|
||||
stageName,
|
||||
briefContent,
|
||||
projectRoot: resolvedRoot,
|
||||
runId: manifest.runId,
|
||||
runDir,
|
||||
});
|
||||
|
||||
if (i > 0) {
|
||||
task.dependsOn = [tasks[i - 1]!.id];
|
||||
} else {
|
||||
delete task.dependsOn;
|
||||
}
|
||||
tasks.push(task);
|
||||
}
|
||||
|
||||
await executeStages({
|
||||
manifest,
|
||||
runDir,
|
||||
tasks,
|
||||
stageNames: remainingStages,
|
||||
executor: wiredExecutor,
|
||||
simulate,
|
||||
});
|
||||
|
||||
manifest.status = simulate ? 'simulated' : 'completed';
|
||||
saveManifest(runDir, manifest);
|
||||
|
||||
return {
|
||||
runId: manifest.runId,
|
||||
briefPath: manifest.brief,
|
||||
projectRoot: resolvedRoot,
|
||||
runDir,
|
||||
taskIds: tasks.map((t) => t.id),
|
||||
stages: remainingStages,
|
||||
manifest,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the status of a pipeline run.
|
||||
*/
|
||||
export function getPipelineStatus(runDir: string): RunManifest {
|
||||
return loadManifest(runDir);
|
||||
}
|
||||
Reference in New Issue
Block a user