@beignet/devtools 0.0.1

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAElB;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAgB,EAChB,UAAsC,EAAE;IAExC,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,OAAO,wBAAwB,EAAE,CAAC;IACpC,CAAC;IAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAE1C,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE;KACxD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAgB;IAC1C,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEvD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBA6KO,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmlBzB,CAAC;AACT,CAAC"}

package/dist/watchers.d.ts

@@ -0,0 +1,22 @@
+import type { DevtoolsEvent } from "./events";
+export declare const BUILT_IN_DEVTOOLS_WATCHER_NAMES: readonly ["requests", "errors", "useCases", "eventBus", "jobs", "schedules", "providers", "db", "cache", "storage", "mail", "auth", "audit", "rateLimit", "custom"];
+export type BuiltInDevtoolsWatcherName = (typeof BUILT_IN_DEVTOOLS_WATCHER_NAMES)[number];
+export type DevtoolsWatcherName = BuiltInDevtoolsWatcherName | (string & {});
+export interface DevtoolsWatcher {
+    name: DevtoolsWatcherName;
+    label: string;
+    description?: string;
+    eventTypes: readonly DevtoolsEvent["type"][];
+    enabled: boolean;
+}
+export type DevtoolsWatcherOptions = boolean | {
+    enabled?: boolean;
+    label?: string;
+    description?: string;
+    eventTypes?: readonly DevtoolsEvent["type"][];
+};
+export type DevtoolsWatchersOptions = Partial<Record<BuiltInDevtoolsWatcherName, DevtoolsWatcherOptions>> & Record<string, DevtoolsWatcherOptions | undefined>;
+export declare function resolveDevtoolsWatchers(options?: DevtoolsWatchersOptions): DevtoolsWatcher[];
+export declare function isDevtoolsWatcherEnabled(watchers: readonly DevtoolsWatcher[], name: DevtoolsWatcherName): boolean;
+export declare function isDevtoolsEventEnabled(watchers: readonly DevtoolsWatcher[], event: DevtoolsEvent): boolean;
+//# sourceMappingURL=watchers.d.ts.map

package/dist/watchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchers.d.ts","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,eAAO,MAAM,+BAA+B,qKAgBlC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,SAAS,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,sBAAsB,GAC9B,OAAO,GACP;IACE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;CAC/C,CAAC;AAEN,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAC3C,MAAM,CAAC,0BAA0B,EAAE,sBAAsB,CAAC,CAC3D,GACC,MAAM,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAAC,CAAC;AA6IrD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,eAAe,EAAE,CAuBnB;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAET;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,KAAK,EAAE,aAAa,GACnB,OAAO,CAWT"}

package/dist/watchers.js

