te.js 1.3.1 → 2.0.0

package/.cursor/plans/ai_native_framework_features_5bb1a20a.plan.md

@@ -0,0 +1,234 @@
+---
+name: AI Native Framework Features
+overview: 'A framework that uses AI/LLM internally for its own features—not to expose LLM calls to developers, but to make the framework itself smarter: intelligent error handling, semantic routing, auto-documentation, self-optimization, and more.'
+todos: []
+isProject: false
+---
+
+# AI-Native Framework: Internal AI Features
+
+## What "AI Internally" Means
+
+**Not:** A framework that lets developers call LLMs (`ammo.llm()`, chat endpoints, etc.)
+
+**Yes:** A framework that **uses AI internally** to enhance its own capabilities. The framework itself is smarter—routing, errors, config, docs, and observability are powered by AI behind the scenes.
+
+---
+
+## Pain Points a Framework Can Solve by Using AI Internally
+
+### 1. Useless Error Messages
+
+**Pain:** "Cannot read property 'id' of undefined" — developer spends 20 minutes tracing where it came from.
+
+**AI internally:** Framework catches the error, uses AI to analyze stack trace + request context + code, returns a **plain-language explanation** and **suggested fix** in the response or logs.
+
+```
+Error: User lookup failed in GET /users/:id
+Cause: ammo.payload.id is undefined when id is "undefined" (string from query)
+Fix: Validate route param before use: if (!ammo.payload.id) ammo.notFound();
+```
+
+### 2. Routing is Rigid
+
+**Pain:** URLs must match exactly. Typos, alternate phrasings, or semantic equivalents (e.g. "user" vs "account") hit 404.
+
+**AI internally:** **Semantic routing** — framework uses embeddings + intent matching to route requests to the right handler even when the path doesn't match literally. "Get my account info" could route to `/users/:id` when confidence is high. Low confidence → 404 or clarification.
+
+### 3. Documentation is Always Stale
+
+**Pain:** Docs drift from code. New routes, changed params, deprecated endpoints—docs don't reflect reality.
+
+**AI internally:** Framework **auto-generates docs** from registered targets, handlers, and schemas. On startup or via CLI, it produces OpenAPI/JSON Schema. When code changes, docs update. Optional: natural language descriptions from JSDoc/comments.
+
+### 4. Configuration is Guesswork
+
+**Pain:** "What rate limit should I use?" "What body size?" Developers copy-paste from examples or guess.
+
+**AI internally:** **Natural language config** — "I want to handle 1000 req/min with strict rate limiting" → framework uses AI to suggest `maxRequests: 1000`, `algorithm: 'token-bucket'`, etc. Or: **self-tuning** — framework observes traffic, suggests config changes (e.g. "Consider increasing BODY_MAX_SIZE based on observed payloads").
+
+### 5. Debugging is Manual Correlation
+
+**Pain:** Logs, traces, and errors are scattered. Developer manually correlates "this 500 at 3:42pm" with "this Redis timeout at 3:41pm."
+
+**AI internally:** **AI-powered root cause analysis** — framework aggregates logs, traces, and metrics; uses AI to suggest "Likely cause: Redis connection dropped. See trace X. Suggested fix: check Redis URL and retry logic."
+
+### 6. Malformed Input = Generic 400
+
+**Pain:** Client sends `{ "name": 123 }` instead of `{ "name": "string" }`. Framework returns "Bad Request" with no guidance.
+
+**AI internally:** **Intelligent validation errors** — AI suggests what the client likely meant: "Field 'name' expected string, got number. Did you mean to send a string? Example: { name: John }."
+
+### 7. Recovery Requires Humans
+
+**Pain:** Rate limit hit, DB timeout, or transient failure → 503. Human must retry or investigate.
+
+**AI internally:** **Auto-remediation** — framework can attempt retries with backoff, fallback to cached response, or route to a degraded handler. Optional: "This looks like a transient DB error; retrying in 2s" and auto-retry before returning 503.
+
+### 8. Security is Reactive
+
+**Pain:** Unusual traffic patterns (DDoS, scraping, abuse) are detected only after damage.
+
+**AI internally:** **Anomaly detection** — framework uses ML/AI on request patterns (IP, path, frequency, payload size) to flag anomalies. Can auto-trigger stricter rate limits, CAPTCHA, or alerting.
+
+---
+
+## Recommended Internal AI Features for Tejas
+
+### Tier 1: High Impact, Clear Value
+
+1. **Intelligent Error Responses**
+
+- When `errorHandler` catches an error, optionally call AI with: stack trace, `ammo` context (path, method, payload keys), recent logs
+- AI returns: human-readable cause, suggested fix, relevant doc link
+- Attach to `LOG_EXCEPTIONS` output or optional `X-Error-Hint` header (dev only)
+- Location: extend [server/handler.js](server/handler.js) `errorHandler`, new `utils/ai-error-analyzer.js`
+
+1. **Semantic Routing (Optional Mode)**
+
+- When exact `aim()` match fails, optionally use embeddings + intent registry to find best-matching target
+- Each target can declare: `intents: ["get user", "fetch account", "user profile"]`
+- Low confidence → fall through to 404
+- Requires: embedding provider (OpenAI, local model), intent index
+- Location: extend [server/targets/registry.js](server/targets/registry.js), new `server/targets/semantic-router.js`
+
+1. **Auto-Generated Documentation**
+
+- CLI or startup hook: `tejas docs` or `app.withAutoDocs()`
+- Scans `targetRegistry.getAllEndpoints()`, infers schemas from handler patterns or explicit annotations
+- Outputs OpenAPI spec, or serves `/docs` with interactive UI
+- Optional: AI enhances descriptions from JSDoc
+- Location: new `utils/auto-docs.js`, optional `docs/` route
+
+### Tier 2: Developer Experience
+
+1. **Natural Language Config**
+
+- `app.configure("I need strict rate limiting for 500 req/min and 5MB body limit")`
+- AI parses intent, returns config object; user can approve or edit
+- Or: interactive `tejas init` that asks in plain language and generates `tejas.config.json`
+- Location: new `utils/ai-config.js`, CLI
+
+1. **Smart Validation Errors**
+
+- When body-parser or validation fails, AI suggests corrections: "Expected 'email' as string; received number. Did you mean to send a string?"
+- Integrates with existing body parsing in [server/ammo/body-parser.js](server/ammo/body-parser.js)
+- Location: extend body-parser error path, new `utils/ai-validation-hint.js`
+
+1. **Root Cause Analysis (Observability)**
+
+- When `LOG_EXCEPTIONS` is on, batch recent logs and send to AI for correlation
+- "Last 5 errors: Redis timeout, Redis timeout, DB connection refused. Likely cause: database connectivity. Check Redis URL."
+- Can run as background job or on-demand via admin endpoint
+- Location: new `utils/ai-rca.js`, optional admin target
+
+### Tier 3: Advanced / Later
+
+1. **Auto-Remediation**
+
+- Configurable: on 503/timeout, framework retries N times with backoff before returning
+- Or: fallback to cached/stale response when available
+- Requires policy: "when X, do Y"
+- Location: middleware or handler wrapper
+
+1. **Anomaly Detection**
+
+- Framework tracks request patterns; ML model (or rules) flags anomalies
+- Triggers: alert, stricter rate limit, CAPTCHA challenge
+- Heavier dependency; may be plugin
+- Location: new `middlewares/anomaly-detector.js` (optional)
+
+---
+
+## Architecture: AI as Internal Service
+
+```mermaid
+flowchart TB
+    subgraph Request [Normal Request Flow]
+        Req[HTTP Request]
+        Handler[handler.js]
+        Ammo[Ammo]
+        Registry[TargetRegistry]
+    end
+
+    subgraph AI [AI Internal Services]
+        ErrorAnalyzer[Error Analyzer]
+        SemanticRouter[Semantic Router]
+        ConfigGen[Config Generator]
+        DocGen[Doc Generator]
+        RCA[Root Cause Analysis]
+    end
+
+    Req --> Registry
+    Registry -->|"exact match"| Handler
+    Registry -->|"no match"| SemanticRouter
+    SemanticRouter -->|"high confidence"| Handler
+    SemanticRouter -->|"low confidence"| NotFound[404]
+
+    Handler --> Ammo
+    Ammo --> Response[Response]
+
+    Handler -->|"throws"| ErrorAnalyzer
+    ErrorAnalyzer -->|"enriched error"| Logs[Logs / X-Error-Hint]
+
+    subgraph Dev [Dev / CLI]
+        Init[tejas init]
+        Docs[tejas docs]
+        Init --> ConfigGen
+        Docs --> DocGen
+    end
+```
+
+**Design principle:** AI is **opt-in** and **configurable**. Each feature can be disabled. AI calls happen in the framework's own code paths, not in user handlers.
+
+---
+
+## Implementation Considerations
+
+### When to Call AI
+
+- **Synchronous (blocking):** Error analysis, validation hints — adds latency. Make it opt-in, async where possible (e.g. log enrichment in background).
+- **Asynchronous (non-blocking):** Doc generation, config suggestion, RCA — run on CLI or cron, not per-request.
+
+### Cost and Latency
+
+- Every AI call costs money and adds latency. Features should be:
+  - **Dev-only** where possible (error hints, config gen)
+  - **Cached** (semantic route index, intent embeddings)
+  - **Batchable** (RCA over last N errors, not per error)
+
+### Provider Abstraction
+
+- Framework needs one AI provider interface: `analyzeError(context)`, `matchIntent(query, intents)`, `suggestConfig(nl)`, etc.
+- Pluggable: OpenAI, Anthropic, local Ollama, or disabled
+- Config: `app.withAI({ provider: 'openai', apiKey: env('OPENAI_API_KEY'), features: ['errorAnalysis', 'semanticRouting'] })`
+
+### Privacy and Security
+
+- Never send sensitive data (tokens, passwords, PII) to AI without user consent
+- Error analysis: sanitize stack traces, redact payload values
+- Semantic routing: only path/headers, not body
+
+---
+
+## Summary: Pain Points Solved by Internal AI
+
+| Pain Point                | Internal AI Feature        | User-Visible Benefit                 |
+| ------------------------- | -------------------------- | ------------------------------------ |
+| Useless errors            | Intelligent error analysis | Plain-language cause + suggested fix |
+| Rigid routing             | Semantic routing           | Intent-based matching, fewer 404s    |
+| Stale docs                | Auto-generated docs        | Always-in-sync OpenAPI, `/docs`      |
+| Config guesswork          | Natural language config    | "I need X" → suggested config        |
+| Manual debugging          | Root cause analysis        | Correlated insights from logs        |
+| Generic validation errors | Smart validation hints     | "Did you mean...?" suggestions       |
+| Human-only recovery       | Auto-remediation           | Retries, fallbacks, degraded mode    |
+| Reactive security         | Anomaly detection          | Proactive abuse detection            |
+
+---
+
+## Next Steps (When Implementing)
+
+1. **Error analysis** — highest impact, dev-only, no user code changes. Add `withAI({ features: ['errorAnalysis'] })`.
+2. **Auto-docs** — no AI required for v1 (static from registry); add AI-enhanced descriptions later.
+3. **Semantic routing** — requires intent registry and embeddings; good for apps with many similar routes.
+4. **Natural language config** — CLI-only, great for `tejas init` experience.

