@cyanheads/mcp-ts-core 0.1.0-beta.12

package/skills/api-utils/references/parsing.md

@@ -0,0 +1,263 @@
+# Parsing Utilities (`utils/parsing`)
+
+```ts
+import { yamlParser, xmlParser, csvParser, jsonParser, pdfParser, dateParser, frontmatterParser } from '@cyanheads/mcp-ts-core/utils/parsing';
+```
+
+All parsers are **Tier 3** — lazy-load their peer dependency on first call. All methods are **async** unless noted.
+
+**Common behavior:**
+- Singleton instances exported alongside classes
+- `<think>...</think>` blocks at the start of input are automatically stripped and logged at `debug` level (except `dateParser` and `pdfParser`)
+- All `context?: RequestContext` parameters are optional (synthetic context created if omitted)
+- Errors throw `McpError` — never return error values
+
+---
+
+## `yamlParser`
+
+**Peer dep:** `js-yaml` (`bun add js-yaml`)
+
+| Method | Signature |
+|:-------|:----------|
+| `parse` | `<T = unknown>(yamlString, context?) -> Promise<T>` |
+
+Uses `js-yaml` `DEFAULT_SCHEMA`. Throws `ConfigurationError` if dep missing, `ValidationError` on empty/malformed input.
+
+```ts
+const config = await yamlParser.parse<ServerConfig>(yamlString);
+```
+
+---
+
+## `xmlParser`
+
+**Peer dep:** `fast-xml-parser` (`bun add fast-xml-parser`)
+
+| Method | Signature |
+|:-------|:----------|
+| `parse` | `<T = unknown>(xmlString, context?) -> Promise<T>` |
+
+Internal `XMLParser` instance constructed once with `{ processEntities: false, htmlEntities: false }` and cached. Entity refs pass through as-is.
+
+```ts
+const data = await xmlParser.parse<FeedResponse>(xmlString);
+```
+
+---
+
+## `csvParser`
+
+**Peer dep:** `papaparse` (`bun add papaparse`)
+
+| Method | Signature |
+|:-------|:----------|
+| `parse` | `<T = unknown>(csvString, options?, context?) -> Promise<Papa.ParseResult<T>>` |
+
+`options` is `Papa.ParseConfig` forwarded verbatim — key options: `header`, `delimiter`, `dynamicTyping`. Returns `{ data: T[], errors: ParseError[], meta: ParseMeta }`. Throws `ValidationError` if `result.errors` is non-empty.
+
+```ts
+const result = await csvParser.parse<Row>(csvString, { header: true, dynamicTyping: true });
+for (const row of result.data) { /* ... */ }
+```
+
+---
+
+## `jsonParser`
+
+**Peer dep:** `partial-json` (`bun add partial-json`)
+
+| Method | Signature |
+|:-------|:----------|
+| `parse` | `<T = unknown>(jsonString, allowPartial?, context?) -> Promise<T>` |
+
+`allowPartial` defaults to `Allow.ALL`. Combine `Allow` flags with bitwise OR for fine-grained control over what partial constructs to accept.
+
+### `Allow` flags
+
+| Flag | Value | Meaning |
+|:-----|------:|:--------|
+| `STR` | `0x1` | Partial strings |
+| `NUM` | `0x2` | Partial numbers |
+| `ARR` | `0x4` | Partial arrays |
+| `OBJ` | `0x8` | Partial objects |
+| `NULL` | `0x10` | Partial nulls |
+| `BOOL` | `0x20` | Partial booleans |
+| `NAN` | `0x40` | NaN values |
+| `INFINITY` | `0x80` | Positive Infinity |
+| `_INFINITY` | `0x100` | Negative Infinity |
+| `INF` | `0x180` | Both Infinity variants |
+| `SPECIAL` | `0x1F0` | NULL \| BOOL \| NAN \| INF |
+| `ATOM` | `0x1F3` | All atomic types |
+| `COLLECTION` | `0xC` | ARR \| OBJ |
+| `ALL` | `0x1FF` | Everything (default) |
+
+```ts
+// Parse streaming/partial JSON from LLM output
+const partial = await jsonParser.parse<ToolCall>(chunk, Allow.OBJ | Allow.STR);
+
+// Strict parse — no partial constructs
+const strict = await jsonParser.parse<Config>(jsonString, 0);
+```
+
+---
+
+## `pdfParser`
+
+**Peer deps:** `pdf-lib` + `unpdf` (`bun add pdf-lib unpdf`)
+
+### Methods
+
+| Method | Sync? | Signature |
+|:-------|:------|:----------|
+| `createDocument` | async | `(context?) -> Promise<PDFDocument>` |
+| `loadDocument` | async | `(pdfBytes, context?) -> Promise<PDFDocument>` |
+| `addPage` | **sync** | `(doc, options?) -> PDFPage` |
+| `embedFont` | async | `(doc, fontName?, context?) -> Promise<PDFFont>` |
+| `embedImage` | async | `(doc, options, context?) -> Promise<PDFImage>` |
+| `drawText` | async | `(page, options) -> Promise<void>` |
+| `drawImage` | async | `(page, options) -> Promise<void>` |
+| `mergePdfs` | async | `(pdfBytesArray, context?) -> Promise<PDFDocument>` |
+| `splitPdf` | async | `(pdfBytes, ranges, context?) -> Promise<PDFDocument[]>` |
+| `fillForm` | **sync** | `(doc, options, context?) -> void` |
+| `extractMetadata` | **sync** | `(doc) -> PdfMetadata` |
+| `setMetadata` | **sync** | `(doc, metadata) -> void` |
+| `extractText` | async | `(doc, options?, context?) -> Promise<ExtractTextResult>` |
+| `saveDocument` | async | `(doc, context?) -> Promise<Uint8Array>` |
+
+### Option types
+
+```ts
+interface AddPageOptions { height?: number; width?: number }  // default: 612x792 (US Letter)
+
+interface DrawTextOptions {
+  text: string; x: number; y: number;
+  size?: number;        // default 12
+  font?: PDFFont;       // default Helvetica
+  color?: RGB;          // default black
+  rotate?: number;      // degrees, default 0
+  maxWidth?: number;    // enables word-wrap when set
+  lineHeight?: number;  // multiplier, default 1.2
+}
+
+interface EmbedImageOptions { imageBytes: Uint8Array | ArrayBuffer; format: 'png' | 'jpg' }
+
+interface DrawImageOptions {
+  image: PDFImage; x: number; y: number;
+  width?: number; height?: number;  // default: intrinsic dimensions
+  rotate?: number; opacity?: number; // default: 0, 1
+}
+
+interface PageRange { start: number; end: number }  // 0-based, inclusive
+
+interface FillFormOptions {
+  fields: Record<string, string | boolean | number>;
+  flatten?: boolean;  // default false — flatten removes form interactivity
+}
+
+interface ExtractTextOptions { mergePages?: boolean }  // default false
+
+interface ExtractTextResult { text: string | string[]; totalPages: number }
+// mergePages=true -> single string; false -> string[] per page
+
+interface PdfMetadata {
+  pageCount: number;
+  title?: string; author?: string; subject?: string; keywords?: string;
+  creator?: string; producer?: string;
+  creationDate?: string; modificationDate?: string;  // ISO 8601
+}
+
+interface SetMetadataOptions {
+  title?: string; author?: string; subject?: string; keywords?: string;
+  creator?: string; producer?: string;
+}
+```
+
+Also re-exports from `pdf-lib`: `PDFDocument`, `PDFFont`, `PDFImage`, `PDFPage`, `RGB`.
+
+### Usage
+
+```ts
+// Create a PDF
+const doc = await pdfParser.createDocument();
+const page = pdfParser.addPage(doc, { width: 612, height: 792 });
+const font = await pdfParser.embedFont(doc, 'Helvetica');
+await pdfParser.drawText(page, { text: 'Hello', x: 50, y: 700, font, size: 24 });
+const bytes = await pdfParser.saveDocument(doc);
+
+// Extract text from existing PDF
+const loaded = await pdfParser.loadDocument(existingBytes);
+const result = await pdfParser.extractText(loaded, { mergePages: true });
+// result: { text: 'full document text', totalPages: 5 }
+
+// Merge multiple PDFs
+const merged = await pdfParser.mergePdfs([pdf1Bytes, pdf2Bytes]);
+
+// Fill form fields
+pdfParser.fillForm(doc, {
+  fields: { name: 'Alice', approved: true, score: 95 },
+  flatten: true,
+});
+```
+
+---
+
+## `dateParser`
+
+**Peer dep:** `chrono-node` (`bun add chrono-node`)
+
+Unlike other parsers, `dateParser` is a plain object (not a class singleton) and `context` is **required**.
+
+| Method | Signature | Returns |
+|:-------|:----------|:--------|
+| `parseDate` | `(text, context, refDate?) -> Promise<Date \| null>` | First parsed date, or `null` |
+| `parse` | `(text, context, refDate?) -> Promise<chrono.ParsedResult[]>` | Full chrono results array |
+
+Both use `forwardDate: true` — ambiguous relative dates resolve to the next future occurrence.
+
+Also exported as standalone functions: `parseDateString` (= `parseDate`) and `parseDateStringDetailed` (= `parse`).
+
+```ts
+const date = await dateParser.parseDate('next Tuesday at 3pm', ctx);
+// Date object for the upcoming Tuesday
+
+const results = await dateParser.parse('between March 1 and March 15', ctx);
+// Array of ParsedResult with start/end components
+```
+
+---
+
+## `frontmatterParser`
+
+**Peer dep:** inherits `js-yaml` via `yamlParser` (`bun add js-yaml`)
+
+| Method | Signature |
+|:-------|:----------|
+| `parse` | `<T = unknown>(markdown, context?) -> Promise<FrontmatterResult<T>>` |
+
+```ts
+interface FrontmatterResult<T = unknown> {
+  frontmatter: T;         // parsed YAML object, or {} if none found
+  content: string;        // markdown body after frontmatter block
+  hasFrontmatter: boolean;
+}
+```
+
+Matches `--- ... ---` at the very start of the document. An empty `---\n---` block returns `frontmatter: {}` with `hasFrontmatter: true`. Delegates YAML parsing to `yamlParser`, so `<think>` blocks are also stripped from the YAML content.
+
+```ts
+const { frontmatter, content, hasFrontmatter } = await frontmatterParser.parse<SkillMeta>(markdown);
+if (hasFrontmatter) {
+  console.log(frontmatter.name, frontmatter.version);
+}
+```
+
+---
+
+## `thinkBlockRegex`
+
+Exported from the barrel. Regex: `/^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/`
+
+- Group 1: content inside `<think>` tag
+- Group 2: payload after the closing tag
+- Only matches when `<think>` is the very first character of the string

