@boopkit/cap-background-jobs 0.2.0 → 0.2.2

package/capability.json

@@ -12,15 +12,13 @@
     { "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 — supports --interval and --job filtering" }
+    "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"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-background-jobs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Background job processing with RabbitMQ for boopkit-scaffolded projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -87,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
@@ -182,7 +188,13 @@ If drain exceeds 30s, the worker force-exits with code 1.
 |------|---------|
 | `src/worker.ts` | Worker entry point — boots services, registers consumers, handles shutdown |
 | `src/scheduler.ts` | Scheduler entry point — CLI with interval/job filtering, publishes trigger messages, exits |
-| `src/services/message-queue.service.ts` | MQ service — publish, listen (auto/manual ACK), topology, retry/DLQ |
+| `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

@@ -69,11 +69,15 @@ function printUsage(): void {
 
 Commands:
   run-jobs      Publish trigger messages to matching job queues
+  publish       Publish a single message to a queue and exit
   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
+  --queue <name>     Target queue for publish command
+  --task <name>      Task name for publish payload (default: "cli")
+  --data <json>      JSON string of extra data for publish payload
 `);
 }
 
@@ -104,6 +108,32 @@ async function main(args: string[], opts: Record<string, unknown>): Promise<void
       break;
     }
 
+    case 'publish': {
+      const queue = opts.queue as string | undefined;
+      if (!queue) {
+        console.error('[scheduler] --queue is required for publish command');
+        process.exit(1);
+      }
+      const task = (opts.task as string) ?? 'cli';
+      let data: Record<string, unknown> = {};
+      if (opts.data) {
+        try {
+          data = JSON.parse(opts.data as string);
+        } catch {
+          console.error('[scheduler] --data must be valid JSON');
+          process.exit(1);
+        }
+      }
+      const ok = await MessageQueueService.publish(queue, { task, data });
+      if (ok) {
+        console.log(`[scheduler] published to "${queue}": ${task}`);
+      } else {
+        console.error(`[scheduler] failed to publish to "${queue}"`);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
       console.error(`[scheduler] unknown command: ${command}`);
       printUsage();

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',

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');
-    });
-  });
-});