@orkify/cli 1.0.0-beta.5

package/packages/next/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@orkify/next",
+  "version": "1.0.0-beta.1",
+  "private": true,
+  "description": "Next.js integration for orkify — cache handlers and browser error tracking",
+  "type": "module",
+  "exports": {
+    "./use-cache": {
+      "types": "./src/use-cache.ts",
+      "import": "./dist/use-cache.js",
+      "default": "./dist/use-cache.js"
+    },
+    "./isr-cache": {
+      "types": "./src/isr-cache.ts",
+      "import": "./dist/isr-cache.js",
+      "default": "./dist/isr-cache.js"
+    },
+    "./error-capture": {
+      "types": "./src/error-capture.ts",
+      "import": "./dist/error-capture.js",
+      "default": "./dist/error-capture.js"
+    },
+    "./error-handler": {
+      "types": "./src/error-handler.ts",
+      "import": "./dist/error-handler.js",
+      "default": "./dist/error-handler.js"
+    },
+    "./utils": {
+      "types": "./src/utils.ts",
+      "import": "./dist/utils.js",
+      "default": "./dist/utils.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@orkify/cache": "file:../cache"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "zod": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  }
+}

package/packages/next/src/error-capture.ts

@@ -0,0 +1,177 @@
+'use client';
+
+// Minimal DOM types — this module runs in the browser via 'use client'.
+// We don't add "DOM" to tsconfig.lib to avoid polluting Node.js code.
+
+declare const window: {
+  addEventListener(type: string, listener: (event: never) => void): void;
+  removeEventListener(type: string, listener: (event: never) => void): void;
+};
+declare const location: undefined | { href: string };
+declare const navigator: undefined | { userAgent: string };
+interface ErrorEvent {
+  error: unknown;
+  message: string;
+}
+interface PromiseRejectionEvent {
+  reason: unknown;
+}
+
+import { useEffect } from 'react';
+
+interface OrkifyErrorCaptureProps {
+  /** API route endpoint. Default: `/orkify/errors` */
+  endpoint?: string;
+  /** Max errors to report per page load. Default: 10 */
+  maxErrors?: number;
+}
+
+/** Simple hash for client-side dedup (not cryptographic). */
+function simpleHash(str: string): string {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+  }
+  return h.toString(36);
+}
+
+/**
+ * Normalize a Firefox/Safari `fn@file:line:col` stack to V8 `at fn (file:line:col)` format.
+ * Chrome/Edge stacks (already V8 format) pass through unchanged.
+ */
+export function normalizeStack(stack: string): string {
+  return stack
+    .split('\n')
+    .map((line) => {
+      // Already V8 format: "    at fn (...)" or "    at ..."
+      if (/^\s*at\s+/.test(line)) return line;
+
+      // Firefox/Safari: "fn@file:line:col" or "@file:line:col"
+      const m = line.match(/^([^@]*)@(.+):(\d+):(\d+)$/);
+      if (m) {
+        const fn = m[1];
+        const loc = `${m[2]}:${m[3]}:${m[4]}`;
+        return fn ? `    at ${fn} (${loc})` : `    at ${loc}`;
+      }
+
+      return line;
+    })
+    .join('\n');
+}
+
+// Module-level state for dedup and rate limiting
+const recentHashes = new Map<string, number>();
+let errorCount = 0;
+let configuredEndpoint = '/orkify/errors';
+let configuredMax = 10;
+
+/** Flush expired dedup entries (older than 5 seconds). */
+function flushExpired(): void {
+  const cutoff = Date.now() - 5_000;
+  for (const [hash, ts] of recentHashes) {
+    if (ts < cutoff) recentHashes.delete(hash);
+  }
+}
+
+/** Send an error report to the server endpoint. */
+function sendError(
+  name: string,
+  message: string,
+  stack: string,
+  errorType: 'browser:error' | 'browser:unhandledRejection'
+): void {
+  if (errorCount >= configuredMax) return;
+
+  const normalizedStack = normalizeStack(stack);
+  const hash = simpleHash(normalizedStack);
+
+  // Dedup: skip if same stack seen in last 5 seconds
+  flushExpired();
+  if (recentHashes.has(hash)) return;
+  recentHashes.set(hash, Date.now());
+  errorCount++;
+
+  void fetch(configuredEndpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name,
+      message,
+      stack: normalizedStack,
+      errorType,
+      url: typeof location !== 'undefined' ? location.href : '',
+      userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+      timestamp: Date.now(),
+    }),
+    keepalive: true,
+  }).catch(() => {
+    // Silently ignore — never crash the app for error reporting
+  });
+}
+
+/**
+ * Report an error manually. Use this from React Error Boundaries
+ * (including Next.js `error.tsx`) where errors don't bubble to `window.onerror`.
+ *
+ * ```tsx
+ * import { reportError } from '@orkify/next/error-capture';
+ * useEffect(() => { reportError(error); }, [error]);
+ * ```
+ */
+export function reportError(error: unknown): void {
+  if (!(error instanceof Error)) return;
+  sendError(error.name || 'Error', error.message || '', error.stack || '', 'browser:error');
+}
+
+/**
+ * Drop-in component that captures browser errors and reports them to orkify.
+ * Add to your root layout:
+ *
+ * ```tsx
+ * import { OrkifyErrorCapture } from '@orkify/next/error-capture';
+ *
+ * <OrkifyErrorCapture />
+ * ```
+ */
+export function OrkifyErrorCapture({
+  endpoint = '/orkify/errors',
+  maxErrors = 10,
+}: OrkifyErrorCaptureProps): null {
+  useEffect(() => {
+    configuredEndpoint = endpoint;
+    configuredMax = maxErrors;
+
+    const onError = (event: ErrorEvent): void => {
+      const err = event.error;
+      if (err instanceof Error) {
+        sendError(err.name || 'Error', err.message || '', err.stack || '', 'browser:error');
+      } else {
+        sendError('Error', String(event.message || err), '', 'browser:error');
+      }
+    };
+
+    const onRejection = (event: PromiseRejectionEvent): void => {
+      const reason = event.reason;
+      if (reason instanceof Error) {
+        sendError(
+          reason.name || 'UnhandledRejection',
+          reason.message || '',
+          reason.stack || '',
+          'browser:unhandledRejection'
+        );
+      } else {
+        sendError('UnhandledRejection', String(reason), '', 'browser:unhandledRejection');
+      }
+    };
+
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+
+    return () => {
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+    };
+  }, [endpoint, maxErrors]);
+
+  return null;
+}

