@wootsup/yt-builder-mcp 0.2.0-alpha.2

package/dist/tools/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/tools/sources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tools/sources.js

@@ -0,0 +1,14 @@
+/**
+ * Backwards-compatible re-export shim.
+ *
+ * Wave G.4.0b split the original 228-LoC `sources.ts` into
+ * `./sources/{index, handlers, builders}.ts` after Wave G.4.2/G.4.3
+ * added elicitation + ambiguity-resolution logic that pushed it well
+ * over the 200-LoC budget. This shim keeps the legacy import path
+ * (`from '../tools/sources.js'`) working for downstream callers and
+ * tests. New code should import from `./sources/index.js` directly.
+ *
+ * @license MIT
+ */
+export { buildSourcesTools } from './sources/index.js';
+//# sourceMappingURL=sources.js.map

package/dist/tools/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../src/tools/sources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tools/sparse-fields.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Sparse-fields helper — projects per-item field whitelists onto tool
+ * responses and exposes per-tool default-sets that the AI client can rely
+ * on when calling read tools without a `fields` parameter.
+ *
+ * Design references:
+ *
+ *   - §3.5 Sparse-Fields Adaption: 4 read tools opt-in to `fields[]`;
+ *     the toolkit's `pickFields` is used directly; `projected_fields` is
+ *     echoed in the result envelope so the LLM can confirm exactly which
+ *     keys were kept.
+ *   - §4.4.1 — when used together with `flat: true` projection runs
+ *     AFTER the depth-first walk so paths are stable before narrowing.
+ *
+ * Reference implementation pattern: `connections.ts:721, 779-792, 810`
+ * in `@wootsup/apimapper-mcp`.
+ *
+ * The defaults are pure constants so they can be imported, exported, and
+ * asserted against in tests without any side-effects.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+/**
+ * Optional whitelist of fields. Per Design §3.5 the cap is 40 to stop
+ * runaway prompts from blowing up the request size; nested paths
+ * (`props.title`) are supported by the toolkit's `pickFields`.
+ */
+export declare const FIELDS: z.ZodOptional<z.ZodArray<z.ZodString>>;
+/**
+ * Flag enabling client-side flattening on `page_get_layout`. When true
+ * the response shape switches from `{layout, etag}` to
+ * `{elements: [...], etag}` and `fields[]` projection becomes meaningful.
+ */
+export declare const FLAT: z.ZodDefault<z.ZodBoolean>;
+/**
+ * Default fields echoed when the caller omits `fields`. Following the
+ * apimapper-mcp convention these are **echo-only** — projection itself
+ * is skipped (default-all preserved) but `projected_fields` still
+ * surfaces the implicit compact set so the AI can plan future requests.
+ */
+export declare const DEFAULT_FIELDS_PAGES_LIST: readonly string[];
+export declare const DEFAULT_FIELDS_ELEMENT_LIST: readonly string[];
+export declare const DEFAULT_FIELDS_SCHEMA: readonly string[];
+export declare const DEFAULT_FIELDS_SOURCES_LIST: readonly string[];
+export declare const DEFAULT_FIELDS_TYPES_LIST: readonly string[];
+/**
+ * element_get defaults to "all" because the AI often needs the full
+ * props payload for follow-up edits; sparse projection here is opt-in
+ * with nested-path support.
+ */
+export declare const DEFAULT_FIELDS_ELEMENT_GET: readonly string[] | undefined;
+/**
+ * Project an array of items to the requested fields. Returns items
+ * unchanged when `fields` is undefined (default-all). Skips non-object
+ * entries without crashing (they pass through as-is).
+ *
+ * @param items - The items to project.
+ * @param fields - The whitelist; `undefined` skips projection.
+ * @param _defaults - Per-tool default set, accepted for interface symmetry
+ *   with `projectedFieldsEcho` (unused for actual projection — default-all
+ *   semantics matches the apimapper-mcp reference, see `connections.ts:789`).
+ */
+export declare function projectFields<T extends Record<string, unknown>>(items: readonly T[], fields: readonly string[] | undefined, _defaults: readonly string[]): T[];
+/**
+ * Project a single object via the same `pickFields` rules. Returns the
+ * object unchanged when `fields` is undefined.
+ */
+export declare function projectFieldsSingle<T extends Record<string, unknown>>(obj: T, fields: readonly string[] | undefined, _defaults: readonly string[] | undefined): T;
+/**
+ * Compute the `projected_fields` echo. Returns the caller-requested
+ * fields when provided; otherwise returns the per-tool default set so
+ * the AI client knows exactly which compact view it implicitly opted into.
+ *
+ * @returns `undefined` only when neither `requested` nor `defaults` was set
+ *   (e.g. `element_get` with no opt-in) — callers should omit
+ *   `projected_fields` from the structuredContent in that case.
+ */
+export declare function projectedFieldsEcho(requested: readonly string[] | undefined, defaults: readonly string[] | undefined): readonly string[] | undefined;
+//# sourceMappingURL=sparse-fields.d.ts.map

