@zintrust/trace 1.6.6 → 1.7.0

package/dist/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.4",
-  "buildDate": "2026-04-30T15:30:37.643Z",
+  "version": "1.7.0",
+  "buildDate": "2026-04-30T21:21:48.786Z",
   "buildEnvironment": {
-    "node": "v25.6.1",
-    "platform": "darwin",
-    "arch": "arm64"
+    "node": "v20.20.2",
+    "platform": "linux",
+    "arch": "x64"
   },
   "git": {
-    "commit": "f235df8b",
-    "branch": "release"
+    "commit": "d74d4702",
+    "branch": "master"
   },
   "package": {
     "engines": {
@@ -29,10 +29,6 @@
       "size": 4640,
       "sha256": "c51cc312046b6b2bbe1673f1ff9508425cc7140a1d2341907f67aa36069c09f9"
     },
-    "build-manifest.json": {
-      "size": 15912,
-      "sha256": "6732e16044ffbcb77bf9873cf30a671007b5acc4aa2f3edf5071da667d4df534"
-    },
     "cli-register.d.ts": {
       "size": 255,
       "sha256": "da8d689fe5ef32e97e755f28017e4d3cb1aa63489073a71907ea41ad5761ede9"
@@ -87,7 +83,7 @@
     },
     "index.js": {
       "size": 3421,
-      "sha256": "ee5aca20d1e6d980fa0b2c02e4832c35e8a18fff9fe63a7bf6a26ae8f734d377"
+      "sha256": "c86927e6157cc6dbc6ffd4ed39c6e00a795bc0954ffb41de67e131248e630fe7"
     },
     "ingest/TraceIngestGateway.d.ts": {
       "size": 786,
@@ -153,14 +149,6 @@
       "size": 19680,
       "sha256": "042a7585e68a8a676e25f33c9a176c6f263bccb4a63090b4d2cea52b9bcdd193"
     },
-    "storage/DebuggerStorage.d.ts": {
-      "size": 517,
-      "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
-    },
-    "storage/DebuggerStorage.js": {
-      "size": 7442,
-      "sha256": "5ecce0fcfcf695df587a7b90a7a5c7efd2e64ad13c9f2d104b392f89f34f0dc4"
-    },
     "storage/ProxyTraceStorage.d.ts": {
       "size": 339,
       "sha256": "9c724ff342dfe82da12e7cce95593f6623faa80c40f97593719b8e78e95f266d"
@@ -366,8 +354,8 @@
       "sha256": "ce9a95a670f755193fd74ce721dbfa4b30f20c879a6566ebb35229b3b2435429"
     },
     "watchers/HttpWatcher.js": {
-      "size": 6152,
-      "sha256": "b5af31b46a9a8754f6032fde78fc46e9ad7221977a0bfbbaa26e13214951ea0f"
+      "size": 6880,
+      "sha256": "a69795a885d6b350012bb3be7a93a0a1a6e71070873cd172e3bd672b67b4ac08"
     },
     "watchers/JobWatcher.d.ts": {
       "size": 441,

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.6",
+  "version": "1.7.0",
   "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/dist/storage/DebuggerStorage.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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

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