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

package/dist/maestro-packages/broadcast.md

@@ -0,0 +1,306 @@
+---
+name: broadcast
+description: "\"Pattern-based event routing across channels and processes using @maestro-js/broadcast. Use when working with @maestro-js/broadcast, channel patterns, broadcast listeners, event name generation, or wildcard/dynamic-segment routing. Key capabilities: define typed channels with URL-like patterns (:id, optional segments, wildcards), emit and listen for events through a pluggable driver (e.g. Events/Redis), extract params from matched patterns, generate concrete event names from patterns, and manage listener lifecycles.\""
+---
+
+# @maestro-js/broadcast
+
+Pattern-based event routing that layers typed channels, dynamic-segment matching, and wildcard support on top of a pluggable driver (typically `@maestro-js/events`). Each channel is a typed event emitter scoped to a URL-like pattern; the driver distributes emitted events across processes.
+
+## Quick Setup
+
+```ts
+import { Broadcast } from '@maestro-js/broadcast'
+import { Events } from '@maestro-js/events'
+
+// 1. Define typed channels
+const userChannel = Broadcast.channel('/user/:id').create<{ name: string }>()
+const chatChannel = Broadcast.channel('/chat(/:room)').create<{ message: string }>()
+
+// 2. Create and register
+const broadcast = Broadcast.Provider.create({
+  channels: [userChannel, chatChannel],
+  driver: Events // any BroadcastingDriver
+})
+Broadcast.Provider.register('default', broadcast)
+
+// 3. Use via facade
+Broadcast.addListener('/user/42', {
+  handler({ data, params }) {
+    console.log(data.name, params.id)
+  }
+})
+
+const event = Broadcast.generateEventName('/user/:id', { id: '42' })
+Broadcast.emit(event, { name: 'Alice' })
+```
+
+## Channel Patterns and Parameters
+
+Patterns use `@remix-run/route-pattern` syntax. Three segment types:
+
+| Syntax | Example | Matches |
+|---|---|---|
+| `:param` | `/user/:id` | `/user/42` -> `{ id: '42' }` |
+| `(/:param)` | `/chat(/:room)` | `/chat` or `/chat/general` |
+| `*splat` | `/system/*splat` | `/system/logs/today` -> `{ splat: 'logs/today' }` |
+
+Matching is case-insensitive. Static patterns (e.g. `/health`) also work.
+
+### Pattern Matching
+
+Use `Broadcast.matchPattern` to test if an event name matches a pattern:
+
+```ts
+const match = Broadcast.matchPattern('/user/:id', '/user/42')
+// match.params.id === '42'
+// match.eventName === '/user/42'
+// match.eventNameBase === '/user/42'
+// match.pattern === '/user/:id'
+
+const noMatch = Broadcast.matchPattern('/user/:id', '/order/42')
+// noMatch === null
+```
+
+For wildcard patterns, `eventNameBase` strips the wildcard suffix:
+
+```ts
+const match = Broadcast.matchPattern('/system/*splat', '/system/logs/today')
+// match.params.splat === 'logs/today'
+// match.eventNameBase === '/system'
+```
+
+### Event Name Generation
+
+Interpolate params into a pattern to produce a concrete event name:
+
+```ts
+Broadcast.generateEventName('/user/:id', { id: '42' })
+// '/user/42'
+
+Broadcast.generateEventName('/org/:orgId/user/:userId', { orgId: 'acme', userId: '42' })
+// '/org/acme/user/42'
+
+Broadcast.generateEventName('/chat(/:room)', { room: 'general' })
+// '/chat/general'
+
+Broadcast.generateEventName('/chat(/:room)')
+// '/chat'
+```
+
+## API Reference
+
+### `Broadcast.channel(pattern)`
+
+Create a channel builder. Call `.create<EventData>()` to produce a typed `Channel`.
+
+```ts
+function channel<Pattern extends string>(pattern: Pattern): {
+  create<EventData extends Record<string, any>>(): Channel<Pattern, EventData>
+}
+```
+
+### `Broadcast.Provider.create(config)`
+
+Create a broadcast service instance from channels and a driver.
+
+```ts
+function create<Channels extends Channel<string, Record<string, any>>[]>(config: {
+  channels: Channels
+  driver: BroadcastingDriver
+}): BroadcastService<Channels>
+```
+
+Throws if duplicate channel patterns are provided.
+
+### `Broadcast.Provider.register(name, service)`
+
+Register the service instance in the named registry.
+
+### `Broadcast.provider(key)`
+
+Resolve a named broadcast instance. Returns the full `BroadcastService` interface.
+
+### `Broadcast.emit(eventName, data)`
+
+Broadcast data through the driver. Throws if the event name does not match any registered channel pattern.
+
+```ts
+Broadcast.emit('/user/42', { name: 'Alice' })
+```
+
+### `Broadcast.addListener(eventName, listener)`
+
+Subscribe to events matching a channel pattern. Returns a handle with `remove()`.
+
+```ts
+const handle = Broadcast.addListener('/user/42', {
+  handler({ data, params, eventName }) {
+    // data: { name: string }
+    // params: { id: string }
+    // eventName: '/user/42'
+  }
+})
+
+handle.remove() // unsubscribe
+```
+
+### `Broadcast.getChannel(pattern)`
+
+Retrieve a channel by its exact pattern string. Returns the channel without `emit` (read-only view).
+
+```ts
+const channel = Broadcast.getChannel('/user/:id')
+// channel.pattern === '/user/:id'
+// channel.addListener(...)
+```
+
+### `Broadcast.generateEventName(pattern, params)`
+
+Interpolate parameters into a pattern to produce a concrete event name string.
+
+### `Broadcast.matchPattern(pattern, eventName)`
+
+Test if an event name matches a pattern. Returns `EventNameMatch` or `null`.
+
+### `Broadcast.removeAllListeners()`
+
+Remove all active listeners from all channels and the driver.
+
+## BroadcastingDriver Interface
+
+Any driver must implement:
+
+```ts
+interface BroadcastingDriver {
+  emit(eventName: string, data: Record<string, any>): unknown
+  addListener(eventName: string, listener: (data: Record<string, any>) => void): unknown
+  removeListener(eventName: string, listener: (data: Record<string, any>) => void): unknown
+  removeAllListeners?(): unknown
+}
+```
+
+`@maestro-js/events` satisfies this interface. A minimal mock driver for testing:
+
+```ts
+const listeners: Map<string, Set<(data: Record<string, any>) => void>> = new Map()
+
+const mockDriver = {
+  emit(eventName: string, data: Record<string, any>) {
+    const set = listeners.get(eventName)
+    if (set) {
+      for (const listener of set) listener(data)
+    }
+  },
+  addListener(eventName: string, listener: (data: Record<string, any>) => void) {
+    if (!listeners.has(eventName)) listeners.set(eventName, new Set())
+    listeners.get(eventName)!.add(listener)
+  },
+  removeListener(eventName: string, listener: (data: Record<string, any>) => void) {
+    listeners.get(eventName)?.delete(listener)
+  }
+}
+```
+
+## Key Types
+
+```ts
+// Extracts union of dynamic param names from a pattern
+type PatternParam<Pattern extends string>
+
+// Match result from matchPattern
+interface EventNameMatch<Pattern extends string> {
+  params: PatternParams<Pattern>
+  eventName: string
+  eventNameBase: string
+  pattern: Pattern
+}
+
+// Listener object
+interface ChannelListener<Pattern extends string, EventData extends Record<string, any>> {
+  handler: (options: { data: EventData; params: PatternParams<Pattern>; eventName: string }) => void
+}
+
+// Handle returned by addListener
+type AddListenerResult = { remove(): void }
+```
+
+## Common Patterns
+
+### Multiple Named Providers
+
+```ts
+declare module '@maestro-js/broadcast' {
+  namespace Broadcast.Provider {
+    interface Keys {
+      default: [typeof userChannel, typeof chatChannel]
+      admin: [typeof adminChannel]
+    }
+  }
+}
+
+Broadcast.Provider.register('default', defaultBroadcast)
+Broadcast.Provider.register('admin', adminBroadcast)
+
+const admin = Broadcast.provider('admin')
+admin.emit('/admin/alerts', { level: 'critical' })
+```
+
+### Listen Then Emit
+
+```ts
+const orderChannel = Broadcast.channel('/order/:orderId').create<{ status: string }>()
+const broadcast = Broadcast.Provider.create({ channels: [orderChannel], driver: Events })
+Broadcast.Provider.register('default', broadcast)
+
+// Subscribe
+Broadcast.addListener('/order/123', {
+  handler({ data, params }) {
+    console.log(`Order ${params.orderId} is ${data.status}`)
+  }
+})
+
+// Emit with generated event name
+const event = Broadcast.generateEventName('/order/:orderId', { orderId: '123' })
+Broadcast.emit(event, { status: 'shipped' })
+```
+
+### Cleanup
+
+```ts
+// Remove a single listener
+const handle = Broadcast.addListener('/user/42', { handler() {} })
+handle.remove()
+
+// Remove all listeners at once
+Broadcast.removeAllListeners()
+```
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/broadcast test
+```
+
+Or a single file:
+
+```bash
+cd packages/broadcast && npx beartest ./tests/broadcast.test.ts
+```
+
+Tests use `beartest-js` with `expect` for assertions. Use the mock driver pattern shown above for unit tests -- no real Redis or Events instance required.
+
+## Cross-Package Integration
+
+- **@maestro-js/service-registry** -- powers the Provider pattern (create, register, resolve via proxy)
+- **@maestro-js/events** -- primary driver for cross-process event distribution (Redis, WebSocket, or Local)
+- **@remix-run/route-pattern** -- handles URL-like pattern matching and parameter extraction
+
+### Source Files
+
+- `packages/broadcast/src/index.ts` -- main export, Provider, facade, channel factory
+- `packages/broadcast/src/broadcasting-helpers.ts` -- `matchPattern` and `generateEventName` implementations
+- `packages/broadcast/src/broadcasting-types.ts` -- all type definitions (Channel, Broadcast, BroadcastingDriver, etc.)
+- `packages/broadcast/tests/broadcast.test.ts` -- full test suite

package/dist/maestro-packages/cache-control.md

@@ -0,0 +1,337 @@
+---
+name: cache-control
+description: "HTTP Cache-Control-inspired caching for async functions with caller/callee directives. Use when working with @maestro-js/cache-control. Key capabilities: wrap async functions with cacheFn to add cache-control semantics, set response directives (maxAge, staleWhileRevalidate, noStore) from the callee, set request directives (maxAge, noStore) from the caller, automatic background revalidation of stale data, in-flight request deduplication, built-in LRU cache or custom cache backends, human-readable duration strings (e.g. '5 minutes'), structured logging of all cache lifecycle events, and optional tracing integration for observability."
+---
+
+## Overview
+
+`@maestro-js/cache-control` provides an HTTP Cache-Control-inspired caching layer for async functions. Both the caller and callee provide directives that together determine whether a cached response is returned, a fresh value is fetched, or a stale value is served while revalidation happens in the background. It follows the maestro Provider pattern built on `@maestro-js/service-registry`.
+
+## Quick Setup
+
+```ts
+import { CacheControl } from '@maestro-js/cache-control'
+import { Log } from '@maestro-js/log'
+
+// Create a logger
+const logger = Log.create<[CacheControl.LogMessage]>({
+  transports: [{ write(msg) { console.log(msg) } }]
+})
+
+// Create and register the service
+const cc = CacheControl.Provider.create({
+  cache: CacheControl.caches.leastRecentlyUsed({ max: 100 }),
+  logger
+})
+CacheControl.Provider.register('default', cc)
+```
+
+After registering the default provider, use the facade directly:
+
+```ts
+const getUser = CacheControl.cacheFn('users/getById', async (id: string) => {
+  const user = await fetchUser(id)
+  return CacheControl.response(user, {
+    maxAge: '5 minutes',
+    staleWhileRevalidate: '1 minute'
+  })
+})
+
+const user = await getUser('123', { maxAge: '5 minutes' })
+```
+
+## Cache Directives
+
+### Response Directives (Callee)
+
+Set by the function being cached via `CacheControl.response(value, options)`:
+
+| Directive | Type | Description |
+|-----------|------|-------------|
+| `maxAge` | `number \| DurationString` | Seconds the response remains fresh. Required unless `noStore` is set. |
+| `staleWhileRevalidate` | `number \| DurationString \| undefined` | Seconds a stale response can be served while revalidating in the background. |
+| `swr` | same as above | Alias for `staleWhileRevalidate`. |
+| `noStore` | `true` | Return the value but never store it in the cache. |
+
+### Request Directives (Caller)
+
+Passed as the last argument when calling a cached function:
+
+| Directive | Type | Description |
+|-----------|------|-------------|
+| `maxAge` | `number \| DurationString \| null` | Maximum acceptable age (seconds) for a cached value. `null` means accept any age within response maxAge. |
+| `noStore` | `boolean \| undefined` | Bypass the cache entirely -- always call the underlying function and do not store the result. |
+
+### Duration Strings
+
+Both `maxAge` and `staleWhileRevalidate` accept human-readable duration strings:
+
+```ts
+type CacheControlDurationString = `${number} ${'day' | 'days' | 'hour' | 'hours' | 'minute' | 'minutes' | 'second' | 'seconds'}`
+```
+
+Examples: `'1 second'`, `'30 seconds'`, `'5 minutes'`, `'1 hour'`, `'7 days'`
+
+## API Reference
+
+### `CacheControl.Provider.create(config)`
+
+Create a new CacheControl service instance.
+
+```ts
+function create(config: {
+  cache: CacheControlCache
+  logger: Log.LogFunctions<[CacheControl.LogMessage]>
+  tracing?: CacheControl.Tracing
+}): CacheControl.CacheControlService
+```
+
+### `CacheControl.Provider.register(name, service)`
+
+Register a service instance in the named registry.
+
+```ts
+CacheControl.Provider.register('default', cc)
+```
+
+### `CacheControl.provider(key)`
+
+Resolve a named service instance. Returns `{ cacheFn }`.
+
+```ts
+const { cacheFn } = CacheControl.provider('analytics')
+```
+
+### `CacheControl.cacheFn(options, func)`
+
+Wrap an async function with cache-control semantics. Available on the facade (uses the `'default'` provider) or on a service instance.
+
+```ts
+// String key prefix (arguments are hashed with object-hash)
+const fn = CacheControl.cacheFn('my/prefix', async (id: string) => {
+  return CacheControl.response(await fetchData(id), { maxAge: 60 })
+})
+
+// Object options with custom argument hashing
+const fn = CacheControl.cacheFn(
+  {
+    keyPrefix: 'my/prefix',
+    hashArguments: (args) => args[0]
+  },
+  async (id: string) => {
+    return CacheControl.response(await fetchData(id), { maxAge: 60 })
+  }
+)
+```
+
+**Signature:**
+
+```ts
+cacheFn<Args, Returns>(
+  options: string | { keyPrefix: string; hashArguments?(args: Args): string },
+  func: (...args: Args) => Returns
+): (...args: [...Args, CacheControlRequestDirectives]) => Promise<UnwrapCacheResponse<Awaited<Returns>>>
+```
+
+The wrapped function appends a `CacheControlRequestDirectives` argument. The callback **must** return `CacheControl.response(value, options)`.
+
+### `CacheControl.response(value, options)`
+
+Create a cache-control response wrapper pairing a value with freshness directives.
+
+```ts
+// With maxAge and staleWhileRevalidate
+CacheControl.response(data, { maxAge: '5 minutes', staleWhileRevalidate: '15 minutes' })
+
+// With swr alias
+CacheControl.response(data, { maxAge: '5 minutes', swr: '15 minutes' })
+
+// No-store (return value but do not cache)
+CacheControl.response(data, { noStore: true })
+```
+
+### `CacheControl.caches.leastRecentlyUsed(config)`
+
+Create an in-memory LRU cache backend.
+
+```ts
+const cache = CacheControl.caches.leastRecentlyUsed({ max: 500 })
+```
+
+### `CacheControlCache` Interface
+
+Implement this interface to provide a custom cache backend:
+
+```ts
+interface CacheControlCache {
+  set(key: string, value: object, ttlSeconds: number): void | Promise<void>
+  get<T>(key: string): T | Promise<T> | undefined | null
+  del(key: string): void | Promise<void>
+  dump?(): any
+}
+```
+
+## Common Patterns
+
+### Basic Cached Function
+
+```ts
+const getUser = CacheControl.cacheFn('users/getById', async (id: string) => {
+  const user = await db.query('SELECT * FROM users WHERE id = ?', [id])
+  return CacheControl.response(user, { maxAge: '5 minutes', swr: '15 minutes' })
+})
+
+// Caller accepts any cached value within the response's maxAge
+const user = await getUser('123', { maxAge: null })
+```
+
+### Force Fresh Data
+
+```ts
+// Bypass cache -- always execute the function and do not store
+const user = await getUser('123', { noStore: true })
+```
+
+### Caller-Limited Staleness
+
+```ts
+// Only accept cached values generated within the last 60 seconds
+const user = await getUser('123', { maxAge: 60 })
+
+// Accept cached values up to 5 minutes old
+const user = await getUser('123', { maxAge: '5 minutes' })
+```
+
+### Custom Argument Hashing
+
+```ts
+const getReport = CacheControl.cacheFn(
+  {
+    keyPrefix: 'reports/monthly',
+    hashArguments: (args) => args[0]
+  },
+  async (month: string) => {
+    const report = await generateReport(month)
+    return CacheControl.response(report, { maxAge: '1 hour' })
+  }
+)
+
+await getReport('2025-01', { maxAge: null })
+```
+
+### Multiple Named Providers
+
+```ts
+const fastCache = CacheControl.Provider.create({
+  cache: CacheControl.caches.leastRecentlyUsed({ max: 1000 }),
+  logger
+})
+CacheControl.Provider.register('fast', fastCache)
+
+const { cacheFn } = CacheControl.provider('fast')
+const fn = cacheFn('my/key', myFunction)
+```
+
+### Sensitive Data (No-Store Response)
+
+```ts
+const getToken = CacheControl.cacheFn('auth/token', async (userId: string) => {
+  const token = await generateToken(userId)
+  return CacheControl.response(token, { noStore: true })
+})
+```
+
+### Tracing Integration
+
+```ts
+const cc = CacheControl.Provider.create({
+  cache: CacheControl.caches.leastRecentlyUsed({ max: 100 }),
+  logger,
+  tracing: {
+    startActiveSpan: (name, fn) => tracer.startActiveSpan(name, fn),
+    getActiveSpan: () => tracer.getActiveSpan()
+  }
+})
+```
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/cache-control test
+# or
+cd packages/cache-control && npx beartest ./tests/cache-control.test.ts
+```
+
+Tests use `beartest-js` with `expect`. Create mock caches for testing:
+
+```ts
+function mockWorkingCache(): CacheControl.CacheControlService['cache'] {
+  const map = new Map<string, any>()
+  return {
+    get(key) { return map.get(key) },
+    set(key, value) { map.set(key, value) },
+    del(key) { map.delete(key) }
+  }
+}
+
+function mockBrokenCache(): CacheControl.CacheControlService['cache'] {
+  return {
+    get() { throw new Error('This cache is broken') },
+    set(key, value) {},
+    del(key) {}
+  }
+}
+```
+
+Create a testing logger that tracks cache hits and background refreshes:
+
+```ts
+const logger = Log.create<[CacheControl.LogMessage]>({
+  transports: [{
+    write(message) {
+      const data = message.data[0]
+      // Track events by callId to detect cache hits, errors, and background refreshes
+    }
+  }]
+})
+```
+
+Use `{ maxAge: null }` as the standard no-preference request directive in tests.
+
+## Cross-Package Integration
+
+### Dependencies
+
+- **`@maestro-js/service-registry`** -- Provider pattern (create, register, resolve via Proxy)
+- **`@maestro-js/log`** -- Structured logging of cache lifecycle events
+
+### Cache Backend
+
+The `CacheControlCache` interface is deliberately simple. Any backend that implements `get`, `set`, and `del` works. The built-in `CacheControl.caches.leastRecentlyUsed()` uses the `lru-cache` npm package internally.
+
+A custom backend backed by `@maestro-js/cache` (Redis, etc.) can be created by implementing the `CacheControlCache` interface and delegating to the cache package.
+
+### Log Events
+
+All operations emit structured log messages of type `CacheControl.LogMessage`. Key events:
+
+- `cacheFunctionCalled` -- function invoked with arguments and request directives
+- `getCachedValueStart` / `getCachedValueSuccess` / `getCachedValueEmpty` / `getCachedValueError` -- cache lookup lifecycle
+- `getCachedValueNotReused` -- caller's maxAge directive rejected a cached value
+- `getCachedValueOutdated` -- entry expired past maxAge + staleWhileRevalidate window
+- `getFreshValueStart` / `getFreshValueSuccess` / `getFreshValueError` -- fresh value fetch lifecycle
+- `writeFreshValueSuccess` / `writeFreshValueError` -- writing to cache backend
+- `refreshValueStart` / `refreshValueSuccess` / `refreshValueError` -- background stale-while-revalidate lifecycle
+- `cacheFunctionReturned` / `cacheFunctionComplete` -- overall function lifecycle
+
+### Key File Locations
+
+- Source: `packages/cache-control/src/index.ts`
+- Types: `packages/cache-control/src/cache-control-types.ts`
+- Cache lookup logic: `packages/cache-control/src/get-cache-control-value.ts`
+- Fresh value + write logic: `packages/cache-control/src/get-fresh-cache-control-value.ts`
+- Response parsing + duration strings: `packages/cache-control/src/parse-cache-response.ts`
+- LRU cache backend: `packages/cache-control/src/lru-cache.ts`
+- Tests: `packages/cache-control/tests/cache-control.test.ts`