forgehive 0.6.0

package/forgehive/skills/expert/gdpr-compliance.md

@@ -0,0 +1,64 @@
+# GDPR-Compliant Coding Patterns
+
+## Core Principles (Art. 5 GDPR)
+
+| Principle | Implementation |
+|-----------|---------------|
+| Lawfulness, fairness, transparency | Consent records, privacy notices |
+| Purpose limitation | Separate schemas per data use |
+| Data minimisation | Collect only what's needed |
+| Accuracy | Update mechanisms, validation |
+| Storage limitation | Retention policies, automatic deletion |
+| Integrity & confidentiality | Encryption, access control |
+| Accountability | Audit logs |
+
+---
+
+## PII Data Classification
+
+```typescript
+type PiiCategory =
+  | "DIRECT_IDENTIFIER"    // name, email, NIN, passport
+  | "QUASI_IDENTIFIER"     // DOB, postcode, gender
+  | "SENSITIVE_SPECIAL"    // health, biometric, race, religion (Art. 9)
+  | "FINANCIAL"            // IBAN, card numbers
+  | "BEHAVIORAL"           // browsing history, location traces
+  | "NONE";
+```
+
+---
+
+## Right to Erasure (Art. 17)
+
+```typescript
+export async function eraseUserData(db: Database, userId: string): Promise<void> {
+  // 1. Anonymize user record (don't delete if referenced by orders etc.)
+  await db.users.update({
+    where: { id: userId },
+    data: {
+      email: `deleted-${userId}@erasure.invalid`,
+      name: "Deleted User",
+      deletedAt: new Date(),
+    },
+  });
+  // 2. Delete personally identifiable child records
+  await db.addresses.deleteMany({ where: { userId } });
+  await db.sessions.deleteMany({ where: { userId } });
+  // 3. Log the erasure (keep audit trail even without PII)
+  await db.erasureLog.create({ data: { userId, erasedAt: new Date() } });
+}
+```
+
+---
+
+## GDPR Checklist for New Features
+
+- [ ] Lawful basis for processing defined
+- [ ] Data minimised — only collect what's needed
+- [ ] Retention period defined and enforced
+- [ ] Data encrypted at rest (Art. 9 special categories)
+- [ ] Access controls in place
+- [ ] Processing documented in data register
+- [ ] Erasure endpoint handles this data
+- [ ] Privacy notice updated
+- [ ] DPIA completed if high risk (Art. 35)

package/forgehive/skills/expert/git-conventions.md

@@ -0,0 +1,84 @@
+# Git Conventions
+
+## Commit Messages (Conventional Commits)
+
+```
+<type>(<scope>): <short description>
+
+[optional body — wrap at 72 chars]
+
+[optional footer: BREAKING CHANGE, Closes #123]
+```
+
+**Types:**
+
+| Type | When |
+|---|---|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `chore` | Build, deps, config (no code change) |
+| `refactor` | Code change without feature/fix |
+| `test` | Adding/fixing tests |
+| `docs` | Documentation only |
+| `perf` | Performance improvement |
+| `ci` | CI/CD changes |
+
+**Rules:**
+- Imperative mood: "add" not "added", "fix" not "fixes"
+- No period at end of subject line
+- Subject ≤ 72 chars
+- Body explains WHY, not what (the diff shows what)
+
+## Branch Naming
+
+```
+feat/user-authentication
+fix/login-redirect-loop
+chore/upgrade-dependencies
+refactor/extract-auth-middleware
+```
+
+## Workflow
+
+```
+main (protected)
+  └── feat/my-feature
+        ├── commit: feat: add login form
+        ├── commit: test: add login form tests
+        └── PR → squash merge to main
+```
+
+- Work on feature branches — never directly on `main`
+- Keep branches short-lived (days, not weeks)
+- Squash merge for features, merge commit for releases
+
+## Good Commit Habits
+
+- One logical change per commit (atomic)
+- Green tests before committing
+- `git add -p` for partial staging when you changed multiple things
+- `git commit --fixup` for small corrections before push
+
+## PR Description Template
+
+```markdown
+## What
+[1-2 sentences: what changed]
+
+## Why
+[motivation, ticket link]
+
+## Test Plan
+- [ ] Unit tests added/updated
+- [ ] Smoke tested locally
+```
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| "WIP", "fix", "asdf" commits | Meaningless history |
+| 1000-line commits | Hard to review, hard to bisect |
+| `git push --force` on shared branches | Rewrites shared history |
+| Committing generated files | Noise, conflicts |
+| Committing secrets | Permanent in history |

package/forgehive/skills/expert/monorepo-patterns.md

