buncargo 1.0.29 → 3.2.0

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,
+	};
+}

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

@@ -0,0 +1,67 @@
+import type {
+	DockerComposeServiceRaw,
+	DockerPresetName,
+	ServiceConfig,
+} from "../../types";
+import type { DockerServicePreset } from "./define-docker-service";
+
+export type {
+	DockerServicePreset,
+	DockerServicePresetDefaults,
+	PresetServiceSharedOptions,
+} from "./define-docker-service";
+
+import {
+	type ClickhouseServiceOptions,
+	clickhouseDockerService,
+} from "./clickhouse";
+import { type PostgresServiceOptions, postgresDockerService } from "./postgres";
+import { type RedisServiceOptions, redisDockerService } from "./redis";
+
+const PRESET_SERVICES = {
+	postgres: postgresDockerService,
+	redis: redisDockerService,
+	clickhouse: clickhouseDockerService,
+} satisfies Record<DockerPresetName, DockerServicePreset>;
+
+export { clickhouseDockerService, postgresDockerService, redisDockerService };
+export type {
+	ClickhouseServiceOptions,
+	PostgresServiceOptions,
+	RedisServiceOptions,
+};
+
+export type CustomServiceOptions = ServiceConfig & {
+	docker: DockerComposeServiceRaw;
+};
+
+/**
+ * Public service builders for dev.config.ts.
+ * Core owns this surface so defaults and preset mapping live in one place.
+ */
+export const service = {
+	postgres: postgresDockerService.toServiceConfig,
+	redis: redisDockerService.toServiceConfig,
+	clickhouse: clickhouseDockerService.toServiceConfig,
+
+	custom(options: CustomServiceOptions): ServiceConfig {
+		return options;
+	},
+};
+
+export function inferDockerPreset(
+	serviceKey: string,
+): DockerPresetName | undefined {
+	const normalized = serviceKey.toLowerCase();
+	if (Object.hasOwn(PRESET_SERVICES, normalized)) {
+		return normalized as DockerPresetName;
+	}
+	return undefined;
+}
+
+export function buildPresetDockerService(
+	preset: DockerPresetName,
+	input: Parameters<DockerServicePreset["build"]>[0],
+): ReturnType<DockerServicePreset["build"]> {
+	return PRESET_SERVICES[preset].build(input);
+}

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

@@ -0,0 +1,60 @@
+import type {
+	BuiltInHealthCheck,
+	DockerComposeHealthcheckRaw,
+	DockerComposeServiceRaw,
+} from "../../types";
+import { defineDockerService } from "./define-docker-service";
+import { getDefaultPortBindings, resolveHealthcheck } from "./shared";
+
+export type PostgresServiceOptions = {
+	port?: number;
+	expose?: boolean;
+	healthCheck?: BuiltInHealthCheck | false;
+	serviceName?: string;
+	database?: string;
+	user?: string;
+	password?: string;
+	docker?: DockerComposeServiceRaw;
+};
+
+export const postgresDockerService =
+	defineDockerService<PostgresServiceOptions>({
+		preset: "postgres",
+		defaults: {
+			port: 5432,
+			healthCheck: "pg_isready",
+		},
+		build: ({ serviceKey, config }) => {
+			const user = config.user ?? "postgres";
+			const password = config.password ?? "postgres";
+			const database = config.database ?? "postgres";
+			const defaultHealthcheck: DockerComposeHealthcheckRaw = {
+				test: ["CMD-SHELL", `pg_isready -U ${user}`],
+				interval: "250ms",
+				timeout: "5s",
+				retries: 20,
+			};
+
+			return {
+				service: {
+					image: "pgvector/pgvector:pg16",
+					ports: getDefaultPortBindings(serviceKey, config, "postgres"),
+					volumes: [`${serviceKey}_data:/var/lib/postgresql/data`],
+					environment: {
+						POSTGRES_USER: user,
+						POSTGRES_PASSWORD: password,
+						POSTGRES_DB: database,
+					},
+					healthcheck: resolveHealthcheck(
+						config.healthCheck,
+						defaultHealthcheck,
+						{
+							internalPort: 5432,
+							user,
+						},
+					),
+				},
+				volume: `${serviceKey}_data`,
+			};
+		},
+	});

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

