cue-ai 0.5.0 → 0.7.0

package/src/lib/skill-subset.ts

@@ -0,0 +1,166 @@
+/**
+ * Smart skill subsetting: given a profile's skill list and a user prompt,
+ * ask Claude which skills are plausibly relevant. The intent is to cut context
+ * bloat in `cue launch` for sessions that only need 3-4 of N skills.
+ *
+ * Design rules:
+ *   1. **Fail open.** Any error path returns the original list unchanged.
+ *      Smart-subset is an optimization, not a gate. Never make `cue launch`
+ *      slower than today on the failure path.
+ *   2. **Single Claude call.** All skills + prompt in one --print invocation.
+ *      One round-trip cost (~$0.001, ~2s) regardless of profile size.
+ *   3. **Always keep "core" essentials.** A handful of skills (caveman,
+ *      analyze, cue-usage) are operational primitives — never prune them
+ *      even if the classifier doesn't pick them.
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { findRealClaudeBin } from "./claude-binary";
+import { resolveLocalSkill } from "./resolver-local";
+import { parseMetadataFromContent } from "../commands/optimizer";
+
+// Skills that survive every subset filter. They're operational, not domain-
+// specific, and pruning them changes how the agent behaves more than it
+// changes what it can do.
+const ALWAYS_KEEP = new Set([
+  "meta/analyze",
+  "meta/cue-usage",
+  "meta/acpx",
+  "caveman/caveman",
+  "caveman/caveman-commit",
+]);
+
+export interface SubsetResult {
+  /** Skill IDs the classifier picked (plus ALWAYS_KEEP). Same ordering as input. */
+  selected: string[];
+  /** True if classification ran; false if we fell back to the original list. */
+  classified: boolean;
+  /** One-line reason — useful for the user-facing message. */
+  reason: string;
+}
+
+interface SkillDescriptor {
+  id: string;
+  description: string;
+}
+
+async function loadSkillDescriptor(id: string): Promise<SkillDescriptor> {
+  try {
+    const dir = await resolveLocalSkill(id);
+    const md = join(dir, "SKILL.md");
+    if (!existsSync(md)) return { id, description: "" };
+    const meta = parseMetadataFromContent(readFileSync(md, "utf8"));
+    return { id, description: meta.description };
+  } catch {
+    return { id, description: "" };
+  }
+}
+
+function buildPrompt(prompt: string, descriptors: SkillDescriptor[]): string {
+  const lines = descriptors.map((d, i) => `${i + 1}. ${d.id}${d.description ? ` — ${d.description}` : ""}`);
+  return `You are choosing which skills to load for a Claude Code session. Each skill is a chunk of system-prompt context; loading every skill costs tokens. Pick only the ones plausibly relevant to the user's first prompt.
+
+User prompt:
+${prompt}
+
+Available skills:
+${lines.join("\n")}
+
+Respond in EXACTLY this format (no other text):
+KEEP: <comma-separated skill IDs from the list above, or "none">
+REASON: <one short sentence>
+
+Rules:
+- Pick 3-8 skills, never more than half the list.
+- If the prompt is generic ("help", "what can you do"), respond KEEP: none.
+- If unsure, KEEP fewer skills. The user can always load more by retrying.`;
+}
+
+function callClaude(prompt: string, timeoutMs: number): { ok: boolean; output: string } {
+  const tryOne = (bin: string) => spawnSync(bin, ["--print", "-p", prompt], {
+    encoding: "utf8",
+    timeout: timeoutMs,
+    env: { ...process.env, CUE_BYPASS: "1" },
+  });
+
+  let res = tryOne("claude");
+  if (res.status !== 0 || !res.stdout?.trim()) {
+    const fallback = findRealClaudeBin();
+    if (fallback) res = tryOne(fallback);
+  }
+  if (res.status !== 0 || !res.stdout?.trim()) return { ok: false, output: "" };
+  return { ok: true, output: res.stdout.trim() };
+}
+
+function parseClaudeKeep(output: string, allSkillIds: string[]): string[] | null {
+  const m = output.match(/KEEP:\s*(.+)/i);
+  if (!m) return null;
+  const raw = m[1]!.trim();
+  if (/^none$/i.test(raw)) return [];
+  const known = new Set(allSkillIds);
+  const picked = raw.split(",").map(s => s.trim()).filter(s => s && known.has(s));
+  // Sanity check: if Claude returned nothing usable, signal a parse failure
+  // rather than an empty selection.
+  return picked.length === 0 ? null : picked;
+}
+
+/**
+ * Returns the subset of `skillIds` relevant to `prompt`. ALWAYS_KEEP skills
+ * are always included. If anything goes wrong (no claude binary, timeout,
+ * unparseable response), returns the original list unchanged with classified=false.
+ */
+export async function selectRelevantSkills(
+  skillIds: string[],
+  prompt: string,
+  opts: { timeoutMs?: number; minKeep?: number } = {},
+): Promise<SubsetResult> {
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const minKeep = opts.minKeep ?? 3;
+  const trimmed = prompt.trim();
+
+  if (!trimmed) {
+    return { selected: skillIds, classified: false, reason: "empty prompt — kept all skills" };
+  }
+  // Very short prompts don't have enough signal to classify well.
+  if (trimmed.length < 8) {
+    return { selected: skillIds, classified: false, reason: `prompt too short (${trimmed.length} chars) — kept all skills` };
+  }
+  if (skillIds.length <= 4) {
+    return { selected: skillIds, classified: false, reason: `only ${skillIds.length} skills — nothing to subset` };
+  }
+
+  const descriptors = await Promise.all(skillIds.map(loadSkillDescriptor));
+  const claudePrompt = buildPrompt(trimmed, descriptors);
+  const { ok, output } = callClaude(claudePrompt, timeoutMs);
+  if (!ok) {
+    return { selected: skillIds, classified: false, reason: "claude --print unavailable — kept all skills" };
+  }
+
+  const picked = parseClaudeKeep(output, skillIds);
+  if (picked === null) {
+    return { selected: skillIds, classified: false, reason: "could not parse classifier output — kept all skills" };
+  }
+
+  const keepSet = new Set(picked);
+  for (const id of skillIds) if (ALWAYS_KEEP.has(id)) keepSet.add(id);
+
+  if (keepSet.size < minKeep) {
+    return { selected: skillIds, classified: false, reason: `classifier picked < ${minKeep} skills — kept all` };
+  }
+
+  // Preserve original ordering.
+  const selected = skillIds.filter(id => keepSet.has(id));
+  const reasonMatch = output.match(/REASON:\s*(.+)/i);
+  const why = reasonMatch?.[1]?.trim().slice(0, 100) ?? "relevance ranking";
+  return {
+    selected,
+    classified: true,
+    reason: `${selected.length}/${skillIds.length} skills kept — ${why}`,
+  };
+}
+
+// Exported for tests.
+export const __test = { parseClaudeKeep, buildPrompt, ALWAYS_KEEP };

