magus-cli 7.10.3 → 7.10.4

package/src/cli/update.ts

@@ -77,6 +77,7 @@ import {
 } from "../services/update-engine.js";
 import {
 	type UpdatePlan,
+	binHeldBack,
 	planBinUpdates,
 	planHasWork,
 	planIsBehind,
@@ -98,7 +99,7 @@ import {
 	header,
 	info,
 	note as noteLine,
-	nothingToApplyNotice,
+	nothingToApplyLines,
 	ok as okLine,
 	pendingHeadline,
 	planReport,
@@ -106,7 +107,6 @@ import {
 	stepRecord,
 	summaryLine,
 	uncheckedGateNotice,
-	unknownToolsNotice,
 	warn as warnLine,
 } from "./update-view.js";
 import { setUpOtherWorktrees } from "./worktrees.js";
@@ -447,18 +447,25 @@ async function updateProfile(
 		const items = planBinUpdates(tools, facts);
 		const n = (a: string) => items.filter((i) => i.action === a).length;
 		const behind = n("upgrade");
-		const unknown = n("unknown");
+		const elsewhere = n("external");
+		// A held-back tool was checked: brew says it is behind and pinned.
+		const held = items.filter(binHeldBack).length;
+		const unchecked = n("unknown") - held;
 		const missing = n("install");
 		steps.binaries.detail = [
 			`${items.length} checked`,
 			behind > 0 ? `${behind} behind` : "",
-			unknown > 0 ? `${unknown} unknown` : "",
+			held > 0 ? `${held} held back` : "",
+			elsewhere > 0 ? `${elsewhere} installed elsewhere` : "",
+			unchecked > 0 ? `${unchecked} not checked` : "",
 			missing > 0 ? `${missing} missing` : "",
 			declaredOnly > 0 ? `${declaredOnly} managed by their declaration` : "",
 		]
 			.filter(Boolean)
 			.join(" · ");
-		if (missing + unknown > 0) steps.binaries.state = "warn";
+		// A warning only for a tool that is missing. Installed elsewhere is not a
+		// problem, and a tool that could not be checked is counted, not alarmed.
+		if (missing > 0) steps.binaries.state = "warn";
 		return facts;
 	});
 
@@ -505,21 +512,11 @@ async function updateProfile(
 	for (const line of planReport(plan)) console.log(line);
 
 	const counts = summarizePlan(plan);
-	const unknownToolNames = plan.bins
-		.filter((b) => b.action === "unknown")
-		.map((b) => b.name);
-	const toolUnknownLine = () =>
-		unknownToolsNotice(counts.unknownTools, unknownToolNames);
-	// No plugin equivalent of `toolUnknownLine`. Every unverified plugin is
-	// already a row in the table above, under a heading that names its state,
-	// so a trailing "N plugin(s) could not be checked" restated the table in
-	// prose and — since the grouping landed — miscounted it: the count is raw
-	// `unknown`, which now includes rows filed under Current. A tool has no
-	// such row, which is why that notice stays and names them.
-	if (counts.unknownTools > 0) {
-		console.log("");
-		console.log(toolUnknownLine());
-	}
+	// No trailing "N could not be checked" notice, for plugins or tools. Every
+	// unverified plugin is already a row under a heading that names its state,
+	// and every tool is counted by state in the CLI section's header — so such
+	// a notice only restated the table in prose, and for a tool installed
+	// another way it claimed a failure that never happened.
 
 	// `--check` gates on planIsBehind, not planHasWork. An already-installed
 	// skill is re-fetched on every apply because its manifest ref carries no
@@ -528,17 +525,29 @@ async function updateProfile(
 	//
 	// An `unknown` does not fail the gate, for plugins and tools alike (see
 	// planIsBehind). The same argument applies to both: a plugin whose
-	// marketplace publishes no version, or a tool another npm owns, is unknown
-	// permanently, so failing on it is the skill case again — this profile's 5
-	// unversioned official plugins made `--check` exit 1 on every run. A tool
-	// or plugin something says is BEHIND still does fail it. Because a failed
-	// check now passes silently by exit code, the unchecked count is printed
-	// beside the verdict; the per-kind notices and each row's reason are above.
+	// marketplace publishes no version is unknown permanently, so failing on it
+	// is the skill case again — this profile's 5 unversioned official plugins
+	// made `--check` exit 1 on every run. A tool installed another way is not
+	// unknown at all, and never fails it; nor does a held-back one, which only
+	// the user can release. A tool or plugin something says is
+	// BEHIND still does fail it. Because a failed check now passes silently by
+	// exit code, the unchecked count is printed beside the verdict.
 	if (flags.check) {
 		console.log("");
 		if (!planIsBehind(plan)) {
-			if (counts.unknown > 0) console.log(uncheckedGateNotice(counts.unknown));
-			console.log(okLine("Nothing missing and nothing behind."));
+			if (counts.unknown > 0)
+				console.log(
+					uncheckedGateNotice(counts.unknownPlugins, counts.unknownTools),
+				);
+			// A held-back tool is behind, so "nothing behind" would be false; it
+			// does not fail the gate because only the user can release the pin.
+			console.log(
+				okLine(
+					counts.heldBack > 0
+						? `Nothing missing, and nothing behind except ${counts.heldBack} held back.`
+						: "Nothing missing and nothing behind.",
+				),
+			);
 			return 0;
 		}
 		console.error(
@@ -563,21 +572,17 @@ async function updateProfile(
 			Date.now() - startedAt,
 			0,
 			counts.kept,
+			counts.external,
+			counts.heldBack,
 		))
 			console.log(line);
 		// `planHasWork` counts an `unknown` plugin as work, because from the
 		// planner's side "we could not check this" is genuinely not "this is
 		// fine". But nothing is APPLIED for an unknown — the apply loop skips it —
 		// so reporting on `planHasWork` alone claimed a run had happened when it
-		// had not. Say what is actually true instead.
-		if (counts.unknownPlugins + counts.unknownTools > 0) {
-			if (counts.unknownPlugins > 0) {
-				console.log(nothingToApplyNotice(counts.unknownPlugins));
-			}
-			if (counts.unknownTools > 0) console.log(toolUnknownLine());
-			return 0;
-		}
-		console.log(okLine("Everything is up to date."));
+		// had not. Say what is actually true instead: "Everything is up to date"
+		// only when nothing went unchecked and nothing is held back.
+		for (const line of nothingToApplyLines(counts)) console.log(line);
 		return 0;
 	}
 
@@ -697,6 +702,8 @@ async function updateProfile(
 		Date.now() - startedAt,
 		outcome.unchanged.length,
 		counts.kept,
+		counts.external,
+		counts.heldBack,
 	))
 		console.log(line);
 

package/src/data/cli-tools.ts

@@ -21,8 +21,12 @@ interface CatalogueDisplay {
 	category: "ai-coding" | "utility";
 }
 
+/**
+ * There is no `checkCommand` field either: how magus asks a tool its version
+ * is `data/tool-versions.ts`, the one table, so each tool's version command
+ * exists once.
+ */
 export interface CliTool extends CatalogueDisplay {
-	checkCommand: string;
 	/**
 	 * Reuses `BinInstaller` rather than restating its members, so the
 	 * correspondence with the resolver in `services/toolchain.ts` — which is
@@ -62,7 +66,6 @@ export const cliTools: CatalogueEntry[] = [
 		displayName: "magus",
 		description:
 			"TUI tool for managing Claude Code plugins, MCPs, and configuration",
-		checkCommand: "magus --version",
 		website: "https://github.com/MadAppGang/magus/tree/main/tools/magus",
 		category: "ai-coding",
 		packageManager: "bun",
@@ -91,7 +94,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "claude",
 		displayName: "Claude Code",
 		description: "Anthropic official agentic coding tool",
-		checkCommand: "claude --version",
 		website: "https://claude.ai/code",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -102,7 +104,6 @@ export const cliTools: CatalogueEntry[] = [
 		displayName: "OpenAI Codex",
 		description:
 			"Lightweight coding agent from OpenAI that runs in your terminal",
-		checkCommand: "codex --version",
 		website: "https://github.com/openai/codex",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -112,7 +113,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "gemini",
 		displayName: "Gemini CLI",
 		description: "Google AI agent with 1M token context, free tier available",
-		checkCommand: "gemini --version",
 		website: "https://github.com/google-gemini/gemini-cli",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -122,7 +122,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "qwen",
 		displayName: "Qwen Code",
 		description: "Alibaba coding agent optimized for Qwen3-Coder models",
-		checkCommand: "qwen --version",
 		website: "https://github.com/QwenLM/qwen-code",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -133,7 +132,6 @@ export const cliTools: CatalogueEntry[] = [
 		displayName: "Cline",
 		description:
 			"Autonomous coding agent with plan & act, checkpoints, browser use",
-		checkCommand: "cline --version",
 		website: "https://cline.bot",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -143,7 +141,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "opencode",
 		displayName: "OpenCode",
 		description: "Open source AI coding agent trusted by 400k+ developers",
-		checkCommand: "opencode --version",
 		website: "https://opencode.ai",
 		category: "ai-coding",
 		packageManager: "npm",
@@ -153,7 +150,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "aider",
 		displayName: "Aider",
 		description: "AI pair programming - works with Claude, GPT-4, local models",
-		checkCommand: "aider --version",
 		website: "https://aider.chat",
 		category: "ai-coding",
 		packageManager: "pip",
@@ -163,7 +159,6 @@ export const cliTools: CatalogueEntry[] = [
 		name: "crush",
 		displayName: "Crush",
 		description: "AI coding assistant from Charm with terminal-native UX",
-		checkCommand: "crush --version",
 		website: "https://github.com/charmbracelet/crush",
 		category: "ai-coding",
 		packageManager: "npm",

package/src/data/tool-versions.ts

@@ -0,0 +1,137 @@
+/**
+ * tool-versions.ts — how magus asks a CLI tool its version. ONE table.
+ *
+ * A version is read from exactly two places: the installer's own record (brew
+ * list, the npm/bun global package, uv/pipx, go build info), or the command
+ * below. Nothing else. magus used to guess when the installer was silent — a
+ * `package.json` above a `node_modules` path, a `versions/<n>` folder name, the
+ * first version-like token of whatever a plugin's `check` string printed — and
+ * a guess is how a row shows a version nobody ran.
+ *
+ * Because magus wrote every argv here, the probe may run it while PLANNING,
+ * including `--dry-run` and `--check`. A plugin manifest's `requires.bin[].check`
+ * is a string a third party wrote, and the update probe never runs it.
+ *
+ * Every entry is pinned by a test to a line of real output captured from the
+ * tool (`__tests__/tool-versions.test.ts`). Each pattern is anchored at both
+ * ends and is tested against the FIRST non-empty line only, so a trailing
+ * "Update available: v0.36.2" notice can never be read as the version. A tool
+ * whose output was never captured has no entry: it still gets a version when
+ * its installer's record has one, and shows none otherwise.
+ *
+ * Imports nothing: the probe, the resolver and the catalogue all read it.
+ */
+
+export interface ToolVersionCommand {
+	/**
+	 * Arguments after the executable. argv[0] is ALWAYS the tool's own name,
+	 * resolved by PATH — so the version read is the version of the file PATH
+	 * runs.
+	 */
+	readonly args: readonly string[];
+	/**
+	 * Tested against the first non-empty line of stdout (of stderr when stdout
+	 * is empty). Group 1 is the version. Anchored at both ends.
+	 */
+	readonly parse: RegExp;
+}
+
+/** `X.Y.Z`, with an optional prerelease suffix. */
+const V = String.raw`(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)`;
+const anchored = (body: string): RegExp => new RegExp(`^${body}$`);
+
+/**
+ * A `Map`, never a bare object: a plugin may declare a bin named after an
+ * Object.prototype key ("constructor"), and that must not find a "command".
+ */
+const TABLE: ReadonlyMap<string, ToolVersionCommand> = new Map<
+	string,
+	ToolVersionCommand
+>([
+	// `claudish version 10.4.1`
+	[
+		"claudish",
+		{ args: ["--version"], parse: anchored(`claudish version v?${V}`) },
+	],
+	// `jq-1.8.2`; jq 1.6 prints `jq-1.6`. A dev build `jq-1.7.1-dirty` keeps its
+	// suffix, so it never compares equal to brew's 1.7.1.
+	[
+		"jq",
+		{
+			args: ["--version"],
+			parse: /^jq-(\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?)$/,
+		},
+	],
+	// `mnemex v0.36.1`, then update-notice lines the first-line rule ignores.
+	["mnemex", { args: ["--version"], parse: anchored(`mnemex v${V}`) }],
+	// `tmux 3.7c`. HEAD builds (`tmux next-3.7`, `tmux master`) give null on
+	// purpose: they have no release to compare with.
+	["tmux", { args: ["-V"], parse: /^tmux (\d+\.\d+[a-z]?)$/ }],
+	// `uv 0.11.15 (3cffe97c2 2026-05-18 aarch64-apple-darwin)`
+	["uv", { args: ["--version"], parse: anchored(`uv ${V}(?: \\(.*\\))?`) }],
+	// `zsh 5.9 (arm64-apple-darwin26.0)`
+	[
+		"zsh",
+		{
+			args: ["--version"],
+			parse: /^zsh (\d+\.\d+(?:\.\d+)*(?:-[0-9A-Za-z.]+)?) \(.+\)$/,
+		},
+	],
+	// `magus v7.9.0`, then update-notice lines.
+	["magus", { args: ["--version"], parse: anchored(`magus v${V}`) }],
+	// `2.1.293 (Claude Code)`
+	[
+		"claude",
+		{ args: ["--version"], parse: anchored(`${V} \\(Claude Code\\)`) },
+	],
+	// `codex-cli 0.153.2`
+	["codex", { args: ["--version"], parse: anchored(`codex-cli ${V}`) }],
+	// `0.46.0`
+	["gemini", { args: ["--version"], parse: anchored(V) }],
+	// `1.17.11`
+	["opencode", { args: ["--version"], parse: anchored(V) }],
+	// `crush version v0.55.0`
+	["crush", { args: ["--version"], parse: anchored(`crush version v${V}`) }],
+]);
+
+/** The version command magus defines for `name`, or undefined when it has none. */
+export function toolVersionCommand(
+	name: string,
+): ToolVersionCommand | undefined {
+	return TABLE.get(name);
+}
+
+/** The first non-empty line, trimmed; "" when there is none. */
+function firstLine(text: string): string {
+	return (
+		text
+			.split("\n")
+			.find((l) => l.trim())
+			?.trim() ?? ""
+	);
+}
+
+/**
+ * The version in a tool's output, or null when the first non-empty line is
+ * not one the pattern anchors. stdout is read; stderr only when stdout says
+ * nothing (tmux and some older tools print their version there).
+ */
+export function parseToolVersion(
+	cmd: ToolVersionCommand,
+	stdout: string,
+	stderr: string,
+): string | null {
+	const line = firstLine(stdout) || firstLine(stderr);
+	if (!line) return null;
+	return cmd.parse.exec(line)?.[1] ?? null;
+}
+
+/**
+ * The presence check argv for a tool magus maps itself (a catalogue entry, a
+ * profile cliTool): its version command when the table knows it, else
+ * `<name> --version`. Built here so the version command exists once.
+ */
+export function presenceArgv(name: string): string[] {
+	const cmd = toolVersionCommand(name);
+	return [name, ...(cmd ? cmd.args : ["--version"])];
+}

package/src/services/cli-tool-commands.ts

@@ -83,7 +83,6 @@ export function ownedCliTool(
 		description,
 		website,
 		category,
-		checkCommand: owned.check.join(" "),
 		packageManager: managed.via,
 		packageName:
 			managed.package ?? managed.formula ?? managed.module ?? owned.name,
@@ -159,7 +158,7 @@ export type InstallMethod =
  * Entries used to carry a literal `installCommand` string beside the
  * `packageManager` and `packageName` that describe the same thing, so the two
  * could disagree — and did. `aider` declared `packageName: "aider-chat"` and
- * `checkCommand: "aider --version"`, and its `installCommand` installed
+ * checked its version with `aider --version`, and its `installCommand` installed
  * `aider-install`: a bootstrapper whose version nothing in this screen ever
  * looked at, while the version check queried `aider-chat`. Deriving makes that
  * disagreement unrepresentable rather than merely fixed.

package/src/services/cli-tool-version.ts

@@ -1,101 +1,23 @@
-import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 
-/**
- * The version of the npm/bun package a binary on PATH belongs to.
- *
- * A global install leaves `<prefix>/bin/<tool>` as a symlink into
- * `<prefix>/lib/node_modules/<package>/…` (npm) or
- * `~/.bun/install/global/node_modules/<package>/…` (bun). The package's own
- * `package.json` is therefore the authority on what is installed, and reading
- * it needs neither an installer record nor running the tool.
- *
- * The walk starts from the binary's REAL location — the symlink is resolved
- * first, chain and all — because the directory the symlink sits in can belong
- * to some unrelated project whose `package.json` would answer wrongly. The
- * nearest `package.json` carrying both `name` and `version` wins; the partial
- * ones a build leaves in `dist/` (`{"type":"module"}`) are skipped.
- *
- * Never throws: a missing binary, a dangling link, an unreadable or unparseable
- * manifest, and "no package at all" are all `null`.
- */
-export function readPackageVersionForBin(binPath: string): string | null {
-	let real: string;
-	try {
-		real = realpathSync(binPath);
-	} catch {
-		return null;
-	}
-
-	let dir = path.dirname(real);
-	for (;;) {
-		const version = qualifyingVersion(path.join(dir, "package.json"));
-		if (version !== undefined) return version;
-		const parent = path.dirname(dir);
-		if (parent === dir) return null;
-		dir = parent;
-	}
-}
-
 /** A bare release number, as a versioned install directory names its files. */
 const RELEASE = /^v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 
 /**
- * The version a VERSIONED INSTALL names its binary by, or `null`.
- *
- * Some installers keep every release side by side and point PATH at one:
- * Claude Code's native installer links `~/.local/bin/claude` to
- * `~/.local/share/claude/versions/2.1.276`. There is no package.json there to
- * read, but the file's own name IS the version — accepted only when the real
- * path's parent directory is literally `versions` and the name is a bare
- * release number, so an ordinary binary called `1.0.0` is not misread.
+ * The version a VERSIONED INSTALL names its binary by, or `null`, from a path
+ * that is ALREADY real — pure string work, no filesystem. The probe resolves
+ * paths through its own IO seam and must not reach past it to the real disk.
  *
- * Reads no file and runs nothing; never throws.
- */
-export function readVersionDirForBin(binPath: string): string | null {
-	let real: string;
-	try {
-		real = realpathSync(binPath);
-	} catch {
-		return null;
-	}
-	return versionFromVersionedPath(real);
-}
-
-/**
- * The same reading as {@link readVersionDirForBin}, from a path that is ALREADY
- * real — pure string work, no filesystem. The probe resolves paths through its
- * own IO seam and must not reach past it to the real disk.
+ * Claude Code's native installer keeps every release side by side and points
+ * PATH at one: `~/.local/bin/claude` links to
+ * `~/.local/share/claude/versions/2.1.276`. That installer's record IS the file
+ * name — accepted only when the parent directory is literally `versions` and
+ * the name is a bare release number, so an ordinary binary called `1.0.0` is
+ * not misread. The probe calls this only once it has confirmed the layout is
+ * that installer's own.
  */
 export function versionFromVersionedPath(realPath: string): string | null {
 	const name = path.basename(realPath);
 	if (path.basename(path.dirname(realPath)) !== "versions") return null;
 	return RELEASE.test(name) ? name.replace(/^v/, "") : null;
 }
-
-/**
- * The manifest's version when it names both a package and a version.
- *
- * `undefined` means "not a package root, keep walking"; `null` means "this is
- * the package root, and it cannot be read" — the walk stops there rather than
- * letting an enclosing workspace answer for a package it does not own.
- */
-function qualifyingVersion(file: string): string | null | undefined {
-	let text: string;
-	try {
-		text = readFileSync(file, "utf8");
-	} catch {
-		return undefined;
-	}
-	let manifest: unknown;
-	try {
-		manifest = JSON.parse(text);
-	} catch {
-		return null;
-	}
-	if (manifest === null || typeof manifest !== "object") return undefined;
-	const { name, version } = manifest as Record<string, unknown>;
-	if (typeof name !== "string" || name === "") return undefined;
-	if (typeof version !== "string" || version === "") return undefined;
-	return version;
-}

package/src/services/resolver.ts

@@ -13,6 +13,7 @@ import semver from "semver";
 import { cliTools, isOwnedEntry } from "../data/cli-tools.js";
 import { getMarketplaceByName } from "../data/marketplaces.js";
 import { PREDEFINED_PROFILES } from "../data/predefined-profiles.js";
+import { presenceArgv } from "../data/tool-versions.js";
 import {
 	type InstallOption,
 	type Requirement,
@@ -258,13 +259,11 @@ export function pinOfBin(bin: SelectedBin): string | undefined {
 	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) 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
+ * kinds), magus's own version command as the check (`presenceArgv`), 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.
@@ -293,18 +292,13 @@ export function cliToolToBin(
 			: { ...owned, chosen: withPin(owned.chosen) };
 	}
 	const tool = cliTools.find((t) => t.name === name);
-	let option: InstallOption;
-	let check: string[];
-	if (tool && !isOwnedEntry(tool)) {
-		check = splitCheck(tool.checkCommand);
-		option =
-			tool.packageManager === "brew"
+	const check = presenceArgv(name);
+	const option: InstallOption =
+		tool && !isOwnedEntry(tool)
+			? tool.packageManager === "brew"
 				? { via: "brew", formula: tool.packageName }
-				: { via: tool.packageManager, package: tool.packageName };
-	} else {
-		check = [name, "--version"];
-		option = { via: "bun", package: name };
-	}
+				: { via: tool.packageManager, package: tool.packageName }
+			: { via: "bun", package: name };
 	const requirement: Requirement = { name, check, install: [withPin(option)] };
 	return (
 		selectBins([requirement], undefined)[0] ?? {