package/dist/tools/sparse-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-fields.d.ts","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,MAAM,wCASd,CAAC;AAEN;;;;GAIG;AACH,eAAO,MAAM,IAAI,4BAMZ,CAAC;AAIN;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAMtD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAIxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAIlD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAKxD,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAKtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAE,GAAG,SAAqB,CAAC;AAInF;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC7B,CAAC,EAAE,CAWL;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,CAAC,CAQH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,SAAS,MAAM,EAAE,GAAG,SAAS,CAI/B"}

package/dist/tools/sparse-fields.js

@@ -0,0 +1,144 @@
+/**
+ * Sparse-fields helper — projects per-item field whitelists onto tool
+ * responses and exposes per-tool default-sets that the AI client can rely
+ * on when calling read tools without a `fields` parameter.
+ *
+ * Design references:
+ *
+ *   - §3.5 Sparse-Fields Adaption: 4 read tools opt-in to `fields[]`;
+ *     the toolkit's `pickFields` is used directly; `projected_fields` is
+ *     echoed in the result envelope so the LLM can confirm exactly which
+ *     keys were kept.
+ *   - §4.4.1 — when used together with `flat: true` projection runs
+ *     AFTER the depth-first walk so paths are stable before narrowing.
+ *
+ * Reference implementation pattern: `connections.ts:721, 779-792, 810`
+ * in `@wootsup/apimapper-mcp`.
+ *
+ * The defaults are pure constants so they can be imported, exported, and
+ * asserted against in tests without any side-effects.
+ *
+ * @license MIT
+ */
+import { pickFields } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+// ─── Schema ──────────────────────────────────────────────────────────
+/**
+ * Optional whitelist of fields. Per Design §3.5 the cap is 40 to stop
+ * runaway prompts from blowing up the request size; nested paths
+ * (`props.title`) are supported by the toolkit's `pickFields`.
+ */
+export const FIELDS = z
+    .array(z.string().min(1))
+    .max(40)
+    .optional()
+    .describe('Optional whitelist of fields to keep per item (supports nested paths like ' +
+    '"props.title"). Default: tool-specific compact set (echoed in projected_fields). ' +
+    'Cuts response size — e.g. fields:["path","element_type","label"] for a minimal ' +
+    'navigation view.');
+/**
+ * Flag enabling client-side flattening on `page_get_layout`. When true
+ * the response shape switches from `{layout, etag}` to
+ * `{elements: [...], etag}` and `fields[]` projection becomes meaningful.
+ */
+export const FLAT = z
+    .boolean()
+    .default(false)
+    .describe('When true, response is a flat [{path, element_type, ...}] array. Enables ' +
+    'fields[] projection. Default: false (nested layout, no projection).');
+// ─── Default field-sets per tool ─────────────────────────────────────
+/**
+ * Default fields echoed when the caller omits `fields`. Following the
+ * apimapper-mcp convention these are **echo-only** — projection itself
+ * is skipped (default-all preserved) but `projected_fields` still
+ * surfaces the implicit compact set so the AI can plan future requests.
+ */
+export const DEFAULT_FIELDS_PAGES_LIST = [
+    'id',
+    'label',
+    'type',
+    'elements_count',
+    'modified_at',
+];
+export const DEFAULT_FIELDS_ELEMENT_LIST = [
+    'path',
+    'element_type',
+    'label',
+];
+export const DEFAULT_FIELDS_SCHEMA = [
+    'path',
+    'element_type',
+    'label',
+];
+export const DEFAULT_FIELDS_SOURCES_LIST = [
+    'name',
+    'label',
+    'origin',
+    'kind',
+];
+export const DEFAULT_FIELDS_TYPES_LIST = [
+    'name',
+    'label',
+    'origin',
+    'has_children_support',
+];
+/**
+ * element_get defaults to "all" because the AI often needs the full
+ * props payload for follow-up edits; sparse projection here is opt-in
+ * with nested-path support.
+ */
+export const DEFAULT_FIELDS_ELEMENT_GET = undefined;
+// ─── Pure projection helpers ─────────────────────────────────────────
+/**
+ * Project an array of items to the requested fields. Returns items
+ * unchanged when `fields` is undefined (default-all). Skips non-object
+ * entries without crashing (they pass through as-is).
+ *
+ * @param items - The items to project.
+ * @param fields - The whitelist; `undefined` skips projection.
+ * @param _defaults - Per-tool default set, accepted for interface symmetry
+ *   with `projectedFieldsEcho` (unused for actual projection — default-all
+ *   semantics matches the apimapper-mcp reference, see `connections.ts:789`).
+ */
+export function projectFields(items, fields, _defaults) {
+    if (fields === undefined) {
+        return [...items];
+    }
+    const mutable = [...fields];
+    return items.map((item) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            return item;
+        }
+        return pickFields(item, mutable);
+    });
+}
+/**
+ * Project a single object via the same `pickFields` rules. Returns the
+ * object unchanged when `fields` is undefined.
+ */
+export function projectFieldsSingle(obj, fields, _defaults) {
+    if (fields === undefined) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return obj;
+    }
+    return pickFields(obj, [...fields]);
+}
+/**
+ * Compute the `projected_fields` echo. Returns the caller-requested
+ * fields when provided; otherwise returns the per-tool default set so
+ * the AI client knows exactly which compact view it implicitly opted into.
+ *
+ * @returns `undefined` only when neither `requested` nor `defaults` was set
+ *   (e.g. `element_get` with no opt-in) — callers should omit
+ *   `projected_fields` from the structuredContent in that case.
+ */
+export function projectedFieldsEcho(requested, defaults) {
+    if (requested !== undefined)
+        return requested;
+    if (defaults !== undefined)
+        return defaults;
+    return undefined;
+}
+//# sourceMappingURL=sparse-fields.js.map

