@f5-sales-demo/xcsh 22.4.3 → 22.4.6

package/src/host/archive.ts

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, link as hardlink, lstat, mkdir, mkdtemp, rename, rm, symlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, posix } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { extract } from "tar-stream";
+import type { ArchiveInstall } from "../integrations/types";
+import { exposeExecutable } from "./host";
+
+export function safeArchivePath(name: string): string {
+	if (
+		!name ||
+		name.includes("\\") ||
+		name.includes("\0") ||
+		name.startsWith("/") ||
+		/^[a-z]:/i.test(name) ||
+		name.split("/").includes("..")
+	)
+		throw new Error("Unsafe archive extraction path");
+	const normalized = posix.normalize(name);
+	if (normalized === "." || normalized.startsWith("../")) throw new Error("Unsafe archive extraction path");
+	return normalized.replace(/\/$/, "");
+}
+async function unpack(file: string, stage: string, baseDir: string, signal: AbortSignal) {
+	const archive = extract();
+	const pendingLinks: { path: string; target: string; hard: boolean }[] = [];
+	const seen = new Set<string>();
+	let total = 0;
+	let entries = 0;
+	archive.on("entry", (header, stream, next) => {
+		stream.on("error", error => archive.destroy(error));
+		void (async () => {
+			signal.throwIfAborted();
+			const name = safeArchivePath(header.name);
+			if ((name !== baseDir && !name.startsWith(`${baseDir}/`)) || seen.has(name) || ++entries > 100_000)
+				throw new Error("Unsafe or duplicate archive extraction path");
+			seen.add(name);
+			total += header.size ?? 0;
+			if (total > 2 * 1024 ** 3) throw new Error("Archive extraction size limit exceeded");
+			const path = join(stage, name);
+			if (header.type === "directory") {
+				await mkdir(path, { recursive: true, mode: 0o700 });
+				stream.resume();
+			} else if (header.type === "file" || header.type === "contiguous-file") {
+				await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+				await pipeline(stream, createWriteStream(path, { flags: "wx", mode: (header.mode ?? 0o600) & 0o777 }), {
+					signal,
+				});
+			} else if (header.type === "symlink" || header.type === "link") {
+				const target = header.linkname ?? "";
+				if (!target || isAbsolute(target) || target.includes("\\") || target.includes("\0"))
+					throw new Error("Unsafe archive link");
+				const resolved =
+					header.type === "link"
+						? safeArchivePath(target)
+						: posix.normalize(posix.join(posix.dirname(name), target));
+				if (!resolved.startsWith(`${baseDir}/`) && resolved !== baseDir)
+					throw new Error("Unsafe archive link target");
+				pendingLinks.push({
+					path,
+					target: header.type === "link" ? join(stage, resolved) : target,
+					hard: header.type === "link",
+				});
+				stream.resume();
+			} else throw new Error("Unsupported archive entry type");
+		})().then(
+			() => next(),
+			error => {
+				stream.destroy(error);
+				archive.destroy(error);
+			},
+		);
+	});
+	await pipeline(createReadStream(file), createGunzip(), archive, { signal });
+	// No deferred link may be an ancestor of any other entry, including another link.
+	const relativeLinks = pendingLinks.map(item => item.path.slice(stage.length + 1));
+	for (const linkPath of relativeLinks)
+		if ([...seen].some(name => name.startsWith(`${linkPath}/`))) throw new Error("Unsafe archive link ancestor");
+	// Create links only after extraction; no extracted file can traverse a symlink.
+	for (const item of pendingLinks) {
+		signal.throwIfAborted();
+		await mkdir(dirname(item.path), { recursive: true, mode: 0o700 });
+		if (item.hard) {
+			if (!(await lstat(item.target)).isFile()) throw new Error("Unsafe archive hard link");
+			await hardlink(item.target, item.path);
+		} else await symlink(item.target, item.path);
+	}
+}
+export async function installArchive(
+	archive: ArchiveInstall,
+	signal?: AbortSignal,
+	timeoutMs = 600_000,
+): Promise<void> {
+	const timeout = AbortSignal.timeout(timeoutMs);
+	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+	if (
+		!isAbsolute(archive.destination) ||
+		!isAbsolute(archive.link) ||
+		!/^[a-f0-9]{64}$/.test(archive.sha256) ||
+		new URL(archive.url).protocol !== "https:"
+	)
+		throw new Error("Invalid archive installation plan");
+	const baseDir = safeArchivePath(archive.baseDir);
+	const relativeExecutable = safeArchivePath(archive.executable);
+	if (baseDir.includes("/")) throw new Error("Invalid archive base directory");
+	combined.throwIfAborted();
+	await mkdir(dirname(archive.destination), { recursive: true, mode: 0o700 });
+	const stage = await mkdtemp(join(dirname(archive.destination), ".xcsh-stage-"));
+	let ownedDestination = false;
+	let ownedLink = false;
+	try {
+		const response = await fetch(archive.url, {
+			signal: combined,
+			redirect: "error",
+			headers: { "User-Agent": "curl/8.5.0 xcsh-software" },
+		});
+		if (!response.ok || !response.body) throw new Error("Archive download failed");
+		const file = join(stage, "download.tar.gz");
+		const hash = createHash("sha256");
+		let size = 0;
+		const reader = response.body.getReader();
+		const output = createWriteStream(file, { flags: "wx", mode: 0o600 });
+		try {
+			await pipeline(
+				Readable.from(
+					(async function* () {
+						while (true) {
+							const { done, value } = await reader.read();
+							if (done) break;
+							size += value.length;
+							if (size > 1024 ** 3) throw new Error("Archive download size limit exceeded");
+							hash.update(value);
+							yield value;
+						}
+					})(),
+				),
+				output,
+				{ signal: combined },
+			);
+		} finally {
+			await reader.cancel().catch(() => {});
+			reader.releaseLock();
+		}
+		if (hash.digest("hex") !== archive.sha256) throw new Error("Archive SHA-256 checksum mismatch");
+		await unpack(file, stage, baseDir, combined);
+		const executable = join(stage, baseDir, relativeExecutable);
+		if (!(await lstat(executable)).isFile())
+			throw new Error("Archive executable is missing or is not a regular file");
+		await chmod(executable, 0o755);
+		const child = Bun.spawn([executable, ...archive.versionArgs], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "ignore",
+			signal: AbortSignal.any([combined, AbortSignal.timeout(15_000)]),
+			killSignal: "SIGKILL",
+		});
+		const version = await new Response(child.stdout).text();
+		if ((await child.exited) !== 0 || !version.includes(archive.version))
+			throw new Error("Archive executable version verification failed");
+		combined.throwIfAborted();
+		// Exclusive reservation prevents a competing or unrelated destination from being replaced.
+		await mkdir(archive.destination, { mode: 0o700 });
+		ownedDestination = true;
+		await rename(join(stage, baseDir), join(archive.destination, baseDir));
+		await mkdir(dirname(archive.link), { recursive: true, mode: 0o700 });
+		combined.throwIfAborted();
+		const installed = join(archive.destination, baseDir, relativeExecutable);
+		await symlink(installed, archive.link);
+		ownedLink = true;
+		exposeExecutable(installed);
+	} catch (error) {
+		if (ownedLink) await rm(archive.link, { force: true });
+		if (ownedDestination) await rm(archive.destination, { recursive: true, force: true });
+		if (combined.aborted)
+			throw new Error(signal?.aborted ? "Integration setup cancelled" : "Archive installation timed out");
+		throw error;
+	} finally {
+		await rm(stage, { recursive: true, force: true });
+	}
+}

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 });