claudeup 4.40.1 → 4.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.40.1",
+  "version": "4.42.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "claudeup-darwin-arm64": "4.40.1",
-    "claudeup-darwin-x64": "4.40.1",
-    "claudeup-linux-x64": "4.40.1"
+    "claudeup-darwin-arm64": "4.42.0",
+    "claudeup-darwin-x64": "4.42.0",
+    "claudeup-linux-x64": "4.42.0"
   }
 }

package/src/__tests__/component-badge.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+	COMPONENT_BADGE,
+	CONTRAST_REFERENCE_KEYS,
+	componentBadge,
+	resetThemeMode,
+	setThemeMode,
+} from "../ui/theme-mode.js";
+
+afterEach(() => {
+	resetThemeMode();
+});
+
+/** WCAG relative luminance of a #rrggbb string. */
+function luminance(hex: string): number {
+	const channel = (v: number) => {
+		const c = v / 255;
+		return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+	};
+	const n = Number.parseInt(hex.slice(1), 16);
+	return (
+		0.2126 * channel((n >> 16) & 0xff) +
+		0.7152 * channel((n >> 8) & 0xff) +
+		0.0722 * channel(n & 0xff)
+	);
+}
+
+function contrast(a: string, b: string): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+const KINDS = ["skill", "command", "agent", "mcp"] as const;
+
+describe("componentBadge", () => {
+	it("returns no chip when the terminal never answered the theme query", () => {
+		// Unknown means no tint, the same rule the scope bar's fill follows: a
+		// light wash guessed onto a dark page is a bright band on every row.
+		for (const kind of KINDS) {
+			expect(componentBadge(kind)).toBeNull();
+		}
+	});
+
+	it("serves the light pair on a light terminal", () => {
+		setThemeMode("light");
+
+		expect(componentBadge("skill")).toEqual(COMPONENT_BADGE.skill.light);
+		expect(componentBadge("mcp")).toEqual(COMPONENT_BADGE.mcp.light);
+	});
+
+	it("serves the dark pair on a dark terminal", () => {
+		setThemeMode("dark");
+
+		expect(componentBadge("skill")).toEqual(COMPONENT_BADGE.skill.dark);
+		expect(componentBadge("mcp")).toEqual(COMPONENT_BADGE.mcp.dark);
+	});
+
+	it("keeps every glyph legible on its own chip", () => {
+		// 3:1 is the floor the rest of the palette is measured to. A chip whose
+		// glyph disappears into its wash is worse than no chip at all.
+		for (const kind of KINDS) {
+			for (const mode of ["light", "dark"] as const) {
+				const { bg, fg } = COMPONENT_BADGE[kind][mode];
+				expect(contrast(bg, fg)).toBeGreaterThanOrEqual(3);
+			}
+		}
+	});
+
+	it("keeps every chip quiet against the page it is drawn on", () => {
+		// The wash must read as a tint of the page, not as a block on it. Above
+		// ~1.6 it stops being a chip and starts being a highlight bar.
+		for (const kind of KINDS) {
+			for (const mode of ["light", "dark"] as const) {
+				const { bg } = COMPONENT_BADGE[kind][mode];
+				const page = CONTRAST_REFERENCE_KEYS[mode];
+				expect(contrast(bg, page)).toBeLessThan(1.6);
+			}
+		}
+	});
+
+	it("mirrors the reference pages theme.ts measures accents against", async () => {
+		// The duplicate exists so this module stays free of the renderer import.
+		// If theme.ts ever restates its backgrounds, the chips must move with it.
+		const { CONTRAST_REFERENCE } = await import("../ui/theme.js");
+
+		expect(CONTRAST_REFERENCE_KEYS.light).toBe(CONTRAST_REFERENCE.light);
+		expect(CONTRAST_REFERENCE_KEYS.dark).toBe(CONTRAST_REFERENCE.dark);
+	});
+
+	it("gives each kind a distinguishable hue", () => {
+		// Single-character colour carries no readable hue *shift*, only a readable
+		// hue *difference* — the same reason the scope squares are far apart.
+		for (const mode of ["light", "dark"] as const) {
+			const fills = KINDS.map((k) => COMPONENT_BADGE[k][mode].bg);
+			expect(new Set(fills).size).toBe(KINDS.length);
+		}
+	});
+});

