dev-prism 0.3.0 → 0.6.0

package/README.md

@@ -8,20 +8,22 @@ A minimal CLI tool for managing isolated parallel development sessions. Enables
 
 ## Philosophy
 
-**Minimal orchestration, maximal Docker Compose.** This tool does the bare minimum:
+**Stateless orchestration, Docker as source of truth.** This tool does the bare minimum:
 1. Creates git worktrees for isolated working directories
-2. Generates `.env.session` with calculated ports
+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`
 
-All Docker configuration lives in `docker-compose.session.yml` in your project - a standard file you control.
+No database, no state tracking—everything is derived from Docker's reality.
 
 ## Features
 
+- **Stateless** - No database, Docker is the single source of truth
 - **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
+- **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)
 - **Claude Code integration** built-in (`dev-prism claude`)
 - **Portable**: Works with any project
@@ -34,17 +36,36 @@ npm install -g dev-prism
 pnpm add -D dev-prism
 ```
 
+## Quick Start
+
+```bash
+# Create a session with worktree
+dev-prism create
+
+# Or create in current directory
+dev-prism create --in-place
+
+# List active sessions
+dev-prism list
+
+# Check current directory status
+dev-prism info
+
+# Stop session in current directory
+dev-prism stop
+
+# Destroy session in current directory
+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
 
@@ -67,33 +88,59 @@ dev-prism create --no-detach
 dev-prism list
 ```
 
-### Session info (for current directory)
+Shows only running sessions with their ports and container counts.
+
+### Session info
 
 ```bash
+# Show info for current directory
 dev-prism info
+
+# Or specify directory
+dev-prism info /path/to/session
 ```
 
 ### Start/Stop services
 
 ```bash
-dev-prism stop 001   # Stop without destroying
-dev-prism start 001  # Start again
-dev-prism stop-all   # Stop all sessions
+# 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
 ```
 
 ### View logs
 
 ```bash
-dev-prism logs 001
+# Stream logs from current directory
+dev-prism logs
+
+# Or specify directory
+dev-prism logs /path/to/session
 ```
 
 ### 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
+
+# Or specify directory
+dev-prism destroy /path/to/session
+
+# Destroy all sessions
+dev-prism destroy --all
+
+# Remove all stopped session directories
+dev-prism prune
+dev-prism prune -y  # Skip confirmation
 ```
 
 ### Claude Code integration
@@ -103,19 +150,57 @@ dev-prism claude          # Install Claude Code skill + CLAUDE.md
 dev-prism claude --force  # Overwrite existing files
 ```
 
-## Port Allocation
+## 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
 
-Formula: `port = portBase + (sessionId * 100) + offset`
+# If containers are manually removed, session disappears from list
+dev-prism list  # Only shows what Docker reports
 
-With base port 47000:
+# If containers exist but .env.session is missing, file is recreated
+```
 
-| 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       |
+No warnings, no errors, no stale state—just current reality.
 
 ## Configuration
 
@@ -123,18 +208,11 @@ With base port 47000:
 
 ```javascript
 export default {
-  // Required
-  portBase: 47000,
-  sessionsDir: '../my-project-sessions',
+  // Project name for Docker namespace (defaults to directory name)
+  projectName: 'myproject',
 
-  // 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...
-  },
+  // 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
@@ -158,15 +236,14 @@ export default {
 };
 ```
 
-### docker-compose.session.yml (standard Docker Compose)
+### docker-compose.yml (your base services)
+
+Define your services as usual:
 
 ```yaml
 services:
   postgres:
     image: postgres:16
-    container_name: postgres-${SESSION_ID}
-    ports:
-      - "${POSTGRES_PORT}:5432"
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -176,14 +253,11 @@ services:
       timeout: 5s
       retries: 5
 
-  my-app:
-    profiles: ["apps"]  # Only runs in docker mode
+  app:
+    profiles: ["app"]  # Only runs in docker mode
     build:
       context: .
       dockerfile: apps/my-app/Dockerfile.dev
