@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/sfcc/write-grants.js

@@ -2,11 +2,18 @@
  * Shared OCAPI write-grant JSON helpers (BAPI-582 foundation).
  *
  * This module is the single source of truth for the OCAPI write-grant JSON that
- * is both echoed by future write handlers on a 403 and printed by the
+ * is both echoed by write handlers on a 403 and printed by the
  * `check_permissions` diagnostic. Keeping one definition guarantees the
  * remediation JSON an operator sees is identical no matter which surface it
  * comes from.
+ *
+ * BAPI-766 converted the 403 handler response from prose to the universal SFCC
+ * failure envelope. The remediation is not lost — it moved from an English
+ * paragraph into structured, non-secret fields under `error.details.remediation`,
+ * where a caller can read it without parsing text and `result.isError === true`
+ * still detects the failure.
  */
+import { formatSfccWriteFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Write resource families
 // ---------------------------------------------------------------------------
@@ -52,29 +59,45 @@ export function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<
 // ---------------------------------------------------------------------------
 // 403 write-grant UX
 // ---------------------------------------------------------------------------
-/**
- * Build the human-facing 403 remediation text for a failed write operation.
- * Includes the 403 status, the failed operation/path, and the exact write-grant
- * JSON operators must paste in Business Manager.
- */
-export function buildOcapiWriteGrant403Text(params) {
-    const { operation, path, ocapiVersion, body } = params;
-    const bodyLine = body === undefined
-        ? ""
-        : `\nResponse body:\n${JSON.stringify(body, null, 2)}\n`;
-    return (`HTTP 403: OCAPI write access denied for ${operation} ${path}.\n` +
-        bodyLine +
-        `\nTo grant write access, paste the JSON below in Business Manager:\n` +
-        `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
-        `${formatOcapiWriteGrantJson(ocapiVersion)}\n\n` +
-        `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
+/** Where an operator pastes the grant JSON in Business Manager. */
+export const OCAPI_WRITE_GRANT_BUSINESS_MANAGER_PATH = "Administration > Site Development > Open Commerce API Settings → Data API tab";
+/** The one instruction an operator must act on after pasting the grant JSON. */
+export const OCAPI_WRITE_GRANT_CLIENT_ID_INSTRUCTION = "Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.";
+/** The fixed, Bridge-authored message for a 403 on an OCAPI write. */
+export function ocapiWriteForbiddenMessage(operation, path) {
+    return (`OCAPI write access denied for ${operation} ${path}. The client is not granted ` +
+        `write access to this resource. See error.details.remediation for the exact ` +
+        `write-grant settings to paste in Business Manager.`);
 }
 /**
- * MCP-shaped wrapper around `buildOcapiWriteGrant403Text` so future write
- * handlers can return the grant UX without re-implementing content wrapping.
+ * Build the unified 403 failure for a denied OCAPI write.
+ *
+ * The remediation an operator needs — where to paste, what to paste, and the one
+ * substitution to make — is carried as structured fields under
+ * `error.details.remediation` rather than as prose, so the result is parseable
+ * and `isError: true` detects it like every other SFCC failure. The grant JSON
+ * keeps the `<YOUR_CLIENT_ID>` placeholder: the real resolved client_id is never
+ * substituted, so nothing secret enters the response.
+ *
+ * The upstream 403 body is preserved verbatim under `error.details.body`, the
+ * same way an OCAPI read fault body is preserved.
  */
 export function writeGrantForbiddenResult(params) {
-    return {
-        content: [{ type: "text", text: buildOcapiWriteGrant403Text(params) }],
-    };
+    const { operation, path, ocapiVersion, body } = params;
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
+        status: 403,
+        message: ocapiWriteForbiddenMessage(operation, path),
+        source: "ocapi",
+        details: {
+            operation,
+            path,
+            remediation: {
+                business_manager_path: OCAPI_WRITE_GRANT_BUSINESS_MANAGER_PATH,
+                instruction: OCAPI_WRITE_GRANT_CLIENT_ID_INSTRUCTION,
+                write_grant: buildOcapiWriteGrantSettings(ocapiVersion),
+            },
+            ...(body === undefined ? {} : { body }),
+        },
+    });
 }

package/build/sfcc/write-guard.js

@@ -6,14 +6,13 @@
  * mutation. A non-null return value is
  * the pre-formatted MCP rejection to return directly; a null return means the
  * effective instance is a sandbox and the handler may proceed.
+ *
+ * BAPI-766 moved the rejection's *representation* to the shared SFCC formatter
+ * so the guardrail fails at the protocol level like every other SFCC failure.
+ * The guard's decision is untouched: `undefined` still defaults to `"sandbox"`,
+ * `"sandbox"` still proceeds, and every other value is still refused.
  */
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/** Wrap text in the standard MCP text-result shape. */
-function textResult(text) {
-    return { content: [{ type: "text", text }] };
-}
+import { formatSfccWriteFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Guard
 // ---------------------------------------------------------------------------
@@ -22,18 +21,27 @@ function textResult(text) {
  *
  * SFCC write tools are sandbox-only in this foundation. The effective instance
  * defaults to `"sandbox"` when `undefined` (some schemas default the value
- * elsewhere), so an omitted instance is allowed. Any other value returns a
- * structured JSON validation error naming the rejected instance; a sandbox
- * returns `null` so the caller proceeds.
+ * elsewhere), so an omitted instance is allowed. Any other value returns the
+ * unified validation failure naming the rejected instance; a sandbox returns
+ * `null` so the caller proceeds.
+ *
+ * `details` carries non-sensitive guard metadata only — the rejected value is
+ * caller-supplied.
  */
 export function rejectIfNotSandboxForWrite(instance) {
     const effective = instance === undefined ? "sandbox" : instance;
     if (effective === "sandbox")
         return null;
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
         status: 400,
         message: `SFCC write tools are sandbox-only. Refusing to write against instance ` +
             `'${effective}'. Re-run the write against a developer sandbox instance.`,
-    }));
+        source: "tool",
+        details: {
+            guard: "sandbox_only",
+            received_instance: effective,
+            supported_instances: ["sandbox"],
+        },
+    });
 }

