@narumitw/pi-sync 0.49.15 → 0.50.0

package/src/ui/setup/setup-location-ui.ts

@@ -0,0 +1,167 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { normalizeGitBranch } from "../../backends/git/git-config.js";
+import { readLocalConfigObject } from "../../settings/settings-store.js";
+import type {
+	StorageConnectionSettings,
+	SyncSetupSettings,
+} from "../../settings/settings-types.js";
+import {
+	effectiveSyncSetupRemoteIdentity,
+	normalizeStoragePath,
+	ownRecord,
+} from "../../settings/settings-validation.js";
+import { errorMessage } from "../../sync/sync-errors.js";
+import { safeTerminalText } from "../terminal-text.js";
+import {
+	promptTextInput,
+	requiredExistingBucket,
+	requiredInput,
+	requiredValueInput,
+} from "./text-input.js";
+
+interface ChosenRemoteLocation {
+	connectionName: string;
+	bucket: string;
+	path: string;
+}
+
+export async function chooseInitialRemoteLocation(
+	ctx: ExtensionCommandContext,
+	_preset: string,
+	setupName: string,
+	signal?: AbortSignal,
+): Promise<ChosenRemoteLocation | undefined> {
+	const choice = await ctx.ui.select(
+		"Choose storage location\n\nUse an existing bucket. ./ stores snapshots at the bucket root; a custom path keeps them in a separate folder.",
+		["Use an existing bucket at ./", "Customize remote location", "Cancel"],
+		{ signal },
+	);
+	if (signal?.aborted || !choice || choice === "Cancel") return undefined;
+	if (choice === "Customize remote location")
+		return chooseCustomRemoteLocation(ctx, setupName, signal);
+	const bucket = await requiredExistingBucket(ctx, "pi-sync", signal);
+	return bucket ? { connectionName: setupName, bucket, path: "./" } : undefined;
+}
+
+export async function chooseAdditionalRemoteLocation(
+	ctx: ExtensionCommandContext,
+	settings: Record<string, unknown>,
+	connectionName: string,
+	setupName: string,
+	signal?: AbortSignal,
+): Promise<Omit<ChosenRemoteLocation, "connectionName"> | undefined> {
+	const setups = ownRecord(settings.syncSetups) ?? {};
+	const currentSetup =
+		typeof settings.activeSyncSetup === "string" ? settings.activeSyncSetup : undefined;
+	const candidates = Object.entries(setups)
+		.map(([name, value]) => ({ name, storage: ownRecord(ownRecord(value)?.storage) }))
+		.filter(
+			(item): item is { name: string; storage: Record<string, unknown> } =>
+				item.storage?.connection === connectionName && typeof item.storage.bucket === "string",
+		);
+	const source =
+		candidates.find((item) => item.name === currentSetup) ??
+		candidates.sort((left, right) => left.name.localeCompare(right.name))[0];
+	if (source) {
+		const suggestedPath = "./";
+		const sameBucketLabel = `Same bucket as “${safeTerminalText(source.name)}”`;
+		const choice = await ctx.ui.select(
+			[
+				`Storage location for “${safeTerminalText(setupName)}”`,
+				"",
+				`Existing bucket: ${safeTerminalText(String(source.storage.bucket))}`,
+				`Remote path: ${safeTerminalText(suggestedPath)}`,
+				"./ uses the bucket root. Use a different path or bucket for independent setups.",
+			].join("\n"),
+			[sameBucketLabel, "Use a different bucket", "Customize remote location", "Cancel"],
+			{ signal },
+		);
+		if (signal?.aborted || !choice || choice === "Cancel") return undefined;
+		if (choice === sameBucketLabel) {
+			return { bucket: String(source.storage.bucket), path: suggestedPath };
+		}
+		if (choice === "Use a different bucket") {
+			const bucket = await requiredExistingBucket(ctx, "pi-sync", signal);
+			return bucket ? { bucket, path: "./" } : undefined;
+		}
+		const custom = await chooseCustomRemoteLocation(ctx, connectionName, signal);
+		return custom ? { bucket: custom.bucket, path: custom.path } : undefined;
+	}
+
+	const location = await chooseInitialRemoteLocation(ctx, "S3", setupName, signal);
+	return location ? { bucket: location.bucket, path: location.path } : undefined;
+}
+
+async function chooseCustomRemoteLocation(
+	ctx: ExtensionCommandContext,
+	connectionName: string,
+	signal?: AbortSignal,
+): Promise<ChosenRemoteLocation | undefined> {
+	const bucket = await requiredExistingBucket(ctx, "pi-sync", signal);
+	if (!bucket) return undefined;
+	const storagePath = await requiredInput(
+		ctx,
+		"Storage path\n\nPath inside the bucket, not your local filesystem.\n./ uses the bucket root. Use different paths for independent setups.",
+		"./",
+		signal,
+		normalizeStoragePath,
+	);
+	if (!storagePath) return undefined;
+	return { connectionName, bucket, path: normalizeStoragePath(storagePath) };
+}
+
+/** Early UI check only; the settings writer still validates uniqueness under its lock. */
+export async function promptAvailableSetupStorage<T extends SyncSetupSettings["storage"]>(
+	ctx: ExtensionCommandContext,
+	initial: T,
+	signal?: AbortSignal,
+): Promise<T | undefined> {
+	let storage = initial;
+	while (!signal?.aborted) {
+		const settings = await readLocalConfigObject();
+		if (signal?.aborted) return undefined;
+		const connection = settings?.storageConnections[storage.connection];
+		if (!settings || !connection) throw new Error("Storage connection changed; reopen setup.");
+		const identity = setupPublicationIdentity(storage, connection);
+		const occupied = Object.entries(settings.syncSetups).find(
+			([, setup]) =>
+				setupPublicationIdentity(
+					setup.storage,
+					settings.storageConnections[setup.storage.connection],
+				) === identity,
+		);
+		if (!occupied) return storage;
+		const git = connection.type === "git";
+		const message = `${git ? "Git branch" : "Storage location"} is already used by “${safeTerminalText(occupied[0])}”. ${git ? "Use a different branch; pi-sync owns the entire branch." : "Enter a different storage path, or cancel to choose another connection or bucket."}`;
+		ctx.ui.notify(message, "warning");
+		const title = `${git ? "Git branch for the new setup" : "Storage path for the new setup"}\n\n${message}`;
+		const example = git ? "pi-sync/work" : "backups/work";
+		const value =
+			connection.type === "webdav"
+				? await promptTextInput(ctx, title, { example }, signal)
+				: await requiredValueInput(ctx, title, example, signal);
+		if (signal?.aborted || value === undefined) return undefined;
+		try {
+			storage = git
+				? { ...storage, branch: normalizeGitBranch(value) }
+				: { ...storage, path: normalizeStoragePath(value) };
+		} catch (error) {
+			ctx.ui.notify(safeTerminalText(errorMessage(error)), "warning");
+		}
+	}
+	return undefined;
+}
+
+function setupPublicationIdentity(
+	storage: SyncSetupSettings["storage"],
+	connection: StorageConnectionSettings,
+) {
+	// Git publications own a complete branch tree; changing only its directory is not isolation.
+	return effectiveSyncSetupRemoteIdentity(
+		{
+			storage: connection.type === "git" ? { ...storage, path: "./" } : storage,
+			sync: { include: [], automatic: false },
+		},
+		connection,
+	);
+}

