buncargo 1.0.29 → 3.2.0

package/{types.ts → src/types/all-types.ts}

@@ -27,12 +27,106 @@ export interface UrlBuilderContext {
  */
 export type UrlBuilderFn = (ctx: UrlBuilderContext) => string;
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Docker Compose Configuration
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Recursive YAML-safe value used for Docker Compose objects.
+ */
+export type DockerComposeNode =
+	| string
+	| number
+	| boolean
+	| null
+	| DockerComposeNode[]
+	| { [key: string]: DockerComposeNode | undefined };
+
+/**
+ * Built-in Docker service presets.
+ */
+export type DockerPresetName = "postgres" | "redis" | "clickhouse";
+
+/**
+ * Docker Compose healthcheck object.
+ */
+export interface DockerComposeHealthcheckRaw {
+	test?: string[] | string;
+	interval?: string;
+	timeout?: string;
+	retries?: number;
+	start_period?: string;
+	disable?: boolean;
+	[composeKey: string]: DockerComposeNode | undefined;
+}
+
+/**
+ * Docker Compose service (raw escape hatch).
+ * Includes common fields plus index signature for advanced keys.
+ */
+export interface DockerComposeServiceRaw {
+	image?: string;
+	container_name?: string;
+	ports?: string[];
+	volumes?: string[];
+	environment?: Record<string, string | number | boolean>;
+	command?: string | string[];
+	entrypoint?: string | string[];
+	depends_on?: string[] | Record<string, DockerComposeNode>;
+	healthcheck?: DockerComposeHealthcheckRaw;
+	ulimits?: Record<string, number | { soft: number; hard: number }>;
+	restart?: string;
+	working_dir?: string;
+	[composeKey: string]: DockerComposeNode | undefined;
+}
+
+/**
+ * Docker Compose volume object.
+ */
+export interface DockerComposeVolumeRaw {
+	driver?: string;
+	driver_opts?: Record<string, string | number | boolean>;
+	[composeKey: string]: DockerComposeNode | undefined;
+}
+
+/**
+ * Helper-friendly preset service definition.
+ */
+export interface DockerPresetServiceDefinition {
+	kind: "preset";
+	preset: DockerPresetName;
+	service?: DockerComposeServiceRaw;
+}
+
+/**
+ * Docker service definition accepted by service config.
+ * - raw object is the manual escape hatch
+ * - helper mode returns `kind`-based definitions
+ */
+export type DockerServiceDefinition =
+	| DockerComposeServiceRaw
+	| DockerPresetServiceDefinition;
+
+/**
+ * Docker Compose generation configuration.
+ */
+export interface DockerComposeGenerationOptions {
+	/** Path to generated compose file relative to root. Default: '.buncargo/docker-compose.generated.yml' */
+	generatedFile?: string;
+	/** Write strategy for generated compose file. Default: 'always' */
+	writeStrategy?: "always" | "if-missing";
+	/** Extra top-level named volumes */
+	volumes?: Record<string, DockerComposeVolumeRaw>;
+}
+
 /**
  * Configuration for a Docker Compose service (e.g., postgres, redis).
  */
 export interface ServiceConfig {
 	/** Base port for the service (before offset is applied) */
 	port: number;
+	/** Whether this service can be exposed publicly via tunnel */
+	expose?: boolean;
 	/** Optional secondary port (e.g., ClickHouse native protocol) */
 	secondaryPort?: number;
 	/** Health check: built-in name, custom function, or disabled (false) */
@@ -53,6 +147,8 @@ export interface ServiceConfig {
 	user?: string;
 	/** Password (default: 'postgres' for postgres, 'root' for mysql, 'clickhouse' for clickhouse) */
 	password?: string;
+	/** Docker Compose service definition (preset helper or raw escape hatch) */
+	docker?: DockerServiceDefinition;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -65,6 +161,8 @@ export interface ServiceConfig {
 export interface AppConfig {
 	/** Base port for the app (before offset is applied) */
 	port: number;
+	/** Whether this app can be exposed publicly via tunnel */
+	expose?: boolean;
 	/** Command to start the dev server */
 	devCommand: string;
 	/** Command to start production server (optional) */
@@ -110,6 +208,8 @@ export interface HookContext<
 	ports: ComputedPorts<TServices, TApps>;
 	/** Computed URLs for all services and apps */
 	urls: ComputedUrls<TServices, TApps>;
+	/** Public tunnel URLs for exposed services/apps (when active) */
+	publicUrls: ComputedPublicUrls<TServices, TApps>;
 	/** Execute a shell command with environment variables set */
 	exec: (
 		cmd: string,
@@ -269,8 +369,6 @@ export interface DevOptions {
 	worktreeIsolation?: boolean;
 	/** Auto-shutdown after idle time in ms. Set to false to disable. Default: false */
 	autoShutdown?: number | false;
-	/** Path to docker-compose.yml relative to root. Default: 'docker-compose.yml' */
-	composeFile?: string;
 	/** Default verbose setting for all operations. Default: true */
 	verbose?: boolean;
 }
@@ -284,7 +382,12 @@ export type EnvVarsBuilder<
 > = (
 	ports: ComputedPorts<TServices, TApps>,
 	urls: ComputedUrls<TServices, TApps>,
-	ctx: { projectName: string; localIp: string; portOffset: number },
+	ctx: {
+		projectName: string;
+		localIp: string;
+		portOffset: number;
+		publicUrls: ComputedPublicUrls<TServices, TApps>;
+	},
 ) => Record<string, string | number>;
 
 /**
@@ -308,11 +411,12 @@ export interface DevConfig<
 	 *
 	 * @example
 	 * ```typescript
-	 * envVars: (ports, urls, { localIp }) => ({
+	 * envVars: (ports, urls, { localIp, publicUrls }) => ({
 	 *   DATABASE_URL: urls.postgres,
 	 *   BASE_URL: urls.api,
 	 *   VITE_PORT: ports.platform,
-	 *   EXPO_API_URL: `http://${localIp}:${ports.api}`
+	 *   EXPO_API_URL: `http://${localIp}:${ports.api}`,
+	 *   WEBHOOK_URL: publicUrls.api
 	 * })
 	 * ```
 	 */
@@ -327,6 +431,8 @@ export interface DevConfig<
 	prisma?: PrismaConfig;
 	/** Additional options (optional) */
 	options?: DevOptions;
+	/** Docker Compose generation options (optional) */
+	docker?: DockerComposeGenerationOptions;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -366,6 +472,13 @@ export type ComputedUrls<
 	[K in keyof TApps]: string;
 };
 
+export type ComputedPublicUrls<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+> = Partial<{
+	[K in keyof TServices | keyof TApps]: string;
+}>;
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Start/Stop Options
 // ═══════════════════════════════════════════════════════════════════════════
@@ -386,6 +499,10 @@ export interface StartOptions {
 	suffix?: string;
 	/** Skip automatic seeding (useful when CLI handles seeding separately). Default: false */
 	skipSeed?: boolean;
+	/** Skip the initial `logInfo` banner (CLI uses this with `--expose`, then logs once with tunnel URLs). Default: false */
+	skipEnvironmentLog?: boolean;
+	/** If set, start and wait for only these app names (must exist in `apps`). */
+	onlyApps?: string[];
 }
 
 /**
@@ -409,6 +526,40 @@ export interface DevServerPids {
 	[appName: string]: number;
 }
 
+/** Tunnel rows passed to `logInfo` for public URL lines (matches `PublicTunnel` without `close`) */
+export interface DevEnvironmentTunnelLog {
+	kind: "service" | "app";
+	name: string;
+	localUrl: string;
+	publicUrl: string;
+}
+
+/** Active tunnel with teardown — same shape as core `PublicTunnel`. */
+export type PublicTunnelHandle = DevEnvironmentTunnelLog & {
+	close: () => Promise<void>;
+};
+
+/** Options for {@link DevEnvironment.openPublicTunnels}. */
+export interface OpenPublicTunnelsOptions {
+	/** Subset of expose targets by name; omit for all `expose: true` services/apps. */
+	names?: string[];
+	/**
+	 * Wait for these apps' HTTP health endpoints before opening tunnels.
+	 * Servers must already be listening on their ports.
+	 */
+	waitForHealthy?: string[];
+}
+
+/** Result of {@link DevEnvironment.openPublicTunnels}. */
+export interface OpenPublicTunnelsResult<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+> {
+	publicUrls: ComputedPublicUrls<TServices, TApps>;
+	tunnels: PublicTunnelHandle[];
+	close: () => Promise<void>;
+}
+
 /**
  * The main dev environment interface returned by createDevEnvironment().
  */
@@ -426,6 +577,10 @@ export interface DevEnvironment<
 	readonly ports: ComputedPorts<TServices, TApps>;
 	/** Computed URLs for all services and apps */
 	readonly urls: ComputedUrls<TServices, TApps>;
+	/** Public tunnel URLs for exposed services/apps (when active) */
+	readonly publicUrls: ComputedPublicUrls<TServices, TApps>;
+	/** Services configuration */
+	readonly services: TServices;
 	/** Apps configuration (for CLI to build commands) */
 	readonly apps: TApps;
 	/** Port offset applied (0 for main, > 0 for worktrees) */
@@ -436,6 +591,8 @@ export interface DevEnvironment<
 	readonly localIp: string;
 	/** Path to monorepo root */
 	readonly root: string;
+	/** Path passed to docker compose -f */
+	readonly composeFile: string;
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Container Management
@@ -458,6 +615,8 @@ export interface DevEnvironment<
 	startServers(options?: {
 		productionBuild?: boolean;
 		verbose?: boolean;
+		/** If set, start and wait for only these app names (must exist in `apps`). */
+		onlyApps?: string[];
 	}): Promise<DevServerPids>;
 	/** Stop a process by PID */
 	stopProcess(pid: number): void;
@@ -465,14 +624,25 @@ export interface DevEnvironment<
 	waitForServers(options?: {
 		timeout?: number;
 		productionBuild?: boolean;
+		/** If set, wait only for these app names (must exist in `apps`). */
+		onlyApps?: string[];
 	}): Promise<void>;
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Utilities
 	// ─────────────────────────────────────────────────────────────────────────
 
-	/** Build environment variables for shell commands */
+	/**
+	 * Build environment variables for shell commands.
+	 * Call **after** {@link setPublicUrls} or {@link openPublicTunnels} so `envVars` and `*_PUBLIC_URL` reflect tunnel URLs.
+	 */
 	buildEnvVars(production?: boolean): Record<string, string>;
+	/** Set public tunnel URLs used by envVars and *_PUBLIC_URL injection */
+	setPublicUrls(urls: ComputedPublicUrls<TServices, TApps>): void;
+	/** Clear all public tunnel URLs */
+	clearPublicUrls(): void;
+	/** Ensure generated docker compose file exists and return path used with -f */
+	ensureComposeFile(): string;
 	/** Execute a command with environment variables set */
 	exec(
 		cmd: string,
@@ -480,8 +650,16 @@ export interface DevEnvironment<
 	): Promise<{ exitCode: number; stdout: string; stderr: string }>;
 	/** Wait for an HTTP server to respond */
 	waitForServer(url: string, timeout?: number): Promise<void>;
-	/** Log environment info to console */
-	logInfo(label?: string): void;
+	/** Log environment info to console; pass `tunnels` to show public URLs next to services/apps */
+	logInfo(label?: string, tunnels?: DevEnvironmentTunnelLog[]): void;
+
+	/**
+	 * Resolve expose targets, start public quick tunnels, and apply {@link setPublicUrls}.
+	 * Call {@link buildEnvVars} after this resolves when spawning processes that need `EXPO_PUBLIC_*` / `*_PUBLIC_URL`.
+	 */
+	openPublicTunnels(
+		options?: OpenPublicTunnelsOptions,
+	): Promise<OpenPublicTunnelsResult<TServices, TApps>>;
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Vibe Kanban Integration

package/src/types/index.ts

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

package/bin.ts

@@ -1,192 +0,0 @@
-#!/usr/bin/env bun
-
-/**
- * CLI Entry Point for buncargo
- *
- * Usage:
- *   bunx buncargo dev           # Start containers + dev servers
- *   bunx buncargo dev --down    # Stop containers
- *   bunx buncargo dev --reset   # Stop + remove volumes
- *   bunx buncargo typecheck     # Run TypeScript typecheck
- *   bunx buncargo prisma ...    # Run prisma commands
- *   bunx buncargo help          # Show help
- */
-
-import { runCli } from "./cli";
-import { loadDevEnv } from "./loader";
-
-/**
- * Load the dev environment with CLI-friendly error output.
- */
-async function loadEnv() {
-	try {
-		return await loadDevEnv();
-	} catch (error) {
-		console.error(`❌ ${error instanceof Error ? error.message : error}`);
-		process.exit(1);
-	}
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Command Handlers
-// ═══════════════════════════════════════════════════════════════════════════
-
-async function handleDev(args: string[]): Promise<void> {
-	const env = await loadEnv();
-	await runCli(env, { args });
-}
-
-async function handlePrisma(args: string[]): Promise<void> {
-	const env = await loadEnv();
-
-	if (!env.prisma) {
-		console.error("❌ Prisma is not configured in your dev config.");
-		console.error("");
-		console.error("   Add prisma to your config:");
-		console.error("");
-		console.error("   export default defineDevConfig({");
-		console.error("     ...");
-		console.error("     prisma: {");
-		console.error("       cwd: 'packages/prisma'");
-		console.error("     }");
-		console.error("   })");
-		process.exit(1);
-	}
-
-	// Ensure database is running
-	const running = await env.isRunning();
-	if (!running) {
-		console.log("🐳 Starting database container...");
-		await env.start({ startServers: false, wait: true });
-	}
-
-	const exitCode = await env.prisma.run(args);
-	process.exit(exitCode);
-}
-
-async function handleEnv(): Promise<void> {
-	const env = await loadEnv();
-	console.log(
-		JSON.stringify(
-			{
-				projectName: env.projectName,
-				ports: env.ports,
-				urls: env.urls,
-				portOffset: env.portOffset,
-				isWorktree: env.isWorktree,
-				localIp: env.localIp,
-				root: env.root,
-			},
-			null,
-			2,
-		),
-	);
-}
-
-async function handleTypecheck(): Promise<void> {
-	const env = await loadEnv();
-	const { runWorkspaceTypecheck } = await import("./lint");
-	const result = await runWorkspaceTypecheck({
-		root: env.root,
-		verbose: true,
-	});
-	process.exit(result.success ? 0 : 1);
-}
-
-function showHelp(): void {
-	console.log(`
-buncargo - Development environment CLI
-
-USAGE:
-  bunx buncargo <command> [options]
-
-COMMANDS:
-  dev                 Start the development environment
-  typecheck           Run TypeScript typecheck across workspaces
-  prisma <args>       Run Prisma CLI with correct DATABASE_URL
-  env                 Print environment info as JSON
-  help                Show this help message
-  version             Show version
-
-EXAMPLES:
-  bunx buncargo dev              # Start everything
-  bunx buncargo dev --help       # Show dev command options
-  bunx buncargo dev --down       # Stop containers
-  bunx buncargo typecheck        # Run typecheck
-  bunx buncargo prisma studio    # Open Prisma Studio
-  bunx buncargo env              # Get ports/urls as JSON
-
-CONFIG:
-  Create a dev.config.ts with a default export:
-
-  import { defineDevConfig } from 'buncargo'
-
-  export default defineDevConfig({
-    projectPrefix: 'myapp',
-    services: { ... },
-    apps: { ... }
-  })
-
-Run "bunx buncargo dev --help" for dev command options.
-`);
-}
-
-function showVersion(): void {
-	const pkg = require("./package.json");
-	console.log(`buncargo v${pkg.version}`);
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Main
-// ═══════════════════════════════════════════════════════════════════════════
-
-async function main(): Promise<void> {
-	const args = process.argv.slice(2);
-	const command = args[0];
-	const commandArgs = args.slice(1);
-
-	if (
-		!command ||
-		command === "help" ||
-		command === "--help" ||
-		command === "-h"
-	) {
-		showHelp();
-		process.exit(0);
-	}
-
-	if (command === "version" || command === "--version" || command === "-v") {
-		showVersion();
-		process.exit(0);
-	}
-
-	switch (command) {
-		case "dev":
-			await handleDev(commandArgs);
-			break;
-
-		case "typecheck":
-			await handleTypecheck();
-			break;
-
-		case "prisma":
-			await handlePrisma(commandArgs);
-			break;
-
-		case "env":
-			await handleEnv();
-			break;
-
-		default:
-			console.error(`❌ Unknown command: ${command}`);
-			console.error("");
-			console.error('   Run "bunx buncargo help" for available commands.');
-			process.exit(1);
-	}
-}
-
-main().catch((error) => {
-	const message = error instanceof Error ? error.message : String(error);
-	console.error(`❌ ${message}`);
-	process.exit(1);
-});

package/config.ts

@@ -1,194 +0,0 @@
-import type {
-	AppConfig,
-	DevConfig,
-	DevHooks,
-	DevOptions,
-	EnvVarsBuilder,
-	MigrationConfig,
-	PrismaConfig,
-	SeedConfig,
-	ServiceConfig,
-} from "./types";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Config Factory
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Define a dev environment configuration with full TypeScript inference.
- *
- * @example
- * ```typescript
- * const config = defineDevConfig({
- *   projectPrefix: 'myapp',
- *   services: {
- *     postgres: { port: 5432, healthCheck: 'pg_isready' },
- *     redis: { port: 6379 },
- *   },
- *   apps: {
- *     api: { port: 3000, devCommand: 'bun run dev', cwd: 'apps/backend' },
- *     web: { port: 5173, devCommand: 'bun run dev', cwd: 'apps/frontend' },
- *   },
- *   envVars: (ports, urls) => ({
- *     DATABASE_URL: urls.postgres,
- *     REDIS_URL: urls.redis,
- *     API_PORT: String(ports.api),
- *   }),
- * })
- * ```
- */
-export function defineDevConfig<
-	TServices extends Record<string, ServiceConfig>,
-	TApps extends Record<string, AppConfig> = Record<string, never>,
->(config: {
-	/** Prefix for Docker project name (e.g., 'myapp' -> 'myapp-main') */
-	projectPrefix: string;
-	/** Docker Compose services to manage */
-	services: TServices;
-	/** Applications to start (optional) */
-	apps?: TApps;
-	/**
-	 * Environment variables builder. Define all env vars here.
-	 *
-	 * @example
-	 * ```typescript
-	 * envVars: (ports, urls, { localIp }) => ({
-	 *   DATABASE_URL: urls.postgres,
-	 *   BASE_URL: urls.api,
-	 *   VITE_PORT: ports.platform,
-	 *   EXPO_API_URL: `http://${localIp}:${ports.api}`
-	 * })
-	 * ```
-	 */
-	envVars?: EnvVarsBuilder<TServices, TApps>;
-	/** Lifecycle hooks (optional) */
-	hooks?: DevHooks<TServices, TApps>;
-	/** Migrations to run after containers are ready (optional). Runs in parallel. */
-	migrations?: MigrationConfig[];
-	/** Seed configuration (optional). Runs after migrations, before servers. */
-	seed?: SeedConfig<TServices, TApps>;
-	/** Prisma configuration (optional). When set, dev.prisma is available. */
-	prisma?: PrismaConfig;
-	/** Additional options (optional) */
-	options?: DevOptions;
-}): DevConfig<TServices, TApps> {
-	return config as DevConfig<TServices, TApps>;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Config Validation
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Validate a dev config and return any errors.
- */
-export function validateConfig<
-	TServices extends Record<string, ServiceConfig>,
-	TApps extends Record<string, AppConfig>,
->(config: DevConfig<TServices, TApps>): string[] {
-	const errors: string[] = [];
-
-	// Check project prefix
-	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",
-		);
-	}
-
-	// Check services
-	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`);
-		}
-	}
-
-	// Check apps
-	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`);
-		}
-	}
-
-	// Check migrations
-	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`);
-		}
-	}
-
-	// Check seed
-	if (config.seed && !config.seed.command) {
-		errors.push("Seed must have a command");
-	}
-
-	return errors;
-}
-
-/**
- * Validate config and throw if invalid.
- */
-export function assertValidConfig<
-	TServices extends Record<string, ServiceConfig>,
-	TApps extends Record<string, AppConfig>,
->(config: DevConfig<TServices, TApps>): void {
-	const errors = validateConfig(config);
-	if (errors.length > 0) {
-		throw new Error(`Invalid dev config:\n  - ${errors.join("\n  - ")}`);
-	}
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Config Helpers
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Merge two configs, with the second taking precedence.
- */
-export function mergeConfigs<
-	TServices extends Record<string, ServiceConfig>,
-	TApps extends Record<string, AppConfig>,
->(
-	base: DevConfig<TServices, TApps>,
-	overrides: Partial<DevConfig<TServices, TApps>>,
-): DevConfig<TServices, TApps> {
-	return {
-		...base,
-		...overrides,
-		services: { ...base.services, ...overrides.services } as TServices,
-		apps: { ...base.apps, ...overrides.apps } as TApps,
-		hooks: { ...base.hooks, ...overrides.hooks },
-		migrations: overrides.migrations ?? base.migrations,
-		seed: overrides.seed ?? base.seed,
-		options: { ...base.options, ...overrides.options },
-	};
-}
-
-/**
- * Create a partial config that can be merged later.
- */
-export function definePartialConfig<
-	TServices extends Record<string, ServiceConfig> = Record<
-		string,
-		ServiceConfig
-	>,
-	TApps extends Record<string, AppConfig> = Record<string, AppConfig>,
->(
-	config: Partial<DevConfig<TServices, TApps>>,
-): Partial<DevConfig<TServices, TApps>> {
-	return config;
-}