package/skills/api-utils/references/security.md

@@ -0,0 +1,226 @@
+# Security Utilities (`utils/security`)
+
+```ts
+import { sanitization, RateLimiter, IdGenerator, idGenerator, generateUUID, generateRequestContextId } from '@cyanheads/mcp-ts-core/utils/security';
+```
+
+---
+
+## `sanitization`
+
+Pre-constructed singleton of `Sanitization`. Tier 3 peers: `sanitize-html`, `validator` (install as needed per method).
+
+### Methods
+
+| Method | Async | Peer dep | Signature |
+|:-------|:------|:---------|:----------|
+| `sanitizeHtml` | yes | `sanitize-html` | `(input, config?) -> Promise<string>` |
+| `sanitizeString` | yes | `sanitize-html` / `validator` | `(input, options?) -> Promise<string>` |
+| `sanitizeUrl` | yes | `validator` | `(input, allowedProtocols?) -> Promise<string>` |
+| `sanitizeNumber` | yes | `validator` (string input) | `(input, min?, max?) -> Promise<number>` |
+| `sanitizePath` | **no** | Node.js only | `(input, options?) -> SanitizedPathInfo` |
+| `sanitizeJson` | **no** | none | `<T>(input, maxSize?) -> T` |
+| `sanitizeForLogging` | **no** | none | `(input) -> unknown` |
+| `redactSensitiveFields` | **no** | none | `(data, fields?, ctx?) -> unknown` |
+| `getSensitivePinoFields` | **no** | none | `() -> string[]` |
+
+### Option types
+
+```ts
+interface HtmlSanitizeConfig {
+  allowedTags?: string[];
+  allowedAttributes?: sanitizeHtml.IOptions['allowedAttributes'];
+  preserveComments?: boolean;
+  transformTags?: sanitizeHtml.IOptions['transformTags'];
+}
+
+interface SanitizeStringOptions {
+  context?: 'text' | 'html' | 'attribute' | 'url' | 'javascript';  // default: 'text'
+  allowedTags?: string[];          // only used when context: 'html'
+  allowedAttributes?: Record<string, string[]>;  // only used when context: 'html'
+}
+
+interface PathSanitizeOptions {
+  allowAbsolute?: boolean;  // default: false
+  rootDir?: string;         // resolved via path.resolve before use
+  toPosix?: boolean;        // normalize backslashes to /
+}
+
+interface SanitizedPathInfo {
+  sanitizedPath: string;
+  originalInput: string;
+  wasAbsolute: boolean;
+  convertedToRelative: boolean;
+  optionsUsed: PathSanitizeOptions;
+}
+```
+
+### Behavior notes
+
+- `sanitizeHtml`: returns `''` for falsy input; `<a>` tags get `rel="noopener noreferrer"` by default
+- `sanitizeString`: `'javascript'` context always throws `McpError(ValidationError)` — no JavaScript allowed
+- `sanitizeUrl`: default protocols `['http', 'https']`; always blocks `javascript:`, `data:`, `vbscript:`
+- `sanitizePath`: **Node-only** — throws `McpError(InternalError)` in Workers. Throws `McpError(ValidationError)` on path traversal or null bytes.
+- `sanitizeJson`: `maxSize` is bytes (UTF-8); uses `Buffer.byteLength` / `TextEncoder` / `string.length` fallback chain
+- `sanitizeNumber`: `NaN`/`Infinity` always rejected; out-of-range values silently clamped with debug log
+- `sanitizeForLogging`: deep clones via `structuredClone`; returns `'[Log Sanitization Failed]'` on clone error
+
+### Sensitive fields
+
+Pre-populated: `password`, `token`, `secret`, `apiKey`, `credential`, `jwt`, `ssn`, `cvv`, `authorization`, `cookie`, `clientsecret`, `client_secret`, `private_key`, `privatekey`.
+
+Manage with `setSensitiveFields(fields)` (merges, deduped, lowercased) and `getSensitiveFields()`. `getSensitivePinoFields()` generates 3-depth pino `redact.paths` patterns from the current list.
+
+### Usage
+
+```ts
+// HTML sanitization
+const clean = await sanitization.sanitizeHtml(userHtml, {
+  allowedTags: ['p', 'b', 'i', 'a'],
+  allowedAttributes: { a: ['href'] },
+});
+
+// URL validation
+const safeUrl = await sanitization.sanitizeUrl(userUrl, ['http', 'https', 'mailto']);
+
+// Path sanitization (Node-only)
+const info = sanitization.sanitizePath(userPath, { rootDir: '/app/data', allowAbsolute: false });
+// info.sanitizedPath is safe to use in fs operations
+
+// JSON with size limit
+const data = sanitization.sanitizeJson<Config>(rawJson, 1024 * 1024); // 1MB max
+
+// Logging redaction
+const safe = sanitization.sanitizeForLogging({ password: 'secret', name: 'Alice' });
+// { password: '[REDACTED]', name: 'Alice' }
+```
+
+Also exported: `sanitizeInputForLogging(input)` — convenience wrapper around `sanitization.sanitizeForLogging`.
+
+---
+
+## `RateLimiter`
+
+In-process sliding window rate limiter with LRU eviction and OTEL span annotations.
+
+### Constructor
+
+```ts
+new RateLimiter(config: AppConfig, logger: Logger)
+```
+
+Reads initial settings from `AppConfig`. Call `configure()` to override at runtime.
+
+### Configuration
+
+```ts
+interface RateLimitConfig {
+  maxRequests: number;            // required
+  windowMs: number;               // required, in milliseconds
+  cleanupInterval?: number;       // ms between expired entry purges
+  maxTrackedKeys?: number;        // default 10,000; LRU eviction beyond this
+  skipInDevelopment?: boolean;    // skips limiting when environment === 'development'
+  errorMessage?: string;          // supports {waitTime} placeholder
+  keyGenerator?: (identifier: string, context?: RequestContext) => string;
+}
+```
+
+Defaults: `windowMs` 15 min, `maxRequests` 100, `cleanupInterval` 5 min, `maxTrackedKeys` 10,000.
+
+### Methods
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `configure` | `(config: Partial<RateLimitConfig>) -> void` | Merges partial config; restarts cleanup timer if `cleanupInterval` changed |
+| `check` | `(key, context?) -> void` | Throws `McpError(RateLimited)` with data `{ waitTimeSeconds, key, limit, windowMs }` when exceeded; annotates active OTEL span |
+| `getStatus` | `(key) -> { current, limit, remaining, resetTime } \| null` | Does NOT apply `keyGenerator` — pass the already-resolved key |
+| `getConfig` | `() -> RateLimitConfig` | Shallow copy of effective config |
+| `reset` | `() -> void` | Clears all tracked entries (no per-key reset) |
+| `dispose` | `() -> void` | Stops cleanup timer and clears all entries; call on shutdown |
+
+### Usage
+
+```ts
+// In a service — check before expensive operation
+rateLimiter.check(`api:${ctx.tenantId}`, ctx);
+
+// Check status without consuming a request
+const status = rateLimiter.getStatus('api:tenant-123');
+if (status) {
+  console.log(`${status.remaining} requests left, resets at ${new Date(status.resetTime)}`);
+}
+
+// Runtime reconfiguration
+rateLimiter.configure({ maxRequests: 200, windowMs: 60_000 });
+
+// Cleanup on shutdown
+rateLimiter.dispose();
+```
+
+---
+
+## `IdGenerator` / `idGenerator`
+
+Crypto-random ID generation via Web Crypto API (`crypto.getRandomValues`). Rejection sampling prevents modulo bias.
+
+### Constructor
+
+```ts
+new IdGenerator(entityPrefixes?: EntityPrefixConfig)
+```
+
+`idGenerator` is the pre-constructed singleton (no prefixes registered by default).
+
+### Configuration
+
+```ts
+interface EntityPrefixConfig {
+  [key: string]: string;  // entityType -> prefix, e.g. { project: 'PROJ', task: 'TASK' }
+}
+
+interface IdGenerationOptions {
+  charset?: string;    // default: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  length?: number;     // default: 6 (random part length)
+  separator?: string;  // default: '_'
+}
+```
+
+### Methods
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `generate` | `(prefix?, options?) -> string` | `PREFIX_XXXXXX` or just `XXXXXX` if no prefix |
+| `generateForEntity` | `(entityType, options?) -> string` | Uses registered prefix; throws `McpError(ValidationError)` if type unknown |
+| `generateRandomString` | `(length?, charset?) -> string` | Raw random string; defaults: length 6, charset `A-Z0-9` |
+| `isValid` | `(id, entityType, options?) -> boolean` | Regex-validates format against prefix + separator + charset{length} |
+| `getEntityType` | `(id, separator?) -> string` | Resolves entity type from prefix; throws `McpError(ValidationError)` if unknown |
+| `normalize` | `(id, separator?) -> string` | Canonical prefix casing + uppercase random part |
+| `stripPrefix` | `(id, separator?) -> string` | Returns random part; returns original if separator not found |
+| `setEntityPrefixes` | `(config) -> void` | Replaces all prefixes and rebuilds reverse lookup |
+| `getEntityPrefixes` | `() -> EntityPrefixConfig` | Copy of current config |
+
+### Standalone exports
+
+| Export | Returns | Notes |
+|:-------|:--------|:------|
+| `generateUUID()` | `string` | `crypto.randomUUID()` — UUID v4 |
+| `generateRequestContextId()` | `string` | `XXXXX-XXXXX` format (5+5 alphanumeric, hyphen-joined) |
+
+### Usage
+
+```ts
+// Simple ID with prefix
+const id = idGenerator.generate('PROJ'); // 'PROJ_A7K2M9'
+
+// Entity-based generation
+const gen = new IdGenerator({ project: 'PROJ', task: 'TASK' });
+const taskId = gen.generateForEntity('task'); // 'TASK_X3B8P1'
+const valid = gen.isValid('TASK_X3B8P1', 'task'); // true
+const type = gen.getEntityType('TASK_X3B8P1'); // 'task'
+
+// Raw random string
+const token = idGenerator.generateRandomString(32); // 32-char alphanumeric
+
+// UUIDs
+const uuid = generateUUID(); // 'a1b2c3d4-e5f6-...'
+```