package/packages/next/src/error-handler.ts

@@ -0,0 +1,221 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { extractContext, parseBrowserFrames, type StackFrame } from './utils.js';
+
+// ── Rate Limiter ────────────────────────────────────────────────────────
+
+const MAX_ERRORS_PER_WINDOW = 10;
+const WINDOW_MS = 10_000;
+
+interface RateBucket {
+  count: number;
+  resetAt: number;
+}
+
+const rateLimits = new Map<string, RateBucket>();
+
+/** Periodic cleanup to prevent unbounded Map growth. */
+let cleanupTimer: null | ReturnType<typeof setInterval> = null;
+
+function ensureCleanupTimer(): void {
+  if (cleanupTimer) return;
+  cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, bucket] of rateLimits) {
+      if (bucket.resetAt <= now) rateLimits.delete(key);
+    }
+    if (rateLimits.size === 0 && cleanupTimer) {
+      clearInterval(cleanupTimer);
+      cleanupTimer = null;
+    }
+  }, 30_000);
+  cleanupTimer.unref();
+}
+
+function isRateLimited(ip: string): boolean {
+  const now = Date.now();
+  const bucket = rateLimits.get(ip);
+
+  if (!bucket || bucket.resetAt <= now) {
+    rateLimits.set(ip, { count: 1, resetAt: now + WINDOW_MS });
+    ensureCleanupTimer();
+    return false;
+  }
+
+  bucket.count++;
+  return bucket.count > MAX_ERRORS_PER_WINDOW;
+}
+
+// ── Validation ──────────────────────────────────────────────────────────
+
+const MAX_BODY_SIZE = 65_536; // 64 KB
+const MAX_STACK_LINES = 100;
+
+const browserErrorSchema = z.object({
+  name: z.string().max(256),
+  message: z.string().max(4096),
+  stack: z.string().max(32_768),
+  errorType: z.enum(['browser:error', 'browser:unhandledRejection']),
+  url: z.string().max(2048),
+  userAgent: z.string().max(512),
+  timestamp: z.number(),
+});
+
+// ── Source Context Builder ──────────────────────────────────────────────
+
+interface SourceContextFrame {
+  file: string;
+  line: number;
+  column: number;
+  pre: string[];
+  target: string;
+  post: string[];
+}
+
+function buildSourceContext(frames: StackFrame[]): SourceContextFrame[] {
+  const result: SourceContextFrame[] = [];
+
+  for (const frame of frames) {
+    if (!existsSync(frame.file)) continue;
+
+    try {
+      const source = readFileSync(frame.file, 'utf8');
+      const context = extractContext(source, frame.line);
+      if (!context) continue;
+
+      result.push({
+        file: frame.file,
+        line: frame.line,
+        column: frame.column,
+        pre: context.pre,
+        target: context.target,
+        post: context.post,
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return result;
+}
+
+// ── Request Handler ─────────────────────────────────────────────────────
+
+function getClientIp(request: Request): string {
+  // Cloudflare: most reliable, cannot be spoofed by the client
+  const cfIp = request.headers.get('cf-connecting-ip');
+  if (cfIp) return cfIp;
+  // Standard proxy headers
+  const xff = request.headers.get('x-forwarded-for');
+  if (xff) return xff.split(',')[0].trim();
+  const realIp = request.headers.get('x-real-ip');
+  if (realIp) return realIp;
+  return '127.0.0.1';
+}
+
+/**
+ * Next.js API route handler for browser error reporting.
+ *
+ * Create `app/orkify/errors/route.ts`:
+ * ```ts
+ * export { POST } from '@orkify/next/error-handler';
+ * ```
+ */
+export async function POST(request: Request): Promise<Response> {
+  try {
+    // 1. Validate origin — browsers always send Origin on POST requests.
+    //    This blocks cross-origin abuse and non-browser clients (curl/bots).
+    //    Behind reverse proxies (nginx, Cloudflare), Host may be internal
+    //    while Origin is public. X-Forwarded-Host carries the original Host.
+    const origin = request.headers.get('origin');
+    if (!origin) {
+      return Response.json({ ok: false }, { status: 403 });
+    }
+    const effectiveHost = request.headers.get('x-forwarded-host') || request.headers.get('host');
+    if (effectiveHost) {
+      try {
+        const originHost = new URL(origin).host;
+        if (originHost !== effectiveHost) {
+          return Response.json({ ok: false }, { status: 403 });
+        }
+      } catch {
+        return Response.json({ ok: false }, { status: 403 });
+      }
+    }
+
+    // 2. Check content length
+    const contentLength = request.headers.get('content-length');
+    if (contentLength && parseInt(contentLength, 10) > MAX_BODY_SIZE) {
+      return Response.json({ ok: false }, { status: 413 });
+    }
+
+    // 3. Rate limit
+    const ip = getClientIp(request);
+    if (isRateLimited(ip)) {
+      return Response.json({ ok: false }, { status: 429 });
+    }
+
+    // 4. Parse and validate body
+    const raw = await request.text();
+    if (raw.length > MAX_BODY_SIZE) {
+      return Response.json({ ok: false }, { status: 413 });
+    }
+
+    let body: unknown;
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      return Response.json({ ok: false }, { status: 400 });
+    }
+
+    const parsed = browserErrorSchema.safeParse(body);
+    if (!parsed.success) {
+      return Response.json({ ok: false }, { status: 400 });
+    }
+
+    const data = parsed.data;
+
+    // 5. Truncate stack to max lines
+    const stackLines = data.stack.split('\n');
+    const truncatedStack =
+      stackLines.length > MAX_STACK_LINES
+        ? stackLines.slice(0, MAX_STACK_LINES).join('\n')
+        : data.stack;
+
+    // 6. Parse browser stack → frames, map URLs to file paths
+    const cwd = process.cwd();
+    const frames = parseBrowserFrames(truncatedStack, cwd);
+
+    // 7. Build source context from bundled files on disk
+    const sourceContext = frames.length > 0 ? buildSourceContext(frames) : null;
+    const topFrame = frames[0] ?? null;
+
+    // 8. Relay to daemon via IPC
+    if (typeof process.send === 'function') {
+      process.send({
+        __orkify: true,
+        type: 'error',
+        data: {
+          errorType: data.errorType,
+          name: data.name,
+          message: data.message,
+          stack: truncatedStack,
+          fingerprint: '', // Daemon recomputes this
+          sourceContext: sourceContext && sourceContext.length > 0 ? sourceContext : null,
+          topFrame,
+          diagnostics: null,
+          timestamp: data.timestamp,
+          nodeVersion: '',
+          pid: 0,
+          url: data.url,
+          userAgent: data.userAgent,
+        },
+      });
+    }
+
+    return Response.json({ ok: true });
+  } catch {
+    // Never crash the app for error reporting
+    return Response.json({ ok: true });
+  }
+}

package/packages/next/src/isr-cache.ts

@@ -0,0 +1,100 @@
+import { cache } from '@orkify/cache';
+
+/**
+ * ISR / route cache handler for Next.js (`cacheHandler` config).
+ * Next.js instantiates this with `new`, so it must be a class.
+ *
+ * Next.js expects `get()` to return `{ value, lastModified }` (the
+ * `CacheHandlerValue` interface), so we wrap/unwrap around the raw
+ * `IncrementalCacheValue` when storing in orkify/cache.
+ *
+ * During `next build`, this handler is a no-op — data stored in-memory
+ * would be lost when the build process exits, causing invariant errors
+ * at runtime when Next.js expects cached pages that no longer exist.
+ * Pre-rendered pages are still served from disk (`.next/server/app/`).
+ *
+ * Headers objects (used by APP_ROUTE responses) don't survive V8
+ * structured clone (IPC in cluster mode). We convert them to plain
+ * objects on set so they work with both IPC and bracket-notation
+ * access in Next.js internals.
+ *
+ * Cache tags are extracted from the `x-next-cache-tags` header (set by
+ * Next.js for APP_PAGE/APP_ROUTE) and registered in orkify's tag index
+ * so `revalidateTag()` → `cache.invalidateTag()` can find entries.
+ */
+const IS_BUILD = process.env.NEXT_PHASE === 'phase-production-build';
+const NEXT_CACHE_TAGS_HEADER = 'x-next-cache-tags';
+
+interface StoredEntry {
+  lastModified: number;
+  value: null | Record<string, unknown>;
+}
+
+/** Convert Headers to a plain object. Non-Headers pass through. */
+function headersToPlainObject(headers: unknown): Record<string, string> | undefined {
+  if (!headers) return undefined;
+  if (headers instanceof Headers) {
+    return Object.fromEntries([...(headers as Headers).entries()]);
+  }
+  if (Array.isArray(headers)) {
+    // entries array from a previous version — normalize to plain object
+    return Object.fromEntries(headers);
+  }
+  return headers as Record<string, string>;
+}
+
+/** Extract cache tags from the x-next-cache-tags header value. */
+function extractTags(headers: Record<string, string> | undefined): string[] | undefined {
+  const tagHeader = headers?.[NEXT_CACHE_TAGS_HEADER];
+  if (typeof tagHeader === 'string' && tagHeader.length > 0) {
+    return tagHeader.split(',');
+  }
+  return undefined;
+}
+
+export default class OrkifyCacheHandler {
+  async get(key: string): Promise<null | unknown> {
+    if (IS_BUILD) return null;
+
+    const stored = await cache.getAsync<StoredEntry>(key);
+    if (!stored) return null;
+
+    return stored;
+  }
+
+  async set(key: string, data: unknown, ctx?: { tags?: string[] }): Promise<void> {
+    if (IS_BUILD) return;
+
+    let value = data as null | Record<string, unknown>;
+
+    // Normalize Headers objects to plain objects for IPC and bracket-notation access
+    if (value && 'headers' in value) {
+      const plainHeaders = headersToPlainObject(value.headers);
+      if (plainHeaders !== value.headers) {
+        value = { ...value, headers: plainHeaders };
+      }
+    }
+
+    // Gather tags: merge explicit ctx.tags with x-next-cache-tags header (deduplicated)
+    const headerTags = value ? extractTags(value.headers as Record<string, string>) : undefined;
+    const mergedTags =
+      ctx?.tags && headerTags
+        ? [...new Set([...ctx.tags, ...headerTags])]
+        : (ctx?.tags ?? headerTags);
+    const tags = mergedTags && mergedTags.length > 0 ? mergedTags : undefined;
+
+    const entry: StoredEntry = { value, lastModified: Date.now() };
+    cache.set(key, entry, tags ? { tags } : undefined);
+  }
+
+  async revalidateTag(tag: string | string[]): Promise<void> {
+    const tags = Array.isArray(tag) ? tag : [tag];
+    for (const t of tags) {
+      cache.invalidateTag(t);
+    }
+  }
+
+  resetRequestCache(): void {
+    // No-op — shared cache, not per-request
+  }
+}

package/packages/next/src/stream.ts

@@ -0,0 +1,23 @@
+/** Consume a ReadableStream into a single Buffer. */
+export async function streamToBuffer(stream: ReadableStream<Uint8Array>): Promise<Buffer> {
+  const chunks: Uint8Array[] = [];
+  const reader = stream.getReader();
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks);
+}
+
+/** Create a single-chunk ReadableStream from a Buffer. */
+export function bufferToStream(buffer: Buffer): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new Uint8Array(buffer));
+      controller.close();
+    },
+  });
+}

package/packages/next/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Next.js cache handler interfaces, mirrored here so orkify doesn't
+ * depend on `next` as a package dependency.
+ */
+
+/** What Next.js passes to / expects from the 'use cache' handler. */
+export interface NextCacheEntry {
+  expire: number; // seconds, hard max lifetime
+  revalidate: number; // seconds, revalidation interval
+  stale: number; // seconds
+  tags: string[];
+  timestamp: number; // ms, when created
+  value: ReadableStream<Uint8Array>;
+}
+
+/** 'use cache' handler — 5 methods. */
+export interface NextCacheHandler {
+  get(cacheKey: string, softTags: string[]): Promise<NextCacheEntry | undefined>;
+  getExpiration(tags: string[]): Promise<number>;
+  refreshTags(): Promise<void>;
+  set(cacheKey: string, pendingEntry: Promise<NextCacheEntry>): Promise<void>;
+  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;
+}
+
+/** What we actually store in orkify/cache (Buffer instead of stream). */
+export interface StoredCacheEntry {
+  buffer: Buffer;
+  expire: number;
+  revalidate: number;
+  stale: number;
+  tags: string[];
+  timestamp: number;
+}