@wuyaos/pi-sync 1.1.0 → 1.2.0

package/PROMO.md

@@ -1,95 +1,59 @@
 # pi-sync promotion drafts
 
-Repo: https://github.com/wuyaos/pi-packages  
-Install: `pi install git:github.com/wuyaos/pi-packages`  
-Release: https://github.com/wuyaos/pi-packages/releases/tag/v1.0.1
+## English
 
----
-
-## English (short)
-
-**pi-sync** — WebDAV backup/restore for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
-
-Open `/sync`, then **Upload Backup** on one machine and **Download Backup** on another.
+**pi-sync 1.2** — versioned WebDAV archives for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
 
 ```bash
-pi install git:github.com/wuyaos/pi-packages
-/sync   # main machine  → Upload Backup (Backup to cloud)
-/sync   # new machine   → Download Backup (Restore from cloud)
+pi install npm:@wuyaos/pi-sync
+/sync
 ```
 
-Works with any WebDAV (Nextcloud, 坚果云, TeraCLOUD, self-hosted). Restore keeps local `.bak` copies. MIT.
-
-👉 https://github.com/wuyaos/pi-packages
-
----
-
-## English (Discord / forum)
-
-Hey Pi users — I open-sourced **pi-sync**, a small package that syncs your Pi agent home over WebDAV.
-
-Problem: multi-machine setups mean re-copying `models.json`, skills, and extensions by hand.  
-Solution: `/sync push` on the main box, `/sync pull` on the next one.
-
-- Install: `pi install git:github.com/wuyaos/pi-packages`
-- Interactive menu: Upload Backup · Download Backup · Configure Sync Settings
-- Optional Windows bootstrap script for brand-new machines
-- Backup zips tagged by platform (`windows11`, `macos`, …)
-- Restore confirms and keeps timestamped local backups
-
-Feedback / issues welcome: https://github.com/wuyaos/pi-packages
-
----
+Highlights:
 
-## 中文（短）
+- Direct `~/.pi/agent` archive with configurable exclusions
+- Independent shared-Skills and per-project session archives
+- Automatic current-project archive when Pi exits
+- Back Up All / Restore All (latest)
+- English and Chinese menus
+- Streamed WebDAV transfers and safe archive validation
+- No live or per-turn synchronization
 
-**pi-sync**：给 [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) 用的 WebDAV 配置同步插件。
+WebDAV layout:
 
-多机之间一键备份 / 恢复 models、settings、skills、extensions。
-
-```bash
-pi install git:github.com/wuyaos/pi-packages
-/sync   # 主力机 → Upload Backup (Backup to cloud)
-/sync   # 新机器 → Download Backup (Restore from cloud)
+```text
+backup/pi/
+backup/skills/
+backup/sessions/<project>/
 ```
 
-支持任意 WebDAV（坚果云 / Nextcloud / 自建）。恢复前会做本地备份。MIT 开源。
-
-👉 https://github.com/wuyaos/pi-packages
-
----
-
-## 中文（朋友圈 / 社区）
-
-换电脑重装 Pi 配置太烦？我做了个小工具 **pi-sync** 并开源了。
+Repository: https://github.com/wuyaos/pi-packages/tree/master/pi-sync
 
-- 主力机 `/sync` → **Upload Backup** 把配置打成 zip 传到 WebDAV
-- 新机器 `/sync` → **Download Backup** 选择备份并还原
-- 覆盖 models / settings / skills / extensions
-- 恢复前自动留本地备份，密码建议用应用专用密码 + 环境变量
+## 简体中文
 
-安装一行：
+**pi-sync 1.2**：面向 [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) 的 WebDAV 有版本归档备份。
 
 ```bash
