dev-prism 0.6.0 → 0.7.0

package/README.md

@@ -4,29 +4,27 @@
   <img src="banner.png" alt="dev-prism - One codebase, many parallel sessions" width="600">
 </p>
 
-A minimal CLI tool for managing isolated parallel development sessions. Enables multiple Claude Code (or human developer) sessions to work on the same repo simultaneously with complete isolation.
+A port allocator, env injector, and worktree manager for parallel development sessions. Enables multiple Claude Code (or human developer) sessions to work on the same repo simultaneously with complete isolation.
 
 ## Philosophy
 
-**Stateless orchestration, Docker as source of truth.** This tool does the bare minimum:
-1. Creates git worktrees for isolated working directories
-2. Generates `docker-compose.session.yml` with random port bindings
-3. Runs `docker compose` commands
-4. Discovers ports from running containers and writes `.env.session`
+**Allocate ports. Inject env. Get out of the way.**
 
-No database, no state tracking—everything is derived from Docker's reality.
+dev-prism does three things:
+1. Allocates unique ports via SQLite (UNIQUE constraints prevent conflicts)
+2. Injects those ports into any command via `with-env`
+3. Optionally manages git worktrees for isolated working directories
+
+Docker is the user's responsibility. dev-prism just hands ports to whatever you run.
 
 ## Features
 
-- **Stateless** - No database, Docker is the single source of truth
+- **SQLite-backed port allocation** with UNIQUE constraints (zero conflicts)
+- **`with-env` pass-through** — injects env vars into any command, no-op outside sessions
 - **Git worktrees** for isolated working directories (or in-place mode)
-- **Docker Compose** handles all container orchestration
-- **Random port allocation** via Docker (zero conflicts)
-- **Automatic port discovery** from running containers
-- **Auto-healing** - commands always sync to Docker reality
-- **Two modes**: Docker (apps in containers) or Native (apps run locally)
+- **App-specific env** — different env vars for different apps in a monorepo
 - **Claude Code integration** built-in (`dev-prism claude`)
-- **Portable**: Works with any project
+- **Portable**: Works with any project, any runtime, any Docker setup
 
 ## Installation
 
@@ -39,22 +37,28 @@ pnpm add -D dev-prism
 ## Quick Start
 
 ```bash
-# Create a session with worktree
-dev-prism create
+# Create a session (allocates ports + creates worktree)
+dev-prism create --branch feature/auth
 
 # Or create in current directory
 dev-prism create --in-place
 
-# List active sessions
-dev-prism list
+# Start Docker services with allocated ports
+dev-prism with-env -- docker compose up -d
 
-# Check current directory status
+# Run app with session env injected
+dev-prism with-env my-app -- pnpm dev
+
+# Show allocated ports and env vars
 dev-prism info
 
-# Stop session in current directory
-dev-prism stop
+# Print env vars (for eval or piping)
+dev-prism env
 
-# Destroy session in current directory
+# Write .env file for IDE
+dev-prism env --write .env
+
+# Destroy session
 dev-prism destroy
 ```
 
@@ -69,61 +73,48 @@ dev-prism create
 # Custom branch name
 dev-prism create --branch feature/my-feature
 
-# Native mode - only infrastructure in Docker, apps run via pnpm dev
-dev-prism create --mode native
-
-# Exclude specific apps from Docker
-dev-prism create --without web,widget
-
-# In-place mode - use current directory instead of creating worktree
+# In-place mode — use current directory instead of creating worktree
 dev-prism create --in-place
-
-# Stream logs after creation instead of detaching
-dev-prism create --no-detach
 ```
 
-### List sessions
+### Inject env and run commands
 
 ```bash
-dev-prism list
+# Inject session env into any command
+dev-prism with-env -- docker compose up -d
+dev-prism with-env -- pnpm dev
+dev-prism with-env -- cargo run
+
+# Inject app-specific env (merges global + app config)
+dev-prism with-env convas-app -- pnpm --filter convas-app dev
+dev-prism with-env convas-web -- pnpm --filter convas-web dev
 ```
 
-Shows only running sessions with their ports and container counts.
+`with-env` is a no-op outside sessions — safe to use unconditionally in scripts and Makefiles.
 
-### Session info
+### View env vars
 
 ```bash
-# Show info for current directory
-dev-prism info
+# Print all env vars to stdout
+dev-prism env
+
+# Write to file (for IDE/GUI tools)
+dev-prism env --write .env
 
