@buildepicshit/cli 0.0.3 → 0.0.5

package/package.json

@@ -16,7 +16,8 @@
 		"esbuild": "^0.25.5"
 	},
 	"exports": {
-		".": "./src/orchestrator/index.ts"
+		".": "./src/orchestrator/index.ts",
+		"./presets": "./src/orchestrator/presets/index.ts"
 	},
 	"files": [
 		"dist",
@@ -34,5 +35,5 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"type": "module",
-	"version": "0.0.3"
+	"version": "0.0.5"
 }

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

@@ -119,44 +119,44 @@ describe("cmd", () => {
 describe("command identity", () => {
 	it("returns default identity from dir basename", () => {
 		const c = cmd("node server.js").dir("apps/api");
-		const id = c.identity();
+		const id = c.identity;
 		expect(id.name).toBe("api");
 	});
 
 	it("returns default identity from display name", () => {
 		const c = cmd("node server.js").as("my-service");
-		expect(c.identity().name).toBe("my-service");
+		expect(c.identity.name).toBe("my-service");
 	});
 
 	it("returns default identity from base command", () => {
 		const c = cmd("tsx watch src/main.ts");
-		expect(c.identity().name).toBe("tsx");
+		expect(c.identity.name).toBe("tsx");
 	});
 
-	it("overrides identity with .identity(suffix)", () => {
-		const c = cmd("node server.js").identity("custom").dir("apps/api");
-		expect(c.identity().name).toBe("custom");
+	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");
-		expect(c.identity().name).toBe("api");
+		expect(c.identity.name).toBe("api");
 	});
 
 	it("identity is immutable across branches", () => {
 		const base = cmd("node server.js");
-		const withId = base.identity("custom");
-		expect(base.identity().name).toBe("node");
-		expect(withId.identity().name).toBe("custom");
+		const withId = base.withIdentity("custom");
+		expect(base.identity.name).toBe("node");
+		expect(withId.identity.name).toBe("custom");
 	});
 
-	it("identity().port() returns a token", async () => {
-		const c = cmd("node server.js").identity("api").dir("apps/api");
-		const token = c.identity().port();
+	it("identity.port() returns a token", async () => {
+		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),
@@ -166,40 +166,82 @@ describe("command identity", () => {
 		expect(port).toBeLessThanOrEqual(9999);
 	});
 
-	it("identity().localhostUrl() returns a token", async () => {
-		const c = cmd("node server.js").identity("api");
-		const token = c.identity().localhostUrl("/health");
+	it("identity.localhostUrl() returns a token", async () => {
+		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() })
+			.env({ API_URL: server.identity.localhostUrl() })
 			.build(ctx);
 		expect(built.env.API_URL).toMatch(/^http:\/\/localhost:\d+$/);
 	});
+
+	it("identity.port(name) resolves a named sub-identity", async () => {
+		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);
+		// 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").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);
+		expect(url).toBe(`http://localhost:${minioPort}/health`);
+	});
+});
+
+describe("multiple waitFor", () => {
+	it("appends health checks instead of replacing", () => {
+		const c = cmd("node server.js")
+			.waitFor(health.http("http://localhost:3000"))
+			.waitFor(health.tcp("localhost", "5432"));
+		// The command should build without error (checks are stored internally)
+		expect(c).toBeDefined();
+	});
+
+	it("accepts callback form for multiple waitFor", async () => {
+		const c = cmd("node server.js")
+			.withIdentity("api")
+			.waitFor((self) => health.http(self.identity.url("/livez")))
+			.waitFor((self) => health.tcp("localhost", self.identity.port()));
+		const built = await c.build(ctx);
+		expect(built).toBeDefined();
+	});
 });
 
 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")));
+			.waitFor((self) => health.http(self.identity.url("/livez")));
 
 		const built = await c.build(ctx);
 		expect(built).toBeDefined();
-		expect(c.identity().name).toBe("api");
+		expect(c.identity.name).toBe("api");
 	});
 });
 
 describe("env callback form", () => {
 	it("accepts a callback that receives the command", async () => {
 		const c = cmd("node server.js")
-			.identity("api")
-			.env((self) => ({ PORT: self.identity().port() }));
+			.withIdentity("api")
+			.env((self) => ({ PORT: self.identity.port() }));
 
 		const built = await c.build(ctx);
 		const port = Number.parseInt(built.env.PORT, 10);
@@ -209,9 +251,9 @@ 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((self) => ({ PORT: self.identity.port() }))
 			.env({ B: "2" });
 
 		const built = await c.build(ctx);

package/src/orchestrator/core/command.ts

@@ -5,7 +5,6 @@ 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 {
@@ -29,7 +28,7 @@ interface CommandState {
 	readonly displayName: string | null;
 	readonly envSources: readonly EnvSource[];
 	readonly flags: readonly { name: string; value?: Token }[];
-	readonly healthCheck: HealthCheck | null;
+	readonly healthChecks: readonly HealthCheck[];
 	readonly identitySuffix: string | null;
 }
 
@@ -41,16 +40,14 @@ class Command implements ICommand {
 		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());
+	get identity() {
+		return createIdentity(
+			this.state.identitySuffix ?? this.deriveName(),
+		);
+	}
+
+	withIdentity(suffix: string): ICommand {
+		return new Command({ ...this.state, identitySuffix: suffix });
 	}
 
 	flag(name: string, value?: Token): ICommand {
@@ -92,7 +89,7 @@ class Command implements ICommand {
 		const resolved = typeof check === "function" ? check(this) : check;
 		return new Command({
 			...this.state,
-			healthCheck: resolved,
+			healthChecks: [...this.state.healthChecks, resolved],
 		});
 	}
 
@@ -185,8 +182,11 @@ class Command implements ICommand {
 			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.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) =>
@@ -228,16 +228,18 @@ class Command implements ICommand {
 			});
 		});
 
-		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;
+		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);
@@ -315,7 +317,7 @@ export function cmd(base: string): ICommand {
 		displayName: null,
 		envSources: [],
 		flags: [],
-		healthCheck: null,
+		healthChecks: [],
 		identitySuffix: null,
 	});
 }

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

