@bridge_gpt/mcp-server 0.2.25 → 0.2.26

package/build/conductor-bundle-cli.js

@@ -0,0 +1,256 @@
+/**
+ * BAPI-634: thin CLI handler exposing the deterministic conductor-bundle helpers
+ * to `emit-conductor-bundle.md`.
+ *
+ * Why this exists: the instruction ships **compiled** to consuming repositories
+ * inside `build/pipelines.generated.js`. `mcp_server/src/` does not exist there,
+ * so an instruction that told the agent to "call `validateConductorBundleInputs`"
+ * would be referencing a path only this repository has. This subcommand is the
+ * reachable surface, mirroring how `store-and-approve-epic-plan.md` invokes
+ * `setup-epic` rather than hand-rolling HTTP calls.
+ *
+ * It holds no policy of its own: it parses argv, delegates to
+ * `conductor-bundle-artifacts.ts`, and prints a JSON envelope. All I/O is behind
+ * an injectable seam so tests never touch a real disk or construct a server.
+ */
+import path from "node:path";
+import { finalizeEpicPlanSidecar, serializeSiblingTicketManifest, validateConductorBundleInputs, writeJsonAtomically, } from "./conductor-bundle-artifacts.js";
+const USAGE = [
+    "Usage: emit-conductor-bundle <validate|finalize> --input <file> [--docs-dir <dir>] [--json]",
+    "",
+    "  validate   Validate identities, the node->ticket mapping, manifest agreement,",
+    "             and path containment. Writes nothing.",
+    "  finalize   Validate, then finalize epic-plan.dag.json with real keys and",
+    "             per-node touched_files, and write the sibling-ticket manifest.",
+    "",
+    "Options:",
+    "  --input <file>     JSON document with epic_key, epic_slug, mappings,",
+    "                     decomposition_fingerprint, and (for finalize)",
+    "                     touched_files_by_key.",
+    "  --docs-dir <dir>   Docs directory (default: $BAPI_DOCS_DIR, else docs/tmp).",
+    "  --json             Emit a machine-readable result on stdout.",
+    "  -h, --help         Show this help.",
+].join("\n");
+/** Read a flag's value, rejecting a missing or flag-shaped value. */
+function takeValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("-")) {
+        throw new Error(`Flag "${flag}" requires a value.`);
+    }
+    return value;
+}
+/** Parse argv into options, or throw with an actionable message. */
+export function parseConductorBundleArgs(argv) {
+    const mode = argv[0];
+    if (mode === "-h" || mode === "--help" || mode === undefined) {
+        return { mode: "validate", inputFile: "", json: false, help: true };
+    }
+    if (mode !== "validate" && mode !== "finalize") {
+        throw new Error(`Unknown subcommand "${mode}". Expected "validate" or "finalize".`);
+    }
+    let inputFile;
+    let docsDir;
+    let json = false;
+    let help = false;
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--input":
+                inputFile = takeValue(argv, i, "--input");
+                i++;
+                break;
+            case "--docs-dir":
+                docsDir = takeValue(argv, i, "--docs-dir");
+                i++;
+                break;
+            case "--json":
+                json = true;
+                break;
+            case "-h":
+            case "--help":
+                help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument "${arg}".`);
+        }
+    }
+    if (help)
+        return { mode, inputFile: inputFile ?? "", docsDir, json, help: true };
+    if (!inputFile)
+        throw new Error('Flag "--input" is required.');
+    return { mode, inputFile, docsDir, json, help: false };
+}
+/** Parse JSON, converting a syntax error into an actionable message. */
+async function readJson(filePath, fs, label) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath);
+    }
+    catch (err) {
+        throw new Error(`Could not read ${label} at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${label} at ${filePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Read an optional JSON file, returning null when it does not exist. */
+async function readOptionalJson(filePath, fs, label) {
+    try {
+        await fs.readFile(filePath);
+    }
+    catch {
+        return null;
+    }
+    return readJson(filePath, fs, label);
+}
+/**
+ * Run the `emit-conductor-bundle` subcommand. Returns a process exit code; never
+ * throws for an expected validation failure.
+ */
+export async function runConductorBundleCli(argv, overrides = {}) {
+    const deps = {
+        env: process.env,
+        cwd: process.cwd(),
+        fs: createDefaultBundleFs(),
+        log: (m) => console.log(m),
+        // Diagnostics go to stderr so `--json` keeps stdout a single result object.
+        errorLog: (m) => console.error(m),
+        ...overrides,
+    };
+    let opts;
+    try {
+        opts = parseConductorBundleArgs(argv);
+    }
+    catch (err) {
+        deps.errorLog(err instanceof Error ? err.message : String(err));
+        deps.errorLog(USAGE);
+        return 1;
+    }
+    if (opts.help) {
+        deps.log(USAGE);
+        return 0;
+    }
+    const emitFailure = (error) => {
+        if (opts.json)
+            deps.log(JSON.stringify({ ok: false, error }));
+        else
+            deps.errorLog(`Error: ${error}`);
+        return 1;
+    };
+    const docsDir = path.resolve(deps.cwd, opts.docsDir ?? deps.env.BAPI_DOCS_DIR ?? path.join("docs", "tmp"));
+    let input;
+    try {
+        input = (await readJson(path.resolve(deps.cwd, opts.inputFile), deps.fs, "--input document"));
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    if (!input || typeof input !== "object") {
+        return emitFailure("--input document must be a JSON object.");
+    }
+    const epicDir = path.resolve(docsDir, "epic-plans", String(input.epic_slug));
+    const sidecarPath = path.join(epicDir, "epic-plan.dag.json");
+    const manifestPath = path.join(epicDir, "sibling-ticket-manifest.json");
+    let sidecar;
+    let existingManifest;
+    try {
+        sidecar = await readJson(sidecarPath, deps.fs, "epic-plan.dag.json");
+        existingManifest = await readOptionalJson(manifestPath, deps.fs, "sibling-ticket-manifest.json");
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    const validation = await validateConductorBundleInputs({
+        epic_key: input.epic_key,
+        epic_slug: input.epic_slug,
+        docs_dir: docsDir,
+        mappings: input.mappings,
+        sidecar,
+        existing_manifest: existingManifest ?? undefined,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+    }, deps.fs);
+    if (!validation.ok)
+        return emitFailure(validation.error);
+    if (opts.mode === "validate") {
+        const result = {
+            ok: true,
+            mode: "validate",
+            epic_key: validation.value.epic_key,
+            plan_version: validation.value.plan_version,
+            mapped_nodes: validation.value.mappings.length,
+            sidecar_path: validation.value.sidecar_path,
+        };
+        if (opts.json)
+            deps.log(JSON.stringify(result));
+        else {
+            deps.log(`Validated ${result.mapped_nodes} node mapping(s) for ${result.epic_key} ` +
+                `(plan v${result.plan_version}). Nothing was written.`);
+        }
+        return 0;
+    }
+    // ---- finalize ----------------------------------------------------------
+    const nodeKeyMap = {};
+    for (const m of validation.value.mappings) {
+        nodeKeyMap[m.plan_node_id] = m.ticket_key;
+    }
+    const finalized = finalizeEpicPlanSidecar({
+        sidecar,
+        node_key_map: nodeKeyMap,
+        touched_files_by_key: input.touched_files_by_key ?? {},
+        plan_version_already_stored: input.plan_version_already_stored === true,
+    });
+    if (!finalized.ok)
+        return emitFailure(finalized.error);
+    const sidecarWrite = await writeJsonAtomically(validation.value.sidecar_path, finalized.value, deps.fs);
+    if (!sidecarWrite.ok)
+        return emitFailure(sidecarWrite.error);
+    const manifest = serializeSiblingTicketManifest({
+        schema_version: 1,
+        epic_key: validation.value.epic_key,
+        epic_slug: validation.value.epic_slug,
+        plan_version: validation.value.plan_version,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+        finalized_fingerprint: null,
+        run_phase: input.run_phase ?? "staged",
+        mappings: validation.value.mappings.map((m) => ({
+            plan_node_id: m.plan_node_id,
+            ticket_key: m.ticket_key,
+            exploration_path: m.exploration_path,
+            draft_path: m.draft_path,
+        })),
+        decisions: [],
+        completed_mutations: [],
+    });
+    const manifestWrite = await writeJsonAtomically(validation.value.manifest_path, manifest, deps.fs);
+    if (!manifestWrite.ok)
+        return emitFailure(manifestWrite.error);
+    const result = {
+        ok: true,
+        mode: "finalize",
+        epic_key: validation.value.epic_key,
+        plan_version: validation.value.plan_version,
+        sidecar_path: validation.value.sidecar_path,
+        manifest_path: validation.value.manifest_path,
+        ticket_keys: validation.value.mappings.map((m) => m.ticket_key),
+    };
+    if (opts.json)
+        deps.log(JSON.stringify(result));
+    else {
+        deps.log(`Finalized ${result.sidecar_path} with ${result.ticket_keys.length} real key(s) ` +
+            `and per-node touched_files. Manifest: ${result.manifest_path}`);
+    }
+    return 0;
+}
+/** Real filesystem seam, loaded lazily so importing this module stays cheap. */
+function createDefaultBundleFs() {
+    return {
+        readFile: async (p) => (await import("node:fs/promises")).readFile(p, "utf-8"),
+        writeFile: async (p, data) => (await import("node:fs/promises")).writeFile(p, data, "utf-8"),
+        rename: async (from, to) => (await import("node:fs/promises")).rename(from, to),
+        unlink: async (p) => (await import("node:fs/promises")).unlink(p),
+        realpath: async (p) => (await import("node:fs/promises")).realpath(p),
+    };
+}

package/build/docs.generated.js

@@ -1,5 +1,6 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
 // This file is produced by scripts/bundle-docs.js
 export const DOCS = {
-    "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Brainstorms (BLOCK on a code index, mode-dependent)\n\n`request_brainstorm` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n"
+    "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Council (BLOCK on a code index, mode-dependent)\n\n`request_council` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n",
+    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**. The tools reject non-sandbox instances, and the permissions grant below is\n> deliberately broad (all methods, all resources) — appropriate for a throwaway dev\n> sandbox, **never** for staging or production. Do not configure this grant on any\n> instance that holds real data. Credentials stay local (in `dw.json` or `SFCC_*` env\n> vars) and are never sent to Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the following client entry to the `clients` array of the Data API settings, then\n**Save**. This grants the client full read/write access to every Data API resource —\nacceptable only on a developer sandbox:\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    {\n      \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n      \"read_attributes\": \"(**)\",\n      \"write_attributes\": \"(**)\",\n      \"resource_id\": \"/**\"\n    }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entry in the standard settings envelope:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          {\n            \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n            \"read_attributes\": \"(**)\",\n            \"write_attributes\": \"(**)\",\n            \"resource_id\": \"/**\"\n          }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. The read tools, write tools, and `sfcc_log_query` are gated behind the\n`sfcc` profile. Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is\ncomma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n"
 };

package/build/doctor.js

@@ -20,7 +20,11 @@ import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { VERSION } from "./version.generated.js";
-import { collectInstallStatusChecks, formatInstallStatusReport, } from "./install-doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
+import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { createBridgeApiUrls } from "./bridge-api-urls.js";
+import { probeToolSurface } from "./tool-surface-gating.js";
+import { resolveBapiCredentials } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
@@ -51,6 +55,14 @@ export function getDoctorUsage() {
         "bootstrap-field completeness, and repository-indexing state. It performs",
         "read-only GETs only and never affects the exit code.",
         "",
+        "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
+        "dynamic capability gating would advertise for this repo. It performs at most",
+        "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
+        "is advisory/fail-open — a timeout or malformed response is reported as",
+        "'fail-open to full surface' and never affects the exit code. Clients that",
+        "ignore notifications/tools/list_changed must reconnect or start a new MCP",
+        "session to observe surface changes; no project MCP config change is required.",
+        "",
         "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  conductor doctor",
@@ -363,6 +375,111 @@ export function formatLauncherCacheReport(inspections) {
     }
     return lines.join("\n");
 }
+/**
+ * Collect the read-only tool-surface diagnostic. Evaluates the kill switch first
+ * and returns without any network request when disabled. For an enabled flag and
+ * a resolved repo/credential, performs ONE 500 ms `probeToolSurface()` GET to the
+ * deployed route. Credential values live ONLY in the request headers and never in
+ * the returned result. Never throws.
+ */
+export async function collectToolSurfaceDiagnostic(deps) {
+    const enabled = parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED);
+    if (!enabled) {
+        return { enabled: false, reason: "kill-switch" };
+    }
+    const target = await resolveInstallDoctorTarget(deps);
+    if (!target.repoName) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: "no BAPI_REPO_NAME in the environment or project-local MCP configs",
+        };
+    }
+    const credDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => { },
+    };
+    const cred = await resolveBapiCredentials(target.repoName, credDeps);
+    if (!cred.ok) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: `no Bridge API credential resolved (${cred.kind})`,
+        };
+    }
+    const apiKey = cred.credentials.apiKey;
+    const urls = createBridgeApiUrls(target.baseUrl);
+    const url = urls.buildGetUrl("/mcp/tool-surface", {
+        repo_name: target.repoName,
+    });
+    const result = await probeToolSurface({
+        url,
+        resolveHeaders: async () => ({ "X-API-Key": apiKey }),
+        fetchFn: deps.fetch,
+    });
+    if (result.reason === "blocked") {
+        return {
+            enabled: true,
+            reason: "blocked",
+            blockedTools: Array.from(result.blockedTools),
+            catalogRevision: result.catalogRevision,
+            evaluatedToolCount: result.evaluatedToolCount,
+        };
+    }
+    if (result.reason === "timeout") {
+        return { enabled: true, reason: "timeout" };
+    }
+    return { enabled: true, reason: "malformed", subtype: result.subtype };
+}
+/**
+ * Render the advisory "MCP tool surface" section (pure formatting — no probing).
+ * States the kill-switch state, probe reachability, decision reason/subtype,
+ * fail-open behavior when applicable, blocked IDs/count/revision for a valid
+ * response, and clarifies that blocked IDs are intersected with the locally
+ * active profile and SDK-enabled baseline only when an MCP session starts.
+ */
+export function formatToolSurfaceDiagnosticReport(diag) {
+    const lines = ["", "MCP tool surface (dynamic capability gating — advisory)", ""];
+    lines.push(`Kill switch: ${diag.enabled ? "ENABLED (gating active)" : "DISABLED (full surface)"}`);
+    switch (diag.reason) {
+        case "kill-switch":
+            lines.push("Reason: kill-switch — BAPI_MCP_TOOL_SURFACE_GATING_ENABLED is off, so the full profile surface is advertised and no probe is performed.");
+            break;
+        case "unresolved":
+            lines.push(`Reason: unresolved — ${diag.detail ?? "repo/credential not resolved"}; the probe was skipped and the full surface is advertised (fail-open to full surface).`);
+            break;
+        case "blocked": {
+            const ids = diag.blockedTools ?? [];
+            lines.push("Reason: blocked — the backend returned a valid capability decision.");
+            lines.push(`Probe: reachable (HTTP 200, valid response).`);
+            lines.push(`Blocked tools (${ids.length}): [${ids.join(", ")}]`);
+            if (diag.catalogRevision)
+                lines.push(`Catalog revision: ${diag.catalogRevision}`);
+            if (typeof diag.evaluatedToolCount === "number") {
+                lines.push(`Evaluated tool count: ${diag.evaluatedToolCount}`);
+            }
+            break;
+        }
+        case "timeout":
+            lines.push("Reason: timeout — the 500 ms probe deadline elapsed; fail-open to full surface.");
+            break;
+        case "malformed":
+            lines.push(`Reason: malformed (${diag.subtype ?? "unknown"}) — fail-open to full surface.`);
+            break;
+    }
+    lines.push("");
+    lines.push("Blocked IDs are intersected with the locally active MCP profile and the current SDK-enabled");
+    lines.push("baseline only when an MCP session starts, so IDs unknown to this package or excluded by the");
+    lines.push("active profile have no effect. Capability-hidden tools remain registered and callable — the");
+    lines.push("backend is the enforcement boundary. This section is advisory and never changes the exit code.");
+    lines.push("Clients that ignore notifications/tools/list_changed must reconnect or start a new MCP session");
+    lines.push("to observe surface changes; no project MCP configuration change is required.");
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -429,6 +546,36 @@ export async function runDoctorCli(argv, overrides = {}) {
             /* install-status diagnostics are advisory; never block the doctor report */
         }
     }
