@webpieces/rules-config 0.2.116 → 0.2.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.2.116",
+  "version": "0.2.117",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/templates/webpieces.dependencies.md

@@ -0,0 +1,136 @@
+# Instructions: Architecture Dependency Violation
+
+IN GENERAL, it is better to avoid these changes and find a different way by moving classes
+around to existing packages you already depend on. It is not always avoidable though.
+A clean dependency graph keeps you out of huge trouble later.
+
+If you are a human, simply run these commands:
+* nx run architecture:visualize - to see the new dependencies and validate that change is desired
+* nx run architecture:generate - updates the dep graph
+* git diff architecture/dependencies.json - to see the deps changes you made
+
+**READ THIS FILE FIRST before making any changes!**
+
+## ⚠️ CRITICAL WARNING ⚠️
+
+**This is a VERY IMPORTANT change that has LARGE REPERCUSSIONS later!**
+
+Adding new dependencies creates technical debt that compounds over time:
+- Creates coupling between packages that may be hard to undo
+- Can create circular dependency tangles
+- Makes packages harder to test in isolation
+- Increases build times and bundle sizes
+- May force unnecessary upgrades across the codebase
+
+**DO NOT add dependencies without senior developer approval!**
+
+## Understanding the Error
+
+You've attempted to import from a package that is not in your project's allowed dependencies.
+The architecture enforces a layered dependency structure where:
+- Level 0 packages are foundation packages with NO dependencies on other @webpieces packages
+- Higher level packages can only depend on lower level packages
+- All dependencies must be explicitly declared
+
+## Steps to Resolve
+
+### Step 1: Generate Current Dependency Graph
+Run this command to see the current architecture:
+```bash
+npx nx run architecture:generate
+```
+This creates/updates `architecture/dependencies.json` showing all packages and their levels.
+
+### Step 2: Analyze the Proposed Change
+Ask yourself:
+1. **Is this import truly necessary?** Can you refactor to avoid it?
+2. **Should the code move instead?** Maybe the code belongs in a different package.
+3. **Will this create a cycle?** Use `npx nx graph` to visualize dependencies.
+4. **Can you use an interface/abstraction?** Define interface in lower-level package, implement in higher-level.
+
+### Step 3: Get Senior Developer Approval
+
+## 🛑 AI AGENTS: STOP HERE AND ASK FOR HUMAN APPROVAL! 🛑
+
+**YOU MUST NOT PROCEED TO STEP 4 WITHOUT EXPLICIT HUMAN APPROVAL!**
+
+**REQUIRED**: Discuss this architectural change with a senior developer before proceeding.
+- Explain why the dependency is needed
+- Show you've considered alternatives (Step 2)
+- **WAIT for explicit approval before making ANY changes to project.json or package.json**
+
+**AI Agent Instructions:**
+1. Present your analysis from Step 2 to the human
+2. Explain which package needs which dependency and why
+3. ASK: "Do you approve adding this dependency?"
+4. **DO NOT modify project.json or package.json until you receive explicit "yes" or approval**
+
+### Step 4: If Approved, Add the Dependency
+
+## ⛔ NEVER MODIFY THESE FILES WITHOUT HUMAN APPROVAL FROM STEP 3! ⛔
+
+Only after receiving explicit human approval in Step 3, make these changes:
+
+1. **Update project.json** - Add to `build.dependsOn`:
+   ```json
+   {
+     "targets": {
+       "build": {
+         "dependsOn": ["^build", "dep1:build", "NEW_PACKAGE:build"]
+       }
+     }
+   }
+   ```
+
+2. **Update package.json** - Add to `dependencies`:
+   ```json
+   {
+     "dependencies": {
+       "@webpieces/NEW_PACKAGE": "*"
+     }
+   }
+   ```
+
+### Step 5: Update Architecture Definition
+Run this command to validate and update the architecture:
+```bash
+npx nx run architecture:generate
+```
+
+This will:
+- Detect any cycles (which MUST be fixed before proceeding)
+- Update `architecture/dependencies.json` with the new dependency
+- Recalculate package levels
+
+### Step 6: Verify No Cycles
+```bash
+npx nx run architecture:validate-no-architecture-cycles
+```
+
+If cycles are detected, you MUST refactor to break the cycle. Common strategies:
+- Move shared code to a lower-level package
+- Use dependency inversion (interfaces in low-level, implementations in high-level)
+- Restructure package boundaries
+
+## Alternative Solutions (Preferred over adding dependencies)
+
+### Option A: Move the Code
+If you need functionality from another package, consider moving that code to a shared lower-level package.
+
+### Option B: Dependency Inversion
+Define an interface in the lower-level package, implement it in the higher-level package:
+```typescript
+// In foundation package (level 0)
+export interface Logger { log(msg: string): void; }
+
+// In higher-level package
+export class ConsoleLogger implements Logger { ... }
+```
+
+### Option C: Pass Dependencies as Parameters
+Instead of importing, receive the dependency as a constructor or method parameter.
+
+## Remember
+- Every dependency you add today is technical debt for tomorrow
+- The best dependency is the one you don't need
+- When in doubt, refactor rather than add dependencies

