@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/sfcc/read-projection.js

@@ -0,0 +1,185 @@
+/**
+ * SFCC read projection policy (BAPI-767).
+ *
+ * WHY THIS MODULE EXISTS
+ * ----------------------
+ * Before BAPI-767 no `select` was constructed anywhere in the SFCC read path.
+ * The only occurrence of the OCAPI full-projection expression in the tree was
+ * the *grant template* in `permissions.ts` (`read_attributes: "(**)"`) — a
+ * permission the tools were never actually exercising. The consequence was the
+ * headline finding of the 2026-08-11 introspection report: an agent could
+ * enumerate every attribute id on a type and learn nothing about any of them —
+ * not the `value_type`, not `mandatory`, `localizable`, `searchable`, or
+ * `site_specific`. The MCP could *write* a type it could not read back.
+ *
+ * The fix is a projection, and the reason it lives in one module rather than in
+ * each handler is that the *default* is the load-bearing part. "Complete by
+ * default on attribute reads, lean by default on broad lists" is a single
+ * ratified policy; six handlers each deciding their own default is how that
+ * policy silently drifts. Requirement 2 of the ticket asks for exactly one
+ * place with its own test, and this is it.
+ *
+ * THE `(**)` EXPRESSION IS PRIVATE
+ * --------------------------------
+ * Callers select a `projection` of `"full"` or `"lean"`. They never see or pass
+ * raw OCAPI select syntax. That keeps the tool surface stable if the expression
+ * ever changes, and — more importantly — stops an agent from constructing an
+ * arbitrary select expression against a live instance.
+ *
+ * EVERY CATEGORY HERE WAS VERIFIED LIVE
+ * -------------------------------------
+ * The category table is not documentation-sourced. Each entry was probed
+ * against a developer sandbox (OCAPI Data API v25_6) before it was written, and
+ * the observed key-count expansion is recorded next to it. This matters because
+ * an unverified projection flag is worse than no flag: it reads as a capability
+ * and delivers nothing.
+ *
+ * `system_object_get` is deliberately ABSENT from this policy. Its endpoint,
+ * GET /system_object_definitions/{type}, already returns its complete 13-field
+ * document and ignores `select` entirely (verified: 13 keys with and without).
+ * Giving it a `projection` flag would ship a parameter with no observable
+ * effect — the same defect BAPI-760 removed from that very tool when it deleted
+ * the no-op `expand_attribute_definitions` boolean. A tool that cannot honor a
+ * projection does not get a projection input.
+ */
+import { z } from "zod";
+/** The two projection values, as a runtime-checkable list. */
+export const SFCC_READ_PROJECTIONS = ["full", "lean"];
+// ---------------------------------------------------------------------------
+// The policy
+// ---------------------------------------------------------------------------
+/**
+ * OCAPI's full-projection expression.
+ *
+ * Intentionally NOT exported. Only `selectExpressionFor` may map a projection
+ * onto it, so there is exactly one place where an outbound `select` value can
+ * originate.
+ */
+const FULL_SELECT_EXPRESSION = "(**)";
+/**
+ * The single endpoint-category → projection policy table (Requirement 2).
+ *
+ * Verified live against a developer sandbox, 2026-08-13 (OCAPI v25_6). The
+ * key-count expansions below are observations, not estimates:
+ *
+ *   attribute_search      POST .../attribute_definition_search
+ *                         system_object:        4 → 25 keys
+ *                         custom_object_def:    4 → 26 keys
+ *   attribute_collection  GET  .../attribute_definitions
+ *                         custom_object_def:    4 → 26 keys
+ *   broad_list            GET  /system_object_definitions
+ *                                               4 → 13 keys
+ *                         GET  .../SitePreferences/attribute_groups
+ *                                               4 → 10 keys
+ *
+ * The ratified requirement these defaults encode: complete by default on
+ * attribute reads, lean by default on broad lists, caller can override in
+ * either direction. An opt-in-only flag was explicitly rejected — the caller
+ * who does not know to ask is precisely the caller the report described.
+ */
+const PROJECTION_POLICY = {
+    attribute_search: {
+        defaultProjection: "full",
+        placement: "body",
+        inputDescription: "Detail level. Default: full — OCAPI's complete metadata projection " +
+            "(value_type, mandatory, localizable, searchable, site_specific); " +
+            "default_value is withheld. lean returns ids only.",
+    },
+    attribute_collection: {
+        defaultProjection: "full",
+        placement: "query",
+        inputDescription: "Detail level. Default: full — OCAPI's complete metadata projection " +
+            "(value_type, mandatory, localizable, searchable, site_specific); " +
+            "default_value is withheld. lean returns ids only.",
+    },
+    broad_list: {
+        defaultProjection: "lean",
+        placement: "query",
+        inputDescription: "Detail level. Default: lean (ids only); full returns all fields.",
+    },
+};
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective projection for a category.
+ *
+ * An omitted / undefined request resolves to the category default. An explicit
+ * caller value always wins — including an explicit `"lean"` on a full-default
+ * category, which is the "override in either direction" half of the
+ * requirement and is easy to lose to a truthiness check.
+ */
+export function resolveReadProjection(category, requested) {
+    return requested ?? PROJECTION_POLICY[category].defaultProjection;
+}
+/** The wire placement (`body` or `query`) for a category. */
+export function projectionPlacementFor(category) {
+    return PROJECTION_POLICY[category].placement;
+}
+/**
+ * Map an effective projection onto an OCAPI `select` expression.
+ *
+ * Returns `undefined` for `lean` — deliberately, so `lean` means "send no
+ * `select` at all" rather than "send an empty one". OCAPI's unqualified
+ * response is the lean shape; there is no lean expression to construct.
+ */
+export function selectExpressionFor(projection) {
+    return projection === "full" ? FULL_SELECT_EXPRESSION : undefined;
+}
+// ---------------------------------------------------------------------------
+// Application helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply the resolved projection to an OCAPI search POST body.
+ *
+ * Mutates and returns `body` so a handler can build its body normally and then
+ * hand it here as the last step. A `lean` resolution leaves the body untouched
+ * — no `select` key is added.
+ *
+ * Throws if the category is not body-placed, rather than silently writing a
+ * `select` into a body OCAPI would ignore for that endpoint.
+ */
+export function applyProjectionToBody(body, category, requested) {
+    if (projectionPlacementFor(category) !== "body") {
+        throw new Error(`SFCC read category "${category}" carries its projection in the query string, not the POST body.`);
+    }
+    const expression = selectExpressionFor(resolveReadProjection(category, requested));
+    if (expression !== undefined) {
+        body.select = expression;
+    }
+    return body;
+}
+/**
+ * Query-string entries carrying the resolved projection.
+ *
+ * Returns an empty object for `lean`, so a caller can spread it unconditionally
+ * into its query params without a conditional at each call site.
+ *
+ * Throws if the category is body-placed, for the same reason as above.
+ */
+export function projectionQueryEntries(category, requested) {
+    if (projectionPlacementFor(category) !== "query") {
+        throw new Error(`SFCC read category "${category}" carries its projection in the POST body, not the query string.`);
+    }
+    const expression = selectExpressionFor(resolveReadProjection(category, requested));
+    return expression === undefined ? {} : { select: expression };
+}
+// ---------------------------------------------------------------------------
+// Input schema
+// ---------------------------------------------------------------------------
+/**
+ * The optional `projection` Zod field for a category's input schema.
+ *
+ * The description is category-specific because the default differs by category,
+ * and the default is decision-critical *before* invocation — an agent choosing
+ * whether to pass `projection` cannot learn the answer from the response. It is
+ * kept to the fewest words that convey the default and the override, because
+ * every tool description and schema competes for the same tools/list token
+ * budget (see `integration/budget-config.ts`).
+ */
+export function projectionInputFor(category) {
+    return z
+        .enum(["full", "lean"])
+        .optional()
+        .describe(PROJECTION_POLICY[category].inputDescription);
+}

