buncargo 1.0.29 → 3.0.0

package/src/core/tunnel.ts

@@ -0,0 +1,151 @@
+import { startTunnel } from "untun";
+import type { AppConfig, DevEnvironment, ServiceConfig } from "../types";
+
+export interface PublicExposeTarget {
+	kind: "service" | "app";
+	name: string;
+	port: number;
+}
+
+export interface PublicTunnel {
+	kind: "service" | "app";
+	name: string;
+	localUrl: string;
+	publicUrl: string;
+	close: () => Promise<void>;
+}
+
+interface UntunTunnelLike {
+	url?: string;
+	publicUrl?: string;
+	tunnelUrl?: string;
+	close?: () => void | Promise<void>;
+	stop?: () => void | Promise<void>;
+	destroy?: () => void | Promise<void>;
+}
+
+function parseExposeNames(exposeValue?: string): Set<string> | null {
+	if (exposeValue === undefined) return null;
+	const names = exposeValue
+		.split(",")
+		.map((name) => name.trim())
+		.filter(Boolean);
+	return new Set(names);
+}
+
+function asPublicUrl(tunnel: UntunTunnelLike): string | null {
+	return tunnel.url ?? tunnel.publicUrl ?? tunnel.tunnelUrl ?? null;
+}
+
+function toCloseFn(tunnel: UntunTunnelLike): () => Promise<void> {
+	const close = tunnel.close ?? tunnel.stop ?? tunnel.destroy;
+	if (!close) return async () => {};
+	return async () => {
+		await close();
+	};
+}
+
+export function resolveExposeTargets<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	env: DevEnvironment<TServices, TApps>,
+	exposeValue?: string,
+): {
+	targets: PublicExposeTarget[];
+	unknownNames: string[];
+	notEnabledNames: string[];
+} {
+	const requestedNames = parseExposeNames(exposeValue);
+	const knownTargets = new Map<string, PublicExposeTarget>();
+	const enabledTargets = new Map<string, PublicExposeTarget>();
+
+	for (const [name, config] of Object.entries(env.services)) {
+		const port = env.ports[name];
+		if (port === undefined) continue;
+		const target: PublicExposeTarget = { kind: "service", name, port };
+		knownTargets.set(name, target);
+		if (config.expose === true) {
+			enabledTargets.set(name, target);
+		}
+	}
+
+	for (const [name, config] of Object.entries(env.apps)) {
+		const port = env.ports[name];
+		if (port === undefined) continue;
+		const target: PublicExposeTarget = { kind: "app", name, port };
+		knownTargets.set(name, target);
+		if (config.expose === true) {
+			enabledTargets.set(name, target);
+		}
+	}
+
+	if (requestedNames === null) {
+		return {
+			targets: Array.from(enabledTargets.values()),
+			unknownNames: [],
+			notEnabledNames: [],
+		};
+	}
+
+	const unknownNames: string[] = [];
+	const notEnabledNames: string[] = [];
+	const targets: PublicExposeTarget[] = [];
+
+	for (const name of requestedNames) {
+		if (!knownTargets.has(name)) {
+			unknownNames.push(name);
+			continue;
+		}
+		const enabledTarget = enabledTargets.get(name);
+		if (!enabledTarget) {
+			notEnabledNames.push(name);
+			continue;
+		}
+		targets.push(enabledTarget);
+	}
+
+	return { targets, unknownNames, notEnabledNames };
+}
+
+export async function startPublicTunnels(
+	targets: PublicExposeTarget[],
+	options: {
+		start?: (input: { url: string }) => Promise<UntunTunnelLike>;
+	} = {},
+): Promise<PublicTunnel[]> {
+	const start = options.start ?? ((input) => startTunnel(input));
+	const tunnels: PublicTunnel[] = [];
+
+	try {
+		for (const target of targets) {
+			const localUrl = `http://localhost:${target.port}`;
+			const tunnel = (await start({
+				url: localUrl,
+			})) as UntunTunnelLike;
+			const publicUrl = asPublicUrl(tunnel);
+			if (!publicUrl) {
+				throw new Error(
+					`Tunnel for "${target.name}" did not provide a public URL`,
+				);
+			}
+			tunnels.push({
+				kind: target.kind,
+				name: target.name,
+				localUrl,
+				publicUrl,
+				close: toCloseFn(tunnel),
+			});
+		}
+		return tunnels;
+	} catch (error) {
+		await stopPublicTunnels(tunnels);
+		throw error;
+	}
+}
+
+export async function stopPublicTunnels(
+	tunnels: PublicTunnel[],
+): Promise<void> {
+	await Promise.allSettled(tunnels.map((tunnel) => tunnel.close()));
+}

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