package/templates/webpieces.exceptions.md

@@ -0,0 +1,694 @@
+# AI Agent Instructions: Try-Catch Blocks Detected
+
+**READ THIS FILE to understand why try-catch blocks are restricted and how to fix violations**
+
+## GETTING STARTED: Rolling Out This Rule
+
+**Why this rule exists**: AI agents tend to randomly add try-catch blocks ~50% of the time, creating pointless error handling that swallows exceptions and breaks debugging.
+
+**How to roll out on existing codebases**:
+1. Enable the rule: `'@webpieces/no-unmanaged-exceptions': 'error'`
+2. Have AI add `// eslint-disable-next-line @webpieces/no-unmanaged-exceptions` to EACH try-catch line (NOT file-level disables)
+3. This forces AI to consciously acknowledge each exception handling location
+4. Going forward, the rule makes AI think twice before adding new try-catch blocks
+
+**What the global error handler provides** (when exceptions bubble up properly):
+1. **Logs it** - Full error with stack trace and traceId
+2. **Reports to operations** - Sends to monitoring (Sentry/Datadog) so AI/team can fix
+3. **Shows user-friendly error** - Pops error dialog with errorId (user receives email with same ID for support)
+
+**Per-line disables are intentional**: Each disable comment serves as documentation explaining WHY that specific try-catch exists, making code review and future AI sessions aware of the exception handling decision.
+
+## 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: Pointless Try-Catch-Rethrow
+```typescript
+// BAD: Catching just to rethrow without adding value
+try {
+  await operation();
+} catch (err: unknown) {
+  const error = toError(err);
+  console.error('Failed:', error);
+  throw error;  // No new info added - why catch?
+}
+```
+
+**However, try-catch-rethrow IS acceptable when:**
+1. **Adding context to the error**: `throw new Error("Failed to process order #123", { cause: error })`
+2. **Edge code logging** (see "Edge Code Patterns" section below)
+
+The key question: Are you adding meaningful information or context? If yes, it may be valid.
+
+### Problem 4: Swallowing Exceptions = Lazy Programming
+```typescript
+// BAD: "I don't want to deal with this error"
+try {
+  await riskyOperation();
+} catch (err: unknown) {
+  // 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 and ASK USER if needed:
+   - 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
+   - **Is this a global entry point?** → **ASK USER**: "I think this code is the entry point where we need a global try-catch block. Is this correct?" (95% of the time it is NOT!)
+   - **Is this edge code calling external services?** → **ASK USER**: "This looks like edge code calling an external service. Should I add request/response logging with try-catch?"
+   - **Is this form error handling?** → Valid IF: catches only `HttpUserError` for display AND rethrows other errors (see Form Error Handling Pattern)
+   - Is it adding context to the error before rethrowing? → May be valid (see Problem 3)
+
+3. **IF REMOVING** the try-catch block:
+   - Delete the `try {` and `} catch (err: unknown) { ... }` wrapper
+   - Let the code execute normally
+   - Errors will bubble to global handler automatically
+
+4. **IF KEEPING** (after user approval):
+   - Add eslint-disable comment with justification
+   - Ensure traceId is logged/preserved
+   - Follow patterns in "Global Try-Catch Entry Points" or "Edge Code Patterns" sections
+
+5. **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
+
+6. **ADD** traceId to RequestContext (if not already present):
+   - In ContextFilter or similar high-priority filter
+   - Use `RequestContext.put('TRACE_ID', generateTraceId())`
+
+7. **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: unknown) {
+      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: unknown) {
+    // 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: unknown) {
+    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: unknown) {
+  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: unknown) {
+      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: unknown) {
+      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: Pointless Try-Catch-Rethrow (Internal Code)
+
+```typescript
+// UNACCEPTABLE: Pointless try-catch in INTERNAL code
+async function saveUser(user: User): Promise<void> {
+  try {
+    await userRepository.save(user);  // Internal call, not edge
+  } catch (err: unknown) {
+    const error = toError(err);
+    console.error('Save failed:', error);
+    throw error;  // No value added - why catch?
+  }
+}
+```
+
+**Why UNACCEPTABLE for internal code**:
+- Adds no value - logging should be in LogApiFilter
+- Global handler already logs errors
+- Just adds noise and confusion
+- Remove the try-catch entirely!
+
+**CONTRAST with edge code (ACCEPTABLE)**:
+```typescript
+// ACCEPTABLE: Edge code calling external database service
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Edge code: database logging
+async function saveUserToDb(user: User): Promise<void> {
+  const traceId = RequestContext.get<string>('TRACE_ID');
+  try {
+    logRequest('[DB] Saving user', { traceId, userId: user.id });
+    await externalDbClient.save('users', user);  // EDGE: external service
+    logSuccess('[DB] User saved', { traceId, userId: user.id });
+  } catch (err: unknown) {
+    const error = toError(err);
+    logFailure('[DB] Save failed', { traceId, userId: user.id, error: error.message });
+    throw error;  // Rethrow - logging value at the edge
+  }
+}
+```
+
+**The difference**: Edge code benefits from request/response/failure logging at the service boundary. Internal code does not.
+
+## 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
+4. **Global error handler entry points** (see below)
+5. **Edge code patterns** for vendor/external service calls (see below)
+6. **Form error handling** - catching `HttpUserError` for display, rethrowing others (see below)
+
+All require:
+- Comment explaining WHY try-catch is needed
+- TraceId must still be logged/included in final error (or error must be rethrown)
+
+## Global Try-Catch Entry Points (MUST ASK USER)
+
+**CRITICAL: 95% of the time, the code you're looking at is NOT a global entry point!**
+
+Before adding a global try-catch, **AI agents MUST ask the user**: "I think this code is the entry point where we need a global try-catch block. Is this correct?"
+
+### Examples of LEGITIMATE Global Error Handlers
+
+These are the rare places where global try-catch IS correct:
+
+1. **Node.js/Express middleware** (at the TOP, after setting up traceId in context):
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Global error handler entry point
+app.use(async (req, res, next) => {
+  // First: set up traceId in RequestContext
+  const traceId = uuidv4();
+  RequestContext.put('TRACE_ID', traceId);
+
+  try {
+    await next();
+  } catch (err: unknown) {
+    const error = toError(err);
+    // Report to Sentry/observability
+    Sentry.captureException(error, { extra: { traceId } });
+    res.status(500).json({ error: 'Internal error', traceId });
+  }
+});
+```
+
+2. **RxJS global error handler**:
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- RxJS global unhandled error hook
+config.onUnhandledError = (err: any) => {
+  const error = toError(err);
+  Sentry.captureException(error);
+  console.error('[RxJS Unhandled]', error);
+};
+```
+
+3. **Browser window unhandled promise rejection**:
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Browser global unhandled promise handler
+window.addEventListener('unhandledrejection', (event) => {
+  const error = toError(event.reason);
+  Sentry.captureException(error);
+  console.error('[Unhandled Promise]', error);
+});
+```
+
+4. **Angular ErrorHandler** (may need try-catch to prevent double recording):
+```typescript
+@Injectable()
+export class GlobalErrorHandler implements ErrorHandler {
+  // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Angular global error handler
+  handleError(error: any): void {
+    try {
+      Sentry.captureException(error);
+    } catch (sentryError) {
+      // Prevent infinite loop if Sentry itself fails
+      console.error('[Sentry failed]', sentryError);
+    }
+    console.error('[Angular Error]', error);
+  }
+}
+```
+
+5. **3rd party vendor event listeners**:
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Vendor callback error boundary
+vendorSdk.on('event', async (data) => {
+  try {
+    await processVendorEvent(data);
+  } catch (err: unknown) {
+    const error = toError(err);
+    const traceId = RequestContext.get<string>('TRACE_ID');
+    Sentry.captureException(error, { extra: { traceId, vendorData: data } });
+    // Don't rethrow - vendor SDK may not handle errors gracefully
+  }
+});
+```
+
+**All global handlers should report to observability (Sentry, Datadog, etc.) in production.**
+
+## Edge Code Patterns (MUST ASK USER)
+
+Edge code is code that interacts with external systems (vendors, APIs, databases, email services, etc.). These often benefit from a try-catch pattern for **logging the full request/response cycle**.
+
+**AI agents MUST ask the user** before adding edge code try-catch: "This looks like edge code calling an external service. Should I add request/response logging with try-catch?"
+
+### Example: sendMail Pattern
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Edge code: external email service logging
+async function sendMail(request: MailRequest): Promise<MailResponse> {
+  const traceId = RequestContext.get<string>('TRACE_ID');
+
+  try {
+    logRequest('[Email] Sending', { traceId, to: request.to, subject: request.subject });
+    const response = await emailService.send(request);
+    logSuccess('[Email] Sent', { traceId, messageId: response.messageId });
+    return response;
+  } catch (err: unknown) {
+    const error = toError(err);
+    logFailure('[Email] Failed', { traceId, error: error.message, to: request.to });
+    throw error;  // Rethrow - adds logging value at the edge
+  }
+}
+```
+
+### Why This Pattern Is Valuable at Edges
+
+1. **Complete audit trail**: Request logged, then either success OR failure logged
+2. **Vendor debugging**: When vendor says "we never received it", you have proof
+3. **Performance monitoring**: Track timing at service boundaries
+4. **Correlation**: TraceId connects this edge call to the overall request
+
+### Where Edge Code Patterns Apply
+
+- HTTP client calls to external APIs
+- Database operations (especially writes)
+- Message queue publish/consume
+- Email/SMS/notification services
+- Payment gateway calls
+- File storage operations (S3, GCS, etc.)
+- Any call leaving your service boundary
+
+## Form Error Handling Pattern (Client-Side)
+
+Frontend forms often need to catch user-facing errors (like validation errors) to display in the UI, while rethrowing unexpected errors to the global handler.
+
+**This pattern is ACCEPTABLE because**:
+- It catches ONLY user-facing errors (`HttpUserError`) for display
+- Unexpected errors are RETHROWN (not swallowed)
+- Server throws `HttpUserError` → protocol translates to error payload → client translates back to exception
+
+### Example: Form Submission Error Handling
+```typescript
+// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Form error display: catch user errors, rethrow others
+async submitForm(): Promise<void> {
+  try {
+    await this.apiClient.saveData(this.formData);
+    this.router.navigate(['/success']);
+  } catch (err: unknown) {
+    const error = toError(err);
+
+    if (error instanceof HttpUserError) {
+      // User-facing error - display in form
+      this.formError = error.message;
+      this.cdr.detectChanges();
+    } else {
+      // Unexpected error - let global handler deal with it
+      throw error;
+    }
+  }
+}
+```
+
+### Why This Pattern Is Valid
+
+1. **Selective catching**: Only catches errors meant for user display
+2. **No swallowing**: Unexpected errors bubble to global handler with traceId
+3. **Protocol design**: Server intentionally throws `HttpUserError` for user-facing messages
+4. **UX requirement**: Forms must show validation errors inline, not via global error page
+
+### Key Requirements
+
+- **ONLY catch specific error types** (e.g., `HttpUserError`, `ValidationError`)
+- **ALWAYS rethrow** errors that aren't user-facing
+- The server-side code should throw `HttpUserError` for user-displayable messages
+
+## 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 in internal code = lost context and debugging nightmares
+- 95% of try-catch blocks can be removed safely
+- Acceptable try-catch uses: retries, batching, global entry points, edge code
+- **AI agents MUST ask user** before adding global try-catch or edge code patterns
+- TraceId enables `/debugLocal/{id}` and `/debugCloud/{id}` endpoints
+
+**Acceptable patterns (with eslint-disable)**:
+1. **Global entry points**: Express middleware, RxJS error hooks, Angular ErrorHandler, browser unhandledrejection
+2. **Edge code**: External API calls, database operations, email services - use logRequest/logSuccess/logFailure pattern
+3. **Retry loops**: Vendor APIs with exponential backoff
+4. **Batching**: Partial failure handling where processing must continue
+5. **Form error handling**: Catch `HttpUserError` for UI display, rethrow all other errors
+
+**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.
+

