tlc-claude-code 0.7.7 → 0.8.0

package/README.md

@@ -102,6 +102,7 @@ TLC knows where you are and what's next.
 | `/tlc:who` | See who's working on what |
 | `/tlc:bug` | Log a bug |
 | `/tlc:server` | Start dev server with dashboard |
+| `npx tlc-claude-code init` | Add Docker dev launcher to project |
 
 ### Integration Commands
 
@@ -138,17 +139,40 @@ TLC supports distributed teams with git-based coordination.
 
 ## Dev Server
 
-Launch a mini-Replit for your team:
+Launch a mini-Replit for your team. Two options:
+
+### Option 1: Docker (Recommended)
+
+One-click launcher that runs your app, database, and dashboard in containers:
 
 ```bash
-/tlc:server
-```
+# Add launcher to your project
+npx tlc-claude-code init
 
+# Then double-click tlc-start.bat (Windows)
 ```
-Dashboard: http://localhost:3147
-Share:     http://192.168.1.x:3147
+
+**What you get:**
+- **Dashboard**: http://localhost:3147 — Live preview, logs, tasks
+- **App**: http://localhost:5000 — Your running application
+- **Database**: localhost:5433 — PostgreSQL auto-provisioned
+
+Containers are named `tlc-{project}-*` so you can run multiple projects simultaneously.
+
+**Requirements:** [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+> **Note:** Windows only for now. macOS/Linux support coming soon.
+
+### Option 2: Direct (No Docker)
+
+```bash
+/tlc:server
 ```
 
+Runs the app directly on your machine with auto-detected start command.
+
+### Features
+
 - **Live preview** — Your app embedded in dashboard
 - **Real-time logs** — App, tests, git activity
 - **Bug submission** — Web form for QA
@@ -217,6 +241,16 @@ PROJECT.md                    Project overview
     1-PLAN.md                 Phase 1 tasks
     2-PLAN.md                 Phase 2 tasks
 .tlc.json                     Configuration
+tlc-start.bat                 Docker dev launcher (Windows, gitignored)
+```
+
+### TLC Installation Files
+
+```
+C:\Code\TLC\                  (or your install location)
+  start-dev.ps1               PowerShell launcher
+  docker-compose.dev.yml      Container orchestration
+  server/                     Dashboard server
 ```
 
 ---