package/build/sfcc/write-result.js

@@ -1,26 +1,76 @@
 /**
- * Shared write-result formatter (BAPI-582 foundation).
+ * Shared write-result formatter (BAPI-582 foundation, unified by BAPI-766).
  *
- * This is the single formatting path for all future SFCC write tools. Handlers
- * pass the raw `OcapiGetResult` from `ocapiPut`/`ocapiPatch` here rather than
- * inventing their own 403/fault/success response logic, guaranteeing a
- * consistent surface across every write tool.
+ * This is the single formatting path for all SFCC write tools. Handlers pass the
+ * raw `OcapiGetResult` from `ocapiPut`/`ocapiPatch` here rather than inventing
+ * their own 403/fault/success response logic, guaranteeing a consistent surface
+ * across every write tool.
+ *
+ * Successful results never gain `isError`, but their echoed `body` is redacted
+ * (BAPI-769): an attribute-definition write's success body can carry the same
+ * `default_value` a read can, so it is withheld via `read-body.ts`'s
+ * `redactSfccBody` before serialization. Every other *failure* branch —
+ * including the 403 write-grant remediation, which used to be prose — returns
+ * the universal nested envelope from `sfcc-result.ts`, so `result.isError ===
+ * true` is total across a write tool's post-transport failures as well as its
+ * pre-transport ones.
  */
 import { writeGrantForbiddenResult } from "./write-grants.js";
 import { DEFAULT_OCAPI_VERSION } from "./config.js";
