pi-profile-switch 0.1.0 → 0.3.0

package/src/mcp-config.ts

@@ -1,23 +1,32 @@
 /**
- * AdapterConfigDiscovery: reads the MCP server NAMES pi-mcp-adapter would
- * discover from its pi-native config files, without ever managing them.
+ * 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.
  *
- * pi-profile-switch never stores MCP connection parameters or credentials
- * (ADR-0002); this module reads only the `mcpServers` key names so an
- * activation can validate a profile's `mcp` references before applying it.
+ * 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).
  *
- * 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 activation validation. The pi-native files are the
- * adapter's documented default, so keep configs there.
+ * 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.
  *
  * Malformed config files fail loudly — a broken mcp.json must not silently
  * read as "no servers" and reject every reference.
  */
 
-import { isRecord, readJsonFile } from "./json-file.ts";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { isRecord, readJsonFileSync } from "./json-file.ts";
 
 export class McpConfigError extends Error {
 	readonly filePath: string;
@@ -29,35 +38,145 @@ export class McpConfigError extends Error {
 	}
 }
 
-async function readServerNames(filePath: string): Promise<string[]> {
-	const result = await readJsonFile(filePath);
-	if (!result.ok) {
-		if (result.reason === "missing") {
-			return [];
+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);
+	if (!result.ok) {
+		if (result.reason === "missing") return undefined;
 		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);
 	}
-	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);
+	return result.value;
 }
 
