buncargo 1.0.26 → 3.0.0

package/dist/docker/runtime.d.ts

@@ -0,0 +1,87 @@
+import type { BuiltInHealthCheck, HealthCheckFn, ServiceConfig } from "../types";
+export declare const POLL_INTERVAL = 250;
+export declare const MAX_ATTEMPTS = 120;
+export declare const DOCKER_NOT_RUNNING_MESSAGE = "Docker is not running. Please start Docker and try again.";
+/**
+ * Check if a specific container service is running using docker ps.
+ */
+export declare function isContainerRunning(project: string, service: string): Promise<boolean>;
+/**
+ * Check if Docker daemon is running and reachable.
+ */
+export declare function isDockerRunning(): boolean;
+/**
+ * Ensure Docker is running before attempting compose operations.
+ */
+export declare function assertDockerRunning(): void;
+/**
+ * Check if all expected containers are running.
+ */
+export declare function areContainersRunning(project: string, minCount?: number): Promise<boolean>;
+export interface StartContainersOptions {
+    verbose?: boolean;
+    wait?: boolean;
+    composeFile?: string;
+}
+/**
+ * Build `-f` argument for docker compose.
+ */
+export declare function getComposeArg(composeFile?: string): string;
+/**
+ * Start Docker Compose containers.
+ */
+export declare function startContainers(root: string, projectName: string, envVars: Record<string, string>, options?: StartContainersOptions): void;
+export interface StopContainersOptions {
+    verbose?: boolean;
+    removeVolumes?: boolean;
+    composeFile?: string;
+}
+/**
+ * Stop Docker Compose containers.
+ */
+export declare function stopContainers(root: string, projectName: string, options?: StopContainersOptions): void;
+/**
+ * Start a specific service only.
+ */
+export declare function startService(root: string, projectName: string, serviceName: string, envVars: Record<string, string>, options?: {
+    verbose?: boolean;
+    composeFile?: string;
+}): void;
+export interface HealthCheckContext {
+    projectName?: string;
+    root?: string;
+}
+/**
+ * Create a health check function from a built-in type.
+ */
+export declare function createBuiltInHealthCheck(type: BuiltInHealthCheck, serviceName: string, context?: HealthCheckContext): HealthCheckFn;
+/**
+ * Wait for a service to be healthy.
+ */
+export declare function waitForService(serviceName: string, config: ServiceConfig, port: number, options?: {
+    maxAttempts?: number;
+    pollInterval?: number;
+    projectName?: string;
+    root?: string;
+}): Promise<void>;
+/**
+ * Wait for all services to be healthy.
+ */
+export declare function waitForAllServices(services: Record<string, ServiceConfig>, ports: Record<string, number>, options?: {
+    maxAttempts?: number;
+    pollInterval?: number;
+    verbose?: boolean;
+    projectName?: string;
+    root?: string;
+}): Promise<void>;
+/**
+ * Wait for a service to be healthy using a built-in health check type.
+ * Simpler API when you don't have a ServiceConfig object.
+ */
+export declare function waitForServiceByType(serviceName: string, healthCheckType: BuiltInHealthCheck, port: number, options?: {
+    maxAttempts?: number;
+    pollInterval?: number;
+    verbose?: boolean;
+    projectName?: string;
+    root?: string;
+}): Promise<void>;

package/dist/docker/runtime.js

@@ -0,0 +1,37 @@
+import {
+	areContainersRunning,
+	assertDockerRunning,
+	createBuiltInHealthCheck,
+	DOCKER_NOT_RUNNING_MESSAGE,
+	getComposeArg,
+	isContainerRunning,
+	isDockerRunning,
+	MAX_ATTEMPTS,
+	POLL_INTERVAL,
+	startContainers,
+	startService,
+	stopContainers,
+	waitForAllServices,
+	waitForService,
+	waitForServiceByType,
+} from "../index-tjbx2r2t.js";
+import "../index-4gp0az1g.js";
+import "../index-xkvd0nsd.js";
+import "../index-qnx9j3qa.js";
+export {
+	waitForServiceByType,
+	waitForService,
+	waitForAllServices,
+	stopContainers,
+	startService,
+	startContainers,
+	isDockerRunning,
+	isContainerRunning,
+	getComposeArg,
+	createBuiltInHealthCheck,
+	assertDockerRunning,
+	areContainersRunning,
+	POLL_INTERVAL,
+	MAX_ATTEMPTS,
+	DOCKER_NOT_RUNNING_MESSAGE,
+};