package/templates/webpieces.filesize.md

@@ -0,0 +1,173 @@
+# AI Agent Instructions: File Too Long
+
+**READ THIS FILE to fix files that are too long**
+
+## Core Principle
+
+With **stateless systems + dependency injection, refactor is trivial**.
+Pick a method or a few and move to new class XXXXX, then inject XXXXX
+into all users of those methods via the constructor.
+Delete those methods from original class.
+
+**99% of files can be less than the configured max lines of code.**
+
+Files should contain a SINGLE COHESIVE UNIT.
+- One class per file (Java convention)
+- If class is too large, extract child responsibilities
+- Use dependency injection to compose functionality
+
+## Command: Reduce File Size
+
+### Step 1: Check for Multiple Classes
+If the file contains multiple classes, **SEPARATE each class into its own file**.
+
+```typescript
+// BAD: UserController.ts (multiple classes)
+export class UserController { /* ... */ }
+export class UserValidator { /* ... */ }
+export class UserNotifier { /* ... */ }
+
+// GOOD: Three separate files
+// UserController.ts
+export class UserController { /* ... */ }
+
+// UserValidator.ts
+export class UserValidator { /* ... */ }
+
+// UserNotifier.ts
+export class UserNotifier { /* ... */ }
+```
+
+### Step 2: Extract Child Responsibilities (if single class is too large)
+
+#### Pattern: Create New Service Class with Dependency Injection
+
+```typescript
+// BAD: UserController.ts (800 lines, single class)
+@provideSingleton()
+@Controller()
+export class UserController {
+  // 200 lines: CRUD operations
+  // 300 lines: validation logic
+  // 200 lines: notification logic
+  // 100 lines: analytics logic
+}
+
+// GOOD: Extract validation service
+// 1. Create UserValidationService.ts
+@provideSingleton()
+export class UserValidationService {
+  validateUserData(data: UserData): ValidationResult {
+    // 300 lines of validation logic moved here
+  }
+
+  validateEmail(email: string): boolean { /* ... */ }
+  validatePassword(password: string): boolean { /* ... */ }
+}
+
+// 2. Inject into UserController.ts
+@provideSingleton()
+@Controller()
+export class UserController {
+  constructor(
+    @inject(TYPES.UserValidationService)
+    private validator: UserValidationService
+  ) {}
+
+  async createUser(data: UserData): Promise<User> {
+    const validation = this.validator.validateUserData(data);
+    if (!validation.isValid) {
+      throw new ValidationError(validation.errors);
+    }
+    // ... rest of logic
+  }
+}
+```
+
+## AI Agent Action Steps
+
+1. **ANALYZE** the file structure:
+   - Count classes (if >1, separate immediately)
+   - Identify logical responsibilities within single class
+
+2. **IDENTIFY** "child code" to extract:
+   - Validation logic -> ValidationService
+   - Notification logic -> NotificationService
+   - Data transformation -> TransformerService
+   - External API calls -> ApiService
+   - Business rules -> RulesEngine
+
+3. **CREATE** new service file(s):
+   - Start with temporary name: `XXXX.ts` or `ChildService.ts`
+   - Add `@provideSingleton()` decorator
+   - Move child methods to new class
+
+4. **UPDATE** dependency injection:
+   - Add to `TYPES` constants (if using symbol-based DI)
+   - Inject new service into original class constructor
+   - Replace direct method calls with `this.serviceName.method()`
+
+5. **RENAME** extracted file:
+   - Read the extracted code to understand its purpose
+   - Rename `XXXX.ts` to logical name (e.g., `UserValidationService.ts`)
+
+6. **VERIFY** file sizes:
+   - Original file should now be under the limit
+   - Each extracted file should be under the limit
+   - If still too large, extract more services
+
+## Examples of Child Responsibilities to Extract
+
+| If File Contains | Extract To | Pattern |
+|-----------------|------------|---------|
+| Validation logic (200+ lines) | `XValidator.ts` or `XValidationService.ts` | Singleton service |
+| Notification logic (150+ lines) | `XNotifier.ts` or `XNotificationService.ts` | Singleton service |
+| Data transformation (200+ lines) | `XTransformer.ts` | Singleton service |
+| External API calls (200+ lines) | `XApiClient.ts` | Singleton service |
+| Complex business rules (300+ lines) | `XRulesEngine.ts` | Singleton service |
+| Database queries (200+ lines) | `XRepository.ts` | Singleton service |
+
+## WebPieces Dependency Injection Pattern
+
+```typescript
+// 1. Define service with @provideSingleton
+import { provideSingleton } from '@webpieces/http-routing';
+
+@provideSingleton()
+export class MyService {
+  doSomething(): void { /* ... */ }
+}
+
+// 2. Inject into consumer
+import { inject } from 'inversify';
+import { TYPES } from './types';
+
+@provideSingleton()
+@Controller()
+export class MyController {
+  constructor(
+    @inject(TYPES.MyService) private service: MyService
+  ) {}
+}
+```
+
+## Escape Hatch
+
+If refactoring is genuinely not feasible (generated files, complex algorithms, etc.),
+add a disable comment at the TOP of the file (within first 5 lines) with a DATE:
+
+```typescript
+// webpieces-disable max-lines-modified-files 2025/01/15 -- Complex generated file, refactoring would break generation
+```
+
+**IMPORTANT**: The date format is yyyy/mm/dd. The disable will EXPIRE after 1 month from this date.
+After expiration, you must either fix the file or update the date to get another month.
+This ensures that disable comments are reviewed periodically.
+
+For ESLint-enforced file size limits, use:
+
+```typescript
+// eslint-disable-next-line @webpieces/max-file-lines
+```
+
+Remember: Find the "child code" and pull it down into a new class. Once moved, the code's purpose becomes clear, making it easy to rename to a logical name.

