pipeline-sdk 0.1.0

package/src/cli/helpers.ts

@@ -0,0 +1,52 @@
+interface DaemonInfo {
+	port: number;
+	pid: number;
+}
+
+export async function readDaemonPid(dir = ".pipeline"): Promise<DaemonInfo> {
+	const pidPath = `${dir}/daemon.pid`;
+	const pidFile = Bun.file(pidPath);
+
+	if (!(await pidFile.exists())) {
+		console.error("Error: No running daemon found.");
+		console.error("");
+		console.error("  Start one with: pipeline start");
+		process.exit(1);
+	}
+
+	let info: DaemonInfo;
+	try {
+		info = JSON.parse(await pidFile.text()) as DaemonInfo;
+	} catch {
+		console.error("Error: Corrupt PID file at .pipeline/daemon.pid");
+		console.error("");
+		console.error("  Remove it and restart: rm .pipeline/daemon.pid && pipeline start");
+		process.exit(1);
+	}
+
+	if (!info.port || !info.pid) {
+		console.error("Error: Invalid PID file — missing port or pid.");
+		console.error("");
+		console.error("  Remove it and restart: rm .pipeline/daemon.pid && pipeline start");
+		process.exit(1);
+	}
+
+	return info;
+}
+
+export async function fetchDaemon(
+	port: number,
+	path: string,
+	options?: RequestInit,
+): Promise<Response> {
+	try {
+		return await fetch(`http://127.0.0.1:${port}${path}`, options);
+	} catch {
+		console.error(`Error: Daemon is not responding on port ${port}.`);
+		console.error("");
+		console.error("  The daemon may have crashed. Try:");
+		console.error("    rm .pipeline/daemon.pid");
+		console.error("    pipeline start");
+		process.exit(1);
+	}
+}

package/src/cli/index.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { VERSION } from "../index";
+import { advanceCommand } from "./advance";
+import { cleanupCommand } from "./cleanup";
+import { initCommand } from "./init";
+import { resumeCommand } from "./resume";
+import { signalCommand } from "./signal";
+import { startCommand } from "./start";
+import { statusCommand } from "./status";
+import { templateCommand } from "./template";
+import { validateCommand } from "./validate";
+import { verifyCommand } from "./verify";
+import { visualizeCommand } from "./visualize";
+
+const program = new Command();
+
+program
+	.name("pipeline")
+	.description("Pipeline SDK — multi-stage AI agent orchestration")
+	.version(VERSION);
+
+program
+	.command("init")
+	.description("Initialize a pipeline in the current project")
+	.option("-t, --template <name>", "Pipeline template to use")
+	.action((opts: { template?: string }) => initCommand(opts));
+
+program
+	.command("start")
+	.description("Start pipeline execution")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts) => startCommand(opts));
+
+program
+	.command("status")
+	.description("Show current pipeline status")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts) => statusCommand(opts));
+
+program
+	.command("advance")
+	.description("Advance to the next stage by emitting an event")
+	.argument("<event>", "Event name to emit")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((event, opts) => advanceCommand({ ...opts, event }));
+
+program
+	.command("signal")
+	.description("Send a signal to a waiting async gate")
+	.argument("<gate>", "Gate ID to signal")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((gate, opts) => signalCommand({ ...opts, gate }));
+
+program
+	.command("validate")
+	.description("Validate a pipeline definition file")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts: { file: string }) => validateCommand(opts));
+
+program
+	.command("verify")
+	.description("Verify the evidence chain for a completed pipeline")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts) => verifyCommand(opts));
+
+program
+	.command("visualize")
+	.description("Generate a visual diagram of the pipeline")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.option("--format <fmt>", "Output format (mermaid)", "mermaid")
+	.action((opts: { file: string; format: string }) => visualizeCommand(opts));
+
+program
+	.command("resume")
+	.description("Resume a paused pipeline from its last saved state")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts) => resumeCommand(opts));
+
+program
+	.command("cleanup")
+	.description("Run cleanup handlers for a terminated pipeline")
+	.option("-f, --file <path>", "Path to pipeline.yaml", "pipeline.yaml")
+	.action((opts) => cleanupCommand(opts));
+
+program
+	.command("template")
+	.description("List or export built-in pipeline templates")
+	.argument("[name]", "Template name to export")
+	.action((name, opts) => templateCommand({ ...opts, name }));
+
+program.parse();