package/build/sfcc/read-result.js

@@ -0,0 +1,158 @@
+/**
+ * SFCC read boundary, layered on the universal SFCC result contract (BAPI-759,
+ * generalized by BAPI-766).
+ *
+ * This module owns the *read-specific* concerns: OCAPI fault-message extraction,
+ * the read-boundary error wrapper, and the fixed read messages. The envelope
+ * itself — normalization, serialization, and the `isError` predicate — lives in
+ * `sfcc-result.ts` and is shared with the write and WebDAV log surfaces, so
+ * there is exactly one implementation for the whole SFCC surface.
+ *
+ * Read handlers never construct an error envelope inline — they call
+ * `formatSfccReadFailure`, which is re-exported here as a thin delegate to the
+ * shared formatter.
+ *
+ * The unified guarantees (`isError: true` on every failure, and a body that
+ * parses as `{ error: { code, status, message, source, details } }`) are
+ * documented in `sfcc-result.ts`. An object-valued OCAPI body is preserved
+ * verbatim under `error.details` (`_v`, `fault.type`, `fault.message`,
+ * `fault.arguments` and any other upstream field), so upstream data is never
+ * discarded and never collides with the Bridge-owned envelope fields.
+ */
+import { z } from "zod";
+import { formatSfccFailure } from "./sfcc-result.js";
+export { formatSfccReadFailure } from "./sfcc-result.js";
+// ---------------------------------------------------------------------------
+// Fixed messages
+// ---------------------------------------------------------------------------
+/**
+ * The one message returned for an unexpected throw. Bridge-authored and fixed:
+ * the thrown value is never serialized, so a credential, token, request header,
+ * or stack frame carried by the exception cannot reach the caller.
+ */
+export const SFCC_INTERNAL_ERROR_MESSAGE = "An unexpected internal error occurred while handling this SFCC read. " +
+    "The underlying failure detail is withheld from this response to avoid " +
+    "leaking credentials or internal state.";
+/** The one message returned when arguments fail schema validation at the read boundary. */
+export const SFCC_VALIDATION_ERROR_MESSAGE = "Arguments failed schema validation before any OCAPI call was made. " +
+    "See error.details.issues for the offending fields.";
+/** Bridge-authored fallback used when an OCAPI body carries no usable `fault.message`. */
+export function ocapiFallbackMessage(status) {
+    return (`The SFCC OCAPI Data API returned HTTP ${status} for this read and supplied no ` +
+        `fault message. The upstream response body is preserved under error.details.`);
+}
+// ---------------------------------------------------------------------------
+// OCAPI read failures
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Format a non-OK OCAPI read response through the shared formatter.
+ *
+ * The message is the upstream `fault.message` when it is a non-empty string,
+ * otherwise a stable Bridge-authored fallback — raw response text is never
+ * promoted into `error.message`. The whole upstream body is preserved under
+ * `error.details`.
+ *
+ * `upstreamHttpStatus` exists for the case where Bridge reports a status other
+ * than the one HTTP returned. The OCAPI client does not currently normalize a
+ * read status (`ocapiGet`/`ocapiPost` surface `Response.status` verbatim), so
+ * in practice the two are equal and the field is omitted; the parameter keeps
+ * the seam honest if a normalization step is ever introduced.
+ */
+export function formatOcapiReadFailure(result, upstreamHttpStatus) {
+    return formatSfccFailure({
+        code: "OCAPI_FAULT",
+        status: result.status,
+        message: ocapiFaultMessage(result.body, result.status),
+        source: "ocapi",
+        details: result.body,
+        upstreamHttpStatus,
+    });
+}
+/** Pull a usable human-readable message out of an OCAPI fault body. */
+function ocapiFaultMessage(body, status) {
+    if (isPlainObject(body) && isPlainObject(body.fault)) {
+        const faultMessage = body.fault.message;
+        if (typeof faultMessage === "string" && faultMessage.trim() !== "") {
+            return faultMessage;
+        }
+    }
+    return ocapiFallbackMessage(status);
+}
+// ---------------------------------------------------------------------------
+// Read boundary
+// ---------------------------------------------------------------------------
+/**
+ * Recognize a Zod/schema failure without matching on the exception message.
+ *
+ * `instanceof` covers the normal case. The structural fallback covers a
+ * ZodError produced by a second copy of Zod (a duplicated dependency or a
+ * module-mocked import), where the prototype chain differs but the contract
+ * — a `ZodError` name plus an `issues` array — does not.
+ */
+function isSchemaFailure(err) {
+    if (err instanceof z.ZodError)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "ZodError" &&
+        Array.isArray(err.issues));
+}
+/** Reduce Zod issues to field path + code + message; nothing else is disclosed. */
+function safeZodIssues(err) {
+    const issues = Array.isArray(err.issues) ? err.issues : [];
+    return issues.map((issue) => ({
+        path: Array.isArray(issue.path) ? issue.path.map(String).join(".") : "",
+        code: typeof issue.code === "string" ? issue.code : "invalid",
+        message: typeof issue.message === "string" ? issue.message : "Invalid input.",
+    }));
+}
+/**
+ * Wrap a read tool callback so no failure escapes as a raw throw.
+ *
+ * This is the outermost project-owned callback for every SFCC read tool. It
+ * converts:
+ *
+ *   - a recognized Zod/schema failure → `VALIDATION_ERROR` (400, source `tool`)
+ *   - any other thrown value          → `INTERNAL_ERROR` (500, source `tool`)
+ *
+ * A result the inner handler *returns* — success or an already-formatted
+ * failure — is passed through untouched, so a gate rejection keeps its
+ * `NOT_CONFIGURED` code rather than being reclassified.
+ *
+ * Note on ordering: the MCP SDK validates `inputSchema` before invoking this
+ * callback and turns a rejection into its own `isError: true` result, so the
+ * transport path is already a tool result rather than a transport error. This
+ * boundary covers the paths the SDK does not: the handler's own `schema.parse`,
+ * in-process dispatch through `TOOL_HANDLERS` (which bypasses SDK validation
+ * entirely), and every unexpected throw from the gate, the OCAPI client, or the
+ * output seam.
+ */
+export function withSfccReadErrorBoundary(handler) {
+    return async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (err) {
+            if (isSchemaFailure(err)) {
+                return formatSfccFailure({
+                    code: "VALIDATION_ERROR",
+                    status: 400,
+                    message: SFCC_VALIDATION_ERROR_MESSAGE,
+                    source: "tool",
+                    details: { issues: safeZodIssues(err) },
+                });
+            }
+            return formatSfccFailure({
+                code: "INTERNAL_ERROR",
+                status: 500,
+                message: SFCC_INTERNAL_ERROR_MESSAGE,
+                source: "tool",
+                details: {},
+            });
+        }
+    };
+}

