@narumitw/pi-sync 0.24.0 → 0.28.0

package/README.md

@@ -8,19 +8,17 @@ It syncs automatically by default when Pi starts, then uses immutable snapshot b
 
 ## ✨ 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`
-  - `APPEND_SYSTEM.md`
-  - `skills/`, `prompts/`, `themes/`, and `extensions/`
+- Opens every pi-sync action from the bare `/sync` menu and keeps direct `help`, `init`, `config`, `files`, `status`, `diff`, `doctor`, `push`, `pull`, `sync`, `history`, `rollback`, and `unlock` subcommands for automation and advanced flags.
+- Uses `/sync files` to choose which top-level Pi files and recursive directory groups are managed by this machine.
+- Syncs selected, allowlisted Pi configuration from `~/.pi/agent`:
+  - `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` when `syncSessions` is enabled
 - 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.
+- Runs `/sync 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.
@@ -48,7 +46,7 @@ pi -e ./extensions/pi-sync
 Run:
 
 ```text
-/pisync init
+/sync init
 ```
 
 Then edit:
@@ -71,6 +69,17 @@ Example:
   "profile": "default",
   "prefix": "pi-sync",
   "autoSync": true,
+  "syncFiles": [
+    "settings.json",
+    "keybindings.json",
+    "models.json",
+    "AGENTS.md",
+    "APPEND_SYSTEM.md",
+    "skills",
+    "prompts",
+    "themes",
+    "extensions"
+  ],
   "syncSessions": false,
   "extraFiles": []
 }
@@ -91,7 +100,13 @@ export PI_SYNC_AUTO_SYNC="true"
 export PI_SYNC_SESSIONS="false" # opt in with true to sync Pi conversation JSONL files
 ```
 
-Set `extraFiles` to additional top-level file names to include beyond the default allowlist. Machines without a matching `extraFiles` entry preserve those remote files but do not apply or delete them locally.
+Run `/sync files` in TUI mode to edit `syncFiles`, `syncSessions`, and `extraFiles` with a searchable selector. Enter or Space toggles an item and Escape closes the screen. Each successful change is saved immediately to `pi-sync.local.json`, preserving unknown fields through an atomic replacement with `0600` permissions on POSIX. No network sync starts until the next manual `push`, `pull`, or `sync`, or the existing automatic sync lifecycle.
+
+`syncFiles` accepts the built-in names shown above and has no environment-variable override. Directory names select the complete recursive group. Omitting `syncFiles` preserves the legacy default of selecting every built-in item; an empty array is valid and means this machine manages none of them. Unknown values make configuration validation fail instead of silently narrowing the selection.
+
+The selector always shows built-in items, even when they are absent locally, so another machine can provide them on pull. It also shows safe top-level regular files found locally and configured `extraFiles` that may only exist remotely. It excludes directories, symlinks, reserved names, and denylisted names. You can still edit `extraFiles` manually to select additional safe top-level file names.
+
+An unselected item is unmanaged by this machine: pi-sync does not collect, compare, pull, overwrite, or delete its local content, and pushes preserve its existing remote snapshot content for other machines. This applies to built-ins, directory groups, sessions, and extra files. Selecting nothing therefore does not delete unmanaged local or remote files.
 
 `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, assumed roles, or S3-compatible providers that issue short-lived credentials.
 
@@ -103,7 +118,7 @@ pi-sync also reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TO
 
 `syncSessions` defaults to `false`. Set it to `true`, or set `PI_SYNC_SESSIONS=true`, to include Pi's configured session JSONL files in snapshots. pi-sync uses `PI_CODING_AGENT_SESSION_DIR`, Pi's `sessionDir` setting, or the default `${PI_CODING_AGENT_DIR:-~/.pi/agent}/sessions/**/*.jsonl` storage. Empty or misspelled `PI_SYNC_SESSIONS` values stay disabled. Only JSONL session files are included; other session-directory files and denylisted paths such as `.env*`, `.pisync`, `node_modules`, and names containing `token` or `secret` are ignored.
 
-Session sync is snapshot-based, not live collaboration. If the same session changes on two machines, `/pisync sync` uses the same conflict rules as settings sync and skips when both local and remote changed. Run `/pisync diff`, then choose `/pisync pull --force` or `/pisync push --force` if needed.
+Session sync is snapshot-based, not live collaboration. If the same session changes on two machines, `/sync sync` uses the same conflict rules as settings sync and skips when both local and remote changed. Run `/sync diff`, then choose `/sync pull --force` or `/sync push --force` if needed.
 
 When both `autoSync` and `syncSessions` are enabled, pi-sync syncs on startup and attempts a quiet session push on shutdown when local files changed. Startup session pulls happen after Pi has already selected the current session, so restart Pi or resume a pulled session to use newly synced conversations. If the remote changed first, the shutdown push is skipped with a warning instead of overwriting it.
 
@@ -111,32 +126,45 @@ Session files can contain prompts, model output, tool results, file paths, image
 
 ## 🚀 Usage
 
+Run `/sync` without arguments to open the interactive menu containing every pi-sync action. The **files — Choose synced files** action opens the persistent selector. Choosing rollback asks for the snapshot id before showing the existing confirmation. Cancelling either action leaves unmodified state unchanged; file-selection changes that were already saved are not rolled back when the screen closes.
+
 ```text
