@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/backend/PACK.md

@@ -1,104 +1,104 @@
----
-name: "@rune/backend"
-description: Backend patterns — API design, authentication, database patterns, middleware architecture, caching strategies, background job processing, CLI generation, and async processing pipelines.
-metadata:
-  author: runedev
-  version: "0.3.0"
-  layer: L4
-  price: "free"
-  target: Backend developers
-  format: split
----
-
-# @rune/backend
-
-## Purpose
-
-Backend codebases accumulate structural debt across six areas: inconsistent API contracts (mixed naming, missing pagination, vague errors), insecure auth flows (token mismanagement, missing refresh rotation, weak RBAC), database anti-patterns (N+1 queries, missing indexes, unsafe migrations), ad-hoc middleware (duplicated validation, no request tracing, inconsistent error format), missing or naive caching (no invalidation strategy, cache stampede risk, unbounded memory growth), and synchronous processing of inherently async work (blocking request threads on email, PDF, image tasks). This pack addresses each systematically — detect the anti-pattern, emit the fix, verify the result. Skills are independent but compound: clean APIs need solid auth, solid auth needs safe queries, safe queries need proper middleware, and high-traffic APIs need caching and background jobs to stay responsive.
-
-## Triggers
-
-- Auto-trigger: when `routes/`, `controllers/`, `middleware/`, `*.resolver.ts`, `*.service.ts`, `queues/`, `workers/`, or server framework config detected
-- `/rune api-patterns` — audit and fix API design
-- `/rune auth-patterns` — audit and fix authentication flows
-- `/rune database-patterns` — audit and fix database queries and schema
-- `/rune middleware-patterns` — audit and fix middleware stack
-- `/rune caching-patterns` — audit and implement caching strategy
-- `/rune background-jobs` — identify async operations and implement job queues
-- `/rune cli-generation` — generate production CLI for existing backend services
-- `/rune async-pipeline` — build multi-stage async processing pipelines with waterfall fallback
-- Called by `cook` (L1) when backend task is detected
-- Called by `review` (L2) when API/backend code is under review
-
-## Skills Included
-
-| Skill | Model | Description |
-|-------|-------|-------------|
-| [api-patterns](skills/api-patterns.md) | sonnet | RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation. |
-| [auth-patterns](skills/auth-patterns.md) | sonnet | Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows. |
-| [database-patterns](skills/database-patterns.md) | sonnet | Database design and query patterns — schema design, migrations, indexing strategies, N+1 prevention, soft deletes, read replicas, connection pooling, seeding. |
-| [middleware-patterns](skills/middleware-patterns.md) | sonnet | Middleware architecture — request validation, error handling, logging, CORS, compression, graceful shutdown, health checks, request ID tracking. |
-| [caching-patterns](skills/caching-patterns.md) | sonnet | Caching strategies — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention. |
-| [background-jobs](skills/background-jobs.md) | sonnet | Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring. |
-| [cli-generation](skills/cli-generation.md) | sonnet | Generate production-grade CLI wrappers — command groups, dual output mode (human + JSON), stateful REPL, session management with undo/redo, installable packaging. |
-| [async-pipeline](skills/async-pipeline.md) | sonnet | Multi-stage async processing pipelines with waterfall engine selection, progress streaming via SSE, concurrency control, and credit-based billing. |
-
-## Tech Stack Support
-
-| Framework | ORM | Auth Library | Queue | Cache |
-|-----------|-----|-------------|-------|-------|
-| Express 5 | Prisma | Passport / custom JWT | BullMQ | ioredis |
-| Fastify 5 | Drizzle | @fastify/jwt | BullMQ | ioredis |
-| Next.js 16 (Route Handlers) | Prisma | NextAuth v5 / Lucia | BullMQ | ioredis / Upstash |
-| NestJS 11 | TypeORM / Prisma | @nestjs/passport | @nestjs/bull | @nestjs/cache-manager |
-| FastAPI | SQLAlchemy | python-jose / authlib | Celery | redis-py |
-| Django 5 | Django ORM | django-rest-framework | Celery | django-redis |
-
-## Connections
-
-```
-Calls → docs-seeker (L3): lookup API documentation and framework guides
-Calls → sentinel (L2): security audit on auth implementations
-Calls → watchdog (L3): monitor queue depth and cache hit ratios
-Calls → @rune/devops (L4): container and serverless deployment config for backend services
-Called By ← cook (L1): when backend task detected
-Called By ← review (L2): when API/backend code is being reviewed
-Called By ← audit (L2): backend health dimension
-Called By ← deploy (L2): pre-deploy readiness checks (health endpoints, graceful shutdown)
-Called By ← @rune/saas (L4): SaaS services use backend API, auth, and caching patterns
-Called By ← @rune/security (L4): security audits reference auth flows and middleware patterns
-Called By ← @rune/mobile (L4): mobile backend integration patterns (auth, push server)
-Inter-skill: cli-generation → api-patterns (CLI wraps existing API surface)
-Inter-skill: async-pipeline → background-jobs (pipeline stages use job queue for execution)
-Inter-skill: async-pipeline → caching-patterns (pipeline results cached by content hash)
-```
-
-## Sharp Edges
-
-- **Auth**: Never emit JWT without expiry; hard-cap access tokens at 15min, refresh at 7d.
-- **Cache stampede**: Always emit Redis `SET NX` mutex lock on cache miss for hot keys.
-- **Job idempotency**: Never use random UUID as job ID — use deterministic domain key (e.g., `email:welcome:${userId}`).
-- **N+1**: Check ORM `lazy: true` defaults (Sequelize, TypeORM) — not caught by loop scan alone.
-- **Migrations**: Every migration MUST include both `up()` and `down()` — flag any missing rollback.
-- **LRU**: Always set `max` entries AND `ttl` — unbounded LRU grows to OOM.
-- **CORS**: Flag `origin: '*'` in production configs; check `NODE_ENV` before emitting.
-- **SSE**: Send heartbeat comment every 30s (`:\n\n`) to prevent proxy/LB 60s timeout drops.
-- **Dead letters**: Emit alert on DLQ depth > 0 for critical queues; never silently drop failed jobs.
-- **Credit math**: Always `Math.ceil()` final cost; use integer cents internally to avoid float drift.
-
-## Done When
-
-- API audit report emitted with naming violations, missing pagination, versioning strategy, and fix diffs
-- Auth flow hardened: short-lived access tokens, httpOnly refresh cookies, proper hashing, OAuth/OIDC integration ready
-- N+1 queries detected and replaced with eager loading; soft delete pattern applied; missing indexes migrated
-- Middleware stack has: request ID, structured logging, global error handler, input validation, compression, graceful shutdown, health endpoints
-- Caching strategy implemented: cacheable endpoints identified, cache layer selected, invalidation logic emitted alongside every write
-- Async operations moved to background jobs: idempotency keys assigned, retry strategy configured, dead letter queue wired
-- All emitted code uses project's existing framework and ORM (detected from package.json)
-- CLI generated with dual output (human + JSON), REPL mode, session undo/redo, and installable package
-- Async pipeline has waterfall engine selection, progress streaming via SSE, concurrency control, and credit billing
-- Structured report emitted for each skill invoked
-
-## Cost Profile
-
-~14,000–28,000 tokens per full pack run (all 8 skills). Individual skill: ~2,000–5,000 tokens. Sonnet default for code generation and security audit. Use haiku for detection scans (Step 1 of each skill). Escalate to opus for architecture decisions on caching topology, pipeline design, or queue system selection in high-traffic systems.
+---
+name: "@rune/backend"
+description: Backend patterns — API design, authentication, database patterns, middleware architecture, caching strategies, background job processing, CLI generation, and async processing pipelines.
+metadata:
+  author: runedev
+  version: "0.3.0"
+  layer: L4
+  price: "free"
+  target: Backend developers
+  format: split
+---
+
+# @rune/backend
+
+## Purpose
+
+Backend codebases accumulate structural debt across six areas: inconsistent API contracts (mixed naming, missing pagination, vague errors), insecure auth flows (token mismanagement, missing refresh rotation, weak RBAC), database anti-patterns (N+1 queries, missing indexes, unsafe migrations), ad-hoc middleware (duplicated validation, no request tracing, inconsistent error format), missing or naive caching (no invalidation strategy, cache stampede risk, unbounded memory growth), and synchronous processing of inherently async work (blocking request threads on email, PDF, image tasks). This pack addresses each systematically — detect the anti-pattern, emit the fix, verify the result. Skills are independent but compound: clean APIs need solid auth, solid auth needs safe queries, safe queries need proper middleware, and high-traffic APIs need caching and background jobs to stay responsive.
+
+## Triggers
+
+- Auto-trigger: when `routes/`, `controllers/`, `middleware/`, `*.resolver.ts`, `*.service.ts`, `queues/`, `workers/`, or server framework config detected
+- `/rune api-patterns` — audit and fix API design
+- `/rune auth-patterns` — audit and fix authentication flows
+- `/rune database-patterns` — audit and fix database queries and schema
+- `/rune middleware-patterns` — audit and fix middleware stack
+- `/rune caching-patterns` — audit and implement caching strategy
+- `/rune background-jobs` — identify async operations and implement job queues
+- `/rune cli-generation` — generate production CLI for existing backend services
+- `/rune async-pipeline` — build multi-stage async processing pipelines with waterfall fallback
+- Called by `cook` (L1) when backend task is detected
+- Called by `review` (L2) when API/backend code is under review
+
+## Skills Included
+
+| Skill | Model | Description |
+|-------|-------|-------------|
+| [api-patterns](skills/api-patterns.md) | sonnet | RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation. |
+| [auth-patterns](skills/auth-patterns.md) | sonnet | Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows. |
+| [database-patterns](skills/database-patterns.md) | sonnet | Database design and query patterns — schema design, migrations, indexing strategies, N+1 prevention, soft deletes, read replicas, connection pooling, seeding. |
+| [middleware-patterns](skills/middleware-patterns.md) | sonnet | Middleware architecture — request validation, error handling, logging, CORS, compression, graceful shutdown, health checks, request ID tracking. |
+| [caching-patterns](skills/caching-patterns.md) | sonnet | Caching strategies — in-memory LRU, Redis distributed cache, CDN/edge cache, browser cache headers, invalidation, and stampede prevention. |
+| [background-jobs](skills/background-jobs.md) | sonnet | Queue-based async processing — BullMQ (Node.js), job patterns, retry strategies, idempotency, dead letter queues, monitoring. |
+| [cli-generation](skills/cli-generation.md) | sonnet | Generate production-grade CLI wrappers — command groups, dual output mode (human + JSON), stateful REPL, session management with undo/redo, installable packaging. |
+| [async-pipeline](skills/async-pipeline.md) | sonnet | Multi-stage async processing pipelines with waterfall engine selection, progress streaming via SSE, concurrency control, and credit-based billing. |
+
+## Tech Stack Support
+
+| Framework | ORM | Auth Library | Queue | Cache |
+|-----------|-----|-------------|-------|-------|
+| Express 5 | Prisma | Passport / custom JWT | BullMQ | ioredis |
+| Fastify 5 | Drizzle | @fastify/jwt | BullMQ | ioredis |
+| Next.js 16 (Route Handlers) | Prisma | NextAuth v5 / Lucia | BullMQ | ioredis / Upstash |
+| NestJS 11 | TypeORM / Prisma | @nestjs/passport | @nestjs/bull | @nestjs/cache-manager |
+| FastAPI | SQLAlchemy | python-jose / authlib | Celery | redis-py |
+| Django 5 | Django ORM | django-rest-framework | Celery | django-redis |
+
+## Connections
+
+```
+Calls → docs-seeker (L3): lookup API documentation and framework guides
+Calls → sentinel (L2): security audit on auth implementations
+Calls → watchdog (L3): monitor queue depth and cache hit ratios
+Calls → @rune/devops (L4): container and serverless deployment config for backend services
+Called By ← cook (L1): when backend task detected
+Called By ← review (L2): when API/backend code is being reviewed
+Called By ← audit (L2): backend health dimension
+Called By ← deploy (L2): pre-deploy readiness checks (health endpoints, graceful shutdown)
+Called By ← @rune/saas (L4): SaaS services use backend API, auth, and caching patterns
+Called By ← @rune/security (L4): security audits reference auth flows and middleware patterns
+Called By ← @rune/mobile (L4): mobile backend integration patterns (auth, push server)
+Inter-skill: cli-generation → api-patterns (CLI wraps existing API surface)
+Inter-skill: async-pipeline → background-jobs (pipeline stages use job queue for execution)
+Inter-skill: async-pipeline → caching-patterns (pipeline results cached by content hash)
+```
+
+## Sharp Edges
+
+- **Auth**: Never emit JWT without expiry; hard-cap access tokens at 15min, refresh at 7d.
+- **Cache stampede**: Always emit Redis `SET NX` mutex lock on cache miss for hot keys.
+- **Job idempotency**: Never use random UUID as job ID — use deterministic domain key (e.g., `email:welcome:${userId}`).
+- **N+1**: Check ORM `lazy: true` defaults (Sequelize, TypeORM) — not caught by loop scan alone.
+- **Migrations**: Every migration MUST include both `up()` and `down()` — flag any missing rollback.
+- **LRU**: Always set `max` entries AND `ttl` — unbounded LRU grows to OOM.
+- **CORS**: Flag `origin: '*'` in production configs; check `NODE_ENV` before emitting.
+- **SSE**: Send heartbeat comment every 30s (`:\n\n`) to prevent proxy/LB 60s timeout drops.
+- **Dead letters**: Emit alert on DLQ depth > 0 for critical queues; never silently drop failed jobs.
+- **Credit math**: Always `Math.ceil()` final cost; use integer cents internally to avoid float drift.
+
+## Done When
+
+- API audit report emitted with naming violations, missing pagination, versioning strategy, and fix diffs
+- Auth flow hardened: short-lived access tokens, httpOnly refresh cookies, proper hashing, OAuth/OIDC integration ready
+- N+1 queries detected and replaced with eager loading; soft delete pattern applied; missing indexes migrated
+- Middleware stack has: request ID, structured logging, global error handler, input validation, compression, graceful shutdown, health endpoints
+- Caching strategy implemented: cacheable endpoints identified, cache layer selected, invalidation logic emitted alongside every write
+- Async operations moved to background jobs: idempotency keys assigned, retry strategy configured, dead letter queue wired
+- All emitted code uses project's existing framework and ORM (detected from package.json)
+- CLI generated with dual output (human + JSON), REPL mode, session undo/redo, and installable package
+- Async pipeline has waterfall engine selection, progress streaming via SSE, concurrency control, and credit billing
+- Structured report emitted for each skill invoked
+
+## Cost Profile
+
+~14,000–28,000 tokens per full pack run (all 8 skills). Individual skill: ~2,000–5,000 tokens. Sonnet default for code generation and security audit. Use haiku for detection scans (Step 1 of each skill). Escalate to opus for architecture decisions on caching topology, pipeline design, or queue system selection in high-traffic systems.

