@zintrust/trace 1.6.0 → 1.6.2

package/dist/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.0",
-  "buildDate": "2026-04-29T16:58:34.543Z",
+  "version": "1.5.1",
+  "buildDate": "2026-04-28T16:08:58.961Z",
   "buildEnvironment": {
-    "node": "v20.20.2",
-    "platform": "linux",
-    "arch": "x64"
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
   },
   "git": {
-    "commit": "bcc45109",
-    "branch": "master"
+    "commit": "6c6a3f59",
+    "branch": "release"
   },
   "package": {
     "engines": {
@@ -29,6 +29,10 @@
       "size": 4640,
       "sha256": "c51cc312046b6b2bbe1673f1ff9508425cc7140a1d2341907f67aa36069c09f9"
     },
+    "build-manifest.json": {
+      "size": 15912,
+      "sha256": "b7ce0234e13707d03336dbad905b5c1403a910880469504ec6cde78ad67fe9a9"
+    },
     "cli-register.d.ts": {
       "size": 255,
       "sha256": "da8d689fe5ef32e97e755f28017e4d3cb1aa63489073a71907ea41ad5761ede9"
@@ -83,7 +87,7 @@
     },
     "index.js": {
       "size": 3421,
-      "sha256": "34223487b1e087a904da56e1e76a4fabcc38c34538330feaa355636311b59fce"
+      "sha256": "6cab0d02424c088c23dce13c349f177993fd55f21864eea1842c2276a81ad526"
     },
     "ingest/TraceIngestGateway.d.ts": {
       "size": 786,
@@ -146,8 +150,16 @@
       "sha256": "535869aa1bfcdf0ec26fad27d7f18bb8822bc586c38fcc5ffdde5274ecbea17e"
     },
     "register.js": {
-      "size": 19592,
-      "sha256": "5f0510477750c2b7e40aaa869ae2e655a41ca643d5c3e1cf291cf1aed5338f79"
+      "size": 20927,
+      "sha256": "026fd79a98596d2be108b350668f4345b11020953f24369866c0aad42cd7ba0f"
+    },
+    "storage/DebuggerStorage.d.ts": {
+      "size": 517,
+      "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
+    },
+    "storage/DebuggerStorage.js": {
+      "size": 7442,
+      "sha256": "5ecce0fcfcf695df587a7b90a7a5c7efd2e64ad13c9f2d104b392f89f34f0dc4"
     },
     "storage/ProxyTraceStorage.d.ts": {
       "size": 339,

package/dist/register.js

@@ -291,26 +291,30 @@ const createTraceWatcherArgs = async (core, Env, config) => {
     globalTraceRegisterState.__zintrust_system_trace_connection_name__ = resolvedConnectionName;
     globalTraceRegisterState.__zintrust_system_trace_observe_connection_name__ =
         resolvedObservedConnectionName;
-    const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
     const observedDb = core.useDatabase?.(undefined, resolvedObservedConnectionName);
-    assertTraceConnectionResolved(core, storageDb, {
-        connectionName: resolvedConnectionName,
-        envKey: 'TRACE_DB_CONNECTION',
-    });
     assertTraceConnectionResolved(core, observedDb, {
         connectionName: resolvedObservedConnectionName,
         envKey: 'TRACE_QUERY_CONNECTION',
     });
-    await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
-    const resolvedStorage = config.proxy.enabled
-        ? ProxyTraceStorage.create({
+    let resolvedStorage;
+    if (config.proxy.enabled) {
+        resolvedStorage = ProxyTraceStorage.create({
             baseUrl: config.proxy.url ?? '',
             path: config.proxy.path,
             keyId: config.proxy.keyId ?? '',
             secret: config.proxy.secret ?? '',
             timeoutMs: config.proxy.timeoutMs,
-        })
-        : TraceStorage.resolveStorage(storageDb);
+        });
+    }
+    else {
+        const storageDb = core.useDatabase?.(undefined, resolvedConnectionName);
+        assertTraceConnectionResolved(core, storageDb, {
+            connectionName: resolvedConnectionName,
+            envKey: 'TRACE_DB_CONNECTION',
+        });
+        await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
+        resolvedStorage = TraceStorage.resolveStorage(storageDb);
+    }
     const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceServiceTag.wrapStorage(resolvedStorage, config), config), config.redaction), config), {
         connectionName: resolvedConnectionName,
         logger: core.Logger,

package/dist/storage/DebuggerStorage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { ITraceStorage } from '../types';
+export declare const TraceStorage: Readonly<{
+    resolveStorage: (db: IDatabase) => ITraceStorage;
+    reset: () => void;
+    familyHash: (input: string) => string;
+}>;
+export { type ITraceStorage } from '../types';

package/dist/storage/DebuggerStorage.js

@@ -0,0 +1,195 @@
+import { familyHash } from '../utils/familyHash.js';
+const TABLE_ENTRIES = 'zin_trace_entries';
+const TABLE_TAGS = 'zin_trace_entries_tags';
+const TABLE_MONITORING = 'zin_trace_monitoring';
+const generateUuid = () => crypto.randomUUID();
+const rowToEntry = (row, tags) => ({
+    uuid: row.uuid,
+    batchId: row.batch_id,
+    familyHash: row.family_hash ?? undefined,
+    type: row.type,
+    content: JSON.parse(row.content),
+    tags,
+    isLatest: Boolean(row.is_latest),
+    createdAt: row.created_at,
+});
+const insertTags = async (db, uuid, tags) => {
+    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) => {
+    const conditions = [];
+    const params = [];
+    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, uuids) => {
+    const tagsByUuid = new Map();
+    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));
+    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) => {
+    const writeEntry = async (entry) => {
+        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, patch) => {
+        const sets = [];
+        const params = [];
+        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, exceptUuid) => {
+        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) => {
+        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));
+        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]));
+        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) => {
+        const row = (await db.queryOne(`SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
+       FROM ${TABLE_ENTRIES}
+       WHERE uuid = ?`, [uuid]));
+        if (!row)
+            return null;
+        const tags = (await db.query(`SELECT tag FROM ${TABLE_TAGS} WHERE entry_uuid = ?`, [
+            uuid,
+        ]));
+        return rowToEntry(row, tags.map((tag) => tag.tag));
+    };
+    const getBatch = async (batchId) => {
+        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]));
+        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, keepExceptions = false) => {
+        const countResult = (await db.queryOne(`SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES}
+       WHERE created_at < ?
+       ${keepExceptions ? "AND type != 'exception'" : ''}`, [olderThanMs]));
+        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 () => {
+        await db.execute(`DELETE FROM ${TABLE_ENTRIES}`, []);
+    };
+    const getMonitoring = async () => {
+        const rows = (await db.query(`SELECT tag FROM ${TABLE_MONITORING}`, []));
+        return rows.map((row) => row.tag);
+    };
+    const addMonitoring = async (tag) => {
+        await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
+    };
+    const removeMonitoring = async (tag) => {
+        await db.execute(`DELETE FROM ${TABLE_MONITORING} WHERE tag = ?`, [tag]);
+    };
+    const stats = async () => {
+        const rows = (await db.query(`SELECT type, COUNT(*) as cnt FROM ${TABLE_ENTRIES} GROUP BY type`, []));
+        const output = {};
+        for (const row of rows) {
+            output[row.type] = row.cnt;
+        }
+        return output;
+    };
+    return {
+        writeEntry,
+        updateEntry,
+        markFamilyStale,
+        queryEntries,
+        getEntry,
+        getBatch,
+        prune,
+        clear,
+        getMonitoring,
+        addMonitoring,
+        removeMonitoring,
+        stats,
+    };
+};
+const resolveStorage = (db) => {
+    return createStorage(db);
+};
+const reset = () => {
+    return;
+};
+export const TraceStorage = Object.freeze({ resolveStorage, reset, familyHash });

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "exports": {
     ".": {
@@ -56,4 +55,4 @@
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.migrations.json && node ../../scripts/fix-dist-esm-imports.mjs dist",
     "prepublishOnly": "npm run build"
   }
-}
+}

