buncargo 1.0.5

package/core/docker.ts

@@ -0,0 +1,384 @@
+import { execSync } from "node:child_process";
+import type {
+	BuiltInHealthCheck,
+	HealthCheckFn,
+	ServiceConfig,
+} from "../types";
+import { sleep } from "./utils";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const POLL_INTERVAL = 250; // Fast polling for quicker startup
+export const MAX_ATTEMPTS = 120; // 30 seconds total (120 * 250ms)
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Container Status Checks
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a specific container service is running using docker ps.
+ */
+export async function isContainerRunning(
+	project: string,
+	service: string,
+): Promise<boolean> {
+	try {
+		const result = execSync(
+			`docker ps --filter "label=com.docker.compose.project=${project}" --filter "label=com.docker.compose.service=${service}" --format "{{.State}}"`,
+			{ encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+		);
+		return result.trim() === "running";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if all expected containers are running.
+ */
+export async function areContainersRunning(
+	project: string,
+	minCount = 1,
+): Promise<boolean> {
+	try {
+		const result = execSync(
+			`docker ps --filter "label=com.docker.compose.project=${project}" --format "{{.State}}"`,
+			{ encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+		);
+		const states = result.trim().split("\n").filter(Boolean);
+		if (states.length < minCount) return false;
+		return states.every((state) => state === "running");
+	} catch {
+		return false;
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Container Lifecycle
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface StartContainersOptions {
+	verbose?: boolean;
+	wait?: boolean;
+	composeFile?: string;
+}
+
+/**
+ * Start Docker Compose containers.
+ */
+export function startContainers(
+	root: string,
+	projectName: string,
+	envVars: Record<string, string>,
+	options: StartContainersOptions = {},
+): void {
+	const { verbose = true, wait = true, composeFile } = options;
+
+	if (verbose) console.log("🐳 Starting Docker containers...");
+
+	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const waitFlag = wait ? "--wait" : "";
+	const cmd = `docker compose ${composeArg} up -d ${waitFlag}`.trim();
+
+	execSync(cmd, {
+		cwd: root,
+		env: { ...process.env, ...envVars, COMPOSE_PROJECT_NAME: projectName },
+		stdio: verbose ? "inherit" : "ignore",
+	});
+
+	if (verbose) console.log("✓ Containers started");
+}
+
+export interface StopContainersOptions {
+	verbose?: boolean;
+	removeVolumes?: boolean;
+	composeFile?: string;
+}
+
+/**
+ * Stop Docker Compose containers.
+ */
+export function stopContainers(
+	root: string,
+	projectName: string,
+	options: StopContainersOptions = {},
+): void {
+	const { verbose = true, removeVolumes = false, composeFile } = options;
+
+	if (verbose) {
+		console.log(
+			removeVolumes
+				? "🗑️  Stopping containers and removing volumes..."
+				: "🛑 Stopping containers...",
+		);
+	}
+
+	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const volumeFlag = removeVolumes ? "-v" : "";
+	const cmd = `docker compose ${composeArg} down ${volumeFlag}`.trim();
+
+	execSync(cmd, {
+		cwd: root,
+		env: { ...process.env, COMPOSE_PROJECT_NAME: projectName },
+		stdio: verbose ? "inherit" : "ignore",
+	});
+
+	if (verbose) console.log("✓ Containers stopped");
+}
+
+/**
+ * Start a specific service only.
+ */
+export function startService(
+	root: string,
+	projectName: string,
+	serviceName: string,
+	envVars: Record<string, string>,
+	options: { verbose?: boolean; composeFile?: string } = {},
+): void {
+	const { verbose = true, composeFile } = options;
+
+	if (verbose) console.log(`🐳 Starting ${serviceName}...`);
+
+	const composeArg = composeFile ? `-f ${composeFile}` : "";
+	const cmd = `docker compose ${composeArg} up -d ${serviceName}`.trim();
+
+	execSync(cmd, {
+		cwd: root,
+		env: { ...process.env, ...envVars, COMPOSE_PROJECT_NAME: projectName },
+		stdio: verbose ? "inherit" : "ignore",
+	});
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Built-in Health Checks
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface HealthCheckContext {
+	projectName?: string;
+	root?: string;
+}
+
+/**
+ * Create a health check function from a built-in type.
+ */
+export function createBuiltInHealthCheck(
+	type: BuiltInHealthCheck,
+	serviceName: string,
+	context: HealthCheckContext = {},
+): HealthCheckFn {
+	const { projectName, root } = context;
+
+	switch (type) {
+		case "pg_isready":
+			return async () => {
+				try {
+					const projectArg = projectName ? `-p ${projectName}` : "";
+					execSync(
+						`docker compose ${projectArg} exec -T ${serviceName} pg_isready -U postgres`,
+						{
+							cwd: root,
+							stdio: ["pipe", "pipe", "pipe"],
+						},
+					);
+					return true;
+				} catch {
+					return false;
+				}
+			};
+
+		case "redis-cli":
+			return async () => {
+				try {
+					const projectArg = projectName ? `-p ${projectName}` : "";
+					execSync(
+						`docker compose ${projectArg} exec -T ${serviceName} redis-cli ping`,
+						{
+							cwd: root,
+							stdio: ["pipe", "pipe", "pipe"],
+						},
+					);
+					return true;
+				} catch {
+					return false;
+				}
+			};
+
+		case "http":
+			return async (port) => {
+				try {
+					const controller = new AbortController();
+					const timeoutId = setTimeout(() => controller.abort(), 2000);
+					try {
+						const response = await fetch(`http://localhost:${port}/`, {
+							signal: controller.signal as RequestInit["signal"],
+						});
+						clearTimeout(timeoutId);
+						return response.ok || response.status === 404;
+					} catch {
+						clearTimeout(timeoutId);
+						return false;
+					}
+				} catch {
+					return false;
+				}
+			};
+
+		case "tcp":
+			return async (port) => {
+				// TCP check using a quick fetch that will fail fast if port is closed
+				try {
+					const controller = new AbortController();
+					const timeoutId = setTimeout(() => controller.abort(), 1000);
+					try {
+						await fetch(`http://localhost:${port}/`, {
+							signal: controller.signal as RequestInit["signal"],
+						});
+						clearTimeout(timeoutId);
+						return true;
+					} catch (error) {
+						clearTimeout(timeoutId);
+						// Connection refused means port is not open
+						// Other errors (like timeout) might mean it's open but not HTTP
+						if (
+							error instanceof Error &&
+							error.message.includes("ECONNREFUSED")
+						) {
+							return false;
+						}
+						return true; // Assume open for other errors
+					}
+				} catch {
+					return false;
+				}
+			};
+
+		default:
+			return async () => true;
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Service Readiness
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wait for a service to be healthy.
+ */
+export async function waitForService(
+	serviceName: string,
+	config: ServiceConfig,
+	port: number,
+	options: {
+		maxAttempts?: number;
+		pollInterval?: number;
+		projectName?: string;
+		root?: string;
+	} = {},
+): Promise<void> {
+	const {
+		maxAttempts = MAX_ATTEMPTS,
+		pollInterval = POLL_INTERVAL,
+		projectName,
+		root,
+	} = options;
+
+	// No health check configured - just return
+	if (config.healthCheck === false || config.healthCheck === undefined) {
+		return;
+	}
+
+	// Get or create health check function
+	const healthCheckFn =
+		typeof config.healthCheck === "function"
+			? config.healthCheck
+			: createBuiltInHealthCheck(
+					config.healthCheck,
+					config.serviceName ?? serviceName,
+					{ projectName, root },
+				);
+
+	for (let i = 0; i < maxAttempts; i++) {
+		const isHealthy = await healthCheckFn(port);
+		if (isHealthy) return;
+		await sleep(pollInterval);
+	}
+
+	throw new Error(`Service ${serviceName} did not become ready in time`);
+}
+
+/**
+ * Wait for all services to be healthy.
+ */
+export async function waitForAllServices(
+	services: Record<string, ServiceConfig>,
+	ports: Record<string, number>,
+	options: {
+		maxAttempts?: number;
+		pollInterval?: number;
+		verbose?: boolean;
+		projectName?: string;
+		root?: string;
+	} = {},
+): Promise<void> {
+	const { verbose = true, ...waitOptions } = options;
+
+	if (verbose) console.log("⏳ Waiting for services to be healthy...");
+
+	const promises = Object.entries(services).map(([name, config]) => {
+		const port = ports[name];
+		if (port === undefined) {
+			console.warn(
+				`⚠️  No port found for service ${name}, skipping health check`,
+			);
+			return Promise.resolve();
+		}
+		return waitForService(name, config, port, waitOptions);
+	});
+
+	await Promise.all(promises);
+
+	if (verbose) console.log("✓ All services healthy");
+}
+
+/**
+ * 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 async function waitForServiceByType(
+	serviceName: string,
+	healthCheckType: BuiltInHealthCheck,
+	port: number,
+	options: {
+		maxAttempts?: number;
+		pollInterval?: number;
+		verbose?: boolean;
+		projectName?: string;
+		root?: string;
+	} = {},
+): Promise<void> {
+	const {
+		maxAttempts = MAX_ATTEMPTS,
+		pollInterval = POLL_INTERVAL,
+		verbose = false,
+		projectName,
+		root,
+	} = options;
+	const healthCheckFn = createBuiltInHealthCheck(healthCheckType, serviceName, {
+		projectName,
+		root,
+	});
+
+	for (let i = 0; i < maxAttempts; i++) {
+		const isHealthy = await healthCheckFn(port);
+		if (isHealthy) {
+			if (verbose) console.log(`✓ ${serviceName} is ready`);
+			return;
+		}
+		await sleep(pollInterval);
+	}
+
+	throw new Error(`Service ${serviceName} did not become ready in time`);
+}

package/core/index.ts

@@ -0,0 +1,7 @@
+// Re-export all core utilities
+export * from "./docker";
+export * from "./network";
+export * from "./ports";
+export * from "./process";
+export * from "./utils";
+export * from "./watchdog";

package/core/network.ts

@@ -0,0 +1,152 @@
+import { networkInterfaces } from "node:os";
+import type { AppConfig } from "../types";
+import { sleep } from "./utils";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Local IP Detection
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Gets the local IP address of the machine for mobile device connectivity.
+ * Prefers IPv4 addresses on non-internal interfaces.
+ */
+export function getLocalIp(): string {
+	const interfaces = networkInterfaces();
+
+	for (const name of Object.keys(interfaces)) {
+		const nets = interfaces[name];
+		if (!nets) continue;
+
+		for (const net of nets) {
+			// Skip internal (loopback) addresses
+			if (net.family === "IPv4" && !net.internal) {
+				return net.address;
+			}
+		}
+	}
+
+	return "127.0.0.1";
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HTTP Health Checks
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface WaitForServerOptions {
+	/** Timeout in milliseconds */
+	timeout?: number;
+	/** Polling interval in milliseconds */
+	interval?: number;
+	/** Log progress */
+	verbose?: boolean;
+}
+
+/**
+ * Wait for an HTTP server to respond.
+ */
+export async function waitForServer(
+	url: string,
+	options: WaitForServerOptions = {},
+): Promise<void> {
+	const { timeout = 30000, interval = 2000, verbose = false } = options;
+
+	const start = Date.now();
+	let attempts = 0;
+
+	while (Date.now() - start < timeout) {
+		attempts++;
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), 5000);
+		try {
+			const response = await fetch(url, {
+				signal: controller.signal as RequestInit["signal"],
+			});
+			clearTimeout(timeoutId);
+			// Accept 2xx, 3xx, or 404 (server is up, just no route)
+			if (response.ok || response.status === 404) {
+				if (verbose) {
+					console.log(`   ✓ ${url} ready after ${attempts} attempts`);
+				}
+				return;
+			}
+		} catch {
+			clearTimeout(timeoutId);
+			// Server not ready yet
+			if (verbose && attempts % 5 === 0) {
+				console.log(
+					`   ⏳ Waiting for ${url}... (${Math.round((Date.now() - start) / 1000)}s)`,
+				);
+			}
+		}
+		await sleep(interval);
+	}
+
+	throw new Error(
+		`Server at ${url} did not respond within ${timeout}ms after ${attempts} attempts`,
+	);
+}
+
+/**
+ * Wait for all dev servers to be ready.
+ */
+export async function waitForDevServers(
+	apps: Record<string, AppConfig>,
+	ports: Record<string, number>,
+	options: {
+		timeout?: number;
+		verbose?: boolean;
+		productionBuild?: boolean;
+	} = {},
+): Promise<void> {
+	const { timeout = 60000, verbose = true } = options;
+
+	if (verbose) console.log("⏳ Waiting for servers to be ready...");
+
+	const promises: Promise<void>[] = [];
+
+	for (const [name, config] of Object.entries(apps)) {
+		const port = ports[name];
+		const healthPath = config.healthEndpoint ?? "/";
+		const url = `http://localhost:${port}${healthPath}`;
+		const appTimeout = config.healthTimeout ?? timeout;
+
+		promises.push(waitForServer(url, { timeout: appTimeout, verbose }));
+	}
+
+	await Promise.all(promises);
+
+	if (verbose) console.log("✓ All servers ready");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Port Availability
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a port is available (not in use).
+ */
+export async function isPortAvailable(port: number): Promise<boolean> {
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), 500);
+	try {
+		const _response = await fetch(`http://localhost:${port}/`, {
+			signal: controller.signal as RequestInit["signal"],
+		});
+		clearTimeout(timeoutId);
+		// If we get any response, port is in use
+		return false;
+	} catch (error) {
+		clearTimeout(timeoutId);
+		if (error instanceof Error) {
+			// Connection refused means port is free
+			if (
+				error.message.includes("ECONNREFUSED") ||
+				error.message.includes("fetch failed")
+			) {
+				return true;
+			}
+		}
+		// Timeout or other error - assume port is free
+		return true;
+	}
+}