buncargo 1.0.26 → 3.0.0

package/{environment.ts → src/environment/create-dev-environment.ts}

@@ -1,37 +1,38 @@
-import pc from "picocolors";
-import { assertValidConfig } from "./config";
+import { assertValidConfig } from "../config";
+import { getLocalIp, waitForDevServers, waitForServer } from "../core/network";
 import {
-	areContainersRunning,
-	startContainers,
-	stopContainers,
-	waitForAllServices,
-} from "./core/docker";
-import { getLocalIp, waitForDevServers, waitForServer } from "./core/network";
-import {
-	calculatePortOffset,
+	computeDevIdentity,
 	computePorts,
 	computeUrls,
 	findMonorepoRoot,
-	getProjectName,
-	isWorktree,
-} from "./core/ports";
+} from "../core/ports";
 import {
 	buildApps,
 	execAsync,
 	startDevServers,
 	stopProcess as stopProcessFn,
-} from "./core/process";
-import { isCI as isCIEnv, logExpoApiUrl, logFrontendPort } from "./core/utils";
+} from "../core/process";
+import { isCI as isCIEnv, logExpoApiUrl, logFrontendPort } from "../core/utils";
 import {
 	spawnWatchdog as spawnWatchdogFn,
 	startHeartbeat as startHeartbeatFn,
 	stopHeartbeat as stopHeartbeatFn,
 	stopWatchdog as stopWatchdogFn,
-} from "./core/watchdog";
-import { createPrismaRunner } from "./prisma";
+} from "../core/watchdog";
+import {
+	areContainersRunning,
+	startContainers,
+	stopContainers,
+} from "../docker/runtime";
+import {
+	getGeneratedComposePath,
+	writeGeneratedComposeFile,
+} from "../docker-compose";
+import { createPrismaRunner } from "../prisma";
 import type {
 	AppConfig,
 	ComputedPorts,
+	ComputedPublicUrls,
 	ComputedUrls,
 	DevConfig,
 	DevEnvironment,
@@ -42,34 +43,9 @@ import type {
 	ServiceConfig,
 	StartOptions,
 	StopOptions,
-} from "./types";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Console Output Formatting (Vite-inspired)
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Format a URL with colored port number (Vite-style).
- */
-function formatUrl(url: string): string {
-	return pc.cyan(
-		url.replace(/:(\d+)(\/?)/, (_, port, slash) => `:${pc.bold(port)}${slash}`),
-	);
-}
-
-/**
- * Format a label with arrow prefix (Vite-style).
- */
-function formatLabel(label: string, value: string, arrow = "➜"): string {
-	return `  ${pc.green(arrow)}  ${pc.bold(label.padEnd(10))} ${value}`;
-}
-
-/**
- * Format a dim label (for secondary info).
- */
-function formatDimLabel(label: string, value: string): string {
-	return `  ${pc.dim("•")}  ${pc.dim(label.padEnd(10))} ${pc.dim(value)}`;
-}
+} from "../types";
+import { logEnvironmentInfo } from "./logging";
+import { createCheckTableHelper, createSeedCheckContext } from "./seeding";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Environment Factory
@@ -107,13 +83,25 @@ export function createDevEnvironment<
 	// Compute environment values
 	const root = findMonorepoRoot();
 	const suffix = options.suffix;
-	const worktree = isWorktree(root);
-	const portOffset = calculatePortOffset(suffix, root);
-	const projectName = getProjectName(config.projectPrefix, suffix, root);
+	const identity = computeDevIdentity({
+		projectPrefix: config.projectPrefix,
+		suffix,
+		root,
+		worktreeIsolation: config.options?.worktreeIsolation,
+	});
+	const { worktree, projectSuffix, portOffset, projectName } = identity;
 	const localIp = getLocalIp();
 
 	const services = config.services;
 	const apps = (config.apps ?? {}) as TApps;
