claudeup 4.41.0 → 4.42.0

package/src/services/plugin-checkout.ts

@@ -0,0 +1,186 @@
+/**
+ * plugin-checkout.ts — a read-only shallow clone, so browsing never installs.
+ *
+ * Why this exists
+ * ---------------
+ * Listing what a plugin contains needs its files. Three ways to get them, and
+ * only one is both complete and free:
+ *
+ *   1. Claude Code's marketplace clone — free and complete, but only exists for
+ *      a marketplace the user has actually added. "✓ Added" in the plugin list
+ *      does NOT imply a clone: that badge means the catalog resolved, and a
+ *      catalog resolves over HTTP for marketplaces that were never cloned.
+ *   2. The GitHub Tree API — works for anything, but an unauthenticated client
+ *      gets 60 requests an hour across every repo on screen combined. A list of
+ *      300+ rows exhausts that in one sitting, after which every expand answers
+ *      "Could not read the plugin".
+ *   3. A shallow git clone of our own. Unlimited, complete, and offline after
+ *      the first fetch.
+ *
+ * This module is (3). It is deliberately NOT an install: nothing here writes to
+ * `installed_plugins.json`, `known_marketplaces.json`, `enabledPlugins`, or
+ * Claude Code's plugin cache. Those are Claude Code-owned and claudeup does not
+ * touch them. A checkout lives in claudeup's own directory, is never loaded by
+ * Claude Code, and can be deleted at any time with no effect on what is
+ * installed.
+ */
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import fs from "fs-extra";
+import { requireClaudeConfigDir } from "../utils/config-dir.js";
+
+const run = promisify(execFile);
+
+/**
+ * How long a checkout is reused before it is refreshed.
+ *
+ * Matches the catalog TTL so the tool has one refresh rhythm rather than two.
+ * A checkout going stale costs the user a skill added in the last hour; longer
+ * would start to misreport what a plugin ships.
+ */
+export const CHECKOUT_TTL_MS = 60 * 60 * 1000;
+
+/** Clones live beside Claude Code's data, never inside its owned directories. */
+function checkoutRoot(): string {
+	return path.join(requireClaudeConfigDir(), "claudeup-checkouts");
+}
+
+/** `owner/repo` → a flat directory name that is safe on every filesystem. */
+export function checkoutDirName(repo: string): string {
+	return repo.replace(/[^a-zA-Z0-9._-]+/g, "__");
+}
+
+export function checkoutPath(repo: string): string {
+	return path.join(checkoutRoot(), checkoutDirName(repo));
+}
+
+/** Is `git` on PATH? Cached — the answer cannot change mid-session. */
+let gitAvailable: boolean | null = null;
+async function hasGit(): Promise<boolean> {
+	if (gitAvailable !== null) return gitAvailable;
+	try {
+		await run("git", ["--version"], { timeout: 5000 });
+		gitAvailable = true;
+	} catch {
+		gitAvailable = false;
+	}
+	return gitAvailable;
+}
+
+/** In-flight clones, so two rows expanding at once do not clone twice. */
+const inFlight = new Map<string, Promise<string | null>>();
+
+/**
+ * Ensure a read-only checkout of `repo` exists, and return its path.
+ *
+ * Returns null when git is unavailable or the clone fails, so the caller can
+ * fall back to the API rather than treating a missing checkout as an empty
+ * plugin — reporting "ships nothing" because a clone failed would be a lie
+ * about the plugin rather than about the network.
+ */
+export async function ensureCheckout(repo: string): Promise<string | null> {
+	// Never clone from a test. This was not a precaution: a unit test that only
+	// meant to exercise the tree-API path shallow-cloned a real GitHub repo,
+	// because a stubbed `globalThis.fetch` does not stop `git`. Same convention
+	// `claudeConfigDirOrNull` uses to keep tests off the real config directory.
+	if (process.env.NODE_ENV === "test") return null;
+
+	const existing = inFlight.get(repo);
+	if (existing) return existing;
+
+	const task = (async () => {
+		const dir = checkoutPath(repo);
+
+		if (await fs.pathExists(path.join(dir, ".git"))) {
+			if (!(await isStale(dir))) return dir;
+			// A refresh that fails leaves the previous checkout in place: stale
+			// content is a better answer than none, and the alternative is a plugin
+			// that browsed fine yesterday reading as unreadable today.
+			if (await refresh(dir)) return dir;
+			return dir;
+		}
+
+		if (!(await hasGit())) return null;
+
+		await fs.ensureDir(checkoutRoot());
+		const tmp = `${dir}.partial`;
+		await fs.remove(tmp);
+		try {
+			// Shallow, one branch, no tags: this is a content read, not history.
+			await run(
+				"git",
+				[
+					"clone",
+					"--depth",
+					"1",
+					"--single-branch",
+					"--no-tags",
+					"--quiet",
+					`https://github.com/${repo}.git`,
+					tmp,
+				],
+				{ timeout: 120_000 },
+			);
+			// Move into place only once complete, so an interrupted clone never
+			// leaves a half-tree that would read as a plugin missing most of itself.
+			await fs.remove(dir);
+			await fs.move(tmp, dir);
+			return dir;
+		} catch {
+			await fs.remove(tmp).catch(() => {});
+			return null;
+		}
+	})();
+
+	inFlight.set(repo, task);
+	try {
+		return await task;
+	} finally {
+		inFlight.delete(repo);
+	}
+}
+
+async function isStale(dir: string): Promise<boolean> {
+	try {
+		const stat = await fs.stat(path.join(dir, ".git"));
+		return Date.now() - stat.mtimeMs > CHECKOUT_TTL_MS;
+	} catch {
+		return true;
+	}
+}
+
+async function refresh(dir: string): Promise<boolean> {
+	if (!(await hasGit())) return false;
+	try {
+		await run("git", ["fetch", "--depth", "1", "--quiet", "origin"], {
+			cwd: dir,
+			timeout: 120_000,
+		});
+		await run("git", ["reset", "--hard", "--quiet", "FETCH_HEAD"], {
+			cwd: dir,
+			timeout: 30_000,
+		});
+		await fs.utimes(path.join(dir, ".git"), new Date(), new Date());
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Every checkout on disk, for a size report or a purge. */
+export async function listCheckouts(): Promise<string[]> {
+	try {
+		return (await fs.readdir(checkoutRoot())).filter(
+			(d) => !d.endsWith(".partial"),
+		);
+	} catch {
+		return [];
+	}
+}
+
+/** Delete every checkout. Safe at any time — none of it is installed state. */
+export async function purgeCheckouts(): Promise<void> {
+	await fs.remove(checkoutRoot());
+}

package/src/services/plugin-manager.ts

@@ -89,6 +89,18 @@ export interface PluginInfo {
 	skills?: string[];
 	mcpServers?: string[];
 	lspServers?: Record<string, unknown>;
+	/**
+	 * The plugin's directory within its marketplace repo, as the manifest
+	 * declares it ("./" for a repo that is one plugin, "./plugins/dev" for a
+	 * multi-plugin marketplace). Needed to scope a skill listing to this
+	 * plugin's subtree rather than the whole repo.
+	 */
+	source?: string;
+	/**
+	 * Set only when the plugin's files live in a repo other than its
+	 * marketplace's — an object `source` naming a different repo.
+	 */
+	sourceRepo?: string;
 	isOrphaned?: boolean;
 	/**
 	 * Set when the installed version equals the catalog version, but the
@@ -340,6 +352,8 @@ export async function getAvailablePlugins(
 				homepage: plugin.homepage,
 				tags: plugin.tags,
 				releases: plugin.releases,
+				source: plugin.source,
+				sourceRepo: plugin.sourceRepo,
 			});
 		}
 	}
@@ -376,6 +390,7 @@ export async function getAvailablePlugins(
 				agents: localPlugin.agents,
 				commands: localPlugin.commands,
 				skills: localPlugin.skills,
+				source: localPlugin.source,
 				mcpServers: localPlugin.mcpServers,
 				lspServers: localPlugin.lspServers,
 				releases: localPlugin.releases,
@@ -561,6 +576,8 @@ export async function getGlobalAvailablePlugins(): Promise<PluginInfo[]> {
 				homepage: plugin.homepage,
 				tags: plugin.tags,
 				releases: plugin.releases,
+				source: plugin.source,
+				sourceRepo: plugin.sourceRepo,
 			});
 		}
 	}
@@ -597,6 +614,7 @@ export async function getGlobalAvailablePlugins(): Promise<PluginInfo[]> {
 				agents: localPlugin.agents,
 				commands: localPlugin.commands,
 				skills: localPlugin.skills,
+				source: localPlugin.source,
 				mcpServers: localPlugin.mcpServers,
 				lspServers: localPlugin.lspServers,
 				releases: localPlugin.releases,