-# Or specify directory
-dev-prism info /path/to/session
+# Include app-specific vars
+dev-prism env --app convas-app
 ```
 
-### Start/Stop services
+### List sessions
 
 ```bash
-# Stop session in current directory
-dev-prism stop
-
-# Or specify directory
-dev-prism stop /path/to/session
-
-# Stop all running sessions
-dev-prism stop-all
-
-# Start stopped session
-dev-prism start
+dev-prism list
 ```
 
-### View logs
+### Session info
 
 ```bash
-# Stream logs from current directory
-dev-prism logs
-
-# Or specify directory
-dev-prism logs /path/to/session
+dev-prism info
 ```
 
 ### Cleanup
@@ -132,13 +123,10 @@ dev-prism logs /path/to/session
 # Destroy session in current directory
 dev-prism destroy
 
-# Or specify directory
-dev-prism destroy /path/to/session
-
 # Destroy all sessions
 dev-prism destroy --all
 
-# Remove all stopped session directories
+# Remove orphaned sessions from database
 dev-prism prune
 dev-prism prune -y  # Skip confirmation
 ```
@@ -150,278 +138,147 @@ dev-prism claude          # Install Claude Code skill + CLAUDE.md
 dev-prism claude --force  # Overwrite existing files
 ```
 
-## Architecture
-
-### Stateless Design
-
-dev-prism v0.6+ has **zero persistent state**. Every command queries Docker to understand current reality:
-
-```bash
-# Session discovery
-docker ps --filter "label=dev-prism.managed=true"
-
-# Session identity = working directory path
-# Stored in container label: dev-prism.working_dir=/path/to/session
-```
-
-### Port Management
-
-Ports are **randomly assigned by Docker** and **discovered after startup**:
-
-1. Generate `docker-compose.session.yml` with `"0:5432"` (random host port)
-2. Start containers: `docker compose up -d`
-3. Inspect containers: `docker inspect` to get actual ports
-4. Write `.env.session` with discovered ports
-
-Example discovered ports:
-```bash
-POSTGRES_PORT=54321  # Random
-APP_PORT=32768       # Random
-WEB_PORT=32769       # Random
-```
-
-**Why random ports?**
-- Zero configuration
-- Docker handles conflicts automatically
-- Large ephemeral port range (32768-60999)
-- Simpler than centralized allocation
-
-### Auto-Healing
-
-Commands always reflect Docker's current state:
-
-```bash
-# If .env.session is deleted, it regenerates from Docker
-dev-prism info  # Queries Docker, recreates .env.session
-
-# If containers are manually removed, session disappears from list
-dev-prism list  # Only shows what Docker reports
-
-# If containers exist but .env.session is missing, file is recreated
-```
-
-No warnings, no errors, no stale state—just current reality.
-
 ## Configuration
 
-### session.config.mjs
+### prism.config.mjs
 
 ```javascript
 export default {
-  // Project name for Docker namespace (defaults to directory name)
-  projectName: 'myproject',
-
-  // Where to create worktrees (relative to project root)
-  sessionsDir: '../my-project-sessions',
-
-  // Docker Compose profiles for app containers (used in docker mode)
-  // These match service names with `profiles: ["app-name"]` in docker-compose
-  apps: ['app', 'web'],
-
-  // .env files to copy to session worktree (DATABASE_URL auto-updated)
-  envFiles: [
-    'apps/my-app/.env',
-    'packages/db/.env',
-  ],
+  ports: ['postgres', 'mailpit_http', 'mailpit_smtp', 'app', 'web'],
 
-  // Commands to run after session creation
-  setup: ['pnpm install', 'pnpm db:push'],
+  env: {
+    POSTGRES_PORT:     '${postgres}',
+    MAILPIT_HTTP_PORT: '${mailpit_http}',
+    MAILPIT_SMTP_PORT: '${mailpit_smtp}',
+    DATABASE_URL:      'postgresql://postgres:postgres@localhost:${postgres}/postgres',
+  },
 
-  // Optional: app-specific env for CLI commands from host (native mode)
-  appEnv: {
-    'apps/my-app': {
-      DATABASE_URL: 'postgresql://postgres:postgres@localhost:${POSTGRES_PORT}/postgres',
+  apps: {
+    'convas-app': {
+      PORT:         '${app}',
+      DATABASE_URL: 'postgresql://postgres:postgres@localhost:${postgres}/postgres',
     },
+    'convas-web': { PORT: '${web}' },
   },
+
+  setup: ['pnpm install'],
 };
 ```
 
-### docker-compose.yml (your base services)
-
-Define your services as usual:
+### docker-compose.yml (user-managed)
 
 ```yaml
 services:
   postgres:
     image: postgres:16
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U postgres"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  app:
-    profiles: ["app"]  # Only runs in docker mode
-    build:
-      context: .
-      dockerfile: apps/my-app/Dockerfile.dev
-    environment:
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
-    depends_on:
-      postgres:
-        condition: service_healthy
-```
-
-### Generated docker-compose.session.yml
-
-dev-prism generates this automatically with random ports and labels:
-
-```yaml
-# Auto-generated by dev-prism - DO NOT EDIT
-version: "3.8"
-
-x-dev-prism-labels: &dev-prism-labels
-  dev-prism.managed: "true"
-  dev-prism.working_dir: "/Users/you/worktrees/session-2026-02-06T12-30-45"
-  dev-prism.session_id: "/Users/you/worktrees/session-2026-02-06T12-30-45"
-  dev-prism.created_at: "2026-02-06T12:30:45.123Z"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
 
-services:
-  postgres:
-    extends:
-      file: docker-compose.yml
-      service: postgres
-    ports:
-      - "0:5432"  # Random host port
-    labels:
-      <<: *dev-prism-labels
-      dev-prism.service: "postgres"
-      dev-prism.internal_port: "5432"
-
-  app:
-    extends:
-      file: docker-compose.yml
-      service: app
+  mailpit:
+    image: axllent/mailpit
     ports:
-      - "0:3000"  # Random host port
-    labels:
-      <<: *dev-prism-labels
-      dev-prism.service: "app"
-      dev-prism.internal_port: "3000"
+      - "${MAILPIT_HTTP_PORT:-8025}:8025"
+      - "${MAILPIT_SMTP_PORT:-1025}:1025"
+
+volumes:
+  postgres-data:
 ```
 
+The `:-` defaults mean it works without dev-prism too (solo dev, standard ports).
+
 ## How It Works
 
-1. **Create session**: `dev-prism create`
-   - Checks for existing session in directory via Docker labels
-   - Creates git worktree (or uses current dir with `--in-place`)
-   - Generates `docker-compose.session.yml` with random port bindings (`"0:5432"`)
-   - Writes `.env.session` stub with compose project name
-   - Runs `docker compose up -d`
-   - Inspects running containers to discover actual ports
-   - Updates `.env.session` with discovered ports
-   - Runs setup commands
-
-2. **Port discovery**
-   - Query containers: `docker inspect <container-id>`
-   - Extract `NetworkSettings.Ports` mappings
-   - Write discovered ports to `.env.session`
-
-3. **Session identity**
-   - Session ID = full working directory path
-   - Stored in container labels: `dev-prism.working_dir=/path/to/session`
-   - One session per directory maximum
-
-4. **List sessions**: `dev-prism list`
-   - Query Docker: `docker ps --filter label=dev-prism.managed=true`
-   - Group by `working_dir` label
-   - Show only running sessions
-
-5. **Stop session**: `dev-prism stop`
-   - Find containers via labels
-   - Run `docker compose stop`
-   - Delete `.env.session` file
-
-## Generated Files
+1. **`dev-prism create`** allocates ports via `get-port` + SQLite UNIQUE constraints
+2. **`dev-prism with-env -- <cmd>`** reads ports from SQLite, renders env templates, injects into command
+3. **Docker Compose** uses `${VAR:-default}` substitution — standard, no dev-prism dependency
 
-```
-session-2026-02-06T12-30-45/
-├── .env.session               # Discovered ports (gitignored)
-├── docker-compose.session.yml # Generated compose file (gitignored)
-└── apps/my-app/.env.session   # App-specific env (gitignored)
-```
+### Typical workflow
 
-Example `.env.session` (after port discovery):
 ```bash
-# Auto-generated by dev-prism
-COMPOSE_PROJECT_NAME=myproject-a1b2c3d4
-SESSION_DIR=/Users/you/worktrees/session-2026-02-06T12-30-45
-
-# Discovered ports from running containers
-POSTGRES_PORT=54321
-APP_PORT=32768
-WEB_PORT=32769
-```
+dev-prism create --branch feature/auth
+cd ../sessions/feature/auth
 
-Add to `.gitignore`:
-```
-.env.session
-docker-compose.session.yml
+dev-prism with-env -- docker compose up -d     # infra on allocated ports
+dev-prism with-env convas-app -- pnpm dev      # app with PORT + DATABASE_URL
+
+# Or in package.json scripts:
+# "dev": "dev-prism with-env -- turbo dev"
+# "docker:up": "dev-prism with-env -- docker compose up -d"
 ```
 
-## Portability
+## Architecture
 
-To use in another project:
+### SQLite as Source of Truth
 
-1. Install: `pnpm add -D dev-prism`
-2. Create `session.config.mjs` (optional, has defaults)
-3. Define services in `docker-compose.yml`
-4. Run `dev-prism create`
+Location: `<project-root>/.dev-prism/sessions.db`
 
-dev-prism generates `docker-compose.session.yml` automatically—you never need to write it.
+```sql
+CREATE TABLE sessions (
+  id         TEXT PRIMARY KEY,  -- working directory path
+  branch     TEXT,
+  created_at TEXT NOT NULL
+);
 
-## Migration from v0.5.x
+CREATE TABLE port_allocations (
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  service    TEXT NOT NULL,
+  port       INTEGER NOT NULL UNIQUE,  -- prevents cross-session conflicts
+  PRIMARY KEY (session_id, service)
+);
+```
 
-v0.6.0 is a breaking change with a new stateless architecture:
+### Port Allocation Strategy
 
-**What changed:**
-- Session IDs: `001, 002, 003` → full directory paths
-- Port allocation: calculated → random (Docker assigns)
-- State storage: SQLite database → stateless (Docker labels)
-- Commands: `dev-prism stop 001` → `dev-prism stop` (uses cwd)
+Two-phase: `get-port` finds free TCP ports, SQLite UNIQUE prevents cross-session conflicts.
 
-**Migration steps:**
-1. Stop all v0.5 sessions: `dev-prism stop-all` (on v0.5.x)
-2. Upgrade to v0.6: `pnpm add -g dev-prism@0.6`
-3. Recreate sessions as needed
+1. Query all existing allocated + reserved ports
+2. Use `get-port` to find free ports (excluding existing)
+3. INSERT all in a single transaction
+4. Retry once on UNIQUE violation (race condition)
+
+### `with-env` Pass-Through
+
+```
+No project root found → exec command as-is
+No session in DB      → exec command as-is
+Session found         → render env templates → merge with process.env → exec
+```
 
-Old session directories can be deleted manually if no longer needed.
+This makes `with-env` safe to use unconditionally in scripts, Makefiles, and CI.
 
-## Why Stateless?
+## Portability
 
-**Problems with v0.5.x database approach:**
-- State could diverge from Docker reality (manual container removal)
-- Required reconciliation logic
-- Database was single point of failure
-- Stored data that Docker already knows
+To use in another project:
 
-**v0.6+ stateless benefits:**
-- Docker is always the source of truth
-- No state sync issues
-- Survives `docker system prune`
-- Simpler codebase (fewer abstractions)
-- Auto-heals on every command
-- Zero configuration for port conflicts
+1. Install: `pnpm add -D dev-prism`
+2. Create `prism.config.mjs` with your ports and env templates
+3. Write your own `docker-compose.yml` using `${VAR:-default}` for ports
+4. Run `dev-prism create --in-place`
 
-## Troubleshooting
+dev-prism doesn't generate any Docker files — you own your Docker setup entirely.
 
-**"No session found in this directory"**
-- Session only exists when containers are running
-- Run `dev-prism create` to start a new session
+## Migration from v0.6.x
 
-**"Session already running in this directory"**
-- Containers are already running here
-- Use `dev-prism stop` first, then `dev-prism create` again
+v0.7.0 is a breaking change that removes Docker orchestration:
 
-**Ports not in .env.session**
-- Run `dev-prism info` to regenerate from Docker
+**What changed:**
+- Port allocation: Docker random → `get-port` + SQLite
+- State storage: Docker labels → SQLite database
+- Docker management: Removed (user's responsibility)
+- New commands: `with-env`, `env`
+- Removed commands: `start`, `stop`, `stop-all`, `logs`
 
-**Want predictable ports?**
-- Override in your `docker-compose.yml`: `ports: ["5432:5432"]`
-- Trade-off: potential conflicts across sessions
+**Migration steps:**
+1. Stop all v0.6 sessions: `dev-prism stop-all` (on v0.6.x)
+2. Upgrade: `pnpm add -g dev-prism@0.7`
+3. Update config to `prism.config.mjs` with new format (ports array, env templates)
+4. Write your own `docker-compose.yml` with `${VAR:-default}` port substitution
+5. Recreate sessions
 
 ## License