@buildepicshit/cli 0.0.4 → 0.0.6

package/package.json

@@ -35,5 +35,5 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"type": "module",
-	"version": "0.0.4"
+	"version": "0.0.6"
 }

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

@@ -133,14 +133,14 @@ describe("command identity", () => {
 		expect(c.identity.name).toBe("tsx");
 	});
 
-	it("overrides identity with .identity(suffix)", () => {
-		const c = cmd("node server.js").identity("custom").dir("apps/api");
+	it("overrides identity with .withIdentity(suffix)", () => {
+		const c = cmd("node server.js").withIdentity("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")
+			.withIdentity("api")
 			.dir("apps/server")
 			.env({ KEY: "value" })
 			.flag("verbose");
@@ -149,13 +149,39 @@ describe("command identity", () => {
 
 	it("identity is immutable across branches", () => {
 		const base = cmd("node server.js");
-		const withId = base.identity("custom");
+		const withId = base.withIdentity("custom");
 		expect(base.identity.name).toBe("node");
 		expect(withId.identity.name).toBe("custom");
 	});
 
+	it("throws a helpful error when .identity is called as a function", () => {
+		const c = cmd("node server.js");
+		expect(() => {
+			(c.identity as unknown as (s: string) => void)("api");
+		}).toThrow(
+			'.identity("api") is not a function. To set identity, use .withIdentity("api") instead.',
+		);
+	});
+
+	it("throws a helpful error when .identity is called without args", () => {
+		const c = cmd("node server.js");
+		expect(() => {
+			(c.identity as unknown as () => void)();
+		}).toThrow(
+			".identity() is not a function. To set identity, use .withIdentity() instead.",
+		);
+	});
+
+	it("identity proxy still exposes .port() and .url()", async () => {
+		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");
+	});
+
 	it("identity.port() returns a token", async () => {
-		const c = cmd("node server.js").identity("api").dir("apps/api");
+		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(
@@ -167,14 +193,14 @@ describe("command identity", () => {
 	});
 
 	it("identity.localhostUrl() returns a token", async () => {
-		const c = cmd("node server.js").identity("api");
+		const c = cmd("node server.js").withIdentity("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 server = cmd("node server.js").withIdentity("api").dir("apps/api");
 		const built = await cmd("next dev")
 			.env({ API_URL: server.identity.localhostUrl() })
 			.build(ctx);
@@ -182,25 +208,35 @@ describe("command identity", () => {
 	});
 
 	it("identity.port(name) resolves a named sub-identity", async () => {
-		const c = cmd("docker compose").identity("infra");
+		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 = await (
+			dbPortToken as (ctx: ComputeContext) => Promise<string>
+		)(ctx);
+		const infraPort = await (
+			infraPortToken as (ctx: ComputeContext) => Promise<string>
+		)(ctx);
 		// 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 () => {
-		const c = cmd("docker compose").identity("infra");
-		const urlToken = c.identity.localhostUrl("/health", { portIdentity: "minio" });
-		const url = await (urlToken as (ctx: ComputeContext) => Promise<string>)(ctx);
+		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,
+		);
 		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 = await (
+			minioPortToken as (ctx: ComputeContext) => Promise<string>
+		)(ctx);
 		expect(url).toBe(`http://localhost:${minioPort}/health`);
 	});
 });
@@ -216,7 +252,7 @@ describe("multiple waitFor", () => {
 
 	it("accepts callback form for multiple waitFor", async () => {
 		const c = cmd("node server.js")
-			.identity("api")
+			.withIdentity("api")
 			.waitFor((self) => health.http(self.identity.url("/livez")))
 			.waitFor((self) => health.tcp("localhost", self.identity.port()));
 		const built = await c.build(ctx);
@@ -227,7 +263,7 @@ describe("multiple waitFor", () => {
 describe("waitFor callback form", () => {
 	it("accepts a callback that receives the command", async () => {
 		const c = cmd("node server.js")
-			.identity("api")
+			.withIdentity("api")
 			.dir("apps/api")
 			.waitFor((self) => health.http(self.identity.url("/livez")));
 
@@ -240,7 +276,7 @@ describe("waitFor callback form", () => {
 describe("env callback form", () => {
 	it("accepts a callback that receives the command", async () => {
 		const c = cmd("node server.js")
-			.identity("api")
+			.withIdentity("api")
 			.env((self) => ({ PORT: self.identity.port() }));
 
 		const built = await c.build(ctx);
@@ -251,7 +287,7 @@ describe("env callback form", () => {
 
 	it("mixes callback env with record env", async () => {
 		const c = cmd("node server.js")
-			.identity("api")
+			.withIdentity("api")
 			.env({ A: "1" })
 			.env((self) => ({ PORT: self.identity.port() }))
 			.env({ B: "2" });
@@ -262,3 +298,31 @@ describe("env callback form", () => {
 		expect(Number.parseInt(built.env.PORT, 10)).toBeGreaterThanOrEqual(3000);
 	});
 });
+
+describe("logs", () => {
+	it("logs({ silent: true }) builds without error", async () => {
+		const c = cmd("node server.js").logs({ silent: true });
+		const built = await c.build(ctx);
+		expect(built).toBeDefined();
+	});
+
+	it("logs state propagates through builder chain", async () => {
+		const c = cmd("node server.js")
+			.logs({ silent: true })
+			.dir("apps/api")
+			.env({ KEY: "value" })
+			.flag("verbose");
+		const built = await c.build(ctx);
+		expect(built).toBeDefined();
+	});
+
+	it("is immutable — logs does not affect original", async () => {
+		const base = cmd("node server.js");
+		const silent = base.logs({ silent: true });
+		// Both should build fine — they are independent instances
+		const built1 = await base.build(ctx);
+		const built2 = await silent.build(ctx);
+		expect(built1).toBeDefined();
+		expect(built2).toBeDefined();
+	});
+});

package/src/orchestrator/core/command.ts

@@ -5,7 +5,7 @@ import {
 	createDeferred,
 	getRuntimeContext,
 } from "../runner/runtime-context.js";
-import { createIdentity } from "../utils/dna.js";
+import { createIdentity, type Identity } from "../utils/dna.js";
 import { resolveToken } from "./token.js";
 import {
 	type BuiltCommand,
@@ -14,7 +14,6 @@ import {
 	type HealthCheck,
 	type HealthCheckCallback,
 	type ICommand,
-	type IdentityAccessor,
 	isEnvCallback,
 	isLazyEnvSource,
 	type Runnable,
@@ -31,6 +30,7 @@ interface CommandState {
 	readonly flags: readonly { name: string; value?: Token }[];
 	readonly healthChecks: readonly HealthCheck[];
 	readonly identitySuffix: string | null;
+	readonly logsSilent: boolean;
 }
 
 class Command implements ICommand {
@@ -41,24 +41,39 @@ class Command implements ICommand {
 		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,
+	get identity(): Identity {
+		const id = createIdentity(this.state.identitySuffix ?? this.deriveName());
+
+		function throwOnCall(...args: unknown[]): never {
+			const hint = typeof args[0] === "string" ? `("${args[0]}")` : "()";
+			throw new TypeError(
+				`.identity${hint} is not a function. To set identity, use .withIdentity${hint} instead. ` +
+					`.identity is a read-only property that provides access to .port() and .url().`,
+			);
+		}
+
+		return new Proxy(throwOnCall, {
+			apply(_target, _thisArg, args) {
+				throwOnCall(...(args as unknown[]));
+			},
+			get(_target, prop, receiver) {
+				return Reflect.get(id, prop, receiver);
+			},
+			has(_target, prop) {
+				return prop in id;
+			},
+		}) as unknown as Identity;
+	}
+
+	withIdentity(suffix: string): ICommand {
+		return new Command({ ...this.state, identitySuffix: suffix });
+	}
+
+	logs(options: { silent?: boolean }): ICommand {
+		return new Command({
+			...this.state,
+			logsSilent: options.silent ?? false,
 		});
-		return Object.assign(setter, {
-			localhostUrl: id.localhostUrl,
-			port: id.port,
-			url: id.url,
-		}) as IdentityAccessor;
 	}
 
 	flag(name: string, value?: Token): ICommand {
@@ -194,9 +209,7 @@ class Command implements ICommand {
 				rtx.logger.system(`    env: ${JSON.stringify(built.env)}`);
 			}
 			if (this.state.healthChecks.length > 0) {
-				const types = this.state.healthChecks
-					.map((hc) => hc.type)
-					.join(", ");
+				const types = this.state.healthChecks.map((hc) => hc.type).join(", ");
 				rtx.logger.system(`    waitFor: ${types}`);
 			}
 			if (this.state.dependencies.length > 0) {
@@ -226,17 +239,19 @@ class Command implements ICommand {
 		});
 
 		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.logsSilent) {
+				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) {
@@ -330,5 +345,6 @@ export function cmd(base: string): ICommand {
 		flags: [],
 		healthChecks: [],
 		identitySuffix: null,
+		logsSilent: false,
 	});
 }

package/src/orchestrator/core/index.ts

@@ -29,7 +29,6 @@ export type {
 	HealthCheckCallback,
 	ICommand,
 	ICompound,
-	IdentityAccessor,
 	LazyEnvSource,
 	ProcessStatus,
 	Runnable,

package/src/orchestrator/core/types.ts

@@ -46,10 +46,6 @@ export interface BuiltCommand {
 	env: Record<string, string>;
 }
 
-export interface IdentityAccessor extends Identity {
-	(suffix: string): ICommand;
-}
-
 export interface ICommand {
 	readonly __type: "command";
 	arg(value: Token): ICommand;
@@ -60,9 +56,11 @@ export interface ICommand {
 	dir(path: string): ICommand;
 	env(source: EnvSource): ICommand;
 	flag(name: string, value?: Token): ICommand;
-	readonly identity: IdentityAccessor;
+	readonly identity: Identity;
+	logs(options: { silent?: boolean }): ICommand;
 	run(): Promise<void>;
 	waitFor(check: HealthCheck | HealthCheckCallback): ICommand;
+	withIdentity(suffix: string): ICommand;
 }
 
 // ─── Compound ────────────────────────────────────────────────────────────────

package/src/orchestrator/index.ts

@@ -25,7 +25,6 @@ export type {
 	HealthCheckCallback,
 	ICommand,
 	ICompound,
-	IdentityAccessor,
 	ProcessStatus,
 	Runnable,
 	Token,
@@ -34,7 +33,12 @@ export type {
 export type { Logger } from "./logger/logger.js";
 export { createLazyLogger, createLogger } from "./logger/logger.js";
 // Presets
-export type { IDockerCompose, IDrizzle, INextjs, NextPreset } from "./presets/index.js";
+export type {
+	IDockerCompose,
+	IDrizzle,
+	INextjs,
+	NextPreset,
+} from "./presets/index.js";
 export {
 	docker,
 	dockerCompose,

package/src/orchestrator/presets/docker.ts

@@ -6,14 +6,16 @@ import type {
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,
-	IdentityAccessor,
 	Runnable,
 	Token,
 } from "../core/types.js";
+import type { Identity } from "../utils/dna.js";
 
 export interface IDockerCompose extends ICommand {
 	file(path: string): IDockerCompose;
+	logs(options: { silent?: boolean }): IDockerCompose;
 	up(options?: { detach?: boolean }): IDockerCompose;
+	withIdentity(suffix: string): IDockerCompose;
 }
 
 interface DockerComposeState {
@@ -49,24 +51,16 @@ class DockerCompose implements IDockerCompose {
 
 	// ─── ICommand delegation (returns IDockerCompose for chaining) ───────
 
-	get identity(): IdentityAccessor {
-		const innerAccessor = this.inner.identity;
-		const self = this;
-		const setter = (suffix: string): IDockerCompose => {
-			return new DockerCompose(
-				self.inner.identity(suffix),
-				self.dcState,
-			);
-		};
-		Object.defineProperty(setter, "name", {
-			configurable: true,
-			value: innerAccessor.name,
-		});
-		return Object.assign(setter, {
-			localhostUrl: innerAccessor.localhostUrl,
-			port: innerAccessor.port,
-			url: innerAccessor.url,
-		}) as IdentityAccessor;
+	get identity(): Identity {
+		return this.inner.identity;
+	}
+
+	withIdentity(suffix: string): IDockerCompose {
+		return new DockerCompose(this.inner.withIdentity(suffix), this.dcState);
+	}
+
+	logs(options: { silent?: boolean }): IDockerCompose {
+		return new DockerCompose(this.inner.logs(options), this.dcState);
 	}
 
 	flag(name: string, value?: Token): IDockerCompose {
@@ -94,10 +88,7 @@ class DockerCompose implements IDockerCompose {
 	}
 
 	dependsOn(...deps: Runnable[]): IDockerCompose {
-		return new DockerCompose(
-			this.inner.dependsOn(...deps),
-			this.dcState,
-		);
+		return new DockerCompose(this.inner.dependsOn(...deps), this.dcState);
 	}
 
 	collectNames(): string[] {

package/src/orchestrator/presets/index.ts

@@ -1,5 +1,5 @@
-export { type IDockerCompose, docker, dockerCompose } from "./docker.js";
-export { type IDrizzle, drizzle } from "./drizzle.js";
+export { docker, dockerCompose, type IDockerCompose } from "./docker.js";
+export { drizzle, type IDrizzle } from "./drizzle.js";
 export { esbuild, esbuildWatch } from "./esbuild.js";
 export { hono } from "./hono.js";
 export { type INextjs, type NextPreset, next, nextjs } from "./nextjs.js";

package/src/orchestrator/presets/nextjs.ts

@@ -6,12 +6,15 @@ import type {
 	HealthCheck,
 	HealthCheckCallback,
 	ICommand,
-	IdentityAccessor,
 	Runnable,
 	Token,
 } from "../core/types.js";
+import type { Identity } from "../utils/dna.js";
 
-export interface INextjs extends ICommand {}
+export interface INextjs extends ICommand {
+	logs(options: { silent?: boolean }): INextjs;
+	withIdentity(suffix: string): INextjs;
+}
 
 /** @deprecated Use `INextjs` instead */
 export type NextPreset = INextjs;
@@ -26,21 +29,16 @@ class Nextjs implements INextjs {
 
 	// ─── ICommand delegation (returns INextjs for chaining) ─────────────
 
-	get identity(): IdentityAccessor {
-		const innerAccessor = this.inner.identity;
-		const self = this;
-		const setter = (suffix: string): INextjs => {
-			return new Nextjs(self.inner.identity(suffix));
-		};
-		Object.defineProperty(setter, "name", {
-			configurable: true,
-			value: innerAccessor.name,
-		});
-		return Object.assign(setter, {
-			localhostUrl: innerAccessor.localhostUrl,
-			port: innerAccessor.port,
-			url: innerAccessor.url,
-		}) as IdentityAccessor;
+	get identity(): Identity {
+		return this.inner.identity;
+	}
+
+	withIdentity(suffix: string): INextjs {
+		return new Nextjs(this.inner.withIdentity(suffix));
+	}
+
+	logs(options: { silent?: boolean }): INextjs {
+		return new Nextjs(this.inner.logs(options));
 	}
 
 	flag(name: string, value?: Token): INextjs {

package/src/orchestrator/utils/dna.ts

@@ -12,7 +12,16 @@ const RESERVED_PORTS = new Set([
 	5984, // CouchDB
 	6379, // Redis
 	6380, // Redis alt
-	6660, 6661, 6662, 6663, 6664, 6665, 6666, 6667, 6668, 6669, // IRC
+	6660,
+	6661,
+	6662,
+	6663,
+	6664,
+	6665,
+	6666,
+	6667,
+	6668,
+	6669, // IRC
 	6697, // IRC over TLS (ircs-u)
 	7474, // Neo4j
 	8080, // HTTP alternate
@@ -32,23 +41,23 @@ function computePort(
 ): number {
 	const span = range.max - range.min + 1;
 	for (let attempt = 0; attempt < 10; attempt++) {
-		const input = attempt === 0 ? `${cwd}:${suffix}` : `${cwd}:${suffix}:${attempt}`;
+		const input =
+			attempt === 0 ? `${cwd}:${suffix}` : `${cwd}:${suffix}:${attempt}`;
 		const hash = createHash("md5").update(input).digest("hex");
 		const num = Number.parseInt(hash.slice(0, 8), 16);
 		const port = range.min + (num % span);
 		if (!RESERVED_PORTS.has(port)) return port;
 	}
 	// Extremely unlikely fallback — just offset from the last attempt
-	const hash = createHash("md5").update(`${cwd}:${suffix}:fallback`).digest("hex");
+	const hash = createHash("md5")
+		.update(`${cwd}:${suffix}:fallback`)
+		.digest("hex");
 	const num = Number.parseInt(hash.slice(0, 8), 16);
 	return range.min + (num % span);
 }
 
 export interface Identity {
-	localhostUrl: (
-		path?: string,
-		options?: { portIdentity?: string },
-	) => Token;
+	localhostUrl: (path?: string, options?: { portIdentity?: string }) => Token;
 	readonly name: string;
 	port: (identityName?: string) => Token;
 	url: (path?: string, options?: { portIdentity?: string }) => Token;