@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/build/review-generation.js

@@ -193,6 +193,28 @@ export class ReviewGenerationRegistry {
             return null;
         return { baseline: entry.baseline, expectedLegCount: entry.expectedLegCount };
     }
+    /**
+     * Consecutive all-`404` wait windows recorded for the live submission
+     * (BAPI-1382), or `0` when there is none or no live entry.
+     */
+    notFoundWindowCount(repoName, ticketNumber) {
+        this.evictExpired();
+        return this.entries.get(baselineKey(repoName, ticketNumber))?.notFoundWindows ?? 0;
+    }
+    /** Count one more all-`404` wait window for the live submission. No-op without one. */
+    noteNotFoundWindow(repoName, ticketNumber) {
+        this.evictExpired();
+        const entry = this.entries.get(baselineKey(repoName, ticketNumber));
+        if (!entry)
+            return;
+        entry.notFoundWindows = (entry.notFoundWindows ?? 0) + 1;
+    }
+    /** A non-`404` observation resets the count. No-op without a live entry. */
+    resetNotFoundWindows(repoName, ticketNumber) {
+        const entry = this.entries.get(baselineKey(repoName, ticketNumber));
+        if (entry)
+            entry.notFoundWindows = 0;
+    }
     /**
      * Consume a baseline. Clearing means "durable persistence has happened",
      * not "a terminal envelope was received" (BAPI-1129) — the anchor is

package/build/setup-epic.js

@@ -1,10 +1,14 @@
 /**
- * `setup-epic` — one-command bootstrap for an Epic Conductor v2 run.
+ * `setup-epic` — one-command bootstrap for an Epic Implementer run.
  *
  * Creates the epic run, stores the plan DAG, and approves it. Before this
- * existed the only path was hand-rolled HTTP with a hand-computed plan hash,
- * which is why the shipped `store-and-approve-epic-plan` pipeline step told the
- * agent to "make a direct API call" — there was no tool to call.
+ * existed the only path was hand-rolled HTTP with a hand-computed plan hash —
+ * there was no tool to call.
+ *
+ * This is a separate run-creation workflow, not a `/plan-epic` pipeline step:
+ * `/plan-epic` authors the local sidecar and stops. An operator creates the child
+ * tickets, finalizes the plan, and then launches through the gated `drive-epic`
+ * entry point, which is what reaches this command.
  *
  * Ordering is load-bearing:
  *
@@ -85,8 +89,9 @@ import { formatEpicLaunchChannelIdentity, getPinnedEpicLaunchPolicy, readEpicLau
 // that module never imports from `setup-epic.ts`). Reused here rather than
 // reimplemented so the mapping stays single-defined.
 import { mapLegacyMergeExecutionModeToPolicyMode, resolveMergeExecutionMode, } from "./merge-pull-request.js";
-import { MERGE_EXECUTION_INELIGIBLE, MERGE_EXECUTION_MODE_GITHUB_ACTIONS, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
+import { MERGE_EXECUTION_INELIGIBLE, MERGE_EXECUTION_MODE_GITHUB_ACTIONS, MERGE_WORKFLOW_CODEOWNER_INSTRUCTION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
 import { classifyMergeExecutionEligibility } from "./conductor/merge-execution-eligibility.js";
+import { repositoryWorkflowRemedy } from "./conductor/repository-workflow-remedy.js";
 import { resolveTrackedPaths } from "./git-reachability.js";
 import { validateBranchName } from "./base-ref.js";
 // Reused from the implement-epic client on purpose: adding a second wrapper under
@@ -100,6 +105,7 @@ import { validateBranchName } from "./base-ref.js";
 import { getConfigFieldBaseBranch, getIndexScopeLifecycle, getParseStatus, } from "./epic-shared/bridge-client.js";
 import { boundScopeLifecycleLabel, createExecFileRunCommand, ensureCommitResolvableLocally, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_LIFECYCLE_LABELS, } from "./epic-shared/cut-protocol.js";
 import { hashPlan } from "./conductor/plan.js";
+import { PLACEHOLDER_NODE_KEY_RE } from "./conductor-bundle-artifacts.js";
 import { BRING_UP_REFUSAL_MESSAGES, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-872: local plane-manifest binding, so `plane down` can later stop the
@@ -190,7 +196,7 @@ export function getSetupEpicUsage() {
     return [
         "Usage: mcp-server setup-epic --epic-key <KEY> --plan-file <path> [options]",
         "",
-        "Bootstraps an Epic Conductor v2 run: creates the run, stores the plan DAG,",
+        "Bootstraps an Epic Implementer run: creates the run, stores the plan DAG,",
         "and approves it. Idempotent — re-running reuses an existing live run.",
         "",
         "Branch strategy (default): a plan with TWO OR MORE nodes runs on a dedicated",
@@ -210,11 +216,12 @@ export function getSetupEpicUsage() {
         "that selects no epic branch (--into-base, or a single-node plan) is unchanged",
         "and composes no posture at all.",
         "",
-        "Unattended runs have TWO repository prerequisites, refused by name before any",
-        "run is created: repository consent (ON by default; the repository owner can",
+        "Unattended runs have THREE repository prerequisites, refused by name before",
+        "any run is created: repository consent (ON by default; the repository owner can",
         "switch 'Allow unattended Epic Implementer runs' off and on in the Bridge admin",
-        "panel's Setup page) and a verified notify webhook default. `drive-epic`",
-        "readiness lists both with their current state.",
+        "panel's Setup page); an escalation channel, either a verified notify webhook or",
+        "the account's email address; and confirmed review and CI workflows on the",
+        "default branch. `drive-epic` readiness lists all three with their current state.",
         "",
         "Required:",
         "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
@@ -279,7 +286,7 @@ export function getSetupEpicUsage() {
         "                         10799; remediate / ci_fix 3599; rebase / smoke 2699;",
         "                         merge 1799); the server rejects a higher value with a",
         "                         422 naming the offending field. Full table:",
-        "                         docs/claude/epic-implementer-v2-operator-runbook.md §4.",
+        "                         docs/epic-implementer/operator-runbook.md §4.",
         "  --replace-policy       Authorize replacing a LIVE run's stored policy with the",
         "                         policy file, as a complete replacement. Without it, a",
         "                         divergent policy on a reused run is refused with a",
@@ -297,8 +304,8 @@ export function getSetupEpicUsage() {
         "                         never a substitute for authoritative validation.",
         "",
         "After setup, the server-side reconciler picks the run up within ~30s.",
-        "To execute claimed jobs on this machine, run:",
-        `  npx -y ${MCP_PACKAGE_NAME} executor --repo <name>`,
+        "To execute this run's claimed jobs on this machine, run:",
+        `  npx -y ${MCP_PACKAGE_NAME} executor --repo <name> --epic-run-id <run-id>`,
     ].join("\n");
 }
 function takeValue(argv, i, flag) {
@@ -988,6 +995,20 @@ export function validateEpicPlanSidecar(parsed) {
                 `to get that scheduling protection (use [] when no files are predicted).`);
         }
     }
+    // BAPI-1366: refuse unfinalized `TBD-N` node keys before any graph, access, or
+    // network work. `/plan-epic` authors placeholders; finalization replaces them.
+    // This runs here, not in the server lane, so an updated client refuses even
+    // against an older server and in `--dry-run --local-only`.
+    const placeholders = [...keys].filter((key) => PLACEHOLDER_NODE_KEY_RE.test(key)).sort();
+    if (placeholders.length > 0) {
+        return {
+            ok: false,
+            error: `Plan node keys ${placeholders.join(", ")} are placeholders, not tickets. ` +
+                `Create the child tickets and run \`emit-epic-implementer-bundle finalize\` ` +
+                `to replace every placeholder, then run this again (this invocation created ` +
+                `no run, cut no branch, and incurred no charge).`,
+        };
+    }
     // Build one adjacency in a consistent predecessor -> successor direction, the
     // same way the server does. `depends_on` points at the predecessor; an edge's
     // `from` IS the predecessor.
@@ -1293,12 +1314,13 @@ export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPol
         };
     }
     if (!unattended.repository_readiness_confirmed) {
+        // BAPI-1359: the shared formatter names the specific missing item; the reason
+        // code and the trailing sentence are unchanged.
         return {
             reason: "repository_readiness_unconfirmed",
             message: "the unattended default authorizes automatic merge, which requires the review and " +
-                "conductor-CI workflows to be CONFIRMED on the default branch, and they are not. " +
-                "Run `install-bridge conductor` to install them, or pass --attended to create an " +
-                "attended run. No run was created.",
+                "epic-implementer-ci workflows to be CONFIRMED on the default branch, and they are not. " +
+                `${repositoryWorkflowRemedy(readiness)} No run was created.`,
         };
     }
     return null;
@@ -1371,8 +1393,10 @@ export function evaluateSetupEpicMergeExecutionPrerequisites(readiness, requeste
             reason: MERGE_EXECUTION_INELIGIBLE,
             message: "this run declares merge_execution_mode: github_actions, and the Bridge API " +
                 "conductor readiness report could not be read, so the repository's merge " +
-                "capability could not be confirmed. Retry once the server is reachable, or " +
-                `resolve it with \`${MERGE_WORKFLOW_REMEDY_COMMAND}\`. ${NO_RUN_WAS_CREATED}`,
+                "capability could not be confirmed. Retry once the server is reachable. If " +
+                "readiness then reports the merge workflow missing or out of date, resolve it " +
+                `with \`${MERGE_WORKFLOW_REMEDY_COMMAND}\`. ${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION} ` +
+                NO_RUN_WAS_CREATED,
         };
     }
     const verdict = classifyMergeExecutionEligibility(readiness);
@@ -1385,7 +1409,8 @@ export function evaluateSetupEpicMergeExecutionPrerequisites(readiness, requeste
         reason: MERGE_EXECUTION_INELIGIBLE,
         message: "this run declares merge_execution_mode: github_actions, and this repository's " +
             `merge capability ${category}: ${verdict.detail}. Resolve it with ` +
-            `\`${MERGE_WORKFLOW_REMEDY_COMMAND}\`, then re-run. ${NO_RUN_WAS_CREATED}`,
+            `\`${MERGE_WORKFLOW_REMEDY_COMMAND}\`, then re-run. ` +
+            `${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION} ${NO_RUN_WAS_CREATED}`,
     };
 }
 /**

package/build/sfcc/config.js

@@ -9,6 +9,15 @@
 export const SFCC_VERSIONS = ["sfra", "pwakit", "sitegenesis", "storefrontnext", "hybrid"];
 /** Pinned OCAPI Data API version used for all requests (configurable at call-time). */
 export const DEFAULT_OCAPI_VERSION = "v25_6";
+/**
+ * The `_v` value of the OCAPI Settings JSON an operator pastes in Business
+ * Manager. This is the settings-STRUCTURE version, not the OCAPI API version
+ * above; Business Manager rejects an API version here.
+ *
+ * UNVERIFIED: "23.2" is provisional until owner check OR-1 saves the emitted
+ * grant in Business Manager. If OR-1 shows a different value, change it here.
+ */
+export const OCAPI_SETTINGS_STRUCTURE_VERSION = "23.2";
 /** Account Manager OAuth2 token endpoint host. */
 export const AM_HOST = "account.demandware.com";
 /** AM OAuth2 token endpoint URL. */

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({