@gmickel/gno 2.9.2 → 2.10.0

package/src/cli/commands/mcp/launch-path.ts

@@ -0,0 +1,87 @@
+/**
+ * Version-independent launch paths for client registrations (fn-213).
+ *
+ * `process.execPath` and the GNO entrypoint are absolute, and under a
+ * version manager they sit in a versioned install directory
+ * (`installs/bun/1.3.14/...`, `Cellar/bun/1.4.2/...`). A registration that
+ * names that directory keeps starting the old runtime after an upgrade, and
+ * fails once the version is removed. Each manager also keeps a link that
+ * follows its upgrades; a registration names that link instead, but only
+ * when it resolves to the very file in use now. Shims that pick a version
+ * from the shell environment (asdf, proto, mise shims) are never used: GUI
+ * clients start servers without that environment.
+ *
+ * @module src/cli/commands/mcp/launch-path
+ */
+
+// node:fs realpathSync: synchronous link resolution; Bun has no realpath API.
+import { realpathSync } from "node:fs";
+
+/** mise, asdf and proto: `<root>/{installs,tools}/bun/<version>/...`. */
+const MANAGER_VERSION_DIR = /([\\/])(installs|tools)\1bun\1([^\\/]+)(?=[\\/])/;
+/** Homebrew: `<prefix>/Cellar/bun/<version>/...`. */
+const HOMEBREW_VERSION_DIR = /([\\/])Cellar\1bun\1[^\\/]+(?=[\\/])/;
+/** Version-independent directory names a manager keeps itself. */
+const ALIAS_VERSIONS = new Set(["latest", "current", "system"]);
+
+/**
+ * The version-independent links a manager keeps for `path`, or null when
+ * `path` is not inside a versioned install directory.
+ */
+export function versionIndependentCandidates(path: string): string[] | null {
+  const cellar = HOMEBREW_VERSION_DIR.exec(path);
+  if (cellar) {
+    const separator = cellar[1] ?? "/";
+    return [
+      path.replace(HOMEBREW_VERSION_DIR, `${separator}opt${separator}bun`),
+    ];
+  }
+  const manager = MANAGER_VERSION_DIR.exec(path);
+  if (!manager || ALIAS_VERSIONS.has(manager[3] ?? "")) {
+    return null;
+  }
+  const separator = manager[1] ?? "/";
+  return [
+    path.replace(
+      MANAGER_VERSION_DIR,
+      `${separator}${manager[2]}${separator}bun${separator}latest`
+    ),
+  ];
+}
+
+const realpathOrNull = (path: string): string | null => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+export interface LaunchPath {
+  /** The path to write. */
+  path: string;
+  /**
+   * True when `path` is inside a versioned install directory and no
+   * version-independent link resolves to it: the registration stays on this
+   * version until it is reinstalled.
+   */
+  pinned: boolean;
+}
+
+/** Prefer a version-independent link that resolves to the same file. */
+export function stableLaunchPath(
+  path: string,
+  realpath: (path: string) => string | null = realpathOrNull
+): LaunchPath {
+  const candidates = versionIndependentCandidates(path);
+  if (!candidates) {
+    return { path, pinned: false };
+  }
+  const target = realpath(path);
+  for (const candidate of candidates) {
+    if (target !== null && realpath(candidate) === target) {
+      return { path: candidate, pinned: false };
+    }
+  }
+  return { path, pinned: true };
+}

package/src/cli/commands/mcp/paths.ts

@@ -18,6 +18,8 @@ import {
   type McpToolProfile,
   isMcpToolProfile,
 } from "../../../mcp/tool-profile.js";
+import { isBunfsPath } from "../../../serve/spa-production-build";
+import { type LaunchPath, stableLaunchPath } from "./launch-path.js";
 import { getTargetDisplayName } from "./target-display.js";
 
 export { getTargetDisplayName } from "./target-display.js";
