@narumitw/pi-sync 0.49.14 → 0.50.0

package/src/sync.ts

@@ -1,12 +1,12 @@
-export { completeSyncArguments, parseOptions, splitArgs } from "./command.js";
+export { completeSyncArguments, parseOptions, splitArgs } from "./commands/command.js";
+export { encodeKey, posixJoin, safeJoin, safeName } from "./paths.js";
 export {
-	isCloudflareR2Endpoint,
 	isEnabled,
 	isExplicitlyEnabled,
 	loadConfig,
 	sessionTokenWarnings,
-} from "./config.js";
-export { encodeKey, posixJoin, safeJoin, safeName } from "./paths.js";
+} from "./settings/config.js";
+export { isCloudflareR2Endpoint } from "./settings/settings-validation.js";
 export {
 	canonicalSnapshotPathForConfig,
 	collectFiles,
@@ -19,14 +19,13 @@ export {
 	scanSnapshot,
 	sessionSnapshotPathFromAbsolute,
 	snapshotWithoutSessions,
-} from "./snapshot.js";
+} from "./snapshot/snapshot.js";
 export {
 	addTopLevelCaseVariantDeletes,
 	appliedFileHashMap,
 	preflightSnapshotApply,
 	protectSnapshotApplyPlan,
-} from "./snapshot-apply.js";
-export { default, type SyncDependencies } from "./sync-extension.js";
+} from "./snapshot/snapshot-apply.js";
 export {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,
@@ -35,4 +34,5 @@ export {
 	settingsHashesMatchState,
 	settingsHashMap,
 	settingsHashMapFromState,
-} from "./sync-state.js";
+} from "./sync/sync-state.js";
+export { default, type SyncDependencies } from "./sync-extension.js";

package/src/types.ts

