tlc-claude-code 2.10.0 → 2.10.1

package/.claude/commands/tlc/recall.md

@@ -1,6 +1,6 @@
 # /tlc:recall - Team Memory Search
 
-Search TLC team memory using plain grep. This is intentional: no vector search, no extra services.
+Search TLC team memory through the context engine hybrid search pipeline. Use FTS5 plus vector search when the engine is available, and fall back to grep only when it is not.
 
 ## Usage
 
@@ -10,33 +10,58 @@ Search TLC team memory using plain grep. This is intentional: no vector search,
 
 ## What This Does
 
-1. Searches `.tlc/memory/team/` with `grep -rl "query" .tlc/memory/team/`.
-2. Looks in both `.tlc/memory/team/decisions/` and `.tlc/memory/team/gotchas/`.
-3. Shows the file path, date from the filename, and a matching excerpt.
-4. Uses grep only because it works everywhere.
+1. Opens `.tlc/context.sqlite` through `createContextEngine()`.
+2. Builds a search pipeline with `createSearchPipeline` from `@tlc/context-engine/search-pipeline`.
+3. Runs the context leg with the engine's hybrid FTS5 plus vector search.
+4. Searches TLC memory under `.tlc/memory/team/`.
+5. Falls back to recursive grep only when the context engine or database is unavailable.
 
 ## Search Rules
 
 - Search both `decisions/` and `gotchas/`.
-- Do not use vector search.
-- Do not depend on embeddings, databases, or external services.
-- Prefer simple recursive grep so the command works across projects.
+- Prefer context-engine hybrid search over grep.
+- Use vector ranking when embeddings are available; FTS5-only results are acceptable when vectors are missing.
+- Fall back to grep if `@tlc/context-engine` cannot be loaded or `.tlc/context.sqlite` does not exist yet.
 
 ## Process
 
-### Step 1: Find matching files
+### Step 1: Try the context engine
+
+```js
+import { createContextEngine } from '@tlc/context-engine';
+import { createSearch } from '@tlc/context-engine/retrieval/search';
+import { createSearchPipeline } from '@tlc/context-engine/search-pipeline';
+
+const engine = createContextEngine({ dbPath: '.tlc/context.sqlite' });
+const hybridSearch = createSearch({
+  embeddingStore: {
+    findSimilar(db, queryVec, options) {
+      return engine.embeddings.findSimilar(queryVec, options);
+    },
+  },
+});
+
+const searchAll = createSearchPipeline({
+  search: (db, query, options) => hybridSearch(db, query, options),
+});
+
+const results = await searchAll(engine.db, query, { limit: 10 });
+```
+
+### Step 2: If the engine is unavailable, fall back to grep
 
 ```bash
-grep -rl "query" .tlc/memory/team/
+grep -Ril "query" .tlc/memory/team/
 ```
 
-### Step 2: Display matches
+### Step 3: Display matches
 
 For each matching file, show:
 
 - File path
 - Date parsed from the filename prefix
 - A short matching excerpt from the file body
+- Search source: `context-engine` or `grep-fallback`
 
 ## Example Output
 
@@ -57,3 +82,4 @@ Excerpt: Local timezone conversion caused reporting drift in scheduled jobs.
 - If there are no matches, say so directly.
 - Keep excerpts short and relevant.
 - Search TLC memory under `.tlc/memory/team/`, not Claude-managed memory.
+- Close the context engine after the search when it was opened successfully.

package/.claude/commands/tlc/remember.md

@@ -17,31 +17,32 @@ Or without arguments:
 ## What This Does
 
 1. Captures the provided decision text, or extracts decisions from the recent conversation context if no argument is given.
-2. Writes a markdown file to `.tlc/memory/team/decisions/{date}-{slug}.md`.
-3. Stores TLC-owned frontmatter for later grep-based recall.
-4. Never writes to `~/.claude/projects/.../memory/` because that is Claude memory, not TLC memory.
+2. Appends a JSONL event to `.tlc/events/memory.jsonl` through the context engine event log.
+3. Replays the event into `.tlc/context.sqlite`.
+4. Exports visible `.md` memory files for git visibility under `.tlc/memory/team/decisions/`.
+5. Never writes to `~/.claude/projects/.../memory/` because that is Claude memory, not TLC memory.
 
 ## Write Format
 
