@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/share/archive.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, type Stats, statSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { type ClioSettings, readSettings, settingsPath, updateSettings } from "../../core/config.js";
+import { type ClioSettings, readSettings, settingsPath, updateSettings, validateSettings } from "../../core/config.js";
 import { DEFAULT_SETTINGS } from "../../core/defaults.js";
 import { readClioVersion } from "../../core/package-root.js";
 import {
@@ -18,6 +18,7 @@ import {
 	parseAgentRecipeSchema,
 	parseFleetContract,
 } from "../agents/index.js";
+import { migrateSettingsV1Document } from "../lifecycle/migrations/2026-09-01-settings-v2.js";
 
 export type ShareScope = "project" | "user";
 export type ShareEntryType = "project-context" | "prompt" | "skill" | "agent" | "fleet" | "settings" | "extension";
@@ -43,14 +44,14 @@ export interface ShareArchiveManifestFile {
 }
 
 export interface ShareArchiveManifest {
-	format: "clio.share.v1";
-	clioVersion: string;
+	format: "clio-coder.share.v1";
+	clioCoderVersion: string;
 	createdAt: string;
 	files: ShareArchiveManifestFile[];
 }
 
 export interface ClioShareArchive {
-	kind: "clio-share-archive";
+	kind: "clio-coder-share-archive";
 	formatVersion: 1;
 	manifest: ShareArchiveManifest;
 	files: ShareArchiveFile[];
@@ -194,17 +195,49 @@ function addTree(
 
 function settingsFragment(settings: Readonly<ClioSettings>): Record<string, unknown> {
 	return {
-		autonomy: settings.autonomy,
-		scope: settings.scope,
-		budget: settings.budget,
-		theme: settings.theme,
-		terminal: settings.terminal,
-		keybindings: settings.keybindings,
-		compaction: settings.compaction,
-		retry: settings.retry,
+		version: 2,
+		chat: {
+			modelPicker: { cycleSet: [...settings.chat.modelPicker.cycleSet] },
+			retry: structuredClone(settings.chat.retry),
+		},
+		fleet: { concurrency: settings.fleet.concurrency },
+		context: { compaction: structuredClone(settings.context.compaction) },
+		safety: {
+			autonomy: settings.safety.autonomy,
+			limits: { sessionCostUsd: settings.safety.limits.sessionCostUsd },
+		},
+		interface: structuredClone(settings.interface),
 	};
 }
 
+const SETTINGS_FRAGMENT_ROOTS = ["chat", "fleet", "context", "safety", "interface"] as const;
+
+function normalizedSettingsFragment(parsed: unknown): Record<string, unknown> {
+	if (!isRecord(parsed)) throw new Error("settings fragment must be a YAML object");
+	let normalized = parsed;
+	if (parsed.version === undefined || parsed.version === 1) {
+		normalized = migrateSettingsV1Document(parsed).document;
+	} else if (parsed.version !== 2) {
+		throw new Error(`settings fragment version must be 1 or 2, got ${String(parsed.version)}`);
+	}
+	const validation = validateSettings(normalized);
+	if (validation.issues.length > 0) {
+		throw new Error(
+			`invalid settings fragment: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+		);
+	}
+	return normalized;
+}
+
+function mergeFragmentValue(current: unknown, fragment: unknown): unknown {
+	if (!isRecord(current) || !isRecord(fragment)) return structuredClone(fragment);
+	const merged: Record<string, unknown> = { ...current };
+	for (const [key, value] of Object.entries(fragment)) {
+		merged[key] = mergeFragmentValue(merged[key], value);
+	}
+	return merged;
+}
+
 function requestedScopes(scope: ShareExportOptions["scope"]): ShareScope[] {
 	if (scope === "both") return ["project", "user"];
 	return [scope ?? "project"];
@@ -314,11 +347,11 @@ export function createShareArchive(options: ShareExportOptions = {}): ClioShareA
 
 	const manifestFiles = files.map(({ data: _data, encoding: _encoding, ...entry }) => entry);
 	return {
-		kind: "clio-share-archive",
+		kind: "clio-coder-share-archive",
 		formatVersion: 1,
 		manifest: {
-			format: "clio.share.v1",
-			clioVersion: readClioVersion(),
+			format: "clio-coder.share.v1",
+			clioCoderVersion: readClioVersion(),
 			createdAt: new Date().toISOString(),
 			files: manifestFiles,
 		},
@@ -337,13 +370,33 @@ function decodeArchiveFile(entry: ShareArchiveFile): Buffer {
 }
 
 function parseArchive(raw: unknown): ClioShareArchive {
-	if (!isRecord(raw) || raw.kind !== "clio-share-archive" || raw.formatVersion !== 1 || !isRecord(raw.manifest)) {
+	if (
+		!isRecord(raw) ||
+		(raw.kind !== "clio-coder-share-archive" && raw.kind !== "clio-share-archive") ||
+		raw.formatVersion !== 1 ||
+		!isRecord(raw.manifest)
+	) {
 		throw new Error("not a Clio share archive v1");
 	}
-	if (raw.manifest.format !== "clio.share.v1" || !Array.isArray(raw.files)) {
+	if (
+		(raw.manifest.format !== "clio-coder.share.v1" && raw.manifest.format !== "clio.share.v1") ||
+		!Array.isArray(raw.files)
+	) {
 		throw new Error("share archive manifest is malformed");
 	}
-	const archive = raw as unknown as ClioShareArchive;
+	const clioCoderVersion = raw.manifest.clioCoderVersion ?? raw.manifest.clioVersion;
+	if (typeof clioCoderVersion !== "string") throw new Error("share archive manifest is malformed");
+	const archive: ClioShareArchive = {
+		kind: "clio-coder-share-archive",
+		formatVersion: 1,
+		manifest: {
+			format: "clio-coder.share.v1",
+			clioCoderVersion,
+			createdAt: raw.manifest.createdAt as string,
+			files: raw.manifest.files as ShareArchiveManifestFile[],
+		},
+		files: raw.files as ShareArchiveFile[],
+	};
 	const allowedTypes = new Set<ShareEntryType>([
 		"project-context",
 		"prompt",
@@ -558,12 +611,12 @@ function preflightImportTargets(
 function versionDiagnostics(archive: ClioShareArchive): ShareDiagnostic[] {
 	const current = readClioVersion();
 	const [curMajor, curMinor] = current.split(".");
-	const [arcMajor, arcMinor] = archive.manifest.clioVersion.split(".");
+	const [arcMajor, arcMinor] = archive.manifest.clioCoderVersion.split(".");
 	if (curMajor !== arcMajor || curMinor !== arcMinor) {
 		return [
 			{
 				type: "warning",
-				message: `archive was created by Clio ${archive.manifest.clioVersion}; current Clio is ${current}`,
+				message: `archive was created by Clio ${archive.manifest.clioCoderVersion}; current Clio is ${current}`,
 			},
 		];
 	}
@@ -571,12 +624,18 @@ function versionDiagnostics(archive: ClioShareArchive): ShareDiagnostic[] {
 }
 
 function settingsPlan(buffer: Buffer, options: ShareImportOptions): ShareDiagnostic[] {
-	const parsed = parseYaml(buffer.toString("utf8")) as unknown;
-	if (!isRecord(parsed)) return [{ type: "error", message: "settings fragment must be a YAML object" }];
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = normalizedSettingsFragment(parseYaml(buffer.toString("utf8")) as unknown);
+	} catch (error) {
+		return [{ type: "error", message: error instanceof Error ? error.message : String(error) }];
+	}
 	const settingsTarget = settingsFilePath();
 	const current = settingsFragment(existsSync(settingsTarget) ? readSettings() : DEFAULT_SETTINGS);
 	const diagnostics: ShareDiagnostic[] = [];
-	for (const [key, value] of Object.entries(parsed)) {
+	for (const [key, value] of Object.entries(parsed).filter(([key]) =>
+		(SETTINGS_FRAGMENT_ROOTS as ReadonlyArray<string>).includes(key),
+	)) {
 		if (key in current && JSON.stringify(current[key]) !== JSON.stringify(value)) {
 			diagnostics.push({
 				type: "conflict",
@@ -664,25 +723,15 @@ export function planShareImport(filePath: string, options: ShareImportOptions =
 }
 
 function mergeSettingsFragment(buffer: Buffer): string {
-	const parsed = parseYaml(buffer.toString("utf8")) as unknown;
-	if (!isRecord(parsed)) throw new Error("settings fragment must be a YAML object");
+	const parsed = normalizedSettingsFragment(parseYaml(buffer.toString("utf8")) as unknown);
 	// Single-writer rule: the merge goes through updateSettings (lock + strict
 	// re-validation), so an invalid fragment throws here instead of landing on
 	// disk. No backup sidecar: settings.yaml is machine-owned and versioned by
 	// the importer's own plan/diagnostics flow.
 	updateSettings((settings) => {
 		const next = settings as unknown as Record<string, unknown>;
-		for (const key of [
-			"autonomy",
-			"scope",
-			"budget",
-			"theme",
-			"terminal",
-			"keybindings",
-			"compaction",
-			"retry",
-		] as const) {
-			if (key in parsed) next[key] = parsed[key];
+		for (const key of SETTINGS_FRAGMENT_ROOTS) {
+			if (key in parsed) next[key] = mergeFragmentValue(next[key], parsed[key]);
 		}
 	});
 	return settingsPath();

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";