@@ -93,6 +93,7 @@ export function getEnvVar<
 			projectName: config.projectPrefix,
 			localIp,
 			portOffset: offset,
+			publicUrls: {},
 		},
 	);
 

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

@@ -120,6 +120,10 @@ export function getWatchdogPid(projectName: string): number | null {
  * Spawn watchdog as a detached process.
  * The watchdog monitors the heartbeat file and shuts down containers after idle timeout.
  */
+export function getWatchdogComposeArg(composeFile?: string): string {
+	return composeFile ? `-f "${composeFile}"` : "";
+}
+
 export async function spawnWatchdog(
 	projectName: string,
 	root: string,
@@ -162,7 +166,7 @@ export async function spawnWatchdog(
 			WATCHDOG_HEARTBEAT_FILE: getHeartbeatFile(projectName),
 			WATCHDOG_PID_FILE: pidFile,
 			WATCHDOG_TIMEOUT_MS: String(timeoutMinutes * 60 * 1000),
-			WATCHDOG_COMPOSE_ARG: composeFile ? `-f ${composeFile}` : "",
+			WATCHDOG_COMPOSE_ARG: getWatchdogComposeArg(composeFile),
 		},
 	});
 

package/src/docker/index.ts

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

package/{core/docker.ts → src/docker/runtime.ts}

@@ -1,10 +1,10 @@
 import { execSync } from "node:child_process";
+import { sleep } from "../core/utils";
 import type {
 	BuiltInHealthCheck,
 	HealthCheckFn,
 	ServiceConfig,
 } from "../types";
-import { sleep } from "./utils";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
@@ -91,6 +91,13 @@ export interface StartContainersOptions {
 	composeFile?: string;
 }
 
+/**
+ * Build `-f` argument for docker compose.
+ */
+export function getComposeArg(composeFile?: string): string {
+	return composeFile ? `-f "${composeFile}"` : "";
+}
+
 /**
  * Start Docker Compose containers.
  */
@@ -105,7 +112,7 @@ export function startContainers(
 
 	if (verbose) console.log("🐳 Starting Docker containers...");
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const waitFlag = wait ? "--wait" : "";
 	const cmd = `docker compose ${composeArg} up -d ${waitFlag}`.trim();
 
@@ -143,7 +150,7 @@ export function stopContainers(
 		);
 	}
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const volumeFlag = removeVolumes ? "-v" : "";
 	const cmd = `docker compose ${composeArg} down ${volumeFlag}`.trim();
 
