magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/plugin-mcp-config.ts

@@ -0,0 +1,242 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+
+const CLAUDE_PLUGINS_DIR = path.join(
+	os.homedir(),
+	".claude",
+	"plugins",
+	"marketplaces",
+);
+
+/**
+ * Represents a required environment variable for a plugin's MCP server
+ */
+export interface PluginEnvRequirement {
+	/** The environment variable name (e.g., "FIGMA_ACCESS_TOKEN") */
+	name: string;
+	/** User-friendly label (defaults to name if not provided) */
+	label: string;
+	/** The MCP server name this env var is for */
+	serverName: string;
+	/** Whether this env var is required (all detected vars are considered required) */
+	required: boolean;
+}
+
+/**
+ * Extract ${VAR_NAME} patterns from a value
+ * @param value - The value to search for env var references
+ * @returns Array of env var names found
+ */
+function extractEnvVarReferences(value: unknown): string[] {
+	if (typeof value !== "string") return [];
+
+	const matches = value.match(/\$\{([A-Z_][A-Z0-9_]*)\}/g);
+	if (!matches) return [];
+
+	return matches
+		.map((match) => {
+			// Extract VAR_NAME from ${VAR_NAME}
+			const innerMatch = match.match(/\$\{([A-Z_][A-Z0-9_]*)\}/);
+			return innerMatch ? innerMatch[1] : "";
+		})
+		.filter(Boolean);
+}
+
+/**
+ * Recursively extract all env var references from an object
+ */
+function extractAllEnvVarReferences(obj: unknown): string[] {
+	const vars: string[] = [];
+
+	if (typeof obj === "string") {
+		vars.push(...extractEnvVarReferences(obj));
+	} else if (Array.isArray(obj)) {
+		for (const item of obj) {
+			vars.push(...extractAllEnvVarReferences(item));
+		}
+	} else if (obj && typeof obj === "object") {
+		for (const value of Object.values(obj)) {
+			vars.push(...extractAllEnvVarReferences(value));
+		}
+	}
+
+	return vars;
+}
+
+interface McpServerConfig {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	type?: "http";
+	url?: string;
+}
+
+/**
+ * Get the path to a plugin's mcp-config.json in the marketplace cache
+ * @param marketplaceName - Name of the marketplace (e.g., "magus")
+ * @param pluginSource - Plugin source path from marketplace.json (e.g., "./plugins/frontend")
+ * @returns Full path to mcp-config.json or undefined if not found
+ */
+function getPluginMcpConfigPath(
+	marketplaceName: string,
+	pluginSource?: string,
+): string | undefined {
+	if (!pluginSource) return undefined;
+
+	const marketplacePath = path.join(CLAUDE_PLUGINS_DIR, marketplaceName);
+	const pluginPath = path.join(
+		marketplacePath,
+		pluginSource.replace(/^\.\//, ""),
+	);
+	const mcpConfigPath = path.join(pluginPath, "mcp-servers", "mcp-config.json");
+
+	return mcpConfigPath;
+}
+
+/**
+ * Read and parse a plugin's MCP configuration
+ * @param marketplaceName - Name of the marketplace
+ * @param pluginSource - Plugin source path from marketplace.json
+ * @returns Parsed MCP config or empty object if not found
+ */
+export async function readPluginMcpConfig(
+	marketplaceName: string,
+	pluginSource?: string,
+): Promise<Record<string, McpServerConfig>> {
+	const configPath = getPluginMcpConfigPath(marketplaceName, pluginSource);
+	if (!configPath) return {};
+
+	try {
+		if (await fs.pathExists(configPath)) {
+			const content = await fs.readJson(configPath);
+			// Filter out comment fields (keys starting with _)
+			const filtered: Record<string, McpServerConfig> = {};
+			for (const [key, value] of Object.entries(content)) {
+				if (!key.startsWith("_") && value && typeof value === "object") {
+					filtered[key] = value as McpServerConfig;
+				}
+			}
+			return filtered;
+		}
+	} catch (error) {
+		console.error(`Failed to read plugin MCP config: ${error}`);
+	}
+
+	return {};
+}
+
+/**
+ * Generate user-friendly label from env var name
+ * @param varName - Environment variable name (e.g., "FIGMA_ACCESS_TOKEN")
+ * @returns Human-readable label (e.g., "Figma Access Token")
+ */
+function generateLabel(varName: string): string {
+	return varName
+		.split("_")
+		.map((word) => word.charAt(0) + word.slice(1).toLowerCase())
+		.join(" ");
+}
+
+/**
+ * Get all environment variable requirements for a plugin
+ * Extracts ${VAR_NAME} patterns from the plugin's mcp-config.json
+ *
+ * @param marketplaceName - Name of the marketplace (e.g., "magus")
+ * @param pluginSource - Plugin source path from marketplace.json (e.g., "./plugins/frontend")
+ * @returns Array of required env vars with metadata
+ */
+export async function getPluginEnvRequirements(
+	marketplaceName: string,
+	pluginSource?: string,
+): Promise<PluginEnvRequirement[]> {
+	const mcpConfig = await readPluginMcpConfig(marketplaceName, pluginSource);
+	const requirements: PluginEnvRequirement[] = [];
+	const seenVars = new Set<string>();
+
+	for (const [serverName, config] of Object.entries(mcpConfig)) {
+		// Extract from env object
+		if (config.env) {
+			for (const value of Object.values(config.env)) {
+				const vars = extractEnvVarReferences(value);
+				for (const varName of vars) {
+					if (!seenVars.has(varName)) {
+						seenVars.add(varName);
+						requirements.push({
+							name: varName,
+							label: generateLabel(varName),
+							serverName,
+							required: true,
+						});
+					}
+				}
+			}
+		}
+
+		// Also check args array for env var references (e.g., sqlite with ${DATABASE_PATH})
+		if (config.args) {
+			const argsVars = extractAllEnvVarReferences(config.args);
+			for (const varName of argsVars) {
+				if (!seenVars.has(varName)) {
+					seenVars.add(varName);
+					requirements.push({
+						name: varName,
+						label: generateLabel(varName),
+						serverName,
+						required: true,
+					});
+				}
+			}
+		}
+	}
+
+	return requirements;
+}
+
+/**
+ * Get plugin source path from local marketplace cache
+ * @param marketplaceName - Name of the marketplace
+ * @param pluginName - Name of the plugin
+ * @returns Plugin source path or undefined
+ */
+export async function getPluginSourcePath(
+	marketplaceName: string,
+	pluginName: string,
+): Promise<string | undefined> {
+	const marketplacePath = path.join(CLAUDE_PLUGINS_DIR, marketplaceName);
+	const manifestPath = path.join(
+		marketplacePath,
+		".claude-plugin",
+		"marketplace.json",
+	);
+
+	try {
+		if (await fs.pathExists(manifestPath)) {
+			const manifest = await fs.readJson(manifestPath);
+			if (manifest.plugins && Array.isArray(manifest.plugins)) {
+				const plugin = manifest.plugins.find(
+					(p: { name: string }) => p.name === pluginName,
+				);
+				return plugin?.source;
+			}
+		}
+	} catch {
+		// Return undefined if can't read
+	}
+
+	return undefined;
+}
+
+/**
+ * Get all MCP server names from a plugin's config
+ * @param marketplaceName - Name of the marketplace
+ * @param pluginSource - Plugin source path
+ * @returns Array of MCP server names
+ */
+export async function getPluginMcpServerNames(
+	marketplaceName: string,
+	pluginSource?: string,
+): Promise<string[]> {
+	const mcpConfig = await readPluginMcpConfig(marketplaceName, pluginSource);
+	return Object.keys(mcpConfig);
+}

package/src/services/plugin-releases.ts

@@ -0,0 +1,47 @@
+/**
+ * Normalisation for the `releases` array published in marketplace manifests.
+ *
+ * Lives apart from both readers because both need it: `marketplace-fetcher.ts`
+ * (manifest over the network) and `local-marketplace.ts` (same manifest from the
+ * on-disk cache). Putting it in either would make one import the other, and
+ * marketplace-fetcher was split out precisely to avoid importing local-marketplace,
+ * whose module-level `os.homedir()` constants contaminate the test suite.
+ */
+
+import type { PluginRelease } from "../types/index.js";
+
+/** Most release entries the panel will show, however many the manifest declares. */
+export const MAX_RELEASES = 5;
+
+/**
+ * Coerce a manifest `releases` value into renderable shape, or undefined.
+ *
+ * The remote manifest is fetched over the network from a repo whose contents we do
+ * not control at read time, so nothing about its shape may be assumed — a number
+ * where a string belongs, or a ten-thousand-entry array, would otherwise reach the
+ * renderer. Entries missing a version or summary are dropped rather than rendered
+ * blank, and the array is capped so one manifest cannot flood the detail panel.
+ */
+export function normalizeReleases(input: unknown): PluginRelease[] | undefined {
+	if (!Array.isArray(input)) return undefined;
+
+	const out: PluginRelease[] = [];
+	for (const raw of input.slice(0, MAX_RELEASES)) {
+		if (!raw || typeof raw !== "object") continue;
+		const r = raw as Record<string, unknown>;
+		if (typeof r.version !== "string" || typeof r.summary !== "string")
+			continue;
+		if (!r.version.trim() || !r.summary.trim()) continue;
+		out.push({
+			version: r.version.trim(),
+			...(typeof r.date === "string" && r.date.trim()
+				? { date: r.date.trim() }
+				: {}),
+			...(Array.isArray(r.kinds)
+				? { kinds: r.kinds.filter((k): k is string => typeof k === "string") }
+				: {}),
+			summary: r.summary.trim(),
+		});
+	}
+	return out.length > 0 ? out : undefined;
+}

package/src/services/plugin-requires.ts

@@ -0,0 +1,227 @@
+/**
+ * Read plugin-declared binary dependencies from plugin.json `requires.bin`.
+ *
+ * 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.
+ */
+
+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 { parsePluginId } from "../utils/string-utils.js";
+import { getLocalMarketplacesInfo } from "./plugin-manager.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 } : {};
+}
+
+/** Read `requires` from a plugin.json at a known plugin directory. */
+export async function readPluginRequires(
+	pluginPath: string,
+): Promise<PluginRequires> {
+	// `.claude-plugin/plugin.json` FIRST — that is the only location Claude Code's
+	// runtime loader reads, and the only one its documentation describes. The root
+	// fallback stays for third-party plugins whose authors put it there; such a manifest
+	// is inert as far as Claude Code is concerned, but magus can still read metadata
+	// out of it rather than reporting nothing.
+	const manifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
+	try {
+		if (await fs.pathExists(manifestPath)) {
+			return parsePluginRequires(await fs.readJson(manifestPath));
+		}
+		const rootLevel = path.join(pluginPath, "plugin.json");
+		if (await fs.pathExists(rootLevel)) {
+			return parsePluginRequires(await fs.readJson(rootLevel));
+		}
+	} catch {
+		// Unreadable/malformed — treat as no requirements.
+	}
+	return {};
+}
+
+/**
+ * Resolve a plugin id (name@marketplace) to its on-disk source directory in
+ * the local marketplace cache. Returns null if the marketplace/plugin/source
+ * can't be located. Mirrors doctor.ts's resolvePluginPath.
+ */
+export async function resolvePluginPath(
+	pluginId: string,
+): Promise<string | null> {
+	const parsed = parsePluginId(pluginId);
+	if (!parsed) return null;
+	const { pluginName, marketplace } = parsed;
+
+	const localMarketplaces = await getLocalMarketplacesInfo();
+	const localMp = localMarketplaces.get(marketplace);
+	if (!localMp) return null;
+
+	const localPlugin = localMp.plugins.find((p) => p.name === pluginName);
+	if (!localPlugin?.source || typeof localPlugin.source !== "string") {
+		return null;
+	}
+
+	const pluginPath = path.join(
+		MARKETPLACES_DIR(),
+		marketplace,
+		localPlugin.source.replace("./", ""),
+	);
+	return (await fs.pathExists(pluginPath)) ? pluginPath : null;
+}
+
+/**
+ * Resolve the binary requirements a plugin declares. Returns an empty array
+ * when the plugin can't be located or declares none.
+ */
+export async function resolvePluginBinRequirements(
+	pluginId: string,
+): Promise<BinRequirement[]> {
+	const pluginPath = await resolvePluginPath(pluginId);
+	if (!pluginPath) return [];
+	const requires = await readPluginRequires(pluginPath);
+	return requires.bin ?? [];
+}