@beignet/devtools 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/devtools",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "description": "Development-time devtools for Beignet - mini Telescope for the server runtime",
   "main": "./dist/index.js",

package/src/access.ts

@@ -1,9 +1,18 @@
+/**
+ * Result returned by a devtools authorization check.
+ */
 export type DevtoolsAuthorizeResult = boolean | Response;
 
+/**
+ * App-owned authorization callback for devtools routes.
+ */
 export type DevtoolsAuthorize = (
   req: Request,
 ) => DevtoolsAuthorizeResult | Promise<DevtoolsAuthorizeResult>;
 
+/**
+ * Access control options for devtools HTTP routes.
+ */
 export interface DevtoolsRouteAccessOptions {
   /**
    * Whether the devtools route should be exposed.
@@ -21,16 +30,27 @@ export interface DevtoolsRouteAccessOptions {
   authorize?: DevtoolsAuthorize;
 }
 
+/**
+ * Resolve whether devtools routes should be exposed.
+ *
+ * Defaults to disabled in production and enabled elsewhere.
+ */
 export function isDevtoolsRouteEnabled(
   options: DevtoolsRouteAccessOptions = {},
 ): boolean {
   return options.enabled ?? process.env.NODE_ENV !== "production";
 }
 
+/**
+ * Return the standard hidden devtools response.
+ */
 export function devtoolsNotFoundResponse(): Response {
   return new Response("Not Found", { status: 404 });
 }
 
+/**
+ * Authorize a devtools request and return a denial response when blocked.
+ */
 export async function authorizeDevtoolsRequest(
   req: Request,
   options: DevtoolsRouteAccessOptions = {},

package/src/audit.ts

@@ -7,10 +7,25 @@ import {
 } from "@beignet/core/ports";
 import type { DevtoolsPort } from "./index";
 
+/**
+ * Options for wrapping an audit log with devtools emission.
+ */
 export interface DevtoolsAuditLogOptions {
+  /**
+   * Durable audit log to write first.
+   */
   audit: AuditLogPort;
+  /**
+   * Optional devtools port that receives audit events.
+   */
   devtools?: DevtoolsPort;
+  /**
+   * Whether to emit devtools events. Defaults to true.
+   */
   emit?: boolean;
+  /**
+   * Optional app-owned redactor applied after Beignet's audit redaction.
+   */
   redact?: (entry: AuditLogEntry) => AuditLogEntry;
 }
 
@@ -32,6 +47,12 @@ function auditSummary(entry: AuditLogEntry): string {
     : `${entry.action} ${outcome}`;
 }
 
+/**
+ * Wrap an audit log so durable audit writes can also appear in devtools.
+ *
+ * Devtools observer failures are ignored so audit persistence remains the
+ * source of truth.
+ */
 export function createDevtoolsAuditLog(
   options: DevtoolsAuditLogOptions,
 ): AuditLogPort {

package/src/events.ts

@@ -110,7 +110,13 @@ export interface EventBusEvent extends BaseDevtoolsEvent {
 export interface JobEvent extends BaseDevtoolsEvent {
   type: "job";
   jobName: string;
-  status: "scheduled" | "started" | "completed" | "failed";
+  status:
+    | "scheduled"
+    | "started"
+    | "completed"
+    | "failed"
+    | "retryScheduled"
+    | "deadLettered";
 }
 
 /**
@@ -156,14 +162,23 @@ export type DevtoolsEvent =
   | ProviderEvent
   | CustomDevtoolsEvent;
 
+/**
+ * Input accepted by `createDevtoolsEvent(...)`.
+ */
 export type DevtoolsEventInput = DevtoolsEvent extends infer Event
   ? Event extends DevtoolsEvent
     ? Omit<Event, "id" | "timestamp"> & Partial<Pick<Event, "id" | "timestamp">>
     : never
   : never;
 
+/**
+ * Function that redacts a normalized devtools event before storage.
+ */
 export type DevtoolsRedactor = (event: DevtoolsEvent) => DevtoolsEvent;
 
+/**
+ * Event emitted to live devtools subscribers.
+ */
 export type DevtoolsSubscriptionEvent =
   | {
       type: "record";
@@ -173,8 +188,14 @@ export type DevtoolsSubscriptionEvent =
       type: "clear";
     };
 
+/**
+ * Devtools subscription listener.
+ */
 export type DevtoolsListener = (event: DevtoolsSubscriptionEvent) => void;
 
+/**
+ * All built-in devtools event types.
+ */
 export const DEVTOOLS_EVENT_TYPES = [
   "request",
   "error",
@@ -186,6 +207,9 @@ export const DEVTOOLS_EVENT_TYPES = [
   "custom",
 ] as const satisfies readonly DevtoolsEvent["type"][];
 
+/**
+ * Check whether a string is a built-in devtools event type.
+ */
 export function isDevtoolsEventType(
   value: string,
 ): value is DevtoolsEvent["type"] {

package/src/instrumentation.ts

@@ -32,6 +32,9 @@ type ContextWithPorts = {
   };
 };
 
+/**
+ * Options for server hooks that record request/error events to devtools.
+ */
 export interface DevtoolsHooksOptions<Ctx> {
   /**
    * Devtools route prefix. Requests under this path are ignored to avoid
@@ -41,6 +44,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   basePath?: string;
 
+  /**
+   * Resolve the request ID used for event correlation.
+   */
   getRequestId?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -66,6 +72,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   traceContextHeader?: string | false;
 
+  /**
+   * Resolve a trace context from request/context/response data.
+   */
   getTraceContext?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -78,6 +87,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   redact?: DevtoolsRedactor;
 
+  /**
+   * Decide whether to capture a completed request event.
+   */
   shouldCapture?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -87,6 +99,9 @@ export interface DevtoolsHooksOptions<Ctx> {
   }) => boolean;
 }
 
+/**
+ * Use-case run event shape consumed by the devtools observer.
+ */
 export interface DevtoolsUseCaseRunEvent<Ctx> {
   name: string;
   kind: "command" | "query";
@@ -96,10 +111,25 @@ export interface DevtoolsUseCaseRunEvent<Ctx> {
   ctx: Ctx;
 }
 
+/**
+ * Options for `createDevtoolsUseCaseObserver(...)`.
+ */
 export interface DevtoolsUseCaseObserverOptions<Ctx> {
+  /**
+   * Resolve a devtools port from use-case context.
+   */
   getDevtools?: (ctx: Ctx) => DevtoolsPort | undefined;
+  /**
+   * Resolve the request ID used for event correlation.
+   */
   getRequestId?: (ctx: Ctx) => string | undefined;
+  /**
+   * Whether use-case error phases should also emit `error` events.
+   */
   logErrorEvents?: boolean;
+  /**
+   * Optional redactor applied before events are recorded.
+   */
   redact?: DevtoolsRedactor;
 }
 
@@ -175,6 +205,13 @@ function isWatcherEnabled(
   return devtools.isWatcherEnabled(name);
 }
 
+/**
+ * Create server hooks that record Beignet request and error activity.
+ *
+ * Devtools routes under `basePath` are ignored so polling and SSE traffic do not
+ * fill the event buffer. Request IDs and trace context are also written to
+ * response headers unless disabled.
+ */
 export function createDevtoolsHooks<
   Ctx,
   Ports extends PortsWithDevtools = PortsWithDevtools,
@@ -359,6 +396,9 @@ export function createDevtoolsHooks<
   };
 }
 
+/**
+ * Create a use-case observer compatible with `createUseCase({ onRun })`.
+ */
 export function createDevtoolsUseCaseObserver<Ctx>(
   options: DevtoolsUseCaseObserverOptions<Ctx> = {},
 ): (event: DevtoolsUseCaseRunEvent<Ctx>) => void {

package/src/persistence.ts

@@ -1,15 +1,33 @@
 import type { DevtoolsEvent } from "./events";
 
+/**
+ * Persistence interface for devtools event stores.
+ */
 export interface DevtoolsEventStore {
+  /**
+   * Store name used in diagnostics.
+   */
   name?: string;
+  /**
+   * Load persisted events at startup.
+   */
   load?(): DevtoolsEvent[] | Promise<DevtoolsEvent[]>;
+  /**
+   * Append one event. The second argument is the current bounded buffer.
+   */
   append?(
     event: DevtoolsEvent,
     events: readonly DevtoolsEvent[],
   ): void | Promise<void>;
+  /**
+   * Clear persisted events.
+   */
   clear?(): void | Promise<void>;
 }
 
+/**
+ * Options for the Node-only file-backed devtools store.
+ */
 export interface FileDevtoolsStoreOptions {
   /**
    * JSONL file used for persisted devtools events.
@@ -80,6 +98,12 @@ async function loadNodeModules(): Promise<{
   return { fs, path };
 }
 
+/**
+ * Create a JSONL file-backed devtools store.
+ *
+ * This store lazily imports Node fs/path modules and is intended for Node
+ * runtimes. It compacts periodically to keep the persisted file bounded.
+ */
 export function createFileDevtoolsStore(
   options: FileDevtoolsStoreOptions = {},
 ): DevtoolsEventStore {

package/src/provider-instrumentation.ts

@@ -7,11 +7,25 @@ import {
 } from "@beignet/core/providers";
 import type { DevtoolsPort } from "./index";
 
+/**
+ * Provider devtools instrumentation options.
+ */
 export type ProviderDevtoolsOptions = ProviderInstrumentationOptions;
+
+/**
+ * Custom provider event input accepted by provider devtools instrumentation.
+ */
 export type ProviderCustomDevtoolsEventInput =
   ProviderCustomInstrumentationEventInput;
+
+/**
+ * Provider instrumentation object backed by devtools.
+ */
 export type ProviderDevtools = ProviderInstrumentation;
 
+/**
+ * Check whether an unknown value implements the devtools port shape.
+ */
 export function isDevtoolsPort(value: unknown): value is DevtoolsPort {
   return (
     isProviderInstrumentationPort(value) &&
@@ -24,6 +38,9 @@ export function isDevtoolsPort(value: unknown): value is DevtoolsPort {
   );
 }
 
+/**
+ * Resolve a devtools port from a direct port or `{ devtools }` object.
+ */
 export function resolveDevtoolsPort(target: unknown): DevtoolsPort | undefined {
   if (isDevtoolsPort(target)) return target;
 
@@ -39,6 +56,9 @@ export function resolveDevtoolsPort(target: unknown): DevtoolsPort | undefined {
   return undefined;
 }
 
+/**
+ * Create provider instrumentation backed by a devtools port when available.
+ */
 export function createProviderDevtools(
   target: unknown,
   options: ProviderDevtoolsOptions,

package/src/provider.ts

@@ -37,11 +37,29 @@ import {
  */
 const MAX_EVENTS = 500;
 
+/**
+ * Options for `createInMemoryDevtools(...)`.
+ */
 export interface InMemoryDevtoolsOptions {
+  /**
+   * Maximum events kept in memory.
+   */
   maxEvents?: number;
+  /**
+   * Custom redactor applied after the default devtools redactor.
+   */
   redact?: DevtoolsRedactor;
+  /**
+   * Watcher configuration.
+   */
   watchers?: DevtoolsWatchersOptions;
+  /**
+   * Events loaded into the buffer at startup.
+   */
   initialEvents?: readonly DevtoolsEvent[];
+  /**
+   * Optional persistence store.
+   */
   store?: DevtoolsEventStore;
 }
 
@@ -52,6 +70,9 @@ function createEventId(): string {
   return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
 
+/**
+ * Normalize a devtools event by filling `id` and `timestamp`.
+ */
 export function createDevtoolsEvent(event: DevtoolsEventInput): DevtoolsEvent {
   return {
     ...event,
@@ -247,13 +268,34 @@ const DevtoolsConfigSchema = z.object({
   PERSIST_PATH: z.string().optional(),
 });
 
+/**
+ * Devtools provider config loaded from `DEVTOOLS_*` env vars.
+ */
 export type DevtoolsConfig = z.infer<typeof DevtoolsConfigSchema>;
 
+/**
+ * Options for `createDevtoolsProvider(...)`.
+ */
 export interface DevtoolsProviderOptions {
+  /**
+   * Whether devtools are enabled. Defaults to non-production.
+   */
   enabled?: boolean;
+  /**
+   * Maximum events kept in memory.
+   */
   maxEvents?: number;
+  /**
+   * Custom redactor applied after the default redactor.
+   */
   redact?: DevtoolsRedactor;
+  /**
+   * Watcher configuration.
+   */
   watchers?: DevtoolsWatchersOptions;
+  /**
+   * Optional persistence store or async store factory.
+   */
   store?:
     | DevtoolsEventStore
     | (() => DevtoolsEventStore | Promise<DevtoolsEventStore>);

package/src/redaction.ts

@@ -1,9 +1,15 @@
 import { redactValue } from "@beignet/core/ports";
 import type { DevtoolsEvent, DevtoolsRedactor } from "./events";
 
+/**
+ * Default devtools event redactor.
+ */
 export const defaultDevtoolsRedactor: DevtoolsRedactor = (event) =>
   redactValue(event);
 
+/**
+ * Apply default redaction and then an optional custom redactor.
+ */
 export function applyDevtoolsRedaction(
   event: DevtoolsEvent,
   redact?: DevtoolsRedactor,
@@ -13,6 +19,9 @@ export function applyDevtoolsRedaction(
   return redact(redacted);
 }
 
+/**
+ * Create a devtools error event when redaction fails.
+ */
 export function createRedactionFailureEvent(error: unknown): DevtoolsEvent {
   return {
     id: `${Date.now()}-${Math.random().toString(16).slice(2)}`,

package/src/routes.ts

@@ -13,6 +13,9 @@ import { isDevtoolsEventType } from "./events";
 import type { DevtoolsFilter, DevtoolsPort } from "./index";
 import { handleDevtoolsUIRequest } from "./ui";
 
+/**
+ * Devtools route options shared by route handlers.
+ */
 export interface DevtoolsRequestOptions extends DevtoolsRouteAccessOptions {
   /**
    * URL path prefix where devtools routes are mounted.
@@ -22,8 +25,17 @@ export interface DevtoolsRequestOptions extends DevtoolsRouteAccessOptions {
   basePath: string;
 }
 
+/**
+ * GET/POST route handlers returned by `createDevtoolsRoute(...)`.
+ */
 export interface DevtoolsRouteHandlers {
+  /**
+   * Handle devtools GET requests.
+   */
   GET(req: Request): Promise<Response>;
+  /**
+   * Handle devtools POST requests.
+   */
   POST(req: Request): Promise<Response>;
 }
 

package/src/trace-context.ts

@@ -1,19 +1,52 @@
 const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
 
+/**
+ * Devtools trace context used to correlate related events.
+ */
 export interface DevtoolsTraceContext {
+  /**
+   * W3C trace ID.
+   */
   traceId: string;
+  /**
+   * Current span ID.
+   */
   spanId: string;
+  /**
+   * Parent span ID when available.
+   */
   parentSpanId?: string;
+  /**
+   * W3C traceparent header value.
+   */
   traceparent: string;
 }
 
+/**
+ * Parsed W3C traceparent header.
+ */
 export interface ParsedTraceparent {
+  /**
+   * W3C trace ID.
+   */
   traceId: string;
+  /**
+   * Span ID from the traceparent header.
+   */
   spanId: string;
+  /**
+   * Trace flags from the traceparent header.
+   */
   traceFlags: string;
+  /**
+   * Normalized traceparent header value.
+   */
   traceparent: string;
 }
 
+/**
+ * Input accepted when creating devtools trace context.
+ */
 export interface DevtoolsTraceContextInput {
   traceId?: string;
   spanId?: string;
@@ -41,6 +74,9 @@ function isNonZeroHex(value: string): boolean {
   return !/^0+$/.test(value);
 }
 
+/**
+ * Create a non-zero W3C trace ID.
+ */
 export function createTraceId(): string {
   let traceId = createHexId(32);
   while (!isNonZeroHex(traceId)) {
@@ -49,6 +85,9 @@ export function createTraceId(): string {
   return traceId;
 }
 
+/**
+ * Create a non-zero W3C span ID.
+ */
 export function createSpanId(): string {
   let spanId = createHexId(16);
   while (!isNonZeroHex(spanId)) {
@@ -57,6 +96,9 @@ export function createSpanId(): string {
   return spanId;
 }
 
+/**
+ * Create a W3C traceparent header value.
+ */
 export function createTraceparent(args: {
   traceId: string;
   spanId: string;
@@ -65,6 +107,9 @@ export function createTraceparent(args: {
   return `00-${args.traceId}-${args.spanId}-${args.traceFlags ?? "01"}`;
 }
 
+/**
+ * Parse and validate a W3C traceparent header value.
+ */
 export function parseTraceparent(
   value: string | null | undefined,
 ): ParsedTraceparent | undefined {
@@ -84,6 +129,9 @@ export function parseTraceparent(
   };
 }
 
+/**
+ * Create devtools trace context from explicit IDs or an existing traceparent.
+ */
 export function createDevtoolsTraceContext(
   input: DevtoolsTraceContextInput = {},
 ): DevtoolsTraceContext {
@@ -104,6 +152,9 @@ export function createDevtoolsTraceContext(
   };
 }
 
+/**
+ * Create child trace context from a parent context.
+ */
 export function createChildDevtoolsTraceContext(
   parent: DevtoolsTraceContextInput,
 ): DevtoolsTraceContext {

package/src/ui.ts

@@ -132,8 +132,10 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
 .badge-cache{background:#f7fee7;color:#4d7c0f;border-color:#d9f99d}
 .badge-db{background:#ecfeff;color:#0e7490;border-color:#cffafe}
 .badge-mail{background:#fdf2f8;color:#be185d;border-color:#fbcfe8}
+.badge-notifications{background:#f5f3ff;color:#6d28d9;border-color:#ddd6fe}
 .badge-rateLimit{background:#fffbeb;color:#b45309;border-color:#fde68a}
 .badge-storage{background:#f0fdf4;color:#15803d;border-color:#bbf7d0}
+.badge-uploads{background:#f0f9ff;color:#0369a1;border-color:#bae6fd}
 .request-id{font-family:var(--font-mono);font-size:10px;color:var(--text-muted);padding:2px 5px;background:var(--surface-2);border:1px solid var(--border);border-radius:4px}
 .trace-id{font-family:var(--font-mono);font-size:10px;color:var(--accent-strong);padding:2px 5px;background:#eef2ff;border:1px solid rgba(79,70,229,.16);border-radius:4px}
 @media(max-width:760px){
@@ -221,14 +223,16 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
     {id:"db",label:"Database",type:"custom",watcher:"db",watcherName:"db"},
     {id:"cache",label:"Cache",type:"custom",watcher:"cache",watcherName:"cache"},
     {id:"storage",label:"Storage",type:"custom",watcher:"storage",watcherName:"storage"},
+    {id:"uploads",label:"Uploads",type:"custom",watcher:"uploads",watcherName:"uploads"},
     {id:"mail",label:"Mail",type:"custom",watcher:"mail",watcherName:"mail"},
+    {id:"notifications",label:"Notifications",type:"custom",watcher:"notifications",watcherName:"notifications"},
     {id:"auth",label:"Auth",type:"custom",watcher:"auth",watcherName:"auth"},
     {id:"audit",label:"Audit",type:"custom",watcher:"audit",watcherName:"audit"},
     {id:"rateLimit",label:"Rate limits",type:"custom",watcher:"rateLimit",watcherName:"rateLimit"},
     {id:"custom",label:"Custom",type:"custom",watcher:"custom"}
   ];
-  const FOCUS_PANEL_TABS={events:true,jobs:true,schedules:true,db:true,cache:true,storage:true,mail:true,auth:true,audit:true,rateLimit:true};
-  const BUILT_IN_WATCHERS={requests:true,errors:true,useCases:true,eventBus:true,jobs:true,schedules:true,providers:true,db:true,cache:true,storage:true,mail:true,auth:true,audit:true,rateLimit:true,custom:true};
+  const FOCUS_PANEL_TABS={events:true,jobs:true,schedules:true,db:true,cache:true,storage:true,uploads:true,mail:true,notifications:true,auth:true,audit:true,rateLimit:true};
+  const BUILT_IN_WATCHERS={requests:true,errors:true,useCases:true,eventBus:true,jobs:true,schedules:true,providers:true,db:true,cache:true,storage:true,uploads:true,mail:true,notifications:true,auth:true,audit:true,rateLimit:true,custom:true};
   let events=[];
   let watchers=[];
   let activeTab=localStorage.getItem("beignet-devtools-tab")||"timeline";
@@ -331,8 +335,10 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
         case "cache": return "cache";
         case "db": return "database";
         case "mail": return "mail";
+        case "notifications": return "notifications";
         case "rateLimit": return "rate limit";
         case "storage": return "storage";
+        case "uploads": return "uploads";
         default: return "custom";
       }
     }
@@ -347,8 +353,10 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
         case "cache": return "cache";
         case "db": return "db";
         case "mail": return "mail";
+        case "notifications": return "notifications";
         case "rateLimit": return "rateLimit";
         case "storage": return "storage";
+        case "uploads": return "uploads";
         default: return "custom";
       }
     }
@@ -564,7 +572,9 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
       case "db": return {title:"Database",subtitle:"Queries and database provider diagnostics"};
       case "cache": return {title:"Cache",subtitle:"Reads, writes, deletes, and hit rates"};
       case "storage": return {title:"Storage",subtitle:"Object storage operations"};
+      case "uploads": return {title:"Uploads",subtitle:"Upload preparation, signing, and completion"};
       case "mail": return {title:"Mail",subtitle:"Delivery attempts and provider results"};
+      case "notifications": return {title:"Notifications",subtitle:"Notification intent and channel delivery"};
       case "auth": return {title:"Auth",subtitle:"Session and authentication activity"};
       case "audit": return {title:"Audit",subtitle:"Durable activity records emitted by application code"};
       case "rateLimit": return {title:"Rate limits",subtitle:"Allowed, blocked, and failed checks"};