@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/sfcc/reads-site-preference.js

@@ -9,6 +9,34 @@
  * All three tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
  *
+ * PREFERENCE VALUES ARE NOT AVAILABLE HERE (BAPI-767).
+ * `preference_search` returns hits shaped `{_type, id}` and nothing more.
+ * Verified live against a developer sandbox (OCAPI v25_6): supplying
+ * `?select=(**)` changes the response not at all — zero hits gain a `value`
+ * key. That is why these two tools take no `projection` input while
+ * `site_preference_group_list` does: a projection that cannot alter the
+ * response is a flag with no observable effect.
+ *
+ * The consequence is a genuine caller-facing limitation, stated in both tool
+ * descriptions rather than left to be discovered: an ids-only read cannot
+ * distinguish "preference not set" from "preference set to the empty string".
+ *
+ * It is also, for now, accidentally protective. A name-heuristic scan of all 19
+ * preference groups on the tested sandbox found secret-named preferences in six
+ * of them — including one literally named `client_id` — and none of them expose
+ * a value through this endpoint. If OCAPI ever starts returning values here,
+ * redaction must be added on the raw body BEFORE normalization, serialization,
+ * truncation, or save, so one placement covers both the inline response and the
+ * docs/tmp/sfcc/ save path — exactly the `readSfccBody` seam these three
+ * handlers already route through (BAPI-769).
+ *
+ * That value-bearing route already exists elsewhere: `SitePreferences`
+ * attribute-definition reads via `system_object_attribute_search` (with
+ * `object_type: "SitePreferences"`) can return each preference's
+ * `default_value`, and `readSfccBody` withholds it there today. This module's
+ * three preference-value tools remain ids-only for the reason stated above —
+ * OCAPI's `preference_search` itself never returns a value, `select` or not.
+ *
  * NOTE: SCAPI Preferences API (sfcc.preferences) is intentionally NOT used.
  * This keeps the tool context on the OCAPI Data API, preserving the single
  * AM-OAuth boundary established in T1. Do not "modernize" these tools onto
@@ -18,7 +46,9 @@ import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
-import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { formatOcapiReadFailure, formatSfccReadFailure, withSfccReadErrorBoundary, } from "./read-result.js";
+import { readSfccBody } from "./read-body.js";
+import { projectionInputFor, projectionQueryEntries } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
 // Annotations (SPEC: read-only against developer sandboxes)
