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

package/dist/maestro-packages/hash.md

@@ -0,0 +1,248 @@
+---
+name: hash
+description: "Pluggable hashing and verification with driver-based backends for @maestro-js/hash. Use when working with @maestro-js/hash, hashing values, verifying hashes, detecting when a rehash is needed, or rotating signing keys. Built-in drivers: SHA256 (HMAC-SHA256 with key rotation and timing-safe comparison)."
+---
+
+# @maestro-js/hash
+
+HMAC-SHA256 signing and verification with transparent key rotation. Built on the
+Provider pattern from `@maestro-js/service-registry`.
+
+## Quick Setup
+
+```ts
+import { Hash } from '@maestro-js/hash'
+
+Hash.Provider.register('default', Hash.Provider.create({
+  key: process.env.HMAC_SIGNING_KEY!,
+  previousKeys: [process.env.HMAC_SIGNING_KEY_PREV!]
+}))
+
+// Use the facade directly
+const signed = Hash.signString('order.completed:ord_8k2Xp')
+Hash.isSignatureValid({ plaintext: 'order.completed:ord_8k2Xp', signedText: signed }) // true
+```
+
+## API Reference
+
+### `Hash.Provider.create(config)` — Factory
+
+Create a hash service instance. Accepts a keyset config and returns a `HashService`.
+
+```ts
+interface Keyset {
+  key: string           // Current signing key, base64-encoded
+  previousKeys: string[] // Rotated-out keys, base64-encoded (verification only)
+}
+
+const svc = Hash.Provider.create({
+  key: 'base64EncodedCurrentKey',
+  previousKeys: ['base64EncodedOldKey1', 'base64EncodedOldKey2']
+})
+```
+
+All keys must be valid base64 strings. The factory asserts that at least the
+current key or the first previous key exists at creation time.
+
+### `Hash.Provider.register(name, service)` — Registration
+
+Register a created service under a name for later resolution.
+
+```ts
+Hash.Provider.register('default', svc)
+```
+
+### `Hash.provider(key)` — Resolution
+
+Resolve a named instance. The default facade (`Hash.signString`, etc.) resolves
+`'default'` automatically.
+
+```ts
+const custom = Hash.provider('myService')
+custom.signString('data')
+```
+
+### `signString(plaintext)` — Sign
+
+Sign a plaintext string using the current key. Returns a `keyId.digest` string
+where `keyId` is a 4-character identifier derived from the key.
+
+```ts
+const signed = Hash.signString('Testing')
+// Returns something like 'Ab1c.xYzBase64Digest...'
+```
+
+### `isSignatureValid({ plaintext, signedText })` — Verify
+
+Verify a signed string against the plaintext. Checks all keys in the keyset
+whose ID matches the embedded key ID. Uses `crypto.timingSafeEqual` to prevent
+timing attacks.
+
+```ts
+Hash.isSignatureValid({ plaintext: 'Testing', signedText: signed }) // true
+```
+
+Returns `false` for tampered signatures, unknown keys, or length mismatches.
+
+### `getSigningKeyId(signedText)` — Extract Key ID
+
+Extract the key ID prefix from a signed string. Returns `undefined` if the
+string has no `.` separator (malformed).
+
+```ts
+Hash.getSigningKeyId(signed)        // 'Ab1c'
+Hash.getSigningKeyId('no-dot')      // undefined
+```
+
+### `getCurrentKeyId()` — Current Key ID
+
+Return the 4-character ID of the current active signing key.
+
+```ts
+Hash.getCurrentKeyId() // 'Ab1c'
+```
+
+## Key Rotation
+
+Key rotation is the primary design goal. The keyset has one current key (used
+for signing) and any number of previous keys (used only for verification).
+
+1. Generate a new base64-encoded 256-bit key.
+2. Move the old `key` into `previousKeys`.
+3. Set the new key as `key`.
+
+```ts
+// Before rotation
+Hash.Provider.register('default', Hash.Provider.create({
+  key: 'currentKeyBase64',
+  previousKeys: []
+}))
+
+// After rotation — old signatures still verify
+Hash.Provider.register('default', Hash.Provider.create({
+  key: 'newKeyBase64',
+  previousKeys: ['currentKeyBase64']
+}))
+```
+
+New calls to `signString` use the new key. Existing signed strings created with
+the old key still pass `isSignatureValid` because the old key remains in the
+keyset for verification.
+
+### How Key IDs Work
+
+Each key gets a 4-character ID computed as:
+
+```ts
+crypto.createHash('sha256').update(key).digest('base64').substring(0, 4)
+```
+
+Signed strings embed this ID before the dot: `keyId.hmacDigest`. During
+verification, only keys matching the embedded ID are tested.
+
+## Common Patterns
+
+### Sign and Verify a Webhook Payload
+
+```ts
+const payload = JSON.stringify({ event: 'order.completed', orderId: 'ord_8k2Xp' })
+const signature = Hash.signString(payload)
+
+// Later, verify the signature
+const valid = Hash.isSignatureValid({ plaintext: payload, signedText: signature })
+```
+
+### Multiple Named Instances
+
+```ts
+Hash.Provider.register('webhooks', Hash.Provider.create({
+  key: process.env.WEBHOOK_SIGNING_KEY!,
+  previousKeys: []
+}))
+
+Hash.Provider.register('tokens', Hash.Provider.create({
+  key: process.env.TOKEN_SIGNING_KEY!,
+  previousKeys: []
+}))
+
+const webhookSigned = Hash.provider('webhooks').signString(payload)
+const tokenSigned = Hash.provider('tokens').signString(tokenData)
+```
+
+Extend `Hash.Provider.Keys` to get type-safe provider names:
+
+```ts
+declare module '@maestro-js/hash' {
+  namespace Hash.Provider {
+    interface Keys {
+      webhooks: unknown
+      tokens: unknown
+    }
+  }
+}
+```
+
+### Generate a Key for Development
+
+```ts
+import crypto from 'node:crypto'
+const key = crypto.randomBytes(32).toString('base64')
+```
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/hash test
+# or
+cd packages/hash && npx beartest ./tests/hash.test.ts
+```
+
+Tests use `beartest-js` with `expect`. Create service instances directly with
+`Hash.Provider.create()` without registering — no global state needed.
+
+```ts
+import crypto from 'node:crypto'
+import { Hash } from '@maestro-js/hash'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('should sign and verify', () => {
+  const key = crypto.randomBytes(32).toString('base64')
+  const svc = Hash.Provider.create({ key, previousKeys: [] })
+
+  const signed = svc.signString('hello')
+  expect(svc.isSignatureValid({ plaintext: 'hello', signedText: signed })).toBe(true)
+})
+
+test('key rotation preserves old signatures', () => {
+  const key1 = crypto.randomBytes(32).toString('base64')
+  const key2 = crypto.randomBytes(32).toString('base64')
+
+  const svc1 = Hash.Provider.create({ key: key1, previousKeys: [] })
+  const signed1 = svc1.signString('data')
+
+  const svc2 = Hash.Provider.create({ key: key2, previousKeys: [key1] })
+  expect(svc2.isSignatureValid({ plaintext: 'data', signedText: signed1 })).toBe(true)
+})
+```
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` for the Provider pattern
+  (registry, deferred proxy resolution, facade).
+- **No downstream dependents**: standalone utility package.
+- **Shares pattern with**: `@maestro-js/crypt` (same Provider + keyset
+  rotation architecture, but for encryption rather than signing).
+
+## Package Structure
+
+```
+packages/hash/
+  src/index.ts          # Single-file implementation and type declarations
+  tests/hash.test.ts    # beartest-js tests
+  package.json          # @maestro-js/hash
+```
+
+Source file: `packages/hash/src/index.ts`

