dev-prism 0.4.0 → 0.7.0

package/README.md

@@ -4,27 +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
 
-**Minimal orchestration, maximal Docker Compose.** This tool does the bare minimum:
-1. Creates git worktrees for isolated working directories
-2. Generates `.env.session` with calculated ports
-3. Runs `docker compose` commands
+**Allocate ports. Inject env. Get out of the way.**
 
-All Docker configuration lives in `docker-compose.session.yml` in your project - a standard file you control.
+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
 
+- **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
-- **Unique ports** per session (calculated from session ID, displayed as clickable URLs)
-- **Auto-assign** session IDs or choose your own
-- **SQLite tracking** — all sessions stored in a local database
-- **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
 
@@ -34,66 +34,101 @@ npm install -g dev-prism
 pnpm add -D dev-prism
 ```
 
+## Quick Start
+
+```bash
+# Create a session (allocates ports + creates worktree)
+dev-prism create --branch feature/auth
+
+# Or create in current directory
+dev-prism create --in-place
+
+# Start Docker services with allocated ports
+dev-prism with-env -- docker compose up -d
+
+# Run app with session env injected
+dev-prism with-env my-app -- pnpm dev
+
+# Show allocated ports and env vars
+dev-prism info
+
+# Print env vars (for eval or piping)
+dev-prism env
+
+# Write .env file for IDE
+dev-prism env --write .env
+
+# Destroy session
+dev-prism destroy
+```
+
 ## Usage
 
 ### Create a session
 
 ```bash
-# Auto-assign session ID
+# Create with worktree (generates timestamp-based branch)
 dev-prism create
 
-# Explicit session ID
-dev-prism create 001
-
 # 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
 ```
 
-### Session info (for current directory)
+`with-env` is a no-op outside sessions — safe to use unconditionally in scripts and Makefiles.
+
+### View env vars
 
 ```bash
-dev-prism info
+# Print all env vars to stdout
+dev-prism env
+
+# Write to file (for IDE/GUI tools)
+dev-prism env --write .env
+
+# Include app-specific vars
+dev-prism env --app convas-app
 ```
 
-### Start/Stop services
+### List sessions
 
 ```bash
-dev-prism stop 001   # Stop without destroying
-dev-prism start 001  # Start again
-dev-prism stop-all   # Stop all sessions
+dev-prism list
 ```
 
-### View logs
+### Session info
 
 ```bash
-dev-prism logs 001
+dev-prism info
 ```
 
 ### Cleanup
 
 ```bash
-dev-prism destroy 001     # Destroy specific session
-dev-prism destroy --all   # Destroy all sessions
-dev-prism prune           # Remove all stopped sessions
-dev-prism prune -y        # Skip confirmation
+# Destroy session in current directory
+dev-prism destroy
+
+# Destroy all sessions
+dev-prism destroy --all
+
+# Remove orphaned sessions from database
+dev-prism prune
+dev-prism prune -y  # Skip confirmation
 ```
 
 ### Claude Code integration
@@ -103,134 +138,148 @@ dev-prism claude          # Install Claude Code skill + CLAUDE.md
 dev-prism claude --force  # Overwrite existing files
 ```
 
-## Port Allocation
-
-Formula: `port = portBase + (sessionId * 100) + offset`
-
-With base port 47000:
-
-| Service        | Session 001 | Session 002 | Session 003 |
-|----------------|-------------|-------------|-------------|
-| APP_PORT       | 47100       | 47200       | 47300       |
-| WEB_PORT       | 47101       | 47201       | 47301       |
-| POSTGRES_PORT  | 47110       | 47210       | 47310       |
-| MAILPIT_SMTP   | 47111       | 47211       | 47311       |
-| MAILPIT_WEB    | 47112       | 47212       | 47312       |
-
 ## Configuration
 
-### session.config.mjs
+### prism.config.mjs
 
 ```javascript
 export default {
-  // Required
-  portBase: 47000,
-  sessionsDir: '../my-project-sessions',
-
-  // Port offsets - become env vars for docker-compose
-  // Formula: portBase + (sessionId * 100) + offset
-  ports: {
-    APP_PORT: 0,        // 47100, 47200, 47300...
-    WEB_PORT: 1,        // 47101, 47201, 47301...
-    POSTGRES_PORT: 10,  // 47110, 47210, 47310...
-    REDIS_PORT: 11,     // 47111, 47211, 47311...
-  },
-
-  // 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.session.yml (standard Docker Compose)
+### docker-compose.yml (user-managed)
 
 ```yaml
 services:
   postgres:
     image: postgres:16