@@ -53,6 +83,7 @@ const sitePreferenceSearchInput = z.object({
 const sitePreferenceGroupListInput = z.object({
     count: z.number().optional().describe("Maximum number of site preference groups to return."),
     start: z.number().optional().describe("Zero-based offset for paging."),
+    projection: projectionInputFor("broad_list"),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -66,18 +97,37 @@ function safeGroup(group) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-async function saveAndReturn(text, dir, filename) {
-    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+async function saveAndReturn(text, dir, filename, page) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename, page);
     return textResult(output);
 }
-// D-5: reject any non-sandbox instance context (safer than silently proceeding)
+/**
+ * D-5: reject any non-sandbox instance context (safer than silently proceeding).
+ *
+ * The rejection decision is unchanged; BAPI-759 moved its representation to the
+ * shared formatter, so the guardrail fails at the protocol level like every
+ * other SFCC failure. Details carry non-sensitive guard metadata only — the
+ * rejected value is caller-supplied and enum-constrained.
+ *
+ * BAPI-766 reworded the message only. It used to open with "v1", which reads as
+ * an API version while OCAPI simultaneously reports `_v: "25.6"` in the same
+ * session; the constraint belongs to this Bridge tool, not to a version. The
+ * status, code, source, decision, and `details` payload are untouched.
+ */
 function rejectIfNotSandbox(instance) {
     if (instance !== "sandbox") {
-        return textResult(JSON.stringify({
-            error: "VALIDATION_ERROR",
+        return formatSfccReadFailure({
+            code: "VALIDATION_ERROR",
             status: 400,
-            message: `v1 only supports the 'sandbox' instance context. Received: '${instance}'.`,
-        }, null, 2));
+            message: `The Bridge site-preference tool only supports the 'sandbox' instance ` +
+                `context. Received: '${instance}'.`,
+            source: "tool",
+            details: {
+                guard: "sandbox_only",
+                received_instance: instance,
+                supported_instances: ["sandbox"],
+            },
+        });
     }
     return null;
 }
@@ -85,7 +135,7 @@ function rejectIfNotSandbox(instance) {
 // Handlers
 // ---------------------------------------------------------------------------
 export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
         const { group, instance, start, count } = sitePreferenceGetInput.parse(args);
         const guard = rejectIfNotSandbox(instance);
         if (guard)
@@ -100,16 +150,16 @@ export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         const result = await ocapiPost(`/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-get-${safeGroup(group)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-get-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
         const { group, instance, query, start, count, sorts } = sitePreferenceSearchInput.parse(args);
         const guard = rejectIfNotSandbox(instance);
         if (guard)
@@ -128,18 +178,20 @@ export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
             postBody.sorts = sorts;
         const result = await ocapiPost(`/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { count, start } = sitePreferenceGroupListInput.parse(args);
-        const queryParams = {};
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start, projection } = sitePreferenceGroupListInput.parse(args);
+        const queryParams = {
+            ...projectionQueryEntries("broad_list", projection),
+        };
         if (count !== undefined)
             queryParams.count = String(count);
         if (start !== undefined)
@@ -149,13 +201,13 @@ export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
             : "";
         const result = await ocapiGet(`/system_object_definitions/SitePreferences/attribute_groups${queryStr}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the three SFCC site-preference introspection read tools.
@@ -173,18 +225,19 @@ export function registerSitePreferenceTools(registerTool, deps) {
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceGroupListHandler(gateDeps, getDocsDir));
     registerTool("site_preference_get", {
-        description: "Read effective preferences for a site preference group from the developer sandbox " +
-            "via a match-all POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
-            "Read-only, sandbox-only. Accepts optional `start`/`count` paging in the POST body. " +
-            "Oversized payloads are auto-saved locally.",
+        description: "List preference IDENTIFIERS for a site preference group from the developer sandbox via a match-all " +
+            "POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
+            "Returns ids only, NOT values — 'unset' and 'empty string' are indistinguishable. " +
+            "Read-only, sandbox-only. Optional start/count paging. Oversized payloads auto-saved locally.",
         inputSchema: sitePreferenceGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceGetHandler(gateDeps, getDocsDir));
     registerTool("site_preference_search", {
-        description: "Search/filter preferences within a site preference group from the developer sandbox " +
-            "via POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
-            "Read-only; v1 sandbox only. Pass a plain string for id-only text search or a structured " +
-            "OCAPI query object. Oversized results are auto-saved locally.",
+        description: "Search preference IDENTIFIERS within a site preference group via " +
+            "POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
+            "Returns ids only — this endpoint does not expose values. Read-only; v1 sandbox only. " +
+            "Pass a plain string for id-only text search or a structured OCAPI query. " +
+            "Oversized results auto-saved locally.",
         inputSchema: sitePreferenceSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceSearchHandler(gateDeps, getDocsDir));

package/build/sfcc/reads-system-object.js

@@ -8,12 +8,19 @@
  *
  * All tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
+ *
+ * `system_object_attribute_search` can return complete attribute-definition
+ * documents at `projection: "full"` (BAPI-767). Bridge withholds each
+ * attribute's `default_value` from that response (BAPI-769, `read-body.ts`) —
+ * every other schema field (type, flags, labels) is unaffected.
  */
 import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
-import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { formatOcapiReadFailure, withSfccReadErrorBoundary } from "./read-result.js";
+import { readSfccBody } from "./read-body.js";
+import { applyProjectionToBody, projectionInputFor, projectionQueryEntries, } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
 // Annotations (SPEC: read-only against developer sandboxes)
@@ -30,19 +37,23 @@ const READ_ANNOTATIONS = {
 const systemObjectListInput = z.object({
     count: z.number().optional().describe("Maximum number of system object types to return."),
     start: z.number().optional().describe("Zero-based offset for paging."),
+    projection: projectionInputFor("broad_list"),
 });
+// No `projection` field: GET /system_object_definitions/{type} already returns
+// its complete document and ignores `select` (verified live — 13 keys with and
+// without it). A flag here would have no observable effect, which is the defect
+// BAPI-760 removed from this same tool. See read-projection.ts.
 const systemObjectGetInput = z.object({
     object_type: z.string().describe("System object type identifier, e.g. \"Product\" or \"Order\"."),
-    expand_attribute_definitions: z.boolean().optional().describe("When true, include the full attribute definition list in the response. " +
-        "May produce a large payload — auto-saved locally when oversized."),
 });
 const systemObjectAttributeSearchInput = z.object({
     object_type: z.string().describe("System object type to search within, e.g. \"Order\"."),
-    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for a text search across id and display_name, " +
-        "or a structured OCAPI query object (term_query, filtered_query, etc.)."),
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. A plain string is a case-insensitive substring match across " +
+        "id and display_name; a structured OCAPI query object passes through unchanged."),
     start: z.number().optional().describe("Zero-based offset for paging."),
     count: z.number().optional().describe("Maximum number of results to return."),
     sorts: z.array(z.any()).optional().describe("Array of OCAPI sort descriptors."),
+    projection: projectionInputFor("attribute_search"),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -56,17 +67,19 @@ function safeType(objectType) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-async function saveAndReturn(text, dir, filename) {
-    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+async function saveAndReturn(text, dir, filename, page) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename, page);
     return textResult(output);
 }
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 function buildSystemObjectListHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { count, start } = systemObjectListInput.parse(args);
-        const queryParams = {};
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start, projection } = systemObjectListInput.parse(args);
+        const queryParams = {
+            ...projectionQueryEntries("broad_list", projection),
+        };
         if (count !== undefined)
             queryParams.count = String(count);
         if (start !== undefined)
@@ -76,34 +89,31 @@ function buildSystemObjectListHandler(gateDeps, getDocsDir) {
             : "";
         const result = await ocapiGet(`/system_object_definitions${queryStr}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildSystemObjectGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, expand_attribute_definitions } = systemObjectGetInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type } = systemObjectGetInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
-        const expandParam = expand_attribute_definitions === true
-            ? "?expand=attribute_definitions"
-            : "";
-        const result = await ocapiGet(`/system_object_definitions/${encodedType}${expandParam}`, credentials);
+        const result = await ocapiGet(`/system_object_definitions/${encodedType}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, query, start, count, sorts } = systemObjectAttributeSearchInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, query, start, count, sorts, projection } = systemObjectAttributeSearchInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
         // Coerce plain string queries into OCAPI text_query shape
         const resolvedQuery = typeof query === "string"
@@ -116,15 +126,16 @@ function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         if (sorts !== undefined)
             postBody.sorts = sorts;
+        applyProjectionToBody(postBody, "attribute_search", projection);
         const result = await ocapiPost(`/system_object_definitions/${encodedType}/attribute_definition_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the three SFCC system-object introspection read tools.
@@ -137,25 +148,26 @@ export function registerSystemObjectReadTools(registerTool, deps) {
         description: "List all system object types from the developer sandbox via " +
             "GET /system_object_definitions. Read-only. " +
             "Accepts optional `count` and `start` for paging (OCAPI default pagination applies when omitted). " +
-            "Oversized outputs are auto-saved locally and previewed inline.",
+            "Returns ids only by default; pass projection=full for all fields. " +
+            "Oversized outputs are auto-saved locally.",
         inputSchema: systemObjectListInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectListHandler(gateDeps, getDocsDir));
     registerTool("system_object_get", {
-        description: "Retrieve a system object type from the developer sandbox. Read-only. " +
+        description: "Retrieve a system object type definition from the developer sandbox. Read-only. " +
             "GET /system_object_definitions/{type}. " +
-            "Prefer system_object_attribute_search for targeted attribute lookups — " +
-            "use this for a full type dump or expanded attribute list " +
-            "(expand_attribute_definitions=true). Oversized payloads are auto-saved locally.",
+            "Prefer system_object_attribute_search for targeted attribute lookups. " +
+            "Oversized payloads are auto-saved locally.",
         inputSchema: systemObjectGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectGetHandler(gateDeps, getDocsDir));
     registerTool("system_object_attribute_search", {
         description: "Search attribute definitions for a system object type. Read-only. " +
             "POST /system_object_definitions/{type}/attribute_definition_search. " +
-            "Prefer over system_object_get+expand for targeted c_ attribute lookups. " +
-            "Pass a plain string for text search or a structured OCAPI query object. " +
-            "Oversized results are auto-saved locally.",
+            "Use for targeted c_ attribute lookups; returns each attribute's schema " +
+            "by default (default_value withheld). " +
+            "Pass a plain string for text search or a structured OCAPI query. " +
+            "Oversized results auto-saved locally.",
         inputSchema: systemObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir));

package/build/sfcc/sfcc-result.js

@@ -0,0 +1,106 @@
+/**
+ * The universal SFCC failure contract (BAPI-766).
+ *
+ * BAPI-759 unified the SFCC *read* surface behind one formatter. This module
+ * generalizes that formatter so the same envelope covers every SFCC tool: reads,
+ * all nine writes, the OCAPI call-time gate, and the separate WebDAV log surface.
+ * There is exactly one normalization and one serialization implementation here —
+ * two parallel formatters would let the read and write sides drift, which is the
+ * failure this module exists to prevent.
+ *
+ * Two things are unified:
+ *
+ *  1. **The protocol predicate.** Every formatted failure sets `isError: true`,
+ *     so a caller can detect "this call did not succeed" without parsing text.
+ *     `result.isError === true` is therefore a *total* predicate for failure
+ *     across the SFCC surface. `sfcc_setup_status` is the one deliberate
+ *     exemption: reporting a not-configured repository is its *successful*
+ *     output, and it sits outside every gate.
+ *
+ *  2. **The body shape.** Exactly one text content item, whose text parses as
+ *     `{ error: { code, status, message, source, details } }`. Those four
+ *     fields mean the same thing for an OCAPI fault, a tool-level guardrail, a
+ *     gate rejection, a WebDAV failure, and an unexpected internal failure — one
+ *     parse path reads all of them with no shape discrimination.
+ *
+ * Everything failure-specific lives under `error.details`, which is always
+ * present. An object-valued upstream body is preserved there verbatim, so
+ * upstream data is never discarded and never collides with the Bridge-owned
+ * envelope fields.
+ *
+ * Successful results are NOT passed through this formatter. `SfccToolResult`
+ * declares `isError` optional precisely so a content-only success (every
+ * successful read, every successful write) stays assignable without gaining the
+ * flag.
+ */
+// ---------------------------------------------------------------------------
+// Detail normalization
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object whose fields can be preserved in place. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Coerce arbitrary detail input into an object so `error.details` is always
+ * present and always the same kind of thing.
+ *
+ * A plain object is preserved verbatim (shallow copy) — this is what keeps an
+ * OCAPI fault body's `_v` / `fault.*` fields at their original nesting. Anything
+ * else (absent, null, a primitive, an array) is wrapped as `{ value }` rather
+ * than being spread, which would scatter an array across numeric keys or
+ * fabricate structure that upstream never sent.
+ */
+function normalizeDetails(details) {
+    if (details === undefined)
+        return {};
+    if (isPlainObject(details))
+        return { ...details };
+    return { value: details };
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+/**
+ * Format any SFCC failure into the unified protocol result.
+ *
+ * Returns exactly one text content item and sets `isError: true`. The text
+ * serializes exactly one top-level `error` object. This is the single
+ * serialization point for the whole SFCC surface.
+ */
+export function formatSfccFailure(input) {
+    const details = normalizeDetails(input.details);
+    // Only surface the upstream status when it actually differs from the status
+    // we are reporting. Equal statuses would be noise; a synthetic status has no
+    // upstream to report at all.
+    if (input.upstreamHttpStatus !== undefined &&
+        input.upstreamHttpStatus !== input.status) {
+        details.upstream_http_status = input.upstreamHttpStatus;
+    }
+    const envelope = {
+        error: {
+            code: input.code,
+            status: input.status,
+            message: input.message,
+            source: input.source,
+            details,
+        },
+    };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    };
+}
+/**
+ * Read-side name for the shared formatter, kept so BAPI-759's read call sites
+ * read naturally. It is a thin delegate, not a second implementation.
+ */
+export function formatSfccReadFailure(input) {
+    return formatSfccFailure(input);
+}
+/**
+ * Write-side name for the shared formatter. Same contract, same implementation —
+ * the discriminator between the two sides is `source`, not the function called.
+ */
+export function formatSfccWriteFailure(input) {
+    return formatSfccFailure(input);
+}

package/build/sfcc/tool-wrapper.js

@@ -12,23 +12,55 @@
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
 import { resolveSfccCredentials } from "./credentials.js";
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Not-configured envelope helpers
 // ---------------------------------------------------------------------------
+/**
+ * Appended to every gate diagnostic (BAPI-759).
+ *
+ * A hard protocol failure in a repository that simply is not an SFCC project
+ * must not send a calling agent into a retry or self-repair loop, so the
+ * message says so outright. It is appended to — never a replacement for — each
+ * failure class's own distinct diagnostic.
+ */
+const NO_RETRY_INSTRUCTION = "This repository is not configured for SFCC; do not retry SFCC tools.";
+/**
+ * Build the unified gate failure result.
+ *
+ * The gate's 503 is synthetic — it is Bridge's own status, not something OCAPI
+ * returned — so no upstream HTTP status is supplied and `details` carries only
+ * the preserved `failure_class`.
+ *
+ * This runs for READ AND WRITE tools alike. `withSfccGate` is shared
+ * infrastructure — the nine write handlers in `writes-system-object.ts`,
+ * `writes-custom-object-def.ts`, and `writes-site-preference.ts` all wrap
+ * themselves in it — so a gate rejection on a write tool returns this envelope
+ * with `isError: true` too. That is intended, not incidental: a write tool that
+ * never reached OCAPI produced no write, so the protocol failure is accurate.
+ * The flag is set unconditionally, with no per-tool branch, tool-name check, or
+ * read/write mode parameter, precisely so no caller has to know which side of
+ * the surface it is on.
+ *
+ * BAPI-766 closed the split BAPI-759 left behind: a write tool's OWN
+ * pre-transport failures (Zod, sandbox guard, id mismatch, unexpected throw) and
+ * its post-transport OCAPI failures now use this same envelope, built through
+ * the shared formatter in `sfcc-result.ts`. `write-gate-rejection.test.ts`
+ * drives the real gate through the real write handlers and asserts that the two
+ * origins now produce the same shape, so neither can drift silently.
+ *
+ * `sfcc_log_query` keeps its own separate gate (`withSfccLogGate`) because it
+ * authenticates over WebDAV Basic auth rather than the OCAPI AM-OAuth boundary.
+ * Only the failure representation is shared — those two gates are not merged.
+ */
 function notConfigured(failureClass, message) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    error: "NOT_CONFIGURED",
-                    status: 503,
-                    failure_class: failureClass,
-                    message,
-                }),
-            },
-        ],
-    };
+    return formatSfccFailure({
+        code: "NOT_CONFIGURED",
+        status: 503,
+        message: `${message} ${NO_RETRY_INSTRUCTION}`,
+        source: "gate",
+        details: { failure_class: failureClass },
+    });
 }
 // ---------------------------------------------------------------------------
 // Gate
@@ -41,6 +73,17 @@ function notConfigured(failureClass, message) {
  * 2. Validates the value is an SFCC version.
  * 3. Resolves dw.json credentials.
  * 4. Calls the inner handler only if all checks pass.
+ *
+ * Every early rejection is the unified `isError: true` result — unconditionally,
+ * with no tool-name check, per-tool branch, exemption flag, or gate-mode
+ * parameter. `sfcc_setup_status`, the one SFCC tool whose successful output *is*
+ * a not-configured report, is exempt structurally: `register.ts` registers it
+ * outside this gate, so no code here needs to know about it.
+ *
+ * On the success path the inner handler's result is returned directly — not
+ * cloned, wrapped, or re-formatted — so write handlers keep ownership of their
+ * own result bodies. The generic `R` preserves each caller's concrete result
+ * type through the gate.
  */
 export function withSfccGate(deps, handler) {
     return async (args) => {