@iowarp/clio-coder 0.4.6 → 0.4.7

package/src/domains/interop/import.ts

@@ -0,0 +1,277 @@
+/**
+ * Explicit library import: one plan/apply/release seam shared by the CLI and a
+ * later TUI. A plan retains the fetched source until apply or release; apply
+ * re-projects the source, refuses drift, publishes through the library install
+ * seam with foreign trust, then reports publication, validation and runtime
+ * admission as three separate facts.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fetchPluginSource, parsePluginGithubSource, pluginLocalPath } from "../plugins/catalog.js";
+import { listInstalledPlugins, pluginBaseDir, readPluginManifest } from "../plugins/index.js";
+import type { ForeignPackageFormat, PluginOrigin } from "../plugins/types.js";
+import { type LibraryPackageValidationResult, validateLibraryPackage } from "../resources/library-validation.js";
+import {
+	type PreparedAdoption,
+	prepareForeignPackage,
+	preparePortablePackage,
+	unmetRequirements,
+	vendorOf,
+} from "./adopt.js";
+import { detectForeignPlugin, type ForeignPluginDetection, type ForeignResourceOutcome } from "./foreign.js";
+import { installInteropPackage } from "./install.js";
+import { digest, reviewFingerprint } from "./projection.js";
+import type { InteropAgentId } from "./types.js";
+
+export interface LibraryImportSource {
+	input: string;
+	transport: "local" | "github";
+	/** Directory the plan reads; staged clone for github, the operator's path for local. */
+	root: string;
+	url?: string;
+	path?: string;
+}
+
+export interface LibraryImportPlan {
+	source: LibraryImportSource;
+	detection: ForeignPluginDetection;
+	format?: ForeignPackageFormat;
+	action: "install" | "blocked";
+	/** Why the plan is blocked, or review notes for an installable plan. */
+	reasons: string[];
+	id?: string;
+	version?: string;
+	destination?: string;
+	digest?: string;
+	scope: "user" | "project";
+	cwd: string;
+	outcomes: ForeignResourceOutcome[];
+	unsupported: string[];
+	omitted: string[];
+	requirements: string[];
+	/** Exactly the provenance record apply persists. */
+	origin: PluginOrigin;
+	/** Full-tree review fingerprint (paths, modes, bytes, hidden manifests, omitted files); apply refuses drift. */
+	reviewFingerprint: string;
+	/** Reviewed bytes. Never serialized by the CLI. */
+	files?: Readonly<Record<string, string>>;
+	/** Release retained remote staging. Never serialized. */
+	cleanup: () => void;
+}
+
+export interface LibraryImportApplyResult {
+	/** The package was written to disk and recorded in install state. */
+	published: boolean;
+	installed?: string;
+	destination?: string;
+	/** Native validation of the installed recipe files; absent when nothing was published. */
+	validation?: LibraryPackageValidationResult;
+	/**
+	 * Trust admission is a separate fact from publication and validity. This is
+	 * only the gate setting the caller supplied; actual recipe availability is
+	 * the inventory's fact.
+	 */
+	admission: {
+		trust: "foreign";
+		gate: "integrations.projectResources.trustProjectImports";
+		gateEnabled: boolean | "unknown";
+	};
+	diagnostics: string[];
+}
+
+function prepare(
+	root: string,
+	format?: "claude-code" | "codex",
+): { detection: ForeignPluginDetection; value: PreparedAdoption } {
+	const detection = detectForeignPlugin(root, format);
+	if (detection.format === "portable") return { detection, value: preparePortablePackage(root) };
+	if (detection.format === "none") throw new Error(detection.diagnostics.join(" "));
+	return { detection, value: prepareForeignPackage(root, detection.format) };
+}
+
+export function planLibraryImport(
+	input: string,
+	options: {
+		cwd?: string;
+		scope?: "user" | "project";
+		format?: "claude-code" | "codex";
+		/** Set only when the source was discovered inside an installed local agent. */
+		host?: InteropAgentId;
+		marketplace?: string;
+	} = {},
+): LibraryImportPlan {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const scope = options.scope ?? "user";
+	const remote = parsePluginGithubSource(input);
+	const local = pluginLocalPath(input, cwd);
+	const fetched = fetchPluginSource(input, cwd);
+	const source: LibraryImportSource = remote
+		? { input, transport: "github", root: fetched.root, url: input }
+		: { input, transport: "local", root: fetched.root, path: local };
+	const originSource = remote ? input : path.resolve(local);
+	try {
+		const raw = reviewFingerprint(fetched.root);
+		let detection: ForeignPluginDetection;
+		let value: PreparedAdoption | undefined;
+		const reasons: string[] = [];
+		try {
+			({ detection, value } = prepare(fetched.root, options.format));
+		} catch (error) {
+			detection = detectForeignPlugin(fetched.root, options.format);
+			reasons.push(error instanceof Error ? error.message : String(error));
+		}
+		reasons.push(...detection.diagnostics);
+		const format = value?.format ?? (detection.format === "none" ? undefined : detection.format);
+		const origin: PluginOrigin = {
+			kind: "import",
+			source: originSource,
+			transport: remote ? "github" : "local",
+			format: format ?? "portable",
+			...(options.host ? { host: options.host } : {}),
+			...(options.marketplace ? { marketplace: options.marketplace } : {}),
+		};
+		const base: Omit<LibraryImportPlan, "action" | "reasons"> = {
+			source,
+			detection,
+			...(format ? { format } : {}),
+			scope,
+			cwd,
+			outcomes: value?.outcomes ?? [],
+			unsupported: value?.unsupported ?? [],
+			omitted: value?.omitted ?? [],
+			requirements: value?.requirements ?? [],
+			origin,
+			reviewFingerprint: raw,
+			cleanup: fetched.cleanup,
+		};
+		if (!value) return { ...base, action: "blocked", reasons };
+		const missing = unmetRequirements(value.requirements, cwd, scope, vendorOf(value.format));
+		if (missing.length)
+			reasons.push(
+				`Unsatisfied package requirements: ${missing.join(", ")}. Install or import those packages first; no extra resources are imported.`,
+			);
+		const installed = listInstalledPlugins(cwd, { all: true });
+		if (installed.some((pkg) => pkg.id === value.id && pkg.scope === scope))
+			reasons.push(`Package ${value.id} is already installed in ${scope} scope; remove it before importing again.`);
+		const blocked = missing.length > 0 || installed.some((pkg) => pkg.id === value.id && pkg.scope === scope);
+		return {
+			...base,
+			action: blocked ? "blocked" : "install",
+			reasons: [value.note, ...reasons],
+			id: value.id,
+			version: value.version,
+			destination: path.join(pluginBaseDir(scope, cwd), value.id),
+			digest: digest(value.files),
+			files: value.files,
+		};
+	} catch (error) {
+		fetched.cleanup();
+		throw error;
+	}
+}
+
+export function releaseLibraryImport(plan: LibraryImportPlan): void {
+	plan.cleanup();
+}
+
+/** Apply always releases the plan, whether it installs, refuses, or throws. */
+export function applyLibraryImport(
+	plan: LibraryImportPlan,
+	approved: boolean,
+	options: { trustProjectImports?: boolean } = {},
+): LibraryImportApplyResult {
+	const admission = {
+		trust: "foreign" as const,
+		gate: "integrations.projectResources.trustProjectImports" as const,
+		gateEnabled: options.trustProjectImports === undefined ? ("unknown" as const) : options.trustProjectImports,
+	};
+	const result: LibraryImportApplyResult = { published: false, admission, diagnostics: [] };
+	let staging: string | undefined;
+	try {
+		if (!approved) {
+			result.diagnostics.push("Approval required; nothing installed.");
+			return result;
+		}
+		if (plan.action !== "install" || !plan.files || !plan.id || !plan.digest) {
+			result.diagnostics.push(...(plan.reasons.length ? plan.reasons : ["Plan is not installable."]));
+			return result;
+		}
+		if (reviewFingerprint(plan.source.root) !== plan.reviewFingerprint)
+			throw new Error("Source changed after review; inspect a new plan.");
+		const current = prepare(plan.source.root, plan.format === "portable" ? undefined : plan.format).value;
+		if (digest(plan.files) !== plan.digest || digest(current.files) !== plan.digest)
+			throw new Error("Plan changed after review; inspect a new plan.");
+		const missing = unmetRequirements(current.requirements, plan.cwd, plan.scope, vendorOf(current.format));
+		if (missing.length)
+			throw new Error(
+				`Unsatisfied package requirements after review: ${missing.join(", ")}. No extra resources are imported.`,
+			);
+		staging = mkdtempSync(path.join(tmpdir(), "clio-coder-library-import-"));
+		for (const [file, text] of Object.entries(plan.files)) {
+			const target = path.join(staging, file);
+			mkdirSync(path.dirname(target), { recursive: true });
+			writeFileSync(target, text, { mode: 0o644 });
+		}
+		const candidate = readPluginManifest(staging);
+		if (!candidate.valid || !candidate.contentDigest)
+			throw new Error(candidate.diagnostics.map((d) => d.message).join("; "));
+		const installed = installInteropPackage({
+			sourcePath: staging,
+			kind: candidate.manifest?.clio.kind ?? "plugin",
+			trust: "foreign",
+			cwd: plan.cwd,
+			scope: plan.scope,
+			expectedId: plan.id,
+			expectedDigest: candidate.contentDigest,
+			origin: plan.origin,
+		});
+		result.diagnostics.push(...installed.diagnostics.map((d) => d.message));
+		if (installed.plugin) {
+			result.published = true;
+			result.installed = installed.plugin.id;
+			result.destination = installed.plugin.rootPath;
+			result.validation = validateLibraryPackage(installed.plugin.rootPath, { cwd: plan.cwd });
+		}
+		return result;
+	} catch (error) {
+		result.diagnostics.push(error instanceof Error ? error.message : String(error));
+		return result;
+	} finally {
+		if (staging) rmSync(staging, { recursive: true, force: true });
+		releaseLibraryImport(plan);
+	}
+}
+
+/** JSON-safe view: no reviewed bytes, no callbacks. */
+export function libraryImportPlanSummary(plan: LibraryImportPlan): Omit<LibraryImportPlan, "files" | "cleanup"> {
+	const { files: _files, cleanup: _cleanup, ...summary } = plan;
+	return summary;
+}
+
+export function renderLibraryImportPlan(plan: LibraryImportPlan): string {
+	const lines = [
+		`Import ${plan.source.transport === "github" ? plan.source.url : plan.source.path} into Clio (${plan.scope})?`,
+		`  Format: ${plan.format ?? "unknown"}${plan.detection.manifestPath ? ` (${plan.detection.manifestPath})` : ""}`,
+		...(plan.action === "install"
+			? [`  Package: ${plan.id} ${plan.version}`, `  Destination: ${plan.destination}`, `  SHA-256: ${plan.digest}`]
+			: ["  BLOCKED"]),
+		...plan.reasons.map((reason) => `  ${reason}`),
+		...(plan.requirements.length ? [`  Requires installed packages: ${plan.requirements.join(", ")}`] : []),
+		...plan.outcomes.map((outcome) => {
+			const detail = [
+				...(outcome.omittedFields?.length ? [`omitted frontmatter: ${outcome.omittedFields.join(", ")}`] : []),
+				...(outcome.omittedFiles?.length ? [`omitted files: ${outcome.omittedFiles.join(", ")}`] : []),
+				...(outcome.reason ? [outcome.reason] : []),
+			];
+			return outcome.status === "converted"
+				? `  CONVERT ${outcome.kind} ${outcome.name} -> ${outcome.destination}${detail.length ? ` (${detail.join("; ")})` : ""}`
+				: `  UNSUPPORTED ${outcome.kind} ${outcome.name} (${outcome.source}): ${detail.join("; ")}`;
+		}),
+		...plan.unsupported.map((feature) => `  UNSUPPORTED ${feature}`),
+		...plan.omitted.map((file) => `  SKIP ${file}: executable, host-specific, or non-text data.`),
+		"Imported resources keep foreign trust and stay behind the project-import trust setting.",
+		"Source files are never changed. Approval applies only to the displayed content.",
+	];
+	return lines.join("\n");
+}

