@zintrust/trace 0.4.75

package/src/dashboard/zintrust-debuger.svg

@@ -0,0 +1,30 @@
+<svg width="120" height="120" viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="zt-g1e" x1="15" y1="15" x2="85" y2="85" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#38bdf8" />
+      <stop offset="1" stop-color="#22c55e" />
+    </linearGradient>
+  </defs>
+  <path
+    d="M50 8L18 22V46C18 66.2 32 84.1 50 92C68 84.1 82 66.2 82 46V22L50 8Z"
+    stroke="url(#zt-g1e)"
+    stroke-width="6"
+    stroke-linejoin="round"
+  />
+  <path
+    d="M34 54H42L46 44L52 62L58 50H66"
+    stroke="white"
+    stroke-width="8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <circle cx="34" cy="54" r="2.8" fill="white" fill-opacity="0.7" />
+  <circle cx="66" cy="50" r="2.8" fill="white" fill-opacity="0.7" />
+  <path
+    d="M30 28H70"
+    stroke="white"
+    stroke-opacity="0.12"
+    stroke-width="3"
+    stroke-linecap="round"
+  />
+</svg>

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * @zintrust/trace — public API surface.
+ *
+ * Zero side-effects. Import watchers, storage, dashboard, and config
+ * individually. For full auto-initialisation, use:
+ *   import '@zintrust/trace/register';
+ */
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+export { TraceConfig } from './config';
+
+// ---------------------------------------------------------------------------
+// Storage
+// ---------------------------------------------------------------------------
+export { TraceStorage } from './storage';
+export type { ITraceStorage } from './storage';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+export { TraceContext } from './context';
+
+// ---------------------------------------------------------------------------
+// Dashboard
+// ---------------------------------------------------------------------------
+export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';
+export type { TraceDashboardOptions, TraceDashboardRegistrationOptions } from './dashboard/routes';
+
+// ---------------------------------------------------------------------------
+// Watchers (named re-exports for use with custom wiring)
+// ---------------------------------------------------------------------------
+export { AuthWatcher } from './watchers/AuthWatcher';
+export { BatchWatcher } from './watchers/BatchWatcher';
+export { CacheWatcher } from './watchers/CacheWatcher';
+export { CommandWatcher } from './watchers/CommandWatcher';
+export { DumpWatcher } from './watchers/DumpWatcher';
+export { EventWatcher } from './watchers/EventWatcher';
+export { ExceptionWatcher } from './watchers/ExceptionWatcher';
+export { GateWatcher } from './watchers/GateWatcher';
+export { HttpClientWatcher } from './watchers/HttpClientWatcher';
+export { HttpWatcher } from './watchers/HttpWatcher';
+export { JobWatcher } from './watchers/JobWatcher';
+export { LogWatcher } from './watchers/LogWatcher';
+export { MailWatcher } from './watchers/MailWatcher';
+export { MiddlewareWatcher } from './watchers/MiddlewareWatcher';
+export { ModelWatcher } from './watchers/ModelWatcher';
+export { NotificationWatcher } from './watchers/NotificationWatcher';
+export { QueryWatcher } from './watchers/QueryWatcher';
+export { RedisWatcher } from './watchers/RedisWatcher';
+export { ScheduleWatcher } from './watchers/ScheduleWatcher';
+export { ViewWatcher } from './watchers/ViewWatcher';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export { EntryType } from './types';
+export type {
+  AuthContent,
+  BatchContent,
+  CacheContent,
+  ClientRequestContent,
+  CommandContent,
+  DumpContent,
+  EntryTypeValue,
+  EventContent,
+  ExceptionContent,
+  GateContent,
+  ITraceConfig,
+  ITraceEntry,
+  ITraceWatcher,
+  ITraceWatcherConfig,
+  JobContent,
+  LogContent,
+  MailContent,
+  MiddlewareContent,
+  ModelContent,
+  NotificationContent,
+  QueryContent,
+  RedactionConfig,
+  RedisContent,
+  RequestContent,
+  ScheduleContent,
+  TraceConfigOverrides,
+  ViewContent,
+  WatcherToggles,
+} from './types';

