@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/tools/tool-builder/index.d.ts

@@ -1,28 +1,5 @@
-/**
- * `tool-builder/index` — barrel re-export for the split
- * tool-definition system.
- *
- * Round-1.5: structural split of the former monolithic
- * `tool-builder.ts` (320 LoC). Cohesion is preserved by topic:
- *
- *   - `types.ts`        — pure type declarations (no runtime imports
- *                         beyond type-only `zod` + SDK notifications)
- *   - `annotations.ts`  — `readOnly` / `mutating` / `creating` /
- *                         `destructive` annotation builders
- *   - `results.ts`      — `jsonResult` / `errorResult` /
- *                         `structuredResult` / `confirmGuard` envelope
- *                         builders + the shared `sanitizeContentItem`
- *                         helper (single LLM-boundary mask)
- *   - `define.ts`       — `defineTool` identity helper + progress-
- *                         reporter re-export
- *
- * The parent file `../tool-builder.ts` re-exports this barrel so
- * existing `./tool-builder.js` imports keep working without churn.
- *
- * @license MIT
- */
-export type { AnyToolDefinition, HandlerExtra, ToolAnnotations, ToolContent, ToolDefinition, ToolHandler, ToolResult, } from './types.js';
-export { creating, destructive, mutating, readOnly, } from './annotations.js';
-export { confirmGuard, errorResult, jsonResult, structuredResult, withSiteMeta, } from './results.js';
+export type { AnyToolDefinition, HandlerExtra, ServedToolDefinition, ToolAnnotations, ToolContent, ToolDefinition, ToolHandler, ToolResult, } from './types.js';
+export { creating, destructive, destructiveIdempotent, mutating, readOnly, } from './annotations.js';
+export { confirmGuard, errorResult, jsonResult, rejectionOnBothLegs, structuredResult, withSiteMeta, } from './results.js';
 export { createProgressReporter, defineTool } from './define.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/tool-builder/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EACR,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACH,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAwBA,YAAY,EACR,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACH,QAAQ,EACR,WAAW,EACX,qBAAqB,EACrB,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/tools/tool-builder/index.js

@@ -1,27 +1,4 @@
-/**
- * `tool-builder/index` — barrel re-export for the split
- * tool-definition system.
- *
- * Round-1.5: structural split of the former monolithic
- * `tool-builder.ts` (320 LoC). Cohesion is preserved by topic:
- *
- *   - `types.ts`        — pure type declarations (no runtime imports
- *                         beyond type-only `zod` + SDK notifications)
- *   - `annotations.ts`  — `readOnly` / `mutating` / `creating` /
- *                         `destructive` annotation builders
- *   - `results.ts`      — `jsonResult` / `errorResult` /
- *                         `structuredResult` / `confirmGuard` envelope
- *                         builders + the shared `sanitizeContentItem`
- *                         helper (single LLM-boundary mask)
- *   - `define.ts`       — `defineTool` identity helper + progress-
- *                         reporter re-export
- *
- * The parent file `../tool-builder.ts` re-exports this barrel so
- * existing `./tool-builder.js` imports keep working without churn.
- *
- * @license MIT
- */
-export { creating, destructive, mutating, readOnly, } from './annotations.js';
-export { confirmGuard, errorResult, jsonResult, structuredResult, withSiteMeta, } from './results.js';
+export { creating, destructive, destructiveIdempotent, mutating, readOnly, } from './annotations.js';
+export { confirmGuard, errorResult, jsonResult, rejectionOnBothLegs, structuredResult, withSiteMeta, } from './results.js';
 export { createProgressReporter, defineTool } from './define.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/tool-builder/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EACH,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/index.ts"],"names":[],"mappings":"AAkCA,OAAO,EACH,QAAQ,EACR,WAAW,EACX,qBAAqB,EACrB,QAAQ,EACR,QAAQ,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/tools/tool-builder/results.d.ts