package/extensions/backend/skills/api-patterns.md

@@ -1,84 +1,84 @@
----
-name: "api-patterns"
-pack: "@rune/backend"
-description: "RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# api-patterns
-
-RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation.
-
-#### Workflow
-
-**Step 1 — Detect API surface**
-Use Grep to find route definitions (`app.get`, `app.post`, `router.`, `@Get()`, `@Post()`, `@Query`, `@Mutation`). Read each route file to inventory: endpoint paths, HTTP methods, response shapes, error handling approach.
-
-**Step 2 — Audit naming and structure**
-Check each endpoint against REST conventions: plural nouns for collections (`/users` not `/getUsers`), nested resources for relationships (`/users/:id/posts`), query params for filtering (`?status=active`), consistent error envelope. Flag violations with specific fix for each.
-
-**Step 3 — Add missing pagination and filtering**
-For list endpoints returning unbounded arrays, emit cursor-based or offset pagination. For endpoints with no filtering, add query param parsing with Zod/Joi validation. Emit the middleware or decorator that enforces the pattern.
-
-**Step 4 — API versioning strategy**
-Choose versioning approach based on project context: URL path (`/v2/users`) for public APIs with long deprecation windows; `Accept-Version: 2` header for internal APIs needing cleaner URLs; query param (`?version=2`) for simple cases. Emit version routing middleware and a deprecation warning header (`Deprecation: true, Sunset: <date>`) on v1 routes. Document migration path in the route file as a comment.
-
-**Step 5 — OpenAPI/Swagger and GraphQL patterns**
-For REST: emit OpenAPI 3.1 schema from route definitions using tsoa decorators (TypeScript), Fastify's built-in JSON Schema (`schema: { body, querystring, response }`), or NestJS `@ApiProperty`. For GraphQL: if schema-first, validate resolvers match schema types; if code-first (NestJS), check `@ObjectType` / `@Field` decorators. Add DataLoader to any resolver with a per-request DB call to prevent N+1 at the GraphQL layer. Emit subscription pattern (WebSocket transport) for real-time fields.
-
-#### Example
-
-```typescript
-// BEFORE: inconsistent naming, no pagination, bare error
-app.get('/getUsers', async (req, res) => {
-  const users = await db.query('SELECT * FROM users');
-  res.json(users);
-});
-
-// AFTER: REST naming, cursor pagination, error envelope, Zod validation
-const paginationSchema = z.object({
-  query: z.object({
-    cursor: z.string().optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(20),
-    status: z.enum(['active', 'inactive']).optional(),
-  }),
-});
-
-app.get('/users', validate(paginationSchema), async (req, res) => {
-  const { cursor, limit, status } = req.query;
-  const users = await userRepo.findMany({ cursor, limit: limit + 1, status });
-  const hasNext = users.length > limit;
-  res.json({
-    data: users.slice(0, limit),
-    pagination: { next_cursor: hasNext ? users[limit - 1].id : null, has_more: hasNext },
-  });
-});
-
-// Rate limiting: sliding window with Redis (atomic, no race condition)
-const rateLimitMiddleware = async (req, res, next) => {
-  const key = `rl:${req.ip}:${Math.floor(Date.now() / 60_000)}`; // 1-minute window
-  const multi = redis.multi();
-  multi.incr(key);
-  multi.expire(key, 60);
-  const [count] = await multi.exec();
-  if (count > 100) return res.status(429).json({ error: { code: 'RATE_LIMITED', message: 'Too many requests' } });
-  res.setHeader('X-RateLimit-Remaining', 100 - count);
-  next();
-};
-
-// Fastify: built-in schema validation + OpenAPI generation
-fastify.get('/users/:id', {
-  schema: {
-    params: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } }, required: ['id'] },
-    response: { 200: UserSchema, 404: ErrorSchema },
-  },
-}, async (req, reply) => { /* handler */ });
-
-// GraphQL: DataLoader prevents N+1 in resolvers
-const userLoader = new DataLoader(async (userIds: string[]) => {
-  const users = await prisma.user.findMany({ where: { id: { in: userIds } } });
-  return userIds.map(id => users.find(u => u.id === id) ?? new Error(`User ${id} not found`));
-});
-// In resolver: return userLoader.load(post.authorId) — batches all loads per request
-```
+---
+name: "api-patterns"
+pack: "@rune/backend"
+description: "RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# api-patterns
+
+RESTful and GraphQL API design patterns — resource naming, pagination, filtering, error responses, versioning, rate limiting, OpenAPI generation.
+
+#### Workflow
+
+**Step 1 — Detect API surface**
+Use Grep to find route definitions (`app.get`, `app.post`, `router.`, `@Get()`, `@Post()`, `@Query`, `@Mutation`). Read each route file to inventory: endpoint paths, HTTP methods, response shapes, error handling approach.
+
+**Step 2 — Audit naming and structure**
+Check each endpoint against REST conventions: plural nouns for collections (`/users` not `/getUsers`), nested resources for relationships (`/users/:id/posts`), query params for filtering (`?status=active`), consistent error envelope. Flag violations with specific fix for each.
+
+**Step 3 — Add missing pagination and filtering**
+For list endpoints returning unbounded arrays, emit cursor-based or offset pagination. For endpoints with no filtering, add query param parsing with Zod/Joi validation. Emit the middleware or decorator that enforces the pattern.
+
+**Step 4 — API versioning strategy**
+Choose versioning approach based on project context: URL path (`/v2/users`) for public APIs with long deprecation windows; `Accept-Version: 2` header for internal APIs needing cleaner URLs; query param (`?version=2`) for simple cases. Emit version routing middleware and a deprecation warning header (`Deprecation: true, Sunset: <date>`) on v1 routes. Document migration path in the route file as a comment.
+
+**Step 5 — OpenAPI/Swagger and GraphQL patterns**
+For REST: emit OpenAPI 3.1 schema from route definitions using tsoa decorators (TypeScript), Fastify's built-in JSON Schema (`schema: { body, querystring, response }`), or NestJS `@ApiProperty`. For GraphQL: if schema-first, validate resolvers match schema types; if code-first (NestJS), check `@ObjectType` / `@Field` decorators. Add DataLoader to any resolver with a per-request DB call to prevent N+1 at the GraphQL layer. Emit subscription pattern (WebSocket transport) for real-time fields.
+
+#### Example
+
+```typescript
+// BEFORE: inconsistent naming, no pagination, bare error
+app.get('/getUsers', async (req, res) => {
+  const users = await db.query('SELECT * FROM users');
+  res.json(users);
+});
+
+// AFTER: REST naming, cursor pagination, error envelope, Zod validation
+const paginationSchema = z.object({
+  query: z.object({
+    cursor: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    status: z.enum(['active', 'inactive']).optional(),
+  }),
+});
+
+app.get('/users', validate(paginationSchema), async (req, res) => {
+  const { cursor, limit, status } = req.query;
+  const users = await userRepo.findMany({ cursor, limit: limit + 1, status });
+  const hasNext = users.length > limit;
+  res.json({
+    data: users.slice(0, limit),
+    pagination: { next_cursor: hasNext ? users[limit - 1].id : null, has_more: hasNext },
+  });
+});
+
+// Rate limiting: sliding window with Redis (atomic, no race condition)
+const rateLimitMiddleware = async (req, res, next) => {
+  const key = `rl:${req.ip}:${Math.floor(Date.now() / 60_000)}`; // 1-minute window
+  const multi = redis.multi();
+  multi.incr(key);
+  multi.expire(key, 60);
+  const [count] = await multi.exec();
+  if (count > 100) return res.status(429).json({ error: { code: 'RATE_LIMITED', message: 'Too many requests' } });
+  res.setHeader('X-RateLimit-Remaining', 100 - count);
+  next();
+};
+
+// Fastify: built-in schema validation + OpenAPI generation
+fastify.get('/users/:id', {
+  schema: {
+    params: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } }, required: ['id'] },
+    response: { 200: UserSchema, 404: ErrorSchema },
+  },
+}, async (req, reply) => { /* handler */ });
+
+// GraphQL: DataLoader prevents N+1 in resolvers
+const userLoader = new DataLoader(async (userIds: string[]) => {
+  const users = await prisma.user.findMany({ where: { id: { in: userIds } } });
+  return userIds.map(id => users.find(u => u.id === id) ?? new Error(`User ${id} not found`));
+});
+// In resolver: return userLoader.load(post.authorId) — batches all loads per request
+```