-/** Wrap text in the standard MCP text-result shape. */
+import { formatSfccWriteFailure } from "./sfcc-result.js";
+import { redactSfccBody } from "./read-body.js";
+/** Wrap text in the standard MCP text-result shape (success path only). */
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Bridge-authored fallback used when an OCAPI write body carries no usable `fault.message`. */
+export function ocapiWriteFallbackMessage(status) {
+    return (`The SFCC OCAPI Data API returned HTTP ${status} for this write and supplied no ` +
+        `fault message. The upstream response body is preserved under error.details.`);
+}
+/**
+ * Pull a usable human-readable message out of an OCAPI write fault body.
+ *
+ * Raw response text is never promoted into `error.message` — an unparsed body
+ * falls through to the stable Bridge-authored fallback instead.
+ */
+function ocapiWriteFaultMessage(body, status) {
+    if (isPlainObject(body) && isPlainObject(body.fault)) {
+        const faultMessage = body.fault.message;
+        if (typeof faultMessage === "string" && faultMessage.trim() !== "") {
+            return faultMessage;
+        }
+    }
+    return ocapiWriteFallbackMessage(status);
+}
+// ---------------------------------------------------------------------------
 // Formatter
 // ---------------------------------------------------------------------------
 /**
  * Format an OCAPI write result into the standard MCP tool response.
  *
- *  - `403` → the paste-ready write-grant remediation (via write-grants.ts).
- *  - success → JSON with `status`, `outcome`, and `body`.
- *  - other failure → JSON with `error: "OCAPI_WRITE_ERROR"`, `status`, `fault`, `body`.
+ *  - `403` → the unified failure carrying the paste-ready write-grant
+ *    remediation as structured data (via write-grants.ts).
+ *  - success → JSON with `status`, `outcome`, and `body`; no `isError`. `body`
+ *    is redacted (BAPI-769) before serialization: a successful
+ *    attribute-definition PUT/PATCH echoes the updated resource in the same
+ *    shape a GET returns, so it can carry a real `default_value` exactly like a
+ *    read can — `redactSfccBody` withholds it here the same way `readSfccBody`
+ *    withholds it on the read path. Every other key survives untouched.
+ *  - other failure → the unified `OCAPI_WRITE_ERROR` failure, source `ocapi`,
+ *    with the structured fault mapping and the upstream body under
+ *    `error.details`.
+ *
+ * No `upstreamHttpStatus` is supplied: `ocapiPut`/`ocapiPatch` surface
+ * `Response.status` verbatim, so the reported status *is* the upstream status
+ * and the shared formatter would rightly omit a duplicate.
  */
 export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion = DEFAULT_OCAPI_VERSION) {
     if (result.status === 403) {
@@ -35,13 +85,19 @@ export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion
         return textResult(JSON.stringify({
             status: result.status,
             outcome: result.outcome,
-            body: result.body,
+            body: redactSfccBody(result.body),
         }));
     }
-    return textResult(JSON.stringify({
-        error: "OCAPI_WRITE_ERROR",
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
         status: result.status,
-        fault: result.fault,
-        body: result.body,
-    }));
+        message: ocapiWriteFaultMessage(result.body, result.status),
+        source: "ocapi",
+        details: {
+            operation,
+            path,
+            fault: result.fault,
+            body: result.body,
+        },
+    });
 }

package/build/sfcc/write-tool-common.js

