tlc-claude-code 2.2.1 → 2.3.0

package/server/lib/test-selector.test.js

@@ -0,0 +1,172 @@
+// @depends server/lib/test-selector.js
+import { describe, it, expect } from 'vitest';
+import {
+  parseDependsComment,
+  buildTestMap,
+  getAffectedTests,
+  formatSelection,
+} from './test-selector.js';
+
+describe('test-selector', () => {
+  describe('parseDependsComment', () => {
+    it('extracts a single @depends path', () => {
+      const result = parseDependsComment('// @depends src/lib/auth.js');
+      expect(result).toEqual(['src/lib/auth.js']);
+    });
+
+    it('extracts multiple @depends from separate lines', () => {
+      const content = '// @depends src/a.js\n// @depends src/b.js';
+      const result = parseDependsComment(content);
+      expect(result).toEqual(['src/a.js', 'src/b.js']);
+    });
+
+    it('returns empty array when no @depends present', () => {
+      const result = parseDependsComment('no depends here');
+      expect(result).toEqual([]);
+    });
+
+    it('handles comma-separated dependencies on one line', () => {
+      const result = parseDependsComment('// @depends src/a.js, src/b.js');
+      expect(result).toEqual(['src/a.js', 'src/b.js']);
+    });
+
+    it('handles empty string', () => {
+      const result = parseDependsComment('');
+      expect(result).toEqual([]);
+    });
+
+    it('trims whitespace from paths', () => {
+      const result = parseDependsComment('// @depends   src/foo.js  ');
+      expect(result).toEqual(['src/foo.js']);
+    });
+
+    it('ignores @depends inside non-comment lines', () => {
+      const content = 'const x = "// @depends fake.js";\n// @depends real.js';
+      const result = parseDependsComment(content);
+      // Both lines start with // so the string literal line won't match
+      // Actually the first line starts with 'const' so it won't match
+      expect(result).toEqual(['real.js']);
+    });
+  });
+
+  describe('buildTestMap', () => {
+    it('builds mapping from test files to their dependencies', async () => {
+      const mockReadFile = async (filePath) => {
+        const files = {
+          'tests/auth.test.js': '// @depends src/auth.js\nimport { auth } from "../src/auth.js";',
+          'tests/db.test.js': '// @depends src/db.js, src/models.js\nimport { db } from "../src/db.js";',
+          'tests/utils.test.js': 'import { utils } from "../src/utils.js";',
+        };
+        if (files[filePath] === undefined) {
+          throw new Error(`ENOENT: no such file: ${filePath}`);
+        }
+        return files[filePath];
+      };
+
+      const testFiles = ['tests/auth.test.js', 'tests/db.test.js', 'tests/utils.test.js'];
+      const result = await buildTestMap(testFiles, { readFile: mockReadFile });
+
+      expect(result).toBeInstanceOf(Map);
+      expect(result.get('tests/auth.test.js')).toEqual(['src/auth.js']);
+      expect(result.get('tests/db.test.js')).toEqual(['src/db.js', 'src/models.js']);
+      expect(result.get('tests/utils.test.js')).toEqual([]);
+    });
+
+    it('handles readFile errors gracefully by treating as no-depends', async () => {
+      const mockReadFile = async () => {
+        throw new Error('ENOENT: file not found');
+      };
+
+      const result = await buildTestMap(['missing.test.js'], { readFile: mockReadFile });
+
+      expect(result.get('missing.test.js')).toEqual([]);
+    });
+
+    it('returns empty map for empty test file list', async () => {
+      const mockReadFile = async () => '';
+      const result = await buildTestMap([], { readFile: mockReadFile });
+
+      expect(result).toBeInstanceOf(Map);
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe('getAffectedTests', () => {
+    const testMap = new Map([
+      ['tests/auth.test.js', ['src/auth.js']],
+      ['tests/db.test.js', ['src/db.js', 'src/models.js']],
+      ['tests/utils.test.js', []],  // no @depends — always included
+      ['tests/api.test.js', ['src/api.js', 'src/auth.js']],
+    ]);
+
+    it('returns tests depending on a changed file', () => {
+      const result = getAffectedTests(['src/auth.js'], testMap);
+
+      expect(result).toContain('tests/auth.test.js');
+      expect(result).toContain('tests/api.test.js');
+      // no-depends tests are always included
+      expect(result).toContain('tests/utils.test.js');
+    });
+
+    it('returns only no-depends tests when changed file is unrelated', () => {
+      const result = getAffectedTests(['src/unrelated.js'], testMap);
+
+      expect(result).toEqual(['tests/utils.test.js']);
+    });
+
+    it('always includes tests with no @depends annotation', () => {
+      const result = getAffectedTests(['src/db.js'], testMap);
+
+      expect(result).toContain('tests/utils.test.js');
+      expect(result).toContain('tests/db.test.js');
+      expect(result).not.toContain('tests/auth.test.js');
+    });
+
+    it('returns only no-depends tests when changedFiles is empty', () => {
+      const result = getAffectedTests([], testMap);
+
+      expect(result).toEqual(['tests/utils.test.js']);
+    });
+
+    it('handles empty test map', () => {
+      const result = getAffectedTests(['src/auth.js'], new Map());
+
+      expect(result).toEqual([]);
+    });
+
+    it('handles multiple changed files', () => {
+      const result = getAffectedTests(['src/auth.js', 'src/db.js'], testMap);
+
+      expect(result).toContain('tests/auth.test.js');
+      expect(result).toContain('tests/db.test.js');
+      expect(result).toContain('tests/api.test.js');
+      expect(result).toContain('tests/utils.test.js');
+    });
+  });
+
+  describe('formatSelection', () => {
+    it('returns summary with skip count when not all tests selected', () => {
+      const result = formatSelection(3, 10);
+
+      expect(result).toBe('Running 3 of 10 tests (7 skipped — dependencies unchanged)');
+    });
+
+    it('returns "all tests" message when all selected', () => {
+      const result = formatSelection(10, 10);
+
+      expect(result).toBe('Running all 10 tests');
+    });
+
+    it('handles 1 of 1', () => {
+      const result = formatSelection(1, 1);
+
+      expect(result).toBe('Running all 1 tests');
+    });
+
+    it('handles 0 of N', () => {
+      const result = formatSelection(0, 5);
+
+      expect(result).toBe('Running 0 of 5 tests (5 skipped — dependencies unchanged)');
+    });
+  });
+});

package/server/templates/CLAUDE.md

@@ -31,6 +31,12 @@ src/
 2. **No hardcoded URLs or config** - Use environment variables
 3. **No magic strings** - Define constants in `constants/` folder
 4. **JSDoc required** - Document all public functions, classes, and methods
+5. **No direct `process.env`** - All config through a validated config module
+6. **Ownership checks on every endpoint** - Auth is not enough; verify the user owns the resource
+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`
 
 ### Standards Reference
 

package/server/templates/CODING-STANDARDS.md

@@ -241,25 +241,64 @@ if (status === 'pending') { ... }  // TypeScript will validate
 
 ---
 
-## 6. Configuration: No Hardcoded Values
+## 6. Configuration: Validated, Centralized, No Direct `process.env`
+
+### Centralized Config with Validation
+
+All configuration MUST go through a validated config module. Never read `process.env` directly in application code.
 
 ```typescript
-// ❌ NEVER
+// ❌ NEVER: Direct process.env in services/controllers
 class PaymentService {
-  private baseUrl = "https://api.stripe.com";
-  private timeout = 30000;
+  private baseUrl = process.env.STRIPE_BASE_URL || 'https://api.stripe.com';
+  private apiKey = process.env.STRIPE_API_KEY;  // silently undefined if missing
 }
 
-// ✅ ALWAYS
-// lib/configuration.ts or shared/config/stripe.config.ts
+// ❌ NEVER: Config without validation
 export const stripeConfig = {
   baseUrl: process.env.STRIPE_BASE_URL || 'https://api.stripe.com',
-  apiKey: process.env.STRIPE_API_KEY,
-  timeout: parseInt(process.env.STRIPE_TIMEOUT || '30000'),
-} as const;
+  apiKey: process.env.STRIPE_API_KEY,  // no validation, no fail-fast
+};
+
+// ✅ ALWAYS: Validated config module with fail-fast
+// src/config/config.ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  stripe: z.object({
+    baseUrl: z.string().url().default('https://api.stripe.com'),
+    apiKey: z.string().min(1, 'STRIPE_API_KEY is required'),
+    timeout: z.coerce.number().int().positive().default(30000),
+  }),
+});
+
+export type AppConfig = z.infer<typeof configSchema>;
+
+export function loadConfig(): AppConfig {
+  const result = configSchema.safeParse({
+    stripe: {
+      baseUrl: process.env.STRIPE_BASE_URL,
+      apiKey: process.env.STRIPE_API_KEY,
+      timeout: process.env.STRIPE_TIMEOUT,
+    },
+  });
+
+  if (!result.success) {
+    throw new Error(`Config validation failed:\n${result.error.format()}`);
+  }
+  return result.data;
+}
 ```
 
-**Rule**: If it could differ between environments, it's config.
+### Rules
+
+1. **All `process.env` access MUST be in the config module** — never in services, controllers, or middleware.
+2. **All required env vars MUST be validated at startup** — fail fast, not at first request.
+3. **Distinguish required vs optional** — required vars throw on boot; optional have explicit defaults.
+4. **No silent empty-string fallbacks** for secrets or connection strings.
+5. **Config is injected via DI or imported from the config module** — never read from env directly.
+
+**Rule**: If it could differ between environments, it's config. If it's required, validate it at boot.
 
 ---
 
@@ -432,6 +471,13 @@ Before committing any code:
 - [ ] Typed errors, not generic throws
 - [ ] Tests co-located with module
 - [ ] Build passes (`npm run build`)
+- [ ] **No direct `process.env`** in services/controllers — config module only
+- [ ] **Config validated at startup** with schema (Zod/Joi)
+- [ ] **Ownership checks** on every data-access endpoint
+- [ ] **No secrets in responses** — API keys, tokens are write-only
+- [ ] **Sensitive data hashed** at rest (OTPs, reset tokens)
+- [ ] **All HTML output escaped** — no raw interpolation of user values
+- [ ] **No manual `new Service()`** — use DI container
 
 ---
 
@@ -588,6 +634,295 @@ Refs: #456
 
 ---
 
+## 18. File Size Limits
+
+Large files are a code smell. They indicate a class or module is doing too much.
+
+| Threshold | Action |
+|---|---|
+| **< 300 lines** | Ideal. No action needed. |
+| **300-500 lines** | Acceptable. Review if it can be split. |
+| **500-1000 lines** | Warning. Should be split into focused sub-modules. |
+| **> 1000 lines** | Violation. MUST be split before merging. |
+
+### How to Split
+
+**Controllers with many routes:**
+```
+# Bad: csp.controller.ts (2,000+ lines)
+# Good: Split by resource/feature:
+modules/csp/
+  controllers/
+    policy.controller.ts      # CRUD for policies
+    report.controller.ts      # CSP violation reports
+    directive.controller.ts   # Directive management
+  csp.routes.ts               # Route registration (thin)
+```
+
+**Services with many methods:**
+```
+# Bad: user.service.ts (1,500 lines)
+# Good: Split by responsibility:
+modules/user/
+  services/
+    user-auth.service.ts      # Login, register, password reset
+    user-profile.service.ts   # Profile CRUD, avatar, preferences
+    user-admin.service.ts     # Admin operations, ban, role changes
+  user.service.ts             # Thin facade re-exporting sub-services
+```
+
+---
+
+## 19. Folder Overcrowding
+
+Too many files in one folder makes navigation difficult. Organize into subfolders by domain.
+
+| Threshold | Action |
+|---|---|
+| **< 8 files** | Fine as-is. |
+| **8-15 files** | Consider grouping into subfolders. |
+| **> 15 files** | MUST be organized into subfolders. |
+
+```
+# Bad: 25 files dumped in controllers/
+controllers/
+  auth.controller.ts
+  user.controller.ts
+  payment.controller.ts
+  invoice.controller.ts
+  product.controller.ts
+  ... (20 more)
+
+# Good: Organized by domain
+modules/
+  auth/auth.controller.ts
+  user/user.controller.ts
+  billing/
+    payment.controller.ts
+    invoice.controller.ts
+  catalog/
+    product.controller.ts
+```
+
+---
+
+## 20. Strict Typing
+
+TypeScript without strict types is just JavaScript with extra steps.
+
+### Rules
+
+1. **No `any` type** - Use `unknown` and narrow, or define a proper interface.
+2. **No implicit `any`** - Enable `noImplicitAny` in tsconfig.
+3. **All functions must have explicit return types** - Not just exported functions.
+4. **All parameters must be typed** - No untyped function parameters.
+5. **Prefer `interface` over `type`** for object shapes - Easier to extend.
+6. **Use `strict: true`** in tsconfig.json.
+
+```typescript
+// Bad: Missing types, implicit any
+function processData(data) {
+  const result = data.items.map(item => item.value);
+  return result;
+}
+
+// Good: Explicit types everywhere
+interface DataPayload {
+  items: Array<{ value: number }>;
+}
+
+function processData(data: DataPayload): number[] {
+  return data.items.map((item) => item.value);
+}
+```
+
+```typescript
+// Bad: any type
+function handleResponse(response: any): any {
+  return response.data;
+}
+
+// Good: Proper types
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+}
+
+function handleResponse<T>(response: ApiResponse<T>): T {
+  return response.data;
+}
+```
+
+### tsconfig.json Requirements
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}
+```
+
+---
+
+## 21. Security: Authorization, Secrets, and Output Encoding
+
+### Resource Ownership Checks
+
+Every endpoint that accesses a resource MUST verify the requesting user owns or has permission to access that resource. Authentication alone is not enough.
+
+```typescript
+// ❌ WRONG: Only checks authentication, not ownership
+@Get('settings/:merchantId')
+@UseGuards(AuthGuard)
+async getSettings(@Param('merchantId') merchantId: string): Promise<Settings> {
+  return this.settingsService.findByMerchant(merchantId); // any authed user can read any merchant
+}
+
+// ✅ CORRECT: Verifies ownership
+@Get('settings/:merchantId')
+@UseGuards(AuthGuard)
+async getSettings(
+  @Param('merchantId') merchantId: string,
+  @CurrentUser() user: User,
+): Promise<Settings> {
+  if (user.merchantId !== merchantId && user.role !== 'admin') {
+    throw new ForbiddenError('Cannot access another merchant\'s settings');
+  }
+  return this.settingsService.findByMerchant(merchantId);
+}
+```
+
+**Rules:**
+1. Every data-access endpoint MUST check that the requesting user owns the resource.
+2. Tests MUST prove that user A cannot read/modify user B's data.
+3. Prefer a reusable ownership guard over per-endpoint checks.
+
+### Never Expose Secrets in Responses
+
+API keys, webhook secrets, tokens, and credentials MUST never appear in API responses or rendered HTML.
+
+```typescript
+// ❌ WRONG: Returning secrets to the client
+return {
+  merchantId: merchant.id,
+  apiKey: merchant.apiKey,           // NEVER
+  webhookSecret: merchant.webhookSecret, // NEVER
+};
+
+// ✅ CORRECT: Mask or omit secrets
+return {
+  merchantId: merchant.id,
+  apiKey: mask(merchant.apiKey),     // "sk_live_...4x7f"
+  webhookSecret: '••••••••',         // write-only, never read back
+};
+```
+
+**Rules:**
+1. Secrets are **write-only** — accept on create/update, never return in GET responses.
+2. If display is needed, return masked values (first 4 + last 4 chars).
+3. Audit every response DTO and HTML template for leaked credentials.
+
+### Hash Sensitive Data at Rest
+
+OTP codes, reset tokens, and session secrets MUST be stored as one-way hashes, never plaintext.
+
+```typescript
+// ❌ WRONG: Plaintext OTP
+await db.otpSessions.insert({ code: '123456', expiresAt });
+
+// ✅ CORRECT: Hashed OTP
+import { createHash } from 'crypto';
+const hashedCode = createHash('sha256').update(code).digest('hex');
+await db.otpSessions.insert({ codeHash: hashedCode, expiresAt });
+
+// Verification: hash the input and compare
+function verifyOtp(input: string, stored: string): boolean {
+  const inputHash = createHash('sha256').update(input).digest('hex');
+  return timingSafeEqual(Buffer.from(inputHash), Buffer.from(stored));
+}
+```
+
+### Output Encoding (XSS Prevention)
+
+Never interpolate user-controlled values into HTML without escaping. This applies to inline HTML generation, template strings, and server-rendered pages.
+
+```typescript
+// ❌ WRONG: Raw interpolation — XSS risk
+const html = `<h1>Welcome, ${user.name}</h1>`;
+const html = `<a href="${redirectUrl}">Continue</a>`;
+
+// ✅ CORRECT: Always escape
+import { escapeHtml } from '@/shared/utils/escape';
+
+const html = `<h1>Welcome, ${escapeHtml(user.name)}</h1>`;
+const html = `<a href="${escapeHtml(redirectUrl)}">Continue</a>`;
+```
+
+```typescript
+// shared/utils/escape.ts
+/**
+ * Escapes HTML special characters to prevent XSS.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+```
+
+**Rules:**
+1. **Every** dynamic value in HTML output MUST be escaped.
+2. Prefer a real templating engine over string concatenation for HTML.
+3. Audit merchant-controlled, query-string, and user-input values first.
+4. Do not add new pages using inline HTML string builders — use a proper frontend.
+
+---
+
+## 22. Dependency Injection: No Manual Instantiation
+
+Never manually instantiate services or providers that should be managed by the DI container.
+
+```typescript
+// ❌ WRONG: Bypassing DI
+class PaymentService {
+  async processPayment(method: string): Promise<void> {
+    const provider = method === 'cyberpay'
+      ? new CyberpayProvider(process.env.CYBERPAY_KEY)  // untestable, unmanaged
+      : new CodProvider();
+    await provider.charge(amount);
+  }
+}
+
+// ✅ CORRECT: Provider registry via DI
+@Injectable()
+class PaymentService {
+  constructor(
+    @Inject('PAYMENT_PROVIDERS') private providers: Map<string, PaymentProvider>,
+  ) {}
+
+  async processPayment(method: string): Promise<void> {
+    const provider = this.providers.get(method);
+    if (!provider) throw new BadRequestError(`Unknown payment method: ${method}`);
+    await provider.charge(amount);
+  }
+}
+```
+
+**Rules:**
+1. All providers/services MUST be registered in the DI container.
+2. Never use `new ServiceClass()` in application code — let the framework manage lifecycle.
+3. Use factory providers or provider registries for dynamic selection.
+
+---
+
 ## AI Instructions
 
 When generating code:
@@ -605,6 +940,17 @@ When generating code:
 11. **Always** add JSDoc to public members
 12. **Always** create index.ts with barrel exports
 13. **Always** verify build passes after changes
+14. **Never** let files exceed 1000 lines - split into sub-modules
+15. **Never** let folders exceed 15 files - organize into subfolders
+16. **Never** use `any` type - use `unknown` or proper interfaces
+17. **Always** add explicit return types to functions
+18. **Never** read `process.env` outside the config module
+19. **Always** validate config at startup with a schema
+20. **Always** add ownership/authorization checks on data-access endpoints
+21. **Never** return secrets (API keys, tokens) in API responses or HTML
+22. **Always** hash OTPs, reset tokens, and session secrets before storing
+23. **Always** escape dynamic values in HTML output
+24. **Never** use `new ServiceClass()` — register in DI and inject
 
 ### Cleanup Tasks