@lisang233/pi-sync 0.1.2 → 0.2.0

package/README.md

@@ -1,18 +1,30 @@
 # 🔄 pi-sync
 
-A personal Pi extension that syncs Pi configuration through **Git** with git-style `fetch`/`pull`/`merge`/`push`, a single config file, and conflict resolution inside the Pi UI.
+A personal Pi extension that syncs Pi configuration through **Git** using the real
+file tree — each synced file lives in the repo as its actual file, so conflict
+detection and merging are handled by git itself.
 
-> **Experimental.** This is a from-scratch rewrite of the classic pi-sync flow: one config file, one git remote, content-level diffs, three-way merges, and deliberate commands that never move your files without asking.
+> **Experimental.** A from-scratch rewrite that treats the remote repo as a
+> genuine file tree instead of a single packed snapshot. Conflicts resolve
+> through git's native three-way merge; the base is git's real merge-base, so a
+> fresh machine or a force-pushed remote never causes a false conflict.
 
 ## ✨ Features
 
-- **Single config, direct connection** — one `pi-sync.json` points at one git remote and branch. No two-level setup/connection model.
-- **Observe-only automatic** — `automatic: true` fetches at session start and shows a persistent status-bar indicator (up-to-date / ahead / behind / conflict). It never pushes, pulls or merges on its own.
-- **Git-style pull** — `/sync pull` fetches and merges. Clean changes apply directly; divergence without a flag writes nothing; `--force` overwrites local files; `--merge` opens in-UI conflict resolution.
-- **In-UI conflict resolution** — divergent edits are parsed into conflict blocks and resolved one at a time (keep local / keep remote / type a replacement). Progress persists across sessions; `/sync merge` resumes, `/sync merge --abort` restores the pre-merge backup.
-- **JSON-aware merging** — single-line `settings.json`/`keybindings.json`/`models.json` merge field-wise, so formatting or an unrelated field change doesn't conflict.
-- **Closed-loop status** — `/sync status` shows the effective config, the sync state, any in-progress merge, and the exact next step; `/sync status --diff` shows the content-level diff (JSON pretty-printed, secrets masked, bounded).
-- **No stored credentials** — Git uses your existing SSH/credential-helper setup; the config file never holds tokens.
+- **Real file tree, not a blob** — the remote branch holds `settings.json`,
+  `skills/…`, `prompts/…` as real files. Git does per-path, per-line detection
+  and merging; no hand-rolled snapshot engine.
+- **Git-native conflict detection** — the base is git's merge-base, not a local
+  anchor file. A new machine's first `pull` adopts the remote cleanly; a
+  rewritten remote doesn't spuriously conflict.
+- **Git-native three-way merge** — `/sync pull` merges the remote branch into
+  the local side. Divergent edits produce real conflict markers in the actual
+  files; `/sync merge` completes once you resolve them, `--abort` discards.
+- **Deliberate commands** — nothing moves your files without being asked;
+  `automatic` only observes at session start.
+- **Sensible defaults** — one `pi-sync.json` points at a git remote and branch,
+  an `include` list, and `automatic`.
+- **No stored credentials** — git uses your existing SSH/credential helper.
 
 ## 📦 Install
 
@@ -32,10 +44,10 @@ pi install npm:@lisang233/pi-sync
 /sync init         # first-run wizard: remote, branch, include, automatic
 /sync config       # view and edit the config at any time
 /sync status       # config + sync state + next step (--diff for content)
