@cyanheads/mcp-ts-core 0.4.0 → 0.5.0

package/skills/maintenance/SKILL.md

@@ -1,48 +1,167 @@
 ---
 name: maintenance
 description: >
-  Sync skills and dependencies after package updates. Use after running `bun update @cyanheads/mcp-ts-core` to ensure project skills are up to date, or periodically to check for drift.
+  Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
 
-## Context
+## When to Use
 
-Skills flow from the package to the project:
+- After running `bun update --latest` yourself and wanting to review the impact (**Mode B** — typical)
+- To run the whole flow end-to-end — outdated check → update → investigate → adopt → verify (**Mode A**)
+- Periodically, to check for skill drift from the package
 
-1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source, updated via `bun update`)
-2. **Project** — `skills/` at project root (working copy, can have local overrides or server-specific skills)
+## Entry Modes
 
-After `bun update @cyanheads/mcp-ts-core`, the package may have newer skills than the project. This skill syncs them and handles general dependency upkeep.
+| Mode | Starting Point | First Step |
+|:-----|:---------------|:-----------|
+| **A — Full flow** | Lockfile is current; want to update | Step 1 |
+| **B — Post-update review** | User already ran `bun update --latest` + `bun run rebuild` + `bun run test` | Skip to Step 3 with the update output or `git diff bun.lock` |
+
+Both modes converge at Step 3 and end at Step 8.
 
 ## Steps
 
