@narumitw/pi-sync 0.29.1 → 0.30.0

package/README.md

@@ -10,7 +10,7 @@ The extension uses immutable snapshot bundles, a `latest.json` publication point
 
 - Opens a goal-oriented `/sync` manager showing the current target, storage, auto-sync, session scope, and relevant next actions.
 - Supports multiple named **sync targets** and reusable R2/S3 **storage profiles**.
-- Switches targets without syncing or modifying files; only the current target runs automatic startup/shutdown sync.
+- Asks to review a pull after switching targets by default, with settings to start that review automatically or switch only.
 - Previews concrete local or remote file changes before push, pull, force resolution, or rollback.
 - Uses transactional synced-content drafts with explicit Save, Discard, and Continue editing choices.
 - Keeps direct `help`, `use`, `init`, `config`, `files`, `status`, `diff`, `doctor`, `push`, `pull`, `sync`, `history`, `rollback`, and `unlock` routes for compatibility and automation.
@@ -79,36 +79,49 @@ A configured manager shows:
 ```text
 Current target: home
 Storage: Cloudflare R2 · personal-pi
-Auto-sync: On · Sessions: Off
-Last known sync: Remote not checked
+Synced content: 9 built-in groups · 0 extra files · Sessions: Off
+Auto-sync: On
+Last applied snapshot: snapshot-id (or Never synced)
+Remote changes: Not checked
 ```
 
 Its primary actions are:
 
-- **Sync now** — conservatively decide whether to push, pull, or do nothing
-- **Switch target** — preview and change the current target without syncing
+- **Sync now (recommended)** — conservatively decide whether to push, pull, or do nothing
+- **Pull from remote** — check the remote snapshot, preview exact local writes/deletes, then confirm
+- **Push to remote** — scan and preview exact remote publication changes, then confirm
+- **Switch target** — preview the target change, then follow the configured pull behavior
 - **Status & changes** — perform a cancellable read-only remote check
-- **Settings** — control automatic sync and synced content for the current target
-- **Manage targets & storage** — add, edit, or remove local target/profile definitions
-- **History & recovery** — browse snapshots, preview rollback, diagnose setup, or recover a stale lock
-- **Help**
+- **Settings** — control post-switch pulling, automatic sync, and synced content
+- **More…** — open one shallow level containing target/storage management, history/recovery, Help, and Back
 
-Escape exits the main menu. Secondary menus provide Back; dirty synced-content drafts provide Save, Discard, and Continue editing. Cancellation before publication has no side effects.
+The menu does not query remote storage merely to open. It shows the last locally applied snapshot and marks remote changes as unchecked until an operation runs. When no synced content is selected, transfer actions are hidden and Settings becomes the first action. During an active or recoverable lock, mutation actions remain unavailable.
+
+Push and pull keep their existing concrete previews and confirmation prompts. Pull creates a local backup before applying; push scans locally managed content for likely secrets before publication. Escape cancels a pre-commit check without changing local or remote files. Once publication or apply begins, cancellation is disabled. Conflicts never force automatically; inspect **Status & changes** and use an explicit direct route only after reviewing the conflict.
+
+Escape exits the main menu. **More…** and secondary menus provide Back; dirty synced-content drafts provide Save, Discard, and Continue editing. Cancellation before publication has no side effects.
 
 ## ⚙️ Settings
 
 The private user settings file is:
 
 ```text
-${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-sync.local.json
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-sync.json
 ```
 
