@zintrust/core 0.4.33 → 0.4.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.4.33",
+  "version": "0.4.36",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {
@@ -57,10 +57,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cloudflare/containers": "^0.1.1",
-    "@zintrust/workers": "^0.4.25",
+    "@cloudflare/containers": "^0.2.0",
+    "@zintrust/workers": "^0.4.36",
     "bcryptjs": "^3.0.3",
-    "bullmq": "^5.71.0",
+    "bullmq": "^5.71.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "inquirer": "^13.3.2",

package/src/cache/drivers/RedisDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAkXtD;;GAEG;AACH,eAAO,MAAM,WAAW;kBAXL,WAAW;EAa5B,CAAC"}
+{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAmXtD;;GAEG;AACH,eAAO,MAAM,WAAW;kBAXL,WAAW;EAa5B,CAAC"}

package/src/cache/drivers/RedisDriver.js

@@ -38,7 +38,7 @@ const createIoredisClient = (params) => {
             port: Env.REDIS_PORT,
             password: Env.get('REDIS_PASSWORD', ''),
             db,
-        }, 3);
+        }, 3, { subsystem: 'cache' });
         return client !== null && typeof client.get === 'function' ? client : null;
     }
     catch (error) {

package/src/cli/OptionalCliExtensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OptionalCliExtensions.d.ts","sourceRoot":"","sources":["../../../src/cli/OptionalCliExtensions.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,8BAA8B,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE3F,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,+BAA+B,GAAG,QAAQ,CAAC;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC,CAAC;AAkRH,eAAO,MAAM,qBAAqB;oCACM,OAAO,CAAC,0BAA0B,EAAE,CAAC;sBAQnD,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC;sCAmBhE,MAAM,EAAE,YACJ,aAAa,CAAC,0BAA0B,CAAC,GAClD,0BAA0B,GAAG,SAAS;uCASN,0BAA0B,GAAG,MAAM;mCArDlC,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;EA8D/E,CAAC;AAEH,eAAO,MAAM,6BAA6B;yBA/ThB,MAAM;8BAQD,MAAM;wCAoF5B,oBAAoB,YACjB,+BAA+B,KACxC,MAAM,GAAG,IAAI;kCAhFqB,+BAA+B,KAAG,OAAO;4BAMnE,MAAM,QACT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACnB,+BAA+B,KACxC,IAAI;8CA6FE,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;qCA0BV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;uCAgCV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;gCAuBV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,0BAA0B,CAAC;gCAwCH,MAAM,EAAE,KAAG,MAAM,GAAG,SAAS;mCAU1B,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;8BAOhD,MAAM,EAAE,KAAG,OAAO;uCAvMT,oBAAoB,KAAG,MAAM,EAAE;gCAwBtC,oBAAoB,KAAG,MAAM,EAAE;EAuPhE,CAAC"}
+{"version":3,"file":"OptionalCliExtensions.d.ts","sourceRoot":"","sources":["../../../src/cli/OptionalCliExtensions.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,8BAA8B,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE3F,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,+BAA+B,GAAG,QAAQ,CAAC;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC,CAAC;AAmRH,eAAO,MAAM,qBAAqB;oCACM,OAAO,CAAC,0BAA0B,EAAE,CAAC;sBAQnD,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC;sCAmBhE,MAAM,EAAE,YACJ,aAAa,CAAC,0BAA0B,CAAC,GAClD,0BAA0B,GAAG,SAAS;uCASN,0BAA0B,GAAG,MAAM;mCArDlC,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;EA8D/E,CAAC;AAEH,eAAO,MAAM,6BAA6B;yBAhUhB,MAAM;8BAQD,MAAM;wCAqF5B,oBAAoB,YACjB,+BAA+B,KACxC,MAAM,GAAG,IAAI;kCAjFqB,+BAA+B,KAAG,OAAO;4BAMnE,MAAM,QACT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACnB,+BAA+B,KACxC,IAAI;8CA8FE,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;qCA0BV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;uCAgCV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;gCAuBV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,0BAA0B,CAAC;gCAwCH,MAAM,EAAE,KAAG,MAAM,GAAG,SAAS;mCAU1B,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;8BAOhD,MAAM,EAAE,KAAG,OAAO;uCAvMT,oBAAoB,KAAG,MAAM,EAAE;gCAwBtC,oBAAoB,KAAG,MAAM,EAAE;EAuPhE,CAAC"}

package/src/cli/OptionalCliExtensions.js

@@ -52,6 +52,7 @@ const OPTIONAL_CLI_EXTENSIONS = Object.freeze([
             'worker:start-all',
             'worker:stop',
             'worker:restart',
+            'worker:doctor',
             'worker:summary',
         ],
         installCommand: 'npm install @zintrust/workers',

package/src/cli/commands/WorkerCommands.d.ts

@@ -2,7 +2,7 @@
  * Worker Management CLI Commands
  * Command-line interface for managing workers
  */
-import type { IBaseCommand } from '../BaseCommand';
+import { type IBaseCommand } from '../BaseCommand';
 /**
  * Export worker command creators
  */
@@ -13,6 +13,7 @@ export declare const WorkerCommands: {
     createWorkerStartAllCommand: () => IBaseCommand;
     createWorkerStopCommand: () => IBaseCommand;
     createWorkerRestartCommand: () => IBaseCommand;
+    createWorkerDoctorCommand: () => IBaseCommand;
     createWorkerSummaryCommand: () => IBaseCommand;
 };
 //# sourceMappingURL=WorkerCommands.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"WorkerCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/WorkerCommands.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0lBrD;;GAEG;AACH,eAAO,MAAM,cAAc;mCAtaS,YAAY;qCA4CV,YAAY;oCAiDb,YAAY;uCAqHT,YAAY;mCAyFhB,YAAY;sCAgCT,YAAY;sCAgCZ,YAAY;CAmElD,CAAC"}
+{"version":3,"file":"WorkerCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/WorkerCommands.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAyqBvF;;GAEG;AACH,eAAO,MAAM,cAAc;mCAneS,YAAY;qCA4CV,YAAY;oCAiDb,YAAY;uCA2NT,YAAY;mCAgDhB,YAAY;sCAgCT,YAAY;qCAtEb,YAAY;sCAsGX,YAAY;CAoElD,CAAC"}

package/src/cli/commands/WorkerCommands.js

@@ -5,6 +5,7 @@
  */
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 import { BaseCommand } from '../BaseCommand.js';
+import { WorkerStartupDiagnostics, } from '../services/WorkerStartupDiagnostics.js';
 import { Env } from '../../config/env.js';
 import { Logger } from '../../config/logger.js';
 import { WorkerProjectAutoImports } from '../../runtime/WorkerProjectAutoImports.js';
@@ -100,6 +101,14 @@ const formatTable = (headers, rows) => {
     const dataRows = rows.map((row) => row.map((cell, i) => (cell || '').padEnd(columnWidths[i])).join(' | '));
     return [headerRow, separator, ...dataRows].join('\n');
 };
+const logFirstFaultSummaryOnce = (state, error, context) => {
+    const report = WorkerStartupDiagnostics.collect(error);
+    if (!state.logged) {
+        state.logged = true;
+        WorkerStartupDiagnostics.log(error, context);
+    }
+    return report;
+};
 /**
  * Worker List Command
  */
@@ -270,78 +279,117 @@ const resolveAutoStartWorkerNames = async (factory, workersModule) => {
     }
     return { names: fileNames, source: fileNames.length > 0 ? 'file' : 'none' };
 };
+const resolveEligibleWorkers = async (factory, workersModule) => {
+    const { names: workers, source } = await resolveAutoStartWorkerNames(factory, workersModule);
+    if (workers.length === 0) {
+        Logger.info('No auto-start eligible persisted or file-backed workers found.');
+        return [];
+    }
+    if (source !== 'persisted') {
+        return workers;
+    }
+    const discoveredWorkers = await pollForPersistedWorkers(factory);
+    return workers.filter((name) => discoveredWorkers.includes(name));
+};
+const startEligibleWorker = async (factory, name, diagnosticsState) => {
+    const existing = await factory.get(name);
+    if (existing !== null && existing !== undefined) {
+        const trulyRunning = await isRegisteredWorkerRunning(existing);
+        if (trulyRunning) {
+            return { name, status: 'skipped' };
+        }
+        Logger.warn(`Worker "${name}" is registered but not truly running. Restarting for crash recovery.`);
+        try {
+            await factory.restart(name);
+            return { name, status: 'started' };
+        }
+        catch (error) {
+            logFirstFaultSummaryOnce(diagnosticsState, error, `worker:start-all failed while restarting "${name}"`);
+            Logger.warn(`Failed to restart stale worker "${name}"`, error);
+            return { name, status: 'failed' };
+        }
+    }
+    try {
+        await factory.startFromPersisted(name);
+        return { name, status: 'started' };
+    }
+    catch (error) {
+        logFirstFaultSummaryOnce(diagnosticsState, error, `worker:start-all failed while starting "${name}"`);
+        Logger.warn(`Failed to start worker "${name}"`, error);
+        return { name, status: 'failed' };
+    }
+};
+const executeWorkerStartAll = async () => {
+    const diagnosticsState = { logged: false };
+    try {
+        const globalAutoStart = Env.getBool('WORKER_AUTO_START', false);
+        if (!globalAutoStart) {
+            Logger.info('Skipping auto-start because WORKER_AUTO_START is false.');
+            return;
+        }
+        const factory = await getWorkerFactory();
+        const workersModule = await loadWorkersModule();
+        const eligibleWorkers = await resolveEligibleWorkers(factory, workersModule);
+        if (eligibleWorkers.length === 0) {
+            Logger.info('No auto-start eligible workers are currently available.');
+            return;
+        }
+        const results = await Promise.all(eligibleWorkers.map(async (name) => startEligibleWorker(factory, name, diagnosticsState)));
+        const started = results.filter((result) => result.status === 'started').length;
+        const skipped = results.filter((result) => result.status === 'skipped').length;
+        const failed = results.filter((result) => result.status === 'failed').length;
+        Logger.info('Worker start-all summary', {
+            total: eligibleWorkers.length,
+            started,
+            skipped,
+            failed,
+        });
+    }
+    catch (error) {
+        logFirstFaultSummaryOnce(diagnosticsState, error, 'worker:start-all failed');
+        Logger.error('worker:start-all command failed', error);
+        process.exit(1);
+    }
+};
 /**
  * Worker Start All Command
  */
 const createWorkerStartAllCommand = () => {
-    const ext = async () => {
-        try {
-            const globalAutoStart = Env.getBool('WORKER_AUTO_START', false);
-            if (!globalAutoStart) {
-                Logger.info('Skipping auto-start because WORKER_AUTO_START is false.');
-                return;
-            }
-            const factory = await getWorkerFactory();
-            const workersModule = await loadWorkersModule();
-            const { names: workers, source } = await resolveAutoStartWorkerNames(factory, workersModule);
-            if (workers.length === 0) {
-                Logger.info('No auto-start eligible persisted or file-backed workers found.');
-                return;
-            }
-            let eligibleWorkers = workers;
-            if (source === 'persisted') {
-                const discoveredWorkers = await pollForPersistedWorkers(factory);
-                eligibleWorkers = workers.filter((name) => discoveredWorkers.includes(name));
-            }
-            if (eligibleWorkers.length === 0) {
-                Logger.info('No auto-start eligible workers are currently available.');
-                return;
+    const cmd = BaseCommand.create({
+        name: 'worker:start-all',
+        description: 'Start all persisted workers',
+        execute: executeWorkerStartAll,
+    });
+    return cmd;
+};
+const createWorkerDoctorCommand = () => {
+    const ext = (options) => {
+        const json = options['json'] === true;
+        const report = WorkerStartupDiagnostics.collect();
+        if (json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log();
+            for (const line of WorkerStartupDiagnostics.renderLines(report)) {
+                console.log(line);
             }
-            const results = await Promise.all(eligibleWorkers.map(async (name) => {
-                const existing = await factory.get(name);
-                if (existing !== null && existing !== undefined) {
-                    const trulyRunning = await isRegisteredWorkerRunning(existing);
-                    if (trulyRunning) {
-                        return { name, status: 'skipped' };
-                    }
-                    Logger.warn(`Worker "${name}" is registered but not truly running. Restarting for crash recovery.`);
-                    try {
-                        await factory.restart(name);
-                        return { name, status: 'started' };
-                    }
-                    catch (error) {
-                        Logger.warn(`Failed to restart stale worker "${name}"`, error);
-                        return { name, status: 'failed' };
-                    }
-                }
-                try {
-                    await factory.startFromPersisted(name);
-                    return { name, status: 'started' };
-                }
-                catch (error) {
-                    Logger.warn(`Failed to start worker "${name}"`, error);
-                    return { name, status: 'failed' };
-                }
-            }));
-            const started = results.filter((result) => result.status === 'started').length;
-            const skipped = results.filter((result) => result.status === 'skipped').length;
-            const failed = results.filter((result) => result.status === 'failed').length;
-            Logger.info('Worker start-all summary', {
-                total: eligibleWorkers.length,
-                started,
-                skipped,
-                failed,
-            });
+            console.log();
         }
-        catch (error) {
-            Logger.error('worker:start-all command failed', error);
+        if (WorkerStartupDiagnostics.hasBlockingIssues(report)) {
             process.exit(1);
         }
     };
     const cmd = BaseCommand.create({
-        name: 'worker:start-all',
-        description: 'Start all persisted workers',
-        execute: async () => ext(),
+        name: 'worker:doctor',
+        description: 'Print worker startup diagnostics and likely missing env keys',
+        addOptions: (command) => {
+            command.option('--json', 'Print machine-readable diagnostics');
+        },
+        execute: async (options) => {
+            await Promise.resolve();
+            ext(options);
+        },
     });
     return cmd;
 };
@@ -461,5 +509,6 @@ export const WorkerCommands = {
     createWorkerStartAllCommand,
     createWorkerStopCommand,
     createWorkerRestartCommand,
+    createWorkerDoctorCommand,
     createWorkerSummaryCommand,
 };

package/src/cli/services/WorkerStartupDiagnostics.d.ts

@@ -0,0 +1,41 @@
+type IssueSeverity = 'error' | 'warn' | 'info';
+export type WorkerStartupIssue = Readonly<{
+    severity: IssueSeverity;
+    message: string;
+    envKeys: ReadonlyArray<string>;
+}>;
+export type WorkerStartupEnvStatus = Readonly<{
+    key: string;
+    present: boolean;
+    resolvedValue: string;
+    explicitValue: string;
+}>;
+export type WorkerStartupDiagnosticsReport = Readonly<{
+    flags: Readonly<{
+        runtimeMode: string;
+        workerEnabled: boolean;
+        workerAutoStart: boolean;
+        dockerWorker: boolean;
+        queueEnabled: boolean;
+        queueDriver: string;
+        persistenceDriver: string;
+    }>;
+    issues: ReadonlyArray<WorkerStartupIssue>;
+    missingEnvKeys: ReadonlyArray<string>;
+    envStatus: ReadonlyArray<WorkerStartupEnvStatus>;
+    firstFault: Readonly<{
+        message: string;
+        code?: string;
+    }> | null;
+    logPointers: ReadonlyArray<string>;
+    nextSteps: ReadonlyArray<string>;
+}>;
+export declare const WorkerStartupDiagnostics: Readonly<{
+    collect: (error?: unknown) => WorkerStartupDiagnosticsReport;
+    renderLines: (report: WorkerStartupDiagnosticsReport) => string[];
+    log: (error?: unknown, context?: string) => WorkerStartupDiagnosticsReport;
+    hasBlockingIssues: (report: WorkerStartupDiagnosticsReport) => boolean;
+    createCliError(message: string): Error;
+}>;
+export {};
+//# sourceMappingURL=WorkerStartupDiagnostics.d.ts.map

package/src/cli/services/WorkerStartupDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerStartupDiagnostics.d.ts","sourceRoot":"","sources":["../../../../src/cli/services/WorkerStartupDiagnostics.ts"],"names":[],"mappings":"AAMA,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC;IACpD,KAAK,EAAE,QAAQ,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,OAAO,CAAC;QACvB,eAAe,EAAE,OAAO,CAAC;QACzB,YAAY,EAAE,OAAO,CAAC;QACtB,YAAY,EAAE,OAAO,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC,CAAC;IACH,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC1C,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACjD,UAAU,EAAE,QAAQ,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,GAAG,IAAI,CAAC;IACV,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClC,CAAC,CAAC;AA4bH,eAAO,MAAM,wBAAwB;sBAxFZ,OAAO,KAAG,8BAA8B;0BAwCpC,8BAA8B,KAAG,MAAM,EAAE;kBA0BjD,OAAO,uBAA+B,8BAA8B;gCAmBtD,8BAA8B,KAAG,OAAO;4BAQjD,MAAM,GAAG,KAAK;EAGtC,CAAC"}