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

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/tracing.md

@@ -0,0 +1,240 @@
+---
+name: tracing
+description: "Distributed tracing package built on OpenTelemetry with pluggable providers (Sentry, Maestro). Use when working with @maestro-js/tracing. Key capabilities: wrap functions for automatic span tracking, create active spans with duration measurement, proxy entire objects for tracing, serialize/deserialize trace context across process boundaries (dehydrate/hydrate), add custom log transports for span events, integrate Sentry as a tracing provider."
+---
+
+# @maestro-js/tracing
+
+Distributed tracing built on OpenTelemetry. Tracks function calls, durations, and parent/child relationships across the request lifecycle with pluggable providers (Sentry or the built-in Maestro tracer).
+
+## Quick Setup
+
+```ts
+import { Tracing } from '@maestro-js/tracing'
+
+// Use the default Maestro tracer (works out of the box)
+const result = Tracing.startActiveSpan('my-operation', () => {
+  return doWork()
+})
+
+// Or set Sentry as the provider
+import * as Sentry from '@sentry/node'
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+## Providers
+
+### Maestro (default)
+
+The `MaestroTracerProvider` is set as the global OpenTelemetry tracer provider automatically on import. It wraps every span to capture attributes, start/end times, and parent span IDs, then logs them through the built-in `Log` transport system.
+
+No configuration required -- it works immediately.
+
+### Sentry
+
+Pass a Sentry SDK instance to configure Sentry as the tracing backend. The factory sets up the `SentrySampler`, `SentrySpanProcessor`, `SentryPropagator`, and `SentryContextManager`.
+
+```ts
+import * as Sentry from '@sentry/node'
+import { Tracing } from '@maestro-js/tracing'
+
+Sentry.init({ dsn: '...', tracesSampleRate: 1.0 })
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+The Sentry provider expects an object with:
+- `getClient()` -- returns the Sentry client
+- `SentryContextManager` -- the context manager constructor
+- `validateOpenTelemetrySetup()` -- validates the OTEL integration
+
+## API Reference
+
+### `Tracing.startActiveSpan(name, fn)`
+
+Start a span that becomes the active span for the duration of `fn`. Automatically ends the span when `fn` returns or when the returned Promise resolves/rejects.
+
+```ts
+// Simple string name
+Tracing.startActiveSpan('fetch-user', () => {
+  return db.query('SELECT * FROM users WHERE id = ?', [userId])
+})
+
+// With SpanOptions
+Tracing.startActiveSpan({ name: 'fetch-user', attributes: { userId } }, () => {
+  return db.query('SELECT * FROM users WHERE id = ?', [userId])
+})
+```
+
+### `Tracing.wrap(name, fn)`
+
+Return a new function that automatically creates a span on every invocation. The wrapped function preserves the original function's properties.
+
+```ts
+const tracedFetch = Tracing.wrap('fetch-data', fetchData)
+await tracedFetch(url) // each call creates a span
+```
+
+### `Tracing.isWrapped(fn)`
+
+Check whether a function has already been wrapped by the current tracer.
+
+```ts
+if (!Tracing.isWrapped(myFn)) {
+  myFn = Tracing.wrap('myFn', myFn)
+}
+```
+
+### `Tracing.proxy(obj, options?)`
+
+Wrap an entire object so every function call on it is traced. Nested objects are proxied recursively with dotted tracer names. Use `options.ignore` to skip specific properties.
+
+```ts
+const tracedService = Tracing.proxy(userService)
+await tracedService.findById(123) // creates span "findById"
+
+// Ignore specific methods
+const tracedService = Tracing.proxy(userService, {
+  ignore: ({ name }) => name === 'toString'
+})
+```
+
+The `ignore` option accepts a single predicate or an array of predicates with signature `(options: { name: string; tracer: string | null }) => boolean`.
+
+### `Tracing.getTracer(name)`
+
+Get a named tracer for a specific package or module. Returns an object with `wrap`, `proxy`, `startActiveSpan`, and `isWrapped` scoped to that tracer name.
+
+```ts
+const { wrap, startActiveSpan, proxy } = Tracing.getTracer('my-package')
+```
+
+The default export (`Tracing.wrap`, `Tracing.startActiveSpan`, etc.) uses the `'maestro'` tracer.
+
+### `Tracing.getActiveSpan()`
+
+Return the currently active OpenTelemetry span, or `undefined` if none.
+
+```ts
+const span = Tracing.getActiveSpan()
+span?.setAttribute('user.id', userId)
+```
+
+### `Tracing.addTransport(transport)`
+
+Add a log transport that receives a `TraceLogMessage` for every completed span.
+
+```ts
+Tracing.addTransport({
+  info(message: Tracing.LogMessage) {
+    console.log(`[${message.name}] ${message.endTime - message.startTime}ms`)
+  }
+})
+```
+
+`TraceLogMessage` shape:
+- `name` -- span name
+- `id` -- span ID
+- `parentId` -- parent span ID or `null`
+- `startTime` / `endTime` -- `performance.now()` timestamps
+- `instrumentation` -- instrumentation library name or `null`
+- `attributes` -- key-value span attributes
+
+### `Tracing.dehydrate()`
+
+Serialize the current trace context for transmission across process boundaries (e.g., into a queue job payload). Returns `null` if no active span.
+
+```ts
+const serialized = Tracing.dehydrate()
+// { traceId, spanId, traceFlags, traceState }
+```
+
+### `Tracing.hydrate(trace, callback)`
+
+Restore a serialized trace context and execute `callback` within it. The hydrated span is marked as remote, establishing the parent/child relationship across processes.
+
+```ts
+Tracing.hydrate(serializedTrace, () => {
+  // This runs within the original trace context
+  Tracing.startActiveSpan('process-job', () => {
+    return processJob(payload)
+  })
+})
+```
+
+### `Tracing.setProvider(provider)`
+
+Set the underlying OpenTelemetry `TracerProvider` delegate. The `MaestroTracerProvider` wraps this delegate to add logging and instrumentation.
+
+```ts
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+## Common Patterns
+
+### Trace a queue job across processes
+
+```ts
+// Producer: serialize trace context into the job payload
+Tracing.startActiveSpan('enqueue-email', () => {
+  const trace = Tracing.dehydrate()
+  Queue.dispatch('send-email', { to, subject, body, trace })
+})
+
+// Consumer: restore trace context when processing the job
+function handleSendEmail(payload) {
+  Tracing.hydrate(payload.trace, () => {
+    Tracing.startActiveSpan('send-email', () => {
+      return mail.send(payload)
+    })
+  })
+}
+```
+
+### Trace an entire service object
+
+```ts
+const rawService = {
+  async getUser(id: number) { /* ... */ },
+  async updateUser(id: number, data: any) { /* ... */ },
+  helpers: {
+    formatName(user: any) { /* ... */ }
+  }
+}
+// All methods (including nested helpers.formatName) get spans
+const service = Tracing.proxy(rawService)
+```
+
+### Create a package-scoped tracer
+
+```ts
+const { wrap, startActiveSpan } = Tracing.getTracer('billing')
+
+export const createInvoice = wrap('createInvoice', async (order: Order) => {
+  return startActiveSpan('validate', () => validateOrder(order))
+})
+```
+
+## Cross-Package Integration
+
+- **@maestro-js/log** -- `MaestroTracerProvider` uses `Log.create()` internally; span completion events are emitted through the log transport system
+- **@maestro-js/context** -- spans preserve `AsyncLocalStorage` context; `Context.runWith` is used to restore the correct store when logging span events
+- **@maestro-js/queue** -- use `dehydrate`/`hydrate` to propagate trace context through queue job payloads
+
+## Types
+
+```ts
+declare namespace Tracing {
+  type Attributes = TracingAttributes
+  type LogMessage = TraceLogMessage
+  type Provider = api.TracerProvider
+  type DehydratedTrace = SerializedTrace
+}
+```
+
+## Package Info
+
+- **Package**: `@maestro-js/tracing`
+- **Dependencies**: `@opentelemetry/api`, `@opentelemetry/sdk-trace-node`, `@sentry/opentelemetry`, `@maestro-js/log`, `@maestro-js/context`
+- **No tests currently** (`echo 'No tests yet'`)
+- Build: `pnpm --filter @maestro-js/tracing build`
+- Typecheck: `pnpm --filter @maestro-js/tracing typecheck`

package/package.json

@@ -2,22 +2,21 @@
   "name": "@maestro-js/agent-skills",
   "description": "Agent skills for the @maestro-js framework.",
   "type": "module",
-  "bin": {
-    "maestro-skills": "./dist/bin.js"
-  },
   "exports": {
-    "./package.json": "./package.json"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "devDependencies": {
     "@types/node": "^22.19.11"
   },
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.2",
   "publishConfig": {
     "access": "restricted"
   },
   "files": [
-    "dist",
-    "skills"
+    "dist"
   ],
   "license": "UNLICENSED",
   "engines": {
@@ -28,7 +27,7 @@
     "generate-skills": "node scripts/generate-package-skills.ts",
     "generate-choosing-npm-package-skill": "node scripts/generate-choosing-npm-package-skill.ts",
     "generate-maestro-cli-skill": "node scripts/generate-maestro-cli-skill.ts",
-    "build": "node scripts/build.ts && tsup",
+    "build": "node scripts/generate-package-skills.ts && node scripts/generate-choosing-npm-package-skill.ts && node scripts/generate-maestro-cli-skill.ts",
     "typecheck": "tsc --noEmit"
   }
 }

package/dist/bin.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-
-// src/bin.ts
-import path from "path";
-import { spawnSync } from "child_process";
-import { parseArgs } from "util";
-var { values } = parseArgs({
-  options: {
-    interactive: { type: "boolean", default: false },
-    copy: { type: "boolean", default: false }
-  },
-  strict: false
-});
-var skillsPath = path.resolve(import.meta.dirname, "..");
-var args = ["skills", "add", skillsPath, "-a", "claude-code"];
-if (!values.interactive) args.push("-s", "*", "-y");
-if (values.copy) args.push("--copy");
-var result = spawnSync("npx", args, { stdio: "inherit" });
-if (result.status !== 0) process.exit(1);