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

package/dist/maestro-packages/context.md

@@ -0,0 +1,365 @@
+---
+name: context
+description: "Guide for working with @maestro-js/context, a request-scoped key-value storage package backed by Node.js AsyncLocalStorage. Use when working with @maestro-js/context, adding per-request state, storing visible or hidden context values, propagating context across async boundaries, integrating context with logging or tracing, creating typed context item handles, or transferring context stores between execution scopes. Covers the Provider pattern, visible/hidden buckets, run/runWith lifecycle, createItem typed handles, getStore for context propagation, and testing patterns."
+---
+
+# @maestro-js/context
+
+## Overview
+
+The `@maestro-js/context` package provides request-scoped key-value storage backed by Node.js `AsyncLocalStorage`. Each call to `run()` creates an isolated store with two buckets -- visible (safe for logging) and hidden (for sensitive data like tokens) -- ensuring data never leaks between concurrent requests.
+
+## Quick Setup
+
+```ts
+import { Context } from '@maestro-js/context'
+
+// Create and register a context provider
+const ctx = Context.Provider.create()
+Context.Provider.register('default', ctx)
+
+// Use the default facade directly
+Context.run(() => {
+  Context.add('userId', 123)
+  Context.get<number>('userId')  // 123
+  Context.all()                  // { userId: 123 }
+})
+```
+
+## API Reference
+
+### Lifecycle Methods
+
+#### `run<T>(callback: () => T): T`
+
+Initialize a fresh context store for the duration of `callback`. All `add`/`get`/`push` calls inside the callback (including across `await` boundaries) share the same isolated store. Returns the callback's return value.
+
+```ts
+const result = Context.run(() => {
+  Context.add('requestId', 'abc-123')
+  return Context.get('requestId')
+})
+// result === 'abc-123'
+```
+
+#### `runWith<T>(store: Context.Store | undefined, callback: () => T): T`
+
+Run `callback` within a previously captured store so context is available inside. If `store` is `undefined`, run the callback without any context (all reads return `undefined`).
+
+```ts
+Context.run(() => {
+  Context.add('userId', 42)
+  const store = Context.getStore()
+
+  // Later, in a different async boundary:
+  Context.runWith(store, () => {
+    Context.get('userId')  // 42
+  })
+})
+```
+
+#### `getStore(): Context.Store | undefined`
+
+Return a reference to the current `AsyncLocalStorage` store, or `undefined` if called outside a `run()`. The returned store is a live reference -- mutations via `runWith` affect the original.
+
+### Visible Context Methods
+
+#### `add(key: Context.Key, value: any): void`
+
+Store a key-value pair in the visible context, overriding any existing value.
+
+```ts
+Context.run(() => {
+  Context.add('tenantId', 'acme-corp')
+  Context.add('tenantId', 'other-corp')  // overrides
+  Context.get('tenantId')                // 'other-corp'
+})
+```
+
+#### `get<Value = unknown>(key: Context.Key): Value | undefined`
+
+Retrieve the value for a key from the visible context, or `undefined` if absent.
+
+```ts
+Context.run(() => {
+  Context.add('role', 'admin')
+  Context.get<string>('role')    // 'admin'
+  Context.get('nonexistent')     // undefined
+})
+```
+
+#### `has(key: Context.Key): boolean`
+
+Return `true` if the key exists in the visible context.
+
+#### `del(...key: Context.Key[]): void`
+
+Remove one or more keys from the visible context.
+
+```ts
+Context.run(() => {
+  Context.add('a', 1)
+  Context.add('b', 2)
+  Context.del('a', 'b')
+  Context.has('a')  // false
+})
+```
+
+#### `push(key: Context.Key, ...value: any[]): void`
+
+Append value(s) to an array in the visible context. Create the array if the key does not exist. Wrap an existing non-array value into an array before appending.
+
+```ts
+Context.run(() => {
+  Context.push('tags', 'admin')
+  Context.get('tags')              // ['admin']
+
+  Context.push('tags', 'user', 'verified')
+  Context.get('tags')              // ['admin', 'user', 'verified']
+
+  Context.add('scalar', 'x')
+  Context.push('scalar', 'y')
+  Context.get('scalar')            // ['x', 'y']
+})
+```
+
+#### `all(): { [key: Context.Key]: unknown }`
+
+Return all visible context entries as a plain object. Hidden entries are excluded.
+
+```ts
+Context.run(() => {
+  Context.add('userId', 123)
+  Context.addHidden('authToken', 'secret')
+  Context.all()  // { userId: 123 }
+})
+```
+
+#### `createItem<Value = unknown>(key: Context.Key)`
+
+Return a typed handle scoped to a single key in the visible context. The handle exposes `add(value)`, `get()`, `del()`, and `push(...)` methods.
+
+```ts
+Context.run(() => {
+  const userId = Context.createItem<number>('userId')
+  userId.add(42)
+  userId.get()  // 42
+  userId.del()
+  userId.get()  // undefined
+})
+```
+
+### Hidden Context Methods
+
+Hidden methods mirror visible methods but operate on a separate bucket excluded from `all()`. Use hidden context for sensitive data (tokens, credentials) that should not appear in logs.
+
+- `addHidden(key, value)` -- Store in hidden context.
+- `getHidden<Value>(key)` -- Retrieve from hidden context.
+- `hasHidden(key)` -- Check existence in hidden context.
+- `delHidden(...key)` -- Remove from hidden context.
+- `pushHidden(key, ...value)` -- Append to array in hidden context.
+- `allHidden()` -- Return all hidden entries as a plain object.
+- `createHiddenItem<Value>(key)` -- Typed handle for hidden context.
+
+```ts
+Context.run(() => {
+  Context.addHidden('authToken', 'Bearer xyz')
+  Context.getHidden('authToken')  // 'Bearer xyz'
+  Context.all()                   // {} -- hidden values excluded
+  Context.allHidden()             // { authToken: 'Bearer xyz' }
+})
+```
+
+### Provider Methods
+
+#### `Context.Provider.create(): Context.ContextService`
+
+Factory that instantiates a new context service with its own `AsyncLocalStorage`.
+
+#### `Context.Provider.register(name: Context.Provider.Key, service: Context.ContextService): void`
+
+Register an instance in the named registry.
+
+#### `Context.provider(key: Context.Provider.Key): Context.ContextService`
+
+Resolve a named instance. Resolution is deferred via Proxy, so `provider()` can be called before `register()`.
+
+## Common Patterns
+
+### Request-Scoped Data in HTTP Middleware
+
+Wrap each incoming request in `Context.run()` to isolate per-request data:
+
+```ts
+function contextMiddleware(req, res, next) {
+  Context.run(() => {
+    Context.add('requestId', req.headers['x-request-id'])
+    Context.add('method', req.method)
+    Context.add('path', req.path)
+    Context.addHidden('authToken', req.headers.authorization)
+    next()
+  })
+}
+```
+
+### Propagating Context Across Async Boundaries
+
+When context must survive into a callback that runs outside the original `run()` scope (e.g., stream event handlers), capture and restore the store:
+
+```ts
+Context.run(() => {
+  Context.add('queryId', 'q-001')
+  const store = Context.getStore()
+
+  stream.on('end', () => {
+    Context.runWith(store, () => {
+      // Context is available here
+      Context.get('queryId')  // 'q-001'
+    })
+  })
+})
+```
+
+This pattern is used by `@maestro-js/db` for query stream logging and by `@maestro-js/tracing` for span instrumentation.
+
+### Nested Runs Create Fresh Stores
+
+Each `run()` creates a completely fresh store. Nested calls do not inherit from the outer scope:
+
+```ts
+Context.run(() => {
+  Context.add('outer', 1)
+  Context.run(() => {
+    Context.get('outer')  // undefined -- fresh store
+    Context.add('inner', 2)
+  })
+  Context.get('inner')    // undefined -- inner store is gone
+  Context.get('outer')    // 1
+})
+```
+
+### Silent No-Ops Outside run()
+
+All context operations silently do nothing when called outside a `run()` scope. No errors are thrown:
+
+```ts
+Context.add('key', 'value')    // no-op
+Context.get('key')             // undefined
+Context.has('key')             // false
+Context.all()                  // {}
+```
+
+### Store Mutations via runWith Are Shared
+
+`getStore()` returns a reference, not a copy. Mutations inside `runWith` affect the original store:
+
+```ts
+Context.run(() => {
+  Context.add('count', 1)
+  const store = Context.getStore()
+
+  Context.runWith(store, () => {
+    Context.add('count', 2)
+  })
+
+  Context.get('count')  // 2 -- mutated by runWith
+})
+```
+
+### Multiple Isolated Providers
+
+Separate `create()` calls produce fully independent context instances:
+
+```ts
+const appContext = Context.Provider.create()
+const requestContext = Context.Provider.create()
+
+appContext.run(() => {
+  appContext.add('env', 'production')
+  requestContext.run(() => {
+    requestContext.add('env', 'staging')
+    appContext.get('env')       // 'production'
+    requestContext.get('env')   // 'staging'
+  })
+})
+```
+
+## Testing
+
+Context requires no mock driver -- `Provider.create()` returns a fully functional instance using in-process `AsyncLocalStorage`. Wrap test logic in `run()`:
+
+```ts
+import { Context } from '@maestro-js/context'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('adds and retrieves context values', () => {
+  const ctx = Context.Provider.create()
+  ctx.run(() => {
+    ctx.add('userId', 123)
+    expect(ctx.get('userId')).toBe(123)
+    expect(ctx.has('userId')).toBe(true)
+    expect(ctx.all()).toEqual({ userId: 123 })
+  })
+})
+
+test('hidden values excluded from all()', () => {
+  const ctx = Context.Provider.create()
+  ctx.run(() => {
+    ctx.add('visible', 'yes')
+    ctx.addHidden('secret', 'token')
+    expect(ctx.all()).toEqual({ visible: 'yes' })
+    expect(ctx.getHidden('secret')).toBe('token')
+  })
+})
+
+test('async propagation across await', async () => {
+  const ctx = Context.Provider.create()
+  await ctx.run(async () => {
+    ctx.add('before', true)
+    await new Promise((r) => setTimeout(r, 10))
+    expect(ctx.get('before')).toBe(true)
+  })
+})
+```
+
+Run tests with:
+
+```bash
+pnpm --filter @maestro-js/context test
+# or
+cd packages/context && npx beartest ./tests/context.test.ts
+```
+
+## Cross-Package Integration
+
+### Db (query stream logging)
+
+The `@maestro-js/db` package captures the context store before creating query streams and restores it in `end` and `error` event handlers via `Context.runWith()`, ensuring log messages emitted during stream callbacks include the original request context.
+
+### Tracing (span instrumentation)
+
+The `@maestro-js/tracing` package captures the context store when starting or wrapping spans and restores it in `onEnd` callbacks via `Context.runWith()`, so span completion logs include the request context.
+
+### Log (contextual logging)
+
+Log transports can call `Context.all()` to attach visible context entries to every log line within a request scope, providing automatic request-scoped structured logging without manually passing data.
+
+### Dependencies
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation)
+- **Used by**: `@maestro-js/db`, `@maestro-js/tracing`
+- **Works with**: `@maestro-js/log` (contextual logging)
+
+## Types
+
+```ts
+// Key type for context entries
+type Context.Key = string | number | symbol
+
+// The raw context snapshot containing visible and hidden Map buckets
+type Context.Store = {
+  hidden: Map<Context.Key, unknown>
+  visible: Map<Context.Key, unknown>
+}
+```