-pi install git:github.com/wuyaos/pi-packages
+pi install npm:@wuyaos/pi-sync
+/sync
 ```
 
-仓库：https://github.com/wuyaos/pi-packages  
-Release：https://github.com/wuyaos/pi-packages/releases/tag/v1.0.1
+主要特性：
 
-欢迎试用和提 issue。
+- 直接归档 `~/.pi/agent`，支持黑名单排除
+- 共享 Skills 与项目会话独立归档
+- 退出 Pi 时自动归档当前项目会话
+- 全部备份 / 全部恢复（最新）
+- 中英文菜单切换
+- WebDAV 流式传输与安全归档校验
+- 不进行实时或每轮同步
 
----
+WebDAV 目录：
 
-## Tweet / X (EN)
-
-Multi-machine Pi setup? I open-sourced pi-sync:
-
-`/sync` → Upload Backup → WebDAV  
-`/sync` → Download Backup → new machine
-
-models · settings · skills · extensions
-
-`pi install git:github.com/wuyaos/pi-packages`
+```text
+backup/pi/
+backup/skills/
+backup/sessions/<project>/
+```
 
-https://github.com/wuyaos/pi-packages
+仓库：https://github.com/wuyaos/pi-packages/tree/master/pi-sync

package/README.md

@@ -4,202 +4,211 @@
 
 [![pi package](https://img.shields.io/badge/pi-package-blue)](https://github.com/earendil-works/pi-coding-agent)
 [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![release](https://img.shields.io/github/v/release/wuyaos/pi-packages?display_name=tag&sort=semver)](https://github.com/wuyaos/pi-packages/releases)
 
-WebDAV-based config sync for [Pi](https://github.com/earendil-works/pi-coding-agent) — backup and restore **models**, **settings**, **skills**, **extensions**, and **session projects** across machines.
+WebDAV archive backup and restore for [Pi](https://github.com/earendil-works/pi-coding-agent).
 
-Run `/sync`, pick an action from the menu. One machine uploads; another downloads and restores.
+`pi-sync` creates versioned `.tar.xz` archives for Pi agent data, shared skills, and project sessions. It is intentionally **archive-only**: there are no live uploads, per-turn hooks, interval synchronization, or multi-machine merge conflicts.
 
-<p align="center">
-  <img src="docs/sync-menu.png" alt="Pi WebDAV Synchronization menu" width="720" />
-</p>
+## Features
 
-<p align="center"><sub><b>Pi WebDAV Synchronization</b> — interactive menu after <code>/sync</code></sub></p>
-
-## Why
-
-If you run Pi on multiple PCs / WSL / servers, reinstalling models, skills, and extensions by hand is painful. `pi-sync` packages your agent home into a timestamped zip, uploads it to any WebDAV folder, and restores it with local safety backups.
+- Back up `~/.pi/agent` directly without a staging copy
+- Exclude reinstallable or transient trees through a configurable blacklist
+- Keep `~/.agents/skills` in an independent, optional archive
+- Archive sessions separately per project
+- Automatically archive the current project when Pi exits
+- Back up or restore every enabled category in one action
+- English and Simplified Chinese `/sync` menus
+- Stream WebDAV uploads/downloads instead of buffering whole archives in memory
+- Reject unsafe archive paths, symbolic links, special nodes, and unsafe restore destinations
 
 ## Install
 
-Requires [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) and a WebDAV endpoint (TeraCLOUD, 坚果云 / Jianguoyun, Nextcloud, ownCloud, self-hosted, …).
-
-`pi-sync` is part of the [wuyaos/pi-packages](https://github.com/wuyaos/pi-packages) monorepo. Installing the whole repo loads every sub-package:
+Install the package from npm:
 
 ```bash
-pi install git:github.com/wuyaos/pi-packages
+pi install npm:@wuyaos/pi-sync
 ```
 
-To load **only** `pi-sync`, use the object form in `~/.pi/agent/settings.json`:
+Or install the complete monorepo:
 
-```json
-{
-  "packages": [
-    {
-      "source": "git:github.com/wuyaos/pi-packages",
-      "extensions": ["pi-sync/extensions/*.ts"],
-      "themes": []
-    }
-  ]
-}
+```bash
+pi install git:github.com/wuyaos/pi-packages
 ```
 
-Then restart Pi or run `/reload`.
+Restart Pi or run `/reload` after installation.
 
 ## Usage
 
-Type **`/sync`** in Pi. There are no CLI subcommands — everything goes through the interactive menu:
+Run `/sync`. The interactive menu contains:
 
-| Menu item | What it does |
-|-----------|----------------|
-| ☁️ **Upload Backup (Backup to cloud)** | Zip current config and upload to WebDAV |
-| 📥 **Download Backup (Restore from cloud)** | List remote backups, download one, restore with confirmation |
-| ⚙️ **Configure Sync Settings** | WebDAV URL / user / password, and what to include |
-| ❌ **Cancel** | Leave the menu |
+- **Back Up All** / **Restore All (latest)**
+- Upload or restore **Pi Backup**
+- Upload or restore **Skills Backup**
+- Upload or restore **Sessions Archive**
+- Configure backup settings
+- Switch the menu between English and Chinese
 