+	const composeFile = getGeneratedComposePath(
+		root,
+		config.docker,
+	).composeFileArg;
+
+	function ensureComposeFile(): string {
+		return writeGeneratedComposeFile(root, services, config.docker);
+	}
 
 	// Compute ports and URLs
 	const ports = computePorts(services, apps, portOffset) as ComputedPorts<
@@ -124,6 +112,22 @@ export function createDevEnvironment<
 		TServices,
 		TApps
 	>;
+	const publicUrls: Record<string, string> = {};
+
+	function setPublicUrls(urlsInput: Record<string, string>): void {
+		for (const key of Object.keys(publicUrls)) {
+			delete publicUrls[key];
+		}
+		for (const [key, value] of Object.entries(urlsInput)) {
+			publicUrls[key] = value;
+		}
+	}
+
+	function clearPublicUrls(): void {
+		for (const key of Object.keys(publicUrls)) {
+			delete publicUrls[key];
+		}
+	}
 
 	// Build environment variables
 	function buildEnvVars(production = false): Record<string, string> {
@@ -144,12 +148,19 @@ export function createDevEnvironment<
 			baseEnv[envName] = url;
 		}
 
+		// Add public URL environment variables when tunnels are active
+		for (const [name, url] of Object.entries(publicUrls)) {
+			const envName = `${name.toUpperCase()}_PUBLIC_URL`;
+			baseEnv[envName] = url;
+		}
+
 		// Call user's envVars function if provided
 		if (config.envVars) {
 			const userEnv = config.envVars(ports, urls, {
 				projectName,
 				localIp,
 				portOffset,
+				publicUrls: publicUrls as ComputedPublicUrls<TServices, TApps>,
 			});
 			for (const [key, value] of Object.entries(userEnv)) {
 				baseEnv[key] = String(value);
@@ -168,6 +179,7 @@ export function createDevEnvironment<
 				projectName,
 				ports,
 				urls,
+				publicUrls: publicUrls as ComputedPublicUrls<TServices, TApps>,
 				root,
 				isCI: isCIEnv(),
 				portOffset,
@@ -204,6 +216,7 @@ export function createDevEnvironment<
 		} = startOptions;
 
 		const envVars = buildEnvVars(productionBuild);
+		ensureComposeFile();
 
 		// Log environment info
 		if (verbose) {
@@ -223,16 +236,7 @@ export function createDevEnvironment<
 			startContainers(root, projectName, envVars, {
 				verbose,
 				wait,
-				composeFile: config.options?.composeFile,
-			});
-		}
-
-		// Wait for services to be healthy
-		if (wait) {
-			await waitForAllServices(services, ports, {
-				verbose,
-				projectName,
-				root,
+				composeFile,
 			});
 		}
 
@@ -266,19 +270,19 @@ export function createDevEnvironment<
 				}),
 			);
 
