@diviops/mcp-server 1.4.0 → 1.4.1

package/README.md

@@ -296,9 +296,21 @@ Tool returns a preview of the changes it would make; caller reviews the diff, th
 
 > Both preview-then-commit tools share the same semantic pattern but use different parameter shapes (`mode` enum vs `dry_run` bool). Both predate this convention and stay as-is for caller compatibility. **New bulk tools should use the enum form** (`mode: "dry-run" | "apply"`) — it's more extensible if future modes are needed (`"interactive"`, `"selective"`, etc.) and keeps the interface consistent as the tool set grows.
 
+### Pattern B (variant) — universal `dry_run: boolean` on every write tool
+
+Every mutating tool also accepts an optional `dry_run: boolean` (default `false`). When `true`, the response carries a uniform plan shape — `{ ok: true, data: { dry_run: true, plan: { summary, changes[, warnings] } } }` — and no state is mutated. Apply mode (`dry_run` omitted) keeps each tool's pre-existing response shape unchanged, so adding the parameter is non-breaking.
+
+This complements Pattern B's `mode: dry-run/apply` convention on bulk operations:
+- `mode: "dry-run"/"apply"` is the explicit two-round-trip contract for bulk tools where the preview *is* the value.
+- `dry_run: true` is the lighter "preview before commit" knob available on every write tool, including single-item ones.
+
+A handful of pre-existing tools predate the standard plan shape and keep their original response shapes for now: `preset_cleanup`, `preset_reassign`, `preset_delete`, `canvas_duplicate`, `page_trash`, `page_update_status`, `scf_sync`, `variable_create_fluid_system`.
+
+`meta_wp_cli` and `scf_import` do not accept `dry_run` — `meta_wp_cli` is a raw passthrough (use explicit read-only commands instead) and SCF's upstream `wp scf json import` lacks a `--dry-run` flag (use `scf_sync --dry_run` for the SCF-on-disk preview path).
+
 ### Picking a pattern for a new tool
 
-Ask: **single item or many?** If single, Pattern A. If many, Pattern B.
+Ask: **single item or many?** If single, Pattern A. If many, Pattern B (with `mode: "dry-run"/"apply"`). Either way, the universal `dry_run: boolean` knob is also available on every write tool — adding it on a new write tool is the default expectation.
 
 Don't introduce a third pattern (`confirmation_token`, session-based preview, etc.) unless a tool has a genuine need that neither A nor B covers — both patterns above are stateless and flexible enough for most cases.
 