package/src/ui/setup/setup-name-ui.ts

@@ -0,0 +1,34 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { validateConfigName } from "../../settings/settings-validation.js";
+import { errorMessage } from "../../sync/sync-errors.js";
+import { safeTerminalText } from "../terminal-text.js";
+
+export async function promptInitialSetupName(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	while (!signal?.aborted) {
+		const hint = "For example: home or work. Leave blank for default.";
+		// Pi styles the whole input title as accent; give only the guidance a muted role.
+		const guidance = ctx.mode === "tui" ? ctx.ui.theme.fg("muted", hint) : hint;
+		// This compact prompt owns its default hint; the general helper would repeat it.
+		const value = await ctx.ui.input(`Sync setup name\n${guidance}`, undefined, { signal });
+		if (signal?.aborted) {
+			throw signal.reason instanceof Error
+				? signal.reason
+				: new DOMException("The operation was aborted", "AbortError");
+		}
+		if (value === undefined) return undefined;
+		const name = value.trim() || "default";
+		try {
+			if (name.includes("<") || name.includes(">")) {
+				throw new Error("Replace example placeholders with your own name.");
+			}
+			validateConfigName(name, "sync setup");
+			return name;
+		} catch (error) {
+			ctx.ui.notify(
+				`This name cannot be used for the sync setup. ${safeTerminalText(errorMessage(error))} Enter another name (for example, default).`,
+				"warning",
+			);
+		}
+	}
+	return undefined;
+}

package/src/ui/setup/setup-prompts.ts

