@bridge_gpt/mcp-server 0.1.17 → 0.2.0

package/build/agent-capabilities/runner.js

@@ -0,0 +1,56 @@
+/**
+ * Non-throwing probe runner. For each selected agent it builds a probe context,
+ * filters probes by `--only` and per-agent applicability, applies the skip-gate
+ * (binary absent, or an `env`-auth agent whose credential is unset → skip BEFORE
+ * spawning), runs each probe catching any throw as `fail`, and cleans up temp dirs.
+ */
+import { resolveAgentSpec } from "../agent-registry.js";
+import { createProbeContext } from "./probe-context.js";
+import { ALL_PROBES } from "./probes.js";
+import { AGENT_AUTH, } from "./types.js";
+/** Apply the skip-gate, then run the probe (catching throws as `fail`). */
+async function runOneProbe(deps, agentName, probe, ctx) {
+    if (probe.spawnsAgent) {
+        if (ctx.resolvedBinary === null) {
+            return { status: "skip", detail: `${ctx.agent.command} not on PATH — see binary-resolves` };
+        }
+        const auth = AGENT_AUTH[agentName];
+        if (auth.kind === "env") {
+            const value = deps.env[auth.varName];
+            if (!value || value.length === 0) {
+                return { status: "skip", detail: `${auth.varName} not set — set it to run this probe` };
+            }
+        }
+        // interactive auth (claude) cannot be verified from env — run and report the outcome.
+    }
+    try {
+        return await probe.run(ctx);
+    }
+    catch (err) {
+        return { status: "fail", detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+export async function collectCapabilityResults(deps, options) {
+    const records = [];
+    for (const agentName of options.agents) {
+        const agent = resolveAgentSpec(agentName);
+        if (!agent)
+            continue; // defensive: agent names are validated by the CLI parser
+        const applicable = ALL_PROBES.filter((p) => p.appliesTo.includes(agentName) && (!options.only || options.only.includes(p.id)));
+        const { ctx, cleanup } = await createProbeContext(deps, agent, options.timeoutMs);
+        try {
+            for (const probe of applicable) {
+                const result = await runOneProbe(deps, agentName, probe, ctx);
+                records.push({ agent: agentName, probeId: probe.id, title: probe.title, result });
+            }
+        }
+        finally {
+            await cleanup();
+        }
+    }
+    return { records };
+}
+/** True when any probe failed or hung — drives the nonzero CLI exit code. */
+export function hasFailureOrHang(collection) {
+    return collection.records.some((r) => r.result.status === "fail" || r.result.status === "hang");
+}

package/build/agent-capabilities/types.js

@@ -0,0 +1,10 @@
+/** Per-agent auth requirement used by the runner's skip-gate and the reporter. */
+export const AGENT_AUTH = {
+    claude: {
+        kind: "interactive",
+        note: "Claude Code authenticates via keychain/OAuth — cannot be verified from the environment.",
+    },
+    "cursor-agent": { kind: "env", varName: "CURSOR_API_KEY" },
+};
+/** Default hard timeout per headless probe run (ms). The cursor `-p` hang bug is version-sensitive. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 90_000;

package/build/agent-launchers/claude.js

@@ -3,7 +3,7 @@
  *
  * Resolves the `claude` binary against the *baked schedule-time PATH* (not the
  * ambient process default), builds the locked
- * `/full-automation --scheduled-at <T> --idea-file <abs> [--auto-approve]`
+ * `/full-automation --scheduled-at <T> --idea-file <abs> [--auto]`
  * prompt, and emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
  * working-directory flag, so the cwd is always set by the scheduler unit — this
  * adapter must never add a cwd argument to the invocation.
@@ -51,13 +51,13 @@ export function quoteIdeaFileForPrompt(ideaFile) {
     return `"${ideaFile.replace(/"/g, '\\"')}"`;
 }
 /**
- * Build the exact full-automation prompt. `--auto-approve` is appended by
- * default; it is omitted only when the caller selected `--no-auto-approve`.
+ * Build the exact full-automation prompt. `--auto` is appended by
+ * default; it is omitted only when the caller selected `--no-auto`.
  */
 export function buildClaudePrompt(input) {
     const base = `/full-automation --scheduled-at ${input.runAtIso} ` +
         `--idea-file ${quoteIdeaFileForPrompt(input.ideaFile)}`;
-    return input.autoApprove ? `${base} --auto-approve` : base;
+    return input.autoApprove ? `${base} --auto` : base;
 }
 const CLAUDE_CAPABILITY = {
     name: "claude",

package/build/agents.generated.js

@@ -8,6 +8,6 @@ export const AGENTS = {
             "model": "opus",
             "color": "blue"
         },
-        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Checklist format using markdown checkboxes. Each criterion is a testable, verifiable condition.]\n\n- [ ] [Specific, testable criterion]\n- [ ] [Another criterion]\n- [ ] [Continue as needed]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use checkbox format (`- [ ]`) so engineers can track progress\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
+        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links.\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
     }
 };

package/build/brainstorm-files.js

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// brainstorm-files
+// ---------------------------------------------------------------------------
+// Pure, side-effect-free helpers for naming and writing brainstorm result
+// files. Extracted from ``index.ts`` so they can be unit-tested directly —
+// ``index.ts`` self-executes its CLI/server at module top level and therefore
+// cannot be imported from a test. ``index.ts`` imports these as the single
+// source of truth (no logic is duplicated there).
+import { writeFile, mkdir } from "fs/promises";
+import path from "path";
+/**
+ * Lowercase, strip non-alphanumeric runs, collapse to single hyphens, cap to
+ * ``maxLength`` characters, and trim a trailing hyphen. Shared generic helper
+ * (also used for deep-research query slugs in ``index.ts``).
+ */
+export function slugify(text, maxLength = 60) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .slice(0, maxLength)
+        .replace(/-$/, "");
+}
+export function sanitizeProviderForFilename(provider) {
+    // Defensive: allow letters/digits/hyphen/underscore only; collapse runs and
+    // trim trailing punctuation. Falls back to "provider" for an empty result.
+    const cleaned = provider
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "provider";
+}
+/**
+ * Build the on-disk filename for one brainstorm result row.
+ *
+ * When the original task ``subject`` is available and slugifies to a non-empty
+ * string, use a human-readable semantic name:
+ *   ``{slugified-subject}-{short_brainstorm_id}-{provider}.md``
+ * where ``short_brainstorm_id`` is the first 8 chars of the brainstorm UUID
+ * (enough for practical uniqueness / idempotent overwrite on re-runs).
+ *
+ * The UUID-only pattern ``{brainstorm_id}-{provider}.md`` is the intentional
+ * backward-compatible fallback, used only when no subject is provided, the
+ * subject is whitespace-only, or ``slugify(subject)`` returns an empty string
+ * (e.g. punctuation-only). This keeps callers without a subject — notably the
+ * ``get_brainstorm`` retrieval path, whose result envelope does not echo
+ * ``task_description`` — safe and unchanged.
+ */
+export function buildBrainstormResultFilename(envelope, row, subject) {
+    const providerSegment = sanitizeProviderForFilename(row.provider);
+    const subjectSlug = subject ? slugify(subject) : "";
+    const shortId = envelope.brainstorm_id.slice(0, 8);
+    if (subjectSlug) {
+        return `${subjectSlug}-${shortId}-${providerSegment}.md`;
+    }
+    return `${envelope.brainstorm_id}-${providerSegment}.md`;
+}
+/**
+ * Write each brainstorm result row's markdown into ``dir`` using
+ * ``buildBrainstormResultFilename`` for the name. ``index.ts`` wraps this with
+ * the resolved ``BAPI_DOCS_DIR/brainstorm`` directory.
+ *
+ * Behavior is fail-open: rows without markdown are skipped, the directory is
+ * created recursively, markdown is written as UTF-8, and per-row write failures
+ * are swallowed so saving never blocks the tool response.
+ */
+export async function saveBrainstormResultsToDir(envelope, dir, subject) {
+    const savedPaths = [];
+    for (const row of envelope.results) {
+        const markdown = row.markdown;
+        if (!markdown) {
+            continue;
+        }
+        const filename = buildBrainstormResultFilename(envelope, row, subject);
+        const filePath = path.join(dir, filename);
+        try {
+            await mkdir(dir, { recursive: true });
+            await writeFile(filePath, markdown, "utf-8");
+            savedPaths.push(filePath);
+        }
+        catch {
+            // Skip rows that fail to write — never block the response.
+        }
+    }
+    return savedPaths;
+}