-Keyboard hints (as shown in the TUI): `↵` select · `↑↓` navigate · `Esc` cancel.
+The first run opens a WebDAV setup wizard when the URL, username, or password is missing.
 
-### First-time setup
+## Archive model
 
-```bash
-# 1. Install
-pi install git:github.com/wuyaos/pi-packages
+### Pi backup
 
-# 2. Open the menu (first run starts the setup wizard if WebDAV is empty)
-/sync
+The Pi archive packs `~/.pi/agent` directly. Its default blacklist is:
 
-# 3. If needed: Configure Sync Settings
-#    enter URL / user / password
-#    tip: set password to $PI_WEBDAV_PASS and export that env var
+```json
+["npm", "git", "sessions", "state", "tmp", "webui-rpc-supervisor", "vstack"]
+```
+
+This keeps configuration and extension state while excluding installed package sources, temporary extension caches, sessions (archived separately), workspace history, background-task state, and Web UI RPC runtime sockets. `config/sync.json` is included unless explicitly blacklisted.
+
+Archive name:
 
-# 4. On your main machine → Upload Backup (Backup to cloud)
-# 5. On a new machine (after install + configure) → Download Backup (Restore from cloud)
+```text
+backup/pi/pi_agent_<platform>_<timestamp>.tar.xz
 ```
 
-### What gets synced
+### Shared skills backup
 
-| Component | Default | Notes |
-|-----------|---------|-------|
-| Config | ON | `models.json`, `settings.json`, `auth.json` |
-| Skills | ON | entire `~/.pi/agent/skills` |
-| Extensions | ON | `~/.pi/agent/extensions` (the sync plugin itself is excluded from the zip) |
-| Sessions | OFF | per-project session history under `~/.pi/agent/sessions/`; pick which projects to include under **Configure Sync Settings → Session Projects** |
+`~/.agents/skills` is stored in a separate archive and is disabled by default.
 
-Toggle any of these under **Configure Sync Settings**.
+```text
+backup/skills/agent_skills_<timestamp>.tar.xz
+```
 
-### Sessions (optional)
+### Session archives
 
-Session history is organized by project cwd under `~/.pi/agent/sessions/<projectDir>/`. The **Session Projects** submenu lists every project directory found on this machine and lets you check the ones you want to back up.
+Sessions are archived by project. There is no live synchronization or `_latest.json` marker.
 
-- Turn on **Backup Sessions** in **Configure Sync Settings**.
-- Open **Session Projects** and toggle projects on/off (use **Select All** / **Reset list** for convenience).
-- List mode (toggleable):
-  - **Whitelist**: only checked projects are backed up; an empty list backs up **nothing**.
-  - **Blacklist**: checked projects are skipped; an empty list backs up **everything**.
-- On restore, session files are *merged* into the local `~/.pi/agent/sessions/` — session file names are unique (timestamp + uuid), so restoring never overwrites or deletes your local sessions.
+```text
+backup/sessions/<projectDir>/sessions_<platform>_<timestamp>.tar.xz
+```
+
+Project selection supports:
 
-> Note: project directory names encode the project path, so a backup made on one machine only restores into the same project path on another machine.
+- **Whitelist**: only listed projects are archived; an empty list means none.
+- **Blacklist**: listed projects are excluded; an empty list means all projects.
 
-### Backup filename
+When `backupOnExit` is enabled, Pi archives the current allowed project during `session_shutdown`. Manual session backup remains available from `/sync`.
 
-Archives look like:
+## WebDAV layout
 
 ```text
