@boopkit/cap-background-jobs 0.1.0 → 0.2.0

package/capability.json

@@ -4,8 +4,8 @@
   "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)" },
@@ -13,7 +13,7 @@
   ],
   "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)" }
+    "scheduler": { "cmd": "ts-node src/scheduler.ts", "description": "Publish trigger messages to job queues — supports --interval and --job filtering" }
   },
   "files": [
     "src/scheduler.ts",
@@ -32,7 +32,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.0",
   "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
 
 ---
 
@@ -130,7 +156,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,7 +181,7 @@ 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/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/controllers/example-job.controller.ts` | Example consumer — copyable template for new job handlers |
 | `tests/services/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

@@ -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