@@ -0,0 +1,171 @@
+export const BUILT_IN_DEVTOOLS_WATCHER_NAMES = [
+    "requests",
+    "errors",
+    "useCases",
+    "eventBus",
+    "jobs",
+    "schedules",
+    "providers",
+    "db",
+    "cache",
+    "storage",
+    "mail",
+    "auth",
+    "audit",
+    "rateLimit",
+    "custom",
+];
+const BUILT_IN_DEVTOOLS_WATCHERS = {
+    requests: {
+        name: "requests",
+        label: "Requests",
+        description: "HTTP request timing and contract route activity.",
+        eventTypes: ["request"],
+        enabled: true,
+    },
+    errors: {
+        name: "errors",
+        label: "Errors",
+        description: "Unhandled errors, use case failures, and devtools failures.",
+        eventTypes: ["error"],
+        enabled: true,
+    },
+    useCases: {
+        name: "useCases",
+        label: "Use cases",
+        description: "Application command and query execution.",
+        eventTypes: ["usecase"],
+        enabled: true,
+    },
+    eventBus: {
+        name: "eventBus",
+        label: "Event bus",
+        description: "Domain event publishing.",
+        eventTypes: ["eventBus"],
+        enabled: true,
+    },
+    jobs: {
+        name: "jobs",
+        label: "Jobs",
+        description: "Background job scheduling and execution.",
+        eventTypes: ["job"],
+        enabled: true,
+    },
+    schedules: {
+        name: "schedules",
+        label: "Schedules",
+        description: "Scheduled task execution.",
+        eventTypes: ["schedule"],
+        enabled: true,
+    },
+    providers: {
+        name: "providers",
+        label: "Providers",
+        description: "Provider setup, start, and stop lifecycle activity.",
+        eventTypes: ["provider"],
+        enabled: true,
+    },
+    db: {
+        name: "db",
+        label: "Database",
+        description: "Database queries and mutations from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    cache: {
+        name: "cache",
+        label: "Cache",
+        description: "Cache reads, writes, and deletes from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    storage: {
+        name: "storage",
+        label: "Storage",
+        description: "Object storage reads, writes, and deletes from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    mail: {
+        name: "mail",
+        label: "Mail",
+        description: "Mail delivery attempts from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    auth: {
+        name: "auth",
+        label: "Auth",
+        description: "Authentication and session activity from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    audit: {
+        name: "audit",
+        label: "Audit",
+        description: "Durable audit and activity records emitted by the app.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    rateLimit: {
+        name: "rateLimit",
+        label: "Rate limits",
+        description: "Rate limit checks from first-party providers.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+    custom: {
+        name: "custom",
+        label: "Custom",
+        description: "Application and integration-specific diagnostic events.",
+        eventTypes: ["custom"],
+        enabled: true,
+    },
+};
+function normalizeWatcherOptions(name, defaultWatcher, options) {
+    const base = defaultWatcher ?? {
+        name,
+        label: name,
+        eventTypes: [],
+        enabled: true,
+    };
+    if (typeof options === "boolean") {
+        return {
+            ...base,
+            enabled: options,
+        };
+    }
+    return {
+        ...base,
+        ...options,
+        name,
+        label: options?.label ?? base.label,
+        eventTypes: options?.eventTypes ?? base.eventTypes,
+        enabled: options?.enabled ?? base.enabled,
+    };
+}
+export function resolveDevtoolsWatchers(options = {}) {
+    const watchers = BUILT_IN_DEVTOOLS_WATCHER_NAMES.map((name) => normalizeWatcherOptions(name, BUILT_IN_DEVTOOLS_WATCHERS[name], options[name]));
+    for (const [name, option] of Object.entries(options)) {
+        if (BUILT_IN_DEVTOOLS_WATCHER_NAMES.includes(name) ||
+            option === undefined) {
+            continue;
+        }
+        watchers.push(normalizeWatcherOptions(name, undefined, option));
+    }
+    return watchers;
+}
+export function isDevtoolsWatcherEnabled(watchers, name) {
+    return watchers.find((watcher) => watcher.name === name)?.enabled ?? true;
+}
+export function isDevtoolsEventEnabled(watchers, event) {
+    if (event.watcher) {
+        return isDevtoolsWatcherEnabled(watchers, event.watcher);
+    }
+    if (event.type === "custom") {
+        return isDevtoolsWatcherEnabled(watchers, "custom");
+    }
+    const watcher = watchers.find((item) => item.eventTypes.includes(event.type));
+    return watcher?.enabled ?? true;
+}
+//# sourceMappingURL=watchers.js.map

package/dist/watchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchers.js","sourceRoot":"","sources":["../src/watchers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@beignet/devtools",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Development-time devtools for Beignet - mini Telescope for the server runtime",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "devtools",
+    "development",
+    "debugging",
+    "server",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/devtools"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@beignet/core": "*"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/access.ts

