npm - tlc-claude-code - Versions diffs - 2.0.1 → 2.2.0 - Mend

tlc-claude-code 2.0.1 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

package/.claude/agents/builder.md +144 -0
package/.claude/agents/planner.md +143 -0
package/.claude/agents/reviewer.md +160 -0
package/.claude/commands/tlc/build.md +4 -0
package/.claude/commands/tlc/deploy.md +194 -2
package/.claude/commands/tlc/e2e-verify.md +214 -0
package/.claude/commands/tlc/guard.md +191 -0
package/.claude/commands/tlc/help.md +32 -0
package/.claude/commands/tlc/init.md +73 -37
package/.claude/commands/tlc/llm.md +19 -4
package/.claude/commands/tlc/preflight.md +134 -0
package/.claude/commands/tlc/review-plan.md +363 -0
package/.claude/commands/tlc/review.md +172 -57
package/.claude/commands/tlc/watchci.md +159 -0
package/.claude/hooks/tlc-block-tools.sh +41 -0
package/.claude/hooks/tlc-capture-exchange.sh +50 -0
package/.claude/hooks/tlc-post-build.sh +38 -0
package/.claude/hooks/tlc-post-push.sh +22 -0
package/.claude/hooks/tlc-prompt-guard.sh +69 -0
package/.claude/hooks/tlc-session-init.sh +123 -0
package/CLAUDE.md +13 -0
package/bin/install.js +268 -2
package/bin/postinstall.js +102 -24
package/bin/setup-autoupdate.js +206 -0
package/bin/setup-autoupdate.test.js +124 -0
package/bin/tlc.js +0 -0
package/dashboard-web/dist/assets/index-CdS5CHqu.css +1 -0
package/dashboard-web/dist/assets/index-CwNPPVpg.js +483 -0
package/dashboard-web/dist/assets/index-CwNPPVpg.js.map +1 -0
package/dashboard-web/dist/index.html +2 -2
package/docker-compose.dev.yml +18 -12
package/package.json +4 -2
package/scripts/project-docs.js +1 -1
package/server/index.js +228 -2
package/server/lib/capture-bridge.js +242 -0
package/server/lib/capture-bridge.test.js +363 -0
package/server/lib/capture-guard.js +140 -0
package/server/lib/capture-guard.test.js +182 -0
package/server/lib/command-runner.js +159 -0
package/server/lib/command-runner.test.js +92 -0
package/server/lib/cost-tracker.test.js +49 -12
package/server/lib/deploy/runners/dependency-runner.js +106 -0
package/server/lib/deploy/runners/dependency-runner.test.js +148 -0
package/server/lib/deploy/runners/secrets-runner.js +174 -0
package/server/lib/deploy/runners/secrets-runner.test.js +127 -0
package/server/lib/deploy/security-gates.js +11 -24
package/server/lib/deploy/security-gates.test.js +9 -2
package/server/lib/deploy-engine.js +182 -0
package/server/lib/deploy-engine.test.js +147 -0
package/server/lib/docker-api.js +137 -0
package/server/lib/docker-api.test.js +202 -0
package/server/lib/docker-client.js +297 -0
package/server/lib/docker-client.test.js +308 -0
package/server/lib/input-sanitizer.js +86 -0
package/server/lib/input-sanitizer.test.js +117 -0
package/server/lib/launchd-agent.js +225 -0
package/server/lib/launchd-agent.test.js +185 -0
package/server/lib/memory-api.js +3 -1
package/server/lib/memory-api.test.js +3 -5
package/server/lib/memory-bridge-e2e.test.js +160 -0
package/server/lib/memory-committer.js +18 -4
package/server/lib/memory-committer.test.js +21 -0
package/server/lib/memory-hooks-capture.test.js +69 -4
package/server/lib/memory-hooks-integration.test.js +98 -0
package/server/lib/memory-hooks.js +42 -4
package/server/lib/memory-store-adapter.js +105 -0
package/server/lib/memory-store-adapter.test.js +141 -0
package/server/lib/memory-wiring-e2e.test.js +93 -0
package/server/lib/nginx-config.js +114 -0
package/server/lib/nginx-config.test.js +82 -0
package/server/lib/ollama-health.js +91 -0
package/server/lib/ollama-health.test.js +74 -0
package/server/lib/orchestration/agent-dispatcher.js +114 -0
package/server/lib/orchestration/agent-dispatcher.test.js +110 -0
package/server/lib/orchestration/orchestrator.js +130 -0
package/server/lib/orchestration/orchestrator.test.js +192 -0
package/server/lib/orchestration/tmux-manager.js +101 -0
package/server/lib/orchestration/tmux-manager.test.js +109 -0
package/server/lib/orchestration/worktree-manager.js +132 -0
package/server/lib/orchestration/worktree-manager.test.js +129 -0
package/server/lib/port-guard.js +44 -0
package/server/lib/port-guard.test.js +65 -0
package/server/lib/project-scanner.js +37 -2
package/server/lib/project-scanner.test.js +152 -0
package/server/lib/remember-command.js +2 -0
package/server/lib/remember-command.test.js +23 -0
package/server/lib/review/plan-reviewer.js +260 -0
package/server/lib/review/plan-reviewer.test.js +269 -0
package/server/lib/review/review-schemas.js +173 -0
package/server/lib/review/review-schemas.test.js +152 -0
package/server/lib/security/crypto-utils.test.js +2 -2
package/server/lib/semantic-recall.js +1 -1
package/server/lib/semantic-recall.test.js +17 -0
package/server/lib/ssh-client.js +184 -0
package/server/lib/ssh-client.test.js +127 -0
package/server/lib/vps-api.js +184 -0
package/server/lib/vps-api.test.js +208 -0
package/server/lib/vps-bootstrap.js +124 -0
package/server/lib/vps-bootstrap.test.js +79 -0
package/server/lib/vps-monitor.js +126 -0
package/server/lib/vps-monitor.test.js +98 -0
package/server/lib/workspace-api.js +182 -1
package/server/lib/workspace-api.test.js +474 -0
package/server/package-lock.json +737 -0
package/server/package.json +3 -0
package/server/setup.sh +271 -271
package/dashboard-web/dist/assets/index-Uhc49PE-.css +0 -1
package/dashboard-web/dist/assets/index-W36XHPC5.js +0 -431
package/dashboard-web/dist/assets/index-W36XHPC5.js.map +0 -1