package/bin/init.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+/**
+ * TLC Init - Add TLC dev server launcher to a project
+ * Usage: npx tlc-claude-code init
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectDir = process.cwd();
+
+// Windows batch file content
+const batContent = `@echo off
+:: ========================================
+:: TLC Dev Server Launcher
+:: ========================================
+:: Double-click to start your dev environment
+::
+:: Dashboard: http://localhost:3147
+:: App:       http://localhost:5000
+:: DB Admin:  http://localhost:8080
+:: Database:  localhost:5433
+:: ========================================
+
+setlocal
+
+:: Find TLC installation (check common locations)
+set TLC_DIR=
+if exist "C:\\Code\\TLC\\start-dev.ps1" set TLC_DIR=C:\\Code\\TLC
+if exist "%USERPROFILE%\\Code\\TLC\\start-dev.ps1" set TLC_DIR=%USERPROFILE%\\Code\\TLC
+if exist "%~dp0..\\TLC\\start-dev.ps1" set TLC_DIR=%~dp0..\\TLC
+
+:: Also check if installed globally via npm
+for /f "delims=" %%i in ('npm root -g 2^>nul') do (
+    if exist "%%i\\tlc-claude-code\\start-dev.ps1" set TLC_DIR=%%i\\tlc-claude-code
+)
+
+if "%TLC_DIR%"=="" (
+    echo [TLC] ERROR: Could not find TLC installation
+    echo [TLC] Install TLC or set TLC_DIR in this script
+    echo [TLC] See: https://github.com/jurgencalleja/TLC
+    pause
+    exit /b 1
+)
+
+:: Get project directory without trailing backslash
+set PROJECT_PATH=%~dp0
+if "%PROJECT_PATH:~-1%"=="\\" set PROJECT_PATH=%PROJECT_PATH:~0,-1%
+
+echo [TLC] Found TLC at: %TLC_DIR%
+echo [TLC] Starting dev server for: %PROJECT_PATH%
+echo.
+
+powershell -ExecutionPolicy Bypass -File "%TLC_DIR%\\start-dev.ps1" -ProjectPath "%PROJECT_PATH%"
+
+pause
+`;
+
+// macOS/Linux shell script (placeholder for future)
+const shContent = `#!/bin/bash
+# ========================================
+# TLC Dev Server Launcher
+# ========================================
+# Dashboard: http://localhost:3147
+# App:       http://localhost:5000
+# DB Admin:  http://localhost:8080
+# Database:  localhost:5433
+# ========================================
+
+echo "[TLC] macOS/Linux support coming soon!"
+echo "[TLC] For now, run manually:"
+echo ""
+echo "  export PROJECT_DIR=\\$(pwd)"
+echo "  export COMPOSE_PROJECT_NAME=\\$(basename \\$(pwd) | tr -cd 'a-z0-9')"
+echo "  docker-compose -f /path/to/TLC/docker-compose.dev.yml up"
+echo ""
+
+# TODO: Implement full macOS/Linux support
+`;
+
+console.log('');
+console.log('  ============================');
+console.log('       TLC Project Init');
+console.log('  ============================');
+console.log('');
+
+// Detect OS
+const isWindows = process.platform === 'win32';
+
+if (isWindows) {
+    // Create Windows launcher
+    const batPath = path.join(projectDir, 'tlc-start.bat');
+
+    if (fs.existsSync(batPath)) {
+        console.log('[TLC] tlc-start.bat already exists, overwriting...');
+    }
+    fs.writeFileSync(batPath, batContent);
+    console.log('[TLC] Created: tlc-start.bat');
+} else {
+    // Create Unix launcher (placeholder)
+    const shPath = path.join(projectDir, 'tlc-start.sh');
+
+    if (fs.existsSync(shPath)) {
+        console.log('[TLC] tlc-start.sh already exists, overwriting...');
+    }
+    fs.writeFileSync(shPath, shContent, { mode: 0o755 });
+    console.log('[TLC] Created: tlc-start.sh');
+    console.log('[TLC] Note: Full macOS/Linux support coming soon!');
+}
+
+// Add to .gitignore if not already there
+const gitignorePath = path.join(projectDir, '.gitignore');
+
+if (fs.existsSync(gitignorePath)) {
+    let gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    if (!gitignore.includes('tlc-start')) {
+        gitignore += '\\n# TLC dev server launcher (local only)\\ntlc-start.*\\n';
+        fs.writeFileSync(gitignorePath, gitignore);
+        console.log('[TLC] Added tlc-start.* to .gitignore');
+    }
+} else {
+    fs.writeFileSync(gitignorePath, '# TLC dev server launcher (local only)\\ntlc-start.*\\n');
+    console.log('[TLC] Created .gitignore with tlc-start.*');
+}
+
+// Create/update .tlc.json if it doesn't exist
+const tlcConfigPath = path.join(projectDir, '.tlc.json');
+if (!fs.existsSync(tlcConfigPath)) {
+    // Try to detect project settings
+    const pkgPath = path.join(projectDir, 'package.json');
+    let appPort = 3000;
+    let startCommand = 'npm run dev';
+
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            // Detect port from scripts if possible
+            if (pkg.scripts?.dev?.includes('--port')) {
+                const match = pkg.scripts.dev.match(/--port[=\\s]+(\\d+)/);
+                if (match) appPort = parseInt(match[1]);
+            }
+            if (pkg.scripts?.dev?.includes('5000')) appPort = 5000;
+            if (pkg.scripts?.dev?.includes('3000')) appPort = 3000;
+            if (pkg.scripts?.dev?.includes('5173')) appPort = 5173;
+        } catch (e) {
+            // Ignore parsing errors
+        }
+    }
+
+    const tlcConfig = {
+        server: {
+            startCommand: startCommand,
+            appPort: appPort
+        }
+    };
+
+    fs.writeFileSync(tlcConfigPath, JSON.stringify(tlcConfig, null, 2) + '\\n');
+    console.log('[TLC] Created: .tlc.json');
+}
+
+console.log('');
+console.log('[TLC] Setup complete!');
+console.log('');
+
+if (isWindows) {
+    console.log('[TLC] To start your dev server:');
+    console.log('      Double-click tlc-start.bat');
+    console.log('');
+    console.log('[TLC] Or run from command line:');
+    console.log('      .\\\\tlc-start.bat');
+} else {
+    console.log('[TLC] To start your dev server:');
+    console.log('      ./tlc-start.sh');
+}
+
+console.log('');
+console.log('[TLC] Services when running:');
+console.log('      Dashboard: http://localhost:3147');
+console.log('      App:       http://localhost:5000');
+console.log('      DB Admin:  http://localhost:8080');
+console.log('      Database:  localhost:5433');
+console.log('');

package/bin/setup.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawn } = require('child_process');
+const fs = require('fs');
+
+const setupScript = path.join(__dirname, '..', 'server', 'setup.sh');
+
+// Check if running on Windows without WSL
+if (process.platform === 'win32') {
+  console.log('\n[TLC] Windows detected');
+  console.log('[TLC] Please install Docker Desktop from: https://www.docker.com/products/docker-desktop');
+  console.log('[TLC] After installation, TLC will automatically use Docker for databases.\n');
+  process.exit(0);
+}
+
+// Check if setup script exists
+if (!fs.existsSync(setupScript)) {
+  console.error('[TLC] Setup script not found:', setupScript);
+  process.exit(1);
+}
+
+console.log('\n[TLC] Running TLC server setup...');
+console.log('[TLC] This will install Docker and other requirements.');
+console.log('[TLC] You may be prompted for your sudo password.\n');
+
+// Run the setup script with sudo
+const child = spawn('sudo', ['bash', setupScript], {
+  stdio: 'inherit',
+  cwd: process.cwd()
+});
+
+child.on('exit', (code) => {
+  if (code === 0) {
+    console.log('\n[TLC] Setup completed successfully!');
+    console.log('[TLC] Please log out and log back in for Docker permissions to take effect.');
+    console.log('[TLC] Then run: tlc-server\n');
+  } else {
+    console.error('\n[TLC] Setup failed with code:', code);
+  }
+  process.exit(code || 0);
+});

package/docker-compose.dev.yml

@@ -0,0 +1,83 @@
+# TLC Dev Environment
+# Run with: PROJECT_DIR=/path/to/project docker-compose -f docker-compose.dev.yml up
+# Container names will be: tlc-{project-name}-{service}
+
+services:
+  # PostgreSQL Database
+  db:
+    image: postgres:16-alpine
+    container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-db
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - "${DB_PORT:-5433}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  # Your App (runs from project directory)
+  app:
+    image: node:20-alpine
+    container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-app
+    working_dir: /app
+    command: >
+      sh -c "
+        npm install &&
+        echo 'Running database migrations...' &&
+        (npm run db:push 2>/dev/null || npx drizzle-kit push 2>/dev/null || echo 'No migrations to run') &&
+        npm run dev
+      "
+    environment:
+      - NODE_ENV=development
+      - DATABASE_URL=postgres://postgres:postgres@db:5432/app
+      - PORT=5000
+    ports:
+      - "${APP_PORT:-5000}:5000"
+    volumes:
+      - ${PROJECT_DIR:-.}:/app
+      - /app/node_modules
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: on-failure
+
+  # Database GUI (Adminer)
+  dbadmin:
+    image: adminer:latest
+    container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-dbadmin
+    ports:
+      - "${DBADMIN_PORT:-8080}:8080"
+    environment:
+      - ADMINER_DEFAULT_SERVER=db
+      - ADMINER_DESIGN=nette
+    depends_on:
+      - db
+    restart: on-failure
+
+  # TLC Dashboard
+  dashboard:
+    image: node:20-alpine
+    container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-dashboard
+    working_dir: /project
+    command: sh -c "cd /tlc/server && npm install && cd /project && node /tlc/server/index.js --proxy-only"
+    environment:
+      - TLC_PORT=3147
+      - TLC_PROXY_ONLY=true
+      - TLC_APP_PORT=5000
+    ports:
+      - "${DASHBOARD_PORT:-3147}:3147"
+    volumes:
+      - ./server:/tlc/server
+      - ${PROJECT_DIR:-.}:/project
+    depends_on:
+      - app
+    restart: on-failure
+
+volumes:
+  postgres-data:

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "tlc-claude-code",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",
     "tlc-dashboard": "./dashboard/dist/index.js",
-    "tlc-server": "./bin/server.js"
+    "tlc-server": "./bin/server.js",
+    "tlc-setup": "./bin/setup.js",
+    "tlc-init": "./bin/init.js"
   },
   "files": [
     "bin/",
     "dashboard/dist/",
     "dashboard/package.json",
     "server/",
+    "docker-compose.dev.yml",
+    "start-dev.ps1",
+    "start-dev.bat",
     "*.md",
     "install.sh"
   ],

package/server/index.js

@@ -13,9 +13,27 @@ const { detectProject } = require('./lib/project-detector');
 const { parsePlan, parseBugs } = require('./lib/plan-parser');
 const { autoProvision, stopDatabase } = require('./lib/auto-database');
 
+// Handle PGlite WASM crashes gracefully
+process.on('uncaughtException', (err) => {
+  if (err.message && err.message.includes('unreachable')) {
+    console.error('\n[TLC] ⚠️  Database crashed (PGlite WASM limitation)');
+    console.error('[TLC] This happens with heavy concurrent database operations.');
+    console.error('[TLC] Solutions:');
+    console.error('[TLC]   1. Install Docker for stable PostgreSQL support');
+    console.error('[TLC]   2. Use an external PostgreSQL database');
+    console.error('[TLC]   3. Set DATABASE_URL environment variable\n');
+    process.exit(1);
+  }
+  console.error('[TLC] Uncaught exception:', err);
+  process.exit(1);
+});
+
 // Configuration
 const TLC_PORT = parseInt(process.env.TLC_PORT || '3147');
 const PROJECT_DIR = process.cwd();
+const SKIP_DB = process.argv.includes('--skip-db') || process.env.TLC_SKIP_DB === 'true';
+const PROXY_ONLY = process.argv.includes('--proxy-only') || process.env.TLC_PROXY_ONLY === 'true';
+const EXTERNAL_APP_PORT = parseInt(process.env.TLC_APP_PORT || '5000');
 
 // State
 let appProcess = null;
@@ -87,10 +105,14 @@ async function startApp() {
 
   // Auto-provision database if needed
   let extraEnv = {};
-  try {
-    extraEnv = await autoProvision(PROJECT_DIR, (msg) => addLog('app', msg, 'info'));
-  } catch (err) {
-    addLog('app', `Database provisioning failed: ${err.message}`, 'error');
+  if (SKIP_DB) {
+    addLog('app', 'Skipping database auto-provisioning (--skip-db)', 'info');
+  } else {
+    try {
+      extraEnv = await autoProvision(PROJECT_DIR, (msg) => addLog('app', msg, 'info'));
+    } catch (err) {
+      addLog('app', `Database provisioning failed: ${err.message}`, 'error');
+    }
   }
 
   // Kill existing process if any
@@ -424,7 +446,16 @@ async function main() {
   });
 
   setupWatchers();
-  await startApp();
+
+  if (PROXY_ONLY) {
+    // In proxy-only mode, just set the app port for proxying
+    // App is managed externally (e.g., by docker-compose)
+    appPort = EXTERNAL_APP_PORT;
+    console.log(`  Proxy-only mode: forwarding to app on port ${appPort}`);
+    addLog('app', `Proxy-only mode: app expected on port ${appPort}`, 'info');
+  } else {
+    await startApp();
+  }
 
   console.log('  Press Ctrl+C to stop\n');
 }