@buildepicshit/cli 0.0.2 → 0.0.4

package/src/orchestrator/presets/nextjs.ts

@@ -0,0 +1,97 @@
+import { cmd } from "../core/command.js";
+import type {
+	BuiltCommand,
+	ComputeContext,
+	EnvSource,
+	HealthCheck,
+	HealthCheckCallback,
+	ICommand,
+	IdentityAccessor,
+	Runnable,
+	Token,
+} from "../core/types.js";
+
+export interface INextjs extends ICommand {}
+
+/** @deprecated Use `INextjs` instead */
+export type NextPreset = INextjs;
+
+class Nextjs implements INextjs {
+	readonly __type = "command" as const;
+	private readonly inner: ICommand;
+
+	constructor(inner: ICommand) {
+		this.inner = inner;
+	}
+
+	// ─── ICommand delegation (returns INextjs for chaining) ─────────────
+
+	get identity(): IdentityAccessor {
+		const innerAccessor = this.inner.identity;
+		const self = this;
+		const setter = (suffix: string): INextjs => {
+			return new Nextjs(self.inner.identity(suffix));
+		};
+		Object.defineProperty(setter, "name", {
+			configurable: true,
+			value: innerAccessor.name,
+		});
+		return Object.assign(setter, {
+			localhostUrl: innerAccessor.localhostUrl,
+			port: innerAccessor.port,
+			url: innerAccessor.url,
+		}) as IdentityAccessor;
+	}
+
+	flag(name: string, value?: Token): INextjs {
+		return new Nextjs(this.inner.flag(name, value));
+	}
+
+	arg(value: Token): INextjs {
+		return new Nextjs(this.inner.arg(value));
+	}
+
+	env(source: EnvSource): INextjs {
+		return new Nextjs(this.inner.env(source));
+	}
+
+	dir(path: string): INextjs {
+		return new Nextjs(this.inner.dir(path));
+	}
+
+	waitFor(check: HealthCheck | HealthCheckCallback): INextjs {
+		return new Nextjs(this.inner.waitFor(check));
+	}
+
+	as(name: string): INextjs {
+		return new Nextjs(this.inner.as(name));
+	}
+
+	dependsOn(...deps: Runnable[]): INextjs {
+		return new Nextjs(this.inner.dependsOn(...deps));
+	}
+
+	collectNames(): string[] {
+		return this.inner.collectNames();
+	}
+
+	build(ctx: ComputeContext): Promise<BuiltCommand> {
+		return this.inner.build(ctx);
+	}
+
+	run(): Promise<void> {
+		return this.inner.run();
+	}
+}
+
+export function nextjs(): INextjs {
+	// Base: `next` with PORT from identity. Mode (.arg("dev"/"start"/"build"))
+	// and health checks are added by the consumer.
+	const inner = cmd("next").env((self) => ({
+		PORT: self.identity.port(),
+	}));
+	return new Nextjs(inner);
+}
+
+/** @deprecated Use `nextjs()` instead */
+export const next = nextjs;

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";

package/src/orchestrator/runner/process.ts