package/build/bridge-config.js

@@ -0,0 +1,404 @@
+/**
+ * Reader and validator for the committed, secret-free `.bridge/config` manifest.
+ *
+ * The manifest is a tiny, hand-written TOML subset — `repo_name` plus repeated
+ * `[[mcp]]` target blocks — committed at the repo root and inherited by every
+ * git worktree. It NEVER contains credentials; this module only resolves repo
+ * identity and which MCP targets a worktree should be provisioned for.
+ *
+ * Everything is dependency-free (no TOML runtime dependency) and dependency
+ * injected (`readFile`, optional `runCommand`) so it is unit-testable without
+ * touching the filesystem or invoking real `git`.
+ */
+import path from "path";
+/**
+ * True if a string contains any ASCII control character (0x00-0x1f or 0x7f).
+ * Keeps identifiers path-safe and free of anything that could smuggle into a
+ * shell argument or filename. Implemented by char-code scan to avoid a
+ * control-character regex literal in source.
+ */
+function hasControlChars(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Identifier validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a repo-name identifier. Requires a trimmed, non-empty string with no
+ * path separators or ASCII control characters. Returns a structured result with
+ * the trimmed value rather than throwing.
+ */
+export function validateRepoName(raw) {
+    if (typeof raw !== "string") {
+        return { ok: false, error: "repo_name must be a string" };
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        return { ok: false, error: "repo_name must be a non-empty string" };
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        return { ok: false, error: "repo_name must not contain path separators" };
+    }
+    if (hasControlChars(value)) {
+        return { ok: false, error: "repo_name must not contain control characters" };
+    }
+    return { ok: true, value };
+}
+/**
+ * Validate an MCP target identifier. Same path-safety rules as repo names.
+ * Non-`bapi` targets validate successfully (parsing is not hard-coded to
+ * `bapi`); only `bapi` is acted on elsewhere for this MVP.
+ */
+export function validateMcpTarget(raw) {
+    if (typeof raw !== "string") {
+        return { ok: false, error: "mcp target must be a string" };
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        return { ok: false, error: "mcp target must be a non-empty string" };
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        return { ok: false, error: "mcp target must not contain path separators" };
+    }
+    if (hasControlChars(value)) {
+        return { ok: false, error: "mcp target must not contain control characters" };
+    }
+    return { ok: true, value };
+}
+// ---------------------------------------------------------------------------
+// TOML subset parser
+// ---------------------------------------------------------------------------
+/** Extract the inner content of a `"..."` double-quoted string, or null. */
+function parseQuotedString(value) {
+    if (value.length < 2)
+        return null;
+    if (value[0] !== '"' || value[value.length - 1] !== '"')
+        return null;
+    const inner = value.slice(1, -1);
+    // The supported subset does not include escapes or embedded quotes.
+    if (inner.includes('"'))
+        return null;
+    return inner;
+}
+/**
+ * Parse a minimal, dependency-free TOML string array: `[ "a", "b" ]`. Elements
+ * are double-quoted, comma-free strings; whitespace around brackets, commas, and
+ * elements is ignored. An empty `[]` yields `[]`. Returns null on any malformed
+ * input (so callers can emit a secret-safe error that never echoes the value).
+ */
+function parseStringArray(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 2 || trimmed[0] !== "[" || trimmed[trimmed.length - 1] !== "]") {
+        return null;
+    }
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner.length === 0)
+        return [];
+    const parts = inner.split(",");
+    const out = [];
+    for (const part of parts) {
+        const element = parseQuotedString(part.trim());
+        if (element === null)
+            return null;
+        out.push(element);
+    }
+    return out;
+}
+/**
+ * Parse the supported `.bridge/config` TOML subset:
+ *   - a single top-level `repo_name = "..."`
+ *   - zero or more `[[mcp]]` sections, each with `target = "..."`
+ *   - `#` comments, blank lines, and surrounding whitespace
+ *
+ * Anything outside this subset (other keys, single-bracket tables, unquoted or
+ * unterminated strings, duplicate `repo_name`, `target` outside `[[mcp]]`) is a
+ * structured error. Error messages reference line numbers and key names only —
+ * never the raw manifest content or a value — so secrets can never leak through
+ * a misplaced line.
+ */
+export function parseBridgeConfigToml(text) {
+    const lines = text.split("\n");
+    let repoName;
+    let sawRepoName = false;
+    const mcp = [];
+    // null = top-level scope; otherwise points at the in-progress [[mcp]] block.
+    let currentMcp = null;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const line = lines[i].trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        if (line === "[[mcp]]") {
+            currentMcp = { headerLine: lineNo };
+            mcp.push(currentMcp);
+            continue;
+        }
+        // Any other bracketed table header is unsupported.
+        if (line.startsWith("[")) {
+            return {
+                ok: false,
+                kind: "parse-error",
+                error: `Unsupported table header on line ${lineNo}; only [[mcp]] is allowed`,
+            };
+        }
+        const eq = line.indexOf("=");
+        if (eq === -1) {
+            return {
+                ok: false,
+                kind: "parse-error",
+                error: `Malformed line ${lineNo}; expected key = "value"`,
+            };
+        }
+        const key = line.slice(0, eq).trim();
+        const rawValue = line.slice(eq + 1).trim();
+        if (key.length === 0) {
+            return {
+                ok: false,
+                kind: "parse-error",
+                error: `Malformed line ${lineNo}; missing key`,
+            };
+        }
+        if (currentMcp === null) {
+            // Top-level scope: only repo_name is allowed.
+            if (key === "repo_name") {
+                if (sawRepoName) {
+                    return {
+                        ok: false,
+                        kind: "parse-error",
+                        error: `Duplicate repo_name on line ${lineNo}`,
+                    };
+                }
+                sawRepoName = true;
+                const stringValue = parseQuotedString(rawValue);
+                if (stringValue === null) {
+                    return {
+                        ok: false,
+                        kind: "parse-error",
+                        error: `Expected a double-quoted string for '${key}' on line ${lineNo}`,
+                    };
+                }
+                const validated = validateRepoName(stringValue);
+                if (!validated.ok) {
+                    return { ok: false, kind: "validation-error", error: validated.error };
+                }
+                repoName = validated.value;
+                continue;
+            }
+            if (key === "target") {
+                return {
+                    ok: false,
+                    kind: "parse-error",
+                    error: `target on line ${lineNo} must appear inside an [[mcp]] section`,
+                };
+            }
+            return {
+                ok: false,
+                kind: "parse-error",
+                error: `Unsupported key '${key}' on line ${lineNo}`,
+            };
+        }
+        // Inside an [[mcp]] block: target / command / args / secret_bundle.
+        if (key === "args") {
+            if (currentMcp.args !== undefined) {
+                return { ok: false, kind: "parse-error", error: `Duplicate args on line ${lineNo}` };
+            }
+            const arr = parseStringArray(rawValue);
+            if (arr === null) {
+                return {
+                    ok: false,
+                    kind: "parse-error",
+                    error: `Expected a string array for 'args' on line ${lineNo}`,
+                };
+            }
+            currentMcp.args = arr;
+            continue;
+        }
+        if (key === "target" || key === "command" || key === "secret_bundle") {
+            const stringValue = parseQuotedString(rawValue);
+            if (stringValue === null) {
+                return {
+                    ok: false,
+                    kind: "parse-error",
+                    error: `Expected a double-quoted string for '${key}' on line ${lineNo}`,
+                };
+            }
+            if (key === "target") {
+                if (currentMcp.target !== undefined) {
+                    return { ok: false, kind: "parse-error", error: `Duplicate target on line ${lineNo}` };
+                }
+                const validated = validateMcpTarget(stringValue);
+                if (!validated.ok) {
+                    return { ok: false, kind: "validation-error", error: validated.error };
+                }
+                currentMcp.target = validated.value;
+                continue;
+            }
+            if (key === "command") {
+                if (currentMcp.command !== undefined) {
+                    return { ok: false, kind: "parse-error", error: `Duplicate command on line ${lineNo}` };
+                }
+                currentMcp.command = stringValue;
+                continue;
+            }
+            // secret_bundle
+            if (currentMcp.secretBundle !== undefined) {
+                return { ok: false, kind: "parse-error", error: `Duplicate secret_bundle on line ${lineNo}` };
+            }
+            currentMcp.secretBundle = stringValue;
+            continue;
+        }
+        return {
+            ok: false,
+            kind: "parse-error",
+            error: `Unsupported key '${key}' inside [[mcp]] on line ${lineNo}`,
+        };
+    }
+    if (!sawRepoName || repoName === undefined) {
+        return { ok: false, kind: "validation-error", error: "Missing required repo_name" };
+    }
+    const cleaned = [];
+    for (const entry of mcp) {
+        if (entry.target === undefined) {
+            return {
+                ok: false,
+                kind: "validation-error",
+                error: `An [[mcp]] section on line ${entry.headerLine} is missing its target`,
+            };
+        }
+        if (entry.target !== "bapi") {
+            // Tier-2 targets must declare a launch command, an args array, and the
+            // store bundle that provides their secrets.
+            if (entry.command === undefined || entry.command.trim().length === 0) {
+                return {
+                    ok: false,
+                    kind: "validation-error",
+                    error: `[[mcp]] target '${entry.target}' on line ${entry.headerLine} requires a non-empty command`,
+                };
+            }
+            if (entry.args === undefined) {
+                return {
+                    ok: false,
+                    kind: "validation-error",
+                    error: `[[mcp]] target '${entry.target}' on line ${entry.headerLine} requires an args array`,
+                };
+            }
+            if (entry.secretBundle === undefined || entry.secretBundle.trim().length === 0) {
+                return {
+                    ok: false,
+                    kind: "validation-error",
+                    error: `[[mcp]] target '${entry.target}' on line ${entry.headerLine} requires a non-empty secret_bundle`,
+                };
+            }
+        }
+        const clean = { target: entry.target };
+        if (entry.command !== undefined)
+            clean.command = entry.command;
+        if (entry.args !== undefined)
+            clean.args = entry.args;
+        if (entry.secretBundle !== undefined)
+            clean.secretBundle = entry.secretBundle;
+        cleaned.push(clean);
+    }
+    return { ok: true, manifest: { repoName, mcp: cleaned } };
+}
+// ---------------------------------------------------------------------------
+// Reading + identity resolution
+// ---------------------------------------------------------------------------
+/** Absolute path to a project root's committed manifest. */
+export function bridgeConfigPath(projectRoot) {
+    return path.join(projectRoot, ".bridge", "config");
+}
+/**
+ * Read and parse `<projectRoot>/.bridge/config`. A missing file is the common,
+ * non-fatal case (`kind: "missing"`); malformed/invalid content surfaces as a
+ * structured error. Raw manifest content is never echoed back.
+ */
+export async function readBridgeConfig(projectRoot, deps) {
+    const filePath = bridgeConfigPath(projectRoot);
+    let raw;
+    try {
+        raw = await deps.readFile(filePath);
+    }
+    catch (err) {
+        if (err && typeof err === "object" && err.code === "ENOENT") {
+            return { ok: false, kind: "missing" };
+        }
+        return { ok: false, kind: "parse-error", error: "Unable to read .bridge/config" };
+    }
+    return parseBridgeConfigToml(raw);
+}
+/** True only when the manifest contains an exact target match (e.g. `"bapi"`). */
+export function hasMcpTarget(manifest, target) {
+    return manifest.mcp.some((entry) => entry.target === target);
+}
+/**
+ * Derive the repo name from `git rev-parse --git-common-dir`, run with the
+ * passed `projectRoot` as `cwd` (so a worktree resolves to its parent repo's
+ * identity). The common dir is the directory immediately before the `.git`
+ * path segment, e.g. `<repo>/bapi/.git` and `<repo>/bapi/.git/worktrees/X` both
+ * derive `bapi`.
+ */
+export async function deriveRepoNameFromGitCommonDir(projectRoot, deps) {
+    if (!deps.runCommand) {
+        return { ok: false, error: "Cannot derive repo name: no command runner available" };
+    }
+    let result;
+    try {
+        result = await deps.runCommand("git", ["rev-parse", "--git-common-dir"], {
+            cwd: projectRoot,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `git rev-parse --git-common-dir failed: ${message}` };
+    }
+    if (result.exitCode !== 0) {
+        const reason = (result.stderr || result.stdout || "").trim();
+        return {
+            ok: false,
+            error: `git rev-parse --git-common-dir failed${reason ? `: ${reason}` : ""}`,
+        };
+    }
+    const commonDir = result.stdout.trim();
+    if (commonDir.length === 0) {
+        return { ok: false, error: "git rev-parse --git-common-dir returned no output" };
+    }
+    const resolved = path.isAbsolute(commonDir)
+        ? commonDir
+        : path.resolve(projectRoot, commonDir);
+    const segments = resolved.split(/[\\/]+/).filter((s) => s.length > 0);
+    const gitIndex = segments.lastIndexOf(".git");
+    if (gitIndex < 1) {
+        return {
+            ok: false,
+            error: "Unable to derive repo name from git common dir",
+        };
+    }
+    const derived = segments[gitIndex - 1];
+    const validated = validateRepoName(derived);
+    if (!validated.ok) {
+        return { ok: false, error: `Derived repo name is invalid: ${validated.error}` };
+    }
+    return { ok: true, value: validated.value };
+}
+/**
+ * Resolve the repo name for a project root. A valid manifest `repo_name` wins;
+ * a *missing* manifest falls back to the git-common-dir derivation; a malformed
+ * or invalid manifest returns a structured error rather than silently falling
+ * back (so a broken committed file is never papered over by git guessing).
+ */
+export async function resolveRepoNameForProjectRoot(projectRoot, deps) {
+    const read = await readBridgeConfig(projectRoot, deps);
+    if (read.ok) {
+        return { ok: true, value: read.manifest.repoName };
+    }
+    if (read.kind === "missing") {
+        return deriveRepoNameFromGitCommonDir(projectRoot, deps);
+    }
+    return { ok: false, error: read.error };
+}