package/src/plugin.ts

@@ -0,0 +1,9 @@
+export type {};
+
+type GlobalTracePluginState = {
+  __zintrust_system_trace_plugin_requested__?: boolean;
+};
+
+const globalTracePluginState = globalThis as unknown as GlobalTracePluginState;
+
+globalTracePluginState.__zintrust_system_trace_plugin_requested__ = true;

package/src/register.ts

@@ -0,0 +1,219 @@
+/**
+ * @zintrust/trace register side-effect module.
+ *
+ * For plugin-file activation, prefer:
+ *   import '@zintrust/trace/plugin';
+ *
+ * The framework boot layer will lazy-load this register module once the app
+ * runtime is ready. Importing this file directly is still supported for
+ * advanced manual bootstrap flows that intentionally activate the trace
+ * after databases and the kernel are available.
+ *
+ * Config is read from environment variables (TRACE_* keys) matching
+ * the defaults in TraceConfig. For custom overrides supply them via
+ * calling `initTrace(overrides)` instead.
+ *
+ * Routes are NOT auto-mounted here. Wire the dashboard into your router:
+ *   import { registerTraceDashboard } from '@zintrust/trace/ui';
+ *   registerTraceDashboard(router, {
+ *     middleware: ['admin'],
+ *   });
+ */
+import { TraceConfig } from './config';
+import { TraceContext } from './context';
+import { TraceStorage } from './storage';
+import type { ITraceWatcherConfig } from './types';
+
+export type {}; // side-effect ESM module
+
+type GlobalTraceRegisterState = {
+  __zintrust_system_trace_register_initialized__?: boolean;
+  __zintrust_system_trace_plugin_requested__?: boolean;
+};
+
+const globalTraceRegisterState = globalThis as unknown as GlobalTraceRegisterState;
+globalTraceRegisterState.__zintrust_system_trace_plugin_requested__ = true;
+const traceAlreadyInitialized =
+  globalTraceRegisterState.__zintrust_system_trace_register_initialized__ === true;
+
+if (!traceAlreadyInitialized) {
+  globalTraceRegisterState.__zintrust_system_trace_register_initialized__ = true;
+}
+
+const importCore = async (): Promise<unknown> => {
+  try {
+    return await import('@zintrust/core');
+  } catch {
+    return {};
+  }
+};
+
+type CoreApi = {
+  Env?: {
+    getBool(key: string, fallback: boolean): boolean;
+    get(key: string, fallback: string): string;
+    getInt(key: string, fallback: number): number;
+  };
+  useDatabase?: (config?: unknown, connection?: string) => import('@zintrust/core').IDatabase;
+  RequestContext?: {
+    current(): unknown;
+  };
+};
+
+type GlobalMiddlewareRegistrarState = {
+  __zintrust_register_global_middleware__?: ITraceWatcherConfig['registerMiddleware'];
+  __zintrust_pending_global_middlewares__?: Array<
+    Parameters<NonNullable<ITraceWatcherConfig['registerMiddleware']>>[0]
+  >;
+};
+
+const resolveRegisterMiddleware = (): NonNullable<ITraceWatcherConfig['registerMiddleware']> => {
+  const globalMiddlewareRegistrarState = globalThis as unknown as GlobalMiddlewareRegistrarState;
+
+  return (middleware): void => {
+    const registerMiddleware =
+      globalMiddlewareRegistrarState.__zintrust_register_global_middleware__;
+    if (typeof registerMiddleware === 'function') {
+      registerMiddleware(middleware);
+      return;
+    }
+
+    globalMiddlewareRegistrarState.__zintrust_pending_global_middlewares__ ??= [];
+    globalMiddlewareRegistrarState.__zintrust_pending_global_middlewares__.push(middleware);
+  };
+};
+
+const resolveTraceConnectionName = (
+  env: Pick<NonNullable<CoreApi['Env']>, 'get'> | undefined,
+  configuredConnection?: string
+): string => {
+  const resolveDefaultConnection = (): string => {
+    const defaultConnection = env?.get('DB_CONNECTION', '').trim() ?? '';
+    if (defaultConnection === '' || defaultConnection === 'default') return 'default';
+    return defaultConnection;
+  };
+
+  const explicitConnection = configuredConnection?.trim();
+  if (explicitConnection !== undefined && explicitConnection !== '') {
+    return explicitConnection === 'default' ? resolveDefaultConnection() : explicitConnection;
+  }
+
+  return resolveDefaultConnection();
+};
+
+const core = (await importCore()) as CoreApi;
+const Env = core.Env;
+
+if (!traceAlreadyInitialized && Env) {
+  const enabled = Env.getBool('TRACE_ENABLED', false);
+
+  if (enabled) {
+    const connection = Env.get('TRACE_DB_CONNECTION', '') || undefined;
+    const pruneAfterHours = Env.getInt('TRACE_PRUNE_HOURS', 24);
+    const slowQueryThreshold = Env.getInt('TRACE_SLOW_QUERY_MS', 100);
+    const logMinLevel = Env.get('TRACE_LOG_LEVEL', 'info') as
+      | 'debug'
+      | 'info'
+      | 'warn'
+      | 'error'
+      | 'fatal';
+
+    const config = TraceConfig.merge({
+      enabled,
+      connection,
+      pruneAfterHours,
+      slowQueryThreshold,
+      logMinLevel,
+    });
+
+    const db = core.useDatabase?.(undefined, resolveTraceConnectionName(Env, connection));
+
+    if (db) {
+      const storage = TraceStorage.resolveStorage(db);
+
+      if (core.RequestContext) {
+        TraceContext.setRequestContextImpl(
+          core.RequestContext as {
+            current?: () => unknown;
+            peek?: () => unknown;
+          }
+        );
+      }
+
+      const [
+        { HttpWatcher },
+        { QueryWatcher },
+        { LogWatcher },
+        { ExceptionWatcher },
+        { JobWatcher },
+        { CacheWatcher },
+        { ScheduleWatcher },
+        { MailWatcher },
+        { AuthWatcher },
+        { EventWatcher },
+        { ModelWatcher },
+        { NotificationWatcher },
+        { RedisWatcher },
+        { GateWatcher },
+        { MiddlewareWatcher },
+        { CommandWatcher },
+        { BatchWatcher },
+        { DumpWatcher },
+        { ViewWatcher },
+        { HttpClientWatcher },
+      ] = await Promise.all([
+        import('./watchers/HttpWatcher'),
+        import('./watchers/QueryWatcher'),
+        import('./watchers/LogWatcher'),
+        import('./watchers/ExceptionWatcher'),
+        import('./watchers/JobWatcher'),
+        import('./watchers/CacheWatcher'),
+        import('./watchers/ScheduleWatcher'),
+        import('./watchers/MailWatcher'),
+        import('./watchers/AuthWatcher'),
+        import('./watchers/EventWatcher'),
+        import('./watchers/ModelWatcher'),
+        import('./watchers/NotificationWatcher'),
+        import('./watchers/RedisWatcher'),
+        import('./watchers/GateWatcher'),
+        import('./watchers/MiddlewareWatcher'),
+        import('./watchers/CommandWatcher'),
+        import('./watchers/BatchWatcher'),
+        import('./watchers/DumpWatcher'),
+        import('./watchers/ViewWatcher'),
+        import('./watchers/HttpClientWatcher'),
+      ]);
+
+      const watcherArgs = { storage, config, db };
+
+      HttpWatcher.register({ ...watcherArgs, registerMiddleware: resolveRegisterMiddleware() });
+
+      QueryWatcher.register(watcherArgs);
+      LogWatcher.register(watcherArgs);
+      ExceptionWatcher.register(watcherArgs);
+      JobWatcher.register(watcherArgs);
+      CacheWatcher.register(watcherArgs);
+      ScheduleWatcher.register(watcherArgs);
+      MailWatcher.register(watcherArgs);
+      AuthWatcher.register(watcherArgs);
+      EventWatcher.register(watcherArgs);
+      ModelWatcher.register(watcherArgs);
+      NotificationWatcher.register(watcherArgs);
+      RedisWatcher.register(watcherArgs);
+      GateWatcher.register(watcherArgs);
+      MiddlewareWatcher.register(watcherArgs);
+      CommandWatcher.register(watcherArgs);
+      BatchWatcher.register(watcherArgs);
+      DumpWatcher.register(watcherArgs);
+      ViewWatcher.register(watcherArgs);
+      HttpClientWatcher.register(watcherArgs);
+    } else {
+      // eslint-disable-next-line no-console
+      console.warn('[trace] Could not resolve database connection - skipping init.');
+    }
+  }
+} else if (!traceAlreadyInitialized) {
+  // Running outside a ZinTrust project - skip init silently.
+  // eslint-disable-next-line no-console
+  console.warn('[trace] @zintrust/core not found - trace will not be activated.');
+}

