@cyanheads/mcp-ts-core 0.9.17 → 0.9.19

package/dist/utils/network/retry.js

@@ -34,9 +34,22 @@ function computeDelay(attempt, baseDelayMs, maxDelayMs, jitter) {
 /**
  * Default transient check: `McpError` with a transient code, or any non-McpError
  * (network failures, unexpected throws) which are assumed transient.
+ *
+ * **Per-error opt-out.** When a thrown `McpError` carries `data.retryable === false`,
+ * the error is treated as non-transient and fails fast — even if its code is in
+ * `TRANSIENT_CODES`. This is the in-band escape hatch for deterministic upstream
+ * failures (e.g. a query too expensive to ever succeed surfaced as HTTP 200 +
+ * error body) that arrive with a transient code but should never be retried.
+ *
+ * Absent the flag (or when it is `true`), behavior is unchanged — code-based
+ * classification applies. Non-`McpError` throws (raw network errors, unexpected
+ * throws) are always assumed transient regardless of the flag.
  */
 function defaultIsTransient(error) {
     if (error instanceof McpError) {
+        // Explicit opt-out wins over code-based classification.
+        if (error.data?.retryable === false)
+            return false;
         return TRANSIENT_CODES.has(error.code);
     }
     // Non-McpError (raw network errors, unexpected throws) — assume transient
@@ -72,6 +85,13 @@ function enrichExhaustedError(error, totalAttempts, operation) {
  * parsing, and validation — not just the network call. This ensures that
  * transient upstream errors (e.g., HTTP 200 with an error body) are retried.
  *
+ * **Deterministic-failure opt-out.** When the thrown `McpError` carries
+ * `data.retryable === false`, the default predicate treats it as non-transient
+ * and fails immediately — even for `Timeout`/`ServiceUnavailable`/`RateLimited`
+ * codes. Use this at the throw site (or let the error contract auto-populate it
+ * via `ctx.fail`) for failures that can never succeed on retry (oversized query,
+ * malformed request surfaced as HTTP 200 + error body, etc.).
+ *
  * When retries exhaust, the final error is enriched with attempt count in both
  * the message and structured data, so callers know retries were already attempted.
  *

package/dist/utils/network/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"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"}

package/dist/utils/pagination/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAc3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA6BrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,eAAe,CAAC,CAAC,CAAC,CAmCpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC,uCAAuC;;IAEvC,qCAAqC;;IAErC,qCAAqC;;CAE7B,CAAC"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IAEjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAc3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA6BrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,eAAe,CAAC,CAAC,CAAC,CAmCpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC,uCAAuC;;IAEvC,qCAAqC;;IAErC,qCAAqC;;CAE7B,CAAC"}

package/dist/utils/pagination/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.9.17",
+  "version": "0.9.19",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -12,12 +12,14 @@
     "scripts/build.ts",
     "scripts/check-docs-sync.ts",
     "scripts/check-framework-antipatterns.ts",
+    "scripts/check-skill-versions.ts",
     "scripts/check-skills-sync.ts",
     "scripts/clean.ts",
     "scripts/devcheck.ts",
     "scripts/lint-mcp.ts",
     "scripts/lint-packaging.ts",
     "scripts/list-skills.ts",
+    "scripts/release-github.ts",
     "scripts/tree.ts",
     "skills/",
     "templates/",
@@ -160,6 +162,7 @@
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
     "changelog:build": "bun run scripts/build-changelog.ts",
     "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "release:github": "bun run scripts/release-github.ts",
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
   },
   "resolutions": {

package/scripts/check-skill-versions.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Enforces the skill-versioning policy (#98 → #99): a change to a
+ * `skills/<name>/SKILL.md` body must bump `metadata.version` in the same edit.
+ * Documenting the policy made the expectation visible; this check makes it stick.
+ * The triggering incident was 7 missed bumps across 2 consecutive releases — the
+ * kind of low-salience checklist item that needs tooling, not vigilance.
+ *
+ * For each `skills/<name>/SKILL.md` that differs from `HEAD` (working tree, staged
+ * or not), it compares the frontmatter `metadata.version` and the body across
+ * `HEAD` → working tree. A changed body with an unchanged version is a violation.
+ * Whitespace-only body edits never trigger it (the policy's typo/whitespace
+ * carve-out); a genuine typo fix opts out via `devcheck.config.json`:
+ *
+ *   {
+ *     "skillVersions": {
+ *       "ignore": ["add-tool", "api-linter/SKILL.md"]
+ *     }
+ *   }
+ *
+ * A bare name (`add-tool`) and the file path (`add-tool/SKILL.md`) both match.
+ *
+ * Diffing against `HEAD` keeps the per-release-cycle carve-out automatic: once the
+ * version line is bumped, later commits in the same cycle no longer re-trigger.
+ * Severity mirrors `check-skills-sync.ts` — exits 1, demoted to a warning by
+ * devcheck. New skills (no `HEAD` version) and non-git trees are skipped.
+ *
+ * Runs standalone (`bun run scripts/check-skill-versions.ts`) and as a devcheck step.
+ *
+ * @module scripts/check-skill-versions
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+const ROOT = resolve('.');
+const SKILL_MD_RE = /^skills\/[^/]+\/SKILL\.md$/;
+
+interface DevcheckConfig {
+  skillVersions?: { ignore?: string[] };
+}
+
+function loadIgnorePatterns(): string[] {
+  try {
+    const cfg = JSON.parse(
+      readFileSync(resolve(ROOT, 'devcheck.config.json'), 'utf-8'),
+    ) as DevcheckConfig;
+    return cfg.skillVersions?.ignore ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Match check-skills-sync semantics: full `<name>/SKILL.md` path or the bare `<name>`. */
+function isIgnored(relPath: string, patterns: string[]): boolean {
+  const name = relPath.split('/')[1]; // skills/<name>/SKILL.md → <name>
+  return patterns.some(
+    (p) => p === relPath || p === name || (name !== undefined && p === `${name}/SKILL.md`),
+  );
+}
+
+/** Skill `SKILL.md` files that differ from `HEAD` (staged + unstaged). */
+function changedSkillFiles(): string[] {
+  const result = spawnSync('git', ['diff', '--name-only', 'HEAD', '--'], { encoding: 'utf-8' });
+  if (result.status !== 0) return []; // not a git repo / no HEAD commit
+  return result.stdout
+    .trim()
+    .split('\n')
+    .filter((p) => SKILL_MD_RE.test(p));
+}
+
+/** Content of a path at `HEAD`, or null when it didn't exist there (new file). */
+function headContent(relPath: string): string | null {
+  const result = spawnSync('git', ['show', `HEAD:${relPath}`], { encoding: 'utf-8' });
+  return result.status === 0 ? result.stdout : null;
+}
+
+/** `metadata.version` from skill frontmatter, or null when absent/unparseable. */
+function extractVersion(content: string): string | null {
+  const block = content.match(/^---\n([\s\S]*?)\n---/)?.[1];
+  if (!block) return null;
+  const version = block.match(/^\s*version:\s*["']?([^"'\n]+?)["']?\s*$/m)?.[1];
+  return version?.trim() ?? null;
+}
+
+/** Body = everything after the frontmatter block. */
+function extractBody(content: string): string {
+  const fm = content.match(/^---\n[\s\S]*?\n---/)?.[0];
+  return fm ? content.slice(fm.length) : content;
+}
+
+/** Whitespace-insensitive comparison (`git diff -w` style). */
+function bodiesDiffer(a: string, b: string): boolean {
+  return a.replace(/\s+/g, '') !== b.replace(/\s+/g, '');
+}
+
+if (!existsSync(resolve(ROOT, 'skills'))) {
+  console.log('Skipped: no skills/ directory.');
+  process.exit(0);
+}
+
+const ignore = loadIgnorePatterns();
+const changed = changedSkillFiles().filter((f) => !isIgnored(f, ignore));
+
+const violations: { file: string; version: string }[] = [];
+for (const file of changed) {
+  const oldContent = headContent(file);
+  if (oldContent === null) continue; // new skill — no prior version to compare
+  const newContent = readFileSync(resolve(ROOT, file), 'utf-8');
+
+  if (!bodiesDiffer(extractBody(oldContent), extractBody(newContent))) continue; // whitespace-only
+
+  const oldVersion = extractVersion(oldContent);
+  const newVersion = extractVersion(newContent);
+  if (oldVersion !== null && oldVersion === newVersion) {
+    violations.push({ file, version: oldVersion });
+  }
+}
+
+if (violations.length === 0) {
+  console.log('Skill versions are in step with body changes.');
+  process.exit(0);
+}
+
+const lines = [
+  `${violations.length} skill${violations.length === 1 ? '' : 's'} changed body without a metadata.version bump:`,
+  '',
+];
+for (const v of violations) {
+  lines.push(`  - ${v.file} body changed but metadata.version is still "${v.version}"`);
+}
+lines.push('');
+lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
+lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+console.log(lines.join('\n'));
+process.exit(1);

package/scripts/devcheck.ts

@@ -242,6 +242,9 @@ interface DevcheckConfig {
   skillsSync?: {
     ignore?: string[];
   };
+  skillVersions?: {
+    ignore?: string[];
+  };
 }
 
 function loadDevcheckConfig(rootDir: string): DevcheckConfig {
@@ -438,6 +441,21 @@ const ALL_CHECKS: Check[] = [
     tip: (c) =>
       `Remove the flagged SDK-coupling shortcut. See ${c.bold('scripts/check-framework-antipatterns.ts')} for rule rationale.`,
   },
+  {
+    name: 'Open-Indexed Interfaces',
+    flag: '--no-open-index',
+    canFix: false,
+    // Framework-only AST check (#123): flags interfaces mixing named members with an
+    // open `[key: string]: unknown|any` index signature that lack an opt-out comment.
+    // Not shipped in package.json `files:`, so the existence guard skips it cleanly in
+    // consumer projects — the pattern is common and legitimate in consumer code.
+    getCommand: () => {
+      if (!existsSync(path.join(ROOT_DIR, 'scripts/audit-open-index-signatures.ts'))) return null;
+      return ['bun', 'run', 'scripts/audit-open-index-signatures.ts'];
+    },
+    tip: (c) =>
+      `Add ${c.bold('// allow open-indexed-named: <rationale>')} above the index signature, or use explicit fields. See ${c.bold('scripts/audit-open-index-signatures.ts')}.`,
+  },
   {
     name: 'Docs Sync',
     flag: '--no-docs-sync',
@@ -470,6 +488,27 @@ const ALL_CHECKS: Check[] = [
     tip: (c) =>
       `Propagate ${c.bold('skills/')} to ${c.bold('.agents/skills/')} and ${c.bold('.claude/skills/')}, or add entries to ${c.bold('devcheck.config.json')} ${c.bold('skillsSync.ignore')}.`,
   },
+  {
+    name: 'Skill Versions',
+    flag: '--no-skill-versions',
+    canFix: false,
+    // Flags skills/<name>/SKILL.md body changes (vs HEAD) that lack a metadata.version
+    // bump (#99). Skipped when skills/ is absent. Drift is demoted to a warning via
+    // isSuccess — the typo/whitespace carve-out lives in devcheck.config.json
+    // `skillVersions.ignore`.
+    getCommand: () => {
+      if (!existsSync(path.join(ROOT_DIR, 'skills'))) return null;
+      return ['bun', 'run', 'scripts/check-skill-versions.ts'];
+    },
+    isSuccess: (result) => {
+      if (result.exitCode === 0) return true;
+      const firstLine =
+        result.stdout.split('\n')[0]?.trim() || 'Skill bodies changed without a version bump.';
+      return { success: true, warning: firstLine };
+    },
+    tip: (c) =>
+      `Bump ${c.bold('metadata.version')} in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
+  },
   {
     name: 'Changelog Sync',
     flag: '--no-changelog-sync',

package/scripts/release-github.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Create (or repair) a GitHub Release on the current package version's
+ * annotated tag, enforcing the `v<VERSION>: <tag subject>` title format that
+ * `--notes-from-tag` alone cannot set.
+ *
+ * What it does:
+ *   1. Reads `version` from `package.json`.
+ *   2. Derives the tag subject via `git for-each-ref refs/tags/v<version>`.
+ *   3. Runs `gh release create v<version> --verify-tag --notes-from-tag
+ *         --title "v<version>: <subject>"` plus `dist/*.mcpb` when
+ *      `manifest.json` exists (MCPB bundle attach).
+ *   4. On "release already exists" (re-invocation after partial run):
+ *      - If `manifest.json` exists: `gh release upload v<version> --clobber dist/*.mcpb`
+ *        to attach/replace the asset, then `gh release edit` to set the title.
+ *      - Otherwise: `gh release edit` to set the title on the existing release.
+ *
+ * The framework itself has no `manifest.json`/`.mcpb`, so the attach path is
+ * skipped here but scaffolded servers that do have a manifest get the full flow.
+ *
+ * @module scripts/release-github
+ *
+ * @example
+ * // Create a GitHub Release for the current package version:
+ * // bun run release:github
+ *
+ * @example
+ * // Dry-run — print the command that would be executed without running it:
+ * // bun run release:github -- --dry-run
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Run a command synchronously and return its trimmed stdout.
+ * Exits the process on non-zero exit when `required` is true.
+ */
+function run(
+  cmd: string,
+  args: string[],
+  options: { required?: boolean; capture?: boolean } = {},
+): string {
+  const { required = true, capture = true } = options;
+  const result = spawnSync(cmd, args, {
+    encoding: 'utf-8',
+    stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'pipe'],
+  });
+  const stdout = (result.stdout ?? '').trim();
+  const stderr = (result.stderr ?? '').trim();
+
+  if (result.error) {
+    console.error(`Failed to spawn '${cmd}': ${result.error.message}`);
+    if (required) process.exit(1);
+    return '';
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    if (required) {
+      console.error(`Command failed: ${cmd} ${args.join(' ')}`);
+      if (stderr) console.error(stderr);
+      process.exit(1);
+    }
+    // Return stderr concatenated so callers can inspect the failure reason.
+    return `__ERROR__:${stderr}`;
+  }
+
+  return stdout;
+}
+
+/**
+ * Run a `gh` CLI command.
+ * On "release already exists" the return value starts with `__ERROR__:`.
+ */
+function gh(args: string[], options: { required?: boolean } = {}): string {
+  return run('gh', args, { required: options.required ?? true, capture: true });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+function main(): void {
+  // 1. Read version from package.json
+  const pkgPath = resolve('package.json');
+  if (!existsSync(pkgPath)) {
+    console.error('package.json not found in current directory. Run from the project root.');
+    process.exit(1);
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
+  const version = pkg.version?.trim();
+  if (!version) {
+    console.error('package.json has no version field.');
+    process.exit(1);
+  }
+
+  const tag = `v${version}`;
+
+  // 2. Derive tag subject via git for-each-ref
+  const subject = run('git', ['for-each-ref', `refs/tags/${tag}`, '--format=%(contents:subject)']);
+
+  if (!subject) {
+    console.error(
+      `Tag ${tag} not found locally or has no subject line. ` +
+        `Create the annotated tag first: git tag -a ${tag} -m "..."`,
+    );
+    process.exit(1);
+  }
+
+  const title = `${tag}: ${subject}`;
+  const hasMcpb = existsSync('manifest.json');
+
+  // 3. Build the gh release create command
+  const createArgs = [
+    'release',
+    'create',
+    tag,
+    '--verify-tag',
+    '--notes-from-tag',
+    '--title',
+    title,
+  ];
+  if (hasMcpb) {
+    createArgs.push('dist/*.mcpb');
+  }
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] gh ${createArgs.join(' ')}`);
+    if (hasMcpb) {
+      console.log(
+        `[dry-run] fallback (if release exists): gh release upload ${tag} dist/*.mcpb --clobber`,
+      );
+      console.log(
+        `[dry-run] fallback (if release exists): gh release edit ${tag} --title "${title}"`,
+      );
+    } else {
+      console.log(
+        `[dry-run] fallback (if release exists): gh release edit ${tag} --title "${title}"`,
+      );
+    }
+    return;
+  }
+
+  console.log(`Creating GitHub Release ${tag}…`);
+  console.log(`  title: ${title}`);
+  if (hasMcpb) {
+    console.log('  asset: dist/*.mcpb');
+  }
+
+  // 4. Try to create the release
+  const createResult = gh(createArgs, { required: false });
+
+  if (!createResult.startsWith('__ERROR__:')) {
+    // Success — print the release URL returned by gh
+    if (createResult) console.log(createResult);
+    console.log(`Release ${tag} created.`);
+    return;
+  }
+
+  const errText = createResult.slice('__ERROR__:'.length);
+  const alreadyExists = /release already exists/i.test(errText);
+
+  if (!alreadyExists) {
+    console.error(`gh release create failed:\n${errText}`);
+    process.exit(1);
+  }
+
+  // 5. Release already exists — repair: upload asset (if applicable) and set title.
+  console.log(`Release ${tag} already exists. Repairing…`);
+
+  if (hasMcpb) {
+    console.log('  uploading dist/*.mcpb (--clobber)…');
+    gh(['release', 'upload', tag, 'dist/*.mcpb', '--clobber']);
+  }
+
+  console.log(`  setting title: ${title}`);
+  gh(['release', 'edit', tag, '--title', title]);
+
+  console.log(`Release ${tag} repaired.`);
+}
+
+main();

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -131,7 +131,7 @@ async fetchItem(id: string, ctx: Context): Promise<Item> {
 
 1. **Calibrate backoff to the upstream.** 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default `baseDelayMs: 1000` suits most APIs.
 2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws on non-OK responses with granular status mapping (401→`Unauthorized`, 403→`Forbidden`, 404→`NotFound`, 408/425→`Timeout`, 422→`ValidationError`, 429→`RateLimited`, 5xx→`ServiceUnavailable`/`InternalError`) — this prevents feeding HTML error pages into XML/JSON parsers.
-3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
+3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient). **Exception — deterministic HTTP 200 errors fail fast, not transient.** Some upstreams return HTTP 200 with a structured error body for failures that will *never* succeed regardless of how many times you retry: a query too expensive for the server's budget, an oversized result set, or a malformed request the server rejects. Retrying these wastes upstream capacity and delays the client. Declare them in the contract with `retryable: false` (or pass `{ retryable: false }` in `data` at the throw site) — `withRetry`'s default predicate reads `error.data.retryable === false` and fails immediately, even for `Timeout`/`ServiceUnavailable` codes. `ctx.fail` auto-populates `data.retryable` from the contract entry, so declaring it once in `errors[]` is enough.
 4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
 
 ### When you need finer-grained HTTP error classification

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.14"
+  version: "2.15"
   audience: external
   type: workflow
 ---
@@ -350,6 +350,7 @@ output: z.object({
 
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
 - **Spill big tabular results to a queryable surface.** When a tool's row set can exceed any reasonable context budget — paginated APIs, streamed exports, big query results — pair an inline preview with a `DataCanvas` table holding the full set, returned as a token the agent can SQL. Compute distributions or refinement hints across the full result, not the preview, so aggregate signal stays honest. See `api-canvas` for the `spillover()` helper.
+- **Mirror a bulk upstream instead of paginating it live.** When the server wraps a large or slow API whose corpus is queried far more than it changes, sync it once into a persistent local index and query that as the primary data path — not the live API per request. Match the backend to corpus size: ≲ tens of thousands of rows → an in-memory index (server-level, no primitive); ~10⁴–10⁷ → the `MirrorService` (embedded SQLite + FTS5; declare a schema + a `sync` ingester via `defineMirror`/`sqliteMirrorStore`, then `runSync`/`query`, see `api-mirror`); ≳ 10⁸ → an external store. Distinct lifecycle from DataCanvas: a mirror is long-lived and cross-session, refreshed on a schedule; canvas is ephemeral and per-session.
 - **`format()` is the markdown twin of `structuredContent` — make both content-complete.** Different MCP clients forward different surfaces to the model: some (e.g., Claude Code) read `structuredContent` from `output`, others (e.g., Claude Desktop) read `content[]` from `format()`. Both must carry the same data so every client sees the same picture — `format()` just dresses it up with markdown. A thin `format()` that returns only a count or title leaves `content[]`-only clients blind to data that `structuredContent` clients can see. Render all fields the LLM needs, with structured markdown (headers, bold labels, lists) for readability.
 - **Agent-facing context must reach both client surfaces — put it in `enrichment`.** `structuredContent` (from `output`) and `content[]` (from `format()`) are read by different clients. Empty-result notices, the query/filter as the server parsed it, and pagination totals — the context the agent *reasons with*, distinct from the domain payload — reach only `content[]` if hand-authored into `format()` text alone, leaving `structuredContent`-only clients (Claude Code) blind. (The reverse can't happen: `format-parity` drags every `output` field into `format()`, so `output`-authored context already reaches both.) An `enrichment` block — the success-path counterpart to `errors[]`, populated via `ctx.enrich(...)` — reaches both automatically: merged into `structuredContent`, advertised as `output.extend(enrichment)`, mirrored into a `content[]` trailer, no `format()` entry needed. How each field renders in that trailer is a per-tool call — a kind-tag (`notice`/`total`/`echo`/`delta`) when a canonical form fits, a domain key like `totalFound` otherwise, and an `enrichmentTrailer.render` for any structured (object/array) field so it doesn't ship as a JSON blob. See `add-tool`'s **Tool Response Design**.
 

package/skills/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: internal
   type: workflow
 ---
@@ -157,7 +157,7 @@ For N targets in a phase:
 3. Collect their reports
 4. Verify with a read-only orchestrator check before advancing to the next phase
 
-**Barriers only where gates sit.** Step 4's "advance to the next phase" implies a barrier — collect every target's phase-N result before any target starts phase N+1. That barrier is only required when a gate sits between the phases: a human decision (authorization, version-bump intent) or cross-target synthesis (the roll-up). Where no gate intervenes, a target may flow through consecutive phases independently — tier-3 platforms pipeline this for wall-clock, and even hand-spawned runs can let one sub-agent carry a target across adjacent gate-free phases. Keep the barrier at gate boundaries; drop it elsewhere.
+**Barriers only where gates sit.** Step 4's "advance to the next phase" implies a barrier — collect every target's phase-N result before any target starts phase N+1. That barrier is only required when a gate sits between the phases: a human decision (authorization, version-bump intent) or cross-target synthesis (the roll-up). Where no gate intervenes, a target may flow through consecutive phases independently — tier-3 platforms pipeline this for wall-clock, and even hand-spawned runs can let one sub-agent carry a target across adjacent gate-free phases. Keep the barrier at gate boundaries; drop it elsewhere. Each workflow's phases table encodes this directly: the `Gate after` column marks every boundary as `barrier` (with a terse reason) or `gate-free` so the spawn/round structure is derivable without re-derivation.
 
 ### Editor / wrap-up separation
 

package/skills/orchestrations/workflows/field-test-fix.md

@@ -49,15 +49,15 @@ Per target:
 
 Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce.
 
-| # | Phase | Objective | Sub-agent mode |
-|:--|:---|:---|:---|
-| 1 | Field-test | Per target: live tool/resource/prompt surface exercised across happy/error/edge paths; valid findings filed as GH issues against the server's own repo; noise filtered | parallel fanout per target; within a target, 1 or 3 sub-agents (see below) |
-| 2 | Issue triage | Per-target GH issue count + severity breakdown reconciled against actual GH state | orchestrator (serial) |
-| 3 | Fix | Per target: priority issues fixed in source, tests updated, `devcheck` + `test` green, each issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) |
-| 4 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout |
-| 5 | Loop decision | Orchestrator decision recorded — proceed to release, loop another field-test cycle, or pause/surface to user. Evidence-based | orchestrator (serial) |
-| 6 | Wrap-up + release | (Optional) Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) |
-| 7 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment; skipped issues remain open | orchestrator (serial) |
+| # | Phase | Objective | Sub-agent mode | Gate after |
+|:--|:---|:---|:---|:---|
+| 1 | Field-test | Per target: live tool/resource/prompt surface exercised across happy/error/edge paths; valid findings filed as GH issues against the server's own repo; noise filtered | parallel fanout per target; within a target, 1 or 3 sub-agents (see below) | **barrier** — cross-target synthesis: orchestrator reconciles all findings before filing triage |
+| 2 | Issue triage | Per-target GH issue count + severity breakdown reconciled against actual GH state | orchestrator (serial) | gate-free |
+| 3 | Fix | Per target: priority issues fixed in source, tests updated, `devcheck` + `test` green, each issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) | gate-free |
+| 4 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout | **barrier** — orchestrator loop decision (human/evidence-based: proceed, loop, or surface to user) |
+| 5 | Loop decision | Orchestrator decision recorded — proceed to release, loop another field-test cycle, or pause/surface to user. Evidence-based | orchestrator (serial) | **barrier** — release authorization required before advancing |
+| 6 | Wrap-up + release | (Optional) Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) | gate-free |
+| 7 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment; skipped issues remain open | orchestrator (serial) | — |
 
 Phase 6 is optional — stop earlier if release isn't authorized. Phase 7 only runs if Phase 6 ran.
 

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -57,13 +57,13 @@ Per target:
 
 Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce.
 
-| # | Phase | Objective | Sub-agent mode |
-|:--|:---|:---|:---|
-| 1a | Validate (conditional) | Each handoff finding field-tested live; valid ones filed as GH issues; invalidated ones reported back with reason. If zero validate, workflow stops | one sub-agent per target |
-| 1b | Fix | Per target: targeted issues fixed in source, tests updated/added, `devcheck` + `rebuild` + `test` green, each fixed issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) |
-| 2 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout |
-| 3 | Wrap-up + release | Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) |
-| 4 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment | orchestrator (serial) |
+| # | Phase | Objective | Sub-agent mode | Gate after |
+|:--|:---|:---|:---|:---|
+| 1a | Validate (conditional) | Each handoff finding field-tested live; valid ones filed as GH issues; invalidated ones reported back with reason. If zero validate, workflow stops | one sub-agent per target | **barrier** — cross-target synthesis: orchestrator confirms validated findings before fix proceeds (or stops workflow if zero validate) |
+| 1b | Fix | Per target: targeted issues fixed in source, tests updated/added, `devcheck` + `rebuild` + `test` green, each fixed issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) | **barrier** — orchestrator reviews diffs before verify (explicit gate in checklist) |
+| 2 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout | **barrier** — orchestrator reviews simplified diff and verified outputs; release authorization required |
+| 3 | Wrap-up + release | Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) | gate-free |
+| 4 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment | orchestrator (serial) | — |
 
 Phase 1a is conditional — only runs when the input is a handoff document or otherwise unvalidated. When the input is already tracked GH issues, skip directly to Phase 1b. The release portion of Phase 3 is conditional on user authorization to ship.