package/.cursor/plans/auto_error_fix_agent_e68979c5.plan.md

@@ -0,0 +1,356 @@
+---
+name: Auto Error Fix Agent
+overview: When code hits an error (test failure or runtime exception), trigger an AI agent that analyzes the error, attempts a fix, and creates a PR on GitHub for review.
+todos: []
+isProject: false
+---
+
+# Auto Error Fix Agent Plan
+
+## Overview
+
+When an error occurs—either a **test failure** or a **runtime exception**—an AI agent is triggered to:
+
+1. Analyze the error (stack trace, context, failing code)
+2. Propose and apply a fix
+3. Create a branch, commit, push, and open a PR on GitHub
+
+---
+
+## Trigger Modes
+
+| Mode                  | When                                                                                                                      | Use Case               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| **Test failure**      | `npm run test:fix` or `tejas auto-fix` runs tests; on failure, agent triggers                                             | Local dev, CI pipeline |
+| **Runtime exception** | Error caught in [server/handler.js](server/handler.js) `errorHandler`; if `AUTO_ERROR_FIX` enabled, enqueue agent (async) | Dev server only        |
+
+**Recommendation:** Start with **test failure** mode. It's deterministic, reproducible, and doesn't add latency to request handling. Runtime mode can be added later as opt-in for dev.
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Trigger [Trigger]
+        Tests[Vitest Run]
+        Runtime[Runtime Error]
+    end
+
+    subgraph Agent [AI Agent]
+        Capture[Capture Context]
+        Analyze[Analyze Error]
+        Propose[Propose Fix]
+        Apply[Apply Changes]
+        Verify[Run Tests Again]
+    end
+
+    subgraph GitHub [GitHub]
+        Branch[Create Branch]
+        Commit[Commit]
+        Push[Push]
+        PR[Open PR]
+    end
+
+    Tests -->|"fail"| Capture
+    Runtime -->|"AUTO_ERROR_FIX"| Capture
+
+    Capture --> ShouldTrigger{shouldTrigger?}
+    ShouldTrigger -->|"no"| Skip[Skip - log only]
+    ShouldTrigger -->|"yes"| Analyze
+    Analyze --> Propose
+    Propose --> Apply
+    Apply --> Verify
+    Verify -->|"pass"| Branch
+    Verify -->|"fail"| Log[Log / Notify]
+    Branch --> Commit
+    Commit --> Push
+    Push --> PR
+```
+
+---
+
+## Components
+
+### 1. Error Context Capture
+
+**Inputs to collect:**
+
+- Error message and stack trace
+- Failing test name and file (if test failure)
+- Test output (Vitest JSON reporter or stdout)
+- Relevant source files (inferred from stack trace: file paths + line numbers)
+- Request context for runtime errors: path, method, payload keys (sanitized)
+
+**Output:** Structured JSON passed to the agent.
+
+**Location:** `utils/auto-fix/context-capture.js`
+
+### 2. AI Agent
+
+**Responsibilities:**
+
+- Receive error context
+- Call LLM with: error details, relevant file contents, project structure
+- LLM returns: proposed fix (file path, old code, new code) or "cannot fix"
+- Parse and validate the response
+
+**LLM prompt structure:**
+
+- System: "You are an expert debugger. Fix the error. Return only the minimal change."
+- User: Error + stack + file contents + "What change would fix this?"
+- Response format: Structured (JSON) with `{ file, oldSnippet, newSnippet }` or `{ reason: "cannot fix" }`
+
+**Provider:** Pluggable (OpenAI, Anthropic). Config: `AUTO_FIX_LLM_PROVIDER`, `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
+
+**Location:** `utils/auto-fix/agent.js`
+
+### 3. Fix Applicator
+
+**Responsibilities:**
+
+- Take proposed fix (file, oldSnippet, newSnippet)
+- Validate: oldSnippet exists in file (fuzzy match if whitespace differs)
+- Apply: replace oldSnippet with newSnippet
+- Run tests again
+- If tests pass → proceed to PR; if fail → retry with feedback or abort
+
+**Location:** `utils/auto-fix/apply-fix.js`
+
+### 4. GitHub PR Creator
+
+**Responsibilities:**
+
+- Create branch: `auto-fix/error-{hash}` or `auto-fix/{short-description}`
+- Stage changed files, commit with message: "fix: [error summary]"
+- Push to origin
+- Open PR via GitHub API with: title, body (error context + fix summary), base branch
+
+**Requirements:**
+
+- `GITHUB_TOKEN` (PAT with `repo` scope) or `GH_TOKEN`
+- Git remote must be configured (e.g. `origin` → GitHub)
+- Run from a clean or committed working tree (or stash first)
+
+**Location:** `utils/auto-fix/github-pr.js`
+
+### 5. CLI Entry Point
+
+**Command:** `tejas auto-fix` or `npm run test:fix`
+
+**Flow:**
+
+1. Run `vitest run` (or `vitest run --reporter=json` for structured output)
+2. If exit code 0 → done
+3. If exit code !== 0 → capture context from Vitest output
+4. Invoke agent → apply fix → verify
+5. If verified → create PR
+6. Print PR URL or "Fix applied locally" (if no GitHub config)
+
+**Location:** `cli/auto-fix.js` or `scripts/auto-fix.js`; add to `package.json` scripts
+
+---
+
+## File Structure
+
+```
+te.js/
+├── utils/
+│   └── auto-fix/
+│       ├── index.js           # Orchestrator
+│       ├── should-trigger.js  # Error filter (include/exclude/predicate)
+│       ├── context-capture.js # Capture error + test output
+│       ├── agent.js           # LLM call, parse fix
+│       ├── apply-fix.js       # Apply patch, re-run tests
+│       └── github-pr.js       # Branch, commit, push, PR
+├── cli/
+│   └── auto-fix.js            # CLI entry (or bin in package.json)
+└── package.json               # "test:fix": "node cli/auto-fix.js"
+```
+
+---
+
+## Configuration
+
+| Env / Config                           | Purpose                                          |
+| -------------------------------------- | ------------------------------------------------ | ----------- |
+| `AUTO_FIX_ENABLED`                     | Enable feature (default: false)                  |
+| `AUTO_FIX_LLM_PROVIDER`                | `openai`                                         | `anthropic` |
+| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | LLM API key                                      |
+| `GITHUB_TOKEN` / `GH_TOKEN`            | GitHub PAT for PR creation                       |
+| `AUTO_FIX_CREATE_PR`                   | If true, create PR; if false, only apply locally |
+| `AUTO_FIX_BASE_BRANCH`                 | Branch to target (default: current or `main`)    |
+
+---
+
+## Error Filtering: Developer Control
+
+Developers must be able to control **which errors** trigger the auto-fix agent. Not every error should—e.g. 404s, auth failures, or intentional `TejError` throws may be undesirable.
+
+### Filter Options
+
+| Approach             | Config                            | Use Case                                |
+| -------------------- | --------------------------------- | --------------------------------------- |
+| **Include only**     | `autoFix.include`                 | Whitelist: only these trigger the agent |
+| **Exclude**          | `autoFix.exclude`                 | Blacklist: never trigger for these      |
+| **Custom predicate** | `autoFix.shouldFix(err, context)` | Full control via function               |
+
+### Filter Criteria (for include/exclude)
+
+| Criterion           | Example                                | Applies To        |
+| ------------------- | -------------------------------------- | ----------------- |
+| **Error name**      | `TypeError`, `TejError`                | Both modes        |
+| **Status code**     | `500`, `404` (exclude 404)             | Runtime only      |
+| **Message pattern** | Regex: `/ECONNREFUSED/`, `/not found/` | Both              |
+| **File path**       | `server/`**, `!tests/`**               | Both (from stack) |
+| **Route path**      | `/api/`, `!/auth/login`                | Runtime only      |
+| **Test file**       | `**/*.test.js`, `!e2e/`                | Test failure only |
+
+### Configuration Examples
+
+**tejas.config.json:**
+
+```json
+{
+  "autoFix": {
+    "enabled": true,
+    "include": {
+      "errorNames": ["TypeError", "ReferenceError"],
+      "statusCodes": [500],
+      "filePatterns": ["server/**", "utils/**"]
+    },
+    "exclude": {
+      "errorNames": ["TejError"],
+      "statusCodes": [404, 401, 403],
+      "messagePatterns": ["/ECONNREFUSED/", "/timeout/"],
+      "routePatterns": ["/auth/**", "/health"]
+    }
+  }
+}
+```
+
+**Programmatic (custom predicate):**
+
+```javascript
+// index.js or tejas.config.js
+const app = new Tejas({
+  autoFix: {
+    enabled: true,
+    shouldFix: (err, context) => {
+      // Never fix auth or 404
+      if (context.statusCode === 404 || context.statusCode === 401)
+        return false;
+      // Only fix errors in our source, not deps
+      if (!context.stackFiles?.some((f) => f.startsWith("server/")))
+        return false;
+      // Skip "connection refused" - infra issue, not code
+      if (/ECONNREFUSED|ETIMEDOUT/.test(err.message)) return false;
+      return true;
+    },
+  },
+});
+```
+
+### Filter Evaluation Order
+
+1. If `shouldFix` is provided → call it; if it returns `false`, **do not trigger**
+2. If `include` is set → error must match at least one include criterion; else **do not trigger**
+3. If `exclude` is set → error must match none of the exclude criteria; else **do not trigger**
+4. Default (no config): **trigger** for all errors (when auto-fix is enabled)
+
+### Context Passed to `shouldFix`
+
+```javascript
+{
+  error: Error,           // The thrown error
+  errorName: string,      // e.g. "TypeError"
+  message: string,
+  stack: string,
+  stackFiles: string[],   // File paths from stack trace
+  statusCode?: number,    // Runtime: TejError.code or 500
+  path?: string,          // Runtime: request path
+  method?: string,        // Runtime: GET, POST, etc.
+  testFile?: string,     // Test failure: failing test file
+  testName?: string       // Test failure: failing test name
+}
+```
+
+### Location
+
+- Filter logic: `utils/auto-fix/should-trigger.js`
+- Called from: context capture (before invoking agent) and `errorHandler` (before enqueue)
+- Config loading: reuse `loadConfigFile` + `standardizeObj` from [utils/configuration.js](utils/configuration.js)
+
+---
+
+## Safety and Guardrails
+
+1. **Never run in production** — Only when `NODE_ENV=development` or explicit `AUTO_FIX_ENABLED=true`
+2. **Sanitize context** — Redact secrets, tokens, PII from error payloads before sending to LLM
+3. **Human review** — Fix goes to PR, never auto-merge
+4. **Retry limit** — Agent tries at most N times (e.g. 2) before giving up
+5. **Scope** — Only modify files inferred from stack trace; never touch `node_modules`, `.git`, config files (unless error points there)
+
+---
+
+## Runtime Error Integration (Optional, Phase 2)
+
+To trigger from runtime errors in [server/handler.js](server/handler.js):
+
+1. In `errorHandler`, after logging: if `env('AUTO_ERROR_FIX')` and `env('NODE_ENV') === 'development'`, call `shouldTrigger(err, context)`. If true, call `enqueueAutoFix(ammo, err)` (non-blocking)
+2. `enqueueAutoFix` pushes to an in-memory queue or spawns a detached child process
+3. Child process runs the same agent flow with runtime context (path, method, stack, sanitized payload)
+4. Same apply → verify → PR flow
+
+**Caveat:** Runtime errors may be non-deterministic (e.g. race, bad input). Agent might not reproduce the fix. Test failure mode is more reliable.
+
+---
+
+## Dependencies
+
+- **Git operations:** `simple-git` or Node's `child_process` + `git` CLI
+- **GitHub API:** `@octokit/rest` or `fetch` to `https://api.github.com`
+- **LLM:** `openai` SDK or `@anthropic-ai/sdk` (or fetch to provider APIs)
+- **Vitest:** Already present; use `vitest run --reporter=json` for parseable output
+
+---
+
+## Implementation Order
+
+1. **Should-trigger filter** — Config loading, include/exclude/predicate logic (needed by both modes)
+2. **Context capture** — Parse Vitest failure output, extract stack + files
+3. **Agent** — LLM integration, prompt design, structured response parsing
+4. **Apply fix** — Patch application, re-run tests
+5. **GitHub PR** — Branch, commit, push, create PR
+6. **CLI** — Wire it all together, `tejas auto-fix`
+7. **Runtime trigger** (optional) — Enqueue from errorHandler
+
+---
+
+## Example Usage
+
+```bash
+# After a test failure
+$ npm run test:fix
+
+# Output:
+# Tests failed. Running auto-fix agent...
+# Agent proposed fix for server/ammo.js
+# Re-running tests... passed.
+# Created PR: https://github.com/user/te.js/pull/42
+```
+
+```javascript
+// In tejas.config.json (for runtime mode, phase 2)
+{
+  "autoFix": {
+    "enabled": true,
+    "createPr": true,
+    "exclude": {
+      "statusCodes": [404, 401, 403],
+      "routePatterns": ["/auth/**"]
+    }
+  },
+  "auto_fix_llm_provider": "openai"
+}
+```