buncargo 1.0.5

package/core/watchdog-runner.ts

@@ -0,0 +1,111 @@
+/**
+ * Watchdog Runner
+ *
+ * Monitors heartbeat file and shuts down containers after inactivity.
+ * Spawned as a detached process by the dev environment.
+ *
+ * Environment variables:
+ *   WATCHDOG_PROJECT_NAME - Docker project name
+ *   WATCHDOG_HEARTBEAT_FILE - Path to heartbeat file
+ *   WATCHDOG_PID_FILE - Path to PID file
+ *   WATCHDOG_TIMEOUT_MS - Idle timeout in milliseconds
+ *   WATCHDOG_COMPOSE_ARG - Optional docker compose argument (e.g., "-f compose.yml")
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+
+// Configuration from environment
+const PROJECT_NAME = process.env.WATCHDOG_PROJECT_NAME ?? "";
+const HEARTBEAT_FILE = process.env.WATCHDOG_HEARTBEAT_FILE ?? "";
+const PID_FILE = process.env.WATCHDOG_PID_FILE ?? "";
+const IDLE_TIMEOUT = parseInt(process.env.WATCHDOG_TIMEOUT_MS ?? "600000", 10);
+const COMPOSE_ARG = process.env.WATCHDOG_COMPOSE_ARG ?? "";
+const CHECK_INTERVAL = 60_000; // Check every minute
+
+// Validate configuration
+if (!PROJECT_NAME || !HEARTBEAT_FILE || !PID_FILE) {
+	console.error("[watchdog] Missing required environment variables");
+	process.exit(1);
+}
+
+// Type assertion after validation
+const heartbeatFile: string = HEARTBEAT_FILE;
+const pidFile: string = PID_FILE;
+
+// Write PID file
+writeFileSync(pidFile, process.pid.toString());
+
+// Cleanup function
+function cleanup(): void {
+	try {
+		unlinkSync(pidFile);
+	} catch {
+		// File may not exist
+	}
+	try {
+		unlinkSync(heartbeatFile);
+	} catch {
+		// File may not exist
+	}
+}
+
+// Handle signals
+process.on("SIGTERM", () => {
+	cleanup();
+	process.exit(0);
+});
+
+process.on("SIGINT", () => {
+	cleanup();
+	process.exit(0);
+});
+
+console.log(`[watchdog] Started for ${PROJECT_NAME} (PID: ${process.pid})`);
+console.log(`[watchdog] Idle timeout: ${IDLE_TIMEOUT / 60000} minutes`);
+
+// Main watchdog loop
+async function watchdog(): Promise<void> {
+	while (true) {
+		await new Promise((r) => setTimeout(r, CHECK_INTERVAL));
+
+		// Check if heartbeat file exists
+		if (!existsSync(heartbeatFile)) {
+			continue;
+		}
+
+		// Read last heartbeat timestamp
+		let lastBeat: number;
+		try {
+			const content = readFileSync(heartbeatFile, "utf-8");
+			lastBeat = parseInt(content, 10);
+		} catch {
+			continue;
+		}
+
+		if (Number.isNaN(lastBeat)) {
+			continue;
+		}
+
+		const elapsed = Date.now() - lastBeat;
+
+		if (elapsed > IDLE_TIMEOUT) {
+			console.log(
+				`[watchdog] No heartbeat for ${Math.ceil(elapsed / 60000)} minutes, shutting down...`,
+			);
+			try {
+				execSync(`docker compose ${COMPOSE_ARG} down`.trim(), {
+					env: { ...process.env, COMPOSE_PROJECT_NAME: PROJECT_NAME },
+					stdio: "ignore",
+				});
+			} catch {
+				// Ignore errors
+			}
+			console.log("[watchdog] Containers stopped");
+			cleanup();
+			process.exit(0);
+		}
+	}
+}
+
+watchdog();

package/core/watchdog.ts

@@ -0,0 +1,196 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { isProcessAlive } from "./process";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// File Paths
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get the heartbeat file path for a project.
+ */
+export function getHeartbeatFile(projectName: string): string {
+	return `/tmp/${projectName}-heartbeat`;
+}
+
+/**
+ * Get the watchdog PID file path for a project.
+ */
+export function getWatchdogPidFile(projectName: string): string {
+	return `/tmp/${projectName}-watchdog.pid`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Heartbeat
+// ═══════════════════════════════════════════════════════════════════════════
+
+let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Start writing heartbeat to file.
+ * The heartbeat is used by the watchdog to detect idle state.
+ */
+export function startHeartbeat(projectName: string, intervalMs = 30_000): void {
+	const heartbeatFile = getHeartbeatFile(projectName);
+
+	// Write initial heartbeat
+	writeFileSync(heartbeatFile, Date.now().toString());
+
+	// Update heartbeat at interval
+	heartbeatInterval = setInterval(() => {
+		writeFileSync(heartbeatFile, Date.now().toString());
+	}, intervalMs);
+}
+
+/**
+ * Stop writing heartbeat.
+ */
+export function stopHeartbeat(): void {
+	if (heartbeatInterval) {
+		clearInterval(heartbeatInterval);
+		heartbeatInterval = null;
+	}
+}
+
+/**
+ * Read the last heartbeat timestamp.
+ */
+export function readHeartbeat(projectName: string): number | null {
+	const heartbeatFile = getHeartbeatFile(projectName);
+	try {
+		if (!existsSync(heartbeatFile)) return null;
+		const content = readFileSync(heartbeatFile, "utf-8");
+		const timestamp = parseInt(content, 10);
+		return Number.isNaN(timestamp) ? null : timestamp;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Remove the heartbeat file.
+ */
+export function removeHeartbeatFile(projectName: string): void {
+	const heartbeatFile = getHeartbeatFile(projectName);
+	try {
+		unlinkSync(heartbeatFile);
+	} catch {
+		// File may not exist
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Watchdog
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if watchdog is already running.
+ */
+export function isWatchdogRunning(projectName: string): boolean {
+	const pidFile = getWatchdogPidFile(projectName);
+	try {
+		if (!existsSync(pidFile)) return false;
+		const content = readFileSync(pidFile, "utf-8");
+		const pid = parseInt(content, 10);
+		if (Number.isNaN(pid)) return false;
+		return isProcessAlive(pid);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Get the watchdog PID if running.
+ */
+export function getWatchdogPid(projectName: string): number | null {
+	const pidFile = getWatchdogPidFile(projectName);
+	try {
+		if (!existsSync(pidFile)) return null;
+		const content = readFileSync(pidFile, "utf-8");
+		const pid = parseInt(content, 10);
+		if (Number.isNaN(pid)) return null;
+		if (!isProcessAlive(pid)) return null;
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Spawn watchdog as a detached process.
+ * The watchdog monitors the heartbeat file and shuts down containers after idle timeout.
+ */
+export async function spawnWatchdog(
+	projectName: string,
+	root: string,
+	options: {
+		timeoutMinutes?: number;
+		verbose?: boolean;
+		composeFile?: string;
+	} = {},
+): Promise<void> {
+	const { timeoutMinutes = 10, verbose = true, composeFile } = options;
+
+	// Check if watchdog is already running
+	const existingPid = getWatchdogPid(projectName);
+	if (existingPid) {
+		if (verbose)
+			console.log(`✓ Watchdog already running (PID: ${existingPid})`);
+		return;
+	}
+
+	// Remove stale PID file if exists
+	const pidFile = getWatchdogPidFile(projectName);
+	try {
+		unlinkSync(pidFile);
+	} catch {
+		// File may not exist
+	}
+
+	// Get the path to the watchdog runner script
+	const watchdogScript = new URL("./watchdog-runner.ts", import.meta.url)
+		.pathname;
+
+	// Spawn watchdog as a separate process
+	const proc = spawn("bun", ["run", watchdogScript], {
+		cwd: root,
+		detached: true,
+		stdio: "ignore",
+		env: {
+			...process.env,
+			WATCHDOG_PROJECT_NAME: projectName,
+			WATCHDOG_HEARTBEAT_FILE: getHeartbeatFile(projectName),
+			WATCHDOG_PID_FILE: pidFile,
+			WATCHDOG_TIMEOUT_MS: String(timeoutMinutes * 60 * 1000),
+			WATCHDOG_COMPOSE_ARG: composeFile ? `-f ${composeFile}` : "",
+		},
+	});
+
+	proc.unref();
+
+	if (verbose && proc.pid) {
+		console.log(`✓ Watchdog started (PID: ${proc.pid})`);
+	}
+}
+
+/**
+ * Stop the watchdog process.
+ */
+export function stopWatchdog(projectName: string): void {
+	const pid = getWatchdogPid(projectName);
+	if (pid) {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch {
+			// Process may already be dead
+		}
+	}
+
+	// Clean up files
+	const pidFile = getWatchdogPidFile(projectName);
+	try {
+		unlinkSync(pidFile);
+	} catch {
+		// File may not exist
+	}
+}

package/dist/bin.d.ts

@@ -0,0 +1,12 @@
+#!/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
+ */
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+import type { AppConfig, CliOptions, DevEnvironment, ServiceConfig } from "./types";
+/**
+ * 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 declare function runCli<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(env: DevEnvironment<TServices, TApps>, options?: CliOptions): Promise<void>;
+/**
+ * Check if a CLI flag is present.
+ */
+export declare function hasFlag(args: string[], flag: string): boolean;
+/**
+ * Get a flag value (e.g., --timeout=10 or --timeout 10).
+ */
+export declare function getFlagValue(args: string[], flag: string): string | undefined;

package/dist/config.d.ts

@@ -0,0 +1,72 @@
+import type { AppConfig, DevConfig, DevHooks, DevOptions, EnvVarsBuilder, MigrationConfig, PrismaConfig, SeedConfig, ServiceConfig } from "./types";
+/**
+ * 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 declare 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>;
+/**
+ * Validate a dev config and return any errors.
+ */
+export declare function validateConfig<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>): string[];
+/**
+ * Validate config and throw if invalid.
+ */
+export declare function assertValidConfig<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>): void;
+/**
+ * Merge two configs, with the second taking precedence.
+ */
+export declare function mergeConfigs<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(base: DevConfig<TServices, TApps>, overrides: Partial<DevConfig<TServices, TApps>>): DevConfig<TServices, TApps>;
+/**
+ * Create a partial config that can be merged later.
+ */
+export declare 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>>;

package/dist/core/docker.d.ts

@@ -0,0 +1,74 @@
+import type { BuiltInHealthCheck, HealthCheckFn, ServiceConfig } from "../types";
+export declare const POLL_INTERVAL = 250;
+export declare const MAX_ATTEMPTS = 120;
+/**
+ * Check if a specific container service is running using docker ps.
+ */
+export declare function isContainerRunning(project: string, service: string): Promise<boolean>;
+/**
+ * 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;
+}
+/**
+ * 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/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./docker";
+export * from "./network";
+export * from "./ports";
+export * from "./process";
+export * from "./utils";
+export * from "./watchdog";

package/dist/core/network.d.ts

@@ -0,0 +1,30 @@
+import type { AppConfig } from "../types";
+/**
+ * Gets the local IP address of the machine for mobile device connectivity.
+ * Prefers IPv4 addresses on non-internal interfaces.
+ */
+export declare function getLocalIp(): string;
+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 declare function waitForServer(url: string, options?: WaitForServerOptions): Promise<void>;
+/**
+ * Wait for all dev servers to be ready.
+ */
+export declare function waitForDevServers(apps: Record<string, AppConfig>, ports: Record<string, number>, options?: {
+    timeout?: number;
+    verbose?: boolean;
+    productionBuild?: boolean;
+}): Promise<void>;
+/**
+ * Check if a port is available (not in use).
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;

package/dist/core/ports.d.ts

@@ -0,0 +1,30 @@
+import type { AppConfig, ServiceConfig } from "../types";
+/**
+ * Find the monorepo root by looking for package.json with workspaces.
+ */
+export declare function findMonorepoRoot(startDir?: string): string;
+/**
+ * Get the worktree name from .git file (if in a worktree).
+ */
+export declare function getWorktreeName(root?: string): string | null;
+/**
+ * Check if the current directory is a git worktree.
+ */
+export declare function isWorktree(root?: string): boolean;
+/**
+ * Calculate port offset based on worktree name and optional suffix.
+ * Returns 0 for main branch, 10-99 for worktrees.
+ */
+export declare function calculatePortOffset(suffix?: string, root?: string): number;
+/**
+ * Generate Docker project name from prefix and directory.
+ */
+export declare function getProjectName(prefix: string, suffix?: string, root?: string): string;
+/**
+ * Compute all ports for services and apps with offset applied.
+ */
+export declare function computePorts<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(services: TServices, apps: TApps | undefined, offset: number): Record<string, number>;
+/**
+ * Compute URLs for all services and apps.
+ */
+export declare 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>;

package/dist/core/process.d.ts

@@ -0,0 +1,52 @@
+import { type ChildProcess } from "node:child_process";
+import type { AppConfig, DevServerPids, ExecOptions } from "../types";
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Execute a shell command with environment variables.
+ */
+export declare function exec(cmd: string, root: string, envVars: Record<string, string>, options?: ExecOptions): ExecResult;
+/**
+ * Execute a shell command asynchronously.
+ */
+export declare function execAsync(cmd: string, root: string, envVars: Record<string, string>, options?: ExecOptions): Promise<ExecResult>;
+export interface SpawnDevServerOptions {
+    verbose?: boolean;
+    detached?: boolean;
+    isCI?: boolean;
+}
+/**
+ * Spawn a dev server as a detached process.
+ */
+export declare function spawnDevServer(command: string, root: string, appCwd: string | undefined, envVars: Record<string, string>, options?: SpawnDevServerOptions): ChildProcess;
+/**
+ * Start all configured dev servers.
+ */
+export declare function startDevServers(apps: Record<string, AppConfig>, root: string, envVars: Record<string, string>, options?: {
+    verbose?: boolean;
+    productionBuild?: boolean;
+    isCI?: boolean;
+}): DevServerPids;
+/**
+ * Stop a process by PID.
+ */
+export declare function stopProcess(pid: number): void;
+/**
+ * Stop all processes by their PIDs.
+ */
+export declare function stopAllProcesses(pids: DevServerPids, options?: {
+    verbose?: boolean;
+}): void;
+/**
+ * Check if a process is alive by sending signal 0.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Run production build for apps that have buildCommand configured.
+ */
+export declare function buildApps(apps: Record<string, AppConfig>, root: string, envVars: Record<string, string>, options?: {
+    verbose?: boolean;
+}): void;

package/dist/core/utils.d.ts

@@ -0,0 +1,60 @@
+import type { AppConfig, DevConfig, ServiceConfig } from "../types";
+/**
+ * Core utility functions shared across modules.
+ */
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Detect if running in a CI environment.
+ */
+export declare function isCI(): boolean;
+/**
+ * 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 declare function logFrontendPort(port: number | undefined): void;
+/**
+ * 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 declare function getEnvVar<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>, name: string, options?: {
+    log?: boolean;
+}): string | number | undefined;
+/**
+ * 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 declare function logApiUrl(url: string): void;
+/**
+ * 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 declare function logExpoApiUrl(url: string): void;

package/dist/core/watchdog-runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Watchdog Runner
+ *
+ * Monitors heartbeat file and shuts down containers after inactivity.
+ * Spawned as a detached process by the dev environment.
+ *
+ * Environment variables:
+ *   WATCHDOG_PROJECT_NAME - Docker project name
+ *   WATCHDOG_HEARTBEAT_FILE - Path to heartbeat file
+ *   WATCHDOG_PID_FILE - Path to PID file
+ *   WATCHDOG_TIMEOUT_MS - Idle timeout in milliseconds
+ *   WATCHDOG_COMPOSE_ARG - Optional docker compose argument (e.g., "-f compose.yml")
+ */
+export {};