@@ -0,0 +1,92 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { readLocalConfigObject } from "../../settings/settings-store.js";
+import { validateConfigName } from "../../settings/settings-validation.js";
+import { DEFAULT_SYNC_INCLUDE } from "../../sync/sync-policy.js";
+import { safeTerminalText } from "../terminal-text.js";
+import { promptTextInput } from "./text-input.js";
+
+export async function readSetupConnection(name: string, signal?: AbortSignal) {
+	const connection = (await readLocalConfigObject())?.storageConnections[name];
+	signal?.throwIfAborted();
+	if (!connection) throw new Error("Storage connection changed; reopen setup.");
+	return connection;
+}
+
+export const AUTOMATIC_SYNC_DESCRIPTION =
+	"Check the current setup in the background at startup; review changes in /sync before transferring. At shutdown, automatically push selected content only when sessions are included. No startup dialogs.";
+
+export async function chooseSetupContent(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	const choice = await ctx.ui.select(
+		"Choose included content\n\nRecommended: Pi settings, instructions, skills, prompts, themes, and extensions.\nMinimal: settings.json and AGENTS.md.\nReview the exact paths before saving.",
+		["Recommended Pi settings", "Minimal settings", "Cancel"],
+		{ signal },
+	);
+	signal?.throwIfAborted();
+	if (!choice || choice === "Cancel") return undefined;
+	return choice === "Minimal settings" ? ["settings.json", "AGENTS.md"] : [...DEFAULT_SYNC_INCLUDE];
+}
+
+export async function chooseAutomaticSync(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	const choice = await ctx.ui.select(
+		`Automatic sync for this setup\n\n${AUTOMATIC_SYNC_DESCRIPTION}`,
+		["Keep automatic sync off", "Enable automatic sync", "Cancel"],
+		{ signal },
+	);
+	signal?.throwIfAborted();
+	return !choice || choice === "Cancel" ? undefined : choice === "Enable automatic sync";
+}
+
+export async function chooseSessions(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	const choice = await ctx.ui.select(
+		"Session conversations\n\nSessions can contain prompts, tool output, paths, screenshots, and secrets.",
+		["Keep sessions off (recommended)", "Include session conversations", "Cancel"],
+		{ signal },
+	);
+	signal?.throwIfAborted();
+	if (!choice || choice === "Cancel") return undefined;
+	if (choice !== "Include session conversations") return false;
+	const confirmed = await ctx.ui.confirm(
+		"Include session conversations?",
+		"I understand that session JSONL can contain prompts, tool output, paths, screenshots, and secrets.",
+		{ signal },
+	);
+	signal?.throwIfAborted();
+	return confirmed ? true : undefined;
+}
+
+export function includedContentLines(include: readonly string[], sessions = false) {
+	const paths = [...include, ...(sessions && !include.includes("sessions") ? ["sessions"] : [])];
+	return [
+		`Included content: ${paths.length} paths`,
+		...paths.map((item) => `  ${safeTerminalText(item)}`),
+		`Sessions: ${sessions ? "On — privacy warning acknowledged" : "Off"}`,
+	];
+}
+
+export async function promptResourceName(
+	ctx: ExtensionCommandContext,
+	kind: "sync setup" | "storage connection",
+	defaultValue: string,
+	signal?: AbortSignal,
+	literalBrackets = false,
+) {
+	return promptTextInput(
+		ctx,
+		`Name this ${kind}\n\nA local label, such as home or work.`,
+		{
+			defaultValue,
+			rejectPlaceholders: !literalBrackets,
+			validate: async (name) => {
+				validateConfigName(name, kind);
+				const settings = await readLocalConfigObject();
+				signal?.throwIfAborted();
+				const names = kind === "sync setup" ? settings?.syncSetups : settings?.storageConnections;
+				if (names && Object.hasOwn(names, name)) {
+					throw new Error(`A ${kind} with this name already exists. Choose a different name.`);
+				}
+				return name;
+			},
+		},
+		signal,
+	);
+}

package/src/ui/setup/setup-review.ts

