@buildepicshit/cli 0.0.2 → 0.0.4

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");
+	});
+});

package/src/orchestrator/core/command.ts

@@ -0,0 +1,334 @@
+import { basename, resolve } from "node:path";
+import { waitForHealthy } from "../runner/health-runner.js";
+import { spawnProcess } from "../runner/process.js";
+import {
+	createDeferred,
+	getRuntimeContext,
+} from "../runner/runtime-context.js";
+import { createIdentity } from "../utils/dna.js";
+import { resolveToken } from "./token.js";
+import {
+	type BuiltCommand,
+	type ComputeContext,
+	type EnvSource,
+	type HealthCheck,
+	type HealthCheckCallback,
+	type ICommand,
+	type IdentityAccessor,
+	isEnvCallback,
+	isLazyEnvSource,
+	type Runnable,
+	type Token,
+} from "./types.js";
+
+interface CommandState {
+	readonly args: readonly Token[];
+	readonly base: string;
+	readonly dependencies: readonly Runnable[];
+	readonly dirPath: string | null;
+	readonly displayName: string | null;
+	readonly envSources: readonly EnvSource[];
+	readonly flags: readonly { name: string; value?: Token }[];
+	readonly healthChecks: readonly HealthCheck[];
+	readonly identitySuffix: string | null;
+}
+
+class Command implements ICommand {
+	readonly __type = "command" as const;
+	private readonly state: CommandState;
+
+	constructor(state: CommandState) {
+		this.state = state;
+	}
+
+	get identity(): IdentityAccessor {
+		const id = createIdentity(
+			this.state.identitySuffix ?? this.deriveName(),
+		);
+		const self = this;
+		const setter = (suffix: string): ICommand => {
+			return new Command({ ...self.state, identitySuffix: suffix });
+		};
+		// Function.name is read-only, must use defineProperty
+		Object.defineProperty(setter, "name", {
+			configurable: true,
+			value: id.name,
+		});
+		return Object.assign(setter, {
+			localhostUrl: id.localhostUrl,
+			port: id.port,
+			url: id.url,
+		}) as IdentityAccessor;
+	}
+
+	flag(name: string, value?: Token): ICommand {
+		return new Command({
+			...this.state,
+			flags: [...this.state.flags, { name, value }],
+		});
+	}
+
+	arg(value: Token): ICommand {
+		return new Command({
+			...this.state,
+			args: [...this.state.args, value],
+		});
+	}
+
+	env(source: EnvSource): ICommand {
+		if (isEnvCallback(source)) {
+			const resolved = source(this);
+			return new Command({
+				...this.state,
+				envSources: [...this.state.envSources, resolved],
+			});
+		}
+		return new Command({
+			...this.state,
+			envSources: [...this.state.envSources, source],
+		});
+	}
+
+	dir(path: string): ICommand {
+		return new Command({
+			...this.state,
+			dirPath: path,
+		});
+	}
+
+	waitFor(check: HealthCheck | HealthCheckCallback): ICommand {
+		const resolved = typeof check === "function" ? check(this) : check;
+		return new Command({
+			...this.state,
+			healthChecks: [...this.state.healthChecks, resolved],
+		});
+	}
+
+	as(name: string): ICommand {
+		return new Command({
+			...this.state,
+			displayName: name,
+		});
+	}
+
+	dependsOn(...deps: Runnable[]): ICommand {
+		return new Command({
+			...this.state,
+			dependencies: [...this.state.dependencies, ...deps],
+		});
+	}
+
+	collectNames(): string[] {
+		return [this.deriveName()];
+	}
+
+	async build(ctx: ComputeContext): Promise<BuiltCommand> {
+		const args: string[] = [];
+
+		for (const flag of this.state.flags) {
+			if (flag.value !== undefined) {
+				const resolved = await resolveToken(flag.value, ctx);
+				args.push(`--${flag.name}`, resolved);
+			} else {
+				args.push(`--${flag.name}`);
+			}
+		}
+
+		for (const arg of this.state.args) {
+			const resolved = await resolveToken(arg, ctx);
+			if (resolved) args.push(resolved);
+		}
+
+		// Resolve env: inherited sources first, then own sources (own wins)
+		const env: Record<string, string> = {};
+		for (const source of this.state.envSources) {
+			await mergeEnvSource(env, source, ctx);
+		}
+
+		return {
+			args,
+			command: this.state.base,
+			cwd: ctx.cwd,
+			env,
+		};
+	}
+
+	async run(): Promise<void> {
+		const rtx = getRuntimeContext();
+		const name = this.deriveName();
+
+		// Register a ready promise so dependents can wait on us
+		const deferred = createDeferred();
+		rtx.readyPromises.set(name, deferred);
+
+		// Wait for dependencies to be ready before starting
+		await this.waitForDependencies();
+
+		// Resolve cwd: own dir > inherited dir > root
+		const dirPath = this.state.dirPath ?? rtx.inheritedDir;
+		const cwd = dirPath ? resolve(rtx.root, dirPath) : rtx.root;
+
+		const computeCtx: ComputeContext = {
+			cwd,
+			env: { ...(process.env as Record<string, string>) },
+			root: rtx.root,
+		};
+
+		// Resolve env: inherited sources first (outermost to innermost),
+		// then own sources. Later sources override earlier ones.
+		const allEnvSources = [...rtx.inheritedEnv, ...this.state.envSources];
+
+		for (const source of allEnvSources) {
+			await mergeEnvSource(computeCtx.env, source, computeCtx);
+		}
+
+		const built = await this.build(computeCtx);
+
+		if (rtx.dryRun) {
+			const fullCmd = [built.command, ...built.args].join(" ");
+			rtx.logger.system(`  ${name}`);
+			rtx.logger.system(`    cmd: ${fullCmd}`);
+			rtx.logger.system(`    cwd: ${built.cwd}`);
+			const envKeys = Object.keys(built.env);
+			if (envKeys.length > 0) {
+				rtx.logger.system(`    env: ${JSON.stringify(built.env)}`);
+			}
+			if (this.state.healthChecks.length > 0) {
+				const types = this.state.healthChecks
+					.map((hc) => hc.type)
+					.join(", ");
+				rtx.logger.system(`    waitFor: ${types}`);
+			}
+			if (this.state.dependencies.length > 0) {
+				const depNames = this.state.dependencies.flatMap((d) =>
+					d.collectNames(),
+				);
+				rtx.logger.system(`    dependsOn: ${depNames.join(", ")}`);
+			}
+			rtx.logger.system("");
+			deferred.resolve();
+			return;
+		}
+
+		rtx.logger.starting(name, name);
+
+		const proc = spawnProcess(name, name, built);
+		rtx.processes.set(name, proc);
+
+		rtx.eventBus.emit({
+			data: {
+				command: [built.command, ...built.args].join(" "),
+				cwd: built.cwd,
+				id: name,
+				serviceName: name,
+			},
+			type: "process:registered",
+		});
+
+		proc.onOutput((line, stream) => {
+			rtx.logger.output(name, line, stream);
+			rtx.eventBus.emit({
+				data: {
+					id: name,
+					line,
+					serviceName: name,
+					stream,
+					timestamp: Date.now(),
+				},
+				type: "log",
+			});
+		});
+
+		if (this.state.healthChecks.length > 0) {
+			for (const check of this.state.healthChecks) {
+				try {
+					await waitForHealthy(check, computeCtx, proc);
+				} catch (err) {
+					rtx.logger.output(
+						name,
+						err instanceof Error ? err.message : String(err),
+						"stderr",
+					);
+					throw err;
+				}
+			}
+			proc.setStatus("healthy");
+			rtx.logger.healthy(name);
+		} else {
+			await proc.waitFor("started");
+			rtx.logger.ready(name);
+		}
+
+		// Signal that this command is ready — dependents can proceed
+		deferred.resolve();
+
+		rtx.eventBus.emit({
+			data: { id: name, status: proc.status },
+			type: "process:status",
+		});
+	}
+
+	private async waitForDependencies(): Promise<void> {
+		if (this.state.dependencies.length === 0) return;
+
+		const rtx = getRuntimeContext();
+
+		for (const dep of this.state.dependencies) {
+			for (const depName of dep.collectNames()) {
+				// Poll until the dependency registers its ready promise
+				let ready = rtx.readyPromises.get(depName);
+				while (!ready) {
+					await sleep(50);
+					ready = rtx.readyPromises.get(depName);
+				}
+				await ready.promise;
+			}
+		}
+	}
+
+	private deriveName(): string {
+		if (this.state.displayName) return this.state.displayName;
+		if (this.state.dirPath) return basename(this.state.dirPath);
+		return this.state.base.split(" ")[0];
+	}
+}
+
+async function mergeEnvSource(
+	target: Record<string, string>,
+	source: EnvSource,
+	ctx: ComputeContext,
+): Promise<void> {
+	if (isEnvCallback(source)) {
+		// Should not happen — callbacks are resolved eagerly in Command.env()
+		// Defensive: skip
+		return;
+	}
+	if (isLazyEnvSource(source)) {
+		const resolved = await source.resolve(ctx);
+		Object.assign(target, resolved);
+	} else {
+		for (const [key, token] of Object.entries(
+			source as Record<string, Token>,
+		)) {
+			target[key] = await resolveToken(token, ctx);
+		}
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function cmd(base: string): ICommand {
+	return new Command({
+		args: [],
+		base,
+		dependencies: [],
+		dirPath: null,
+		displayName: null,
+		envSources: [],
+		flags: [],
+		healthChecks: [],
+		identitySuffix: null,
+	});
+}

package/src/orchestrator/core/compound.ts

@@ -0,0 +1,84 @@
+import { getRuntimeContext } from "../runner/runtime-context.js";
+import type { EnvSource, ICompound, Runnable } from "./types.js";
+
+interface CompoundState {
+	readonly dirPath: string | null;
+	readonly entries: readonly Runnable[];
+	readonly envSources: readonly EnvSource[];
+	readonly mode: "par" | "seq";
+}
+
+class Compound implements ICompound {
+	readonly __type = "compound" as const;
+	readonly mode: "par" | "seq";
+	private readonly state: CompoundState;
+
+	constructor(state: CompoundState) {
+		this.state = state;
+		this.mode = state.mode;
+	}
+
+	env(source: EnvSource): ICompound {
+		return new Compound({
+			...this.state,
+			envSources: [...this.state.envSources, source],
+		});
+	}
+
+	dir(path: string): ICompound {
+		return new Compound({
+			...this.state,
+			dirPath: path,
+		});
+	}
+
+	collectNames(): string[] {
+		return this.state.entries.flatMap((entry) => entry.collectNames());
+	}
+
+	async run(): Promise<void> {
+		const rtx = getRuntimeContext();
+
+		// Save parent inheritance state
+		const prevEnv = rtx.inheritedEnv;
+		const prevDir = rtx.inheritedDir;
+
+		// Push our env/dir onto the inheritance stack
+		rtx.inheritedEnv = [...prevEnv, ...this.state.envSources];
+		if (this.state.dirPath !== null) {
+			rtx.inheritedDir = this.state.dirPath;
+		}
+
+		try {
+			if (this.state.mode === "par") {
+				await Promise.all(this.state.entries.map((entry) => entry.run()));
+			} else {
+				for (const entry of this.state.entries) {
+					await entry.run();
+				}
+			}
+		} finally {
+			// Restore parent inheritance state
+			rtx.inheritedEnv = prevEnv;
+			rtx.inheritedDir = prevDir;
+		}
+	}
+}
+
+export function par(...entries: Runnable[]): ICompound {
+	return new Compound({
+		dirPath: null,
+		entries,
+		envSources: [],
+		mode: "par",
+	});
+}
+
+export function seq(...entries: Runnable[]): ICompound {
+	return new Compound({
+		dirPath: null,
+		entries,
+		envSources: [],
+		mode: "seq",
+	});
+}

package/src/orchestrator/core/health-check.ts

@@ -0,0 +1,38 @@
+import type { HealthCheck, ICommand, Token } from "./types.js";
+
+export function tcpHealthCheck(host: Token, port: Token): HealthCheck {
+	return { host, port, type: "tcp" };
+}
+
+export function httpHealthCheck(url: Token, status?: number): HealthCheck {
+	return { status, type: "http", url };
+}
+
+export function stdoutHealthCheck(pattern: RegExp): HealthCheck {
+	return { pattern, type: "stdout" };
+}
+
+export function execHealthCheck(command: ICommand): HealthCheck {
+	return { command, type: "exec" };
+}
+
+export function customHealthCheck(check: () => Promise<boolean>): HealthCheck {
+	return { check, type: "custom" };
+}
+
+export function postgresHealthCheck(port: Token): HealthCheck {
+	return { host: "localhost", port, type: "tcp" };
+}
+
+/**
+ * Namespace for health check factories.
+ * Usage: health.http(url), health.tcp(host, port), health.postgres(port)
+ */
+export const health = {
+	custom: customHealthCheck,
+	exec: execHealthCheck,
+	http: httpHealthCheck,
+	postgres: postgresHealthCheck,
+	stdout: stdoutHealthCheck,
+	tcp: tcpHealthCheck,
+};

package/src/orchestrator/core/index.ts

@@ -0,0 +1,39 @@
+// Command builder
+export { cmd } from "./command.js";
+// Compound commands
+export { par, seq } from "./compound.js";
+// Health checks
+export {
+	customHealthCheck,
+	execHealthCheck,
+	health,
+	httpHealthCheck,
+	postgresHealthCheck,
+	stdoutHealthCheck,
+	tcpHealthCheck,
+} from "./health-check.js";
+// Tokens
+export {
+	compute,
+	fromEnv,
+	fromFile,
+	fromPackageJson,
+	resolveToken,
+} from "./token.js";
+export type {
+	BuiltCommand,
+	ComputeContext,
+	EnvCallback,
+	EnvSource,
+	HealthCheck,
+	HealthCheckCallback,
+	ICommand,
+	ICompound,
+	IdentityAccessor,
+	LazyEnvSource,
+	ProcessStatus,
+	Runnable,
+	Token,
+} from "./types.js";
+// Types
+export { isEnvCallback, isLazyEnvSource } from "./types.js";