@warlock.js/queue 5.13.0 → 5.15.0

package/esm/queue-dashboard-unguarded.error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-dashboard-unguarded.error.mjs","names":[],"sources":["../../../../../../queue/src/queue-dashboard-unguarded.error.ts"],"sourcesContent":["/**\n * Thrown at boot when `queue.dashboard.enabled` is `true` in production with\n * no guard middleware. The dashboard can retry and delete jobs; mounting it\n * on the open internet without a guard is a production incident waiting to\n * happen, so this fails the boot instead of shipping the hole.\n */\nexport class QueueDashboardUnguardedError extends Error {\n  public constructor() {\n    super(\n      \"queue.dashboard.enabled is true in production with no middleware. The dashboard can \" +\n        \"retry and delete jobs, so it must be guarded before it is exposed.\\n\\n\" +\n        \"Add a guard middleware:\\n\\n\" +\n        \"  import { middleware } from \\\"@warlock.js/core\\\";\\n\" +\n        \"  import { authMiddleware } from \\\"@warlock.js/auth\\\";\\n\\n\" +\n        \"  const queueConfig: QueueConfig = {\\n\" +\n        \"    // ...\\n\" +\n        \"    dashboard: {\\n\" +\n        \"      enabled: true,\\n\" +\n        \"      middleware: [authMiddleware(\\\"admin\\\")],\\n\" +\n        \"    },\\n\" +\n        \"  };\\n\",\n    );\n    this.name = \"QueueDashboardUnguardedError\";\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,+BAAb,cAAkD,MAAM;CACtD,AAAO,cAAc;EACnB,MACE,6bAYF;EACA,KAAK,OAAO;CACd;AACF"}

package/esm/types.d.mts

@@ -1,4 +1,5 @@
 import { ConnectionOptions } from "bullmq";
+import { Middleware } from "@warlock.js/core";
 
 //#region ../queue/src/types.d.ts
 /** Units accepted in a {@link Duration} string. */
@@ -47,6 +48,21 @@ type QueueWorkersConfig = {
    */
   shutdownTimeout?: number;
 };
+/**
+ * The bull-board dashboard, mounted automatically by `queueConnector()` when
+ * `enabled` is `true`. Equivalent to calling `queueDashboard()` yourself at
+ * boot, driven by config instead — see `warlock add bull-board`.
+ */
+type QueueDashboardConfig = {
+  /** Mount the dashboard at boot. Default `false`. */enabled?: boolean; /** URL path the dashboard is mounted on. Default `"/admin/queues"`. */
+  path?: string;
+  /**
+   * Run before every dashboard route — this is how the dashboard is guarded.
+   * The dashboard can retry and delete jobs, so `NODE_ENV === "production"`
+   * with an empty list throws `QueueDashboardUnguardedError` at boot.
+   */
+  middleware?: Middleware[];
+};
 /**
  * The `queue` configuration key — `src/config/queue.ts`.
  */
@@ -59,7 +75,8 @@ type QueueConfig = {
   prefix?: string; /** Queue name used when a job does not name one. Default `"default"`. */
   defaultQueue?: string; /** Defaults merged under every job's own options. */
   defaultJobOptions?: JobOptions; /** In-process workers. */
-  workers?: QueueWorkersConfig;
+  workers?: QueueWorkersConfig; /** The bull-board job dashboard. */
+  dashboard?: QueueDashboardConfig;
 };
 /** A progress value: a number (e.g. a percentage) or a JSON object. */
 type JobProgress = number | Record<string, unknown>;
@@ -145,5 +162,5 @@ type QueueJob<TPayload, TResult = unknown> = {
   find(id: string): Promise<JobSnapshot<TPayload, TResult> | undefined>;
 };
 //#endregion
-export { DispatchOptions, DispatchedJob, Duration, DurationUnit, FailedJob, JobBackoff, JobContext, JobDefinition, JobOptions, JobProgress, JobRetention, JobSnapshot, JobState, QueueConfig, QueueJob, QueueWorkersConfig };
+export { DispatchOptions, DispatchedJob, Duration, DurationUnit, FailedJob, JobBackoff, JobContext, JobDefinition, JobOptions, JobProgress, JobRetention, JobSnapshot, JobState, QueueConfig, QueueDashboardConfig, QueueJob, QueueWorkersConfig };
 //# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../queue/src/types.ts"],"mappings":";;;;KAGY,YAAA;AAAZ;;;;AAAA,KAMY,QAAA,wBAAgC,YAAY;AAAxD;;;;AAAA,KAMY,UAAA;EAAA,uFAIN,IAAA;EAEA,KAAK;AAAA;AAOX;;;;AAAA,KAAY,YAAA;AAMZ;;;;AAAA,KAAY,UAAA;EAQK,kEANf,QAAA,WAM2B;EAJ3B,OAAA,GAAU,UAAA,EAAV;EAEA,gBAAA,GAAmB,YAAA,EAAnB;EAEA,YAAA,GAAe,YAAA;AAAA;;;AAAY;KAMjB,kBAAA;EAAkB;;;;EAK5B,OAAA,YAOA;EALA,WAAA;EAKe;AAMjB;;;EANE,eAAA;AAAA;;;;KAMU,WAAA;EAKE;;;;EAAZ,UAAA,EAAY,iBAAA,EAQZ;EANA,MAAA,WAM4B;EAJ5B,YAAA,WAQU;EANV,iBAAA,GAAoB,UAAA;EAEpB,OAAA,GAAU,kBAAA;AAAA;AASZ;AAAA,KALY,WAAA,YAAuB,MAAM;;;;KAK7B,UAAA;EAcgB,kBAZ1B,EAAA;EAEA,IAAA,UAEA;EAAA,KAAA,UAIA;EAFA,OAAA,UAIgB;EAFhB,WAAA,UAE8B;EAA9B,QAAA,CAAS,KAAA,EAAO,WAAA,GAAc,OAAA,QAE1B;EAAJ,GAAA,CAAI,IAAA,WAAe,OAAA;AAAA;AAAO;AAM5B;;AAN4B,KAMhB,aAAA,sBAAmC,UAAA;EAAA,+CAE7C,IAAA,UAImC;EAFnC,KAAA,WAEgD;EAAhD,MAAA,CAAO,OAAA,EAAS,QAAA,EAAU,OAAA,EAAS,UAAA,GAAa,OAAA,CAAQ,OAAA,IAAW,OAAA;AAAA;;;;KAMzD,eAAA;EAVV,6CAYA,KAAA,GAAQ,QAAA;EARR;;;;EAaA,QAAA;EAbgD;;;;EAkBhD,KAAA,WAZU;EAcV,QAAA;EAEA,OAAA,GAAU,UAAU;AAAA;;KAIV,aAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;AAAA;;KAIU,QAAA;AAPZ;AAAA,KAkBY,WAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA,EAAO,QAAA;EACP,OAAA,EAAS,QAAA;EACT,QAAA,EAAU,WAAA;EACV,YAAA;EACA,MAAA,GAAS,OAAA;EACT,YAAA;EACA,SAAA,EAAW,IAAA;EACX,UAAA,GAAa,IAAA;AAAA;AAXf;AAAA,KAeY,SAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,OAAA,EAAS,QAAA;EACT,YAAA;EACA,YAAA;EACA,UAAA;EACA,QAAA,GAAW,IAAA,EAZM;EAcjB,KAAA,IAAS,OAAA;AAAA;;;;KAMC,QAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAA,UA5BA;EA8BT,QAAA,CAAS,OAAA,EAAS,QAAA,EAAU,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,aAAA,GA7BtD;EA+BV,IAAA,CAAK,EAAA,WAAa,OAAA,CAAQ,WAAA,CAAY,QAAA,EAAU,OAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../queue/src/types.ts"],"mappings":";;;;;KAIY,YAAA;AAAZ;;;;AAAA,KAMY,QAAA,wBAAgC,YAAY;AAAxD;;;;AAAA,KAMY,UAAA;EAAA,uFAIN,IAAA;EAEA,KAAK;AAAA;AAOX;;;;AAAA,KAAY,YAAA;AAMZ;;;;AAAA,KAAY,UAAA;EAQK,kEANf,QAAA,WAM2B;EAJ3B,OAAA,GAAU,UAAA,EAAV;EAEA,gBAAA,GAAmB,YAAA,EAAnB;EAEA,YAAA,GAAe,YAAA;AAAA;;;AAAY;KAMjB,kBAAA;EAAkB;;;;EAK5B,OAAA,YAOA;EALA,WAAA;EAKe;AAQjB;;;EARE,eAAA;AAAA;;;;;AAkBuB;KAVb,oBAAA;EAgBW,oDAdrB,OAAA,YAmBY;EAjBZ,IAAA;EAyBU;;;;;EAnBV,UAAA,GAAa,UAAU;AAAA;;;;KAMb,WAAA;EAaA;;;;EARV,UAAA,EAAY,iBAAA,EAcF;EAZV,MAAA;EAEA,YAAA,WAUuC;EARvC,iBAAA,GAAoB,UAAA,EAaA;EAXpB,OAAA,GAAU,kBAAA,EAuBM;EArBhB,SAAA,GAAY,oBAAA;AAAA;;KAIF,WAAA,YAAuB,MAAM;;;;KAK7B,UAAA;EAUV,kBARA,EAAA,UAUgB;EARhB,IAAA,UAQ8B;EAN9B,KAAA,UAQI;EANJ,OAAA,UAM0B;EAJ1B,WAAA,UAUU;EARV,QAAA,CAAS,KAAA,EAAO,WAAA,GAAc,OAAA,QAQP;EANvB,GAAA,CAAI,IAAA,WAAe,OAAA;AAAA;;;;KAMT,aAAA,sBAAmC,UAAA;EAM6B,+CAJ1E,IAAA,UAFwB;EAIxB,KAAA,WAJ6C;EAM7C,MAAA,CAAO,OAAA,EAAS,QAAA,EAAU,OAAA,EAAS,UAAA,GAAa,OAAA,CAAQ,OAAA,IAAW,OAAA;AAAA;;;;KAMzD,eAAA;EANgB,6CAQ1B,KAAA,GAAQ,QAAA;EARgD;;;AAAkB;EAa1E,QAAA;EAPyB;;;;EAYzB,KAAA,WALA;EAOA,QAAA;EAEA,OAAA,GAAU,UAAU;AAAA;;KAIV,aAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;AAAA;;KAIU,QAAA;;KAWA,WAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA,EAAO,QAAA;EACP,OAAA,EAAS,QAAA;EACT,QAAA,EAAU,WAAA;EACV,YAAA;EACA,MAAA,GAAS,OAAA;EACT,YAAA;EACA,SAAA,EAAW,IAAA;EACX,UAAA,GAAa,IAAA;AAAA;;KAIH,SAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,OAAA,EAAS,QAAA;EACT,YAAA;EACA,YAAA;EACA,UAAA;EACA,QAAA,GAAW,IAAA,EAnBX;EAqBA,KAAA,IAAS,OAAA;AAAA;;;;KAMC,QAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAA,UAxBT;EA0BA,QAAA,CAAS,OAAA,EAAS,QAAA,EAAU,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,aAAA,GAzBrD;EA2BX,IAAA,CAAK,EAAA,WAAa,OAAA,CAAQ,WAAA,CAAY,QAAA,EAAU,OAAA;AAAA"}

package/llms-full.txt

@@ -62,6 +62,10 @@ process.on("SIGTERM", () => closeQueue());
 
 Every process must use the same `prefix`, or they will not see each other's jobs.
 
+## Dashboard
+
+`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).
+
 
 ## define-jobs  `@warlock.js/queue/define-jobs/SKILL.md`
 
@@ -122,7 +126,7 @@ const job = await sendInvoice.find(id);
 
 ---
 name: manage-failed-jobs
-description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the optional bull-board UI via `queueDashboard(server, { basePath, queues })` — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
+description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
 ---
 
 # Failed jobs
@@ -145,19 +149,48 @@ await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if n
 ## Dashboard (optional)
 
 ```sh
-npm install @bull-board/api @bull-board/fastify
+warlock add bull-board
 ```
 
+This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+const queueConfig: QueueConfig = {
+  // ...
+  dashboard: {
+    enabled: true,
+    path: "/admin/queues", // default
+    middleware: [authMiddleware("admin")], // guards every dashboard route
+  },
+};
+
+export default queueConfig;
+```
+
+- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
+- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
+
+### Advanced: manual `queueDashboard()`
+
+For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
+
 ```ts
 import { getHttpServer } from "@warlock.js/core";
 import { queueDashboard } from "@warlock.js/queue";
 
-await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+await queueDashboard(getHttpServer(), {
+  basePath: "/admin/queues",
+  middleware: [authMiddleware("admin")],
+});
 ```
 
 - Call it before the HTTP server starts listening.
 - Shows every queue that has a job, plus the default queue, unless you pass `queues`.
-- It has no authentication of its own, and it can retry and delete jobs. Protect the path.
+- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.
 
 
 ## overview  `@warlock.js/queue/overview/SKILL.md`
@@ -187,30 +220,31 @@ Durable background jobs. Jobs are stored in **Redis** (required), retried on fai
 - [`configure-queue`](@warlock.js/queue/configure-queue/SKILL.md) — `src/config/queue.ts`, `queueConnector()`, workers on/off, shutdown.
 - [`define-jobs`](@warlock.js/queue/define-jobs/SKILL.md) — `defineJob`, `dispatch` options, retries, progress, `find`.
 - [`manage-failed-jobs`](@warlock.js/queue/manage-failed-jobs/SKILL.md) — `failedJobs`, `retryFailedJob`, the bull-board dashboard.
-- [`queue-notifications`](@warlock.js/queue/queue-notifications/SKILL.md) — `queueNotificationDispatcher()` for notifications `.queue()`.
+- [`queue-notifications`](@warlock.js/queue/queue-notifications/SKILL.md) — `bullmqQueue()` for notifications `.queue()`.
 
 
 ## queue-notifications  `@warlock.js/queue/queue-notifications/SKILL.md`
 
 ---
 name: queue-notifications
-description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `queueNotificationDispatcher({ queue?, attempts?, backoff? })` from `@warlock.js/queue/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Notifications keeps no queue dependency. Triggers: `queueNotificationDispatcher`, `@warlock.js/queue/notifications`, `NotificationConfig.queue`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
+description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
 ---
 
 # Queue notifications with BullMQ
 
 ```ts title="src/config/notifications.ts"
-import { type NotificationConfig, mailChannel } from "@warlock.js/notifications";
-import { queueNotificationDispatcher } from "@warlock.js/queue/notifications";
+import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
 
 const config: NotificationConfig = {
   channels: { mail: mailChannel() },
-  queue: queueNotificationDispatcher({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
 };
 
 export default config;
 ```
 
+`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
+
 Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
 
 ```ts
@@ -226,4 +260,6 @@ await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10
 - Channel not configured in the worker → fails at once, no retries.
 - Deliveries run under the job name `warlock.notifications.deliver`.
 
+> **Deprecated:** `queueNotificationDispatcher` from `@warlock.js/queue/notifications` still works this release (it logs a one-time deprecation warning) and is removed next release. Migrate to `bullmqQueue` above — same option names (`queue`, `attempts`, `backoff`).
+
 

package/llms.txt

@@ -8,6 +8,6 @@
 
 - [configure-queue](@warlock.js/queue/configure-queue/SKILL.md): Configure `@warlock.js/queue`: the declarative `src/config/queue.ts` (`QueueConfig` — `connection`, `prefix`, `defaultQueue`, `defaultJobOptions`, `workers: { enabled, concurrency, shutdownTimeout }`), registering `queueConnector()` in `warlock.config.ts > connectors`, running a dispatch-only process, and graceful shutdown. Programmatic `setQueueConfig` / `startWorkers` / `closeQueue` for scripts and tests. Triggers: `QueueConfig`, `queueConnector`, `setQueueConfig`, `startWorkers`, `closeQueue`, `workers.enabled`, `shutdownTimeout`; "configure the queue", "connect BullMQ to Redis", "disable workers in the web process", "graceful shutdown of jobs". Skip: writing jobs — `@warlock.js/queue/define-jobs/SKILL.md`.
 - [define-jobs](@warlock.js/queue/define-jobs/SKILL.md): Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — `@warlock.js/queue/configure-queue/SKILL.md`; failed jobs — `@warlock.js/queue/manage-failed-jobs/SKILL.md`.
-- [manage-failed-jobs](@warlock.js/queue/manage-failed-jobs/SKILL.md): Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the optional bull-board UI via `queueDashboard(server, { basePath, queues })` — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.
+- [manage-failed-jobs](@warlock.js/queue/manage-failed-jobs/SKILL.md): Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.
 - [overview](@warlock.js/queue/overview/SKILL.md): Front door for `@warlock.js/queue` — durable background jobs for Warlock apps on BullMQ + Redis (Redis is required): `defineJob` + `.dispatch()`, retries/backoff, delay, priority, progress, failed-job listing/retry, in-process workers started by `queueConnector()` with graceful shutdown, a BullMQ backend for notifications `.queue()`, and an optional bull-board dashboard. TRIGGER when: importing from `@warlock.js/queue`; "background job", "job queue", "run this later", "retry failed jobs", "BullMQ in Warlock", "worker process". Skip: in-memory batching inside one process — that is core's `Queue` class (`@warlock.js/core`); cron-style schedules — `@warlock.js/scheduler/overview/SKILL.md`; a known task — load `configure-queue`, `define-jobs`, `manage-failed-jobs` or `queue-notifications`.
-- [queue-notifications](@warlock.js/queue/queue-notifications/SKILL.md): Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `queueNotificationDispatcher({ queue?, attempts?, backoff? })` from `@warlock.js/queue/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Notifications keeps no queue dependency. Triggers: `queueNotificationDispatcher`, `@warlock.js/queue/notifications`, `NotificationConfig.queue`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.
+- [queue-notifications](@warlock.js/queue/queue-notifications/SKILL.md): Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.

package/package.json

@@ -11,9 +11,8 @@
   "peerDependencies": {
     "@bull-board/api": "^9.0.0",
     "@bull-board/fastify": "^9.0.0",
-    "@warlock.js/core": "5.13.0",
-    "@warlock.js/logger": "5.13.0",
-    "@warlock.js/notifications": "5.13.0"
+    "@warlock.js/core": "5.15.0",
+    "@warlock.js/logger": "5.15.0"
   },
   "peerDependenciesMeta": {
     "@bull-board/api": {
@@ -21,9 +20,6 @@
     },
     "@bull-board/fastify": {
       "optional": true
-    },
-    "@warlock.js/notifications": {
-      "optional": true
     }
   },
   "repository": {
@@ -41,7 +37,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.13.0",
+  "version": "5.15.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",
@@ -55,16 +51,6 @@
         "types": "./esm/index.d.mts",
         "default": "./cjs/index.cjs"
       }
-    },
-    "./notifications": {
-      "import": {
-        "types": "./esm/notifications/index.d.mts",
-        "default": "./esm/notifications/index.mjs"
-      },
-      "require": {
-        "types": "./esm/notifications/index.d.mts",
-        "default": "./cjs/notifications/index.cjs"
-      }
     }
   }
 }

package/skills/configure-queue/SKILL.md

@@ -53,3 +53,7 @@ process.on("SIGTERM", () => closeQueue());
 ```
 
 Every process must use the same `prefix`, or they will not see each other's jobs.
+
+## Dashboard
+
+`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).

