pi-profile-switch 0.3.0 → 0.4.0

package/src/switching/switch-profile.ts

@@ -0,0 +1,219 @@
+/**
+ * SwitchProfile: the in-session switching orchestrator (ticket 05).
+ *
+ * Runs inside Pi (the extension's `/profile use` / `/profile reload`), but
+ * is written dependency-injected so unit tests never need a real Pi.
+ *
+ * Flow (`/profile use <name>`):
+ *   1. wait for the agent to be idle (Pi's native `ctx.waitForIdle()`) — a
+ *      running turn is never torn down
+ *   2. snapshot the runtime dir's settings.json + pi-profile.json in memory
+ *   3. re-resolve through the full launcher path (trust check, catalogs,
+ *      discovery, registry, model/MCP validation) against the REAL agent
+ *      dir — any failure here leaves the runtime untouched
+ *   4. rewrite the runtime files in place (the running process's
+ *      PI_CODING_AGENT_DIR cannot move) and mark the plan
+ *      `persistSelection` so the post-reload extension instance saves the
+ *      selection + rollback anchor
+ *   5. `ctx.reload()` — Pi re-reads settings from disk, re-executes
+ *      extensions, preserves the session
+ *   6. VERIFY the reload ran: interactive Pi swallows reload refusals and
+ *      errors (showError) instead of rejecting, so a resolved promise is
+ *      not proof. A real reload invalidates this extension context — the
+ *      `assertStale` probe throws iff that happened. A silent skip rolls
+ *      back exactly like a rejection: restore the snapshot, reload again.
+ *      The runtime never sits half-switched.
+ *
+ * `/profile reload` is the same path minus the `switchedFrom` marker (no
+ * change summary) and preserving however the current profile became active
+ * (transient launch selections stay transient).
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { resolveInitialProfile } from "../launcher/initial-profile.ts";
+import { RuntimeStateStore, type RuntimeOverlay } from "../runtime-state-store.ts";
+import { getGlobalStateDir } from "../workspace.ts";
+import { writeRuntimeFiles } from "../settings-generator.ts";
+import { readLaunchPlanFile } from "./apply-plan.ts";
+
+export class SwitchError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SwitchError";
+	}
+}
+
+export interface SwitchDeps {
+	/** The active generated runtime dir (the running Pi's agent dir). */
+	runtimeDir: string;
+	/** The user's real agent dir (from the launch plan; trust, catalogs,
+	 *  registries, and state all live there). */
+	realAgentDir: string;
+	/** The project working directory. */
+	cwd: string;
+	/** Pi's native idle wait (ctx.waitForIdle): resolves when the current
+	 *  turn/compaction finishes. */
+	waitForIdle(): Promise<void>;
+	reload(): Promise<void>;
+	/** Throws iff this extension context has been invalidated — proof the
+	 *  reload actually re-executed extensions. Interactive Pi swallows reload
+	 *  refusals/failures instead of rejecting, so without this probe a
+	 *  skipped reload would be misreported as a successful switch. Optional
+	 *  for tests; always provided by the extension. */
+	assertStale?(): void;
+}
+
+export interface SwitchResult {
+	profile: string;
+	warnings: string[];
+}
+
+interface RuntimeSnapshot {
+	settings?: string;
+	plan?: string;
+}
+
+async function readIfExists(filePath: string): Promise<string | undefined> {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		// Absence is expected (first launch); anything else (permissions,
+		// unreadable dir) must not silently disable rollback protection.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function snapshotRuntimeFiles(runtimeDir: string): Promise<RuntimeSnapshot> {
+	return {
+		settings: await readIfExists(path.join(runtimeDir, "settings.json")),
+		plan: await readIfExists(path.join(runtimeDir, "pi-profile.json")),
+	};
+}
+
+async function restoreRuntimeFiles(runtimeDir: string, snapshot: RuntimeSnapshot): Promise<void> {
+	if (snapshot.settings !== undefined) {
+		await writeFile(path.join(runtimeDir, "settings.json"), snapshot.settings);
+	}
+	if (snapshot.plan !== undefined) {
+		await writeFile(path.join(runtimeDir, "pi-profile.json"), snapshot.plan);
+	}
+}
+
+/** Waits are delegated to Pi's native `ctx.waitForIdle()` (see SwitchDeps);
+ *  no polling loop lives here. */
+
+/** Reads the current plan file for `switchedFrom`/persistence. A missing or
+ *  malformed plan means the session is not profile-managed: switching still
+ *  works, with no prior name to report. */
+async function readCurrentPlan(runtimeDir: string): Promise<{ profile?: string; persistSelection: boolean }> {
+	const plan = await readLaunchPlanFile(runtimeDir);
+	return { profile: plan?.profile, persistSelection: plan?.persistSelection === true };
+}
+
+export async function switchProfile(
+	name: string | undefined,
+	deps: SwitchDeps,
+	options?: { reloadCurrent?: boolean; overlay?: RuntimeOverlay | null; clearOverlay?: boolean },
+): Promise<SwitchResult> {
+	const current = await readCurrentPlan(deps.runtimeDir);
+	const target = options?.reloadCurrent === true ? (current.profile ?? name) : name;
+	if (target === undefined) {
+		throw new SwitchError("no active profile to reload");
+	}
+
+	// Overlay resolution: explicit `overlay` wins (customize), explicit
+	// `null` suppresses (reset/switch), and a plain `/profile reload`
+	// re-applies the stored overlay so runtime and state never diverge.
+	let overlay = options?.overlay;
+	if (overlay === undefined && options?.reloadCurrent === true && current.profile !== undefined) {
+		const currentPlan = await readLaunchPlanFile(deps.runtimeDir);
+		if (currentPlan?.agentDir !== undefined) {
+			const stateDir = currentPlan.source === "project" ? path.join(deps.cwd, ".pi") : getGlobalStateDir(currentPlan.agentDir);
+			overlay = (await new RuntimeStateStore(stateDir).read()).overlay ?? null;
+		}
+	}
+
+	await deps.waitForIdle();
+
+	// Snapshot before resolving so the rollback target always exists.
+	const snapshot = await snapshotRuntimeFiles(deps.runtimeDir);
+
+	// Full launcher resolution: trust gate, catalogs, discovery, dependency
+	// closure, model + MCP validation. Failures here leave the runtime
+	// untouched — nothing was written yet.
+	const resolved = await resolveInitialProfile(
+		target,
+		{ agentDir: deps.realAgentDir, cwd: deps.cwd },
+		{ overlay: overlay ?? undefined },
+	);
+
+	const isSwitch = !options?.reloadCurrent && target !== current.profile;
+	// Carry the pre-switch resolved sets into the new plan for status deltas.
+	const previousPlan = await readLaunchPlanFile(deps.runtimeDir);
+	const previousResolved =
+		previousPlan?.resolved !== undefined
+			? {
+					skills: previousPlan.resolved.skills.map((skill) => skill.name),
+					extensions: previousPlan.resolved.extensions.map((entry) => entry.id),
+					...(previousPlan.tools !== undefined ? { tools: previousPlan.tools } : {}),
+					...(previousPlan.mcps !== undefined ? { mcps: previousPlan.mcps } : {}),
+				}
+			: undefined;
+	await writeRuntimeFiles(deps.runtimeDir, resolved.plan, {
+		agentDir: deps.realAgentDir,
+		discovery: resolved.discovery,
+		projectSettings: resolved.projectSettings,
+		planExtras: {
+			...(isSwitch && current.profile !== undefined ? { switchedFrom: current.profile } : {}),
+			// `/profile use` persists; `/profile reload` keeps the current
+			// profile's existing persistence (launch selections stay transient).
+			persistSelection: options?.reloadCurrent === true ? current.persistSelection : true,
+			// A switch discards the previous profile's overlay; the post-reload
+			// instance drops it from the state file. Customize/reset manage the
+			// overlay directly and never set this.
+			...(options?.clearOverlay === true ? { clearOverlay: true } : {}),
+			...(previousResolved !== undefined ? { previousResolved } : {}),
+		},
+	});
+
+	const rollback = async (cause: string): Promise<never> => {
+		// Restore the verified snapshot and reload again — the runtime must
+		// never sit half-switched. State files were not written yet (the
+		// post-reload extension instance owns them), so nothing else moved.
+		await restoreRuntimeFiles(deps.runtimeDir, snapshot);
+		try {
+			await deps.reload();
+		} catch {
+			// The restore reload failing too is reported through the original error.
+		}
+		throw new SwitchError(
+			`activation of profile "${target}" failed; restored the previous settings. Cause: ${cause}`,
+		);
+	};
+
+	try {
+		await deps.reload();
+	} catch (error) {
+		await rollback(error instanceof Error ? error.message : String(error));
+	}
+
+	// Interactive Pi reports reload refusals/failures via the UI instead of
+	// rejecting — verify the reload actually re-executed extensions (which
+	// invalidates this context) before calling the switch a success.
+	if (deps.assertStale !== undefined) {
+		let stale = false;
+		try {
+			deps.assertStale();
+		} catch {
+			stale = true;
+		}
+		if (!stale) {
+			await rollback("Pi did not run the reload (refused or failed silently)");
+		}
+	}
+
+	return { profile: resolved.plan.profile, warnings: resolved.warnings };
+}

