@maestro-js/agent-skills 1.0.0-alpha.0

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

@@ -0,0 +1,353 @@
+---
+name: recurring-jobs
+description: "Use when working with @maestro-js/recurring-jobs. Cron-based job scheduling backed by the Queue package. Covers creating recurring jobs, managing schedules, start/stop processing, rescheduling, listing jobs, and inspecting upcoming runs. Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, deduplication across process restarts, per-job dedicated queues, structured log events, and paginated execution history."
+---
+
+# RecurringJobs Skill
+
+## Overview
+
+RecurringJobs provides cron-based job scheduling backed by the Queue package. Each recurring job gets its own dedicated queue where every execution is a persisted message with full lifecycle tracking. The next run is enqueued before the work function executes, guaranteeing the schedule continues even if the current run fails.
+
+## Quick Setup
+
+```ts
+import { RecurringJobs } from '@maestro-js/recurring-jobs'
+import { Queue } from '@maestro-js/queue'
+import { Log } from '@maestro-js/log'
+
+// Create a logger for recurring job events
+const logger = Log.create<[RecurringJobs.LogMessage]>({
+  transports: [{ write: ({ data: [msg] }) => console.log(msg) }]
+})
+
+// Create and register the recurring jobs service with a queue service
+const recurringJobsService = RecurringJobs.Provider.create({
+  logger,
+  queueService: Queue.provider('default')
+})
+RecurringJobs.Provider.register('default', recurringJobsService)
+
+// Define a recurring job
+const dailyReport = RecurringJobs.createJob({
+  name: 'daily-sales-report',
+  cron: '0 6 * * *',
+  workFn: async () => {
+    const total = await calculateDailySales()
+    return { total }
+  }
+})
+
+// Start processing
+dailyReport.startProcessing()
+```
+
+## Cron Expression Format
+
+Uses the `cron-parser` library (v4.x) for standard 5-field cron expressions:
+
+```
+ ┌───────────── minute (0-59)
+ │ ┌───────────── hour (0-23)
+ │ │ ┌───────────── day of month (1-31)
+ │ │ │ ┌───────────── month (1-12)
+ │ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
+ │ │ │ │ │
+ * * * * *
+```
+
+Common examples:
+- `0 6 * * *` -- every day at 6:00 AM
+- `*/15 * * * *` -- every 15 minutes
+- `0 0 * * 0` -- every Sunday at midnight
+- `0 9 1 * *` -- first day of every month at 9:00 AM
+- `30 */2 * * *` -- every 2 hours at the 30-minute mark
+
+Invalid cron expressions throw immediately when passed to `createJob()`, since `cron-parser.parseExpression()` is called at creation time.
+
+## API Reference
+
+### Provider Setup
+
+#### `RecurringJobs.Provider.create(config)`
+
+Create a recurring jobs service instance.
+
+```ts
+RecurringJobs.Provider.create(config: {
+  logger: Log.Logger<[RecurringJobs.LogMessage]>
+  queueService: Queue.QueueService
+})
+```
+
+- `logger` -- a Log instance typed to `RecurringJobs.LogMessage` for structured job lifecycle events
+- `queueService` -- the Queue service used to back each recurring job's dedicated queue
+
+#### `RecurringJobs.Provider.register(name, service)`
+
+Register the service instance in the named registry.
+
+```ts
+RecurringJobs.Provider.register('default', recurringJobsService)
+```
+
+#### `RecurringJobs.provider(key)`
+
+Resolve a named instance from the registry. Supports deferred resolution via Proxy.
+
+```ts
+const jobs = RecurringJobs.provider('default')
+```
+
+### Service Methods (on the facade or provider instance)
+
+#### `RecurringJobs.createJob(config)`
+
+Create a recurring job with a dedicated queue. Returns a `RecurringJob` handle.
+
+```ts
+RecurringJobs.createJob<T>(config: {
+  name: string
+  cron: string
+  workFn: () => Promise<T>
+  logger?: Log.LogFunctions<[RecurringJobs.LogMessage]>  // optional per-job logger
+}): RecurringJobs.RecurringJob<T>
+```
+
+Each job creates a queue named `RecurringJobs: <name>`. The cron expression is validated immediately and throws if invalid.
+
+#### `RecurringJobs.startProcessing()`
+
+Start processing on all registered recurring jobs.
+
+```ts
+RecurringJobs.startProcessing()
+```
+
+#### `RecurringJobs.stopProcessing()`
+
+Stop processing on all registered recurring jobs.
+
+```ts
+RecurringJobs.stopProcessing()
+```
+
+#### `RecurringJobs.list()`
+
+Return the names of all registered recurring jobs.
+
+```ts
+RecurringJobs.list()  // ['daily-sales-report', 'session-cleanup']
+```
+
+#### `RecurringJobs.get(name)`
+
+Return the recurring job with the given name, or `undefined` if not found.
+
+```ts
+const job = RecurringJobs.get<{ total: number }>('daily-sales-report')
+```
+
+### RecurringJob Instance Methods
+
+#### `job.startProcessing()`
+
+Enqueue the next scheduled run and begin polling. If a waiting job already exists, it is not duplicated (deduplication).
+
+```ts
+dailyReport.startProcessing()
+```
+
+#### `job.stopProcessing()`
+
+Stop polling for this job.
+
+```ts
+dailyReport.stopProcessing()
+```
+
+#### `job.getNextUp()`
+
+Return the first message in `waiting` status, or `null` if none exists.
+
+```ts
+const next = await dailyReport.getNextUp()
+// { id: 42, status: 'waiting', scheduledDate: '2026-02-22T06:00:00.000Z', cron: '0 6 * * *', ... }
+```
+
+#### `job.list({ pageSize, pageNumber })`
+
+Return a paginated list of all messages (past runs and pending) for this job.
+
+```ts
+const history = await dailyReport.list({ pageSize: 20, pageNumber: 0 })
+// [{ id: 41, status: 'success', result: { total: 15420 }, ... }, ...]
+```
+
+#### `job.rescheduleJob({ jobId, scheduledDate })`
+
+Change the scheduled time of a waiting job. Only the next waiting job can be rescheduled; throws if `jobId` does not match the current waiting job.
+
+```ts
+await dailyReport.rescheduleJob({
+  jobId: 42,
+  scheduledDate: '2026-02-22T08:00:00.000Z' as Iso.Instant
+})
+```
+
+#### `job.name` / `job.cron`
+
+Read-only properties exposing the job's name and cron expression.
+
+```ts
+dailyReport.name  // 'daily-sales-report'
+dailyReport.cron  // '0 6 * * *'
+```
+
+### JobMessage Interface
+
+Each queue message returned by `getNextUp()` and `list()` has these fields:
+
+```ts
+interface JobMessage<Result = any> {
+  id: number
+  batchId: number | null
+  queue: string
+  scheduledDate: Iso.Instant
+  enqueuedDate: Iso.Instant
+  startedDate: Iso.Instant | null
+  status: 'waiting' | 'processing' | 'success' | 'error' | 'stuck'
+  result: Result
+  recovered: number
+  runningTime: number | null
+  uniqueKey: number | null
+  priority: number | null
+  cron: string
+}
+```
+
+## Common Patterns
+
+### Multiple Recurring Jobs
+
+```ts
+const report = RecurringJobs.createJob({
+  name: 'daily-report',
+  cron: '0 6 * * *',
+  workFn: async () => generateReport()
+})
+
+const cleanup = RecurringJobs.createJob({
+  name: 'session-cleanup',
+  cron: '0 0 * * *',
+  workFn: async () => cleanStaleSessions()
+})
+
+// Start all jobs at once
+RecurringJobs.startProcessing()
+
+// Or start individually
+report.startProcessing()
+cleanup.startProcessing()
+```
+
+### Inspecting and Rescheduling
+
+```ts
+const job = RecurringJobs.get('daily-report')
+if (job) {
+  const next = await job.getNextUp()
+  if (next) {
+    // Delay the next run by 2 hours
+    const delayed = new Date(new Date(next.scheduledDate).getTime() + 2 * 60 * 60 * 1000)
+    await job.rescheduleJob({
+      jobId: next.id,
+      scheduledDate: delayed.toISOString() as Iso.Instant
+    })
+  }
+}
+```
+
+### Per-Job Logger
+
+Add a dedicated logger to a specific job for fine-grained observability:
+
+```ts
+const jobLogger: Log.LogFunctions<[RecurringJobs.LogMessage]> = {
+  write({ data: [msg] }) {
+    if (msg.event === 'jobFailed') {
+      alertOpsTeam(msg.job, msg.error)
+    }
+  }
+}
+
+const criticalJob = RecurringJobs.createJob({
+  name: 'payment-reconciliation',
+  cron: '0 */4 * * *',
+  workFn: async () => reconcilePayments(),
+  logger: jobLogger
+})
+```
+
+### Execution History
+
+```ts
+const job = RecurringJobs.get('daily-report')
+if (job) {
+  const runs = await job.list({ pageSize: 50, pageNumber: 0 })
+  const failures = runs.filter(r => r.status === 'error')
+  const avgRuntime = runs
+    .filter(r => r.runningTime !== null)
+    .reduce((sum, r) => sum + r.runningTime!, 0) / runs.length
+}
+```
+
+## Log Events
+
+The service emits structured log events of type `RecurringJobs.LogMessage`:
+
+| Event | Level | Description |
+|---|---|---|
+| `jobProcessing` | info | A job message was dequeued and is about to execute |
+| `jobSucceeded` | info | The work function completed successfully |
+| `jobFailed` | error | The work function threw an error |
+| `jobScheduled` | info | The next run was enqueued with its scheduled date |
+| `jobAlreadyScheduled` | info | A waiting job already exists; skip enqueueing |
+| `jobSchedulingFailed` | error | Failed to enqueue the next run |
+
+## Cross-Package Integration
+
+### Dependencies
+
+- **@maestro-js/service-registry** -- foundation for the Provider pattern (registry, deferred Proxy resolution)
+- **@maestro-js/queue** -- each recurring job creates a dedicated queue via `queueService.create()`. Queue handles message persistence, polling, dequeuing, and lifecycle transitions
+- **@maestro-js/log** -- structured logging with pluggable transports for job lifecycle events
+
+### How It Connects
+
+RecurringJobs wraps Queue to add cron scheduling semantics. When `startProcessing()` is called, the next cron-derived date is computed and a queue message is enqueued for that date. When the Queue dequeues and runs the message, the work function fires and the next run is enqueued before the work executes. This ensures schedule continuity even on failure.
+
+Queue itself depends on Db (MySQL) for message persistence, so the full dependency chain is:
+
+```
+RecurringJobs -> Queue -> Db (MySQL)
+              -> Log
+              -> ServiceRegistry
+```
+
+### Provider Pattern
+
+This package follows the standard maestro Provider pattern:
+
+1. `RecurringJobs.Provider.create(config)` -- factory that instantiates the service
+2. `RecurringJobs.Provider.register(name, service)` -- registers the instance by name
+3. `RecurringJobs.provider(key)` -- resolves a named instance (deferred via Proxy)
+4. `RecurringJobs.*` -- facade that spreads `provider('default')` for direct method access
+
+## Notes
+
+- No tests exist for this package yet (`pnpm --filter @maestro-js/recurring-jobs test` prints "No tests yet").
+- The `cron-parser` library validates cron expressions at job creation time; invalid expressions throw immediately.
+- Deduplication: `startProcessing()` checks for an existing waiting message before enqueueing, preventing double-fires across process restarts.
+- The next run is enqueued inside the queue's `workFn` (before the user's `workFn` runs), so the schedule continues even if the current execution fails.
+- Only the next waiting job can be rescheduled via `rescheduleJob()`. Attempting to reschedule a non-waiting or non-next job throws an error.

