buncargo 1.0.5

package/bin.ts

@@ -0,0 +1,253 @@
+#!/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 prisma ...    # Run prisma commands
+ *   bunx buncargo help          # Show help
+ */
+
+import { runCli } from "./cli";
+import { createDevEnvironment } from "./environment";
+import type { AppConfig, DevEnvironment, ServiceConfig } from "./types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Config Discovery
+// ═══════════════════════════════════════════════════════════════════════════
+
+const CONFIG_FILES = [
+	"dev.config.ts",
+	"dev.config.js",
+	"dev-tools.config.ts",
+	"dev-tools.config.js",
+];
+
+/**
+ * Find and load the dev config file from the current directory.
+ * Returns the DevEnvironment created from the config.
+ */
+async function loadEnv(): Promise<
+	DevEnvironment<Record<string, ServiceConfig>, Record<string, AppConfig>>
+> {
+	const cwd = process.cwd();
+
+	for (const file of CONFIG_FILES) {
+		const path = `${cwd}/${file}`;
+		const exists = await Bun.file(path).exists();
+
+		if (exists) {
+			try {
+				const mod = await import(path);
+				const config = mod.default;
+
+				if (!config) {
+					console.error(
+						`❌ Config file "${file}" found but no default export.`,
+					);
+					console.error("");
+					console.error("   Export your config as default:");
+					console.error("");
+					console.error("   import { defineDevConfig } from 'buncargo'");
+					console.error("");
+					console.error("   export default defineDevConfig({ ... })");
+					process.exit(1);
+				}
+
+				// Validate it looks like a config
+				if (!config.projectPrefix || !config.services) {
+					console.error(`❌ Config file "${file}" is not a valid dev config.`);
+					console.error("");
+					console.error("   Make sure to use defineDevConfig:");
+					console.error("");
+					console.error("   export default defineDevConfig({");
+					console.error("     projectPrefix: 'myapp',");
+					console.error("     services: { ... }");
+					console.error("   })");
+					process.exit(1);
+				}
+
+				// Create environment from config
+				return createDevEnvironment(config);
+			} catch (error) {
+				console.error(`❌ Failed to load config file "${file}":`);
+				console.error(error);
+				process.exit(1);
+			}
+		}
+	}
+
+	console.error("❌ No config file found.");
+	console.error("");
+	console.error("   Create a dev.config.ts file in your project root:");
+	console.error("");
+	console.error("   import { defineDevConfig } from 'buncargo'");
+	console.error("");
+	console.error("   export default defineDevConfig({");
+	console.error("     projectPrefix: 'myapp',");
+	console.error("     services: {");
+	console.error('       postgres: { port: 5432, healthCheck: "pg_isready" }');
+	console.error("     }");
+	console.error("   })");
+	console.error("");
+	console.error("   Supported config files:");
+	for (const file of CONFIG_FILES) {
+		console.error(`     - ${file}`);
+	}
+	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,
+		),
+	);
+}
+
+function showHelp(): void {
+	console.log(`
+buncargo - Development environment CLI
+
+USAGE:
+  bunx buncargo <command> [options]
+
+COMMANDS:
+  dev                 Start the development environment
+  prisma <args>       Run Prisma CLI with correct DATABASE_URL
+  env                 Print environment info as JSON
+  help                Show this help message
+  version             Show version
+
+DEV OPTIONS:
+  --up-only           Start containers only (no dev servers)
+  --down              Stop containers
+  --reset             Stop containers and remove volumes
+  --migrate           Run migrations only
+  --seed              Run seeders
+  --lint              Run typecheck (no Docker required)
+
+EXAMPLES:
+  bunx buncargo dev              # Start everything
+  bunx buncargo dev --down       # Stop containers
+  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: { ... }
+  })
+`);
+}
+
+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 "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) => {
+	console.error("❌ Fatal error:", error);
+	process.exit(1);
+});

package/cli.ts