package/src/lib/star-prompt.ts

@@ -11,7 +11,7 @@ import { spawnSync } from "node:child_process";
 const CONFIG_DIR = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cue");
 const FLAG_FILE = join(CONFIG_DIR, ".star-prompted");
 const ANALYTICS_FILE = join(CONFIG_DIR, "analytics.jsonl");
-const REPO = "recodeee/cue";
+const REPO = "opencue/cue";
 const SESSION_THRESHOLD = 10;
 
 export async function maybePromptStar(): Promise<void> {

package/src/lib/uvx-installer.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, test } from "bun:test";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { normalizeUvxGitServers } from "./uvx-installer";
+import type { McpServerConfig } from "./runtime-materializer";
+
+const localBin = (b: string) => join(homedir(), ".local", "bin", b);
+
+const stubs = (overrides: {
+  binExists?: (b: string) => boolean;
+  uvOnPath?: () => boolean;
+  install?: (gitUrl: string, binary: string) => { ok: boolean; stderr: string };
+  seedAssets?: (gitUrl: string, binary: string, assets: string[]) => string[];
+}) => ({
+  binExists: overrides.binExists ?? (() => false),
+  uvOnPath: overrides.uvOnPath ?? (() => true),
+  install: overrides.install ?? (() => ({ ok: true, stderr: "" })),
+  seedAssets: overrides.seedAssets ?? (() => []),
+  warn: () => { /* swallow */ },
+});
+
+describe("normalizeUvxGitServers", () => {
+  test("passes non-uvx entries through unchanged", () => {
+    const servers: Record<string, McpServerConfig> = {
+      drawio: { command: "npx", args: ["-y", "@drawio/mcp"] },
+      gbrain: { command: "~/.local/bin/gbrain.sh" },
+    };
+    const { normalized, report } = normalizeUvxGitServers(servers, stubs({}));
+    expect(normalized).toEqual(servers);
+    expect(report).toEqual({ installed: [], reused: [], skipped: [], seeded: [] });
+  });
+
+  test("passes uvx entries without git+ source through unchanged", () => {
+    const servers: Record<string, McpServerConfig> = {
+      pypi: { command: "uvx", args: ["--from", "trendradar-mcp", "trendradar-mcp"] },
+    };
+    const { normalized, report } = normalizeUvxGitServers(servers, stubs({}));
+    expect(normalized).toEqual(servers);
+    expect(report.installed).toEqual([]);
+    expect(report.reused).toEqual([]);
+  });
+
+  test("rewrites git+ entry to local binary when already installed", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+        env: { FOO: "bar" },
+      },
+    };
+    const calls: string[] = [];
+    const { normalized, report } = normalizeUvxGitServers(servers, stubs({
+      binExists: (b) => { calls.push(`exists:${b}`); return true; },
+      install: () => { throw new Error("install should not be called when binary exists"); },
+    }));
+    expect(normalized.trendradar).toEqual({
+      command: localBin("trendradar-mcp"),
+      args: [],
+      env: { FOO: "bar" },
+    });
+    expect(report.reused).toEqual(["trendradar"]);
+    expect(report.installed).toEqual([]);
+    expect(calls).toEqual(["exists:trendradar-mcp"]);
+  });
+
+  test("installs missing binary and rewrites entry", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+        env: {},
+      },
+    };
+    let installCalled: { gitUrl?: string; binary?: string } = {};
+    const { normalized, report } = normalizeUvxGitServers(servers, stubs({
+      binExists: () => false,
+      install: (gitUrl, binary) => {
+        installCalled = { gitUrl, binary };
+        return { ok: true, stderr: "" };
+      },
+    }));
+    expect(installCalled).toEqual({
+      gitUrl: "git+https://github.com/sansan0/TrendRadar.git",
+      binary: "trendradar-mcp",
+    });
+    expect(normalized.trendradar.command).toBe(localBin("trendradar-mcp"));
+    expect(normalized.trendradar.args).toEqual([]);
+    expect(report.installed).toEqual(["trendradar"]);
+  });
+
+  test("falls back to raw uvx when uv is missing", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+      },
+    };
+    const warnings: string[] = [];
+    const { normalized, report } = normalizeUvxGitServers(servers, {
+      binExists: () => false,
+      uvOnPath: () => false,
+      install: () => { throw new Error("install should not be called when uv missing"); },
+      warn: (m) => warnings.push(m),
+    });
+    expect(normalized.trendradar).toEqual(servers.trendradar);
+    expect(report.skipped).toEqual([{ id: "trendradar", reason: "uv-missing" }]);
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain("uv");
+  });
+
+  test("falls back to raw uvx when install fails", () => {
+    const servers: Record<string, McpServerConfig> = {
+      bad: {
+        command: "uvx",
+        args: ["--from", "git+https://example.invalid/x.git", "bad-mcp"],
+      },
+    };
+    const warnings: string[] = [];
+    const { normalized, report } = normalizeUvxGitServers(servers, {
+      binExists: () => false,
+      uvOnPath: () => true,
+      install: () => ({ ok: false, stderr: "fatal: repository not found" }),
+      warn: (m) => warnings.push(m),
+    });
+    expect(normalized.bad).toEqual(servers.bad);
+    expect(report.skipped).toEqual([{ id: "bad", reason: "install-failed" }]);
+    expect(warnings[0]).toContain("repository not found");
+  });
+
+  test("preserves extra uvx args around --from", () => {
+    const servers: Record<string, McpServerConfig> = {
+      x: {
+        command: "uvx",
+        args: ["--python", "3.12", "--from", "git+https://example.com/x.git", "x-mcp", "--verbose"],
+      },
+    };
+    const { normalized } = normalizeUvxGitServers(servers, stubs({ binExists: () => true }));
+    expect(normalized.x.command).toBe(localBin("x-mcp"));
+    // Pre-`--from` and post-binary args are preserved (order: pre then post).
+    expect(normalized.x.args).toEqual(["--python", "3.12", "--verbose"]);
+  });
+
+  test("seeds repo-root assets after fresh install for known git URLs", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+      },
+    };
+    const seedCalls: { gitUrl: string; binary: string; assets: string[] }[] = [];
+    const { report } = normalizeUvxGitServers(servers, stubs({
+      binExists: () => false,
+      install: () => ({ ok: true, stderr: "" }),
+      seedAssets: (gitUrl, binary, assets) => {
+        seedCalls.push({ gitUrl, binary, assets });
+        return assets; // pretend we copied all of them
+      },
+    }));
+    expect(seedCalls).toEqual([{
+      gitUrl: "git+https://github.com/sansan0/TrendRadar.git",
+      binary: "trendradar-mcp",
+      assets: ["config"],
+    }]);
+    expect(report.seeded).toEqual([{ id: "trendradar", assets: ["config"] }]);
+  });
+
+  test("heals existing install missing repo-root assets on reuse path", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+      },
+    };
+    const { report } = normalizeUvxGitServers(servers, stubs({
+      binExists: () => true, // binary already on disk
+      seedAssets: (_gitUrl, _binary, assets) => assets, // assets were missing, now copied
+    }));
+    expect(report.reused).toEqual(["trendradar"]);
+    expect(report.seeded).toEqual([{ id: "trendradar", assets: ["config"] }]);
+  });
+
+  test("does not seed when git URL is not in the asset table", () => {
+    const servers: Record<string, McpServerConfig> = {
+      other: {
+        command: "uvx",
+        args: ["--from", "git+https://example.com/other.git", "other-mcp"],
+      },
+    };
+    let seedCalled = false;
+    const { report } = normalizeUvxGitServers(servers, stubs({
+      binExists: () => true,
+      seedAssets: () => { seedCalled = true; return []; },
+    }));
+    expect(seedCalled).toBe(false);
+    expect(report.seeded).toEqual([]);
+  });
+
+  test("does not record seed when seeder copies nothing (assets already present)", () => {
+    const servers: Record<string, McpServerConfig> = {
+      trendradar: {
+        command: "uvx",
+        args: ["--from", "git+https://github.com/sansan0/TrendRadar.git", "trendradar-mcp"],
+      },
+    };
+    const { report } = normalizeUvxGitServers(servers, stubs({
+      binExists: () => true,
+      seedAssets: () => [], // nothing copied — already healthy
+    }));
+    expect(report.seeded).toEqual([]);
+  });
+
+  test("only spawns uv once for many git+ entries", () => {
+    const servers: Record<string, McpServerConfig> = {
+      a: { command: "uvx", args: ["--from", "git+https://example.com/a.git", "a"] },
+      b: { command: "uvx", args: ["--from", "git+https://example.com/b.git", "b"] },
+      c: { command: "uvx", args: ["--from", "git+https://example.com/c.git", "c"] },
+    };
+    let uvChecks = 0;
+    normalizeUvxGitServers(servers, {
+      binExists: () => true, // skip install path
+      uvOnPath: () => { uvChecks++; return true; },
+      install: () => ({ ok: true, stderr: "" }),
+      warn: () => { /* swallow */ },
+    });
+    // All entries hit the binExists fast path, so uvOnPath shouldn't be touched.
+    expect(uvChecks).toBe(0);
+  });
+});