@@ -0,0 +1,70 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+
+/** A settings draft is committed only after review; retryable I/O failures retain the same draft. */
+export async function saveReviewedDraft(
+	ctx: ExtensionCommandContext,
+	title: string,
+	lines: readonly string[],
+	label: string,
+	save: (signal: AbortSignal) => Promise<unknown>,
+	signal?: AbortSignal,
+) {
+	let saved = false;
+	let failure: unknown;
+	let failureText: string | undefined;
+	const menu = defineMenu<undefined, "review", "save", ExtensionCommandContext>({
+		start: "review",
+		screens: {
+			review: () => ({
+				kind: "review",
+				title,
+				content: [...(failureText ? [failureText, ""] : []), ...lines].join("\n"),
+				lines: ["Review before saving. Back cancels this draft."],
+				format: { kind: "text" },
+				viewportSize: "adaptive",
+				confirm: { id: "save", label, action: "save" },
+				hint: "back",
+			}),
+		},
+		actions: {
+			save: async ({ signal: actionSignal }) => {
+				try {
+					actionSignal.throwIfAborted();
+					await save(actionSignal);
+					saved = true;
+					return { kind: "close" };
+				} catch (error) {
+					if (actionSignal.aborted) return { kind: "close" };
+					// Do not silently rebase a stale review or overwrite an invalid settings file.
+					// The caller must reopen current settings for those failures.
+					if (!retryableSettingsError(error)) {
+						failure = error;
+						return { kind: "close" };
+					}
+					failureText = `Not saved. ${syncErrorGuidance(error)}\nYour draft is retained. Fix the problem, then save again, or cancel.`;
+					ctx.ui.notify(failureText, "error");
+					return { kind: "stay" };
+				}
+			},
+		},
+	});
+	const result = await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal,
+		isCurrent: () => !signal?.aborted,
+	});
+	if (signal?.aborted) return false;
+	if (failure) throw failure;
+	if (result.kind === "error") throw result.error;
+	return saved;
+}
+
+function retryableSettingsError(error: unknown) {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return (
+		code !== undefined &&
+		["EACCES", "EPERM", "ENOSPC", "EBUSY", "EIO", "EMFILE", "ENFILE", "EROFS"].includes(code)
+	);
+}

package/src/ui/setup/setup-switcher.ts

