start-vibing-stacks 2.6.0 → 2.7.0

package/stacks/_shared/skills/error-handling/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: error-handling
+version: 1.0.0
+description: Universal error-handling patterns. Error taxonomy, Result types, error boundaries, structured exceptions, never-swallow rules. Invoke when designing service layers, API responses, or any try/catch.
+---
+
+# Error Handling
+
+**ALWAYS invoke when adding try/catch, designing service layers, API error responses, or handling external API failures.**
+
+> The default state of software is broken. Errors are not exceptional — handling them is the job.
+
+## Core Principles
+
+1. **Errors are values.** Plan for them in the type signature, not as a side channel.
+2. **Throw at boundaries, return at edges.** Internal modules return Results; HTTP layer translates to status codes; user sees a generic message.
+3. **Never swallow.** A `catch` with no log, no rethrow, and no recovery is a bug.
+4. **Fail closed.** On unexpected error, deny — don't continue with degraded state.
+5. **Distinguish operational from programmer errors.** Operational = expected (network blip, validation). Programmer = bug. They get different treatment.
+
+---
+
+## Error Taxonomy (mandatory)
+
+Every error you create classifies into one of these:
+
+| Class | Examples | Strategy |
+|---|---|---|
+| **Validation** | Bad input, schema mismatch | Return 4xx with field details; do not log as error |
+| **Authentication** | Missing/expired/invalid token | 401, log at info |
+| **Authorization** | Authenticated but not allowed | 403, log at warn (could be probing) |
+| **NotFound** | Resource missing | 404, log at info |
+| **Conflict** | Optimistic lock, duplicate key | 409, log at warn |
+| **RateLimit** | Quota exceeded | 429 + `Retry-After`, log at info |
+| **External** | Upstream API failed | Retry+backoff if idempotent; 502/503; log at error |
+| **Programmer** | Null deref, type mismatch, switch missed | 500, log at error, alert, fix |
+
+If the error doesn't fit, you have a new class — add it deliberately.
+
+---
+
+## Pattern 1 — Custom Error Classes (TS / Python / PHP)
+
+### TypeScript
+```ts
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly httpStatus: number,
+    message: string,
+    public readonly cause?: unknown,
+    public readonly meta?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, fields?: Record<string, string[]>) {
+    super('validation_error', 422, message, undefined, { fields });
+  }
+}
+export class NotFoundError extends AppError {
+  constructor(resource: string) { super('not_found', 404, `${resource} not found`); }
+}
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') { super('unauthorized', 401, message); }
+}
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') { super('forbidden', 403, message); }
+}
+export class ConflictError extends AppError {
+  constructor(message: string) { super('conflict', 409, message); }
+}
+export class ExternalError extends AppError {
+  constructor(service: string, cause: unknown) {
+    super('external_error', 502, `Upstream ${service} failed`, cause);
+  }
+}
+```
+
+### Python
+```python
+class AppError(Exception):
+    code: str = "error"
+    http_status: int = 500
+    def __init__(self, message: str, *, cause: Exception | None = None, meta: dict | None = None):
+        super().__init__(message)
+        self.cause, self.meta = cause, meta or {}
+
+class ValidationError(AppError):  code, http_status = "validation_error", 422
+class NotFoundError(AppError):    code, http_status = "not_found", 404
+class UnauthorizedError(AppError):code, http_status = "unauthorized", 401
+class ForbiddenError(AppError):   code, http_status = "forbidden", 403
+class ConflictError(AppError):    code, http_status = "conflict", 409
+class ExternalError(AppError):    code, http_status = "external_error", 502
+```
+
+### PHP
+Use Laravel's `HttpException` family + custom domain exceptions. Override `Handler::register` to map domain exceptions to HTTP responses.
+
+---
+
+## Pattern 2 — Result Types (for internal layers)
+
+Throwing across many layers is expensive (TypeScript) and opaque (it's not in the signature). For internal service code, use a Result.
+
+### TypeScript
+```ts
+type Result<T, E = AppError> =
+  | { ok: true;  data: T }
+  | { ok: false; error: E };
+
+const ok = <T>(data: T): Result<T> => ({ ok: true, data });
+const err = <E extends AppError>(error: E): Result<never, E> => ({ ok: false, error });
+
+// Service returns Result; caller handles both branches
+async function findUser(id: string): Promise<Result<User>> {
+  const user = await db.user.findById(id);
+  if (!user) return err(new NotFoundError('user'));
+  return ok(user);
+}
+
+// Caller (route handler) — throws to be caught by error middleware
+const result = await findUser(id);
+if (!result.ok) throw result.error;
+return result.data;
+```
+
+### Python
+```python
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+T = TypeVar("T"); E = TypeVar("E")
+
+@dataclass(frozen=True)
+class Ok(Generic[T]):  data: T
+@dataclass(frozen=True)
+class Err(Generic[E]): error: E
+
+Result = Ok[T] | Err[E]
+```
+
+Or use `returns` library: `from returns.result import Result, Success, Failure`.
+
+---
+
+## Pattern 3 — Centralized HTTP Error Handler
+
+### Express
+```ts
+// errors of type AppError → mapped; everything else → 500
+app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
+  const requestId = res.getHeader('x-request-id');
+  if (err instanceof AppError) {
+    req.log.warn({ err, code: err.code, status: err.httpStatus }, err.message);
+    return res.status(err.httpStatus).json({
+      error: { code: err.code, message: err.message, requestId, ...err.meta },
+    });
+  }
+  // Unknown — programmer error, never leak details
+  req.log.error({ err }, 'Unhandled exception');
+  res.status(500).json({ error: { code: 'internal_error', message: 'Internal Server Error', requestId } });
+});
+```
+
+### Next.js — App Router
+Use `error.tsx` + `global-error.tsx` for client-rendered errors, and a wrapper for Route Handlers:
+
+```ts
+// app/api/_handler.ts
+export function safeHandler<T extends Request>(fn: (req: T) => Promise<Response>) {
+  return async (req: T): Promise<Response> => {
+    try { return await fn(req); }
+    catch (e) {
+      if (e instanceof AppError) {
+        return Response.json({ error: { code: e.code, message: e.message, ...e.meta } }, { status: e.httpStatus });
+      }
+      logger.error({ err: e }, 'Unhandled');
+      return Response.json({ error: { code: 'internal_error', message: 'Internal Server Error' } }, { status: 500 });
+    }
+  };
+}
+```
+
+### FastAPI
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(AppError)
+async def app_error_handler(req: Request, exc: AppError):
+    return JSONResponse(
+        {"error": {"code": exc.code, "message": str(exc), **exc.meta}},
+        status_code=exc.http_status,
+    )
+
+@app.exception_handler(Exception)
+async def unhandled_handler(req: Request, exc: Exception):
+    log.exception("unhandled", request_id=req.headers.get("x-request-id"))
+    return JSONResponse(
+        {"error": {"code": "internal_error", "message": "Internal Server Error"}},
+        status_code=500,
+    )
+```
+
+---
+
+## Pattern 4 — Retry with Backoff (External Calls)
+
+```ts
+// Idempotent operations only. Never retry payments without idempotency keys.
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  { tries = 3, baseMs = 200, factor = 2, jitter = 0.3 } = {},
+): Promise<T> {
+  let lastErr: unknown;
+  for (let i = 0; i < tries; i++) {
+    try { return await fn(); }
+    catch (e) {
+      lastErr = e;
+      if (i === tries - 1) break;
+      const delay = baseMs * Math.pow(factor, i) * (1 + (Math.random() - 0.5) * 2 * jitter);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new ExternalError('upstream', lastErr);
+}
+```
+
+For HTTP retries, use `axios-retry`, `got` (built-in), or `tenacity` (Python). Don't roll your own unless you must.
+
+**Idempotency keys** for non-idempotent operations (POST that creates / charges):
+```ts
+await stripe.charges.create({ amount, customer }, { idempotencyKey: orderId });
+```
+
+---
+
+## Pattern 5 — Circuit Breaker (External Outages)
+
+When upstream is down, fail fast instead of piling up requests:
+
+```ts
+import CircuitBreaker from 'opossum';
+const breaker = new CircuitBreaker(callUpstream, {
+  timeout: 3000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30000,
+});
+breaker.fallback(() => ({ data: cached, stale: true }));
+```
+
+Python: `pybreaker`. PHP: `ackintosh/ganesha`.
+
+---
+
+## Pattern 6 — Async / Promise Hygiene
+
+```ts
+// WRONG — unhandled rejection crashes the process (Node 15+)
+somePromise();
+
+// CORRECT — always handle, even if just to log
+somePromise().catch(err => logger.error({ err }, 'background task failed'));
+
+// Promise.all rejects on first failure — for partial success use allSettled
+const results = await Promise.allSettled([fetchA(), fetchB(), fetchC()]);
+const failures = results.filter(r => r.status === 'rejected');
+if (failures.length > 0) logger.warn({ failures }, 'partial failure');
+```
+
+Catch handler at process level (defense in depth):
+```ts
+process.on('unhandledRejection', (reason) => {
+  logger.fatal({ reason }, 'Unhandled rejection');
+  process.exit(1);
+});
+process.on('uncaughtException', (err) => {
+  logger.fatal({ err }, 'Uncaught exception');
+  process.exit(1);
+});
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Why it's bad | Fix |
+|---|---|---|
+| `try { ... } catch {}` | Silent failure | Log + rethrow or recover deliberately |
+| `catch (e) { console.log(e) }` | No structured context | Use logger; include `request_id`, `user_id` |
+| `catch (e) { throw new Error(e.message) }` | Loses stack trace | `throw new AppError(..., e)` (preserve cause) |
+| `if (err) return null` | Caller can't distinguish "no result" from "failed" | Result type |
+| Returning `{ error: 'something' }` from a function | Convention drift, untyped | Result type or throw |
+| Catching `Error` to coerce | Hides bugs | Catch specific classes |
+| Generic 500 response with raw stack | Info disclosure | Log full, return generic message + requestId |
+| Retrying non-idempotent calls | Double-charge / double-create | Idempotency keys |
+| Retrying without backoff | DoS your own upstream | Exponential + jitter |
+
+## API Error Response Shape (Standardize)
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid input",
+    "fields": {
+      "email": ["must be a valid email"],
+      "age": ["must be at least 13"]
+    },
+    "requestId": "req_abc123"
+  }
+}
+```
+
+Stable contract: client code can switch on `code`. Always include `requestId` so support can correlate with logs.
+
+## Pre-Commit Checklist
+
+- [ ] No empty `catch` blocks
+- [ ] Every `catch` either logs+rethrows, recovers deliberately, or transforms to `AppError`
+- [ ] Service-layer functions that can fail return `Result` or throw `AppError`
+- [ ] HTTP layer has a single error mapper; routes do not stringify exceptions
+- [ ] External calls have retry + backoff (if idempotent) or idempotency keys
+- [ ] No raw stack traces in API responses
+- [ ] Process-level `unhandledRejection` / `uncaughtException` handlers exist (Node)
+
+## See Also
+
+- `observability` — what to log on errors
+- `security-baseline` — A09 logging, A05 config (don't leak stack traces)
+- Stack `api-security-*` — error mapping in framework handlers

package/stacks/_shared/skills/final-check/SKILL.md

@@ -1,56 +1,93 @@
-# Final Check — Task Completion Validator
+---
+name: final-check
+version: 2.0.0
+description: Final validator with VETO power. Now executable — runs `npx tsx .claude/hooks/final-check.ts` to scan for debug statements, secrets, .skip, any, RCE risks, SQL concat. Blocks completion on CRITICAL/HIGH findings.
+---
 
-**ALWAYS invoke BEFORE completing ANY task. HAS VETO POWER.**
+# Final Check — Executable Validator
 
-> ⚠️ **VETO POWER:** If any rule is violated → STOP, list violations, require fix, re-validate.
+**ALWAYS run BEFORE completing ANY task. HAS VETO POWER.**
 
-## Purpose
+> v2.0+ promotes this from a manual checklist to an executable script. The script never trusts memory.
 
-Last check before task completion. Ensures nothing was forgotten.
+## How to Run
 
-## Checklist
+```bash
+npx tsx .claude/hooks/final-check.ts
+```
 
-### 1. Code Quality
-- [ ] Quality gates passed (PHPStan/TypeCheck, Tests, Lint)
-- [ ] No `console.log` / `var_dump` left in code
-- [ ] No TODO/FIXME left unresolved
-- [ ] No hardcoded secrets or credentials
+Exit codes:
+- `0` — clean (or only LOW/MEDIUM warnings)
+- `1` — at least one CRITICAL or HIGH finding → **task blocked**
 
-### 2. Documentation
-- [ ] CLAUDE.md "Last Change" updated
-- [ ] Affected domain files updated
-- [ ] New patterns documented
+## What It Scans
 
-### 3. Testing
-- [ ] New code has tests
-- [ ] Existing tests still pass
-- [ ] Edge cases covered
+For every file in the diff (staged + unstaged + untracked) matching the active stack's source extensions, every line is checked against:
 
-### 4. Git
-- [ ] On correct branch
-- [ ] All files committed
-- [ ] Conventional commit message
-- [ ] Merged to main (if complete)
+| Severity | Rule | Why blocking |
+|---|---|---|
+| CRITICAL | Hardcoded secret pattern (api key / token / password) | Leak risk |
+| CRITICAL | Public env var with `*SECRET\|*TOKEN\|*PRIVATE\|*PASSWORD\|*CREDENTIAL` | Bundles into client |
+| HIGH | Arbitrary code-execution function (`eval`, Python `exec`) | RCE |
+| HIGH | `subprocess` with `shell=True` (Python) | Command injection |
+| HIGH | SQL string concatenation / f-string SQL | SQL injection |
+| HIGH | `it.only` / `test.only` / `describe.only` / `it.skip` in committed test | False green CI |
+| MEDIUM | `console.log/debug/trace` outside tests | Debug leftover, log noise |
+| MEDIUM | PHP `var_dump/dd/dump/print_r` | Debug leftover |
+| MEDIUM | TypeScript `any` (without `/* ok */` escape) | Erodes strict mode |
+| MEDIUM | `@ts-ignore` (use `@ts-expect-error` with comment) | Silently outdated |
+| MEDIUM | `@pytest.mark.skip` | Hidden test gaps |
+| LOW | `print()` outside tests (Python) | Use logger |
+| LOW | TODO / FIXME / XXX / HACK | Track or remove |
 
-### 5. Skills Consulted
-- [ ] Codebase knowledge checked before implementing
-- [ ] Research cache checked before web search
-- [ ] Security patterns applied
+Lines containing recognised placeholders (`<your...>`, `YOUR_X`, `placeholder`, `example.com`, `sk_test_`) are skipped to avoid false positives in `.env.example` and docs.
 
-## Violation Response
+## Workflow
 
 ```