@@ -1,15 +1,26 @@
 /**
- * Shared helpers for the SFCC write MCP tools (BAPI-584).
+ * Shared helpers for the SFCC write MCP tools (BAPI-584, unified by BAPI-766).
  *
- * The two write-surface modules (`writes-custom-object-def.ts` and
- * `writes-site-preference.ts`) both need the same small set of primitives:
- * the destructive tool annotations, the MCP text-result shape, a consistent
- * set of safe pre-transport error envelopes (validation / unexpected), and a
- * single path-segment encoder. Centralizing them here guarantees every write
- * tool returns an identical envelope shape and never leaks a stack trace or a
- * raw thrown value to the caller.
+ * All nine write tools — the two custom-object-definition tools, the
+ * site-preference value tool, and the six system-object tools — need the same
+ * small set of primitives: the destructive tool annotations, the MCP text-result
+ * shape, a consistent set of safe pre-transport failure envelopes (validation /
+ * payload fault / unexpected), and a single path-segment encoder.
+ *
+ * Every failure helper here returns the *universal* nested failure envelope
+ * built by `sfcc-result.ts` — `{ error: { code, status, message, source,
+ * details } }` with `isError: true`. There is no write-local envelope
+ * construction and no second serialization path, so a write tool's own
+ * pre-transport failure is indistinguishable in shape from a gate rejection, an
+ * OCAPI read fault, or a WebDAV log failure. That is what makes
+ * `result.isError === true` a total predicate across the SFCC surface.
+ *
+ * Nothing here ever serializes a stack trace, a raw thrown value, or a complete
+ * Zod issue object: validation issues are projected down to `{ path, message }`.
  */
 import { z } from "zod";
+import { formatSfccWriteFailure } from "./sfcc-result.js";
+import { SfccWritePayloadFault } from "./writes-system-object-payloads.js";
 // ---------------------------------------------------------------------------
 // Annotations
 // ---------------------------------------------------------------------------
@@ -24,35 +35,86 @@ export const WRITE_ANNOTATIONS = {
     idempotentHint: false,
     openWorldHint: true,
 };
-/** Wrap text in the standard MCP text-result shape. */
+/** Wrap text in the standard MCP text-result shape (success path only). */
 export function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
-// Pre-transport error envelopes
+// Fixed messages
 // ---------------------------------------------------------------------------
 /**
- * Convert a Zod validation failure into a safe `VALIDATION_ERROR` envelope.
- * The flattened issues are surfaced so callers can see which field failed,
- * without exposing any thrown-error internals.
+ * The one message returned when write arguments fail schema validation. The
+ * offending fields are reported under `error.details.issues`, never inline.
+ */
+export const SFCC_WRITE_VALIDATION_ERROR_MESSAGE = "Input failed schema validation before any OCAPI call. " +
+    "See error.details.issues for the offending fields.";
+/**
+ * The one message returned for an unexpected throw inside a write handler.
+ * 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 function zodValidationEnvelope(err) {
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
+export const SFCC_WRITE_INTERNAL_ERROR_MESSAGE = "An unexpected internal error occurred while handling this SFCC write. " +
+    "The underlying failure detail is withheld from this response to avoid " +
+    "leaking credentials or internal state.";
+// ---------------------------------------------------------------------------
+// Pre-transport failure envelopes
+// ---------------------------------------------------------------------------
+/** Reduce Zod issues to field path + 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(".") : "",
+        message: typeof issue.message === "string" ? issue.message : "Invalid input.",
+    }));
+}
+/**
+ * Convert a Zod validation failure into the unified `VALIDATION_ERROR` envelope.
+ *
+ * Private: it has no caller outside this module — `preTransportErrorEnvelope`
+ * is the dispatcher every write handler actually uses. Issues are projected to
+ * the safe `{ path, message }` shape so no raw Zod issue object (with its
+ * `expected` / `received` / `unionErrors` internals) reaches a tool result.
+ */
+function zodValidationEnvelope(err) {
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
         status: 400,
-        message: "Input failed schema validation before any OCAPI call.",
-        issues: err.issues.map((issue) => ({
-            path: issue.path.join("."),
-            message: issue.message,
-        })),
-    }, null, 2));
+        message: SFCC_WRITE_VALIDATION_ERROR_MESSAGE,
+        source: "tool",
+        details: { issues: safeZodIssues(err) },
+    });
+}
+/**
+ * A local, pre-transport payload-shape failure surfaced in OCAPI-fault
+ * vocabulary (e.g. `IdConflictException`), without a network round trip.
+ *
+ * Private for the same reason as the Zod variant: handlers reach it through the
+ * dispatcher. `source` is `"tool"` — the fault was decided locally, so labelling
+ * it `"ocapi"` would claim OCAPI said something it never did.
+ */
+function payloadFaultEnvelope(fault) {
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
+        status: fault.status,
+        message: fault.message,
+        source: "tool",
+        details: { fault: { type: fault.faultType, message: fault.message } },
+    });
 }
 /**
  * A plain (non-Zod) validation rejection, e.g. a body/URL field mismatch that
- * the schema alone cannot express. Same envelope shape as the Zod variant.
+ * the schema alone cannot express. The caller's message is preserved verbatim;
+ * only the envelope around it changed.
  */
 export function validationEnvelope(message) {
-    return textResult(JSON.stringify({ error: "VALIDATION_ERROR", status: 400, message }, null, 2));
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
+        status: 400,
+        message,
+        source: "tool",
+        details: {},
+    });
 }
 /**
  * Safe fallback envelope for an unexpected thrown error inside a write handler
@@ -60,20 +122,52 @@ export function validationEnvelope(message) {
  * thrown value.
  */
 export function unexpectedEnvelope() {
-    return textResult(JSON.stringify({
-        error: "INTERNAL_ERROR",
+    return formatSfccWriteFailure({
+        code: "INTERNAL_ERROR",
         status: 500,
-        message: "Unexpected SFCC write tool failure.",
-    }, null, 2));
+        message: SFCC_WRITE_INTERNAL_ERROR_MESSAGE,
+        source: "tool",
+        details: {},
+    });
 }
 /**
- * Map a pre-transport error to its envelope: Zod validation errors become a
- * `VALIDATION_ERROR`, everything else becomes the generic `INTERNAL_ERROR`.
- * Used for the `.parse()` boundary before any OCAPI mutation.
+ * 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.
  */
