pi-profile-switch 0.6.0 → 0.8.0

package/src/launcher/runtime-cleanup.ts

@@ -21,19 +21,21 @@
  * PID reuse needs no /proc check: a wrong keep only delays cleanup and
  * self-heals once the reused pid dies.
  *
- * A candidate is deleted only when every entry in it is pi-profile's own: a
- * symlink (the mirror's link into the real agent dir) or a managed generated
- * file. Anything else is state an extension created at runtime, so the
- * directory is kept and reported — the sweep never destroys data it cannot
- * attribute. The check deliberately does NOT consult the real agent dir: a
- * same-named entry there (a seeded `missions`, say) must not turn an
- * instance-local real directory into a deletable one.
+ * A candidate is reclaimed only when every entry in it is pi-profile's own
+ * or has been dispositioned away. Unrecognized entries (state an extension
+ * created at runtime) get one of three dispositions per entry (ADR-0012):
+ * content that references the instance dir's own path, exceeds the scan
+ * budget, or is not a regular file/dir is kept and reported; position-
+ * independent content is renamed into the real agent dir (adopted), or
+ * deleted when the real agent dir already holds that name (real wins — the
+ * conflict window means the instance copy is never the authority). The sweep
+ * never destroys data it cannot attribute.
  *
  * Everything is best-effort: sweep errors never block a launch.
  */
 
 import type { Dirent } from "node:fs";
-import { lstat, readdir, readFile, rm, stat } from "node:fs/promises";
+import { lstat, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 
 import { MANAGED_INSTANCE_FILES } from "../settings-generator.ts";
@@ -49,6 +51,29 @@ export const NO_PID_GRACE_MS = 10 * 60 * 1000;
  *  may write its own files inside them (e.g. an extension's own config). */
 const MANAGED_DIRS_WITH_RUNTIME_CONTENT = new Set(["extensions"]);
 
+/** Content-scan budget for deciding whether an unrecognized entry is safe to
+ *  adopt (ADR-0012). Over budget → undecidable → keep and warn. The values
+ *  are implementation constants: the contract only fixes "over budget means
+ *  keep". Exported for the tests that pin the over-budget behavior. */
+export const SCAN_MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+export const SCAN_MAX_FILES = 1024;
+
+/** What the sweep does with one unrecognized entry in a candidate dir. */
+type Disposition = "adopt" | "delete" | "keep-warn";
+
+interface EntryDecision {
+	/** Entry name relative to the instance dir. */
+	name: string;
+	disposition: Disposition;
+}
+
+export interface SweepResult {
+	/** Warnings for directories intentionally kept. */
+	warnings: string[];
+	/** One-line notices for entries adopted into or deleted from a candidate. */
+	notices: string[];
+}
+
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -59,10 +84,98 @@ function isProcessAlive(pid: number): boolean {
 	}
 }
 
-/** Paths inside `dir` that pi-profile did not generate, relative to `dir`.
- *  `undefined` means the directory could not be inspected — the caller must
- *  treat that as unrecognized rather than as empty. */
-async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
+/** Scan budget shared across one entry's recursive content scan. */
+interface ScanBudget {
+	bytes: number;
+	files: number;
+	/** Set when a limit is hit or a member cannot be read: undecidable. */
+	exceeded: boolean;
+	/** Set when a member's bytes contain the instance dir's absolute path. */
+	found: boolean;
+}
+
+async function scanContent(entryPath: string, instanceDir: string, budget: ScanBudget): Promise<void> {
+	if (budget.exceeded || budget.found) return;
+	let info;
+	try {
+		info = await lstat(entryPath);
+	} catch {
+		budget.exceeded = true; // Vanished or unreadable mid-scan: undecidable.
+		return;
+	}
+	if (info.isDirectory()) {
+		let members: string[];
+		try {
+			members = await readdir(entryPath);
+		} catch {
+			budget.exceeded = true;
+			return;
+		}
+		for (const member of members) {
+			await scanContent(path.join(entryPath, member), instanceDir, budget);
+			if (budget.exceeded || budget.found) return;
+		}
+		return;
+	}
+	if (!info.isFile()) {
+		// A socket/fifo/device member cannot be read: undecidable.
+		budget.exceeded = true;
+		return;
+	}
+	budget.files += 1;
+	budget.bytes += info.size;
+	if (budget.files > SCAN_MAX_FILES || budget.bytes > SCAN_MAX_TOTAL_BYTES) {
+		budget.exceeded = true;
+		return;
+	}
+	let content: Buffer;
+	try {
+		content = await readFile(entryPath);
+	} catch {
+		budget.exceeded = true;
+		return;
+	}
+	if (content.includes(instanceDir)) budget.found = true;
+}
+
+/** Whether an unrecognized entry must be kept because its content scan says
+ *  so: the content references the instance dir's own path (records like
+ *  pi-subagents ledgers would break if moved), the scan could not finish
+ *  within the budget, or the entry is not a regular file/dir. Only a clean
+ *  negative scan makes the entry eligible for adoption (ADR-0012). */
+export async function mustKeepByContentScan(entryPath: string, instanceDir: string): Promise<boolean> {
+	let info;
+	try {
+		info = await lstat(entryPath);
+	} catch {
+		return true; // Vanished or unreadable: nothing to adopt.
+	}
+	if (!info.isFile() && !info.isDirectory()) return true; // socket/fifo etc.
+	const budget: ScanBudget = { bytes: 0, files: 0, exceeded: false, found: false };
+	await scanContent(entryPath, instanceDir, budget);
+	// Keep unless the scan finished within budget and never saw the path.
+	return budget.exceeded || budget.found;
+}
+
+/** Decides one top-level unrecognized entry: keep when the content scan is
+ *  not a clean negative; otherwise real-wins on a name conflict, adopt when
+ *  the real agent dir is free. A name lookup that fails for reasons other
+ *  than absence is undecidable → keep. */
+async function decideEntry(name: string, entryPath: string, instanceDir: string, agentDir: string): Promise<EntryDecision> {
+	if (await mustKeepByContentScan(entryPath, instanceDir)) return { name, disposition: "keep-warn" };
+	try {
+		await lstat(path.join(agentDir, name));
+		return { name, disposition: "delete" };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { name, disposition: "adopt" };
+		return { name, disposition: "keep-warn" };
+	}
+}
+
+/** Unrecognized entry names inside a managed runtime-content directory
+ *  (`extensions/`): reported at pi-profile's boundary, never adopted or
+ *  deleted. `undefined` means the directory could not be inspected. */
+async function unrecognizedNames(dir: string): Promise<string[] | undefined> {
 	let entries: Dirent<string>[];
 	try {
 		entries = await readdir(dir, { withFileTypes: true });
@@ -71,6 +184,41 @@ async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
 	}
 
 	const found: string[] = [];
+	for (const entry of entries) {
+		const entryPath = path.join(dir, entry.name);
+		let linkStat;
+		try {
+			linkStat = await lstat(entryPath);
+		} catch {
+			continue; // Vanished under us: nothing to protect.
+		}
+		if (linkStat.isSymbolicLink()) continue;
+		if (MANAGED_DIRS_WITH_RUNTIME_CONTENT.has(entry.name) && linkStat.isDirectory()) {
+			const nested = await unrecognizedNames(entryPath);
+			if (nested === undefined) {
+				found.push(entry.name);
+				continue;
+			}
+			found.push(...nested.map((name) => path.join(entry.name, name)));
+			continue;
+		}
+		found.push(entry.name);
+	}
+	return found;
+}
+
+/** Decides every unrecognized entry in `dir`. `undefined` means the directory
+ *  could not be inspected — the caller must treat that as unrecognized rather
+ *  than as empty. */
+async function classifyUnrecognized(dir: string, agentDir: string): Promise<EntryDecision[] | undefined> {
+	let entries: Dirent<string>[];
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return undefined;
+	}
+
+	const decisions: EntryDecision[] = [];
 	for (const entry of entries) {
 		const entryPath = path.join(dir, entry.name);
 		let linkStat;
@@ -82,24 +230,26 @@ async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
 		// Symlinks only point at the real agent dir and hold no data of their own.
 		if (linkStat.isSymbolicLink()) continue;
 		if (!MANAGED_INSTANCE_FILES.has(entry.name)) {
-			found.push(entry.name);
+			decisions.push(await decideEntry(entry.name, entryPath, dir, agentDir));
 			continue;
 		}
 		if (MANAGED_DIRS_WITH_RUNTIME_CONTENT.has(entry.name) && linkStat.isDirectory()) {
-			const nested = await unrecognizedEntries(entryPath);
+			const nested = await unrecognizedNames(entryPath);
 			if (nested === undefined) {
-				found.push(entry.name);
+				decisions.push({ name: entry.name, disposition: "keep-warn" });
 				continue;
 			}
-			found.push(...nested.map((name) => path.join(entry.name, name)));
+			for (const name of nested) decisions.push({ name: path.join(entry.name, name), disposition: "keep-warn" });
 		}
 	}
-	return found;
+	return decisions;
 }
 
-/** Reclaims `dir` if it is both dead and free of unrecognized entries.
- *  Returns the warnings for the cases where it was intentionally kept. */
-async function sweepEntry(dir: string): Promise<string[]> {
+/** Reclaims `dir` if it is both dead and free of unrecognized entries, after
+ *  dispositioning those entries (ADR-0012). Appends notices for adopted and
+ *  deleted entries to `notices`; returns the warnings for the cases where the
+ *  directory was intentionally kept. */
+async function sweepEntry(dir: string, agentDir: string, notices: string[]): Promise<string[]> {
 	let pid: number | undefined;
 	try {
 		const raw = await readFile(path.join(dir, "pid"), "utf8");
@@ -116,15 +266,43 @@ async function sweepEntry(dir: string): Promise<string[]> {
 		if (Date.now() - info.mtimeMs <= NO_PID_GRACE_MS) return [];
 	}
 
-	const unrecognized = await unrecognizedEntries(dir);
-	if (unrecognized === undefined) {
+	const decisions = await classifyUnrecognized(dir, agentDir);
+	if (decisions === undefined) {
 		return [
 			`${dir} was not reclaimed: it could not be inspected (permissions?). Check its contents and delete it manually.`,
 		];
 	}
-	if (unrecognized.length > 0) {
+
+	const kept: string[] = [];
+	for (const decision of decisions) {
+		if (decision.disposition === "keep-warn") {
+			kept.push(decision.name);
+			continue;
+		}
+		const entryPath = path.join(dir, decision.name);
+		if (decision.disposition === "adopt") {
+			try {
+				await rename(entryPath, path.join(agentDir, decision.name));
+				notices.push(`adopted ${decision.name} from ${dir} into the real agent dir (${agentDir}); it is mirrored on the next launch`);
+				continue;
+			} catch {
+				kept.push(decision.name); // Best-effort: keep rather than destroy.
+				continue;
+			}
+		}
+		// delete: the real agent dir already holds this name (real wins, no
+		// content comparison — ADR-0012).
+		try {
+			await rm(entryPath, { recursive: true, force: true });
+			notices.push(`deleted ${decision.name} from ${dir}: the real agent dir already holds that name`);
+		} catch {
+			kept.push(decision.name);
+		}
+	}
+
+	if (kept.length > 0) {
 		return [
-			`${dir} was not reclaimed: it holds state pi-profile did not generate (${unrecognized.join(", ")}). ` +
+			`${dir} was not reclaimed: it holds state pi-profile did not generate (${kept.join(", ")}). ` +
 				`Move that state into the real agent dir (it is mirrored on the next launch), or point the extension that ` +
 				`created it at a fixed path via that extension's own configuration, then delete ${dir}.`,
 		];
@@ -135,16 +313,19 @@ async function sweepEntry(dir: string): Promise<string[]> {
 }
 
 /** Deletes stale instance dirs under the instances root and returns the
- *  warnings for directories it deliberately kept. Never throws. */
-export async function sweepStaleInstances(): Promise<string[]> {
+ *  warnings for directories it deliberately kept plus the notices for entries
+ *  it adopted or deleted. `agentDir` is the real agent dir that adopted
+ *  entries move into and name conflicts resolve against. Never throws. */
+export async function sweepStaleInstances(agentDir: string): Promise<SweepResult> {
 	const warnings: string[] = [];
+	const notices: string[] = [];
 	const root = getInstancesRootDir();
 
 	let entries: string[];
 	try {
 		entries = await readdir(root);
 	} catch {
-		return warnings; // No instances root yet: nothing to sweep.
+		entries = []; // No instances root yet: nothing to sweep.
 	}
 
 	for (const entry of entries) {
@@ -155,11 +336,11 @@ export async function sweepStaleInstances(): Promise<string[]> {
 		const dir = path.join(root, entry);
 		try {
 			if (!(await stat(dir)).isDirectory()) continue;
-			warnings.push(...(await sweepEntry(dir)));
+			warnings.push(...(await sweepEntry(dir, agentDir, notices)));
 		} catch {
 			// Best-effort: one bad entry must not stop the sweep or the launch.
 		}
 	}
 
-	return warnings;
+	return { warnings, notices };
 }

package/src/profile-catalog-store.ts

@@ -1,109 +1,86 @@
 /**
- * ProfileCatalogStore: the WRITE side of a profile catalog file
- * (ticket 09), kept separate from the read-only ProfileCatalog.
+ * ProfileCatalogStore: the WRITE side of profile catalog files,
+ * storing each profile in its own `<name>.json` file.
  *
  * Invariants:
- * - 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.
+ * - Single-file operations (pretty-printed JSON without schemaVersion envelope).
+ * - Writes land in `<dir>/<name>.json` via a temporary file + rename.
+ * - Names must match `PROFILE_NAME_PATTERN` and cannot be "default".
+ * - Definitions are complete and self-contained: no inheritance fields exist.
  * - Definitions are re-parsed through the catalog's own
- *   `parseProfileDefinition`, so anything written is loadable;
- *   "default" is built in and can never be written.
- * - Writes land in exactly one scope file (global or project).
+ *   `parseProfileDefinition`, so anything written is loadable.
+ * - Writes land in exactly one scope directory (global or project).
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { isRecord, readJsonFile } from "./json-file.ts";
 import {
 	CatalogError,
 	DEFAULT_PROFILE_NAME,
+	loadCatalogDirectory,
 	parseProfileDefinition,
-	PROFILE_SCHEMA_VERSION,
+	PROFILE_NAME_PATTERN,
 	type ProfileDefinition,
 } from "./profile-catalog.ts";
 
 export class ProfileCatalogStore {
-	readonly #filePath: string;
-	readonly #fallbackPath?: string;
+	readonly #dirPath: string;
 
-	constructor(catalogPath: string, fallbackPath?: string) {
-		this.#filePath = catalogPath;
-		this.#fallbackPath = fallbackPath;
+	constructor(catalogDir: string) {
+		this.#dirPath = catalogDir;
 	}
 
-	/** Validated definitions: missing file → empty; malformed → CatalogError
+	/** Validated definitions: missing directory → empty; malformed → CatalogError
 	 *  (catalog errors never pass silently, even on the write path). */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
-		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}`);
-		}
-		if (!isRecord(result.value)) {
-			throw new CatalogError(`${this.#filePath}: catalog must be an object`);
-		}
-		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). */
-	async writeDefinitions(definitions: ReadonlyMap<string, ProfileDefinition>): Promise<void> {
-		const profiles: Record<string, unknown> = {};
-		for (const [name, definition] of [...definitions.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-			// Round-trip through the parser: only declared, validated fields
-			// are written back (self-contained; no unknown keys survive).
-			profiles[name] = parseProfileDefinition(name, definition);
-		}
-		await mkdir(path.dirname(this.#filePath), { recursive: true });
-		await writeFile(
-			this.#filePath,
-			`${JSON.stringify({ schemaVersion: PROFILE_SCHEMA_VERSION, profiles }, null, 2)}\n`,
-		);
+		return loadCatalogDirectory(this.#dirPath);
 	}
 
-	/** Inserts or replaces one complete definition. */
+	/** Inserts or replaces one complete definition (via atomic rename). */
 	async upsert(name: string, definition: ProfileDefinition): Promise<void> {
-		if (name.trim().length === 0) {
-			throw new CatalogError(`profile name must be non-empty`);
+		if (!PROFILE_NAME_PATTERN.test(name)) {
+			throw new CatalogError(`invalid profile name "${name}" (must match ${PROFILE_NAME_PATTERN})`);
 		}
 		if (name === DEFAULT_PROFILE_NAME) {
 			throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`);
 		}
-		const definitions = await this.readDefinitions();
-		// Validate before mutating: the wizard's definition must parse.
-		definitions.set(name, parseProfileDefinition(name, definition));
-		await this.writeDefinitions(definitions);
+
+		// Validate before mutating: the definition must parse.
+		const validated = parseProfileDefinition(name, definition);
+
+		await mkdir(this.#dirPath, { recursive: true });
+		const targetPath = path.join(this.#dirPath, `${name}.json`);
+		const tempPath = path.join(
+			this.#dirPath,
+			`.${name}.json.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+		);
+
+		try {
+			await writeFile(tempPath, `${JSON.stringify(validated, null, 2)}\n`);
+			await rename(tempPath, targetPath);
+		} catch (error) {
+			await rm(tempPath, { force: true });
+			throw error;
+		}
 	}
 
 	/** Removes one profile; unknown names are a loud error, not a no-op. */
 	async remove(name: string): Promise<void> {
-		const definitions = await this.readDefinitions();
-		if (!definitions.delete(name)) {
-			throw new CatalogError(`profile "${name}" not found in ${this.#filePath}`);
+		if (!PROFILE_NAME_PATTERN.test(name)) {
+			throw new CatalogError(`invalid profile name "${name}" (must match ${PROFILE_NAME_PATTERN})`);
+		}
+		if (name === DEFAULT_PROFILE_NAME) {
+			throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and cannot be deleted`);
+		}
+		const targetPath = path.join(this.#dirPath, `${name}.json`);
+		try {
+			await unlink(targetPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				throw new CatalogError(`profile "${name}" not found in ${this.#dirPath}`);
+			}
+			throw error;
 		}
-		await this.writeDefinitions(definitions);
 	}
 }