@buildepicshit/cli 0.0.2 → 0.0.3

package/src/orchestrator/index.ts

@@ -0,0 +1,62 @@
+// Core API
+export {
+	cmd,
+	compute,
+	customHealthCheck,
+	execHealthCheck,
+	fromEnv,
+	fromFile,
+	fromPackageJson,
+	health,
+	httpHealthCheck,
+	par,
+	seq,
+	stdoutHealthCheck,
+	tcpHealthCheck,
+} from "./core/index.js";
+// Types
+export type {
+	BuiltCommand,
+	ComputeContext,
+	EnvCallback,
+	EnvSource,
+	HealthCheck,
+	HealthCheckCallback,
+	ICommand,
+	ICompound,
+	ProcessStatus,
+	Runnable,
+	Token,
+} from "./core/types.js";
+// Logger
+export type { Logger } from "./logger/logger.js";
+export { createLazyLogger, createLogger } from "./logger/logger.js";
+// Presets
+export type { NextPreset } from "./presets/index.js";
+export {
+	docker,
+	esbuild,
+	esbuildWatch,
+	hono,
+	next,
+	nodemon,
+	tsx,
+} from "./presets/index.js";
+// Runner
+export type {
+	DevEvent,
+	IEventBus,
+	LogEntry,
+	OrchestratorProcess,
+	ProcessMeta,
+	RuntimeContext,
+} from "./runner/index.js";
+export {
+	clearRuntimeContext,
+	createEventBus,
+	getRuntimeContext,
+	setRuntimeContext,
+} from "./runner/index.js";
+export type { Identity } from "./utils/dna.js";
+// Utils
+export { createIdentity, identity } from "./utils/dna.js";

package/src/orchestrator/logger/logger.ts

