@bridge_gpt/mcp-server 0.2.25 → 0.2.27

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/conductor-claude-hook-bin.js

@@ -1,173 +1,3 @@
 #!/usr/bin/env node
-
-// src/conductor/claude-hook.ts
-import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-var CONDUCTOR_HOOK_EMIT_FAILED_WARNING = "Warning: conductor hook emit failed.";
-function resolveClaudeHookEventName(payload) {
-  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
-    return null;
-  }
-  const record = payload;
-  const candidates = ["hook_event_name", "hookEventName", "event_name", "event"];
-  for (const key of candidates) {
-    const value = record[key];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
-    }
-  }
-  return null;
-}
-function mapClaudeHookEventToSemanticType(eventName) {
-  switch (eventName) {
-    case "SessionStart":
-      return "run.started";
-    case "SessionEnd":
-      return "run.stopped";
-    case "Stop":
-      return null;
-    case "SubagentStop":
-      return null;
-    case "Notification":
-      return "agent.notification";
-    case "PreToolUse":
-      return "tool.intent";
-    default:
-      return null;
-  }
-}
-var REQUIRED_IDENTITY_ENV = [
-  "BAPI_CONDUCTOR_RUN_ID",
-  "BAPI_CONDUCTOR_WORKER_ID",
-  "BAPI_CONDUCTOR_TICKET_KEY",
-  "BAPI_CONDUCTOR_WORKTREE_PATH"
-];
-function nonEmpty(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function buildClaudeHookConductorEvent(payload, env) {
-  const eventName = resolveClaudeHookEventName(payload);
-  const type = mapClaudeHookEventToSemanticType(eventName);
-  if (type === null) {
-    return null;
-  }
-  if (env.BAPI_CONDUCTOR_ENABLED !== "1") {
-    return null;
-  }
-  for (const key of REQUIRED_IDENTITY_ENV) {
-    if (!nonEmpty(env[key])) {
-      return null;
-    }
-  }
-  const ticketKey = env.BAPI_CONDUCTOR_TICKET_KEY.trim();
-  const worktreePath = env.BAPI_CONDUCTOR_WORKTREE_PATH.trim();
-  const details = {
-    ticket_key: ticketKey,
-    worktree_path: worktreePath
-  };
-  if (nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME)) {
-    details.repo = env.BAPI_CONDUCTOR_REPO_NAME.trim();
-  }
-  const raw = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : { payload };
-  return {
-    source: "claude-code",
-    type,
-    subject: ticketKey,
-    run_id: env.BAPI_CONDUCTOR_RUN_ID.trim(),
-    worker_id: env.BAPI_CONDUCTOR_WORKER_ID.trim(),
-    producer: "claude-code-hook",
-    observed_via: "claude-code-hook",
-    data: {
-      details,
-      raw
-    }
-  };
-}
-function buildConductorEmitEventArgs(event) {
-  const args = ["--type", event.type, "--source", event.source];
-  if (nonEmpty(event.subject ?? void 0)) args.push("--subject", event.subject);
-  if (nonEmpty(event.run_id ?? void 0)) args.push("--run-id", event.run_id);
-  if (nonEmpty(event.worker_id ?? void 0)) args.push("--worker-id", event.worker_id);
-  if (nonEmpty(event.producer ?? void 0)) args.push("--producer", event.producer);
-  if (nonEmpty(event.observed_via ?? void 0)) {
-    args.push("--observed-via", event.observed_via);
-  }
-  args.push("--data-json-stdin", "--json");
-  return args;
-}
-function resolveConductorEmitCommand(env, emitArgs) {
-  const cliFile = env.BAPI_CONDUCTOR_CLI_FILE;
-  if (nonEmpty(cliFile)) {
-    return {
-      command: process.execPath,
-      args: [cliFile.trim(), "emit-event", ...emitArgs]
-    };
-  }
-  const bin = nonEmpty(env.BAPI_CONDUCTOR_BIN) ? env.BAPI_CONDUCTOR_BIN.trim() : "conductor";
-  return { command: bin, args: ["emit-event", ...emitArgs] };
-}
-var defaultConductorSpawn = (command, args, input) => {
-  const result = spawnSync(command, args, {
-    input,
-    encoding: "utf-8",
-    // Never use a shell: list args + stdin keep raw payloads/secrets out of any
-    // shell-interpreted command string.
-    shell: false
-  });
-  return { status: result.status, error: result.error };
-};
-function emitClaudeHookEventWithConductorCli(event, deps = {}) {
-  const env = deps.env ?? process.env;
-  const spawn = deps.spawn ?? defaultConductorSpawn;
-  const emitArgs = buildConductorEmitEventArgs(event);
-  const { command, args } = resolveConductorEmitCommand(env, emitArgs);
-  const stdinPayload = JSON.stringify(event.data ?? {});
-  try {
-    const result = spawn(command, args, stdinPayload);
-    if (result.error) return false;
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-function runClaudeConductorHookCli(deps = {}) {
-  const env = deps.env ?? process.env;
-  const readStdin = deps.readStdin ?? (() => readStdinSync());
-  const warn = deps.warn ?? ((m) => process.stderr.write(`${m}
-`));
-  let payload;
-  try {
-    const raw = readStdin();
-    payload = JSON.parse(raw);
-  } catch {
-    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
-    return 0;
-  }
-  let event;
-  try {
-    event = buildClaudeHookConductorEvent(payload, env);
-  } catch {
-    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
-    return 0;
-  }
-  if (event === null) {
-    return 0;
-  }
-  const ok = emitClaudeHookEventWithConductorCli(event, { env, spawn: deps.spawn });
-  if (!ok) {
-    warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING);
-  }
-  return 0;
-}
-function readStdinSync() {
-  return readFileSync(0, "utf-8");
-}
-
-// src/conductor-claude-hook-bin.ts
-var exitCode = 0;
-try {
-  exitCode = runClaudeConductorHookCli();
-} catch {
-  exitCode = 0;
-}
-process.exit(exitCode);
+import{spawnSync}from"node:child_process";import{readFileSync}from"node:fs";var CONDUCTOR_HOOK_EMIT_FAILED_WARNING="Warning: conductor hook emit failed.";function resolveClaudeHookEventName(payload){if(payload===null||typeof payload!="object"||Array.isArray(payload))return null;let record=payload,candidates=["hook_event_name","hookEventName","event_name","event"];for(let key of candidates){let value=record[key];if(typeof value=="string"&&value.trim().length>0)return value.trim()}return null}function mapClaudeHookEventToSemanticType(eventName){switch(eventName){case"SessionStart":return"run.started";case"SessionEnd":return"run.stopped";case"Stop":return null;case"SubagentStop":return null;case"Notification":return"agent.notification";case"PreToolUse":return"tool.intent";default:return null}}var REQUIRED_IDENTITY_ENV=["BAPI_CONDUCTOR_RUN_ID","BAPI_CONDUCTOR_WORKER_ID","BAPI_CONDUCTOR_TICKET_KEY","BAPI_CONDUCTOR_WORKTREE_PATH"];function nonEmpty(value){return typeof value=="string"&&value.trim().length>0}function buildClaudeHookConductorEvent(payload,env){let eventName=resolveClaudeHookEventName(payload),type=mapClaudeHookEventToSemanticType(eventName);if(type===null||env.BAPI_CONDUCTOR_ENABLED!=="1")return null;for(let key of REQUIRED_IDENTITY_ENV)if(!nonEmpty(env[key]))return null;let ticketKey=env.BAPI_CONDUCTOR_TICKET_KEY.trim(),worktreePath=env.BAPI_CONDUCTOR_WORKTREE_PATH.trim(),details={ticket_key:ticketKey,worktree_path:worktreePath};nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME)&&(details.repo=env.BAPI_CONDUCTOR_REPO_NAME.trim());let raw=payload!==null&&typeof payload=="object"&&!Array.isArray(payload)?payload:{payload};return{source:"claude-code",type,subject:ticketKey,run_id:env.BAPI_CONDUCTOR_RUN_ID.trim(),worker_id:env.BAPI_CONDUCTOR_WORKER_ID.trim(),producer:"claude-code-hook",observed_via:"claude-code-hook",data:{details,raw}}}function buildConductorEmitEventArgs(event){let args=["--type",event.type,"--source",event.source];return nonEmpty(event.subject??void 0)&&args.push("--subject",event.subject),nonEmpty(event.run_id??void 0)&&args.push("--run-id",event.run_id),nonEmpty(event.worker_id??void 0)&&args.push("--worker-id",event.worker_id),nonEmpty(event.producer??void 0)&&args.push("--producer",event.producer),nonEmpty(event.observed_via??void 0)&&args.push("--observed-via",event.observed_via),args.push("--data-json-stdin","--json"),args}function resolveConductorEmitCommand(env,emitArgs){let cliFile=env.BAPI_CONDUCTOR_CLI_FILE;return nonEmpty(cliFile)?{command:process.execPath,args:[cliFile.trim(),"emit-event",...emitArgs]}:{command:nonEmpty(env.BAPI_CONDUCTOR_BIN)?env.BAPI_CONDUCTOR_BIN.trim():"conductor",args:["emit-event",...emitArgs]}}var defaultConductorSpawn=(command,args,input)=>{let result=spawnSync(command,args,{input,encoding:"utf-8",shell:!1});return{status:result.status,error:result.error}};function emitClaudeHookEventWithConductorCli(event,deps={}){let env=deps.env??process.env,spawn=deps.spawn??defaultConductorSpawn,emitArgs=buildConductorEmitEventArgs(event),{command,args}=resolveConductorEmitCommand(env,emitArgs),stdinPayload=JSON.stringify(event.data??{});try{let result=spawn(command,args,stdinPayload);return result.error?!1:result.status===0}catch{return!1}}function runClaudeConductorHookCli(deps={}){let env=deps.env??process.env,readStdin=deps.readStdin??(()=>readStdinSync()),warn=deps.warn??(m=>process.stderr.write(`${m}
+`)),payload;try{let raw=readStdin();payload=JSON.parse(raw)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}let event;try{event=buildClaudeHookConductorEvent(payload,env)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}return event===null||emitClaudeHookEventWithConductorCli(event,{env,spawn:deps.spawn})||warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}function readStdinSync(){return readFileSync(0,"utf-8")}var exitCode=0;try{exitCode=runClaudeConductorHookCli()}catch{exitCode=0}process.exit(exitCode);

