tlc-claude-code 1.8.5 → 2.1.0

package/server/lib/claude-cascade.js

@@ -0,0 +1,247 @@
+/**
+ * CLAUDE.md Cascade
+ *
+ * When working in a child project inside a workspace, this module injects
+ * workspace-level CLAUDE.md content into the project's context. Only relevant
+ * sections (coding standards, conventions, architecture, rules) are cascaded,
+ * and a token budget (max 2000 chars) prevents context bloat.
+ *
+ * Workspace content is injected between TLC-WORKSPACE-START/END markers in
+ * the project CLAUDE.md so that project-specific rules always take precedence.
+ *
+ * @module claude-cascade
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WORKSPACE_MARKERS = {
+  START: '<!-- TLC-WORKSPACE-START -->',
+  END: '<!-- TLC-WORKSPACE-END -->',
+};
+
+/**
+ * Section heading keywords that are considered relevant for cascading.
+ * Matched case-insensitively against ## headings in the workspace CLAUDE.md.
+ */
+const RELEVANT_KEYWORDS = [
+  'standards',
+  'conventions',
+  'architecture',
+  'rules',
+];
+
+/**
+ * Maximum character budget for workspace content injection.
+ * Rough token estimate: 4 chars per token, so 2000 chars ~ 500 tokens.
+ */
+const MAX_WORKSPACE_CHARS = 2000;
+
+/**
+ * Read a file and return its content, or null if it doesn't exist.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {Promise<string|null>}
+ */
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.promises.readFile(filePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Extract relevant sections from workspace CLAUDE.md content.
+ *
+ * A section starts with a `## Heading` line and ends just before the next
+ * `## Heading` or end-of-file.  Only sections whose heading contains one
+ * of the RELEVANT_KEYWORDS (case-insensitive) are included.
+ *
+ * @param {string} content - Full workspace CLAUDE.md content
+ * @returns {string} Filtered content with only relevant sections
+ */
+function extractRelevantSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let currentSection = null;
+  let currentLines = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^##\s+(.+)/);
+    if (headingMatch) {
+      // Save previous section if relevant
+      if (currentSection !== null) {
+        sections.push({ heading: currentSection, lines: [...currentLines] });
+      }
+      currentSection = headingMatch[1];
+      currentLines = [line];
+    } else if (currentSection !== null) {
+      currentLines.push(line);
+    }
+  }
+
+  // Save last section
+  if (currentSection !== null) {
+    sections.push({ heading: currentSection, lines: [...currentLines] });
+  }
+
+  // Filter to only relevant sections
+  const relevant = sections.filter((section) => {
+    const headingLower = section.heading.toLowerCase();
+    return RELEVANT_KEYWORDS.some((kw) => headingLower.includes(kw));
+  });
+
+  return relevant.map((s) => s.lines.join('\n')).join('\n\n');
+}
+
+/**
+ * Truncate content to the character budget, breaking at the last newline
+ * before the limit to avoid cutting mid-line.
+ *
+ * @param {string} content - Content to truncate
+ * @param {number} maxChars - Maximum character count
+ * @returns {string} Truncated content
+ */
+function truncateTobudget(content, maxChars) {
+  if (content.length <= maxChars) return content;
+
+  const truncated = content.slice(0, maxChars);
+  const lastNewline = truncated.lastIndexOf('\n');
+  if (lastNewline > 0) {
+    return truncated.slice(0, lastNewline);
+  }
+  return truncated;
+}
+
+/**
+ * Build the merged content with workspace section injected between markers,
+ * followed by the original project content (minus any existing markers).
+ *
+ * @param {string|null} workspaceContent - Filtered workspace content to inject
+ * @param {string|null} projectContent - Original project CLAUDE.md content
+ * @returns {string} Merged content
+ */
+function buildMergedContent(workspaceContent, projectContent) {
+  if (!workspaceContent && !projectContent) return '';
+
+  // If no workspace content, return project as-is (strip any old markers)
+  if (!workspaceContent) {
+    return stripWorkspaceMarkers(projectContent || '');
+  }
+
+  const truncated = truncateTobudget(workspaceContent, MAX_WORKSPACE_CHARS);
+
+  const workspaceBlock = [
+    WORKSPACE_MARKERS.START,
+    truncated,
+    WORKSPACE_MARKERS.END,
+  ].join('\n');
+
+  // If no project content, just return workspace block
+  if (!projectContent) {
+    return workspaceBlock + '\n';
+  }
+
+  // Strip existing workspace markers from project content
+  const cleanedProject = stripWorkspaceMarkers(projectContent).trim();
+
+  // Workspace first, then project (project takes precedence by being last)
+  return workspaceBlock + '\n\n' + cleanedProject + '\n';
+}
+
+/**
+ * Remove existing TLC-WORKSPACE markers and their content from a string.
+ *
+ * @param {string} content - Content to strip markers from
+ * @returns {string} Content with markers removed
+ */
+function stripWorkspaceMarkers(content) {
+  const startIdx = content.indexOf(WORKSPACE_MARKERS.START);
+  const endIdx = content.indexOf(WORKSPACE_MARKERS.END);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return content;
+  }
+
+  const before = content.slice(0, startIdx);
+  const after = content.slice(endIdx + WORKSPACE_MARKERS.END.length);
+
+  // Clean up extra blank lines at the junction
+  return (before + after).replace(/\n{3,}/g, '\n\n');
+}
+
+/**
+ * Create a CLAUDE.md cascade instance.
+ *
+ * @param {Object} options
+ * @param {Object} options.workspaceDetector - A workspace detector instance
+ *   with a `detectWorkspace(projectDir)` method.
+ * @returns {{ getCascadedContext: Function, syncCascade: Function }}
+ */
+export function createClaudeCascade({ workspaceDetector }) {
+  /**
+   * Get merged context for a project directory.
+   *
+   * @param {string} projectDir - Absolute path to the project directory
+   * @returns {Promise<{ workspaceContent: string|null, projectContent: string|null, merged: string }>}
+   */
+  async function getCascadedContext(projectDir) {
+    const result = workspaceDetector.detectWorkspace(projectDir);
+    const projectClaudeMd = path.join(projectDir, 'CLAUDE.md');
+    const projectContent = await readFileOrNull(projectClaudeMd);
+
+    // If not in a workspace, return project content only
+    if (!result.isInWorkspace || !result.workspaceRoot) {
+      return {
+        workspaceContent: null,
+        projectContent,
+        merged: projectContent || '',
+      };
+    }
+
+    // Read workspace CLAUDE.md
+    const wsClaudeMd = path.join(result.workspaceRoot, 'CLAUDE.md');
+    const rawWorkspaceContent = await readFileOrNull(wsClaudeMd);
+
+    if (!rawWorkspaceContent) {
+      return {
+        workspaceContent: null,
+        projectContent,
+        merged: projectContent || '',
+      };
+    }
+
+    // Extract only relevant sections
+    const relevantContent = extractRelevantSections(rawWorkspaceContent);
+    const workspaceContent = relevantContent || rawWorkspaceContent;
+
+    const merged = buildMergedContent(relevantContent || null, projectContent);
+
+    return {
+      workspaceContent: rawWorkspaceContent,
+      projectContent,
+      merged,
+    };
+  }
+
+  /**
+   * Sync workspace content into the project's CLAUDE.md file on disk.
+   *
+   * Writes the merged content back to the project's CLAUDE.md, placing
+   * workspace content between TLC-WORKSPACE markers and preserving all
+   * project-specific content after the markers.
+   *
+   * @param {string} projectDir - Absolute path to the project directory
+   * @returns {Promise<void>}
+   */
+  async function syncCascade(projectDir) {
+    const context = await getCascadedContext(projectDir);
+    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+
+    await fs.promises.writeFile(claudeMdPath, context.merged, 'utf-8');
+  }
+
+  return { getCascadedContext, syncCascade };
+}