-Write the decision as a markdown file with YAML frontmatter:
+Write the canonical record as a JSONL event first:
+
+```json
+{"type":"decision","category":"decision","scope":"team","subject":"use-utc-timestamps","body":"Always use UTC timestamps in the database and in exported logs."}
+```
+
+Then export the visible markdown file with YAML frontmatter:
 
 ```yaml
 ---
-provider: claude
-source: manual
 timestamp: 2026-03-28T12:34:56Z
 type: decision
 scope: team
+category: decision
+subject: "use-utc-timestamps"
 ---
 ```
 
-The filename must be:
-
-```text
-.tlc/memory/team/decisions/{date}-{slug}.md
-```
-
-Example:
+The markdown filename must be:
 
 ```text
 .tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
@@ -53,19 +54,43 @@ Example:
 
 - Use the argument as the decision content.
 - Generate a short slug from the decision.
-- Write the file under `.tlc/memory/team/decisions/`.
+- Append the event with `engine.events.appendEvent('.tlc/events/memory.jsonl', event)`.
+- Replay the log into the database.
+- Export markdown back to `.tlc/memory/team/decisions/`.
 
 ### Without an argument
 
 - Review the recent conversation context.
 - Extract concrete decisions, conventions, or constraints worth preserving.
 - Summarize them clearly.
-- Write one decision file under `.tlc/memory/team/decisions/`.
+- Append one JSONL event.
+- Export one visible markdown file under `.tlc/memory/team/decisions/`.
+
+## Implementation Sketch
+
+```js
+import { createContextEngine } from '@tlc/context-engine';
+import { exportFactsToMarkdown } from '@tlc/context-engine/import/markdown-exporter';
+
+const engine = createContextEngine({ dbPath: '.tlc/context.sqlite' });
+const event = engine.events.appendEvent('.tlc/events/memory.jsonl', {
+  type: 'decision',
+  category: 'decision',
+  scope: 'team',
+  subject: slug,
+  body: decisionText,
+});
+
+engine.events.replayEvents([event]);
+exportFactsToMarkdown(engine.db, '.tlc/memory/team/decisions');
+engine.close();
+```
 
 ## Confirmation
 
 ```text
 Remembered: {summary}
