@xopcai/xopc 0.0.308 → 0.0.311

package/dist/src/connectors/cli/adapters/wps365.d.ts

@@ -0,0 +1,2 @@
+import type { CliAdapter } from '../types.js';
+export declare const wps365Adapter: CliAdapter;

package/dist/src/connectors/cli/adapters/wps365.js

@@ -0,0 +1,115 @@
+import { CliProtocolError, actionRevision, closedSchema, object, parseJson } from "../protocol.js";
+import { WPS365_DISTRIBUTIONS } from "../distributions.js";
+import { actions, assets, version } from "./wps365/bundle.js";
+//#region src/connectors/cli/adapters/wps365.ts
+function decodeAuthorization(output) {
+	if (output.exitCode !== 0) decodeResult(output);
+}
+const contracts = new Map(actions.map((action) => [action.id, action]));
+const staticActions = Object.fromEntries(actions.map((action) => [action.id, {
+	id: action.id,
+	description: `WPS 365: ${action.description}`,
+	scope: "read",
+	requiredScopes: [],
+	inputSchema: closedSchema(action.inputSchema),
+	revision: actionRevision({
+		action,
+		specs: assets.map((asset) => asset.sha256),
+		version
+	})
+}]));
+function decodeResult(output) {
+	if (output.exitCode !== 0) {
+		const diagnostic = `${output.stdout}\n${output.stderr}`;
+		if (/403000001|ErrPrivileges|interface_company_doc/.test(diagnostic)) throw new Error("WPS enterprise subscription does not include this capability. Contact the enterprise administrator; reconnecting will not resolve it.");
+		if (/not logged in|invalid_grant|expired|revoked/i.test(diagnostic)) throw new Error("WPS user authorization is unavailable or expired. Reconnect this account.");
+		if (/scope|permission|forbidden/i.test(diagnostic)) throw new Error("WPS permission is missing. Check application publication, administrator approval and data access scope.");
+		throw new Error(`WPS command failed (exit ${output.exitCode}). Check connection and enterprise permissions.`);
+	}
+	const row = object(parseJson(output.stdout));
+	if (typeof row.code !== "number") throw new CliProtocolError("Missing WPS response status.");
+	if (row.code !== 0) {
+		if (row.code === 403000001) throw new Error("WPS enterprise subscription does not include this capability. Contact the enterprise administrator.");
+		throw new Error(`WPS rejected the request (code ${row.code}). Check enterprise permissions.`);
+	}
+	if (!("data" in row)) throw new CliProtocolError("Missing WPS response data.");
+	return row.data;
+}
+const wps365Adapter = {
+	id: "wps365",
+	version: "1",
+	binaryVersion: version,
+	executable: "wps365-cli",
+	distributions: WPS365_DISTRIBUTIONS,
+	configEnvironment: "WPS365_CONFIG_DIR",
+	environment: { WPS365_KEYRING_BACKEND: "file" },
+	configAssets: assets,
+	staticActions,
+	curatedActions: Object.fromEntries(actions.map((action) => [action.id, "read"])),
+	schemaArgs: () => {
+		throw new Error("WPS uses packaged action contracts.");
+	},
+	decodeSchema: () => {
+		throw new Error("WPS uses packaged action contracts.");
+	},
+	actionArgs(action, input) {
+		const contract = contracts.get(action.id);
+		if (!contract) throw new Error("WPS action is not enabled.");
+		const args = [
+			...contract.command,
+			"--token-type",
+			"delegated",
+			"--output",
+			"json"
+		];
+		for (const [name, value] of Object.entries(input)) {
+			if (!(name in contract.inputSchema.properties) || name === "token_type") throw new Error("Unsupported WPS argument.");
+			if (!contract.positionals.includes(name)) args.push(`--${name}=${Array.isArray(value) ? value.join(",") : String(value)}`);
+		}
+		if (contract.positionals.length) args.push("--", ...contract.positionals.map((name) => String(input[name])));
+		return args;
+	},
+	decodeResult,
+	statusArgs: [
+		"user",
+		"me",
+		"--token-type",
+		"delegated",
+		"--output",
+		"json"
+	],
+	decodeIdentity(output) {
+		if (output.timedOut || output.aborted || output.outputTruncated) throw new Error("WPS identity verification did not complete.");
+		const user = object(decodeResult(output));
+		if (typeof user.id !== "string" || !user.id || typeof user.company_id !== "string" || !user.company_id) throw new CliProtocolError("Missing WPS user or enterprise identity.");
+		return {
+			key: `${user.company_id}:${user.id}`,
+			label: typeof user.user_name === "string" ? user.user_name : user.id,
+			scopes: [],
+			identity: {
+				userId: user.id,
+				companyId: user.company_id,
+				name: user.user_name,
+				kind: "user"
+			}
+		};
+	},
+	authorizationSteps: [{
+		decodeResult: decodeAuthorization,
+		initialOnly: true,
+		args: ["config", "init"],
+		challenge: "url",
+		urlHosts: ["open.wps.cn", "openapi.wps.cn"]
+	}, {
+		decodeResult: decodeAuthorization,
+		args: [
+			"auth",
+			"login",
+			"--device"
+		],
+		challenge: "url",
+		urlHosts: ["open.wps.cn", "openapi.wps.cn"]
+	}]
+};
+//#endregion
+export { wps365Adapter };

