@narumitw/pi-sync 0.31.0 → 0.35.0

package/README.md

@@ -1,27 +1,18 @@
-# ☁️ pi-sync — R2/S3 Pi Settings Sync
+# ☁️ pi-sync — Git/WebDAV/R2/S3 Pi Settings Sync
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-sync)](https://www.npmjs.com/package/@narumitw/pi-sync) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-sync` syncs selected Pi configuration through Cloudflare R2 or other S3-compatible object storage. Named sync targets such as `home` and `work` can reuse storage profiles such as `r2` and `s3`.
-
-The extension uses immutable snapshot bundles, a `latest.json` publication pointer, local locking, secret scanning, pre-apply backups, and recoverable local apply transactions. Conversation/session syncing remains opt-in because session JSONL can contain prompts, tool output, paths, screenshots, and secrets.
+`@narumitw/pi-sync` syncs selected Pi content through Git, WebDAV, Cloudflare R2, or other S3-compatible storage. A reusable **storage connection** holds access configuration. A named **sync setup** selects one connection, one exact remote storage path, included content, and automatic-sync behavior.
 
 ## ✨ Features
 
-- 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**.
-- 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.
-- Syncs allowlisted Pi configuration from the Pi agent directory:
-  - `settings.json`, `keybindings.json`, `models.json`, `AGENTS.md`, and `APPEND_SYSTEM.md`
-  - recursive `skills/`, `prompts/`, `themes/`, and `extensions/` groups
-  - safe top-level files selected through `extraFiles`
-  - optionally denylist-filtered `sessions/**/*.jsonl`
-- Preserves files outside the addressed target's selection locally and in remote uploads.
-- Creates backups before pull/rollback and journals multi-file applies so failures roll back; interrupted transactions recover before the next sync.
-- Refuses common secret patterns, unsafe paths, symlink escapes, live-lock removal, and unreviewed conflict overwrites.
+- A goal-oriented `/sync` manager with symmetric **Sync setups** and **Storage connections** list/detail flows.
+- S3-compatible storage, a Cloudflare R2 setup preset, Git, and WebDAV.
+- Immutable snapshots, secret scanning, local locks, conflict checks, pull backups, transactional apply, and recovery journals.
+- Exact reviewed storage paths that do not change when a local sync setup is renamed.
+- One ordered `sync.include` list for Pi roots, safe agent-relative paths, and the privacy-sensitive `sessions` root.
+- Atomic private settings writes that preserve unknown fields and reject stale concurrent edits.
+- Fail-closed validation for missing references, mixed backend fields, duplicate remote locations, unsafe paths, malformed credentials, and credential-bearing Git URLs.
 
 ## 📦 Install
 
@@ -35,7 +26,7 @@ Try without installing permanently:
 pi -e npm:@narumitw/pi-sync
 ```
 
-Try this package from a local checkout:
+Try a local checkout:
 
 ```bash
 pi -e ./extensions/pi-sync
@@ -43,311 +34,243 @@ pi -e ./extensions/pi-sync
 
 ## 🚀 Quick start
 
-Run the manager:
+Run:
 
 ```text
 /sync
 ```
 
-When pi-sync is not configured, choose **Set up sync**. The TUI guides you through:
-
-1. Cloudflare R2 or another S3-compatible service
-2. `Personal / Home`, `Work`, or a custom target purpose
-3. an endpoint and, for S3, the existing bucket name
-4. a recommended remote location or advanced customization
-5. environment credentials or a private settings-file template
-6. a synced-content preset
-7. an exact setup preview and **Save setup** confirmation
-
-For a first Cloudflare R2 target, the recommended location requires no raw path questions:
-
-```json
-{
-  "profile": "r2",
-  "bucket": "pi-sync",
-  "prefix": "pi-sync",
-  "namespace": "home"
-}
-```
-
-The R2 bucket must already exist; pi-sync never creates buckets. Generic S3 setup asks for one existing, potentially globally unique bucket and derives storage profile `s3`, prefix `pi-sync`, and namespace `home` or `work`. **Customize remote location** retains direct control over profile name, bucket, prefix, and namespace.
-
-Pi's extension input API does not provide masked secret entry, so pi-sync never asks for a secret in an unmasked dialog. Use existing environment credentials or add credentials manually to the private settings file. Secret values are never shown in menus, status, warnings, or errors.
+Choose **Set up sync**, then review the storage connection, exact storage path, included content, automatic-sync choice, and masked credentials before saving. Buckets and remote repositories must already exist. Git uses the user's existing non-interactive SSH or credential-helper configuration and never stores Git credentials.
 
-A configured manager shows:
+The manager shows local state without contacting remote storage:
 
 ```text
-Current target: home
-Storage: Cloudflare R2 · personal-pi
-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
+Current sync setup: home
+Storage: Cloudflare R2 · r2 · personal-pi
+Included: 5 built-in groups · 0 extra files · Sessions off
+Automatic sync: On
+Remote status: Not checked
 ```
 
-Its primary actions are:
-
-- **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 post-switch pulling, automatic sync, and synced content
-- **More…** — open one shallow level containing target/storage management, history/recovery, Help, and Back
-
-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.
+Primary actions include **Sync now**, **Switch sync setup**, **Status & changes**, **Settings**, and **More…**. Secondary screens provide **Back**; Escape closes the flow. Destructive and externally visible operations show exact previews and confirmations.
 
 ## ⚙️ Settings
 
-The private user settings file is:
+The canonical private user file is:
 
 ```text
-${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-sync.json
+~/.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.
+Pi's configured agent directory replaces `~/.pi/agent` when applicable. Missing settings load as unconfigured without creating an agent directory, file, temporary, or lock. An explicit setup creates the file atomically. On POSIX, pi-sync creates and replaces it with mode `0600`. Pi-sync processes coordinate settings access through `pi-sync.json.mutation-lock`; lock-unaware editors are outside that serialization boundary and should not save the file while a pi-sync settings operation is running. Credentials stay in this canonical private file and are never shown in menus, reviews, status, notifications, errors, logs, or completion metadata.
+
+An existing private `pi-sync.local.json` containing a valid version 3 document is copied byte-for-byte to `pi-sync.json`; the old file remains as a recovery copy. If both paths exist, `pi-sync.json` wins and the other path remains untouched.
 
-A version 2 example:
+### Complete version 3 example
 
 ```json
 {
-  "version": 2,
-  "activeTarget": "home",
-  "targetSwitchAction": "ask",
-  "profiles": {
+  "version": 3,
+  "activeSyncSetup": "home",
+  "onSwitch": "ask-before-pull",
+  "storageConnections": {
     "r2": {
-      "kind": "r2",
-      "endpoint": "https://<account-id>.r2.cloudflarestorage.com",
+      "type": "s3",
+      "endpoint": "https://example.r2.cloudflarestorage.com",
       "region": "auto",
-      "accessKeyId": "<access-key-id>",
-      "secretAccessKey": "<secret-access-key>"
+      "credentials": {
+        "accessKeyId": "<access-key-id>",
+        "secretAccessKey": "<secret-access-key>"
+      }
     },
-    "s3": {
-      "kind": "s3-compatible",
-      "endpoint": "https://s3.example.com",
-      "region": "ap-northeast-1",
-      "accessKeyId": "<access-key-id>",
-      "secretAccessKey": "<secret-access-key>"
+    "github": {
+      "type": "git",
+      "remote": "git@github.com:owner/private-pi-sync.git"
+    },
+    "nextcloud": {
+      "type": "webdav",
+      "url": "https://cloud.example.com/remote.php/dav/files/user",
+      "credentials": {
+        "username": "user",
+        "password": "<app-password>"
+      }
     }
   },
-  "targets": {
+  "syncSetups": {
     "home": {
-      "profile": "r2",
-      "bucket": "personal-pi",
-      "prefix": "pi-sync",
-      "namespace": "home",
-      "autoSync": true,
-      "syncFiles": ["settings.json", "skills", "prompts", "themes"],
-      "syncSessions": false,
-      "extraFiles": []
+      "storage": {
+        "connection": "r2",
+        "bucket": "personal-pi",
+        "path": "pi-sync/home"
+      },
+      "sync": {
+        "include": ["settings.json", "AGENTS.md", "skills", "prompts", "themes"],
+        "automatic": true
+      }
+    },
+    "git-backup": {
+      "storage": {
+        "connection": "github",
+        "branch": "pi-sync/home",
+        "path": "pi-sync/home"
+      },
+      "sync": {
+        "include": ["settings.json", "AGENTS.md"],
+        "automatic": false
+      }
     },
-    "work": {
-      "profile": "s3",
-      "bucket": "company-pi",
-      "prefix": "developers/narumi",
-      "namespace": "work",
-      "autoSync": true,
-      "syncFiles": ["AGENTS.md", "prompts"],
-      "syncSessions": false,
-      "extraFiles": []
+    "webdav-backup": {
+      "storage": {
+        "connection": "nextcloud",
+        "path": "pi-sync/home"
+      },
+      "sync": {
+        "include": ["settings.json", "sessions"],
+        "automatic": false
+      }
     }
   }
 }
 ```
 
-### Terminology
-
-- 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.
+Cloudflare R2 is persisted as `"type": "s3"`; R2 is a setup preset, not another schema type. Temporary S3 credentials may additionally include `credentials.sessionToken`.
 
-### Target switching
+### Required backend shapes
 
-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.
+- **S3/R2 connection:** `type`, `endpoint`, `region`, and `credentials.accessKeyId` / `credentials.secretAccessKey`.
+- **S3/R2 setup storage:** `connection`, `bucket`, and complete relative `path`; `branch` is rejected.
+- **Git connection:** `type` and a credential-free SSH or HTTPS `remote`.
+- **Git setup storage:** `connection`, `branch`, and complete repository `path`; `bucket` is rejected.
+- **WebDAV connection:** `type`, HTTPS `url`, and `credentials.username` / `credentials.password`.
+- **WebDAV setup storage:** `connection` and complete relative `path`; `bucket` and `branch` are rejected.
 
-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.
+Every setup requires `sync.include` and explicit `sync.automatic`. `activeSyncSetup` must reference an own-property setup when any setups exist and must be absent when the setup catalog is empty. A referenced connection cannot be removed. The current setup must be switched before removal. Two setups cannot resolve to the same normalized backend location.
 
-### Synced content
+`onSwitch` accepts:
 
-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.
+- `ask-before-pull` — switch, then ask in TUI whether to start a reviewed pull;
+- `pull-after-switch` — require observable UI and start the normal reviewed pull;
+- `switch-only` — switch without reading or applying remote content.
 
-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.
+### Included content
 
-Unselected items are unmanaged: pi-sync does not compare, pull, overwrite, or delete their local content, and pushes preserve their existing remote content.
+`sync.include` is ordered and duplicate-free. Supported Pi roots are:
 
-### Environment precedence and deprecation
-
-The existing `PI_SYNC_*` family still works in this release with its existing highest precedence, but it is deprecated and will be removed in a future major version. pi-sync shows variable names—not values—and migration guidance when any are active.
-
-Move these fields into a storage profile:
-
-- `PI_SYNC_ENDPOINT`
-- `PI_SYNC_REGION`
-- `PI_SYNC_ACCESS_KEY_ID`
-- `PI_SYNC_SECRET_ACCESS_KEY`
-- `PI_SYNC_SESSION_TOKEN`
-
-Move these fields into a sync target:
-
-- `PI_SYNC_BUCKET`
-- `PI_SYNC_PROFILE` → `namespace`
-- `PI_SYNC_PREFIX`
-- `PI_SYNC_AUTO_SYNC`
-- `PI_SYNC_SESSIONS`
-
-`PI_SYNC_PROFILE` continues to mean only the remote namespace during the deprecation period; it never selects a storage profile or current target.
+```text
+settings.json, keybindings.json, models.json, AGENTS.md, APPEND_SYSTEM.md,
+skills, prompts, themes, extensions, sessions
+```
 
-Standard compatibility aliases remain below `PI_SYNC_*` precedence:
+Safe agent-relative custom files or directories may also be included. Absolute paths, `..`, backslashes, controls, denied secret/settings paths, duplicate case variants, and ambiguous nested paths under reserved roots are rejected.
 
-- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`
-- `R2_ENDPOINT`, `R2_BUCKET`
+An empty array is valid. It means no useful transfer is selected: **Sync now** reports the condition and does not claim that the setup is up to date. Unselected content remains unmanaged locally and is preserved when republishing existing remote snapshots.
 
-Environment-overridden fields are read-only in interactive settings. Cloudflare R2 static keys commonly reject `X-Amz-Security-Token`; pi-sync retains its one-time retry without the configured token for that R2 response.
+Adding `sessions` requires a privacy acknowledgement in interactive flows. Session JSONL can contain prompts, tool output, file paths, images, and secrets. Automatic apply protects the currently open session file; restart Pi or resume a pulled session to use newly synchronized conversations.
 
-### Legacy flat settings
+### Unsupported old settings and recovery
 
-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.
+Version 1, version 2, and non-empty unversioned documents are intentionally unsupported by this breaking schema reset. pi-sync does **not** migrate, partially interpret, downgrade, or overwrite them. Automatic sync pauses and reports an actionable version 3 error without displaying secrets.
 
-Adding a second target offers an explicit migration preview. On confirmation pi-sync:
+Recovery:
 
-1. takes an exact private backup of the original JSON bytes;
-2. preserves unknown top-level fields;
-3. maps existing connection and policy fields without changing the remote destination;
-4. adopts the existing local sync state for the migrated target;
-5. publishes the version 2 file atomically.
+1. retain the old file byte-for-byte;
+2. move it aside manually;
+3. create a new version 3 document or run the setup manager;
+4. run `/sync doctor`, inspect the exact storage path, and review the first pull or push;
+5. restore the retained file and a compatible older package only if rolling back.
 
-Malformed, invalid, symlinked, or concurrently changed settings are never overwritten automatically. Version 2 settings require the multi-target pi-sync release or newer. For a manual downgrade, restore the exact `.legacy-<timestamp>.bak` flat-config backup; no remote migration or rollback is needed.
+Malformed, invalid, unsupported, symlinked, or concurrently changed documents remain untouched. Failed UI saves keep the previous file and displayed/effective state.
 
 ## 💬 Commands
 
-The menu is the preferred interactive workflow. Existing deterministic routes remain available:
+The menu is preferred, while deterministic routes remain available:
 
 ```text
 /sync help
-/sync use <target>
+/sync use <setup>
 /sync init
-/sync config [--target <name>]
-/sync files [--target <name>]
-/sync status [--target <name>]
-/sync diff [--target <name>]
-/sync doctor [--target <name>]
-/sync push [--target <name>]
-/sync pull [--target <name>]
-/sync sync [--target <name>]
-/sync history [--target <name>]
-/sync rollback <snapshot-id> [--target <name>]
+/sync config [--setup <name>]
+/sync files [--setup <name>]
+/sync status [--setup <name>]
+/sync diff [--setup <name>]
+/sync doctor [--setup <name>]
+/sync push [--setup <name>]
+/sync pull [--setup <name>]
+/sync sync [--setup <name>]
+/sync history [--setup <name>]
+/sync rollback <snapshot-id> [--setup <name>]
 /sync unlock --stale
 ```
 
-Flags:
-
-- `--target <name>` addresses a target without switching it.
-- `--yes` / `-y` skips an explicit direct command's confirmation.
-- `--force` resolves a reviewed conflict for push/pull/sync.
+- `--setup <name>` addresses a setup without switching it.
+- `--yes` / `-y` skips a direct route's confirmation.
+- `--force` accepts a reviewed content conflict but never disables backend concurrency protection.
 - `--stale` requests guarded stale-lock recovery.
 
-Unknown flags, unexpected values, and missing target/snapshot values are rejected. Argument completion includes configured target names after session start.
-
-TUI mode provides the full manager and custom settings components. RPC uses Pi's dialog/notification protocol and does not call TUI-only components. Print/JSON modes cannot display extension UI; use explicit direct routes for compatible automation and do not expect notification-only status output.
+The former version 2 setup-addressing flag is rejected. Unknown flags, unknown commands, trailing values, and missing setup/snapshot values are rejected. Completion includes known setup names and preserves preceding command tokens.
 
-## 🔄 Sync and recovery model
+TUI mode provides custom components. RPC uses Pi's supported dialog/notification protocol. Print and JSON modes never enter TUI-only screens; unsupported interactive routes reject or remain protocol-safe rather than relying on no-op output.
 
-For the current target, startup auto-sync uses conservative decisions:
+## 🔄 Backend and recovery model
 
-- local changed or remote empty → preview/confirm manually, or push in the existing quiet automatic path
-- identical first sync → initialize local state
-- safe remote-only change → pull with backup
-- first-sync mismatch or both changed → stop and require review
-- no selected content → report/skip
+| Backend | Publication guarantee | Authentication | Remote path |
+| --- | --- | --- | --- |
+| Git | Exact expected-ref lease | Existing SSH/configured credential helper | `<branch>:<storage.path>` |
+| WebDAV | Verified strong conditional requests | Private settings username/app password | `<url>/<storage.path>` |
+| R2/S3 | Read-check-write-verify | Private settings credentials | `<bucket>/<storage.path>` |
 
-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.
+Git requires Git 2.30 or newer and a SHA-1-format remote repository. HTTPS userinfo, URL passwords, local paths, `file`, `git`, `ext`, and remote-helper transports are rejected. When editing a Git setup, changing its storage path also requires a new owned branch so the existing branch remains readable at its reviewed path. The private bare cache under `.pisync/git/` is rebuildable.
 
-Remote layout remains compatible:
+WebDAV requires HTTPS except loopback tests. URL credentials, query strings, fragments, unsafe redirects, weak/missing ETags, and ignored conditional headers fail closed. `/sync doctor` verifies collection and conditional-write behavior with an isolated probe.
 
-```text
-<prefix>/
-└── profiles/
-    └── <namespace>/
-        ├── latest.json
-        ├── history.json
-        └── snapshots/
-            └── <snapshot-id>.json.gz
-```
-
-Snapshot upload is staging; `latest.json` is the active publication boundary. A failed history update after publication is reported as “snapshot active, history needs repair” instead of falsely claiming no remote change.
-
-Before pull/rollback, pi-sync writes a backup under `.pisync/backups/`. It then preflights all paths, stages a private transaction journal, applies changes, and restores every affected path if a later mutation fails. An interrupted journal is recovered before the next session/snapshot apply. Filesystem-wide replacement cannot be one OS primitive, so the guarantee is a complete previous or complete new accepted state after rollback/recovery—not an unrecoverable partial accepted state.
-
-R2/S3 does not provide the true cross-machine compare-and-swap used here. pi-sync re-reads `latest.json` immediately before publication and verifies afterward, but simultaneous writers can still race. Review status before important forced updates.
+S3/R2 stages immutable bundles, rechecks the visible head before publication, and verifies afterward. Unlike Git/WebDAV, generic S3 does not provide an atomic compare-and-swap for `latest.json`; status review remains important for simultaneous writers.
 
-## 🔒 Session syncing
-
-`syncSessions` defaults to `false`. Enabling it includes configured Pi session JSONL files and makes the privacy warning visible in settings, status, previews, and confirmations.
-
-Only JSONL session files are included. Denylisted names and paths such as `.env*`, `.pisync`, `node_modules`, `token`, and `secret` are ignored. The currently open session file is protected during pull; restart Pi or resume a pulled session to use newly synced conversations.
-
-Sessions can contain prompts, model output, tool results, file paths, images, and secrets. Use only storage you trust.
+Before pull or rollback, pi-sync writes a backup under `.pisync/backups/`. Apply preflights paths and checksums, journals all mutations, restores the prior state after failures, and recovers interrupted journals on startup. Removing a local setup or connection never deletes remote data.
 
 ## 🛡️ Safety notes
 
-- 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.
-- A live local lock disables destructive work. Stale/unreadable lock recovery retains process-liveness and guard checks.
-- Force operations remain explicit direct/conflict-recovery actions and retain exact confirmations.
-- Terminal-bound config, remote metadata, machine names, paths, and errors are control-character sanitized.
+- Canonical, legacy, temporary, and recovery settings paths are denied from snapshots.
+- Push scans managed local content for common secret patterns.
+- Remote snapshot references, checksums, paths, manifests, response sizes, and publication revisions are validated.
+- Symlink parents, path escapes, duplicate paths, and unsafe file/directory replacement fail before local mutation.
+- Live locks block mutation; stale recovery rechecks process and guard ownership.
+- Cancellation aborts preparation and dialogs. Publication/apply commit boundaries finish with bounded signals and report ambiguous outcomes explicitly.
+- Terminal-bound names, paths, metadata, and errors are control-character sanitized.
 
 ## ♿ Conditional terminal accessibility smoke
 
-Pi exposes terminal components rather than a semantic/ARIA tree, so automated tests verify textual state, keyboard paths, control-character escaping, and 32/60/100-column fitting rather than claiming semantic announcements. When validating a release in a supported environment:
-
-1. open `/sync` using only the keyboard and verify arrows, Enter, Space, search typing, paging where available, Back, and Escape;
-2. enter a Unicode target/profile name with an IME and confirm focus returns to Pi after closing;
-3. check the main, warning, preview, saved, cancelled, and invalid states with the terminal screen reader in use;
-4. repeat under a light and dark Pi theme and at 32, 60, and 100 columns.
-
-Critical meaning is always present in text such as `(current)`, `Warning`, `Invalid`, `Saved`, `Cancelled`, or `Applied`; color is supplementary.
+Pi exposes terminal components rather than a semantic/ARIA tree. Release validation checks textual state, keyboard operation, Escape/Back, control escaping, and narrow rendering. Critical meaning appears in text such as `(current)`, `Warning`, `Invalid`, `Saved`, `Cancelled`, and `Applied`; color is supplementary.
 
 ## 🗂️ Package layout
 
 ```text
 extensions/pi-sync/
 ├── src/
-│   ├── index.ts                 # Thin Pi entrypoint
-│   ├── 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
+│   ├── index.ts
+│   ├── sync.ts
+│   ├── config.ts
+│   ├── config-file.ts
+│   ├── settings-management.ts
+│   ├── manager-ui.ts
+│   ├── storage-connections-ui.ts
+│   ├── sync-setups-ui.ts
+│   ├── file-selection.ts
+│   ├── sync-operations.ts
+│   ├── sync-backend.ts
+│   ├── s3-backend.ts
+│   ├── webdav-backend.ts
+│   ├── git-backend.ts
+│   ├── snapshot.ts
+│   └── *.ts
 ├── test/
 ├── README.md
 ├── LICENSE
-├── tsconfig.json
 └── package.json
 ```
 
 ## 🔎 Keywords
 
-Pi extension, Pi coding agent, settings sync, Cloudflare R2, S3-compatible storage, multi-profile sync, sync targets, snapshot sync, dotfiles sync.
+Pi extension, Pi coding agent, settings sync, Git, WebDAV, Nextcloud, Cloudflare R2, S3-compatible storage, storage connections, sync setups, snapshot sync, dotfiles sync.
 
 ## 📄 License
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.31.0",
-	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
+	"version": "0.35.0",
+	"description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -11,7 +11,14 @@
 		"pi",
 		"sync",
 		"r2",
-		"s3"
+		"s3",
+		"webdav",
+		"nextcloud",
+		"synology",
+		"git",
+		"github",
+		"gitlab",
+		"forgejo"
 	],
 	"files": [
 		"src",
@@ -29,6 +36,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"fast-xml-parser": "^5.10.1",
 		"proper-lockfile": "^4.1.2"
 	},
 	"devDependencies": {

package/src/backend-factory.ts

@@ -0,0 +1,20 @@
+import { GitSyncBackend } from "./git-backend.js";
+import { S3SyncBackend } from "./s3-backend.js";
+import type { SyncBackend } from "./sync-backend.js";
+import type { AnySyncConfig } from "./types.js";
+import { WebDavSyncBackend } from "./webdav-backend.js";
+
+export type SyncBackendFactory = {
+	bivarianceHack(config: AnySyncConfig): SyncBackend;
+}["bivarianceHack"];
+
+export const createSyncBackend: SyncBackendFactory = (config) => {
+	switch (config.backend.type) {
+		case "s3":
+			return new S3SyncBackend(config.backend);
+		case "webdav":
+			return new WebDavSyncBackend(config.backend);
+		case "git":
+			return new GitSyncBackend(config.backend);
+	}
+};