@buildepicshit/cli 0.0.10 → 0.0.12

package/README.md

@@ -0,0 +1,68 @@
+# @buildepicshit/cli
+
+The core orchestrator library and CLI binary for [Build Epic Shit](../../README.md).
+
+## Install
+
+```bash
+npm install @buildepicshit/cli
+```
+
+See the [root README](../../README.md) for full API documentation, examples, and usage guide.
+
+## What's in this package
+
+- **Orchestrator API** — `cmd()`, `par()`, `seq()`, health checks, tokens, identity system
+- **Framework presets** — `nextjs()`, `docker()`, `esbuild()`, `hono()`, `tsx()`, etc.
+- **`bes` CLI binary** — reads `bes.config.ts` and turns exported functions into CLI commands
+
+## Exports
+
+```typescript
+// Main entry point
+import { cmd, par, seq, health, fromEnv, fromFile, compute } from "@buildepicshit/cli"
+
+// Presets
+import { nextjs, dockerCompose, esbuild, tsx, hono, drizzle } from "@buildepicshit/cli/presets"
+```
+
+## Development
+
+```bash
+pnpm dev          # Watch mode (esbuild)
+pnpm build        # Production build
+pnpm test         # Run tests
+pnpm typecheck    # Type checking
+```
+
+## Architecture
+
+```
+src/
+├── bes.ts                    # CLI entry point (commander)
+├── config-loader.ts          # bes.config.ts discovery and loading (jiti)
+├── completion.ts             # Shell tab-completion (omelette)
+├── orchestrator/
+│   ├── index.ts              # Public API surface
+│   ├── core/
+│   │   ├── command.ts        # ICommand implementation (immutable builder)
+│   │   ├── compound.ts       # par/seq implementation
+│   │   ├── health-check.ts   # Health check factories
+│   │   ├── token.ts          # Token resolution (compute, fromEnv, fromFile)
+│   │   └── types.ts          # All TypeScript interfaces
+│   ├── presets/
+│   │   ├── nextjs.ts         # Next.js preset
+│   │   ├── docker.ts         # Docker/docker-compose preset
+│   │   ├── drizzle.ts        # Drizzle ORM preset
+│   │   ├── esbuild.ts        # esbuild preset
+│   │   ├── hono.ts           # Hono preset
+│   │   └── node.ts           # tsx/nodemon presets
+│   ├── runner/
+│   │   ├── event-bus.ts      # Event emission for process lifecycle
+│   │   ├── process.ts        # Child process spawning
+│   │   └── runtime-context.ts
+│   ├── logger/
+│   │   └── logger.ts         # Structured logging
+│   └── utils/
+│       └── dna.ts            # Identity/port allocation (deterministic hashing)
+```

package/package.json

@@ -37,5 +37,5 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"type": "module",
-	"version": "0.0.10"
+	"version": "0.0.12"
 }

package/src/bes.typetest.ts

