pipeline-sdk 0.1.0

package/src/daemon/server.ts

@@ -0,0 +1,144 @@
+import { unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { StateMachine } from "../core/state-machine";
+import type { PipelineDefinition, PipelineState } from "../types";
+import {
+	createAdvanceResponse,
+	createCheckResponse,
+	createSignalResponse,
+	createStatusResponse,
+} from "./ipc";
+import { StateFile } from "./state-file";
+
+export class PipelineDaemon {
+	private readonly dir: string;
+	private sm: StateMachine;
+	private stateFile: StateFile;
+	private server: ReturnType<typeof Bun.serve> | null = null;
+	private signals: Map<string, { signal: string; source?: string }> = new Map();
+
+	constructor(pipeline: PipelineDefinition, dir: string, state?: PipelineState) {
+		this.dir = dir;
+		this.sm = state ? StateMachine.fromState(pipeline, state) : new StateMachine(pipeline);
+		this.stateFile = new StateFile(join(dir, "state.json"));
+	}
+
+	async start(): Promise<{ port: number; pid: number }> {
+		if (this.server) {
+			throw new Error("Daemon is already running. Call stop() first.");
+		}
+		const daemon = this;
+
+		this.server = Bun.serve({
+			hostname: "127.0.0.1",
+			port: 0,
+			async fetch(req) {
+				try {
+					const url = new URL(req.url);
+					const path = url.pathname;
+
+					if (req.method === "GET" && path === "/api/status") {
+						const stageDef = daemon.sm.currentStageDefinition;
+						const gatesRemaining = stageDef?.gates?.exit ?? [];
+						const state = daemon.sm.exportState();
+						const body = createStatusResponse(
+							daemon.sm.currentStage,
+							gatesRemaining,
+							state.started_at,
+							daemon.sm.completedStages,
+							daemon.sm.allowedEvents,
+							daemon.sm.allowedTools,
+						);
+						return Response.json(body);
+					}
+
+					if (req.method === "POST" && path === "/api/check") {
+						const body = (await req.json()) as { tool?: string; command?: string };
+						if (!body.tool || typeof body.tool !== "string") {
+							return Response.json(
+								{ error: "Missing required field: tool (string)" },
+								{ status: 400 },
+							);
+						}
+						const tool = body.tool ?? "";
+						const allowedTools = daemon.sm.allowedTools;
+						// If no whitelist defined, allow all tools
+						const allowed = allowedTools.length === 0 || allowedTools.includes(tool);
+						const reason = allowed
+							? undefined
+							: `Tool "${tool}" is not in the allowed list for stage "${daemon.sm.currentStage}"`;
+						const resp = createCheckResponse(allowed, daemon.sm.currentStage, allowedTools, reason);
+						return Response.json(resp);
+					}
+
+					if (req.method === "POST" && path === "/api/advance") {
+						const body = (await req.json()) as { event?: string };
+						if (!body.event || typeof body.event !== "string") {
+							return Response.json(
+								{ error: "Missing required field: event (string)" },
+								{ status: 400 },
+							);
+						}
+						const event = body.event ?? "";
+						const result = daemon.sm.transition(event);
+						if (result.success) {
+							await daemon.stateFile.write(daemon.sm.exportState());
+						}
+						const resp = createAdvanceResponse(result.success, result.newStage, result.error);
+						return Response.json(resp);
+					}
+
+					if (req.method === "POST" && path === "/api/signal") {
+						const body = (await req.json()) as {
+							signal?: string;
+							gate_id?: string;
+							source?: string;
+						};
+						if (!body.gate_id || typeof body.gate_id !== "string") {
+							return Response.json(
+								{ error: "Missing required field: gate_id (string)" },
+								{ status: 400 },
+							);
+						}
+						const gateId = body.gate_id;
+						const signal = body.signal ?? "";
+						if (gateId) {
+							daemon.signals.set(gateId, { signal, source: body.source });
+						}
+						const resp = createSignalResponse(true, gateId);
+						return Response.json(resp);
+					}
+
+					return new Response("Not Found", { status: 404 });
+				} catch (err: unknown) {
+					if (err instanceof SyntaxError) {
+						return Response.json({ error: "Invalid JSON in request body" }, { status: 400 });
+					}
+					return Response.json(
+						{ error: err instanceof Error ? err.message : "Internal server error" },
+						{ status: 500 },
+					);
+				}
+			},
+		});
+
+		const port = this.server.port ?? 0;
+		const pid = process.pid;
+
+		await writeFile(join(this.dir, "daemon.pid"), JSON.stringify({ port, pid }), "utf8");
+
+		return { port, pid };
+	}
+
+	async stop(): Promise<void> {
+		if (this.server) {
+			this.server.stop(true);
+			this.server = null;
+		}
+		try {
+			await unlink(join(this.dir, "daemon.pid"));
+		} catch {
+			// ignore if already gone
+		}
+	}
+}

package/src/daemon/state-file.ts

@@ -0,0 +1,65 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { PipelineState } from "../types";
+
+export class StateFile {
+	private readonly path: string;
+
+	constructor(path: string) {
+		this.path = path;
+	}
+
+	async write(state: PipelineState): Promise<void> {
+		const dir = dirname(this.path);
+		await mkdir(dir, { recursive: true });
+		const tmpPath = `${this.path}.tmp`;
+		await writeFile(tmpPath, JSON.stringify(state, null, 2), "utf8");
+		await rename(tmpPath, this.path);
+	}
+
+	async read(): Promise<PipelineState | null> {
+		try {
+			const content = await readFile(this.path, "utf8");
+			return JSON.parse(content) as PipelineState;
+		} catch (err: unknown) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+				return null;
+			}
+			throw err;
+		}
+	}
+
+	async writeCleanupPending(stages: string[]): Promise<void> {
+		const dir = dirname(this.path);
+		await mkdir(dir, { recursive: true });
+		const cleanupPath = join(dir, "cleanup-pending.json");
+		await writeFile(cleanupPath, JSON.stringify(stages, null, 2), "utf8");
+	}
+
+	async readCleanupPending(): Promise<string[]> {
+		const dir = dirname(this.path);
+		const cleanupPath = join(dir, "cleanup-pending.json");
+		try {
+			const content = await readFile(cleanupPath, "utf8");
+			return JSON.parse(content) as string[];
+		} catch (err: unknown) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+				return [];
+			}
+			throw err;
+		}
+	}
+
+	async clearCleanupPending(): Promise<void> {
+		const dir = dirname(this.path);
+		const cleanupPath = join(dir, "cleanup-pending.json");
+		try {
+			await unlink(cleanupPath);
+		} catch (err: unknown) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+				return;
+			}
+			throw err;
+		}
+	}
+}

