@bridge_gpt/mcp-server 0.2.6 → 0.2.10

package/build/init.js

@@ -0,0 +1,481 @@
+/**
+ * Bridge API project scaffolding (`--init`).
+ *
+ * Extracted from `index.ts` (BAPI-429) so the scaffolding logic can be reused by
+ * the `install-bridge` CLI subcommand without importing `index.ts` — `index.ts`
+ * constructs and connects the MCP server at module top level, so importing it
+ * from a subcommand module would start the server as a side effect AND create a
+ * circular dependency (`index.ts` imports `runInstallBridgeCli`, which would
+ * import `runInit` back from `index.ts`). This module has no top-level side
+ * effects and depends only on leaf modules.
+ */
+import { writeFile, mkdir, readFile, stat } from "fs/promises";
+import path from "path";
+import { COMMANDS } from "./commands.generated.js";
+import { AGENTS } from "./agents.generated.js";
+import { VERSION } from "./version.generated.js";
+import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
+import { validateRepoName } from "./bridge-config.js";
+import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
+// ---------------------------------------------------------------------------
+// CLI: --init scaffolds slash commands and MCP configs into the current project
+// ---------------------------------------------------------------------------
+export function buildBridgeApiEntry(cwd) {
+    // Secret-free by design: BAPI_API_KEY is NEVER scaffolded into generated MCP
+    // config. The server self-resolves the key from the environment or the
+    // home-dir credential store (~/.config/bridge/credentials.json) at runtime.
+    //
+    // R4a (BAPI-429): the launcher is pinned to the EXACT running version
+    // (`@bridge_gpt/mcp-server@${VERSION}`, sourced from version.generated.js)
+    // rather than the unpinned name. An unpinned `npx -y @bridge_gpt/mcp-server`
+    // lets npx silently reuse a stale local copy of the server (a verified bug
+    // where 0.2.6 persisted despite an upgrade). Pinning keeps the running
+    // configuration predictable and visible in version control. The `install-bridge`
+    // config write reuses this same entry so both install paths agree.
+    return {
+        command: "npx",
+        args: ["-y", `@bridge_gpt/mcp-server@${VERSION}`],
+        env: {
+            BAPI_BASE_URL: "https://bridgegpt-api.com",
+            BAPI_REPO_NAME: "YOUR_REPO_NAME",
+            BAPI_DOCS_DIR: "docs/tmp",
+            BAPI_PROJECT_ROOT: cwd,
+        },
+    };
+}
+/**
+ * Choose the `repo_name` written into a scaffolded `.bridge/config`. Uses the
+ * cwd basename when it passes manifest repo-name validation; otherwise falls
+ * back to the `YOUR_REPO_NAME` placeholder for the user to edit.
+ */
+export function chooseScaffoldRepoName(cwd) {
+    const validated = validateRepoName(path.basename(cwd));
+    return validated.ok ? validated.value : "YOUR_REPO_NAME";
+}
+/** Build the secret-free `.bridge/config` TOML scaffolded by `--init`. */
+export function buildBridgeConfigManifest(repoName) {
+    return [
+        "# Bridge API repository MCP manifest (committed, secret-free, machine-agnostic).",
+        "#",
+        "# Inherited by every git worktree; start-tickets worktree provisioning reads it",
+        "# to decide which Bridge API MCP registrations to write. Do not add credentials,",
+        "# connection URLs, or machine-specific paths here — those are resolved at runtime.",
+        "",
+        `repo_name = "${repoName}"`,
+        "",
+        "[[mcp]]",
+        'target = "bapi"',
+        "",
+        "# Optional: declare additional (Tier-2) MCP targets here. Each non-bapi target",
+        "# names the real command/args to launch and the credential-store bundle that",
+        "# supplies its secrets — never the secrets themselves. Uncomment and adapt:",
+        "#",
+        "# [[mcp]]",
+        '# target = "sfcc"',
+        '# command = "npx"',
+        '# args = ["-y", "@salesforce/b2c-dx-mcp"]',
+        '# secret_bundle = "sfcc:YOUR_SANDBOX_ID"',
+        "",
+    ].join("\n");
+}
+async function ensureGitignored(cwd, filePath) {
+    await ensureGitignoredShared(cwd, filePath, {
+        readFile: (p) => readFile(p, "utf-8"),
+        writeFile: (p, data) => writeFile(p, data, "utf-8"),
+        mkdir: (p, options) => mkdir(p, options),
+    });
+}
+/**
+ * Core initialization logic shared by --init and --upgrade.
+ * Runs all scaffolding phases without calling process.exit().
+ */
+export async function runInit(cwd) {
+    // ---- Phase 1: IDE Detection ----
+    const ideDetection = {
+        claude: true,
+        vscode: false,
+        cursor: false,
+        windsurf: false,
+    };
+    try {
+        await stat(path.join(cwd, ".vscode"));
+        ideDetection.vscode = true;
+    }
+    catch { }
+    try {
+        await stat(path.join(cwd, ".cursor"));
+        ideDetection.cursor = true;
+    }
+    catch { }
+    if (!ideDetection.cursor && process.env.CURSOR_TRACE_DIR)
+        ideDetection.cursor = true;
+    try {
+        await stat(path.join(cwd, ".windsurf"));
+        ideDetection.windsurf = true;
+    }
+    catch { }
+    if (!ideDetection.windsurf) {
+        try {
+            await stat(path.join(cwd, ".windsurfrules"));
+            ideDetection.windsurf = true;
+        }
+        catch { }
+    }
+    const detectedIDEs = Object.entries(ideDetection)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+    console.log(`Bridge API --init: detected IDEs: ${detectedIDEs.join(", ")}`);
+    // ---- Phase 2: Windsurf manual instructions ----
+    if (ideDetection.windsurf) {
+        const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": buildBridgeApiEntry(cwd) } }, null, 2);
+        console.log("\n⚠ Windsurf does not support project-local MCP configuration.\n" +
+            "Add the following to ~/.codeium/windsurf/mcp_config.json:\n\n" +
+            windsurfSnippet + "\n");
+    }
+    // ---- Phase 3: Config file handling ----
+    const configTargets = [
+        { path: ".mcp.json", topLevelKey: "mcpServers", shouldCreate: true },
+        { path: ".vscode/mcp.json", topLevelKey: "servers", shouldCreate: ideDetection.vscode },
+        { path: ".cursor/mcp.json", topLevelKey: "mcpServers", shouldCreate: ideDetection.cursor },
+    ];
+    const configActions = [];
+    let anyCreatedOrAdded = false;
+    for (const target of configTargets) {
+        const fullPath = path.join(cwd, target.path);
+        let fileExists = false;
+        try {
+            await stat(fullPath);
+            fileExists = true;
+        }
+        catch { }
+        if (!target.shouldCreate && !fileExists) {
+            configActions.push({ path: target.path, action: "skipped — IDE not detected" });
+            continue;
+        }
+        if (fileExists) {
+            // Read and parse existing file
+            const raw = await readFile(fullPath, "utf-8");
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                console.warn(`  ${target.path} skipped — invalid JSON format`);
+                configActions.push({ path: target.path, action: "skipped — invalid JSON" });
+                continue;
+            }
+            const topLevel = parsed[target.topLevelKey];
+            if (topLevel && topLevel["bridge-api"]) {
+                // Entry exists — update BAPI_PROJECT_ROOT and launcher args to preserve exact version pin.
+                // Note: command is always rewritten to "npx". A custom launcher (e.g. "bun x", wrapper
+                // script) will be replaced. This is intentional for the standard npx-based setup.
+                const entryTemplate = buildBridgeApiEntry(cwd);
+                const prevCommand = topLevel["bridge-api"].command;
+                if (prevCommand && prevCommand !== entryTemplate.command) {
+                    console.warn(`Warning: replacing launcher "${prevCommand}" with "${entryTemplate.command}" in ${target.path}. If you use a custom launcher, re-add it after this upgrade.`);
+                }
+                topLevel["bridge-api"].command = entryTemplate.command;
+                topLevel["bridge-api"].args = entryTemplate.args;
+                if (!topLevel["bridge-api"].env)
+                    topLevel["bridge-api"].env = {};
+                topLevel["bridge-api"].env.BAPI_PROJECT_ROOT = cwd;
+                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+                configActions.push({ path: target.path, action: "updated entry and pinned version" });
+            }
+            else {
+                // Entry missing — add it, preserving existing content
+                if (!parsed[target.topLevelKey])
+                    parsed[target.topLevelKey] = {};
+                parsed[target.topLevelKey]["bridge-api"] = buildBridgeApiEntry(cwd);
+                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+                configActions.push({ path: target.path, action: "added entry" });
+                anyCreatedOrAdded = true;
+            }
+        }
+        else {
+            // Create new file
+            await mkdir(path.dirname(fullPath), { recursive: true });
+            const content = { [target.topLevelKey]: { "bridge-api": buildBridgeApiEntry(cwd) } };
+            await writeFile(fullPath, JSON.stringify(content, null, 2) + "\n", "utf-8");
+            await ensureGitignored(cwd, target.path);
+            configActions.push({ path: target.path, action: "created" });
+            anyCreatedOrAdded = true;
+        }
+    }
+    console.log("\nMCP config files:");
+    for (const entry of configActions) {
+        console.log(`  ${entry.path}: ${entry.action}`);
+    }
+    // ---- Phase 4: Scaffold slash command directories ----
+    const commandDirs = [path.join(cwd, ".claude", "commands")];
+    if (ideDetection.cursor) {
+        commandDirs.push(path.join(cwd, ".cursor", "commands"));
+    }
+    const writtenFiles = new Set();
+    const skippedFiles = new Set();
+    const overwrittenFiles = new Set();
+    for (const dir of commandDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [filename, content] of Object.entries(COMMANDS)) {
+            const target = path.join(dir, filename);
+            try {
+                const existing = await readFile(target, "utf-8");
+                if (existing === content) {
+                    skippedFiles.add(filename);
+                    continue;
+                }
+                overwrittenFiles.add(filename);
+            }
+            catch { /* file doesn't exist */ }
+            await writeFile(target, content, "utf-8");
+            writtenFiles.add(filename);
+        }
+    }
+    // A file written in any directory takes priority over skipped
+    for (const f of writtenFiles)
+        skippedFiles.delete(f);
+    const total = Object.keys(COMMANDS).length;
+    const dirNames = commandDirs.map((d) => path.relative(cwd, d)).join(" and ");
+    console.log(`\nSlash commands: scaffolded ${total} commands into ${commandDirs.length} director${commandDirs.length === 1 ? "y" : "ies"}`);
+    if (writtenFiles.size > 0)
+        console.log(`  Written: ${writtenFiles.size}`);
+    if (overwrittenFiles.size > 0)
+        console.log(`  Overwritten (content changed): ${overwrittenFiles.size}`);
+    if (skippedFiles.size > 0)
+        console.log(`  Skipped (unchanged): ${skippedFiles.size}`);
+    console.log(`  ${dirNames}`);
+    // ---- Phase 5: Scaffold agent directories ----
+    const agentWritten = new Set();
+    const agentSkipped = new Set();
+    const agentOverwritten = new Set();
+    // Always scaffold to .claude/agents/
+    const claudeAgentsDir = path.join(cwd, ".claude", "agents");
+    await mkdir(claudeAgentsDir, { recursive: true });
+    for (const [key, agent] of Object.entries(AGENTS)) {
+        const filename = `${key}.md`;
+        const content = reconstructAgentMarkdown(agent.frontmatter, agent.body);
+        const target = path.join(claudeAgentsDir, filename);
+        try {
+            const existing = await readFile(target, "utf-8");
+            if (existing === content) {
+                agentSkipped.add(filename);
+                continue;
+            }
+            agentOverwritten.add(filename);
+        }
+        catch { /* file doesn't exist */ }
+        await writeFile(target, content, "utf-8");
+        agentWritten.add(filename);
+    }
+    // Scaffold to .github/agents/ for VS Code / Copilot
+    if (ideDetection.vscode) {
+        const copilotAgentsDir = path.join(cwd, ".github", "agents");
+        await mkdir(copilotAgentsDir, { recursive: true });
+        for (const [key, agent] of Object.entries(AGENTS)) {
+            const filename = `${key}.agent.md`;
+            const content = translateAgentToCopilot(agent.frontmatter, agent.body);
+            const target = path.join(copilotAgentsDir, filename);
+            try {
+                const existing = await readFile(target, "utf-8");
+                if (existing === content) {
+                    agentSkipped.add(filename);
+                    continue;
+                }
+                agentOverwritten.add(filename);
+            }
+            catch { /* file doesn't exist */ }
+            await writeFile(target, content, "utf-8");
+            agentWritten.add(filename);
+        }
+    }
+    // TODO: Add Cursor agent scaffolding when Cursor publishes a formal agent spec
+    // A file written in any directory takes priority over skipped
+    for (const f of agentWritten)
+        agentSkipped.delete(f);
+    const agentTotal = Object.keys(AGENTS).length;
+    console.log(`\nAgents: scaffolded ${agentTotal} agent${agentTotal === 1 ? "" : "s"}`);
+    if (agentWritten.size > 0)
+        console.log(`  Written: ${agentWritten.size}`);
+    if (agentOverwritten.size > 0)
+        console.log(`  Overwritten (content changed): ${agentOverwritten.size}`);
+    if (agentSkipped.size > 0)
+        console.log(`  Skipped (unchanged): ${agentSkipped.size}`);
+    // ---- Phase 6: Scaffold custom pipeline directories ----
+    const pipelinesDir = path.resolve(cwd, process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
+    const instrDir = path.join(path.dirname(pipelinesDir), "instructions");
+    await mkdir(pipelinesDir, { recursive: true });
+    await mkdir(instrDir, { recursive: true });
+    const readmePath = path.join(pipelinesDir, "README.md");
+    const examplePath = path.join(pipelinesDir, "example-pipeline.json");
+    const readmeContent = `# Custom Pipelines
+
+Place custom pipeline JSON files in this directory. They will be loaded at
+server startup and available alongside the bundled pipelines.
+
+## JSON Schema
+
+Each pipeline file must be a JSON object with these fields:
+
+| Field         | Type       | Required | Description                              |
+|---------------|------------|----------|------------------------------------------|
+| \`name\`        | string     | yes      | Display name of the pipeline             |
+| \`description\`  | string     | no       | Short description shown in list_pipelines |
+| \`variables\`    | string[]   | no       | Variable names for substitution          |
+| \`steps\`        | Step[]     | yes      | Ordered list of steps to execute         |
+
+## Step Types
+
+### mcp_call
+Calls an MCP tool with specific parameters.
+\`\`\`json
+{
+  "type": "mcp_call",
+  "tool": "tool_name",
+  "params": { "key": "value" },
+  "description": "What this step does",
+  "on_error": "halt",
+  "requires_approval": false
+}
+\`\`\`
+
+### agent_task
+Gives the agent a free-form instruction to execute.
+\`\`\`json
+{
+  "type": "agent_task",
+  "instruction": "Do something specific",
+  "description": "What this step does",
+  "on_error": "warn_and_continue"
+}
+\`\`\`
+
+Or reference an instruction file from \`.bridge/instructions/\`:
+\`\`\`json
+{
+  "type": "agent_task",
+  "instruction_file": "my-instructions.md",
+  "description": "What this step does"
+}
+\`\`\`
+
+## Variables
+
+Declare variables in the \`variables\` array and reference them with \`{variable_name}\`
+in step params, instructions, and descriptions. The \`docs_dir\` variable is
+automatically provided by the server.
+
+## on_error
+
+- \`"halt"\` (default) — stop the pipeline immediately on failure
+- \`"warn_and_continue"\` — log a warning and proceed to the next step
+
+## Executing Pipelines
+
+Pipelines defined here can be executed end-to-end via the \`run_pipeline\` MCP
+tool. \`run_pipeline\` returns a unified envelope keyed on \`status\`:
+
+- \`completed\` — the pipeline finished and \`results\` holds the per-step output.
+- \`needs_agent_task\` — the orchestrator paused on an \`agent_task\` step (or an
+  approval-gated \`mcp_call\` when \`auto_approve\` was false). Perform the task
+  described by \`instruction\`, then call \`resume_pipeline\` with the
+  \`pipeline_run_id\` and the resulting string as \`agent_result\`.
+- \`failed\` — terminal failure; \`error_code\` is one of \`VALIDATION\`,
+  \`NOT_FOUND\`, \`EXPIRED\`, \`REPO_MISMATCH\`, or \`TOOL_ERROR\`.
+
+Paused runs auto-expire after an idle TTL (default 24 hours, override via
+\`ttl_seconds\` on \`run_pipeline\`). The TTL is reset on every state transition.
+Use \`list_pipeline_runs\` to recover a \`pipeline_run_id\` if the prior
+\`needs_agent_task\` envelope is no longer in scope.
+
+## \`agent_task\` Instruction Files
+
+When you reference an instruction file (\`instruction_file: "…"\`), the file
+markdown MUST end with a terminal \`## Return\` H2 section describing what the
+agent should pass back as \`resume_pipeline.agent_result\`. The return value
+is a string — do NOT ask the agent to wrap it in JSON unless the instruction
+body explicitly says to serialize structured output.
+`;
+    const exampleContent = JSON.stringify({
+        name: "Example Pipeline",
+        description: "A sample pipeline demonstrating all step types and features.",
+        variables: ["ticket_key"],
+        steps: [
+            {
+                type: "mcp_call",
+                tool: "get_ticket",
+                params: { ticket_number: "{ticket_key}" },
+                description: "Fetch the ticket details from Jira",
+                on_error: "halt",
+            },
+            {
+                type: "agent_task",
+                instruction: "Read the ticket details above and summarize the key requirements in 3 bullet points.",
+                description: "Summarize ticket requirements",
+                on_error: "halt",
+            },
+            {
+                type: "agent_task",
+                instruction: "Search the codebase for files related to the ticket and list the top 5 most relevant files.",
+                description: "Find relevant source files",
+                on_error: "warn_and_continue",
+            },
+            {
+                type: "mcp_call",
+                tool: "add_comment",
+                params: {
+                    ticket_number: "{ticket_key}",
+                    comment_text: "Pipeline analysis complete. See agent output for details.",
+                },
+                description: "Post a summary comment to the ticket",
+                on_error: "warn_and_continue",
+                requires_approval: true,
+            },
+        ],
+    }, null, 2) + "\n";
+    try {
+        await stat(readmePath);
+        console.log(`  ${path.relative(cwd, readmePath)} (skipped — already exists)`);
+    }
+    catch {
+        await writeFile(readmePath, readmeContent, "utf-8");
+        console.log(`  ${path.relative(cwd, readmePath)} (written)`);
+    }
+    try {
+        await stat(examplePath);
+        console.log(`  ${path.relative(cwd, examplePath)} (skipped — already exists)`);
+    }
+    catch {
+        await writeFile(examplePath, exampleContent, "utf-8");
+        console.log(`  ${path.relative(cwd, examplePath)} (written)`);
+    }
+    console.log(`  ${path.relative(cwd, instrDir)}/ (ensured)`);
+    // ---- Phase 6b: Scaffold the committed secret-free `.bridge/config` ----
+    // This manifest is committed and inherited by every worktree; it is the
+    // input to start-tickets worktree MCP provisioning. It is intentionally
+    // NOT gitignored (unlike the .mcp.json configs above). Credentials are
+    // resolved at runtime, never written here.
+    const bridgeConfigPath = path.join(cwd, ".bridge", "config");
+    let bridgeConfigExists = false;
+    try {
+        await stat(bridgeConfigPath);
+        bridgeConfigExists = true;
+    }
+    catch { }
+    if (bridgeConfigExists) {
+        console.log(`\n.bridge/config: skipped — already exists`);
+    }
+    else {
+        await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
+        await writeFile(bridgeConfigPath, buildBridgeConfigManifest(chooseScaffoldRepoName(cwd)), "utf-8");
+        console.log(`\n.bridge/config: written`);
+    }
+    console.log("  Credentials are resolved at runtime from BAPI_API_KEY or " +
+        "~/.config/bridge/credentials.json (no secrets are written to .bridge/config).");
+    // ---- Phase 7: Final summary ----
+    if (anyCreatedOrAdded) {
+        console.log("\nSet BAPI_REPO_NAME in your config files. Do NOT put BAPI_API_KEY in the " +
+            "generated MCP config — supply it via the BAPI_API_KEY environment variable, " +
+            "or store it under \"bapi:<repo_name>\" in ~/.config/bridge/credentials.json. " +
+            "Get your values from the Bridge API setup UI at https://bridgegpt-api.com");
+    }
+}