@gmickel/gno 2.9.2 → 2.10.1

package/src/cli/commands/mcp/config-editors.ts

@@ -371,19 +371,66 @@ function tomlString(value: string): string {
   return JSON.stringify(value);
 }
 
-function serializeTomlEntry(entry: StandardMcpEntry, newline: string): string {
+const TOML_BARE_KEY = /^[A-Za-z0-9_-]+$/;
+
+function tomlKey(key: string): string {
+  return TOML_BARE_KEY.test(key) ? key : tomlString(key);
+}
+
+/** A kept key's value as TOML; null for values this writer cannot express. */
+function tomlValue(value: unknown): string | null {
+  if (typeof value === "string") {
+    return tomlString(value);
+  }
+  if (
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map(tomlValue);
+    return items.every((item) => item !== null)
+      ? `[${items.join(", ")}]`
+      : null;
+  }
+  return null;
+}
+
+/** Keys of an existing GNO entry kept by a repair (see repair-entry.ts). */
+export interface TomlEntryExtras {
+  env?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}
+
+function serializeTomlEntry(
+  entry: StandardMcpEntry,
+  newline: string,
+  configPath: string,
+  extras: TomlEntryExtras = {}
+): string {
   const args = entry.args.map(tomlString).join(", ");
   const lines = [
     "[mcp_servers.gno]",
     `command = ${tomlString(entry.command)}`,
     `args = [${args}]`,
   ];
-  if (entry.env && Object.keys(entry.env).length > 0) {
+  for (const [key, value] of Object.entries(extras.extra ?? {})) {
+    const serialized = tomlValue(value);
+    if (serialized === null) {
+      throw new CliError(
+        "RUNTIME",
+        `Cannot keep "${key}" of the GNO MCP entry in ${configPath}; remove the entry with gno mcp uninstall, or edit the key, then install again.`
+      );
+    }
+    lines.push(`${tomlKey(key)} = ${serialized}`);
+  }
+  const env = { ...entry.env, ...extras.env };
+  if (Object.keys(env).length > 0) {
     lines.push("", "[mcp_servers.gno.env]");
-    for (const key of ["GNO_DATA_DIR", "GNO_CACHE_DIR"] as const) {
-      const value = entry.env[key];
+    for (const [key, value] of Object.entries(env)) {
       if (value) {
-        lines.push(`${key} = ${tomlString(value)}`);
+        lines.push(`${tomlKey(key)} = ${tomlString(value)}`);
       }
     }
   }
@@ -393,7 +440,8 @@ function serializeTomlEntry(entry: StandardMcpEntry, newline: string): string {
 export function setTomlServerEntry(
   content: string,
   configPath: string,
-  entry: StandardMcpEntry
+  entry: StandardMcpEntry,
+  extras?: TomlEntryExtras
 ): string {
   const parsed = getTomlServerEntry(content, configPath);
   const removed = removeTomlGnoSections(content, configPath);
@@ -405,8 +453,8 @@ export function setTomlServerEntry(
   }
   const prefix = removed.content.trimEnd();
   const updated = prefix
-    ? `${prefix}${removed.newline}${removed.newline}${serializeTomlEntry(entry, removed.newline)}`
-    : serializeTomlEntry(entry, removed.newline);
+    ? `${prefix}${removed.newline}${removed.newline}${serializeTomlEntry(entry, removed.newline, configPath, extras)}`
+    : serializeTomlEntry(entry, removed.newline, configPath, extras);
   parseTomlRoot(updated, configPath);
   return updated;
 }

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

@@ -29,14 +29,22 @@ import {
 } from "./config.js";
 import {
   buildMcpServerEntry,
+  resolveLaunchPaths,
   getDefaultTargetScope,
   getTargetScopes,
   getTargetDisplayName,
+  type McpConfigFormat,
   type McpScope,
   type McpServerEntry,
   type McpTarget,
   resolveMcpConfigPath,
 } from "./paths.js";
+import {
+  type ExplicitInstallValues,
+  readExistingRegistration,
+  type RepairedRegistration,
+  repairRegistration,
+} from "./repair-entry.js";
 import { normalizeMcpServerEntryForInstall } from "./server-entry.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -71,6 +79,8 @@ export interface McpInstallResult {
   configPath: string;
   action: "created" | "updated" | "dry_run_create" | "dry_run_update";
   serverEntry: McpServerEntry;
+  /** `--force` kept the existing entry's settings and repaired its launch path. */
+  repaired?: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -89,6 +99,12 @@ export async function installMcpToTarget(
     dryRun?: boolean;
     cwd?: string;
     homeDir?: string;
+    /**
+     * With `force` over an existing entry: keep its settings and apply only
+     * these explicit options (repair-entry.ts). Without it, the entry is
+     * replaced.
+     */
+    preserveExisting?: ExplicitInstallValues;
   }
 ): Promise<McpInstallResult> {
   const { force = false, dryRun = false, cwd, homeDir } = options;
@@ -120,23 +136,45 @@ export async function installMcpToTarget(
     );
   }
 
-  const entry = buildEntry(
-    normalizedEntry.command,
-    normalizedEntry.args,
-    configFormat,
-    normalizedEntry.env
-  );
-  const standardEntry = {
-    command: normalizedEntry.command,
-    args: normalizedEntry.args,
-    ...(normalizedEntry.env ? { env: normalizedEntry.env } : {}),
-  };
-  const updated =
-    configFormat === "codex_toml"
-      ? setTomlServerEntry(content, configPath, standardEntry)
-      : configFormat === "yaml_standard"
-        ? setYamlServerEntry(content, configPath, serversKey, standardEntry)
-        : setJsoncServerEntry(content, configPath, serversKey, entry);
+  const existing =
+    alreadyExists && options.preserveExisting
+      ? readExistingRegistration(parsed.entry, configFormat)
+      : null;
+  const repaired =
+    existing && options.preserveExisting
+      ? repairRegistration(existing, normalizedEntry, options.preserveExisting)
+      : null;
+  if (repaired) {
+    // Same structural rules as a fresh entry for what this command writes.
+    normalizeMcpServerEntryForInstall({
+      command: repaired.command,
+      args: repaired.args,
+    });
+  }
+  const updated = repaired
+    ? writeRepairedEntry(
+        content,
+        configPath,
+        configFormat,
+        serversKey,
+        repaired
+      )
+    : writeFreshEntry(
+        content,
+        configPath,
+        configFormat,
+        serversKey,
+        normalizedEntry
+      );
+  const writtenEntry: McpServerEntry = repaired
+    ? {
+        command: repaired.command,
+        args: repaired.args,
+        ...(Object.keys(repaired.env).length > 0
+          ? { env: repaired.env as McpServerEntry["env"] }
+          : {}),
+      }
+    : normalizedEntry;
 
   const wouldCreate = !alreadyExists;
   if (dryRun) {
@@ -145,7 +183,8 @@ export async function installMcpToTarget(
       scope,
       configPath,
       action: wouldCreate ? "dry_run_create" : "dry_run_update",
-      serverEntry: normalizedEntry,
+      serverEntry: writtenEntry,
+      ...(repaired ? { repaired: true } : {}),
     };
   }
 
@@ -157,8 +196,73 @@ export async function installMcpToTarget(
     scope,
     configPath,
     action,
-    serverEntry: normalizedEntry,
+    serverEntry: writtenEntry,
+    ...(repaired ? { repaired: true } : {}),
+  };
+}
+
+function writeFreshEntry(
+  content: string,
+  configPath: string,
+  configFormat: McpConfigFormat,
+  serversKey: string,
+  normalizedEntry: McpServerEntry
+): string {
+  const standardEntry = {
+    command: normalizedEntry.command,
+    args: normalizedEntry.args,
+    ...(normalizedEntry.env ? { env: normalizedEntry.env } : {}),
+  };
+  if (configFormat === "codex_toml") {
+    return setTomlServerEntry(content, configPath, standardEntry);
+  }
+  if (configFormat === "yaml_standard") {
+    return setYamlServerEntry(content, configPath, serversKey, standardEntry);
+  }
+  const entry = buildEntry(
+    normalizedEntry.command,
+    normalizedEntry.args,
+    configFormat,
+    normalizedEntry.env
+  );
+  return setJsoncServerEntry(content, configPath, serversKey, entry);
+}
+
+/** Write a repaired entry, keeping the keys GNO does not manage. */
+function writeRepairedEntry(
+  content: string,
+  configPath: string,
+  configFormat: McpConfigFormat,
+  serversKey: string,
+  repaired: RepairedRegistration
+): string {
+  const hasEnv = Object.keys(repaired.env).length > 0;
+  if (configFormat === "codex_toml") {
+    return setTomlServerEntry(
+      content,
+      configPath,
+      { command: repaired.command, args: repaired.args },
+      { env: repaired.env, extra: repaired.extra }
+    );
+  }
+  if (configFormat === "mcp") {
+    return setJsoncServerEntry(content, configPath, serversKey, {
+      type: "local",
+      enabled: true,
+      ...repaired.extra,
+      command: [repaired.command, ...repaired.args],
+      ...(hasEnv ? { environment: repaired.env } : {}),
+    });
+  }
+  const entry = {
+    ...repaired.extra,
+    command: repaired.command,
+    args: repaired.args,
+    ...(hasEnv ? { env: repaired.env } : {}),
   };
+  return configFormat === "yaml_standard"
+    ? setYamlServerEntry(content, configPath, serversKey, entry)
+    : setJsoncServerEntry(content, configPath, serversKey, entry);
 }
 
 /**
@@ -200,6 +304,14 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
     opts.configPath ?? paths.configFile,
     opts.cwd
   );
+  // Only what the user passed overrides an existing entry under --force;
+  // the defaults above never do.
+  const explicit: ExplicitInstallValues = {
+    ...(opts.indexName !== undefined ? { indexName } : {}),
+    ...(opts.configPath !== undefined ? { configPath } : {}),
+    ...(toolProfile !== undefined ? { toolProfile } : {}),
+    ...(opts.enableWrite ? { enableWrite: true } : {}),
+  };
   const globals = safeGetGlobals();
   const json = opts.json ?? globals.json;
   const quiet = opts.quiet ?? globals.quiet;
@@ -228,11 +340,18 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
     dryRun,
     cwd: opts.cwd,
     homeDir: opts.homeDir,
+    preserveExisting: explicit,
   });
+  const launch = resolveLaunchPaths();
+  const pinnedPaths = [launch.bun, launch.entrypoint]
+    .filter((path) => path.pinned)
+    .map((path) => path.path);
 
   // Output
   if (json) {
-    process.stdout.write(`${JSON.stringify({ installed: result }, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify({ installed: { ...result, ...(pinnedPaths.length > 0 ? { pinnedPaths } : {}) } }, null, 2)}\n`
+    );
     return;
   }
 
@@ -247,8 +366,9 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
       `Would ${dryRunVerb} gno in ${getTargetDisplayName(target)}:\n`
     );
     process.stdout.write(`  Config: ${result.configPath}\n`);
-    process.stdout.write(`  Command: ${serverEntry.command}\n`);
-    process.stdout.write(`  Args: ${serverEntry.args.join(" ")}\n`);
+    process.stdout.write(`  Command: ${result.serverEntry.command}\n`);
+    process.stdout.write(`  Args: ${result.serverEntry.args.join(" ")}\n`);
+    writePinNote(pinnedPaths);
     return;
   }
 
@@ -256,8 +376,23 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
   process.stdout.write(
     `${verb} gno MCP server in ${getTargetDisplayName(target)}.\n`
   );
-  process.stdout.write(`  Config: ${result.configPath}\n\n`);
+  process.stdout.write(`  Config: ${result.configPath}\n`);
+  if (result.repaired) {
+    process.stdout.write(
+      "  Kept the existing settings; updated the Bun and GNO paths.\n"
+    );
+  }
+  writePinNote(pinnedPaths);
   process.stdout.write(
-    `Restart ${getTargetDisplayName(target)} to load the server.\n`
+    `\nRestart ${getTargetDisplayName(target)} to load the server.\n`
   );
 }
+
+/** Say when a launch path stays on one installed version. */
+function writePinNote(pinnedPaths: string[]): void {
+  for (const path of pinnedPaths) {
+    process.stdout.write(
+      `  Note: ${path} is inside a versioned install directory with no version-independent link to it; this registration keeps using that version after an upgrade. Run gno mcp install --force again after upgrading (gno doctor reports it).\n`
+    );
+  }
+}

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,
+  };
+}