@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/init.js

@@ -11,17 +11,24 @@
  */
 import { writeFile, mkdir, readFile, stat } from "fs/promises";
 import path from "path";
+import os from "os";
 import { COMMANDS } from "./commands.generated.js";
 import { AGENTS } from "./agents.generated.js";
 import { DOCS } from "./docs.generated.js";
 import { VERSION } from "./version.generated.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
-import { validateRepoName } from "./bridge-config.js";
+import { validateRepoName, resolveRepoNameForProjectRoot } from "./bridge-config.js";
 import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
+import { resolveBapiCredentials } from "./credential-store.js";
+import { BRIDGE_ENTRY_KEY, describeLauncherReason, inspectLauncherConfigs, isPrerequisiteFailure, launcherTargetFor, } from "./launcher-config-inspection.js";
 // ---------------------------------------------------------------------------
 // CLI: --init scaffolds slash commands and MCP configs into the current project
 // ---------------------------------------------------------------------------
-export function buildBridgeApiEntry(cwd) {
+/** The production Bridge API endpoint a placeholder entry falls back to. */
+export const DEFAULT_BRIDGE_BASE_URL = "https://bridgegpt-api.com";
+/** The repo-name placeholder that marks an entry as never-configured. */
+export const PLACEHOLDER_REPO_NAME = "YOUR_REPO_NAME";
+export function buildBridgeApiEntry(cwd, metadata) {
     // 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.
@@ -47,12 +54,15 @@ export function buildBridgeApiEntry(cwd) {
     // an installer invocation. Bare invocation remains a permanent server-start
     // contract; see `refreshBridgeApiPackageSpec` for why EXISTING configs are never
     // migrated to this shape.
+    // BAPI-728: `repoName`/`baseUrl` are non-secret and always supplied by the
+    // caller when it has already resolved them. `BAPI_API_KEY` remains absent in
+    // EVERY branch — the server self-resolves it at runtime.
     return {
         command: "npx",
         args: ["-y", "--prefer-offline", `@bridge_gpt/mcp-server@${VERSION}`, "serve"],
         env: {
-            BAPI_BASE_URL: "https://bridgegpt-api.com",
-            BAPI_REPO_NAME: "YOUR_REPO_NAME",
+            BAPI_BASE_URL: metadata?.baseUrl ?? DEFAULT_BRIDGE_BASE_URL,
+            BAPI_REPO_NAME: metadata?.repoName ?? PLACEHOLDER_REPO_NAME,
             BAPI_DOCS_DIR: "docs/tmp",
             BAPI_PROJECT_ROOT: cwd,
         },
@@ -271,11 +281,11 @@ export async function mergeBridgeApiProfileToken(cwd, token) {
     }
     return lastProfile;
 }
-async function ensureGitignored(cwd, filePath) {
+async function ensureGitignored(cwd, filePath, io) {
     await ensureGitignoredShared(cwd, filePath, {
-        readFile: (p) => readFile(p, "utf-8"),
-        writeFile: (p, data) => writeFile(p, data, "utf-8"),
-        mkdir: (p, options) => mkdir(p, options),
+        readFile: (p) => (io?.readFile ?? readFile)(p, "utf-8"),
+        writeFile: (p, data) => (io?.writeFile ?? writeFile)(p, data, "utf-8"),
+        mkdir: (p, options) => (io?.mkdir ?? mkdir)(p, options),
     });
 }
 /**
@@ -304,11 +314,149 @@ async function scaffoldFile(target, content, mkdirDir) {
     await writeFile(target, content, "utf-8");
     return existed ? "overwritten" : "written";
 }
+/**
+ * A preflight failure: an existing config we must not write over. Thrown BEFORE
+ * any mutation so a run either reconciles everything or changes nothing.
+ */
+export class InitPreflightError extends Error {
+    failures;
+    constructor(failures) {
+        super(`Cannot reconcile MCP launcher configs:\n${failures
+            .map((f) => `  ${f.relPath}: ${f.reason}`)
+            .join("\n")}`);
+        this.name = "InitPreflightError";
+        this.failures = failures;
+    }
+}
+/**
+ * Resolve the non-secret identity a NEW `bridge-api` entry should carry.
+ *
+ * Precedence (plan Step 3.9): an explicit caller context wins; then an explicit
+ * `BAPI_REPO_NAME`; then the committed `.bridge/config` / git-derived identity.
+ * A cwd basename is only ever an unconfirmed candidate — it is promoted to the
+ * real identity ONLY when a `bapi:<repo>` credential actually resolves for it,
+ * so a directory name can never masquerade as a configured repository.
+ *
+ * The resolved API key is reduced immediately to `credentialAvailable`. It is
+ * never returned, logged, persisted, or written into a generated MCP entry.
+ */
+async function resolveNewEntryIdentity(cwd, options, io) {
+    const env = options.env ?? process.env;
+    const explicitBaseUrl = typeof env.BAPI_BASE_URL === "string" ? env.BAPI_BASE_URL.trim() : "";
+    const baseUrl = explicitBaseUrl.length > 0 ? explicitBaseUrl : undefined;
+    // A caller that already did verified resolution is authoritative.
+    if (options.creationContext?.repoName) {
+        return {
+            repoName: options.creationContext.repoName,
+            baseUrl: options.creationContext.baseUrl ?? baseUrl,
+            credentialAvailable: options.creationContext.credentialAvailable ?? true,
+            baseUrlDefaulted: !(options.creationContext.baseUrl ?? baseUrl),
+        };
+    }
+    const checkCredential = async (repoName) => {
+        try {
+            const result = options.resolveCredentials
+                ? await options.resolveCredentials(repoName)
+                : await resolveBapiCredentials(repoName, {
+                    env,
+                    homedir: options.homedir ?? os.homedir,
+                    platform: options.platform ?? process.platform,
+                    readFile: (p) => io.readFile(p, "utf-8"),
+                    stat: async (p) => {
+                        const s = (await io.stat(p));
+                        return { mode: typeof s?.mode === "number" ? s.mode : 0o600 };
+                    },
+                    // Silence the resolver's own stderr: init owns its reporting.
+                    stderr: () => { },
+                });
+            return result.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    /** Candidate identities in precedence order; the first that authenticates wins. */
+    const confirmed = [];
+    const explicitRepo = typeof env.BAPI_REPO_NAME === "string" ? env.BAPI_REPO_NAME.trim() : "";
+    if (explicitRepo.length > 0 && explicitRepo !== PLACEHOLDER_REPO_NAME) {
+        const validated = validateRepoName(explicitRepo);
+        if (validated.ok) {
+            // An explicit environment identity is a deliberate operator statement, so
+            // it is used even when no credential is present locally; readiness still
+            // reflects the missing credential.
+            return {
+                repoName: validated.value,
+                baseUrl,
+                credentialAvailable: await checkCredential(validated.value),
+                baseUrlDefaulted: baseUrl === undefined,
+            };
+        }
+    }
+    const manifestDeps = {
+        readFile: (p) => io.readFile(p, "utf-8"),
+        runCommand: undefined,
+    };
+    try {
+        const resolved = options.resolveRepoName
+            ? await options.resolveRepoName(cwd)
+            : await resolveRepoNameForProjectRoot(cwd, manifestDeps);
+        if (resolved.ok && resolved.value !== PLACEHOLDER_REPO_NAME) {
+            confirmed.push(resolved.value);
+        }
+    }
+    catch {
+        // A malformed or unreadable manifest is not fatal for identity resolution;
+        // it just means this source contributes no candidate.
+    }
+    for (const candidate of confirmed) {
+        if (await checkCredential(candidate)) {
+            return {
+                repoName: candidate,
+                baseUrl,
+                credentialAvailable: true,
+                baseUrlDefaulted: baseUrl === undefined,
+            };
+        }
+    }
+    // The cwd basename is the weakest signal: accepted ONLY when a credential
+    // exists for it. Otherwise it stays an unconfirmed candidate and the entry is
+    // written explicitly unconfigured rather than looking configured.
+    const basename = validateRepoName(path.basename(cwd));
+    if (basename.ok && (await checkCredential(basename.value))) {
+        return {
+            repoName: basename.value,
+            baseUrl,
+            credentialAvailable: true,
+            baseUrlDefaulted: baseUrl === undefined,
+        };
+    }
+    // Nothing resolvable. Fall back to a manifest/git identity WITHOUT claiming it
+    // is configured, so the entry at least names the right repo for a human to fix.
+    return {
+        repoName: confirmed[0],
+        baseUrl,
+        credentialAvailable: false,
+        baseUrlDefaulted: baseUrl === undefined,
+    };
+}
 /**
  * Core initialization logic shared by --init and --upgrade.
  * Runs all scaffolding phases without calling process.exit().
+ *
+ * BAPI-728: performs a complete read-only launcher preflight BEFORE its first
+ * write, and returns structured, secret-free results instead of `void`.
  */
-export async function runInit(cwd) {
+export async function runInit(cwd, options = {}) {
+    const io = {
+        readFile: options.io?.readFile ?? readFile,
+        writeFile: options.io?.writeFile ?? writeFile,
+        mkdir: options.io?.mkdir ?? mkdir,
+        stat: options.io?.stat ?? stat,
+    };
+    const targetVersion = options.targetVersion ?? VERSION;
+    const targetSpec = `@bridge_gpt/mcp-server@${targetVersion}`;
+    const say = options.stdout ?? ((m) => console.log(m));
+    const warn = options.stderr ?? ((m) => console.error(m));
     // ---- Phase 1: IDE Detection ----
     // BAPI-708: detection lives in `detectInitIdes` so the commit-safe asset
     // manifest resolves the SAME conditional targets this scaffolder writes.
@@ -325,82 +473,215 @@ export async function runInit(cwd) {
             windsurfSnippet + "\n");
     }
     // ---- Phase 3: Config file handling ----
+    // Order is preserved from the original implementation so existing console
+    // narration and its tests are unchanged; the per-path metadata (which root
+    // key each config uses) now comes from the shared inspection module.
     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 },
-    ];
+        { path: ".mcp.json", shouldCreate: true },
+        { path: ".vscode/mcp.json", shouldCreate: ideDetection.vscode },
+        { path: ".cursor/mcp.json", shouldCreate: ideDetection.cursor },
+    ].map((t) => ({
+        ...t,
+        topLevelKey: launcherTargetFor(t.path).topLevelKey,
+    }));
+    // ---- Phase 3a: read-only preflight, BEFORE the first write ----
+    // A run must either reconcile every config or change nothing. Discovering a
+    // malformed second config only after the first was rewritten would leave the
+    // project half-migrated with no record of what moved.
+    const inspections = await inspectLauncherConfigs({
+        cwd,
+        targetVersion,
+        readFile: (p) => io.readFile(p, "utf-8"),
+        isCreatable: (relPath) => configTargets.find((t) => t.path === relPath)?.shouldCreate ?? false,
+        targets: configTargets.map((t) => ({
+            relPath: t.path,
+            topLevelKey: t.topLevelKey,
+        })),
+    });
+    const blocking = inspections.filter(isPrerequisiteFailure);
+    if (blocking.length > 0) {
+        throw new InitPreflightError(blocking.map((f) => ({
+            relPath: f.relPath,
+            reason: describeLauncherReason(f.reason),
+        })));
+    }
+    const byPath = new Map(inspections.map((i) => [i.relPath, i]));
+    // Resolve the identity a NEW entry would carry — only when one is actually
+    // needed, so an ordinary repin run never touches the credential store.
+    const needsNewEntry = inspections.some((i) => i.action === "create" || i.action === "add");
+    const identity = needsNewEntry
+        ? await resolveNewEntryIdentity(cwd, options, io)
+        : { credentialAvailable: true, baseUrlDefaulted: false };
+    const entryReady = Boolean(identity.repoName) && identity.credentialAvailable;
+    const newEntryMetadata = {
+        repoName: entryReady ? identity.repoName : undefined,
+        baseUrl: identity.baseUrl,
+    };
     const configActions = [];
+    const structuredActions = [];
+    const readinessWarnings = [];
     for (const target of configTargets) {
+        const found = byPath.get(target.path);
         const fullPath = path.join(cwd, target.path);
-        let fileExists = false;
-        try {
-            await stat(fullPath);
-            fileExists = true;
-        }
-        catch { }
-        if (!target.shouldCreate && !fileExists) {
+        if (found.action === "skip-inactive") {
             configActions.push({ path: target.path, action: "skipped — IDE not detected" });
+            structuredActions.push({ relPath: target.path, kind: "skipped-inactive" });
             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 refresh the 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;
-                // BAPI-714: refresh ONLY the package-spec token. Assigning the whole
-                // template array here would migrate every legacy bare launcher to
-                // `serve` on the next --init/install/upgrade, which requirement C-3
-                // forbids. An args array we cannot recognize falls back to the template
-                // (that is the pre-existing behavior for a shape we cannot preserve).
-                topLevel["bridge-api"].args =
-                    refreshBridgeApiPackageSpec(topLevel["bridge-api"].args, currentBridgePackageSpec()) ??
-                        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" });
+        if (found.action === "skip-worktree-shim") {
+            // BAPI-714 / worktree provisioning: this registration points at a sibling
+            // checkout's build. Gate BEFORE touching `command`, `args`, or `env` —
+            // rewriting any of them would break the worktree's server.
+            configActions.push({
+                path: target.path,
+                action: "skipped — worktree mcp-invoke shim preserved",
+            });
+            structuredActions.push({
+                relPath: target.path,
+                kind: "skipped-worktree-shim",
+            });
+            continue;
+        }
+        if (found.action === "ahead") {
+            // Never walk a project backwards. `upgrade` blocks on this before it
+            // ever calls init; a direct `--init` from an older CLI reaches here, and
+            // must leave the newer pin exactly as it found it.
+            configActions.push({
+                path: target.path,
+                action: `skipped — pinned ahead at ${found.currentVersion}`,
+            });
+            structuredActions.push({
+                relPath: target.path,
+                kind: "skipped-ahead",
+                fromVersion: found.currentVersion ?? undefined,
+                fromSpec: found.spec ?? undefined,
+            });
+            continue;
+        }
+        if (found.action === "create") {
+            await io.mkdir(path.dirname(fullPath), { recursive: true });
+            const content = {
+                [target.topLevelKey]: {
+                    [BRIDGE_ENTRY_KEY]: buildBridgeApiEntry(cwd, newEntryMetadata),
+                },
+            };
+            await io.writeFile(fullPath, JSON.stringify(content, null, 2) + "\n", "utf-8");
+            await ensureGitignored(cwd, target.path, io);
+            configActions.push({ path: target.path, action: "created" });
+            structuredActions.push({
+                relPath: target.path,
+                kind: "created",
+                toVersion: targetVersion,
+                unconfigured: !entryReady,
+            });
+            if (!entryReady) {
+                readinessWarnings.push({
+                    relPath: target.path,
+                    kind: "unconfigured-entry-created",
+                    baseUrlDefaulted: identity.baseUrlDefaulted,
+                });
             }
-            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" });
+            continue;
+        }
+        // Every remaining action reads and rewrites an existing, already-validated
+        // file. The preflight above proved it parses and carries a shape we can
+        // safely reconcile, so no defensive re-parse branch is needed here.
+        const raw = await io.readFile(fullPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (found.action === "add") {
+            if (!parsed[target.topLevelKey])
+                parsed[target.topLevelKey] = {};
+            parsed[target.topLevelKey][BRIDGE_ENTRY_KEY] = buildBridgeApiEntry(cwd, newEntryMetadata);
+            await io.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+            configActions.push({ path: target.path, action: "added entry" });
+            structuredActions.push({
+                relPath: target.path,
+                kind: "added",
+                toVersion: targetVersion,
+                unconfigured: !entryReady,
+            });
+            if (!entryReady) {
+                readinessWarnings.push({
+                    relPath: target.path,
+                    kind: "unconfigured-entry-created",
+                    baseUrlDefaulted: identity.baseUrlDefaulted,
+                });
             }
+            continue;
         }
-        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" });
+        // Existing standard launcher: change ONLY the package-spec token and
+        // BAPI_PROJECT_ROOT. `command` is preserved (BAPI-728 — the old code
+        // rewrote it to "npx" unconditionally, silently replacing a custom
+        // launcher), and `refreshBridgeApiPackageSpec` preserves the bare-versus-
+        // `serve` composition plus every surrounding argument (BAPI-714 C-3).
+        const entry = parsed[target.topLevelKey][BRIDGE_ENTRY_KEY];
+        const refreshed = refreshBridgeApiPackageSpec(entry.args, targetSpec);
+        if (refreshed === null) {
+            // Unreachable: preflight classifies an unrecognizable args array as
+            // `unsupported` and throws above. Fail closed rather than fall back to
+            // the template, which is what used to clobber custom launchers.
+            throw new InitPreflightError([
+                { relPath: target.path, reason: describeLauncherReason("no-package-token") },
+            ]);
+        }
+        entry.args = refreshed;
+        if (!entry.env)
+            entry.env = {};
+        entry.env.BAPI_PROJECT_ROOT = cwd;
+        await io.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+        const kind = found.action === "already-current"
+            ? "already-current"
+            : found.action === "normalize-unpinned"
+                ? "normalized"
+                : "repinned";
+        configActions.push({ path: target.path, action: "updated entry and pinned version" });
+        structuredActions.push({
+            relPath: target.path,
+            kind,
+            fromVersion: found.currentVersion ?? undefined,
+            fromSpec: found.spec ?? undefined,
+            toVersion: targetVersion,
+        });
+        // An existing entry that still says YOUR_REPO_NAME loads without error and
+        // authenticates as nobody. Its env is left exactly as-is — but the run is
+        // no longer allowed to report itself as a working configuration.
+        if (entry.env?.BAPI_REPO_NAME === PLACEHOLDER_REPO_NAME) {
+            readinessWarnings.push({
+                relPath: target.path,
+                kind: "unconfigured-entry-existing",
+            });
         }
     }
-    console.log("\nMCP config files:");
-    for (const entry of configActions) {
-        console.log(`  ${entry.path}: ${entry.action}`);
+    if (!options.suppressConfigSummary) {
+        say("\nMCP config files:");
+        for (const entry of configActions) {
+            say(`  ${entry.path}: ${entry.action}`);
+        }
+    }
+    // Loud, secret-free readiness reporting. A config that looks configured but
+    // silently 401s is the failure mode BAPI-728 exists to end, so this warning
+    // names every affected path and what to do about it.
+    if (readinessWarnings.length > 0) {
+        const created = readinessWarnings.filter((w) => w.kind === "unconfigured-entry-created");
+        const existing = readinessWarnings.filter((w) => w.kind === "unconfigured-entry-existing");
+        warn("\n⚠ Bridge API MCP configuration is NOT ready to authenticate.");
+        if (created.length > 0) {
+            warn(`  Wrote an UNCONFIGURED bridge-api entry (BAPI_REPO_NAME=${PLACEHOLDER_REPO_NAME}) to: ${created
+                .map((w) => w.relPath)
+                .join(", ")}`);
+            warn(identity.repoName
+                ? `  Reason: no API key could be resolved for repository "${identity.repoName}".`
+                : "  Reason: no repository identity could be resolved from the environment, .bridge/config, or the credential store.");
+            if (identity.baseUrlDefaulted) {
+                warn(`  BAPI_BASE_URL was defaulted to the production endpoint ${DEFAULT_BRIDGE_BASE_URL}.`);
+            }
+        }
+        if (existing.length > 0) {
+            warn(`  Existing bridge-api entry still uses the ${PLACEHOLDER_REPO_NAME} placeholder in: ${existing
+                .map((w) => w.relPath)
+                .join(", ")}`);
+        }
+        warn("  Fix with: npx -y @bridge_gpt/mcp-server install   (or set BAPI_REPO_NAME and store a key with the install flow)");
     }
     // ---- Phase 4: Scaffold slash command directories ----
     const commandDirs = [path.join(cwd, ".claude", "commands")];
@@ -694,4 +975,13 @@ body explicitly says to serialize structured output.
         await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
         await writeFile(bridgeConfigPath, buildBridgeConfigManifest(chooseScaffoldRepoName(cwd)), "utf-8");
     }
+    // BAPI-728: authoritative, secret-free outcome. `ok` is false whenever any
+    // entry authenticates as nobody, so no caller can report full success over a
+    // configuration that will 401 on its first request.
+    return {
+        ok: readinessWarnings.length === 0,
+        configActions: structuredActions,
+        readinessWarnings,
+        targetVersion,
+    };
 }