buncargo 1.0.5

package/core/ports.ts

@@ -0,0 +1,253 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import type { AppConfig, ServiceConfig } from "../types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Monorepo Root Detection
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Find the monorepo root by looking for package.json with workspaces.
+ */
+export function findMonorepoRoot(startDir?: string): string {
+	let dir = startDir ?? process.cwd();
+	while (dir !== "/") {
+		try {
+			const pkgPath = resolve(dir, "package.json");
+			if (existsSync(pkgPath)) {
+				const content = readFileSync(pkgPath, "utf-8");
+				const pkg = JSON.parse(content);
+				if (pkg.workspaces) {
+					return dir;
+				}
+			}
+		} catch {
+			// Continue searching
+		}
+		dir = dirname(dir);
+	}
+	return process.cwd();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Worktree Detection
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get the worktree name from .git file (if in a worktree).
+ */
+export function getWorktreeName(root?: string): string | null {
+	const monorepoRoot = root ?? findMonorepoRoot();
+	const gitPath = resolve(monorepoRoot, ".git");
+	try {
+		if (!existsSync(gitPath) || !statSync(gitPath).isFile()) return null;
+		const content = readFileSync(gitPath, "utf-8").trim();
+		const match = content.match(/^gitdir:\s*(.+)$/);
+		if (!match?.[1]) return null;
+		return basename(match[1]);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check if the current directory is a git worktree.
+ */
+export function isWorktree(root?: string): boolean {
+	return getWorktreeName(root) !== null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Port Offset Calculation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Simple hash function for consistent port offsets.
+ */
+function simpleHash(str: string): number {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return Math.abs(hash);
+}
+
+/**
+ * Calculate port offset based on worktree name and optional suffix.
+ * Returns 0 for main branch, 10-99 for worktrees.
+ */
+export function calculatePortOffset(suffix?: string, root?: string): number {
+	const worktreeName = getWorktreeName(root);
+	if (!worktreeName) return 0;
+	const hashInput = suffix ? `${worktreeName}-${suffix}` : worktreeName;
+	// Range 10-99 to avoid conflicts with main (0) and leave room
+	return 10 + (simpleHash(hashInput) % 90);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Project Naming
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate Docker project name from prefix and directory.
+ */
+export function getProjectName(
+	prefix: string,
+	suffix?: string,
+	root?: string,
+): string {
+	const monorepoRoot = root ?? findMonorepoRoot();
+	const dirName = basename(monorepoRoot);
+	const baseName = `${prefix}-${dirName.toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
+	return suffix ? `${baseName}-${suffix}` : baseName;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Port Computation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute all ports for services and apps with offset applied.
+ */
+export function computePorts<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	services: TServices,
+	apps: TApps | undefined,
+	offset: number,
+): Record<string, number> {
+	const ports: Record<string, number> = {};
+
+	// Add service ports
+	for (const [name, config] of Object.entries(services)) {
+		ports[name] = config.port + offset;
+		// Handle secondary ports (e.g., clickhouseNative)
+		if (config.secondaryPort) {
+			ports[`${name}Secondary`] = config.secondaryPort + offset;
+		}
+	}
+
+	// Add app ports
+	if (apps) {
+		for (const [name, config] of Object.entries(apps)) {
+			ports[name] = config.port + offset;
+		}
+	}
+
+	return ports;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// URL Generation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Service defaults for common services.
+ */
+const SERVICE_DEFAULTS: Record<
+	string,
+	{ user: string; password: string; database: string }
+> = {
+	postgres: { user: "postgres", password: "postgres", database: "postgres" },
+	postgresql: { user: "postgres", password: "postgres", database: "postgres" },
+	redis: { user: "", password: "", database: "" },
+	clickhouse: { user: "default", password: "clickhouse", database: "default" },
+	mysql: { user: "root", password: "root", database: "mysql" },
+	mongodb: { user: "", password: "", database: "" },
+};
+
+/**
+ * Build URL for a service with given credentials and database.
+ */
+function buildServiceUrl(
+	serviceName: string,
+	ctx: { port: number; host: string },
+	config: { database?: string; user?: string; password?: string },
+): string | null {
+	const defaults = SERVICE_DEFAULTS[serviceName];
+	if (!defaults && !config.database) return null;
+
+	const user = config.user ?? defaults?.user ?? "";
+	const password = config.password ?? defaults?.password ?? "";
+	const database = config.database ?? defaults?.database ?? "";
+
+	switch (serviceName) {
+		case "postgres":
+		case "postgresql":
+			return `postgresql://${user}:${password}@${ctx.host}:${ctx.port}/${database}`;
+		case "redis":
+			return `redis://${ctx.host}:${ctx.port}`;
+		case "clickhouse":
+			return `http://${user}:${password}@${ctx.host}:${ctx.port}/${database}`;
+		case "mysql":
+			return `mysql://${user}:${password}@${ctx.host}:${ctx.port}/${database}`;
+		case "mongodb":
+			return `mongodb://${ctx.host}:${ctx.port}/${database}`;
+		default:
+			return null;
+	}
+}
+
+/**
+ * Compute URLs for all services and apps.
+ */
+export function computeUrls<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	services: TServices,
+	apps: TApps | undefined,
+	ports: Record<string, number>,
+	localIp: string,
+): Record<string, string> {
+	const urls: Record<string, string> = {};
+	const host = "localhost";
+
+	// Add service URLs
+	for (const [name, config] of Object.entries(services)) {
+		const port = ports[name];
+		const secondaryPort = ports[`${name}Secondary`];
+
+		// Skip if port is not defined
+		if (port === undefined) continue;
+
+		const ctx = { port, secondaryPort, host, localIp };
+
+		if (config.urlTemplate) {
+			// Use the provided function
+			urls[name] = config.urlTemplate(ctx);
+		} else {
+			// Try to build URL using service name and config options
+			const builtUrl = buildServiceUrl(
+				name,
+				{ port, host },
+				{
+					database: config.database,
+					user: config.user,
+					password: config.password,
+				},
+			);
+			if (builtUrl) {
+				urls[name] = builtUrl;
+			} else {
+				// Fallback to simple HTTP URL
+				urls[name] = `http://${host}:${port}`;
+			}
+		}
+	}
+
+	// Add app URLs
+	if (apps) {
+		for (const [name, _config] of Object.entries(apps)) {
+			const port = ports[name];
+			urls[name] = `http://${host}:${port}`;
+			// Also add local IP version for mobile connectivity
+			urls[`${name}Local`] = `http://${localIp}:${port}`;
+		}
+	}
+
+	return urls;
+}

package/core/process.ts

@@ -0,0 +1,253 @@
+import {
+	type ChildProcess,
+	execSync,
+	type SpawnOptions,
+	spawn,
+} from "node:child_process";
+import { resolve } from "node:path";
+import type { AppConfig, DevServerPids, ExecOptions } from "../types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Command Execution
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ExecResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+}
+
+/**
+ * Execute a shell command with environment variables.
+ */
+export function exec(
+	cmd: string,
+	root: string,
+	envVars: Record<string, string>,
+	options: ExecOptions = {},
+): ExecResult {
+	const { cwd, verbose = false, env = {}, throwOnError = true } = options;
+
+	const workingDir = cwd ? resolve(root, cwd) : root;
+	const fullEnv = { ...process.env, ...envVars, ...env };
+
+	try {
+		const stdout = execSync(cmd, {
+			cwd: workingDir,
+			env: fullEnv,
+			encoding: "utf-8",
+			stdio: verbose ? "inherit" : ["pipe", "pipe", "pipe"],
+		});
+
+		return {
+			exitCode: 0,
+			stdout: typeof stdout === "string" ? stdout : "",
+			stderr: "",
+		};
+	} catch (error) {
+		const execError = error as {
+			status?: number;
+			stdout?: string;
+			stderr?: string;
+		};
+		const result: ExecResult = {
+			exitCode: execError.status ?? 1,
+			stdout: execError.stdout ?? "",
+			stderr: execError.stderr ?? "",
+		};
+
+		if (throwOnError) {
+			throw new Error(
+				`Command failed with exit code ${result.exitCode}: ${cmd}\n${result.stderr}`,
+			);
+		}
+
+		return result;
+	}
+}
+
+/**
+ * Execute a shell command asynchronously.
+ */
+export async function execAsync(
+	cmd: string,
+	root: string,
+	envVars: Record<string, string>,
+	options: ExecOptions = {},
+): Promise<ExecResult> {
+	// For now, wrap sync in Promise - can be optimized later with spawn
+	return new Promise((resolve) => {
+		const result = exec(cmd, root, envVars, {
+			...options,
+			throwOnError: false,
+		});
+		resolve(result);
+	});
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Process Spawning
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SpawnDevServerOptions {
+	verbose?: boolean;
+	detached?: boolean;
+	isCI?: boolean;
+}
+
+/**
+ * Spawn a dev server as a detached process.
+ */
+export function spawnDevServer(
+	command: string,
+	root: string,
+	appCwd: string | undefined,
+	envVars: Record<string, string>,
+	options: SpawnDevServerOptions = {},
+): ChildProcess {
+	const { verbose = false, detached = true, isCI = false } = options;
+
+	// Parse command into parts
+	const parts = command.split(" ");
+	const cmd = parts[0];
+	const args = parts.slice(1);
+
+	if (!cmd) {
+		throw new Error("Command cannot be empty");
+	}
+
+	const workingDir = appCwd ? resolve(root, appCwd) : root;
+
+	const spawnOptions: SpawnOptions = {
+		cwd: workingDir,
+		env: { ...process.env, ...envVars },
+		detached,
+		stdio: isCI || verbose ? "inherit" : "ignore",
+	};
+
+	const proc = spawn(cmd, args, spawnOptions);
+
+	if (detached && proc.unref) {
+		proc.unref();
+	}
+
+	return proc;
+}
+
+/**
+ * Start all configured dev servers.
+ */
+export function startDevServers(
+	apps: Record<string, AppConfig>,
+	root: string,
+	envVars: Record<string, string>,
+	options: {
+		verbose?: boolean;
+		productionBuild?: boolean;
+		isCI?: boolean;
+	} = {},
+): DevServerPids {
+	const { verbose = true, productionBuild = false, isCI = false } = options;
+	const pids: DevServerPids = {};
+
+	if (verbose) {
+		console.log(
+			productionBuild
+				? "🚀 Starting production servers..."
+				: "🔧 Starting dev servers...",
+		);
+	}
+
+	for (const [name, config] of Object.entries(apps)) {
+		const command = productionBuild
+			? (config.prodCommand ?? config.devCommand)
+			: config.devCommand;
+
+		const proc = spawnDevServer(command, root, config.cwd, envVars, {
+			verbose,
+			isCI,
+		});
+
+		if (proc.pid) {
+			pids[name] = proc.pid;
+			if (verbose) {
+				console.log(`   ${name} PID: ${proc.pid}`);
+			}
+		}
+	}
+
+	return pids;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Process Management
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Stop a process by PID.
+ */
+export function stopProcess(pid: number): void {
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {
+		// Process may already be dead
+	}
+}
+
+/**
+ * Stop all processes by their PIDs.
+ */
+export function stopAllProcesses(
+	pids: DevServerPids,
+	options: { verbose?: boolean } = {},
+): void {
+	const { verbose = true } = options;
+
+	for (const [name, pid] of Object.entries(pids)) {
+		if (pid) {
+			if (verbose) console.log(`   Stopping ${name} (PID: ${pid})`);
+			stopProcess(pid);
+		}
+	}
+}
+
+/**
+ * Check if a process is alive by sending signal 0.
+ */
+export function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Build Commands
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Run production build for apps that have buildCommand configured.
+ */
+export function buildApps(
+	apps: Record<string, AppConfig>,
+	root: string,
+	envVars: Record<string, string>,
+	options: { verbose?: boolean } = {},
+): void {
+	const { verbose = true } = options;
+
+	for (const [name, config] of Object.entries(apps)) {
+		if (config.buildCommand) {
+			if (verbose) console.log(`🔨 Building ${name}...`);
+
+			exec(config.buildCommand, root, envVars, {
+				cwd: config.cwd,
+				verbose,
+			});
+		}
+	}
+
+	if (verbose) console.log("✓ Build complete");
+}

package/core/utils.ts

@@ -0,0 +1,127 @@
+import type { AppConfig, DevConfig, ServiceConfig } from "../types";
+import { getLocalIp } from "./network";
+import { calculatePortOffset, computePorts, computeUrls } from "./ports";
+
+/**
+ * Core utility functions shared across modules.
+ */
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Detect if running in a CI environment.
+ */
+export function isCI(): boolean {
+	return (
+		process.env.CI === "true" ||
+		process.env.CI === "1" ||
+		process.env.GITHUB_ACTIONS === "true" ||
+		process.env.GITLAB_CI === "true" ||
+		process.env.CIRCLECI === "true" ||
+		process.env.JENKINS_URL !== undefined
+	);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Vibe Kanban Integration
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Log the frontend port in a format that Vibe Kanban can detect.
+ * This is used to communicate the dev server port to external tools.
+ *
+ * @param port - The port number the frontend is running on
+ */
+export function logFrontendPort(port: number | undefined): void {
+	console.log(`using_frontend_port:${port}`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Config-based Env Var Helper
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get an environment variable value from the config.
+ * Computes ports/urls and runs envVars to get the value.
+ *
+ * @param config - The dev config object (from defineDevConfig)
+ * @param name - The environment variable name
+ * @param options - Optional settings (log for Vibe Kanban detection)
+ *
+ * @example
+ * ```typescript
+ * // In vite.config.ts
+ * import { getEnvVar } from 'buncargo'
+ * import config from '../../dev.config'
+ *
+ * export default defineConfig(async ({ command }) => {
+ *   const isDev = command === 'serve'
+ *   const vitePort = isDev ? getEnvVar(config, 'VITE_PORT') : undefined
+ *   const apiUrl = getEnvVar(config, 'VITE_API_URL')
+ *   return {
+ *     server: { port: vitePort, strictPort: true }
+ *   }
+ * })
+ * ```
+ */
+export function getEnvVar<
+	TServices extends Record<string, ServiceConfig>,
+	TApps extends Record<string, AppConfig>,
+>(
+	config: DevConfig<TServices, TApps>,
+	name: string,
+	options: { log?: boolean } = {},
+): string | number | undefined {
+	const { log = true } = options;
+	const offset = calculatePortOffset();
+	const localIp = getLocalIp();
+
+	// Compute ports and urls
+	const ports = computePorts(config.services, config.apps, offset);
+	const urls = computeUrls(config.services, config.apps, ports, localIp);
+
+	// Build env vars from the function
+	const envVars = config.envVars?.(
+		ports as Parameters<NonNullable<typeof config.envVars>>[0],
+		urls as Parameters<NonNullable<typeof config.envVars>>[1],
+		{
+			projectName: config.projectPrefix,
+			localIp,
+			portOffset: offset,
+		},
+	);
+
+	const value = envVars?.[name];
+
+	// Log frontend port for Vibe Kanban detection
+	if (log && name === "VITE_PORT" && typeof value === "number") {
+		logFrontendPort(value);
+	}
+
+	return value;
+}
+
+/**
+ * Log the API URL in a format that tools can detect.
+ * This is used by Expo and other tools to find the API server.
+ *
+ * @param url - The API URL
+ */
+export function logApiUrl(url: string): void {
+	console.log(`using_api_url:${url}`);
+}
+
+/**
+ * Log the Expo API URL in a format that tools can detect.
+ * This is typically the local IP address for mobile device connectivity.
+ *
+ * @param url - The Expo API URL (usually http://<local-ip>:<port>)
+ */
+export function logExpoApiUrl(url: string): void {
+	console.log(`using_expo_api_url:${url}`);
+}