@diviops/mcp-server 1.4.0 → 1.4.1

package/dist/wp-cli.d.ts

@@ -27,6 +27,10 @@ export declare function createWpCli(config: WpCliConfig): {
         success: boolean;
         output: string;
         error?: string;
+        stdout: string;
+        stderr: string;
+        exitCode: number | null;
+        failureKind?: "rejected" | "spawn_failed" | "killed" | "exited";
     }>;
     /**
      * Execute a WP-CLI command from a pre-built argv array. Skips
@@ -39,6 +43,10 @@ export declare function createWpCli(config: WpCliConfig): {
         success: boolean;
         output: string;
         error?: string;
+        stdout: string;
+        stderr: string;
+        exitCode: number | null;
+        failureKind?: "rejected" | "spawn_failed" | "killed" | "exited";
     }>;
     /** Return the list of allowed commands and available extensions. */
     getAllowedCommands(): {

package/dist/wp-cli.js

@@ -333,19 +333,18 @@ export function createWpCli(config) {
     const runOptions = customWpCliCmd
         ? { ...execOptions, env, cwd: config.wpPath }
         : { ...execOptions, env };
-    // Internal argv-based runner — used by both `run(string)` (after
-    // parseCommand) and `runArgs(string[])` (skip parseCommand). Typed
-    // wrappers should call runArgs to bypass parseCommand's quote-toggling
-    // weakness: when a value contains an apostrophe (e.g. label "Bob's
-    // Group", file path /tmp/it's-fine.json), parseCommand mis-splits the
-    // argv because it treats the embedded `'` as a quote toggle. Passing
-    // pre-built argv eliminates the parsing step entirely so user-provided
-    // strings flow through verbatim — execFile (no shell) handles them
-    // correctly. Raised in PR #473 review (Copilot/Gemini both flagged).
     const runArgv = async (args) => {
         const check = isCommandAllowed(args);
         if (!check.allowed) {
-            return { success: false, output: '', error: check.reason };
+            return {
+                success: false,
+                output: '',
+                error: check.reason,
+                stdout: '',
+                stderr: '',
+                exitCode: null,
+                failureKind: 'rejected',
+            };
         }
         // Second-pass FS validation for commands whose flags/args can read/write
         // arbitrary paths. Scoped to DEFAULT-tier FS commands only — EXTENDED
@@ -368,7 +367,15 @@ export function createWpCli(config) {
                 isWrapper: !!customWpCliCmd,
             });
             if (!fsCheck.allowed) {
-                return { success: false, output: '', error: fsCheck.reason };
+                return {
+                    success: false,
+                    output: '',
+                    error: fsCheck.reason,
+                    stdout: '',
+                    stderr: '',
+                    exitCode: null,
+                    failureKind: 'rejected',
+                };
             }
         }
         const fullArgs = customWpCliCmd
@@ -376,22 +383,71 @@ export function createWpCli(config) {
             : [...args, `--path=${config.wpPath}`, '--no-color'];
         return new Promise((resolve) => {
             execFile(executable, fullArgs, runOptions, (error, stdout, stderr) => {
-                // Filter PHP deprecation warnings from output
+                // Filter PHP deprecation warnings from the legacy concatenated
+                // `output` field; `stdout` / `stderr` siblings are kept raw so
+                // envelope adopters (meta_wp_cli passthrough, scf_* round-trip)
+                // see the unfiltered streams.
                 const output = (stdout + '\n' + stderr)
                     .split('\n')
                     .filter((line) => !line.includes('Deprecated:') && !line.includes('PHP Deprecated'))
                     .join('\n')
                     .trim();
                 if (error) {
-                    const detail = error.killed
-                        ? 'Command timed out'
-                        : error.signal
-                            ? `Killed by signal ${error.signal}`
-                            : `Exit code ${error.code ?? 'unknown'}`;
-                    resolve({ success: false, output, error: detail });
+                    // execFile callback fired with an error. Three possible
+                    // sub-cases; classifying them up-front so the handler can emit
+                    // accurate hints per cause:
+                    //
+                    //  - `error.killed === true`            → timeout (Node sets
+                    //    this when the configured `timeout` expires).
+                    //  - `error.signal != null`             → killed by signal.
+                    //  - typeof error.code === 'number'     → child ran and exited
+                    //    with a numeric exit code (the normal "exited non-zero"
+                    //    case).
+                    //  - typeof error.code === 'string' or undefined → spawn-side
+                    //    failure. ENOENT (binary missing), EACCES (not executable),
+                    //    EPERM, etc. — execFile reports these via the same error
+                    //    callback but the child never started. Distinct from
+                    //    "killed" because there's no partial output to preserve
+                    //    and the fix path is environmental (PATH, install, perms),
+                    //    not "raise the timeout."
+                    const codeRaw = error.code;
+                    const isKilled = error.killed === true || error.signal != null;
+                    const isExited = typeof codeRaw === 'number';
+                    const exitCode = isExited ? codeRaw : null;
+                    const failureKind = isKilled
+                        ? 'killed'
+                        : isExited
+                            ? 'exited'
+                            : 'spawn_failed';
+                    const detail = isKilled
+                        ? error.killed
+                            ? 'Command timed out'
+                            : `Killed by signal ${error.signal}`
+                        : isExited
+                            ? `Exit code ${codeRaw}`
+                            : // spawn_failed — surface the system errno as the detail
+                                // string ("Spawn failed: ENOENT") so the cause is visible
+                                // without parsing structured fields. Falls back to the
+                                // raw error.message when `code` is empty.
+                                `Spawn failed: ${codeRaw ?? error.message ?? 'unknown'}`;
+                    resolve({
+                        success: false,
+                        output,
+                        error: detail,
+                        stdout,
+                        stderr,
+                        exitCode,
+                        failureKind,
+                    });
                 }
                 else {
-                    resolve({ success: true, output });
+                    resolve({
+                        success: true,
+                        output,
+                        stdout,
+                        stderr,
+                        exitCode: 0,
+                    });
                 }
             });
         });

package/dist/wp-client.d.ts

@@ -5,6 +5,7 @@
  * Generate one at: WP Admin → Users → Your Profile → Application Passwords.
  */
 import { type HandshakeResult } from './compatibility.js';
+import { type DiviopsResponse } from './envelope.js';
 export interface WPClientConfig {
     siteUrl: string;
     username: string;
@@ -22,8 +23,45 @@ export declare class WPClient {
         body?: Record<string, unknown>;
         params?: Record<string, string>;
     }): Promise<T>;
+    /**
+     * Envelope-aware sibling of `request()`.
+     *
+     * Issue the same HTTP call as `request()`, but return the parsed body
+     * directly as a `DiviopsResponse<T>` without throwing on envelope errors:
+     *
+     *   - Body is an envelope (`{ok: true, data}` or `{ok: false, error}`)
+     *     → return it verbatim. Plugin-emitted error envelopes (typically
+     *     4xx with `{ok: false, error: {code, message, hint?}}`) flow back
+     *     to the caller as a typed result, not a throw.
+     *   - Response is non-2xx and body is NOT an envelope (e.g. a WP REST
+     *     framework error before the route runs, an unexpected 5xx)
+     *     → synthesize `{ok: false, error: {code: 'wp_error', message: ...}}`
+     *     so callers see a uniform shape regardless of upstream.
+     *   - Response is 2xx but body is not enveloped (legacy routes that
+     *     have not adopted yet) → wrap as `{ok: true, data: <body>}` to
+     *     preserve a single contract for adopting tools to consume.
+     *
+     * Transport errors (network, JSON parse failure on a 2xx body) still
+     * throw — those are not domain-level outcomes the envelope models.
+     *
+     * Migration: pilot's three `schema_*` tools and every subsequent
+     * namespace adoption use this method. Once the rollout completes,
+     * `request()` becomes orphan and is removed.
+     */
+    requestEnveloped<T = unknown>(endpoint: string, options?: {
+        method?: string;
+        body?: Record<string, unknown>;
+        params?: Record<string, string>;
+    }): Promise<DiviopsResponse<T>>;
     /**
      * Test the connection to WordPress.
+     *
+     * Routes through `requestEnveloped` because `/schema/settings` was
+     * envelope-adopted in the schema_* pilot — its body is now
+     * `{ ok: true, data: { builder, ... } }`. Reading
+     * `result.builder.version` against that shape (the pre-pilot pattern)
+     * silently regresses meta_ping to "Connected to Divi unknown" on
+     * healthy sites.
      */
     testConnection(): Promise<{
         ok: boolean;

package/dist/wp-client.js

@@ -4,6 +4,7 @@
  * Uses WP Application Passwords (built into WP 5.6+) for auth.
  * Generate one at: WP Admin → Users → Your Profile → Application Passwords.
  */
+import { ErrorCodes, isEnveloped, } from './envelope.js';
 /**
  * Normalize quote-escape pathologies inside `$variable(...)$` token regions only.
  *
@@ -141,15 +142,159 @@ export class WPClient {
         }
         return response.json();
     }
+    /**
+     * Envelope-aware sibling of `request()`.
+     *
+     * Issue the same HTTP call as `request()`, but return the parsed body
+     * directly as a `DiviopsResponse<T>` without throwing on envelope errors:
+     *
+     *   - Body is an envelope (`{ok: true, data}` or `{ok: false, error}`)
+     *     → return it verbatim. Plugin-emitted error envelopes (typically
+     *     4xx with `{ok: false, error: {code, message, hint?}}`) flow back
+     *     to the caller as a typed result, not a throw.
+     *   - Response is non-2xx and body is NOT an envelope (e.g. a WP REST
+     *     framework error before the route runs, an unexpected 5xx)
+     *     → synthesize `{ok: false, error: {code: 'wp_error', message: ...}}`
+     *     so callers see a uniform shape regardless of upstream.
+     *   - Response is 2xx but body is not enveloped (legacy routes that
+     *     have not adopted yet) → wrap as `{ok: true, data: <body>}` to
+     *     preserve a single contract for adopting tools to consume.
+     *
+     * Transport errors (network, JSON parse failure on a 2xx body) still
+     * throw — those are not domain-level outcomes the envelope models.
+     *
+     * Migration: pilot's three `schema_*` tools and every subsequent
+     * namespace adoption use this method. Once the rollout completes,
+     * `request()` becomes orphan and is removed.
+     */
+    async requestEnveloped(endpoint, options = {}) {
+        const { method = 'GET', body, params } = options;
+        let url = `${this.baseUrl}/wp-json/diviops/v1${endpoint}`;
+        if (params) {
+            const searchParams = new URLSearchParams(params);
+            url += `?${searchParams.toString()}`;
+        }
+        const fetchOptions = {
+            method,
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+        };
+        if (body && method !== 'GET') {
+            fetchOptions.body = JSON.stringify(normalizeBody(body));
+        }
+        const response = await fetch(url, fetchOptions);
+        const rawBody = await response.text();
+        // Try to parse the body as JSON. Failure is recoverable for non-2xx
+        // responses (HTML/plain-text error pages from a misconfigured host or
+        // upstream proxy synthesize a `wp_error` envelope rather than throwing)
+        // and is fatal only on a 2xx body that promised JSON but didn't deliver.
+        let parsed;
+        let parseError = null;
+        try {
+            parsed = rawBody === '' ? null : JSON.parse(rawBody);
+        }
+        catch (e) {
+            parseError = e;
+        }
+        if (parseError === null && isEnveloped(parsed)) {
+            return parsed;
+        }
+        if (!response.ok) {
+            // Non-2xx + body either non-JSON or non-enveloped JSON. Two sub-cases:
+            //
+            //  (1) Body is a parsed `WP_Error`-shaped JSON object — `{code, message,
+            //      data?: {status?, hint?}}`. This is what older diviops-agent
+            //      versions (pre-envelope-adoption) emit alongside `WP_Error`-based
+            //      handlers, and what the WP REST framework itself emits for
+            //      framework-level errors (`rest_forbidden`, `rest_no_route`,
+            //      `rest_invalid_param`, etc.). Promote `code` to the envelope's
+            //      `error.code` so callers running against a mixed-version
+            //      deployment (new server + older plugin emitting non-envelope
+            //      error bodies) still receive granular codes like `invalid_type`,
+            //      `not_found`, `rest_forbidden` — instead of having every legacy
+            //      4xx collapse to a generic `wp_error` and lose the upstream
+            //      slug. Hint is forwarded when present in `data.hint` (matches
+            //      the convention `envelope_from_wp_error` writes plugin-side).
+            //
+            //  (2) Body is non-JSON, or JSON without `code`/`message` (HTML/plain
+            //      error pages from a misconfigured host, host firewall pages,
+            //      502/504 from a reverse proxy, etc.) — fall back to a synthesized
+            //      `wp_error` so adopted tools still see a uniform envelope.
+            const isLegacyWpErrorBody = parseError === null &&
+                parsed !== null &&
+                typeof parsed === 'object' &&
+                typeof parsed.code === 'string' &&
+                typeof parsed.message === 'string';
+            if (isLegacyWpErrorBody) {
+                const obj = parsed;
+                const out = {
+                    code: obj.code,
+                    message: obj.message,
+                };
+                const data = obj.data;
+                if (data !== null &&
+                    typeof data === 'object' &&
+                    'hint' in data &&
+                    typeof data.hint === 'string') {
+                    out.hint = data.hint;
+                }
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('Retry-After') || '60';
+                    out.message = `${out.message} (retry after ${retryAfter}s)`;
+                }
+                return { ok: false, error: out };
+            }
+            const messageFromBody = parseError
+                ? rawBody.slice(0, 200)
+                : parsed && typeof parsed === 'object' && parsed !== null && 'message' in parsed
+                    ? String(parsed.message)
+                    : rawBody;
+            let message = `WordPress API error (${response.status}): ${messageFromBody}`;
+            if (response.status === 429) {
+                const retryAfter = response.headers.get('Retry-After') || '60';
+                message = `Rate limited (${response.status}): ${messageFromBody} (retry after ${retryAfter}s)`;
+            }
+            return {
+                ok: false,
+                error: { code: ErrorCodes.WP_ERROR, message },
+            };
+        }
+        // 2xx with non-JSON body — only legitimate failure mode that warrants a
+        // throw. A successful HTTP status with garbage in the body is a server-
+        // side contract violation, not a domain-level outcome the envelope can
+        // represent.
+        if (parseError) {
+            throw new Error(`WordPress API non-JSON body (${response.status}): ${rawBody.slice(0, 200)}`);
+        }
+        // 2xx body that is not yet shaped as an envelope — legacy route. Wrap
+        // it so adopting tools always see a uniform success shape.
+        return { ok: true, data: parsed };
+    }
     /**
      * Test the connection to WordPress.
+     *
+     * Routes through `requestEnveloped` because `/schema/settings` was
+     * envelope-adopted in the schema_* pilot — its body is now
+     * `{ ok: true, data: { builder, ... } }`. Reading
+     * `result.builder.version` against that shape (the pre-pilot pattern)
+     * silently regresses meta_ping to "Connected to Divi unknown" on
+     * healthy sites.
      */
     async testConnection() {
         try {
-            const result = await this.request('/schema/settings');
+            const response = await this.requestEnveloped('/schema/settings');
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    message: `Connection failed: [${response.error.code}] ${response.error.message}`,
+                };
+            }
             return {
                 ok: true,
-                message: `Connected to Divi ${result.builder?.version ?? 'unknown'}`,
+                message: `Connected to Divi ${response.data.builder?.version ?? 'unknown'}`,
             };
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",