@@ -20,14 +20,19 @@ 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.stdout(pattern)
+ * 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

@@ -8,6 +8,7 @@ export {
 	execHealthCheck,
 	health,
 	httpHealthCheck,
+	postgresHealthCheck,
 	stdoutHealthCheck,
 	tcpHealthCheck,
 } from "./health-check.js";
@@ -28,6 +29,7 @@ export type {
 	HealthCheckCallback,
 	ICommand,
 	ICompound,
+
 	LazyEnvSource,
 	ProcessStatus,
 	Runnable,

package/src/orchestrator/core/types.ts

@@ -56,10 +56,10 @@ export interface ICommand {
 	dir(path: string): ICommand;
 	env(source: EnvSource): ICommand;
 	flag(name: string, value?: Token): ICommand;
-	identity(): Identity;
-	identity(suffix: string): ICommand;
+	readonly identity: Identity;
 	run(): Promise<void>;
 	waitFor(check: HealthCheck | HealthCheckCallback): ICommand;
+	withIdentity(suffix: string): ICommand;
 }
 
 // ─── Compound ────────────────────────────────────────────────────────────────

package/src/orchestrator/index.ts

@@ -10,6 +10,7 @@ export {
 	health,
 	httpHealthCheck,
 	par,
+	postgresHealthCheck,
 	seq,
 	stdoutHealthCheck,
 	tcpHealthCheck,
@@ -24,6 +25,7 @@ export type {
 	HealthCheckCallback,
 	ICommand,
 	ICompound,
+
 	ProcessStatus,
 	Runnable,
 	Token,
@@ -32,13 +34,16 @@ export type {
 export type { Logger } from "./logger/logger.js";
 export { createLazyLogger, createLogger } from "./logger/logger.js";
 // Presets
-export type { NextPreset } from "./presets/index.js";
+export type { IDockerCompose, IDrizzle, INextjs, NextPreset } from "./presets/index.js";
 export {
 	docker,
+	dockerCompose,
+	drizzle,
 	esbuild,
 	esbuildWatch,
 	hono,
 	next,
+	nextjs,
 	nodemon,
 	tsx,
 } from "./presets/index.js";

package/src/orchestrator/presets/docker.ts

@@ -1,6 +1,133 @@
 import { cmd } from "../core/command.js";
-import type { ICommand, Token } from "../core/types.js";
+import type {
+	BuiltCommand,
+	ComputeContext,
+	EnvSource,
+	HealthCheck,
+	HealthCheckCallback,
+	ICommand,
+	Runnable,
+	Token,
+} from "../core/types.js";
+import type { Identity } from "../utils/dna.js";
 
+export interface IDockerCompose extends ICommand {
+	file(path: string): IDockerCompose;
+	up(options?: { detach?: boolean }): IDockerCompose;
+	withIdentity(suffix: string): IDockerCompose;
+}
+
+interface DockerComposeState {
+	readonly detach: boolean;
+	readonly filePath: string | null;
+}
+
+class DockerCompose implements IDockerCompose {
+	readonly __type = "command" as const;
+	private readonly inner: ICommand;
+	private readonly dcState: DockerComposeState;
+
+	constructor(inner: ICommand, dcState: DockerComposeState) {
+		this.inner = inner;
+		this.dcState = dcState;
+	}
+
+	// ─── Docker-compose-specific methods ─────────────────────────────────
+
+	up(options?: { detach?: boolean }): IDockerCompose {
+		return new DockerCompose(this.inner, {
+			...this.dcState,
+			detach: options?.detach ?? true,
+		});
+	}
+
+	file(path: string): IDockerCompose {
+		return new DockerCompose(this.inner, {
+			...this.dcState,
+			filePath: path,
+		});
+	}
+
+	// ─── ICommand delegation (returns IDockerCompose for chaining) ───────
+
+	get identity(): Identity {
+		return this.inner.identity;
+	}
+
+	withIdentity(suffix: string): IDockerCompose {
+		return new DockerCompose(this.inner.withIdentity(suffix), this.dcState);
+	}
+
+	flag(name: string, value?: Token): IDockerCompose {
+		return new DockerCompose(this.inner.flag(name, value), this.dcState);
+	}
+
+	arg(value: Token): IDockerCompose {
+		return new DockerCompose(this.inner.arg(value), this.dcState);
+	}
+
+	env(source: EnvSource): IDockerCompose {
+		return new DockerCompose(this.inner.env(source), this.dcState);
+	}
+
+	dir(path: string): IDockerCompose {
+		return new DockerCompose(this.inner.dir(path), this.dcState);
+	}
+
+	waitFor(check: HealthCheck | HealthCheckCallback): IDockerCompose {
+		return new DockerCompose(this.inner.waitFor(check), this.dcState);
+	}
+
+	as(name: string): IDockerCompose {
+		return new DockerCompose(this.inner.as(name), this.dcState);
+	}
+
+	dependsOn(...deps: Runnable[]): IDockerCompose {
+		return new DockerCompose(
+			this.inner.dependsOn(...deps),
+			this.dcState,
+		);
+	}
+
+	collectNames(): string[] {
+		return this.inner.collectNames();
+	}
+
+	async build(ctx: ComputeContext): Promise<BuiltCommand> {
+		// Build the final docker compose command from state
+		let command = this.inner;
+		if (this.dcState.filePath) {
+			command = command.flag("file", this.dcState.filePath);
+		}
+		command = command.arg("up");
+		if (this.dcState.detach) {
+			command = command.flag("detach");
+		}
+		return command.build(ctx);
+	}
+
+	async run(): Promise<void> {
+		// Build a resolved inner command with docker-compose args applied
+		let command = this.inner;
+		if (this.dcState.filePath) {
+			command = command.flag("file", this.dcState.filePath);
+		}
+		command = command.arg("up");
+		if (this.dcState.detach) {
+			command = command.flag("detach");
+		}
+		return command.run();
+	}
+}
+
+export function dockerCompose(): IDockerCompose {
+	return new DockerCompose(cmd("docker compose"), {
+		detach: false,
+		filePath: null,
+	});
+}
+
+/** @deprecated Use `dockerCompose()` instead */
 export function docker(options?: {
 	detach?: boolean;
 	file?: Token;

package/src/orchestrator/presets/drizzle.ts

@@ -0,0 +1,93 @@
+import { cmd } from "../core/command.js";
+import type {
+	EnvSource,
+	ICommand,
+	LazyEnvSource,
+	Runnable,
+	Token,
+} from "../core/types.js";
+
+export interface IDrizzle {
+	database(port: Token): IDrizzle;
+	dependsOn(...deps: Runnable[]): IDrizzle;
+	dir(path: string): IDrizzle;
+	envFile(source: LazyEnvSource): IDrizzle;
+	readonly migrate: ICommand;
+	readonly studio: ICommand;
+}
+
+interface DrizzleState {
+	readonly databasePort: Token | null;
+	readonly dependencies: readonly Runnable[];
+	readonly dirPath: string | null;
+	readonly envSources: readonly EnvSource[];
+}
+
+class Drizzle implements IDrizzle {
+	private readonly state: DrizzleState;
+
+	constructor(state: DrizzleState) {
+		this.state = state;
+	}
+
+	database(port: Token): IDrizzle {
+		return new Drizzle({ ...this.state, databasePort: port });
+	}
+
+	dependsOn(...deps: Runnable[]): IDrizzle {
+		return new Drizzle({
+			...this.state,
+			dependencies: [...this.state.dependencies, ...deps],
+		});
+	}
+
+	dir(path: string): IDrizzle {
+		return new Drizzle({ ...this.state, dirPath: path });
+	}
+
+	envFile(source: LazyEnvSource): IDrizzle {
+		return new Drizzle({
+			...this.state,
+			envSources: [...this.state.envSources, source],
+		});
+	}
+
+	get migrate(): ICommand {
+		return this.buildCommand("drizzle-kit migrate");
+	}
+
+	get studio(): ICommand {
+		return this.buildCommand("drizzle-kit studio");
+	}
+
+	private buildCommand(base: string): ICommand {
+		let command: ICommand = cmd(base);
+
+		if (this.state.dirPath) {
+			command = command.dir(this.state.dirPath);
+		}
+
+		for (const source of this.state.envSources) {
+			command = command.env(source);
+		}
+
+		if (this.state.databasePort) {
+			command = command.env({ DATABASE_PORT: this.state.databasePort });
+		}
+
+		if (this.state.dependencies.length > 0) {
+			command = command.dependsOn(...this.state.dependencies);
+		}
+
+		return command;
+	}
+}
+
+export function drizzle(): IDrizzle {
+	return new Drizzle({
+		databasePort: null,
+		dependencies: [],
+		dirPath: null,
+		envSources: [],
+	});
+}

package/src/orchestrator/presets/index.ts

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

package/src/orchestrator/presets/nextjs.ts

@@ -1,48 +1,90 @@
-import { cmd } from "../core/command";
-import { health } from "../core/health-check";
-import type { ICommand } from "../core/types";
-import { createIdentity } from "../utils/dna";
-
-export interface NextPreset {
-	build(): ICommand;
-	dev(): ICommand;
-	dir(path: string): NextPreset;
-	start(): ICommand;
+import { cmd } from "../core/command.js";
+import type {
+	BuiltCommand,
+	ComputeContext,
+	EnvSource,
+	HealthCheck,
+	HealthCheckCallback,
+	ICommand,
+	Runnable,
+	Token,
+} from "../core/types.js";
+import type { Identity } from "../utils/dna.js";
+
+export interface INextjs extends ICommand {
+	withIdentity(suffix: string): INextjs;
 }
 
-export function next(suffix = "next"): NextPreset {
-	const identity = createIdentity(suffix);
-	return createNextPreset(identity, null);
+/** @deprecated Use `INextjs` instead */
+export type NextPreset = INextjs;
+
+class Nextjs implements INextjs {
+	readonly __type = "command" as const;
+	private readonly inner: ICommand;
+
+	constructor(inner: ICommand) {
+		this.inner = inner;
+	}
+
+	// ─── ICommand delegation (returns INextjs for chaining) ─────────────
+
+	get identity(): Identity {
+		return this.inner.identity;
+	}
+
+	withIdentity(suffix: string): INextjs {
+		return new Nextjs(this.inner.withIdentity(suffix));
+	}
+
+	flag(name: string, value?: Token): INextjs {
+		return new Nextjs(this.inner.flag(name, value));
+	}
+
+	arg(value: Token): INextjs {
+		return new Nextjs(this.inner.arg(value));
+	}
+
+	env(source: EnvSource): INextjs {
+		return new Nextjs(this.inner.env(source));
+	}
+
+	dir(path: string): INextjs {
+		return new Nextjs(this.inner.dir(path));
+	}
+
+	waitFor(check: HealthCheck | HealthCheckCallback): INextjs {
+		return new Nextjs(this.inner.waitFor(check));
+	}
+
+	as(name: string): INextjs {
+		return new Nextjs(this.inner.as(name));
+	}
+
+	dependsOn(...deps: Runnable[]): INextjs {
+		return new Nextjs(this.inner.dependsOn(...deps));
+	}
+
+	collectNames(): string[] {
+		return this.inner.collectNames();
+	}
+
+	build(ctx: ComputeContext): Promise<BuiltCommand> {
+		return this.inner.build(ctx);
+	}
+
+	run(): Promise<void> {
+		return this.inner.run();
+	}
 }
 
-function createNextPreset(
-	identity: ReturnType<typeof createIdentity>,
-	dirPath: string | null,
-): NextPreset {
-	function applyDir(command: ICommand): ICommand {
-		return dirPath ? command.dir(dirPath) : command;
-	}
-
-	return {
-		build(): ICommand {
-			return applyDir(cmd("next build"));
-		},
-		dev(): ICommand {
-			return applyDir(
-				cmd("next dev")
-					.waitFor(health.http(identity.url("/livez")))
-					.env({ PORT: identity.port() }),
-			);
-		},
-		dir(path: string): NextPreset {
-			return createNextPreset(identity, path);
-		},
-		start(): ICommand {
-			return applyDir(
-				cmd("next start")
-					.waitFor(health.http(identity.url("/livez")))
-					.env({ PORT: identity.port() }),
-			);
-		},
-	};
+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(),
+	}));
+	return new Nextjs(inner);
 }
+
+/** @deprecated Use `nextjs()` instead */
+export const next = nextjs;

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

@@ -85,4 +85,49 @@ describe("DNA", () => {
 		const fromLocalhostUrl = await resolveToken(id.localhostUrl("/api"), ctx);
 		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);
+		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);
+		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);
+		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,
+		);
+		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,
+		);
+		expect(url).toBe(`http://localhost:${minioPort}/health`);
+	});
 });

