@lisang233/pi-sync 0.2.1 → 0.2.3

package/README.md

@@ -18,8 +18,10 @@ detection and merging are handled by git itself.
   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.
+  the local side. Divergent edits keep local configuration protected while
+  holding conflicts in the mirror; `/sync mergetool` or `--ours`/`--theirs`
+  resolve them, and `/sync merge` validates (no markers, valid JSON) before
+  applying to local files.
 - **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,
@@ -46,7 +48,8 @@ pi install npm:@lisang233/pi-sync
 /sync status       # config + sync state + next step (--diff for content)
 /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 mergetool    # launch git mergetool for conflicts ([tool])
+/sync merge        # complete merge (--abort, --ours, --theirs)
 /sync push         # publish the local tree (--force overwrites remote)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lisang233/pi-sync",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"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",
@@ -16,6 +16,9 @@
 		"README.md",
 		"LICENSE"
 	],
+	"publishConfig": {
+		"access": "public"
+	},
 	"pi": {
 		"extensions": [
 			"./src/index.ts"

package/src/extension.ts

@@ -15,7 +15,17 @@ interface BackgroundSync {
 	settled: Promise<void>;
 }
 
-const COMMANDS = ["init", "status", "push", "pull", "fetch", "merge", "config", "help"] as const;
+const COMMANDS = [
+	"init",
+	"status",
+	"push",
+	"pull",
+	"fetch",
+	"merge",
+	"mergetool",
+	"config",
+	"help",
+] as const;
 
 type Subcommand = (typeof COMMANDS)[number];
 
@@ -30,7 +40,8 @@ const USAGE = [
 	"  status              config + sync state + next step (--diff for content)",
 	"  fetch               fetch the remote tree without applying",
 	"  pull                fetch + merge (--force overwrites local)",
-	"  merge               continue an in-progress merge (--abort discards)",
+	"  merge               complete merge (--abort, --ours, --theirs)",
+	"  mergetool           launch git mergetool for conflicts ([tool])",
 	"  push                publish local tree (--force overwrites remote)",
 	"  help                show this help",
 ].join("\n");
@@ -211,8 +222,15 @@ async function handleCommand(
 		case "merge":
 			await operations.merge(ctx, config, {
 				abort: restTokens.some((token) => token === "--abort"),
+				ours: restTokens.some((token) => token === "--ours"),
+				theirs: restTokens.some((token) => token === "--theirs"),
 			});
 			return;
+		case "mergetool": {
+			const tool = restTokens.find((token) => !token.startsWith("-"));
+			await operations.mergetool(ctx, config, tool);
+			return;
+		}
 		case "config":
 			await runConfigEditor(ctx.ui, config);
 			return;

package/src/git.ts

@@ -271,6 +271,25 @@ export async function readMergeBase(
 	return readFilesAt(base, options);
 }
 
+/** Read the content of a file at a specific git ref (e.g. "HEAD:settings.json"). */
+export async function readCommitFile(
+	ref: string,
+	relativePath: string,
+	options: GitRunOptions = {},
+): Promise<string | undefined> {
+	const repo = gitCwd();
+	try {
+		const out = await runGit(["show", `${ref}:${relativePath}`], {
+			cwd: repo,
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		});
+		return out.stdout;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Stage all changes (after grafting the local side) in the mirror work tree. */
 export async function stageAll(options: GitRunOptions = {}): Promise<void> {
 	await runGit(["add", "-A"], { cwd: gitCwd(), signal: options.signal });
@@ -346,7 +365,49 @@ export async function completeMerge(
 	options: GitRunOptions = {},
 ): Promise<boolean> {
 	await stageAll(options);
-	return commitSync(message, options);
+	const repo = gitCwd();
+	try {
+		await runGit(["commit", "--quiet", "-m", message], { cwd: repo, signal: options.signal });
+		return true;
+	} catch {
+		return !(await isMergeInProgress(options));
+	}
+}
+
+/** Check out our local version for all conflicted files in the mirror work tree. */
+export async function checkoutOurs(options: GitRunOptions = {}): Promise<void> {
+	await runGit(["checkout", "--ours", "--", "."], { cwd: gitCwd(), signal: options.signal });
+	await stageAll(options);
+}
+
+/** Check out their remote version for all conflicted files in the mirror work tree. */
+export async function checkoutTheirs(options: GitRunOptions = {}): Promise<void> {
+	await runGit(["checkout", "--theirs", "--", "."], { cwd: gitCwd(), signal: options.signal });
+	await stageAll(options);
+}
+
+/**
+ * Launch git mergetool interactively in the mirror work tree.
+ */
+export async function launchMergetool(tool?: string, options: GitRunOptions = {}): Promise<void> {
+	throwIfAborted(options.signal);
+	const repo = gitCwd();
+	const args = ["mergetool", "-y"];
+	if (tool && tool.trim().length > 0) {
+		args.push(`--tool=${tool.trim()}`);
+	}
+	await new Promise<void>((resolve, reject) => {
+		const child = spawn("git", args, {
+			cwd: repo,
+			stdio: process.stdin.isTTY ? "inherit" : ["ignore", "pipe", "pipe"],
+			windowsHide: false,
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve();
+			else reject(new Error(`git mergetool exited with status ${code ?? "unknown"}.`));
+		});
+	});
 }
 
 /** Abort an in-progress merge, restoring the work tree to the pre-merge state. */

package/src/operations.ts

@@ -1,3 +1,5 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import type {
 	ExtensionCommandContext,
 	ExtensionContext,
@@ -10,26 +12,34 @@ import { diffSummary, formatDiff } from "./diff.js";
 import {
 	abortMerge,
 	aheadBehind,
+	checkoutOurs,
+	checkoutTheirs,
 	commitSync,
 	completeMerge,
 	ensureBranch,
 	ensureMirror,
 	fetchRemote,
 	isMergeInProgress,
+	launchMergetool,
 	listConflictedPaths,
 	mergeRemote,
 	pushBranch,
+	readCommitFile,
 	readMergeBase,
 	readRemoteFiles,
 	readRemoteRevision,
 	resetHard,
 	stageAll,
 } from "./git.js";
+import { agentDir } from "./paths.js";
 import { classifyState, type StateClassify, syncIndicatorText } from "./status.js";
 import {
+	agentTarget,
 	collectAgentFiles,
 	copyMirrorToAgent,
 	graftAgentIntoMirror,
+	mirrorProjectedFiles,
+	mirrorTarget,
 	readAgentContents,
 } from "./tree.js";
 
@@ -116,7 +126,7 @@ function nextStepHint(info: StateClassify): string {
 		case "behind":
 			return "next: /sync pull to fetch and apply remote changes";
 		case "conflict":
-			return "next: /sync pull to merge, or /sync pull --force to overwrite local";
+			return "next: /sync merge (--ours, --theirs, or mergetool), or /sync pull --force to overwrite local";
 		case "unknown":
 			return "next: /sync fetch to check the remote";
 	}
@@ -209,10 +219,8 @@ export async function pull(
 	await commitLocalSide({ signal: ctx.signal });
 
 	const conflicted = await mergeRemote(config, { signal: ctx.signal });
-	await copyMirrorToAgent(config);
-	await refreshIndicator(ctx, config);
-
 	if (conflicted) {
+		await refreshIndicator(ctx, config);
 		const conflicts = await listConflictedPaths({ signal: ctx.signal });
 		let remoteRevision = "";
 		try {
@@ -220,13 +228,15 @@ export async function pull(
 		} catch {
 			// ignore
 		}
-		const message = `Merge conflict in ${conflicts.length} file(s). Resolve the markers, then /sync merge. (remote ${shortId(
+		const conflictList = conflicts.length > 0 ? ` (${conflicts.join(", ")})` : "";
+		const message = `Merge conflict in ${conflicts.length} file(s)${conflictList}. Local configuration in ${agentDir()} was preserved. Resolve with /sync merge --ours, /sync merge --theirs, or /sync mergetool. Then run /sync merge. (remote ${shortId(
 			remoteRevision,
 		)})`;
 		ctx.ui.notify(message, "warning");
-		return { pushed: false, pulled: false, merged: true, message, conflicts };
+		return { pushed: false, pulled: false, merged: false, message, conflicts };
 	}
 
+	await copyMirrorToAgent(config);
 	await refreshIndicator(ctx, config);
 	const remote = await readRemoteFiles(config, { signal: ctx.signal });
 	const message = `Pulled ${remote.size} file(s) from ${config.branch}.`;
@@ -267,10 +277,78 @@ export async function fetch(
 	return { pushed: false, pulled: false, merged: false, message };
 }
 
+export interface FileValidationError {
+	path: string;
+	line?: number;
+	reason: string;
+}
+
+/**
+ * Validate that the mirror work tree has resolved all conflicts and produced
+ * valid JSON for any .json files before allowing completeMerge to commit.
+ */
+export async function validateResolvedMirror(
+	config: SyncConfig,
+	signal?: AbortSignal,
+): Promise<FileValidationError[]> {
+	const errors: FileValidationError[] = [];
+	const unmerged = await listConflictedPaths({ signal });
+	for (const file of unmerged) {
+		errors.push({ path: file, reason: "unmerged git conflict" });
+	}
+
+	const projected = await mirrorProjectedFiles(config);
+	for (const relative of projected) {
+		const fullPath = mirrorTarget(relative);
+		let content: string;
+		try {
+			content = await fs.readFile(fullPath, "utf8");
+		} catch {
+			continue;
+		}
+
+		const lines = content.split(/\r?\n/u);
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			if (
+				line.startsWith("<<<<<<<") ||
+				line.startsWith("=======") ||
+				line.startsWith(">>>>>>>") ||
+				line.startsWith("|||||||")
+			) {
+				errors.push({
+					path: relative,
+					line: i + 1,
+					reason: `unresolved conflict marker: ${line.slice(0, 12).trim()}`,
+				});
+				break;
+			}
+		}
+
+		if (relative.toLowerCase().endsWith(".json")) {
+			try {
+				JSON.parse(content);
+			} catch (err) {
+				errors.push({
+					path: relative,
+					reason: `invalid JSON syntax: ${(err as Error).message}`,
+				});
+			}
+		}
+	}
+	return errors;
+}
+
+export interface MergeOptions {
+	abort?: boolean;
+	ours?: boolean;
+	theirs?: boolean;
+}
+
 export async function merge(
 	ctx: CommandContext,
 	config: SyncConfig,
-	options: { abort?: boolean } = {},
+	options: MergeOptions = {},
 ): Promise<SyncResult> {
 	if (options.abort) {
 		if (!(await isMergeInProgress({ signal: ctx.signal }))) {
@@ -279,7 +357,6 @@ export async function merge(
 			return { pushed: false, pulled: false, merged: false, message };
 		}
 		await abortMerge({ signal: ctx.signal });
-		await copyMirrorToAgent(config);
 		await refreshIndicator(ctx, config);
 		const message = "Merge aborted; local files restored to the pre-merge state.";
 		ctx.ui.notify(message, "info");
@@ -293,21 +370,100 @@ export async function merge(
 		return { pushed: false, pulled: false, merged: false, message };
 	}
 
-	// The user resolved conflicts in the real agent files; graft the resolved
-	// tree back into the mirror, then commit to complete the merge.
-	const files = await collectAgentFiles(config);
-	await graftAgentIntoMirror(config, files);
-	await stageAll({ signal: ctx.signal });
+	if (options.ours && options.theirs) {
+		const message = "Cannot specify both --ours and --theirs.";
+		ctx.ui.notify(message, "error");
+		return { pushed: false, pulled: false, merged: false, message };
+	}
+
+	if (options.ours) {
+		await checkoutOurs({ signal: ctx.signal });
+	} else if (options.theirs) {
+		await checkoutTheirs({ signal: ctx.signal });
+	} else {
+		// Graft any user modifications from the agent directory into mirror if the
+		// user manually edited the agent file while resolving.
+		const localFiles = await collectAgentFiles(config);
+		for (const file of localFiles) {
+			try {
+				const agentContent = await fs.readFile(file.source, "utf8");
+				const headContent = await readCommitFile("HEAD", file.path, { signal: ctx.signal });
+				if (headContent === undefined || agentContent !== headContent) {
+					const target = mirrorTarget(file.path);
+					await fs.mkdir(path.dirname(target), { recursive: true });
+					await fs.writeFile(target, agentContent, "utf8");
+				}
+			} catch {
+				// Unreadable file — ignore
+			}
+		}
+		await stageAll({ signal: ctx.signal });
+	}
+
+	// Validate mirror files before completing merge.
+	const errors = await validateResolvedMirror(config, ctx.signal);
+	if (errors.length > 0) {
+		const errorDetails = errors
+			.slice(0, 5)
+			.map((e) => `  - ${agentTarget(e.path)}${e.line ? `:${e.line}` : ""}: ${e.reason}`)
+			.join("\n");
+		const message = [
+			`Cannot complete merge: ${errors.length} unresolved issue(s) detected.`,
+			errorDetails,
+			"",
+			`To resolve manually, edit files in: ${agentDir()}`,
+			"Or choose a resolution strategy:",
+			"  /sync merge --ours     (keep local configuration)",
+			"  /sync merge --theirs   (use remote configuration)",
+			"  /sync mergetool        (open 3-way merge tool)",
+			"  /sync merge --abort    (discard merge and restore)",
+		].join("\n");
+		ctx.ui.notify(message, "error");
+		return { pushed: false, pulled: false, merged: false, message };
+	}
+
 	const completed = await completeMerge(LOCAL_COMMIT_MESSAGE, { signal: ctx.signal });
 	await copyMirrorToAgent(config);
 	await refreshIndicator(ctx, config);
 	const message = completed
-		? "Merge completed. Run /sync push to publish."
+		? "Merge completed. Applied cleanly to local configuration. Run /sync push to publish."
 		: "Merge has no further changes to record. Run /sync push to publish.";
 	ctx.ui.notify(message, "info");
 	return { pushed: false, pulled: false, merged: true, message };
 }
 
+export async function mergetool(
+	ctx: CommandContext,
+	config: SyncConfig,
+	tool?: string,
+): Promise<SyncResult> {
+	if (!(await isMergeInProgress({ signal: ctx.signal }))) {
+		const message =
+			"No merge in progress. Run /sync pull to merge remote changes into local files.";
+		ctx.ui.notify(message, "info");
+		return { pushed: false, pulled: false, merged: false, message };
+	}
+
+	try {
+		await launchMergetool(tool, { signal: ctx.signal });
+		await refreshIndicator(ctx, config);
+		const conflicts = await listConflictedPaths({ signal: ctx.signal });
+		if (conflicts.length === 0) {
+			ctx.ui.notify("Mergetool finished. Run /sync merge to validate and apply.", "info");
+		} else {
+			ctx.ui.notify(
+				`Mergetool finished, but ${conflicts.length} file(s) still conflicted.`,
+				"warning",
+			);
+		}
+		return { pushed: false, pulled: false, merged: false, message: "mergetool" };
+	} catch (error) {
+		const message = `Failed to run mergetool: ${error instanceof Error ? error.message : String(error)}`;
+		ctx.ui.notify(message, "error");
+		return { pushed: false, pulled: false, merged: false, message };
+	}
+}
+
 function describeChanges(summary: ReturnType<typeof diffSummary>): string {
 	const parts: string[] = [];
 	if (summary.added > 0) parts.push(`${summary.added} added`);

package/src/status.ts

@@ -135,6 +135,6 @@ export function syncIndicatorText(info: SyncStatusInfo): string {
 		case "behind":
 			return `sync: ${info.behind} behind — pull`;
 		case "conflict":
-			return `sync: conflict (${info.conflicts}) — pull --merge or --force`;
+			return `sync: conflict (${info.conflicts}) — /sync merge or mergetool`;
 	}
 }