buncargo 1.0.26 → 3.0.0

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

package/src/docker-compose/yaml.ts

@@ -0,0 +1,88 @@
+import type { DockerComposeNode } from "../types";
+import type { ComposeDocument } from "./model";
+
+function isObject(
+	value: DockerComposeNode,
+): value is Record<string, DockerComposeNode | undefined> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatScalar(value: string | number | boolean | null): string {
+	if (value === null) return "null";
+	if (typeof value === "string") {
+		return JSON.stringify(value);
+	}
+	return String(value);
+}
+
+function formatKey(key: string): string {
+	return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function sortNode(node: DockerComposeNode): DockerComposeNode {
+	if (Array.isArray(node)) {
+		return node.map(sortNode);
+	}
+	if (isObject(node)) {
+		const sorted: Record<string, DockerComposeNode | undefined> = {};
+		for (const key of Object.keys(node).sort()) {
+			const value = node[key];
+			if (value !== undefined) {
+				sorted[key] = sortNode(value);
+			}
+		}
+		return sorted;
+	}
+	return node;
+}
+
+function stringifyNode(node: DockerComposeNode, indent = 0): string {
+	const prefix = " ".repeat(indent);
+
+	if (
+		typeof node === "string" ||
+		typeof node === "number" ||
+		typeof node === "boolean" ||
+		node === null
+	) {
+		return `${prefix}${formatScalar(node)}`;
+	}
+
+	if (Array.isArray(node)) {
+		if (node.length === 0) return `${prefix}[]`;
+		return node
+			.map((item) => {
+				const isNested = typeof item === "object" && item !== null;
+				if (!isNested) {
+					return `${prefix}- ${formatScalar(
+						item as string | number | boolean | null,
+					)}`;
+				}
+				return `${prefix}-\n${stringifyNode(item, indent + 2)}`;
+			})
+			.join("\n");
+	}
+
+	const entries = Object.entries(node).filter(
+		([, value]) => value !== undefined,
+	) as Array<[string, DockerComposeNode]>;
+	if (entries.length === 0) return `${prefix}{}`;
+
+	return entries
+		.map(([key, value]) => {
+			const formattedKey = formatKey(key);
+			const isNested = typeof value === "object" && value !== null;
+			if (!isNested) {
+				return `${prefix}${formattedKey}: ${formatScalar(
+					value as string | number | boolean | null,
+				)}`;
+			}
+			return `${prefix}${formattedKey}:\n${stringifyNode(value, indent + 2)}`;
+		})
+		.join("\n");
+}
+
+export function composeToYaml(document: ComposeDocument): string {
+	const sorted = sortNode(document as DockerComposeNode);
+	return `${stringifyNode(sorted)}\n`;
+}