-		// Check for failures
-		for (const { name, result } of migrationResults) {
-			if (result.exitCode !== 0) {
-				console.error(`❌ Migration "${name}" failed`);
-				if (result.stdout) {
-					console.error(result.stdout);
-				}
-				if (result.stderr) {
-					console.error(result.stderr);
+			// Check for failures
+			for (const { name, result } of migrationResults) {
+				if (result.exitCode !== 0) {
+					console.error(`❌ Migration "${name}" failed`);
+					if (result.stdout) {
+						console.error(result.stdout);
+					}
+					if (result.stderr) {
+						console.error(result.stderr);
+					}
+					throw new Error(`Migration "${name}" failed`);
 				}
-				throw new Error(`Migration "${name}" failed`);
 			}
-		}
 
 			if (verbose) console.log("✓ Migrations complete");
 		}
@@ -294,35 +298,14 @@ export function createDevEnvironment<
 
 			// Check if seeding is needed using check function
 			if (config.seed.check) {
-				// Create checkTable helper function with typed service parameter
-				const checkTable = async (
-					tableName: string,
-					service?: keyof TServices,
-				): Promise<boolean> => {
-					const serviceName = (service ?? "postgres") as string;
-					const serviceUrl = (urls as Record<string, string>)[serviceName];
-					if (!serviceUrl) {
-						console.warn(`⚠️ Service "${serviceName}" not found for checkTable`);
-						return true; // Default to seeding if service not found
-					}
-				const checkResult = await exec(
-					`psql "${serviceUrl}" -tAc 'SELECT COUNT(*) FROM "${tableName}" LIMIT 1'`,
-					{ throwOnError: false },
+				const checkTable = createCheckTableHelper<TServices, TApps>(
+					urls as Record<string, string>,
+					exec,
 				);
-				const count = checkResult.stdout.trim();
-				const shouldSeed = checkResult.exitCode !== 0 || count === "0" || count === "";
-				if (!shouldSeed) {
-					console.log(`  📊 Table "${tableName}" has ${count} rows`);
-				}
-				return shouldSeed;
-				};
-
-				// Build seed check context with helpers
-				const seedCheckContext = {
-					...getHookContext(),
+				const seedCheckContext = createSeedCheckContext(
+					getHookContext(),
 					checkTable,
-				};
-
+				);
 				shouldSeed = await config.seed.check(seedCheckContext);
 			}
 
@@ -388,6 +371,7 @@ export function createDevEnvironment<
 
 	async function stop(stopOptions: StopOptions = {}): Promise<void> {
 		const { verbose = true, removeVolumes = false } = stopOptions;
+		ensureComposeFile();
 
 		// Run beforeStop hook
 		if (config.hooks?.beforeStop) {
@@ -397,7 +381,7 @@ export function createDevEnvironment<
 		stopContainers(root, projectName, {
 			verbose,
 			removeVolumes,
-			composeFile: config.options?.composeFile,
+			composeFile,
 		});
 	}
 
@@ -446,54 +430,17 @@ export function createDevEnvironment<
 	// ─────────────────────────────────────────────────────────────────────────
 
 	function logInfo(label = "Docker Dev"): void {
-		const serviceNames = Object.keys(services);
-		const appNames = Object.keys(apps);
-
-		console.log("");
-		console.log(`  ${pc.cyan(pc.bold(`🐳 ${label}`))}`);
-		console.log(formatLabel("Project:", pc.white(projectName)));
-
-		// Services section (Docker containers)
-		if (serviceNames.length > 0) {
-			console.log("");
-			console.log(`  ${pc.dim("─── Services ───")}`);
-			for (const name of serviceNames) {
-				const port = (ports as Record<string, number>)[name];
-				const url = `localhost:${port}`;
-				console.log(formatLabel(`${name}:`, formatUrl(`http://${url}`)));
-			}
-		}
-
-		// Apps section (Dev servers)
-		if (appNames.length > 0) {
-			console.log("");
-			console.log(`  ${pc.dim("─── Applications ───")}`);
-			for (const name of appNames) {
-				const port = (ports as Record<string, number>)[name];
-				const localUrl = `http://localhost:${port}`;
-				const networkUrl = `http://${localIp}:${port}`;
-
-				console.log(`  ${pc.green("➜")}  ${pc.bold(pc.cyan(name))}`);
-				console.log(`       ${pc.dim("Local:")}   ${formatUrl(localUrl)}`);
-				console.log(`       ${pc.dim("Network:")} ${formatUrl(networkUrl)}`);
-			}
-		}
-
-		// Environment info
-		console.log("");
-		console.log(`  ${pc.dim("─── Environment ───")}`);
-		console.log(formatDimLabel("Worktree:", worktree ? "yes" : "no"));
-		console.log(
-			formatDimLabel(
-				"Port offset:",
-				portOffset > 0 ? `+${portOffset}` : "none",
-			),
-		);
-		if (suffix) {
-			console.log(formatDimLabel("Suffix:", suffix));
-		}
-		console.log(formatDimLabel("Local IP:", localIp));
-		console.log("");
+		logEnvironmentInfo({
+			label,
+			projectName,
+			services,
+			apps,
+			ports: ports as Record<string, number>,
+			localIp,
+			worktree,
+			portOffset,
+			projectSuffix,
+		});
 	}
 
 	async function waitForServerUrl(
@@ -519,7 +466,7 @@ export function createDevEnvironment<
 		await spawnWatchdogFn(projectName, root, {
 			timeoutMinutes,
 			verbose: true,
-			composeFile: config.options?.composeFile,
+			composeFile,
 		});
 	}
 
@@ -562,11 +509,14 @@ export function createDevEnvironment<
 		projectName,
 		ports,
 		urls,
+		publicUrls: publicUrls as ComputedPublicUrls<TServices, TApps>,
+		services,
 		apps,
 		portOffset,
 		isWorktree: worktree,
 		localIp,
 		root,
+		composeFile,
 
 		// Container management
 		start,
@@ -581,6 +531,11 @@ export function createDevEnvironment<
 
 		// Utilities
 		buildEnvVars,
+		setPublicUrls: (urlsInput) => {
+			setPublicUrls(urlsInput as Record<string, string>);
+		},
+		clearPublicUrls,
+		ensureComposeFile,
 		exec,
 		waitForServer: waitForServerUrl,
 		logInfo,

package/src/environment/index.ts

@@ -0,0 +1 @@
+export { createDevEnvironment } from "./create-dev-environment";

package/src/environment/logging.ts

@@ -0,0 +1,101 @@
+import pc from "picocolors";
+
+function formatUrl(url: string): string {
+	return pc.cyan(
+		url.replace(/:(\d+)(\/?)/, (_, port, slash) => `:${pc.bold(port)}${slash}`),
+	);
+}
+
+function formatLabel(label: string, value: string, arrow = "➜"): string {
+	return `  ${pc.green(arrow)}  ${pc.bold(label.padEnd(10))} ${value}`;
+}
+
+function formatDimLabel(label: string, value: string): string {
+	return `  ${pc.dim("•")}  ${pc.dim(label.padEnd(10))} ${pc.dim(value)}`;
+}
+
+export function logEnvironmentInfo(input: {
+	label: string;
+	projectName: string;
+	services: Record<string, unknown>;
+	apps: Record<string, unknown>;
+	ports: Record<string, number>;
+	localIp: string;
+	worktree: boolean;
+	portOffset: number;
+	projectSuffix?: string;
+}): void {
+	const {
+		label,
+		projectName,
+		services,
+		apps,
+		ports,
+		localIp,
+		worktree,
+		portOffset,
+		projectSuffix,
+	} = input;
+	const serviceNames = Object.keys(services);
+	const appNames = Object.keys(apps);
+
+	console.log("");
+	console.log(`  ${pc.cyan(pc.bold(`🐳 ${label}`))}`);
+	console.log(formatLabel("Project:", pc.white(projectName)));
+
+	if (serviceNames.length > 0) {
+		console.log("");
+		console.log(`  ${pc.dim("─── Services ───")}`);
+		for (const name of serviceNames) {
+			const port = ports[name];
+			const url = `localhost:${port}`;
+			console.log(formatLabel(`${name}:`, formatUrl(`http://${url}`)));
+		}
+	}
+
+	if (appNames.length > 0) {
+		console.log("");
+		console.log(`  ${pc.dim("─── Applications ───")}`);
+		for (const name of appNames) {
+			const port = ports[name];
+			const localUrl = `http://localhost:${port}`;
+			const networkUrl = `http://${localIp}:${port}`;
+
+			console.log(`  ${pc.green("➜")}  ${pc.bold(pc.cyan(name))}`);
+			console.log(`       ${pc.dim("Local:")}   ${formatUrl(localUrl)}`);
+			console.log(`       ${pc.dim("Network:")} ${formatUrl(networkUrl)}`);
+		}
+	}
+
+	console.log("");
+	console.log(`  ${pc.dim("─── Environment ───")}`);
+	console.log(formatDimLabel("Worktree:", worktree ? "yes" : "no"));
+	console.log(
+		formatDimLabel("Port offset:", portOffset > 0 ? `+${portOffset}` : "none"),
+	);
+	if (projectSuffix) {
+		console.log(formatDimLabel("Suffix:", projectSuffix));
+	}
+	console.log(formatDimLabel("Local IP:", localIp));
+	console.log("");
+}
+
+export function logPublicUrls(
+	tunnels: Array<{
+		kind: "service" | "app";
+		name: string;
+		publicUrl: string;
+		localUrl: string;
+	}>,
+): void {
+	if (tunnels.length === 0) return;
+
+	console.log("");
+	console.log(`  ${pc.dim("─── Public URLs (Quick Tunnel) ───")}`);
+	for (const tunnel of tunnels) {
+		const label = `${tunnel.name} (${tunnel.kind})`;
+		console.log(formatLabel(`${label}:`, formatUrl(tunnel.publicUrl), "🌐"));
+		console.log(formatDimLabel("Local target:", tunnel.localUrl));
+	}
+	console.log("");
+}

package/src/environment/seeding.ts

@@ -0,0 +1,57 @@
+import type {
+	AppConfig,
+	HookContext,
+	SeedCheckContext,
+	ServiceConfig,
+} from "../types";
+
+export function createCheckTableHelper<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	urls: Record<string, string>,
+	exec: (
+		cmd: string,
+		options?: { throwOnError?: boolean },
+	) => Promise<{
+		exitCode: number;
+		stdout: string;
+		stderr: string;
+	}>,
+): SeedCheckContext<TServices, TApps>["checkTable"] {
+	return async (
+		tableName: string,
+		service?: keyof TServices,
+	): Promise<boolean> => {
+		const serviceName = (service ?? "postgres") as string;
+		const serviceUrl = urls[serviceName];
+		if (!serviceUrl) {
+			console.warn(`⚠️ Service "${serviceName}" not found for checkTable`);
+			return true;
+		}
+		const checkResult = await exec(
+			`psql "${serviceUrl}" -tAc 'SELECT COUNT(*) FROM "${tableName}" LIMIT 1'`,
+			{ throwOnError: false },
+		);
+		const count = checkResult.stdout.trim();
+		const shouldSeed =
+			checkResult.exitCode !== 0 || count === "0" || count === "";
+		if (!shouldSeed) {
+			console.log(`  📊 Table "${tableName}" has ${count} rows`);
+		}
+		return shouldSeed;
+	};
+}
+
+export function createSeedCheckContext<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	baseContext: HookContext<TServices, TApps>,
+	checkTable: SeedCheckContext<TServices, TApps>["checkTable"],
+): SeedCheckContext<TServices, TApps> {
+	return {
+		...baseContext,
+		checkTable,
+	};
+}

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

@@ -3,25 +3,33 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 // CLI runner
-export { getFlagValue, hasFlag, runCli } from "./cli";
+export { getFlagValue, hasFlag, runCli } from "./cli/run-cli";
 // Config factory
 export {
 	assertValidConfig,
 	defineDevConfig,
 	mergeConfigs,
 	validateConfig,
-} from "./config";
+} from "./config/index";
+export type {
+	ClickhouseServiceOptions,
+	CustomServiceOptions,
+	PostgresServiceOptions,
+	RedisServiceOptions,
+} from "./docker-compose/services";
+// Service helpers
+export { service } from "./docker-compose/services";
 // Environment factory
