magus-cli 7.8.0 → 7.9.1

package/src/services/local-marketplace.ts

@@ -162,9 +162,6 @@ 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.
  *
@@ -260,6 +257,11 @@ export async function scanMcpServers(pluginPath: string): Promise<string[]> {
 	return found;
 }
 
+/**
+ * Read one marketplace clone: its manifest, plus the component counts of each
+ * plugin whose source directory is on disk. Read-only — the manifest and the
+ * clone belong to Claude Code, and nothing here writes either.
+ */
 async function scanSingleMarketplace(
 	marketplacePath: string,
 	marketplaceName: string,
@@ -277,8 +279,6 @@ async function scanSingleMarketplace(
 		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) {
@@ -292,18 +292,13 @@ async function scanSingleMarketplace(
 				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;
-					}
-
+				// A plugin whose source directory is not on disk is still listed: the
+				// manifest is Claude Code's, and a scan reads it, never rewrites it.
+				// Its component lists stay empty because there is nothing to count.
+				const pluginPath = sourceStr
+					? path.join(marketplacePath, sourceStr.replace("./", ""))
+					: null;
+				if (pluginPath && (await fs.pathExists(pluginPath))) {
 					try {
 						// Scan for agents
 						const agentsDir = path.join(pluginPath, "agents");
@@ -330,7 +325,6 @@ async function scanSingleMarketplace(
 					}
 				}
 
-				validManifestPlugins.push(plugin);
 				plugins.push({
 					name: plugin.name,
 					version: plugin.version || "0.0.0",
@@ -349,12 +343,6 @@ async function scanSingleMarketplace(
 			}
 		}
 
-		// 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 || "",
@@ -466,13 +454,6 @@ export async function hasLocalMarketplace(name: string): Promise<boolean> {
 	return fs.pathExists(manifestPath);
 }
 
-export interface RefreshResult {
-	name: string;
-	success: boolean;
-	updated: boolean;
-	error?: string;
-}
-
 export interface RefreshProgress {
 	current: number;
 	total: number;
@@ -480,178 +461,3 @@ export interface RefreshProgress {
 }
 
 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;
-}

package/src/services/marketplace-refresh.ts

@@ -1,12 +1,12 @@
 /**
  * Keep on-disk marketplace clones current — safely.
  *
- * The plugin *list* magus shows is fetched fresh from GitHub, but a plugin's
- * `setup` block and Claude Code's own installer read the on-disk marketplace
- * clone (~/.claude/plugins/marketplaces/<name>). Nothing else keeps that clone
+ * The plugin *list* magus shows is fetched fresh from GitHub, but the
+ * `requires` of a plugin not installed yet and Claude Code's own installer read
+ * the on-disk marketplace clone (~/.claude/plugins/marketplaces/<name>). Nothing else keeps that clone
  * current — recoverMarketplaceSettings only pulls entries it had to re-register —
  * so a healthy marketplace's clone goes stale and its plugin metadata (e.g. a
- * pinned dependency version in a plugin's setup) is never seen, even while the
+ * dependency pin in a plugin's `requires`) is never seen, even while the
  * displayed version looks up to date.
  *
  * IMPORTANT: this refreshes the clone with a NON-DESTRUCTIVE `git pull --ff-only`,

package/src/services/plugin-manager.ts

@@ -33,8 +33,6 @@ import { inheritablePaths } from "./git-worktree.js";
 import {
 	type LocalMarketplace,
 	type ProgressCallback,
-	type RepairMarketplaceResult,
-	repairAllMarketplaces,
 	scanLocalMarketplaces,
 } from "./local-marketplace.js";
 import {
@@ -1043,18 +1041,14 @@ async function autoSyncIfStale(
 	return localMarketplaces;
 }
 
-export interface RefreshAndRepairResult {
-	refresh: never[];
-	repair: RepairMarketplaceResult[];
-}
-
 /**
- * Refresh magus's internal cache
- * Note: Marketplace updates should be done via Claude Code's /plugin marketplace update command
+ * Refresh magus's internal cache. Only magus's own caches are cleared: the
+ * marketplace clones are Claude Code's, and refreshing them is
+ * `claude plugin marketplace update`.
  */
 export async function refreshAllMarketplaces(
 	onProgress?: ProgressCallback,
-): Promise<RefreshAndRepairResult> {
+): Promise<void> {
 	onProgress?.({ current: 1, total: 1, name: "Clearing cache..." });
 
 	// Clear all caches to force fresh data. The on-disk catalog cache is awaited
@@ -1062,14 +1056,6 @@ export async function refreshAllMarketplaces(
 	// entries this is discarding.
 	clearMarketplaceCache();
 	await clearPersistedCatalogs();
-
-	// Auto-repair plugin.json files with missing agents/commands/skills
-	const repairResults = await repairAllMarketplaces();
-
-	return {
-		refresh: [],
-		repair: repairResults,
-	};
 }
 
 // Re-export types for consumers

package/src/services/plugin-requires.ts

@@ -1,21 +1,28 @@
 /**
- * Read plugin-declared binary dependencies from plugin.json `requires.bin`.
+ * What a plugin's plugin.json says it needs: its `dependencies` (other plugins)
+ * and its `requires` (binaries on the machine).
  *
- * A plugin declares the binaries it needs on PATH (e.g. terminal@magus needs
- * `tmux` and `tmux-mcp`). `magus install` resolves these transitively so a
- * teammate who enables a plugin also gets its binaries — closing the class of
- * bug where a plugin's MCP server silently fails because its binary is missing.
+ * `requires` is parsed by `shared/plugin/hooks/lib/requires-probe.ts` and by
+ * nothing else — the same file every declaring plugin carries for its
+ * SessionStart deps check, so the hook and magus read one declaration one way.
+ * This module only locates the manifest Claude Code loads and hands it over.
  */
 
 import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
-import type {
-	BinInstaller,
-	BinRequirement,
-	PluginRequires,
-} from "../types/index.js";
-import { goBinaryName } from "../utils/go-module.js";
+import {
+	type Arch,
+	type Os,
+	type ParseResult,
+	type Requirement,
+	applicable,
+	currentPlatform,
+	onPath,
+	parseRequires,
+	selectOption,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type { SelectedBin } from "../types/index.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { readInstalledPluginsRegistry } from "./claude-settings.js";
 import { getLocalMarketplacesInfo } from "./plugin-manager.js";
@@ -24,144 +31,6 @@ import { pickLoadedEntry } from "./plugin-resolution.js";
 const MARKETPLACES_DIR = (): string =>
 	path.join(os.homedir(), ".claude", "plugins", "marketplaces");
 
-const VALID_INSTALLERS: readonly BinInstaller[] = [
-	"bun",
-	"brew",
-	"npm",
-	"pip",
-	"go",
-];
-
-/**
- * Normalize a raw `requires.bin` entry into a complete BinRequirement,
- * filling in defaults. Returns null for entries that can't be made valid
- * (missing name, or an unrecognized installer).
- */
-function normalizeBin(raw: unknown): BinRequirement | null {
-	if (!raw || typeof raw !== "object") return null;
-	const o = raw as Record<string, unknown>;
-	const name = typeof o.name === "string" ? o.name.trim() : "";
-	if (!name) return null;
-
-	const via = o.via as BinInstaller;
-	if (!VALID_INSTALLERS.includes(via)) return null;
-
-	const bin: BinRequirement = {
-		name,
-		via,
-		check:
-			typeof o.check === "string" && o.check.trim()
-				? o.check.trim()
-				: `${name} --version`,
-	};
-	if (typeof o.package === "string") bin.package = o.package;
-	if (typeof o.formula === "string") bin.formula = o.formula;
-	if (typeof o.module === "string") bin.module = o.module;
-	if (typeof o.version === "string") bin.version = o.version;
-	return bin;
-}
-
-/** Split a package/module spec into its base and optional version. Handles
- *  scoped npm (@scope/pkg@1.2.0) and go modules (host/path@latest). */
-function splitVersion(spec: string): { base: string; version?: string } {
-	const at = spec.lastIndexOf("@");
-	// at > 0 avoids treating a leading npm scope "@scope/..." as a version.
-	if (at > 0) return { base: spec.slice(0, at), version: spec.slice(at + 1) };
-	return { base: spec };
-}
-
-const basename = (p: string): string => p.split("/").pop() ?? p;
-
-/**
- * Map a plugin.json `setup` block (the established convention: browser-use uses
- * `pip`, terminal uses `go` + `required`) to BinRequirements.
- *   setup: { bun|npm|pip: string[], go: string[], brew: string[], required: string[] }
- */
-function parseSetup(setup: unknown): BinRequirement[] {
-	if (!setup || typeof setup !== "object") return [];
-	const s = setup as Record<string, unknown>;
-	const bins: BinRequirement[] = [];
-
-	const pkgManager = (key: "bun" | "npm" | "pip"): void => {
-		for (const spec of (s[key] as string[] | undefined) ?? []) {
-			if (typeof spec !== "string") continue;
-			const { base, version } = splitVersion(spec);
-			bins.push({
-				name: basename(base),
-				via: key,
-				package: base,
-				version,
-				check: `${basename(base)} --version`,
-			});
-		}
-	};
-	pkgManager("bun");
-	pkgManager("npm");
-	pkgManager("pip");
-
-	// Not basename(): a Go module's trailing /vN is its major version, not the
-	// binary. `tmux-mcp/v2` installs `tmux-mcp`; naming it `v2` here made every
-	// downstream presence check look for a binary that never exists.
-	for (const spec of (s.go as string[] | undefined) ?? []) {
-		if (typeof spec !== "string") continue;
-		const { base, version } = splitVersion(spec);
-		const name = goBinaryName(base);
-		bins.push({
-			name,
-			via: "go",
-			module: base,
-			version,
-			check: `${name} --version`,
-		});
-	}
-	for (const spec of (s.brew as string[] | undefined) ?? []) {
-		if (typeof spec !== "string") continue;
-		bins.push({
-			name: spec,
-			via: "brew",
-			formula: spec,
-			check: `${spec} --version`,
-		});
-	}
-	// `required` names a system tool that must be present; brew is the assumed
-	// installer (matches the "system tools via brew" decision).
-	for (const name of (s.required as string[] | undefined) ?? []) {
-		if (typeof name !== "string") continue;
-		bins.push({ name, via: "brew", formula: name, check: `${name} --version` });
-	}
-
-	return bins;
-}
-
-/**
- * Parse a plugin.json's binary requirements from BOTH the established `setup`
- * block and the richer explicit `requires.bin` form. On a name collision the
- * explicit `requires.bin` entry wins (it can override installer/check/version).
- */
-export function parsePluginRequires(pluginJson: unknown): PluginRequires {
-	if (!pluginJson || typeof pluginJson !== "object") return {};
-	const obj = pluginJson as Record<string, unknown>;
-
-	const fromSetup = parseSetup(obj.setup);
-
-	const requires = obj.requires;
-	const binRaw =
-		requires && typeof requires === "object"
-			? (requires as Record<string, unknown>).bin
-			: undefined;
-	const fromRequires = Array.isArray(binRaw)
-		? binRaw.map(normalizeBin).filter((b): b is BinRequirement => b !== null)
-		: [];
-
-	// Merge, requires.bin winning by name.
-	const byName = new Map<string, BinRequirement>();
-	for (const b of fromSetup) byName.set(b.name, b);
-	for (const b of fromRequires) byName.set(b.name, b);
-
-	const bin = [...byName.values()];
-	return bin.length > 0 ? { bin } : {};
-}
-
 /**
  * The plugin.json at a plugin directory, parsed — null when there is none or
  * it does not parse.
@@ -191,12 +60,15 @@ export async function readPluginManifest(
 	return null;
 }
 
-/** Read `requires` from a plugin.json at a known plugin directory. */
+/**
+ * `requires` from the plugin.json at a plugin directory, or null when there is
+ * no readable manifest there.
+ */
 export async function readPluginRequires(
 	pluginPath: string,
-): Promise<PluginRequires> {
-	// Unreadable/malformed — treat as no requirements.
-	return parsePluginRequires(await readPluginManifest(pluginPath));
+): Promise<ParseResult | null> {
+	const manifest = await readPluginManifest(pluginPath);
+	return manifest === null ? null : parseRequires(manifest);
 }
 
 /**
@@ -257,8 +129,8 @@ export interface PluginManifestSources {
  *      row its loader resolves there (`pickLoadedEntry`). Claude Code checks
  *      the dependencies of the version it loads, which may be older than the
  *      marketplace's latest;
- *   2. its source in the local marketplace clone (the reader `requires.bin`
- *      uses), for a plugin not installed yet;
+ *   2. its source in the local marketplace clone, for a plugin not installed
+ *      yet;
  *   3. any other installed copy — where a plugin whose marketplace entry
  *      points at another repository lives.
  */
@@ -337,14 +209,73 @@ export async function resolvePluginPath(
 }
 
 /**
- * Resolve the binary requirements a plugin declares. Returns an empty array
- * when the plugin can't be located or declares none.
+ * The `requires` of the copy of `pluginId` Claude Code loads in `projectPath`
+ * (else its marketplace clone), and the directory it was read from — the same
+ * plugin.json its SessionStart hook reads through ${CLAUDE_PLUGIN_ROOT}. Null
+ * when no plugin.json for it can be read on this machine.
+ */
+export async function resolvePluginRequires(
+	pluginId: string,
+	projectPath: string = process.cwd(),
+	sources: PluginManifestSources = {},
+): Promise<{ dir: string; parse: ParseResult } | null> {
+	for (const dir of await pluginManifestDirs(pluginId, projectPath, sources)) {
+		const parse = await readPluginRequires(dir);
+		if (parse !== null) return { dir, parse };
+	}
+	return null;
+}
+
+/**
+ * Each requirement that applies on this platform, with its option chosen for
+ * this machine — the first in declaration order whose prerequisite is on PATH
+ * or declared beside it ({@link selectOption}) — and the directory it was read
+ * from, which a `${CLAUDE_PLUGIN_ROOT}` check and a plugin-relative script
+ * resolve against.
+ */
+export function selectBins(
+	requirements: Requirement[],
+	root: string | undefined,
+	pathEnv: string = process.env.PATH ?? "",
+	platform: { os: Os; arch: Arch } | null = currentPlatform(),
+): SelectedBin[] {
+	if (!platform) return [];
+	const live = applicable(requirements, platform.os);
+	const names = new Set(live.map((r) => r.name));
+	const has = (tool: string) =>
+		names.has(tool) || onPath(tool, pathEnv) !== null;
+	return live.map((r) => ({
+		...r,
+		chosen: selectOption(r, platform, has),
+		...(root ? { root } : {}),
+	}));
+}
+
+/**
+ * The requirements a plugin declares, selected for this machine, from the copy
+ * Claude Code loads in `projectPath`. Empty when the plugin cannot be located,
+ * declares none, or its declaration does not parse (doctor and the plugin's
+ * own SessionStart hook report that one).
  */
 export async function resolvePluginBinRequirements(
 	pluginId: string,
-): Promise<BinRequirement[]> {
-	const pluginPath = await resolvePluginPath(pluginId);
-	if (!pluginPath) return [];
-	const requires = await readPluginRequires(pluginPath);
-	return requires.bin ?? [];
+	projectPath: string = process.cwd(),
+): Promise<SelectedBin[]> {
+	const found = await resolvePluginRequires(pluginId, projectPath);
+	if (!found?.parse.ok) return [];
+	return selectBins(found.parse.requirements, found.dir);
+}
+
+/**
+ * The requirement named `name` that `pluginId` declares — how a catalogue tool
+ * owned by a plugin is checked and installed — or null when that plugin's
+ * declaration cannot be read here or does not name it.
+ */
+export async function ownedRequirement(
+	pluginId: string,
+	name: string,
+	projectPath: string = process.cwd(),
+): Promise<SelectedBin | null> {
+	const bins = await resolvePluginBinRequirements(pluginId, projectPath);
+	return bins.find((b) => b.name === name) ?? null;
 }