package/dist/docker-compose/compose.d.ts

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

package/dist/docker-compose/generated-file.d.ts

@@ -0,0 +1,7 @@
+import type { DockerComposeGenerationOptions, ServiceConfig } from "../types";
+export declare const DEFAULT_GENERATED_COMPOSE_FILE = ".buncargo/docker-compose.generated.yml";
+export declare function getGeneratedComposePath(root: string, docker?: DockerComposeGenerationOptions): {
+    absolutePath: string;
+    composeFileArg: string;
+};
+export declare function writeGeneratedComposeFile(root: string, services: Record<string, ServiceConfig>, docker?: DockerComposeGenerationOptions): string;

package/dist/docker-compose/index.d.ts

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

package/dist/docker-compose/index.js

@@ -0,0 +1,15 @@
+import {
+  DEFAULT_GENERATED_COMPOSE_FILE,
+  buildComposeModel,
+  composeToYaml,
+  getGeneratedComposePath,
+  writeGeneratedComposeFile
+} from "../index-5t9jxqm0.js";
+import"../index-qnx9j3qa.js";
+export {
+  writeGeneratedComposeFile,
+  getGeneratedComposePath,
+  composeToYaml,
+  buildComposeModel,
+  DEFAULT_GENERATED_COMPOSE_FILE
+};

package/dist/docker-compose/model.d.ts

@@ -0,0 +1,6 @@
+import type { DockerComposeGenerationOptions, DockerComposeServiceRaw, DockerComposeVolumeRaw, ServiceConfig } from "../types";
+export type ComposeDocument = {
+    services: Record<string, DockerComposeServiceRaw>;
+    volumes?: Record<string, DockerComposeVolumeRaw>;
+};
+export declare function buildComposeModel(services: Record<string, ServiceConfig>, docker?: DockerComposeGenerationOptions): ComposeDocument;

package/dist/docker-compose/services/clickhouse.d.ts

@@ -0,0 +1,16 @@
+import type { BuiltInHealthCheck, DockerComposeServiceRaw, ServiceConfig } from "../../types";
+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 declare const clickhouseDockerService: import("./define-docker-service").DockerServicePreset<ClickhouseServiceOptions, ClickhouseServiceConfig>;

package/dist/docker-compose/services/define-docker-service.d.ts

@@ -0,0 +1,41 @@
+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 declare function defineDockerService<TOptions extends PresetServiceSharedOptions = PresetServiceSharedOptions, TServiceConfig extends ServiceConfig = ServiceConfig>(input: DefineDockerServiceInput<TOptions, TServiceConfig>): DockerServicePreset<TOptions, TServiceConfig>;
+export {};

package/dist/docker-compose/services/index.d.ts

@@ -0,0 +1,23 @@
+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";
+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 declare const service: {
+    postgres: (options?: PostgresServiceOptions | undefined) => ServiceConfig;
+    redis: (options?: RedisServiceOptions | undefined) => ServiceConfig;
+    clickhouse: (options?: ClickhouseServiceOptions | undefined) => import("./clickhouse").ClickhouseServiceConfig;
+    custom(options: CustomServiceOptions): ServiceConfig;
+};
+export declare function inferDockerPreset(serviceKey: string): DockerPresetName | undefined;
+export declare function buildPresetDockerService(preset: DockerPresetName, input: Parameters<DockerServicePreset["build"]>[0]): ReturnType<DockerServicePreset["build"]>;

package/dist/docker-compose/services/index.js