@@ -0,0 +1,52 @@
+export type DevtoolsAuthorizeResult = boolean | Response;
+
+export type DevtoolsAuthorize = (
+  req: Request,
+) => DevtoolsAuthorizeResult | Promise<DevtoolsAuthorizeResult>;
+
+export interface DevtoolsRouteAccessOptions {
+  /**
+   * Whether the devtools route should be exposed.
+   *
+   * @default process.env.NODE_ENV !== "production"
+   */
+  enabled?: boolean;
+
+  /**
+   * Optional app-owned authorization check for exposed devtools routes.
+   *
+   * Returning `false` hides devtools with a 404. Returning a `Response` lets
+   * the app provide a custom denial response.
+   */
+  authorize?: DevtoolsAuthorize;
+}
+
+export function isDevtoolsRouteEnabled(
+  options: DevtoolsRouteAccessOptions = {},
+): boolean {
+  return options.enabled ?? process.env.NODE_ENV !== "production";
+}
+
+export function devtoolsNotFoundResponse(): Response {
+  return new Response("Not Found", { status: 404 });
+}
+
+export async function authorizeDevtoolsRequest(
+  req: Request,
+  options: DevtoolsRouteAccessOptions = {},
+): Promise<Response | undefined> {
+  if (!isDevtoolsRouteEnabled(options)) {
+    return devtoolsNotFoundResponse();
+  }
+
+  if (!options.authorize) {
+    return undefined;
+  }
+
+  const result = await options.authorize(req);
+  if (result instanceof Response) {
+    return result;
+  }
+
+  return result ? undefined : devtoolsNotFoundResponse();
+}

package/src/audit.ts

@@ -0,0 +1,71 @@
+import {
+  type AuditLogEntry,
+  type AuditLogEntryInput,
+  type AuditLogPort,
+  normalizeAuditLogEntry,
+  redactAuditLogEntry,
+} from "@beignet/core/ports";
+import type { DevtoolsPort } from "./index";
+
+export interface DevtoolsAuditLogOptions {
+  audit: AuditLogPort;
+  devtools?: DevtoolsPort;
+  emit?: boolean;
+  redact?: (entry: AuditLogEntry) => AuditLogEntry;
+}
+
+function prepareEntry(
+  input: AuditLogEntryInput,
+  redact?: (entry: AuditLogEntry) => AuditLogEntry,
+): AuditLogEntry {
+  const redacted = redactAuditLogEntry(normalizeAuditLogEntry(input));
+  return redact ? redact(redacted) : redacted;
+}
+
+function auditSummary(entry: AuditLogEntry): string {
+  const resource = entry.resource?.id
+    ? `${entry.resource.type}:${entry.resource.id}`
+    : entry.resource?.type;
+  const outcome = entry.outcome === "failure" ? "failed" : "succeeded";
+  return resource
+    ? `${entry.action} ${outcome} for ${resource}`
+    : `${entry.action} ${outcome}`;
+}
+
+export function createDevtoolsAuditLog(
+  options: DevtoolsAuditLogOptions,
+): AuditLogPort {
+  return {
+    async record(input) {
+      const entry = prepareEntry(input, options.redact);
+
+      await options.audit.record(entry);
+
+      if (options.emit === false || !options.devtools) return;
+
+      try {
+        options.devtools.record({
+          type: "custom",
+          watcher: "audit",
+          name: entry.action,
+          label: "Audit",
+          summary: auditSummary(entry),
+          requestId: entry.requestId,
+          traceId: entry.traceId,
+          details: {
+            action: entry.action,
+            actor: entry.actor,
+            tenant: entry.tenant,
+            resource: entry.resource,
+            outcome: entry.outcome,
+            message: entry.message,
+            metadata: entry.metadata,
+            occurredAt: entry.occurredAt.toISOString(),
+          },
+        });
+      } catch {
+        // Devtools is an observer; durable audit writes must not depend on it.
+      }
+    },
+  };
+}

package/src/events.ts

