@bridge_gpt/mcp-server 0.2.36 → 0.2.38

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-invoke.js

@@ -25,6 +25,7 @@ import path from "path";
 import os from "os";
 import { resolveRepoNameForProjectRoot, readBridgeConfig, validateMcpTarget, } from "./bridge-config.js";
 import { resolveBapiCredentials } from "./credential-store.js";
+import { describeBaseUrlRejection, validateHttpBaseUrl } from "./base-url.js";
 import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
 // ---------------------------------------------------------------------------
 // Usage / argument parsing
@@ -47,18 +48,30 @@ export function getMcpInvokeUsage() {
         "                               API server; a configured third-party target from",
         "                               .bridge/config (e.g. sfcc) launches that server.",
         "  --project-root <ABS_PATH>    Absolute path to the worktree (required)",
+        "  --base-url <HTTP(S)_URL>     Optional. Bridge API endpoint for the spawned",
+        "                               server; applies ONLY to --target bapi. When",
+        "                               omitted, the child inherits BAPI_BASE_URL",
+        "                               unchanged. Must be an absolute http/https URL",
+        "                               with no embedded username or password.",
         "  -h, --help                   Show this help",
     ].join("\n");
 }
-const KNOWN_FLAGS = new Set(["--target", "--project-root"]);
+const KNOWN_FLAGS = new Set(["--target", "--project-root", "--base-url"]);
 /**
- * Parse `--target` and `--project-root` (split or `=` form). Rejects unknown
- * flags, positional arguments, missing values, and duplicates. Requires a safe
- * non-empty `--target` identifier and a host-platform-absolute `--project-root`.
+ * Parse `--target`, `--project-root`, and the optional `--base-url` (split or `=`
+ * form). Rejects unknown flags, positional arguments, missing values, and
+ * duplicates. Requires a safe non-empty `--target` identifier and a
+ * host-platform-absolute `--project-root`.
+ *
+ * `--base-url` is validated strictly and is valid ONLY with `--target bapi`;
+ * pairing it with any other target is an error rather than a silent no-op, so a
+ * misgenerated registration fails loudly instead of quietly routing a Tier-2
+ * server nowhere. No rejection message ever echoes the supplied URL.
  */
 export function parseMcpInvokeArgs(argv) {
     let target;
     let projectRoot;
+    let baseUrl;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
         if (token === "-h" || token === "--help") {
@@ -91,6 +104,16 @@ export function parseMcpInvokeArgs(argv) {
             }
             target = value;
         }
+        else if (flag === "--base-url") {
+            if (baseUrl !== undefined) {
+                return { status: "error", message: "Duplicate --base-url flag" };
+            }
+            const validation = validateHttpBaseUrl(value);
+            if (!validation.ok) {
+                return { status: "error", message: describeBaseUrlRejection("--base-url", validation.reason) };
+            }
+            baseUrl = validation.baseUrl;
+        }
         else {
             if (projectRoot !== undefined) {
                 return { status: "error", message: "Duplicate --project-root flag" };
@@ -111,7 +134,15 @@ export function parseMcpInvokeArgs(argv) {
     if (!path.isAbsolute(projectRoot)) {
         return { status: "error", message: "--project-root must be an absolute path" };
     }
-    return { status: "ok", target: targetValidation.value, projectRoot };
+    if (baseUrl !== undefined && targetValidation.value !== "bapi") {
+        return {
+            status: "error",
+            message: "--base-url is only valid with --target bapi",
+        };
+    }
+    return baseUrl === undefined
+        ? { status: "ok", target: targetValidation.value, projectRoot }
+        : { status: "ok", target: targetValidation.value, projectRoot, baseUrl };
 }
 // ---------------------------------------------------------------------------
 // Validation, env construction, signals
@@ -284,6 +315,15 @@ export async function resolveBapiInvocation(projectRoot, deps) {
     if (typeof conductorNodePath === "string" && conductorNodePath.trim().length > 0) {
         overlay.CONDUCTOR_NODE_PATH = conductorNodePath;
     }
+    // BAPI-727: overlay the endpoint ONLY when `--base-url` was supplied, mirroring
+    // the conditional `CONDUCTOR_NODE_PATH` overlay directly above. The absent case
+    // must add, delete, normalize, and override nothing — `buildChildEnv` already
+    // inherits the parent's `BAPI_BASE_URL`, and the server keeps its own production
+    // default for callers that were never given a URL. Like `CONDUCTOR_NODE_PATH`,
+    // this is non-secret routing metadata, not a credential.
+    if (typeof deps.baseUrl === "string" && deps.baseUrl.length > 0) {
+        overlay.BAPI_BASE_URL = deps.baseUrl;
+    }
     const env = buildChildEnv(deps.env, overlay);
     return {
         ok: true,
@@ -356,7 +396,7 @@ export async function runMcpInvokeCli(argv, overrides = {}) {
         stderr(getMcpInvokeUsage());
         return 1;
     }
-    const { target, projectRoot } = parsed;
+    const { target, projectRoot, baseUrl } = parsed;
     const statFn = overrides.stat ?? ((p) => stat(p));
     const dirCheck = await validateProjectRootDirectory(projectRoot, statFn);
     if (!dirCheck.ok) {
@@ -379,12 +419,15 @@ export async function runMcpInvokeCli(argv, overrides = {}) {
             }));
         const resolveCredentials = overrides.resolveCredentials ??
             ((rn) => resolveBapiCredentials(rn, credentialDeps));
+        // The parsed URL reaches ONLY this branch; the parser already rejected
+        // `--base-url` for every other target, so the Tier-2 path below cannot see it.
         const resolved = await resolveBapiInvocation(projectRoot, {
             env,
             execPath: process.execPath,
             scriptPath: process.argv[1],
             resolveRepoName,
             resolveCredentials,
+            baseUrl,
         });
         if (!resolved.ok) {
             stderr(`Error: ${resolved.error}`);

package/build/mcp-provisioning.js

@@ -78,13 +78,29 @@ export function serverNameForMcpTarget(target) {
  * form preferred) and never depends on a worker-injected `CONDUCTOR_NODE_PATH`
  * or any other worker-shell env — the executor worker environment carries no
  * such key at all (see `executor/env.ts`).
+ *
+ * BAPI-727 extends the BAPI-527 note above rather than contradicting it. The
+ * optional `bridgeApiBaseUrl` is appended as the ARGUMENT `--base-url <url>`, and
+ * only for the `bapi` target. A Bridge API endpoint is non-secret ROUTING
+ * metadata — the same value that appears in an operator's `--base-url` flag and in
+ * generated executor service units — so persisting it does not weaken the
+ * no-`env`, no-credential registration invariant. The entry keeps exactly
+ * `command` and `args`; credentials continue to be resolved by the `mcp-invoke`
+ * shim at launch and are never written into the worktree.
  */
-export function buildShimMcpServerEntry(target, absoluteWorktreePath, invocation) {
-    return buildMcpShimCommand(invocation, target, absoluteWorktreePath);
+export function buildShimMcpServerEntry(target, absoluteWorktreePath, invocation, bridgeApiBaseUrl) {
+    const entry = buildMcpShimCommand(invocation, target, absoluteWorktreePath);
+    // Tier-2 targets are structurally unchanged: `--base-url` is a `bapi`-only flag
+    // and `mcp-invoke` rejects it for any other target, so appending it elsewhere
+    // would generate a registration that refuses to launch.
+    if (target !== "bapi" || bridgeApiBaseUrl === undefined)
+        return entry;
+    // Clone/extend the generated args; never add a property beyond command/args.
+    return { command: entry.command, args: [...entry.args, "--base-url", bridgeApiBaseUrl] };
 }
 /** Back-compat wrapper around `buildShimMcpServerEntry("bapi", ...)`. */
-export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath, invocation) {
-    return buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
+export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath, invocation, bridgeApiBaseUrl) {
+    return buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation, bridgeApiBaseUrl);
 }
 /**
  * Convert all supported manifest `mcp` entries into a map of server name -> shim
@@ -93,12 +109,14 @@ export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath, invocatio
  * or incomplete non-`bapi` targets are skipped with a secret-free warning (they
  * never appear in the returned entries).
  */
-export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath, invocation) {
+export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath, invocation, bridgeApiBaseUrl) {
     const entries = {};
     const warnings = [];
     for (const mcp of manifest.mcp) {
         if (mcp.target === "bapi") {
-            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
+            // The optional base URL reaches ONLY this branch — Tier-2 entries below are
+            // built without it and stay byte-identical to their pre-BAPI-727 shape.
+            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation, bridgeApiBaseUrl);
             continue;
         }
         const definition = getThirdPartyTargetDefinition(mcp.target);
@@ -162,6 +180,11 @@ export function mergeEnabledMcpjsonServers(existing, serverNames) {
  * Unrelated top-level fields and unrelated MCP servers are preserved; only the
  * generated server names are replaced. Any legacy secret-embedded entry for a
  * generated server name is force-upgraded to the secret-free shim shape.
+ *
+ * Deliberately UNCHANGED by BAPI-727: because a generated name is replaced rather
+ * than merged field-by-field, re-provisioning an existing worktree automatically
+ * upgrades an older `bridge-api` entry that lacks `--base-url` to the URL-bearing
+ * one. No migration step is needed.
  */
 export function mergeMcpRegistrations(existing, topLevelKey, entries) {
     const result = existing && typeof existing === "object" && !Array.isArray(existing)
@@ -321,7 +344,7 @@ export async function provisionMcpRegistrationForWorktree(row, deps) {
     if (!normalized.ok) {
         return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${normalized.error}` };
     }
-    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path, deps.mcpServerInvocation);
+    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path, deps.mcpServerInvocation, deps.bridgeApiBaseUrl);
     if (Object.keys(built.entries).length === 0) {
         // Nothing supported to write (e.g. a manifest with no bapi target and no
         // supported Tier-2 targets). Surface any warnings but leave status unchanged.

package/build/mcp-registration-doctor.js

@@ -8,17 +8,26 @@
  */
 import path from "path";
 /**
- * Read and parse a JSON file. A read failure (e.g. ENOENT) is `missing`; invalid
- * JSON is `malformed` (carrying only the path, never the raw content); otherwise
- * `present` with the parsed value.
+ * Read and parse a JSON file.
+ *
+ * A read failure whose error carries an `ENOENT` code is `missing` — the file
+ * genuinely is not there. Any OTHER read failure (e.g. `EACCES`) is `unreadable`:
+ * BAPI-727's shadow inspector must not treat "I could not look" as "there is
+ * nothing there", because an unreadable `~/.claude.json` could still be shadowing
+ * a worker's MCP registration. Invalid JSON stays `malformed`; both non-present
+ * failure states carry ONLY the path — never the raw content and never the read
+ * exception's message, which can contain arbitrary text.
  */
 export async function readJsonIfPresent(filePath, deps) {
     let raw;
     try {
         raw = await deps.readFile(filePath);
     }
-    catch {
-        return { state: "missing" };
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT")
+            return { state: "missing" };
+        return { state: "unreadable", path: filePath };
     }
     try {
         return { state: "present", value: JSON.parse(raw) };