bunqueue 2.8.9 → 2.8.10

package/dist/cli/client.d.ts

@@ -16,5 +16,14 @@ export interface ClientOptions {
     /** Output as JSON */
     json: boolean;
 }
+/**
+ * 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
+ * request") get the server-side timeout plus a 10s network buffer so the
+ * client never gives up first. On every other command a `timeout` field has
+ * a different meaning (e.g. PUSH: job execution timeout) and must not
+ * stretch the client wait.
+ */
+export declare function clientTimeoutFor(cmd: Record<string, unknown>): number;
 /** Execute a CLI command against the server */
 export declare function executeCommand(command: string, args: string[], options: ClientOptions): Promise<void>;

package/dist/cli/client.js

@@ -7,14 +7,27 @@ import { pack, unpack } from 'msgpackr';
 import { FrameParser, FrameSizeError } from '../infrastructure/server/protocol';
 import { CommandError } from './commands/types';
 import { buildClientTls } from '../client/tcp/connection';
+/**
+ * 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
+ * request") get the server-side timeout plus a 10s network buffer so the
+ * client never gives up first. On every other command a `timeout` field has
+ * a different meaning (e.g. PUSH: job execution timeout) and must not
+ * stretch the client wait.
+ */
+export function clientTimeoutFor(cmd) {
+    const isLongPoll = cmd.cmd === 'PULL' || cmd.cmd === 'WaitJob';
+    const cmdTimeout = isLongPoll && typeof cmd.timeout === 'number' ? cmd.timeout : 0;
+    return Math.max(30000, cmdTimeout + 10000);
+}
 /** Send a command and wait for response */
