@boopkit/cap-background-jobs 0.1.0 → 0.2.1

package/capability.json

@@ -4,23 +4,21 @@
   "type": "application",
   "package": "@boopkit/cap-background-jobs",
   "requires": ["services"],
-  "dependencies": ["amqplib@^0.10"],
-  "devDependencies": ["@types/amqplib@^0.10"],
+  "dependencies": ["amqplib@^0.10", "minimist@^1.2"],
+  "devDependencies": ["@types/amqplib@^0.10", "@types/minimist@^1.2"],
   "env": [
     { "name": "CLOUDAMQP_URL", "description": "CloudAMQP connection URL (amqp://...)", "required": "boot" },
     { "name": "QUEUE_PREFIX", "description": "Queue name prefix for environment isolation (e.g. dev/mike)" },
     { "name": "MAX_MESSAGE_RETRIES", "description": "Maximum retry attempts before dead-lettering (default: 5)" }
   ],
   "scripts": {
-    "worker": { "cmd": "ts-node src/worker.ts", "description": "Start the background job worker process" },
-    "scheduler": { "cmd": "ts-node src/scheduler.ts", "description": "Publish trigger messages to job queues (run via Heroku Scheduler)" }
+    "worker": { "cmd": "tsx src/worker.ts", "description": "Start the background job worker process" },
+    "scheduler": { "cmd": "tsx src/scheduler.ts", "description": "Publish trigger messages to job queues — supports --interval and --job filtering" }
   },
   "files": [
     "src/scheduler.ts",
     "src/worker.ts",
-    "src/services/message-queue.service.ts",
     "src/controllers/example-job.controller.ts",
-    "tests/services/message-queue.service.test.ts",
     "tests/controllers/example-job.controller.test.ts",
     "reference/background-jobs.ref.md"
   ],
@@ -32,7 +30,7 @@
       "Add CLOUDAMQP_URL to .env",
       "Set QUEUE_PREFIX for local dev isolation (e.g. dev/yourname)",
       "Add worker entry to Procfile: worker: npm run worker",
-      "Configure Heroku Scheduler to run npm run scheduler on desired interval"
+      "Configure Heroku Scheduler to run 'npm run scheduler -- run-jobs --interval <tag>' on desired interval (e.g. 10-minutes, 60-minutes)"
     ],
     "verify": "npm run worker"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-background-jobs",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Background job processing with RabbitMQ for boopkit-scaffolded projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,10 +20,12 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "amqplib": "^0.10.0"
+    "amqplib": "^0.10.0",
+    "minimist": "^1.2.8"
   },
   "devDependencies": {
     "@types/amqplib": "^0.10.0",
+    "@types/minimist": "^1.2.5",
     "typescript": "^5.9.3"
   },
   "license": "ISC",

package/scaffold/reference/background-jobs.ref.md

@@ -33,7 +33,33 @@ Three separate OS processes share one MQ service:
 |---------|------------|------|-----------|
 | **Web** | `src/server.ts` | Publishes messages as a side effect of HTTP requests | Long-running |
 | **Worker** | `src/worker.ts` | Consumes messages via registered controllers | Long-running |
-| **Scheduler** | `src/scheduler.ts` | Publishes trigger messages, then exits | One-shot (cron) |
+| **Scheduler** | `src/scheduler.ts` | Publishes trigger messages filtered by interval/job, then exits | One-shot (cron) |
+
+---
+
+## Scheduler CLI
+
+The scheduler supports subcommands and options for selecting which jobs to trigger:
+
+```bash
+# Publish all jobs tagged with the '10-minutes' interval
+npm run scheduler -- run-jobs --interval 10-minutes
+
+# Publish a specific job regardless of interval
+npm run scheduler -- run-jobs --job example-job
+
+# Combine filters
+npm run scheduler -- run-jobs --interval 60-minutes --job reconciler
+
+# List all registered jobs with their queue and interval
+npm run scheduler -- list
+```
+
+Each job in the `jobs` array has:
+- `name` — human-readable identifier (for `--job` filtering)
+- `queue` — target MQ queue name
+- `interval` — tag for external scheduler filtering (e.g. `10-minutes`, `60-minutes`)
+- `payload` — message body published to the queue
 
 ---
 
@@ -61,6 +87,12 @@ Each queue has a corresponding direct exchange for routing. Retry messages dead-
 
 The web process only opens an AMQP connection if it actually publishes a message.
 
+> **Package vs scaffold:** The `MessageQueueService` implementation lives in the
+> `@boopkit/cap-background-jobs` package (`src/message-queue.service.ts`). The
+> scaffold's `src/services/message-queue.service.ts` is a thin re-export so
+> existing local imports keep working. Package updates flow to consuming
+> projects via `npm update` without re-scaffolding.
+
 ---
 
 ## Consumer Registration
@@ -130,7 +162,9 @@ await MessageQueueService.listen('queue', handler, { prefetch: 10 });
 
 1. **CloudAMQP addon**: `heroku addons:create cloudamqp` — sets `CLOUDAMQP_URL` automatically
 2. **Procfile**: Add `worker: npm run worker`
-3. **Heroku Scheduler**: Configure `npm run scheduler` on the desired interval
+3. **Heroku Scheduler**: Configure intervals, e.g.:
+   - Every 10 min: `npm run scheduler -- run-jobs --interval 10-minutes`
+   - Every hour: `npm run scheduler -- run-jobs --interval 60-minutes`
 4. **Scale worker**: `heroku ps:scale worker=1`
 
 ---
@@ -153,8 +187,14 @@ If drain exceeds 30s, the worker force-exits with code 1.
 | File | Purpose |
 |------|---------|
 | `src/worker.ts` | Worker entry point — boots services, registers consumers, handles shutdown |
-| `src/scheduler.ts` | Scheduler entry point — publishes trigger messages, exits |
-| `src/services/message-queue.service.ts` | MQ service — publish, listen (auto/manual ACK), topology, retry/DLQ |
+| `src/scheduler.ts` | Scheduler entry point — CLI with interval/job filtering, publishes trigger messages, exits |
+| `src/services/message-queue.service.ts` | Re-exports `MessageQueueService` from `@boopkit/cap-background-jobs` |
 | `src/controllers/example-job.controller.ts` | Example consumer — copyable template for new job handlers |
-| `tests/services/message-queue.service.test.ts` | MQ service unit tests |
 | `tests/controllers/example-job.controller.test.ts` | Example controller unit tests |
+
+### Package-level files
+
+| File | Purpose |
+|------|---------||
+| `@boopkit/cap-background-jobs` `src/message-queue.service.ts` | Core MQ service — publish, listen (auto/manual ACK), topology, retry/DLQ |
+| `@boopkit/cap-background-jobs` `tests/message-queue.service.test.ts` | MQ service unit tests |

package/scaffold/src/scheduler.ts

@@ -1,12 +1,28 @@
 /** @boopkit/cap-background-jobs — Scheduler entry point for triggering background jobs. */
 
 import { loadServices } from '@services';
+import minimist from 'minimist';
 import MessageQueueService from './services/message-queue.service';
 