@@ -0,0 +1,193 @@
+/**
+ * Event types for Beignet devtools
+ *
+ * These events represent activity within the Beignet server and can be
+ * logged during development to aid in debugging and observability.
+ */
+
+/**
+ * Base interface for all devtools events.
+ * All events share these common fields for correlation and debugging.
+ */
+export interface BaseDevtoolsEvent {
+  /**
+   * Unique identifier for this event (UUID or timestamp-based).
+   */
+  id: string;
+
+  /**
+   * ISO timestamp when the event occurred.
+   */
+  timestamp: string;
+
+  /**
+   * Optional correlation ID to link events from the same request/operation.
+   */
+  requestId?: string;
+
+  /**
+   * W3C trace ID for cross-service correlation.
+   */
+  traceId?: string;
+
+  /**
+   * Span ID for the operation represented by this event.
+   */
+  spanId?: string;
+
+  /**
+   * Parent span ID when this event belongs to a nested operation.
+   */
+  parentSpanId?: string;
+
+  /**
+   * W3C traceparent header value associated with this event.
+   */
+  traceparent?: string;
+
+  /**
+   * Optional watcher name that owns this event. Built-in events can infer their
+   * watcher from `type`; custom integrations can set this to use their own
+   * watcher configuration.
+   */
+  watcher?: string;
+
+  /**
+   * Optional structured detail payload. Devtools applies default redaction to
+   * this field before events are stored.
+   */
+  details?: unknown;
+}
+
+/**
+ * Logged when the server handles a request mapped from a contract.
+ */
+export interface RequestEvent extends BaseDevtoolsEvent {
+  type: "request";
+  method: string;
+  path: string;
+  contractName?: string;
+  status?: number;
+  durationMs?: number;
+  summary?: string;
+}
+
+/**
+ * Logged when an error occurs (unhandled or explicit).
+ */
+export interface ErrorEvent extends BaseDevtoolsEvent {
+  type: "error";
+  message: string;
+  stack?: string;
+  contractName?: string;
+  useCaseName?: string;
+}
+
+/**
+ * Logged when a use case runs.
+ */
+export interface UseCaseEvent extends BaseDevtoolsEvent {
+  type: "usecase";
+  name: string;
+  kind?: "command" | "query";
+  phase: "start" | "end" | "error";
+  durationMs?: number;
+  error?: string;
+}
+
+/**
+ * Logged when the event bus publishes an event.
+ */
+export interface EventBusEvent extends BaseDevtoolsEvent {
+  type: "eventBus";
+  eventName: string;
+}
+
+/**
+ * Logged when a job is scheduled / starts / completes / fails.
+ * Jobs may be backed by Inngest or other providers.
+ */
+export interface JobEvent extends BaseDevtoolsEvent {
+  type: "job";
+  jobName: string;
+  status: "scheduled" | "started" | "completed" | "failed";
+}
+
+/**
+ * Logged when a scheduled task starts, completes, or fails.
+ */
+export interface ScheduleEvent extends BaseDevtoolsEvent {
+  type: "schedule";
+  scheduleName: string;
+  status: "started" | "completed" | "failed";
+  cron?: string;
+  timezone?: string;
+}
+
+/**
+ * Logged when a provider is set up, started, or stopped.
+ */
+export interface ProviderEvent extends BaseDevtoolsEvent {
+  type: "provider";
+  providerName: string;
+  action: "setup" | "start" | "stop";
+}
+
+/**
+ * Logged by application or integration code for app-specific diagnostics.
+ */
+export interface CustomDevtoolsEvent extends BaseDevtoolsEvent {
+  type: "custom";
+  name: string;
+  label?: string;
+  summary?: string;
+}
+
+/**
+ * Union type of all devtools events.
+ */
+export type DevtoolsEvent =
+  | RequestEvent
+  | ErrorEvent
+  | UseCaseEvent
+  | EventBusEvent
+  | JobEvent
+  | ScheduleEvent
+  | ProviderEvent
+  | CustomDevtoolsEvent;
+
+export type DevtoolsEventInput = DevtoolsEvent extends infer Event
+  ? Event extends DevtoolsEvent
+    ? Omit<Event, "id" | "timestamp"> & Partial<Pick<Event, "id" | "timestamp">>
+    : never
+  : never;
+
+export type DevtoolsRedactor = (event: DevtoolsEvent) => DevtoolsEvent;
+
+export type DevtoolsSubscriptionEvent =
+  | {
+      type: "record";
+      event: DevtoolsEvent;
+    }
+  | {
+      type: "clear";
+    };
+
+export type DevtoolsListener = (event: DevtoolsSubscriptionEvent) => void;
+
+export const DEVTOOLS_EVENT_TYPES = [
+  "request",
+  "error",
+  "usecase",
+  "eventBus",
+  "job",
+  "schedule",
+  "provider",
+  "custom",
+] as const satisfies readonly DevtoolsEvent["type"][];
+
+export function isDevtoolsEventType(
+  value: string,
+): value is DevtoolsEvent["type"] {
+  return DEVTOOLS_EVENT_TYPES.includes(value as DevtoolsEvent["type"]);
+}