@@ -1,284 +1,47 @@
-export type StorageConnectionType = "s3" | "git" | "webdav";
-export type OnSwitchAction = "ask-before-pull" | "pull-after-switch" | "switch-only";
-
-export interface S3CredentialsSettings {
-	accessKeyId: string;
-	secretAccessKey: string;
-	sessionToken?: string;
-	[key: string]: unknown;
-}
-
-export interface WebDavCredentialsSettings {
-	username: string;
-	password: string;
-	[key: string]: unknown;
-}
-
-export interface S3StorageConnectionSettings {
-	type: "s3";
-	endpoint: string;
-	region: string;
-	credentials: S3CredentialsSettings;
-	remote?: never;
-	url?: never;
-	[key: string]: unknown;
-}
-
-export interface GitStorageConnectionSettings {
-	type: "git";
-	remote: string;
-	endpoint?: never;
-	region?: never;
-	credentials?: never;
-	url?: never;
-	[key: string]: unknown;
-}
-
-export interface WebDavStorageConnectionSettings {
-	type: "webdav";
-	url: string;
-	credentials: WebDavCredentialsSettings;
-	endpoint?: never;
-	region?: never;
-	remote?: never;
-	[key: string]: unknown;
-}
-
-export type StorageConnectionSettings =
-	| S3StorageConnectionSettings
-	| GitStorageConnectionSettings
-	| WebDavStorageConnectionSettings;
-
-export interface CommonSyncSetupStorageSettings {
-	connection: string;
-	path: string;
-	[key: string]: unknown;
-}
-
-export interface S3SyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
-	bucket: string;
-	branch?: never;
-}
-
-export interface GitSyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
-	branch: string;
-	bucket?: never;
-}
-
-export interface WebDavSyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
-	bucket?: never;
-	branch?: never;
-}
-
-export type SyncSetupStorageSettings =
-	| S3SyncSetupStorageSettings
-	| GitSyncSetupStorageSettings
-	| WebDavSyncSetupStorageSettings;
-
-export interface SyncPolicySettings {
-	include: string[];
-	automatic: boolean;
-	[key: string]: unknown;
-}
-
-export interface SyncSetupSettings {
-	storage: SyncSetupStorageSettings;
-	sync: SyncPolicySettings;
-	[key: string]: unknown;
-}
-
-export interface PiSyncSettingsV3 {
-	version: 3;
-	activeSyncSetup?: string;
-	onSwitch: OnSwitchAction;
-	storageConnections: Record<string, StorageConnectionSettings>;
-	syncSetups: Record<string, SyncSetupSettings>;
-	[key: string]: unknown;
-}
-
-/** Backend-only resolved S3 connection fields. */
-export interface ResolvedS3StorageProfile {
-	kind: "r2" | "s3-compatible";
-	endpoint: string;
-	region: string;
-	accessKeyId: string;
-	secretAccessKey: string;
-	sessionToken?: string;
-}
-
-/** Backend-only coordinates. `prefix` is the complete reviewed v3 storage path. */
-export interface ResolvedS3Destination {
-	bucket: string;
-	prefix: string;
-	/** Snapshot/wire identity; never derived from the local setup name. */
-	namespace: string;
-}
-
-export interface ResolvedS3Backend {
-	type: "s3";
-	profile: ResolvedS3StorageProfile;
-	destination: ResolvedS3Destination;
-}
-
-export interface ResolvedWebDavStorageProfile {
-	kind: "webdav";
-	url: string;
-	username: string;
-	password: string;
-}
-
-/** Backend-only coordinates. `path` is the complete reviewed v3 storage path. */
-export interface ResolvedWebDavDestination {
-	path: string;
-	namespace: string;
-}
-
-export interface ResolvedWebDavBackend {
-	type: "webdav";
-	profile: ResolvedWebDavStorageProfile;
-	destination: ResolvedWebDavDestination;
-}
-
-export interface ResolvedGitStorageProfile {
-	kind: "git";
-	remote: string;
-}
-
-/** Backend-only coordinates. `directory` is the complete reviewed v3 storage path. */
-export interface ResolvedGitDestination {
-	branch: string;
-	directory: string;
-	namespace: string;
-}
-
-export interface ResolvedGitBackend {
-	type: "git";
-	profile: ResolvedGitStorageProfile;
-	destination: ResolvedGitDestination;
-}
-
-export type ResolvedSyncBackend = ResolvedS3Backend | ResolvedWebDavBackend | ResolvedGitBackend;
-
-export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Backend> {
-	setupName: string;
-	connectionName: string;
-	storagePath: string;
-	/** Snapshot/wire identity retained behind the settings normalization boundary. */
-	snapshotIdentity: string;
-	include: string[];
-	automatic: boolean;
-	onSwitch: OnSwitchAction;
-	backend: Backend;
-}
-
-export type AnySyncConfig = SyncConfig<ResolvedSyncBackend>;
-export type CommonSyncConfig = Omit<AnySyncConfig, "backend">;
-
-/** UI projection over a fully validated v3 setup; it is never persisted directly. */
-export interface PartialConfig {
-	setupName: string;
-	connectionName: string;
-	storageKind: StorageConnectionType;
-	storagePath: string;
-	include: string[];
-	automatic: boolean;
-	onSwitch: OnSwitchAction;
-	bucket?: string;
-	branch?: string;
-}
-
-export interface SnapshotFile {
-	path: string;
-	contentBase64: string;
-	sha256: string;
-}
-
-export interface SnapshotSelection {
-	version: 1;
-	include: string[];
-}
-
-export interface Snapshot {
-	version: number;
-	id: string;
-	createdAt: string;
-	machine: string;
-	/** Backend-scoped remote identity retained in the snapshot wire format. */
-	profile: string;
-	syncSessions?: boolean;
-	/** Portable, credential-free included-content intent. Absent on legacy snapshots. */
-	selection?: SnapshotSelection;
-	files: SnapshotFile[];
-}
-
-export interface LatestPointer {
-	version: number;
-	profile: string;
-	snapshot: string;
-	sha256: string;
-	createdAt: string;
-	machine: string;
-	syncSessions?: boolean;
-	/** Lightweight projection; the immutable snapshot remains authoritative. */
-	selection?: SnapshotSelection;
-}
-
-export interface RemoteObject<T> {
-	value?: T;
-	etag?: string;
-	missing: boolean;
-}
-
-export interface SyncState {
-	version: number;
-	profile: string;
-	lastAppliedSnapshot?: string;
-	lastRemoteRevision?: string;
-	lastRemoteEtag?: string;
-	lastFileHashes: Record<string, string>;
-	include?: string[];
-	/** Legacy state fields are read only so v3 can detect and replace stale policy state. */
-	syncFiles?: string[];
-	syncSessions?: boolean;
-	extraFiles?: string[];
-}
-
-export interface LockFile {
-	id: string;
-	pid: number;
-	command: string;
-	startedAt: string;
-}
-
-export interface CommandOptions {
-	yes: boolean;
-	force: boolean;
-	stale: boolean;
-	silent: boolean;
-	reload: boolean;
-	auto: boolean;
-	setup?: string;
-	signal?: AbortSignal;
-	onCommit?: () => void;
-	args: string[];
-}
-
-export interface CommandArgumentCompletion {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-export interface SnapshotOptions {
-	include?: string[];
-	sessionDir?: string;
-	/** Temporary internal projections while snapshot storage remains wire-compatible. */
-	syncFiles?: string[];
-	syncSessions?: boolean;
-	extraFiles?: string[];
-}
-
-export interface SnapshotApplyPlan {
-	writes: Array<{ target: string; content: Buffer }>;
-	deletes: string[];
-}
+// Compatibility type surface; implementation modules import from the owning domain.
+
+export type {
+	LatestPointer,
+	RemoteObject,
+	ResolvedGitBackend,
+	ResolvedGitDestination,
+	ResolvedGitStorageProfile,
+	ResolvedS3Backend,
+	ResolvedS3Destination,
+	ResolvedS3StorageProfile,
+	ResolvedSyncBackend,
+	ResolvedWebDavBackend,
+	ResolvedWebDavDestination,
+	ResolvedWebDavStorageProfile,
+} from "./backends/backend-types.js";
+export type { CommandArgumentCompletion, CommandOptions } from "./commands/command-types.js";
+export type {
+	AnySyncConfig,
+	CommonSyncConfig,
+	CommonSyncSetupStorageSettings,
+	GitStorageConnectionSettings,
+	GitSyncSetupStorageSettings,
+	OnSwitchAction,
+	PartialConfig,
+	PiSyncSettingsV3,
+	S3CredentialsSettings,
+	S3StorageConnectionSettings,
+	S3SyncSetupStorageSettings,
+	StorageConnectionSettings,
+	StorageConnectionType,
+	SyncConfig,
+	SyncPolicySettings,
+	SyncSetupSettings,
+	SyncSetupStorageSettings,
+	WebDavCredentialsSettings,
+	WebDavStorageConnectionSettings,
+	WebDavSyncSetupStorageSettings,
+} from "./settings/settings-types.js";
+export type {
+	Snapshot,
+	SnapshotApplyPlan,
+	SnapshotFile,
+	SnapshotOptions,
+	SnapshotSelection,
+} from "./snapshot/snapshot-types.js";
+export type { LockFile, SyncState } from "./state/state-types.js";

package/src/ui/automatic-sync-summary.ts

@@ -0,0 +1,6 @@
+/** Keep the setting's automatic transfer scope visible in every setup summary. */
+export function automaticSyncSummary(enabled: boolean) {
+	return enabled
+		? "On (startup check; shutdown pushes selected content if sessions included)"
+		: "Off";
+}

package/src/{cancellable-operation.ts → ui/cancellable-operation.ts}

@@ -5,10 +5,10 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { runCustomInteraction } from "@narumitw/pi-tui-kit";
-import { safeTerminalText } from "./manager-helpers.js";
-import type { SetupPullOutcome } from "./setup-switch.js";
-import type { SyncDecision } from "./sync-decision.js";
-import type { RemoteSelectionDecision } from "./sync-policy.js";
+import type { SetupPullOutcome } from "../sync/setup-switch.js";
+import type { SyncDecision } from "../sync/sync-decision.js";
+import type { RemoteSelectionDecision } from "../sync/sync-policy.js";
+import { safeTerminalText } from "./terminal-text.js";
 
 export type RunRouteResult =
 	| { kind: "completed"; outcome?: SetupPullOutcome }

package/src/{file-selection.ts → ui/file-selection.ts}

@@ -1,14 +1,16 @@
 import fs from "node:fs/promises";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
-import { agentDir, loadConfig, localConfigPath } from "./config.js";
-import { updateSyncSetup } from "./settings-management.js";
+import { loadConfig } from "../settings/config.js";
+import { localConfigPath } from "../settings/config-file.js";
+import { updateSyncSetup } from "../settings/settings-management.js";
+import { agentDir } from "../snapshot/session-paths.js";
 import {
 	BUILT_IN_SYNC_ROOTS,
 	isSafeCustomIncludePath,
 	normalizeSyncInclude,
 	syncIncludeSelection,
-} from "./sync-policy.js";
+} from "../sync/sync-policy.js";
 
 const BUILT_IN_PREFIX = "builtin:";
 const CUSTOM_PREFIX = "custom:";