package/src/gates/async.ts

@@ -0,0 +1,60 @@
+import type { GateVerdict } from "../types";
+
+interface SignalPayload {
+	signal: string;
+	source: string;
+	metadata?: Record<string, unknown>;
+}
+
+const APPROVE_SIGNALS = new Set(["APPROVED", "LGTM", "PASS"]);
+
+export class AsyncGate {
+	private readonly gateId: string;
+	private readonly timeoutMs: number;
+	private resolve: ((verdict: GateVerdict) => void) | null = null;
+	private pending: Promise<GateVerdict> | null = null;
+	private timerId: ReturnType<typeof setTimeout> | null = null;
+
+	constructor(gateId: string, options: { timeoutMs: number }) {
+		this.gateId = gateId;
+		this.timeoutMs = options.timeoutMs;
+	}
+
+	deliver(payload: SignalPayload): void {
+		if (!this.resolve) return;
+
+		if (this.timerId) {
+			clearTimeout(this.timerId);
+			this.timerId = null;
+		}
+
+		const signal = payload.signal.toUpperCase();
+		const status: GateVerdict["status"] = APPROVE_SIGNALS.has(signal) ? "pass" : "fail";
+
+		this.resolve({
+			status,
+			message: `Gate "${this.gateId}" received signal "${payload.signal}" from "${payload.source}"`,
+		});
+		this.resolve = null;
+	}
+
+	wait(): Promise<GateVerdict> {
+		if (this.pending) return this.pending;
+
+		this.pending = new Promise<GateVerdict>((res) => {
+			this.resolve = res;
+
+			this.timerId = setTimeout(() => {
+				if (!this.resolve) return;
+				this.resolve({
+					status: "fail",
+					message: `Gate "${this.gateId}" timed out after ${this.timeoutMs}ms`,
+				});
+				this.resolve = null;
+				this.timerId = null;
+			}, this.timeoutMs);
+		});
+
+		return this.pending;
+	}
+}

