magus-cli 7.4.1 → 7.5.1

package/src/services/manifest.ts

@@ -9,6 +9,17 @@
 
 import path from "node:path";
 import fs from "fs-extra";
+import {
+	type FormattingOptions,
+	type JSONPath,
+	type Node as JsonNode,
+	applyEdits,
+	findNodeAtLocation,
+	format,
+	getNodeValue,
+	modify,
+	parseTree,
+} from "jsonc-parser";
 import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
 import { validateModelsConfig } from "./models-core.js";
 import {
@@ -160,10 +171,216 @@ export async function writeManifest(
 	projectPath?: string,
 ): Promise<void> {
 	const filePath = getManifestPath(projectPath);
-	// Read for the throw alone; the contents are about to be replaced.
-	await readProfilesFile(filePath);
+	// The refusal, and the view every caller read: `readManifest`'s. Only what
+	// the caller changed in that view is written (see `writeJsonMinimal`).
+	// `version` is the file's own, so a v1 file is recorded as v2 on write.
+	const current = await readProfilesFile(filePath);
+	await writeJsonMinimal(filePath, manifest, {
+		...migrateToV2(current),
+		version: current.version,
+	});
+}
+
+/**
+ * Write `next` to a JSON file, changing only the values that differ from
+ * `view` — every other byte stays exactly as it was: formatting, key order,
+ * inline arrays, the trailing newline, and keys the caller never saw.
+ *
+ * `profiles.json` is committed and reviewed. Re-serialising the whole file on
+ * every write turned one absorbed plugin into a 63-line diff that expanded
+ * every inline array and dropped `"strictVersions": false` — a key the
+ * manifest type models only as `true`. So the write is an edit, not a dump.
+ *
+ * `view` is what the caller READ — the same projection of the file it then
+ * mutated (for `readManifest`, `migrateToV2` of the raw file, which omits
+ * `strictVersions: false` and unmodelled keys). Diffing `next` against that
+ * view, not against the raw file, is what makes a key the caller never saw
+ * "unchanged" rather than "deleted". The changed paths are then applied to the
+ * file's own text: objects key by key, anything else (arrays included) as a
+ * whole value, so a changed array is re-written and an unchanged one is not.
+ * Each edit keeps the style around it — see {@link editJsonText}.
+ *
+ * A file that does not exist yet (or is empty) is written as 2-space JSON.
+ */
+export async function writeJsonMinimal(
+	filePath: string,
+	next: unknown,
+	view: unknown,
+): Promise<void> {
+	let text = "";
+	try {
+		text = await fs.readFile(filePath, "utf8");
+	} catch {
+		// Absent: written fresh below.
+	}
 	await fs.ensureDir(path.dirname(filePath));
-	await fs.writeJson(filePath, manifest, { spaces: 2 });
+	if (text.trim() === "") {
+		await fs.writeFile(filePath, `${JSON.stringify(next, null, 2)}\n`);
+		return;
+	}
+	const edits: Array<{ path: JSONPath; value: unknown }> = [];
+	diffJson(view, next, [], edits);
+	if (edits.length === 0) return;
+	const options: FormattingOptions = {
+		insertSpaces: !/^\t/m.test(text),
+		tabSize: detectIndent(text),
+		eol: text.includes("\r\n") ? "\r\n" : "\n",
+	};
+	for (const edit of edits) {
+		text = editJsonText(text, edit.path, edit.value, options);
+	}
+	await fs.writeFile(filePath, text);
+}
+
+const MULTILINE = /[\r\n]/;
+
+/**
+ * Set (or, for `undefined`, remove) the value at `at` in JSON `text`, changing
+ * as few bytes as possible and keeping the style around the change:
+ *
+ *   - a container written on one line (`{ "a": "x" }`) stays on one line — it
+ *     is re-written inline, whole;
+ *   - a value written on one line is replaced on that line;
+ *   - anything else is jsonc-parser's edit, formatted only across the bytes it
+ *     inserted plus the join on either side.
+ *
+ * jsonc-parser's own formatting option is not used: it re-formats every line
+ * an insertion or removal touches, so adding a key after an inline array
+ * expands that array — a line the write did not change.
+ */
+function editJsonText(
+	text: string,
+	at: JSONPath,
+	value: unknown,
+	options: FormattingOptions,
+): string {
+	const root = parseTree(text);
+	const node = root ? findNodeAtLocation(root, at) : undefined;
+	const parent =
+		root && at.length > 0
+			? findNodeAtLocation(root, at.slice(0, -1))
+			: undefined;
+	const source = (n: JsonNode) => text.slice(n.offset, n.offset + n.length);
+	const replace = (n: JsonNode, content: string) =>
+		text.slice(0, n.offset) + content + text.slice(n.offset + n.length);
+	const key = at[at.length - 1];
+
+	if (
+		parent?.type === "object" &&
+		typeof key === "string" &&
+		(parent.children?.length ?? 0) > 0 &&
+		!MULTILINE.test(source(parent))
+	) {
+		const updated = { ...(getNodeValue(parent) as Record<string, unknown>) };
+		if (value === undefined) delete updated[key];
+		else updated[key] = value;
+		return replace(parent, inlineJson(updated));
+	}
+
+	if (
+		node &&
+		value !== undefined &&
+		!MULTILINE.test(source(node)) &&
+		(!isContainer(value) || isNonEmptyContainerNode(node))
+	) {
+		return replace(node, inlineJson(value));
+	}
+
+	const [edit] = modify(text, at, value, {});
+	if (!edit) return text;
+	const next = applyEdits(text, [edit]);
+	const from = Math.max(0, edit.offset - 1);
+	const to = Math.min(next.length, edit.offset + edit.content.length + 1);
+	return applyEdits(
+		next,
+		format(
+			next,
+			{ offset: from, length: to - from },
+			{
+				...options,
+				keepLines: false,
+			},
+		),
+	);
+}
+
+function isContainer(value: unknown): boolean {
+	return (
+		(Array.isArray(value) && value.length > 0) ||
+		(isPlainObject(value) && Object.keys(value).length > 0)
+	);
+}
+
+function isNonEmptyContainerNode(node: JsonNode): boolean {
+	return (
+		(node.type === "object" || node.type === "array") &&
+		(node.children?.length ?? 0) > 0
+	);
+}
+
+/** One-line JSON in the common inline style: `{ "a": 1 }`, `["x", "y"]`. */
+function inlineJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(inlineJson).join(", ")}]`;
+	if (isPlainObject(value)) {
+		const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+		if (entries.length === 0) return "{}";
+		return `{ ${entries
+			.map(([k, v]) => `${JSON.stringify(k)}: ${inlineJson(v)}`)
+			.join(", ")} }`;
+	}
+	return JSON.stringify(value);
+}
+
+/** The indent width of the first indented line, or 2. */
+function detectIndent(text: string): number {
+	const match = /^( +)\S/m.exec(text);
+	return match ? (match[1] as string).length : 2;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Same meaning, whatever the key order. */
+function sameJson(a: unknown, b: unknown): boolean {
+	const sort = (v: unknown): unknown => {
+		if (Array.isArray(v)) return v.map(sort);
+		if (isPlainObject(v)) {
+			const out: Record<string, unknown> = {};
+			for (const key of Object.keys(v).sort()) out[key] = sort(v[key]);
+			return out;
+		}
+		return v;
+	};
+	return JSON.stringify(sort(a)) === JSON.stringify(sort(b));
+}
+
+/**
+ * The edits that turn `before` into `after`: objects are walked key by key; a
+ * removed key is an edit to `undefined`; every other difference replaces the
+ * value at that path whole. Key order alone is not a difference.
+ */
+function diffJson(
+	before: unknown,
+	after: unknown,
+	at: JSONPath,
+	out: Array<{ path: JSONPath; value: unknown }>,
+): void {
+	if (sameJson(before, after)) return;
+	if (isPlainObject(before) && isPlainObject(after)) {
+		for (const key of Object.keys(before)) {
+			if (!(key in after) || after[key] === undefined) {
+				out.push({ path: [...at, key], value: undefined });
+			}
+		}
+		for (const [key, value] of Object.entries(after)) {
+			if (value === undefined) continue;
+			if (key in before) diffJson(before[key], value, [...at, key], out);
+			else out.push({ path: [...at, key], value });
+		}
+		return;
+	}
+	out.push({ path: at, value: after });
 }
 
 export interface ManifestValidationError {
@@ -311,11 +528,10 @@ export async function updateProfileEntry(
  * Merge `patch` into `profiles.<profile>.settings`, optionally removing the
  * keys named in `unset`.
  *
- * Why this exists: `.claude/settings.json` is a symlink into the active
- * profile's materialized directory, so a live write lands in the right place —
- * but `materializeProfile` REWRITES that file from the manifest on every
- * `magus install`, so the live write alone silently regresses. The manifest
- * is the durable half of every settings write magus makes.
+ * Why this exists: `.claude/settings.json` is rendered from the active
+ * profile's entry, so a setting magus writes belongs in the entry — the next
+ * render reads it from there. The manifest is the durable half of every
+ * settings write magus makes.
  */
 export async function mergeManifestSettings(
 	projectPath: string,

package/src/services/models-manager.ts

@@ -11,15 +11,13 @@
  *
  * The routing is a PROFILE property, committed in `.claude/profiles.json` under
  * `profiles.<name>.models`. `.claude/models.json` is the generated view of it —
- * a symlink into `_profiles/<active>/models.json` when a profile is active, a
- * plain file when the project has no profiles. The hook reads the generated
- * file (it walks up from the session's cwd looking for exactly that name); a
- * teammate gets the routing by pulling profiles.json and running `magus
- * install`.
+ * a real file rendered from the active profile when there is one, a plain
+ * hand-kept file when the project has no profiles. The hook reads the
+ * generated file (it walks up from the session's cwd looking for exactly that
+ * name); a teammate gets the routing by pulling profiles.json.
  *
- * Writing only the generated file would be silently temporary: `magus
- * install` rewrites `_profiles/<name>/` from the manifest, so the routing would
- * disappear on the next install with nothing to explain why.
+ * Writing only the generated file would be silently temporary: every
+ * activation renders it again from the manifest.
  *
  * ## Why the full model id is resolved live
  *
@@ -61,17 +59,17 @@ import {
 	computeModelsStatus,
 	validateModelsConfig,
 } from "./models-core.js";
-import { materializeProfile } from "./profile-materializer.js";
-import { resolveAllProfiles, resolveProfile } from "./resolver.js";
+import { regenerateLiveFiles } from "./profile-activate.js";
+import { activeProfile } from "./profile-live.js";
+import { prepareProfileWrite } from "./profile-state.js";
 import { readSettingsFile, updateSettingsFile } from "./settings-file.js";
-import { activeProfile, syncProfileLink } from "./symlink-manager.js";
 
 /** `<projectPath>/.claude/models.json` — what the hook looks for. */
 export function configPath(projectPath: string): string {
 	return path.join(projectPath, ".claude", "models.json");
 }
 
-/** `<projectPath>/.claude/settings.json` — a symlink when a profile is active. */
+/** `<projectPath>/.claude/settings.json` — rendered from the profile when one is active. */
 function settingsPathFor(projectPath: string): string {
 	return path.join(projectPath, ".claude", "settings.json");
 }
@@ -368,8 +366,9 @@ export interface ApplyModelPresetResult {
  *
  * Validation comes first: an invalid config makes every subagent spawn fail, so
  * it must never reach disk. After that the order of the numbered steps below is
- * load-bearing — the manifest is written before materialization because
- * materialization regenerates `_profiles/<n>/` FROM the manifest, and the hook
+ * load-bearing — Claude Code's edits are absorbed before the manifest is
+ * written, the manifest is written before the live files because they are
+ * rendered FROM it, and the hook
  * is registered last because a hook pointing at a config that failed to write is
  * worse than no hook at all.
  */
@@ -405,10 +404,14 @@ export async function applyModelPreset(
 	if (Object.keys(manifest.profiles).length === 0 && args.ensureManifest) {
 		manifest = (await args.ensureManifest(projectPath)) ?? manifest;
 	}
+	// 2. The gate: anything Claude Code wrote to the live files goes into the
+	// profile first, so the regeneration below replaces nothing unrecorded —
+	// and a live file that does not parse stops everything, unwritten.
+	await prepareProfileWrite(projectPath);
 	const profile = await activeProfile(projectPath);
 
-	// 2. Record BOTH halves in the manifest: the routing, and the settings it
-	// implies. Without the settings half the next `magus install` rewrites
+	// 3. Record BOTH halves in the manifest: the routing, and the settings it
+	// implies. Without the settings half the next activation renders
 	// settings.json from the manifest and silently reverts the main thread's
 	// model — the routing would keep working and the orchestrator would not.
 	const recordedInManifest = await updateProfileEntry(
@@ -420,38 +423,23 @@ export async function applyModelPreset(
 		},
 	);
 
-	// 3. Regenerate the profile dir from the manifest, then point
-	// .claude/models.json at it. Only the models link is touched: repointing all
-	// four here would replace a project's real .mcp.json with a symlink as a side
-	// effect of choosing a model.
+	// 4. The live files. With a profile active, settings.json and models.json
+	// are rendered from the manifest just written. Without one, models.json is
+	// a plain file and settings.json is edited in place.
 	if (recordedInManifest && profile) {
-		// Re-read: `manifest` above predates the write, so resolving from it would
-		// materialize the OLD entry — which, having no `models`, would delete the
-		// file this call exists to create.
-		const written = await readManifest(projectPath);
-		await materializeProfile(
-			profile,
-			await resolveProfile(written, profile, { binResolver: noBins }),
-			projectPath,
-			await unionPluginIds(projectPath),
-		);
-		await syncProfileLink(profile, "models", projectPath);
+		await regenerateLiveFiles(projectPath);
 	} else {
-		// No profile: models.json is a plain committed-alongside file.
 		await fs.outputFile(
 			configPath(projectPath),
 			`${JSON.stringify(config, null, 2)}\n`,
 		);
+		await updateSettingsFile(settingsPath, (settings) => {
+			for (const [key, value] of Object.entries(patch.set)) {
+				settings[key] = value;
+			}
+		});
 	}
 
-	// 4. The live settings file (a symlink into the profile when one is active,
-	// so this lands in the same place materialization just wrote).
-	await updateSettingsFile(settingsPath, (settings) => {
-		for (const [key, value] of Object.entries(patch.set)) {
-			settings[key] = value;
-		}
-	});
-
 	// 5. Without this, nothing routes.
 	const hook = await registerAgentModelHook();
 
@@ -480,6 +468,8 @@ export async function clearModels(projectPath: string): Promise<void> {
 			)
 		: [];
 
+	// The gate first; a live file that does not parse stops everything.
+	await prepareProfileWrite(projectPath);
 	const profile = await activeProfile(projectPath);
 	const removed = await updateProfileEntry(projectPath, profile, (entry) => {
 		// biome-ignore lint/performance/noDelete: absence is the state, not undefined
@@ -493,21 +483,14 @@ export async function clearModels(projectPath: string): Promise<void> {
 		}
 	});
 
+	// With a profile active, rendering from an entry with no `models` REMOVES
+	// .claude/models.json — that is the whole mechanism by which `off` is off.
 	if (removed && profile) {
-		// Re-materializing with no `models` in the closure DELETES
-		// _profiles/<n>/models.json, and the relink then removes the now-dangling
-		// .claude/models.json. That is the whole mechanism by which `off` is off.
-		const manifest = await readManifest(projectPath);
-		await materializeProfile(
-			profile,
-			await resolveProfile(manifest, profile, { binResolver: noBins }),
-			projectPath,
-			await unionPluginIds(projectPath),
-		);
-		await syncProfileLink(profile, "models", projectPath);
+		await regenerateLiveFiles(projectPath);
+		return;
 	}
-	await fs.remove(configPath(projectPath));
 
+	await fs.remove(configPath(projectPath));
 	const settingsPath = settingsPathFor(projectPath);
 	if (await fs.pathExists(settingsPath)) {
 		await updateSettingsFile(settingsPath, (settings) => {
@@ -543,26 +526,6 @@ function unclaimModelSettings(
 	}
 }
 
-/**
- * Materialization needs no binary requirements — it writes settings, mcp,
- * models and skills, and reads none of `closure.bins`. Skipping the resolver's
- * per-plugin `plugin.json` reads keeps `models use` off the marketplace cache
- * entirely.
- */
-const noBins = async () => [];
-
-/**
- * The manifest-wide union of plugin ids, which `materializeProfile` needs to
- * keep writing the explicit `false` entries that make `profile switch`
- * exclusive. Re-materializing without it would silently make switching additive
- * again — a routing change must not have that side effect.
- */
-async function unionPluginIds(projectPath: string): Promise<string[]> {
-	const manifest = await readManifest(projectPath);
-	const union = await resolveAllProfiles(manifest, { binResolver: noBins });
-	return Object.keys(union.plugins);
-}
-
 // ─── Status ───────────────────────────────────────────────────────────────────
 
 /** What `magus models status` and `magus doctor` report. */
@@ -596,7 +559,7 @@ async function readSettingsFileSafely(
 	}
 }
 
-/** Re-apply the config already on disk. Used by `doctor --fix` to clear drift. */
+/** Re-apply the config already on disk. Used by `doctor --fix` to repair settings the config implies. */
 export async function reapplyModels(
 	projectPath: string,
 ): Promise<ApplyModelPresetResult | null> {

package/src/services/plugin-dependencies.ts

@@ -0,0 +1,48 @@
+/**
+ * Which plugins a plugin depends on, as its own plugin.json declares them.
+ *
+ * A plugin's `dependencies` must be ENABLED for it to load — Claude Code's
+ * loader refuses it otherwise ("Dependency "claudish@magus" is disabled —
+ * enable it or remove the dependency"). A profile renders every other
+ * profile's plugins as `false`, so without reading these a profile that
+ * enables dev@magus but not claudish@magus switched dev off in effect.
+ *
+ * The reading itself lives beside the other plugin.json readers
+ * (`resolvePluginDependencies` in `plugin-requires.ts`). This module is only
+ * the entry point, kept free of imports: the render reaches it on every
+ * command, and a test preload replaces it so no test ever reads the plugin
+ * files installed on the machine running it.
+ */
+
+/**
+ * The plugin ids `pluginId` declares as dependencies, or null when no
+ * plugin.json for it can be read on this machine. `projectPath` picks the
+ * installed copy Claude Code loads there (default: the current directory).
+ */
+export type PluginDependencyReader = (
+	pluginId: string,
+	projectPath?: string,
+) => Promise<string[] | null>;
+
+let replacement: PluginDependencyReader | null = null;
+
+/**
+ * Replace where dependencies are read from, or restore the real reader with
+ * null. For tests: the real one reads `~/.claude/plugins`, which differs on
+ * every machine.
+ */
+export function setPluginDependencyReader(
+	reader: PluginDependencyReader | null,
+): void {
+	replacement = reader;
+}
+
+/** Read `pluginId`'s declared dependencies — see {@link PluginDependencyReader}. */
+export async function readPluginDependencies(
+	pluginId: string,
+	projectPath?: string,
+): Promise<string[] | null> {
+	if (replacement) return replacement(pluginId, projectPath);
+	const { resolvePluginDependencies } = await import("./plugin-requires.js");
+	return resolvePluginDependencies(pluginId, projectPath);
+}

package/src/services/plugin-requires.ts

@@ -17,7 +17,9 @@ import type {
 } from "../types/index.js";
 import { goBinaryName } from "../utils/go-module.js";
 import { parsePluginId } from "../utils/string-utils.js";
+import { readInstalledPluginsRegistry } from "./claude-settings.js";
 import { getLocalMarketplacesInfo } from "./plugin-manager.js";
+import { pickLoadedEntry } from "./plugin-resolution.js";
 
 const MARKETPLACES_DIR = (): string =>
 	path.join(os.homedir(), ".claude", "plugins", "marketplaces");
@@ -160,28 +162,149 @@ export function parsePluginRequires(pluginJson: unknown): PluginRequires {
 	return bin.length > 0 ? { bin } : {};
 }
 
+/**
+ * The plugin.json at a plugin directory, parsed — null when there is none or
+ * it does not parse.
+ *
+ * `.claude-plugin/plugin.json` FIRST — that is the only location Claude Code's
+ * runtime loader reads, and the only one its documentation describes. The root
+ * fallback stays for third-party plugins whose authors put it there; such a
+ * manifest is inert as far as Claude Code is concerned, but magus can still
+ * read metadata out of it rather than reporting nothing.
+ */
+export async function readPluginManifest(
+	pluginPath: string,
+): Promise<unknown | null> {
+	const candidates = [
+		path.join(pluginPath, ".claude-plugin", "plugin.json"),
+		path.join(pluginPath, "plugin.json"),
+	];
+	for (const manifestPath of candidates) {
+		try {
+			if (await fs.pathExists(manifestPath)) {
+				return await fs.readJson(manifestPath);
+			}
+		} catch {
+			return null; // Present but malformed: never fall through to another.
+		}
+	}
+	return null;
+}
+
 /** Read `requires` from a plugin.json at a known plugin directory. */
 export async function readPluginRequires(
 	pluginPath: string,
 ): Promise<PluginRequires> {
-	// `.claude-plugin/plugin.json` FIRST — that is the only location Claude Code's
-	// runtime loader reads, and the only one its documentation describes. The root
-	// fallback stays for third-party plugins whose authors put it there; such a manifest
-	// is inert as far as Claude Code is concerned, but magus can still read metadata
-	// out of it rather than reporting nothing.
-	const manifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
-	try {
-		if (await fs.pathExists(manifestPath)) {
-			return parsePluginRequires(await fs.readJson(manifestPath));
+	// Unreadable/malformed — treat as no requirements.
+	return parsePluginRequires(await readPluginManifest(pluginPath));
+}
+
+/**
+ * The plugin ids a plugin.json's `dependencies` names, resolved the way
+ * Claude Code resolves them: an entry that names a marketplace
+ * (`"claudish@magus"`, or `{ "name": "claudish", "marketplace": "magus" }`)
+ * is taken as written; a bare name (`"claudish"`, `{ "name": "claudish" }`)
+ * is looked up in the DEPENDENT's marketplace — `claudish` declared by
+ * dev@magus is claudish@magus. Version constraints are not modelled here: a
+ * dependency is enabled, and installed at latest.
+ */
+export function parsePluginDependencies(
+	pluginJson: unknown,
+	dependentId: string,
+): string[] {
+	if (!pluginJson || typeof pluginJson !== "object") return [];
+	const raw = (pluginJson as Record<string, unknown>).dependencies;
+	if (!Array.isArray(raw)) return [];
+	const home = parsePluginId(dependentId)?.marketplace;
+	const out = new Set<string>();
+	for (const item of raw) {
+		let name = "";
+		let marketplace: string | undefined;
+		if (typeof item === "string") {
+			name = item.trim();
+		} else if (item && typeof item === "object") {
+			const o = item as Record<string, unknown>;
+			if (typeof o.name === "string") name = o.name.trim();
+			if (typeof o.marketplace === "string" && o.marketplace.trim()) {
+				marketplace = o.marketplace.trim();
+			}
+		}
+		if (!name) continue;
+		if (name.lastIndexOf("@") > 0) {
+			out.add(name);
+			continue;
 		}
-		const rootLevel = path.join(pluginPath, "plugin.json");
-		if (await fs.pathExists(rootLevel)) {
-			return parsePluginRequires(await fs.readJson(rootLevel));
+		const at = marketplace ?? home;
+		// A bare id cannot be named in enabledPlugins, so it is not one to render.
+		if (at) out.add(`${name}@${at}`);
+	}
+	return [...out];
+}
+
+/** Where {@link resolvePluginDependencies} looks; replaced in tests. */
+export interface PluginManifestSources {
+	/** The plugins directory holding the registry — see `pluginsDir`. */
+	root?: string;
+	/** The plugin's source in the local marketplace clone. */
+	clone?: (pluginId: string) => Promise<string | null>;
+}
+
+/**
+ * The directories that may hold `pluginId`'s plugin.json on this machine, in
+ * the order they are trusted:
+ *
+ *   1. the installed copy Claude Code LOADS in `projectPath` — the registry
+ *      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;
+ *   3. any other installed copy — where a plugin whose marketplace entry
+ *      points at another repository lives.
+ */
+async function pluginManifestDirs(
+	pluginId: string,
+	projectPath: string,
+	sources: PluginManifestSources,
+): Promise<string[]> {
+	const dirs: string[] = [];
+	const installed: string[] = [];
+	try {
+		const registry = await readInstalledPluginsRegistry(sources.root);
+		const rows = registry.plugins?.[pluginId];
+		if (Array.isArray(rows)) {
+			const loaded = pickLoadedEntry(rows, projectPath)?.installPath;
+			if (loaded) dirs.push(loaded);
+			for (const row of rows) {
+				if (typeof row.installPath === "string" && row.installPath) {
+					installed.push(row.installPath);
+				}
+			}
 		}
 	} catch {
-		// Unreadable/malformed — treat as no requirements.
+		// No readable registry: the clone alone decides.
+	}
+	const clone = await (sources.clone ?? resolvePluginPath)(pluginId);
+	if (clone) dirs.push(clone);
+	return [...new Set([...dirs, ...installed])];
+}
+
+/**
+ * The plugin ids `pluginId` declares as dependencies (see
+ * {@link parsePluginDependencies}) in the copy Claude Code loads in
+ * `projectPath`, or null when no plugin.json for it can be read on this
+ * machine — reported by the caller, never guessed.
+ */
+export async function resolvePluginDependencies(
+	pluginId: string,
+	projectPath: string = process.cwd(),
+	sources: PluginManifestSources = {},
+): Promise<string[] | null> {
+	for (const dir of await pluginManifestDirs(pluginId, projectPath, sources)) {
+		const manifest = await readPluginManifest(dir);
+		if (manifest !== null) return parsePluginDependencies(manifest, pluginId);
 	}
-	return {};
+	return null;
 }
 
 /**