-pi_sync_backup_2026-7-14_20260714120000_windows11.zip
+<webdavUrl>/
+└── backup/
+    ├── pi/
+    │   └── pi_agent_<platform>_<timestamp>.tar.xz
+    ├── skills/
+    │   └── agent_skills_<timestamp>.tar.xz
+    └── sessions/
+        └── <projectDir>/
+            └── sessions_<platform>_<timestamp>.tar.xz
+```
+
+`maxBackups` is enforced independently in each backup directory. `0` keeps every archive.
+
+## Configuration
+
+Configuration is stored at `~/.pi/agent/config/sync.json`:
+
+```json
+{
+  "webdavUrl": "https://example.com/dav/pi",
+  "webdavUser": "user",
+  "webdavPass": "$PI_WEBDAV_PASS",
+  "language": "en",
+  "backupProviders": true,
+  "backupSessions": true,
+  "backupAgentSkills": false,
+  "piExcludePaths": ["npm", "git", "sessions", "state", "tmp", "webui-rpc-supervisor", "vstack"],
+  "backupOnExit": true,
+  "sessionProjectMode": "blacklist",
+  "sessionProjects": [],
+  "maxBackups": 10
+}
 ```
 
-The trailing platform tag (`windows11` / `windows10` / `macos` / `linux`) shows which host created the backup.
+The password may reference an environment variable (`$PI_WEBDAV_PASS`). When `language` is absent, pi-sync uses `settings.json → piSwitch.language` and falls back to English.
 
-### Safety on restore
+## Restore behavior and safety
 
-- Existing config files get a timestamped `.bak` copy before overwrite
-- Existing skills / extensions folders are renamed to `*-backup-<timestamp>` before replace/merge
-- Restore shows a plan and asks for confirmation
-- After a successful restore you can reload the agent runtime to apply skills/extensions
+- Every archive path is checked for absolute paths and traversal.
+- Symlinks and non-regular filesystem nodes are rejected before extraction.
+- Archives are extracted to a temporary directory before merging.
+- Restore refuses symbolic links or type conflicts in destination paths.
+- Pi restore only touches files present in the archive; excluded directories remain unchanged.
+- Skills restore moves the existing `~/.agents/skills` to a timestamped backup first.
+- Session restore merges files into `~/.pi/agent/sessions`.
+- Pi restore shows a plan and offers `/reload` afterward.
 
-## Bootstrap (new Windows machine, no Pi yet)
+Treat archives as sensitive: Pi backups may contain WebDAV credentials, API keys, provider settings, and other secrets.
 
-If Pi is not installed yet, you can still pull the latest zip with the helper script:
+## New Windows machine
+
+`pi-bootstrap.ps1` downloads the latest archive from `backup/pi/` and merges it into `%USERPROFILE%\.pi\agent`:
+
+> **Trusted archives only:** this bootstrap helper does not perform pi-sync's TypeScript path and link validation. Use `/sync` restore for normal recovery, and use the script only with a trusted WebDAV endpoint and archive.
 
 ```powershell
