@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/extensions/compatibility.ts

@@ -0,0 +1,285 @@
+/**
+ * SemVer range evaluation for extension compatibility.
+ *
+ * Extension manifests are untrusted package input, so this parser is bounded
+ * and fail-closed. It accepts the ordinary npm range vocabulary authors use in
+ * manifests: comparator sets, `||`, exact and partial versions, wildcards,
+ * hyphen ranges, caret ranges, and tilde ranges. Tags and malformed or
+ * overlong expressions are rejected instead of being treated as compatible.
+ */
+
+import { getVersionInfo } from "../lifecycle/version.js";
+
+const MAX_RANGE_CHARS = 256;
+
+interface SemVer {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: ReadonlyArray<string | number>;
+}
+
+interface PartialVersion {
+	major: number | null;
+	minor: number | null;
+	patch: number | null;
+	prerelease: ReadonlyArray<string | number>;
+}
+
+type Predicate = (version: SemVer) => boolean;
+
+const NUMERIC = "(?:0|[1-9]\\d*)";
+const IDENTIFIER = "[0-9A-Za-z-]+";
+const VERSION_RE = new RegExp(
+	`^v?(${NUMERIC})\\.(${NUMERIC})\\.(${NUMERIC})(?:-(${IDENTIFIER}(?:\\.${IDENTIFIER})*))?(?:\\+${IDENTIFIER}(?:\\.${IDENTIFIER})*)?$`,
+);
+const PARTIAL_RE = new RegExp(
+	`^v?(${NUMERIC}|[xX*])(?:\\.(${NUMERIC}|[xX*]))?(?:\\.(${NUMERIC}|[xX*]))?(?:-(${IDENTIFIER}(?:\\.${IDENTIFIER})*))?(?:\\+${IDENTIFIER}(?:\\.${IDENTIFIER})*)?$`,
+);
+
+function prerelease(value: string | undefined): ReadonlyArray<string | number> | null {
+	if (value === undefined) return [];
+	const out: Array<string | number> = [];
+	for (const identifier of value.split(".")) {
+		if (identifier.length === 0) return null;
+		if (/^\d+$/u.test(identifier)) {
+			if (identifier.length > 1 && identifier.startsWith("0")) return null;
+			const parsed = Number(identifier);
+			if (!Number.isSafeInteger(parsed)) return null;
+			out.push(parsed);
+		} else {
+			out.push(identifier);
+		}
+	}
+	return out;
+}
+
+function parseSemVer(value: string): SemVer | null {
+	const match = VERSION_RE.exec(value);
+	if (match === null) return null;
+	const parsedPrerelease = prerelease(match[4]);
+	if (parsedPrerelease === null) return null;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (![major, minor, patch].every(Number.isSafeInteger)) return null;
+	return { major, minor, patch, prerelease: parsedPrerelease };
+}
+
+function parsePart(value: string | undefined): number | null {
+	if (value === undefined || value === "x" || value === "X" || value === "*") return null;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function parsePartial(value: string): PartialVersion | null {
+	const match = PARTIAL_RE.exec(value);
+	if (match === null) return null;
+	for (const part of match.slice(1, 4)) {
+		if (part === undefined || part === "x" || part === "X" || part === "*") continue;
+		if (!Number.isSafeInteger(Number(part))) return null;
+	}
+	const major = parsePart(match[1]);
+	const minor = parsePart(match[2]);
+	const patch = parsePart(match[3]);
+	// A wildcard closes the core. `1.x.3` is not a range with a coherent
+	// meaning, and accepting it differently from npm would be worse than a
+	// parse-time refusal.
+	if (
+		(major === null && (match[2] !== undefined || match[3] !== undefined)) ||
+		(minor === null && match[3] !== undefined)
+	) {
+		return null;
+	}
+	const parsedPrerelease = prerelease(match[4]);
+	if (parsedPrerelease === null) return null;
+	if (parsedPrerelease.length > 0 && (major === null || minor === null || patch === null)) return null;
+	return { major, minor, patch, prerelease: parsedPrerelease };
+}
+
+function compareIdentifiers(left: string | number, right: string | number): number {
+	if (left === right) return 0;
+	if (typeof left === "number" && typeof right === "number") return left < right ? -1 : 1;
+	if (typeof left === "number") return -1;
+	if (typeof right === "number") return 1;
+	return left < right ? -1 : 1;
+}
+
+function compare(left: SemVer, right: SemVer): number {
+	for (const key of ["major", "minor", "patch"] as const) {
+		if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
+	}
+	if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+		if (left.prerelease.length === right.prerelease.length) return 0;
+		return left.prerelease.length === 0 ? 1 : -1;
+	}
+	const length = Math.max(left.prerelease.length, right.prerelease.length);
+	for (let index = 0; index < length; index += 1) {
+		const leftPart = left.prerelease[index];
+		const rightPart = right.prerelease[index];
+		if (leftPart === undefined || rightPart === undefined) {
+			if (leftPart === rightPart) return 0;
+			return leftPart === undefined ? -1 : 1;
+		}
+		const order = compareIdentifiers(leftPart, rightPart);
+		if (order !== 0) return order;
+	}
+	return 0;
+}
+
+function floor(partial: PartialVersion): SemVer {
+	return {
+		major: partial.major ?? 0,
+		minor: partial.minor ?? 0,
+		patch: partial.patch ?? 0,
+		prerelease: partial.prerelease,
+	};
+}
+
+function nextWildcard(partial: PartialVersion): SemVer | null {
+	if (partial.major === null) return null;
+	if (partial.minor === null) return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+	if (partial.patch === null) return { major: partial.major, minor: partial.minor + 1, patch: 0, prerelease: [] };
+	return null;
+}
+
+function lowerBound(version: SemVer, inclusive: boolean): Predicate {
+	return (candidate) => (inclusive ? compare(candidate, version) >= 0 : compare(candidate, version) > 0);
+}
+
+function upperBound(version: SemVer, inclusive: boolean): Predicate {
+	return (candidate) => (inclusive ? compare(candidate, version) <= 0 : compare(candidate, version) < 0);
+}
+
+function core(version: SemVer): string {
+	return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+function predicatesForToken(token: string): { predicates: Predicate[]; prereleaseCore: string | null } | null {
+	const match = /^(<=|>=|<|>|=|~|\^)?(.+)$/u.exec(token);
+	if (match === null) return null;
+	const operator = match[1] ?? "";
+	const partial = parsePartial(match[2] ?? "");
+	if (partial === null) return null;
+	const base = floor(partial);
+	const wildcardUpper = nextWildcard(partial);
+	const prereleaseCore = partial.prerelease.length > 0 ? core(base) : null;
+
+	if (operator === "" || operator === "=") {
+		if (partial.major === null) return { predicates: [], prereleaseCore };
+		if (wildcardUpper !== null) {
+			return { predicates: [lowerBound(base, true), upperBound(wildcardUpper, false)], prereleaseCore };
+		}
+		return { predicates: [(candidate) => compare(candidate, base) === 0], prereleaseCore };
+	}
+	if (operator === ">=") return { predicates: [lowerBound(base, true)], prereleaseCore };
+	if (operator === "<") return { predicates: [upperBound(base, false)], prereleaseCore };
+	if (operator === ">") {
+		return {
+			predicates: [wildcardUpper === null ? lowerBound(base, false) : lowerBound(wildcardUpper, true)],
+			prereleaseCore,
+		};
+	}
+	if (operator === "<=") {
+		return {
+			predicates: [wildcardUpper === null ? upperBound(base, true) : upperBound(wildcardUpper, false)],
+			prereleaseCore,
+		};
+	}
+	if (partial.major === null) return { predicates: [], prereleaseCore };
+	if (operator === "~") {
+		const upper =
+			partial.minor === null
+				? { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] }
+				: { major: partial.major, minor: partial.minor + 1, patch: 0, prerelease: [] };
+		return { predicates: [lowerBound(base, true), upperBound(upper, false)], prereleaseCore };
+	}
+	const upper =
+		partial.major > 0
+			? { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] }
+			: partial.minor === null
+				? { major: 1, minor: 0, patch: 0, prerelease: [] }
+				: (partial.minor ?? 0) > 0
+					? { major: 0, minor: (partial.minor ?? 0) + 1, patch: 0, prerelease: [] }
+					: partial.patch === null
+						? { major: 0, minor: 1, patch: 0, prerelease: [] }
+						: { major: 0, minor: 0, patch: (partial.patch ?? 0) + 1, prerelease: [] };
+	return { predicates: [lowerBound(base, true), upperBound(upper, false)], prereleaseCore };
+}
+
+function predicatesForSet(raw: string): { predicates: Predicate[]; prereleaseCores: ReadonlySet<string> } | null {
+	const hyphen = /^(\S+)\s+-\s+(\S+)$/u.exec(raw);
+	if (hyphen !== null) {
+		const left = parsePartial(hyphen[1] ?? "");
+		const right = parsePartial(hyphen[2] ?? "");
+		if (left === null || right === null || left.major === null || right.major === null) return null;
+		const rightUpper = nextWildcard(right);
+		return {
+			predicates: [
+				lowerBound(floor(left), true),
+				rightUpper === null ? upperBound(floor(right), true) : upperBound(rightUpper, false),
+			],
+			prereleaseCores: new Set(
+				[
+					left.prerelease.length > 0 ? core(floor(left)) : null,
+					right.prerelease.length > 0 ? core(floor(right)) : null,
+				].filter((entry): entry is string => entry !== null),
+			),
+		};
+	}
+	const normalized = raw.replace(/(<=|>=|<|>|=|~|\^)\s+/gu, "$1");
+	const tokens = normalized.split(/\s+/u).filter((entry) => entry.length > 0);
+	if (tokens.length === 0) return null;
+	const predicates: Predicate[] = [];
+	const prereleaseCores = new Set<string>();
+	for (const token of tokens) {
+		const parsed = predicatesForToken(token);
+		if (parsed === null) return null;
+		predicates.push(...parsed.predicates);
+		if (parsed.prereleaseCore !== null) prereleaseCores.add(parsed.prereleaseCore);
+	}
+	return { predicates, prereleaseCores };
+}
+
+function parseRange(
+	range: string,
+): ReadonlyArray<{ predicates: Predicate[]; prereleaseCores: ReadonlySet<string> }> | null {
+	const trimmed = range.trim();
+	if (trimmed.length === 0 || trimmed.length > MAX_RANGE_CHARS) return null;
+	const sets = trimmed.split("||");
+	if (sets.some((set) => set.trim().length === 0)) return null;
+	const parsed = sets.map((set) => predicatesForSet(set.trim()));
+	return parsed.every((set) => set !== null) ? (parsed as Array<NonNullable<(typeof parsed)[number]>>) : null;
+}
+
+export function isValidSemVerRange(range: string): boolean {
+	return parseRange(range) !== null;
+}
+
+export function satisfiesSemVerRange(version: string, range: string): boolean {
+	const candidate = parseSemVer(version);
+	const sets = parseRange(range);
+	if (candidate === null || sets === null) return false;
+	return sets.some((set) => {
+		if (candidate.prerelease.length > 0 && !set.prereleaseCores.has(core(candidate))) return false;
+		return set.predicates.every((predicate) => predicate(candidate));
+	});
+}
+
+export interface ClioCompatibilityEvaluation {
+	rangeValid: boolean;
+	satisfied: boolean;
+	runningVersion: string;
+}
+
+export function evaluateClioCompatibility(
+	range: string,
+	runningVersion = getVersionInfo().clio,
+): ClioCompatibilityEvaluation {
+	const rangeValid = isValidSemVerRange(range);
+	return {
+		rangeValid,
+		satisfied: rangeValid && satisfiesSemVerRange(runningVersion, range),
+		runningVersion,
+	};
+}