+    // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
+    // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
+    // response, or unexpected throw degrades to a "fail-open to full surface" line
+    // and never affects the exit code, exactly like install-status above.
+    if (overrides.toolSurface !== false) {
+        try {
+            const injectedFs = deps;
+            const toolSurfaceDeps = {
+                env: overrides.toolSurface?.env ?? deps.env,
+                cwd: overrides.toolSurface?.cwd ?? deps.cwd,
+                platform: overrides.toolSurface?.platform ?? deps.platform,
+                homedir: overrides.toolSurface?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.toolSurface?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.toolSurface?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                fetch: overrides.toolSurface?.fetch ?? ((...args) => fetch(...args)),
+            };
+            const diagnostic = await collectToolSurfaceDiagnostic(toolSurfaceDeps);
+            log(formatToolSurfaceDiagnosticReport(diagnostic));
+        }
+        catch {
+            // Any unexpected failure still degrades to a sanitized advisory section.
+            log(formatToolSurfaceDiagnosticReport({
+                enabled: parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED),
+                reason: "malformed",
+                subtype: "unexpected",
+            }));
+        }
+    }
     if (!collection.ok)
         return 1;
     return collection.results.some((r) => !r.found) ? 1 : 0;

package/build/env-flags.js

@@ -0,0 +1,31 @@
+/**
+ * env-flags — shared parsing for default-ON boolean environment flags.
+ *
+ * Extracted from `index.ts` (BAPI-641) so normal server startup and the
+ * `doctor` diagnostic share ONE implementation of the default-on semantics.
+ * A default-on flag is enabled unless explicitly set to a recognized off-token,
+ * so an unknown value fails OPEN (enabled) rather than silently disabling a
+ * feature.
+ */
+/** The recognized, case-insensitive off-tokens for a default-on flag. */
+const OFF_TOKENS = new Set([
+    "false",
+    "0",
+    "no",
+    "off",
+    "disabled",
+]);
+/**
+ * Parse a default-ON boolean env flag. `undefined` / blank → true; the
+ * normalized off-tokens (`false`, `0`, `no`, `off`, `disabled`) → false; any
+ * other value → true (preserving default-on / fail-open behavior). Matching is
+ * case-insensitive and trims surrounding whitespace.
+ */
+export function parseDefaultOnEnvFlag(value) {
+    if (value === undefined)
+        return true;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return true;
+    return !OFF_TOKENS.has(normalized);
+}