package/src/__tests__/component-icons.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "bun:test";
+import { COMPONENT_ICON } from "../ui/renderers/pluginRenderers.js";
+
+/**
+ * Every component badge is exactly one terminal cell wide.
+ *
+ * This is the constraint that rules out the icons the ecosystem actually uses:
+ * Cursor's skill badge defaults to a lightning bolt and the community VS Code
+ * Skills sidebar uses a sparkle, but `⚡` (U+26A1) and `✨` (U+2728) are both
+ * East-Asian-Width Wide — two cells — and a two-cell badge shifts every name on
+ * the row out of alignment with the plugin names above it.
+ *
+ * Unicode has no `east_asian_width` in the JS standard library, so the wide
+ * ranges are spelled out. They cover the emoji and CJK blocks a plausible icon
+ * would come from; anything outside them is single-width in practice.
+ */
+const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+	[0x1100, 0x115f], // Hangul Jamo
+	[0x2329, 0x232a], // angle brackets
+	[0x2e80, 0x303e], // CJK radicals, Kangxi
+	[0x3041, 0x33ff], // Hiragana through CJK compatibility
+	[0x3400, 0x4dbf], // CJK Extension A
+	[0x4e00, 0x9fff], // CJK Unified Ideographs
+	[0xa000, 0xa4cf], // Yi
+	[0xac00, 0xd7a3], // Hangul syllables
+	[0xf900, 0xfaff], // CJK compatibility ideographs
+	[0xfe30, 0xfe6f], // CJK compatibility forms
+	[0xff00, 0xff60], // fullwidth forms
+	[0xffe0, 0xffe6], // fullwidth signs
+	[0x1f300, 0x1f64f], // misc symbols and pictographs, emoticons
+	[0x1f900, 0x1f9ff], // supplemental symbols and pictographs
+	[0x20000, 0x3fffd], // CJK Extension B and beyond
+	// Individually Wide despite sitting among narrow neighbours. These are the
+	// ones that actually bite: ⚡ and ✨ are exactly the icons a future editor
+	// would reach for.
+	[0x231a, 0x231b], // watch, hourglass
+	[0x23e9, 0x23ec],
+	[0x25fd, 0x25fe],
+	[0x2614, 0x2615],
+	[0x26a1, 0x26a1], // ⚡ HIGH VOLTAGE SIGN
+	[0x2728, 0x2728], // ✨ SPARKLES
+	[0x274c, 0x274c],
+	[0x2b1b, 0x2b1c],
+	[0x2b50, 0x2b50],
+];
+
+function isWide(ch: string): boolean {
+	const cp = ch.codePointAt(0) ?? 0;
+	return WIDE_RANGES.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+
+describe("component icons", () => {
+	it("covers every component kind", () => {
+		expect(Object.keys(COMPONENT_ICON).sort()).toEqual([
+			"agent",
+			"command",
+			"mcp",
+			"skill",
+		]);
+	});
+
+	it("uses exactly one code point per icon", () => {
+		for (const [kind, icon] of Object.entries(COMPONENT_ICON)) {
+			expect([...icon], `${kind} must be a single code point`).toHaveLength(1);
+		}
+	});
+
+	it("never uses a double-width glyph", () => {
+		for (const [kind, icon] of Object.entries(COMPONENT_ICON)) {
+			expect(isWide(icon), `${kind} icon ${icon} is double-width`).toBe(false);
+		}
+	});
+
+	it("rejects the two emoji a future editor would reach for", () => {
+		// Negative control: the guard above only means something if it fires.
+		expect(isWide("⚡")).toBe(true);
+		expect(isWide("✨")).toBe(true);
+		expect(isWide("📁")).toBe(true);
+	});
+
+	it("gives each kind a distinct glyph", () => {
+		const icons = Object.values(COMPONENT_ICON);
+		expect(new Set(icons).size).toBe(icons.length);
+	});
+
+	it("does not reuse a glyph this screen already means something by", () => {
+		// ★ is "★ Official" on a marketplace row, ● is "● Installed", ■ is a scope
+		// segment, and ▼ / ▶ are the expand arrows. Reusing one would make a badge
+		// read as a status.
+		for (const taken of ["★", "●", "■", "▼", "▶", "○", "✓", "⚠"]) {
+			expect(Object.values(COMPONENT_ICON)).not.toContain(taken);
+		}
+	});
+});

package/src/__tests__/local-marketplace-scan.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import {
+	scanMcpServers,
+	scanSkillDirs,
+} from "../services/local-marketplace.js";
+import { walkMarkdown, walkSkillDirs } from "../services/skills-manager.js";
+
+/**
+ * The skill count in the plugin detail panel comes from a scan of the cloned
+ * marketplace. It used to read only the top level of `skills/`, which counts
+ * the *grouping* directories rather than the skills: dev reported 9 against 43
+ * on disk, mattpocock 5 against 37.
+ */
+describe("scanSkillDirs", () => {
+	let root: string;
+
+	beforeEach(async () => {
+		root = await fs.mkdtemp(path.join(os.tmpdir(), "claudeup-skills-"));
+	});
+
+	afterEach(async () => {
+		await fs.remove(root);
+	});
+
+	async function writeSkill(...segments: string[]): Promise<void> {
+		const dir = path.join(root, ...segments);
+		await fs.ensureDir(dir);
+		await fs.writeFile(path.join(dir, "SKILL.md"), "---\nname: x\n---\n");
+	}
+
+	it("counts skills nested under grouping directories", async () => {
+		await writeSkill("skills", "frontend", "design-system");
+		await writeSkill("skills", "frontend", "forms");
+		await writeSkill("skills", "backend", "db-branching");
+		await writeSkill("skills", "flat-skill");
+
+		const found = await scanSkillDirs(path.join(root, "skills"));
+
+		expect(found.sort()).toEqual([
+			"db-branching",
+			"design-system",
+			"flat-skill",
+			"forms",
+		]);
+	});
+
+	it("never counts a grouping directory as a skill", async () => {
+		await writeSkill("skills", "engineering", "code-review");
+		await writeSkill("skills", "engineering", "tdd");
+
+		const found = await scanSkillDirs(path.join(root, "skills"));
+
+		expect(found.sort()).toEqual(["code-review", "tdd"]);
+		expect(found).not.toContain("engineering");
+	});
+
+	it("returns nothing when the directory is absent", async () => {
+		expect(await scanSkillDirs(path.join(root, "nope"))).toEqual([]);
+	});
+
+	it("stops descending past four levels rather than walking the whole tree", async () => {
+		await writeSkill("skills", "a", "b", "c", "d", "too-deep");
+
+		expect(await scanSkillDirs(path.join(root, "skills"))).toEqual([]);
+	});
+});
+
+/**
+ * mnemex ships one MCP server and nothing else. The scan only looked in an
+ * `mcp-servers/` directory, so it reported zero of every component kind and the
+ * plugin read as shipping nothing at all.
+ */
+describe("scanMcpServers", () => {
+	let root: string;
+
+	beforeEach(async () => {
+		root = await fs.mkdtemp(path.join(os.tmpdir(), "claudeup-mcp-"));
+	});
+
+	afterEach(async () => {
+		await fs.remove(root);
+	});
+
+	it("reads server names from a root .mcp.json", async () => {
+		await fs.writeJson(path.join(root, ".mcp.json"), {
+			mnemex: { command: "mnemex", args: ["--mcp"] },
+		});
+
+		expect(await scanMcpServers(root)).toEqual(["mnemex"]);
+	});
+
+	it("reads the mcpServers wrapper shape too", async () => {
+		await fs.writeJson(path.join(root, ".mcp.json"), {
+			mcpServers: { alpha: { command: "a" }, beta: { command: "b" } },
+		});
+
+		expect((await scanMcpServers(root)).sort()).toEqual(["alpha", "beta"]);
+	});
+
+	it("still reads an mcp-servers/ directory", async () => {
+		await fs.ensureDir(path.join(root, "mcp-servers"));
+		await fs.writeJson(path.join(root, "mcp-servers", "tmux.json"), {});
+
+		expect(await scanMcpServers(root)).toEqual(["tmux"]);
+	});
+
+	it("reports a server rather than zero when .mcp.json will not parse", async () => {
+		await fs.writeFile(path.join(root, ".mcp.json"), "{ not json");
+
+		expect(await scanMcpServers(root)).toEqual(["mcp"]);
+	});
+
+	it("reports none when the plugin declares no server", async () => {
+		expect(await scanMcpServers(root)).toEqual([]);
+	});
+});
+
+/**
+ * The clone walkers behind the local-first read. A marketplace the user has
+ * added is on disk, so listing its plugins must cost no GitHub request — the
+ * hourly cap of 60 unauthenticated requests is shared across every repo on
+ * screen, and once it ran out every expand answered "Could not read the plugin",
+ * including for marketplaces sitting complete in the cache.
+ */
+describe("clone walkers", () => {
+	let root: string;
+
+	beforeEach(async () => {
+		root = await fs.mkdtemp(path.join(os.tmpdir(), "claudeup-walk-"));
+	});
+
+	afterEach(async () => {
+		await fs.remove(root);
+	});
+
+	async function write(rel: string, body = "x"): Promise<void> {
+		const full = path.join(root, rel);
+		await fs.ensureDir(path.dirname(full));
+		await fs.writeFile(full, body);
+	}
+
+	it("carries the grouping path so nested skills match the network shape", async () => {
+		await write("skills/frontend/design-system/SKILL.md");
+		await write("skills/backend/db/SKILL.md");
+		await write("skills/flat/SKILL.md");
+
+		const found = await walkSkillDirs(path.join(root, "skills"));
+		const byName = Object.fromEntries(found.map((f) => [f.name, f.group]));
+
+		expect(Object.keys(byName).sort()).toEqual(["db", "design-system", "flat"]);
+		expect(byName["design-system"]).toBe("frontend");
+		expect(byName.db).toBe("backend");
+		expect(byName.flat).toBeUndefined();
+	});
+
+	it("lists markdown commands and skips README", async () => {
+		await write("commands/go.md");
+		await write("commands/README.md");
+		await write("commands/deep/trace.md");
+
+		const found = await walkMarkdown(path.join(root, "commands"));
+
+		expect(found.map((f) => f.name).sort()).toEqual(["go", "trace"]);
+		expect(found.find((f) => f.name === "trace")?.group).toBe("deep");
+	});
+
+	it("returns nothing for a directory that is not there", async () => {
+		expect(await walkSkillDirs(path.join(root, "nope"))).toEqual([]);
+		expect(await walkMarkdown(path.join(root, "nope"))).toEqual([]);
+	});
+});

package/src/__tests__/markdown-renderer.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "bun:test";
+import { renderMarkdown } from "../ui/renderers/markdownRenderer.js";
+
+/**
+ * The renderer emits OpenTUI elements, so these assert structure and counts
+ * rather than pixels: how many lines a construct produces, and that the raw
+ * markers (fences, pipes, hashes) do not survive into the output.
+ */
+
+/** Flatten a rendered node tree to the text a reader would see. */
+// biome-ignore lint/suspicious/noExplicitAny: walking opaque element trees
+function textOf(node: any): string {
+	if (node === null || node === undefined || typeof node === "boolean") {
+		return "";
+	}
+	if (typeof node === "string" || typeof node === "number") return String(node);
+	if (Array.isArray(node)) return node.map(textOf).join("");
+	if (node.props) return textOf(node.props.children);
+	return "";
+}
+
+const render = (src: string, width = 80) =>
+	renderMarkdown(src, { width, maxLines: 500 });
+
+describe("renderMarkdown", () => {
+	it("drops the # markers from a heading", () => {
+		const { nodes } = render("## Routing");
+
+		expect(nodes).toHaveLength(1);
+		expect(textOf(nodes[0])).toBe("Routing");
+	});
+
+	it("drops the fence markers and keeps the code", () => {
+		const { nodes } = render(
+			["```bash", "which mnemex && mnemex --version", "```"].join("\n"),
+		);
+
+		const text = nodes.map(textOf).join("\n");
+		expect(text).not.toContain("```");
+		expect(text).toContain("which mnemex && mnemex --version");
+		expect(text).toContain("bash");
+	});
+
+	it("turns a pipe table into aligned columns with a rule, no pipes", () => {
+		const { nodes } = render(
+			[
+				"| Mode | Keywords |",
+				"|------|----------|",
+				"| Bug | debug, error |",
+				"| Test | coverage |",
+			].join("\n"),
+		);
+
+		// header + rule + 2 body rows
+		expect(nodes).toHaveLength(4);
+		const text = nodes.map(textOf).join("\n");
+		expect(text).not.toContain("|");
+		expect(text).toContain("Mode");
+		expect(text).toContain("debug, error");
+		expect(textOf(nodes[1])).toMatch(/^\s*─+\s+─+$/);
+	});
+
+	it("narrows the widest table column instead of overflowing the pane", () => {
+		const { nodes } = render(
+			["| Mode | Notes |", "|---|---|", `| Bug | ${"x".repeat(120)} |`].join(
+				"\n",
+			),
+			40,
+		);
+
+		for (const node of nodes) {
+			expect(textOf(node).length).toBeLessThanOrEqual(41);
+		}
+		expect(nodes.map(textOf).join("")).toContain("…");
+	});
+
+	it("strips inline markers inside table cells", () => {
+		const { nodes } = render(
+			[
+				"| Mode | Primary Commands |",
+				"|---|---|",
+				"| Bug | `context`, `callers` |",
+				"| Arch | **map** |",
+			].join("\n"),
+		);
+
+		const text = nodes.map(textOf).join("\n");
+		expect(text).toContain("context, callers");
+		expect(text).not.toContain("`");
+		expect(text).not.toContain("**");
+	});
+
+	it("draws a rule for --- rather than printing hyphens as text", () => {
+		const { nodes } = render("---", 30);
+
+		expect(textOf(nodes[0])).toMatch(/^─+$/);
+	});
+
+	it("renders a list bullet and keeps ordered markers", () => {
+		const { nodes } = render(["- first", "2. second"].join("\n"));
+
+		expect(textOf(nodes[0])).toContain("•");
+		expect(textOf(nodes[0])).toContain("first");
+		expect(textOf(nodes[1])).toContain("2.");
+	});
+
+	it("strips inline code backticks and bold asterisks", () => {
+		const { nodes } = render("Run `bun test` and **stop**.");
+
+		const text = textOf(nodes[0]);
+		expect(text).toBe("Run bun test and stop.");
+	});
+
+	it("does not read bold markers that sit inside a code span", () => {
+		const { nodes } = render("Use `a**b` here.");
+
+		expect(textOf(nodes[0])).toBe("Use a**b here.");
+	});
+
+	it("marks a blockquote with a bar instead of a > character", () => {
+		const { nodes } = render("> With a sufficient number of users");
+
+		const text = textOf(nodes[0]);
+		expect(text).toContain("│");
+		expect(text).not.toContain(">");
+	});
+
+	it("reports the lines it stopped short of", () => {
+		const long = Array.from({ length: 30 }, (_, i) => `line ${i}`).join("\n");
+
+		const { nodes, withheld } = renderMarkdown(long, {
+			width: 80,
+			maxLines: 10,
+		});
+
+		expect(nodes).toHaveLength(10);
+		expect(withheld).toBe(20);
+	});
+
+	it("withholds nothing when the whole document fits", () => {
+		expect(render("one\ntwo").withheld).toBe(0);
+	});
+});

package/src/__tests__/marketplaces.test.ts

@@ -38,3 +38,91 @@ describe("marketplaces", () => {
 		expect(names).not.toContain("superpowers");
 	});
 });
