@narumitw/pi-sync 0.49.15 → 0.50.0

package/src/{git-storage.ts → backends/git/git-storage.ts}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { portableSnapshotSelection, snapshotSelectionInclude } from "./sync-policy.js";
-import type { Snapshot, SnapshotSelection } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "../../snapshot/snapshot-types.js";
+import { portableSnapshotSelection, snapshotSelectionInclude } from "../../sync/sync-policy.js";
 
 export const GIT_MANIFEST_VERSION = 2;
 export const MAX_GIT_MANIFEST_BYTES = 1024 * 1024;

package/src/{s3-backend.ts → backends/s3/s3-backend.ts}

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
-import { sessionTokenWarnings } from "./config.js";
-import { encodeKey, posixJoin } from "./paths.js";
-import { S3Client, S3ObjectAlreadyExistsError } from "./s3-client.js";
-import { decodeSnapshot, encodeSnapshot } from "./snapshot-codec.js";
+import { encodeKey, posixJoin } from "../../paths.js";
+import { sessionTokenWarnings } from "../../settings/config.js";
+import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
+import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+import { portableSnapshotSelection } from "../../sync/sync-policy.js";
+import type { LatestPointer, RemoteObject, ResolvedS3Backend } from "../backend-types.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -13,9 +16,8 @@ import {
 	type SyncBackend,
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
-} from "./sync-backend.js";
-import { portableSnapshotSelection } from "./sync-policy.js";
-import type { LatestPointer, RemoteObject, ResolvedS3Backend, Snapshot } from "./types.js";
+} from "../sync-backend.js";
+import { S3Client, S3ObjectAlreadyExistsError } from "./s3-client.js";
 
 const VERSION = 1;
 const POST_COMMIT_TIMEOUT_MS = 30_000;
