rovecode 0.3.2

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

package/src/mcp/market.ts

@@ -0,0 +1,362 @@
+/** The MCP market: where `rovecode mcp search|info|add` and the TUI's /mcp find servers to install.
+ *  Two sources, merged: the built-in curated list (market-catalog.ts, offline, hand-checked) and the
+ *  official registry at registry.modelcontextprotocol.io. Registry responses are UNTRUSTED DATA: every
+ *  field is re-typed here, every string is capped, every list is capped, and nothing from a response is
+ *  ever executed, evaluated or written to a config file without the human seeing it first
+ *  (market-install.ts owns the preview + write). Responses are cached under ~/.rovecode/cache/
+ *  mcp-market.json with a TTL so a flaky network or an offline train still leaves /mcp usable.
+ *
+ *  Registry API, verified live on 2026-09-04 (the shape is NOT assumed from docs):
+ *    GET /v0/servers?search=<substring of name>&version=latest&limit=<=100[&cursor=]
+ *      → { servers: [{ server: ServerJson, _meta: { "io.modelcontextprotocol.registry/official": { status, isLatest, … } } }],
+ *          metadata: { nextCursor?, count } }
+ *    GET /v0/servers/<url-encoded name>/versions/latest → { server: ServerJson, _meta }
+ *    ServerJson: { name, description, title?, version, repository?: { url, source, subfolder? }, websiteUrl?,
+ *      packages?: [{ registryType: npm|pypi|oci|nuget|mcpb, identifier, version?, runtimeHint?, transport: { type },
+ *                    runtimeArguments?: Arg[], packageArguments?: Arg[], environmentVariables?: Var[] }],
+ *      remotes?: [{ type: streamable-http|sse, url, headers?: Var[] }] }
+ *    Arg: { type: positional|named, name?, value?, default?, isRequired?, valueHint?, description? }
+ *    Var: { name, value?, default?, isRequired?, isSecret?, description? } — `value` may hold "{placeholder}"s. */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+import { isRecord, message } from "./config.ts";
+import { CURATED } from "./market-catalog.ts";
+
+export const REGISTRY_URL = "https://registry.modelcontextprotocol.io/v0";
+/** cache TTL: a day — registry entries change rarely and the human sees the version before installing */
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_QUERIES = 40;
+/** the registry's detail route has been seen taking >8s from here; a CLI can wait this long once, the cache does the rest */
+const FETCH_TIMEOUT_MS = 20_000;
+/** hard ceilings on what a response may contribute — anything past them is dropped, never trusted */
+export const LIMITS = { body: 2 * 1024 * 1024, servers: 100, str: 300, desc: 500, list: 32, packages: 8 } as const;
+
+/** one environment variable (or header placeholder) a server wants; `secret` ones are asked masked */
+export interface EnvSpec { name: string; description?: string; required: boolean; secret: boolean; default?: string }
+/** one HTTP header a remote wants; `{name}` placeholders in `template` are asked as EnvSpecs */
+export interface HeaderSpec { name: string; template?: string; description?: string; required: boolean; secret: boolean }
+export type MarketInstall =
+  | { kind: "stdio"; runtime: "npx" | "uvx" | "docker" | "other"; command: string; args: string[]; env: EnvSpec[];
+      /** required arguments the registry could not fill (a path, a token on the command line): named for the human */
+      pending: string[] }
+  | { kind: "http"; url: string; headers: HeaderSpec[] };
+
+export interface MarketEntry {
+  /** what `mcp add <key>` takes: the curated short name, or the registry's reverse-DNS name */
+  key: string;
+  title?: string;
+  description: string;
+  version?: string;
+  source: "curated" | "registry";
+  /** who publishes it — a curated entry says so, a registry entry derives it from its namespace */
+  publisher?: string;
+  /** the registry's listing status when it is anything but active (e.g. "deprecated") */
+  status?: string;
+  repository?: string;
+  homepage?: string;
+  installs: MarketInstall[];
+}
+
+export interface MarketDeps {
+  fetch?: typeof fetch;
+  home?: string;
+  now?: () => number;
+  catalog?: readonly MarketEntry[];
+  registryUrl?: string;
+  /** skip the network entirely (curated + cache only) */
+  offline?: boolean;
+}
+export interface MarketResult { entries: MarketEntry[]; notes: string[]; fromCache: boolean }
+
+// ------------------------------------------------------------------ validated re-typing of registry JSON
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+const COMMAND = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_-]*)\}/g;
+
+function str(v: unknown, max: number = LIMITS.str): string | undefined {
+  if (typeof v !== "string" || v.length === 0) return undefined;
+  const flat = v.replace(/[\u0000-\u001f\u007f]/g, " ");
+  return flat.length > max ? flat.slice(0, max - 1) + "…" : flat;
+}
+function list(v: unknown, max: number = LIMITS.list): unknown[] { return Array.isArray(v) ? v.slice(0, max) : []; }
+function httpUrl(v: unknown): string | undefined {
+  const s = str(v, 2000);
+  if (s === undefined) return undefined;
+  try { const u = new URL(s); return u.protocol === "http:" || u.protocol === "https:" ? s : undefined; } catch { return undefined; }
+}
+
+function envSpec(raw: unknown): EnvSpec | undefined {
+  if (!isRecord(raw)) return undefined;
+  const name = str(raw.name, 128);
+  if (name === undefined || !ENV_NAME.test(name)) return undefined;
+  const def = str(raw.value) ?? str(raw.default);
+  const out: EnvSpec = { name, required: raw.isRequired === true, secret: raw.isSecret === true };
+  const d = str(raw.description, LIMITS.desc);
+  if (d !== undefined) out.description = d;
+  if (def !== undefined && !PLACEHOLDER.test(def)) out.default = def; // a "{placeholder}" is a question, not a value
+  PLACEHOLDER.lastIndex = 0;
+  return out;
+}
+function headerSpec(raw: unknown): HeaderSpec | undefined {
+  if (!isRecord(raw)) return undefined;
+  const name = str(raw.name, 64);
+  if (name === undefined || !HEADER_NAME.test(name)) return undefined;
+  const out: HeaderSpec = { name, required: raw.isRequired === true, secret: raw.isSecret === true };
+  const t = str(raw.value) ?? str(raw.default);
+  if (t !== undefined) out.template = t;
+  const d = str(raw.description, LIMITS.desc);
+  if (d !== undefined) out.description = d;
+  return out;
+}
+
+/** the angle brackets are what marks a hole, here and in mcp/config.ts — a value already wearing them
+ *  keeps the wording the registry chose */
+function hole(hint: string): string { return hint.startsWith("<") && hint.endsWith(">") ? hint : `<${hint}>`; }
+
+/** registry Arg[] → argv words; what has no value but is required goes to `pending` for the human */
+function argWords(raws: unknown[], pending: string[]): string[] {
+  const words: string[] = [];
+  for (const raw of raws) {
+    if (!isRecord(raw)) continue;
+    const value = str(raw.value) ?? str(raw.default);
+    const name = str(raw.name, 128);
+    const hint = str(raw.valueHint, 64) ?? name ?? "<argument>";
+    if (raw.type === "named") {
+      if (name === undefined) continue;
+      if (value !== undefined) words.push(name, value);
+      // a required flag with no value is "--root <path>", not "--root": pending entries are argv
+      // FRAGMENTS the installer appends, and the <angle-bracketed> part is the hole a human fills.
+      // Appending the bare flag would write a server that launches and then rejects its own arguments.
+      else if (raw.isRequired === true) pending.push(`${name} ${hole(str(raw.valueHint, 64) ?? "value")}`);
+    } else if (value !== undefined) words.push(value);
+    else if (raw.isRequired === true) pending.push(hole(hint));
+  }
+  return words;
+}
+
+/** one registry package → a stdio install, or undefined (unsupported type, non-stdio transport, bad hint) */
+export function installFromPackage(raw: unknown, notes: string[]): MarketInstall | undefined {
+  if (!isRecord(raw)) return undefined;
+  const type = str(raw.registryType, 32), id = str(raw.identifier, 200), version = str(raw.version, 64);
+  if (type === undefined || id === undefined) return undefined;
+  const transport = isRecord(raw.transport) ? str(raw.transport.type, 32) : "stdio";
+  if (transport !== undefined && transport !== "stdio") return undefined; // an http package is "run it yourself, then connect": not an install
+  const hint = str(raw.runtimeHint, 64);
+  if (hint !== undefined && !COMMAND.test(hint)) { notes.push(`${id}: runtime hint "${hint}" refused (not a bare command name)`); return undefined; }
+  const pending: string[] = [];
+  const runtimeArgs = argWords(list(raw.runtimeArguments), pending);
+  const pkgArgs = argWords(list(raw.packageArguments), pending);
+  const env = list(raw.environmentVariables).map(envSpec).filter((e): e is EnvSpec => e !== undefined);
+  const pinned = version !== undefined && version !== "latest";
+  let command: string, args: string[], runtime: Extract<MarketInstall, { kind: "stdio" }>["runtime"];
+  switch (type) {
+    case "npm":
+      command = hint ?? "npx"; runtime = command === "npx" ? "npx" : "other";
+      args = [...(command === "npx" && !runtimeArgs.includes("-y") ? ["-y"] : []), ...runtimeArgs, pinned ? `${id}@${version}` : id, ...pkgArgs];
+      break;
+    case "pypi":
+      command = hint ?? "uvx"; runtime = command === "uvx" ? "uvx" : "other";
+      args = [...runtimeArgs, pinned ? `${id}==${version}` : id, ...pkgArgs];
+      break;
+    case "oci":
+      // docker gets `-e NAME` per variable so the value travels through the environment, never argv
+      command = hint ?? "docker"; runtime = command === "docker" ? "docker" : "other";
+      args = ["run", "-i", "--rm", ...env.flatMap((e) => ["-e", e.name]), ...runtimeArgs, pinned ? `${id}:${version}` : id, ...pkgArgs];
+      break;
+    default:
+      notes.push(`${id}: package type "${type}" is not something rovecode can launch`);
+      return undefined;
+  }
+  return { kind: "stdio", runtime, command, args, env, pending };
+}
+
+/** one registry remote → an http install, or undefined (sse is legacy and the loader refuses it anyway) */
+export function installFromRemote(raw: unknown, notes: string[] = []): MarketInstall | undefined {
+  if (!isRecord(raw)) return undefined;
+  const type = str(raw.type, 32);
+  const url = httpUrl(raw.url);
+  if (type !== "streamable-http" && type !== "http") {
+    // the human asked why nothing was written: an sse (legacy) remote is the usual answer — say so, like the package path does
+    notes.push(`${url ?? "a remote"}: ${type === "sse" ? "sse remote (legacy transport) is not something rovecode can connect to" : `remote type "${type ?? "?"}" is not something rovecode can connect to`}`);
+    return undefined;
+  }
+  if (url === undefined) return undefined;
+  return { kind: "http", url, headers: list(raw.headers).map(headerSpec).filter((h): h is HeaderSpec => h !== undefined) };
+}
+
+/** `io.github.owner/repo` → "github.com/owner"; `com.example/x` → "example.com" — the namespace the
+ *  registry verified ownership of, shown beside every registry result so the human knows who published it */
+export function publisherOf(name: string): string {
+  const ns = name.split("/")[0] ?? name;
+  if (ns.startsWith("io.github.")) return `github.com/${ns.slice("io.github.".length)}`;
+  return ns.split(".").reverse().join(".");
+}
+
+/** one `{ server, _meta }` item → a MarketEntry; undefined when it is not an active, well-formed server */
+export function entryFromRegistry(item: unknown, notes: string[]): MarketEntry | undefined {
+  if (!isRecord(item) || !isRecord(item.server)) return undefined;
+  const s = item.server;
+  const name = str(s.name, 200);
+  if (name === undefined || !/^[a-z0-9][a-z0-9.-]*\/[A-Za-z0-9._-]+$/.test(name)) return undefined;
+  // the registry's own verdict on the listing (active · deprecated · deleted): a deleted server is gone,
+  // anything else is kept WITH its status so the human sees "deprecated" before installing
+  const meta = isRecord(item._meta) ? item._meta["io.modelcontextprotocol.registry/official"] : undefined;
+  const status = isRecord(meta) ? str(meta.status, 32) : undefined;
+  if (status === "deleted") return undefined;
+  const installs: MarketInstall[] = [];
+  for (const p of list(s.packages, LIMITS.packages)) { const i = installFromPackage(p, notes); if (i) installs.push(i); }
+  for (const r of list(s.remotes, LIMITS.packages)) { const i = installFromRemote(r, notes); if (i) installs.push(i); }
+  const out: MarketEntry = { key: name, description: str(s.description, LIMITS.desc) ?? "", source: "registry", publisher: publisherOf(name), installs };
+  const title = str(s.title, 120), version = str(s.version, 64), home = httpUrl(s.websiteUrl);
+  const repo = isRecord(s.repository) ? httpUrl(s.repository.url) : undefined;
+  if (title !== undefined) out.title = title;
+  if (version !== undefined) out.version = version;
+  if (status !== undefined && status !== "active") out.status = status;
+  if (repo !== undefined) out.repository = repo;
+  if (home !== undefined) out.homepage = home;
+  return out;
+}
+
+/** a list page → entries (deduped by name, capped at LIMITS.servers) */
+/** The cursor for the NEXT page, if the registry says there is one. Kept apart from parseRegistryPage so
+ *  that function's shape (and every caller of it) stays as it was. A cursor is opaque, so it is only
+ *  length-capped and type-checked — never interpreted. */
+export function nextCursorOf(json: unknown): string | undefined {
+  if (!isRecord(json) || !isRecord(json.metadata)) return undefined;
+  const c = json.metadata.nextCursor;
+  return typeof c === "string" && c.length > 0 && c.length <= LIMITS.str ? c : undefined;
+}
+
+/** how many pages one search will follow. 5 x 50 = 250 servers is far past what a person reads, and the
+ *  ceiling matters more than the reach: a cursor loop with no bound is a request amplifier pointed at us
+ *  by whatever the registry returns. */
+export const MAX_PAGES = 5;
+
+export function parseRegistryPage(json: unknown, notes: string[]): MarketEntry[] {
+  if (!isRecord(json)) { notes.push("registry: response is not an object"); return []; }
+  const seen = new Set<string>(), out: MarketEntry[] = [];
+  for (const item of list(json.servers, LIMITS.servers)) {
+    const e = entryFromRegistry(item, notes);
+    if (e && !seen.has(e.key)) { seen.add(e.key); out.push(e); }
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ cache (~/.rovecode/cache/mcp-market.json)
+
+interface CacheFile { version: 1; queries: Record<string, { at: number; entries: MarketEntry[] }> }
+export function cachePath(home: string): string { return join(home, "cache", "mcp-market.json"); }
+
+function readCache(home: string): CacheFile {
+  const path = cachePath(home);
+  if (!existsSync(path)) return { version: 1, queries: {} };
+  try {
+    const json: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (isRecord(json) && json.version === 1 && isRecord(json.queries)) return json as unknown as CacheFile;
+  } catch { /* a broken cache is an empty cache */ }
+  return { version: 1, queries: {} };
+}
+function writeCache(home: string, cache: CacheFile): void {
+  // keep the newest CACHE_QUERIES; the file is a convenience, never a source of truth
+  const keep = Object.entries(cache.queries).sort((a, b) => b[1].at - a[1].at).slice(0, CACHE_QUERIES);
+  try {
+    mkdirSync(dirname(cachePath(home)), { recursive: true });
+    writeFileSync(cachePath(home), JSON.stringify({ version: 1, queries: Object.fromEntries(keep) }) + "\n");
+  } catch { /* read-only home: the search still answered */ }
+}
+
+// ------------------------------------------------------------------ registry client
+
+async function registryGet(path: string, deps: MarketDeps): Promise<unknown> {
+  const f = deps.fetch ?? fetch;
+  const base = deps.registryUrl ?? process.env.ROVECODE_MCP_REGISTRY ?? REGISTRY_URL;
+  const res = await f(`${base}${path}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`registry answered ${res.status}`);
+  const text = await res.text();
+  if (text.length > LIMITS.body) throw new Error(`registry response too large (${text.length} bytes)`);
+  return JSON.parse(text) as unknown;
+}
+
+/** cache-through: a fresh cached answer is served as is; otherwise the network, then the cache; a
+ *  failed network falls back to a STALE cached answer with a note, else to nothing with the reason */
+async function cached(key: string, load: () => Promise<MarketEntry[]>, deps: MarketDeps, notes: string[]): Promise<{ entries: MarketEntry[]; fromCache: boolean }> {
+  const home = deps.home ?? rovecodeHome(), now = (deps.now ?? Date.now)();
+  const cache = readCache(home), hit = cache.queries[key];
+  if (hit && now - hit.at < CACHE_TTL_MS) return { entries: hit.entries, fromCache: true };
+  if (deps.offline) { if (hit) notes.push("offline: showing cached registry results"); return { entries: hit?.entries ?? [], fromCache: hit !== undefined }; }
+  try {
+    const entries = await load();
+    cache.queries[key] = { at: now, entries };
+    writeCache(home, cache);
+    return { entries, fromCache: false };
+  } catch (err) {
+    notes.push(`registry unreachable (${message(err)})${hit ? " — showing cached results" : ""}`);
+    return { entries: hit?.entries ?? [], fromCache: hit !== undefined };
+  }
+}
+
+/** curated first (all of them for an empty query; substring on key/title/description otherwise), then
+ *  the registry's name matches for a query of two+ characters, minus anything the curated list already names */
+export async function searchMarket(query: string, deps: MarketDeps = {}): Promise<MarketResult> {
+  const notes: string[] = [];
+  const q = query.trim().toLowerCase();
+  const catalog = deps.catalog ?? CURATED;
+  const words = q.split(/\s+/).filter(Boolean);
+  const curated = catalog.filter((e) => words.every((w) => `${e.key} ${e.title ?? ""} ${e.description}`.toLowerCase().includes(w)));
+  if (q.length < 2) return { entries: curated, notes, fromCache: false };
+  const { entries, fromCache } = await cached(`search:${q}`, async () => {
+    // FOLLOW THE CURSOR. A single page was not a smaller result, it was a WRONG one: the registry answers
+    // "here are the first 50 and there is more", and stopping there tells the human their server does not
+    // exist when it is on page two. Bounded three ways — page count, total entries, and a cursor that must
+    // actually change — because a paginating client that trusts the server's cursor can be walked forever.
+    const parseNotes: string[] = [];
+    const all: MarketEntry[] = [];
+    const seenKeys = new Set<string>();   // parseRegistryPage dedupes WITHIN a page; this spans pages
+    const seenCursors = new Set<string>();
+    let cursor: string | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const url = `/servers?search=${encodeURIComponent(q)}&version=latest&limit=50${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+      const json = await registryGet(url, deps);
+      for (const e of parseRegistryPage(json, parseNotes)) {
+        if (seenKeys.has(e.key)) continue;
+        seenKeys.add(e.key);
+        all.push(e);
+      }
+      if (all.length >= LIMITS.servers) break;
+      const next = nextCursorOf(json);
+      if (next === undefined || seenCursors.has(next)) break;   // no more, or the registry is looping us
+      seenCursors.add(next);
+      cursor = next;
+    }
+    return all.slice(0, LIMITS.servers);
+  }, deps, notes);
+  const taken = new Set(curated.flatMap((e) => [e.key, ...(e.repository ? [e.repository] : [])]));
+  return { entries: [...curated, ...entries.filter((e) => !taken.has(e.key) && !(e.repository && taken.has(e.repository)))], notes, fromCache };
+}
+
+/** one entry by key: the curated one if the key is a curated short name, else the registry's latest version */
+export async function marketInfo(key: string, deps: MarketDeps = {}): Promise<{ entry?: MarketEntry; notes: string[] }> {
+  const notes: string[] = [];
+  const name = key.trim();
+  const catalog = deps.catalog ?? CURATED;
+  const hit = catalog.find((e) => e.key === name);
+  if (hit) return { entry: hit, notes };
+  if (!name.includes("/")) { notes.push(`"${name}" is not a curated name and not a registry name (those look like io.github.owner/repo) — try: rovecode mcp search ${name}`); return { notes }; }
+  const { entries } = await cached(`info:${name}`, async () => {
+    const json = await registryGet(`/servers/${encodeURIComponent(name)}/versions/latest`, deps);
+    const e = entryFromRegistry(json, notes);
+    return e ? [e] : [];
+  }, deps, notes);
+  const entry = entries[0];
+  if (!entry && notes.length === 0) notes.push(`"${name}" is not in the registry`);
+  return entry ? { entry, notes } : { notes };
+}
+
+/** what a stdio install runs / an http install connects to — one line, exact, for lists and cards */
+export function installLabel(i: MarketInstall): string {
+  return i.kind === "stdio" ? [i.command, ...i.args].join(" ") : i.url;
+}