package/server/lib/claude-cascade.test.js

@@ -0,0 +1,245 @@
+/**
+ * CLAUDE.md Cascade Tests
+ *
+ * Tests for injecting workspace-level CLAUDE.md content into child project context.
+ * Uses temp directories with actual CLAUDE.md files and a mocked workspaceDetector.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createClaudeCascade } from './claude-cascade.js';
+
+/** Create a unique temp directory for each test */
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-cascade-'));
+}
+
+/** Recursively remove a directory */
+function rmDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+describe('ClaudeCascade', () => {
+  let tmpDir;
+  let wsRoot;
+  let projectDir;
+  let mockDetector;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    wsRoot = path.join(tmpDir, 'workspace');
+    projectDir = path.join(wsRoot, 'my-project');
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    mockDetector = {
+      detectWorkspace: vi.fn().mockReturnValue({
+        isInWorkspace: true,
+        workspaceRoot: wsRoot,
+        projectPath: projectDir,
+        relativeProjectPath: 'my-project',
+      }),
+    };
+  });
+
+  afterEach(() => {
+    if (tmpDir) rmDir(tmpDir);
+  });
+
+  describe('getCascadedContext', () => {
+    it('reads workspace CLAUDE.md content', async () => {
+      const wsContent = '# Workspace Rules\n\n## Coding Standards\n\nUse semicolons.\n';
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), wsContent);
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.workspaceContent).toContain('Workspace Rules');
+      expect(context.workspaceContent).toContain('Use semicolons');
+    });
+
+    it('reads project CLAUDE.md content', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n');
+      const projContent = '# My Project\n\nProject-specific rules.\n';
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), projContent);
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.projectContent).toContain('My Project');
+      expect(context.projectContent).toContain('Project-specific rules');
+    });
+
+    it('injects workspace content between TLC-WORKSPACE-START/END markers', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n\n## Coding Standards\n\nFollow TDD.\n');
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.merged).toContain('<!-- TLC-WORKSPACE-START -->');
+      expect(context.merged).toContain('<!-- TLC-WORKSPACE-END -->');
+      expect(context.merged).toContain('Follow TDD');
+    });
+
+    it('project rules take precedence (project content appears after workspace)', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n\n## Conventions\n\nWorkspace convention.\n');
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n\nProject rule.\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      const wsStartIdx = context.merged.indexOf('<!-- TLC-WORKSPACE-START -->');
+      const wsEndIdx = context.merged.indexOf('<!-- TLC-WORKSPACE-END -->');
+      const projectIdx = context.merged.indexOf('Project rule');
+
+      // Project content must appear after the workspace section
+      expect(projectIdx).toBeGreaterThan(wsEndIdx);
+      // Workspace content is between markers
+      expect(wsStartIdx).toBeLessThan(wsEndIdx);
+    });
+
+    it('only relevant sections injected (coding standards, conventions, architecture)', async () => {
+      const wsContent = [
+        '# Workspace',
+        '',
+        '## Coding Standards',
+        '',
+        'Use ESLint.',
+        '',
+        '## Architecture',
+        '',
+        'Microservices pattern.',
+        '',
+        '## Personal Notes',
+        '',
+        'Remember to buy milk.',
+        '',
+        '## Conventions',
+        '',
+        'Naming: camelCase.',
+        '',
+        '## Random Stuff',
+        '',
+        'Not relevant.',
+        '',
+      ].join('\n');
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), wsContent);
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      // Relevant sections should be present
+      expect(context.merged).toContain('Use ESLint');
+      expect(context.merged).toContain('Microservices pattern');
+      expect(context.merged).toContain('Naming: camelCase');
+
+      // Irrelevant sections should NOT be present in workspace injection
+      const wsStart = context.merged.indexOf('<!-- TLC-WORKSPACE-START -->');
+      const wsEnd = context.merged.indexOf('<!-- TLC-WORKSPACE-END -->');
+      const wsSection = context.merged.slice(wsStart, wsEnd);
+      expect(wsSection).not.toContain('Remember to buy milk');
+      expect(wsSection).not.toContain('Not relevant');
+    });
+
+    it('token budget respected (truncates workspace content if > 2000 chars)', async () => {
+      // Create a workspace CLAUDE.md with a relevant section longer than 2000 chars
+      const longContent = '## Coding Standards\n\n' + 'A'.repeat(3000) + '\n';
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), longContent);
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      // Extract workspace section from merged
+      const wsStart = context.merged.indexOf('<!-- TLC-WORKSPACE-START -->');
+      const wsEnd = context.merged.indexOf('<!-- TLC-WORKSPACE-END -->');
+      const wsSection = context.merged.slice(
+        wsStart + '<!-- TLC-WORKSPACE-START -->'.length,
+        wsEnd
+      );
+
+      // Workspace section content should be truncated to max 2000 chars
+      expect(wsSection.trim().length).toBeLessThanOrEqual(2000);
+    });
+
+    it('no cascade when no workspace detected (standalone project)', async () => {
+      const standaloneDetector = {
+        detectWorkspace: vi.fn().mockReturnValue({
+          isInWorkspace: false,
+          workspaceRoot: null,
+          projectPath: projectDir,
+          relativeProjectPath: null,
+        }),
+      };
+
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Standalone\n\nProject content.\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: standaloneDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.workspaceContent).toBeNull();
+      expect(context.projectContent).toContain('Standalone');
+      expect(context.merged).toContain('Project content');
+      expect(context.merged).not.toContain('<!-- TLC-WORKSPACE-START -->');
+    });
+
+    it('handles missing workspace CLAUDE.md gracefully', async () => {
+      // No CLAUDE.md in workspace root
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n\nRules.\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.workspaceContent).toBeNull();
+      expect(context.projectContent).toContain('Project');
+      expect(context.merged).toContain('Rules');
+    });
+
+    it('handles missing project CLAUDE.md gracefully', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n\n## Coding Standards\n\nWs rules.\n');
+      // No CLAUDE.md in project dir
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      const context = await cascade.getCascadedContext(projectDir);
+
+      expect(context.projectContent).toBeNull();
+      expect(context.workspaceContent).toContain('Workspace');
+      expect(context.merged).toContain('Ws rules');
+    });
+  });
+
+  describe('syncCascade', () => {
+    it('syncCascade updates markers in project CLAUDE.md', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n\n## Coding Standards\n\nUse Vitest.\n');
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n\nMy rules.\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+      await cascade.syncCascade(projectDir);
+
+      const updated = fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8');
+      expect(updated).toContain('<!-- TLC-WORKSPACE-START -->');
+      expect(updated).toContain('<!-- TLC-WORKSPACE-END -->');
+      expect(updated).toContain('Use Vitest');
+      expect(updated).toContain('My rules');
+    });
+
+    it('marker-based replacement is idempotent (running syncCascade twice gives same result)', async () => {
+      fs.writeFileSync(path.join(wsRoot, 'CLAUDE.md'), '# Workspace\n\n## Rules\n\nWorkspace rules.\n## Conventions\n\nBe consistent.\n');
+      fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Project\n\nProject stuff.\n');
+
+      const cascade = createClaudeCascade({ workspaceDetector: mockDetector });
+
+      await cascade.syncCascade(projectDir);
+      const afterFirst = fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8');
+
+      await cascade.syncCascade(projectDir);
+      const afterSecond = fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8');
+
+      expect(afterFirst).toBe(afterSecond);
+    });
+  });
+});