+On first read, an existing `pi-sync.local.json` is migrated byte-for-byte to `pi-sync.json`
+with private POSIX `0600` permissions. The private legacy file is retained as a recovery copy and may
+be deleted after verifying the new file. If both files exist, `pi-sync.json` takes precedence and the
+legacy file remains untouched. Malformed, invalid, symlinked, changed, or otherwise unsafe legacy
+files are never overwritten automatically.
+
 A version 2 example:
 
 ```json
 {
   "version": 2,
   "activeTarget": "home",
+  "targetSwitchAction": "ask",
   "profiles": {
     "r2": {
       "kind": "r2",
@@ -155,15 +168,22 @@ A version 2 example:
 - A **storage profile** owns connection/authentication fields: `kind`, `endpoint`, `region`, `accessKeyId`, `secretAccessKey`, and optional `sessionToken`.
 - A **sync target** references a storage profile and owns `bucket`, `prefix`, `namespace`, `autoSync`, and its synced-content policy.
 - `activeTarget` is used by bare commands and automatic sync.
+- `targetSwitchAction` controls what happens after a target switch: `ask` (default), `pull`, or `switch-only`.
 - `namespace` is the old flat `profile` concept. The remote layout and snapshot wire field remain named `profiles`/`profile` for compatibility.
 
 When adding another target with the same storage profile, pi-sync recommends reusing the current target's bucket and prefix while deriving a separate namespace from the new target name. For example, `home` and `work` may both use profile `r2`, bucket `pi-sync`, and prefix `pi-sync`, producing `pi-sync/profiles/home/` and `pi-sync/profiles/work/`.
 
 Two targets may intentionally overlap local files, but only one is automatic. pi-sync rejects duplicate effective target remote identities—including deprecated bucket/prefix/namespace environment overrides—to prevent independent local states from controlling the same remote pointer. Removing a target/profile removes local configuration only; it never deletes buckets or snapshots. A referenced profile cannot be removed, and users must switch away before removing one of several current targets.
 
+### Target switching
+
+The default `targetSwitchAction: "ask"` changes `activeTarget` atomically, then asks in TUI mode whether to review a pull for that target. Choosing not to review leaves local files unchanged. Accepting starts the normal pull flow, which fetches the remote snapshot and shows the exact writes and deletions before apply. In print, JSON, or RPC mode, `ask` switches without pulling and directs interactive users to `/sync pull` where notifications are available.
+
+Set `targetSwitchAction` to `"pull"` to start that reviewed pull automatically after a confirmed target switch. The exact pull summary and apply confirmation remain enabled, conflict detection still stops unsafe merges, a local backup is created before apply, and pi-sync never adds `--force`; Pi may separately ask whether to reload changed resources after a successful pull. Because that confirmation requires observable UI, `/sync use` rejects `"pull"` in print and JSON modes before changing `activeTarget`; use TUI or RPC mode instead. Set it to `"switch-only"` to retain the previous no-pull behavior. Selecting an already-current target is a no-op. If a pull fails or its concrete review is declined, the new target remains active and pi-sync reports that synced files were not changed before `/sync pull` is retried.
+
 ### Synced content
 
-The **Settings → Choose synced content** screen edits a draft. Enter or Space toggles, typing searches, and Escape opens the Save/Discard/Continue decision. A single Save atomically updates the target while preserving unknown fields and POSIX `0600` permissions. Saving settings never starts network sync.
+The **Settings → Choose synced content** screen edits a draft. Arrow keys navigate, Enter or Space toggles, and Escape opens the Save/Discard/Continue decision. A single Save atomically updates the target while preserving unknown fields and POSIX `0600` permissions. Saving settings never starts network sync.
 
 Omitting `syncFiles` preserves the legacy default of every built-in item. An empty array is valid and means the target manages nothing; **Sync now** reports that state instead of publishing an empty sync. Unknown built-in names fail validation.
 
@@ -200,7 +220,7 @@ Environment-overridden fields are read-only in interactive settings. Cloudflare
 
 ### Legacy flat settings
 
-Existing flat `pi-sync.local.json` files continue to work unchanged as a synthetic `default` target/profile. The old flat `profile` remains the remote namespace.
+Existing flat settings continue to work unchanged as a synthetic `default` target/profile, including settings migrated from the legacy `pi-sync.local.json` filename. The old flat `profile` remains the remote namespace.
 
 Adding a second target offers an explicit migration preview. On confirmation pi-sync:
 
@@ -254,7 +274,7 @@ For the current target, startup auto-sync uses conservative decisions:
 - first-sync mismatch or both changed → stop and require review
 - no selected content → report/skip
 
-Switching targets changes only `activeTarget`; it never starts sync. The next startup uses the new target's `autoSync`, or the user can choose **Sync now** immediately.
+Switching targets first changes `activeTarget`, then follows `targetSwitchAction`: ask before reviewing a pull in TUI by default, start a reviewed pull automatically when configured, or stop after switching. Pulls remain pinned to the selected target and retain exact summaries, locking, backups, and conflict safeguards. The next startup uses the new target's `autoSync` regardless of the switch action.
 
 Remote layout remains compatible:
 
@@ -284,7 +304,7 @@ Sessions can contain prompts, model output, tool results, file paths, images, an
 
 ## 🛡️ Safety notes
 
-- Credentials stay local and are never included in snapshots.
+- Credentials stay local; canonical, legacy, temporary, and migration-recovery settings files are always excluded from snapshots.
 - Push refuses common secret patterns in locally managed files.
 - Pull/rollback reject unsafe paths, duplicate paths, checksum mismatches, symlink parents, and file/directory replacement hazards before mutation.
 - Unmanaged local/remote files remain preserved.
@@ -312,7 +332,10 @@ extensions/pi-sync/
 │   ├── sync.ts                  # Command and lifecycle orchestration
 │   ├── manager-ui.ts            # Goal-oriented menus and setup/management flows
 │   ├── file-selection.ts        # Transactional synced-content editor
+│   ├── config-file.ts           # Private settings I/O and legacy filename migration
 │   ├── settings-management.ts   # Profiles, targets, migration, and atomic saves
+│   ├── settings-ui.ts           # SettingsList interaction and serialized saves
+│   ├── target-switch.ts         # Post-switch prompt, policy, and target handoff
 │   ├── snapshot-transaction.ts  # Local apply journal, rollback, and recovery
 │   └── *.ts                     # Config, policy, snapshot, S3, lock, and format modules
 ├── test/

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.29.1",
+	"version": "0.30.0",
 	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",

package/src/command.ts

@@ -230,6 +230,6 @@ export function usage() {
 	return [
 		"Usage: /sync <command>",
 		`Commands: ${commands}`,
-		"Settings: use /sync init or edit profiles and targets in ~/.pi/agent/pi-sync.local.json (or $PI_CODING_AGENT_DIR/pi-sync.local.json). Existing PI_SYNC_* overrides still work but are deprecated for future major-version removal.",
+		"Settings: use /sync init or edit profiles and targets in ~/.pi/agent/pi-sync.json (or $PI_CODING_AGENT_DIR/pi-sync.json). Existing PI_SYNC_* overrides still work but are deprecated for future major-version removal.",
 	].join("\n");
 }