-export function preTransportErrorEnvelope(err) {
+function isSchemaFailure(err) {
     if (err instanceof z.ZodError)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "ZodError" &&
+        Array.isArray(err.issues));
+}
+/** Recognize a local payload-shape fault, tolerating a duplicated module instance. */
+function isPayloadFault(err) {
+    if (err instanceof SfccWritePayloadFault)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "SfccWritePayloadFault" &&
+        typeof err.faultType === "string" &&
+        typeof err.status === "number");
+}
+/**
+ * Map a pre-transport error to its unified envelope: Zod validation failures
+ * become `VALIDATION_ERROR`, a recognized payload-shape fault becomes
+ * `OCAPI_WRITE_ERROR`, and everything else becomes the sanitized
+ * `INTERNAL_ERROR`. Used at the `.parse()` / payload-build boundary before any
+ * OCAPI mutation.
+ */
+export function preTransportErrorEnvelope(err) {
+    if (isSchemaFailure(err))
         return zodValidationEnvelope(err);
+    if (isPayloadFault(err))
+        return payloadFaultEnvelope(err);
     return unexpectedEnvelope();
 }
 // ---------------------------------------------------------------------------

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

@@ -8,7 +8,10 @@
  * Both tools write ATTRIBUTE DEFINITIONS on an already-known custom object type.
  * Custom object TYPE creation is intentionally NOT attempted: OCAPI cannot
  * create custom object types (that is a v2 metadata-import capability), so the
- * type must pre-exist. Mirrors reads-custom-object-def.ts.
+ * type must pre-exist. OCAPI also cannot enumerate custom object type IDs
+ * directly — see reads-custom-object-def.ts for the `system_object_list` +
+ * `projection: "full"` discovery path a caller can use to find one before
+ * writing to it. Mirrors reads-custom-object-def.ts.
  *
  * Every handler is call-time gated by `withSfccGate`, sandbox-guarded via
  * `rejectIfNotSandboxForWrite`, and routes its OCAPI result through