-export { createDevEnvironment } from "./environment";
+export { createDevEnvironment } from "./environment/index";
+// Config loader (for programmatic access)
+export { clearDevEnvCache, getDevEnv, loadDevEnv } from "./loader/index";
 // Lint / Typecheck
 export {
 	runWorkspaceTypecheck,
 	type TypecheckResult,
 	type WorkspaceTypecheckOptions,
 	type WorkspaceTypecheckResult,
-} from "./lint";
-// Config loader (for programmatic access)
-export { clearDevEnvCache, getDevEnv, loadDevEnv } from "./loader";
+} from "./typecheck/index";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -34,6 +42,7 @@ export type {
 	CliOptions,
 	// Computed types
 	ComputedPorts,
+	ComputedPublicUrls,
 	ComputedUrls,
 	// Main config
 	DevConfig,
@@ -42,6 +51,14 @@ export type {
 	DevHooks,
 	DevOptions,
 	DevServerPids,
+	DockerComposeGenerationOptions,
+	DockerComposeHealthcheckRaw,
+	DockerComposeNode,
+	DockerComposeServiceRaw,
+	DockerComposeVolumeRaw,
+	DockerPresetName,
+	DockerPresetServiceDefinition,
+	DockerServiceDefinition,
 	EnvVarsBuilder,
 	ExecOptions,
 	HealthCheckFn,
@@ -61,28 +78,22 @@ export type {
 	StopOptions,
 	UrlBuilderContext,
 	UrlBuilderFn,
-} from "./types";
+} from "./types/index";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Core Utilities (for advanced use cases)
 // ═══════════════════════════════════════════════════════════════════════════
 
-export {
-	areContainersRunning,
-	isContainerRunning,
-	MAX_ATTEMPTS,
-	POLL_INTERVAL,
-} from "./core/docker";
-
 export { getLocalIp, isPortAvailable, waitForServer } from "./core/network";
 export {
 	calculatePortOffset,
+	computeDevIdentity,
 	findMonorepoRoot,
 	getProjectName,
 	getWorktreeName,
+	getWorktreeProjectSuffix,
 	isWorktree,
 } from "./core/ports";
-
 export {
 	getProcessOnPort,
 	isPortInUse,
@@ -91,6 +102,13 @@ export {
 	killProcessOnPort,
 	killProcessOnPortAndWait,
 } from "./core/process";
+export {
+	type PublicExposeTarget,
+	type PublicTunnel,
+	resolveExposeTargets,
+	startPublicTunnels,
+	stopPublicTunnels,
+} from "./core/tunnel";
 export {
 	getEnvVar,
 	isCI,
@@ -108,3 +126,19 @@ export {
 	stopHeartbeat,
 	stopWatchdog,
 } from "./core/watchdog";
+export {
+	areContainersRunning,
+	assertDockerRunning,
+	DOCKER_NOT_RUNNING_MESSAGE,
+	isContainerRunning,
+	isDockerRunning,
+	MAX_ATTEMPTS,
+	POLL_INTERVAL,
+} from "./docker/index";
+export {
+	buildComposeModel,
+	composeToYaml,
+	DEFAULT_GENERATED_COMPOSE_FILE,
+	getGeneratedComposePath,
+	writeGeneratedComposeFile,
+} from "./docker-compose/index";

package/src/loader/cache.ts

@@ -0,0 +1,23 @@
+import type { AppConfig, DevEnvironment, ServiceConfig } from "../types";
+
+let cachedEnv: DevEnvironment<
+	Record<string, ServiceConfig>,
+	Record<string, AppConfig>
+> | null = null;
+
+export function setCachedDevEnv(
+	env: DevEnvironment<Record<string, ServiceConfig>, Record<string, AppConfig>>,
+): void {
+	cachedEnv = env;
+}
+
+export function getCachedDevEnv(): DevEnvironment<
+	Record<string, ServiceConfig>,
+	Record<string, AppConfig>
+> | null {
+	return cachedEnv;
+}
+
+export function clearDevEnvCache(): void {
+	cachedEnv = null;
+}