@xopcai/xopc 0.0.395 → 0.0.397

package/dist/src/extensions/agent-plugins/setup.js

@@ -0,0 +1,491 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { pluginAuthorizations } from "./setup-contract.js";
+import { preparePluginResources } from "./resources.js";
+import { pluginName, pluginServerId } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+import { connectionFingerprint, matchingReusableConnection } from "./connection-reuse.js";
+import { createNativeMcpCredentials } from "../../agent/mcp/credential-store.js";
+import { readPluginAuthBinding, savePluginAuthBinding, savePluginOAuthReference } from "./auth.js";
+import { pluginConfigMissing, readPluginUserConfig, savePluginUserConfig } from "./user-config.js";
+import { materializePluginServers } from "./mcp-adapter.js";
+import { getNativePiAgentDir } from "../../agent/mcp/native-mcp.js";
+import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "../../agent/mcp/connection-setup.js";
+import { cancelPluginCliAuthorizations, checkPluginCliAuthorization, getPluginCliAuthorization, startPluginCliAuthorization } from "./cli-authorization.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import lockfile from "proper-lockfile";
+//#region src/extensions/agent-plugins/setup.ts
+init_logger();
+init_write_file_atomic();
+const connection = z.object({
+	name: z.string(),
+	state: z.enum([
+		"pending",
+		"connected",
+		"oauth_required",
+		"token_required",
+		"error",
+		"skipped"
+	]),
+	toolCount: z.number().optional(),
+	authorizationId: z.string().optional()
+});
+const schema = z.object({
+	id: z.string().uuid(),
+	pluginId: pluginName,
+	owner: z.string(),
+	packageRevision: z.string().uuid(),
+	revision: z.number().int(),
+	state: z.enum([
+		"pending",
+		"running",
+		"action_required",
+		"completed",
+		"cancelled",
+		"interrupted",
+		"failed"
+	]),
+	resources: z.enum([
+		"pending",
+		"running",
+		"ready",
+		"error"
+	]),
+	connections: z.array(connection),
+	installed: z.boolean().default(false),
+	deferred: z.boolean().default(false),
+	authorizations: z.array(z.object({
+		id: z.string(),
+		state: z.enum([
+			"pending",
+			"connected",
+			"skipped",
+			"error"
+		]),
+		method: z.string().optional(),
+		attemptId: z.string().optional()
+	})).default([]),
+	operations: z.array(z.object({
+		key: z.string().uuid(),
+		action: z.string()
+	})).max(100).default([]),
+	missingConfig: z.array(z.string()).default([]),
+	partial: z.boolean(),
+	updatedAt: z.string(),
+	error: z.string().optional()
+});
+const actionRevision = {
+	expectedRevision: z.number().int(),
+	idempotencyKey: z.string().uuid().optional()
+};
+const setupActionSchema = z.discriminatedUnion("action", [
+	z.strictObject({
+		action: z.literal("prepare"),
+		...actionRevision
+	}),
+	z.strictObject({
+		action: z.literal("reuse"),
+		...actionRevision,
+		server: z.string(),
+		sourceServerId: z.string()
+	}),
+	z.strictObject({
+		action: z.literal("authorize"),
+		...actionRevision,
+		server: z.string(),
+		method: z.string().optional()
+	}),
+	z.strictObject({
+		action: z.literal("configure"),
+		...actionRevision,
+		values: z.record(z.string(), z.unknown()),
+		authorization: z.string().optional(),
+		method: z.string().optional()
+	}),
+	z.strictObject({
+		action: z.literal("complete"),
+		...actionRevision,
+		workspacePaths: z.array(z.string().min(1)).max(100).nullable().optional(),
+		allowPartial: z.boolean().default(false)
+	}),
+	z.strictObject({
+		action: z.literal("defer"),
+		...actionRevision
+	}),
+	z.strictObject({
+		action: z.literal("cancel"),
+		...actionRevision
+	})
+]);
+const log = createLogger("PluginSetup");
+const running = /* @__PURE__ */ new Map();
+var PluginSetupService = class {
+	constructor(store = new AgentPluginStore()) {
+		this.store = store;
+	}
+	path(id) {
+		return join(this.store.stateDir, "plugin-setup", `${pluginName.parse(id)}.json`);
+	}
+	key(id) {
+		return this.path(id);
+	}
+	write(job) {
+		job.revision++;
+		job.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		writeTextAtomicSync(this.path(job.pluginId), JSON.stringify(schema.parse(job)));
+	}
+	get(id, owner) {
+		if (!existsSync(this.path(id))) return;
+		const job = schema.parse(JSON.parse(readFileSync(this.path(id), "utf8")));
+		if (job.owner !== owner) throw new Error("Setup belongs to another principal");
+		if (job.state === "running" && !running.has(this.key(id)) && !lockfile.checkSync(this.path(id), { realpath: false })) {
+			job.state = "interrupted";
+			job.error = "Preparation was interrupted. Retry to continue.";
+			this.write(job);
+		}
+		return job;
+	}
+	create(id, owner) {
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin || plugin.readiness === "blocked") throw new Error("Plugin unavailable");
+		const previous = this.get(id, owner);
+		if (previous?.packageRevision === plugin.receipt.revision && previous.state !== "cancelled") return previous;
+		if (running.has(this.key(id)) || lockfile.checkSync(this.path(id), { realpath: false })) throw new Error("Preparation is already running");
+		const job = {
+			id: randomUUID(),
+			pluginId: id,
+			owner,
+			packageRevision: plugin.receipt.revision,
+			revision: 0,
+			state: "pending",
+			resources: "pending",
+			connections: Object.keys(plugin.servers).map((name) => ({
+				name,
+				state: "pending"
+			})),
+			installed: false,
+			deferred: false,
+			authorizations: pluginAuthorizations(plugin.manifest).map((value) => ({
+				id: value.id,
+				state: "pending"
+			})),
+			operations: [],
+			missingConfig: pluginConfigMissing(this.store, plugin),
+			partial: plugin.diagnostics.length > 0,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		this.write(job);
+		return job;
+	}
+	invalidateConnection(id, owner, name) {
+		const job = this.get(id, owner);
+		if (!job) return;
+		running.get(this.key(id))?.abort();
+		const server = job.connections.find((value) => value.name === name);
+		if (server) {
+			if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			server.state = "pending";
+			delete server.authorizationId;
+		}
+		job.state = "action_required";
+		this.write(job);
+	}
+	async reusableConnections(id, owner, config) {
+		if (!this.get(id, owner)) return {};
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin) return {};
+		getNativePiAgentDir();
+		const credentials = await createNativeMcpCredentials();
+		const result = {};
+		for (const [name, target] of Object.entries(plugin.servers)) {
+			result[name] = [];
+			for (const [sourceId, source] of Object.entries(config.mcp?.servers ?? {})) {
+				if (!matchingReusableConnection(target, source) || !source.url || !source.xopcOAuthCredentialId) continue;
+				if (await credentials.tokens(source.xopcOAuthCredentialId, source.url)) result[name].push({
+					id: sourceId,
+					name: source.displayName ?? sourceId
+				});
+			}
+		}
+		return result;
+	}
+	async authorization(id, owner, server, config) {
+		const job = this.get(id, owner);
+		if (!job) throw new Error("Setup not found");
+		const declared = pluginAuthorizations((this.store.pending(id) ?? this.store.get(id)).manifest).find((value) => value.id === server);
+		const selected = job.authorizations.find((value) => value.id === server);
+		const method = declared?.methods.find((value) => value.id === selected?.method);
+		if (method?.type === "cli") return selected?.attemptId ? getPluginCliAuthorization(selected.attemptId, owner, job.packageRevision) : void 0;
+		const target = job.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : server));
+		if (!target?.authorizationId) return void 0;
+		const effective = this.config(id, job.packageRevision, config);
+		return getMcpAuthorization(target.authorizationId, owner, effective);
+	}
+	redirect(id, owner, server, url, config) {
+		const job = this.get(id, owner);
+		const declaration = pluginAuthorizations((this.store.pending(id) ?? this.store.get(id)).manifest).find((value) => value.id === server);
+		const selected = job?.authorizations.find((value) => value.id === server);
+		const method = declaration?.methods.find((value) => value.id === selected?.method);
+		const attempt = job?.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : server))?.authorizationId;
+		return !!job && !!attempt && submitMcpRedirect(attempt, owner, url, this.config(id, job.packageRevision, config));
+	}
+	config(id, revision, config) {
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin || plugin.receipt.revision !== revision || plugin.readiness === "blocked") throw new Error("Plugin revision changed; restart setup");
+		const servers = materializePluginServers(plugin, this.store, [], true);
+		return {
+			...config,
+			mcp: {
+				...config.mcp,
+				servers: {
+					...config.mcp?.servers,
+					...servers
+				}
+			}
+		};
+	}
+	startPrepare(id, owner, revision, config, workspace, idempotencyKey) {
+		const current = this.get(id, owner);
+		if (idempotencyKey && current?.operations.some((op) => op.key === idempotencyKey && op.action === "prepare")) return current;
+		if (!current || current.revision !== revision) throw new Error("Setup changed. Refresh and retry.");
+		if (current.state === "running") return current;
+		if (lockfile.checkSync(this.path(id), { realpath: false })) throw new Error("Preparation is already running");
+		this.act(id, owner, {
+			action: "prepare",
+			expectedRevision: revision,
+			idempotencyKey
+		}, config, workspace).catch(() => {
+			log.warn({ pluginId: id }, "Plugin preparation could not continue");
+		});
+		return this.get(id, owner);
+	}
+	async act(id, owner, input, config, workspace) {
+		const current = this.get(id, owner);
+		const previous = input.idempotencyKey && current?.operations.find((op) => op.key === input.idempotencyKey);
+		if (previous) {
+			if (previous.action !== input.action) throw new Error("Idempotency key belongs to another action");
+			return current;
+		}
+		const remember = (job) => {
+			if (input.idempotencyKey && (job.state !== "cancelled" || input.action === "cancel")) {
+				job.operations = [...job.operations, {
+					key: input.idempotencyKey,
+					action: input.action
+				}].slice(-100);
+				this.write(job);
+			}
+			return job;
+		};
+		if (input.action === "cancel") return remember(await this.perform(id, owner, input, config, workspace));
+		const release = lockfile.lockSync(this.path(id), { realpath: false });
+		try {
+			return remember(await this.perform(id, owner, input, config, workspace));
+		} finally {
+			release();
+		}
+	}
+	async perform(id, owner, input, config, workspace) {
+		const job = this.get(id, owner);
+		if (!job) throw new Error("Setup not found");
+		if (job.revision !== input.expectedRevision) throw new Error("Setup changed. Refresh and retry.");
+		if (input.action === "cancel") {
+			running.get(this.key(id))?.abort();
+			cancelPluginCliAuthorizations(id, owner);
+			for (const server of job.connections) if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			job.state = "cancelled";
+			this.write(job);
+			this.store.discardPending(id);
+			return job;
+		}
+		if (running.has(this.key(id))) throw new Error("Preparation is already running");
+		if (job.state === "cancelled") throw new Error("Restart setup before continuing");
+		const effective = this.config(id, job.packageRevision, config);
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		const declarations = pluginAuthorizations(plugin.manifest);
+		if (input.action === "configure") {
+			const controller = new AbortController();
+			running.set(this.key(id), controller);
+			try {
+				if (input.authorization || input.method) {
+					const declaration = declarations.find((value) => value.id === input.authorization);
+					const method = declaration?.methods.find((value) => value.id === input.method);
+					if (!method || !("fields" in method) || Object.keys(input.values).some((key) => !method.fields.includes(key))) throw new Error("Invalid credential form");
+					const saved = readPluginUserConfig(this.store, id, plugin.receipt.revision);
+					if (method.fields.some((key) => input.values[key] === void 0 && saved[key] === void 0 || typeof input.values[key] === "string" && !input.values[key].trim())) throw new Error("Complete the required credential fields");
+					const target = job.authorizations.find((value) => value.id === declaration.id);
+					target.method = method.id;
+					target.state = "pending";
+					delete target.attemptId;
+				}
+				cancelPluginCliAuthorizations(id, owner);
+				await savePluginUserConfig(this.store, plugin, input.values);
+				controller.signal.throwIfAborted();
+				this.config(id, job.packageRevision, config);
+				for (const server of job.connections) {
+					if (input.authorization && !declarations.find((value) => value.id === input.authorization)?.servers.includes(server.name)) continue;
+					if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+					server.state = "pending";
+					delete server.authorizationId;
+				}
+				job.missingConfig = pluginConfigMissing(this.store, plugin);
+				job.state = "action_required";
+				this.write(job);
+				return job;
+			} finally {
+				running.delete(this.key(id));
+			}
+		}
+		if (input.action === "reuse") {
+			const source = config.mcp?.servers?.[input.sourceServerId];
+			const candidates = await this.reusableConnections(id, owner, config);
+			if (!source?.xopcOAuthCredentialId || !candidates[input.server]?.some((value) => value.id === input.sourceServerId)) throw new Error("This connection is unavailable or has different endpoint or OAuth scopes");
+			if (this.get(id, owner)?.revision !== job.revision) throw new Error("Setup changed. Refresh and retry.");
+			savePluginOAuthReference(this.store, id, input.server, {
+				sourceServerId: input.sourceServerId,
+				credentialId: source.xopcOAuthCredentialId,
+				fingerprint: connectionFingerprint(source)
+			});
+			const server = job.connections.find((value) => value.name === input.server);
+			if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			server.state = "pending";
+			delete server.authorizationId;
+			job.state = "action_required";
+			this.write(job);
+			return job;
+		}
+		if (input.action === "authorize") {
+			const declaration = declarations.find((value) => value.id === input.server);
+			const method = declaration?.methods.find((value) => value.id === input.method);
+			if (declaration && !method) throw new Error("Choose an authorization method");
+			if (method?.type === "form") throw new Error("Complete this method using its credential form");
+			if (declaration && method) {
+				if (job.resources !== "ready") throw new Error("Prepare resources before signing in");
+				const target = job.authorizations.find((value) => value.id === declaration.id);
+				target.method = method.id;
+				target.state = "pending";
+				for (const server of job.connections) if (declaration.servers.includes(server.name)) {
+					if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+					server.state = "pending";
+					delete server.authorizationId;
+				}
+				if (method.type === "cli") {
+					target.attemptId = startPluginCliAuthorization(this.store, plugin, declaration.id, method, owner).id;
+					job.state = "action_required";
+					this.write(job);
+					return job;
+				}
+			}
+			const server = job.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : input.server));
+			if (!server) throw new Error("Unknown setup connection");
+			const target = plugin.servers[server.name];
+			if (target && readPluginAuthBinding(this.store, id, server.name, target, plugin.receipt.revision)?.oauthReference) await savePluginAuthBinding(this.store, id, server.name, { mode: "auto" });
+			if (this.get(id, owner)?.revision !== job.revision) throw new Error("Setup changed. Refresh and retry.");
+			server.authorizationId = startMcpAuthorization(this.config(id, job.packageRevision, config), workspace, pluginServerId(id, server.name), owner, { authorizationScope: `${job.id}:${server.name}` }).id;
+			job.state = "action_required";
+			this.write(job);
+			return job;
+		}
+		if (input.action === "complete" || input.action === "defer") {
+			const deferred = input.action === "defer";
+			if (job.resources !== "ready" || !deferred && pluginConfigMissing(this.store, plugin).length) throw new Error("Prepare resources and configuration first");
+			const partial = plugin.diagnostics.length > 0 || job.connections.some((c) => c.state !== "connected") || job.authorizations.some((value) => value.state !== "connected") || pluginConfigMissing(this.store, plugin).length > 0;
+			if (partial && !deferred && !("allowPartial" in input && input.allowPartial)) throw new Error("Some capabilities are unavailable. Review before enabling partially.");
+			if (plugin.layout?.compatibility.some((item) => item.component === "hooks")) throw new Error("Lifecycle hooks are not supported; keep this plugin installed and disabled until a compatible adapter is available");
+			this.store.commitPending(id);
+			this.store.setWorkspaceScope(id, "workspacePaths" in input ? input.workspacePaths : void 0);
+			this.store.setEnabled(id, true);
+			if (deferred) {
+				delete job.error;
+				cancelPluginCliAuthorizations(id, owner);
+				for (const server of job.connections) if (server.authorizationId && server.state !== "connected") cancelMcpAuthorization(server.authorizationId, owner);
+			}
+			job.installed = true;
+			job.deferred = deferred && partial;
+			job.partial = partial;
+			job.state = "completed";
+			this.write(job);
+			return job;
+		}
+		const controller = new AbortController();
+		running.set(this.key(id), controller);
+		const cancellationPoll = setInterval(() => {
+			try {
+				const current = this.get(id, owner);
+				if (!current || current.id !== job.id || current.revision !== job.revision || current.state === "cancelled" || !this.store.receipt(id)) controller.abort();
+			} catch {
+				controller.abort();
+			}
+		}, 500);
+		cancellationPoll.unref();
+		job.state = "running";
+		job.resources = "running";
+		delete job.error;
+		this.write(job);
+		try {
+			await preparePluginResources(this.store, plugin, controller.signal);
+			job.resources = "ready";
+			job.missingConfig = pluginConfigMissing(this.store, plugin);
+			if (job.missingConfig.length) {
+				job.state = "action_required";
+				job.error = "Complete the required configuration fields.";
+			} else {
+				for (const target of job.authorizations) {
+					const method = declarations.find((value) => value.id === target.id).methods.find((value) => value.id === target.method);
+					if (method?.type === "cli") target.state = await checkPluginCliAuthorization(this.store, plugin, target.id, method, controller.signal) ? "connected" : "pending";
+					else if (method?.type === "form") {
+						const values = readPluginUserConfig(this.store, id, plugin.receipt.revision);
+						target.state = method.fields.every((key) => values[key] !== void 0 && values[key] !== "") ? "connected" : "pending";
+					}
+				}
+				for (const server of job.connections) {
+					controller.signal.throwIfAborted();
+					if (declarations.filter((value) => value.servers.includes(server.name)).some((gate) => {
+						const target = job.authorizations.find((value) => value.id === gate.id);
+						const method = gate.methods.find((value) => value.id === target.method);
+						return !method || method.type !== "oauth" && target.state !== "connected";
+					})) {
+						server.state = "skipped";
+						delete server.toolCount;
+						continue;
+					}
+					const result = await probeMcpConnection(effective, workspace, pluginServerId(id, server.name), { signal: controller.signal });
+					controller.signal.throwIfAborted();
+					server.state = result.state;
+					server.toolCount = result.toolCount;
+					const persisted = this.get(id, owner);
+					if (!persisted || persisted.id !== job.id || persisted.revision !== job.revision || persisted.state === "cancelled" || !this.store.receipt(id)) throw new Error("Setup changed");
+					this.config(id, job.packageRevision, config);
+					this.write(job);
+				}
+				for (const target of job.authorizations) target.state = declarations.find((value) => value.id === target.id).servers.every((name) => job.connections.find((value) => value.name === name)?.state === "connected") ? "connected" : "pending";
+				job.partial = plugin.diagnostics.length > 0;
+				if (job.connections.some((value) => value.state === "error")) job.error = "Connection verification failed. Check the credentials or login status and try again.";
+				job.state = "action_required";
+			}
+			this.config(id, job.packageRevision, config);
+			controller.signal.throwIfAborted();
+			if (this.get(id, owner)?.id !== job.id || this.get(id, owner)?.state === "cancelled") throw new Error("Setup changed");
+			this.write(job);
+		} catch {
+			const current = this.get(id, owner);
+			if (!controller.signal.aborted && current?.id === job.id && current.revision === job.revision && current.state !== "cancelled" && (this.store.pending(id) ?? this.store.get(id))?.receipt.revision === job.packageRevision) {
+				job.state = "failed";
+				if (job.resources !== "ready") job.resources = "error";
+				job.error = "Preparation failed. Retry after checking resources and connections.";
+				this.write(job);
+			}
+		} finally {
+			clearInterval(cancellationPoll);
+			running.delete(this.key(id));
+		}
+		const latest = this.get(id, owner);
+		if (!latest) throw new Error("Setup was removed");
+		return latest;
+	}
+};
+//#endregion
+export { PluginSetupService, setupActionSchema };

