@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/install-reexec.js

@@ -0,0 +1,233 @@
+/**
+ * Installer-owned self-re-exec from `@latest` (BAPI-714, Group B).
+ *
+ * WHY THIS EXISTS. The documented setup command dropped `@latest`
+ * (`npx -y @bridge_gpt/mcp-server install`), and an UNPINNED npx spec silently
+ * reuses a stale cached copy — the verified bug recorded in `init.ts:32-38`,
+ * where 0.2.6 persisted across an upgrade. So the install path must do for itself
+ * what `upgrade` already does: look up the latest published version and, when the
+ * local copy is strictly older, hand off to `@latest`.
+ *
+ * THREE PROPERTIES ARE LOAD-BEARING.
+ *
+ *  1. FAIL OPEN, ALWAYS. `upgrade` can afford to fail; `install` is someone's
+ *     first contact with Bridge. An unreachable, slow, non-2xx, or malformed
+ *     registry means "run the local copy" — never an error, prompt, or stall.
+ *  2. `stdio: "inherit"` IS NOT STYLISTIC. `promptSecret`/`promptLine`/
+ *     `promptMultiSelect` are wired only when `process.stdin.isTTY`
+ *     (`install-bridge.ts:1195`, `:1224-1226`); non-inherited stdio silently
+ *     strips all three and turns an interactive install into a non-interactive
+ *     one with no error.
+ *  3. THE SENTINEL IS STRIPPED BEFORE *ANY* ARGV INTERPRETATION. Two verified
+ *     reasons: `parseInstallBridgeArgs` rejects unrecognized arguments, so a
+ *     leftover `--internal-reexec` is an argument error on the child run; and
+ *     `install-bridge.ts:1690` computes `isBareInvocation = argv.length === 0`,
+ *     so a leftover sentinel makes the child take a DIFFERENT onboarding branch
+ *     silently. Its presence is also the terminating condition, so exactly one
+ *     re-exec is possible per invocation.
+ *
+ * SECRET DISCIPLINE. Child argv is process-visible (`ps`), so `--api-key <value>`
+ * and a VALUED `--invite <token>` are lifted out of argv and forwarded only
+ * through the child ENVIRONMENT as `BAPI_API_KEY` / `BAPI_INVITE`. A value-less
+ * `--invite` marker is deliberately RETAINED in child argv: it is what selects
+ * bootstrap-invite mode, and dropping it would leave `argv.length === 0` and send
+ * the child down the bare-onboarding branch instead. The failure diagnostic is a
+ * fixed string — it interpolates no argv, no environment value, and no exception
+ * text.
+ */
+import { spawn } from "child_process";
+import { VERSION } from "./version.generated.js";
+import { isNewerVersion } from "./update-check.js";
+import { fetchLatestVersion } from "./cli-release.js";
+import { runInstallBridgeCli } from "./install-bridge.js";
+/** The sentinel that marks an already-re-exec'd child. Matches `upgrade-cli.ts`. */
+export const INSTALL_REEXEC_SENTINEL = "--internal-reexec";
+/**
+ * The ONLY text emitted when the hand-off itself fails. Fixed by construction —
+ * no argv, no environment value, no raw exception message, no credential.
+ */
+export const INSTALL_REEXEC_FAILURE_MESSAGE = "Bridge API install failed: could not run the latest installer.";
+/**
+ * Remove EVERY `--internal-reexec` occurrence and report whether any was present.
+ *
+ * Called before nested-command detection, before the re-exec decision, and before
+ * anything is handed to `runInstallBridgeCli` — the sentinel must never reach the
+ * installer's strict argument parser or its bare-invocation computation.
+ */
+export function stripInternalReexecSentinels(argv) {
+    const args = [];
+    let sentinelPresent = false;
+    for (const arg of argv) {
+        if (arg === INSTALL_REEXEC_SENTINEL) {
+            sentinelPresent = true;
+            continue;
+        }
+        args.push(arg);
+    }
+    return { args, sentinelPresent };
+}
+/**
+ * Lift secret-valued flags out of argv and into a child-environment overlay.
+ *
+ * Mirrors `parseInstallBridgeArgs` token-for-token so the two never disagree:
+ *
+ *  - `--api-key=<value>` / `--api-key <value>` → `BAPI_API_KEY`, flag AND value
+ *    removed. The installer resolves the key from the environment, and
+ *    `hasEnvApiKey` keeps the bare-interactive chooser suppressed exactly as the
+ *    flag did.
+ *  - `--invite=<token>` / `--invite <token>` → `BAPI_INVITE`, with a VALUE-LESS
+ *    `--invite` left in argv. That marker still selects bootstrap-invite mode and
+ *    the installer falls back to `BAPI_INVITE` for the token.
+ *  - MALFORMED forms (`--api-key` at end of argv, `--api-key=`, `--invite=`) are
+ *    left untouched so the installer's own parser produces the established
+ *    argument error rather than this layer inventing a new one.
+ *
+ * Every other argument is preserved byte-for-byte in its original order. This is
+ * deliberately NOT `sanitizePrewarmEnv()` from `install-bridge.ts`: that helper
+ * STRIPS installer credentials for a `--version` probe and has the opposite
+ * contract from this hand-off.
+ */
+export function prepareInstallReexecArguments(argv) {
+    const forwardedArgs = [];
+    const secretEnv = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--api-key" || arg.startsWith("--api-key=")) {
+            let value;
+            let consumedNext = false;
+            if (arg.startsWith("--api-key=")) {
+                value = arg.slice("--api-key=".length);
+            }
+            else if (i + 1 < argv.length) {
+                value = argv[i + 1];
+                consumedNext = true;
+            }
+            // Blank / absent value == malformed: hand it to the installer's parser.
+            if (value === undefined || value.length === 0) {
+                forwardedArgs.push(arg);
+                continue;
+            }
+            secretEnv.BAPI_API_KEY = value;
+            if (consumedNext)
+                i += 1;
+            continue;
+        }
+        if (arg === "--invite" || arg.startsWith("--invite=")) {
+            if (arg.startsWith("--invite=")) {
+                const value = arg.slice("--invite=".length);
+                if (value.length === 0) {
+                    // Malformed: leave it for the installer's parser.
+                    forwardedArgs.push(arg);
+                    continue;
+                }
+                secretEnv.BAPI_INVITE = value;
+                forwardedArgs.push("--invite");
+                continue;
+            }
+            // Bare `--invite`: only a following NON-flag token is its value, exactly as
+            // `parseInstallBridgeArgs` reads it.
+            const next = argv[i + 1];
+            forwardedArgs.push("--invite");
+            if (typeof next === "string" && !next.startsWith("-") && next.length > 0) {
+                secretEnv.BAPI_INVITE = next;
+                i += 1;
+            }
+            continue;
+        }
+        forwardedArgs.push(arg);
+    }
+    return { forwardedArgs, secretEnv };
+}
+/**
+ * The public `install` / legacy `install-bridge` entry point.
+ *
+ * Fail-open ordering, in the only order that is safe:
+ *
+ *  1. Strip sentinels (before anything reads argv).
+ *  2. If a sentinel was present, or the first remaining token is `conductor`,
+ *     delegate straight to the local installer — no registry lookup, no spawn.
+ *     The nested `install conductor` surface is intercepted inside
+ *     `runInstallBridgeCli`, so it must reach it as `["conductor", ...]` rather
+ *     than being collapsed into bare onboarding.
+ *  3. Otherwise look up the latest version, defaulting the comparison target to
+ *     the local `VERSION` so an unusable answer changes nothing.
+ *  4. Re-exec only for a STRICTLY newer published version.
+ */
+export async function runInstallBridgeWithLatestCli(argv, deps = {}) {
+    const resolveLatest = deps.fetchLatestVersion ?? (() => fetchLatestVersion());
+    const runLocal = deps.runInstallBridgeCli ?? runInstallBridgeCli;
+    const doSpawn = deps.spawn ?? spawn;
+    const env = deps.env ?? process.env;
+    const platform = deps.platform ?? process.platform;
+    const cwd = deps.cwd ?? process.cwd();
+    const errorLog = deps.errorLog ?? ((message) => console.error(message));
+    const localVersion = deps.localVersion ?? VERSION;
+    const { args: cleanedArgs, sentinelPresent } = stripInternalReexecSentinels(argv);
+    // Terminating condition, and the nested-conductor bypass. Both skip the
+    // registry entirely.
+    if (sentinelPresent || cleanedArgs[0] === "conductor") {
+        return runLocal(cleanedArgs);
+    }
+    // Default the comparison target to the local version: an unusable registry
+    // answer must be indistinguishable from "already current".
+    let latestVersion = localVersion;
+    let fetched = null;
+    try {
+        fetched = await resolveLatest();
+    }
+    catch {
+        fetched = null;
+    }
+    if (fetched)
+        latestVersion = fetched;
+    if (!isNewerVersion(localVersion, latestVersion)) {
+        return runLocal(cleanedArgs);
+    }
+    const { forwardedArgs, secretEnv } = prepareInstallReexecArguments(cleanedArgs);
+    const npxCmd = platform === "win32" ? "npx.cmd" : "npx";
+    const childArgs = [
+        "-y",
+        "@bridge_gpt/mcp-server@latest",
+        "install",
+        INSTALL_REEXEC_SENTINEL,
+        ...forwardedArgs,
+    ];
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(code);
+        };
+        const fail = () => {
+            errorLog(INSTALL_REEXEC_FAILURE_MESSAGE);
+            settle(1);
+        };
+        let child;
+        try {
+            child = doSpawn(npxCmd, childArgs, {
+                shell: false,
+                stdio: "inherit",
+                cwd,
+                // Explicit CLI values win over an inherited value of the same key.
+                env: { ...env, ...secretEnv },
+            });
+        }
+        catch {
+            fail();
+            return;
+        }
+        child.on("close", (code) => {
+            // A signal termination or an absent numeric code is an abnormal exit.
+            if (typeof code === "number") {
+                settle(code);
+                return;
+            }
+            fail();
+        });
+        child.on("error", () => {
+            fail();
+        });
+    });
+}

