@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/domains/toolchain/archive.ts

@@ -0,0 +1,175 @@
+import { gunzipSync, inflateRawSync } from "node:zlib";
+
+/**
+ * Just enough zip and tar.gz reading to unpack a pinned release asset.
+ *
+ * Node ships neither reader, and the alternatives were a dependency or shelling
+ * out to `unzip` and `tar`. A dependency for two hundred lines of well-specified
+ * format is a poor trade, and shelling out makes the install fail on a machine
+ * that has one of the two but not the other, which is exactly the machine a
+ * vendored-tool installer exists to serve. Both readers are deliberately narrow:
+ * they read the members the registry names and refuse anything they do not
+ * understand rather than guessing.
+ *
+ * The bytes reaching here have already been checksum-verified against the pin,
+ * so these are not parsing hostile input. The size cap and the path checks are
+ * belt and braces for the day a pin is updated carelessly.
+ */
+
+/** One file read out of an archive. */
+export interface ArchiveEntry {
+	path: string;
+	data: Buffer;
+	/** Unix mode when the archive records one, otherwise null. */
+	mode: number | null;
+}
+
+/** Refuse to materialize more than this from one asset. */
+const MAX_TOTAL_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+
+const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_CENTRAL_SIGNATURE = 0x02014b50;
+const ZIP_LOCAL_SIGNATURE = 0x04034b50;
+const ZIP_STORED = 0;
+const ZIP_DEFLATED = 8;
+
+/** Every regular file in a zip, keyed by its path inside the archive. */
+export function readZipEntries(buffer: Buffer): Map<string, ArchiveEntry> {
+	const eocd = findEndOfCentralDirectory(buffer);
+	if (eocd < 0) throw new Error("not a zip archive: end-of-central-directory record not found");
+	const entryCount = buffer.readUInt16LE(eocd + 10);
+	let cursor = buffer.readUInt32LE(eocd + 16);
+	const entries = new Map<string, ArchiveEntry>();
+	let total = 0;
+
+	for (let i = 0; i < entryCount; i += 1) {
+		if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== ZIP_CENTRAL_SIGNATURE) {
+			throw new Error(`zip central directory is malformed at entry ${i}`);
+		}
+		const method = buffer.readUInt16LE(cursor + 10);
+		const compressedSize = buffer.readUInt32LE(cursor + 20);
+		const uncompressedSize = buffer.readUInt32LE(cursor + 24);
+		const nameLength = buffer.readUInt16LE(cursor + 28);
+		const extraLength = buffer.readUInt16LE(cursor + 30);
+		const commentLength = buffer.readUInt16LE(cursor + 32);
+		const externalAttributes = buffer.readUInt32LE(cursor + 38);
+		const localOffset = buffer.readUInt32LE(cursor + 42);
+		const name = buffer.toString("utf8", cursor + 46, cursor + 46 + nameLength);
+		cursor += 46 + nameLength + extraLength + commentLength;
+
+		if (name.endsWith("/")) continue;
+		assertSafeMember(name);
+		total += uncompressedSize;
+		if (total > MAX_TOTAL_UNCOMPRESSED_BYTES) throw new Error("zip archive expands beyond the size cap");
+
+		if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== ZIP_LOCAL_SIGNATURE) {
+			throw new Error(`zip local header is malformed for ${name}`);
+		}
+		const localNameLength = buffer.readUInt16LE(localOffset + 26);
+		const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+		const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+		const raw = buffer.subarray(dataStart, dataStart + compressedSize);
+		const data =
+			method === ZIP_STORED
+				? Buffer.from(raw)
+				: method === ZIP_DEFLATED
+					? inflateRawSync(raw)
+					: (() => {
+							throw new Error(`unsupported zip compression method ${method} for ${name}`);
+						})();
+		// The high 16 bits of the external attributes carry the unix mode when the
+		// archive was produced on a unix host, which is where the executable bit
+		// on a release binary lives.
+		const unixMode = (externalAttributes >>> 16) & 0o7777;
+		entries.set(name, { path: name, data, mode: unixMode === 0 ? null : unixMode });
+	}
+	return entries;
+}
+
+/** Every regular file in a gzipped tar, keyed by its path inside the archive. */
+export function readTarGzEntries(buffer: Buffer): Map<string, ArchiveEntry> {
+	const tar = gunzipSync(buffer);
+	const entries = new Map<string, ArchiveEntry>();
+	let offset = 0;
+	let total = 0;
+	let pendingLongName: string | null = null;
+
+	while (offset + 512 <= tar.length) {
+		const header = tar.subarray(offset, offset + 512);
+		// Two consecutive zero blocks end the archive; one is enough to stop.
+		if (header.every((byte) => byte === 0)) break;
+		const rawName = readTarString(header, 0, 100);
+		const prefix = readTarString(header, 345, 155);
+		const size = readTarOctal(header, 124, 12);
+		const mode = readTarOctal(header, 100, 8);
+		const typeFlag = String.fromCharCode(header[156] ?? 0);
+		const dataStart = offset + 512;
+		const padded = Math.ceil(size / 512) * 512;
+		offset = dataStart + padded;
+
+		// GNU long-name extension: this block's payload is the next block's name.
+		if (typeFlag === "L") {
+			pendingLongName = tar.toString("utf8", dataStart, dataStart + size).replace(/\0+$/, "");
+			continue;
+		}
+		// PAX headers and directories carry no file content Clio wants.
+		if (typeFlag === "x" || typeFlag === "g" || typeFlag === "5") {
+			pendingLongName = null;
+			continue;
+		}
+		if (typeFlag !== "0" && typeFlag !== "\0") {
+			pendingLongName = null;
+			continue;
+		}
+
+		const name = pendingLongName ?? (prefix.length > 0 ? `${prefix}/${rawName}` : rawName);
+		pendingLongName = null;
+		if (name.length === 0 || name.endsWith("/")) continue;
+		assertSafeMember(name);
+		total += size;
+		if (total > MAX_TOTAL_UNCOMPRESSED_BYTES) throw new Error("tar archive expands beyond the size cap");
+		entries.set(name, {
+			path: name,
+			data: Buffer.from(tar.subarray(dataStart, dataStart + size)),
+			mode: mode === 0 ? null : mode & 0o7777,
+		});
+	}
+	return entries;
+}
+
+function findEndOfCentralDirectory(buffer: Buffer): number {
+	// The record is at the very end unless a zip comment follows it, and the
+	// comment length field is 16 bits, so 22 + 65535 bytes is the whole search.
+	const start = Math.max(0, buffer.length - (22 + 0xffff));
+	for (let i = buffer.length - 22; i >= start; i -= 1) {
+		if (buffer.readUInt32LE(i) === ZIP_EOCD_SIGNATURE) return i;
+	}
+	return -1;
+}
+
+function readTarString(header: Buffer, offset: number, length: number): string {
+	const slice = header.subarray(offset, offset + length);
+	const end = slice.indexOf(0);
+	return slice.toString("utf8", 0, end === -1 ? slice.length : end);
+}
+
+function readTarOctal(header: Buffer, offset: number, length: number): number {
+	const text = readTarString(header, offset, length).trim();
+	if (text.length === 0) return 0;
+	const value = Number.parseInt(text, 8);
+	return Number.isNaN(value) ? 0 : value;
+}
+
+/**
+ * An archive member's path is used to look up a registry-named member, never to
+ * build a write path, but a member escaping the archive root still means the
+ * asset is not what the pin says it is.
+ */
+function assertSafeMember(name: string): void {
+	if (name.startsWith("/") || name.startsWith("\\") || /^[A-Za-z]:/.test(name)) {
+		throw new Error(`archive member has an absolute path: ${name}`);
+	}
+	if (name.split(/[/\\]/).includes("..")) {
+		throw new Error(`archive member escapes the archive root: ${name}`);
+	}
+}

