pi-profile-switch 0.3.1 → 0.4.2

package/src/launcher/model-check.ts

@@ -0,0 +1,52 @@
+/**
+ * Pre-spawn validation for a profile's declared model (ticket 02).
+ *
+ * Mirrors Pi's own session preflight: the model must resolve against the
+ * user's real model catalog (built-ins + models.json custom providers), and
+ * the provider must have configured auth (stored credential, static key, or
+ * ambient source). A missing or unauthenticated declared model fails
+ * activation before Pi is spawned, so a session never runs on an unexpected
+ * model.
+ *
+ * Note: Pi deliberately accepts unlisted model IDs under a known provider
+ * (custom/self-hosted models), so an unknown *provider* is the hard failure.
+ */
+
+import path from "node:path";
+
+import { ModelRuntime, resolveCliModel } from "@earendil-works/pi-coding-agent";
+
+import type { ProfileModel } from "../profile-catalog.ts";
+
+/** Returns an error message, or undefined when the model exists and is
+ *  authenticated. Reads the user's real agent dir state; never writes. */
+export async function checkDeclaredModel(agentDir: string, model: ProfileModel): Promise<string | undefined> {
+	const runtime = await ModelRuntime.create({
+		authPath: path.join(agentDir, "auth.json"),
+		modelsPath: path.join(agentDir, "models.json"),
+		modelsStorePath: path.join(agentDir, "models-store.json"),
+		refreshOnCreate: false,
+		allowModelNetwork: false,
+	});
+	const resolved = resolveCliModel({ cliModel: `${model.provider}/${model.id}`, modelRuntime: runtime });
+	if (resolved.error !== undefined) {
+		return resolved.error;
+	}
+	// resolveCliModel fuzzy-matches partial IDs; a stored profile must resolve
+	// to exactly the declared model (Pi's custom-model-id fallback also yields
+	// the declared ID verbatim, so exactness is compatible with it).
+	if (
+		resolved.model === undefined ||
+		resolved.model.id !== model.id ||
+		resolved.model.provider.toLowerCase() !== model.provider.toLowerCase()
+	) {
+		return `model not found: ${model.provider}/${model.id}`;
+	}
+	const authenticated =
+		runtime.hasConfiguredAuth(resolved.model.provider) ||
+		(await runtime.checkAuth(resolved.model.provider)) !== undefined;
+	if (!authenticated) {
+		return `no credentials configured for provider "${resolved.model.provider}"`;
+	}
+	return undefined;
+}

package/src/launcher/runtime-cleanup.ts

