magus-cli 7.7.0 → 7.9.0

package/src/services/plugin-requires.ts

@@ -1,21 +1,28 @@
 /**
- * Read plugin-declared binary dependencies from plugin.json `requires.bin`.
+ * What a plugin's plugin.json says it needs: its `dependencies` (other plugins)
+ * and its `requires` (binaries on the machine).
  *
- * A plugin declares the binaries it needs on PATH (e.g. terminal@magus needs
- * `tmux` and `tmux-mcp`). `magus install` resolves these transitively so a
- * teammate who enables a plugin also gets its binaries — closing the class of
- * bug where a plugin's MCP server silently fails because its binary is missing.
+ * `requires` is parsed by `shared/plugin/hooks/lib/requires-probe.ts` and by
+ * nothing else — the same file every declaring plugin carries for its
+ * SessionStart deps check, so the hook and magus read one declaration one way.
+ * This module only locates the manifest Claude Code loads and hands it over.
  */
 
 import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
-import type {
-	BinInstaller,
-	BinRequirement,
-	PluginRequires,
-} from "../types/index.js";
-import { goBinaryName } from "../utils/go-module.js";
+import {
+	type Arch,
+	type Os,
+	type ParseResult,
+	type Requirement,
+	applicable,
+	currentPlatform,
+	onPath,
+	parseRequires,
+	selectOption,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type { SelectedBin } from "../types/index.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { readInstalledPluginsRegistry } from "./claude-settings.js";
 import { getLocalMarketplacesInfo } from "./plugin-manager.js";
@@ -24,144 +31,6 @@ import { pickLoadedEntry } from "./plugin-resolution.js";
 const MARKETPLACES_DIR = (): string =>
 	path.join(os.homedir(), ".claude", "plugins", "marketplaces");
 
-const VALID_INSTALLERS: readonly BinInstaller[] = [
-	"bun",
-	"brew",
-	"npm",
-	"pip",
-	"go",
-];
-
-/**
- * Normalize a raw `requires.bin` entry into a complete BinRequirement,
- * filling in defaults. Returns null for entries that can't be made valid
- * (missing name, or an unrecognized installer).
- */
-function normalizeBin(raw: unknown): BinRequirement | null {
-	if (!raw || typeof raw !== "object") return null;
-	const o = raw as Record<string, unknown>;
-	const name = typeof o.name === "string" ? o.name.trim() : "";
-	if (!name) return null;
-
-	const via = o.via as BinInstaller;
-	if (!VALID_INSTALLERS.includes(via)) return null;
-
-	const bin: BinRequirement = {
-		name,
-		via,
-		check:
-			typeof o.check === "string" && o.check.trim()
-				? o.check.trim()
-				: `${name} --version`,
-	};
-	if (typeof o.package === "string") bin.package = o.package;
-	if (typeof o.formula === "string") bin.formula = o.formula;
-	if (typeof o.module === "string") bin.module = o.module;
-	if (typeof o.version === "string") bin.version = o.version;
-	return bin;
-}
-
-/** Split a package/module spec into its base and optional version. Handles
- *  scoped npm (@scope/pkg@1.2.0) and go modules (host/path@latest). */
-function splitVersion(spec: string): { base: string; version?: string } {
-	const at = spec.lastIndexOf("@");
-	// at > 0 avoids treating a leading npm scope "@scope/..." as a version.
-	if (at > 0) return { base: spec.slice(0, at), version: spec.slice(at + 1) };
-	return { base: spec };
-}
-
-const basename = (p: string): string => p.split("/").pop() ?? p;
-
-/**
- * Map a plugin.json `setup` block (the established convention: browser-use uses
- * `pip`, terminal uses `go` + `required`) to BinRequirements.
- *   setup: { bun|npm|pip: string[], go: string[], brew: string[], required: string[] }
- */
-function parseSetup(setup: unknown): BinRequirement[] {
-	if (!setup || typeof setup !== "object") return [];
-	const s = setup as Record<string, unknown>;
-	const bins: BinRequirement[] = [];
-
-	const pkgManager = (key: "bun" | "npm" | "pip"): void => {
-		for (const spec of (s[key] as string[] | undefined) ?? []) {
-			if (typeof spec !== "string") continue;
-			const { base, version } = splitVersion(spec);
-			bins.push({
-				name: basename(base),
-				via: key,
-				package: base,
-				version,
-				check: `${basename(base)} --version`,
-			});
-		}
-	};
-	pkgManager("bun");
-	pkgManager("npm");
-	pkgManager("pip");
-
-	// Not basename(): a Go module's trailing /vN is its major version, not the
-	// binary. `tmux-mcp/v2` installs `tmux-mcp`; naming it `v2` here made every
-	// downstream presence check look for a binary that never exists.
-	for (const spec of (s.go as string[] | undefined) ?? []) {
-		if (typeof spec !== "string") continue;
-		const { base, version } = splitVersion(spec);
-		const name = goBinaryName(base);
-		bins.push({
-			name,
-			via: "go",
-			module: base,
-			version,
-			check: `${name} --version`,
-		});
-	}
-	for (const spec of (s.brew as string[] | undefined) ?? []) {
-		if (typeof spec !== "string") continue;
-		bins.push({
-			name: spec,
-			via: "brew",
-			formula: spec,
-			check: `${spec} --version`,
-		});
-	}
-	// `required` names a system tool that must be present; brew is the assumed
-	// installer (matches the "system tools via brew" decision).
-	for (const name of (s.required as string[] | undefined) ?? []) {
-		if (typeof name !== "string") continue;
-		bins.push({ name, via: "brew", formula: name, check: `${name} --version` });
-	}
-
-	return bins;
-}
-
-/**
- * Parse a plugin.json's binary requirements from BOTH the established `setup`
- * block and the richer explicit `requires.bin` form. On a name collision the
- * explicit `requires.bin` entry wins (it can override installer/check/version).
- */
-export function parsePluginRequires(pluginJson: unknown): PluginRequires {
-	if (!pluginJson || typeof pluginJson !== "object") return {};
-	const obj = pluginJson as Record<string, unknown>;
-
-	const fromSetup = parseSetup(obj.setup);
-
-	const requires = obj.requires;
-	const binRaw =
-		requires && typeof requires === "object"
-			? (requires as Record<string, unknown>).bin
-			: undefined;
-	const fromRequires = Array.isArray(binRaw)
-		? binRaw.map(normalizeBin).filter((b): b is BinRequirement => b !== null)
-		: [];
-
-	// Merge, requires.bin winning by name.
-	const byName = new Map<string, BinRequirement>();
-	for (const b of fromSetup) byName.set(b.name, b);
-	for (const b of fromRequires) byName.set(b.name, b);
-
-	const bin = [...byName.values()];
-	return bin.length > 0 ? { bin } : {};
-}
-
 /**
  * The plugin.json at a plugin directory, parsed — null when there is none or
  * it does not parse.
@@ -191,12 +60,15 @@ export async function readPluginManifest(
 	return null;
 }
 
-/** Read `requires` from a plugin.json at a known plugin directory. */
+/**
+ * `requires` from the plugin.json at a plugin directory, or null when there is
+ * no readable manifest there.
+ */
 export async function readPluginRequires(
 	pluginPath: string,
-): Promise<PluginRequires> {
-	// Unreadable/malformed — treat as no requirements.
-	return parsePluginRequires(await readPluginManifest(pluginPath));
+): Promise<ParseResult | null> {
+	const manifest = await readPluginManifest(pluginPath);
+	return manifest === null ? null : parseRequires(manifest);
 }
 
 /**
@@ -257,8 +129,8 @@ export interface PluginManifestSources {
  *      row its loader resolves there (`pickLoadedEntry`). Claude Code checks
  *      the dependencies of the version it loads, which may be older than the
  *      marketplace's latest;
- *   2. its source in the local marketplace clone (the reader `requires.bin`
- *      uses), for a plugin not installed yet;
+ *   2. its source in the local marketplace clone, for a plugin not installed
+ *      yet;
  *   3. any other installed copy — where a plugin whose marketplace entry
  *      points at another repository lives.
  */
@@ -337,14 +209,73 @@ export async function resolvePluginPath(
 }
 
 /**
- * Resolve the binary requirements a plugin declares. Returns an empty array
- * when the plugin can't be located or declares none.
+ * The `requires` of the copy of `pluginId` Claude Code loads in `projectPath`
+ * (else its marketplace clone), and the directory it was read from — the same
+ * plugin.json its SessionStart hook reads through ${CLAUDE_PLUGIN_ROOT}. Null
+ * when no plugin.json for it can be read on this machine.
+ */
+export async function resolvePluginRequires(
+	pluginId: string,
+	projectPath: string = process.cwd(),
+	sources: PluginManifestSources = {},
+): Promise<{ dir: string; parse: ParseResult } | null> {
+	for (const dir of await pluginManifestDirs(pluginId, projectPath, sources)) {
+		const parse = await readPluginRequires(dir);
+		if (parse !== null) return { dir, parse };
+	}
+	return null;
+}
+
+/**
+ * Each requirement that applies on this platform, with its option chosen for
+ * this machine — the first in declaration order whose prerequisite is on PATH
+ * or declared beside it ({@link selectOption}) — and the directory it was read
+ * from, which a `${CLAUDE_PLUGIN_ROOT}` check and a plugin-relative script
+ * resolve against.
+ */
+export function selectBins(
+	requirements: Requirement[],
+	root: string | undefined,
+	pathEnv: string = process.env.PATH ?? "",
+	platform: { os: Os; arch: Arch } | null = currentPlatform(),
+): SelectedBin[] {
+	if (!platform) return [];
+	const live = applicable(requirements, platform.os);
+	const names = new Set(live.map((r) => r.name));
+	const has = (tool: string) =>
+		names.has(tool) || onPath(tool, pathEnv) !== null;
+	return live.map((r) => ({
+		...r,
+		chosen: selectOption(r, platform, has),
+		...(root ? { root } : {}),
+	}));
+}
+
+/**
+ * The requirements a plugin declares, selected for this machine, from the copy
+ * Claude Code loads in `projectPath`. Empty when the plugin cannot be located,
+ * declares none, or its declaration does not parse (doctor and the plugin's
+ * own SessionStart hook report that one).
  */
 export async function resolvePluginBinRequirements(
 	pluginId: string,
-): Promise<BinRequirement[]> {
-	const pluginPath = await resolvePluginPath(pluginId);
-	if (!pluginPath) return [];
-	const requires = await readPluginRequires(pluginPath);
-	return requires.bin ?? [];
+	projectPath: string = process.cwd(),
+): Promise<SelectedBin[]> {
+	const found = await resolvePluginRequires(pluginId, projectPath);
+	if (!found?.parse.ok) return [];
+	return selectBins(found.parse.requirements, found.dir);
+}
+
+/**
+ * The requirement named `name` that `pluginId` declares — how a catalogue tool
+ * owned by a plugin is checked and installed — or null when that plugin's
+ * declaration cannot be read here or does not name it.
+ */
+export async function ownedRequirement(
+	pluginId: string,
+	name: string,
+	projectPath: string = process.cwd(),
+): Promise<SelectedBin | null> {
+	const bins = await resolvePluginBinRequirements(pluginId, projectPath);
+	return bins.find((b) => b.name === name) ?? null;
 }

package/src/services/plugin-resolution.ts

@@ -4,7 +4,12 @@
  * Ported from Claude Code 2.1.274, decompiled: the relevance filter `SF`
  * (byte 178070986) and the selection function `Bls` (byte 178140984). The port
  * was validated against the real loader over 123/123 plugin resolutions across
- * 12 repositories and worktrees. RE-VALIDATE IT WHEN CLAUDE CODE UPDATES —
+ * 12 repositories and worktrees. Re-derived from 2.1.284 (`Aw` at byte
+ * 188165906, `t5t` at 188274660): the picker is unchanged, and the relevance
+ * filter now rejects a row with no `projectPath` and matches nothing by root when
+ * the current folder is in no repository (see {@link isRelevantInstallation}).
+ * Checked against `--debug-file` in a rootless folder (7/7) and in a repository
+ * (11/11). RE-VALIDATE IT WHEN CLAUDE CODE UPDATES —
  * this file describes someone else's algorithm, so a new release can move it
  * without anything here failing.
  *
@@ -21,26 +26,14 @@
  * This module holds NO magus policy. It answers the second question only, so
  * that a disagreement between the two is visible rather than averaged away.
  *
- * KNOWN DIVERGENCES from the decompiled original, both of which only ever REMOVE
- * candidates — so each can make this module name an entry the loader does not
- * use, and neither can make it miss one the loader does use:
- *
- *  1. The binary additionally rejects an entry whose `installPath` fails a
- *     path-safety check (`suspect(installPath)`). Not ported — every
- *     `installPath` is treated as non-suspect here.
- *  2. The binary's relevance filter reads `entry.projectPath === originalCwd ||
- *     repoRoot(entry.projectPath) === repoRoot(originalCwd)` with no guard on
- *     `projectPath` being absent at all. A project-scope row carrying no
- *     `projectPath` is rejected outright here (`isRelevantInstallation`), because
- *     what `repoRoot(undefined)` answers inside the binary was not measured and
- *     guessing it would put a row into the selection on a guess. Claude Code
- *     writes `projectPath` for every project-scope install, so the case is
- *     theoretical rather than observed.
- *
- * A THIRD divergence was removed rather than documented: two rootless paths used
- * to compare unequal here, so in a directory belonging to no repository every
- * rootless row was irrelevant to magus while the loader still counted it. See
- * {@link isRelevantInstallation}.
+ * ONE KNOWN DIVERGENCE from the decompiled original: the binary additionally
+ * rejects an entry whose `installPath` fails a path-safety check
+ * (`suspect(installPath)`). Not ported — every `installPath` is treated as
+ * non-suspect here. That check only ever removes candidates, so skipping it can
+ * make this module name an entry the loader does not use, never miss one the
+ * loader does use. A row's `projectPath` is compared as the raw string the
+ * binary compares — normalising it once added candidates the loader rejects —
+ * so path handling is not a second divergence.
  */
 
 import fs from "node:fs";
@@ -193,28 +186,27 @@ export function isRelevantInstallation(
 	if (isMachineWideScope(entry.scope)) return true;
 	if (!entry.projectPath) return false;
 
-	// The binary compares the two paths as raw strings. They are normalised here
-	// first, which can only turn a spelling difference of the same directory
-	// ("/p/a/" vs "/p/a") into a match — and that same pair already matches on
-	// the repository-root comparison below, which normalises on the way through.
-	if (path.resolve(entry.projectPath) === path.resolve(cwd)) return true;
-
-	// NULL MATCHES NULL, because the original's `repoRoot(entry.projectPath) ===
-	// repoRoot(originalCwd)` does: two directories in no repository at all compare
-	// equal there, so every rootless row competes when Claude Code runs from a
-	// scratch directory, a home directory, or any plain non-git folder.
+	// Raw strings, exactly as the binary compares them. Normalising first looked
+	// harmless — "/p/a/" and "/p/a" are the same directory — but it is not a
+	// no-op: in a folder outside any repository the root comparison below
+	// matches nothing, so normalisation was the ONLY thing that could make that
+	// pair relevant, and it added a candidate the loader rejects.
 	//
-	// This used to `return false` on a null `cwdRoot`, on the reasoning that two
-	// unrelated rootless directories are not the same project. That reasoning is
-	// magus policy, and this module holds none: with it, magus could name a
-	// `loadedVersion` the loader would not pick, and a repair would skip the very
-	// rows the loader treats as relevant — the same class of wrong answer the port
-	// exists to eliminate.
-	//
-	// The policy did not disappear, it moved to where it belongs: `repairStaleLoad`
-	// rewrites a row only when it belongs to THIS repository, which requires either
-	// the exact same directory or a non-null shared root. So a rootless row from an
-	// unrelated directory is reported as relevant (true) and never written (correct).
+	// Only `cwd` is resolved, because it stands in for the binary's own working
+	// directory, which is always absolute and has no trailing slash; a caller
+	// handing over "./x" or "/p/a/" means that directory. The row's path is
+	// compared exactly as written, as the binary compares it.
+	if (entry.projectPath === path.resolve(cwd)) return true;
+
+	// A directory in no repository matches NOTHING by root. Claude Code 2.1.284
+	// guards the comparison (`Aw` at byte 188165906:
+	// `let r=Zx(n);return r!==null&&Zx(e.projectPath)===r`), so in a rootless
+	// folder only its own rows and the machine-wide ones count. 2.1.274 had no
+	// guard and two nulls compared equal, which this port used to copy — and so
+	// named, in every rootless folder, versions from strangers' rows that the
+	// loader never looks at. Measured on 2.1.284 with `--debug-file` in a rootless
+	// folder: 7 of 7 plugins matched this rule, 2 of 7 matched the old one.
+	if (cwdRoot === null) return false;
 	return repoRootForPath(entry.projectPath, cache) === cwdRoot;
 }
 

