magus-cli 7.8.0 → 7.9.0

package/src/services/deps-report.ts

@@ -0,0 +1,265 @@
+/**
+ * What the plugins Claude Code loads here need on this machine, and what is
+ * missing: the dependency half of `magus doctor`.
+ *
+ * The plugin set is `enabledPlugins` across user, project and local scope, each
+ * read from the copy Claude Code loads (`resolvePluginRequires`), so it works
+ * with or without `.claude/profiles.json`. A project with profiles adds its
+ * profiles' own cliTools. Presence is requires-probe's `probe` at full depth,
+ * the plan is `planDeps`; this module only gathers and shapes, and prints
+ * nothing.
+ */
+
+import {
+	type Os,
+	type Presence,
+	describeStep,
+	onPath,
+	renderInstall,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type { ResolvedBin, SelectedBin } from "../types/index.js";
+import {
+	readGlobalSettings,
+	readLocalSettings,
+	readSettings,
+} from "./claude-settings.js";
+import {
+	type ApplyOutcome,
+	type DepsPlan,
+	type PathAdvice,
+	type PlanEnv,
+	planDeps,
+	prefixOf,
+	prefixOnPath,
+	requiredByOf,
+} from "./deps-plan.js";
+import { DOCTOR_CHECK_CAP_MS, probeBins } from "./doctor-bins.js";
+import { readManifest } from "./manifest.js";
+import { resolvePluginRequires, selectBins } from "./plugin-requires.js";
+import { binKey, cliToolBins, mergeBins } from "./resolver.js";
+
+/** The `--json` document's shape version. */
+export const DEPS_REPORT_SCHEMA = 1;
+
+export interface PluginParseProblem {
+	plugin: string;
+	kind: "invalid" | "newer-schema" | "older-schema";
+	errors: string[];
+}
+
+export interface CollectedDeps {
+	/** The enabled plugins whose declaration was read. */
+	plugins: string[];
+	bins: ResolvedBin[];
+	problems: PluginParseProblem[];
+}
+
+/** Where {@link collectDeps} reads; replaced in tests. */
+export interface CollectSources {
+	enabledPlugins(projectPath: string): Promise<string[]>;
+	pluginRequires: typeof resolvePluginRequires;
+	profileCliTools(
+		projectPath: string,
+	): Promise<Array<{ bin: SelectedBin; source: string }>>;
+}
+
+/** Plugin ids turned on here, user then project then local — Claude Code's precedence. */
+async function enabledHere(projectPath: string): Promise<string[]> {
+	const read = async (
+		f: () => Promise<{ enabledPlugins?: Record<string, boolean> }>,
+	) => {
+		try {
+			return (await f()).enabledPlugins ?? {};
+		} catch {
+			// An unparseable settings file is doctor's own finding elsewhere.
+			return {};
+		}
+	};
+	const merged = Object.assign(
+		{},
+		await read(readGlobalSettings),
+		await read(() => readSettings(projectPath)),
+		await read(() => readLocalSettings(projectPath)),
+	) as Record<string, boolean>;
+	return Object.keys(merged)
+		.filter((id) => merged[id] === true)
+		.sort();
+}
+
+/** Every profile's own cliTools, when the project has profiles. */
+async function profilesCliTools(
+	projectPath: string,
+): Promise<Array<{ bin: SelectedBin; source: string }>> {
+	let profiles: Record<string, { cliTools?: Record<string, string> }> = {};
+	try {
+		profiles = (await readManifest(projectPath)).profiles;
+	} catch {
+		return [];
+	}
+	const out: Array<{ bin: SelectedBin; source: string }> = [];
+	for (const [name, entry] of Object.entries(profiles)) {
+		out.push(...(await cliToolBins({ name, cliTools: entry.cliTools })));
+	}
+	return out;
+}
+
+export const REAL_COLLECT_SOURCES: CollectSources = {
+	enabledPlugins: enabledHere,
+	pluginRequires: resolvePluginRequires,
+	profileCliTools: profilesCliTools,
+};
+
+/** The requirements of everything loaded here, merged once. */
+export async function collectDeps(
+	projectPath: string,
+	sources: CollectSources = REAL_COLLECT_SOURCES,
+	/** Selection sees the PATH and platform the probe and the plan see. */
+	env?: PlanEnv,
+): Promise<CollectedDeps> {
+	const entries = await sources.profileCliTools(projectPath);
+	const plugins: string[] = [];
+	const problems: PluginParseProblem[] = [];
+	for (const id of await sources.enabledPlugins(projectPath)) {
+		const found = await sources.pluginRequires(id, projectPath);
+		// Not installed here: doctor's "Plugin loads" section says so.
+		if (!found) continue;
+		plugins.push(id);
+		if (!found.parse.ok) {
+			problems.push({
+				plugin: id,
+				kind: found.parse.kind,
+				errors: found.parse.errors,
+			});
+			continue;
+		}
+		const selected = selectBins(
+			found.parse.requirements,
+			found.dir,
+			env?.path,
+			env,
+		);
+		for (const bin of selected) {
+			entries.push({ bin, source: `plugin:${id}` });
+		}
+	}
+	return { plugins, bins: mergeBins(entries), problems };
+}
+
+export interface DepsState {
+	collected: CollectedDeps;
+	presences: Presence[];
+	plan: DepsPlan;
+}
+
+/** Probe collected requirements at full depth and plan — always a fresh probe. */
+export async function assessBins(
+	collected: CollectedDeps,
+	env: PlanEnv,
+): Promise<DepsState> {
+	const presences = await probeBins(collected.bins, {
+		env,
+		depth: "full",
+		capMs: DOCTOR_CHECK_CAP_MS,
+	});
+	return {
+		collected,
+		presences,
+		plan: planDeps(collected.bins, presences, env),
+	};
+}
+
+/** Collect what is loaded here, then {@link assessBins}. */
+export async function assessDeps(
+	projectPath: string,
+	env: PlanEnv,
+	sources?: CollectSources,
+): Promise<DepsState> {
+	return assessBins(await collectDeps(projectPath, sources, env), env);
+}
+
+// ─── the --json document ──────────────────────────────────────────────────────
+
+export interface DepJson {
+	name: string;
+	key: string;
+	status: Presence["status"];
+	requiredBy: string[];
+	blockedBy?: string;
+	prefix?: string;
+	reason?: string;
+	fix?: {
+		via: string;
+		escalation: "none" | "sudo";
+		text: string;
+		prefix?: string;
+		prefixOnPath?: boolean;
+	};
+}
+
+export interface DepsReportJson {
+	schema: typeof DEPS_REPORT_SCHEMA;
+	platform: { os: Os; arch: string };
+	magusOnPath: boolean;
+	plugins: string[];
+	deps: DepJson[];
+	plugins_needing_update: { plugin: string; kind: string; message: string }[];
+	invalid: { plugin: string; errors: string[] }[];
+	unfixable: { name: string; why: string }[];
+	pathAdvice: PathAdvice[];
+	applied?: ApplyOutcome[];
+}
+
+/** The one JSON document `magus doctor --json` prints. */
+export function depsReportJson(
+	state: DepsState,
+	env: PlanEnv,
+	applied?: ApplyOutcome[],
+): DepsReportJson {
+	const { collected, presences, plan } = state;
+	const deps = collected.bins.map((bin, i): DepJson => {
+		const p = presences[i] as Presence;
+		const entry: DepJson = {
+			name: bin.name,
+			key: binKey(bin),
+			status: p.status,
+			requiredBy: requiredByOf(bin),
+		};
+		if (p.status === "missing" && p.blockedBy) entry.blockedBy = p.blockedBy;
+		if (p.status === "off-path") entry.prefix = p.prefix;
+		if (p.status === "unknown") entry.reason = p.reason;
+		if (p.status !== "present" && bin.chosen) {
+			const step = renderInstall(bin, bin.chosen, {
+				...env,
+				pluginRoot: bin.root ?? "",
+			});
+			const prefix = prefixOf(step);
+			entry.fix = {
+				via: bin.chosen.via,
+				escalation: "escalation" in step ? step.escalation : "none",
+				text: describeStep(step, env.os),
+				...(prefix ? { prefix, prefixOnPath: prefixOnPath(prefix, env) } : {}),
+			};
+		}
+		return entry;
+	});
+	return {
+		schema: DEPS_REPORT_SCHEMA,
+		platform: { os: env.os, arch: env.arch },
+		magusOnPath: onPath("magus", env.path) !== null,
+		plugins: collected.plugins,
+		deps,
+		plugins_needing_update: collected.problems
+			.filter((p) => p.kind !== "invalid")
+			.map((p) => ({
+				plugin: p.plugin,
+				kind: p.kind,
+				message: p.errors.join("; "),
+			})),
+		invalid: collected.problems
+			.filter((p) => p.kind === "invalid")
+			.map((p) => ({ plugin: p.plugin, errors: p.errors })),
+		unfixable: plan.unfixable,
+		pathAdvice: plan.pathAdvice,
+		...(applied ? { applied } : {}),
+	};
+}

package/src/services/doctor-bins.ts

@@ -1,63 +1,135 @@
 /**
- * Binary-dependency check for `magus doctor`.
+ * Presence of resolved requirements, for `magus doctor`, `magus install` and
+ * `profile switch`.
  *
- * Verifies that every binary a profile's plugins declare (plugin.json
- * `requires.bin`) plus the profile's own cliTools is present on PATH. This is
- * the diagnostic that would have caught the dead `tmux-mcp` — a plugin's MCP
- * server silently failing because its binary was never installed.
+ * Presence is requires-probe's `probe` — the very function the SessionStart
+ * hook runs — so magus and the hook cannot disagree about whether a dependency
+ * is here. doctor probes at "full" depth (every declared check runs, with a
+ * long cap); the hook at "presence".
  */
 
+import {
+	type Presence,
+	type ProbeDepth,
+	type Requirement,
+	currentPlatform,
+	describeStep,
+	expandCheck,
+	onPath,
+	probe,
+	renderInstall,
+	whyUnselectable,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
 import type { ResolvedBin } from "../types/index.js";
-import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
-import { binInstallCommand } from "./toolchain.js";
+import type { PlanEnv } from "./deps-plan.js";
+
+/** doctor's per-check cap: long enough that a slow check is still definitive. */
+export const DOCTOR_CHECK_CAP_MS = 60_000;
+
+export interface ProbeBinsOptions {
+	env: PlanEnv;
+	depth: ProbeDepth;
+	capMs: number;
+}
+
+/** This machine, as planning and probing see it. Null on an unsupported platform. */
+export function machineEnv(
+	home: string,
+	path: string,
+	userShell: string,
+): PlanEnv | null {
+	const platform = currentPlatform();
+	return platform ? { ...platform, home, path, userShell } : null;
+}
+
+/**
+ * The probe's answer for each of `bins`, index-aligned. Each check's
+ * `${CLAUDE_PLUGIN_ROOT}` is expanded with its own plugin's directory, so one
+ * probe covers requirements from many plugins; requirements sharing a name are
+ * probed in separate passes, since a probe answers by name.
+ */
+export async function probeBins(
+	bins: readonly ResolvedBin[],
+	opts: ProbeBinsOptions,
+): Promise<Presence[]> {
+	const out: Presence[] = new Array(bins.length);
+	let pending = bins.map((bin, index) => ({ bin, index }));
+	while (pending.length > 0) {
+		const seen = new Set<string>();
+		const batch: typeof pending = [];
+		const later: typeof pending = [];
+		for (const item of pending) {
+			if (seen.has(item.bin.name)) later.push(item);
+			else {
+				seen.add(item.bin.name);
+				batch.push(item);
+			}
+		}
+		const reqs: Requirement[] = batch.map(({ bin }) => ({
+			name: bin.name,
+			check: expandCheck(bin, bin.root ?? ""),
+			install: bin.install,
+		}));
+		const answers = await probe(reqs, {
+			pluginRoot: process.cwd(),
+			os: opts.env.os,
+			arch: opts.env.arch,
+			home: opts.env.home,
+			path: opts.env.path,
+			capMs: opts.capMs,
+			depth: opts.depth,
+			userShell: opts.env.userShell,
+		});
+		const byName = new Map(answers.map((a) => [a.name, a]));
+		for (const { bin, index } of batch) {
+			out[index] = byName.get(bin.name) ?? {
+				name: bin.name,
+				status: "unknown",
+				reason: "not probed",
+			};
+		}
+		pending = later;
+	}
+	return out;
+}
+
+/** The line a person runs to install `bin` here, or why nothing can. */
+export function installText(bin: ResolvedBin, env: PlanEnv): string {
+	if (!bin.chosen) {
+		return whyUnselectable(bin, env, (t) => onPath(t, env.path) !== null);
+	}
+	return describeStep(
+		renderInstall(bin, bin.chosen, { ...env, pluginRoot: bin.root ?? "" }),
+		env.os,
+	);
+}
 
 export interface BinCheckResult {
 	name: string;
-	present: boolean;
-	/**
-	 * The command that would install it, shown when missing.
-	 *
-	 * A rendered string, not a {@link Command}: this is advisory text printed
-	 * after "run:" for a human to copy. Nothing executes it — doctor diagnoses
-	 * and never installs — so there is nothing here for a shell to re-parse.
-	 */
+	presence: Presence;
+	/** Advisory text after "run:" for a human to copy. Never executed. */
 	installCommand: string;
 	/** Where the requirement came from (profile cliTools / plugin ids). */
 	sources: string[];
 }
 
-/**
- * Check each resolved binary for presence on PATH. `isPresent` is injectable
- * for tests; it defaults to a real PATH lookup.
- *
- * The probes are deliberately SERIAL — a PATH walk per binary, each resolving
- * symlinks — so a profile declaring a dozen tools spends real time here. That
- * is what `onProbe` is for: it fires with the name about to be checked, before
- * the await, so a caller can name the binary it is currently blocked on rather
- * than showing a bare spinner.
- */
+/** Probe each bin and pair the answer with its install line. */
 export async function checkBinaries(
 	bins: ResolvedBin[],
-	// Default resolves symlinks + checks executability, so a dangling link
-	// (the tmux-mcp / npx-cache failure mode) reads as MISSING, not present.
-	isPresent: (name: string) => Promise<boolean> = async (name) =>
-		(await resolveExecutable(name)) !== null,
-	onProbe?: (name: string, index: number, total: number) => void,
+	opts: ProbeBinsOptions,
 ): Promise<BinCheckResult[]> {
-	const results: BinCheckResult[] = [];
-	for (const [index, bin] of bins.entries()) {
-		onProbe?.(bin.name, index, bins.length);
-		results.push({
-			name: bin.name,
-			present: await isPresent(bin.name),
-			installCommand: formatCommand(binInstallCommand(bin)),
-			sources: bin.sources,
-		});
-	}
-	return results;
+	const presences = await probeBins(bins, opts);
+	return bins.map((bin, i) => ({
+		name: bin.name,
+		presence: presences[i] as Presence,
+		installCommand: installText(bin, opts.env),
+		sources: bin.sources,
+	}));
 }
 
-/** Just the missing ones — the actionable subset. */
+/** The actionable subset: missing, or installed but not on PATH. */
 export function missingBinaries(results: BinCheckResult[]): BinCheckResult[] {
-	return results.filter((r) => !r.present);
+	return results.filter(
+		(r) => r.presence.status === "missing" || r.presence.status === "off-path",
+	);
 }

package/src/services/install-plan.ts

@@ -12,6 +12,7 @@ import type {
 	InstalledPluginsRegistry,
 	ResolvedClosure,
 } from "../types/index.js";
+import { pinOfBin } from "./resolver.js";
 
 export interface VersionDrift {
 	pluginId: string;
@@ -94,7 +95,16 @@ export function summarizeClosure(closure: ResolvedClosure): string[] {
 	if (mcps.length) lines.push(`mcp servers   ${mcps.join(", ")}`);
 	if (closure.bins.length) {
 		lines.push(
-			`cli tools     ${closure.bins.map((b) => (b.version ? `${b.name}@${b.version}` : b.name)).join(", ")}`,
+			`cli tools     ${closure.bins
+				.map((b) => {
+					const pin = pinOfBin(b);
+					if (pin) return `${b.name}@${pin}`;
+					const refused = b.refusedPins ?? [];
+					return refused.length > 0
+						? `${b.name}@${refused.join("|")} (pin not applied)`
+						: b.name;
+				})
+				.join(", ")}`,
 		);
 	}
 	if (closure.skills.length) {