package/src/TraceConnection.ts

@@ -1,182 +0,0 @@
-import type { IDatabase } from '@zintrust/core';
-
-type TraceErrorFactory = {
-  createConfigError?(message: string, details?: unknown): Error;
-};
-
-type TraceErrorApi = {
-  ErrorFactory?: TraceErrorFactory;
-};
-
-type TraceEnvApi = {
-  get(key: string, fallback: string): string;
-};
-
-type GlobalTraceConnectionState = {
-  __zintrust_system_trace_connection_name__?: string;
-  __zintrust_system_trace_plugin_requested__?: boolean;
-};
-
-export const TRACE_REQUIRED_TABLES = [
-  'zin_trace_entries',
-  'zin_trace_entries_tags',
-  'zin_trace_monitoring',
-] as const;
-
-const createFallbackTraceConfigError = (message: string, details?: unknown): Error => {
-  const error = new globalThis.Error(message) as Error & {
-    code?: string;
-    details?: unknown;
-    name?: string;
-    statusCode?: number;
-  };
-  error.name = 'ConfigError';
-  error.code = 'CONFIG_ERROR';
-  error.statusCode = 500;
-  error.details = details;
-  return error;
-};
-
-export const createTraceConfigError = (
-  coreApi: TraceErrorApi,
-  message: string,
-  details?: unknown
-): Error => {
-  if (coreApi.ErrorFactory?.createConfigError !== undefined) {
-    return coreApi.ErrorFactory.createConfigError(message, details);
-  }
-
-  return createFallbackTraceConfigError(message, details);
-};
-
-export const getRuntimeTraceConnectionName = (): string | undefined => {
-  const runtimeConnection = (
-    globalThis as GlobalTraceConnectionState
-  ).__zintrust_system_trace_connection_name__?.trim();
-
-  return runtimeConnection === undefined || runtimeConnection === ''
-    ? undefined
-    : runtimeConnection;
-};
-
-export const resolveDashboardTraceConnectionName = (
-  coreApi: TraceErrorApi,
-  input: {
-    explicitConnectionName?: string;
-    configuredConnectionName?: string;
-  }
-): string => {
-  const explicitConnection = input.explicitConnectionName?.trim();
-  if (explicitConnection !== undefined && explicitConnection !== '') {
-    return explicitConnection;
-  }
-
-  const runtimeConnection = getRuntimeTraceConnectionName();
-  if (runtimeConnection !== undefined) {
-    return runtimeConnection;
-  }
-
-  const configuredConnection = input.configuredConnectionName?.trim();
-  if (configuredConnection !== undefined && configuredConnection !== '') {
-    return configuredConnection;
-  }
-
-  throw createTraceConfigError(coreApi, 'Trace dashboard connection is not configured.', {
-    envKey: 'TRACE_DB_CONNECTION',
-    hint: 'Import @zintrust/trace/register before mounting the dashboard, pass connectionName explicitly, or set TRACE_DB_CONNECTION to the trace storage connection.',
-  });
-};
-
-export const resolveTraceConnectionName = (
-  env: Pick<TraceEnvApi, '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();
-};
-
-export const resolveObservedConnectionName = (
-  env: Pick<TraceEnvApi, 'get'> | undefined,
-  configuredObservedConnection: string | undefined,
-  storageConnectionName: string
-): string => {
-  if (
-    typeof configuredObservedConnection === 'string' &&
-    configuredObservedConnection.trim() !== ''
-  ) {
-    return resolveTraceConnectionName(env, configuredObservedConnection);
-  }
-
-  const defaultConnectionName = resolveTraceConnectionName(env);
-  if (storageConnectionName !== defaultConnectionName) {
-    return defaultConnectionName;
-  }
-
-  return storageConnectionName;
-};
-
-export function assertTraceConnectionResolved(
-  coreApi: TraceErrorApi,
-  db: IDatabase | undefined,
-  params: { connectionName: string; envKey: 'TRACE_DB_CONNECTION' | 'TRACE_QUERY_CONNECTION' }
-): asserts db is IDatabase {
-  if (db !== undefined) {
-    return;
-  }
-
-  const pluginRequested =
-    (globalThis as GlobalTraceConnectionState).__zintrust_system_trace_plugin_requested__ === true;
-  let hint =
-    'Configure TRACE_QUERY_CONNECTION, or ensure DB_CONNECTION resolves to an existing database connection.';
-
-  if (params.envKey === 'TRACE_DB_CONNECTION') {
-    hint = pluginRequested
-      ? 'Configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.'
-      : 'If this module is being imported from zintrust.plugins.*, switch that import to @zintrust/trace/plugin so trace registration runs after database runtime registration. Otherwise configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.';
-  }
-
-  throw createTraceConfigError(
-    coreApi,
-    `Trace connection "${params.connectionName}" could not be resolved.`,
-    {
-      connectionName: params.connectionName,
-      envKey: params.envKey,
-      hint,
-    }
-  );
-}
-
-export const assertTraceStorageReady = async (
-  coreApi: TraceErrorApi,
-  db: IDatabase,
-  connectionName: string,
-  operation = 'Trace storage connection'
-): Promise<void> => {
-  try {
-    await Promise.all(
-      TRACE_REQUIRED_TABLES.map(async (table) => {
-        await db.queryOne(`SELECT 1 AS ok FROM ${table} LIMIT 1`, []);
-      })
-    );
-  } catch (error) {
-    throw createTraceConfigError(
-      coreApi,
-      `${operation} "${connectionName}" is not ready. Create the database if needed and run \`zin migrate:trace\` before enabling TRACE_ENABLED.`,
-      {
-        connectionName,
-        error,
-        requiredTables: [...TRACE_REQUIRED_TABLES],
-      }
-    );
-  }
-};

package/src/cli-register.ts

@@ -1,63 +0,0 @@
-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
-}