package/dist/maestro-packages/sql.md

@@ -0,0 +1,316 @@
+---
+name: sql
+description: "Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions (CTEs). Use when working with @maestro-js/sql, building dynamic SQL filters, constructing parameterized WHERE clauses, wrapping Db services with CTEs, or generating safe parameterized SQL fragments. Key capabilities: WhereClauseBuilder for incremental AND/OR conditions with nested sub-groups, CommonTableExpressionBuilder for wrapping a Db service so all queries auto-prepend WITH clauses, cloning builders, recursive CTEs, and dynamic parameter resolution."
+---
+
+# @maestro-js/sql
+
+Composable SQL query builders for constructing parameterized WHERE clauses and Common Table Expressions (CTEs). Standalone utility package with no runtime dependencies on other maestro packages.
+
+## Quick Setup
+
+```ts
+import { Sql } from '@maestro-js/sql'
+
+// Dynamic WHERE clause
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and('price > ?', [50])
+await Db.select(`SELECT * FROM products WHERE ${where.query}`, where.parameters)
+
+// CTE wrapping a Db service
+const withTotals = Sql.cte({
+  orderTotals: { subquery: '(SELECT userId, SUM(amount) as total FROM orders GROUP BY userId)', params: [] }
+}, Db)
+await withTotals.select('SELECT * FROM orderTotals WHERE total > ?', [500])
+```
+
+## WHERE Clause Builder
+
+Build parameterized SQL WHERE clauses incrementally with `Sql.where()`. Conditions are appended via `and()` and `or()`. If no conditions are added, `query` returns `'TRUE'`.
+
+### Basic Conditions
+
+```ts
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and('created_at > ?', ['2024-01-01'])
+// where.query       => 'status = ? AND created_at > ?'
+// where.parameters  => ['active', '2024-01-01']
+```
+
+### Mixed AND/OR
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.or('b = ?', [2])
+where.and('c = ?', [3])
+// where.query       => 'a = ? OR b = ? AND c = ?'
+// where.parameters  => [1, 2, 3]
+```
+
+### Nested Groups (Parenthesized Sub-Conditions)
+
+Pass a callback to `and()` or `or()` to create parenthesized groups using a sub-builder:
+
+```ts
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and(sub => {
+  sub.or('role = ?', ['admin'])
+  sub.or('role = ?', ['editor'])
+})
+// where.query       => 'status = ? AND (role = ? OR role = ?)'
+// where.parameters  => ['active', 'admin', 'editor']
+```
+
+### Deeply Nested Groups
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.or(qb => {
+  qb.and('b = ?', [2])
+  qb.or(iqb => {
+    iqb.and('c = ?', [3])
+    iqb.and('d = ?', [4])
+  })
+})
+// where.query       => 'a = ? OR (b = ? OR (c = ? AND d = ?))'
+// where.parameters  => [1, 2, 3, 4]
+```
+
+### IN Clauses
+
+```ts
+const where = Sql.where()
+where.and('id IN (?)', [[1, 2, 3]])
+// where.query       => 'id IN (?)'
+// where.parameters  => [[1, 2, 3]]
+```
+
+### Cloning
+
+Pass an existing builder to `Sql.where()` to clone it. The clone is independent of the original:
+
+```ts
+const original = Sql.where()
+original.and('a = ?', [1])
+
+const clone = Sql.where(original)
+clone.and('b = ?', [2])
+
+// original.query => 'a = ?'
+// clone.query    => 'a = ? AND b = ?'
+```
+
+### Empty Sub-Builder
+
+If a callback adds no conditions, the group is silently skipped:
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.and(sub => {
+  // no conditions added
+})
+// where.query => 'a = ?'
+```
+
+## CTE Builder (Common Table Expressions)
+
+Wrap a Db service with `Sql.cte()` so every query method auto-prepends the `WITH` clause and merges CTE parameters before the query parameters.
+
+### Basic CTE
+
+```ts
+const withStats = Sql.cte({
+  userStats: {
+    subquery: '(SELECT userId, COUNT(*) as total FROM orders GROUP BY userId)',
+    params: []
+  }
+}, Db)
+
+const results = await withStats.select('SELECT * FROM userStats WHERE total > ?', [10])
+// Executes: WITH userStats AS (SELECT userId, COUNT(*) ...) SELECT * FROM userStats WHERE total > ?
+// Parameters: [10]
+```
+
+### Multiple CTEs
+
+```ts
+const builder = Sql.cte({
+  activeUsers: {
+    subquery: '(SELECT * FROM users WHERE active = ?)',
+    params: [true]
+  },
+  recentOrders: {
+    subquery: '(SELECT * FROM orders WHERE created_at > ?)',
+    params: ['2024-01-01']
+  }
+}, Db)
+
+await builder.select('SELECT * FROM activeUsers JOIN recentOrders ON activeUsers.id = recentOrders.userId')
+// WITH activeUsers AS (...), recentOrders AS (...) SELECT ...
+// Parameters: [true, '2024-01-01']
+```
+
+### Recursive CTEs
+
+Set `recursive: true` on any expression to trigger `WITH RECURSIVE`:
+
+```ts
+const builder = Sql.cte({
+  hierarchy: {
+    subquery: '(SELECT id, parentId, name FROM categories WHERE parentId IS NULL UNION ALL SELECT c.id, c.parentId, c.name FROM categories c JOIN hierarchy h ON c.parentId = h.id)',
+    params: [],
+    recursive: true
+  }
+}, Db)
+// WITH RECURSIVE hierarchy AS (...)
+```
+
+### Dynamic Parameters
+
+Pass a function for `params` to resolve values at query time:
+
+```ts
+const builder = Sql.cte({
+  filtered: {
+    subquery: '(SELECT * FROM items WHERE tenant_id = ?)',
+    params: () => [getCurrentTenantId()]
+  }
+}, Db)
+```
+
+### Re-Wrapping with fromDbService
+
+Use `fromDbService()` to apply the same CTEs to a different Db service (e.g., inside a transaction):
+
+```ts
+const cteBuilder = Sql.cte({ ... }, Db)
+const txResult = await Db.transaction(async () => {
+  const txCte = cteBuilder.fromDbService(TxDb)
+  return txCte.select('SELECT * FROM ...')
+})
+```
+
+### Wrapped Methods
+
+The CTE builder exposes all standard Db methods: `select`, `selectIterable`, `insert`, `update`, `delete`, `statement`, `scalar`, `format`, `transaction`.
+
+## API Reference
+
+### Sql.where(existing?)
+
+Create a new WhereClauseBuilder. Pass an existing builder to clone it.
+
+```ts
+function WhereClauseBuilder(existing?: WhereClauseBuilder): WhereClauseBuilder
+```
+
+**WhereClauseBuilder interface:**
+
+| Member       | Type                                                   | Description                                              |
+|--------------|--------------------------------------------------------|----------------------------------------------------------|
+| `and()`      | `(condition: string \| Callback, params?: any[]) => void` | Append condition with AND, or parenthesized group via callback |
+| `or()`       | `(condition: string \| Callback, params?: any[]) => void` | Append condition with OR, or parenthesized group via callback  |
+| `query`      | `string` (readonly getter)                             | Assembled clause string, or `'TRUE'` if empty            |
+| `parameters` | `any[]` (readonly getter)                              | Parameter array matching `?` placeholders in query       |
+
+### Sql.cte(expressions, db)
+
+Create a CTE builder wrapping a Db service.
+
+```ts
+function CommonTableExpressionBuilder(
+  commonTableExpressions: CommonTableExpressionSet,
+  db: CteDbService
+): CteDbService & { fromDbService(db: CteDbService): CteDbService }
+```
+
+**CommonTableExpressionSet:**
+
+```ts
+interface CommonTableExpressionSet {
+  [name: string]: {
+    subquery: string                    // CTE body wrapped in parentheses
+    params?: any[] | (() => any[])      // Static array or dynamic resolver
+    recursive?: boolean                 // Triggers WITH RECURSIVE
+  }
+}
+```
+
+### Type Exports
+
+Access types through the `Sql` namespace:
+
+```ts
+Sql.cte.Expression     // CommonTableExpressionConfig
+Sql.cte.ExpressionSet  // CommonTableExpressionSet
+Sql.cte.DbService      // CteDbService
+Sql.where.Builder      // WhereClauseBuilder
+Sql.where.Callback     // WhereClauseCallback
+```
+
+`Sql.commonTableExpression` is an alias for `Sql.cte` (both the function and its namespace types).
+
+## Important: Avoid Table Name Aliases
+
+When writing SQL queries with these builders, avoid table name aliases when possible. Write full table names for clarity:
+
+```ts
+// Preferred
+where.and('users.status = ?', ['active'])
+await builder.select('SELECT users.id, orders.total FROM users JOIN orders ON users.id = orders.userId')
+
+// Avoid
+where.and('u.status = ?', ['active'])
+await builder.select('SELECT u.id, o.total FROM users u JOIN orders o ON u.id = o.userId')
+```
+
+## Testing
+
+```bash
+# Run tests
+pnpm --filter @maestro-js/sql test
+
+# Single test file
+cd packages/sql && npx beartest ./tests/where-clause.test.ts
+
+# Typecheck
+pnpm --filter @maestro-js/sql typecheck
+```
+
+Tests use `beartest-js` with `expect` for assertions. Test file location: `packages/sql/tests/where-clause.test.ts`.
+
+## Cross-Package Integration
+
+- **No runtime dependencies** on other maestro packages
+- **Works with @maestro-js/db**: SQL builders produce `{ query, parameters }` pairs for Db to execute. The CTE builder wraps a Db service (or any object matching `CteDbService`) to auto-prepend WITH clauses.
+- **@maestro-js/db is a devDependency** only, used for the `CteDbService` type interface
+
+### Typical Usage with Db
+
+```ts
+import { Sql } from '@maestro-js/sql'
+import { Db } from '@maestro-js/db'
+
+// WHERE builder feeds into Db.select
+const where = Sql.where()
+where.and('active = ?', [true])
+if (minPrice) where.and('price >= ?', [minPrice])
+if (category) where.and('category = ?', [category])
+
+const products = await Db.select(`SELECT * FROM products WHERE ${where.query}`, where.parameters)
+
+// CTE builder wraps Db directly
+const withMetrics = Sql.cte({
+  dailySales: {
+    subquery: '(SELECT DATE(created_at) as day, SUM(amount) as total FROM orders GROUP BY DATE(created_at))',
+    params: []
+  }
+}, Db)
+const trends = await withMetrics.select('SELECT * FROM dailySales WHERE total > ?', [1000])
+```