@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/sfcc/log-gate.js

@@ -11,20 +11,36 @@
  * (BM username + 40-char WebDAV access key) that lives entirely server-side; the
  * spike proved an AM bearer token 401s on `/Logs`. Readiness is resolved by the
  * backend `GET /jira/sfcc/logs/capability` probe, which never returns a secret.
+ *
+ * BAPI-766 changed only the *representation* of this gate's failures: they now
+ * use the universal SFCC envelope from `sfcc-result.ts`, so one detection rule
+ * (`result.isError === true`) and one parse path cover the log surface too. The
+ * gate itself remains operationally separate — the WebDAV Basic-auth boundary is
+ * still distinct from the OCAPI AM-OAuth boundary, and the two gates are not
+ * merged. A capability-probe failure is reported with source `"webdav"`, never
+ * `"ocapi"`, because that is where it actually originates.
  */
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Envelope helpers
 // ---------------------------------------------------------------------------
-function jsonResult(payload) {
-    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
-}
+/**
+ * Build the unified log-gate not-configured failure.
+ *
+ * The 503 is synthetic — Bridge's own status, not something WebDAV returned — so
+ * no upstream HTTP status is supplied. `source` is `"gate"`, matching the OCAPI
+ * gate: the rejection is the gate's decision, not an upstream response.
+ */
 function notConfigured(failureClass, message, limits) {
-    return jsonResult({
-        error: "NOT_CONFIGURED",
+    return formatSfccFailure({
+        code: "NOT_CONFIGURED",
         status: 503,
-        failure_class: failureClass,
         message,
-        ...(limits !== undefined ? { limits } : {}),
+        source: "gate",
+        details: {
+            failure_class: failureClass,
+            ...(limits !== undefined ? { limits } : {}),
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -54,22 +70,33 @@ export function withSfccLogGate(deps, handler) {
             const resp = await fetch(url, { headers: await deps.getGetHeaders() });
             if (!resp.ok) {
                 // Distinguish a Bridge auth/connectivity failure from "not configured".
-                return jsonResult({
-                    error: resp.status === 401 || resp.status === 403 ? "UNAUTHORIZED" : "SERVICE_UNAVAILABLE",
+                // The reported status IS the upstream status, so the shared formatter
+                // rightly omits a duplicate `upstream_http_status`.
+                return formatSfccFailure({
+                    code: resp.status === 401 || resp.status === 403
+                        ? "UNAUTHORIZED"
+                        : "SERVICE_UNAVAILABLE",
                     status: resp.status,
                     message: "Could not read the SFCC log capability from Bridge API " +
                         "(/jira/sfcc/logs/capability). Ensure your Bridge API key is set and the " +
                         "repo is authorized. Run sfcc_setup_status for a full diagnostic.",
+                    source: "webdav",
+                    details: {},
+                    upstreamHttpStatus: resp.status,
                 });
             }
             body = (await resp.json());
         }
         catch {
-            return jsonResult({
-                error: "BAD_GATEWAY",
+            // A synthetic 502: no upstream responded at all, so no upstream status
+            // may be reported.
+            return formatSfccFailure({
+                code: "BAD_GATEWAY",
                 status: 502,
                 message: "Could not reach Bridge API to resolve the SFCC log capability. " +
                     "Check that BAPI_BASE_URL points to a running Bridge API instance.",
+                source: "webdav",
+                details: {},
             });
         }
         if (body?.configured !== true) {

package/build/sfcc/log-query.js

@@ -11,9 +11,17 @@
  * The backend response has already passed through the `RedactionPort`, so its JSON
  * is returned to the LLM unchanged; there is deliberately NO local retrieval
  * bypass in TypeScript.
+ *
+ * BAPI-766 moved this tool's failure representation onto the universal SFCC
+ * envelope (`sfcc-result.ts`), so `result.isError === true` and one parse path
+ * cover the log surface exactly as they cover reads and writes. Redaction is
+ * untouched: a non-OK backend response contributes only its Bridge-authored
+ * string `detail` to `error.details`, and never raw text or an unknown payload
+ * whose redaction cannot be established (see `safeBackendDetail`).
  */
 import { z } from "zod";
 import { withSfccLogGate } from "./log-gate.js";
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Bounds — mirror src/python/sfcc_monitor/log_query.py (kept in lock-step).
 // ---------------------------------------------------------------------------
@@ -24,11 +32,42 @@ const MAX_SELECTED_PREFIXES = 5;
 const MAX_MAX_ENTRIES = 2000;
 const SUPPORTED_ENVIRONMENTS = ["production", "staging", "development"];
 const PREFIX_RE = /^[a-z][a-z0-9]*$/;
-function jsonResult(payload) {
-    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+/** Bridge-authored message for a non-OK backend query response. */
+function backendFailureMessage(status) {
+    return (`The Bridge API SFCC log-query endpoint returned HTTP ${status}. ` +
+        `No log content is included in this response.`);
+}
+/**
+ * Project a non-OK backend response body down to what is provably safe.
+ *
+ * Every failure the backend raises (`api/routes/sfcc_log_query.py`) is an
+ * `HTTPException` whose `detail` is a fixed Bridge-authored string — never log
+ * content. Anything else (a request-validation 422's structured list, an
+ * unparsed body, an unexpected payload) has no redaction guarantee, so it is
+ * dropped rather than forwarded. Redaction is a shipped safety property
+ * (BAPI-554); reformatting must not become a way around it.
+ */
+function safeBackendDetail(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const detail = parsed.detail;
+    return typeof detail === "string" ? { detail } : {};
 }
 function validationError(message) {
-    return jsonResult({ error: "VALIDATION_ERROR", status: 400, message });
+    return formatSfccFailure({
+        code: "VALIDATION_ERROR",
+        status: 400,
+        message,
+        source: "tool",
+        details: {},
+    });
 }
 // ---------------------------------------------------------------------------
 // Zod input schema
@@ -118,26 +157,27 @@ function buildHandler(deps) {
             });
         }
         catch {
-            return jsonResult({
-                error: "BAD_GATEWAY",
+            // Synthetic 502: nothing responded, so no upstream status may be reported.
+            return formatSfccFailure({
+                code: "BAD_GATEWAY",
                 status: 502,
                 message: "Could not reach Bridge API to run the SFCC log query. Check that " +
                     "BAPI_BASE_URL points to a running Bridge API instance.",
+                source: "webdav",
+                details: {},
             });
         }
         const text = await resp.text();
         if (!resp.ok) {
-            let detail = text;
-            try {
-                detail = JSON.parse(text);
-            }
-            catch {
-                /* keep raw text detail */
-            }
-            return jsonResult({
-                error: resp.status >= 500 ? "SERVICE_UNAVAILABLE" : "REQUEST_FAILED",
+            // The reported status IS the upstream status, so the shared formatter
+            // rightly omits a duplicate `upstream_http_status`.
+            return formatSfccFailure({
+                code: resp.status >= 500 ? "SERVICE_UNAVAILABLE" : "REQUEST_FAILED",
                 status: resp.status,
-                detail,
+                message: backendFailureMessage(resp.status),
+                source: "webdav",
+                details: safeBackendDetail(text),
+                upstreamHttpStatus: resp.status,
             });
         }
         // The backend response has already passed through RedactionPort — return it

package/build/sfcc/ocapi-shape.js

@@ -5,13 +5,56 @@
  * envelope. This module provides a typed extractor for the `data` array so
  * sub-task read tools share one normalizer rather than each re-deriving the
  * shape.
+ *
+ * Collection metadata lives under a single `page` object rather than at the top
+ * level (BAPI-760). Two properties of that metadata are load-bearing:
+ *
+ *   - `returned` is the actual length of the `items` array this call produced.
+ *     It is never read from the upstream `count` field, because OCAPI's `count`
+ *     is a request-echo (the page size asked for) and not a guarantee about how
+ *     many records came back.
+ *   - `total` exists ONLY when OCAPI itself supplied a numeric `total`. It is
+ *     never inferred from `items.length`, and it is absent — not `null`, not
+ *     `0` — when OCAPI omitted it. A consumer that sees no `total` knows the
+ *     instance-wide count is genuinely unavailable rather than zero.
+ *
+ * Nesting the metadata under `page` also keeps it from colliding with fields
+ * that legitimately live inside the returned resources: an OCAPI attribute
+ * search document carries its own `count` and `hits`, and those stay untouched
+ * inside `items`.
+ *
+ * `page` is built strictly from properties of the collection envelope itself,
+ * never from a field promoted out of an individual item (BAPI-769). A bare
+ * object response is the one shape where this matters concretely: `items` is
+ * always that single object, so its own internal `total`/`count` describes hits
+ * *inside* the document, not a count of `items`, and is never attached to
+ * `page.total` — see the bare-object branch of `normalizeOcapiBody` below.
+ */
+/**
+ * Single constructor for page metadata, shared by both normalizers.
+ *
+ * Centralizing it means `returned`, `total`, and `has_more` cannot be derived
+ * two different ways in the strict and permissive paths. `total` is attached
+ * conditionally so an unsupplied total is an absent property rather than an
+ * explicit `undefined` that would serialize as a present-but-empty field.
  */
+function buildPageMeta(items, rawTotal, rawNext) {
+    const page = {
+        returned: items.length,
+        has_more: rawNext != null,
+    };
+    if (typeof rawTotal === "number") {
+        page.total = rawTotal;
+    }
+    return page;
+}
 /**
  * Parse a raw OCAPI response body into a normalized envelope result.
  *
  * Returns `null` when `body` is not a valid OCAPI paging envelope (missing
  * `data` array or `count` field), allowing callers to surface a structured
- * error instead of crashing.
+ * error instead of crashing. Strict validation is unchanged; only the returned
+ * metadata shape moved under `page`.
  */
 export function normalizeOcapiPage(body) {
     if (body === null ||
@@ -23,9 +66,7 @@ export function normalizeOcapiPage(body) {
     const envelope = body;
     return {
         items: envelope.data,
-        count: envelope.count,
-        total: envelope.total,
-        hasMore: envelope.next != null,
+        page: buildPageMeta(envelope.data, envelope.total, envelope.next),
     };
 }
 /**
@@ -40,11 +81,25 @@ export function normalizeOcapiPage(body) {
  *
  * Unlike `normalizeOcapiPage`, this function never returns null and is
  * forward-compatible with future OCAPI envelope shapes.
+ *
+ * Items are passed through verbatim in every branch. A bare object — including
+ * an attribute-search document with its own `count` and `hits` — becomes the
+ * single item unchanged; its `count` is never promoted to collection metadata,
+ * and a missing `hits` is never synthesized.
+ *
+ * `page` describes only the normalized `items` array; it is never built from a
+ * field promoted out of an item's own body (BAPI-769). The bare-object branch
+ * always produces exactly one item — the whole document — so a `total` count
+ * OCAPI reported about the document's own internal contents (e.g. a search
+ * document's zero-hit `total: 0`) is never attached to `page.total`, where it
+ * would misread as "0 of 1 returned item" for a wrapper whose `returned` is
+ * always 1. `page.total` is therefore absent on every bare-object response;
+ * `has_more` is unaffected — it still reflects the bare object's own `next`.
  */
 export function normalizeOcapiBody(body) {
     // Bare array
     if (Array.isArray(body)) {
-        return { items: body, count: body.length, total: undefined, hasMore: false };
+        return { items: body, page: buildPageMeta(body, undefined, null) };
     }
     // Object forms
     if (body !== null && typeof body === "object") {
@@ -52,18 +107,19 @@ export function normalizeOcapiBody(body) {
         // Wrapped envelope: has a data array (with or without explicit count)
         if (Array.isArray(obj.data)) {
             const items = obj.data;
-            return {
-                items,
-                count: typeof obj.count === "number" ? obj.count : items.length,
-                total: typeof obj.total === "number" ? obj.total : undefined,
-                hasMore: obj.next != null,
-            };
+            return { items, page: buildPageMeta(items, obj.total, obj.next) };
         }
-        // Bare object (single resource, no wrapping envelope)
-        return { items: [body], count: 1, total: undefined, hasMore: false };
+        // Bare object (single resource, no wrapping envelope). `items` is always
+        // the single wrapper document, so `returned` is always 1 — a `total` (and,
+        // for a search document, `count`/`hits`) reported INSIDE that document is
+        // never promoted to `page.total`: it describes hits within the document,
+        // not a count of `items`. `page.total` is therefore always absent here
+        // (BAPI-769); `next` is still honored for `has_more`, which is unaffected.
+        const items = [body];
+        return { items, page: buildPageMeta(items, undefined, obj.next) };
     }
     // Non-object (null, string, number, etc.)
-    return { items: [], count: 0, total: undefined, hasMore: false };
+    return { items: [], page: buildPageMeta([], undefined, null) };
 }
 /**
  * SPEC §4.5 `value_type` mapper.

package/build/sfcc/output.js

@@ -4,23 +4,30 @@
  * Re-exports the truncation + docs-path utilities through a stable sfcc/
  * interface so sub-task read tools import from here instead of reaching into
  * the host module directly. This boundary makes a future extraction cheap.
+ *
+ * Oversized responses return a JSON descriptor rather than a sliced prefix
+ * (BAPI-760). Slicing a serialized JSON payload at a fixed character offset
+ * almost always cuts mid-token, so what reached the caller was neither the data
+ * nor valid JSON — and appending an English note made it unparseable by
+ * construction. Every branch here now emits JSON the caller can parse, and the
+ * collection metadata travels outside the omitted data so `returned`, `total`,
+ * and `has_more` survive truncation.
  */
 import path from "path";
 import { mkdir, writeFile } from "fs/promises";
 /** Maximum characters returned inline; content beyond this is saved locally. */
 export const SFCC_MAX_INLINE = 50_000;
-/** Truncation note appended to truncated payloads. */
-function truncationNote(savedPath) {
-    return `\n\n[Response truncated — full payload saved to ${savedPath}]`;
-}
 /**
  * If `text` exceeds `SFCC_MAX_INLINE`, save it to `dir/filename` and return a
- * truncated version with a local-path note. Otherwise returns `text` unchanged.
+ * JSON truncation descriptor naming the saved file and carrying `page`.
+ * Otherwise returns `text` unchanged.
  *
- * Write failures are non-fatal: the full (un-truncated) text is returned with
- * a warning rather than throwing.
+ * Write failures are non-fatal: a JSON save-failure descriptor carrying the
+ * complete payload is returned rather than throwing. This is deliberately kept
+ * on the successful-read path — the OCAPI read itself succeeded, so it does not
+ * route through `formatSfccReadFailure` and does not set `isError`.
  */
-export async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
+export async function truncateAndSaveIfNeeded(text, dir, filename, page, deps = {}) {
     if (text.length <= SFCC_MAX_INLINE) {
         return text;
     }
@@ -32,8 +39,31 @@ export async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
         await wf(filePath, text, "utf-8");
     }
     catch (err) {
-        return (text +
-            `\n\nWarning: response was NOT truncated because local save failed: ${err instanceof Error ? err.message : String(err)}`);
+        const message = err instanceof Error ? err.message : String(err);
+        const descriptor = {
+            truncated: false,
+            save_failed: true,
+            oversized: true,
+            warning: `Response was NOT truncated because the local save failed: ${message}. ` +
+                `The complete payload is returned inline.`,
+            page,
+        };
+        // Parse before embedding so callers receive JSON data rather than a
+        // JSON string containing escaped JSON. If the caller's text was never
+        // valid JSON, fall back to carrying it verbatim as a string — the helper
+        // itself must never emit invalid JSON.
+        try {
+            descriptor.data = JSON.parse(text);
+        }
+        catch {
+            descriptor.data_text = text;
+        }
+        return JSON.stringify(descriptor);
     }
-    return text.slice(0, SFCC_MAX_INLINE) + truncationNote(filePath);
+    const descriptor = {
+        truncated: true,
+        saved_path: filePath,
+        page,
+    };
+    return JSON.stringify(descriptor);
 }

package/build/sfcc/permissions.js

@@ -82,7 +82,6 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
     }
     if (result.ok) {
         const normalized = normalizeOcapiPage(result.body);
-        const itemCount = normalized ? normalized.count : "unknown";
         return {
             content: [
                 {
@@ -90,7 +89,7 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
                     text: `✓ OCAPI access confirmed.\n` +
                         `  Instance: ${credentials.hostname.split(".")[0]}\n` +
                         `  OCAPI version: ${ocapiVersion}\n` +
-                        `  GET /system_object_definitions: ${itemCount} items returned`,
+                        `  GET /system_object_definitions: ${formatProbeCount(normalized)}`,
                 },
             ],
         };
@@ -116,6 +115,29 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
         ],
     };
 }
+/**
+ * Render the probe's count line without overstating what OCAPI reported.
+ *
+ * The probe reads one page, so the number of records it got back is a page
+ * count, not the instance-wide total. Saying "N items returned" made a page of
+ * 25 look like an instance that owns exactly 25 system objects. Three distinct
+ * cases are now distinguishable:
+ *
+ *   - OCAPI supplied a total  → "25 of 73 items returned"
+ *   - OCAPI omitted the total → the number is labelled as the current page and
+ *     the missing instance total is stated outright
+ *   - strict normalization failed → neither number is claimed
+ */
+function formatProbeCount(normalized) {
+    if (!normalized) {
+        return "page count and instance total unavailable (unrecognized response envelope)";
+    }
+    const { returned, total } = normalized.page;
+    if (total !== undefined) {
+        return `${returned} of ${total} items returned`;
+    }
+    return `${returned} items returned on this page (OCAPI did not provide the instance total)`;
+}
 function ocapiSettingsInstructions(ocapiVersion) {
     return (`To grant OCAPI access, paste the JSON below in Business Manager:\n` +
         `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +

package/build/sfcc/read-body.js

@@ -0,0 +1,92 @@
+/**
+ * SFCC read-body redaction seam (BAPI-769).
+ *
+ * `projection: "full"` (BAPI-767) makes several OCAPI Data API endpoints return
+ * complete attribute-definition documents — `system_object_attribute_search`,
+ * `custom_object_definition_attribute_*`, and `system_object_definitions/{type}/
+ * attribute_definitions/{id}`. Live sandbox verification (OCAPI Data API v25_6)
+ * showed one of those 27 keys is not schema metadata about the attribute: it is
+ * the attribute's own runtime VALUE. `default_value` can carry a real
+ * configuration value — an attribute named `llmAvailableModelsJson` can carry
+ * actual model-routing config as its default — and that value must never reach
+ * an MCP caller, in the inline response, the `docs/tmp/sfcc/` save, or a
+ * successful attribute-definition write echo.
+ *
+ * This module owns exactly that: withholding one named structured field. It
+ * deliberately does NOT port `src/python/sfcc_monitor/adapters/redaction.py`'s
+ * regex/entropy engine — there is nothing to detect heuristically, only one key
+ * to withhold — and it deliberately does NOT redact inside `ocapi-shape.ts`.
+ * `normalizeOcapiBody`'s documented invariant is verbatim passthrough; folding
+ * redaction into it would make that no longer true. `readSfccBody` composes the
+ * two steps explicitly instead: redact first, normalize second.
+ *
+ * Attribute default values are intentionally unavailable through this MCP
+ * surface. Business Manager (Administration → Site Development → an object
+ * type's attribute definition) is the supported path to read one.
+ */
+import { normalizeOcapiBody } from "./ocapi-shape.js";
+/**
+ * Marker substituted for a withheld `default_value` node.
+ *
+ * Deliberately distinct from the log-query system's own `[REDACTED]` marker
+ * (`sfcc/log-query.ts` and friends) — the two redaction seams are unrelated:
+ * this one withholds one named structured field before normalization, the log
+ * seam performs regex/entropy scrubbing of log text. Conflating the markers
+ * would make a caller unable to tell which seam produced a given redaction.
+ */
+export const BRIDGE_REDACTED_MARKER = "[REDACTED_BY_BRIDGE]";
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Recursively withhold every `default_value` key found anywhere in `body`.
+ *
+ * Whenever an object carries an own `default_value` key, that key's ENTIRE
+ * value — including the `object_attribute_value_definition` wrapper OCAPI
+ * shapes it as (`{ _type, id, position, value }`) — is replaced with
+ * `BRIDGE_REDACTED_MARKER`. The key itself is always kept; only its value
+ * changes. Recursion continues into every sibling and into the rest of the same
+ * object/array, so a document that embeds another attribute-definition-shaped
+ * object deeper in its tree is still covered — the live key survey found only
+ * one `default_value` per document, but the walker stays general rather than
+ * hard-coding that shape.
+ *
+ * Side-effect-free: `body` is never mutated. A fresh tree is built and
+ * returned, so the caller's original object is unchanged after the call. A
+ * `default_value` key that was never present on the source is never
+ * synthesized — absence stays absence.
+ */
+export function redactSfccBody(body) {
+    if (Array.isArray(body)) {
+        return body.map((item) => redactSfccBody(item));
+    }
+    if (isPlainObject(body)) {
+        const result = {};
+        for (const [key, value] of Object.entries(body)) {
+            // Object.entries only yields own enumerable properties, so reaching this
+            // branch already means `body` owns `default_value` — no key is ever added
+            // where the source never had one.
+            if (key === "default_value") {
+                result[key] = BRIDGE_REDACTED_MARKER;
+                continue;
+            }
+            result[key] = redactSfccBody(value);
+        }
+        return result;
+    }
+    return body;
+}
+/**
+ * Redact, then normalize, a raw OCAPI response body.
+ *
+ * This is the read-path replacement for calling `normalizeOcapiBody` directly.
+ * Redaction happens BEFORE normalization, serialization, truncation, or save —
+ * one placement covers the inline MCP response and the `docs/tmp/sfcc/` save
+ * path identically, because both are derived from this same normalized result.
+ * `normalizeOcapiBody` itself remains a non-redacting verbatim shaper; it is
+ * `readSfccBody` that owns the redaction decision.
+ */
+export function readSfccBody(body) {
+    return normalizeOcapiBody(redactSfccBody(body));
+}