@@ -0,0 +1,238 @@
+import { spawn } from "node:child_process";
+import { spawnWatchdog, startHeartbeat, stopHeartbeat } from "./core/watchdog";
+import type {
+	AppConfig,
+	CliOptions,
+	DevEnvironment,
+	ServiceConfig,
+} from "./types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CLI Runner
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run the CLI for a dev environment.
+ * Handles common flags like --down, --reset, --up-only, --migrate, --seed, --lint.
+ *
+ * @example
+ * ```typescript
+ * import { dev } from './dev.config'
+ * import { runCli } from 'buncargo'
+ *
+ * await runCli(dev)
+ * ```
+ */
+export async function runCli<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	env: DevEnvironment<TServices, TApps>,
+	options: CliOptions = {},
+): Promise<void> {
+	const {
+		args = process.argv.slice(2),
+		watchdog = true,
+		watchdogTimeout = 10,
+		devServersCommand,
+	} = options;
+
+	// Log environment info
+	env.logInfo();
+
+	// Handle --lint (no Docker required)
+	if (args.includes("--lint")) {
+		const { runWorkspaceTypecheck } = await import("./lint");
+		const result = await runWorkspaceTypecheck({
+			root: env.root,
+			verbose: true,
+		});
+		process.exit(result.success ? 0 : 1);
+	}
+
+	// Handle --down
+	if (args.includes("--down")) {
+		await env.stop();
+		process.exit(0);
+	}
+
+	// Handle --reset
+	if (args.includes("--reset")) {
+		await env.stop({ removeVolumes: true });
+		process.exit(0);
+	}
+
+	// Start containers if not already running
+	const running = await env.isRunning();
+	if (running) {
+		console.log("✓ Containers already running");
+	} else {
+		await env.start({ startServers: false, wait: true });
+	}
+
+	// Handle --migrate (just run hooks, then exit)
+	if (args.includes("--migrate")) {
+		console.log("");
+		console.log("✅ Migrations applied successfully");
+		process.exit(0);
+	}
+
+	// Handle --seed (force run seeders via hook context)
+	if (args.includes("--seed")) {
+		console.log("🌱 Running seeders...");
+		const result = await env.exec("bun run run:seeder", {
+			throwOnError: false,
+		});
+		if (result.exitCode !== 0) {
+			console.error("❌ Seeding failed");
+			process.exit(1);
+		}
+		console.log("");
+		console.log("✅ Seeding complete");
+		process.exit(0);
+	}
+
+	// Handle --up-only
+	if (args.includes("--up-only")) {
+		console.log("");
+		console.log("✅ Containers started. Environment ready.");
+		console.log("");
+		process.exit(0);
+	}
+
+	// Start watchdog and heartbeat for interactive mode
+	if (watchdog) {
+		await spawnWatchdog(env.projectName, env.root, {
+			timeoutMinutes: watchdogTimeout,
+			verbose: true,
+		});
+		startHeartbeat(env.projectName);
+	}
+
+	// Build command: use provided command or auto-build from apps config
+	const command = devServersCommand ?? buildDevServersCommand(env.apps);
+
+	if (!command) {
+		console.log("✅ Containers ready. No apps configured.");
+		// Keep process alive if no apps
+		await new Promise(() => {});
+		return;
+	}
+
+	// Start dev servers interactively
+	console.log("");
+	console.log("🔧 Starting dev servers...");
+	console.log("");
+
+	await runCommand(command, env.root, env.buildEnvVars());
+
+	// Clean up heartbeat on exit
+	stopHeartbeat();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Command Building
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build a concurrently command from the apps config.
+ */
+function buildDevServersCommand(
+	apps: Record<string, AppConfig>,
+): string | null {
+	const appEntries = Object.entries(apps);
+	if (appEntries.length === 0) return null;
+
+	// Build commands for each app
+	const commands: string[] = [];
+	const names: string[] = [];
+	const colors = ["blue", "green", "yellow", "magenta", "cyan", "red"];
+
+	for (const [name, config] of appEntries) {
+		names.push(name);
+		const cwdPart = config.cwd ? `--cwd ${config.cwd}` : "";
+		commands.push(
+			`"bun run ${cwdPart} ${config.devCommand}"`.replace(/\s+/g, " ").trim(),
+		);
+	}
+
+	// Use concurrently to run all apps
+	const namesArg = `-n ${names.join(",")}`;
+	const colorsArg = `-c ${colors.slice(0, names.length).join(",")}`;
+	const commandsArg = commands.join(" ");
+
+	return `bun concurrently ${namesArg} ${colorsArg} ${commandsArg}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Interactive Command Runner
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run a command interactively (inherits stdio).
+ */
+function runCommand(
+	command: string,
+	cwd: string,
+	envVars: Record<string, string>,
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn(command, [], {
+			cwd,
+			env: { ...process.env, ...envVars },
+			stdio: "inherit",
+			shell: true,
+		});
+
+		proc.on("close", (code) => {
+			if (code === 0 || code === null) {
+				resolve();
+			} else {
+				reject(new Error(`Command exited with code ${code}`));
+			}
+		});
+
+		proc.on("error", reject);
+
+		// Handle SIGINT/SIGTERM
+		const cleanup = () => {
+			proc.kill("SIGTERM");
+		};
+
+		process.on("SIGINT", cleanup);
+		process.on("SIGTERM", cleanup);
+	});
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Utility Functions
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a CLI flag is present.
+ */
+export function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+/**
+ * Get a flag value (e.g., --timeout=10 or --timeout 10).
+ */
+export function getFlagValue(args: string[], flag: string): string | undefined {
+	// Check --flag=value format
+	const prefixed = args.find((arg) => arg.startsWith(`${flag}=`));
+	if (prefixed) {
+		return prefixed.split("=")[1];
+	}
+
+	// Check --flag value format
+	const index = args.indexOf(flag);
+	if (index !== -1 && index + 1 < args.length) {
+		const nextArg = args[index + 1];
+		if (nextArg !== undefined && !nextArg.startsWith("-")) {
+			return nextArg;
+		}
+	}
+
+	return undefined;
+}

package/config.ts

@@ -0,0 +1,194 @@
+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;
+}