@f5-sales-demo/xcsh 22.4.5 → 22.4.7

package/src/host/host.ts

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { runCli } from "../person-profile/collectors";
+import { type HostManagement, probeManagement } from "./management";
+
+export interface HostInfo {
+	readonly os: NodeJS.Platform;
+	readonly architecture: string;
+	readonly management: HostManagement;
+	readonly packageManagers: Readonly<Partial<Record<"brew" | "apt" | "winget" | "sudo", string>>>;
+	readonly effectiveUid?: number;
+	readonly sudo: "available" | "unavailable" | "unknown";
+	readonly distribution?: string;
+}
+export function findExecutable(name: string): string | undefined {
+	const path =
+		Bun.which(name, { PATH: process.env.PATH }) ?? Bun.which(join(homedir(), ".local", "bin", name)) ?? undefined;
+	if (path) exposeExecutable(path);
+	return path;
+}
+export async function executableIdentity(path: string): Promise<string> {
+	const target = await realpath(path);
+	const info = await stat(target);
+	return JSON.stringify([
+		path,
+		target,
+		info.dev,
+		info.ino,
+		info.size,
+		info.mtimeMs,
+		info.mode,
+		createHash("sha256")
+			.update(await readFile(target))
+			.digest("hex"),
+	]);
+}
+export function exposeExecutable(path: string): void {
+	const directory = path.slice(0, Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")));
+	const parts = (process.env.PATH ?? "").split(delimiter);
+	if (!parts.includes(directory)) process.env.PATH = [directory, ...parts].join(delimiter);
+}
+export async function getHost(signal?: AbortSignal): Promise<HostInfo> {
+	signal?.throwIfAborted();
+	const managers: Partial<Record<"brew" | "apt" | "winget" | "sudo", string>> = {};
+	for (const [key, name] of [
+		["brew", "brew"],
+		["apt", "apt-get"],
+		["winget", "winget"],
+		["sudo", "sudo"],
+	] as const) {
+		const path = Bun.which(name, { PATH: process.env.PATH });
+		if (path) managers[key] = path;
+	}
+	let distribution: string | undefined;
+	if (process.platform === "linux")
+		try {
+			distribution = (await readFile("/etc/os-release", "utf8")).match(/^ID=["']?([^"'\n]+)["']?/m)?.[1];
+		} catch {
+			/* unknown */
+		}
+	const effectiveUid = process.geteuid?.();
+	const sudoResult =
+		effectiveUid === 0 || !managers.sudo ? undefined : await runCli([managers.sudo, "-n", "-l"], 5000, signal);
+	const management = await probeManagement(signal);
+	signal?.throwIfAborted();
+	return Object.freeze({
+		os: process.platform,
+		architecture: process.arch,
+		management: management.status,
+		packageManagers: Object.freeze(managers),
+		effectiveUid,
+		sudo: effectiveUid === 0 || sudoResult?.exitCode === 0 ? "available" : managers.sudo ? "unknown" : "unavailable",
+		distribution,
+	});
+}
+export const host = Object.freeze({ get: getHost, findExecutable });

package/src/host/management.ts

@@ -0,0 +1,63 @@
+import { $which } from "@f5-sales-demo/pi-utils";
+import { runCli } from "../person-profile/collectors";
+import type { ManagementStatus } from "../person-profile/machine-profile";
+
+export type HostManagement = "managed" | "unmanaged" | "unknown";
+export interface ManagementProbe {
+	status: HostManagement;
+	details: ManagementStatus;
+}
+export function detectMdmVendor(output: string): string | undefined {
+	const names: [RegExp, string][] = [
+		[/jamf/i, "Jamf"],
+		[/intune|microsoft/i, "Intune"],
+		[/mosyle/i, "Mosyle"],
+		[/kandji/i, "Kandji"],
+		[/workspace one|airwatch/i, "Workspace ONE"],
+		[/addigy/i, "Addigy"],
+		[/simplemdm/i, "SimpleMDM"],
+		[/hexnode/i, "Hexnode"],
+	];
+	return names.find(([pattern]) => pattern.test(output))?.[1];
+}
+export function parseEnrollment(code: number, output: string): ManagementProbe {
+	if (code !== 0) return { status: "unknown", details: {} };
+	const match = output.match(/MDM enrollment:\s*(Yes|No)\b/i);
+	if (!match) return { status: "unknown", details: {} };
+	const managed = match[1].toLowerCase() === "yes";
+	const dep = output.match(/Enrolled via DEP:\s*(Yes|No)/i);
+	return {
+		status: managed ? "managed" : "unmanaged",
+		details: {
+			isManaged: managed,
+			...(managed ? { userApproved: output.includes("User Approved") } : {}),
+			...(dep ? { depEnrolled: dep[1].toLowerCase() === "yes" } : {}),
+			...(detectMdmVendor(output) ? { mdmVendor: detectMdmVendor(output) } : {}),
+		},
+	};
+}
+export async function probeManagement(signal?: AbortSignal, platform = process.platform): Promise<ManagementProbe> {
+	if (platform !== "darwin") {
+		// Absence of an agent is not evidence that a host is unmanaged.
+		if (platform === "linux")
+			for (const agent of ["puppet", "chef-client", "salt-minion", "ansible"]) {
+				if ($which(agent)) return { status: "managed", details: { isManaged: true, mdmVendor: agent } };
+			}
+		return { status: "unknown", details: {} };
+	}
+	const result = await runCli(["profiles", "status", "-type", "enrollment"], undefined, signal);
+	const probe = parseEnrollment(result.exitCode, result.stdout);
+	if (!probe.details.mdmVendor && ($which("jamf") || $which("/usr/local/bin/jamf"))) probe.details.mdmVendor = "Jamf";
+	if (probe.details.mdmVendor === "Jamf") {
+		const version = await runCli(["jamf", "version"], undefined, signal);
+		if (version.exitCode === 0) probe.details.mdmVersion = version.stdout.match(/version=([\d.]+)/)?.[1];
+	}
+	if (probe.status === "managed") {
+		const mdm = await runCli(["/usr/libexec/mdmclient", "DumpManagementStatus"], undefined, signal);
+		if (mdm.exitCode === 0) {
+			if (mdm.stdout.includes("DeviceIsSupervised = 1")) probe.details.isSupervised = true;
+			probe.details.organizationName = mdm.stdout.match(/OrganizationName\s*=\s*"?([^"\n;]+)"?/)?.[1]?.trim();
+		}
+	}
+	return probe;
+}

