@bridge_gpt/mcp-server 0.2.34 → 0.2.37

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.
@@ -40,17 +47,65 @@ 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.
+    // 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}`],
+        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,
         },
     };
 }
+/** 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 +141,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,
@@ -143,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),
     });
 }
 /**
@@ -177,41 +315,152 @@ async function scaffoldFile(target, content, mkdirDir) {
     return existed ? "overwritten" : "written";
 }
 /**
- * Core initialization logic shared by --init and --upgrade.
- * Runs all scaffolding phases without calling process.exit().
+ * 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 async function runInit(cwd) {
-    // ---- Phase 1: IDE Detection ----
-    const ideDetection = {
-        claude: true,
-        vscode: false,
-        cursor: false,
-        windsurf: false,
+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;
+        }
     };
-    try {
-        await stat(path.join(cwd, ".vscode"));
-        ideDetection.vscode = true;
+    /** 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,
+            };
+        }
     }
-    catch { }
+    const manifestDeps = {
+        readFile: (p) => io.readFile(p, "utf-8"),
+        runCommand: undefined,
+    };
     try {
-        await stat(path.join(cwd, ".cursor"));
-        ideDetection.cursor = true;
+        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 { }
-    if (!ideDetection.cursor && process.env.CURSOR_TRACE_DIR)
-        ideDetection.cursor = true;
-    try {
-        await stat(path.join(cwd, ".windsurf"));
-        ideDetection.windsurf = true;
+    catch {
+        // A malformed or unreadable manifest is not fatal for identity resolution;
+        // it just means this source contributes no candidate.
     }
-    catch { }
-    if (!ideDetection.windsurf) {
-        try {
-            await stat(path.join(cwd, ".windsurfrules"));
-            ideDetection.windsurf = true;
+    for (const candidate of confirmed) {
+        if (await checkCredential(candidate)) {
+            return {
+                repoName: candidate,
+                baseUrl,
+                credentialAvailable: true,
+                baseUrlDefaulted: baseUrl === undefined,
+            };
         }
-        catch { }
     }
+    // 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, 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.
+    const ideDetection = await detectInitIdes({ cwd });
     const detectedIDEs = Object.entries(ideDetection)
         .filter(([, v]) => v)
         .map(([k]) => k);
@@ -224,78 +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 = [];
-    let anyCreatedOrAdded = false;
+    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 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" });
+        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" });
-                anyCreatedOrAdded = true;
+            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" });
-            anyCreatedOrAdded = true;
+        // 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")];
@@ -415,7 +801,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 +963,25 @@ 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");
     }
+    // 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,
+    };
 }