magus-cli 7.7.0 → 7.9.0

package/src/services/resolver.ts

@@ -4,29 +4,38 @@
  * Turns a manifest entry into a fully-resolved {@link ResolvedClosure}: the
  * marketplaces, plugins, MCP servers, binary deps, skills, settings, and env a
  * machine must have to match the profile. Binary deps are the union of the
- * profile's own `cliTools` and every enabled plugin's declared `requires.bin`,
- * deduped by executable name with the project's pin winning. Plugins include
+ * profile's own `cliTools` and every enabled plugin's declared `requires`,
+ * merged by {@link mergeBins} with the project's pin winning. Plugins include
  * every plugin an enabled one declares as a dependency, transitively.
  */
 
 import semver from "semver";
-import { cliTools } from "../data/cli-tools.js";
+import { cliTools, isOwnedEntry } from "../data/cli-tools.js";
 import { getMarketplaceByName } from "../data/marketplaces.js";
 import { PREDEFINED_PROFILES } from "../data/predefined-profiles.js";
+import {
+	type InstallOption,
+	type Requirement,
+	dedupeKey,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
 import type {
-	BinRequirement,
 	DependencyReport,
 	ProfileManifest,
 	ProfileManifestEntry,
 	ResolvedBin,
 	ResolvedClosure,
+	SelectedBin,
 } from "../types/index.js";
 import { readManifest } from "./manifest.js";
 import {
 	type PluginDependencyReader,
 	readPluginDependencies,
 } from "./plugin-dependencies.js";
-import { resolvePluginBinRequirements } from "./plugin-requires.js";
+import {
+	ownedRequirement,
+	resolvePluginBinRequirements,
+	selectBins,
+} from "./plugin-requires.js";
 import { activeProfile } from "./profile-live.js";
 
 export interface ResolveOptions {
@@ -34,7 +43,15 @@ export interface ResolveOptions {
 	 * Resolve a plugin id to its declared binary requirements. Injectable for
 	 * tests; defaults to reading plugin.json from the marketplace cache.
 	 */
-	binResolver?: (pluginId: string) => Promise<BinRequirement[]>;
+	binResolver?: (pluginId: string) => Promise<SelectedBin[]>;
+	/**
+	 * The requirement a plugin declares for a catalogue tool it owns
+	 * (`ownedBy`). Defaults to reading that plugin's declaration here.
+	 */
+	ownedResolver?: (
+		pluginId: string,
+		name: string,
+	) => Promise<SelectedBin | null>;
 	/**
 	 * Resolve a plugin id to the plugin ids its plugin.json declares as
 	 * dependencies, or null when it cannot be read. Defaults to reading the
@@ -60,6 +77,7 @@ export async function resolveDependencies(
 	read: PluginDependencyReader,
 ): Promise<DependencyReport> {
 	const derived: string[] = [];
+	const requiredBy: Record<string, string> = {};
 	const unreadable: string[] = [];
 	const blocked: DependencyReport["blocked"] = [];
 	const queue = [...enabled];
@@ -75,13 +93,105 @@ export async function resolveDependencies(
 				blocked.push({ plugin: id, dependency });
 				continue;
 			}
+			// Every edge, including to a plugin the profile names itself: "still
+			// required" is a fact about the plugin that needs it, not about how
+			// the profile came to enable it. Recording only derived ones let a
+			// no-longer-published dependency the profile ALSO listed be planned
+			// for removal from under the plugin that needs it.
+			if (dependency !== id && !Object.hasOwn(requiredBy, dependency)) {
+				requiredBy[dependency] = id;
+			}
 			if (seen.has(dependency)) continue;
 			seen.add(dependency);
 			derived.push(dependency);
 			queue.push(dependency);
 		}
 	}
-	return { derived: derived.sort(), unreadable: unreadable.sort(), blocked };
+	return {
+		derived: derived.sort(),
+		requiredBy,
+		unreadable: unreadable.sort(),
+		blocked,
+	};
+}
+
+/**
+ * Which plugin requires each plugin, for the planner's STILL-REQUIRED rule:
+ * the profile's edges (`DependencyReport.requiredBy`) and, beside them, the
+ * edges every INSTALLED plugin's own plugin.json declares.
+ *
+ * The profile alone is not enough. A plugin installed at USER scope, or in a
+ * project with no profile at all, is planned too — and without its edges a
+ * dependency it needs that stopped being published was planned for removal
+ * from under it. One plugin.json read per installed plugin, the same read the
+ * profile's resolve makes. The profile's answer wins where both name one.
+ *
+ * ONE function for `magus update` and the Plugins screen, so the two plan the
+ * same removals.
+ */
+export async function requiredByHere(
+	profileRequiredBy: Readonly<Record<string, string>> | undefined,
+	installedIds: readonly string[],
+	projectPath?: string,
+	read: PluginDependencyReader = readPluginDependencies,
+): Promise<Record<string, string>> {
+	const all = await requirersHere(
+		profileRequiredBy,
+		installedIds,
+		projectPath,
+		read,
+	);
+	const first: Record<string, string> = {};
+	for (const [dependency, requirers] of Object.entries(all)) {
+		const [requirer] = requirers;
+		if (requirer) first[dependency] = requirer;
+	}
+	return first;
+}
+
+/**
+ * {@link requiredByHere} with EVERY requirer of each plugin, not only the
+ * first — what the planner needs to remove deprecated plugins that require
+ * one another together, while keeping one that anything staying still needs.
+ * The profile's requirer comes first; the installed plugins' follow, sorted.
+ *
+ * This is what `magus update` and the Plugins screen plan with.
+ */
+export async function requirersHere(
+	profileRequiredBy: Readonly<Record<string, string>> | undefined,
+	installedIds: readonly string[],
+	projectPath?: string,
+	read: PluginDependencyReader = readPluginDependencies,
+): Promise<Record<string, string[]>> {
+	const declared = await Promise.all(
+		[...installedIds].sort().map(async (id) => {
+			try {
+				return [id, await read(id, projectPath)] as const;
+			} catch {
+				return [id, null] as const;
+			}
+		}),
+	);
+	const edges: Record<string, string[]> = {};
+	const add = (dependency: string, requirer: string, front = false) => {
+		if (dependency === requirer) return;
+		const list = (
+			Object.hasOwn(edges, dependency) ? (edges[dependency] as string[]) : []
+		).filter((r) => !front || r !== requirer);
+		if (list.includes(requirer)) return;
+		if (front) list.unshift(requirer);
+		else list.push(requirer);
+		edges[dependency] = list;
+	};
+	for (const [id, dependencies] of declared) {
+		for (const dependency of dependencies ?? []) add(dependency, id);
+	}
+	for (const [dependency, requirer] of Object.entries(
+		profileRequiredBy ?? {},
+	)) {
+		add(dependency, requirer, true);
+	}
+	return edges;
 }
 
 function hasDependencies(report: DependencyReport): boolean {
@@ -142,84 +252,163 @@ export function resolveExtends(
 	};
 }
 
+/** The pin a selected requirement installs at, if its chosen option carries one. */
+export function pinOfBin(bin: SelectedBin): string | undefined {
+	const option = bin.chosen;
+	return option && "version" in option ? option.version : undefined;
+}
+
+/** The catalogue's check line as argv: split once, here, never by a shell. */
+const splitCheck = (line: string): string[] => line.trim().split(/\s+/);
+
 /**
- * Map a manifest cliTools entry (name -> version) to a BinRequirement.
+ * Map a manifest cliTools entry (name -> version) onto a requirement: the
+ * catalogue's installer as one option (`npm`/`pip`/`go` are the profile-only
+ * kinds), its check as argv, the pin carried in the option. A tool a plugin
+ * owns (`ownedBy`) is that plugin's declaration, passed in as `owned`, with
+ * the pin applied to its chosen option. An unknown tool installs with bun
+ * under its own name.
  *
  * Exported so the TUI's CLI Tools screen maps a catalogue tool the same way the
  * resolver does, rather than keeping a second copy of the mapping.
  */
-export function cliToolToBin(name: string, version: string): BinRequirement {
+export function cliToolToBin(
+	name: string,
+	version: string,
+	owned?: SelectedBin | null,
+): SelectedBin {
+	const pin = version && version !== "latest" ? version : undefined;
+	const carriesPin = (
+		o: InstallOption,
+	): o is Extract<InstallOption, { via: "bun" | "npm" | "pip" | "go" }> =>
+		o.via === "bun" || o.via === "npm" || o.via === "pip" || o.via === "go";
+	const withPin = (o: InstallOption): InstallOption =>
+		pin && carriesPin(o) ? { ...o, version: pin } : o;
+	if (owned) {
+		if (!owned.chosen) return owned;
+		// The plugin's option decides the version: a pin it cannot carry is
+		// kept as refused, so it is reported rather than lost.
+		return pin && !carriesPin(owned.chosen)
+			? { ...owned, refusedPins: [pin] }
+			: { ...owned, chosen: withPin(owned.chosen) };
+	}
 	const tool = cliTools.find((t) => t.name === name);
-	const pinned = version && version !== "latest" ? version : undefined;
-	if (tool) {
-		return {
-			name,
-			via: tool.packageManager,
-			package: tool.packageName,
-			check: tool.checkCommand,
-			version: pinned,
-		};
+	let option: InstallOption;
+	let check: string[];
+	if (tool && !isOwnedEntry(tool)) {
+		check = splitCheck(tool.checkCommand);
+		option =
+			tool.packageManager === "brew"
+				? { via: "brew", formula: tool.packageName }
+				: { via: tool.packageManager, package: tool.packageName };
+	} else {
+		check = [name, "--version"];
+		option = { via: "bun", package: name };
 	}
-	// Unknown tool: default to bun (magus's toolchain) with name as package.
+	const requirement: Requirement = { name, check, install: [withPin(option)] };
+	return (
+		selectBins([requirement], undefined)[0] ?? {
+			...requirement,
+			chosen: null,
+		}
+	);
+}
+
+/** The declaration of a requirement, without what selection and provenance add. */
+export function requirementOf(bin: Requirement): Requirement {
 	return {
-		name,
-		via: "bun",
-		package: name,
-		check: `${name} --version`,
-		version: pinned,
+		name: bin.name,
+		check: bin.check,
+		...(bin.os ? { os: bin.os } : {}),
+		install: bin.install,
 	};
 }
 
 /**
- * Dedupe binary requirements by executable name. Entries are processed in the
- * order given, so callers put higher-precedence sources first (project pins
- * before plugin-declared deps); the first entry's installer/version wins and
- * later ones only contribute provenance.
+ * The identity two requirements merge by: requires-probe's `dedupeKey` of the
+ * declaration, plus the plugin directory when the check reads
+ * `${CLAUDE_PLUGIN_ROOT}` — such a check is per plugin by nature.
  */
-export function dedupeBins(
-	entries: Array<{ bin: BinRequirement; source: string }>,
+export function binKey(bin: SelectedBin): string {
+	const key = dedupeKey(requirementOf(bin));
+	return bin.check.some((t) => t.includes("${CLAUDE_PLUGIN_ROOT}"))
+		? `${key}@${bin.root ?? ""}`
+		: key;
+}
+
+/**
+ * Merge selected requirements, in the order given — callers put higher
+ * precedence first (project pins before plugin declarations). Identical
+ * declarations merge (one entry, every source). A profile cliTools entry
+ * absorbs any later requirement of the same name: the project's pin is the
+ * decision. Two different plugin declarations of one name stay two entries,
+ * so neither hides the other.
+ */
+export function mergeBins(
+	entries: Array<{ bin: SelectedBin; source: string }>,
 ): ResolvedBin[] {
-	const byName = new Map<string, ResolvedBin>();
+	const out: ResolvedBin[] = [];
+	const byKey = new Map<string, ResolvedBin>();
+	const pinnedByName = new Map<string, ResolvedBin>();
 	for (const { bin, source } of entries) {
-		const existing = byName.get(bin.name);
+		const key = binKey(bin);
+		const existing = byKey.get(key) ?? pinnedByName.get(bin.name);
 		if (existing) {
 			if (!existing.sources.includes(source)) existing.sources.push(source);
-			// A later entry only fills a version the winner left unset.
-			if (existing.version === undefined && bin.version !== undefined) {
-				existing.version = bin.version;
-			}
 			continue;
 		}
-		byName.set(bin.name, { ...bin, sources: [source] });
+		const resolved: ResolvedBin = { ...bin, sources: [source] };
+		byKey.set(key, resolved);
+		if (source.startsWith("profile:")) pinnedByName.set(bin.name, resolved);
+		out.push(resolved);
+	}
+	return out;
+}
+
+/** A profile's own cliTools as selected requirements, with their source. */
+export async function cliToolBins(
+	entry: Pick<ProfileManifestEntry, "name" | "cliTools">,
+	ownedResolver: (
+		pluginId: string,
+		name: string,
+	) => Promise<SelectedBin | null> = ownedRequirement,
+): Promise<Array<{ bin: SelectedBin; source: string }>> {
+	const out: Array<{ bin: SelectedBin; source: string }> = [];
+	for (const [name, version] of Object.entries(entry.cliTools ?? {})) {
+		const tool = cliTools.find((t) => t.name === name);
+		const owned =
+			tool && isOwnedEntry(tool)
+				? await ownedResolver(tool.ownedBy, name)
+				: null;
+		out.push({
+			bin: cliToolToBin(name, version, owned),
+			source: `profile:${entry.name}.cliTools`,
+		});
 	}
-	return [...byName.values()];
+	return out;
 }
 
 /** Collect the binary requirements for a resolved plugin set + profile cliTools. */
 async function resolveBins(
 	entry: ProfileManifestEntry,
 	pluginIds: string[],
-	binResolver: (pluginId: string) => Promise<BinRequirement[]>,
+	binResolver: (pluginId: string) => Promise<SelectedBin[]>,
+	ownedResolver: (
+		pluginId: string,
+		name: string,
+	) => Promise<SelectedBin | null>,
 ): Promise<ResolvedBin[]> {
-	const collected: Array<{ bin: BinRequirement; source: string }> = [];
-
 	// Project pins first (highest precedence).
-	for (const [name, version] of Object.entries(entry.cliTools ?? {})) {
-		collected.push({
-			bin: cliToolToBin(name, version),
-			source: `profile:${entry.name}.cliTools`,
-		});
-	}
+	const collected = await cliToolBins(entry, ownedResolver);
 
-	// Then each plugin's declared binary deps.
+	// Then each plugin's declared requirements.
 	for (const pluginId of pluginIds) {
-		const bins = await binResolver(pluginId);
-		for (const bin of bins) {
+		for (const bin of await binResolver(pluginId)) {
 			collected.push({ bin, source: `plugin:${pluginId}` });
 		}
 	}
 
-	return dedupeBins(collected);
+	return mergeBins(collected);
 }
 
 /** Resolve a single profile (applying `extends`) into an install closure. */
@@ -293,6 +482,7 @@ export async function resolveProfile(
 	if (!raw) throw new Error(`Profile "${profileId}" not found in manifest`);
 	const entry = resolveExtends(raw);
 	const binResolver = opts.binResolver ?? resolvePluginBinRequirements;
+	const ownedResolver = opts.ownedResolver ?? ownedRequirement;
 
 	const plugins = normalizePlugins(entry.plugins);
 	const disabledPlugins = Object.entries(entry.plugins ?? {})
@@ -307,7 +497,12 @@ export async function resolveProfile(
 	);
 	for (const id of dependencies.derived) plugins[id] = "latest";
 
-	const bins = await resolveBins(entry, Object.keys(plugins), binResolver);
+	const bins = await resolveBins(
+		entry,
+		Object.keys(plugins),
+		binResolver,
+		ownedResolver,
+	);
 
 	return {
 		marketplaces: withDerivedMarketplaces(entry.marketplaces, plugins),
@@ -387,18 +582,26 @@ function mergeClosures(
 			continue;
 		}
 		const mergedSources = [...new Set([...existing.sources, ...bin.sources])];
-		const va = existing.version;
-		const vb = bin.version;
+		// Every profile's refused pin survives the union, whichever entry wins.
+		const refused = [
+			...new Set([...(existing.refusedPins ?? []), ...(bin.refusedPins ?? [])]),
+		];
+		const merged = (winner: ResolvedBin): ResolvedBin => ({
+			...winner,
+			sources: mergedSources,
+			...(refused.length > 0 ? { refusedPins: refused } : {}),
+		});
+		const va = pinOfBin(existing);
+		const vb = pinOfBin(bin);
 		if (va === undefined && vb === undefined) {
-			existing.sources = mergedSources;
+			binByName.set(bin.name, merged(existing));
 		} else if (va === undefined) {
-			binByName.set(bin.name, { ...bin, sources: mergedSources });
+			binByName.set(bin.name, merged(bin));
 		} else if (vb === undefined) {
-			existing.sources = mergedSources;
+			binByName.set(bin.name, merged(existing));
 		} else {
 			const { chosen, conflict } = pickVersion(bin.name, va, vb);
-			const winner = chosen === va ? existing : bin;
-			binByName.set(bin.name, { ...winner, sources: mergedSources });
+			binByName.set(bin.name, merged(chosen === va ? existing : bin));
 			if (conflict) conflicts.push(conflict);
 		}
 	}
@@ -444,6 +647,7 @@ function mergeDependencyReports(
 	);
 	return {
 		derived: [...new Set([...a.derived, ...b.derived])].sort(),
+		requiredBy: { ...b.requiredBy, ...a.requiredBy },
 		unreadable: [...new Set([...a.unreadable, ...b.unreadable])].sort(),
 		blocked: [...blocked.values()],
 	};

package/src/services/tool-probe.ts

@@ -43,11 +43,7 @@ import os from "node:os";
 import path from "node:path";
 import semver from "semver";
 import { CLAUDE_CODE_NPM_PACKAGE, type CliTool } from "../data/cli-tools.js";
-import type {
-	BinInstaller,
-	BinRequirement,
-	ResolvedBin,
-} from "../types/index.js";
+import type { BinInstaller, ManagedBin, ManagedTool } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import type { InstallMethod } from "./cli-tool-commands.js";
 import {
@@ -210,7 +206,7 @@ export function compareToolVersions(a: string, b: string): -1 | 0 | 1 | null {
 // ── The classifier ───────────────────────────────────────────────────────────
 
 /** The exact pin, or undefined for an unpinned (or "latest") requirement. */
-function pinOf(spec: BinRequirement): string | undefined {
+function pinOf(spec: ManagedTool): string | undefined {
 	const v = spec.version?.trim();
 	return v && v !== "latest" ? v : undefined;
 }
@@ -220,7 +216,7 @@ function withFailure(text: string, failure: string | undefined): string {
 }
 
 /** The `not-managed` sentence. Names the file and its owner, never the version. */
-function notManagedNote(spec: BinRequirement, facts: ToolFacts): string {
+function notManagedNote(spec: ManagedTool, facts: ToolFacts): string {
 	return facts.managed === false
 		? `on PATH at ${facts.resolvedPath ?? "?"}, which ${facts.owner ?? spec.via} does not own — upgrading through ${spec.via} would install a second copy`
 		: withFailure(
@@ -247,10 +243,7 @@ function notManagedNote(spec: BinRequirement, facts: ToolFacts): string {
  * rules are not displaced by it — they need a version to compare, and there is
  * none.
  */
-export function classifyTool(
-	spec: BinRequirement,
-	facts: ToolFacts,
-): ToolStatus {
+export function classifyTool(spec: ManagedTool, facts: ToolFacts): ToolStatus {
 	const pin = pinOf(spec);
 	const base = {
 		name: spec.name,
@@ -1027,7 +1020,7 @@ const SHELL_META = /[|&;<>()$`\\"'*?{}[\]~!#\n\r]/;
  * Refuse a name that could be read as an option, carries a NUL, or (for a
  * value joined into a path) climbs out of its directory. Null when fine.
  */
-function refusal(spec: BinRequirement): string | null {
+function refusal(spec: ManagedTool): string | null {
 	const bad = (v: string | undefined, isPath: boolean): boolean =>
 		v !== undefined &&
 		(v.startsWith("-") ||
@@ -1102,7 +1095,7 @@ async function packageJsonVersion(
  */
 async function versionFromCheck(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	onPath: string,
 ): Promise<void> {
@@ -1191,7 +1184,7 @@ async function containedIn(
 
 async function probeBrew(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	resolvedPath: string,
 ): Promise<void> {
@@ -1230,7 +1223,7 @@ async function probeBrew(
 
 async function probePip(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	onPath: string,
 	resolvedPath: string,
@@ -1361,7 +1354,7 @@ async function readNodePackage(
 
 async function probeNodeGlobal(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	resolvedPath: string,
 ): Promise<void> {
@@ -1495,7 +1488,7 @@ async function isNativeLauncher(
  */
 async function probeClaudeNative(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	onPath: string,
 	resolvedPath: string,
@@ -1532,7 +1525,7 @@ async function probeClaudeNative(
 
 async function probeGo(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 	resolvedPath: string,
 	pinned: boolean,
@@ -1585,7 +1578,7 @@ async function probeGo(
 /** Probe one tool into `f`, mutating it as facts arrive. Never throws. */
 async function probeInto(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	f: ToolFacts,
 ): Promise<void> {
 	const refused = refusal(spec);
@@ -1683,7 +1676,7 @@ function timedOut(f: ToolFacts, deadlineMs: number): ToolFacts {
 
 async function probeWithDeadline(
 	s: ProbeSession,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	deadlineAt: number,
 	deadlineMs: number,
 ): Promise<ToolFacts> {
@@ -1721,7 +1714,7 @@ async function probeWithDeadline(
  * facts with `failure` set, which classify as `unknown`, never `upgrade`.
  */
 export async function probeTools(
-	specs: readonly BinRequirement[],
+	specs: readonly ManagedTool[],
 	io: ToolProbeIO = REAL_TOOL_PROBE_IO,
 	opts: ProbeOptions = {},
 ): Promise<ToolFacts[]> {
@@ -1774,7 +1767,7 @@ export async function probeTools(
 
 /** One tool, with its own probe session. */
 export async function probeTool(
-	spec: BinRequirement,
+	spec: ManagedTool,
 	io: ToolProbeIO = REAL_TOOL_PROBE_IO,
 	opts: Omit<ProbeOptions, "concurrency" | "onResult"> = {},
 ): Promise<ToolFacts> {
@@ -1804,7 +1797,7 @@ function isBinInstaller(m: InstallMethod): m is BinInstaller & InstallMethod {
 /**
  * The spec a catalogue tool is probed through, in order:
  *
- *  1. the active profile's `ResolvedBin` of the same name — the same pin and
+ *  1. the active profile's `ManagedBin` of the same name — the same pin and
  *     the same installer `magus update` uses, so the two agree;
  *  2. the DETECTED installer, when it is one magus models — "how it IS
  *     installed", the rule `cliToolUpdate` follows, so the row's state and the
@@ -1814,9 +1807,9 @@ function isBinInstaller(m: InstallMethod): m is BinInstaller & InstallMethod {
  */
 export function specForCatalogTool(
 	tool: CliTool,
-	closureBins: readonly ResolvedBin[] | null,
+	closureBins: readonly ManagedBin[] | null,
 	install: InstallInfo | undefined,
-): BinRequirement {
+): ManagedTool {
 	const declared = closureBins?.find((b) => b.name === tool.name);
 	if (declared) return declared;
 	if (install && isBinInstaller(install.primary)) {