agent-skill-kit 3.9.135

package/.agent/skills/nodejs-pro/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: nodejs-pro
+description: >-
+  Node.js backend development with Hono, Fastify, Express, or NestJS.
+  Use when building APIs, servers, backend logic, or choosing Node.js frameworks.
+  NOT for frontend code (use react-pro) or database schema (use data-modeler).
+category: backend-architect
+triggers: ["Node.js", "Express", "Fastify", "Hono", "backend", "server", "API"]
+coordinates_with: ["api-architect", "data-modeler", "auth-patterns", "problem-checker", "knowledge-compiler", "typescript-expert"]
+success_metrics: ["0 Security Vulnerabilities", "0 IDE/Lint Errors", "0 Unhandled Promise Rejections"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Node.js Pro — Backend Decision Framework
+
+> 5 frameworks. Async-first. Validate at boundary. No sync in production.
+
+**Philosophy:** Learn to THINK, not memorize. Choose framework by context.
+
+---
+
+## 5 Must-Ask Questions (Before Any Development)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Who are the Consumers? | SPA, mobile, third-party, internal |
+| 2 | Runtime / Target? | Edge (Hono/Bun), Node.js, Serverless |
+| 3 | Framework Preference? | Hono, Fastify, Express, NestJS |
+| 4 | Database & ORM? | PostgreSQL/Neon, Turso/SQLite, Prisma/Drizzle |
+| 5 | Authentication? | JWT, Session, OAuth2, None |
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Choosing Node.js framework | Use framework decision tree |
+| Building API | Check framework comparison |
+| Edge/serverless deployment | Consider Hono |
+| Enterprise w/ large team | Consider NestJS |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Framework selection (5 options) | API design (→ api-architect) |
+| Architecture routing | Database/ORM (→ data-modeler) |
+| Async pattern guidance | TypeScript patterns (→ typescript-expert) |
+| Error handling strategy | Performance profiling (→ perf-optimizer) |
+
+**Expert decision skill:** Produces framework decisions and pattern guidance. Does not write code.
+
+---
+
+## Framework Decision Tree (Deterministic)
+
+```
+What are you building?
+├── Edge / Serverless → Hono (fastest cold starts)
+├── High-performance API → Fastify (2-3x faster than Express)
+├── Enterprise / Large team → NestJS (structured, DI)
+├── Legacy / Max ecosystem → Express
+└── Full-stack → Next.js API Routes or tRPC
+```
+
+---
+
+## Framework Comparison (Fixed)
+
+| Factor | Hono | Fastify | Express | NestJS |
+|--------|------|---------|---------|--------|
+| **Best for** | Edge, serverless | Performance | Legacy | Enterprise |
+| **Cold start** | Fastest | Fast | Moderate | Moderate |
+| **TypeScript** | Native | Excellent | Good | Native |
+| **Throughput** | Highest | High | Baseline | Moderate |
+
+---
+
+## Core Principles (Fixed)
+
+| Principle | Enforcement |
+|-----------|-------------|
+| Async-first | No `*Sync()` methods in production |
+| Validate at boundary | All inputs validated before business logic |
+| Secrets via env vars | Never hardcode credentials |
+| Layered separation | Controllers → Services → Repositories |
+| Event loop protection | CPU work → worker threads |
+| No `eval()` / `Function()` | Never in production |
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `architecture_decision` | `{"runtime": "nodejs|edge", "framework": "..."}` | `INFO` |
+| `framework_selection` | `{"reason": "...", "database": "..."}` | `INFO` |
+| `build_verification` | `{"status": "pass|fail", "metrics_met": true}` | `INFO` |
+
+All executions MUST emit the `build_verification` span before reporting completion.
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_UNKNOWN_TARGET` | Yes | Deployment target not recognized |
+| `ERR_UNKNOWN_FRAMEWORK` | Yes | Framework not one of 5 |
+
+**Zero internal retries.** Deterministic; same context = same recommendation.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to Express for new projects | Choose framework by deployment target |
+| Use sync methods in production | Always use async/await |
+| Put business logic in controllers | Use layered architecture |
+| Skip input validation | Validate all inputs at boundary |
+| Block event loop with CPU work | Use worker threads |
+| Hardcode secrets | Use environment variables |
+| Ignore IDE warnings/errors | Call `problem-checker` to auto-fix |
+
+---
+
+## Decision Checklist
+
+- [ ] Asked user about stack preference?
+- [ ] Chosen framework for THIS context (not default)?
+- [ ] Considered deployment target (edge/container/VM)?
+- [ ] Planned error handling strategy?
+- [ ] Identified input validation points?
+- [ ] Considered security requirements?
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [framework-selection.md](rules/framework-selection.md) | Framework decision criteria | Choosing framework |
+| [runtime-modules.md](rules/runtime-modules.md) | Runtime & module system | Module decisions |
+| [architecture-patterns.md](rules/architecture-patterns.md) | Architecture patterns | Structuring app |
+| [error-handling.md](rules/error-handling.md) | Error handling patterns | Error strategy |
+| [async-patterns.md](rules/async-patterns.md) | Async patterns | Async code |
+| [validation-security.md](rules/validation-security.md) | Validation & security | Security planning |
+| [testing-strategy.md](rules/testing-strategy.md) | Testing patterns | Test planning |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+**Selective reading:** Read ONLY the file relevant to current decision.
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `api-architect` | Skill | API design |
+| `data-modeler` | Skill | Database patterns |
+| `typescript-expert` | Skill | TypeScript |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/_sections.md

@@ -0,0 +1,50 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Architecture (architecture)
+
+**Impact:** LOW  
+**Description:** Architecture patterns and best practices.
+
+## 2. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+## 3. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 4. Error (error)
+
+**Impact:** LOW  
+**Description:** Error patterns and best practices.
+
+## 5. Framework (framework)
+
+**Impact:** LOW  
+**Description:** Framework patterns and best practices.
+
+## 6. Runtime (runtime)
+
+**Impact:** LOW  
+**Description:** Runtime patterns and best practices.
+
+## 7. Testing (testing)
+
+**Impact:** LOW  
+**Description:** Testing patterns and best practices.
+
+## 8. Validation (validation)
+
+**Impact:** LOW  
+**Description:** Validation patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/architecture-patterns.md

@@ -0,0 +1,229 @@
+---
+name: architecture-patterns
+description: Layered architecture — Controller/Service/Repository with code examples, DI, project structure, and anti-patterns
+title: "Layered separation is not bureaucracy — it's testability, swappability, and clarity."
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: architecture, patterns
+---
+
+# Architecture Patterns
+
+> Layered separation is not bureaucracy — it's testability, swappability, and clarity.
+
+---
+
+## Layered Architecture
+
+```
+Request Flow:
+│
+├── Route / Controller Layer
+│   ├── Handles HTTP specifics (status codes, headers)
+│   ├── Input validation at boundary
+│   ├── Calls service layer
+│   └── NEVER contains business logic
+│
+├── Service Layer
+│   ├── Business logic
+│   ├── Framework-agnostic (no req/res)
+│   ├── Calls repository layer
+│   └── Orchestrates workflows
+│
+└── Repository Layer
+    ├── Data access only
+    ├── Database queries (Drizzle, Prisma)
+    └── Returns domain objects
+```
+
+---
+
+## Code Example — Layered Pattern
+
+### Repository (data access)
+
+```typescript
+// repositories/user.repository.ts
+import { db } from '../db'
+import { users } from '../db/schema'
+import { eq } from 'drizzle-orm'
+
+export class UserRepository {
+  async findById(id: string) {
+    return db.query.users.findFirst({ where: eq(users.id, id) })
+  }
+
+  async findByEmail(email: string) {
+    return db.query.users.findFirst({ where: eq(users.email, email) })
+  }
+
+  async create(data: { email: string; name: string }) {
+    const [user] = await db.insert(users).values(data).returning()
+    return user
+  }
+}
+```
+
+### Service (business logic)
+
+```typescript
+// services/user.service.ts
+import { UserRepository } from '../repositories/user.repository'
+
+export class UserService {
+  constructor(private repo: UserRepository) {}
+
+  async getUser(id: string) {
+    const user = await this.repo.findById(id)
+    if (!user) throw new NotFoundError('User not found')
+    return user
+  }
+
+  async createUser(data: { email: string; name: string }) {
+    const existing = await this.repo.findByEmail(data.email)
+    if (existing) throw new ConflictError('Email already registered')
+    return this.repo.create(data)
+  }
+}
+```
+
+### Controller (HTTP layer)
+
+```typescript
+// Fastify example
+// controllers/user.controller.ts
+import { UserService } from '../services/user.service'
+
+export function userRoutes(app: FastifyInstance, service: UserService) {
+  app.get('/users/:id', async (request, reply) => {
+    const user = await service.getUser(request.params.id)
+    return user
+  })
+
+  app.post('/users', async (request, reply) => {
+    const user = await service.createUser(request.body)
+    return reply.code(201).send(user)
+  })
+}
+```
+
+```typescript
+// Hono example
+import { Hono } from 'hono'
+import { UserService } from '../services/user.service'
+
+export function userRoutes(service: UserService) {
+  const app = new Hono()
+
+  app.get('/:id', async (c) => {
+    const user = await service.getUser(c.req.param('id'))
+    return c.json(user)
+  })
+
+  app.post('/', async (c) => {
+    const body = await c.req.json()
+    const user = await service.createUser(body)
+    return c.json(user, 201)
+  })
+
+  return app
+}
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├── controllers/        # Route handlers (HTTP-specific)
+│   ├── user.controller.ts
+│   └── product.controller.ts
+├── services/           # Business logic (framework-agnostic)
+│   ├── user.service.ts
+│   └── product.service.ts
+├── repositories/       # Data access (DB queries)
+│   ├── user.repository.ts
+│   └── product.repository.ts
+├── middleware/          # Auth, validation, logging
+│   ├── auth.ts
+│   └── validate.ts
+├── db/                 # Database config + schema
+│   ├── index.ts        # Connection
+│   ├── schema.ts       # Drizzle/Prisma schema
+│   └── migrations/
+├── errors/             # Custom error classes
+│   └── index.ts
+├── types/              # Shared TypeScript types
+│   └── index.ts
+├── utils/              # Pure utility functions
+│   └── index.ts
+└── app.ts              # App setup + route registration
+```
+
+---
+
+## Dependency Injection (Simple)
+
+```typescript
+// di.ts — Manual DI (no framework needed)
+import { UserRepository } from './repositories/user.repository'
+import { UserService } from './services/user.service'
+
+// Create instances once
+const userRepo = new UserRepository()
+const userService = new UserService(userRepo)
+
+export { userService }
+```
+
+```typescript
+// app.ts
+import { userService } from './di'
+import { userRoutes } from './controllers/user.controller'
+
+const app = Fastify()
+userRoutes(app, userService)
+```
+
+**Why manual DI?** Simple, testable, no magic. For NestJS, use built-in DI. For small projects, this is enough.
+
+---
+
+## When to Simplify
+
+| Project Size | Architecture |
+|-------------|-------------|
+| Script / CLI | Single file |
+| Small API (< 5 routes) | Routes + services (skip repo layer) |
+| Medium API (5-20 routes) | Full 3-layer + manual DI |
+| Large / Enterprise | NestJS with modules + built-in DI |
+| Microservice | 3-layer per service, shared types package |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Business logic in controllers | Service layer handles all logic |
+| `req`/`res` in service layer | Services are framework-agnostic |
+| Direct DB calls in controllers | Repository pattern |
+| God service (1000+ lines) | Split by domain (UserService, OrderService) |
+| Circular dependencies | Unidirectional: Controller → Service → Repository |
+| Over-engineering small APIs | Match architecture to project size |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [framework-selection.md](framework-selection.md) | Choose framework first |
+| [error-handling.md](error-handling.md) | Error classes for service layer |
+| [testing-strategy.md](testing-strategy.md) | Testing each layer independently |
+| [validation-security.md](validation-security.md) | Middleware validation patterns |
+
+---
+
+⚡ PikaKit v3.9.134