package/build/launcher-config-inspection.js

@@ -0,0 +1,351 @@
+/**
+ * Shared, read-only inspection of every project-local MCP launcher config
+ * (BAPI-728).
+ *
+ * Before this module, three callers each carried their own idea of what a
+ * launcher config looks like:
+ *
+ *  - `doctor.ts` parsed the pin correctly and reported `STALE-PINNED`.
+ *  - `upgrade-cli.ts` kept a duplicate path list and never read the pin at all,
+ *    deciding from the running process `VERSION` instead — which is why a
+ *    twenty-release repin reported itself as `0.2.36 -> 0.2.36`.
+ *  - `init.ts` repaired the pin as an undocumented side effect of writing.
+ *
+ * This module is the single authority for *what a config currently says*. It is
+ * strictly read-only: it never writes, never spawns, never touches the network,
+ * and never resolves credentials. Callers layer their own concerns on top —
+ * `doctor` adds a read-only npx cache probe, `init` performs the mutation,
+ * `upgrade` renders the transition report and owns exit status.
+ *
+ * Secret safety: an inspection result carries only sanitized launcher facts —
+ * relative path, launcher shape, the package spec token, and versions. It never
+ * carries config bodies, `env` maps, credential values, or raw error text.
+ */
+import path from "path";
+/** The npm package every Bridge launcher spec names. */
+export const BRIDGE_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+/**
+ * The subcommand token that marks a worktree shim registration. A shim points at
+ * a sibling worktree's server rather than a published package, so no pin applies
+ * and no rewrite is ever safe (BAPI-714 / worktree provisioning).
+ */
+const WORKTREE_SHIM_TOKEN = "mcp-invoke";
+/** The MCP server entry key every Bridge registration uses. */
+export const BRIDGE_ENTRY_KEY = "bridge-api";
+/**
+ * Every project-local MCP config Bridge registers into. Exported so `doctor`,
+ * `init`, and `upgrade` can no longer drift apart on which paths exist or which
+ * root key each one uses. Callers that need a different *order* should map over
+ * their own list and use {@link launcherTargetFor} for the metadata.
+ */
+export const LAUNCHER_CONFIG_TARGETS = [
+    { relPath: ".mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" },
+    { relPath: ".vscode/mcp.json", topLevelKey: "servers" },
+];
+/** Look up a target's metadata by relative path, or `undefined` if unknown. */
+export function launcherTargetFor(relPath) {
+    return LAUNCHER_CONFIG_TARGETS.find((t) => t.relPath === relPath);
+}
+// ---------------------------------------------------------------------------
+// Exact-version parsing and comparison
+// ---------------------------------------------------------------------------
+/**
+ * Strict exact-release form: `MAJOR.MINOR.PATCH`, nothing else. Deliberately
+ * narrower than semver at large — a prerelease, build metadata, a `v` prefix, a
+ * two-part `0.2`, a range (`^0.2.0`), or a dist-tag (`beta`) is NOT an exact
+ * version and must never be treated as one. Everything the package publishes
+ * takes this form, so anything else in a config is something a human wrote and
+ * an automated repin has no business silently rewriting.
+ */
+const EXACT_VERSION_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+/** Parse an exact `MAJOR.MINOR.PATCH` string, or return null for any other form. */
+export function parseExactVersion(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const match = EXACT_VERSION_RE.exec(raw.trim());
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `value` is an exact `MAJOR.MINOR.PATCH` release string. */
+export function isExactVersion(raw) {
+    return parseExactVersion(raw) !== null;
+}
+/**
+ * Compare two exact versions: negative when `a < b`, zero when equal, positive
+ * when `a > b`. Returns null when either side is not an exact version, so a
+ * caller can never accidentally order a range against a release.
+ */
+export function compareExactVersions(a, b) {
+    const left = parseExactVersion(a);
+    const right = parseExactVersion(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    }
+    return 0;
+}
+/**
+ * Extract the Bridge package token from a launcher args array.
+ *
+ * The package name is itself scoped (`@scope/name`), so the version delimiter is
+ * the FIRST `@` *after* the package name — not the last `@` in the string.
+ * `@bridge_gpt/mcp-server` is bare; `@bridge_gpt/mcp-server@0.2.16` pins
+ * `0.2.16`. A non-Bridge package token is never matched.
+ */
+export function parseLauncherPin(args) {
+    if (!Array.isArray(args))
+        return null;
+    for (const arg of args) {
+        if (typeof arg !== "string")
+            continue;
+        if (arg === BRIDGE_PACKAGE_NAME) {
+            return { spec: arg, specifier: null, exactVersion: null };
+        }
+        if (arg.startsWith(`${BRIDGE_PACKAGE_NAME}@`)) {
+            const specifier = arg.slice(BRIDGE_PACKAGE_NAME.length + 1).trim();
+            if (specifier.length === 0) {
+                return { spec: arg, specifier: null, exactVersion: null };
+            }
+            return {
+                spec: arg,
+                specifier,
+                exactVersion: isExactVersion(specifier) ? specifier : null,
+            };
+        }
+    }
+    return null;
+}
+/** True when the args array carries the worktree-shim subcommand token. */
+export function isWorktreeShimArgs(args) {
+    return Array.isArray(args) && args.some((a) => a === WORKTREE_SHIM_TOKEN);
+}
+/** Human-readable text for each reason code (no dynamic content). */
+const REASON_TEXT = {
+    "file-unreadable": "the file exists but could not be read",
+    "invalid-json": "the file is not valid JSON",
+    "root-not-object": "the JSON root is not an object",
+    "servers-not-object": "the servers section is not an object",
+    "entry-not-object": "the bridge-api entry is not an object",
+    "no-package-token": "the bridge-api launcher has no recognizable @bridge_gpt/mcp-server token",
+    "version-range": "the launcher pin is a version range, which an automated repin must not rewrite",
+    "non-release-specifier": "the launcher pin is a dist-tag or channel, not an exact release",
+    "malformed-version": "the launcher pin is not a valid MAJOR.MINOR.PATCH release",
+    "pinned-ahead-of-target": "the launcher pin is newer than the target version and must not be downgraded",
+};
+/** Render a reason code as sanitized prose. */
+export function describeLauncherReason(reason) {
+    return REASON_TEXT[reason];
+}
+/** True for the two actions that must abort a mutation run before any write. */
+export function isPrerequisiteFailure(inspection) {
+    return inspection.action === "invalid" || inspection.action === "unsupported";
+}
+/**
+ * True when this target carries a standard launcher whose pin participates in
+ * the "is everything already current?" question. Worktree shims, inactive
+ * targets, and absent files deliberately do not.
+ */
+export function isApplicableStandardLauncher(inspection) {
+    return (inspection.shape === "standard" &&
+        (inspection.action === "repin" ||
+            inspection.action === "already-current" ||
+            inspection.action === "normalize-unpinned"));
+}
+/**
+ * Inspect every project-local MCP config's `bridge-api` launcher, read-only.
+ *
+ * Every target always produces exactly one result, so a caller can render one
+ * line per config without re-deriving which paths it looked at. Only an `ENOENT`
+ * read is treated as absence — a permission error on an existing file is an
+ * `invalid` prerequisite failure, never a "missing file we can freshly create".
+ */
+export async function inspectLauncherConfigs(options) {
+    const targets = options.targets ?? LAUNCHER_CONFIG_TARGETS;
+    const results = [];
+    for (const target of targets) {
+        results.push(await inspectOne(target, options));
+    }
+    return results;
+}
+async function inspectOne(target, options) {
+    const { targetVersion } = options;
+    const base = {
+        relPath: target.relPath,
+        topLevelKey: target.topLevelKey,
+        targetVersion,
+        spec: null,
+        currentVersion: null,
+    };
+    let raw;
+    try {
+        raw = await options.readFile(path.join(options.cwd, target.relPath));
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            const creatable = options.isCreatable?.(target.relPath) ?? false;
+            return {
+                ...base,
+                filePresent: false,
+                bridgeEntryPresent: false,
+                shape: "none",
+                action: creatable ? "create" : "skip-inactive",
+            };
+        }
+        // Present-but-unreadable is NOT absence. Creating a fresh file over a config
+        // we merely failed to read would silently destroy a working registration.
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "invalid",
+            reason: "file-unreadable",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "invalid",
+            reason: "invalid-json",
+        };
+    }
+    if (!isPlainObject(parsed)) {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "invalid",
+            reason: "root-not-object",
+        };
+    }
+    const servers = parsed[target.topLevelKey];
+    if (servers !== undefined && !isPlainObject(servers)) {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "invalid",
+            reason: "servers-not-object",
+        };
+    }
+    const entry = isPlainObject(servers)
+        ? servers[BRIDGE_ENTRY_KEY]
+        : undefined;
+    if (entry === undefined) {
+        // A valid host config that simply has no Bridge registration yet. Other
+        // servers in the same file are deliberately not inspected or reported.
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "add",
+        };
+    }
+    if (!isPlainObject(entry)) {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: true,
+            shape: "custom",
+            action: "invalid",
+            reason: "entry-not-object",
+        };
+    }
+    const args = entry.args;
+    // Worktree shims are detected BEFORE any package-token requirement: the
+    // absolute-build-path form (`node /abs/path/build/index.js mcp-invoke`) has no
+    // package token at all, and must not be misread as an unsupported launcher.
+    if (isWorktreeShimArgs(args)) {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: true,
+            shape: "worktree-shim",
+            action: "skip-worktree-shim",
+        };
+    }
+    const pin = parseLauncherPin(args);
+    if (!pin) {
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: true,
+            shape: "custom",
+            action: "unsupported",
+            reason: "no-package-token",
+        };
+    }
+    const common = {
+        ...base,
+        filePresent: true,
+        bridgeEntryPresent: true,
+        shape: "standard",
+        spec: pin.spec,
+    };
+    // Bare and explicit `@latest` are the two forms an exact-pin policy normalizes
+    // rather than rejects — both mean "whatever npx resolves", which is exactly the
+    // non-determinism BAPI-429 pinned away from.
+    if (pin.specifier === null || pin.specifier === "latest") {
+        return { ...common, action: "normalize-unpinned" };
+    }
+    if (!isExactVersion(pin.specifier)) {
+        return {
+            ...common,
+            action: "unsupported",
+            reason: classifyNonExactSpecifier(pin.specifier),
+        };
+    }
+    const comparison = compareExactVersions(pin.specifier, targetVersion);
+    if (comparison === null) {
+        // The TARGET is not an exact release. Refuse rather than guess.
+        return {
+            ...common,
+            currentVersion: pin.specifier,
+            action: "unsupported",
+            reason: "malformed-version",
+        };
+    }
+    if (comparison > 0) {
+        return {
+            ...common,
+            currentVersion: pin.specifier,
+            action: "ahead",
+            reason: "pinned-ahead-of-target",
+        };
+    }
+    return {
+        ...common,
+        currentVersion: pin.specifier,
+        action: comparison === 0 ? "already-current" : "repin",
+    };
+}
+/** Classify why a non-exact specifier cannot be treated as a release pin. */
+function classifyNonExactSpecifier(specifier) {
+    if (/^[\^~]|^[<>=]/.test(specifier) || specifier.includes(" - ") || specifier.includes("||")) {
+        return "version-range";
+    }
+    // A leading digit means the author meant a version and got the shape wrong
+    // (`0.2`, `1.2.3.4`); anything else is a dist-tag or channel (`beta`, `next`).
+    if (/^v?\d/.test(specifier))
+        return "malformed-version";
+    return "non-release-specifier";
+}
+/** True for a non-null, non-array object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/build/mcp-host-config.js

@@ -28,6 +28,7 @@
  * rather than reserialize unrelated content.
  */
 import { VERSION } from "./version.generated.js";