-// Static job registration — add new {queue, payload} entries here
-const jobs = [
+interface JobConfig {
+  /** Human-readable job name (used for --job filtering). */
+  name: string;
+  /** Target queue name to publish to. */
+  queue: string;
+  /** Interval tag for external scheduler filtering (e.g. '10-minutes', '60-minutes'). */
+  interval: string;
+  /** Message payload to publish. */
+  payload: { task: string; data?: Record<string, unknown> };
+}
+
+// Static job registration — add new entries here.
+// The `interval` field tags each job so an external scheduler can run subsets:
+//   npm run scheduler -- run-jobs --interval 10-minutes
+const jobs: JobConfig[] = [
   {
+    name: 'example-job',
     queue: 'example-job',
+    interval: '10-minutes',
     payload: {
       task: 'scheduled-run',
       data: {
@@ -17,10 +33,28 @@ const jobs = [
   },
 ];
 
-async function run() {
-  await loadServices();
+/**
+ * Publish trigger messages for jobs matching the given filters.
+ */
+async function runJobs(
+  opts: { interval?: string; job?: string; await?: boolean },
+): Promise<void> {
+  let selected = jobs;
+
+  if (opts.interval) {
+    selected = selected.filter((j) => j.interval === opts.interval);
+  }
+  if (opts.job) {
+    selected = selected.filter((j) => j.name === opts.job);
+  }
 
-  for (const job of jobs) {
+  console.log(
+    `[scheduler] ${selected.length} job(s) selected` +
+      (opts.interval ? ` for interval "${opts.interval}"` : '') +
+      (opts.job ? ` matching job "${opts.job}"` : ''),
+  );
+
+  for (const job of selected) {
     const ok = await MessageQueueService.publish(job.queue, job.payload);
     if (ok) {
       console.log(`[scheduler] published to "${job.queue}": ${job.payload.task}`);
@@ -28,12 +62,60 @@ async function run() {
       console.error(`[scheduler] failed to publish to "${job.queue}"`);
     }
   }
+}
+
+function printUsage(): void {
+  console.log(`Usage: npm run scheduler -- <command> [options]
+
+Commands:
+  run-jobs      Publish trigger messages to matching job queues
+  list          List all registered jobs
+
+Options:
+  --interval <tag>   Filter jobs by interval tag (e.g. 10-minutes, 60-minutes)
+  --job <name>       Filter jobs by name
+`);
+}
+
+async function main(args: string[], opts: Record<string, unknown>): Promise<void> {
+  const command = (args[0] ?? '').toLowerCase();
+
+  if (!command) {
+    printUsage();
+    process.exit(0);
+  }
+
+  await loadServices();
+
+  switch (command) {
+    case 'run-jobs': {
+      await runJobs({
+        interval: opts.interval as string | undefined,
+        job: opts.job as string | undefined,
+      });
+      break;
+    }
+
+    case 'list': {
+      console.log('[scheduler] registered jobs:');
+      for (const job of jobs) {
+        console.log(`  ${job.name}  queue=${job.queue}  interval=${job.interval}`);
+      }
+      break;
+    }
+
+    default:
+      console.error(`[scheduler] unknown command: ${command}`);
+      printUsage();
+      process.exit(1);
+  }
 
   await MessageQueueService.close();
   process.exit(0);
 }
 
-run().catch((err) => {
+const argv = minimist(process.argv.slice(2));
+main(argv._, argv).catch((err) => {
   console.error('[scheduler] failed:', err);
   process.exit(1);
 });

package/skills/design.background-jobs.skill.md

@@ -50,7 +50,7 @@ That's it. The MQ service creates the queue topology (main + retry + DLQ) automa
 Use `MessageQueueService.publish(queue, payload)` from any process:
 
 ```typescript
-import MessageQueueService from './services/message-queue.service';
+import { MessageQueueService } from '@boopkit/cap-background-jobs';
 
 await MessageQueueService.publish('my-job', {
   task: 'process-upload',
@@ -71,13 +71,27 @@ await MessageQueueService.publish('my-job', {
 Add an entry to the `jobs` array in `src/scheduler.ts`:
 
 ```typescript
-const jobs = [
-  { queue: 'example-job', payload: { task: 'scheduled-run', data: { ... } } },
-  { queue: 'my-job',      payload: { task: 'nightly-sync', data: { ... } } },
+const jobs: JobConfig[] = [
+  { name: 'example-job', queue: 'example-job', interval: '10-minutes', payload: { task: 'scheduled-run', data: { ... } } },
+  { name: 'nightly-sync', queue: 'my-job',     interval: '60-minutes', payload: { task: 'nightly-sync', data: { ... } } },
 ];
 ```
 
-The scheduler publishes all jobs and exits. Configure Heroku Scheduler to run `npm run scheduler` at the desired interval.
+Each job has an `interval` tag. Configure Heroku Scheduler to run different intervals:
+
+```bash
+# Every 10 minutes
+npm run scheduler -- run-jobs --interval 10-minutes
+
+# Every hour
+npm run scheduler -- run-jobs --interval 60-minutes
+
+# Specific job only
+npm run scheduler -- run-jobs --job nightly-sync
+
+# List all registered jobs
+npm run scheduler -- list
+```
 
 ## Auto-ACK vs manual-ACK
 

package/scaffold/src/services/message-queue.service.ts

@@ -1,316 +0,0 @@
-/** @boopkit/cap-background-jobs — RabbitMQ message queue service. */
-
-import amqplib from 'amqplib';
-import type { ChannelModel, Channel, ConsumeMessage } from 'amqplib';
-
-const QUEUE_PREFIX = process.env.QUEUE_PREFIX ?? '';
-const MAX_RETRIES = parseInt(process.env.MAX_MESSAGE_RETRIES ?? '5', 10);
-const BACKOFF_BASE_MS = 4000;
-const BACKOFF_MAX_MS = 60000;
-
-/** All open connections tracked for shutdown cleanup. */
-const connections: ChannelModel[] = [];
-
-/** Lazy-initialized publish connection and channel. */
-let publishConnection: ChannelModel | null = null;
-let publishChannel: Channel | null = null;
-
-const MessageQueueService = {
-  name: 'message-queue',
-  init,
-  publish,
-  listen,
-  close,
-};
-
-export default MessageQueueService;
-
-/**
- * Validate that CLOUDAMQP_URL is set. Does NOT open a connection —
- * publish connection is lazy (first publish call), listener connections
- * are created at listen() time.
- */
-function init(): void {
-  if (!process.env.CLOUDAMQP_URL) {
-    throw new Error(
-      'E: CLOUDAMQP_URL is not set. ' +
-      'R: The message queue service requires a CloudAMQP connection URL. ' +
-      'R: Set CLOUDAMQP_URL in your environment (e.g. .env file).',
-    );
-  }
-}
-
-/**
- * Publish a message to the given queue.
- * Lazy-initializes a persistent connection on first call, reuses it
- * across subsequent calls. Returns true on success, false on failure.
- */
-async function publish(queue: string, payload: unknown): Promise<boolean> {
-  const queueName = prefixedName(queue);
-
-  try {
-    const channel = await getPublishChannel();
-    await channel.assertQueue(queueName, { durable: true });
-
-    const body = Buffer.from(JSON.stringify(payload));
-    const ok = channel.sendToQueue(queueName, body, {
-      persistent: true,
-      messageId: crypto.randomUUID(),
-    });
-
-    if (!ok) {
-      // Channel buffer full — wait for drain
-      await new Promise<void>((resolve) => channel.once('drain', resolve));
-    }
-
-    return true;
-  } catch (err) {
-    console.error(`[message-queue] publish error on "${queue}":`, err);
-    resetPublishConnection();
-    return false;
-  }
-}
-
-/** Options for listen(). */
-interface ListenOpts {
-  /** When true, handler receives guarded ack/nack functions instead of returning boolean. */
-  manualAck?: boolean;
-  /** Channel prefetch count — limits concurrent message delivery for backpressure. */
-  prefetch?: number;
-}
-
-/**
- * Listen on a queue with auto-ACK or manual-ACK semantics.
- *
- * Asserts full queue topology on registration:
- *   - Main queue: `{prefix}/{name}`
- *   - Retry queue: `{prefix}/{name}.retry` (TTL redelivery to main)
- *   - DLQ: `{prefix}/{name}.failed` (dead-letter exchange)
- *
- * **Auto-ACK (default):** Handler returns true → ACK, false → retry with backoff,
- * throws → NACK to DLQ after max retries.
- *
- * **Manual-ACK (opts.manualAck = true):** Handler receives guarded ack()/nack()
- * functions. First call wins — subsequent calls are no-ops. If handler resolves
- * or throws without settling → retry/DLQ after max retries.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function listen(queue: string, handler: (...args: any[]) => Promise<any>, opts?: ListenOpts): Promise<void> {
-  const connection = await amqplib.connect(process.env.CLOUDAMQP_URL!);
-  connections.push(connection);
-
-  const channel = await connection.createChannel();
-  const { mainQueue, retryQueue, failedQueue } = await assertTopology(channel, queue);
-
-  if (opts?.prefetch != null) {
-    await channel.prefetch(opts.prefetch);
-  }
-
-  await channel.consume(mainQueue, async (raw) => {
-    if (!raw) return;
-
-    const retryCount = getRetryCount(raw);
-    let parsed: unknown;
-
-    try {
-      parsed = JSON.parse(raw.content.toString());
-    } catch {
-      // Poison message — ACK to prevent infinite redelivery
-      console.error(`[message-queue] unparseable message on "${queue}", sending to DLQ`);
-      channel.nack(raw, false, false);
-      return;
-    }
-
-    if (opts?.manualAck) {
-      // Manual-ACK: handler receives guarded ack/nack
-      let settled = false;
-
-      const guardedAck = (): void => {
-        if (settled) {
-          console.warn(`[message-queue] duplicate ack on "${queue}" — ignored`);
-          return;
-        }
-        settled = true;
-        channel.ack(raw);
-      };
-
-      const guardedNack = async (): Promise<void> => {
-        if (settled) {
-          console.warn(`[message-queue] duplicate nack on "${queue}" — ignored`);
-          return;
-        }
-        settled = true;
-        await retryOrDLQ(channel, raw, retryCount, retryQueue, failedQueue);
-      };
-
-      try {
-        await (handler as (msg: unknown, ack: () => void, nack: () => void) => Promise<void>)(parsed, guardedAck, guardedNack);
-
-        if (!settled) {
-          console.warn(`[message-queue] handler resolved without settling on "${queue}" — treating as failure`);
-          await retryOrDLQ(channel, raw, retryCount, retryQueue, failedQueue);
-        }
-      } catch (err) {
-        console.error(`[message-queue] handler threw on "${queue}":`, err);
-        if (!settled) {
-          await retryOrDLQ(channel, raw, retryCount, retryQueue, failedQueue);
-        }
-      }
-    } else {
-      // Auto-ACK: handler returns boolean
-      try {
-        const ok = await (handler as (msg: unknown) => Promise<boolean>)(parsed);
-
-        if (ok) {
-          channel.ack(raw);
-        } else {
-          await retryOrDLQ(channel, raw, retryCount, retryQueue, failedQueue);
-        }
-      } catch (err) {
-        console.error(`[message-queue] handler threw on "${queue}":`, err);
-        await retryOrDLQ(channel, raw, retryCount, retryQueue, failedQueue);
-      }
-    }
-  }, { noAck: false });
-}
-
-/** Close all tracked connections (publish + listeners). */
-async function close(): Promise<void> {
-  resetPublishConnection();
-
-  const closing = connections.map(async (conn) => {
-    try {
-      await conn.close();
-    } catch {
-      // Already closed — ignore
-    }
-  });
-  await Promise.all(closing);
-  connections.length = 0;
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-function prefixedName(name: string): string {
-  return QUEUE_PREFIX ? `${QUEUE_PREFIX}/${name}` : name;
-}
-
-/** Lazy-create or return the existing publish channel. */
-async function getPublishChannel(): Promise<Channel> {
-  if (publishChannel) return publishChannel;
-
-  const conn = await amqplib.connect(process.env.CLOUDAMQP_URL!);
-  connections.push(conn);
-  publishConnection = conn;
-
-  conn.on('error', () => resetPublishConnection());
-  conn.on('close', () => resetPublishConnection());
-
-  publishChannel = await conn.createChannel();
-  return publishChannel;
-}
-
-/** Clear cached publish connection so the next call reconnects. */
-function resetPublishConnection(): void {
-  if (publishConnection) {
-    publishConnection.close().catch(() => { /* already closing */ });
-    const idx = connections.indexOf(publishConnection);
-    if (idx !== -1) connections.splice(idx, 1);
-  }
-  publishConnection = null;
-  publishChannel = null;
-}
-
-/**
- * Assert main + retry + DLQ queues for a given queue name.
- *
- * Topology:
- *   main ──(dead-letter)──▸ {name}.failed  (via exchange)
- *   retry ──(TTL expiry)──▸ main           (via dead-letter back to main exchange)
- */
-async function assertTopology(
-  channel: Channel,
-  queue: string,
-): Promise<{ mainQueue: string; retryQueue: string; failedQueue: string }> {
-  const mainQueue = prefixedName(queue);
-  const retryQueue = `${mainQueue}.retry`;
-  const failedQueue = `${mainQueue}.failed`;
-
-  const mainExchange = `${mainQueue}.exchange`;
-  const retryExchange = `${retryQueue}.exchange`;
-  const failedExchange = `${failedQueue}.exchange`;
-
-  // Exchanges
-  await channel.assertExchange(mainExchange, 'direct', { durable: true });
-  await channel.assertExchange(retryExchange, 'direct', { durable: true });
-  await channel.assertExchange(failedExchange, 'direct', { durable: true });
-
-  // Main queue — dead-letters to failed exchange.
-  // Note: the DLX here is primarily exercised for poison messages (unparseable
-  // JSON) which are nacked without requeue. Normal failures go through
-  // retryOrDLQ() which manually publishes to the retry/failed queue and acks.
-  await channel.assertQueue(mainQueue, {
-    durable: true,
-    deadLetterExchange: failedExchange,
-  });
-  await channel.bindQueue(mainQueue, mainExchange, '');
-
-  // Retry queue — messages TTL then dead-letter back to main exchange
-  await channel.assertQueue(retryQueue, {
-    durable: true,
-    deadLetterExchange: mainExchange,
-  });
-  await channel.bindQueue(retryQueue, retryExchange, '');
-
-  // Failed (DLQ) — terminal resting place
-  await channel.assertQueue(failedQueue, { durable: true });
-  await channel.bindQueue(failedQueue, failedExchange, '');
-
-  return { mainQueue, retryQueue, failedQueue };
-}
-
-function getRetryCount(msg: ConsumeMessage): number {
-  const headers = msg.properties.headers ?? {};
-  return typeof headers['x-retry-count'] === 'number' ? headers['x-retry-count'] : 0;
-}
-
-function computeBackoff(retryCount: number): number {
-  return Math.min(BACKOFF_BASE_MS * Math.pow(2, retryCount), BACKOFF_MAX_MS);
-}
-
-/**
- * Retry a message (publish to retry queue with incremented count and TTL)
- * or send to DLQ if max retries exceeded.
- */
-async function retryOrDLQ(
-  channel: Channel,
-  raw: ConsumeMessage,
-  retryCount: number,
-  retryQueue: string,
-  failedQueue: string,
-): Promise<void> {
-  if (retryCount >= MAX_RETRIES) {
-    console.error(
-      `[message-queue] max retries (${MAX_RETRIES}) exceeded, moving to DLQ: ${failedQueue}`,
-    );
-    channel.publish('', failedQueue, raw.content, {
-      persistent: true,
-      headers: { ...raw.properties.headers, 'x-retry-count': retryCount },
-    });
-    channel.ack(raw);
-    return;
-  }
-
-  const ttl = computeBackoff(retryCount);
-  channel.publish('', retryQueue, raw.content, {
-    persistent: true,
-    expiration: String(ttl),
-    headers: {
-      ...raw.properties.headers,
-      'x-retry-count': retryCount + 1,
-    },
-  });
-  channel.ack(raw);
-}

package/scaffold/tests/services/message-queue.service.test.ts

@@ -1,419 +0,0 @@
-import type { ConsumeMessage } from 'amqplib';
-
-// Mock amqplib before importing the service
-const mockChannel: Record<string, jest.Mock> = {
-  assertExchange: jest.fn().mockResolvedValue(undefined),
-  assertQueue: jest.fn().mockResolvedValue({ queue: 'test' }),
-  bindQueue: jest.fn().mockResolvedValue(undefined),
-  sendToQueue: jest.fn().mockReturnValue(true),
-  publish: jest.fn().mockReturnValue(true),
-  consume: jest.fn().mockResolvedValue({ consumerTag: 'test-tag' }),
-  prefetch: jest.fn().mockResolvedValue(undefined),
-  ack: jest.fn(),
-  nack: jest.fn(),
-  once: jest.fn(),
-};
-
-const mockConnection: Record<string, jest.Mock> = {
-  createChannel: jest.fn().mockResolvedValue(mockChannel),
-  close: jest.fn().mockResolvedValue(undefined),
-  on: jest.fn(),
-};
-
-jest.mock('amqplib', () => ({
-  connect: jest.fn().mockResolvedValue(mockConnection),
-}));
-
-import amqplib from 'amqplib';
-import MessageQueueService from '../../src/services/message-queue.service';
-
-describe('MessageQueueService', () => {
-  const ORIGINAL_ENV = process.env;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    process.env = { ...ORIGINAL_ENV, CLOUDAMQP_URL: 'amqp://test:test@localhost/test' };
-  });
-
-  afterEach(() => {
-    process.env = ORIGINAL_ENV;
-  });
-
-  describe('init()', () => {
-    it('succeeds when CLOUDAMQP_URL is set', () => {
-      expect(() => MessageQueueService.init()).not.toThrow();
-    });
-
-    it('throws when CLOUDAMQP_URL is missing', () => {
-      delete process.env.CLOUDAMQP_URL;
-      expect(() => MessageQueueService.init()).toThrow('CLOUDAMQP_URL is not set');
-    });
-  });
-
-  describe('publish()', () => {
-    it('connects lazily on first publish', async () => {
-      const result = await MessageQueueService.publish('test-queue', { foo: 'bar' });
-
-      expect(result).toBe(true);
-      expect(amqplib.connect).toHaveBeenCalledWith(process.env.CLOUDAMQP_URL);
-      expect(mockConnection.createChannel).toHaveBeenCalled();
-    });
-
-    it('publishes with persistent flag and messageId', async () => {
-      await MessageQueueService.publish('test-queue', { data: 1 });
-
-      expect(mockChannel.sendToQueue).toHaveBeenCalledWith(
-        'test-queue',
-        expect.any(Buffer),
-        expect.objectContaining({
-          persistent: true,
-          messageId: expect.any(String),
-        }),
-      );
-    });
-
-    it('serializes payload as JSON', async () => {
-      const payload = { key: 'value', count: 42 };
-      await MessageQueueService.publish('test-queue', payload);
-
-      const sentBuffer = (mockChannel.sendToQueue as jest.Mock).mock.calls[0][1];
-      expect(JSON.parse(sentBuffer.toString())).toEqual(payload);
-    });
-
-    it('returns false on error', async () => {
-      (mockChannel.sendToQueue as jest.Mock).mockImplementationOnce(() => {
-        throw new Error('channel closed');
-      });
-
-      const result = await MessageQueueService.publish('test-queue', {});
-      expect(result).toBe(false);
-    });
-
-    it('waits for drain when channel buffer is full', async () => {
-      (mockChannel.sendToQueue as jest.Mock).mockReturnValueOnce(false);
-      (mockChannel.once as jest.Mock).mockImplementationOnce(
-        (_event: string, cb: () => void) => { cb(); },
-      );
-
-      const result = await MessageQueueService.publish('test-queue', {});
-
-      expect(result).toBe(true);
-      expect(mockChannel.once).toHaveBeenCalledWith('drain', expect.any(Function));
-    });
-
-    // Note: QUEUE_PREFIX is captured once at module load time via const.
-    // It cannot be tested by setting process.env after import. The prefix
-    // behavior is verified through listen() topology assertions instead.
-  });
-
-  describe('listen()', () => {
-    it('creates a new connection per listener', async () => {
-      await MessageQueueService.listen('jobs', async () => true);
-
-      expect(amqplib.connect).toHaveBeenCalledWith(process.env.CLOUDAMQP_URL);
-      expect(mockConnection.createChannel).toHaveBeenCalled();
-    });
-
-    it('asserts full queue topology (main + retry + DLQ)', async () => {
-      await MessageQueueService.listen('jobs', async () => true);
-
-      // Exchanges
-      expect(mockChannel.assertExchange).toHaveBeenCalledWith(
-        'jobs.exchange', 'direct', { durable: true },
-      );
-      expect(mockChannel.assertExchange).toHaveBeenCalledWith(
-        'jobs.retry.exchange', 'direct', { durable: true },
-      );
-      expect(mockChannel.assertExchange).toHaveBeenCalledWith(
-        'jobs.failed.exchange', 'direct', { durable: true },
-      );
-
-      // Queues
-      expect(mockChannel.assertQueue).toHaveBeenCalledWith(
-        'jobs',
-        expect.objectContaining({ durable: true, deadLetterExchange: 'jobs.failed.exchange' }),
-      );
-      expect(mockChannel.assertQueue).toHaveBeenCalledWith(
-        'jobs.retry',
-        expect.objectContaining({ durable: true, deadLetterExchange: 'jobs.exchange' }),
-      );
-      expect(mockChannel.assertQueue).toHaveBeenCalledWith(
-        'jobs.failed',
-        expect.objectContaining({ durable: true }),
-      );
-    });
-
-    it('sets up a consumer on the main queue', async () => {
-      await MessageQueueService.listen('jobs', async () => true);
-      expect(mockChannel.consume).toHaveBeenCalledWith('jobs', expect.any(Function), { noAck: false });
-    });
-
-    describe('message dispatch', () => {
-      let consumeCallback: (msg: ConsumeMessage | null) => Promise<void>;
-
-      beforeEach(async () => {
-        (mockChannel.consume as jest.Mock).mockImplementationOnce(
-          (_queue: string, cb: (msg: ConsumeMessage | null) => Promise<void>) => {
-            consumeCallback = cb;
-            return Promise.resolve({ consumerTag: 'tag' });
-          },
-        );
-        await MessageQueueService.listen('jobs', async (msg) => {
-          if ((msg as any).fail) return false;
-          if ((msg as any).throw) throw new Error('boom');
-          return true;
-        });
-      });
-
-      function makeMessage(payload: unknown, retryCount = 0): ConsumeMessage {
-        return {
-          content: Buffer.from(JSON.stringify(payload)),
-          properties: {
-            headers: { 'x-retry-count': retryCount },
-          },
-          fields: { deliveryTag: 1, redelivered: false, exchange: '', routingKey: '' },
-        } as unknown as ConsumeMessage;
-      }
-
-      it('ACKs when handler returns true', async () => {
-        await consumeCallback(makeMessage({ ok: true }));
-        expect(mockChannel.ack).toHaveBeenCalled();
-      });
-
-      it('retries when handler returns false', async () => {
-        await consumeCallback(makeMessage({ fail: true }));
-
-        // Should publish to retry queue with incremented retry count
-        expect(mockChannel.publish).toHaveBeenCalledWith(
-          '',
-          'jobs.retry',
-          expect.any(Buffer),
-          expect.objectContaining({
-            persistent: true,
-            expiration: '4000', // 4000 * 2^0
-            headers: expect.objectContaining({ 'x-retry-count': 1 }),
-          }),
-        );
-        expect(mockChannel.ack).toHaveBeenCalled();
-      });
-
-      it('sends to DLQ after max retries', async () => {
-        await consumeCallback(makeMessage({ fail: true }, 5));
-
-        expect(mockChannel.publish).toHaveBeenCalledWith(
-          '',
-          'jobs.failed',
-          expect.any(Buffer),
-          expect.objectContaining({
-            persistent: true,
-            headers: expect.objectContaining({ 'x-retry-count': 5 }),
-          }),
-        );
-        expect(mockChannel.ack).toHaveBeenCalled();
-      });
-
-      it('retries on handler throw (below max retries)', async () => {
-        await consumeCallback(makeMessage({ throw: true }, 2));
-
-        expect(mockChannel.publish).toHaveBeenCalledWith(
-          '',
-          'jobs.retry',
-          expect.any(Buffer),
-          expect.objectContaining({
-            expiration: '16000', // 4000 * 2^2
-            headers: expect.objectContaining({ 'x-retry-count': 3 }),
-          }),
-        );
-      });
-
-      it('ignores null messages', async () => {
-        await consumeCallback(null as unknown as ConsumeMessage);
-        expect(mockChannel.ack).not.toHaveBeenCalled();
-        expect(mockChannel.nack).not.toHaveBeenCalled();
-      });
-
-      it('NACKs unparseable messages (poison)', async () => {
-        const poisonMsg = {
-          content: Buffer.from('not-json{{{'),
-          properties: { headers: {} },
-          fields: { deliveryTag: 1, redelivered: false, exchange: '', routingKey: '' },
-        } as unknown as ConsumeMessage;
-
-        await consumeCallback(poisonMsg);
-        expect(mockChannel.nack).toHaveBeenCalledWith(poisonMsg, false, false);
-      });
-    });
-  });
-
-  describe('listen() manual-ACK mode', () => {
-    let consumeCallback: (msg: ConsumeMessage | null) => Promise<void>;
-
-    function makeMessage(payload: unknown, retryCount = 0): ConsumeMessage {
-      return {
-        content: Buffer.from(JSON.stringify(payload)),
-        properties: {
-          headers: { 'x-retry-count': retryCount },
-        },
-        fields: { deliveryTag: 1, redelivered: false, exchange: '', routingKey: '' },
-      } as unknown as ConsumeMessage;
-    }
-
-    function setupManualAckListener(
-      handler: (msg: unknown, ack: () => void, nack: () => void) => Promise<void>,
-    ) {
-      (mockChannel.consume as jest.Mock).mockImplementationOnce(
-        (_queue: string, cb: (msg: ConsumeMessage | null) => Promise<void>) => {
-          consumeCallback = cb;
-          return Promise.resolve({ consumerTag: 'tag' });
-        },
-      );
-      return MessageQueueService.listen('jobs', handler, { manualAck: true });
-    }
-
-    it('handler receives ack and nack functions', async () => {
-      let receivedAck: (() => void) | undefined;
-      let receivedNack: (() => void) | undefined;
-
-      await setupManualAckListener(async (_msg, ack, nack) => {
-        receivedAck = ack;
-        receivedNack = nack;
-        ack();
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      expect(typeof receivedAck).toBe('function');
-      expect(typeof receivedNack).toBe('function');
-      expect(mockChannel.ack).toHaveBeenCalled();
-    });
-
-    it('guarded ack — second call is no-op', async () => {
-      await setupManualAckListener(async (_msg, ack) => {
-        ack();
-        ack(); // second call — should be no-op
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      expect(mockChannel.ack).toHaveBeenCalledTimes(1);
-    });
-
-    it('guarded nack — second call is no-op', async () => {
-      await setupManualAckListener(async (_msg, _ack, nack) => {
-        nack();
-        nack(); // second call — should be no-op
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      // retryOrDLQ publishes to retry queue then acks — only one round
-      expect(mockChannel.publish).toHaveBeenCalledTimes(1);
-      expect(mockChannel.ack).toHaveBeenCalledTimes(1);
-    });
-
-    it('ack then nack — nack is no-op (first call wins)', async () => {
-      await setupManualAckListener(async (_msg, ack, nack) => {
-        ack();
-        nack(); // should be no-op since ack already settled
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      expect(mockChannel.ack).toHaveBeenCalledTimes(1);
-      expect(mockChannel.publish).not.toHaveBeenCalled(); // no retry
-    });
-
-    it('handler throws without settling — retries via DLQ path', async () => {
-      await setupManualAckListener(async () => {
-        throw new Error('boom');
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      // retryOrDLQ should have been called (publishes to retry queue)
-      expect(mockChannel.publish).toHaveBeenCalledWith(
-        '',
-        'jobs.retry',
-        expect.any(Buffer),
-        expect.objectContaining({
-          persistent: true,
-          headers: expect.objectContaining({ 'x-retry-count': 1 }),
-        }),
-      );
-      expect(mockChannel.ack).toHaveBeenCalled();
-    });
-
-    it('handler resolves without settling — treated as failure', async () => {
-      await setupManualAckListener(async () => {
-        // deliberately not calling ack or nack
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      // retryOrDLQ should have been called
-      expect(mockChannel.publish).toHaveBeenCalledWith(
-        '',
-        'jobs.retry',
-        expect.any(Buffer),
-        expect.objectContaining({
-          headers: expect.objectContaining({ 'x-retry-count': 1 }),
-        }),
-      );
-      expect(mockChannel.ack).toHaveBeenCalled();
-    });
-
-    it('handler throws after acking — no double retry', async () => {
-      await setupManualAckListener(async (_msg, ack) => {
-        ack();
-        throw new Error('post-ack error');
-      });
-      await consumeCallback(makeMessage({ data: 1 }));
-
-      // ack was called but no retry should happen (already settled)
-      expect(mockChannel.ack).toHaveBeenCalledTimes(1);
-      expect(mockChannel.publish).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('listen() prefetch', () => {
-    it('sets channel.prefetch when opts.prefetch is provided', async () => {
-      await MessageQueueService.listen('jobs', async () => true, { prefetch: 10 });
-      expect(mockChannel.prefetch).toHaveBeenCalledWith(10);
-    });
-
-    it('does not call prefetch when opts.prefetch is not provided', async () => {
-      await MessageQueueService.listen('jobs', async () => true);
-      expect(mockChannel.prefetch).not.toHaveBeenCalled();
-    });
-
-    it('sets prefetch before consuming', async () => {
-      const callOrder: string[] = [];
-      (mockChannel.prefetch as jest.Mock).mockImplementation(() => {
-        callOrder.push('prefetch');
-        return Promise.resolve(undefined);
-      });
-      (mockChannel.consume as jest.Mock).mockImplementation(() => {
-        callOrder.push('consume');
-        return Promise.resolve({ consumerTag: 'tag' });
-      });
-
-      await MessageQueueService.listen('jobs', async () => true, { prefetch: 5 });
-
-      expect(callOrder).toEqual(['prefetch', 'consume']);
-    });
-  });
-
-  describe('close()', () => {
-    it('closes all tracked connections', async () => {
-      // Create a listener connection
-      await MessageQueueService.listen('q', async () => true);
-
-      await MessageQueueService.close();
-      expect(mockConnection.close).toHaveBeenCalled();
-    });
-  });
-
-  describe('service shape', () => {
-    it('exports the required service interface', () => {
-      expect(MessageQueueService.name).toBe('message-queue');
-      expect(typeof MessageQueueService.init).toBe('function');
-      expect(typeof MessageQueueService.publish).toBe('function');
-      expect(typeof MessageQueueService.listen).toBe('function');
-      expect(typeof MessageQueueService.close).toBe('function');
-    });
-  });
-});