package/dist/maestro-packages/helpers.md

@@ -0,0 +1,249 @@
+---
+name: helpers
+description: "Standalone utility functions for async control flow and file handling in the @maestro-js/helpers package. Use when working with @maestro-js/helpers. Key capabilities: retry with configurable attempts/delay/backoff, sleep, withMaxConcurrency for limiting parallel executions, withRateLimit with fixed or sliding window, raceWithFallback for promise racing with default values, AsyncIterableCollection for lazy async iteration (map, filter, reduce, forEach, toArray), sanitizeFilename for safe cross-platform filenames, and withRetry for wrapping functions with retry behavior."
+---
+
+# @maestro-js/helpers
+
+Standalone utility package providing async control flow primitives (retry, concurrency, rate limiting, promise racing) and helper functions (filename sanitization, async iterable collections). No dependencies on other maestro packages.
+
+## Available Utilities
+
+- **retry** - Retry an async operation with configurable attempts, delay, and conditional retry logic
+- **withRetry** - Wrap a function to add retry behavior, returning a new function
+- **sleep** - Pause execution for a given number of milliseconds
+- **withMaxConcurrency** - Wrap a function to limit the number of concurrent executions
+- **withRateLimit** - Wrap a function to enforce rate limits using fixed or sliding time windows
+- **raceWithFallback** - Race a promise against another, returning a fallback value if the racer wins
+- **AsyncIterableCollection** - Wrap an `AsyncIterable` with chainable collection methods (map, filter, reduce, forEach, toArray)
+- **sanitizeFilename** - Strip illegal, control, and reserved characters from a filename string
+
+## API Reference
+
+### retry
+
+Retry an async function with configurable options. Defaults: 3 attempts, 1000ms delay.
+
+```ts
+function retry<R = void>(
+  fn: () => Promise<R>,
+  options?: Partial<{
+    maxAttempts: number
+    delay: number | ((attempt: number) => number)
+    shouldRetry: (error: unknown) => boolean
+  }>
+): Promise<R>
+```
+
+- `maxAttempts` - Maximum number of attempts (default: 3)
+- `delay` - Fixed milliseconds or a function receiving the attempt number (default: 1000)
+- `shouldRetry` - Predicate that receives the error; return `false` to stop retrying immediately
+
+### withRetry
+
+Return a new function that wraps the original with retry behavior. Accepts the same options as `retry`.
+
+```ts
+function withRetry<Args extends any[], R>(
+  callback: (...args: Args) => Promise<R>,
+  options?: Partial<Helpers.RetryOptions>
+): (...args: Args) => Promise<R>
+```
+
+### sleep
+
+Pause execution for the specified duration.
+
+```ts
+function sleep(ms: number): Promise<void>
+```
+
+### withMaxConcurrency
+
+Return a new function that limits how many invocations run in parallel. Excess calls queue and wait.
+
+```ts
+function withMaxConcurrency<Args extends any[], R>(
+  callback: (...args: Args) => Promise<R>,
+  options?: { concurrency?: number }
+): (...args: Args) => Promise<R>
+```
+
+- `concurrency` - Maximum parallel executions (default: 10)
+
+### withRateLimit
+
+Return a new function that enforces a rate limit using either fixed or sliding time windows.
+
+```ts
+function withRateLimit<Args extends any[], R>(
+  callback: (...args: Args) => Promise<R>,
+  options?: {
+    windowType?: 'fixed' | 'sliding'
+    window: number
+    limit?: number
+  }
+): (...args: Args) => Promise<R>
+```
+
+- `windowType` - `'fixed'` (clock-aligned windows) or `'sliding'` (rolling window). Default: `'fixed'`
+- `window` - Window size in milliseconds (default: 1000)
+- `limit` - Maximum executions per window (default: 1)
+
+### raceWithFallback
+
+Race a primary promise against a competing promise. If the competing promise resolves first, return the fallback value instead.
+
+```ts
+function raceWithFallback<Result, Fallback = null>(
+  promise: Promise<Result>,
+  options: {
+    fallback?: Fallback
+    promiseToRace: Promise<unknown>
+  }
+): Promise<{ value: Awaited<Result> | Fallback }>
+```
+
+Returns `{ value }` where value is the primary result or the fallback.
+
+### AsyncIterableCollection
+
+Wrap any `AsyncIterable<T>` with chainable collection methods. Create with `Helpers.AsyncIterableCollection.from(iterable)`.
+
+```ts
+interface AsyncIterableCollection<T> extends AsyncIterable<T> {
+  forEach(callbackfn: (item: T, index: number) => unknown): Promise<void>
+  map<S>(callbackfn: (item: T, index: number) => S): AsyncIterableCollection<S>
+  filter(predicate: (value: T, index: number) => unknown): AsyncIterableCollection<T>
+  reduce<U>(callbackfn: (prev: U, curr: T, index: number) => U, initialValue: U): Promise<U>
+  toArray(): Promise<T[]>
+}
+```
+
+- `map` and `filter` return a new `AsyncIterableCollection` (lazy, chainable)
+- `forEach`, `reduce`, and `toArray` are terminal operations that consume the iterable
+
+### sanitizeFilename
+
+Remove illegal, control, unicode whitespace, reserved, and Windows-reserved characters from a filename. Truncate to 255 bytes.
+
+```ts
+function sanitizeFilename(input: string): string
+```
+
+## Common Patterns
+
+### Retry with exponential backoff
+
+```ts
+import { Helpers } from '@maestro-js/helpers'
+
+const result = await Helpers.retry(() => fetchFromApi(), {
+  maxAttempts: 5,
+  delay: (attempt) => 1000 * 2 ** (attempt - 1)
+})
+```
+
+### Retry only on specific errors
+
+```ts
+await Helpers.retry(() => callExternalService(), {
+  maxAttempts: 3,
+  delay: 500,
+  shouldRetry: (error) => (error as any)?.code === 'TIMEOUT'
+})
+```
+
+### Wrap a function with retry behavior
+
+```ts
+const resilientFetch = Helpers.withRetry(fetchFromApi, {
+  maxAttempts: 3,
+  delay: 1000
+})
+const result = await resilientFetch('/endpoint')
+```
+
+### Limit concurrent API calls
+
+```ts
+const limitedFetch = Helpers.withMaxConcurrency(fetch, { concurrency: 5 })
+
+const results = await Promise.all(
+  urls.map((url) => limitedFetch(url))
+)
+```
+
+### Rate-limit outbound requests
+
+```ts
+const rateLimited = Helpers.withRateLimit(sendRequest, {
+  windowType: 'sliding',
+  window: 1000,
+  limit: 10
+})
+```
+
+### Race a slow operation with a timeout
+
+```ts
+const { value } = await Helpers.raceWithFallback(
+  slowDatabaseQuery(),
+  {
+    fallback: null,
+    promiseToRace: Helpers.sleep(5000)
+  }
+)
+// value is the query result, or null if it took longer than 5 seconds
+```
+
+### Process async iterables with collection methods
+
+```ts
+const collection = Helpers.AsyncIterableCollection.from(asyncGenerator())
+
+const results = await collection
+  .filter((item) => item.active)
+  .map((item) => item.name)
+  .toArray()
+```
+
+### Reduce an async iterable
+
+```ts
+const total = await Helpers.AsyncIterableCollection.from(rowStream())
+  .reduce((sum, row) => sum + row.amount, 0)
+```
+
+### Sanitize a user-provided filename
+
+```ts
+const safe = Helpers.sanitizeFilename(userInput)
+// Strips illegal chars, control chars, Windows reserved names, trailing dots/spaces
+// Truncates to 255 bytes
+```
+
+## Testing
+
+Run tests with beartest-js:
+
+```bash
+pnpm --filter @maestro-js/helpers test
+```
+
+Or run the test file directly:
+
+```bash
+cd packages/helpers && npx beartest ./tests/helpers.test.ts
+```
+
+Tests use `beartest-js` with `expect` for assertions. Test file location: `packages/helpers/tests/helpers.test.ts`.
+
+## Package Info
+
+- **Package name**: `@maestro-js/helpers`
+- **Source**: `packages/helpers/src/index.ts`
+- **No dependencies** on other maestro packages
+- **No downstream dependents**
+- Build: `tsup` (ESM + .d.ts)
+- Code style: Prettier (2-space indent, no semicolons, single quotes, 125 char width)