package/build/sfcc/reads-custom-object-def.js

@@ -11,16 +11,32 @@
  * OCAPI's CustomObjectDefinitions resource only exposes operations scoped to
  * a known object_type — there is no top-level list and no bare get-by-type
  * (unlike SystemObjectDefinitions). A caller-supplied object_type is always
- * required; OCAPI cannot enumerate custom object types.
+ * required; OCAPI cannot enumerate custom object type IDs directly.
+ *
+ * That is narrower than "wholly undiscoverable," and the tools below say so:
+ * `system_object_list` at `projection: "full"` returns a distinct
+ * `display_name` and `attribute_definition_count` per custom type, from which a
+ * candidate ID can be derived (e.g. strip spaces from "Product Quality Result"
+ * → "ProductQualityResult") and confirmed by checking that this module's own
+ * `custom_object_definition_attributes_get` returns an attribute count matching
+ * that row's `attribute_definition_count`. This adds no new tool and no new
+ * projection value — it is existing capability, stated accurately.
  *
  * Note: custom object TYPE creation/update is NOT available via OCAPI REST.
  * It is a v2 metadata-import capability (metadata XML → WebDAV → import job).
+ *
+ * Both tools 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)
@@ -34,22 +50,23 @@ const READ_ANNOTATIONS = {
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
+const OBJECT_TYPE_DISCOVERY_HINT = 'Known custom object type id (e.g. starting with "c_"). OCAPI cannot enumerate ' +
+    "type IDs directly, but you can discover a candidate via system_object_list at " +
+    "projection=\"full\" (distinct display_name + attribute_definition_count per " +
+    "custom type) and confirm it by checking that this tool's returned attribute " +
+    "count matches that row's attribute_definition_count.";
 const customObjectAttributesGetInput = z.object({
-    object_type: z
-        .string()
-        .describe('Known custom object type identifier, e.g. a custom type id starting with "c_". ' +
-        "OCAPI cannot enumerate custom object types — the type must already be known."),
+    object_type: z.string().describe(OBJECT_TYPE_DISCOVERY_HINT),
+    projection: projectionInputFor("attribute_collection"),
 });
 const customObjectAttributeSearchInput = z.object({
-    object_type: z
-        .string()
-        .describe('Known custom object type to search within, e.g. a custom type id starting with "c_". ' +
-        "OCAPI cannot enumerate custom object types — the type must already be known."),
-    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.)."),
+    object_type: z.string().describe(OBJECT_TYPE_DISCOVERY_HINT),
+    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
@@ -63,30 +80,34 @@ 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 buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type } = customObjectAttributesGetInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, projection } = customObjectAttributesGetInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
-        const result = await ocapiGet(`/custom_object_definitions/${encodedType}/attribute_definitions`, credentials);
+        const queryEntries = projectionQueryEntries("attribute_collection", projection);
+        const queryStr = Object.keys(queryEntries).length > 0
+            ? "?" + new URLSearchParams(queryEntries).toString()
+            : "";
+        const result = await ocapiGet(`/custom_object_definitions/${encodedType}/attribute_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, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, query, start, count, sorts } = customObjectAttributeSearchInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, query, start, count, sorts, projection } = customObjectAttributeSearchInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
         // Coerce plain string queries into OCAPI text_query shape
         const resolvedQuery = typeof query === "string"
@@ -99,15 +120,16 @@ function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         if (sorts !== undefined)
             postBody.sorts = sorts;
+        applyProjectionToBody(postBody, "attribute_search", projection);
         const result = await ocapiPost(`/custom_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, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the two SFCC custom-object-definition introspection read tools.
@@ -118,18 +140,19 @@ export function registerSfccCustomObjectDefReadTools(registerTool, deps) {
     const { gateDeps, getDocsDir } = deps;
     registerTool("custom_object_definition_attributes_get", {
         description: "Retrieve attribute definitions for a KNOWN custom object type via " +
-            "GET /custom_object_definitions/{type}/attribute_definitions. " +
-            "OCAPI cannot enumerate types — object_type is required. " +
-            "Type creation is v2 metadata-import only, not OCAPI. Oversized payloads auto-saved locally.",
+            "GET /custom_object_definitions/{type}/attribute_definitions " +
+            "(default_value withheld). OCAPI cannot enumerate type IDs directly; " +
+            "derive one via system_object_list (projection=full, attribute_definition_count), " +
+            "confirm here. Type creation is v2 metadata-import only.",
         inputSchema: customObjectAttributesGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir));
     registerTool("custom_object_definition_attribute_search", {
         description: "Search attribute definitions within a KNOWN custom object type via " +
-            "POST /custom_object_definitions/{type}/attribute_definition_search. " +
-            "OCAPI cannot enumerate types — object_type is required. " +
-            "Pass a string or structured OCAPI query. Type creation is v2 metadata-import only. " +
-            "Oversized results auto-saved locally.",
+            "POST /custom_object_definitions/{type}/attribute_definition_search " +
+            "(default_value withheld). OCAPI cannot enumerate type IDs directly; " +
+            "derive one via system_object_list (projection=full, attribute_definition_count), " +
+            "confirm here. Type creation is v2 metadata-import only.",
         inputSchema: customObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir));