@wootsup/mcp 0.1.0 → 0.3.0

package/dist/modules/apimapper/whitelist-drift.js

@@ -0,0 +1,360 @@
+// src/modules/apimapper/whitelist-drift.ts — Wave-16 #88
+//
+// MCP↔PHP whitelist drift detector — shared harness.
+//
+// PURPOSE
+// -------
+// Every API Mapper MCP tool that mutates state POSTs/PUTs a JSON body to a
+// WordPress REST route under /wp-json/api-mapper/v1/. If a tool puts a key in
+// that body which the PHP handler does NOT read, one of two bad things happens:
+//
+//   * the PHP layer silently DROPS the key (the tool advertises behaviour that
+//     never takes effect — e.g. an ordering option that does nothing), or
+//   * the PHP layer REJECTS the request (e.g. ConnectionAdminController's
+//     ALLOWED_PATCH_KEYS 422s an unknown patch key).
+//
+// Both are real defects, and both are invisible to the type system because the
+// MCP and PHP sides live in different languages. This harness reconciles the
+// two surfaces so a CI test fails the moment they drift.
+//
+// THE THREE INPUTS
+// ----------------
+//  1. The LIVE MCP tool surface — enumerated at runtime from the registered
+//     module (essentials forwarded to a real McpServer + advanced registry +
+//     the externally-registered profile/status tools). See collectLiveTools().
+//  2. TOOL_WIRE_MAP — the hand-maintained bridge from each body-sending tool to
+//     the REST route it calls and the EXACT wire body keys it sends. The wire
+//     keys are NOT always the zod keys: several tools remap (e.g.
+//     local_source_query's zod `content_type` → wire `contentType`). A PHP scan
+//     cannot see this remap and the zod schema does not encode the route, so
+//     this bridge is curated. It is anti-rot-guarded: the test asserts it
+//     covers EXACTLY the live tool set (minus declared local tools), so a new
+//     or removed tool fails CI until the map is updated.
+//  3. The PHP-accepted-params manifest (tests/fixtures/php-accepted-params.json)
+//     — route → accepted body keys, generated by scripts/dump-rest-whitelist.php
+//     from the real controllers and hand-reconciled. Plus `_allowed_drift`
+//     (per-tool justified exceptions) and `_local_tools` (tools with no REST
+//     route).
+//
+// The harness is pure + import-safe (no network, no env requirement) so it can
+// be imported by both the vitest pin test and the standalone gate script.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { apimapperRestModule } from "./index.js";
+/**
+ * Curated bridge: body-sending tool → route + wire body keys.
+ *
+ * ONLY tools that send a request body appear here. Read-only (GET) tools and
+ * path/query-only tools carry no body-drift surface and are listed in the
+ * manifest's `_local_tools` (when they hit no route at all) or are simply
+ * absent (when they hit a GET route — GET routes never drift on body keys).
+ *
+ * `envelope` tools forward a free-form record (`patch` / `pipeline` / a settings
+ * map) whose individual keys are validated on the PHP side (e.g.
+ * ConnectionAdminController::ALLOWED_PATCH_KEYS). Their wrapper key is recorded
+ * so the test confirms the tool is accounted for; per-key validation lives in
+ * the PHP layer and is covered by PHP-side tests.
+ */
+export const TOOL_WIRE_MAP = {
+    // ── Connections ────────────────────────────────────────────────────
+    apimapper_connection_create: {
+        route: "POST /connections",
+        bodyKeys: [
+            "name",
+            "endpoint",
+            "method",
+            "auth_type",
+            "credential_id",
+            "items_path",
+            "cache_ttl",
+            "description",
+        ],
+        kind: "structured",
+    },
+    apimapper_connection_update: {
+        route: "PUT /connections/{id}",
+        bodyKeys: ["patch"],
+        kind: "envelope",
+    },
+    apimapper_connection_recover: {
+        route: "PUT /connections/{id}",
+        bodyKeys: ["patch"],
+        kind: "envelope",
+    },
+    apimapper_connection_test: {
+        route: "POST /connections/test",
+        bodyKeys: ["connection_id"],
+        kind: "structured",
+    },
+    apimapper_connection_health_check: {
+        route: "POST /connections/health-check",
+        bodyKeys: ["connection_ids"],
+        kind: "structured",
+    },
+    apimapper_connection_pipeline_update: {
+        route: "PUT /connections/{id}/pipeline",
+        bodyKeys: ["pipeline"],
+        kind: "envelope",
+    },
+    // ── Credentials ────────────────────────────────────────────────────
+    apimapper_credential_create: {
+        route: "POST /credentials",
+        bodyKeys: [
+            "name",
+            "auth_type",
+            "auth_data",
+            "oauth_provider",
+            "provider",
+            "oauth_token_expires_at",
+        ],
+        kind: "structured",
+    },
+    apimapper_credential_update: {
+        route: "PUT /credentials/{id}",
+        bodyKeys: ["patch"],
+        kind: "envelope",
+    },
+    apimapper_credential_link: {
+        route: "POST /oauth/authorize",
+        bodyKeys: ["existing_credential_id", "scopes"],
+        kind: "structured",
+    },
+    apimapper_oauth_authorize_begin: {
+        route: "POST /oauth/authorize",
+        bodyKeys: ["existing_credential_id", "scopes"],
+        kind: "structured",
+    },
+    // ── Flows ──────────────────────────────────────────────────────────
+    apimapper_flow_create: {
+        route: "POST /flows",
+        bodyKeys: ["name", "description", "nodes", "edges", "viewport"],
+        kind: "structured",
+    },
+    apimapper_flow_update: {
+        route: "PUT /flows/{id}",
+        bodyKeys: ["patch"],
+        kind: "envelope",
+    },
+    apimapper_flow_import_validate: {
+        route: "POST /flows/import/validate",
+        bodyKeys: ["bundle"],
+        kind: "envelope",
+    },
+    apimapper_flow_import: {
+        route: "POST /flows/import",
+        bodyKeys: ["bundle"],
+        kind: "envelope",
+    },
+    // ── Graph / Schema ─────────────────────────────────────────────────
+    apimapper_graph_preview: {
+        route: "POST /graph/preview",
+        bodyKeys: ["nodes", "edges", "targetNodeId", "forceRefresh"],
+        kind: "structured",
+    },
+    apimapper_graph_validate: {
+        route: "POST /graph/validate",
+        bodyKeys: ["nodes", "edges"],
+        kind: "structured",
+    },
+    apimapper_schema_profile: {
+        route: "POST /schema-profile",
+        bodyKeys: ["nodes", "edges", "target_node_id", "flow_id"],
+        kind: "structured",
+    },
+    // ── Local sources ──────────────────────────────────────────────────
+    apimapper_local_source_query: {
+        route: "POST /local-sources/query",
+        // Wire keys after the handler's zod→wire remap: content_type→contentType,
+        // orderby→sort, order→sortDirection (see #88 reconciliation).
+        bodyKeys: ["contentType", "filters", "limit", "offset", "sort", "sortDirection"],
+        kind: "structured",
+    },
+    // ── Cache / Settings ───────────────────────────────────────────────
+    apimapper_cache_invalidate: {
+        route: "POST /cache/admin/invalidate",
+        bodyKeys: ["scope", "payload"],
+        kind: "structured",
+    },
+    apimapper_settings_update: {
+        route: "POST /settings",
+        bodyKeys: ["patch"],
+        kind: "envelope",
+    },
+    // ── License ────────────────────────────────────────────────────────
+    apimapper_license_activate: {
+        route: "POST /license/activate",
+        bodyKeys: ["license_key", "email"],
+        kind: "structured",
+    },
+    apimapper_license_beta_channel: {
+        route: "POST /license/beta-channel",
+        bodyKeys: ["enabled"],
+        kind: "structured",
+    },
+    // ── Misc ───────────────────────────────────────────────────────────
+    apimapper_health_warnings_dismiss: {
+        route: "POST /admin/health-warnings/dismiss",
+        bodyKeys: ["id"],
+        kind: "structured",
+    },
+    apimapper_feedback_submit: {
+        route: "POST /feedback",
+        bodyKeys: ["type", "subject", "message", "email", "attachments", "idempotency_key"],
+        kind: "structured",
+    },
+    apimapper_release_download: {
+        route: "POST /releases/download",
+        bodyKeys: ["version", "product"],
+        kind: "structured",
+    },
+};
+/**
+ * Resolve the committed fixture path. From this module
+ * (`<pkg>/{src,dist}/modules/apimapper/whitelist-drift.{ts,js}`) the package
+ * root is three directories up; the fixture is `tests/fixtures/...` under it.
+ * The depth is identical for the source layout (vitest/tsx) and the built
+ * `dist/` layout, so the same relative offset works in both.
+ */
+export function manifestPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..", "..", "tests", "fixtures", "php-accepted-params.json");
+}
+/** Narrowing guard for the parsed manifest JSON. */
+function isManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.routes === "object" &&
+        v.routes !== null &&
+        typeof v._allowed_drift === "object" &&
+        v._allowed_drift !== null &&
+        typeof v._local_tools === "object" &&
+        v._local_tools !== null);
+}
+/** Load + validate the committed PHP-accepted-params manifest. */
+export function loadManifest(path = manifestPath()) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (!isManifest(raw)) {
+        throw new Error(`Invalid php-accepted-params manifest at ${path}`);
+    }
+    return raw;
+}
+/**
+ * Enumerate every registered MCP tool name. Mirrors the runtime tool surface:
+ *   - module essentials forwarded to a real McpServer,
+ *   - the gateway-captured advanced tools,
+ *   - the profile / status tools registered in src/index.ts AFTER module load.
+ *
+ * The src/index.ts trio is appended explicitly: they are registered on the real
+ * server outside the module's register(), so a module-only enumeration would
+ * miss them. They are pure local/profile tools (no REST body) and live in
+ * `_local_tools`; listing them here keeps the coverage check honest.
+ */
+export function collectLiveTools() {
+    const server = new McpServer({ name: "drift-probe", version: "0.0.0" });
+    const names = new Set();
+    // Intercept registerTool so essentials forwarded to the real server are seen.
+    const realRegister = server.registerTool.bind(server);
+    const patched = server;
+    patched.registerTool = (name, config, cb) => {
+        names.add(name);
+        return realRegister(name, config, cb);
+    };
+    apimapperRestModule.register(server);
+    const advanced = apimapperRestModule.getAdvancedRegistry();
+    if (advanced) {
+        for (const name of advanced.keys())
+            names.add(name);
+    }
+    // Externally-registered (src/index.ts) — no REST body; covered by _local_tools.
+    for (const n of ["apimapper_use_profile", "apimapper_list_profiles", "apimapper_rest_modules_status"]) {
+        names.add(n);
+    }
+    return [...names].sort();
+}
+/**
+ * Compute the drift report from the live tool surface + the curated wire map +
+ * the PHP-accepted manifest. Pure — no I/O.
+ */
+export function computeDrift(liveTools, manifest) {
+    const drift = [];
+    const inverse = [];
+    const uncovered = [];
+    const live = new Set(liveTools);
+    // Coverage: every live tool must be in the wire map OR declared local.
+    for (const tool of liveTools) {
+        const inWireMap = Object.prototype.hasOwnProperty.call(TOOL_WIRE_MAP, tool);
+        const isLocal = Object.prototype.hasOwnProperty.call(manifest._local_tools, tool);
+        if (!inWireMap && !isLocal)
+            uncovered.push(tool);
+    }
+    // Anti-rot: nothing in the wire map / local map may reference a vanished tool.
+    const stale = [];
+    for (const tool of Object.keys(TOOL_WIRE_MAP)) {
+        if (!live.has(tool))
+            stale.push(tool);
+    }
+    for (const tool of Object.keys(manifest._local_tools)) {
+        if (!live.has(tool))
+            stale.push(tool);
+    }
+    // Forward direction: each wire body key must be accepted or allow-listed.
+    for (const [tool, binding] of Object.entries(TOOL_WIRE_MAP)) {
+        if (!live.has(tool))
+            continue; // reported as stale above
+        const accepted = new Set(manifest.routes[binding.route] ?? []);
+        const allowed = manifest._allowed_drift[tool] ?? {};
+        for (const key of binding.bodyKeys) {
+            if (accepted.has(key))
+                continue;
+            if (Object.prototype.hasOwnProperty.call(allowed, key))
+                continue;
+            drift.push({ tool, route: binding.route, key });
+        }
+    }
+    // Inverse direction (advisory): PHP-accepted keys no tool sends.
+    //
+    // Built per route from the union of the STRUCTURED bindings' literal body
+    // keys. Routes that ANY envelope binding targets are skipped entirely: an
+    // envelope tool forwards a free-form record that can legitimately carry any
+    // of the route's accepted keys, so "no tool sends key X" is meaningless there
+    // (per-key validity for envelope routes is a PHP-side concern). The inverse
+    // check therefore only fires for routes whose tools send a fixed, literal key
+    // set — exactly where a PHP-only key really is unreachable from the MCP.
+    const sentByRoute = new Map();
+    const envelopeRoutes = new Set();
+    for (const binding of Object.values(TOOL_WIRE_MAP)) {
+        if (binding.kind === "envelope") {
+            envelopeRoutes.add(binding.route);
+            continue;
+        }
+        if (!sentByRoute.has(binding.route))
+            sentByRoute.set(binding.route, new Set());
+        const set = sentByRoute.get(binding.route);
+        for (const k of binding.bodyKeys)
+            set.add(k);
+    }
+    for (const [route, accepted] of Object.entries(manifest.routes)) {
+        if (envelopeRoutes.has(route))
+            continue; // free-form record carries any key
+        const sent = sentByRoute.get(route);
+        if (!sent)
+            continue; // no structured tool targets this route with a body
+        const ignore = manifest._inverse_ignore?.[route] ?? {};
+        for (const key of accepted) {
+            if (sent.has(key))
+                continue;
+            if (Object.prototype.hasOwnProperty.call(ignore, key))
+                continue;
+            inverse.push({ route, key });
+        }
+    }
+    drift.sort((a, b) => a.tool.localeCompare(b.tool) || a.key.localeCompare(b.key));
+    inverse.sort((a, b) => a.route.localeCompare(b.route) || a.key.localeCompare(b.key));
+    uncovered.sort();
+    stale.sort();
+    return { drift, inverse, uncovered, stale };
+}
+//# sourceMappingURL=whitelist-drift.js.map

package/dist/modules/apimapper/whitelist-drift.js.map

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

package/dist/modules/apimapper/workflows.js

@@ -56,9 +56,20 @@ export function registerWorkflowTools(server) {
             transform: TransformSpec.optional().describe("Optional Transform node"),
             output: OutputSpec.describe("Output node config"),
             compile: z.boolean().default(true).describe("Compile after save (= publish to YOOtheme)"),
+            autofix: z
+                .boolean()
+                .default(true)
+                .describe("Defaults to true. When compile:true, auto-repair empty-output-schema compile errors " +
+                "by calling detect-schema then retrying compile so the new source compiles and " +
+                "appears. Pass false to opt out (verbatim old behaviour — no detect-schema retry). " +
+                "Mirrors `flow_full_recompile_publish` autofix."),
         },
         annotations: creating({ title: "Setup Flow with Sources", openWorld: true }),
-    }, async ({ name, description, sources, merge, transform, output, compile }, extra) => {
+    }, async ({ name, description, sources, merge, transform, output, compile, autofix }, extra) => {
+        // C (2026-06-04): autofix defaults to true. Treat `undefined` (omitted
+        // arg / unit-test harness that bypasses the schema default) as the
+        // on-default; only an explicit `autofix:false` opts out.
+        const autofixEnabled = autofix !== false;
         // W3.5 — progress side-channel. `null` when the caller sent no
         // progressToken; `progress?.report(...)` then no-ops. Total steps:
         // build-graph + create + (compile when requested).
@@ -116,9 +127,29 @@ export function registerWorkflowTools(server) {
         // does not include the full flow object.
         let compiled = false;
         let compileError;
+        const autofixActions = [];
         if (compile) {
             await progress?.report(2, totalSteps, "Compiling and publishing to YOOtheme…");
-            const compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+            let compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+            // F5 (W9b, 2026-05-29): autofix mirror of flow_full_recompile_publish.
+            // CODE_EMPTY_SCHEMA = 4 (PHP FlowCompilerException constant, frozen).
+            // On empty-schema error, call detect-schema then retry compile. This
+            // makes the composite tool self-healing on the most common compile
+            // failure (newly created flow has no output schema yet).
+            const COMPILER_CODE_EMPTY_SCHEMA = 4;
+            if (!compileR.success &&
+                autofixEnabled &&
+                compileR.errorBody?.compiler_error_code === COMPILER_CODE_EMPTY_SCHEMA) {
+                autofixActions.push("Detected empty output schema, running detect-schema");
+                const detectR = await request(`/flows/${encodeURIComponent(flowId)}/detect-schema`, { method: "POST" });
+                if (detectR.success) {
+                    autofixActions.push("Schema detected, retrying compile");
+                    compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+                }
+                else {
+                    autofixActions.push(`Schema detection failed: ${detectR.error ?? "unknown"}; cannot retry compile`);
+                }
+            }
             if (!compileR.success) {
                 compileError = compileR.error;
                 steps.push(`2. Compile FAILED: ${compileR.error}`);
@@ -132,7 +163,8 @@ export function registerWorkflowTools(server) {
                 }
                 else {
                     compiled = true;
-                    steps.push("2. Compiled — flow visible in YOOtheme dropdown");
+                    const autofixSuffix = autofixActions.length > 0 ? " (autofix applied)" : "";
+                    steps.push(`2. Compiled — flow visible in YOOtheme dropdown${autofixSuffix}`);
                 }
             }
         }
@@ -142,6 +174,7 @@ export function registerWorkflowTools(server) {
                 flow_id: flowId,
                 compiled: false,
                 compile_error: compileError,
+                autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
                 steps,
                 next_action: "investigate_compile_error",
                 cleanup: `Call apimapper_flow_delete with id="${flowId}" + confirm=true to roll back the orphan, OR fix node config and call apimapper_flow_compile again.`,
@@ -298,20 +331,30 @@ export function registerWorkflowTools(server) {
     //      so the source appears in YOOtheme immediately without a second MCP
     //      package (matches audit recommendation A1 P1).
     //
-    // The default (`autofix:false`) preserves the v2.0.7 behaviour verbatim so
-    // existing tool callers do not see a behaviour change. The PHP layer
-    // surfaces `compiler_error_code` on compile-error responses (FlowHandler.php)
-    // so this branch reads a numeric class rather than string-matching messages.
+    // C (2026-06-04): the default is now `autofix:true`. Observed live in a
+    // Claude Desktop session: when the AI omits `autofix`, the old default
+    // (false) meant the YOOtheme schema cache was never flushed, so the source
+    // did NOT appear in the YOOtheme builder after publish. Flipping the default
+    // makes the autofix path (detect-schema retry + flush-yt) the normal path,
+    // so a plain `apimapper_flow_full_recompile_publish({id})` reliably publishes
+    // a visible source. `autofix:false` is now an explicit opt-out that restores
+    // the verbatim v2.0.7 behaviour (compile + admin-cache only, no detect-schema
+    // retry, no YT flush). The handler treats `autofix !== false` as enabled, so
+    // an omitted/undefined value behaves identically to the schema default at the
+    // real SDK call boundary. The PHP layer surfaces `compiler_error_code` on
+    // compile-error responses (FlowHandler.php) so this branch reads a numeric
+    // class rather than string-matching messages.
     server.registerTool("apimapper_flow_full_recompile_publish", {
         title: "Full Recompile + Cache Clear (Composite)",
-        description: "Compile a flow + invalidate admin cache in one call. Use after upstream API changes " +
-            "to ensure the flow + schema are fresh. Each step's success is surfaced separately, " +
-            "and a cache-clear failure does NOT silently downgrade compile success. " +
-            "Pass autofix:true to auto-repair common compile errors " +
-            "(empty output schema → re-detect; then retry compile) and to flush the " +
-            "YOOtheme schema cache so the source becomes visible in YOOtheme without " +
-            "a second MCP package." +
-            "\n\nExample:\n  apimapper_flow_full_recompile_publish({ id: 'flow_Z2fLg70M84', autofix: true })",
+        description: "Compile a flow + invalidate admin cache + flush the YOOtheme schema cache in one call. " +
+            "Use after upstream API changes to ensure the flow + schema are fresh. Each step's success " +
+            "is surfaced separately, and a cache-clear failure does NOT silently downgrade compile success. " +
+            "autofix defaults to true: it auto-repairs common compile errors " +
+            "(empty output schema → re-detect; then retry compile) AND flushes the " +
+            "YOOtheme schema cache so the source becomes visible in the YOOtheme builder — " +
+            "no second MCP package needed. Pass autofix:false to opt out (compile + admin-cache " +
+            "only, no detect-schema retry, no YT flush — the verbatim v2.0.7 behaviour)." +
+            "\n\nExample:\n  apimapper_flow_full_recompile_publish({ id: 'flow_Z2fLg70M84' })",
         inputSchema: {
             // L-6 (W3F-5): accept either `id` (canonical, matches every other
             // flow_* tool) or `flow_id` (legacy alias kept so existing callers
@@ -327,10 +370,11 @@ export function registerWorkflowTools(server) {
                 .describe("Deprecated alias for `id` — accepted for back-compat with pre-W3F-5 callers."),
             autofix: z
                 .boolean()
-                .default(false)
-                .describe("When true: on empty-schema compile error, call detect-schema and retry compile. " +
-                "On compile success, also flush the YOOtheme schema cache so the source surfaces " +
-                "in the YOOtheme builder. Default false preserves v2.0.7 behaviour."),
+                .default(true)
+                .describe("When true (default): on empty-schema compile error, call detect-schema and retry " +
+                "compile. On compile success, also flush the YOOtheme schema cache so the source " +
+                "surfaces in the YOOtheme builder. Pass false to opt out — compile + admin-cache " +
+                "only, no detect-schema retry, no YT flush (the verbatim v2.0.7 behaviour)."),
         },
         annotations: mutating({ title: "Full Recompile & Publish Flow", openWorld: true }),
     }, async ({ id, flow_id: flowIdAlias, autofix }, extra) => {
@@ -346,9 +390,15 @@ export function registerWorkflowTools(server) {
         const steps = [];
         const errors = [];
         const autofixActions = [];
-        // W3.5: progress side-channel. autofix:true adds a third stage
+        // C (2026-06-04): autofix defaults to true. Treat `undefined` (caller
+        // omitted the arg, and the unit-test harness bypasses the schema default)
+        // identically to the on-default, so only an explicit `autofix:false`
+        // opts out. This keeps the handler faithful to the documented default
+        // whether or not the SDK applied the Zod default before dispatch.
+        const autofixEnabled = autofix !== false;
+        // W3.5: progress side-channel. autofix adds a third stage
         // (YOOtheme schema cache flush) so it's a 3-step pipeline.
-        const totalSteps = autofix ? 3 : 2;
+        const totalSteps = autofixEnabled ? 3 : 2;
         const progress = extra ? createProgressReporter(extra) : null;
         await progress?.report(0, totalSteps, "Recompiling flow…");
         // Stage 1: compile (with optional autofix retry)
@@ -359,7 +409,7 @@ export function registerWorkflowTools(server) {
         // because both share src/modules/core/src/Flow/FlowCompilerException.php).
         const COMPILER_CODE_EMPTY_SCHEMA = 4;
         if (!compileR.success &&
-            autofix === true &&
+            autofixEnabled &&
             compileR.errorBody?.compiler_error_code === COMPILER_CODE_EMPTY_SCHEMA) {
             autofixActions.push("Detected empty output schema, running detect-schema");
             const detectR = await request(`/flows/${encodeURIComponent(flow_id)}/detect-schema`, { method: "POST" });
@@ -377,7 +427,7 @@ export function registerWorkflowTools(server) {
                 status: compileR.status,
                 errorCode: compileR.errorCode,
                 compiler_error_code: compileR.errorBody?.compiler_error_code,
-                context: { flow_id, stage: "compile", autofix: !!autofix },
+                context: { flow_id, stage: "compile", autofix: autofixEnabled },
                 autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
                 hint: hintFor(compileR.errorCode),
             }, true);
@@ -406,7 +456,7 @@ export function registerWorkflowTools(server) {
         // {flushed: false, error: <msg>} in the body when the buster threw.
         // We treat the request-level success/failure as authoritative and
         // record any flushed:false as a non-fatal warning step.
-        if (autofix === true) {
+        if (autofixEnabled) {
             await progress?.report(2, totalSteps, "Flushing YOOtheme schema cache…");
             const ytR = await request("/cache/flush-yt", { method: "POST" });
             if (ytR.success && ytR.data?.flushed !== false) {
@@ -434,11 +484,16 @@ export function registerWorkflowTools(server) {
             errors: ok ? undefined : errors,
             autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
             next: ok
-                ? autofix
+                ? autofixEnabled
                     ? "Flow recompiled, admin cache invalidated, and YOOtheme schema cache flushed. The source should now be visible in the YOOtheme builder."
-                    : "Flow is fresh in both admin + render layers. YOOtheme schema cache is NOT cleared by this tool; pass autofix:true (or call yootheme_clear_cache via the YOOtheme MCP) if the source does not appear in the builder."
+                    : "Flow is fresh in both admin + render layers. You passed autofix:false, so the YOOtheme schema cache was NOT cleared by this tool; re-run without autofix:false (the default flushes it) or call yootheme_clear_cache via the YOOtheme MCP if the source does not appear in the builder."
                 : "Compile succeeded but a cache step had issues. Manually call apimapper_cache_invalidate scope=all if downstream still sees stale data.",
-        }, ok, { maxChars: 2500 });
+        }, 
+        // Wave-5 F7 fix (2026-05-29): formatResult's 2nd positional is `isError`.
+        // Pre-fix we passed `ok` here, which inverted the meaning — ok:true was
+        // tagged as `<error>` envelope. Pass `!ok` so success-with-no-errors
+        // renders as success and partial (errors.length > 0) renders as error.
+        !ok, { maxChars: 2500 });
     });
 }
 //# sourceMappingURL=workflows.js.map