@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/share/archive.ts

@@ -1,8 +1,20 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, type Stats, statSync } from "node:fs";
+import {
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	type Stats,
+	statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 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 +30,11 @@ import {
 	parseAgentRecipeSchema,
 	parseFleetContract,
 } from "../agents/index.js";
+import { loadManifestFromRoot } from "../extensions/discovery.js";
+import { extensionContentDigest } from "../extensions/integrity.js";
+import { extensionBaseDir, installExtension, listInstalledExtensions } from "../extensions/state.js";
+import type { ExtensionScope } from "../extensions/types.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 +60,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 +211,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"];
@@ -298,7 +347,14 @@ export function createShareArchive(options: ShareExportOptions = {}): ClioShareA
 		for (const scope of scopes) {
 			const root =
 				scope === "user" ? path.join(clioConfigDir(), "extensions") : path.join(cwd, ".clio-coder", "extensions");
-			addTree(files, "extension", scope, root, `${scope}/extensions`, (rel) => path.basename(rel) !== "state.json");
+			addTree(
+				files,
+				"extension",
+				scope,
+				root,
+				`${scope}/extensions`,
+				(relativePath) => !relativePath.split("/")[0]?.startsWith(".") && path.basename(relativePath) !== "state.json",
+			);
 		}
 	}
 	if (includes.includeSettings) {
@@ -314,11 +370,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 +393,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",
@@ -400,6 +476,15 @@ interface ShareImportPreparedPlan {
 	actions: ShareImportAction[];
 	diagnostics: ShareDiagnostic[];
 	targets: ShareImportPreparedTarget[];
+	extensionPackages: ShareImportPreparedExtensionPackage[];
+}
+
+interface ShareImportPreparedExtensionPackage {
+	id: string;
+	scope: ExtensionScope;
+	files: Array<{ relativePath: string; buffer: Buffer }>;
+	contentDigest: string;
+	install: boolean;
 }
 
 function configDirPath(): string {
@@ -555,15 +640,100 @@ function preflightImportTargets(
 	return { targets, diagnostics };
 }
 
+function withStagedExtensionPackage<T>(
+	input: { id: string; files: ReadonlyArray<{ relativePath: string; buffer: Buffer }> },
+	fn: (root: string) => T,
+): T {
+	const stagingParent = mkdtempSync(path.join(tmpdir(), "clio-share-extension-"));
+	const root = path.join(stagingParent, input.id);
+	try {
+		mkdirSync(root, { recursive: true });
+		for (const file of input.files) safeResourceWrite(path.join(root, file.relativePath), file.buffer);
+		return fn(root);
+	} finally {
+		rmSync(stagingParent, { recursive: true, force: true });
+	}
+}
+
+function prepareExtensionPackages(
+	targets: ReadonlyArray<ShareImportPreparedTarget>,
+	options: ShareImportOptions,
+): { packages: ShareImportPreparedExtensionPackage[]; diagnostics: ShareDiagnostic[] } {
+	const diagnostics: ShareDiagnostic[] = [];
+	const grouped = new Map<string, Omit<ShareImportPreparedExtensionPackage, "contentDigest" | "install">>();
+	for (const target of targets) {
+		if (target.entry.type !== "extension") continue;
+		const segments = relativePathSegments(target.entry.relativePath);
+		const id = segments?.[0];
+		const packagePath = segments?.slice(1).join("/");
+		if (!id || !packagePath) {
+			diagnostics.push({
+				type: "error",
+				message: `extension archive path must be <id>/<package-path>: ${pathDiagnostic(target.entry)}`,
+				path: target.entry.relativePath,
+			});
+			continue;
+		}
+		const scope = target.scope as ExtensionScope;
+		const key = `${scope}\0${id}`;
+		const group = grouped.get(key) ?? { id, scope, files: [] };
+		if (group.files.some((file) => file.relativePath === packagePath)) {
+			diagnostics.push({ type: "error", message: `duplicate extension archive path ${target.entry.relativePath}` });
+			continue;
+		}
+		group.files.push({ relativePath: packagePath, buffer: target.buffer });
+		grouped.set(key, group);
+	}
+
+	const packages: ShareImportPreparedExtensionPackage[] = [];
+	for (const group of [...grouped.values()].sort((a, b) => `${a.scope}/${a.id}`.localeCompare(`${b.scope}/${b.id}`))) {
+		try {
+			const contentDigest = withStagedExtensionPackage(group, (root) => {
+				const candidate = loadManifestFromRoot(root);
+				if (!candidate.valid || !candidate.manifest) {
+					throw new Error(candidate.diagnostics.map((diagnostic) => diagnostic.message).join("; ") || "manifest is invalid");
+				}
+				if (candidate.manifest.id !== group.id) {
+					throw new Error(`manifest id ${candidate.manifest.id} does not match archive package ${group.id}`);
+				}
+				return extensionContentDigest(root);
+			});
+			const cwd = path.resolve(options.cwd ?? process.cwd());
+			const targetRoot = path.join(extensionBaseDir(group.scope, cwd), group.id);
+			const existing = listInstalledExtensions(cwd, { scope: group.scope, all: true }).find(
+				(extension) => extension.id === group.id && extension.rootPath === targetRoot,
+			);
+			const alreadyVerified =
+				existing?.valid === true &&
+				existing.provenance?.contentDigest === contentDigest &&
+				existing.observedContentDigest === contentDigest;
+			if (existsSync(targetRoot) && !alreadyVerified && !options.force) {
+				diagnostics.push({
+					type: "conflict",
+					message: `extension ${group.id} is not already installed with the archive's verified digest; re-run with --force to use the canonical installer`,
+					path: targetRoot,
+				});
+			}
+			packages.push({ ...group, contentDigest, install: !alreadyVerified });
+		} catch (error) {
+			diagnostics.push({
+				type: "error",
+				message: `extension ${group.id} in share archive is invalid: ${error instanceof Error ? error.message : String(error)}`,
+			});
+		}
+	}
+	return { packages, diagnostics };
+}
+
 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 +741,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",
@@ -598,13 +774,20 @@ function prepareShareImport(filePath: string, options: ShareImportOptions = {}):
 			actions: [],
 			diagnostics: [{ type: "error", message: err instanceof Error ? err.message : String(err), path: filePath }],
 			targets: [],
+			extensionPackages: [],
 		};
 	}
 	const diagnostics: ShareDiagnostic[] = [...versionDiagnostics(archive)];
 	const actions: ShareImportAction[] = [];
 	const preflight = preflightImportTargets(archive, options);
 	if (preflight.diagnostics.length > 0) {
-		return { archive, actions: [], diagnostics: [...diagnostics, ...preflight.diagnostics], targets: [] };
+		return {
+			archive,
+			actions: [],
+			diagnostics: [...diagnostics, ...preflight.diagnostics],
+			targets: [],
+			extensionPackages: [],
+		};
 	}
 	for (const targetInfo of preflight.targets) {
 		const { entry, target, scope, buffer } = targetInfo;
@@ -647,7 +830,9 @@ function prepareShareImport(filePath: string, options: ShareImportOptions = {}):
 		}
 		actions.push({ action: "write", type: entry.type, scope, path: target });
 	}