package/src/{manager-attention.ts → ui/manager-attention.ts}

@@ -1,11 +1,14 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { ActionMenuItem } from "@narumitw/pi-tui-kit";
+import type { StartupObservation } from "../sync/sync-inspection.js";
 import type { RunRoute } from "./cancellable-operation.js";
 import { dispatchManagerResult } from "./manager-result-dispatcher.js";
 import type { ManagerDescription } from "./manager-state.js";
 import type { SyncAttentionState } from "./sync-attention.js";
 
 export interface SyncManagerAttentionOptions {
+	getObservation?: () => StartupObservation | undefined;
+	onObservationInvalidated?: () => void;
 	getAttention?: () => SyncAttentionState | undefined;
 	onSelectionResolved?: (expected: SyncAttentionState) => void;
 }
@@ -13,7 +16,8 @@ export interface SyncManagerAttentionOptions {
 export function attentionMainMenuItems(
 	manager: ManagerDescription,
 ): ActionMenuItem<"main" | "more" | "recovery", "review-attention">[] {
-	if (!manager.attention) return [];
+	if (!manager.attention && manager.observation?.inspection.selectionState?.kind !== "different")
+		return [];
 	const disabled = manager.attentionReviewDisabled === true;
 	return [
 		{

package/src/{manager-recovery.ts → ui/manager-recovery.ts}

@@ -1,9 +1,13 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { runConfirmation } from "@narumitw/pi-tui-kit";
+import {
+	inspectOperationAvailability,
+	operationCanRecover,
+} from "../state/operation-availability.js";
+import { errorMessage } from "../sync/sync-errors.js";
 import type { RunRoute } from "./cancellable-operation.js";
-import { errorMessage, safeTerminalText } from "./manager-helpers.js";
 import type { ManagerDescription } from "./manager-state.js";
-import { inspectOperationAvailability, operationCanRecover } from "./operation-availability.js";
+import { safeTerminalText } from "./terminal-text.js";
 
 export type RecoveryDisposition = "restored" | "stay" | "close";
 

package/src/{manager-state.ts → ui/manager-state.ts}

@@ -1,22 +1,28 @@
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import {
-	activeLocalConfigPath,
-	isCloudflareR2Endpoint,
-	loadConfig,
-	readLocalConfigObject,
-	readStateForConfig,
-} from "./config.js";
-import { errorMessage, ownRecord, safeTerminalText } from "./manager-helpers.js";
+import { loadConfig } from "../settings/config.js";
+import { activeLocalConfigPath } from "../settings/config-file.js";
+import { readLocalConfigObject } from "../settings/settings-store.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { isCloudflareR2Endpoint, ownRecord } from "../settings/settings-validation.js";
 import {
 	inspectOperationAvailability,
 	type OperationAvailability,
 	operationBlocksChanges,
 	operationCanRecover,
-} from "./operation-availability.js";
-import { type SyncAttentionState, syncAttentionMatchesConfig } from "./sync-attention.js";
-import { compareSyncInclude, syncIncludeSelection } from "./sync-policy.js";
+} from "../state/operation-availability.js";
+import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import { errorMessage } from "../sync/sync-errors.js";
+import type { StartupObservation } from "../sync/sync-inspection.js";
+import { compareSyncInclude, syncIncludeSelection } from "../sync/sync-policy.js";
+import { automaticSyncSummary } from "./automatic-sync-summary.js";
+import {
+	observationMatchesConfig,
+	observationSummary,
+	type SyncAttentionState,
+	syncAttentionMatchesConfig,
+} from "./sync-attention.js";
 import { countValidSyncSetups } from "./sync-setups-ui.js";
-import type { AnySyncConfig } from "./types.js";
+import { safeTerminalText } from "./terminal-text.js";
 
 export const MAIN_MENU_ACTIONS = [
 	"Sync now (recommended)",
@@ -31,6 +37,7 @@ export interface ManagerDescription {
 	actions: string[];
 	operation?: OperationAvailability;
 	attention?: SyncAttentionState;
+	observation?: StartupObservation;
 	attentionBlocksSync?: boolean;
 	attentionReviewDisabled?: boolean;
 }
@@ -39,6 +46,7 @@ export async function describeManagerState(
 	signal?: AbortSignal,
 	attention?: SyncAttentionState,
 	inspectOperation: () => Promise<OperationAvailability> = inspectOperationAvailability,
+	observation?: StartupObservation,
 ): Promise<ManagerDescription> {
 	let raw: Record<string, unknown> | undefined;
 	try {
@@ -105,6 +113,13 @@ export async function describeManagerState(
 		const syncState = changesBlocked
 			? undefined
 			: await readStateForConfig(config).catch(() => undefined);
+		const currentObservation =
+			observation &&
+			observationMatchesConfig(observation, config) &&
+			syncState &&
+			syncStateFingerprint(syncState) === observation.inspection.stateIdentity
+				? observation
+				: undefined;
 		const lastAppliedSnapshot = changesBlocked
 			? "Unavailable while operations are locked"
 			: syncState?.lastAppliedSnapshot
@@ -122,7 +137,7 @@ export async function describeManagerState(
 			`Current sync setup: ${safeTerminalText(config.setupName)}`,
 			`Storage: ${backendStorageDescription(config)}`,
 			`Included: ${selection.builtIns.length} built-in group${selection.builtIns.length === 1 ? "" : "s"} · ${selection.custom.length} extra path${selection.custom.length === 1 ? "" : "s"} · Sessions ${selection.sessions ? "on" : "off"}`,
-			`Automatic sync: ${config.automatic ? "On" : "Off"}`,
+			`Automatic sync: ${automaticSyncSummary(config.automatic)}`,
 			`Last applied: ${lastAppliedSnapshot}`,
 			...(currentAttention
 				? [
@@ -135,7 +150,12 @@ export async function describeManagerState(
 							: `Remote-only paths: ${attentionComparison?.remoteOnly.length ?? 0} · Device-only paths: ${attentionComparison?.localOnly.length ?? 0}`,
 						"Nothing has been changed.",
 					]
-				: ["Remote status: Not checked"]),
+				: currentObservation
+					? [
+							`Startup check (${safeTerminalText(currentObservation.checkedAt)}): ${observationSummary(currentObservation)}`,
+							"Check-time observation only; synchronization rechecks current content.",
+						]
+					: ["Remote status: Not checked"]),
 			...(noSyncedContent
 				? [
 						"",
@@ -152,6 +172,7 @@ export async function describeManagerState(
 			).join("\n"),
 			actions: operationActions(operation, noSyncedContent, canSwitch, mainActions),
 			operation,
+			...(currentObservation ? { observation: currentObservation } : {}),
 			...(currentAttention
 				? {
 						attention: currentAttention,