@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/backend/skills/cli-generation.md

@@ -0,0 +1,133 @@
+---
+name: "cli-generation"
+pack: "@rune/backend"
+description: "Generate production-grade CLI wrappers for backend services — command groups, dual output mode (human + JSON), stateful REPL, session management with undo/redo, and pip/npm-installable packaging."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# cli-generation
+
+Generate production-grade CLI wrappers for backend services — command groups, dual output mode (human + JSON), stateful REPL, session management with undo/redo, and pip/npm-installable packaging.
+
+#### Workflow
+
+**Step 1 — Analyze backend service surface**
+Map existing API endpoints, service methods, or data models to CLI command groups:
+```typescript
+interface CLICommandGroup {
+  name: string;          // e.g., 'users', 'orders', 'config'
+  source: string;        // API route file or service class
+  commands: CLICommand[];
+}
+
+interface CLICommand {
+  name: string;          // e.g., 'list', 'create', 'delete'
+  sourceMethod: string;  // e.g., 'UserService.findAll'
+  params: CLIParam[];
+  mutating: boolean;     // true = needs confirmation/undo support
+}
+```
+
+**Step 2 — Design dual output mode**
+Every command MUST support both human-readable and machine-readable output:
+```typescript
+// Human mode (default): tables, colors, formatted text
+function formatHuman(data: any, format: 'table' | 'list' | 'detail'): string {
+  if (format === 'table') return formatTable(data, { borders: true, colors: true });
+  if (format === 'list') return data.map((d: any) => `  • ${d.name}`).join('\n');
+  return JSON.stringify(data, null, 2);
+}
+
+// JSON mode (--json flag): structured output for piping/scripting
+function formatJSON(data: any): string {
+  return JSON.stringify(data, null, 2);
+}
+
+// Error output follows same dual pattern
+function formatError(error: Error, jsonMode: boolean): string {
+  if (jsonMode) return JSON.stringify({ error: error.message, type: error.constructor.name });
+  return chalk.red(`Error: ${error.message}`);
+}
+```
+
+**Step 3 — Implement session with undo/redo**
+For mutating operations, maintain session state:
+```typescript
+interface CLISession {
+  id: string;
+  history: SessionSnapshot[];
+  undoStack: SessionSnapshot[];   // max 50
+  redoStack: SessionSnapshot[];
+  modified: boolean;
+}
+
+function snapshot(session: CLISession, action: string): CLISession {
+  return {
+    ...session,
+    undoStack: [...session.undoStack.slice(-49), { action, state: deepCopy(session) }],
+    redoStack: [],  // new action clears redo
+    modified: true,
+  };
+}
+```
+
+**Step 4 — Build REPL mode**
+CLI enters REPL when invoked without subcommand:
+```typescript
+// Click (Python) — invoke_without_command=True enters REPL
+@click.group(invoke_without_command=True)
+@click.pass_context
+def cli(ctx):
+    if ctx.invoked_subcommand is None:
+        start_repl(ctx)
+
+// Commander (Node.js) — detect no args
+if (process.argv.length <= 2) {
+  startREPL({ history: '~/.myapp_history', prompt: 'myapp> ' });
+}
+```
+
+REPL features: command history (file-persisted), auto-suggest from history, tab completion, colored prompt, help command, status bar showing connection state.
+
+**Step 5 — Package for distribution**
+```bash
+# Python: PEP 420 namespace packages for independent installability
+# pyproject.toml or setup.py
+entry_points = {
+    'console_scripts': ['myapp = myapp.cli:main'],
+}
+
+# Node.js: bin field in package.json
+{
+  "bin": { "myapp": "./bin/cli.js" },
+  "files": ["bin/", "lib/"]
+}
+```
+
+**Step 6 — Verify installation**
+After packaging: install locally (`pip install -e .` or `npm link`), verify binary on PATH (`which myapp`), run `myapp --version`, test `myapp --json` mode, and verify REPL launch.
+
+#### Example
+
+```python
+# Generated CLI structure for a backend service
+# myapp/
+# ├── cli.py          ← Click entry point + REPL
+# ├── commands/
+# │   ├── users.py    ← User CRUD commands
+# │   ├── orders.py   ← Order management
+# │   └── config.py   ← Config operations
+# ├── core/
+# │   ├── session.py  ← Session + undo/redo
+# │   └── client.py   ← API client wrapper
+# └── utils/
+#     ├── output.py   ← Dual output (human + JSON)
+#     └── repl.py     ← REPL with prompt-toolkit
+
+# Usage:
+# myapp users list                    → human-readable table
+# myapp users list --json             → JSON output for piping
+# myapp users create --name "Alice"   → creates user, snapshots for undo
+# myapp                               → enters REPL mode
+```

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

