buncargo 1.0.29 → 3.2.0

package/readme.md

@@ -1,110 +1,224 @@
 # Buncargo
 
-Type-safe development environment CLI for Docker Compose-based projects. Handles container lifecycle, port isolation for git worktrees, and dev server orchestration. It's easy!
+A Bun-first development environment toolkit that eliminates the friction of local dev setup. Define your entire dev stack in a single typed config file—Docker services, app servers, environment variables, migrations, and more.
+
+## Why Buncargo?
+
+**The problem**: Local development environments are fragile. Teams maintain separate `docker-compose.yml` files, scatter port assignments across `.env` files, manually manage container lifecycles, and struggle with port conflicts when working on multiple branches.
+
+**The solution**: Buncargo provides a single source of truth for your dev environment. One `dev.config.ts` file defines everything. Type-safe. Auto-generated Docker Compose. Worktree-aware port isolation. Zero configuration drift.
+
+## Key Features
+
+- **Single config file** — Define services, apps, ports, URLs, migrations, and hooks in one typed `dev.config.ts`
+- **Auto-generated Docker Compose** — No manual compose files; buncargo generates them from your config
+- **Worktree isolation** — Each git worktree gets unique ports and isolated containers automatically
+- **Built-in service presets** — One-liner setup for Postgres, Redis, ClickHouse with health checks and URL templates
+- **Custom service support** — Full Docker Compose escape hatch for any service
+- **Dev server orchestration** — Start and monitor multiple app servers with health checks
+- **Public tunnels** — Expose services via Cloudflare Quick Tunnels for webhook testing and mobile dev
+- **Prisma integration** — Run Prisma commands with auto-injected `DATABASE_URL`
+- **Lifecycle hooks** — Run migrations, seeders, or custom scripts at the right time
+- **Programmatic API** — Access ports/URLs in tests or scripts
+- **Watchdog auto-shutdown** — Containers stop automatically after inactivity
 
 ## Quick Start
 
-### 1. Create `dev.config.ts` in your project root
+### 1. Install
+
+```bash
+bun add -d buncargo
+```
+
+### 2. Create `dev.config.ts`
 
 ```typescript
-import { defineDevConfig } from 'buncargo'
+import { defineDevConfig, service } from 'buncargo'
 
 export default defineDevConfig({
   projectPrefix: 'myapp',
 
   services: {
-    postgres: {
-      port: 5432,
-      healthCheck: 'pg_isready',
-      urlTemplate: ({ port }) => `postgresql://postgres:postgres@localhost:${port}/mydb`
-    },
-    redis: {
-      port: 6379,
-      healthCheck: 'redis-cli'
-    }
+    postgres: service.postgres({ database: 'mydb' }),
+    redis: service.redis(),
   },
 
   apps: {
     api: {
       port: 3000,
       devCommand: 'bun run dev',
-      cwd: 'apps/backend'
+      cwd: 'apps/backend',
     },
     web: {
       port: 5173,
       devCommand: 'bun run dev',
-      cwd: 'apps/frontend'
-    }
+      cwd: 'apps/frontend',
+    },
   },
 
   envVars: (ports, urls) => ({
     DATABASE_URL: urls.postgres,
     REDIS_URL: urls.redis,
-    API_PORT: ports.api
+    API_PORT: ports.api,
   }),
