@iowarp/clio-coder 0.4.6 → 0.4.7

package/src/domains/plugins/catalog.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { buildSafeToolEnv } from "../../core/safe-exec.js";
+import { isSemanticVersion } from "../extensions/compatibility.js";
+import {
+	isLibraryKind,
+	isLibraryResourceKind,
+	LIBRARY_PROVIDES_LIMITS,
+	type LibraryPackageEntry,
+	type LibraryProvidedResource,
+	type LibraryRequirementRef,
+} from "../resources/library-types.js";
+import { isPluginId } from "./discovery.js";
+
+export type PluginCatalogEntry = LibraryPackageEntry;
+
+export interface PluginSource {
+	root: string;
+	cleanup: () => void;
+}
+
+/** Explicit GitHub tree URLs identify both the revision and the bundle directory. */
+export function parsePluginGithubSource(source: string): { url: string; ref: string; subdir: string } | undefined {
+	const match =
+		/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/tree\/([A-Za-z0-9_.-]+)(?:\/(.*?))?\/?$/.exec(source);
+	if (!match?.[1] || !match[2] || !match[3]) return undefined;
+	const subdir = match[4] ?? "";
+	if (subdir.split("/").some((part) => part === ".." || part === ".") || subdir.includes("\\") || subdir.includes("\0"))
+		return undefined;
+	return { url: `https://github.com/${match[1]}/${match[2]}.git`, ref: match[3], subdir };
+}
+
+export function pluginLocalPath(source: string, cwd = process.cwd()): string {
+	return path.resolve(cwd, source.startsWith("~/") ? path.join(homedir(), source.slice(2)) : source);
+}
+
+/** The same bounded, vector-only Git transport used by the skill installer. */
+export function fetchPluginSource(source: string, cwd = process.cwd()): PluginSource {
+	const local = pluginLocalPath(source, cwd);
+	if (existsSync(local)) return { root: local, cleanup: () => {} };
+	const remote = parsePluginGithubSource(source);
+	if (!remote)
+		throw new Error(
+			`unsupported plugin source: ${source}; use a local directory or https://github.com/owner/repo/tree/ref/path`,
+		);
+	const temp = mkdtempSync(path.join(tmpdir(), "clio-coder-plugin-"));
+	const cleanup = (): void => rmSync(temp, { recursive: true, force: true });
+	try {
+		execFileSync(
+			"git",
+			["-c", "core.hooksPath=/dev/null", "clone", "--depth", "1", "--branch", remote.ref, "--", remote.url, temp],
+			{
+				stdio: "pipe",
+				timeout: 120_000,
+				maxBuffer: 1_000_000,
+				env: buildSafeToolEnv({ GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" }),
+			},
+		);
+		const root = path.join(temp, remote.subdir);
+		if (!existsSync(root) || !statSync(root).isDirectory())
+			throw new Error(`plugin source has no directory ${remote.subdir || "."}: ${source}`);
+		const relative = path.relative(realpathSync(temp), realpathSync(root));
+		if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+			throw new Error("plugin source escapes repository");
+		// Repository metadata is transport state, not part of a root-level package.
+		if (!remote.subdir) rmSync(path.join(temp, ".git"), { recursive: true, force: true });
+		return { root, cleanup };
+	} catch (error) {
+		cleanup();
+		throw error;
+	}
+}
+
+const PROVIDED_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/**
+ * Parse optional `provides` hints. A malformed hint list is dropped with a
+ * diagnostic and the row stays valid: hints support discovery, never admission,
+ * so a bad hint must not hide an otherwise installable package.
+ */
+function providedResources(value: unknown, name: string, diagnostics: string[]): LibraryProvidedResource[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.length > LIBRARY_PROVIDES_LIMITS.entries) {
+		diagnostics.push(`library index provides ignored (not a bounded list): ${name}`);
+		return undefined;
+	}
+	const hints: LibraryProvidedResource[] = [];
+	const seen = new Set<string>();
+	for (const raw of value) {
+		const item = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : undefined;
+		if (
+			!item ||
+			!isLibraryResourceKind(item.kind) ||
+			typeof item.name !== "string" ||
+			item.name.length > LIBRARY_PROVIDES_LIMITS.name ||
+			!PROVIDED_NAME.test(item.name) ||
+			(item.description !== undefined &&
+				(typeof item.description !== "string" || item.description.length > LIBRARY_PROVIDES_LIMITS.description))
+		) {
+			diagnostics.push(`library index provides ignored (malformed hint): ${name}`);
+			return undefined;
+		}
+		const key = `${item.kind}:${item.name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		hints.push({
+			kind: item.kind,
+			name: item.name,
+			...(typeof item.description === "string" ? { description: item.description } : {}),
+		});
+	}
+	return hints;
+}
+
+export function readPluginCatalog(file: string, diagnostics: string[]): LibraryPackageEntry[] {
+	if (!existsSync(file)) return [];
+	try {
+		const parsed: unknown = parseYaml(readFileSync(file, "utf8"));
+		const rows: unknown[] | undefined = Array.isArray(parsed)
+			? parsed
+			: parsed && typeof parsed === "object" && Array.isArray((parsed as { entries?: unknown }).entries)
+				? (parsed as { entries: unknown[] }).entries
+				: undefined;
+		if (!rows) throw new Error("library index must be a list or contain an entries list");
+		return rows.flatMap((row): LibraryPackageEntry[] => {
+			if (!row || typeof row !== "object") {
+				diagnostics.push(`library index entry malformed: ${file}`);
+				return [];
+			}
+			const item = row as Record<string, unknown>;
+			if (
+				!isLibraryKind(item.kind) ||
+				typeof item.name !== "string" ||
+				!isPluginId(item.name) ||
+				typeof item.description !== "string" ||
+				typeof item.sourceUrl !== "string" ||
+				item.sourceUrl.trim().length === 0 ||
+				!isSemanticVersion(item.version) ||
+				typeof item.sha256 !== "string" ||
+				!/^[a-f0-9]{64}$/.test(item.sha256)
+			) {
+				diagnostics.push(
+					`library index entry requires name, description, sourceUrl, version, and full-tree sha256: ${String(item.name ?? file)}`,
+				);
+				return [];
+			}
+			if (
+				item.requires !== undefined &&
+				(!Array.isArray(item.requires) || item.requires.some((ref) => typeof ref !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${item.name}`);
+				return [];
+			}
+			const remote = /^(?:[a-z][a-z0-9+.-]*:\/\/|git@)/i.test(item.sourceUrl);
+			if (remote && !parsePluginGithubSource(item.sourceUrl)) {
+				diagnostics.push(`unsupported library index source: ${item.sourceUrl}`);
+				return [];
+			}
+			const provides = providedResources(item.provides, item.name, diagnostics);
+			return [
+				{
+					kind: item.kind,
+					name: item.name,
+					description: item.description,
+					sourceUrl: remote ? item.sourceUrl : path.resolve(path.dirname(file), item.sourceUrl),
+					version: item.version,
+					sha256: item.sha256,
+					origin: "catalog",
+					...(typeof item.category === "string" ? { category: item.category } : {}),
+					...(["pass", "warn", "fail", "unknown"].includes(String(item.audit))
+						? { audit: item.audit as NonNullable<LibraryPackageEntry["audit"]> }
+						: {}),
+					...(Array.isArray(item.triggers)
+						? { triggers: item.triggers.filter((value): value is string => typeof value === "string") }
+						: {}),
+					...(Array.isArray(item.requires) ? { requires: item.requires as LibraryRequirementRef[] } : {}),
+					...(provides ? { provides } : {}),
+					index: path.resolve(file),
+				},
+			];
+		});
+	} catch (error) {
+		diagnostics.push(`library index unreadable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}
+
+/** The index shipped inside this Clio-Coder package; rows from it are the only "bundled" evidence. */
+export function bundledLibraryIndexPath(): string {
+	return path.join(resolvePackageRoot(), "library", "registry.yaml");
+}
+
+export function bundledPluginCatalog(diagnostics: string[]): LibraryPackageEntry[] {
+	try {
+		return readPluginCatalog(bundledLibraryIndexPath(), diagnostics);
+	} catch (error) {
+		diagnostics.push(`library index unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}

package/src/domains/plugins/contract.ts

@@ -0,0 +1,24 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type {
+	InstalledPlugin,
+	PluginCandidate,
+	PluginInstallOptions,
+	PluginListOptions,
+	PluginMutationResult,
+	PluginResourceKind,
+	PluginResourceRoot,
+	PluginSnapshot,
+} from "./types.js";
+
+export interface PluginsContract extends DomainContract {
+	list(cwd?: string, options?: PluginListOptions): InstalledPlugin[];
+	discover(root: string): PluginCandidate[];
+	install(source: string, options?: PluginInstallOptions): PluginMutationResult;
+	update(id: string, options?: PluginInstallOptions): PluginMutationResult;
+	enable(id: string, options?: PluginListOptions): PluginMutationResult;
+	disable(id: string, options?: PluginListOptions): PluginMutationResult;
+	remove(id: string, options?: PluginListOptions): PluginMutationResult;
+	resourceRoots(kind: PluginResourceKind, cwd?: string): PluginResourceRoot[];
+	snapshot(cwd?: string): PluginSnapshot;
+	reload(cwd?: string): PluginSnapshot;
+}

package/src/domains/plugins/discovery.ts

@@ -0,0 +1,316 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { evaluateClioCompatibility, isSemanticVersion } from "../extensions/compatibility.js";
+import { isLibraryKind, type LibraryRequirementRef } from "../resources/library-types.js";
+import { pluginContentDigestWithCapture } from "./integrity.js";
+import type {
+	ClioPluginConfiguration,
+	PluginCandidate,
+	PluginComponent,
+	PluginComponentKind,
+	PluginDiagnostic,
+	PluginManifest,
+	PluginResourceKind,
+	PluginResources,
+} from "./types.js";
+
+export const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export const PLUGIN_EXTENSION_KEY = "ai.iowarp.clio";
+export const PLUGIN_RESOURCE_KINDS: readonly PluginResourceKind[] = ["skills", "prompts", "agents", "fleets", "themes"];
+const COMPONENT_KINDS = new Set(["prompt", "agent", "skill", "fleet", "script", "resource", "tool"]);
+const ROOT_KEYS = new Set([
+	"$schema",
+	"name",
+	"version",
+	"description",
+	"author",
+	"homepage",
+	"repository",
+	"license",
+	"keywords",
+	"extensions",
+]);
+
+export function isPluginId(value: string): boolean {
+	return (
+		value.length <= 64 && /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/u.test(value) && value !== "state.json"
+	);
+}
+
+export function pluginPathContained(root: string, target: string): boolean {
+	const relative = path.relative(root, target);
+	return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+/** Resolve a declared file or directory against the canonical installed root. */
+export function pluginResourcePath(root: string, value: string, allowRoot = false): string {
+	if (!value || value.includes("\\") || path.isAbsolute(value))
+		throw new Error(`plugin path must be relative: ${value}`);
+	const lexicalRoot = path.resolve(root);
+	const lexical = path.resolve(lexicalRoot, value);
+	if ((!allowRoot && lexical === lexicalRoot) || !pluginPathContained(lexicalRoot, lexical))
+		throw new Error(`plugin path escapes root: ${value}`);
+	const canonicalRoot = realpathSync(lexicalRoot);
+	const canonical = realpathSync(lexical);
+	if (!pluginPathContained(canonicalRoot, canonical) || (!allowRoot && canonical === canonicalRoot))
+		throw new Error(`plugin path escapes through a symbolic link: ${value}`);
+	return canonical;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, label: string): void {
+	for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown ${label} key '${key}'`);
+}
+
+function components(value: unknown, root: string): PluginComponent[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 1024)
+		throw new Error("components must be an array of at most 1024 entries");
+	const refs = new Map<string, PluginComponent>();
+	for (const raw of value) {
+		if (!record(raw)) throw new Error("component must be an object");
+		requireKeys(raw, new Set(["kind", "id", "path", "requires"]), "component");
+		if (typeof raw.kind !== "string" || !COMPONENT_KINDS.has(raw.kind)) throw new Error("unsupported component kind");
+		if (typeof raw.id !== "string" || raw.id.length > 80 || !/^[a-z0-9][a-z0-9._-]*$/u.test(raw.id))
+			throw new Error("component id must be a stable lowercase identifier");
+		if (typeof raw.path !== "string") throw new Error(`component ${raw.id} must have a relative path`);
+		const file = pluginResourcePath(root, raw.path);
+		if (!statSync(file).isFile()) throw new Error(`component ${raw.id} path must be a file`);
+		if (raw.kind === "skill" && path.basename(file) !== "SKILL.md")
+			throw new Error(`skill component ${raw.id} must point to SKILL.md`);
+		if (
+			raw.requires !== undefined &&
+			(!Array.isArray(raw.requires) || raw.requires.some((ref) => typeof ref !== "string"))
+		)
+			throw new Error(`component ${raw.id} requires must be an array of component references`);
+		const item: PluginComponent = {
+			kind: raw.kind as PluginComponentKind,
+			id: raw.id,
+			path: raw.path,
+			...(raw.requires !== undefined ? { requires: raw.requires as string[] } : {}),
+		};
+		const ref = `${item.kind}:${item.id}`;
+		if (refs.has(ref)) throw new Error(`duplicate component reference: ${ref}`);
+		refs.set(ref, item);
+	}
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const visit = (ref: string): void => {
+		if (visiting.has(ref)) throw new Error(`component dependency cycle at ${ref}`);
+		if (visited.has(ref)) return;
+		const item = refs.get(ref);
+		if (!item) throw new Error(`missing component reference: ${ref}`);
+		visiting.add(ref);
+		for (const dependency of item.requires ?? []) visit(dependency);
+		visiting.delete(ref);
+		visited.add(ref);
+	};
+	for (const ref of refs.keys()) visit(ref);
+	return [...refs.values()];
+}
+
+function clioConfiguration(value: unknown, root: string): ClioPluginConfiguration {
+	if (value !== undefined && !record(value)) throw new Error(`${PLUGIN_EXTENSION_KEY} must be an object`);
+	const raw = value ?? {};
+	requireKeys(
+		raw,
+		new Set(["manifestVersion", "kind", "requires", "evals", "compatibility", "resources", "components"]),
+		PLUGIN_EXTENSION_KEY,
+	);
+	if (value !== undefined && raw.manifestVersion !== 1) throw new Error("Clio plugin manifestVersion must be 1");
+	const kind = raw.kind ?? "plugin";
+	if (!isLibraryKind(kind)) throw new Error("package kind must be plugin, skill, agent, prompt, or fleet");
+	if (
+		raw.requires !== undefined &&
+		(!Array.isArray(raw.requires) ||
+			raw.requires.some(
+				(ref) => typeof ref !== "string" || !/^(plugin|skill|agent|prompt|fleet):[a-z0-9][a-z0-9.-]*$/.test(ref),
+			))
+	)
+		throw new Error("package requires must contain kind:name references");
+	const evals: Record<string, string> = {};
+	if (raw.evals !== undefined) {
+		if (!record(raw.evals)) throw new Error("package evals must map names to Suite v2 files");
+		for (const [id, file] of Object.entries(raw.evals)) {
+			if (!isPluginId(id) || typeof file !== "string" || !statSync(pluginResourcePath(root, file)).isFile())
+				throw new Error(`invalid package eval: ${id}`);
+			evals[id] = file;
+		}
+	}
+	let compatibility: ClioPluginConfiguration["compatibility"];
+	if (raw.compatibility !== undefined) {
+		if (!record(raw.compatibility)) throw new Error("compatibility must be an object");
+		requireKeys(raw.compatibility, new Set(["clio"]), "compatibility");
+		if (
+			raw.compatibility.clio !== undefined &&
+			(typeof raw.compatibility.clio !== "string" || !evaluateClioCompatibility(raw.compatibility.clio).rangeValid)
+		)
+			throw new Error("compatibility.clio must be a valid SemVer range");
+		compatibility = raw.compatibility as { clio?: string };
+	}
+	const resources: PluginResources = {};
+	if (existsSync(path.join(root, "skills"))) resources.skills = "skills";
+	if (raw.resources !== undefined) {
+		if (!record(raw.resources)) throw new Error("resources must be an object");
+		requireKeys(raw.resources, new Set(PLUGIN_RESOURCE_KINDS), "resources");
+		for (const kind of PLUGIN_RESOURCE_KINDS) {
+			const resource = raw.resources[kind];
+			if (resource === undefined) continue;
+			if (typeof resource !== "string") throw new Error(`resources.${kind} must be a relative directory`);
+			resources[kind] = resource;
+		}
+	}
+	for (const [resourceKind, relative] of Object.entries(resources)) {
+		const full = pluginResourcePath(root, relative, kind === "skill" && relative === ".");
+		if (!statSync(full).isDirectory()) throw new Error(`resources.${resourceKind} must be a directory`);
+		if (
+			resourceKind === "skills" &&
+			relative !== "." &&
+			path.resolve(root, relative) !== path.join(path.resolve(root), "skills")
+		)
+			throw new Error("portable skills must use the root skills directory");
+	}
+	const inventory = components(raw.components, root);
+	const componentRoots: Partial<Record<PluginComponentKind, PluginResourceKind>> = {
+		prompt: "prompts",
+		agent: "agents",
+		skill: "skills",
+		fleet: "fleets",
+	};
+	for (const item of inventory) {
+		const resourceKind = componentRoots[item.kind];
+		if (!resourceKind) continue;
+		const resource = resources[resourceKind];
+		if (
+			!resource ||
+			!pluginPathContained(
+				pluginResourcePath(root, resource, kind === "skill" && resource === "."),
+				pluginResourcePath(root, item.path),
+			)
+		)
+			throw new Error(`component ${item.kind}:${item.id} is outside its declared resource root`);
+	}
+	if (kind !== "plugin") {
+		const publicItems = inventory.filter((item) => ["prompt", "agent", "skill", "fleet"].includes(item.kind));
+		if (publicItems.length !== 1 || publicItems[0]?.kind !== kind)
+			throw new Error(`a ${kind} package must declare exactly one public ${kind} component`);
+		if (Object.keys(resources).some((resource) => resource !== `${kind}s`))
+			throw new Error(`a ${kind} package may only declare its ${kind}s resource root`);
+		const resource = resources[`${kind}s` as PluginResourceKind];
+		if (!resource) throw new Error(`a ${kind} package must declare its resource root`);
+		const discovered: string[] = [];
+		const scan = (directory: string, ancestors: Set<string>): void => {
+			const canonical = realpathSync(directory);
+			if (ancestors.has(canonical)) throw new Error("cyclic package resource directory");
+			const visited = new Set([...ancestors, canonical]);
+			for (const item of readdirSync(directory)) {
+				const file = path.join(directory, item);
+				if (statSync(file).isDirectory()) scan(file, visited);
+				else if (kind === "skill" ? item === "SKILL.md" : item.endsWith(".md")) discovered.push(file);
+			}
+		};
+		scan(pluginResourcePath(root, resource, kind === "skill" && resource === "."), new Set());
+		const declared = publicItems[0];
+		if (
+			discovered.length !== 1 ||
+			!declared ||
+			path.resolve(discovered[0] as string) !== pluginResourcePath(root, declared.path)
+		)
+			throw new Error(`a ${kind} package must expose only its declared ${kind} file`);
+	}
+	return {
+		manifestVersion: 1,
+		kind,
+		resources,
+		components: inventory,
+		...(raw.requires ? { requires: raw.requires as LibraryRequirementRef[] } : {}),
+		...(raw.evals ? { evals } : {}),
+		...(compatibility ? { compatibility } : {}),
+	};
+}
+
+export function parsePluginManifest(raw: string, root: string): PluginManifest {
+	const value: unknown = JSON.parse(raw);
+	if (!record(value)) throw new Error("plugin manifest must be an object");
+	requireKeys(value, ROOT_KEYS, "plugin manifest");
+	if (value.$schema !== PLUGIN_SCHEMA) throw new Error(`plugin $schema must be ${PLUGIN_SCHEMA}`);
+	if (typeof value.name !== "string" || !isPluginId(value.name))
+		throw new Error("plugin name must be a portable identifier of 1 to 64 characters and may not be state.json");
+	for (const field of ["version", "description", "homepage", "repository", "license"]) {
+		if (value[field] !== undefined && typeof value[field] !== "string") throw new Error(`${field} must be a string`);
+	}
+	if (!isSemanticVersion(value.version))
+		throw new Error("package version must be an explicit Semantic Version (for example 1.0.0)");
+	if (value.author !== undefined) {
+		if (!record(value.author)) throw new Error("author must be an object");
+		requireKeys(value.author, new Set(["name", "email", "url"]), "author");
+		if (Object.values(value.author).some((field) => typeof field !== "string"))
+			throw new Error("author fields must be strings");
+	}
+	if (
+		value.keywords !== undefined &&
+		(!Array.isArray(value.keywords) || value.keywords.some((field) => typeof field !== "string"))
+	)
+		throw new Error("keywords must be an array of strings");
+	if (
+		value.extensions !== undefined &&
+		(!record(value.extensions) || Object.values(value.extensions).some((field) => !record(field)))
+	)
+		throw new Error("extensions must contain namespaced objects");
+	const extensions = value.extensions as Record<string, Record<string, unknown>> | undefined;
+	const clio = clioConfiguration(extensions?.[PLUGIN_EXTENSION_KEY], root);
+	return { ...(value as unknown as Omit<PluginManifest, "clio">), clio };
+}
+
+/** Hash once, then parse the exact manifest bytes covered by that digest. */
+export function readPluginManifest(root: string): PluginCandidate {
+	const resolved = path.resolve(root);
+	const manifestPath = path.join(resolved, "plugin.json");
+	const diagnostics: PluginDiagnostic[] = [];
+	try {
+		if (existsSync(path.join(resolved, "state.json")))
+			throw new Error("root state.json is reserved for plugin installation state");
+		const digest = pluginContentDigestWithCapture(resolved, { capture: ["plugin.json"] });
+		const bytes = digest.captured.get("plugin.json");
+		if (!bytes) throw new Error("plugin.json must be a regular file at the plugin root");
+		const manifest = parsePluginManifest(bytes.toString("utf8"), resolved);
+		if (existsSync(path.join(resolved, "mcp.json")))
+			diagnostics.push({
+				type: "warning",
+				message: "MCP declarations are preserved; this Clio version does not execute MCP servers",
+				path: path.join(resolved, "mcp.json"),
+			});
+		return {
+			path: resolved,
+			manifestPath,
+			manifest,
+			valid: true,
+			diagnostics,
+			contentDigest: digest.digest,
+			manifestDigest: createHash("sha256").update(bytes).digest("hex"),
+		};
+	} catch (error) {
+		diagnostics.push({
+			type: "error",
+			message: error instanceof Error ? error.message : String(error),
+			path: manifestPath,
+		});
+		return { path: resolved, manifestPath, valid: false, diagnostics };
+	}
+}
+
+export function discoverPluginPackages(root: string): PluginCandidate[] {
+	if (existsSync(path.join(root, "plugin.json"))) return [readPluginManifest(root)];
+	try {
+		return readdirSync(root)
+			.sort()
+			.filter((name) => !name.startsWith(".") && lstatSync(path.join(root, name)).isDirectory())
+			.map((name) => readPluginManifest(path.join(root, name)));
+	} catch {
+		return [readPluginManifest(root)];
+	}
+}

package/src/domains/plugins/extension.ts

@@ -0,0 +1,40 @@
+import type { DomainBundle, DomainContext } from "../../core/domain-loader.js";
+import type { PluginsContract } from "./contract.js";
+import { discoverPluginPackages } from "./discovery.js";
+import {
+	clearPluginSnapshots,
+	enabledPluginResourceRoots,
+	pluginSnapshotFor,
+	reloadPluginResources,
+} from "./resources.js";
+import {
+	disablePlugin,
+	enablePlugin,
+	installPlugin,
+	listInstalledPlugins,
+	removePlugin,
+	updatePlugin,
+} from "./state.js";
+
+export function createPluginsBundle(_context: DomainContext): DomainBundle<PluginsContract> {
+	return {
+		extension: {
+			start() {},
+			stop() {
+				clearPluginSnapshots();
+			},
+		},
+		contract: {
+			list: listInstalledPlugins,
+			discover: discoverPluginPackages,
+			install: installPlugin,
+			update: updatePlugin,
+			enable: enablePlugin,
+			disable: disablePlugin,
+			remove: removePlugin,
+			resourceRoots: enabledPluginResourceRoots,
+			snapshot: pluginSnapshotFor,
+			reload: reloadPluginResources,
+		},
+	};
+}

package/src/domains/plugins/index.ts

@@ -0,0 +1,77 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import type { PluginsContract } from "./contract.js";
+import { createPluginsBundle } from "./extension.js";
+import { PluginsManifest } from "./manifest.js";
+
+export const PluginsDomainModule: DomainModule<PluginsContract> = {
+	manifest: PluginsManifest,
+	createExtension: createPluginsBundle,
+};
+export type { PluginsContract } from "./contract.js";
+export {
+	discoverPluginPackages,
+	isPluginId,
+	PLUGIN_EXTENSION_KEY,
+	PLUGIN_RESOURCE_KINDS,
+	PLUGIN_SCHEMA,
+	parsePluginManifest,
+	pluginPathContained,
+	pluginResourcePath,
+	readPluginManifest,
+} from "./discovery.js";
+export { pluginContentDigest, pluginContentDigestWithCapture } from "./integrity.js";
+export {
+	buildPluginSnapshot,
+	clearPluginSnapshots,
+	enabledPluginResourceRoots,
+	pluginSnapshotFor,
+	reloadPluginResources,
+} from "./resources.js";
+export {
+	disablePlugin,
+	enablePlugin,
+	installLibraryPackage,
+	installPlugin,
+	listInstalledPlugins,
+	newlyBrokenDependents,
+	observePluginCopy,
+	type PluginDependentBreak,
+	PluginWriterRefusal,
+	pluginBaseDir,
+	pluginStatePath,
+	readPluginInstallRecord,
+	removePlugin,
+	resolvePluginPrecedence,
+	updatePlugin,
+	withPluginScopeLock,
+} from "./state.js";
+export type {
+	ClioPluginConfiguration,
+	ForeignPackageFormat,
+	InstalledPlugin,
+	LibraryPackageInstallInput,
+	PackageTrust,
+	PluginCandidate,
+	PluginComponent,
+	PluginComponentKind,
+	PluginDiagnostic,
+	PluginDiagnosticCode,
+	PluginExpectedCopy,
+	PluginExpectedState,
+	PluginInstallOptions,
+	PluginInstallRecord,
+	PluginInstallResult,
+	PluginListOptions,
+	PluginManifest,
+	PluginMutationOptions,
+	PluginMutationResult,
+	PluginOrigin,
+	PluginProvenance,
+	PluginResourceKind,
+	PluginResourceRoot,
+	PluginResources,
+	PluginScope,
+	PluginSnapshot,
+	PluginState,
+} from "./types.js";
+export { isForeignPluginOrigin } from "./types.js";

package/src/domains/plugins/integrity.ts

@@ -0,0 +1,6 @@
+// Both package engines use the same exact-tree framing, so a digest computed
+// for one is directly comparable to a digest computed for the other.
+export {
+	extensionContentDigest as pluginContentDigest,
+	extensionContentDigestWithCapture as pluginContentDigestWithCapture,
+} from "../extensions/integrity.js";

package/src/domains/plugins/manifest.ts

@@ -0,0 +1,3 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const PluginsManifest: DomainManifest = { name: "plugins", dependsOn: ["config"] };