package/dist/tools/sparse-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-fields.js","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC;KAClB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KACxB,GAAG,CAAC,EAAE,CAAC;KACP,QAAQ,EAAE;KACV,QAAQ,CACL,4EAA4E;IACxE,mFAAmF;IACnF,iFAAiF;IACjF,kBAAkB,CACzB,CAAC;AAEN;;;;GAIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC;KAChB,OAAO,EAAE;KACT,OAAO,CAAC,KAAK,CAAC;KACd,QAAQ,CACL,2EAA2E;IACvE,qEAAqE,CAC5E,CAAC;AAEN,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IACxD,IAAI;IACJ,OAAO;IACP,MAAM;IACN,gBAAgB;IAChB,aAAa;CAChB,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAsB;IAC1D,MAAM;IACN,cAAc;IACd,OAAO;CACV,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACpD,MAAM;IACN,cAAc;IACd,OAAO;CACV,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAsB;IAC1D,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;CACT,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IACxD,MAAM;IACN,OAAO;IACP,QAAQ;IACR,sBAAsB;CACzB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAkC,SAAS,CAAC;AAEnF,wEAAwE;AAExE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CACzB,KAAmB,EACnB,MAAqC,EACrC,SAA4B;IAE5B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtB,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACnE,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,CAAM,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAC/B,GAAM,EACN,MAAqC,EACrC,SAAwC;IAExC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,OAAO,GAAG,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAM,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAC/B,SAAwC,EACxC,QAAuC;IAEvC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,SAAS,CAAC;AACrB,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * `tool-builder/annotations` — annotation builders that produce the
+ * MCP `ToolAnnotations` shape. Each helper encodes a verified
+ * read/write/destructive policy so call-sites in domain tools (pages,
+ * elements, sources, …) get a single one-liner instead of repeating
+ * the four-flag pattern verbatim.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+import type { ToolAnnotations } from './types.js';
+/** Build a `readOnly` annotation. */
+export declare function readOnly(title?: string): ToolAnnotations;
+/** Build a `mutating` annotation for idempotent updates (PUT). */
+export declare function mutating(title?: string): ToolAnnotations;
+/** Build a `creating` annotation for non-idempotent creates (POST). */
+export declare function creating(title?: string): ToolAnnotations;
+/** Build a `destructive` annotation. Callers MUST also expose a `confirm` param. */
+export declare function destructive(title?: string): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAExD;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAExD;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAExD;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQ3D"}

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