@@ -1,142 +1,22 @@
-/**
- * `tool-builder/results` — envelope builders (`jsonResult`,
- * `errorResult`, `structuredResult`, `confirmGuard`) + the shared
- * `sanitizeContentItem` helper. Every payload accepted here runs
- * through the `sanitizeSecrets` / `sanitizeForLogs` boundary so an
- * upstream regression can never land in the LLM context. The mask
- * is concentrated here — `define.ts` and call-sites do not re-mask.
- *
- * Split from `tool-builder.ts` in Round-1.5.
- *
- * @license MIT
- */
 import type { ResolvedSite } from '../../sites/registry.js';
 import type { ToolContent, ToolResult } from './types.js';
-/**
- * F80 (2026-06-10): the size at/above which a JSON-document text body is
- * split off into its own content block instead of carrying the in-band
- * `[label @ host] ` site-prefix.
- *
- * Why a threshold rather than "all JSON": a tool host (Claude Code, …)
- * spills only OVERSIZED tool results to a temp file. That file is read
- * back with `jq`, so the bytes must be pure JSON — an in-band prefix
- * corrupts the first line and breaks the parse (the observed F80
- * friction on `page_get_layout`, a multi-kB layout dump). Small JSON
- * envelopes (error results, single-element confirms, short lists) are
- * NEVER dumped, so they keep the in-band prefix — which preserves the
- * long-standing contract that `content[0].text` is the directly-parseable
- * JSON for those results (141 error-matrix / handler tests depend on it).
- *
- * 8 kB is comfortably below any host's spill threshold yet above every
- * small structured envelope this surface emits.
- */
 export declare const SITE_PREFIX_JSON_SPLIT_THRESHOLD: number;
-/**
- * Convert any JSON-serializable value into the MCP content envelope
- * (2-space JSON). Wave G.6.4b: every payload is deep-walked through
- * `sanitizeSecrets` before stringification so an upstream regression
- * (REST handler surfacing `oauth_refresh_token`, `auth_data`, etc.)
- * can never land in the LLM context.
- */
 export declare function jsonResult(payload: unknown, options?: {
     isError?: boolean;
 }): ToolResult;
-/**
- * Render a structured error result with `context` (echoed input) and a
- * recovery `hint`. Wave G.6.3 defense-in-depth: message is
- * mask-and-truncate'd; context is deep-walked so an input param that
- * accidentally echoed a secret-bearing value cannot leak.
- */
+export declare function rejectionOnBothLegs(payload: Record<string, unknown>): ToolResult;
+export declare const PASSTHROUGH_ERROR_KEYS: readonly ["element_path", "expected_etag", "error_code", "retry_after", "retry_after_ms", "retry_after_seconds", "limit", "window_seconds", "required_scope", "token_scope", "remediation", "min_client", "current_client"];
 export declare function errorResult(opts: {
     error: unknown;
     context: Record<string, unknown>;
     hint: string;
 }): ToolResult;
-/**
- * Confirm-guard preview helper for destructive tools. Returns the
- * preview `ToolResult` when `confirm` is false; callers `return` it
- * before executing the destructive REST call.
- *
- * F131 (Wave 4a): the blocked-state result is now STRUCTURALLY distinct
- * from a successful mutation. Previously the preview was a plain
- * `jsonResult` with no `isError` — envelope-identical to a success — so a
- * model that did not parse `preview:true` read "delete succeeded" and
- * silently left the element in place (the dry-run / silent-no-op footgun
- * class). Three redundant signals now make the block unmistakable:
- *   1. result-level `isError: true` (hosts that only read the error flag),
- *   2. body `applied: false` + `requires_confirmation: true` (structured
- *      consumers),
- *   3. a leading "NOT EXECUTED" line in the human-readable warning text
- *      (models that skim prose).
- */
 export declare function confirmGuard(opts: {
     operation: string;
     details: Record<string, unknown>;
+    structured: Record<string, unknown>;
+    structuredExtra?: Record<string, unknown>;
 }): ToolResult;