package/templates/webpieces.methods.md

@@ -0,0 +1,97 @@
+# AI Agent Instructions: Method Too Long
+
+**READ THIS FILE to fix methods that are too long**
+
+## Core Principle
+Every method should read like a TABLE OF CONTENTS of a book.
+- Each method call is a "chapter"
+- When you dive into a method, you find another table of contents
+- Keeping methods under 70 lines is achievable with proper extraction
+
+## Command: Extract Code into Named Methods
+
+### Pattern 1: Extract Loop Bodies
+```typescript
+// BAD: 50 lines embedded in loop
+for (const order of orders) {
+  // 20 lines of validation logic
+  // 15 lines of processing logic
+  // 10 lines of notification logic
+}
+
+// GOOD: Extracted to named methods
+for (const order of orders) {
+  validateOrder(order);
+  processOrderItems(order);
+  sendNotifications(order);
+}
+```
+
+### Pattern 2: Try-Catch Wrapper for Exception Handling
+```typescript
+// GOOD: Separates success path from error handling
+async function handleRequest(req: Request): Promise<Response> {
+  // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+  try {
+    return await executeRequest(req);
+  } catch (err: unknown) {
+    const error = toError(err);
+    return createErrorResponse(error);
+  }
+}
+```
+
+### Pattern 3: Sequential Method Calls (Table of Contents)
+```typescript
+// GOOD: Self-documenting steps
+function processOrder(order: Order): void {
+  validateOrderData(order);
+  calculateTotals(order);
+  applyDiscounts(order);
+  processPayment(order);
+  updateInventory(order);
+  sendConfirmation(order);
+}
+```
+
+### Pattern 4: Separate Data Object Creation
+```typescript
+// BAD: 15 lines of inline object creation
+doSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });
+
+// GOOD: Extract to factory method
+const request = createRequestObject(data);
+doSomething(request);
+```
+
+### Pattern 5: Extract Inline Logic to Named Functions
+```typescript
+// BAD: Complex inline logic
+if (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {
+  // 30 lines of admin logic
+}
+
+// GOOD: Extract to named methods
+if (isAdminWithWriteAccess(user)) {
+  performAdminOperation(user);
+}
+```
+
+## AI Agent Action Steps
+
+1. **IDENTIFY** the long method in the error message
+2. **READ** the method to understand its logical sections
+3. **EXTRACT** logical units into separate methods with descriptive names
+4. **REPLACE** inline code with method calls
+5. **VERIFY** each extracted method is <70 lines
+6. **TEST** that functionality remains unchanged
+
+## Examples of "Logical Units" to Extract
+- Validation logic -> `validateX()`
+- Data transformation -> `transformXToY()`
+- API calls -> `fetchXFromApi()`
+- Object creation -> `createX()`
+- Loop bodies -> `processItem()`
+- Error handling -> `handleXError()`
+
+Remember: Methods should read like a table of contents. Each line should be a "chapter title" (method call) that describes what happens, not how it happens.