package/dashboard-web/dist/index.html CHANGED Viewed

@@ -9,8 +9,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-W36XHPC5.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Uhc49PE-.css">
+    <script type="module" crossorigin src="/assets/index-CwNPPVpg.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CdS5CHqu.css">
   </head>
   <body>
     <div id="root"></div>

package/docker-compose.dev.yml CHANGED Viewed

@@ -22,10 +22,14 @@ services:
       retries: 5
   # Your App (runs from project directory)
+  # Only starts when you explicitly provide PROJECT_DIR:
+  #   PROJECT_DIR=/path/to/your/app docker compose -f docker-compose.dev.yml up app
   app:
     image: node:20-alpine
     container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-app
     working_dir: /app
+    profiles:
+      - app
     command: >
       sh -c "
         npm install &&
@@ -51,7 +55,7 @@ services:
     ports:
       - "${APP_PORT:-5001}:5001"
     volumes:
-      - ..:/app
+      - ${PROJECT_DIR:-.}:/app
       - /app/node_modules
     depends_on:
       db:
@@ -95,31 +99,33 @@ services:
     restart: on-failure
   # TLC Dashboard (Express API + React SPA on port 3147)
-  # Since v1.8.1, the server serves the React dashboard from dashboard-web/dist/
+  # Mounts local TLC repo and user's home directory (read-only)
+  # so the dashboard setup screen can scan any code folder.
+  # Just run: docker compose -f docker-compose.dev.yml up
   dashboard:
     image: node:20-alpine
     container_name: tlc-${COMPOSE_PROJECT_NAME:-dev}-dashboard
-    working_dir: /project
+    working_dir: /tlc
     command: >
       sh -c "
-        echo 'Installing TLC...' &&
-        npm install -g tlc-claude-code@latest &&
-        TLC_DIR=/usr/local/lib/node_modules/tlc-claude-code &&
-        echo 'TLC installed at:' $$TLC_DIR &&
-        ls $$TLC_DIR/dashboard-web/dist/index.html && echo '[TLC] React SPA ready' || echo '[TLC] WARNING: dashboard-web/dist not found' &&
-        cd /project && node $$TLC_DIR/server/index.js --proxy-only --skip-db
+        echo '[TLC] Starting dashboard server...' &&
+        node server/index.js --proxy-only --skip-db
       "
     environment:
       - TLC_PORT=3147
       - TLC_PROXY_ONLY=true
       - TLC_APP_PORT=5001
       - TLC_AUTH=false
