@bridge_gpt/mcp-server 0.2.34 → 0.2.36

package/build/init.js

@@ -40,9 +40,16 @@ export function buildBridgeApiEntry(cwd) {
     // `--offline`, it falls back automatically). It cannot resurrect a stale build
     // — the BAPI-429 hazard above was specific to UNPINNED specs; here the exact
     // `@${VERSION}` is immutable, so a cache hit is always the right build.
+    // BAPI-714 (Group C): NEWLY generated registrations name the server subcommand
+    // explicitly. `serve` is a no-op relative to bare invocation — it consumes its
+    // own token and falls through to the same startup path — but it makes a
+    // generated config self-describing, so a reader can tell a server launcher from
+    // an installer invocation. Bare invocation remains a permanent server-start
+    // contract; see `refreshBridgeApiPackageSpec` for why EXISTING configs are never
+    // migrated to this shape.
     return {
         command: "npx",
-        args: ["-y", "--prefer-offline", `@bridge_gpt/mcp-server@${VERSION}`],
+        args: ["-y", "--prefer-offline", `@bridge_gpt/mcp-server@${VERSION}`, "serve"],
         env: {
             BAPI_BASE_URL: "https://bridgegpt-api.com",
             BAPI_REPO_NAME: "YOUR_REPO_NAME",
@@ -51,6 +58,44 @@ export function buildBridgeApiEntry(cwd) {
         },
     };
 }
+/** The package-name prefix every Bridge launcher spec starts with. */
+const BRIDGE_PACKAGE_PREFIX = "@bridge_gpt/mcp-server";
+/**
+ * Refresh ONLY the package-spec token of an existing launcher args array
+ * (BAPI-714, Group C).
+ *
+ * Adding `serve` to {@link buildBridgeApiEntry} changes the bytes of every FRESH
+ * registration, and the previous update path assigned the whole template array
+ * over an existing entry — which would have silently migrated every legacy bare
+ * launcher on the next `--init`, `install`, or `upgrade`. That is explicitly out
+ * of scope: legacy bare launchers can never be declared fully migrated, so bare
+ * invocation must keep meaning "server" permanently and no config-rewrite pass may
+ * add `serve`.
+ *
+ * So this helper replaces the single element beginning with `@bridge_gpt/mcp-server`
+ * with `spec` and preserves EVERY other token and its position — including whether
+ * `serve` is present. An args array with no package-spec token is returned
+ * unchanged (a custom launcher shape this helper must not invent tokens for).
+ *
+ * Pure: it returns a new array and never mutates its input.
+ */
+export function refreshBridgeApiPackageSpec(args, spec) {
+    if (!Array.isArray(args))
+        return null;
+    const tokens = args.filter((a) => typeof a === "string");
+    if (tokens.length !== args.length)
+        return null;
+    const index = tokens.findIndex((token) => token.startsWith(BRIDGE_PACKAGE_PREFIX));
+    if (index === -1)
+        return null;
+    const next = [...tokens];
+    next[index] = spec;
+    return next;
+}
+/** The exact package spec a launcher generated by THIS build should carry. */
+export function currentBridgePackageSpec() {
+    return `${BRIDGE_PACKAGE_PREFIX}@${VERSION}`;
+}
 /**
  * Choose the `repo_name` written into a scaffolded `.bridge/config`. Uses the
  * cwd basename when it passes manifest repo-name validation; otherwise falls
@@ -86,6 +131,89 @@ export function buildBridgeConfigManifest(repoName) {
         "",
     ].join("\n");
 }
+/**
+ * Detect the editors present in `cwd`. Extracted from `runInit`'s Phase 1 so the
+ * asset manifest and the scaffolder cannot disagree about which conditional
+ * targets (`.cursor/commands/`, `.github/agents/`) this run actually writes.
+ */
+export async function detectInitIdes(options) {
+    const { cwd } = options;
+    const env = options.env ?? process.env;
+    const probe = options.stat ?? stat;
+    const exists = async (p) => {
+        try {
+            await probe(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const detection = {
+        claude: true,
+        vscode: await exists(path.join(cwd, ".vscode")),
+        cursor: await exists(path.join(cwd, ".cursor")),
+        windsurf: await exists(path.join(cwd, ".windsurf")),
+    };
+    if (!detection.cursor && env.CURSOR_TRACE_DIR)
+        detection.cursor = true;
+    if (!detection.windsurf)
+        detection.windsurf = await exists(path.join(cwd, ".windsurfrules"));
+    return detection;
+}
+/**
+ * Resolve the pipelines directory exactly the way `runInit`'s Phase 6 does, so a
+ * `BAPI_PIPELINES_DIR` override moves the scaffold AND the manifest together.
+ */
+export function resolveInitPipelinesDir(cwd, env = process.env) {
+    return path.resolve(cwd, env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
+}
+/**
+ * Render an absolute scaffold target as the path we print. Targets inside the
+ * project stay project-relative (in POSIX form, so the notice reads the same on
+ * every platform); anything resolved outside it keeps its absolute path rather
+ * than growing a `../../` prefix nobody can act on.
+ */
+function displayScaffoldPath(cwd, target, isDirectory) {
+    const relative = path.relative(cwd, target);
+    const inProject = relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+    const base = inProject ? relative.split(path.sep).join("/") : target;
+    return isDirectory ? `${base.replace(/\/+$/, "")}/` : base;
+}
+/**
+ * The single authority on which files a `runInit` invocation scaffolds that are
+ * SAFE to recommend for commit (BAPI-708, Part C).
+ *
+ * Derived from the run's own resolved targets — the detected IDEs and the
+ * resolved `BAPI_PIPELINES_DIR` — rather than a hand-copied literal, so the list
+ * cannot drift from what was actually written. See {@link InitScaffoldAssets} for
+ * the hard exclusion contract; nothing gitignored or credential-bearing is
+ * constructible from this function's inputs.
+ */
+export async function resolveInitScaffoldAssets(options) {
+    const { cwd } = options;
+    const env = options.env ?? process.env;
+    const ide = await detectInitIdes({ ...options, env });
+    const pipelinesDir = resolveInitPipelinesDir(cwd, env);
+    const instructionsDir = path.join(path.dirname(pipelinesDir), "instructions");
+    const commitSafePaths = [
+        displayScaffoldPath(cwd, path.join(cwd, ".bridge", "config"), false),
+        displayScaffoldPath(cwd, path.join(pipelinesDir, "README.md"), false),
+        displayScaffoldPath(cwd, path.join(pipelinesDir, "example-pipeline.json"), false),
+        displayScaffoldPath(cwd, instructionsDir, true),
+        displayScaffoldPath(cwd, path.join(cwd, ".claude", "commands"), true),
+        ...(ide.cursor ? [displayScaffoldPath(cwd, path.join(cwd, ".cursor", "commands"), true)] : []),
+        displayScaffoldPath(cwd, path.join(cwd, ".claude", "agents"), true),
+        ...(ide.vscode ? [displayScaffoldPath(cwd, path.join(cwd, ".github", "agents"), true)] : []),
+        // Sourced from the bundled DOCS map, so a new scaffolded doc is covered
+        // automatically rather than needing a second edit here.
+        ...Object.keys(DOCS)
+            .slice()
+            .sort()
+            .map((target) => displayScaffoldPath(cwd, path.join(cwd, target), false)),
+    ];
+    return { ide, pipelinesDir, instructionsDir, commitSafePaths };
+}
 /**
  * Merge a group token (e.g. "sfcc") into the BRIDGE_MCP_PROFILE env value of the
  * `bridge-api` entry in each present MCP config file (.mcp.json, .vscode/mcp.json,
@@ -182,36 +310,9 @@ async function scaffoldFile(target, content, mkdirDir) {
  */
 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 { }
-    }
+    // BAPI-708: detection lives in `detectInitIdes` so the commit-safe asset
+    // manifest resolves the SAME conditional targets this scaffolder writes.
+    const ideDetection = await detectInitIdes({ cwd });
     const detectedIDEs = Object.entries(ideDetection)
         .filter(([, v]) => v)
         .map(([k]) => k);
@@ -230,7 +331,6 @@ export async function runInit(cwd) {
         { 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;
@@ -257,7 +357,7 @@ export async function runInit(cwd) {
             }
             const topLevel = parsed[target.topLevelKey];
             if (topLevel && topLevel["bridge-api"]) {
-                // Entry exists — update BAPI_PROJECT_ROOT and launcher args to preserve exact version pin.
+                // 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);
@@ -266,7 +366,14 @@ export async function runInit(cwd) {
                     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;
+                // 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;
@@ -280,7 +387,6 @@ export async function runInit(cwd) {
                 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 {
@@ -290,7 +396,6 @@ export async function runInit(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:");
@@ -415,7 +520,9 @@ export async function runInit(cwd) {
     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");
+    // BAPI-708: shared with `resolveInitScaffoldAssets`, so a `BAPI_PIPELINES_DIR`
+    // override moves the scaffold and the commit-safe manifest in lockstep.
+    const pipelinesDir = resolveInitPipelinesDir(cwd);
     const instrDir = path.join(path.dirname(pipelinesDir), "instructions");
     await mkdir(pipelinesDir, { recursive: true });
     await mkdir(instrDir, { recursive: true });
@@ -575,21 +682,16 @@ body explicitly says to serialize structured output.
         bridgeConfigExists = true;
     }
     catch { }
-    if (bridgeConfigExists) {
-        console.log(`\n.bridge/config: skipped — already exists`);
-    }
-    else {
+    // BAPI-708 (Part B): the file is still written with UNCHANGED content — only
+    // its narration goes. The written/skipped line, the runtime-credential
+    // paragraph, and the old `Set BAPI_REPO_NAME…` summary were redundant on all
+    // three callers (`--init`, `upgrade`, and `install-bridge`): each scaffolds the
+    // same secret-free manifest, and install-bridge separately reports both where
+    // the credential landed and which generated assets are safe to commit. Removed
+    // outright rather than behind an output-mode flag — parameterizing would change
+    // the injected `deps.runInit` seam signature for no user-visible gain.
+    if (!bridgeConfigExists) {
         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");
     }
 }