@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/sfcc/credentials.js

@@ -1,12 +1,14 @@
 /**
  * SFCC credential resolution — dw.json only (D-2: no Bridge credential store).
  *
- * Precedence: explicit tool arg → environment variable → dw.json.
+ * Precedence: explicit tool arg (matched against dw.json, then environment
+ * variables) → environment variable → dw.json.
  * Multi-sandbox detection fails loudly with actionable guidance; no silent
  * first-pick. Secret values (client_secret, tokens) are never included in
  * any returned or thrown string — only source and target are reported.
  */
 import { ensureGitInfoExcluded } from "../git-ignore-utils.js";
+import { canonicalizeSfccHostname, formatSafeHost } from "./hostname.js";
 import { readFile, writeFile, mkdir } from "fs/promises";
 import path from "path";
 // ---------------------------------------------------------------------------
@@ -20,13 +22,66 @@ const DW_JSON = "dw.json";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Redact-safe summary of a resolved hostname (no secrets). */
+/** Redact-safe full hostname, bounded; a non-hostname becomes a fixed label. */
 function safeHostLabel(hostname) {
-    return hostname.split(".")[0] ?? hostname;
+    return formatSafeHost(hostname);
 }
-// ---------------------------------------------------------------------------
-// Main resolver
-// ---------------------------------------------------------------------------
+/** A dw.json config's credential fields, or null when any is missing. */
+function readConfigCredentials(cfg) {
+    const hostname = String(cfg.hostname ?? cfg.host ?? "");
+    const clientId = String(cfg["client-id"] ?? cfg.clientId ?? cfg.client_id ?? "");
+    const clientSecret = String(cfg["client-secret"] ?? cfg.clientSecret ?? cfg.client_secret ?? "");
+    if (!hostname || !clientId || !clientSecret)
+        return null;
+    return { hostname, clientId, clientSecret };
+}
+/** Every config in a parsed dw.json: the `configs` array, plus a top-level config. */
+function allConfigs(dwJson) {
+    const configs = Array.isArray(dwJson.configs) ? dwJson.configs : [];
+    const list = configs.filter((c) => typeof c === "object" && c !== null);
+    if (dwJson.hostname !== undefined || dwJson.host !== undefined)
+        list.push(dwJson);
+    return list;
+}
+/**
+ * Read dw.json once, keeping the git-exclude side effect.
+ *
+ * "absent" means the file genuinely is not there (or could not be read at all);
+ * "invalid" means it is present but is not a JSON object. The gate treats only
+ * "absent" as "this repository is not set up for SFCC".
+ */
+async function loadDwJson(deps) {
+    const cwd = deps.cwd ?? process.cwd();
+    const rf = deps.readFile ?? ((p) => readFile(p, "utf-8"));
+    const wf = deps.writeFile ?? ((p, data) => writeFile(p, data, "utf-8"));
+    const mk = deps.mkdir ?? ((p, opts) => mkdir(p, opts));
+    // Ensure dw.json is excluded from git tracking.
+    try {
+        await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
+    }
+    catch {
+        // Non-fatal — continue even if we can't update .git/info/exclude.
+    }
+    let raw;
+    try {
+        raw = await rf(path.join(cwd, DW_JSON));
+    }
+    catch {
+        return { state: "absent" };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { state: "invalid" };
+        }
+        return { state: "ok", dwJson: parsed };
+    }
+    catch {
+        return { state: "invalid" };
+    }
+}
+const DW_JSON_ABSENT_MESSAGE = "Could not read dw.json. Create a dw.json file in your project root " +
+    "with your SFCC sandbox credentials (hostname, client-id, client-secret).";
 /**
  * Resolve SFCC credentials with strict precedence and redacted error messages.
  *
@@ -37,14 +92,34 @@ function safeHostLabel(hostname) {
 export async function resolveSfccCredentials(explicitHostname, env = process.env, deps = {}) {
     // --- Tier 1: explicit tool argument ---
     if (explicitHostname) {
+        // A dw.json config for this exact host wins; environment credentials are
+        // the fallback when the file is absent, unusable, or has no usable match.
+        const explicitCanonical = canonicalizeSfccHostname(explicitHostname);
+        const loaded = await loadDwJson(deps);
+        if (loaded.state === "ok" && explicitCanonical !== null) {
+            for (const cfg of allConfigs(loaded.dwJson)) {
+                const cfgHost = canonicalizeSfccHostname(String(cfg.hostname ?? cfg.host ?? ""));
+                if (cfgHost !== explicitCanonical)
+                    continue;
+                const found = readConfigCredentials(cfg);
+                if (found) {
+                    return {
+                        ok: true,
+                        credentials: { ...found, source: "dw.json (explicit instance match)" },
+                    };
+                }
+            }
+        }
         const clientId = env[ENV_CLIENT_ID];
         const clientSecret = env[ENV_CLIENT_SECRET];
         if (!clientId || !clientSecret) {
             return {
                 ok: false,
-                error: `Explicit instance '${safeHostLabel(explicitHostname)}' provided but ` +
-                    `${ENV_CLIENT_ID} and/or ${ENV_CLIENT_SECRET} are not set in environment. ` +
-                    `Set them and retry.`,
+                kind: "explicit-instance-unresolved",
+                error: `Explicit instance '${safeHostLabel(explicitHostname)}' could not be resolved: ` +
+                    `no complete dw.json config matches it, and ${ENV_CLIENT_ID} and/or ` +
+                    `${ENV_CLIENT_SECRET} are not set in environment. Add a matching config ` +
+                    `to dw.json or set them, then retry.`,
             };
         }
         return {
@@ -73,30 +148,19 @@ export async function resolveSfccCredentials(explicitHostname, env = process.env
         };
     }
     // --- Tier 3: dw.json ---
-    const cwd = deps.cwd ?? process.cwd();
-    const rf = deps.readFile ?? ((p) => readFile(p, "utf-8"));
-    const wf = deps.writeFile ?? ((p, data) => writeFile(p, data, "utf-8"));
-    const mk = deps.mkdir ?? ((p, opts) => mkdir(p, opts));
-    // Ensure dw.json is excluded from git tracking.
-    try {
-        await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
-    }
-    catch {
-        // Non-fatal — continue even if we can't update .git/info/exclude.
+    const loaded = await loadDwJson(deps);
+    if (loaded.state === "absent") {
+        return { ok: false, kind: "no-dw-json", error: DW_JSON_ABSENT_MESSAGE };
     }
-    const dwJsonPath = path.join(cwd, DW_JSON);
-    let dwJson;
-    try {
-        const raw = await rf(dwJsonPath);
-        dwJson = JSON.parse(raw);
-    }
-    catch {
+    if (loaded.state === "invalid") {
         return {
             ok: false,
-            error: "Could not read dw.json. Create a dw.json file in your project root " +
-                "with your SFCC sandbox credentials (hostname, client-id, client-secret).",
+            kind: "dw-json-invalid",
+            error: "dw.json is present but is not a valid JSON object. Fix its syntax; it needs " +
+                "hostname, client-id, and client-secret.",
         };
     }
+    const dwJson = loaded.dwJson;
     // Detect multiple sandbox configurations.
     // dw.json may carry a top-level 'configs' array (multi-sandbox format) or just a single config.
     const configs = Array.isArray(dwJson.configs)
@@ -104,22 +168,22 @@ export async function resolveSfccCredentials(explicitHostname, env = process.env
         : null;
     if (configs && configs.length > 1) {
         const instances = configs
-            .map((c) => safeHostLabel(String(c.hostname ?? c.host ?? "unknown")))
+            .map((c) => safeHostLabel(String(c.hostname ?? c.host ?? "")))
             .join(", ");
         return {
             ok: false,
+            kind: "multi-sandbox",
             error: `dw.json contains multiple sandboxes (${instances}). ` +
-                `Pass an explicit 'instance' argument to select one: ${instances}.`,
+                `Pass one of these as 'instance' to select it: ${instances}.`,
         };
     }
     // Extract single-config credentials — support both top-level and configs[0] shapes.
     const cfg = configs && configs.length === 1 ? configs[0] : dwJson;
-    const hostname = String(cfg.hostname ?? cfg.host ?? "");
-    const clientId = String(cfg["client-id"] ?? cfg.clientId ?? cfg.client_id ?? "");
-    const clientSecret = String(cfg["client-secret"] ?? cfg.clientSecret ?? cfg.client_secret ?? "");
-    if (!hostname || !clientId || !clientSecret) {
+    const found = readConfigCredentials(cfg);
+    if (!found) {
         return {
             ok: false,
+            kind: "dw-json-invalid",
             error: "dw.json is present but missing required fields (hostname, client-id, client-secret). " +
                 "Ensure all three fields are set.",
         };
@@ -127,10 +191,8 @@ export async function resolveSfccCredentials(explicitHostname, env = process.env
     return {
         ok: true,
         credentials: {
-            hostname,
-            clientId,
-            clientSecret,
-            source: `dw.json (instance: ${safeHostLabel(hostname)})`,
+            ...found,
+            source: `dw.json (instance: ${safeHostLabel(found.hostname)})`,
         },
     };
 }

package/build/sfcc/hostname.js

@@ -0,0 +1,67 @@
+/**
+ * Shared SFCC hostname helpers.
+ *
+ * `canonicalizeSfccHostname` lives here so the target boundary
+ * (`tool-wrapper.ts`), the credential resolver, and `check_permissions` all
+ * canonicalize and display hosts the same way. `tool-wrapper.ts` re-exports it
+ * so its public import surface is unchanged.
+ */
+/** Longest hostname echoed in a diagnostic. */
+export const MAX_DIAGNOSTIC_HOST_LENGTH = 120;
+/** Shown in place of any value that is not a bare hostname. */
+export const INVALID_HOST_LABEL = "<invalid host>";
+/** One DNS label: 1–63 chars, alphanumeric, internal hyphens only. */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Reduce a raw hostname to a canonical comparable form, or `null` if it is not
+ * a bare hostname at all.
+ *
+ * Only DNS-equivalent normalization is applied — lowercasing and stripping a
+ * single trailing root dot. Everything else is a rejection rather than a
+ * repair: a value carrying a scheme, port, path, query, credentials, or
+ * whitespace is not a hostname, and "cleaning it up" would mean guessing which
+ * part the operator meant. Guessing is how a boundary gets bypassed, so this
+ * returns `null` and the caller fails closed.
+ */
+export function canonicalizeSfccHostname(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let value = raw.trim().toLowerCase();
+    if (value.endsWith("."))
+        value = value.slice(0, -1);
+    if (value === "" || value.length > 253)
+        return null;
+    // Anything that is not strictly `label(.label)*` — scheme, port, path, query,
+    // userinfo, whitespace, IPv6 brackets, wildcards.
+    if (!/^[a-z0-9.-]+$/.test(value))
+        return null;
+    if (value.includes(".."))
+        return null;
+    const labels = value.split(".");
+    if (labels.length < 2)
+        return null;
+    if (!labels.every((label) => DNS_LABEL.test(label)))
+        return null;
+    // A bare IPv4 address is not a sandbox hostname and must not be canonicalized
+    // into one; the suffix check in the boundary would reject it anyway, but
+    // rejecting here keeps "is this a hostname?" and "is this host approved?"
+    // separate concerns.
+    if (/^\d+(\.\d+)*$/.test(value))
+        return null;
+    return value;
+}
+/**
+ * Render a host for a diagnostic message.
+ *
+ * The value is canonicalized first. A value that is not a bare hostname is
+ * replaced by a fixed label, so arbitrary input (which may carry a secret) is
+ * never echoed. A valid hostname is shown in full, bounded to 120 characters.
+ */
+export function formatSafeHost(raw) {
+    const canonical = canonicalizeSfccHostname(raw);
+    if (canonical === null)
+        return INVALID_HOST_LABEL;
+    return canonical.length > MAX_DIAGNOSTIC_HOST_LENGTH
+        ? `${canonical.slice(0, MAX_DIAGNOSTIC_HOST_LENGTH)}…`
+        : canonical;
+}

