rovecode 0.4.0-beta.2 → 0.4.0

package/src/mcp/local-package.ts

@@ -0,0 +1,211 @@
+/** Install-once for MCP servers the market would otherwise launch with `npx -y <package>`.
+ *
+ *  Why this exists, in numbers (Windows 11, node 24, npm 11, the memory and filesystem servers, medians of
+ *  3–5 runs through McpManager, measured 2026-09-06): a warm `npx -y` takes 1.8–2.1 s from spawn to the
+ *  initialize handshake; the same package installed once and launched with `node <its bin>` takes
+ *  0.35–0.47 s. The difference is npx itself — `npx --version` alone is 0.6 s, and every warm launch still
+ *  asks registry.npmjs.org to revalidate the package (0.3–1.3 s, and no network means a timeout path). A
+ *  cold cache is 7 s and a 47 MB download, repeated whenever upstream publishes, because `-y <package>`
+ *  means "latest". The one-time install is ~6 s and ~30 MB for two servers sharing one SDK copy.
+ *
+ *  What it is NOT: silent, or the only path. The human is asked, in the plan they approve, and "no" leaves
+ *  the npx line exactly as it is today. Installing code is a bigger act than writing a config line, and
+ *  the plan says so in those words. The record in installed.json carries the package name, the version
+ *  that landed and npm's integrity hash from the lockfile — an install that is recorded is auditable; an
+ *  `npx -y` that runs whatever "latest" is at every start is not.
+ *
+ *  Where: one shared prefix, `~/.rovecode/mcp/`, with its own package.json so npm never mistakes a parent
+ *  folder for the project. N servers share one node_modules and one SDK copy. The launch line is `node`
+ *  plus the ABSOLUTE path of the package's bin — never the .cmd shim (it means cmd.exe and its quoting),
+ *  and the path survives a space because it is one argv entry, not a shell string. */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { McpServerConfig } from "./config.ts";
+import type { MarketInstall } from "./market.ts";
+
+export type Spawn = (cmd: string[], cwd: string) => Promise<{ code: number; stderr: string }>;
+
+/** the package an `npx …` launch line runs, taken apart */
+export interface NpxPackage {
+  /** the package name, `@scope/name` or `name` */
+  name: string;
+  /** what npx was given: name, or `name@version` when the catalog pinned one */
+  spec: string;
+  /** the pinned version, when the spec carried one */
+  version?: string;
+  /** the arguments the SERVER receives — everything after the package spec */
+  rest: string[];
+}
+
+const NPX_FLAGS_NO_VALUE = new Set(["-y", "--yes", "-q", "--quiet", "--no-install", "--prefer-offline", "--prefer-online"]);
+/** `@scope/name`, `name`, optionally `@version` — a registry package and nothing else (no git URL, no tarball, no path) */
+const PACKAGE_SPEC = /^(@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)(?:@([^@\s/]+))?$/;
+
+/** The package a stdio `npx` launch runs, or undefined when the line is not a plain `npx [flags] <package>
+ *  [args]` — an `npx -p x cmd`, a git URL or a tarball is left to npx, since we cannot say what we would be
+ *  installing. Undefined means "no offer", never an error: the npx line still works. */
+export function npxPackage(install: MarketInstall): NpxPackage | undefined {
+  if (install.kind !== "stdio" || install.runtime !== "npx" || install.command !== "npx") return undefined;
+  let i = 0;
+  while (i < install.args.length && install.args[i]!.startsWith("-")) {
+    if (!NPX_FLAGS_NO_VALUE.has(install.args[i]!)) return undefined; // a flag with a value (-p, --package, -c): not our shape
+    i += 1;
+  }
+  const spec = install.args[i];
+  if (spec === undefined) return undefined;
+  const m = PACKAGE_SPEC.exec(spec);
+  if (!m) return undefined;
+  const out: NpxPackage = { name: m[1]!, spec, rest: install.args.slice(i + 1) };
+  if (m[2] !== undefined) out.version = m[2];
+  return out;
+}
+
+/** the shared prefix every install-once server lives in */
+export function localPrefix(home: string): string { return join(home, "mcp"); }
+
+/** what landed on disk, read back after npm finished — the record's source of truth */
+export interface LocalPackage {
+  name: string;
+  version: string;
+  /** ABSOLUTE path of the package's bin script — what `node` runs */
+  bin: string;
+  /** npm's integrity hash for the tarball, from package-lock.json */
+  integrity?: string;
+  /** the tarball URL npm resolved, from package-lock.json */
+  resolved?: string;
+  /** what could not be recorded and why — an empty list is the normal case. Written into installed.json
+   *  as it is, so a record with a hole says where the hole is instead of leaving a field silently absent. */
+  missing: string[];
+}
+
+export interface InstallLocalDeps {
+  /** how `npm install` runs — tests inject one that writes a fake node_modules and never touches the network */
+  spawn?: Spawn;
+}
+
+const defaultSpawn: Spawn = async (cmd, cwd) => {
+  const p = Bun.spawn(cmd, { cwd, stdout: "ignore", stderr: "pipe", stdin: "ignore" });
+  return { code: await p.exited, stderr: await new Response(p.stderr).text() };
+};
+
+/** the exact argv `installLocalPackage` runs — exported so the plan can show it verbatim */
+export function npmInstallArgv(pkg: NpxPackage, prefix: string): string[] {
+  return ["npm", "install", "--prefix", prefix, "--save", "--no-fund", "--no-audit", "--loglevel=error", pkg.spec];
+}
+
+/** Run `npm install` for one package into the shared prefix, then read back what landed. Never throws for
+ *  an npm failure — the caller shows the error and nothing has been written to mcp.json yet. */
+export async function installLocalPackage(pkg: NpxPackage, prefix: string, deps: InstallLocalDeps = {}): Promise<{ ok: true; pkg: LocalPackage } | { ok: false; error: string }> {
+  const spawn = deps.spawn ?? defaultSpawn;
+  try {
+    mkdirSync(prefix, { recursive: true });
+    // a package.json of its own, so npm treats the prefix as the project: without one it can walk up and
+    // install into whatever package.json it finds above ~/.rovecode
+    const manifest = join(prefix, "package.json");
+    if (!existsSync(manifest)) {
+      writeFileSync(manifest, JSON.stringify({ name: "rovecode-mcp-servers", private: true, description: "MCP servers installed once by rovecode's market — launched with node, not npx (docs/mcp-market.md)" }, null, 2) + "\n");
+    }
+    const r = await spawn(npmInstallArgv(pkg, prefix), prefix);
+    if (r.code !== 0) return { ok: false, error: `npm install ${pkg.spec} failed (exit ${r.code})${r.stderr.trim() ? `: ${r.stderr.trim().split("\n").slice(-3).join(" · ")}` : ""}` };
+  } catch (e) {
+    return { ok: false, error: `npm install ${pkg.spec} could not run: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  return readLocalPackage(pkg.name, prefix);
+}
+
+/** What is on disk for one package under the prefix: version and bin from its package.json, integrity from
+ *  the lockfile. `ok: false` when the package or its bin is not there — then there is nothing to launch. */
+export function readLocalPackage(name: string, prefix: string): { ok: true; pkg: LocalPackage } | { ok: false; error: string } {
+  const dir = join(prefix, "node_modules", ...name.split("/"));
+  const manifestPath = join(dir, "package.json");
+  if (!existsSync(manifestPath)) return { ok: false, error: `npm reported success but ${manifestPath} is not there` };
+  let manifest: Record<string, unknown>;
+  try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>; }
+  catch (e) { return { ok: false, error: `${manifestPath}: ${e instanceof Error ? e.message : String(e)}` }; }
+  const version = typeof manifest.version === "string" ? manifest.version : undefined;
+  if (version === undefined) return { ok: false, error: `${manifestPath} states no version` };
+  const binRel = binOf(name, manifest.bin);
+  if (binRel === undefined) return { ok: false, error: `${name} declares no bin — there is nothing for node to run; npx would have failed the same way` };
+  const bin = resolve(dir, binRel);
+  if (!existsSync(bin)) return { ok: false, error: `${name}'s bin ${bin} is not on disk` };
+  const missing: string[] = [];
+  const lock = lockEntry(prefix, name, missing);
+  const pkg: LocalPackage = { name, version, bin, missing };
+  if (lock?.integrity !== undefined) pkg.integrity = lock.integrity;
+  if (lock?.resolved !== undefined) pkg.resolved = lock.resolved;
+  return { ok: true, pkg };
+}
+
+/** the bin a package declares: a string, or a map — the entry named like the package, else the only one */
+function binOf(name: string, bin: unknown): string | undefined {
+  if (typeof bin === "string") return bin;
+  if (typeof bin !== "object" || bin === null) return undefined;
+  const entries = Object.entries(bin as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === "string");
+  if (entries.length === 0) return undefined;
+  const short = name.split("/").pop()!;
+  return (entries.find(([k]) => k === short) ?? entries[0]!)[1];
+}
+
+/** package-lock.json (lockfileVersion 2/3) → the entry for `node_modules/<name>`. Every way it can fall
+ *  short is written into `missing` in words, because a silent undefined here becomes a record that looks
+ *  complete and is not. */
+function lockEntry(prefix: string, name: string, missing: string[]): { integrity?: string; resolved?: string } | undefined {
+  const lockPath = join(prefix, "package-lock.json");
+  if (!existsSync(lockPath)) { missing.push(`integrity: ${lockPath} was not written by npm`); return undefined; }
+  let lock: unknown;
+  try { lock = JSON.parse(readFileSync(lockPath, "utf8")); }
+  catch { missing.push(`integrity: ${lockPath} is not valid JSON`); return undefined; }
+  const packages = typeof lock === "object" && lock !== null ? (lock as { packages?: unknown }).packages : undefined;
+  if (typeof packages !== "object" || packages === null) { missing.push(`integrity: ${lockPath} has no "packages" map (lockfileVersion 1?)`); return undefined; }
+  const entry = (packages as Record<string, unknown>)[`node_modules/${name}`];
+  if (typeof entry !== "object" || entry === null) { missing.push(`integrity: ${lockPath} has no entry for node_modules/${name}`); return undefined; }
+  const e = entry as { integrity?: unknown; resolved?: unknown };
+  const out: { integrity?: string; resolved?: string } = {};
+  if (typeof e.integrity === "string") out.integrity = e.integrity; else missing.push(`integrity: the lockfile entry for ${name} carries no integrity field`);
+  if (typeof e.resolved === "string") out.resolved = e.resolved;
+  return out;
+}
+
+/** the mcp.json launch line for an installed package: `node` + the bin's absolute path + the server's own
+ *  arguments. One argv entry per item — a path with a space in it is still one argument, because nothing
+ *  here goes through a shell (mcp/client.ts spawns with shell: false). */
+export function localLaunch(pkg: LocalPackage, rest: string[]): { command: "node"; args: string[] } {
+  return { command: "node", args: [pkg.bin, ...rest] };
+}
+
+/** the launch line as the plan can show it BEFORE the install: the bin's exact filename is read from the
+ *  package after npm has put it there, so the preview names the folder and marks the file as pending */
+export function plannedLaunchLabel(pkg: NpxPackage, prefix: string): string {
+  return ["node", `${join(prefix, "node_modules", ...pkg.name.split("/"))}${process.platform === "win32" ? "\\" : "/"}<its bin, read after the install>`, ...pkg.rest].join(" ");
+}
+
+/** the plan rows that say what installing once means — every word the human should read before the yes */
+export function localPlanLines(pkg: NpxPackage, prefix: string): string[] {
+  return [
+    `  installs   ${npmInstallArgv(pkg, prefix).join(" ")}`,
+    `             rovecode runs a package manager for you here. npm downloads ${pkg.spec} and everything it depends`,
+    `             on and puts their CODE on this machine, under ${prefix} — typically 20–30 MB and a few seconds, once.`,
+    `             In return the server starts in ~0.4 s instead of ~2 s and needs no network to start.`,
+    `             Requires npm (it comes with Node.js, as npx does).`,
+    `  records    package name, version and npm's integrity hash in installed.json — what ran is on record`,
+    `             (an npx line runs whatever "latest" is at every start, and records nothing)`,
+  ];
+}
+
+/** a configured server that still launches through npx — the rows `mcp list` may offer the install-once line for */
+export function launchesViaNpx(server: McpServerConfig): boolean {
+  return server.transport === "stdio" && server.command === "npx" && server.enabled !== false;
+}
+
+/** the one-line offer `mcp list` prints under the rows when some of them start through npx. Says what
+ *  changes, what it costs and that nothing happens until the human runs the command — no config is
+ *  rewritten by a listing. */
+export function npxOfferLine(names: string[]): string | undefined {
+  if (names.length === 0) return undefined;
+  const n = names.length;
+  // `<catalog name>`, not the server name the row shows: `mcp add` takes the name you installed it by (a
+  // registry server is `io.github.acme/widgets`, its row is `widgets`), and a renamed one needs its `--as` back
+  return `${n} server${n === 1 ? "" : "s"} start${n === 1 ? "s" : ""} through npx, which re-resolves the package at every start (~2 s each): ${names.join(", ")}. `
+    + `To start in ~0.4 s, reinstall with \`rovecode mcp add <catalog name> --local --force\` (the name you installed it by; add \`--as <server name>\` if you renamed it; installs the package once, ~25 MB). Nothing changes until you do.`;
+}

package/src/mcp/market-catalog.ts

@@ -0,0 +1,84 @@
+/** The curated half of the MCP market: servers we have looked at, from publishers we can name, with
+ *  the exact launch line spelled out. Offline by design — `rovecode mcp search` answers from this list
+ *  before it asks the registry, and /mcp with an empty query shows only this list. Rules for an entry:
+ *  the publisher is the org that owns the package or the host; secrets travel by environment variable
+ *  (or a header for a remote), never as an argument; anything OAuth-only is left out because our http
+ *  transport carries a header, not a browser flow. Keep it short — this is a shelf, not a mirror. */
+
+import type { MarketEntry } from "./market.ts";
+
+const npx = (pkg: string, ...rest: string[]): string[] => ["-y", pkg, ...rest];
+
+export const CURATED: readonly MarketEntry[] = [
+  { key: "filesystem", title: "Filesystem", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "Read, write, search and move files under the directories you name.",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@modelcontextprotocol/server-filesystem"), env: [], pending: ["<directory the server may touch>"] }] },
+  { key: "memory", title: "Memory", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "A knowledge graph the model can remember across sessions with (entities, relations, observations).",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@modelcontextprotocol/server-memory"), env: [], pending: [] }] },
+  { key: "sequential-thinking", title: "Sequential Thinking", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "A scratchpad tool for step-by-step reasoning with revisions and branches.",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@modelcontextprotocol/server-sequential-thinking"), env: [], pending: [] }] },
+  { key: "everything", title: "Everything (test server)", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "Exercises every MCP feature — prompts, resources, sampling, progress. For testing a client, not for work.",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@modelcontextprotocol/server-everything"), env: [], pending: [] }] },
+  { key: "fetch", title: "Fetch", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "Fetch a URL and hand the page back as markdown (Python; needs uv).",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "uvx", command: "uvx", args: ["mcp-server-fetch"], env: [], pending: [] }] },
+  { key: "git", title: "Git", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "Read and search git repositories: log, diff, show, status (Python; needs uv).",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "uvx", command: "uvx", args: ["mcp-server-git"], env: [], pending: [] }] },
+  { key: "time", title: "Time", source: "curated", publisher: "modelcontextprotocol (Anthropic)",
+    description: "Current time and timezone conversion (Python; needs uv).",
+    repository: "https://github.com/modelcontextprotocol/servers",
+    installs: [{ kind: "stdio", runtime: "uvx", command: "uvx", args: ["mcp-server-time"], env: [], pending: [] }] },
+  { key: "github", title: "GitHub", source: "curated", publisher: "GitHub",
+    description: "Issues, pull requests, code search and Actions on GitHub — remote with a personal access token, or the official image via docker.",
+    repository: "https://github.com/github/github-mcp-server",
+    installs: [
+      { kind: "http", url: "https://api.githubcopilot.com/mcp/", headers: [{ name: "Authorization", template: "Bearer {GITHUB_PAT}", required: true, secret: true, description: "a GitHub personal access token" }] },
+      { kind: "stdio", runtime: "docker", command: "docker", args: ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+        env: [{ name: "GITHUB_PERSONAL_ACCESS_TOKEN", required: true, secret: true, description: "a GitHub personal access token" }], pending: [] },
+    ] },
+  { key: "playwright", title: "Playwright", source: "curated", publisher: "Microsoft",
+    description: "Drive a real browser through accessibility snapshots: navigate, click, type, screenshot.",
+    repository: "https://github.com/microsoft/playwright-mcp",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@playwright/mcp@latest"), env: [], pending: [] }] },
+  { key: "context7", title: "Context7", source: "curated", publisher: "Upstash",
+    description: "Up-to-date library documentation and code examples for the versions you actually use.",
+    repository: "https://github.com/upstash/context7",
+    installs: [
+      { kind: "http", url: "https://mcp.context7.com/mcp", headers: [{ name: "CONTEXT7_API_KEY", required: false, secret: true, description: "optional API key for higher limits" }] },
+      { kind: "stdio", runtime: "npx", command: "npx", args: npx("@upstash/context7-mcp"), env: [{ name: "CONTEXT7_API_KEY", required: false, secret: true, description: "optional API key for higher limits" }], pending: [] },
+    ] },
+  { key: "brave-search", title: "Brave Search", source: "curated", publisher: "Brave",
+    description: "Web, news, image and local search through the Brave Search API.",
+    repository: "https://github.com/brave/brave-search-mcp-server",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("@brave/brave-search-mcp-server"), env: [{ name: "BRAVE_API_KEY", required: true, secret: true, description: "Brave Search API key" }], pending: [] }] },
+  { key: "firecrawl", title: "Firecrawl", source: "curated", publisher: "Firecrawl (Mendable)",
+    description: "Scrape, crawl and extract structured data from websites.",
+    repository: "https://github.com/mendableai/firecrawl-mcp-server",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("firecrawl-mcp"), env: [{ name: "FIRECRAWL_API_KEY", required: true, secret: true, description: "Firecrawl API key" }], pending: [] }] },
+  { key: "tavily", title: "Tavily", source: "curated", publisher: "Tavily",
+    description: "Search and extract built for agents: web search, page extraction, site crawl.",
+    repository: "https://github.com/tavily-ai/tavily-mcp",
+    installs: [{ kind: "stdio", runtime: "npx", command: "npx", args: npx("tavily-mcp"), env: [{ name: "TAVILY_API_KEY", required: true, secret: true, description: "Tavily API key" }], pending: [] }] },
+  { key: "exa", title: "Exa", source: "curated", publisher: "Exa",
+    description: "Neural web search and page contents for AI; the remote works without a key at a low rate.",
+    repository: "https://github.com/exa-labs/exa-mcp-server",
+    installs: [{ kind: "http", url: "https://mcp.exa.ai/mcp", headers: [] }] },
+  { key: "deepwiki", title: "DeepWiki", source: "curated", publisher: "Cognition (Devin)",
+    description: "Ask questions about any public GitHub repository, answered from its generated wiki. No key.",
+    homepage: "https://docs.devin.ai/work-with-devin/deepwiki-mcp",
+    installs: [{ kind: "http", url: "https://mcp.deepwiki.com/mcp", headers: [] }] },
+  { key: "cloudflare-docs", title: "Cloudflare Docs", source: "curated", publisher: "Cloudflare",
+    description: "Search Cloudflare's developer documentation. No key.",
+    repository: "https://github.com/cloudflare/mcp-server-cloudflare",
+    installs: [{ kind: "http", url: "https://docs.mcp.cloudflare.com/mcp", headers: [] }] },
+];