-/pisync config
-/pisync doctor
-/pisync status
-/pisync diff
-/pisync push
-/pisync pull
-/pisync sync
-/pisync history
-/pisync rollback <snapshot-id>
-/pisync unlock --stale
+/sync
 ```
 
+The same actions remain available as direct routes for automation, non-interactive use, and advanced flags:
+
+```text
+/sync help
+/sync init
+/sync config
+/sync files
+/sync status
+/sync diff
+/sync doctor
+/sync push
+/sync pull
+/sync sync
+/sync history
+/sync rollback <snapshot-id>
+/sync unlock --stale
+```
+
+Bare `/sync` reports command usage when an interactive UI is unavailable; use a direct route for the desired operation. Outside TUI mode, `/sync files` does not open a custom component and instead reports the effective selection, config path, and manual editing fields. When `PI_SYNC_SESSIONS` is set, the sessions row is read-only and identifies the environment override.
+
 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`.
+- `--stale`: remove a stale local lock with `/sync unlock --stale`.
 
 ## 🔄 Automatic sync
 
-`autoSync` defaults to `true`. When Pi starts, pi-sync runs the same conservative decision logic as `/pisync sync`:
+`autoSync` defaults to `true`. When Pi starts, pi-sync runs the same conservative decision logic as `/sync 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`
+- first sync with existing local settings and a different remote snapshot → skip and show a warning so you manually choose `/sync pull` or `/sync 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
@@ -171,13 +199,14 @@ pi-sync/
 
 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.
+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 `/sync 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.
+- Unselected built-in files, directory groups, sessions, and extra files are unmanaged locally and preserved remotely; selecting nothing does not delete them.
 - With `syncSessions`/`PI_SYNC_SESSIONS` disabled, pi-sync does not collect or apply local Pi sessions, though settings-only pushes may preserve session files already present in remote snapshots. It never syncs 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 Pi process is already syncing on the same machine, destructive commands stop at the local lock. `/sync 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.
@@ -187,7 +216,10 @@ Before updating `latest.json`, pi-sync re-reads the current pointer and rejects
 ```txt
 extensions/pi-sync/
 ├── src/
-│   ├── sync.ts        # Pi entrypoint and command orchestration
+│   ├── index.ts       # Pi package entrypoint
+│   ├── sync.ts        # Extension registration and command orchestration
+│   ├── file-selection.ts # Persistent SettingsList selector
+│   ├── sync-policy.ts # Shared built-in catalog and path policy
 │   └── *.ts           # Package-local config, snapshot, path, and S3 modules
 ├── README.md
 ├── LICENSE