@@ -0,0 +1,48 @@
+import type {
+	BuiltInHealthCheck,
+	DockerComposeHealthcheckRaw,
+	DockerComposeServiceRaw,
+} from "../../types";
+import { defineDockerService } from "./define-docker-service";
+import { getDefaultPortBindings, resolveHealthcheck } from "./shared";
+
+export type RedisServiceOptions = {
+	port?: number;
+	expose?: boolean;
+	healthCheck?: BuiltInHealthCheck | false;
+	serviceName?: string;
+	database?: string;
+	user?: string;
+	password?: string;
+	docker?: DockerComposeServiceRaw;
+};
+
+export const redisDockerService = defineDockerService<RedisServiceOptions>({
+	preset: "redis",
+	defaults: {
+		port: 6379,
+		healthCheck: "redis-cli",
+	},
+	build: ({ serviceKey, config }) => {
+		const defaultHealthcheck: DockerComposeHealthcheckRaw = {
+			test: ["CMD", "redis-cli", "ping"],
+			interval: "250ms",
+			timeout: "5s",
+			retries: 20,
+		};
+
+		return {
+			service: {
+				image: "redis:7-alpine",
+				ports: getDefaultPortBindings(serviceKey, config, "redis"),
+				healthcheck: resolveHealthcheck(
+					config.healthCheck,
+					defaultHealthcheck,
+					{
+						internalPort: 6379,
+					},
+				),
+			},
+		};
+	},
+});

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

@@ -0,0 +1,79 @@
+import type {
+	DockerComposeHealthcheckRaw,
+	DockerPresetName,
+	ServiceConfig,
+} from "../../types";
+
+const DEFAULT_HEALTHCHECK_SETTINGS = {
+	interval: "250ms",
+	timeout: "5s",
+	retries: 20,
+} as const;
+
+export function getPortEnvName(portKey: string): string {
+	return `${portKey.toUpperCase()}_PORT`;
+}
+
+export function getDefaultPortBindings(
+	serviceKey: string,
+	config: ServiceConfig,
+	preset?: DockerPresetName,
+): string[] {
+	const envName = getPortEnvName(serviceKey);
+	const bindings: string[] = [];
+
+	const defaultInternalPort =
+		preset === "postgres"
+			? 5432
+			: preset === "redis"
+				? 6379
+				: preset === "clickhouse"
+					? 8123
+					: config.port;
+
+	bindings.push(`\${${envName}:-${config.port}}:${defaultInternalPort}`);
+
+	if (config.secondaryPort !== undefined) {
+		const secondaryEnv = getPortEnvName(`${serviceKey}Secondary`);
+		const secondaryInternal =
+			preset === "clickhouse" ? 9000 : config.secondaryPort;
+		bindings.push(
+			`\${${secondaryEnv}:-${config.secondaryPort}}:${secondaryInternal}`,
+		);
+	}
+
+	return bindings;
+}
+
+export function resolveHealthcheck(
+	healthCheck: ServiceConfig["healthCheck"] | undefined,
+	fallback: DockerComposeHealthcheckRaw | undefined,
+	options: { internalPort: number; user?: string },
+): DockerComposeHealthcheckRaw | undefined {
+	if (healthCheck === false) return undefined;
+	if (typeof healthCheck === "function") return fallback;
+	if (!healthCheck) return fallback;
+
+	switch (healthCheck) {
+		case "pg_isready":
+			return {
+				test: ["CMD-SHELL", `pg_isready -U ${options.user ?? "postgres"}`],
+				...DEFAULT_HEALTHCHECK_SETTINGS,
+			};
+		case "redis-cli":
+			return {
+				test: ["CMD", "redis-cli", "ping"],
+				...DEFAULT_HEALTHCHECK_SETTINGS,
+			};
+		case "http":
+			return {
+				test: [
+					"CMD-SHELL",
+					`wget -qO- http://127.0.0.1:${options.internalPort}/ping || exit 1`,
+				],
+				...DEFAULT_HEALTHCHECK_SETTINGS,
+			};
+		default:
+			return fallback;
+	}
+}