-    container_name: postgres-${SESSION_ID}
     ports:
-      - "${POSTGRES_PORT}:5432"
+      - "${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
-
-  my-app:
-    profiles: ["apps"]  # Only runs in docker mode
-    build:
-      context: .
-      dockerfile: apps/my-app/Dockerfile.dev
-    container_name: my-app-${SESSION_ID}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  mailpit:
+    image: axllent/mailpit
     ports:
-      - "${APP_PORT}:3000"
-    environment:
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
-    depends_on:
-      postgres:
-        condition: service_healthy
+      - "${MAILPIT_HTTP_PORT:-8025}:8025"
+      - "${MAILPIT_SMTP_PORT:-1025}:1025"
+
+volumes:
+  postgres-data:
 ```
 
-## How It Works
+The `:-` defaults mean it works without dev-prism too (solo dev, standard ports).
 
-1. **Create session**: `dev-prism create`
-   - Auto-assigns next available session ID (or use explicit ID)
-   - Creates git worktree at `../project-sessions/session-001` (or uses current dir with `--in-place`)
-   - Generates `.env.session` with calculated ports
-   - Records session in local SQLite database
-   - Runs `docker compose --env-file .env.session up -d`
-   - Runs setup commands
+## How It Works
 
-2. **Docker Compose** reads `.env.session` and substitutes `${VAR}` placeholders
+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
 
-3. **Docker mode** (`--profile apps`): All services including apps run in containers
-4. **Native mode**: Only infrastructure runs; apps use `pnpm dev` with `.env.session`
+### Typical workflow
 
-All session state is tracked in a SQLite database (`~/.dev-prism/sessions.db`), making both worktree and in-place sessions first-class citizens across all commands.
+```bash
+dev-prism create --branch feature/auth
+cd ../sessions/feature/auth
 