+      - TLC_CONFIG_DIR=${HOME}/.tlc
+      - DOCKER_SOCKET=/var/run/docker.sock
     ports:
       - "${DASHBOARD_PORT:-3147}:3147"
     volumes:
-      - ..:/project
-    depends_on:
-      - app
+      - .:/tlc
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${HOME}/.tlc:${HOME}/.tlc
+      - ${HOME}:${HOME}:ro
+      - ${HOME}/.ssh:${HOME}/.ssh:ro
     restart: on-failure
   # Playwright E2E Tests (optional - starts on demand)

package/package.json CHANGED Viewed

@@ -1,15 +1,16 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
-    "tlc": "./bin/tlc.js",
     "tlc-claude-code": "./bin/install.js",
     "tlc-docs": "./scripts/project-docs.js"
   },
   "files": [
     "bin/",
+    ".claude/agents/",
     ".claude/commands/",
+    ".claude/hooks/",
     "dashboard/dist/",
     "dashboard/package.json",
     "dashboard-web/dist/",
@@ -58,6 +59,7 @@
   "devDependencies": {
     "@playwright/test": "^1.58.1",
     "playwright": "^1.58.1",
+    "supertest": "^7.2.2",
     "text-to-image": "^8.0.1"
   },
   "dependencies": {

package/scripts/project-docs.js CHANGED Viewed

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * Project Documentation Maintenance
  *

package/server/index.js CHANGED Viewed

@@ -24,6 +24,8 @@ 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 {
   createUserStore,
   createAuthMiddleware,
@@ -34,6 +36,12 @@ const {
   hasPermission,
   USER_ROLES,
 } = require('./lib/auth-system');
+const { createDockerClient } = require('./lib/docker-client');
+const { createDockerRouter } = require('./lib/docker-api');
+const { createSshClient } = require('./lib/ssh-client');
+const { createVpsRouter } = require('./lib/vps-api');
+const { createVpsMonitor } = require('./lib/vps-monitor');
+const { createCommandRunner } = require('./lib/command-runner');
 // Handle PGlite WASM crashes gracefully
 process.on('uncaughtException', (err) => {
@@ -80,11 +88,146 @@ app.use(cors({ origin: true, credentials: true }));
 // Workspace API
 const globalConfig = new GlobalConfig();
 const projectScanner = new ProjectScanner();
-const workspaceRouter = createWorkspaceRouter({ globalConfig, 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');
+// Initialize memory directory structure (non-blocking)
+(async () => {
+  try {
+    const { initMemorySystem } = require('./lib/memory-init');
+    await initMemorySystem(PROJECT_DIR);
+  } catch (err) {
+    console.warn('[TLC] Memory directory init skipped:', err.message);
+  }
+})();
+// Initialize server-level memory capture (auto-captures conversations)
+const memoryCapture = createServerMemoryCapture({
+  projectRoot: PROJECT_DIR,
+  observeAndRemember,
+});
+// Lazy-initialized memory dependencies (ESM modules loaded async)
+const memoryDeps = {
+  observeAndRemember,
+  semanticRecall: null,
+  vectorIndexer: null,
+  embeddingClient: null,
+  vectorStore: 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
+    }
+  })();
+  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 adapter = createMemoryStoreAdapter(PROJECT_DIR);
+    return {
+      listConversations: async () => ({ items: [], total: 0 }), // TODO Phase 74: rich conversation capture
+      getConversation: async () => null, // TODO Phase 74: rich conversation capture
+      listDecisions: async () => adapter.listDecisions(),
+      listGotchas: async () => adapter.listGotchas(),
+      getStats: async () => adapter.getStats(),
+    };
+  })(),
+});
+const workspaceRouter = createWorkspaceRouter({
+  globalConfig,
+  projectScanner,
+  memoryApi,
+  memoryDeps,
+});
 app.use('/api/workspace', workspaceRouter);
 // Also mount project-level routes at /api/projects for per-project endpoints
 app.use('/api', workspaceRouter);
+// ============================================
+// Docker + VPS Management (Phase 80)
+// ============================================
+const DOCKER_SOCKET = process.env.DOCKER_SOCKET || '/var/run/docker.sock';
+const TLC_CONFIG_DIR = process.env.TLC_CONFIG_DIR || path.join(require('os').homedir(), '.tlc');
+// Docker client (graceful when socket unavailable)
+let dockerClient;
+try {
+  dockerClient = createDockerClient({ socketPath: DOCKER_SOCKET });
+} catch (err) {
+  console.log('[TLC] Docker client init skipped:', err.message);
+  dockerClient = null;
+}
+if (dockerClient) {
+  const dockerRouter = createDockerRouter({ dockerClient });
+  app.use('/api/docker', dockerRouter);
+  console.log('[TLC] Docker API mounted at /api/docker');
+}
+// SSH + VPS (always available, VPS operations fail gracefully)
+const sshClient = createSshClient();
+const vpsRouter = createVpsRouter({ sshClient, configDir: TLC_CONFIG_DIR });
+app.use('/api/vps', vpsRouter);
+// VPS monitor
+const vpsMonitor = createVpsMonitor({ sshClient });
+// Command runner
+const commandRunner = createCommandRunner();
 // ============================================
 // Authentication Setup
 // ============================================
@@ -478,7 +621,61 @@ wss.on('connection', (ws) => {
   // Send recent logs to new client
   ws.send(JSON.stringify({ type: 'init', data: { logs, appPort } }));
+  // Docker streaming state per connection
+  const dockerStreams = new Map();
+  ws.on('message', (raw) => {
+    try {
+      const msg = JSON.parse(raw.toString());
+      // Memory capture: auto-observe assistant responses
+      if (msg.type === 'assistant_response' && msg.text) {
+        memoryCapture.onAssistantResponse(msg.text);
+      }
+      // Memory capture: TLC command events flush capture
+      if (msg.type === 'tlc_command' && msg.command) {
+        memoryCapture.onTlcCommand(msg.command);
+      }
+      // Docker log streaming
+      if (msg.type === 'docker:subscribe-logs' && dockerClient && msg.containerId) {
+        const abort = dockerClient.streamContainerLogs(msg.containerId, (data) => {
+          if (ws.readyState === 1) {
+            ws.send(JSON.stringify({ type: 'docker:log', containerId: msg.containerId, data, timestamp: new Date().toISOString() }));
+          }
+        });
+        dockerStreams.set(`logs:${msg.containerId}`, abort);
+      }
+      if (msg.type === 'docker:unsubscribe-logs' && msg.containerId) {
+        const abort = dockerStreams.get(`logs:${msg.containerId}`);
+        if (abort) { abort(); dockerStreams.delete(`logs:${msg.containerId}`); }
+      }
+      // Docker stats streaming
+      if (msg.type === 'docker:subscribe-stats' && dockerClient && msg.containerId) {
+        const abort = dockerClient.streamContainerStats(msg.containerId, (stats) => {
+          if (ws.readyState === 1) {
+            ws.send(JSON.stringify({ type: 'docker:stats', containerId: msg.containerId, ...stats }));
+          }
+        });
+        dockerStreams.set(`stats:${msg.containerId}`, abort);
+      }
+      if (msg.type === 'docker:unsubscribe-stats' && msg.containerId) {
+        const abort = dockerStreams.get(`stats:${msg.containerId}`);
+        if (abort) { abort(); dockerStreams.delete(`stats:${msg.containerId}`); }
+      }
+    } catch {}
+  });
   ws.on('close', () => {
+    // Clean up Docker streams
+    for (const abort of dockerStreams.values()) {
+      try { abort(); } catch {}
+    }
+    dockerStreams.clear();
     wsClients.delete(ws);
     console.log(`[TLC] Client disconnected (${wsClients.size} total)`);
   });
@@ -1036,6 +1233,9 @@ app.post('/api/commands/:command', (req, res) => {
   addLog('app', `Executing command: tlc:${command}${args ? ' ' + args : ''}`, 'info');
   broadcast('command-started', { id: entry.id, command });
+  // Flush memory capture on TLC command execution
+  memoryCapture.onTlcCommand(command);
   // Build the CLI command
   const cliArgs = ['tlc', command];
   if (args) cliArgs.push(args);
@@ -1115,8 +1315,16 @@ app.put('/api/config', (req, res) => {
 });
 // GET /api/health - System health status
-app.get('/api/health', (req, res) => {
+app.get('/api/health', async (req, res) => {
   const memUsage = process.memoryUsage();
+  const ollamaHealth = await checkOllamaHealth();
+  const adapter = createMemoryStoreAdapter(PROJECT_DIR);
+  let memoryStats;
+  try {
+    memoryStats = await adapter.getStats();
+  } catch {
+    memoryStats = { decisions: 0, gotchas: 0, total: 0 };
+  }
   res.json({
     status: 'ok',
     timestamp: new Date().toISOString(),
@@ -1128,6 +1336,14 @@ app.get('/api/health', (req, res) => {
     },
     appRunning: appProcess !== null || appIsDocker,
     appPort,
+    tlcMemory: {
+      ollama: ollamaHealth,
+      fileStore: {
+        decisions: memoryStats.decisions,
+        gotchas: memoryStats.gotchas,
+        total: memoryStats.total,
+      },
+    },
   });
 });
@@ -1555,6 +1771,16 @@ async function main() {
   // Initialize authentication
   await initializeAuth();
+  // Check for port conflicts before listening
+  const { checkPort } = require('./lib/port-guard');
+  const portCheck = await checkPort(TLC_PORT);
+  if (!portCheck.available) {
+    console.error(`\n  Port ${TLC_PORT} is already in use.`);
+    console.error('  Another TLC server may be running, or a different process holds this port.');
+    console.error('  Use TLC_PORT=<port> to choose a different port.\n');
+    process.exit(1);
+  }
   server.listen(TLC_PORT, () => {
     console.log(`  Dashboard: http://localhost:${TLC_PORT}`);
     console.log(`  Share:     http://${getLocalIP()}:${TLC_PORT}`);

package/server/lib/capture-bridge.js ADDED Viewed

@@ -0,0 +1,242 @@
+/**
+ * Capture Bridge - Connects Claude Code Stop hooks to TLC memory capture.
+ *
+ * Called by the shell hook script (.claude/hooks/tlc-capture-exchange.sh).
+ * Reads Stop hook stdin, extracts the exchange, POSTs to the TLC server
+ * capture endpoint, and spools to a local JSONL file on failure.
+ *
+ * @module capture-bridge
+ */
+const fs = require('fs');
+const path = require('path');
+/** Spool filename for failed capture attempts */
+const SPOOL_FILENAME = '.spool.jsonl';
+/** Maximum message size before truncation (10KB) */
+const MAX_MESSAGE_SIZE = 10240;
+/** Default TLC server port */
+const DEFAULT_PORT = 3147;
+/**
+ * Parse the JSON stdin from a Claude Code Stop hook.
+ *
+ * @param {string} input - Raw JSON string from stdin
+ * @returns {{ sessionId: string, assistantMessage: string|null, transcriptPath: string|null, cwd: string|null } | null}
+ */
+function parseStopHookInput(input) {
+  if (!input) return null;
+  try {
+    const data = JSON.parse(input);
+    return {
+      sessionId: data.session_id || null,
+      assistantMessage: data.last_assistant_message || null,
+      transcriptPath: data.transcript_path || null,
+      cwd: data.cwd || null,
+    };
+  } catch {
+    return null;
+  }
+}
+/**
+ * Extract the last user message from a Claude Code transcript JSONL file.
+ *
+ * @param {string} transcriptPath - Absolute path to the transcript .jsonl file
+ * @returns {string|null} Last user message text, or null
+ */
+function extractLastUserMessage(transcriptPath) {
+  try {
+    const content = fs.readFileSync(transcriptPath, 'utf-8').trim();
+    if (!content) return null;
+    const lines = content.split('\n').filter(Boolean);
+    let lastUserMessage = null;
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.role === 'user' && entry.content) {
+          lastUserMessage = entry.content;
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+    return lastUserMessage;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Detect the project ID from the working directory.
+ * Reads .tlc.json if present, otherwise uses the directory basename.
+ *
+ * @param {string} cwd - Working directory path
+ * @returns {string} Project identifier
+ */
+function detectProjectId(cwd) {
+  try {
+    const tlcPath = path.join(cwd, '.tlc.json');
+    if (fs.existsSync(tlcPath)) {
+      const config = JSON.parse(fs.readFileSync(tlcPath, 'utf-8'));
+      if (config.project) return config.project;
+    }
+  } catch {
+    // Fall through to basename
+  }
+  return path.basename(cwd) || 'unknown';
+}
+/**
+ * Truncate a string to MAX_MESSAGE_SIZE, appending a marker if truncated.
+ *
+ * @param {string} text - Input text
+ * @returns {string} Possibly truncated text
+ */
+function truncate(text) {
+  if (!text || text.length <= MAX_MESSAGE_SIZE) return text || '';
+  return text.slice(0, MAX_MESSAGE_SIZE) + '... [truncated]';
+}
+/**
+ * Append a failed capture to the local spool file for later retry.
+ *
+ * @param {string} spoolDir - Directory containing the spool file
+ * @param {object} payload - The capture payload that failed to send
+ */
+function appendToSpool(spoolDir, payload) {
+  try {
+    if (!fs.existsSync(spoolDir)) {
+      fs.mkdirSync(spoolDir, { recursive: true });
+    }
+    const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+    fs.appendFileSync(spoolPath, JSON.stringify(payload) + '\n');
+  } catch {
+    // Spool write failure is non-fatal
+  }
+}
+/**
+ * Capture an exchange and POST it to the TLC server.
+ * On failure, spools to a local JSONL file.
+ * Never throws — all errors are swallowed.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - Working directory
+ * @param {string} opts.assistantMessage - The assistant's response text
+ * @param {string|null} opts.userMessage - The user's prompt text
+ * @param {string} opts.sessionId - Session identifier
+ * @param {object} [deps] - Injectable dependencies
+ * @param {Function} [deps.fetch] - fetch implementation (default: globalThis.fetch)
+ * @param {string} [deps.spoolDir] - Spool directory override
+ * @param {number} [deps.port] - Server port override
+ */
+async function captureExchange(opts, deps = {}) {
+  try {
+    const { cwd, assistantMessage, userMessage, sessionId } = opts;
+    const fetchFn = deps.fetch || globalThis.fetch;
+    const port = deps.port || DEFAULT_PORT;
+    // Skip empty messages
+    if (!assistantMessage) return;
+    const projectId = detectProjectId(cwd || '.');
+    const spoolDir = deps.spoolDir || path.join(cwd, '.tlc', 'memory');
+    const payload = {
+      projectId,
+      exchanges: [{
+        user: truncate(userMessage || ''),
+        assistant: truncate(assistantMessage),
+        timestamp: Date.now(),
+      }],
+    };
+    try {
+      const url = `http://localhost:${port}/api/projects/${encodeURIComponent(projectId)}/memory/capture`;
+      const response = await fetchFn(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      if (!response.ok) {
+        appendToSpool(spoolDir, payload);
+      }
+    } catch {
+      // Server unreachable — spool for later
+      appendToSpool(spoolDir, payload);
+    }
+  } catch {
+    // Total failure — silently ignore
+  }
+}
+/**
+ * Drain the local spool file by POSTing each entry to the capture endpoint.
+ * Successfully sent entries are removed; failed entries remain for next drain.
+ * Never throws.
+ *
+ * @param {string} spoolDir - Directory containing the spool file
+ * @param {object} [deps] - Injectable dependencies
+ * @param {Function} [deps.fetch] - fetch implementation
+ * @param {number} [deps.port] - Server port override
+ */
+async function drainSpool(spoolDir, deps = {}) {
+  try {
+    const fetchFn = deps.fetch || globalThis.fetch;
+    const port = deps.port || DEFAULT_PORT;
+    const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+    if (!fs.existsSync(spoolPath)) return;
+    const content = fs.readFileSync(spoolPath, 'utf-8').trim();
+    if (!content) return;
+    const lines = content.split('\n').filter(Boolean);
+    const failed = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        const projectId = entry.projectId || 'unknown';
+        const url = `http://localhost:${port}/api/projects/${encodeURIComponent(projectId)}/memory/capture`;
+        const response = await fetchFn(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ exchanges: entry.exchanges }),
+        });
+        if (!response.ok) {
+          failed.push(line);
+        }
+      } catch {
+        failed.push(line);
+      }
+    }
+    // Rewrite spool with only failed entries
+    fs.writeFileSync(spoolPath, failed.length > 0 ? failed.join('\n') + '\n' : '');
+  } catch {
+    // Drain failure is non-fatal
+  }
+}
+module.exports = {
+  parseStopHookInput,
+  extractLastUserMessage,
+  captureExchange,
+  drainSpool,
+  detectProjectId,
+  truncate,
+  SPOOL_FILENAME,
+  MAX_MESSAGE_SIZE,
+  DEFAULT_PORT,
+};