package/skills/manage-failed-jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-failed-jobs
-description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the optional bull-board UI via `queueDashboard(server, { basePath, queues })` — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
+description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
 ---
 
 # Failed jobs
@@ -23,16 +23,45 @@ await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if n
 ## Dashboard (optional)
 
 ```sh
-npm install @bull-board/api @bull-board/fastify
+warlock add bull-board
 ```
 
+This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+const queueConfig: QueueConfig = {
+  // ...
+  dashboard: {
+    enabled: true,
+    path: "/admin/queues", // default
+    middleware: [authMiddleware("admin")], // guards every dashboard route
+  },
+};
+
+export default queueConfig;
+```
+
+- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
+- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
+
+### Advanced: manual `queueDashboard()`
+
+For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
+
 ```ts
 import { getHttpServer } from "@warlock.js/core";
 import { queueDashboard } from "@warlock.js/queue";
 
-await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+await queueDashboard(getHttpServer(), {
+  basePath: "/admin/queues",
+  middleware: [authMiddleware("admin")],
+});
 ```
 
 - Call it before the HTTP server starts listening.
 - Shows every queue that has a job, plus the default queue, unless you pass `queues`.
-- It has no authentication of its own, and it can retry and delete jobs. Protect the path.
+- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.

package/skills/overview/SKILL.md

@@ -23,4 +23,4 @@ Durable background jobs. Jobs are stored in **Redis** (required), retried on fai
 - [`configure-queue`](@warlock.js/queue/configure-queue/SKILL.md) — `src/config/queue.ts`, `queueConnector()`, workers on/off, shutdown.
 - [`define-jobs`](@warlock.js/queue/define-jobs/SKILL.md) — `defineJob`, `dispatch` options, retries, progress, `find`.
 - [`manage-failed-jobs`](@warlock.js/queue/manage-failed-jobs/SKILL.md) — `failedJobs`, `retryFailedJob`, the bull-board dashboard.
-- [`queue-notifications`](@warlock.js/queue/queue-notifications/SKILL.md) — `queueNotificationDispatcher()` for notifications `.queue()`.
+- [`queue-notifications`](@warlock.js/queue/queue-notifications/SKILL.md) — `bullmqQueue()` for notifications `.queue()`.

package/skills/queue-notifications/SKILL.md

@@ -1,22 +1,23 @@
 ---
 name: queue-notifications
-description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `queueNotificationDispatcher({ queue?, attempts?, backoff? })` from `@warlock.js/queue/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Notifications keeps no queue dependency. Triggers: `queueNotificationDispatcher`, `@warlock.js/queue/notifications`, `NotificationConfig.queue`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
+description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
 ---
 
 # Queue notifications with BullMQ
 
 ```ts title="src/config/notifications.ts"
-import { type NotificationConfig, mailChannel } from "@warlock.js/notifications";
-import { queueNotificationDispatcher } from "@warlock.js/queue/notifications";
+import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
 
 const config: NotificationConfig = {
   channels: { mail: mailChannel() },
-  queue: queueNotificationDispatcher({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
 };
 
 export default config;
 ```
 
+`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
+
 Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
 
 ```ts
@@ -31,3 +32,4 @@ await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10
 - `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
 - Channel not configured in the worker → fails at once, no retries.
 - Deliveries run under the job name `warlock.notifications.deliver`.
+