package/dist/envelope.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Standardized response envelope (#489).
+ *
+ * Every diviops tool — server-local or plugin-routed — returns:
+ *   success: { ok: true,  data: T }
+ *   error:   { ok: false, error: { code: string, message: string, hint?: string } }
+ *
+ * Adoption is per-namespace (#489 + per-namespace follow-ups). Tools that
+ * have not adopted yet still pass legacy raw payloads through to consumers;
+ * the helpers here coexist with that shape during the rollout window.
+ *
+ * HTTP status stays orthogonal to envelope shape on the wire — the plugin
+ * emits 200 on ok:true and the real status (400/404/409/412/500) on ok:false.
+ * The server-side `wp.request` raises on non-2xx today, so error envelopes
+ * arrive as thrown errors carrying the JSON body; `wrapResponse` is the
+ * normalizer that maps both branches to the typed `DiviopsResponse<T>`.
+ */
+export type DiviopsSuccess<T> = {
+    ok: true;
+    data: T;
+};
+export type DiviopsErrorBody = {
+    code: string;
+    message: string;
+    hint?: string;
+    /**
+     * Optional structured payload attached to the error envelope. Used by
+     * tools whose failure mode carries machine-readable detail beyond a
+     * code/message pair — e.g. `meta_wp_cli` exposes
+     * `error.data = { exit_code, stdout, stderr }` so callers can branch
+     * on the wp-cli exit code without parsing the message string. Tools
+     * that don't need it omit the field entirely.
+     *
+     * Naming convention: when a namespace-specific error code attaches
+     * `data`, list the field shape in the tool's description and in
+     * tools.md "Response shape" so consumers know what to expect per
+     * code without runtime probing.
+     */
+    data?: unknown;
+};
+export type DiviopsFailure = {
+    ok: false;
+    error: DiviopsErrorBody;
+};
+export type DiviopsResponse<T> = DiviopsSuccess<T> | DiviopsFailure;
+/**
+ * Standard error code vocabulary. Plugin and server emit only these codes
+ * for the matching condition; namespace-specific extensions use the
+ * `<namespace>.<reason>` form (e.g. `library.import_conflict`).
+ */
+export declare const ErrorCodes: {
+    /** Target ID does not resolve. HTTP 404. */
+    readonly NOT_FOUND: "not_found";
+    /** Schema violation, malformed args. HTTP 400. */
+    readonly INVALID_INPUT: "invalid_input";
+    /** Underlying WordPress error (wraps WP_Error or REST framework error). HTTP 500. */
+    readonly WP_ERROR: "wp_error";
+    /** Divi-specific error (block parser, validator, etc.). HTTP 500. */
+    readonly DIVI_ERROR: "divi_error";
+    /** Plugin version below required for this tool (#486 handshake miss). HTTP 412. */
+    readonly CAPABILITY_MISSING: "capability_missing";
+    /** validate_blocks-detected shape error in submitted markup. HTTP 400. */
+    readonly VALIDATION_FAILED: "validation_failed";
+    /** Uniqueness collision (#542 / #543). HTTP 409. */
+    readonly CONFLICT: "conflict";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes] | string;
+/**
+ * Typed throw used inside server-local handlers to short-circuit with a
+ * specific envelope error code. `wrapResponse` catches it and re-emits.
+ */
+export declare class DiviopsError extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    readonly data?: unknown;
+    constructor(code: string, message: string, hint?: string, data?: unknown);
+}
+/**
+ * Throw a `DiviopsError`. Helper for ergonomics — `withCode(...)` reads
+ * better at call sites than `throw new DiviopsError(...)` and matches the
+ * kickoff's helper-API sketch. Pass `data` when the failure carries a
+ * structured payload (e.g. wp-cli exit code + captured streams).
+ */
+export declare function withCode(code: string, message: string, hint?: string, data?: unknown): never;
+/**
+ * Type guard: is `value` already shaped as a `DiviopsResponse`?
+ *
+ * Plugin-routed tools return the envelope; server-local tools may return
+ * raw values. `wrapResponse` uses this to avoid double-wrapping.
+ */
+export declare function isEnveloped(value: unknown): value is DiviopsResponse<unknown>;
+/**
+ * Run an async producer and normalize its outcome to a `DiviopsResponse<T>`.
+ *
+ * Behavior:
+ *  - Producer returns an already-enveloped value → pass through unchanged
+ *    (no double-wrap). Plugin-routed tools land here.
+ *  - Producer returns a raw value → wrap as `{ok: true, data: <value>}`.
+ *    Server-local tools land here.
+ *  - Producer throws `DiviopsError` → emit `{ok: false, error: {code, message, hint?}}`.
+ *  - Producer throws anything else → emit `{ok: false, error: {code: 'wp_error', message: e.message}}`.
+ *    The fallback covers thrown HTTP errors from `wp.request` whose body
+ *    is the plugin's envelope JSON; we attempt to parse the message and
+ *    promote the embedded code/hint when present.
+ */
+export declare function wrapResponse<T>(producer: () => Promise<T | DiviopsResponse<T>>): Promise<DiviopsResponse<T>>;
+/**
+ * Map the data of a `DiviopsResponse` through `fn` (success branch only).
+ * Errors pass through unchanged. Use to post-process a wrapped result
+ * (e.g. shrink schema, project fields) without unwrapping by hand.
+ */
+export declare function envelopeMap<T, U>(response: DiviopsResponse<T>, fn: (data: T) => U): DiviopsResponse<U>;
+/**
+ * Serialize a `DiviopsResponse` as the JSON string an MCP tool emits in its
+ * `content[0].text` slot. Single emit point keeps the wire shape consistent.
+ */
+export declare function serializeEnvelope<T>(response: DiviopsResponse<T>): string;

package/dist/envelope.js

@@ -0,0 +1,171 @@
+/**
+ * Standardized response envelope (#489).
+ *
+ * Every diviops tool — server-local or plugin-routed — returns:
+ *   success: { ok: true,  data: T }
+ *   error:   { ok: false, error: { code: string, message: string, hint?: string } }
+ *
+ * Adoption is per-namespace (#489 + per-namespace follow-ups). Tools that
+ * have not adopted yet still pass legacy raw payloads through to consumers;
+ * the helpers here coexist with that shape during the rollout window.
+ *
+ * HTTP status stays orthogonal to envelope shape on the wire — the plugin
+ * emits 200 on ok:true and the real status (400/404/409/412/500) on ok:false.
+ * The server-side `wp.request` raises on non-2xx today, so error envelopes
+ * arrive as thrown errors carrying the JSON body; `wrapResponse` is the
+ * normalizer that maps both branches to the typed `DiviopsResponse<T>`.
+ */
+/**
+ * Standard error code vocabulary. Plugin and server emit only these codes
+ * for the matching condition; namespace-specific extensions use the
+ * `<namespace>.<reason>` form (e.g. `library.import_conflict`).
+ */
+export const ErrorCodes = {
+    /** Target ID does not resolve. HTTP 404. */
+    NOT_FOUND: "not_found",
+    /** Schema violation, malformed args. HTTP 400. */
+    INVALID_INPUT: "invalid_input",
+    /** Underlying WordPress error (wraps WP_Error or REST framework error). HTTP 500. */
+    WP_ERROR: "wp_error",
+    /** Divi-specific error (block parser, validator, etc.). HTTP 500. */
+    DIVI_ERROR: "divi_error",
+    /** Plugin version below required for this tool (#486 handshake miss). HTTP 412. */
+    CAPABILITY_MISSING: "capability_missing",
+    /** validate_blocks-detected shape error in submitted markup. HTTP 400. */
+    VALIDATION_FAILED: "validation_failed",
+    /** Uniqueness collision (#542 / #543). HTTP 409. */
+    CONFLICT: "conflict",
+};
+/**
+ * Typed throw used inside server-local handlers to short-circuit with a
+ * specific envelope error code. `wrapResponse` catches it and re-emits.
+ */
+export class DiviopsError extends Error {
+    code;
+    hint;
+    data;
+    constructor(code, message, hint, data) {
+        super(message);
+        this.name = "DiviopsError";
+        this.code = code;
+        this.hint = hint;
+        this.data = data;
+    }
+}
+/**
+ * Throw a `DiviopsError`. Helper for ergonomics — `withCode(...)` reads
+ * better at call sites than `throw new DiviopsError(...)` and matches the
+ * kickoff's helper-API sketch. Pass `data` when the failure carries a
+ * structured payload (e.g. wp-cli exit code + captured streams).
+ */
+export function withCode(code, message, hint, data) {
+    throw new DiviopsError(code, message, hint, data);
+}
+/**
+ * Type guard: is `value` already shaped as a `DiviopsResponse`?
+ *
+ * Plugin-routed tools return the envelope; server-local tools may return
+ * raw values. `wrapResponse` uses this to avoid double-wrapping.
+ */
+export function isEnveloped(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v.ok === true && "data" in v)
+        return true;
+    if (v.ok === false && typeof v.error === "object" && v.error !== null) {
+        const e = v.error;
+        return typeof e.code === "string" && typeof e.message === "string";
+    }
+    return false;
+}
+/**
+ * Run an async producer and normalize its outcome to a `DiviopsResponse<T>`.
+ *
+ * Behavior:
+ *  - Producer returns an already-enveloped value → pass through unchanged
+ *    (no double-wrap). Plugin-routed tools land here.
+ *  - Producer returns a raw value → wrap as `{ok: true, data: <value>}`.
+ *    Server-local tools land here.
+ *  - Producer throws `DiviopsError` → emit `{ok: false, error: {code, message, hint?}}`.
+ *  - Producer throws anything else → emit `{ok: false, error: {code: 'wp_error', message: e.message}}`.
+ *    The fallback covers thrown HTTP errors from `wp.request` whose body
+ *    is the plugin's envelope JSON; we attempt to parse the message and
+ *    promote the embedded code/hint when present.
+ */
+export async function wrapResponse(producer) {
+    try {
+        const result = await producer();
+        if (isEnveloped(result)) {
+            return result;
+        }
+        return { ok: true, data: result };
+    }
+    catch (e) {
+        if (e instanceof DiviopsError) {
+            const error = { code: e.code, message: e.message };
+            if (e.hint)
+                error.hint = e.hint;
+            if (e.data !== undefined)
+                error.data = e.data;
+            return { ok: false, error };
+        }
+        return { ok: false, error: parseThrownError(e) };
+    }
+}
+/**
+ * Extract envelope error info from a thrown value.
+ *
+ * `wp.request` throws Errors of the form
+ *   `WordPress API error (NNN): <body>`
+ * where `<body>` may be the plugin's envelope JSON. We try to recover the
+ * embedded code/hint in that case so re-thrown plugin errors don't lose
+ * their structured shape on round-trip through `wrapResponse`.
+ */
+function parseThrownError(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const bodyMatch = message.match(/^WordPress API error \(\d+\):\s*(.*)$/s);
+    if (bodyMatch) {
+        try {
+            const parsed = JSON.parse(bodyMatch[1]);
+            if (parsed &&
+                typeof parsed === "object" &&
+                parsed.ok === false &&
+                parsed.error &&
+                typeof parsed.error === "object" &&
+                typeof parsed.error.code === "string" &&
+                typeof parsed.error.message === "string") {
+                const out = {
+                    code: parsed.error.code,
+                    message: parsed.error.message,
+                };
+                if (typeof parsed.error.hint === "string")
+                    out.hint = parsed.error.hint;
+                if (parsed.error.data !== undefined)
+                    out.data = parsed.error.data;
+                return out;
+            }
+        }
+        catch {
+            // Body wasn't JSON, fall through to generic wp_error.
+        }
+    }
+    return { code: ErrorCodes.WP_ERROR, message };
+}
+/**
+ * Map the data of a `DiviopsResponse` through `fn` (success branch only).
+ * Errors pass through unchanged. Use to post-process a wrapped result
+ * (e.g. shrink schema, project fields) without unwrapping by hand.
+ */
+export function envelopeMap(response, fn) {
+    if (response.ok)
+        return { ok: true, data: fn(response.data) };
+    return response;
+}
+/**
+ * Serialize a `DiviopsResponse` as the JSON string an MCP tool emits in its
+ * `content[0].text` slot. Single emit point keeps the wire shape consistent.
+ */
+export function serializeEnvelope(response) {
+    return JSON.stringify(response);
+}