@@ -0,0 +1,87 @@
+---
+name: "database-patterns"
+pack: "@rune/backend"
+description: "Database design and query patterns — schema design, migrations, indexing strategies, N+1 prevention, soft deletes, read replicas, connection pooling, seeding."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# database-patterns
+
+Database design and query patterns — schema design, migrations, indexing strategies, N+1 prevention, soft deletes, read replicas, connection pooling, seeding.
+
+#### Workflow
+
+**Step 1 — Detect ORM and query patterns**
+Use Grep to find ORM usage (`prisma.`, `knex(`, `sequelize.`, `typeorm`, `drizzle`, `mongoose.`, `db.query`) and raw SQL strings. Read schema files (`schema.prisma`, `migrations/`, `models/`) to understand the data model.
+
+**Step 2 — Detect N+1 and missing indexes**
+Scan for loops containing database calls (a query inside `for`, `map`, `forEach` → N+1). Check foreign key columns for missing indexes. Identify queries with `WHERE` clauses on unindexed columns. Flag each with the specific query and fix.
+
+**Step 3 — Emit optimized queries**
+For N+1: emit eager loading (`include`, `populate`, `JOIN`). For missing indexes: emit migration files. For unsafe raw SQL: emit parameterized version. For connection pooling: check pool config and recommend sizing based on max connections.
+
+**Step 4 — Soft delete and query scoping**
+Emit soft delete pattern: add `deleted_at TIMESTAMPTZ` column, update all `findMany`/`findUnique` calls to include `WHERE deleted_at IS NULL`. Cascade consideration: soft-delete parent should soft-delete children (emit trigger or application-level cascade). For Prisma: emit a custom extension that injects the filter automatically. Warn about index bloat from soft-deleted rows — add partial index `WHERE deleted_at IS NULL` to keep index lean.
+
+**Step 5 — Read replicas, connection pooling, and seeding**
+Read replicas: emit query routing — writes to primary, reads to replica. Handle replication lag: do not read from replica immediately after write in the same request (use primary for the read-after-write). For Prisma: emit `$extends` with read/write client split. Connection pooling deep dive: PgBouncer in transaction mode for serverless (each query gets a connection); Prisma's built-in pool for long-running servers. Pool sizing formula: `connections = (core_count * 2) + effective_spindle_count`. Seeding: emit factory functions using `@faker-js/faker` — deterministic seeds via `faker.seed(42)` for reproducible test data.
+
+#### Example
+
+```typescript
+// BEFORE: N+1 — one query per post to get author
+const posts = await prisma.post.findMany();
+for (const post of posts) {
+  post.author = await prisma.user.findUnique({ where: { id: post.authorId } });
+}
+
+// AFTER: eager loading, single query with JOIN
+const posts = await prisma.post.findMany({
+  include: { author: { select: { id: true, name: true, avatar: true } } },
+});
+
+// Migration: missing indexes + soft delete column
+-- Migration: add_indexes_and_soft_delete_to_posts
+ALTER TABLE posts ADD COLUMN deleted_at TIMESTAMPTZ;
+CREATE INDEX idx_posts_author_id ON posts(author_id);
+CREATE INDEX idx_posts_created_at ON posts(created_at DESC);
+CREATE INDEX idx_posts_active ON posts(author_id, created_at DESC) WHERE deleted_at IS NULL;
+
+// Prisma soft delete extension (auto-scopes all queries)
+const softDelete = Prisma.defineExtension({
+  name: 'softDelete',
+  query: {
+    $allModels: {
+      async findMany({ model, operation, args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+      async delete({ model, args, query }) {
+        return (query as any)({ ...args, data: { deletedAt: new Date() } } as any);
+      },
+    },
+  },
+});
+const prisma = new PrismaClient().$extends(softDelete);
+
+// Read replica routing with Prisma
+const primaryClient = new PrismaClient({ datasources: { db: { url: PRIMARY_URL } } });
+const replicaClient = new PrismaClient({ datasources: { db: { url: REPLICA_URL } } });
+const db = { write: primaryClient, read: replicaClient };
+// Usage: db.write.user.create(...) vs db.read.user.findMany(...)
+
+// Factory seeding
+import { faker } from '@faker-js/faker';
+faker.seed(42); // reproducible
+
+const createUserFactory = (overrides = {}) => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  createdAt: faker.date.past(),
+  ...overrides,
+});
+
+await prisma.user.createMany({ data: Array.from({ length: 50 }, () => createUserFactory()) });
+```

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