-
-  hooks: {
-    afterContainersReady: async (ctx) => {
-      await ctx.exec('bunx prisma migrate deploy', { cwd: 'packages/prisma' })
-    }
-  },
-
-  prisma: {
-    cwd: 'packages/prisma'
-  }
 })
 ```
 
-### 2. Run it
-
-```bash
-bunx buncargo dev           # Start containers + dev servers
-bunx buncargo dev --up-only # Start containers only
-bunx buncargo dev --down    # Stop containers
-bunx buncargo dev --reset   # Stop and remove volumes
-bunx buncargo typecheck     # Run TypeScript typecheck across workspaces
-bunx buncargo prisma studio # Run prisma with correct DATABASE_URL
-bunx buncargo env           # Print ports/urls as JSON
-```
-
-Or add scripts to `package.json`:
+### 3. Add scripts to `package.json`
 
 ```json
 {
   "scripts": {
     "dev": "bunx buncargo dev",
-    "dev:docker:down": "bunx buncargo dev --down",
-    "typecheck": "bunx buncargo typecheck",
+    "dev:up": "bunx buncargo dev --up-only",
+    "dev:down": "bunx buncargo dev --down",
+    "dev:reset": "bunx buncargo dev --reset",
+    "dev:expose": "bunx buncargo dev --expose",
     "prisma": "bunx buncargo prisma"
   }
 }
 ```
 
-## Programmatic Access
+### 4. Run
+
+```bash
+bun run dev
+```
+
+Buncargo will:
+1. Generate a Docker Compose file from your config
+2. Start all containers and wait for health checks
+3. Run any configured migrations
+4. Start your dev servers
+5. Print all ports and URLs
+
+## CLI Commands
+
+```bash
+bunx buncargo dev              # Start containers + dev servers
+bunx buncargo dev --up-only    # Start containers only (no dev servers)
+bunx buncargo dev --down       # Stop containers
+bunx buncargo dev --reset      # Stop containers and remove volumes
+bunx buncargo dev --expose     # Start with public tunnels for expose:true targets
+bunx buncargo dev --expose=api # Expose specific targets
+bunx buncargo dev --migrate    # Run migrations only
+bunx buncargo dev --seed       # Run migrations and seeders
+bunx buncargo prisma <args>    # Run Prisma CLI with correct DATABASE_URL
+bunx buncargo typecheck        # Run TypeScript typecheck across workspaces
+bunx buncargo env              # Print ports/URLs as JSON
+bunx buncargo help             # Show help
+bunx buncargo version          # Show version
+```
+
+## Services
 
-Need ports/urls in your code (e.g., for tests)?
+### Built-in Presets
+
+Use `service.*` helpers for common databases with sensible defaults:
 
 ```typescript