+
+/**
+ * The community marketplaces added alongside the Magus channels.
+ *
+ * `name` is not cosmetic: plugin ids are built as `${plugin.name}@${mpName}`
+ * (plugin-manager.ts), so it MUST equal the upstream
+ * .claude-plugin/marketplace.json "name" field. A mismatch fails at install
+ * time with "not found in marketplace", nowhere near the typo that caused it.
+ *
+ * Verify against upstream with:
+ *   gh api repos/<repo>/contents/.claude-plugin/marketplace.json \
+ *     -H "Accept: application/vnd.github.raw" | jq -r '.name'
+ */
+const COMMUNITY_MARKETPLACES: ReadonlyArray<[name: string, repo: string]> = [
+	["mattpocock", "mattpocock/skills"],
+	["ecc", "affaan-m/everything-claude-code"],
+	["ponytail", "DietrichGebert/ponytail"],
+	["addy-agent-skills", "addyosmani/agent-skills"],
+	["humanizer", "blader/humanizer"],
+	["opendesign", "manalkaff/opendesign"],
+	// A fork, not the original: cursor/plugins keeps every manifest under
+	// `.cursor-plugin/` and carries no `.claude-plugin/marketplace.json`, so
+	// Claude Code cannot resolve it at all.
+	["open-pstack", "ericlitman/open-pstack"],
+];
+
+describe("community marketplaces", () => {
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s points at the repo whose manifest declares that name",
+		(name, repo) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			expect(mp).toBeDefined();
+			expect(mp?.source.repo).toBe(repo);
+		},
+	);
+
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s is visible by default via the always-show gate",
+		(name) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			// plugin-manager's gate: configured || official || featured || owned.
+			// Without one of these the entry is only a name-to-repo mapping and
+			// never appears, which is a silent no-op rather than a failure.
+			expect(mp?.official || mp?.featured || mp?.owned).toBe(true);
+		},
+	);
+
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s claims neither Anthropic nor MadAppGang ownership",
+		(name) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			// `official` badges it as Anthropic-managed; `owned` sorts it above
+			// everything as a MadAppGang channel. Both would be a false claim.
+			expect(mp?.official).toBeUndefined();
+			expect(mp?.owned).toBeUndefined();
+		},
+	);
+
+	it("introduces no duplicate marketplace name or repo", () => {
+		const names = defaultMarketplaces.map((m) => m.name);
+		const repos = defaultMarketplaces.map((m) => m.source.repo.toLowerCase());
+
+		expect(new Set(names).size).toBe(names.length);
+		expect(new Set(repos).size).toBe(repos.length);
+	});
+
+	it("surfaces every community marketplace through getAllMarketplaces", () => {
+		const names = getAllMarketplaces().map((mp) => mp.name);
+
+		for (const [name] of COMMUNITY_MARKETPLACES) {
+			expect(names).toContain(name);
+		}
+	});
+
+	it("keeps the Magus channels sorted above the community ones", () => {
+		const order = getAllMarketplaces().map((mp) => mp.name);
+		const lastMagus = Math.max(
+			order.indexOf("magus"),
+			order.indexOf("magus-marketing"),
+			order.indexOf("magus-alpha"),
+		);
+		const firstCommunity = Math.min(
+			...COMMUNITY_MARKETPLACES.map(([name]) => order.indexOf(name)),
+		);
+
+		expect(lastMagus).toBeLessThan(firstCommunity);
+	});
+});