package/skills/api-workers/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: api-workers
+description: >
+  Cloudflare Workers deployment using `createWorkerHandler` from `@cyanheads/mcp-ts-core/worker`. Covers the full handler signature, binding types, CloudflareBindings extensibility, runtime compatibility guards, and wrangler.toml requirements.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+`@cyanheads/mcp-ts-core/worker` exports `createWorkerHandler` — the Workers entry point. It wraps tool/resource/prompt registries into a per-request `McpServer` factory that integrates with the Cloudflare Workers runtime.
+
+---
+
+## `createWorkerHandler(options)`
+
+```ts
+import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
+import { allToolDefinitions } from './mcp-server/tools/index.js';
+import { allResourceDefinitions } from './mcp-server/resources/index.js';
+import { allPromptDefinitions } from './mcp-server/prompts/index.js';
+import { initMyService } from './services/my-domain/my-service.js';
+
+export default createWorkerHandler({
+  tools: allToolDefinitions,
+  resources: allResourceDefinitions,
+  prompts: allPromptDefinitions,
+  setup(core) {
+    initMyService(core.config, core.storage);
+  },
+  extraEnvBindings: [['MY_API_KEY', 'MY_API_KEY']],
+  extraObjectBindings: [['MY_CUSTOM_KV', 'MY_CUSTOM_KV']],
+  onScheduled: async (controller, env, ctx) => {
+    // Cloudflare cron trigger handler
+  },
+});
+```
+
+### Options
+
+| Option | Type | Purpose |
+|:-------|:-----|:--------|
+| `tools` | `AnyToolDefinition[]` | Tool definitions to register |
+| `resources` | `AnyResourceDefinition[]` | Resource definitions to register |
+| `prompts` | `PromptDefinition[]` | Prompt definitions to register |
+| `setup` | `(core: CoreServices) => void \| Promise<void>` | Runs after core services are ready, before first request |
+| `extraEnvBindings` | `[bindingKey: string, processEnvKey: string][]` | Maps CF string bindings to `process.env` keys |
+| `extraObjectBindings` | `[bindingKey: string, globalKey: string][]` | Maps CF object bindings (KV, R2, D1, AI) to `globalThis` keys |
+| `onScheduled` | `(controller, env, ctx) => Promise<void>` | Cloudflare cron trigger handler |
+
+### Key design points
+
+- **Per-request `McpServer` factory** — a new server instance is created for each request. Required by SDK security advisory GHSA-345p-7cg4-v4c7.
+- **Env bindings refreshed per-request** — Cloudflare may rotate binding object references between requests; the handler re-injects them on every call.
+- **`ctx.waitUntil()` is documented but not yet called by the framework** — the `ExecutionContext` is received and passed through to `app.fetch` and `onScheduled`, but the framework itself does not currently call `ctx.waitUntil()` for telemetry flush. Spans complete synchronously within the request lifecycle.
+- **Singleton app promise with retry-on-failure** — the framework init runs once; if it fails, the next request retries rather than leaving the Worker in a permanently broken state.
+
+---
+
+## Binding types
+
+Cloudflare Workers bindings come in two kinds with different injection mechanisms:
+
+| Type | Examples | Injection mechanism | Runtime access |
+|:-----|:---------|:--------------------|:---------------|
+| String values | API keys, base URLs, feature flags | `injectEnvVars()` → `process.env` | `process.env.MY_API_KEY` |
+| Object bindings | KV namespace, R2 bucket, D1 database, AI | `storeBindings()` → `globalThis` | `(globalThis as any).MY_CUSTOM_KV` |
+
+**`extraEnvBindings`** — array of `[bindingKey, processEnvKey]` tuples. The value of `env[bindingKey]` is assigned to `process.env[processEnvKey]` at request time.
+
+**`extraObjectBindings`** — array of `[bindingKey, globalKey]` tuples. The object at `env[bindingKey]` is stored on `globalThis[globalKey]` at request time.
+
+Both are refreshed on every request. Never cache binding references between requests.
+
+---
+
+## `CloudflareBindings` extensibility
+
+Core defines `CloudflareBindings` without an index signature, so servers extend it via intersection rather than module augmentation:
+
+```ts
+import type { CloudflareBindings as CoreBindings } from '@cyanheads/mcp-ts-core/worker';
+
+interface MyBindings extends CoreBindings {
+  MY_CUSTOM_KV: KVNamespace;
+  MY_R2_BUCKET: R2Bucket;
+}
+```
+
+Pass `MyBindings` as a type parameter where the framework accepts a generic env type (e.g., Hono route handlers, `onScheduled`).
+
+---
+
+## Runtime compatibility
+
+### `runtimeCaps` feature detection
+
+```ts
+import { runtimeCaps } from '@cyanheads/mcp-ts-core/utils/runtime';
+
+if (runtimeCaps.isWorkerLike) {
+  // Workers-specific path
+}
+
+if (runtimeCaps.isNode) {
+  // Node.js-specific path (e.g., filesystem access)
+}
+```
+
+`runtimeCaps` is a snapshot taken at import time. Fields: `isNode`, `isBun`, `isWorkerLike`, `isBrowserLike`, `hasProcess`, `hasBuffer`, `hasTextEncoder`, `hasPerformanceNow`. All booleans, never throw.
+
+### Serverless storage whitelist
+
+In Workers, only these storage providers are allowed:
+
+| Provider | Notes |
+|:---------|:------|
+| `in-memory` | Default — data lost on cold start, no persistence |
+| `cloudflare-kv` | KV namespace binding — eventually consistent |
+| `cloudflare-r2` | R2 bucket binding — object storage |
+| `cloudflare-d1` | D1 database binding — SQLite-compatible |
+
+`filesystem` and `supabase` providers are not on the whitelist. In a serverless environment, any non-whitelisted provider type is **silently forced to `in-memory`** (a warning is logged) rather than throwing. Set `STORAGE_PROVIDER_TYPE` to one of the whitelisted values to avoid the fallback.
+
+---
+
+## `wrangler.toml` requirements
+
+```toml
+compatibility_flags = ["nodejs_compat"]
+compatibility_date = "2025-09-01"  # must be >= 2025-09-01
+
+[[kv_namespaces]]
+binding = "MY_CUSTOM_KV"
+id = "..."
+
+[[r2_buckets]]
+binding = "MY_R2_BUCKET"
+bucket_name = "..."
+```
+
+`nodejs_compat` is required for Node.js API shims (e.g., `process.env`, `Buffer`, `crypto`). The minimum `compatibility_date` activates the required shim set.
+
+---
+
+## Workers-specific warnings
+
+**Lazy env parsing is mandatory.** Cloudflare injects env bindings at request time via `injectEnvVars()` — after all static module imports complete. Never parse `process.env` at module top-level in Workers:
+
+```ts
+// WRONG — parsed before env is injected
+const apiKey = process.env.MY_API_KEY;  // undefined in Workers
+
+// CORRECT — lazy parse inside a function or getter
+export function getServerConfig() {
+  return ServerConfigSchema.parse({ apiKey: process.env.MY_API_KEY });
+}
+```
+
+**`in-memory` storage is volatile.** Data stored with the `in-memory` provider is lost between cold starts and is not shared across Worker instances. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for any state that must persist or be shared.
+
+**Node-only utilities throw in Workers.** `scheduler` (`node-cron`), `sanitizePath` (fs-based), and `filesystem` storage provider all throw `ConfigurationError` when called from a Worker. Guard with `runtimeCaps.isNode` or avoid entirely.

package/skills/devcheck/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: devcheck
+description: >
+  Lint, format, typecheck, and audit the project. Use after making changes, before committing, or when the user asks to verify the project is clean.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: workflow
+---
+
+## Steps
+
+1. Run `bun run devcheck`
+2. Read the output carefully — it runs lint, format check, typecheck, and security audit
+3. If there are failures, fix the issues in the source files
+4. Re-run `bun run devcheck` until clean
+5. Do not consider this skill complete until the command exits successfully with no errors
+
+## Common Issues
+
+| Error Type | Typical Fix |
+|:-----------|:------------|
+| Lint errors | Fix code style issues, unused imports, missing types |
+| Format errors | Run `bun run format` or fix manually |
+| Type errors | Fix type mismatches, missing properties, incorrect generics |
+| Security audit | Update vulnerable dependencies with `bun update` |
+
+## Checklist
+
+- [ ] `bun run devcheck` exits with no errors