+import { refreshBridgeApiPackageSpec } from "./init.js";
 // ---------------------------------------------------------------------------
 // Path helpers (POSIX-normalized; module stays free of node:path).
 // ---------------------------------------------------------------------------
@@ -119,7 +120,16 @@ export function mergeJsonHostConfig(existing, target, adaptedEntry) {
     const root = rootRaw && typeof rootRaw === "object" && !Array.isArray(rootRaw)
         ? { ...rootRaw }
         : {};
-    root["bridge-api"] = adaptedEntry;
+    // BAPI-714 (Group C): an UPDATE to a pre-existing Bridge registration keeps that
+    // registration's own launcher args composition — only the package-spec token is
+    // refreshed — so a global/manual host config written before `serve` existed is
+    // never migrated to it. A registration this path CREATES receives the adapted
+    // template args, `serve` included.
+    const prior = root["bridge-api"];
+    const preservedArgs = prior && typeof prior === "object" && !Array.isArray(prior)
+        ? refreshBridgeApiPackageSpec(prior.args, currentLauncherSpec())
+        : null;
+    root["bridge-api"] = preservedArgs ? { ...adaptedEntry, args: preservedArgs } : adaptedEntry;
     merged[target.topLevelKey] = root;
     return merged;
 }

package/build/mcp-install-state.js

