claudeup 4.42.0 → 5.0.0

package/src/services/update-plan.ts

@@ -0,0 +1,385 @@
+/**
+ * Pure planning for `claudeup update` — the dependency-facing update.
+ *
+ * `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 command file only
+ * does IO.
+ *
+ * The one rule worth stating out loud: a catalog fetch that FAILED 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 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 { BinCheckResult } from "./doctor-bins.js";
+import { type PluginInfo, compareVersions } from "./plugin-manager.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";
+
+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;
+	/** Scopes holding an install this action must touch. Empty for a fresh install. */
+	scopes: PluginScope[];
+	/** Human explanation, set for `unknown` and `repair`. */
+	note?: string;
+}
+
+/** Scope → installed version, for the three scopes a PluginInfo carries. */
+function scopeVersions(
+	info: PluginInfo | undefined,
+): Array<[PluginScope, string]> {
+	if (!info) return [];
+	return (
+		[
+			["user", info.userScope],
+			["project", info.projectScope],
+			["local", info.localScope],
+		] as const
+	)
+		.filter(([, status]) => !!status?.version)
+		.map(
+			([scope, status]) => [scope, status!.version!] as [PluginScope, string],
+		);
+}
+
+/** The highest version installed across scopes, or null. */
+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) >= 0 ? a : b));
+}
+
+/**
+ * Scopes that are strictly BEHIND `target`.
+ *
+ * Every scope that holds an outdated install is returned, not just "user". The
+ * prerunner learned this the expensive way: it detected drift from the current
+ * project's resolved version, then "fixed" it at user scope and reported
+ * success, leaving the project row untouched so the same drift reappeared on
+ * every 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[] {
+	return scopeVersions(info)
+		.filter(([, version]) => compareVersions(target, version) > 0)
+		.map(([scope]) => scope);
+}
+
+/**
+ * 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 items: PluginUpdateItem[] = [];
+
+	for (const [pluginId, pin] of Object.entries(pinned)) {
+		const info = catalog.get(pluginId);
+		const installed = highestInstalled(info);
+		const available = info?.version ?? null;
+
+		const base = { pluginId, pinned: pin, installed, available };
+
+		// Not installed anywhere — the "checked but not installed" case.
+		if (!installed) {
+			items.push({
+				...base,
+				target: pin === "latest" ? available : pin,
+				action: "install",
+				scopes: [],
+			});
+			continue;
+		}
+
+		// 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);
+			items.push({
+				...base,
+				target: deliverable,
+				action: needing.length === 0 ? "current" : "update",
+				scopes: needing,
+				...(available !== null && available !== pin
+					? {
+							note: `manifest pins ${pin}; the marketplace offers only ${available}`,
+						}
+					: {}),
+			});
+			continue;
+		}
+
+		// "latest" — and the catalog is the only source for what that means.
+		if (info?.updateCheckFailed) {
+			items.push({
+				...base,
+				target: null,
+				action: "unknown",
+				scopes: [],
+				note:
+					info.updateCheckFailure?.detail ??
+					"catalog fetch failed — cannot tell whether a newer version exists",
+			});
+			continue;
+		}
+
+		// 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) {
+			items.push({
+				...base,
+				target: installed,
+				action: "repair",
+				scopes: scopeVersions(info).map(([scope]) => scope),
+				note: "files changed without a version bump",
+			});
+			continue;
+		}
+
+		// Installed, but no marketplace offers it any more. "current" would be a
+		// claim we cannot support — there is nothing to compare against.
+		if (!available) {
+			items.push({
+				...base,
+				target: null,
+				action: "unknown",
+				scopes: [],
+				note: "not offered by any configured marketplace",
+			});
+			continue;
+		}
+
+		// Again per-scope, and only ever forward.
+		const needing = scopesNeeding(info, available);
+		items.push({
+			...base,
+			target: needing.length === 0 ? installed : available,
+			action: needing.length === 0 ? "current" : "update",
+			scopes: needing,
+		});
+	}
+
+	return items.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+}
+
+// ── Binaries ─────────────────────────────────────────────────────────────────
+
+export type BinUpdateAction =
+	/** Not on PATH. */
+	| "install"
+	/** Present and unpinned — re-run the installer to advance it. */
+	| "upgrade"
+	/** Present and pinned to an exact version; nothing to advance to. */
+	| "current";
+
+export interface BinUpdateItem {
+	name: string;
+	action: BinUpdateAction;
+	/** The exact pin, when the profile declares one. */
+	version?: string;
+	sources: string[];
+}
+
+/**
+ * Plan binary work from a presence check.
+ *
+ * There is no version probe for an arbitrary binary — `checkBinaries` answers
+ * present/absent only — so a PINNED bin that is present is left alone rather
+ * than reinstalled on a guess. An unpinned one is re-run through its installer,
+ * which is what "update" means for a dependency with no declared version.
+ */
+export function planBinUpdates(
+	bins: ResolvedBin[],
+	checks: BinCheckResult[],
+): BinUpdateItem[] {
+	const present = new Map(checks.map((c) => [c.name, c.present]));
+	return bins.map((bin) => {
+		const item: BinUpdateItem = {
+			name: bin.name,
+			sources: bin.sources,
+			action: !present.get(bin.name)
+				? "install"
+				: bin.version
+					? "current"
+					: "upgrade",
+		};
+		if (bin.version) item.version = bin.version;
+		return item;
+	});
+}
+
+// ── 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((b) => b.action !== "current") ||
+		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 two kinds of item are re-run every time
+ * without that meaning anything is wrong:
+ * - a skill, whose manifest ref carries no content hash, so it is re-fetched
+ *   rather than compared;
+ * - an unpinned binary, for which there is no version probe at all, only
+ *   present/absent.
+ *
+ * Counting those 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.
+ *
+ * `unknown` DOES count: an unverifiable plugin is exactly what a gate must not
+ * wave through.
+ */
+export function planIsBehind(plan: UpdatePlan): boolean {
+	return (
+		plan.plugins.some((p) => p.action !== "current") ||
+		plan.bins.some((b) => b.action === "install") ||
+		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;
+	unknown: number;
+} {
+	const count = (a: PluginUpdateAction) =>
+		plan.plugins.filter((p) => p.action === a).length;
+	return {
+		installed:
+			count("install") + plan.bins.filter((b) => b.action === "install").length,
+		updated:
+			count("update") + plan.bins.filter((b) => b.action === "upgrade").length,
+		repaired: count("repair"),
+		current:
+			count("current") + plan.bins.filter((b) => b.action === "current").length,
+		unknown: count("unknown"),
+	};
+}

package/src/ui/App.tsx

@@ -259,7 +259,7 @@ function UpdateBanner({ result }: { result: VersionCheckResult }) {
 				v{result.currentVersion} → v{result.latestVersion}
 			</text>
 			<text fg={theme.colors.muted}> Run: </text>
-			<text fg={theme.colors.info}>claudeup update</text>
+			<text fg={theme.colors.info}>claudeup upgrade</text>
 		</box>
 	);
 }