@zintrust/trace 0.4.75

package/src/cli-register.ts

@@ -0,0 +1,63 @@
+type Registry = {
+  register: (id: string, provider: CliCommandProvider) => void;
+};
+
+type CliCommandProvider = {
+  getCommand: () => unknown;
+  name?: string;
+};
+
+type TraceCommandsModule = {
+  TraceCommands: {
+    createTracePruneProvider: () => CliCommandProvider;
+    createTraceClearProvider: () => CliCommandProvider;
+    createTraceStatusProvider: () => CliCommandProvider;
+    createTraceMigrateProvider: () => CliCommandProvider;
+  };
+};
+
+const commandModule = (await import('@zintrust/core/cli')) as unknown as TraceCommandsModule;
+
+const getTraceProviders = (): Array<[string, CliCommandProvider]> => {
+  const { TraceCommands } = commandModule;
+
+  return [
+    ['trace:prune', TraceCommands.createTracePruneProvider()],
+    ['trace:clear', TraceCommands.createTraceClearProvider()],
+    ['trace:status', TraceCommands.createTraceStatusProvider()],
+    ['migrate:trace', TraceCommands.createTraceMigrateProvider()],
+  ];
+};
+
+export function registerTraceCliCommands(registry: Registry): void {
+  for (const [id, provider] of getTraceProviders()) {
+    registry.register(id, provider);
+  }
+}
+
+type GlobalWithRegistry = {
+  __zintrust_cli_command_registry__?: Map<string, CliCommandProvider>;
+};
+
+const globalWithRegistry = globalThis as unknown as GlobalWithRegistry;
+const globalRegistry =
+  globalWithRegistry.__zintrust_cli_command_registry__ ??
+  (globalWithRegistry.__zintrust_cli_command_registry__ = new Map<string, CliCommandProvider>());
+
+registerTraceCliCommands({
+  register: (id, provider) => {
+    globalRegistry.set(id, provider);
+  },
+});
+
+try {
+  const coreCli = (await import('@zintrust/core/cli')) as unknown as {
+    OptionalCliCommandRegistry?: Registry;
+  };
+
+  if (coreCli.OptionalCliCommandRegistry !== undefined) {
+    registerTraceCliCommands(coreCli.OptionalCliCommandRegistry);
+  }
+} catch {
+  // no-op
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+/**
+ * TraceConfig — defaults and merge helper for @zintrust/trace
+ */
+import type { ITraceConfig, TraceConfigOverrides } from './types';
+
+const DEFAULTS: ITraceConfig = Object.freeze({
+  enabled: false,
+  connection: undefined,
+  pruneAfterHours: 24,
+  ignoreRoutes: ['/trace', '/health', '/ping'],
+  slowQueryThreshold: 100,
+  logMinLevel: 'info',
+  watchers: {},
+  redaction: {
+    headers: ['authorization', 'cookie', 'x-api-key', 'x-auth-token'],
+    body: ['password', 'token', 'secret', 'apiKey', 'api_key', 'jwt', 'bearer'],
+    query: [],
+  },
+} satisfies ITraceConfig);
+
+const isWatcherEnabled = (config: ITraceConfig, key: keyof ITraceConfig['watchers']): boolean => {
+  const override = config.watchers[key];
+  return override !== false; // undefined = enabled by default; explicit false = disabled
+};
+
+export const TraceConfig = Object.freeze({
+  defaults(): ITraceConfig {
+    return DEFAULTS;
+  },
+
+  merge(overrides?: TraceConfigOverrides): ITraceConfig {
+    if (overrides === undefined || overrides === null) return DEFAULTS;
+    return Object.freeze({
+      ...DEFAULTS,
+      ...overrides,
+      watchers: { ...DEFAULTS.watchers, ...(overrides.watchers ?? {}) },
+      redaction: {
+        ...DEFAULTS.redaction,
+        ...(overrides.redaction ?? {}),
+      },
+      ignoreRoutes: overrides.ignoreRoutes ?? DEFAULTS.ignoreRoutes,
+    });
+  },
+
+  isWatcherEnabled,
+});

package/src/context.ts

@@ -0,0 +1,101 @@
+/**
+ * TraceContext — sealed namespace for batch_id, userId, hostname, and memory.
+ * Piggybacks on RequestContext (already available in core) — no new ALS store.
+ */
+type RequestContextProvider = {
+  current?: () => unknown;
+  peek?: () => unknown;
+};
+
+// Lazy reference to ZinTrust RequestContext — typed as unknown to stay runtime-agnostic.
+let _reqCtx: RequestContextProvider | undefined;
+
+const getRequestContext = (): RequestContextProvider | undefined => {
+  return _reqCtx;
+};
+
+const setRequestContextImpl = (impl: RequestContextProvider): void => {
+  _reqCtx = impl;
+};
+
+const isPromiseLike = (value: unknown): value is PromiseLike<unknown> => {
+  return typeof value === 'object' && value !== null && 'then' in value;
+};
+
+const getCurrentContext = (): Record<string, unknown> | undefined => {
+  const provider = getRequestContext();
+  if (!provider) return undefined;
+
+  let currentValue: unknown;
+
+  if (typeof provider.peek === 'function') {
+    currentValue = provider.peek();
+  } else if (typeof provider.current === 'function') {
+    currentValue = provider.current();
+  } else {
+    currentValue = undefined;
+  }
+
+  if (isPromiseLike(currentValue)) return undefined;
+  if (typeof currentValue !== 'object' || currentValue === null) return undefined;
+
+  return currentValue as Record<string, unknown>;
+};
+
+const getContextString = (key: 'traceId' | 'userId' | 'path'): string | undefined => {
+  const value = getCurrentContext()?.[key];
+  if (typeof value === 'string' && value.trim() !== '') return value;
+  if (typeof value === 'number') return String(value);
+  return undefined;
+};
+
+const getBatchId = (): string => {
+  return getContextString('traceId') ?? crypto.randomUUID();
+};
+
+const getUserId = (): string | undefined => {
+  return getContextString('userId');
+};
+
+const getRequestPath = (): string | undefined => {
+  return getContextString('path');
+};
+
+const getHostname = (): string => {
+  // Workers do not expose `os` or `process` — return 'worker' as fallback.
+  if (typeof process !== 'undefined' && typeof process.env === 'object') {
+    try {
+      // Dynamic import avoids the need for a node-singletons wrapper at the type level.
+      // Hostname is non-critical; we fall back gracefully.
+      const hostname = (process.env as Record<string, string | undefined>)['HOSTNAME'];
+      if (typeof hostname === 'string' && hostname.length > 0) return hostname;
+    } catch {
+      // fall through
+    }
+    return 'node';
+  }
+  return 'worker';
+};
+
+const getMemory = (): number | null => {
+  if (typeof process !== 'undefined' && typeof process.memoryUsage === 'function') {
+    try {
+      return Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+};
+
+const now = (): number => Date.now();
+
+export const TraceContext = Object.freeze({
+  getBatchId,
+  getUserId,
+  getRequestPath,
+  getHostname,
+  getMemory,
+  now,
+  setRequestContextImpl,
+});

package/src/dashboard/handlers.ts

@@ -0,0 +1,197 @@
+/**
+ * TraceDashboard handlers — pure handler functions wired to ITraceStorage.
+ * No auth in this layer — caller mounts middleware as needed.
+ */
+import type { IRequest, IResponse } from '@zintrust/core';
+import type { EntryTypeValue, ITraceStorage } from '../types';
+
+// ---------------------------------------------------------------------------
+// Storage holder (set once from routes.ts)
+// ---------------------------------------------------------------------------
+
+let _storage: ITraceStorage | null = null;
+
+export const setHandlerStorage = (s: ITraceStorage): void => {
+  _storage = s;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const requireStorage = (res: IResponse): boolean => {
+  if (_storage) {
+    return true;
+  }
+
+  res.setStatus(503).json({ error: 'Trace not initialised' });
+  return false;
+};
+
+const getStorage = (res: IResponse): ITraceStorage | null => {
+  if (requireStorage(res)) {
+    return _storage;
+  }
+
+  return null;
+};
+
+const qp = (req: IRequest, key: string): string | undefined => {
+  const v = req.getQueryParam(key);
+  return Array.isArray(v) ? v[0] : v;
+};
+
+const qpInt = (req: IRequest, key: string, fallback: number): number => {
+  const raw = qp(req, key);
+  const n = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isNaN(n) ? fallback : n;
+};
+
+const getNumericQueryParam = (req: IRequest, key: string): number | undefined => {
+  const raw = qp(req, key);
+  if (typeof raw === 'string') {
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Entry handlers
+// ---------------------------------------------------------------------------
+
+export async function listEntries(req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage !== null) {
+    const opts = {
+      type: qp(req, 'type') as EntryTypeValue | undefined,
+      tag: qp(req, 'tag'),
+      batchId: qp(req, 'batchId'),
+      from: getNumericQueryParam(req, 'from'),
+      to: getNumericQueryParam(req, 'to'),
+      page: qpInt(req, 'page', 1),
+      perPage: Math.min(qpInt(req, 'perPage', 50), 200),
+    };
+    try {
+      const result = await storage.queryEntries(opts);
+      res.json({ ok: true, ...result, page: opts.page, perPage: opts.perPage });
+    } catch (err) {
+      res.setStatus(500).json({ error: (err as Error).message });
+    }
+  }
+}
+
+export async function getEntry(req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  const uuid = req.getParam('uuid');
+  if (uuid) {
+    try {
+      const entry = await storage.getEntry(uuid);
+      if (entry) {
+        res.json({ ok: true, entry });
+        return;
+      }
+
+      res.setStatus(404).json({ error: 'Not found' });
+      return;
+    } catch (err) {
+      res.setStatus(500).json({ error: (err as Error).message });
+      return;
+    }
+  }
+
+  res.setStatus(400).json({ error: 'uuid required' });
+}
+
+export async function getBatch(req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  const batchId = req.getParam('batchId');
+  if (batchId) {
+    try {
+      const entries = await storage.getBatch(batchId);
+      res.json({ ok: true, entries });
+      return;
+    } catch (err) {
+      res.setStatus(500).json({ error: (err as Error).message });
+      return;
+    }
+  }
+
+  res.setStatus(400).json({ error: 'batchId required' });
+}
+
+export async function getStats(_req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  try {
+    const stats = await storage.stats();
+    res.json({ ok: true, stats });
+  } catch (err) {
+    res.setStatus(500).json({ error: (err as Error).message });
+  }
+}
+
+export async function clearEntries(_req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  try {
+    await storage.clear();
+    res.json({ ok: true });
+  } catch (err) {
+    res.setStatus(500).json({ error: (err as Error).message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Monitoring handlers
+// ---------------------------------------------------------------------------
+
+export async function getMonitoring(_req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  try {
+    const tags = await storage.getMonitoring();
+    res.json({ ok: true, tags });
+  } catch (err) {
+    res.setStatus(500).json({ error: (err as Error).message });
+  }
+}
+
+export async function addMonitoring(req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  const tag = req.getParam('tag');
+  if (tag) {
+    try {
+      await storage.addMonitoring(tag);
+      res.json({ ok: true });
+      return;
+    } catch (err) {
+      res.setStatus(500).json({ error: (err as Error).message });
+      return;
+    }
+  }
+
+  res.setStatus(400).json({ error: 'tag required' });
+}
+
+export async function removeMonitoring(req: IRequest, res: IResponse): Promise<void> {
+  const storage = getStorage(res);
+  if (storage === null) return;
+  const tag = req.getParam('tag');
+  if (tag) {
+    try {
+      await storage.removeMonitoring(tag);
+      res.json({ ok: true });
+      return;
+    } catch (err) {
+      res.setStatus(500).json({ error: (err as Error).message });
+      return;
+    }
+  }
+
+  res.setStatus(400).json({ error: 'tag required' });
+}

package/src/dashboard/routes.ts

@@ -0,0 +1,101 @@
+/**
+ * Dashboard route registrar for @zintrust/trace.
+ * Mounts the SPA + all REST API endpoints under the configured basePath.
+ * Auth is NOT applied here — callers add middleware via routeOptions.
+ */
+import { appConfig, Router, useDatabase, type IRouter, type RouteOptions } from '@zintrust/core';
+import { TraceConfig } from '../config';
+import { TraceStorage } from '../storage';
+import type { ITraceStorage } from '../types';
+import {
+  addMonitoring,
+  clearEntries,
+  getBatch,
+  getEntry,
+  getMonitoring,
+  getStats,
+  listEntries,
+  removeMonitoring,
+  setHandlerStorage,
+} from './handlers';
+import { buildDashboardHtml } from './ui';
+
+export type TraceDashboardOptions = {
+  /** Base path for the dashboard, e.g. '/trace'. Defaults to '/trace'. */
+  basePath?: string;
+  /** Optional ZinTrust middleware names to apply to all routes. */
+  middleware?: ReadonlyArray<string>;
+};
+
+export type TraceDashboardRegistrationOptions = TraceDashboardOptions & {
+  /** Optional trace storage connection override. Defaults to TraceConfig / runtime default. */
+  connectionName?: string;
+};
+
+const resolveDashboardConnectionName = (connectionName?: string): string | undefined => {
+  const explicitConnection = connectionName?.trim();
+  if (explicitConnection !== undefined && explicitConnection !== '') {
+    return explicitConnection;
+  }
+
+  const configuredConnection = TraceConfig.merge().connection?.trim();
+  return configuredConnection === undefined || configuredConnection === ''
+    ? undefined
+    : configuredConnection;
+};
+
+export const registerTraceRoutes = (
+  router: IRouter,
+  storage: ITraceStorage,
+  options: TraceDashboardOptions = {}
+): void => {
+  setHandlerStorage(storage);
+
+  const base = options.basePath ?? '/trace';
+  const routeOptions: RouteOptions | undefined =
+    (options.middleware?.length ?? 0) > 0
+      ? ({ middleware: options.middleware } as RouteOptions)
+      : undefined;
+
+  // SPA shell
+  Router.get(
+    router,
+    base,
+    (_req, res) => {
+      res.html(buildDashboardHtml(base, appConfig.name));
+    },
+    routeOptions
+  );
+  // Serve the SPA for any /<basePath>/* sub-path (client-side routing)
+  Router.get(
+    router,
+    `${base}/*`,
+    (_req, res) => {
+      res.html(buildDashboardHtml(base, appConfig.name));
+    },
+    routeOptions
+  );
+
+  // REST API
+  Router.group(router, `${base}/api`, (r: IRouter) => {
+    Router.get(r, '/entries', listEntries, routeOptions);
+    Router.get(r, '/entries/:uuid', getEntry, routeOptions);
+    Router.del(r, '/entries', clearEntries, routeOptions);
+    Router.get(r, '/batch/:batchId', getBatch, routeOptions);
+    Router.get(r, '/stats', getStats, routeOptions);
+    Router.get(r, '/monitoring', getMonitoring, routeOptions);
+    Router.post(r, '/monitoring/:tag', addMonitoring, routeOptions);
+    Router.del(r, '/monitoring/:tag', removeMonitoring, routeOptions);
+  });
+};
+
+export const registerTraceDashboard = (
+  router: IRouter,
+  options: TraceDashboardRegistrationOptions = {}
+): void => {
+  const storage = TraceStorage.resolveStorage(
+    useDatabase(undefined, resolveDashboardConnectionName(options.connectionName))
+  );
+
+  registerTraceRoutes(router, storage, options);
+};