package/dist/src/connectors/cli/assets.d.ts

@@ -0,0 +1,3 @@
+import type { CliAdapter } from './types.js';
+/** Install immutable, packaged provider specifications without touching credentials. */
+export declare function prepareCliAssets(adapter: CliAdapter, configPath: string): Promise<void>;

package/dist/src/connectors/cli/assets.js

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+//#region src/connectors/cli/assets.ts
+const digest = (content) => createHash("sha256").update(content).digest("hex");
+/** Install immutable, packaged provider specifications without touching credentials. */
+async function prepareCliAssets(adapter, configPath) {
+	if (!adapter.configAssets?.length) return;
+	const root = await lstat(configPath);
+	if (!root.isDirectory() || root.isSymbolicLink()) throw new Error("Invalid CLI config directory.");
+	for (const asset of adapter.configAssets) {
+		const parts = asset.path.split("/");
+		if (!parts.length || parts.some((part) => !/^[a-zA-Z0-9_.-]+$/.test(part) || part === "." || part === "..") || digest(asset.content) !== asset.sha256) throw new Error("Invalid packaged CLI asset.");
+		let parent = configPath;
+		for (const part of parts.slice(0, -1)) {
+			parent = join(parent, part);
+			await mkdir(parent, {
+				recursive: true,
+				mode: 448
+			});
+			const info = await lstat(parent);
+			if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Invalid CLI asset directory.");
+		}
+		const path = join(configPath, asset.path);
+		const temporary = join(parent, `.asset-${randomUUID()}`);
+		try {
+			await writeFile(temporary, asset.content, {
+				flag: "wx",
+				mode: 384
+			});
+			try {
+				await link(temporary, path);
+			} catch (error) {
+				if (error.code !== "EEXIST") throw error;
+			}
+		} finally {
+			await rm(temporary, { force: true });
+		}
+		const info = await lstat(path);
+		if (!info.isFile() || info.isSymbolicLink() || info.size > Buffer.byteLength(asset.content) || digest(await readFile(path, "utf8")) !== asset.sha256) throw new Error("CLI specification integrity mismatch. Reconnect using a new account context.");
+	}
+}
+//#endregion
+export { prepareCliAssets };

package/dist/src/connectors/cli/authorization.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from '../../config/schema.js';
+import type { CliAdapter } from './types.js';
+export declare function requireCliInstance(config: Config, instanceId: string, options?: {
+    allowDisabled?: boolean;
+}): CliAdapter;
+export declare function extractAuthorizationUrl(text: string, allowedHosts: readonly string[], field?: string): string | undefined;
+export declare function startCliAuthorization(config: Config, instanceId: string, expectedAccountId?: string): {
+    id: string;
+    status: "failed" | "succeeded" | "expired" | "cancelled" | "verifying" | "awaiting_user" | "preparing";
+    challenge: import("./types.js").CliChallenge;
+    error: string;
+    accountId: string;
+    expiresAt: number;
+};
+export declare function cancelCliAuthorization(id: string): void;
+export declare function cancelCliInstanceAuthorizations(instanceId: string): void;

package/dist/src/connectors/cli/authorization.js