@@ -0,0 +1,91 @@
+# Monorepo Patterns
+
+## When to Use a Monorepo
+
+Use when packages share code, have coordinated releases, or need atomic cross-package changes. Don't use just because you have multiple services — separate repos are fine for fully independent teams.
+
+## Structure
+
+```
+packages/
+  core/          ← shared domain types, utilities
+  api/           ← backend service
+  web/           ← frontend app
+  cli/           ← command-line tool
+apps/            ← deployable applications (thin, import from packages)
+tools/           ← internal scripts, generators
+package.json     ← workspaces config
+turbo.json       ← build orchestration (if using Turborepo)
+```
+
+## Workspace Setup (npm/pnpm)
+
+```json
+// root package.json
+{
+  "workspaces": ["packages/*", "apps/*"],
+  "scripts": {
+    "build": "turbo build",
+    "test": "turbo test",
+    "lint": "turbo lint"
+  }
+}
+```
+
+## Package Boundaries
+
+```typescript
+// packages/core/index.ts — explicit public API
+export type { User, Order, Money };
+export { parseConfig } from "./config.ts";
+// Don't export internal helpers
+
+// packages/api/src/service.ts
+import { User } from "@company/core"; // ✅ use workspace package
+import { helper } from "../../../core/src/internal"; // ❌ bypass boundary
+```
+
+## Dependency Management
+
+- Hoist shared dev dependencies to root
+- Keep runtime deps in each package (visibility)
+- Use `workspace:*` protocol for internal deps
+
+```json
+// packages/api/package.json
+{
+  "dependencies": {
+    "@company/core": "workspace:*",
+    "express": "^4.18"
+  }
+}
+```
+
+## Build Order
+
+Turborepo / Nx handle this with task graphs:
+```json
+// turbo.json
+{
+  "pipeline": {
+    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
+    "test": { "dependsOn": ["build"] }
+  }
+}
+```
+
+## CI Strategy
+
+- Cache build artifacts by content hash
+- Run only affected packages on PR: `turbo run test --filter=[HEAD^1]`
+- Full build on merge to main
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| Circular package dependencies | Build order impossible |
+| Importing internal paths across packages | Bypasses public API |
+| One giant `packages/shared` | Becomes a dumping ground |
+| Versioning each package independently | Defeats coordination benefits |
+| No build cache | CI takes 20min for every change |

package/forgehive/skills/expert/observability.md

@@ -0,0 +1,98 @@
+# Observability
+
+## Three Pillars
+
+| Pillar | What | Tool examples |
+|---|---|---|
+| Logs | What happened | Winston, Pino, Datadog |
+| Metrics | How much / how fast | Prometheus, Datadog |
+| Traces | Where time was spent | OpenTelemetry, Jaeger |
+
+## Structured Logging
+
+```typescript
+// ✅ Structured — queryable, filterable
+log.info("user.login", { userId, ip, duration_ms: 45, success: true });
+
+// ❌ String interpolation — unsearchable
+console.log(`User ${userId} logged in from ${ip} in 45ms`);
+```
+
+**Log Levels:**
+
+| Level | When |
+|---|---|
+| `error` | Something broke — requires action |
+| `warn` | Unexpected but handled |
+| `info` | Key business events (login, purchase, deploy) |
+| `debug` | Detailed flow for troubleshooting (not in prod) |
+
+**Never log:** passwords, tokens, PII, full request bodies with secrets.
+
+## Metrics to Track
+
+**RED Method** (for services):
+- **R**ate — requests per second
+- **E**rrors — error rate (%)
+- **D**uration — latency (p50, p95, p99)
+
+**USE Method** (for infrastructure):
+- **U**tilization — CPU/memory/disk %
+- **S**aturation — queue depth, wait time
+- **E**rrors — hardware/kernel errors
+
+## OpenTelemetry (Node.js)
+
+```typescript
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-service");
+
+async function processOrder(orderId: string) {
+  const span = tracer.startSpan("processOrder");
+  span.setAttribute("order.id", orderId);
+
+  try {
+    await doWork(orderId);
+    span.setStatus({ code: SpanStatusCode.OK });
+  } catch (err) {
+    span.recordException(err as Error);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+```
+
+## Alerting
+
+- Alert on symptoms (high error rate, slow responses), not causes
+- Every alert must have a runbook
+- PagerDuty for P1/P2 (revenue impact, data loss risk)
+- Slack for P3/P4 (degraded, not down)
+- Alert fatigue = ignored alerts = missed incidents
+
+## Health Endpoints
+
+```typescript
+// Liveness: is the process alive?
+app.get("/health/live", (req, res) => res.json({ status: "ok" }));
+
+// Readiness: can it serve traffic?
+app.get("/health/ready", async (req, res) => {
+  const dbOk = await db.ping().then(() => true).catch(() => false);
+  if (!dbOk) return res.status(503).json({ status: "not ready", db: false });
+  res.json({ status: "ok", db: true });
+});
+```
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| `console.log` in production | No structure, no log level, no context |
+| Logging every function entry/exit | Noise drowns signal |
+| Metrics without dashboards | Data no one looks at |
+| Alerting on causes (`cpu > 80%`) | Noisy, doesn't map to user impact |
+| No correlation IDs | Can't trace a request across services |

