@zintrust/core 0.4.76 → 0.4.77

package/bin/zintrust-main.d.ts

@@ -4,6 +4,18 @@
  * This module contains the CLI implementation without a hashbang so that it can
  * be imported by other bin shortcuts (zin/z/zt) without parse errors.
  */
+type ProjectLocalCliTarget = {
+    binPath: string;
+    packageRoot: string;
+};
 export declare function run(): Promise<void>;
+export declare const CliLauncherInternal: Readonly<{
+    CLI_HANDOFF_ENV_KEY: "ZINTRUST_CLI_HANDOFF";
+    findProjectLocalCliTarget: (cwd: string) => ProjectLocalCliTarget | undefined;
+    getCurrentPackageRoot: () => string;
+    getRealPath: (targetPath: string) => string;
+    isWithinDirectory: (targetPath: string, possibleParentPath: string) => boolean;
+    resolveProjectLocalCliHandoff: (cwd: string, currentPackageRoot: string, env?: NodeJS.ProcessEnv) => ProjectLocalCliTarget | undefined;
+}>;
 export {};
 //# sourceMappingURL=zintrust-main.d.ts.map

package/bin/zintrust-main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zintrust-main.d.ts","sourceRoot":"","sources":["../../bin/zintrust-main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqIH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAgFzC;AAED,OAAO,EAAE,CAAC"}
+{"version":3,"file":"zintrust-main.d.ts","sourceRoot":"","sources":["../../bin/zintrust-main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAmTF,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAMzC;AAED,eAAO,MAAM,mBAAmB;;qCAjSQ,MAAM,KAAG,qBAAqB,GAAG,SAAS;iCAtBhD,MAAM;8BAIP,MAAM,KAAG,MAAM;oCAQT,MAAM,sBAAsB,MAAM,KAAG,OAAO;yCAqC5E,MAAM,sBACS,MAAM,QACrB,MAAM,CAAC,UAAU,KACrB,qBAAqB,GAAG,SAAS;EA0QlC,CAAC;AAEH,OAAO,EAAE,CAAC"}

package/bin/zintrust-main.js

@@ -5,9 +5,86 @@
  * be imported by other bin shortcuts (zin/z/zt) without parse errors.
  */
 import { Logger } from '../src/config/logger.js';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+const CLI_HANDOFF_ENV_KEY = 'ZINTRUST_CLI_HANDOFF';
+const getCurrentPackageRoot = () => {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+};
+const getRealPath = (targetPath) => {
+    try {
+        return fs.realpathSync(targetPath);
+    }
+    catch {
+        return path.resolve(targetPath);
+    }
+};
+const isWithinDirectory = (targetPath, possibleParentPath) => {
+    const normalizedTarget = getRealPath(targetPath);
+    const normalizedParent = getRealPath(possibleParentPath);
+    if (normalizedTarget === normalizedParent)
+        return true;
+    const relativePath = path.relative(normalizedParent, normalizedTarget);
+    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+};
+const findProjectLocalCliTarget = (cwd) => {
+    let currentDir = path.resolve(cwd);
+    while (true) {
+        const packageRoot = path.join(currentDir, 'node_modules', '@zintrust', 'core');
+        const packageJsonPath = path.join(packageRoot, 'package.json');
+        const binCandidates = [
+            path.join(packageRoot, 'bin', 'zin.js'),
+            path.join(packageRoot, 'bin', 'zin.mjs'),
+            path.join(packageRoot, 'bin', 'zin.cjs'),
+            path.join(packageRoot, 'bin', 'zin.ts'),
+        ];
+        if (fs.existsSync(packageJsonPath)) {
+            const binPath = binCandidates.find((candidate) => fs.existsSync(candidate));
+            if (binPath !== undefined) {
+                return { binPath, packageRoot };
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            return undefined;
+        currentDir = parentDir;
+    }
+};
+const resolveProjectLocalCliHandoff = (cwd, currentPackageRoot, env = process.env) => {
+    if (env[CLI_HANDOFF_ENV_KEY] === '1')
+        return undefined;
+    if (isWithinDirectory(cwd, currentPackageRoot))
+        return undefined;
+    const target = findProjectLocalCliTarget(cwd);
+    if (target === undefined)
+        return undefined;
+    if (getRealPath(target.packageRoot) === getRealPath(currentPackageRoot)) {
+        return undefined;
+    }
+    return target;
+};
+const handoffToProjectLocalCli = (target, rawArgs) => {
+    const result = spawnSync(process.execPath, [target.binPath, ...rawArgs], {
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            [CLI_HANDOFF_ENV_KEY]: '1',
+        },
+    });
+    if (result.error !== undefined) {
+        throw result.error;
+    }
+    process.exit(typeof result.status === 'number' ? result.status : 1);
+};
+const maybeHandoffToProjectLocalCli = (rawArgs) => {
+    const localCliTarget = resolveProjectLocalCliHandoff(process.cwd(), getCurrentPackageRoot());
+    if (localCliTarget === undefined)
+        return false;
+    handoffToProjectLocalCli(localCliTarget, rawArgs);
+    return true;
+};
 const loadPackageVersionFast = () => {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -33,6 +110,12 @@ const getArgsFromProcess = () => {
 const isVersionRequest = (args) => {
     return args.includes('-v') || args.includes('--version');
 };
+const maybePrintVersionAndExit = (args) => {
+    if (!isVersionRequest(args))
+        return false;
+    printFancyVersion(loadPackageVersionFast());
+    return true;
+};
 const printFancyVersion = (version) => {
     const framework = 'ZinTrust Framework';
     const bannerWidth = 46;
@@ -110,69 +193,81 @@ const handleCliFatal = async (error, context) => {
     }
     process.exit(1);
 };
-export async function run() {
+const runCliInternal = async () => {
+    const { rawArgs: rawArgs0, args: args0 } = getArgsFromProcess();
+    if (maybeHandoffToProjectLocalCli(rawArgs0)) {
+        return;
+    }
+    // Fast path: print version and exit without bootstrapping the CLI.
+    // This keeps `zin -v` / `zin --version` snappy and avoids any debug output.
+    if (maybePrintVersionAndExit(args0)) {
+        return;
+    }
+    const { EnvFileLoader } = await import('../src/cli/utils/EnvFileLoader.js');
+    EnvFileLoader.ensureLoaded();
+    // Auto-load install-only CLI extension packages that self-register commands.
+    let optionalCliExtensions;
+    let optionalCliStatuses = [];
     try {
-        // Fast path: print version and exit without bootstrapping the CLI.
-        // This keeps `zin -v` / `zin --version` snappy and avoids any debug output.
-        const { rawArgs: _rawArgs0, args: args0 } = getArgsFromProcess();
-        if (isVersionRequest(args0)) {
-            printFancyVersion(loadPackageVersionFast());
-            return;
-        }
-        const { EnvFileLoader } = await import('../src/cli/utils/EnvFileLoader.js');
-        EnvFileLoader.ensureLoaded();
-        // Auto-load install-only CLI extension packages that self-register commands.
-        let optionalCliExtensions;
-        let optionalCliStatuses = [];
-        try {
-            ({ OptionalCliExtensions: optionalCliExtensions } =
-                await import('../src/cli/OptionalCliExtensions.js'));
-            optionalCliStatuses = await optionalCliExtensions.loadForArgs(args0);
-        }
-        catch {
-            // best-effort; missing optional extensions must not block the CLI
+        ({ OptionalCliExtensions: optionalCliExtensions } = await import('../src/cli/OptionalCliExtensions.js'));
+        optionalCliStatuses = await optionalCliExtensions.loadForArgs(args0);
+    }
+    catch {
+        // best-effort; missing optional extensions must not block the CLI
+    }
+    const missingOptionalExtension = optionalCliExtensions?.findMissingExtensionForArgs(args0, optionalCliStatuses);
+    if (missingOptionalExtension !== undefined) {
+        const { ErrorFactory } = await import('../src/exceptions/ZintrustError.js');
+        throw ErrorFactory.createCliError(optionalCliExtensions?.getMissingExtensionMessage(missingOptionalExtension) ??
+            `Missing optional CLI package: ${missingOptionalExtension.packageName}`);
+    }
+    // Ensure project-installed adapters/drivers are registered for CLI commands.
+    // (This is driven by src/zintrust.plugins.ts generated by `zin plugin install`.)
+    try {
+        const { PluginAutoImports } = await import('../src/runtime/PluginAutoImports.js');
+        const runtimeImportMode = process.env['DOCKER_WORKER'] === 'true' ? 'worker' : 'base';
+        const officialImports = await PluginAutoImports.tryImportRuntimeAutoImports(runtimeImportMode);
+        if (!officialImports.ok) {
+            logPluginAutoImportFailure(args0, 'Official', officialImports.errorMessage);
         }
-        const missingOptionalExtension = optionalCliExtensions?.findMissingExtensionForArgs(args0, optionalCliStatuses);
-        if (missingOptionalExtension !== undefined) {
-            const { ErrorFactory } = await import('../src/exceptions/ZintrustError.js');
-            throw ErrorFactory.createCliError(optionalCliExtensions?.getMissingExtensionMessage(missingOptionalExtension) ??
-                `Missing optional CLI package: ${missingOptionalExtension.packageName}`);
+        const projectImports = await PluginAutoImports.tryImportProjectAutoImports();
+        if (!projectImports.ok && projectImports.reason !== 'not-found') {
+            logPluginAutoImportFailure(args0, 'Project', projectImports.errorMessage);
         }
-        // Ensure project-installed adapters/drivers are registered for CLI commands.
-        // (This is driven by src/zintrust.plugins.ts generated by `zin plugin install`.)
+    }
+    catch {
+        // best-effort; CLI should still run even if plugins file is missing
+    }
+    const { CLI } = await import('../src/cli/CLI.js');
+    const cli = CLI.create();
+    // When executing via tsx (e.g. `npx tsx bin/zin.ts ...`), the script path can
+    // appear as the first element of `process.argv.slice(2)`. Commander expects
+    // args to start at the command name, so we strip a leading script path if present.
+    const { rawArgs, args } = getArgsFromProcess();
+    if (shouldDebugArgs(rawArgs)) {
         try {
-            const { PluginAutoImports } = await import('../src/runtime/PluginAutoImports.js');
-            const runtimeImportMode = process.env['DOCKER_WORKER'] === 'true' ? 'worker' : 'base';
-            const officialImports = await PluginAutoImports.tryImportRuntimeAutoImports(runtimeImportMode);
-            if (!officialImports.ok) {
-                logPluginAutoImportFailure(args0, 'Official', officialImports.errorMessage);
-            }
-            const projectImports = await PluginAutoImports.tryImportProjectAutoImports();
-            if (!projectImports.ok && projectImports.reason !== 'not-found') {
-                logPluginAutoImportFailure(args0, 'Project', projectImports.errorMessage);
-            }
+            process.stderr.write(`[zintrust-cli] process.argv=${JSON.stringify(process.argv)}\n`);
+            process.stderr.write(`[zintrust-cli] rawArgs=${JSON.stringify(rawArgs)}\n`);
         }
         catch {
-            // best-effort; CLI should still run even if plugins file is missing
-        }
-        const { CLI } = await import('../src/cli/CLI.js');
-        const cli = CLI.create();
-        // When executing via tsx (e.g. `npx tsx bin/zin.ts ...`), the script path can
-        // appear as the first element of `process.argv.slice(2)`. Commander expects
-        // args to start at the command name, so we strip a leading script path if present.
-        const { rawArgs, args } = getArgsFromProcess();
-        if (shouldDebugArgs(rawArgs)) {
-            try {
-                process.stderr.write(`[zintrust-cli] process.argv=${JSON.stringify(process.argv)}\n`);
-                process.stderr.write(`[zintrust-cli] rawArgs=${JSON.stringify(rawArgs)}\n`);
-            }
-            catch {
-                // ignore
-            }
+            // ignore
         }
-        await cli.run(normalizeProxyTargetArgs(args));
+    }
+    await cli.run(normalizeProxyTargetArgs(args));
+};
+export async function run() {
+    try {
+        await runCliInternal();
     }
     catch (error) {
         await handleCliFatal(error, 'CLI execution failed');
     }
 }
+export const CliLauncherInternal = Object.freeze({
+    CLI_HANDOFF_ENV_KEY,
+    findProjectLocalCliTarget,
+    getCurrentPackageRoot,
+    getRealPath,
+    isWithinDirectory,
+    resolveProjectLocalCliHandoff,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.4.76",
+  "version": "0.4.77",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/boot/registry/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/runtime.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAuO9C,eAAO,MAAM,8BAA8B,GAAI,iBAAiB,gBAAgB,KAAG,IA6BlF,CAAC;AAwRF,eAAO,MAAM,eAAe,GAAI,QAAQ;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,gBAAgB,CAAC;IAClC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,KAAG;IAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CA0F7D,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/runtime.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AA2O9C,eAAO,MAAM,8BAA8B,GAAI,iBAAiB,gBAAgB,KAAG,IA6BlF,CAAC;AAqUF,eAAO,MAAM,eAAe,GAAI,QAAQ;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,gBAAgB,CAAC;IAClC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,KAAG;IAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CA0F7D,CAAC"}

package/src/boot/registry/runtime.js

@@ -384,11 +384,27 @@ const isTraceEnabled = () => {
     const raw = readEnvString('TRACE_ENABLED').trim().toLowerCase();
     return raw === '1' || raw === 'true';
 };
+const isTraceDashboardAutoMountEnabled = () => {
+    const raw = readEnvString('TRACE_AUTO_MOUNT').trim().toLowerCase();
+    return raw === '1' || raw === 'true';
+};
+const resolveTraceDashboardBasePath = () => {
+    const raw = readEnvString('TRACE_BASE_PATH').trim();
+    if (raw === '')
+        return '/trace';
+    return raw.startsWith('/') ? raw : `/${raw}`;
+};
+const resolveTraceDashboardMiddleware = () => {
+    return readEnvString('TRACE_MIDDLEWARE')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(isNonEmptyString);
+};
 const isSystemTracePluginRequested = () => {
     const globalTracePluginState = globalThis;
     return globalTracePluginState.__zintrust_system_trace_plugin_requested__ === true;
 };
-const initializeSystemTrace = async () => {
+const initializeSystemTrace = async (router) => {
     if (!isSystemTracePluginRequested()) {
         Logger.debug('System Trace plugin is not enabled in zintrust.plugins.*. Skipping init.');
         return;
@@ -397,13 +413,31 @@ const initializeSystemTrace = async () => {
         return;
     const traceModule = (await tryImportOptional('@runtime/plugins/trace-runtime')) ??
         (await loadLocalSystemTraceModule());
-    if (traceModule === undefined || traceModule.isAvailable?.() === false) {
+    if (traceModule === undefined) {
         Logger.debug('System Trace is enabled but the optional package is unavailable.');
         return;
     }
     try {
         await traceModule.ensureSystemTraceRegistered();
-        Logger.info('System Trace runtime activated. Register dashboard routes manually if needed.');
+        if (traceModule.isAvailable?.() === false) {
+            Logger.debug('System Trace is enabled but the optional package is unavailable.');
+            return;
+        }
+        if (!isTraceDashboardAutoMountEnabled()) {
+            Logger.info('System Trace runtime activated. Set TRACE_AUTO_MOUNT=true or register dashboard routes manually if needed.');
+            return;
+        }
+        if (typeof traceModule.registerTraceDashboard !== 'function') {
+            Logger.warn('System Trace auto-mount requested but the optional package does not expose registerTraceDashboard.');
+            return;
+        }
+        const basePath = resolveTraceDashboardBasePath();
+        const middleware = resolveTraceDashboardMiddleware();
+        traceModule.registerTraceDashboard(router, {
+            basePath,
+            ...(middleware.length > 0 ? { middleware } : {}),
+        });
+        Logger.info(`System Trace dashboard auto-mounted at ${basePath}.`);
     }
     catch (error) {
         Logger.warn('Failed to initialize System Trace runtime', error);
@@ -474,7 +508,7 @@ export const createLifecycle = (params) => {
         await initializeArtifactDirectories(params.resolvedBasePath);
         await registerMasterRoutes(params.resolvedBasePath, params.router);
         initializeSockets(params.router);
-        await initializeSystemTrace();
+        await initializeSystemTrace(params.router);
         if (Cloudflare.getWorkersEnv() === null && appConfig.dockerWorker === false) {
             await initializeWorkers(params.router);
             await initializeQueueMonitor(params.router);

package/src/cli/commands/TraceCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TraceCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/TraceCommands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsBrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuoBzC,eAAO,MAAM,aAAa;mCACK,YAAY;mCAQZ,YAAY;oCAaX,YAAY;qCAgBX,YAAY;;cA7CzB,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;EAmEnD,CAAC"}
+{"version":3,"file":"TraceCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/TraceCommands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsBrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgqBzC,eAAO,MAAM,aAAa;mCACK,YAAY;mCAQZ,YAAY;oCAQX,YAAY;qCAQX,YAAY;;cAhCzB,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;;cAAjC,MAAM;oBAAc,MAAM,OAAO;;EAmDnD,CAAC"}

package/src/cli/commands/TraceCommands.js

@@ -16,20 +16,40 @@ import { Database } from '../../orm/Database.js';
 import { DatabaseAdapterRegistry } from '../../orm/DatabaseAdapterRegistry.js';
 const loadTraceModule = async () => {
     try {
-        return (await import('../../../packages/trace/src/index.js'));
+        return (await import('@zintrust/trace'));
     }
     catch (error) {
         Logger.error('Failed to load optional package "@zintrust/trace"', error);
         throw ErrorFactory.createCliError('Package "@zintrust/trace" is not installed. Add it to your project first.');
     }
 };
-const addPruneOptions = (command) => {
+const addD1DatabaseOptions = (command) => {
     command
-        .option('--hours <number>', 'Remove entries older than N hours (default: from config)', '')
         .option('--local', 'D1 only: run against local D1 database')
         .option('--remote', 'D1 only: run against remote D1 database')
-        .option('--database <name>', 'D1 only: Wrangler D1 database binding name')
+        .option('--database <name>', 'D1 only: Wrangler D1 database binding name');
+};
+const createTraceCommand = (config) => {
+    const command = BaseCommand.create({
+        name: config.name,
+        description: config.description,
+        addOptions: config.addOptions,
+        execute: async (options) => config.execute(options, command),
+    });
+    return command;
+};
+const resolveNamedTraceConnection = (name) => {
+    const connections = databaseConfig.connections;
+    return {
+        name,
+        config: connections[name] ?? databaseConfig.getConnection(),
+    };
+};
+const addPruneOptions = (command) => {
+    command
+        .option('--hours <number>', 'Remove entries older than N hours (default: from config)', '')
         .option('--keep-exceptions', 'Keep exception entries regardless of age', false);
+    addD1DatabaseOptions(command);
 };
 const addMigrateOptions = (command) => {
     command
@@ -41,10 +61,8 @@ const addMigrateOptions = (command) => {
         .option('--force', 'Skip production confirmation (allow unsafe operations in production)')
         .option('--all', 'Run migrations for all configured database connections')
         .option('--connection <name>', 'Use a specific database connection for trace migrations')
-        .option('--local', 'D1 only: run against local D1 database')
-        .option('--remote', 'D1 only: run against remote D1 database')
-        .option('--database <name>', 'D1 only: Wrangler D1 database binding name')
         .option('--no-interactive', 'Disable interactive prompts (useful for CI/CD)');
+    addD1DatabaseOptions(command);
 };
 const resolveDashboardBasePath = () => {
     const raw = readEnvString('TRACE_BASE_PATH').trim();
@@ -456,20 +474,10 @@ const executeMigrateTrace = async (options, cmd) => {
         }
     }
     else if (isNonEmptyString(options['connection'])) {
-        const selected = String(options['connection']).trim();
-        const connections = databaseConfig.connections;
-        targets.push({
-            name: selected,
-            config: connections[selected] ?? databaseConfig.getConnection(),
-        });
+        targets.push(resolveNamedTraceConnection(String(options['connection']).trim()));
     }
     else {
-        const selected = readEnvString('TRACE_DB_CONNECTION').trim() || 'default';
-        const connections = databaseConfig.connections;
-        targets.push({
-            name: selected,
-            config: connections[selected] ?? databaseConfig.getConnection(),
-        });
+        targets.push(resolveNamedTraceConnection(readEnvString('TRACE_DB_CONNECTION').trim() || 'default'));
     }
     let sequence = Promise.resolve();
     for (const { name, config } of targets) {
@@ -489,46 +497,30 @@ const createProvider = (name, getCommand) => {
     });
 };
 export const TraceCommands = Object.freeze({
-    createTracePruneCommand: () => BaseCommand.create({
+    createTracePruneCommand: () => createTraceCommand({
         name: 'trace:prune',
         description: 'Prune old entries from the trace storage',
         addOptions: addPruneOptions,
-        execute: executePrune,
+        execute: async (options) => executePrune(options),
     }),
-    createTraceClearCommand: () => BaseCommand.create({
+    createTraceClearCommand: () => createTraceCommand({
         name: 'trace:clear',
         description: 'Clear all entries from the trace storage',
-        addOptions: (command) => {
-            command
-                .option('--local', 'D1 only: run against local D1 database')
-                .option('--remote', 'D1 only: run against remote D1 database')
-                .option('--database <name>', 'D1 only: Wrangler D1 database binding name');
-        },
+        addOptions: addD1DatabaseOptions,
         execute: async (options) => executeClear(options),
     }),
-    createTraceStatusCommand: () => {
-        const cmd = BaseCommand.create({
-            name: 'trace:status',
-            description: 'Show trace storage stats and dashboard location',
-            addOptions: (command) => {
-                command
-                    .option('--local', 'D1 only: run against local D1 database')
-                    .option('--remote', 'D1 only: run against remote D1 database')
-                    .option('--database <name>', 'D1 only: Wrangler D1 database binding name');
-            },
-            execute: async (options) => executeStatus(options, cmd),
-        });
-        return cmd;
-    },
-    createTraceMigrateCommand: () => {
-        const cmd = BaseCommand.create({
-            name: 'migrate:trace',
-            description: 'Run trace package migrations',
-            addOptions: addMigrateOptions,
-            execute: async (options) => executeMigrateTrace(options, cmd),
-        });
-        return cmd;
-    },
+    createTraceStatusCommand: () => createTraceCommand({
+        name: 'trace:status',
+        description: 'Show trace storage stats and dashboard location',
+        addOptions: addD1DatabaseOptions,
+        execute: executeStatus,
+    }),
+    createTraceMigrateCommand: () => createTraceCommand({
+        name: 'migrate:trace',
+        description: 'Run trace package migrations',
+        addOptions: addMigrateOptions,
+        execute: executeMigrateTrace,
+    }),
     createTracePruneProvider: () => createProvider('trace:prune', TraceCommands.createTracePruneCommand),
     createTraceClearProvider: () => createProvider('trace:clear', TraceCommands.createTraceClearCommand),
     createTraceStatusProvider: () => createProvider('trace:status', TraceCommands.createTraceStatusCommand),

package/src/config/logging/KvLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KvLogger.d.ts","sourceRoot":"","sources":["../../../../src/config/logging/KvLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA2IF,eAAO,MAAM,QAAQ;mBACE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;EAkB/C,CAAC;AAEH,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"KvLogger.d.ts","sourceRoot":"","sources":["../../../../src/config/logging/KvLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAiKF,eAAO,MAAM,QAAQ;mBACE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;EAa/C,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/config/logging/KvLogger.js

@@ -46,6 +46,7 @@ const buildKey = (timestampIso) => {
 let buffer = [];
 let flushTimer;
 let flushPromise;
+let resolveScheduledFlush;
 const scheduleFlush = async () => {
     if (flushPromise !== undefined)
         return flushPromise;
@@ -57,6 +58,7 @@ const scheduleFlush = async () => {
                 await flushNow();
             }
             finally {
+                resolveScheduledFlush = undefined;
                 resolve(undefined);
             }
         };
@@ -65,6 +67,7 @@ const scheduleFlush = async () => {
             void run();
             return;
         }
+        resolveScheduledFlush = resolve;
         flushTimer = globalThis.setTimeout(() => {
             flushTimer = undefined;
             void run();
@@ -122,6 +125,20 @@ const flushSoon = async () => {
     });
     return flushPromise;
 };
+const flushImmediately = async () => {
+    const pendingResolve = resolveScheduledFlush;
+    if (flushTimer !== undefined) {
+        globalThis.clearTimeout(flushTimer);
+        flushTimer = undefined;
+        resolveScheduledFlush = undefined;
+        flushPromise = undefined;
+    }
+    const immediatePromise = flushSoon();
+    if (pendingResolve !== undefined) {
+        void immediatePromise.finally(() => pendingResolve());
+    }
+    return immediatePromise;
+};
 export const KvLogger = Object.freeze({
     async enqueue(event) {
         if (!isEnabled())
@@ -130,12 +147,7 @@ export const KvLogger = Object.freeze({
         // Basic size guard: flush if it gets too large
         const maxBatch = 100;
         if (buffer.length >= maxBatch) {
-            // Cancel scheduled flush and flush immediately
-            if (flushTimer !== undefined) {
-                globalThis.clearTimeout(flushTimer);
-                flushTimer = undefined;
-            }
-            return flushSoon();
+            return flushImmediately();
         }
         return scheduleFlush();
     },

package/src/functions/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../../src/functions/cloudflare.ts"],"names":[],"mappings":";mBAgPuB,OAAO,QAAQ,OAAO,QAAQ,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;;AADhF,wBAoDE;AAGF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO;IAKlC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;CAkBjD"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../../src/functions/cloudflare.ts"],"names":[],"mappings":";mBAyPuB,OAAO,QAAQ,OAAO,QAAQ,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;;AADhF,wBAoDE;AAGF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO;IAKlC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;CAkBjD"}

package/src/functions/cloudflare.js

@@ -25,6 +25,10 @@ const startupConfigModules = Object.freeze([
         file: StartupConfigFile.Mail,
         serviceModuleId: '@service-runtime-config/' + 'mail.ts',
     },
+    {
+        file: StartupConfigFile.Trace,
+        serviceModuleId: '@service-runtime-config/' + 'trace.ts',
+    },
     {
         file: StartupConfigFile.Middleware,
         serviceModuleId: '@service-runtime-config/' + 'middleware.ts',
@@ -58,6 +62,9 @@ const importRootDatabaseModule = async () => {
 const importRootMailModule = async () => {
     return (await import('@runtime-config/' + 'mail.ts').catch(() => ({})));
 };
+const importRootTraceModule = async () => {
+    return (await import('@runtime-config/' + 'trace.ts').catch(() => ({})));
+};
 const importRootMiddlewareModule = async () => {
     return (await import('@runtime-config/' + 'middleware.ts').catch(() => ({})));
 };
@@ -78,6 +85,7 @@ const rootStartupImporters = Object.freeze({
     [StartupConfigFile.Cache]: importRootCacheModule,
     [StartupConfigFile.Database]: importRootDatabaseModule,
     [StartupConfigFile.Mail]: importRootMailModule,
+    [StartupConfigFile.Trace]: importRootTraceModule,
     [StartupConfigFile.Middleware]: importRootMiddlewareModule,
     [StartupConfigFile.Notification]: importRootNotificationModule,
     [StartupConfigFile.Queue]: importRootQueueModule,

package/src/http/RequestContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../../src/http/RequestContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAsGD,eAAO,MAAM,cAAc;QACf,CAAC,WAAW,eAAe,YAAY,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAKpD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;YAK7C,eAAe,GAAG,SAAS;gBAIvB,QAAQ,GAAG,eAAe;gBAmC1B,QAAQ,WAAW,eAAe,GAAG,IAAI;aAS5C,QAAQ,GAAG,eAAe,GAAG,SAAS;oBAM/B,eAAe,UAAU,MAAM,GAAG,eAAe;mBASlD,QAAQ,UAAU,MAAM,GAAG,SAAS,GAAG,IAAI;qBAIzC,QAAQ,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI;oBAI9C,QAAQ,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI;EAG5D,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../../src/http/RequestContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAqGD,eAAO,MAAM,cAAc;QACf,CAAC,WAAW,eAAe,YAAY,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAKpD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;YAK7C,eAAe,GAAG,SAAS;gBAIvB,QAAQ,GAAG,eAAe;gBAoC1B,QAAQ,WAAW,eAAe,GAAG,IAAI;aAS5C,QAAQ,GAAG,eAAe,GAAG,SAAS;oBAM/B,eAAe,UAAU,MAAM,GAAG,eAAe;mBASlD,QAAQ,UAAU,MAAM,GAAG,SAAS,GAAG,IAAI;qBAIzC,QAAQ,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI;oBAI9C,QAAQ,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI;EAG5D,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/http/RequestContext.js

@@ -77,11 +77,9 @@ const setContextField = (req, field, value) => {
         ctx[field] = value;
     }
 };
-const STORAGE_PROMISE = (async () => {
-    const storage = await resolveStorage();
-    syncStorage = storage;
-    return storage;
-})();
+const resolvedStorage = await resolveStorage();
+syncStorage = resolvedStorage;
+const STORAGE_PROMISE = Promise.resolve(resolvedStorage);
 export const RequestContext = Object.freeze({
     async run(context, callback) {
         const storage = await STORAGE_PROMISE;
@@ -101,7 +99,8 @@ export const RequestContext = Object.freeze({
         const traceId = extractTraceIdFromTraceparent(getHeaderString(req, 'traceparent')) ??
             getHeaderString(req, 'x-trace-id') ??
             getTraceIdFromMicroserviceTraceContext(req) ??
-            getOptionalContextString(req, 'traceId');
+            getOptionalContextString(req, 'traceId') ??
+            requestId;
         const userId = getOptionalContextString(req, 'userId');
         const tenantId = getOptionalContextString(req, 'tenantId');
         const ctx = {

package/src/index.d.ts

@@ -99,6 +99,7 @@ export { Xss } from './security/Xss';
 export { XssProtection } from './security/XssProtection';
 export { ErrorFactory } from './exceptions/ZintrustError';
 export { detectCloudflareWorkers, detectRuntimePlatform, RUNTIME_PLATFORM, RuntimeServices, type RuntimeCrypto, type RuntimeEnvReader, type RuntimeFs, type RuntimePlatform, type RuntimeServices as RuntimeServicesType, type RuntimeTimers, } from './runtime/RuntimeServices';
+export { StartupConfigFile, StartupConfigFileRegistry } from './runtime/StartupConfigFileRegistry';
 export { SystemTraceBridge } from './trace/SystemTraceBridge';
 export { EventDispatcher } from './events/EventDispatcher';
 export type { EventListener, EventMap, IEventDispatcher } from './events/EventDispatcher';