magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/local-marketplace.ts

@@ -0,0 +1,657 @@
+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";
+
+export interface LocalMarketplacePlugin {
+	name: string;
+	version: string;
+	description: string;
+	source?: string;
+	category?: string;
+	author?: { name: string; email?: string };
+	/** Recent release history, as published in the marketplace manifest. */
+	releases?: PluginRelease[];
+	// Extended info from plugin.json or marketplace.json
+	strict?: boolean;
+	lspServers?: Record<string, unknown>;
+	agents?: string[];
+	commands?: string[];
+	skills?: string[];
+	mcpServers?: string[];
+}
+
+export interface LocalMarketplace {
+	name: string;
+	description: string;
+	plugins: LocalMarketplacePlugin[];
+	gitRepo?: string; // Extracted from git remote
+}
+
+const CLAUDE_PLUGINS_DIR = path.join(
+	os.homedir(),
+	".claude",
+	"plugins",
+	"marketplaces",
+);
+const KNOWN_MARKETPLACES_FILE = path.join(
+	os.homedir(),
+	".claude",
+	"plugins",
+	"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;
+	lastUpdated: string;
+}
+
+type KnownMarketplaces = Record<string, KnownMarketplaceEntry>;
+
+/**
+ * Read known_marketplaces.json, or null when it cannot be read honestly.
+ *
+ * The null matters. {@link readKnownMarketplaces} collapses "absent",
+ * "unparseable" and "genuinely empty" into `{}`, which is fine for a lookup and
+ * catastrophic for a filter: intersecting the marketplaces directory against an
+ * empty registry deletes every marketplace, and every installed plugin then
+ * reports as no longer published. A registry we could not read is UNKNOWN, and
+ * unknown must not render as a determinate negative.
+ */
+async function readKnownMarketplacesOrNull(): Promise<KnownMarketplaces | null> {
+	try {
+		if (!(await fs.pathExists(KNOWN_MARKETPLACES_FILE))) return null;
+		const parsed = await fs.readJson(KNOWN_MARKETPLACES_FILE);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return null;
+		}
+		return parsed as KnownMarketplaces;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Read known_marketplaces.json (Claude Code's internal marketplace tracking)
+ */
+async function readKnownMarketplaces(): Promise<KnownMarketplaces> {
+	return (await readKnownMarketplacesOrNull()) ?? {};
+}
+
+/**
+ * Directory names a parsed `known_marketplaces.json` registers, or null when it
+ * says nothing usable.
+ *
+ * Pure, and exported, because `scanLocalMarketplaces` resolves its paths from
+ * `os.homedir()` at module load and cannot be pointed at a temp directory. The
+ * decision this encodes is the part worth testing; the IO around it is not.
+ *
+ * Keyed by BOTH the registry key and the basename of `installLocation`: the two
+ * are normally equal and nothing enforces it, and dropping a real marketplace
+ * is far worse than keeping a stray directory.
+ *
+ * An empty object is an ANSWER — nothing is registered — and filters everything
+ * out. Only unusable input is null. The distinction lives in
+ * {@link readKnownMarketplacesOrNull}, which returns null for an absent file,
+ * so a machine that has never added a marketplace stays permissive.
+ */
+export function registeredMarketplaceNames(
+	parsed: unknown,
+): Set<string> | null {
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return null;
+	}
+	const names = new Set<string>();
+	for (const [name, entry] of Object.entries(
+		parsed as Record<string, unknown>,
+	)) {
+		names.add(name);
+		const loc = (entry as { installLocation?: unknown })?.installLocation;
+		if (typeof loc === "string" && loc.length > 0) {
+			names.add(path.basename(loc));
+		}
+	}
+	return names;
+}
+
+async function registeredDirNames(): Promise<Set<string> | null> {
+	return registeredMarketplaceNames(await readKnownMarketplacesOrNull());
+}
+
+/**
+ * Get git remote URL from a marketplace directory
+ */
+function getGitRemote(marketplacePath: string): string | undefined {
+	try {
+		const gitDir = path.join(marketplacePath, ".git");
+		if (!fs.existsSync(gitDir)) return undefined;
+
+		const result = execSync("git remote get-url origin", {
+			cwd: marketplacePath,
+			encoding: "utf-8",
+			timeout: 5000,
+		}).trim();
+
+		// Convert SSH URL to HTTPS format: git@github.com:user/repo.git -> user/repo
+		if (result.startsWith("git@github.com:")) {
+			return result.replace("git@github.com:", "").replace(/\.git$/, "");
+		}
+		// HTTPS URL: https://github.com/user/repo -> user/repo
+		if (result.includes("github.com")) {
+			const match = result.match(/github\.com[/:]([^/]+\/[^/\s.]+)/);
+			if (match) return match[1].replace(/\.git$/, "");
+		}
+		return undefined;
+	} catch {
+		return 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 nests its skills by category 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
+ * once reported 9 skills against 43 on disk, mattpocock 5 against 37 — and that
+ * count is what the plugin detail panel prints. dev also ships a `knowledge/`
+ * tree beside `skills/`: reference manuals reached by path, holding no SKILL.md
+ * and registering nothing, so this scan correctly never sees them.
+ *
+ * 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,
+): Promise<LocalMarketplace | null> {
+	const manifestPath = path.join(
+		marketplacePath,
+		".claude-plugin",
+		"marketplace.json",
+	);
+
+	if (!(await fs.pathExists(manifestPath))) return null;
+
+	try {
+		const manifest = await fs.readJson(manifestPath);
+		const gitRepo = getGitRemote(marketplacePath);
+
+		const plugins: LocalMarketplacePlugin[] = [];
+		const validManifestPlugins: typeof manifest.plugins = [];
+		let manifestModified = false;
+
+		if (manifest.plugins && Array.isArray(manifest.plugins)) {
+			for (const plugin of manifest.plugins) {
+				// Try to scan plugin directory for component counts
+				let agents: string[] = [];
+				let commands: string[] = [];
+				let skills: string[] = [];
+				let mcpServers: string[] = [];
+
+				// Handle both string sources (local paths) and object sources (remote URLs)
+				const sourceStr =
+					typeof plugin.source === "string" ? plugin.source : null;
+
+				if (sourceStr) {
+					const pluginPath = path.join(
+						marketplacePath,
+						sourceStr.replace("./", ""),
+					);
+
+					// Remove plugins whose source directory doesn't exist
+					if (!(await fs.pathExists(pluginPath))) {
+						manifestModified = true;
+						continue;
+					}
+
+					try {
+						// Scan for agents
+						const agentsDir = path.join(pluginPath, "agents");
+						if (await fs.pathExists(agentsDir)) {
+							const agentFiles = await fs.readdir(agentsDir);
+							agents = agentFiles
+								.filter((f) => f.endsWith(".md"))
+								.map((f) => f.replace(".md", ""));
+						}
+						// Scan for commands
+						const commandsDir = path.join(pluginPath, "commands");
+						if (await fs.pathExists(commandsDir)) {
+							const cmdFiles = await fs.readdir(commandsDir);
+							commands = cmdFiles
+								.filter((f) => f.endsWith(".md"))
+								.map((f) => f.replace(".md", ""));
+						}
+						// Scan for skills
+						skills = await scanSkillDirs(path.join(pluginPath, "skills"));
+						// Scan for MCP servers
+						mcpServers = await scanMcpServers(pluginPath);
+					} catch {
+						// Ignore scan errors
+					}
+				}
+
+				validManifestPlugins.push(plugin);
+				plugins.push({
+					name: plugin.name,
+					version: plugin.version || "0.0.0",
+					description: plugin.description || "",
+					source: plugin.source,
+					category: plugin.category,
+					author: plugin.author,
+					releases: normalizeReleases(plugin.releases),
+					strict: plugin.strict,
+					lspServers: plugin.lspServers,
+					agents,
+					commands,
+					skills,
+					mcpServers,
+				});
+			}
+		}
+
+		// Update marketplace.json if we removed invalid plugins
+		if (manifestModified) {
+			manifest.plugins = validManifestPlugins;
+			await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+		}
+
+		return {
+			name: manifest.name || marketplaceName,
+			description: manifest.description || manifest.metadata?.description || "",
+			plugins,
+			gitRepo,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Scan local marketplace cache and return marketplace info
+ * Includes both:
+ * - Marketplaces in ~/.claude/plugins/marketplaces/
+ * - Directory-based marketplaces from known_marketplaces.json
+ */
+export async function scanLocalMarketplaces(): Promise<
+	Map<string, LocalMarketplace>
+> {
+	const marketplaces = new Map<string, LocalMarketplace>();
+
+	// A directory is not a marketplace; a REGISTRY ENTRY is. Null means the
+	// registry could not be read, and then every directory is kept — see
+	// `registeredDirNames`.
+	//
+	// Claude Code refreshes a marketplace by delete-then-clone and leaves
+	// `<name>.bak` behind. An unfiltered scan treated that backup as a real
+	// marketplace, which cost the reporter twice: `magus.bak` shadowed the real
+	// `magus` in `getAllMarketplaces()` (deduped by repo, first-come) so the real
+	// one vanished from the plugin list entirely, and later it became the target
+	// of a nonsense label — `kanban@magus … moved → magus.bak`. `claude plugin
+	// marketplace list` never showed it, because Claude Code reads the registry.
+	const registered = await registeredDirNames();
+
+	// 1. Scan marketplaces from the standard directory
+	if (await fs.pathExists(CLAUDE_PLUGINS_DIR)) {
+		try {
+			const entries = await fs.readdir(CLAUDE_PLUGINS_DIR, {
+				withFileTypes: true,
+			});
+
+			for (const entry of entries) {
+				if (!entry.isDirectory()) continue;
+				if (registered && !registered.has(entry.name)) continue;
+
+				const marketplacePath = path.join(CLAUDE_PLUGINS_DIR, entry.name);
+				const marketplace = await scanSingleMarketplace(
+					marketplacePath,
+					entry.name,
+				);
+				if (marketplace) {
+					marketplaces.set(entry.name, marketplace);
+				}
+			}
+		} catch {
+			// Ignore read errors
+		}
+	}
+
+	// 2. Add directory-based marketplaces from known_marketplaces.json
+	try {
+		const known = await readKnownMarketplaces();
+		for (const [name, entry] of Object.entries(known)) {
+			// Only add if it's a directory source AND not already in the map
+			if (
+				entry.source.source === "directory" &&
+				entry.installLocation &&
+				!marketplaces.has(name)
+			) {
+				if (await fs.pathExists(entry.installLocation)) {
+					const marketplace = await scanSingleMarketplace(
+						entry.installLocation,
+						name,
+					);
+					if (marketplace) {
+						marketplaces.set(name, marketplace);
+					}
+				}
+			}
+		}
+	} catch {
+		// Ignore errors reading known_marketplaces
+	}
+
+	return marketplaces;
+}
+
+/**
+ * Get a specific local marketplace by name
+ */
+export async function getLocalMarketplace(
+	name: string,
+): Promise<LocalMarketplace | undefined> {
+	const marketplaces = await scanLocalMarketplaces();
+	return marketplaces.get(name);
+}
+
+/**
+ * Check if a marketplace exists in local cache
+ */
+export async function hasLocalMarketplace(name: string): Promise<boolean> {
+	const marketplacePath = path.join(CLAUDE_PLUGINS_DIR, name);
+	const manifestPath = path.join(
+		marketplacePath,
+		".claude-plugin",
+		"marketplace.json",
+	);
+	return fs.pathExists(manifestPath);
+}
+
+export interface RefreshResult {
+	name: string;
+	success: boolean;
+	updated: boolean;
+	error?: string;
+}
+
+export interface RefreshProgress {
+	current: number;
+	total: number;
+	name: string;
+}
+
+export type ProgressCallback = (progress: RefreshProgress) => void;
+
+export interface RepairResult {
+	repaired: boolean;
+	pluginName: string;
+	added: {
+		agents: string[];
+		commands: string[];
+		skills: string[];
+	};
+}
+
+/**
+ * Repair a plugin's plugin.json by adding missing agents/commands/skills arrays
+ * based on what files exist on disk.
+ *
+ * This fixes plugins where the author forgot to add the arrays to plugin.json,
+ * causing Claude Code to not load the agents/commands even though files exist.
+ */
+export async function repairPluginJson(
+	pluginPath: string,
+): Promise<RepairResult> {
+	const pluginJsonPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
+	const pluginName = path.basename(pluginPath);
+
+	const result: RepairResult = {
+		repaired: false,
+		pluginName,
+		added: { agents: [], commands: [], skills: [] },
+	};
+
+	if (!(await fs.pathExists(pluginJsonPath))) {
+		return result;
+	}
+
+	try {
+		const pluginJson = await fs.readJson(pluginJsonPath);
+		let modified = false;
+
+		// Scan and add agents if array is missing
+		const agentsDir = path.join(pluginPath, "agents");
+		if (await fs.pathExists(agentsDir)) {
+			const files = (await fs.readdir(agentsDir))
+				.filter((f) => f.endsWith(".md"))
+				.map((f) => `./agents/${f}`);
+
+			if (files.length > 0 && !pluginJson.agents) {
+				pluginJson.agents = files;
+				result.added.agents = files;
+				modified = true;
+			}
+		}
+
+		// Scan and add commands if array is missing
+		const commandsDir = path.join(pluginPath, "commands");
+		if (await fs.pathExists(commandsDir)) {
+			const files = (await fs.readdir(commandsDir))
+				.filter((f) => f.endsWith(".md"))
+				.map((f) => `./commands/${f}`);
+
+			if (files.length > 0 && !pluginJson.commands) {
+				pluginJson.commands = files;
+				result.added.commands = files;
+				modified = true;
+			}
+		}
+
+		// Scan and add skills if array is missing
+		const skillsDir = path.join(pluginPath, "skills");
+		if (await fs.pathExists(skillsDir)) {
+			const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+			const skills = entries
+				.filter((e) => e.isDirectory() || e.name.endsWith(".md"))
+				.map((e) => `./skills/${e.name}`);
+
+			if (skills.length > 0 && !pluginJson.skills) {
+				pluginJson.skills = skills;
+				result.added.skills = skills;
+				modified = true;
+			}
+		}
+
+		if (modified) {
+			await fs.writeJson(pluginJsonPath, pluginJson, { spaces: 2 });
+			result.repaired = true;
+		}
+	} catch {
+		// Ignore repair errors for individual plugins
+	}
+
+	return result;
+}
+
+export interface RepairMarketplaceResult {
+	marketplace: string;
+	repaired: RepairResult[];
+}
+
+/**
+ * Repair all plugins in a marketplace
+ */
+export async function repairMarketplacePlugins(
+	marketplaceName: string,
+): Promise<RepairMarketplaceResult> {
+	const result: RepairMarketplaceResult = {
+		marketplace: marketplaceName,
+		repaired: [],
+	};
+
+	const marketplacePath = path.join(CLAUDE_PLUGINS_DIR, marketplaceName);
+	const manifestPath = path.join(
+		marketplacePath,
+		".claude-plugin",
+		"marketplace.json",
+	);
+
+	if (!(await fs.pathExists(manifestPath))) {
+		return result;
+	}
+
+	try {
+		const manifest = await fs.readJson(manifestPath);
+
+		if (manifest.plugins && Array.isArray(manifest.plugins)) {
+			for (const plugin of manifest.plugins) {
+				if (plugin.source) {
+					const pluginPath = path.join(
+						marketplacePath,
+						plugin.source.replace("./", ""),
+					);
+					const repairResult = await repairPluginJson(pluginPath);
+
+					if (repairResult.repaired) {
+						result.repaired.push(repairResult);
+					}
+				}
+			}
+		}
+	} catch {
+		// Ignore errors
+	}
+
+	return result;
+}
+
+/**
+ * Repair all plugins in all marketplaces
+ */
+export async function repairAllMarketplaces(): Promise<
+	RepairMarketplaceResult[]
+> {
+	const results: RepairMarketplaceResult[] = [];
+
+	if (!(await fs.pathExists(CLAUDE_PLUGINS_DIR))) {
+		return results;
+	}
+
+	try {
+		const entries = await fs.readdir(CLAUDE_PLUGINS_DIR, {
+			withFileTypes: true,
+		});
+
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+
+			const repairResult = await repairMarketplacePlugins(entry.name);
+			if (repairResult.repaired.length > 0) {
+				results.push(repairResult);
+			}
+		}
+	} catch {
+		// Return empty on error
+	}
+
+	return results;
+}