package/dist/src/extensions/agent-plugins/source-catalog.d.ts

@@ -0,0 +1,21 @@
+export interface PluginCandidate {
+    name: string;
+    source: string;
+    description?: string;
+}
+export declare class PluginSourceRedirect extends Error {
+    readonly source: string;
+    constructor(source: string);
+}
+export declare class PluginSelectionRequired extends Error {
+    readonly candidates: PluginCandidate[];
+    constructor(candidates: PluginCandidate[]);
+}
+export declare const isGitPluginSource: (source: string) => boolean;
+/** Fetch and validate a fixed tree without running hooks, submodules or package scripts. */
+export declare function withCatalogSource<T>(source: string, fn: (local: string, metadata: {
+    origin: string;
+    commit?: string;
+    importManifest?: Record<string, unknown>;
+}) => T | Promise<T>): Promise<T>;
+export declare const pluginSourceKey: (source: string) => string;

package/dist/src/extensions/agent-plugins/source-catalog.js

@@ -0,0 +1,175 @@
+import { PLUGIN_MANIFEST_PATHS } from "./formats.js";
+import { containedPath } from "./validation.js";
+import { runExec } from "../../infra/exec.js";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/extensions/agent-plugins/source-catalog.ts
+var PluginSourceRedirect = class extends Error {
+	constructor(source) {
+		super("Resolve marketplace plugin source");
+		this.source = source;
+	}
+};
+var PluginSelectionRequired = class extends Error {
+	constructor(candidates) {
+		super("Select a plugin from this marketplace.");
+		this.candidates = candidates;
+	}
+};
+const isGitPluginSource = (source) => /^(git\+https:\/\/|git\+ssh:\/\/|github:)/.test(source) || /^https:\/\/github\.com\/[^/]+\/[^/#]+(?:\.git)?(?:#.*)?$/.test(source);
+/** Fetch and validate a fixed tree without running hooks, submodules or package scripts. */
+async function withCatalogSource(source, fn) {
+	const [origin, fragment = ""] = source.split("#", 2);
+	const options = new URLSearchParams(fragment);
+	const plugin = options.get("plugin");
+	const subdir = options.get("path") ?? ".";
+	const temp = isGitPluginSource(source) ? mkdtempSync(join(tmpdir(), "xopc-plugin-git-")) : void 0;
+	try {
+		let root = origin;
+		let commit;
+		if (temp) {
+			let url = origin.replace(/^git\+/, "").replace(/^github:([^/]+\/[^/]+)$/, "https://github.com/$1.git");
+			const parsed = new URL(url);
+			if (!["https:", "ssh:"].includes(parsed.protocol) || parsed.password || parsed.search || parsed.protocol === "https:" && parsed.username) throw new Error("Use an HTTPS or SSH Git repository without embedded credentials");
+			if (parsed.protocol === "ssh:" && (!/^[A-Za-z0-9][A-Za-z0-9.-]*$/.test(parsed.hostname) || parsed.username && !/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(parsed.username))) throw new Error("Invalid SSH repository host or user");
+			url = parsed.href;
+			const ref = options.get("ref") ?? "HEAD";
+			if (!/^[A-Za-z0-9][A-Za-z0-9_./-]{0,199}$/.test(ref) || ref.includes("..")) throw new Error("Invalid Git reference");
+			const env = {
+				...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+				GIT_CONFIG_NOSYSTEM: "1",
+				GIT_TERMINAL_PROMPT: "0",
+				GIT_CONFIG_GLOBAL: "/dev/null"
+			};
+			const run = (args) => runExec("git", [
+				"-c",
+				"core.hooksPath=/dev/null",
+				"-c",
+				"protocol.file.allow=never",
+				...args
+			], {
+				cwd: temp,
+				env,
+				timeoutMs: 3e4,
+				maxBuffer: 1024 * 1024
+			});
+			await run(["init", "--quiet"]);
+			await run([
+				"fetch",
+				"--depth=1",
+				"--no-tags",
+				"--",
+				url,
+				ref
+			]);
+			commit = (await run([
+				"rev-parse",
+				"--verify",
+				"FETCH_HEAD^{commit}"
+			])).stdout.trim();
+			const inventory = (await run([
+				"ls-tree",
+				"-r",
+				"-l",
+				commit
+			])).stdout.trim().split("\n").filter(Boolean);
+			let expandedBytes = 0;
+			if (inventory.length > 1e4) throw new Error("Git package exceeds file limit");
+			for (const line of inventory) {
+				const item = /^(100644|100755) blob [a-f0-9]+\s+(\d+)\t/.exec(line);
+				if (!item) throw new Error("Git symlinks and submodules are not supported");
+				expandedBytes += Number(item[2]);
+				if (expandedBytes > 100 * 1024 * 1024) throw new Error("Git package exceeds 100 MiB");
+			}
+			await run([
+				"-c",
+				"core.symlinks=false",
+				"checkout",
+				"--force",
+				"--detach",
+				commit
+			]);
+			rmSync(join(temp, ".git"), {
+				recursive: true,
+				force: true
+			});
+			root = temp;
+		}
+		root = containedPath(root, join(root, subdir));
+		let importManifest;
+		const catalog = options.get("package") === "1" ? void 0 : [".agents/plugins/marketplace.json", ".claude-plugin/marketplace.json"].map((p) => join(root, p)).find(existsSync);
+		if (catalog) {
+			if (statSync(catalog).size > 1024 * 1024) throw new Error("Marketplace exceeds 1 MiB");
+			const manifest = JSON.parse(readFileSync(containedPath(root, catalog), "utf8"));
+			if (!Array.isArray(manifest.plugins) || manifest.plugins.length > 1e3) throw new Error("Invalid marketplace plugin list");
+			const entries = manifest.plugins;
+			if (!plugin) throw new PluginSelectionRequired(entries.map((entry) => ({
+				name: String(entry.name),
+				description: typeof entry.description === "string" ? entry.description : void 0,
+				source: `${origin}#${new URLSearchParams({
+					...Object.fromEntries(options),
+					plugin: String(entry.name)
+				})}`
+			})));
+			const matches = entries.filter((entry) => entry.name === plugin);
+			if (matches.length !== 1) throw new Error("Marketplace plugin is missing or ambiguous");
+			const entry = matches[0];
+			const refSource = entry.source;
+			let rel = typeof refSource === "string" ? refSource : void 0;
+			if (refSource && typeof refSource === "object") {
+				const local = refSource;
+				if (local.source === "local") rel = local.path;
+				if (local.source === "url" && typeof local.url === "string" && local.url.startsWith("./")) rel = local.url;
+			}
+			if (typeof refSource === "object" && refSource) {
+				const remote = refSource;
+				if (rel === void 0 && (remote.source === "github" || remote.source === "url" || remote.source === "git-subdir")) {
+					const target = remote.source === "github" ? `github:${remote.repo}` : `git+${remote.url}`;
+					const query = new URLSearchParams({ package: "1" });
+					if (typeof remote.sha === "string" || typeof remote.ref === "string") query.set("ref", String(remote.sha ?? remote.ref));
+					if (remote.source === "git-subdir" && typeof remote.path === "string") query.set("path", remote.path);
+					throw new PluginSourceRedirect(`${target}#${query}`);
+				}
+			}
+			if (typeof rel !== "string" || !rel.startsWith("./") && rel !== ".") throw new Error("This marketplace source type is not supported; install its repository or archive directly");
+			root = containedPath(root, join(root, rel));
+			const hasManifest = PLUGIN_MANIFEST_PATHS.some((path) => existsSync(join(root, path)));
+			if (hasManifest && [
+				"skills",
+				"mcpServers",
+				"hooks",
+				"commands",
+				"agents"
+			].some((key) => entry[key] !== void 0)) throw new Error("Marketplace component overlays are not supported by this compatibility version");
+			if (!hasManifest && catalog.endsWith(".claude-plugin/marketplace.json")) importManifest = Object.fromEntries(Object.entries(entry).filter(([key]) => ![
+				"source",
+				"strict",
+				"category",
+				"tags"
+			].includes(key)));
+		} else if (plugin) throw new Error("No marketplace found at this source");
+		return await fn(root, {
+			origin: source,
+			commit,
+			importManifest
+		});
+	} finally {
+		if (temp) rmSync(temp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+const pluginSourceKey = (source) => {
+	if (source.startsWith("store:")) return createHash("sha256").update(source.replace(/@[^/]+$/, "")).digest("hex").slice(0, 12);
+	const [origin, fragment = ""] = source.split("#", 2);
+	const params = new URLSearchParams(fragment);
+	params.delete("ref");
+	params.sort();
+	const canonical = (/^(?:github:|git\+|https:\/\/)/.test(origin) ? origin : existsSync(origin) ? realpathSync(origin) : resolve(origin)).replace(/^git\+/, "").replace(/^github:([^/]+\/[^/]+)$/, "https://github.com/$1").replace(/\.git$/, "").replace(/\/$/, "");
+	return createHash("sha256").update(`${canonical}#${params}`).digest("hex").slice(0, 12);
+};
+//#endregion
+export { PluginSelectionRequired, PluginSourceRedirect, isGitPluginSource, pluginSourceKey, withCatalogSource };