@@ -0,0 +1,123 @@
+import chalk, { type ChalkInstance } from "chalk";
+
+const COLORS: ChalkInstance[] = [
+	chalk.cyan,
+	chalk.magenta,
+	chalk.yellow,
+	chalk.green,
+	chalk.blue,
+	chalk.red,
+	chalk.white,
+];
+
+export interface Logger {
+	completed(serviceName: string): void;
+	error(serviceName: string, message: string): void;
+	healthy(serviceName: string): void;
+	output(serviceName: string, line: string, stream: "stderr" | "stdout"): void;
+	ready(serviceName: string): void;
+	starting(serviceName: string, nodeId: string): void;
+	system(message: string): void;
+}
+
+export function createLogger(serviceNames: string[]): Logger {
+	// Compute max prefix width for alignment
+	const maxLen = Math.max(...serviceNames.map((n) => n.length), 6);
+	const colorMap = new Map<string, ChalkInstance>();
+
+	for (let i = 0; i < serviceNames.length; i++) {
+		colorMap.set(serviceNames[i], COLORS[i % COLORS.length]);
+	}
+
+	function prefix(name: string): string {
+		const color = colorMap.get(name) ?? chalk.white;
+		return color(`[${name.padEnd(maxLen)}]`);
+	}
+
+	return {
+		completed(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("completed")} ✓`);
+		},
+
+		error(serviceName, message) {
+			console.error(
+				`${prefix(serviceName)} ${chalk.red("error")} ✗ ${message}`,
+			);
+		},
+
+		healthy(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("healthy")} ✓`);
+		},
+
+		output(serviceName, line, _stream) {
+			console.log(`${prefix(serviceName)} ${line}`);
+		},
+
+		ready(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("ready")} ✓`);
+		},
+		starting(serviceName, nodeId) {
+			console.log(`${prefix(serviceName)} Starting ${nodeId}...`);
+		},
+
+		system(message) {
+			console.log(chalk.gray(message));
+		},
+	};
+}
+
+/**
+ * Lazy logger that auto-registers service names on first use.
+ * Adjusts column padding dynamically as new names appear.
+ */
+export function createLazyLogger(): Logger {
+	const colorMap = new Map<string, ChalkInstance>();
+	let maxLen = 6;
+	let nextColorIdx = 0;
+
+	function ensureName(name: string) {
+		if (!colorMap.has(name)) {
+			colorMap.set(name, COLORS[nextColorIdx % COLORS.length]);
+			nextColorIdx++;
+			maxLen = Math.max(maxLen, name.length);
+		}
+	}
+
+	function prefix(name: string): string {
+		ensureName(name);
+		const color = colorMap.get(name) as ChalkInstance;
+		return color(`[${name.padEnd(maxLen)}]`);
+	}
+
+	return {
+		completed(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("completed")} ✓`);
+		},
+
+		error(serviceName, message) {
+			console.error(
+				`${prefix(serviceName)} ${chalk.red("error")} ✗ ${message}`,
+			);
+		},
+
+		healthy(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("healthy")} ✓`);
+		},
+
+		output(serviceName, line, _stream) {
+			console.log(`${prefix(serviceName)} ${line}`);
+		},
+
+		ready(serviceName) {
+			console.log(`${prefix(serviceName)} ${chalk.green("ready")} ✓`);
+		},
+
+		starting(serviceName, _nodeId) {
+			console.log(`${prefix(serviceName)} Starting...`);
+		},
+
+		system(message) {
+			console.log(chalk.gray(message));
+		},
+	};
+}

package/src/orchestrator/presets/docker.ts

@@ -0,0 +1,26 @@
+import { cmd } from "../core/command.js";
+import type { ICommand, Token } from "../core/types.js";
+
+export function docker(options?: {
+	detach?: boolean;
+	file?: Token;
+	service?: string;
+}): ICommand {
+	let command = cmd("docker compose");
+
+	if (options?.file) {
+		command = command.flag("file", options.file);
+	}
+
+	command = command.arg("up");
+
+	if (options?.detach) {
+		command = command.flag("detach");
+	}
+
+	if (options?.service) {
+		command = command.arg(options.service);
+	}
+
+	return command;
+}

package/src/orchestrator/presets/esbuild.ts

@@ -0,0 +1,12 @@
+import { cmd } from "../core/command.js";
+import type { ICommand } from "../core/types.js";
+
+export function esbuild(configFile?: string): ICommand {
+	return cmd("node").arg(configFile ?? "esbuild.config.js");
+}
+
+export function esbuildWatch(configFile?: string): ICommand {
+	return cmd("node")
+		.arg(configFile ?? "esbuild.config.js")
+		.flag("watch");
+}

package/src/orchestrator/presets/hono.ts

@@ -0,0 +1,7 @@
+import { cmd } from "../core/command.js";
+import type { ICommand } from "../core/types.js";
+import { identity } from "../utils/dna.js";
+
+export function hono(): ICommand {
+	return cmd("tsx").env({ PORT: identity("hono").port() });
+}

package/src/orchestrator/presets/index.ts

@@ -0,0 +1,5 @@
+export { docker } from "./docker.js";
+export { esbuild, esbuildWatch } from "./esbuild.js";
+export { hono } from "./hono.js";
+export { type NextPreset, next } from "./nextjs.js";
+export { nodemon, tsx } from "./node.js";

package/src/orchestrator/presets/nextjs.ts

@@ -0,0 +1,48 @@
+import { cmd } from "../core/command";
+import { health } from "../core/health-check";
+import type { ICommand } from "../core/types";
+import { createIdentity } from "../utils/dna";
+
+export interface NextPreset {
+	build(): ICommand;
+	dev(): ICommand;
+	dir(path: string): NextPreset;
+	start(): ICommand;
+}
+
+export function next(suffix = "next"): NextPreset {
+	const identity = createIdentity(suffix);
+	return createNextPreset(identity, null);
+}
+
+function createNextPreset(
+	identity: ReturnType<typeof createIdentity>,
+	dirPath: string | null,
+): NextPreset {
+	function applyDir(command: ICommand): ICommand {
+		return dirPath ? command.dir(dirPath) : command;
+	}
+
+	return {
+		build(): ICommand {
+			return applyDir(cmd("next build"));
+		},
+		dev(): ICommand {
+			return applyDir(
+				cmd("next dev")
+					.waitFor(health.http(identity.url("/livez")))
+					.env({ PORT: identity.port() }),
+			);
+		},
+		dir(path: string): NextPreset {
+			return createNextPreset(identity, path);
+		},
+		start(): ICommand {
+			return applyDir(
+				cmd("next start")
+					.waitFor(health.http(identity.url("/livez")))
+					.env({ PORT: identity.port() }),
+			);
+		},
+	};
+}

package/src/orchestrator/presets/node.ts

@@ -0,0 +1,12 @@
+import { cmd } from "../core/command.js";
+import type { ICommand } from "../core/types.js";
+
+export function tsx(entry: string, watch?: boolean): ICommand {
+	let command = cmd("tsx");
+	if (watch) command = command.arg("watch");
+	return command.arg(entry);
+}
+
+export function nodemon(entry: string): ICommand {
+	return cmd("nodemon").arg(entry);
+}

package/src/orchestrator/runner/__tests__/event-bus.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from "vitest";
+import { createEventBus, type DevEvent } from "../event-bus.js";
+
+describe("createEventBus", () => {
+	it("emits events to listeners", () => {
+		const bus = createEventBus();
+		const listener = vi.fn();
+		bus.on(listener);
+
+		const event: DevEvent = { type: "stack:ready" };
+		bus.emit(event);
+
+		expect(listener).toHaveBeenCalledWith(event);
+	});
+
+	it("supports multiple listeners", () => {
+		const bus = createEventBus();
+		const l1 = vi.fn();
+		const l2 = vi.fn();
+		bus.on(l1);
+		bus.on(l2);
+
+		bus.emit({ type: "stack:ready" });
+
+		expect(l1).toHaveBeenCalledOnce();
+		expect(l2).toHaveBeenCalledOnce();
+	});
+
+	it("removes listeners with off()", () => {
+		const bus = createEventBus();
+		const listener = vi.fn();
+		bus.on(listener);
+		bus.off(listener);
+
+		bus.emit({ type: "stack:ready" });
+
+		expect(listener).not.toHaveBeenCalled();
+	});
+
+	it("emits process:registered with meta", () => {
+		const bus = createEventBus();
+		const listener = vi.fn();
+		bus.on(listener);
+
+		bus.emit({
+			data: {
+				command: "next dev --port 3456",
+				cwd: "/apps/web",
+				id: "web:dev",
+				serviceName: "web",
+			},
+			type: "process:registered",
+		});
+
+		expect(listener).toHaveBeenCalledWith(
+			expect.objectContaining({ type: "process:registered" }),
+		);
+	});
+
+	it("emits log entries with timestamp", () => {
+		const bus = createEventBus();
+		const events: DevEvent[] = [];
+		bus.on((e) => events.push(e));
+
+		bus.emit({
+			data: {
+				id: "api:dev",
+				line: "Server listening on port 3000",
+				serviceName: "api",
+				stream: "stdout",
+				timestamp: Date.now(),
+			},
+			type: "log",
+		});
+
+		expect(events).toHaveLength(1);
+		expect(events[0].type).toBe("log");
+	});
+
+	it("emits stack:failed with error details", () => {
+		const bus = createEventBus();
+		const listener = vi.fn();
+		bus.on(listener);
+
+		bus.emit({
+			data: { error: "Process crashed", service: "api" },
+			type: "stack:failed",
+		});
+
+		expect(listener).toHaveBeenCalledWith(
+			expect.objectContaining({
+				data: { error: "Process crashed", service: "api" },
+				type: "stack:failed",
+			}),
+		);
+	});
+});

package/src/orchestrator/runner/event-bus.ts

@@ -0,0 +1,55 @@
+import type { ProcessStatus } from "../core/types.js";
+
+// ─── Event payload types ─────────────────────────────────────────────────────
+
+export interface ProcessMeta {
+	command: string;
+	cwd: string;
+	id: string;
+	serviceName: string;
+}
+
+export interface LogEntry {
+	id: string;
+	line: string;
+	serviceName: string;
+	stream: "stderr" | "stdout";
+	timestamp: number;
+}
+
+// ─── Event union ─────────────────────────────────────────────────────────────
+
+export type DevEvent =
+	| { data: LogEntry; type: "log" }
+	| { data: ProcessMeta; type: "process:registered" }
+	| { data: { id: string; status: ProcessStatus }; type: "process:status" }
+	| { data: { error: string; service: string }; type: "stack:failed" }
+	| { type: "stack:ready" };
+
+// ─── EventBus ────────────────────────────────────────────────────────────────
+
+type Listener = (event: DevEvent) => void;
+
+export interface IEventBus {
+	emit(event: DevEvent): void;
+	off(listener: Listener): void;
+	on(listener: Listener): void;
+}
+
+export function createEventBus(): IEventBus {
+	const listeners = new Set<Listener>();
+
+	return {
+		emit(event: DevEvent): void {
+			for (const listener of listeners) {
+				listener(event);
+			}
+		},
+		off(listener: Listener): void {
+			listeners.delete(listener);
+		},
+		on(listener: Listener): void {
+			listeners.add(listener);
+		},
+	};
+}

package/src/orchestrator/runner/health-runner.ts

@@ -0,0 +1,129 @@
+import { createConnection } from "node:net";
+import { resolveToken } from "../core/token.js";
+import type { ComputeContext, HealthCheck } from "../core/types.js";
+import type { OrchestratorProcess } from "./process.js";
+
+interface HealthCheckOptions {
+	intervalMs?: number;
+	maxRetries?: number;
+	timeoutMs?: number;
+}
+
+const DEFAULT_INTERVAL = 1000;
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_RETRIES = 30;
+
+export async function waitForHealthy(
+	check: HealthCheck,
+	ctx: ComputeContext,
+	proc: OrchestratorProcess,
+	options: HealthCheckOptions = {},
+): Promise<void> {
+	const interval = options.intervalMs ?? DEFAULT_INTERVAL;
+	const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT;
+	const maxRetries = options.maxRetries ?? DEFAULT_RETRIES;
+
+	const startTime = Date.now();
+	let retries = 0;
+
+	while (retries < maxRetries && Date.now() - startTime < timeout) {
+		// Bail if process died
+		if (proc.status === "failed" || proc.status === "completed") {
+			throw new Error(
+				`Process "${proc.serviceName}" exited before becoming healthy`,
+			);
+		}
+
+		try {
+			const healthy = await runCheck(check, ctx, proc);
+			if (healthy) return;
+		} catch {
+			// Check failed, retry
+		}
+
+		retries++;
+		await sleep(interval);
+	}
+
+	throw new Error(
+		`Health check for "${proc.serviceName}" timed out after ${timeout}ms (${retries} retries)`,
+	);
+}
+
+async function runCheck(
+	check: HealthCheck,
+	ctx: ComputeContext,
+	proc: OrchestratorProcess,
+): Promise<boolean> {
+	switch (check.type) {
+		case "tcp":
+			return checkTcp(
+				await resolveToken(check.host, ctx),
+				Number.parseInt(await resolveToken(check.port, ctx), 10),
+			);
+
+		case "http": {
+			const resolvedUrl = await resolveToken(check.url, ctx);
+			return checkHttp(resolvedUrl, check.status);
+		}
+
+		case "stdout":
+			return checkStdout(check.pattern, proc);
+
+		case "exec": {
+			const built = await check.command.build(ctx);
+			const fullCmd = [built.command, ...built.args].join(" ");
+			const { execa } = await import("execa");
+			const result = await execa({ reject: false, shell: true })`${fullCmd}`;
+			return result.exitCode === 0;
+		}
+
+		case "custom":
+			return check.check();
+
+		default:
+			throw new Error(
+				`Unknown health check type: ${(check as { type: string }).type}`,
+			);
+	}
+}
+
+function checkTcp(host: string, port: number): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = createConnection({ host, port }, () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.on("error", () => {
+			socket.destroy();
+			resolve(false);
+		});
+		socket.setTimeout(2000, () => {
+			socket.destroy();
+			resolve(false);
+		});
+	});
+}
+
+async function checkHttp(
+	url: string,
+	expectedStatus?: number,
+): Promise<boolean> {
+	try {
+		const response = await fetch(url, {
+			signal: AbortSignal.timeout(2000),
+		});
+		if (expectedStatus) return response.status === expectedStatus;
+		return response.ok;
+	} catch {
+		return false;
+	}
+}
+
+function checkStdout(pattern: RegExp, proc: OrchestratorProcess): boolean {
+	return proc.outputLines.some((line) => pattern.test(line));
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/orchestrator/runner/index.ts

@@ -0,0 +1,17 @@
+export {
+	createEventBus,
+	type DevEvent,
+	type IEventBus,
+	type LogEntry,
+	type ProcessMeta,
+} from "./event-bus.js";
+export { waitForHealthy } from "./health-runner.js";
+export { type OrchestratorProcess, spawnProcess } from "./process.js";
+export {
+	clearRuntimeContext,
+	createDeferred,
+	type Deferred,
+	getRuntimeContext,
+	type RuntimeContext,
+	setRuntimeContext,
+} from "./runtime-context.js";