package/src/gates/builtin.ts

@@ -0,0 +1,40 @@
+import { exec as execCb } from "node:child_process";
+import { promisify } from "node:util";
+import type { GateEvaluator } from "../core/gate-runner";
+import type { GateInput, GateVerdict } from "../types";
+
+const exec = promisify(execCb);
+
+export const BUILTIN_GATES: Record<string, { defaultCommand: string }> = {
+	"lint-pass": { defaultCommand: "npm run lint" },
+	"typecheck-pass": { defaultCommand: "npm run typecheck" },
+	"format-check": { defaultCommand: "npm run format:check" },
+	"unit-tests-pass": { defaultCommand: "npm test" },
+	"integration-tests-pass": { defaultCommand: "npm run test:integration" },
+	"e2e-tests-pass": { defaultCommand: "npm run test:e2e" },
+	"dep-audit-pass": { defaultCommand: "npm audit --audit-level=high" },
+	"build-succeeds": { defaultCommand: "npm run build" },
+};
+
+export function createBuiltinGate(
+	name: string,
+	config: { command?: string },
+): GateEvaluator | null {
+	const builtin = BUILTIN_GATES[name];
+	if (!builtin) return null;
+
+	const command = config.command ?? builtin.defaultCommand;
+
+	return async (input: GateInput): Promise<GateVerdict> => {
+		try {
+			await exec(command, {
+				cwd: input.workspace.root,
+				timeout: 300_000,
+			});
+			return { status: "pass", message: `${name}: command succeeded` };
+		} catch (err: unknown) {
+			const message = err instanceof Error ? err.message : `${name}: command failed`;
+			return { status: "fail", message };
+		}
+	};
+}