@@ -0,0 +1,35 @@
+/**
+ * `tool-builder/annotations` — annotation builders that produce the
+ * MCP `ToolAnnotations` shape. Each helper encodes a verified
+ * read/write/destructive policy so call-sites in domain tools (pages,
+ * elements, sources, …) get a single one-liner instead of repeating
+ * the four-flag pattern verbatim.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+/** Build a `readOnly` annotation. */
+export function readOnly(title) {
+    return { title, readOnlyHint: true, openWorldHint: true };
+}
+/** Build a `mutating` annotation for idempotent updates (PUT). */
+export function mutating(title) {
+    return { title, readOnlyHint: false, openWorldHint: true, idempotentHint: true };
+}
+/** Build a `creating` annotation for non-idempotent creates (POST). */
+export function creating(title) {
+    return { title, readOnlyHint: false, openWorldHint: true, idempotentHint: false };
+}
+/** Build a `destructive` annotation. Callers MUST also expose a `confirm` param. */
+export function destructive(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+        idempotentHint: false,
+    };
+}
+//# sourceMappingURL=annotations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,qCAAqC;AACrC,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;AAC9D,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AACrF,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AACtF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,KAAc;IACtC,OAAO;QACH,KAAK;QACL,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,IAAI;QACrB,aAAa,EAAE,IAAI;QACnB,cAAc,EAAE,KAAK;KACxB,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * `tool-builder/define` — the `defineTool` identity helper plus the
+ * progress-reporter re-export.
+ *
+ * `defineTool` is intentionally trivial at runtime (returns its
+ * argument verbatim) — its only job is to preserve the inferred Zod
+ * schema shape so each tool's handler is fully type-checked against
+ * its inputSchema. The wrapping/sanitising work happens in
+ * `results.ts`.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+import { createProgressReporter as toolkitCreateProgressReporter } from '@getimo/mcp-toolkit';
+import type { ZodRawShape } from 'zod';
+import type { ToolDefinition } from './types.js';
+/**
+ * Re-export the toolkit's `createProgressReporter` under a stable
+ * local symbol so every write-handler in this package depends on a
+ * single import path. Returns `null` when the caller sent no
+ * `progressToken` — handlers then no-op via `progress?.report(...)`.
+ */
+export declare const createProgressReporter: typeof toolkitCreateProgressReporter;
+/**
+ * `defineTool` — preserves the inferred Zod-schema shape so each
+ * tool's handler is fully type-checked against its inputSchema.
+ */
+export declare function defineTool<TSchema extends ZodRawShape>(def: ToolDefinition<TSchema>): ToolDefinition<TSchema>;
+//# sourceMappingURL=define.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,sBAAsB,IAAI,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,sCAAgC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,WAAW,EAClD,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,GAC7B,cAAc,CAAC,OAAO,CAAC,CAEzB"}

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

@@ -0,0 +1,31 @@
+/**
+ * `tool-builder/define` — the `defineTool` identity helper plus the
+ * progress-reporter re-export.
+ *
+ * `defineTool` is intentionally trivial at runtime (returns its
+ * argument verbatim) — its only job is to preserve the inferred Zod
+ * schema shape so each tool's handler is fully type-checked against
+ * its inputSchema. The wrapping/sanitising work happens in
+ * `results.ts`.
+ *
+ * Split from `tool-builder.ts` in Round-1.5 — see `index.ts` for
+ * the cohesion rationale.
+ *
+ * @license MIT
+ */
+import { createProgressReporter as toolkitCreateProgressReporter } from '@getimo/mcp-toolkit';
+/**
+ * Re-export the toolkit's `createProgressReporter` under a stable
+ * local symbol so every write-handler in this package depends on a
+ * single import path. Returns `null` when the caller sent no
+ * `progressToken` — handlers then no-op via `progress?.report(...)`.
+ */
+export const createProgressReporter = toolkitCreateProgressReporter;
+/**
+ * `defineTool` — preserves the inferred Zod-schema shape so each
+ * tool's handler is fully type-checked against its inputSchema.
+ */
+export function defineTool(def) {
+    return def;
+}
+//# sourceMappingURL=define.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,sBAAsB,IAAI,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAI9F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAEpE;;;GAGG;AACH,MAAM,UAAU,UAAU,CACtB,GAA4B;IAE5B,OAAO,GAAG,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * `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, } from './results.js';
+export { createProgressReporter, defineTool } from './define.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,27 @@
+/**
+ * `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, } from './results.js';
+export { createProgressReporter, defineTool } from './define.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * `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 { ToolContent, ToolResult } from './types.js';
+/**
+ * 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 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.
+ */
+export declare function confirmGuard(opts: {
+    operation: string;
+    details: Record<string, unknown>;
+}): ToolResult;
+/**
+ * Merge a toolkit `StructuredCallToolResult` (carries `content[0].text`
+ * + `_meta.ui`) with a domain-typed `structuredContent` payload. The
+ * result satisfies both Rich-Card hosts (read `_meta.ui`) 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.
+ */
+export declare function structuredResult(toolkitResult: {
+    content: ToolContent[];
+    _meta?: {
+        ui?: unknown;
+    } & Record<string, unknown>;
+    isError?: boolean;
+}, structuredContent: Record<string, unknown>): ToolResult;
+//# sourceMappingURL=results.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAaD;;;;;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,CAYb;AAED;;;;GAIG;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,CAQb;AAuBD;;;;;;;GAOG;AACH,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,CAgBZ"}

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