package/src/lib/uvx-installer.ts

@@ -0,0 +1,278 @@
+/**
+ * uvx-installer — normalize `uvx --from git+<repo> <binary>` MCP entries to a
+ * locally-installed binary.
+ *
+ * Why this exists
+ *   Two problems with the raw `uvx --from git+...` shape inside an MCP entry:
+ *     1. First-launch cold start does a network download. MCP startup has a
+ *        short handshake timeout, so the server often races and gets reaped
+ *        before registering tools.
+ *     2. Claude Code's auto-mode bash classifier blocks the same command when
+ *        the model tries to probe it (`uvx --from git+<url>` is treated as
+ *        "fetch and execute arbitrary code from an unverified URL").
+ *
+ * Fix
+ *   At materialize time, run `uv tool install --from <git-url> <binary>` once
+ *   (idempotent) and rewrite the runtime entry to invoke `~/.local/bin/<binary>`
+ *   directly. Subsequent session starts are a plain local exec — no network,
+ *   no classifier flag.
+ *
+ * Failure modes (warn + leave entry untouched, never throw)
+ *   - `uv` missing from PATH       → tell the user to install uv.
+ *   - `uv tool install` non-zero   → print stderr, fall back to raw uvx.
+ *   Both keep the profile working on machines where the optimization can't
+ *   be applied; only the first-launch race + classifier annoyance persist.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, realpathSync, rmSync, readdirSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import type { McpServerConfig } from "./runtime-materializer";
+
+/**
+ * Repo-root assets to seed into the venv's site-packages after `uv tool install`.
+ *
+ * Some upstream packages (e.g. TrendRadar) ship runtime config at the repo root
+ * rather than inside the python package. `uv tool install` only copies the
+ * package, so the binary then fails at startup looking for `<site-packages>/X/`.
+ * For each known git URL, we sparse-clone the listed top-level dirs and copy
+ * them next to the installed package. Idempotent: skipped if target exists.
+ */
+const REPO_ROOT_ASSETS: Record<string, string[]> = {
+  "git+https://github.com/sansan0/TrendRadar.git": ["config"],
+};
+
+export interface NormalizeReport {
+  /** Entries we just installed via `uv tool install` and rewrote. */
+  installed: string[];
+  /** Entries whose binary was already on disk — just rewrote. */
+  reused: string[];
+  /** Entries we left alone, with why. */
+  skipped: { id: string; reason: "uv-missing" | "install-failed" }[];
+  /** Entries whose repo-root assets we just seeded into site-packages. */
+  seeded: { id: string; assets: string[] }[];
+}
+
+interface ParsedUvxGit {
+  gitUrl: string;
+  binary: string;
+  /** Any args before `--from` or after the binary slot — preserved on rewrite. */
+  extraArgs: string[];
+}
+
+/** Recognize the shape `uvx [pre...] --from git+<url> <binary> [post...]`. */
+function parseUvxGit(cfg: McpServerConfig): ParsedUvxGit | null {
+  if (cfg.command !== "uvx") return null;
+  const args = cfg.args ?? [];
+  const fromIdx = args.indexOf("--from");
+  if (fromIdx < 0 || fromIdx + 2 >= args.length) return null;
+  const gitUrl = args[fromIdx + 1]!;
+  if (!gitUrl.startsWith("git+")) return null;
+  const binary = args[fromIdx + 2]!;
+  if (!binary || binary.startsWith("-")) return null;
+  return {
+    gitUrl,
+    binary,
+    extraArgs: [...args.slice(0, fromIdx), ...args.slice(fromIdx + 3)],
+  };
+}
+
+function uvOnPathDefault(): boolean {
+  const res = spawnSync("uv", ["--version"], { stdio: "ignore" });
+  return res.status === 0;
+}
+
+function localBinPath(binary: string): string {
+  return join(homedir(), ".local", "bin", binary);
+}
+
+function installBinaryDefault(
+  gitUrl: string,
+  _binary: string,
+): { ok: boolean; stderr: string } {
+  // `uv tool install <git-url>` installs whatever package the URL declares and
+  // links every `[project.scripts]` entry into ~/.local/bin/. We deliberately
+  // do NOT pass `--from <url> <bin>` — uv enforces install-name == package-name
+  // in that mode, which breaks when the binary name (e.g. `trendradar-mcp`)
+  // differs from the package name (`trendradar`).
+  const res = spawnSync(
+    "uv",
+    ["tool", "install", gitUrl],
+    { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 180_000 },
+  );
+  if (res.status === 0) return { ok: true, stderr: "" };
+  return { ok: false, stderr: (res.stderr ?? "").toString().trim() };
+}
+
+/**
+ * Default seeder: sparse-clones `gitUrl` and copies each repo-root `asset` dir
+ * into the site-packages of the venv that owns `binary`. No-op for any asset
+ * already present. Returns the list of asset names actually copied.
+ */
+function seedRepoRootAssetsDefault(
+  gitUrl: string,
+  binary: string,
+  assets: string[],
+): string[] {
+  const seeded: string[] = [];
+  const sitePackages = resolveSitePackages(binary);
+  if (!sitePackages) return seeded;
+
+  const missing = assets.filter((a) => !existsSync(join(sitePackages, a)));
+  if (missing.length === 0) return seeded;
+
+  const cloneUrl = gitUrl.startsWith("git+") ? gitUrl.slice("git+".length) : gitUrl;
+  const tmp = mkdtempSync(join(tmpdir(), "cue-uvx-seed-"));
+  try {
+    const clone = spawnSync(
+      "git",
+      ["clone", "--depth=1", "--filter=blob:none", "--sparse", cloneUrl, "repo"],
+      { cwd: tmp, stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 120_000 },
+    );
+    if (clone.status !== 0) return seeded;
+
+    const sparse = spawnSync(
+      "git",
+      ["-C", "repo", "sparse-checkout", "set", ...missing],
+      { cwd: tmp, stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 60_000 },
+    );
+    if (sparse.status !== 0) return seeded;
+
+    for (const asset of missing) {
+      const src = join(tmp, "repo", asset);
+      if (!existsSync(src)) continue;
+      cpSync(src, join(sitePackages, asset), { recursive: true });
+      seeded.push(asset);
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+  return seeded;
+}
+
+/**
+ * Find the site-packages dir for a `uv tool install`-ed binary by resolving the
+ * symlink at ~/.local/bin/<binary> and walking up to the venv's
+ * lib/python<X.Y>/site-packages/. Returns null if anything is off.
+ */
+function resolveSitePackages(binary: string): string | null {
+  const linkPath = localBinPath(binary);
+  if (!existsSync(linkPath)) return null;
+  let real: string;
+  try {
+    real = realpathSync(linkPath);
+  } catch {
+    return null;
+  }
+  // real = <venv>/bin/<binary> → venv root is two dirs up.
+  const venvRoot = dirname(dirname(real));
+  const libDir = join(venvRoot, "lib");
+  if (!existsSync(libDir)) return null;
+  let entries: string[];
+  try {
+    entries = readdirSync(libDir);
+  } catch {
+    return null;
+  }
+  const pyDir = entries.find((e) => e.startsWith("python"));
+  if (!pyDir) return null;
+  const sp = join(libDir, pyDir, "site-packages");
+  return existsSync(sp) ? sp : null;
+}
+
+export interface NormalizeOptions {
+  install?: (gitUrl: string, binary: string) => { ok: boolean; stderr: string };
+  binExists?: (binary: string) => boolean;
+  uvOnPath?: () => boolean;
+  warn?: (msg: string) => void;
+  /** Seed repo-root assets into the venv's site-packages. Returns names copied. */
+  seedAssets?: (gitUrl: string, binary: string, assets: string[]) => string[];
+}
+
+/**
+ * Normalize MCP server entries in-place (functionally — returns a new map).
+ *
+ * Pure-ish: the only side effects are (optionally) spawning `uv` subprocesses
+ * and writing to the warn sink. Tests inject mocks via {@link NormalizeOptions}.
+ */
+export function normalizeUvxGitServers(
+  servers: Record<string, McpServerConfig>,
+  opts: NormalizeOptions = {},
+): { normalized: Record<string, McpServerConfig>; report: NormalizeReport } {
+  const install = opts.install ?? installBinaryDefault;
+  const binExists = opts.binExists ?? ((b) => existsSync(localBinPath(b)));
+  const uvOnPath = opts.uvOnPath ?? uvOnPathDefault;
+  const warn = opts.warn ?? ((m) => process.stderr.write(`[cue] ${m}\n`));
+  const seedAssets = opts.seedAssets ?? seedRepoRootAssetsDefault;
+
+  const report: NormalizeReport = { installed: [], reused: [], skipped: [], seeded: [] };
+  const normalized: Record<string, McpServerConfig> = {};
+
+  const trySeed = (id: string, gitUrl: string, binary: string): void => {
+    const assets = REPO_ROOT_ASSETS[gitUrl];
+    if (!assets || assets.length === 0) return;
+    const copied = seedAssets(gitUrl, binary, assets);
+    if (copied.length > 0) report.seeded.push({ id, assets: copied });
+  };
+
+  let uvCache: boolean | null = null;
+  const checkUv = () => {
+    if (uvCache === null) uvCache = uvOnPath();
+    return uvCache;
+  };
+
+  for (const [id, cfg] of Object.entries(servers)) {
+    const parsed = parseUvxGit(cfg);
+    if (!parsed) {
+      normalized[id] = cfg;
+      continue;
+    }
+    const { gitUrl, binary, extraArgs } = parsed;
+    const binPath = localBinPath(binary);
+
+    const rewrite = (): McpServerConfig => ({
+      ...cfg,
+      command: binPath,
+      args: extraArgs,
+    });
+
+    if (binExists(binary)) {
+      report.reused.push(id);
+      trySeed(id, gitUrl, binary);
+      normalized[id] = rewrite();
+      continue;
+    }
+
+    if (!checkUv()) {
+      warn(
+        `MCP "${id}": uvx git+ source detected but \`uv\` is not on PATH. ` +
+          `Leaving entry as raw \`uvx --from git+...\` — first session may time out ` +
+          `during cold download. Install uv (https://docs.astral.sh/uv/) and re-run ` +
+          `\`cue switch\` to enable the local-binary fast path.`,
+      );
+      report.skipped.push({ id, reason: "uv-missing" });
+      normalized[id] = cfg;
+      continue;
+    }
+
+    const { ok, stderr } = install(gitUrl, binary);
+    if (!ok) {
+      warn(
+        `MCP "${id}": \`uv tool install ${gitUrl}\` failed (looking for binary "${binary}").\n  ${
+          stderr || "(no stderr)"
+        }\nLeaving entry as raw \`uvx --from git+...\`.`,
+      );
+      report.skipped.push({ id, reason: "install-failed" });
+      normalized[id] = cfg;
+      continue;
+    }
+
+    report.installed.push(id);
+    trySeed(id, gitUrl, binary);
+    normalized[id] = rewrite();
+  }
+
+  return { normalized, report };
+}