@buildepicshit/cli 0.0.8 → 0.0.9

package/package.json

@@ -37,5 +37,5 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"type": "module",
-	"version": "0.0.8"
+	"version": "0.0.9"
 }

package/src/config-loader.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { createJiti } from "jiti";
+import { setConfigRoot } from "./orchestrator/utils/config-context.js";
 
 const CONFIG_FILENAME = "bes.config.ts";
 
@@ -40,6 +41,11 @@ export async function loadConfig(
 		);
 	}
 
+	const root = dirname(configPath);
+
+	// Set root BEFORE evaluating config so identity() can compute ports eagerly
+	setConfigRoot(root);
+
 	const jiti = createJiti(configPath, {
 		fsCache: false,
 		interopDefault: true,
@@ -63,6 +69,6 @@ export async function loadConfig(
 
 	return {
 		commands,
-		root: dirname(configPath),
+		root,
 	};
 }

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

@@ -1,8 +1,9 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, 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";
+import { setConfigRoot } from "../../utils/config-context.js";
 
 const ctx: ComputeContext = {
 	cwd: "/app",
@@ -10,6 +11,10 @@ const ctx: ComputeContext = {
 	root: "/",
 };
 
+beforeEach(() => {
+	setConfigRoot("/app");
+});
+
 describe("cmd", () => {
 	it("builds a simple command", async () => {
 		const built = await cmd("next dev").build(ctx);
@@ -172,30 +177,24 @@ describe("command identity", () => {
 		);
 	});
 
-	it("identity proxy still exposes .port() and .url()", async () => {
+	it("identity proxy still exposes .port() and .url()", () => {
 		const c = cmd("node server.js").withIdentity("api");
 		expect(c.identity.name).toBe("api");
-		expect(typeof c.identity.port()).toBe("function");
-		expect(typeof c.identity.url("/health")).toBe("function");
-		expect(typeof c.identity.localhostUrl()).toBe("function");
+		expect(typeof c.identity.port()).toBe("string");
+		expect(typeof c.identity.url("/health")).toBe("string");
+		expect(typeof c.identity.localhostUrl()).toBe("string");
 	});
 
-	it("identity.port() returns a token", async () => {
+	it("identity.port() returns a string port number", () => {
 		const c = cmd("node server.js").withIdentity("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,
-		);
+		const port = Number.parseInt(c.identity.port(), 10);
 		expect(port).toBeGreaterThanOrEqual(3000);
 		expect(port).toBeLessThanOrEqual(9999);
 	});
 
-	it("identity.localhostUrl() returns a token", async () => {
+	it("identity.localhostUrl() returns a URL string", () => {
 		const c = cmd("node server.js").withIdentity("api");
-		const token = c.identity.localhostUrl("/health");
-		const url = await (token as (ctx: ComputeContext) => Promise<string>)(ctx);
+		const url = c.identity.localhostUrl("/health");
 		expect(url).toMatch(/^http:\/\/localhost:\d+\/health$/);
 	});
 
@@ -207,36 +206,22 @@ describe("command identity", () => {
 		expect(built.env.API_URL).toMatch(/^http:\/\/localhost:\d+$/);
 	});
 
-	it("identity.port(name) resolves a named sub-identity", async () => {
+	it("identity.port(name) resolves a named sub-identity", () => {
 		const c = cmd("docker compose").withIdentity("infra");
-		const dbPortToken = c.identity.port("database");
-		const infraPortToken = c.identity.port();
-		const dbPort = await (
-			dbPortToken as (ctx: ComputeContext) => Promise<string>
-		)(ctx);
-		const infraPort = await (
-			infraPortToken as (ctx: ComputeContext) => Promise<string>
-		)(ctx);
+		const dbPort = c.identity.port("database");
+		const infraPort = c.identity.port();
 		// Named sub-identity should produce a different port
 		expect(dbPort).not.toBe(infraPort);
 		expect(Number.parseInt(dbPort, 10)).toBeGreaterThanOrEqual(3000);
 	});
 
-	it("identity.localhostUrl with portIdentity option", async () => {
+	it("identity.localhostUrl with portIdentity option", () => {
 		const c = cmd("docker compose").withIdentity("infra");
-		const urlToken = c.identity.localhostUrl("/health", {
-			portIdentity: "minio",
-		});
-		const url = await (urlToken as (ctx: ComputeContext) => Promise<string>)(
-			ctx,
-		);
+		const url = c.identity.localhostUrl("/health", { portIdentity: "minio" });
 		expect(url).toMatch(/^http:\/\/localhost:\d+\/health$/);
 
 		// Port in the URL should match minio identity, not infra
-		const minioPortToken = c.identity.port("minio");
-		const minioPort = await (
-			minioPortToken as (ctx: ComputeContext) => Promise<string>
-		)(ctx);
+		const minioPort = c.identity.port("minio");
 		expect(url).toBe(`http://localhost:${minioPort}/health`);
 	});
 });
@@ -326,3 +311,28 @@ describe("logs", () => {
 		expect(built2).toBeDefined();
 	});
 });
+
+describe("ensurePort", () => {
+	it("returns a new command instance (immutability)", () => {
+		const base = cmd("node server.js").withIdentity("api");
+		const withEnsure = base.ensurePort();
+		expect(withEnsure).not.toBe(base);
+	});
+
+	it("propagates through builder chain", async () => {
+		const c = cmd("node server.js")
+			.withIdentity("api")
+			.ensurePort()
+			.dir("apps/api")
+			.env({ KEY: "value" })
+			.flag("verbose");
+		const built = await c.build(ctx);
+		expect(built).toBeDefined();
+	});
+
+	it("builds without error when ensurePort is set", async () => {
+		const c = cmd("node server.js").withIdentity("api").ensurePort();
+		const built = await c.build(ctx);
+		expect(built.command).toBe("node server.js");
+	});
+});

package/src/orchestrator/core/command.ts

@@ -6,6 +6,7 @@ import {
 	getRuntimeContext,
 } from "../runner/runtime-context.js";
 import { createIdentity, type Identity } from "../utils/dna.js";
+import { killProcessOnPort } from "../utils/port.js";
 import { resolveToken } from "./token.js";
 import {
 	type BuiltCommand,
@@ -26,6 +27,7 @@ interface CommandState {
 	readonly dependencies: readonly Runnable[];
 	readonly dirPath: string | null;
 	readonly displayName: string | null;
+	readonly ensurePort: boolean;
 	readonly envSources: readonly EnvSource[];
 	readonly flags: readonly { name: string; value?: Token }[];
 	readonly healthChecks: readonly HealthCheck[];
@@ -69,6 +71,10 @@ class Command implements ICommand {
 		return new Command({ ...this.state, identitySuffix: suffix });
 	}
 
+	ensurePort(): ICommand {
+		return new Command({ ...this.state, ensurePort: true });
+	}
+
 	logs(options: { silent?: boolean }): ICommand {
 		return new Command({
 			...this.state,
@@ -91,13 +97,6 @@ class Command implements ICommand {
 	}
 
 	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],
@@ -157,7 +156,7 @@ class Command implements ICommand {
 		// 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);
+			await mergeEnvSource(env, source, ctx, this);
 		}
 
 		return {
@@ -194,7 +193,7 @@ class Command implements ICommand {
 		const allEnvSources = [...rtx.inheritedEnv, ...this.state.envSources];
 
 		for (const source of allEnvSources) {
-			await mergeEnvSource(computeCtx.env, source, computeCtx);
+			await mergeEnvSource(computeCtx.env, source, computeCtx, this);
 		}
 
 		const built = await this.build(computeCtx);
@@ -218,11 +217,26 @@ class Command implements ICommand {
 				);
 				rtx.logger.system(`    dependsOn: ${depNames.join(", ")}`);
 			}
+			if (this.state.ensurePort) {
+				rtx.logger.system(`    ensurePort: ${this.identity.port()}`);
+			}
 			rtx.logger.system("");
 			deferred.resolve();
 			return;
 		}
 
+		if (this.state.ensurePort) {
+			const port = Number.parseInt(this.identity.port(), 10);
+			const killed = await killProcessOnPort(port);
+			if (killed) {
+				rtx.logger.output(
+					name,
+					`Killed process ${killed} on port ${port}`,
+					"stderr",
+				);
+			}
+		}
+
 		const fullCmd = [built.command, ...built.args].join(" ");
 		rtx.logger.starting(name, name);
 		rtx.logger.system(`  ${fullCmd}`);
@@ -314,10 +328,12 @@ async function mergeEnvSource(
 	target: Record<string, string>,
 	source: EnvSource,
 	ctx: ComputeContext,
+	command?: ICommand,
 ): Promise<void> {
 	if (isEnvCallback(source)) {
-		// Should not happen — callbacks are resolved eagerly in Command.env()
-		// Defensive: skip
+		if (!command) return;
+		const resolved = source(command);
+		await mergeEnvSource(target, resolved, ctx);
 		return;
 	}
 	if (isLazyEnvSource(source)) {
@@ -343,6 +359,7 @@ export function cmd(base: string): ICommand {
 		dependencies: [],
 		dirPath: null,
 		displayName: null,
+		ensurePort: false,
 		envSources: [],
 		flags: [],
 		healthChecks: [],

package/src/orchestrator/core/types.ts

@@ -54,6 +54,7 @@ export interface ICommand {
 	collectNames(): string[];
 	dependsOn(...deps: Runnable[]): ICommand;
 	dir(path: string): ICommand;
+	ensurePort(): ICommand;
 	env(source: EnvSource): ICommand;
 	flag(name: string, value?: Token): ICommand;
 	readonly identity: Identity;

package/src/orchestrator/presets/docker.ts

@@ -59,6 +59,10 @@ class DockerCompose implements IDockerCompose {
 		return new DockerCompose(this.inner.withIdentity(suffix), this.dcState);
 	}
 
+	ensurePort(): IDockerCompose {
+		return new DockerCompose(this.inner.ensurePort(), this.dcState);
+	}
+
 	logs(options: { silent?: boolean }): IDockerCompose {
 		return new DockerCompose(this.inner.logs(options), this.dcState);
 	}

package/src/orchestrator/presets/nextjs.ts

@@ -37,6 +37,10 @@ class Nextjs implements INextjs {
 		return new Nextjs(this.inner.withIdentity(suffix));
 	}
 
+	ensurePort(): INextjs {
+		return new Nextjs(this.inner.ensurePort());
+	}
+
 	logs(options: { silent?: boolean }): INextjs {
 		return new Nextjs(this.inner.logs(options));
 	}
@@ -85,9 +89,11 @@ class Nextjs implements INextjs {
 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(),
-	}));
+	const inner = cmd("next")
+		.ensurePort()
+		.env((self) => ({
+			PORT: self.identity.port(),
+		}));
 	return new Nextjs(inner);
 }
 

package/src/orchestrator/utils/__tests__/dna.test.ts

@@ -1,133 +1,129 @@
 import { describe, expect, it } from "vitest";
-import type { ComputeContext } from "../../core/types.js";
 import { identity } from "../dna.js";
 
-const ctx: ComputeContext = {
-	cwd: "/projects/myapp",
-	env: {},
-	root: "/projects/myapp",
-};
-
-async function resolveToken(
-	token: ReturnType<ReturnType<typeof identity>["port"]>,
-	context: ComputeContext,
-): Promise<string> {
-	return typeof token === "function" ? token(context) : token;
-}
+const root = "/projects/myapp";
 
 describe("DNA", () => {
-	it("port() returns a number in range 3000–9999", async () => {
-		const result = await resolveToken(identity("hono").port(), ctx);
+	it("port() returns a number in range 3000–9999", () => {
+		const result = identity("hono", root).port();
 		const port = Number.parseInt(result, 10);
 		expect(port).toBeGreaterThanOrEqual(3000);
 		expect(port).toBeLessThanOrEqual(9999);
 	});
 
-	it("port() is deterministic for same cwd + suffix", async () => {
-		const r1 = await resolveToken(identity("hono").port(), ctx);
-		const r2 = await resolveToken(identity("hono").port(), ctx);
+	it("port() is deterministic for same root + suffix", () => {
+		const r1 = identity("hono", root).port();
+		const r2 = identity("hono", root).port();
 		expect(r1).toBe(r2);
 	});
 
-	it("port() differs for different suffixes", async () => {
-		const r1 = await resolveToken(identity("hono").port(), ctx);
-		const r2 = await resolveToken(identity("next").port(), ctx);
+	it("port() differs for different suffixes", () => {
+		const r1 = identity("hono", root).port();
+		const r2 = identity("next", root).port();
 		expect(r1).not.toBe(r2);
 	});
 
-	it("port() differs for different cwds", async () => {
-		const ctx2: ComputeContext = { cwd: "/other/project", env: {}, root: "/" };
-		const r1 = await resolveToken(identity("hono").port(), ctx);
-		const r2 = await resolveToken(identity("hono").port(), ctx2);
+	it("port() differs for different roots", () => {
+		const r1 = identity("hono", root).port();
+		const r2 = identity("hono", "/other/project").port();
 		expect(r1).not.toBe(r2);
 	});
 
-	it("url() returns http://localhost:{port}", async () => {
-		const result = await resolveToken(identity("hono").url(), ctx);
+	it("url() returns http://localhost:{port}", () => {
+		const result = identity("hono", root).url();
 		expect(result).toMatch(/^http:\/\/localhost:\d+$/);
 	});
 
-	it("url(path) appends the path", async () => {
-		const result = await resolveToken(identity("hono").url("/health"), ctx);
+	it("url(path) appends the path", () => {
+		const result = identity("hono", root).url("/health");
 		expect(result).toMatch(/^http:\/\/localhost:\d+\/health$/);
 	});
 
-	it("url() port matches port()", async () => {
-		const port = await resolveToken(identity("hono").port(), ctx);
-		const url = await resolveToken(identity("hono").url("/api"), ctx);
+	it("url() port matches port()", () => {
+		const id = identity("hono", root);
+		const port = id.port();
+		const url = id.url("/api");
 		expect(url).toBe(`http://localhost:${port}/api`);
 	});
 
 	it("has a name property matching the suffix", () => {
-		expect(identity("server").name).toBe("server");
+		expect(identity("server", root).name).toBe("server");
 	});
 
 	it("has an empty name when no suffix is provided", () => {
-		expect(identity().name).toBe("");
+		expect(identity(undefined, root).name).toBe("");
 	});
 
-	it("localhostUrl() returns http://localhost:{port}", async () => {
-		const result = await resolveToken(identity("hono").localhostUrl(), ctx);
+	it("localhostUrl() returns http://localhost:{port}", () => {
+		const result = identity("hono", root).localhostUrl();
 		expect(result).toMatch(/^http:\/\/localhost:\d+$/);
 	});
 
-	it("localhostUrl(path) appends the path", async () => {
-		const result = await resolveToken(
-			identity("hono").localhostUrl("/health"),
-			ctx,
-		);
+	it("localhostUrl(path) appends the path", () => {
+		const result = identity("hono", root).localhostUrl("/health");
 		expect(result).toMatch(/^http:\/\/localhost:\d+\/health$/);
 	});
 
-	it("localhostUrl() matches url() output", async () => {
-		const id = identity("hono");
-		const fromUrl = await resolveToken(id.url("/api"), ctx);
-		const fromLocalhostUrl = await resolveToken(id.localhostUrl("/api"), ctx);
+	it("localhostUrl() matches url() output", () => {
+		const id = identity("hono", root);
+		const fromUrl = id.url("/api");
+		const fromLocalhostUrl = id.localhostUrl("/api");
 		expect(fromLocalhostUrl).toBe(fromUrl);
 	});
 
-	it("port(identityName) computes port for a different identity", async () => {
-		const id = identity("infra");
-		const ownPort = await resolveToken(id.port(), ctx);
-		const dbPort = await resolveToken(id.port("database"), ctx);
+	it("port(identityName) computes port for a different identity", () => {
+		const id = identity("infra", root);
+		const ownPort = id.port();
+		const dbPort = id.port("database");
 		expect(ownPort).not.toBe(dbPort);
 		const port = Number.parseInt(dbPort, 10);
 		expect(port).toBeGreaterThanOrEqual(3000);
 		expect(port).toBeLessThanOrEqual(9999);
 	});
 
-	it("port(identityName) is deterministic", async () => {
-		const id = identity("infra");
-		const r1 = await resolveToken(id.port("database"), ctx);
-		const r2 = await resolveToken(id.port("database"), ctx);
+	it("port(identityName) is deterministic", () => {
+		const id = identity("infra", root);
+		const r1 = id.port("database");
+		const r2 = id.port("database");
 		expect(r1).toBe(r2);
 	});
 
-	it("port(identityName) matches standalone identity port", async () => {
-		const infra = identity("infra");
-		const db = identity("database");
-		const fromSub = await resolveToken(infra.port("database"), ctx);
-		const fromStandalone = await resolveToken(db.port(), ctx);
+	it("port(identityName) matches standalone identity port", () => {
+		const infra = identity("infra", root);
+		const db = identity("database", root);
+		const fromSub = infra.port("database");
+		const fromStandalone = db.port();
 		expect(fromSub).toBe(fromStandalone);
 	});
 
-	it("url with portIdentity option uses different port", async () => {
-		const id = identity("infra");
-		const minioPort = await resolveToken(id.port("minio"), ctx);
-		const url = await resolveToken(
-			id.url("/health", { portIdentity: "minio" }),
-			ctx,
-		);
+	it("url with portIdentity option uses different port", () => {
+		const id = identity("infra", root);
+		const minioPort = id.port("minio");
+		const url = id.url("/health", { portIdentity: "minio" });
 		expect(url).toBe(`http://localhost:${minioPort}/health`);
 	});
 
-	it("localhostUrl with portIdentity option uses different port", async () => {
-		const id = identity("infra");
-		const minioPort = await resolveToken(id.port("minio"), ctx);
-		const url = await resolveToken(
-			id.localhostUrl("/health", { portIdentity: "minio" }),
-			ctx,
-		);
+	it("localhostUrl with portIdentity option uses different port", () => {
+		const id = identity("infra", root);
+		const minioPort = id.port("minio");
+		const url = id.localhostUrl("/health", { portIdentity: "minio" });
 		expect(url).toBe(`http://localhost:${minioPort}/health`);
 	});
+
+	it("returns plain strings (not functions)", () => {
+		const id = identity("server", root);
+		expect(typeof id.port()).toBe("string");
+		expect(typeof id.url()).toBe("string");
+		expect(typeof id.localhostUrl()).toBe("string");
+	});
+
+	it("works in template literals", () => {
+		const id = identity("database", root);
+		const url = `postgresql://user:pass@localhost:${id.port()}/mydb`;
+		expect(url).toMatch(/^postgresql:\/\/user:pass@localhost:\d+\/mydb$/);
+	});
+
+	it("throws when no root is available", () => {
+		expect(() => identity("test")).toThrow("no root available");
+	});
 });

package/src/orchestrator/utils/config-context.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared config context using globalThis so it survives across module
+ * instances (jiti creates separate module caches from Node's native one).
+ */
+
+const KEY = "__bes_config_root__";
+
+export function setConfigRoot(root: string): void {
+	(globalThis as Record<string, unknown>)[KEY] = root;
+}
+
+export function getConfigRoot(): string | null {
+	return ((globalThis as Record<string, unknown>)[KEY] as string) ?? null;
+}

package/src/orchestrator/utils/dna.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { Token } from "../core/types.js";
+import { getConfigRoot } from "./config-context.js";
 
 // Well-known/reserved ports in the 3000-9999 range to avoid
 const RESERVED_PORTS = new Set([
@@ -57,37 +57,41 @@ function computePort(
 }
 
 export interface Identity {
-	localhostUrl: (path?: string, options?: { portIdentity?: string }) => Token;
+	localhostUrl: (path?: string, options?: { portIdentity?: string }) => string;
 	readonly name: string;
-	port: (identityName?: string) => Token;
-	url: (path?: string, options?: { portIdentity?: string }) => Token;
+	port: (identityName?: string) => string;
+	url: (path?: string, options?: { portIdentity?: string }) => string;
 }
 
-export function createIdentity(suffix?: string): Identity {
+export function createIdentity(suffix?: string, root?: string): Identity {
 	const name = suffix || "";
+	const resolvedRoot = root ?? getConfigRoot();
 
-	const urlToken = (
+	if (!resolvedRoot) {
+		throw new Error(
+			"Cannot create identity: no root available. " +
+				"Ensure identity() is called during config evaluation or pass root explicitly.",
+		);
+	}
+
+	const urlFn = (
 		pathValue?: string,
 		options?: { portIdentity?: string },
-	): Token => {
-		return async ({ cwd }) => {
-			const portName = options?.portIdentity ?? name;
-			const port = computePort(cwd, portName);
-			const base = `http://localhost:${port}`;
-			return pathValue ? `${base}${pathValue}` : base;
-		};
+	): string => {
+		const portName = options?.portIdentity ?? name;
+		const port = computePort(resolvedRoot, portName);
+		const base = `http://localhost:${port}`;
+		return pathValue ? `${base}${pathValue}` : base;
 	};
 
 	return {
-		localhostUrl: urlToken,
+		localhostUrl: urlFn,
 		name,
-		port: (identityName?: string): Token => {
-			return async ({ cwd }) => {
-				const portName = identityName ?? name;
-				return computePort(cwd, portName).toString();
-			};
+		port: (identityName?: string): string => {
+			const portName = identityName ?? name;
+			return computePort(resolvedRoot, portName).toString();
 		},
-		url: urlToken,
+		url: urlFn,
 	};
 }
 

package/src/orchestrator/utils/port.ts

@@ -0,0 +1,51 @@
+import { execSync } from "node:child_process";
+
+/**
+ * Find and kill any process listening on the given port.
+ * Returns the PID of the first process killed, or null if the port was free.
+ */
+export async function killProcessOnPort(
+	port: number,
+): Promise<number | null> {
+	let pids: number[];
+	try {
+		const output = execSync(`lsof -ti :${port}`, {
+			encoding: "utf8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!output) return null;
+		pids = output
+			.split("\n")
+			.map((p) => Number.parseInt(p.trim(), 10))
+			.filter(Boolean);
+	} catch {
+		return null; // No process on that port
+	}
+
+	if (pids.length === 0) return null;
+
+	const first = pids[0];
+
+	// SIGTERM first
+	for (const pid of pids) {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch {
+			// Already exited
+		}
+	}
+
+	// Wait, then SIGKILL survivors
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+
+	for (const pid of pids) {
+		try {
+			process.kill(pid, 0); // Check if still alive
+			process.kill(pid, "SIGKILL");
+		} catch {
+			// Already dead
+		}
+	}
+
+	return first;
+}