@@ -0,0 +1,167 @@
+import { join } from "node:path";
+import { execa, type ResultPromise } from "execa";
+import type { BuiltCommand, ProcessStatus } from "../core/types.js";
+import { getRuntimeContext } from "./runtime-context.js";
+
+const KILL_TIMEOUT_MS = 5000;
+
+export interface OrchestratorProcess {
+	readonly id: string;
+	kill(): Promise<void>;
+	onOutput(listener: (line: string, stream: "stderr" | "stdout") => void): void;
+	readonly outputLines: string[];
+	readonly serviceName: string;
+	setStatus(status: ProcessStatus): void;
+	readonly status: ProcessStatus;
+	waitFor(condition: "completed" | "healthy" | "started"): Promise<void>;
+}
+
+export function spawnProcess(
+	id: string,
+	serviceName: string,
+	built: BuiltCommand,
+): OrchestratorProcess {
+	let currentStatus: ProcessStatus = "starting";
+	const outputLines: string[] = [];
+	const outputListeners: Array<
+		(line: string, stream: "stderr" | "stdout") => void
+	> = [];
+	const waiters = new Map<string, Array<() => void>>();
+
+	function setStatus(s: ProcessStatus) {
+		currentStatus = s;
+		const callbacks = waiters.get(s);
+		if (callbacks) {
+			for (const cb of callbacks) cb();
+			waiters.delete(s);
+		}
+	}
+
+	const fullCommand = [built.command, ...built.args].join(" ");
+
+	// Prepend node_modules/.bin from both the process cwd and the workspace root
+	// to PATH. This mirrors `pnpm exec` behavior: local binaries (tsx, next, etc.)
+	// resolve from the pnpm store with correct module resolution context.
+	const rtx = getRuntimeContext();
+	const localBin = join(built.cwd, "node_modules", ".bin");
+	const rootBin = join(rtx.root, "node_modules", ".bin");
+	const currentPath = process.env.PATH ?? "";
+	const enhancedPath = `${localBin}:${rootBin}:${currentPath}`;
+
+	const child: ResultPromise = execa({
+		cwd: built.cwd,
+		env: { ...process.env, ...built.env, FORCE_COLOR: "1", PATH: enhancedPath },
+		reject: false,
+		shell: true,
+		stderr: "pipe",
+		stdout: "pipe",
+	})`${fullCommand}`;
+
+	setStatus("running");
+
+	child.stdout?.on("data", (data: Buffer) => {
+		const text = data.toString();
+		for (const line of text.split("\n").filter(Boolean)) {
+			outputLines.push(line);
+			for (const listener of outputListeners) {
+				listener(line, "stdout");
+			}
+		}
+	});
+
+	child.stderr?.on("data", (data: Buffer) => {
+		const text = data.toString();
+		for (const line of text.split("\n").filter(Boolean)) {
+			outputLines.push(line);
+			for (const listener of outputListeners) {
+				listener(line, "stderr");
+			}
+		}
+	});
+
+	child.then((result) => {
+		if (currentStatus !== "failed") {
+			setStatus(result.exitCode === 0 ? "completed" : "failed");
+		}
+	});
+
+	return {
+		id,
+
+		async kill() {
+			const s = currentStatus;
+			if (s === "completed" || s === "failed") return;
+
+			child.kill("SIGTERM");
+
+			await Promise.race([
+				child,
+				new Promise<void>((resolve) => setTimeout(resolve, KILL_TIMEOUT_MS)),
+			]);
+
+			// Re-read: status may have changed during the await
+			const afterWait: ProcessStatus = currentStatus;
+			if (afterWait !== "completed" && afterWait !== "failed") {
+				child.kill("SIGKILL");
+			}
+		},
+
+		onOutput(listener) {
+			outputListeners.push(listener);
+		},
+		outputLines,
+		serviceName,
+		setStatus,
+
+		get status() {
+			return currentStatus;
+		},
+
+		async waitFor(condition) {
+			const satisfies = (s: ProcessStatus) => {
+				if (condition === "started") return s !== "pending" && s !== "starting";
+				if (condition === "healthy")
+					return s === "healthy" || s === "completed";
+				if (condition === "completed") return s === "completed";
+				return false;
+			};
+
+			if (satisfies(currentStatus)) return;
+			if (currentStatus === "failed") {
+				throw new Error(
+					`Process "${serviceName}" failed before reaching "${condition}"`,
+				);
+			}
+
+			return new Promise<void>((resolve, reject) => {
+				const tryResolve = (targetStatus: string) => {
+					const existing = waiters.get(targetStatus) ?? [];
+					existing.push(resolve);
+					waiters.set(targetStatus, existing);
+				};
+
+				if (condition === "started") {
+					tryResolve("running");
+					tryResolve("healthy");
+					tryResolve("completed");
+				} else if (condition === "healthy") {
+					tryResolve("healthy");
+					tryResolve("completed");
+				} else {
+					tryResolve("completed");
+				}
+
+				// Also listen for failure
+				const failCallbacks = waiters.get("failed") ?? [];
+				failCallbacks.push(() =>
+					reject(
+						new Error(
+							`Process "${serviceName}" failed before reaching "${condition}"`,
+						),
+					),
+				);
+				waiters.set("failed", failCallbacks);
+			});
+		},
+	};
+}

package/src/orchestrator/runner/runtime-context.ts

@@ -0,0 +1,51 @@
+import type { EnvSource } from "../core/types.js";
+import type { Logger } from "../logger/logger.js";
+import type { IEventBus } from "./event-bus.js";
+import type { OrchestratorProcess } from "./process.js";
+
+export interface Deferred {
+	promise: Promise<void>;
+	resolve: () => void;
+}
+
+export function createDeferred(): Deferred {
+	let resolve!: () => void;
+	const promise = new Promise<void>((r) => {
+		resolve = r;
+	});
+	return { promise, resolve };
+}
+
+export interface RuntimeContext {
+	dryRun: boolean;
+	eventBus: IEventBus;
+	/** Dir inherited from nearest parent compound that set .dir() */
+	inheritedDir: string | null;
+	/** Env sources inherited from parent compounds (outermost first) */
+	inheritedEnv: EnvSource[];
+	logger: Logger;
+	processes: Map<string, OrchestratorProcess>;
+	/** Resolved when a command finishes its health check / startup */
+	readyPromises: Map<string, Deferred>;
+	root: string;
+}
+
+const CONTEXT_KEY = "__bes_runtime_context__";
+
+export function setRuntimeContext(ctx: RuntimeContext): void {
+	(globalThis as Record<string, unknown>)[CONTEXT_KEY] = ctx;
+}
+
+export function getRuntimeContext(): RuntimeContext {
+	const ctx = (globalThis as Record<string, unknown>)[CONTEXT_KEY] as
+		| RuntimeContext
+		| undefined;
+	if (!ctx) {
+		throw new Error("No runtime context — are you running via the `bes` CLI?");
+	}
+	return ctx;
+}
+
+export function clearRuntimeContext(): void {
+	delete (globalThis as Record<string, unknown>)[CONTEXT_KEY];
+}