@narumitw/pi-sync 0.1.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# ☁️ pi-sync — 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` is a native [Pi coding agent](https://pi.dev) extension that syncs selected Pi configuration through Cloudflare R2 or other S3-compatible object storage.
+
+It syncs automatically by default when Pi starts, then uses immutable snapshot bundles, a `latest.json` pointer, local locking, secret scanning, and pre-apply backups. Cross-machine pushes use a best-effort remote re-read guard because R2 rejected conditional `latest.json` writes during testing.
+
+## ✨ Features
+
+- Adds a `/pisync` command with `status`, `diff`, `push`, `pull`, `sync`, `history`, `rollback`, `doctor`, and `unlock` subcommands.
+- Syncs allowlisted Pi configuration from `~/.pi/agent`:
+  - `settings.json`
+  - `keybindings.json`
+  - `models.json`
+  - `AGENTS.md`
+  - `skills/`, `prompts/`, `themes/`, and `extensions/`
+- Stores each remote version as an immutable gzip-compressed JSON snapshot bundle.
+- Updates remote state through `latest.json` after re-reading remote state to reject already-visible remote changes.
+- Creates local backups before `pull` and `rollback` under `~/.pi/agent/.pisync/backups/`.
+- Runs `/pisync sync` automatically on Pi startup when R2/S3 config is present.
+- Uses a local exclusive lock at `~/.pi/agent/.pisync/lock` for destructive sync operations and only treats locks as stale after checking process liveness.
+- Refuses to push common secret patterns and denylisted paths such as `.env`, `.env.local`, token/secret files, `.pisync`, `.git`, and `node_modules`.
+- Preflights snapshot apply operations before mutating local files, refuses symlink path escapes, and rejects writes over symlinks or directories.
+
+## 📦 Install
+
+```bash
+pi install npm:@narumitw/pi-sync
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-sync
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-sync
+```
+
+## ⚙️ Configuration
+
+Run:
+
+```text
+/pisync init
+```
+
+Then edit:
+
+```text
+~/.pi/agent/pi-sync.local.json
+```
+
+Example:
+
+```json
+{
+  "endpoint": "https://<account-id>.r2.cloudflarestorage.com",
+  "bucket": "pi-sync",
+  "region": "auto",
+  "accessKeyId": "<access-key-id>",
+  "secretAccessKey": "<secret-access-key>",
+  "sessionToken": "<optional-session-token>",
+  "profile": "default",
+  "prefix": "pi-sync",
+  "autoSync": true
+}
+```
+
+Environment variables override the local config file:
+
+```bash
+export PI_SYNC_ENDPOINT="https://<account-id>.r2.cloudflarestorage.com"
+export PI_SYNC_BUCKET="pi-sync"
+export PI_SYNC_REGION="auto"
+export PI_SYNC_ACCESS_KEY_ID="..."
+export PI_SYNC_SECRET_ACCESS_KEY="..."
+export PI_SYNC_SESSION_TOKEN="..." # optional, for temporary STS/SSO credentials
+export PI_SYNC_PROFILE="default"
+export PI_SYNC_PREFIX="pi-sync"
+export PI_SYNC_AUTO_SYNC="true"
+```
+
+`PI_SYNC_ACCESS_KEY_ID`, `PI_SYNC_SECRET_ACCESS_KEY`, and `PI_SYNC_SESSION_TOKEN` are local-only credentials. Do not put them in files that pi-sync syncs. `PI_SYNC_SESSION_TOKEN` is optional and only needed for temporary credentials such as AWS STS, AWS SSO, or assumed roles. pi-sync also reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, `R2_ENDPOINT`, and `R2_BUCKET` as compatibility aliases when the matching `PI_SYNC_*` variable is not set.
+
+## 🚀 Usage
+
+```text
+/pisync config
+/pisync doctor
+/pisync status
+/pisync diff
+/pisync push
+/pisync pull
+/pisync sync
+/pisync history
+/pisync rollback <snapshot-id>
+/pisync unlock --stale
+```
+
+Useful flags:
+
+- `--yes` / `-y`: skip confirmation prompts.
+- `--force`: allow push or pull when both local and remote state changed.
+- `--stale`: remove a stale local lock with `/pisync unlock --stale`.
+
+## 🔄 Automatic sync
+
+`autoSync` defaults to `true`. When Pi starts, pi-sync runs the same conservative decision logic as `/pisync sync`:
+
+- only local changed or remote is empty → push
+- first sync with existing local settings and an identical remote snapshot → initialize local sync state without rewriting files
+- first sync with existing local settings and a different remote snapshot → skip and show a warning so you manually choose `/pisync pull` or `/pisync push`
+- only remote changed after an established sync → pull with a backup
+- both local and remote changed after a previous sync → skip and show a warning
+- no config present → do nothing
+
+Disable startup sync with either:
+
+```json
+{
+  "autoSync": false
+}
+```
+
+or:
+
+```bash
+export PI_SYNC_AUTO_SYNC=false
+```
+
+## 🧠 Sync model
+
+Remote layout:
+
+```txt
+pi-sync/
+└── profiles/
+    └── default/
+        ├── latest.json
+        ├── history.json
+        └── snapshots/
+            └── 2026-05-21T12-00-00-000Z-abcd1234.json.gz
+```
+
+Each snapshot contains the selected file tree and SHA-256 hashes. `latest.json` points to the active snapshot. Rollback applies an older snapshot locally and moves `latest.json` back to that snapshot.
+
+Before updating `latest.json`, pi-sync re-reads the current pointer and rejects the push if it already differs from the version seen at the start of the command. This prevents overwriting changes that are visible before the final write. It is not a true atomic cross-machine compare-and-swap on R2, so two machines that push at the same instant can still race; run `/pisync status` before important manual pushes if you use multiple machines heavily.
+
+## 🛡️ Safety notes
+
+- pi-sync auto-syncs on startup by default, but skips instead of overwriting when first-run local settings and a remote snapshot both exist, or when both local and remote changed after a previous sync.
+- pi-sync does not sync Pi sessions, OAuth state, npm caches, `.env`, `.env.local`, `node_modules`, or `.pisync` state.
+- If another Pi process is already syncing on the same machine, destructive commands stop at the local lock. `/pisync unlock --stale` is intended for locks whose process is gone or invalid.
+- If another machine's update is visible before this machine updates `latest.json`, push is rejected unless you explicitly use `--force`.
+- Pull and rollback create backups before writing local files, then preflight deletes and writes before mutating the local settings tree.
+- Pull and rollback refuse to follow symlinked parent paths during snapshot apply and refuse to overwrite a symlink or directory with file content.
+
+## 🗂️ Package layout
+
+```txt
+extensions/pi-sync/
+├── src/
+│   └── sync.ts
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```
+
+The package exposes its Pi extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/sync.ts"]
+  }
+}
+```
+
+## 🔎 Keywords
+
+Pi extension, Pi coding agent, settings sync, Cloudflare R2, S3-compatible storage, snapshot sync, dotfiles sync.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@narumitw/pi-sync",
+	"version": "0.1.29",
+	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"sync",
+		"r2",
+		"s3"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/sync.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@mariozechner/pi-coding-agent": "0.73.0",
+		"typescript": "6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-sync"
+	}
+}