magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/update-engine.ts

@@ -0,0 +1,691 @@
+/**
+ * update-engine.ts — applying an update plan. The ONLY implementation.
+ *
+ * This used to live inside `cli/update.ts`, which meant the TUI could not reach
+ * it and grew its own loop in `PluginsScreen.handleUpdateAll`. The two drifted
+ * exactly where you would expect:
+ *
+ *  - the CLI advanced **every scope** holding an outdated install; the TUI
+ *    updated one, derived from whichever scope tab was open, so drift in the
+ *    others survived and reappeared on the next run;
+ *  - the CLI recorded the version it **read back** after installing; the TUI
+ *    recorded the version it had *expected*, which is the bug the CLI's own
+ *    comments describe at length — `claude plugin install` takes no version
+ *    argument, so writing the intended value made `install --check` compare a
+ *    pin against a copy of itself and report clean forever;
+ *  - only the CLI reported pins the installer could not honour.
+ *
+ * None of that was a decision. It was two copies of one idea, edited apart.
+ *
+ * So the engine lives here, in `services/`, and both front ends drive it.
+ * `cli/` and `ui/` are sibling presentation layers: they own how progress looks
+ * and nothing else. Everything IO-shaped is injected — `PluginApplyDeps` for
+ * the five Claude Code calls, `ApplyReporter` for progress, `runCommand` for
+ * installers — so the same code drives an animated terminal meter, a TUI modal,
+ * and a test that wants silence.
+ *
+ * NOTHING HERE PRINTS. A `console.log` in this file is a layering violation:
+ * the CLI paints an animated region that a stray write corrupts, and the TUI
+ * has no stdout to write to at all.
+ */
+
+import path from "node:path";
+import type {
+	ProfileSkillRef,
+	ResolvedBin,
+	SkillInfo,
+} from "../types/index.js";
+import type { Command } from "../utils/command-utils.js";
+import { formatCommand } from "../utils/command-utils.js";
+import { runCommand } from "../utils/run.js";
+import type { PluginScope } from "./claude-cli.js";
+import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
+import {
+	readInstalledVersionForScope,
+	saveInstalledPluginVersionForScope,
+} from "./plugin-manager.js";
+import { installSkill } from "./skills-manager.js";
+import {
+	type ToolFacts,
+	compareToolVersions,
+	probeTool,
+} from "./tool-probe.js";
+import { binCommandForState } from "./toolchain.js";
+import {
+	type BinUpdateItem,
+	type PluginUpdateItem,
+	type UpdatePlan,
+	binNeedsWork,
+} from "./update-plan.js";
+
+// -- results -----------------------------------------------------------------
+
+export interface ApplyResult {
+	/** Items that CHANGED — the installer exited 0 and read-back shows movement. */
+	ok: number;
+	failed: string[];
+	/**
+	 * Items whose installer exited 0 but whose read-back shows nothing moved.
+	 *
+	 * Not a failure, and not a change. A stale tap, a PATH that still resolves
+	 * an older copy, a marketplace clone behind its catalog — each "succeeds",
+	 * lands on the same version, and is planned identically next run. Counting
+	 * those as changed is how "3 changed" was printed on every run forever.
+	 */
+	unchanged: string[];
+}
+
+/** An exact pin the installer could not deliver, discovered by reading back. */
+export interface PinMismatch {
+	pluginId: string;
+	pinned: string;
+	actual: string | null;
+	scope: PluginScope;
+}
+
+export interface PluginApplyResult extends ApplyResult {
+	mismatches: PinMismatch[];
+}
+
+/** Everything one full apply produced, for whichever front end is reporting. */
+export interface UpdateOutcome {
+	plugins: PluginApplyResult;
+	bins: ApplyResult;
+	skills: ApplyResult;
+	/** Items that changed, across all three. */
+	changed: number;
+	/** Names whose installer exited 0 but read-back shows no movement. */
+	unchanged: string[];
+	/** Names that failed, across all three. */
+	failed: string[];
+}
+
+// -- injected edges ----------------------------------------------------------
+
+/**
+ * How the apply loop reports itself.
+ *
+ * Injected rather than hard-coded, because the loop is the same work whether it
+ * is driving an animated meter, a TUI modal, or a test that wants silence.
+ */
+export interface ApplyReporter {
+	/** An item is starting. Called before any of its work. */
+	begin(name: string): void;
+	/** An item finished. `detail` is already formatted for display. */
+	finish(ok: boolean, name: string, detail: string, ms: number): void;
+	/**
+	 * Run `work` with the terminal released.
+	 *
+	 * A binary upgrade spawns `brew`/`uv` with inherited stdio: it writes and
+	 * moves the cursor itself, so any animated block must be erased first or the
+	 * two interleave into garbage. A TUI implementation suspends its renderer;
+	 * a silent one just awaits.
+	 */
+	detach<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/** Reports nothing. The right default for a caller that renders its own state. */
+export const SILENT_REPORTER: ApplyReporter = {
+	begin: () => {},
+	finish: () => {},
+	detach: (work) => work(),
+};
+
+/**
+ * The four side-effecting calls the plugin apply path makes, injectable so the
+ * path itself can be tested.
+ *
+ * This exists because the apply half shipped with no coverage while the pure
+ * planner had forty tests — and every real defect found in review lived here,
+ * not there.
+ */
+export interface PluginApplyDeps {
+	/**
+	 * A plugin NOT installed at this scope yet.
+	 *
+	 * Separate from {@link PluginApplyDeps.update} because the two are separate
+	 * Claude Code commands that each no-op in the other's case — see the note on
+	 * `updatePlugin` in claude-cli.ts.
+	 */
+	install: (pluginId: string, scope: PluginScope) => Promise<void>;
+	update: (pluginId: string, scope: PluginScope) => Promise<void>;
+	repair: (
+		pluginId: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<void>;
+	readInstalled: (
+		pluginId: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<string | null>;
+	saveInstalled: (
+		pluginId: string,
+		version: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<void>;
+}
+
+export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
+	install: installPlugin,
+	update: updatePlugin,
+	repair: repairPlugin,
+	readInstalled: readInstalledVersionForScope,
+	saveInstalled: saveInstalledPluginVersionForScope,
+};
+
+// -- selection ---------------------------------------------------------------
+
+/**
+ * Scopes the apply loop would touch for `item`. Empty means it is skipped.
+ *
+ * A plugin the profile declares but nothing has installed goes in at PROJECT
+ * scope, matching `install`: a profile is a property of one repo, so its
+ * plugins must not be enabled machine-wide.
+ *
+ * Every scope holding an outdated install is returned, not just one. Fixing a
+ * single hardcoded scope does not converge: it reports success while the
+ * project row stays untouched, so the same drift reappears on the next run.
+ */
+function scopesToApply(item: PluginUpdateItem): PluginScope[] {
+	if (item.action === "current" || item.action === "unknown") return [];
+	return item.action === "install" ? ["project"] : item.scopes;
+}
+
+/**
+ * Whether the apply loop will do anything for `item`.
+ *
+ * Exported for ONE reason: a progress meter's denominator must be the same
+ * predicate the loop applies. Re-deriving it at the call site is how the two
+ * drift, and a bar that stops short of full at the end of a successful run
+ * looks exactly like a hang.
+ */
+export function pluginNeedsWork(item: PluginUpdateItem): boolean {
+	return scopesToApply(item).length > 0;
+}
+
+// -- plugins -----------------------------------------------------------------
+
+/**
+ * Advance a plugin at `scope`, choosing the command by whether THIS project
+ * actually holds an install row there.
+ *
+ * The check is not defensive tidiness — without it `update` mutates a project
+ * nobody named. `claude plugin update --scope project` resolves the project
+ * from the CLI's working directory, and when that directory has no row for the
+ * plugin it falls back to some OTHER project's row and updates that one.
+ * Measured on Claude Code 2.1.252, run from a directory with no madbench row:
+ *
+ *     $ claude plugin update madbench@magus --scope project
+ *     ✔ Plugin "madbench" updated from 0.2.4 to 0.3.0 for scope project
+ *       (/Users/jack/mag/tmux-mcp). Restart to apply changes.
+ *
+ * `/Users/jack/mag/tmux-mcp` was not the working directory and had nothing to
+ * do with the request. `plugin install` has no such fallback — it keys on the
+ * working directory — so the absent case must go there instead.
+ *
+ * This is live for git worktrees in particular: magus resolves a worktree's
+ * installed version by inheriting the parent repo's rows, so a worktree can
+ * report "0.2.4 installed, 0.3.0 available" while owning no row of its own.
+ * That is exactly the shape that used to reach `update`.
+ *
+ * `readInstalled` matches the project path EXACTLY (no worktree inheritance),
+ * which is what makes it the right question to ask here.
+ */
+async function advanceInScope(
+	deps: PluginApplyDeps,
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+): Promise<void> {
+	const here = await deps.readInstalled(pluginId, scope, projectPath);
+	if (here) await deps.update(pluginId, scope);
+	else await deps.install(pluginId, scope);
+}
+
+/**
+ * Why nothing moved for `item`, judged by READ-BACK; null when something did.
+ *
+ * No installer output is parsed — "already at the latest version" is
+ * locale- and version-fragile. The registry row the apply loop already reads
+ * back is compared with the before-version the plan carries:
+ *  - update: every touched scope reads back exactly what it held before;
+ *  - install: no touched scope reads back any version at all;
+ *  - repair: never — same version is its definition; the files moved.
+ */
+function pluginNoMove(
+	item: PluginUpdateItem,
+	landed: ReadonlyArray<[PluginScope, string | null]>,
+): string | null {
+	if (landed.length === 0) return null;
+	if (item.action === "update") {
+		const same = landed.every(
+			([scope, actual]) => (actual ?? undefined) === item.beforeVersions[scope],
+		);
+		if (!same) return null;
+		const v = landed.find(([, a]) => a)?.[1];
+		return v
+			? `the installer exited 0 but ${item.pluginId} is still ${v}`
+			: `the installer exited 0 but no version of ${item.pluginId} was recorded`;
+	}
+	if (item.action === "install") {
+		return landed.every(([, actual]) => actual === null)
+			? `the installer exited 0 but no version of ${item.pluginId} was recorded`
+			: null;
+	}
+	return null;
+}
+
+export async function applyPlugins(
+	items: PluginUpdateItem[],
+	projectPath: string,
+	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
+	report: ApplyReporter = SILENT_REPORTER,
+): Promise<PluginApplyResult> {
+	const result: PluginApplyResult = {
+		ok: 0,
+		failed: [],
+		unchanged: [],
+		mismatches: [],
+	};
+
+	for (const item of items) {
+		const scopes = scopesToApply(item);
+		if (scopes.length === 0) continue;
+
+		report.begin(item.pluginId);
+		const startedAt = Date.now();
+		const landed: Array<[PluginScope, string | null]> = [];
+
+		try {
+			for (const scope of scopes) {
+				// Three actions, three DIFFERENT Claude Code commands. Each is a
+				// silent no-op in the other two cases:
+				//   repair  — same version, changed files: only uninstall+install
+				//             re-copies; `update` sees no version bump to act on.
+				//   install — absent at this scope: `update` answers "already at the
+				//             latest version" and installs nothing.
+				//   update  — installed but behind: `install` answers "already
+				//             installed", ignores the version, and exits 0.
+				// Folding install and update together is the bug that made every
+				// magus update path do nothing while reporting success.
+				if (item.action === "repair") {
+					await deps.repair(item.pluginId, scope, projectPath);
+				} else if (item.action === "install") {
+					await deps.install(item.pluginId, scope);
+				} else {
+					await advanceInScope(deps, item.pluginId, scope, projectPath);
+				}
+
+				// Record what LANDED, not what we asked for.
+				//
+				// `claude plugin install` accepts no version, so an exact pin is a
+				// request the installer cannot honour — it fetches whatever the
+				// marketplace publishes now. Writing `item.target` here recorded the
+				// pin as satisfied whatever actually installed, and `install --check`
+				// reads that same field to decide whether the machine has drifted.
+				// The gate would have compared the pin against a copy of itself and
+				// reported clean forever.
+				const actual = await deps.readInstalled(
+					item.pluginId,
+					scope,
+					projectPath,
+				);
+				landed.push([scope, actual]);
+				if (actual) {
+					await deps.saveInstalled(item.pluginId, actual, scope, projectPath);
+				}
+				if (item.pinned !== "latest" && actual !== item.pinned) {
+					result.mismatches.push({
+						pluginId: item.pluginId,
+						pinned: item.pinned,
+						actual,
+						scope,
+					});
+				}
+			}
+			const noMove = pluginNoMove(item, landed);
+			if (noMove) {
+				report.finish(
+					true,
+					item.pluginId,
+					`no change — ${noMove}`,
+					Date.now() - startedAt,
+				);
+				result.unchanged.push(item.pluginId);
+			} else {
+				report.finish(
+					true,
+					item.pluginId,
+					`${scopes.join(", ")}${item.target ? ` → ${item.target}` : ""}`,
+					Date.now() - startedAt,
+				);
+				result.ok++;
+			}
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			report.finish(false, item.pluginId, msg, Date.now() - startedAt);
+			result.failed.push(item.pluginId);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * One plugin, ONE explicitly chosen scope, recording what landed.
+ *
+ * For the scope-targeted actions — a menu where the user picked "install in user
+ * scope" — where {@link applyPlugins}'s "every scope that is behind" would
+ * override the choice they just made.
+ *
+ * These exist so those call sites still get the read-back: writing the version
+ * you EXPECTED is the bug documented at length in `applyPlugins`, and it was
+ * live in the TUI's per-scope menu long after the CLI had fixed it.
+ *
+ * They take no version parameter, deliberately: there is nothing for a caller
+ * to pass that could be wrong.
+ */
+async function applyOneInScope(
+	run: (pluginId: string, scope: PluginScope) => Promise<void>,
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+	deps: PluginApplyDeps,
+): Promise<string | null> {
+	await run(pluginId, scope);
+	const actual = await deps.readInstalled(pluginId, scope, projectPath);
+	if (actual) await deps.saveInstalled(pluginId, actual, scope, projectPath);
+	return actual;
+}
+
+/**
+ * Install a plugin NOT yet present at `scope`.
+ *
+ * This used to cover updating too, on the premise that `installPlugin` and
+ * `updatePlugin` issued the identical command. They no longer do, and never
+ * safely did: `claude plugin install` ignores the version of an install that is
+ * already there. Sending an update through here is why the TUI's scope menu
+ * reported success and changed nothing. Use {@link updatePluginInScope}.
+ *
+ * @returns the version actually on disk afterwards, or null if it could not be
+ *   read — which is reported, never guessed.
+ */
+export async function installPluginInScope(
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
+): Promise<string | null> {
+	return applyOneInScope(deps.install, pluginId, scope, projectPath, deps);
+}
+
+/**
+ * Advance a plugin ALREADY installed at `scope` to the latest published version.
+ *
+ * @returns the version actually on disk afterwards, or null if it could not be
+ *   read — which is reported, never guessed.
+ */
+export async function updatePluginInScope(
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
+): Promise<string | null> {
+	// Same guard as the apply loop, for the same reason — see advanceInScope.
+	return applyOneInScope(
+		(id, sc) => advanceInScope(deps, id, sc, projectPath),
+		pluginId,
+		scope,
+		projectPath,
+		deps,
+	);
+}
+
+// -- binaries ----------------------------------------------------------------
+
+/**
+ * The command a bin item runs, or null when it is not work.
+ *
+ * The state→command rule itself is {@link binCommandForState}, shared with the
+ * TUI's CLI Tools row so the two front ends cannot run different commands for
+ * the same row. The CLI's plan report renders this same function, so what it
+ * shows is what runs.
+ */
+export function binCommandFor(
+	item: BinUpdateItem,
+	spec: ResolvedBin,
+): Command | null {
+	if (!binNeedsWork(item)) return null;
+	return binCommandForState(
+		item.action === "install" ? "install" : "upgrade",
+		item.target,
+		spec,
+	);
+}
+
+/**
+ * Why nothing moved for a bin, judged by RE-PROBING it; null when it moved.
+ *
+ * The re-probe resolves PATH again, so it reads the binary that runs NOW —
+ * which is what catches the no-ops planning cannot see: a stale brew tap, an
+ * installer that wrote a copy PATH does not resolve, `~/.bun/bin` missing from
+ * PATH. Versions are compared with the same comparator the planner used,
+ * because before and after can come from different sources ("v0.13.10" from
+ * `uv tool list` against "0.13.10").
+ *
+ * A read-back that cannot read a version is NOT a no-op: failing to read is not
+ * evidence nothing changed, and saying so would turn every go-less machine's
+ * upgrade into a warning.
+ */
+function binNoMove(item: BinUpdateItem, after: ToolFacts): string | null {
+	if (item.action === "install" && !after.present) {
+		return `the installer exited 0 but ${item.name} is still not on PATH`;
+	}
+	if (after.managed === false) {
+		return `installed, but PATH still runs ${after.resolvedPath ?? "another copy"}`;
+	}
+	if (
+		item.action === "upgrade" &&
+		after.installed !== null &&
+		item.installed !== null &&
+		compareToolVersions(after.installed, item.installed) === 0
+	) {
+		return `the installer exited 0 but ${item.name} is still ${after.installed}`;
+	}
+	return null;
+}
+
+/**
+ * The read-back probe, and the ONLY caller that lets the probe run a tool's
+ * `check` command.
+ *
+ * Planning never does: `check` comes from a marketplace `plugin.json`, and
+ * `--dry-run` / `--check` must execute nothing a catalogue supplied. Here the
+ * installer for this very tool has just run with the user's consent, and the
+ * probe's own narrowing means the only argv that can run is the tool asking
+ * itself its version (`tool-probe.ts`, `versionFromCheck`). Without it a tool
+ * whose installer keeps no readable record reads back as "version unknown",
+ * which R6 counts as changed — the safe answer, but never "no change — still
+ * 3.7c", the one the user needs.
+ */
+const REAL_READ_BACK = (spec: ResolvedBin): Promise<ToolFacts> =>
+	probeTool(spec, undefined, { allowCheckCommand: true });
+
+export async function applyBins(
+	plan: UpdatePlan,
+	report: ApplyReporter = SILENT_REPORTER,
+	// Named `run`, not `shell`. The old name was the misnomer that let a
+	// profile-supplied package name reach `/bin/sh`: a seam called "shell" reads
+	// as an invitation to hand it a string. It takes argv, and nothing here
+	// builds a shell line.
+	run: (command: Command) => Promise<boolean> = runCommand,
+	/** Read-back seam: re-probe ONE tool after its installer ran. */
+	probe: (spec: ResolvedBin) => Promise<ToolFacts> = REAL_READ_BACK,
+): Promise<ApplyResult> {
+	const result: ApplyResult = { ok: 0, failed: [], unchanged: [] };
+	for (const item of plan.bins) {
+		// The SAME predicate planWorkItems and planHasWork use. Skipping only
+		// `current` here would apply an `unknown` — "cannot tell" run as an
+		// upgrade.
+		if (!binNeedsWork(item)) continue;
+		const bin = plan.binSpecs.get(item.name);
+		if (!bin) continue;
+		report.begin(item.name);
+		const startedAt = Date.now();
+		const cmd = binCommandFor(item, bin);
+		if (!cmd) {
+			// Unreachable from the planner (a brew pin is never planned as work),
+			// but the meter counted this item, so it must finish.
+			report.finish(
+				false,
+				item.name,
+				`no command can move ${bin.via} to ${item.target ?? "the pin"}`,
+				Date.now() - startedAt,
+			);
+			result.failed.push(item.name);
+			continue;
+		}
+		// The installer owns the terminal for the duration: it streams its own
+		// output through inherited stdio.
+		const succeeded = await report.detach(() => run(cmd));
+		if (!succeeded) {
+			report.finish(
+				false,
+				item.name,
+				formatCommand(cmd),
+				Date.now() - startedAt,
+			);
+			result.failed.push(item.name);
+			continue;
+		}
+		let noMove: string | null = null;
+		try {
+			noMove = binNoMove(item, await probe(bin));
+		} catch {
+			// Could not read back: not evidence of a no-op.
+		}
+		// The reporter renders; only the argv above is executed.
+		if (noMove) {
+			report.finish(
+				true,
+				item.name,
+				`no change — ${noMove}`,
+				Date.now() - startedAt,
+			);
+			result.unchanged.push(item.name);
+		} else {
+			report.finish(
+				true,
+				item.name,
+				formatCommand(cmd),
+				Date.now() - startedAt,
+			);
+			result.ok++;
+		}
+	}
+	return result;
+}
+
+// -- skills ------------------------------------------------------------------
+
+/** Map a manifest skill ref to the SkillInfo shape installSkill expects. */
+function toSkillInfo(ref: ProfileSkillRef): SkillInfo {
+	return {
+		id: `${ref.repo}/${ref.path}`,
+		name: ref.name,
+		source: {
+			label: ref.repo,
+			repo: ref.repo,
+			skillsPath: path.dirname(ref.path),
+		},
+		repoPath: ref.path,
+		gitBlobSha: "",
+		frontmatter: null,
+		installed: false,
+		installedScope: null,
+		hasUpdate: false,
+	};
+}
+
+export async function applySkills(
+	plan: UpdatePlan,
+	projectPath: string,
+	report: ApplyReporter = SILENT_REPORTER,
+	install: typeof installSkill = installSkill,
+): Promise<ApplyResult> {
+	const result: ApplyResult = { ok: 0, failed: [], unchanged: [] };
+	for (const item of plan.skills) {
+		report.begin(item.name);
+		const startedAt = Date.now();
+		try {
+			await install(toSkillInfo(item.ref), "project", projectPath);
+			report.finish(true, item.name, item.ref.repo, Date.now() - startedAt);
+			result.ok++;
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			report.finish(false, item.name, msg, Date.now() - startedAt);
+			result.failed.push(item.name);
+		}
+	}
+	return result;
+}
+
+// -- the whole plan ----------------------------------------------------------
+
+export interface ApplyPlanOptions {
+	deps?: PluginApplyDeps;
+	report?: ApplyReporter;
+	/** Installer execution seam — see the note on {@link applyBins}. */
+	run?: (command: Command) => Promise<boolean>;
+	/** Read-back seam — see {@link applyBins}. Default: `probeTool(spec)`. */
+	probe?: (spec: ResolvedBin) => Promise<ToolFacts>;
+}
+
+/**
+ * Apply a whole plan: plugins, then binaries, then skills.
+ *
+ * Order matters. Plugins first because a binary requirement is declared BY a
+ * plugin, so installing the plugin is what makes the requirement real; skills
+ * last because they are the only re-fetched-every-time item and a failure there
+ * must not stop the two that actually advance versions.
+ */
+export async function applyPlan(
+	plan: UpdatePlan,
+	projectPath: string,
+	opts: ApplyPlanOptions = {},
+): Promise<UpdateOutcome> {
+	const report = opts.report ?? SILENT_REPORTER;
+	const plugins = await applyPlugins(
+		plan.plugins,
+		projectPath,
+		opts.deps ?? REAL_PLUGIN_DEPS,
+		report,
+	);
+	const bins = await applyBins(plan, report, opts.run, opts.probe);
+	const skills = await applySkills(plan, projectPath, report);
+
+	return {
+		plugins,
+		bins,
+		skills,
+		// `ok` counts only items read-back shows moved, so a no-op installer
+		// run is never "changed".
+		changed: plugins.ok + bins.ok + skills.ok,
+		unchanged: [...plugins.unchanged, ...bins.unchanged, ...skills.unchanged],
+		failed: [...plugins.failed, ...bins.failed, ...skills.failed],
+	};
+}
+
+/**
+ * The items `applyPlan` will actually touch — a progress denominator that
+ * cannot drift from the loops, because it is derived from the same predicates.
+ */
+export function planWorkItems(plan: UpdatePlan): string[] {
+	return [
+		...plan.plugins.filter(pluginNeedsWork).map((p) => p.pluginId),
+		...plan.bins.filter(binNeedsWork).map((b) => b.name),
+		...plan.skills.map((s) => s.name),
+	];
+}