engrm 0.1.0 → 0.2.0

package/packs/react-gotchas.json

@@ -0,0 +1,182 @@
+{
+  "name": "react-gotchas",
+  "description": "Common React pitfalls, performance issues, and best practices",
+  "version": "1.0.0",
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Use key prop correctly — index keys cause bugs with reordering",
+      "narrative": "React uses keys to track list identity. Using array index as key causes incorrect component reuse when items are reordered, deleted, or inserted.",
+      "facts": ["Use stable unique IDs as keys (database IDs, UUIDs)", "Index keys are only safe for static lists that never change", "Missing keys cause React to warn and use index implicitly"],
+      "concepts": ["react-keys", "list-rendering", "reconciliation"]
+    },
+    {
+      "type": "bugfix",
+      "title": "useEffect cleanup: return a cleanup function to avoid memory leaks",
+      "narrative": "Effects that set up subscriptions, timers, or event listeners must return a cleanup function. Without it, listeners accumulate on re-renders.",
+      "facts": ["Return a function from useEffect for cleanup", "Cleanup runs before re-running the effect and on unmount", "Common sources: setInterval, addEventListener, WebSocket connections"],
+      "concepts": ["useEffect", "cleanup", "memory-leak", "subscriptions"]
+    },
+    {
+      "type": "pattern",
+      "title": "Avoid creating objects/arrays in render — causes unnecessary re-renders",
+      "narrative": "New object/array literals in JSX (style={{}}, options={[]}) create new references every render, defeating React.memo and causing child re-renders.",
+      "facts": ["Move constant objects outside the component", "Use useMemo for computed objects", "Use useCallback for function props", "React.memo compares props by reference"],
+      "concepts": ["referential-equality", "useMemo", "useCallback", "performance"]
+    },
+    {
+      "type": "bugfix",
+      "title": "State updates are batched — don't read state immediately after setState",
+      "narrative": "React batches state updates for performance. Reading state right after setState gives the old value. Use the callback form or useEffect to react to changes.",
+      "facts": ["setState is asynchronous in event handlers", "Use functional updates: setState(prev => prev + 1)", "useEffect with the state as dependency reacts to changes", "React 18 batches all updates, including in promises and timeouts"],
+      "concepts": ["state-batching", "setState", "async-state", "react-18"]
+    },
+    {
+      "type": "pattern",
+      "title": "Lift state up only as high as needed — avoid prop drilling",
+      "narrative": "State should live in the lowest common ancestor that needs it. For deeply nested access, use Context or a state management library instead of passing through many layers.",
+      "facts": ["Prop drilling through 2-3 levels is fine", "Beyond that, consider Context or state libraries", "Context re-renders all consumers — keep contexts focused", "Composition (passing children) often eliminates prop drilling"],
+      "concepts": ["state-management", "prop-drilling", "context", "component-composition"]
+    },
+    {
+      "type": "discovery",
+      "title": "React.StrictMode double-invokes effects to catch bugs",
+      "narrative": "In development, StrictMode intentionally runs effects twice to help find cleanup bugs. This is normal and doesn't happen in production.",
+      "facts": ["Effects run twice in dev with StrictMode", "This catches missing cleanup functions", "Does not happen in production builds", "Don't remove StrictMode to 'fix' double renders"],
+      "concepts": ["strict-mode", "development", "debugging"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use React.lazy and Suspense for code splitting",
+      "narrative": "Large bundles slow initial load. Split code at route boundaries using React.lazy() with Suspense fallback. This loads components on demand.",
+      "facts": ["React.lazy(() => import('./Component')) for dynamic import", "Wrap with <Suspense fallback={<Loading/>}>", "Split at route level first for biggest impact", "Avoid lazy for above-the-fold content"],
+      "concepts": ["code-splitting", "lazy-loading", "suspense", "performance"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Closures in useEffect capture stale state values",
+      "narrative": "Effects close over the state from the render they were created in. Without proper dependencies, they reference stale values.",
+      "facts": ["Always include used variables in the dependency array", "Use the eslint exhaustive-deps rule", "Functional updates (setCount(c => c + 1)) avoid stale closure", "Refs (useRef) provide a mutable escape hatch"],
+      "concepts": ["stale-closures", "useEffect-dependencies", "hooks-rules"]
+    },
+    {
+      "type": "pattern",
+      "title": "Error boundaries catch render errors — use them at route level",
+      "narrative": "Unhandled errors in render crash the entire app. Error boundaries (class components with componentDidCatch) prevent this by catching errors in their subtree.",
+      "facts": ["Error boundaries must be class components", "Catch errors in render, lifecycle, and constructors", "Don't catch errors in event handlers — use try/catch", "Place boundaries at route level and around risky components"],
+      "concepts": ["error-boundary", "error-handling", "resilience"]
+    },
+    {
+      "type": "pattern",
+      "title": "Avoid derived state — compute during render instead",
+      "narrative": "Storing values derived from props/state in separate state causes sync bugs. Compute derived values during render or use useMemo for expensive computations.",
+      "facts": ["Derived state = state computed from other state/props", "Compute it inline or with useMemo", "getDerivedStateFromProps is almost always wrong", "Filtering/sorting lists is a common case — useMemo, don't store"],
+      "concepts": ["derived-state", "useMemo", "anti-pattern"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Don't mutate state directly — always create new references",
+      "narrative": "React detects changes by reference comparison. Mutating objects/arrays in state (push, splice, obj.key = val) won't trigger re-renders.",
+      "facts": ["Use spread: setState({...state, key: val})", "For arrays: [...arr, newItem], arr.filter(), arr.map()", "Use structuredClone() for deep copies", "Libraries like Immer make immutable updates easier"],
+      "concepts": ["immutability", "state-updates", "reference-equality"]
+    },
+    {
+      "type": "pattern",
+      "title": "useId for unique IDs — don't use Math.random in render",
+      "narrative": "Components needing unique IDs (for label-input associations, ARIA) should use React.useId() which is stable across server/client rendering.",
+      "facts": ["useId generates deterministic IDs safe for SSR", "Math.random() causes hydration mismatches", "useId works with multiple IDs: id + '-name', id + '-email'"],
+      "concepts": ["useId", "accessibility", "ssr-hydration"]
+    },
+    {
+      "type": "pattern",
+      "title": "Debounce search inputs — don't fire API calls on every keystroke",
+      "narrative": "Text inputs connected to search should debounce the API call. Use a custom hook or useDeferredValue to avoid flooding the server.",
+      "facts": ["Debounce with 200-300ms delay for search", "useDeferredValue is React 18's built-in approach", "AbortController cancels in-flight requests", "Show stale results while loading new ones"],
+      "concepts": ["debounce", "search", "useDeferredValue", "performance"]
+    },
+    {
+      "type": "discovery",
+      "title": "React DevTools Profiler identifies unnecessary re-renders",
+      "narrative": "The Profiler in React DevTools shows which components re-render and why. Use it to find performance bottlenecks instead of premature optimization.",
+      "facts": ["Enable 'Highlight updates' to see re-renders visually", "Profiler shows render time and commit info", "Check 'Why did this render?' with the option enabled", "Optimize only measured bottlenecks"],
+      "concepts": ["react-devtools", "profiling", "performance-debugging"]
+    },
+    {
+      "type": "pattern",
+      "title": "Controlled vs uncontrolled inputs: pick one and be consistent",
+      "narrative": "Mixing controlled (value + onChange) and uncontrolled (defaultValue + ref) patterns on the same input causes React warnings and bugs.",
+      "facts": ["Controlled: value={state} + onChange handler", "Uncontrolled: defaultValue + useRef to read on submit", "Switching from uncontrolled to controlled is a warning", "Forms with many fields: consider react-hook-form (uncontrolled)"],
+      "concepts": ["controlled-components", "forms", "useRef"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use React.memo strategically — not on every component",
+      "narrative": "React.memo prevents re-renders when props haven't changed. But it has a cost (shallow comparison) and is only worthwhile for components that re-render often with same props.",
+      "facts": ["Measure before memoizing", "Useless if parent always passes new object/function props", "Pair with useCallback/useMemo for prop stability", "List items and expensive renders benefit most"],
+      "concepts": ["react-memo", "memoization", "performance-optimization"]
+    },
+    {
+      "type": "bugfix",
+      "title": "useEffect with empty deps runs once — watch for missing dependencies",
+      "narrative": "useEffect(() => {...}, []) runs only on mount. If the effect uses props or state, those values will be stale forever. Add them to the dependency array.",
+      "facts": ["Empty array = run once on mount", "Missing deps = stale values (subtle bug)", "ESLint exhaustive-deps rule catches this", "If you truly want run-once, ensure no external deps are used"],
+      "concepts": ["useEffect", "dependency-array", "stale-closures"]
+    },
+    {
+      "type": "pattern",
+      "title": "Prefer composition over configuration for flexible components",
+      "narrative": "Instead of adding more and more props to configure a component, compose smaller components. Slots (children, render props) are more flexible than config objects.",
+      "facts": ["Composition: <Card><CardHeader/><CardBody/></Card>", "Configuration: <Card title='...' body='...' footer='...'/>", "Composition scales better and avoids prop explosion", "React children pattern is the simplest form of composition"],
+      "concepts": ["composition", "component-design", "render-props", "children"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Conditional hooks violate Rules of Hooks — always call in same order",
+      "narrative": "Hooks must be called in the same order every render. Putting hooks inside if/else, loops, or after early returns causes React to lose track of state.",
+      "facts": ["Hooks rely on call order for identity", "Move conditions inside the hook instead", "eslint-plugin-react-hooks enforces this", "Custom hooks must also follow this rule"],
+      "concepts": ["rules-of-hooks", "conditional-hooks", "hook-order"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use AbortController to cancel fetch requests on unmount",
+      "narrative": "Fetch requests that complete after a component unmounts cause 'setState on unmounted component' warnings. Use AbortController in the cleanup function.",
+      "facts": ["Create AbortController in effect, pass signal to fetch", "Abort in cleanup: return () => controller.abort()", "Aborted fetch throws AbortError — catch and ignore it", "Works with axios via cancelToken too"],
+      "concepts": ["fetch", "abort-controller", "cleanup", "useEffect"]
+    },
+    {
+      "type": "pattern",
+      "title": "Server Components (RSC) run on the server — no state, no effects",
+      "narrative": "React Server Components execute at build/request time on the server. They can't use useState, useEffect, or browser APIs. Use 'use client' directive for interactive components.",
+      "facts": ["Server Components are the default in Next.js App Router", "Add 'use client' at top of file for client components", "Server Components can async/await directly", "Pass server data as props to client components"],
+      "concepts": ["server-components", "rsc", "nextjs", "use-client"]
+    },
+    {
+      "type": "pattern",
+      "title": "Virtualize long lists — don't render 1000+ items in DOM",
+      "narrative": "Rendering thousands of DOM nodes kills performance. Use react-window or react-virtuoso to only render visible items.",
+      "facts": ["Virtual lists render only visible rows", "react-window is lightweight (6kb)", "react-virtuoso handles variable heights", "Measure first — small lists (<100 items) don't need virtualization"],
+      "concepts": ["virtualization", "performance", "react-window", "long-lists"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use useReducer for complex state logic with multiple sub-values",
+      "narrative": "When state has multiple related values or complex update logic, useReducer provides clearer state transitions than multiple useState calls.",
+      "facts": ["useReducer is better for related state values", "Actions describe what happened, reducer decides how state changes", "Easier to test — reducer is a pure function", "Combine with useContext for app-level state"],
+      "concepts": ["useReducer", "state-management", "complex-state"]
+    },
+    {
+      "type": "discovery",
+      "title": "React 19: use() hook for promises and context",
+      "narrative": "React 19 introduces the use() hook which can read promises (with Suspense) and context values. It can be called conditionally, unlike other hooks.",
+      "facts": ["use(promise) suspends until promise resolves", "use(context) replaces useContext(context)", "Can be called inside if/else (exception to hook rules)", "Works with server components and client components"],
+      "concepts": ["react-19", "use-hook", "suspense", "context"]
+    },
+    {
+      "type": "pattern",
+      "title": "Handle loading, error, and empty states explicitly",
+      "narrative": "Every data-fetching component needs three states: loading (skeleton/spinner), error (retry/message), and empty (helpful message/CTA). Don't just handle the happy path.",
+      "facts": ["Skeletons are better UX than spinners for content", "Show retry button on error", "Empty state should guide user to action", "Consider using Suspense + ErrorBoundary for this pattern"],
+      "concepts": ["loading-states", "error-states", "empty-states", "ux"]
+    }
+  ]
+}

package/packs/typescript-patterns.json

@@ -0,0 +1,67 @@
+{
+  "name": "typescript-patterns",
+  "description": "Common TypeScript patterns, gotchas, and best practices",
+  "stacks": ["typescript"],
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Use 'satisfies' for type-safe config objects",
+      "narrative": "The 'satisfies' operator validates a value matches a type without widening it. Prefer `const config = { ... } satisfies Config` over `const config: Config = { ... }` to preserve literal types.",
+      "concepts": ["typescript", "satisfies", "type-safety"]
+    },
+    {
+      "type": "pattern",
+      "title": "Discriminated unions over optional properties",
+      "narrative": "Use a shared literal 'kind' or 'type' field to discriminate union variants. This enables exhaustive switch/case checking and eliminates impossible states that optional properties allow.",
+      "concepts": ["typescript", "discriminated-union", "type-safety"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use 'as const' for literal type inference",
+      "narrative": "Apply 'as const' to object/array literals when you need TypeScript to infer exact string/number literal types instead of widened string/number types.",
+      "concepts": ["typescript", "const-assertion", "literal-types"]
+    },
+    {
+      "type": "discovery",
+      "title": "Template literal types for string patterns",
+      "narrative": "TypeScript supports template literal types like `type Route = \\`/api/${string}\\`` to constrain string shapes at the type level. Useful for API paths, CSS values, and event names.",
+      "concepts": ["typescript", "template-literal-types"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Avoid 'any' leaking through generic defaults",
+      "narrative": "Generic functions with `<T = any>` silently disable type checking for callers who don't provide the type parameter. Use `<T = unknown>` or `<T extends Base>` instead.",
+      "concepts": ["typescript", "generics", "any-leak"]
+    },
+    {
+      "type": "pattern",
+      "title": "Branded types for domain identifiers",
+      "narrative": "Prevent mixing up IDs like userId and orderId by creating branded types: `type UserId = string & { __brand: 'UserId' }`. Create helper functions to construct them.",
+      "concepts": ["typescript", "branded-types", "domain-modeling"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use 'unknown' over 'any' for safe catch blocks",
+      "narrative": "In catch blocks, use `catch (err: unknown)` and narrow with `err instanceof Error` before accessing .message. This prevents runtime crashes from non-Error throws.",
+      "concepts": ["typescript", "error-handling", "unknown"]
+    },
+    {
+      "type": "pattern",
+      "title": "Record<string, T> vs Map<string, T>",
+      "narrative": "Use Record for static key sets known at compile time. Use Map when keys are dynamic, when you need size/iteration order guarantees, or when non-string keys are needed.",
+      "concepts": ["typescript", "record", "map", "data-structures"]
+    },
+    {
+      "type": "discovery",
+      "title": "Infer return types from implementation",
+      "narrative": "For internal functions, let TypeScript infer the return type from the implementation. Only add explicit return types at module boundaries (exports) or when the inference is too wide.",
+      "concepts": ["typescript", "return-types", "type-inference"]
+    },
+    {
+      "type": "pattern",
+      "title": "Zod schemas as single source of truth",
+      "narrative": "Define Zod schemas first, then derive TypeScript types with z.infer<typeof schema>. This gives you both runtime validation and compile-time types from a single definition.",
+      "concepts": ["typescript", "zod", "validation", "schema"]
+    }
+  ]
+}

package/packs/web-security.json

@@ -0,0 +1,182 @@
+{
+  "name": "web-security",
+  "description": "Common web security patterns, vulnerabilities, and best practices",
+  "version": "1.0.0",
+  "observations": [
+    {
+      "type": "pattern",
+      "title": "Always validate and sanitize user input on the server side",
+      "narrative": "Client-side validation is a UX feature, not a security measure. All user input must be validated and sanitized server-side before use in queries, file operations, or rendering.",
+      "facts": ["Client-side validation can be bypassed trivially", "Server-side validation is the real security boundary", "Use allowlists over denylists when possible"],
+      "concepts": ["input-validation", "xss-prevention", "server-side-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use parameterized queries to prevent SQL injection",
+      "narrative": "Never concatenate user input into SQL strings. Use parameterized queries or prepared statements provided by your database library.",
+      "facts": ["SQL injection is consistently in OWASP Top 10", "Parameterized queries separate code from data", "ORMs generally handle this but raw queries need explicit parameterization"],
+      "concepts": ["sql-injection", "parameterized-queries", "prepared-statements"]
+    },
+    {
+      "type": "pattern",
+      "title": "Set Content-Security-Policy headers to mitigate XSS",
+      "narrative": "CSP headers instruct browsers to only execute scripts from trusted sources, dramatically reducing the attack surface for cross-site scripting.",
+      "facts": ["Start with a restrictive policy and loosen as needed", "Use nonces or hashes for inline scripts", "Report-only mode helps during rollout"],
+      "concepts": ["csp", "xss", "http-headers", "content-security-policy"]
+    },
+    {
+      "type": "pattern",
+      "title": "Store passwords using bcrypt, scrypt, or Argon2",
+      "narrative": "Never store passwords in plaintext or with fast hashing algorithms like MD5/SHA. Use purpose-built password hashing with salt and work factor.",
+      "facts": ["Argon2id is the current recommendation", "bcrypt with cost factor 12+ is still acceptable", "Always use unique salts per password", "Never use MD5 or SHA for passwords"],
+      "concepts": ["password-hashing", "bcrypt", "argon2", "authentication"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement CSRF protection for state-changing requests",
+      "narrative": "Cross-Site Request Forgery tricks authenticated users into making unwanted requests. Use anti-CSRF tokens, SameSite cookies, and verify Origin headers.",
+      "facts": ["SameSite=Lax cookies prevent most CSRF attacks", "CSRF tokens must be unique per session", "GET requests should never modify state"],
+      "concepts": ["csrf", "cookies", "session-security"]
+    },
+    {
+      "type": "discovery",
+      "title": "HttpOnly and Secure flags on session cookies prevent theft",
+      "narrative": "HttpOnly prevents JavaScript access to cookies (mitigating XSS cookie theft). Secure ensures cookies are only sent over HTTPS.",
+      "facts": ["HttpOnly blocks document.cookie access", "Secure flag requires HTTPS transport", "SameSite=Strict prevents cross-origin sending"],
+      "concepts": ["cookies", "session-management", "http-only", "secure-flag"]
+    },
+    {
+      "type": "pattern",
+      "title": "Rate limit authentication endpoints to prevent brute force",
+      "narrative": "Login, registration, and password reset endpoints must have rate limiting to prevent credential stuffing and brute force attacks.",
+      "facts": ["Use progressive delays (1s, 2s, 4s, 8s) or hard lockout after N attempts", "Rate limit by IP and by account independently", "Consider CAPTCHA after 3-5 failed attempts"],
+      "concepts": ["rate-limiting", "brute-force", "authentication", "account-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Validate file uploads: type, size, and content",
+      "narrative": "File uploads are a common attack vector. Validate MIME type, file extension, file size, and ideally scan content. Never trust the client-provided filename.",
+      "facts": ["Check magic bytes, not just extension", "Store uploads outside webroot", "Generate new filenames server-side", "Set maximum file size limits"],
+      "concepts": ["file-upload", "content-type", "path-traversal"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use HTTPS everywhere — no exceptions for internal services",
+      "narrative": "TLS encrypts data in transit. Internal services communicate over networks that can be compromised. Use TLS for all service-to-service communication.",
+      "facts": ["Let's Encrypt provides free certificates", "HSTS header prevents downgrade attacks", "Internal services should also use TLS"],
+      "concepts": ["https", "tls", "hsts", "encryption-in-transit"]
+    },
+    {
+      "type": "discovery",
+      "title": "Environment variables for secrets, never in code or config files",
+      "narrative": "API keys, database passwords, and tokens must come from environment variables or a secrets manager. Never commit them to version control.",
+      "facts": ["Use .env files locally (gitignored)", "Use secrets manager in production (AWS SM, Vault, etc.)", "Rotate secrets regularly", "Audit git history for accidentally committed secrets"],
+      "concepts": ["secrets-management", "environment-variables", "api-keys"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement proper CORS configuration",
+      "narrative": "Cross-Origin Resource Sharing must be configured to allow only trusted origins. Wildcards in CORS headers are dangerous for authenticated APIs.",
+      "facts": ["Never use Access-Control-Allow-Origin: * with credentials", "Whitelist specific origins", "Preflight requests (OPTIONS) must be handled correctly"],
+      "concepts": ["cors", "cross-origin", "api-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Escape output based on context: HTML, JS, URL, CSS",
+      "narrative": "Output encoding must match the context where data is rendered. HTML escaping doesn't protect against JavaScript injection in script tags.",
+      "facts": ["HTML context: escape < > & \" '", "JavaScript context: use JSON.stringify or \\xHH encoding", "URL context: use encodeURIComponent", "CSS context: use \\HH encoding"],
+      "concepts": ["output-encoding", "xss-prevention", "context-aware-escaping"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use helmet.js or equivalent for security headers in Node.js",
+      "narrative": "Security headers like X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security should be set on all responses. Helmet.js sets sensible defaults.",
+      "facts": ["X-Frame-Options: DENY prevents clickjacking", "X-Content-Type-Options: nosniff prevents MIME sniffing", "Referrer-Policy controls information leakage"],
+      "concepts": ["security-headers", "helmet", "node-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "JWT tokens: short expiry, secure storage, validate all claims",
+      "narrative": "JWTs are not session tokens. Use short expiry (15min), refresh tokens for renewal, validate iss/aud/exp claims, and never store in localStorage for sensitive apps.",
+      "facts": ["Short-lived access tokens (5-15 min)", "Refresh tokens in httpOnly cookies", "Validate algorithm to prevent 'none' attack", "Check token revocation for sensitive operations"],
+      "concepts": ["jwt", "authentication", "token-security", "session-management"]
+    },
+    {
+      "type": "discovery",
+      "title": "Dependency vulnerabilities: audit regularly with automated tools",
+      "narrative": "Third-party packages introduce supply chain risk. Run npm audit, Snyk, or Dependabot regularly. Pin versions and review changelogs before upgrading.",
+      "facts": ["Run npm audit or yarn audit in CI", "Use lock files for reproducible builds", "Review dependency tree for unnecessary transitive deps", "Consider using Socket.dev for supply chain analysis"],
+      "concepts": ["dependency-security", "npm-audit", "supply-chain", "vulnerability-scanning"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement proper error handling — never leak stack traces",
+      "narrative": "Production error responses should be generic. Stack traces, SQL errors, and internal paths help attackers understand your system.",
+      "facts": ["Return generic error messages to clients", "Log detailed errors server-side", "Different error handling for dev vs prod", "Never expose database error details"],
+      "concepts": ["error-handling", "information-disclosure", "production-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Authorization checks on every endpoint, not just the frontend",
+      "narrative": "Broken access control is OWASP #1. Every API endpoint must verify the user has permission for the requested resource. Frontend route guards are not security.",
+      "facts": ["Check authorization server-side on every request", "Use middleware for consistent enforcement", "IDOR: always verify resource ownership", "Principle of least privilege"],
+      "concepts": ["authorization", "access-control", "idor", "broken-access-control"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use Subresource Integrity (SRI) for CDN-loaded scripts",
+      "narrative": "SRI hashes ensure that scripts loaded from CDNs haven't been tampered with. If the hash doesn't match, the browser refuses to execute the script.",
+      "facts": ["Add integrity attribute to script and link tags", "Generate hashes with shasum or online tools", "Combine with crossorigin='anonymous'"],
+      "concepts": ["sri", "cdn-security", "supply-chain", "integrity"]
+    },
+    {
+      "type": "bugfix",
+      "title": "Path traversal: normalize and validate file paths",
+      "narrative": "Attackers use ../ sequences to access files outside intended directories. Always normalize paths and verify they resolve within the expected base directory.",
+      "facts": ["Use path.resolve() then check startsWith(baseDir)", "Reject paths containing .. after normalization", "URL-encoded ../ (%2e%2e%2f) can bypass naive checks"],
+      "concepts": ["path-traversal", "directory-traversal", "file-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement request signing for API-to-API communication",
+      "narrative": "For service-to-service calls, use HMAC request signing or mutual TLS instead of static API keys. This prevents replay attacks and ensures message integrity.",
+      "facts": ["Include timestamp in signed payload to prevent replay", "HMAC-SHA256 is widely supported", "Mutual TLS provides both authentication and encryption"],
+      "concepts": ["request-signing", "hmac", "mutual-tls", "api-security"]
+    },
+    {
+      "type": "discovery",
+      "title": "Content-Type validation prevents polyglot file attacks",
+      "narrative": "Uploaded files can be valid in multiple formats simultaneously (polyglot). Validate Content-Type matches actual file content using magic bytes.",
+      "facts": ["A file can be both valid JPEG and valid HTML", "Check first few bytes (magic number) against claimed type", "Re-encode images server-side to strip embedded payloads"],
+      "concepts": ["polyglot-files", "content-type", "file-upload-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Log security events with structured data for incident response",
+      "narrative": "Authentication failures, authorization denials, input validation failures, and admin actions should be logged with structured data for security monitoring.",
+      "facts": ["Include: timestamp, user_id, IP, action, resource, outcome", "Never log passwords, tokens, or PII", "Use structured logging (JSON) for machine parsing", "Forward to SIEM for alerting"],
+      "concepts": ["security-logging", "audit-trail", "incident-response"]
+    },
+    {
+      "type": "pattern",
+      "title": "Implement account lockout with exponential backoff",
+      "narrative": "After repeated failed login attempts, temporarily lock the account. Use exponential backoff to make brute force infeasible while limiting impact on legitimate users.",
+      "facts": ["Lock after 5-10 failed attempts", "Exponential backoff: 1min, 5min, 15min, 1hr", "Notify user via email on lockout", "Track attempts per account AND per IP"],
+      "concepts": ["account-lockout", "brute-force-protection", "authentication"]
+    },
+    {
+      "type": "discovery",
+      "title": "Server-Side Request Forgery (SSRF) via user-supplied URLs",
+      "narrative": "When your server fetches URLs provided by users (webhooks, image URLs, etc.), attackers can target internal services. Validate and restrict allowed destinations.",
+      "facts": ["Block requests to private IP ranges (10.x, 172.16-31.x, 192.168.x)", "Use allowlists for permitted domains when possible", "DNS rebinding can bypass IP checks — resolve DNS before connecting", "Cloud metadata endpoints (169.254.169.254) are high-value targets"],
+      "concepts": ["ssrf", "url-validation", "internal-network", "cloud-security"]
+    },
+    {
+      "type": "pattern",
+      "title": "Use nonces for inline scripts with CSP",
+      "narrative": "If you must use inline scripts, generate a random nonce per request and include it in both the CSP header and the script tag. Never use unsafe-inline.",
+      "facts": ["Nonce must be cryptographically random per request", "Add nonce to CSP: script-src 'nonce-abc123'", "Add to script tag: <script nonce='abc123'>", "unsafe-inline defeats the purpose of CSP"],
+      "concepts": ["csp-nonce", "inline-scripts", "xss-prevention"]
+    }
+  ]
+}

package/.mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "engrm": {
-      "type": "stdio",
-      "command": "/Users/david/.bun/bin/bun",
-      "args": ["run", "src/server.ts"]
-    }
-  }
-}