-	return { archive, actions, diagnostics, targets: preflight.targets };
+	const extensions = prepareExtensionPackages(preflight.targets, options);
+	diagnostics.push(...extensions.diagnostics);
+	return { archive, actions, diagnostics, targets: preflight.targets, extensionPackages: extensions.packages };
 }
 
 function publicImportPlan(prepared: ShareImportPreparedPlan, recovery?: ShareImportRecovery): ShareImportPlan {
@@ -664,25 +849,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();
@@ -701,10 +876,41 @@ export function importShareArchive(filePath: string, options: ShareImportOptions
 	};
 	let failed: string | undefined;
 	try {
+		for (const extensionPackage of prepared.extensionPackages) {
+			if (!extensionPackage.install) continue;
+			const cwd = path.resolve(options.cwd ?? process.cwd());
+			failed = path.join(extensionBaseDir(extensionPackage.scope, cwd), extensionPackage.id);
+			const result = withStagedExtensionPackage(extensionPackage, (root) =>
+				installExtension(root, {
+					cwd,
+					scope: extensionPackage.scope,
+					...(options.force !== undefined ? { force: options.force } : {}),
+				}),
+			);
+			for (const backup of [result.recovery?.stateBackup, result.recovery?.packageBackup]) {
+				if (backup && !backups.includes(backup)) backups.push(backup);
+			}
+			const errors = result.diagnostics.filter((diagnostic) => diagnostic.type === "error");
+			if (!result.extension || errors.length > 0) {
+				throw new Error(errors.map((diagnostic) => diagnostic.message).join("; ") || "canonical install failed");
+			}
+			if (result.extension.provenance?.contentDigest !== extensionPackage.contentDigest) {
+				throw new Error(`canonical install digest mismatch for extension ${extensionPackage.id}`);
+			}
+			for (const diagnostic of result.diagnostics) {
+				prepared.diagnostics.push({
+					type: "warning",
+					message: diagnostic.message,
+					...(diagnostic.path ? { path: diagnostic.path } : {}),
+				});
+			}
+			if (!written.includes(result.extension.rootPath)) written.push(result.extension.rootPath);
+			failed = undefined;
+		}
 		for (let index = 0; index < prepared.targets.length; index += 1) {
 			const targetInfo = prepared.targets[index];
 			const action = prepared.actions[index];
-			if (!targetInfo || !action || action.action === "skip") continue;
+			if (!targetInfo || !action || action.action === "skip" || targetInfo.entry.type === "extension") continue;
 			failed = targetInfo.target;
 			if (targetInfo.entry.type === "settings") {
 				const path = mergeSettingsFragment(targetInfo.buffer);
@@ -719,7 +925,7 @@ export function importShareArchive(filePath: string, options: ShareImportOptions
 			);
 			failed = undefined;
 		}
-		return plan;
+		return publicImportPlan(prepared, backups.length > 0 ? { written, backups } : undefined);
 	} catch (err) {
 		if (failed) {
 			const expectedBackup = safeResourceBackupPath(failed);
@@ -738,7 +944,7 @@ export function importShareArchive(filePath: string, options: ShareImportOptions
 					...prepared.diagnostics,
 					{
 						type: "error",
-						message: `share import failed while writing${failed ? ` ${failed}` : ""}: ${reason}`,
+						message: `share import failed${failed ? ` while importing ${failed}` : ""}: ${reason}`,
 						...(failed ? { path: failed } : {}),
 					},
 				],

package/src/domains/toolchain/install.ts

@@ -191,7 +191,7 @@ export async function installPinnedTool(
 			documents.push(join(dir, name));
 		}
 		writeFileSync(
-			join(staging, "clio-install.json"),
+			join(staging, "clio-coder-install.json"),
 			`${JSON.stringify(
 				{
 					id: entry.id,

package/src/engine/acp/adapter.ts

@@ -32,7 +32,7 @@ export interface AcpDelegationRunInput {
 	dynamicPromptMessages?: ReadonlyArray<{ body: string }>;
 	cwd: string;
 	safety: SafetyContract;
-	/** Session autonomy level applied by the mediator under clio-policy governance. */
+	/** Session autonomy level applied by the mediator under clio-coder-policy governance. */
 	autonomy?: AutonomyLevel;
 	signal?: AbortSignal;
 	clientVersion?: string;
@@ -223,11 +223,11 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 	const mediator = new AcpToolMediator({
 		safety: input.safety,
 		cwd: input.cwd,
-		toolGovernance: input.agent.toolGovernance ?? "clio-policy",
+		toolGovernance: input.agent.toolGovernance ?? "clio-coder-policy",
 		...(input.autonomy !== undefined ? { autonomy: input.autonomy } : {}),
 		onPermissionResolved: (event) =>
 			emit({
-				type: "clio_permission_resolved",
+				type: "clio_coder_permission_resolved",
 				payload: event,
 			} as ClioWorkerEvent),
 	});

package/src/engine/acp/event-mapper.ts

@@ -74,7 +74,7 @@ export class AcpEventMapper {
 			return this.mapToolUpdate(update as AcpToolCallUpdate);
 		}
 		if (kind === "plan") {
-			return [{ type: "clio_plan_update", payload: update } as unknown as AgentEvent];
+			return [{ type: "clio_coder_plan_update", payload: update } as unknown as AgentEvent];
 		}
 		return [];
 	}
@@ -116,7 +116,7 @@ export class AcpEventMapper {
 			// operator surface. The descriptor composed from it here does.
 			const action = describeCallAction(update.kind ?? title, update.rawInput);
 			out.push({
-				type: "clio_tool_start",
+				type: "clio_coder_tool_start",
 				payload: {
 					tool: update.kind ?? title,
 					toolCallId,
@@ -145,7 +145,7 @@ export class AcpEventMapper {
 				isError,
 			} as unknown as AgentEvent);
 			out.push({
-				type: "clio_tool_finish",
+				type: "clio_coder_tool_finish",
 				payload: {
 					tool: update.kind ?? title,
 					toolCallId,