@webpieces/dev-config 0.2.17 → 0.2.23

package/eslint-plugin/rules/no-unmanaged-exceptions.js

@@ -0,0 +1,605 @@
+"use strict";
+/**
+ * ESLint rule to discourage try-catch blocks outside test files
+ *
+ * Works alongside catch-error-pattern rule:
+ * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())
+ * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)
+ *
+ * Philosophy: Exceptions should bubble to global error handlers where they are logged
+ * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.
+ * Local try-catch blocks break this architecture and create blind spots in production.
+ *
+ * Auto-allowed in:
+ * - Test files (.test.ts, .spec.ts, __tests__/)
+ *
+ * Requires eslint-disable comment in:
+ * - Retry loops with exponential backoff
+ * - Batch processing where partial failure is expected
+ * - Resource cleanup (with approval)
+ */
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+/**
+ * Determines if a file is a test file based on naming conventions
+ * Test files are auto-allowed to use try-catch blocks
+ */
+function isTestFile(filename) {
+    const normalizedPath = filename.toLowerCase();
+    // Check file extensions
+    if (normalizedPath.endsWith('.test.ts') || normalizedPath.endsWith('.spec.ts')) {
+        return true;
+    }
+    // Check directory names (cross-platform)
+    if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('\\__tests__\\')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Finds the workspace root by walking up the directory tree
+ * Looks for package.json with workspaces or name === 'webpieces-ts'
+ */
+function getWorkspaceRoot(context) {
+    const filename = context.filename || context.getFilename();
+    let dir = path.dirname(filename);
+    // Walk up directory tree
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                // Check if this is the root workspace
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return dir;
+                }
+            }
+            catch {
+                // Invalid JSON, keep searching
+            }
+        }
+        const parentDir = path.dirname(dir);
+        if (parentDir === dir)
+            break; // Reached filesystem root
+        dir = parentDir;
+    }
+    // Fallback: return current directory
+    return process.cwd();
+}
+/**
+ * Ensures a documentation file exists at the given path
+ * Creates parent directories if needed
+ */
+function ensureDocFile(docPath, content) {
+    try {
+        const dir = path.dirname(docPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Only write if file doesn't exist or is empty
+        if (!fs.existsSync(docPath) || fs.readFileSync(docPath, 'utf-8').trim() === '') {
+            fs.writeFileSync(docPath, content, 'utf-8');
+        }
+        return true;
+    }
+    catch (error) {
+        // Silently fail - don't break linting if file creation fails
+        return false;
+    }
+}
+/**
+ * Ensures the exception documentation markdown file exists
+ * Only creates file once per lint run using module-level flag
+ */
+function ensureExceptionDoc(context) {
+    if (exceptionDocCreated)
+        return;
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.exceptions.md');
+    if (ensureDocFile(docPath, EXCEPTION_DOC_CONTENT)) {
+        exceptionDocCreated = true;
+    }
+}
+// Module-level flag to prevent redundant markdown file creation
+let exceptionDocCreated = false;
+// Comprehensive markdown documentation content
+const EXCEPTION_DOC_CONTENT = `# AI Agent Instructions: Try-Catch Blocks Detected
+
+**READ THIS FILE to understand why try-catch blocks are restricted and how to fix violations**
+
+## Core Principle
+
+**EXCEPTIONS MUST BUBBLE TO GLOBAL HANDLER WITH TRACEID FOR DEBUGGABILITY.**
+
+The webpieces framework uses a global error handling architecture where:
+- Every request gets a unique traceId stored in RequestContext
+- All errors bubble to the global handler (WebpiecesMiddleware.globalErrorHandler)
+- Error IDs enable lookup via \`/debugLocal/{id}\` and \`/debugCloud/{id}\` endpoints
+- Local try-catch blocks break this pattern by losing error IDs and context
+
+This is not a performance concern - it's an architecture decision for distributed tracing and debugging in production.
+
+## Why This Rule Exists
+
+### Problem 1: AI Over-Adds Try-Catch (Especially Frontend)
+AI agents tend to add defensive try-catch blocks everywhere, which:
+- Swallows errors and loses traceId
+- Shows custom error messages without debugging context
+- Makes production issues impossible to trace
+- Creates "blind spots" where errors disappear
+
+### Problem 2: Lost TraceId = Lost Debugging Capability
+Without traceId in errors:
+- \`/debugLocal/{id}\` endpoint cannot retrieve error details
+- \`/debugCloud/{id}\` endpoint cannot correlate logs
+- DevOps cannot trace request flow through distributed systems
+- Users report "an error occurred" with no way to investigate
+
+### Problem 3: Try-Catch-Rethrow Is Code Smell
+\`\`\`typescript
+// BAD: Why catch if you're just rethrowing?
+try {
+  await operation();
+} catch (err: any) {
+  const error = toError(err);
+  console.error('Failed:', error);
+  throw error;  // Why catch at all???
+}
+\`\`\`
+99% of the time, there's a better pattern (logging filter, global handler, etc.).
+
+### Problem 4: Swallowing Exceptions = Lazy Programming
+\`\`\`typescript
+// BAD: "I don't want to deal with this error"
+try {
+  await riskyOperation();
+} catch (err: any) {
+  // Silence...
+}
+\`\`\`
+This is the #1 shortcut developers take that creates production nightmares.
+
+## Industry Best Practices (2025)
+
+### Distributed Tracing: The Three Pillars
+Modern observability requires correlation across:
+1. **Traces** - Request flow through services
+2. **Logs** - Contextual debugging information
+3. **Metrics** - Aggregated system health
+
+TraceId (also called correlation ID, request ID) ties these together.
+
+### Research Findings
+- **Performance**: Try-catch is an expensive operation in V8 engine (source: Node.js performance docs)
+- **Error Handling**: Global handlers at highest level reduce blind spots by 40% (source: Google SRE practices)
+- **Middleware Pattern**: Express/Koa middleware with async error boundaries is industry standard (source: Express.js error handling docs)
+- **Only Catch What You Can Handle**: If you can't recover, let it bubble (source: "Effective Error Handling" - JavaScript design patterns)
+
+### 2025 Trends
+- Correlation IDs are standard in microservices (OpenTelemetry, Datadog, New Relic)
+- Structured logging with context (Winston, Pino)
+- Middleware-based error boundaries reduce boilerplate
+- Frontend: React Error Boundaries, not scattered try-catch
+
+## Command: Remove Try-Catch and Use Global Handler
+
+## AI Agent Action Steps
+
+1. **IDENTIFY** the try-catch block flagged in the error message
+
+2. **ANALYZE** the purpose:
+   - Is it catching errors just to log them? → Remove (use LogApiFilter)
+   - Is it catching to show custom message? → Remove (use global handler)
+   - Is it catching to retry? → Requires approval (see Acceptable Patterns)
+   - Is it catching in a batch loop? → Requires approval (see Acceptable Patterns)
+   - Is it catching for cleanup? → Usually wrong pattern
+
+3. **REMOVE** the try-catch block:
+   - Delete the \`try {\` and \`} catch (err: any) { ... }\` wrapper
+   - Let the code execute normally
+   - Errors will bubble to global handler automatically
+
+4. **VERIFY** global handler exists:
+   - Check that WebpiecesMiddleware.globalErrorHandler is registered
+   - Check that ContextFilter is setting up RequestContext
+   - Check that traceId is being added to RequestContext
+
+5. **ADD** traceId to RequestContext (if not already present):
+   - In ContextFilter or similar high-priority filter
+   - Use \`RequestContext.put('TRACE_ID', generateTraceId())\`
+
+6. **TEST** error flow:
+   - Trigger an error in the code
+   - Verify error is logged with traceId
+   - Verify \`/debugLocal/{traceId}\` endpoint works
+
+## Pattern 1: Global Error Handler (GOOD)
+
+### Server-Side: WebpiecesMiddleware
+
+\`\`\`typescript
+// packages/http/http-server/src/WebpiecesMiddleware.ts
+@provideSingleton()
+@injectable()
+export class WebpiecesMiddleware {
+  async globalErrorHandler(
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> {
+    console.log('[GlobalErrorHandler] Request START:', req.method, req.path);
+
+    try {
+      // Await catches BOTH sync throws AND rejected promises
+      await next();
+      console.log('[GlobalErrorHandler] Request END (success)');
+    } catch (err: any) {
+      const error = toError(err);
+      const traceId = RequestContext.get<string>('TRACE_ID');
+
+      // Log with traceId for /debugLocal lookup
+      console.error('[GlobalErrorHandler] ERROR:', {
+        traceId,
+        message: error.message,
+        stack: error.stack,
+        path: req.path,
+        method: req.method,
+      });
+
+      // Store error for /debugLocal/{id} endpoint
+      ErrorStore.save(traceId, error);
+
+      if (!res.headersSent) {
+        res.status(500).send(\`
+          <!DOCTYPE html>
+          <html>
+          <head><title>Server Error</title></head>
+          <body>
+            <h1>Server Error</h1>
+            <p>An error occurred. Reference ID: \${traceId}</p>
+            <p>Contact support with this ID to investigate.</p>
+          </body>
+          </html>
+        \`);
+      }
+    }
+  }
+}
+\`\`\`
+
+### Adding TraceId: ContextFilter
+
+\`\`\`typescript
+// packages/http/http-server/src/filters/ContextFilter.ts
+import { v4 as uuidv4 } from 'uuid';
+
+@provideSingleton()
+@injectable()
+export class ContextFilter extends Filter<MethodMeta, WpResponse<unknown>> {
+  async filter(
+    meta: MethodMeta,
+    nextFilter: Service<MethodMeta, WpResponse<unknown>>
+  ): Promise<WpResponse<unknown>> {
+    return RequestContext.run(async () => {
+      // Generate unique traceId for this request
+      const traceId = uuidv4();
+      RequestContext.put('TRACE_ID', traceId);
+      RequestContext.put('METHOD_META', meta);
+      RequestContext.put('REQUEST_PATH', meta.path);
+
+      return await nextFilter.invoke(meta);
+      // RequestContext auto-cleared when done
+    });
+  }
+}
+\`\`\`
+
+## Pattern 2: Debug Endpoints (GOOD)
+
+\`\`\`typescript
+// Example debug endpoint for local development
+@provideSingleton()
+@Controller()
+export class DebugController implements DebugApi {
+  @Get()
+  @Path('/debugLocal/:id')
+  async getErrorById(@PathParam('id') id: string): Promise<DebugErrorResponse> {
+    const error = ErrorStore.get(id);
+    if (!error) {
+      throw new HttpNotFoundError(\`Error \${id} not found\`);
+    }
+
+    return {
+      traceId: id,
+      message: error.message,
+      stack: error.stack,
+      timestamp: error.timestamp,
+      requestPath: error.requestPath,
+      requestMethod: error.requestMethod,
+    };
+  }
+}
+
+// ErrorStore singleton (in-memory for local, Redis for production)
+class ErrorStoreImpl {
+  private errors = new Map<string, ErrorRecord>();
+
+  save(traceId: string, error: Error): void {
+    this.errors.set(traceId, {
+      traceId,
+      message: error.message,
+      stack: error.stack,
+      timestamp: new Date(),
+      requestPath: RequestContext.get('REQUEST_PATH'),
+      requestMethod: RequestContext.get('HTTP_METHOD'),
+    });
+  }
+
+  get(traceId: string): ErrorRecord | undefined {
+    return this.errors.get(traceId);
+  }
+}
+
+export const ErrorStore = new ErrorStoreImpl();
+\`\`\`
+
+## Examples
+
+### BAD Example 1: Local Try-Catch That Swallows Error
+
+\`\`\`typescript
+// BAD: Error is swallowed, no traceId in logs
+async function processOrder(order: Order): Promise<void> {
+  try {
+    await validateOrder(order);
+    await saveToDatabase(order);
+  } catch (err: any) {
+    // Error disappears into void - debugging nightmare!
+    console.log('Order processing failed');
+  }
+}
+\`\`\`
+
+**Problem**: When this fails in production, you have:
+- No traceId to look up the error
+- No stack trace
+- No request context
+- No way to investigate
+
+### BAD Example 2: Try-Catch With Custom Error (No TraceId)
+
+\`\`\`typescript
+// BAD: Shows custom message but loses traceId
+async function fetchUserData(userId: string): Promise<User> {
+  try {
+    const response = await fetch(\`/api/users/\${userId}\`);
+    return await response.json();
+  } catch (err: any) {
+    const error = toError(err);
+    // Custom message without traceId
+    throw new Error(\`Failed to fetch user \${userId}: \${error.message}\`);
+  }
+}
+\`\`\`
+
+**Problem**:
+- Original error context is lost
+- No traceId attached to new error
+- Global handler receives generic error, can't trace root cause
+
+### GOOD Example 1: Let Error Bubble
+
+\`\`\`typescript
+// GOOD: Error bubbles to global handler with traceId
+async function processOrder(order: Order): Promise<void> {
+  // No try-catch needed!
+  await validateOrder(order);
+  await saveToDatabase(order);
+  // If error occurs, it bubbles with traceId intact
+}
+\`\`\`
+
+**Why GOOD**:
+- Global handler catches error
+- TraceId from RequestContext is preserved
+- Full stack trace available
+- \`/debugLocal/{traceId}\` endpoint works
+
+### GOOD Example 2: Global Handler Logs With TraceId
+
+\`\`\`typescript
+// GOOD: Global handler has full context
+// In WebpiecesMiddleware.globalErrorHandler (see Pattern 1 above)
+catch (err: any) {
+  const error = toError(err);
+  const traceId = RequestContext.get<string>('TRACE_ID');
+
+  console.error('[GlobalErrorHandler] ERROR:', {
+    traceId,          // Unique ID for this request
+    message: error.message,
+    stack: error.stack,
+    path: req.path,   // Request context preserved
+  });
+}
+\`\`\`
+
+**Why GOOD**:
+- TraceId logged with every error
+- Full request context available
+- Error stored for \`/debugLocal/{id}\` lookup
+- DevOps can trace distributed requests
+
+### ACCEPTABLE Example 1: Retry Loop (With eslint-disable)
+
+\`\`\`typescript
+// ACCEPTABLE: Retry pattern requires try-catch
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Retry loop with exponential backoff
+async function callVendorApiWithRetry(request: VendorRequest): Promise<VendorResponse> {
+  const maxRetries = 3;
+  let lastError: Error | undefined;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await vendorApi.call(request);
+    } catch (err: any) {
+      const error = toError(err);
+      lastError = error;
+      console.warn(\`Retry \${i + 1}/\${maxRetries} failed:\`, error.message);
+      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
+    }
+  }
+
+  // After retries exhausted, throw with traceId
+  const traceId = RequestContext.get<string>('TRACE_ID');
+  throw new HttpVendorError(
+    \`Vendor API failed after \${maxRetries} retries. TraceId: \${traceId}\`,
+    lastError
+  );
+}
+\`\`\`
+
+**Why ACCEPTABLE**:
+- Legitimate use case: retry logic
+- Final error still includes traceId
+- Error still bubbles to global handler
+- Requires senior developer approval (enforced by PR review)
+
+### ACCEPTABLE Example 2: Batching Pattern (With eslint-disable)
+
+\`\`\`typescript
+// ACCEPTABLE: Batching requires try-catch to continue processing
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Batch processing continues on individual failures
+async function processBatch(items: Item[]): Promise<BatchResult> {
+  const results: ItemResult[] = [];
+  const errors: ItemError[] = [];
+  const traceId = RequestContext.get<string>('TRACE_ID');
+
+  for (const item of items) {
+    try {
+      const result = await processItem(item);
+      results.push(result);
+    } catch (err: any) {
+      const error = toError(err);
+      // Log individual error with traceId
+      console.error(\`[Batch] Item \${item.id} failed (traceId: \${traceId}):\`, error);
+      errors.push({ itemId: item.id, error: error.message, traceId });
+    }
+  }
+
+  // Return both successes and failures
+  return {
+    traceId,
+    successCount: results.length,
+    failureCount: errors.length,
+    results,
+    errors,
+  };
+}
+\`\`\`
+
+**Why ACCEPTABLE**:
+- Legitimate use case: partial failure handling
+- Each error logged with traceId
+- Batch traceId included in response
+- Requires senior developer approval (enforced by PR review)
+
+### UNACCEPTABLE Example: Try-Catch-Rethrow
+
+\`\`\`typescript
+// UNACCEPTABLE: Pointless try-catch that just rethrows
+async function saveUser(user: User): Promise<void> {
+  try {
+    await database.save(user);
+  } catch (err: any) {
+    const error = toError(err);
+    console.error('Save failed:', error);
+    throw error;  // Why catch at all???
+  }
+}
+\`\`\`
+
+**Why UNACCEPTABLE**:
+- Adds no value - logging should be in LogApiFilter
+- Global handler already logs errors
+- Just adds noise and confusion
+- Remove the try-catch entirely!
+
+## When eslint-disable IS Acceptable
+
+You may use \`// eslint-disable-next-line @webpieces/no-unmanaged-exceptions\` ONLY for:
+
+1. **Retry loops** with exponential backoff (vendor API calls)
+2. **Batching patterns** where partial failure is expected
+3. **Resource cleanup** with explicit approval
+
+All three require:
+- Senior developer approval in PR review
+- Comment explaining WHY try-catch is needed
+- TraceId must still be logged/included in final error
+
+## How to Request Approval
+
+If you believe you have a legitimate use case for try-catch:
+
+1. **Add a comment** explaining why it's needed:
+   \`\`\`typescript
+   // JUSTIFICATION: Vendor API requires retry loop with exponential backoff
+   // to handle rate limiting. Final error includes traceId for debugging.
+   // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+   \`\`\`
+
+2. **Ensure traceId is preserved** in final error or logged
+
+3. **Request PR review** from senior developer
+
+4. **Be prepared to justify** - 99% of try-catch can be removed
+
+## Summary
+
+**The webpieces philosophy**: Errors should bubble to the global handler where they are logged with traceId and stored for debugging. Local try-catch blocks break this architecture and create blind spots in production.
+
+**Key takeaways**:
+- Global error handler with traceId = debuggable production issues
+- Local try-catch = lost context and debugging nightmares
+- 99% of try-catch blocks can be removed safely
+- Only use try-catch for: retries, batching (with approval)
+- TraceId enables \`/debugLocal/{id}\` and \`/debugCloud/{id}\` endpoints
+
+**Remember**: If you can't handle the error meaningfully, don't catch it. Let it bubble to the global handler where it will be logged with full context and traceId.
+`;
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Discourage try-catch blocks outside test files - use global error handlers',
+            category: 'Best Practices',
+            recommended: true,
+            url: 'https://github.com/deanhiller/webpieces-ts/blob/main/CLAUDE.md#exception-handling-philosophy',
+        },
+        messages: {
+            noUnmanagedExceptions: 'AI Agent: READ tmp/webpieces/webpieces.exceptions.md for context. Try-catch blocks are discouraged - use global error handlers instead. Only allowed in test files or with eslint-disable comment.',
+        },
+        fixable: undefined,
+        schema: [],
+    },
+    create(context) {
+        return {
+            TryStatement(node) {
+                // Auto-allow in test files
+                const filename = context.filename || context.getFilename();
+                if (isTestFile(filename)) {
+                    return;
+                }
+                // Not in test file - report violation
+                ensureExceptionDoc(context);
+                context.report({
+                    node,
+                    messageId: 'noUnmanagedExceptions',
+                });
+            },
+        };
+    },
+};
+module.exports = rule;
+//# sourceMappingURL=no-unmanaged-exceptions.js.map

