bunqueue 2.8.38 → 2.8.40

package/dist/cli/commands/doctor.js

@@ -1,128 +1,145 @@
-/**
- * bunqueue doctor - Diagnostic command
- * Checks client/server version, connectivity, health, and queue state
- */
 import { VERSION } from '../../shared/version';
-const green = '\x1b[32m';
-const red = '\x1b[31m';
-const yellow = '\x1b[33m';
-const dim = '\x1b[2m';
-const bold = '\x1b[1m';
-const reset = '\x1b[0m';
-function pass(msg) {
-    console.log(`  ${green}✓${reset} ${msg}`);
+const style = {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    reset: '\x1b[0m',
+};
+export async function fetchDoctorHealth(host, httpPort) {
+    const endpoint = `${host}:${httpPort}`;
+    try {
+        const response = await fetch(`http://${endpoint}/health`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            return { kind: 'http-error', endpoint, status: response.status };
+        }
+        return {
+            kind: 'ok',
+            endpoint,
+            health: (await response.json()),
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'network-error',
+            endpoint,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
 }
-function fail(msg) {
-    console.log(`  ${red}✗${reset} ${msg}`);
+/** Evaluate diagnostics without performing I/O or reading clocks. */
+export function evaluateDoctor(input) {
+    if (input.kind !== 'ok') {
+        const error = input.kind === 'http-error' ? `HTTP ${input.status} from ${input.endpoint}` : input.message;
+        return {
+            clientVersion: VERSION,
+            endpoint: input.endpoint,
+            reachable: false,
+            error,
+            issues: 1,
+            fatal: true,
+            exitCode: 1,
+        };
+    }
+    const health = input.health;
+    let issues = 0;
+    if (health.version && health.version !== VERSION)
+        issues++;
+    if (health.status !== 'healthy')
+        issues++;
+    if ((health.queues?.dlq ?? 0) > 0)
+        issues++;
+    if ((health.memory?.rss ?? 0) > 512)
+        issues++;
+    return {
+        clientVersion: VERSION,
+        endpoint: input.endpoint,
+        reachable: true,
+        health,
+        issues,
+        fatal: false,
+        exitCode: issues > 0 ? 1 : 0,
+    };
 }
-function warn(msg) {
-    console.log(`  ${yellow}!${reset} ${msg}`);
+function mark(kind, message) {
+    const decoration = kind === 'pass' ? `${style.green}✓` : kind === 'fail' ? `${style.red}✗` : `${style.yellow}!`;
+    return `  ${decoration}${style.reset} ${message}`;
 }
-function info(msg) {
-    console.log(`  ${dim}${msg}${reset}`);
+function formatUptime(uptime) {
+    const hours = Math.floor(uptime / 3600);
+    const minutes = Math.floor((uptime % 3600) / 60);
+    const seconds = uptime % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    parts.push(`${seconds}s`);
+    return parts.join(' ');
 }
-export async function runDoctor(host, httpPort) {
-    console.log(`\n${bold}bunqueue doctor${reset}\n`);
-    let issues = 0;
-    // 1. Client version
-    console.log(`${bold}Client${reset}`);
-    pass(`Version: ${VERSION}`);
-    // 2. Server connectivity + version
-    console.log(`\n${bold}Server${reset}`);
-    const url = `http://${host}:${httpPort}/health`;
-    let health = null;
-    try {
-        const resp = await fetch(url, { signal: AbortSignal.timeout(5000) });
-        if (resp.ok) {
-            health = (await resp.json());
-            pass(`Reachable at ${host}:${httpPort}`);
-        }
+export function formatDoctorText(report) {
+    const lines = [
+        '',
+        `${style.bold}bunqueue doctor${style.reset}`,
+        '',
+        `${style.bold}Client${style.reset}`,
+        mark('pass', `Version: ${report.clientVersion}`),
+        '',
+        `${style.bold}Server${style.reset}`,
+    ];
+    if (!report.reachable) {
+        if (report.error?.startsWith('HTTP '))
+            lines.push(mark('fail', report.error));
         else {
-            fail(`HTTP ${resp.status} from ${host}:${httpPort}`);
-            issues++;
+            lines.push(mark('fail', `Not reachable at ${report.endpoint}`));
+            if (report.error)
+                lines.push(`  ${style.dim}${report.error}${style.reset}`);
         }
+        lines.push('', `${style.red}${style.bold}Cannot continue without server connection.${style.reset}`, `${style.dim}Start the server or use --port to specify the TCP port.${style.reset}`, '');
+        return lines.join('\n');
     }
-    catch (err) {
-        fail(`Not reachable at ${host}:${httpPort}`);
-        info(err instanceof Error ? err.message : String(err));
-        issues++;
-    }
-    if (!health) {
-        console.log(`\n${red}${bold}Cannot continue without server connection.${reset}`);
-        console.log(`${dim}Start the server or use --port to specify the TCP port.${reset}\n`);
-        process.exit(1);
-    }
-    // 3. Server version + mismatch check
+    const health = report.health ?? {};
+    lines.push(mark('pass', `Reachable at ${report.endpoint}`));
     if (health.version) {
-        pass(`Version: ${health.version}`);
+        lines.push(mark('pass', `Version: ${health.version}`));
         if (health.version !== VERSION) {
-            warn(`Version mismatch! Client=${VERSION}, Server=${health.version}`);
-            info('Update both client and server to the same version');
-            issues++;
+            lines.push(mark('warn', `Version mismatch! Client=${VERSION}, Server=${health.version}`));
+            lines.push(`  ${style.dim}Update both client and server to the same version${style.reset}`);
         }
     }
-    // 4. Server status
-    if (health.status === 'healthy') {
-        pass(`Status: healthy`);
-    }
-    else {
-        fail(`Status: ${health.status ?? 'unknown'}`);
-        issues++;
-    }
-    // 5. Uptime
+    lines.push(health.status === 'healthy'
+        ? mark('pass', 'Status: healthy')
+        : mark('fail', `Status: ${health.status ?? 'unknown'}`));
     if (health.uptime !== undefined) {
-        const hrs = Math.floor(health.uptime / 3600);
-        const mins = Math.floor((health.uptime % 3600) / 60);
-        const secs = health.uptime % 60;
-        const parts = [];
-        if (hrs > 0)
-            parts.push(`${hrs}h`);
-        if (mins > 0)
-            parts.push(`${mins}m`);
-        parts.push(`${secs}s`);
-        pass(`Uptime: ${parts.join(' ')}`);
+        lines.push(mark('pass', `Uptime: ${formatUptime(health.uptime)}`));
     }
-    // 6. Connections
     if (health.connections) {
-        const c = health.connections;
-        pass(`Connections: TCP=${c.tcp ?? 0}, WS=${c.ws ?? 0}, SSE=${c.sse ?? 0}`);
+        const connections = health.connections;
+        lines.push(mark('pass', `Connections: TCP=${connections.tcp ?? 0}, WS=${connections.ws ?? 0}, SSE=${connections.sse ?? 0}`));
     }
-    // 7. Queue state
-    console.log(`\n${bold}Queues${reset}`);
-    const q = health.queues;
-    if (q) {
-        pass(`Waiting: ${q.waiting ?? 0}`);
-        pass(`Active: ${q.active ?? 0}`);
-        pass(`Delayed: ${q.delayed ?? 0}`);
-        pass(`Completed: ${q.completed ?? 0}`);
-        if ((q.dlq ?? 0) > 0) {
-            warn(`DLQ: ${q.dlq} (dead-letter jobs need attention)`);
-            issues++;
-        }
-        else {
-            pass(`DLQ: 0`);
-        }
+    lines.push('', `${style.bold}Queues${style.reset}`);
+    if (health.queues) {
+        const queues = health.queues;
+        lines.push(mark('pass', `Waiting: ${queues.waiting ?? 0}`), mark('pass', `Active: ${queues.active ?? 0}`), mark('pass', `Delayed: ${queues.delayed ?? 0}`), mark('pass', `Completed: ${queues.completed ?? 0}`), (queues.dlq ?? 0) > 0
+            ? mark('warn', `DLQ: ${queues.dlq} (dead-letter jobs need attention)`)
+            : mark('pass', 'DLQ: 0'));
     }
-    // 8. Memory
-    console.log(`\n${bold}Memory${reset}`);
+    lines.push('', `${style.bold}Memory${style.reset}`);
     if (health.memory) {
-        const m = health.memory;
-        const heapUsed = typeof m.heapUsed === 'number' ? m.heapUsed : 0;
-        const rss = typeof m.rss === 'number' ? m.rss : 0;
-        pass(`Heap: ${heapUsed}MB`);
-        pass(`RSS: ${rss}MB`);
-        if (rss > 512) {
-            warn(`High memory usage (${rss}MB RSS)`);
-            issues++;
-        }
-    }
-    // Summary
-    console.log('');
-    if (issues === 0) {
-        console.log(`${green}${bold}All checks passed.${reset}\n`);
+        const heapUsed = health.memory.heapUsed ?? 0;
+        const rss = health.memory.rss ?? 0;
+        lines.push(mark('pass', `Heap: ${heapUsed}MB`), mark('pass', `RSS: ${rss}MB`));
+        if (rss > 512)
+            lines.push(mark('warn', `High memory usage (${rss}MB RSS)`));
     }
-    else {
-        console.log(`${yellow}${bold}${issues} issue${issues > 1 ? 's' : ''} found.${reset}\n`);
-    }
-    process.exit(issues > 0 ? 1 : 0);
+    lines.push('', report.issues === 0
+        ? `${style.green}${style.bold}All checks passed.${style.reset}`
+        : `${style.yellow}${style.bold}${report.issues} issue${report.issues > 1 ? 's' : ''} found.${style.reset}`, '');
+    return lines.join('\n');
+}
+export async function runDoctor(host, httpPort) {
+    return evaluateDoctor(await fetchDoctorHealth(host, httpPort));
 }

package/dist/cli/commands/types.js

@@ -33,7 +33,11 @@ export function parseNumberArg(value, name) {
     if (!/^-?\d+$/.test(value)) {
         throw new CommandError(`Invalid number for ${name}: ${value}`);
     }
-    return parseInt(value, 10);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new CommandError(`Invalid number for ${name}: ${value}`);
+    }
+    return parsed === 0 ? 0 : parsed;
 }
 /** Parse job ID argument (UUIDs, numeric IDs, or custom IDs) */
 export function parseBigIntArg(value, name) {

package/dist/cli/globalOptions.d.ts

@@ -0,0 +1,16 @@
+export interface GlobalOptions {
+    host: string;
+    port: number;
+    token?: string;
+    tls?: boolean | {
+        rejectUnauthorized?: boolean;
+        caFile?: string;
+    };
+    json: boolean;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseGlobalOptions(allArgs?: string[]): {
+    options: GlobalOptions;
+    commandArgs: string[];
+};

package/dist/cli/globalOptions.js

@@ -0,0 +1,192 @@
+import { resolveToken } from '../client/resolveToken';
+function resolveEnvPort(currentPort) {
+    const envPort = Bun.env.TCP_PORT ?? Bun.env.BUNQUEUE_TCP_PORT ?? Bun.env.BQ_TCP_PORT;
+    if (!envPort)
+        return currentPort;
+    const parsed = parseInt(envPort, 10);
+    if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        console.warn(`Warning: Invalid env port "${envPort}". Using ${currentPort}.`);
+        return currentPort;
+    }
+    return parsed;
+}
+function resolveEnvHost(currentHost) {
+    return Bun.env.HOST ?? Bun.env.BUNQUEUE_HOST ?? Bun.env.BQ_HOST ?? currentHost;
+}
+function applyTlsFlag(arg, allArgs, index, state, commandArgs) {
+    if (arg === '--tls') {
+        state.enabled = true;
+        return index;
+    }
+    if (arg === '--tls-no-verify') {
+        state.noVerify = true;
+        return index;
+    }
+    if (arg === '--tls-ca') {
+        const value = allArgs[index + 1];
+        if (value === undefined || value.startsWith('-')) {
+            console.warn('Warning: --tls-ca requires a file path. Option ignored.');
+            return index;
+        }
+        state.caFile = value;
+        return index + 1;
+    }
+    if (arg.startsWith('--tls-ca=')) {
+        const value = arg.slice(9);
+        if (value)
+            state.caFile = value;
+        else
+            console.warn('Warning: --tls-ca= requires a file path. Option ignored.');
+        return index;
+    }
+    commandArgs.push(arg);
+    return index;
+}
+function buildTlsOption(state) {
+    if (state.noVerify || state.caFile !== undefined) {
+        return {
+            ...(state.noVerify && { rejectUnauthorized: false }),
+            ...(state.caFile !== undefined && { caFile: state.caFile }),
+        };
+    }
+    return state.enabled ? true : undefined;
+}
+function commandOwnsShortT(commandArgs) {
+    return commandArgs[0] === 'pull' || (commandArgs[0] === 'job' && commandArgs[1] === 'wait');
+}
+function applyTokenFlag(arg, allArgs, index, state, commandArgs) {
+    if (arg === '-t' && commandOwnsShortT(commandArgs)) {
+        commandArgs.push(arg);
+        return index;
+    }
+    const value = allArgs[index + 1];
+    if (value === undefined || value.startsWith('-')) {
+        console.warn('Warning: --token requires a value. Token not set.');
+        return index;
+    }
+    state.token = value;
+    return index + 1;
+}
+function applyHostFlag(allArgs, index, state) {
+    const value = allArgs[index + 1];
+    if (value === undefined || value.startsWith('-')) {
+        console.warn('Warning: --host requires a value. Using localhost.');
+        return index;
+    }
+    state.host = value;
+    state.hostExplicit = true;
+    return index + 1;
+}
+function applyPortFlag(allArgs, index, state) {
+    const value = allArgs[index + 1];
+    if (value === undefined || value.startsWith('-')) {
+        console.warn('Warning: --port requires a value. Using default port 6789.');
+        return index;
+    }
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        console.warn(`Warning: Invalid port "${value}". Using default port 6789.`);
+        state.port = 6789;
+    }
+    else {
+        state.port = parsed;
+        state.portExplicit = true;
+    }
+    return index + 1;
+}
+function warnAmbiguousAttachedShort(arg, commandArgs) {
+    if (!/^-[Hpthv][^-\s]/.test(arg))
+        return;
+    if (arg.startsWith('-t') && commandOwnsShortT(commandArgs))
+        return;
+    console.warn(`Warning: "${arg}" looks like a short flag with an attached value; ` +
+        `use the separated form ("${arg.slice(0, 2)} ${arg.slice(2)}") or the long form.`);
+}
+export function parseGlobalOptions(allArgs = process.argv.slice(2)) {
+    const hp = {
+        host: 'localhost',
+        port: 6789,
+        hostExplicit: false,
+        portExplicit: false,
+    };
+    const tokenState = {};
+    const tlsState = { enabled: false, noVerify: false };
+    const commandArgs = [];
+    let json = false;
+    let help = false;
+    let version = false;
+    for (let index = 0; index < allArgs.length; index++) {
+        const arg = allArgs[index];
+        if (arg === '--') {
+            commandArgs.push(...allArgs.slice(index + 1));
+            break;
+        }
+        if (arg === '--host' || arg === '-H') {
+            index = applyHostFlag(allArgs, index, hp);
+        }
+        else if (arg === '--port' || arg === '-p') {
+            index = applyPortFlag(allArgs, index, hp);
+        }
+        else if (arg === '--token' || arg === '-t') {
+            index = applyTokenFlag(arg, allArgs, index, tokenState, commandArgs);
+        }
+        else if (arg.startsWith('--tls')) {
+            index = applyTlsFlag(arg, allArgs, index, tlsState, commandArgs);
+        }
+        else if (arg === '--json') {
+            json = true;
+        }
+        else if (arg === '--help' || (arg === '-h' && commandArgs.length === 0)) {
+            help = true;
+        }
+        else if (arg === '--version' || (arg === '-v' && commandArgs.length === 0)) {
+            version = true;
+        }
+        else if (arg.startsWith('--host=')) {
+            hp.host = arg.slice(7);
+            hp.hostExplicit = true;
+        }
+        else if (arg.startsWith('--port=')) {
+            const raw = arg.slice(7);
+            const parsed = parseInt(raw, 10);
+            if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
+                console.warn(`Warning: Invalid port "${raw}". Using default port 6789.`);
+                hp.port = 6789;
+            }
+            else {
+                hp.port = parsed;
+                hp.portExplicit = true;
+            }
+        }
+        else if (arg.startsWith('--token=')) {
+            const value = arg.slice(8);
+            if (value)
+                tokenState.token = value;
+            else
+                console.warn('Warning: --token= requires a value. Token not set.');
+        }
+        else {
+            warnAmbiguousAttachedShort(arg, commandArgs);
+            commandArgs.push(arg);
+        }
+    }
+    const serverMode = commandArgs[0] === 'start' || commandArgs.length === 0 || commandArgs[0]?.startsWith('-');
+    if (serverMode) {
+        if (hp.hostExplicit)
+            commandArgs.push('--host', hp.host);
+        if (hp.portExplicit)
+            commandArgs.push('--tcp-port', String(hp.port));
+    }
+    return {
+        options: {
+            host: hp.hostExplicit ? hp.host : resolveEnvHost(hp.host),
+            port: hp.portExplicit ? hp.port : resolveEnvPort(hp.port),
+            token: resolveToken(tokenState.token),
+            tls: buildTlsOption(tlsState),
+            json,
+            help,
+            version,
+        },
+        commandArgs,
+    };
+}

package/dist/cli/help.d.ts

@@ -3,11 +3,20 @@
  */
 /** Print version information */
 export declare function printVersion(version: string): void;
+export declare function renderVersion(version: string): string;
+/** Render main help, optionally without terminal escapes for JSON output. */
+export declare function renderHelp(color?: boolean): string;
 /** Print main help */
 export declare function printHelp(): void;
+/** Render server help. */
+export declare function renderServerHelp(): string;
 /** Print server help */
 export declare function printServerHelp(): void;
+/** Render push command help. */
+export declare function renderPushHelp(): string;
 /** Print push command help */
 export declare function printPushHelp(): void;
+/** Render cron add help. */
+export declare function renderCronAddHelp(): string;
 /** Print cron add help */
 export declare function printCronAddHelp(): void;

package/dist/cli/help.js

@@ -3,15 +3,18 @@
  */
 /** Print version information */
 export function printVersion(version) {
-    console.log(`bunqueue v${version}`);
+    console.log(renderVersion(version));
 }
-/** Print main help */
-export function printHelp() {
-    const magenta = '\x1b[35m';
-    const reset = '\x1b[0m';
-    const dim = '\x1b[2m';
-    const bold = '\x1b[1m';
-    console.log(`
+export function renderVersion(version) {
+    return `bunqueue v${version}`;
+}
+/** Render main help, optionally without terminal escapes for JSON output. */
+export function renderHelp(color = true) {
+    const magenta = color ? '\x1b[35m' : '';
+    const reset = color ? '\x1b[0m' : '';
+    const dim = color ? '\x1b[2m' : '';
+    const bold = color ? '\x1b[1m' : '';
+    return `
 ${magenta}   (\\(\\        ${reset}
 ${magenta}   ( -.-)      ${bold}bunqueue${reset} ${dim}- High-performance job queue for Bun${reset}
 ${magenta}   o_(")(")    ${reset}
@@ -85,11 +88,13 @@ MONITORING:
   stats                           Show server statistics
   metrics                         Show Prometheus metrics
   health                          Health check
+  ping                            Check TCP connectivity
   version                         Show client and server version
   doctor                          Run diagnostics (version, health, queues)
 
 BACKUP (S3):
   backup now                      Create backup immediately
+  backup create                   Alias for backup now
   backup list                     List available backups
   backup restore <key> [-f]       Restore from backup
   backup status                   Show backup configuration
@@ -115,11 +120,15 @@ EXAMPLES:
   bunqueue job get 12345
   bunqueue queue list
   bunqueue stats --json
-`);
+`;
 }
-/** Print server help */
-export function printServerHelp() {
-    console.log(`
+/** Print main help */
+export function printHelp() {
+    console.log(renderHelp());
+}
+/** Render server help. */
+export function renderServerHelp() {
+    return `
 Usage: bunqueue start [options]
 
 Start the bunQ server.
@@ -138,11 +147,15 @@ Examples:
   bunqueue start
   bunqueue start --tcp-port 7000 --http-port 7001
   bunqueue start --data-path ./data/queue.db
-`);
+`;
 }
-/** Print push command help */
-export function printPushHelp() {
-    console.log(`
+/** Print server help */
+export function printServerHelp() {
+    console.log(renderServerHelp());
+}
+/** Render push command help. */
+export function renderPushHelp() {
+    return `
 Usage: bunqueue push <queue> <data> [options]
 
 Push a job to a queue.
@@ -171,11 +184,15 @@ Examples:
   bunqueue push emails '{"to":"user@test.com"}'
   bunqueue push tasks '{"action":"sync"}' --priority 10
   bunqueue push jobs '{"id":1}' --delay 60000 --max-attempts 5
-`);
+`;
 }
-/** Print cron add help */
-export function printCronAddHelp() {
-    console.log(`
+/** Print push command help */
+export function printPushHelp() {
+    console.log(renderPushHelp());
+}
+/** Render cron add help. */
+export function renderCronAddHelp() {
+    return `
 Usage: bunqueue cron add <name> [options]
 
 Add a cron job.
@@ -194,5 +211,9 @@ Options:
 Examples:
   bunqueue cron add hourly-cleanup -q maintenance -d '{"task":"cleanup"}' -s "0 * * * *"
   bunqueue cron add health-check -q monitoring -d '{}' -e 60000
-`);
+`;
+}
+/** Print cron add help */
+export function printCronAddHelp() {
+    console.log(renderCronAddHelp());
 }

package/dist/cli/index.d.ts

@@ -1,27 +1,3 @@
 #!/usr/bin/env bun
-/**
- * bunqueue CLI Entry Point
- * Routes to server or client mode based on arguments
- */
-/** Global CLI options */
-interface GlobalOptions {
-    host: string;
-    port: number;
-    token?: string;
-    /** TLS to the server: true = verify with system CAs, object = custom CA / no-verify */
-    tls?: boolean | {
-        rejectUnauthorized?: boolean;
-        caFile?: string;
-    };
-    json: boolean;
-    help: boolean;
-    version: boolean;
-}
-/** Parse global options from process.argv */
-export declare function parseGlobalOptions(): {
-    options: GlobalOptions;
-    commandArgs: string[];
-};
-/** Main CLI entry */
+export { parseGlobalOptions } from './globalOptions';
 export declare function main(): Promise<void>;
-export {};