claudeup 4.41.0 → 4.42.1

package/src/services/dotenv.ts

@@ -0,0 +1,176 @@
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import path from "node:path";
+
+/**
+ * Load the project's .env into the process environment — deliberately, in our
+ * own code, with every failure downgraded to a warning.
+ *
+ * Bun's standalone-executable autoload used to do this for free. It is compiled
+ * OFF now (see scripts/build-binaries.ts): Bun 1.4.0 aborts inside that autoload
+ * when .env is a symlink pointing at a FIFO — exactly how 1Password serves
+ * secrets into a git worktree — exiting 1 with nothing on stdout or stderr,
+ * before any JavaScript runs and therefore before any error handler exists.
+ * claudeup simply vanished in every such directory.
+ *
+ * Two rules this loader keeps that the autoload did not:
+ *
+ *   1. Only regular files are read. A FIFO, socket or device is skipped, never
+ *      opened. That dodges the crash, and it is right on its own terms: a FIFO
+ *      hands its bytes to whoever opens it FIRST, so reading one would swallow
+ *      the secrets a dev server or `op run` was waiting for.
+ *   2. Nothing here is fatal. A missing, unreadable or malformed .env produces a
+ *      warning and claudeup carries on. Managing ~/.claude must never depend on
+ *      the state of whatever directory you happen to be standing in.
+ *
+ * A real environment variable always beats a file, matching dotenv convention;
+ * a later file beats an earlier one.
+ */
+
+/** Files loaded, in order. A later file overrides an earlier one. */
+const ENV_FILES = [".env", ".env.local"] as const;
+
+export interface DotenvOutcome {
+	/** Files actually parsed, in the order applied. */
+	loaded: string[];
+	/** Names newly set. A pre-existing variable is never overwritten. */
+	applied: string[];
+	/** One line per file skipped or failed. Print these; never throw them. */
+	warnings: string[];
+}
+
+/**
+ * Parse dotenv text. Best-effort by design: an unparseable line is skipped
+ * rather than raised, because a broken .env must not be able to stop claudeup.
+ * Values spanning several lines are not supported.
+ */
+export function parseDotenv(text: string): Record<string, string> {
+	const out: Record<string, string> = {};
+
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("#")) continue;
+
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+
+		let key = line.slice(0, eq).trim();
+		if (key.startsWith("export ")) key = key.slice("export ".length).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+		let value = line.slice(eq + 1).trim();
+		const quote = value[0];
+		const quoted =
+			(quote === '"' || quote === "'") &&
+			value.length > 1 &&
+			value.endsWith(quote);
+
+		if (quoted) {
+			value = value.slice(1, -1);
+			// Escapes are a double-quote feature; single quotes stay literal.
+			if (quote === '"') {
+				value = value
+					.replace(/\\n/g, "\n")
+					.replace(/\\r/g, "\r")
+					.replace(/\\t/g, "\t");
+			}
+		} else {
+			// An unquoted value ends at the first " #" comment.
+			const hash = value.indexOf(" #");
+			if (hash !== -1) value = value.slice(0, hash).trimEnd();
+		}
+
+		out[key] = value;
+	}
+
+	return out;
+}
+
+/** What a non-regular entry actually is, for a warning a human can act on. */
+function describeKind(info: Stats): string {
+	if (info.isFIFO()) {
+		return "it is a named pipe; reading it would consume another process's secrets";
+	}
+	if (info.isSocket()) return "it is a socket, not a regular file";
+	if (info.isDirectory()) return "it is a directory, not a regular file";
+	if (info.isBlockDevice() || info.isCharacterDevice()) {
+		return "it is a device, not a regular file";
+	}
+	return "it is not a regular file";
+}
+
+function reason(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Read .env and .env.local from `cwd` into `env`. Never throws.
+ *
+ * Returns what was loaded and, in `warnings`, every reason a file was skipped or
+ * failed — the caller decides how to surface them.
+ */
+export function loadProjectDotenv(
+	cwd: string = process.cwd(),
+	env: Record<string, string | undefined> = process.env,
+): DotenvOutcome {
+	const outcome: DotenvOutcome = { loaded: [], applied: [], warnings: [] };
+
+	// Merge every file BEFORE touching `env`. Applying file by file would make
+	// the "never overwrite" rule below fire against .env's own values, so .env
+	// would silently beat .env.local — the opposite of the intended precedence.
+	const merged: Record<string, string> = {};
+
+	for (const name of ENV_FILES) {
+		const file = path.join(cwd, name);
+
+		// lstat first, so a symlink is recognised as one: the warning should name
+		// the file the user sees, while the decision is made about its target.
+		let info: Stats;
+		try {
+			info = lstatSync(file);
+		} catch {
+			continue; // Absent. That is the ordinary case, not a problem.
+		}
+
+		if (info.isSymbolicLink()) {
+			try {
+				info = statSync(file);
+			} catch {
+				outcome.warnings.push(`skipped ${name} — the symlink does not resolve`);
+				continue;
+			}
+		}
+
+		if (!info.isFile()) {
+			outcome.warnings.push(`skipped ${name} — ${describeKind(info)}`);
+			continue;
+		}
+
+		let text: string;
+		try {
+			text = readFileSync(file, "utf8");
+		} catch (error) {
+			outcome.warnings.push(`could not read ${name} — ${reason(error)}`);
+			continue;
+		}
+
+		let parsed: Record<string, string>;
+		try {
+			parsed = parseDotenv(text);
+		} catch (error) {
+			outcome.warnings.push(`could not parse ${name} — ${reason(error)}`);
+			continue;
+		}
+
+		outcome.loaded.push(name);
+		Object.assign(merged, parsed); // A later file beats an earlier one.
+	}
+
+	for (const [key, value] of Object.entries(merged)) {
+		if (env[key] !== undefined) continue; // A real variable always wins.
+		env[key] = value;
+		outcome.applied.push(key);
+	}
+
+	return outcome;
+}

package/src/services/local-marketplace.ts

@@ -1,7 +1,7 @@
-import fs from "fs-extra";
-import path from "node:path";
-import os from "node:os";
 import { execSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
 import type { PluginRelease } from "../types/index.js";
 import { normalizeReleases } from "./plugin-releases.js";
 
@@ -43,6 +43,18 @@ const KNOWN_MARKETPLACES_FILE = path.join(
 	"known_marketplaces.json",
 );
 
+/**
+ * Where Claude Code keeps a marketplace's clone, whether or not it exists.
+ *
+ * Exported so a reader can prefer the clone over the network. Anything already
+ * added is on disk in full, and reading it costs no GitHub request — which
+ * matters because an unauthenticated client gets 60 an hour for every repo on
+ * screen combined.
+ */
+export function getMarketplaceClonePath(marketplaceName: string): string {
+	return path.join(CLAUDE_PLUGINS_DIR, marketplaceName);
+}
+
 interface KnownMarketplaceEntry {
 	source: { source: string; url?: string; repo?: string };
 	installLocation: string;
@@ -97,6 +109,99 @@ function getGitRemote(marketplacePath: string): string | undefined {
 /**
  * Scan a single marketplace directory and return marketplace info
  */
+/**
+ * Names of the skills under `skillsDir`, recursing through grouping directories.
+ *
+ * A skill is a directory holding a SKILL.md, and it may sit one or more levels
+ * down: dev groups its 43 skills under `skills/frontend/`, `skills/backend/`
+ * and so on, and mattpocock groups its 37 under `skills/engineering/`. Reading
+ * only the top level counted the *groups* — dev reported 9 skills against 43 on
+ * disk, mattpocock 5 against 37 — and that count is what the plugin detail
+ * panel prints.
+ *
+ * Depth is capped because this runs over every plugin of every cloned
+ * marketplace on each list load, and a skill nested four levels below `skills/`
+ * does not exist in practice.
+ */
+export async function scanSkillDirs(
+	skillsDir: string,
+	depth = 0,
+): Promise<string[]> {
+	if (depth > 3) return [];
+	if (!(await fs.pathExists(skillsDir))) return [];
+
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await fs.readdir(skillsDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const found: string[] = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const child = path.join(skillsDir, entry.name);
+		if (await fs.pathExists(path.join(child, "SKILL.md"))) {
+			found.push(entry.name);
+		} else {
+			found.push(...(await scanSkillDirs(child, depth + 1)));
+		}
+	}
+	return found;
+}
+
+/**
+ * Names of the MCP servers a plugin declares.
+ *
+ * Two locations are in use, and only one of them used to be read. An
+ * `mcp-servers/` directory of one JSON per server was the only thing scanned;
+ * a root `.mcp.json`, which is the form `plugin.json` points at with
+ * `"mcpServers": "./.mcp.json"`, was invisible. In this marketplace that is 5
+ * plugins of 7, mnemex among them — and mnemex ships *nothing else*, so it
+ * reported zero components of every kind and read as an empty plugin.
+ *
+ * Inside `.mcp.json`, both a bare `{ "<name>": {...} }` map and the
+ * `{ "mcpServers": {...} }` wrapper appear in the wild.
+ */
+export async function scanMcpServers(pluginPath: string): Promise<string[]> {
+	const found: string[] = [];
+
+	const mcpDir = path.join(pluginPath, "mcp-servers");
+	if (await fs.pathExists(mcpDir)) {
+		try {
+			const files = await fs.readdir(mcpDir);
+			found.push(
+				...files
+					.filter((f) => f.endsWith(".json"))
+					.map((f) => f.replace(".json", "")),
+			);
+		} catch {
+			// Ignore scan errors
+		}
+	}
+
+	const mcpFile = path.join(pluginPath, ".mcp.json");
+	if (await fs.pathExists(mcpFile)) {
+		try {
+			const raw = (await fs.readJson(mcpFile)) as Record<string, unknown>;
+			const servers =
+				raw.mcpServers && typeof raw.mcpServers === "object"
+					? (raw.mcpServers as Record<string, unknown>)
+					: raw;
+			for (const name of Object.keys(servers)) {
+				if (!found.includes(name)) found.push(name);
+			}
+		} catch {
+			// Unreadable or malformed. The file exists, so the plugin does declare a
+			// server — report one rather than dropping to zero, which is the exact
+			// "ships nothing" misreport this function exists to fix.
+			if (found.length === 0) found.push("mcp");
+		}
+	}
+
+	return found;
+}
+
 async function scanSingleMarketplace(
 	marketplacePath: string,
 	marketplaceName: string,
@@ -159,23 +264,9 @@ async function scanSingleMarketplace(
 								.map((f) => f.replace(".md", ""));
 						}
 						// Scan for skills
-						const skillsDir = path.join(pluginPath, "skills");
-						if (await fs.pathExists(skillsDir)) {
-							const skillFiles = await fs.readdir(skillsDir);
-							skills = skillFiles.filter(
-								(f) =>
-									f.endsWith(".md") ||
-									fs.statSync(path.join(skillsDir, f)).isDirectory(),
-							);
-						}
+						skills = await scanSkillDirs(path.join(pluginPath, "skills"));
 						// Scan for MCP servers
-						const mcpDir = path.join(pluginPath, "mcp-servers");
-						if (await fs.pathExists(mcpDir)) {
-							const mcpFiles = await fs.readdir(mcpDir);
-							mcpServers = mcpFiles
-								.filter((f) => f.endsWith(".json"))
-								.map((f) => f.replace(".json", ""));
-						}
+						mcpServers = await scanMcpServers(pluginPath);
 					} catch {
 						// Ignore scan errors
 					}

package/src/services/marketplace-catalog.ts

@@ -26,6 +26,17 @@ export interface MarketplacePlugin {
 	homepage?: string;
 	tags?: string[];
 	releases?: PluginRelease[];
+	/**
+	 * The plugin's directory inside the marketplace repo, as declared. "" means
+	 * the repo root, which is how every single-plugin marketplace publishes
+	 * ("source": "./").
+	 */
+	source?: string;
+	/**
+	 * Set only when the plugin declares an object source naming a repo other
+	 * than the marketplace's own. Its files live there, not in the marketplace.
+	 */
+	sourceRepo?: string;
 }
 
 // Session-level cache for each marketplace's declared version (from
@@ -58,6 +69,28 @@ interface RawPlugin {
 	homepage?: string;
 	tags?: string[];
 	releases?: unknown;
+	source?: string | { source?: string; repo?: string };
+}
+
+/**
+ * Split a manifest `source` into a repo-relative directory and, when the plugin
+ * points at a different repo than the marketplace, that repo.
+ *
+ * Both forms are in use: a string path ("./", "./plugins/dev") and an object
+ * ({"source":"github","repo":"owner/name"}), which addyosmani/agent-skills
+ * publishes. The object form has no path — the plugin is the whole repo.
+ */
+function splitSource(source: RawPlugin["source"]): {
+	source?: string;
+	sourceRepo?: string;
+} {
+	if (typeof source === "string") {
+		return { source: source.replace(/^\.\//, "").replace(/\/+$/, "") };
+	}
+	if (source && typeof source === "object" && typeof source.repo === "string") {
+		return { source: "", sourceRepo: source.repo };
+	}
+	return {};
 }
 
 /** Parse a `marketplace.json` payload into plugin entries. */
@@ -87,6 +120,7 @@ export function normalizeCatalogJson(
 				homepage: plugin.homepage,
 				tags: plugin.tags,
 				releases: normalizeReleases(plugin.releases),
+				...splitSource(plugin.source),
 			});
 		}
 	}

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,