rovecode 0.3.2 → 0.4.0-beta.2

package/src/mcp/market-install.ts

@@ -1,289 +0,0 @@
-/** 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

@@ -1,362 +0,0 @@
-/** 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;
-}