-async function sendCommand(socket, command) {
+async function sendCommand(socket, command, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
         const timeoutId = setTimeout(() => {
             socket.data.resolve = null;
             socket.data.reject = null;
             reject(new Error('Command timeout'));
-        }, 30000);
+        }, timeoutMs);
         socket.data.resolve = (value) => {
             clearTimeout(timeoutId);
             resolve(value);
@@ -124,6 +137,13 @@ async function connect(options) {
 export async function executeCommand(command, args, options) {
     let connection = null;
     try {
+        // Build the command first: unknown commands and parse errors must be
+        // reported without requiring a reachable server.
+        const cmd = await buildCommand(command, args);
+        if (!cmd) {
+            console.error(formatError(`Unknown command: ${command}`, options.json));
+            process.exit(1);
+        }
         connection = await connect(options);
         // Authenticate if token provided
         if (options.token) {
@@ -138,14 +158,8 @@ export async function executeCommand(command, args, options) {
                 process.exit(1);
             }
         }
-        // Build the command
-        const cmd = await buildCommand(command, args);
-        if (!cmd) {
-            console.error(formatError(`Unknown command: ${command}`, options.json));
-            process.exit(1);
-        }
         // Execute command
-        const response = await sendCommand(connection.socket, cmd);
+        const response = await sendCommand(connection.socket, cmd, clientTimeoutFor(cmd));
         // Extract subcommand (first positional arg) so the formatter can pick the
         // right verb for batch-id responses (queue drain → "Drained", dlq retry
         // → "Retried", etc.). Falls back to undefined when not applicable.
@@ -154,6 +168,18 @@ export async function executeCommand(command, args, options) {
             console.error(formatOutput(response, command, options.json, subcommand));
             process.exit(1);
         }
+        // `job wait` that ran out of time replies ok:true + completed:false —
+        // for scripts that is a failure, not an "OK": exit 1 with a clear message.
+        if (cmd.cmd === 'WaitJob' && response.completed === false) {
+            console.error(formatError('Job not completed within timeout', options.json));
+            process.exit(1);
+        }
+        // GetState replies ok:true + state:'unknown' for a missing job — align
+        // with `job get` (Job not found, exit 1) instead of a false success.
+        if (cmd.cmd === 'GetState' && response.state === 'unknown') {
+            console.error(formatError('Job not found', options.json));
+            process.exit(1);
+        }
         console.log(formatOutput(response, command, options.json, subcommand));
         // Worker registrations are tied to the TCP connection — the server
         // auto-unregisters when the client disconnects (see tcp.ts close handler).

package/dist/cli/commands/backup.js

@@ -12,12 +12,12 @@ import { CommandError, requireArg } from './types';
 export async function executeBackupCommand(args) {
     const subcommand = args[0];
     const subArgs = args.slice(1);
-    // Get database path from env
-    const dataPath = Bun.env.DATA_PATH ?? Bun.env.SQLITE_PATH;
+    // Get database path from env — canonical priority (see config/resolve.ts)
+    const dataPath = Bun.env.BUNQUEUE_DATA_PATH ?? Bun.env.BQ_DATA_PATH ?? Bun.env.DATA_PATH ?? Bun.env.SQLITE_PATH;
     if (!dataPath) {
         return {
             success: false,
-            message: 'DATA_PATH not set. Backup requires persistent storage.',
+            message: 'BUNQUEUE_DATA_PATH not set. Backup requires persistent storage.',
         };
     }
     // Create backup manager

package/dist/cli/commands/cron.js

@@ -56,14 +56,27 @@ function buildCronAdd(args) {
     if (values.schedule)
         cmd.schedule = values.schedule;
     const every = parseNumberArg(values.every, 'every');
-    if (every !== undefined)
+    if (every !== undefined) {
+        // <= 0 would compute a nextRun that is always in the past: the scheduler
+        // would fire the cron on every tick, indefinitely.
+        if (every <= 0) {
+            throw new CommandError(`Invalid every: ${every}. Must be a positive interval in ms`);
+        }
         cmd.repeatEvery = every;
+    }
     const priority = parseNumberArg(values.priority, 'priority');
     if (priority !== undefined)
         cmd.priority = priority;
     const maxLimit = parseNumberArg(values['max-limit'], 'max-limit');
-    if (maxLimit !== undefined)
-        cmd.maxLimit = maxLimit;
+    if (maxLimit !== undefined) {
+        if (maxLimit < 0) {
+            throw new CommandError(`Invalid max-limit: ${maxLimit}. Must be >= 0 (0 = unlimited)`);
+        }
+        // 0 = unlimited: omit the field so the server stores null (no limit).
+        // Sending 0 would make isAtLimit treat the cron as already exhausted.
+        if (maxLimit > 0)
+            cmd.maxLimit = maxLimit;
+    }
     if (values.timezone)
         cmd.timezone = values.timezone;
     return cmd;

package/dist/cli/commands/job.js

@@ -151,7 +151,11 @@ function buildWaitJob(args) {
         id,
     };
     const timeout = parseNumberArg(values.timeout, 'timeout');
-    if (timeout !== undefined)
+    if (timeout !== undefined) {
+        if (timeout < 0) {
+            throw new CommandError(`Invalid timeout: ${timeout}. Must be >= 0 ms`);
+        }
         cmd.timeout = timeout;
+    }
     return cmd;
 }

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

@@ -1,6 +1,8 @@
 /**
  * Server Command Handler
- * Starts the bunQ server
+ * Parses `bunqueue start` flags and boots the SAME full server as the bare
+ * `bunqueue` entry point (shared bootstrap — S3 backup, cloud agent, stats,
+ * crash handlers and graceful shutdown included).
  */
 /** Run the server */
 export declare function runServer(args: string[], showHelp: boolean): Promise<void>;

package/dist/cli/commands/server.js

@@ -1,11 +1,13 @@
 /**
  * Server Command Handler
- * Starts the bunQ server
+ * Parses `bunqueue start` flags and boots the SAME full server as the bare
+ * `bunqueue` entry point (shared bootstrap — S3 backup, cloud agent, stats,
+ * crash handlers and graceful shutdown included).
  */
 import { parseArgs } from 'node:util';
 import { printServerHelp } from '../help';
-import { VERSION } from '../../shared/version';
-import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveTlsServerOptions, } from '../../config';
+import { loadConfigFile, resolveServerConfig } from '../../config';
+import { bootServer } from '../../infrastructure/server/bootstrap';
 /** Validate port number */
 function validatePort(value, name, defaultPort) {
     const port = parseInt(value, 10);
@@ -103,106 +105,6 @@ export async function runServer(args, showHelp) {
     const fileConfig = await loadConfigFile(flags.configPath);
     const mergedConfig = applyCliFlags(fileConfig, flags);
     const config = resolveServerConfig(mergedConfig);
-    const cloudConfig = resolveCloudConfig(mergedConfig, config.dataPath);
-    // Resolve TLS — fail fast on partial cert/key before binding anything
-    let tlsConfig;
-    try {
-        tlsConfig = resolveTlsServerOptions(config);
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-    // Import and start the server components
-    const { QueueManager } = await import('../../application/queueManager');
-    const { createTcpServer } = await import('../../infrastructure/server/tcp');
-    const { createHttpServer } = await import('../../infrastructure/server/http');
-    const { serverLog } = await import('../../shared/logger');
-    // Initialize
-    const qm = new QueueManager({
-        dataPath: config.dataPath,
-    });
-    const authTokens = config.authTokens.length > 0 ? config.authTokens : undefined;
-    // Start TCP and HTTP servers
-    let tcpServer;
-    let httpServer;
-    try {
-        tcpServer = createTcpServer(qm, {
-            port: config.tcpPort,
-            hostname: config.hostname,
-            authTokens,
-            ...(tlsConfig && { tls: tlsConfig }),
-        });
-        httpServer = createHttpServer(qm, {
-            port: config.httpPort,
-            hostname: config.hostname,
-            authTokens,
-            ...(tlsConfig && { tls: tlsConfig }),
-        });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : 'Unknown error';
-        console.error(`Failed to start server: ${msg}`);
-        qm.shutdown();
-        process.exit(1);
-    }
-    serverLog.info('bunqueue server started', {
-        tcpPort: config.tcpPort,
-        httpPort: config.httpPort,
-        host: config.hostname,
-        dataPath: config.dataPath ?? 'in-memory',
-        auth: authTokens ? 'enabled' : 'disabled',
-    });
-    // Initialize bunqueue Cloud agent (remote dashboard telemetry)
-    const { CloudAgent } = await import('../../infrastructure/cloud/cloudAgent');
-    const cloudAgent = cloudConfig ? CloudAgent.createFromConfig(qm, cloudConfig) : null;
-    if (cloudAgent) {
-        cloudAgent.setServerHandles({
-            getConnectionCount: () => tcpServer.getConnectionCount(),
-            getWsClientCount: () => httpServer.getWsClientCount(),
-            getSseClientCount: () => httpServer.getSseClientCount(),
-        });
-    }
-    const dim = '\x1b[2m';
-    const reset = '\x1b[0m';
-    const bold = '\x1b[1m';
-    const magenta = '\x1b[35m';
-    const green = '\x1b[32m';
-    const yellow = '\x1b[33m';
-    // Format endpoint display
-    const tcpDisplay = `${bold}${config.hostname}:${config.tcpPort}${reset}`;
-    const httpDisplay = `${bold}${config.hostname}:${config.httpPort}${reset}`;
-    console.log(`
-${magenta}        (\\(\\        ${reset}
-${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
-${magenta}        o_(")(")    ${reset}${dim}High-performance job queue for Bun${reset}
-
-${dim}─────────────────────────────────────────────────${reset}
-
-  ${green}●${reset} TCP    ${tcpDisplay}
-  ${green}●${reset} HTTP   ${httpDisplay}
-  ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
-  ${yellow}●${reset} TLS    ${tlsConfig ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
-  ${yellow}●${reset} Auth   ${authTokens ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
-  ${yellow}●${reset} Cloud  ${cloudConfig ? `${green}enabled${reset} ${dim}→ ${cloudConfig.url}${reset}` : `${dim}disabled${reset}`}
-
-${dim}─────────────────────────────────────────────────${reset}
-
-  ${dim}Press ${bold}Ctrl+C${reset}${dim} to stop${reset}
-`);
-    // Handle shutdown
-    const shutdown = () => {
-        serverLog.info('Shutting down...');
-        const doStop = async () => {
-            if (cloudAgent)
-                await cloudAgent.stop();
-            tcpServer.stop();
-            httpServer.stop();
-            qm.shutdown();
-            process.exit(0);
-        };
-        void doStop();
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
+    // Same full server as the bare `bunqueue` entry (shared bootstrap)
+    bootServer(mergedConfig, config);
 }

package/dist/cli/commands/webhook.js

@@ -4,15 +4,9 @@
  */
 import { parseArgs } from 'node:util';
 import { CommandError, requireArg } from './types';
-/** Valid webhook events */
-const VALID_EVENTS = [
-    'job.completed',
-    'job.failed',
-    'job.progress',
-    'job.active',
-    'job.waiting',
-    'job.delayed',
-];
+import { WEBHOOK_EVENTS } from '../../domain/types/webhook';
+/** Valid webhook events — canonical list shared with server/MCP validation */
+const VALID_EVENTS = WEBHOOK_EVENTS;
 /** Build a webhook subcommand */
 export function buildWebhookCommand(args) {
     const subcommand = args[0];

package/dist/cli/help.js

@@ -98,6 +98,8 @@ GLOBAL OPTIONS:
   -H, --host <host>               Server host (default: localhost)
   -p, --port <port>               TCP port (default: 6789)
   -t, --token <token>             Authentication token (env: BQ_TOKEN, BUNQUEUE_TOKEN)
+                                  Note: after \`pull\` / \`job wait\`, -t is their --timeout;
+                                  use --token there
   --tls                           Connect with TLS (verify with system CAs)
   --tls-ca <file>                 Trust a custom CA cert (implies --tls)
   --tls-no-verify                 TLS without cert verification (self-signed, dev only)
@@ -126,7 +128,7 @@ Options:
   --tcp-port <port>       TCP server port (default: 6789, env: TCP_PORT)
   --http-port <port>      HTTP server port (default: 6790, env: HTTP_PORT)
   --host <host>           Bind address (default: 0.0.0.0, env: HOST)
-  --data-path <path>      SQLite database path (env: DATA_PATH)
+  --data-path <path>      SQLite database path (env: BUNQUEUE_DATA_PATH, DATA_PATH)
   --auth-tokens <list>    Comma-separated auth tokens (env: AUTH_TOKENS)
   --tls-cert <file>       PEM certificate for native TLS (env: TLS_CERT_FILE)
   --tls-key <file>        PEM private key for native TLS (env: TLS_KEY_FILE)

package/dist/cli/index.js

@@ -5,7 +5,7 @@
  */
 import { runServer } from './commands/server';
 import { executeCommand } from './client';
-import { printHelp, printVersion } from './help';
+import { printHelp, printVersion, printPushHelp, printCronAddHelp } from './help';
 import { isBackupCommand, executeBackupCommand } from './commands/backup';
 import { runDoctor } from './commands/doctor';
 import { VERSION } from '../shared/version';
@@ -82,47 +82,110 @@ function buildTlsOption(state) {
     }
     return state.enabled ? true : undefined;
 }
+/**
+ * Exactly two subcommands define their own short `-t` (--timeout):
+ * `pull` and `job wait`. ONLY there `-t` is passed through instead of being
+ * consumed as the global token flag — every other command keeps `-t TOKEN`
+ * working anywhere on the line. The long form `--token` is global everywhere.
+ */
+function commandOwnsShortT(commandArgs) {
+    return commandArgs[0] === 'pull' || (commandArgs[0] === 'job' && commandArgs[1] === 'wait');
+}
+/**
+ * Handle `--token` / global `-t` and return the index to continue scanning
+ * from. When the command already parsed owns short `-t` (pull / job wait),
+ * the flag is passed through to the subcommand instead of being consumed.
+ */
+function applyTokenFlag(arg, allArgs, i, state, commandArgs) {
+    if (arg === '-t' && commandOwnsShortT(commandArgs)) {
+        commandArgs.push(arg); // pull / job wait own -t (timeout): pass through
+        return i;
+    }
+    const nextArg = allArgs[i + 1];
+    // A following flag is not a token: don't swallow it (--token --json ...)
+    if (nextArg === undefined || nextArg.startsWith('-')) {
+        console.warn('Warning: --token requires a value. Token not set.');
+        return i;
+    }
+    state.token = nextArg;
+    return i + 1;
+}
+/** Handle `--host`/`-H <value>`; refuses to swallow a following flag. */
+function applyHostFlag(allArgs, i, state) {
+    const nextArg = allArgs[i + 1];
+    if (nextArg === undefined || nextArg.startsWith('-')) {
+        console.warn('Warning: --host requires a value. Using localhost.');
+        return i;
+    }
+    state.host = nextArg;
+    state.hostExplicit = true;
+    return i + 1;
+}
+/** Handle `--port`/`-p <value>`; refuses to swallow a following flag. */
+function applyPortFlag(allArgs, i, state) {
+    const nextArg = allArgs[i + 1];
+    if (nextArg === undefined || nextArg.startsWith('-')) {
+        console.warn('Warning: --port requires a value. Using default port 6789.');
+        return i;
+    }
+    const parsed = parseInt(nextArg, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        console.warn(`Warning: Invalid port "${nextArg}". Using default port 6789.`);
+        state.port = 6789;
+    }
+    else {
+        state.port = parsed;
+        state.portExplicit = true;
+    }
+    return i + 1;
+}
+/**
+ * Attached-value short flags (-p10, -Hfoo) shadowing a global flag letter are
+ * silently mis-parsed downstream (strict:false expands them to garbage
+ * booleans — e.g. push -p10 dropped the priority and pushed anyway). Warn so
+ * the user switches to the separated/long form. Exception: -t<value> after
+ * pull/job wait, where parseArgs handles the attached form correctly.
+ */
+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.`);
+}
 /** Parse global options from process.argv */
 export function parseGlobalOptions() {
     const allArgs = process.argv.slice(2);
     // Extract global options manually to preserve subcommand flags
-    let host = 'localhost';
-    let port = 6789;
-    let token;
+    const hp = {
+        host: 'localhost',
+        port: 6789,
+        hostExplicit: false,
+        portExplicit: false,
+    };
+    const tokenState = {};
     let json = false;
     let help = false;
     let version = false;
-    let hostExplicit = false;
-    let portExplicit = false;
     const tlsState = { enabled: false, noVerify: false };
     const commandArgs = [];
     let i = 0;
     while (i < allArgs.length) {
         const arg = allArgs[i];
+        if (arg === '--') {
+            // Separator: everything after -- is opaque to the global parser
+            commandArgs.push(...allArgs.slice(i + 1));
+            break;
+        }
         if (arg === '--host' || arg === '-H') {
-            host = allArgs[++i] ?? 'localhost';
-            hostExplicit = true;
+            i = applyHostFlag(allArgs, i, hp);
         }
         else if (arg === '--port' || arg === '-p') {
-            const raw = allArgs[++i] ?? '6789';
-            const parsed = parseInt(raw, 10);
-            if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
-                console.warn(`Warning: Invalid port "${raw}". Using default port 6789.`);
-                port = 6789;
-            }
-            else {
-                port = parsed;
-                portExplicit = true;
-            }
+            i = applyPortFlag(allArgs, i, hp);
         }
         else if (arg === '--token' || arg === '-t') {
-            const nextArg = allArgs[i + 1];
-            if (nextArg === undefined) {
-                console.warn('Warning: --token requires a value. Token not set.');
-            }
-            else {
-                token = allArgs[++i];
-            }
+            i = applyTokenFlag(arg, allArgs, i, tokenState, commandArgs);
         }
         else if (arg.startsWith('--tls')) {
             i = applyTlsFlag(arg, allArgs, i, tlsState, commandArgs);
@@ -130,26 +193,28 @@ export function parseGlobalOptions() {
         else if (arg === '--json') {
             json = true;
         }
-        else if (arg === '--help' || arg === '-h') {
+        else if (arg === '--help' || (arg === '-h' && commandArgs.length === 0)) {
+            // Short -h is global help ONLY before the command: after it, a typo of
+            // -H (host) must not suppress execution with a false-success exit 0.
             help = true;
         }
-        else if (arg === '--version' || arg === '-v') {
+        else if (arg === '--version' || (arg === '-v' && commandArgs.length === 0)) {
             version = true;
         }
         else if (arg.startsWith('--host=')) {
-            host = arg.slice(7);
-            hostExplicit = true;
+            hp.host = arg.slice(7);
+            hp.hostExplicit = true;
         }
         else if (arg.startsWith('--port=')) {
             const raw = arg.slice(7);
             const parsed = parseInt(raw, 10);
             if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
                 console.warn(`Warning: Invalid port "${raw}". Using default port 6789.`);
-                port = 6789;
+                hp.port = 6789;
             }
             else {
-                port = parsed;
-                portExplicit = true;
+                hp.port = parsed;
+                hp.portExplicit = true;
             }
         }
         else if (arg.startsWith('--token=')) {
@@ -158,10 +223,11 @@ export function parseGlobalOptions() {
                 console.warn('Warning: --token= requires a value. Token not set.');
             }
             else {
-                token = val;
+                tokenState.token = val;
             }
         }
         else {
+            warnAmbiguousAttachedShort(arg, commandArgs);
             // Not a global option, pass to command
             commandArgs.push(arg);
         }
@@ -173,20 +239,18 @@ export function parseGlobalOptions() {
     // so they reach parseServerArgs in runServer().
     // Global -p/--port maps to --tcp-port for the server command.
     if (isServerMode) {
-        if (hostExplicit) {
-            commandArgs.push('--host', host);
+        if (hp.hostExplicit) {
+            commandArgs.push('--host', hp.host);
         }
-        if (portExplicit) {
-            commandArgs.push('--tcp-port', String(port));
+        if (hp.portExplicit) {
+            commandArgs.push('--tcp-port', String(hp.port));
         }
     }
     // Fall back to environment variables for token if not set via CLI flag
     // Priority: --token flag > BQ_TOKEN > BUNQUEUE_TOKEN
-    token = resolveToken(token);
-    if (!portExplicit)
-        port = resolveEnvPort(port);
-    if (!hostExplicit)
-        host = resolveEnvHost(host);
+    const token = resolveToken(tokenState.token);
+    const port = hp.portExplicit ? hp.port : resolveEnvPort(hp.port);
+    const host = hp.hostExplicit ? hp.host : resolveEnvHost(hp.host);
     return {
         options: { host, port, token, tls: buildTlsOption(tlsState), json, help, version },
         commandArgs,
@@ -236,8 +300,12 @@ export async function main() {
     }
     // Help for specific command
     if (options.help) {
-        // Could add command-specific help here
-        printHelp();
+        if (command === 'push')
+            printPushHelp();
+        else if (command === 'cron')
+            printCronAddHelp();
+        else
+            printHelp();
         process.exit(0);
     }
     // Version command - shows client version + server version if reachable

package/dist/cli/output.js

@@ -143,6 +143,15 @@ function formatStats(stats) {
         lines.push(`  Total Completed: ${str(stats.totalCompleted)}`);
         lines.push(`  Total Failed:    ${str(stats.totalFailed)}`);
     }
+    if (stats.uptime !== undefined) {
+        lines.push('', `  ${color('Uptime:', colors.cyan)}      ${str(stats.uptime)}s`);
+    }
+    if (stats.pushPerSec !== undefined) {
+        lines.push(`  Push/sec:    ${str(stats.pushPerSec)}`);
+    }
+    if (stats.pullPerSec !== undefined) {
+        lines.push(`  Pull/sec:    ${str(stats.pullPerSec)}`);
+    }
     return lines.join('\n');
 }
 /** Format counts object */
@@ -167,7 +176,17 @@ function formatCronJobs(jobs) {
         const schedule = job.schedule !== null && job.schedule !== undefined
             ? str(job.schedule)
             : `every ${str(job.repeatEvery)}ms`;
-        return `  ${color(str(job.name), colors.bold)}\n    Queue: ${str(job.queue)}\n    Schedule: ${schedule}\n    Executions: ${str(job.executions)}`;
+        let out = `  ${color(str(job.name), colors.bold)}\n    Queue: ${str(job.queue)}\n    Schedule: ${schedule}\n    Executions: ${str(job.executions)}`;
+        if (typeof job.nextRun === 'number') {
+            out += `\n    Next run: ${new Date(job.nextRun).toISOString()}`;
+        }
+        if (job.maxLimit !== null && job.maxLimit !== undefined) {
+            out += `\n    Max: ${str(job.maxLimit)}`;
+        }
+        if (job.timezone !== null && job.timezone !== undefined) {
+            out += `\n    Timezone: ${str(job.timezone)}`;
+        }
+        return out;
     });
     return lines.join('\n\n');
 }
@@ -177,7 +196,25 @@ function formatWorkers(workers) {
         return color('No workers registered', colors.yellow);
     }
     return workers
-        .map((w) => `  ${color(str(w.id), colors.bold)}: ${str(w.name)} (${Array.isArray(w.queues) ? w.queues.join(', ') : 'none'})`)
+        .map((w) => {
+        const queues = Array.isArray(w.queues) ? w.queues.join(', ') : 'none';
+        // status matters operationally: a stale worker must be visible
+        const status = w.status === 'stale'
+            ? color('[stale]', colors.red)
+            : w.status !== undefined
+                ? color(`[${str(w.status)}]`, colors.green)
+                : '';
+        const extra = [];
+        if (w.concurrency !== undefined)
+            extra.push(`concurrency=${str(w.concurrency)}`);
+        if (w.activeJobs !== undefined)
+            extra.push(`active=${str(w.activeJobs)}`);
+        if (w.processedJobs !== undefined) {
+            extra.push(`processed=${str(w.processedJobs)}/failed=${str(w.failedJobs, '0')}`);
+        }
+        const extraStr = extra.length > 0 ? `\n    ${extra.join(' ')}` : '';
+        return `  ${color(str(w.id), colors.bold)}: ${str(w.name)} ${status} (${queues})${extraStr}`;
+    })
         .join('\n');
 }
 /** Format webhooks list */
@@ -186,7 +223,15 @@ function formatWebhooks(webhooks) {
         return color('No webhooks registered', colors.yellow);
     }
     return webhooks
-        .map((w) => `  ${color(str(w.id), colors.bold)}: ${str(w.url)}\n    Events: ${w.events.join(', ')}`)
+        .map((w) => {
+        const events = Array.isArray(w.events) ? w.events.join(', ') : 'none';
+        const enabled = w.enabled === false ? ` ${color('[disabled]', colors.yellow)}` : '';
+        const queue = w.queue !== null && w.queue !== undefined ? `\n    Queue: ${str(w.queue)}` : '';
+        const counters = w.successCount !== undefined || w.failureCount !== undefined
+            ? `\n    Delivered: ${str(w.successCount, '0')} ok / ${str(w.failureCount, '0')} failed`
+            : '';
+        return `  ${color(str(w.id), colors.bold)}: ${str(w.url)}${enabled}\n    Events: ${events}${queue}${counters}`;
+    })
         .join('\n\n');
 }
 /** Format DLQ jobs */
@@ -300,6 +345,15 @@ function formatSuccess(response, command, subcommand) {
     // Worker registered
     if ('workerId' in r)
         return color(`Worker registered: ${str(r.workerId)}`, colors.green);
+    // Webhook added — show the id, it is needed for `webhook remove`
+    if ('webhookId' in r)
+        return color(`Webhook added: ${str(r.webhookId)}`, colors.green);
+    // Cron scheduled — surface nextRun
+    if ('cron' in r && r.cron !== null && typeof r.cron === 'object') {
+        const c = r.cron;
+        const next = typeof c.nextRun === 'number' ? ` (next run: ${new Date(c.nextRun).toISOString()})` : '';
+        return color(`Cron scheduled: ${str(c.name)}${next}`, colors.green);
+    }
     // State
     if ('state' in r)
         return `State: ${str(r.state)}`;

package/dist/domain/types/cron.js

@@ -16,7 +16,9 @@ export function createCronJob(input, nextRun) {
         timezone: input.timezone ?? null,
         nextRun,
         executions: 0,
-        maxLimit: input.maxLimit ?? null,
+        // 0/negative mean "no limit" on every surface (CLI/HTTP/TCP/MCP): storing
+        // 0 would make isAtLimit treat the cron as already exhausted (0 >= 0).
+        maxLimit: input.maxLimit !== undefined && input.maxLimit > 0 ? input.maxLimit : null,
         uniqueKey: input.uniqueKey ?? null,
         dedup: input.dedup ?? null,
         skipMissedOnRestart: input.skipMissedOnRestart ?? true,

package/dist/domain/types/webhook.d.ts

@@ -3,8 +3,18 @@
  */
 /** Webhook ID type */
 export type WebhookId = string;
-/** Webhook event types */
-export type WebhookEvent = 'job.pushed' | 'job.started' | 'job.completed' | 'job.failed' | 'job.progress' | 'job.stalled';
+/**
+ * Canonical list of webhook events the server actually triggers — single
+ * source of truth for CLI/TCP/HTTP/MCP validation. job.pushed/started/
+ * completed/failed flow through eventsManager.mapEventToWebhook; job.progress
+ * is triggered directly by updateProgress (jobManagement).
+ */
+export declare const WEBHOOK_EVENTS: readonly ["job.pushed", "job.started", "job.completed", "job.failed", "job.progress"];
+/**
+ * Webhook event types. Includes 'job.stalled' for backward compatibility with
+ * stored webhooks, but it is never emitted and not accepted on new ones.
+ */
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number] | 'job.stalled';
 /** Webhook configuration */
 export interface Webhook {
     id: WebhookId;

package/dist/domain/types/webhook.js

@@ -2,6 +2,19 @@
  * Webhook domain types
  */
 import { uuid } from '../../shared/hash';
+/**
+ * Canonical list of webhook events the server actually triggers — single
+ * source of truth for CLI/TCP/HTTP/MCP validation. job.pushed/started/
+ * completed/failed flow through eventsManager.mapEventToWebhook; job.progress
+ * is triggered directly by updateProgress (jobManagement).
+ */
+export const WEBHOOK_EVENTS = [
+    'job.pushed',
+    'job.started',
+    'job.completed',
+    'job.failed',
+    'job.progress',
+];
 /** Create a new webhook */
 export function createWebhook(url, events, queue, secret) {
     return {

package/dist/infrastructure/server/bootstrap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server bootstrap — the ONE place that boots a full bunqueue server.
+ * Used by both entry points (`bunqueue` bare via main.ts and
+ * `bunqueue start` via the CLI) so they cannot drift: S3 backup, cloud
+ * agent, stats interval, crash handlers and graceful shutdown are always on.
+ */
+import { type BunqueueConfig, type ResolvedConfig } from '../../config';
+/** Boot the full server from resolved configuration. Runs until shutdown. */
+export declare function bootServer(fileConfig: BunqueueConfig | null, config: ResolvedConfig): void;

package/dist/infrastructure/server/bootstrap.js

@@ -0,0 +1,217 @@
+/**
+ * Server bootstrap — the ONE place that boots a full bunqueue server.
+ * Used by both entry points (`bunqueue` bare via main.ts and
+ * `bunqueue start` via the CLI) so they cannot drift: S3 backup, cloud
+ * agent, stats interval, crash handlers and graceful shutdown are always on.
+ */
+import { QueueManager } from '../../application/queueManager';
+import { createTcpServer } from './tcp';
+import { createHttpServer } from './http';
+import { Logger, serverLog, statsLog } from '../../shared/logger';
+import { stopRateLimiter } from './rateLimiter';
+import { VERSION } from '../../shared/version';
+import { S3BackupManager } from '../backup';
+import { CloudAgent } from '../cloud';
+import { SHARD_COUNT } from '../../shared/hash';
+import { resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from '../../config';
+/** Print startup banner */
+function printBanner(config, cloudUrl) {
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    const bold = '\x1b[1m';
+    const magenta = '\x1b[35m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    // Format TCP endpoint display
+    const tcpDisplay = config.tcpSocketPath
+        ? `${bold}${config.tcpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.tcpPort}${reset}`;
+    // Format HTTP endpoint display
+    const httpDisplay = config.httpSocketPath
+        ? `${bold}${config.httpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.httpPort}${reset}`;
+    // Socket mode display
+    const hasUnixSockets = config.tcpSocketPath !== undefined || config.httpSocketPath !== undefined;
+    const socketDisplay = hasUnixSockets
+        ? `${green}enabled${reset} ${dim}(${config.tcpSocketPath ? 'TCP' : ''}${config.tcpSocketPath && config.httpSocketPath ? '+' : ''}${config.httpSocketPath ? 'HTTP' : ''})${reset}`
+        : `${dim}disabled${reset}`;
+    console.log(`
+${magenta}        (\\(\\        ${reset}
+${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
+${magenta}        o_(")(")    ${reset}${dim}High-performance job queue for Bun${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+  ${green}●${reset} TCP    ${tcpDisplay}
+  ${green}●${reset} HTTP   ${httpDisplay}
+  ${yellow}●${reset} Socket ${socketDisplay}
+  ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} TLS    ${config.tlsCertFile ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} Auth   ${config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} S3 Backup ${config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} Cloud  ${cloudUrl ? `${green}enabled${reset} ${dim}→ ${cloudUrl}${reset}` : `${dim}disabled${reset}`}
+  ${dim}●${reset} Shards ${bold}${SHARD_COUNT}${reset} ${dim}(${navigator.hardwareConcurrency} CPU cores)${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+`);
+}
+/** Boot the full server from resolved configuration. Runs until shutdown. */
+export function bootServer(fileConfig, config) {
+    // Apply logging config before anything else
+    const logFormat = fileConfig?.logging?.format ?? Bun.env.LOG_FORMAT;
+    const logLevel = fileConfig?.logging?.level ?? Bun.env.LOG_LEVEL?.toLowerCase();
+    if (logFormat === 'json')
+        Logger.enableJsonMode();
+    if (logLevel) {
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        if (validLevels.includes(logLevel))
+            Logger.setLevel(logLevel);
+    }
+    // Resolve cloud config
+    const cloudConfig = resolveCloudConfig(fileConfig, config.dataPath);
+    // Resolve TLS config — fail fast on partial cert/key before binding anything
+    let tlsConfig;
+    try {
+        tlsConfig = resolveTlsServerOptions(config);
+    }
+    catch (err) {
+        serverLog.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    printBanner(config, cloudConfig?.url);
+    // Create queue manager
+    const queueManager = new QueueManager({
+        dataPath: config.dataPath,
+    });
+    // Start TCP + HTTP servers; a bind failure must not leave a half-started process
+    let tcpServer;
+    let httpServer;
+    try {
+        tcpServer = createTcpServer(queueManager, {
+            port: config.tcpPort,
+            hostname: config.hostname,
+            authTokens: config.authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
+        });
+        httpServer = createHttpServer(queueManager, {
+            port: config.httpPort,
+            hostname: config.hostname,
+            socketPath: config.httpSocketPath,
+            authTokens: config.authTokens,
+            corsOrigins: config.corsOrigins,
+            requireAuthForMetrics: config.requireAuthForMetrics,
+            ...(tlsConfig && { tls: tlsConfig }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        console.error(`Failed to start server: ${msg}`);
+        queueManager.shutdown();
+        process.exit(1);
+    }
+    // Initialize S3 backup manager
+    let backupManager = null;
+    if (config.dataPath) {
+        const backupConfig = resolveBackupConfig(fileConfig, config.dataPath);
+        backupManager = new S3BackupManager(backupConfig);
+        backupManager.setDashboardEmit(queueManager.emitDashboardEvent.bind(queueManager));
+        backupManager.start();
+    }
+    // Initialize bunqueue Cloud agent (remote dashboard telemetry)
+    const cloudAgent = cloudConfig ? CloudAgent.createFromConfig(queueManager, cloudConfig) : null;
+    if (cloudAgent) {
+        cloudAgent.setServerHandles({
+            getConnectionCount: () => tcpServer.getConnectionCount(),
+            getWsClientCount: () => httpServer.getWsClientCount(),
+            getSseClientCount: () => httpServer.getSseClientCount(),
+            getBackupStatus: () => backupManager?.getStatus() ?? null,
+        });
+    }
+    queueManager.emitDashboardEvent('server:started', {
+        tcpPort: config.tcpPort,
+        httpPort: config.httpPort,
+        shards: SHARD_COUNT,
+    });
+    // Graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        serverLog.info(`Received ${signal}, shutting down...`);
+        // Stop stats interval immediately
+        clearInterval(statsInterval);
+        tcpServer.stop();
+        httpServer.stop();
+        const shutdownTimeout = config.shutdownTimeoutMs;
+        const start = Date.now();
+        while (Date.now() - start < shutdownTimeout) {
+            const stats = queueManager.getStats();
+            if (stats.active === 0)
+                break;
+            serverLog.info(`Waiting for ${stats.active} active jobs...`);
+            await Bun.sleep(1000);
+        }
+        // Stop backup manager
+        if (backupManager) {
+            backupManager.stop();
+        }
+        // Stop Cloud agent (sends final shutdown snapshot)
+        if (cloudAgent) {
+            await cloudAgent.stop();
+        }
+        queueManager.emitDashboardEvent('server:shutdown', { signal });
+        queueManager.shutdown();
+        stopRateLimiter();
+        serverLog.info('Shutdown complete');
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('uncaughtException', (err) => {
+        serverLog.error('Uncaught exception - initiating shutdown', {
+            error: err.message,
+            stack: err.stack,
+        });
+        void shutdown('uncaughtException');
+    });
+    process.on('unhandledRejection', (reason) => {
+        serverLog.error('Unhandled promise rejection - initiating shutdown', {
+            reason: reason instanceof Error ? reason.message : String(reason),
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
+        void shutdown('unhandledRejection');
+    });
+    // Print stats periodically
+    const statsInterval = setInterval(() => {
+        const stats = queueManager.getStats();
+        const memStats = queueManager.getMemoryStats();
+        const workerStats = queueManager.workerManager.getStats();
+        const mem = process.memoryUsage();
+        const now = new Date();
+        const timestamp = now.toLocaleTimeString('en-GB', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+        statsLog.info('Queue statistics', {
+            time: timestamp,
+            waiting: stats.waiting,
+            active: stats.active,
+            delayed: stats.delayed,
+            completed: stats.completed,
+            dlq: stats.dlq,
+            tcp: tcpServer.getConnectionCount(),
+            ws: httpServer.getWsClientCount(),
+            sse: httpServer.getSseClientCount(),
+            workers: `${workerStats.active}/${workerStats.total}`,
+            mem: `${Math.round(mem.heapUsed / 1024 / 1024)}MB/${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
+            rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
+            // Internal collection sizes (for memory debugging)
+            idx: memStats.jobIndex,
+            locks: memStats.jobLocks,
+            clients: memStats.clientJobsTotal,
+        });
+    }, config.statsIntervalMs);
+}

package/dist/infrastructure/server/handlers/advanced.js

@@ -4,6 +4,7 @@
  */
 import * as resp from '../../../domain/types/response';
 import { jobId } from '../../../domain/types/job';
+import { validateNumericField } from '../protocol';
 /**
  * Coerce a value to a finite number, or return undefined if it can't be.
  * Guards config endpoints against non-numeric input (e.g. `"abc"`) that would
@@ -108,6 +109,13 @@ export async function handleDiscard(cmd, ctx, reqId) {
 /** Handle WaitJob command - wait for job completion (event-driven, no polling) */
 export async function handleWaitJob(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
+    // Bounded like PULL (which caps at 60s); waiting for completion is
+    // legitimately longer, so the cap here is 10 min. validateNumericField also
+    // rejects NaN/Infinity from hostile clients (a hand-rolled <0/>max check
+    // would let NaN through and resolve instantly as a false "not completed").
+    const timeoutError = validateNumericField(cmd.timeout, 'timeout', { min: 0, max: 600000 });
+    if (timeoutError)
+        return resp.error(timeoutError, reqId);
     const timeout = cmd.timeout ?? 30000;
     // First check if job exists and is already completed
     const job = await ctx.queueManager.getJob(jid);

package/dist/infrastructure/server/handlers/monitoring.js

@@ -6,6 +6,7 @@ import { jobId } from '../../../domain/types/job';
 import { VERSION } from '../../../shared/version';
 import * as resp from '../../../domain/types/response';
 import { validateWebhookUrl } from '../protocol';
+import { WEBHOOK_EVENTS } from '../../../domain/types/webhook';
 // ============ Job Logs ============
 export function handleAddLog(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
@@ -140,6 +141,12 @@ export function handleAddWebhook(cmd, ctx, reqId) {
     const urlError = validateWebhookUrl(cmd.url);
     if (urlError)
         return resp.error(urlError, reqId);
+    // Reject events that are never triggered — a webhook subscribed to a dead
+    // event would be created "ok" and then never fire (silent failure).
+    const invalidEvents = cmd.events.filter((e) => !WEBHOOK_EVENTS.includes(e));
+    if (invalidEvents.length > 0) {
+        return resp.error(`Invalid webhook event(s): ${invalidEvents.join(', ')}. Valid: ${WEBHOOK_EVENTS.join(', ')}`, reqId);
+    }
     const webhook = ctx.queueManager.webhookManager.add(cmd.url, cmd.events, cmd.queue, cmd.secret);
     ctx.queueManager.emitDashboardEvent('webhook:added', {
         id: webhook.id,

package/dist/main.js

@@ -8,241 +8,29 @@
 // module; without this guard, the top-level dispatch would re-run the CLI/server
 // on every import and cause "Failed to listen at 0.0.0.0".
 if (import.meta.main) {
-    const clientCommands = [
-        'push',
-        'pull',
-        'ack',
-        'fail',
-        'job',
-        'queue',
-        'dlq',
-        'cron',
-        'worker',
-        'webhook',
-        'rate-limit',
-        'concurrency',
-        'stats',
-        'metrics',
-        'health',
-        'backup',
-    ];
     const firstArg = process.argv[2];
-    const isClientCommand = firstArg && clientCommands.includes(firstArg);
-    const isStartCommand = firstArg === 'start';
-    const hasHelpOrVersion = process.argv.includes('--help') || process.argv.includes('--version');
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- process.argv[2] can be undefined at runtime
-    const hasFlags = firstArg?.startsWith('-');
-    if (isClientCommand || hasHelpOrVersion || isStartCommand || hasFlags) {
-        void import('./cli/index').then(({ main }) => main());
+    // The server boots ONLY for a bare `bunqueue` invocation. `start` and
+    // flag-led argv go through the CLI, which detects server mode itself and
+    // boots the same full server (shared bootstrap). Every other first argument
+    // is a CLI command: known ones execute, unknown ones print
+    // "Unknown command: X" and exit 1 — a typo must never silently boot a server.
+    if (!firstArg) {
+        void startServer();
     }
     else {
-        void startServer();
+        void import('./cli/index').then(({ main }) => main());
     }
 }
-import { QueueManager } from './application/queueManager';
-import { createTcpServer } from './infrastructure/server/tcp';
-import { createHttpServer } from './infrastructure/server/http';
-import { Logger, serverLog, statsLog } from './shared/logger';
-import { stopRateLimiter } from './infrastructure/server/rateLimiter';
-import { VERSION } from './shared/version';
-import { S3BackupManager } from './infrastructure/backup';
-import { CloudAgent } from './infrastructure/cloud';
-import { SHARD_COUNT } from './shared/hash';
-import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from './config';
+import { Logger } from './shared/logger';
+import { loadConfigFile, resolveServerConfig } from './config';
+import { bootServer } from './infrastructure/server/bootstrap';
 export { defineConfig } from './config';
-/** Print startup banner */
-function printBanner(config, cloudUrl) {
-    const dim = '\x1b[2m';
-    const reset = '\x1b[0m';
-    const bold = '\x1b[1m';
-    const magenta = '\x1b[35m';
-    const green = '\x1b[32m';
-    const yellow = '\x1b[33m';
-    // Format TCP endpoint display
-    const tcpDisplay = config.tcpSocketPath
-        ? `${bold}${config.tcpSocketPath}${reset} ${dim}(unix)${reset}`
-        : `${bold}${config.hostname}:${config.tcpPort}${reset}`;
-    // Format HTTP endpoint display
-    const httpDisplay = config.httpSocketPath
-        ? `${bold}${config.httpSocketPath}${reset} ${dim}(unix)${reset}`
-        : `${bold}${config.hostname}:${config.httpPort}${reset}`;
-    // Socket mode display
-    const hasUnixSockets = config.tcpSocketPath !== undefined || config.httpSocketPath !== undefined;
-    const socketDisplay = hasUnixSockets
-        ? `${green}enabled${reset} ${dim}(${config.tcpSocketPath ? 'TCP' : ''}${config.tcpSocketPath && config.httpSocketPath ? '+' : ''}${config.httpSocketPath ? 'HTTP' : ''})${reset}`
-        : `${dim}disabled${reset}`;
-    console.log(`
-${magenta}        (\\(\\        ${reset}
-${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
-${magenta}        o_(")(")    ${reset}${dim}High-performance job queue for Bun${reset}
-
-${dim}─────────────────────────────────────────────────${reset}
-
-  ${green}●${reset} TCP    ${tcpDisplay}
-  ${green}●${reset} HTTP   ${httpDisplay}
-  ${yellow}●${reset} Socket ${socketDisplay}
-  ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
-  ${yellow}●${reset} TLS    ${config.tlsCertFile ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
-  ${yellow}●${reset} Auth   ${config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
-  ${yellow}●${reset} S3 Backup ${config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
-  ${yellow}●${reset} Cloud  ${cloudUrl ? `${green}enabled${reset} ${dim}→ ${cloudUrl}${reset}` : `${dim}disabled${reset}`}
-  ${dim}●${reset} Shards ${bold}${SHARD_COUNT}${reset} ${dim}(${navigator.hardwareConcurrency} CPU cores)${reset}
-
-${dim}─────────────────────────────────────────────────${reset}
-
-`);
-}
 /** Start the server (direct mode) */
 async function startServer() {
     // Load config file (bunqueue.config.ts) if present, then merge with env vars
     const fileConfig = await loadConfigFile();
     const config = resolveServerConfig(fileConfig);
-    // Apply logging config before anything else
-    const logFormat = fileConfig?.logging?.format ?? Bun.env.LOG_FORMAT;
-    const logLevel = fileConfig?.logging?.level ?? Bun.env.LOG_LEVEL?.toLowerCase();
-    if (logFormat === 'json')
-        Logger.enableJsonMode();
-    if (logLevel) {
-        const validLevels = ['debug', 'info', 'warn', 'error'];
-        if (validLevels.includes(logLevel))
-            Logger.setLevel(logLevel);
-    }
-    // Resolve cloud config
-    const cloudConfig = resolveCloudConfig(fileConfig, config.dataPath);
-    // Resolve TLS config — fail fast on partial cert/key before binding anything
-    let tlsConfig;
-    try {
-        tlsConfig = resolveTlsServerOptions(config);
-    }
-    catch (err) {
-        serverLog.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-    printBanner(config, cloudConfig?.url);
-    // Create queue manager
-    const queueManager = new QueueManager({
-        dataPath: config.dataPath,
-    });
-    // Start TCP server
-    const tcpServer = createTcpServer(queueManager, {
-        port: config.tcpPort,
-        hostname: config.hostname,
-        authTokens: config.authTokens,
-        ...(tlsConfig && { tls: tlsConfig }),
-    });
-    // Start HTTP server
-    const httpServer = createHttpServer(queueManager, {
-        port: config.httpPort,
-        hostname: config.hostname,
-        authTokens: config.authTokens,
-        corsOrigins: config.corsOrigins,
-        requireAuthForMetrics: config.requireAuthForMetrics,
-        ...(tlsConfig && { tls: tlsConfig }),
-    });
-    // Initialize S3 backup manager
-    let backupManager = null;
-    if (config.dataPath) {
-        const backupConfig = resolveBackupConfig(fileConfig, config.dataPath);
-        backupManager = new S3BackupManager(backupConfig);
-        backupManager.setDashboardEmit(queueManager.emitDashboardEvent.bind(queueManager));
-        backupManager.start();
-    }
-    // Initialize bunqueue Cloud agent (remote dashboard telemetry)
-    const cloudAgent = cloudConfig ? CloudAgent.createFromConfig(queueManager, cloudConfig) : null;
-    if (cloudAgent) {
-        cloudAgent.setServerHandles({
-            getConnectionCount: () => tcpServer.getConnectionCount(),
-            getWsClientCount: () => httpServer.getWsClientCount(),
-            getSseClientCount: () => httpServer.getSseClientCount(),
-            getBackupStatus: () => backupManager?.getStatus() ?? null,
-        });
-    }
-    queueManager.emitDashboardEvent('server:started', {
-        tcpPort: config.tcpPort,
-        httpPort: config.httpPort,
-        shards: SHARD_COUNT,
-    });
-    // Graceful shutdown
-    let shuttingDown = false;
-    const shutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        serverLog.info(`Received ${signal}, shutting down...`);
-        // Stop stats interval immediately
-        clearInterval(statsInterval);
-        tcpServer.stop();
-        httpServer.stop();
-        const shutdownTimeout = config.shutdownTimeoutMs;
-        const start = Date.now();
-        while (Date.now() - start < shutdownTimeout) {
-            const stats = queueManager.getStats();
-            if (stats.active === 0)
-                break;
-            serverLog.info(`Waiting for ${stats.active} active jobs...`);
-            await Bun.sleep(1000);
-        }
-        // Stop backup manager
-        if (backupManager) {
-            backupManager.stop();
-        }
-        // Stop Cloud agent (sends final shutdown snapshot)
-        if (cloudAgent) {
-            await cloudAgent.stop();
-        }
-        queueManager.emitDashboardEvent('server:shutdown', { signal });
-        queueManager.shutdown();
-        stopRateLimiter();
-        serverLog.info('Shutdown complete');
-        process.exit(0);
-    };
-    process.on('SIGINT', () => void shutdown('SIGINT'));
-    process.on('SIGTERM', () => void shutdown('SIGTERM'));
-    process.on('uncaughtException', (err) => {
-        serverLog.error('Uncaught exception - initiating shutdown', {
-            error: err.message,
-            stack: err.stack,
-        });
-        void shutdown('uncaughtException');
-    });
-    process.on('unhandledRejection', (reason) => {
-        serverLog.error('Unhandled promise rejection - initiating shutdown', {
-            reason: reason instanceof Error ? reason.message : String(reason),
-            stack: reason instanceof Error ? reason.stack : undefined,
-        });
-        void shutdown('unhandledRejection');
-    });
-    // Print stats periodically
-    const statsInterval = setInterval(() => {
-        const stats = queueManager.getStats();
-        const memStats = queueManager.getMemoryStats();
-        const workerStats = queueManager.workerManager.getStats();
-        const mem = process.memoryUsage();
-        const now = new Date();
-        const timestamp = now.toLocaleTimeString('en-GB', {
-            hour: '2-digit',
-            minute: '2-digit',
-            second: '2-digit',
-        });
-        statsLog.info('Queue statistics', {
-            time: timestamp,
-            waiting: stats.waiting,
-            active: stats.active,
-            delayed: stats.delayed,
-            completed: stats.completed,
-            dlq: stats.dlq,
-            tcp: tcpServer.getConnectionCount(),
-            ws: httpServer.getWsClientCount(),
-            sse: httpServer.getSseClientCount(),
-            workers: `${workerStats.active}/${workerStats.total}`,
-            mem: `${Math.round(mem.heapUsed / 1024 / 1024)}MB/${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
-            rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
-            // Internal collection sizes (for memory debugging)
-            idx: memStats.jobIndex,
-            locks: memStats.jobLocks,
-            clients: memStats.clientJobsTotal,
-        });
-    }, config.statsIntervalMs);
+    bootServer(fileConfig, config);
 }
 // Logger env-var bootstrap only applies when this file is the entry point.
 // Imported consumers (e.g. user config files using `defineConfig`) must not

package/dist/mcp/tools/webhookTools.js

@@ -4,19 +4,11 @@
  */
 import { z } from 'zod';
 import { withErrorHandler } from './withErrorHandler';
+import { WEBHOOK_EVENTS } from '../../domain/types/webhook';
 export function registerWebhookTools(server, backend) {
     server.tool('bunqueue_add_webhook', 'Add a webhook to receive notifications for job events.', {
         url: z.string().url().describe('Webhook URL to receive POST requests'),
-        events: z
-            .array(z.enum([
-            'job.completed',
-            'job.failed',
-            'job.progress',
-            'job.active',
-            'job.waiting',
-            'job.delayed',
-        ]))
-            .describe('Events to subscribe to'),
+        events: z.array(z.enum(WEBHOOK_EVENTS)).describe('Events to subscribe to'),
         queue: z.string().optional().describe('Limit to a specific queue (omit for all queues)'),
     }, withErrorHandler('bunqueue_add_webhook', async ({ url, events, queue }) => {
         const webhook = await backend.addWebhook(url, events, queue);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.9",
+  "version": "2.8.10",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
   "type": "module",
   "main": "dist/main.js",