@@ -195,12 +227,12 @@ extensions/pi-sync/
 └── package.json
 ```
 
-Only `sync.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `sync.ts`; the other source modules are internal. The package exposes its Pi extension through `package.json`:
 
 ```json
 {
   "pi": {
-    "extensions": ["./src/sync.ts"]
+    "extensions": ["./src/index.ts"]
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.24.0",
+	"version": "0.28.0",
 	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",
@@ -20,7 +20,7 @@
 	],
 	"pi": {
 		"extensions": [
-			"./src/sync.ts"
+			"./src/index.ts"
 		]
 	},
 	"scripts": {
@@ -28,11 +28,20 @@
 		"format": "biome check --write .",
 		"typecheck": "tsc --noEmit"
 	},
+	"dependencies": {
+		"proper-lockfile": "^4.1.2"
+	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.3",
 		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@earendil-works/pi-tui": "0.80.10",
+		"@types/proper-lockfile": "^4.1.4",
 		"typescript": "7.0.2"
 	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",

package/src/command.ts

@@ -1,23 +1,31 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { CommandArgumentCompletion, CommandOptions } from "./types.js";
 
 const YES_FLAG_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ value: "--yes", label: "--yes", description: "Skip confirmation prompts" },
 	{ value: "-y", label: "-y", description: "Skip confirmation prompts" },
 ];
-const SYNC_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
-	{ value: "help", label: "help", description: "Show command usage" },
-	{ value: "init", label: "init", description: "Create local config template" },
-	{ value: "config", label: "config", description: "Show resolved configuration" },
-	{ value: "status", label: "status", description: "Show sync status" },
-	{ value: "diff", label: "diff", description: "Show local/remote diff" },
-	{ value: "doctor", label: "doctor", description: "Check config, secrets, and lock state" },
-	{ value: "push", label: "push", description: "Upload local settings" },
-	{ value: "pull", label: "pull", description: "Apply remote settings" },
-	{ value: "sync", label: "sync", description: "Push or pull as needed" },
-	{ value: "history", label: "history", description: "Show recent remote snapshots" },
-	{ value: "rollback", label: "rollback", description: "Apply a previous snapshot" },
-	{ value: "unlock", label: "unlock", description: "Remove a stale local lock" },
-];
+export const SYNC_COMMANDS = [
+	{ name: "help", description: "Show command usage" },
+	{ name: "init", description: "Create local config template" },
+	{ name: "config", description: "Show resolved configuration" },
+	{ name: "files", description: "Choose synced files" },
+	{ name: "status", description: "Show sync status" },
+	{ name: "diff", description: "Show local/remote diff" },
+	{ name: "doctor", description: "Check config, secrets, and lock state" },
+	{ name: "push", description: "Upload local settings" },
+	{ name: "pull", description: "Apply remote settings" },
+	{ name: "sync", description: "Push or pull as needed" },
+	{ name: "history", description: "Show recent remote snapshots" },
+	{ name: "rollback", description: "Apply a previous snapshot", usageSuffix: " <snapshot>" },
+	{ name: "unlock", description: "Remove a stale local lock", usageSuffix: " --stale" },
+] as const;
+
+export type SyncCommandName = (typeof SYNC_COMMANDS)[number]["name"];
+
+const SYNC_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = SYNC_COMMANDS.map(
+	({ name, description }) => ({ value: name, label: name, description }),
+);
 const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]> = {
 	push: [
 		...YES_FLAG_COMPLETIONS,
@@ -36,7 +44,10 @@ const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]
 };
 
 export function splitArgs(input: string) {
-	return input.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((arg) => arg.replace(/^['"]|['"]$/g, "")) ?? [];
+	return (
+		input.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((arg) => arg.replace(/^['"]|['"]$/g, "")) ??
+		[]
+	);
 }
 
 export function parseOptions(args: string[]): CommandOptions {
@@ -88,10 +99,42 @@ export function completeSyncArguments(argumentPrefix: string): CommandArgumentCo
 		: null;
 }
 
+export function syncMenuOptions() {
+	return SYNC_COMMANDS.map(({ name, description }) => `${name} — ${description}`);
+}
+
+export function syncCommandFromMenuOption(option: string): SyncCommandName | undefined {
+	return SYNC_COMMANDS.find(({ name, description }) => option === `${name} — ${description}`)?.name;
+}
+
+export async function resolveSyncCommand(input: string, ctx: ExtensionCommandContext) {
+	const [subcommand, ...rest] = splitArgs(input);
+	if (subcommand) return { subcommand, rest };
+	if (!ctx.hasUI) {
+		ctx.ui.notify(usage(), "info");
+		return undefined;
+	}
+
+	const selectedOption = await ctx.ui.select("pi-sync", syncMenuOptions());
+	const selected = selectedOption ? syncCommandFromMenuOption(selectedOption) : undefined;
+	if (!selected) return undefined;
+	if (selected !== "rollback") return { subcommand: selected, rest: [] };
+
+	const target = (await ctx.ui.input("Rollback snapshot", "snapshot id"))?.trim();
+	if (!target) {
+		ctx.ui.notify("Rollback cancelled.", "info");
+		return undefined;
+	}
+	return { subcommand: selected, rest: [target] };
+}
+
 export function usage() {
+	const commands = SYNC_COMMANDS.map(
+		(command) => `${command.name}${"usageSuffix" in command ? command.usageSuffix : ""}`,
+	).join(", ");
 	return [
-		"Usage: /pisync <command>",
-		"Commands: init, config, status, diff, doctor, push, pull, sync, history, rollback <snapshot>, unlock --stale",
-		"Config: set PI_SYNC_ENDPOINT, PI_SYNC_BUCKET, PI_SYNC_ACCESS_KEY_ID, PI_SYNC_SECRET_ACCESS_KEY, optional PI_SYNC_SESSION_TOKEN, PI_SYNC_SESSIONS/syncSessions, region/profile/prefix, or edit ~/.pi/agent/pi-sync.local.json (or $PI_CODING_AGENT_DIR/pi-sync.local.json when PI_CODING_AGENT_DIR is set).",
+		"Usage: /sync <command>",
+		`Commands: ${commands}`,
+		"Config: set PI_SYNC_ENDPOINT, PI_SYNC_BUCKET, PI_SYNC_ACCESS_KEY_ID, PI_SYNC_SECRET_ACCESS_KEY, optional PI_SYNC_SESSION_TOKEN, PI_SYNC_SESSIONS/syncSessions, region/profile/prefix, or edit syncFiles/extraFiles in ~/.pi/agent/pi-sync.local.json (or $PI_CODING_AGENT_DIR/pi-sync.local.json when PI_CODING_AGENT_DIR is set).",
 	].join("\n");
 }