pi-profile-switch 0.1.0

package/src/switching/apply-profile.ts

@@ -0,0 +1,131 @@
+/**
+ * ApplyProfile: applies a resolved selection to the running Pi.
+ *
+ * Replaces the launch-plan application of the host architecture: there is no
+ * plan file and no reload. Application is ordered so that the only
+ * fallible step — the model preset — runs first; a failure leaves the
+ * runtime untouched and the caller keeps the previous state.
+ *
+ * Steps:
+ *   1. validate: the declared model exists and has configured auth.
+ *   2. model: `setModel` + `setThinkingLevel` (when the preset applies).
+ *   3. tools: `setActiveTools` with the resolved active set. Literals the
+ *      live registry does not provide yet stay in `pendingTools` and are
+ *      retried by the caller each turn (MCP and extension tools register
+ *      after session start).
+ *   4. mcp: publish the runtime server allowlist to pi-mcp-adapter.
+ *
+ * Dependency-injected against a narrow surface so unit tests never need a
+ * real Pi.
+ */
+
+import {
+	MCP_ALLOWLIST_EVENT,
+	MCP_ALLOWLIST_VERSION,
+} from "../mcp-coordination.ts";
+import type { PresetDecisions } from "../model-selection.ts";
+import type { ResolvedSelection } from "../profile-resolver.ts";
+
+/** The narrow slice of ExtensionAPI/Context the application needs. */
+export interface ApplySurface {
+	getAllTools(): Array<{ name: string }>;
+	setActiveTools(names: string[]): void;
+	modelRegistry: {
+		find(provider: string, id: string): unknown | undefined;
+		hasConfiguredAuth(model: unknown): boolean;
+	};
+	setModel(model: unknown): Promise<boolean>;
+	setThinkingLevel(level: string): void;
+	events: { emit(channel: string, data: unknown): void };
+}
+
+export interface ApplyResult {
+	applied: boolean;
+	/** Present when nothing was applied. */
+	error?: string;
+	warnings: string[];
+	/** Tool literals still missing from the live registry. */
+	pendingTools: string[];
+}
+
+/** Checks everything that can be checked before mutating the runtime. */
+export function validateSelection(
+	selection: ResolvedSelection,
+	surface: ApplySurface,
+	preset: PresetDecisions,
+): string | undefined {
+	if (selection.model === undefined || !preset.model) return undefined;
+	const model = surface.modelRegistry.find(selection.model.provider, selection.model.id);
+	if (model === undefined) {
+		return `profile "${selection.name}": declared model ${selection.model.provider}/${selection.model.id} not found`;
+	}
+	if (!surface.modelRegistry.hasConfiguredAuth(model)) {
+		return `profile "${selection.name}": model ${selection.model.provider}/${selection.model.id} has no configured auth`;
+	}
+	return undefined;
+}
+
+/** Applies the selection. Validation runs first; on failure nothing is
+ *  applied and the runtime keeps its previous state. */
+export async function applySelection(input: {
+	selection: ResolvedSelection;
+	surface: ApplySurface;
+	preset: PresetDecisions;
+}): Promise<ApplyResult> {
+	const { selection, surface, preset } = input;
+	const error = validateSelection(selection, surface, preset);
+	if (error !== undefined) {
+		return { applied: false, error, warnings: [], pendingTools: [] };
+	}
+
+	if (selection.model !== undefined && preset.model) {
+		const model = surface.modelRegistry.find(selection.model.provider, selection.model.id);
+		const applied = await surface.setModel(model);
+		if (!applied) {
+			return {
+				applied: false,
+				error: `profile "${selection.name}": model ${selection.model.provider}/${selection.model.id} could not be activated`,
+				warnings: [],
+				pendingTools: [],
+			};
+		}
+		if (selection.model.thinkingLevel !== undefined && preset.thinking) {
+			surface.setThinkingLevel(selection.model.thinkingLevel);
+		}
+	}
+
+	if (selection.tools !== undefined) {
+		surface.setActiveTools(selection.tools);
+	}
+
+	if (selection.mcp !== undefined) {
+		surface.events.emit(MCP_ALLOWLIST_EVENT, {
+			version: MCP_ALLOWLIST_VERSION,
+			profile: selection.name,
+			servers: selection.mcp,
+		});
+	}
+
+	return { applied: true, warnings: [], pendingTools: selection.pendingTools };
+}
+
+/** Retries pending tool literals against the live registry. Once every
+ *  literal resolves the caller stops retrying, so a user's later native tool
+ *  toggle is never clobbered. */
+export function retryPendingTools(input: {
+	selection: ResolvedSelection;
+	surface: ApplySurface;
+}): { pendingTools: string[]; active?: string[]; applied: boolean } {
+	const { selection, surface } = input;
+	if (selection.pendingTools.length === 0) {
+		return { pendingTools: [], applied: false };
+	}
+	const live = new Set(surface.getAllTools().map((tool) => tool.name));
+	const resolved = selection.pendingTools.filter((name) => live.has(name));
+	if (resolved.length === 0) {
+		return { pendingTools: selection.pendingTools, applied: false };
+	}
+	const active = [...new Set([...(selection.tools ?? []), ...resolved])];
+	surface.setActiveTools(active);
+	return { pendingTools: selection.pendingTools.filter((name) => !live.has(name)), active, applied: true };
+}