@@ -0,0 +1,181 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { loadConfig, syncConfigReviewIdentity } from "../../settings/config.js";
+import { loadOnSwitch, readLocalConfigObject } from "../../settings/settings-store.js";
+import type { AnySyncConfig } from "../../settings/settings-types.js";
+import { ownRecord } from "../../settings/settings-validation.js";
+import { useSyncSetup } from "../../sync/setup-switch.js";
+import { errorMessage } from "../../sync/sync-errors.js";
+import { automaticSyncSummary } from "../automatic-sync-summary.js";
+import { type RunRoute, runCancellableOperation } from "../cancellable-operation.js";
+import { dispatchManagerResult } from "../manager-result-dispatcher.js";
+import { backendStorageDescription } from "../manager-state.js";
+import { safeTerminalText } from "../terminal-text.js";
+
+async function selectSetupForSwitch(
+	ctx: ExtensionCommandContext,
+	raw: Record<string, unknown>,
+	targets: Record<string, unknown>,
+	active: string | undefined,
+	signal?: AbortSignal,
+) {
+	let selectedName: string | undefined;
+	const nameById = new Map<string, string>();
+	const profiles = ownRecord(raw.storageConnections);
+	const menu = defineMenu<undefined, "setups", "select", ExtensionCommandContext>({
+		start: "setups",
+		screens: {
+			setups: () => ({
+				kind: "actions",
+				title: "Switch sync setup",
+				lines: [`Current sync setup: ${safeTerminalText(active ?? "none")}`],
+				items: Object.keys(targets)
+					.sort((left, right) => left.localeCompare(right))
+					.map((candidate, index) => {
+						const target = ownRecord(targets[candidate]);
+						const storage = ownRecord(target?.storage);
+						const profileName =
+							typeof storage?.connection === "string" ? storage.connection : undefined;
+						const profile = profileName && profiles ? ownRecord(profiles[profileName]) : undefined;
+						const location = profile
+							? profile.type === "git"
+								? `${String(storage?.branch ?? "missing branch")}:${String(storage?.path ?? "missing path")}`
+								: profile.type === "s3"
+									? `${String(storage?.bucket ?? "missing bucket")}/${String(storage?.path ?? "missing path")}`
+									: String(storage?.path ?? "missing path")
+							: `invalid: missing connection ${profileName ?? "reference"}`;
+						const id = `setup:${index}`;
+						nameById.set(id, candidate);
+						return {
+							id,
+							label: `${safeTerminalText(candidate)}${candidate === active ? " (current)" : ""}`,
+							description: `${safeTerminalText(profileName ?? "unknown")} · ${safeTerminalText(location)}`,
+							action: "select" as const,
+						};
+					}),
+				hint: "close",
+			}),
+		},
+		actions: {
+			select: async ({ itemId }) => {
+				selectedName = nameById.get(itemId);
+				return { kind: "close" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal,
+		isCurrent: () => !signal?.aborted,
+	});
+	return selectedName;
+}
+
+export async function showSetupSwitcher(
+	ctx: ExtensionCommandContext,
+	runRoute: RunRoute,
+	selectedName?: string,
+	signal?: AbortSignal,
+) {
+	const raw = await readLocalConfigObject();
+	if (signal?.aborted) return false;
+	if (raw?.version !== 3) {
+		ctx.ui.notify("Add a second sync setup before switching setups.", "info");
+		return false;
+	}
+	const targets = ownRecord(raw.syncSetups);
+	if (!targets) {
+		ctx.ui.notify("No sync setups are configured.", "warning");
+		return false;
+	}
+	const active = typeof raw.activeSyncSetup === "string" ? raw.activeSyncSetup : undefined;
+	let name = selectedName;
+	if (!name) {
+		name = await selectSetupForSwitch(ctx, raw, targets, active, signal);
+		if (!name) return false;
+	}
+	if (!name || !Object.hasOwn(targets, name)) {
+		ctx.ui.notify(
+			`Sync setup “${safeTerminalText(name ?? "unknown")}” no longer exists.`,
+			"warning",
+		);
+		return false;
+	}
+	if (name === active) {
+		ctx.ui.notify(`Sync setup “${safeTerminalText(name)}” is already current.`, "info");
+		return false;
+	}
+	let config: AnySyncConfig;
+	try {
+		config = await loadConfig(name);
+		if (signal?.aborted) return false;
+	} catch (error) {
+		ctx.ui.notify(
+			`Cannot use sync setup “${safeTerminalText(name)}”: ${safeTerminalText(errorMessage(error))}`,
+			"error",
+		);
+		return false;
+	}
+	const onSwitch = await loadOnSwitch();
+	if (signal?.aborted) return false;
+	const switchEffect =
+		onSwitch === "ask-before-pull"
+			? "After switching, pi-sync will ask whether to review a pull for this setup."
+			: onSwitch === "pull-after-switch"
+				? "After switching, pi-sync will check this setup and show exact changes before applying them."
+				: "After switching, pi-sync will not pull or modify synced files.";
+	const confirmed = await ctx.ui.confirm(
+		"Switch sync setup?",
+		[
+			`From: ${safeTerminalText(active ?? "none")}`,
+			`To: ${safeTerminalText(name)}`,
+			`Storage: ${backendStorageDescription(config)}`,
+			`Included content: ${config.include.length} paths`,
+			`Automatic sync: ${automaticSyncSummary(config.automatic)} · Sessions: ${config.include.includes("sessions") ? "On" : "Off"}`,
+			"",
+			switchEffect,
+		].join("\n"),
+		{ signal },
+	);
+	if (signal?.aborted || !confirmed) return false;
+	try {
+		let pullClosed = false;
+		const result = await useSyncSetup(
+			ctx,
+			name,
+			async (selectedTarget) => {
+				const pullResult = await runCancellableOperation(
+					ctx,
+					`Pulling sync setup “${safeTerminalText(name)}”…`,
+					"pull",
+					runRoute,
+					{
+						commitAware: true,
+						cancelledMessage: null,
+						target: selectedTarget,
+						signal,
+					},
+				);
+				const disposition = await dispatchManagerResult(ctx, pullResult, "pull", runRoute, signal);
+				if (pullResult.kind === "closed" || pullResult.kind.endsWith("required")) {
+					pullClosed = disposition.kind === "close";
+				}
+				if (disposition.appliedRoute === "pull") return "applied";
+				if (pullResult.kind === "completed") return pullResult.outcome;
+				return pullResult.kind === "cancelled" ? "cancelled" : undefined;
+			},
+			onSwitch,
+			signal,
+			syncConfigReviewIdentity(config),
+		);
+		if (pullClosed) return "closed";
+		return result.pullApplied ? "pull-attempted" : "switched";
+	} catch (error) {
+		if (signal?.aborted) return false;
+		ctx.ui.notify(
+			`Sync setup “${safeTerminalText(name)}” was not switched: ${safeTerminalText(errorMessage(error))}`,
+			"error",
+		);
+		return false;
+	}
+}

package/src/ui/setup/setup-wizard.ts

@@ -0,0 +1,39 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { refreshTargetCompletions } from "../../commands/setup-completions.js";
+import { localConfigPath } from "../../settings/config-file.js";
+import { safeTerminalText } from "../terminal-text.js";
+import { showGitSetup } from "./git-ui.js";
+import { showS3Setup } from "./s3-ui.js";
+import { promptInitialSetupName } from "./setup-name-ui.js";
+import { showWebDavSetup } from "./webdav-ui.js";
+
+export async function showSetupWizard(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			`Guided sync setup requires TUI mode for masked credential input. Create version 3 settings in ${safeTerminalText(localConfigPath())}.`,
+			"warning",
+		);
+		return false;
+	}
+	const preset = await ctx.ui.select(
+		"Set up sync\n\nWhere will Pi settings be stored?",
+		["Cloudflare R2", "Other S3-compatible storage", "WebDAV", "Git", "Cancel"],
+		{ signal },
+	);
+	if (signal?.aborted || !preset || preset === "Cancel") return false;
+	const targetName = await promptInitialSetupName(ctx, signal);
+	if (!targetName) return false;
+	if (preset === "WebDAV") {
+		const saved = await showWebDavSetup(ctx, targetName, signal);
+		if (signal?.aborted) return false;
+		if (saved) await refreshTargetCompletions();
+		return saved;
+	}
+	if (preset === "Git") {
+		const saved = await showGitSetup(ctx, targetName, signal);
+		if (signal?.aborted) return false;
+		if (saved) await refreshTargetCompletions();
+		return saved;
+	}
+	return showS3Setup(ctx, preset, targetName, signal);
+}

package/src/ui/setup/text-input.ts

@@ -0,0 +1,78 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { normalizeS3Bucket, requiredString } from "../../settings/settings-validation.js";
+import { errorMessage } from "../../sync/sync-errors.js";
+import { safeTerminalText } from "../terminal-text.js";
+
+export type ValidateInput = (value: string) => string | Promise<string>;
+
+export async function requiredExistingBucket(
+	ctx: ExtensionCommandContext,
+	example: string,
+	signal?: AbortSignal,
+) {
+	return requiredValueInput(
+		ctx,
+		"Existing bucket\n\nThe bucket must already exist; pi-sync will not create it.",
+		example,
+		signal,
+		normalizeS3Bucket,
+	);
+}
+
+export async function requiredInput(
+	ctx: ExtensionCommandContext,
+	title: string,
+	defaultValue: string,
+	signal?: AbortSignal,
+	validate?: ValidateInput,
+) {
+	return promptTextInput(ctx, title, { defaultValue, validate, rejectPlaceholders: true }, signal);
+}
+
+export async function requiredValueInput(
+	ctx: ExtensionCommandContext,
+	title: string,
+	example: string,
+	signal?: AbortSignal,
+	validate?: ValidateInput,
+) {
+	return promptTextInput(ctx, title, { example, validate, rejectPlaceholders: true }, signal);
+}
+
+export async function promptTextInput(
+	ctx: ExtensionCommandContext,
+	title: string,
+	options: {
+		defaultValue?: string;
+		example?: string;
+		validate?: ValidateInput;
+		rejectPlaceholders?: boolean;
+	},
+	signal?: AbortSignal,
+) {
+	// Pi ignores placeholders. Keep defaults/examples visible; only an explicit blank accepts a default.
+	const hint =
+		options.defaultValue !== undefined
+			? `Default: ${safeTerminalText(options.defaultValue)} (leave blank to keep)`
+			: `Example: ${safeTerminalText(options.example ?? "")}\nEnter your own value; this example is not a default.`;
+	while (true) {
+		signal?.throwIfAborted();
+		const value = await ctx.ui.input(`${title}\n\n${hint}`, undefined, { signal });
+		signal?.throwIfAborted();
+		if (value === undefined) return undefined;
+		try {
+			const normalized = value.trim() || options.defaultValue;
+			if (!normalized) throw new Error(`${title.split("\n")[0]} is required.`);
+			if (options.rejectPlaceholders && /[<>]/u.test(normalized)) {
+				throw new Error("Replace example placeholders such as <account-id> with your own value.");
+			}
+			const checked = requiredString(normalized, title.split("\n")[0] ?? "value");
+			const result = options.validate ? await options.validate(checked) : checked;
+			signal?.throwIfAborted();
+			return result;
+		} catch (error) {
+			signal?.throwIfAborted();
+			ctx.ui.notify(`${errorMessage(error)} Enter a corrected value, or cancel.`, "warning");
+		}
+	}
+}