package/forgehive/skills/expert/owasp-top10.md

@@ -0,0 +1,153 @@
+# OWASP Top 10 — Security Patterns for Node.js/TypeScript
+
+## Overview
+
+This skill covers the OWASP Top 10 (2021) vulnerability categories with detection
+patterns and remediation examples in TypeScript/Node.js.
+
+---
+
+## A01: Broken Access Control
+
+**Risk:** Users can act outside their intended permissions.
+
+**Detection patterns:**
+- Missing authorization checks before database queries
+- Direct object references using user-supplied IDs without ownership verification
+- CORS misconfiguration allowing all origins
+
+**Vulnerable:**
+```typescript
+// ❌ No ownership check
+app.get("/documents/:id", authenticate, async (req, res) => {
+  const doc = await db.documents.findById(req.params.id);
+  res.json(doc);
+});
+```
+
+**Secure:**
+```typescript
+// ✅ Verify ownership
+app.get("/documents/:id", authenticate, async (req, res) => {
+  const doc = await db.documents.findOne({
+    _id: req.params.id,
+    ownerId: req.user.id,
+  });
+  if (!doc) return res.status(404).json({ error: "Not found" });
+  res.json(doc);
+});
+```
+
+---
+
+## A02: Cryptographic Failures
+
+**Risk:** Sensitive data exposed due to weak or missing encryption.
+
+**Detection patterns:**
+- `MD5` or `SHA1` for password hashing
+- Sensitive data in plaintext
+- Weak JWT secrets
+
+**Vulnerable:**
+```typescript
+// ❌ MD5 not suitable for passwords
+const hash = crypto.createHash("md5").update(password).digest("hex");
+```
+
+**Secure:**
+```typescript
+// ✅ Use bcrypt for passwords
+import bcrypt from "bcrypt";
+const hash = await bcrypt.hash(password, 12);
+```
+
+---
+
+## A03: Injection
+
+**Risk:** Untrusted data sent to an interpreter as part of a command or query.
+
+**Vulnerable:**
+```typescript
+// ❌ SQL injection
+const rows = await db.query(`SELECT * FROM users WHERE email = '${req.body.email}'`);
+```
+
+**Secure:**
+```typescript
+// ✅ Parameterized queries
+const rows = await db.query("SELECT * FROM users WHERE email = $1", [req.body.email]);
+```
+
+---
+
+## A04: Insecure Design
+
+**Checklist:**
+- [ ] Threat model for sensitive flows
+- [ ] Rate limiting on public endpoints
+- [ ] Business logic validated server-side
+
+---
+
+## A05: Security Misconfiguration
+
+**Secure Express setup:**
+```typescript
+import helmet from "helmet";
+app.use(helmet());
+app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(",") ?? [] }));
+```
+
+---
+
+## A06: Vulnerable and Outdated Components
+
+```bash
+npm audit
+fh security deps
+```
+
+---
+
+## A07: Identification and Authentication Failures
+
+**Secure JWT:**
+```typescript
+const token = jwt.sign({ userId }, JWT_SECRET, { expiresIn: "15m" });
+```
+
+---
+
+## A08: Software and Data Integrity Failures
+
+- Verify npm package integrity with `npm audit`
+- Use lockfiles (`package-lock.json`)
+- Pin dependencies in production
+
+---
+
+## A09: Security Logging and Monitoring Failures
+
+```typescript
+// Log security events
+fh security audit
+```
+
+---
+
+## A10: Server-Side Request Forgery (SSRF)
+
+**Vulnerable:**
+```typescript
+// ❌ Fetch user-controlled URL
+const data = await fetch(req.body.url);
+```
+
+**Secure:**
+```typescript
+// ✅ Validate URL against allowlist
+const allowed = new URL(req.body.url);
+if (!ALLOWED_HOSTS.includes(allowed.hostname)) throw new Error("Blocked");
+```

package/forgehive/skills/expert/performance-patterns.md

