buncargo 1.0.26 → 3.0.0

package/src/cli/commands/runtime.ts

@@ -0,0 +1,72 @@
+import { loadDevEnv } from "../../loader";
+import { runCli } from "../run-cli";
+
+export async function loadEnv() {
+	try {
+		return await loadDevEnv();
+	} catch (error) {
+		console.error(`❌ ${error instanceof Error ? error.message : error}`);
+		process.exit(1);
+	}
+}
+
+export async function handleDev(args: string[]): Promise<void> {
+	const env = await loadEnv();
+	await runCli(env, { args });
+}
+
+export async function handlePrisma(args: string[]): Promise<void> {
+	const env = await loadEnv();
+
+	if (!env.prisma) {
+		console.error("❌ Prisma is not configured in your dev config.");
+		console.error("");
+		console.error("   Add prisma to your config:");
+		console.error("");
+		console.error("   export default defineDevConfig({");
+		console.error("     ...");
+		console.error("     prisma: {");
+		console.error("       cwd: 'packages/prisma'");
+		console.error("     }");
+		console.error("   })");
+		process.exit(1);
+	}
+
+	const running = await env.isRunning();
+	if (!running) {
+		console.log("🐳 Starting database container...");
+		await env.start({ startServers: false, wait: true });
+	}
+
+	const exitCode = await env.prisma.run(args);
+	process.exit(exitCode);
+}
+
+export async function handleEnv(): Promise<void> {
+	const env = await loadEnv();
+	console.log(
+		JSON.stringify(
+			{
+				projectName: env.projectName,
+				ports: env.ports,
+				urls: env.urls,
+				portOffset: env.portOffset,
+				isWorktree: env.isWorktree,
+				localIp: env.localIp,
+				root: env.root,
+			},
+			null,
+			2,
+		),
+	);
+}
+
+export async function handleTypecheck(): Promise<void> {
+	const env = await loadEnv();
+	const { runWorkspaceTypecheck } = await import("../../typecheck");
+	const result = await runWorkspaceTypecheck({
+		root: env.root,
+		verbose: true,
+	});
+	process.exit(result.success ? 0 : 1);
+}

package/src/cli/commands/version.ts

@@ -0,0 +1,4 @@
+export function showVersion(): void {
+	const pkg = require("../../../package.json");
+	console.log(`buncargo v${pkg.version}`);
+}

package/src/cli/index.ts

@@ -0,0 +1 @@
+export * from "./run-cli";

package/{cli.ts → src/cli/run-cli.ts}

@@ -1,12 +1,19 @@
 import { spawn } from "node:child_process";
-import { killProcessesOnAppPorts } from "./core/process";
-import { spawnWatchdog, startHeartbeat, stopHeartbeat } from "./core/watchdog";
+import { killProcessesOnAppPorts } from "../core/process";
+import {
+	type PublicTunnel,
+	resolveExposeTargets,
+	startPublicTunnels,
+	stopPublicTunnels,
+} from "../core/tunnel";
+import { spawnWatchdog, startHeartbeat, stopHeartbeat } from "../core/watchdog";
+import { logPublicUrls } from "../environment/logging";
 import type {
 	AppConfig,
 	CliOptions,
 	DevEnvironment,
 	ServiceConfig,
-} from "./types";
+} from "../types";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // CLI Runner
@@ -20,6 +27,7 @@ const ACCEPTED_FLAGS = [
 	"--migrate",
 	"--seed",
 	"--up-only",
+	"--expose",
 ] as const;
 
 /**
@@ -36,12 +44,15 @@ Options:
   --migrate   Run migrations and exit
   --seed      Run migrations and seeders, then exit
   --up-only   Start containers and run migrations, then exit (no dev servers)
+  --expose    Expose configured targets via public quick tunnels
 
 Examples:
   bun dev              Start dev environment with all services
   bun dev --seed       Run migrations and seed the database
   bun dev --down       Stop all containers
   bun dev --reset      Stop containers and remove all data
+  bun dev --expose     Expose all targets with expose: true
+  bun dev --expose=api,web  Expose specific targets
 `);
 }
 
@@ -50,7 +61,13 @@ Examples:
  */
 function getUnknownFlags(args: string[]): string[] {
 	return args.filter(
-		(arg) => arg.startsWith("--") && !ACCEPTED_FLAGS.includes(arg as typeof ACCEPTED_FLAGS[number]),
+		(arg) =>
+			arg.startsWith("--") &&
+			!ACCEPTED_FLAGS.includes(
+				(arg.includes("=")
+					? arg.split("=")[0]
+					: arg) as (typeof ACCEPTED_FLAGS)[number],
+			),
 	);
 }
 