package/src/switching/tool-references.ts

@@ -0,0 +1,40 @@
+/**
+ * Tool reference expansion against Pi's LIVE tool registry.
+ *
+ * Pre-spawn, the resolver expands tool globs against built-in names only
+ * (extension tools are unknowable before extension code runs). Post session
+ * start, the extension re-expands the raw references against
+ * `pi.getAllTools()`, which includes extension- and MCP-provided names.
+ * Literal references that match nothing are reported, not silently dropped
+ * (Pi's setActiveTools ignores unknown names).
+ */
+
+import { minimatch } from "minimatch";
+
+export interface ToolExpansion {
+	expanded: string[];
+	/** Literal references no live tool provides. */
+	droppedLiterals: string[];
+}
+
+export function expandToolReferences(references: string[], liveToolNames: string[]): ToolExpansion {
+	const live = new Set(liveToolNames);
+	const expanded = new Set<string>();
+	const droppedLiterals: string[] = [];
+	for (const reference of references) {
+		if (reference.includes("*") || reference.includes("?")) {
+			for (const name of liveToolNames) {
+				if (minimatch(name, reference)) {
+					expanded.add(name);
+				}
+			}
+			continue;
+		}
+		if (live.has(reference)) {
+			expanded.add(reference);
+		} else {
+			droppedLiterals.push(reference);
+		}
+	}
+	return { expanded: [...expanded], droppedLiterals };
+}

