dev-prism 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Emil Bryggare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# dev-prism
+
+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.
+
+## 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
+
+All Docker configuration lives in `docker-compose.session.yml` in your project - a standard file you control.
+
+## Features
+
+- **Git worktrees** for isolated working directories
+- **Docker Compose** handles all container orchestration
+- **Unique ports** per session (calculated from session ID)
+- **Two modes**: Docker (apps in containers) or Native (apps run locally)
+- **Portable**: Works with any project
+
+## Installation
+
+```bash
+npm install -g dev-prism
+# or
+pnpm add -D dev-prism
+```
+
+## Usage
+
+### Create a session
+
+```bash
+# Docker mode (default) - apps run in containers
+dev-prism create 001
+
+# Native mode - only infrastructure in Docker, apps run via pnpm dev
+dev-prism create 001 --mode=native
+
+# In-place mode - use current directory instead of creating worktree
+dev-prism create 001 --in-place
+```
+
+**Note:** In-place sessions are not shown in `dev-prism list` (which only lists worktree-based sessions). Use `dev-prism info` from within an in-place session directory to see its details.
+
+### List sessions
+
+```bash
+dev-prism list
+```
+
+### Session info (for current directory)
+
+```bash
+dev-prism info
+```
+
+### Start/Stop services
+
+```bash
+dev-prism stop 001   # Stop without destroying
+dev-prism start 001  # Start again
+dev-prism stop-all   # Stop all sessions
+```
+
+### View logs
+
+```bash
+dev-prism logs 001
+```
+
+### Destroy a session
+
+```bash
+dev-prism destroy 001     # Destroy specific session
+dev-prism destroy --all   # Destroy all sessions
+```
+
+## Port Allocation
+
+Formula: `port = portBase + (sessionId * 100) + offset`
+
+With base port 47000:
+
+| Service        | Session 001 | Session 002 | Session 003 |
+|----------------|-------------|-------------|-------------|
+| CONVAS_APP_PORT| 47100       | 47200       | 47300       |
+| CONVAS_WEB_PORT| 47101       | 47201       | 47301       |
+| POSTGRES_PORT  | 47110       | 47210       | 47310       |
+| MAILPIT_SMTP   | 47111       | 47211       | 47311       |
+| MAILPIT_WEB    | 47112       | 47212       | 47312       |
+
+## Configuration
+
+### session.config.mjs (minimal)
+
+```javascript
+export default {
+  portBase: 47000,
+  sessionsDir: '../my-project-sessions',
+
+  // Port offsets - become env vars for docker-compose
+  ports: {
+    POSTGRES_PORT: 10,
+    REDIS_PORT: 11,
+    APP_PORT: 0,
+  },
+
+  // Optional: app-specific env for CLI commands from host
+  appEnv: {
+    'apps/my-app': {
+      DATABASE_URL: 'postgresql://postgres:postgres@localhost:${POSTGRES_PORT}/postgres',
+    },
+  },
+
+  setup: ['pnpm install', 'pnpm db:push'],
+};
+```
+
+### docker-compose.session.yml (standard Docker Compose)
+
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    container_name: postgres-${SESSION_ID}
+    ports:
+      - "${POSTGRES_PORT}: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}
+    ports:
+      - "${APP_PORT}:3000"
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
+    depends_on:
+      postgres:
+        condition: service_healthy
+```
+
+## How It Works
+
+1. **Create session**: `dev-prism create 001`
+   - Creates git worktree at `../project-sessions/session-001`
+   - Generates `.env.session` with calculated ports
+   - Runs `docker compose --env-file .env.session up -d`
+   - Runs setup commands
+
+2. **Docker Compose** reads `.env.session` and substitutes `${VAR}` placeholders
+
+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`
+
+## 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
+```
+
+Example `.env.session`:
+```bash
+SESSION_ID=001
+POSTGRES_PORT=47110
+MAILPIT_SMTP_PORT=47111
+MAILPIT_WEB_PORT=47112
+CONVAS_APP_PORT=47100
+```
+
+## 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 001`

