@buildepicshit/cli 0.0.1 → 0.0.3

package/src/orchestrator/core/command.ts

@@ -0,0 +1,321 @@
+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 type { Identity } from "../utils/dna.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,
+	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 healthCheck: HealthCheck | null;
+	readonly identitySuffix: string | null;
+}
+
+class Command implements ICommand {
+	readonly __type = "command" as const;
+	private readonly state: CommandState;
+
+	constructor(state: CommandState) {
+		this.state = state;
+	}
+
+	identity(): Identity;
+	identity(suffix: string): ICommand;
+	identity(suffix?: string): Identity | ICommand {
+		if (suffix !== undefined) {
+			return new Command({
+				...this.state,
+				identitySuffix: suffix,
+			});
+		}
+		return createIdentity(this.state.identitySuffix ?? this.deriveName());
+	}
+
+	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,
+			healthCheck: 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.healthCheck) {
+				rtx.logger.system(`    waitFor: ${this.state.healthCheck.type}`);
+			}
+			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.healthCheck) {
+			try {
+				await waitForHealthy(this.state.healthCheck, 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: [],
+		healthCheck: null,
+		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,33 @@
+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" };
+}
+
+/**
+ * Namespace for health check factories.
+ * Usage: health.http(url), health.tcp(host, port), health.stdout(pattern)
+ */
+export const health = {
+	custom: customHealthCheck,
+	exec: execHealthCheck,
+	http: httpHealthCheck,
+	stdout: stdoutHealthCheck,
+	tcp: tcpHealthCheck,
+};

package/src/orchestrator/core/index.ts

@@ -0,0 +1,37 @@
+// Command builder
+export { cmd } from "./command.js";
+// Compound commands
+export { par, seq } from "./compound.js";
+// Health checks
+export {
+	customHealthCheck,
+	execHealthCheck,
+	health,
+	httpHealthCheck,
+	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,
+	LazyEnvSource,
+	ProcessStatus,
+	Runnable,
+	Token,
+} from "./types.js";
+// Types
+export { isEnvCallback, isLazyEnvSource } from "./types.js";

package/src/orchestrator/core/token.ts

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { ComputeContext, LazyEnvSource, Token } from "./types.js";
+
+export function compute(fn: (ctx: ComputeContext) => Promise<string>): Token {
+	return fn;
+}
+
+export function fromEnv(key: string, fallback?: string): Token {
+	return async ({ env }: ComputeContext) => {
+		const value = env[key];
+		if (value !== undefined) return value;
+		if (fallback !== undefined) return fallback;
+		throw new Error(
+			`Environment variable "${key}" is not set and no fallback provided`,
+		);
+	};
+}
+
+export function fromPackageJson(path: string, fallback?: string): Token {
+	return async ({ cwd }: ComputeContext) => {
+		const raw = await readFile(join(cwd, "package.json"), "utf8");
+		const pkg = JSON.parse(raw);
+
+		const value = path.split(".").reduce<unknown>((obj, key) => {
+			if (obj != null && typeof obj === "object") {
+				return (obj as Record<string, unknown>)[key];
+			}
+			return undefined;
+		}, pkg);
+
+		if (value !== undefined) return String(value);
+		if (fallback !== undefined) return fallback;
+		throw new Error(
+			`package.json path "${path}" not found in ${cwd}/package.json and no fallback provided`,
+		);
+	};
+}
+
+/**
+ * Parse .env file(s) relative to the command's cwd.
+ * Multiple files can be passed — later files override earlier ones.
+ */
+export function fromFile(...paths: string[]): LazyEnvSource {
+	return {
+		__type: "env-source",
+		resolve: async (ctx: ComputeContext) => {
+			const env: Record<string, string> = {};
+
+			for (const filePath of paths) {
+				const fullPath = resolve(ctx.cwd, filePath);
+				let content: string;
+				try {
+					content = await readFile(fullPath, "utf8");
+				} catch {
+					continue; // skip missing files silently
+				}
+
+				for (const line of content.split("\n")) {
+					const trimmed = line.trim();
+					if (!trimmed || trimmed.startsWith("#")) continue;
+					const eqIdx = trimmed.indexOf("=");
+					if (eqIdx === -1) continue;
+					const key = trimmed.slice(0, eqIdx).trim();
+					let value = trimmed.slice(eqIdx + 1).trim();
+					// Strip surrounding quotes
+					if (
+						(value.startsWith('"') && value.endsWith('"')) ||
+						(value.startsWith("'") && value.endsWith("'"))
+					) {
+						value = value.slice(1, -1);
+					}
+					env[key] = value;
+				}
+			}
+
+			return env;
+		},
+	};
+}
+
+export async function resolveToken(
+	token: Token,
+	ctx: ComputeContext,
+): Promise<string> {
+	if (typeof token === "string") return token;
+	return token(ctx);
+}

package/src/orchestrator/core/types.ts

@@ -0,0 +1,99 @@
+import type { Identity } from "../utils/dna.js";
+
+// ─── Token ───────────────────────────────────────────────────────────────────
+
+export type ComputeContext = {
+	cwd: string;
+	env: Record<string, string>;
+	root: string;
+};
+
+export type Token = string | ((ctx: ComputeContext) => Promise<string>);
+
+// ─── Env Source ──────────────────────────────────────────────────────────────
+
+export interface LazyEnvSource {
+	__type: "env-source";
+	resolve: (ctx: ComputeContext) => Promise<Record<string, string>>;
+}
+
+export type EnvCallback = (
+	self: ICommand,
+) => Record<string, Token> | LazyEnvSource;
+
+export type EnvSource = Record<string, Token> | LazyEnvSource | EnvCallback;
+
+export function isLazyEnvSource(
+	source: Record<string, Token> | LazyEnvSource,
+): source is LazyEnvSource {
+	return (
+		typeof source === "object" &&
+		"__type" in source &&
+		source.__type === "env-source"
+	);
+}
+
+export function isEnvCallback(source: EnvSource): source is EnvCallback {
+	return typeof source === "function";
+}
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
+export interface BuiltCommand {
+	args: string[];
+	command: string;
+	cwd: string;
+	env: Record<string, string>;
+}
+
+export interface ICommand {
+	readonly __type: "command";
+	arg(value: Token): ICommand;
+	as(name: string): ICommand;
+	build(ctx: ComputeContext): Promise<BuiltCommand>;
+	collectNames(): string[];
+	dependsOn(...deps: Runnable[]): ICommand;
+	dir(path: string): ICommand;
+	env(source: EnvSource): ICommand;
+	flag(name: string, value?: Token): ICommand;
+	identity(): Identity;
+	identity(suffix: string): ICommand;
+	run(): Promise<void>;
+	waitFor(check: HealthCheck | HealthCheckCallback): ICommand;
+}
+
+// ─── Compound ────────────────────────────────────────────────────────────────
+
+export interface ICompound {
+	readonly __type: "compound";
+	collectNames(): string[];
+	dir(path: string): ICompound;
+	env(source: EnvSource): ICompound;
+	readonly mode: "par" | "seq";
+	run(): Promise<void>;
+}
+
+// ─── Runnable ────────────────────────────────────────────────────────────────
+
+export type Runnable = ICommand | ICompound;
+
+// ─── Health Check ────────────────────────────────────────────────────────────
+
+export type HealthCheckCallback = (self: ICommand) => HealthCheck;
+
+export type HealthCheck =
+	| { type: "tcp"; host: Token; port: Token }
+	| { type: "http"; url: Token; status?: number }
+	| { type: "stdout"; pattern: RegExp }
+	| { type: "exec"; command: ICommand }
+	| { type: "custom"; check: () => Promise<boolean> };
+
+// ─── Process ─────────────────────────────────────────────────────────────────
+
+export type ProcessStatus =
+	| "completed"
+	| "failed"
+	| "healthy"
+	| "pending"
+	| "running"
+	| "starting";