agent-skill-kit 3.9.135

package/.agent/skills/nodejs-pro/rules/error-handling.md

@@ -0,0 +1,257 @@
+---
+name: error-handling
+description: Centralized error handling — custom error classes, framework middleware, async patterns, and structured logging
+title: "Every error must be caught, classified, and communicated. No silent failures."
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: error, handling
+---
+
+# Error Handling
+
+> Every error must be caught, classified, and communicated. **No silent failures.**
+
+---
+
+## Custom Error Classes
+
+```typescript
+// errors/index.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public code: string,
+    public isOperational = true
+  ) {
+    super(message)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource = 'Resource') {
+    super(`${resource} not found`, 404, 'NOT_FOUND')
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, public details?: unknown) {
+    super(message, 422, 'VALIDATION_ERROR')
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string) {
+    super(message, 409, 'CONFLICT')
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401, 'UNAUTHORIZED')
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 403, 'FORBIDDEN')
+  }
+}
+```
+
+---
+
+## Framework Error Handlers
+
+### Fastify
+
+```typescript
+// Fastify handles async errors automatically — no try/catch needed!
+app.setErrorHandler((error, request, reply) => {
+  if (error instanceof AppError) {
+    reply.code(error.statusCode).send({
+      error: error.code,
+      message: error.message,
+      ...(error.details && { details: error.details })
+    })
+    return
+  }
+
+  // Unexpected error — log full details, send generic response
+  request.log.error(error)
+  reply.code(500).send({
+    error: 'INTERNAL_ERROR',
+    message: 'An unexpected error occurred'
+  })
+})
+```
+
+### Hono
+
+```typescript
+import { HTTPException } from 'hono/http-exception'
+
+// Global error handler
+app.onError((err, c) => {
+  if (err instanceof AppError) {
+    return c.json({
+      error: err.code,
+      message: err.message,
+    }, err.statusCode as any)
+  }
+
+  console.error('Unexpected error:', err)
+  return c.json({ error: 'INTERNAL_ERROR', message: 'Unexpected error' }, 500)
+})
+```
+
+### Express (requires wrapper)
+
+```typescript
+// Express does NOT handle async errors — you MUST wrap or use a library
+
+// Option 1: express-async-errors (recommended)
+import 'express-async-errors' // Import once at top
+
+// Option 2: Manual wrapper
+const asyncHandler = (fn: Function) => (req: Request, res: Response, next: NextFunction) =>
+  Promise.resolve(fn(req, res, next)).catch(next)
+
+app.get('/users/:id', asyncHandler(async (req, res) => {
+  const user = await getUser(req.params.id) // Errors auto-forwarded
+  res.json(user)
+}))
+
+// Error middleware (must be last, must have 4 params)
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({
+      error: err.code,
+      message: err.message
+    })
+    return
+  }
+
+  console.error('Unexpected error:', err)
+  res.status(500).json({ error: 'INTERNAL_ERROR', message: 'Unexpected error' })
+})
+```
+
+---
+
+## Error Response Format (Fixed)
+
+```typescript
+// Client gets:
+{
+  "error": "NOT_FOUND",           // Machine-readable code
+  "message": "User not found",    // Human-readable message
+  "details": { ... }              // Optional: validation details
+}
+
+// Client NEVER gets:
+// - Stack traces
+// - Internal file paths
+// - Database query details
+// - Environment variables
+```
+
+---
+
+## Status Code Selection
+
+| Situation | Status | Code | When |
+|-----------|:------:|------|------|
+| Bad input format | 400 | `BAD_REQUEST` | Malformed JSON, missing fields |
+| No auth | 401 | `UNAUTHORIZED` | Missing or invalid token |
+| No permission | 403 | `FORBIDDEN` | Valid auth, insufficient role |
+| Not found | 404 | `NOT_FOUND` | Resource doesn't exist |
+| Conflict | 409 | `CONFLICT` | Duplicate email, version conflict |
+| Validation | 422 | `VALIDATION_ERROR` | Schema valid but business rules fail |
+| Rate limited | 429 | `RATE_LIMITED` | Too many requests |
+| Server error | 500 | `INTERNAL_ERROR` | Our fault — log everything |
+
+---
+
+## Operational vs Programming Errors
+
+```
+Operational (expected, handle gracefully):
+├── User not found → 404
+├── Invalid input → 422
+├── Duplicate email → 409
+├── Rate limited → 429
+└── External API timeout → 503
+
+Programming (bugs, crash + restart):
+├── TypeError: Cannot read property of undefined
+├── RangeError: Array index out of bounds
+├── Unhandled promise rejection
+└── → Log, crash, let process manager restart
+```
+
+```typescript
+// Crash on programming errors — don't try to recover
+process.on('uncaughtException', (error) => {
+  console.error('UNCAUGHT EXCEPTION:', error)
+  process.exit(1) // Let PM2/Docker restart
+})
+
+process.on('unhandledRejection', (reason) => {
+  console.error('UNHANDLED REJECTION:', reason)
+  process.exit(1)
+})
+```
+
+---
+
+## Structured Logging
+
+```typescript
+// Use structured JSON logging (Pino is default in Fastify)
+import pino from 'pino'
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  ...(process.env.NODE_ENV === 'development' && {
+    transport: { target: 'pino-pretty' }
+  })
+})
+
+// Log context, not messages
+logger.error({ err, userId, requestId, path: req.url }, 'User fetch failed')
+// ✅ Structured, searchable in Datadog/CloudWatch
+
+// NOT: logger.error(`Error fetching user ${userId}: ${err.message}`)
+// ❌ String, unsearchable
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `try/catch` in every Express route | Use `express-async-errors` or Fastify |
+| Return stack traces to client | Return error code + message only |
+| `console.log` for errors | Use structured logger (Pino) |
+| Swallow errors (empty catch) | Always log or rethrow |
+| Generic `throw new Error('fail')` | Throw specific `AppError` subclass |
+| Recover from programming errors | Crash and restart (PM2/Docker) |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [architecture-patterns.md](architecture-patterns.md) | Where errors flow through layers |
+| [async-patterns.md](async-patterns.md) | Async error handling |
+| [validation-security.md](validation-security.md) | Validation errors at boundary |
+| [framework-selection.md](framework-selection.md) | Framework-specific error behavior |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/framework-selection.md

@@ -0,0 +1,220 @@
+---
+name: framework-selection
+description: Node.js framework decision criteria — Hono, Fastify, Express, NestJS with code examples, middleware, and migration paths
+title: "Framework Selection (2025)"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: framework, selection
+---
+
+# Framework Selection (2025)
+
+> Choose framework by deployment target and team context. **Never default to Express for new projects.**
+
+---
+
+## Decision Tree
+
+```
+What are you building?
+│
+├── Edge / Serverless (Cloudflare Workers, Vercel Edge, Deno Deploy)
+│   └── Hono
+│       ├── Zero dependencies, ~14KB
+│       ├── Fastest cold starts (~1ms)
+│       ├── Web Standards API (Request/Response)
+│       └── Runs on: CF Workers, Deno, Bun, Node.js, Lambda@Edge
+│
+├── High-Performance API (containers, VMs)
+│   └── Fastify
+│       ├── 2-3x faster than Express
+│       ├── JSON Schema validation built-in
+│       ├── Plugin-based architecture
+│       └── Best for: REST APIs, microservices
+│
+├── Enterprise / Large Team
+│   └── NestJS
+│       ├── Structured (modules, controllers, services)
+│       ├── Dependency Injection built-in
+│       ├── Decorators + TypeScript native
+│       └── Best for: large teams, enterprise apps
+│
+├── Legacy / Maximum Ecosystem
+│   └── Express
+│       ├── Largest middleware ecosystem
+│       ├── Most tutorials and examples
+│       └── Best for: maintaining existing apps
+│
+└── Full-Stack with Frontend
+    └── Next.js API Routes or tRPC
+```
+
+---
+
+## Comparison Matrix
+
+| Factor | Hono | Fastify | Express | NestJS |
+|--------|------|---------|---------|--------|
+| **Best for** | Edge, serverless | Performance | Legacy | Enterprise |
+| **Cold start** | ~1ms | ~50ms | ~100ms | ~200ms |
+| **Throughput** | ~150k req/s | ~78k req/s | ~15k req/s | ~12k req/s |
+| **TypeScript** | Native | Excellent | Good (DefinitelyTyped) | Native |
+| **Bundle size** | ~14KB | ~2MB | ~1.5MB | ~15MB |
+| **Learning curve** | Low | Medium | Low | High |
+| **Ecosystem** | Growing fast | Good | Largest | Good |
+| **DI built-in** | No | No | No | Yes |
+
+---
+
+## Hello World — Each Framework
+
+### Hono
+
+```typescript
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.get('/api/users/:id', async (c) => {
+  const id = c.req.param('id')
+  const user = await getUser(id)
+  if (!user) return c.json({ error: 'Not found' }, 404)
+  return c.json(user)
+})
+
+export default app // Works on CF Workers, Deno, Bun, Node.js
+```
+
+### Fastify
+
+```typescript
+import Fastify from 'fastify'
+
+const app = Fastify({ logger: true })
+
+app.get('/api/users/:id', {
+  schema: {
+    params: { type: 'object', properties: { id: { type: 'string' } } },
+    response: { 200: { type: 'object', properties: { name: { type: 'string' } } } }
+  }
+}, async (request, reply) => {
+  const user = await getUser(request.params.id)
+  if (!user) return reply.code(404).send({ error: 'Not found' })
+  return user // Auto-serialized via schema
+})
+
+await app.listen({ port: 3000 })
+```
+
+### Express
+
+```typescript
+import express from 'express'
+
+const app = express()
+app.use(express.json())
+
+app.get('/api/users/:id', async (req, res, next) => {
+  try {
+    const user = await getUser(req.params.id)
+    if (!user) return res.status(404).json({ error: 'Not found' })
+    res.json(user)
+  } catch (err) {
+    next(err) // Must manually forward errors
+  }
+})
+
+app.listen(3000)
+```
+
+### NestJS
+
+```typescript
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get(':id')
+  async findOne(@Param('id') id: string) {
+    const user = await this.usersService.findOne(id)
+    if (!user) throw new NotFoundException()
+    return user
+  }
+}
+```
+
+---
+
+## Middleware Comparison
+
+| Feature | Hono | Fastify | Express | NestJS |
+|---------|------|---------|---------|--------|
+| **Auth** | `hono/jwt` | `@fastify/jwt` | `passport` | `@nestjs/passport` |
+| **CORS** | `hono/cors` | `@fastify/cors` | `cors` | Built-in `enableCors()` |
+| **Rate limit** | `hono/rate-limiter` | `@fastify/rate-limit` | `express-rate-limit` | `@nestjs/throttler` |
+| **Validation** | Zod middleware | JSON Schema (built-in) | Zod/express-validator | class-validator (built-in) |
+| **Logging** | Built-in | Pino (built-in) | `morgan` | Built-in logger |
+| **Helmet** | `hono/secure-headers` | `@fastify/helmet` | `helmet` | `helmet` via Express adapter |
+
+---
+
+## Migration Paths
+
+### Express → Fastify
+
+```
+1. Replace app creation: express() → Fastify()
+2. Replace middleware: app.use() → app.register()
+3. Replace (req, res) → (request, reply)
+4. Replace res.json() → reply.send() (or just return)
+5. Add JSON schema for validation (optional but recommended)
+6. Remove try/catch in routes (Fastify handles async errors)
+```
+
+### Express → Hono
+
+```
+1. Replace app creation: express() → new Hono()
+2. Replace (req, res) → (c) context object
+3. Replace req.params.id → c.req.param('id')
+4. Replace res.json() → c.json()
+5. Remove body-parser middleware (Hono parses automatically)
+6. Test on target runtime (CF Workers, Bun, etc.)
+```
+
+---
+
+## Selection Questions (Ask Before Choosing)
+
+1. **Deployment target?** Edge → Hono. Container → Fastify. VM → any.
+2. **Cold start critical?** Yes → Hono or Fastify. No → any.
+3. **Team experience?** NestJS team → NestJS. Express team → consider migration to Fastify.
+4. **Project size?** Small → Hono. Medium → Fastify. Large → NestJS.
+5. **Existing codebase?** Express → keep or migrate gradually.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to Express for new projects | Choose by deployment target |
+| Use Express without error wrapper | Use Fastify (auto async) or express-async-errors |
+| Install 20 middleware packages | Choose framework with built-ins (Fastify, Hono) |
+| Choose NestJS for small API | Use Hono or Fastify for simplicity |
+| Ignore cold start for serverless | Benchmark cold start before choosing |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [architecture-patterns.md](architecture-patterns.md) | After framework chosen — structure the app |
+| [error-handling.md](error-handling.md) | Framework-specific error patterns |
+| [validation-security.md](validation-security.md) | Input validation per framework |
+| [runtime-modules.md](runtime-modules.md) | ESM/CJS module decisions |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/runtime-modules.md

@@ -0,0 +1,176 @@
+---
+name: runtime-modules
+description: Node.js runtime selection, ESM vs CJS, native TypeScript, node prefix, and module interop
+title: "Runtime & Module System"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: runtime, modules
+---
+
+# Runtime & Module System
+
+> Use ESM for new projects. Use `node:` prefix. Run TypeScript natively on Node.js 22+.
+
+---
+
+## Runtime Selection
+
+| Runtime | Best For | TypeScript | Package Manager |
+|---------|----------|-----------|----------------|
+| **Node.js** | General purpose, largest ecosystem | Via `--experimental-strip-types` (22+) or tsx | npm/pnpm/yarn |
+| **Bun** | Performance, scripts, built-in bundler | Native | bun |
+| **Deno** | Security-first, built-in TypeScript | Native | deno/npm |
+
+**Default recommendation:** Node.js 22+ (LTS) unless specific Bun/Deno features needed.
+
+---
+
+## Module System Decision
+
+| Factor | ESM (`import/export`) | CJS (`require/module.exports`) |
+|--------|----------------------|-------------------------------|
+| **Standard** | Modern (ECMAScript) | Legacy (Node.js original) |
+| **Tree-shaking** | ✅ Yes | ❌ No |
+| **Top-level await** | ✅ Yes | ❌ No |
+| **New projects** | ✅ Use this | ❌ Avoid |
+| **Existing codebases** | Migrate gradually | Keep if migration cost high |
+
+### ESM Setup
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+---
+
+## Native TypeScript (Node.js 22+)
+
+```bash
+# Run .ts directly — no build step
+node --experimental-strip-types src/app.ts
+
+# With type-checking (slower, for CI)
+npx tsx src/app.ts
+```
+
+**When to use native TS:**
+- Scripts and CLIs
+- Simple APIs
+- Development
+
+**When to use a build step:**
+- Production (compiled JS is faster to start)
+- Complex projects with path aliases
+- When you need decorators (NestJS)
+
+---
+
+## `node:` Prefix (Always Use)
+
+```typescript
+// ❌ Ambiguous — is this npm package or built-in?
+import { readFile } from 'fs/promises'
+import { join } from 'path'
+
+// ✅ Clear — this is a Node.js built-in
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { createServer } from 'node:http'
+```
+
+**Why?** Prevents name conflicts with npm packages. Makes imports instantly recognizable.
+
+---
+
+## Interop Gotchas
+
+### Importing CJS from ESM
+
+```typescript
+// ✅ Default imports usually work
+import express from 'express' // CJS library
+
+// ⚠️ Named imports may fail
+import { Router } from 'express' // May error in some setups
+
+// ✅ Safe alternative
+import express from 'express'
+const { Router } = express
+```
+
+### `__dirname` / `__filename` in ESM
+
+```typescript
+// ❌ Not available in ESM
+console.log(__dirname) // ReferenceError
+
+// ✅ ESM equivalent
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Or use import.meta directly (Node.js 21+)
+const configPath = new URL('./config.json', import.meta.url)
+```
+
+### `require()` in ESM
+
+```typescript
+// ❌ Not available in ESM
+const pkg = require('./package.json')
+
+// ✅ Use createRequire or import assertion
+import { createRequire } from 'node:module'
+const require = createRequire(import.meta.url)
+const pkg = require('./package.json')
+
+// ✅ Or import with assertion (Node.js 22+)
+import pkg from './package.json' with { type: 'json' }
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Start new projects with CJS | Use ESM (`"type": "module"`) |
+| Import built-ins without `node:` | Always `import from 'node:fs'` |
+| Mix ESM and CJS in same package | Pick one, migrate fully |
+| Use `__dirname` in ESM | Use `import.meta.url` |
+| Skip tsconfig `"strict": true` | Always enable strict mode |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [framework-selection.md](framework-selection.md) | Framework TypeScript support |
+| [async-patterns.md](async-patterns.md) | node: built-in async APIs |
+| [testing-strategy.md](testing-strategy.md) | node:test built-in runner |
+
+---
+
+⚡ PikaKit v3.9.134