@wootsup/yt-builder-mcp 1.0.1 → 1.1.0

package/dist/platform/joomla.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Joomla 5/6 platform implementation — Wave 7 prep.
+ *
+ * Mirrors {@link WordPressPlatform} but targets the Joomla Web Services
+ * API surface registered by `plg_system_ytbmcp` (see
+ * `src/packaging/joomla/extensions/plg_system_ytbmcp/src/Extension/Ytbmcp.php`
+ * — `onBeforeApiRoute()` mounts the routes under
+ * `v1/yt-builder-mcp/...` against `com_ytbmcp`).
+ *
+ * The full request URL composed by {@link RestClient} is:
+ *
+ *     {baseUrl}/api/index.php/v1/yt-builder-mcp/{path}
+ *
+ * — where `{baseUrl}` is the Joomla site origin (e.g. `https://example.com`
+ * or `https://example.com/joomla` for a subfolder install) and `{path}`
+ * is the per-tool REST path (e.g. `/health`, `/pages`, `/etag`).
+ *
+ * Cookbook Ch1 Finding 2: the `PlatformKind` union already declared
+ * `'joomla'` in Wave G.0; this class fills the seam so no tool handler
+ * has to change.
+ *
+ * Cookbook §3.7 (cross-platform parity): the REST byte-shape returned
+ * by every endpoint is identical across platforms — only the route
+ * prefix differs.
+ *
+ * @license MIT
+ */
+import type { Platform } from './index.js';
+/** Canonical Joomla REST namespace prefix for this plugin. */
+export declare const JOOMLA_REST_NAMESPACE_PATH = "/api/index.php/v1/yt-builder-mcp";
+/**
+ * Joomla platform implementation.
+ *
+ * `restNamespacePath` is fixed to the Web Services API mount point that
+ * `plg_system_ytbmcp::onBeforeApiRoute()` registers; the caller supplies
+ * only the site origin.
+ */
+export declare class JoomlaPlatform implements Platform {
+    readonly kind: "joomla";
+    readonly baseUrl: string;
+    readonly restNamespacePath: string;
+    constructor(baseUrl: string);
+}
+//# sourceMappingURL=joomla.d.ts.map

package/dist/platform/joomla.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joomla.d.ts","sourceRoot":"","sources":["../../src/platform/joomla.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC3C,SAAgB,IAAI,EAAG,QAAQ,CAAU;IACzC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,OAAO,EAAE,MAAM;CAI9B"}

package/dist/platform/joomla.js

@@ -0,0 +1,46 @@
+/**
+ * Joomla 5/6 platform implementation — Wave 7 prep.
+ *
+ * Mirrors {@link WordPressPlatform} but targets the Joomla Web Services
+ * API surface registered by `plg_system_ytbmcp` (see
+ * `src/packaging/joomla/extensions/plg_system_ytbmcp/src/Extension/Ytbmcp.php`
+ * — `onBeforeApiRoute()` mounts the routes under
+ * `v1/yt-builder-mcp/...` against `com_ytbmcp`).
+ *
+ * The full request URL composed by {@link RestClient} is:
+ *
+ *     {baseUrl}/api/index.php/v1/yt-builder-mcp/{path}
+ *
+ * — where `{baseUrl}` is the Joomla site origin (e.g. `https://example.com`
+ * or `https://example.com/joomla` for a subfolder install) and `{path}`
+ * is the per-tool REST path (e.g. `/health`, `/pages`, `/etag`).
+ *
+ * Cookbook Ch1 Finding 2: the `PlatformKind` union already declared
+ * `'joomla'` in Wave G.0; this class fills the seam so no tool handler
+ * has to change.
+ *
+ * Cookbook §3.7 (cross-platform parity): the REST byte-shape returned
+ * by every endpoint is identical across platforms — only the route
+ * prefix differs.
+ *
+ * @license MIT
+ */
+/** Canonical Joomla REST namespace prefix for this plugin. */
+export const JOOMLA_REST_NAMESPACE_PATH = '/api/index.php/v1/yt-builder-mcp';
+/**
+ * Joomla platform implementation.
+ *
+ * `restNamespacePath` is fixed to the Web Services API mount point that
+ * `plg_system_ytbmcp::onBeforeApiRoute()` registers; the caller supplies
+ * only the site origin.
+ */
+export class JoomlaPlatform {
+    kind = 'joomla';
+    baseUrl;
+    restNamespacePath;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+        this.restNamespacePath = JOOMLA_REST_NAMESPACE_PATH;
+    }
+}
+//# sourceMappingURL=joomla.js.map

package/dist/platform/joomla.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joomla.js","sourceRoot":"","sources":["../../src/platform/joomla.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,0BAA0B,GAAG,kCAAkC,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACP,IAAI,GAAG,QAAiB,CAAC;IACzB,OAAO,CAAS;IAChB,iBAAiB,CAAS;IAE1C,YAAY,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,0BAA0B,CAAC;IACxD,CAAC;CACJ"}

package/dist/server.d.ts

@@ -0,0 +1,109 @@
+/**
+ * MCP server factory — Wave G.1 / Gateway-Hub edition.
+ *
+ * `createServer({client})` builds a configured `McpServer` with a 3-lane
+ * tool registration:
+ *
+ *   L3 — direct top-level (yootheme_builder_health + yootheme_builder_diagnose)
+ *        Registered FIRST, BEFORE the CapturingServer wraps the real server.
+ *        These tools must reach the LLM even when the gateway itself
+ *        misbehaves (chicken-and-egg: the LLM diagnoses gateway breakage
+ *        via these two).
+ *
+ *   L1 — essential forwarded (7 tools)
+ *        Routed through the CapturingServer to the real server. Appear in
+ *        `tools/list` as first-class entries (Cursor-cap-safe).
+ *
+ *   L2 — advanced captured (12 tools)
+ *        Routed through the CapturingServer into its in-process advanced
+ *        registry; reachable via the single `yootheme_builder_advanced`
+ *        gateway tool. Hidden from `tools/list`.
+ *
+ *   Gateway — `yootheme_builder_advanced`
+ *        Registered LAST on the real server, after every L1/L2 tool is
+ *        placed and the advanced registry is final.
+ *
+ * Result: `tools/list.length === 10` (7 L1 + 2 L3 + 1 gateway), and the
+ * full tool surface is 22 (collectAllRegisteredTools).
+ *
+ * @license MIT
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CapturingServer } from './gateway/capturing-server.js';
+import type { ClientPool } from './sites/client-pool.js';
+import type { SiteRegistry } from './sites/registry.js';
+import { type ToolDefinition } from './tools/index.js';
+export declare const SERVER_NAME = "@wootsup/yt-builder-mcp";
+export declare const SERVER_VERSION = "0.2.0-alpha.2";
+/**
+ * W8 — stable URI under which the live sites snapshot is exposed via
+ * MCP `resources/*`. Single fixed resource (no list-changed needed) —
+ * MCP hosts can fetch the current registry roster on demand without
+ * having to invoke a tool.
+ */
+export declare const SITES_RESOURCE_URI = "sites://current";
+/** Human-readable resource name surfaced in `resources/list`. */
+export declare const SITES_RESOURCE_NAME = "Currently configured sites";
+/** Short description for `resources/list` consumers. */
+export declare const SITES_RESOURCE_DESCRIPTION: string;
+/** MIME type for the `sites://current` payload. */
+export declare const SITES_RESOURCE_MIME_TYPE = "application/json";
+/**
+ * Bearer-redacted JSON payload shape for the W8 `sites://current`
+ * resource. Mirrors the structured-content shape of the
+ * `yootheme_builder_sites_list` tool but never reveals bearer or
+ * bearer_ref — only safe-to-render display fields land in the
+ * `sites[]` rows.
+ */
+export interface SitesResourcePayload {
+    readonly default_site_id: string | null;
+    readonly sites: readonly SitesResourceRow[];
+}
+/**
+ * One row inside {@link SitesResourcePayload.sites}. Strictly the
+ * fields enumerated by plan §W8 Z.929 — no bearer / bearer_ref /
+ * bearer_source. `label` and `platform_resolved` are optional (only
+ * present when the underlying registry entry / probe carries them).
+ */
+export interface SitesResourceRow {
+    readonly site_id: string;
+    readonly url: string;
+    readonly platform: 'wordpress' | 'joomla' | 'auto';
+    readonly is_default: boolean;
+    readonly label?: string;
+}
+/**
+ * Build the JSON payload served by the `sites://current` resource.
+ *
+ * Field projection (per plan §W8 Z.925-933):
+ *  - `default_site_id` from {@link SiteRegistry.defaultSiteId}.
+ *  - `sites[].site_id` / `url` / `is_default` / `label` verbatim.
+ *  - `sites[].platform` prefers the resolved kind from the W3 memo
+ *    cache (peek-only, no probe) and falls back to the configured
+ *    hint when no probe has run.
+ *
+ * Bearer fields are NEVER referenced. The `bearer_source` hint that
+ * the W7 `sites_list` tool exposes is intentionally omitted from this
+ * resource: even the "plain" vs "op" hint hints at storage layout,
+ * and the resource is positioned as a host-facing public roster.
+ */
+export declare function buildSitesResourcePayload(registry: SiteRegistry): SitesResourcePayload;
+export interface CreateServerOptions {
+    /**
+     * Multi-site client pool — replaces the single `client` parameter
+     * shipped pre-W6. Each tool handler asks `pool.resolve(site_id)`
+     * for the per-call REST client + resolved site descriptor.
+     */
+    readonly pool: ClientPool;
+    /** Override the tool set (defaults to `buildAllTools`). */
+    readonly tools?: readonly ToolDefinition[];
+}
+export interface CreatedServer {
+    readonly mcp: McpServer;
+    /** The full set of tool definitions registered across all 3 lanes + gateway. */
+    readonly tools: readonly ToolDefinition[];
+    /** The CapturingServer wrapping `mcp` — exposed for test helpers. */
+    readonly capturing: CapturingServer;
+}
+export declare function createServer(options: CreateServerOptions): CreatedServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,eAAe,EAAsB,MAAM,+BAA+B,CAAC;AAEpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEtE,eAAO,MAAM,WAAW,4BAA4B,CAAC;AACrD,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAGsB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,YAAY,GACvB,oBAAoB,CAmBtB;AAED,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACvC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAuIxE"}

package/dist/server.js

@@ -0,0 +1,237 @@
+/**
+ * MCP server factory — Wave G.1 / Gateway-Hub edition.
+ *
+ * `createServer({client})` builds a configured `McpServer` with a 3-lane
+ * tool registration:
+ *
+ *   L3 — direct top-level (yootheme_builder_health + yootheme_builder_diagnose)
+ *        Registered FIRST, BEFORE the CapturingServer wraps the real server.
+ *        These tools must reach the LLM even when the gateway itself
+ *        misbehaves (chicken-and-egg: the LLM diagnoses gateway breakage
+ *        via these two).
+ *
+ *   L1 — essential forwarded (7 tools)
+ *        Routed through the CapturingServer to the real server. Appear in
+ *        `tools/list` as first-class entries (Cursor-cap-safe).
+ *
+ *   L2 — advanced captured (12 tools)
+ *        Routed through the CapturingServer into its in-process advanced
+ *        registry; reachable via the single `yootheme_builder_advanced`
+ *        gateway tool. Hidden from `tools/list`.
+ *
+ *   Gateway — `yootheme_builder_advanced`
+ *        Registered LAST on the real server, after every L1/L2 tool is
+ *        placed and the advanced registry is final.
+ *
+ * Result: `tools/list.length === 10` (7 L1 + 2 L3 + 1 gateway), and the
+ * full tool surface is 22 (collectAllRegisteredTools).
+ *
+ * @license MIT
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerAdvancedTool } from './gateway/advanced-tool.js';
+import { CapturingServer } from './gateway/capturing-server.js';
+import { isDirectTopLevel } from './gateway/essentials.js';
+import { loadSkillContent, SKILL_RESOURCE_DESCRIPTION, SKILL_RESOURCE_MIME_TYPE, SKILL_RESOURCE_NAME, SKILL_RESOURCE_URI, } from './skill-loader.js';
+import { toElicitationCapability } from './tools/elicitation.js';
+import { buildAllTools } from './tools/index.js';
+export const SERVER_NAME = '@wootsup/yt-builder-mcp';
+export const SERVER_VERSION = '0.2.0-alpha.2';
+/**
+ * W8 — stable URI under which the live sites snapshot is exposed via
+ * MCP `resources/*`. Single fixed resource (no list-changed needed) —
+ * MCP hosts can fetch the current registry roster on demand without
+ * having to invoke a tool.
+ */
+export const SITES_RESOURCE_URI = 'sites://current';
+/** Human-readable resource name surfaced in `resources/list`. */
+export const SITES_RESOURCE_NAME = 'Currently configured sites';
+/** Short description for `resources/list` consumers. */
+export const SITES_RESOURCE_DESCRIPTION = 'Live snapshot of sites wired into this MCP server (site_id, URL, ' +
+    'platform, default flag, label). Bearer fields are redacted. ' +
+    'Mirrors what `yootheme_builder_sites_list` would print.';
+/** MIME type for the `sites://current` payload. */
+export const SITES_RESOURCE_MIME_TYPE = 'application/json';
+/**
+ * Build the JSON payload served by the `sites://current` resource.
+ *
+ * Field projection (per plan §W8 Z.925-933):
+ *  - `default_site_id` from {@link SiteRegistry.defaultSiteId}.
+ *  - `sites[].site_id` / `url` / `is_default` / `label` verbatim.
+ *  - `sites[].platform` prefers the resolved kind from the W3 memo
+ *    cache (peek-only, no probe) and falls back to the configured
+ *    hint when no probe has run.
+ *
+ * Bearer fields are NEVER referenced. The `bearer_source` hint that
+ * the W7 `sites_list` tool exposes is intentionally omitted from this
+ * resource: even the "plain" vs "op" hint hints at storage layout,
+ * and the resource is positioned as a host-facing public roster.
+ */
+export function buildSitesResourcePayload(registry) {
+    const rows = registry.listForDisplay();
+    return {
+        default_site_id: registry.defaultSiteId(),
+        sites: rows.map((row) => {
+            const platform = row.platform_resolved ?? row.platform_hint;
+            const out = {
+                site_id: row.site_id,
+                url: row.url,
+                platform,
+                is_default: row.is_default,
+            };
+            if (row.label !== undefined) {
+                out.label = row.label;
+            }
+            return out;
+        }),
+    };
+}
+export function createServer(options) {
+    // Stream B1 — Skill-Distribution via MCP-Protocol.
+    //
+    // The bundled SKILL.md is published through two MCP-native channels:
+    //
+    //   (a) `instructions` field on the `initialize` response. MCP-spec
+    //       hosts (Claude Desktop, Cursor, …) surface this string as
+    //       auto-context so Maria-the-Claude-Desktop-user receives the
+    //       skill narrative without ever calling a tool.
+    //
+    //   (b) `skill://yt-builder-mcp` resource exposed via
+    //       `resources/list` + `resources/read`. Backup for hosts that
+    //       ignore `instructions` but honor the resources API.
+    //
+    // Reading SKILL.md is synchronous (small file, ~17 KB) and cached
+    // after first call by `loadSkillContent` — no async cost.
+    //
+    // W8 — pass the pool's registry so loadSkillContent can append the
+    // live "Currently configured sites" block. When the registry is
+    // empty (fresh install, no sites yet) the appendix is silently
+    // omitted and the host receives the unchanged skill content.
+    // Bearer fields are never touched by the appendix (see
+    // {@link appendSitesBlock} in skill-loader.ts).
+    const instructions = loadSkillContent(options.pool.registry);
+    const mcp = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        instructions,
+    });
+    // Register the SKILL.md as a static MCP resource. The capability
+    // (`resources: { listChanged: true }` etc.) is auto-advertised by
+    // McpServer the moment the first resource is registered, so MCP
+    // hosts see `resources` in `initialize.capabilities`.
+    mcp.registerResource(SKILL_RESOURCE_NAME, SKILL_RESOURCE_URI, {
+        title: SKILL_RESOURCE_NAME,
+        description: SKILL_RESOURCE_DESCRIPTION,
+        mimeType: SKILL_RESOURCE_MIME_TYPE,
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.toString(),
+                mimeType: SKILL_RESOURCE_MIME_TYPE,
+                text: instructions,
+            },
+        ],
+    }));
+    // W8 — `sites://current` resource: live registry snapshot as JSON.
+    //
+    // The payload is computed on every read (cheap — listForDisplay()
+    // is in-memory) so hosts that re-fetch after a sites file edit see
+    // up-to-date data. We do NOT emit `notifications/resources/updated`
+    // since the only mutation path is the W9 CLI which itself requires
+    // an AI-client restart (per plan §W8 line 919) — the resource is
+    // structurally static for the lifetime of the MCP session.
+    //
+    // Bearer / bearer_ref are NEVER referenced (see
+    // {@link buildSitesResourcePayload}). The resource intentionally
+    // omits the `bearer_source` hint that the `sites_list` tool
+    // surfaces; a host-facing roster should not even hint at storage
+    // layout.
+    const registry = options.pool.registry;
+    mcp.registerResource(SITES_RESOURCE_NAME, SITES_RESOURCE_URI, {
+        title: SITES_RESOURCE_NAME,
+        description: SITES_RESOURCE_DESCRIPTION,
+        mimeType: SITES_RESOURCE_MIME_TYPE,
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.toString(),
+                mimeType: SITES_RESOURCE_MIME_TYPE,
+                text: JSON.stringify(buildSitesResourcePayload(registry), null, 2),
+            },
+        ],
+    }));
+    // Wave G.4.5 — MCP elicitation capability wiring.
+    //
+    // `toElicitationCapability(mcp)` bridges the SDK's stricter
+    // discriminated `ElicitRequestFormParams` to the toolkit's looser
+    // `ElicitInputParams`. The 3 elicitation-aware tools
+    // (`element_delete`, `element_unbind_source`, `element_bind_source`)
+    // consume this capability through their `*HandlerDeps`; the other 19
+    // tools never see it. When the host the SDK connects to does not
+    // advertise the elicitation capability, the toolkit's `elicitChoice` /
+    // `elicitConfirmation` return `null` / `false` and the tool falls
+    // back to the structured-error / preview path (no hang, no guess).
+    const elicitation = toElicitationCapability(mcp);
+    const tools = options.tools ?? buildAllTools(options.pool, { elicitation });
+    // L3 — direct top-level: registered FIRST on the real McpServer, before
+    // the CapturingServer wraps it. These names get a no-op route inside
+    // the CapturingServer (see capturing-server.ts), so the SDK never sees
+    // a duplicate registration when the builder list is later replayed.
+    for (const tool of tools) {
+        if (isDirectTopLevel(tool.name)) {
+            registerToolOn(mcp, tool);
+        }
+    }
+    // L1 / L2 — every other tool is routed through the CapturingServer,
+    // which forwards essentials to the real server and captures the rest
+    // into its advanced registry.
+    const capturing = new CapturingServer(mcp);
+    for (const tool of tools) {
+        if (isDirectTopLevel(tool.name))
+            continue;
+        registerToolOn(capturing, tool);
+    }
+    // Gateway — registered LAST so the advanced registry is final.
+    registerAdvancedTool(mcp, capturing.getAdvancedRegistry());
+    return { mcp, tools, capturing };
+}
+/**
+ * Registers a `ToolDefinition` on a `ToolRegistrar`. A real `McpServer`
+ * satisfies `ToolRegistrar` structurally (its `registerTool` returns
+ * `RegisteredTool`, which is assignable to the `ToolRegistrar` declared
+ * `void` return type), so call-sites pass either a real server (for L3
+ * + the gateway, which need not be captured) or a `CapturingServer`
+ * (for L1 + L2 routing).
+ */
+function registerToolOn(registrar, tool) {
+    // The SDK's `registerTool` accepts a raw Zod shape as inputSchema. We
+    // cast through `ZodRawShapeCompat` to keep our `ToolDefinition` generic
+    // (any ZodRawShape) compatible with the SDK's v3/v4 dual-zod surface.
+    const inputSchema = tool.inputSchema;
+    // outputSchema is optional — tools migrated to structured-content (Wave
+    // G.2) declare a Zod schema describing the `structuredContent` payload.
+    // The SDK accepts a `ZodTypeAny` (v3/v4) via `AnySchema`; we forward our
+    // schema verbatim. Hosts that support MCP structured output validate
+    // responses against this schema.
+    const outputSchema = tool.outputSchema !== undefined
+        ? tool.outputSchema
+        : undefined;
+    registrar.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema,
+        ...(outputSchema !== undefined ? { outputSchema } : {}),
+        annotations: tool.annotations,
+    }, 
+    // Wave G.5 — forward the SDK-supplied `extra` (RequestHandlerExtra)
+    // as the 2nd argument to every handler. Write-handlers consume
+    // `extra._meta.progressToken` + `extra.sendNotification` via the
+    // local `createProgressReporter` helper; read-handlers ignore it
+    // (their handler signature still binds `extra` to `HandlerExtra |
+    // undefined`, so no runtime coupling for non-progress tools).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK generic narrows to inferred shape; safe because zod validates upstream
+    (async (args, extra) => {
+        return tool.handler(args, extra);
+    }));
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/setup-cli-confirm.d.ts

@@ -0,0 +1,36 @@
+/**
+ * W12-R2A — TTY confirm prompt for destructive CLI subcommands.
+ *
+ * Hosts `confirmTTY(prompt)`, the y/N readline callback the W9
+ * dispatcher wires into the `removeSiteCommand` / `setDefaultCommand`
+ * deps bag. Lives in its own file so the dispatcher stays a thin
+ * routing layer and so tests can mock the prompt without touching the
+ * subcommand factories.
+ *
+ * Contract:
+ *
+ *  - Returns `true` ONLY when stdin is a TTY AND the operator types
+ *    "y", "Y", or "yes" (case-insensitive). Anything else (incl. EOF,
+ *    empty line, Ctrl-D) returns `false` → caller treats this as a
+ *    cancel and skips the write.
+ *
+ *  - When stdin is NOT a TTY (CI, piped input, MCP-server stdio), the
+ *    function does NOT block — it returns `false` immediately and
+ *    writes a one-line hint to stderr telling the operator to pass
+ *    `--yes` for non-interactive use. The dispatcher then surfaces a
+ *    typed `CONFIRM_REQUIRED` / `SET_DEFAULT_CONFIRM_REQUIRED` error
+ *    via the subcommand factory (which fails closed when no confirm
+ *    hook AND no --yes is in play).
+ *
+ *  - No external deps; uses Node's built-in `node:readline` so the
+ *    package keeps the same dep-graph as Round-1.
+ *
+ * @license MIT
+ */
+/**
+ * Read one line via readline and resolve `true` on y/Y/yes,
+ * `false` otherwise. Stdin-not-a-TTY short-circuits to `false` with a
+ * stderr hint so a piped invocation can't silently hang.
+ */
+export declare function confirmTTY(prompt: string): Promise<boolean>;
+//# sourceMappingURL=setup-cli-confirm.d.ts.map

package/dist/setup-cli-confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-cli-confirm.d.ts","sourceRoot":"","sources":["../src/setup-cli-confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAuBjE"}

package/dist/setup-cli-confirm.js

@@ -0,0 +1,59 @@
+/**
+ * W12-R2A — TTY confirm prompt for destructive CLI subcommands.
+ *
+ * Hosts `confirmTTY(prompt)`, the y/N readline callback the W9
+ * dispatcher wires into the `removeSiteCommand` / `setDefaultCommand`
+ * deps bag. Lives in its own file so the dispatcher stays a thin
+ * routing layer and so tests can mock the prompt without touching the
+ * subcommand factories.
+ *
+ * Contract:
+ *
+ *  - Returns `true` ONLY when stdin is a TTY AND the operator types
+ *    "y", "Y", or "yes" (case-insensitive). Anything else (incl. EOF,
+ *    empty line, Ctrl-D) returns `false` → caller treats this as a
+ *    cancel and skips the write.
+ *
+ *  - When stdin is NOT a TTY (CI, piped input, MCP-server stdio), the
+ *    function does NOT block — it returns `false` immediately and
+ *    writes a one-line hint to stderr telling the operator to pass
+ *    `--yes` for non-interactive use. The dispatcher then surfaces a
+ *    typed `CONFIRM_REQUIRED` / `SET_DEFAULT_CONFIRM_REQUIRED` error
+ *    via the subcommand factory (which fails closed when no confirm
+ *    hook AND no --yes is in play).
+ *
+ *  - No external deps; uses Node's built-in `node:readline` so the
+ *    package keeps the same dep-graph as Round-1.
+ *
+ * @license MIT
+ */
+import { createInterface } from 'node:readline';
+/**
+ * Read one line via readline and resolve `true` on y/Y/yes,
+ * `false` otherwise. Stdin-not-a-TTY short-circuits to `false` with a
+ * stderr hint so a piped invocation can't silently hang.
+ */
+export async function confirmTTY(prompt) {
+    // process.stdin.isTTY is `true | undefined` per Node's typings —
+    // explicit !== true guards against both undefined and false.
+    if (process.stdin.isTTY !== true) {
+        process.stderr.write('yt-builder-mcp: no TTY available for confirmation. '
+            + 'Pass --yes to run this subcommand non-interactively.\n');
+        return false;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(`${prompt} [y/N] `, (line) => resolve(line));
+        });
+        const normalised = answer.trim().toLowerCase();
+        return normalised === 'y' || normalised === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=setup-cli-confirm.js.map

package/dist/setup-cli-confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-cli-confirm.js","sourceRoot":"","sources":["../src/setup-cli-confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc;IAC3C,iEAAiE;IACjE,6DAA6D;IAC7D,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,qDAAqD;cAC/C,wDAAwD,CACjE,CAAC;QACF,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,EAAE,GAAG,eAAe,CAAC;QACvB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACzB,CAAC,CAAC;IACH,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;YACjD,EAAE,CAAC,QAAQ,CAAC,GAAG,MAAM,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/C,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,KAAK,CAAC;IACtD,CAAC;YAAS,CAAC;QACP,EAAE,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;AACL,CAAC"}