package/src/orchestrator/utils/dna.ts

@@ -1,29 +1,69 @@
 import { createHash } from "node:crypto";
 import type { Token } from "../core/types.js";
 
+// Well-known/reserved ports in the 3000-9999 range to avoid
+const RESERVED_PORTS = new Set([
+	3306, // MySQL
+	3389, // RDP
+	4369, // Erlang EPMD
+	5432, // PostgreSQL
+	5433, // PostgreSQL alt
+	5672, // AMQP (RabbitMQ)
+	5984, // CouchDB
+	6379, // Redis
+	6380, // Redis alt
+	6660, 6661, 6662, 6663, 6664, 6665, 6666, 6667, 6668, 6669, // IRC
+	6697, // IRC over TLS (ircs-u)
+	7474, // Neo4j
+	8080, // HTTP alternate
+	8443, // HTTPS alternate
+	8888, // Common dev port
+	9042, // Cassandra
+	9090, // Prometheus
+	9200, // Elasticsearch HTTP
+	9300, // Elasticsearch transport
+	9418, // Git
+]);
+
 function computePort(
 	cwd: string,
 	suffix: string,
 	range = { max: 9999, min: 3000 },
 ): number {
-	const hash = createHash("md5").update(`${cwd}:${suffix}`).digest("hex");
+	const span = range.max - range.min + 1;
+	for (let attempt = 0; attempt < 10; 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 num = Number.parseInt(hash.slice(0, 8), 16);
-	return range.min + (num % (range.max - range.min + 1));
+	return range.min + (num % span);
 }
 
 export interface Identity {
-	localhostUrl: (path?: string) => Token;
+	localhostUrl: (
+		path?: string,
+		options?: { portIdentity?: string },
+	) => Token;
 	readonly name: string;
-	port: () => Token;
-	url: (path?: string) => Token;
+	port: (identityName?: string) => Token;
+	url: (path?: string, options?: { portIdentity?: string }) => Token;
 }
 
 export function createIdentity(suffix?: string): Identity {
 	const name = suffix || "";
 
-	const urlToken = (pathValue?: string): Token => {
+	const urlToken = (
+		pathValue?: string,
+		options?: { portIdentity?: string },
+	): Token => {
 		return async ({ cwd }) => {
-			const port = computePort(cwd, name);
+			const portName = options?.portIdentity ?? name;
+			const port = computePort(cwd, portName);
 			const base = `http://localhost:${port}`;
 			return pathValue ? `${base}${pathValue}` : base;
 		};
@@ -32,9 +72,10 @@ export function createIdentity(suffix?: string): Identity {
 	return {
 		localhostUrl: urlToken,
 		name,
-		port: (): Token => {
+		port: (identityName?: string): Token => {
 			return async ({ cwd }) => {
-				return computePort(cwd, name).toString();
+				const portName = identityName ?? name;
+				return computePort(cwd, portName).toString();
 			};
 		},
 		url: urlToken,