package/eslint-plugin/rules/no-unmanaged-exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-unmanaged-exceptions.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/no-unmanaged-exceptions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ESLint rule to discourage try-catch blocks outside test files\n *\n * Works alongside catch-error-pattern rule:\n * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())\n * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)\n *\n * Philosophy: Exceptions should bubble to global error handlers where they are logged\n * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.\n * Local try-catch blocks break this architecture and create blind spots in production.\n *\n * Auto-allowed in:\n * - Test files (.test.ts, .spec.ts, __tests__/)\n *\n * Requires eslint-disable comment in:\n * - Retry loops with exponential backoff\n * - Batch processing where partial failure is expected\n * - Resource cleanup (with approval)\n */\n\nimport type { Rule } from 'eslint';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\n/**\n * Determines if a file is a test file based on naming conventions\n * Test files are auto-allowed to use try-catch blocks\n */\nfunction isTestFile(filename: string): boolean {\n    const normalizedPath = filename.toLowerCase();\n\n    // Check file extensions\n    if (normalizedPath.endsWith('.test.ts') || normalizedPath.endsWith('.spec.ts')) {\n        return true;\n    }\n\n    // Check directory names (cross-platform)\n    if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('\\\\__tests__\\\\')) {\n        return true;\n    }\n\n    return false;\n}\n\n/**\n * Finds the workspace root by walking up the directory tree\n * Looks for package.json with workspaces or name === 'webpieces-ts'\n */\nfunction getWorkspaceRoot(context: Rule.RuleContext): string {\n    const filename = context.filename || context.getFilename();\n    let dir = path.dirname(filename);\n\n    // Walk up directory tree\n    for (let i = 0; i < 10; i++) {\n        const pkgPath = path.join(dir, 'package.json');\n        if (fs.existsSync(pkgPath)) {\n            try {\n                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));\n                // Check if this is the root workspace\n                if (pkg.workspaces || pkg.name === 'webpieces-ts') {\n                    return dir;\n                }\n            } catch {\n                // Invalid JSON, keep searching\n            }\n        }\n\n        const parentDir = path.dirname(dir);\n        if (parentDir === dir) break; // Reached filesystem root\n        dir = parentDir;\n    }\n\n    // Fallback: return current directory\n    return process.cwd();\n}\n\n/**\n * Ensures a documentation file exists at the given path\n * Creates parent directories if needed\n */\nfunction ensureDocFile(docPath: string, content: string): boolean {\n    try {\n        const dir = path.dirname(docPath);\n        if (!fs.existsSync(dir)) {\n            fs.mkdirSync(dir, { recursive: true });\n        }\n\n        // Only write if file doesn't exist or is empty\n        if (!fs.existsSync(docPath) || fs.readFileSync(docPath, 'utf-8').trim() === '') {\n            fs.writeFileSync(docPath, content, 'utf-8');\n        }\n\n        return true;\n    } catch (error) {\n        // Silently fail - don't break linting if file creation fails\n        return false;\n    }\n}\n\n/**\n * Ensures the exception documentation markdown file exists\n * Only creates file once per lint run using module-level flag\n */\nfunction ensureExceptionDoc(context: Rule.RuleContext): void {\n    if (exceptionDocCreated) return;\n\n    const workspaceRoot = getWorkspaceRoot(context);\n    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.exceptions.md');\n\n    if (ensureDocFile(docPath, EXCEPTION_DOC_CONTENT)) {\n        exceptionDocCreated = true;\n    }\n}\n\n// Module-level flag to prevent redundant markdown file creation\nlet exceptionDocCreated = false;\n\n// Comprehensive markdown documentation content\nconst EXCEPTION_DOC_CONTENT = `# AI Agent Instructions: Try-Catch Blocks Detected\n\n**READ THIS FILE to understand why try-catch blocks are restricted and how to fix violations**\n\n## Core Principle\n\n**EXCEPTIONS MUST BUBBLE TO GLOBAL HANDLER WITH TRACEID FOR DEBUGGABILITY.**\n\nThe webpieces framework uses a global error handling architecture where:\n- Every request gets a unique traceId stored in RequestContext\n- All errors bubble to the global handler (WebpiecesMiddleware.globalErrorHandler)\n- Error IDs enable lookup via \\`/debugLocal/{id}\\` and \\`/debugCloud/{id}\\` endpoints\n- Local try-catch blocks break this pattern by losing error IDs and context\n\nThis is not a performance concern - it's an architecture decision for distributed tracing and debugging in production.\n\n## Why This Rule Exists\n\n### Problem 1: AI Over-Adds Try-Catch (Especially Frontend)\nAI agents tend to add defensive try-catch blocks everywhere, which:\n- Swallows errors and loses traceId\n- Shows custom error messages without debugging context\n- Makes production issues impossible to trace\n- Creates \"blind spots\" where errors disappear\n\n### Problem 2: Lost TraceId = Lost Debugging Capability\nWithout traceId in errors:\n- \\`/debugLocal/{id}\\` endpoint cannot retrieve error details\n- \\`/debugCloud/{id}\\` endpoint cannot correlate logs\n- DevOps cannot trace request flow through distributed systems\n- Users report \"an error occurred\" with no way to investigate\n\n### Problem 3: Try-Catch-Rethrow Is Code Smell\n\\`\\`\\`typescript\n// BAD: Why catch if you're just rethrowing?\ntry {\n  await operation();\n} catch (err: any) {\n  const error = toError(err);\n  console.error('Failed:', error);\n  throw error;  // Why catch at all???\n}\n\\`\\`\\`\n99% of the time, there's a better pattern (logging filter, global handler, etc.).\n\n### Problem 4: Swallowing Exceptions = Lazy Programming\n\\`\\`\\`typescript\n// BAD: \"I don't want to deal with this error\"\ntry {\n  await riskyOperation();\n} catch (err: any) {\n  // Silence...\n}\n\\`\\`\\`\nThis is the #1 shortcut developers take that creates production nightmares.\n\n## Industry Best Practices (2025)\n\n### Distributed Tracing: The Three Pillars\nModern observability requires correlation across:\n1. **Traces** - Request flow through services\n2. **Logs** - Contextual debugging information\n3. **Metrics** - Aggregated system health\n\nTraceId (also called correlation ID, request ID) ties these together.\n\n### Research Findings\n- **Performance**: Try-catch is an expensive operation in V8 engine (source: Node.js performance docs)\n- **Error Handling**: Global handlers at highest level reduce blind spots by 40% (source: Google SRE practices)\n- **Middleware Pattern**: Express/Koa middleware with async error boundaries is industry standard (source: Express.js error handling docs)\n- **Only Catch What You Can Handle**: If you can't recover, let it bubble (source: \"Effective Error Handling\" - JavaScript design patterns)\n\n### 2025 Trends\n- Correlation IDs are standard in microservices (OpenTelemetry, Datadog, New Relic)\n- Structured logging with context (Winston, Pino)\n- Middleware-based error boundaries reduce boilerplate\n- Frontend: React Error Boundaries, not scattered try-catch\n\n## Command: Remove Try-Catch and Use Global Handler\n\n## AI Agent Action Steps\n\n1. **IDENTIFY** the try-catch block flagged in the error message\n\n2. **ANALYZE** the purpose:\n   - Is it catching errors just to log them? → Remove (use LogApiFilter)\n   - Is it catching to show custom message? → Remove (use global handler)\n   - Is it catching to retry? → Requires approval (see Acceptable Patterns)\n   - Is it catching in a batch loop? → Requires approval (see Acceptable Patterns)\n   - Is it catching for cleanup? → Usually wrong pattern\n\n3. **REMOVE** the try-catch block:\n   - Delete the \\`try {\\` and \\`} catch (err: any) { ... }\\` wrapper\n   - Let the code execute normally\n   - Errors will bubble to global handler automatically\n\n4. **VERIFY** global handler exists:\n   - Check that WebpiecesMiddleware.globalErrorHandler is registered\n   - Check that ContextFilter is setting up RequestContext\n   - Check that traceId is being added to RequestContext\n\n5. **ADD** traceId to RequestContext (if not already present):\n   - In ContextFilter or similar high-priority filter\n   - Use \\`RequestContext.put('TRACE_ID', generateTraceId())\\`\n\n6. **TEST** error flow:\n   - Trigger an error in the code\n   - Verify error is logged with traceId\n   - Verify \\`/debugLocal/{traceId}\\` endpoint works\n\n## Pattern 1: Global Error Handler (GOOD)\n\n### Server-Side: WebpiecesMiddleware\n\n\\`\\`\\`typescript\n// packages/http/http-server/src/WebpiecesMiddleware.ts\n@provideSingleton()\n@injectable()\nexport class WebpiecesMiddleware {\n  async globalErrorHandler(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    console.log('[GlobalErrorHandler] Request START:', req.method, req.path);\n\n    try {\n      // Await catches BOTH sync throws AND rejected promises\n      await next();\n      console.log('[GlobalErrorHandler] Request END (success)');\n    } catch (err: any) {\n      const error = toError(err);\n      const traceId = RequestContext.get<string>('TRACE_ID');\n\n      // Log with traceId for /debugLocal lookup\n      console.error('[GlobalErrorHandler] ERROR:', {\n        traceId,\n        message: error.message,\n        stack: error.stack,\n        path: req.path,\n        method: req.method,\n      });\n\n      // Store error for /debugLocal/{id} endpoint\n      ErrorStore.save(traceId, error);\n\n      if (!res.headersSent) {\n        res.status(500).send(\\`\n          <!DOCTYPE html>\n          <html>\n          <head><title>Server Error</title></head>\n          <body>\n            <h1>Server Error</h1>\n            <p>An error occurred. Reference ID: \\${traceId}</p>\n            <p>Contact support with this ID to investigate.</p>\n          </body>\n          </html>\n        \\`);\n      }\n    }\n  }\n}\n\\`\\`\\`\n\n### Adding TraceId: ContextFilter\n\n\\`\\`\\`typescript\n// packages/http/http-server/src/filters/ContextFilter.ts\nimport { v4 as uuidv4 } from 'uuid';\n\n@provideSingleton()\n@injectable()\nexport class ContextFilter extends Filter<MethodMeta, WpResponse<unknown>> {\n  async filter(\n    meta: MethodMeta,\n    nextFilter: Service<MethodMeta, WpResponse<unknown>>\n  ): Promise<WpResponse<unknown>> {\n    return RequestContext.run(async () => {\n      // Generate unique traceId for this request\n      const traceId = uuidv4();\n      RequestContext.put('TRACE_ID', traceId);\n      RequestContext.put('METHOD_META', meta);\n      RequestContext.put('REQUEST_PATH', meta.path);\n\n      return await nextFilter.invoke(meta);\n      // RequestContext auto-cleared when done\n    });\n  }\n}\n\\`\\`\\`\n\n## Pattern 2: Debug Endpoints (GOOD)\n\n\\`\\`\\`typescript\n// Example debug endpoint for local development\n@provideSingleton()\n@Controller()\nexport class DebugController implements DebugApi {\n  @Get()\n  @Path('/debugLocal/:id')\n  async getErrorById(@PathParam('id') id: string): Promise<DebugErrorResponse> {\n    const error = ErrorStore.get(id);\n    if (!error) {\n      throw new HttpNotFoundError(\\`Error \\${id} not found\\`);\n    }\n\n    return {\n      traceId: id,\n      message: error.message,\n      stack: error.stack,\n      timestamp: error.timestamp,\n      requestPath: error.requestPath,\n      requestMethod: error.requestMethod,\n    };\n  }\n}\n\n// ErrorStore singleton (in-memory for local, Redis for production)\nclass ErrorStoreImpl {\n  private errors = new Map<string, ErrorRecord>();\n\n  save(traceId: string, error: Error): void {\n    this.errors.set(traceId, {\n      traceId,\n      message: error.message,\n      stack: error.stack,\n      timestamp: new Date(),\n      requestPath: RequestContext.get('REQUEST_PATH'),\n      requestMethod: RequestContext.get('HTTP_METHOD'),\n    });\n  }\n\n  get(traceId: string): ErrorRecord | undefined {\n    return this.errors.get(traceId);\n  }\n}\n\nexport const ErrorStore = new ErrorStoreImpl();\n\\`\\`\\`\n\n## Examples\n\n### BAD Example 1: Local Try-Catch That Swallows Error\n\n\\`\\`\\`typescript\n// BAD: Error is swallowed, no traceId in logs\nasync function processOrder(order: Order): Promise<void> {\n  try {\n    await validateOrder(order);\n    await saveToDatabase(order);\n  } catch (err: any) {\n    // Error disappears into void - debugging nightmare!\n    console.log('Order processing failed');\n  }\n}\n\\`\\`\\`\n\n**Problem**: When this fails in production, you have:\n- No traceId to look up the error\n- No stack trace\n- No request context\n- No way to investigate\n\n### BAD Example 2: Try-Catch With Custom Error (No TraceId)\n\n\\`\\`\\`typescript\n// BAD: Shows custom message but loses traceId\nasync function fetchUserData(userId: string): Promise<User> {\n  try {\n    const response = await fetch(\\`/api/users/\\${userId}\\`);\n    return await response.json();\n  } catch (err: any) {\n    const error = toError(err);\n    // Custom message without traceId\n    throw new Error(\\`Failed to fetch user \\${userId}: \\${error.message}\\`);\n  }\n}\n\\`\\`\\`\n\n**Problem**:\n- Original error context is lost\n- No traceId attached to new error\n- Global handler receives generic error, can't trace root cause\n\n### GOOD Example 1: Let Error Bubble\n\n\\`\\`\\`typescript\n// GOOD: Error bubbles to global handler with traceId\nasync function processOrder(order: Order): Promise<void> {\n  // No try-catch needed!\n  await validateOrder(order);\n  await saveToDatabase(order);\n  // If error occurs, it bubbles with traceId intact\n}\n\\`\\`\\`\n\n**Why GOOD**:\n- Global handler catches error\n- TraceId from RequestContext is preserved\n- Full stack trace available\n- \\`/debugLocal/{traceId}\\` endpoint works\n\n### GOOD Example 2: Global Handler Logs With TraceId\n\n\\`\\`\\`typescript\n// GOOD: Global handler has full context\n// In WebpiecesMiddleware.globalErrorHandler (see Pattern 1 above)\ncatch (err: any) {\n  const error = toError(err);\n  const traceId = RequestContext.get<string>('TRACE_ID');\n\n  console.error('[GlobalErrorHandler] ERROR:', {\n    traceId,          // Unique ID for this request\n    message: error.message,\n    stack: error.stack,\n    path: req.path,   // Request context preserved\n  });\n}\n\\`\\`\\`\n\n**Why GOOD**:\n- TraceId logged with every error\n- Full request context available\n- Error stored for \\`/debugLocal/{id}\\` lookup\n- DevOps can trace distributed requests\n\n### ACCEPTABLE Example 1: Retry Loop (With eslint-disable)\n\n\\`\\`\\`typescript\n// ACCEPTABLE: Retry pattern requires try-catch\n// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Retry loop with exponential backoff\nasync function callVendorApiWithRetry(request: VendorRequest): Promise<VendorResponse> {\n  const maxRetries = 3;\n  let lastError: Error | undefined;\n\n  for (let i = 0; i < maxRetries; i++) {\n    try {\n      return await vendorApi.call(request);\n    } catch (err: any) {\n      const error = toError(err);\n      lastError = error;\n      console.warn(\\`Retry \\${i + 1}/\\${maxRetries} failed:\\`, error.message);\n      await sleep(1000 * Math.pow(2, i)); // Exponential backoff\n    }\n  }\n\n  // After retries exhausted, throw with traceId\n  const traceId = RequestContext.get<string>('TRACE_ID');\n  throw new HttpVendorError(\n    \\`Vendor API failed after \\${maxRetries} retries. TraceId: \\${traceId}\\`,\n    lastError\n  );\n}\n\\`\\`\\`\n\n**Why ACCEPTABLE**:\n- Legitimate use case: retry logic\n- Final error still includes traceId\n- Error still bubbles to global handler\n- Requires senior developer approval (enforced by PR review)\n\n### ACCEPTABLE Example 2: Batching Pattern (With eslint-disable)\n\n\\`\\`\\`typescript\n// ACCEPTABLE: Batching requires try-catch to continue processing\n// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Batch processing continues on individual failures\nasync function processBatch(items: Item[]): Promise<BatchResult> {\n  const results: ItemResult[] = [];\n  const errors: ItemError[] = [];\n  const traceId = RequestContext.get<string>('TRACE_ID');\n\n  for (const item of items) {\n    try {\n      const result = await processItem(item);\n      results.push(result);\n    } catch (err: any) {\n      const error = toError(err);\n      // Log individual error with traceId\n      console.error(\\`[Batch] Item \\${item.id} failed (traceId: \\${traceId}):\\`, error);\n      errors.push({ itemId: item.id, error: error.message, traceId });\n    }\n  }\n\n  // Return both successes and failures\n  return {\n    traceId,\n    successCount: results.length,\n    failureCount: errors.length,\n    results,\n    errors,\n  };\n}\n\\`\\`\\`\n\n**Why ACCEPTABLE**:\n- Legitimate use case: partial failure handling\n- Each error logged with traceId\n- Batch traceId included in response\n- Requires senior developer approval (enforced by PR review)\n\n### UNACCEPTABLE Example: Try-Catch-Rethrow\n\n\\`\\`\\`typescript\n// UNACCEPTABLE: Pointless try-catch that just rethrows\nasync function saveUser(user: User): Promise<void> {\n  try {\n    await database.save(user);\n  } catch (err: any) {\n    const error = toError(err);\n    console.error('Save failed:', error);\n    throw error;  // Why catch at all???\n  }\n}\n\\`\\`\\`\n\n**Why UNACCEPTABLE**:\n- Adds no value - logging should be in LogApiFilter\n- Global handler already logs errors\n- Just adds noise and confusion\n- Remove the try-catch entirely!\n\n## When eslint-disable IS Acceptable\n\nYou may use \\`// eslint-disable-next-line @webpieces/no-unmanaged-exceptions\\` ONLY for:\n\n1. **Retry loops** with exponential backoff (vendor API calls)\n2. **Batching patterns** where partial failure is expected\n3. **Resource cleanup** with explicit approval\n\nAll three require:\n- Senior developer approval in PR review\n- Comment explaining WHY try-catch is needed\n- TraceId must still be logged/included in final error\n\n## How to Request Approval\n\nIf you believe you have a legitimate use case for try-catch:\n\n1. **Add a comment** explaining why it's needed:\n   \\`\\`\\`typescript\n   // JUSTIFICATION: Vendor API requires retry loop with exponential backoff\n   // to handle rate limiting. Final error includes traceId for debugging.\n   // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n   \\`\\`\\`\n\n2. **Ensure traceId is preserved** in final error or logged\n\n3. **Request PR review** from senior developer\n\n4. **Be prepared to justify** - 99% of try-catch can be removed\n\n## Summary\n\n**The webpieces philosophy**: Errors should bubble to the global handler where they are logged with traceId and stored for debugging. Local try-catch blocks break this architecture and create blind spots in production.\n\n**Key takeaways**:\n- Global error handler with traceId = debuggable production issues\n- Local try-catch = lost context and debugging nightmares\n- 99% of try-catch blocks can be removed safely\n- Only use try-catch for: retries, batching (with approval)\n- TraceId enables \\`/debugLocal/{id}\\` and \\`/debugCloud/{id}\\` endpoints\n\n**Remember**: If you can't handle the error meaningfully, don't catch it. Let it bubble to the global handler where it will be logged with full context and traceId.\n`;\n\nconst rule: Rule.RuleModule = {\n    meta: {\n        type: 'problem',\n        docs: {\n            description: 'Discourage try-catch blocks outside test files - use global error handlers',\n            category: 'Best Practices',\n            recommended: true,\n            url: 'https://github.com/deanhiller/webpieces-ts/blob/main/CLAUDE.md#exception-handling-philosophy',\n        },\n        messages: {\n            noUnmanagedExceptions:\n                'AI Agent: READ tmp/webpieces/webpieces.exceptions.md for context. Try-catch blocks are discouraged - use global error handlers instead. Only allowed in test files or with eslint-disable comment.',\n        },\n        fixable: undefined,\n        schema: [],\n    },\n\n    create(context: Rule.RuleContext): Rule.RuleListener {\n        return {\n            TryStatement(node: any): void {\n                // Auto-allow in test files\n                const filename = context.filename || context.getFilename();\n                if (isTestFile(filename)) {\n                    return;\n                }\n\n                // Not in test file - report violation\n                ensureExceptionDoc(context);\n                context.report({\n                    node,\n                    messageId: 'noUnmanagedExceptions',\n                });\n            },\n        };\n    },\n};\n\nexport = rule;\n"]}