package/dist/maestro-packages/crypt.md

@@ -0,0 +1,253 @@
+---
+name: crypt
+description: "AES-256-GCM encryption and decryption with automatic key rotation for the maestro-js framework. Use when working with @maestro-js/crypt, encrypting or decrypting strings, rotating encryption keys, checking key IDs on encrypted data, or setting up field-level encryption. Key capabilities include AES-256-GCM authenticated encryption, dot-delimited cipher format with embedded key IDs, zero-downtime key rotation via previousKeys, per-call random IV generation, Provider pattern with deferred resolution, and key identification without decryption."
+---
+
+# Maestro Crypt
+
+## Overview
+
+The `@maestro-js/crypt` package provides AES-256-GCM encryption and decryption with automatic key rotation. Encrypted strings use a dot-delimited format (`keyId.iv.ciphertext.authTag`) that embeds a short key identifier, allowing the correct key to be selected during decryption even after key rotation.
+
+## Quick Setup
+
+```ts
+import { Crypt } from '@maestro-js/crypt'
+import crypto from 'node:crypto'
+
+// Create a service with a 32-byte base64-encoded key
+const service = Crypt.Provider.create({
+  key: process.env.ENCRYPTION_KEY!,   // base64-encoded, 32 bytes decoded
+  previousKeys: []                     // no rotated keys yet
+})
+
+// Register as the default provider
+Crypt.Provider.register('default', service)
+
+// Encrypt and decrypt
+const encrypted = Crypt.encryptString('sensitive data')
+const plaintext = Crypt.decryptString(encrypted)  // 'sensitive data'
+```
+
+Generate a valid key: `crypto.randomBytes(32).toString('base64')`
+
+## API Reference
+
+### `Crypt.Provider.create(config)`
+
+Create a new Crypt service instance from a keyset.
+
+```ts
+function create(config: {
+  key: string            // current primary key, base64-encoded (32 bytes decoded)
+  previousKeys: string[] // previously-used keys for decryption, base64-encoded
+}): Crypt.CryptService
+```
+
+Each key is assigned a short ID (first 4 characters of its base64 SHA-256 hash). Keys must be exactly 32 bytes when decoded from base64.
+
+```ts
+const service = Crypt.Provider.create({
+  key: 'aGVsbG93b3JsZGhlbGxvd29ybGRoZWxsb3dvcmxkMTI=',
+  previousKeys: []
+})
+```
+
+### `Crypt.Provider.register(name, service)`
+
+Register a service instance in the named registry.
+
+```ts
+Crypt.Provider.register('default', service)
+```
+
+### `Crypt.provider(key)`
+
+Resolve a named provider instance. The default facade (`Crypt.encryptString`, etc.) delegates to `Crypt.provider('default')`.
+
+```ts
+const fieldCrypt = Crypt.provider('field-level')
+const encrypted = fieldCrypt.encryptString('SSN: 123-45-6789')
+```
+
+### `encryptString(plaintext)`
+
+Encrypt a plaintext string using AES-256-GCM with the current primary key. Generates a random 12-byte IV per call, so encrypting the same string twice produces different ciphertext.
+
+```ts
+encryptString(plaintext: string): string
+```
+
+Returns a dot-delimited string: `{keyId}.{iv}.{ciphertext}.{authTag}`.
+
+```ts
+const token1 = Crypt.encryptString('user-session-abc')
+const token2 = Crypt.encryptString('user-session-abc')
+// token1 !== token2 (different IVs)
+```
+
+### `decryptString(encryptedText)`
+
+Decrypt a dot-delimited cipher string. Parses the embedded key ID and tries all keys in the keyset with a matching ID. Throws if no key can decrypt the text.
+
+```ts
+decryptString(encryptedText: string): string
+```
+
+```ts
+const plaintext = Crypt.decryptString(encrypted)  // 'user-session-abc'
+```
+
+### `getEncryptingKeyId(encryptedText)`
+
+Extract the key ID from an encrypted string without decrypting it. Useful for checking whether data needs re-encryption after a key rotation.
+
+```ts
+getEncryptingKeyId(encryptedText: string): string | undefined
+```
+
+```ts
+const keyId = Crypt.getEncryptingKeyId(encrypted)  // e.g. 'aB3d'
+```
+
+### `getCurrentKeyId()`
+
+Return the ID of the current primary encryption key.
+
+```ts
+getCurrentKeyId(): string
+```
+
+```ts
+const currentId = Crypt.getCurrentKeyId()  // e.g. 'aB3d'
+
+// Check if data needs re-encryption
+if (Crypt.getEncryptingKeyId(encrypted) !== Crypt.getCurrentKeyId()) {
+  const refreshed = Crypt.encryptString(Crypt.decryptString(encrypted))
+}
+```
+
+## Key Rotation
+
+Key rotation allows transitioning to a new encryption key without breaking decryption of existing data. Move the old key into `previousKeys` and set the new key as `key`.
+
+```ts
+// Before rotation: key1 is the primary key
+const service = Crypt.Provider.create({
+  key: key1,
+  previousKeys: []
+})
+
+// After rotation: key2 is primary, key1 still decrypts old data
+const rotatedService = Crypt.Provider.create({
+  key: key2,
+  previousKeys: [key1]
+})
+
+// New encryptions use key2
+const newEncrypted = rotatedService.encryptString('new data')
+
+// Old data encrypted with key1 still decrypts
+const oldPlaintext = rotatedService.decryptString(oldEncryptedWithKey1)
+```
+
+### Re-encrypting Existing Data
+
+After rotation, identify and re-encrypt data that uses old keys:
+
+```ts
+function reEncryptIfNeeded(encryptedValue: string): string {
+  if (Crypt.getEncryptingKeyId(encryptedValue) !== Crypt.getCurrentKeyId()) {
+    return Crypt.encryptString(Crypt.decryptString(encryptedValue))
+  }
+  return encryptedValue
+}
+```
+
+## Common Patterns
+
+### Field-Level Encryption in Database Records
+
+```ts
+// Encrypt before storing
+const encryptedSsn = Crypt.encryptString('123-45-6789')
+await Db.query('INSERT INTO users (name, ssn_encrypted) VALUES (?, ?)', ['Alice', encryptedSsn])
+
+// Decrypt after reading
+const [row] = await Db.query('SELECT ssn_encrypted FROM users WHERE id = ?', [userId])
+const ssn = Crypt.decryptString(row.ssn_encrypted)  // '123-45-6789'
+```
+
+### Multiple Named Providers
+
+```ts
+// Separate keysets for different sensitivity levels
+Crypt.Provider.register('default', Crypt.Provider.create({
+  key: process.env.GENERAL_ENCRYPTION_KEY!,
+  previousKeys: []
+}))
+
+Crypt.Provider.register('pii', Crypt.Provider.create({
+  key: process.env.PII_ENCRYPTION_KEY!,
+  previousKeys: [process.env.PII_OLD_KEY!]
+}))
+
+// Use the PII provider for sensitive fields
+const piiCrypt = Crypt.provider('pii')
+const encryptedSsn = piiCrypt.encryptString(ssn)
+```
+
+### Encrypted String Format
+
+The dot-delimited format is: `{keyId}.{iv}.{ciphertext}.{authTag}`
+
+- **keyId** -- first 4 chars of the key's base64 SHA-256 hash
+- **iv** -- random 12-byte initialization vector, base64-encoded
+- **ciphertext** -- AES-256-GCM encrypted data, base64-encoded
+- **authTag** -- GCM authentication tag, base64-encoded
+
+## Testing
+
+Use `Crypt.Provider.create` directly in tests with generated keys. No mock driver is needed since encryption is CPU-only with no external dependencies.
+
+```ts
+import crypto from 'node:crypto'
+import { Crypt } from '@maestro-js/crypt'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('encrypt and decrypt a value', () => {
+  const key = crypto.randomBytes(32).toString('base64')
+  const service = Crypt.Provider.create({ key, previousKeys: [] })
+
+  const encrypted = service.encryptString('sensitive-token')
+  const decrypted = service.decryptString(encrypted)
+
+  expect(decrypted).toBe('sensitive-token')
+})
+
+test('key rotation decrypts old and new data', () => {
+  const key1 = crypto.randomBytes(32).toString('base64')
+  const key2 = crypto.randomBytes(32).toString('base64')
+
+  const oldService = Crypt.Provider.create({ key: key1, previousKeys: [] })
+  const oldEncrypted = oldService.encryptString('original-secret')
+
+  const newService = Crypt.Provider.create({ key: key2, previousKeys: [key1] })
+  const newEncrypted = newService.encryptString('new-secret')
+
+  expect(newService.decryptString(oldEncrypted)).toBe('original-secret')
+  expect(newService.decryptString(newEncrypted)).toBe('new-secret')
+  expect(newService.getEncryptingKeyId(newEncrypted)).not.toBe(
+    newService.getEncryptingKeyId(oldEncrypted)
+  )
+})
+```
+
+Run tests: `pnpm --filter @maestro-js/crypt test`
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` for the Provider pattern (registry, deferred proxy resolution)
+- **Architectural sibling**: `@maestro-js/hash` follows the same single-driver Provider pattern
+- **Standalone**: No downstream maestro packages depend on Crypt directly; it is used at the application layer for field-level encryption