-BLOCKED: [Violation description]
+1. Implementation done
+2. Run npx tsx .claude/hooks/final-check.ts
+3. If exit 1 → fix, re-run
+4. If exit 0 → proceed to quality-gate → commit
+```
+
+## Suppressing False Positives
 
-Required fixes:
-1. [Fix needed]
-2. [Fix needed]
+When a finding is intentional (e.g. an `any` in well-justified glue code):
 
-Re-run final-check after fixing.
+```ts
+const result = (json as any) /* ok: external lib without types */;
 ```
 
+Only `/* ok */` immediately after `: any` is recognised. For other rules, refactor — there is no general-purpose suppression by design.
+
+## Hook Wiring (Optional)
+
+To run automatically on Stop, add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "npx tsx ${CLAUDE_PROJECT_DIR}/.claude/hooks/final-check.ts" }]
+    }]
+  }
+}
+```
+
+The default Stop is `stop-validator.ts` (git/branch/CLAUDE.md/secret scan). `final-check.ts` is complementary — runs before it as a code-quality gate.
+
 ## Rules
 
-1. **VETO POWER** — can block task completion
-2. **ALL CHECKS MUST PASS** — no partial approvals
-3. **RE-VALIDATE AFTER FIXES** — don't trust "I fixed it"
+1. **VETO POWER** — exit 1 blocks task completion
+2. **NEVER skip** — `--no-verify` style bypasses are forbidden
+3. **RE-RUN after fixes** — don't trust memory
+4. **One finding at a time** — fix CRITICAL first, then HIGH
+5. **Refactor over suppress** — `/* ok */` is for extraordinary cases
+
+## See Also
+
+- `quality-gate` — typecheck/lint/test/build (different scope)
+- `security-baseline` — what the secret/RCE rules enforce
+- `stop-validator.ts` — git/branch/docs gate (sibling, complementary)

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: git-workflow
+version: 1.0.0
+---
+
 # Git Workflow
 
 ## Branch Naming

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: hook-development
+version: 1.0.0
+---
+
 # Hook Development — Claude Code Hooks
 
 **ALWAYS invoke when creating or modifying Claude Code hooks.**