pipeline-sdk 0.1.0

package/src/core/cleanup.ts

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { CleanupHandler } from "../types";
+
+interface CleanupEntry {
+	stage: string;
+	handlers: CleanupHandler[];
+}
+
+interface CleanupResult {
+	stage: string;
+	script: string;
+	success: boolean;
+	error?: string;
+}
+
+export class CleanupManager {
+	private registry: CleanupEntry[] = [];
+
+	register(stage: string, handlers: CleanupHandler[]): void {
+		this.registry.push({ stage, handlers });
+	}
+
+	async runAll(workspaceRoot: string): Promise<CleanupResult[]> {
+		const results: CleanupResult[] = [];
+
+		// LIFO — reverse registration order
+		const reversed = [...this.registry].reverse();
+
+		for (const entry of reversed) {
+			for (const handler of entry.handlers) {
+				const result = await this.runHandler(entry.stage, handler, workspaceRoot);
+				results.push(result);
+			}
+		}
+
+		return results;
+	}
+
+	private runHandler(stage: string, handler: CleanupHandler, cwd: string): Promise<CleanupResult> {
+		return new Promise((resolve) => {
+			const child = spawn(handler.script, {
+				cwd,
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+
+			let stderr = "";
+			child.stderr?.on("data", (chunk: Buffer) => {
+				stderr += chunk.toString();
+			});
+
+			child.on("error", (err) => {
+				resolve({
+					stage,
+					script: handler.script,
+					success: false,
+					error: err.message,
+				});
+			});
+
+			child.on("close", (code) => {
+				if (code === 0) {
+					resolve({ stage, script: handler.script, success: true });
+				} else {
+					resolve({
+						stage,
+						script: handler.script,
+						success: false,
+						error: stderr.trim() || `exited with code ${code}`,
+					});
+				}
+			});
+		});
+	}
+}

package/src/core/evidence.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ArtifactRef, EvidenceRecord, GateResult } from "../types";
+
+export interface RecordInput {
+	stage_id: string;
+	pipeline_id: string;
+	duration_ms: number;
+	agent: { provider: string; model?: string; session_id?: string };
+	gates_passed: GateResult[];
+	artifacts: ArtifactRef[];
+	git: { tree_sha: string; branch?: string; files_changed?: number };
+}
+
+export interface VerificationResult {
+	valid: boolean;
+	recordCount: number;
+	errors: string[];
+}
+
+export class EvidenceStore {
+	private readonly dir: string;
+	private _head: string | null = null;
+
+	constructor(dir: string) {
+		this.dir = dir;
+	}
+
+	async record(input: RecordInput): Promise<EvidenceRecord> {
+		await mkdir(this.dir, { recursive: true });
+
+		const partial: Omit<EvidenceRecord, "evidence_hash"> = {
+			stage_id: input.stage_id,
+			pipeline_id: input.pipeline_id,
+			timestamp: new Date().toISOString(),
+			duration_ms: input.duration_ms,
+			agent: input.agent,
+			gates_passed: input.gates_passed,
+			artifacts: input.artifacts,
+			git: input.git,
+			previous_evidence_hash: this._head,
+		};
+
+		const evidence_hash = computeHash(partial);
+
+		const evidenceRecord: EvidenceRecord = { ...partial, evidence_hash };
+
+		const fileName = `${evidence_hash.replace(":", "-")}.json`;
+		await writeFile(join(this.dir, fileName), JSON.stringify(evidenceRecord, null, 2));
+
+		this._head = evidence_hash;
+		return evidenceRecord;
+	}
+
+	async verify(): Promise<VerificationResult> {
+		const errors: string[] = [];
+
+		let files: string[];
+		try {
+			files = (await readdir(this.dir)).filter((f) => f.endsWith(".json"));
+		} catch {
+			return { valid: true, recordCount: 0, errors: [] };
+		}
+
+		if (files.length === 0) {
+			return { valid: true, recordCount: 0, errors: [] };
+		}
+
+		const records: EvidenceRecord[] = [];
+		for (const file of files) {
+			const raw = await readFile(join(this.dir, file), "utf-8");
+			records.push(JSON.parse(raw) as EvidenceRecord);
+		}
+
+		// Sort topologically by following the chain: null previous_evidence_hash = genesis
+		const sorted: EvidenceRecord[] = [];
+		let current = records.find((r) => r.previous_evidence_hash === null);
+		while (current) {
+			sorted.push(current);
+			const next = records.find((r) => r.previous_evidence_hash === current?.evidence_hash);
+			current = next;
+		}
+		// If chain is broken or forked, fall back to original order for remaining records
+		if (sorted.length !== records.length) {
+			const inSorted = new Set(sorted.map((r) => r.evidence_hash));
+			for (const r of records) {
+				if (!inSorted.has(r.evidence_hash)) sorted.push(r);
+			}
+		}
+		records.length = 0;
+		records.push(...sorted);
+
+		for (let i = 0; i < records.length; i++) {
+			const rec = records[i];
+			const { evidence_hash, ...rest } = rec;
+
+			const recomputed = computeHash(rest);
+			if (recomputed !== evidence_hash) {
+				errors.push(`Record ${evidence_hash}: hash mismatch (expected ${recomputed})`);
+			}
+
+			if (i === 0) {
+				if (rec.previous_evidence_hash !== null) {
+					errors.push(
+						`Record ${evidence_hash}: first record should have null previous_evidence_hash`,
+					);
+				}
+			} else {
+				const expected = records[i - 1].evidence_hash;
+				if (rec.previous_evidence_hash !== expected) {
+					errors.push(
+						`Record ${evidence_hash}: previous_evidence_hash mismatch (expected ${expected}, got ${rec.previous_evidence_hash})`,
+					);
+				}
+			}
+		}
+
+		return {
+			valid: errors.length === 0,
+			recordCount: records.length,
+			errors,
+		};
+	}
+
+	get head(): string | null {
+		return this._head;
+	}
+
+	static async hashFile(filePath: string): Promise<string> {
+		const contents = await readFile(filePath);
+		return `sha256:${createHash("sha256").update(contents).digest("hex")}`;
+	}
+}
+
+function computeHash(record: Omit<EvidenceRecord, "evidence_hash">): string {
+	const sortedKeys = Object.keys(record).sort() as Array<keyof typeof record>;
+	const canonical: Record<string, unknown> = {};
+	for (const key of sortedKeys) {
+		canonical[key] = record[key];
+	}
+	const json = JSON.stringify(canonical);
+	return `sha256:${createHash("sha256").update(json).digest("hex")}`;
+}

package/src/core/gate-runner.ts

@@ -0,0 +1,109 @@
+import type { GateInput, GateResult, GateVerdict } from "../types";
+
+export type GateEvaluator = (input: GateInput) => Promise<GateVerdict>;
+
+export interface GateRunnerOptions {
+	failFast?: boolean;
+	timeoutMs?: number;
+}
+
+export interface GateRunResult {
+	passed: boolean;
+	results: Array<GateResult & { status: string; message: string }>;
+	firstFailure?: GateResult & { status: string; message: string };
+	duration_ms: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+export class GateRunner {
+	private readonly evaluators = new Map<string, GateEvaluator>();
+	private readonly failFast: boolean;
+	private readonly timeoutMs: number;
+
+	constructor(options?: GateRunnerOptions) {
+		this.failFast = options?.failFast ?? false;
+		this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+
+	register(name: string, evaluator: GateEvaluator): void {
+		this.evaluators.set(name, evaluator);
+	}
+
+	async evaluateAll(gateNames: string[], input: GateInput): Promise<GateRunResult> {
+		const started = Date.now();
+		const results: Array<GateResult & { status: string; message: string }> = [];
+		let firstFailure: (GateResult & { status: string; message: string }) | undefined;
+
+		for (const gateName of gateNames) {
+			const evaluator = this.evaluators.get(gateName);
+
+			if (!evaluator) {
+				const entry: GateResult & { status: string; message: string } = {
+					gate: gateName,
+					exit_code: 1,
+					duration_ms: 0,
+					status: "fail",
+					message: `Gate "${gateName}" is not registered`,
+				};
+				results.push(entry);
+				if (!firstFailure) firstFailure = entry;
+				if (this.failFast) break;
+				continue;
+			}
+
+			const gateStart = Date.now();
+
+			let verdict: GateVerdict;
+			try {
+				verdict = await Promise.race([
+					evaluator({ ...input, gate_id: gateName }),
+					new Promise<never>((_, reject) =>
+						setTimeout(
+							() => reject(new Error(`Gate "${gateName}" timed out after ${this.timeoutMs}ms`)),
+							this.timeoutMs,
+						),
+					),
+				]);
+			} catch (err: unknown) {
+				const message = err instanceof Error ? err.message : "Unknown error";
+				const entry: GateResult & { status: string; message: string } = {
+					gate: gateName,
+					exit_code: 1,
+					duration_ms: Date.now() - gateStart,
+					status: "fail",
+					message,
+				};
+				results.push(entry);
+				if (!firstFailure) firstFailure = entry;
+				if (this.failFast) break;
+				continue;
+			}
+
+			const isFail = verdict.status === "fail";
+			const entry: GateResult & { status: string; message: string } = {
+				gate: gateName,
+				exit_code: isFail ? 1 : 0,
+				duration_ms: Date.now() - gateStart,
+				status: verdict.status,
+				message: verdict.message,
+				...(verdict.evidence
+					? { evidence: { type: verdict.evidence.type, hash: verdict.evidence.summary } }
+					: {}),
+			};
+			results.push(entry);
+
+			if (isFail) {
+				if (!firstFailure) firstFailure = entry;
+				if (this.failFast) break;
+			}
+		}
+
+		return {
+			passed: !firstFailure,
+			results,
+			...(firstFailure ? { firstFailure } : {}),
+			duration_ms: Date.now() - started,
+		};
+	}
+}

package/src/core/loader.ts

@@ -0,0 +1,125 @@
+import { readFile } from "node:fs/promises";
+import Ajv from "ajv";
+import { parse as parseYaml } from "yaml";
+import schema from "../../schemas/pipeline.schema.json";
+import type { PipelineDefinition } from "../types";
+
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile(schema);
+
+export async function loadPipeline(filePath: string): Promise<PipelineDefinition> {
+	const raw = await readFile(filePath, "utf-8");
+	const doc = parseYaml(raw) as { pipeline?: unknown };
+
+	const valid = validate(doc);
+	if (!valid) {
+		const messages = (validate.errors ?? [])
+			.map((e) => `${e.instancePath || "root"} ${e.message}`)
+			.join("; ");
+		throw new Error(`Schema validation failed: ${messages}`);
+	}
+
+	const pipeline = (doc as { pipeline: PipelineDefinition }).pipeline;
+
+	const errors = validatePipeline(pipeline);
+	if (errors.length > 0) {
+		throw new Error(`Semantic validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+	}
+
+	return pipeline;
+}
+
+export function validatePipeline(pipeline: PipelineDefinition): string[] {
+	const errors: string[] = [];
+	const stageIds = new Set(Object.keys(pipeline.stages));
+	const conditionIds = new Set(Object.keys(pipeline.conditions ?? {}));
+	const gateIds = new Set(Object.keys(pipeline.gates ?? {}));
+
+	// Initial stage must exist
+	if (!stageIds.has(pipeline.initial)) {
+		errors.push(`Initial stage "${pipeline.initial}" does not exist in stages`);
+	}
+
+	for (const [stageId, stage] of Object.entries(pipeline.stages)) {
+		// Transition targets must exist
+		if (stage.on) {
+			for (const [event, transition] of Object.entries(stage.on)) {
+				if (!stageIds.has(transition.target)) {
+					errors.push(
+						`Stage "${stageId}" event "${event}" targets unknown stage "${transition.target}"`,
+					);
+				}
+				// Guard references must exist in conditions
+				if (transition.guard !== undefined && !conditionIds.has(transition.guard)) {
+					errors.push(
+						`Stage "${stageId}" event "${event}" guard "${transition.guard}" not found in conditions`,
+					);
+				}
+			}
+		}
+
+		// Gate references must exist in top-level gates
+		if (stage.gates) {
+			for (const ref of [...(stage.gates.entry ?? []), ...(stage.gates.exit ?? [])]) {
+				if (!gateIds.has(ref)) {
+					errors.push(`Stage "${stageId}" references unknown gate "${ref}"`);
+				}
+			}
+		}
+
+		// Parallel children must exist and have type "parallel-child"
+		if (stage.parallel) {
+			for (const childId of stage.parallel) {
+				if (!stageIds.has(childId)) {
+					errors.push(`Stage "${stageId}" parallel child "${childId}" does not exist`);
+				} else if (pipeline.stages[childId]?.type !== "parallel-child") {
+					errors.push(
+						`Stage "${stageId}" parallel child "${childId}" must have type "parallel-child"`,
+					);
+				}
+			}
+		}
+
+		// `when` conditions must exist in conditions
+		if (stage.when !== undefined && !conditionIds.has(stage.when)) {
+			errors.push(`Stage "${stageId}" when condition "${stage.when}" not found in conditions`);
+		}
+	}
+
+	// Unreachable stages via BFS from initial
+	if (stageIds.has(pipeline.initial)) {
+		const reachable = new Set<string>();
+		const queue: string[] = [pipeline.initial];
+		while (queue.length > 0) {
+			const current = queue.shift()!;
+			if (reachable.has(current)) continue;
+			reachable.add(current);
+			const stage = pipeline.stages[current];
+			if (!stage) continue;
+			// Follow transitions
+			if (stage.on) {
+				for (const transition of Object.values(stage.on)) {
+					if (!reachable.has(transition.target)) {
+						queue.push(transition.target);
+					}
+				}
+			}
+			// Follow parallel children
+			if (stage.parallel) {
+				for (const childId of stage.parallel) {
+					if (!reachable.has(childId)) {
+						queue.push(childId);
+					}
+				}
+			}
+		}
+
+		for (const stageId of stageIds) {
+			if (!reachable.has(stageId)) {
+				errors.push(`Stage "${stageId}" is unreachable from initial stage "${pipeline.initial}"`);
+			}
+		}
+	}
+
+	return errors;
+}

package/src/core/state-machine.ts

@@ -0,0 +1,119 @@
+import type { PipelineDefinition, PipelineState, StageDefinition } from "../types";
+
+export interface TransitionResult {
+	success: boolean;
+	newStage?: string;
+	previousStage?: string;
+	error?: string;
+}
+
+export class StateMachine {
+	private readonly pipeline: PipelineDefinition;
+	private _currentStage: string;
+	private _completedStages: string[];
+	private _retryCounts: Record<string, number>;
+	private _evidenceHead: string | null;
+	private _startedAt: string;
+
+	constructor(pipeline: PipelineDefinition) {
+		this.pipeline = pipeline;
+		this._currentStage = pipeline.initial;
+		this._completedStages = [];
+		this._retryCounts = {};
+		this._evidenceHead = null;
+		this._startedAt = new Date().toISOString();
+	}
+
+	static fromState(pipeline: PipelineDefinition, state: PipelineState): StateMachine {
+		const sm = new StateMachine(pipeline);
+		sm._currentStage = state.current_stage;
+		sm._completedStages = [...state.stages_completed];
+		sm._retryCounts = { ...state.retry_count };
+		sm._evidenceHead = state.evidence_chain_head;
+		sm._startedAt = state.started_at;
+		return sm;
+	}
+
+	get currentStage(): string {
+		return this._currentStage;
+	}
+
+	get isTerminal(): boolean {
+		const stageDef = this.pipeline.stages[this._currentStage];
+		return stageDef?.type === "terminal";
+	}
+
+	get completedStages(): string[] {
+		return [...this._completedStages];
+	}
+
+	get allowedEvents(): string[] {
+		const stageDef = this.pipeline.stages[this._currentStage];
+		if (!stageDef?.on) return [];
+		return Object.keys(stageDef.on);
+	}
+
+	get allowedTools(): string[] {
+		const stageDef = this.pipeline.stages[this._currentStage];
+		return stageDef?.agent?.tools ?? [];
+	}
+
+	get currentStageDefinition(): StageDefinition {
+		return this.pipeline.stages[this._currentStage];
+	}
+
+	getRetryCount(stageName: string): number {
+		return this._retryCounts[stageName] ?? 0;
+	}
+
+	transition(event: string): TransitionResult {
+		if (this.isTerminal) {
+			return {
+				success: false,
+				error: `Cannot transition from terminal stage "${this._currentStage}"`,
+			};
+		}
+
+		const stageDef = this.pipeline.stages[this._currentStage];
+		const transitionDef = stageDef?.on?.[event];
+
+		if (!transitionDef) {
+			return {
+				success: false,
+				error: `Event "${event}" is not valid in stage "${this._currentStage}". Allowed: [${this.allowedEvents.join(", ")}]`,
+			};
+		}
+
+		const previousStage = this._currentStage;
+		const newStage = transitionDef.target;
+
+		this._completedStages.push(previousStage);
+		this._currentStage = newStage;
+		this._incrementRetryCount(newStage);
+
+		return {
+			success: true,
+			newStage,
+			previousStage,
+		};
+	}
+
+	exportState(): PipelineState {
+		return {
+			pipeline_id: this.pipeline.id,
+			current_stage: this._currentStage,
+			started_at: this._startedAt,
+			stages_completed: [...this._completedStages],
+			retry_count: { ...this._retryCounts },
+			evidence_chain_head: this._evidenceHead,
+		};
+	}
+
+	updateEvidenceHead(hash: string): void {
+		this._evidenceHead = hash;
+	}
+
+	private _incrementRetryCount(stageName: string): void {
+		this._retryCounts[stageName] = (this._retryCounts[stageName] ?? 0) + 1;
+	}
+}

package/src/daemon/ipc.ts

@@ -0,0 +1,56 @@
+import type { IpcResponse } from "../types";
+
+export function createCheckResponse(
+	allowed: boolean,
+	currentStage: string,
+	allowedTools: string[],
+	reason?: string,
+): IpcResponse {
+	return {
+		verdict: allowed ? "allow" : "deny",
+		allowed,
+		current_stage: currentStage,
+		allowed_tools: allowedTools,
+		...(reason !== undefined ? { reason } : {}),
+	};
+}
+
+export function createAdvanceResponse(
+	success: boolean,
+	newStage?: string,
+	error?: string,
+): IpcResponse {
+	return {
+		verdict: "transition",
+		transitioned: success,
+		...(newStage !== undefined ? { new_stage: newStage } : {}),
+		...(error !== undefined ? { error } : {}),
+	};
+}
+
+export function createStatusResponse(
+	stage: string,
+	gatesRemaining: string[],
+	startedAt: string,
+	completedStages: string[] = [],
+	allowedEvents: string[] = [],
+	allowedTools: string[] = [],
+): IpcResponse {
+	const elapsedMs = Date.now() - new Date(startedAt).getTime();
+	const elapsedSec = Math.floor(elapsedMs / 1000);
+	return {
+		stage,
+		gates_remaining: gatesRemaining,
+		elapsed: `${elapsedSec}s`,
+		completed_stages: completedStages,
+		allowed_events: allowedEvents,
+		allowed_tools: allowedTools,
+	};
+}
+
+export function createSignalResponse(received: boolean, gateClearedId?: string): IpcResponse {
+	return {
+		received,
+		...(gateClearedId !== undefined ? { gate_cleared: gateClearedId } : {}),
+	};
+}