package/templates/webpieces.methodsize.md

@@ -0,0 +1,132 @@
+# Instructions: Method Too Long
+
+## Requirement
+
+**~99% of the time**, you can stay under the `limit` from nx.json
+by extracting logical units into well-named methods.
+Nearly all software can be written with methods under this size.
+Take the extra time to refactor - it's worth it for long-term maintainability.
+
+## The "Table of Contents" Principle
+
+Good code reads like a book's table of contents:
+- Chapter titles (method names) tell you WHAT happens
+- Reading chapter titles gives you the full story
+- You can dive into chapters (implementations) for details
+
+## Why Limit Method Sizes?
+
+Methods under reasonable limits are:
+- Easy to review in a single screen
+- Simple to understand without scrolling
+- Quick for AI to analyze and suggest improvements
+- More testable in isolation
+- Self-documenting through well-named extracted methods
+
+## Gradual Cleanup Strategy
+
+This codebase uses a gradual cleanup approach:
+- **New methods**: Must be under `limit` from nx.json
+- **Modified methods**: Must be under `limit` from nx.json
+- **Untouched methods**: No limit (legacy code is allowed until touched)
+
+## How to Refactor
+
+Instead of:
+```typescript
+async processOrder(order: Order): Promise<Result> {
+    // 100 lines of validation, transformation, saving, notifications...
+}
+```
+
+Write:
+```typescript
+async processOrder(order: Order): Promise<Result> {
+    const validated = this.validateOrder(order);
+    const transformed = this.applyBusinessRules(validated);
+    const saved = await this.saveToDatabase(transformed);
+    await this.notifyStakeholders(saved);
+    return this.buildResult(saved);
+}
+```
+
+Now the main method is a "table of contents" - each line tells part of the story!
+
+## Patterns for Extraction
+
+### Pattern 1: Extract Loop Bodies
+```typescript
+// BEFORE
+for (const item of items) {
+    // 20 lines of processing
+}
+
+// AFTER
+for (const item of items) {
+    this.processItem(item);
+}
+```
+
+### Pattern 2: Extract Conditional Blocks
+```typescript
+// BEFORE
+if (isAdmin(user)) {
+    // 15 lines of admin logic
+}
+
+// AFTER
+if (isAdmin(user)) {
+    this.handleAdminUser(user);
+}
+```
+
+### Pattern 3: Extract Data Transformations
+```typescript
+// BEFORE
+const result = {
+    // 10+ lines of object construction
+};
+
+// AFTER
+const result = this.buildResultObject(data);
+```
+
+## If Refactoring Is Not Feasible
+
+Sometimes methods genuinely need to be longer (complex algorithms, state machines, etc.).
+
+**Escape hatch for new methods**: Add a webpieces-disable comment with justification:
+
+```typescript
+// webpieces-disable max-lines-new-methods -- Complex state machine, splitting reduces clarity
+async complexStateMachine(): Promise<void> {
+    // ... longer method with justification
+}
+```
+
+**Escape hatch for modified methods**: Add a webpieces-disable comment with DATE and justification:
+
+```typescript
+// webpieces-disable max-lines-modified 2025/01/15 -- Complex state machine, splitting reduces clarity
+async complexStateMachine(): Promise<void> {
+    // ... longer method with justification
+}
+```
+
+**IMPORTANT**: The date format is yyyy/mm/dd. The disable will EXPIRE after 1 month from this date.
+After expiration, you must either fix the method or update the date to get another month.
+This ensures that disable comments are reviewed periodically.
+
+## AI Agent Action Steps
+
+1. **READ** the method to understand its logical sections
+2. **IDENTIFY** logical units that can be extracted
+3. **EXTRACT** into well-named private methods
+4. **VERIFY** the main method now reads like a table of contents
+5. **IF NOT FEASIBLE**: Add webpieces-disable comment with clear justification
+
+## Remember
+
+- Every method you write today will be read many times tomorrow
+- The best code explains itself through structure
+- When in doubt, extract and name it

