@wootsup/yt-builder-mcp 1.4.1 → 1.6.0

package/dist/clients/zed.js.map

@@ -1 +1 @@
-{"version":3,"file":"zed.js","sourceRoot":"","sources":["../../src/clients/zed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EACH,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GAGtB,MAAM,YAAY,CAAC;AAEpB,SAAS,UAAU;IACf,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAiB;IACnC,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,KAAK;IACZ,UAAU;IACV,UAAU,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAChE,KAAK,EAAE,KAAK,EAAE,UAAkB,EAAE,MAAuB,EAAE,EAAE;QACzD,MAAM,aAAa,CAAC,UAAU,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE;YAC1C,MAAM,OAAO,GACT,OAAO,CAAC,eAAe,KAAK,IAAI;gBAChC,OAAO,OAAO,CAAC,eAAe,KAAK,QAAQ;gBAC3C,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC;gBACnC,CAAC,CAAC,EAAE,GAAI,OAAO,CAAC,eAA2C,EAAE;gBAC7D,CAAC,CAAC,EAAE,CAAC;YACb,OAAO,CAAC,UAAU,CAAC,GAAG;gBAClB,OAAO,EAAE;oBACL,IAAI,EAAE,MAAM,CAAC,OAAO;oBACpB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,GAAG,EAAE,MAAM,CAAC,GAAG;iBAClB;gBACD,QAAQ,EAAE,EAAE;aACf,CAAC;YACF,OAAO,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;QACpD,CAAC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,iBAAiB,CAAC;IAChE,MAAM,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,UAAU,EAAE,EAAE,iBAAiB,CAAC;CACrE,CAAC"}
+{"version":3,"file":"zed.js","sourceRoot":"","sources":["../../src/clients/zed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EACH,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,mBAAmB,GAGtB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,OAAO,GAAI,KAAiC,CAAC,OAAO,CAAC;IAC3D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAQ,OAAmC,CAAC,GAAG,CAAC;AACpD,CAAC;AAED,SAAS,UAAU;IACf,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAiB;IACnC,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,KAAK;IACZ,UAAU;IACV,UAAU,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAChE,KAAK,EAAE,KAAK,EAAE,UAAkB,EAAE,MAAuB,EAAE,EAAE;QACzD,MAAM,aAAa,CAAC,UAAU,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE;YAC1C,MAAM,OAAO,GACT,OAAO,CAAC,eAAe,KAAK,IAAI;gBAChC,OAAO,OAAO,CAAC,eAAe,KAAK,QAAQ;gBAC3C,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC;gBACnC,CAAC,CAAC,EAAE,GAAI,OAAO,CAAC,eAA2C,EAAE;gBAC7D,CAAC,CAAC,EAAE,CAAC;YACb,+DAA+D;YAC/D,kEAAkE;YAClE,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;YAClD,OAAO,CAAC,UAAU,CAAC,GAAG;gBAClB,OAAO,EAAE;oBACL,IAAI,EAAE,MAAM,CAAC,OAAO;oBACpB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,GAAG,EAAE,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;iBAC5C;gBACD,QAAQ,EAAE,EAAE;aACf,CAAC;YACF,OAAO,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;QACpD,CAAC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,iBAAiB,CAAC;IAChE,MAAM,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,UAAU,EAAE,EAAE,iBAAiB,CAAC;CACrE,CAAC"}

package/dist/diagnostics/doctor.d.ts

@@ -22,20 +22,54 @@ export interface DoctorConfig {
     readonly currentVersion: string;
     readonly packageName: string;
 }
+/**
+ * WordPress host install-readiness facts, surfaced on the **Bearer-authenticated**
+ * `/health` payload (Task 2.1/2.2b PHP side). These diagnose the "some files
+ * could not be copied" install-failure class — the Glöckle stress-test failure
+ * where a non-`direct` filesystem transport silently blocks plugin
+ * updates/uninstalls. Mirrors the canonical PHP shape in
+ * `src/modules/rest-bridge/src/HealthController::collectHostCompat()`.
+ */
+export interface HostCompat {
+    /** WP filesystem transport: 'direct' | 'ftpext' | 'ssh2' | ''. 'direct' = PHP writes files itself. */
+    readonly fs_method: string;
+    /** Whether the plugin-dir owner matches the web-server user; null when undeterminable (no posix). */
+    readonly plugin_dir_owner_matches_web_user: boolean | null;
+    /** Whether OPcache is on (stale bytecode can linger after an in-place .php overwrite). */
+    readonly opcache_enabled: boolean;
+    /** Whether PHP can write into the plugin directory at all. */
+    readonly plugin_dir_writable: boolean;
+}
 export interface DoctorDeps {
-    /** Probe `<url>/wp-json/yt-builder-mcp/v1/health`. */
+    /**
+     * Probe `<url>/wp-json/yt-builder-mcp/v1/health` (then the Joomla path).
+     * When a bearer token is available the probe authenticates, so the success
+     * return can carry the {@link HostCompat} `host` block (authed-tier only —
+     * without a token `host` is simply undefined and the doctor still reports
+     * reachability + plugin version, no regression).
+     */
     probeHealth: (url: string) => Promise<{
         ok: true;
         pluginVersion?: string;
+        host?: HostCompat;
     } | {
         ok: false;
         error: unknown;
     }>;
-    /** Probe an authenticated endpoint with the bearer. */
+    /**
+     * Probe an authenticated endpoint with the bearer.
+     *
+     * P0.5 (U2): when the probe can observe the server's coarse `token_scope`
+     * (the authenticated /health payload carries it), it returns `tokenScope`
+     * so the doctor can report a "Bearer scope" row — a read-only key is a valid
+     * key that nonetheless cannot WRITE, which the bearer-validity check alone
+     * would not surface. Optional for back-compat (older probes / tests omit it).
+     */
     probeBearer: (url: string, token: string) => Promise<{
         ok: boolean;
         status?: number;
         error?: unknown;
+        tokenScope?: 'read' | 'write';
     }>;
     /** Latest version on npm, or null. */
     fetchLatest: (packageName: string) => Promise<string | null>;
@@ -51,7 +85,31 @@ export interface DoctorDeps {
         ok: boolean;
         error?: unknown;
     }>;
+    /**
+     * Task 2.3 pre-install mode — probe the platform REST ROOT (`/wp-json/`)
+     * reachability, independent of the plugin endpoint. Optional (back-compat).
+     * When `/health` 404s (plugin not installed yet) but the REST root IS
+     * reachable, the doctor downgrades reachability to an advisory "plugin not
+     * yet installed" hint (exit 0) instead of a hard failure — the operator
+     * very likely hit an install-upload failure (FS_METHOD / ownership / FTP).
+     */
+    probeRestRoot?: (url: string) => Promise<{
+        ok: boolean;
+        error?: unknown;
+    }>;
 }
+/**
+ * Validate an **already-peeled** value as {@link HostCompat} — the single source
+ * of truth for the host-compat shape. Both validation boundaries call this:
+ *   • the network boundary (`parseHost` in doctor-command.ts peels `body.host`
+ *     off the wire response, then delegates here), and
+ *   • the consumption boundary (`runDoctor` re-validates `health.host` so a
+ *     directly injected / future probe can't feed it a malformed host).
+ * Keeping the shape check in one place means a future `HostCompat` field can't
+ * be validated in one boundary but silently skipped in the other. A
+ * partial/typo'd bag is discarded (treated as absent), never crashed on.
+ */
+export declare function asHostCompat(value: unknown): HostCompat | undefined;
 /**
  * Run the self-diagnostic. Pure decision core — all network probes are
  * injected via {@link DoctorDeps}, so the logic is fully testable offline.

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

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

package/dist/diagnostics/doctor.js

@@ -19,6 +19,110 @@ function meetsFloor(v, floor) {
 function proxyOf(env) {
     return env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy ?? null;
 }
+/**
+ * Validate an **already-peeled** value as {@link HostCompat} — the single source
+ * of truth for the host-compat shape. Both validation boundaries call this:
+ *   • the network boundary (`parseHost` in doctor-command.ts peels `body.host`
+ *     off the wire response, then delegates here), and
+ *   • the consumption boundary (`runDoctor` re-validates `health.host` so a
+ *     directly injected / future probe can't feed it a malformed host).
+ * Keeping the shape check in one place means a future `HostCompat` field can't
+ * be validated in one boundary but silently skipped in the other. A
+ * partial/typo'd bag is discarded (treated as absent), never crashed on.
+ */
+export function asHostCompat(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    const owner = v.plugin_dir_owner_matches_web_user;
+    if (typeof v.fs_method !== 'string')
+        return undefined;
+    if (!(owner === null || typeof owner === 'boolean'))
+        return undefined;
+    if (typeof v.opcache_enabled !== 'boolean')
+        return undefined;
+    if (typeof v.plugin_dir_writable !== 'boolean')
+        return undefined;
+    return {
+        fs_method: v.fs_method,
+        plugin_dir_owner_matches_web_user: owner,
+        opcache_enabled: v.opcache_enabled,
+        plugin_dir_writable: v.plugin_dir_writable,
+    };
+}
+/** Read a numeric `.status` off a health-probe error (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;
+}
+/** Manual FS_METHOD guidance — the copy-pasteable fix for the Glöckle install-failure class. */
+const FS_METHOD_FIX = "plugin updates/uninstalls need FTP credentials or define('FS_METHOD','direct') in wp-config.php so PHP writes files directly.";
+/**
+ * Append the "Host readiness" checks for a {@link HostCompat} block (authed
+ * /health only). One line per fact with an actionable hint; warnings are
+ * tolerated (they never fail the doctor).
+ */
+function pushHostChecks(checks, host) {
+    // fs_method — the Glöckle class. Non-'direct' transports (ftpext/ssh2)
+    // mean WordPress can't write plugin files itself on an upgrade/uninstall.
+    if (host.fs_method === 'direct') {
+        checks.push({ name: 'host_fs_method', label: 'Host · FS method', status: 'ok', detail: "FS_METHOD=direct — PHP writes files directly." });
+    }
+    else {
+        const method = host.fs_method === '' ? '(unset)' : host.fs_method;
+        checks.push({
+            name: 'host_fs_method',
+            label: 'Host · FS method',
+            status: 'warn',
+            detail: `FS_METHOD=${method} — ${FS_METHOD_FIX}`,
+            fix: `FS_METHOD=${method} → ${FS_METHOD_FIX}`,
+        });
+    }
+    // plugin_dir_owner_matches_web_user — a mismatch can block file ops.
+    if (host.plugin_dir_owner_matches_web_user === false) {
+        checks.push({
+            name: 'host_owner',
+            label: 'Host · Dir ownership',
+            status: 'warn',
+            detail: 'Plugin-dir owner does not match the web-server user — file ops (update/uninstall) may be blocked.',
+            fix: 'chown the plugin directory to the web-server user (e.g. www-data), or fix the upload via FTP credentials.',
+        });
+    }
+    else if (host.plugin_dir_owner_matches_web_user === true) {
+        checks.push({ name: 'host_owner', label: 'Host · Dir ownership', status: 'ok', detail: 'Plugin-dir owner matches the web-server user.' });
+    }
+    else {
+        checks.push({ name: 'host_owner', label: 'Host · Dir ownership', status: 'info', detail: 'Ownership could not be determined on this host.' });
+    }
+    // plugin_dir_writable — can PHP write into the plugin directory at all.
+    if (host.plugin_dir_writable) {
+        checks.push({ name: 'host_writable', label: 'Host · Dir writable', status: 'ok', detail: 'Plugin directory is writable.' });
+    }
+    else {
+        checks.push({
+            name: 'host_writable',
+            label: 'Host · Dir writable',
+            status: 'warn',
+            detail: 'Plugin directory is NOT writable — updates/uninstalls will fail.',
+            fix: 'Grant the web-server user write access to the plugin directory, or use FTP credentials for file ops.',
+        });
+    }
+    // opcache_enabled — informational, surfaced ONLY when enabled (the
+    // stale-bytecode-after-upgrade hint per the brief). When OPcache is off
+    // there is nothing to warn about, so we emit no line (no noise).
+    if (host.opcache_enabled) {
+        checks.push({
+            name: 'host_opcache',
+            label: 'Host · OPcache',
+            status: 'info',
+            detail: 'OPcache is enabled — after an in-place upgrade, reload PHP-FPM (or flush OPcache) so old bytecode does not linger.',
+        });
+    }
+}
 /**
  * Run the self-diagnostic. Pure decision core — all network probes are
  * injected via {@link DoctorDeps}, so the logic is fully testable offline.
@@ -69,22 +173,84 @@ export async function runDoctor(config, deps) {
                 status: 'ok',
                 detail: health.pluginVersion !== undefined ? `OK — plugin ${health.pluginVersion}` : 'OK',
             });
+            // 4b. Host readiness — only present on the authed payload (with a
+            // token). Absent host = no token / pre-install → no host section,
+            // no failure. Validate at consumption (a malformed bag is ignored).
+            const host = asHostCompat(health.host);
+            if (host !== undefined) {
+                pushHostChecks(checks, host);
+            }
         }
         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.',
-            });
+            // Task 2.3 — pre-install mode. A 404 means the plugin endpoint is
+            // not there (plugin not installed at this URL). If the platform
+            // REST ROOT is still reachable, the site is up and the upload very
+            // likely failed (FS_METHOD / ownership / FTP) — surface advisory
+            // guidance and DO NOT fail the doctor.
+            const healthStatus = statusOf(health.error);
+            const restRoot = healthStatus === 404 && deps.probeRestRoot !== undefined ? await deps.probeRestRoot(url) : null;
+            // `restRoot.ok` reflects the same `< 500` "REST surface is up"
+            // boundary as `probeRestRoot` (doctor-command.ts): any < 500 means
+            // the host answered, so the site is live and only the plugin is
+            // missing → advisory pre-install. A 5xx site is NOT "up" for install
+            // purposes, so the probe reports not-ok and we hard-fail below (this
+            // is reachability triage, not a pre-install case).
+            if (healthStatus === 404 && restRoot !== null && restRoot.ok) {
+                checks.push({
+                    name: 'reachability',
+                    label: 'Plugin reachable',
+                    status: 'info',
+                    detail: 'Plugin /health not found (HTTP 404), but the REST root is reachable.',
+                });
+                checks.push({
+                    name: 'preinstall',
+                    label: 'Pre-install',
+                    status: 'info',
+                    detail: 'Plugin not yet installed at this URL — the REST root responded, so the site is up. ' +
+                        'If the plugin ZIP upload failed, this is the install-readiness check.',
+                    fix: 'Check FS_METHOD (a non-direct transport blocks the file copy) / plugin-dir ownership / FTP credentials. ' +
+                        `Manual fix: ${FS_METHOD_FIX}`,
+                });
+            }
+            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.' });
+                // P0.5 (U2) — Bearer SCOPE, distinct from bearer VALIDITY. A
+                // read-only key is accepted (✓ above) yet cannot perform any
+                // write tool — the doctor must surface that BEFORE the customer
+                // hits a confusing mid-wizard failure. A write/admin key is ok;
+                // a read-only key is an `info` row with the regenerate-key fix;
+                // an unknown scope (pre-U2 server) emits no row (no noise).
+                if (bearer.tokenScope === 'write') {
+                    checks.push({
+                        name: 'bearer_scope',
+                        label: 'Bearer scope',
+                        status: 'ok',
+                        detail: 'write — this key can create and edit builder content.',
+                    });
+                }
+                else if (bearer.tokenScope === 'read') {
+                    checks.push({
+                        name: 'bearer_scope',
+                        label: 'Bearer scope',
+                        status: 'info',
+                        detail: 'read-only — this key can READ but every write tool will be refused.',
+                        fix: 'Regenerate a write-scoped key in YT Builder MCP → Keys, then update the token.',
+                    });
+                }
             }
             else {
                 const diag = diagnoseNetworkError(bearer.error ?? { status: bearer.status }, env);
@@ -153,7 +319,18 @@ 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', ''];
+    let hostSectionOpen = false;
     for (const c of report.checks) {
+        const isHost = c.name.startsWith('host_');
+        // Group the host-compat facts under a "Host readiness" heading so the
+        // install-readiness block reads as one unit (Task 2.3).
+        if (isHost && !hostSectionOpen) {
+            lines.push('', '  Host readiness:');
+            hostSectionOpen = true;
+        }
+        else if (!isHost && hostSectionOpen) {
+            hostSectionOpen = false;
+        }
         lines.push(`  ${GLYPH[c.status]} ${c.label}: ${c.detail}`);
         if (c.fix !== undefined)
             lines.push(`      → ${c.fix}`);

package/dist/diagnostics/doctor.js.map

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

package/dist/diagnostics/startup-self-probe.d.ts

@@ -0,0 +1,39 @@
+/** A bounded TLS reachability probe of `url`. Resolves on any HTTP response
+ * (including 4xx/5xx — the TLS handshake succeeded), rejects on a transport
+ * failure (CA-trust, DNS, timeout, refused). */
+export type TlsProbe = (url: string, timeoutMs: number) => Promise<void>;
+export interface SelfProbeResult {
+    /** True → a TLS chain-of-trust failure was detected; the caller must exit. */
+    readonly caTrustFailure: boolean;
+    /** The actionable stderr message to print when `caTrustFailure` is true. */
+    readonly message?: string;
+}
+/** Default bound for the startup probe — short enough to beat the host's ~30s
+ * connect-timeout with wide margin, long enough for a real corporate proxy. */
+export declare const DEFAULT_SELF_PROBE_TIMEOUT_MS = 4000;
+/**
+ * The default probe: a bounded `fetch` (HEAD) of `url` with an AbortController
+ * timeout. Resolves on ANY response (the handshake completed); the only thing we
+ * care about is whether the connection rejects with a CA-trust error, which
+ * surfaces as a rejected promise whose `.cause` chain carries the TLS code.
+ */
+export declare const defaultTlsProbe: TlsProbe;
+/**
+ * Build the actionable stderr message for a CA-trust startup failure. Chooses
+ * the zero-export `--use-system-ca` remedy on Node ≥ 22.15, else the
+ * `NODE_EXTRA_CA_CERTS=<pem>` remedy. Never suggests disabling verification.
+ */
+export declare function caTrustStartupMessage(siteUrl: string, nodeVersion: string): string;
+/**
+ * Run the startup TLS self-probe against `siteUrl`. Returns `{ caTrustFailure:
+ * false }` for every outcome EXCEPT a TLS chain-of-trust rejection — only that
+ * one outcome is fail-fast-worthy (everything else must still let the server
+ * boot). When `siteUrl` is empty/undefined the probe is skipped (the
+ * boot-unconfigured path must stay).
+ */
+export declare function runStartupSelfProbe(siteUrl: string | undefined, deps?: {
+    readonly probe?: TlsProbe;
+    readonly nodeVersion?: string;
+    readonly timeoutMs?: number;
+}): Promise<SelfProbeResult>;
+//# sourceMappingURL=startup-self-probe.d.ts.map

package/dist/diagnostics/startup-self-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-self-probe.d.ts","sourceRoot":"","sources":["../../src/diagnostics/startup-self-probe.ts"],"names":[],"mappings":"AA4BA;;gDAEgD;AAChD,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;+EAC+E;AAC/E,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,QAQ7B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAUlF;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,GAAE;IACF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC1B,GACP,OAAO,CAAC,eAAe,CAAC,CAoB1B"}

package/dist/diagnostics/startup-self-probe.js

@@ -0,0 +1,87 @@
+// packages/mcp/src/diagnostics/startup-self-probe.ts
+/**
+ * Startup TLS self-probe (P0.4 — fail-fast instead of a 30s /mcp hang).
+ *
+ * The Glöckle install-blocker: when the configured site sits behind a corporate
+ * TLS-inspection proxy whose root CA Node does not trust, the server opened
+ * stdio and waited — answering nothing — so the host's 30s `/mcp` connect-timeout
+ * fired with an opaque "Server disconnected" toast that "looked like an auth or
+ * server problem". The real cause (a self-signed cert in the chain) was invisible.
+ *
+ * This module sends ONE bounded HTTPS request to the configured site BEFORE the
+ * stdio transport is wired. If it rejects with a TLS chain-of-trust error
+ * (`isCaTrustError`), `main()` / the proxy bridge writes the actionable
+ * `--use-system-ca` / `NODE_EXTRA_CA_CERTS` fix to stderr and exits non-zero in
+ * < 2s — turning a silent 30s timeout into an immediate, copy-pasteable remedy.
+ * Any OTHER probe outcome (success, 401/404/5xx, DNS, plain timeout) is NOT a
+ * reason to abort: the server must still boot for those (auth can be fixed via a
+ * tool call; an unconfigured boot must stay). Never disables TLS verification.
+ *
+ * Pure + deps-injectable (the `probe` fn + `nodeVersion` + `now`) so it is
+ * unit-testable offline with no real network.
+ *
+ * @license MIT
+ */
+import { isCaTrustError, supportsSystemCa } from './ca-trust.js';
+/** Default bound for the startup probe — short enough to beat the host's ~30s
+ * connect-timeout with wide margin, long enough for a real corporate proxy. */
+export const DEFAULT_SELF_PROBE_TIMEOUT_MS = 4000;
+/**
+ * The default probe: a bounded `fetch` (HEAD) of `url` with an AbortController
+ * timeout. Resolves on ANY response (the handshake completed); the only thing we
+ * care about is whether the connection rejects with a CA-trust error, which
+ * surfaces as a rejected promise whose `.cause` chain carries the TLS code.
+ */
+export const defaultTlsProbe = async (url, timeoutMs) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        await fetch(url, { method: 'HEAD', signal: controller.signal, redirect: 'manual' });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/**
+ * Build the actionable stderr message for a CA-trust startup failure. Chooses
+ * the zero-export `--use-system-ca` remedy on Node ≥ 22.15, else the
+ * `NODE_EXTRA_CA_CERTS=<pem>` remedy. Never suggests disabling verification.
+ */
+export function caTrustStartupMessage(siteUrl, nodeVersion) {
+    const remedy = supportsSystemCa(nodeVersion)
+        ? 'set NODE_OPTIONS=--use-system-ca (Node ≥ 22.15 — reads your OS / corporate root CA store)'
+        : `set NODE_EXTRA_CA_CERTS=<path-to-corp-root-ca.pem> (this Node ${nodeVersion} is below 22.15, so --use-system-ca is unavailable)`;
+    return (`[yt-builder-mcp] fatal: self-signed cert in chain reaching ${siteUrl} — ` +
+        'a corporate TLS-inspection proxy is injecting its own root CA that Node does not trust. ' +
+        `Fix: ${remedy}, then restart your AI client. ` +
+        'Re-run `npx -y @wootsup/yt-builder-mcp setup` to bake this automatically. Never disable TLS verification.');
+}
+/**
+ * Run the startup TLS self-probe against `siteUrl`. Returns `{ caTrustFailure:
+ * false }` for every outcome EXCEPT a TLS chain-of-trust rejection — only that
+ * one outcome is fail-fast-worthy (everything else must still let the server
+ * boot). When `siteUrl` is empty/undefined the probe is skipped (the
+ * boot-unconfigured path must stay).
+ */
+export async function runStartupSelfProbe(siteUrl, deps = {}) {
+    const url = (siteUrl ?? '').trim();
+    if (url === '')
+        return { caTrustFailure: false };
+    const probe = deps.probe ?? defaultTlsProbe;
+    const nodeVersion = deps.nodeVersion ?? process.version;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_SELF_PROBE_TIMEOUT_MS;
+    try {
+        await probe(url, timeoutMs);
+        return { caTrustFailure: false };
+    }
+    catch (err) {
+        if (isCaTrustError(err)) {
+            return { caTrustFailure: true, message: caTrustStartupMessage(url, nodeVersion) };
+        }
+        // Any other failure (DNS, timeout, refused, plain abort) is NOT a
+        // boot-blocker — the server must still come up. The proxy bridge's
+        // first-frame catch already turns those into actionable JSON-RPC errors.
+        return { caTrustFailure: false };
+    }
+}
+//# sourceMappingURL=startup-self-probe.js.map

package/dist/diagnostics/startup-self-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-self-probe.js","sourceRoot":"","sources":["../../src/diagnostics/startup-self-probe.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAcjE;+EAC+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa,KAAK,EAAE,GAAW,EAAE,SAAiB,EAAiB,EAAE;IAC7F,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxF,CAAC;YAAS,CAAC;QACP,YAAY,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;AACL,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,WAAmB;IACtE,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,CAAC;QACxC,CAAC,CAAC,2FAA2F;QAC7F,CAAC,CAAC,iEAAiE,WAAW,qDAAqD,CAAC;IACxI,OAAO,CACH,8DAA8D,OAAO,KAAK;QAC1E,0FAA0F;QAC1F,QAAQ,MAAM,iCAAiC;QAC/C,2GAA2G,CAC9G,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACrC,OAA2B,EAC3B,OAII,EAAE;IAEN,MAAM,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAEjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,6BAA6B,CAAC;IAElE,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5B,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,qBAAqB,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,CAAC;QACtF,CAAC;QACD,kEAAkE;QAClE,mEAAmE;QACnE,yEAAyE;QACzE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;AACL,CAAC"}

package/dist/gateway/essentials.d.ts

@@ -15,11 +15,20 @@
  *                                 entirely (no forward, no capture) so the
  *                                 SDK never sees a duplicate registration.
  *
- * Why this split: Cursor caps MCP servers at ~40 tools. This adapter
- * declares 31 callable tools (26 domain L1/L3 + 4 advanced L2 + 1 gateway).
- * The 3-lane shape keeps `tools/list` at 24 (L1) + 2 (L3) + 1 (gateway) =
- * 27 entries, well under the cap, while every tool stays fully reachable
- * (advanced tools through `yootheme_builder_advanced`).
+ * Why this split: Cursor caps MCP servers at ~40 tools. The 3-lane shape
+ * keeps `tools/list` at 32 (L1) + 2 (L3) + 2 (gateways) = 36 entries, well
+ * under the cap, while every tool stays fully reachable (advanced tools
+ * through `yootheme_builder_advanced` / `yootheme_builder_advanced_read`).
+ * B4 (2026-06-27): element_get_binding promoted L2 → L1 (binding-read made
+ * first-class, mirroring the already-L1 element_bind_source write). L1 26 → 27.
+ * U4-L1 (Glöckle onboarding, 2026-06-27): source_get_schema promoted L2 → L1
+ * (the archive/category binding entry-point made first-class, mirroring how the
+ * bind→verify tools are already L1). L1 27 → 28.
+ * HANDOFF-4/5 L1 (Glöckle onboarding, 2026-06-28): render_preview,
+ * element_set_source, rename_source, template_set_type promoted L2 → L1 — the
+ * core write/refactor + render-verify tools the Glöckle HANDOFF-4/5 ask for,
+ * made first-class so a cold agent can discover them in tools/list (L2 was a
+ * discoverability workaround). L1 28 → 32, advanced 9 → 5.
  *
  * F116 (2026-06-11): the bind→save→publish chain (element_bind_source,
  * page_save, page_publish) was promoted from the advanced lane to L1. It is
@@ -42,7 +51,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_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"];
+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_element_get_binding", "yootheme_builder_page_dynamize", "yootheme_builder_scaffold_section", "yootheme_builder_source_get_schema", "yootheme_builder_render_preview", "yootheme_builder_element_set_source", "yootheme_builder_rename_source", "yootheme_builder_template_set_type"];
 /**
  * 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,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"}
+{"version":3,"file":"essentials.d.ts","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,onCAyHlB,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"}