@buildepicshit/cli 0.0.2 → 0.0.3

package/package.json

@@ -19,7 +19,8 @@
 		".": "./src/orchestrator/index.ts"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"src"
 	],
 	"name": "@buildepicshit/cli",
 	"publishConfig": {
@@ -33,5 +34,5 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"type": "module",
-	"version": "0.0.2"
+	"version": "0.0.3"
 }

package/src/bes.ts

@@ -0,0 +1,124 @@
+import { Command } from "commander";
+import { loadConfig } from "./config-loader.js";
+import { createLazyLogger } from "./orchestrator/logger/logger.js";
+import { createEventBus } from "./orchestrator/runner/event-bus.js";
+import {
+	clearRuntimeContext,
+	getRuntimeContext,
+	setRuntimeContext,
+} from "./orchestrator/runner/runtime-context.js";
+
+const program = new Command();
+
+program
+	.name("bes")
+	.description("Build Epic Shit — dev process manager CLI")
+	.version("0.1.0")
+	.option("--dry", "Resolve all tokens and print commands without executing");
+
+async function main() {
+	const { root, commands } = await loadConfig();
+
+	// Register each exported function as a CLI command
+	for (const [name, fn] of Object.entries(commands)) {
+		program
+			.command(name)
+			.description(`Run ${name}() from bes.config.ts`)
+			.action(async () => {
+				const isDry = program.opts().dry ?? false;
+				const logger = createLazyLogger();
+				const eventBus = createEventBus();
+
+				setRuntimeContext({
+					dryRun: isDry,
+					eventBus,
+					inheritedDir: null,
+					inheritedEnv: [],
+					logger,
+					processes: new Map(),
+					readyPromises: new Map(),
+					root,
+				});
+
+				const cleanup = async () => {
+					try {
+						const rtx = getRuntimeContext();
+						logger.system("Shutting down...");
+						const kills = [...rtx.processes.values()]
+							.reverse()
+							.map((p) => p.kill());
+						await Promise.allSettled(kills);
+					} catch {
+						// context may already be cleared
+					}
+					process.exit(0);
+				};
+
+				process.on("SIGINT", cleanup);
+				process.on("SIGTERM", cleanup);
+
+				try {
+					if (isDry) {
+						logger.system("Dry run — resolving all commands:\n");
+					}
+
+					await fn();
+
+					// After fn() returns, wait for long-running processes
+					const rtx = getRuntimeContext();
+					const running = [...rtx.processes.values()].filter(
+						(p) => p.status === "running" || p.status === "healthy",
+					);
+
+					if (running.length > 0) {
+						await Promise.all(
+							running.map(
+								(p) =>
+									new Promise<void>((resolve) => {
+										const check = () => {
+											if (p.status === "completed" || p.status === "failed") {
+												resolve();
+											} else {
+												setTimeout(check, 500);
+											}
+										};
+										check();
+									}),
+							),
+						);
+					}
+				} catch (error) {
+					logger.system(
+						`Error: ${error instanceof Error ? error.message : String(error)}`,
+					);
+					const rtx = getRuntimeContext();
+					const kills = [...rtx.processes.values()]
+						.reverse()
+						.map((p) => p.kill());
+					await Promise.allSettled(kills);
+					process.exit(1);
+				} finally {
+					process.removeListener("SIGINT", cleanup);
+					process.removeListener("SIGTERM", cleanup);
+					clearRuntimeContext();
+				}
+			});
+	}
+
+	// No args → list available commands
+	if (process.argv.length <= 2) {
+		console.log("Available commands:\n");
+		for (const name of Object.keys(commands)) {
+			console.log(`  bes ${name}`);
+		}
+		console.log("");
+		process.exit(0);
+	}
+
+	program.parse();
+}
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+});