@@ -79,6 +96,16 @@ export async function runCli<
 		watchdogTimeout = 10,
 		devServersCommand,
 	} = options;
+	const exposeRequested = hasFlag(args, "--expose");
+	const exposeValue = getFlagValue(args, "--expose");
+	let tunnels: PublicTunnel[] = [];
+
+	async function cleanupTunnels(): Promise<void> {
+		env.clearPublicUrls();
+		if (tunnels.length === 0) return;
+		await stopPublicTunnels(tunnels);
+		tunnels = [];
+	}
 
 	// Handle --help
 	if (args.includes("--help")) {
@@ -89,7 +116,9 @@ export async function runCli<
 	// Validate flags
 	const unknownFlags = getUnknownFlags(args);
 	if (unknownFlags.length > 0) {
-		console.error(`❌ Unknown flag${unknownFlags.length > 1 ? "s" : ""}: ${unknownFlags.join(", ")}`);
+		console.error(
+			`❌ Unknown flag${unknownFlags.length > 1 ? "s" : ""}: ${unknownFlags.join(", ")}`,
+		);
 		console.error("");
 		printHelp();
 		process.exit(1);
@@ -98,6 +127,7 @@ export async function runCli<
 	// Handle --down (no need to start anything)
 	if (args.includes("--down")) {
 		env.logInfo();
+		await cleanupTunnels();
 		await env.stop();
 		process.exit(0);
 	}
@@ -105,6 +135,7 @@ export async function runCli<
 	// Handle --reset (no need to start anything)
 	if (args.includes("--reset")) {
 		env.logInfo();
+		await cleanupTunnels();
 		await env.stop({ removeVolumes: true });
 		process.exit(0);
 	}
@@ -114,10 +145,50 @@ export async function runCli<
 	const skipSeed = args.includes("--seed");
 	await env.start({ startServers: false, wait: true, skipSeed });
 
+	if (exposeRequested) {
+		const { targets, unknownNames, notEnabledNames } = resolveExposeTargets(
+			env,
+			exposeValue,
+		);
+		if (unknownNames.length > 0) {
+			console.error(
+				`❌ Unknown expose target${unknownNames.length > 1 ? "s" : ""}: ${unknownNames.join(", ")}`,
+			);
+			await cleanupTunnels();
+			process.exit(1);
+		}
+		if (notEnabledNames.length > 0) {
+			console.error(
+				`❌ Target${notEnabledNames.length > 1 ? "s" : ""} missing expose: true: ${notEnabledNames.join(", ")}`,
+			);
+			console.error(
+				"   Mark these in dev.config.ts with expose: true or remove them from --expose.",
+			);
+			await cleanupTunnels();
+			process.exit(1);
+		}
+		if (targets.length === 0) {
+			console.error(
+				"❌ No expose targets selected. Add expose: true to services/apps or pass names with --expose=<name>.",
+			);
+			await cleanupTunnels();
+			process.exit(1);
+		}
+
+		tunnels = await startPublicTunnels(targets);
+		env.setPublicUrls(
+			Object.fromEntries(
+				tunnels.map((tunnel) => [tunnel.name, tunnel.publicUrl]),
+			) as typeof env.publicUrls,
+		);
+		logPublicUrls(tunnels);
+	}
+
 	// Handle --migrate (exit after migrations)
 	if (args.includes("--migrate")) {
 		console.log("");
 		console.log("✅ Migrations applied successfully");
+		await cleanupTunnels();
 		process.exit(0);
 	}
 
@@ -135,10 +206,12 @@ export async function runCli<
 			if (result.stdout) {
 				console.error(result.stdout);
 			}
+			await cleanupTunnels();
 			process.exit(1);
 		}
 		console.log("");
 		console.log("✅ Seeding complete");
+		await cleanupTunnels();
 		process.exit(0);
 	}
 
