tribunal-kit 4.3.0 → 4.3.1
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/.agent/scripts/case_law_manager.js +684 -684
- package/.agent/scripts/graph_builder.js +199 -0
- package/.agent/scripts/graph_zoom.js +154 -0
- package/.agent/skills/agent-organizer/SKILL.md +9 -1
- package/.agent/skills/agentic-patterns/SKILL.md +9 -1
- package/.agent/skills/ai-prompt-injection-defense/SKILL.md +9 -1
- package/.agent/skills/api-patterns/SKILL.md +206 -198
- package/.agent/skills/api-security-auditor/SKILL.md +9 -1
- package/.agent/skills/app-builder/SKILL.md +9 -1
- package/.agent/skills/app-builder/templates/SKILL.md +77 -69
- package/.agent/skills/appflow-wireframe/SKILL.md +9 -1
- package/.agent/skills/architecture/SKILL.md +9 -1
- package/.agent/skills/authentication-best-practices/SKILL.md +9 -1
- package/.agent/skills/bash-linux/SKILL.md +9 -1
- package/.agent/skills/behavioral-modes/SKILL.md +9 -1
- package/.agent/skills/brainstorming/SKILL.md +9 -1
- package/.agent/skills/building-native-ui/SKILL.md +9 -1
- package/.agent/skills/clean-code/SKILL.md +9 -1
- package/.agent/skills/code-review-checklist/SKILL.md +9 -1
- package/.agent/skills/config-validator/SKILL.md +9 -1
- package/.agent/skills/csharp-developer/SKILL.md +9 -1
- package/.agent/skills/data-validation-schemas/SKILL.md +287 -279
- package/.agent/skills/database-design/SKILL.md +199 -191
- package/.agent/skills/deployment-procedures/SKILL.md +9 -1
- package/.agent/skills/devops-engineer/SKILL.md +9 -1
- package/.agent/skills/devops-incident-responder/SKILL.md +9 -1
- package/.agent/skills/documentation-templates/SKILL.md +9 -1
- package/.agent/skills/edge-computing/SKILL.md +9 -1
- package/.agent/skills/error-resilience/SKILL.md +387 -379
- package/.agent/skills/extract-design-system/SKILL.md +9 -1
- package/.agent/skills/framer-motion-expert/SKILL.md +203 -195
- package/.agent/skills/frontend-design/SKILL.md +160 -152
- package/.agent/skills/game-design-expert/SKILL.md +9 -1
- package/.agent/skills/game-engineering-expert/SKILL.md +9 -1
- package/.agent/skills/geo-fundamentals/SKILL.md +9 -1
- package/.agent/skills/github-operations/SKILL.md +9 -1
- package/.agent/skills/gsap-core/SKILL.md +54 -46
- package/.agent/skills/gsap-frameworks/SKILL.md +54 -46
- package/.agent/skills/gsap-performance/SKILL.md +54 -46
- package/.agent/skills/gsap-plugins/SKILL.md +54 -46
- package/.agent/skills/gsap-react/SKILL.md +54 -46
- package/.agent/skills/gsap-scrolltrigger/SKILL.md +54 -46
- package/.agent/skills/gsap-timeline/SKILL.md +54 -46
- package/.agent/skills/gsap-utils/SKILL.md +54 -46
- package/.agent/skills/i18n-localization/SKILL.md +9 -1
- package/.agent/skills/intelligent-routing/SKILL.md +38 -30
- package/.agent/skills/knowledge-graph/SKILL.md +36 -0
- package/.agent/skills/lint-and-validate/SKILL.md +9 -1
- package/.agent/skills/llm-engineering/SKILL.md +9 -1
- package/.agent/skills/local-first/SKILL.md +9 -1
- package/.agent/skills/mcp-builder/SKILL.md +9 -1
- package/.agent/skills/mobile-design/SKILL.md +222 -214
- package/.agent/skills/monorepo-management/SKILL.md +293 -285
- package/.agent/skills/motion-engineering/SKILL.md +193 -185
- package/.agent/skills/nextjs-react-expert/SKILL.md +193 -185
- package/.agent/skills/nodejs-best-practices/SKILL.md +9 -1
- package/.agent/skills/observability/SKILL.md +9 -1
- package/.agent/skills/parallel-agents/SKILL.md +9 -1
- package/.agent/skills/performance-profiling/SKILL.md +9 -1
- package/.agent/skills/plan-writing/SKILL.md +9 -1
- package/.agent/skills/platform-engineer/SKILL.md +9 -1
- package/.agent/skills/playwright-best-practices/SKILL.md +9 -1
- package/.agent/skills/powershell-windows/SKILL.md +9 -1
- package/.agent/skills/project-idioms/SKILL.md +9 -1
- package/.agent/skills/python-patterns/SKILL.md +9 -1
- package/.agent/skills/python-pro/SKILL.md +282 -274
- package/.agent/skills/react-specialist/SKILL.md +236 -228
- package/.agent/skills/readme-builder/SKILL.md +9 -1
- package/.agent/skills/realtime-patterns/SKILL.md +9 -1
- package/.agent/skills/red-team-tactics/SKILL.md +9 -1
- package/.agent/skills/rust-pro/SKILL.md +9 -1
- package/.agent/skills/seo-fundamentals/SKILL.md +9 -1
- package/.agent/skills/server-management/SKILL.md +9 -1
- package/.agent/skills/shadcn-ui-expert/SKILL.md +9 -1
- package/.agent/skills/skill-creator/SKILL.md +9 -1
- package/.agent/skills/sql-pro/SKILL.md +9 -1
- package/.agent/skills/supabase-postgres-best-practices/SKILL.md +9 -1
- package/.agent/skills/swiftui-expert/SKILL.md +9 -1
- package/.agent/skills/systematic-debugging/SKILL.md +9 -1
- package/.agent/skills/tailwind-patterns/SKILL.md +9 -1
- package/.agent/skills/tdd-workflow/SKILL.md +9 -1
- package/.agent/skills/test-result-analyzer/SKILL.md +9 -1
- package/.agent/skills/testing-patterns/SKILL.md +9 -1
- package/.agent/skills/trend-researcher/SKILL.md +9 -1
- package/.agent/skills/typescript-advanced/SKILL.md +294 -286
- package/.agent/skills/ui-ux-pro-max/SKILL.md +9 -1
- package/.agent/skills/ui-ux-researcher/SKILL.md +9 -1
- package/.agent/skills/vue-expert/SKILL.md +234 -226
- package/.agent/skills/vulnerability-scanner/SKILL.md +9 -1
- package/.agent/skills/web-accessibility-auditor/SKILL.md +9 -1
- package/.agent/skills/web-design-guidelines/SKILL.md +9 -1
- package/.agent/skills/webapp-testing/SKILL.md +9 -1
- package/.agent/skills/whimsy-injector/SKILL.md +9 -1
- package/.agent/skills/workflow-optimizer/SKILL.md +9 -1
- package/README.md +242 -242
- package/bin/tribunal-kit.js +30 -22
- package/package.json +81 -80
- package/scripts/validate-payload.js +73 -0
|
@@ -1,200 +1,200 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: api-patterns
|
|
3
|
-
description: API design mastery. REST, GraphQL, tRPC, and gRPC selection. Request/response design, pagination (cursor/offset), filtering, versioning, rate limiting, error formats (RFC 9457), authentication (JWT/OAuth2/API keys), idempotency, file uploads, webhooks, and OpenAPI documentation. Use when designing APIs, choosing protocols, or implementing API standards.
|
|
4
|
-
allowed-tools: Read, Write, Edit, Glob, Grep
|
|
5
|
-
version: 3.1.0
|
|
6
|
-
last-updated: 2026-04-07
|
|
7
|
-
applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
# API Patterns — Design & Protocol Mastery
|
|
11
|
-
|
|
12
|
-
## Hallucination Traps (Read First)
|
|
13
|
-
- ❌ JWT in URL query params → ✅ `Authorization: Bearer` header only. Query params get logged in server access logs.
|
|
14
|
-
- ❌ Assuming JWT is encrypted → ✅ JWT is base64-encoded (NOT encrypted). Anyone can decode it. Never put secrets/PII in the payload.
|
|
15
|
-
- ❌ Offset pagination on large tables → ✅ `OFFSET 100000` scans and discards 100K rows. Use cursor pagination for tables > 10K rows.
|
|
16
|
-
- ❌ Verbs in REST URLs (`/api/getUsers`) → ✅ Nouns only (`GET /api/users`). HTTP method IS the verb.
|
|
17
|
-
- ❌ `POST` is idempotent → ✅ `POST` is NOT idempotent — requires `Idempotency-Key` header for safe retries.
|
|
18
|
-
- ❌ GraphQL has no security risks → ✅ Deeply nested queries are a DoS vector. Set max depth, query cost limits. Disable introspection in production.
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## Protocol Selection Matrix
|
|
23
|
-
|
|
24
|
-
| Protocol | Use When |
|
|
25
|
-
|----------|----------|
|
|
26
|
-
| **REST** | Public APIs, 3rd-party consumers, standard CRUD, HTTP caching |
|
|
27
|
-
| **GraphQL** | Complex nested data, multiple clients, flexible queries, mobile bandwidth sensitivity |
|
|
28
|
-
| **tRPC** | Full-stack TypeScript (Next.js monorepo), shared types, no codegen |
|
|
29
|
-
| **gRPC** | Internal microservices, high-throughput, streaming, binary protocol |
|
|
30
|
-
| **WebSocket** | Bidirectional real-time (chat, gaming, live collaboration) |
|
|
31
|
-
| **SSE** | Server-to-client streaming only (AI token streaming, live feeds) |
|
|
32
|
-
|
|
33
|
-
---
|
|
34
|
-
|
|
35
|
-
## REST Design
|
|
36
|
-
|
|
37
|
-
### URL Conventions
|
|
38
|
-
```
|
|
39
|
-
✅ GET /api/v1/users list users
|
|
40
|
-
✅ GET /api/v1/users/123 get user by ID
|
|
41
|
-
✅ POST /api/v1/users create user
|
|
42
|
-
✅ PATCH /api/v1/users/123 partial update
|
|
43
|
-
✅ DELETE /api/v1/users/123 delete user
|
|
44
|
-
✅ GET /api/v1/users/123/posts nested resource
|
|
45
|
-
|
|
46
|
-
❌ /api/getUsers /api/createUser /api/user (singular) /api/Users (uppercase)
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
### HTTP Status Codes
|
|
50
|
-
```
|
|
51
|
-
200 OK → GET / PUT / PATCH success
|
|
52
|
-
201 Created → POST success (include Location: /api/v1/users/123 header)
|
|
53
|
-
204 No Content → DELETE success
|
|
54
|
-
400 Bad Request → Malformed request / missing fields
|
|
55
|
-
401 Unauthorized → Missing or invalid authentication
|
|
56
|
-
403 Forbidden → Authenticated but not authorized
|
|
57
|
-
404 Not Found → Resource does not exist
|
|
58
|
-
409 Conflict → Duplicate resource (email already exists)
|
|
59
|
-
422 Unprocessable → Valid JSON, semantically invalid data
|
|
60
|
-
429 Too Many Req → Rate limit exceeded
|
|
61
|
-
500 Internal → Unhandled server error — NEVER expose stack traces
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### Response Envelope
|
|
65
|
-
```typescript
|
|
66
|
-
interface ApiResponse<T> { data: T; meta?: Record<string, unknown>; }
|
|
67
|
-
|
|
68
|
-
interface ApiError {
|
|
69
|
-
error: {
|
|
70
|
-
code: string; // machine-readable: "VALIDATION_ERROR"
|
|
71
|
-
message: string; // human-readable: "Email is already in use"
|
|
72
|
-
details?: Array<{ field: string; message: string }>; // field-level errors
|
|
73
|
-
requestId?: string; // for support/tracing
|
|
74
|
-
};
|
|
75
|
-
}
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
## Pagination
|
|
81
|
-
|
|
82
|
-
```typescript
|
|
83
|
-
// ✅ Cursor-based — required for large/dynamic datasets
|
|
84
|
-
// GET /api/v1/posts?cursor=eyJpZCI6MTAwfQ&limit=20
|
|
85
|
-
const posts = await db.post.findMany({
|
|
86
|
-
where: { id: { lt: decodeCursor(req.query.cursor).id } },
|
|
87
|
-
orderBy: { id: "desc" },
|
|
88
|
-
take: limit + 1, // fetch one extra to determine hasMore
|
|
89
|
-
});
|
|
90
|
-
const hasMore = posts.length > limit;
|
|
91
|
-
if (hasMore) posts.pop();
|
|
92
|
-
return { data: posts, meta: { hasMore, nextCursor: encodeCursor(posts.at(-1)) } };
|
|
93
|
-
|
|
94
|
-
// Offset-based — only for small datasets where users need page jumping
|
|
95
|
-
// GET /api/v1/posts?page=3&limit=20
|
|
96
|
-
// ❌ TRAP: OFFSET 100000 scans and discards 100K rows — degrades badly at scale
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## Idempotency
|
|
102
|
-
|
|
103
|
-
```typescript
|
|
104
|
-
// POST /api/v1/payments with header: Idempotency-Key: <uuid>
|
|
105
|
-
app.post("/api/v1/payments", async (req, res) => {
|
|
106
|
-
const key = req.headers["idempotency-key"];
|
|
107
|
-
if (!key) return res.status(400).json({ error: "Missing Idempotency-Key" });
|
|
108
|
-
|
|
109
|
-
const cached = await redis.get(`idempotency:${key}`);
|
|
110
|
-
if (cached) return res.status(200).json(JSON.parse(cached));
|
|
111
|
-
|
|
112
|
-
const result = await processPayment(req.body);
|
|
113
|
-
await redis.set(`idempotency:${key}`, JSON.stringify(result), "EX", 86400);
|
|
114
|
-
return res.status(201).json(result);
|
|
115
|
-
});
|
|
116
|
-
// GET, PUT, DELETE → naturally idempotent (safe to retry without a key)
|
|
117
|
-
// POST, PATCH → NOT idempotent by default — require Idempotency-Key
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## Webhooks
|
|
123
|
-
|
|
124
|
-
```typescript
|
|
125
|
-
// HMAC signature verification (always verify — never trust unsigned webhooks)
|
|
126
|
-
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
127
|
-
function verify(payload: string, signature: string, secret: string): boolean {
|
|
128
|
-
const expected = createHmac("sha256", secret).update(payload).digest("hex");
|
|
129
|
-
return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
app.post("/webhooks", (req, res) => {
|
|
133
|
-
if (!verify(JSON.stringify(req.body), req.headers["x-webhook-signature"] as string, WEBHOOK_SECRET))
|
|
134
|
-
return res.status(401).send("Invalid signature");
|
|
135
|
-
res.status(200).send("OK"); // respond immediately
|
|
136
|
-
processWebhookAsync(req.body); // process asynchronously
|
|
137
|
-
});
|
|
138
|
-
// Retry policy: 3 retries with exponential backoff (1s → 10s → 100s)
|
|
139
|
-
// Include unique event ID in payload for receiver-side deduplication
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
## Versioning
|
|
145
|
-
|
|
146
|
-
```
|
|
147
|
-
URL path (recommended): /api/v1/users → simplest, most common, cache-friendly
|
|
148
|
-
Header: Accept: application/vnd.api.v1+json
|
|
149
|
-
Query param: /api/users?version=1 → messy, avoid
|
|
150
|
-
|
|
151
|
-
Rules:
|
|
152
|
-
- Start at v1, never v0
|
|
153
|
-
- Breaking changes = new major version (v2)
|
|
154
|
-
- Non-breaking additions (new optional fields) do NOT need a version bump
|
|
155
|
-
- Deprecate before removing — give consumers 6+ months notice
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
---
|
|
159
|
-
|
|
160
|
-
## Rate Limiting
|
|
161
|
-
|
|
162
|
-
```
|
|
163
|
-
Strategy How When
|
|
164
|
-
Token bucket → Burst allowed, refills Most APIs (recommended)
|
|
165
|
-
Sliding window → Smooth distribution Strict fairness required
|
|
166
|
-
Fixed window → Simple counter per period Basic needs only
|
|
167
|
-
|
|
168
|
-
Response headers to always include:
|
|
169
|
-
X-RateLimit-Limit (max requests in window)
|
|
170
|
-
X-RateLimit-Remaining (requests left)
|
|
171
|
-
X-RateLimit-Reset (Unix timestamp when limit resets)
|
|
172
|
-
Retry-After (seconds to wait on 429)
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## GraphQL Security
|
|
178
|
-
|
|
179
|
-
```
|
|
180
|
-
Protect against:
|
|
181
|
-
Depth attacks → Set max query depth (typically 7–10)
|
|
182
|
-
Cost attacks → Calculate query complexity score, reject > threshold
|
|
183
|
-
Batch abuse → Limit batch size / alias count
|
|
184
|
-
Introspection → Disable in production (exposes full schema to attackers)
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
## Authentication Selection
|
|
190
|
-
|
|
191
|
-
| Pattern | Best For |
|
|
192
|
-
|---------|----------|
|
|
193
|
-
| **JWT** (short-lived access + httpOnly refresh) | Stateless services, microservices |
|
|
194
|
-
| **Session** | Traditional server-rendered apps |
|
|
195
|
-
| **OAuth 2.0 / OIDC** | Third-party login, delegated access |
|
|
196
|
-
| **API Key** | Server-to-server, public API consumers |
|
|
197
|
-
| **Passkey (WebAuthn)** | Modern passwordless (2026+) |
|
|
1
|
+
---
|
|
2
|
+
name: api-patterns
|
|
3
|
+
description: API design mastery. REST, GraphQL, tRPC, and gRPC selection. Request/response design, pagination (cursor/offset), filtering, versioning, rate limiting, error formats (RFC 9457), authentication (JWT/OAuth2/API keys), idempotency, file uploads, webhooks, and OpenAPI documentation. Use when designing APIs, choosing protocols, or implementing API standards.
|
|
4
|
+
allowed-tools: Read, Write, Edit, Glob, Grep
|
|
5
|
+
version: 3.1.0
|
|
6
|
+
last-updated: 2026-04-07
|
|
7
|
+
applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# API Patterns — Design & Protocol Mastery
|
|
11
|
+
|
|
12
|
+
## Hallucination Traps (Read First)
|
|
13
|
+
- ❌ JWT in URL query params → ✅ `Authorization: Bearer` header only. Query params get logged in server access logs.
|
|
14
|
+
- ❌ Assuming JWT is encrypted → ✅ JWT is base64-encoded (NOT encrypted). Anyone can decode it. Never put secrets/PII in the payload.
|
|
15
|
+
- ❌ Offset pagination on large tables → ✅ `OFFSET 100000` scans and discards 100K rows. Use cursor pagination for tables > 10K rows.
|
|
16
|
+
- ❌ Verbs in REST URLs (`/api/getUsers`) → ✅ Nouns only (`GET /api/users`). HTTP method IS the verb.
|
|
17
|
+
- ❌ `POST` is idempotent → ✅ `POST` is NOT idempotent — requires `Idempotency-Key` header for safe retries.
|
|
18
|
+
- ❌ GraphQL has no security risks → ✅ Deeply nested queries are a DoS vector. Set max depth, query cost limits. Disable introspection in production.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Protocol Selection Matrix
|
|
23
|
+
|
|
24
|
+
| Protocol | Use When |
|
|
25
|
+
|----------|----------|
|
|
26
|
+
| **REST** | Public APIs, 3rd-party consumers, standard CRUD, HTTP caching |
|
|
27
|
+
| **GraphQL** | Complex nested data, multiple clients, flexible queries, mobile bandwidth sensitivity |
|
|
28
|
+
| **tRPC** | Full-stack TypeScript (Next.js monorepo), shared types, no codegen |
|
|
29
|
+
| **gRPC** | Internal microservices, high-throughput, streaming, binary protocol |
|
|
30
|
+
| **WebSocket** | Bidirectional real-time (chat, gaming, live collaboration) |
|
|
31
|
+
| **SSE** | Server-to-client streaming only (AI token streaming, live feeds) |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## REST Design
|
|
36
|
+
|
|
37
|
+
### URL Conventions
|
|
38
|
+
```
|
|
39
|
+
✅ GET /api/v1/users list users
|
|
40
|
+
✅ GET /api/v1/users/123 get user by ID
|
|
41
|
+
✅ POST /api/v1/users create user
|
|
42
|
+
✅ PATCH /api/v1/users/123 partial update
|
|
43
|
+
✅ DELETE /api/v1/users/123 delete user
|
|
44
|
+
✅ GET /api/v1/users/123/posts nested resource
|
|
45
|
+
|
|
46
|
+
❌ /api/getUsers /api/createUser /api/user (singular) /api/Users (uppercase)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### HTTP Status Codes
|
|
50
|
+
```
|
|
51
|
+
200 OK → GET / PUT / PATCH success
|
|
52
|
+
201 Created → POST success (include Location: /api/v1/users/123 header)
|
|
53
|
+
204 No Content → DELETE success
|
|
54
|
+
400 Bad Request → Malformed request / missing fields
|
|
55
|
+
401 Unauthorized → Missing or invalid authentication
|
|
56
|
+
403 Forbidden → Authenticated but not authorized
|
|
57
|
+
404 Not Found → Resource does not exist
|
|
58
|
+
409 Conflict → Duplicate resource (email already exists)
|
|
59
|
+
422 Unprocessable → Valid JSON, semantically invalid data
|
|
60
|
+
429 Too Many Req → Rate limit exceeded
|
|
61
|
+
500 Internal → Unhandled server error — NEVER expose stack traces
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Response Envelope
|
|
65
|
+
```typescript
|
|
66
|
+
interface ApiResponse<T> { data: T; meta?: Record<string, unknown>; }
|
|
67
|
+
|
|
68
|
+
interface ApiError {
|
|
69
|
+
error: {
|
|
70
|
+
code: string; // machine-readable: "VALIDATION_ERROR"
|
|
71
|
+
message: string; // human-readable: "Email is already in use"
|
|
72
|
+
details?: Array<{ field: string; message: string }>; // field-level errors
|
|
73
|
+
requestId?: string; // for support/tracing
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Pagination
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
// ✅ Cursor-based — required for large/dynamic datasets
|
|
84
|
+
// GET /api/v1/posts?cursor=eyJpZCI6MTAwfQ&limit=20
|
|
85
|
+
const posts = await db.post.findMany({
|
|
86
|
+
where: { id: { lt: decodeCursor(req.query.cursor).id } },
|
|
87
|
+
orderBy: { id: "desc" },
|
|
88
|
+
take: limit + 1, // fetch one extra to determine hasMore
|
|
89
|
+
});
|
|
90
|
+
const hasMore = posts.length > limit;
|
|
91
|
+
if (hasMore) posts.pop();
|
|
92
|
+
return { data: posts, meta: { hasMore, nextCursor: encodeCursor(posts.at(-1)) } };
|
|
93
|
+
|
|
94
|
+
// Offset-based — only for small datasets where users need page jumping
|
|
95
|
+
// GET /api/v1/posts?page=3&limit=20
|
|
96
|
+
// ❌ TRAP: OFFSET 100000 scans and discards 100K rows — degrades badly at scale
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Idempotency
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
// POST /api/v1/payments with header: Idempotency-Key: <uuid>
|
|
105
|
+
app.post("/api/v1/payments", async (req, res) => {
|
|
106
|
+
const key = req.headers["idempotency-key"];
|
|
107
|
+
if (!key) return res.status(400).json({ error: "Missing Idempotency-Key" });
|
|
108
|
+
|
|
109
|
+
const cached = await redis.get(`idempotency:${key}`);
|
|
110
|
+
if (cached) return res.status(200).json(JSON.parse(cached));
|
|
111
|
+
|
|
112
|
+
const result = await processPayment(req.body);
|
|
113
|
+
await redis.set(`idempotency:${key}`, JSON.stringify(result), "EX", 86400);
|
|
114
|
+
return res.status(201).json(result);
|
|
115
|
+
});
|
|
116
|
+
// GET, PUT, DELETE → naturally idempotent (safe to retry without a key)
|
|
117
|
+
// POST, PATCH → NOT idempotent by default — require Idempotency-Key
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Webhooks
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
// HMAC signature verification (always verify — never trust unsigned webhooks)
|
|
126
|
+
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
127
|
+
function verify(payload: string, signature: string, secret: string): boolean {
|
|
128
|
+
const expected = createHmac("sha256", secret).update(payload).digest("hex");
|
|
129
|
+
return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
app.post("/webhooks", (req, res) => {
|
|
133
|
+
if (!verify(JSON.stringify(req.body), req.headers["x-webhook-signature"] as string, WEBHOOK_SECRET))
|
|
134
|
+
return res.status(401).send("Invalid signature");
|
|
135
|
+
res.status(200).send("OK"); // respond immediately
|
|
136
|
+
processWebhookAsync(req.body); // process asynchronously
|
|
137
|
+
});
|
|
138
|
+
// Retry policy: 3 retries with exponential backoff (1s → 10s → 100s)
|
|
139
|
+
// Include unique event ID in payload for receiver-side deduplication
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Versioning
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
URL path (recommended): /api/v1/users → simplest, most common, cache-friendly
|
|
148
|
+
Header: Accept: application/vnd.api.v1+json
|
|
149
|
+
Query param: /api/users?version=1 → messy, avoid
|
|
150
|
+
|
|
151
|
+
Rules:
|
|
152
|
+
- Start at v1, never v0
|
|
153
|
+
- Breaking changes = new major version (v2)
|
|
154
|
+
- Non-breaking additions (new optional fields) do NOT need a version bump
|
|
155
|
+
- Deprecate before removing — give consumers 6+ months notice
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Rate Limiting
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
Strategy How When
|
|
164
|
+
Token bucket → Burst allowed, refills Most APIs (recommended)
|
|
165
|
+
Sliding window → Smooth distribution Strict fairness required
|
|
166
|
+
Fixed window → Simple counter per period Basic needs only
|
|
167
|
+
|
|
168
|
+
Response headers to always include:
|
|
169
|
+
X-RateLimit-Limit (max requests in window)
|
|
170
|
+
X-RateLimit-Remaining (requests left)
|
|
171
|
+
X-RateLimit-Reset (Unix timestamp when limit resets)
|
|
172
|
+
Retry-After (seconds to wait on 429)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## GraphQL Security
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
Protect against:
|
|
181
|
+
Depth attacks → Set max query depth (typically 7–10)
|
|
182
|
+
Cost attacks → Calculate query complexity score, reject > threshold
|
|
183
|
+
Batch abuse → Limit batch size / alias count
|
|
184
|
+
Introspection → Disable in production (exposes full schema to attackers)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Authentication Selection
|
|
190
|
+
|
|
191
|
+
| Pattern | Best For |
|
|
192
|
+
|---------|----------|
|
|
193
|
+
| **JWT** (short-lived access + httpOnly refresh) | Stateless services, microservices |
|
|
194
|
+
| **Session** | Traditional server-rendered apps |
|
|
195
|
+
| **OAuth 2.0 / OIDC** | Third-party login, delegated access |
|
|
196
|
+
| **API Key** | Server-to-server, public API consumers |
|
|
197
|
+
| **Passkey (WebAuthn)** | Modern passwordless (2026+) |
|
|
198
198
|
|
|
199
199
|
|
|
200
200
|
---
|
|
@@ -236,4 +236,12 @@ Review these questions before confirming output:
|
|
|
236
236
|
|
|
237
237
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
238
238
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
239
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
239
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
## Pre-Flight Checklist
|
|
243
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
244
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
245
|
+
|
|
246
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
247
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -182,4 +182,12 @@ Review these questions before confirming output:
|
|
|
182
182
|
|
|
183
183
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
184
184
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
185
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
185
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
## Pre-Flight Checklist
|
|
189
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
190
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
191
|
+
|
|
192
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
193
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -561,4 +561,12 @@ Review these questions before confirming output:
|
|
|
561
561
|
|
|
562
562
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
563
563
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
564
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
564
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
## Pre-Flight Checklist
|
|
568
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
569
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
570
|
+
|
|
571
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
572
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -35,73 +35,81 @@ allowed-tools: Read, Glob, Grep
|
|
|
35
35
|
2. Match to appropriate template
|
|
36
36
|
3. Read ONLY that template's TEMPLATE.md
|
|
37
37
|
4. Follow its tech stack and structure
|
|
38
|
-
|
|
39
|
-
---
|
|
40
|
-
|
|
41
|
-
## 🚨 LLM Trap Table
|
|
42
|
-
|
|
43
|
-
|Pattern|What AI Does Wrong|What Is Actually Correct|
|
|
44
|
-
|:---|:---|:---|
|
|
45
|
-
|[domain-specific trap 1]|[hallucination]|[correct behavior]|
|
|
46
|
-
|[domain-specific trap 2]|[hallucination]|[correct behavior]|
|
|
47
|
-
|[domain-specific trap 3]|[hallucination]|[correct behavior]|
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## ✅ Pre-Flight Self-Audit
|
|
52
|
-
|
|
53
|
-
Before producing any output, verify:
|
|
54
|
-
``
|
|
55
|
-
✅ Did I read the actual files before making claims about them?
|
|
56
|
-
✅ Did I verify all method names against official documentation?
|
|
57
|
-
✅ Did I add // VERIFY: on any uncertain API calls?
|
|
58
|
-
✅ Are all imports from packages that actually exist in package.json?
|
|
59
|
-
✅ Did I test my logic with edge cases (null, empty, 0, max)?
|
|
60
|
-
✅ Did I avoid generating code for more than one module at a time?
|
|
61
|
-
✅ Am I working from evidence, not assumption?
|
|
62
|
-
``
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
## 🔠VBC Protocol (Verify → Build → Confirm)
|
|
67
|
-
|
|
68
|
-
``
|
|
69
|
-
VERIFY: Read the actual codebase before writing anything
|
|
70
|
-
BUILD: Generate the smallest meaningful unit of code
|
|
71
|
-
CONFIRM: Verify the output is correct before presenting
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🚨 LLM Trap Table
|
|
42
|
+
|
|
43
|
+
|Pattern|What AI Does Wrong|What Is Actually Correct|
|
|
44
|
+
|:---|:---|:---|
|
|
45
|
+
|[domain-specific trap 1]|[hallucination]|[correct behavior]|
|
|
46
|
+
|[domain-specific trap 2]|[hallucination]|[correct behavior]|
|
|
47
|
+
|[domain-specific trap 3]|[hallucination]|[correct behavior]|
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## ✅ Pre-Flight Self-Audit
|
|
52
|
+
|
|
53
|
+
Before producing any output, verify:
|
|
54
|
+
``
|
|
55
|
+
✅ Did I read the actual files before making claims about them?
|
|
56
|
+
✅ Did I verify all method names against official documentation?
|
|
57
|
+
✅ Did I add // VERIFY: on any uncertain API calls?
|
|
58
|
+
✅ Are all imports from packages that actually exist in package.json?
|
|
59
|
+
✅ Did I test my logic with edge cases (null, empty, 0, max)?
|
|
60
|
+
✅ Did I avoid generating code for more than one module at a time?
|
|
61
|
+
✅ Am I working from evidence, not assumption?
|
|
62
|
+
``
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 🔠VBC Protocol (Verify → Build → Confirm)
|
|
67
|
+
|
|
68
|
+
``
|
|
69
|
+
VERIFY: Read the actual codebase before writing anything
|
|
70
|
+
BUILD: Generate the smallest meaningful unit of code
|
|
71
|
+
CONFIRM: Verify the output is correct before presenting
|
|
72
|
+
``
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 🚨 LLM Trap Table
|
|
77
|
+
|
|
78
|
+
|Pattern|What AI Does Wrong|What Is Actually Correct|
|
|
79
|
+
|:---|:---|:---|
|
|
80
|
+
|[domain-specific trap 1]|[hallucination]|[correct behavior]|
|
|
81
|
+
|[domain-specific trap 2]|[hallucination]|[correct behavior]|
|
|
82
|
+
|[domain-specific trap 3]|[hallucination]|[correct behavior]|
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## ✅ Pre-Flight Self-Audit
|
|
87
|
+
|
|
88
|
+
Before producing any output, verify:
|
|
72
89
|
``
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## 🔠VBC Protocol (Verify → Build → Confirm)
|
|
102
|
-
|
|
103
|
-
``
|
|
104
|
-
VERIFY: Read the actual codebase before writing anything
|
|
105
|
-
BUILD: Generate the smallest meaningful unit of code
|
|
106
|
-
CONFIRM: Verify the output is correct before presenting
|
|
107
|
-
``
|
|
90
|
+
✅ Did I read the actual files before making claims about them?
|
|
91
|
+
✅ Did I verify all method names against official documentation?
|
|
92
|
+
✅ Did I add // VERIFY: on any uncertain API calls?
|
|
93
|
+
✅ Are all imports from packages that actually exist in package.json?
|
|
94
|
+
✅ Did I test my logic with edge cases (null, empty, 0, max)?
|
|
95
|
+
✅ Did I avoid generating code for more than one module at a time?
|
|
96
|
+
✅ Am I working from evidence, not assumption?
|
|
97
|
+
``
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 🔠VBC Protocol (Verify → Build → Confirm)
|
|
102
|
+
|
|
103
|
+
``
|
|
104
|
+
VERIFY: Read the actual codebase before writing anything
|
|
105
|
+
BUILD: Generate the smallest meaningful unit of code
|
|
106
|
+
CONFIRM: Verify the output is correct before presenting
|
|
107
|
+
``
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
## Pre-Flight Checklist
|
|
111
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
112
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
113
|
+
|
|
114
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
115
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -134,4 +134,12 @@ Review these questions before confirming output:
|
|
|
134
134
|
|
|
135
135
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
136
136
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
137
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
137
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
## Pre-Flight Checklist
|
|
141
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
142
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
143
|
+
|
|
144
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
145
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -208,4 +208,12 @@ Review these questions before confirming output:
|
|
|
208
208
|
|
|
209
209
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
210
210
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
211
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
211
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
## Pre-Flight Checklist
|
|
215
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
216
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
217
|
+
|
|
218
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
219
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -178,4 +178,12 @@ Review these questions before confirming output:
|
|
|
178
178
|
|
|
179
179
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
180
180
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
181
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
181
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
## Pre-Flight Checklist
|
|
185
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
186
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
187
|
+
|
|
188
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
189
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|
|
@@ -168,4 +168,12 @@ Review these questions before confirming output:
|
|
|
168
168
|
|
|
169
169
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
170
170
|
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
|
|
171
|
-
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
171
|
+
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
## Pre-Flight Checklist
|
|
175
|
+
- [ ] Have I reviewed the user's specific constraints and requests?
|
|
176
|
+
- [ ] Have I checked the environment for relevant existing implementations?
|
|
177
|
+
|
|
178
|
+
## VBC Protocol (Verification-Before-Completion)
|
|
179
|
+
You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
|