buncargo 1.0.29 → 3.2.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,18 @@
 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 type {
 	AppConfig,
 	CliOptions,
 	DevEnvironment,
 	ServiceConfig,
-} from "./types";
+} from "../types";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // CLI Runner
@@ -20,6 +26,7 @@ const ACCEPTED_FLAGS = [
 	"--migrate",
 	"--seed",
 	"--up-only",
+	"--expose",
 ] as const;
 
 /**
@@ -36,12 +43,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 +60,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],
+			),
 	);
 }
 
@@ -71,14 +87,37 @@ export async function runCli<
 	TApps extends Record<string, AppConfig>,
 >(
 	env: DevEnvironment<TServices, TApps>,
-	options: CliOptions = {},
+	options: CliOptions & {
+		/** Substitute tunnel helpers (used by CLI integration tests). */
+		cliTestTunnel?: {
+			resolveExposeTargets: typeof resolveExposeTargets;
+			startPublicTunnels: typeof startPublicTunnels;
+			stopPublicTunnels: typeof stopPublicTunnels;
+		};
+	} = {},
 ): Promise<void> {
 	const {
 		args = process.argv.slice(2),
 		watchdog = true,
 		watchdogTimeout = 10,
 		devServersCommand,
+		cliTestTunnel,
 	} = options;
+	const tunnelApi = cliTestTunnel ?? {
+		resolveExposeTargets,
+		startPublicTunnels,
+		stopPublicTunnels,
+	};
+	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 tunnelApi.stopPublicTunnels(tunnels);
+		tunnels = [];
+	}
 
 	// Handle --help
 	if (args.includes("--help")) {
@@ -89,7 +128,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 +139,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 +147,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);
 	}
@@ -112,12 +155,55 @@ export async function runCli<
 	// All other paths need containers + migrations
 	// Skip automatic seeding when --seed flag is used (CLI handles it explicitly)
 	const skipSeed = args.includes("--seed");
-	await env.start({ startServers: false, wait: true, skipSeed });
+	await env.start({
+		startServers: false,
+		wait: true,
+		skipSeed,
+		skipEnvironmentLog: exposeRequested,
+	});
+
+	if (exposeRequested) {
+		const { targets, unknownNames, notEnabledNames } =
+			tunnelApi.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 tunnelApi.startPublicTunnels(targets);
+		env.setPublicUrls(
+			Object.fromEntries(
+				tunnels.map((tunnel) => [tunnel.name, tunnel.publicUrl]),
+			) as typeof env.publicUrls,
+		);
+		env.logInfo("Dev Environment", tunnels);
+	}
 
 	// Handle --migrate (exit after migrations)
 	if (args.includes("--migrate")) {
 		console.log("");
 		console.log("✅ Migrations applied successfully");
+		await cleanupTunnels();
 		process.exit(0);
 	}
 
@@ -135,10 +221,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 +235,7 @@ export async function runCli<
 		console.log("");
 		console.log("✅ Containers started. Environment ready.");
 		console.log("");
+		await cleanupTunnels();
 		process.exit(0);
 	}
 
@@ -155,6 +244,7 @@ export async function runCli<
 		await spawnWatchdog(env.projectName, env.root, {
 			timeoutMinutes: watchdogTimeout,
 			verbose: true,
+			composeFile: env.composeFile,
 		});
 		startHeartbeat(env.projectName);
 	}
@@ -166,6 +256,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 +268,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 +325,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 +350,9 @@ function runCommand(
 
 		// Handle SIGINT/SIGTERM
 		const cleanup = () => {
+			if (onSignal) {
+				void onSignal();
+			}
 			proc.kill("SIGTERM");
 		};
 
@@ -262,10 +366,10 @@ function runCommand(
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Check if a CLI flag is present.
+ * Check if a CLI flag is present (including `--flag=value` form).
  */
 export function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
+	return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
 }
 
 /**

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

@@ -155,7 +155,8 @@ export function computeDevIdentity(options: DevIdentityOptions): DevIdentity {
 	const worktree = isWorktree(root);
 	const worktreeSuffix =
 		worktree && worktreeIsolation ? getWorktreeProjectSuffix(root) : null;
-	const projectSuffix = [suffix, worktreeSuffix].filter(Boolean).join("-") || undefined;
+	const projectSuffix =
+		[suffix, worktreeSuffix].filter(Boolean).join("-") || undefined;
 	const projectName = getProjectName(projectPrefix, projectSuffix, root);
 	const portOffset = calculatePortOffset(suffix, root);
 
@@ -249,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`,
+				);
 			}
 		}
 	}

package/src/core/quick-tunnel/cloudflared-process.ts

@@ -0,0 +1,83 @@
+/**
+ * Spawn cloudflared and parse the quick-tunnel public URL from output.
+ * Derived from unjs/untun (MIT), originally forked from node-cloudflared.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import { cloudflaredBinPath } from "./constants";
+
+const urlRegex = /\|\s+(https?:\/\/\S+)/;
+
+export function startCloudflaredTunnel(
+	options: Record<string, string | number | null>,
+): {
+	url: Promise<string>;
+	child: ChildProcess;
+	stop: () => boolean;
+} {
+	const args: string[] = ["tunnel"];
+	for (const [key, value] of Object.entries(options)) {
+		if (typeof value === "string") {
+			args.push(`${key}`, value);
+		} else if (typeof value === "number") {
+			args.push(`${key}`, value.toString());
+		} else if (value === null) {
+			args.push(`${key}`);
+		}
+	}
+	if (args.length === 1) {
+		args.push("--url", "localhost:8080");
+	}
+
+	const child = spawn(cloudflaredBinPath, args, {
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+
+	if (process.env.DEBUG) {
+		child.stdout?.pipe(process.stdout);
+		child.stderr?.pipe(process.stderr);
+	}
+
+	let settled = false;
+	let urlResolver!: (value: string | PromiseLike<string>) => void;
+	let urlRejector!: (reason: unknown) => void;
+	const url = new Promise<string>((resolve, reject) => {
+		urlResolver = (v) => {
+			if (!settled) {
+				settled = true;
+				resolve(v);
+			}
+		};
+		urlRejector = (e) => {
+			if (!settled) {
+				settled = true;
+				reject(e);
+			}
+		};
+	});
+
+	const parser = (data: Buffer) => {
+		const str = data.toString();
+
+		const urlMatch = str.match(urlRegex);
+		if (urlMatch) {
+			urlResolver(urlMatch[1] ?? "");
+		}
+	};
+	child.stdout?.on("data", parser).on("error", urlRejector);
+	child.stderr?.on("data", parser).on("error", urlRejector);
+
+	child.on("exit", (code, signal) => {
+		if (!settled) {
+			urlRejector(
+				new Error(
+					`cloudflared exited before a tunnel URL was parsed (code=${code}, signal=${signal ?? "none"})`,
+				),
+			);
+		}
+	});
+	child.on("error", urlRejector);
+
+	const stop = () => child.kill("SIGINT");
+
+	return { url, child, stop };
+}