@@ -0,0 +1,125 @@
+/**
+ * `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 { NetworkError, RestError } from '../../errors.js';
+import { sanitizeForLogs } from '../../errors/mask.js';
+import { sanitizeSecrets } from '../../errors/sanitize.js';
+function stringify(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * 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 function jsonResult(payload, options = {}) {
+    const safe = sanitizeSecrets(payload);
+    return {
+        content: [{ type: 'text', text: stringify(safe) }],
+        ...(options.isError === true ? { isError: true } : {}),
+    };
+}
+/** Extract `(message, status?, code?)` from any thrown value, honouring
+ * `RestError` / `NetworkError` shape distinctions. */
+function describeError(e) {
+    if (e instanceof RestError)
+        return { message: e.message, status: e.status, code: e.code };
+    if (e instanceof NetworkError)
+        return { message: e.message };
+    if (e instanceof Error)
+        return { message: e.message };
+    return { message: stringify(e) };
+}
+/**
+ * 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 function errorResult(opts) {
+    const { message, status, code } = describeError(opts.error);
+    return jsonResult({
+        error: sanitizeForLogs(message),
+        ...(status !== undefined ? { status } : {}),
+        ...(code !== undefined ? { code } : {}),
+        context: sanitizeSecrets(opts.context),
+        hint: opts.hint,
+    }, { isError: true });
+}
+/**
+ * Confirm-guard preview helper for destructive tools. Returns the
+ * preview `ToolResult` when `confirm` is false; callers `return` it
+ * before executing the destructive REST call.
+ */
+export function confirmGuard(opts) {
+    return jsonResult({
+        preview: true,
+        warning: 'DESTRUCTIVE — Confirmation required',
+        operation: opts.operation,
+        details: opts.details,
+        instruction: 'Ask the user to confirm, then call again with `confirm: true`.',
+    });
+}
+/**
+ * Sanitise a single content item from a toolkit builder. Text items
+ * frequently embed a JSON-stringified payload — if it parses, deep-walk
+ * and re-stringify; otherwise leave as-is (toolkit-rendered tables /
+ * details are already domain-mapped at the call site).
+ */
+function sanitizeContentItem(item) {
+    if (item.type !== 'text' || typeof item.text !== 'string')
+        return item;
+    const text = item.text;
+    try {
+        const parsed = JSON.parse(text);
+        const safe = sanitizeSecrets(parsed);
+        return { ...item, text: stringify(safe) };
+    }
+    catch {
+        // Not JSON — toolkit-rendered text. No structural redaction
+        // possible without false-positives; the caller has already
+        // mapped raw secrets out via field-projection helpers.
+        return item;
+    }
+}
+/**
+ * Merge a toolkit `StructuredCallToolResult` (carries `content[0].text`
+ * + `_meta.ui`) with a domain-typed `structuredContent` payload. The
+ * result satisfies both Rich-Card hosts (read `_meta.ui`) 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.
+ */
+export function structuredResult(toolkitResult, structuredContent) {
+    // Wave G.6.4b — deep-walk-sanitise all three legs (text content,
+    // _meta.ui, structuredContent) so regressing sources never bypass
+    // the LLM-boundary mask.
+    const safeContent = toolkitResult.content.map(sanitizeContentItem);
+    const safeStructured = sanitizeSecrets(structuredContent);
+    const safeMeta = toolkitResult._meta !== undefined
+        ? sanitizeSecrets(toolkitResult._meta)
+        : undefined;
+    return {
+        content: safeContent,
+        ...(safeMeta !== undefined ? { _meta: safeMeta } : {}),
+        ...(toolkitResult.isError === true ? { isError: true } : {}),
+        structuredContent: safeStructured,
+    };
+}
+//# sourceMappingURL=results.js.map