@@ -152,6 +152,10 @@ export async function writeMcpInstallState(cwd, input, deps) {
         projectConfigPaths: normalizeProjectPaths(input.projectConfigPaths),
     };
     const finalPath = installStatePath(cwd);
+    return persistMcpInstallState(cwd, state, finalPath, deps);
+}
+/** Shared serialize-and-atomically-persist tail for the two writers below. */
+async function persistMcpInstallState(cwd, state, finalPath, deps) {
     const tempPath = installStateTempPath(cwd);
     const serialized = serializeMcpInstallState(state);
     try {
@@ -173,3 +177,31 @@ export async function writeMcpInstallState(cwd, input, deps) {
     }
     return { ok: true, path: finalPath, state };
 }
+/**
+ * Record a locally installed project artifact WITHOUT clobbering existing state.
+ *
+ * `writeMcpInstallState` rebuilds the whole document from its `input` — it does
+ * not merge. A caller supplying only `projectConfigPaths` would therefore write
+ * an EMPTY `selectedPlatforms`, silently dropping the platform roster a later
+ * `doctor` run reports from (BAPI-679 review, E-13). This helper reads the
+ * current state first and writes back the union, so the additive record stays
+ * additive.
+ *
+ * Only the repo-relative PATH is stored. No OAuth token, API key, GitHub
+ * credential, or expanded workflow secret can reach the file: the state schema
+ * has no field for one, and the serializer emits only schema-approved keys.
+ */
+export async function recordInstalledProjectArtifact(cwd, relPath, deps) {
+    if (typeof relPath !== "string" || relPath.length === 0) {
+        return { ok: false, error: "artifact path must be a non-empty relative path" };
+    }
+    const existing = await readMcpInstallState(cwd, deps);
+    const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];
+    const priorPaths = existing.status === "valid" ? existing.state.projectConfigPaths : [];
+    const state = {
+        version: MCP_INSTALL_STATE_VERSION,
+        selectedPlatforms: normalizePlatforms(priorPlatforms),
+        projectConfigPaths: normalizeProjectPaths([...priorPaths, relPath]),
+    };
+    return persistMcpInstallState(cwd, state, installStatePath(cwd), deps);
+}