package/src/switching/customize.ts

@@ -0,0 +1,87 @@
+/**
+ * Overlay customize/reset orchestration.
+ *
+ * The overlay narrows the ACTIVE profile for this runtime only. It is
+ * written to the scope state file (never a catalog) as persistence and the
+ * status surface; the runtime effect flows through re-resolution with the
+ * overlay, exactly like a switch. Startup activation ignores stored
+ * overlays, so an overlay never outlives its runtime.
+ *
+ * Ordering invariants:
+ * - customize: activate with the candidate overlay FIRST (validation:
+ *   unknown references fail here, before anything is written), then persist
+ *   the overlay to state. A failed activation leaves the stored overlay
+ *   untouched.
+ * - reset: activate without the overlay first, then delete it from state.
+ */
+
+
+import type { ProfileSource } from "../profile-catalog.ts";
+import { RuntimeStateStore, stateDirFor, type RuntimeOverlay } from "../runtime-state-store.ts";
+import { activateProfile, ActivationError, type ActivationDeps, type ActivationResult } from "./activate-profile.ts";
+
+export interface OverlayTarget {
+	profile: { name: string; source: ProfileSource };
+}
+
+/** Applies a mutation to the active profile's overlay and re-activates. */
+export async function customizeOverlay(
+	deps: ActivationDeps & OverlayTarget,
+	mutate: (overlay: RuntimeOverlay) => RuntimeOverlay,
+): Promise<ActivationResult> {
+	const stateDir = stateDirFor(deps.profile.source, deps);
+	const stored = (await new RuntimeStateStore(stateDir).read()).overlay ?? {};
+	const candidate = mutate(stored);
+	// activateProfile re-resolves with the candidate and persists it
+	// (overlay in the state update) — validation fails before any write.
+	return activateProfile(deps.profile.name, deps, { overlay: candidate, persist: true });
+}
+
+/** Discards the overlay and reactivates the profile exactly as declared. */
+export async function resetOverlay(deps: ActivationDeps & OverlayTarget): Promise<ActivationResult> {
+	return activateProfile(deps.profile.name, deps, { overlay: null, persist: true });
+}
+
+export const CUSTOMIZE_USAGE =
+	"/profile customize disable|enable skill|mcp <name> · /profile customize tools [ref...]" as const;
+
+const DISABLED_FIELDS = {
+	skill: "disabledSkills",
+	mcp: "disabledMcp",
+} as const;
+
+/** Parses `/profile customize` arguments into an overlay mutation.
+ *  Grammar:
+ *    customize disable skill|mcp <name>
+ *    customize enable  skill|mcp <name>   (un-disable)
+ *    customize tools <ref>...             (replace tool refs)
+ *    customize tools                      (clear the tools override)
+ */
+export function parseCustomizeArgs(args: string): (overlay: RuntimeOverlay) => RuntimeOverlay {
+	const [action, kind, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+
+	if (action === "tools") {
+		const refs = [kind, ...rest].filter((entry): entry is string => entry !== undefined);
+		return (overlay) => {
+			const next = { ...overlay };
+			if (refs.length === 0) delete next.tools;
+			else next.tools = refs;
+			return next;
+		};
+	}
+
+	const field = DISABLED_FIELDS[kind as keyof typeof DISABLED_FIELDS];
+	if (field === undefined || (action !== "disable" && action !== "enable") || rest.length !== 1) {
+		throw new ActivationError(`usage: ${CUSTOMIZE_USAGE}`);
+	}
+	const [name] = rest;
+	return (overlay) => {
+		const current = overlay[field] ?? [];
+		const nextList =
+			action === "disable" ? [...new Set([...current, name])] : current.filter((entry) => entry !== name);
+		const next = { ...overlay };
+		if (nextList.length === 0) delete next[field];
+		else next[field] = nextList;
+		return next;
+	};
+}

package/src/switching/list-profiles.ts

@@ -0,0 +1,55 @@
+/**
+ * ProfileListing: the `/profile list` and `/profile` selector data surface.
+ *
+ * Trust-gated exactly like activation: an untrusted project's profiles are
+ * invisible. The listing reports each visible profile with the source of
+ * the WINNING definition (a same-name project definition fully replaces the
+ * global one — the shadowed global entry is reported as such).
+ */
+
+import { ProfileCatalog, type ProfileSource } from "../profile-catalog.ts";
+
+export interface ProfileListEntry {
+	name: string;
+	/** The source of the winning definition. */
+	source: ProfileSource;
+	label?: string;
+	description?: string;
+	/** True when a global definition of the same name is shadowed by the
+	 *  project one. */
+	shadowsGlobal: boolean;
+}
+
+export async function listProfiles(input: {
+	realAgentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+}): Promise<{ entries: ProfileListEntry[]; warnings: string[] }> {
+	const catalog = await ProfileCatalog.load(input.realAgentDir, {
+		projectDir: input.projectTrusted ? input.cwd : undefined,
+	});
+	return {
+		entries: catalog.list().map((profile) => ({
+			name: profile.name,
+			source: profile.source,
+			...(typeof profile.definition.label === "string" ? { label: profile.definition.label } : {}),
+			...(typeof profile.definition.description === "string" ? { description: profile.definition.description } : {}),
+			shadowsGlobal: profile.source === "project" && catalog.shadowsGlobal(profile.name),
+		})),
+		warnings: [...catalog.warnings],
+	};
+}
+
+export function formatProfileList(entries: ProfileListEntry[], activeProfile?: string): string {
+	if (entries.length === 0) {
+		return "no profiles found";
+	}
+	return entries
+		.map((entry) => {
+			const active = entry.name === activeProfile ? " ← active" : "";
+			const shadowed = entry.shadowsGlobal ? " (shadows global)" : "";
+			const label = entry.label ?? entry.description;
+			return `${entry.name} [${entry.source}]${shadowed}${label !== undefined ? ` — ${label}` : ""}${active}`;
+		})
+		.join("\n");
+}

package/src/switching/mcp-toggle.ts

@@ -0,0 +1,75 @@
+/**
+ * McpToggle: persistent, profile-scoped `/mcp enable|disable` (ticket 10).
+ *
+ * The profile's `mcp` 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
+ * re-activation of the active profile, which republishes the allowlist over
+ * the coordination channel.
+ *
+ * Invariants:
+ * - Enable accepts only adapter-discovered names (fail fast on typos);
+ *   disable also removes names the adapter no longer reports (stale
+ *   cleanup).
+ * - The built-in default profile has no catalog entry — toggling it is a
+ *   clear error, not a synthetic write.
+ * - Only the ACTIVE profile's array changes; other profiles and the
+ *   adapter's own configuration (global mcp.json, project .pi/mcp.json)
+ *   are never modified.
+ */
+
+import { discoverAdapterServerNames } from "../mcp-config.ts";
+import { CatalogError, DEFAULT_PROFILE_NAME, type ProfileDefinition, type ProfileSource } from "../profile-catalog.ts";
+import { catalogStore, readCatalogScope, type CatalogScope } from "./profile-crud.ts";
+
+export async function setMcpServerEnabled(
+	input: {
+		realAgentDir: string;
+		cwd: string;
+		projectTrusted: boolean;
+		profile: { name: string; source: ProfileSource };
+	},
+	server: string,
+	enabled: boolean,
+): Promise<{ mcp: string[]; changed: boolean }> {
+	const { name, source } = input.profile;
+	if (name === DEFAULT_PROFILE_NAME || source === "builtin") {
+		throw new CatalogError(
+			`the built-in default profile has no catalog entry — create a named profile (/profile create) to toggle MCP servers`,
+		);
+	}
+	if (source !== "global" && source !== "project") {
+		throw new CatalogError(`profile "${name}" has no writable owning catalog (source: ${source})`);
+	}
+	const scope: CatalogScope = source;
+
+	if (scope === "project" && !input.projectTrusted) {
+		throw new CatalogError(`project catalog is unavailable: ${input.cwd} is not trusted`);
+	}
+	const discovered = await discoverAdapterServerNames(input.realAgentDir, input.projectTrusted ? input.cwd : undefined);
+	if (enabled && !discovered.includes(server)) {
+		throw new CatalogError(
+			`unknown MCP server "${server}" — adapter discovered: [${discovered.join(", ") || "(none)"}]`,
+		);
+	}
+
+	const definitions = await readCatalogScope(input, scope);
+	const definition = definitions.get(input.profile.name);
+	if (definition === undefined) {
+		throw new CatalogError(`profile "${input.profile.name}" not found in the ${scope} catalog`);
+	}
+
+	const current = definition.mcp ?? [];
+	if (enabled === current.includes(server)) {
+		return { mcp: 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).
+	const rest = { ...definition };
+	delete rest.mcp;
+	const updated: ProfileDefinition = next.length > 0 ? { ...rest, mcp: next } : rest;
+	await catalogStore(input, scope).upsert(input.profile.name, updated);
+	return { mcp: next, changed: true };
+}

package/src/switching/profile-crud.ts

@@ -0,0 +1,132 @@
+/**
+ * ProfileCrud: `/profile create|edit|delete|duplicate` semantics (ticket 09)
+ * on top of ProfileCatalogStore.
+ *
+ * Invariants:
+ * - Trust-gated exactly like activation: an untrusted project's catalog is
+ *   never read or written.
+ * - Deleting the ACTIVE profile requires a replacement up front — the
+ *   session must land somewhere defined; the caller switches to it.
+ * - Deleting one scope's record while the other scope keeps the name
+ *   reveals that definition (merged-catalog semantics; nothing extra to
+ *   do beyond reloading).
+ * - Duplicating copies the COMPLETE definition under a new name — the
+ *   only variant mechanism (no inheritance).
+ */
+
+import path from "node:path";
+
+import { CatalogError, DEFAULT_PROFILE_NAME, type ProfileDefinition } from "../profile-catalog.ts";
+import { ProfileCatalogStore } from "../profile-catalog-store.ts";
+
+export type CatalogScope = "global" | "project";
+
+/** The caller's trust decision (`ctx.isProjectTrusted()`) plus the two
+ *  directories scope files live in. */
+export interface CatalogInput {
+	realAgentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+}
+
+/** The store for one scope's catalog file — the ONLY place scope-file
+ *  paths are constructed. Callers must still trust-gate project access
+ *  (`requireScope` / `readCatalogScope`). */
+export function catalogStore(input: CatalogInput, scope: CatalogScope): ProfileCatalogStore {
+	return new ProfileCatalogStore(
+		scope === "global" ? path.join(input.realAgentDir, "profiles.json") : path.join(input.cwd, ".pi", "profiles.json"),
+	);
+}
+
+function requireScope(input: CatalogInput, scope: CatalogScope): void {
+	if (scope === "project" && !input.projectTrusted) {
+		throw new CatalogError(`project catalog is unavailable: ${input.cwd} is not trusted`);
+	}
+}
+
+/** Reads one scope's catalog with the trust gate applied — project reads
+ *  return empty when untrusted (never touching the file). */
+export async function readCatalogScope(
+	input: CatalogInput,
+	scope: CatalogScope,
+): Promise<Map<string, ProfileDefinition>> {
+	if (scope === "project" && !input.projectTrusted) {
+		return new Map();
+	}
+	return catalogStore(input, scope).readDefinitions();
+}
+
+/** Creates a complete definition in the chosen scope. */
+export async function createProfile(
+	input: CatalogInput,
+	scope: CatalogScope,
+	name: string,
+	definition: ProfileDefinition,
+): Promise<void> {
+	requireScope(input, scope);
+	const store = catalogStore(input, scope);
+	if ((await store.readDefinitions()).has(name)) {
+		throw new CatalogError(`profile "${name}" already exists in the ${scope} catalog`);
+	}
+	await store.upsert(name, definition);
+}
+
+/** Replaces a complete definition; the caller reloads iff it is active. */
+export async function editProfile(
+	input: CatalogInput,
+	scope: CatalogScope,
+	name: string,
+	definition: ProfileDefinition,
+): Promise<void> {
+	requireScope(input, scope);
+	if (name === DEFAULT_PROFILE_NAME) {
+		throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and cannot be edited`);
+	}
+	const store = catalogStore(input, scope);
+	if (!(await store.readDefinitions()).has(name)) {
+		throw new CatalogError(`profile "${name}" not found in the ${scope} catalog`);
+	}
+	await store.upsert(name, definition);
+}
+
+/**
+ * Deletes a profile from the chosen scope. Deleting the active profile
+ * requires `replacement` (validated for existence in the remaining merged
+ * catalog by the caller's switch); the built-in default can never be
+ * deleted.
+ */
+export async function deleteProfile(
+	input: CatalogInput,
+	scope: CatalogScope,
+	name: string,
+	options: { activeProfile?: string; replacement?: string },
+): Promise<void> {
+	requireScope(input, scope);
+	if (name === DEFAULT_PROFILE_NAME) {
+		throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and cannot be deleted`);
+	}
+	if (options.activeProfile === name && options.replacement === undefined) {
+		throw new CatalogError(`profile "${name}" is active — choose a replacement profile first`);
+	}
+	await catalogStore(input, scope).remove(name);
+}
+
+/** Copies a complete definition under a new, unused name. */
+export async function duplicateProfile(
+	input: CatalogInput,
+	scope: CatalogScope,
+	sourceName: string,
+	newName: string,
+): Promise<void> {
+	requireScope(input, scope);
+	const store = catalogStore(input, scope);
+	const definitions = await store.readDefinitions();
+	const source = definitions.get(sourceName);
+	if (source === undefined) {
+		throw new CatalogError(`profile "${sourceName}" not found in the ${scope} catalog`);
+	}
+	if (definitions.has(newName)) {
+		throw new CatalogError(`profile "${newName}" already exists in the ${scope} catalog`);
+	}
+	await store.upsert(newName, { ...source });
+}

package/src/switching/profile-wizard.ts

@@ -0,0 +1,158 @@
+/**
+ * ProfileWizard: the interactive create/edit/duplicate dialog for
+ * `/profile create|edit|delete|duplicate` (ticket 09), UI-injected for
+ * testability.
+ *
+ * Definitions are complete and self-contained — the wizard edits whole
+ * fields, never inheritance or merge syntax. On edit, an empty answer
+ * keeps the current value (prefill via placeholder); there is no
+ * field-clearing gesture (delete + create instead). Any cancelled step
+ * aborts the wizard — nothing is written.
+ */
+
+import type { ProfileDefinition } from "../profile-catalog.ts";
+import type { CatalogScope } from "./profile-crud.ts";
+
+export interface ProfileWizardUi {
+	select(title: string, options: string[]): Promise<string | undefined>;
+	input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+
+export interface ProfileWizardResult {
+	scope: CatalogScope;
+	name: string;
+	definition: ProfileDefinition;
+}
+
+interface ExistingProfile {
+	name: string;
+	source: CatalogScope;
+	definition: ProfileDefinition;
+}
+
+function parseList(raw: string): string[] {
+	return raw
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+}
+
+/** "provider/id[/thinkingLevel]" → ProfileModel; empty/undefined → none. */
+function parseModel(raw: string): ProfileDefinition["model"] | undefined {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return undefined;
+	const [provider, id, thinkingLevel] = trimmed.split("/").map((part) => part.trim());
+	if (provider === undefined || provider.length === 0 || id === undefined || id.length === 0) {
+		return undefined;
+	}
+	return thinkingLevel !== undefined && thinkingLevel.length > 0
+		? { provider, id, thinkingLevel }
+		: { provider, id };
+}
+
+async function captureDefinition(
+	ui: ProfileWizardUi,
+	existing?: ProfileDefinition,
+): Promise<ProfileDefinition | undefined> {
+	const definition: ProfileDefinition = {};
+
+	const label = await ui.input("label (optional; empty keeps current)", existing?.label);
+	if (label === undefined) return undefined;
+	if (label.trim().length > 0) definition.label = label.trim();
+	else if (existing?.label !== undefined) definition.label = existing.label;
+
+	const description = await ui.input("description (optional; empty keeps current)", existing?.description);
+	if (description === undefined) return undefined;
+	if (description.trim().length > 0) definition.description = description.trim();
+	else if (existing?.description !== undefined) definition.description = existing.description;
+
+	const listFields = [
+		["skills", "skills (comma-separated names or globs, empty = all visible)"],
+		["mcp", "mcp servers (names or globs, empty = none)"],
+		["tools", "tools (names or globs, empty = pi default set)"],
+	] as const;
+	for (const [field, prompt] of listFields) {
+		const current = existing?.[field]?.join(", ");
+		const raw = await ui.input(prompt, current);
+		if (raw === undefined) return undefined;
+		const parsed = parseList(raw);
+		// Empty keeps the existing value on edit; on create it omits the field.
+		if (parsed.length > 0) {
+			definition[field] = parsed;
+		} else if (current !== undefined) {
+			definition[field] = existing?.[field];
+		}
+	}
+
+	const instructions = await ui.input(
+		"instructions (appended to the system prompt; empty keeps current)",
+		existing?.instructions,
+	);
+	if (instructions === undefined) return undefined;
+	if (instructions.trim().length > 0) definition.instructions = instructions;
+	else if (existing?.instructions !== undefined) definition.instructions = existing.instructions;
+
+	const currentModel =
+		existing?.model !== undefined
+			? `${existing.model.provider}/${existing.model.id}${existing.model.thinkingLevel !== undefined ? `/${existing.model.thinkingLevel}` : ""}`
+			: undefined;
+	const modelRaw = await ui.input("model provider/id[/thinking] (empty = none)", currentModel);
+	if (modelRaw === undefined) return undefined;
+	const model = parseModel(modelRaw);
+	if (model !== undefined) {
+		definition.model = model;
+	} else if (existing?.model !== undefined && modelRaw.trim().length === 0) {
+		definition.model = existing.model;
+	}
+
+	return definition;
+}
+
+/** Create: scope first (project only when trusted), then name, then fields. */
+export async function runProfileCreateWizard(
+	ui: ProfileWizardUi,
+	input: { projectTrusted: boolean },
+): Promise<ProfileWizardResult | undefined> {
+	const scopeOptions = input.projectTrusted ? ["global", "project"] : ["global"];
+	// A single available scope needs no dialog.
+	const scope = scopeOptions.length === 1 ? scopeOptions[0] : await ui.select("write to which catalog?", scopeOptions);
+	if (scope === undefined) return undefined;
+
+	const name = await ui.input("profile name");
+	if (name === undefined || name.trim().length === 0) return undefined;
+
+	const definition = await captureDefinition(ui);
+	if (definition === undefined) return undefined;
+
+	return { scope: scope as CatalogScope, name: name.trim(), definition };
+}
+
+/** Edit: fields prefilled from the existing complete definition. */
+export async function runProfileEditWizard(
+	ui: ProfileWizardUi,
+	input: { existing: ExistingProfile },
+): Promise<ProfileWizardResult | undefined> {
+	const definition = await captureDefinition(ui, input.existing.definition);
+	if (definition === undefined) return undefined;
+	return { scope: input.existing.source, name: input.existing.name, definition };
+}
+
+/** Duplicate: pick a source, name the copy — the only variant mechanism. */
+export async function runProfileDuplicateWizard(
+	ui: ProfileWizardUi,
+	input: { candidates: ExistingProfile[] },
+): Promise<{ scope: CatalogScope; sourceName: string; newName: string } | undefined> {
+	if (input.candidates.length === 0) return undefined;
+	const options = input.candidates.map(
+		(candidate) => `${candidate.name} [${candidate.source}]${candidate.definition.label !== undefined ? ` — ${candidate.definition.label}` : ""}`,
+	);
+	const chosen = await ui.select("duplicate which profile?", options);
+	if (chosen === undefined) return undefined;
+	const source = input.candidates.find((candidate) => chosen.startsWith(`${candidate.name} [`));
+	if (source === undefined) return undefined;
+
+	const newName = await ui.input("new profile name");
+	if (newName === undefined || newName.trim().length === 0) return undefined;
+
+	return { scope: source.source, sourceName: source.name, newName: newName.trim() };
+}