@@ -0,0 +1,85 @@
+/**
+ * RuntimeCleanup: sweeps stale per-launch runtime directories at startup.
+ *
+ * The generated agent dirs under `<agentDir>/pi-profile/runtime/launch-*`
+ * (ADR-0005) would otherwise accumulate forever. Startup sweep is the ONLY
+ * cleanup mechanism by design: any exit — graceful, signal, SIGKILL, power
+ * loss — kills the child pid, so the next launch's sweep converges. There is
+ * no exit-time deletion; it would only buy immediacy at the cost of deletion
+ * logic on the signal path.
+ *
+ * Liveness token: a `pid` file written by spawnPi into the runtime dir.
+ * (Naming the dir after the pid is impossible — the pid does not exist
+ * before spawn, and the running process's PI_CODING_AGENT_DIR path is
+ * frozen.) Rules per launch-* dir:
+ * - pid file parses and the process is alive (or EPERM) → keep;
+ *   ESRCH → delete.
+ * - no/unparsable pid file → delete only when the dir mtime is older than
+ *   NO_PID_GRACE_MS. The grace window guards the concurrent-launch race (a
+ *   second launcher between mkdtemp and its pid write must not be reaped);
+ *   it also covers pre-feature dirs and post-mkdtemp crashes.
+ * PID reuse needs no /proc check: a wrong keep only delays cleanup and
+ * self-heals once the reused pid dies.
+ *
+ * Everything is best-effort: sweep errors never block a launch.
+ */
+
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** Grace period for launch dirs without a (parseable) pid file. */
+export const NO_PID_GRACE_MS = 10 * 60 * 1000;
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means the process exists but is not signal-able by us: keep.
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function runtimeRootOf(agentDir: string): string {
+	return path.join(agentDir, "pi-profile", "runtime");
+}
+
+async function sweepEntry(dir: string): Promise<void> {
+	let pid: number | undefined;
+	try {
+		const raw = await readFile(path.join(dir, "pid"), "utf8");
+		const parsed = Number.parseInt(raw.trim(), 10);
+		if (Number.isInteger(parsed) && parsed > 0) pid = parsed;
+	} catch {
+		// No pid file (or unreadable): fall through to the mtime guard.
+	}
+
+	if (pid !== undefined) {
+		if (!isProcessAlive(pid)) await rm(dir, { recursive: true, force: true });
+		return;
+	}
+
+	const info = await stat(dir);
+	if (Date.now() - info.mtimeMs > NO_PID_GRACE_MS) {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+/** Deletes stale launch dirs under the agent dir's runtime root. Never throws. */
+export async function sweepStaleRuntimeDirs(agentDir: string): Promise<void> {
+	let entries: string[];
+	try {
+		entries = await readdir(runtimeRootOf(agentDir));
+	} catch {
+		return; // No runtime root yet: nothing to sweep.
+	}
+	for (const entry of entries) {
+		if (!entry.startsWith("launch-")) continue;
+		const dir = path.join(runtimeRootOf(agentDir), entry);
+		try {
+			if ((await stat(dir)).isDirectory()) await sweepEntry(dir);
+		} catch {
+			// Best-effort: one bad entry must not stop the sweep or the launch.
+		}
+	}
+}

package/src/launcher/spawn.ts

@@ -0,0 +1,82 @@
+/**
+ * Spawns the real `pi` binary as a subprocess (ADR-0005).
+ *
+ * The spawned pi gets: the pi-profile extension via `-e`, any generated
+ * flags, and the user's arguments verbatim. stdio is inherited so interactive
+ * TUI, RPC, and print modes all behave natively; exit codes and signals
+ * propagate.
+ */
+
+import { spawn } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { GeneratedRuntime } from "../settings-generator.ts";
+
+export interface SpawnPiOptions {
+	/** Generated runtime dir + env + flags. */
+	generated: GeneratedRuntime;
+	/** User arguments, forwarded verbatim. */
+	piArgs: string[];
+	/** Trust override recorded by the launcher; re-applied natively for the default profile. */
+	trustOverride: boolean | undefined;
+}
+
+const EXTENSION_ENTRY = fileURLToPath(new URL("../../extensions/pi-profile/index.ts", import.meta.url));
+
+/** Pure argv construction for the spawned pi: extension entry, generated
+ *  flags, trust re-application, then user args verbatim. */
+export function buildPiArgs(options: SpawnPiOptions): string[] {
+	const args = ["-e", EXTENSION_ENTRY, ...options.generated.flags];
+	// default profile keeps trust behavior native: re-apply the recorded flag.
+	if (options.trustOverride === true) args.push("--approve");
+	if (options.trustOverride === false) args.push("--no-approve");
+	args.push(...options.piArgs);
+	return args;
+}
+
+export async function spawnPi(options: SpawnPiOptions): Promise<number> {
+	const env = { ...process.env, ...options.generated.env };
+	delete env.PI_CODING_AGENT_SESSION_DIR;
+
+	const child = spawn("pi", buildPiArgs(options), {
+		stdio: "inherit",
+		env,
+	});
+
+	// Liveness token for the next launch's startup sweep (runtime-cleanup.ts).
+	// Best-effort: the dir was just written by generateRuntimeDir, so this can
+	// only fail under disk/permission trouble that would have surfaced earlier.
+	if (child.pid !== undefined) {
+		try {
+			await writeFile(path.join(options.generated.runtimeDir, "pid"), String(child.pid));
+		} catch (error) {
+			console.error(`pi-profile: warning: could not write pid file: ${(error as Error).message}`);
+		}
+	}
+
+	const onSigint = () => child.kill("SIGINT");
+	const onSigterm = () => child.kill("SIGTERM");
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+
+	try {
+		return await new Promise<number>((resolve, reject) => {
+			child.on("error", (error: NodeJS.ErrnoException) => {
+				if (error.code === "ENOENT") {
+					reject(new Error(`pi binary not found on PATH`));
+				} else {
+					reject(error);
+				}
+			});
+			child.on("exit", (code, signal) => {
+				if (code !== null) resolve(code);
+				else resolve(signal === "SIGINT" ? 130 : 1);
+			});
+		});
+	} finally {
+		process.off("SIGINT", onSigint);
+		process.off("SIGTERM", onSigterm);
+	}
+}

package/src/mcp-config.ts

@@ -1,32 +1,26 @@
 /**
- * AdapterConfigDiscovery: reads what pi-mcp-adapter would load from its
- * pi-native FILE sources — server names for reference validation, and the
- * "Pi global override" slot document for the generated overlay.
+ * AdapterConfigDiscovery: reads the MCP server NAMES pi-mcp-adapter would
+ * discover from its pi-native config files, without ever managing them.
  *
- * Discovery mirrors the adapter's own source order (later sources override
- * earlier ones): shared global MCP config, the two `.agents` globals, the Pi
- * global override slot (`--mcp-config`, else `<agentDir>/mcp.json`), then the
- * project's `.mcp.json` and `.pi/mcp.json` (project sources only when Pi
- * reports the project trusted — an untrusted project's config is never read).
+ * pi-profile never stores MCP connection parameters or credentials
+ * (ADR-0002); this module reads only the `mcpServers` key names so the
+ * launcher can validate a profile's `mcp` references before spawn.
  *
- * Not covered (documented limitation): the adapter's opt-in host discovery
- * (`~/.claude.json`, `~/.cursor/mcp.json`, …), package manifests (`pi.mcp`)
- * and agent/Claude plugin sources. Their servers are namespaced and cannot be
- * referenced by a profile today; the overlay still disables them when a name
- * happens to match one it knows.
- *
- * pi-profile-switch never writes these files and never exposes connection
- * parameters; the slot document is read only to be carried into the generated
- * overlay, because that file replaces the slot.
+ * Discovery scope (documented limitation): the pi-native files only — the
+ * global `<agentDir>/mcp.json` and, when trusted, the project's
+ * `.pi/mcp.json`. Servers defined solely in the adapter's editor-specific
+ * legacy locations (~/.claude/mcp.json et al.) are invisible here; profiles
+ * referencing them fail launch validation. The pi-native files are the
+ * adapter's documented default, and no in-session re-validation exists (the
+ * adapter's status snapshots arrive too late and only post-init), so the
+ * launch check is the only name validation — keep configs in the pi-native
+ * files.
  *
  * Malformed config files fail loudly — a broken mcp.json must not silently
  * read as "no servers" and reject every reference.
  */
 
-import { homedir } from "node:os";
-import path from "node:path";
-
-import { isRecord, readJsonFileSync } from "./json-file.ts";
+import { isRecord, readJsonFile } from "./json-file.ts";
 
 export class McpConfigError extends Error {
 	readonly filePath: string;
@@ -38,145 +32,35 @@ export class McpConfigError extends Error {
 	}
 }
 
-export interface AdapterMcpSource {
-	label: string;
-	filePath: string;
-	scope: "global" | "project";
-	/** True for the slot `--mcp-config` replaces. */
-	slot: boolean;
-}
-
-export interface AdapterMcpDiscoveryInput {
-	agentDir: string;
-	cwd: string;
-	projectTrusted: boolean;
-	/** The effective `--mcp-config` value, when one is in play. */
-	overridePath?: string;
-	/** Home directory override; tests point this at their fixture. */
-	homeDir?: string;
-}
-
-/** The adapter's file sources, in its own precedence order. Paths are
- *  de-duplicated: the adapter skips a source whose read path equals the slot. */
-export function adapterMcpSources(input: AdapterMcpDiscoveryInput): AdapterMcpSource[] {
-	const home = input.homeDir ?? homedir();
-	const slotPath = path.resolve(input.overridePath ?? path.join(input.agentDir, "mcp.json"));
-	const candidates: AdapterMcpSource[] = [
-		{ label: "shared global MCP config", filePath: path.join(home, ".config", "mcp", "mcp.json"), scope: "global", slot: false },
-		{ label: ".agents MCP config", filePath: path.join(home, ".agents", "mcp.json"), scope: "global", slot: false },
-		{ label: ".agents/mcp MCP config", filePath: path.join(home, ".agents", "mcp", "mcp.json"), scope: "global", slot: false },
-		{ label: "Pi global MCP override", filePath: slotPath, scope: "global", slot: true },
-	];
-	if (input.projectTrusted) {
-		candidates.push(
-			{ label: "project MCP config", filePath: path.resolve(input.cwd, ".mcp.json"), scope: "project", slot: false },
-			{ label: "project Pi MCP override", filePath: path.resolve(input.cwd, ".pi", "mcp.json"), scope: "project", slot: false },
-		);
-	}
-	const seen = new Set<string>();
-	return candidates.filter((source) => {
-		if (source.slot) return true; // the slot is always the read path
-		if (seen.has(source.filePath)) return false;
-		seen.add(source.filePath);
-		return true;
-	});
-}
-
-export interface AdapterMcpView {
-	/** Read path of the slot `--mcp-config` replaces. */
-	slotPath: string;
-	/** Parsed slot document (verbatim), when the file exists. */
-	slotDocument?: Record<string, unknown>;
-	slotNames: string[];
-	/** Server names from the other file sources. */
-	otherNames: string[];
-	/** Union of slot and other names, sorted. */
-	serverNames: string[];
-}
-
-/** Synchronous read: the extension-load pass must finish before the adapter's
- *  session initialization, and the files are tiny. */
-export function readAdapterMcpViewSync(input: AdapterMcpDiscoveryInput): AdapterMcpView {
-	const sources = adapterMcpSources(input);
-	const slot = sources.find((source) => source.slot);
-	const slotPath = slot?.filePath ?? path.join(input.agentDir, "mcp.json");
-	let slotDocument: Record<string, unknown> | undefined;
-	const slotNames: string[] = [];
-	const otherNames = new Set<string>();
-	for (const source of sources) {
-		if (source.slot) {
-			const document = readMcpDocumentSync(source.filePath);
-			if (document === undefined) continue;
-			slotDocument = document;
-			slotNames.push(...serverNames(document, source.filePath));
-			continue;
-		}
-		const document = readMcpDocumentSync(source.filePath);
-		if (document === undefined) continue;
-		for (const name of serverNames(document, source.filePath)) otherNames.add(name);
-	}
-	for (const name of slotNames) otherNames.delete(name);
-	return {
-		slotPath,
-		...(slotDocument === undefined ? {} : { slotDocument }),
-		slotNames,
-		otherNames: [...otherNames].sort(),
-		serverNames: [...new Set([...slotNames, ...otherNames])].sort(),
-	};
-}
-
-/** Async twin for the runtime paths (selection, status, toggles). */
-export async function readAdapterMcpView(input: AdapterMcpDiscoveryInput): Promise<AdapterMcpView> {
-	return readAdapterMcpViewSync(input);
-}
-
-/** Server names from every source EXCEPT the slot file. The slot is generated
- *  by pi-profile-switch, so it must not feed back into the next generation —
- *  otherwise a stub would look like a source server and vanish on the next
- *  write. */
-export function readAdapterOtherServerNamesSync(input: AdapterMcpDiscoveryInput): string[] {
-	const names = new Set<string>();
-	for (const source of adapterMcpSources(input)) {
-		if (source.slot) continue;
-		const document = readMcpDocumentSync(source.filePath);
-		if (document === undefined) continue;
-		for (const name of serverNames(document, source.filePath)) names.add(name);
-	}
-	return [...names].sort();
-}
-
-/** Server names the adapter would discover. `projectDir` is passed only when
- *  the trust check passed. */
-export async function discoverAdapterServerNames(
-	agentDir: string,
-	projectDir?: string,
-	homeDir?: string,
-): Promise<string[]> {
-	return readAdapterMcpViewSync({
-		agentDir,
-		cwd: projectDir ?? process.cwd(),
-		projectTrusted: projectDir !== undefined,
-		...(homeDir === undefined ? {} : { homeDir }),
-	}).serverNames;
-}
-
-/** Missing file → undefined; malformed → McpConfigError. */
-export function readMcpDocumentSync(filePath: string): Record<string, unknown> | undefined {
-	const result = readJsonFileSync(filePath);
+async function readServerNames(filePath: string): Promise<string[]> {
+	const result = await readJsonFile(filePath);
 	if (!result.ok) {
-		if (result.reason === "missing") return undefined;
+		if (result.reason === "missing") {
+			return [];
+		}
 		throw new McpConfigError(`MCP config is not valid JSON: ${filePath}`, filePath);
 	}
 	if (!isRecord(result.value)) {
 		throw new McpConfigError(`MCP config must be a JSON object: ${filePath}`, filePath);
 	}
-	return result.value;
+	if (result.value.mcpServers === undefined) {
+		return [];
+	}
+	if (!isRecord(result.value.mcpServers)) {
+		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
+	}
+	return Object.keys(result.value.mcpServers);
 }
 
-function serverNames(document: Record<string, unknown>, filePath: string): string[] {
-	if (document.mcpServers === undefined) return [];
-	if (!isRecord(document.mcpServers)) {
-		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
+/** Server names the adapter would discover: global agentDir config plus the
+ *  trusted project's config. Pass `projectDir` only when the trust check
+ *  passed — an untrusted project's config is never read. */
+export async function discoverAdapterServerNames(agentDir: string, projectDir?: string): Promise<string[]> {
+	const names = new Set(await readServerNames(`${agentDir}/mcp.json`));
+	if (projectDir !== undefined) {
+		for (const name of await readServerNames(`${projectDir}/.pi/mcp.json`)) {
+			names.add(name);
+		}
 	}
-	return Object.keys(document.mcpServers);
+	return [...names].sort();
 }

package/src/mcp-coordination.ts

@@ -1,25 +1,26 @@
 /**
- * McpCoordination: the pi-profile-switch ↔ pi-mcp-adapter contract (ADR-0002).
+ * McpCoordination: the pi-profile ↔ pi-mcp-adapter contract (ADR-0002).
  *
  * The adapter's released versions (≤2.33) offer no in-memory server
- * allowlist, so pi-profile-switch defines the coordination channel the locked
+ * allowlist, so pi-profile defines the coordination channel the locked
  * adapter implements:
  *
- * - pi-profile-switch publishes the active profile's runtime server allowlist on
- *   `pi-profile:mcp-allowlist:v1` at activation (session start, `/profile
- *   use`, `customize`/`reset`, `/mcp enable|disable`). The allowlist is
- *   memory-only: pi-profile-switch never writes the adapter's `.pi/mcp.json`.
+ * - pi-profile publishes the active profile's runtime server allowlist on
+ *   `pi-profile:mcp-allowlist:v1` at session start (and after every profile
+ *   switch reload, ticket 05). The allowlist is memory-only: pi-profile
+ *   never writes the adapter's `.pi/mcp.json` overlay.
  * - Adapter presence is probed via the adapter's documented
  *   request/result event pattern: emit a snapshot request for a bogus
  *   server name; an installed adapter fills `request.result` synchronously
  *   (with `{ok: false}` — the name is bogus), an absent adapter leaves it
  *   undefined.
  *
- * Activation probes the adapter and refuses a profile whose declared MCP
- * intent cannot be satisfied before applying anything.
+ * Launch-time, the launcher additionally refuses to spawn when a profile
+ * declares `mcp` but no active extension identifies as the adapter
+ * (`isAdapterExtension`) — failing before spawn beats failing in-session.
  */
 
-/** pi-profile-switch's allowlist channel (the locked adapter subscribes). */
+/** pi-profile's allowlist channel (the locked adapter subscribes). */
 export const MCP_ALLOWLIST_EVENT = "pi-profile:mcp-allowlist:v1";
 export const MCP_ALLOWLIST_VERSION = 1 as const;
 
@@ -30,10 +31,28 @@ export interface McpAllowlistMessage {
 }
 
 /** The adapter's snapshot channel, used here purely as a presence probe
- *  (see the module docblock). Kept as a literal so pi-profile-switch doesn't
+ *  (see the module docblock). Kept as a literal so pi-profile doesn't
  *  import adapter internals. */
 export const MCP_ADAPTER_SNAPSHOT_EVENT = "pi-mcp-adapter:runtime-snapshot:v1";
 
+export class MissingMcpAdapterError extends Error {
+	constructor(profile: string) {
+		super(
+			`profile "${profile}" declares MCP servers but pi-mcp-adapter is not active. ` +
+				`Select the adapter in the profile's extensions (e.g. via its npm package) or remove the "mcps" declaration.`,
+		);
+		this.name = "MissingMcpAdapterError";
+	}
+}
+
+/** Identifies the adapter among active extension entries by its install
+ *  path containing "pi-mcp-adapter" (npm package roots and local dirs both
+ *  match). Heuristic by design — activation-plan entries carry no package
+ *  source string, and the in-session probe is the authoritative check. */
+export function isAdapterExtension(entry: { entry: string }): boolean {
+	return entry.entry.includes("pi-mcp-adapter");
+}
+
 /** True when the adapter answered the probe (filled `result` on the
  *  request object), regardless of the answer — presence, not health. */
 export function probeAdapterPresence(events: { emit(channel: string, data: unknown): void }): boolean {

package/src/profile-catalog-store.ts

@@ -1,12 +1,11 @@
 /**
- * ProfileCatalogStore: the WRITE side of a profile catalog file, kept
- * separate from the read-only ProfileCatalog.
+ * ProfileCatalogStore: the WRITE side of a profile catalog file
+ * (ticket 09), kept separate from the read-only ProfileCatalog.
  *
  * Invariants:
- * - Whole-file overwrites (pretty-printed, `schemaVersion 1` envelope, the
- *   constant owned by profile-catalog.ts). Wizard saves never block on
- *   concurrent edits — re-read at write time, same-name conflicts resolve
- *   last-write-wins.
+ * - Whole-file overwrites (pretty-printed, schemaVersion envelope);
+ *   wizard saves never block on concurrent edits — re-read at write time,
+ *   same-name conflicts resolve last-write-wins.
  * - Definitions are complete and self-contained: no inheritance fields
  *   (`extends`, merge, array append) exist or are accepted.
  * - Definitions are re-parsed through the catalog's own
@@ -22,7 +21,6 @@ import { isRecord, readJsonFile } from "./json-file.ts";
 import {
 	CatalogError,
 	DEFAULT_PROFILE_NAME,
-	parseCatalogDocument,
 	parseProfileDefinition,
 	PROFILE_SCHEMA_VERSION,
 	type ProfileDefinition,
@@ -30,16 +28,20 @@ import {
 
 export class ProfileCatalogStore {
 	readonly #filePath: string;
+	readonly #fallbackPath?: string;
 
-	constructor(catalogPath: string) {
+	constructor(catalogPath: string, fallbackPath?: string) {
 		this.#filePath = catalogPath;
+		this.#fallbackPath = fallbackPath;
 	}
 
 	/** Validated definitions: missing file → empty; malformed → CatalogError
-	 *  (catalog errors never pass silently, even on the write path).
-	 *  Unknown fields (an `extensions` key left over from v0.1.0) are dropped. */
+	 *  (catalog errors never pass silently, even on the write path). */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
-		const result = await readJsonFile(this.#filePath);
+		let result = await readJsonFile(this.#filePath);
+		if (!result.ok && result.reason === "missing" && this.#fallbackPath) {
+			result = await readJsonFile(this.#fallbackPath);
+		}
 		if (!result.ok) {
 			if (result.reason === "missing") return new Map();
 			throw new CatalogError(`invalid JSON in ${this.#filePath}`);
@@ -47,7 +49,24 @@ export class ProfileCatalogStore {
 		if (!isRecord(result.value)) {
 			throw new CatalogError(`${this.#filePath}: catalog must be an object`);
 		}
-		return parseCatalogDocument(result.value, this.#filePath);
+		if (result.value.schemaVersion !== PROFILE_SCHEMA_VERSION) {
+			throw new CatalogError(
+				`${this.#filePath}: unsupported schemaVersion ${JSON.stringify(result.value.schemaVersion)} (expected ${PROFILE_SCHEMA_VERSION})`,
+			);
+		}
+		if (!isRecord(result.value.profiles)) {
+			throw new CatalogError(`${this.#filePath}: "profiles" must be an object mapping names to definitions`);
+		}
+		const definitions = new Map<string, ProfileDefinition>();
+		for (const [name, raw] of Object.entries(result.value.profiles)) {
+			if (name === DEFAULT_PROFILE_NAME) {
+				throw new CatalogError(
+					`${this.#filePath}: "${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`,
+				);
+			}
+			definitions.set(name, parseProfileDefinition(name, raw));
+		}
+		return definitions;
 	}
 
 	/** Overwrites the file with the given definitions (last write wins). */