@@ -147,6 +220,7 @@ export async function runCli<
 		console.log("");
 		console.log("✅ Containers started. Environment ready.");
 		console.log("");
+		await cleanupTunnels();
 		process.exit(0);
 	}
 
@@ -155,6 +229,7 @@ export async function runCli<
 		await spawnWatchdog(env.projectName, env.root, {
 			timeoutMinutes: watchdogTimeout,
 			verbose: true,
+			composeFile: env.composeFile,
 		});
 		startHeartbeat(env.projectName);
 	}
@@ -166,6 +241,7 @@ export async function runCli<
 		console.log("✅ Containers ready. No apps configured.");
 		// Keep process alive if no apps
 		await new Promise(() => {});
+		await cleanupTunnels();
 		return;
 	}
 
@@ -177,10 +253,16 @@ export async function runCli<
 	console.log("🔧 Starting dev servers...");
 	console.log("");
 
-	await runCommand(command, env.root, env.buildEnvVars());
+	await runCommand(command, env.root, env.buildEnvVars(), {
+		onSignal: async () => {
+			await cleanupTunnels();
+			stopHeartbeat();
+		},
+	});
 
 	// Clean up heartbeat on exit
 	stopHeartbeat();
+	await cleanupTunnels();
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -228,7 +310,11 @@ function runCommand(
 	command: string,
 	cwd: string,
 	envVars: Record<string, string>,
+	options: {
+		onSignal?: () => void | Promise<void>;
+	} = {},
 ): Promise<void> {
+	const { onSignal } = options;
 	return new Promise((resolve, reject) => {
 		const proc = spawn(command, [], {
 			cwd,
@@ -249,6 +335,9 @@ function runCommand(
 
 		// Handle SIGINT/SIGTERM
 		const cleanup = () => {
+			if (onSignal) {
+				void onSignal();
+			}
 			proc.kill("SIGTERM");
 		};
 

package/src/config/define-config.ts

@@ -0,0 +1,30 @@
+import type {
+	AppConfig,
+	DevConfig,
+	DevHooks,
+	DevOptions,
+	DockerComposeGenerationOptions,
+	EnvVarsBuilder,
+	MigrationConfig,
+	PrismaConfig,
+	SeedConfig,
+	ServiceConfig,
+} from "../types";
+
+export function defineDevConfig<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig> = Record<string, never>,
+>(config: {
+	projectPrefix: string;
+	services: TServices;
+	apps?: TApps;
+	envVars?: EnvVarsBuilder<TServices, TApps>;
+	hooks?: DevHooks<TServices, TApps>;
+	migrations?: MigrationConfig[];
+	seed?: SeedConfig<TServices, TApps>;
+	prisma?: PrismaConfig;
+	options?: DevOptions;
+	docker?: DockerComposeGenerationOptions;
+}): DevConfig<TServices, TApps> {
+	return config as DevConfig<TServices, TApps>;
+}

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export { defineDevConfig } from "./define-config";
+export { definePartialConfig, mergeConfigs } from "./merge-configs";
+export { assertValidConfig, validateConfig } from "./validate-config";

package/src/config/merge-configs.ts

@@ -0,0 +1,33 @@
+import type { AppConfig, DevConfig, ServiceConfig } from "../types";
+
+export function mergeConfigs<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	base: DevConfig<TServices, TApps>,
+	overrides: Partial<DevConfig<TServices, TApps>>,
+): DevConfig<TServices, TApps> {
+	return {
+		...base,
+		...overrides,
+		services: { ...base.services, ...overrides.services } as TServices,
+		apps: { ...base.apps, ...overrides.apps } as TApps,
+		hooks: { ...base.hooks, ...overrides.hooks },
+		migrations: overrides.migrations ?? base.migrations,
+		seed: overrides.seed ?? base.seed,
+		options: { ...base.options, ...overrides.options },
+		docker: { ...base.docker, ...overrides.docker },
+	};
+}
+
+export function definePartialConfig<
+	TServices extends Record<string, ServiceConfig> = Record<
+		string,
+		ServiceConfig
+	>,
+	TApps extends Record<string, AppConfig> = Record<string, AppConfig>,
+>(
+	config: Partial<DevConfig<TServices, TApps>>,
+): Partial<DevConfig<TServices, TApps>> {
+	return config;
+}

package/src/config/validate-config.ts

@@ -0,0 +1,136 @@
+import { isAbsolute, normalize } from "node:path";
+import type { AppConfig, DevConfig, ServiceConfig } from "../types";
+
+const BUILTIN_DOCKER_PRESETS = new Set(["postgres", "redis", "clickhouse"]);
+
+function inferBuiltInPreset(serviceName: string): string | null {
+	const normalized = serviceName.toLowerCase();
+	return BUILTIN_DOCKER_PRESETS.has(normalized) ? normalized : null;
+}
+
+export function validateConfig<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(config: DevConfig<TServices, TApps>): string[] {
+	const errors: string[] = [];
+	const composeServiceNames = new Set<string>();
+
+	if (!config.projectPrefix) {
+		errors.push("projectPrefix is required");
+	} else if (!/^[a-z][a-z0-9-]*$/.test(config.projectPrefix)) {
+		errors.push(
+			"projectPrefix must start with a letter and contain only lowercase letters, numbers, and hyphens",
+		);
+	}
+
+	if (!config.services || Object.keys(config.services).length === 0) {
+		errors.push("At least one service is required");
+	}
+
+	for (const [name, service] of Object.entries(config.services ?? {})) {
+		if (!service.port || typeof service.port !== "number") {
+			errors.push(`Service "${name}" must have a valid port number`);
+		}
+		if (service.port < 1 || service.port > 65535) {
+			errors.push(`Service "${name}" port must be between 1 and 65535`);
+		}
+		if (
+			service.secondaryPort !== undefined &&
+			(service.secondaryPort < 1 || service.secondaryPort > 65535)
+		) {
+			errors.push(
+				`Service "${name}" secondaryPort must be between 1 and 65535`,
+			);
+		}
+
+		const composeServiceName = service.serviceName ?? name;
+		if (composeServiceNames.has(composeServiceName)) {
+			errors.push(
+				`Duplicate compose service name "${composeServiceName}". Use unique serviceName values.`,
+			);
+		}
+		composeServiceNames.add(composeServiceName);
+
+		const dockerConfig = service.docker;
+		const preset = inferBuiltInPreset(name);
+		if (!dockerConfig && !preset) {
+			errors.push(
+				`Service "${name}" must define docker config (helper or raw) because it has no built-in preset.`,
+			);
+		}
+		if (
+			dockerConfig &&
+			typeof dockerConfig === "object" &&
+			"kind" in dockerConfig &&
+			dockerConfig.kind === "preset"
+		) {
+			const presetName = dockerConfig.preset;
+			if (
+				typeof presetName !== "string" ||
+				!BUILTIN_DOCKER_PRESETS.has(presetName)
+			) {
+				errors.push(
+					`Service "${name}" has invalid docker preset "${presetName}".`,
+				);
+			}
+		}
+	}
+
+	if (config.docker?.writeStrategy) {
+		const writeStrategy = config.docker.writeStrategy;
+		if (writeStrategy !== "always" && writeStrategy !== "if-missing") {
+			errors.push(
+				`docker.writeStrategy "${String(writeStrategy)}" is invalid. Use "always" or "if-missing".`,
+			);
+		}
+	}
+
+	if (config.docker?.generatedFile) {
+		const generatedFile = config.docker.generatedFile;
+		if (isAbsolute(generatedFile)) {
+			errors.push(
+				"docker.generatedFile must be a relative path inside the repo.",
+			);
+		}
+		const normalized = normalize(generatedFile).replace(/\\/g, "/");
+		if (normalized === ".." || normalized.startsWith("../")) {
+			errors.push(
+				"docker.generatedFile cannot point outside the repository root.",
+			);
+		}
+	}
+
+	for (const [name, app] of Object.entries(config.apps ?? {})) {
+		if (!app.port || typeof app.port !== "number") {
+			errors.push(`App "${name}" must have a valid port number`);
+		}
+		if (!app.devCommand) {
+			errors.push(`App "${name}" must have a devCommand`);
+		}
+	}
+
+	for (const migration of config.migrations ?? []) {
+		if (!migration.name) {
+			errors.push("Migration must have a name");
+		}
+		if (!migration.command) {
+			errors.push(`Migration "${migration.name}" must have a command`);
+		}
+	}
+
+	if (config.seed && !config.seed.command) {
+		errors.push("Seed must have a command");
+	}
+
+	return errors;
+}
+
+export function assertValidConfig<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(config: DevConfig<TServices, TApps>): void {
+	const errors = validateConfig(config);
+	if (errors.length > 0) {
+		throw new Error(`Invalid dev config:\n  - ${errors.join("\n  - ")}`);
+	}
+}

package/{core → src/core}/index.ts

@@ -1,7 +1,7 @@
-// Re-export all core utilities
-export * from "./docker";
+// Re-export core runtime utilities only.
 export * from "./network";
 export * from "./ports";
 export * from "./process";
+export * from "./tunnel";
 export * from "./utils";
 export * from "./watchdog";

package/{core → src/core}/ports.ts

@@ -57,6 +57,28 @@ export function isWorktree(root?: string): boolean {
 	return getWorktreeName(root) !== null;
 }
 
+/**
+ * Sanitize a string for use as a Docker Compose project suffix.
+ */
+function sanitizeProjectSuffix(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Get a sanitized worktree-derived suffix for Docker project isolation.
+ * Returns null when not running in a worktree.
+ */
+export function getWorktreeProjectSuffix(root?: string): string | null {
+	const worktreeName = getWorktreeName(root);
+	if (!worktreeName) return null;
+	const sanitized = sanitizeProjectSuffix(worktreeName);
+	return sanitized || "worktree";
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Port Offset Calculation
 // ═══════════════════════════════════════════════════════════════════════════
@@ -104,6 +126,49 @@ export function getProjectName(
 	return suffix ? `${baseName}-${suffix}` : baseName;
 }
 
+export interface DevIdentityOptions {
+	projectPrefix: string;
+	suffix?: string;
+	root?: string;
+	worktreeIsolation?: boolean;
+}
+
+export interface DevIdentity {
+	worktree: boolean;
+	worktreeSuffix: string | null;
+	projectSuffix?: string;
+	projectName: string;
+	portOffset: number;
+}
+
+/**
+ * Compute all identity values used by the dev environment in one place.
+ */
+export function computeDevIdentity(options: DevIdentityOptions): DevIdentity {
+	const {
+		projectPrefix,
+		suffix,
+		root: providedRoot,
+		worktreeIsolation = true,
+	} = options;
+	const root = providedRoot ?? findMonorepoRoot();
+	const worktree = isWorktree(root);
+	const worktreeSuffix =
+		worktree && worktreeIsolation ? getWorktreeProjectSuffix(root) : null;
+	const projectSuffix =
+		[suffix, worktreeSuffix].filter(Boolean).join("-") || undefined;
+	const projectName = getProjectName(projectPrefix, projectSuffix, root);
+	const portOffset = calculatePortOffset(suffix, root);
+
+	return {
+		worktree,
+		worktreeSuffix,
+		projectSuffix,
+		projectName,
+		portOffset,
+	};
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Port Computation
 // ═══════════════════════════════════════════════════════════════════════════
@@ -185,7 +250,9 @@ function buildServiceUrl(
 		case "mysql":
 			return `mysql://${user}:${password}@${ctx.host}:${ctx.port}/${database}`;
 		case "mongodb":
-			return `mongodb://${ctx.host}:${ctx.port}/${database}`;
+			return database
+				? `mongodb://${ctx.host}:${ctx.port}/${database}`
+				: `mongodb://${ctx.host}:${ctx.port}`;
 		default:
 			return null;
 	}

package/{core → src/core}/process.ts

@@ -395,11 +395,15 @@ export async function killProcessesOnAppPorts(
 				killedAny = true;
 			}
 			if (verbose) {
-				console.log(`⚠️  Port ${port} (${name}) is in use by process ${existingPid}`);
+				console.log(
+					`⚠️  Port ${port} (${name}) is in use by process ${existingPid}`,
+				);
 			}
 			const killed = await killProcessOnPortAndWait(port, { verbose });
 			if (!killed && verbose) {
-				console.log(`   ⚠️  Could not kill process on port ${port}, server may fail to start`);
+				console.log(
+					`   ⚠️  Could not kill process on port ${port}, server may fail to start`,
+				);
 			}
 		}
 	}