bfi-cli 0.1.89 → 0.1.92

package/dist/_chunks/package-plugin.mjs

@@ -0,0 +1,595 @@
+import { PluginInstallRecords, PluginRegistryClient, inspectPluginArchive, materializePluginTree, normalizeRegistry, pluginArchiveLimits, pluginInstallKey, pluginSlotKey, selectPluginRoot, sha256, treeDigest } from "./registry-client.mjs";
+import { resolveConfig } from "./config.mjs";
+import { isPluginArchive, isPluginVersion, parsePluginArguments } from "../cli.mjs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join, resolve } from "node:path";
+import { lstat, mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+const adapters = Object.freeze({});
+const reasons = {
+	"claude-code": ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
+	codex: ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
+	zcode: ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"],
+	codebuddy: ["OFFICIAL_FIXTURE_UNVERIFIED", "HOST_BINARY_UNAVAILABLE"],
+	"qwen-code": ["HOST_BINARY_UNAVAILABLE", "NATIVE_ADAPTER_UNVERIFIED"]
+};
+function nativeAdapterFor(target) {
+	return adapters[target] ?? null;
+}
+function nativeSupportFor(target) {
+	return {
+		targetAgent: target,
+		status: "EXPORT_ONLY",
+		reasons: [...reasons[target]]
+	};
+}
+const nativeManifestFormats = {
+	"claude-code": ["CLAUDE"],
+	codex: [
+		"AGENT_PLUGINS_V1",
+		"CODEX",
+		"CLAUDE",
+		"CURSOR"
+	],
+	zcode: [
+		"ZCODE",
+		"CLAUDE",
+		"CODEX"
+	],
+	codebuddy: ["CODEBUDDY"],
+	"qwen-code": ["QWEN"]
+};
+const metadataFields = /* @__PURE__ */ new Set([
+	"$schema",
+	"name",
+	"version",
+	"description",
+	"author",
+	"homepage",
+	"repository",
+	"license",
+	"keywords",
+	"displayName",
+	"metadata",
+	"interface"
+]);
+const defaultComponents = /* @__PURE__ */ new Set([
+	"skills",
+	"commands",
+	"agents",
+	"hooks",
+	"output-styles",
+	"workflows",
+	"themes",
+	"monitors",
+	"bin"
+]);
+const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+function nativeRequirements(tree, target) {
+	const requirements = /* @__PURE__ */ new Set(["native-plugin"]);
+	const manifest = nativeManifestFormats[target].map((format) => tree.manifests.find((item) => item.root === "" && item.format === format)).find(Boolean);
+	if (!manifest || manifest.invalid || !manifest.name?.trim()) requirements.add("manifest:missing-or-invalid");
+	else requirements.add(`manifest:${manifest.format}`);
+	const files = new Map(tree.files.map((file) => [file.path, file]));
+	for (const file of tree.files) {
+		const root = file.path.split("/")[0];
+		if (defaultComponents.has(root)) requirements.add(`component:${root}`);
+		if (file.executable) requirements.add("executable-assets");
+	}
+	const configuration = (value, kind) => {
+		if (!object(value)) {
+			requirements.add(`configuration:${kind}:unknown`);
+			return;
+		}
+		if (kind === "hooks") {
+			const events = object(value.hooks) ? value.hooks : value;
+			for (const [event, groups] of Object.entries(events)) {
+				if (event === "description") continue;
+				requirements.add(`hook-event:${event}`);
+				if (!Array.isArray(groups)) {
+					requirements.add("hook-handler:unknown");
+					continue;
+				}
+				for (const group of groups) {
+					if (!object(group) || !Array.isArray(group.hooks)) {
+						requirements.add("hook-handler:unknown");
+						continue;
+					}
+					for (const handler of group.hooks) requirements.add(`hook-handler:${object(handler) && typeof handler.type === "string" ? handler.type : "unknown"}`);
+				}
+			}
+		} else {
+			const servers = object(value.mcpServers) ? value.mcpServers : value;
+			for (const server of Object.values(servers)) {
+				const transport = object(server) ? typeof server.type === "string" ? server.type : typeof server.command === "string" ? "stdio" : "unknown" : "unknown";
+				requirements.add(`mcp-transport:${transport}`);
+			}
+		}
+	};
+	const visited = /* @__PURE__ */ new Set();
+	const inspect = (value, kind) => {
+		if (Array.isArray(value)) {
+			value.forEach((item) => inspect(item, kind));
+			return;
+		}
+		if (typeof value !== "string") {
+			configuration(value, kind);
+			return;
+		}
+		const path = value.replace(/^\.\//u, "");
+		if (visited.has(`${kind}:${path}`)) return;
+		visited.add(`${kind}:${path}`);
+		const file = files.get(path);
+		if (!file) {
+			requirements.add(`configuration:${kind}:external-or-missing`);
+			return;
+		}
+		try {
+			configuration(JSON.parse(file.content.toString("utf8")), kind);
+		} catch {
+			requirements.add(`configuration:${kind}:invalid`);
+		}
+	};
+	for (const [path, component] of [
+		[".mcp.json", "mcp"],
+		[".lsp.json", "lsp"],
+		["settings.json", "settings"],
+		[".app.json", "apps"]
+	]) if (files.has(path)) requirements.add(`component:${component}`);
+	if (files.has(".mcp.json")) inspect(".mcp.json", "mcp");
+	if (files.has("hooks/hooks.json")) inspect("hooks/hooks.json", "hooks");
+	if (manifest && files.has(manifest.path)) try {
+		const data = JSON.parse(files.get(manifest.path).content.toString("utf8"));
+		if (!object(data)) requirements.add("manifest:missing-or-invalid");
+		else {
+			for (const field of Object.keys(data)) if (!metadataFields.has(field)) requirements.add(`manifest-field:${field}`);
+			if (data.hooks !== void 0) inspect(data.hooks, "hooks");
+			if (data.mcpServers !== void 0) inspect(data.mcpServers, "mcp");
+			if (data.mcp_servers !== void 0) inspect(data.mcp_servers, "mcp");
+		}
+	} catch {
+		requirements.add("manifest:missing-or-invalid");
+	}
+	return [...requirements].sort();
+}
+function meetsMinimum(version, minimum) {
+	const expression = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z.-]+)?$/u;
+	const current = expression.exec(version), required = expression.exec(minimum);
+	if (!current || !required) return false;
+	for (const index of [
+		1,
+		2,
+		3
+	]) {
+		const difference = BigInt(current[index]) - BigInt(required[index]);
+		if (difference !== 0n) return difference > 0n;
+	}
+	return true;
+}
+function createPluginInstallPlan(input) {
+	const { identity, release, adapter, host } = input;
+	const plan = {
+		identity: structuredClone(identity),
+		treeDigest: release.treeDigest,
+		artifactSha256: release.artifactSha256,
+		adapterVersion: adapter?.version ?? "",
+		hostVersion: host.version ?? "",
+		status: "BLOCKED",
+		reasons: [],
+		invocations: []
+	};
+	try {
+		pluginInstallKey(identity);
+	} catch {
+		plan.reasons.push("INVALID_IDENTITY");
+	}
+	if (release.version !== identity.version) plan.reasons.push("VERSION_IDENTITY_MISMATCH");
+	if (release.state !== "PUBLISHED") plan.reasons.push("RELEASE_WITHDRAWN");
+	if (release.quarantined) plan.reasons.push("RELEASE_QUARANTINED");
+	if (!/^[a-f0-9]{64}$/u.test(release.treeDigest) || input.actualTreeDigest !== release.treeDigest) plan.reasons.push("TREE_DIGEST_MISMATCH");
+	if (!/^[a-f0-9]{64}$/u.test(release.artifactSha256) || input.actualArtifactSha256 !== release.artifactSha256) plan.reasons.push("ARCHIVE_DIGEST_MISMATCH");
+	if (!isAbsolute(input.artifactDirectory) || /[\u0000-\u001f\u007f]/u.test(input.artifactDirectory)) plan.reasons.push("INVALID_ARTIFACT_DIRECTORY");
+	if (plan.reasons.length) return plan;
+	if (!adapter) return {
+		...plan,
+		status: "EXPORT_ONLY",
+		reasons: ["NATIVE_ADAPTER_UNVERIFIED"]
+	};
+	if (adapter.targetAgent !== identity.agent || host.agent !== identity.agent) plan.reasons.push("HOST_IDENTITY_MISMATCH");
+	if (!host.version || !adapter.hostVersions.includes(host.version)) plan.reasons.push("HOST_VERSION_UNVERIFIED");
+	if (!adapter.scopes.includes(identity.scope)) plan.reasons.push("SCOPE_UNSUPPORTED");
+	for (const capability of new Set(input.requiredCapabilities)) if (!adapter.capabilities.includes(capability)) plan.reasons.push(`UNSUPPORTED_CAPABILITY:${capability}`);
+	const server = input.serverCapability;
+	if (server?.minCliVersion && !meetsMinimum(input.cliVersion, server.minCliVersion)) plan.reasons.push("CLI_UPGRADE_REQUIRED");
+	const matching = input.evidence.filter((item) => item.targetAgent === identity.agent && item.treeDigest === release.treeDigest && item.adapterVersion === adapter.version && item.hostVersion === host.version);
+	if (matching.some((item) => item.result === "FAIL" || item.result === "UNSUPPORTED")) plan.reasons.push("COMPATIBILITY_CHECK_FAILED");
+	if (plan.reasons.length) return plan;
+	if (identity.source.kind === "registry" && (!server?.installable || !server.minCliVersion || server.adapterVersion !== adapter.version)) return {
+		...plan,
+		status: "EXPORT_ONLY",
+		reasons: ["SERVER_NATIVE_CAPABILITY_UNVERIFIED"]
+	};
+	if (!matching.some((item) => ["LOAD", "FUNCTIONAL"].includes(item.level) && item.result === "PASS")) return {
+		...plan,
+		status: "EXPORT_ONLY",
+		reasons: ["EXACT_RUNTIME_EVIDENCE_REQUIRED"]
+	};
+	const invocations = adapter.plan({
+		identity: structuredClone(identity),
+		artifactDirectory: input.artifactDirectory
+	});
+	if (!invocations.length || invocations.some((invocation) => !invocation.command || [invocation.command, ...invocation.args].some((value) => typeof value !== "string" || value.includes("\0")))) return {
+		...plan,
+		reasons: ["INVALID_NATIVE_PLAN"]
+	};
+	return {
+		...plan,
+		status: "READY",
+		invocations: structuredClone(invocations)
+	};
+}
+const runNative = (invocation, options) => new Promise((resolve, reject) => {
+	execFile(invocation.command, invocation.args, {
+		cwd: options.cwd,
+		shell: false,
+		timeout: 6e4,
+		maxBuffer: 1024 ** 2,
+		signal: options.signal,
+		windowsHide: true
+	}, (error, stdout, stderr) => {
+		if (error) reject(/* @__PURE__ */ new Error(error.name === "AbortError" ? "NATIVE_CANCELLED" : "NATIVE_COMMAND_FAILED"));
+		else resolve({
+			stdout,
+			stderr
+		});
+	});
+});
+async function installNativePlugin(request) {
+	const { input, archive, tree, records, adapter, runner } = request;
+	if (sha256(archive) !== input.release.artifactSha256 || archive.length !== input.release.artifactSize || treeDigest(tree.files) !== input.release.treeDigest) throw new Error("Plugin integrity changed before installation");
+	const plan = createPluginInstallPlan({
+		...input,
+		adapter,
+		actualArtifactSha256: sha256(archive),
+		actualTreeDigest: treeDigest(tree.files)
+	});
+	if (plan.status !== "READY") throw new Error(`${plan.status}: ${plan.reasons.join(", ")}`);
+	const previous = records.read(), activeId = previous.active[pluginSlotKey(plan.identity)];
+	if (activeId) {
+		const active = previous.operations[activeId];
+		if (active.adapterVersion !== adapter.version) throw new Error("Existing plugin requires its original adapter for safe update");
+		const verification = await adapter.verify(active, runner);
+		if (!verification.verified || verification.treeDigest !== active.treeDigest || verification.installationId !== active.installationId) throw new Error("Existing plugin ownership changed; refusing destructive update");
+	}
+	const identifier = records.prepare(plan.identity, plan.artifactSha256, adapter.version, {
+		treeDigest: plan.treeDigest,
+		artifactDirectory: input.artifactDirectory
+	});
+	let invoked = false;
+	try {
+		await materializePluginTree(tree, input.artifactDirectory);
+		invoked = true;
+		await adapter.install(plan, runner);
+		const verification = await adapter.verify(records.read().operations[identifier], runner);
+		if (!verification.verified || verification.treeDigest !== plan.treeDigest || !verification.installationId) throw new Error("Native verification failed");
+		records.complete(identifier, verification);
+		return identifier;
+	} catch {
+		if (!invoked) {
+			records.fail(identifier, "STAGING_FAILED");
+			throw new Error(`PLUGIN_STAGING_FAILED: ${identifier}`);
+		}
+		throw new Error(`NATIVE_OUTCOME_UNKNOWN: ${identifier}; PREPARED retained, inspect the native host before recovery`);
+	}
+}
+async function uninstallNativePlugin(request) {
+	const { operationId, expectedIdentity, records, adapter, runner } = request;
+	const record = records.read().operations[operationId];
+	if (!record || pluginInstallKey(record.identity) !== pluginInstallKey(expectedIdentity) || record.adapterVersion !== adapter.version || record.identity.agent !== adapter.targetAgent) throw new Error("Uninstall identity or adapter mismatch");
+	const removalId = records.prepareRemoval(operationId);
+	let invoked = false;
+	try {
+		const verification = await adapter.verify(record, runner);
+		if (!verification.verified || verification.installationId !== record.installationId || verification.treeDigest !== record.treeDigest) throw new Error("Plugin was modified outside bfi");
+		invoked = true;
+		await adapter.uninstall(record, runner);
+		if (!await adapter.verifyAbsent(record, runner)) throw new Error("Native removal is not verified");
+		records.removed(removalId);
+	} catch {
+		if (!invoked) {
+			records.fail(removalId, "OWNERSHIP_CHANGED");
+			throw new Error("Plugin ownership changed; user content retained");
+		}
+		throw new Error(`NATIVE_OUTCOME_UNKNOWN: ${removalId}; active installation retained until native removal is verified`);
+	}
+}
+const exactId = z.string().regex(/^[1-9][0-9]*$/u);
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const releaseSchema = z.object({
+	id: exactId,
+	snapshotId: exactId,
+	version: z.string().refine(isPluginVersion),
+	treeDigest: digest,
+	artifactSha256: digest,
+	artifactSize: z.number().int().min(0).max(pluginArchiveLimits.compressedBytes),
+	state: z.enum(["PUBLISHED", "YANKED"]),
+	quarantined: z.boolean(),
+	distributionScope: z.enum(["PUBLIC", "PACKAGE_MEMBERS"]),
+	lifecycleRevision: z.string().regex(/^[0-9]+$/u)
+});
+const detailSchema = z.object({
+	release: releaseSchema,
+	files: z.array(z.object({
+		path: z.string(),
+		sha256: digest,
+		size: z.number().int().nonnegative(),
+		executable: z.boolean(),
+		mediaType: z.string()
+	})).max(pluginArchiveLimits.entries),
+	evidence: z.array(z.object({
+		treeDigest: digest,
+		targetAgent: z.string(),
+		hostVersion: z.string().nullable(),
+		adapterVersion: z.string(),
+		level: z.enum([
+			"UNVERIFIED",
+			"STATIC",
+			"LOAD",
+			"FUNCTIONAL"
+		]),
+		result: z.enum([
+			"PASS",
+			"FAIL",
+			"UNKNOWN",
+			"UNSUPPORTED"
+		])
+	}))
+});
+function checkedDetail(value) {
+	const result = detailSchema.safeParse(value);
+	if (!result.success) throw new Error("Invalid immutable plugin release response");
+	return {
+		...result.data,
+		evidence: result.data.evidence.map((item) => ({
+			...item,
+			hostVersion: item.hostVersion ?? "",
+			targetAgent: item.targetAgent
+		}))
+	};
+}
+async function readArchive(path) {
+	const descriptor = await open(path, "r");
+	try {
+		const info = await descriptor.stat();
+		if (!info.isFile() || info.size > pluginArchiveLimits.compressedBytes) throw new Error("Local plugin archive exceeds the file limit or is not a regular file");
+		const bytes = Buffer.alloc(Math.min(info.size + 1, pluginArchiveLimits.compressedBytes + 1));
+		let length = 0;
+		while (length < bytes.length) {
+			const result = await descriptor.read(bytes, length, bytes.length - length, null);
+			if (!result.bytesRead) break;
+			length += result.bytesRead;
+		}
+		if (length !== info.size) throw new Error("Local archive changed while reading");
+		return bytes.subarray(0, length);
+	} finally {
+		await descriptor.close();
+	}
+}
+function checkFiles(detail, tree) {
+	const actual = new Map(tree.files.map((file) => [file.path, file]));
+	if (detail.files.length !== actual.size || new Set(detail.files.map((file) => file.path)).size !== actual.size) throw new Error("Plugin file inventory integrity mismatch");
+	for (const expected of detail.files) {
+		const file = actual.get(expected.path);
+		if (!file || file.executable !== expected.executable || file.content.length !== expected.size || sha256(file.content) !== expected.sha256) throw new Error("Plugin file integrity mismatch");
+	}
+}
+async function artifactParent(root) {
+	let current = root;
+	for (const part of [".bfi", "plugin-artifacts"]) {
+		current = join(current, part);
+		try {
+			await mkdir(current, { mode: 448 });
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		const info = await lstat(current);
+		if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("Plugin artifact store must not follow symbolic links");
+	}
+	return current;
+}
+function matchingOperations(records, options, root, registry) {
+	const lock = records.read();
+	return Object.values(lock.active).map((identifier) => ({
+		identifier,
+		record: lock.operations[identifier]
+	})).filter(({ identifier, record }) => {
+		const identity = record.identity;
+		if (identity.agent !== options.agent || identity.scope !== options.scope || identity.scope === "project" && identity.projectPath !== root || options.version && identity.version !== options.version) return false;
+		if (options.operationId && options.operationId !== identifier) return false;
+		if (!options.source) return Boolean(options.operationId);
+		return identity.source.kind === "registry" ? identity.source.registry === normalizeRegistry(registry) && identity.source.packageRef === options.source : identity.source.sourcePath === resolve(root, options.source);
+	});
+}
+async function runPluginPackage(args, globalOpts) {
+	const options = parsePluginArguments(args), cwd = await realpath(String(globalOpts.workdir ?? process.cwd()));
+	const storeRoot = options.scope === "user" ? await realpath(homedir()) : cwd;
+	const records = new PluginInstallRecords(storeRoot), config = resolveConfig(globalOpts);
+	const registry = new PluginRegistryClient(config.registry, config.token);
+	if (options.command === "list") {
+		const lock = records.read();
+		console.log(JSON.stringify({
+			version: 1,
+			scope: options.scope,
+			active: lock.active,
+			operations: Object.fromEntries(Object.entries(lock.operations).filter(([, record]) => !options.agent || record.identity.agent === options.agent))
+		}, null, 2));
+		return;
+	}
+	const agent = options.agent, adapter = nativeAdapterFor(agent);
+	if (options.command === "uninstall") {
+		const matches = matchingOperations(records, options, cwd, config.registry);
+		if (matches.length !== 1) throw new Error("No unique active plugin installation matches; use list --as plugin and --operation with exact scope/agent");
+		const selected = matches[0];
+		if (options.planOnly) {
+			console.log(JSON.stringify({
+				operationId: selected.identifier,
+				identity: selected.record.identity,
+				status: adapter ? "VERIFY_REQUIRED" : "EXPORT_ONLY",
+				reason: adapter ? "Native ownership verification required before removal" : "Original native adapter is unavailable; no files were removed"
+			}, null, 2));
+			return;
+		}
+		if (!adapter || !adapter.hostVersions.includes(await adapter.detect(runNative, cwd) ?? "")) throw new Error("Original native adapter/host version unavailable; no files were removed");
+		await uninstallNativePlugin({
+			operationId: selected.identifier,
+			expectedIdentity: selected.record.identity,
+			records,
+			adapter,
+			runner: runNative
+		});
+		console.log(JSON.stringify({
+			removed: selected.identifier,
+			identity: selected.record.identity
+		}));
+		return;
+	}
+	let archive, tree, identity, detail;
+	let serverCapability, archiveName = "plugin.zip", root = "";
+	const source = options.source;
+	if (isPluginArchive(source) && !source.startsWith("@")) {
+		const sourcePath = await realpath(resolve(cwd, source));
+		archive = await readArchive(sourcePath);
+		archiveName = sourcePath;
+		const inspected = await inspectPluginArchive(archive, archiveName);
+		if (options.root === void 0 && inspected.roots.length !== 1) throw new Error(`Multiple plugin roots; choose --root explicitly: ${JSON.stringify(inspected.roots)}`);
+		root = options.root ?? inspected.roots[0];
+		tree = selectPluginRoot(inspected, root);
+		const manifest = nativeManifestFormats[agent].map((format) => tree.manifests.find((item) => item.root === "" && item.format === format)).find(Boolean);
+		if (manifest?.invalid) throw new Error("Invalid native plugin manifest");
+		const version = options.version ?? manifest?.version;
+		if (!version || !isPluginVersion(version)) throw new Error("Local plugin needs an exact manifest version or explicit --version; source files are never rewritten");
+		if (manifest?.version && manifest.version !== version) throw new Error("Local manifest version conflicts with --version");
+		const hash = sha256(archive);
+		identity = {
+			source: {
+				kind: "local",
+				sourcePath,
+				sourceDigest: hash
+			},
+			version,
+			agent,
+			scope: options.scope,
+			projectPath: options.scope === "project" ? cwd : null
+		};
+		detail = {
+			release: {
+				id: `local:${hash}`,
+				snapshotId: `local:${tree.treeDigest}`,
+				version,
+				treeDigest: tree.treeDigest,
+				artifactSha256: hash,
+				artifactSize: archive.length,
+				state: "PUBLISHED",
+				quarantined: false,
+				distributionScope: "PUBLIC",
+				lifecycleRevision: "0"
+			},
+			files: [],
+			evidence: []
+		};
+	} else {
+		const [namespace, slug] = source.slice(1).split("/");
+		const packageId = await registry.packageId(namespace, slug), summary = await registry.summary(namespace, slug);
+		if (!summary?.enabled) throw new Error("Plugin capability is not enabled for this package");
+		const version = options.version ?? summary.stable?.version;
+		if (!version || !isPluginVersion(version)) throw new Error("No visible stable plugin version; specify an exact --version, never latest");
+		detail = checkedDetail(await registry.release(namespace, slug, version));
+		if (detail.release.version !== version || detail.release.state !== "PUBLISHED" || detail.release.quarantined) throw new Error("Requested plugin release is not distributable");
+		identity = {
+			source: {
+				kind: "registry",
+				registry: registry.registry,
+				packageId,
+				packageRef: source
+			},
+			version,
+			agent,
+			scope: options.scope,
+			projectPath: options.scope === "project" ? cwd : null
+		};
+		serverCapability = summary.installCapabilities?.version === "1" ? summary.installCapabilities.targets.find((item) => item.targetAgent === agent && item.path === "native") : void 0;
+		archive = await registry.download(namespace, slug, version);
+		if (sha256(archive) !== detail.release.artifactSha256 || archive.length !== detail.release.artifactSize) throw new Error("Plugin archive digest/size integrity mismatch");
+		tree = await inspectPluginArchive(archive, archiveName);
+		if (tree.treeDigest !== detail.release.treeDigest) throw new Error("Plugin tree digest integrity mismatch");
+		checkFiles(detail, tree);
+	}
+	if (options.command === "update" && !records.read().active[pluginSlotKey(identity)]) throw new Error("This exact source/agent/scope is not installed; local changed-content archives are separate identities");
+	const artifactDirectory = join(storeRoot, ".bfi", "plugin-artifacts", `${pluginInstallKey(identity)}-${randomUUID()}`);
+	const input = {
+		identity,
+		release: detail.release,
+		actualTreeDigest: tree.treeDigest,
+		actualArtifactSha256: sha256(archive),
+		requiredCapabilities: nativeRequirements(tree, agent),
+		evidence: detail.evidence,
+		host: {
+			agent,
+			version: adapter ? await adapter.detect(runNative, cwd) : null
+		},
+		cliVersion: String(globalOpts.version ?? ""),
+		serverCapability,
+		artifactDirectory,
+		adapter
+	};
+	const plan = createPluginInstallPlan(input);
+	if (options.planOnly) {
+		console.log(JSON.stringify({
+			...plan,
+			archiveRoot: root,
+			requiredCapabilities: input.requiredCapabilities,
+			nativeSupport: nativeSupportFor(agent)
+		}, null, 2));
+		return;
+	}
+	if (options.exportPath) {
+		const target = resolve(cwd, options.exportPath);
+		if (/\.zip$/iu.test(archiveName) !== /\.zip$/iu.test(target) || !isPluginArchive(target)) throw new Error("Export extension must match original archive format");
+		await writeFile(target, archive, {
+			flag: "wx",
+			mode: 384
+		});
+		console.log(JSON.stringify({
+			exported: target,
+			archiveSha256: sha256(archive),
+			treeDigest: tree.treeDigest,
+			archiveRoot: root,
+			originalArchive: true,
+			installed: false
+		}, null, 2));
+		return;
+	}
+	if (plan.status !== "READY" || !adapter) throw new Error(`${plan.status}: ${plan.reasons.join(", ")}; use --plan or --export <archive>, no skills-only fallback occurred`);
+	if (identity.source.kind === "registry") {
+		const [namespace, slug] = identity.source.packageRef.slice(1).split("/");
+		const current = checkedDetail(await registry.release(namespace, slug, identity.version));
+		if (await registry.packageId(namespace, slug) !== identity.source.packageId || current.release.id !== detail.release.id || current.release.treeDigest !== tree.treeDigest || current.release.state !== "PUBLISHED" || current.release.quarantined) throw new Error("Plugin distribution identity or authority changed before installation");
+	}
+	await artifactParent(storeRoot);
+	const operationId = await installNativePlugin({
+		input,
+		archive,
+		tree,
+		records,
+		adapter,
+		runner: runNative
+	});
+	console.log(JSON.stringify({
+		operationId,
+		identity,
+		verified: true
+	}, null, 2));
+}
+export { runPluginPackage };

package/dist/_chunks/package-skill-identity.mjs

@@ -0,0 +1,18 @@
+import { __exportAll } from "./rolldown-runtime.mjs";
+import { createHash } from "node:crypto";
+var package_skill_identity_exports = /* @__PURE__ */ __exportAll({
+	packageSkillName: () => packageSkillName,
+	scopePackageSkill: () => scopePackageSkill
+});
+function packageSkillName(namespace, slug) {
+	if (!namespace || !slug) throw new Error("Namespace and slug are required");
+	return `bfi-skill-${createHash("sha256").update(JSON.stringify([namespace, slug])).digest("hex")}`;
+}
+function scopePackageSkill(skills, namespace, slug) {
+	if (skills.length !== 1) throw new Error("A package reference must resolve to exactly one skill");
+	return [{
+		...skills[0],
+		name: packageSkillName(namespace, slug)
+	}];
+}
+export { packageSkillName, package_skill_identity_exports };