-import { loadDevEnv } from 'buncargo'
+services: {
+  postgres: service.postgres({ database: 'mydb' }),
+  redis: service.redis(),
+  clickhouse: service.clickhouse({ database: 'analytics' }),
+}
+```
 
-const env = await loadDevEnv()
-console.log(env.ports.postgres)  // 5432 (or offset port)
-console.log(env.urls.api)        // http://localhost:3000
-console.log(env.urls.postgres)   // postgresql://...
+Each preset includes:
+- Default Docker image
+- Health check configuration
+- URL template (e.g., `postgresql://postgres:postgres@localhost:5432/mydb`)
+- Volume for data persistence
+
+### Custom Services
+
+Use `service.custom()` for any Docker service:
+
+```typescript
+services: {
+  rabbitmq: service.custom({
+    port: 5672,
+    healthCheck: false,
+    docker: {
+      image: 'rabbitmq:3-management-alpine',
+      ports: ['${RABBITMQ_PORT:-5672}:5672', '15672:15672'],
+      environment: {
+        RABBITMQ_DEFAULT_USER: 'guest',
+        RABBITMQ_DEFAULT_PASS: 'guest',
+      },
+    },
+  }),
+  nats: service.custom({
+    port: 4222,
+    docker: {
+      image: 'nats:2-alpine',
+      ports: ['${NATS_PORT:-4222}:4222'],
+    },
+  }),
+}
+```
+
+## Apps
+
+Define dev servers to run alongside containers:
+
+```typescript
+apps: {
+  api: {
+    port: 3000,
+    devCommand: 'bun run dev',
+    cwd: 'apps/backend',
+    healthEndpoint: '/health',
+  },
+  web: {
+    port: 5173,
+    devCommand: 'bun run dev',
+    cwd: 'apps/frontend',
+    healthEndpoint: '/',
+  },
+}
+```
+
+Use `onlyApps` on `start()` or `startServers()` to launch and wait for only those named apps (same env injection and health checks as when all apps run).
+
+## Environment Variables
+
+The `envVars` function builds all env vars from computed ports and URLs:
+
+```typescript
+envVars: (ports, urls, { localIp, publicUrls }) => ({
+  DATABASE_URL: urls.postgres,
+  REDIS_URL: urls.redis,
+  API_PORT: ports.api,
+  EXPO_API_URL: `http://${localIp}:${ports.api}`,
+  WEBHOOK_URL: publicUrls.api ?? urls.api,
+})
 ```
 
-## Features
+`buildEnvVars()` always includes, for each service/app name `foo`:
+
+- `FOO_PORT` — assigned port
+- `FOO_URL` — local URL (LAN)
+- `FOO_PUBLIC_URL` — only while a public tunnel is active for that name
 
-### Worktree Isolation
+Your `envVars` callback receives `publicUrls` and typically maps client bundles, e.g. `EXPO_PUBLIC_API_URL: publicUrls.api ?? urls.api`.
+
+These are injected into:
+- Docker Compose services
+- Dev server processes
+- Hook `exec()` calls
+- Prisma commands
 
-Each git worktree automatically gets:
+## Worktree Isolation
 
-- Unique ports (offset 10-99)
-- Unique Docker Compose project names
+When working in git worktrees, buncargo automatically assigns unique port offsets (10-99) so each worktree has isolated:
+- Ports (e.g., postgres on 5442 instead of 5432)
+- Docker Compose project names
+- Containers, networks, and volumes
 
-This means each worktree has isolated containers, networks, and volumes by default.
+This means you can run multiple branches simultaneously without conflicts.
 
-If you intentionally want shared Docker state across worktrees, set:
+To disable isolation and share state across worktrees:
 
 ```typescript
 options: {
@@ -112,46 +226,71 @@ options: {
 }
 ```
 
-### Health Checks
+## Public Tunnels
 
-Built-in health checks for common services:
+Expose local services to the internet using Cloudflare Quick Tunnels:
 
-- `pg_isready` - PostgreSQL
-- `redis-cli` - Redis
-- `http` - HTTP endpoint check
-- `tcp` - TCP port check
+```typescript
+services: {
+  postgres: service.postgres({ database: 'mydb' }),
+},
+apps: {
+  api: {
+    port: 3000,
+    devCommand: 'bun run dev',
+    expose: true,  // Mark as exposable
+  },
+}
+```
 
-### URL Templates
+```bash
+bun run dev --expose      # Expose all targets with expose: true
+bun run dev --expose=api  # Expose specific targets
+```
 
-Define connection URLs as functions:
+Public URLs are printed in the console and available via `publicUrls` in `envVars`:
 
 ```typescript
-urlTemplate: ({ port, host, localIp }) => 
-  `postgresql://user:pass@${host}:${port}/db`
+envVars: (_ports, urls, { publicUrls }) => ({
+  WEBHOOK_URL: publicUrls.api ?? urls.api,
+})
 ```
 
-Default templates exist for: `postgres`, `redis`, `clickhouse`, `mysql`, `mongodb`
+**CLI vs programmatic ordering:** `bunx buncargo dev --expose` starts Cloudflare quick tunnels after containers and migrations but **before** the interactive dev-server command (e.g. `concurrently`) runs. Until those servers are listening on their ports, tunnel traffic can briefly error. For “servers first, then public URLs,” use the API: e.g. `await dev.startServers({ onlyApps: ['api', 'platform'] })`, then `await dev.openPublicTunnels({ waitForHealthy: ['api', 'platform'] })` (optional; waits HTTP health first), then read `dev.buildEnvVars()` for spawned children.
+
+**Expo hybrid:** buncargo is suited to exposing **API** and **platform** (Vite, etc.) for devices on cellular. **Metro** often uses Expo’s own tunnel (`expo start --tunnel`); you usually do **not** add Metro as a buncargo `app` unless you want buncargo to start it. Wire `EXPO_PUBLIC_*` from `publicUrls.* ?? urls.*` in `envVars`.
 
-### Lifecycle Hooks
+**Programmatic helper:** `openPublicTunnels({ names?, waitForHealthy? })` applies tunnel URLs via `setPublicUrls` and returns `close()` to stop tunnels and clear public URLs. Call `buildEnvVars()` after `openPublicTunnels` resolves so `envVars` and `*_PUBLIC_URL` see the tunnel origins.
+
+## Lifecycle Hooks
+
+Run code at specific points in the startup/shutdown cycle:
 
 ```typescript
 hooks: {
-  afterContainersReady: async (ctx) => { /* Run migrations */ },
-  beforeServers: async (ctx) => { /* Seed database */ },
-  afterServers: async (ctx) => { /* Post-startup tasks */ },
-  beforeStop: async (ctx) => { /* Cleanup */ }
+  afterContainersReady: async (ctx) => {
+    await ctx.exec('bunx prisma migrate deploy', { cwd: 'packages/prisma' })
+  },
+  beforeServers: async (ctx) => {
+    await ctx.exec('bun run seed')
+  },
+  afterServers: async (ctx) => {
+    console.log(`API running at ${ctx.urls.api}`)
+  },
+  beforeStop: async (ctx) => {
+    await ctx.exec('bun run cleanup', { throwOnError: false })
+  },
 }
 ```
 
-### Hook Context
-
-Hooks receive a context object with:
+Hook context provides:
 
 ```typescript
 interface HookContext {
   projectName: string
   ports: { postgres: number, api: number, ... }
   urls: { postgres: string, api: string, ... }
+  publicUrls: { api?: string, ... }
   root: string
   isCI: boolean
   portOffset: number
@@ -160,54 +299,171 @@ interface HookContext {
 }
 ```
 
-### Watchdog Auto-Shutdown
+## Migrations and Seeding
 
-Containers automatically stop after 10 minutes of inactivity when running via CLI.
+### Migrations
 
-## CLI Reference
+Run migration commands after containers are healthy:
 
+```typescript
+migrations: [
+  { name: 'prisma', command: 'bunx prisma migrate deploy', cwd: 'packages/prisma' },
+  { name: 'clickhouse', command: 'bun run migrate:clickhouse' },
+]
 ```
-COMMANDS:
-  dev                 Start the development environment
-  typecheck           Run TypeScript typecheck across workspaces
-  prisma <args>       Run Prisma CLI with correct DATABASE_URL
-  env                 Print environment info as JSON
-  help                Show help
-  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
+### Seeding
+
+Seed the database with a check to avoid re-seeding:
+
+```typescript
+seed: {
+  command: 'bun run seed',
+  check: ({ checkTable }) => checkTable('User', 'postgres'),
+}
 ```
 
-## Environment Variables
+## Prisma Integration
 
-The `envVars` function receives:
+Configure Prisma to use the correct database URL:
 
 ```typescript
-envVars: (ports, urls, context) => ({
-  // ports: { postgres: 5432, api: 3000, ... }
-  // urls: { postgres: "postgresql://...", ... }
-  // context: { localIp, portOffset, isCI, root }
-})
+prisma: {
+  cwd: 'packages/prisma',
+  service: 'postgres',        // Default: 'postgres'
+  urlEnvVar: 'DATABASE_URL',  // Default: 'DATABASE_URL'
+}
 ```
 
-These are injected into:
-- Docker Compose (via `COMPOSE_PROJECT_NAME`)
-- Dev server processes
-- Hook `exec()` calls
+Then run Prisma commands through buncargo:
+
+```bash
+bun run prisma migrate dev
+bun run prisma studio
+bun run prisma db push
+```
 
-## Docker Compose
+Buncargo ensures the database container is running and injects the correct `DATABASE_URL` with worktree-aware ports.
 
-Your `docker-compose.yml` should use environment variables for ports:
+## Programmatic API
 
-```yaml
-services:
-  postgres:
-    image: postgres:16
-    ports:
-      - "${POSTGRES_PORT:-5432}:5432"
+Access the dev environment from code (useful for tests):
+
+```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
+console.log(env.urls.postgres)   // postgresql://postgres:postgres@localhost:5432/mydb
+
+// Start/stop programmatically
+await env.start()
+await env.stop({ removeVolumes: true })
+
+// Build env vars for subprocess
+const envVars = env.buildEnvVars()
+```
+
+## Docker Compose Generation
+
+Buncargo generates Docker Compose from your config. No external `docker-compose.yml` is read.
+
+```typescript
+docker: {
+  generatedFile: '.buncargo/docker-compose.generated.yml',
+  writeStrategy: 'always',  // or 'if-missing'
+  volumes: {
+    shared_cache: {},
+  },
+}
+```
+
+## Health Checks
+
+Built-in health check types:
+
+| Type | Description |
+|------|-------------|
+| `pg_isready` | PostgreSQL readiness check |
+| `redis-cli` | Redis PING check |
+| `http` | HTTP endpoint check |
+| `tcp` | TCP port check |
+
+Or provide a custom health check function:
+
+```typescript
+healthCheck: async (port) => {
+  const res = await fetch(`http://localhost:${port}/health`)
+  return res.ok
+}
 ```
+
+## Watchdog Auto-Shutdown
+
+When running via CLI, containers automatically stop after 10 minutes of inactivity. The watchdog monitors heartbeats and shuts down orphaned environments.
+
+## Full Example
+
+```typescript
+import { defineDevConfig, service } from 'buncargo'
+
+export default defineDevConfig({
+  projectPrefix: 'platform',
+
+  services: {
+    postgres: service.postgres({ database: 'platform' }),
+    redis: service.redis(),
+    clickhouse: service.clickhouse({ database: 'platform' }),
+  },
+
+  apps: {
+    api: {
+      port: 3000,
+      expose: true,
+      devCommand: 'bun run dev',
+      cwd: 'apps/backend',
+      healthEndpoint: '/health',
+    },
+    web: {
+      port: 5173,
+      devCommand: 'bun run dev',
+      cwd: 'apps/frontend',
+    },
+  },
+
+  envVars: (ports, urls, { localIp, publicUrls }) => ({
+    DATABASE_URL: urls.postgres,
+    REDIS_URL: urls.redis,
+    CLICKHOUSE_URL: urls.clickhouse,
+    API_URL: urls.api,
+    VITE_API_URL: urls.api,
+    EXPO_API_URL: `http://${localIp}:${ports.api}`,
+    WEBHOOK_URL: publicUrls.api ?? urls.api,
+  }),
+
+  migrations: [
+    { name: 'prisma', command: 'bunx prisma migrate deploy', cwd: 'packages/prisma' },
+  ],
+
+  seed: {
+    command: 'bun run seed',
+    check: ({ checkTable }) => checkTable('User', 'postgres'),
+  },
+
+  prisma: {
+    cwd: 'packages/prisma',
+  },
+
+  hooks: {
+    afterContainersReady: async (ctx) => {
+      console.log(`Containers ready on port offset ${ctx.portOffset}`)
+    },
+  },
+})
+```
+
+## License
+
+MIT

package/src/cli/bin.ts

@@ -0,0 +1,77 @@
+#!/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 typecheck     # Run TypeScript typecheck
+ *   bunx buncargo prisma ...    # Run prisma commands
+ *   bunx buncargo help          # Show help
+ */
+
+import { showHelp } from "./commands/help";
+import {
+	handleDev,
+	handleEnv,
+	handlePrisma,
+	handleTypecheck,
+} from "./commands/runtime";
+import { showVersion } from "./commands/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 "typecheck":
+			await handleTypecheck();
+			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) => {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`❌ ${message}`);
+	process.exit(1);
+});

package/src/cli/commands/help.ts

@@ -0,0 +1,39 @@
+export function showHelp(): void {
+	console.log(`
+buncargo - Development environment CLI
+
+USAGE:
+  bunx buncargo <command> [options]
+
+COMMANDS:
+  dev                 Start the development environment
+  typecheck           Run TypeScript typecheck across workspaces
+  prisma <args>       Run Prisma CLI with correct DATABASE_URL
+  env                 Print environment info as JSON
+  help                Show this help message
+  version             Show version
+
+EXAMPLES:
+  bunx buncargo dev              # Start everything
+  bunx buncargo dev --expose     # Public quick tunnel for expose:true targets
+  bunx buncargo dev --expose=api # Public quick tunnel for selected target
+  bunx buncargo dev --help       # Show dev command options
+  bunx buncargo dev --down       # Stop containers
+  bunx buncargo typecheck        # Run typecheck
+  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: { ... }
+  })
+
+Run "bunx buncargo dev --help" for dev command options.
+`);
+}