@@ -0,0 +1,104 @@
+---
+name: "middleware-patterns"
+pack: "@rune/backend"
+description: "Middleware architecture — request validation, error handling, logging, CORS, compression, graceful shutdown, health checks, request ID tracking."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# middleware-patterns
+
+Middleware architecture — request validation, error handling, logging, CORS, compression, graceful shutdown, health checks, request ID tracking.
+
+#### Workflow
+
+**Step 1 — Audit middleware stack**
+Read the main server file (app.ts, server.ts, index.ts) to inventory all middleware in registration order. Check for: missing request ID generation, missing structured logging, inconsistent error responses, missing input validation, CORS misconfiguration (`*` in production).
+
+**Step 2 — Detect error handling gaps**
+Use Grep to find `catch` blocks, error middleware signatures (`err, req, res, next`), and unhandled promise rejections. Check if errors return consistent format (same envelope for 400, 401, 403, 404, 500). Flag any that leak stack traces or internal details in production.
+
+**Step 3 — Emit middleware improvements**
+For each gap, emit the middleware function: request ID (`X-Request-Id` header, UUID per request), structured JSON logger (request method, path, status, duration, request ID), global error handler with consistent envelope, Zod-based request validation middleware.
+
+**Step 4 — Compression strategy**
+Emit response compression middleware. Use `brotli` for static assets and pre-compressible responses (better ratio than gzip, supported by all modern clients). Use `gzip` as fallback for older clients. Conditional compression: skip for already-compressed content types (`image/*`, `video/*`, `application/zip`) — compressing these wastes CPU. In Express: use `compression` package with a `filter` function. In Fastify: `@fastify/compress` with `encodings: ['br', 'gzip']`. Minimum size threshold: do not compress responses < 1KB (overhead exceeds benefit).
+
+**Step 5 — Graceful shutdown and health checks**
+Graceful shutdown: on `SIGTERM`/`SIGINT`, stop accepting new connections, wait for in-flight requests to complete (timeout 30s), then close DB pools and exit. Emit the shutdown handler for Express (`server.close()`), Fastify (`fastify.close()`), and worker processes. Health check endpoints: `/health/live` (liveness — is the process alive? return 200 always unless process is broken), `/health/ready` (readiness — can it serve traffic? check DB connection, Redis connection, return 503 if dependencies are down). In Kubernetes: map liveness to `livenessProbe`, readiness to `readinessProbe`. Do NOT check external third-party APIs in readiness — only your own dependencies.
+
+#### Example
+
+```typescript
+// Request ID middleware
+const requestId = (req, res, next) => {
+  req.id = req.headers['x-request-id'] || crypto.randomUUID();
+  res.setHeader('X-Request-Id', req.id);
+  next();
+};
+
+// Structured error handler — consistent envelope, no stack leak
+const errorHandler = (err, req, res, _next) => {
+  const status = err.status || 500;
+  const message = status < 500 ? err.message : 'Internal server error';
+  logger.error({ err, requestId: req.id, path: req.path });
+  res.status(status).json({
+    error: { code: err.code || 'INTERNAL_ERROR', message },
+    request_id: req.id,
+  });
+};
+
+// Zod validation middleware
+const validate = (schema: z.ZodSchema) => (req, res, next) => {
+  const result = schema.safeParse({ body: req.body, query: req.query, params: req.params });
+  if (!result.success) {
+    return res.status(400).json({ error: { code: 'VALIDATION_ERROR', message: 'Invalid request', details: result.error.flatten() } });
+  }
+  Object.assign(req, result.data);
+  next();
+};
+
+// Compression with conditional skip (Express)
+import compression from 'compression';
+app.use(compression({
+  filter: (req, res) => {
+    const contentType = res.getHeader('Content-Type') as string || '';
+    if (/image|video|audio|zip|gz|br/.test(contentType)) return false;
+    return compression.filter(req, res);
+  },
+  threshold: 1024, // skip responses < 1KB
+}));
+
+// Graceful shutdown
+const gracefulShutdown = async (signal: string) => {
+  console.log(`Received ${signal}, shutting down gracefully...`);
+  server.close(async () => {
+    try {
+      await prisma.$disconnect();
+      await redis.quit();
+      console.log('All connections closed. Exiting.');
+      process.exit(0);
+    } catch (err) {
+      console.error('Error during shutdown:', err);
+      process.exit(1);
+    }
+  });
+  // Force exit after 30s if still not done
+  setTimeout(() => { console.error('Forced shutdown after timeout'); process.exit(1); }, 30_000);
+};
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+// Health check endpoints
+app.get('/health/live', (req, res) => res.json({ status: 'ok' }));
+
+app.get('/health/ready', async (req, res) => {
+  const checks = await Promise.allSettled([
+    prisma.$queryRaw`SELECT 1`,   // DB check
+    redis.ping(),                  // Redis check
+  ]);
+  const results = { db: checks[0].status, redis: checks[1].status };
+  const allHealthy = checks.every(c => c.status === 'fulfilled');
+  res.status(allHealthy ? 200 : 503).json({ status: allHealthy ? 'ready' : 'degraded', checks: results });
+});
+```