@@ -447,14 +449,35 @@ export function resolveAllMcpPaths(
 // Bun & GNO Path Discovery
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * The Bun and GNO paths a registration launches, preferring links that
+ * follow version-manager upgrades (see launch-path.ts). A standalone
+ * compiled executable is left alone: its execPath is GNO itself.
+ */
+export function resolveLaunchPaths(): {
+  bun: LaunchPath;
+  entrypoint: LaunchPath;
+} {
+  const entrypoint = getCurrentGnoEntrypoint();
+  if (isBunfsPath(import.meta.path)) {
+    return {
+      bun: { path: process.execPath, pinned: false },
+      entrypoint: { path: entrypoint, pinned: false },
+    };
+  }
+  return {
+    bun: stableLaunchPath(process.execPath),
+    entrypoint: stableLaunchPath(entrypoint),
+  };
+}
+
 /**
  * Find absolute path to bun executable.
- * Cross-platform: uses process.execPath since we're already running under Bun.
+ * Cross-platform: starts from process.execPath since we're already running
+ * under Bun, then prefers a version-independent link to the same binary.
  */
 export function findBunPath(): string {
-  // process.execPath is the absolute path to the Bun binary running this process.
-  // This is cross-platform and doesn't require shelling out to `which`.
-  return process.execPath;
+  return resolveLaunchPaths().bun.path;
 }
 
 /**
@@ -467,8 +490,9 @@ export function buildMcpServerEntry(
   if (options.indexName !== undefined) {
     assertValidIndexName(options.indexName);
   }
-  const bunPath = findBunPath();
-  const args = ["run", getCurrentGnoEntrypoint()];
+  const launch = resolveLaunchPaths();
+  const bunPath = launch.bun.path;
+  const args = ["run", launch.entrypoint.path];
   appendMcpArguments(args, options);
   const dirs = resolveDirs();
   return {

package/src/cli/commands/mcp/repair-entry.ts

@@ -0,0 +1,160 @@
+/**
+ * `gno mcp install --force` over an existing registration (fn-213).
+ *
+ * The launch path (the interpreter and the `run <entrypoint>` prefix) is
+ * always rewritten. Every other argument, environment variable and entry key
+ * is kept, except the options the user passed explicitly in this invocation,
+ * which override their values. Defaults the installer fills in for omitted
+ * options never override an existing value.
+ *
+ * @module src/cli/commands/mcp/repair-entry
+ */
+
+// node:path basename: no Bun path utilities.
+import { basename } from "node:path";
+
+import type { McpToolProfile } from "../../../mcp/tool-profile.js";
+import type { McpConfigFormat, McpServerEntry } from "./paths.js";
+
+import { isPlainRecord } from "./config-editors.js";
+
+/** Install options the user passed explicitly (undefined = not passed). */
+export interface ExplicitInstallValues {
+  indexName?: string;
+  configPath?: string;
+  toolProfile?: McpToolProfile;
+  enableWrite?: boolean;
+}
+
+/** An existing registration split into what GNO writes and everything else. */
+export interface ExistingRegistration {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  /** Entry keys GNO does not manage, kept verbatim. */
+  extra: Record<string, unknown>;
+}
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+const stringRecord = (value: unknown): Record<string, string> | null => {
+  if (value === undefined) {
+    return {};
+  }
+  if (!isPlainRecord(value)) {
+    return null;
+  }
+  const entries = Object.entries(value);
+  return entries.every(([, item]) => typeof item === "string")
+    ? (Object.fromEntries(entries) as Record<string, string>)
+    : null;
+};
+
+/** The entry `--force` writes when it repairs an existing registration. */
+export interface RepairedRegistration {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  extra: Record<string, unknown>;
+}
+
+/** Read an existing entry; null when it is not a command registration. */
+export function readExistingRegistration(
+  entry: unknown,
+  format: McpConfigFormat
+): ExistingRegistration | null {
+  if (!isPlainRecord(entry)) {
+    return null;
+  }
+  if (format === "mcp") {
+    const { command, environment, ...extra } = entry;
+    const env = stringRecord(environment);
+    if (!isStringArray(command) || command.length === 0 || env === null) {
+      return null;
+    }
+    const [executable = "", ...args] = command;
+    return { command: executable, args, env, extra };
+  }
+  const { command, args, env: rawEnv, ...extra } = entry;
+  const env = stringRecord(rawEnv);
+  if (typeof command !== "string" || !isStringArray(args) || env === null) {
+    return null;
+  }
+  return { command, args, env, extra };
+}
+
+const isGnoExecutable = (command: string): boolean =>
+  ["gno", "gno.exe", "gno.cmd"].includes(basename(command).toLowerCase());
+
+/**
+ * The arguments after the launch prefix, or null when the registration is
+ * not a recognizable GNO MCP launch (it is then replaced as before).
+ */
+function argumentsAfterLaunch(
+  registration: ExistingRegistration
+): string[] | null {
+  const { command, args } = registration;
+  let rest: string[] | null = null;
+  if (args[0] === "run" && args.length >= 2) {
+    rest = args.slice(2);
+  } else if (isGnoExecutable(command)) {
+    rest = args;
+  }
+  return rest?.includes("mcp") ? rest : null;
+}
+
+/** Set `flag value` in `list`, replacing `flag v` or `flag=v` in place. */
+function setFlag(list: string[], flag: string, value: string): string[] {
+  const position = list.findIndex(
+    (item) => item === flag || item.startsWith(`${flag}=`)
+  );
+  if (position === -1) {
+    return [...list, flag, value];
+  }
+  const next = [...list];
+  if (next[position] === flag) {
+    next.splice(position, 2, flag, value);
+  } else {
+    next.splice(position, 1, flag, value);
+  }
+  return next;
+}
+
+/**
+ * The entry `--force` writes over `existing`: `fresh`'s launch path, the
+ * existing arguments and environment with explicit options applied, and the
+ * existing keys GNO does not manage. Null when `existing` is not a GNO MCP
+ * launch, so the caller writes `fresh` as before.
+ */
+export function repairRegistration(
+  existing: ExistingRegistration,
+  fresh: McpServerEntry,
+  explicit: ExplicitInstallValues
+): RepairedRegistration | null {
+  const rest = argumentsAfterLaunch(existing);
+  if (!rest) {
+    return null;
+  }
+  const mcpPosition = rest.indexOf("mcp");
+  let globals = rest.slice(0, mcpPosition);
+  let subcommand = rest.slice(mcpPosition + 1);
+  if (explicit.indexName !== undefined) {
+    globals = setFlag(globals, "--index", explicit.indexName);
+  }
+  if (explicit.configPath !== undefined) {
+    globals = setFlag(globals, "--config", explicit.configPath);
+  }
+  if (explicit.toolProfile !== undefined) {
+    subcommand = setFlag(subcommand, "--tool-profile", explicit.toolProfile);
+  }
+  if (explicit.enableWrite && !subcommand.includes("--enable-write")) {
+    subcommand = [...subcommand, "--enable-write"];
+  }
+  return {
+    command: fresh.command,
+    args: [...fresh.args.slice(0, 2), ...globals, "mcp", ...subcommand],
+    env: { ...fresh.env, ...existing.env },
+    extra: existing.extra,
+  };
+}

package/src/cli/commands/mcp/status.ts

@@ -101,6 +101,54 @@ interface StatusResult {
 // Config Reading
 // ─────────────────────────────────────────────────────────────────────────────
 
+const isStringArray = (value: unknown): boolean =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+/**
+ * Client settings that never change how the command runs: timeouts, labels
+ * and approval prompts. Anything else (cwd, url, headers, another transport,
+ * unknown keys) keeps an entry fail-closed, because the connector verifier
+ * starts the registered command.
+ */
+const INERT_ENTRY_KEYS: Record<string, (value: unknown) => boolean> = {
+  type: (value) => value === "stdio",
+  timeout: (value) => typeof value === "number",
+  startup_timeout_sec: (value) => typeof value === "number",
+  tool_timeout_sec: (value) => typeof value === "number",
+  description: (value) => typeof value === "string",
+  autoApprove: isStringArray,
+  alwaysAllow: isStringArray,
+  enabled: (value) => typeof value === "boolean",
+  disabled: (value) => typeof value === "boolean",
+};
+
+/** Keys other than the launch keys are all known and inert. */
+function hasOnlyInertExtras(
+  record: Record<string, unknown>,
+  launchKeys: readonly string[],
+  allowed: Record<string, (value: unknown) => boolean>
+): boolean {
+  return Object.entries(record).every(
+    ([key, value]) =>
+      launchKeys.includes(key) || (allowed[key]?.(value) ?? false)
+  );
+}
+
+/** OpenCode writes `type: "local"` and `enabled` itself. */
+const OPENCODE_INERT_KEYS: Record<string, (value: unknown) => boolean> = {
+  timeout: (value) => typeof value === "number",
+  enabled: (value) => typeof value === "boolean",
+};
+
+/** A registration the client has switched off. */
+function isDisabledEntry(entry: unknown): boolean {
+  if (!entry || typeof entry !== "object") {
+    return false;
+  }
+  const record = entry as Record<string, unknown>;
+  return record.enabled === false || record.disabled === true;
+}
+
 /**
  * Normalize entry to standard format for display.
  */
@@ -120,12 +168,10 @@ function normalizeEntry(
       !Array.isArray(record.command) ||
       record.command.length === 0 ||
       !record.command.every((part) => typeof part === "string") ||
-      Object.keys(record).some(
-        (key) =>
-          key !== "type" &&
-          key !== "command" &&
-          key !== "enabled" &&
-          key !== "environment"
+      !hasOnlyInertExtras(
+        record,
+        ["type", "command", "environment"],
+        OPENCODE_INERT_KEYS
       )
     ) {
       return null;
@@ -149,9 +195,7 @@ function normalizeEntry(
     record.command.length === 0 ||
     !Array.isArray(record.args) ||
     !record.args.every((argument) => typeof argument === "string") ||
-    Object.keys(record).some(
-      (key) => key !== "command" && key !== "args" && key !== "env"
-    )
+    !hasOnlyInertExtras(record, ["command", "args", "env"], INERT_ENTRY_KEYS)
   ) {
     return null;
   }
@@ -211,12 +255,8 @@ export async function checkMcpTargetStatus(
       return { target, scope, configPath, configured: false };
     }
     const entry = parsed.entry;
-    if (
-      configFormat === "mcp" &&
-      entry &&
-      typeof entry === "object" &&
-      (entry as { enabled?: unknown }).enabled === false
-    ) {
+    // A registration the client has switched off is not configured.
+    if (isDisabledEntry(entry)) {
       return { target, scope, configPath, configured: false };
     }
     const configIdentity = entryIdentity(entry);

package/src/cli/commands/mcp.ts

@@ -7,6 +7,8 @@
 import type { McpToolProfile } from "../../mcp/tool-profile";
 import type { GlobalOptions } from "../context";
 
+import { warnIfBunBelowFloor } from "../../app/bun-runtime";
+
 /**
  * Start the MCP server.
  * Reads global options for --index and --config flags.
@@ -15,6 +17,8 @@ export async function mcpCommand(
   options: GlobalOptions,
   commandOptions: { enableWrite?: boolean; toolProfile?: McpToolProfile } = {}
 ): Promise<void> {
+  // stderr only: stdout carries the MCP protocol.
+  warnIfBunBelowFloor("mcp");
   const { startMcpServer } = await import("../../mcp/server.js");
   await startMcpServer({
     indexName: options.index,

package/src/cli/commands/serve.ts

@@ -5,6 +5,8 @@
  * @module src/cli/commands/serve
  */
 
+import { warnIfBunBelowFloor } from "../../app/bun-runtime";
+
 export type { ServeOptions, ServeResult } from "../../serve";
 
 /**
@@ -14,6 +16,7 @@ export type { ServeOptions, ServeResult } from "../../serve";
 export async function serve(
   options: import("../../serve").ServeOptions = {}
 ): Promise<import("../../serve").ServeResult> {
+  warnIfBunBelowFloor("serve");
   const { startServer } = await import("../../serve");
   return startServer(options);
 }

package/src/cli/commands/status.ts

@@ -44,6 +44,12 @@ import {
   resolveProcessPaths,
   statusProcess,
 } from "../detach";
+import {
+  checkRegistrationRuntimes,
+  checkResidentRuntimes,
+  formatRuntimeIssue,
+  type RuntimeIssue,
+} from "../runtime-health";
 
 /**
  * Options for status command.
@@ -70,6 +76,8 @@ export type StatusResult =
       contentTypeBoost: ContentTypeBoostStatus;
       memory: MemoryStatus;
       backgroundIssues: ResidentBackgroundIssue[];
+      /** Registrations and residents on a missing, old or other Bun (fn-213). */
+      runtimeIssues?: RuntimeIssue[];
       /** Files whose latest conversion stopped at the per-file budget. */
       budgetStops: BudgetStop[];
     }
@@ -433,6 +441,10 @@ export async function status(
       contentTypeBoost: buildContentTypeBoostStatus(config.contentTypes ?? []),
       memory: await buildMemoryStatus(store, config.collections),
       backgroundIssues: await collectResidentIssues(),
+      runtimeIssues: [
+        ...(await checkRegistrationRuntimes()),
+        ...(await checkResidentRuntimes()),
+      ],
       budgetStops: await collectBudgetStops(store),
     };
   } finally {
@@ -486,6 +498,9 @@ export function formatStatus(
         ...(result.backgroundIssues.length
           ? { backgroundIssues: result.backgroundIssues }
           : {}),
+        ...(result.runtimeIssues?.length
+          ? { runtimeIssues: result.runtimeIssues }
+          : {}),
       },
       null,
       2
@@ -524,5 +539,14 @@ export function formatStatus(
         ]
       : []),
     ...(issueLines.length ? ["", "Background issues:", ...issueLines] : []),
+    ...(result.runtimeIssues?.length
+      ? [
+          "",
+          "Bun runtime:",
+          ...result.runtimeIssues.map(
+            (issue) => `  [${issue.severity}] ${formatRuntimeIssue(issue)}`
+          ),
+        ]
+      : []),
   ].join("\n");
 }

package/src/cli/detach.ts

@@ -56,6 +56,8 @@ export interface PidFilePayload {
   version: string;
   started_at: string;
   port?: number | null;
+  /** Bun the resident runs on (fn-213); absent in older pid-files. */
+  bun_version?: string;
 }
 
 /** Result of a `--status` call (matches process-status@1.0). */
@@ -246,6 +248,9 @@ export async function readPidFile(
     version: record.version,
     started_at: record.started_at,
     port,
+    ...(typeof record.bun_version === "string" && record.bun_version
+      ? { bun_version: record.bun_version }
+      : {}),
   };
 }
 