@@ -189,7 +191,7 @@ export class S3SyncBackend implements SyncBackend {
 
 	async diagnose(signal?: AbortSignal): Promise<BackendDiagnostic[]> {
 		throwIfAborted(signal);
-		return [
+		const diagnostics: BackendDiagnostic[] = [
 			{
 				key: "s3-config",
 				level: "info",
@@ -201,6 +203,39 @@ export class S3SyncBackend implements SyncBackend {
 				message,
 			})),
 		];
+		const deadline = AbortSignal.timeout(10_000);
+		const probeSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+		try {
+			const result = await new S3Client(this.config, probeSignal).diagnoseRead(
+				latestKey(this.config),
+			);
+			throwIfAborted(probeSignal);
+			const messages = {
+				readable:
+					"s3 remote read: HTTP success. Snapshot contents and write access are not tested.",
+				"missing-key":
+					"s3 remote read: no snapshot at this path (NoSuchKey). Write access is not tested; verify the bucket and path before first sync.",
+				"missing-bucket":
+					"s3 remote read: bucket not found (NoSuchBucket). Create the bucket with your provider or edit the setup's bucket name.",
+				"unknown-404":
+					"s3 remote read: HTTP 404; cannot confirm whether the bucket or snapshot is missing. Verify the endpoint, bucket, and path with your provider. Write access is not tested.",
+			};
+			diagnostics.push({
+				key: "s3-read",
+				level: result === "readable" ? "info" : "warning",
+				message: messages[result],
+			});
+		} catch (error) {
+			throwIfAborted(signal);
+			diagnostics.push({
+				key: "s3-read",
+				level: "warning",
+				message: syncErrorGuidance(
+					deadline.aborted ? new Error("S3 diagnostic request timed out.") : error,
+				),
+			});
+		}
+		return diagnostics;
 	}
 
 	private async resolveChecksum(reference: string, signal?: AbortSignal) {
@@ -257,7 +292,7 @@ export function snapshotKey(config: ResolvedS3Backend, id: string) {
 }
 
 export function storageRoot(config: ResolvedS3Backend) {
-	return config.destination.prefix;
+	return config.destination.prefix === "./" ? "" : config.destination.prefix;
 }
 
 export function pointerFor(
@@ -444,6 +479,7 @@ function assertSafeDestination(config: ResolvedS3Backend) {
 		["prefix", config.destination.prefix, true],
 		["namespace", config.destination.namespace, false],
 	] as const) {
+		if (label === "prefix" && value === "./") continue;
 		if (
 			(!allowEmpty && value.length === 0) ||
 			value.includes("\\") ||

package/src/{s3-client.ts → backends/s3/s3-client.ts}

@@ -1,7 +1,7 @@
 import { createHash, createHmac } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
-import { encodeKey, posixJoin } from "./paths.js";
-import type { RemoteObject, ResolvedS3Backend } from "./types.js";
+import { encodeKey, posixJoin } from "../../paths.js";
+import type { RemoteObject, ResolvedS3Backend } from "../backend-types.js";
 
 const MAX_JSON_RESPONSE_BYTES = 1024 * 1024;
 const MAX_SNAPSHOT_RESPONSE_BYTES = 256 * 1024 * 1024;
@@ -32,6 +32,16 @@ export class S3ObjectAlreadyExistsError extends Error {
 	}
 }
 
+export class S3HttpError extends Error {
+	constructor(
+		message: string,
+		readonly status: number,
+	) {
+		super(message);
+		this.name = "S3HttpError";
+	}
+}
+
 export class S3Client {
 	private config: ResolvedS3Backend;
 	private endpoint: URL;
@@ -50,6 +60,28 @@ export class S3Client {
 		this.requestTimeoutMs = requestTimeoutMs;
 	}
 
+	/** Read-only access probe. A bare 404 cannot distinguish a missing key from a missing bucket. */
+	async diagnoseRead(
+		key: string,
+	): Promise<"readable" | "missing-key" | "missing-bucket" | "unknown-404"> {
+		this.signal?.throwIfAborted();
+		const response = await this.request("GET", key);
+		if (response.ok) {
+			await response.body?.cancel();
+			this.signal?.throwIfAborted();
+			return "readable";
+		}
+		const detail = await this.readErrorText(response);
+		this.signal?.throwIfAborted();
+		if (response.status === 404) {
+			const code = /<Code>\s*([A-Za-z]+)\s*<\/Code>/u.exec(detail)?.[1];
+			if (code === "NoSuchBucket") return "missing-bucket";
+			if (code === "NoSuchKey") return "missing-key";
+			return "unknown-404";
+		}
+		throw new S3HttpError(`S3 remote read failed (HTTP ${response.status}).`, response.status);
+	}
+
 	async getJson<T>(key: string): Promise<RemoteObject<T>> {
 		const maxAttempts = 3;
 		let lastError: unknown;
@@ -57,7 +89,10 @@ export class S3Client {
 			const object = await this.request("GET", key);
 			if (object.status === 404) return { missing: true };
 			if (!object.ok) {
-				throw new Error(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`);
+				throw new S3HttpError(
+					`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+					object.status,
+				);
 			}
 			const body = await readBoundedText(object, MAX_JSON_RESPONSE_BYTES, "S3 JSON response");
 			// R2 can intermittently return an empty 200 body (read-after-write
@@ -87,7 +122,10 @@ export class S3Client {
 			const object = await this.request("GET", key);
 			if (object.status === 404) return { missing: true };
 			if (!object.ok) {
-				throw new Error(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`);
+				throw new S3HttpError(
+					`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+					object.status,
+				);
 			}
 			const buffer = await readBoundedBuffer(
 				object,
@@ -130,7 +168,10 @@ export class S3Client {
 			throw new S3ObjectAlreadyExistsError(key);
 		}
 		if (!response.ok) {
-			throw new Error(`S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`);
+			throw new S3HttpError(
+				`S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`,
+				response.status,
+			);
 		}
 	}
 
@@ -173,8 +214,13 @@ export class S3Client {
 			? undefined
 			: this.config.profile.sessionToken;
 		const response = await send(sessionToken);
-		if (!(await this.shouldRetryWithoutSessionToken(response, sessionToken))) return response;
-
+		try {
+			if (!(await this.shouldRetryWithoutSessionToken(response, sessionToken))) return response;
+		} catch (error) {
+			await response.body?.cancel().catch(() => undefined);
+			throw error;
+		}
+		await response.body?.cancel();
 		const retry = await send(undefined);
 		if (retry.ok || retry.status === 404) this.omitSessionTokenAfterRejection = true;
 		return retry;
@@ -246,6 +292,8 @@ async function readBoundedText(response: Response, limit: number, label: string)
 async function readBoundedBuffer(response: Response, limit: number, label: string) {
 	const contentLength = Number(response.headers.get("content-length"));
 	if (Number.isFinite(contentLength) && contentLength > limit) {
+		// Do not await cancellation of a cloned stream before its sibling can be released.
+		void response.body?.cancel().catch(() => undefined);
 		throw new Error(`${label} exceeds the ${limit}-byte limit.`);
 	}
 	if (!response.body) return Buffer.alloc(0);
@@ -258,7 +306,7 @@ async function readBoundedBuffer(response: Response, limit: number, label: strin
 			if (done) break;
 			total += value.byteLength;
 			if (total > limit) {
-				await reader.cancel().catch(() => undefined);
+				void reader.cancel().catch(() => undefined);
 				throw new Error(`${label} exceeds the ${limit}-byte limit.`);
 			}
 			chunks.push(Buffer.from(value));

package/src/{sync-backend.ts → backends/sync-backend.ts}

@@ -1,4 +1,4 @@
-import type { Snapshot, SnapshotSelection } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
 
 export type PublicationCapability =
 	| "read-check-write-verify"

package/src/{webdav-backend.ts → backends/webdav/webdav-backend.ts}

@@ -1,5 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
-import { decodeSnapshot, encodeSnapshot } from "./snapshot-codec.js";
+import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
+import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+import { portableSnapshotSelection } from "../../sync/sync-policy.js";
+import type { LatestPointer, RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -10,9 +14,7 @@ import {
 	type SyncBackend,
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
-} from "./sync-backend.js";
-import { portableSnapshotSelection } from "./sync-policy.js";
-import type { LatestPointer, RemoteObject, ResolvedWebDavBackend, Snapshot } from "./types.js";
+} from "../sync-backend.js";
 import { WebDavClient, WebDavHttpError, WebDavPreconditionError } from "./webdav-client.js";
 
 const VERSION = 1;
@@ -198,6 +200,12 @@ export class WebDavSyncBackend implements SyncBackend {
 				level: "info",
 				message: `webdav URL/TLS/auth: configured (${webDavStorageLocation(this.config)})`,
 			},
+			{
+				key: "webdav-scope",
+				level: "info",
+				message:
+					"webdav check scope: temporary write/delete probe; repair the active snapshot's history entry if missing. No local content is applied.",
+			},
 		];
 		try {
 			await this.runCapabilityProbe(signal);
@@ -217,7 +225,7 @@ export class WebDavSyncBackend implements SyncBackend {
 			diagnostics.push({
 				key: "webdav-probe",
 				level: "error",
-				message: `webdav publication is read-only until diagnostics pass: ${errorMessage(error)}`,
+				message: `webdav publication is read-only until diagnostics pass: ${syncErrorGuidance(error)}`,
 			});
 			return diagnostics;
 		}
@@ -232,7 +240,7 @@ export class WebDavSyncBackend implements SyncBackend {
 			diagnostics.push({
 				key: "webdav-history",
 				level: "error",
-				message: `webdav history repair failed: ${errorMessage(error)}`,
+				message: `webdav history repair failed: ${syncErrorGuidance(error)}`,
 			});
 		}
 		return diagnostics;
@@ -250,7 +258,7 @@ export class WebDavSyncBackend implements SyncBackend {
 
 	private async runCapabilityProbe(signal?: AbortSignal) {
 		throwIfAborted(signal);
-		const probeCollection = `${rootPath(this.config)}/.pi-sync-probes/${randomUUID()}`;
+		const probeCollection = joinRemote(rootPath(this.config), ".pi-sync-probes", randomUUID());
 		const probe = `${probeCollection}/conditional.txt`;
 		const client = new WebDavClient(this.config, signal);
 		let created = false;
@@ -382,7 +390,7 @@ export class WebDavSyncBackend implements SyncBackend {
 }
 
 export function rootPath(config: ResolvedWebDavBackend) {
-	return config.destination.path;
+	return config.destination.path === "./" ? "" : config.destination.path;
 }
 
 export function latestPath(config: ResolvedWebDavBackend) {
@@ -410,7 +418,7 @@ export function webDavBackendIdentity(config: ResolvedWebDavBackend) {
 
 function webDavStorageLocation(config: ResolvedWebDavBackend) {
 	const url = new URL(secretFreeUrl(config.profile.url));
-	return `${url.host} · ${rootPath(config)}`;
+	return `${url.host} · ${config.destination.path}`;
 }
 
 function pointerFor(
@@ -586,7 +594,11 @@ function assertSafeDestination(config: ResolvedWebDavBackend) {
 	const url = new URL(config.profile.url);
 	if (url.username || url.password || url.search || url.hash)
 		throw new Error("Invalid WebDAV URL.");
-	for (const value of [config.destination.path, config.destination.namespace]) {
+	for (const [label, value] of [
+		["path", config.destination.path],
+		["namespace", config.destination.namespace],
+	]) {
+		if (label === "path" && value === "./") continue;
 		if (
 			!value ||
 			value.includes("\\") ||

package/src/{webdav-client.ts → backends/webdav/webdav-client.ts}

@@ -1,5 +1,5 @@
 import { XMLParser } from "fast-xml-parser";
-import type { RemoteObject, ResolvedWebDavBackend } from "./types.js";
+import type { RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
 
 const JSON_LIMIT = 1024 * 1024;
 const ERROR_LIMIT = 64 * 1024;

package/src/{webdav-config.ts → backends/webdav/webdav-config.ts}

@@ -41,6 +41,7 @@ export function normalizeWebDavUrl(value: string | undefined) {
 }
 
 export function normalizeWebDavPath(value: string | undefined) {
+	if (value?.trim() === "." || value?.trim() === "./") return "./";
 	const normalized = trimSlashes(normalizeOptionalString(value) ?? DEFAULT_PATH);
 	if (
 		!normalized ||

package/src/commands/command-execution.ts

@@ -0,0 +1,330 @@
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig, sessionTokenWarnings, syncSessionsWarnings } from "../settings/config.js";
+import {
+	activeLocalConfigPath,
+	createLocalConfigDocument,
+	localConfigPath,
+} from "../settings/config-file.js";
+import { localConfigTemplate, readLocalConfigObject } from "../settings/settings-store.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { unlock, withLock } from "../state/lock.js";
+import {
+	migrateLegacyStateDirectory,
+	stateDirectoryMigrationNotice,
+} from "../state/state-directory.js";
+import { throwIfAborted } from "../sync/signals.js";
+import { syncErrorGuidance } from "../sync/sync-error-guidance.js";
+import { isSyncDecisionRequiredError, SetupPullRequiresUiError } from "../sync/sync-errors.js";
+import type { SyncLoaders } from "../sync/sync-loaders.js";
+import { RemoteSelectionMismatchError } from "../sync/sync-policy.js";
+import { automaticSyncSummary } from "../ui/automatic-sync-summary.js";
+import type { RunRouteResult } from "../ui/cancellable-operation.js";
+import {
+	parseOptions,
+	resolveSyncCommand,
+	splitArgs,
+	usage,
+	validateCommandOptions,
+} from "./command.js";
+import type { CommandOptions } from "./command-types.js";
+
+const STATUS_KEY = "sync";
+
+export async function executeRecoveryCommand(
+	rawArgs: string,
+	ctx: ExtensionContext,
+	signal: AbortSignal | undefined,
+	loaders: SyncLoaders,
+	onCommit?: () => void,
+	setup?: string,
+): Promise<RunRouteResult> {
+	try {
+		const [subcommand, ...rest] = splitArgs(rawArgs);
+		if (subcommand !== "sync" && subcommand !== "pull" && subcommand !== "push") {
+			throw new Error(`Unsupported sync recovery route: ${subcommand ?? "missing"}`);
+		}
+		const options = parseOptions(rest);
+		if (setup !== undefined) options.setup = setup;
+		if (signal) options.signal = signal;
+		if (onCommit) options.onCommit = onCommit;
+		options.reload = false;
+		options.auto = false;
+		validateCommandOptions(subcommand, options);
+		const operations = await loaders.operations();
+		throwIfAborted(options.signal);
+		if (subcommand === "push") {
+			const outcome = await withLock("push", () => operations.push(ctx, options));
+			return { kind: "completed", ...(outcome ? { outcome } : {}) };
+		}
+		if (subcommand === "pull") {
+			const outcome = await withLock("pull", () => operations.pull(ctx, options));
+			return { kind: "completed", ...(outcome ? { outcome } : {}) };
+		}
+		await withLock("sync", () => operations.syncBoth(ctx, options));
+		return { kind: "completed" };
+	} catch (error) {
+		if (signal?.aborted) return { kind: "failed" };
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		if (error instanceof RemoteSelectionMismatchError) {
+			return { kind: "remote-selection-required", decision: error.decision };
+		}
+		if (isSyncDecisionRequiredError(error)) {
+			return { kind: "decision-required", decision: error.decision };
+		}
+		ctx.ui.notify(syncErrorGuidance(error), "error");
+		return { kind: "failed" };
+	}
+}
+
+export async function executeCommand(
+	rawArgs: string,
+	ctx: ExtensionCommandContext,
+	signal: AbortSignal | undefined,
+	loaders: SyncLoaders,
+	onCommit?: () => void,
+	setup?: string,
+): Promise<RunRouteResult> {
+	try {
+		const command = await resolveSyncCommand(rawArgs, ctx);
+		if (signal?.aborted || !command) return { kind: "completed" };
+		const { subcommand, rest } = command;
+		const options = parseOptions(rest);
+		if (setup !== undefined) options.setup = setup;
+		if (signal) options.signal = signal;
+		if (onCommit) options.onCommit = onCommit;
+		validateCommandOptions(subcommand, options);
+
+		switch (subcommand) {
+			case "help":
+				ctx.ui.notify(usage(), "info");
+				return { kind: "completed" };
+			case "use": {
+				const { useSyncSetup } = await loaders.setupSwitch();
+				throwIfAborted(options.signal);
+				await useSyncSetup(
+					ctx,
+					options.args[0] ?? "",
+					async (selectedSetup) => {
+						const operations = await loaders.operations();
+						throwIfAborted(options.signal);
+						return withLock("pull", () =>
+							operations.pull(ctx, { ...options, setup: selectedSetup }),
+						);
+					},
+					undefined,
+					options.signal,
+				);
+				return { kind: "completed" };
+			}
+			case "init":
+				await initConfig(ctx, signal);
+				return { kind: "completed" };
+			case "config":
+				await showConfig(ctx, options);
+				return { kind: "completed" };
+			case "files": {
+				const { showFileSelection } = await import("../ui/file-selection.js");
+				throwIfAborted(options.signal);
+				await showFileSelection(ctx, options.setup, options.signal);
+				return { kind: "completed" };
+			}
+			case "status": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await operations.status(ctx, options);
+				return { kind: "completed" };
+			}
+			case "diff": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await operations.diff(ctx, options);
+				return { kind: "completed" };
+			}
+			case "doctor": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await operations.doctor(ctx, options);
+				return { kind: "completed" };
+			}
+			case "push": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				const outcome = await withLock("push", () => operations.push(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
+			case "pull": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				const outcome = await withLock("pull", () => operations.pull(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
+			case "sync": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await withLock("sync", () => operations.syncBoth(ctx, options));
+				return { kind: "completed" };
+			}
+			case "history": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await operations.history(ctx, options);
+				return { kind: "completed" };
+			}
+			case "rollback": {
+				const operations = await loaders.operations();
+				throwIfAborted(options.signal);
+				await withLock("rollback", () => operations.rollback(ctx, options));
+				return { kind: "completed" };
+			}
+			case "migrate-state":
+				await migrateStateDirectory(ctx, options);
+				return { kind: "completed" };
+			case "unlock":
+				await unlock(ctx, options);
+				return { kind: "completed" };
+			default:
+				ctx.ui.notify(`Unknown /sync command: ${subcommand}\n\n${usage()}`, "warning");
+				return { kind: "failed" };
+		}
+	} catch (error) {
+		if (signal?.aborted) return { kind: "failed" };
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		if (error instanceof SetupPullRequiresUiError) throw error;
+		if (error instanceof RemoteSelectionMismatchError) {
+			return { kind: "remote-selection-required", decision: error.decision };
+		}
+		if (isSyncDecisionRequiredError(error)) {
+			return { kind: "decision-required", decision: error.decision };
+		}
+		ctx.ui.notify(syncErrorGuidance(error), "error");
+		return { kind: "failed" };
+	}
+}
+
+async function migrateStateDirectory(ctx: ExtensionCommandContext, options: CommandOptions) {
+	const notice = stateDirectoryMigrationNotice();
+	if (!notice) {
+		ctx.ui.notify("pi-sync already uses the canonical pi-sync/ state directory.", "info");
+		return;
+	}
+	if (
+		!options.yes &&
+		!(await ctx.ui.confirm(
+			"Migrate pi-sync state directory",
+			"Confirm that every other Pi process is closed. pi-sync will atomically rename .pisync/ to pi-sync/ without merging or deleting either root.",
+			{ signal: options.signal },
+		))
+	) {
+		ctx.ui.notify("pi-sync state migration cancelled.", "info");
+		return;
+	}
+	throwIfAborted(options.signal);
+	const result = await migrateLegacyStateDirectory();
+	throwIfAborted(options.signal);
+	if (result.status === "ready") {
+		ctx.ui.notify("pi-sync already uses the canonical pi-sync/ state directory.", "info");
+		return;
+	}
+	ctx.ui.notify(result.message, result.status === "migrated" ? "info" : "warning");
+}
+
+async function initConfig(ctx: ExtensionCommandContext, signal?: AbortSignal) {
+	const configPath = localConfigPath();
+	if (await readLocalConfigObject()) {
+		ctx.ui.notify(`Config already exists: ${await activeLocalConfigPath()}`, "info");
+		return;
+	}
+
+	if (ctx.mode === "tui") {
+		const { showSetupWizard } = await import("../ui/setup/setup-wizard.js");
+		throwIfAborted(signal);
+		await showSetupWizard(ctx, signal);
+		return;
+	}
+	await createLocalConfigDocument(localConfigTemplate());
+	ctx.ui.notify(
+		`Created ${configPath}. Add a storage connection and sync setup before syncing.`,
+		"info",
+	);
+}
+
+async function showConfig(ctx: ExtensionCommandContext, options: CommandOptions) {
+	const config = await loadConfig(options.setup);
+	const warnings = [
+		...(config.backend.type === "s3" ? sessionTokenWarnings(config.backend.profile) : []),
+		...syncSessionsWarnings(config),
+	];
+	const storageLines = configStorageLines(config);
+	ctx.ui.notify(
+		[
+			"pi-sync config:",
+			`sync setup: ${config.setupName}`,
+			`storage connection: ${config.connectionName}`,
+			...storageLines,
+			`storage path: ${config.storagePath}`,
+			`automatic sync: ${automaticSyncSummary(config.automatic)}`,
+			`included content: ${config.include.join(", ") || "none"}`,
+			`sessions: ${config.include.includes("sessions") ? "included" : "not included"}`,
+			`settings file: ${localConfigPath()}`,
+			...warnings,
+		].join("\n"),
+		warnings.length > 0 ? "warning" : "info",
+	);
+}
+
+function configStorageLines(config: AnySyncConfig) {
+	switch (config.backend.type) {
+		case "git":
+			return [
+				"kind: git",
+				`remote: ${displayGitRemote(config.backend.profile.remote)}`,
+				"authentication: existing Git/SSH credentials (not stored)",
+				`branch: ${config.backend.destination.branch}`,
+			];
+		case "webdav":
+			return [
+				"kind: webdav",
+				`url: ${displayWebDavUrl(config.backend.profile.url, config.backend.profile.username)}`,
+				"username: configured (value hidden)",
+				"password: configured",
+			];
+		case "s3":
+			return [
+				"kind: s3",
+				`endpoint: ${config.backend.profile.endpoint}`,
+				`bucket: ${config.backend.destination.bucket}`,
+				`region: ${config.backend.profile.region}`,
+				"access key id: configured",
+				"secret access key: configured",
+				`session token: ${config.backend.profile.sessionToken ? "configured" : "not configured"}`,
+			];
+	}
+}
+
+function displayGitRemote(value: string | undefined) {
+	if (!value) return "missing";
+	try {
+		const url = new URL(value);
+		url.username = "";
+		url.password = "";
+		url.search = "";
+		url.hash = "";
+		return url.toString();
+	} catch {
+		return value.replace(/^(?:[^@\s]+@)?(?<host>[^:]+):.+$/u, "$<host>:…");
+	}
+}
+
+function displayWebDavUrl(value: string | undefined, username: string | undefined) {
+	if (!value) return "missing";
+	try {
+		const url = new URL(value);
+		url.username = "";
+		url.password = "";
+		url.search = "";
+		url.hash = "";
+		return username ? `${url.origin}/…` : `${url.origin}${url.pathname}`;
+	} catch {
+		return "invalid (value hidden)";
+	}
+}