package/bin/dev-prism.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createSession } from '../dist/commands/create.js';
+import { destroySession } from '../dist/commands/destroy.js';
+import { listSessions } from '../dist/commands/list.js';
+import { installClaude } from '../dist/commands/claude.js';
+
+const program = new Command();
+
+program
+  .name('dev-prism')
+  .description('CLI tool for managing isolated parallel development sessions')
+  .version('0.1.0');
+
+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)')
+  .option('--in-place', 'Run in current directory instead of creating a worktree')
+  .action(async (sessionId, options) => {
+    const projectRoot = process.cwd();
+    await createSession(projectRoot, sessionId, {
+      mode: options.mode,
+      branch: options.branch,
+      detach: options.detach,
+      without: options.without,
+      inPlace: options.inPlace,
+    });
+  });
+
+program
+  .command('destroy [sessionId]')
+  .description('Destroy a development session')
+  .option('-a, --all', 'Destroy all sessions')
+  .action(async (sessionId, options) => {
+    const projectRoot = process.cwd();
+    await destroySession(projectRoot, sessionId, { all: options.all });
+  });
+
+program
+  .command('list')
+  .description('List all active development sessions')
+  .action(async () => {
+    const projectRoot = process.cwd();
+    await listSessions(projectRoot);
+  });
+
+program
+  .command('info')
+  .description('Show session info for current directory (useful for --in-place sessions)')
+  .action(async () => {
+    const cwd = process.cwd();
+    const chalk = (await import('chalk')).default;
+    const { existsSync, readFileSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const docker = await import('../dist/lib/docker.js');
+
+    const envFile = resolve(cwd, '.env.session');
+    if (!existsSync(envFile)) {
+      console.log(chalk.yellow('No .env.session found in current directory.'));
+      console.log(chalk.gray('Run `dev-prism create --in-place` to create a session here.'));
+      process.exit(1);
+    }
+
+    // Parse .env.session
+    const envContent = readFileSync(envFile, 'utf-8');
+    const env = {};
+    for (const line of envContent.split('\n')) {
+      const match = line.match(/^([^=]+)=(.*)$/);
+      if (match) {
+        env[match[1]] = match[2];
+      }
+    }
+
+    const sessionId = env.SESSION_ID || 'unknown';
+    const running = await docker.isRunning({ cwd });
+
+    console.log(chalk.blue(`\nSession ${sessionId}`));
+    console.log(chalk.gray(`Directory: ${cwd}`));
+    console.log(running ? chalk.green('Status: running') : chalk.yellow('Status: stopped'));
+
+    console.log(chalk.gray('\nPorts:'));
+    for (const [key, value] of Object.entries(env)) {
+      if (key.includes('PORT')) {
+        console.log(chalk.gray(`  ${key}: ${value}`));
+      }
+    }
+
+    console.log(chalk.gray('\nURLs:'));
+    for (const [key, value] of Object.entries(env)) {
+      if (key.includes('APP') || key.includes('WEB') || key.includes('WIDGET')) {
+        if (key.includes('PORT')) {
+          console.log(chalk.cyan(`  ${key.replace('_PORT', '')}: http://localhost:${value}`));
+        }
+      }
+    }
+    console.log('');
+  });
+
+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();
+    const { loadConfig, getSessionDir } = await import('../dist/lib/config.js');
+    const docker = await import('../dist/lib/docker.js');
+
+    const config = await loadConfig(projectRoot);
+    const sessionDir = getSessionDir(config, projectRoot, sessionId);
+    let profiles;
+    if (options.mode === 'docker') {
+      const allApps = config.apps ?? ['app', 'web', 'widget'];
+      const excludeApps = options.without ?? [];
+      profiles = allApps.filter((app) => !excludeApps.includes(app));
+    }
+
+    await docker.up({ cwd: sessionDir, profiles });
+  });
+
+program
+  .command('stop <sessionId>')
+  .description('Stop Docker services for a session (without destroying)')
+  .action(async (sessionId) => {
+    const projectRoot = process.cwd();
+    const { loadConfig, getSessionDir } = await import('../dist/lib/config.js');
+    const { execa } = await import('execa');
+
+    const config = await loadConfig(projectRoot);
+    const sessionDir = getSessionDir(config, projectRoot, sessionId);
+
+    // Use stop instead of down to preserve volumes
+    await execa(
+      'docker',
+      ['compose', '-f', 'docker-compose.session.yml', '--env-file', '.env.session', 'stop'],
+      { cwd: sessionDir, stdio: 'inherit' }
+    );
+  });
+
+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();
+    const { loadConfig, getSessionDir } = await import('../dist/lib/config.js');
+    const { execa } = await import('execa');
+
+    const config = await loadConfig(projectRoot);
+    const sessionDir = getSessionDir(config, projectRoot, sessionId);
+    let profileFlags = [];
+    if (options.mode === 'docker') {
+      const allApps = config.apps ?? ['app', 'web', 'widget'];
+      const excludeApps = options.without ?? [];
+      const profiles = allApps.filter((app) => !excludeApps.includes(app));
+      profileFlags = profiles.flatMap((p) => ['--profile', p]);
+    }
+
+    const args = [
+      'compose',
+      '-f', 'docker-compose.session.yml',
+      '--env-file', '.env.session',
+      ...profileFlags,
+      'logs',
+      '-f',
+      '--tail', options.tail,
+    ];
+
+    await execa('docker', args, { cwd: sessionDir, stdio: 'inherit' });
+  });
+
+program
+  .command('stop-all')
+  .description('Stop all running sessions (preserves data)')
+  .action(async () => {
+    const projectRoot = process.cwd();
+    const chalk = (await import('chalk')).default;
+    const { loadConfig, getSessionDir } = await import('../dist/lib/config.js');
+    const { getSessionWorktrees } = await import('../dist/lib/worktree.js');
+    const docker = await import('../dist/lib/docker.js');
+    const { existsSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+
+    const config = await loadConfig(projectRoot);
+    const sessions = await getSessionWorktrees(projectRoot);
+
+    if (sessions.length === 0) {
+      console.log(chalk.gray('No sessions found.'));
+      return;
+    }
+
+    // Find running sessions
+    const runningSessions = [];
+    for (const session of sessions) {
+      const envFile = resolve(session.path, '.env.session');
+      if (existsSync(envFile)) {
+        const running = await docker.isRunning({ cwd: session.path });
+        if (running) {
+          runningSessions.push(session);
+        }
+      }
+    }
+
+    if (runningSessions.length === 0) {
+      console.log(chalk.gray('No running sessions found.'));
+      return;
+    }
+
+    console.log(chalk.blue(`Stopping ${runningSessions.length} running session(s)...\n`));
+
+    // Get all app profiles and service names to ensure we stop everything
+    const allApps = config.apps ?? ['app', 'web', 'widget'];
+    const profileFlags = allApps.flatMap((p) => ['--profile', p]);
+    // Explicitly list all services to stop (infrastructure + apps)
+    const allServices = ['postgres', 'mailpit', 'convas-app', 'convas-web', 'convas-widget'];
+
+    const { execa } = await import('execa');
+    for (const session of runningSessions) {
+      console.log(chalk.gray(`  Stopping session ${session.sessionId}...`));
+      try {
+        await execa(
+          'docker',
+          ['compose', '-f', 'docker-compose.session.yml', '--env-file', '.env.session', ...profileFlags, 'stop', ...allServices],
+          { cwd: session.path, stdio: 'pipe' }
+        );
+        console.log(chalk.green(`  Session ${session.sessionId} stopped.`));
+      } catch (error) {
+        console.log(chalk.yellow(`  Warning: Could not stop session ${session.sessionId}`));
+      }
+    }
+
+    console.log(chalk.green(`\nStopped ${runningSessions.length} session(s).`));
+  });
+
+program
+  .command('prune')
+  .description('Remove all stopped sessions (destroys data)')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (options) => {
+    const projectRoot = process.cwd();
+    const chalk = (await import('chalk')).default;
+    const { loadConfig } = await import('../dist/lib/config.js');
+    const { getSessionWorktrees, removeWorktree } = await import('../dist/lib/worktree.js');
+    const docker = await import('../dist/lib/docker.js');
+    const { existsSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const readline = await import('node:readline');
+
+    const config = await loadConfig(projectRoot);
+    const sessions = await getSessionWorktrees(projectRoot);
+
+    if (sessions.length === 0) {
+      console.log(chalk.gray('No sessions found.'));
+      return;
+    }
+
+    // Find stopped sessions
+    const stoppedSessions = [];
+    for (const session of sessions) {
+      const envFile = resolve(session.path, '.env.session');
+      let running = false;
+      if (existsSync(envFile)) {
+        running = await docker.isRunning({ cwd: session.path });
+      }
+      if (!running) {
+        stoppedSessions.push(session);
+      }
+    }
+
+    if (stoppedSessions.length === 0) {
+      console.log(chalk.gray('No stopped sessions to prune.'));
+      return;
+    }
+
+    console.log(chalk.yellow(`\nFound ${stoppedSessions.length} stopped session(s) to prune:`));
+    for (const session of stoppedSessions) {
+      console.log(chalk.gray(`  - Session ${session.sessionId} (${session.branch})`));
+    }
+    console.log('');
+
+    // Confirm unless --yes flag provided
+    if (!options.yes) {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      const answer = await new Promise((resolve) => {
+        rl.question(chalk.red('Are you sure you want to delete these sessions? This cannot be undone. [y/N] '), resolve);
+      });
+      rl.close();
+
+      if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+        console.log(chalk.gray('Cancelled.'));
+        return;
+      }
+    }
+
+    console.log(chalk.blue('\nPruning stopped sessions...\n'));
+
+    for (const session of stoppedSessions) {
+      console.log(chalk.gray(`  Removing session ${session.sessionId}...`));
+      try {
+        // Clean up any docker resources
+        const envFile = resolve(session.path, '.env.session');
+        if (existsSync(envFile)) {
+          try {
+            await docker.down({ cwd: session.path });
+          } catch {
+            // Ignore errors - containers might already be removed
+          }
+        }
+        // Remove worktree and branch
+        await removeWorktree(projectRoot, session.path, session.branch);
+        console.log(chalk.green(`  Session ${session.sessionId} removed.`));
+      } catch (error) {
+        console.log(chalk.yellow(`  Warning: Could not fully remove session ${session.sessionId}`));
+      }
+    }
+
+    console.log(chalk.green(`\nPruned ${stoppedSessions.length} session(s).`));
+  });
+
+program
+  .command('claude')
+  .description('Install Claude Code integration (skill + CLAUDE.md)')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(async (options) => {
+    await installClaude(process.cwd(), { force: options.force });
+  });
+
+program
+  .command('help')
+  .description('Show detailed help and examples')
+  .action(async () => {
+    const chalk = (await import('chalk')).default;
+
+    console.log(`
+${chalk.bold('dev-prism')} - Manage isolated parallel development sessions
+
+${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.bold('EXAMPLES')}
+  ${chalk.gray('# Create a new session (auto-assigns next available ID)')}
+  $ dev-prism create
+
+  ${chalk.gray('# Create session with specific branch')}
+  $ 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('# Stop all running sessions before switching context')}
+  $ dev-prism stop-all
+
+  ${chalk.gray('# Clean up old stopped sessions')}
+  $ dev-prism prune
+
+  ${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.bold('MORE INFO')}
+  Run ${chalk.cyan('dev-prism <command> --help')} for command-specific options
+`);
+  });
+
+program.parse();