package/build/sfcc/permissions.js

@@ -8,14 +8,15 @@
  */
 import { ocapiGet } from "./client.js";
 import { normalizeOcapiPage } from "./ocapi-shape.js";
-import { DEFAULT_OCAPI_VERSION } from "./config.js";
+import { DEFAULT_OCAPI_VERSION, OCAPI_SETTINGS_STRUCTURE_VERSION } from "./config.js";
+import { formatSafeHost } from "./hostname.js";
 import { formatOcapiWriteGrantJson } from "./write-grants.js";
 // ---------------------------------------------------------------------------
 // OCAPI Settings JSON template
 // Operators paste this in: Administration > Site Development > Open Commerce API Settings → Data API tab.
 // ---------------------------------------------------------------------------
-const OCAPI_SETTINGS_READ_SEARCH = (ocapiVersion) => JSON.stringify({
-    _v: ocapiVersion,
+const OCAPI_SETTINGS_READ_SEARCH = () => JSON.stringify({
+    _v: OCAPI_SETTINGS_STRUCTURE_VERSION,
     clients: [
         {
             client_id: "<YOUR_CLIENT_ID>",
@@ -52,8 +53,9 @@ const OCAPI_SETTINGS_READ_SEARCH = (ocapiVersion) => JSON.stringify({
 // JSON printed here is byte-identical to what future write handlers echo on a
 // 403. This now covers all required write resource families:
 // /system_object_definitions, /system_object_definitions/**,
-// /custom_object_definitions/**, and /site_preferences/**.
-const OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => formatOcapiWriteGrantJson(ocapiVersion);
+// /custom_object_definitions/**, and the site-scoped /sites/*/site_preferences/**
+// (the org-level /site_preferences/** above stays read/search only).
+const OCAPI_SETTINGS_WRITE_IMPORT = () => formatOcapiWriteGrantJson();
 // ---------------------------------------------------------------------------
 // Tool implementation
 // ---------------------------------------------------------------------------
@@ -75,7 +77,7 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
                 {
                     type: "text",
                     text: `OCAPI probe failed: ${msg}\n\n` +
-                        ocapiSettingsInstructions(ocapiVersion),
+                        ocapiSettingsInstructions(),
                 },
             ],
         };
@@ -86,8 +88,10 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
             content: [
                 {
                     type: "text",
-                    text: `✓ OCAPI access confirmed.\n` +
-                        `  Instance: ${credentials.hostname.split(".")[0]}\n` +
+                    text: `✓ OCAPI read access confirmed (GET /system_object_definitions). ` +
+                        `Write access is not probed; the sfcc-write tools need the mutation grant — ` +
+                        `run check_permissions after a 403 or see SFCC-SETUP-CHECKLIST.md.\n` +
+                        `  Instance: ${formatSafeHost(credentials.hostname)}\n` +
                         `  OCAPI version: ${ocapiVersion}\n` +
                         `  GET /system_object_definitions: ${formatProbeCount(normalized)}`,
                 },
@@ -99,8 +103,8 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
             content: [
                 {
                     type: "text",
-                    text: `HTTP ${result.status}: OCAPI access denied for instance ${credentials.hostname.split(".")[0]}.\n\n` +
-                        ocapiSettingsInstructions(ocapiVersion),
+                    text: `HTTP ${result.status}: OCAPI access denied for instance ${formatSafeHost(credentials.hostname)}.\n\n` +
+                        ocapiSettingsInstructions(),
                 },
             ],
         };
@@ -157,13 +161,13 @@ function formatProbeCount(normalized) {
  * A label that understates a grant is worse than no label, because the operator
  * stops reading the JSON once the heading has told them it is safe.
  */
-function ocapiSettingsInstructions(ocapiVersion) {
+function ocapiSettingsInstructions() {
     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` +
         `--- READ/SEARCH TOOL GRANTS (required for the sfcc read tools) ---\n` +
-        `${OCAPI_SETTINGS_READ_SEARCH(ocapiVersion)}\n\n` +
+        `${OCAPI_SETTINGS_READ_SEARCH()}\n\n` +
         `--- MUTATION GRANTS (required for the nine sfcc-write tools) ---\n` +
-        `${OCAPI_SETTINGS_WRITE_IMPORT(ocapiVersion)}\n\n` +
+        `${OCAPI_SETTINGS_WRITE_IMPORT()}\n\n` +
         `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
 }
 /**

package/build/sfcc/register.js

@@ -89,7 +89,7 @@ export function registerSfccTools(registerTool, deps) {
         const gatedCheckPermissions = withSfccGate(gateDeps, async (_args, credentials) => checkPermissionsTool(credentials));
         registerSfccTool("check_permissions", {
             description: "Probe SFCC OCAPI access via GET /system_object_definitions. " +
-                "On 200: reports OK and the detected OCAPI version. " +
+                "On 200: reports read access OK and the detected OCAPI version. " +
                 "On 401/403: prints the exact OCAPI Settings JSON to paste in Business Manager " +
                 "(read/search and mutation grants).",
             inputSchema: z.object({

package/build/sfcc/setup-status.js

@@ -6,6 +6,7 @@
  * prevent the others from running.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { getAmToken } from "./client.js";
 // ---------------------------------------------------------------------------
 // Implementation
@@ -38,6 +39,7 @@ export async function sfccSetupStatusTool(deps) {
     if (apiKeyOk && repoOk) {
         try {
             resolvedVersion = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+            publishSfccVersion(resolvedVersion);
             if (resolvedVersion === null) {
                 versionStatus = "✗ Not set (configure the 'version' field in Bridge API project settings)";
             }

package/build/sfcc/tool-wrapper.js

@@ -62,8 +62,13 @@
  * no per-tool opt-in and no exemption flag.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { resolveSfccCredentials } from "./credentials.js";
 import { formatSfccFailure } from "./sfcc-result.js";
+import { canonicalizeSfccHostname, formatSafeHost } from "./hostname.js";
+// `canonicalizeSfccHostname` moved to hostname.ts; re-exported so existing
+// importers of this module are unaffected.
+export { canonicalizeSfccHostname };
 // ---------------------------------------------------------------------------
 // Hostname policy
 // ---------------------------------------------------------------------------
@@ -107,47 +112,8 @@ export const APPROVED_SANDBOX_HOST_FORMS = [
     "<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com",
     "<realm>-<nnn>.dx.commercecloud.salesforce.com",
 ];
-/** One DNS label: 1–63 chars, alphanumeric, internal hyphens only. */
-const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 /** Form B's leading label: an SFCC realm id followed by a numeric instance. */
 const REALM_INSTANCE_LABEL = /^[a-z0-9]+-\d{3}$/;
-/**
- * Reduce a raw hostname to a canonical comparable form, or `null` if it is not
- * a bare hostname at all.
- *
- * Only DNS-equivalent normalization is applied — lowercasing and stripping a
- * single trailing root dot. Everything else is a rejection rather than a
- * repair: a value carrying a scheme, port, path, query, credentials, or
- * whitespace is not a hostname, and "cleaning it up" would mean guessing which
- * part the operator meant. Guessing is how a boundary gets bypassed, so this
- * returns `null` and the caller fails closed.
- */
-export function canonicalizeSfccHostname(raw) {
-    if (typeof raw !== "string")
-        return null;
-    let value = raw.trim().toLowerCase();
-    if (value.endsWith("."))
-        value = value.slice(0, -1);
-    if (value === "" || value.length > 253)
-        return null;
-    // Anything that is not strictly `label(.label)*` — scheme, port, path, query,
-    // userinfo, whitespace, IPv6 brackets, wildcards.
-    if (!/^[a-z0-9.-]+$/.test(value))
-        return null;
-    if (value.includes(".."))
-        return null;
-    const labels = value.split(".");
-    if (labels.length < 2)
-        return null;
-    if (!labels.every((label) => DNS_LABEL.test(label)))
-        return null;
-    // A bare IPv4 address is not a sandbox hostname and must not be canonicalized
-    // into one; the suffix check below would reject it anyway, but rejecting here
-    // keeps "is this a hostname?" and "is this host approved?" separate concerns.
-    if (/^\d+(\.\d+)*$/.test(value))
-        return null;
-    return value;
-}
 /**
  * Decide whether a canonical hostname is an approved developer sandbox.
  *
@@ -215,9 +181,9 @@ export function isApprovedSfccSandboxHost(canonical) {
  * raw `dw.json` contents never enter this envelope.
  */
 function targetNotSandbox(rejectedHostname) {
-    // A malformed value is echoed back bounded, so a pathological configuration
-    // value cannot inflate the response.
-    const safeRejected = rejectedHostname.length > 120 ? `${rejectedHostname.slice(0, 120)}…` : rejectedHostname;
+    // A valid host is echoed in full but bounded; anything that is not a bare
+    // hostname is replaced by a fixed label so arbitrary input is never echoed.
+    const safeRejected = formatSafeHost(rejectedHostname);
     return formatSfccFailure({
         code: "TARGET_NOT_SANDBOX",
         status: 403,
@@ -266,9 +232,19 @@ export function withSfccTargetBoundary(handler, deps = {}) {
         // actually returned.
         const rawInstance = typeof safeArgs.instance === "string" ? safeArgs.instance : undefined;
         const explicitHostname = rawInstance && rawInstance.includes(".") ? rawInstance : undefined;
+        // Refuse an unsafe explicit host BEFORE any credential lookup. The check
+        // below on the resolved host stays: this one only adds a refusal earlier, so
+        // an unknown host never reaches the resolver, and a host that resolution
+        // selects is still validated after it.
+        if (explicitHostname !== undefined) {
+            const explicitCanonical = canonicalizeSfccHostname(explicitHostname);
+            if (explicitCanonical === null || !isApprovedSfccSandboxHost(explicitCanonical)) {
+                return targetNotSandbox(explicitHostname);
+            }
+        }
         const credResult = await resolve(explicitHostname);
         if (!credResult.ok) {
-            return handler(safeArgs, { approved: false, error: credResult.error });
+            return handler(safeArgs, { approved: false, error: credResult.error, kind: credResult.kind });
         }
         const rawHostname = credResult.credentials.hostname;
         const canonical = canonicalizeSfccHostname(rawHostname);
@@ -333,6 +309,22 @@ function notConfigured(failureClass, message) {
         details: { failure_class: failureClass },
     });
 }
+/**
+ * Build the failure for a credential problem on a repository that IS set up.
+ *
+ * The repo has a `dw.json` (or the caller named an explicit instance), so the
+ * caller can fix the input. That is why this carries no `NO_RETRY_INSTRUCTION`
+ * and is a 400, not the 503 "not configured" envelope.
+ */
+function credentialResolutionFailed(message) {
+    return formatSfccFailure({
+        code: "CREDENTIAL_RESOLUTION_FAILED",
+        status: 400,
+        message,
+        source: "gate",
+        details: { failure_class: "credential-resolution" },
+    });
+}
 // ---------------------------------------------------------------------------
 // Gate
 // ---------------------------------------------------------------------------
@@ -385,6 +377,7 @@ export function withSfccGate(deps, handler) {
         }
         // (a) Read /config-field/version
         const version = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+        publishSfccVersion(version);
         if (version === null) {
             return notConfigured("bridge-auth", "Could not read the SFCC version from Bridge API (/config-field/version). " +
                 "Ensure your Bridge API key is set and the repo is configured. " +
@@ -400,6 +393,11 @@ export function withSfccGate(deps, handler) {
         // reaches here — the boundary already refused it — so the only remaining
         // case is credential resolution having failed outright.
         if (!target.approved) {
+            // Only a genuinely absent dw.json means "this repo is not set up for
+            // SFCC". Every other resolver failure is fixable by the caller.
+            if (target.kind !== undefined && target.kind !== "no-dw-json") {
+                return credentialResolutionFailed(target.error);
+            }
             return notConfigured("missing-dw-json", `SFCC credential resolution failed: ${target.error} ` +
                 "Ensure a dw.json file exists in your project root with " +
                 "hostname, client-id, and client-secret fields.");

package/build/sfcc/tools-configured.js

@@ -0,0 +1,96 @@
+/** Process-local, secret-free SFCC setup verdict for authenticated Bridge requests. */
+import { access } from "fs/promises";
+import { constants } from "fs";
+import path from "path";
+import { resolveSfccCredentials } from "./credentials.js";
+import { getSfccVersionConfig, SFCC_VERSIONS } from "./config.js";
+const DIAGNOSTIC = "SFCC tools header omitted: version lookup did not establish SFCC setup; check setup status.";
+/** Existence and readability are enough to establish the local gate. */
+export async function hasRootDwJson() {
+    try {
+        await access(path.join(process.cwd(), "dw.json"), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Isolated state is injectable for offline tests; the MCP uses one instance. */
+export function createSfccToolsHeaderState(deps) {
+    let credentialVerdict;
+    let knownVersion;
+    let lookupStarted = false;
+    let diagnosticPrinted = false;
+    function getCredentialVerdict() {
+        credentialVerdict ??= Promise.resolve().then(() => deps.resolveCredentials(deps.env, {
+            ...deps.credentialDeps,
+            writeFile: async () => { },
+            mkdir: async () => { },
+        })).then((result) => result.ok ? "yes" : "no")
+            .catch(() => "no");
+        return credentialVerdict;
+    }
+    function publishVersion(version) {
+        if (version !== null && knownVersion === undefined)
+            knownVersion = version;
+        if (version !== null && SFCC_VERSIONS.includes(version))
+            knownVersion = version;
+    }
+    function reportUnresolved() {
+        if (diagnosticPrinted)
+            return;
+        diagnosticPrinted = true;
+        deps.diagnostic(DIAGNOSTIC);
+    }
+    async function withHeader(headers, options) {
+        if (options.skipSfccToolsHeader)
+            return headers;
+        try {
+            const localFile = await deps.hasDwJson();
+            if (knownVersion === undefined && !lookupStarted && options.repoName) {
+                lookupStarted = true;
+                void deps.getVersion(options.buildGetUrl, options.getLookupHeaders, options.repoName)
+                    .then((version) => {
+                    if (version !== null)
+                        publishVersion(version);
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                })
+                    .catch(() => {
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                });
+            }
+            const isSfcc = knownVersion !== undefined && knownVersion !== null
+                && SFCC_VERSIONS.includes(knownVersion);
+            if (!localFile && !isSfcc) {
+                if (!options.repoName)
+                    reportUnresolved();
+                return headers;
+            }
+            headers["X-Bridge-SFCC-Tools"] = await getCredentialVerdict();
+        }
+        catch {
+            // Optional enrichment cannot interrupt authenticated requests.
+        }
+        return headers;
+    }
+    return { getCredentialVerdict, publishVersion, withHeader };
+}
+const processState = createSfccToolsHeaderState({
+    hasDwJson: hasRootDwJson,
+    resolveCredentials: (env, credentialDeps) => resolveSfccCredentials(undefined, env, credentialDeps),
+    credentialDeps: {},
+    env: process.env,
+    getVersion: getSfccVersionConfig,
+    diagnostic: (message) => console.error(message),
+});
+export const getSfccCredentialVerdict = processState.getCredentialVerdict;
+export const publishSfccVersion = processState.publishVersion;
+export const withSfccToolsHeader = processState.withHeader;