@@ -0,0 +1,87 @@
+/**
+ * This file is a typescript type test for the bes.config.ts file.
+ * It is used to test the types of the bes.config.ts file.
+ * It is not used in the production code.
+ * It is used to test the types of the bes.config.ts file.
+ * It is used to test the types of the bes.config.ts file.
+ * AI can't make changes to this file.
+ */
+
+import {
+	cmd,
+	dockerCompose,
+	fromFile,
+	health,
+	nextjs,
+	par,
+} from "@buildepicshit/cli";
+
+const identities = {
+	database: "database",
+};
+
+const infra = dockerCompose()
+	.file("docker-compose.yml")
+	.up({ detach: true })
+	.withIdentity("database")
+	.env((self) => ({
+		DB_PORT: self.identity.port(identities.database),
+	}))
+	.logs({ silent: true })
+	.flag("docker-compose.yml")
+	.waitFor((self) => health.postgres(self.identity.port(identities.database)));
+
+const api = cmd("tsx watch src/index.ts")
+	.withIdentity("api")
+	.env((self) => ({ PORT: self.identity.port(identities.database) }))
+	.dir("apps/api")
+	.waitFor((self) => health.http(self.identity.url("/livez")));
+
+const envFile = fromFile(".env");
+const dynamicApiEnv = {
+	DATABASE_URL: `postgresql://simly:simly@localhost:${infra.identity.port(identities.database)}/simly`,
+};
+
+const dynamicAppsEnv = {
+	API_URL: api.identity.localhostUrl(),
+};
+
+const dbPush = cmd("drizzle-kit push")
+	.withIdentity("db-push")
+	.dir("apps/api")
+	.env(dynamicApiEnv)
+	.dependsOn(infra);
+
+const dbStudio = cmd("drizzle-kit studio")
+	.withIdentity("db-studio")
+	.dir("apps/api")
+	.env(dynamicApiEnv)
+	.dependsOn(infra);
+
+const playground = cmd("vite")
+	.withIdentity("playground")
+	.flag("port", (self) => self.identity.port())
+	.dependsOn(api)
+	.dir("apps/playground")
+	.env(envFile)
+	.env(dynamicAppsEnv);
+
+const web = nextjs()
+	.withIdentity("web")
+	.env(envFile)
+	.flag("port", (self) => self.identity.port())
+	.env(dynamicAppsEnv)
+	.dependsOn(api)
+	.dir("apps/web")
+	.env(envFile);
+
+export async function dev() {
+	await par(
+		infra,
+		dbPush,
+		dbStudio,
+		api.flag("watch"),
+		playground,
+		web.arg("dev"),
+	).run();
+}

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

@@ -1,9 +1,9 @@
 import { beforeEach, describe, expect, it } from "vitest";
+import { setConfigRoot } from "../../utils/config-context.js";
 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",
@@ -42,12 +42,13 @@ describe("cmd", () => {
 		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("resolves flag callback with self", async () => {
+		const c = cmd("next dev")
+			.withIdentity("web")
+			.flag("port", (self) => self.identity.port());
+		const built = await c.build(ctx);
+		const port = c.identity.port();
+		expect(built.args).toEqual(["--port", port]);
 	});
 
 	it("adds env vars via record", async () => {

package/src/orchestrator/core/command.ts

@@ -12,6 +12,7 @@ import {
 	type BuiltCommand,
 	type ComputeContext,
 	type EnvSource,
+	type FlagCallback,
 	type HealthCheck,
 	type HealthCheckCallback,
 	type ICommand,
@@ -29,7 +30,7 @@ interface CommandState {
 	readonly displayName: string | null;
 	readonly ensurePort: boolean;
 	readonly envSources: readonly EnvSource[];
-	readonly flags: readonly { name: string; value?: Token }[];
+	readonly flags: readonly { name: string; value?: string }[];
 	readonly healthChecks: readonly HealthCheck[];
 	readonly identitySuffix: string | null;
 	readonly logsSilent: boolean;
@@ -82,10 +83,11 @@ class Command implements ICommand {
 		});
 	}
 
-	flag(name: string, value?: Token): ICommand {
+	flag(name: string, value?: string | FlagCallback): ICommand {
+		const resolved = typeof value === "function" ? value(this) : value;
 		return new Command({
 			...this.state,
-			flags: [...this.state.flags, { name, value }],
+			flags: [...this.state.flags, { name, value: resolved }],
 		});
 	}
 
@@ -141,8 +143,7 @@ class Command implements ICommand {
 
 		for (const flag of this.state.flags) {
 			if (flag.value !== undefined) {
-				const resolved = await resolveToken(flag.value, ctx);
-				args.push(`--${flag.name}`, resolved);
+				args.push(`--${flag.name}`, flag.value);
 			} else {
 				args.push(`--${flag.name}`);
 			}
@@ -199,28 +200,7 @@ class Command implements ICommand {
 		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(", ")}`);
-			}
-			if (this.state.ensurePort) {
-				rtx.logger.system(`    ensurePort: ${this.identity.port()}`);
-			}
-			rtx.logger.system("");
+			this.logDryRun(name, built, rtx);
 			deferred.resolve();
 			return;
 		}
@@ -271,18 +251,7 @@ class Command implements ICommand {
 		});
 
 		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;
-				}
-			}
+			await this.awaitHealthChecks(name, computeCtx, proc, rtx);
 			proc.setStatus("healthy");
 			rtx.logger.healthy(name);
 		} else {
@@ -299,6 +268,53 @@ class Command implements ICommand {
 		});
 	}
 
+	private logDryRun(
+		name: string,
+		built: BuiltCommand,
+		rtx: ReturnType<typeof getRuntimeContext>,
+	): void {
+		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(", ")}`);
+		}
+		if (this.state.ensurePort) {
+			rtx.logger.system(`    ensurePort: ${this.identity.port()}`);
+		}
+		rtx.logger.system("");
+	}
+
+	private async awaitHealthChecks(
+		name: string,
+		ctx: ComputeContext,
+		proc: ReturnType<typeof spawnProcess>,
+		rtx: ReturnType<typeof getRuntimeContext>,
+	): Promise<void> {
+		for (const check of this.state.healthChecks) {
+			try {
+				await waitForHealthy(check, ctx, proc);
+			} catch (err) {
+				rtx.logger.output(
+					name,
+					err instanceof Error ? err.message : String(err),
+					"stderr",
+				);
+				throw err;
+			}
+		}
+	}
+
 	private async waitForDependencies(): Promise<void> {
 		if (this.state.dependencies.length === 0) return;
 

package/src/orchestrator/core/index.ts

@@ -25,6 +25,7 @@ export type {
 	ComputeContext,
 	EnvCallback,
 	EnvSource,
+	FlagCallback,
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,

package/src/orchestrator/core/types.ts

@@ -10,6 +10,10 @@ export type ComputeContext = {
 
 export type Token = string | ((ctx: ComputeContext) => Promise<string>);
 
+// ─── Flag ────────────────────────────────────────────────────────────────────
+
+export type FlagCallback = (self: ICommand) => string;
+
 // ─── Env Source ──────────────────────────────────────────────────────────────
 
 export interface LazyEnvSource {
@@ -56,7 +60,7 @@ export interface ICommand {
 	dir(path: string): ICommand;
 	ensurePort(): ICommand;
 	env(source: EnvSource): ICommand;
-	flag(name: string, value?: Token): ICommand;
+	flag(name: string, value?: string | FlagCallback): ICommand;
 	readonly identity: Identity;
 	logs(options: { silent?: boolean }): ICommand;
 	run(): Promise<void>;

package/src/orchestrator/index.ts

@@ -21,6 +21,7 @@ export type {
 	ComputeContext,
 	EnvCallback,
 	EnvSource,
+	FlagCallback,
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,

package/src/orchestrator/presets/docker.ts

@@ -3,6 +3,7 @@ import type {
 	BuiltCommand,
 	ComputeContext,
 	EnvSource,
+	FlagCallback,
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,
@@ -67,7 +68,7 @@ class DockerCompose implements IDockerCompose {
 		return new DockerCompose(this.inner.logs(options), this.dcState);
 	}
 
-	flag(name: string, value?: Token): IDockerCompose {
+	flag(name: string, value?: string | FlagCallback): IDockerCompose {
 		return new DockerCompose(this.inner.flag(name, value), this.dcState);
 	}
 
@@ -136,7 +137,7 @@ export function dockerCompose(): IDockerCompose {
 /** @deprecated Use `dockerCompose()` instead */
 export function docker(options?: {
 	detach?: boolean;
-	file?: Token;
+	file?: string;
 	service?: string;
 }): ICommand {
 	let command = cmd("docker compose");

package/src/orchestrator/presets/nextjs.ts

@@ -3,6 +3,7 @@ import type {
 	BuiltCommand,
 	ComputeContext,
 	EnvSource,
+	FlagCallback,
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,
@@ -45,7 +46,7 @@ class Nextjs implements INextjs {
 		return new Nextjs(this.inner.logs(options));
 	}
 
-	flag(name: string, value?: Token): INextjs {
+	flag(name: string, value?: string | FlagCallback): INextjs {
 		return new Nextjs(this.inner.flag(name, value));
 	}
 

package/src/orchestrator/utils/port.ts

@@ -4,9 +4,7 @@ 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> {
+export async function killProcessOnPort(port: number): Promise<number | null> {
 	let pids: number[];
 	try {
 		const output = execSync(`lsof -ti :${port}`, {