bfi-cli 0.1.102 → 0.1.104

package/dist/_chunks/package-plugin.mjs

@@ -2,10 +2,10 @@ import { isCancel } from "./libs/@clack/core.mjs";
 import { confirm, select } from "./libs/@clack/prompts.mjs";
 import { PluginInstallRecords, PluginRegistryClient, inspectPluginArchive, isPluginArchive, isPluginVersion, materializePluginTree, normalizeRegistry, parsePluginArguments, pluginArchiveLimits, pluginInstallKey, pluginSlotKey, pluginTargets, selectPluginRoot, sha256, treeDigest } from "./intent.mjs";
 import { loadGlobalConfig, loadProjectConfig, resolveConfig } from "./config.mjs";
-import { credentialForRegistry } from "./client.mjs";
+import { credentialForRegistry } from "../cli.mjs";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { lstat, mkdir, open, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, readdir, realpath, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { execFile } from "node:child_process";
@@ -139,9 +139,9 @@ function nativeRequirements(tree, target) {
 	}
 	return [...requirements].sort();
 }
-const nativeNamePattern = /^[a-z][a-z0-9-]{0,63}$/u;
-const cwdFor = (identity) => identity.projectPath ?? homedir();
-const marketName = (identity, digest, directory) => `bfi-${pluginInstallKey(identity).slice(0, 20)}-${digest.slice(0, 12)}-${sha256(Buffer.from(directory)).slice(0, 12)}`;
+const nativeNamePattern$1 = /^[a-z][a-z0-9-]{0,63}$/u;
+const cwdFor$1 = (identity) => identity.projectPath ?? homedir();
+const marketName$1 = (identity, digest, directory) => `bfi-${pluginInstallKey(identity).slice(0, 20)}-${digest.slice(0, 12)}-${sha256(Buffer.from(directory)).slice(0, 12)}`;
 async function nativeDirectoryDigest(directory) {
 	const files = [];
 	let bytes = 0, entries = 0;
@@ -176,9 +176,9 @@ async function nativeList(runner, cwd, markets = false) {
 	if (!Array.isArray(result) || result.some((item) => !item || typeof item !== "object" || Array.isArray(item))) throw new Error("NATIVE_LIST_INVALID");
 	return result;
 }
-function contextValues(context) {
-	if (!context.nativeName || !nativeNamePattern.test(context.nativeName) || !/^[a-f0-9]{64}$/u.test(context.treeDigest ?? "") || basename(context.artifactDirectory) !== "plugin") throw new Error("NATIVE_CONTEXT_INVALID");
-	const market = marketName(context.identity, context.treeDigest, context.artifactDirectory);
+function contextValues$1(context) {
+	if (!context.nativeName || !nativeNamePattern$1.test(context.nativeName) || !/^[a-f0-9]{64}$/u.test(context.treeDigest ?? "") || basename(context.artifactDirectory) !== "plugin") throw new Error("NATIVE_CONTEXT_INVALID");
+	const market = marketName$1(context.identity, context.treeDigest, context.artifactDirectory);
 	return {
 		market,
 		selector: `${context.nativeName}@${market}`,
@@ -197,7 +197,7 @@ function contextValues(context) {
 async function recordValues(record) {
 	if (await nativeDirectoryDigest(record.artifactDirectory) !== record.treeDigest) throw new Error("NATIVE_CONTENT_CHANGED");
 	const manifest = JSON.parse(await readFile(join(record.artifactDirectory, ".claude-plugin/plugin.json"), "utf8"));
-	return contextValues({
+	return contextValues$1({
 		...record,
 		nativeName: manifest.name
 	});
@@ -233,7 +233,7 @@ const claudeAdapter = {
 		}
 	},
 	plan(context) {
-		const values = contextValues(context);
+		const values = contextValues$1(context);
 		return [{
 			command: "claude",
 			args: [
@@ -257,21 +257,21 @@ const claudeAdapter = {
 	},
 	async preflight(plan, runner) {
 		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
-		const values = contextValues({
+		const values = contextValues$1({
 			...plan,
 			artifactDirectory: plan.artifactDirectory
 		});
-		const cwd = cwdFor(plan.identity);
+		const cwd = cwdFor$1(plan.identity);
 		if ((await nativeList(runner, cwd)).some((item) => typeof item.id !== "string" || item.id.split("@")[0] === plan.nativeName)) throw new Error("NATIVE_NAME_CONFLICT");
 		if ((await nativeList(runner, cwd, true)).some((item) => item.name === values.market)) throw new Error("NATIVE_MARKET_CONFLICT");
 	},
 	async install(plan, runner) {
 		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
-		const values = contextValues({
+		const values = contextValues$1({
 			...plan,
 			artifactDirectory: plan.artifactDirectory
 		});
-		const cwd = cwdFor(plan.identity);
+		const cwd = cwdFor$1(plan.identity);
 		await this.preflight(plan, runner);
 		if (await nativeDirectoryDigest(plan.artifactDirectory) !== plan.treeDigest) throw new Error("NATIVE_CONTENT_CHANGED");
 		const nativeManifest = JSON.parse(await readFile(join(plan.artifactDirectory, ".claude-plugin/plugin.json"), "utf8"));
@@ -288,7 +288,7 @@ const claudeAdapter = {
 	},
 	async verify(record, runner) {
 		try {
-			const values = await recordValues(record), cwd = cwdFor(record.identity);
+			const values = await recordValues(record), cwd = cwdFor$1(record.identity);
 			const index = JSON.parse(await readFile(join(values.directory, ".claude-plugin/marketplace.json"), "utf8"));
 			if (JSON.stringify(index) !== JSON.stringify(values.manifest)) throw new Error("NATIVE_INDEX_CHANGED");
 			const market = (await nativeList(runner, cwd, true)).filter((item) => item.name === values.market);
@@ -309,7 +309,7 @@ const claudeAdapter = {
 		}
 	},
 	async uninstall(record, runner) {
-		const values = await recordValues(record), cwd = cwdFor(record.identity);
+		const values = await recordValues(record), cwd = cwdFor$1(record.identity);
 		await runner({
 			command: "claude",
 			args: [
@@ -324,7 +324,7 @@ const claudeAdapter = {
 	},
 	async verifyAbsent(record, runner) {
 		const values = await recordValues(record);
-		return !(await nativeList(runner, cwdFor(record.identity))).some((item) => item.id === values.selector && item.scope === record.identity.scope && (record.identity.scope === "user" || item.projectPath === record.identity.projectPath));
+		return !(await nativeList(runner, cwdFor$1(record.identity))).some((item) => item.id === values.selector && item.scope === record.identity.scope && (record.identity.scope === "user" || item.projectPath === record.identity.projectPath));
 	}
 };
 const codexRequirements = [
@@ -336,26 +336,75 @@ const codexRequirements = [
 	"executable-assets"
 ];
 async function prepareNativeHandoff(input) {
-	const { tree, target, scope, hostVersion, version } = input;
+	const { tree, target, scope, hostVersion, version, market } = input;
 	if (target !== "claude-code" && target !== "codex") throw new Error("NATIVE_HOST_UNVERIFIED");
 	if (hostVersion !== (target === "claude-code" ? "2.1.251" : "0.136.0")) throw new Error("HOST_VERSION_UNVERIFIED");
 	if (target === "codex" && scope !== "user") throw new Error("SCOPE_UNSUPPORTED");
+	if (!/^bfi-[a-f0-9]{24}$/u.test(market)) throw new Error("MARKET_NAME_INVALID");
 	const supported = target === "claude-code" ? claudeAdapter.capabilities : codexRequirements;
 	const missing = nativeRequirements(tree, target).filter((requirement) => !supported.includes(requirement));
 	if (missing.length) throw new Error(`NATIVE_COMPONENTS_UNSUPPORTED: ${missing.join(", ")}; original files retained; no skills fallback`);
 	const manifest = tree.manifests.find((item) => item.root === "" && item.format === (target === "claude-code" ? "CLAUDE" : "CODEX"));
 	if (!manifest?.name || !/^[a-z][a-z0-9-]{0,63}$/u.test(manifest.name) || !isPluginVersion(version) || manifest.version && manifest.version !== version) throw new Error("NATIVE_MANIFEST_UNSUPPORTED");
-	const destination = resolve(input.directory);
-	const directory = join(await realpath(dirname(destination)), destination.slice(dirname(destination).length + 1));
-	const market = `bfi-${target}-${tree.treeDigest.slice(0, 24)}`;
+	const requested = resolve(input.directory);
+	await mkdir(dirname(requested), {
+		recursive: true,
+		mode: 448
+	});
+	const root = join(await realpath(dirname(requested)), requested.slice(dirname(requested).length + 1));
+	await mkdir(root, {
+		recursive: true,
+		mode: 448
+	});
+	const pluginDirectory = join(root, "versions", version, "plugin");
+	const existing = await nativeDirectoryDigest(pluginDirectory).catch(() => null);
+	if (existing === null) {
+		await mkdir(join(root, "versions", version), {
+			recursive: true,
+			mode: 448
+		});
+		await materializePluginTree(tree, pluginDirectory);
+	} else if (existing !== tree.treeDigest) throw new Error("NATIVE_VERSION_CONTENT_CONFLICT: this version directory already contains different content; choose another --dir");
+	const indexDirectory = join(root, target === "claude-code" ? ".claude-plugin" : ".agents/plugins");
+	await mkdir(indexDirectory, {
+		recursive: true,
+		mode: 448
+	});
+	const indexFile = join(indexDirectory, "marketplace.json");
+	const source = `./versions/${version}/plugin`;
+	const entry = target === "claude-code" ? {
+		name: manifest.name,
+		version,
+		source
+	} : {
+		name: manifest.name,
+		version,
+		source: {
+			source: "local",
+			path: source
+		},
+		policy: { installation: "AVAILABLE" }
+	};
+	const previous = await readFile(indexFile, "utf8").then(JSON.parse).catch(() => null);
+	if (previous && previous.name !== market) throw new Error("MARKET_DIRECTORY_CONFLICT: this directory holds a different marketplace");
+	const plugins = Array.isArray(previous?.plugins) ? previous.plugins : [];
+	const index = {
+		...previous ?? {},
+		name: market,
+		owner: { name: "bfi" },
+		plugins: [...plugins.filter((item) => item?.name !== manifest.name), entry]
+	};
+	const temporary = `${indexFile}.${process.pid}.tmp`;
+	await writeFile(temporary, JSON.stringify(index, null, 2) + "\n", { mode: 384 });
+	await rename(temporary, indexFile);
 	const selector = `${manifest.name}@${market}`;
-	const commands = target === "claude-code" ? [{
+	const installCommands = target === "claude-code" ? [{
 		command: "claude",
 		args: [
 			"plugin",
 			"marketplace",
 			"add",
-			directory,
+			root,
 			"--scope",
 			scope
 		]
@@ -374,7 +423,40 @@ async function prepareNativeHandoff(input) {
 			"plugin",
 			"marketplace",
 			"add",
-			directory
+			root
+		]
+	}, {
+		command: "codex",
+		args: [
+			"plugin",
+			"add",
+			selector
+		]
+	}];
+	const updateCommands = target === "claude-code" ? [{
+		command: "claude",
+		args: [
+			"plugin",
+			"marketplace",
+			"update",
+			market
+		]
+	}, {
+		command: "claude",
+		args: [
+			"plugin",
+			"update",
+			selector,
+			"--scope",
+			scope
+		]
+	}] : [{
+		command: "codex",
+		args: [
+			"plugin",
+			"marketplace",
+			"add",
+			root
 		]
 	}, {
 		command: "codex",
@@ -384,45 +466,208 @@ async function prepareNativeHandoff(input) {
 			selector
 		]
 	}];
-	await mkdir(directory, { mode: 448 });
-	await materializePluginTree(tree, join(directory, "plugin"));
-	const indexDirectory = join(directory, target === "claude-code" ? ".claude-plugin" : ".agents/plugins");
-	await mkdir(indexDirectory, {
-		recursive: true,
-		mode: 448
-	});
-	const index = target === "claude-code" ? {
-		name: market,
-		owner: { name: "bfi" },
-		plugins: [{
-			name: manifest.name,
-			version,
-			source: "./plugin"
-		}]
-	} : {
-		name: market,
-		plugins: [{
-			name: manifest.name,
-			source: {
-				source: "local",
-				path: "./plugin"
-			}
-		}]
-	};
-	await writeFile(join(indexDirectory, "marketplace.json"), JSON.stringify(index, null, 2) + "\n", {
-		flag: "wx",
-		mode: 384
-	});
 	return {
 		state: "PREPARED_FOR_REVIEW",
-		directory,
+		directory: root,
+		market,
+		selector,
+		version,
+		pluginDirectory,
 		treeDigest: tree.treeDigest,
 		registered: false,
 		loaded: false,
-		commands,
-		instructions: "Review all plugin code and native-name conflicts first. Execute from the intended project only after user confirmation. Do not bypass trust. Keep this directory while installed. List/registration success is not runtime LOAD; restart the host and check all components. Use the native host for updates/removal; this handoff does not create bfi installation ownership."
+		commands: input.update ? updateCommands : installCommands,
+		installCommands,
+		updateCommands,
+		instructions: "Review all plugin code and native-name conflicts first. Execute from the intended project only after user confirmation. Do not bypass trust. Keep this directory while installed. List/registration success is not runtime LOAD; restart the host and check all components."
 	};
 }
+const nativeNamePattern = /^[a-z][a-z0-9-]{0,63}$/u;
+const scope = "user";
+const cwdFor = (identity) => identity.projectPath ?? homedir();
+const codexHome = () => process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+const marketName = (identity, digest, directory) => `bfi-${pluginInstallKey(identity).slice(0, 20)}-${digest.slice(0, 12)}-${sha256(Buffer.from(directory)).slice(0, 12)}`;
+async function installedSelector(record) {
+	return record.installationId ?? null;
+}
+async function listed(runner, cwd) {
+	return (await runner({
+		command: "codex",
+		args: ["plugin", "list"]
+	}, { cwd })).stdout;
+}
+function contextValues(context) {
+	if (!context.nativeName || !nativeNamePattern.test(context.nativeName) || !/^[a-f0-9]{64}$/u.test(context.treeDigest ?? "")) throw new Error("NATIVE_CONTEXT_INVALID");
+	const market = marketName(context.identity, context.treeDigest, context.artifactDirectory);
+	return {
+		market,
+		directory: dirname(context.artifactDirectory),
+		selector: `${context.nativeName}@${market}`,
+		manifest: {
+			name: market,
+			interface: { displayName: `bfi ${context.nativeName}` },
+			plugins: [{
+				name: context.nativeName,
+				version: context.identity.version,
+				source: {
+					source: "local",
+					path: "./plugin"
+				},
+				policy: { installation: "AVAILABLE" }
+			}]
+		}
+	};
+}
+const codexAdapter = {
+	targetAgent: "codex",
+	version: "codex-public-v1",
+	hostVersions: ["0.136.0"],
+	scopes: [scope],
+	capabilities: [
+		"native-plugin",
+		"manifest:CODEX",
+		"manifest-field:skills",
+		"component:skills",
+		"component:agent-metadata",
+		"executable-assets"
+	],
+	async detect(runner, cwd) {
+		try {
+			return /^codex(?:-cli)? (\d+\.\d+\.\d+)\s*$/u.exec((await runner({
+				command: "codex",
+				args: ["--version"]
+			}, { cwd })).stdout)?.[1] ?? null;
+		} catch {
+			return null;
+		}
+	},
+	plan(context) {
+		const values = contextValues(context);
+		return [{
+			command: "codex",
+			args: [
+				"plugin",
+				"marketplace",
+				"add",
+				values.directory
+			]
+		}, {
+			command: "codex",
+			args: [
+				"plugin",
+				"add",
+				values.selector
+			]
+		}];
+	},
+	async preflight(plan, runner) {
+		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
+		const values = contextValues({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		});
+		const cwd = cwdFor(plan.identity);
+		if ((await runner({
+			command: "codex",
+			args: [
+				"plugin",
+				"marketplace",
+				"list"
+			]
+		}, { cwd })).stdout.split("\n").some((line) => line.trim().startsWith(values.market))) throw new Error("NATIVE_MARKET_CONFLICT");
+		if ((await listed(runner, cwd)).split("\n").some((line) => line.trim().startsWith(`${plan.nativeName}@`))) throw new Error("NATIVE_NAME_CONFLICT");
+	},
+	async install(plan, runner) {
+		if (!plan.artifactDirectory) throw new Error("NATIVE_CONTEXT_INVALID");
+		const values = contextValues({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		});
+		const cwd = cwdFor(plan.identity);
+		await this.preflight(plan, runner);
+		if (await nativeDirectoryDigest(plan.artifactDirectory) !== plan.treeDigest) throw new Error("NATIVE_CONTENT_CHANGED");
+		const indexDirectory = join(values.directory, ".agents", "plugins");
+		await mkdir(indexDirectory, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(join(indexDirectory, "marketplace.json"), JSON.stringify(values.manifest, null, 2) + "\n", {
+			flag: "wx",
+			mode: 384
+		});
+		for (const invocation of this.plan({
+			...plan,
+			artifactDirectory: plan.artifactDirectory
+		})) await runner(invocation, { cwd });
+	},
+	async verify(record, runner) {
+		try {
+			const selector = await installedSelector(record);
+			if (!selector) return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+			const [nativeName, market] = selector.split("@");
+			if (!nativeName || !market) return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+			if (!enabled(await readFile(join(codexHome(), "config.toml"), "utf8"), selector)) return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+			const entry = (await listed(runner, cwdFor(record.identity))).split("\n").find((line) => line.trim().startsWith(selector));
+			if (!entry || !/installed(?:,\s*enabled)?/u.test(entry)) return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+			const digest = await nativeDirectoryDigest(join(codexHome(), "plugins", "cache", market, nativeName, record.identity.version));
+			return {
+				verified: digest === record.treeDigest,
+				installationId: selector,
+				treeDigest: digest
+			};
+		} catch {
+			return {
+				verified: false,
+				installationId: "",
+				treeDigest: ""
+			};
+		}
+	},
+	async uninstall(record, runner) {
+		const selector = await installedSelector(record);
+		if (!selector) throw new Error("NATIVE_CONTEXT_INVALID");
+		await runner({
+			command: "codex",
+			args: [
+				"plugin",
+				"remove",
+				selector
+			]
+		}, { cwd: cwdFor(record.identity) });
+	},
+	async verifyAbsent(record, runner) {
+		const selector = await installedSelector(record);
+		if (!selector) return false;
+		return !(await listed(runner, cwdFor(record.identity)).catch(() => "")).split("\n").some((line) => line.trim().startsWith(selector));
+	}
+};
+function enabled(config, selector) {
+	const lines = config.split("\n");
+	const header = `[plugins."${selector}"]`;
+	const start = lines.findIndex((line) => line.trim() === header);
+	if (start < 0) return false;
+	for (const line of lines.slice(start + 1)) {
+		if (line.trim().startsWith("[")) break;
+		if (/^\s*enabled\s*=\s*true\s*$/u.test(line)) return true;
+	}
+	return false;
+}
 var targets = [
 	{
 		"id": "claude-code",
@@ -438,12 +683,12 @@ var targets = [
 	{
 		"id": "codex",
 		"name": "Codex",
-		"status": "EXPORT_ONLY",
+		"status": "NATIVE_GATED",
 		"versions": ["0.136.0"],
 		"scopes": ["user"],
 		"manifest": ".codex-plugin/plugin.json",
 		"docs": "https://learn.chatgpt.com/docs/plugins",
-		"reason": "已验证公开市场注册、安装和卸载接口；尚未满足自动安装的完整加载及归属验证门禁。项目级原生插件安装未验证。",
+		"reason": "适配器已按 0.136.0 的本地市场与 plugin add/remove/list 实现；仍需每个发布版本的运行时加载证据与服务端授权，项目级安装未验证。",
 		"manual": "仅原生 Codex 技能型插件可用 --prepare-native 生成完整目录和独立市场索引，再按输出执行 codex plugin marketplace add / plugin add。在 /plugins 检查实际启用；有 MCP、Hooks、Apps 或转换需求时停止，不把不支持的组件丢弃。"
 	},
 	{
@@ -480,7 +725,10 @@ var targets = [
 		"manual": "原生入口为 qwen extensions install；此处未验证隔离安装及组件保真，只导出。禁止自动把 Claude 插件转换成扩展或拆成技能。"
 	}
 ];
-const adapters = Object.freeze({ "claude-code": claudeAdapter });
+const adapters = Object.freeze({
+	"claude-code": claudeAdapter,
+	codex: codexAdapter
+});
 const reasons = {
 	"claude-code": ["EXACT_RELEASE_LOAD_EVIDENCE_REQUIRED", "SERVER_NATIVE_CAPABILITY_REQUIRED"],
 	codex: ["PUBLIC_INSTALL_VERIFIED", "EXACT_RUNTIME_LOAD_AND_OWNERSHIP_UNVERIFIED"],
@@ -663,6 +911,24 @@ async function uninstallNativePlugin(request) {
 }
 const exactId = z.string().regex(/^[1-9][0-9]*$/u);
 const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+function baseName(source) {
+	if (source.startsWith("@")) return source.split("/")[1] ?? "plugin";
+	return basename(source).replace(/\.(?:zip|tgz|tar\.gz)$/iu, "");
+}
+function archiveFormat(path) {
+	if (/\.zip$/iu.test(path)) return "zip";
+	if (/\.tar\.gz$/iu.test(path)) return "tar.gz";
+	if (/\.tgz$/iu.test(path)) return "tgz";
+}
+function handoffMarket(identity) {
+	const source = identity.source.kind === "registry" ? `${identity.source.registry}|${identity.source.packageRef}` : identity.source.sourcePath;
+	return `bfi-${sha256(Buffer.from(JSON.stringify([
+		source,
+		identity.agent,
+		identity.scope,
+		identity.projectPath
+	]))).slice(0, 24)}`;
+}
 const releaseSchema = z.object({
 	id: exactId,
 	snapshotId: exactId,
@@ -770,7 +1036,7 @@ function matchingOperations(records, options, root, registry) {
 }
 async function runPluginPackage(args, globalOpts) {
 	const options = parsePluginArguments(args), cwd = await realpath(String(globalOpts.workdir ?? process.cwd()));
-	const chooseAgent = !options.agent && options.command !== "list";
+	const chooseAgent = !options.agent && options.command !== "list" && options.command !== "download" && !options.exportPath;
 	if (chooseAgent) {
 		if (options.json || options.confirmed || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("AGENT_REQUIRED: specify --agent; interactive installation will ask you to choose");
 		const agent = await select({
@@ -783,7 +1049,8 @@ async function runPluginPackage(args, globalOpts) {
 		if (isCancel(agent) || !pluginTargets.includes(agent)) throw new Error("NATIVE_CANCELLED");
 		options.agent = agent;
 	}
-	if (!options.scopeExplicit && options.command !== "list" && (chooseAgent || !options.planOnly && !options.exportPath)) {
+	if (!options.agent && (options.command === "download" || options.exportPath)) options.agent = "claude-code";
+	if (!options.scopeExplicit && options.command !== "list" && options.command !== "download" && (chooseAgent || !options.planOnly && !options.exportPath)) {
 		if (options.json || options.confirmed || !process.stdin.isTTY || !process.stdout.isTTY) throw new Error("SCOPE_REQUIRED: specify --scope user or --scope project; --yes does not choose a scope");
 		const scope = await select({
 			message: "选择插件安装范围",
@@ -844,8 +1111,14 @@ async function runPluginPackage(args, globalOpts) {
 	}
 	let archive, tree, identity, detail;
 	let serverCapability, archiveName = "plugin.zip", root = "";
-	const source = options.source;
-	if (isPluginArchive(source) && !source.startsWith("@")) {
+	const source = options.source, local = isPluginArchive(source) && !source.startsWith("@");
+	const exportRequested = options.command === "download" || Boolean(options.exportPath);
+	const localFormat = local ? archiveFormat(source) : void 0;
+	if (local && options.format && options.format !== localFormat) throw new Error("--format must match the local archive format");
+	if (options.format && !exportRequested) throw new Error("--format requires download or --export");
+	const format = exportRequested ? options.format ?? localFormat ?? archiveFormat(options.exportPath ?? "") ?? "zip" : "zip";
+	if (!local) archiveName = format === "zip" ? "plugin.zip" : format === "tar.gz" ? "plugin.tar.gz" : "plugin.tgz";
+	if (local) {
 		const sourcePath = await realpath(resolve(cwd, source));
 		archive = await readArchive(sourcePath);
 		archiveName = sourcePath;
@@ -907,13 +1180,12 @@ async function runPluginPackage(args, globalOpts) {
 			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");
+		archive = await registry.download(namespace, slug, version, format);
+		if (format === "zip" && (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 artifactContainer = join(storeRoot, ".bfi", "plugin-artifacts", `${pluginInstallKey(identity)}-${randomUUID()}`);
 	const artifactDirectory = join(artifactContainer, "plugin");
 	const manifest = nativeManifestFormats[agent].map((format) => tree.manifests.find((item) => item.root === "" && item.format === format)).find(Boolean);
@@ -956,9 +1228,11 @@ async function runPluginPackage(args, globalOpts) {
 		}, 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");
+	if (options.exportPath || options.command === "download") {
+		const suffix = format === "zip" ? ".zip" : format === "tar.gz" ? ".tar.gz" : ".tgz";
+		const target = resolve(cwd, options.exportPath ?? `${baseName(options.source)}-${identity.version}${suffix}`);
+		const targetFormat = archiveFormat(target);
+		if (!targetFormat || targetFormat === "zip" !== (format === "zip")) throw new Error("Export extension must match --format");
 		await writeFile(target, archive, {
 			flag: "wx",
 			mode: 384
@@ -966,17 +1240,18 @@ async function runPluginPackage(args, globalOpts) {
 		console.log(JSON.stringify({
 			state: "EXPORTED",
 			exported: target,
+			format,
+			version: identity.version,
 			archiveSha256: sha256(archive),
 			treeDigest: tree.treeDigest,
 			archiveRoot: root,
-			originalArchive: true,
 			installed: false,
 			registered: false,
 			loaded: false
 		}, null, 2));
 		return;
 	}
-	if (options.preparePath) {
+	if (options.preparePath || options.command === "prepare") {
 		if (detail.evidence.some((item) => item.targetAgent === agent && item.treeDigest === tree.treeDigest && (!item.hostVersion || item.hostVersion === hostVersion) && (item.result === "FAIL" || item.result === "UNSUPPORTED"))) throw new Error("COMPATIBILITY_CHECK_FAILED: native handoff blocked by recorded compatibility failure; complete export remains available");
 		if (plan.reasons.includes("CLI_UPGRADE_REQUIRED")) throw new Error("CLI_UPGRADE_REQUIRED");
 		console.log(JSON.stringify(await prepareNativeHandoff({
@@ -985,7 +1260,9 @@ async function runPluginPackage(args, globalOpts) {
 			scope: options.scope,
 			version: identity.version,
 			hostVersion,
-			directory: resolve(cwd, options.preparePath)
+			directory: resolve(cwd, options.preparePath ?? `${baseName(options.source)}-handoff`),
+			market: handoffMarket(identity),
+			update: options.command === "update"
 		}), null, 2));
 		return;
 	}

package/dist/_chunks/receipt.mjs

@@ -1,5 +1,5 @@
-import { checkPath, readConfig } from "./files.mjs";
 import { canonical, hash } from "./digest.mjs";
+import { checkPath, readConfig } from "../cli.mjs";
 import { randomUUID } from "node:crypto";
 import { constants, realpathSync } from "node:fs";
 import { dirname, join, parse, resolve } from "node:path";