@wootsup/yt-builder-mcp 1.2.0 → 1.4.0

package/dist/diagnostics/ca-trust.js

@@ -0,0 +1,54 @@
+// packages/mcp/src/diagnostics/ca-trust.ts
+/**
+ * Shared helpers for the corporate TLS-inspection (CA-trust) install path.
+ *
+ * G-D #6/#7 — two questions the wizard + CLI both need answered:
+ *   1. "Did this connection fail because of a TLS-inspection root CA?"
+ *      → {@link isCaTrustError}, classifying against the canonical
+ *        {@link CA_TRUST_CODES} (no duplicate set).
+ *   2. "Can this Node read the OS trust store natively (`--use-system-ca`)?"
+ *      → {@link supportsSystemCa}, a real numeric semver compare against the
+ *        backport floor — never a string comparison.
+ *
+ * Node's `--use-system-ca` (reads Windows CryptoAPI + macOS Keychain) was
+ * stabilised on the 24.x line and backported to 22.15.0, so the floor is
+ * 22.15.0. Below that floor, a corporate CA must be supplied as a `.pem`
+ * via NODE_EXTRA_CA_CERTS. Neither path ever disables TLS verification.
+ */
+import { CA_TRUST_CODES, collectCodes } from './diagnose-network-error.js';
+/**
+ * True when `err` (or anything in its `.cause` / `AggregateError.errors`
+ * chain) carries a TLS chain-of-trust failure code — the signature of a
+ * corporate TLS-inspection proxy injecting its own root CA. Pure; reuses the
+ * same walker + code set as {@link diagnoseNetworkError}.
+ */
+export function isCaTrustError(err) {
+    return collectCodes(err).some((c) => CA_TRUST_CODES.has(c));
+}
+/** Node version that first reads the OS trust store via `--use-system-ca`. */
+export const SYSTEM_CA_NODE_FLOOR = [22, 15, 0];
+function parseNodeVersion(v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (m === null)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/**
+ * Does `nodeVersion` (default `process.version`) support `--use-system-ca`?
+ * A real numeric triple compare against {@link SYSTEM_CA_NODE_FLOOR} —
+ * fail-closed (`false`) on unparseable input.
+ */
+export function supportsSystemCa(nodeVersion = process.version) {
+    const v = parseNodeVersion(nodeVersion);
+    if (v === null)
+        return false;
+    const floor = SYSTEM_CA_NODE_FLOOR;
+    for (let i = 0; i < 3; i++) {
+        if (v[i] > floor[i])
+            return true;
+        if (v[i] < floor[i])
+            return false;
+    }
+    return true; // exactly equal to the floor
+}
+//# sourceMappingURL=ca-trust.js.map

package/dist/diagnostics/ca-trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ca-trust.js","sourceRoot":"","sources":["../../src/diagnostics/ca-trust.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAE3C;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACvC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAsC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF,SAAS,gBAAgB,CAAC,CAAS;IAC/B,MAAM,CAAC,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB,OAAO,CAAC,OAAO;IAClE,MAAM,CAAC,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7B,MAAM,KAAK,GAAG,oBAAoB,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,CAAC,CAAE;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,CAAC,CAAE;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,6BAA6B;AAC9C,CAAC"}

package/dist/diagnostics/diagnose-network-error.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A human-actionable diagnosis of an outbound-connection failure.
+ *
+ * The Glöckle corporate stress-test failed with an opaque 30-second timeout
+ * that "looked like an auth or server problem" when the real cause was a
+ * TLS-inspection root CA. Mapping the low-level `.code` to a copy-pasteable fix
+ * is the difference between a 5-minute self-serve and a support ticket.
+ */
+export interface NetworkDiagnosis {
+    /** The matched low-level code, e.g. `SELF_SIGNED_CERT_IN_CHAIN`, `ENOTFOUND`, `HTTP_401`. */
+    readonly code: string;
+    /** One-line summary of what went wrong. */
+    readonly summary: string;
+    /** Actionable, copy-pasteable fix. NEVER suggests disabling TLS verification. */
+    readonly fix: string;
+}
+/**
+ * TLS chain-of-trust failures — the corporate-CA / TLS-inspection signature.
+ *
+ * Exported so the wizard's CA-detection path (`isCaTrustError`) classifies an
+ * outbound failure against the SAME canonical set — there is exactly one
+ * definition of "this is a TLS-inspection CA problem" in the package.
+ */
+export declare const CA_TRUST_CODES: ReadonlySet<string>;
+/**
+ * Walk `err`, its `.cause` chain, and any `AggregateError.errors`, collecting
+ * every `.code` string. A Node global-fetch failure (`TypeError: fetch failed`)
+ * hides the real TLS/socket code one or more `.cause` levels down.
+ */
+export declare function collectCodes(err: unknown, depth?: number): string[];
+/**
+ * Classify an outbound-connection failure into an actionable diagnosis, or
+ * `null` when nothing specific matches (the caller should fall back to the raw
+ * error message). Pure — `env` is injectable for tests.
+ */
+export declare function diagnoseNetworkError(err: unknown, env?: NodeJS.ProcessEnv): NetworkDiagnosis | null;
+//# sourceMappingURL=diagnose-network-error.d.ts.map

package/dist/diagnostics/diagnose-network-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose-network-error.d.ts","sourceRoot":"","sources":["../../src/diagnostics/diagnose-network-error.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAO7C,CAAC;AAmCH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAa9D;AAOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,GAAE,MAAM,CAAC,UAAwB,GACrC,gBAAgB,GAAG,IAAI,CAqFzB"}

package/dist/diagnostics/diagnose-network-error.js

@@ -0,0 +1,158 @@
+// packages/mcp/src/diagnostics/diagnose-network-error.ts
+/**
+ * TLS chain-of-trust failures — the corporate-CA / TLS-inspection signature.
+ *
+ * Exported so the wizard's CA-detection path (`isCaTrustError`) classifies an
+ * outbound failure against the SAME canonical set — there is exactly one
+ * definition of "this is a TLS-inspection CA problem" in the package.
+ */
+export const CA_TRUST_CODES = new Set([
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'SELF_SIGNED_CERT',
+    'CERT_UNTRUSTED',
+]);
+const TIMEOUT_CODES = new Set([
+    'UND_ERR_CONNECT_TIMEOUT',
+    'ETIMEDOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+const DNS_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN']);
+const CA_FIX = 'On Node ≥ 22.15, the zero-export fix is `npx -y @wootsup/yt-builder-mcp setup --use-system-ca` (Node reads your OS ' +
+    'trust store / Windows cert store / macOS Keychain). Otherwise export your corporate/proxy root CA to a .pem file and ' +
+    'set NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem in the server entry\'s env block (re-run setup with `--ca <path>`, ' +
+    'or `… doctor` to detect it), then restart your AI client. Never disable TLS verification.';
+/** Read a string `.code` off an unknown value, or null. */
+function codeOf(value) {
+    if (value !== null && typeof value === 'object' && 'code' in value) {
+        const c = value.code;
+        if (typeof c === 'string' && c !== '')
+            return c;
+    }
+    return null;
+}
+/** Read a numeric `.status` off an unknown value (RestError-like), or null. */
+function statusOf(value) {
+    if (value !== null && typeof value === 'object' && 'status' in value) {
+        const s = value.status;
+        if (typeof s === 'number' && Number.isFinite(s))
+            return s;
+    }
+    return null;
+}
+/**
+ * Walk `err`, its `.cause` chain, and any `AggregateError.errors`, collecting
+ * every `.code` string. A Node global-fetch failure (`TypeError: fetch failed`)
+ * hides the real TLS/socket code one or more `.cause` levels down.
+ */
+export function collectCodes(err, depth = 0) {
+    if (err === null || typeof err !== 'object' || depth > 6)
+        return [];
+    const codes = [];
+    const c = codeOf(err);
+    if (c !== null)
+        codes.push(c);
+    if ('cause' in err)
+        codes.push(...collectCodes(err.cause, depth + 1));
+    if ('errors' in err) {
+        const list = err.errors;
+        if (Array.isArray(list)) {
+            for (const inner of list)
+                codes.push(...collectCodes(inner, depth + 1));
+        }
+    }
+    return codes;
+}
+/** Does the environment have any forward-proxy configured? */
+function configuredProxy(env) {
+    return env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy ?? null;
+}
+/**
+ * Classify an outbound-connection failure into an actionable diagnosis, or
+ * `null` when nothing specific matches (the caller should fall back to the raw
+ * error message). Pure — `env` is injectable for tests.
+ */
+export function diagnoseNetworkError(err, env = process.env) {
+    // HTTP-status failures (RestError-like) take precedence — the request DID
+    // reach the server, so it is not a transport problem.
+    const status = statusOf(err);
+    if (status === 401 || status === 403) {
+        return {
+            code: `HTTP_${status}`,
+            summary: `The site rejected the bearer token (HTTP ${status}).`,
+            fix: 'Re-issue an MCP key in the plugin admin (YT Builder MCP → Keys) and update YTB_MCP_BEARER_TOKEN, then restart.',
+        };
+    }
+    if (status === 404) {
+        return {
+            code: 'HTTP_404',
+            summary: 'The MCP endpoint was not found (HTTP 404).',
+            fix: 'Confirm the plugin is installed + active and YTB_MCP_SITE_URL points at the site root (not wp-admin). Run `… doctor`.',
+        };
+    }
+    if (status !== null && status >= 500) {
+        return {
+            code: `HTTP_${status}`,
+            summary: `The site returned a server error (HTTP ${status}).`,
+            fix: 'Check the site\'s PHP error log; retry once it recovers. If it persists, the plugin may have crashed on this request.',
+        };
+    }
+    const codes = collectCodes(err);
+    const has = (set) => codes.find((c) => set.has(c)) ?? null;
+    const caCode = has(CA_TRUST_CODES);
+    if (caCode !== null) {
+        return {
+            code: caCode,
+            summary: 'The TLS certificate could not be verified — the signature of a corporate TLS-inspection proxy that injects its own root CA.',
+            fix: CA_FIX,
+        };
+    }
+    if (codes.includes('CERT_HAS_EXPIRED')) {
+        return {
+            code: 'CERT_HAS_EXPIRED',
+            summary: 'The TLS certificate presented for the site has expired.',
+            fix: 'Renew the site certificate. If a corporate proxy presents it, update the CA in NODE_EXTRA_CA_CERTS.',
+        };
+    }
+    const proxy = configuredProxy(env);
+    if (codes.includes('ECONNREFUSED')) {
+        return proxy !== null
+            ? {
+                code: 'ECONNREFUSED',
+                summary: `The configured proxy (${proxy}) refused the connection.`,
+                fix: `Verify HTTPS_PROXY=${proxy} is correct and reachable, and set NO_PROXY for internal hosts that must bypass it.`,
+            }
+            : {
+                code: 'ECONNREFUSED',
+                summary: 'The target host refused the connection.',
+                fix: 'Check YTB_MCP_SITE_URL is correct and the site is up and reachable from this machine.',
+            };
+    }
+    const timeoutCode = has(TIMEOUT_CODES);
+    if (timeoutCode !== null) {
+        return proxy !== null
+            ? {
+                code: timeoutCode,
+                summary: `The connection through the proxy (${proxy}) timed out.`,
+                fix: `Confirm HTTPS_PROXY=${proxy} can reach the site, and set NO_PROXY for internal hosts. Run \`… doctor\`.`,
+            }
+            : {
+                code: timeoutCode,
+                summary: 'The connection timed out.',
+                fix: 'The site may be internal (VPN needed) or require a proxy (set HTTPS_PROXY). Run `npx -y @wootsup/yt-builder-mcp doctor` to diagnose.',
+            };
+    }
+    const dnsCode = has(DNS_CODES);
+    if (dnsCode !== null) {
+        return {
+            code: dnsCode,
+            summary: 'DNS lookup failed for the site host.',
+            fix: 'Check the host in YTB_MCP_SITE_URL is spelled correctly and resolvable from this machine (VPN/DNS).',
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=diagnose-network-error.js.map

package/dist/diagnostics/diagnose-network-error.js.map

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

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/advanced-read-tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `yootheme_builder_advanced_read` — a READ-ONLY sibling of the
+ * `yootheme_builder_advanced` gateway (F200a, 2026-06-12).
+ *
+ * The Desktop-E2E #2 forensic showed approval-gates firing on EVERY advanced
+ * call. Root cause: the single `yootheme_builder_advanced` gateway is annotated
+ * `readOnlyHint:false` + `destructiveHint:true` (correctly — it can route into
+ * delete / unbind handlers), so spec-compliant MCP hosts gate it
+ * conservatively. The read-only L2 subtools (page_get_schema,
+ * element_get_binding, inspect_sublayout) inherited that gate even though they
+ * mutate nothing — a per-call approval tax on pure inspection.
+ *
+ * This second gateway WHITELISTS only read-only advanced entries (annotation
+ * `readOnlyHint:true`) and is itself annotated `readOnly()`, so hosts can
+ * auto-allow it. Writing subtools (unbind, clean-implode) stay reachable ONLY
+ * through the existing (gated) `yootheme_builder_advanced` — defense-in-depth:
+ * the read gateway physically cannot route to them (they are not in its
+ * registry view).
+ *
+ * Two modes mirror the write gateway:
+ *   { tool }            → discovery (target schema + annotations; no invoke).
+ *   { tool, arguments } → execution (strict-validated, then handler called).
+ *
+ * @license MIT
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AdvancedToolEntry } from './capturing-server.js';
+/** The pinned name — never rename (host configs + skill docs reference it). */
+export declare const ADVANCED_READ_TOOL_NAME = "yootheme_builder_advanced_read";
+/**
+ * Registers `yootheme_builder_advanced_read` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the read gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export declare function registerAdvancedReadTool(realServer: McpServer, advancedRegistry: Map<string, AdvancedToolEntry>): void;
+//# sourceMappingURL=advanced-read-tool.d.ts.map

package/dist/gateway/advanced-read-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-read-tool.d.ts","sourceRoot":"","sources":["../../src/gateway/advanced-read-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM/D,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAgExE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,SAAS,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,IAAI,CAwEN"}