buncargo 1.0.5

package/dist/core/watchdog.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Get the heartbeat file path for a project.
+ */
+export declare function getHeartbeatFile(projectName: string): string;
+/**
+ * Get the watchdog PID file path for a project.
+ */
+export declare function getWatchdogPidFile(projectName: string): string;
+/**
+ * Start writing heartbeat to file.
+ * The heartbeat is used by the watchdog to detect idle state.
+ */
+export declare function startHeartbeat(projectName: string, intervalMs?: number): void;
+/**
+ * Stop writing heartbeat.
+ */
+export declare function stopHeartbeat(): void;
+/**
+ * Read the last heartbeat timestamp.
+ */
+export declare function readHeartbeat(projectName: string): number | null;
+/**
+ * Remove the heartbeat file.
+ */
+export declare function removeHeartbeatFile(projectName: string): void;
+/**
+ * Check if watchdog is already running.
+ */
+export declare function isWatchdogRunning(projectName: string): boolean;
+/**
+ * Get the watchdog PID if running.
+ */
+export declare function getWatchdogPid(projectName: string): number | null;
+/**
+ * Spawn watchdog as a detached process.
+ * The watchdog monitors the heartbeat file and shuts down containers after idle timeout.
+ */
+export declare function spawnWatchdog(projectName: string, root: string, options?: {
+    timeoutMinutes?: number;
+    verbose?: boolean;
+    composeFile?: string;
+}): Promise<void>;
+/**
+ * Stop the watchdog process.
+ */
+export declare function stopWatchdog(projectName: string): void;

package/dist/environment.d.ts

@@ -0,0 +1,23 @@
+import type { AppConfig, DevConfig, DevEnvironment, ServiceConfig } from "./types";
+/**
+ * Create a dev environment from a configuration.
+ *
+ * @example
+ * ```typescript
+ * import { defineDevConfig, createDevEnvironment } from 'buncargo'
+ *
+ * const config = defineDevConfig({
+ *   projectPrefix: 'myapp',
+ *   services: { postgres: { port: 5432 } },
+ *   apps: { api: { port: 3000, devCommand: 'bun run dev' } }
+ * })
+ *
+ * export const dev = createDevEnvironment(config)
+ *
+ * // Usage
+ * await dev.start()
+ * ```
+ */
+export declare function createDevEnvironment<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(config: DevConfig<TServices, TApps>, options?: {
+    suffix?: string;
+}): DevEnvironment<TServices, TApps>;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { getFlagValue, hasFlag, runCli } from "./cli";
+export { assertValidConfig, defineDevConfig, mergeConfigs, validateConfig, } from "./config";
+export { createDevEnvironment } from "./environment";
+export { runWorkspaceTypecheck, type TypecheckResult, type WorkspaceTypecheckOptions, type WorkspaceTypecheckResult, } from "./lint";
+export { clearDevEnvCache, getDevEnv, loadDevEnv } from "./loader";
+export type { AppConfig, BuiltInHealthCheck, CliOptions, ComputedPorts, ComputedUrls, DevConfig, DevEnvironment, DevHooks, DevOptions, DevServerPids, EnvVarsBuilder, ExecOptions, HealthCheckFn, HookContext, MigrationConfig, PrismaConfig, PrismaRunner, SeedCheckContext, SeedCheckHelpers, SeedConfig, ServiceConfig, StartOptions, StopOptions, UrlBuilderContext, UrlBuilderFn, } from "./types";
+export { areContainersRunning, isContainerRunning, MAX_ATTEMPTS, POLL_INTERVAL, } from "./core/docker";
+export { getLocalIp, isPortAvailable, waitForServer } from "./core/network";
+export { calculatePortOffset, findMonorepoRoot, getProjectName, getWorktreeName, isWorktree, } from "./core/ports";
+export { isProcessAlive } from "./core/process";
+export { getEnvVar, isCI, logApiUrl, logExpoApiUrl, logFrontendPort, sleep, } from "./core/utils";
+export { getHeartbeatFile, getWatchdogPidFile, isWatchdogRunning, spawnWatchdog, startHeartbeat, stopHeartbeat, stopWatchdog, } from "./core/watchdog";