-# Prefer env vars so secrets never land in shell history
-$env:PI_WEBDAV_URL  = "https://your-webdav.example/dav/Pi"
-$env:PI_WEBDAV_USER = "your-user"
-$env:PI_WEBDAV_PASS = "your-app-password"
+$env:PI_WEBDAV_URL  = "https://example.com/dav/pi"
+$env:PI_WEBDAV_USER = "user"
+$env:PI_WEBDAV_PASS = "app-password"
 .\pi-bootstrap.ps1
 ```
 
-Or one-liner placeholders (replace before running):
+The script is intended for trusted archives and new-machine bootstrap. Install/update packages afterward so excluded `npm/` and `git/` trees are rebuilt.
 
-```powershell
-$url="https://your-webdav.example/dav/Pi"; $user="your-user"; $pass="your-app-password"
-$pair="$user`:$pass"; $auth=[Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
-$resp=Invoke-RestMethod -Uri $url -Method PROPFIND -Headers @{Authorization="Basic $auth";Depth="1"} -ContentType "application/xml"
-$files=([regex]'<d:href>([^<]+)</d:href>').Matches($resp) | %{$_.Groups[1].Value} | ?{$_ -match "pi_sync_backup_.*\.zip$"} | Sort-Object -Descending
-$latest=$files[0]; $name=Split-Path $latest -Leaf
-Invoke-WebRequest -Uri "$url/$name" -Headers @{Authorization="Basic $auth"} -OutFile "$env:TEMP\$name"
-```
+## Troubleshooting
 
-Then install Pi and use **Download Backup** from `/sync` for future updates.
+| Symptom | Fix |
+|---|---|
+| HTTP 401 / 403 | Verify the WebDAV URL and use an app-specific password. |
+| PROPFIND fails | Ensure the server supports WebDAV `PROPFIND` with `Depth: 1`. |
+| tar errors | Install a `tar` implementation with xz support. |
+| Exit backup is skipped | Check `backupOnExit`, `backupSessions`, project mode/list, and WebDAV credentials. |
+| Packages missing after Pi restore | Re-run `pi update --extensions` or reinstall packages from `settings.json`. |
 
-## Security
+## Development
 
-- WebDAV credentials are stored locally in `~/.pi/agent/sync_config.json`
-- Prefer **app-specific passwords** (not your main account password)
-- Prefer env-var references: set password to `$PI_WEBDAV_PASS` in the UI, then export that variable in your shell profile
-- Backups may include `auth.json` / API keys if those options are enabled — treat the WebDAV folder as sensitive
-- Never commit real WebDAV URLs with credentials into git
+```bash
+cd /mnt/d/work/project/person/pi-packages
+node --import tsx --test pi-sync/extensions/sync/*.test.ts
+npm run typecheck
+```
 
-## Troubleshooting
+The monorepo typecheck may report unrelated errors from other packages; pi-sync-specific errors are identified by paths beginning with `pi-sync/`.
 
-| Symptom | Fix |
-|---------|-----|
-| HTTP 401 / 403 | Check user/password; use app password; confirm URL includes the correct DAV path |
-| PROPFIND fails / empty list | Server may block PROPFIND; try another WebDAV provider; ensure Depth:1 is allowed |
-| tar / zip errors | Need a working `tar` on PATH (Windows 10+ has one; Git Bash / WSL also fine) |
-| Restore overwrote something | Look for `*.bak-*` files and `skills-backup-*` / `extensions-backup-*` folders next to the agent dir |
-| Plugin missing after restore | Re-run `pi install git:github.com/wuyaos/pi-packages` — the sync package excludes itself from the archive |
+### WebDAV smoke test
 
-## Structure
+The committed smoke harness creates uniquely named temporary Pi and session archives, uploads/list/downloads/validates them, then deletes them. It never prints credentials. It is intentionally write-protected:
 
-```text
-pi-sync/
-  package.json
-  LICENSE
-  README.md
-  README.zh-CN.md
-  pi-bootstrap.ps1
-  docs/
-    sync-menu.png       # /sync menu screenshot
-  extensions/
-    sync/
-      index.ts          # /sync command
-    _shared/
-      json-io.ts
-      enhanced-select.ts
-      spawn.ts
-      fetch-utils.ts
-      box-drawing.ts
+```bash
+cd /mnt/d/work/project/person/pi-packages
+PI_SYNC_SMOKE_WRITE=1 bash --noprofile --norc pi-sync/scripts/verify.sh
 ```
 
+`verify.sh` also runs the unit tests, strict pi-sync typecheck, extension-load check, package whitelist check, and diff check. It uses `~/.pi/agent/config/sync.json`; optionally set `PI_SYNC_SMOKE_PROJECT` to a permitted local session directory name (such as `--home-user--`).
+
 ## Changelog
 
-### v1.0.1
+### v1.2.0
+
+- Replace live synchronization with versioned archive-only backup/restore
+- Add direct Pi-home tar backup with blacklist exclusions
+- Separate Pi, shared skills, and per-project session archives
+- Add exit-time session archiving and manual all-category backup/restore
+- Add English/Chinese menu switching
+- Add streamed WebDAV transfer, config caching, and archive/restore safety checks
+- Remove live sync, interval sync, custom-path, memory, and legacy monolithic code
+
+### v1.1.1
 
-- Tag backup zip names with host platform (`windows11` / `macos` / `linux` / …)
-- Remove example credentials from bootstrap script comments
-- Add MIT `LICENSE` and expand README (security, restore safety, troubleshooting, menu screenshot)
+- Cache WebDAV directory creation and loaded configuration to reduce repeated I/O
 
 ### v1.0.0
 
-- Initial public release: interactive `/sync` menu over WebDAV
-  - Upload Backup · Download Backup · Configure Sync Settings
-- Windows bootstrap helper script
+- Initial WebDAV backup/restore release
 
 ## License
 
 MIT — see [LICENSE](./LICENSE).
-
-## Acknowledgements
-
-This open-source project is linked and recognized by the [LINUX DO](https://linux.do) community.