-## Generated Files
+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"
 ```
-session-001/
-├── .env.session              # Port variables for docker-compose
-├── docker-compose.session.yml # (from git, not generated)
-└── apps/my-app/.env.session  # App-specific env for host CLI
+
+## Architecture
+
+### SQLite as Source of Truth
+
+Location: `<project-root>/.dev-prism/sessions.db`
+
+```sql
+CREATE TABLE sessions (
+  id         TEXT PRIMARY KEY,  -- working directory path
+  branch     TEXT,
+  created_at TEXT NOT NULL
+);
+
+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)
+);
 ```
 
-Example `.env.session`:
-```bash
-SESSION_ID=001
-POSTGRES_PORT=47110
-MAILPIT_SMTP_PORT=47111
-MAILPIT_WEB_PORT=47112
-APP_PORT=47100
+### Port Allocation Strategy
+
+Two-phase: `get-port` finds free TCP ports, SQLite UNIQUE prevents cross-session conflicts.
+
+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
+```
+
+This makes `with-env` safe to use unconditionally in scripts, Makefiles, and CI.
 
 ## Portability
 
 To use in another project:
 
 1. Install: `pnpm add -D dev-prism`
-2. Create `session.config.mjs` with port offsets
-3. Create `docker-compose.session.yml` with `${VAR}` placeholders
-4. Run `dev-prism create`
+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`
+
+dev-prism doesn't generate any Docker files — you own your Docker setup entirely.
+
+## Migration from v0.6.x
+
+v0.7.0 is a breaking change that removes Docker orchestration:
+
+**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`
+
+**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
+
+MIT

package/bin/dev-prism.js

@@ -6,114 +6,96 @@ import { destroySession } from '../dist/commands/destroy.js';
 import { listSessions } from '../dist/commands/list.js';
 import { installClaude } from '../dist/commands/claude.js';
 import { showInfo } from '../dist/commands/info.js';
-import { startSession } from '../dist/commands/start.js';
-import { stopSession } from '../dist/commands/stop.js';
-import { stopAllSessions } from '../dist/commands/stop-all.js';
+import { withEnv } from '../dist/commands/with-env.js';
+import { showEnv } from '../dist/commands/env.js';
 import { pruneSessions } from '../dist/commands/prune.js';
-import { streamLogs } from '../dist/commands/logs.js';
 
 const program = new Command();
 
 program
   .name('dev-prism')
-  .description('CLI tool for managing isolated parallel development sessions')
-  .version('0.4.0');
+  .description('Port allocator, env injector, and worktree manager for parallel development')
+  .version('0.7.0')
+  .enablePositionalOptions();
 
 program
-  .command('create [sessionId]')
-  .description('Create a new isolated development session')
-  .option('-m, --mode <mode>', 'App mode: docker (default) or native', 'docker')
-  .option('-b, --branch <branch>', 'Git branch name (default: session/YYYY-MM-DD/XXX)')
-  .option('-W, --without <apps>', 'Exclude apps (comma-separated: app,web,widget)', (val) => val.split(','))
-  .option('--no-detach', 'Stream container logs after starting (default: detach)')
+  .command('create')
+  .description('Create a new session (allocate ports + optional worktree)')
+  .option('-b, --branch <branch>', 'Git branch name (default: session/TIMESTAMP)')
   .option('--in-place', 'Run in current directory instead of creating a worktree')
-  .action(async (sessionId, options) => {
+  .action(async (options) => {
     const projectRoot = process.cwd();
-    await createSession(projectRoot, sessionId, {
-      mode: options.mode,
+    await createSession(projectRoot, {
       branch: options.branch,
-      detach: options.detach,
-      without: options.without,
       inPlace: options.inPlace,
     });
   });
 
 program
-  .command('destroy [sessionId]')
-  .description('Destroy a development session')
+  .command('destroy')
+  .description('Destroy session for current directory (deallocate ports + remove worktree)')
   .option('-a, --all', 'Destroy all sessions')
-  .action(async (sessionId, options) => {
-    const projectRoot = process.cwd();
-    await destroySession(projectRoot, sessionId, { all: options.all });
+  .action(async (options) => {
+    await destroySession(process.cwd(), { all: options.all });
   });
 
 program
   .command('list')
-  .description('List all active development sessions')
-  .option('-a, --all', 'Show sessions across all projects')
-  .action(async (options) => {
-    const projectRoot = process.cwd();
-    await listSessions(projectRoot, { all: options.all });
+  .description('List all sessions')
+  .action(async () => {
+    await listSessions();
   });
 
 program
   .command('info')
-  .description('Show session info for current directory (useful for --in-place sessions)')
+  .description('Show session ports and env vars for current directory')
   .action(async () => {
     await showInfo(process.cwd());
   });
 
-program
-  .command('start <sessionId>')
-  .description('Start Docker services for a session')
-  .option('-m, --mode <mode>', 'App mode: docker or native', 'docker')
-  .option('-W, --without <apps>', 'Exclude apps (comma-separated: app,web,widget)', (val) => val.split(','))
-  .action(async (sessionId, options) => {
-    const projectRoot = process.cwd();
-    await startSession(projectRoot, sessionId, {
-      mode: options.mode,
-      without: options.without,
-    });
-  });
-
-program
-  .command('stop <sessionId>')
-  .description('Stop Docker services for a session (without destroying)')
-  .action(async (sessionId) => {
-    const projectRoot = process.cwd();
-    await stopSession(projectRoot, sessionId);
-  });
-
-program
-  .command('logs <sessionId>')
-  .description('Stream logs from a session\'s Docker services')
-  .option('-m, --mode <mode>', 'App mode: docker or native', 'docker')
-  .option('-W, --without <apps>', 'Exclude apps (comma-separated: app,web,widget)', (val) => val.split(','))
-  .option('-n, --tail <lines>', 'Number of lines to show from the end', '50')
-  .action(async (sessionId, options) => {
-    const projectRoot = process.cwd();
-    await streamLogs(projectRoot, sessionId, {
-      mode: options.mode,
-      without: options.without,
-      tail: options.tail,
-    });
+const withEnvCmd = program
+  .command('with-env [app]')
+  .description('Inject session env vars and exec a command')
+  .passThroughOptions()
+  .allowUnknownOption()
+  .action(async (app, options, cmd) => {
+    // cmd.args includes [app] as its first element when set — strip it.
+    const rawArgs = app ? cmd.args.slice(1) : cmd.args;
+
+    let appName;
+    let command;
+
+    const dashIdx = rawArgs.indexOf('--');
+    if (dashIdx !== -1) {
+      // dev-prism with-env my-app -- echo hello
+      appName = app;
+      command = rawArgs.slice(dashIdx + 1);
+    } else if (app) {
+      // No --, treat app as start of command (not an app name)
+      // dev-prism with-env echo hello world
+      command = [app, ...rawArgs];
+    } else {
+      command = rawArgs;
+    }
+
+    await withEnv(command, appName);
   });
 
 program
-  .command('stop-all')
-  .description('Stop all running sessions (preserves data)')
-  .action(async () => {
-    const projectRoot = process.cwd();
-    await stopAllSessions(projectRoot);
+  .command('env')
+  .description('Print or write session env vars')
+  .option('-w, --write <path>', 'Write env to file instead of stdout')
+  .option('-a, --app <name>', 'Include app-specific env vars')
+  .action(async (options) => {
+    await showEnv({ write: options.write, app: options.app });
   });
 
 program
   .command('prune')
-  .description('Remove all stopped sessions (destroys data)')
+  .description('Remove orphaned sessions from the database')
   .option('-y, --yes', 'Skip confirmation prompt')
   .action(async (options) => {
-    const projectRoot = process.cwd();
-    await pruneSessions(projectRoot, { yes: options.yes });
+    await pruneSessions({ yes: options.yes });
   });
 
 program
@@ -131,53 +113,51 @@ program
     const chalk = (await import('chalk')).default;
 
     console.log(`