@@ -0,0 +1,17 @@
+import {
+	buildPresetDockerService,
+	clickhouseDockerService,
+	inferDockerPreset,
+	postgresDockerService,
+	redisDockerService,
+	service,
+} from "../../index-w8zxnjka.js";
+import "../../index-qnx9j3qa.js";
+export {
+	service,
+	redisDockerService,
+	postgresDockerService,
+	inferDockerPreset,
+	clickhouseDockerService,
+	buildPresetDockerService,
+};

package/dist/docker-compose/services/postgres.d.ts

@@ -0,0 +1,12 @@
+import type { BuiltInHealthCheck, DockerComposeServiceRaw } from "../../types";
+export type PostgresServiceOptions = {
+    port?: number;
+    expose?: boolean;
+    healthCheck?: BuiltInHealthCheck | false;
+    serviceName?: string;
+    database?: string;
+    user?: string;
+    password?: string;
+    docker?: DockerComposeServiceRaw;
+};
+export declare const postgresDockerService: import("./define-docker-service").DockerServicePreset<PostgresServiceOptions, import("../..").ServiceConfig>;

package/dist/docker-compose/services/redis.d.ts

@@ -0,0 +1,12 @@
+import type { BuiltInHealthCheck, DockerComposeServiceRaw } from "../../types";
+export type RedisServiceOptions = {
+    port?: number;
+    expose?: boolean;
+    healthCheck?: BuiltInHealthCheck | false;
+    serviceName?: string;
+    database?: string;
+    user?: string;
+    password?: string;
+    docker?: DockerComposeServiceRaw;
+};
+export declare const redisDockerService: import("./define-docker-service").DockerServicePreset<RedisServiceOptions, import("../..").ServiceConfig>;

package/dist/docker-compose/services/shared.d.ts

@@ -0,0 +1,7 @@
+import type { DockerComposeHealthcheckRaw, DockerPresetName, ServiceConfig } from "../../types";
+export declare function getPortEnvName(portKey: string): string;
+export declare function getDefaultPortBindings(serviceKey: string, config: ServiceConfig, preset?: DockerPresetName): string[];
+export declare function resolveHealthcheck(healthCheck: ServiceConfig["healthCheck"] | undefined, fallback: DockerComposeHealthcheckRaw | undefined, options: {
+    internalPort: number;
+    user?: string;
+}): DockerComposeHealthcheckRaw | undefined;

package/dist/docker-compose/yaml.d.ts

@@ -0,0 +1,2 @@
+import type { ComposeDocument } from "./model";
+export declare function composeToYaml(document: ComposeDocument): string;

package/dist/environment/create-dev-environment.d.ts

@@ -0,0 +1,23 @@
+import type { AppConfig, DevConfig, DevEnvironment, ServiceConfig } from "../types";
+/**
+ * Create a dev environment from a configuration.
+ *
+ * @example
+ * ```typescript
+ * import { defineDevConfig, createDevEnvironment } from 'buncargo'
+ *
+ * const config = defineDevConfig({
+ *   projectPrefix: 'myapp',
+ *   services: { postgres: { port: 5432 } },
+ *   apps: { api: { port: 3000, devCommand: 'bun run dev' } }
+ * })
+ *
+ * export const dev = createDevEnvironment(config)
+ *
+ * // Usage
+ * await dev.start()
+ * ```
+ */
+export declare function createDevEnvironment<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>, options?: {
+    suffix?: string;
+}): DevEnvironment<TServices, TApps>;

package/dist/environment/index.d.ts

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

package/dist/environment/index.js

@@ -0,0 +1,15 @@
+import {
+  createDevEnvironment
+} from "../index-ma6tgdb2.js";
+import"../index-d8tyv5se.js";
+import"../index-c0dr6mcv.js";
+import"../index-fb29934k.js";
+import"../index-5t9jxqm0.js";
+import"../index-bnk6nr0g.js";
+import"../index-mam0bcyz.js";
+import"../index-mm412dkp.js";
+import"../index-t0fj6gg1.js";
+import"../index-qnx9j3qa.js";
+export {
+  createDevEnvironment
+};

