@zintrust/core 0.1.41 → 0.1.42

package/src/cli/commands/MigrateCommand.js

@@ -8,6 +8,7 @@ import { WranglerConfig } from '../d1/WranglerConfig.js';
 import { WranglerD1 } from '../d1/WranglerD1.js';
 import { PromptHelper } from '../PromptHelper.js';
 import { confirmProductionRun, mapConnectionToOrmConfig, parseRollbackSteps, } from '../utils/DatabaseCliUtils.js';
+import { EnvFileLoader } from '../utils/EnvFileLoader.js';
 import { readEnvString } from '../../common/ExternalServiceUtils.js';
 import { databaseConfig } from '../../config/database.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
@@ -52,7 +53,7 @@ const getServiceArgs = (options) => {
     return { service: serviceArg, includeGlobal };
 };
 const isDestructiveAction = (options) => options['fresh'] === true || options['reset'] === true || options['rollback'] === true;
-const isD1Driver = (driver) => driver === 'd1' || driver === 'd1-remote';
+const isWranglerD1Driver = (driver) => driver === 'd1';
 const describeTargetDatabase = (conn) => {
     switch (conn.driver) {
         case 'sqlite':
@@ -189,33 +190,47 @@ const runD1Actions = async (params) => {
         cmd.info(output);
     cmd.success('D1 migrations completed successfully');
 };
-const processConnection = async (conn, options, cmd, interactive) => {
-    // Avoid confusion: `--database` is a D1-only option (Wrangler binding name), not DB_DATABASE.
-    if (isD1Driver(conn.driver)) {
+const logOptionsForConn = (cmd, conn, options) => {
+    if (isWranglerD1Driver(conn.driver)) {
         cmd.debug(`Migrate command executed with options: ${JSON.stringify(options)}`);
+        return;
     }
-    else {
-        const optionsForLog = { ...options };
-        delete optionsForLog['database'];
-        delete optionsForLog['local'];
-        delete optionsForLog['remote'];
-        cmd.debug(`Migrate command executed with options: ${JSON.stringify(optionsForLog)}`);
+    const optionsForLog = { ...options };
+    delete optionsForLog['database'];
+    delete optionsForLog['local'];
+    delete optionsForLog['remote'];
+    cmd.debug(`Migrate command executed with options: ${JSON.stringify(optionsForLog)}`);
+};
+const warnIfAdapterMissing = (cmd, conn) => {
+    if (conn.driver === 'mysql' && DatabaseAdapterRegistry.get('mysql') === undefined) {
+        cmd.warn('MySQL adapter is not installed/registered; migrations may not hit a real MySQL DB.');
+        cmd.warn('Install via `zin plugin install adapter:mysql` (or `zin add db:mysql`).');
+        cmd.debug('[debug] Expected a side-effect import in src/zintrust.plugins.ts like: import "@zintrust/db-mysql/register";');
     }
-    const { globalDir, extension, separateTracking } = getMigrationDirs();
-    const { service, includeGlobal } = getServiceArgs(options);
-    if (isD1Driver(conn.driver)) {
-        await runD1Actions({
-            options,
-            cmd,
-            projectRoot: process.cwd(),
-            globalDir,
-            extension,
-            separateTracking,
-            service,
-            includeGlobal,
-        });
-        return;
+    if (conn.driver === 'postgresql' && DatabaseAdapterRegistry.get('postgresql') === undefined) {
+        cmd.warn('PostgreSQL adapter is not installed/registered; migrations may not hit a real PostgreSQL DB.');
+        cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
     }
+};
+const withD1RemoteSqlMode = async (fn) => {
+    if (typeof process === 'undefined' || process.env === undefined)
+        return fn();
+    const prev = process.env['D1_REMOTE_MODE'];
+    process.env['D1_REMOTE_MODE'] = 'sql';
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined) {
+            delete process.env['D1_REMOTE_MODE'];
+        }
+        else {
+            process.env['D1_REMOTE_MODE'] = prev;
+        }
+    }
+};
+const runOrmMigrationsForConn = async (params) => {
+    const { conn, options, cmd, interactive, globalDir, extension, separateTracking, service, includeGlobal, } = params;
     const ormConfig = mapConnectionToOrmConfig(conn);
     const destructive = isDestructiveAction(options);
     const force = options['force'] === true;
@@ -231,18 +246,7 @@ const processConnection = async (conn, options, cmd, interactive) => {
     cmd.info(`[i] Target database: ${describeTargetDatabase(conn)}`);
     cmd.info('[i] Migration tracking table: migrations');
     cmd.debug(`[debug] Registered database adapters: ${DatabaseAdapterRegistry.list().join(', ')}`);
-    // Warn only when the adapter truly isn't registered.
-    // Adapters are registered via side-effect imports in src/zintrust.plugins.ts
-    // (generated by `zin plugin install`) and are loaded at CLI startup.
-    if (conn.driver === 'mysql' && DatabaseAdapterRegistry.get('mysql') === undefined) {
-        cmd.warn('MySQL adapter is not installed/registered; migrations may not hit a real MySQL DB.');
-        cmd.warn('Install via `zin plugin install adapter:mysql` (or `zin add db:mysql`).');
-        cmd.debug('[debug] Expected a side-effect import in src/zintrust.plugins.ts like: import "@zintrust/db-mysql/register";');
-    }
-    if (conn.driver === 'postgresql' && DatabaseAdapterRegistry.get('postgresql') === undefined) {
-        cmd.warn('PostgreSQL adapter is not installed/registered; migrations may not hit a real PostgreSQL DB.');
-        cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
-    }
+    warnIfAdapterMissing(cmd, conn);
     const db = Database.create(ormConfig);
     await db.connect();
     try {
@@ -261,7 +265,45 @@ const processConnection = async (conn, options, cmd, interactive) => {
         await db.disconnect();
     }
 };
+const processConnection = async (conn, options, cmd, interactive) => {
+    // Avoid confusion: `--database` is a D1-only option (Wrangler binding name), not DB_DATABASE.
+    logOptionsForConn(cmd, conn, options);
+    const { globalDir, extension, separateTracking } = getMigrationDirs();
+    const { service, includeGlobal } = getServiceArgs(options);
+    if (isWranglerD1Driver(conn.driver)) {
+        await runD1Actions({
+            options,
+            cmd,
+            projectRoot: process.cwd(),
+            globalDir,
+            extension,
+            separateTracking,
+            service,
+            includeGlobal,
+        });
+        return;
+    }
+    const run = async () => runOrmMigrationsForConn({
+        conn,
+        options,
+        cmd,
+        interactive,
+        globalDir,
+        extension,
+        separateTracking,
+        service,
+        includeGlobal,
+    });
+    if (conn.driver === 'd1-remote') {
+        cmd.info('[i] d1-remote migrations: using SQL mode automatically for this CLI run');
+        await withD1RemoteSqlMode(run);
+        return;
+    }
+    await run();
+};
 const executeMigrate = async (options, cmd) => {
+    // Ensure .env overlays are loaded for CLI runs (needed for d1-remote signing fallbacks).
+    EnvFileLoader.ensureLoaded();
     const interactive = getInteractive(options);
     const targets = [];
     if (options['all'] === true) {

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

@@ -1 +1 @@
-{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAqKrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}
+{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiNrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}

package/src/cli/commands/MigrateWorkerCommand.js

@@ -9,6 +9,19 @@ import { Migrator } from '../../migrations/Migrator.js';
 import * as path from '../../node-singletons/path.js';
 import { Database } from '../../orm/Database.js';
 import { DatabaseAdapterRegistry } from '../../orm/DatabaseAdapterRegistry.js';
+const isBuiltInDriver = (driver) => driver === 'sqlite' ||
+    driver === 'mysql' ||
+    driver === 'postgresql' ||
+    driver === 'sqlserver' ||
+    driver === 'd1' ||
+    driver === 'd1-remote';
+const getWorkerPersistenceConnectionName = () => {
+    if (typeof process === 'undefined')
+        return 'default';
+    const raw = process.env?.['WORKER_PERSISTENCE_DB_CONNECTION'];
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    return value.length > 0 ? value : 'default';
+};
 const addOptions = (command) => {
     command
         .option('--status', 'Display migration status (applied, pending, failed)')
@@ -80,10 +93,16 @@ const runForConnection = async (conn, options, cmd, interactive) => {
     });
     if (!proceed)
         return;
-    if (!DatabaseAdapterRegistry.has(conn.driver)) {
+    if (!isBuiltInDriver(conn.driver) && !DatabaseAdapterRegistry.has(conn.driver)) {
         cmd.warn(`Missing adapter for driver: ${conn.driver}`);
         cmd.warn(`Install via 'zin plugin install adapter:${conn.driver}' (or 'zin add db:${conn.driver}').`);
     }
+    const previousD1RemoteMode = typeof process === 'undefined' ? undefined : process.env['D1_REMOTE_MODE'];
+    if (conn.driver === 'd1-remote' && typeof process !== 'undefined') {
+        // Important: set BEFORE Database.create() so D1RemoteAdapter is constructed in SQL mode.
+        // Registry mode uses /zin/d1/statement, which is not appropriate for migrations.
+        process.env['D1_REMOTE_MODE'] = 'sql';
+    }
     const ormConfig = mapConnectionToOrmConfig(conn);
     const db = Database.create(ormConfig);
     await db.connect();
@@ -98,6 +117,14 @@ const runForConnection = async (conn, options, cmd, interactive) => {
         await runActions(migrator, options, cmd, conn.driver);
     }
     finally {
+        if (conn.driver === 'd1-remote' && typeof process !== 'undefined') {
+            if (previousD1RemoteMode === undefined) {
+                delete process.env['D1_REMOTE_MODE'];
+            }
+            else {
+                process.env['D1_REMOTE_MODE'] = previousD1RemoteMode;
+            }
+        }
         await db.disconnect();
     }
 };
@@ -110,7 +137,14 @@ const executeMigrateWorker = async (options, cmd) => {
         }
     }
     else {
-        targets.push({ name: 'default', config: databaseConfig.getConnection() });
+        const selected = getWorkerPersistenceConnectionName();
+        const hasSelected = selected.length > 0;
+        const connections = databaseConfig.connections;
+        const configured = hasSelected ? connections[selected] : undefined;
+        targets.push({
+            name: hasSelected ? selected : 'default',
+            config: configured ?? databaseConfig.getConnection(),
+        });
     }
     let sequence = Promise.resolve();
     for (const { name, config } of targets) {

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

@@ -0,0 +1,6 @@
+import { type IBaseCommand } from '../BaseCommand';
+export declare const PutCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default PutCommand;
+//# sourceMappingURL=PutCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PutCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/PutCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAmNvF,eAAO,MAAM,UAAU;cACX,YAAY;EAWtB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/cli/commands/PutCommand.js

@@ -0,0 +1,173 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { resolveNpmPath } from '../../common/index.js';
+import { appConfig } from '../../config/app.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { execFileSync } from '../../node-singletons/child-process.js';
+import { existsSync, readFileSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import { EnvFile } from '../../toolkit/Secrets/EnvFile.js';
+const toStringArray = (value) => {
+    if (typeof value === 'string')
+        return [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string');
+};
+const uniq = (items) => {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const normalized = item.trim();
+        if (normalized === '' || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+};
+const readZintrustConfig = (cwd) => {
+    const filePath = path.join(cwd, '.zintrust.json');
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch (error) {
+        throw ErrorFactory.createCliError('Failed to parse .zintrust.json', error);
+    }
+};
+const getConfigArray = (config, key) => {
+    const raw = config[key];
+    if (!Array.isArray(raw))
+        return [];
+    return uniq(raw.filter((item) => typeof item === 'string'));
+};
+const resolveConfigGroups = (options) => {
+    return uniq(toStringArray(options.var));
+};
+const resolveWranglerEnvs = (options) => {
+    const requested = uniq(toStringArray(options.wg));
+    if (requested.length === 0)
+        return ['worker'];
+    return requested;
+};
+const parseEnvPath = (options) => {
+    const direct = options['env_path'];
+    if (typeof direct === 'string' && direct.trim() !== '')
+        return direct;
+    return '.env';
+};
+const resolveValue = (key, envMap) => {
+    const fromFile = envMap[key];
+    const fromProcess = process.env[key];
+    return fromFile ?? fromProcess ?? '';
+};
+const getPutTimeoutMs = () => {
+    const raw = process.env['ZT_PUT_TIMEOUT_MS'];
+    if (typeof raw !== 'string')
+        return 120000;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return 120000;
+    return parsed;
+};
+const putSecret = (wranglerEnv, key, value) => {
+    const npmPath = resolveNpmPath();
+    execFileSync(npmPath, ['exec', '--yes', '--', 'wrangler', 'secret', 'put', key, '--env', wranglerEnv], {
+        stdio: ['pipe', 'inherit', 'inherit'],
+        input: value,
+        encoding: 'utf8',
+        timeout: getPutTimeoutMs(),
+        killSignal: 'SIGTERM',
+        env: appConfig.getSafeEnv(),
+    });
+};
+const addOptions = (command) => {
+    command
+        .argument('[provider]', 'Secret provider (cloudflare)', 'cloudflare')
+        .option('--wg <env...>', 'Wrangler environment target(s), e.g. d1-proxy kv-proxy')
+        .option('--var <configKey...>', 'Config array key(s) from .zintrust.json (e.g. d1_env kv_env)')
+        .option('--env_path <path>', 'Path to env file used as source values', '.env')
+        .option('--dry-run', 'Show what would be uploaded without calling wrangler');
+};
+const ensureCloudflareProvider = (providerRaw) => {
+    if (providerRaw.toLowerCase() === 'cloudflare')
+        return;
+    throw ErrorFactory.createCliError('Only cloudflare provider is supported for `zin put`');
+};
+const resolveSelectedKeys = (cmd, config, options) => {
+    const configGroups = resolveConfigGroups(options);
+    if (configGroups.length === 0) {
+        throw ErrorFactory.createCliError('No config groups selected. Use --var <group>.');
+    }
+    const selectedKeys = uniq(configGroups.flatMap((groupKey) => {
+        const keys = getConfigArray(config, groupKey);
+        if (keys.length === 0) {
+            cmd.warn(`Group \`${groupKey}\` is missing or empty in .zintrust.json`);
+        }
+        return keys;
+    }));
+    if (selectedKeys.length === 0) {
+        throw ErrorFactory.createCliError('No secret keys resolved from selected groups.');
+    }
+    return selectedKeys;
+};
+const getFailureReason = (error) => error instanceof Error ? error.message : String(error);
+const reportResult = (cmd, pushed, failures) => {
+    cmd.success(`Cloudflare secrets report: pushed=${pushed}, failed=${failures.length}`);
+    for (const item of failures) {
+        cmd.warn(`${item.key} -> ${item.wranglerEnv}: ${item.reason}`);
+    }
+};
+const processPut = (cmd, wranglerEnvs, selectedKeys, envMap, dryRun) => {
+    let pushed = 0;
+    const failures = [];
+    for (const wranglerEnv of wranglerEnvs) {
+        for (const key of selectedKeys) {
+            const value = resolveValue(key, envMap);
+            if (value.trim() === '') {
+                failures.push({ wranglerEnv, key, reason: 'empty value' });
+                continue;
+            }
+            try {
+                if (!dryRun) {
+                    cmd.info(`putting ${key} -> ${wranglerEnv}...`);
+                    putSecret(wranglerEnv, key, value);
+                }
+                pushed += 1;
+                cmd.info(`${dryRun ? '[dry-run] ' : ''}put ${key} -> ${wranglerEnv}`);
+            }
+            catch (error) {
+                failures.push({ wranglerEnv, key, reason: getFailureReason(error) });
+            }
+        }
+    }
+    return { pushed, failures };
+};
+const execute = async (cmd, options) => {
+    ensureCloudflareProvider(String(options.args?.[0] ?? 'cloudflare'));
+    const cwd = process.cwd();
+    const config = readZintrustConfig(cwd);
+    const selectedKeys = resolveSelectedKeys(cmd, config, options);
+    const envFilePath = parseEnvPath(options);
+    const envMap = await EnvFile.read({ cwd, path: envFilePath });
+    const wranglerEnvs = resolveWranglerEnvs(options);
+    const dryRun = options.dryRun === true;
+    const result = processPut(cmd, wranglerEnvs, selectedKeys, envMap, dryRun);
+    reportResult(cmd, result.pushed, result.failures);
+};
+export const PutCommand = Object.freeze({
+    create() {
+        const cmd = BaseCommand.create({
+            name: 'put',
+            description: 'Put secrets to Cloudflare with dynamic groups from .zintrust.json',
+            addOptions,
+            execute: async (options) => execute(cmd, options),
+        });
+        return cmd;
+    },
+});
+export default PutCommand;

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

@@ -1 +1 @@
-{"version":3,"file":"QueueRecoveryCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/QueueRecoveryCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAwoBrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAsBtB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"QueueRecoveryCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/QueueRecoveryCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAwvBrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAsBtB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/src/cli/commands/QueueRecoveryCommand.js

@@ -1,8 +1,10 @@
 import { BaseCommand } from '../BaseCommand.js';
+import { databaseConfig } from '../../config/database.js';
 import { Logger } from '../../config/logger.js';
 import { queueConfig } from '../../config/queue.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
-import { useDatabase } from '../../orm/Database.js';
+import { resetDatabase, useDatabase } from '../../orm/Database.js';
+import { registerDatabasesFromRuntimeConfig } from '../../orm/DatabaseRuntimeRegistration.js';
 import { JobRecoveryDaemon } from '../../tools/queue/JobRecoveryDaemon.js';
 import { JobStateTracker } from '../../tools/queue/JobStateTracker.js';
 import { Queue } from '../../tools/queue/Queue.js';
@@ -57,6 +59,7 @@ const normalizeStatus = (value) => {
     const statuses = [
         'pending',
         'active',
+        'enqueued',
         'completed',
         'failed',
         'stalled',
@@ -98,17 +101,13 @@ const toRecordFromPersisted = (row) => {
     };
 };
 const getRecoverableStatuses = () => {
-    return new Set([
-        'pending_recovery',
-        'timeout',
-        'stalled',
-        'dead_letter',
-    ]);
+    return new Set(['pending_recovery']);
 };
 const getAllStatuses = () => {
     return new Set([
         'pending',
         'active',
+        'enqueued',
         'completed',
         'failed',
         'stalled',
@@ -355,8 +354,35 @@ const runRecoveryOnce = async () => {
     const result = await JobRecoveryDaemon.runOnce();
     Logger.info('Queue recovery run completed', result);
 };
+const isDuplicateJobIdError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    return normalized.includes('jobid') && normalized.includes('already exists');
+};
+const validatePushable = (record) => {
+    if (record.status === 'enqueued') {
+        Logger.info('Job is already enqueued; nothing to push', {
+            jobId: record.jobId,
+            queueName: record.queueName,
+        });
+        return { ok: false };
+    }
+    if (record.status !== 'pending_recovery') {
+        Logger.error(`Refusing to push job in status ${record.status}. Only pending_recovery can be pushed.`);
+        if (typeof process !== 'undefined')
+            process.exitCode = 1;
+        return { ok: false };
+    }
+    return { ok: true };
+};
 const runPushForJob = async (record, options) => {
-    const payload = toSafeObject(record.payload);
+    if (!validatePushable(record).ok)
+        return;
+    const basePayload = toSafeObject(record.payload);
+    const hasPayload = record.payload !== undefined &&
+        record.payload !== null &&
+        typeof record.payload === 'object' &&
+        Object.keys(basePayload).length > 0;
     if (options.dryRun) {
         Logger.info('Dry-run: skipping enqueue for target job', {
             jobId: record.jobId,
@@ -365,12 +391,36 @@ const runPushForJob = async (record, options) => {
         });
         return;
     }
-    const replayJobId = await Queue.enqueue(record.queueName, payload);
-    await JobStateTracker.markedRecovered({
+    if (!hasPayload) {
+        Logger.error(`Cannot push job because payload is missing in tracker/persistence store: ${record.jobId}. ` +
+            'Rehydrate payload_json first (or use policy recovery states) before pushing.');
+        if (typeof process !== 'undefined')
+            process.exitCode = 1;
+        return;
+    }
+    const payload = {
+        ...basePayload,
+        uniqueId: record.jobId,
+        attempts: typeof record.maxAttempts === 'number' ? record.maxAttempts : 3,
+        _currentAttempts: Math.max(0, Math.floor(record.attempts ?? 0)),
+        timestamp: Date.now(),
+    };
+    let replayJobId;
+    try {
+        replayJobId = await Queue.enqueue(record.queueName, payload, 'default');
+    }
+    catch (error) {
+        if (isDuplicateJobIdError(error)) {
+            replayJobId = record.jobId;
+        }
+        else {
+            throw error;
+        }
+    }
+    await JobStateTracker.handedOffToQueue({
         queueName: record.queueName,
         jobId: record.jobId,
         reason: `CLI pushed job as ${replayJobId}`,
-        retryAt: new Date().toISOString(),
     });
     Logger.info('Target job pushed to queue', {
         originalJobId: record.jobId,
@@ -378,6 +428,21 @@ const runPushForJob = async (record, options) => {
         queueName: record.queueName,
     });
 };
+const isTestRuntime = () => (process.env['NODE_ENV'] ?? '').trim().toLowerCase() === 'test' || Boolean(process.env['VITEST']);
+const cleanupOneOffCli = async () => {
+    try {
+        QueueReliabilityOrchestrator.stop();
+    }
+    catch {
+        // ignore
+    }
+    try {
+        await resetDatabase();
+    }
+    catch {
+        // ignore
+    }
+};
 const runRecoverOneForJob = async (record, options) => {
     if (options.dryRun) {
         Logger.info('Dry-run: skipping policy recovery for target job', {
@@ -456,10 +521,23 @@ const runTargetedRecovery = async (resolved) => {
         return;
     const record = await findRecord(resolved.jobId, resolved.queueName, resolved.allowDbLookup);
     if (record === null) {
-        throw ErrorFactory.createConfigError(`Job not found in tracker${resolved.allowDbLookup ? ' or persistence store' : ''}: ${resolved.jobId}`);
+        Logger.error(`Job not found in tracker${resolved.allowDbLookup ? ' or persistence store' : ''}: ${resolved.jobId}`);
+        if (typeof process !== 'undefined')
+            process.exitCode = 1;
+        return;
+    }
+    if (record.status === 'enqueued' && !resolved.push) {
+        Logger.info('Job already enqueued; nothing to recover', {
+            jobId: record.jobId,
+            queueName: record.queueName,
+        });
+        return;
     }
     if (!resolved.push && !getRecoverableStatuses().has(record.status)) {
-        throw ErrorFactory.createConfigError(`Job status is not recoverable via policy runner: ${record.status}. Use --push to force requeue.`);
+        Logger.error(`Job status is not recoverable via policy runner: ${record.status}. Use --push to force requeue.`);
+        if (typeof process !== 'undefined')
+            process.exitCode = 1;
+        return;
     }
     if (resolved.push) {
         await runPushForJob(record, { dryRun: resolved.dryRun });
@@ -480,11 +558,32 @@ const executeQueueRecovery = async (options) => {
     const resolved = resolveExecutionOptions(options);
     if (await maybeRunListMode(resolved))
         return;
-    await registerQueuesFromRuntimeConfig(queueConfig);
+    // Ensure DB connections exist for optional persistence lookups.
+    // (CLI commands don't run full app bootstrap.)
+    registerDatabasesFromRuntimeConfig(databaseConfig);
+    const envDefault = (process.env['QUEUE_DRIVER'] ?? '').toString().trim().toLowerCase();
+    const cliQueueConfig = {
+        ...queueConfig,
+        default: (envDefault.length > 0
+            ? envDefault
+            : queueConfig.default),
+    };
+    await registerQueuesFromRuntimeConfig(cliQueueConfig);
+    if (!resolved.start) {
+        // Queue registration may auto-start orchestrator when JOB_RELIABILITY_AUTOSTART=true.
+        // For one-off CLI runs, stop it to avoid noisy intervals.
+        QueueReliabilityOrchestrator.stop();
+    }
     if (await maybeRunDefaultRecovery(resolved))
         return;
     await runTargetedRecovery(resolved);
     await finalizeRecoveryExecution(resolved);
+    if (!resolved.start) {
+        await cleanupOneOffCli();
+        if (!isTestRuntime() && typeof process !== 'undefined') {
+            process.exit(process.exitCode ?? 0);
+        }
+    }
 };
 export const QueueRecoveryCommand = Object.freeze({
     create() {

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

@@ -0,0 +1,6 @@
+import type { IBaseCommand } from '../BaseCommand';
+export declare const ScheduleListCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default ScheduleListCommand;
+//# sourceMappingURL=ScheduleListCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleListCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleListCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsErE,eAAO,MAAM,mBAAmB;cACpB,YAAY;EAUtB,CAAC;AAEH,eAAe,mBAAmB,CAAC"}