package/build/decision-page-template.js

@@ -59,7 +59,7 @@ function hasDisplayText(value) {
 // ---------------------------------------------------------------------------
 // Template
 // ---------------------------------------------------------------------------
-const DEFAULT_ASSETS = { faviconBase64: "", logoBase64: "", fontsRelPath: "" };
+const DEFAULT_ASSETS = { faviconBase64: "", logoBase64: "" };
 export function generateDecisionPageHtml(data, assets = DEFAULT_ASSETS) {
     const { ticket_key, actionable_items, clear_improvements } = data;
     const hasDecisions = actionable_items.length > 0;
@@ -73,7 +73,6 @@ export function generateDecisionPageHtml(data, assets = DEFAULT_ASSETS) {
     const faviconLink = assets.faviconBase64
         ? `<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,${assets.faviconBase64}">`
         : "";
-    const fontFaces = assets.fontsRelPath ? renderFontFaces(assets.fontsRelPath) : "";
     // The has-decisions intro is an overridable label; the no-decisions copy is a
     // fixed constant. For review_decisions pages the MCP handler short-circuits
     // before rendering when there are no decisions, so that branch is reachable
@@ -93,7 +92,6 @@ export function generateDecisionPageHtml(data, assets = DEFAULT_ASSETS) {
   <title>${escapeHtml(effectiveLabels.title)}: ${escapeHtml(ticket_key)}</title>
   ${faviconLink}
   <style>
-${fontFaces}
     :root {
       --primary-color: #E2624B;
       --primary-dark: #C51616;
@@ -112,7 +110,7 @@ ${fontFaces}
     }
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     body {
-      font-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
       background-color: var(--background-color);
       color: var(--text-color);
       line-height: 1.5;
@@ -541,33 +539,6 @@ ${needsForm ? renderScript(data, isPlanning) : ""}
 </html>`;
 }
 // ---------------------------------------------------------------------------
-// Font faces
-// ---------------------------------------------------------------------------
-// fontsRelPath comes from server-controlled env vars, so this is not an
-// injection vector — but a deploy path containing a single quote or backslash
-// would silently break CSS parsing and stop fonts from loading. Escape both
-// so the url('...') stays well-formed regardless of deploy layout.
-function escapeCssUrl(value) {
-    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-}
-function renderFontFaces(fontsRelPath) {
-    const weights = [
-        { weight: "400", style: "normal", file: "SourceSansPro-Regular.ttf" },
-        { weight: "400", style: "italic", file: "SourceSansPro-Italic.ttf" },
-        { weight: "600", style: "normal", file: "SourceSansPro-SemiBold.ttf" },
-        { weight: "600", style: "italic", file: "SourceSansPro-SemiBoldItalic.ttf" },
-        { weight: "700", style: "normal", file: "SourceSansPro-Bold.ttf" },
-        { weight: "700", style: "italic", file: "SourceSansPro-BoldItalic.ttf" },
-    ];
-    const safePath = escapeCssUrl(fontsRelPath);
-    return weights.map(({ weight, style, file }) => `    @font-face {
-      font-family: 'Source Sans Pro';
-      src: url('${safePath}/${escapeCssUrl(file)}') format('truetype');
-      font-weight: ${weight};
-      font-style: ${style};
-    }`).join("\n");
-}
-// ---------------------------------------------------------------------------
 // Section renderers
 // ---------------------------------------------------------------------------
 function renderHeader(assets) {

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