package/src/gates/custom.ts

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import type { GateInput, GateVerdict } from "../types";
+
+export class CustomGateRunner {
+	async evaluate(scriptPath: string, input: GateInput, timeoutMs = 300_000): Promise<GateVerdict> {
+		return new Promise((resolve) => {
+			let proc: ReturnType<typeof spawn>;
+
+			try {
+				proc = spawn(scriptPath, [], { stdio: ["pipe", "pipe", "pipe"] });
+			} catch (err: unknown) {
+				const message = err instanceof Error ? err.message : "Failed to spawn process";
+				resolve({ status: "fail", message });
+				return;
+			}
+
+			let stdout = "";
+			let stderr = "";
+
+			proc.stdout?.on("data", (chunk: Buffer) => {
+				stdout += chunk.toString();
+			});
+
+			proc.stderr?.on("data", (chunk: Buffer) => {
+				stderr += chunk.toString();
+			});
+
+			proc.on("error", (err: Error) => {
+				resolve({ status: "fail", message: err.message });
+			});
+
+			const timer = setTimeout(() => {
+				proc.kill();
+				resolve({ status: "fail", message: `Script timed out after ${timeoutMs}ms` });
+			}, timeoutMs);
+
+			proc.on("close", (code: number | null) => {
+				clearTimeout(timer);
+
+				const trimmed = stdout.trim();
+				if (trimmed) {
+					try {
+						const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+						if (typeof parsed.status === "string" && typeof parsed.message === "string") {
+							resolve(parsed as unknown as GateVerdict);
+							return;
+						}
+					} catch {
+						// fall through to exit-code fallback
+					}
+				}
+
+				// Exit-code fallback
+				if (code === 0) {
+					resolve({ status: "pass", message: "Script exited with code 0" });
+				} else {
+					const detail = stderr.trim() || `Script exited with code ${code ?? "null"}`;
+					resolve({ status: "fail", message: detail });
+				}
+			});
+
+			// Send input via stdin then close
+			try {
+				proc.stdin?.write(JSON.stringify(input));
+				proc.stdin?.end();
+			} catch {
+				// stdin may already be closed if the process failed immediately
+			}
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import pkg from "../package.json";
+
+export const VERSION: string = pkg.version;
+export { ClaudeCodeAdapter } from "./adapters/claude-code";
+export { detectProviders } from "./adapters/detector";
+export { GenericAdapter } from "./adapters/generic";
+export type { ProviderAdapter } from "./adapters/interface";
+export { CleanupManager } from "./core/cleanup";
+export { EvidenceStore } from "./core/evidence";
+export { GateRunner } from "./core/gate-runner";
+export { loadPipeline, validatePipeline } from "./core/loader";
+export { StateMachine } from "./core/state-machine";
+export { PipelineDaemon } from "./daemon/server";
+export { StateFile } from "./daemon/state-file";
+export { AsyncGate } from "./gates/async";
+export { BUILTIN_GATES, createBuiltinGate } from "./gates/builtin";
+export { CustomGateRunner } from "./gates/custom";
+export { createMcpServer } from "./mcp/server";
+export { createPipelineTools } from "./mcp/tools";
+export type * from "./types";

package/src/mcp/prompts.ts

@@ -0,0 +1,40 @@
+import type { PipelineDefinition } from "../types";
+
+export function createStagePrompt(pipeline: PipelineDefinition, stageName: string): string {
+	const stageDef = pipeline.stages[stageName];
+
+	if (!stageDef) {
+		return `Stage "${stageName}" not found in pipeline "${pipeline.id}".`;
+	}
+
+	const allowedTools = stageDef.agent?.tools ?? [];
+	const allowedEvents = stageDef.on ? Object.keys(stageDef.on) : [];
+
+	const lines: string[] = [
+		`You are in the ${stageName.toUpperCase()} stage of the "${pipeline.id}" pipeline.`,
+	];
+
+	if (stageDef.description) {
+		lines.push(`Description: ${stageDef.description}`);
+	}
+
+	if (stageDef.agent?.instructions) {
+		lines.push(`Instructions: ${stageDef.agent.instructions}`);
+	}
+
+	if (allowedTools.length > 0) {
+		lines.push(`Allowed tools: ${allowedTools.join(", ")}.`);
+	} else {
+		lines.push("All tools are allowed in this stage.");
+	}
+
+	if (allowedEvents.length > 0) {
+		lines.push(`When done, call pipeline_advance with one of: ${allowedEvents.join(", ")}.`);
+	}
+
+	if (allowedTools.length > 0) {
+		lines.push("Call pipeline_check before any tool use to verify it is allowed.");
+	}
+
+	return lines.join("\n");
+}

package/src/mcp/resources.ts

@@ -0,0 +1,71 @@
+import type { StateMachine } from "../core/state-machine";
+import type { PipelineDefinition } from "../types";
+
+export interface ResourceContent {
+	uri: string;
+	mimeType: string;
+	text: string;
+}
+
+export function createPipelineResources(
+	machine: StateMachine,
+	pipeline: PipelineDefinition,
+): Record<string, () => ResourceContent> {
+	return {
+		"pipeline://state/current"(): ResourceContent {
+			const state = machine.exportState();
+			const stageDef = machine.currentStageDefinition;
+			return {
+				uri: "pipeline://state/current",
+				mimeType: "application/json",
+				text: JSON.stringify({
+					stage: machine.currentStage,
+					gates: {
+						entry: stageDef?.gates?.entry ?? [],
+						exit: stageDef?.gates?.exit ?? [],
+					},
+					evidence_head: state.evidence_chain_head,
+					started_at: state.started_at,
+					is_terminal: machine.isTerminal,
+				}),
+			};
+		},
+
+		"pipeline://instructions/current"(): ResourceContent {
+			const stageDef = machine.currentStageDefinition;
+			return {
+				uri: "pipeline://instructions/current",
+				mimeType: "application/json",
+				text: JSON.stringify({
+					stage: machine.currentStage,
+					description: stageDef?.description ?? null,
+					tools_allowed: machine.allowedTools,
+					constraints: stageDef?.agent?.instructions ?? null,
+					allowed_events: machine.allowedEvents,
+				}),
+			};
+		},
+
+		"pipeline://gates/available"(): ResourceContent {
+			const stageDef = machine.currentStageDefinition;
+			const entryGateIds = stageDef?.gates?.entry ?? [];
+			const exitGateIds = stageDef?.gates?.exit ?? [];
+			const allGateIds = [...entryGateIds, ...exitGateIds];
+
+			const gates = allGateIds.map((id) => {
+				const gateDef = pipeline.gates?.[id];
+				return {
+					id,
+					type: gateDef?.type ?? "builtin",
+					description: gateDef?.signal ?? gateDef?.command ?? id,
+				};
+			});
+
+			return {
+				uri: "pipeline://gates/available",
+				mimeType: "application/json",
+				text: JSON.stringify(gates),
+			};
+		},
+	};
+}