package/dist/chunk-25WQHUYW.js

@@ -0,0 +1,46 @@
+// src/lib/config.ts
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+var DEFAULT_CONFIG = {
+  portBase: 47e3,
+  sessionsDir: "../sessions",
+  ports: {
+    POSTGRES_PORT: 10
+  },
+  setup: ["pnpm install"]
+};
+async function loadConfig(projectRoot) {
+  let configPath = resolve(projectRoot, "session.config.mjs");
+  if (!existsSync(configPath)) {
+    configPath = resolve(projectRoot, "session.config.js");
+  }
+  if (!existsSync(configPath)) {
+    console.warn("No session.config.mjs found, using defaults");
+    return DEFAULT_CONFIG;
+  }
+  try {
+    const configUrl = pathToFileURL(configPath).href;
+    const module = await import(configUrl);
+    const userConfig = module.default || module;
+    return {
+      ...DEFAULT_CONFIG,
+      ...userConfig
+    };
+  } catch (error) {
+    console.error(`Failed to load config from ${configPath}:`, error);
+    return DEFAULT_CONFIG;
+  }
+}
+function getSessionsDir(config, projectRoot) {
+  return resolve(projectRoot, config.sessionsDir);
+}
+function getSessionDir(config, projectRoot, sessionId) {
+  return resolve(getSessionsDir(config, projectRoot), `session-${sessionId}`);
+}
+
+export {
+  loadConfig,
+  getSessionsDir,
+  getSessionDir
+};