package/dist/environment/logging.d.ts

@@ -0,0 +1,17 @@
+export declare 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;
+export declare function logPublicUrls(tunnels: Array<{
+    kind: "service" | "app";
+    name: string;
+    publicUrl: string;
+    localUrl: string;
+}>): void;

package/dist/environment/seeding.d.ts

@@ -0,0 +1,9 @@
+import type { AppConfig, HookContext, SeedCheckContext, ServiceConfig } from "../types";
+export declare 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"];
+export declare function createSeedCheckContext<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(baseContext: HookContext<TServices, TApps>, checkTable: SeedCheckContext<TServices, TApps>["checkTable"]): SeedCheckContext<TServices, TApps>;

package/dist/environment.d.ts

@@ -1,23 +1 @@
-import type { AppConfig, DevConfig, DevEnvironment, ServiceConfig } from "./types";
-/**
- * Create a dev environment from a configuration.
- *
- * @example
- * ```typescript
- * import { defineDevConfig, createDevEnvironment } from 'buncargo'
- *
- * const config = defineDevConfig({
- *   projectPrefix: 'myapp',
- *   services: { postgres: { port: 5432 } },
- *   apps: { api: { port: 3000, devCommand: 'bun run dev' } }
- * })
- *
- * export const dev = createDevEnvironment(config)
- *
- * // Usage
- * await dev.start()
- * ```
- */
-export declare function createDevEnvironment<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>, options?: {
-    suffix?: string;
-}): DevEnvironment<TServices, TApps>;
+export * from "./environment/index";

package/dist/environment.js

@@ -1,14 +1,12 @@
-import {
-  createDevEnvironment
-} from "./index-p8wty0e2.js";
-import"./index-ggq3yryx.js";
-import"./index-1yvbwj4k.js";
-import"./index-tjqw9vtj.js";
-import"./index-5hka0tff.js";
-import"./index-2fr3g85b.js";
-import"./index-6fm7mvwj.js";
-import"./index-08wa79cs.js";
-import"./index-qnx9j3qa.js";
-export {
-  createDevEnvironment
-};
+import { createDevEnvironment } from "./index-38xnzpa6.js";
+import "./index-vbpb89jy.js";
+import "./index-w8zxnjka.js";
+import "./index-mam0bcyz.js";
+import "./index-mm412dkp.js";
+import "./index-045jksh5.js";
+import "./index-6c1w1xk5.js";
+import "./index-tjbx2r2t.js";
+import "./index-4gp0az1g.js";
+import "./index-xkvd0nsd.js";
+import "./index-qnx9j3qa.js";
+export { createDevEnvironment };

package/dist/index-045jksh5.js

@@ -0,0 +1,147 @@
+// src/config/define-config.ts
+function defineDevConfig(config) {
+	return config;
+}
+
+// src/config/validate-config.ts
+import { isAbsolute, normalize } from "node:path";
+
+var BUILTIN_DOCKER_PRESETS = new Set(["postgres", "redis", "clickhouse"]);
+function inferBuiltInPreset(serviceName) {
+	const normalized = serviceName.toLowerCase();
+	return BUILTIN_DOCKER_PRESETS.has(normalized) ? normalized : null;
+}
+function validateConfig(config) {
+	const errors = [];
+	const composeServiceNames = new Set();
+	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;
+}
+function assertValidConfig(config) {
+	const errors = validateConfig(config);
+	if (errors.length > 0) {
+		throw new Error(`Invalid dev config:
+  - ${errors.join(`
+  - `)}`);
+	}
+}
+// src/config/merge-configs.ts
+function mergeConfigs(base, overrides) {
+	return {
+		...base,
+		...overrides,
+		services: { ...base.services, ...overrides.services },
+		apps: { ...base.apps, ...overrides.apps },
+		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 },
+	};
+}
+function definePartialConfig(config) {
+	return config;
+}
+export {
+	defineDevConfig,
+	validateConfig,
+	assertValidConfig,
+	mergeConfigs,
+	definePartialConfig,
+};