-/** 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);
-		}
+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);
 	}
-	return [...names].sort();
+	return Object.keys(document.mcpServers);
 }

package/src/mcp-overlay-file.ts

@@ -0,0 +1,35 @@
+/**
+ * McpOverlayFile: the only writer of the generated MCP overlay.
+ *
+ * Invariants:
+ * - Atomic (temporary file + rename) so a reader never sees a half-written
+ *   document.
+ * - Written only when the bytes change: a profile switch that does not move
+ *   the MCP selection produces no write and therefore no reload.
+ * - Mode 0600: the overlay carries the Pi-global slot's definitions verbatim
+ *   when the user keeps servers there, and those definitions may embed
+ *   credentials even though the overlay itself never introduces any.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Current bytes, or undefined when the file is missing/unreadable. */
+export function readMcpOverlaySync(overlayPath: string): string | undefined {
+	try {
+		return readFileSync(overlayPath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Writes `content` when it differs from what is on disk. Returns true when
+ *  the file changed. */
+export function writeMcpOverlayIfChangedSync(overlayPath: string, content: string): boolean {
+	if (readMcpOverlaySync(overlayPath) === content) return false;
+	mkdirSync(path.dirname(overlayPath), { recursive: true });
+	const temporary = `${overlayPath}.tmp-${process.pid}`;
+	writeFileSync(temporary, content, { mode: 0o600 });
+	renameSync(temporary, overlayPath);
+	return true;
+}

package/src/mcp-overlay.ts

@@ -0,0 +1,122 @@
+/**
+ * McpOverlay: the PURE half of the profile-scoped MCP filter.
+ *
+ * `pi-mcp-adapter` has no runtime allowlist channel (ADR-0002 amendment), so
+ * the profile's `mcp` declaration is enforced by a generated config file the
+ * adapter reads as its "Pi global override" slot (the slot `--mcp-config`
+ * replaces). The file is a DISABLE OVERLAY: entries carry no connection
+ * parameters and no credentials — `{ "<server>": { "disabled": true } }` is
+ * the adapter's own idiom for `/mcp disable`, and its config merge is
+ * per-field, so a stub merges onto the definition owned by the user's own
+ * file.
+ *
+ * One exception is structural: because the overlay file REPLACES the Pi
+ * global slot, the servers the user keeps in that slot are carried over
+ * verbatim from the sidecar (`mcp.user.json`); a hand-written slot file is
+ * adopted into the sidecar before the first overwrite.
+ *
+ * `allowed` semantics:
+ * - `"all"` — the profile declares no `mcp`: nothing is disabled.
+ * - `[]` — every discovered server is disabled.
+ * - `["github", …]` — everything outside the list is disabled.
+ */
+
+import path from "node:path";
+
+import { isRecord } from "./json-file.ts";
+import { matchesReference } from "./name-matching.ts";
+
+/**
+ * The generated overlay REPLACES the adapter's Pi-global slot, so it lives at
+ * the slot's default path. The user's own Pi-global servers move to a sidecar
+ * that this package never writes except when adopting a hand-written slot.
+ */
+export const MCP_SLOT_FILE_NAME = "mcp.json";
+export const MCP_SOURCE_FILE_NAME = "mcp.user.json";
+/** Top-level key marking a file as generated. The adapter ignores unknown
+ *  top-level keys, so the marker never reaches it as configuration. */
+export const MCP_GENERATED_MARKER = "piProfileSwitch";
+
+/** The adapter's Pi-global slot: the generated overlay. */
+export function mcpSlotPath(agentDir: string): string {
+	return path.join(agentDir, MCP_SLOT_FILE_NAME);
+}
+
+/** The user-owned sidecar holding the Pi-global servers verbatim. */
+export function mcpSourcePath(agentDir: string): string {
+	return path.join(agentDir, MCP_SOURCE_FILE_NAME);
+}
+
+/** True when the document was produced by pi-profile-switch. */
+export function isGeneratedOverlay(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	const marker = value[MCP_GENERATED_MARKER];
+	return isRecord(marker) && marker.generated === true;
+}
+
+/** True for the credential-free stubs the overlay adds for servers defined in
+ *  the adapter's other sources. */
+export function isDisabledStub(value: unknown): boolean {
+	return isRecord(value) && Object.keys(value).length === 1 && value.disabled === true;
+}
+
+/** Server names a profile's `mcp` references resolve to. `undefined` (the
+ *  profile declares nothing) means "no filtering" and is reported as the
+ *  literal `"all"`. Glob references follow the same rules as every other
+ *  profile reference. */
+export function resolveAllowedServers(
+	refs: readonly string[] | undefined,
+	discovered: readonly string[],
+): readonly string[] | "all" {
+	if (refs === undefined) return "all";
+	const allowed = new Set<string>();
+	for (const ref of refs) {
+		for (const name of discovered) {
+			if (matchesReference(ref, name)) allowed.add(name);
+		}
+	}
+	return [...allowed];
+}
+
+export interface McpOverlayInput {
+	/** Parsed Pi-global slot document, when the user has one. */
+	slotDocument?: Record<string, unknown>;
+	/** Server names defined in the adapter's other file sources. */
+	otherServerNames: readonly string[];
+	allowed: readonly string[] | "all";
+}
+
+/** Builds the overlay document. Server order is sorted so the serialized
+ *  bytes are stable and a rewrite only happens on a real change. */
+export function buildMcpOverlay(input: McpOverlayInput): Record<string, unknown> {
+	const allowed = input.allowed === "all" ? undefined : new Set(input.allowed);
+	const slotServers = isRecord(input.slotDocument?.mcpServers) ? input.slotDocument.mcpServers : {};
+	const servers: Record<string, unknown> = {};
+	for (const [name, definition] of Object.entries(slotServers)) {
+		if (allowed === undefined || allowed.has(name) || !isRecord(definition)) {
+			servers[name] = definition;
+			continue;
+		}
+		servers[name] = { ...definition, disabled: true };
+	}
+	for (const name of input.otherServerNames) {
+		if (name in servers) continue; // the slot's definition owns the name
+		if (allowed === undefined || allowed.has(name)) continue;
+		servers[name] = { disabled: true };
+	}
+	const document: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input.slotDocument ?? {})) {
+		if (key !== "mcpServers" && key !== MCP_GENERATED_MARKER) document[key] = value;
+	}
+	document[MCP_GENERATED_MARKER] = { generated: true, version: 1 };
+	document.mcpServers = Object.fromEntries(
+		Object.entries(servers).sort(([left], [right]) => left.localeCompare(right)),
+	);
+	return document;
+}
+
+/** Stable serialization: two runs with the same semantics produce the same
+ *  bytes, so the writer can skip no-op writes. */
+export function serializeMcpOverlay(document: Record<string, unknown>): string {
+	return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/profile-badge.ts

@@ -0,0 +1,142 @@
+/**
+ * Profile badge: the persistent, one-line answer to "which profile is this
+ * session running?".
+ *
+ * Presentation only — no state, no I/O, no activation. The extension decides
+ * when a badge is written (after an activation that succeeded, via
+ * `ctx.ui.setStatus(PROFILE_STATUS_KEY, …)`), so the badge can never claim a
+ * selection that was not applied.
+ *
+ * One canonical rendering, shared with the `/profile status` heading
+ * (`profile: <name>`), plus `*` when a runtime overlay is in effect — the only
+ * runtime difference the catalog does not show.
+ */
+
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import { DEFAULT_PROFILE_NAME } from "./profile-catalog.ts";
+
+/**
+ * Status key in Pi's footer. Pi joins all extension statuses into one line,
+ * orders them by key, and truncates that line from the right — so an earlier
+ * key keeps its text visible on a narrow terminal. `active-profile` sorts
+ * before the keys it shares the line with (`mcp`, `pi-…`, `thinking`).
+ */
+export const PROFILE_STATUS_KEY = "active-profile";
+
+/** The label prefix, matching the `/profile status` heading. */
+export const PROFILE_BADGE_LABEL = "profile";
+
+/**
+ * Display columns reserved for the name before it is elided. The footer is a
+ * shared, fixed-width line: profile names are unbounded user input, so an
+ * unelided name would evict the statuses of other extensions.
+ */
+export const PROFILE_BADGE_NAME_COLUMNS = 16;
+
+const ELLIPSIS = "…";
+
+export interface ProfileBadge {
+	/** The name `/profile use` accepts (never the display `label`). */
+	name: string;
+	/** A runtime overlay is in effect: this runtime differs from the catalog. */
+	overlay: boolean;
+}
+
+/** The minimum theme surface the badge needs; `ctx.ui.theme` satisfies it. */
+export interface BadgeTheme {
+	fg(color: ThemeColor, text: string): string;
+}
+
+export interface BadgeOptions {
+	overlay: boolean;
+	/** Override the name budget (tests, future width awareness). */
+	nameColumns?: number;
+}
+
+/**
+ * Builds the badge for a resolved profile, or `undefined` when there must be
+ * no badge at all.
+ *
+ * `default` is Pi's native baseline — it declares nothing — so it must not
+ * change the footer either: a plain Pi session shows no badge, and the footer
+ * status line only exists while some extension status is set.
+ */
+export function buildProfileBadge(name: string, options: BadgeOptions): ProfileBadge | undefined {
+	if (name === DEFAULT_PROFILE_NAME) return undefined;
+	return {
+		name: truncateToColumns(name, options.nameColumns ?? PROFILE_BADGE_NAME_COLUMNS),
+		overlay: options.overlay,
+	};
+}
+
+/**
+ * Renders the badge. Colors come from the caller's theme at render time: Pi
+ * stores footer statuses as finished strings, so the extension re-renders on
+ * profile changes and on each turn (there is no extension-visible theme-change
+ * event).
+ */
+export function renderProfileBadge(badge: ProfileBadge, theme: BadgeTheme): string {
+	const label = theme.fg("dim", `${PROFILE_BADGE_LABEL}: `);
+	const name = theme.fg("dim", badge.name);
+	return badge.overlay ? `${label}${name}${theme.fg("warning", "*")}` : `${label}${name}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Display width                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Width of one code point in terminal columns: 2 for East Asian wide and
+ * fullwidth code points, 1 otherwise. Zero-width joiners and combining marks
+ * are counted as 1 — an approximation that only over-reserves space for
+ * exotic names.
+ */
+export function codePointWidth(codePoint: number): number {
+	return isWide(codePoint) ? 2 : 1;
+}
+
+/** Display width of `text` in terminal columns. */
+export function displayWidth(text: string): number {
+	let width = 0;
+	for (const character of text) width += codePointWidth(character.codePointAt(0)!);
+	return width;
+}
+
+/**
+ * Truncates `text` to at most `columns` terminal columns, appending `…` when
+ * something was dropped. The ellipsis is part of the budget, so the result
+ * never exceeds `columns`.
+ */
+export function truncateToColumns(text: string, columns: number, ellipsis = ELLIPSIS): string {
+	if (columns <= 0) return "";
+	if (displayWidth(text) <= columns) return text;
+	const budget = columns - displayWidth(ellipsis);
+	let result = "";
+	let width = 0;
+	for (const character of text) {
+		const next = width + codePointWidth(character.codePointAt(0)!);
+		if (next > budget) break;
+		result += character;
+		width = next;
+	}
+	return budget < 0 ? "" : `${result}${ellipsis}`;
+}
+
+function isWide(codePoint: number): boolean {
+	return (
+		(codePoint >= 0x1100 && codePoint <= 0x115f) || // Hangul Jamo
+		(codePoint >= 0x2e80 && codePoint <= 0x303e) || // CJK radicals, Kangxi, CJK symbols
+		(codePoint >= 0x3041 && codePoint <= 0x33ff) || // kana, CJK compatibility, CJK punctuation
+		(codePoint >= 0x3400 && codePoint <= 0x4dbf) || // CJK unified ideographs extension A
+		(codePoint >= 0x4e00 && codePoint <= 0x9fff) || // CJK unified ideographs
+		(codePoint >= 0xa000 && codePoint <= 0xa4cf) || // Yi syllables
+		(codePoint >= 0xac00 && codePoint <= 0xd7a3) || // Hangul syllables
+		(codePoint >= 0xf900 && codePoint <= 0xfaff) || // CJK compatibility ideographs
+		(codePoint >= 0xfe30 && codePoint <= 0xfe6f) || // CJK compatibility forms
+		(codePoint >= 0xff00 && codePoint <= 0xff60) || // fullwidth forms
+		(codePoint >= 0xffe0 && codePoint <= 0xffe6) || // fullwidth signs
+		(codePoint >= 0x1f300 && codePoint <= 0x1faff) || // emoji, pictographs
+		(codePoint >= 0x20000 && codePoint <= 0x3fffd) // CJK unified ideographs extension B+
+	);
+}

package/src/profile-catalog-store.ts

@@ -3,9 +3,8 @@
  * separate from the read-only ProfileCatalog.
  *
  * Invariants:
- * - Whole-file overwrites (pretty-printed, `schemaVersion 2` envelope).
- *   A version 1 file is read with its `extensions` fields dropped and is
- *   rewritten as version 2 on the next save; wizard saves never block on
+ * - 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.
  * - Definitions are complete and self-contained: no inheritance fields
@@ -38,7 +37,7 @@ export class ProfileCatalogStore {
 
 	/** Validated definitions: missing file → empty; malformed → CatalogError
 	 *  (catalog errors never pass silently, even on the write path).
-	 *  Version 1 files load with `extensions` dropped. */
+	 *  Unknown fields (an `extensions` key left over from v0.1.0) are dropped. */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
 		const result = await readJsonFile(this.#filePath);
 		if (!result.ok) {
@@ -48,7 +47,7 @@ export class ProfileCatalogStore {
 		if (!isRecord(result.value)) {
 			throw new CatalogError(`${this.#filePath}: catalog must be an object`);
 		}
-		return parseCatalogDocument(result.value, this.#filePath).profiles;
+		return parseCatalogDocument(result.value, this.#filePath);
 	}
 
 	/** Overwrites the file with the given definitions (last write wins). */