package/dist/lint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Options for running workspace typechecks.
+ */
+export interface WorkspaceTypecheckOptions {
+    /** Root directory to search from (defaults to cwd) */
+    root?: string;
+    /** Glob patterns for workspaces to check (defaults to apps/*, packages/*, modules) */
+    patterns?: string[];
+    /** Maximum concurrent typecheck processes (defaults to 1) */
+    concurrency?: number;
+    /** Print output to console (defaults to true) */
+    verbose?: boolean;
+}
+/**
+ * Result of a single workspace typecheck.
+ */
+export interface WorkspaceTypecheckResult {
+    workspace: string;
+    duration: number;
+    success: boolean;
+    fileCount: number;
+    errorOutput?: string;
+}
+/**
+ * Overall result of running typechecks across all workspaces.
+ */
+export interface TypecheckResult {
+    success: boolean;
+    totalDuration: number;
+    totalFiles: number;
+    workspaceCount: number;
+    results: WorkspaceTypecheckResult[];
+}
+/**
+ * Run TypeScript typechecks across all workspaces that have a `typecheck` script.
+ *
+ * @example
+ * ```typescript
+ * const result = await runWorkspaceTypecheck({ verbose: true })
+ * if (!result.success) {
+ *   console.error('Typecheck failed')
+ *   process.exit(1)
+ * }
+ * ```
+ */
+export declare function runWorkspaceTypecheck(options?: WorkspaceTypecheckOptions): Promise<TypecheckResult>;

package/dist/loader.d.ts

@@ -0,0 +1,39 @@
+import type { AppConfig, DevEnvironment, ServiceConfig } from "./types";
+/**
+ * Load the dev environment from the config file.
+ * Caches the result for subsequent calls.
+ *
+ * @example
+ * ```typescript
+ * import { loadDevEnv } from 'buncargo'
+ *
+ * const env = await loadDevEnv()
+ * console.log(env.ports.postgres)  // 5432 (or offset port)
+ * console.log(env.urls.api)        // http://localhost:3000
+ * ```
+ */
+export declare function loadDevEnv(options?: {
+    /** Directory to search for config file. Defaults to process.cwd() */
+    cwd?: string;
+    /** Skip cache and reload config */
+    reload?: boolean;
+}): Promise<DevEnvironment<Record<string, ServiceConfig>, Record<string, AppConfig>>>;
+/**
+ * Get the cached dev environment synchronously.
+ * Throws if loadDevEnv() hasn't been called yet.
+ *
+ * @example
+ * ```typescript
+ * // First load async
+ * await loadDevEnv()
+ *
+ * // Then use sync getter anywhere
+ * import { getDevEnv } from 'buncargo'
+ * const env = getDevEnv()
+ * ```
+ */
+export declare function getDevEnv(): DevEnvironment<Record<string, ServiceConfig>, Record<string, AppConfig>>;
+/**
+ * Clear the cached environment.
+ */
+export declare function clearDevEnvCache(): void;

package/dist/prisma.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Prisma integration for dev-tools-v2.
+ *
+ * When `prisma` is configured in defineDevConfig, `dev.prisma` becomes available
+ * with methods to run prisma commands against the Docker development database.
+ *
+ * @example
+ * ```typescript
+ * // In dev.config.ts
+ * const config = defineDevConfig({
+ *   projectPrefix: 'myapp',
+ *   services: { postgres: { port: 5432, healthCheck: 'pg_isready' } },
+ *   prisma: { cwd: 'packages/prisma' }  // Enable prisma integration
+ * })
+ *
+ * // Usage
+ * await dev.prisma.run(['migrate', 'dev'])
+ * await dev.prisma.ensureDatabase()
+ * const url = dev.prisma.getDatabaseUrl()
+ * ```
+ *
+ * @internal This module is used internally by createDevEnvironment.
+ */
+import type { AppConfig, DevEnvironment, PrismaConfig, PrismaRunner, ServiceConfig } from "./types";
+/**
+ * Create a Prisma runner from config (used internally by createDevEnvironment).
+ * @internal
+ */
+export declare function createPrismaRunner<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>>(env: DevEnvironment<TServices, TApps>, config: PrismaConfig): PrismaRunner;

