@djangocfg/devtools 2.1.459

package/README.md

@@ -0,0 +1,41 @@
+# @djangocfg/devtools
+
+Frontend devtools for django-cfg apps. One package, one event stream:
+
+- **Capture** — `window.onerror`, unhandled rejections, `console.warn/error`,
+  zod validation events from `@djangocfg/api` clients.
+- **Ingest** — errors/warnings are batched to `POST /cfg/monitor/ingest/`
+  (django-cfg's `django_monitor` extension) with dedupe, keepalive flush on
+  unload, and a circuit breaker.
+- **Debug panel** — floating button (auto in dev, `?debug=1` in prod, ⌘D)
+  with a filterable log feed and app-defined custom tabs.
+
+Replaces the retired `@djangocfg/monitor` + `@djangocfg/debuger` pair.
+
+## Usage
+
+```tsx
+// Root layout — that's the whole setup
+import { Devtools } from '@djangocfg/devtools'
+
+<Devtools project="my-app" environment={process.env.NODE_ENV} />
+```
+
+```ts
+// Anywhere in client code
+import { devtools } from '@djangocfg/devtools'
+
+devtools.error('Payment widget crashed', { orderId })   // panel + backend
+const log = devtools.log('CheckoutForm')                // panel only
+log.info('step changed', { step })
+```
+
+```ts
+// Server (route handlers / RSC)
+import { serverDevtools } from '@djangocfg/devtools/server'
+
+serverDevtools.configure({ project: 'my-app', baseUrl: process.env.API_URL })
+await serverDevtools.captureError(err, { url: req.url })
+```
+
+In the browser console: `window.devtools.status()`, `window.devtools.error('test')`.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@djangocfg/devtools",
+  "version": "2.1.459",
+  "description": "Frontend devtools for django-cfg apps: error/console capture with backend ingest, plus a floating debug panel. One package, one event stream.",
+  "keywords": [
+    "django",
+    "devtools",
+    "debug-panel",
+    "error-tracking",
+    "monitoring",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "packages/devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "import": "./src/server.ts",
+      "require": "./src/server.ts"
+    },
+    "./styles": "./src/styles.css"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "@djangocfg/ui-core": "^2.1.459",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.459",
+    "@djangocfg/ui-core": "^2.1.459",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.15",
+    "lucide-react": "^0.545.0",
+    "typescript": "^5.9.3",
+    "zustand": "^5.0.0"
+  }
+}

package/src/Devtools.tsx