@@ -610,6 +615,11 @@ export async function spawnDetached(
       version: VERSION,
       started_at: new Date().toISOString(),
       port: options.port ?? null,
+      // The child runs on this process's Bun unless a caller replaced the
+      // command.
+      ...(options.cmdPrefix || options.execPath
+        ? {}
+        : { bun_version: Bun.version }),
     };
 
     // If the pid-file write fails (disk full, permission race, bad path on

package/src/cli/program.ts

@@ -2644,7 +2644,7 @@ function wireMcpCommand(program: Command): void {
       "advertised tool set the registration starts with: core (7 read tools + capture/remember with --enable-write) or full (default)"
     )
     .option("--json", "JSON output")
-    .action(async (cmdOpts: Record<string, unknown>) => {
+    .action(async (cmdOpts: Record<string, unknown>, command: Command) => {
       const target = cmdOpts.target as string;
       const toolProfile = parseToolProfileOption(cmdOpts.toolProfile);
       const requestedScope = cmdOpts.scope;
@@ -2687,9 +2687,14 @@ function wireMcpCommand(program: Command): void {
         scope: scope as "user" | "project",
         force: Boolean(cmdOpts.force),
         dryRun: Boolean(cmdOpts.dryRun),
-        enableWrite: Boolean(cmdOpts.enableWrite),
+        // Only options the user passed: --force keeps the rest of an
+        // existing registration (--index has a default, so check its source).
+        enableWrite: cmdOpts.enableWrite === true ? true : undefined,
         toolProfile,
-        indexName: globals.index,
+        indexName:
+          command.getOptionValueSourceWithGlobals("index") === "cli"
+            ? globals.index
+            : undefined,
         configPath: globals.config,
         // Pass undefined if not set, so global --json can take effect
         json: cmdOpts.json === true ? true : undefined,