-${chalk.bold('dev-prism')} - Manage isolated parallel development sessions
+${chalk.bold('dev-prism')} - Port allocator, env injector, and worktree manager
 
 ${chalk.bold('USAGE')}
   dev-prism <command> [options]
 
 ${chalk.bold('COMMANDS')}
-  ${chalk.cyan('create')} [id]      Create a new session (auto-assigns ID if not provided)
-  ${chalk.cyan('destroy')} <id>     Destroy a specific session
-  ${chalk.cyan('list')}             List all sessions and their status
-  ${chalk.cyan('info')}             Show session info for current directory
-  ${chalk.cyan('start')} <id>       Start Docker services for a stopped session
-  ${chalk.cyan('stop')} <id>        Stop Docker services (preserves data)
-  ${chalk.cyan('stop-all')}         Stop all running sessions
-  ${chalk.cyan('logs')} <id>        Stream logs from a session
-  ${chalk.cyan('prune')}            Remove all stopped sessions
+  ${chalk.cyan('create')}                        Create a new session (ports + worktree)
+  ${chalk.cyan('destroy')}                       Destroy session for current directory
+  ${chalk.cyan('list')}                          List all sessions
+  ${chalk.cyan('info')}                          Show session info for current directory
+  ${chalk.cyan('with-env')} [app] -- <command>   Inject env vars + exec command
+  ${chalk.cyan('env')}                           Print/write session env vars
+  ${chalk.cyan('prune')}                         Remove orphaned sessions
+  ${chalk.cyan('claude')}                        Install Claude Code integration
 
 ${chalk.bold('EXAMPLES')}
-  ${chalk.gray('# Create a new session (auto-assigns next available ID)')}
+  ${chalk.gray('# Create a new session with worktree')}
   $ dev-prism create
 
-  ${chalk.gray('# Create session with specific branch')}
+  ${chalk.gray('# Create session with specific branch name')}
   $ dev-prism create --branch feature/my-feature
 
-  ${chalk.gray('# Create session in native mode (apps run on host)')}
-  $ dev-prism create --mode native
-
-  ${chalk.gray('# Create session without web app')}
-  $ dev-prism create --without web
-
   ${chalk.gray('# Create session in current directory (no worktree)')}
   $ dev-prism create --in-place
 
-  ${chalk.gray('# Check session status in current directory')}
-  $ dev-prism info
+  ${chalk.gray('# Start Docker services with injected ports')}
+  $ dev-prism with-env -- docker compose up -d
 
-  ${chalk.gray('# Stop all running sessions before switching context')}
-  $ dev-prism stop-all
+  ${chalk.gray('# Run app with app-specific env vars')}
+  $ dev-prism with-env my-app -- pnpm dev
 
-  ${chalk.gray('# Clean up old stopped sessions')}
-  $ dev-prism prune
+  ${chalk.gray('# Show session env vars')}
+  $ dev-prism env
+
+  ${chalk.gray('# Write env file for IDE')}
+  $ dev-prism env --write .env
+
+  ${chalk.gray('# Destroy session in current directory')}
+  $ dev-prism destroy
 
   ${chalk.gray('# Destroy all sessions')}
   $ dev-prism destroy --all
 
-${chalk.bold('SESSION MODES')}
-  ${chalk.cyan('docker')} (default)  All apps run in containers
-  ${chalk.cyan('native')}            Only infrastructure in Docker, apps on host
+  ${chalk.gray('# Clean up orphaned sessions')}
+  $ dev-prism prune
 
 ${chalk.bold('MORE INFO')}
   Run ${chalk.cyan('dev-prism <command> --help')} for command-specific options