package/src/domains/toolchain/contract.ts

@@ -0,0 +1,28 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type { ToolInstallOptions, ToolInstallResult } from "./install.js";
+import type { ToolRemoveOptions, ToolRemoveResult } from "./remove.js";
+import type { PinnedTool, ToolResolution, ToolStatus } from "./types.js";
+
+export interface ToolchainContract extends DomainContract {
+	/** The pinned table, in registry order. */
+	list(): ReadonlyArray<PinnedTool>;
+	/** One row by id. */
+	get(id: string): PinnedTool | null;
+	/** Resolve an executable name through PATH, then the vendored pin, then none. */
+	resolve(name: string): ToolResolution;
+	/** Per-entry state for one row. */
+	status(id: string): ToolStatus | null;
+	/** Per-entry state for every row. */
+	statuses(): ToolStatus[];
+	/**
+	 * Download and vendor one tool. Only ever called from an explicit operator
+	 * command; nothing on a startup path may reach it.
+	 */
+	install(id: string, options?: ToolInstallOptions): Promise<ToolInstallResult>;
+	/**
+	 * Delete every vendored version of one tool. Nothing outside
+	 * `<data>/tools/<id>` is reachable, and a tool with nothing installed is a
+	 * successful no-op rather than an error.
+	 */
+	remove(id: string, options?: ToolRemoveOptions): ToolRemoveResult;
+}