package/src/config-loader.ts

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createJiti } from "jiti";
+
+const CONFIG_FILENAME = "bes.config.ts";
+
+/**
+ * Walk up from `startDir` to find the nearest `bes.config.ts`.
+ */
+function findConfigFile(startDir: string): string | null {
+	let dir = resolve(startDir);
+
+	while (true) {
+		const candidate = join(dir, CONFIG_FILENAME);
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) break; // reached filesystem root
+		dir = parent;
+	}
+
+	return null;
+}
+
+export interface ConfigResult {
+	commands: Record<string, () => Promise<void>>;
+	root: string;
+}
+
+/**
+ * Load `bes.config.ts` and discover all exported async functions.
+ * Each exported function becomes a CLI command.
+ */
+export async function loadConfig(
+	cwd: string = process.cwd(),
+): Promise<ConfigResult> {
+	const configPath = findConfigFile(cwd);
+	if (!configPath) {
+		throw new Error(
+			`Could not find ${CONFIG_FILENAME} in ${cwd} or any parent directory`,
+		);
+	}
+
+	const jiti = createJiti(configPath, {
+		fsCache: false,
+		interopDefault: true,
+	});
+
+	const mod = (await jiti.import(configPath)) as Record<string, unknown>;
+
+	const commands: Record<string, () => Promise<void>> = {};
+	for (const [key, value] of Object.entries(mod)) {
+		if (key === "default") continue;
+		if (typeof value === "function") {
+			commands[key] = value as () => Promise<void>;
+		}
+	}
+
+	if (Object.keys(commands).length === 0) {
+		throw new Error(
+			`${CONFIG_FILENAME} must export at least one async function`,
+		);
+	}
+
+	return {
+		commands,
+		root: dirname(configPath),
+	};
+}

package/src/daemon.ts

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * FNV-1a hash producing a deterministic port in the ephemeral range 49152-65535.
+ * Avoids collisions with user script ports (3000-8999).
+ */
+export function deterministicServerPort(projectPath: string): number {
+	const input = `bes:server:${projectPath}`;
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return (hash % 16383) + 49152;
+}
+
+export interface ServerInfo {
+	host: string;
+	pid: number;
+	port: number;
+	url: string;
+}
+
+function besDir(): string {
+	return join(process.cwd(), ".bes");
+}
+
+function serverInfoPath(): string {
+	return join(besDir(), "server.json");
+}
+
+export function readServerInfo(): ServerInfo | null {
+	const path = serverInfoPath();
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as ServerInfo;
+	} catch {
+		return null;
+	}
+}
+
+function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function healthCheck(url: string): Promise<boolean> {
+	try {
+		const res = await fetch(`${url}/health`, {
+			signal: AbortSignal.timeout(1000),
+		});
+		return res.ok;
+	} catch {
+		return false;
+	}
+}
+
+export async function isServerRunning(): Promise<ServerInfo | null> {
+	const info = readServerInfo();
+	if (!info) return null;
+	if (!isPidAlive(info.pid)) return null;
+	const alive = await healthCheck(info.url);
+	return alive ? info : null;
+}
+
+async function poll(url: string, maxMs: number): Promise<boolean> {
+	const start = Date.now();
+	while (Date.now() - start < maxMs) {
+		if (await healthCheck(url)) return true;
+		await new Promise((r) => setTimeout(r, 300));
+	}
+	return false;
+}
+
+export async function ensureServerRunning(): Promise<ServerInfo> {
+	const existing = await isServerRunning();
+	if (existing) return existing;
+
+	const port = process.env.BES_PORT
+		? Number(process.env.BES_PORT)
+		: deterministicServerPort(process.cwd());
+	const host = process.env.BES_HOST ?? "0.0.0.0";
+	const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
+
+	const child = spawn("npx", ["tsx", "apps/server/src/main.ts"], {
+		cwd: process.cwd(),
+		detached: true,
+		env: {
+			...process.env,
+			BES_CONFIG_DIR: process.cwd(),
+			BES_HOST: host,
+			BES_PORT: String(port),
+		},
+		stdio: "ignore",
+	});
+
+	child.unref();
+
+	if (!child.pid) {
+		throw new Error("Failed to spawn server process");
+	}
+
+	const dir = besDir();
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+	const info: ServerInfo = {
+		host,
+		pid: child.pid,
+		port,
+		url,
+	};
+
+	writeFileSync(serverInfoPath(), JSON.stringify(info, null, "\t"));
+
+	const ready = await poll(url, 6000);
+	if (!ready) {
+		throw new Error("Server failed to start within 6 seconds");
+	}
+
+	return info;
+}

