@bridge_gpt/mcp-server 0.2.66 → 0.2.68

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
@@ -164,6 +170,7 @@ export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
     "verdict_protocol",
     "native_review_decision",
     "none",
+    "repository_policy",
 ];
 export function createDefaultSetupEpicDeps() {
     return {
@@ -190,7 +197,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 +217,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)",
@@ -253,6 +261,10 @@ export function getSetupEpicUsage() {
         "  --review-policy <src>  PER-RUN review policy source, one of:",
         `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
         "                         Composed into policy_json.review_policy on create.",
+        "                         Omitted, setup-epic sends no review policy: the server",
+        "                         stamps repository_policy at first approval for a new",
+        "                         feature-branch run with no repository default. AI review",
+        "                         is an explicit opt-in (--review-policy verdict_protocol).",
         "                         This flag sets the policy for THIS run only and never",
         "                         changes a repository default. To persist one, pass",
         "                         --review-policy to `install-bridge conductor`, which",
@@ -279,7 +291,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 +309,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 +1000,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.
@@ -1242,6 +1268,72 @@ export function policyDeclaresNotifyWebhook(policy) {
     const url = notify.webhook_url;
     return typeof url === "string" && url.trim() !== "";
 }
+/**
+ * BAPI-1397 (F1) — does this policy set `notify.local_sink` together with a
+ * `notify.webhook_url`?
+ *
+ * Mirrors the server's `NotifyPolicy._reject_local_sink_and_webhook_together`
+ * exactly, and nothing more: `local_sink: true` with a PRESENT, non-null
+ * `webhook_url` conflicts; `local_sink: true` with the URL absent or `null` is
+ * fine; `local_sink: false` (or absent) never conflicts. Every other policy rule
+ * stays the server's to judge. Checked locally so a policy the server would
+ * reject is refused before any plane starts or any request is sent.
+ */
+export function policyNotifyDestinationsConflict(policy) {
+    if (policy === undefined || policy === null)
+        return false;
+    const notify = policy.notify;
+    if (typeof notify !== "object" || notify === null || Array.isArray(notify))
+        return false;
+    const block = notify;
+    return block.local_sink === true && block.webhook_url !== undefined && block.webhook_url !== null;
+}
+/**
+ * Name the selected policy for a launch line or a refusal: its resolved path and
+ * source, or — for a stored or default policy that has no file — a deliberate
+ * no-file label. Only the path is named; the file's content never is.
+ */
+export function describeSelectedPolicy(policyPath, source) {
+    return policyPath !== undefined
+        ? `'${policyPath}' (${source} policy file)`
+        : `the ${source} run policy (no policy file)`;
+}
+/**
+ * The refusal for a policy whose notify destinations conflict. Names the file and
+ * the two keys only — never the webhook URL or any other policy content.
+ */
+export function notifyDestinationsConflictMessage(policyPath, source) {
+    return (`The run policy ${describeSelectedPolicy(policyPath, source)} sets notify.local_sink ` +
+        "together with notify.webhook_url. The server permits only one delivery destination, so " +
+        "it would reject this policy. Remove notify.local_sink or notify.webhook_url and re-run. " +
+        "No plane was started and no request was sent.");
+}
+/** Group-read and other-read permission bits. */
+const GROUP_OR_OTHER_READ_BITS = 0o044;
+/**
+ * BAPI-1397 (F1) — warn when a policy file that carries a `notify.webhook_url` is
+ * readable by other users. A warning only, never a refusal: the launch continues.
+ *
+ * Returns the warning text, or `null` when there is nothing to say — including
+ * when the file's mode cannot be read (a failed `stat` is silently skipped). The
+ * text names the path only; it never carries the URL, the policy body, or any
+ * filesystem error text.
+ */
+export async function worldReadableWebhookPolicyWarning(policyPath, policy, stat) {
+    if (!policyDeclaresNotifyWebhook(policy))
+        return null;
+    let mode;
+    try {
+        mode = (await stat(policyPath)).mode;
+    }
+    catch {
+        return null;
+    }
+    if (typeof mode !== "number" || (mode & GROUP_OR_OTHER_READ_BITS) === 0)
+        return null;
+    return (`[warn] Policy file '${policyPath}' holds a notify webhook URL and other users on this ` +
+        `machine can read it. Restrict it with: chmod 600 '${policyPath}'`);
+}
 export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPolicy) {
     const unattended = readiness?.unattended ?? null;
     if (unattended === null) {
@@ -1293,12 +1385,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 +1464,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 +1480,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}`,
     };
 }
 /**
@@ -1949,6 +2045,21 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         return 1;
     }
     const localHash = hashPlan(plan);
+    // --- Notify destination conflict, explicit file (BAPI-1397, F1) ----------
+    // An explicit `--policy-file` is always the selected policy, so a conflict the
+    // server would reject is refused HERE — before credentials are resolved and
+    // before any request. A file that cannot be read or parsed is left to the
+    // policy read below, which reports it in its own words, unchanged.
+    const pinnedLaunchPolicy = handoff ? getPinnedEpicLaunchPolicy(handoff.selection) : undefined;
+    if (opts.policyFile !== undefined) {
+        const earlyPolicy = pinnedLaunchPolicy !== undefined
+            ? { ok: true, policy: pinnedLaunchPolicy }
+            : await readSetupEpicPolicyFile(opts.policyFile, deps.readFile);
+        if (earlyPolicy.ok && policyNotifyDestinationsConflict(earlyPolicy.policy)) {
+            deps.errorLog(notifyDestinationsConflictMessage(opts.policyFile, "explicit"));
+            return 1;
+        }
+    }
     // Resolve the selected target and live-run identity before choosing a policy.
     // The offline local-only path keeps its no-network contract.
     let access;
@@ -2067,8 +2178,12 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
     const selectedPolicyPath = opts.policyFile ?? (existingRunId === null ? selectedProfilePolicyPath : undefined);
     const selectedPolicySource = existingRunId !== null
         ? "stored" : opts.policyFile !== undefined ? "explicit" : selectedProfilePolicyPath !== undefined ? "profile" : "default";
+    // BAPI-1397 (F1): the source NAMED next to a policy path in operator output. An
+    // explicit file is always "explicit" here, even when the effective-policy facts
+    // above report a reused run's policy as "stored".
+    const policyLabelSource = opts.policyFile !== undefined ? "explicit" : selectedPolicySource;
     if (selectedPolicyPath !== undefined) {
-        const pinned = handoff ? getPinnedEpicLaunchPolicy(handoff.selection) : undefined;
+        const pinned = pinnedLaunchPolicy;
         if (pinned !== undefined) {
             filePolicy = pinned;
         }
@@ -2080,6 +2195,17 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             }
             filePolicy = policyRead.policy;
         }
+        // BAPI-1397 (F1): the same server rule, for a profile-selected file. Still
+        // before any write or plane bring-up; the refusal names the resolved file.
+        if (policyNotifyDestinationsConflict(filePolicy)) {
+            deps.errorLog(notifyDestinationsConflictMessage(selectedPolicyPath, policyLabelSource));
+            return 1;
+        }
+        // BAPI-1397 (F1): a webhook URL in a file other users can read is a warning,
+        // never a refusal. Only the path is named.
+        const readableWarning = await worldReadableWebhookPolicyWarning(selectedPolicyPath, filePolicy, deps.stat);
+        if (readableWarning !== null)
+            deps.errorLog(readableWarning);
     }
     const policyDeclaresBranch = filePolicy !== undefined &&
         ["base_branch", "baseBranch"].some((key) => key in filePolicy && filePolicy[key] !== undefined && filePolicy[key] !== null);
@@ -2245,7 +2371,10 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 "human-gated) — pass --attended to opt out"
             : "";
         const shape = inherited === "" ? "complete run policy" : "run policy";
-        say(`Policy:     ${opts.policyFile} (${shape}, applied at creation${inherited})`);
+        // BAPI-1397 (F1): the RESOLVED path and source — `opts.policyFile` is
+        // undefined for a profile-selected or composed policy.
+        say(`Policy:     ${describeSelectedPolicy(selectedPolicyPath, policyLabelSource)} ` +
+            `(${shape}, applied at creation${inherited})`);
     }
     if (effectiveFeatureBranch !== undefined && featureBranch === undefined) {
         say(`Feature:    ${effectiveFeatureBranch} (from the policy file; cut on origin with local ` +
@@ -2833,7 +2962,8 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 // Re-sanitizing here would only destroy the field name that makes the
                 // server's field-named 422 actionable. The property is pinned by the
                 // regression test below rather than left to this comment.
-                deps.errorLog(`The run policy from '${opts.policyFile}' was rejected by the server.\n` +
+                deps.errorLog(`The run policy ${describeSelectedPolicy(selectedPolicyPath, policyLabelSource)} ` +
+                    `was rejected by the server.\n` +
                     `${errorDetail(err)}\n` +
                     `No run was created and no automation-start charge occurred. Fix the ` +
                     `named field in the policy file and re-run.`);

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;
+}