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

package/dist/maestro-packages/log.md

@@ -0,0 +1,321 @@
+---
+name: log
+description: "Structured logging with pluggable transports and channel-based routing for the Maestro framework. Use when working with @maestro-js/log, adding or modifying log transports, configuring log channels, filtering log messages by level or channel, integrating logging into other packages, or writing tests that capture log output. Key capabilities: create loggers with pluggable transports (console, file, Sentry, stub), route messages through named channels, filter by level and channel, override Node.js console, custom formatters, and the silence transport for suppressing output."
+---
+
+# @maestro-js/log
+
+Structured logging with pluggable transports and channel-based routing. Messages have a severity level (`emergency`, `error`, `warn`, `info`) and an optional channel for routing to specific transports.
+
+## Quick Setup
+
+```ts
+import { Log } from '@maestro-js/log'
+
+// Use the default logger directly (falls back to console if no transports added)
+Log.info('Server started on port', 3000)
+
+// Or create an independent logger with transports
+const logger = Log.create({
+  transports: [
+    Log.transports.console(),
+    Log.transports.file({ filename: '/var/log/app.log' })
+  ]
+})
+
+logger.info('Server started on port', 3000)
+logger.error('Connection failed', err)
+```
+
+## Architecture
+
+The package does NOT use the service-registry Provider pattern. Instead it exports a `Log` object that acts as a default logger facade and a `Log.create()` factory for independent logger instances.
+
+### Source Files
+
+- `packages/log/src/index.ts` -- Main entry: `Log.create()`, default logger facade, `Log.transports` namespace
+- `packages/log/src/log-types.ts` -- Core types: `LogLevel`, `LogChannel`, `LogMessage`, `LogTransport`, `LogMessageFilter`, `LogFormatter`
+- `packages/log/src/console-transport.ts` -- Console transport with colorized output
+- `packages/log/src/file-transport.ts` -- File transport with streaming writes and `flush()`
+- `packages/log/src/sentry-transport.ts` -- Sentry error/message capture transport
+- `packages/log/src/sentry-breadcrumbs-transport.ts` -- Sentry breadcrumbs transport
+- `packages/log/src/stub-transport.ts` -- In-memory transport for testing
+- `packages/log/src/transport-helpers.ts` -- `parseLogMessageFilter()` utility
+
+### Key Types
+
+```ts
+type LogLevel = 'emergency' | 'error' | 'warn' | 'info'
+type LogChannel = string | null
+
+interface LogMessage<LogMessageData extends any[] = any[]> {
+  data: LogMessageData
+  level: LogLevel
+  channel: LogChannel
+  time: Iso.Instant
+}
+
+interface LogTransport<LogMessageData extends any[] = any[]> {
+  write(message: LogMessage<LogMessageData>): void
+}
+
+type LogMessageFilter<LogMessageData extends any[] = any[]> =
+  | { level?: LogLevel | LogLevel[]; channel?: LogChannel | LogChannel[] }
+  | ((message: LogMessage<LogMessageData>) => boolean)
+  | undefined
+```
+
+## Transports
+
+All transports accept an optional `filter` for level/channel-based routing.
+
+### Console Transport
+
+Colorized output to stdout with configurable formatting.
+
+```ts
+Log.transports.console()
+Log.transports.console({ filter: { level: ['error', 'emergency'] } })
+Log.transports.console({ format: (message) => `${message.level}: ${message.data.join(' ')}\n` })
+// Pass InspectOptions instead of a formatter function
+Log.transports.console({ format: { colors: true, depth: 4 } })
+```
+
+### File Transport
+
+Appends log messages to a file via streaming. Creates the directory if it does not exist. Returns a transport with an additional `flush()` method.
+
+```ts
+const fileTransport = Log.transports.file({
+  filename: '/var/log/app.log',
+  filter: { level: ['error', 'emergency'] },
+  format: (message) => JSON.stringify(message) + '\n'
+})
+
+// Ensure all buffered writes are flushed to disk
+await fileTransport.flush()
+```
+
+### Sentry Transport
+
+Captures errors and messages to Sentry. Errors at `error`/`emergency` level use `captureException`; other levels use `captureMessage`.
+
+```ts
+import * as Sentry from '@sentry/node'
+
+Log.transports.sentry({
+  sentry: Sentry,
+  filter: { level: ['error', 'emergency'] },
+  getCaptureContext(message) {
+    return {
+      tags: { channel: message.channel ?? 'default' },
+      extra: {},
+      level: message.level === 'emergency' ? 'fatal' : message.level
+    }
+  }
+})
+```
+
+### Sentry Breadcrumbs Transport
+
+Adds log messages as Sentry breadcrumbs for context on future error captures.
+
+```ts
+import * as Sentry from '@sentry/node'
+
+Log.transports.sentryBreadcrumbs({
+  sentry: Sentry,
+  filter: { level: ['info', 'warn'] }
+})
+```
+
+### Stub Transport
+
+In-memory transport for testing. Captures messages and provides `listMessages()` and `reset()`.
+
+```ts
+const stub = Log.transports.stub()
+const logger = Log.create({ transports: [stub] })
+
+logger.info('test message')
+stub.listMessages() // => [{ data: ['test message'], level: 'info', channel: null, time: '...' }]
+stub.reset()
+```
+
+### Silence Transport
+
+Suppresses all output. Use to disable logging entirely.
+
+```ts
+Log.addTransport(Log.transports.silence)
+```
+
+## API Reference
+
+### `Log.create(config?)`
+
+Create an independent logger instance.
+
+```ts
+const logger = Log.create({
+  transports: [Log.transports.console()]
+})
+```
+
+### Default Logger Facade
+
+Call logging methods directly on `Log` without creating an instance.
+
+```ts
+Log.addTransport(Log.transports.console())
+Log.info('message', data)
+Log.warn('slow query', { durationMs: 500 })
+Log.error('failed', new Error('timeout'))
+Log.emergency('system down')
+Log.removeTransport(someTransport)
+```
+
+### Logging Methods
+
+- `info(...data)` -- Log at info level
+- `warn(...data)` -- Log at warn level
+- `error(...data)` -- Log at error level
+- `emergency(...data)` -- Log at emergency level
+- `write(message)` -- Write a raw log message (supply `level`, `data`, and `time` yourself)
+
+### Channels
+
+Create channel-scoped sub-loggers that tag every message with a channel name. Transports can filter by channel.
+
+```ts
+const logger = Log.create({ transports: [Log.transports.console()] })
+const dbLog = logger.channel('database')
+dbLog.info('Query executed', { table: 'users', durationMs: 12 })
+dbLog.warn('Slow query detected')
+
+// Filter transport to only receive database channel messages
+Log.transports.console({ filter: { channel: 'database' } })
+```
+
+### `Log.overrideNodeJsConsole(logger)`
+
+Replace global `console.log`, `console.warn`, `console.error`, `console.info`, and `console.debug` with methods from the provided logger. Returns a restore function.
+
+```ts
+const restore = Log.overrideNodeJsConsole(logger)
+console.log('now goes through logger')
+restore() // restores original console methods
+```
+
+## Filtering
+
+Transports accept a `filter` option that controls which messages reach them.
+
+```ts
+// Filter by level
+Log.transports.console({ filter: { level: 'error' } })
+Log.transports.console({ filter: { level: ['error', 'emergency'] } })
+
+// Filter by channel
+Log.transports.console({ filter: { channel: 'database' } })
+
+// Filter by both level and channel
+Log.transports.console({ filter: { level: 'error', channel: 'database' } })
+
+// Custom filter function
+Log.transports.console({
+  filter: (message) => message.level === 'error' && message.data.some((d) => d instanceof Error)
+})
+```
+
+## Fallback Behavior
+
+When a logger has no transports registered, it falls back to a default `ConsoleTransport()`. Add `Log.transports.silence` to explicitly suppress all output.
+
+## Custom Transports
+
+Implement the `LogTransport` interface.
+
+```ts
+const customTransport: Log.Transport = {
+  write(message) {
+    // message.data, message.level, message.channel, message.time
+    fetch('https://log-service.example.com', {
+      method: 'POST',
+      body: JSON.stringify(message)
+    })
+  }
+}
+```
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/log test
+cd packages/log && npx beartest ./tests/log.test.ts
+```
+
+Use `StubTransport` to capture and assert on log output:
+
+```ts
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { Log } from '@maestro-js/log'
+
+test('should capture log messages', () => {
+  const stub = Log.transports.stub()
+  const logger = Log.create({ transports: [stub] })
+
+  logger.info('test')
+
+  const messages = stub.listMessages()
+  expect(messages).toHaveLength(1)
+  expect(messages[0].level).toBe('info')
+  expect(messages[0].data).toEqual(['test'])
+
+  stub.reset()
+})
+```
+
+Use inline transports for targeted assertions:
+
+```ts
+test('should write to transport', () => {
+  const messages: Log.Message[] = []
+  const log = Log.create()
+  log.addTransport({ write(message) { messages.push(message) } })
+
+  log.info('log')
+  expect(messages).toHaveLength(1)
+})
+```
+
+## Cross-Package Integration
+
+Log is used widely across Maestro packages as the standard logging mechanism:
+
+- **queue, recurring-jobs, mail** -- Log job processing, email sending, and scheduling events
+- **db** -- Log queries and connection events
+- **cache, events, broadcast** -- Log cache operations and event dispatching
+- **metrics, exceptions** -- Log metric collection and exception handling
+
+Typical integration pattern in other packages:
+
+```ts
+import { Log } from '@maestro-js/log'
+
+const log = Log.create()
+// or use Log.info(), Log.error() directly via the default facade
+```
+
+### Context Integration
+
+Combine with `@maestro-js/context` (AsyncLocalStorage) for request-scoped logging by passing contextual data through log message data arguments.
+
+## Dependencies
+
+- `colorette` -- Terminal color support for console transport
+- `iso-fns2` -- ISO timestamp types (`Iso.Instant`)
+- `@sentry/types` (devDependency) -- Sentry type definitions

package/dist/maestro-packages/mail.md

@@ -0,0 +1,365 @@
+---
+name: mail
+description: "Driver-based email sending with queued delivery, scheduled sending, and mailable templates for the @maestro-js/mail package. Use when working with @maestro-js/mail. Covers creating mail services with SendGrid/SES/MailTrap/Stub drivers, sending emails immediately or via queue, scheduling future delivery, building reusable mailable templates, processing webhook events, generating ICS calendar attachments, and testing with the stub driver."
+---
+
+# @maestro-js/mail
+
+Driver-based email sending with queued delivery, scheduled sending, and reusable mailable templates. Follows the Maestro Provider pattern with pluggable drivers (SendGrid, SES, MailTrap, Stub).
+
+## Quick Setup
+
+```ts
+import { Mail } from '@maestro-js/mail'
+import { Queue } from '@maestro-js/queue'
+import { Log } from '@maestro-js/log'
+
+// Create a logger for mail records
+const mailLogger = Log.createLogger<[Mail.LogMessage]>({ transports: [Log.transports.console()] })
+
+// Create and register the mail service
+const mailService = Mail.Provider.create({
+  driver: Mail.drivers.sendGrid(sendGridClient),
+  name: 'default',
+  globalFrom: { email: 'noreply@example.com', name: 'MyApp' },
+  logger: mailLogger,
+  queueService: Queue.provider('default')
+})
+Mail.Provider.register('default', mailService)
+```
+
+## Drivers
+
+### SendGrid
+
+```ts
+import sgMail from '@sendgrid/mail'
+sgMail.setApiKey(process.env.SENDGRID_API_KEY)
+const driver = Mail.drivers.sendGrid(sgMail)
+```
+
+The SendGrid driver accepts the `@sendgrid/mail` client. It passes `envelope.extras` as `customArgs` and supports webhook event normalization via `driver.toMailEvent(sgEvent)`.
+
+### SES
+
+```ts
+import { SESv2Client, SendRawEmailCommand } from '@aws-sdk/client-sesv2'
+const sesClient = new SESv2Client({ region: 'us-east-1' })
+const driver = Mail.drivers.ses(sesClient, 'my-configuration-set')
+```
+
+The SES driver requires a client adapter with a `send()` method and a configuration set name. It uses `nodemailer/MailComposer` to build raw MIME messages, sends per-recipient with retry (5 attempts, 3s delay), and passes `envelope.extras` as SES message tags. Supports webhook event normalization via `driver.toMailEvent(sesEvent)`.
+
+### MailTrap
+
+```ts
+import { MailtrapClient } from 'mailtrap'
+const mailtrapClient = new MailtrapClient({ token: process.env.MAILTRAP_TOKEN })
+const driver = Mail.drivers.mailTrap(mailtrapClient)
+```
+
+The MailTrap driver retries up to 10 attempts with 10s delay. It passes `envelope.extras` as `custom_variables`. Supports webhook event normalization via `driver.toMailEvent(mtEvent)`.
+
+### Stub
+
+```ts
+const driver = Mail.drivers.stub()
+// Or with logging:
+const driver = Mail.drivers.stub({ logger: myLogger })
+```
+
+The Stub driver returns success with random UUIDs as message IDs. Use for testing and development. Optionally accepts a logger to record sent envelopes.
+
+## API Reference
+
+### Mail.Provider.create(config)
+
+Create a mail service instance. Config fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `driver` | `Mail.Driver` | The mail driver instance |
+| `name` | `string` | Instance name, used for queue naming (`Maestro.Mail.{name}`) |
+| `globalFrom` | `Mail.Address` | Default sender, overridden by `envelope.from` |
+| `logger` | `Log.Logger<[Mail.LogMessage]>` | Logger for envelope and event records |
+| `queueService` | `Queue.QueueService` | Queue service for async delivery |
+| `onMessageSendFailure?` | `(envelope, error) => unknown` | Optional callback on send failure |
+
+### Mail.Provider.register(name, service)
+
+Register a service instance in the named registry.
+
+### Mail.send(envelope)
+
+Send an email immediately. Returns `{ success: boolean, messages: { id: string, email: string }[] }`. Addresses are trimmed, lowercased, and deduplicated automatically.
+
+```ts
+await Mail.send({
+  to: 'alice@example.com',
+  subject: 'Order Confirmed',
+  content: { html: '<h1>Thank you!</h1>' }
+})
+```
+
+### Mail.queue(envelope)
+
+Enqueue an email for immediate async processing by the queue worker. Does not block the current request.
+
+```ts
+Mail.queue({
+  to: 'bob@example.com',
+  subject: 'Password Reset',
+  content: { html: '<p>Click the link to reset your password.</p>' }
+})
+```
+
+### Mail.later(envelope, scheduledDate)
+
+Enqueue an email for delivery at a future date. The `scheduledDate` is an `Iso.Instant`.
+
+```ts
+Mail.later(
+  { to: 'user@example.com', subject: 'Reminder', content: { text: 'Your trial ends tomorrow.' } },
+  '2025-01-15T09:00:00Z' as Iso.Instant
+)
+```
+
+### Mail.provider(key)
+
+Resolve a named mail service instance. Returns `{ send, queue, later }`.
+
+```ts
+const transactional = Mail.provider('transactional')
+await transactional.send({ to: '...', subject: '...', content: { html: '...' } })
+```
+
+### Mail.mailable(name, renderFn)
+
+Register a reusable mailable template. The render function receives args and returns an `Envelope` or `Mail.EMPTY_ENVELOPE` to skip sending.
+
+```ts
+const OrderConfirmation = Mail.mailable('OrderConfirmation', async (args: { orderId: string }) => {
+  const order = await db.query('SELECT * FROM orders WHERE id = ?', [args.orderId])
+  return {
+    to: order.email,
+    subject: `Order #${order.id} Confirmed`,
+    content: { html: `<h1>Thank you, ${order.name}!</h1>` }
+  }
+})
+```
+
+#### Rendered Mailable Methods
+
+After calling `.render(args)`, the returned object provides:
+
+- **`send()`** -- Send immediately
+- **`queue()`** -- Enqueue for async processing
+- **`later(scheduledDate)`** -- Schedule for future delivery
+- **`content()`** -- Retrieve the generated content without sending
+- **`provider(key)`** -- Target a specific named mail service
+
+```ts
+// Send immediately
+await OrderConfirmation.render({ orderId: '1042' }).send()
+
+// Queue for async processing
+await OrderConfirmation.render({ orderId: '1042' }).queue()
+
+// Schedule for later
+await OrderConfirmation.render({ orderId: '1042' }).later('2025-06-01T12:00:00Z' as Iso.Instant)
+
+// Get content without sending
+const content = await OrderConfirmation.render({ orderId: '1042' }).content()
+
+// Use a specific provider
+await OrderConfirmation.render({ orderId: '1042' }).provider('transactional').send()
+```
+
+### Mail.EMPTY_ENVELOPE
+
+Return from a mailable render function to skip sending. Useful for conditional emails.
+
+```ts
+const WeeklyDigest = Mail.mailable('WeeklyDigest', async (args: { userId: string }) => {
+  const updates = await getUpdates(args.userId)
+  if (updates.length === 0) return Mail.EMPTY_ENVELOPE
+  return { to: '...', subject: 'Weekly Digest', content: { html: '...' } }
+})
+```
+
+### Mail.attachments.ics(options)
+
+Generate an ICS calendar attachment from structured options.
+
+```ts
+const attachment = Mail.attachments.ics({
+  title: 'Team Standup',
+  start: '2025-03-01T10:00:00Z' as Iso.Instant,
+  end: 'PT1H' as Iso.Duration, // 1-hour duration
+  location: 'Conference Room A',
+  organizer: { name: 'Alice', email: 'alice@example.com' },
+  attendees: [{ name: 'Bob', email: 'bob@example.com', rsvp: true }],
+  status: 'CONFIRMED',
+  alarms: [{ action: 'display', description: 'Standup in 15 min', trigger: '-PT15M' as Iso.Duration }]
+})
+
+await Mail.send({
+  to: 'bob@example.com',
+  subject: 'Team Standup Invite',
+  content: { html: '<p>You are invited to standup.</p>' },
+  attachments: [attachment]
+})
+```
+
+ICS options support `start` and `end` as `Iso.Instant`, `Iso.ZonedDateTime`, or `Iso.DateTime`. The `end` field also accepts `Iso.Duration`. Additional fields: `description`, `geo`, `url`, `busyStatus`, `categories`, `uid`, `method`, `recurrenceRule`, `sequence`, `calName`, `classification`, `created`, `lastModified`, `htmlContent`, `alarms`.
+
+## Envelope Type
+
+```ts
+interface Envelope {
+  to: Mail.Address | Mail.Address[]
+  from?: Mail.Address              // overrides globalFrom
+  cc?: Mail.Address | Mail.Address[]
+  bcc?: Mail.Address | Mail.Address[]
+  attachments?: Mail.Attachment[]
+  subject: string | null
+  content: { text: string } | { html: string }
+  headers?: {
+    listUnsubscribe?: string
+    listUnsubscribePost?: string
+    replyTo?: Mail.Address
+  }
+  category?: string | null
+  extras?: Record<string, string | null>
+}
+```
+
+The `Mail.Address` type is either a plain email string or `{ email: string, name?: string }`.
+
+## Common Patterns
+
+### Sending with Attachments
+
+```ts
+await Mail.send({
+  to: 'user@example.com',
+  subject: 'Your Invoice',
+  content: { html: '<p>Please find your invoice attached.</p>' },
+  attachments: [{
+    content: Buffer.from(pdfData).toString('base64'),
+    filename: 'invoice.pdf',
+    type: 'application/pdf',
+    disposition: 'attachment'
+  }]
+})
+```
+
+### Unsubscribe Headers
+
+```ts
+await Mail.send({
+  to: 'subscriber@example.com',
+  subject: 'Newsletter',
+  content: { html: '...' },
+  headers: {
+    listUnsubscribe: '<https://example.com/unsubscribe?id=123>',
+    listUnsubscribePost: 'List-Unsubscribe=One-Click'
+  },
+  category: 'newsletter'
+})
+```
+
+### Processing Webhook Events
+
+SendGrid, SES, and MailTrap drivers expose `toMailEvent()` to normalize provider-specific webhook payloads into a unified `Mail.Event` type.
+
+```ts
+// SendGrid webhook handler
+const sgDriver = Mail.drivers.sendGrid(sgMail) as SendGridMailDriver
+const event = sgDriver.toMailEvent(rawSendGridEvent) // returns MailEvent | null
+
+// SES webhook handler
+const sesDriver = Mail.drivers.ses(sesClient, 'config-set') as SesMailDriver
+const event = sesDriver.toMailEvent(rawSesEvent) // returns MailEvent | null
+
+// MailTrap webhook handler
+const mtDriver = Mail.drivers.mailTrap(mtClient) as MailTrapMailDriver
+const event = mtDriver.toMailEvent(rawMailTrapEvent) // returns MailEvent
+```
+
+The normalized `Mail.Event` includes: `eventId`, `event` (delivery, bounce, softBounce, open, click, unsubscribe, spamComplaint, reject, suspension), `email`, `messageId`, `timestamp`, `category`, `extras`, `driverName`.
+
+### Conditional Mailable with EMPTY_ENVELOPE
+
+```ts
+const InactivityReminder = Mail.mailable('InactivityReminder', async (args: { userId: string }) => {
+  const user = await getUser(args.userId)
+  if (user.lastActiveAt > thirtyDaysAgo) return Mail.EMPTY_ENVELOPE
+  return {
+    to: user.email,
+    subject: 'We miss you!',
+    content: { html: `<p>Hi ${user.name}, it has been a while...</p>` }
+  }
+})
+```
+
+### Error Handling with onMessageSendFailure
+
+```ts
+Mail.Provider.create({
+  driver: Mail.drivers.sendGrid(sgMail),
+  name: 'default',
+  globalFrom: { email: 'noreply@example.com' },
+  logger: mailLogger,
+  queueService: Queue.provider('default'),
+  onMessageSendFailure(envelope, error) {
+    Log.error({ message: 'Mail send failed', to: envelope.to, error })
+  }
+})
+```
+
+## Testing
+
+Use the Stub driver in tests to avoid real email delivery.
+
+```ts
+const stubDriver = Mail.drivers.stub()
+
+const mailService = Mail.Provider.create({
+  driver: stubDriver,
+  name: 'default',
+  globalFrom: { email: 'test@example.com' },
+  logger: testLogger,
+  queueService: testQueueService
+})
+Mail.Provider.register('default', mailService)
+
+// Emails go through the full pipeline but are not delivered
+await Mail.send({ to: 'user@example.com', subject: 'Test', content: { text: 'Hello' } })
+```
+
+To inspect sent envelopes, pass a logger to the stub driver:
+
+```ts
+const sent: Mail.Envelope[] = []
+const stubDriver = Mail.drivers.stub({
+  logger: { info: (envelope) => sent.push(envelope) } as any
+})
+```
+
+## Cross-Package Integration
+
+- **@maestro-js/service-registry** -- Provides the Provider pattern (`create`, `register`, `provider`, facade)
+- **@maestro-js/log** -- Used for structured mail logging (envelope records and webhook events)
+- **@maestro-js/queue** -- Powers `Mail.queue()` and `Mail.later()` for async and scheduled delivery. Queue names follow the pattern `Maestro.Mail.{name}` and `Maestro.Mailable.{name}`
+- **@maestro-js/helpers** -- Used by SES and MailTrap drivers for retry logic (`Helpers.retry()`)
+
+## Key Source Files
+
+- `packages/mail/src/index.ts` -- Main module, service creation, mailable system, facade export
+- `packages/mail/src/mail-types.ts` -- Type definitions (Envelope, Address, Content, Attachment, Event, Driver)
+- `packages/mail/src/send-grid-mail-driver.ts` -- SendGrid driver with webhook event mapping
+- `packages/mail/src/ses-mail-driver.ts` -- SES driver with raw MIME composition and retry
+- `packages/mail/src/mail-trap-mail-driver.ts` -- MailTrap driver with retry and webhook events
+- `packages/mail/src/stub-mail-driver.ts` -- Stub driver for testing
+- `packages/mail/src/ics-attachment.ts` -- ICS calendar attachment generator