te.js 2.0.1 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +13 -2
- package/.cursor/plans/ai_native_framework_features_5bb1a20a.plan.md +0 -234
- package/.cursor/plans/auto_error_fix_agent_e68979c5.plan.md +0 -356
- package/.cursor/plans/tejas_framework_test_suite_5e3c6fad.plan.md +0 -168
- package/.prettierignore +0 -31
- package/.prettierrc +0 -5
- package/example/API_OVERVIEW.md +0 -77
- package/example/README.md +0 -155
- package/example/index.js +0 -29
- package/example/middlewares/auth.js +0 -9
- package/example/middlewares/global.midair.js +0 -6
- package/example/openapi.json +0 -390
- package/example/package.json +0 -23
- package/example/services/cache.service.js +0 -25
- package/example/services/user.service.js +0 -42
- package/example/start-redis.js +0 -2
- package/example/targets/cache.target.js +0 -35
- package/example/targets/index.target.js +0 -16
- package/example/targets/users.target.js +0 -60
- package/example/tejas.config.json +0 -22
- package/tests/auto-docs/handler-analyzer.test.js +0 -44
- package/tests/auto-docs/openapi-generator.test.js +0 -103
- package/tests/auto-docs/parse.test.js +0 -63
- package/tests/auto-docs/source-resolver.test.js +0 -58
- package/tests/helpers/index.js +0 -37
- package/tests/helpers/mock-http.js +0 -342
- package/tests/helpers/test-utils.js +0 -446
- package/tests/setup.test.js +0 -148
- package/vitest.config.js +0 -54
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "te.js",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.3",
|
|
4
4
|
"description": "A nodejs framework",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "te.js",
|
|
@@ -25,8 +25,19 @@
|
|
|
25
25
|
},
|
|
26
26
|
"repository": {
|
|
27
27
|
"type": "git",
|
|
28
|
-
"url": "git@github.com
|
|
28
|
+
"url": "git+ssh://git@github.com/hirakchhatbar/te.js.git"
|
|
29
29
|
},
|
|
30
|
+
"files": [
|
|
31
|
+
"te.js",
|
|
32
|
+
"cli",
|
|
33
|
+
"server",
|
|
34
|
+
"database",
|
|
35
|
+
"rate-limit",
|
|
36
|
+
"utils",
|
|
37
|
+
"auto-docs",
|
|
38
|
+
"README.md",
|
|
39
|
+
"docs"
|
|
40
|
+
],
|
|
30
41
|
"dependencies": {
|
|
31
42
|
"ansi-colors": "^4.1.3",
|
|
32
43
|
"filesize": "^10.1.1",
|
|
@@ -1,234 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: AI Native Framework Features
|
|
3
|
-
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.'
|
|
4
|
-
todos: []
|
|
5
|
-
isProject: false
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# AI-Native Framework: Internal AI Features
|
|
9
|
-
|
|
10
|
-
## What "AI Internally" Means
|
|
11
|
-
|
|
12
|
-
**Not:** A framework that lets developers call LLMs (`ammo.llm()`, chat endpoints, etc.)
|
|
13
|
-
|
|
14
|
-
**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.
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## Pain Points a Framework Can Solve by Using AI Internally
|
|
19
|
-
|
|
20
|
-
### 1. Useless Error Messages
|
|
21
|
-
|
|
22
|
-
**Pain:** "Cannot read property 'id' of undefined" — developer spends 20 minutes tracing where it came from.
|
|
23
|
-
|
|
24
|
-
**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.
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
Error: User lookup failed in GET /users/:id
|
|
28
|
-
Cause: ammo.payload.id is undefined when id is "undefined" (string from query)
|
|
29
|
-
Fix: Validate route param before use: if (!ammo.payload.id) ammo.notFound();
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
### 2. Routing is Rigid
|
|
33
|
-
|
|
34
|
-
**Pain:** URLs must match exactly. Typos, alternate phrasings, or semantic equivalents (e.g. "user" vs "account") hit 404.
|
|
35
|
-
|
|
36
|
-
**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.
|
|
37
|
-
|
|
38
|
-
### 3. Documentation is Always Stale
|
|
39
|
-
|
|
40
|
-
**Pain:** Docs drift from code. New routes, changed params, deprecated endpoints—docs don't reflect reality.
|
|
41
|
-
|
|
42
|
-
**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.
|
|
43
|
-
|
|
44
|
-
### 4. Configuration is Guesswork
|
|
45
|
-
|
|
46
|
-
**Pain:** "What rate limit should I use?" "What body size?" Developers copy-paste from examples or guess.
|
|
47
|
-
|
|
48
|
-
**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").
|
|
49
|
-
|
|
50
|
-
### 5. Debugging is Manual Correlation
|
|
51
|
-
|
|
52
|
-
**Pain:** Logs, traces, and errors are scattered. Developer manually correlates "this 500 at 3:42pm" with "this Redis timeout at 3:41pm."
|
|
53
|
-
|
|
54
|
-
**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."
|
|
55
|
-
|
|
56
|
-
### 6. Malformed Input = Generic 400
|
|
57
|
-
|
|
58
|
-
**Pain:** Client sends `{ "name": 123 }` instead of `{ "name": "string" }`. Framework returns "Bad Request" with no guidance.
|
|
59
|
-
|
|
60
|
-
**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 }."
|
|
61
|
-
|
|
62
|
-
### 7. Recovery Requires Humans
|
|
63
|
-
|
|
64
|
-
**Pain:** Rate limit hit, DB timeout, or transient failure → 503. Human must retry or investigate.
|
|
65
|
-
|
|
66
|
-
**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.
|
|
67
|
-
|
|
68
|
-
### 8. Security is Reactive
|
|
69
|
-
|
|
70
|
-
**Pain:** Unusual traffic patterns (DDoS, scraping, abuse) are detected only after damage.
|
|
71
|
-
|
|
72
|
-
**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.
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## Recommended Internal AI Features for Tejas
|
|
77
|
-
|
|
78
|
-
### Tier 1: High Impact, Clear Value
|
|
79
|
-
|
|
80
|
-
1. **Intelligent Error Responses**
|
|
81
|
-
|
|
82
|
-
- When `errorHandler` catches an error, optionally call AI with: stack trace, `ammo` context (path, method, payload keys), recent logs
|
|
83
|
-
- AI returns: human-readable cause, suggested fix, relevant doc link
|
|
84
|
-
- Attach to `LOG_EXCEPTIONS` output or optional `X-Error-Hint` header (dev only)
|
|
85
|
-
- Location: extend [server/handler.js](server/handler.js) `errorHandler`, new `utils/ai-error-analyzer.js`
|
|
86
|
-
|
|
87
|
-
1. **Semantic Routing (Optional Mode)**
|
|
88
|
-
|
|
89
|
-
- When exact `aim()` match fails, optionally use embeddings + intent registry to find best-matching target
|
|
90
|
-
- Each target can declare: `intents: ["get user", "fetch account", "user profile"]`
|
|
91
|
-
- Low confidence → fall through to 404
|
|
92
|
-
- Requires: embedding provider (OpenAI, local model), intent index
|
|
93
|
-
- Location: extend [server/targets/registry.js](server/targets/registry.js), new `server/targets/semantic-router.js`
|
|
94
|
-
|
|
95
|
-
1. **Auto-Generated Documentation**
|
|
96
|
-
|
|
97
|
-
- CLI or startup hook: `tejas docs` or `app.withAutoDocs()`
|
|
98
|
-
- Scans `targetRegistry.getAllEndpoints()`, infers schemas from handler patterns or explicit annotations
|
|
99
|
-
- Outputs OpenAPI spec, or serves `/docs` with interactive UI
|
|
100
|
-
- Optional: AI enhances descriptions from JSDoc
|
|
101
|
-
- Location: new `utils/auto-docs.js`, optional `docs/` route
|
|
102
|
-
|
|
103
|
-
### Tier 2: Developer Experience
|
|
104
|
-
|
|
105
|
-
1. **Natural Language Config**
|
|
106
|
-
|
|
107
|
-
- `app.configure("I need strict rate limiting for 500 req/min and 5MB body limit")`
|
|
108
|
-
- AI parses intent, returns config object; user can approve or edit
|
|
109
|
-
- Or: interactive `tejas init` that asks in plain language and generates `tejas.config.json`
|
|
110
|
-
- Location: new `utils/ai-config.js`, CLI
|
|
111
|
-
|
|
112
|
-
1. **Smart Validation Errors**
|
|
113
|
-
|
|
114
|
-
- When body-parser or validation fails, AI suggests corrections: "Expected 'email' as string; received number. Did you mean to send a string?"
|
|
115
|
-
- Integrates with existing body parsing in [server/ammo/body-parser.js](server/ammo/body-parser.js)
|
|
116
|
-
- Location: extend body-parser error path, new `utils/ai-validation-hint.js`
|
|
117
|
-
|
|
118
|
-
1. **Root Cause Analysis (Observability)**
|
|
119
|
-
|
|
120
|
-
- When `LOG_EXCEPTIONS` is on, batch recent logs and send to AI for correlation
|
|
121
|
-
- "Last 5 errors: Redis timeout, Redis timeout, DB connection refused. Likely cause: database connectivity. Check Redis URL."
|
|
122
|
-
- Can run as background job or on-demand via admin endpoint
|
|
123
|
-
- Location: new `utils/ai-rca.js`, optional admin target
|
|
124
|
-
|
|
125
|
-
### Tier 3: Advanced / Later
|
|
126
|
-
|
|
127
|
-
1. **Auto-Remediation**
|
|
128
|
-
|
|
129
|
-
- Configurable: on 503/timeout, framework retries N times with backoff before returning
|
|
130
|
-
- Or: fallback to cached/stale response when available
|
|
131
|
-
- Requires policy: "when X, do Y"
|
|
132
|
-
- Location: middleware or handler wrapper
|
|
133
|
-
|
|
134
|
-
1. **Anomaly Detection**
|
|
135
|
-
|
|
136
|
-
- Framework tracks request patterns; ML model (or rules) flags anomalies
|
|
137
|
-
- Triggers: alert, stricter rate limit, CAPTCHA challenge
|
|
138
|
-
- Heavier dependency; may be plugin
|
|
139
|
-
- Location: new `middlewares/anomaly-detector.js` (optional)
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## Architecture: AI as Internal Service
|
|
144
|
-
|
|
145
|
-
```mermaid
|
|
146
|
-
flowchart TB
|
|
147
|
-
subgraph Request [Normal Request Flow]
|
|
148
|
-
Req[HTTP Request]
|
|
149
|
-
Handler[handler.js]
|
|
150
|
-
Ammo[Ammo]
|
|
151
|
-
Registry[TargetRegistry]
|
|
152
|
-
end
|
|
153
|
-
|
|
154
|
-
subgraph AI [AI Internal Services]
|
|
155
|
-
ErrorAnalyzer[Error Analyzer]
|
|
156
|
-
SemanticRouter[Semantic Router]
|
|
157
|
-
ConfigGen[Config Generator]
|
|
158
|
-
DocGen[Doc Generator]
|
|
159
|
-
RCA[Root Cause Analysis]
|
|
160
|
-
end
|
|
161
|
-
|
|
162
|
-
Req --> Registry
|
|
163
|
-
Registry -->|"exact match"| Handler
|
|
164
|
-
Registry -->|"no match"| SemanticRouter
|
|
165
|
-
SemanticRouter -->|"high confidence"| Handler
|
|
166
|
-
SemanticRouter -->|"low confidence"| NotFound[404]
|
|
167
|
-
|
|
168
|
-
Handler --> Ammo
|
|
169
|
-
Ammo --> Response[Response]
|
|
170
|
-
|
|
171
|
-
Handler -->|"throws"| ErrorAnalyzer
|
|
172
|
-
ErrorAnalyzer -->|"enriched error"| Logs[Logs / X-Error-Hint]
|
|
173
|
-
|
|
174
|
-
subgraph Dev [Dev / CLI]
|
|
175
|
-
Init[tejas init]
|
|
176
|
-
Docs[tejas docs]
|
|
177
|
-
Init --> ConfigGen
|
|
178
|
-
Docs --> DocGen
|
|
179
|
-
end
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
**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.
|
|
183
|
-
|
|
184
|
-
---
|
|
185
|
-
|
|
186
|
-
## Implementation Considerations
|
|
187
|
-
|
|
188
|
-
### When to Call AI
|
|
189
|
-
|
|
190
|
-
- **Synchronous (blocking):** Error analysis, validation hints — adds latency. Make it opt-in, async where possible (e.g. log enrichment in background).
|
|
191
|
-
- **Asynchronous (non-blocking):** Doc generation, config suggestion, RCA — run on CLI or cron, not per-request.
|
|
192
|
-
|
|
193
|
-
### Cost and Latency
|
|
194
|
-
|
|
195
|
-
- Every AI call costs money and adds latency. Features should be:
|
|
196
|
-
- **Dev-only** where possible (error hints, config gen)
|
|
197
|
-
- **Cached** (semantic route index, intent embeddings)
|
|
198
|
-
- **Batchable** (RCA over last N errors, not per error)
|
|
199
|
-
|
|
200
|
-
### Provider Abstraction
|
|
201
|
-
|
|
202
|
-
- Framework needs one AI provider interface: `analyzeError(context)`, `matchIntent(query, intents)`, `suggestConfig(nl)`, etc.
|
|
203
|
-
- Pluggable: OpenAI, Anthropic, local Ollama, or disabled
|
|
204
|
-
- Config: `app.withAI({ provider: 'openai', apiKey: env('OPENAI_API_KEY'), features: ['errorAnalysis', 'semanticRouting'] })`
|
|
205
|
-
|
|
206
|
-
### Privacy and Security
|
|
207
|
-
|
|
208
|
-
- Never send sensitive data (tokens, passwords, PII) to AI without user consent
|
|
209
|
-
- Error analysis: sanitize stack traces, redact payload values
|
|
210
|
-
- Semantic routing: only path/headers, not body
|
|
211
|
-
|
|
212
|
-
---
|
|
213
|
-
|
|
214
|
-
## Summary: Pain Points Solved by Internal AI
|
|
215
|
-
|
|
216
|
-
| Pain Point | Internal AI Feature | User-Visible Benefit |
|
|
217
|
-
| ------------------------- | -------------------------- | ------------------------------------ |
|
|
218
|
-
| Useless errors | Intelligent error analysis | Plain-language cause + suggested fix |
|
|
219
|
-
| Rigid routing | Semantic routing | Intent-based matching, fewer 404s |
|
|
220
|
-
| Stale docs | Auto-generated docs | Always-in-sync OpenAPI, `/docs` |
|
|
221
|
-
| Config guesswork | Natural language config | "I need X" → suggested config |
|
|
222
|
-
| Manual debugging | Root cause analysis | Correlated insights from logs |
|
|
223
|
-
| Generic validation errors | Smart validation hints | "Did you mean...?" suggestions |
|
|
224
|
-
| Human-only recovery | Auto-remediation | Retries, fallbacks, degraded mode |
|
|
225
|
-
| Reactive security | Anomaly detection | Proactive abuse detection |
|
|
226
|
-
|
|
227
|
-
---
|
|
228
|
-
|
|
229
|
-
## Next Steps (When Implementing)
|
|
230
|
-
|
|
231
|
-
1. **Error analysis** — highest impact, dev-only, no user code changes. Add `withAI({ features: ['errorAnalysis'] })`.
|
|
232
|
-
2. **Auto-docs** — no AI required for v1 (static from registry); add AI-enhanced descriptions later.
|
|
233
|
-
3. **Semantic routing** — requires intent registry and embeddings; good for apps with many similar routes.
|
|
234
|
-
4. **Natural language config** — CLI-only, great for `tejas init` experience.
|
|
@@ -1,356 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: Auto Error Fix Agent
|
|
3
|
-
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.
|
|
4
|
-
todos: []
|
|
5
|
-
isProject: false
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Auto Error Fix Agent Plan
|
|
9
|
-
|
|
10
|
-
## Overview
|
|
11
|
-
|
|
12
|
-
When an error occurs—either a **test failure** or a **runtime exception**—an AI agent is triggered to:
|
|
13
|
-
|
|
14
|
-
1. Analyze the error (stack trace, context, failing code)
|
|
15
|
-
2. Propose and apply a fix
|
|
16
|
-
3. Create a branch, commit, push, and open a PR on GitHub
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## Trigger Modes
|
|
21
|
-
|
|
22
|
-
| Mode | When | Use Case |
|
|
23
|
-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
|
|
24
|
-
| **Test failure** | `npm run test:fix` or `tejas auto-fix` runs tests; on failure, agent triggers | Local dev, CI pipeline |
|
|
25
|
-
| **Runtime exception** | Error caught in [server/handler.js](server/handler.js) `errorHandler`; if `AUTO_ERROR_FIX` enabled, enqueue agent (async) | Dev server only |
|
|
26
|
-
|
|
27
|
-
**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.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## Architecture
|
|
32
|
-
|
|
33
|
-
```mermaid
|
|
34
|
-
flowchart TB
|
|
35
|
-
subgraph Trigger [Trigger]
|
|
36
|
-
Tests[Vitest Run]
|
|
37
|
-
Runtime[Runtime Error]
|
|
38
|
-
end
|
|
39
|
-
|
|
40
|
-
subgraph Agent [AI Agent]
|
|
41
|
-
Capture[Capture Context]
|
|
42
|
-
Analyze[Analyze Error]
|
|
43
|
-
Propose[Propose Fix]
|
|
44
|
-
Apply[Apply Changes]
|
|
45
|
-
Verify[Run Tests Again]
|
|
46
|
-
end
|
|
47
|
-
|
|
48
|
-
subgraph GitHub [GitHub]
|
|
49
|
-
Branch[Create Branch]
|
|
50
|
-
Commit[Commit]
|
|
51
|
-
Push[Push]
|
|
52
|
-
PR[Open PR]
|
|
53
|
-
end
|
|
54
|
-
|
|
55
|
-
Tests -->|"fail"| Capture
|
|
56
|
-
Runtime -->|"AUTO_ERROR_FIX"| Capture
|
|
57
|
-
|
|
58
|
-
Capture --> ShouldTrigger{shouldTrigger?}
|
|
59
|
-
ShouldTrigger -->|"no"| Skip[Skip - log only]
|
|
60
|
-
ShouldTrigger -->|"yes"| Analyze
|
|
61
|
-
Analyze --> Propose
|
|
62
|
-
Propose --> Apply
|
|
63
|
-
Apply --> Verify
|
|
64
|
-
Verify -->|"pass"| Branch
|
|
65
|
-
Verify -->|"fail"| Log[Log / Notify]
|
|
66
|
-
Branch --> Commit
|
|
67
|
-
Commit --> Push
|
|
68
|
-
Push --> PR
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## Components
|
|
74
|
-
|
|
75
|
-
### 1. Error Context Capture
|
|
76
|
-
|
|
77
|
-
**Inputs to collect:**
|
|
78
|
-
|
|
79
|
-
- Error message and stack trace
|
|
80
|
-
- Failing test name and file (if test failure)
|
|
81
|
-
- Test output (Vitest JSON reporter or stdout)
|
|
82
|
-
- Relevant source files (inferred from stack trace: file paths + line numbers)
|
|
83
|
-
- Request context for runtime errors: path, method, payload keys (sanitized)
|
|
84
|
-
|
|
85
|
-
**Output:** Structured JSON passed to the agent.
|
|
86
|
-
|
|
87
|
-
**Location:** `utils/auto-fix/context-capture.js`
|
|
88
|
-
|
|
89
|
-
### 2. AI Agent
|
|
90
|
-
|
|
91
|
-
**Responsibilities:**
|
|
92
|
-
|
|
93
|
-
- Receive error context
|
|
94
|
-
- Call LLM with: error details, relevant file contents, project structure
|
|
95
|
-
- LLM returns: proposed fix (file path, old code, new code) or "cannot fix"
|
|
96
|
-
- Parse and validate the response
|
|
97
|
-
|
|
98
|
-
**LLM prompt structure:**
|
|
99
|
-
|
|
100
|
-
- System: "You are an expert debugger. Fix the error. Return only the minimal change."
|
|
101
|
-
- User: Error + stack + file contents + "What change would fix this?"
|
|
102
|
-
- Response format: Structured (JSON) with `{ file, oldSnippet, newSnippet }` or `{ reason: "cannot fix" }`
|
|
103
|
-
|
|
104
|
-
**Provider:** Pluggable (OpenAI, Anthropic). Config: `AUTO_FIX_LLM_PROVIDER`, `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
|
|
105
|
-
|
|
106
|
-
**Location:** `utils/auto-fix/agent.js`
|
|
107
|
-
|
|
108
|
-
### 3. Fix Applicator
|
|
109
|
-
|
|
110
|
-
**Responsibilities:**
|
|
111
|
-
|
|
112
|
-
- Take proposed fix (file, oldSnippet, newSnippet)
|
|
113
|
-
- Validate: oldSnippet exists in file (fuzzy match if whitespace differs)
|
|
114
|
-
- Apply: replace oldSnippet with newSnippet
|
|
115
|
-
- Run tests again
|
|
116
|
-
- If tests pass → proceed to PR; if fail → retry with feedback or abort
|
|
117
|
-
|
|
118
|
-
**Location:** `utils/auto-fix/apply-fix.js`
|
|
119
|
-
|
|
120
|
-
### 4. GitHub PR Creator
|
|
121
|
-
|
|
122
|
-
**Responsibilities:**
|
|
123
|
-
|
|
124
|
-
- Create branch: `auto-fix/error-{hash}` or `auto-fix/{short-description}`
|
|
125
|
-
- Stage changed files, commit with message: "fix: [error summary]"
|
|
126
|
-
- Push to origin
|
|
127
|
-
- Open PR via GitHub API with: title, body (error context + fix summary), base branch
|
|
128
|
-
|
|
129
|
-
**Requirements:**
|
|
130
|
-
|
|
131
|
-
- `GITHUB_TOKEN` (PAT with `repo` scope) or `GH_TOKEN`
|
|
132
|
-
- Git remote must be configured (e.g. `origin` → GitHub)
|
|
133
|
-
- Run from a clean or committed working tree (or stash first)
|
|
134
|
-
|
|
135
|
-
**Location:** `utils/auto-fix/github-pr.js`
|
|
136
|
-
|
|
137
|
-
### 5. CLI Entry Point
|
|
138
|
-
|
|
139
|
-
**Command:** `tejas auto-fix` or `npm run test:fix`
|
|
140
|
-
|
|
141
|
-
**Flow:**
|
|
142
|
-
|
|
143
|
-
1. Run `vitest run` (or `vitest run --reporter=json` for structured output)
|
|
144
|
-
2. If exit code 0 → done
|
|
145
|
-
3. If exit code !== 0 → capture context from Vitest output
|
|
146
|
-
4. Invoke agent → apply fix → verify
|
|
147
|
-
5. If verified → create PR
|
|
148
|
-
6. Print PR URL or "Fix applied locally" (if no GitHub config)
|
|
149
|
-
|
|
150
|
-
**Location:** `cli/auto-fix.js` or `scripts/auto-fix.js`; add to `package.json` scripts
|
|
151
|
-
|
|
152
|
-
---
|
|
153
|
-
|
|
154
|
-
## File Structure
|
|
155
|
-
|
|
156
|
-
```
|
|
157
|
-
te.js/
|
|
158
|
-
├── utils/
|
|
159
|
-
│ └── auto-fix/
|
|
160
|
-
│ ├── index.js # Orchestrator
|
|
161
|
-
│ ├── should-trigger.js # Error filter (include/exclude/predicate)
|
|
162
|
-
│ ├── context-capture.js # Capture error + test output
|
|
163
|
-
│ ├── agent.js # LLM call, parse fix
|
|
164
|
-
│ ├── apply-fix.js # Apply patch, re-run tests
|
|
165
|
-
│ └── github-pr.js # Branch, commit, push, PR
|
|
166
|
-
├── cli/
|
|
167
|
-
│ └── auto-fix.js # CLI entry (or bin in package.json)
|
|
168
|
-
└── package.json # "test:fix": "node cli/auto-fix.js"
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
---
|
|
172
|
-
|
|
173
|
-
## Configuration
|
|
174
|
-
|
|
175
|
-
| Env / Config | Purpose |
|
|
176
|
-
| -------------------------------------- | ------------------------------------------------ | ----------- |
|
|
177
|
-
| `AUTO_FIX_ENABLED` | Enable feature (default: false) |
|
|
178
|
-
| `AUTO_FIX_LLM_PROVIDER` | `openai` | `anthropic` |
|
|
179
|
-
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | LLM API key |
|
|
180
|
-
| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub PAT for PR creation |
|
|
181
|
-
| `AUTO_FIX_CREATE_PR` | If true, create PR; if false, only apply locally |
|
|
182
|
-
| `AUTO_FIX_BASE_BRANCH` | Branch to target (default: current or `main`) |
|
|
183
|
-
|
|
184
|
-
---
|
|
185
|
-
|
|
186
|
-
## Error Filtering: Developer Control
|
|
187
|
-
|
|
188
|
-
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.
|
|
189
|
-
|
|
190
|
-
### Filter Options
|
|
191
|
-
|
|
192
|
-
| Approach | Config | Use Case |
|
|
193
|
-
| -------------------- | --------------------------------- | --------------------------------------- |
|
|
194
|
-
| **Include only** | `autoFix.include` | Whitelist: only these trigger the agent |
|
|
195
|
-
| **Exclude** | `autoFix.exclude` | Blacklist: never trigger for these |
|
|
196
|
-
| **Custom predicate** | `autoFix.shouldFix(err, context)` | Full control via function |
|
|
197
|
-
|
|
198
|
-
### Filter Criteria (for include/exclude)
|
|
199
|
-
|
|
200
|
-
| Criterion | Example | Applies To |
|
|
201
|
-
| ------------------- | -------------------------------------- | ----------------- |
|
|
202
|
-
| **Error name** | `TypeError`, `TejError` | Both modes |
|
|
203
|
-
| **Status code** | `500`, `404` (exclude 404) | Runtime only |
|
|
204
|
-
| **Message pattern** | Regex: `/ECONNREFUSED/`, `/not found/` | Both |
|
|
205
|
-
| **File path** | `server/`**, `!tests/`** | Both (from stack) |
|
|
206
|
-
| **Route path** | `/api/`, `!/auth/login` | Runtime only |
|
|
207
|
-
| **Test file** | `**/*.test.js`, `!e2e/` | Test failure only |
|
|
208
|
-
|
|
209
|
-
### Configuration Examples
|
|
210
|
-
|
|
211
|
-
**tejas.config.json:**
|
|
212
|
-
|
|
213
|
-
```json
|
|
214
|
-
{
|
|
215
|
-
"autoFix": {
|
|
216
|
-
"enabled": true,
|
|
217
|
-
"include": {
|
|
218
|
-
"errorNames": ["TypeError", "ReferenceError"],
|
|
219
|
-
"statusCodes": [500],
|
|
220
|
-
"filePatterns": ["server/**", "utils/**"]
|
|
221
|
-
},
|
|
222
|
-
"exclude": {
|
|
223
|
-
"errorNames": ["TejError"],
|
|
224
|
-
"statusCodes": [404, 401, 403],
|
|
225
|
-
"messagePatterns": ["/ECONNREFUSED/", "/timeout/"],
|
|
226
|
-
"routePatterns": ["/auth/**", "/health"]
|
|
227
|
-
}
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
**Programmatic (custom predicate):**
|
|
233
|
-
|
|
234
|
-
```javascript
|
|
235
|
-
// index.js or tejas.config.js
|
|
236
|
-
const app = new Tejas({
|
|
237
|
-
autoFix: {
|
|
238
|
-
enabled: true,
|
|
239
|
-
shouldFix: (err, context) => {
|
|
240
|
-
// Never fix auth or 404
|
|
241
|
-
if (context.statusCode === 404 || context.statusCode === 401)
|
|
242
|
-
return false;
|
|
243
|
-
// Only fix errors in our source, not deps
|
|
244
|
-
if (!context.stackFiles?.some((f) => f.startsWith("server/")))
|
|
245
|
-
return false;
|
|
246
|
-
// Skip "connection refused" - infra issue, not code
|
|
247
|
-
if (/ECONNREFUSED|ETIMEDOUT/.test(err.message)) return false;
|
|
248
|
-
return true;
|
|
249
|
-
},
|
|
250
|
-
},
|
|
251
|
-
});
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
### Filter Evaluation Order
|
|
255
|
-
|
|
256
|
-
1. If `shouldFix` is provided → call it; if it returns `false`, **do not trigger**
|
|
257
|
-
2. If `include` is set → error must match at least one include criterion; else **do not trigger**
|
|
258
|
-
3. If `exclude` is set → error must match none of the exclude criteria; else **do not trigger**
|
|
259
|
-
4. Default (no config): **trigger** for all errors (when auto-fix is enabled)
|
|
260
|
-
|
|
261
|
-
### Context Passed to `shouldFix`
|
|
262
|
-
|
|
263
|
-
```javascript
|
|
264
|
-
{
|
|
265
|
-
error: Error, // The thrown error
|
|
266
|
-
errorName: string, // e.g. "TypeError"
|
|
267
|
-
message: string,
|
|
268
|
-
stack: string,
|
|
269
|
-
stackFiles: string[], // File paths from stack trace
|
|
270
|
-
statusCode?: number, // Runtime: TejError.code or 500
|
|
271
|
-
path?: string, // Runtime: request path
|
|
272
|
-
method?: string, // Runtime: GET, POST, etc.
|
|
273
|
-
testFile?: string, // Test failure: failing test file
|
|
274
|
-
testName?: string // Test failure: failing test name
|
|
275
|
-
}
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
### Location
|
|
279
|
-
|
|
280
|
-
- Filter logic: `utils/auto-fix/should-trigger.js`
|
|
281
|
-
- Called from: context capture (before invoking agent) and `errorHandler` (before enqueue)
|
|
282
|
-
- Config loading: reuse `loadConfigFile` + `standardizeObj` from [utils/configuration.js](utils/configuration.js)
|
|
283
|
-
|
|
284
|
-
---
|
|
285
|
-
|
|
286
|
-
## Safety and Guardrails
|
|
287
|
-
|
|
288
|
-
1. **Never run in production** — Only when `NODE_ENV=development` or explicit `AUTO_FIX_ENABLED=true`
|
|
289
|
-
2. **Sanitize context** — Redact secrets, tokens, PII from error payloads before sending to LLM
|
|
290
|
-
3. **Human review** — Fix goes to PR, never auto-merge
|
|
291
|
-
4. **Retry limit** — Agent tries at most N times (e.g. 2) before giving up
|
|
292
|
-
5. **Scope** — Only modify files inferred from stack trace; never touch `node_modules`, `.git`, config files (unless error points there)
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## Runtime Error Integration (Optional, Phase 2)
|
|
297
|
-
|
|
298
|
-
To trigger from runtime errors in [server/handler.js](server/handler.js):
|
|
299
|
-
|
|
300
|
-
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)
|
|
301
|
-
2. `enqueueAutoFix` pushes to an in-memory queue or spawns a detached child process
|
|
302
|
-
3. Child process runs the same agent flow with runtime context (path, method, stack, sanitized payload)
|
|
303
|
-
4. Same apply → verify → PR flow
|
|
304
|
-
|
|
305
|
-
**Caveat:** Runtime errors may be non-deterministic (e.g. race, bad input). Agent might not reproduce the fix. Test failure mode is more reliable.
|
|
306
|
-
|
|
307
|
-
---
|
|
308
|
-
|
|
309
|
-
## Dependencies
|
|
310
|
-
|
|
311
|
-
- **Git operations:** `simple-git` or Node's `child_process` + `git` CLI
|
|
312
|
-
- **GitHub API:** `@octokit/rest` or `fetch` to `https://api.github.com`
|
|
313
|
-
- **LLM:** `openai` SDK or `@anthropic-ai/sdk` (or fetch to provider APIs)
|
|
314
|
-
- **Vitest:** Already present; use `vitest run --reporter=json` for parseable output
|
|
315
|
-
|
|
316
|
-
---
|
|
317
|
-
|
|
318
|
-
## Implementation Order
|
|
319
|
-
|
|
320
|
-
1. **Should-trigger filter** — Config loading, include/exclude/predicate logic (needed by both modes)
|
|
321
|
-
2. **Context capture** — Parse Vitest failure output, extract stack + files
|
|
322
|
-
3. **Agent** — LLM integration, prompt design, structured response parsing
|
|
323
|
-
4. **Apply fix** — Patch application, re-run tests
|
|
324
|
-
5. **GitHub PR** — Branch, commit, push, create PR
|
|
325
|
-
6. **CLI** — Wire it all together, `tejas auto-fix`
|
|
326
|
-
7. **Runtime trigger** (optional) — Enqueue from errorHandler
|
|
327
|
-
|
|
328
|
-
---
|
|
329
|
-
|
|
330
|
-
## Example Usage
|
|
331
|
-
|
|
332
|
-
```bash
|
|
333
|
-
# After a test failure
|
|
334
|
-
$ npm run test:fix
|
|
335
|
-
|
|
336
|
-
# Output:
|
|
337
|
-
# Tests failed. Running auto-fix agent...
|
|
338
|
-
# Agent proposed fix for server/ammo.js
|
|
339
|
-
# Re-running tests... passed.
|
|
340
|
-
# Created PR: https://github.com/user/te.js/pull/42
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
```javascript
|
|
344
|
-
// In tejas.config.json (for runtime mode, phase 2)
|
|
345
|
-
{
|
|
346
|
-
"autoFix": {
|
|
347
|
-
"enabled": true,
|
|
348
|
-
"createPr": true,
|
|
349
|
-
"exclude": {
|
|
350
|
-
"statusCodes": [404, 401, 403],
|
|
351
|
-
"routePatterns": ["/auth/**"]
|
|
352
|
-
}
|
|
353
|
-
},
|
|
354
|
-
"auto_fix_llm_provider": "openai"
|
|
355
|
-
}
|
|
356
|
-
```
|