pi-profile-switch 0.2.0 → 0.3.1

package/src/startup-mcp-scope.ts

@@ -0,0 +1,271 @@
+/**
+ * StartupMcpScope: derives the profile-scoped MCP overlay at times when a
+ * full activation has not (or may not yet) run.
+ *
+ * Two callers:
+ * - The extension-load pass: must be synchronous and must finish before
+ *   pi-mcp-adapter reads its config at `session_start` (and, for eager
+ *   servers, at its own load time). Pi applies CLI flag values only AFTER
+ *   extension loading, so the `--profile` / `--mcp-config` values are read
+ *   from argv here; trust is mirrored from Pi's own resolution order
+ *   (`hasTrustRequiringProjectResources` → stored decision →
+ *   `defaultProjectTrust`; an interactive first-time prompt is not yet
+ *   answerable at load time and counts as untrusted).
+ * - The switch pass: the caller already has the resolved allowlist, so the
+ *   overlay is derived from it directly.
+ *
+ * The generated file IS the adapter's Pi-global slot (`<agentDir>/mcp.json`):
+ * flag injection is impossible (Pi rejects two extensions registering the
+ * same flag), so the mechanism works with the slot the adapter already reads.
+ * The user's own Pi-global servers live in the sidecar `mcp.user.json`.
+ *
+ * Failure policy: a profile name that cannot be resolved (missing, malformed
+ * catalog, unknown name) falls back to "no filtering" — the generated overlay
+ * then changes nothing, and the real problem is reported loudly by the
+ * activation that runs right after. A foreign `--mcp-config` disables
+ * management entirely: the user's explicit file is never overwritten.
+ */
+
+import { hasTrustRequiringProjectResources, ProjectTrustStore } from "@earendil-works/pi-coding-agent";
+import path from "node:path";
+
+import { isRecord, readJsonFileSync } from "./json-file.ts";
+import { readAdapterOtherServerNamesSync, readMcpDocumentSync } from "./mcp-config.ts";
+import {
+	buildMcpOverlay,
+	isDisabledStub,
+	isGeneratedOverlay,
+	MCP_GENERATED_MARKER,
+	mcpSlotPath,
+	mcpSourcePath,
+	resolveAllowedServers,
+	serializeMcpOverlay,
+} from "./mcp-overlay.ts";
+import { writeMcpOverlayIfChangedSync } from "./mcp-overlay-file.ts";
+import { DEFAULT_PROFILE_NAME, parseCatalogDocument, type ProfileDefinition } from "./profile-catalog.ts";
+
+/** Reads `--<name> <value>` / `--<name>=<value>` without Pi's parser (Pi
+ *  applies extension flag values only after extension loading). Last wins. */
+export function readFlagFromArgv(argv: readonly string[], name: string): string | undefined {
+	const long = `--${name}`;
+	let value: string | undefined;
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index] ?? "";
+		if (token === long) {
+			const next = argv[index + 1];
+			if (next !== undefined && !next.startsWith("--")) value = next;
+			continue;
+		}
+		if (token.startsWith(`${long}=`)) {
+			const inline = token.slice(long.length + 1);
+			if (inline.length > 0) value = inline;
+		}
+	}
+	return value;
+}
+
+/** True when Pi itself would consider `cwd` trusted right now. Mirrors
+ *  `resolveProjectTrusted` minus extension votes and the interactive prompt. */
+export function resolveProjectTrustedSync(agentDir: string, cwd: string): boolean {
+	if (!hasTrustRequiringProjectResources(cwd)) return true;
+	const stored = new ProjectTrustStore(agentDir).get(cwd);
+	if (stored !== null) return stored;
+	return readDefaultProjectTrustSync(agentDir) === "always";
+}
+
+/** The profile this pass generates the overlay for: this process's already
+ *  applied selection (`continuation`) first — a reload must not regress to
+ *  the `--profile` flag — then the flag, then the saved selection: project
+ *  state wins over global state (project state only when trusted), then the
+ *  built-in default. */
+export function resolveStartupProfileNameSync(input: {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+	argv: readonly string[];
+	continuation?: string;
+}): string {
+	if (input.continuation !== undefined && input.continuation.length > 0) return input.continuation;
+	const requested = readFlagFromArgv(input.argv, "profile");
+	if (requested !== undefined && requested.length > 0) return requested;
+	const project = input.projectTrusted
+		? readActiveProfile(path.join(input.cwd, ".pi", "pi-profile-state.json"))
+		: undefined;
+	return project ?? readActiveProfile(path.join(input.agentDir, "pi-profile-state.json")) ?? DEFAULT_PROFILE_NAME;
+}
+
+export interface McpOverlaySyncInput {
+	agentDir: string;
+	cwd: string;
+	/** Pi's trust decision. Omitted on the extension-load pass, where Pi has
+	 *  not resolved trust yet; the module mirrors Pi's own order then. */
+	projectTrusted?: boolean;
+	/** Effective `--mcp-config`; undefined means the managed overlay path. */
+	overridePath?: string;
+	/** The selection this process already applied: a reload's overlay belongs
+	 *  to it, not to the `--profile` flag. */
+	continuation?: string;
+	/** The command line, for the load pass (Pi applies flag values only after
+	 *  extension loading, so `--profile` is read from here). */
+	argv?: readonly string[];
+	homeDir?: string;
+}
+
+export interface McpOverlaySyncResult {
+	overlayPath: string;
+	/** False when a foreign `--mcp-config` owns the adapter's slot. */
+	managed: boolean;
+	changed: boolean;
+	/** Set when nothing was written; the caller surfaces it as a warning. */
+	error?: string;
+}
+
+/** Load-time (and `session_start` re-check) pass. `profileName` short-circuits
+ *  the state lookup when the caller already activated a profile. */
+export function syncStartupMcpOverlay(
+	input: McpOverlaySyncInput & { profileName?: string; mcpRefs?: readonly string[] | undefined },
+): McpOverlaySyncResult {
+	try {
+		const trust = input.projectTrusted;
+		const profileName =
+			input.profileName ??
+			resolveStartupProfileNameSync({
+				agentDir: input.agentDir,
+				cwd: input.cwd,
+				projectTrusted: trust ?? resolveProjectTrustedSync(input.agentDir, input.cwd),
+				argv: input.argv ?? [],
+				...(input.continuation === undefined ? {} : { continuation: input.continuation }),
+			});
+		const refs = input.mcpRefs ?? readProfileMcpRefsSync({ ...input, name: profileName, trust });
+		return writeOverlayForRefs({ ...input, refs });
+	} catch (error) {
+		return {
+			overlayPath: mcpSlotPath(input.agentDir),
+			managed: true,
+			changed: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+/** Switch pass: the caller already resolved the allowlist. */
+export function syncMcpOverlayForSelection(
+	input: McpOverlaySyncInput & { allowed: readonly string[] | "all" },
+): McpOverlaySyncResult {
+	try {
+		return writeOverlay({ ...input, refs: input.allowed });
+	} catch (error) {
+		return {
+			overlayPath: mcpSlotPath(input.agentDir),
+			managed: true,
+			changed: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+function writeOverlayForRefs(input: McpOverlaySyncInput & { refs: readonly string[] | undefined | "unknown" }): McpOverlaySyncResult {
+	// An unresolvable profile is not an error here: the generated overlay
+	// then filters nothing and the activation reports the real problem.
+	const refs = input.refs === "unknown" ? undefined : input.refs;
+	return writeOverlay({ ...input, refs });
+}
+
+function writeOverlay(input: McpOverlaySyncInput & { refs: readonly string[] | undefined | "all" }): McpOverlaySyncResult {
+	const overlayPath = mcpSlotPath(input.agentDir);
+	if (input.overridePath !== undefined && path.resolve(input.overridePath) !== overlayPath) {
+		return { overlayPath, managed: false, changed: false };
+	}
+	const projectTrusted = input.projectTrusted ?? resolveProjectTrustedSync(input.agentDir, input.cwd);
+	const discovery = {
+		agentDir: input.agentDir,
+		cwd: input.cwd,
+		projectTrusted,
+		...(input.homeDir === undefined ? {} : { homeDir: input.homeDir }),
+	};
+	// The slot is ours; a slot written by hand is adopted into the sidecar
+	// before the first overwrite, so a user's Pi-global servers survive.
+	const sourcePath = mcpSourcePath(input.agentDir);
+	adoptHandWrittenSlotSync(overlayPath, sourcePath);
+	const sourceDocument = readMcpDocumentSync(sourcePath);
+	const sourceNames = isRecord(sourceDocument?.mcpServers) ? Object.keys(sourceDocument.mcpServers) : [];
+	const otherNames = readAdapterOtherServerNamesSync(discovery);
+	const allowed =
+		input.refs === "all"
+			? "all"
+			: resolveAllowedServers(input.refs, [...new Set([...sourceNames, ...otherNames])].sort());
+	const content = serializeMcpOverlay(
+		buildMcpOverlay({
+			...(sourceDocument === undefined ? {} : { slotDocument: sourceDocument }),
+			otherServerNames: otherNames,
+			allowed,
+		}),
+	);
+	return { overlayPath, managed: true, changed: writeMcpOverlayIfChangedSync(overlayPath, content) };
+}
+
+/** A slot file without the generated marker holds the user's own Pi-global
+ *  servers (from before this package managed the slot, or from a manual
+ *  edit). Move them — plus the slot's non-server keys — into the sidecar
+ *  before the slot is overwritten. Stub entries are skipped: they describe
+ *  servers owned by the adapter's other sources. */
+function adoptHandWrittenSlotSync(slotPath: string, sourcePath: string): void {
+	const slot = readMcpDocumentSync(slotPath);
+	if (slot === undefined || isGeneratedOverlay(slot)) return;
+	const sidecar = readMcpDocumentSync(sourcePath) ?? {};
+	const sidecarServers = isRecord(sidecar.mcpServers) ? sidecar.mcpServers : {};
+	const servers: Record<string, unknown> = { ...sidecarServers };
+	const slotServers = isRecord(slot.mcpServers) ? slot.mcpServers : {};
+	for (const [name, definition] of Object.entries(slotServers)) {
+		if (isDisabledStub(definition)) continue;
+		servers[name] = definition;
+	}
+	const document: Record<string, unknown> = { ...sidecar };
+	delete document[MCP_GENERATED_MARKER];
+	for (const [key, value] of Object.entries(slot)) {
+		if (key === "mcpServers" || key === MCP_GENERATED_MARKER) continue;
+		document[key] = value;
+	}
+	document.mcpServers = Object.fromEntries(Object.entries(servers).sort(([left], [right]) => left.localeCompare(right)));
+	writeMcpOverlayIfChangedSync(sourcePath, `${JSON.stringify(document, null, 2)}\n`);
+}
+
+function readActiveProfile(statePath: string): string | undefined {
+	const result = readJsonFileSync(statePath);
+	if (!result.ok || !isRecord(result.value)) return undefined;
+	const name = result.value.activeProfile;
+	return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+
+/** The profile's raw `mcps` references; `"unknown"` when the profile or its
+ *  catalog cannot be read (caller falls back to "no filtering"). */
+function readProfileMcpRefsSync(
+	input: McpOverlaySyncInput & { name: string; trust: boolean | undefined },
+): readonly string[] | undefined | "unknown" {
+	if (input.name === DEFAULT_PROFILE_NAME) return undefined;
+	const trusted = input.trust ?? resolveProjectTrustedSync(input.agentDir, input.cwd);
+	const global = readCatalogSync(path.join(input.agentDir, "profiles.json"));
+	const project = trusted
+		? readCatalogSync(path.join(input.cwd, ".pi", "profiles.json"))
+		: new Map<string, ProfileDefinition>();
+	if (global === "error" || project === "error") return "unknown";
+	const definition = project.get(input.name) ?? global.get(input.name);
+	return definition === undefined ? "unknown" : definition.mcps;
+}
+
+function readCatalogSync(filePath: string): Map<string, ProfileDefinition> | "error" {
+	const result = readJsonFileSync(filePath);
+	if (!result.ok) return result.reason === "missing" ? new Map<string, ProfileDefinition>() : "error";
+	try {
+		return parseCatalogDocument(result.value, filePath);
+	} catch {
+		return "error";
+	}
+}
+
+function readDefaultProjectTrustSync(agentDir: string): string | undefined {
+	const result = readJsonFileSync(path.join(agentDir, "settings.json"));
+	if (!result.ok || !isRecord(result.value)) return undefined;
+	const value = result.value.defaultProjectTrust;
+	return typeof value === "string" ? value : undefined;
+}

package/src/startup-selection.ts

@@ -5,6 +5,12 @@
  *   one-run selection: it is never written back to runtime state.
  * - Without the flag the saved selection applies: the trusted project's
  *   state wins over the global state, then the built-in `default`.
+ * - Every session start after the first continues THIS process's selection
+ *   (`continuation`): the flag is a startup directive, and re-reading it
+ *   after an in-session switch would resurrect the profile the user just
+ *   left. A continuation that no longer resolves falls back like a saved
+ *   selection, with a warning, because a deleted profile must not strand the
+ *   runtime.
  * - A saved selection that no longer resolves falls back to `default` with
  *   a warning — restore is a convenience, not a commitment. An explicit
  *   flag value never falls back: an unknown name is a loud error.
@@ -94,19 +100,70 @@ async function legacyRegistryWarnings(input: {
 	return warnings;
 }
 
-/** Resolves the profile name for this session: explicit flag → trusted
- *  project state → global state → default. Never writes state. */
+/**
+ * The profile this process last applied. Kept on `globalThis` because Pi
+ * re-imports extension modules on every reload (jiti) — module state resets
+ * exactly when it is needed. It is a run-scoped fact, not saved state: the
+ * `--profile` flag must not resurrect itself over an in-session switch when
+ * the MCP overlay change rebuilds the runtime.
+ */
+const RUN_SELECTION_KEY = "pi-profile-switch:applied-profile";
+
+interface RunSelection {
+	appliedProfile?: string;
+}
+
+function runSelection(): RunSelection {
+	const holder = globalThis as unknown as Record<string, RunSelection | undefined>;
+	const current = holder[RUN_SELECTION_KEY] ?? {};
+	holder[RUN_SELECTION_KEY] = current;
+	return current;
+}
+
+/** Records the profile this process applied (startup or in-session).
+ *  `undefined` clears the record; a fresh process starts empty. */
+export function recordAppliedProfile(name: string | undefined): void {
+	runSelection().appliedProfile = name;
+}
+
+/** The profile this process is running, or undefined before the first
+ *  activation. */
+export function appliedProfile(): string | undefined {
+	return runSelection().appliedProfile;
+}
+
+/** Resolves the profile name for this session: the run's current selection
+ *  (`continuation`) → explicit flag → trusted project state → global state →
+ *  default. Never writes state.
+ *
+ *  `requested` is the CLI flag: an unknown name is a loud error.
+ *  `continuation` is what this process already applied, passed on every
+ *  session start after the first: it keeps the in-session switch, and falls
+ *  back (with a warning) when the name no longer resolves. */
 export async function resolveStartupProfile(input: {
 	agentDir: string;
 	cwd: string;
 	projectTrusted: boolean;
 	requested?: string;
+	continuation?: string;
 }): Promise<StartupProfile> {
 	const catalog = await ProfileCatalog.load(input.agentDir, {
 		projectDir: input.projectTrusted ? input.cwd : undefined,
 	});
 	const warnings: string[] = await legacyRegistryWarnings(input);
 
+	// The continuation first: this process already applied it, so the flag
+	// (a startup directive) has had its say.
+	if (input.continuation !== undefined) {
+		if (catalog.resolve(input.continuation) !== undefined) {
+			return { name: input.continuation, warnings };
+		}
+		warnings.push(
+			`profile ${JSON.stringify(input.continuation)} no longer exists — restoring the saved selection; ` +
+				`available: [${catalog.list().map((profile) => profile.name).join(", ")}]`,
+		);
+	}
+
 	if (input.requested !== undefined) {
 		if (catalog.resolve(input.requested) === undefined) {
 			throw new UnknownProfileError(input.requested, catalog.list().map((profile) => profile.name));

package/src/switching/activate-profile.ts

@@ -82,6 +82,18 @@ export async function resolveProfileSelection(
 	return resolveSelection({ profile, overlay, live: deps.live, suppressTools });
 }
 
+/** Drops a stale saved selection from the scope that no longer owns it. A
+ *  project state file left behind by a previous project profile shadows the
+ *  new global choice on the next startup (project state wins), so the switch
+ *  path clears it; the scope's overlay stays, because that belongs to the
+ *  profile it was created for. */
+async function clearOtherSelection(stateDir: string): Promise<void> {
+	const store = new RuntimeStateStore(stateDir);
+	if ((await store.read()).activeProfile !== undefined) {
+		await store.update({ otherActiveProfile: undefined });
+	}
+}
+
 /** Activates a profile: resolve, validate, optionally persist, apply. */
 export async function activateProfile(
 	name: string,
@@ -100,10 +112,27 @@ export async function activateProfile(
 	}
 
 	if (options?.persist !== false) {
-		await new RuntimeStateStore(stateDirFor(selection.source, deps)).update({
-			activeProfile: selection.name,
-			overlay: overlay ?? undefined,
-		});
+		// Exactly one scope holds the saved selection: the project state file
+		// for a project profile, the global one otherwise (including the
+		// built-in `default`). A project profile is only reachable in a
+		// trusted project, so an untrusted project is skipped exactly like
+		// its catalog read — its state file stays untouched (ADR-0007).
+		const ownDir = stateDirFor(selection.source, deps);
+		const projectDir = stateDirFor("project", deps);
+		const writable = selection.source !== "project" || deps.projectTrusted;
+		if (writable) {
+			await new RuntimeStateStore(ownDir).update({
+				activeProfile: selection.name,
+				overlay: overlay ?? undefined,
+			});
+			// The scope that owned the previous selection must let go of it,
+			// or the next startup restores it: project state wins over global.
+			// An untrusted project is never read or written here either.
+			const otherDir = selection.source === "project" ? stateDirFor("global", deps) : projectDir;
+			if (otherDir !== ownDir && (otherDir !== projectDir || deps.projectTrusted)) {
+				await clearOtherSelection(otherDir);
+			}
+		}
 	}
 
 	const result = await applySelection({ selection, surface: deps.surface, preset });

package/src/switching/mcp-toggle.ts

@@ -1,7 +1,7 @@
 /**
  * McpToggle: persistent, profile-scoped `/mcp enable|disable` (ticket 10).
  *
- * The profile's `mcp` array in its OWNING catalog is the profile-scoped
+ * The profile's `mcps` array in its OWNING catalog is the profile-scoped
  * state store (ticket 04 established that pi-mcp-adapter@2.33.0 has no
  * allowlist/profile-state API — ADR-0002's assumed store does not exist;
  * pi-profile-switch owns the contract). The runtime effect is the caller's
@@ -20,7 +20,13 @@
  */
 
 import { discoverAdapterServerNames } from "../mcp-config.ts";
-import { CatalogError, DEFAULT_PROFILE_NAME, type ProfileDefinition, type ProfileSource } from "../profile-catalog.ts";
+import {
+	CatalogError,
+	DEFAULT_PROFILE_NAME,
+	LEGACY_FIELD_ALIASES,
+	type ProfileDefinition,
+	type ProfileSource,
+} from "../profile-catalog.ts";
 import { catalogStore, readCatalogScope, type CatalogScope } from "./profile-crud.ts";
 
 export async function setMcpServerEnabled(
@@ -32,7 +38,7 @@ export async function setMcpServerEnabled(
 	},
 	server: string,
 	enabled: boolean,
-): Promise<{ mcp: string[]; changed: boolean }> {
+): Promise<{ mcps: string[]; changed: boolean }> {
 	const { name, source } = input.profile;
 	if (name === DEFAULT_PROFILE_NAME || source === "builtin") {
 		throw new CatalogError(
@@ -60,16 +66,18 @@ export async function setMcpServerEnabled(
 		throw new CatalogError(`profile "${input.profile.name}" not found in the ${scope} catalog`);
 	}
 
-	const current = definition.mcp ?? [];
+	const current = definition.mcps ?? [];
 	if (enabled === current.includes(server)) {
-		return { mcp: current, changed: false }; // already in the requested state
+		return { mcps: current, changed: false }; // already in the requested state
 	}
 	const next = enabled ? [...current, server] : current.filter((name) => name !== server);
 	// Drop the key entirely when empty (exactOptionalPropertyTypes; a
-	// written `mcp: undefined` would also misrepresent the definition).
+	// written `mcps: undefined` would also misrepresent the definition) and
+	// drop the legacy alias, so one save migrates the file to `mcps`.
 	const rest = { ...definition };
-	delete rest.mcp;
-	const updated: ProfileDefinition = next.length > 0 ? { ...rest, mcp: next } : rest;
+	delete rest.mcps;
+	const updated: ProfileDefinition = next.length > 0 ? { ...rest, mcps: next } : rest;
+	delete (updated as Record<string, unknown>)[LEGACY_FIELD_ALIASES.mcps];
 	await catalogStore(input, scope).upsert(input.profile.name, updated);
-	return { mcp: next, changed: true };
+	return { mcps: next, changed: true };
 }

package/src/switching/profile-wizard.ts

@@ -75,7 +75,7 @@ async function captureDefinition(
 
 	const listFields = [
 		["skills", "skills (comma-separated names or globs, empty = all visible)"],
-		["mcp", "mcp servers (names or globs, empty = none)"],
+		["mcps", "MCP servers (names or globs, empty = none)"],
 		["tools", "tools (names or globs, empty = pi default set)"],
 	] as const;
 	for (const [field, prompt] of listFields) {