-/sync fetch        # pull the remote snapshot without applying
-/sync pull         # fetch + merge (--force overwrites, --merge resolves)
-/sync merge        # continue an in-progress merge (--abort discards)
-/sync push         # publish local snapshot (--force overwrites remote)
+/sync fetch        # pull the remote tree without applying
+/sync pull         # fetch + merge (--force overwrites local)
+/sync merge        # complete an in-progress merge (--abort discards)
+/sync push         # publish the local tree (--force overwrites remote)
 ```
 
 ## ⚙️ Settings
@@ -60,9 +72,18 @@ The config lives at `~/.pi/agent/pi-sync.json` (agent dir honors `PI_CODING_AGEN
 }
 ```
 
-- `include` selects which agent-dir paths sync. The defaults are `settings.json`, `keybindings.json`, `models.json`, `skills`, `prompts`, `themes`, `extensions`, and `extension-settings`. Sessions and `AGENTS.md` are intentionally not included by default. Edit it any time with `/sync config`.
-- `automatic` only controls whether a non-destructive fetch runs at session start; the status-bar indicator always reflects the last known state.
-- State lives under `<agent-dir>/pi-sync/` (a mirror git repo, `state.json`, `merge-session/`, and backups).
+- `include` selects which agent-dir paths sync. The defaults are `settings.json`,
+  `keybindings.json`, `models.json`, `skills`, `prompts`, `themes`, `extensions`,
+  and `extension-settings`. Sessions and `AGENTS.md` are not synced by default.
+- `automatic` only controls whether a non-destructive `fetch` runs at session
+  start; the status-bar indicator always reflects the last known state.
+- A mirror git repo lives under `<agent-dir>/pi-sync/mirror/` and is checked out
+  on the configured branch.
+
+> Note: with a real file tree, any sensitive token in a synced config is stored
+> in the git repo as plaintext (like any dotfile repo). It is not hidden, and it
+> is not encrypted. Use a private remote and a credential helper that keeps
+> `~/.git-credentials` out of the repo.
 
 ## 🗂️ Package layout
 
@@ -73,16 +94,11 @@ src/
   config.ts         single-file config load/validate/save
   config-ui.ts      interactive config editor (view + edit fields)
   paths.ts          agent-dir paths and include normalization
-  git.ts            git subprocess backend (fetch/push/show/merge-file)
-  snapshot.ts       scan include paths into a hashed snapshot
-  state.ts          last-applied snapshot + remote revision
-  status.ts         sync-state derivation and indicator text
-  merge-session.ts  persistent conflict-resolution session store
-  conflict.ts       diff3 marker parsing and resolved-text splicing
-  resolve.ts        structured block-by-block conflict resolver
+  git.ts            git subprocess backend (real-file-tree fetch/push/merge)
+  tree.ts           sync agent-dir <-> mirror work tree (real files)
+  status.ts         sync-state derivation (git merge-base) and indicator
   diff.ts           content-level diff with JSON formatting and secret masking
-  merge.ts          three-way merge (JSON field-wise + git merge-file fallback)
-  operations.ts     status/push/pull/fetch/merge
+  operations.ts     status/push/pull/fetch/merge orchestration
   wizard.ts         first-run setup wizard
 test/               vitest unit + local-bare-repo end-to-end tests
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lisang233/pi-sync",
-	"version": "0.1.2",
+	"version": "0.2.0",
 	"description": "Personal Pi extension that syncs Pi configuration through Git with background auto-sync and git-style fetch/merge conflict handling.",
 	"type": "module",
 	"license": "MIT",

package/src/config.ts

@@ -27,8 +27,9 @@ export const DEFAULT_CONFIG: SyncConfig = {
 	automatic: true,
 };
 
-export const SNAPSHOT_FILE = "snapshot.json";
-export const BACKUP_DIR = "backups";
+export function shortId(value: string): string {
+	return value.length > 10 ? value.slice(0, 10) : value;
+}
 
 export function configPath(): string {
 	return path.join(agentDir(), CONFIG_FILE_NAME);
@@ -42,14 +43,6 @@ export function mirrorRepoDir(): string {
 	return path.join(stateDir(), "mirror");
 }
 
-export function snapshotFilePath(): string {
-	return path.join(mirrorRepoDir(), "pi-sync", SNAPSHOT_FILE);
-}
-
-export function backupRootDir(): string {
-	return path.join(stateDir(), BACKUP_DIR);
-}
-
 export async function loadConfig(): Promise<SyncConfig> {
 	let text: string;
 	try {

package/src/diff.ts

@@ -1,5 +1,4 @@
 import { createTwoFilesPatch } from "diff";
-import { fileHashMap, type Snapshot, snapshotFileContent } from "./snapshot.js";
 
 const HUNK_CONTEXT_LINES = 2;
 const MAX_HUNK_FILE_BYTES = 1024 * 1024;
@@ -15,38 +14,31 @@ const SECRET_PATTERNS = [
 	/gh[pousr]_[A-Za-z0-9_]{20,}/,
 ];
 
-export interface SnapshotDiffSummary {
+export interface DiffSummary {
 	changed: number;
 	added: number;
 	removed: number;
 	identical: boolean;
 }
 
-export function diffSummary(local: Snapshot, remote: Snapshot): SnapshotDiffSummary {
-	const localMap = fileHashMap(local);
-	const remoteMap = fileHashMap(remote);
-	const paths = [...new Set([...localMap.keys(), ...remoteMap.keys()])];
+/** Summarize the difference between two path→content maps (agent vs remote). */
+export function diffSummary(local: Map<string, string>, remote: Map<string, string>): DiffSummary {
+	const paths = new Set([...local.keys(), ...remote.keys()]);
 	let added = 0;
 	let removed = 0;
 	let changed = 0;
 	for (const filePath of paths) {
-		if (!localMap.has(filePath)) added += 1;
-		else if (!remoteMap.has(filePath)) removed += 1;
-		else if (localMap.get(filePath) !== remoteMap.get(filePath)) changed += 1;
+		if (!local.has(filePath)) added += 1;
+		else if (!remote.has(filePath)) removed += 1;
+		else if (local.get(filePath) !== remote.get(filePath)) changed += 1;
 	}
 	return { changed, added, removed, identical: added === 0 && removed === 0 && changed === 0 };
 }
 
-/** Content-level diff of local vs remote with JSON pretty-print, masking, and bounds. */
-export function formatSnapshotDiff(local: Snapshot, remote: Snapshot): string {
-	const localMap = fileHashMap(local);
-	const remoteMap = fileHashMap(remote);
-	const allPaths = [...new Set([...localMap.keys(), ...remoteMap.keys()])].sort();
-	const lines = [
-		`local: ${local.files.length} files`,
-		`remote: ${remote.createdAt} (${remote.files.length} files)`,
-		"",
-	];
+/** Content-level diff of local vs remote path→content maps (JSON pretty, masked, bounded). */
+export function formatDiff(local: Map<string, string>, remote: Map<string, string>): string {
+	const allPaths = [...new Set([...local.keys(), ...remote.keys()])].sort();
+	const lines = [`local: ${local.size} files`, `remote: ${remote.size} files`, ""];
 	let totalChanges = 0;
 	let hunkBudget = MAX_TOTAL_HUNK_LINES;
 	let truncated = false;
@@ -57,22 +49,22 @@ export function formatSnapshotDiff(local: Snapshot, remote: Snapshot): string {
 		if (hunks.at(-1) === TRUNCATED_MARKER) truncated = true;
 	};
 	for (const filePath of allPaths) {
-		if (!localMap.has(filePath)) {
+		if (!local.has(filePath)) {
 			lines.push(`Remote only: ${filePath}`);
 			totalChanges += 1;
 			if (hunkBudget <= 0) truncated = true;
-			else appendHunks(contentHunks("", fileText(remote, filePath), hunkBudget));
-		} else if (!remoteMap.has(filePath)) {
+			else appendHunks(contentHunks("", remote.get(filePath) ?? "", hunkBudget));
+		} else if (!remote.has(filePath)) {
 			lines.push(`Local only: ${filePath}`);
 			totalChanges += 1;
 			if (hunkBudget <= 0) truncated = true;
-			else appendHunks(contentHunks("", fileText(local, filePath), hunkBudget));
-		} else if (localMap.get(filePath) !== remoteMap.get(filePath)) {
+			else appendHunks(contentHunks("", local.get(filePath) ?? "", hunkBudget));
+		} else if (local.get(filePath) !== remote.get(filePath)) {
 			lines.push(`Different: ${filePath}`);
 			totalChanges += 1;
 			if (hunkBudget <= 0) truncated = true;
 			else {
-				const texts = diffTexts(fileText(remote, filePath), fileText(local, filePath));
+				const texts = diffTexts(remote.get(filePath), local.get(filePath));
 				appendHunks(contentHunks(texts.before, texts.after, hunkBudget));
 			}
 		}
@@ -82,10 +74,6 @@ export function formatSnapshotDiff(local: Snapshot, remote: Snapshot): string {
 	return lines.join("\n");
 }
 
-function fileText(snapshot: Snapshot, filePath: string): string {
-	return snapshotFileContent(snapshot, filePath) ?? "";
-}
-
 function diffTexts(before: string | undefined, after: string | undefined) {
 	const beforePretty = before !== undefined ? prettyJson(before) : undefined;
 	const afterPretty = after !== undefined ? prettyJson(after) : undefined;

package/src/extension.ts

@@ -3,7 +3,7 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { loadConfig } from "./config.js";
+import { loadConfig, type SyncConfig } from "./config.js";
 import { runConfigEditor } from "./config-ui.js";
 import * as operations from "./operations.js";
 import { syncBusyText } from "./status.js";
@@ -28,16 +28,17 @@ const USAGE = [
 	"  init                first-run setup wizard",
 	"  config              view and edit the config",
 	"  status              config + sync state + next step (--diff for content)",
-	"  fetch               fetch the remote snapshot without applying",
-	"  pull                fetch + merge (--force overwrites, --merge resolves)",
+	"  fetch               fetch the remote tree without applying",
+	"  pull                fetch + merge (--force overwrites local)",
 	"  merge               continue an in-progress merge (--abort discards)",
-	"  push                publish local snapshot (--force overwrites remote)",
+	"  push                publish local tree (--force overwrites remote)",
 	"  help                show this help",
 ].join("\n");
 
 export default function sync(pi: ExtensionAPI): void {
 	let sessionAbort = new AbortController();
 	let backgroundSync: BackgroundSync | undefined;
+	let backgroundPush: BackgroundSync | undefined;
 
 	const startBackgroundSync = (ctx: ExtensionContext, signal: AbortSignal) => {
 		// While the automatic fetch is in flight the indicator shows the busy
@@ -55,15 +56,40 @@ export default function sync(pi: ExtensionAPI): void {
 		backgroundSync = { settled };
 	};
 
-	const drainBackgroundSync = async (signal?: AbortSignal): Promise<void> => {
-		const current = backgroundSync;
+	// Publish in the background so the TUI stays interactive while git talks
+	// to the remote (fetch + push can take many seconds). The indicator shows
+	// "pushing…"; operations.push notifies the outcome when it settles.
+	const startBackgroundPush = (
+		ctx: ExtensionCommandContext,
+		config: SyncConfig,
+		force: boolean,
+		signal: AbortSignal,
+	) => {
+		ctx.ui.setStatus(STATUS_KEY, syncBusyText("push"));
+		const settled = (async () => {
+			try {
+				await operations.push(ctx, config, { force });
+			} catch (error) {
+				if (signal.aborted) return;
+				ctx.ui.setStatus(STATUS_KEY, undefined);
+				ctx.ui.notify(`pi-sync push failed: ${errorMessage(error)}`, "error");
+			}
+		})();
+		backgroundPush = { settled };
+	};
+
+	const drainBackgroundTasks = async (signal?: AbortSignal): Promise<void> => {
+		const tasks = [backgroundSync, backgroundPush];
 		backgroundSync = undefined;
-		if (!current) return;
-		try {
-			await (signal ? Promise.race([current.settled, waitForAbort(signal)]) : current.settled);
-		} catch {
-			// The shutdown deadline or a replacement aborted while draining; the
-			// background sync observes its own session signal and settles on its own.
+		backgroundPush = undefined;
+		for (const current of tasks) {
+			if (!current) continue;
+			try {
+				await (signal ? Promise.race([current.settled, waitForAbort(signal)]) : current.settled);
+			} catch {
+				// The shutdown deadline or a replacement aborted while draining; the
+				// background task observes its own session signal and settles on its own.
+			}
 		}
 	};
 
@@ -84,7 +110,18 @@ export default function sync(pi: ExtensionAPI): void {
 				);
 			}
 			try {
-				await handleCommand(args, ctx);
+				await handleCommand(args, ctx, async (pushCtx, config, force) => {
+					if (backgroundPush) {
+						pushCtx.ui.notify("A push is already in progress.", "warning");
+						return;
+					}
+					// Wait for the session-start automatic fetch so the two
+					// background tasks never contend on the mirror repo, then run
+					// the publish without blocking the TUI.
+					await drainBackgroundTasks();
+					if (sessionAbort.signal.aborted) return;
+					startBackgroundPush(pushCtx, config, force, sessionAbort.signal);
+				});
 			} catch (error) {
 				if (sessionAbort.signal.aborted) return;
 				ctx.ui.setStatus(STATUS_KEY, undefined);
@@ -98,7 +135,7 @@ export default function sync(pi: ExtensionAPI): void {
 		sessionAbort = new AbortController();
 		const signal = sessionAbort.signal;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
-		await drainBackgroundSync();
+		await drainBackgroundTasks();
 		try {
 			const config = await loadConfig();
 			if (signal.aborted) return;
@@ -126,7 +163,11 @@ async function runAutomaticSync(ctx: ExtensionContext, signal: AbortSignal): Pro
 	await operations.fetch(ctx, config, { quiet: true });
 }
 
-async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext): Promise<void> {
+async function handleCommand(
+	rawArgs: string,
+	ctx: ExtensionCommandContext,
+	runPush: (ctx: ExtensionCommandContext, config: SyncConfig, force: boolean) => Promise<void>,
+): Promise<void> {
 	const [first = "", ...restTokens] = rawArgs.trim().split(/\s+/u);
 	const subcommand = normalizeSubcommand(first);
 	if (subcommand === undefined || subcommand === "help") {
@@ -159,13 +200,10 @@ async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext): Pro
 			});
 			return;
 		case "push":
-			await operations.push(ctx, config, { force });
+			await runPush(ctx, config, force);
 			return;
 		case "pull":
-			await operations.pull(ctx, config, {
-				force,
-				merge: restTokens.some((token) => token === "--merge"),
-			});
+			await operations.pull(ctx, config, { force });
 			return;
 		case "fetch":
 			await operations.fetch(ctx, config);