package/src/host/software.ts

@@ -0,0 +1,370 @@
+import { lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { IntegrationSetupPlan, IntegrationSetupStep } from "../integrations/types";
+import { executableIdentity, exposeExecutable, findExecutable, getHost, type HostInfo } from "./host";
+
+export interface ArchiveRecipe {
+	readonly manifestUrl: string;
+	readonly baseDir: string;
+	readonly executable: string;
+}
+export interface SoftwareRecipe {
+	readonly id: string;
+	readonly executable: string;
+	readonly versionArgs: readonly string[];
+	readonly brew?: { readonly package: string; readonly cask?: boolean };
+	readonly apt?: readonly string[];
+	readonly winget?: string;
+	readonly archive?: ArchiveRecipe;
+}
+export interface SoftwareResolution {
+	readonly executable: string;
+	readonly installer: string;
+	readonly elevation: "none" | "sudo";
+	readonly steps: readonly IntegrationSetupStep[];
+	readonly notes: readonly string[];
+	readonly validate: (signal?: AbortSignal) => Promise<void>;
+}
+export interface SoftwareEnvironment {
+	host(signal?: AbortSignal): Promise<HostInfo>;
+	find(name: string): string | undefined;
+	identity(path: string): Promise<string>;
+	run(argv: readonly string[], signal?: AbortSignal): Promise<{ code: number; stdout: string; stderr: string }>;
+	exists(path: string): Promise<boolean>;
+	home: string;
+	dataHome: string;
+}
+async function boundedRun(argv: readonly string[], signal?: AbortSignal) {
+	const timeout = AbortSignal.timeout(15_000);
+	const child = Bun.spawn([...argv], {
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "ignore",
+		signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+		killSignal: "SIGKILL",
+	});
+	const reader = child.stdout.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			size += value.length;
+			if (size > 1024 * 1024) {
+				child.kill("SIGKILL");
+				throw new Error("Software probe exceeded output limit");
+			}
+			chunks.push(value);
+		}
+		return { code: await child.exited, stdout: Buffer.concat(chunks).toString(), stderr: "" };
+	} finally {
+		reader.releaseLock();
+	}
+}
+const environment: SoftwareEnvironment = {
+	host: getHost,
+	find: findExecutable,
+	identity: executableIdentity,
+	run: boundedRun,
+	home: homedir(),
+	dataHome: process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"),
+	exists: async path => {
+		try {
+			await lstat(path);
+			return true;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+			throw error;
+		}
+	},
+};
+export function parseArchiveManifest(value: unknown, architecture: string, recipe: ArchiveRecipe) {
+	const data = value as { version?: unknown; gz?: unknown; sha256gz?: unknown; baseDir?: unknown };
+	if (
+		!data ||
+		typeof data.version !== "string" ||
+		!/^\d+\.\d+\.\d+$/.test(data.version) ||
+		typeof data.gz !== "string" ||
+		typeof data.sha256gz !== "string" ||
+		!/^[a-f0-9]{64}$/.test(data.sha256gz) ||
+		data.baseDir !== recipe.baseDir
+	)
+		throw new Error("Invalid official archive manifest");
+	const url = new URL(data.gz);
+	const authority = new URL(recipe.manifestUrl);
+	if (
+		url.protocol !== "https:" ||
+		url.origin !== authority.origin ||
+		url.username ||
+		url.password ||
+		url.search ||
+		url.hash ||
+		!url.pathname.includes(`/versions/${data.version}/`) ||
+		!url.pathname.endsWith(`-linux-${architecture}.tar.gz`)
+	)
+		throw new Error("Invalid official archive manifest URL");
+	return { version: data.version, url: url.href, sha256: data.sha256gz };
+}
+export async function resolveSoftware(
+	recipe: SoftwareRecipe,
+	signal?: AbortSignal,
+	env = environment,
+): Promise<SoftwareResolution> {
+	signal?.throwIfAborted();
+	if (
+		!/^[a-z][a-z0-9_-]*$/.test(recipe.id) ||
+		!/^[a-z][a-z0-9_-]*$/.test(recipe.executable) ||
+		!recipe.versionArgs.length ||
+		recipe.versionArgs.some(arg => typeof arg !== "string" || arg.includes("\0")) ||
+		recipe.apt?.some(pkg => !/^[a-z0-9][a-z0-9+.-]*$/.test(pkg)) ||
+		(recipe.brew && !/^[a-z0-9][a-z0-9@+._/-]*$/.test(recipe.brew.package)) ||
+		(recipe.winget && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(recipe.winget))
+	)
+		throw new Error("Invalid software recipe");
+	const info = await env.host(signal);
+	const existing = env.find(recipe.executable);
+	const managersFor = (current: HostInfo) =>
+		existing
+			? []
+			: current.os === "darwin"
+				? [current.packageManagers.brew]
+				: current.os === "win32"
+					? [current.packageManagers.winget]
+					: recipe.archive
+						? []
+						: [
+								current.packageManagers.apt,
+								...(current.effectiveUid === 0 ? [] : [current.packageManagers.sudo]),
+							];
+	const fingerprint = async (current: HostInfo) =>
+		JSON.stringify([
+			current,
+			env.find(recipe.executable),
+			...(await Promise.all(
+				managersFor(current)
+					.filter((path): path is string => path !== undefined)
+					.map(path => env.identity(path)),
+			)),
+			env.find(recipe.executable) ? await env.identity(env.find(recipe.executable)!) : undefined,
+		]);
+	const initial = await fingerprint(info);
+	let executable = existing ?? recipe.executable;
+	let installer = "existing executable";
+	let elevation: "none" | "sudo" = "none";
+	const steps: IntegrationSetupStep[] = [];
+	const notes: string[] = [];
+	const aptPolicies = new Map<string, string>();
+	let archiveDestination: string | undefined;
+	let link: string | undefined;
+	if (!existing && (await env.exists(join(env.home, ".local", "bin", recipe.executable))))
+		throw new Error("Conflicting executable path exists. Inspect ~/.local/bin before reviewing setup again.");
+	if (existing) {
+		let valid = false;
+		try {
+			const result = await env.run([existing, ...recipe.versionArgs], signal);
+			valid = result.code === 0 && /\d+\.\d+/.test(result.stdout);
+		} catch {
+			signal?.throwIfAborted();
+		}
+		if (!valid)
+			throw new Error(
+				`${recipe.executable} at ${existing} did not return a working version. Repair or remove that installation, then review setup again.`,
+			);
+		notes.push(`Reuse existing executable: ${existing}`);
+		if (env === environment) exposeExecutable(existing);
+	} else if (info.os === "darwin") {
+		if (!recipe.brew || !info.packageManagers.brew)
+			throw new Error("Homebrew is required on macOS. Install or make Homebrew available, then review setup again.");
+		installer = "Homebrew";
+		steps.push({
+			kind: "install",
+			argv: [info.packageManagers.brew, "install", ...(recipe.brew.cask ? ["--cask"] : []), recipe.brew.package],
+			timeoutMs: 600_000,
+		});
+	} else if (info.os === "win32") {
+		if (!recipe.winget || !info.packageManagers.winget)
+			throw new Error("The official winget package and winget are required on Windows.");
+		const packageInfo = await env.run(
+			[
+				info.packageManagers.winget,
+				"show",
+				"--exact",
+				"--id",
+				recipe.winget,
+				"--source",
+				"winget",
+				"--accept-source-agreements",
+				"--disable-interactivity",
+			],
+			signal,
+		);
+		if (packageInfo.code !== 0)
+			throw new Error(
+				`Official winget package ${recipe.winget} is unavailable. Install the current official CLI yourself and review setup again.`,
+			);
+		installer = "winget";
+		steps.push({
+			kind: "install",
+			argv: [info.packageManagers.winget, "install", "--exact", "--id", recipe.winget],
+			timeoutMs: 600_000,
+		});
+	} else if (info.os === "linux" && recipe.archive) {
+		if (!["x64", "arm64"].includes(info.architecture))
+			throw new Error(`Unsupported archive architecture: ${info.architecture}`);
+		const url = recipe.archive.manifestUrl.replace("{arch}", info.architecture);
+		const timeout = AbortSignal.timeout(30_000);
+		const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+		const response = await fetch(url, {
+			signal: combined,
+			redirect: "error",
+			headers: { "User-Agent": "curl/8.5.0 xcsh-software" },
+		});
+		if (!response.ok) throw new Error("Unable to fetch official stable archive manifest");
+		const raw = await response.text();
+		if (raw.length > 65536) throw new Error("Invalid official archive manifest size");
+		const archive = parseArchiveManifest(JSON.parse(raw), info.architecture, recipe.archive);
+		archiveDestination = join(env.dataHome, "xcsh", "software", recipe.id, archive.version);
+		link = join(env.home, ".local", "bin", recipe.executable);
+		if ((await env.exists(archiveDestination)) || (await env.exists(link)))
+			throw new Error(
+				"Archive destination or executable link already exists. Inspect that path before reviewing setup again.",
+			);
+		executable = join(archiveDestination, recipe.archive.baseDir, recipe.archive.executable);
+		installer = "official archive";
+		steps.push({
+			kind: "archive-install",
+			argv: [],
+			timeoutMs: 600_000,
+			archive: {
+				...archive,
+				destination: archiveDestination,
+				link,
+				baseDir: recipe.archive.baseDir,
+				executable: recipe.archive.executable,
+				versionArgs: recipe.versionArgs,
+			},
+		});
+		notes.push(
+			`Archive ${archive.version}: ${archive.url}`,
+			`SHA-256: ${archive.sha256}`,
+			`Destination: ${archiveDestination}`,
+			`For direct shell use, add ${join(env.home, ".local", "bin")} to PATH. xcsh makes the executable available to subsequent setup and tools.`,
+		);
+	} else if (info.os === "linux") {
+		if (!["debian", "ubuntu"].includes(info.distribution ?? "") || !recipe.apt?.length || !info.packageManagers.apt)
+			throw new Error(
+				"Declared apt packages on Debian/Ubuntu are required; configure the prerequisite yourself before setup.",
+			);
+		const aptCache = join(info.packageManagers.apt.slice(0, info.packageManagers.apt.lastIndexOf("/")), "apt-cache");
+		for (const pkg of recipe.apt) {
+			const result = await env.run([aptCache, "policy", pkg], signal);
+			aptPolicies.set(pkg, result.stdout);
+			if (result.code !== 0 || !/Candidate:\s*(?!\(none\))\S+/.test(result.stdout))
+				throw new Error(
+					`apt package ${pkg} is unavailable in configured repositories. Configure the prerequisite yourself, then review setup.`,
+				);
+		}
+		if (info.effectiveUid !== 0) {
+			if (!info.packageManagers.sudo || info.sudo !== "available")
+				throw new Error("apt installation requires root or sudo capability");
+			elevation = "sudo";
+		}
+		installer = "apt";
+		steps.push({
+			kind: "install",
+			argv: [
+				...(elevation === "sudo" ? [info.packageManagers.sudo!] : []),
+				info.packageManagers.apt,
+				"install",
+				"--yes",
+				...recipe.apt,
+			],
+			timeoutMs: 600_000,
+			...(elevation === "sudo" ? { stdin: "inherit" } : {}),
+		});
+	} else throw new Error(`Unsupported host: ${info.os}`);
+	notes.unshift(`Installer: ${installer}; required elevation: ${elevation}`);
+	return Object.freeze({
+		executable,
+		installer,
+		elevation,
+		steps: Object.freeze(
+			steps.map(step =>
+				Object.freeze({
+					...step,
+					argv: Object.freeze([...step.argv]),
+					...(step.archive
+						? {
+								archive: Object.freeze({
+									...step.archive,
+									versionArgs: Object.freeze([...step.archive.versionArgs]),
+								}),
+							}
+						: {}),
+				}),
+			),
+		),
+		notes: Object.freeze(notes),
+		validate: async (currentSignal?: AbortSignal) => {
+			currentSignal?.throwIfAborted();
+			if (
+				initial !== (await fingerprint(await env.host(currentSignal))) ||
+				(archiveDestination && (await env.exists(archiveDestination))) ||
+				(link && (await env.exists(link)))
+			)
+				throw new Error("Software identity or prerequisites changed; review setup again");
+			if (installer === "winget") {
+				const packageInfo = await env.run(
+					[
+						info.packageManagers.winget!,
+						"show",
+						"--exact",
+						"--id",
+						recipe.winget!,
+						"--source",
+						"winget",
+						"--accept-source-agreements",
+						"--disable-interactivity",
+					],
+					currentSignal,
+				);
+				if (packageInfo.code !== 0) throw new Error("winget prerequisites changed; review setup again");
+			}
+			if (existing) {
+				const result = await env.run([existing, ...recipe.versionArgs], currentSignal);
+				if (result.code !== 0 || !/\d+\.\d+/.test(result.stdout))
+					throw new Error("Existing executable changed; review setup again");
+			}
+			if (installer === "apt") {
+				for (const pkg of recipe.apt!) {
+					const cache = join(
+						info.packageManagers.apt!.slice(0, info.packageManagers.apt!.lastIndexOf("/")),
+						"apt-cache",
+					);
+					const result = await env.run([cache, "policy", pkg], currentSignal);
+					if (result.code !== 0 || result.stdout !== aptPolicies.get(pkg))
+						throw new Error("apt prerequisites changed; review setup again");
+				}
+			}
+		},
+	});
+}
+export async function prepareSoftwareSetup(
+	recipe: SoftwareRecipe,
+	plan: IntegrationSetupPlan,
+	signal?: AbortSignal,
+): Promise<IntegrationSetupPlan> {
+	const resolution = await resolveSoftware(recipe, signal);
+	const map = (argv: readonly string[]) =>
+		argv[0] === recipe.executable ? [resolution.executable, ...argv.slice(1)] : argv;
+	return {
+		...plan,
+		steps: [...resolution.steps, ...plan.steps.map(step => ({ ...step, argv: map(step.argv) }))],
+		verification: plan.verification.map(step => ({ ...step, argv: map(step.argv) })),
+		notes: resolution.notes,
+		validate: resolution.validate,
+	};
+}
+export const software = Object.freeze({ resolve: resolveSoftware, prepareSetup: prepareSoftwareSetup });