+Event: .tlc/events/memory.jsonl
 File: .tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
 ```
 
@@ -74,3 +99,4 @@ File: .tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
 - Prefer concise, durable statements over raw transcript dumps.
 - Record decisions, not general chatter.
 - Use `.tlc/memory/team/gotchas/` for gotchas, not this command.
+- JSONL is the source of truth; markdown is the human-visible export.

package/.claude/hooks/tlc-session-init.sh

@@ -44,6 +44,15 @@ mkdir -p "$PROJECT_DIR/.tlc/memory/team/decisions" \
          "$PROJECT_DIR/.tlc/memory/team/gotchas" \
          "$PROJECT_DIR/.tlc/memory/.local/sessions" 2>/dev/null
 
+# Bootstrap context engine on first run by importing visible markdown memory.
+CONTEXT_BOOTSTRAP=""
+if node -e "import('@tlc/context-engine/bootstrap').then(()=>process.exit(0)).catch(()=>process.exit(1))" >/dev/null 2>&1; then
+  CONTEXT_BOOTSTRAP="import('@tlc/context-engine').then(async ({ createContextEngine }) => { const { createBootstrap } = await import('@tlc/context-engine/bootstrap'); const { importMarkdownMemories } = await import('@tlc/context-engine/import/markdown-importer'); const { indexProject } = await import('@tlc/context-engine/retrieval/indexer'); const bootstrap = createBootstrap({ contextEngine: createContextEngine, markdownImporter: { importMarkdownMemories }, indexer: { indexProject } }); const result = await bootstrap(process.argv[1]); if ((result.imported || 0) > 0 || (result.indexed || 0) > 0) { console.log('  Context Engine:  ✅ bootstrapped (' + result.imported + ' imported, ' + result.indexed + ' indexed)'); } }).catch(() => {})"
+elif [ -d "$PROJECT_DIR/server/node_modules/@tlc/context-engine" ]; then
+  CONTEXT_BOOTSTRAP="(async () => { const [{ createContextEngine }, { createBootstrap }, { importMarkdownMemories }, { indexProject }] = await Promise.all([import('$PROJECT_DIR/server/node_modules/@tlc/context-engine/src/index.js'), import('$PROJECT_DIR/server/node_modules/@tlc/context-engine/src/bootstrap.js'), import('$PROJECT_DIR/server/node_modules/@tlc/context-engine/src/import/markdown-importer.js'), import('$PROJECT_DIR/server/node_modules/@tlc/context-engine/src/retrieval/indexer.js')]); const bootstrap = createBootstrap({ contextEngine: createContextEngine, markdownImporter: { importMarkdownMemories }, indexer: { indexProject } }); const result = await bootstrap(process.argv[1]); if ((result.imported || 0) > 0 || (result.indexed || 0) > 0) { console.log('  Context Engine:  ✅ bootstrapped (' + result.imported + ' imported, ' + result.indexed + ' indexed)'); } })().catch(() => {})"
+fi
+[ -n "$CONTEXT_BOOTSTRAP" ] && node -e "$CONTEXT_BOOTSTRAP" "$PROJECT_DIR" 2>/dev/null
+
 if curl -sf --max-time 1 "http://localhost:${TLC_PORT}/api/health" > /dev/null 2>&1; then
   echo "  TLC Server:      ✅ running (:${TLC_PORT})"
   # Drain spool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",

package/server/index.js

@@ -23,9 +23,9 @@ const { parsePlan, parseBugs } = require('./lib/plan-parser');
 const { autoProvision, stopDatabase } = require('./lib/auto-database');
 const { GlobalConfig } = require('./lib/global-config');
 const { ProjectScanner } = require('./lib/project-scanner');
-const { createWorkspaceRouter } = require('./lib/workspace-api');
-const { createMemoryApi } = require('./lib/memory-api');
-const { createMemoryStoreAdapter } = require('./lib/memory-store-adapter');
+const { createWorkspaceRouter } = require('./lib/workspace-api');
+const { createMemoryApi } = require('./lib/memory-api');
+const { createMemoryStoreAdapter } = require('./lib/memory-store-adapter');
 const {
   createUserStore,
   createAuthMiddleware,
@@ -86,12 +86,11 @@ const cors = require('cors');
 app.use(cors({ origin: true, credentials: true }));
 
 // Workspace API
-const globalConfig = new GlobalConfig();
-const projectScanner = new ProjectScanner();
-const { observeAndRemember } = require('./lib/memory-observer');
-const { createServerMemoryCapture } = require('./lib/memory-hooks');
-const { createMemoryStoreAdapter } = require('./lib/memory-store-adapter');
-const { checkOllamaHealth } = require('./lib/ollama-health');
+const globalConfig = new GlobalConfig();
+const projectScanner = new ProjectScanner();
+const { observeAndRemember } = require('./lib/memory-observer');
+const { createServerMemoryCapture } = require('./lib/memory-hooks');
+const { checkOllamaHealth } = require('./lib/ollama-health');
 
 // Initialize memory directory structure (non-blocking)
 (async () => {
@@ -110,72 +109,103 @@ const memoryCapture = createServerMemoryCapture({
 });
 
 // Lazy-initialized memory dependencies (ESM modules loaded async)
-const memoryDeps = {
-  observeAndRemember,
-  semanticRecall: null,
-  vectorIndexer: null,
-  embeddingClient: null,
-  vectorStore: null,
-};
+const memoryDeps = {
+  observeAndRemember,
+  contextEngine: null,
+  contextSearch: null,
+  semanticRecall: null,
+  vectorIndexer: null,
+};
 
 // Lazy init: load ESM memory modules on first use
 let memoryInitPromise = null;
-async function initMemoryPipeline() {
-  if (memoryInitPromise) return memoryInitPromise;
-  memoryInitPromise = (async () => {
-    try {
-      const os = require('os');
-      const dbPath = path.join(os.homedir(), '.tlc', 'memory', 'vectors.db');
-
-      // Ensure directory exists
-      const dbDir = path.dirname(dbPath);
-      if (!fs.existsSync(dbDir)) {
-        fs.mkdirSync(dbDir, { recursive: true });
-      }
-
-      const { createEmbeddingClient } = await import('./lib/embedding-client.js');
-      const { createVectorStore } = await import('./lib/vector-store.js');
-      const { createVectorIndexer } = await import('./lib/vector-indexer.js');
-      const { createSemanticRecall } = await import('./lib/semantic-recall.js');
-
-      memoryDeps.embeddingClient = createEmbeddingClient();
-      memoryDeps.vectorStore = await createVectorStore({ dbPath });
-      memoryDeps.vectorIndexer = createVectorIndexer({
-        vectorStore: memoryDeps.vectorStore,
-        embeddingClient: memoryDeps.embeddingClient,
-      });
-      memoryDeps.semanticRecall = createSemanticRecall({
-        vectorStore: memoryDeps.vectorStore,
-        embeddingClient: memoryDeps.embeddingClient,
-      });
-
-      console.log('[TLC] Memory pipeline initialized (vector store at', dbPath + ')');
-    } catch (err) {
-      console.warn('[TLC] Memory pipeline unavailable:', err.message);
-      // Non-fatal: server works without vector store
-    }
-  })();
+async function initMemoryPipeline() {
+  if (memoryInitPromise) return memoryInitPromise;
+  memoryInitPromise = (async () => {
+    try {
+      const dbPath = path.join(PROJECT_DIR, '.tlc', 'context.sqlite');
+
+      // Ensure directory exists
+      const dbDir = path.dirname(dbPath);
+      if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+      }
+
+      const [{ createContextEngine }, { createSearchPipeline }, { createSearch }, { indexProject }] = await Promise.all([
+        import('@tlc/context-engine'),
+        import('@tlc/context-engine/search-pipeline'),
+        import('@tlc/context-engine/retrieval/search'),
+        import('@tlc/context-engine/retrieval/indexer'),
+      ]);
+
+      const contextEngine = createContextEngine({ dbPath });
+      const search = createSearch({
+        embeddingStore: {
+          findSimilar(db, queryVec, options) {
+            return contextEngine.embeddings.findSimilar(queryVec, options);
+          },
+        },
+      });
+      const searchPipeline = createSearchPipeline({
+        search: (db, query, options = {}) => search(db, query, options),
+      });
+
+      memoryDeps.contextEngine = contextEngine;
+      memoryDeps.contextSearch = searchPipeline;
+      memoryDeps.vectorIndexer = {
+        indexAll: async (projectRoot) => indexProject(contextEngine.db, projectRoot),
+      };
+      memoryDeps.semanticRecall = {
+        recall: async (query, _context = {}, options = {}) => {
+          const scope = options.scope ? [options.scope] : undefined;
+          const results = await searchPipeline(contextEngine.db, query, {
+            limit: options.limit,
+            scopes: scope,
+            queryVec: options.queryVec ?? null,
+          });
+
+          return results.map((result) => ({
+            id: result.uri,
+            uri: result.uri,
+            text: result.body || result.title || '',
+            title: result.title || result.uri,
+            body: result.body || '',
+            score: Number.isFinite(result.score) ? result.score : 0,
+            type: result.source === 'context' ? 'context' : 'codedb',
+            source: {
+              sourceFile: result.uri,
+              provider: result.source,
+            },
+            sourceFile: result.uri,
+            permanent: false,
+          }));
+        },
+      };
+
+      console.log('[TLC] Memory pipeline initialized (context engine at', dbPath + ')');
+    } catch (err) {
+      console.warn('[TLC] Memory pipeline unavailable:', err.message);
+      // Non-fatal: server works without vector store
+    }
+  })();
   return memoryInitPromise;
 }
 
 // Start memory init in background (non-blocking)
 initMemoryPipeline();
 
-const memoryApi = createMemoryApi({
-  semanticRecall: { recall: async (...args) => {
-    await initMemoryPipeline();
-    return memoryDeps.semanticRecall ? memoryDeps.semanticRecall.recall(...args) : [];
-  }},
-  vectorIndexer: { indexAll: async (...args) => {
-    await initMemoryPipeline();
-    return memoryDeps.vectorIndexer ? memoryDeps.vectorIndexer.indexAll(...args) : { indexed: 0 };
-  }},
-  richCapture: { processChunk: async () => ({ stored: false }) },
-  embeddingClient: { embed: async (...args) => {
-    await initMemoryPipeline();
-    return memoryDeps.embeddingClient ? memoryDeps.embeddingClient.embed(...args) : [];
-  }},
-  memoryStore: (() => {
+const memoryApi = createMemoryApi({
+  semanticRecall: { recall: async (...args) => {
+    await initMemoryPipeline();
+    return memoryDeps.semanticRecall ? memoryDeps.semanticRecall.recall(...args) : [];
+  }},
+  vectorIndexer: { indexAll: async (...args) => {
+    await initMemoryPipeline();
+    return memoryDeps.vectorIndexer ? memoryDeps.vectorIndexer.indexAll(...args) : { indexed: 0 };
+  }},
+  richCapture: { processChunk: async () => ({ stored: false }) },
+  embeddingClient: { embed: async () => [] },
+  memoryStore: (() => {
     const adapter = createMemoryStoreAdapter(PROJECT_DIR);
     return {
       listConversations: async () => ({ items: [], total: 0 }), // TODO Phase 74: rich conversation capture

package/server/package-lock.json

@@ -10,6 +10,7 @@
       "dependencies": {
         "@electric-sql/pglite": "^0.3.15",
         "@electric-sql/pglite-socket": "^0.0.20",
+        "@tlc/context-engine": "file:../../tlc-context-engine",
         "better-sqlite3": "^12.6.2",
         "chokidar": "^3.5.3",
         "cookie-parser": "^1.4.7",
@@ -22,6 +23,7 @@
         "sqlite-vec": "^0.1.7-alpha.2",
         "ssh2": "^1.17.0",
         "sudo-prompt": "^9.2.1",
+        "tlc-context-engine": "^0.1.0",
         "typescript": "^5.9.3",
         "ws": "^8.14.2"
       },
@@ -33,6 +35,17 @@
         "vitest": "^4.0.18"
       }
     },
+    "../../tlc-context-engine": {
+      "version": "0.1.0",
+      "license": "MIT",
+      "devDependencies": {
+        "better-sqlite3": "^11.9.1",
+        "vitest": "^3.2.4"
+      },
+      "peerDependencies": {
+        "better-sqlite3": ">=11.0.0"
+      }
+    },
     "node_modules/@balena/dockerignore": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/@balena/dockerignore/-/dockerignore-1.0.2.tgz",
@@ -1009,6 +1022,10 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@tlc/context-engine": {
+      "resolved": "../../tlc-context-engine",
+      "link": true
+    },
     "node_modules/@types/chai": {
       "version": "5.2.3",
       "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
@@ -3714,6 +3731,15 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/tlc-context-engine": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/tlc-context-engine/-/tlc-context-engine-0.1.0.tgz",
+      "integrity": "sha512-OhLcPBmHuAYSv3XniJPnGcyDB2RaBi8wk/TsWQAaokkX7NkYhDFWWCrVsOqHTSKNMVf1M+xx+gvUFib5qaUCXA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "better-sqlite3": ">=11.0.0"
+      }
+    },
     "node_modules/to-regex-range": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",

package/server/package.json

@@ -27,6 +27,7 @@
     "sqlite-vec": "^0.1.7-alpha.2",
     "ssh2": "^1.17.0",
     "sudo-prompt": "^9.2.1",
+    "tlc-context-engine": "^0.1.0",
     "typescript": "^5.9.3",
     "ws": "^8.14.2"
   },

package/server/setup.sh

@@ -1,271 +1,271 @@
-#!/bin/bash
-#
-# TLC Server Setup Script
-# Installs Docker and other requirements for TLC dev server
-#
-# Usage: sudo ./setup.sh
-#
-
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-log_info() {
-    echo -e "${GREEN}[TLC]${NC} $1"
-}
-
-log_warn() {
-    echo -e "${YELLOW}[TLC]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[TLC]${NC} $1"
-}
-
-# Check if running as root
-if [ "$EUID" -ne 0 ]; then
-    log_error "Please run with sudo: sudo ./setup.sh"
-    exit 1
-fi
-
-# Get the actual user (not root)
-ACTUAL_USER=${SUDO_USER:-$USER}
-if [ "$ACTUAL_USER" = "root" ]; then
-    log_error "Please run as a regular user with sudo, not as root directly"
-    exit 1
-fi
-
-log_info "Setting up TLC server requirements for user: $ACTUAL_USER"
-
-# Detect OS
-detect_os() {
-    if [ -f /etc/os-release ]; then
-        . /etc/os-release
-        OS=$ID
-        OS_VERSION=$VERSION_ID
-    elif [ "$(uname)" = "Darwin" ]; then
-        OS="macos"
-        OS_VERSION=$(sw_vers -productVersion)
-    else
-        OS="unknown"
-    fi
-    echo "$OS"
-}
-
-OS=$(detect_os)
-log_info "Detected OS: $OS"
-
-# Install Docker based on OS
-install_docker() {
-    if command -v docker &> /dev/null; then
-        log_info "Docker already installed: $(docker --version)"
-        return 0
-    fi
-
-    log_info "Installing Docker..."
-
-    case $OS in
-        ubuntu|debian|pop)
-            # Remove old versions
-            apt-get remove -y docker docker-engine docker.io containerd runc 2>/dev/null || true
-
-            # Install prerequisites
-            apt-get update
-            apt-get install -y \
-                ca-certificates \
-                curl \
-                gnupg \
-                lsb-release
-
-            # Add Docker's official GPG key
-            install -m 0755 -d /etc/apt/keyrings
-            curl -fsSL https://download.docker.com/linux/$OS/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-            chmod a+r /etc/apt/keyrings/docker.gpg
-
-            # Set up repository
-            echo \
-                "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/$OS \
-                $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
-
-            # Install Docker
-            apt-get update
-            apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-
-            log_info "Docker installed successfully"
-            ;;
-
-        fedora|rhel|centos)
-            # Install prerequisites
-            dnf -y install dnf-plugins-core
-
-            # Add Docker repo
-            dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
-
-            # Install Docker
-            dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-
-            log_info "Docker installed successfully"
-            ;;
-
-        arch|manjaro)
-            pacman -S --noconfirm docker docker-compose
-            log_info "Docker installed successfully"
-            ;;
-
-        macos)
-            log_warn "Please install Docker Desktop from https://www.docker.com/products/docker-desktop"
-            log_warn "After installation, enable WSL integration if using WSL"
-            return 1
-            ;;
-
-        *)
-            log_error "Unsupported OS: $OS"
-            log_error "Please install Docker manually: https://docs.docker.com/engine/install/"
-            return 1
-            ;;
-    esac
-}
-
-# Configure Docker for non-root access
-configure_docker_user() {
-    log_info "Configuring Docker for user: $ACTUAL_USER"
-
-    # Add user to docker group
-    if ! getent group docker > /dev/null; then
-        groupadd docker
-    fi
-
-    usermod -aG docker "$ACTUAL_USER"
-    log_info "Added $ACTUAL_USER to docker group"
-}
-
-# Start Docker service
-start_docker() {
-    log_info "Starting Docker service..."
-
-    # Check if systemd is available (native Linux)
-    if command -v systemctl &> /dev/null && systemctl is-system-running &> /dev/null; then
-        systemctl enable docker
-        systemctl start docker
-    # Check if we're in WSL
-    elif grep -qi microsoft /proc/version 2>/dev/null; then
-        # WSL - use service command
-        service docker start || true
-    else
-        # Try service command as fallback
-        service docker start || true
-    fi
-
-    # Wait for Docker to be ready
-    log_info "Waiting for Docker to be ready..."
-    for i in {1..30}; do
-        if docker info &> /dev/null; then
-            log_info "Docker is ready"
-            return 0
-        fi
-        sleep 1
-    done
-
-    log_warn "Docker may not be fully started. You might need to restart your terminal or run: sudo service docker start"
-}
-
-# Pull PostgreSQL image
-pull_postgres_image() {
-    log_info "Pulling PostgreSQL image (this may take a moment)..."
-
-    # Run as the actual user to ensure proper permissions
-    su - "$ACTUAL_USER" -c "docker pull postgres:16-alpine" 2>/dev/null || \
-        docker pull postgres:16-alpine
-
-    log_info "PostgreSQL image ready"
-}
-
-# Install Node.js if not present
-install_nodejs() {
-    if command -v node &> /dev/null; then
-        NODE_VERSION=$(node --version)
-        log_info "Node.js already installed: $NODE_VERSION"
-        return 0
-    fi
-
-    log_info "Installing Node.js..."
-
-    case $OS in
-        ubuntu|debian|pop)
-            # Install Node.js 20.x LTS
-            curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
-            apt-get install -y nodejs
-            ;;
-
-        fedora|rhel|centos)
-            curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
-            dnf install -y nodejs
-            ;;
-
-        arch|manjaro)
-            pacman -S --noconfirm nodejs npm
-            ;;
-
-        macos)
-            log_warn "Please install Node.js from https://nodejs.org/"
-            return 1
-            ;;
-
-        *)
-            log_warn "Please install Node.js manually: https://nodejs.org/"
-            return 1
-            ;;
-    esac
-
-    log_info "Node.js installed: $(node --version)"
-}
-
-# Main setup
-main() {
-    echo ""
-    echo "  ████████╗██╗     ██████╗"
-    echo "  ╚══██╔══╝██║    ██╔════╝"
-    echo "     ██║   ██║    ██║"
-    echo "     ██║   ██║    ██║"
-    echo "     ██║   ███████╗╚██████╗"
-    echo "     ╚═╝   ╚══════╝ ╚═════╝"
-    echo ""
-    echo "  TLC Server Setup"
-    echo ""
-
-    # Install Docker
-    install_docker
-
-    # Configure Docker for user
-    configure_docker_user
-
-    # Start Docker
-    start_docker
-
-    # Pull PostgreSQL image
-    pull_postgres_image
-
-    # Check/install Node.js
-    install_nodejs
-
-    echo ""
-    log_info "=========================================="
-    log_info "Setup complete!"
-    log_info "=========================================="
-    echo ""
-    log_info "IMPORTANT: Log out and log back in (or restart your terminal)"
-    log_info "for Docker group permissions to take effect."
-    echo ""
-    log_info "Then you can run TLC server with:"
-    log_info "  cd your-project && npx tlc-claude-code server"
-    echo ""
-    log_info "Or test Docker now with:"
-    log_info "  sudo docker run hello-world"
-    echo ""
-}
-
-main "$@"
+#!/bin/bash
+#
+# TLC Server Setup Script
+# Installs Docker and other requirements for TLC dev server
+#
+# Usage: sudo ./setup.sh
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[TLC]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[TLC]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[TLC]${NC} $1"
+}
+
+# Check if running as root
+if [ "$EUID" -ne 0 ]; then
+    log_error "Please run with sudo: sudo ./setup.sh"
+    exit 1
+fi
+
+# Get the actual user (not root)
+ACTUAL_USER=${SUDO_USER:-$USER}
+if [ "$ACTUAL_USER" = "root" ]; then
+    log_error "Please run as a regular user with sudo, not as root directly"
+    exit 1
+fi
+
+log_info "Setting up TLC server requirements for user: $ACTUAL_USER"
+
+# Detect OS
+detect_os() {
+    if [ -f /etc/os-release ]; then
+        . /etc/os-release
+        OS=$ID
+        OS_VERSION=$VERSION_ID
+    elif [ "$(uname)" = "Darwin" ]; then
+        OS="macos"
+        OS_VERSION=$(sw_vers -productVersion)
+    else
+        OS="unknown"
+    fi
+    echo "$OS"
+}
+
+OS=$(detect_os)
+log_info "Detected OS: $OS"
+
+# Install Docker based on OS
+install_docker() {
+    if command -v docker &> /dev/null; then
+        log_info "Docker already installed: $(docker --version)"
+        return 0
+    fi
+
+    log_info "Installing Docker..."
+
+    case $OS in
+        ubuntu|debian|pop)
+            # Remove old versions
+            apt-get remove -y docker docker-engine docker.io containerd runc 2>/dev/null || true
+
+            # Install prerequisites
+            apt-get update
+            apt-get install -y \
+                ca-certificates \
+                curl \
+                gnupg \
+                lsb-release
+
+            # Add Docker's official GPG key
+            install -m 0755 -d /etc/apt/keyrings
+            curl -fsSL https://download.docker.com/linux/$OS/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+            chmod a+r /etc/apt/keyrings/docker.gpg
+
+            # Set up repository
+            echo \
+                "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/$OS \
+                $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+            # Install Docker
+            apt-get update
+            apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+            log_info "Docker installed successfully"
+            ;;
+
+        fedora|rhel|centos)
+            # Install prerequisites
+            dnf -y install dnf-plugins-core
+
+            # Add Docker repo
+            dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
+
+            # Install Docker
+            dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+            log_info "Docker installed successfully"
+            ;;
+
+        arch|manjaro)
+            pacman -S --noconfirm docker docker-compose
+            log_info "Docker installed successfully"
+            ;;
+
+        macos)
+            log_warn "Please install Docker Desktop from https://www.docker.com/products/docker-desktop"
+            log_warn "After installation, enable WSL integration if using WSL"
+            return 1
+            ;;
+
+        *)
+            log_error "Unsupported OS: $OS"
+            log_error "Please install Docker manually: https://docs.docker.com/engine/install/"
+            return 1
+            ;;
+    esac
+}
+
+# Configure Docker for non-root access
+configure_docker_user() {
+    log_info "Configuring Docker for user: $ACTUAL_USER"
+
+    # Add user to docker group
+    if ! getent group docker > /dev/null; then
+        groupadd docker
+    fi
+
+    usermod -aG docker "$ACTUAL_USER"
+    log_info "Added $ACTUAL_USER to docker group"
+}
+
+# Start Docker service
+start_docker() {
+    log_info "Starting Docker service..."
+
+    # Check if systemd is available (native Linux)
+    if command -v systemctl &> /dev/null && systemctl is-system-running &> /dev/null; then
+        systemctl enable docker
+        systemctl start docker
+    # Check if we're in WSL
+    elif grep -qi microsoft /proc/version 2>/dev/null; then
+        # WSL - use service command
+        service docker start || true
+    else
+        # Try service command as fallback
+        service docker start || true
+    fi
+
+    # Wait for Docker to be ready
+    log_info "Waiting for Docker to be ready..."
+    for i in {1..30}; do
+        if docker info &> /dev/null; then
+            log_info "Docker is ready"
+            return 0
+        fi
+        sleep 1
+    done
+
+    log_warn "Docker may not be fully started. You might need to restart your terminal or run: sudo service docker start"
+}
+
+# Pull PostgreSQL image
+pull_postgres_image() {
+    log_info "Pulling PostgreSQL image (this may take a moment)..."
+
+    # Run as the actual user to ensure proper permissions
+    su - "$ACTUAL_USER" -c "docker pull postgres:16-alpine" 2>/dev/null || \
+        docker pull postgres:16-alpine
+
+    log_info "PostgreSQL image ready"
+}
+
+# Install Node.js if not present
+install_nodejs() {
+    if command -v node &> /dev/null; then
+        NODE_VERSION=$(node --version)
+        log_info "Node.js already installed: $NODE_VERSION"
+        return 0
+    fi
+
+    log_info "Installing Node.js..."
+
+    case $OS in
+        ubuntu|debian|pop)
+            # Install Node.js 20.x LTS
+            curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+            apt-get install -y nodejs
+            ;;
+
+        fedora|rhel|centos)
+            curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
+            dnf install -y nodejs
+            ;;
+
+        arch|manjaro)
+            pacman -S --noconfirm nodejs npm
+            ;;
+
+        macos)
+            log_warn "Please install Node.js from https://nodejs.org/"
+            return 1
+            ;;
+
+        *)
+            log_warn "Please install Node.js manually: https://nodejs.org/"
+            return 1
+            ;;
+    esac
+
+    log_info "Node.js installed: $(node --version)"
+}
+
+# Main setup
+main() {
+    echo ""
+    echo "  ████████╗██╗     ██████╗"
+    echo "  ╚══██╔══╝██║    ██╔════╝"
+    echo "     ██║   ██║    ██║"
+    echo "     ██║   ██║    ██║"
+    echo "     ██║   ███████╗╚██████╗"
+    echo "     ╚═╝   ╚══════╝ ╚═════╝"
+    echo ""
+    echo "  TLC Server Setup"
+    echo ""
+
+    # Install Docker
+    install_docker
+
+    # Configure Docker for user
+    configure_docker_user
+
+    # Start Docker
+    start_docker
+
+    # Pull PostgreSQL image
+    pull_postgres_image
+
+    # Check/install Node.js
+    install_nodejs
+
+    echo ""
+    log_info "=========================================="
+    log_info "Setup complete!"
+    log_info "=========================================="
+    echo ""
+    log_info "IMPORTANT: Log out and log back in (or restart your terminal)"
+    log_info "for Docker group permissions to take effect."
+    echo ""
+    log_info "Then you can run TLC server with:"
+    log_info "  cd your-project && npx tlc-claude-code server"
+    echo ""
+    log_info "Or test Docker now with:"
+    log_info "  sudo docker run hello-world"
+    echo ""
+}
+
+main "$@"