package/dist/types.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Health check function signature for custom health checks.
+ */
+export type HealthCheckFn = (port: number) => Promise<boolean>;
+/**
+ * Built-in health check types that map to common patterns.
+ */
+export type BuiltInHealthCheck = "pg_isready" | "redis-cli" | "http" | "tcp";
+/**
+ * URL builder context passed to urlTemplate function.
+ */
+export interface UrlBuilderContext {
+    port: number;
+    secondaryPort?: number;
+    host: string;
+    localIp: string;
+}
+/**
+ * URL builder function receives port info and returns the connection URL.
+ */
+export type UrlBuilderFn = (ctx: UrlBuilderContext) => string;
+/**
+ * Configuration for a Docker Compose service (e.g., postgres, redis).
+ */
+export interface ServiceConfig {
+    /** Base port for the service (before offset is applied) */
+    port: number;
+    /** Optional secondary port (e.g., ClickHouse native protocol) */
+    secondaryPort?: number;
+    /** Health check: built-in name, custom function, or disabled (false) */
+    healthCheck?: BuiltInHealthCheck | HealthCheckFn | false;
+    /** URL builder function that returns the connection URL */
+    urlTemplate?: UrlBuilderFn;
+    /** Docker Compose service name (defaults to the key name) */
+    serviceName?: string;
+    /** Database name (for postgres, mysql, clickhouse). Enables built-in URL template. */
+    database?: string;
+    /** Username (default: 'postgres' for postgres, 'root' for mysql, 'default' for clickhouse) */
+    user?: string;
+    /** Password (default: 'postgres' for postgres, 'root' for mysql, 'clickhouse' for clickhouse) */
+    password?: string;
+}
+/**
+ * Configuration for an application (e.g., api, web).
+ */
+export interface AppConfig {
+    /** Base port for the app (before offset is applied) */
+    port: number;
+    /** Command to start the dev server */
+    devCommand: string;
+    /** Command to start production server (optional) */
+    prodCommand?: string;
+    /** Command to build for production (optional) */
+    buildCommand?: string;
+    /** Working directory relative to monorepo root */
+    cwd?: string;
+    /** Health check endpoint path (e.g., '/api/health') */
+    healthEndpoint?: string;
+    /** Timeout for health check in milliseconds */
+    healthTimeout?: number;
+}
+/**
+ * Execution options for the exec helper.
+ */
+export interface ExecOptions {
+    /** Working directory relative to monorepo root */
+    cwd?: string;
+    /** Print output to console */
+    verbose?: boolean;
+    /** Environment variables to add */
+    env?: Record<string, string>;
+    /** Throw on non-zero exit code (default: true) */
+    throwOnError?: boolean;
+}
+/**
+ * Context passed to hooks for executing commands and accessing environment.
+ */
+export interface HookContext<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> {
+    /** Project name (with suffix if applicable) */
+    projectName: string;
+    /** Computed ports for all services and apps */
+    ports: ComputedPorts<TServices, TApps>;
+    /** Computed URLs for all services and apps */
+    urls: ComputedUrls<TServices, TApps>;
+    /** Execute a shell command with environment variables set */
+    exec: (cmd: string, options?: ExecOptions) => Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Path to monorepo root */
+    root: string;
+    /** Whether running in CI environment */
+    isCI: boolean;
+    /** Port offset applied to all ports */
+    portOffset: number;
+    /** Local IP address for mobile connectivity */
+    localIp: string;
+}
+/**
+ * Lifecycle hooks for customizing the dev environment.
+ */
+export interface DevHooks<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> {
+    /** Called after all containers are healthy */
+    afterContainersReady?: (ctx: HookContext<TServices, TApps>) => Promise<void>;
+    /** Called before starting dev servers */
+    beforeServers?: (ctx: HookContext<TServices, TApps>) => Promise<void>;
+    /** Called after dev servers are ready */
+    afterServers?: (ctx: HookContext<TServices, TApps>) => Promise<void>;
+    /** Called before stopping the environment */
+    beforeStop?: (ctx: HookContext<TServices, TApps>) => Promise<void>;
+}
+/**
+ * Configuration for Prisma integration.
+ */
+export interface PrismaConfig {
+    /** Working directory where prisma schema lives (relative to monorepo root). Default: 'packages/prisma' */
+    cwd?: string;
+    /** Docker Compose service name for the database. Default: 'postgres' */
+    service?: string;
+    /** Environment variable name for the database URL. Default: 'DATABASE_URL' */
+    urlEnvVar?: string;
+}
+/**
+ * Prisma runner interface available on dev.prisma when prisma is configured.
+ */
+export interface PrismaRunner {
+    /** Run a prisma command with the correct environment. Returns exit code. */
+    run(args: string[]): Promise<number>;
+    /** Get the database URL from the dev environment */
+    getDatabaseUrl(): string;
+    /** Ensure the database container is running and healthy */
+    ensureDatabase(): Promise<void>;
+}
+/**
+ * Configuration for a migration command to run after containers are ready.
+ */
+export interface MigrationConfig {
+    /** Display name for the migration (e.g., 'prisma', 'clickhouse') */
+    name: string;
+    /** Command to run the migration */
+    command: string;
+    /** Working directory relative to monorepo root */
+    cwd?: string;
+}
+/**
+ * Helper functions available in the seed check function.
+ */
+export interface SeedCheckHelpers<TServices extends Record<string, ServiceConfig>> {
+    /**
+     * Check if a database table is empty.
+     * Returns true if the table has 0 rows (needs seeding), false otherwise.
+     *
+     * @param tableName - The table name to check (e.g., 'User')
+     * @param service - The database service name. Default: 'postgres'
+     *
+     * @example
+     * ```typescript
+     * seed: {
+     *   command: 'bun run run:seeder',
+     *   check: ({ checkTable }) => checkTable('User')
+     * }
+     * ```
+     */
+    checkTable: (tableName: string, service: keyof TServices) => Promise<boolean>;
+}
+/**
+ * Context passed to the seed check function.
+ */
+export type SeedCheckContext<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> = HookContext<TServices, TApps> & SeedCheckHelpers<TServices>;
+/**
+ * Configuration for database seeding.
+ */
+export interface SeedConfig<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> {
+    /** Command to run the seeder */
+    command: string;
+    /** Working directory relative to monorepo root */
+    cwd?: string;
+    /**
+     * Check function to determine if seeding is needed.
+     * Return true to run the seed command, false to skip.
+     * If not provided, seeding always runs.
+     *
+     * Receives hook context plus helper functions like `checkTable`.
+     *
+     * @example
+     * ```typescript
+     * seed: {
+     *   command: 'bun run run:seeder',
+     *   check: ({ checkTable }) => checkTable('User')
+     * }
+     * ```
+     */
+    check?: (ctx: SeedCheckContext<TServices, TApps>) => Promise<boolean>;
+}
+/**
+ * Options for the dev environment.
+ */
+export interface DevOptions {
+    /** Enable worktree isolation (unique ports per worktree). Default: true */
+    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;
+}
+/**
+ * Environment variable builder function.
+ */
+export type EnvVarsBuilder<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> = (ports: ComputedPorts<TServices, TApps>, urls: ComputedUrls<TServices, TApps>, ctx: {
+    projectName: string;
+    localIp: string;
+    portOffset: number;
+}) => Record<string, string | number>;
+/**
+ * Main configuration for the dev environment.
+ */
+export interface DevConfig<TServices extends Record<string, ServiceConfig> = Record<string, ServiceConfig>, TApps extends Record<string, AppConfig> = Record<string, AppConfig>> {
+    /** 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;
+}
+/**
+ * Computed ports object - maps service/app names to their port numbers.
+ */
+type ServicesWithSecondaryPort<TServices extends Record<string, ServiceConfig>> = {
+    [K in keyof TServices as TServices[K] extends {
+        secondaryPort: number;
+    } ? `${K & string}Secondary` : never]: number;
+};
+export type ComputedPorts<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> = {
+    [K in keyof TServices]: number;
+} & {
+    [K in keyof TApps]: number;
+} & ServicesWithSecondaryPort<TServices>;
+/**
+ * Computed URLs object - maps service/app names to their URLs.
+ */
+export type ComputedUrls<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> = {
+    [K in keyof TServices]: string;
+} & {
+    [K in keyof TApps]: string;
+};
+/**
+ * Options for starting the dev environment.
+ */
+export interface StartOptions {
+    /** Print output to console. Default: true */
+    verbose?: boolean;
+    /** Wait for containers to be healthy. Default: true */
+    wait?: boolean;
+    /** Start dev servers after containers. Default: true */
+    startServers?: boolean;
+    /** Use production build for servers. Default: false (true in CI) */
+    productionBuild?: boolean;
+    /** Environment suffix for isolation (e.g., 'test'). Default: undefined */
+    suffix?: string;
+}
+/**
+ * Options for stopping the dev environment.
+ */
+export interface StopOptions {
+    /** Print output to console. Default: true */
+    verbose?: boolean;
+    /** Remove Docker volumes (destroys data). Default: false */
+    removeVolumes?: boolean;
+}
+/**
+ * Process IDs for running dev servers.
+ */
+export interface DevServerPids {
+    [appName: string]: number;
+}
+/**
+ * The main dev environment interface returned by createDevEnvironment().
+ */
+export interface DevEnvironment<TServices extends Record<string, ServiceConfig>, TApps extends Record<string, AppConfig>> {
+    /** Docker project name (includes suffix if set) */
+    readonly projectName: string;
+    /** Computed ports for all services and apps */
+    readonly ports: ComputedPorts<TServices, TApps>;
+    /** Computed URLs for all services and apps */
+    readonly urls: ComputedUrls<TServices, TApps>;
+    /** Apps configuration (for CLI to build commands) */
+    readonly apps: TApps;
+    /** Port offset applied (0 for main, > 0 for worktrees) */
+    readonly portOffset: number;
+    /** Whether running in a git worktree */
+    readonly isWorktree: boolean;
+    /** Local IP address for mobile connectivity */
+    readonly localIp: string;
+    /** Path to monorepo root */
+    readonly root: string;
+    /** Start the dev environment (containers + optional servers) */
+    start(options?: StartOptions): Promise<DevServerPids | null>;
+    /** Stop the dev environment */
+    stop(options?: StopOptions): Promise<void>;
+    /** Restart containers only */
+    restart(): Promise<void>;
+    /** Check if containers are running */
+    isRunning(): Promise<boolean>;
+    /** Start dev servers only (assumes containers are running) */
+    startServers(options?: {
+        productionBuild?: boolean;
+        verbose?: boolean;
+    }): Promise<DevServerPids>;
+    /** Stop a process by PID */
+    stopProcess(pid: number): void;
+    /** Wait for servers to be ready */
+    waitForServers(options?: {
+        timeout?: number;
+        productionBuild?: boolean;
+    }): Promise<void>;
+    /** Build environment variables for shell commands */
+    buildEnvVars(production?: boolean): Record<string, string>;
+    /** Execute a command with environment variables set */
+    exec(cmd: string, options?: ExecOptions): 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;
+    /**
+     * Get the Expo API URL (http://<local-ip>:<api-port>) and log it for detection.
+     * Used by tools like Vibe Kanban to find the API server for mobile testing.
+     */
+    getExpoApiUrl(): string;
+    /**
+     * Get the frontend port and log it for detection.
+     * Used by tools like Vibe Kanban to find the dev server.
+     */
+    getFrontendPort(): number | undefined;
+    /** Start writing heartbeat for watchdog */
+    startHeartbeat(intervalMs?: number): void;
+    /** Stop writing heartbeat */
+    stopHeartbeat(): void;
+    /** Spawn watchdog process for auto-shutdown */
+    spawnWatchdog(timeoutMinutes?: number): Promise<void>;
+    /** Stop the watchdog process */
+    stopWatchdog(): void;
+    /** Prisma runner (only available when prisma is configured) */
+    readonly prisma?: PrismaRunner;
+    /** Create a new environment with a different suffix (for test isolation) */
+    withSuffix(suffix: string): DevEnvironment<TServices, TApps>;
+}
+/**
+ * Options for the CLI runner.
+ */
+export interface CliOptions {
+    /** Custom args (defaults to process.argv.slice(2)) */
+    args?: string[];
+    /** Enable watchdog auto-shutdown (default: true) */
+    watchdog?: boolean;
+    /** Watchdog timeout in minutes (default: 10) */
+    watchdogTimeout?: number;
+    /** Command to run dev servers (e.g., 'bun concurrently ...') */
+    devServersCommand?: string;
+}
+export {};