-### Sync project skills (Package → Project)
+### 1. Survey what's outdated (Mode A only)
+
+```bash
+bun outdated
+```
+
+Note: `bun update --latest` crosses semver majors; `bun update` alone respects ranges. Use `--latest` unless a package is intentionally pinned.
+
+### 2. Apply the update (Mode A only)
+
+```bash
+bun update --latest
+```
+
+Capture the `↑ package old → new` lines from stdout — these feed Step 3. Alternatively, `git diff bun.lock` surfaces version deltas after the fact.
+
+### 3. Investigate changelogs
+
+Invoke the **`changelog`** skill with the captured list of updated packages. It resolves each repo, fetches release notes (or CHANGELOG entries) between old and new versions, and cross-references changes against actual imports in `src/`. Output per package: what changed, impact on this project, action items.
+
+Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks.
+
+### 4. Framework review (`@cyanheads/mcp-ts-core`)
+
+If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. Read:
+
+```bash
+node_modules/@cyanheads/mcp-ts-core/CHANGELOG.md
+```
+
+Extract entries between the old and new version. Scan specifically for:
+
+| Area | Adoption Check |
+|:-----|:---------------|
+| New error factories in `/errors` | Replace ad-hoc `new McpError(...)` with factories where applicable |
+| New utilities in `/utils` | Identify any that supersede local helper code |
+| New context capabilities | Added `ctx.*` methods worth adopting |
+| Provider/service APIs | Updates to `OpenRouterProvider`, `SpeechService`, `GraphService`, etc. |
+| Deprecations | Migrate now, before the next breaking release |
+| Config changes | New env vars, renamed keys, changed defaults |
+| Linter rules | New definition-lint rules that may now flag existing tools/resources |
+
+Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
+
+**Template review.** The framework also ships `templates/CLAUDE.md` and `templates/AGENTS.md` as scaffolding for consumer agent protocol files. The consumer's `CLAUDE.md`/`AGENTS.md` was copied at init time and has since diverged (local customizations, echo replacements, server-specific sections). Read the upstream template fresh:
+
+```bash
+node_modules/@cyanheads/mcp-ts-core/templates/CLAUDE.md
+```
+
+Skip the mechanical diff — consumer customizations create too much noise to filter. Instead, read end-to-end with fresh eyes, mentally comparing against the current `CLAUDE.md`. Look for: new conventions, updated skill references, expanded checklists, new callouts, clearer explanations, restructured sections. Present findings; let the user cherry-pick what to adopt. Never auto-merge — the consumer's file is theirs.
+
+### 5. Sync project skills
+
+Skills flow in two hops: package → project `skills/` → agent directories.
+
+**Phase A — Package → Project `skills/`**
+
+1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source)
+2. **Project** — `skills/` at project root (working copy; may contain local overrides or server-specific skills)
+
+Procedure:
 
 1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/skills/`
 2. For each skill with `metadata.audience: external` in its `SKILL.md` frontmatter:
-   - If the skill does not exist in project `skills/`, copy the full directory
-   - If it exists, compare `metadata.version` — if the package version is newer, replace the full directory
+   - If missing in project `skills/`, copy the full directory
+   - If present, compare `metadata.version` — replace if the package version is newer
    - If the local version is equal or newer, skip (local override)
 3. Do not touch skills in `skills/` that don't exist in the package (server-specific)
 
-### Dependency updates
+**Phase B — Project `skills/` → Agent directories**
+
+The `setup` skill instructs consumers to copy `skills/*` into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:
+
+| Agent | Directory |
+|:------|:----------|
+| Claude Code | `.claude/skills/` |
+| Generic / shared | `.agents/skills/` |
+| Codex | `.codex/skills/` |
+| Cursor | `.cursor/skills/` |
+| Windsurf | `.windsurf/skills/` |
+
+For each agent directory that exists:
+
+1. For every directory in project `skills/`, copy it into the agent dir (overwrite on match, add if missing)
+2. Do **not** delete skills in the agent dir that aren't in project `skills/` — they may be general-purpose skills sourced elsewhere (e.g., `code-security`, `cloudflare`, `changelog`)
+
+If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
+
+**Report** which skills were added/updated in Phase A (with version deltas) and which agent directories were refreshed in Phase B. The user needs to know what new guidance is now available and where.
+
+### 6. Adopt changes in the codebase
+
+Apply the findings from Steps 3 and 4:
+
+- **Breaking changes** — fix call sites
+- **Deprecations** — migrate now, while context is fresh
+- **New framework features** — refactor targeted spots only; don't cargo-cult everywhere
+- **New configuration** — update `.env.example`, server config schema, README if user-facing
+
+Keep diffs focused. Don't sweep refactors beyond the update's scope.
+
+### 7. Rebuild and verify
+
+```bash
+bun run rebuild
+bun run devcheck
+bun run test
+```
+
+`rebuild` (clean + build) catches API surface and type-alignment issues that `devcheck` alone may miss — module resolution, path aliases, post-build processing. `devcheck` includes `bun audit` and `bun outdated`, so no separate audit step is needed.
+
+In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need verification.
+
+Fix anything that fails. Re-run until clean.
+
+### 8. Summary
+
+Present a concise numbered summary to the user:
 
-1. Run `bun outdated` to see what's available
-2. For any major version bumps, review changelogs before proceeding
-3. Run `bun update` to apply updates
-4. Run `bun audit` to check for vulnerabilities introduced by the update
-5. Run `bun run devcheck` to confirm lint, definitions, types, and dependency/security checks still pass
-6. Run `bun run test` to confirm runtime behavior still passes
+1. **Updated packages** — short list with version deltas (N total)
+2. **Breaking changes handled** — call sites fixed
+3. **Features adopted** — new framework APIs now in use
+4. **Skills synced** — added/updated with versions (Phase A) and agent directories refreshed (Phase B)
+5. **Needs attention** — anything deferred, flagged for decision, or risky
+6. **Status** — rebuild / devcheck / test results
 
 ## Checklist
 
-- [ ] Package skills compared against project `skills/` (version check)
-- [ ] New or updated skills copied to project `skills/`
-- [ ] Dependencies updated (`bun update`)
-- [ ] `bun audit` passes (no new vulnerabilities)
-- [ ] `bun run devcheck` passes
+- [ ] Update applied (`bun update --latest`) — Mode A, or already done by user — Mode B
+- [ ] `changelog` skill invoked for each updated package
+- [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
+- [ ] Adoption opportunities identified and applied
+- [ ] Project `skills/` synced from package (Phase A), with a change report
+- [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
+- [ ] `bun run rebuild` succeeds
+- [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes
+- [ ] Numbered summary presented to user

package/skills/setup/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 ## Context
 
-This skill assumes `@cyanheads/mcp-ts-core init` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
+This skill assumes `npx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
 
 ## Agent Protocol File
 
@@ -91,7 +91,7 @@ mkdir -p .claude/skills && cp -R skills/* .claude/skills/
 
 **For other agents** (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., `.codex/skills/`, `.cursor/skills/`).
 
-After the initial copy, use the `maintenance` skill to keep them in sync after package updates.
+This step is the **bootstrap** — it creates the agent directory. From then on, use the `maintenance` skill to refresh it after package updates (Phase B). Maintenance only refreshes directories that already exist; it won't create a new agent directory on your behalf.
 
 ## Project Scaffolding
 

package/templates/AGENTS.md

@@ -14,8 +14,7 @@
 
 1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
 2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Check for Bun** — run `bun --version`. If [Bun](https://bun.sh) is available, it's the recommended runtime: update `package.json` scripts to use `bun` instead of `tsx` (e.g., `"devcheck": "bun scripts/devcheck.ts"`), prefer `bun run` over `npm run` for all commands, and update the Commands table and Checklist in this file to match.
-4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
@@ -25,13 +24,13 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
 8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+9. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -122,20 +121,26 @@ export const reviewCode = prompt('review_code', {
 
 ```ts
 // src/config/server-config.ts — lazy-parsed, separate from framework config
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+
 const ServerConfigSchema = z.object({
-  myApiKey: z.string().describe('External API key'),
+  apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
 });
+
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
 export function getServerConfig() {
-  _config ??= ServerConfigSchema.parse({
-    myApiKey: process.env.MY_API_KEY,
-    maxResults: process.env.MY_MAX_RESULTS,
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    apiKey: 'MY_API_KEY',
+    maxResults: 'MY_MAX_RESULTS',
   });
   return _config;
 }
 ```
 
+`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable (`MY_API_KEY`) rather than the internal path (`apiKey`). It throws a `ConfigurationError` the framework catches and prints as a clean startup banner.
+
 ---
 
 ## Context
@@ -215,7 +220,7 @@ src/
 
 Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, re-copy to pick up changes.
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
 
 Available skills:
 
@@ -232,7 +237,7 @@ Available skills:
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Sync skills and dependencies after updates |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -250,6 +255,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
+**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. Use whichever package manager you have; `bun` is slightly faster for invoking scripts but not required.
+
 | Command | Purpose |
 |:--------|:--------|
 | `npm run build` | Compile TypeScript |
@@ -281,7 +288,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
 - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage

package/templates/CLAUDE.md

@@ -14,8 +14,7 @@
 
 1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
 2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Check for Bun** — run `bun --version`. If [Bun](https://bun.sh) is available, it's the recommended runtime: update `package.json` scripts to use `bun` instead of `tsx` (e.g., `"devcheck": "bun scripts/devcheck.ts"`), prefer `bun run` over `npm run` for all commands, and update the Commands table and Checklist in this file to match.
-4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
@@ -31,7 +30,7 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
 8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+9. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -122,20 +121,26 @@ export const reviewCode = prompt('review_code', {
 
 ```ts
 // src/config/server-config.ts — lazy-parsed, separate from framework config
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+
 const ServerConfigSchema = z.object({
-  myApiKey: z.string().describe('External API key'),
+  apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
 });
+
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
 export function getServerConfig() {
-  _config ??= ServerConfigSchema.parse({
-    myApiKey: process.env.MY_API_KEY,
-    maxResults: process.env.MY_MAX_RESULTS,
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    apiKey: 'MY_API_KEY',
+    maxResults: 'MY_MAX_RESULTS',
   });
   return _config;
 }
 ```
 
+`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable (`MY_API_KEY`) rather than the internal path (`apiKey`). It throws a `ConfigurationError` the framework catches and prints as a clean startup banner.
+
 ---
 
 ## Context
@@ -215,7 +220,7 @@ src/
 
 Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, re-copy to pick up changes.
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
 
 Available skills:
 
@@ -232,7 +237,7 @@ Available skills:
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Sync skills and dependencies after updates |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -250,6 +255,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
+**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. Use whichever package manager you have; `bun` is slightly faster for invoking scripts but not required.
+
 | Command | Purpose |
 |:--------|:--------|
 | `npm run build` | Compile TypeScript |
@@ -281,7 +288,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
 - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage