@wootsup/yt-builder-mcp 1.3.0 → 1.4.0

package/dist/diagnostics/doctor.d.ts

@@ -0,0 +1,62 @@
+export type DoctorStatus = 'ok' | 'warn' | 'fail' | 'info';
+export interface DoctorCheck {
+    readonly name: string;
+    readonly label: string;
+    readonly status: DoctorStatus;
+    readonly detail: string;
+    /** Actionable fix when status is warn/fail. */
+    readonly fix?: string;
+}
+export interface DoctorReport {
+    readonly checks: readonly DoctorCheck[];
+    /** True when no check failed (warnings are tolerated). */
+    readonly ok: boolean;
+}
+export interface DoctorConfig {
+    readonly url?: string;
+    readonly token?: string;
+    /** Defaults to `process.version`. */
+    readonly nodeVersion?: string;
+    /** Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    readonly currentVersion: string;
+    readonly packageName: string;
+}
+export interface DoctorDeps {
+    /** Probe `<url>/wp-json/yt-builder-mcp/v1/health`. */
+    probeHealth: (url: string) => Promise<{
+        ok: true;
+        pluginVersion?: string;
+    } | {
+        ok: false;
+        error: unknown;
+    }>;
+    /** Probe an authenticated endpoint with the bearer. */
+    probeBearer: (url: string, token: string) => Promise<{
+        ok: boolean;
+        status?: number;
+        error?: unknown;
+    }>;
+    /** Latest version on npm, or null. */
+    fetchLatest: (packageName: string) => Promise<string | null>;
+    /**
+     * G-D #10 — probe `registry.npmjs.org` reachability + TLS chain. Optional
+     * for back-compat (older deps bags / tests). When wired, doctor runs the
+     * network-error classifier on a failure and surfaces the SAME CA fix as the
+     * site check — a corporate TLS-inspection CA usually breaks BOTH the site
+     * and the npm registry, but the old code swallowed the registry error into
+     * a generic "could not reach npm".
+     */
+    probeRegistry?: () => Promise<{
+        ok: boolean;
+        error?: unknown;
+    }>;
+}
+/**
+ * Run the self-diagnostic. Pure decision core — all network probes are
+ * injected via {@link DoctorDeps}, so the logic is fully testable offline.
+ */
+export declare function runDoctor(config: DoctorConfig, deps: DoctorDeps): Promise<DoctorReport>;
+/** Render a {@link DoctorReport} as a readable, fixed-width-ish text block. */
+export declare function formatDoctorReport(report: DoctorReport): string;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/diagnostics/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/diagnostics/doctor.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACvB,sDAAsD;IACtD,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5G,uDAAuD;IACvD,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxG,sCAAsC;IACtC,WAAW,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnE;AAsBD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAiI7F;AAID,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAS/D"}

package/dist/diagnostics/doctor.js

@@ -0,0 +1,165 @@
+// packages/mcp/src/diagnostics/doctor.ts
+import { diagnoseNetworkError } from './diagnose-network-error.js';
+import { isVersionNewer } from '../update/update-check.js';
+/** Minimum supported Node — must match package.json engines.node. */
+const NODE_FLOOR = [18, 17, 0];
+function parseNodeVersion(v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v);
+    return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function meetsFloor(v, floor) {
+    for (let i = 0; i < 3; i++) {
+        if (v[i] > floor[i])
+            return true;
+        if (v[i] < floor[i])
+            return false;
+    }
+    return true;
+}
+function proxyOf(env) {
+    return env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy ?? null;
+}
+/**
+ * Run the self-diagnostic. Pure decision core — all network probes are
+ * injected via {@link DoctorDeps}, so the logic is fully testable offline.
+ */
+export async function runDoctor(config, deps) {
+    const env = config.env ?? process.env;
+    const nodeVersion = config.nodeVersion ?? process.version;
+    const checks = [];
+    // 1. Node version vs the engines floor.
+    const parsed = parseNodeVersion(nodeVersion);
+    if (parsed !== null && meetsFloor(parsed, NODE_FLOOR)) {
+        checks.push({ name: 'node', label: 'Node.js', status: 'ok', detail: `${nodeVersion} (≥ 18.17.0)` });
+    }
+    else {
+        checks.push({
+            name: 'node',
+            label: 'Node.js',
+            status: 'fail',
+            detail: `${nodeVersion} is below the required 18.17.0`,
+            fix: 'Install Node.js 18.17+ (LTS recommended) and re-run your AI client.',
+        });
+    }
+    // 2. Proxy env (informational).
+    const proxy = proxyOf(env);
+    checks.push(proxy !== null
+        ? { name: 'proxy', label: 'Proxy', status: 'info', detail: `Forward proxy configured: ${proxy}` }
+        : { name: 'proxy', label: 'Proxy', status: 'info', detail: 'No proxy configured (direct connection).' });
+    // 3. Config presence — without url+token we cannot probe the site.
+    const url = config.url;
+    const token = config.token;
+    if (url === undefined || url === '' || token === undefined || token === '') {
+        checks.push({
+            name: 'config',
+            label: 'Configuration',
+            status: 'fail',
+            detail: 'Missing site URL and/or bearer token.',
+            fix: 'Pass --url <site> --token <key>, or run `npx -y @wootsup/yt-builder-mcp setup` first.',
+        });
+    }
+    else {
+        checks.push({ name: 'config', label: 'Configuration', status: 'ok', detail: `Target: ${url}` });
+        // 4. Reachability + TLS.
+        const health = await deps.probeHealth(url);
+        if (health.ok) {
+            checks.push({
+                name: 'reachability',
+                label: 'Plugin reachable',
+                status: 'ok',
+                detail: health.pluginVersion !== undefined ? `OK — plugin ${health.pluginVersion}` : 'OK',
+            });
+        }
+        else {
+            const diag = diagnoseNetworkError(health.error, env);
+            checks.push({
+                name: 'reachability',
+                label: 'Plugin reachable',
+                status: 'fail',
+                detail: diag !== null ? diag.summary : 'Could not reach the plugin health endpoint.',
+                fix: diag !== null ? diag.fix : 'Verify the site URL and that the yt-builder-mcp plugin is active.',
+            });
+        }
+        // 5. Bearer validity (only meaningful if the site was reachable).
+        if (health.ok) {
+            const bearer = await deps.probeBearer(url, token);
+            if (bearer.ok) {
+                checks.push({ name: 'bearer', label: 'Bearer key', status: 'ok', detail: 'Accepted.' });
+            }
+            else {
+                const diag = diagnoseNetworkError(bearer.error ?? { status: bearer.status }, env);
+                checks.push({
+                    name: 'bearer',
+                    label: 'Bearer key',
+                    status: 'fail',
+                    detail: bearer.status !== undefined ? `Rejected (HTTP ${bearer.status}).` : 'Rejected.',
+                    fix: diag !== null && diag.fix.toLowerCase().includes('key')
+                        ? diag.fix
+                        : 'Re-issue an MCP key in the plugin admin (YT Builder MCP → Keys) and update the token.',
+                });
+            }
+        }
+    }
+    // 6. npm registry reachability + cert chain (G-D #10). Run the same
+    //    classifier as the site check: a corporate TLS-inspection CA breaks the
+    //    registry too, and the operator must see that fix here, not a generic
+    //    "could not reach npm". A CA error FAILS (it blocks `npx` upgrades and
+    //    self-serve); any other failure is a soft WARN (update-check is a
+    //    courtesy). Skipped entirely when no probeRegistry dep is wired.
+    if (deps.probeRegistry !== undefined) {
+        const reg = await deps.probeRegistry();
+        if (reg.ok) {
+            checks.push({ name: 'registry', label: 'npm registry', status: 'ok', detail: 'registry.npmjs.org reachable (TLS chain verified).' });
+        }
+        else {
+            const diag = diagnoseNetworkError(reg.error, env);
+            const isCa = diag !== null && diag.fix.includes('NODE_EXTRA_CA_CERTS');
+            checks.push({
+                name: 'registry',
+                label: 'npm registry',
+                status: isCa ? 'fail' : 'warn',
+                detail: diag !== null ? `registry.npmjs.org: ${diag.summary}` : 'Could not reach registry.npmjs.org.',
+                fix: diag !== null
+                    ? diag.fix
+                    : 'Check network/proxy access to registry.npmjs.org (npx pulls @latest from there).',
+            });
+        }
+    }
+    // 7. Update status (fail-silent — never a hard failure).
+    const latest = await deps.fetchLatest(config.packageName).catch(() => null);
+    if (latest === null) {
+        checks.push({
+            name: 'update',
+            label: 'Version',
+            status: 'info',
+            detail: `Running ${config.currentVersion} (could not reach npm to check for updates).`,
+        });
+    }
+    else if (isVersionNewer(latest, config.currentVersion)) {
+        checks.push({
+            name: 'update',
+            label: 'Version',
+            status: 'warn',
+            detail: `Update available: ${config.currentVersion} → ${latest}.`,
+            fix: 'Restart your AI client (npx pulls @latest), or `npm i -g @wootsup/yt-builder-mcp@latest`.',
+        });
+    }
+    else {
+        checks.push({ name: 'update', label: 'Version', status: 'ok', detail: `${config.currentVersion} (latest).` });
+    }
+    return { checks, ok: !checks.some((c) => c.status === 'fail') };
+}
+const GLYPH = { ok: '✓', warn: '!', fail: '✗', info: 'ℹ' };
+/** Render a {@link DoctorReport} as a readable, fixed-width-ish text block. */
+export function formatDoctorReport(report) {
+    const lines = ['yt-builder-mcp doctor', ''];
+    for (const c of report.checks) {
+        lines.push(`  ${GLYPH[c.status]} ${c.label}: ${c.detail}`);
+        if (c.fix !== undefined)
+            lines.push(`      → ${c.fix}`);
+    }
+    lines.push('');
+    lines.push(report.ok ? '✓ All critical checks passed.' : '✗ One or more checks failed — see the fixes above.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/diagnostics/doctor.js.map

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

package/dist/gateway/essentials.d.ts

@@ -42,7 +42,7 @@
  * L1 — Tools kept as first-class entries in `tools/list`.
  * Forwarded by the CapturingServer to the real McpServer.
  */
-export declare const ESSENTIAL_TOOLS: readonly ["yootheme_builder_pages_list", "yootheme_builder_get_etag", "yootheme_builder_element_list", "yootheme_builder_element_add", "yootheme_builder_element_update_settings", "yootheme_builder_sources_list", "yootheme_builder_element_types_list", "yootheme_builder_inspect_multi_items_binding", "yootheme_builder_element_get", "yootheme_builder_element_delete", "yootheme_builder_element_clone", "yootheme_builder_element_move", "yootheme_builder_page_get_layout", "yootheme_builder_template_summary", "yootheme_builder_element_type_get_schema", "yootheme_builder_sites_list", "yootheme_builder_sites_test", "yootheme_builder_use_site", "yootheme_builder_pages_create", "yootheme_builder_pages_delete", "yootheme_builder_element_bind_source", "yootheme_builder_page_save", "yootheme_builder_page_publish", "yootheme_builder_page_dynamize", "yootheme_builder_scaffold_section"];
+export declare const ESSENTIAL_TOOLS: readonly ["yootheme_builder_pages_list", "yootheme_builder_pages_resolve", "yootheme_builder_get_etag", "yootheme_builder_element_list", "yootheme_builder_element_add", "yootheme_builder_element_update_settings", "yootheme_builder_sources_list", "yootheme_builder_element_types_list", "yootheme_builder_inspect_multi_items_binding", "yootheme_builder_element_get", "yootheme_builder_element_delete", "yootheme_builder_element_clone", "yootheme_builder_element_move", "yootheme_builder_page_get_layout", "yootheme_builder_template_summary", "yootheme_builder_element_type_get_schema", "yootheme_builder_sites_list", "yootheme_builder_sites_test", "yootheme_builder_use_site", "yootheme_builder_pages_create", "yootheme_builder_pages_delete", "yootheme_builder_element_bind_source", "yootheme_builder_page_save", "yootheme_builder_page_publish", "yootheme_builder_page_dynamize", "yootheme_builder_scaffold_section"];
 /**
  * L3 — Tools registered DIRECTLY on the real McpServer, BEFORE the
  * CapturingServer wraps it. The CapturingServer treats these names as a

package/dist/gateway/essentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"essentials.d.ts","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,k3BA+ElB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,mEAGzB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}
+{"version":3,"file":"essentials.d.ts","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,o5BAoFlB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,mEAGzB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/gateway/essentials.js

@@ -44,6 +44,11 @@
  */
 export const ESSENTIAL_TOOLS = [
     'yootheme_builder_pages_list',
+    // G-A (Track-C URL→layout): pages_resolve is THE core "paste a URL →
+    // reach a layout in ≤1 MCP call" tool. It MUST be L1 so a cold agent
+    // handed only a frontend URL reaches it directly (the gap fix would be
+    // moot if it were hidden behind the advanced gateway). L1 25 → 26.
+    'yootheme_builder_pages_resolve',
     'yootheme_builder_get_etag',
     'yootheme_builder_element_list',
     'yootheme_builder_element_add',

package/dist/gateway/essentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,+BAA+B;IAC/B,8BAA8B;IAC9B,0CAA0C;IAC1C,+BAA+B;IAC/B,qCAAqC;IACrC,6DAA6D;IAC7D,kEAAkE;IAClE,6DAA6D;IAC7D,yCAAyC;IACzC,8CAA8C;IAC9C,iEAAiE;IACjE,4DAA4D;IAC5D,mEAAmE;IACnE,iEAAiE;IACjE,sEAAsE;IACtE,qEAAqE;IACrE,8BAA8B;IAC9B,iCAAiC;IACjC,gCAAgC;IAChC,+BAA+B;IAC/B,kCAAkC;IAClC,oEAAoE;IACpE,sEAAsE;IACtE,mCAAmC;IACnC,iEAAiE;IACjE,iEAAiE;IACjE,iEAAiE;IACjE,4DAA4D;IAC5D,4DAA4D;IAC5D,0CAA0C;IAC1C,mEAAmE;IACnE,oEAAoE;IACpE,mEAAmE;IACnE,kEAAkE;IAClE,uEAAuE;IACvE,6BAA6B;IAC7B,6BAA6B;IAC7B,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,8DAA8D;IAC9D,+BAA+B;IAC/B,2BAA2B;IAC3B,oEAAoE;IACpE,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,kCAAkC;IAClC,+BAA+B;IAC/B,+BAA+B;IAC/B,8EAA8E;IAC9E,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,oEAAoE;IACpE,yEAAyE;IACzE,kEAAkE;IAClE,yCAAyC;IACzC,sCAAsC;IACtC,4BAA4B;IAC5B,+BAA+B;IAC/B,sEAAsE;IACtE,wEAAwE;IACxE,oEAAoE;IACpE,qEAAqE;IACrE,kEAAkE;IAClE,oEAAoE;IACpE,gCAAgC;IAChC,wEAAwE;IACxE,oEAAoE;IACpE,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,qEAAqE;IACrE,mCAAmC;CAC7B,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,yBAAyB;IACzB,2BAA2B;CACrB,CAAC;AAKX,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IACzC,OAAQ,sBAA4C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC"}
+{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,6BAA6B;IAC7B,qEAAqE;IACrE,qEAAqE;IACrE,uEAAuE;IACvE,mEAAmE;IACnE,gCAAgC;IAChC,2BAA2B;IAC3B,+BAA+B;IAC/B,8BAA8B;IAC9B,0CAA0C;IAC1C,+BAA+B;IAC/B,qCAAqC;IACrC,6DAA6D;IAC7D,kEAAkE;IAClE,6DAA6D;IAC7D,yCAAyC;IACzC,8CAA8C;IAC9C,iEAAiE;IACjE,4DAA4D;IAC5D,mEAAmE;IACnE,iEAAiE;IACjE,sEAAsE;IACtE,qEAAqE;IACrE,8BAA8B;IAC9B,iCAAiC;IACjC,gCAAgC;IAChC,+BAA+B;IAC/B,kCAAkC;IAClC,oEAAoE;IACpE,sEAAsE;IACtE,mCAAmC;IACnC,iEAAiE;IACjE,iEAAiE;IACjE,iEAAiE;IACjE,4DAA4D;IAC5D,4DAA4D;IAC5D,0CAA0C;IAC1C,mEAAmE;IACnE,oEAAoE;IACpE,mEAAmE;IACnE,kEAAkE;IAClE,uEAAuE;IACvE,6BAA6B;IAC7B,6BAA6B;IAC7B,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,8DAA8D;IAC9D,+BAA+B;IAC/B,2BAA2B;IAC3B,oEAAoE;IACpE,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,kCAAkC;IAClC,+BAA+B;IAC/B,+BAA+B;IAC/B,8EAA8E;IAC9E,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,oEAAoE;IACpE,yEAAyE;IACzE,kEAAkE;IAClE,yCAAyC;IACzC,sCAAsC;IACtC,4BAA4B;IAC5B,+BAA+B;IAC/B,sEAAsE;IACtE,wEAAwE;IACxE,oEAAoE;IACpE,qEAAqE;IACrE,kEAAkE;IAClE,oEAAoE;IACpE,gCAAgC;IAChC,wEAAwE;IACxE,oEAAoE;IACpE,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,qEAAqE;IACrE,mCAAmC;CAC7B,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,yBAAyB;IACzB,2BAA2B;CACrB,CAAC;AAKX,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IACzC,OAAQ,sBAA4C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EACH,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EACH,eAAe,EACf,sBAAsB,EACtB,WAAW,EACX,gBAAgB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACH,yBAAyB,EACzB,QAAQ,EACR,KAAK,aAAa,GACrB,MAAM,2BAA2B,CAAC;AAEnC,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiFnC;AAkBD,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EACH,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EACH,eAAe,EACf,sBAAsB,EACtB,WAAW,EACX,gBAAgB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACH,yBAAyB,EACzB,QAAQ,EACR,KAAK,aAAa,GACrB,MAAM,2BAA2B,CAAC;AAEnC,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiHnC;AAkBD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/index.js

@@ -14,6 +14,11 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { isTestMode, loadRegistry } from './auth.js';
 import { ConfigError } from './errors.js';
+import { installGlobalProxyDispatcher } from './net/proxy-dispatcher.js';
+import { SERVER_VERSION } from './server.js';
+import { checkForUpdate, formatUpdateNotice } from './update/update-check.js';
+/** npm package name — used by the startup update-notice + the diagnose tool. */
+const MCP_PACKAGE_NAME = '@wootsup/yt-builder-mcp';
 import { bootstrapActiveSite } from './sites/bootstrap.js';
 import { ClientPool } from './sites/client-pool.js';
 import { SiteRegistry } from './sites/registry.js';
@@ -36,6 +41,36 @@ export { CapturingServer, } from './gateway/capturing-server.js';
 export { registerAdvancedTool } from './gateway/advanced-tool.js';
 export { collectAllRegisteredTools, findTool, } from './gateway/test-support.js';
 async function main() {
+    // Honor an enterprise HTTP(S)_PROXY / NO_PROXY before any outbound call —
+    // BOTH proxy mode (below) and fat mode use Node's global fetch, which reads
+    // this global dispatcher. Unconditional + passthrough-safe (no proxy env =
+    // direct). Also auto-derives NO_PROXY for an internal site host (gap #9).
+    // See net/proxy-dispatcher.ts.
+    installGlobalProxyDispatcher();
+    // Gap #14 — surface any YTB_MCP_EXTRA_HEADERS parse warnings ONCE at startup
+    // (dropped lines / a forbidden Authorization key) so a misconfigured corp
+    // header isn't silently ignored. stderr only — stdout is the JSON-RPC channel.
+    if (!isTestMode()) {
+        const { parseExtraHeaders } = await import('./net/extra-headers.js');
+        for (const w of parseExtraHeaders().warnings) {
+            process.stderr.write(`[yt-builder-mcp] ${w}\n`);
+        }
+    }
+    // Update notice (non-blocking, cached 24h, fail-silent) — surfaces a newer
+    // npm version to stderr without ever delaying serving or breaking behind a
+    // corporate proxy. Skipped in test-mode (the smoke probe must not hit the
+    // network). stderr only — stdout is the JSON-RPC channel.
+    if (!isTestMode()) {
+        void checkForUpdate({ currentVersion: SERVER_VERSION, packageName: MCP_PACKAGE_NAME })
+            .then((status) => {
+            const notice = formatUpdateNotice(status);
+            if (notice !== null)
+                console.error(notice);
+        })
+            .catch(() => {
+            /* fail-silent — the notifier is a courtesy, never a dependency */
+        });
+    }
     // Proxy mode: forward stdio 1:1 to the plugin-served PHP MCP endpoint and
     // stop here — the fat catalog below is bypassed entirely. Default (fat) is
     // unchanged. The dynamic import is gated on the env so the fat path never

package/dist/index.js.map

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

package/dist/install-skill.d.ts

@@ -8,7 +8,7 @@
  * Idempotent: re-running overwrites existing skill files and skips the
  * AGENTS.md append when the marker is already present.
  *
- * Mirrors the pattern from `@wootsup/mcp install-skill` so users on both
+ * Mirrors the pattern from `@wootsup/apimapper-mcp install-skill` so users on both
  * products get the same workflow.
  *
  * @license MIT

package/dist/install-skill.js

@@ -8,7 +8,7 @@
  * Idempotent: re-running overwrites existing skill files and skips the
  * AGENTS.md append when the marker is already present.
  *
- * Mirrors the pattern from `@wootsup/mcp install-skill` so users on both
+ * Mirrors the pattern from `@wootsup/apimapper-mcp install-skill` so users on both
  * products get the same workflow.
  *
  * @license MIT

package/dist/net/extra-headers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` into a header map that is merged into EVERY
+ * outbound request on BOTH transports (fat-mode {@link RestClient} and
+ * proxy-mode `StreamableHTTPClientTransport`).
+ *
+ * Why this exists (Glöckle gap #14): a WordPress/Joomla site fronted by HTTP
+ * Basic-Auth, a WAF cookie, or a custom required header (e.g. a corporate
+ * gateway secret) cannot be reached — the only header we ever send is
+ * `Authorization: Bearer …`. This env var lets the operator attach the extra
+ * header(s) the gateway demands WITHOUT us inventing per-provider knobs.
+ *
+ * ── Accepted formats (auto-detected) ───────────────────────────────────────
+ * The value is read as ONE of two shapes, in this precedence:
+ *
+ *   1. **JSON object** — `{"X-WAF-Token":"abc","Cookie":"sid=42"}`.
+ *      Used when the trimmed value starts with `{` AND parses as a non-array
+ *      object. Non-string values are coerced via String(); null/array values
+ *      are dropped (with a warning).
+ *
+ *   2. **`Name: value` lines** — one header per line, first `:` splits:
+ *
+ *          X-WAF-Token: abc
+ *          Cookie: sid=42
+ *
+ *      Blank lines and lines starting with `#` (comments) are ignored. A line
+ *      with no `:` is dropped with a warning.
+ *
+ * ── Hard invariants ─────────────────────────────────────────────────────────
+ *   - **`Authorization` can NEVER be set here.** Any `Authorization` key (case-
+ *     insensitive) in the parsed map is dropped with a warning — the Bearer is
+ *     owned by the auth layer and an extra header must never overwrite it. This
+ *     is the parse-side half of "Bearer always wins"; the merge-side half lives
+ *     in {@link mergeExtraHeaders}.
+ *   - Empty header NAMES are dropped. Empty VALUES are kept (a deliberately
+ *     blank header is a legitimate, if rare, gateway requirement).
+ *
+ * Pure + deterministic. `warn` collects non-fatal issues; the caller decides
+ * whether to surface them (the server logs them once to stderr at startup).
+ *
+ * @license MIT
+ */
+/** Canonical env-var name for the extra-headers feature. */
+export declare const ENV_EXTRA_HEADERS = "YTB_MCP_EXTRA_HEADERS";
+export interface ParsedExtraHeaders {
+    /** The accepted header map (never contains `Authorization`). */
+    readonly headers: Record<string, string>;
+    /** Non-fatal issues (dropped lines, forbidden keys, bad JSON shape). */
+    readonly warnings: readonly string[];
+}
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` from `env` (default `process.env`). Returns an
+ * empty map (no warnings) when the var is unset/blank.
+ */
+export declare function parseExtraHeaders(env?: NodeJS.ProcessEnv): ParsedExtraHeaders;
+/**
+ * Merge extra headers UNDER an existing header set so the caller's headers
+ * (which always include `Authorization: Bearer …`) win on collision. Extra
+ * headers fill gaps; they never overwrite. Case-insensitive collision check so
+ * a `authorization` extra can never shadow a real `Authorization`.
+ *
+ * @param base   Authoritative headers (Bearer, Accept, Content-Type, If-Match…).
+ * @param extra  Parsed extra headers to merge underneath `base`.
+ * @returns A fresh record; inputs are not mutated.
+ */
+export declare function mergeExtraHeaders(base: Record<string, string>, extra: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=extra-headers.d.ts.map

package/dist/net/extra-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra-headers.d.ts","sourceRoot":"","sources":["../../src/net/extra-headers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,0BAA0B,CAAC;AAKzD,MAAM,WAAW,kBAAkB;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAwED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAiB1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB"}

package/dist/net/extra-headers.js

@@ -0,0 +1,164 @@
+// packages/mcp/src/net/extra-headers.ts
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` into a header map that is merged into EVERY
+ * outbound request on BOTH transports (fat-mode {@link RestClient} and
+ * proxy-mode `StreamableHTTPClientTransport`).
+ *
+ * Why this exists (Glöckle gap #14): a WordPress/Joomla site fronted by HTTP
+ * Basic-Auth, a WAF cookie, or a custom required header (e.g. a corporate
+ * gateway secret) cannot be reached — the only header we ever send is
+ * `Authorization: Bearer …`. This env var lets the operator attach the extra
+ * header(s) the gateway demands WITHOUT us inventing per-provider knobs.
+ *
+ * ── Accepted formats (auto-detected) ───────────────────────────────────────
+ * The value is read as ONE of two shapes, in this precedence:
+ *
+ *   1. **JSON object** — `{"X-WAF-Token":"abc","Cookie":"sid=42"}`.
+ *      Used when the trimmed value starts with `{` AND parses as a non-array
+ *      object. Non-string values are coerced via String(); null/array values
+ *      are dropped (with a warning).
+ *
+ *   2. **`Name: value` lines** — one header per line, first `:` splits:
+ *
+ *          X-WAF-Token: abc
+ *          Cookie: sid=42
+ *
+ *      Blank lines and lines starting with `#` (comments) are ignored. A line
+ *      with no `:` is dropped with a warning.
+ *
+ * ── Hard invariants ─────────────────────────────────────────────────────────
+ *   - **`Authorization` can NEVER be set here.** Any `Authorization` key (case-
+ *     insensitive) in the parsed map is dropped with a warning — the Bearer is
+ *     owned by the auth layer and an extra header must never overwrite it. This
+ *     is the parse-side half of "Bearer always wins"; the merge-side half lives
+ *     in {@link mergeExtraHeaders}.
+ *   - Empty header NAMES are dropped. Empty VALUES are kept (a deliberately
+ *     blank header is a legitimate, if rare, gateway requirement).
+ *
+ * Pure + deterministic. `warn` collects non-fatal issues; the caller decides
+ * whether to surface them (the server logs them once to stderr at startup).
+ *
+ * @license MIT
+ */
+/** Canonical env-var name for the extra-headers feature. */
+export const ENV_EXTRA_HEADERS = 'YTB_MCP_EXTRA_HEADERS';
+/** Header names that may never be supplied via the extra-headers env var. */
+const FORBIDDEN_HEADER_NAMES = new Set(['authorization']);
+/** Is `name` a header we refuse to let the env var set? Case-insensitive. */
+function isForbidden(name) {
+    return FORBIDDEN_HEADER_NAMES.has(name.trim().toLowerCase());
+}
+/** Coerce a JSON value to a string, or null when it cannot sanely become one. */
+function coerceValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return null;
+}
+/** Parse the JSON-object form. Returns null when `raw` is not a JSON object. */
+function parseJsonObject(raw, warnings) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        const name = key.trim();
+        if (name === '') {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped an entry with an empty header name.`);
+            continue;
+        }
+        if (isForbidden(name)) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: "${name}" is ignored — the Bearer token is set automatically and can never be overridden here.`);
+            continue;
+        }
+        const coerced = coerceValue(value);
+        if (coerced === null) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped header "${name}" — its value is not a string/number/boolean.`);
+            continue;
+        }
+        out[name] = coerced;
+    }
+    return out;
+}
+/** Parse the `Name: value` line form. */
+function parseLines(raw, warnings) {
+    const out = {};
+    for (const lineRaw of raw.split(/\r?\n/)) {
+        const line = lineRaw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const idx = line.indexOf(':');
+        if (idx < 0) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped line with no ":" separator — "${line}".`);
+            continue;
+        }
+        const name = line.slice(0, idx).trim();
+        const value = line.slice(idx + 1).trim();
+        if (name === '') {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped a line with an empty header name.`);
+            continue;
+        }
+        if (isForbidden(name)) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: "${name}" is ignored — the Bearer token is set automatically and can never be overridden here.`);
+            continue;
+        }
+        out[name] = value;
+    }
+    return out;
+}
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` from `env` (default `process.env`). Returns an
+ * empty map (no warnings) when the var is unset/blank.
+ */
+export function parseExtraHeaders(env = process.env) {
+    const raw = (env[ENV_EXTRA_HEADERS] ?? '').trim();
+    if (raw === '') {
+        return { headers: {}, warnings: [] };
+    }
+    const warnings = [];
+    // JSON-object form wins when the value looks like an object literal.
+    if (raw.startsWith('{')) {
+        const obj = parseJsonObject(raw, warnings);
+        if (obj !== null) {
+            return { headers: obj, warnings };
+        }
+        // Looked like JSON but didn't parse — fall back to line-parsing rather
+        // than silently dropping everything, and say so.
+        warnings.push(`${ENV_EXTRA_HEADERS}: value started with "{" but is not valid JSON — falling back to "Name: value" line parsing.`);
+    }
+    return { headers: parseLines(raw, warnings), warnings };
+}
+/**
+ * Merge extra headers UNDER an existing header set so the caller's headers
+ * (which always include `Authorization: Bearer …`) win on collision. Extra
+ * headers fill gaps; they never overwrite. Case-insensitive collision check so
+ * a `authorization` extra can never shadow a real `Authorization`.
+ *
+ * @param base   Authoritative headers (Bearer, Accept, Content-Type, If-Match…).
+ * @param extra  Parsed extra headers to merge underneath `base`.
+ * @returns A fresh record; inputs are not mutated.
+ */
+export function mergeExtraHeaders(base, extra) {
+    const lowerBaseKeys = new Set(Object.keys(base).map((k) => k.toLowerCase()));
+    const merged = {};
+    // Extra first, so a same-name base key overwrites it below.
+    for (const [name, value] of Object.entries(extra)) {
+        // Never let an extra header shadow a base header (esp. Authorization).
+        if (lowerBaseKeys.has(name.toLowerCase()))
+            continue;
+        merged[name] = value;
+    }
+    for (const [name, value] of Object.entries(base)) {
+        merged[name] = value;
+    }
+    return merged;
+}
+//# sourceMappingURL=extra-headers.js.map

package/dist/net/extra-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra-headers.js","sourceRoot":"","sources":["../../src/net/extra-headers.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;AAS/E,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAAY;IAC7B,OAAO,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,gFAAgF;AAChF,SAAS,eAAe,CAAC,GAAW,EAAE,QAAkB;IACpD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAiC,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,+CAA+C,CAAC,CAAC;YACnF,SAAS;QACb,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,MAAM,IAAI,wFAAwF,CAAC,CAAC;YACtI,SAAS;QACb,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,qBAAqB,IAAI,+CAA+C,CAAC,CAAC;YAC5G,SAAS;QACb,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,yCAAyC;AACzC,SAAS,UAAU,CAAC,GAAW,EAAE,QAAkB;IAC/C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,2CAA2C,IAAI,IAAI,CAAC,CAAC;YACvF,SAAS;QACb,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,6CAA6C,CAAC,CAAC;YACjF,SAAS;QACb,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,MAAM,IAAI,wFAAwF,CAAC,CAAC;YACtI,SAAS;QACb,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,qEAAqE;IACrE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACf,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;QACtC,CAAC;QACD,uEAAuE;QACvE,iDAAiD;QACjD,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,8FAA8F,CAAC,CAAC;IACtI,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC7B,IAA4B,EAC5B,KAA6B;IAE7B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,4DAA4D;IAC5D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,uEAAuE;QACvE,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QACpD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}