-    container_name: my-app-${SESSION_ID}
-    ports:
-      - "${APP_PORT}:3000"
     environment:
       DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
     depends_on:
@@ -191,39 +265,101 @@ services:
         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"
+
+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
+    ports:
+      - "0:3000"  # Random host port
+    labels:
+      <<: *dev-prism-labels
+      dev-prism.service: "app"
+      dev-prism.internal_port: "3000"
+```
+
 ## How It Works
 
 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`
+   - 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. **Docker Compose** reads `.env.session` and substitutes `${VAR}` placeholders
+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
 
-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`
+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
 
-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.
+5. **Stop session**: `dev-prism stop`
+   - Find containers via labels
+   - Run `docker compose stop`
+   - Delete `.env.session` file
 
 ## Generated Files
 
 ```
-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
+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)
 ```
 
-Example `.env.session`:
+Example `.env.session` (after port discovery):
 ```bash
-SESSION_ID=001
-POSTGRES_PORT=47110
-MAILPIT_SMTP_PORT=47111
-MAILPIT_WEB_PORT=47112
-APP_PORT=47100
+# 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
+```
+
+Add to `.gitignore`:
+```
+.env.session
+docker-compose.session.yml
 ```
 
 ## Portability
@@ -231,6 +367,62 @@ APP_PORT=47100
 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
+2. Create `session.config.mjs` (optional, has defaults)
+3. Define services in `docker-compose.yml`
 4. Run `dev-prism create`
+
+dev-prism generates `docker-compose.session.yml` automatically—you never need to write it.
+
+## Migration from v0.5.x
+
+v0.6.0 is a breaking change with a new stateless architecture:
+
+**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)
+
+**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
+
+Old session directories can be deleted manually if no longer needed.
+
+## Why Stateless?
+
+**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
+
+**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
+
+## Troubleshooting
+
+**"No session found in this directory"**
+- Session only exists when containers are running
+- Run `dev-prism create` to start a new session
+
+**"Session already running in this directory"**
+- Containers are already running here
+- Use `dev-prism stop` first, then `dev-prism create` again
+
+**Ports not in .env.session**
+- Run `dev-prism info` to regenerate from Docker
+
+**Want predictable ports?**
+- Override in your `docker-compose.yml`: `ports: ["5432:5432"]`
+- Trade-off: potential conflicts across sessions
+
+## License
+
+MIT

package/bin/dev-prism.js

@@ -17,19 +17,19 @@ const program = new Command();
 program
   .name('dev-prism')
   .description('CLI tool for managing isolated parallel development sessions')
-  .version('0.3.0');
+  .version('0.6.0');
 
 program
-  .command('create [sessionId]')
+  .command('create')
   .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('-b, --branch <branch>', 'Git branch name (default: session/TIMESTAMP)')
   .option('-W, --without <apps>', 'Exclude apps (comma-separated: app,web,widget)', (val) => val.split(','))
   .option('--no-detach', 'Stream container logs after starting (default: detach)')
   .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, {
+    await createSession(projectRoot, undefined, {
       mode: options.mode,
       branch: options.branch,
       detach: options.detach,
@@ -39,20 +39,19 @@ program
   });
 
 program
-  .command('destroy [sessionId]')
-  .description('Destroy a development session')
+  .command('destroy [directory]')
+  .description('Destroy a development session (defaults to current directory)')
   .option('-a, --all', 'Destroy all sessions')
-  .action(async (sessionId, options) => {
-    const projectRoot = process.cwd();
-    await destroySession(projectRoot, sessionId, { all: options.all });
+  .action(async (directory, options) => {
+    const workingDir = directory || process.cwd();
+    await destroySession(workingDir, { all: options.all });
   });
 
 program
   .command('list')
   .description('List all active development sessions')
   .action(async () => {
-    const projectRoot = process.cwd();
-    await listSessions(projectRoot);
+    await listSessions();
   });
 
 program
@@ -63,35 +62,35 @@ program
   });
 
 program
-  .command('start <sessionId>')
-  .description('Start Docker services for a session')
+  .command('start [directory]')
+  .description('Start Docker services for a session (defaults to current directory)')
   .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, {
+  .action(async (directory, options) => {
+    const workingDir = directory || process.cwd();
+    await startSession(workingDir, {
       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);
+  .command('stop [directory]')
+  .description('Stop Docker services for a session (defaults to current directory)')
+  .action(async (directory) => {
+    const workingDir = directory || process.cwd();
+    await stopSession(workingDir);
   });
 
 program
-  .command('logs <sessionId>')
-  .description('Stream logs from a session\'s Docker services')
+  .command('logs [directory]')
+  .description('Stream logs from a session\'s Docker services (defaults to current directory)')
   .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, {
+  .action(async (directory, options) => {
+    const workingDir = directory || process.cwd();
+    await streamLogs(workingDir, {
       mode: options.mode,
       without: options.without,
       tail: options.tail,
@@ -102,8 +101,7 @@ program
   .command('stop-all')
   .description('Stop all running sessions (preserves data)')
   .action(async () => {
-    const projectRoot = process.cwd();
-    await stopAllSessions(projectRoot);
+    await stopAllSessions();
   });
 
 program
@@ -111,8 +109,7 @@ program
   .description('Remove all stopped sessions (destroys data)')
   .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
@@ -136,21 +133,21 @@ ${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('create')}           Create a new session
+  ${chalk.cyan('destroy')} [dir]    Destroy a session (defaults to current directory)
+  ${chalk.cyan('list')}             List all active sessions
   ${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('start')} [dir]      Start Docker services (defaults to current directory)
+  ${chalk.cyan('stop')} [dir]       Stop Docker services (defaults to current directory)
   ${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('logs')} [dir]       Stream logs (defaults to current directory)
+  ${chalk.cyan('prune')}            Remove all stopped session directories
 
 ${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)')}
@@ -165,12 +162,18 @@ ${chalk.bold('EXAMPLES')}
   ${chalk.gray('# Check session status in current directory')}
   $ dev-prism info
 
-  ${chalk.gray('# Stop all running sessions before switching context')}
+  ${chalk.gray('# Stop session in current directory')}
+  $ dev-prism stop
+
+  ${chalk.gray('# Stop all running sessions')}
   $ dev-prism stop-all
 
-  ${chalk.gray('# Clean up old stopped sessions')}
+  ${chalk.gray('# Clean up old stopped session directories')}
   $ dev-prism prune
 
+  ${chalk.gray('# Destroy session in current directory')}
+  $ dev-prism destroy
+
   ${chalk.gray('# Destroy all sessions')}
   $ dev-prism destroy --all
 

package/dist/chunk-24OM3LGM.js

@@ -0,0 +1,35 @@
+import {
+  listActiveSessions
+} from "./chunk-DQER5GNG.js";
+
+// src/commands/list.ts
+import chalk from "chalk";
+async function listSessions() {
+  const sessions = await listActiveSessions();
+  if (sessions.length === 0) {
+    console.log(chalk.gray("No active sessions found."));
+    console.log(chalk.gray("\nTo create a session:"));
+    console.log(chalk.cyan("  dev-prism create"));
+    return;
+  }
+  console.log(chalk.blue("Active Sessions:"));
+  console.log(chalk.gray("================\n"));
+  for (const session of sessions) {
+    const statusIcon = session.running ? chalk.green("\u25CF") : chalk.red("\u25CB");
+    const statusText = session.running ? chalk.green("running") : chalk.gray("stopped");
+    const containerCount = session.containers.length;
+    console.log(`${statusIcon} Session ${statusText} (${containerCount} container${containerCount !== 1 ? "s" : ""})`);
+    console.log(chalk.gray(`  Directory: ${session.workingDir}`));
+    if (session.ports.length > 0) {
+      console.log(chalk.gray("  Ports:"));
+      for (const port of session.ports) {
+        console.log(chalk.cyan(`    ${port.service}: http://localhost:${port.externalPort}`));
+      }
+    }
+    console.log("");
+  }
+}
+
+export {
+  listSessions
+};