magus-cli 0.0.0-placeholder → 7.0.0

package/src/cli/update.ts

@@ -0,0 +1,613 @@
+/**
+ * `magus update [profile] [--check] [--yes]`
+ *
+ * Dependency management, not package management: no resolver, no lockfile, no
+ * version negotiation. `magus install` puts the profile's declared set on
+ * this machine; `magus update` keeps it current — anything the profile
+ * declares but the machine lacks is installed, and anything behind the version
+ * its marketplace publishes is advanced to it.
+ *
+ * Scope is the ACTIVE profile, not the union of every profile: "update my
+ * dependencies" means the set actually in use. Pass a name to update another.
+ *
+ * Self-update moved to `magus upgrade`.
+ *
+ * ## Why this file drives a live region
+ *
+ * Most of an update's wall clock is spent inside four calls that print nothing:
+ * a git fetch per marketplace, a catalog read, a serial PATH probe per binary,
+ * then an install per plugin. The command used to print its first line after
+ * all of the first three had finished, and one line per plugin only once that
+ * plugin was already installed. On a slow network that is thirty seconds of a
+ * dead terminal, which reads as a hang, not as work.
+ *
+ * So every phase reports while it runs. `cli/live.ts` owns the mechanism. A
+ * line printed while a region is painting must go through the region, or it
+ * lands inside the animated block and the next repaint's cursor-up arithmetic
+ * erases it along with part of the frame. Prefer `live.note` here for anything
+ * this file emits deliberately — but the region also CAPTURES `console` while
+ * it paints, so a write from deeper in the call graph is routed rather than
+ * corrupting the display. That capture is not belt-and-braces: it is the only
+ * thing that covers `getAvailablePlugins`, which reaches a stale-marketplace
+ * advisory two layers down and used to erase itself mid-frame.
+ *
+ * `cli/update-view.ts` owns every string. Nothing in this file formats.
+ */
+
+import { selectProfileId } from "../services/active-closure.js";
+import { isClaudeAvailable } from "../services/claude-cli.js";
+import { clearContentDriftCache } from "../services/content-drift.js";
+import { validateManifest } from "../services/manifest.js";
+import {
+	refreshRegisteredMarketplaces,
+	reportRegisteredMarketplaces,
+} from "../services/marketplace-refresh.js";
+import { registerClosureMarketplaces } from "../services/marketplace-sync.js";
+import {
+	type PluginInfo,
+	clearMarketplaceCache,
+	getAvailablePlugins,
+} from "../services/plugin-manager.js";
+import { resolveProfile } from "../services/resolver.js";
+import { getInstalledSkillNames } from "../services/skills-manager.js";
+import { activeProfile } from "../services/symlink-manager.js";
+import { REAL_TOOL_PROBE_IO, probeTools } from "../services/tool-probe.js";
+// The apply half lives in services/ so the TUI runs the SAME code — see the
+// header of update-engine.ts for what drifted while it did not.
+import {
+	type ApplyReporter,
+	applyPlan,
+	planWorkItems,
+} from "../services/update-engine.js";
+import {
+	type UpdatePlan,
+	planBinUpdates,
+	planHasWork,
+	planIsBehind,
+	planPluginUpdates,
+	planSkillUpdates,
+	summarizePlan,
+} from "../services/update-plan.js";
+import { brand } from "../ui/theme.js";
+import { bold, dim, fg, width } from "./ansi.js";
+import { ensureManifest } from "./bootstrap.js";
+import { LiveRegion, withPaused } from "./live.js";
+import {
+	type ApplyState,
+	type Step,
+	applyFrame,
+	applyRow,
+	fail as failLine,
+	header,
+	info,
+	note as noteLine,
+	nothingToApplyNotice,
+	ok as okLine,
+	planReport,
+	stepFrame,
+	stepRecord,
+	summaryLine,
+	uncheckedGateNotice,
+	unknownPluginsNotice,
+	unknownToolsNotice,
+	warn as warnLine,
+} from "./update-view.js";
+
+interface UpdateFlags {
+	/** Report drift and exit 1 if anything is behind. The CI gate. */
+	check: boolean;
+	/** Show the plan and stop. Always exits 0 — it is a preview, not a gate. */
+	dryRun: boolean;
+	profile?: string;
+}
+
+/**
+ * `--yes` / `-y` are gone, and are silently ignored rather than rejected.
+ *
+ * They existed to skip a confirmation that no longer exists: `update` applies
+ * its plan. Both start with `-`, so an old script or a habit still runs and
+ * still does the right thing; there is no flag kept alive to mean nothing.
+ */
+export function parseArgs(args: string[]): UpdateFlags {
+	return {
+		check: args.includes("--check"),
+		dryRun: args.includes("--dry-run"),
+		profile: args.find((a) => !a.startsWith("-")),
+	};
+}
+
+// -- phase runner ------------------------------------------------------------
+
+/**
+ * Run one checklist step, keeping its row and the animation truthful.
+ *
+ * `work` gets a `say` callback so a long step can narrate what it is currently
+ * blocked on — the marketplace step names the clone it is pulling, the binary
+ * step names the binary it is probing. That detail is the difference between
+ * "something is happening" and "the network call to THIS marketplace is slow".
+ *
+ * A step that throws is marked `fail` and RE-THROWN. Marking it matters: the
+ * record printed on the way out then names the step that died, instead of a
+ * stack trace landing under a checklist whose last row is still spinning.
+ */
+function makeStepRunner(live: LiveRegion, all: Step[]) {
+	return async function runStep<T>(
+		step: Step,
+		work: (say: (detail: string) => void) => Promise<T>,
+	): Promise<T> {
+		step.state = "running";
+		step.startedAt = Date.now();
+		step.detail = step.detail || "…";
+		live.refresh();
+		const say = (detail: string) => {
+			step.detail = detail;
+			live.refresh();
+		};
+		try {
+			return await work(say);
+		} catch (error) {
+			step.state = "fail";
+			step.detail = error instanceof Error ? error.message : String(error);
+			step.endedAt = Date.now();
+			step.progress = undefined;
+			// Collapse to the record on the way out. Without this the exception
+			// surfaces under a checklist frozen mid-spin, with the cursor still
+			// hidden — the process-exit hook restores the cursor but cannot know
+			// what the last frame should have said.
+			live.stop(stepRecord(all, Date.now()));
+			throw error;
+		} finally {
+			step.endedAt = Date.now();
+			step.progress = undefined;
+			if (step.state === "running") step.state = "done";
+			live.refresh();
+		}
+	};
+}
+
+// -- entry point -------------------------------------------------------------
+
+export async function runUpdateCommand(
+	args: string[],
+	projectPath: string = process.cwd(),
+): Promise<number> {
+	const flags = parseArgs(args);
+	const startedAt = Date.now();
+
+	// The ONE prompt that survives, and only in a repo that has no manifest yet.
+	// Writing `.claude/profiles.json` is not part of updating: it authors the
+	// file a team commits and shares, possibly derived from this machine's
+	// personal user-scope plugin set. That is worth a human, once per repo,
+	// forever. Everything after it applies without asking.
+	const manifest = await ensureManifest(projectPath, {
+		check: flags.check || flags.dryRun,
+	});
+	if (!manifest) return 1;
+
+	const errors = validateManifest(manifest);
+	if (errors.length > 0) {
+		console.error(failLine("Invalid .claude/profiles.json:"));
+		for (const e of errors) console.error(noteLine(`${e.path}: ${e.message}`));
+		return 1;
+	}
+
+	const profileIds = Object.keys(manifest.profiles);
+	if (flags.profile && !manifest.profiles[flags.profile]) {
+		console.error(
+			failLine(
+				`Profile "${flags.profile}" not found. Available: ${profileIds.join(", ")}`,
+			),
+		);
+		return 1;
+	}
+
+	// Active profile, not the union — "update my dependencies" means the set in
+	// use. A single-profile manifest needs no activation to be unambiguous.
+	// Chosen through the same function the TUI uses, so both judge a plugin
+	// against the same pin.
+	const targetId = selectProfileId(
+		profileIds,
+		flags.profile,
+		await activeProfile(projectPath),
+	);
+	if (!targetId) {
+		console.error(
+			failLine(
+				`No active profile. Pass one: magus update <${profileIds.join("|")}>`,
+			),
+		);
+		return 1;
+	}
+
+	for (const line of header(targetId)) console.log(line);
+
+	// ---- resolve phase, under one animated checklist -------------------------
+
+	const steps: Record<
+		"profile" | "marketplaces" | "catalog" | "binaries" | "skills",
+		Step
+	> = {
+		profile: { label: "profile", state: "pending", detail: "" },
+		marketplaces: { label: "marketplaces", state: "pending", detail: "" },
+		catalog: { label: "catalog", state: "pending", detail: "" },
+		binaries: { label: "binaries", state: "pending", detail: "" },
+		skills: { label: "skills", state: "pending", detail: "" },
+	};
+	const stepList = Object.values(steps);
+
+	const live = new LiveRegion();
+	live.start((tick) => stepFrame(stepList, tick, Date.now()));
+	const runStep = makeStepRunner(live, stepList);
+
+	/** Notices worth keeping, flushed after the checklist collapses. */
+	const notices: string[] = [];
+
+	const closure = await runStep(steps.profile, async (say) => {
+		say(`resolving "${targetId}"`);
+		const resolved = await resolveProfile(manifest, targetId);
+		steps.profile.detail = [
+			`${Object.keys(resolved.plugins).length} plugins`,
+			`${resolved.bins.length} tools`,
+			`${resolved.skills.length} skills`,
+		].join(" · ");
+		return resolved;
+	});
+
+	// "latest" is only as fresh as the catalog. Fast-forward the marketplace
+	// clones first, then drop every cached answer derived from the old HEAD —
+	// skipping this is how a clone sits days behind while every plugin reads as
+	// up to date.
+	// ...but NOT under --dry-run or --check. Both promise to write nothing, and
+	// `git pull --ff-only` on a clone under ~/.claude/plugins/marketplaces/ is a
+	// write — it advances the user's marketplace to a new commit. The help text
+	// said "Writes nothing, exits 0" while the run printed "1 refreshed" in its
+	// own output, which is where this was caught. A read-only run plans against
+	// the clone as it stands; the notice below says so, so an unrefreshed
+	// catalog is never mistaken for a current one.
+	const refresh = await runStep(steps.marketplaces, async (say) => {
+		if (flags.dryRun || flags.check) {
+			say("read-only — selecting, not pulling");
+			// Report-only, NOT a skip: the autoUpdate-disabled verdict is a pure
+			// read and is the one diagnostic a read-only run must not lose.
+			const report = await reportRegisteredMarketplaces();
+			steps.marketplaces.detail = `not refreshed (read-only) · ${report.skipped.length} eligible`;
+			return report;
+		}
+		let settled = 0;
+		return refreshRegisteredMarketplaces([], {
+			onStart: (names) => {
+				// Only now is there a denominator; until `onStart` fires the step
+				// shows a sweep rather than a meter that would have to guess one.
+				steps.marketplaces.progress = { done: 0, total: names.length };
+				say(
+					names.length === 0 ? "none eligible" : `pulling ${names.join(", ")}`,
+				);
+			},
+			onSettled: (name, status) => {
+				settled++;
+				if (steps.marketplaces.progress)
+					steps.marketplaces.progress.done = settled;
+				say(`${name} ${status}`);
+			},
+		});
+	});
+	steps.marketplaces.detail = [
+		`${refresh.refreshed.length} refreshed`,
+		refresh.autoUpdateDisabled.length > 0
+			? `${refresh.autoUpdateDisabled.length} auto-update off`
+			: "",
+		refresh.failed.length > 0 ? `${refresh.failed.length} failed` : "",
+		refresh.skipped.length > 0 ? `${refresh.skipped.length} skipped` : "",
+	]
+		.filter(Boolean)
+		.join(" · ");
+	if (refresh.failed.length > 0) steps.marketplaces.state = "fail";
+	else if (refresh.autoUpdateDisabled.length > 0)
+		steps.marketplaces.state = "warn";
+
+	for (const name of refresh.autoUpdateDisabled) {
+		notices.push(
+			warnLine(
+				`${bold(name)}: auto-update disabled — its catalog will not refresh, so updates stay hidden.`,
+			),
+		);
+		notices.push(
+			noteLine(
+				`claude plugin marketplace update ${name}  # to refresh it once`,
+			),
+		);
+	}
+	for (const name of refresh.failed) {
+		notices.push(
+			failLine(
+				`${bold(name)}: refresh failed — clone left intact but stale, so its versions may be behind.`,
+			),
+		);
+	}
+
+	clearMarketplaceCache();
+	clearContentDriftCache();
+
+	const catalog = await runStep(steps.catalog, async (say) => {
+		say("reading installed and available plugins");
+		const map = new Map<string, PluginInfo>(
+			(await getAvailablePlugins(projectPath)).map((p) => [p.id, p]),
+		);
+		steps.catalog.detail = `${map.size} plugins known`;
+		return map;
+	});
+
+	// The tool probe: installed version, owner, and the owning installer's own
+	// "behind?" answer — the same probe the TUI's CLI Tools screen uses. It used
+	// to be a presence check, which is why every present unpinned tool planned
+	// as an upgrade on every run.
+	const toolFacts = await runStep(steps.binaries, async (say) => {
+		if (closure.bins.length === 0) {
+			steps.binaries.detail = "none declared";
+			return [];
+		}
+		steps.binaries.progress = { done: 0, total: closure.bins.length };
+		const facts = await probeTools(closure.bins, REAL_TOOL_PROBE_IO, {
+			// `settled`, not `index`: results arrive in completion order, and a
+			// meter driven by index would jump backwards.
+			onResult: (f, { settled, total }) => {
+				steps.binaries.progress = { done: settled, total };
+				say(f.name);
+			},
+		});
+		const items = planBinUpdates(closure.bins, facts);
+		const n = (a: string) => items.filter((i) => i.action === a).length;
+		const behind = n("upgrade");
+		const unknown = n("unknown");
+		const missing = n("install");
+		steps.binaries.detail = [
+			`${items.length} checked`,
+			behind > 0 ? `${behind} behind` : "",
+			unknown > 0 ? `${unknown} unknown` : "",
+			missing > 0 ? `${missing} missing` : "",
+		]
+			.filter(Boolean)
+			.join(" · ");
+		if (missing + unknown > 0) steps.binaries.state = "warn";
+		return facts;
+	});
+
+	const installedSkills = await runStep(steps.skills, async (say) => {
+		say("reading .claude/skills");
+		const names = await getInstalledSkillNames("project", projectPath);
+		steps.skills.detail =
+			closure.skills.length === 0
+				? "none declared"
+				: `${names.size} installed of ${closure.skills.length} declared`;
+		return names;
+	});
+
+	// Collapse the animation into its permanent record, then flush the notices
+	// underneath it — a warning printed mid-checklist would have scrolled past.
+	live.stop(stepRecord(stepList, Date.now()));
+	for (const line of notices) console.log(line);
+
+	// ---- plan ----------------------------------------------------------------
+
+	const plan: UpdatePlan = {
+		profileId: targetId,
+		plugins: planPluginUpdates(closure.plugins, catalog),
+		bins: planBinUpdates(closure.bins, toolFacts),
+		skills: planSkillUpdates(closure.skills, installedSkills),
+		binSpecs: new Map(closure.bins.map((b) => [b.name, b])),
+	};
+
+	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);
+	if (counts.unknownPlugins > 0 || counts.unknownTools > 0) console.log("");
+	if (counts.unknownPlugins > 0) {
+		console.log(unknownPluginsNotice(counts.unknownPlugins));
+	}
+	if (counts.unknownTools > 0) console.log(toolUnknownLine());
+
+	// `--check` gates on planIsBehind, not planHasWork. An already-installed
+	// skill is re-fetched on every apply because its manifest ref carries no
+	// content hash, which is no evidence that anything is out of date — counting
+	// it made the gate exit 1 forever for any profile declaring a single skill.
+	//
+	// 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.
+	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."));
+			return 0;
+		}
+		console.error(
+			failLine(`Updates available. Run ${bold("magus update")} to apply.`),
+		);
+		return 1;
+	}
+
+	// Exactly the items the engine will touch. Derived by the engine from the
+	// same predicates its loops use, so the meter's denominator cannot drift
+	// from the work — a bar stuck short of full reads as a hang.
+	const workItems = planWorkItems(plan);
+
+	if (!planHasWork(plan) || workItems.length === 0) {
+		for (const line of summaryLine(
+			0,
+			counts.current,
+			counts.unknown,
+			0,
+			Date.now() - startedAt,
+		))
+			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."));
+		return 0;
+	}
+
+	// `--dry-run` stops here: the plan is printed above, nothing is written, and
+	// it exits 0. That is the difference from `--check`, which is a CI gate and
+	// exits 1 precisely when there IS something to do.
+	if (flags.dryRun) {
+		console.log("");
+		console.log(
+			info(
+				`Dry run — ${workItems.length} item(s) would be applied. Nothing written.`,
+			),
+		);
+		return 0;
+	}
+
+	// No confirmation. `update` moves the machine toward what the profile
+	// declares and can only go FORWARD: `claude plugin install` takes no version
+	// and installs the newest published one, so there is no downgrade and no
+	// delete for a prompt to protect against. The plan is printed above, so the
+	// run is still legible after the fact — and `--dry-run` shows it beforehand.
+	//
+	// Note this also runs a profile's CLI-tool installers unattended (`brew
+	// upgrade`, `bun install -g`). That is the deliberate cost of the choice.
+
+	if (!(await isClaudeAvailable())) {
+		console.error(
+			failLine(
+				"claude CLI not found on PATH — cannot install or update plugins.",
+			),
+		);
+		return 1;
+	}
+
+	// Register any marketplace the profile names but this machine does not know.
+	// Without this an install fails with "not found in marketplace" for anything
+	// outside magus's built-in list, which is every private or third-party one.
+	await registerClosureMarketplaces(closure.marketplaces);
+
+	// ---- apply phase, under an animated meter --------------------------------
+
+	const nameWidth = Math.max(12, ...workItems.map((n) => width(n)));
+
+	const state: ApplyState = {
+		done: 0,
+		total: workItems.length,
+		current: "starting",
+		startedAt: Date.now(),
+	};
+
+	const applyLive = new LiveRegion();
+	/** The last detail each item finished with — the reason, for an unchanged one. */
+	const finishedDetail = new Map<string, string>();
+	const reporter: ApplyReporter = {
+		begin: (name) => {
+			state.current = name;
+			applyLive.refresh();
+		},
+		finish: (succeeded, name, detail, ms) => {
+			state.done++;
+			finishedDetail.set(name, detail);
+			applyLive.note(
+				applyRow(
+					succeeded,
+					name,
+					nameWidth,
+					!succeeded
+						? fg(brand.danger, detail)
+						: detail.startsWith("no change — ")
+							? fg(brand.warning, detail)
+							: dim(detail),
+					ms,
+				),
+			);
+		},
+		detach: (work) => withPaused(applyLive, work),
+	};
+
+	console.log("");
+	applyLive.start((tick) => applyFrame(state, tick, Date.now()));
+
+	const outcome = await applyPlan(plan, projectPath, { report: reporter });
+
+	applyLive.stop();
+
+	const { failed } = outcome;
+
+	for (const line of summaryLine(
+		outcome.changed,
+		counts.current,
+		counts.unknown,
+		failed.length,
+		Date.now() - startedAt,
+		outcome.unchanged.length,
+	))
+		console.log(line);
+
+	// Exited 0, read back unmoved. Reported, never fatal — the same precedent
+	// as the pin mismatches below: this is a standing property of the machine
+	// (a stale tap, a shadowing PATH entry), not something this run did wrong,
+	// and it will be replanned. What it must never be is counted as "changed".
+	if (outcome.unchanged.length > 0) {
+		console.log(
+			warnLine(
+				`${bold(String(outcome.unchanged.length))} item(s) ran but did not change:`,
+			),
+		);
+		for (const name of outcome.unchanged) {
+			const detail = (finishedDetail.get(name) ?? "").replace(
+				/^no change — /,
+				"",
+			);
+			console.log(noteLine(`${name}: ${detail}`));
+		}
+	}
+
+	// An exact pin the installer could not deliver. Reported, never fatal: only
+	// the newest published version is installable, so this is a standing property
+	// of the manifest rather than something this run did wrong, and failing here
+	// would make `magus update` exit 1 forever for any profile with a pin.
+	// `install --check` with `strictVersions` is where pin drift is GATED.
+	if (outcome.plugins.mismatches.length > 0) {
+		console.log(
+			warnLine(
+				`${bold(String(outcome.plugins.mismatches.length))} pinned version(s) are not what is installed. Only the newest published version can be installed:`,
+			),
+		);
+		for (const m of outcome.plugins.mismatches) {
+			console.log(
+				noteLine(
+					`${m.pluginId} (${m.scope}): manifest pins ${m.pinned}, installed ${m.actual ?? "unknown"}`,
+				),
+			);
+		}
+		console.log(
+			noteLine(
+				"Recorded what is actually installed. Update the pin to match, or leave it as a record of intent.",
+			),
+		);
+	}
+
+	if (failed.length > 0) {
+		console.error(failLine(`Failed: ${failed.join(", ")}`));
+		return 1;
+	}
+	return 0;
+}