tlc-claude-code 2.2.1 → 2.4.0

package/server/lib/scope-checker.test.js

@@ -0,0 +1,175 @@
+/**
+ * Scope Checker Tests
+ * Detect scope drift between plan files and actual diffs
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  extractPlannedFiles,
+  detectDrift,
+  formatDriftReport,
+} from './scope-checker.js';
+
+describe('scope-checker', () => {
+  describe('extractPlannedFiles', () => {
+    it('extracts file paths from a Files section', () => {
+      const plan = '**Files:**\n- src/auth.ts\n- src/user.ts';
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual(['src/auth.ts', 'src/user.ts']);
+    });
+
+    it('returns empty array when no Files section exists', () => {
+      const plan = 'no files section';
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual([]);
+    });
+
+    it('strips parenthetical annotations like (new) and (modify)', () => {
+      const plan = '**Files:**\n- src/auth.ts (new)\n- src/user.ts (modify)\n- src/config.ts (delete)';
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual(['src/auth.ts', 'src/user.ts', 'src/config.ts']);
+    });
+
+    it('strips backticks from file paths', () => {
+      const plan = '**Files:**\n- `server/lib/review-fixer.js`\n- `server/lib/scope-checker.js` — new module';
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual(['server/lib/review-fixer.js', 'server/lib/scope-checker.js']);
+    });
+
+    it('collects files from multiple tasks', () => {
+      const plan = [
+        '## Task 1: Auth',
+        '**Files:**',
+        '- src/auth.ts',
+        '- src/auth.test.ts',
+        '',
+        '## Task 2: Users',
+        '**Files:**',
+        '- src/user.ts',
+        '- src/user.test.ts',
+      ].join('\n');
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual([
+        'src/auth.ts',
+        'src/auth.test.ts',
+        'src/user.ts',
+        'src/user.test.ts',
+      ]);
+    });
+
+    it('handles file entries with descriptions after em-dash', () => {
+      const plan = '**Files:**\n- server/lib/scope-checker.js — compares diff files against plan';
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual(['server/lib/scope-checker.js']);
+    });
+
+    it('returns empty array for empty string', () => {
+      const result = extractPlannedFiles('');
+      expect(result).toEqual([]);
+    });
+
+    it('deduplicates file paths across tasks', () => {
+      const plan = [
+        '## Task 1',
+        '**Files:**',
+        '- src/shared.ts',
+        '',
+        '## Task 2',
+        '**Files:**',
+        '- src/shared.ts',
+        '- src/other.ts',
+      ].join('\n');
+      const result = extractPlannedFiles(plan);
+      expect(result).toEqual(['src/shared.ts', 'src/other.ts']);
+    });
+  });
+
+  describe('detectDrift', () => {
+    it('returns no drift when diff matches plan exactly', () => {
+      const result = detectDrift(['src/auth.ts'], ['src/auth.ts']);
+      expect(result).toEqual({ drift: [], missing: [] });
+    });
+
+    it('detects extra files not in plan as drift', () => {
+      const result = detectDrift(
+        ['src/auth.ts', 'src/extra.ts'],
+        ['src/auth.ts']
+      );
+      expect(result).toEqual({
+        drift: ['src/extra.ts'],
+        missing: [],
+      });
+    });
+
+    it('detects planned files not in diff as missing', () => {
+      const result = detectDrift(
+        ['src/auth.ts'],
+        ['src/auth.ts', 'src/missing.ts']
+      );
+      expect(result).toEqual({
+        drift: [],
+        missing: ['src/missing.ts'],
+      });
+    });
+
+    it('excludes test files from drift detection', () => {
+      const result = detectDrift(['src/auth.test.ts'], []);
+      expect(result).toEqual({ drift: [], missing: [] });
+    });
+
+    it('excludes _test. pattern from drift detection', () => {
+      const result = detectDrift(['src/auth_test.go'], []);
+      expect(result).toEqual({ drift: [], missing: [] });
+    });
+
+    it('excludes test_ prefix from drift detection', () => {
+      const result = detectDrift(['test_auth.py'], []);
+      expect(result).toEqual({ drift: [], missing: [] });
+    });
+
+    it('returns empty arrays when both inputs are empty', () => {
+      const result = detectDrift([], []);
+      expect(result).toEqual({ drift: [], missing: [] });
+    });
+
+    it('handles both drift and missing simultaneously', () => {
+      const result = detectDrift(
+        ['src/auth.ts', 'src/extra.ts'],
+        ['src/auth.ts', 'src/missing.ts']
+      );
+      expect(result).toEqual({
+        drift: ['src/extra.ts'],
+        missing: ['src/missing.ts'],
+      });
+    });
+  });
+
+  describe('formatDriftReport', () => {
+    it('formats report with both drift and missing sections', () => {
+      const report = formatDriftReport(['extra.ts'], ['missing.ts']);
+      expect(report).toContain('extra.ts');
+      expect(report).toContain('missing.ts');
+      expect(report).toContain('Scope Drift');
+      expect(report).toContain('Missing');
+    });
+
+    it('returns no drift message when both arrays are empty', () => {
+      const report = formatDriftReport([], []);
+      expect(report).toBe('No drift detected');
+    });
+
+    it('formats report with only drift', () => {
+      const report = formatDriftReport(['extra.ts'], []);
+      expect(report).toContain('extra.ts');
+      expect(report).toContain('Scope Drift');
+      expect(report).not.toContain('Missing');
+    });
+
+    it('formats report with only missing', () => {
+      const report = formatDriftReport([], ['missing.ts']);
+      expect(report).toContain('missing.ts');
+      expect(report).toContain('Missing');
+      expect(report).not.toContain('Scope Drift');
+    });
+  });
+});

package/server/lib/skill-validator.js

@@ -0,0 +1,165 @@
+/**
+ * Skill Validator — Tier 1 (Static)
+ *
+ * Parses skill .md files and validates that referenced commands,
+ * modules, and skills actually exist. Fast, free, static analysis.
+ */
+
+const path = require('path');
+const realFs = require('fs');
+
+/**
+ * Extract module require references from code blocks in markdown content.
+ * Finds `require('./lib/...')` and `require('./server/lib/...')` patterns
+ * inside fenced code blocks only.
+ *
+ * @param {string} content - Markdown content to parse
+ * @returns {string[]} Array of module paths found in code blocks
+ */
+function extractModuleRefs(content) {
+  if (!content) return [];
+
+  const codeBlockRegex = /```(?:\w+)?\n([\s\S]*?)```/g;
+  const requireRegex = /require\(['"](\.\/(lib|server\/lib)\/[^'"]+)['"]\)/g;
+  const refs = new Set();
+
+  let blockMatch;
+  while ((blockMatch = codeBlockRegex.exec(content)) !== null) {
+    const blockContent = blockMatch[1];
+    let reqMatch;
+    while ((reqMatch = requireRegex.exec(blockContent)) !== null) {
+      refs.add(reqMatch[1]);
+    }
+  }
+
+  return [...refs];
+}
+
+/**
+ * Extract skill references from content.
+ * Finds `/tlc:...` and `Skill(skill="tlc:...")` patterns.
+ *
+ * @param {string} content - Content to parse
+ * @returns {string[]} Array of skill names (e.g., ['tlc:build', 'tlc:review'])
+ */
+function extractSkillRefs(content) {
+  if (!content) return [];
+
+  const refs = new Set();
+
+  // Match /tlc:name patterns (word chars plus hyphens)
+  const slashRegex = /\/tlc:([\w-]+)/g;
+  let match;
+  while ((match = slashRegex.exec(content)) !== null) {
+    refs.add(`tlc:${match[1]}`);
+  }
+
+  // Match Skill(skill="tlc:name") or Skill(skill='tlc:name')
+  const skillCallRegex = /Skill\(skill=["']tlc:([\w-]+)["']\)/g;
+  while ((match = skillCallRegex.exec(content)) !== null) {
+    refs.add(`tlc:${match[1]}`);
+  }
+
+  return [...refs];
+}
+
+/**
+ * Validate that referenced module files exist on disk.
+ *
+ * @param {string[]} refs - Array of module paths from extractModuleRefs
+ * @param {string} projectDir - Project root directory
+ * @param {Object} options - Options
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {Array<{type: string, ref: string}>} Array of validation errors
+ */
+function validateModuleRefs(refs, projectDir, options = {}) {
+  if (!refs || refs.length === 0) return [];
+
+  const fsImpl = options.fs || realFs;
+  const errors = [];
+
+  for (const ref of refs) {
+    // Skill docs use paths like require('./lib/...') which resolve relative to server/
+    // Try both project root and server/ subdirectory
+    const candidates = [
+      path.resolve(projectDir, ref),
+      path.resolve(projectDir, 'server', ref),
+    ];
+
+    const found = candidates.some((absPath) => {
+      const absPathJs = absPath.endsWith('.js') ? absPath : `${absPath}.js`;
+      return fsImpl.existsSync(absPath) || fsImpl.existsSync(absPathJs);
+    });
+
+    if (!found) {
+      errors.push({ type: 'missing-module', ref });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate that referenced skill files exist on disk.
+ * Maps `tlc:build` to `build.md` in the skill directory.
+ *
+ * @param {string[]} refs - Array of skill names from extractSkillRefs
+ * @param {string} skillDir - Directory containing skill .md files
+ * @param {Object} options - Options
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {Array<{type: string, ref: string}>} Array of validation errors
+ */
+function validateSkillRefs(refs, skillDir, options = {}) {
+  if (!refs || refs.length === 0) return [];
+
+  const fsImpl = options.fs || realFs;
+  const errors = [];
+
+  for (const ref of refs) {
+    // tlc:build -> build.md
+    const name = ref.replace(/^tlc:/, '');
+    const filePath = path.join(skillDir, `${name}.md`);
+
+    if (!fsImpl.existsSync(filePath)) {
+      errors.push({ type: 'missing-skill', ref });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a skill markdown file by running all static checks.
+ *
+ * @param {string} content - Skill file markdown content
+ * @param {Object} options - Validation options
+ * @param {string} options.projectDir - Project root directory
+ * @param {string} options.skillDir - Directory containing skill .md files
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {{valid: boolean, errors: Array<{type: string, ref: string}>}} Validation result
+ */
+function validateSkill(content, options = {}) {
+  if (!content) return { valid: true, errors: [] };
+  if (!options.projectDir || !options.skillDir) {
+    return { valid: false, errors: [{ type: 'config', ref: 'projectDir and skillDir are required' }] };
+  }
+
+  const { projectDir, skillDir, fs: fsImpl } = options;
+  const fsOpt = fsImpl ? { fs: fsImpl } : {};
+
+  const moduleRefs = extractModuleRefs(content);
+  const skillRefs = extractSkillRefs(content);
+
+  const moduleErrors = validateModuleRefs(moduleRefs, projectDir, fsOpt);
+  const skillErrors = validateSkillRefs(skillRefs, skillDir, fsOpt);
+
+  const errors = [...moduleErrors, ...skillErrors];
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+
+module.exports = { extractModuleRefs, extractSkillRefs, validateModuleRefs, validateSkillRefs, validateSkill };

package/server/lib/skill-validator.test.js

@@ -0,0 +1,289 @@
+/**
+ * Skill Validator Tests
+ *
+ * Static analysis for skill .md files — validates that referenced
+ * commands, modules, and skills actually exist.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  extractModuleRefs,
+  extractSkillRefs,
+  validateModuleRefs,
+  validateSkillRefs,
+  validateSkill,
+} from './skill-validator.js';
+
+describe('skill-validator', () => {
+  describe('extractModuleRefs', () => {
+    it('extracts require from code block', () => {
+      const content = "```js\nrequire('./lib/foo');\n```";
+      expect(extractModuleRefs(content)).toEqual(['./lib/foo']);
+    });
+
+    it('returns empty array when no code blocks', () => {
+      expect(extractModuleRefs('no code blocks here')).toEqual([]);
+    });
+
+    it('extracts multiple requires from code blocks', () => {
+      const content = [
+        '```js',
+        "const a = require('./lib/foo');",
+        "const b = require('./lib/bar');",
+        '```',
+        '',
+        'Some text in between.',
+        '',
+        '```js',
+        "const c = require('./server/lib/baz');",
+        '```',
+      ].join('\n');
+      expect(extractModuleRefs(content)).toEqual([
+        './lib/foo',
+        './lib/bar',
+        './server/lib/baz',
+      ]);
+    });
+
+    it('ignores requires outside code blocks', () => {
+      const content = "require('./lib/should-not-match');\nSome text.";
+      expect(extractModuleRefs(content)).toEqual([]);
+    });
+
+    it('handles code blocks with language specifiers', () => {
+      const content = "```javascript\nrequire('./lib/utils');\n```";
+      expect(extractModuleRefs(content)).toEqual(['./lib/utils']);
+    });
+
+    it('returns empty array for empty string', () => {
+      expect(extractModuleRefs('')).toEqual([]);
+    });
+
+    it('deduplicates repeated refs', () => {
+      const content = [
+        '```js',
+        "require('./lib/foo');",
+        "require('./lib/foo');",
+        '```',
+      ].join('\n');
+      expect(extractModuleRefs(content)).toEqual(['./lib/foo']);
+    });
+  });
+
+  describe('extractSkillRefs', () => {
+    it('extracts /tlc: skill references', () => {
+      expect(extractSkillRefs('Run /tlc:build to start')).toEqual([
+        'tlc:build',
+      ]);
+    });
+
+    it('extracts Skill() call references', () => {
+      expect(extractSkillRefs('Skill(skill="tlc:review")')).toEqual([
+        'tlc:review',
+      ]);
+    });
+
+    it('returns empty array when no skills referenced', () => {
+      expect(extractSkillRefs('no skills here')).toEqual([]);
+    });
+
+    it('extracts multiple skill references', () => {
+      const content =
+        'Use /tlc:build then /tlc:review. Also Skill(skill="tlc:plan").';
+      const refs = extractSkillRefs(content);
+      expect(refs).toContain('tlc:build');
+      expect(refs).toContain('tlc:review');
+      expect(refs).toContain('tlc:plan');
+      expect(refs).toHaveLength(3);
+    });
+
+    it('deduplicates repeated skill refs', () => {
+      const content = 'Run /tlc:build and /tlc:build again';
+      expect(extractSkillRefs(content)).toEqual(['tlc:build']);
+    });
+
+    it('returns empty array for empty string', () => {
+      expect(extractSkillRefs('')).toEqual([]);
+    });
+
+    it('handles single-quoted Skill() calls', () => {
+      expect(extractSkillRefs("Skill(skill='tlc:deploy')")).toEqual([
+        'tlc:deploy',
+      ]);
+    });
+  });
+
+  describe('validateModuleRefs', () => {
+    it('returns no errors when files exist', () => {
+      const mockFs = {
+        existsSync: () => true,
+      };
+      const errors = validateModuleRefs(['./lib/foo'], '/project', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('returns error when file is missing', () => {
+      const mockFs = {
+        existsSync: () => false,
+      };
+      const errors = validateModuleRefs(['./lib/foo'], '/project', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([
+        { type: 'missing-module', ref: './lib/foo' },
+      ]);
+    });
+
+    it('checks with .js extension fallback', () => {
+      const checked = [];
+      const mockFs = {
+        existsSync: (p) => {
+          checked.push(p);
+          return false;
+        },
+      };
+      validateModuleRefs(['./lib/foo'], '/project', { fs: mockFs });
+      // Should check both with and without .js
+      expect(checked.some((p) => p.endsWith('foo'))).toBe(true);
+      expect(checked.some((p) => p.endsWith('foo.js'))).toBe(true);
+    });
+
+    it('returns no errors for empty refs', () => {
+      const errors = validateModuleRefs([], '/project', {
+        fs: { existsSync: () => false },
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('reports multiple missing modules', () => {
+      const mockFs = { existsSync: () => false };
+      const errors = validateModuleRefs(
+        ['./lib/a', './lib/b'],
+        '/project',
+        { fs: mockFs }
+      );
+      expect(errors).toHaveLength(2);
+      expect(errors[0].ref).toBe('./lib/a');
+      expect(errors[1].ref).toBe('./lib/b');
+    });
+  });
+
+  describe('validateSkillRefs', () => {
+    it('returns no errors when skill files exist', () => {
+      const mockFs = {
+        existsSync: () => true,
+      };
+      const errors = validateSkillRefs(['tlc:build'], '/skills', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('returns error when skill file is missing', () => {
+      const mockFs = {
+        existsSync: () => false,
+      };
+      const errors = validateSkillRefs(['tlc:build'], '/skills', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([
+        { type: 'missing-skill', ref: 'tlc:build' },
+      ]);
+    });
+
+    it('maps skill name to correct file path', () => {
+      const checked = [];
+      const mockFs = {
+        existsSync: (p) => {
+          checked.push(p);
+          return true;
+        },
+      };
+      validateSkillRefs(['tlc:build'], '/skills', { fs: mockFs });
+      expect(checked[0]).toMatch(/build\.md$/);
+    });
+
+    it('returns no errors for empty refs', () => {
+      const errors = validateSkillRefs([], '/skills', {
+        fs: { existsSync: () => false },
+      });
+      expect(errors).toEqual([]);
+    });
+  });
+
+  describe('validateSkill', () => {
+    it('returns valid for clean content', () => {
+      const result = validateSkill('Just plain text, no refs.', {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => true },
+      });
+      expect(result).toEqual({ valid: true, errors: [] });
+    });
+
+    it('returns invalid with errors for broken module refs', () => {
+      const content = "```js\nrequire('./lib/nonexistent');\n```";
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toEqual({
+        type: 'missing-module',
+        ref: './lib/nonexistent',
+      });
+    });
+
+    it('returns invalid with errors for broken skill refs', () => {
+      const content = 'Run /tlc:nonexistent to start.';
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toEqual({
+        type: 'missing-skill',
+        ref: 'tlc:nonexistent',
+      });
+    });
+
+    it('aggregates both module and skill errors', () => {
+      const content = [
+        '```js',
+        "require('./lib/missing');",
+        '```',
+        'Use /tlc:fake to run.',
+      ].join('\n');
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(2);
+      expect(result.errors.find((e) => e.type === 'missing-module')).toBeTruthy();
+      expect(result.errors.find((e) => e.type === 'missing-skill')).toBeTruthy();
+    });
+
+    it('returns valid when all refs exist', () => {
+      const content = [
+        '```js',
+        "require('./lib/real');",
+        '```',
+        'Use /tlc:build to run.',
+      ].join('\n');
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => true },
+      });
+      expect(result).toEqual({ valid: true, errors: [] });
+    });
+  });
+});

package/server/lib/standards/standards-injector.js

@@ -66,6 +66,12 @@ This project follows TLC (Test-Led Coding) standards. See [CODING-STANDARDS.md](
 2. No hardcoded URLs or config - Use environment variables
 3. No magic strings - Define constants in \`constants/\` folder
 4. JSDoc required on all public members
+5. No direct \`process.env\` - All config through a validated config module
+6. Ownership checks on every data-access endpoint - Auth alone is not enough
+7. Never expose secrets in responses - API keys and tokens are write-only
+8. Hash sensitive data at rest - OTPs, reset tokens, session secrets
+9. Escape all HTML output - No raw interpolation of user values
+10. Use DI - Never manually instantiate services with \`new\`
 
 See [CODING-STANDARDS.md](./CODING-STANDARDS.md) for complete standards.
 `;