@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-packages/queue.md

@@ -0,0 +1,442 @@
+---
+name: queue
+description: "Database-backed job queue with middleware, configurable retries, and backoff strategies. Use when dispatching background jobs, processing queues with concurrency control, scheduling delayed work, handling retries and permanent failures, or integrating with mail/recurring-jobs. Provides db (MySQL) and local (in-memory) drivers."
+---
+
+# @maestro-js/queue
+
+Database-backed job queue with middleware, configurable retries, and backoff strategies.
+
+## Quick Setup
+
+```ts
+import { Queue } from '@maestro-js/queue'
+import { Db } from '@maestro-js/db'
+
+// Create and register a queue service with the db driver
+const service = Queue.Provider.create({
+  driver: Queue.drivers.db({ db: Db.provider('default'), databaseTable: 'queue' }),
+  logger: Log.provider('default')
+})
+Queue.Provider.register('default', service)
+
+// Define a queue with a handler
+const emailQueue = Queue.create({
+  name: 'send-emails',
+  handle: async (body) => sendEmail(body.to, body.subject),
+  tries: 3,
+  backoffSeconds: [30, 60, 120]
+})
+
+// Dispatch a message and start processing
+await emailQueue.dispatch({ to: 'alice@example.com', subject: 'Welcome' })
+await Queue.work({ stopWhenEmpty: true })
+```
+
+## Provider Pattern
+
+Queue follows the standard Maestro Provider pattern built on `@maestro-js/service-registry`:
+
+1. **`Queue.Provider.create(config)`** -- factory that instantiates a queue service with a driver
+2. **`Queue.Provider.register(name, service)`** -- register the instance in a named registry
+3. **`Queue.provider(key)`** -- resolve a named instance (deferred via Proxy)
+4. **Facade** -- `Queue.create()`, `Queue.work()`, etc. spread from `provider('default')`
+5. **`Queue.drivers`** -- factory functions for pluggable backends (`db`, `local`)
+
+Extend provider keys via declaration merging:
+
+```ts
+declare module '@maestro-js/queue' {
+  namespace Queue.Provider {
+    interface Keys {
+      default: unknown
+      highPriority: unknown
+    }
+  }
+}
+```
+
+Source: `packages/queue/src/index.ts`
+
+## Drivers
+
+### db (MySQL)
+
+Production driver backed by MySQL. Uses optimistic locking with `UPDATE ... INNER JOIN` for
+concurrent pop operations.
+
+```ts
+Queue.drivers.db({
+  db: Db.provider('default'),    // must implement select/insert/update
+  databaseTable: 'queue',        // table name (alphanumeric + underscores only)
+  queue: 'send-emails',          // optional: filter to specific queue name(s)
+  batchingMaxWaitSeconds: 0.5    // optional: batch pop requests over this window
+})
+```
+
+Config interface:
+
+| Field                    | Type                 | Default | Description                                    |
+|--------------------------|----------------------|---------|------------------------------------------------|
+| `db`                     | `{ select, insert, update }` | --  | Database connection with query methods          |
+| `databaseTable`          | `string`             | --      | MySQL table name                               |
+| `queue`                  | `string \| string[]` | --      | Optional queue name filter                     |
+| `batchingMaxWaitSeconds` | `number`             | `0`     | Batch pop requests over this window (seconds)  |
+
+Required database schema:
+
+```sql
+CREATE TABLE queue (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  attempt INT UNSIGNED NOT NULL DEFAULT 0,
+  queue VARCHAR(255) NOT NULL,
+  status ENUM('waiting', 'processing', 'succeeded', 'failed', 'failedPermanently') NOT NULL DEFAULT 'waiting',
+  scheduledDate DATETIME NOT NULL,
+  enqueuedDate DATETIME NOT NULL DEFAULT NOW(),
+  startedDate DATETIME,
+  completedDate DATETIME,
+  body JSON,
+  result TEXT,
+  lockId BIGINT UNSIGNED DEFAULT NULL,
+  PRIMARY KEY (id, attempt),
+  INDEX locking_pop (lockId, status, scheduledDate),
+  INDEX queue (queue)
+);
+```
+
+Source: `packages/queue/src/db-queue-driver.ts`
+
+### local (In-Memory)
+
+In-memory driver for testing. Same interface as db but stores messages in a plain array:
+
+```ts
+Queue.drivers.local({
+  queue: 'send-emails'   // optional: filter to specific queue name(s)
+})
+```
+
+Source: `packages/queue/src/local-queue-driver.ts`
+
+## Core Concepts
+
+### Retry and Backoff
+
+Configure retries per queue with `tries` and `backoffSeconds`:
+
+```ts
+const q = Queue.create({
+  name: 'flaky-api',
+  handle: async (body) => callExternalApi(body),
+  tries: 4,                          // total attempts (1 initial + 3 retries)
+  backoffSeconds: [10, 30, 120]      // delay before retry 1, 2, 3
+})
+```
+
+- `tries` defaults to `1` (no retries)
+- `backoffSeconds` can be a single `number` (constant delay) or an `number[]` (per-attempt delay)
+- If the array is shorter than the number of retries, the last value is reused
+- If omitted entirely, defaults to `60` seconds between retries
+- `attempts` on the message is 0-indexed -- the first attempt is `0`, the first retry is `1`
+
+### Middleware
+
+Wrap message handling with middleware functions for cross-cutting concerns:
+
+```ts
+const loggingMiddleware: Queue.Middleware = async (message, next) => {
+  console.log('Processing:', message)
+  const result = await next()
+  console.log('Done:', result)
+  return result
+}
+
+const q = Queue.create({
+  name: 'with-logging',
+  handle: async (body) => processBody(body),
+  middleware: [loggingMiddleware]
+})
+```
+
+Middleware is composed right-to-left (`reduceRight`), so the first middleware in the array is the
+outermost wrapper.
+
+### Fail and Release
+
+Handlers receive `fail` and `release` callbacks as a second argument for explicit message control:
+
+```ts
+const q = Queue.create({
+  name: 'validate-first',
+  tries: 3,
+  handle: async (body, { fail, release }) => {
+    if (!body.email) {
+      fail(new Error('Missing email -- will never succeed'))  // permanently fail, skip retries
+    }
+    const result = await sendEmail(body.email)
+    if (result.rateLimited) {
+      release(new Error('Rate limited'), 300)  // retry in 5 minutes
+    }
+  }
+})
+```
+
+- **`fail(error)`** -- permanently fails the message, regardless of remaining retries
+- **`release(error, delaySeconds?)`** -- releases the message for retry. Pass `delaySeconds` to override the configured backoff, or omit it to use the default.
+
+Both return `never` -- they halt handler execution at the call site.
+
+Any other thrown error also triggers a retry (or permanent failure on the last attempt), using the
+configured `backoffSeconds`. Middleware also receives these callbacks as a third argument.
+
+### Work Loop
+
+`Queue.work()` starts a polling loop that pops messages from the driver and dispatches them to the
+appropriate handler:
+
+```ts
+const workHandle = Queue.work({
+  maxJobs: 100,           // stop after processing 100 messages
+  stopWhenEmpty: false,    // keep polling even when queue is empty
+  maxTimeSeconds: 3600,    // stop after 1 hour
+  sleepSeconds: 1,         // pause between polls when idle (default 1)
+  concurrency: 4           // number of parallel polling workers
+})
+
+// Later: gracefully stop
+workHandle.abort('shutting down')
+
+// Or stop all active work loops
+await Queue.stopAllWork()
+```
+
+The work loop swallows handler errors -- failed messages are logged and released/failed via the
+driver, but the loop continues.
+
+## API Reference
+
+### QueueService Methods
+
+```ts
+Queue.Provider.create(config: { driver: Queue.Driver, logger?: Log.Logger }): Queue.QueueService
+```
+Creates a new queue service with the given driver and optional logger.
+
+```ts
+Queue.create<MessageBody, Result>(config: Queue.Config): Queue.QueueHandle
+```
+Creates a named queue bound to the default service. Throws if a queue with the same name already
+exists.
+
+```ts
+Queue.work(options: Queue.WorkOptions): Promise<void> & { abort(reason?: string): void }
+```
+Starts a polling work loop. Returns a promise that resolves when the loop stops, with an `abort()`
+method to stop it.
+
+```ts
+Queue.stopAllWork(): Promise<void>
+```
+Aborts all active work loops and waits for in-flight messages to finish.
+
+```ts
+Queue.processMessage(queueMessage: Queue.Message): Promise<unknown>
+```
+Processes a single message directly by looking up the queue handler by name. Used by
+`@maestro-js/recurring-jobs` to process messages outside the normal work loop.
+
+### QueueHandle Methods
+
+```ts
+handle.dispatch(body: MessageBody): Promise<void>
+```
+Enqueues a message for immediate processing.
+
+```ts
+handle.dispatchWithDelay(body: MessageBody, scheduledDate: Iso.Instant): Promise<void>
+```
+Enqueues a message scheduled for a future date.
+
+```ts
+handle.dispatchSync(body: MessageBody): Promise<Result>
+```
+Runs the handler synchronously without going through the driver. Useful for testing. Middleware
+still executes.
+
+```ts
+handle.bulk(messages: { body: MessageBody; scheduledDate?: Iso.Instant }[]): Promise<void>
+```
+Enqueues multiple messages in a single operation. Uses the driver's bulk method for efficiency.
+
+### Queue.Config
+
+| Field            | Type                                   | Default | Description                                          |
+|------------------|----------------------------------------|---------|------------------------------------------------------|
+| `name`           | `string`                               | --      | Unique queue name                                    |
+| `handle`         | `(message: MessageBody, actions: Queue.Actions) => Promise<Result>` | --  | Handler function for each message |
+| `middleware`     | `Queue.Middleware[]`                   | `[]`    | Middleware wrapping the handler                       |
+| `tries`          | `number`                               | `1`     | Total attempts (1 = no retries)                      |
+| `backoffSeconds` | `number \| number[]`                   | `60`    | Seconds to wait between retries                      |
+| `logger`         | `Log.LogFunctions`                     | --      | Per-queue logger (in addition to service-level logger)|
+
+### Queue.WorkOptions
+
+| Field            | Type      | Default | Description                                  |
+|------------------|-----------|---------|----------------------------------------------|
+| `maxJobs`        | `number`  | --      | Stop after processing this many messages     |
+| `stopWhenEmpty`  | `boolean` | --      | Stop when no messages are available          |
+| `maxTimeSeconds` | `number`  | --      | Stop after this many seconds                 |
+| `sleepSeconds`   | `number`  | `1`     | Seconds to sleep between polls when idle     |
+| `concurrency`    | `number`  | `1`     | Number of parallel polling workers           |
+
+## Common Patterns
+
+### Email queue with retries
+
+```ts
+const emailQueue = Queue.create({
+  name: 'send-emails',
+  handle: async (body, { fail }) => {
+    const result = await sendEmail(body.to, body.subject, body.html)
+    if (result.rejected) {
+      fail(new Error(`Rejected: ${body.to}`))
+    }
+  },
+  tries: 3,
+  backoffSeconds: [60, 300, 900]
+})
+
+await emailQueue.dispatch({ to: 'bob@example.com', subject: 'Hello', html: '<p>Hi!</p>' })
+```
+
+### Delayed scheduling
+
+```ts
+import { instantFns } from 'iso-fns2'
+
+// Schedule a reminder for 24 hours from now
+await reminderQueue.dispatchWithDelay(
+  { userId: 42, message: 'Check in' },
+  instantFns.add(instantFns.now(), { hours: 24 })
+)
+```
+
+### Bulk dispatch
+
+```ts
+const messages = users.map((user) => ({
+  body: { userId: user.id, type: 'weekly-digest' }
+}))
+await digestQueue.bulk(messages)
+```
+
+### Middleware (logging, tracing)
+
+```ts
+const tracingMiddleware: Queue.Middleware = async (message, next) => {
+  const span = tracer.startSpan('queue.process')
+  try {
+    return await next()
+  } finally {
+    span.end()
+  }
+}
+
+const q = Queue.create({
+  name: 'traced-queue',
+  handle: async (body) => process(body),
+  middleware: [tracingMiddleware]
+})
+```
+
+### Sync dispatch for testing
+
+```ts
+// Bypass the driver entirely -- runs the handler (and middleware) inline
+const result = await emailQueue.dispatchSync({ to: 'test@example.com', subject: 'Test' })
+```
+
+## Testing
+
+Use the local driver in tests. The local driver stores messages in-memory:
+
+```ts
+import { Queue } from '@maestro-js/queue'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+const service = Queue.Provider.create({ driver: Queue.drivers.local() })
+Queue.Provider.register('default', service)
+
+const testQueue = Queue.create({
+  name: 'test-queue',
+  handle: async (body) => ({ processed: body.value })
+})
+
+test('dispatches and processes a message', async () => {
+  await testQueue.dispatch({ value: 42 })
+  await Queue.work({ stopWhenEmpty: true })
+})
+
+test('dispatchSync runs handler inline', async () => {
+  const result = await testQueue.dispatchSync({ value: 99 })
+  expect(result).toEqual({ processed: 99 })
+})
+```
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/queue test
+cd packages/queue && npx beartest ./tests/**/*
+```
+
+## Warnings and Gotchas
+
+- **Queue name uniqueness** -- calling `Queue.create()` with a name that's already registered
+  throws an error. Each queue name must be unique within a service instance.
+- **`attempts` is 0-indexed** -- the first execution has `attempts: 0`, the first retry has
+  `attempts: 1`. The message permanently fails when `attempts + 1 >= tries`.
+- **`backoffSeconds` array indexing** -- `backoffSeconds[attempts]` is used for the delay, where
+  `attempts` is 0-indexed. If the array is shorter than the retry count, the last element is reused.
+- **`dispatchSync` bypasses the driver** -- messages sent with `dispatchSync` are never persisted.
+  The handler runs inline, and `work()` will never pick them up. Middleware still executes.
+- **`work()` swallows handler errors** -- the work loop catches all errors from handlers. Failed
+  messages are released/failed via the driver and logged, but the loop continues polling.
+- **Database schema must be created manually** -- the db driver does not create or migrate the
+  queue table. You must create it before using the driver. See the schema in the Drivers section.
+- **`work()` returns a hybrid promise** -- the returned value is both a `Promise<void>` and has an
+  `abort()` method. Call `abort()` to stop the loop, then `await` the promise.
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation),
+  `@maestro-js/log` (structured logging)
+- **Used by**: `@maestro-js/mail` (async email sending via queue), `@maestro-js/recurring-jobs`
+  (cron-scheduled jobs backed by queue)
+- **Dev dependency**: `@maestro-js/db` (MySQL driver needs a db connection)
+
+## Driver Interface
+
+Implement `Queue.Driver` to create a custom backend:
+
+```ts
+interface QueueDriver {
+  size(): Promise<number>
+  push(message: { queue: string; body: Record<string, any>; scheduledDate: Iso.Instant }): Promise<string>
+  bulk(messages: { queue: string; body: Record<string, any>; scheduledDate: Iso.Instant }[]): Promise<void>
+  pop(): Promise<QueueMessage | null>
+  fail(options: { id: string; attempts: number; error: Error }): Promise<void>
+  success(options: { id: string; attempts: number; result: any }): Promise<void>
+  release(options: { id: string; attempts: number; error: Error; delaySeconds: number }): Promise<void>
+}
+```
+
+Source: `packages/queue/src/queue-driver.ts`
+
+## Key Source Files
+
+- `packages/queue/src/index.ts` -- main export, Provider pattern, `createService()`, queue handles
+- `packages/queue/src/queue-driver.ts` -- `QueueDriver` and `QueueMessage` interfaces
+- `packages/queue/src/db-queue-driver.ts` -- MySQL driver with optimistic locking
+- `packages/queue/src/local-queue-driver.ts` -- in-memory driver for testing

package/skills/maestro-packages/recurring-jobs.md

@@ -0,0 +1,238 @@
+---
+name: recurring-jobs
+description: "Use when working with @maestro-js/recurring-jobs. Cron-based recurring job scheduling with distributed lock-based deduplication. Use for cron scheduling, periodic background tasks, and recurring jobs that must run exactly once across processes. Drivers: Db (MySQL), Cache (Redis via @maestro-js/cache), Local (in-memory). Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, 60-second polling loop, per-job distributed locking, optional middleware wrapping, eager cron validation, structured lifecycle log events (jobDue, jobLockAcquired, jobFailed, jobProcessed), and graceful shutdown via abort/stopAllWork."
+---
+
+# @maestro-js/recurring-jobs
+
+Cron-based recurring job scheduling with distributed lock-based deduplication.
+
+## Quick Setup
+
+```ts
+import { RecurringJobs } from '@maestro-js/recurring-jobs'
+
+// Create and register with the local (in-memory) driver
+const service = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.local()
+})
+RecurringJobs.Provider.register('default', service)
+
+// Define a recurring job
+RecurringJobs.create({
+  name: 'send-weekly-digest',
+  cron: '0 9 * * MON',
+  handle: async () => sendDigest()
+})
+
+// Start polling -- fires immediately then every 60 seconds
+const worker = RecurringJobs.work()
+
+// Graceful shutdown
+await worker.abort()
+```
+
+## Drivers
+
+### Db
+
+MySQL-backed, for multi-process production deployments. Uses `UPDATE ... WHERE lastRunDate < ?`
+and `INSERT IGNORE` for atomic distributed locking.
+
+```ts
+RecurringJobs.drivers.db({
+  db: Db,              // Db service instance
+  databaseTable: 'recurringJobs'
+})
+```
+
+Required table schema:
+
+```sql
+CREATE TABLE recurringJobs (
+  name VARCHAR(255) NOT NULL PRIMARY KEY,
+  lastRunDate DATETIME DEFAULT NULL
+);
+```
+
+Source: `packages/recurring-jobs/src/db-recurring-jobs-driver.ts`
+
+### Cache
+
+Redis-backed via `@maestro-js/cache` with distributed locking (`cache.lock()`). Use when you
+already have Redis and don't need MySQL.
+
+```ts
+RecurringJobs.drivers.cache({
+  cache: cacheService,          // Cache.CacheService instance
+  keyPrefix: 'recurring-jobs:'  // optional, default 'recurring-jobs:'
+})
+```
+
+Source: `packages/recurring-jobs/src/cache-recurring-jobs-driver.ts`
+
+### Local
+
+In-memory, single-process only. No distributed locking -- every process will run every due job.
+Good for development and testing.
+
+```ts
+RecurringJobs.drivers.local()
+```
+
+Source: `packages/recurring-jobs/src/local-recurring-jobs-driver.ts`
+
+### Choosing a driver
+
+| Driver  | Distributed locking | Persistence | Best for                              |
+|---------|---------------------|-------------|---------------------------------------|
+| **Db**  | Yes (MySQL row)     | Yes         | Multi-process production              |
+| **Cache** | Yes (Redis lock)  | Yes*        | Production when you have Redis, no MySQL |
+| **Local** | No                | No          | Development and testing               |
+
+\* Cache persistence depends on Redis persistence settings.
+
+## API Reference
+
+### `RecurringJobs.create(config)`
+
+Register a recurring job. Throws immediately on invalid cron expression or duplicate job name.
+
+```ts
+RecurringJobs.create({
+  name: string,                          // unique job identifier
+  cron: string,                          // cron expression (e.g. '0 9 * * MON')
+  handle: () => Promise<Result>,         // async handler
+  middleware?: Middleware<Result>[]       // optional middleware chain
+})
+```
+
+### `RecurringJobs.work()`
+
+Start a 60-second polling loop that checks for due jobs, acquires distributed locks via the
+driver, and executes handlers. Returns an object with `abort()` to stop the loop and wait for
+in-flight ticks.
+
+```ts
+const worker = RecurringJobs.work()
+
+// Later, to stop:
+await worker.abort()
+```
+
+### `RecurringJobs.stopAllWork()`
+
+Abort all active work loops and wait for in-flight ticks to finish.
+
+```ts
+await RecurringJobs.stopAllWork()
+```
+
+## Common Patterns
+
+### Basic cron job
+
+```ts
+RecurringJobs.create({
+  name: 'cleanup-expired-tokens',
+  cron: '0 3 * * *', // daily at 3am
+  handle: async () => {
+    await db.update('DELETE FROM tokens WHERE expiresAt < NOW()')
+  }
+})
+```
+
+### Middleware wrapping
+
+```ts
+RecurringJobs.create({
+  name: 'generate-report',
+  cron: '0 6 * * MON',
+  middleware: [
+    async (next) => {
+      try {
+        return await next()
+      } catch (e) {
+        await errorReporter.capture(e)
+        throw e
+      }
+    }
+  ],
+  handle: async () => generateWeeklyReport()
+})
+```
+
+### Graceful shutdown
+
+```ts
+const worker = RecurringJobs.work()
+
+process.on('SIGTERM', async () => {
+  await worker.abort()   // waits for in-flight tick to finish
+  process.exit(0)
+})
+
+// Or abort all workers at once:
+process.on('SIGTERM', async () => {
+  await RecurringJobs.stopAllWork()
+  process.exit(0)
+})
+```
+
+### Named provider instances
+
+```ts
+const primary = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.db({ db: Db, databaseTable: 'recurringJobs' })
+})
+RecurringJobs.Provider.register('default', primary)
+
+const secondary = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.local()
+})
+RecurringJobs.Provider.register('dev', secondary)
+
+RecurringJobs.provider('dev').create({ ... })
+```
+
+## Warnings and Gotchas
+
+- **60-second polling**: Jobs won't fire more precisely than ~1 minute.
+- **Unique job names**: Duplicate names within a service instance throw at `create()` time.
+- **Eager cron validation**: Invalid cron expressions throw at `create()` time, not at poll time.
+- **First-time jobs**: A never-before-run job doesn't fire immediately on `work()` -- it waits
+  until its cron expression's next occurrence from now.
+- **Handler errors don't crash the loop**: Failed handlers are logged as `jobFailed` and other
+  jobs continue normally.
+- **Db driver requires a table**: The `recurringJobs` table must exist with the schema shown above.
+- **Local driver has no distributed locking**: All processes will independently run the same job.
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern), `@maestro-js/log` (structured
+  logging), `cron-parser` (cron expression parsing)
+- **Optional drivers depend on**: `@maestro-js/db` (Db driver), `@maestro-js/cache` (Cache driver)
+
+## Driver Interface
+
+Implement `RecurringJobs.Driver` to create a custom backend:
+
+```ts
+interface Driver {
+  listLastRunDates(jobNames: string[]): Promise<{ jobName: string; date: Iso.Instant }[]>
+  pullJob(options: { jobName: string; date: Iso.Instant }): Promise<boolean>
+}
+```
+
+`listLastRunDates` returns the last run date for each known job name. `pullJob` attempts to
+acquire a lock for the given job and date -- returns `true` if the lock was acquired (this process
+should run the job), `false` otherwise.
+
+Source: `packages/recurring-jobs/src/index.ts`
+
+## Key Source Files
+
+- `packages/recurring-jobs/src/index.ts` -- main export, Provider pattern, polling loop, middleware
+- `packages/recurring-jobs/src/db-recurring-jobs-driver.ts` -- MySQL driver with row-level locking
+- `packages/recurring-jobs/src/cache-recurring-jobs-driver.ts` -- Redis driver via @maestro-js/cache
+- `packages/recurring-jobs/src/local-recurring-jobs-driver.ts` -- in-memory driver for dev/testing