@@ -171,7 +178,7 @@ export function startService(
 
 	if (verbose) console.log(`🐳 Starting ${serviceName}...`);
 
-	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const composeArg = getComposeArg(composeFile);
 	const cmd = `docker compose ${composeArg} up -d ${serviceName}`.trim();
 
 	execSync(cmd, {

package/src/docker-compose/generated-file.ts

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import type { DockerComposeGenerationOptions, ServiceConfig } from "../types";
+import { buildComposeModel } from "./model";
+import { composeToYaml } from "./yaml";
+
+export const DEFAULT_GENERATED_COMPOSE_FILE =
+	".buncargo/docker-compose.generated.yml";
+
+export function getGeneratedComposePath(
+	root: string,
+	docker?: DockerComposeGenerationOptions,
+): { absolutePath: string; composeFileArg: string } {
+	const generatedFile = docker?.generatedFile ?? DEFAULT_GENERATED_COMPOSE_FILE;
+	const absolutePath = isAbsolute(generatedFile)
+		? generatedFile
+		: resolve(root, generatedFile);
+	const relativePath = relative(root, absolutePath);
+	const composeFileArg =
+		relativePath && !relativePath.startsWith("..")
+			? relativePath
+			: absolutePath;
+	return { absolutePath, composeFileArg };
+}
+
+export function writeGeneratedComposeFile(
+	root: string,
+	services: Record<string, ServiceConfig>,
+	docker?: DockerComposeGenerationOptions,
+): string {
+	const { absolutePath, composeFileArg } = getGeneratedComposePath(
+		root,
+		docker,
+	);
+	const writeStrategy = docker?.writeStrategy ?? "always";
+	const shouldWrite = writeStrategy === "always" || !existsSync(absolutePath);
+	if (shouldWrite) {
+		const composeModel = buildComposeModel(services, docker);
+		const yaml = composeToYaml(composeModel);
+		mkdirSync(dirname(absolutePath), { recursive: true });
+		writeFileSync(absolutePath, yaml, "utf-8");
+	}
+
+	return composeFileArg;
+}

package/src/docker-compose/index.ts

@@ -0,0 +1,7 @@
+export {
+	DEFAULT_GENERATED_COMPOSE_FILE,
+	getGeneratedComposePath,
+	writeGeneratedComposeFile,
+} from "./generated-file";
+export { buildComposeModel } from "./model";
+export { composeToYaml } from "./yaml";

package/src/docker-compose/model.ts

@@ -0,0 +1,197 @@
+import type {
+	DockerComposeGenerationOptions,
+	DockerComposeNode,
+	DockerComposeServiceRaw,
+	DockerComposeVolumeRaw,
+	DockerPresetName,
+	DockerPresetServiceDefinition,
+	DockerServiceDefinition,
+	ServiceConfig,
+} from "../types";
+import { buildPresetDockerService, inferDockerPreset } from "./services";
+import { getDefaultPortBindings } from "./services/shared";
+
+export type ComposeDocument = {
+	services: Record<string, DockerComposeServiceRaw>;
+	volumes?: Record<string, DockerComposeVolumeRaw>;
+};
+
+function isObject(
+	value: DockerComposeNode,
+): value is Record<string, DockerComposeNode | undefined> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function deepMergeNode(
+	base: DockerComposeNode,
+	override: DockerComposeNode,
+): DockerComposeNode {
+	if (Array.isArray(base) || Array.isArray(override)) {
+		return override;
+	}
+	if (!isObject(base) || !isObject(override)) {
+		return override;
+	}
+
+	const merged: Record<string, DockerComposeNode | undefined> = { ...base };
+	for (const key of Object.keys(override)) {
+		const baseValue = merged[key];
+		const overrideValue = override[key];
+		if (baseValue === undefined || overrideValue === undefined) {
+			merged[key] = overrideValue;
+		} else {
+			merged[key] = deepMergeNode(baseValue, overrideValue);
+		}
+	}
+	return merged;
+}
+
+function isPresetDefinition(
+	value: DockerServiceDefinition | undefined,
+): value is DockerPresetServiceDefinition {
+	return Boolean(
+		value &&
+			typeof value === "object" &&
+			"kind" in value &&
+			(value as { kind?: string }).kind === "preset",
+	);
+}
+
+function normalizeRawService(
+	name: string,
+	config: ServiceConfig,
+	service: DockerComposeServiceRaw,
+): DockerComposeServiceRaw {
+	const normalized = { ...service };
+	if (!normalized.ports || normalized.ports.length === 0) {
+		normalized.ports = getDefaultPortBindings(name, config);
+	}
+	if (config.healthCheck === false) {
+		delete normalized.healthcheck;
+	}
+	return normalized;
+}
+
+type NormalizedServiceConfig =
+	| {
+			kind: "preset";
+			serviceName: string;
+			preset: DockerPresetName;
+			serviceOverride?: DockerComposeServiceRaw;
+	  }
+	| {
+			kind: "raw";
+			serviceName: string;
+			service: DockerComposeServiceRaw;
+	  };
+
+function normalizeServiceConfig(
+	name: string,
+	config: ServiceConfig,
+): NormalizedServiceConfig {
+	const serviceName = config.serviceName ?? name;
+	const rawDefinition = config.docker;
+
+	if (isPresetDefinition(rawDefinition)) {
+		return {
+			kind: "preset",
+			serviceName,
+			preset: rawDefinition.preset,
+			serviceOverride: rawDefinition.service,
+		};
+	}
+
+	if (rawDefinition) {
+		const inferredPreset = inferDockerPreset(name);
+		if (inferredPreset) {
+			return {
+				kind: "preset",
+				serviceName,
+				preset: inferredPreset,
+				serviceOverride: rawDefinition,
+			};
+		}
+		return {
+			kind: "raw",
+			serviceName,
+			service: normalizeRawService(name, config, rawDefinition),
+		};
+	}
+
+	const preset = inferDockerPreset(name);
+	if (!preset) {
+		throw new Error(
+			`Service "${name}" has no docker preset and no docker definition. Add service.docker using helper or raw mode.`,
+		);
+	}
+
+	return {
+		kind: "preset",
+		serviceName,
+		preset,
+	};
+}
+
+function resolveServiceDefinition(
+	name: string,
+	config: ServiceConfig,
+): {
+	serviceName: string;
+	service: DockerComposeServiceRaw;
+	volume?: string;
+} {
+	const normalized = normalizeServiceConfig(name, config);
+	if (normalized.kind === "raw") {
+		return {
+			serviceName: normalized.serviceName,
+			service: normalized.service,
+		};
+	}
+
+	const { service, volume } = buildPresetDockerService(normalized.preset, {
+		serviceKey: name,
+		config,
+	});
+	const mergedService = normalized.serviceOverride
+		? (deepMergeNode(
+				service as DockerComposeNode,
+				normalized.serviceOverride as DockerComposeNode,
+			) as DockerComposeServiceRaw)
+		: service;
+	return {
+		serviceName: normalized.serviceName,
+		service: mergedService,
+		volume,
+	};
+}
+
+export function buildComposeModel(
+	services: Record<string, ServiceConfig>,
+	docker?: DockerComposeGenerationOptions,
+): ComposeDocument {
+	const composeServices: Record<string, DockerComposeServiceRaw> = {};
+	const composeVolumes: Record<string, DockerComposeVolumeRaw> = {};
+
+	for (const [name, serviceConfig] of Object.entries(services)) {
+		const { serviceName, service, volume } = resolveServiceDefinition(
+			name,
+			serviceConfig,
+		);
+		composeServices[serviceName] = service;
+		if (volume) {
+			composeVolumes[volume] = {};
+		}
+	}
+
+	for (const [volumeName, volume] of Object.entries(docker?.volumes ?? {})) {
+		composeVolumes[volumeName] = volume;
+	}
+
+	const document: ComposeDocument = {
+		services: composeServices,
+	};
+	if (Object.keys(composeVolumes).length > 0) {
+		document.volumes = composeVolumes;
+	}
+	return document;
+}

package/src/docker-compose/services/clickhouse.ts

@@ -0,0 +1,79 @@
+import type {
+	BuiltInHealthCheck,
+	DockerComposeHealthcheckRaw,
+	DockerComposeServiceRaw,
+	ServiceConfig,
+} from "../../types";
+import { defineDockerService } from "./define-docker-service";
+import { getDefaultPortBindings, resolveHealthcheck } from "./shared";
+
+export type ClickhouseServiceOptions = {
+	port?: number;
+	secondaryPort?: number;
+	expose?: boolean;
+	healthCheck?: BuiltInHealthCheck | false;
+	serviceName?: string;
+	database?: string;
+	user?: string;
+	password?: string;
+	docker?: DockerComposeServiceRaw;
+};
+
+export type ClickhouseServiceConfig = ServiceConfig & {
+	secondaryPort: number;
+};
+
+export const clickhouseDockerService = defineDockerService<
+	ClickhouseServiceOptions,
+	ClickhouseServiceConfig
+>({
+	preset: "clickhouse",
+	defaults: {
+		port: 8123,
+		secondaryPort: 9000,
+		healthCheck: "http",
+	},
+	enhanceServiceConfig: (base, options): ClickhouseServiceConfig => ({
+		...base,
+		secondaryPort: options.secondaryPort ?? 9000,
+	}),
+	build: ({ serviceKey, config }) => {
+		const user = config.user ?? "default";
+		const password = config.password ?? "clickhouse";
+		const database = config.database ?? "default";
+		const defaultHealthcheck: DockerComposeHealthcheckRaw = {
+			test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8123/ping || exit 1"],
+			interval: "250ms",
+			timeout: "5s",
+			retries: 20,
+		};
+
+		return {
+			service: {
+				image: "clickhouse/clickhouse-server:24-alpine",
+				ports: getDefaultPortBindings(serviceKey, config, "clickhouse"),
+				volumes: [`${serviceKey}_data:/var/lib/clickhouse`],
+				environment: {
+					CLICKHOUSE_USER: user,
+					CLICKHOUSE_PASSWORD: password,
+					CLICKHOUSE_DB: database,
+				},
+				ulimits: {
+					nofile: {
+						soft: 262144,
+						hard: 262144,
+					},
+				},
+				healthcheck: resolveHealthcheck(
+					config.healthCheck,
+					defaultHealthcheck,
+					{
+						internalPort: 8123,
+						user,
+					},
+				),
+			},
+			volume: `${serviceKey}_data`,
+		};
+	},
+});

package/src/docker-compose/services/define-docker-service.ts

@@ -0,0 +1,109 @@
+import type {
+	BuiltInHealthCheck,
+	DockerComposeServiceRaw,
+	DockerPresetName,
+	DockerPresetServiceDefinition,
+	ServiceConfig,
+} from "../../types";
+
+export interface DockerServiceFactoryInput {
+	serviceKey: string;
+	config: ServiceConfig;
+}
+
+export interface DockerServiceFactoryOutput {
+	service: DockerComposeServiceRaw;
+	volume?: string;
+}
+
+export type DockerServiceFactory = (
+	input: DockerServiceFactoryInput,
+) => DockerServiceFactoryOutput;
+
+export type PresetServiceSharedOptions = Pick<
+	ServiceConfig,
+	"serviceName" | "database" | "user" | "password" | "expose"
+> & {
+	port?: number;
+	healthCheck?: BuiltInHealthCheck | false;
+	docker?: DockerComposeServiceRaw;
+};
+
+export interface DockerServicePresetDefaults {
+	port: number;
+	healthCheck: BuiltInHealthCheck;
+	secondaryPort?: number;
+}
+
+export interface DockerServicePreset<
+	TOptions extends PresetServiceSharedOptions = PresetServiceSharedOptions,
+	TServiceConfig extends ServiceConfig = ServiceConfig,
+> {
+	preset: DockerPresetName;
+	defaults: DockerServicePresetDefaults;
+	build: DockerServiceFactory;
+	createPresetDefinition(
+		service?: DockerComposeServiceRaw,
+	): DockerPresetServiceDefinition;
+	toServiceConfig(options?: TOptions): TServiceConfig;
+}
+
+interface DefineDockerServiceInput<
+	TOptions extends PresetServiceSharedOptions = PresetServiceSharedOptions,
+	TServiceConfig extends ServiceConfig = ServiceConfig,
+> {
+	preset: DockerPresetName;
+	defaults: DockerServicePresetDefaults;
+	build: DockerServiceFactory;
+	enhanceServiceConfig?: (
+		base: ServiceConfig,
+		options: TOptions,
+	) => TServiceConfig;
+}
+
+/**
+ * Define a docker service preset as single source of truth.
+ * The same definition powers:
+ * - compose generation (`build`)
+ * - typed config helper defaults (`toServiceConfig`)
+ */
+export function defineDockerService<
+	TOptions extends PresetServiceSharedOptions = PresetServiceSharedOptions,
+	TServiceConfig extends ServiceConfig = ServiceConfig,
+>(
+	input: DefineDockerServiceInput<TOptions, TServiceConfig>,
+): DockerServicePreset<TOptions, TServiceConfig> {
+	function createPresetDefinition(
+		service?: DockerComposeServiceRaw,
+	): DockerPresetServiceDefinition {
+		return {
+			kind: "preset",
+			preset: input.preset,
+			service,
+		};
+	}
+
+	function toServiceConfig(options = {} as TOptions): TServiceConfig {
+		const base: ServiceConfig = {
+			port: options.port ?? input.defaults.port,
+			expose: options.expose,
+			healthCheck: options.healthCheck ?? input.defaults.healthCheck,
+			database: options.database,
+			user: options.user,
+			password: options.password,
+			serviceName: options.serviceName,
+			docker: createPresetDefinition(options.docker),
+		};
+		return input.enhanceServiceConfig
+			? input.enhanceServiceConfig(base, options)
+			: (base as TServiceConfig);
+	}
+
+	return {
+		preset: input.preset,
+		defaults: input.defaults,
+		build: input.build,
+		createPresetDefinition,
+		toServiceConfig,
+	};
+}