package/src/domains/extensions/discovery.ts

@@ -1,6 +1,7 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { evaluateClioCompatibility } from "./compatibility.js";
 import type {
 	ClioExtensionManifest,
 	ExtensionCandidate,
@@ -39,13 +40,99 @@ function normalizeResources(value: unknown): ExtensionManifestResources {
 	const out: ExtensionManifestResources = {};
 	const skills = trimString(value.skills);
 	const prompts = trimString(value.prompts);
+	const agents = trimString(value.agents);
+	const fleets = trimString(value.fleets);
 	const themes = trimString(value.themes);
 	if (skills) out.skills = skills;
 	if (prompts) out.prompts = prompts;
+	if (agents) out.agents = agents;
+	if (fleets) out.fleets = fleets;
 	if (themes) out.themes = themes;
 	return out;
 }
 
+function contained(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function validateResourceTree(
+	root: string,
+	resourcePath: string,
+	kind: string,
+	diagnostics: ExtensionDiagnostic[],
+): void {
+	if (path.isAbsolute(resourcePath)) {
+		diagnostics.push({ type: "error", message: `resources.${kind} must be relative`, path: resourcePath });
+		return;
+	}
+	const resolvedRoot = path.resolve(root);
+	const resolved = path.resolve(resolvedRoot, resourcePath);
+	if (!contained(resolvedRoot, resolved) || resolved === resolvedRoot) {
+		diagnostics.push({ type: "error", message: `resources.${kind} escapes the extension root`, path: resourcePath });
+		return;
+	}
+	let canonicalRoot: string;
+	let canonicalResource: string;
+	try {
+		canonicalRoot = realpathSync(resolvedRoot);
+		canonicalResource = realpathSync(resolved);
+		if (!lstatSync(resolved).isDirectory()) {
+			diagnostics.push({ type: "error", message: `resources.${kind} is not a directory`, path: resolved });
+			return;
+		}
+	} catch (error) {
+		diagnostics.push({
+			type: "error",
+			message: `resources.${kind} cannot be resolved: ${error instanceof Error ? error.message : String(error)}`,
+			path: resolved,
+		});
+		return;
+	}
+	if (!contained(canonicalRoot, canonicalResource)) {
+		diagnostics.push({ type: "error", message: `resources.${kind} escapes through a symbolic link`, path: resolved });
+		return;
+	}
+
+	const pending = [resolved];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		if (!directory) continue;
+		for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+			const candidate = path.join(directory, entry.name);
+			if (entry.isSymbolicLink()) {
+				try {
+					if (!contained(canonicalRoot, realpathSync(candidate))) {
+						diagnostics.push({
+							type: "error",
+							message: `resources.${kind} contains an escaping symbolic link`,
+							path: candidate,
+						});
+					}
+				} catch (error) {
+					diagnostics.push({
+						type: "error",
+						message: `resources.${kind} contains an unresolved symbolic link: ${error instanceof Error ? error.message : String(error)}`,
+						path: candidate,
+					});
+				}
+			} else if (entry.isDirectory()) {
+				pending.push(candidate);
+			}
+		}
+	}
+}
+
+function validateResourceRoots(
+	root: string,
+	resources: ExtensionManifestResources,
+	diagnostics: ExtensionDiagnostic[],
+): void {
+	for (const [kind, resourcePath] of Object.entries(resources)) {
+		if (resourcePath) validateResourceTree(root, resourcePath, kind, diagnostics);
+	}
+}
+
 function stringArray(value: unknown): string[] | undefined {
 	if (!Array.isArray(value)) return undefined;
 	const out = value.map((entry) => trimString(entry)).filter((entry): entry is string => entry !== undefined);
@@ -80,9 +167,32 @@ export function parseExtensionManifest(
 	const resources = normalizeResources(value.resources);
 	const tools = stringArray(value.tools);
 	const settings = stringArray(value.settings);
-	const compatibility = isRecord(value.compatibility)
-		? { ...(trimString(value.compatibility.clio) ? { clio: trimString(value.compatibility.clio) as string } : {}) }
-		: undefined;
+	let compatibility: ClioExtensionManifest["compatibility"];
+	if (value.compatibility !== undefined) {
+		if (!isRecord(value.compatibility)) {
+			diagnostics.push({ type: "error", message: "compatibility must be an object", path: manifestPath });
+		} else if ("clio" in value.compatibility) {
+			const range = trimString(value.compatibility.clio);
+			if (range === undefined) {
+				diagnostics.push({
+					type: "error",
+					message: "compatibility.clio must be a non-empty semver range",
+					path: manifestPath,
+				});
+			} else {
+				const evaluation = evaluateClioCompatibility(range);
+				if (!evaluation.rangeValid) {
+					diagnostics.push({
+						type: "error",
+						message: `extension ${id ?? "<unknown>"} declares malformed compatibility.clio range '${range}'`,
+						path: manifestPath,
+					});
+				} else {
+					compatibility = { clio: range };
+				}
+			}
+		}
+	}
 	if (!id || !name || !version || !description || diagnostics.some((diag) => diag.type === "error")) {
 		return { diagnostics };
 	}
@@ -97,6 +207,17 @@ export function parseExtensionManifest(
 	if (tools) manifest.tools = tools;
 	if (settings) manifest.settings = settings;
 	if (compatibility && Object.keys(compatibility).length > 0) manifest.compatibility = compatibility;
+	const clioRange = manifest.compatibility?.clio;
+	if (clioRange !== undefined) {
+		const evaluation = evaluateClioCompatibility(clioRange);
+		if (!evaluation.satisfied) {
+			diagnostics.push({
+				type: "error",
+				message: `extension ${manifest.id} requires Clio '${clioRange}', but running Clio version is '${evaluation.runningVersion}'`,
+				path: manifestPath,
+			});
+		}
+	}
 	return { manifest, diagnostics };
 }
 
@@ -123,6 +244,7 @@ export function loadManifestFromRoot(root: string): ExtensionCandidate {
 	}
 	try {
 		const parsed = parseExtensionManifest(readJsonOrYaml(manifestPath), manifestPath);
+		if (parsed.manifest) validateResourceRoots(root, parsed.manifest.resources, parsed.diagnostics);
 		return {
 			path: root,
 			manifestPath,

package/src/domains/extensions/resources.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { listInstalledExtensions } from "./state.js";
 import type { ExtensionResourceKind, ExtensionResourceRoot } from "./types.js";
@@ -7,8 +7,24 @@ export function extensionResourcePath(rootPath: string, resourcePath: string): s
 	const root = path.resolve(rootPath);
 	const full = path.resolve(root, resourcePath);
 	const relative = path.relative(root, full);
-	if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return full;
-	return null;
+	if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+		return null;
+	try {
+		const rootReal = realpathSync(root);
+		const fullReal = realpathSync(full);
+		const canonicalRelative = path.relative(rootReal, fullReal);
+		if (
+			canonicalRelative === ".." ||
+			canonicalRelative.startsWith(`..${path.sep}`) ||
+			path.isAbsolute(canonicalRelative)
+		) {
+			return null;
+		}
+		if (!lstatSync(full).isDirectory()) return null;
+		return full;
+	} catch {
+		return null;
+	}
 }
 
 export function enabledExtensionResourceRoots(
@@ -17,20 +33,16 @@ export function enabledExtensionResourceRoots(
 ): ExtensionResourceRoot[] {
 	const roots: ExtensionResourceRoot[] = [];
 	for (const entry of listInstalledExtensions(cwd)) {
-		if (!entry.enabled || !entry.effective) continue;
+		if (!entry.enabled || !entry.compatible || !entry.effective) continue;
 		const rel = entry.resources[kind];
 		if (!rel) continue;
 		const full = extensionResourcePath(entry.rootPath, rel);
 		if (!full) continue;
-		try {
-			if (!statSync(full).isDirectory()) continue;
-		} catch {
-			continue;
-		}
 		roots.push({
 			id: entry.id,
 			scope: entry.scope,
 			path: full,
+			rootPath: entry.rootPath,
 			source: `extension:${entry.scope}:${entry.id}`,
 		});
 	}

package/src/domains/extensions/state.ts

@@ -2,6 +2,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, r
 import path from "node:path";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import { clioConfigDir } from "../../core/xdg.js";
+import { evaluateClioCompatibility } from "./compatibility.js";
 import { isRecord, loadManifestFromRoot, trimString } from "./discovery.js";
 import type {
 	ExtensionInstallOptions,
@@ -63,6 +64,8 @@ function installedFromRoot(root: string, scope: ExtensionScope, state: Extension
 	const candidate = loadManifestFromRoot(root);
 	const manifest = candidate.manifest;
 	if (!manifest || !candidate.manifestPath) return null;
+	const clioRange = manifest.compatibility?.clio;
+	const compatible = clioRange === undefined || evaluateClioCompatibility(clioRange).satisfied;
 	return {
 		id: manifest.id,
 		name: manifest.name,
@@ -72,6 +75,7 @@ function installedFromRoot(root: string, scope: ExtensionScope, state: Extension
 		rootPath: root,
 		manifestPath: candidate.manifestPath,
 		enabled: !state.disabled.includes(manifest.id),
+		compatible,
 		effective: false,
 		resources: manifest.resources,
 		diagnostics: candidate.diagnostics,
@@ -102,13 +106,18 @@ export function listInstalledExtensions(cwd = process.cwd(), options: ExtensionL
 		byId.set(entry.id, list);
 	}
 	for (const group of byId.values()) {
-		const winner = [...group].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope)).at(-1);
+		const winner = group
+			.filter((entry) => entry.compatible)
+			.sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope))
+			.at(-1);
 		for (const entry of group) {
 			entry.effective = entry === winner;
-			if (!entry.effective && winner) entry.overriddenBy = winner.scope;
+			if (entry.compatible && !entry.effective && winner) entry.overriddenBy = winner.scope;
 		}
 	}
-	const all = options.all === true ? entries : entries.filter((entry) => entry.effective);
+	// Incompatible packages remain visible by default so the load refusal and
+	// its version diagnostic cannot disappear with the resources it suppresses.
+	const all = options.all === true ? entries : entries.filter((entry) => entry.effective || !entry.compatible);
 	return all.sort((a, b) => {
 		const id = a.id.localeCompare(b.id);
 		if (id !== 0) return id;
@@ -129,7 +138,7 @@ export function installExtension(sourcePath: string, options: ExtensionInstallOp
 	const cwd = options.cwd ?? process.cwd();
 	const source = path.resolve(sourcePath);
 	const candidate = loadManifestFromRoot(source);
-	if (!candidate.manifest) return { diagnostics: candidate.diagnostics };
+	if (!candidate.manifest || !candidate.valid) return { diagnostics: candidate.diagnostics };
 	const targetRoot = path.join(extensionBaseDir(scope, cwd), candidate.manifest.id);
 	if (existsSync(targetRoot)) {
 		if (!options.force) {
@@ -152,7 +161,11 @@ export function installExtension(sourcePath: string, options: ExtensionInstallOp
 		rmSync(backupRoot, { recursive: true, force: true });
 		cpSync(source, stagingRoot, {
 			recursive: true,
-			filter: (src) => path.basename(src) !== "state.json",
+			// `state.json` beside the installed extension directories belongs to
+			// Clio's extension manager. An extension may legitimately ship nested
+			// resources with the same basename (for example a project-state JSON
+			// template), so exclude only a bookkeeping file at the package root.
+			filter: (src) => path.relative(source, src) !== "state.json",
 		});
 		if (existsSync(targetRoot)) {
 			renameSync(targetRoot, backupRoot);

package/src/domains/extensions/types.ts

@@ -1,9 +1,11 @@
 export type ExtensionScope = "user" | "project";
-export type ExtensionResourceKind = "skills" | "prompts" | "themes";
+export type ExtensionResourceKind = "skills" | "prompts" | "agents" | "fleets" | "themes";
 
 export interface ExtensionManifestResources {
 	skills?: string;
 	prompts?: string;
+	agents?: string;
+	fleets?: string;
 	themes?: string;
 }
 
@@ -34,6 +36,8 @@ export interface InstalledExtension {
 	rootPath: string;
 	manifestPath: string;
 	enabled: boolean;
+	/** Whether this package admits the running Clio version. */
+	compatible: boolean;
 	effective: boolean;
 	resources: ExtensionManifestResources;
 	overriddenBy?: ExtensionScope;
@@ -52,6 +56,7 @@ export interface ExtensionResourceRoot {
 	id: string;
 	scope: ExtensionScope;
 	path: string;
+	rootPath: string;
 	source: string;
 }