magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/update-plan.ts

@@ -0,0 +1,863 @@
+/**
+ * The ONE place plugin state is decided, and the planning for `magus update`.
+ *
+ * `classifyPlugin` answers "what state is this plugin in, and why" for a plugin
+ * id, the version the profile pins it to, and the catalog. Every consumer reads
+ * its answer and nothing else: `magus update`'s plan, and in the TUI the
+ * Plugins row text, the detail panel, the header counts, the `U`/`a` actions
+ * and the scope picker. The TUI used to derive the same state from raw
+ * `PluginInfo` flags with its own rules, and the two front ends drifted — the
+ * same plugin, in the same project, could read green in one and red in the
+ * other, or carry a different reason in each.
+ *
+ * Tools follow the same rule: `planBinUpdates` plans from `classifyTool`
+ * (services/tool-probe.ts), the same classifier the TUI's CLI Tools screen
+ * renders, so a tool has one state in both front ends.
+ *
+ * `install` makes the machine match the manifest's pins. `update` advances it:
+ * anything the active profile declares but the machine lacks gets installed,
+ * and anything pinned "latest" moves to the newest version the marketplace
+ * catalog offers. Everything here is a pure function of a closure plus captured
+ * machine state, so the decisions are unit-testable and the callers only do IO.
+ *
+ * The one rule worth stating out loud: "cannot tell" must never be reported as
+ * "up to date". `PluginInfo.updateCheckFailed` exists because a rate-limited
+ * fetch once compared the installed version against a stale local clone, found
+ * them equal, and rendered the failure as a clean bill of health. That case, and
+ * every other one where the answer is not provable, gets its own action
+ * (`unknown`) rather than folding into `current`.
+ */
+
+import type { ProfileSkillRef, ResolvedBin } from "../types/index.js";
+import type { PluginScope } from "./claude-cli.js";
+import {
+	type PluginInfo,
+	compareVersions,
+	isBehind,
+} from "./plugin-manager.js";
+import {
+	type ToolFacts,
+	type ToolReason,
+	type ToolState,
+	type ToolStatus,
+	classifyTool,
+} from "./tool-probe.js";
+
+// ── Plugins ──────────────────────────────────────────────────────────────────
+
+export type PluginUpdateAction =
+	/** Declared by the profile, installed nowhere. */
+	| "install"
+	/** Installed at a version other than the one we should be on. */
+	| "update"
+	/** Same version, different files — only a reinstall delivers the content. */
+	| "repair"
+	/** Already on the right version. */
+	| "current"
+	/** The catalog check failed; we cannot claim either way. */
+	| "unknown";
+
+/**
+ * WHY a plugin is in its state — a machine code, so tests and styling can key
+ * on it without parsing the human `note`.
+ */
+export type PluginReason =
+	/** install: declared by the profile, installed nowhere. */
+	| "absent"
+	/** install: enabled in a settings file, but no registry row in any scope. */
+	| "enabled-not-installed"
+	/** unknown: a marketplace we READ does not list it. */
+	| "not-offered"
+	/** unknown: installed, unlisted, and another marketplace publishes the name. */
+	| "moved"
+	/** unknown: installed, unlisted, and its marketplace contributed no listed ids. */
+	| "marketplace-unread"
+	/** unknown: the catalog fetch failed ("latest" pins only). */
+	| "catalog-unverified"
+	/** unknown: listed, but its marketplace publishes no version for it. */
+	| "no-published-version"
+	/** unknown: an installed scope cannot be ordered against the target. */
+	| "unorderable"
+	/** repair: files changed without a version bump. */
+	| "content-stale"
+	/** update: a scope is provably behind. */
+	| "behind"
+	/** current|update: an exact pin differs from what the marketplace offers. */
+	| "pin-undeliverable"
+	/** current: every installed scope is at (or ahead of) the target. */
+	| "up-to-date";
+
+export interface PluginUpdateItem {
+	pluginId: string;
+	/** What the profile pins: an exact version, or "latest". */
+	pinned: string;
+	/** Highest version installed in any scope, or null when absent. */
+	installed: string | null;
+	/** Version the marketplace catalog offers, or null when unknown. */
+	available: string | null;
+	/** Version this item would move to. Null for `current`/`unknown`. */
+	target: string | null;
+	action: PluginUpdateAction;
+	/** Why it is in this state. */
+	reason: PluginReason;
+	/** Scopes holding an install this action must touch. Empty for a fresh install. */
+	scopes: PluginScope[];
+	/**
+	 * The version installed in each scope BEFORE any work, so an apply can tell
+	 * by reading back whether anything actually moved.
+	 */
+	beforeVersions: Partial<Record<PluginScope, string>>;
+	/**
+	 * The exact human reason. The CLI prints it and the TUI shows it verbatim, so
+	 * it is the SAME string in both front ends.
+	 */
+	note?: string;
+}
+
+/** Scope → installed version, for the three scopes a PluginInfo carries. */
+function scopeVersions(
+	info: PluginInfo | undefined,
+): Array<[PluginScope, string]> {
+	if (!info) return [];
+	const out: Array<[PluginScope, string]> = [];
+	for (const [scope, status] of [
+		["user", info.userScope],
+		["project", info.projectScope],
+		["local", info.localScope],
+	] as const) {
+		if (status?.version) out.push([scope, status.version]);
+	}
+	return out;
+}
+
+/**
+ * The highest version installed across scopes, or null.
+ *
+ * `compareVersions` answers null for an unorderable pair, and null is not
+ * `>= 0`, so the reduce keeps the right-hand side when two versions cannot be
+ * ranked. "Highest" is not meaningful across commit ids; picking one
+ * deterministically is, and every caller only needs *an* installed version.
+ */
+function highestInstalled(info: PluginInfo | undefined): string | null {
+	const versions = scopeVersions(info).map(([, v]) => v);
+	if (versions.length === 0) return null;
+	return versions.reduce((a, b) =>
+		(compareVersions(a, b) ?? -1) >= 0 ? a : b,
+	);
+}
+
+/**
+ * Scopes that are strictly BEHIND `target`.
+ *
+ * Every scope that holds an outdated install is returned, not just "user".
+ * Updating one hardcoded scope does not converge: drift is detected from the
+ * CURRENT PROJECT's resolved version, so "fixing" user scope reports success
+ * and leaves the project row untouched, and the same drift reappears on the
+ * next run.
+ *
+ * This only ever moves FORWARD, and there is deliberately no option to do
+ * otherwise. Nothing here can perform a downgrade: `claude plugin install`
+ * installs the newest published version and takes no version argument. So a
+ * scope ahead of the target is not a problem to fix — it is a state this tool
+ * cannot change, and planning against it produces a move that runs, appears to
+ * succeed, lands on the same version as before, and is replanned identically on
+ * the next run.
+ *
+ * A "not equal to target" comparison lived here briefly, on the theory that an
+ * explicit pin is absolute and moving down to it is as correct as moving up.
+ * Both halves were wrong: the pin is not deliverable, and the downgrade is not
+ * performable.
+ */
+export function scopesNeeding(
+	info: PluginInfo | undefined,
+	target: string,
+): PluginScope[] {
+	// `isBehind`, not a raw compare: a scope holding a commit sha that differs
+	// from the published one IS behind, even though the two carry no ordering.
+	// A raw `compareVersions(...) > 0` reported false for that pair and the
+	// scope was silently left alone. An unknown (null) is still left alone —
+	// moving a scope we cannot rank would be a guess.
+	return scopeVersions(info)
+		.filter(([, version]) => isBehind(target, version) === true)
+		.map(([scope]) => scope);
+}
+
+/** True when some installed scope cannot be ordered against `target` at all. */
+function hasUnorderableScope(
+	info: PluginInfo | undefined,
+	target: string,
+): boolean {
+	return scopeVersions(info).some(
+		([, version]) => isBehind(target, version) === null,
+	);
+}
+
+/** The "@marketplace" suffix of an id, or null when it has none to reason about. */
+function marketplaceSuffix(id: string): string | null {
+	const at = id.indexOf("@");
+	if (at < 0) return null;
+	const suffix = id.slice(at);
+	return suffix.length < 2 ? null : suffix;
+}
+
+/**
+ * The catalog, indexed for the questions the classifier asks of it.
+ *
+ * "Listed" is narrower than "present". `getAvailablePlugins` puts ORPHANS —
+ * installed or enabled, but published by no marketplace we read — into the same
+ * list with `isOrphaned: true`, so a plain `has(id)` is true for a plugin that
+ * nothing publishes. Treating an orphan as listed is what let an orphan plan as
+ * `current`: its `version` is filled in from its own installed version, so the
+ * compare found them equal.
+ */
+export interface CatalogIndex {
+	get(pluginId: string): PluginInfo | undefined;
+	/** In the catalog AND not an orphan: a marketplace we read publishes it. */
+	isListed(pluginId: string): boolean;
+	/** Some OTHER listed id shares this id's "@marketplace" suffix. False for ids without "@". */
+	marketplaceIsKnown(pluginId: string): boolean;
+}
+
+export function indexCatalog(
+	catalog: ReadonlyMap<string, PluginInfo> | readonly PluginInfo[],
+): CatalogIndex {
+	const byId: ReadonlyMap<string, PluginInfo> =
+		catalog instanceof Map
+			? catalog
+			: new Map((catalog as readonly PluginInfo[]).map((p) => [p.id, p]));
+
+	// Listed ids per marketplace suffix, counted once. The previous inline check
+	// scanned every catalog key for every plugin, which is quadratic in a catalog
+	// of ~300 official plugins.
+	const listedPerSuffix = new Map<string, number>();
+	for (const [id, info] of byId) {
+		if (info.isOrphaned) continue;
+		const suffix = marketplaceSuffix(id);
+		if (suffix)
+			listedPerSuffix.set(suffix, (listedPerSuffix.get(suffix) ?? 0) + 1);
+	}
+
+	const isListed = (id: string): boolean => {
+		const info = byId.get(id);
+		return !!info && !info.isOrphaned;
+	};
+
+	return {
+		get: (id) => byId.get(id),
+		isListed,
+		marketplaceIsKnown: (id) => {
+			const suffix = marketplaceSuffix(id);
+			if (!suffix) return false;
+			const others =
+				(listedPerSuffix.get(suffix) ?? 0) - (isListed(id) ? 1 : 0);
+			return others > 0;
+		},
+	};
+}
+
+/** True when a settings file enables the plugin in at least one scope. */
+function enabledAnywhere(info: PluginInfo | undefined): boolean {
+	return (
+		!!info?.userScope?.enabled ||
+		!!info?.projectScope?.enabled ||
+		!!info?.localScope?.enabled
+	);
+}
+
+/**
+ * THE plugin classifier. Pure.
+ *
+ * The rules are evaluated in order and the first match wins. Each branch below
+ * returns, so reading top to bottom is reading the precedence.
+ *
+ * @param pluginId the plugin
+ * @param pin      what it is judged against: an exact version, or "latest"
+ * @param index    the catalog — see {@link indexCatalog}
+ */
+export function classifyPlugin(
+	pluginId: string,
+	pin: string,
+	index: CatalogIndex,
+): PluginUpdateItem {
+	const info = index.get(pluginId);
+	const listed = index.isListed(pluginId);
+	const installed = highestInstalled(info);
+	// An orphan's `version` is its own installed version (or a stale local
+	// clone's), not something a marketplace we read offers — so it is not
+	// "available" from anywhere.
+	const available = listed ? (info?.version ?? null) : null;
+
+	const base = {
+		pluginId,
+		pinned: pin,
+		installed,
+		available,
+		beforeVersions: Object.fromEntries(scopeVersions(info)) as Partial<
+			Record<PluginScope, string>
+		>,
+	};
+
+	// Declared by the profile, installed nowhere, and its marketplace IS
+	// known to us but does not list it. That pin names a plugin that cannot
+	// be installed, and saying so is the whole point of this branch.
+	//
+	// Measured on the reporter's machine: mnemex's profile pinned
+	// `agentdev@magus` (retired) and `seo@magus` (moved to magus-marketing),
+	// and every run reported "3 install" while two of the three could never
+	// succeed — `claude plugin install` had nothing to fetch. Applied, failed,
+	// replanned identically, forever, with no diagnostic.
+	//
+	// "Not offered" is CATALOG MEMBERSHIP, not a missing version. Keying this
+	// on `available === null` was wrong twice over, and the second way was
+	// worse than the bug it replaced:
+	//
+	// - 278 of the 292 plugins in `claude-plugins-official` declare no
+	//   version at all — `feature-dev` among them. They are listed, they are
+	//   installable, and `available` is null for every one. Treating that as
+	//   "not offered" made a profile pin for any of them plan `unknown` and
+	//   never install. Measured on the reporting machine.
+	// - An INSTALLED plugin whose catalog version is unreadable is handled
+	//   further down against what is on disk. Hence `!installed` here.
+	//
+	// Listing answers the real question directly. The remaining trap is that a
+	// marketplace this machine has not registered yet contributes NO entries, so
+	// its plugins are also absent — but installing one is exactly what registers
+	// the marketplace. `marketplaceIsKnown` separates the two: holding other
+	// LISTED ids from that marketplace proves we genuinely read its catalog, so
+	// absence is an answer; holding none proves nothing.
+	if (!listed && !installed && index.marketplaceIsKnown(pluginId)) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "not-offered",
+			scopes: [],
+			note: "not offered by any configured marketplace",
+		};
+	}
+
+	// Not installed anywhere — the "checked but not installed" case.
+	//
+	// Nothing is installed in any scope here, so "enabled somewhere" is exactly
+	// "enabled but not installed". It is tested directly rather than through
+	// `isEnabledButNotInstalled`, which excludes orphans: an orphan that is only
+	// a settings key would otherwise read as `absent`, and the TUI renders
+	// `absent` as "the profile declares it", which an undeclared orphan does not.
+	if (!installed) {
+		const brokenEnable = enabledAnywhere(info);
+		return {
+			...base,
+			target: pin === "latest" ? available : pin,
+			action: "install",
+			reason: brokenEnable ? "enabled-not-installed" : "absent",
+			scopes: [],
+			...(brokenEnable
+				? { note: "enabled in settings, but no files on disk" }
+				: {}),
+		};
+	}
+
+	// Installed, but no marketplace we read lists it — an orphan.
+	//
+	// Planning this against its own installed version (which is what an
+	// orphan's `version` holds) found the two equal and reported `current`,
+	// while the TUI rendered the same plugin red as "deprecated". Neither is
+	// the fact. What is known is one of three things, and each gets its own
+	// text: it moved to a marketplace that does publish it; a marketplace we
+	// did read no longer lists it; or its marketplace contributed nothing we
+	// could read, so its absence proves nothing either way.
+	if (!listed) {
+		const orphan = {
+			...base,
+			target: null,
+			action: "unknown" as const,
+			scopes: [],
+		};
+		if (info?.movedTo) {
+			return {
+				...orphan,
+				reason: "moved",
+				note: `moved to ${info.movedTo}`,
+			};
+		}
+		if (index.marketplaceIsKnown(pluginId)) {
+			return {
+				...orphan,
+				reason: "not-offered",
+				note: "not offered by any configured marketplace",
+			};
+		}
+		const mp =
+			info?.marketplace || marketplaceSuffix(pluginId)?.slice(1) || pluginId;
+		return {
+			...orphan,
+			reason: "marketplace-unread",
+			note: `its marketplace ${mp} was not read, so whether it still offers this plugin is unknown`,
+		};
+	}
+
+	// An exact pin is planned against what can ACTUALLY be delivered.
+	//
+	// This is dependency management, not a package manager: there is no
+	// resolver and no version negotiation. `claude plugin install` takes no
+	// version — it fetches whatever the marketplace publishes now — so a pin
+	// naming anything else is a request nothing can satisfy.
+	//
+	// Planning toward the pin regardless is an infinite loop with a progress
+	// bar: plan 9.9.9 → 4.6.1, install, get 9.9.9 back, replan the same thing
+	// next run, and fail `--check` every time in between. Targeting the
+	// deliverable version converges, and the note carries the shortfall so it
+	// is recorded rather than hidden. `install --check` + `strictVersions`
+	// remains the place that GATES on pin drift; this command reports it.
+	//
+	// `scopesNeeding` only ever moves forward, so a scope already AHEAD of the
+	// deliverable version is left alone rather than downgraded — the same rule
+	// as the "latest" path below, because in both cases the target is what the
+	// marketplace currently publishes.
+	//
+	// The decision comes from the PER-SCOPE versions, never from `installed`.
+	// `installed` is the highest across scopes, so comparing it to the target
+	// hides the case that matters most: user scope at the target and project
+	// scope behind it reads as "current" while the project — the scope that
+	// actually loads for this repo — stays stale.
+	if (pin !== "latest") {
+		const deliverable = available ?? pin;
+		const needing = scopesNeeding(info, deliverable);
+
+		// The same "cannot tell is not current" rule as the "latest" path below.
+		// A scope that cannot be ordered against the deliverable contributes
+		// nothing to `needing`, and used to fall through to `current` here.
+		if (needing.length === 0 && hasUnorderableScope(info, deliverable)) {
+			return {
+				...base,
+				target: null,
+				action: "unknown",
+				reason: "unorderable",
+				scopes: [],
+				note:
+					available !== null
+						? `installed version cannot be compared with the published ${available}`
+						: `installed version cannot be compared with the pin ${pin}`,
+			};
+		}
+
+		const undeliverable = available !== null && available !== pin;
+		return {
+			...base,
+			target: deliverable,
+			action: needing.length === 0 ? "current" : "update",
+			reason: undeliverable
+				? "pin-undeliverable"
+				: needing.length === 0
+					? "up-to-date"
+					: "behind",
+			scopes: needing,
+			...(undeliverable
+				? {
+						note: `manifest pins ${pin}; the marketplace offers only ${available}`,
+					}
+				: {}),
+		};
+	}
+
+	// "latest" — and the catalog is the only source for what that means.
+	if (info?.updateCheckFailed) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "catalog-unverified",
+			scopes: [],
+			note:
+				info.updateCheckFailure?.detail ??
+				"catalog fetch failed — cannot tell whether a newer version exists",
+		};
+	}
+
+	// Same version, changed files. There is no version bump to detect, so a
+	// plain install is a no-op ("Plugin is already installed") and only
+	// uninstall+install refreshes the content.
+	if (info?.contentStale) {
+		return {
+			...base,
+			target: installed,
+			action: "repair",
+			reason: "content-stale",
+			scopes: scopeVersions(info).map(([scope]) => scope),
+			note: "files changed without a version bump",
+		};
+	}
+
+	// Installed and listed, with nothing to compare against. The answer is
+	// `unknown` — "current" is a claim we cannot support — and the note must not
+	// confuse this with the withdrawn case (handled above as an orphan): it is
+	// still published, still installable; we simply have no number to compare.
+	// 278 of the 292 plugins in `claude-plugins-official` are in this state, so
+	// reporting them as "not offered by any configured marketplace" told the
+	// user their installed, working, currently-published plugin had been
+	// withdrawn.
+	if (!available) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "no-published-version",
+			scopes: [],
+			note: "its marketplace publishes no version for this plugin, so there is nothing to compare",
+		};
+	}
+
+	// Again per-scope, and only ever forward.
+	const needing = scopesNeeding(info, available);
+
+	// No scope is provably behind — but that is not the same as being current.
+	// `scopesNeeding` filters on `isBehind(...) === true`, so a scope whose
+	// version cannot be ordered against the catalog contributes nothing and
+	// would fall through to `current`, which is precisely the "cannot tell
+	// rendered as nothing wrong" this whole change removes.
+	//
+	// Real and measured: 21 registry rows carry the literal string "unknown"
+	// as their version, across 8 `@claude-plugins-official` ids. Against a
+	// semver catalog they are unorderable, so they land here every run.
+	if (needing.length === 0 && hasUnorderableScope(info, available)) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "unorderable",
+			scopes: [],
+			note: `installed version cannot be compared with the published ${available}`,
+		};
+	}
+
+	return {
+		...base,
+		target: needing.length === 0 ? installed : available,
+		action: needing.length === 0 ? "current" : "update",
+		reason: needing.length === 0 ? "up-to-date" : "behind",
+		scopes: needing,
+	};
+}
+
+/**
+ * Decide what to do with every plugin the profile declares.
+ *
+ * @param pinned  closure.plugins — pluginId -> exact version | "latest"
+ * @param catalog getAvailablePlugins() output, keyed by plugin id
+ */
+export function planPluginUpdates(
+	pinned: Record<string, string>,
+	catalog: Map<string, PluginInfo>,
+): PluginUpdateItem[] {
+	const index = indexCatalog(catalog);
+	return Object.entries(pinned)
+		.map(([pluginId, pin]) => classifyPlugin(pluginId, pin, index))
+		.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+}
+
+/**
+ * The pin a TUI row is judged against.
+ *
+ * 1. The active profile's pin, when it declares the plugin — the SAME value
+ *    `magus update` plans with, which is what makes the two agree.
+ * 2. Otherwise "latest", when the plugin is installed in any scope or enabled
+ *    in one — what the TUI's own update actions have always planned with, so
+ *    the row and the action agree.
+ * 3. Otherwise null: an undeclared catalog entry the user is only browsing. It
+ *    gets no status at all. `install` means "the profile wants it", and an
+ *    undeclared plugin carries no such claim.
+ *
+ * A consequence the renderer relies on: reason `absent` can only come from
+ * rule 1, because rule 2 never assigns a pin to a row that is neither installed
+ * nor enabled.
+ */
+export function pinForRow(
+	info: PluginInfo,
+	pins: Readonly<Record<string, string>>,
+): string | null {
+	if (Object.hasOwn(pins, info.id)) return pins[info.id] ?? null;
+	if (scopeVersions(info).length > 0 || enabledAnywhere(info)) return "latest";
+	return null;
+}
+
+/**
+ * One status per row that has a pin. Rows whose {@link pinForRow} is null are
+ * absent from the map.
+ *
+ * Computed once per data/pins change, and the same map feeds every consumer —
+ * so the row, the detail panel, the header and the scope picker cannot disagree.
+ */
+export function classifyPluginRows(
+	plugins: readonly PluginInfo[],
+	pins: Readonly<Record<string, string>>,
+): Map<string, PluginUpdateItem> {
+	const index = indexCatalog(plugins);
+	const out = new Map<string, PluginUpdateItem>();
+	for (const info of plugins) {
+		const pin = pinForRow(info, pins);
+		if (pin === null) continue;
+		out.set(info.id, classifyPlugin(info.id, pin, index));
+	}
+	return out;
+}
+
+export interface PluginStateCounts {
+	install: number;
+	update: number;
+	repair: number;
+	current: number;
+	unknown: number;
+}
+
+/** Counts per action. One implementation, so a header cannot recount differently. */
+export function countPluginStates(
+	items: Iterable<PluginUpdateItem>,
+): PluginStateCounts {
+	const counts: PluginStateCounts = {
+		install: 0,
+		update: 0,
+		repair: 0,
+		current: 0,
+		unknown: 0,
+	};
+	for (const item of items) counts[item.action]++;
+	return counts;
+}
+
+/**
+ * The scope picker's one question: would advancing THIS scope be an update?
+ *
+ * Only a provable `update` that touches the scope says yes. A scope ahead of the
+ * catalog, one that cannot be ordered, and a `repair` all say no — `claude
+ * plugin install` on the same version is a no-op, so offering "update" there
+ * runs something that changes nothing.
+ */
+export function scopeIsBehind(
+	status: PluginUpdateItem | null | undefined,
+	scope: PluginScope,
+): boolean {
+	return status?.action === "update" && status.scopes.includes(scope);
+}
+
+// ── Binaries ─────────────────────────────────────────────────────────────────
+
+/**
+ * A tool's action is exactly its state from `classifyTool` — the same word the
+ * TUI's CLI Tools screen shows for the same tool.
+ */
+export type BinUpdateAction = ToolState;
+
+export interface BinUpdateItem {
+	name: string;
+	action: BinUpdateAction;
+	/** Why it is in this state. */
+	reason: ToolReason;
+	/** The exact human reason; the same string the TUI shows. */
+	note?: string;
+	/**
+	 * Set when the upgrade will take the tool over from another installer —
+	 * {@link ToolStatus.adopted}. The row must say so: it is an ordinary
+	 * `upgrade` otherwise, and the owner changing is not something to discover
+	 * afterwards.
+	 */
+	adopted?: string;
+	/** The exact pin, when the profile declares one. */
+	version?: string;
+	/** The version PATH runs, or null when absent / unreadable. */
+	installed: string | null;
+	/** The newest version its installer offers, when known. */
+	latest: string | null;
+	/** The version an install/upgrade aims at, when known. */
+	target: string | null;
+	sources: string[];
+}
+
+/**
+ * Plan binary work from probe facts, through {@link classifyTool}.
+ *
+ * This used to plan from a presence check alone: present-and-unpinned was an
+ * UPGRADE, every run, because nothing could say whether the tool was behind.
+ * `brew upgrade tmux` on a current tmux, `uv tool install --force --upgrade`
+ * on a current browser-use — each "succeeded", changed nothing, and was
+ * planned identically the next time. Now an upgrade is planned only when the
+ * installer that owns the running binary says it is behind (or its registry
+ * does), and a tool whose state cannot be established is `unknown`, which is
+ * shown and never applied.
+ *
+ * Facts are matched by name. A bin with no facts entry was never probed, and
+ * that is `unknown` too — "not checked" is not "fine".
+ */
+export function planBinUpdates(
+	bins: ResolvedBin[],
+	facts: readonly ToolFacts[],
+): BinUpdateItem[] {
+	const byName = new Map(facts.map((f) => [f.name, f]));
+	return bins.map((bin) => {
+		const f = byName.get(bin.name);
+		const status: ToolStatus = f
+			? classifyTool(bin, f)
+			: {
+					name: bin.name,
+					state: "unknown",
+					reason: "not-probed",
+					note: "not probed",
+					installed: null,
+					latest: null,
+					target: null,
+				};
+		const item: BinUpdateItem = {
+			name: bin.name,
+			action: status.state,
+			reason: status.reason,
+			installed: status.installed,
+			latest: status.latest,
+			target: status.target,
+			sources: bin.sources,
+		};
+		if (status.note) item.note = status.note;
+		if (status.adopted) item.adopted = status.adopted;
+		if (bin.version) item.version = bin.version;
+		return item;
+	});
+}
+
+/**
+ * Whether a bin item is WORK: an install or an upgrade.
+ *
+ * The one predicate `applyBins`, `planWorkItems` and `planHasWork` share. The
+ * apply loop used to skip only `current` and run everything else, so the day an
+ * `unknown` existed it would have been applied — "cannot tell" executed as an
+ * upgrade. One predicate means the three cannot disagree about that.
+ */
+export function binNeedsWork(item: BinUpdateItem): boolean {
+	return item.action === "install" || item.action === "upgrade";
+}
+
+// ── Skills ───────────────────────────────────────────────────────────────────
+
+export interface SkillUpdateItem {
+	name: string;
+	ref: ProfileSkillRef;
+	action: "install" | "refresh";
+}
+
+/**
+ * Plan skill work.
+ *
+ * A profile's skill refs carry no content hash, so "is this one behind?" is not
+ * answerable without fetching every file. Skills are small and the fetch is the
+ * same call either way, so `update` re-fetches the installed ones instead of
+ * guessing. The distinction is kept in the REPORT — a user needs to see which
+ * skills were newly added — not in the work.
+ */
+export function planSkillUpdates(
+	skills: ProfileSkillRef[],
+	installedNames: ReadonlySet<string>,
+): SkillUpdateItem[] {
+	return skills.map((ref) => ({
+		name: ref.name,
+		ref,
+		action: installedNames.has(ref.name) ? "refresh" : "install",
+	}));
+}
+
+// ── Summary ──────────────────────────────────────────────────────────────────
+
+export interface UpdatePlan {
+	profileId: string;
+	plugins: PluginUpdateItem[];
+	bins: BinUpdateItem[];
+	skills: SkillUpdateItem[];
+	/**
+	 * The full requirement behind each bin item, by name. The plan items carry
+	 * only the decision; the installer command needs `via`/`package`/`formula`,
+	 * and re-deriving those from a name would guess.
+	 */
+	binSpecs: Map<string, ResolvedBin>;
+}
+
+/**
+ * True when applying the plan would do any work at all — including work that is
+ * only ever best-effort, like re-fetching an already-installed skill.
+ *
+ * Drives the "nothing to do" early exit. NOT the `--check` gate: see
+ * {@link planIsBehind}.
+ */
+export function planHasWork(plan: UpdatePlan): boolean {
+	return (
+		plan.plugins.some((p) => p.action !== "current") ||
+		plan.bins.some(binNeedsWork) ||
+		plan.skills.length > 0
+	);
+}
+
+/**
+ * True when something is actually MISSING or KNOWN TO BE BEHIND. This is what
+ * `--check` gates on, and it is deliberately narrower than {@link planHasWork}.
+ *
+ * The distinction exists because a skill is re-run every time without that
+ * meaning anything is wrong: its manifest ref carries no content hash, so it is
+ * re-fetched rather than compared. Counting that as drift made `--check` exit 1
+ * forever for any profile that declared a single skill — a gate that can never
+ * pass tells you nothing, and would have been switched off in CI within a week.
+ *
+ * A bin `upgrade` DOES count now. It used to be excluded because an unpinned
+ * binary had no version probe and "upgrade" meant "re-run the installer"; it
+ * now means the owning installer says the tool is behind, which is drift.
+ *
+ * NEITHER an `unknown` plugin NOR an `unknown` tool counts. "We could not check
+ * this" is not evidence of drift, and most unknowns are structural and
+ * permanent rather than transient: a plugin whose marketplace publishes no
+ * version (278 of the official ones), a tool on PATH but installed by a
+ * different npm, `go` absent, a private registry. A gate that exits 1 on those
+ * can never pass, so it protects nothing and is switched off. The cost is that
+ * an item whose check merely FAILED this run — a rate-limited catalog fetch, a
+ * timed-out probe — also passes, so the exit code alone must never be read as
+ * "everything verified": the caller prints how many items went unchecked
+ * (`summarizePlan`'s `unknownPlugins`/`unknownTools`, rendered by
+ * `cli/update-view.ts`), and every unknown row carries its own reason above.
+ *
+ * Both unknowns are listed positively rather than as `!== "current"`, so a new
+ * action has to be classified here deliberately instead of defaulting into the
+ * gate.
+ */
+export function planIsBehind(plan: UpdatePlan): boolean {
+	return (
+		plan.plugins.some(
+			(p) =>
+				p.action === "install" ||
+				p.action === "update" ||
+				p.action === "repair",
+		) ||
+		plan.bins.some((b) => b.action === "install" || b.action === "upgrade") ||
+		plan.skills.some((s) => s.action === "install")
+	);
+}
+
+/** Counts for the closing summary line, in a stable order. */
+export function summarizePlan(plan: UpdatePlan): {
+	installed: number;
+	updated: number;
+	repaired: number;
+	current: number;
+	/** unknownPlugins + unknownTools. */
+	unknown: number;
+	unknownPlugins: number;
+	unknownTools: number;
+} {
+	const count = (a: PluginUpdateAction) =>
+		plan.plugins.filter((p) => p.action === a).length;
+	const bins = (a: BinUpdateAction) =>
+		plan.bins.filter((b) => b.action === a).length;
+	const unknownPlugins = count("unknown");
+	const unknownTools = bins("unknown");
+	return {
+		installed: count("install") + bins("install"),
+		updated: count("update") + bins("upgrade"),
+		repaired: count("repair"),
+		current: count("current") + bins("current"),
+		unknown: unknownPlugins + unknownTools,
+		unknownPlugins,
+		unknownTools,
+	};
+}