package/src/domains/interop/index.ts

@@ -8,6 +8,14 @@ export const InteropDomainModule: DomainModule<InteropContract> = {
 	createExtension: createInteropBundle,
 };
 
+export type { AdoptionKind, InteropAdoptionEntry, InteropAdoptionPlan, PreparedAdoption } from "./adopt.js";
+export {
+	applyInteropAdoption,
+	planInteropAdoption,
+	prepareForeignPackage,
+	preparePortablePackage,
+	renderInteropAdoptionPlan,
+} from "./adopt.js";
 export {
 	acceptInteropAgents,
 	declineInteropAgents,
@@ -19,6 +27,22 @@ export {
 } from "./consent.js";
 export type { InteropContract } from "./contract.js";
 export { detectInteropAgents, resolveOnPath } from "./detect.js";
+export type {
+	ForeignPluginDetection,
+	ForeignPluginFormat,
+	ForeignPluginProjection,
+	ForeignResourceOutcome,
+} from "./foreign.js";
+export { detectForeignPlugin, FOREIGN_MANIFESTS, projectForeignPlugin } from "./foreign.js";
+export type { LibraryImportApplyResult, LibraryImportPlan, LibraryImportSource } from "./import.js";
+export {
+	applyLibraryImport,
+	libraryImportPlanSummary,
+	planLibraryImport,
+	releaseLibraryImport,
+	renderLibraryImportPlan,
+} from "./import.js";
+export { discoverInteropInventory } from "./inventory.js";
 export { InteropManifest } from "./manifest.js";
 export { foreignAgentDirs, INTEROP_AGENT_KINDS, interopAgentKind, interopSourceRank } from "./registry.js";
 export { readInteropReport, writeInteropReport } from "./state.js";

package/src/domains/interop/install.ts

@@ -0,0 +1,6 @@
+import { installLibraryPackage, type LibraryPackageInstallInput, type PluginInstallResult } from "../plugins/index.js";
+
+/** Keep every adoption on the same provenance, trust, integrity and removal seam as the library. */
+export function installInteropPackage(input: LibraryPackageInstallInput): PluginInstallResult {
+	return installLibraryPackage(input);
+}

package/src/domains/interop/inventory.ts

@@ -0,0 +1,351 @@
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+import type { InteropAgentKind, InteropInventory, InteropInventoryItem, InteropResourceKind } from "./types.js";
+
+const MAX_FILES = 4096;
+const MAX_BYTES = 2 * 1024 * 1024;
+export function inventoryText(file: string): string {
+	const stat = lstatSync(file);
+	if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BYTES) throw new Error("not a bounded regular file");
+	return readFileSync(file, "utf8");
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Only declared configuration/resource roots; never sessions, history or executable modules. */
+export function discoverInteropInventory(
+	kind: InteropAgentKind,
+	home: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv = {},
+): InteropInventory {
+	const layout = kind.inventory;
+	const result: InteropInventory = { status: "known", items: [], diagnostics: [], listing: "unknown" };
+	if (!layout) return { ...result, status: "unknown", diagnostics: ["Inventory is not extended for this host."] };
+	const seen = new Set<string>();
+	let visited = 0;
+	const unknown = (message: string): void => {
+		result.status = "unknown";
+		result.diagnostics.push(message);
+	};
+	const entries = (dir: string): string[] => {
+		try {
+			if (lstatSync(dir).isSymbolicLink()) {
+				unknown(`Symbolic-link root was not traversed: ${dir}`);
+				return [];
+			}
+			return readdirSync(dir).sort();
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") unknown(`Cannot inspect ${dir}`);
+			return [];
+		}
+	};
+	const json = (file: string): Record<string, unknown> | undefined => {
+		try {
+			const value: unknown = JSON.parse(inventoryText(file));
+			if (!object(value)) throw new Error("not object");
+			return value;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") unknown(`Cannot parse ${file}`);
+			return undefined;
+		}
+	};
+	const add = (
+		file: string,
+		resourceKind: InteropResourceKind,
+		scope: "user" | "project",
+		plugin?: string,
+		metadata: Partial<InteropInventoryItem> = {},
+	): void => {
+		const key = `${scope}:${resourceKind}:${file}:${metadata.name ?? ""}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		let declaredName: string | undefined;
+		if (["skill", "agent", "prompt"].includes(resourceKind)) {
+			try {
+				const raw = inventoryText(file);
+				const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+				const data: unknown = file.endsWith(".toml")
+					? parseToml(raw)
+					: frontmatter
+						? parseYaml(frontmatter[1] ?? "")
+						: undefined;
+				if (object(data) && typeof data.name === "string") declaredName = data.name;
+			} catch {
+				unknown(`Resource metadata is unknown: ${file}`);
+			}
+		}
+		result.items.push({
+			kind: resourceKind,
+			name:
+				declaredName ??
+				(resourceKind === "skill" ? path.basename(path.dirname(file)) : path.basename(file, path.extname(file))),
+			path: file,
+			scope,
+			...(plugin ? { plugin } : {}),
+			...metadata,
+		});
+	};
+	const walk = (dir: string, visit: (file: string) => void, depth = 0): void => {
+		if (depth > 12) {
+			unknown(`Depth limit reached: ${dir}`);
+			return;
+		}
+		for (const name of entries(dir)) {
+			if (++visited > MAX_FILES) {
+				unknown("Inventory file limit reached.");
+				return;
+			}
+			const file = path.join(dir, name);
+			try {
+				const stat = lstatSync(file);
+				if (stat.isSymbolicLink()) {
+					unknown(`Symbolic link was not traversed: ${file}`);
+					continue;
+				}
+				if (stat.isDirectory()) walk(file, visit, depth + 1);
+				else if (stat.isFile()) visit(file);
+			} catch {
+				unknown(`Cannot inspect ${file}`);
+			}
+		}
+	};
+	const scan = (
+		root: string,
+		scope: "user" | "project",
+		plugin?: string,
+		declarations = layout.declarations,
+		resourceRoots = layout.roots,
+	): void => {
+		for (const entry of resourceRoots) {
+			walk(path.join(root, entry.path), (file) => {
+				if (
+					entry.kind === "skill" ? path.basename(file) === "SKILL.md" : entry.extensions.some((ext) => file.endsWith(ext))
+				)
+					add(file, entry.kind, scope, plugin);
+			});
+		}
+		for (const entry of declarations) {
+			const file = path.join(root, entry.path);
+			if (entry.path.endsWith(".toml")) {
+				try {
+					const data = parseToml(inventoryText(file));
+					if (object(data.mcp_servers))
+						for (const name of Object.keys(data.mcp_servers)) add(file, "mcp", scope, plugin, { name });
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") unknown(`Cannot read ${file}`);
+				}
+			} else {
+				const data = json(file);
+				if (!data) continue;
+				const value = entry.key ? data[entry.key] : data;
+				if (value === undefined) continue;
+				if (object(value))
+					for (const name of Object.keys(value)) {
+						// Configuration values can carry credentials; inventory stores names only.
+						const key = `${scope}:${entry.kind}:${file}:${name}`;
+						if (!seen.has(key)) {
+							seen.add(key);
+							result.items.push({ kind: entry.kind, name, path: file, scope, ...(plugin ? { plugin } : {}) });
+						}
+					}
+				else unknown(`Unsupported declaration shape in ${file}`);
+			}
+		}
+	};
+
+	scan(home, "user", undefined, layout.userDeclarations ?? [], []);
+	scan(cwd, "project", undefined, layout.projectDeclarations ?? [], []);
+	if (layout.projectModuleConfig) {
+		const file = path.join(cwd, layout.projectModuleConfig);
+		const data = json(file);
+		if (Array.isArray(data?.plugin))
+			for (const value of data.plugin) {
+				const name =
+					typeof value === "string" ? value : Array.isArray(value) && typeof value[0] === "string" ? value[0] : undefined;
+				if (name)
+					add(file, "executable", "project", undefined, {
+						name: name.startsWith("file:") || path.isAbsolute(name) ? path.basename(name) : name,
+					});
+				else unknown("Unsupported project executable plugin declaration.");
+			}
+	}
+	const userRoot =
+		env[layout.homeEnv ?? ""] ??
+		(layout.xdgConfigSubdir && env.XDG_CONFIG_HOME
+			? path.join(env.XDG_CONFIG_HOME, layout.xdgConfigSubdir)
+			: path.join(home, layout.userRoot));
+	const roots: Array<{ root: string; scope: "user" | "project" }> = [
+		{ root: userRoot, scope: "user" },
+		...(layout.additionalUserRoots ?? []).map((root) => ({ root: path.join(home, root), scope: "user" as const })),
+		...layout.projectRoots.map((root) => ({ root: path.join(cwd, root), scope: "project" as const })),
+	];
+	const pluginRoots = new Set<string>();
+	const plugin = (root: string, scope: "user" | "project", metadata: Partial<InteropInventoryItem> = {}): void => {
+		if (pluginRoots.has(`${scope}:${root}`)) return;
+		pluginRoots.add(`${scope}:${root}`);
+		let manifest: Record<string, unknown> | undefined;
+		for (const manifestPath of layout.pluginManifests) {
+			manifest = json(path.join(root, manifestPath));
+			if (manifest) break;
+		}
+		add(root, "plugin", scope, undefined, {
+			name: typeof manifest?.name === "string" ? manifest.name : path.basename(root),
+			version: typeof manifest?.version === "string" ? manifest.version : "unknown",
+			marketplace: "unknown",
+			installation: "unknown",
+			...metadata,
+		});
+		scan(root, scope, root);
+		for (const directory of ["scripts", "tools"])
+			walk(path.join(root, directory), (file) => add(file, "executable", scope, root));
+	};
+	for (const { root, scope } of roots) {
+		scan(root, scope);
+		if (layout.moduleConfig) {
+			const data = json(path.join(root, layout.moduleConfig));
+			if (Array.isArray(data?.plugin))
+				for (const name of data.plugin) {
+					const source =
+						typeof name === "string" ? name : Array.isArray(name) && typeof name[0] === "string" ? name[0] : undefined;
+					if (source)
+						add(path.join(root, layout.moduleConfig), "executable", scope, undefined, {
+							name: path.isAbsolute(source)
+								? path.basename(source)
+								: source.startsWith("file:")
+									? path.basename(source)
+									: source,
+						});
+					else unknown("Unsupported executable plugin declaration.");
+				}
+		}
+		if (layout.settingsRegistry === "copilot") {
+			const settings = json(path.join(root, "settings.json"));
+			if (object(settings?.enabledPlugins))
+				for (const [id, enabled] of Object.entries(settings.enabledPlugins)) {
+					const [name, market] = id.split("@");
+					const markets = settings.extraKnownMarketplaces;
+					const entry = object(markets) && market ? markets[market] : undefined;
+					const source = object(entry) ? entry.source : undefined;
+					if (!name || !object(source) || source.source !== "directory" || typeof source.path !== "string") {
+						unknown(`Plugin source path is unknown: ${id}`);
+						add(path.join(root, "settings.json"), "plugin", scope, undefined, {
+							name: id,
+							installation: "installed",
+							marketplace: market ?? "unknown",
+							version: "unknown",
+						});
+						continue;
+					}
+					const marketManifest =
+						json(path.join(source.path, ".claude-plugin/marketplace.json")) ??
+						json(path.join(source.path, "marketplace.json"));
+					const declaration = Array.isArray(marketManifest?.plugins)
+						? marketManifest.plugins.find((entry) => object(entry) && entry.name === name)
+						: undefined;
+					if (!object(declaration) || typeof declaration.source !== "string" || !declaration.source.startsWith(".")) {
+						unknown(`Plugin local source is unknown: ${id}`);
+						continue;
+					}
+					plugin(path.resolve(source.path, declaration.source), scope, {
+						name,
+						marketplace: market ?? "unknown",
+						installation: "installed",
+						...(typeof enabled === "boolean" ? { enabled } : {}),
+					});
+				}
+		}
+
+		if (layout.installedRegistry) {
+			const data = json(path.join(root, layout.installedRegistry));
+			if (object(data?.plugins)) {
+				for (const [id, records] of Object.entries(data.plugins)) {
+					if (!Array.isArray(records)) {
+						unknown("Unsupported installed plugin registry record.");
+						continue;
+					}
+					for (const record of records) {
+						if (!object(record) || typeof record.installPath !== "string") {
+							unknown("Plugin install path is unknown.");
+							continue;
+						}
+						if (record.scope !== "user" && record.scope !== "project" && record.scope !== "local") {
+							unknown("Plugin scope is unknown.");
+							continue;
+						}
+						if (record.scope !== "user" && record.projectPath !== cwd) continue;
+						plugin(record.installPath, record.scope === "user" ? "user" : "project", {
+							name: id.split("@")[0] ?? id,
+							marketplace: id.split("@")[1] ?? "unknown",
+							version: typeof record.version === "string" ? record.version : "unknown",
+							installation: "installed",
+						});
+					}
+				}
+			}
+		}
+		for (const directory of layout.pluginDirs) {
+			// Disk caches establish available content, not activation or installation status.
+			const search = (dir: string, depth: number): void => {
+				if (depth > 4) {
+					unknown(`Plugin search depth reached: ${dir}`);
+					return;
+				}
+				const names = entries(dir);
+				if (
+					layout.pluginManifests.some((name) => {
+						try {
+							return lstatSync(path.join(dir, name)).isFile();
+						} catch {
+							return false;
+						}
+					})
+				) {
+					const relative = path.relative(path.join(root, directory), dir).split(path.sep);
+					plugin(dir, scope, layout.cacheMarketplace ? { marketplace: relative[0] ?? "unknown" } : {});
+					return;
+				}
+				for (const name of names) {
+					if (++visited > MAX_FILES) {
+						unknown("Inventory file limit reached.");
+						return;
+					}
+					try {
+						if (lstatSync(path.join(dir, name)).isDirectory()) search(path.join(dir, name), depth + 1);
+					} catch {
+						unknown(`Cannot inspect ${dir}`);
+					}
+				}
+			};
+			search(path.join(root, directory), 0);
+		}
+	}
+	if (layout.settingsRegistry === "codex") {
+		try {
+			const data = parseToml(inventoryText(path.join(userRoot, "config.toml")));
+			if (object(data.plugins))
+				for (const item of result.items.filter((item) => item.kind === "plugin" && item.scope === "user")) {
+					const state = data.plugins[`${item.name}@${item.marketplace}`];
+					if (object(state) && typeof state.enabled === "boolean") {
+						item.enabled = state.enabled;
+						item.installation = "installed";
+					}
+				}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") unknown("Cannot parse Codex plugin settings.");
+		}
+	}
+	if (layout.settingsRegistry === "antigravity") {
+		const manifest = json(path.join(userRoot, "import_manifest.json"));
+		if (Array.isArray(manifest?.imports))
+			for (const item of result.items.filter((item) => item.kind === "plugin")) {
+				if (manifest.imports.some((entry) => object(entry) && entry.name === item.name)) item.installation = "installed";
+			}
+	}
+
+	return result;
+}