package/src/domains/toolchain/extension.ts

@@ -0,0 +1,47 @@
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import type { ToolchainContract } from "./contract.js";
+import type { ToolInstallOptions } from "./install.js";
+import { findPinnedTool, PINNED_TOOLS } from "./registry.js";
+import { removeTool, type ToolRemoveOptions } from "./remove.js";
+import { resolveToolBinary, toolStatus, toolStatuses } from "./resolve.js";
+
+export function createToolchainBundle(_context: DomainContext): DomainBundle<ToolchainContract> {
+	const extension: DomainExtension = {
+		start() {
+			// Nothing to start. Resolution is on demand and installs are operator
+			// commands, so loading the domain touches neither the network nor disk.
+			return undefined;
+		},
+	};
+	const contract: ToolchainContract = {
+		list() {
+			return PINNED_TOOLS;
+		},
+		get(id) {
+			return findPinnedTool(id);
+		},
+		resolve(name) {
+			return resolveToolBinary(name);
+		},
+		status(id) {
+			const entry = findPinnedTool(id);
+			return entry === null ? null : toolStatus(entry);
+		},
+		statuses() {
+			return toolStatuses();
+		},
+		async install(id: string, options: ToolInstallOptions = {}) {
+			// Imported lazily so the installer's archive readers stay out of every
+			// graph that only ever resolves a binary.
+			const { installTool } = await import("./install.js");
+			return installTool(id, options);
+		},
+		remove(id: string, options: ToolRemoveOptions = {}) {
+			// Statically imported, unlike install: removal is a readdir and an
+			// unlink, so it carries none of the archive readers that keep the
+			// installer off graphs which only ever resolve a binary.
+			return removeTool(id, options);
+		},
+	};
+	return { extension, contract };
+}

package/src/domains/toolchain/index.ts

@@ -0,0 +1,39 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import type { ToolchainContract } from "./contract.js";
+import { createToolchainBundle } from "./extension.js";
+import { ToolchainManifest } from "./manifest.js";
+
+export const ToolchainDomainModule: DomainModule<ToolchainContract> = {
+	manifest: ToolchainManifest,
+	createExtension: createToolchainBundle,
+};
+
+export type { ToolchainContract } from "./contract.js";
+export type { ToolFetcher, ToolInstallOptions, ToolInstallResult } from "./install.js";
+export { installPinnedTool, installTool } from "./install.js";
+export { ToolchainManifest } from "./manifest.js";
+export { toolchainRoot, toolVersionDir, vendoredBinaryPath } from "./paths.js";
+export { currentToolPlatform, findPinnedTool, findPinnedToolByBinary, PINNED_TOOLS } from "./registry.js";
+export type { ToolRemoveOptions, ToolRemoveResult } from "./remove.js";
+export { installedToolVersions, pruneSupersededVersions, removeTool, STALE_STAGING_MS } from "./remove.js";
+export {
+	describeFloorRejection,
+	describeResolution,
+	installRemedy,
+	resolveEntryBinary,
+	resolveToolBinary,
+	toolStatus,
+	toolStatuses,
+} from "./resolve.js";
+export type {
+	PinnedTool,
+	PinnedToolDocument,
+	PinnedToolDownload,
+	ToolArchiveKind,
+	ToolPathCandidate,
+	ToolPlatform,
+	ToolResolution,
+	ToolSource,
+	ToolStatus,
+} from "./types.js";
+export { compareVersions, parseVersion, resetVersionProbeCache, satisfiesMinimum } from "./version.js";

package/src/domains/toolchain/install.ts