package/src/storage/TraceStorage.ts

@@ -0,0 +1,306 @@
+/**
+ * TraceStorage — sealed namespace wrapping the D1/SQLite driver.
+ * Resolves the correct IDatabase from the app config, then delegates all
+ * read/write operations to the trace storage facade.
+ */
+import type { IDatabase } from '@zintrust/core';
+import type { EntryTypeValue, ITraceEntry, ITraceStorage, QueryEntriesOptions } from '../types';
+import { familyHash } from '../utils/familyHash';
+
+const TABLE_ENTRIES = 'zin_trace_entries';
+const TABLE_TAGS = 'zin_trace_entries_tags';
+const TABLE_MONITORING = 'zin_trace_monitoring';
+
+const generateUuid = (): string => crypto.randomUUID();
+
+type EntryRow = {
+  id: number;
+  uuid: string;
+  batch_id: string;
+  family_hash: string | null;
+  type: string;
+  content: string;
+  is_latest: number | boolean;
+  created_at: number;
+};
+
+type TagRow = { entry_uuid: string; tag: string };
+
+const rowToEntry = (row: EntryRow, tags: string[]): ITraceEntry => ({
+  uuid: row.uuid,
+  batchId: row.batch_id,
+  familyHash: row.family_hash ?? undefined,
+  type: row.type as EntryTypeValue,
+  content: JSON.parse(row.content) as unknown,
+  tags,
+  isLatest: Boolean(row.is_latest),
+  createdAt: row.created_at,
+});
+
+const insertTags = async (db: IDatabase, uuid: string, tags: string[]): Promise<void> => {
+  if (tags.length === 0) return;
+
+  await Promise.all(
+    tags.map(async (tag) => {
+      await db.execute(`INSERT OR IGNORE INTO ${TABLE_TAGS} (entry_uuid, tag) VALUES (?, ?)`, [
+        uuid,
+        tag,
+      ]);
+    })
+  );
+};
+
+const buildEntryFilters = (
+  opts: QueryEntriesOptions
+): { joinClause: string; whereClause: string; params: unknown[]; countParams: unknown[] } => {
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (opts.type) {
+    conditions.push('e.type = ?');
+    params.push(opts.type);
+  }
+  if (opts.batchId) {
+    conditions.push('e.batch_id = ?');
+    params.push(opts.batchId);
+  }
+  if (opts.from) {
+    conditions.push('e.created_at >= ?');
+    params.push(opts.from);
+  }
+  if (opts.to) {
+    conditions.push('e.created_at <= ?');
+    params.push(opts.to);
+  }
+
+  let joinClause = '';
+  if (opts.tag) {
+    joinClause = `INNER JOIN ${TABLE_TAGS} t ON t.entry_uuid = e.uuid AND t.tag = ?`;
+    params.unshift(opts.tag);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const countParams = opts.tag ? [opts.tag, ...params.slice(1)] : [...params];
+
+  return { joinClause, whereClause, params, countParams };
+};
+
+const loadTagsByUuid = async (db: IDatabase, uuids: string[]): Promise<Map<string, string[]>> => {
+  const tagsByUuid = new Map<string, string[]>();
+  if (uuids.length === 0) return tagsByUuid;
+
+  const tagRows = (await db.query(
+    `SELECT entry_uuid, tag FROM ${TABLE_TAGS} WHERE entry_uuid IN (${uuids.map(() => '?').join(',')})`,
+    uuids
+  )) as TagRow[];
+
+  for (const tagRow of tagRows) {
+    const tags = tagsByUuid.get(tagRow.entry_uuid) ?? [];
+    tags.push(tagRow.tag);
+    tagsByUuid.set(tagRow.entry_uuid, tags);
+  }
+
+  return tagsByUuid;
+};
+
+// The storage facade intentionally groups related DB operations in one factory.
+// eslint-disable-next-line max-lines-per-function
+const createStorage = (db: IDatabase): ITraceStorage => {
+  const writeEntry = async (entry: ITraceEntry): Promise<void> => {
+    const uuid = entry.uuid || generateUuid();
+    await db.execute(
+      `INSERT INTO ${TABLE_ENTRIES} (uuid, batch_id, family_hash, type, content, is_latest, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        uuid,
+        entry.batchId,
+        entry.familyHash ?? null,
+        entry.type,
+        JSON.stringify(entry.content),
+        entry.isLatest ? 1 : 0,
+        entry.createdAt,
+      ]
+    );
+
+    await insertTags(db, uuid, entry.tags);
+  };
+
+  const updateEntry = async (
+    uuid: string,
+    patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+  ): Promise<void> => {
+    const sets: string[] = [];
+    const params: unknown[] = [];
+
+    if (patch.content !== undefined) {
+      sets.push('content = ?');
+      params.push(JSON.stringify(patch.content));
+    }
+    if (patch.isLatest !== undefined) {
+      sets.push('is_latest = ?');
+      params.push(patch.isLatest ? 1 : 0);
+    }
+
+    if (sets.length === 0) return;
+    params.push(uuid);
+
+    await db.execute(`UPDATE ${TABLE_ENTRIES} SET ${sets.join(', ')} WHERE uuid = ?`, params);
+  };
+
+  const markFamilyStale = async (hash: string, exceptUuid: string): Promise<void> => {
+    await db.execute(
+      `UPDATE ${TABLE_ENTRIES} SET is_latest = 0
+       WHERE family_hash = ? AND uuid != ? AND is_latest = 1`,
+      [hash, exceptUuid]
+    );
+  };
+
+  const queryEntries = async (
+    opts: QueryEntriesOptions
+  ): Promise<{ data: ITraceEntry[]; total: number }> => {
+    const page = opts.page ?? 1;
+    const perPage = opts.perPage ?? 50;
+    const offset = (page - 1) * perPage;
+    const { joinClause, whereClause, params, countParams } = buildEntryFilters(opts);
+
+    const countResult = (await db.queryOne(
+      `SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}`,
+      countParams
+    )) as { cnt: number } | undefined;
+    const total = countResult?.cnt ?? 0;
+
+    const rows = (await db.query(
+      `SELECT e.id, e.uuid, e.batch_id, e.family_hash, e.type, e.content, e.is_latest, e.created_at
+       FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}
+       ORDER BY e.created_at DESC, e.id DESC
+       LIMIT ? OFFSET ?`,
+      [...params, perPage, offset]
+    )) as EntryRow[];
+
+    const tagsByUuid = await loadTagsByUuid(
+      db,
+      rows.map((row) => row.uuid)
+    );
+
+    return {
+      data: rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? [])),
+      total,
+    };
+  };
+
+  const getEntry = async (uuid: string): Promise<ITraceEntry | null> => {
+    const row = (await db.queryOne(
+      `SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
+       FROM ${TABLE_ENTRIES}
+       WHERE uuid = ?`,
+      [uuid]
+    )) as EntryRow | undefined;
+    if (!row) return null;
+
+    const tags = (await db.query(`SELECT tag FROM ${TABLE_TAGS} WHERE entry_uuid = ?`, [
+      uuid,
+    ])) as Array<{
+      tag: string;
+    }>;
+    return rowToEntry(
+      row,
+      tags.map((tag) => tag.tag)
+    );
+  };
+
+  const getBatch = async (batchId: string): Promise<ITraceEntry[]> => {
+    const rows = (await db.query(
+      `SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
+       FROM ${TABLE_ENTRIES}
+       WHERE batch_id = ?
+       ORDER BY created_at ASC, id ASC`,
+      [batchId]
+    )) as EntryRow[];
+    if (rows.length === 0) return [];
+
+    const tagsByUuid = await loadTagsByUuid(
+      db,
+      rows.map((row) => row.uuid)
+    );
+
+    return rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? []));
+  };
+
+  const prune = async (olderThanMs: number, keepExceptions = false): Promise<number> => {
+    const countResult = (await db.queryOne(
+      `SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES}
+       WHERE created_at < ?
+       ${keepExceptions ? "AND type != 'exception'" : ''}`,
+      [olderThanMs]
+    )) as { cnt: number } | undefined;
+    const deleted = countResult?.cnt ?? 0;
+    if (deleted === 0) return 0;
+
+    await db.execute(
+      `DELETE FROM ${TABLE_ENTRIES}
+       WHERE created_at < ?
+       ${keepExceptions ? "AND type != 'exception'" : ''}`,
+      [olderThanMs]
+    );
+
+    return deleted;
+  };
+
+  const clear = async (): Promise<void> => {
+    await db.execute(`DELETE FROM ${TABLE_ENTRIES}`, []);
+  };
+
+  const getMonitoring = async (): Promise<string[]> => {
+    const rows = (await db.query(`SELECT tag FROM ${TABLE_MONITORING}`, [])) as Array<{
+      tag: string;
+    }>;
+    return rows.map((row) => row.tag);
+  };
+
+  const addMonitoring = async (tag: string): Promise<void> => {
+    await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
+  };
+
+  const removeMonitoring = async (tag: string): Promise<void> => {
+    await db.execute(`DELETE FROM ${TABLE_MONITORING} WHERE tag = ?`, [tag]);
+  };
+
+  const stats = async (): Promise<Record<EntryTypeValue, number>> => {
+    const rows = (await db.query(
+      `SELECT type, COUNT(*) as cnt FROM ${TABLE_ENTRIES} GROUP BY type`,
+      []
+    )) as Array<{ type: string; cnt: number }>;
+    const output: Record<string, number> = {};
+    for (const row of rows) {
+      output[row.type] = row.cnt;
+    }
+    return output as Record<EntryTypeValue, number>;
+  };
+
+  return {
+    writeEntry,
+    updateEntry,
+    markFamilyStale,
+    queryEntries,
+    getEntry,
+    getBatch,
+    prune,
+    clear,
+    getMonitoring,
+    addMonitoring,
+    removeMonitoring,
+    stats,
+  };
+};
+
+const resolveStorage = (db: IDatabase): ITraceStorage => {
+  return createStorage(db);
+};
+
+const reset = (): void => {
+  return;
+};
+
+export const TraceStorage = Object.freeze({ resolveStorage, reset, familyHash });
+
+export { type ITraceStorage } from '../types';

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export { TraceStorage } from './TraceStorage';
+export type { ITraceStorage } from './TraceStorage';