package/src/index.ts

@@ -30,6 +30,9 @@ export * from "./extensibility/extensions";
 export * from "./extensibility/skills";
 // Slash commands
 export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./extensibility/slash-commands";
+export { type HostInfo, host } from "./host/host";
+export { type SoftwareRecipe, type SoftwareResolution, software } from "./host/software";
+export type { IntegrationDefinition, IntegrationHandle, IntegrationSetupPlan } from "./integrations/types";
 export type * from "./lsp";
 // Main entry point
 export * from "./main";

package/src/integrations/registry.ts

@@ -33,6 +33,8 @@ function freezeStrings(values: readonly string[]): readonly string[] {
 function freezePlan(plan: IntegrationSetupPlan | undefined): IntegrationSetupPlan | undefined {
 	if (!plan) return undefined;
 	const frozen: IntegrationSetupPlan = {
+		...(plan.notes ? { notes: freezeStrings(plan.notes) } : {}),
+		...(plan.validate ? { validate: plan.validate } : {}),
 		pluginDependencies: freezeStrings(plan.pluginDependencies),
 		requiredEnvironment: freezeStrings(plan.requiredEnvironment),
 		profileFields: freezeStrings(plan.profileFields),
@@ -41,6 +43,14 @@ function freezePlan(plan: IntegrationSetupPlan | undefined): IntegrationSetupPla
 				Object.freeze({
 					...step,
 					argv: freezeStrings(step.argv),
+					...(step.archive
+						? {
+								archive: Object.freeze({
+									...step.archive,
+									versionArgs: freezeStrings(step.archive.versionArgs),
+								}),
+							}
+						: {}),
 					...(step.environment ? { environment: freezeStrings(step.environment) } : {}),
 				}),
 			),
@@ -82,8 +92,13 @@ function validatePlan(plan: IntegrationSetupPlan | undefined): void {
 		plan.steps.some(
 			step =>
 				!step ||
-				!(["install", "login"] as const).includes(step.kind) ||
-				!validateArgv(step.argv) ||
+				!(["install", "login", "archive-install"] as const).includes(step.kind) ||
+				(step.kind === "archive-install"
+					? !step.archive ||
+						!/^\d+\.\d+\.\d+$/.test(step.archive.version) ||
+						!/^[a-f0-9]{64}$/.test(step.archive.sha256) ||
+						!validateArgv(step.archive.versionArgs)
+					: !validateArgv(step.argv)) ||
 				!Number.isInteger(step.timeoutMs) ||
 				step.timeoutMs < 1_000 ||
 				step.timeoutMs > MAX_SETUP_STEP_TIMEOUT_MS ||
@@ -134,7 +149,8 @@ export class IntegrationRegistry {
 		const existing = this.#entries.get(definition.id);
 		if (existing && existing.owner !== owner) throw new Error(`Integration ${definition.id} is already registered`);
 
-		const setupPlan = freezePlan(definition.setup);
+		let setupPlan = freezePlan(definition.setup);
+		let preparationRevision = 0;
 		const frozenDefinition = Object.freeze({
 			...definition,
 			dependencies: definition.dependencies ? freezeStrings(definition.dependencies) : undefined,
@@ -145,12 +161,28 @@ export class IntegrationRegistry {
 			id: definition.id,
 			name: definition.name,
 			plugin: definition.plugin,
-			setupPlan,
+			get setupPlan() {
+				return setupPlan;
+			},
+			prepareSetup: async (signal?: AbortSignal) => {
+				const revision = ++preparationRevision;
+				if (!definition.prepareSetup) {
+					if (!setupPlan) throw new Error("No setup is declared");
+					return setupPlan;
+				}
+				const prepared = await definition.prepareSetup(signal);
+				signal?.throwIfAborted();
+				validatePlan(prepared);
+				if (revision !== preparationRevision || this.#entries.get(definition.id)?.handle !== handle)
+					throw new Error("Setup preparation changed; review again");
+				setupPlan = freezePlan(prepared)!;
+				return setupPlan;
+			},
 			get: (signal?: AbortSignal) => this.#get(definition.id, false, signal) as Promise<IntegrationSnapshot<T>>,
 			invalidate: () => this.invalidate(definition.id),
 			verifyAfterSetup: (reviewedPlan: IntegrationSetupPlan, signal?: AbortSignal) => {
 				const current = this.#entries.get(definition.id);
-				if (!current?.definition.setup || reviewedPlan !== current.definition.setup)
+				if (current?.handle !== handle || reviewedPlan !== setupPlan)
 					throw new Error("Setup requires the current reviewed setup plan");
 				return this.#get(definition.id, true, signal) as Promise<IntegrationSnapshot<T>>;
 			},

package/src/integrations/setup.ts

@@ -1,3 +1,5 @@
+import { installArchive } from "../host/archive";
+import { host } from "../host/host";
 import type { IntegrationHandle, IntegrationSetupPlan, IntegrationSetupStep, IntegrationSnapshot } from "./types";
 
 export type PluginSetupTrigger = "direct-install" | "bulk-install" | "upgrade" | "cache-refresh" | "dependency-install";
@@ -9,6 +11,7 @@ export interface InstallAuthorizedSetupOptions {
 	readonly handles: readonly IntegrationHandle<unknown>[];
 	readonly run?: SetupStepRunner;
 	readonly signal?: AbortSignal;
+	readonly review?: (handle: IntegrationHandle<unknown>, plan: IntegrationSetupPlan) => Promise<void>;
 }
 
 export type SetupStepRunner = (step: IntegrationSetupStep, signal?: AbortSignal) => Promise<number>;
@@ -64,12 +67,15 @@ export function describeSetupPlan(handle: IntegrationHandle<unknown>): string {
 		`Required environment names: ${plan.requiredEnvironment.join(", ") || "none"}`,
 		`Person-profile categories: ${plan.profileFields.join(", ") || "none"}`,
 	];
+	lines.push(...(plan.notes ?? []));
 	if (plan.guidedAction?.kind === "context_wizard") {
 		lines.push("Guided action: native xcsh context wizard");
 	} else {
 		lines.push(
 			"Commands:",
-			...plan.steps.map(step => `  ${step.kind}: ${JSON.stringify(step.argv)} (timeout ${step.timeoutMs}ms)`),
+			...plan.steps.map(
+				step => `  ${step.kind}: ${JSON.stringify(step.archive ?? step.argv)} (timeout ${step.timeoutMs}ms)`,
+			),
 			"Verification:",
 			...plan.verification.map(step => `  ${JSON.stringify(step.argv)} (timeout ${step.timeoutMs}ms)`),
 		);
@@ -82,6 +88,11 @@ export function createSetupStepRunner(
 	options: SetupStepRunnerOptions = {},
 ): SetupStepRunner {
 	return async (step, signal) => {
+		if (step.kind === "archive-install") {
+			if (!step.archive) throw new Error("Missing archive installation specification");
+			await installArchive(step.archive, signal, step.timeoutMs);
+			return 0;
+		}
 		const environment = { ...process.env };
 		for (const name of step.environment ?? []) {
 			const value = resolveEnvironment(name);
@@ -93,7 +104,7 @@ export function createSetupStepRunner(
 		const interactiveInput = step.stdin === "inherit" || step.kind === "login";
 		const output = step.kind === "login" ? "inherit" : (options.nonInteractiveOutput ?? "inherit");
 		try {
-			const child = Bun.spawn([...step.argv], {
+			const child = Bun.spawn([host.findExecutable(step.argv[0]) ?? step.argv[0], ...step.argv.slice(1)], {
 				env: environment,
 				stdin: interactiveInput ? "inherit" : "ignore",
 				stdout: output,
@@ -117,6 +128,9 @@ export async function executeReviewedSetup<T>(
 ): Promise<IntegrationSnapshot<T>> {
 	if (reviewedPlan !== handle.setupPlan) throw new Error("Setup requires the current reviewed setup plan");
 	if (reviewedPlan.guidedAction) throw new Error("Guided setup must run through its native interactive action");
+	if (signal?.aborted) throw new Error("Integration setup cancelled");
+	await reviewedPlan.validate?.(signal);
+	if (reviewedPlan !== handle.setupPlan) throw new Error("Setup requires the current reviewed setup plan");
 	for (const step of reviewedPlan.steps) {
 		if (signal?.aborted) throw new Error("Integration setup cancelled");
 		if ((await run(step, signal)) !== 0) throw new Error(`Integration ${step.kind} step failed`);
@@ -154,5 +168,7 @@ export async function executeInstallAuthorizedSetup(
 	const handle = matches[0];
 	const current = await handle.get(options.signal);
 	if (current.state !== "setup_required" && current.state !== "degraded") return current;
-	return executeReviewedSetup(handle, handle.setupPlan!, options.run, options.signal);
+	const plan = handle.prepareSetup ? await handle.prepareSetup(options.signal) : handle.setupPlan!;
+	await options.review?.(handle, plan);
+	return executeReviewedSetup(handle, plan, options.run, options.signal);
 }