-/**
- * Merge a toolkit builder result (`tableResult` / `detailResult` /
- * `statsResult` / etc.) with a domain-typed `structuredContent` payload. The
- * result satisfies both Rich-Card hosts (read `_meta.ui`, present only when
- * the call site opted in) AND structured-output hosts (read
- * `structuredContent`, may validate against `outputSchema`). Single
- * envelope-merger from every migrated tool's handler — toolkit builders are
- * wrapped, not modified.
- *
- * T-C3c (native `@getimo/mcp-toolkit@1.2.0` migration): `includeMeta` is no
- * longer decided HERE. Every call site now threads it straight into its OWN
- * builder call (`tableResult(items, { ...opts, includeMeta })`, etc.), so the
- * toolkit either allocates the Rich-Card `_meta.ui` + embedded base64 marker
- * or never allocates them at all — nothing is stripped after the fact.
- * Replaces the T-C3 / T-C3b consumer-side shim (this file's own
- * `STRUCTURED_META_MARKER_RE` regex + `stripStructuredMetaItem`), which
- * duplicated the toolkit's marker format and risked drifting out of sync
- * with a future toolkit version. `toolkitResult._meta` is simply whatever
- * the builder decided to attach (or omit) — this function only sanitises and
- * merges it.
- */
-/**
- * W6.2 — site-awareness envelope wrapper.
- *
- * Stamps a resolved-site descriptor onto a tool result so the human +
- * agent both know which connected site the call ran against. Two
- * channels:
- *
- *   1. **text-prefix PRIMARY surface** — `[<label or site_id> @
- *      <hostname>] ` is injected at the start of `content[0].text`
- *      when that block is a text item. Per the W6 web-research
- *      addendum (HCFV §B, Claude-Desktop UI gap doc'd in plan
- *      Z.1329-1332), `_meta` is read by the agent but NOT rendered as
- *      a UI widget today — so the prefix is the only thing Maria the
- *      Claude-Desktop-user reliably SEES. LOAD-BEARING.
- *
- *   2. **result-level `_meta` SECONDARY surface** — `_meta:
- *      {site_id, site_url, platform}` is merged into the RESULT-level
- *      `_meta` (alongside the toolkit's `_meta.ui`). This is the
- *      MCP-spec metadata channel: free-form and NOT validated against
- *      the tool's `outputSchema`.
- *
- *      W12-R2 fix: site meta was previously merged into
- *      `structuredContent._meta`. That broke real hosts. Every tool's
- *      `outputSchema` is generated with `additionalProperties:false`,
- *      so an undeclared `_meta` key inside `structuredContent` fails
- *      client-side schema validation (`-32602`) and surfaces as a
- *      "Failed to call tool" toast in Claude Desktop EVEN ON A
- *      SUCCESSFUL CALL. `live-verify.mjs` never caught it because raw
- *      JSON-RPC calls skip the host's structuredContent↔outputSchema
- *      validation. `structuredContent` must stay schema-pure.
- *
- * Pure function: never mutates the input result. Non-text blocks
- * (resource / image / etc.) pass through verbatim. `structuredContent`
- * is passed through UNTOUCHED so it always validates against
- * `outputSchema`. Empty `content[]` is tolerated and produces a
- * prefix-free result (the meta still lands in result-level `_meta`).
- *
- * Label-fallback: `site.label` wins; falls back to `site.id`.
- *
- * Hostname extraction defaults to `new URL(site.url).host`. A
- * malformed URL falls back to the raw site.url string so the prefix
- * remains user-readable even when the registry was hand-edited.
- */
 export declare function withSiteMeta<R extends ToolResult>(result: R, site: ResolvedSite): R;
 export declare function structuredResult(toolkitResult: {
     content: ToolContent[];

package/dist/tools/tool-builder/results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gCAAgC,QAAW,CAAC;AA2BzD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAsLD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CA8Bb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,UAAU,CAab;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CA6FH;AAED,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,EACD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,UAAU,CAiBZ"}
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA4B1D,eAAO,MAAM,gCAAgC,QAAW,CAAC;AAkCzD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAmCD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAShF;AAsiBD,eAAO,MAAM,sBAAsB,6NAqCzB,CAAC;AAwEX,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CA+Eb;AAmDD,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,GAAG,UAAU,CAyBb;AAuFD,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CAyJH;AAED,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,EACD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,UAAU,CAiBZ"}