package/src/orchestrator/core/__tests__/command.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import { cmd } from "../command.js";
+import { health } from "../health-check.js";
+import { compute } from "../token.js";
+import type { ComputeContext } from "../types.js";
+
+const ctx: ComputeContext = {
+	cwd: "/app",
+	env: { NODE_ENV: "production" },
+	root: "/",
+};
+
+describe("cmd", () => {
+	it("builds a simple command", async () => {
+		const built = await cmd("next dev").build(ctx);
+		expect(built.command).toBe("next dev");
+		expect(built.args).toEqual([]);
+		expect(built.cwd).toBe("/app");
+	});
+
+	it("adds positional args", async () => {
+		const built = await cmd("docker compose").arg("up").build(ctx);
+		expect(built.command).toBe("docker compose");
+		expect(built.args).toEqual(["up"]);
+	});
+
+	it("adds boolean flags (no value)", async () => {
+		const built = await cmd("docker compose")
+			.arg("up")
+			.flag("detach")
+			.build(ctx);
+		expect(built.args).toEqual(["--detach", "up"]);
+	});
+
+	it("adds flags with values", async () => {
+		const built = await cmd("next dev").flag("port", "3000").build(ctx);
+		expect(built.args).toEqual(["--port", "3000"]);
+	});
+
+	it("resolves compute tokens in flags", async () => {
+		const token = compute(async ({ env }) =>
+			env.NODE_ENV === "production" ? "8080" : "3000",
+		);
+		const built = await cmd("next dev").flag("port", token).build(ctx);
+		expect(built.args).toEqual(["--port", "8080"]);
+	});
+
+	it("adds env vars via record", async () => {
+		const built = await cmd("node server.js")
+			.env({ DATABASE_URL: "postgres://localhost/db" })
+			.build(ctx);
+		expect(built.env).toEqual({ DATABASE_URL: "postgres://localhost/db" });
+	});
+
+	it("merges multiple env sources", async () => {
+		const built = await cmd("node server.js")
+			.env({ A: "1" })
+			.env({ A: "overridden", B: "2" })
+			.build(ctx);
+		expect(built.env).toEqual({ A: "overridden", B: "2" });
+	});
+
+	it("resolves token values in env records", async () => {
+		const token = compute(async () => "resolved-value");
+		const built = await cmd("node server.js").env({ KEY: token }).build(ctx);
+		expect(built.env).toEqual({ KEY: "resolved-value" });
+	});
+
+	it("is immutable — each method returns a new instance", async () => {
+		const base = cmd("next");
+		const withDev = base.arg("dev");
+		const withPort = withDev.flag("port", "3000");
+
+		const built1 = await base.build(ctx);
+		const built2 = await withDev.build(ctx);
+		const built3 = await withPort.build(ctx);
+
+		expect(built1.args).toEqual([]);
+		expect(built2.args).toEqual(["dev"]);
+		expect(built3.args).toEqual(["--port", "3000", "dev"]);
+	});
+
+	it("handles multiple flags and args in order", async () => {
+		const built = await cmd("docker compose")
+			.flag("file", "docker-compose.ci.yml")
+			.arg("up")
+			.flag("detach")
+			.build(ctx);
+
+		expect(built.args).toEqual([
+			"--file",
+			"docker-compose.ci.yml",
+			"--detach",
+			"up",
+		]);
+	});
+
+	it("sets dir", () => {
+		const c = cmd("next dev").dir("apps/web");
+		expect(c.collectNames()).toEqual(["web"]);
+	});
+
+	it("sets display name with .as()", () => {
+		const c = cmd("tsx watch src/main.ts").as("api");
+		expect(c.collectNames()).toEqual(["api"]);
+	});
+
+	it("derives name from base command when no dir or as", () => {
+		const c = cmd("tsx watch src/main.ts");
+		expect(c.collectNames()).toEqual(["tsx"]);
+	});
+
+	it("derives name from dir basename", () => {
+		const c = cmd("tsx watch src/main.ts").dir("apps/api");
+		expect(c.collectNames()).toEqual(["api"]);
+	});
+});
+
+describe("command identity", () => {
+	it("returns default identity from dir basename", () => {
+		const c = cmd("node server.js").dir("apps/api");
+		const id = c.identity();
+		expect(id.name).toBe("api");
+	});
+
+	it("returns default identity from display name", () => {
+		const c = cmd("node server.js").as("my-service");
+		expect(c.identity().name).toBe("my-service");
+	});
+
+	it("returns default identity from base command", () => {
+		const c = cmd("tsx watch src/main.ts");
+		expect(c.identity().name).toBe("tsx");
+	});
+
+	it("overrides identity with .identity(suffix)", () => {
+		const c = cmd("node server.js").identity("custom").dir("apps/api");
+		expect(c.identity().name).toBe("custom");
+	});
+
+	it("identity suffix propagates through builder chain", () => {
+		const c = cmd("node server.js")
+			.identity("api")
+			.dir("apps/server")
+			.env({ KEY: "value" })
+			.flag("verbose");
+		expect(c.identity().name).toBe("api");
+	});
+
+	it("identity is immutable across branches", () => {
+		const base = cmd("node server.js");
+		const withId = base.identity("custom");
+		expect(base.identity().name).toBe("node");
+		expect(withId.identity().name).toBe("custom");
+	});
+
+	it("identity().port() returns a token", async () => {
+		const c = cmd("node server.js").identity("api").dir("apps/api");
+		const token = c.identity().port();
+		expect(typeof token).toBe("function");
+		const port = Number.parseInt(
+			await (token as (ctx: ComputeContext) => Promise<string>)(ctx),
+			10,
+		);
+		expect(port).toBeGreaterThanOrEqual(3000);
+		expect(port).toBeLessThanOrEqual(9999);
+	});
+
+	it("identity().localhostUrl() returns a token", async () => {
+		const c = cmd("node server.js").identity("api");
+		const token = c.identity().localhostUrl("/health");
+		const url = await (token as (ctx: ComputeContext) => Promise<string>)(ctx);
+		expect(url).toMatch(/^http:\/\/localhost:\d+\/health$/);
+	});
+
+	it("cross-command identity access works", async () => {
+		const server = cmd("node server.js").identity("api").dir("apps/api");
+		const built = await cmd("next dev")
+			.env({ API_URL: server.identity().localhostUrl() })
+			.build(ctx);
+		expect(built.env.API_URL).toMatch(/^http:\/\/localhost:\d+$/);
+	});
+});
+
+describe("waitFor callback form", () => {
+	it("accepts a callback that receives the command", async () => {
+		const c = cmd("node server.js")
+			.identity("api")
+			.dir("apps/api")
+			.waitFor((self) => health.http(self.identity().url("/livez")));
+
+		const built = await c.build(ctx);
+		expect(built).toBeDefined();
+		expect(c.identity().name).toBe("api");
+	});
+});
+
+describe("env callback form", () => {
+	it("accepts a callback that receives the command", async () => {
+		const c = cmd("node server.js")
+			.identity("api")
+			.env((self) => ({ PORT: self.identity().port() }));
+
+		const built = await c.build(ctx);
+		const port = Number.parseInt(built.env.PORT, 10);
+		expect(port).toBeGreaterThanOrEqual(3000);
+		expect(port).toBeLessThanOrEqual(9999);
+	});
+
+	it("mixes callback env with record env", async () => {
+		const c = cmd("node server.js")
+			.identity("api")
+			.env({ A: "1" })
+			.env((self) => ({ PORT: self.identity().port() }))
+			.env({ B: "2" });
+
+		const built = await c.build(ctx);
+		expect(built.env.A).toBe("1");
+		expect(built.env.B).toBe("2");
+		expect(Number.parseInt(built.env.PORT, 10)).toBeGreaterThanOrEqual(3000);
+	});
+});

