@lisang233/pi-sync 0.1.0

package/src/extension.ts

@@ -0,0 +1,208 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "./config.js";
+import { runConfigEditor } from "./config-ui.js";
+import * as operations from "./operations.js";
+import { runSetupWizard } from "./wizard.js";
+
+const STATUS_KEY = "sync";
+
+interface BackgroundSync {
+	settled: Promise<void>;
+}
+
+const COMMANDS = ["init", "status", "push", "pull", "fetch", "merge", "config", "help"] as const;
+
+type Subcommand = (typeof COMMANDS)[number];
+
+const USAGE = [
+	"pi-sync — sync Pi configuration through Git",
+	"",
+	"usage: /sync <command> [options]",
+	"",
+	"commands:",
+	"  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)",
+	"  merge               continue an in-progress merge (--abort discards)",
+	"  push                publish local snapshot (--force overwrites remote)",
+	"  help                show this help",
+].join("\n");
+
+export default function sync(pi: ExtensionAPI): void {
+	let sessionAbort = new AbortController();
+	let backgroundSync: BackgroundSync | undefined;
+
+	const startBackgroundSync = (ctx: ExtensionContext, signal: AbortSignal) => {
+		const settled = (async () => {
+			try {
+				await runAutomaticSync(ctx, signal);
+			} catch (error) {
+				if (signal.aborted) return;
+				ctx.ui.setStatus(STATUS_KEY, undefined);
+				ctx.ui.notify(`pi-sync auto sync skipped: ${errorMessage(error)}`, "warning");
+			}
+		})();
+		backgroundSync = { settled };
+	};
+
+	const drainBackgroundSync = async (signal?: AbortSignal): Promise<void> => {
+		const current = backgroundSync;
+		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.
+		}
+	};
+
+	pi.registerCommand("sync", {
+		description: "Sync Pi configuration through Git",
+		getArgumentCompletions: (prefix) => {
+			const [first = "", ...rest] = prefix.trim().split(/\s+/u);
+			if (rest.length > 0) return null;
+			return COMMANDS.filter((name) => name.startsWith(first)).map((name) => ({
+				value: name,
+				label: name,
+			}));
+		},
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				throw new Error(
+					"/sync requires TUI or RPC mode so results and safety prompts are observable.",
+				);
+			}
+			try {
+				await handleCommand(args, ctx);
+			} catch (error) {
+				if (sessionAbort.signal.aborted) return;
+				ctx.ui.setStatus(STATUS_KEY, undefined);
+				ctx.ui.notify(errorMessage(error), "error");
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionAbort.abort(new DOMException("Session replaced", "AbortError"));
+		sessionAbort = new AbortController();
+		const signal = sessionAbort.signal;
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		await drainBackgroundSync();
+		try {
+			const config = await loadConfig();
+			if (signal.aborted) return;
+			if (config.remote.length === 0 || !config.automatic) return; // not configured or manual-only
+			startBackgroundSync(ctx, signal);
+		} catch (error) {
+			if (signal.aborted) return;
+			ctx.ui.notify(`pi-sync startup failed: ${errorMessage(error)}`, "warning");
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		// automatic only observes; aborting the in-flight fetch is enough. No
+		// shutdown push — nothing writes local files without an explicit command.
+		sessionAbort.abort(new DOMException("Session shut down", "AbortError"));
+	});
+}
+
+async function runAutomaticSync(ctx: ExtensionContext, signal: AbortSignal): Promise<void> {
+	const config = await loadConfig();
+	throwIfAborted(signal);
+	if (config.remote.length === 0 || !config.automatic) return;
+	// Non-destructive: fetch the remote snapshot and refresh the status-bar
+	// indicator. Never pushes, pulls or merges on its own.
+	await operations.fetch(ctx, config, { quiet: true });
+}
+
+async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext): Promise<void> {
+	const [first = "", ...restTokens] = rawArgs.trim().split(/\s+/u);
+	const subcommand = normalizeSubcommand(first);
+	if (subcommand === undefined || subcommand === "help") {
+		ctx.ui.notify(USAGE, "info");
+		return;
+	}
+
+	const config = await loadConfig();
+	if (subcommand !== "init" && config.remote.length === 0) {
+		ctx.ui.notify(
+			"pi-sync is not configured. Run /sync init to set up the git remote, or edit pi-sync.json.",
+			"warning",
+		);
+		return;
+	}
+
+	const force = restTokens.some((token) => token === "--force");
+
+	switch (subcommand) {
+		case "init":
+			await runSetupWizard(ctx.ui);
+			return;
+		case "status":
+			await operations.status(ctx, config, {
+				diff: restTokens.some((token) => token === "--diff"),
+			});
+			return;
+		case "push":
+			await operations.push(ctx, config, { force });
+			return;
+		case "pull":
+			await operations.pull(ctx, config, {
+				force,
+				merge: restTokens.some((token) => token === "--merge"),
+			});
+			return;
+		case "fetch":
+			await operations.fetch(ctx, config);
+			return;
+		case "merge":
+			await operations.merge(ctx, config, {
+				abort: restTokens.some((token) => token === "--abort"),
+			});
+			return;
+		case "config":
+			await runConfigEditor(ctx.ui, config);
+			return;
+	}
+}
+
+function normalizeSubcommand(value: string): Subcommand | undefined {
+	if (value === "") return undefined;
+	if (COMMANDS.includes(value as Subcommand)) return value as Subcommand;
+	const matches = COMMANDS.filter((name) => name.startsWith(value));
+	return matches.length === 1 ? matches[0] : undefined;
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+	if (!signal.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
+}
+
+function waitForAbort(signal: AbortSignal): Promise<never> {
+	return new Promise((_resolve, reject) => {
+		const rejectWithReason = () =>
+			reject(
+				signal.reason instanceof Error
+					? signal.reason
+					: new DOMException("The operation was aborted", "AbortError"),
+			);
+		if (signal.aborted) {
+			rejectWithReason();
+			return;
+		}
+		signal.addEventListener("abort", rejectWithReason, { once: true });
+	});
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/git.ts

@@ -0,0 +1,317 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { SyncConfig } from "./config.js";
+import { mirrorRepoDir, snapshotFilePath, stateDir } from "./config.js";
+import type { Snapshot } from "./snapshot.js";
+
+const GIT_TIMEOUT_MS = 60_000;
+const COMMIT_IDENTITY = { name: "pi-sync", email: "pi-sync@local" };
+
+export class GitCommandError extends Error {
+	readonly exitCode: number | null;
+	readonly stderr: string;
+
+	constructor(message: string, exitCode: number | null, stderr: string) {
+		super(message);
+		this.name = "GitCommandError";
+		this.exitCode = exitCode;
+		this.stderr = stderr;
+	}
+}
+
+export interface GitRunOptions {
+	signal?: AbortSignal;
+	cwd?: string;
+	input?: Buffer | string;
+	timeoutMs?: number;
+}
+
+export interface GitRunResult {
+	stdout: string;
+	stderr: string;
+}
+
+/** Run one git command with a bounded timeout and prompt-free environment. */
+export async function runGit(args: string[], options: GitRunOptions = {}): Promise<GitRunResult> {
+	throwIfAborted(options.signal);
+	const env: NodeJS.ProcessEnv = {
+		...process.env,
+		GIT_TERMINAL_PROMPT: "0",
+		GCM_INTERACTIVE: "Never",
+		GIT_ASKPASS: "",
+		SSH_ASKPASS: "",
+		SSH_ASKPASS_REQUIRE: "never",
+		GIT_SSH_COMMAND: "ssh -oBatchMode=yes",
+		GIT_AUTHOR_NAME: COMMIT_IDENTITY.name,
+		GIT_AUTHOR_EMAIL: COMMIT_IDENTITY.email,
+		GIT_COMMITTER_NAME: COMMIT_IDENTITY.name,
+		GIT_COMMITTER_EMAIL: COMMIT_IDENTITY.email,
+		LC_ALL: "C",
+		LANG: "C",
+	};
+	const child = spawn("git", args, {
+		cwd: options.cwd,
+		env,
+		stdio: ["pipe", "pipe", "pipe"],
+		windowsHide: true,
+	});
+	const stdout: Buffer[] = [];
+	const stderr: Buffer[] = [];
+	let settled = false;
+	let terminationError: Error | undefined;
+
+	const terminate = (error: Error) => {
+		if (settled || terminationError) return;
+		terminationError = error;
+		child.kill("SIGTERM");
+		setTimeout(() => {
+			if (!settled) child.kill("SIGKILL");
+		}, 2_000);
+	};
+	child.stdout.on("data", (chunk: Buffer) => stdout.push(Buffer.from(chunk)));
+	child.stderr.on("data", (chunk: Buffer) => stderr.push(Buffer.from(chunk)));
+	child.stdin.on("error", () => undefined);
+	if (options.input !== undefined) child.stdin.end(options.input);
+	else child.stdin.end();
+	const onAbort = () => terminate(signalReason(options.signal));
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	const timer = setTimeout(
+		() =>
+			terminate(new Error(`Git command timed out after ${options.timeoutMs ?? GIT_TIMEOUT_MS}ms.`)),
+		options.timeoutMs ?? GIT_TIMEOUT_MS,
+	);
+
+	try {
+		const result = await new Promise<GitRunResult>((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (code) => {
+				settled = true;
+				const stdoutText = Buffer.concat(stdout).toString("utf8");
+				const stderrText = Buffer.concat(stderr).toString("utf8");
+				if (terminationError) {
+					reject(terminationError);
+					return;
+				}
+				if (code !== 0) {
+					reject(
+						new GitCommandError(
+							stderrText.trim() || `Git exited with status ${code ?? "unknown"}.`,
+							code,
+							stderrText,
+						),
+					);
+					return;
+				}
+				resolve({ stdout: stdoutText, stderr: stderrText });
+			});
+		});
+		return result;
+	} finally {
+		clearTimeout(timer);
+		options.signal?.removeEventListener("abort", onAbort);
+	}
+}
+
+/** Ensure the local mirror repository exists, is initialized, and knows the remote. */
+export async function ensureMirror(config: SyncConfig): Promise<void> {
+	await fs.mkdir(stateDir(), { recursive: true });
+	const repo = mirrorRepoDir();
+	if (!(await pathExists(repo))) {
+		await fs.mkdir(repo, { recursive: true });
+		await runGit(["init", "-b", "main"], { cwd: repo });
+		await runGit(["remote", "add", "origin", config.remote], { cwd: repo });
+	}
+	await runGit(["remote", "set-url", "origin", config.remote], { cwd: repo });
+}
+
+/** Fetch the configured branch from the remote into origin/<branch>. */
+export async function fetchRemote(config: SyncConfig, options: GitRunOptions = {}): Promise<void> {
+	await ensureMirror(config);
+	try {
+		await runGit(["fetch", "--quiet", "origin", config.branch], {
+			cwd: mirrorRepoDir(),
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		});
+	} catch (error) {
+		// A fresh remote without the branch yet is a normal first-run state.
+		if (error instanceof GitCommandError && error.stderr.includes("couldn't find remote ref")) {
+			return;
+		}
+		throw error;
+	}
+}
+
+/** Read the remote snapshot for the branch; returns undefined when the branch has no snapshot. */
+export async function readRemoteSnapshot(
+	config: SyncConfig,
+	options: GitRunOptions = {},
+): Promise<Snapshot | undefined> {
+	const repo = mirrorRepoDir();
+	if (!(await pathExists(repo))) return undefined;
+	const ref = `refs/remotes/origin/${config.branch}`;
+	try {
+		const result = await runGit(["show", `${ref}:pi-sync/snapshot.json`], {
+			cwd: repo,
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		});
+		return JSON.parse(result.stdout) as Snapshot;
+	} catch (error) {
+		if (error instanceof GitCommandError && isMissingRefError(error.stderr)) return undefined;
+		throw error;
+	}
+}
+
+/** Read the snapshot stored at a specific revision; undefined when absent. */
+export async function readSnapshotAt(
+	revision: string,
+	options: GitRunOptions = {},
+): Promise<Snapshot | undefined> {
+	try {
+		const result = await runGit(["show", `${revision}:pi-sync/snapshot.json`], {
+			cwd: mirrorRepoDir(),
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		});
+		return JSON.parse(result.stdout) as Snapshot;
+	} catch (error) {
+		if (error instanceof GitCommandError && isMissingRefError(error.stderr)) return undefined;
+		throw error;
+	}
+}
+
+/** Remote revision (commit sha) for the branch, or undefined when the branch is absent. */
+export async function readRemoteRevision(
+	config: SyncConfig,
+	options: GitRunOptions = {},
+): Promise<string | undefined> {
+	if (!(await pathExists(mirrorRepoDir()))) return undefined;
+	const ref = `refs/remotes/origin/${config.branch}`;
+	try {
+		const result = await runGit(["rev-parse", ref], {
+			cwd: mirrorRepoDir(),
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		});
+		return result.stdout.trim();
+	} catch (error) {
+		if (error instanceof GitCommandError && isMissingRefError(error.stderr)) return undefined;
+		throw error;
+	}
+}
+
+/** Publish a snapshot to the remote branch as one commit. */
+export async function publishSnapshot(
+	config: SyncConfig,
+	snapshot: Snapshot,
+	options: GitRunOptions = {},
+	force = false,
+): Promise<string> {
+	const repo = mirrorRepoDir();
+	// The mirror is disposable (it only tracks pi-sync/snapshot.json). Advance
+	// it to the fetched remote tip so the publish push fast-forwards; the
+	// caller has already decided it is safe to publish. Missing ref = first push.
+	try {
+		await runGit(["reset", "--hard", `refs/remotes/origin/${config.branch}`], {
+			cwd: repo,
+			signal: options.signal,
+		});
+	} catch {
+		// Remote branch does not exist yet; publish from the empty HEAD.
+	}
+	// The mirror tracks only pi-sync/snapshot.json. The reset aligned the
+	// index to the remote tip, which may carry legacy or foreign paths;
+	// empty the index so the published commit never drags them along.
+	await runGit(["read-tree", "--empty"], { cwd: repo, signal: options.signal });
+	await fs.mkdir(path.dirname(snapshotFilePath()), { recursive: true });
+	await fs.writeFile(snapshotFilePath(), `${JSON.stringify(snapshot, null, "\t")}\n`, {
+		mode: 0o600,
+	});
+	await runGit(["add", "--", snapshotFilePath()], { cwd: repo, signal: options.signal });
+	await runGit(["commit", "--quiet", "-m", `pi-sync: ${snapshot.files.length} files`], {
+		cwd: repo,
+		signal: options.signal,
+	});
+	await runGit(
+		["push", "--quiet", ...(force ? ["--force"] : []), "origin", `HEAD:${config.branch}`],
+		{
+			cwd: repo,
+			signal: options.signal,
+			timeoutMs: options.timeoutMs,
+		},
+	);
+	// The pushed revision is the commit we just created on HEAD; the
+	// remote-tracking ref is only refreshed by fetch, so read HEAD directly.
+	const result = await runGit(["rev-parse", "HEAD"], {
+		cwd: repo,
+		signal: options.signal,
+	});
+	return result.stdout.trim();
+}
+
+/** List recent snapshot commits on the remote branch (newest first). */
+export async function listHistory(
+	options: GitRunOptions = {},
+): Promise<Array<{ id: string; date: string; message: string }>> {
+	try {
+		const result = await runGit(
+			["log", "--format=%H%x00%cI%x00%s", "-n", "20", "--", "pi-sync/snapshot.json"],
+			{ cwd: mirrorRepoDir(), signal: options.signal, timeoutMs: options.timeoutMs },
+		);
+		return result.stdout
+			.trim()
+			.split("\n")
+			.filter(Boolean)
+			.map((line) => {
+				const [id, date, ...messageParts] = line.split("\u0000");
+				return { id: id ?? "", date: date ?? "", message: messageParts.join("\u0000") };
+			});
+	} catch (error) {
+		if (error instanceof GitCommandError && isMissingRefError(error.stderr)) return [];
+		throw error;
+	}
+}
+
+export function isRemoteUpToDate(
+	localRevision: string | undefined,
+	remoteRevision: string | undefined,
+): boolean {
+	return localRevision !== undefined && localRevision === remoteRevision;
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isMissingRefError(stderr: string): boolean {
+	return (
+		stderr.includes("does not have any commits yet") ||
+		stderr.includes("unknown revision") ||
+		stderr.includes("bad revision") ||
+		stderr.includes("not a valid object name") ||
+		stderr.includes("invalid object name") ||
+		stderr.includes("does not exist in") ||
+		// git resolves <ref>:<path> by checking the working tree too: when the
+		// path is absent from the ref but a same-named file exists on disk it
+		// reports "exists on disk, but not in '<ref>'". Both mean the ref has
+		// no snapshot file.
+		stderr.includes("exists on disk, but not in")
+	);
+}
+
+function signalReason(signal: AbortSignal | undefined): Error {
+	if (signal?.reason instanceof Error) return signal.reason;
+	return new DOMException("The operation was aborted", "AbortError");
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) return;
+	throw signalReason(signal);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import sync from "./extension.js";
+
+export default sync;

package/src/merge-session.ts

@@ -0,0 +1,145 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stateDir } from "./config.js";
+
+const SESSION_DIR = "merge-session";
+const SESSION_FILE = "session.json";
+
+export type BlockChoice = "local" | "remote" | "custom";
+
+/** One divergent block from a merged file; resolution is set when the user resolves it. */
+export interface ConflictBlock {
+	local: string;
+	base: string;
+	remote: string;
+	resolution: string | undefined;
+	choice: BlockChoice | undefined;
+}
+
+export interface MergeFileState {
+	path: string;
+	/** The full merged text with diff3 markers (resume needs no disk state). */
+	merged: string;
+	blocks: ConflictBlock[];
+}
+
+/**
+ * The persistent state of one conflict-resolution session. Lives in its own
+ * file (block contents can be large) so state.json stays small and backward
+ * compatible; only the presence of this file marks an incomplete merge.
+ */
+export interface MergeSessionData {
+	baselineRevision: string;
+	backupDir: string;
+	createdAt: string;
+	/** Files taken from the remote side when the session started. */
+	takeRemote: number;
+	/** Files kept from the local side when the session started. */
+	takeLocal: number;
+	files: MergeFileState[];
+}
+
+export function mergeSessionDir(): string {
+	return path.join(stateDir(), SESSION_DIR);
+}
+
+export function mergeSessionFilePath(): string {
+	return path.join(mergeSessionDir(), SESSION_FILE);
+}
+
+export async function loadMergeSession(): Promise<MergeSessionData | undefined> {
+	let text: string;
+	try {
+		text = await fs.readFile(mergeSessionFilePath(), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	try {
+		return parseMergeSession(JSON.parse(text));
+	} catch {
+		return undefined;
+	}
+}
+
+export async function saveMergeSession(session: MergeSessionData): Promise<void> {
+	await fs.mkdir(mergeSessionDir(), { recursive: true });
+	const serialized = `${JSON.stringify(session, null, "\t")}\n`;
+	await fs.writeFile(mergeSessionFilePath(), serialized, { mode: 0o600 });
+}
+
+export async function clearMergeSession(): Promise<void> {
+	await fs.rm(mergeSessionDir(), { recursive: true, force: true });
+}
+
+/** True when a merge session file exists and parses. */
+export async function hasMergeSession(): Promise<boolean> {
+	return (await loadMergeSession()) !== undefined;
+}
+
+function parseMergeSession(value: unknown): MergeSessionData | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	if (
+		typeof record.baselineRevision !== "string" ||
+		typeof record.backupDir !== "string" ||
+		typeof record.createdAt !== "string" ||
+		typeof record.takeRemote !== "number" ||
+		typeof record.takeLocal !== "number" ||
+		!Array.isArray(record.files)
+	) {
+		return undefined;
+	}
+	const files: MergeFileState[] = [];
+	for (const file of record.files) {
+		const parsed = parseMergeFile(file);
+		if (!parsed) return undefined;
+		files.push(parsed);
+	}
+	return {
+		baselineRevision: record.baselineRevision,
+		backupDir: record.backupDir,
+		createdAt: record.createdAt,
+		takeRemote: record.takeRemote,
+		takeLocal: record.takeLocal,
+		files,
+	};
+}
+
+function parseMergeFile(value: unknown): MergeFileState | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	if (
+		typeof record.path !== "string" ||
+		typeof record.merged !== "string" ||
+		!Array.isArray(record.blocks)
+	) {
+		return undefined;
+	}
+	const blocks: ConflictBlock[] = [];
+	for (const block of record.blocks) {
+		const parsed = parseBlock(block);
+		if (!parsed) return undefined;
+		blocks.push(parsed);
+	}
+	return { path: record.path, merged: record.merged, blocks };
+}
+
+function parseBlock(value: unknown): ConflictBlock | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	if (
+		typeof record.local !== "string" ||
+		typeof record.base !== "string" ||
+		typeof record.remote !== "string"
+	) {
+		return undefined;
+	}
+	const resolution = record.resolution ?? undefined;
+	if (resolution !== undefined && typeof resolution !== "string") return undefined;
+	const choice = record.choice ?? undefined;
+	if (choice !== undefined && choice !== "local" && choice !== "remote" && choice !== "custom") {
+		return undefined;
+	}
+	return { local: record.local, base: record.base, remote: record.remote, resolution, choice };
+}