@@ -0,0 +1,48 @@
+'use client'
+
+/**
+ * <Devtools /> — the one component.
+ *
+ * Drop it once into the app root; it installs error/console capture with
+ * backend ingest AND renders the floating debug button + panel. Replaces the
+ * old MonitorProvider + DebugButton + monitorBridge trio.
+ *
+ * @example
+ * // app/layout.tsx (or BaseApp)
+ * import { Devtools } from '@djangocfg/devtools'
+ *
+ * <Devtools project="my-app" environment={process.env.NODE_ENV} />
+ */
+
+import React, { memo, useEffect } from 'react'
+
+import { devtools } from './instance'
+import { DevtoolsButton } from './panel/DevtoolsButton'
+import type { DevtoolsPanelProps } from './panel/DevtoolsPanel'
+import type { DevtoolsConfig } from './types'
+
+export interface DevtoolsProps extends DevtoolsConfig {
+  /** Panel customization (custom tabs, position, size) */
+  panel?: DevtoolsPanelProps
+  /** Hide the debug button entirely (capture + ingest still run). `?debug=1` overrides. */
+  button?: boolean
+  children?: React.ReactNode
+}
+
+function DevtoolsRaw({ panel, button, children, ...config }: DevtoolsProps) {
+  useEffect(() => {
+    devtools.init(config)
+    return () => devtools.destroy()
+    // Init once per mount — config is captured in the closure.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return (
+    <>
+      {children}
+      <DevtoolsButton enabled={button} panel={panel} />
+    </>
+  )
+}
+
+export const Devtools = memo(DevtoolsRaw)

package/src/capture.ts

@@ -0,0 +1,175 @@
+/**
+ * Browser capture hooks. Each installer returns its cleanup function.
+ * Everything funnels into `devtoolsStore.capture()` — dedupe, panel entry,
+ * and ingest buffering all happen there, once.
+ */
+
+import { devtoolsStore } from './store'
+import { INGEST_PATTERN, getSessionId, truncate } from './internal'
+import { EventLevel, EventType } from './types'
+import type { DevtoolsEvent } from './types'
+
+const MSG_MAX = 2000
+const ARG_MAX = 500
+
+// Hydration mismatches caused by browser extensions (Grammarly, translators…).
+// Not application bugs — filtering them prevents alert noise.
+const HYDRATION_NOISE: RegExp[] = [
+  /hydration failed/i,
+  /there was an error while hydrating/i,
+  /minified react error #418/i,
+  /minified react error #423/i,
+  /minified react error #425/i,
+  /text content does not match server-rendered html/i,
+]
+
+function isNoise(msg: string, stack?: string): boolean {
+  if (HYDRATION_NOISE.some((p) => p.test(msg))) return true
+  // Our own transport failing must never loop back into capture.
+  return INGEST_PATTERN.test(msg) || INGEST_PATTERN.test(stack ?? '')
+}
+
+function browserContext(): Pick<DevtoolsEvent, 'url' | 'session_id' | 'user_agent'> {
+  return {
+    url: typeof window !== 'undefined' ? window.location.href : '',
+    session_id: getSessionId(),
+    user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+  }
+}
+
+// ─── window.onerror + unhandledrejection ────────────────────────────────────
+
+export function installJsErrorCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  const report = (msg: string, stack: string) => {
+    try {
+      if (isNoise(msg, stack)) return
+      devtoolsStore.getState().capture({
+        event_type: EventType.JS_ERROR,
+        level: EventLevel.ERROR,
+        message: truncate(msg, MSG_MAX),
+        stack_trace: stack,
+        ...browserContext(),
+      })
+    } catch {
+      /* never crash the host app */
+    }
+  }
+
+  const onError = (e: ErrorEvent) => {
+    const msg = e.message || String(e.error ?? 'Unknown error')
+    report(msg, e.error?.stack ?? `at ${e.filename}:${e.lineno}:${e.colno}`)
+  }
+
+  const onRejection = (e: PromiseRejectionEvent) => {
+    const reason = e.reason
+    const msg =
+      reason instanceof Error
+        ? reason.message
+        : typeof reason === 'string'
+          ? reason
+          : 'Unhandled promise rejection'
+    report(msg, reason instanceof Error ? (reason.stack ?? '') : '')
+  }
+
+  window.addEventListener('error', onError)
+  window.addEventListener('unhandledrejection', onRejection)
+  return () => {
+    window.removeEventListener('error', onError)
+    window.removeEventListener('unhandledrejection', onRejection)
+  }
+}
+
+// ─── console.warn / console.error ────────────────────────────────────────────
+
+function stringifyArgs(args: unknown[]): string {
+  return args
+    .map((a) => {
+      let s: string
+      if (typeof a === 'string') s = a
+      else if (a instanceof Error) s = a.message
+      else {
+        try {
+          s = JSON.stringify(a)
+        } catch {
+          s = String(a)
+        }
+      }
+      return truncate(s, ARG_MAX)
+    })
+    .join(' ')
+}
+
+export function installConsoleCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  const report = (level: 'warn' | 'error', args: unknown[]) => {
+    try {
+      const message = stringifyArgs(args)
+      const stack = args.find((a): a is Error => a instanceof Error)?.stack
+      if (isNoise(message, stack)) return
+      devtoolsStore.getState().capture({
+        event_type: level === 'error' ? EventType.ERROR : EventType.WARNING,
+        level: level === 'error' ? EventLevel.ERROR : EventLevel.WARNING,
+        message,
+        stack_trace: stack,
+        ...browserContext(),
+      })
+    } catch {
+      /* never crash */
+    }
+  }
+
+  const origWarn = console.warn.bind(console)
+  const origError = console.error.bind(console)
+  console.warn = (...args: unknown[]) => {
+    origWarn(...args)
+    report('warn', args)
+  }
+  console.error = (...args: unknown[]) => {
+    origError(...args)
+    report('error', args)
+  }
+  return () => {
+    console.warn = origWarn
+    console.error = origError
+  }
+}
+
+// ─── zod-validation-error events (fired by @djangocfg/api clients) ──────────
+
+interface ValidationErrorDetail {
+  operation: string
+  path: string
+  method: string
+  error: { message: string }
+}
+
+export function installValidationCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  const handler = (event: Event) => {
+    if (!(event instanceof CustomEvent)) return
+    try {
+      const detail = event.detail as ValidationErrorDetail
+      devtoolsStore.getState().capture({
+        event_type: EventType.WARNING,
+        level: EventLevel.WARNING,
+        message: truncate(
+          `Zod validation error in ${detail.operation}: ${detail.error?.message ?? 'unknown'}`,
+          MSG_MAX,
+        ),
+        http_method: detail.method,
+        http_url: detail.path,
+        extra: { operation: detail.operation, path: detail.path, method: detail.method },
+        ...browserContext(),
+      })
+    } catch {
+      /* never crash */
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+  return () => window.removeEventListener('zod-validation-error', handler)
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @djangocfg/devtools — client entry.
+ *
+ * One package for frontend observability in django-cfg apps:
+ * - `<Devtools />`: error/console capture + backend ingest + debug panel
+ * - `devtools`: imperative capture API + component-scoped local loggers
+ * - also available in the browser console as `window.devtools`
+ *
+ * Server-side reporting lives in `@djangocfg/devtools/server`.
+ */
+
+// The component
+export { Devtools } from './Devtools'
+export type { DevtoolsProps } from './Devtools'
+
+// Imperative API
+export { devtools } from './instance'
+export type { DevtoolsApi } from './instance'
+
+// Store (advanced: custom tabs subscribing to the entry feed)
+export { devtoolsStore } from './store'
+export type { DevtoolsState } from './store'
+
+// Types
+export { EventLevel, EventType } from './types'
+export type {
+  CustomDebugTab,
+  DevtoolsConfig,
+  DevtoolsEvent,
+  LogEntry,
+  Logger,
+  LogLevel,
+  ServerDevtoolsConfig,
+} from './types'
+
+// Panel pieces (for apps that want the panel without the auto button)
+export { DevtoolsButton } from './panel/DevtoolsButton'
+export type { DevtoolsButtonProps } from './panel/DevtoolsButton'
+export { DevtoolsPanel } from './panel/DevtoolsPanel'
+export type { DevtoolsPanelProps } from './panel/DevtoolsPanel'
+
+// Utilities
+export { useDebugMode } from './useDebugMode'
+export { getSessionId, isDevelopment, isProduction } from './internal'

package/src/ingest.ts

@@ -0,0 +1,27 @@
+/**
+ * Ingest transport — one plain fetch to `POST /cfg/monitor/ingest/`.
+ *
+ * The endpoint is AllowAny + rate-limited on the backend and always answers
+ * 202; nothing here needs auth headers or a generated client. `keepalive` is
+ * used on page-unload flushes so the request survives the document.
+ */
+
+import { INGEST_PATH } from './internal'
+import type { DevtoolsEvent } from './types'
+
+export async function sendBatch(
+  baseUrl: string,
+  events: DevtoolsEvent[],
+  useBeacon = false,
+): Promise<void> {
+  if (events.length === 0) return
+
+  const res = await fetch(`${baseUrl}${INGEST_PATH}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ events }),
+    credentials: 'include',
+    ...(useBeacon ? { keepalive: true } : {}),
+  })
+  if (!res.ok) throw new Error(`ingest ${res.status}`)
+}

package/src/instance.ts

@@ -0,0 +1,185 @@
+/**
+ * The `devtools` singleton — the imperative API.
+ *
+ * React apps normally never call `init`/`destroy` directly; the `<Devtools />`
+ * component does. Everything else (`capture`, `error`, `log`) is safe to call
+ * from anywhere, any time — before init it just fills the panel feed.
+ *
+ * From the browser console the same API is available as `window.devtools`.
+ */
+
+import {
+  installConsoleCapture,
+  installJsErrorCapture,
+  installValidationCapture,
+} from './capture'
+import { DEFAULT_FLUSH_INTERVAL, getSessionId, isDevelopment } from './internal'
+import { devtoolsStore } from './store'
+import { EventLevel, EventType } from './types'
+import type { DevtoolsConfig, DevtoolsEvent, Logger } from './types'
+
+let flushTimer: ReturnType<typeof setInterval> | null = null
+const cleanups: Array<() => void> = []
+
+function makeEvent(
+  type: EventType,
+  level: EventLevel,
+  message: string,
+  extra?: Record<string, unknown>,
+): DevtoolsEvent {
+  return {
+    event_type: type,
+    level,
+    message,
+    url: typeof window !== 'undefined' ? window.location.href : '',
+    session_id: getSessionId(),
+    user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+    ...(extra ? { extra } : {}),
+  }
+}
+
+/** Pull an Error out of `data.error` so the panel gets a proper stack. */
+function extractStack(data?: Record<string, unknown>): {
+  cleanData?: Record<string, unknown>
+  stack?: string
+} {
+  if (!data) return {}
+  const cleanData = { ...data }
+  let stack: string | undefined
+  const err = data.error
+  if (err instanceof Error) {
+    stack = err.stack
+    cleanData.error = { name: err.name, message: err.message }
+  } else if (typeof err === 'object' && err !== null) {
+    const e = err as Record<string, unknown>
+    if (typeof e.stack === 'string') stack = e.stack
+    if (typeof e.message === 'string') cleanData.error = e.message
+  }
+  return { cleanData, stack }
+}
+
+export const devtools = {
+  /** Install capture hooks + start the ingest pump. Idempotent per mount. */
+  init(config: DevtoolsConfig = {}): void {
+    if (typeof window === 'undefined') return
+
+    const resolved: DevtoolsConfig = {
+      ...config,
+      baseUrl: config.baseUrl ?? process.env.NEXT_PUBLIC_API_URL ?? '',
+    }
+    devtoolsStore.getState().setConfig(resolved)
+    getSessionId() // ensure the session cookie exists
+
+    if (resolved.captureJsErrors !== false) cleanups.push(installJsErrorCapture())
+    if (resolved.captureConsole !== false) cleanups.push(installConsoleCapture())
+    cleanups.push(installValidationCapture())
+
+    flushTimer = setInterval(
+      () => devtoolsStore.getState().flush(),
+      resolved.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
+    )
+    const onHide = () => {
+      if (document.visibilityState === 'hidden') devtoolsStore.getState().flush(true)
+    }
+    document.addEventListener('visibilitychange', onHide)
+    cleanups.push(() => document.removeEventListener('visibilitychange', onHide))
+
+    window.devtools = devtools
+
+    if (resolved.debug) console.info('[devtools] initialized', resolved)
+  },
+
+  destroy(): void {
+    if (flushTimer !== null) {
+      clearInterval(flushTimer)
+      flushTimer = null
+    }
+    cleanups.forEach((fn) => fn())
+    cleanups.length = 0
+  },
+
+  /** Capture a raw event (panel + backend ingest). */
+  capture(event: DevtoolsEvent): void {
+    devtoolsStore.getState().capture(event)
+  },
+
+  error(message: string, extra?: Record<string, unknown>): void {
+    devtoolsStore.getState().capture(makeEvent(EventType.JS_ERROR, EventLevel.ERROR, message, extra))
+  },
+
+  warn(message: string, extra?: Record<string, unknown>): void {
+    devtoolsStore.getState().capture(makeEvent(EventType.WARNING, EventLevel.WARNING, message, extra))
+  },
+
+  info(message: string, extra?: Record<string, unknown>): void {
+    devtoolsStore.getState().capture(makeEvent(EventType.WARNING, EventLevel.INFO, message, extra))
+  },
+
+  network(status: number, method: string, url: string, extra?: Record<string, unknown>): void {
+    devtoolsStore.getState().capture({
+      ...makeEvent(
+        EventType.NETWORK_ERROR,
+        status >= 500 ? EventLevel.ERROR : EventLevel.WARNING,
+        `${method} ${url} → ${status}`,
+        extra,
+      ),
+      http_status: status,
+      http_method: method,
+      http_url: url,
+    })
+  },
+
+  /**
+   * Component-scoped local logger. Entries go to the debug panel (and the
+   * console in dev) — never to the backend. For "send this to the backend",
+   * use `capture`/`error` instead.
+   */
+  log(source: string): Logger {
+    const write = (
+      level: 'debug' | 'info' | 'warn' | 'error' | 'success',
+      message: string,
+      data?: Record<string, unknown>,
+    ) => {
+      const { cleanData, stack } = extractStack(data)
+      if (typeof window !== 'undefined') {
+        devtoolsStore.getState().addEntry({ level, source, message, data: cleanData, stack })
+      }
+      if (isDevelopment) {
+        const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log'
+        if (cleanData) console[method](`[${source}]`, message, cleanData)
+        else console[method](`[${source}]`, message)
+      }
+    }
+    return {
+      debug: (msg, data) => write('debug', msg, data),
+      info: (msg, data) => write('info', msg, data),
+      warn: (msg, data) => write('warn', msg, data),
+      error: (msg, data) => write('error', msg, data),
+      success: (msg, data) => write('success', msg, data),
+    }
+  },
+
+  /** Force-flush the ingest outbox. */
+  flush(): void {
+    devtoolsStore.getState().flush()
+  },
+
+  /** Print current state to the console (for `window.devtools.status()`). */
+  status(): void {
+    const s = devtoolsStore.getState()
+    console.group('[devtools] status')
+    console.log('config:', s.config)
+    console.log('panel entries:', s.entries.length)
+    console.log('ingest outbox:', s.outbox.length)
+    console.log('session_id:', getSessionId())
+    console.groupEnd()
+  },
+}
+
+export type DevtoolsApi = typeof devtools
+
+declare global {
+  interface Window {
+    devtools?: DevtoolsApi
+  }
+}

package/src/internal.ts

@@ -0,0 +1,85 @@
+/**
+ * Internal utilities: environment, session identity, fingerprinting, dedupe.
+ */
+
+// ─── Environment ─────────────────────────────────────────────────────────────
+
+/** True only in next dev / jest / vitest */
+export const isDevelopment = process.env.NODE_ENV === 'development'
+
+/** True in any non-development environment */
+export const isProduction = !isDevelopment
+
+/** Ingest endpoint (django_monitor extension). */
+export const INGEST_PATH = '/cfg/monitor/ingest/'
+
+/** Matches requests to the ingest endpoint — prevents capture→flush feedback loops. */
+export const INGEST_PATTERN = /cfg\/monitor\/ingest/
+
+export const DEFAULT_DEDUPE_TTL = 30_000
+export const DEFAULT_FLUSH_INTERVAL = 5_000
+export const DEFAULT_MAX_BUFFER = 20
+
+// ─── Session identity ────────────────────────────────────────────────────────
+// Key kept from @djangocfg/monitor so existing visitors keep their session id.
+
+const SESSION_KEY = 'fm_session_id'
+const COOKIE_MAX_AGE = 60 * 60 * 24 * 365
+
+function generateUUID(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID()
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16)
+  })
+}
+
+export function getSessionId(): string {
+  if (typeof localStorage === 'undefined') return ''
+  try {
+    let id = localStorage.getItem(SESSION_KEY)
+    if (!id) {
+      id = generateUUID()
+      localStorage.setItem(SESSION_KEY, id)
+      document.cookie = `${SESSION_KEY}=${id}; path=/; SameSite=Lax; max-age=${COOKIE_MAX_AGE}`
+    }
+    return id
+  } catch {
+    return ''
+  }
+}
+
+// ─── Fingerprint (sync — no crypto.subtle round-trip needed for dedup) ──────
+
+export function computeFingerprint(message: string, stack: string, url: string): string {
+  const raw = `${message}|${stack}|${url}`
+  let hash = 0
+  for (let i = 0; i < raw.length; i++) {
+    hash = (hash << 5) - hash + raw.charCodeAt(i)
+    hash = hash & hash
+  }
+  return Math.abs(hash).toString(16).padStart(8, '0')
+}
+
+// ─── Dedupe ──────────────────────────────────────────────────────────────────
+
+/** TTL-based seen-set with a size cap. One instance guards one capture path. */
+export function makeDeduper(max = 200): (key: string, ttl: number) => boolean {
+  const seen = new Map<string, number>()
+  return (key, ttl) => {
+    const now = Date.now()
+    const last = seen.get(key)
+    if (last !== undefined && now - last < ttl) return true
+    seen.set(key, now)
+    if (seen.size > max) {
+      for (const [k, ts] of seen) {
+        if (now - ts > ttl) seen.delete(k)
+      }
+    }
+    return false
+  }
+}
+
+export function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s
+}