@@ -0,0 +1,327 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { type ArchiveEntry, readTarGzEntries, readZipEntries } from "./archive.js";
+import { ensureToolchainRoot } from "./paths.js";
+import { currentToolPlatform, findPinnedTool } from "./registry.js";
+import { pruneSupersededVersions } from "./remove.js";
+import type { PinnedTool, PinnedToolDownload, ToolPlatform } from "./types.js";
+
+/**
+ * Install a pinned tool into the vendor root.
+ *
+ * Three rules shape this file. Nothing downloads unless an operator asked for
+ * this install by name, so no startup path can reach it. Nothing is written
+ * until the asset's checksum matches the pin, and a mismatch leaves the disk
+ * exactly as it was. And the version directory appears atomically, built in a
+ * sibling staging directory and renamed into place, so a killed install leaves
+ * a `.incomplete-` directory rather than a half-populated version that the
+ * resolution ladder would happily run.
+ *
+ * A successful install then prunes, so a tool holds exactly the pinned version
+ * and nothing else. Only the ladder's own version is ever resolved, so a
+ * superseded directory is dead weight an operator would have to find and delete
+ * by hand. Pruning runs on the already-installed path too, which is what
+ * repairs a machine that bumped pins before this behavior existed.
+ */
+
+/** How a URL becomes bytes. Injectable so the contract tests never touch the network. */
+export type ToolFetcher = (url: string) => Promise<Buffer>;
+
+export interface ToolInstallOptions {
+	/** Re-download and replace an already-installed version. */
+	force?: boolean;
+	/** Install the asset for a platform other than the running one. */
+	platform?: ToolPlatform;
+	/** Vendor root override. Defaults to the data root's `tools` directory. */
+	root?: string;
+	fetch?: ToolFetcher;
+	onProgress?: (message: string) => void;
+}
+
+export interface ToolInstallResult {
+	ok: boolean;
+	id: string;
+	version: string;
+	/** Where the version directory is, whether or not this run created it. */
+	dir: string;
+	/** Absolute paths of the installed executables. */
+	binaries: string[];
+	/** Absolute paths of the license and notice files placed beside them. */
+	documents: string[];
+	/** True when the version was already installed and nothing was downloaded. */
+	skipped: boolean;
+	/** Superseded versions of the same tool this install deleted. */
+	pruned: string[];
+	message: string;
+}
+
+/** How long one asset download may take. */
+const DOWNLOAD_TIMEOUT_MS = 300_000;
+
+/** Install by registry id. */
+export async function installTool(id: string, options: ToolInstallOptions = {}): Promise<ToolInstallResult> {
+	const entry = findPinnedTool(id);
+	if (entry === null) {
+		return failure(id, "unknown", "", `unknown tool: ${id}`);
+	}
+	return installPinnedTool(entry, options);
+}
+
+/** Install a registry row. Exported so tests can drive a fabricated entry. */
+export async function installPinnedTool(
+	entry: PinnedTool,
+	options: ToolInstallOptions = {},
+): Promise<ToolInstallResult> {
+	const root = options.root ?? ensureToolchainRoot();
+	const dir = join(root, entry.id, entry.version);
+	const platform = options.platform ?? currentToolPlatform();
+	const progress = options.onProgress ?? (() => undefined);
+
+	if (platform === null) {
+		return failure(entry.id, entry.version, dir, `no pinned asset for ${process.platform}-${process.arch}`);
+	}
+	const download = entry.downloads[platform];
+	if (download === undefined) {
+		return failure(entry.id, entry.version, dir, `no pinned asset for ${platform}`);
+	}
+
+	const installedBinaries = Object.keys(download.binaryMembers).map((name) => join(dir, executableName(name, platform)));
+	if (!options.force && installedBinaries.every((path) => existsSync(path))) {
+		const swept = prune(root, entry);
+		return {
+			ok: true,
+			id: entry.id,
+			version: entry.version,
+			dir,
+			binaries: installedBinaries,
+			documents: [],
+			skipped: true,
+			pruned: swept.pruned,
+			message: `${entry.id} ${entry.version} is already installed at ${dir}${swept.note}`,
+		};
+	}
+
+	const fetcher = options.fetch ?? fetchAsset;
+	let assetBytes: Buffer;
+	try {
+		progress(`downloading ${download.url}`);
+		assetBytes = await fetcher(download.url);
+	} catch (error) {
+		return failure(entry.id, entry.version, dir, `download failed: ${messageOf(error)}`);
+	}
+
+	const actual = sha256(assetBytes);
+	if (actual !== download.sha256) {
+		return failure(
+			entry.id,
+			entry.version,
+			dir,
+			`checksum mismatch for ${download.url}: expected ${download.sha256}, got ${actual}. Nothing was written.`,
+		);
+	}
+	progress(`checksum verified (${actual})`);
+
+	const documentBytes = new Map<string, Buffer>();
+	for (const doc of entry.documents) {
+		let bytes: Buffer;
+		try {
+			progress(`downloading ${doc.url}`);
+			bytes = await fetcher(doc.url);
+		} catch (error) {
+			return failure(entry.id, entry.version, dir, `download failed for ${doc.name}: ${messageOf(error)}`);
+		}
+		const docHash = sha256(bytes);
+		if (docHash !== doc.sha256) {
+			return failure(
+				entry.id,
+				entry.version,
+				dir,
+				`checksum mismatch for ${doc.url}: expected ${doc.sha256}, got ${docHash}. Nothing was written.`,
+			);
+		}
+		documentBytes.set(doc.name, bytes);
+	}
+
+	let members: Map<string, ArchiveEntry>;
+	try {
+		members = unpack(assetBytes, download);
+	} catch (error) {
+		return failure(entry.id, entry.version, dir, `could not unpack the asset: ${messageOf(error)}`);
+	}
+
+	for (const memberPath of Object.values(download.binaryMembers)) {
+		if (!members.has(memberPath)) {
+			return failure(entry.id, entry.version, dir, `the asset does not contain ${memberPath || entry.primaryBinary}`);
+		}
+	}
+	for (const memberPath of download.documentMembers) {
+		if (!members.has(memberPath)) {
+			return failure(entry.id, entry.version, dir, `the asset does not contain ${memberPath}`);
+		}
+	}
+
+	const staging = join(root, entry.id, `.${entry.version}.incomplete-${process.pid}-${Date.now().toString(36)}`);
+	// Where a `--force` replacement parks the old version directory while the new
+	// one is renamed in. It is unlinked only once the new directory is in place,
+	// so the window where neither copy exists is a single rename wide.
+	const retired = join(root, entry.id, `.${entry.version}.replaced-${process.pid}-${Date.now().toString(36)}`);
+	let retiredOld = false;
+	const binaries: string[] = [];
+	const documents: string[] = [];
+	try {
+		mkdirSync(staging, { recursive: true });
+		for (const [name, memberPath] of Object.entries(download.binaryMembers)) {
+			const member = members.get(memberPath);
+			if (member === undefined) continue;
+			const target = join(staging, executableName(name, platform));
+			writeFileSync(target, member.data);
+			chmodSync(target, 0o755);
+			binaries.push(join(dir, executableName(name, platform)));
+		}
+		for (const memberPath of download.documentMembers) {
+			const member = members.get(memberPath);
+			if (member === undefined) continue;
+			const target = join(staging, basename(memberPath));
+			writeFileSync(target, member.data, { mode: 0o644 });
+			documents.push(join(dir, basename(memberPath)));
+		}
+		for (const [name, bytes] of documentBytes) {
+			writeFileSync(join(staging, name), bytes, { mode: 0o644 });
+			documents.push(join(dir, name));
+		}
+		writeFileSync(
+			join(staging, "clio-install.json"),
+			`${JSON.stringify(
+				{
+					id: entry.id,
+					version: entry.version,
+					platform,
+					license: entry.license,
+					homepage: entry.homepage,
+					url: download.url,
+					sha256: download.sha256,
+					installedAt: new Date().toISOString(),
+				},
+				null,
+				2,
+			)}\n`,
+			{ mode: 0o644 },
+		);
+		if (options.force && existsSync(dir)) {
+			renameSync(dir, retired);
+			retiredOld = true;
+		}
+		renameSync(staging, dir);
+		if (retiredOld) {
+			rmSync(retired, { recursive: true, force: true });
+			retiredOld = false;
+		}
+	} catch (error) {
+		rmSync(staging, { recursive: true, force: true });
+		// The new version never landed, so put the copy the operator had back.
+		if (retiredOld && !existsSync(dir)) {
+			try {
+				renameSync(retired, dir);
+				retiredOld = false;
+			} catch {
+				// Leave the retired directory in place: it is the only surviving copy.
+			}
+		}
+		// A rename losing to a concurrent installer is not a failure: the version
+		// directory the caller asked for exists and holds the same pinned bytes.
+		if (!options.force && existsSync(dir)) {
+			const swept = prune(root, entry);
+			return {
+				ok: true,
+				id: entry.id,
+				version: entry.version,
+				dir,
+				binaries: installedBinaries,
+				documents: [],
+				skipped: true,
+				pruned: swept.pruned,
+				message: `${entry.id} ${entry.version} was installed concurrently at ${dir}${swept.note}`,
+			};
+		}
+		return failure(entry.id, entry.version, dir, `install failed: ${messageOf(error)}`);
+	}
+
+	const swept = prune(root, entry);
+	return {
+		ok: true,
+		id: entry.id,
+		version: entry.version,
+		dir,
+		binaries,
+		documents,
+		skipped: false,
+		pruned: swept.pruned,
+		message: `installed ${entry.id} ${entry.version} (${entry.license}) at ${dir}${swept.note}`,
+	};
+}
+
+/**
+ * Delete the versions this pin supersedes, and say what happened.
+ *
+ * A prune that cannot delete something never fails the install: the version the
+ * operator asked for is in place and runnable, and a directory that resisted
+ * `rm` is a disk problem to report, not a reason to claim the install did not
+ * happen. It is named in the message so the operator can go look.
+ */
+function prune(root: string, entry: PinnedTool): { pruned: string[]; note: string } {
+	const outcome = pruneSupersededVersions(entry.id, entry.version, { root });
+	const parts: string[] = [];
+	if (outcome.removed.length > 0) parts.push(`pruned ${outcome.removed.join(", ")}`);
+	if (outcome.staleStaging.length > 0) {
+		const count = outcome.staleStaging.length;
+		parts.push(`swept ${count} abandoned install ${count === 1 ? "directory" : "directories"}`);
+	}
+	if (outcome.failed.length > 0) {
+		parts.push(`could not prune ${outcome.failed.map((item) => `${item.version} (${item.error})`).join(", ")}`);
+	}
+	return { pruned: outcome.removed, note: parts.length === 0 ? "" : `; ${parts.join("; ")}` };
+}
+
+function unpack(bytes: Buffer, download: PinnedToolDownload): Map<string, ArchiveEntry> {
+	if (download.archive === "raw") {
+		// The asset is the binary. The registry names it with an empty member
+		// path, so the synthetic map key matches what the caller looks up.
+		return new Map([["", { path: "", data: bytes, mode: 0o755 }]]);
+	}
+	if (download.archive === "zip") return readZipEntries(bytes);
+	return readTarGzEntries(bytes);
+}
+
+async function fetchAsset(url: string): Promise<Buffer> {
+	const response = await fetch(url, {
+		redirect: "follow",
+		signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+	return Buffer.from(await response.arrayBuffer());
+}
+
+function sha256(bytes: Buffer): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * What a binary is called once installed, for the platform being installed.
+ *
+ * Keyed off the target rather than `process.platform`, because `--platform`
+ * exists: installing the win32 asset from Linux has to write `herdr.exe`, and
+ * writing `herdr` there would produce a directory Windows could never run and
+ * that the resolution ladder on Windows would report as not installed.
+ */
+function executableName(name: string, platform: ToolPlatform): string {
+	return platform.startsWith("win32") ? `${name}.exe` : name;
+}
+
+function failure(id: string, version: string, dir: string, message: string): ToolInstallResult {
+	return { ok: false, id, version, dir, binaries: [], documents: [], skipped: false, pruned: [], message };
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/domains/toolchain/manifest.ts

@@ -0,0 +1,8 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const ToolchainManifest: DomainManifest = {
+	name: "toolchain",
+	// The registry is a static table plus filesystem lookups under the data
+	// root. It reads no settings and calls no other domain.
+	dependsOn: [],
+};

package/src/domains/toolchain/paths.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { clioDataDir, resolveClioDirs } from "../../core/xdg.js";
+
+/**
+ * Vendored tools are durable artifacts Clio downloaded on request, so they live
+ * under the data root beside memory and evidence, not under state (machine
+ * output) or cache (disposable). The version is part of the path so a pin bump
+ * installs beside the old copy instead of over it, and a rollback is a path
+ * change rather than a re-download.
+ *
+ * Every reader resolves through `resolveClioDirs()` rather than `clioDataDir()`
+ * because the latter creates the root, and doctor and the resolution ladder both
+ * promise to create nothing. Only the installer creates.
+ */
+
+/** `<data>/tools`, without creating it. */
+export function toolchainRoot(): string {
+	return join(resolveClioDirs().data, "tools");
+}
+
+/** `<data>/tools/<id>/<version>`, without creating it. */
+export function toolVersionDir(id: string, version: string): string {
+	return join(toolchainRoot(), id, version);
+}
+
+/** `<data>/tools/<id>/<version>/<binary>`, without creating it. */
+export function vendoredBinaryPath(id: string, version: string, binary: string): string {
+	return join(toolVersionDir(id, version), process.platform === "win32" ? `${binary}.exe` : binary);
+}
+
+/** `<data>/tools`, creating the data root the way every other writer does. */
+export function ensureToolchainRoot(): string {
+	return join(clioDataDir(), "tools");
+}