package/src/cli/init.ts

@@ -0,0 +1,248 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { detectProviders } from "../adapters/detector";
+
+const MINIMAL_PIPELINE_YAML = `pipeline:
+  id: my-pipeline
+  version: 1
+  initial: work
+  stages:
+    work:
+      description: Do the work
+      on:
+        STAGE_COMPLETE:
+          target: done
+    done:
+      description: Pipeline complete
+      type: terminal
+`;
+
+const PIPELINE_ENFORCEMENT_SECTION = `
+## Pipeline Enforcement
+
+This project uses pipeline-sdk for multi-stage AI agent orchestration.
+
+- A \`pipeline.yaml\` at the repo root defines the allowed stage sequence.
+- The pipeline daemon enforces gate checks before stage transitions.
+- Do not skip gates or jump to later stages without completing prior ones.
+- Use \`pipeline status\` to check the current stage at any time.
+- Use \`pipeline advance <EVENT>\` to emit transition events.
+- Evidence is recorded in \`.pipeline/evidence/\` for each completed stage.
+`;
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function ensureDir(path: string): Promise<void> {
+	await mkdir(path, { recursive: true });
+}
+
+async function readTemplate(templateName: string): Promise<string> {
+	const templatePath = join(
+		dirname(import.meta.url.replace("file://", "")),
+		"../templates",
+		`${templateName}.yaml`,
+	);
+	try {
+		return await readFile(templatePath, "utf-8");
+	} catch {
+		// Fall back to inline minimal template
+		return MINIMAL_PIPELINE_YAML;
+	}
+}
+
+async function registerMcpInClaude(cwd: string): Promise<void> {
+	const settingsPath = join(cwd, ".claude", "settings.json");
+	let settings: Record<string, unknown> = {};
+	try {
+		const raw = await readFile(settingsPath, "utf-8");
+		settings = JSON.parse(raw) as Record<string, unknown>;
+	} catch {
+		// Start fresh
+	}
+
+	const mcpServers = (settings.mcpServers as Record<string, unknown> | undefined) ?? {};
+	if (!mcpServers["pipeline-sdk"]) {
+		await writeFile(
+			settingsPath,
+			JSON.stringify(
+				{
+					...settings,
+					mcpServers: {
+						...mcpServers,
+						"pipeline-sdk": {
+							command: "bun",
+							args: ["run", "node_modules/pipeline-sdk/src/mcp/server.ts"],
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+	}
+}
+
+async function registerMcpInCursor(cwd: string): Promise<void> {
+	const mcpPath = join(cwd, ".cursor", "mcp.json");
+	let config: Record<string, unknown> = {};
+	try {
+		const raw = await readFile(mcpPath, "utf-8");
+		config = JSON.parse(raw) as Record<string, unknown>;
+	} catch {
+		// Start fresh
+	}
+
+	const servers = (config.mcpServers as Record<string, unknown> | undefined) ?? {};
+	if (!servers["pipeline-sdk"]) {
+		await writeFile(
+			mcpPath,
+			JSON.stringify(
+				{
+					...config,
+					mcpServers: {
+						...servers,
+						"pipeline-sdk": {
+							command: "bun",
+							args: ["run", "node_modules/pipeline-sdk/src/mcp/server.ts"],
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+	}
+}
+
+async function registerMcpInGemini(cwd: string): Promise<void> {
+	const settingsPath = join(cwd, ".gemini", "settings.json");
+	let settings: Record<string, unknown> = {};
+	try {
+		const raw = await readFile(settingsPath, "utf-8");
+		settings = JSON.parse(raw) as Record<string, unknown>;
+	} catch {
+		// Start fresh
+	}
+
+	const tools = (settings.tools as Record<string, unknown> | undefined) ?? {};
+	const mcpServers = (tools.mcpServers as Record<string, unknown> | undefined) ?? {};
+	if (!mcpServers["pipeline-sdk"]) {
+		await writeFile(
+			settingsPath,
+			JSON.stringify(
+				{
+					...settings,
+					tools: {
+						...tools,
+						mcpServers: {
+							...mcpServers,
+							"pipeline-sdk": {
+								command: "bun",
+								args: ["run", "node_modules/pipeline-sdk/src/mcp/server.ts"],
+							},
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+	}
+}
+
+async function appendInstructionFile(filePath: string): Promise<void> {
+	let existing = "";
+	try {
+		existing = await readFile(filePath, "utf-8");
+	} catch {
+		// File doesn't exist yet — will create it
+	}
+
+	if (existing.includes("Pipeline Enforcement")) {
+		return; // Already present
+	}
+
+	await writeFile(filePath, existing + PIPELINE_ENFORCEMENT_SECTION, "utf-8");
+}
+
+export async function initCommand(opts: { template?: string }): Promise<void> {
+	const cwd = process.cwd();
+	const templateName = opts.template ?? "default";
+
+	console.log(`Initializing pipeline in ${cwd}...`);
+
+	// 1. Detect providers
+	const providers = await detectProviders(cwd);
+	console.log(`Detected providers: ${providers.length > 0 ? providers.join(", ") : "(none)"}`);
+
+	// 2. Write pipeline.yaml
+	const pipelinePath = join(cwd, "pipeline.yaml");
+	if (await fileExists(pipelinePath)) {
+		console.log("pipeline.yaml already exists — skipping.");
+	} else {
+		const yaml = await readTemplate(templateName);
+		await writeFile(pipelinePath, yaml, "utf-8");
+		console.log(`Created pipeline.yaml (template: ${templateName})`);
+	}
+
+	// 3. Create .pipeline/evidence/ directory
+	await ensureDir(join(cwd, ".pipeline", "evidence"));
+	console.log("Created .pipeline/evidence/");
+
+	// 4. Register MCP server in each detected provider's config
+	for (const provider of providers) {
+		try {
+			if (provider === "claude-code") {
+				await registerMcpInClaude(cwd);
+				console.log("Registered MCP server in .claude/settings.json");
+			} else if (provider === "cursor") {
+				await registerMcpInCursor(cwd);
+				console.log("Registered MCP server in .cursor/mcp.json");
+			} else if (provider === "gemini-cli") {
+				await registerMcpInGemini(cwd);
+				console.log("Registered MCP server in .gemini/settings.json");
+			}
+		} catch (err: unknown) {
+			console.warn(
+				`Warning: could not register MCP for ${provider}: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
+	// 5. Generate instruction file additions
+	const instructionFiles: Array<{ file: string; provider: string }> = [
+		{ file: "CLAUDE.md", provider: "claude-code" },
+		{ file: "GEMINI.md", provider: "gemini-cli" },
+		{ file: "AGENTS.md", provider: "generic" },
+		{ file: ".cursorrules", provider: "cursor" },
+	];
+
+	for (const { file, provider } of instructionFiles) {
+		// Write for all detected providers, or AGENTS.md always
+		const shouldWrite =
+			provider === "generic" || providers.includes(provider) || providers.length === 0;
+		if (shouldWrite) {
+			try {
+				await appendInstructionFile(join(cwd, file));
+				console.log(`Updated ${file} with Pipeline Enforcement section`);
+			} catch (err: unknown) {
+				console.warn(
+					`Warning: could not update ${file}: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	console.log("\nPipeline initialized successfully.");
+	console.log("Run `pipeline validate` to check your pipeline definition.");
+}

package/src/cli/resume.ts

@@ -0,0 +1,45 @@
+import { loadPipeline } from "../core/loader";
+import { PipelineDaemon } from "../daemon/server";
+import { StateFile } from "../daemon/state-file";
+import type { PipelineDefinition } from "../types";
+
+export async function resumeCommand(opts: { file: string }): Promise<void> {
+	let pipeline: PipelineDefinition;
+	try {
+		pipeline = await loadPipeline(opts.file);
+	} catch (err: unknown) {
+		console.error(`Error: Failed to load pipeline from ${opts.file}`);
+		console.error("");
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			console.error("  File not found. Are you in the right directory?");
+		} else {
+			console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		}
+		process.exit(1);
+	}
+
+	const dir = ".pipeline";
+	const stateFile = new StateFile(`${dir}/state.json`);
+	const state = await stateFile.read();
+
+	if (!state) {
+		console.error("Error: No saved state found at .pipeline/state.json");
+		console.error("");
+		console.error("  A pipeline must be started and advanced at least once to create state.");
+		console.error("  Start fresh with: pipeline start");
+		process.exit(1);
+	}
+
+	try {
+		const daemon = new PipelineDaemon(pipeline, dir, state);
+		const { port, pid } = await daemon.start();
+		console.log(`Daemon resumed on port ${port} (PID ${pid})`);
+		console.log(`Pipeline: ${state.pipeline_id} | Stage: ${state.current_stage}`);
+		await new Promise(() => {});
+	} catch (err: unknown) {
+		console.error("Error: Failed to resume daemon.");
+		console.error("");
+		console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+}

package/src/cli/signal.ts

@@ -0,0 +1,21 @@
+import { fetchDaemon, readDaemonPid } from "./helpers";
+
+export async function signalCommand(opts: { file: string; gate: string }): Promise<void> {
+	const { port } = await readDaemonPid();
+	const res = await fetchDaemon(port, "/api/signal", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ gate_id: opts.gate, signal: "LGTM" }),
+	});
+	const result = (await res.json()) as { gate_cleared: boolean; gate_id?: string };
+
+	if (result.gate_cleared) {
+		console.log(`Signal sent to gate: ${result.gate_id}`);
+		process.exit(0);
+	}
+
+	console.error(`Error: Failed to signal gate "${opts.gate}".`);
+	console.error("");
+	console.error("  Check available gates with: pipeline status");
+	process.exit(1);
+}

package/src/cli/start.ts

@@ -0,0 +1,33 @@
+import { loadPipeline } from "../core/loader";
+import { PipelineDaemon } from "../daemon/server";
+import type { PipelineDefinition } from "../types";
+
+export async function startCommand(opts: { file: string }): Promise<void> {
+	let pipeline: PipelineDefinition;
+	try {
+		pipeline = await loadPipeline(opts.file);
+	} catch (err: unknown) {
+		console.error(`Error: Failed to load pipeline from ${opts.file}`);
+		console.error("");
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			console.error("  File not found. Create one with: pipeline init");
+		} else {
+			console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		}
+		process.exit(1);
+	}
+
+	try {
+		const dir = ".pipeline";
+		const daemon = new PipelineDaemon(pipeline, dir);
+		const { port, pid } = await daemon.start();
+		console.log(`Daemon started on port ${port} (PID ${pid})`);
+		console.log(`Pipeline: ${pipeline.id} | Stage: ${pipeline.initial}`);
+		await new Promise(() => {});
+	} catch (err: unknown) {
+		console.error("Error: Failed to start daemon.");
+		console.error("");
+		console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+}

package/src/cli/status.ts

@@ -0,0 +1,24 @@
+import { fetchDaemon, readDaemonPid } from "./helpers";
+
+export async function statusCommand(_opts: { file: string }): Promise<void> {
+	const { port } = await readDaemonPid();
+	const res = await fetchDaemon(port, "/api/status");
+	const status = (await res.json()) as Record<string, unknown>;
+
+	console.log(`Stage:      ${status.stage}`);
+	if (status.started_at) console.log(`Started:    ${status.started_at}`);
+
+	const completed = status.completed_stages as string[] | undefined;
+	if (completed?.length) console.log(`Completed:  ${completed.join(" → ")}`);
+
+	const events = status.allowed_events as string[] | undefined;
+	if (events?.length) console.log(`Events:     ${events.join(", ")}`);
+
+	const tools = status.allowed_tools as string[] | undefined;
+	if (tools?.length) console.log(`Tools:      ${tools.join(", ")}`);
+
+	const gates = status.gates_remaining as string[] | undefined;
+	if (gates?.length) console.log(`Gates:      ${gates.join(", ")}`);
+
+	process.exit(0);
+}

package/src/cli/template.ts

@@ -0,0 +1,28 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const TEMPLATES_DIR = join(import.meta.dir, "../templates");
+
+export async function templateCommand(opts: Record<string, unknown>): Promise<void> {
+	const name = opts.name as string | undefined;
+
+	if (!name) {
+		// List mode
+		const files = await readdir(TEMPLATES_DIR);
+		const templates = files.filter((f) => f.endsWith(".yaml")).map((f) => f.replace(".yaml", ""));
+		console.log("Available templates:");
+		for (const t of templates) console.log(`  - ${t}`);
+		return;
+	}
+
+	// Use mode
+	const src = join(TEMPLATES_DIR, `${name}.yaml`);
+	try {
+		const content = await readFile(src, "utf-8");
+		await writeFile(join(process.cwd(), "pipeline.yaml"), content);
+		console.log(`Applied template "${name}" to pipeline.yaml`);
+	} catch {
+		console.error(`Template "${name}" not found.`);
+		process.exit(1);
+	}
+}

package/src/cli/validate.ts

@@ -0,0 +1,21 @@
+import { loadPipeline } from "../core/loader";
+
+export async function validateCommand(opts: { file: string }): Promise<void> {
+	try {
+		const pipeline = await loadPipeline(opts.file);
+
+		const terminalStages = Object.entries(pipeline.stages)
+			.filter(([, stage]) => stage.type === "terminal")
+			.map(([id]) => id);
+
+		console.log(`Pipeline: ${pipeline.id}`);
+		console.log(`  Stages   : ${Object.keys(pipeline.stages).length}`);
+		console.log(`  Initial  : ${pipeline.initial}`);
+		console.log(`  Terminal : ${terminalStages.length > 0 ? terminalStages.join(", ") : "(none)"}`);
+		console.log("Validation passed.");
+		process.exit(0);
+	} catch (err: unknown) {
+		console.error(`Validation failed: ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+}

package/src/cli/verify.ts

@@ -0,0 +1,33 @@
+import { EvidenceStore } from "../core/evidence";
+import { loadPipeline } from "../core/loader";
+
+export async function verifyCommand(opts: { file: string }): Promise<void> {
+	try {
+		await loadPipeline(opts.file);
+	} catch (err: unknown) {
+		console.error(`Error: Failed to load pipeline from ${opts.file}`);
+		console.error("");
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			console.error("  File not found. Are you in the right directory?");
+		} else {
+			console.error(`  ${err instanceof Error ? err.message : String(err)}`);
+		}
+		process.exit(1);
+	}
+
+	const evidenceDir = ".pipeline/evidence";
+	const store = new EvidenceStore(evidenceDir);
+	const result = await store.verify();
+
+	if (result.valid) {
+		console.log(`Evidence chain valid (${result.recordCount} records)`);
+		process.exit(0);
+	}
+
+	console.error("Error: Evidence chain verification failed.");
+	console.error("");
+	for (const err of result.errors) {
+		console.error(`  - ${err}`);
+	}
+	process.exit(1);
+}

package/src/cli/visualize.ts

@@ -0,0 +1,36 @@
+import { loadPipeline } from "../core/loader";
+
+export async function visualizeCommand(opts: { format: string; file: string }): Promise<void> {
+	try {
+		const pipeline = await loadPipeline(opts.file);
+
+		if (opts.format !== "mermaid") {
+			console.error(`Unknown format "${opts.format}". Supported: mermaid`);
+			process.exit(1);
+		}
+
+		const lines: string[] = ["stateDiagram-v2"];
+
+		// Initial arrow
+		lines.push(`  [*] --> ${pipeline.initial}`);
+
+		// Transitions
+		for (const [stageId, stage] of Object.entries(pipeline.stages)) {
+			if (stage.on) {
+				for (const [event, transition] of Object.entries(stage.on)) {
+					lines.push(`  ${stageId} --> ${transition.target} : ${event}`);
+				}
+			}
+			// Terminal stages point to [*]
+			if (stage.type === "terminal") {
+				lines.push(`  ${stageId} --> [*]`);
+			}
+		}
+
+		console.log(lines.join("\n"));
+		process.exit(0);
+	} catch (err: unknown) {
+		console.error(`Visualization failed: ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+}