package/src/services/profile-activate.ts

@@ -209,8 +209,7 @@ export function releasedCommittedSkillNote(folder: string): string {
 
 /**
  * Lines describing what activation did beyond the switch itself, phrased for
- * the terminal. The TUI words its own, shorter set (`activationNotices` in
- * ui/hooks/useProfileStartupModal.ts).
+ * the terminal.
  *
  * `tracked: false` leaves the tracked-path notices out, for the CLI, which
  * prints them itself as a warning with the fix beneath it

package/src/services/profile-startup.ts

@@ -69,11 +69,7 @@ import {
 	findEnclosingManifest,
 	readManifest,
 } from "./manifest.js";
-import {
-	type ActivationResult,
-	type ProfileChoice,
-	activationNotes,
-} from "./profile-activate.js";
+import type { ActivationResult, ProfileChoice } from "./profile-activate.js";
 import { freeProfileId } from "./profile-adopt.js";
 import {
 	activeProfile,
@@ -311,36 +307,29 @@ export async function oldFormatNeed(
 	};
 }
 
-/** What the TUI shows at startup, beyond the question (if any). */
+/** The TUI's startup: the question (if any), and what the gate refused. */
 export interface ProfileStartup {
 	need: ProfileStartupNeed;
 	/**
-	 * One line per thing the gate did: absorbed edits, regeneration, repairs.
-	 * Not what an activation reported — see `activations`.
-	 */
-	notices: string[];
-	/**
-	 * One line per thing the gate REFUSED — the lines the CLI stops on. Kept
-	 * apart from `notices` because a refusal can leave detection reading `ok`:
-	 * an old layout whose settings file does not parse is not converted, yet
-	 * still names its profile, so only this says the update did not happen.
+	 * One line per thing the gate REFUSED — the lines the CLI stops on. A
+	 * refusal can leave detection reading `ok`: an old layout whose settings
+	 * file does not parse is not converted, yet still names its profile, so only
+	 * this says the update did not happen.
 	 */
 	problems: string[];
 	/**
-	 * The activations the gate ran (a re-render, a format update). Handed over
-	 * as results rather than lines because the CLI's lines are the wrong words
-	 * for the TUI: they name plugin.json and backups, and they say "will not
-	 * load" in a line nothing marks as a warning. The TUI words them itself, in
-	 * user terms and with a tone (`activationWarnings` in the startup hook).
+	 * Every activation the gate ran — a re-render after profiles.json changed,
+	 * an older format converted — so the TUI can say what one of them could
+	 * not do. Absent is none.
 	 */
-	activations: ActivationResult[];
+	activations?: ActivationResult[];
 }
 
 /**
  * The TUI's startup: the same gate every CLI command runs, then detection.
  *
- * A failure in the gate never blocks the TUI — its message becomes a notice
- * and detection still runs, so the user is asked whatever is left to ask.
+ * A failure in the gate never blocks the TUI — its message is kept in
+ * `problems` and detection still runs, so the user is asked whatever is left.
  */
 export async function prepareProfileStartup(
 	projectPath: string,
@@ -354,21 +343,13 @@ export async function prepareProfileStartup(
 	if (!opts.convert) {
 		const format = await oldFormatNeed(projectPath);
 		if (format !== null) {
-			return { need: format, notices: [], problems: [], activations: [] };
+			return { need: format, problems: [] };
 		}
 	}
-	const notices: string[] = [];
 	const problems: string[] = [];
 	const activations: ActivationResult[] = [];
 	try {
 		const prep = await prepareProfileState(projectPath);
-		// The gate's lines, less the ones its activations contributed: those
-		// reach the TUI as `activations`, and passing both would say the same
-		// thing twice — once in the CLI's words, as if it were a success.
-		const fromActivations = new Set(
-			prep.activations.flatMap((a) => activationNotes(a, { tracked: false })),
-		);
-		notices.push(...prep.lines.filter((line) => !fromActivations.has(line)));
 		problems.push(...prep.problems);
 		activations.push(...prep.activations);
 	} catch (error) {
@@ -378,19 +359,18 @@ export async function prepareProfileStartup(
 	}
 	return {
 		need: await detectProfileStartupNeed(projectPath),
-		notices,
 		problems,
-		activations,
+		...(activations.length > 0 ? { activations } : {}),
 	};
 }
 
 /**
- * What the TUI shows once "Update it now" has run: another question, a notice
- * line, or an error modal.
+ * What the TUI does once "Update it now" has run: ask another question, carry
+ * on, or show an error modal.
  */
 export type FormatUpdateOutcome =
 	| { kind: "ask"; need: ProfileStartupNeed }
-	| { kind: "updated"; notice: string }
+	| { kind: "updated" }
 	| { kind: "failed"; title: string; message: string };
 
 /**
@@ -410,12 +390,7 @@ export function formatUpdateOutcome(
 		};
 	}
 	if (!needsNothing(result.need)) return { kind: "ask", need: result.need };
-	// One line, not the gate's notices: those are the conversion's working log
-	// (edits carried over, the old format's backup), and the result the user
-	// cares about is only that the update is done. What the conversion's
-	// activation warns about is NOT dropped: the caller words it from
-	// `result.activations`, as it does for any activation.
-	return { kind: "updated", notice: "Profile format updated" };
+	return { kind: "updated" };
 }
 
 // ─── What to offer, as data both surfaces render ─────────────────────────────

package/src/services/profile-state.ts

@@ -26,8 +26,9 @@
  */
 
 import path from "node:path";
-import type { ProfileManifest } from "../types/index.js";
-import { readManifest, writeManifest } from "./manifest.js";
+import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
+import { selectProfileId } from "./active-closure.js";
+import { readManifest, updateProfileEntry, writeManifest } from "./manifest.js";
 import {
 	type ReconcileResult,
 	absorbOlderLayout,
@@ -47,6 +48,7 @@ import {
 	type ActiveMarker,
 	LIVE_FILE_KEYS,
 	MACHINE_LOCAL_SETTINGS_KEYS,
+	activeProfile,
 	folderHash,
 	hasCurrentMarker,
 	hasOlderLayout,
@@ -68,6 +70,7 @@ import {
 	inspectManagedSkills,
 	skillFolder,
 } from "./profile-skills.js";
+import { resolveExtends } from "./resolver.js";
 import type { SettingsParseError } from "./settings-file.js";
 
 export type ActiveProfileCheck =
@@ -652,3 +655,70 @@ export async function withCliBookkeeping<T>(
 		for (const line of reconciled.lines) opts.report?.(line);
 	}
 }
+
+/** Whether a profile entry, `extends` included, turns the plugin on. */
+function profileLists(
+	entry: ProfileManifestEntry | undefined,
+	pluginId: string,
+): boolean {
+	if (!entry) return false;
+	const value = resolveExtends(entry).plugins?.[pluginId];
+	return value !== undefined && value !== false;
+}
+
+/**
+ * Stop a profile listing `pluginId`, so its next activation does not turn the
+ * plugin back on. Answers whether the profile no longer lists it — read back
+ * from profiles.json after the write, never assumed.
+ *
+ * For a deprecated plugin `magus update` removes. The uninstall that runs first
+ * deletes the plugin from this project's settings (measured, Claude Code
+ * 2.1.284), and `reconcileActiveProfile` would absorb that into the ACTIVE
+ * profile at the next entry point — but only there, and only for the active
+ * one. The Plugins screen's `a` runs no reconcile afterwards, so the screen kept
+ * the plugin declared and planned the same removal again; `magus update <name>`
+ * plans a profile that is not active, whose live files nothing absorbs from;
+ * and a profile declaring a plugin that is installed nowhere has no settings
+ * change to absorb at all. So the entry is edited here, directly, through
+ * {@link updateProfileEntry} — the editor `magus models use` writes through.
+ * The reconcile that follows (`withCliBookkeeping`, or the next entry point)
+ * finds profiles.json and the live files agreeing, and regenerates from it.
+ *
+ * `profile` undefined means the active one, chosen as the Plugins screen and
+ * `magus update` choose it; null means no profile, which lists nothing.
+ *
+ * Deletes the entry's own pin. When `extends` supplies the plugin, the pin
+ * becomes `false`, which is how an entry turns an inherited plugin off.
+ * Throws `SettingsParseError` when profiles.json exists and does not parse.
+ */
+export async function removePluginFromProfile(
+	projectPath: string,
+	pluginId: string,
+	profile?: string | null,
+): Promise<boolean> {
+	const manifest = await readManifest(projectPath);
+	const id =
+		profile === undefined
+			? selectProfileId(
+					Object.keys(manifest.profiles),
+					undefined,
+					await activeProfile(projectPath),
+				)
+			: profile;
+	if (!id || !profileLists(manifest.profiles[id], pluginId)) return true;
+
+	await updateProfileEntry(projectPath, id, (entry) => {
+		const plugins = { ...(entry.plugins ?? {}) };
+		delete plugins[pluginId];
+		if (profileLists({ ...entry, plugins }, pluginId))
+			plugins[pluginId] = false;
+		if (Object.keys(plugins).length > 0) entry.plugins = plugins;
+		// biome-ignore lint/performance/noDelete: absent, not undefined, in profiles.json
+		else delete entry.plugins;
+	});
+
+	return !profileLists(
+		(await readManifest(projectPath)).profiles[id],
+		pluginId,
+	);
+}