bunqueue 2.8.39 → 2.8.40

package/dist/application/backgroundTasks.js

@@ -208,6 +208,9 @@ export function recover(ctx) {
         if (qs.stallConfig) {
             ctx.shards[shardIndex(qs.name)].setStallConfig(qs.name, qs.stallConfig);
         }
+        if (qs.dlqConfig) {
+            ctx.shards[shardIndex(qs.name)].setDlqConfig(qs.name, qs.dlqConfig);
+        }
     }
     const now = Date.now();
     // === PHASE 1: Recover active jobs (were processing when server stopped) ===

package/dist/application/operations/jobManagement.js

@@ -78,10 +78,13 @@ export async function updateJobProgress(jobId, progress, ctx, message) {
         const job = ctx.processingShards[procIdx].get(jobId);
         if (!job)
             return false;
-        job.progress = Math.max(0, Math.min(100, progress));
-        if (message !== undefined)
-            job.progressMessage = message;
-        job.lastHeartbeat = Date.now();
+        const clampedProgress = Math.max(0, Math.min(100, progress));
+        const effectiveMessage = message === undefined ? job.progressMessage : message;
+        const heartbeat = Date.now();
+        ctx.storage?.updateJobProgress(jobId, clampedProgress, effectiveMessage, heartbeat);
+        job.progress = clampedProgress;
+        job.progressMessage = effectiveMessage;
+        job.lastHeartbeat = heartbeat;
         // Broadcast progress event to internal subscribers
         ctx.eventsManager.broadcast({
             eventType: 'progress',

package/dist/application/operations/jobStateTransitions.js

@@ -37,6 +37,7 @@ export async function moveActiveToWait(jobId, ctx) {
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
         shard.notify(job.queue);
     });
+    ctx.storage?.updateRunAt(jobId, job.runAt);
     ctx.eventsManager.broadcast({
         eventType: 'waiting',
         jobId,

package/dist/application/operations/pull.d.ts

@@ -29,8 +29,8 @@ export interface PullContext {
 /**
  * Pull next job from queue
  */
-export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext): Promise<Job | null>;
+export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job | null>;
 /**
  * Pull multiple jobs from queue
  */
-export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext): Promise<Job[]>;
+export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job[]>;

package/dist/application/operations/pull.js

@@ -122,10 +122,11 @@ function tryDequeueNextJob(shard, queue, now, ctx) {
     }
 }
 /** Wait until either a notification arrives, the next delay matures, or the pull deadline. */
-async function waitForNextCandidate(shard, queue, deadline, now, nextRunAt) {
+async function waitForNextCandidate(options) {
+    const { shard, queue, deadline, now, nextRunAt, signal } = options;
     const remaining = deadline - now;
     const untilNextRun = nextRunAt === null ? remaining : Math.max(1, nextRunAt - now);
-    await shard.waitForJob(queue, Math.min(remaining, untilNextRun));
+    await shard.waitForJob(queue, Math.min(remaining, untilNextRun), signal);
 }
 /**
  * Finish the handoff of a dequeued job: persist active state and broadcast.
@@ -217,14 +218,20 @@ async function requeueJob(job, queue, idx, ctx) {
 /**
  * Pull next job from queue
  */
-export async function pullJob(queue, timeoutMs, ctx) {
+export async function pullJob(queue, timeoutMs, ctx, signal) {
     const startNs = Bun.nanoseconds();
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
-        const attempt = await tryPullFromShard(queue, idx, ctx);
+        if (signal?.aborted)
+            return null;
+        const attempt = await tryPullFromShard(queue, idx, ctx, signal);
         const job = attempt.job;
         if (job) {
+            if (signal?.aborted) {
+                await requeueJob(job, queue, idx, ctx);
+                return null;
+            }
             let delivered = false;
             try {
                 delivered = finalizeProcessing(job, queue, ctx);
@@ -246,14 +253,23 @@ export async function pullJob(queue, timeoutMs, ctx) {
         if (deadline === 0 || now >= deadline) {
             return null;
         }
-        await waitForNextCandidate(ctx.shards[idx], queue, deadline, now, attempt.nextRunAt);
+        await waitForNextCandidate({
+            shard: ctx.shards[idx],
+            queue,
+            deadline,
+            now,
+            nextRunAt: attempt.nextRunAt,
+            signal,
+        });
     }
 }
 /**
  * Try to pull a job from a specific shard
  */
-async function tryPullFromShard(queue, idx, ctx) {
+async function tryPullFromShard(queue, idx, ctx, signal) {
     return await withWriteLock(ctx.shardLocks[idx], () => {
+        if (signal?.aborted)
+            return { job: null, nextRunAt: null };
         const shard = ctx.shards[idx];
         const state = shard.getState(queue);
         if (state.paused) {
@@ -269,14 +285,22 @@ async function tryPullFromShard(queue, idx, ctx) {
 /**
  * Pull multiple jobs from queue
  */
-export async function pullJobBatch(queue, count, timeoutMs, ctx) {
+export async function pullJobBatch(queue, count, timeoutMs, ctx, signal) {
     const startNs = Bun.nanoseconds();
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
-        const attempt = await tryPullBatchFromShard(queue, idx, count, ctx);
+        if (signal?.aborted)
+            return [];
+        const attempt = await tryPullBatchFromShard(queue, idx, count, ctx, signal);
         const jobs = attempt.jobs;
         if (jobs.length > 0) {
+            if (signal?.aborted) {
+                for (const job of jobs) {
+                    await requeueJob(job, queue, idx, ctx);
+                }
+                return [];
+            }
             let delivered;
             try {
                 delivered = finalizeProcessingBatch(jobs, queue, ctx);
@@ -305,14 +329,23 @@ export async function pullJobBatch(queue, count, timeoutMs, ctx) {
         if (deadline === 0 || now >= deadline) {
             return [];
         }
-        await waitForNextCandidate(ctx.shards[idx], queue, deadline, now, attempt.nextRunAt);
+        await waitForNextCandidate({
+            shard: ctx.shards[idx],
+            queue,
+            deadline,
+            now,
+            nextRunAt: attempt.nextRunAt,
+            signal,
+        });
     }
 }
 /**
  * Try to pull multiple jobs from a shard
  */
-async function tryPullBatchFromShard(queue, idx, count, ctx) {
+async function tryPullBatchFromShard(queue, idx, count, ctx, signal) {
     return await withWriteLock(ctx.shardLocks[idx], () => {
+        if (signal?.aborted)
+            return { jobs: [], nextRunAt: null };
         const shard = ctx.shards[idx];
         const state = shard.getState(queue);
         const jobs = [];

package/dist/application/queueManager.d.ts

@@ -65,13 +65,13 @@ export declare class QueueManager {
     private handleRepeat;
     push(queue: string, input: JobInput): Promise<Job>;
     pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
-    pull(queue: string, timeoutMs?: number): Promise<Job | null>;
-    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number): Promise<{
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
         job: Job | null;
         token: string | null;
     }>;
-    pullBatch(queue: string, count: number, timeoutMs?: number): Promise<Job[]>;
-    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number): Promise<{
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
         jobs: Job[];
         tokens: string[];
     }>;

package/dist/application/queueManager.js

@@ -4,6 +4,7 @@
  */
 import { DEFAULT_LOCK_TTL } from '../domain/types/job';
 import { DEFAULT_STALL_CONFIG } from '../domain/types/stall';
+import { DEFAULT_DLQ_CONFIG } from '../domain/types/dlq';
 import { Shard } from '../domain/queue/shard';
 import { SqliteStorage } from '../infrastructure/persistence/sqlite';
 import { CronScheduler } from '../infrastructure/scheduler/cronScheduler';
@@ -257,21 +258,22 @@ export class QueueManager {
         this.registerQueueName(queue);
         return pushJobBatch(queue, inputs, this.contextFactory.getPushContext());
     }
-    async pull(queue, timeoutMs = 0) {
-        return pullJob(queue, timeoutMs, this.contextFactory.getPullContext());
+    async pull(queue, timeoutMs = 0, signal) {
+        return pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
     }
-    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext());
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
         if (!job)
             return { job: null, token: null };
         const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
         return { job, token };
     }
-    async pullBatch(queue, count, timeoutMs = 0) {
-        return pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext());
+    async pullBatch(queue, count, timeoutMs = 0, signal) {
+        return pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
     }
-    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext());
+    // biome-ignore lint/complexity/useMaxParams: preserves the public API while adding cancellation
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
+        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
         const tokens = [];
         for (const job of jobs) {
             const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
@@ -894,10 +896,16 @@ export class QueueManager {
             return;
         const state = this.shards[shardIndex(queue)].getState(queue);
         const stallConfig = this.shards[shardIndex(queue)].getStallConfig(queue);
+        const dlqConfig = this.shards[shardIndex(queue)].getDlqConfig(queue);
         const hasCustomStallConfig = stallConfig.enabled !== DEFAULT_STALL_CONFIG.enabled ||
             stallConfig.stallInterval !== DEFAULT_STALL_CONFIG.stallInterval ||
             stallConfig.maxStalls !== DEFAULT_STALL_CONFIG.maxStalls ||
             stallConfig.gracePeriod !== DEFAULT_STALL_CONFIG.gracePeriod;
+        const hasCustomDlqConfig = dlqConfig.autoRetry !== DEFAULT_DLQ_CONFIG.autoRetry ||
+            dlqConfig.autoRetryInterval !== DEFAULT_DLQ_CONFIG.autoRetryInterval ||
+            dlqConfig.maxAutoRetries !== DEFAULT_DLQ_CONFIG.maxAutoRetries ||
+            dlqConfig.maxAge !== DEFAULT_DLQ_CONFIG.maxAge ||
+            dlqConfig.maxEntries !== DEFAULT_DLQ_CONFIG.maxEntries;
         // When control-state returns fully to default (not paused, no limits), drop
         // the row instead of persisting an all-default placeholder. Keeps the table
         // free of noise rows for ephemeral queues that only ever call resume/clear*,
@@ -905,7 +913,8 @@ export class QueueManager {
         if (!state.paused &&
             state.rateLimit === null &&
             state.concurrencyLimit === null &&
-            !hasCustomStallConfig) {
+            !hasCustomStallConfig &&
+            !hasCustomDlqConfig) {
             this.storage.deleteQueueState(queue);
             return;
         }
@@ -916,6 +925,7 @@ export class QueueManager {
             rateLimitDuration: state.rateLimitDuration,
             rateLimitExpiresAt: state.rateLimitExpiresAt,
             stallConfig,
+            dlqConfig,
         });
     }
     /** Get rate limit and concurrency limit for a queue */
@@ -954,6 +964,7 @@ export class QueueManager {
     }
     setDlqConfig(queue, config) {
         this.shards[shardIndex(queue)].setDlqConfig(queue, config);
+        this.persistQueueState(queue);
     }
     getDlqConfig(queue) {
         return this.shards[shardIndex(queue)].getDlqConfig(queue);
@@ -1290,11 +1301,15 @@ export class QueueManager {
         if (!childJob.parentId)
             return;
         if (childJob.continueParentOnFailure) {
-            this.continueParentOnChildFailure(childJob, error).catch(() => { });
+            this.continueParentOnChildFailure(childJob, error).catch(() => {
+                // Best-effort parent propagation; child failure is already durable.
+            });
         }
         else {
             // removeDependencyOnFailure or ignoreDependencyOnFailure
-            this.removeChildFromParentDeps(childJob, error, childJob.ignoreDependencyOnFailure).catch(() => { });
+            this.removeChildFromParentDeps(childJob, error, childJob.ignoreDependencyOnFailure).catch(() => {
+                // Best-effort parent propagation; child failure is already durable.
+            });
         }
     }
     /**

package/dist/cli/client.js

@@ -3,10 +3,11 @@
  * Connects to bunQ server and executes commands (msgpack binary protocol)
  */
 import { formatOutput, formatError } from './output';
-import { pack, unpack } from 'msgpackr';
 import { FrameParser, FrameSizeError } from '../infrastructure/server/protocol';
 import { CommandError } from './commands/types';
 import { buildClientTls } from '../client/tcp/connection';
+import { buildCommand } from './commandRouter';
+import { decodeMessagePack, encodeMessagePack } from '../shared/msgpack';
 /**
  * Client-side timeout for a command: base 30s; ONLY the long-poll commands
  * (PULL/WaitJob, where `timeout` means "how long the server may hold the
@@ -21,7 +22,7 @@ export function clientTimeoutFor(cmd) {
     return Math.max(30000, cmdTimeout + 10000);
 }
 /** Send a command and wait for response */
-async function sendCommand(socket, command, timeoutMs = 30000) {
+function sendCommand(socket, command, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
         const timeoutId = setTimeout(() => {
             socket.data.resolve = null;
@@ -36,11 +37,11 @@ async function sendCommand(socket, command, timeoutMs = 30000) {
             clearTimeout(timeoutId);
             reject(error);
         };
-        socket.write(FrameParser.frame(pack(command)));
+        socket.write(FrameParser.frame(encodeMessagePack(command)));
     });
 }
 /** Create TCP connection */
-async function connect(options) {
+function connect(options) {
     return new Promise((resolve, reject) => {
         const socketData = {
             frameParser: new FrameParser(),
@@ -73,7 +74,7 @@ async function connect(options) {
                 for (const frame of frames) {
                     if (socketData.resolve) {
                         try {
-                            const response = unpack(frame);
+                            const response = decodeMessagePack(frame);
                             socketData.resolve(response);
                             socketData.resolve = null;
                             socketData.reject = null;
@@ -200,45 +201,3 @@ export async function executeCommand(command, args, options) {
         connection?.close();
     }
 }
-/** Build a command from CLI arguments */
-async function buildCommand(command, args) {
-    // Import command builders
-    const { buildCoreCommand } = await import('./commands/core');
-    const { buildJobCommand } = await import('./commands/job');
-    const { buildQueueCommand } = await import('./commands/queue');
-    const { buildDlqCommand } = await import('./commands/dlq');
-    const { buildCronCommand } = await import('./commands/cron');
-    const { buildWorkerCommand } = await import('./commands/worker');
-    const { buildWebhookCommand } = await import('./commands/webhook');
-    const { buildRateLimitCommand } = await import('./commands/rateLimit');
-    const { buildMonitorCommand } = await import('./commands/monitor');
-    switch (command) {
-        case 'push':
-        case 'pull':
-        case 'ack':
-        case 'fail':
-            return buildCoreCommand(command, args);
-        case 'job':
-            return buildJobCommand(args);
-        case 'queue':
-            return buildQueueCommand(args);
-        case 'dlq':
-            return buildDlqCommand(args);
-        case 'cron':
-            return buildCronCommand(args);
-        case 'worker':
-            return buildWorkerCommand(args);
-        case 'webhook':
-            return buildWebhookCommand(args);
-        case 'rate-limit':
-        case 'concurrency':
-            return buildRateLimitCommand(command, args);
-        case 'stats':
-        case 'metrics':
-        case 'health':
-        case 'ping':
-            return buildMonitorCommand(command);
-        default:
-            return null;
-    }
-}

package/dist/cli/commandRegistry.d.ts

@@ -0,0 +1,27 @@
+/** Canonical CLI command surface used by routing, help conformance, and tests. */
+export declare const CLI_COMMAND_SURFACE: {
+    readonly push: readonly [];
+    readonly pull: readonly [];
+    readonly ack: readonly [];
+    readonly fail: readonly [];
+    readonly job: readonly ["get", "state", "result", "cancel", "progress", "update", "priority", "promote", "delay", "discard", "logs", "log", "wait"];
+    readonly queue: readonly ["list", "pause", "resume", "drain", "obliterate", "clean", "count", "jobs", "paused"];
+    readonly 'rate-limit': readonly ["set", "clear"];
+    readonly concurrency: readonly ["set", "clear"];
+    readonly dlq: readonly ["list", "retry", "purge"];
+    readonly cron: readonly ["list", "add", "delete"];
+    readonly worker: readonly ["list", "register", "unregister"];
+    readonly webhook: readonly ["list", "add", "remove"];
+    readonly stats: readonly [];
+    readonly metrics: readonly [];
+    readonly health: readonly [];
+    readonly ping: readonly [];
+};
+export type CliNetworkCommand = keyof typeof CLI_COMMAND_SURFACE;
+/** Commands handled locally instead of being translated to a TCP command. */
+export declare const CLI_LOCAL_COMMAND_SURFACE: {
+    readonly start: readonly [];
+    readonly version: readonly [];
+    readonly doctor: readonly [];
+    readonly backup: readonly ["now", "create", "list", "restore", "status"];
+};

package/dist/cli/commandRegistry.js

@@ -0,0 +1,40 @@
+/** Canonical CLI command surface used by routing, help conformance, and tests. */
+export const CLI_COMMAND_SURFACE = {
+    push: [],
+    pull: [],
+    ack: [],
+    fail: [],
+    job: [
+        'get',
+        'state',
+        'result',
+        'cancel',
+        'progress',
+        'update',
+        'priority',
+        'promote',
+        'delay',
+        'discard',
+        'logs',
+        'log',
+        'wait',
+    ],
+    queue: ['list', 'pause', 'resume', 'drain', 'obliterate', 'clean', 'count', 'jobs', 'paused'],
+    'rate-limit': ['set', 'clear'],
+    concurrency: ['set', 'clear'],
+    dlq: ['list', 'retry', 'purge'],
+    cron: ['list', 'add', 'delete'],
+    worker: ['list', 'register', 'unregister'],
+    webhook: ['list', 'add', 'remove'],
+    stats: [],
+    metrics: [],
+    health: [],
+    ping: [],
+};
+/** Commands handled locally instead of being translated to a TCP command. */
+export const CLI_LOCAL_COMMAND_SURFACE = {
+    start: [],
+    version: [],
+    doctor: [],
+    backup: ['now', 'create', 'list', 'restore', 'status'],
+};

package/dist/cli/commandRouter.d.ts

@@ -0,0 +1,3 @@
+export declare const CLI_NETWORK_COMMANDS: readonly ("push" | "queue" | "dlq" | "job" | "cron" | "worker" | "concurrency" | "ping" | "stats" | "metrics" | "pull" | "ack" | "fail" | "rate-limit" | "health" | "webhook")[];
+/** Build the protocol command for a routed network CLI command. */
+export declare function buildCommand(command: string, args: string[]): Promise<Record<string, unknown> | null>;

package/dist/cli/commandRouter.js

@@ -0,0 +1,44 @@
+import { CLI_COMMAND_SURFACE } from './commandRegistry';
+export const CLI_NETWORK_COMMANDS = Object.freeze(Object.keys(CLI_COMMAND_SURFACE));
+/** Build the protocol command for a routed network CLI command. */
+export async function buildCommand(command, args) {
+    if (!CLI_NETWORK_COMMANDS.includes(command))
+        return null;
+    const { buildCoreCommand } = await import('./commands/core');
+    const { buildJobCommand } = await import('./commands/job');
+    const { buildQueueCommand } = await import('./commands/queue');
+    const { buildDlqCommand } = await import('./commands/dlq');
+    const { buildCronCommand } = await import('./commands/cron');
+    const { buildWorkerCommand } = await import('./commands/worker');
+    const { buildWebhookCommand } = await import('./commands/webhook');
+    const { buildRateLimitCommand } = await import('./commands/rateLimit');
+    const { buildMonitorCommand } = await import('./commands/monitor');
+    switch (command) {
+        case 'push':
+        case 'pull':
+        case 'ack':
+        case 'fail':
+            return buildCoreCommand(command, args);
+        case 'job':
+            return buildJobCommand(args);
+        case 'queue':
+            return buildQueueCommand(args);
+        case 'dlq':
+            return buildDlqCommand(args);
+        case 'cron':
+            return buildCronCommand(args);
+        case 'worker':
+            return buildWorkerCommand(args);
+        case 'webhook':
+            return buildWebhookCommand(args);
+        case 'rate-limit':
+        case 'concurrency':
+            return buildRateLimitCommand(command, args);
+        case 'stats':
+        case 'metrics':
+        case 'health':
+        case 'ping':
+            return buildMonitorCommand(command);
+    }
+    return null;
+}

package/dist/cli/commands/backup.js

@@ -42,7 +42,7 @@ export async function executeBackupCommand(args) {
         case 'status':
             return executeBackupStatus(manager);
         default:
-            throw new CommandError(`Unknown backup subcommand: ${subcommand}. Use: now, list, restore, status`);
+            throw new CommandError(`Unknown backup subcommand: ${subcommand}. Use: now, create, list, restore, status`);
     }
 }
 async function executeBackupNow(manager) {

package/dist/cli/commands/core.js

@@ -4,6 +4,56 @@
  */
 import { parseArgs } from 'node:util';
 import { CommandError, requireArg, parseJsonArg, parseNumberArg, parseBigIntArg } from './types';
+const PUSH_VALUE_FLAGS = new Set([
+    '--priority',
+    '-P',
+    '--delay',
+    '-d',
+    '--max-attempts',
+    '--backoff',
+    '--ttl',
+    '--timeout',
+    '--unique-key',
+    '-u',
+    '--job-id',
+    '--depends-on',
+    '--tags',
+    '--group-id',
+    '-g',
+]);
+function protectNegativeJsonData(args) {
+    const protectedArgs = [...args];
+    const restore = new Map();
+    let positionals = 0;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--')
+            break;
+        if (PUSH_VALUE_FLAGS.has(arg)) {
+            index++;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            if (positionals !== 1)
+                continue;
+            try {
+                if (typeof JSON.parse(arg) !== 'number')
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const sentinel = `bunqueue-negative-json-${index}`;
+            protectedArgs[index] = sentinel;
+            restore.set(sentinel, arg);
+            positionals++;
+            continue;
+        }
+        if (!arg.startsWith('--') && !/^-[a-zA-Z]/.test(arg))
+            positionals++;
+    }
+    return { args: protectedArgs, restore };
+}
 /** Build a core command from CLI args */
 export function buildCoreCommand(command, args) {
     switch (command) {
@@ -21,8 +71,9 @@ export function buildCoreCommand(command, args) {
 }
 /** Build PUSH command */
 function buildPush(args) {
+    const protectedInput = protectNegativeJsonData(args);
     const { values, positionals } = parseArgs({
-        args,
+        args: protectedInput.args,
         options: {
             priority: { type: 'string', short: 'P' },
             delay: { type: 'string', short: 'd' },
@@ -43,7 +94,8 @@ function buildPush(args) {
         strict: false,
     });
     const queue = requireArg(positionals, 0, 'queue');
-    const data = parseJsonArg(requireArg(positionals, 1, 'data'), 'data');
+    const protectedData = requireArg(positionals, 1, 'data');
+    const data = parseJsonArg(protectedInput.restore.get(protectedData) ?? protectedData, 'data');
     const cmd = {
         cmd: 'PUSH',
         queue,

package/dist/cli/commands/doctor.d.ts

@@ -1,5 +1,50 @@
-/**
- * bunqueue doctor - Diagnostic command
- * Checks client/server version, connectivity, health, and queue state
- */
-export declare function runDoctor(host: string, httpPort: number): Promise<void>;
+export interface HealthData {
+    version?: string;
+    status?: string;
+    uptime?: number;
+    queues?: {
+        waiting?: number;
+        active?: number;
+        delayed?: number;
+        completed?: number;
+        dlq?: number;
+    };
+    connections?: {
+        tcp?: number;
+        ws?: number;
+        sse?: number;
+    };
+    memory?: {
+        heapUsed?: number;
+        heapTotal?: number;
+        rss?: number;
+    };
+}
+export type DoctorInput = {
+    kind: 'ok';
+    endpoint: string;
+    health: HealthData;
+} | {
+    kind: 'http-error';
+    endpoint: string;
+    status: number;
+} | {
+    kind: 'network-error';
+    endpoint: string;
+    message: string;
+};
+export interface DoctorReport {
+    clientVersion: string;
+    endpoint: string;
+    reachable: boolean;
+    health?: HealthData;
+    error?: string;
+    issues: number;
+    fatal: boolean;
+    exitCode: 0 | 1;
+}
+export declare function fetchDoctorHealth(host: string, httpPort: number): Promise<DoctorInput>;
+/** Evaluate diagnostics without performing I/O or reading clocks. */
+export declare function evaluateDoctor(input: DoctorInput): DoctorReport;
+export declare function formatDoctorText(report: DoctorReport): string;
+export declare function runDoctor(host: string, httpPort: number): Promise<DoctorReport>;