package/server/lib/command-runner.js

@@ -0,0 +1,159 @@
+/**
+ * Command Runner — execute TLC commands via container, Claude Code, or queue
+ * Phase 80 Task 8
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+
+const VALID_COMMANDS = ['build', 'deploy', 'test', 'plan', 'verify', 'review', 'status'];
+
+/**
+ * Create command runner
+ * @param {Object} [options]
+ * @param {Function} [options._checkDocker] - Check if tlc-standalone image exists
+ * @param {Function} [options._checkClaude] - Check if Claude Code is running
+ * @returns {Object} Command runner API
+ */
+function createCommandRunner(options = {}) {
+  const checkDocker = options._checkDocker || defaultCheckDocker;
+  const checkClaude = options._checkClaude || defaultCheckClaude;
+
+  async function defaultCheckDocker() {
+    try {
+      execSync('docker image inspect tlc-standalone 2>/dev/null', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function defaultCheckClaude() {
+    try {
+      const result = execSync('pgrep -f "claude" 2>/dev/null', { stdio: 'pipe' });
+      return result.toString().trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Detect best execution method
+   * @param {string} projectPath
+   * @returns {Promise<string>} 'container' | 'claude-code' | 'queue'
+   */
+  async function detectExecutionMethod(projectPath) {
+    if (await checkDocker()) return 'container';
+    if (checkClaude()) return 'claude-code';
+    return 'queue';
+  }
+
+  /**
+   * Execute command via Docker container
+   * @param {string} projectPath
+   * @param {string} command
+   * @param {Function} onOutput
+   * @returns {Promise<{ exitCode: number }>}
+   */
+  async function executeViaContainer(projectPath, command, onOutput) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('docker', [
+        'run', '--rm',
+        '-v', `${projectPath}:/project`,
+        '-w', '/project',
+        'tlc-standalone',
+        'tlc', command,
+      ]);
+
+      proc.stdout.on('data', (data) => onOutput && onOutput(data.toString()));
+      proc.stderr.on('data', (data) => onOutput && onOutput(data.toString()));
+      proc.on('close', (code) => resolve({ exitCode: code }));
+      proc.on('error', (err) => reject(err));
+    });
+  }
+
+  /**
+   * Queue command as task in PLAN.md
+   * @param {string} projectPath
+   * @param {string} command
+   */
+  async function queueCommand(projectPath, command) {
+    const timestamp = new Date().toISOString();
+    const entry = `\n### Queued: tlc ${command}\n_Queued at ${timestamp}_\n`;
+
+    // Find most recent plan file
+    const planDir = path.join(projectPath, '.planning', 'phases');
+    if (fs.existsSync(planDir)) {
+      const plans = fs.readdirSync(planDir).filter(f => f.endsWith('-PLAN.md')).sort((a, b) => {
+        const numA = parseInt(a.match(/^(\d+)/)?.[1] || '0', 10);
+        const numB = parseInt(b.match(/^(\d+)/)?.[1] || '0', 10);
+        return numA - numB;
+      });
+      if (plans.length > 0) {
+        const planPath = path.join(planDir, plans[plans.length - 1]);
+        fs.appendFileSync(planPath, entry);
+      }
+    }
+
+    // Log to history
+    logCommand(projectPath, { command, timestamp, method: 'queue' });
+
+    return { queued: true, method: 'queue', command };
+  }
+
+  /**
+   * Log a command to history
+   */
+  function logCommand(projectPath, entry) {
+    const histPath = path.join(projectPath, '.tlc', 'command-history.json');
+    const dir = path.dirname(histPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    let history = [];
+    try {
+      if (fs.existsSync(histPath)) {
+        history = JSON.parse(fs.readFileSync(histPath, 'utf8'));
+      }
+    } catch {}
+    history.push(entry);
+    // Keep last 100
+    if (history.length > 100) history = history.slice(-100);
+    fs.writeFileSync(histPath, JSON.stringify(history, null, 2));
+  }
+
+  /**
+   * Get command history for a project
+   * @param {string} projectPath
+   * @returns {Array}
+   */
+  function getCommandHistory(projectPath) {
+    const histPath = path.join(projectPath, '.tlc', 'command-history.json');
+    try {
+      if (fs.existsSync(histPath)) {
+        return JSON.parse(fs.readFileSync(histPath, 'utf8'));
+      }
+    } catch {}
+    return [];
+  }
+
+  /**
+   * Validate command type
+   * @param {string} command
+   * @returns {boolean}
+   */
+  function validateCommand(command) {
+    if (!command || typeof command !== 'string') return false;
+    return VALID_COMMANDS.includes(command);
+  }
+
+  return {
+    detectExecutionMethod,
+    executeViaContainer,
+    queueCommand,
+    getCommandHistory,
+    validateCommand,
+  };
+}
+
+module.exports = { createCommandRunner };