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

package/dist/maestro-packages/cache.md

@@ -0,0 +1,397 @@
+---
+name: cache
+description: "Key-value caching with TTL, stale-while-revalidate, distributed locking, cache-aside pattern, atomic increment/decrement, and set-if-not-exists (add) for @maestro-js/cache. Use when working with @maestro-js/cache, adding caching to services, implementing distributed locks, using the remember/SWR pattern, incrementing or decrementing counters, adding values only if absent, configuring Redis or MockRedis drivers, or following the canonical Provider pattern from service-registry."
+---
+
+# @maestro-js/cache
+
+Key-value caching with optional TTL, stale-while-revalidate (SWR), distributed locking, and
+cache-aside (`remember`) pattern. This is the canonical example of the Maestro Provider pattern.
+
+## Quick Setup
+
+```ts
+import { Cache } from '@maestro-js/cache'
+
+// Create and register a cache instance
+const cacheService = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379 })
+})
+Cache.Provider.register('default', cacheService)
+
+// Use directly via the facade
+await Cache.set('user:123', { name: 'Alice' }, 3600)
+const user = await Cache.get<User>('user:123')
+```
+
+## Provider Pattern
+
+Cache follows the standard Maestro Provider pattern built on `@maestro-js/service-registry`:
+
+1. **`Cache.Provider.create(config)`** -- factory that instantiates a cache service with a driver
+2. **`Cache.Provider.register(name, service)`** -- register the instance in a named registry
+3. **`Cache.provider(key)`** -- resolve a named instance (deferred via Proxy)
+4. **Facade** -- `Cache.get()`, `Cache.set()`, etc. spread from `provider('default')`
+5. **`Cache.drivers`** -- factory functions for pluggable backends (`redis`, `mockRedis`)
+
+Extend provider keys via declaration merging:
+
+```ts
+declare module '@maestro-js/cache' {
+  namespace Cache.Provider {
+    interface Keys {
+      default: unknown
+      sessions: unknown
+    }
+  }
+}
+```
+
+Source: `packages/cache/src/index.ts`
+
+## Drivers
+
+### Redis
+
+Production driver backed by ioredis. Pass connection details and optional tuning:
+
+```ts
+Cache.drivers.redis({
+  url: 'redis-host',
+  port: 6379,
+  operationTimeout: 5000,   // ms, default 5000
+  connectTimeout: 10000,    // ms, default 10000
+  keyPrefix: 'myapp:',      // optional prefix for all keys
+  logger: customLogger       // optional Log.LogFunctions
+})
+```
+
+The returned driver exposes a `connection` property (the raw ioredis `Redis` instance) for
+advanced use cases.
+
+Config interface:
+
+| Field              | Type              | Default | Description                   |
+|--------------------|-------------------|---------|-------------------------------|
+| `url`              | `string`          | --      | Redis host                    |
+| `port`             | `number`          | --      | Redis port                    |
+| `operationTimeout` | `number`          | `5000`  | Per-operation timeout (ms)    |
+| `connectTimeout`   | `number`          | `10000` | Connection timeout (ms)       |
+| `keyPrefix`        | `string`          | `''`    | Prefix applied to all keys    |
+| `logger`           | `Log.LogFunctions`| --      | Optional structured logger    |
+
+Source: `packages/cache/src/redis-cache-driver.ts`
+
+### MockRedis
+
+In-memory driver using `ioredis-mock` for testing. Same interface as Redis:
+
+```ts
+Cache.drivers.mockRedis({
+  keyPrefix: 'test:',   // optional
+  logger: customLogger  // optional
+})
+```
+
+Source: `packages/cache/src/mock-redis-cache-driver.ts`
+
+## API Reference
+
+All values must be JSON-serializable. TTL is always in seconds; pass `null` to persist forever.
+
+### Core Methods
+
+```ts
+Cache.has(key: string): Promise<boolean>
+```
+Return `true` if the key exists in the cache.
+
+```ts
+Cache.get<T>(key: string): Promise<T | null>
+```
+Retrieve a value. Return `null` on miss.
+
+```ts
+Cache.set(key: string, value: any, ttlSeconds: number | null): Promise<void>
+```
+Store a value with TTL in seconds. Pass `null` for no expiration.
+
+```ts
+Cache.del(key: string): Promise<void>
+```
+Remove a key from the cache.
+
+```ts
+Cache.flush(): Promise<void>
+```
+Remove all entries. Ignores key prefix -- affects the entire store.
+
+### Atomic Operations
+
+```ts
+Cache.add(key: string, value: any, ttlSeconds: number): Promise<boolean>
+```
+Store a value only if the key does not already exist. Returns `true` if added, `false` if the key
+was already present. The value is JSON-serialized (compatible with `get`).
+
+```ts
+Cache.increment(key: string, value?: number): Promise<number>
+```
+Atomically increment a numeric value by `value` (default `1`). Returns the new value.
+
+```ts
+Cache.decrement(key: string, value?: number): Promise<number>
+```
+Atomically decrement a numeric value by `value` (default `1`). Returns the new value.
+
+> **Warning:** `increment` and `decrement` use Redis `INCRBY`/`DECRBY` on raw integers, not
+> JSON-serialized values. Values stored with `set` (which JSON-serializes) cannot be incremented.
+> Conversely, values created by `increment`/`decrement` are raw numbers and will come back as plain
+> numbers from `get`, not wrapped in JSON.
+
+```ts
+// Rate-limit counter
+await Cache.increment('rate:user:42')
+const count = await Cache.increment('rate:user:42')
+if (count > 100) throw new Error('Rate limit exceeded')
+
+// Add-if-absent: claim a one-time token
+const claimed = await Cache.add('token:abc123', { userId: 42 }, 300)
+if (!claimed) throw new Error('Token already used')
+```
+
+### remember (Cache-Aside)
+
+```ts
+Cache.remember<T>(key: string, options: RememberOptions, fn: () => Promise<T>): Promise<T>
+```
+
+Retrieve `key` from cache. On miss, call `fn`, cache the result, and return it.
+
+**RememberOptions** accepts:
+- `number` -- TTL in seconds
+- `null` -- persist forever
+- `DurationString` -- e.g. `'5 minutes'`, `'1 hour'`, `'30 seconds'`, `'2 days'`
+- `{ ttl: number | DurationString | null, swr: number | DurationString }` -- TTL with
+  stale-while-revalidate window
+
+```ts
+// Simple TTL
+await Cache.remember('user:1', 60, async () => fetchUser(1))
+
+// Duration string
+await Cache.remember('config', '5 minutes', async () => loadConfig())
+
+// Forever
+await Cache.remember('constants', null, async () => getConstants())
+
+// Stale-while-revalidate
+await Cache.remember('feed', { ttl: 60, swr: 30 }, async () => buildFeed())
+await Cache.remember('feed', { ttl: '1 minute', swr: '30 seconds' }, async () => buildFeed())
+```
+
+SWR behavior: when the TTL expires but the entry is within the SWR window, the stale value is
+returned immediately and `fn` runs in the background to refresh the cache. Background refresh
+errors are silently swallowed (the stale value remains). Only one background refresh per key runs
+at a time.
+
+Do not mix `Cache.set()` and `Cache.remember()` on the same key -- `remember` wraps values in an
+internal envelope (`__remember` marker) and throws if it encounters a raw value.
+
+### item (Typed Key Handle)
+
+```ts
+Cache.item<T>(key: string)
+```
+
+Return a typed handle scoped to a single key:
+
+```ts
+const user = Cache.item<User>('user:456')
+await user.set({ name: 'Bob' }, 7200)
+await user.exists()                        // true
+await user.get()                           // { name: 'Bob' }
+await user.del()
+await user.remember(60, async () => fetchUser(456))
+await user.remember('5 minutes', async () => fetchUser(456))
+await user.remember({ ttl: 1, swr: 10 }, async () => fetchUser(456))
+```
+
+### lock (Distributed Locking)
+
+```ts
+Cache.lock(name: string, ttlSeconds: number | null): Cache.Lock
+```
+
+Create a distributed lock backed by Redis `SET NX`. Lock methods:
+
+```ts
+const lock = Cache.lock('process-orders', 30)
+
+await lock.get()           // true if acquired, false if held by another
+await lock.isAvailable()   // true if no one holds the lock
+await lock.release()       // release if owned by this caller (atomic Lua script)
+await lock.forceRelease()  // release regardless of owner
+await lock.block(5)        // retry acquiring for up to 5 seconds, throw on timeout
+```
+
+Pass `null` for TTL to create a lock with no automatic expiration.
+
+`block()` polls every 250ms and also listens for Redis pub/sub release events for faster
+acquisition. Throws `Error('Could not acquire lock: <name>')` on timeout.
+
+## Common Patterns
+
+### Cache-aside with TTL
+
+```ts
+const user = await Cache.remember('user:123', 3600, async () => {
+  return await db.query('SELECT * FROM users WHERE id = 123')
+})
+```
+
+### Stale-while-revalidate
+
+Serve stale data instantly while refreshing in the background:
+
+```ts
+const dashboard = await Cache.remember(
+  'dashboard:stats',
+  { ttl: '5 minutes', swr: '1 minute' },
+  async () => computeExpensiveStats()
+)
+```
+
+### Distributed mutex
+
+Ensure only one process runs a task at a time:
+
+```ts
+const lock = Cache.lock('import-job', 60)
+const acquired = await lock.get()
+if (acquired) {
+  try {
+    await runImport()
+  } finally {
+    await lock.release()
+  }
+}
+```
+
+### Blocking lock with timeout
+
+Wait for availability:
+
+```ts
+const lock = Cache.lock('critical-section', 30)
+await lock.block(10) // wait up to 10 seconds
+try {
+  await doCriticalWork()
+} finally {
+  await lock.release()
+}
+```
+
+### Named provider instances
+
+```ts
+const sessions = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379, keyPrefix: 'sess:' })
+})
+Cache.Provider.register('sessions', sessions)
+
+// Resolve by name
+const sessCache = Cache.provider('sessions')
+await sessCache.set('abc', { userId: 1 }, 1800)
+```
+
+## Testing
+
+Use MockRedis driver in tests. Flush before each test to ensure isolation:
+
+```ts
+import { Cache } from '@maestro-js/cache'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+const cache = Cache.Provider.create({ driver: Cache.drivers.mockRedis({}) })
+
+test.beforeEach(async () => {
+  await cache.flush()
+})
+
+test('cache stores and retrieves values', async () => {
+  await cache.set('key', { a: 1 }, null)
+  expect(await cache.has('key')).toBeTruthy()
+  expect(await cache.get('key')).toEqual({ a: 1 })
+})
+
+test('remember caches on miss', async () => {
+  const result = await cache.remember('user:1', 60, async () => ({ name: 'Alice' }))
+  expect(result).toEqual({ name: 'Alice' })
+
+  let called = false
+  const cached = await cache.remember('user:1', 60, async () => {
+    called = true
+    return { name: 'Bob' }
+  })
+  expect(cached).toEqual({ name: 'Alice' })
+  expect(called).toBe(false)
+})
+
+test('locks acquire and release', async () => {
+  const lock = cache.lock('test-lock', null)
+  expect(await lock.isAvailable()).toBe(true)
+  await lock.get()
+  expect(await lock.isAvailable()).toBe(false)
+  await lock.release()
+  expect(await lock.isAvailable()).toBe(true)
+})
+```
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/cache test          # all cache tests
+cd packages/cache && npx beartest ./tests/cache.test.ts  # single file
+```
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation),
+  `@maestro-js/log` (structured logging in drivers)
+- **Used by**: `@maestro-js/cache-control` (HTTP cache-control headers backed by cache)
+- **Complements**: `@maestro-js/context` (per-request via AsyncLocalStorage; cache is
+  cross-request shared state)
+
+## Driver Interface
+
+Implement `Cache.Driver` to create a custom backend:
+
+```ts
+interface CacheDriver {
+  has(key: string): Promise<boolean>
+  get(key: string): Promise<any | null>
+  set(key: string, value: any, ttlSeconds: number): Promise<unknown>
+  add(key: string, value: any, ttlSeconds: number): Promise<boolean>
+  setForever(key: string, value: any): Promise<unknown>
+  del(key: string): Promise<unknown>
+  increment(key: string, value: number): Promise<number>
+  decrement(key: string, value: number): Promise<number>
+  flush(): Promise<unknown>
+  getPrefix(): string
+  lock(name: string, ttlSeconds: number | null): Cache.Lock
+}
+```
+
+Source: `packages/cache/src/cache-types.ts`
+
+## Key Source Files
+
+- `packages/cache/src/index.ts` -- main export, Provider pattern, `create()`, `remember()` logic
+- `packages/cache/src/cache-types.ts` -- `CacheDriver` and `CacheLock` interfaces
+- `packages/cache/src/redis-cache-driver.ts` -- production Redis driver
+- `packages/cache/src/mock-redis-cache-driver.ts` -- in-memory mock driver for tests
+- `packages/cache/src/duration.ts` -- `DurationString` type and parser
+- `packages/cache/tests/cache.test.ts` -- core cache and remember/SWR tests
+- `packages/cache/tests/cache-locks.test.ts` -- distributed lock tests

package/dist/maestro-packages/config.md

@@ -0,0 +1,203 @@
+---
+name: config
+description: "Configuration loader for .env files and TypeScript/JavaScript config modules with AES-256-GCM encryption support. Use when working with @maestro-js/config, including loading config into process.env, reading/writing encrypted .env files, creating config modules, deriving computed env values, and generating encryption keys. Key capabilities: load config files, parse .env files (plaintext or encrypted), encrypt/decrypt env files, generate encryption keys, resolve config modules (named exports, default exports, sync/async functions), type-safe process.env via Config.Resolve utility type, and auto-load via node --import @maestro-js/config/load."
+---
+
+# @maestro-js/config
+
+Standalone configuration loader that reads `.env` files (plaintext or AES-256-GCM encrypted), imports a TypeScript or JavaScript config module, and writes the resolved key-value pairs into `process.env`. Zero `@maestro-js` dependencies.
+
+## Quick Setup
+
+```ts
+import { Config } from '@maestro-js/config'
+
+// Load config into process.env (existing keys are NOT overwritten)
+await Config.loadConfigFile({
+  rootDir: process.cwd(),
+  configName: 'app',
+  envName: 'production',
+  encryptionKey: process.env.MAESTRO_ENV_ENCRYPTION_KEY ?? null
+})
+```
+
+Or auto-load at startup without application code:
+
+```bash
+node --import @maestro-js/config/load --config app --env production --root /path/to/project
+```
+
+## API Reference
+
+### ConfigOptions
+
+Every primary function accepts this options object:
+
+```ts
+type ConfigOptions = {
+  rootDir: string           // Project root directory
+  configName: string        // Config file name without extension (looked up in <rootDir>/config/)
+  envName: string | null    // Environment name (.env.<envName>) or null for .env
+  encryptionKey: string | null  // 64-char hex key for encrypted .env files, or null
+}
+```
+
+### Config.loadConfigFile(options: ConfigOptions): Promise<void>
+
+Read the `.env` file, import the config file, and write the resolved values into `process.env`. Keys already present in `process.env` are not overwritten.
+
+### Config.getConfig(options: ConfigOptions): Promise<NodeJS.Dict<string>>
+
+Same as `loadConfigFile` but returns the resolved config object without modifying `process.env`.
+
+### Config.getEnvVars(options): NodeJS.Dict<string>
+
+Read and parse an env file (plaintext or encrypted). Returns `{}` if no env file is found. Throws if an encrypted file is found but no `encryptionKey` is provided.
+
+```ts
+Config.getEnvVars({ rootDir: '.', envName: null, encryptionKey: null })
+// => { FOO: 'bar', BAZ: 'qux' }
+```
+
+### Config.resolveConfig(module: any): Promise<NodeJS.Dict<string>>
+
+Normalize an imported config module into a flat string dictionary. Handles four export shapes: named exports, default object, default sync function, and default async function. Numbers and booleans are stringified. Objects and arrays throw.
+
+### Config.generateEncryptedEnvFile(options): void
+
+Read a plaintext `.env` file and write its AES-256-GCM encrypted counterpart (`.env.encrypted` or `.env.<envName>.encrypted`).
+
+```ts
+Config.generateEncryptedEnvFile({
+  rootDir: process.cwd(),
+  envName: null,
+  encryptionKey: key
+})
+```
+
+### Config.generateDecryptedEnvFile(options): void
+
+Read an encrypted `.env.encrypted` file and write the decrypted plaintext. Throws if the target file already exists unless `force: true`.
+
+```ts
+Config.generateDecryptedEnvFile({
+  rootDir: process.cwd(),
+  envName: 'production',
+  encryptionKey: key,
+  force: true
+})
+```
+
+### Config.generateEncryptionKey(): string
+
+Generate a cryptographically random 32-byte key as a 64-character hex string.
+
+```ts
+const key = Config.generateEncryptionKey()
+// => '7a3f8b2c...' (64 hex chars)
+```
+
+### Config.Resolve<T> (type utility)
+
+Extract the resolved key-value shape from a config module type. Use in an `environment.d.ts` file to make `process.env` type-safe.
+
+```ts
+import type { Config } from '@maestro-js/config'
+import type appConfig from './config/app.ts'
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv extends Config.Resolve<typeof appConfig> {}
+  }
+}
+```
+
+## Common Patterns
+
+### Config file with named exports
+
+Place config files in `<rootDir>/config/`. Supported extensions: `.mts`, `.cts`, `.ts`, `.mjs`, `.cjs`, `.js`.
+
+```ts
+// config/app.ts
+export const DB_HOST = 'localhost'
+export const DB_PORT = '3306'
+export const DEBUG = true  // stringified to 'true'
+```
+
+### Config file as a function (derive values from .env)
+
+When the config exports a function, it receives the merged env vars (process.env values take precedence over .env file values).
+
+```ts
+// config/app.ts
+export default (env: Record<string, string | undefined>) => ({
+  DATABASE_URL: `mysql://${env.DB_USER}:${env.DB_PASS}@${env.DB_HOST}:${env.DB_PORT}/${env.DB_NAME}`,
+  API_KEY: env.API_KEY
+})
+```
+
+### Async config function
+
+```ts
+// config/app.ts
+export default async (env: Record<string, string | undefined>) => {
+  return {
+    SECRET: env.SECRET,
+    COMPUTED: await someAsyncOperation()
+  }
+}
+```
+
+### Env file resolution order
+
+When `envName` is provided (e.g., `'production'`), files are checked in this order:
+1. `.env.production`
+2. `.env.production.encrypted`
+3. `.env`
+4. `.env.encrypted`
+
+When `envName` is null:
+1. `.env`
+2. `.env.encrypted`
+
+### Encryption round-trip
+
+```ts
+const key = Config.generateEncryptionKey()
+
+// Encrypt: reads .env, writes .env.encrypted
+Config.generateEncryptedEnvFile({ rootDir: '.', envName: null, encryptionKey: key })
+
+// Decrypt: reads .env.encrypted, writes .env
+Config.generateDecryptedEnvFile({ rootDir: '.', envName: null, encryptionKey: key, force: true })
+```
+
+Encrypted values use the format `<iv_base64>.<authTag_base64>.<ciphertext_base64>` per key.
+
+### Auto-load entry point
+
+The `@maestro-js/config/load` export is a standalone script intended for `node --import`. It parses CLI arguments and calls `Config.loadConfigFile`.
+
+CLI flags:
+- `--config <name>` (required) -- config file name without extension
+- `--env <name>` -- environment name
+- `--key <hex>` -- encryption key (falls back to `MAESTRO_ENV_ENCRYPTION_KEY` env var)
+- `--root <path>` -- project root (defaults to `process.cwd()`)
+
+## Cross-Package Integration
+
+Config is a standalone package with zero `@maestro-js` dependencies. It is used by:
+
+- **CLI** -- The Maestro CLI uses `Config.generateEncryptedEnvFile`, `Config.generateDecryptedEnvFile`, and `Config.generateEncryptionKey` for the `env:encrypt`, `env:decrypt`, and `env:gen-key` commands.
+- **Application boot** -- Applications use `Config.loadConfigFile` (or `node --import @maestro-js/config/load`) to populate `process.env` before initializing other Maestro packages that read from `process.env`.
+- **Type safety** -- The `Config.Resolve` utility type lets applications create a typed `process.env` derived from the config module shape.
+
+## Testing
+
+```bash
+pnpm --filter @maestro-js/config test
+cd packages/config && npx beartest ./tests/config.test.ts
+```
+
+Tests use `beartest-js` with `expect`. They create temporary directories, write config/env files, and verify loading, encryption round-trips, and error cases.