package/src/__tests__/plugin-checkout.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "bun:test";
+import path from "node:path";
+import {
+	checkoutDirName,
+	checkoutPath,
+	ensureCheckout,
+} from "../services/plugin-checkout.js";
+
+/**
+ * A checkout is a read-only shallow clone claudeup owns, used so that browsing
+ * what a plugin contains never requires installing it and never spends the
+ * GitHub API budget (60 requests an hour, unauthenticated, shared across every
+ * repo on screen).
+ */
+describe("checkoutDirName", () => {
+	it("flattens owner/repo into one filesystem-safe segment", () => {
+		expect(checkoutDirName("addyosmani/agent-skills")).toBe(
+			"addyosmani__agent-skills",
+		);
+		expect(checkoutDirName("MadAppGang/magus")).toBe("MadAppGang__magus");
+	});
+
+	it("never yields a name containing a path separator", () => {
+		for (const repo of [
+			"a/b",
+			"../../etc/passwd",
+			"owner/repo.git",
+			"weird name/with spaces",
+		]) {
+			const name = checkoutDirName(repo);
+			expect(name).not.toContain("/");
+			expect(name).not.toContain("\\");
+			// A traversal attempt must not survive as one: `..` collapses into the
+			// same separator run as everything else, so the result cannot escape
+			// the checkout root.
+			expect(path.basename(name)).toBe(name);
+		}
+	});
+
+	it("keeps dots that are part of a real repo name", () => {
+		expect(checkoutDirName("owner/repo.js")).toBe("owner__repo.js");
+	});
+});
+
+describe("checkoutPath", () => {
+	it("puts every checkout under one root, outside Claude Code's own dirs", () => {
+		const a = checkoutPath("owner/one");
+		const b = checkoutPath("owner/two");
+
+		expect(path.dirname(a)).toBe(path.dirname(b));
+		expect(path.dirname(a)).toContain("claudeup-checkouts");
+		// Claude Code owns `plugins/`; a checkout must not look like installed
+		// state, or a reader could mistake it for something Claude Code loads.
+		expect(a).not.toContain(`${path.sep}plugins${path.sep}`);
+	});
+});
+
+describe("ensureCheckout", () => {
+	it("refuses to clone from a test run", async () => {
+		// Not a precaution. A test that only meant to exercise the tree-API path
+		// shallow-cloned a real GitHub repo, because stubbing `globalThis.fetch`
+		// does not stop `git`.
+		expect(process.env.NODE_ENV).toBe("test");
+		expect(await ensureCheckout("blader/humanizer")).toBeNull();
+	});
+});