@@ -0,0 +1,184 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { getConnectorAccount, init_connector_account_repository } from "../../storage/sqlite/connector-account-repository.js";
+import { getConnectorConnection, getConnectorInstallation, init_connector_repository, upsertConnectorInstallation } from "../../storage/sqlite/connector-repository.js";
+import { cliContextPath, startCliProcess } from "./process.js";
+import { getCliAdapter } from "./adapterRegistry.js";
+import { getConnectorInstance, getInstalledConnectorDefinition } from "../instances.js";
+import { verifyInstalledCli } from "./installer.js";
+import { cliAuthorizationView, commitCliIdentity, createCliAuthorization, readCliAuthorization, updateCliAuthorization } from "./store.js";
+import { join, relative } from "node:path";
+import { cp, rm, stat } from "node:fs/promises";
+//#region src/connectors/cli/authorization.ts
+init_connector_repository();
+init_connector_account_repository();
+init_logger();
+const log = createLogger("CliConnectorAuth");
+const controllers = /* @__PURE__ */ new Map();
+function requireCliInstance(config, instanceId, options = {}) {
+	const instance = getConnectorInstance(config, instanceId);
+	const definition = getInstalledConnectorDefinition(config, instanceId);
+	if (!instance || !options.allowDisabled && !instance.enabled || definition?.runtime.type !== "cli") throw new Error("CLI connector is not installed or is disabled.");
+	const adapter = getCliAdapter(definition.runtime.adapterId);
+	if (definition.runtime.adapterVersion !== adapter.version || definition.runtime.binaryVersion !== adapter.binaryVersion) throw new Error("CLI connector version does not match its adapter. Reinstall the connector.");
+	return adapter;
+}
+function extractAuthorizationUrl(text, allowedHosts, field) {
+	const candidates = [];
+	if (field) for (const line of text.split("\n")) try {
+		const event = JSON.parse(line);
+		if (typeof event?.[field] === "string") candidates.push(event[field]);
+	} catch {}
+	else for (const match of text.matchAll(/https:\/\/[^\s"<>\\]+(?=[\s"<>])/g)) candidates.push(match[0]);
+	for (const candidate of candidates) try {
+		const url = new URL(candidate);
+		if (url.protocol === "https:" && !url.port && allowedHosts.includes(url.hostname) && !url.username && !url.password) return url.href;
+	} catch {}
+}
+async function authorize(adapter, attempt, signal) {
+	let committed = false;
+	try {
+		const executable = await verifyInstalledCli(adapter);
+		const previous = attempt.expected_account_id ? getConnectorAccount(attempt.expected_account_id) : void 0;
+		const previousConnection = previous?.currentConnectionId ? getConnectorConnection(previous.currentConnectionId) : void 0;
+		if (previousConnection) {
+			if (previousConnection.provider !== "cli" || previousConnection.metadata.runtimeInstanceId !== attempt.instance_id) throw new Error("Account belongs to another CLI instance.");
+			await cp(cliContextPath(String(previousConnection.metadata.contextId)), cliContextPath(attempt.context_id), {
+				recursive: true,
+				errorOnExist: true,
+				force: false,
+				filter: (source) => relative(cliContextPath(String(previousConnection.metadata.contextId)), source) !== "files"
+			});
+		}
+		const steps = previousConnection ? adapter.authorizationSteps.filter((step) => !step.initialOnly) : adapter.authorizationSteps;
+		for (const [index, step] of steps.entries()) {
+			const progress = {
+				step: index + 1,
+				totalSteps: steps.length
+			};
+			signal.throwIfAborted();
+			updateCliAuthorization(attempt.id, { phase: "preparing" });
+			let output = "";
+			let challengePublished = false;
+			const handle = await startCliProcess({
+				adapter,
+				executable,
+				contextId: attempt.context_id,
+				args: step.args,
+				signal,
+				timeoutMs: Math.max(1, attempt.expires_at - Date.now()),
+				onOutput(_stream, chunk) {
+					if (step.challenge !== "url" || challengePublished) return;
+					output = (output + chunk.toString("utf8")).slice(-32768);
+					const url = extractAuthorizationUrl(output, step.urlHosts ?? [], step.urlField);
+					if (url) challengePublished = updateCliAuthorization(attempt.id, {
+						phase: "awaiting_user",
+						challenge: {
+							type: "open_url",
+							url,
+							...progress
+						}
+					});
+				}
+			});
+			const qrTimer = step.challenge === "qr" ? setInterval(() => {
+				if (challengePublished) return;
+				stat(join(cliContextPath(attempt.context_id), "files", "authorization.png")).then((info) => {
+					if (info.isFile() && info.size > 0 && !signal.aborted) challengePublished = updateCliAuthorization(attempt.id, {
+						phase: "awaiting_user",
+						challenge: {
+							type: "qr_code",
+							artifactId: attempt.id,
+							...progress
+						}
+					});
+				}).catch(() => void 0);
+			}, 300) : void 0;
+			let result;
+			try {
+				result = await handle.completion;
+			} finally {
+				if (qrTimer) clearInterval(qrTimer);
+			}
+			if (!step.decodeResult && result.exitCode !== 0 || result.timedOut || result.aborted || result.outputTruncated) {
+				log.warn({
+					attemptId: attempt.id,
+					step: index + 1,
+					exitCode: result.exitCode,
+					timedOut: result.timedOut,
+					aborted: result.aborted,
+					outputTruncated: result.outputTruncated
+				}, "CLI authorization step did not complete");
+				throw new Error(`Authorization step ${index + 1}/${steps.length} ${result.timedOut ? "timed out" : "failed"}. Retry authorization.`);
+			}
+			step.decodeResult?.(result);
+		}
+		signal.throwIfAborted();
+		if (!updateCliAuthorization(attempt.id, { phase: "verifying" })) throw new Error("Authorization was cancelled.");
+		const probe = await startCliProcess({
+			adapter,
+			executable,
+			contextId: attempt.context_id,
+			args: adapter.statusArgs,
+			signal
+		});
+		const identity = adapter.decodeIdentity(await probe.completion);
+		signal.throwIfAborted();
+		commitCliIdentity(attempt, identity);
+		committed = true;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Authorization failed.";
+		updateCliAuthorization(attempt.id, {
+			phase: signal.aborted ? "cancelled" : "failed",
+			error: message
+		});
+		log.warn({
+			attemptId: attempt.id,
+			connectorId: attempt.connector_id,
+			errorMessage: message
+		}, "CLI authorization did not complete");
+	} finally {
+		controllers.delete(attempt.id);
+		if (!committed) await rm(cliContextPath(attempt.context_id), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function startCliAuthorization(config, instanceId, expectedAccountId) {
+	const adapter = requireCliInstance(config, instanceId);
+	const definition = getInstalledConnectorDefinition(config, instanceId);
+	if (expectedAccountId) {
+		const account = getConnectorAccount(expectedAccountId);
+		if (!account || account.connectorId !== definition.id) throw new Error("Invalid account.");
+	}
+	const installationId = `${definition.id}-local-owner`;
+	if (!getConnectorInstallation(installationId)) upsertConnectorInstallation({
+		id: installationId,
+		connectorId: definition.id,
+		principalId: "local-owner",
+		enabled: true,
+		allowedAgentIds: [],
+		maxScope: "read",
+		confirmationPolicy: "writes",
+		selectedAccountIds: null
+	});
+	const attempt = createCliAuthorization(instanceId, definition.id, expectedAccountId);
+	const controller = new AbortController();
+	controllers.set(attempt.id, controller);
+	authorize(adapter, attempt, controller.signal).catch((error) => log.error({
+		err: error,
+		attemptId: attempt.id
+	}, "CLI authorization cleanup failed"));
+	return cliAuthorizationView(attempt);
+}
+function cancelCliAuthorization(id) {
+	if (!readCliAuthorization(id)) throw new Error("Authorization not found.");
+	updateCliAuthorization(id, { phase: "cancelled" });
+	controllers.get(id)?.abort();
+}
+function cancelCliInstanceAuthorizations(instanceId) {
+	for (const id of controllers.keys()) if (readCliAuthorization(id)?.instance_id === instanceId) cancelCliAuthorization(id);
+}
+//#endregion
+export { cancelCliAuthorization, cancelCliInstanceAuthorizations, extractAuthorizationUrl, requireCliInstance, startCliAuthorization };

package/dist/src/connectors/cli/distributions.d.ts

@@ -0,0 +1,4 @@
+import type { CliDistribution } from './types.js';
+export declare const LARK_DISTRIBUTIONS: Record<string, CliDistribution>;
+export declare const WECOM_DISTRIBUTIONS: Record<string, CliDistribution>;
+export declare const WPS365_DISTRIBUTIONS: Record<string, CliDistribution>;

package/dist/src/connectors/cli/distributions.js

@@ -0,0 +1,69 @@
+//#region src/connectors/cli/distributions.ts
+const LARK_DISTRIBUTIONS = {
+	"darwin-x64": {
+		"url": "https://github.com/larksuite/cli/releases/download/v1.0.96/lark-cli-1.0.96-darwin-amd64.tar.gz",
+		"integrity": "sha256-f6bd28263dfc4a4d6c2581657efa6af8e8f92eba22394c9c4d840d4ad1fae65e",
+		"archiveEntry": "lark-cli"
+	},
+	"darwin-arm64": {
+		"url": "https://github.com/larksuite/cli/releases/download/v1.0.96/lark-cli-1.0.96-darwin-arm64.tar.gz",
+		"integrity": "sha256-124acdf380f72fa4b1b1e8307a0b00ee93217cf9558baca5bc40091304f2adcd",
+		"archiveEntry": "lark-cli"
+	},
+	"linux-x64": {
+		"url": "https://github.com/larksuite/cli/releases/download/v1.0.96/lark-cli-1.0.96-linux-amd64.tar.gz",
+		"integrity": "sha256-5d1fa96832307b13298fdb11c477ab3f31c3e98026fec585b4b2eb7f63960c36",
+		"archiveEntry": "lark-cli"
+	},
+	"linux-arm64": {
+		"url": "https://github.com/larksuite/cli/releases/download/v1.0.96/lark-cli-1.0.96-linux-arm64.tar.gz",
+		"integrity": "sha256-a83124bad70ddb5a42c8d10a80e8d52f49913b1cb397c7a0a835bd0ddb65f3e2",
+		"archiveEntry": "lark-cli"
+	}
+};
+const WECOM_DISTRIBUTIONS = {
+	"linux-x64": {
+		"url": "https://registry.npmjs.org/@wecom/cli-linux-x64/-/cli-linux-x64-1.3.0.tgz",
+		"integrity": "sha512-kJOub+Gg+wa+K4f21pDyrLtaZK/cPOSrYkm1iST/PfrK66urNKHv7GIEtRUcD4WvKL7yxfyl+QwxyNsMixLAAA==",
+		"archiveEntry": "package/bin/wecom-cli"
+	},
+	"darwin-arm64": {
+		"url": "https://registry.npmjs.org/@wecom/cli-darwin-arm64/-/cli-darwin-arm64-1.3.0.tgz",
+		"integrity": "sha512-DXMSKg3YOF+raHyFeTIFncq3njViWV2dpGltrFvC3Ao6inUFPAbw5mHtgEMFZLlCprmeKshhhOAetn5TqiugjQ==",
+		"archiveEntry": "package/bin/wecom-cli"
+	},
+	"darwin-x64": {
+		"url": "https://registry.npmjs.org/@wecom/cli-darwin-x64/-/cli-darwin-x64-1.3.0.tgz",
+		"integrity": "sha512-j4Uak8gVfT9/lwDCSwT6RqTKED5YLM818I/DL5U66U45gFds/ztMzWKjmpYbRs7uxE1NzQli/H2/WmD6G27OAg==",
+		"archiveEntry": "package/bin/wecom-cli"
+	},
+	"linux-arm64": {
+		"url": "https://registry.npmjs.org/@wecom/cli-linux-arm64/-/cli-linux-arm64-1.3.0.tgz",
+		"integrity": "sha512-t2Mww45xF9E2AEO7hWMKfsynLljfnn4ngVcDGljGIhm306wNBheMU7F6n/HNVwu8fNL76uPIH+eoYyL7EVxf+w==",
+		"archiveEntry": "package/bin/wecom-cli"
+	}
+};
+const WPS365_DISTRIBUTIONS = {
+	"darwin-arm64": {
+		url: "https://github.com/wps365-open/cli/releases/download/v0.3.6/wps365-cli-aarch64-apple-darwin.tar.gz",
+		integrity: "sha256-2605dab1a208327e3fc3b739d589c878ad17c7a22a133dd26171e76c6f81c08f",
+		archiveEntry: "wps365-cli"
+	},
+	"linux-arm64": {
+		url: "https://github.com/wps365-open/cli/releases/download/v0.3.6/wps365-cli-aarch64-unknown-linux-gnu.tar.gz",
+		integrity: "sha256-f9de5dc0a0e5a682bd53c9df8e21196a6090b308db2c339b516f6389ecea0ab3",
+		archiveEntry: "wps365-cli"
+	},
+	"darwin-x64": {
+		url: "https://github.com/wps365-open/cli/releases/download/v0.3.6/wps365-cli-x86_64-apple-darwin.tar.gz",
+		integrity: "sha256-d7c63d3e59446bf0a27361282a7751a818791752bcb8c9b478cb937ff8216f33",
+		archiveEntry: "wps365-cli"
+	},
+	"linux-x64": {
+		url: "https://github.com/wps365-open/cli/releases/download/v0.3.6/wps365-cli-x86_64-unknown-linux-gnu.tar.gz",
+		integrity: "sha256-68b955a8488edcb82ed5373752a937d9ec3588abfb550223dda3d6f0c1a27588",
+		archiveEntry: "wps365-cli"
+	}
+};
+//#endregion
+export { LARK_DISTRIBUTIONS, WECOM_DISTRIBUTIONS, WPS365_DISTRIBUTIONS };

package/dist/src/connectors/cli/installer.d.ts

@@ -0,0 +1,5 @@
+import type { CliAdapter } from './types.js';
+export declare function verifyIntegrity(bytes: Buffer, integrity: string): void;
+export declare function cliExecutablePath(adapter: CliAdapter): string;
+export declare function verifyInstalledCli(adapter: CliAdapter): Promise<string>;
+export declare function installCli(adapter: CliAdapter): Promise<string>;

package/dist/src/connectors/cli/installer.js

@@ -0,0 +1,102 @@
+import { runProcess } from "../../process/run-process.js";
+import { cliRoot } from "./process.js";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+//#region src/connectors/cli/installer.ts
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+const installs = /* @__PURE__ */ new Map();
+function verifyIntegrity(bytes, integrity) {
+	const match = /^(sha256|sha512)-(.+)$/.exec(integrity);
+	if (!match) throw new Error("Unsupported CLI integrity format.");
+	const expected = match[2];
+	if (createHash(match[1]).update(bytes).digest(match[1] === "sha256" ? "hex" : "base64") !== expected) throw new Error("CLI distribution integrity mismatch.");
+}
+function cliExecutablePath(adapter) {
+	return join(cliRoot(), "runtimes", adapter.id, adapter.binaryVersion, `${process.platform}-${process.arch}`, adapter.executable);
+}
+async function verifyInstalledCli(adapter) {
+	const path = cliExecutablePath(adapter);
+	const [binary, digest] = await Promise.all([readFile(path), readFile(`${path}.sha256`, "utf8")]);
+	verifyIntegrity(binary, `sha256-${digest.trim()}`);
+	return path;
+}
+async function install(adapter) {
+	const distribution = adapter.distributions[`${process.platform}-${process.arch}`];
+	if (!distribution) throw new Error(`Unsupported CLI platform: ${process.platform}-${process.arch}.`);
+	const url = new URL(distribution.url);
+	if (url.protocol !== "https:" || !["github.com", "registry.npmjs.org"].includes(url.hostname)) throw new Error("Untrusted CLI distribution URL.");
+	try {
+		return await verifyInstalledCli(adapter);
+	} catch {}
+	const directory = join(cliRoot(), "runtimes", adapter.id, adapter.binaryVersion, `${process.platform}-${process.arch}`);
+	await mkdir(directory, {
+		recursive: true,
+		mode: 448
+	});
+	const staging = join(directory, `.install-${randomUUID()}`);
+	await mkdir(staging, { mode: 448 });
+	try {
+		const response = await fetch(url, { signal: AbortSignal.timeout(9e4) });
+		if (!response.ok || !response.body) throw new Error(`CLI download failed (${response.status}).`);
+		const chunks = [];
+		let size = 0;
+		for await (const chunk of response.body) {
+			size += chunk.length;
+			if (size > MAX_ARCHIVE_BYTES) throw new Error("CLI distribution exceeds size limit.");
+			chunks.push(Buffer.from(chunk));
+		}
+		const bytes = Buffer.concat(chunks);
+		verifyIntegrity(bytes, distribution.integrity);
+		const archive = join(staging, "archive.tgz");
+		await writeFile(archive, bytes, { mode: 384 });
+		const binaryChunks = [];
+		let binaryBytes = 0;
+		const extracted = await runProcess({
+			program: "tar",
+			args: [
+				"-xOf",
+				archive,
+				distribution.archiveEntry
+			],
+			maxOutputBytes: MAX_ARCHIVE_BYTES,
+			timeoutMs: 3e4,
+			terminationPolicy: "tree",
+			onOutput(stream, chunk) {
+				if (stream !== "stdout") return;
+				binaryBytes += chunk.length;
+				if (binaryBytes <= MAX_ARCHIVE_BYTES) binaryChunks.push(Buffer.from(chunk));
+			}
+		});
+		if (extracted.exitCode !== 0 || extracted.outputTruncated || binaryBytes > MAX_ARCHIVE_BYTES) throw new Error("CLI archive extraction failed.");
+		const binary = Buffer.concat(binaryChunks);
+		const executable = cliExecutablePath(adapter);
+		const temporary = join(staging, adapter.executable);
+		await writeFile(temporary, binary, { mode: 448 });
+		await chmod(temporary, 448);
+		const probe = await runProcess({
+			program: temporary,
+			args: ["--version"],
+			timeoutMs: 1e4
+		});
+		if (probe.exitCode !== 0 || !probe.stdout.includes(adapter.binaryVersion)) throw new Error("CLI version verification failed.");
+		await writeFile(`${executable}.sha256`, createHash("sha256").update(binary).digest("hex"), { mode: 384 });
+		await rename(temporary, executable);
+		return executable;
+	} finally {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function installCli(adapter) {
+	const key = cliExecutablePath(adapter);
+	const pending = installs.get(key);
+	if (pending) return pending;
+	const operation = install(adapter).finally(() => installs.delete(key));
+	installs.set(key, operation);
+	return operation;
+}
+//#endregion
+export { cliExecutablePath, installCli, verifyInstalledCli, verifyIntegrity };

package/dist/src/connectors/cli/lifecycle.d.ts

@@ -0,0 +1 @@
+export declare function stopCliInstance(instanceId: string, disconnect?: boolean): void;

package/dist/src/connectors/cli/lifecycle.js

@@ -0,0 +1,19 @@
+import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { listConnectorConnections, upsertConnectorConnection } from "../../storage/sqlite/connector-repository.js";
+import "../../storage/sqlite/index.js";
+import { cancelCliContext } from "./process.js";
+import { cancelCliInstanceAuthorizations } from "./authorization.js";
+//#region src/connectors/cli/lifecycle.ts
+function stopCliInstance(instanceId, disconnect = false) {
+	cancelCliInstanceAuthorizations(instanceId);
+	if (!isXopcDatabaseOpen()) return;
+	for (const connection of listConnectorConnections().filter((item) => item.provider === "cli" && item.metadata.runtimeInstanceId === instanceId)) {
+		cancelCliContext(String(connection.metadata.contextId));
+		if (disconnect) upsertConnectorConnection({
+			...connection,
+			status: "disabled"
+		});
+	}
+}
+//#endregion
+export { stopCliInstance };

package/dist/src/connectors/cli/process.d.ts

@@ -0,0 +1,18 @@
+import type { ProcessHandle } from '../../process/process-spec.js';
+import type { CliAdapter } from './types.js';
+export declare function cancelCliContext(contextId: string): void;
+export declare function cliRoot(): string;
+export declare function cliContextPath(id: string): string;
+export declare function cliEnvironment(adapter: CliAdapter, contextPath: string): NodeJS.ProcessEnv;
+export declare function startCliProcess(options: {
+    adapter: CliAdapter;
+    executable: string;
+    contextId: string;
+    args: string[];
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    beforeSpawn?: () => void;
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
+}): Promise<ProcessHandle>;
+export declare function resolveCliArtifact(contextId: string, filePath: string): Promise<string>;