package/src/mcp/market-install.ts

@@ -0,0 +1,289 @@
+/** From a market entry to a line in mcp.json — in three visible steps, so no install is silent:
+ *  planInstall picks the launch form and lists what must be asked; describePlan renders EXACTLY what
+ *  will be written (command + args or URL, source, publisher, version, the env NAMES, the file) for the
+ *  human to read before answering; fillPlan + writeServer put it on disk. Secrets: asked by name through
+ *  the caller's masked prompt, written as values only into the USER file (~/.rovecode/mcp.json, 0o600
+ *  where the OS honours it) — a PROJECT file gets `${NAME}` and the loader fills it from the environment
+ *  at launch (config.ts expandVars), so a token never lands in a repo. Never on the command line: a
+ *  stdio server receives them through `env`, docker through `-e NAME`. */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isRecord, mcpConfigFiles, normalizeEntry, parseConfigFile, placeholderHoles, type McpServerConfig } from "./config.ts";
+import type { EnvSpec, MarketEntry, MarketInstall } from "./market.ts";
+import { installLabel } from "./market.ts";
+import { mcpTrustStatus, trustMcpFile } from "./trust.ts";
+import { localPlanLines, localPrefix, npxPackage, plannedLaunchLabel, type NpxPackage } from "./local-package.ts";
+
+export type McpScope = "user" | "project";
+const SERVER_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_-]*)\}/g;
+
+export interface InstallPlan {
+  entry: MarketEntry;
+  install: MarketInstall;
+  scope: McpScope;
+  /** the mcp.json this lands in */
+  file: string;
+  /** the server's name in that file (= the tool prefix the model sees) */
+  name: string;
+  /** what has to be asked, in order; `secret` ones go through the masked prompt */
+  asks: EnvSpec[];
+  /** required arguments nobody can fill for the human (a directory, a database URL) */
+  pending: string[];
+  /** where a header placeholder maps back: variable name → header it belongs to */
+  headerVars: Record<string, string>;
+  /** install ONCE (mcp/local-package.ts): the npx package this line would run, and the shared prefix npm
+   *  puts it in. Set only when the human asked for it — the default plan is today's npx line. The launch
+   *  line written to the file is then `node <bin>`, known after npm has run, so fillPlan takes it as an
+   *  argument instead of reading it from `install`. */
+  local?: { pkg: NpxPackage; prefix: string };
+}
+
+/** the server name a registry key gets in mcp.json: its last path segment, lowercased, unsafe runs → "-" */
+export function defaultServerName(key: string): string {
+  const tail = key.split("/").pop() ?? key;
+  const name = tail.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").slice(0, 64);
+  return name.length > 0 ? name : "server";
+}
+
+/** env-variable-safe spelling of a header name: `X-Api-Key` → `X_API_KEY` */
+function headerVar(name: string): string { return name.toUpperCase().replace(/[^A-Z0-9_]/g, "_").replace(/^[0-9]/, "_$&"); }
+
+export interface PlanOptions {
+  scope: McpScope; cwd: string; home: string;
+  /** which of entry.installs (default: the first) */
+  pick?: number;
+  /** override the mcp.json name */
+  name?: string;
+  /** install the npx package once and launch it with node (the human said yes to the offer). An error when
+   *  the chosen form is not a plain `npx <package>` line — silently falling back to npx would write a plan
+   *  the human did not approve. */
+  local?: boolean;
+}
+
+export function planInstall(entry: MarketEntry, opts: PlanOptions): InstallPlan | { error: string } {
+  if (entry.installs.length === 0) return { error: `${entry.key} lists nothing rovecode can launch or connect to (no stdio package, no streamable-http remote)` };
+  const ix = opts.pick ?? 0;
+  const install = entry.installs[ix];
+  if (!install) return { error: `${entry.key} has ${entry.installs.length} install form(s); --pick ${ix} is out of range` };
+  const name = opts.name ?? (entry.source === "curated" ? entry.key : defaultServerName(entry.key));
+  if (!SERVER_NAME.test(name)) return { error: `"${name}" is not a usable server name (lowercase letters, digits, . _ -)` };
+  const files = mcpConfigFiles(opts.cwd, opts.home);
+  const file = opts.scope === "project" ? files.project : files.user!;
+  let local: InstallPlan["local"];
+  if (opts.local === true) {
+    // The launch line install-once writes is THIS machine's absolute path under its ROVECODE_HOME. A project
+    // file is shared with everyone who clones the repo, so that line would be a server none of them can start
+    // — refused with the way out, rather than written and discovered on someone else's machine.
+    if (opts.scope === "project") return { error: `${entry.key}: install-once writes this machine's absolute path (node <home>/mcp/…), and a project file is shared with every clone — install it in user scope (drop --project) or keep the npx line` };
+    const pkg = npxPackage(install);
+    if (pkg === undefined) return { error: `${entry.key} cannot be installed once: its launch line is not a plain \`npx <package>\` (${installLabel(install)}) — drop --local to write it as it is` };
+    local = { pkg, prefix: localPrefix(opts.home) };
+  }
+  const asks: EnvSpec[] = [], headerVars: Record<string, string> = {};
+  if (install.kind === "stdio") {
+    for (const e of install.env) {
+      // a filled default is not a question; an optional plain value without one is left out and named in the preview
+      if (e.default !== undefined) continue;
+      if (e.secret || e.required) asks.push(e);
+    }
+  } else {
+    for (const h of install.headers) {
+      const vars = [...(h.template ?? "").matchAll(PLACEHOLDER)].map((m) => m[1]!);
+      if (h.template !== undefined && vars.length === 0) continue; // a literal header, nothing to ask
+      for (const v of vars.length ? vars : [headerVar(h.name)]) {
+        headerVars[v] = h.name;
+        const spec: EnvSpec = { name: v, required: h.required, secret: h.secret };
+        if (h.description) spec.description = h.description;
+        asks.push(spec);
+      }
+    }
+  }
+  return { entry, install, scope: opts.scope, file, name, asks, pending: install.kind === "stdio" ? install.pending : [], headerVars, ...(local ? { local } : {}) };
+}
+
+/** One `pending` fragment → the argv words it contributes. A fragment is literal words followed by one
+ *  `<hole>` — "--root <path>" or "<directory the server may touch>" — so the flag survives whether or not
+ *  anybody answered, and the hole is either the answer or the placeholder itself. Written into the file
+ *  unanswered it is not a silent failure: mcp/config.ts refuses to launch a server that still carries one
+ *  and names the line. Split on the hole rather than on whitespace, because a hole is usually a sentence. */
+export function pendingWords(fragment: string, answer?: string): string[] {
+  const m = /^(.*?)\s*(<[^<>]*>)\s*$/.exec(fragment);
+  const filled = answer !== undefined && answer.length > 0;
+  if (!m) return [filled ? answer : fragment];          // no hole at all: an older catalog's bare hint
+  const lead = m[1]!.length > 0 ? m[1]!.split(/\s+/) : [];
+  return [...lead, filled ? answer : m[2]!];
+}
+
+/** the raw mcp.json entry, with answers in place. Secrets: a value in the USER file, `${NAME}` in a
+ *  PROJECT file (and `${NAME}` whenever the answer is empty, so a later `export NAME=…` completes it).
+ *  `launch` replaces the entry's own command + args — the install-once path passes `node <bin>` here once
+ *  npm has put the bin on disk (local-package.ts localLaunch); a plan without `local` never sets it. */
+export function fillPlan(plan: InstallPlan, answers: Record<string, string>, launch?: { command: string; args: string[] }): Record<string, unknown> {
+  const ref = (spec: EnvSpec): string | undefined => {
+    const v = answers[spec.name];
+    if (v !== undefined && v.length > 0 && !(spec.secret && plan.scope === "project")) return v;
+    if (v === undefined || v.length === 0) { if (!spec.required && !(v !== undefined && spec.secret)) return undefined; }
+    return `\${${spec.name}}`;
+  };
+  const { install } = plan;
+  if (install.kind === "stdio") {
+    const env: Record<string, string> = {};
+    for (const e of install.env) {
+      if (e.default !== undefined) { env[e.name] = e.default; continue; }
+      const v = ref(e);
+      if (v !== undefined) env[e.name] = v;
+    }
+    // `pending` is the entry's required positional arguments — the filesystem server's directory, say.
+    // They go into args either as the human's answer or, when nobody could be asked (the TUI has no
+    // prompt, `--yes` did not stop), as the placeholder itself. Dropping them, which is what this did
+    // first, wrote a server that could never start and a note pointing at a line that was not there.
+    const positional = install.pending.flatMap((p) => pendingWords(p, answers[p]));
+    const line = launch ?? { command: install.command, args: install.args };
+    return { command: line.command, args: [...line.args, ...positional], ...(Object.keys(env).length ? { env } : {}) };
+  }
+  const headers: Record<string, string> = {};
+  for (const h of install.headers) {
+    if (h.template !== undefined && !PLACEHOLDER.test(h.template)) { headers[h.name] = h.template; PLACEHOLDER.lastIndex = 0; continue; }
+    PLACEHOLDER.lastIndex = 0;
+    const vars = Object.entries(plan.headerVars).filter(([, hn]) => hn === h.name).map(([v]) => v);
+    let value = h.template ?? `{${vars[0] ?? headerVar(h.name)}}`, complete = true;
+    for (const v of vars) {
+      const spec = plan.asks.find((a) => a.name === v)!;
+      const r = ref(spec);
+      if (r === undefined) { complete = false; break; }
+      value = value.split(`{${v}}`).join(r);
+    }
+    if (complete) headers[h.name] = value;
+  }
+  return { type: "http", url: install.url, ...(Object.keys(headers).length ? { headers } : {}) };
+}
+
+/** the asks whose `${NAME}` the filled entry actually carries — what the closing note tells the human to set.
+ *  An optional ask nobody answered is left out of the entry (fillPlan), so naming it would send them to set a
+ *  variable nothing reads. */
+export function namesWritten(plan: InstallPlan, raw: Record<string, unknown>): string[] {
+  const text = JSON.stringify(raw);
+  return plan.asks.filter((a) => text.includes(`\${${a.name}}`)).map((a) => a.name);
+}
+
+/** the confirmation text — everything the human must see before anything is written. `asking` says how
+ *  the plan's questions get answered: "prompt" (the CLI asks, secrets masked) or "env" (the TUI has no
+ *  masked input, so every asked value is written as `${NAME}` and read from the environment at launch) */
+export function describePlan(plan: InstallPlan, asking: "prompt" | "env" = "prompt"): string[] {
+  const { entry, install } = plan;
+  const asked = (secret: boolean): string => asking === "env" ? "(${NAME} — from your environment)" : secret ? "(asked, masked, never shown)" : "(asked)";
+  const lines = [
+    `${entry.title ?? entry.key}${entry.version ? ` ${entry.version}` : ""}${entry.status ? `  [${entry.status}]` : ""}`,
+    `  source     ${entry.source === "curated" ? "curated list (built into rovecode)" : "MCP registry (registry.modelcontextprotocol.io)"}`,
+    `  publisher  ${entry.publisher ?? "unknown"}`,
+  ];
+  if (entry.repository) lines.push(`  repo       ${entry.repository}`);
+  // install-once: the launch line the file will hold is `node <bin>`, and the rows under it say — in so many
+  // words — that a package manager runs and code lands on this machine. That is the plan being approved.
+  if (plan.local) lines.push(`  runs       ${plannedLaunchLabel(plan.local.pkg, plan.local.prefix)}`, ...localPlanLines(plan.local.pkg, plan.local.prefix));
+  else lines.push(install.kind === "stdio" ? `  runs       ${installLabel(install)}` : `  connects   ${install.url}`);
+  const envNames = install.kind === "stdio" ? install.env : [];
+  for (const e of envNames) {
+    const how = e.default !== undefined ? `= ${e.default}` : plan.asks.includes(e) ? asked(e.secret).replace("NAME", e.name) : "(optional, left unset)";
+    lines.push(`  env        ${e.name} ${how}${e.required ? "" : "  optional"}`);
+  }
+  if (install.kind === "http") for (const h of install.headers) {
+    const vars = Object.entries(plan.headerVars).filter(([, hn]) => hn === h.name).map(([v]) => v);
+    lines.push(`  header     ${h.name}: ${vars.length ? `${h.template ?? `{${vars[0]}}`}  ← ${vars.join(", ")} ${asked(h.secret).replace("NAME", vars[0]!)}` : h.template ?? ""}${h.required ? "" : "  optional"}`);
+  }
+  for (const p of plan.pending) lines.push(`  needs      ${p} — ${asking === "env" ? "written as the placeholder; fill it in and the server connects" : "asked here; unanswered it is written as the placeholder"}`);
+  lines.push(`  writes     ${plan.file}  as "${plan.name}"${asking === "prompt" && plan.scope === "project" && plan.asks.some((a) => a.secret) ? "  (secrets stay out of this file: ${NAME} is read from your environment)" : ""}`);
+  return lines;
+}
+
+// ------------------------------------------------------------------ the file
+
+interface FileShape { json: Record<string, unknown>; servers: Record<string, unknown> }
+function readShape(file: string): FileShape {
+  if (!existsSync(file)) return { json: {}, servers: {} };
+  const json: unknown = JSON.parse(readFileSync(file, "utf8")); // a broken file is the human's to fix; we do not overwrite it
+  if (!isRecord(json)) throw new Error(`${file}: root is not an object`);
+  const servers = isRecord(json.mcpServers) ? json.mcpServers : {};
+  return { json, servers };
+}
+function writeShape(file: string, shape: FileShape, secret: boolean): void {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify({ ...shape.json, mcpServers: shape.servers }, null, 2) + "\n", { mode: 0o600 });
+  if (secret && process.platform !== "win32") chmodSync(file, 0o600);
+}
+
+/** add or replace one server; the entry is normalized first (every `${NAME}` counted as set) so the
+ *  runtime is guaranteed to accept what was written. Returns the loader's view of it. `trustHome`: the
+ *  human just approved this exact content on a card/prompt, so a PROJECT file is recorded as trusted in
+ *  that home's store right after the write (mcp/trust.ts) — the "trust my own" half of the gate. */
+export function writeServer(file: string, name: string, raw: Record<string, unknown>, opts: { replace?: boolean; trustHome?: string } = {}): McpServerConfig & { trusted?: boolean } {
+  const warnings: string[] = [];
+  // allowPlaceholders: this validates the SHAPE of an entry the human just approved, and an unanswered
+  // `pending` hole is part of that entry by design — writing it is how the human gets a line to edit. The
+  // loader (parseConfigFile) applies the same check without the exemption, so the server is named and
+  // skipped until it is filled rather than launched into an argument error.
+  const cfg = normalizeEntry(name, raw, file, warnings, new Proxy({}, { get: () => "set" }) as Record<string, string>, { allowPlaceholders: true });
+  if (!cfg) throw new Error(warnings.join("; ") || `${name}: not a valid server entry`);
+  const shape = readShape(file);
+  if (shape.servers[name] !== undefined && !opts.replace) throw new Error(`${file} already has a server named "${name}" — remove it first, or add --force`);
+  // the human approved THIS entry. The rest of the file is approved only if it already was (or there was
+  // no file): adding to a cloned, unapproved file must not quietly bless the strangers already in it.
+  const mayTrust = opts.trustHome !== undefined && (!existsSync(file) || Object.keys(shape.servers).filter((k) => k !== name).length === 0 || mcpTrustStatus(opts.trustHome, file) === "trusted");
+  shape.servers[name] = raw;
+  const secret = JSON.stringify(raw).includes("env") || JSON.stringify(raw).includes("headers");
+  writeShape(file, shape, secret);
+  if (opts.trustHome === undefined) return cfg;
+  if (mayTrust) trustMcpFile(opts.trustHome, file);
+  return { ...cfg, trusted: mayTrust };
+}
+
+/** delete one server; with `trustHome` the file's new bytes stay approved when the file was approved
+ *  before (a removal is the human's edit too) — an unapproved file stays unapproved */
+export function removeServer(file: string, name: string, opts: { trustHome?: string } = {}): boolean {
+  if (!existsSync(file)) return false;
+  const wasTrusted = opts.trustHome !== undefined && mcpTrustStatus(opts.trustHome, file) === "trusted";
+  const shape = readShape(file);
+  if (shape.servers[name] === undefined) return false;
+  delete shape.servers[name];
+  writeShape(file, shape, false);
+  if (wasTrusted) trustMcpFile(opts.trustHome!, file);
+  return true;
+}
+
+/** one configured server on one line, NAMES of env/headers only — never their values (they may be keys) */
+export function serverLine(s: McpServerConfig): string {
+  const what = s.transport === "stdio" ? [s.command, ...(s.args ?? [])].join(" ") : s.url ?? "";
+  const env = s.env && Object.keys(s.env).length ? `  env ${Object.keys(s.env).join(", ")}` : "";
+  const headers = s.headers && Object.keys(s.headers).length ? `  headers ${Object.keys(s.headers).join(", ")}` : "";
+  // an entry the loader will skip until a hand edits it says so on its own line — it is configured, not launchable
+  const holes = placeholderHoles(s);
+  const fill = holes.length ? `  (fill in ${holes.join(", ")})` : "";
+  return `${s.name.padEnd(24)} ${s.transport.padEnd(5)} ${what}${env}${headers}${fill}${s.enabled === false ? "  (disabled)" : ""}`;
+}
+
+/** every configured server with the scope it comes from, most local last — what the files SAY, which is
+ *  more than what the runtime would load: an entry still carrying a `<…>` placeholder is kept (serverLine
+ *  marks it), because the person who was told "fill in the directory after the install" and typed the
+ *  command the docs point at must not be told they have nothing. The loader's own view (skipping such an
+ *  entry with a warning) is loadMcpConfig. `warnings` collects what parsing had to say — an unreadable
+ *  file, invalid JSON, a nameless entry — for the caller to show; it used to be discarded here. */
+export function configuredServers(cwd: string, home: string, warnings: string[] = []): { scope: McpScope | "harvest"; file: string; server: McpServerConfig }[] {
+  const files = mcpConfigFiles(cwd, home);
+  const all = new Proxy({}, { get: () => "set" }) as Record<string, string>; // list what is configured, not what is launchable right now
+  const out: { scope: McpScope | "harvest"; file: string; server: McpServerConfig }[] = [];
+  for (const [scope, file] of [["user", files.user!], ["harvest", files.harvest], ["project", files.project]] as const) {
+    for (const server of parseConfigFile(file, warnings, all, { allowPlaceholders: true })) out.push({ scope, file, server });
+  }
+  return out;
+}
+
+/** The `pending` fragments of a plan whose placeholder is STILL in the written entry — nobody answered for
+ *  them at the prompt (no terminal, or an empty answer). What the closing line of an install must name, and
+ *  only that: a question answered at the prompt must not leave the install telling you to go and edit a line
+ *  that now holds your answer. */
+export function unfilledPending(plan: InstallPlan, raw: Record<string, unknown>): string[] {
+  const args = Array.isArray(raw.args) ? (raw.args as unknown[]) : [];
+  return plan.pending.filter((p) => pendingWords(p).some((w) => /^<.*>$/.test(w) && args.includes(w)));
+}