package/src/workspace.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace management for pi-profile-switch.
+ *
+ * Rooted at `~/.pi-profile-switch` (or `PI_PROFILE_SWITCH_DIR` override).
+ * Contains:
+ * - `profiles.json`: global profile definitions catalog
+ * - `instances/`: instance runtime directories for forked pi processes
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export function getProfileSwitchDir(): string {
+	const env = process.env.PI_PROFILE_SWITCH_DIR;
+	if (env && env.trim()) {
+		return path.resolve(env.trim());
+	}
+	return path.join(homedir(), ".pi-profile-switch");
+}
+
+export function getGlobalProfilesPath(): string {
+	return path.join(getProfileSwitchDir(), "profiles.json");
+}
+
+export function resolveGlobalProfilesPath(agentDir: string): string {
+	const preferred = getGlobalProfilesPath();
+	if (existsSync(preferred)) {
+		return preferred;
+	}
+	// Fallback for legacy ~/.pi/agent/profiles.json
+	const fallback = path.join(agentDir, "profiles.json");
+	if (existsSync(fallback)) {
+		return fallback;
+	}
+	return preferred;
+}
+
+export function getInstancesRootDir(): string {
+	return path.join(getProfileSwitchDir(), "instances");
+}
+
+export function getGlobalStateDir(agentDir?: string): string {
+	const preferred = getProfileSwitchDir();
+	const preferredState = path.join(preferred, "pi-profile-state.json");
+	if (existsSync(preferredState)) {
+		return preferred;
+	}
+	if (agentDir) {
+		const fallbackState = path.join(agentDir, "pi-profile-state.json");
+		if (existsSync(fallbackState)) {
+			return agentDir;
+		}
+	}
+	return agentDir ?? preferred;
+}
+

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 VincentFF
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/examples/profiles.example.json

@@ -1,74 +0,0 @@
-{
-  "schemaVersion": 1,
-  "profiles": {
-    "read-only": {
-      "label": "Read-only",
-      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls"
-      ],
-      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
-    },
-    "review": {
-      "label": "Code review",
-      "description": "Review a diff or a branch: read the change, report findings, modify nothing.",
-      "skills": [
-        "code-review",
-        "git-*"
-      ],
-      "mcp": [
-        "github"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash"
-      ],
-      "model": {
-        "provider": "anthropic",
-        "id": "claude-sonnet-4-5",
-        "thinkingLevel": "high"
-      },
-      "instructions": "Review only: read the change under review, then report findings with file:line evidence.\nNever edit tracked files, commit, or push; describe the required fix instead.\nSeparate verified behavior from suspected issues."
-    },
-    "plan": {
-      "label": "Plan",
-      "description": "Research a change and write the plan; no edits, no implementation.",
-      "skills": [],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash"
-      ],
-      "instructions": "Planning session: research the code first, then write the plan in your reply.\nDo not create, edit, rename, or delete files."
-    },
-    "implement": {
-      "label": "Implement",
-      "description": "Full tool access for implementing a change end to end.",
-      "skills": [
-        "git-commit",
-        "test-*"
-      ],
-      "mcp": [
-        "github"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write"
-      ],
-      "instructions": "Implement the requested change: read before writing, keep the diff minimal.\nRun the tests that cover your change and report the exact commands."
-    }
-  }
-}