package/templates/webpieces.transitivedeps.md

@@ -0,0 +1,102 @@
+# AI Agent Instructions: Redundant Transitive Dependency Violation
+
+**READ THIS FILE FIRST before making any changes!**
+
+## Why This Rule Exists
+
+This rule keeps the architecture dependency graph **CLEAN and SIMPLE**.
+
+When you run `npx nx run architecture:visualize`, it generates a visual diagram of all
+package dependencies. Without this rule, you end up with a tangled mess of 100+ lines
+where everything depends on everything - making it impossible to understand.
+
+**Clean graphs = easier understanding for humans AND AI agents.**
+
+## Understanding the Error
+
+You have a **redundant transitive dependency**. This means:
+
+1. Project A directly depends on Project C
+2. BUT Project A also depends on Project B
+3. AND Project B already brings in Project C (transitively)
+
+Therefore, Project A's direct dependency on C is **redundant** - it's already available
+through B. This extra line clutters the dependency graph.
+
+**Example:**
+```
+http-server depends on: [http-routing, http-filters, core-util]
+                                         ^^^^^^^^^    ^^^^^^^^
+                                         REDUNDANT!   REDUNDANT!
+
+Why? Because http-routing already brings in:
+  - http-filters (direct)
+  - core-util (via http-api)
+```
+
+## How to Fix
+
+### Step 1: Identify the Redundant Dependency
+
+Look at the error message. It tells you:
+- Which project has the problem
+- Which dependency is redundant
+- Which other dependency already brings it in
+
+### Step 2: Remove from project.json
+
+Remove the redundant dependency from `build.dependsOn`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "dependsOn": [
+        "^build",
+        "http-routing:build"
+        // REMOVE: "http-filters:build"  <-- redundant, http-routing brings it in
+        // REMOVE: "core-util:build"     <-- redundant, http-routing brings it in
+      ]
+    }
+  }
+}
+```
+
+### Step 3: Remove from package.json
+
+Remove the redundant dependency from `dependencies`:
+
+```json
+{
+  "dependencies": {
+    "@webpieces/http-routing": "*"
+    // REMOVE: "@webpieces/http-filters": "*"  <-- redundant
+    // REMOVE: "@webpieces/core-util": "*"     <-- redundant
+  }
+}
+```
+
+### Step 4: Regenerate Architecture
+
+```bash
+npx nx run architecture:generate
+```
+
+### Step 5: Verify
+
+```bash
+npm run build-all
+```
+
+## Important Notes
+
+- You DON'T lose access to the transitive dependency - it's still available through the parent
+- This is about keeping the DECLARED dependencies minimal and clean
+- The actual runtime/compile behavior is unchanged
+- TypeScript will still find the types through the transitive path
+
+## Remember
+
+- Fewer lines in the graph = easier to understand
+- Only declare what you DIRECTLY need that isn't already transitively available
+- When in doubt, check with `npx nx run architecture:visualize`