tlc-claude-code 1.8.5 → 2.1.0

package/server/lib/launchd-agent.js

@@ -0,0 +1,225 @@
+/**
+ * LaunchAgent plist generator for macOS.
+ *
+ * Generates, installs, and manages a macOS LaunchAgent that keeps
+ * the TLC server running permanently — auto-starts on login,
+ * auto-restarts on crash.
+ *
+ * @module launchd-agent
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/** LaunchAgent label */
+const PLIST_LABEL = 'com.tlc.server';
+
+/** Default plist install location */
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+
+/**
+ * Generate a macOS LaunchAgent plist XML string.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot - Absolute path to the TLC project
+ * @param {number} [opts.port=3147] - Server port
+ * @returns {string} Valid XML plist
+ */
+function generatePlist(opts) {
+  const { projectRoot, port = 3147 } = opts;
+  const nodePath = process.execPath;
+  const serverScript = path.join(projectRoot, 'server', 'index.js');
+  const logDir = path.join(os.homedir(), '.tlc', 'logs');
+  const logFile = path.join(logDir, 'server.log');
+  const envPath = process.env.PATH || '/usr/local/bin:/usr/bin:/bin';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${PLIST_LABEL}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${serverScript}</string>
+  </array>
+
+  <key>WorkingDirectory</key>
+  <string>${projectRoot}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${envPath}</string>
+    <key>HOME</key>
+    <string>${os.homedir()}</string>
+    <key>NODE_ENV</key>
+    <string>development</string>
+    <key>TLC_PORT</key>
+    <string>${port}</string>
+  </dict>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+
+  <key>StandardOutPath</key>
+  <string>${logFile}</string>
+
+  <key>StandardErrorPath</key>
+  <string>${logFile}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Write the plist file to disk.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot - Absolute path to the TLC project
+ * @param {string} [opts.targetDir] - Override install directory (for testing)
+ * @param {number} [opts.port=3147] - Server port
+ */
+function installAgent(opts) {
+  const targetDir = opts.targetDir || path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(targetDir, `${PLIST_LABEL}.plist`);
+
+  // Ensure log directory exists
+  const logDir = path.join(os.homedir(), '.tlc', 'logs');
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  // Ensure target directory exists
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  const xml = generatePlist(opts);
+  fs.writeFileSync(plistPath, xml, 'utf-8');
+}
+
+/**
+ * Remove the plist file from disk.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.targetDir] - Override install directory (for testing)
+ */
+function uninstallAgent(opts = {}) {
+  const targetDir = opts.targetDir || path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(targetDir, `${PLIST_LABEL}.plist`);
+
+  if (fs.existsSync(plistPath)) {
+    fs.unlinkSync(plistPath);
+  }
+}
+
+/**
+ * Check if the plist file is installed.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.targetDir] - Override install directory (for testing)
+ * @returns {boolean}
+ */
+function isInstalled(opts = {}) {
+  const targetDir = opts.targetDir || path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(targetDir, `${PLIST_LABEL}.plist`);
+  return fs.existsSync(plistPath);
+}
+
+/**
+ * Load the agent into launchd.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.exec] - Async exec function (for testing)
+ * @param {string} [opts.targetDir] - Override install directory
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+async function loadAgent(opts = {}) {
+  const exec = opts.exec || defaultExec;
+  const targetDir = opts.targetDir || path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(targetDir, `${PLIST_LABEL}.plist`);
+
+  try {
+    await exec(`launchctl load -w ${plistPath}`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Unload the agent from launchd and remove the plist.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.exec] - Async exec function (for testing)
+ * @param {string} [opts.targetDir] - Override install directory
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+async function unloadAgent(opts = {}) {
+  const exec = opts.exec || defaultExec;
+  const targetDir = opts.targetDir || path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(targetDir, `${PLIST_LABEL}.plist`);
+
+  try {
+    await exec(`launchctl unload ${plistPath}`);
+  } catch {
+    // Agent may not be loaded — that's fine
+  }
+
+  uninstallAgent({ targetDir });
+  return { ok: true };
+}
+
+/**
+ * Check if the agent is loaded in launchd.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.exec] - Async exec function (for testing)
+ * @returns {Promise<{loaded: boolean, pid?: number}>}
+ */
+async function statusAgent(opts = {}) {
+  const exec = opts.exec || defaultExec;
+
+  try {
+    const { stdout } = await exec(`launchctl list ${PLIST_LABEL}`);
+    const parts = stdout.trim().split('\t');
+    const pid = parts[0] && parts[0] !== '-' ? parseInt(parts[0], 10) : null;
+    return { loaded: true, pid };
+  } catch {
+    return { loaded: false };
+  }
+}
+
+/**
+ * Default exec using child_process.
+ * @param {string} cmd
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function defaultExec(cmd) {
+  const { exec } = require('child_process');
+  return new Promise((resolve, reject) => {
+    exec(cmd, (err, stdout, stderr) => {
+      if (err) return reject(err);
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+module.exports = {
+  generatePlist,
+  installAgent,
+  uninstallAgent,
+  isInstalled,
+  loadAgent,
+  unloadAgent,
+  statusAgent,
+  PLIST_LABEL,
+  PLIST_PATH,
+};

package/server/lib/launchd-agent.test.js

@@ -0,0 +1,185 @@
+/**
+ * LaunchAgent plist generator tests - Phase 83 Task 1
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+
+import {
+  generatePlist,
+  installAgent,
+  uninstallAgent,
+  isInstalled,
+  loadAgent,
+  unloadAgent,
+  statusAgent,
+  PLIST_LABEL,
+  PLIST_PATH,
+} from './launchd-agent.js';
+
+describe('launchd-agent', () => {
+  describe('generatePlist', () => {
+    it('returns valid XML with correct label', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<?xml version="1.0"');
+      expect(xml).toContain('<!DOCTYPE plist');
+      expect(xml).toContain('<string>com.tlc.server</string>');
+    });
+
+    it('includes KeepAlive and ThrottleInterval', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<key>KeepAlive</key>');
+      expect(xml).toContain('<true/>');
+      expect(xml).toContain('<key>ThrottleInterval</key>');
+      expect(xml).toContain('<integer>10</integer>');
+    });
+
+    it('sets WorkingDirectory to project root', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<key>WorkingDirectory</key>');
+      expect(xml).toContain('<string>/Users/dev/myproject</string>');
+    });
+
+    it('sets EnvironmentVariables including PATH and NODE_ENV', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<key>EnvironmentVariables</key>');
+      expect(xml).toContain('<key>NODE_ENV</key>');
+      expect(xml).toContain('<string>development</string>');
+      expect(xml).toContain('<key>PATH</key>');
+    });
+
+    it('uses absolute node path in ProgramArguments', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<key>ProgramArguments</key>');
+      // Should contain path to node and path to server/index.js
+      expect(xml).toContain('server/index.js');
+    });
+
+    it('sets log paths under ~/.tlc/logs/', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject' });
+      expect(xml).toContain('<key>StandardOutPath</key>');
+      expect(xml).toContain('<key>StandardErrorPath</key>');
+      expect(xml).toContain('.tlc/logs/server.log');
+    });
+
+    it('allows custom port via opts', () => {
+      const xml = generatePlist({ projectRoot: '/Users/dev/myproject', port: 4000 });
+      expect(xml).toContain('<key>TLC_PORT</key>');
+      expect(xml).toContain('<string>4000</string>');
+    });
+  });
+
+  describe('installAgent', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-launchd-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('writes plist file to target directory', () => {
+      const plistPath = path.join(tmpDir, 'com.tlc.server.plist');
+      installAgent({ projectRoot: '/Users/dev/myproject', targetDir: tmpDir });
+      expect(fs.existsSync(plistPath)).toBe(true);
+      const content = fs.readFileSync(plistPath, 'utf-8');
+      expect(content).toContain('com.tlc.server');
+    });
+  });
+
+  describe('uninstallAgent', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-launchd-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('removes plist file', () => {
+      const plistPath = path.join(tmpDir, 'com.tlc.server.plist');
+      fs.writeFileSync(plistPath, '<plist/>');
+      uninstallAgent({ targetDir: tmpDir });
+      expect(fs.existsSync(plistPath)).toBe(false);
+    });
+  });
+
+  describe('isInstalled', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-launchd-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('returns true when plist exists', () => {
+      fs.writeFileSync(path.join(tmpDir, 'com.tlc.server.plist'), '<plist/>');
+      expect(isInstalled({ targetDir: tmpDir })).toBe(true);
+    });
+
+    it('returns false when plist does not exist', () => {
+      expect(isInstalled({ targetDir: tmpDir })).toBe(false);
+    });
+  });
+
+  describe('loadAgent', () => {
+    it('calls launchctl load with correct path', async () => {
+      const mockExec = vi.fn().mockResolvedValue({ stdout: '', stderr: '' });
+      const result = await loadAgent({ exec: mockExec, targetDir: '/tmp/agents' });
+      expect(mockExec).toHaveBeenCalledWith(
+        expect.stringContaining('launchctl load'),
+      );
+      expect(mockExec).toHaveBeenCalledWith(
+        expect.stringContaining('com.tlc.server.plist'),
+      );
+    });
+  });
+
+  describe('unloadAgent', () => {
+    it('calls launchctl unload then removes plist', async () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-launchd-'));
+      const plistPath = path.join(tmpDir, 'com.tlc.server.plist');
+      fs.writeFileSync(plistPath, '<plist/>');
+
+      const mockExec = vi.fn().mockResolvedValue({ stdout: '', stderr: '' });
+      await unloadAgent({ exec: mockExec, targetDir: tmpDir });
+
+      expect(mockExec).toHaveBeenCalledWith(
+        expect.stringContaining('launchctl unload'),
+      );
+      expect(fs.existsSync(plistPath)).toBe(false);
+
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+  });
+
+  describe('statusAgent', () => {
+    it('returns loaded when launchctl finds the agent', async () => {
+      const mockExec = vi.fn().mockResolvedValue({ stdout: '12345\t0\tcom.tlc.server', stderr: '' });
+      const result = await statusAgent({ exec: mockExec });
+      expect(result.loaded).toBe(true);
+      expect(result.pid).toBeDefined();
+    });
+
+    it('returns not loaded when launchctl does not find agent', async () => {
+      const mockExec = vi.fn().mockRejectedValue(new Error('Could not find service'));
+      const result = await statusAgent({ exec: mockExec });
+      expect(result.loaded).toBe(false);
+    });
+  });
+
+  describe('constants', () => {
+    it('exports correct plist label', () => {
+      expect(PLIST_LABEL).toBe('com.tlc.server');
+    });
+  });
+});

package/server/lib/memory-api.js

@@ -0,0 +1,182 @@
+/**
+ * Memory API — HTTP handler factory for memory-related endpoints.
+ *
+ * Factory function `createMemoryApi` accepts injected dependencies and returns
+ * handler methods that accept Express-compatible (req, res) objects.
+ *
+ * Endpoints provided:
+ *   - handleSearch        — semantic search across memory
+ *   - handleListConversations — paginated conversation list
+ *   - handleGetConversation   — single conversation detail
+ *   - handleListDecisions — list all decisions
+ *   - handleListGotchas   — list all gotchas
+ *   - handleGetStats      — vector DB statistics
+ *   - handleRebuild       — trigger vector index rebuild
+ *   - handleRemember      — store permanent memory
+ *
+ * @module memory-api
+ */
+
+/**
+ * Create a memory API handler instance.
+ *
+ * @param {object} deps
+ * @param {object} deps.semanticRecall - Semantic recall with recall(query, context, options)
+ * @param {object} deps.vectorIndexer - Vector indexer with indexAll(projectRoot)
+ * @param {object} deps.richCapture - Rich capture with processChunk(text, metadata)
+ * @param {object} deps.embeddingClient - Embedding client with embed(text)
+ * @param {object} deps.memoryStore - Memory store with list/get methods
+ * @returns {object} Handler methods for each memory endpoint
+ */
+function createMemoryApi({ semanticRecall, vectorIndexer, richCapture, embeddingClient, memoryStore }) {
+
+  /**
+   * Search memory semantically.
+   *
+   * Query params: q (search query), scope (project|workspace|global)
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleSearch(req, res) {
+    const { q = '', scope } = req.query;
+
+    if (!q) {
+      return res.json({ results: [] });
+    }
+
+    const context = {};
+    const options = {};
+    if (scope) {
+      options.scope = scope;
+    }
+
+    const results = await semanticRecall.recall(q, context, options);
+    res.json({ results });
+  }
+
+  /**
+   * List conversations with pagination.
+   *
+   * Query params: page, limit, project
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleListConversations(req, res) {
+    const page = parseInt(req.query.page, 10) || 1;
+    const limit = parseInt(req.query.limit, 10) || 20;
+    const { project } = req.query;
+
+    const options = { page, limit };
+    if (project) {
+      options.project = project;
+    }
+
+    const result = await memoryStore.listConversations(options);
+    res.json({ items: result.items, total: result.total });
+  }
+
+  /**
+   * Get a single conversation by ID.
+   *
+   * @param {object} req - Express request with params.id
+   * @param {object} res - Express response
+   */
+  async function handleGetConversation(req, res) {
+    const { id } = req.params;
+    const conversation = await memoryStore.getConversation(id);
+
+    if (!conversation) {
+      return res.status(404).json({ error: 'Conversation not found' });
+    }
+
+    res.json(conversation);
+  }
+
+  /**
+   * List all decisions, optionally filtered by project.
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleListDecisions(req, res) {
+    const { project } = req.query;
+    const options = {};
+    if (project) {
+      options.project = project;
+    }
+
+    const decisions = await memoryStore.listDecisions(options);
+    res.json({ decisions });
+  }
+
+  /**
+   * List all gotchas, optionally filtered by project.
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleListGotchas(req, res) {
+    const { project } = req.query;
+    const options = {};
+    if (project) {
+      options.project = project;
+    }
+
+    const gotchas = await memoryStore.listGotchas(options);
+    res.json({ gotchas });
+  }
+
+  /**
+   * Get vector DB statistics.
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleGetStats(req, res) {
+    const stats = await memoryStore.getStats();
+    res.json(stats);
+  }
+
+  /**
+   * Trigger a full vector index rebuild.
+   *
+   * Body: { projectRoot }
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleRebuild(req, res) {
+    const { projectRoot } = req.body;
+    const result = await vectorIndexer.indexAll(projectRoot);
+    res.json(result);
+  }
+
+  /**
+   * Store a permanent memory entry.
+   *
+   * Body: { text, metadata }
+   *
+   * @param {object} req - Express request
+   * @param {object} res - Express response
+   */
+  async function handleRemember(req, res) {
+    const { text, metadata = {} } = req.body;
+    const result = await richCapture.processChunk(text, { ...metadata, permanent: true });
+    res.json(result);
+  }
+
+  return {
+    handleSearch,
+    handleListConversations,
+    handleGetConversation,
+    handleListDecisions,
+    handleListGotchas,
+    handleGetStats,
+    handleRebuild,
+    handleRemember,
+  };
+}
+
+module.exports = { createMemoryApi };