package/src/orchestrator/core/__tests__/token.test.ts

@@ -0,0 +1,145 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+	compute,
+	fromEnv,
+	fromFile,
+	fromPackageJson,
+	resolveToken,
+} from "../token.js";
+import type { ComputeContext } from "../types.js";
+
+const ctx: ComputeContext = {
+	cwd: "/test",
+	env: { NODE_ENV: "test", PORT: "4000" },
+	root: "/",
+};
+
+describe("resolveToken", () => {
+	it("resolves a plain string", async () => {
+		expect(await resolveToken("hello", ctx)).toBe("hello");
+	});
+
+	it("resolves a compute function", async () => {
+		const token = compute(async ({ env }) => env.NODE_ENV);
+		expect(await resolveToken(token, ctx)).toBe("test");
+	});
+});
+
+describe("fromEnv", () => {
+	it("reads an env var", async () => {
+		const token = fromEnv("PORT");
+		expect(await resolveToken(token, ctx)).toBe("4000");
+	});
+
+	it("uses fallback when var is missing", async () => {
+		const token = fromEnv("MISSING", "default");
+		expect(await resolveToken(token, ctx)).toBe("default");
+	});
+
+	it("throws when var is missing and no fallback", async () => {
+		const token = fromEnv("MISSING");
+		await expect(resolveToken(token, ctx)).rejects.toThrow(
+			'Environment variable "MISSING" is not set',
+		);
+	});
+});
+
+describe("fromPackageJson", () => {
+	let tempDir: string;
+
+	beforeAll(async () => {
+		tempDir = join(tmpdir(), `bes-test-${Date.now()}`);
+		await mkdir(tempDir, { recursive: true });
+		await writeFile(
+			join(tempDir, "package.json"),
+			JSON.stringify({
+				config: { nested: { deep: "value" }, port: 3000 },
+				name: "test-pkg",
+			}),
+		);
+	});
+
+	afterAll(async () => {
+		await rm(tempDir, { force: true, recursive: true });
+	});
+
+	it("reads a top-level field", async () => {
+		const token = fromPackageJson("name");
+		const tempCtx = { ...ctx, cwd: tempDir };
+		expect(await resolveToken(token, tempCtx)).toBe("test-pkg");
+	});
+
+	it("reads a nested field via dot notation", async () => {
+		const token = fromPackageJson("config.port");
+		const tempCtx = { ...ctx, cwd: tempDir };
+		expect(await resolveToken(token, tempCtx)).toBe("3000");
+	});
+
+	it("reads deeply nested fields", async () => {
+		const token = fromPackageJson("config.nested.deep");
+		const tempCtx = { ...ctx, cwd: tempDir };
+		expect(await resolveToken(token, tempCtx)).toBe("value");
+	});
+
+	it("uses fallback when path is missing", async () => {
+		const token = fromPackageJson("missing.path", "fallback");
+		const tempCtx = { ...ctx, cwd: tempDir };
+		expect(await resolveToken(token, tempCtx)).toBe("fallback");
+	});
+
+	it("throws when path is missing and no fallback", async () => {
+		const token = fromPackageJson("missing.path");
+		const tempCtx = { ...ctx, cwd: tempDir };
+		await expect(resolveToken(token, tempCtx)).rejects.toThrow(
+			'package.json path "missing.path" not found',
+		);
+	});
+});
+
+describe("fromFile", () => {
+	let tempDir: string;
+
+	beforeAll(async () => {
+		tempDir = join(tmpdir(), `bes-env-test-${Date.now()}`);
+		await mkdir(tempDir, { recursive: true });
+		await writeFile(
+			join(tempDir, ".env"),
+			"DB_HOST=localhost\nDB_PORT=5432\n# comment\n\nDB_NAME=mydb\n",
+		);
+		await writeFile(
+			join(tempDir, ".env.local"),
+			'DB_PORT=5433\nSECRET="quoted-value"\n',
+		);
+	});
+
+	afterAll(async () => {
+		await rm(tempDir, { force: true, recursive: true });
+	});
+
+	it("parses a .env file", async () => {
+		const source = fromFile(".env");
+		const result = await source.resolve({ ...ctx, cwd: tempDir });
+		expect(result).toEqual({
+			DB_HOST: "localhost",
+			DB_NAME: "mydb",
+			DB_PORT: "5432",
+		});
+	});
+
+	it("merges multiple files (last wins)", async () => {
+		const source = fromFile(".env", ".env.local");
+		const result = await source.resolve({ ...ctx, cwd: tempDir });
+		expect(result.DB_PORT).toBe("5433");
+		expect(result.DB_HOST).toBe("localhost");
+		expect(result.SECRET).toBe("quoted-value");
+	});
+
+	it("skips missing files silently", async () => {
+		const source = fromFile(".env.missing", ".env");
+		const result = await source.resolve({ ...ctx, cwd: tempDir });
+		expect(result.DB_HOST).toBe("localhost");
+	});
+});