@@ -0,0 +1,79 @@
+# Performance Patterns
+
+## Measure First
+
+Never optimize without data. Profile before you guess.
+
+```bash
+# Node.js profiling
+node --prof app.js
+node --prof-process isolate-*.log
+
+# Simple timing
+console.time("operation");
+await heavyOperation();
+console.timeEnd("operation");
+```
+
+## Database
+
+**The N+1 Problem:**
+```typescript
+// ❌ N+1: 1 query for posts + N queries for authors
+const posts = await db.posts.findMany();
+for (const post of posts) {
+  post.author = await db.users.findById(post.authorId); // N queries
+}
+
+// ✅ 1 query with JOIN or 2 queries with batch load
+const posts = await db.posts.findMany({ include: { author: true } });
+```
+
+**Indexing:**
+- Index foreign keys and columns used in WHERE, ORDER BY
+- Composite indexes: column order matters (most selective first)
+- Check `EXPLAIN ANALYZE` for slow queries
+
+**Pagination:** Always paginate large result sets — never `SELECT *` without `LIMIT`.
+
+## Caching
+
+```typescript
+// Cache expensive computations
+const cache = new Map<string, { data: T; expires: number }>();
+
+function cached<T>(key: string, ttlMs: number, fn: () => Promise<T>): Promise<T> {
+  const hit = cache.get(key);
+  if (hit && Date.now() < hit.expires) return Promise.resolve(hit.data);
+  return fn().then(data => { cache.set(key, { data, expires: Date.now() + ttlMs }); return data; });
+}
+```
+
+Cache at the right layer: HTTP (CDN/ETag), application (Redis), DB (query cache).
+
+## Async / Concurrency
+
+```typescript
+// ❌ Sequential when parallel is possible
+const user = await getUser(id);
+const prefs = await getPrefs(id);
+
+// ✅ Parallel
+const [user, prefs] = await Promise.all([getUser(id), getPrefs(id)]);
+```
+
+## Bundle Size (Frontend)
+
+- Code splitting: lazy-load routes and heavy components
+- Tree shaking: named imports only (`import { fn } from "lib"`)
+- Analyze: `npx source-map-explorer dist/*.js`
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| Premature optimization | Adds complexity for imaginary gains |
+| Synchronous I/O in async context | Blocks event loop |
+| Loading all records into memory | OOM on large datasets |
+| Polling every 100ms | Use webhooks or SSE instead |
+| Re-fetching uncached data on every render | Stale-while-revalidate pattern |

package/forgehive/skills/expert/security-checklist.md

@@ -0,0 +1,70 @@
+# Security Checklist
+
+## Input Validation (OWASP Top 10 — A03)
+
+- [ ] Validate all input at the boundary (type, length, format, range)
+- [ ] Use allowlist validation, not denylist
+- [ ] Sanitize before storing, escape before rendering
+- [ ] Never trust user-controlled data in SQL, shell commands, file paths
+
+```typescript
+// Parameterized queries — never string interpolation
+const user = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
+
+// Path traversal prevention
+const safe = path.resolve(baseDir, userInput);
+if (!safe.startsWith(baseDir)) throw new ForbiddenError();
+```
+
+## Authentication & Authorization
+
+- [ ] Passwords: bcrypt/argon2 (never MD5/SHA1), min 12 chars
+- [ ] Sessions: HttpOnly, Secure, SameSite=Strict cookies
+- [ ] JWT: verify signature + expiry, short-lived access tokens
+- [ ] Check authorization on every request — don't rely on UI hiding
+- [ ] Rate limit auth endpoints (login, password reset, OTP)
+
+## Secrets Management
+
+- [ ] Never hardcode secrets in source code
+- [ ] Use env vars for config — never `.env` files in production
+- [ ] Rotate secrets regularly; revoke on any exposure
+- [ ] Secrets in logs? Redact them.
+
+```typescript
+// ✅ Safe logging
+log.info("request", { userId, endpoint }); // no token
+
+// ❌ Never
+log.info("auth", { token: req.headers.authorization });
+```
+
+## Dependencies
+
+- [ ] `npm audit` before every release
+- [ ] Pin major versions in production
+- [ ] Review changelogs for security advisories when upgrading
+- [ ] Remove unused dependencies
+
+## HTTP Security Headers
+
+```typescript
+// Minimum set for web APIs
+res.setHeader("X-Content-Type-Options", "nosniff");
+res.setHeader("X-Frame-Options", "DENY");
+res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+res.setHeader("Content-Security-Policy", "default-src 'none'");
+```
+
+## Error Responses
+
+- [ ] Never expose stack traces to clients
+- [ ] Generic error messages in production (log details server-side)
+- [ ] Consistent error format (don't leak internal structure)
+
+## Data
+
+- [ ] Encrypt sensitive data at rest (PII, payment info)
+- [ ] TLS everywhere in transit
+- [ ] Minimal data collection — don't store what you don't need
+- [ ] GDPR: deletion capability, data export capability