@beignet/devtools 0.0.1

package/src/persistence.ts

@@ -0,0 +1,163 @@
+import type { DevtoolsEvent } from "./events";
+
+export interface DevtoolsEventStore {
+  name?: string;
+  load?(): DevtoolsEvent[] | Promise<DevtoolsEvent[]>;
+  append?(
+    event: DevtoolsEvent,
+    events: readonly DevtoolsEvent[],
+  ): void | Promise<void>;
+  clear?(): void | Promise<void>;
+}
+
+export interface FileDevtoolsStoreOptions {
+  /**
+   * JSONL file used for persisted devtools events.
+   *
+   * @default ".beignet/devtools/core/events.jsonl"
+   */
+  filePath?: string;
+
+  /**
+   * Maximum number of events to load and keep when compacting the file.
+   *
+   * @default 1000
+   */
+  maxEvents?: number;
+
+  /**
+   * Rewrite the JSONL file after this many appended events. Compaction keeps
+   * persistence bounded without making every record pay the rewrite cost.
+   *
+   * @default 50
+   */
+  compactEvery?: number;
+}
+
+const DEFAULT_FILE_PATH = ".beignet/devtools/core/events.jsonl";
+const DEFAULT_MAX_EVENTS = 1000;
+const DEFAULT_COMPACT_EVERY = 50;
+
+type NodeFs = typeof import("node:fs/promises");
+type NodePath = typeof import("node:path");
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof (error as { code?: unknown }).code === "string"
+  );
+}
+
+function isDevtoolsEvent(value: unknown): value is DevtoolsEvent {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    "timestamp" in value &&
+    "type" in value
+  );
+}
+
+function parseJsonLine(line: string): DevtoolsEvent | undefined {
+  try {
+    const parsed = JSON.parse(line);
+    return isDevtoolsEvent(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function loadNodeModules(): Promise<{
+  fs: NodeFs;
+  path: NodePath;
+}> {
+  const [fs, path] = await Promise.all([
+    import("node:fs/promises"),
+    import("node:path"),
+  ]);
+  return { fs, path };
+}
+
+export function createFileDevtoolsStore(
+  options: FileDevtoolsStoreOptions = {},
+): DevtoolsEventStore {
+  const filePath = options.filePath ?? DEFAULT_FILE_PATH;
+  const maxEvents = Math.max(1, options.maxEvents ?? DEFAULT_MAX_EVENTS);
+  const compactEvery = Math.max(
+    1,
+    options.compactEvery ?? DEFAULT_COMPACT_EVERY,
+  );
+  let appendCount = 0;
+  let queue = Promise.resolve();
+
+  async function ensureDirectory(fs: NodeFs, path: NodePath): Promise<void> {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+  }
+
+  async function readEvents(): Promise<DevtoolsEvent[]> {
+    const { fs } = await loadNodeModules();
+    let content: string;
+
+    try {
+      content = await fs.readFile(filePath, "utf8");
+    } catch (error) {
+      if (isErrnoException(error) && error.code === "ENOENT") return [];
+      throw error;
+    }
+
+    return content
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map(parseJsonLine)
+      .filter((event): event is DevtoolsEvent => event !== undefined)
+      .slice(-maxEvents);
+  }
+
+  async function writeEvents(events: readonly DevtoolsEvent[]): Promise<void> {
+    const { fs, path } = await loadNodeModules();
+    await ensureDirectory(fs, path);
+    const content = events.map((event) => JSON.stringify(event)).join("\n");
+    await fs.writeFile(filePath, content ? `${content}\n` : "", "utf8");
+  }
+
+  function enqueue(task: () => Promise<void>): Promise<void> {
+    queue = queue.then(task, task);
+    return queue;
+  }
+
+  return {
+    name: "file",
+    async load() {
+      const events = await readEvents();
+      await writeEvents(events);
+      return events;
+    },
+    append(event, events) {
+      appendCount += 1;
+      const currentAppendCount = appendCount;
+
+      return enqueue(async () => {
+        const shouldCompact =
+          currentAppendCount % compactEvery === 0 || events.length >= maxEvents;
+
+        if (shouldCompact) {
+          await writeEvents(events.slice(-maxEvents));
+          return;
+        }
+
+        const { fs, path } = await loadNodeModules();
+        await ensureDirectory(fs, path);
+        await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, "utf8");
+      });
+    },
+    clear() {
+      appendCount = 0;
+      return enqueue(async () => {
+        await writeEvents([]);
+      });
+    },
+  };
+}

package/src/provider-instrumentation.ts

@@ -0,0 +1,50 @@
+import {
+  createProviderInstrumentation,
+  isProviderInstrumentationPort,
+  type ProviderCustomInstrumentationEventInput,
+  type ProviderInstrumentation,
+  type ProviderInstrumentationOptions,
+} from "@beignet/core/providers";
+import type { DevtoolsPort } from "./index";
+
+export type ProviderDevtoolsOptions = ProviderInstrumentationOptions;
+export type ProviderCustomDevtoolsEventInput =
+  ProviderCustomInstrumentationEventInput;
+export type ProviderDevtools = ProviderInstrumentation;
+
+export function isDevtoolsPort(value: unknown): value is DevtoolsPort {
+  return (
+    isProviderInstrumentationPort(value) &&
+    typeof value === "object" &&
+    value !== null &&
+    "getEvents" in value &&
+    typeof value.getEvents === "function" &&
+    "isWatcherEnabled" in value &&
+    typeof value.isWatcherEnabled === "function"
+  );
+}
+
+export function resolveDevtoolsPort(target: unknown): DevtoolsPort | undefined {
+  if (isDevtoolsPort(target)) return target;
+
+  if (
+    typeof target === "object" &&
+    target !== null &&
+    "devtools" in target &&
+    isDevtoolsPort(target.devtools)
+  ) {
+    return target.devtools;
+  }
+
+  return undefined;
+}
+
+export function createProviderDevtools(
+  target: unknown,
+  options: ProviderDevtoolsOptions,
+): ProviderDevtools {
+  return createProviderInstrumentation(
+    resolveDevtoolsPort(target) ?? undefined,
+    options,
+  );
+}

package/src/provider.ts

@@ -0,0 +1,375 @@
+/**
+ * Devtools provider implementation
+ *
+ * Provides an in-memory event buffer that can be attached to ctx.ports.devtools.
+ * The provider is disabled by default in production environments.
+ */
+
+import { createProvider } from "@beignet/core/providers";
+import { z } from "zod";
+import type {
+  DevtoolsEvent,
+  DevtoolsEventInput,
+  DevtoolsListener,
+  DevtoolsRedactor,
+  DevtoolsSubscriptionEvent,
+} from "./events";
+import type { DevtoolsFilter, DevtoolsPort } from "./index";
+import {
+  createFileDevtoolsStore,
+  type DevtoolsEventStore,
+} from "./persistence";
+import {
+  applyDevtoolsRedaction,
+  createRedactionFailureEvent,
+} from "./redaction";
+import {
+  type DevtoolsWatcher,
+  type DevtoolsWatchersOptions,
+  isDevtoolsEventEnabled,
+  isDevtoolsWatcherEnabled,
+  resolveDevtoolsWatchers,
+} from "./watchers";
+
+/**
+ * Maximum number of events to keep in the buffer.
+ * When this limit is reached, the oldest events are removed.
+ */
+const MAX_EVENTS = 500;
+
+export interface InMemoryDevtoolsOptions {
+  maxEvents?: number;
+  redact?: DevtoolsRedactor;
+  watchers?: DevtoolsWatchersOptions;
+  initialEvents?: readonly DevtoolsEvent[];
+  store?: DevtoolsEventStore;
+}
+
+function createEventId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+export function createDevtoolsEvent(event: DevtoolsEventInput): DevtoolsEvent {
+  return {
+    ...event,
+    id: event.id ?? createEventId(),
+    timestamp: event.timestamp ?? new Date().toISOString(),
+  } as DevtoolsEvent;
+}
+
+/**
+ * Create an in-memory devtools implementation.
+ *
+ * This implementation stores events in a bounded buffer (max 500 events).
+ * When the buffer is full, the oldest events are removed to make room for new ones.
+ *
+ * @returns A DevtoolsPort implementation
+ */
+export function createInMemoryDevtools(
+  options: InMemoryDevtoolsOptions = {},
+): DevtoolsPort {
+  const listeners = new Set<DevtoolsListener>();
+  const maxEvents = options.maxEvents ?? MAX_EVENTS;
+  const watchers = resolveDevtoolsWatchers(options.watchers);
+  const events: DevtoolsEvent[] = [];
+
+  function notify(event: DevtoolsSubscriptionEvent): void {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Subscribers are observers; they must not affect devtools storage.
+      }
+    }
+  }
+
+  function getErrorMessage(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+    return "Unknown error";
+  }
+
+  function persistEvent(event: DevtoolsEvent): void {
+    if (!options.store?.append) return;
+
+    void Promise.resolve(options.store.append(event, [...events])).catch(
+      (error) => {
+        storeInternalError({
+          type: "error",
+          message: "Devtools persistence failed",
+          details: {
+            message: getErrorMessage(error),
+            store: options.store?.name,
+          },
+        });
+      },
+    );
+  }
+
+  async function clearPersistedEvents(): Promise<void> {
+    if (!options.store?.clear) return;
+
+    try {
+      await options.store.clear();
+    } catch (error) {
+      storeInternalError({
+        type: "error",
+        message: "Devtools persistence clear failed",
+        details: {
+          message: getErrorMessage(error),
+          store: options.store?.name,
+        },
+      });
+    }
+  }
+
+  function store(
+    event: DevtoolsEvent,
+    storeOptions: { notify?: boolean; persist?: boolean } = {},
+  ): DevtoolsEvent {
+    events.push(event);
+    if (events.length > maxEvents) {
+      events.splice(0, events.length - maxEvents);
+    }
+    if (storeOptions.notify !== false) {
+      notify({ type: "record", event });
+    }
+    if (storeOptions.persist !== false) {
+      persistEvent(event);
+    }
+    return event;
+  }
+
+  function redact(event: DevtoolsEvent): DevtoolsEvent {
+    try {
+      return applyDevtoolsRedaction(event, options.redact);
+    } catch (error) {
+      return createRedactionFailureEvent(error);
+    }
+  }
+
+  function storeInternalError(event: DevtoolsEventInput): DevtoolsEvent {
+    const normalized = createDevtoolsEvent(event);
+    const redacted = redact(normalized);
+    if (!isDevtoolsEventEnabled(watchers, redacted)) return redacted;
+    return store(redacted, { persist: false });
+  }
+
+  for (const event of options.initialEvents ?? []) {
+    const redacted = redact(event);
+    if (isDevtoolsEventEnabled(watchers, redacted)) {
+      store(redacted, { notify: false, persist: false });
+    }
+  }
+
+  function log(event: DevtoolsEvent): void {
+    const redacted = redact(event);
+    if (!isDevtoolsEventEnabled(watchers, redacted)) return;
+    store(redacted);
+  }
+
+  function record(event: DevtoolsEventInput): DevtoolsEvent {
+    const normalized = createDevtoolsEvent(event);
+    const redacted = redact(normalized);
+    if (!isDevtoolsEventEnabled(watchers, redacted)) return redacted;
+    return store(redacted);
+  }
+
+  function getEvents(filter?: DevtoolsFilter): DevtoolsEvent[] {
+    let result = [...events];
+
+    if (filter?.type) {
+      result = result.filter((e) => e.type === filter.type);
+    }
+    if (filter?.requestId) {
+      result = result.filter((e) => e.requestId === filter.requestId);
+    }
+    if (filter?.traceId) {
+      result = result.filter((e) => e.traceId === filter.traceId);
+    }
+
+    const limit = filter?.limit ?? 200;
+    if (result.length > limit) {
+      result = result.slice(result.length - limit);
+    }
+
+    return result;
+  }
+
+  async function clear(): Promise<void> {
+    events.length = 0;
+    notify({ type: "clear" });
+    await clearPersistedEvents();
+  }
+
+  function getWatchers(): DevtoolsWatcher[] {
+    return watchers.map((watcher) => ({ ...watcher }));
+  }
+
+  function isWatcherEnabled(name: string): boolean {
+    return isDevtoolsWatcherEnabled(watchers, name);
+  }
+
+  function subscribe(listener: DevtoolsListener): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  return {
+    log,
+    record,
+    subscribe,
+    getEvents,
+    clear,
+    getWatchers,
+    isWatcherEnabled,
+  };
+}
+
+/**
+ * Configuration schema for the devtools provider.
+ */
+const DevtoolsConfigSchema = z.object({
+  ENABLED: z
+    .string()
+    .optional()
+    .transform((v) => (v === undefined ? undefined : v === "true")),
+  MAX_EVENTS: z.coerce.number().int().positive().optional(),
+  PERSIST: z
+    .string()
+    .optional()
+    .transform((v) => (v === undefined ? undefined : v === "true")),
+  PERSIST_PATH: z.string().optional(),
+});
+
+export type DevtoolsConfig = z.infer<typeof DevtoolsConfigSchema>;
+
+export interface DevtoolsProviderOptions {
+  enabled?: boolean;
+  maxEvents?: number;
+  redact?: DevtoolsRedactor;
+  watchers?: DevtoolsWatchersOptions;
+  store?:
+    | DevtoolsEventStore
+    | (() => DevtoolsEventStore | Promise<DevtoolsEventStore>);
+}
+
+/**
+ * Devtools service provider.
+ *
+ * This provider attaches a DevtoolsPort to ctx.ports.devtools.
+ * It can be enabled/disabled via the DEVTOOLS_ENABLED environment variable.
+ * By default, it's enabled in non-production environments and disabled in production.
+ *
+ * @example
+ * ```ts
+ * import { createDevtoolsProvider } from "@beignet/devtools";
+ * import { createServer } from "@beignet/core/server";
+ *
+ * const server = await createServer({
+ *   ports,
+ *   providers: [createDevtoolsProvider()],
+ * });
+ * ```
+ *
+ * To explicitly enable/disable:
+ * ```bash
+ * DEVTOOLS_ENABLED=true npm run dev
+ * DEVTOOLS_ENABLED=false npm run dev
+ * ```
+ */
+export function createDevtoolsProvider(options: DevtoolsProviderOptions = {}) {
+  return createProvider<
+    Record<string, unknown>,
+    typeof DevtoolsConfigSchema,
+    { devtools: DevtoolsPort }
+  >({
+    name: "devtools",
+
+    config: {
+      schema: DevtoolsConfigSchema,
+      envPrefix: "DEVTOOLS_",
+    },
+
+    async setup({ config }) {
+      const enabled =
+        options.enabled ??
+        config?.ENABLED ??
+        process.env.NODE_ENV !== "production";
+
+      if (!enabled) {
+        const watchers = resolveDevtoolsWatchers(options.watchers).map(
+          (watcher) => ({
+            ...watcher,
+            enabled: false,
+          }),
+        );
+
+        // Provide a no-op implementation so callers don't need null checks
+        const noop: DevtoolsPort = {
+          log: () => {},
+          record: (event) => createDevtoolsEvent(event),
+          subscribe: () => () => {},
+          getEvents: () => [],
+          clear: () => {},
+          getWatchers: () => watchers.map((watcher) => ({ ...watcher })),
+          isWatcherEnabled: () => false,
+        };
+        return { ports: { devtools: noop } };
+      }
+
+      const maxEvents = config?.MAX_EVENTS ?? options.maxEvents ?? MAX_EVENTS;
+      const configuredStore =
+        typeof options.store === "function"
+          ? await options.store()
+          : options.store;
+      let store =
+        configuredStore ??
+        (config?.PERSIST || config?.PERSIST_PATH
+          ? createFileDevtoolsStore({
+              filePath: config.PERSIST_PATH,
+              maxEvents,
+            })
+          : undefined);
+      let initialEvents: DevtoolsEvent[] = [];
+      let loadError: unknown;
+
+      if (store?.load) {
+        try {
+          initialEvents = await store.load();
+        } catch (error) {
+          loadError = error;
+          store = undefined;
+        }
+      }
+
+      const devtools = createInMemoryDevtools({
+        maxEvents,
+        redact: options.redact,
+        watchers: options.watchers,
+        initialEvents,
+        store,
+      });
+
+      if (loadError) {
+        devtools.record({
+          type: "error",
+          message: "Devtools persistence load failed",
+          details: {
+            message:
+              loadError instanceof Error
+                ? loadError.message
+                : String(loadError),
+          },
+        });
+      }
+
+      return { ports: { devtools } };
+    },
+  });
+}

package/src/redaction.ts

@@ -0,0 +1,26 @@
+import { redactValue } from "@beignet/core/ports";
+import type { DevtoolsEvent, DevtoolsRedactor } from "./events";
+
+export const defaultDevtoolsRedactor: DevtoolsRedactor = (event) =>
+  redactValue(event);
+
+export function applyDevtoolsRedaction(
+  event: DevtoolsEvent,
+  redact?: DevtoolsRedactor,
+): DevtoolsEvent {
+  const redacted = defaultDevtoolsRedactor(event);
+  if (!redact) return redacted;
+  return redact(redacted);
+}
+
+export function createRedactionFailureEvent(error: unknown): DevtoolsEvent {
+  return {
+    id: `${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    timestamp: new Date().toISOString(),
+    type: "error",
+    message: "Devtools redactor failed",
+    details: {
+      message: error instanceof Error ? error.message : String(error),
+    },
+  };
+}