@@ -31,7 +34,8 @@ const createCustomObjectAttributeDefinitionInput = z.object({
     object_type: z
         .string()
         .describe('Known custom object type identifier (must already exist). OCAPI cannot ' +
-        "enumerate or create custom object types — only attribute definitions on a known type."),
+        "create types, and cannot enumerate type IDs directly — only attribute " +
+        "definitions on a known type."),
     attribute_id: z
         .string()
         .describe("URL attribute-definition id. If the body also carries `id`, it must match."),

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

@@ -12,65 +12,26 @@
  *
  * Every handler follows the BAPI-582 foundation write recipe: parse inputs →
  * `rejectIfNotSandboxForWrite` → build a decoupled payload → `ocapiPut`/`ocapiPatch`
- * → `formatOcapiWriteToolResult` (which echoes the OCAPI write-grant JSON on 403).
+ * → `formatOcapiWriteToolResult`.
+ *
+ * This module owns no failure representation of its own. Its annotations, result
+ * type, path encoder, and every pre-transport failure envelope come from
+ * `write-tool-common.ts`, so all nine SFCC write tools emit byte-comparable
+ * bodies for equivalent failures (BAPI-766). The private near-duplicates this
+ * module used to carry leaked raw Zod issue objects and serialized compactly
+ * while the shared helpers pretty-printed — exactly the divergence that made
+ * `isError` non-total.
  */
 import { z } from "zod";
 import { ocapiPut, ocapiPatch } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { rejectIfNotSandboxForWrite } from "./write-guard.js";
 import { formatOcapiWriteToolResult } from "./write-result.js";
-import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, attributeGroupPatchBodySchema, localizedStringSchema, SfccWritePayloadFault, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, buildAttributeGroupPutPayload, buildAttributeGroupPatchPayload, buildEmptyRelationPayload, } from "./writes-system-object-payloads.js";
-// ---------------------------------------------------------------------------
-// Annotations (destructive OCAPI writes against a developer sandbox)
-// ---------------------------------------------------------------------------
-const WRITE_ANNOTATIONS = {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    openWorldHint: true,
-};
-function textResult(text) {
-    return { content: [{ type: "text", text }] };
-}
-/** Safe 400 envelope for a Zod validation failure — no stacks, no raw thrown strings. */
-function zodValidationEnvelope(err) {
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
-        status: 400,
-        message: "Invalid SFCC write tool input.",
-        issues: err.issues,
-    }));
-}
-/** Safe 400 envelope for a local payload-shape fault, in OCAPI-fault vocabulary. */
-function payloadFaultEnvelope(fault) {
-    return textResult(JSON.stringify({
-        error: "OCAPI_WRITE_ERROR",
-        status: fault.status,
-        fault: { type: fault.faultType, message: fault.message },
-    }));
-}
-/** Safe 500 envelope — never includes stacks, secrets, headers, or raw error text. */
-function unexpectedEnvelope() {
-    return textResult(JSON.stringify({
-        error: "INTERNAL_ERROR",
-        status: 500,
-        message: "Unexpected SFCC write tool failure",
-    }));
-}
-/** Map a pre-transport error (parse or payload-build) to its safe envelope. */
-function preTransportErrorEnvelope(err) {
-    if (err instanceof z.ZodError)
-        return zodValidationEnvelope(err);
-    if (err instanceof SfccWritePayloadFault)
-        return payloadFaultEnvelope(err);
-    return unexpectedEnvelope();
-}
+import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, attributeGroupPatchBodySchema, localizedStringSchema, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, buildAttributeGroupPutPayload, buildAttributeGroupPatchPayload, buildEmptyRelationPayload, } from "./writes-system-object-payloads.js";
+import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpectedEnvelope, } from "./write-tool-common.js";
 // ---------------------------------------------------------------------------
 // OCAPI path builders (every dynamic segment URL-encoded)
 // ---------------------------------------------------------------------------
-function encodedSegment(segment) {
-    return encodeURIComponent(segment);
-}
 function attributeDefinitionPath(objectType, attributeId) {
     return `/system_object_definitions/${encodedSegment(objectType)}/attribute_definitions/${encodedSegment(attributeId)}`;
 }