pi-git-sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# pi-git-sync
+
+Pi package that adds `/sync` to sync `~/.pi/agent` through Git.
+
+It keeps your Pi config portable across machines without committing auth, sessions, caches, package clones, or local sync state.
+
+## Install
+
+```bash
+pi install npm:pi-git-sync
+```
+
+Then run inside Pi:
+
+```text
+/sync <git-repo-url>
+```
+
+After the first setup, use:
+
+```text
+/sync
+```
+
+## Commands
+
+```text
+/sync <repo>   # configure repo and sync
+/sync          # sync configured repo
+/sync status   # show git status
+```
+
+## What gets synced
+
+- `settings.json`
+- `web-search.json`
+- `keybindings.json`
+- `agents/`
+- `extensions/`
+- `skills/`
+- `prompts/`
+- `themes/`
+
+## What is ignored
+
+- `auth.json`
+- `models.json`
+- `sync.json`
+- `sessions/`, `cache/`, `logs/`, `tmp/`
+- `npm/`, `git/`, `node_modules/`
+- `.env`, tokens, credentials, keys, pem files
+
+## Conflict handling
+
+If Git reports a conflict, `/sync` offers to:
+
+- ask the agent to merge
+- abort
+- use local and force-push
+- use remote and backup local
+
+When the agent resolves a conflict, the next `/sync` commits it as:
+
+```text
+sync: agent merged conflicts ...
+```
+
+## Safety
+
+- Uses an allowlist instead of `git add .`.
+- Refuses to commit staged files that look like secrets.
+- Backs up local config before replacing it with remote config.
+- Generates the config repo `README.md` automatically.
+
+## Development
+
+```bash
+npm run smoke
+```
+
+## License
+
+MIT

package/extensions/sync.ts

@@ -0,0 +1,328 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const agentDir = join(homedir(), ".pi", "agent");
+const syncFile = join(agentDir, "sync.json");
+const backupDir = join(agentDir, "backups");
+const agentMergeFlag = join(agentDir, ".git", "pi-git-sync-agent-merge");
+const branch = "main";
+const allow = [
+	".gitignore",
+	"README.md",
+	"settings.json",
+	"web-search.json",
+	"keybindings.json",
+	"agents",
+	"extensions",
+	"skills",
+	"prompts",
+	"themes",
+];
+
+const ignore = `# pi-git-sync local state
+sync.json
+models.json
+backups/
+extensions-disabled/
+bin/
+
+# secrets/auth
+.env
+.env.*
+auth*
+tokens*
+secrets*
+credentials*
+*.key
+*.pem
+
+# runtime
+sessions/
+logs/
+cache/
+tmp/
+temp/
+trust.json
+
+# installed packages / external code
+npm/
+git/
+node_modules/
+`;
+
+type Config = { repo: string; branch: string };
+
+function repoOwner(repo?: string) {
+	if (!repo) return "you";
+	const path = repo.replace(/^git@[^:]+:/, "").replace(/^[a-z]+:\/\/[^/]+\//, "");
+	return path.split("/").filter(Boolean)[0]?.replace(/\.git$/, "") || "you";
+}
+
+function readme(config?: Config) {
+	return `# Beautiful Pi Configuration by ${repoOwner(config?.repo)}
+
+Synced pi-agent config managed by pi-git-sync.
+
+## Included
+
+- settings.json
+- web-search.json
+- keybindings.json
+- agents/
+- extensions/
+- skills/
+- prompts/
+- themes/
+
+## Excluded
+
+Secrets, auth, sessions, cache, logs, installed packages, models.json, and local sync state.
+
+Generated automatically by pi-git-sync.
+`;
+}
+
+function sh(cmd: string, args: string[], cwd = agentDir) {
+	return new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
+		execFile(cmd, args, { cwd }, (err, stdout, stderr) => {
+			resolve({ code: (err as any)?.code ?? 0, stdout: String(stdout), stderr: String(stderr) });
+		});
+	});
+}
+
+async function git(args: string[]) {
+	return sh("git", args);
+}
+
+async function mustGit(args: string[]) {
+	const result = await git(args);
+	if (result.code !== 0) throw new Error(result.stderr || result.stdout || `git ${args.join(" ")} failed`);
+	return result;
+}
+
+function isConfig(value: unknown): value is Config {
+	return !!value && typeof value === "object" && typeof (value as Config).repo === "string" && typeof (value as Config).branch === "string";
+}
+
+async function loadConfig(): Promise<Config | undefined> {
+	if (!existsSync(syncFile)) return;
+	try {
+		const config = JSON.parse(await readFile(syncFile, "utf8"));
+		if (isConfig(config)) return config;
+	} catch {}
+	throw new Error("Invalid ~/.pi/agent/sync.json, delete it or fix repo/branch");
+}
+
+async function saveConfig(config: Config) {
+	await mkdir(agentDir, { recursive: true });
+	await writeFile(syncFile, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+async function ensureFiles(config?: Config) {
+	await mkdir(agentDir, { recursive: true });
+	const gitignorePath = join(agentDir, ".gitignore");
+	const current = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+	const normalized = current.replace("# pi-sync local state", "# pi-git-sync local state");
+	if (normalized !== current) await writeFile(gitignorePath, normalized);
+	else if (!current.includes("# pi-git-sync local state")) await writeFile(gitignorePath, `${current.trim()}\n\n${ignore}`.trimStart());
+	const readmePath = join(agentDir, "README.md");
+	// README is generated by design.
+	await writeFile(readmePath, readme(config));
+}
+
+async function backupSafe() {
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const dest = join(backupDir, stamp);
+	await mkdir(dest, { recursive: true });
+	for (const p of allow) {
+		const from = join(agentDir, p);
+		if (existsSync(from)) await cp(from, join(dest, p), { recursive: true });
+	}
+	return dest;
+}
+
+async function removeSafe() {
+	for (const p of allow.filter((p) => !p.startsWith("."))) {
+		await rm(join(agentDir, p), { recursive: true, force: true });
+	}
+}
+
+async function addAllowed() {
+	const tracked = (await mustGit(["ls-files", "--", ...allow])).stdout.split("\n").filter(Boolean);
+	const existing = allow.filter((p) => existsSync(join(agentDir, p)));
+	const paths = [...new Set([...tracked, ...existing])];
+	if (paths.length) await mustGit(["add", "-A", "--", ...paths]);
+}
+
+async function stagedFiles() {
+	return (await mustGit(["diff", "--cached", "--name-only"])).stdout.split("\n").filter(Boolean);
+}
+
+async function scanSecrets() {
+	const files = await stagedFiles();
+	const hits: string[] = [];
+	const secretPattern = /(sk-[A-Za-z0-9_-]{20,}|(apiKey|access[_-]?token|refresh[_-]?token|password|secret)\s*[=:]\s*["'][^"']{8,})/i;
+	for (const file of files) {
+		const path = join(agentDir, file);
+		if (!existsSync(path)) continue;
+		const text = await readFile(path, "utf8").catch(() => "");
+		if (secretPattern.test(text)) hits.push(file);
+	}
+	if (hits.length) throw new Error(`Refusing to commit possible secrets in: ${hits.join(", ")}`);
+}
+
+async function commitIfNeeded(message: string) {
+	await addAllowed();
+	const diff = await git(["diff", "--cached", "--quiet"]);
+	if (diff.code === 0) return false;
+	if (diff.code !== 1) throw new Error(diff.stderr || diff.stdout || "git diff failed");
+	await scanSecrets();
+	await mustGit(["commit", "-m", message]);
+	return true;
+}
+
+async function ensureRemote(config: Config) {
+	const remote = await git(["remote", "get-url", "origin"]);
+	if (remote.code !== 0) await mustGit(["remote", "add", "origin", config.repo]);
+	else if (remote.stdout.trim() !== config.repo) await mustGit(["remote", "set-url", "origin", config.repo]);
+}
+
+async function initRepo(config: Config, ctx: ExtensionCommandContext) {
+	if (!existsSync(join(agentDir, ".git"))) await mustGit(["init"]);
+	await ensureRemote(config);
+	await mustGit(["checkout", "-B", config.branch]);
+
+	const remoteBranch = await git(["ls-remote", "--heads", "origin", config.branch]);
+	if (remoteBranch.code !== 0) throw new Error(remoteBranch.stderr || remoteBranch.stdout || "git ls-remote failed");
+	if (!remoteBranch.stdout.trim()) {
+		await ensureFiles(config);
+		await commitIfNeeded(`sync: initial pi config ${new Date().toISOString()}`);
+		await mustGit(["push", "-u", "origin", config.branch]);
+		ctx.ui.notify("Pi config uploaded to empty repo", "info");
+		return;
+	}
+
+	if (!ctx.hasUI) throw new Error("Remote config exists; interactive setup required");
+	const choice = await ctx.ui.select("Remote config already exists", ["Backup local and download", "Abort"]);
+	if (choice !== "Backup local and download") return;
+	const backup = await backupSafe();
+	await removeSafe();
+	await mustGit(["fetch", "origin", config.branch]);
+	await mustGit(["reset", "--hard", `origin/${config.branch}`]);
+	ctx.ui.notify(`Downloaded remote config. Backup: ${backup}`, "info");
+}
+
+function inMerge() {
+	return existsSync(join(agentDir, ".git", "MERGE_HEAD"));
+}
+
+async function continueMerge(config: Config, ctx: ExtensionCommandContext) {
+	await addAllowed();
+	const unresolved = await mustGit(["diff", "--name-only", "--diff-filter=U"]);
+	if (unresolved.stdout.trim()) throw new Error(`Still unresolved: ${unresolved.stdout.trim()}`);
+	await scanSecrets();
+	const byAgent = existsSync(agentMergeFlag);
+	const message = byAgent ? `sync: agent merged conflicts ${new Date().toISOString()}` : `sync: resolved conflicts ${new Date().toISOString()}`;
+	await mustGit(["commit", "-m", message]);
+	await rm(agentMergeFlag, { force: true });
+	await mustGit(["push", "origin", config.branch]);
+	ctx.ui.notify("Conflict resolution pushed", "info");
+}
+
+async function askAgentToMerge(pi: ExtensionAPI, config: Config) {
+	await writeFile(agentMergeFlag, new Date().toISOString());
+	pi.sendUserMessage(`Resolve pi-git-sync git conflicts in ${agentDir}.
+
+Rules:
+- Only edit tracked/synced pi config files.
+- Do not touch auth.json, models.json, sync.json, sessions, cache, npm, git, or secrets.
+- Preserve useful changes from both sides when possible.
+- After resolving, run git status.
+- Do not commit or push; tell me to run /sync again.
+
+After I run /sync again, pi-git-sync will commit with message: sync: agent merged conflicts ...`, { deliverAs: "followUp" });
+}
+
+async function normalSync(pi: ExtensionAPI, config: Config, ctx: ExtensionCommandContext) {
+	await ensureFiles(config);
+	if (inMerge()) return continueMerge(config, ctx);
+
+	await commitIfNeeded(`sync: ${new Date().toISOString()}`);
+	const pulled = await git(["pull", "--no-rebase", "--no-edit", "origin", config.branch]);
+	if (pulled.code !== 0) {
+		if (!ctx.hasUI) throw new Error(pulled.stderr || "git pull failed");
+		const choice = await ctx.ui.select("Sync conflict", ["Ask agent to merge", "Abort", "Use local and force push", "Use remote and backup local"]);
+		if (choice === "Ask agent to merge") {
+			await askAgentToMerge(pi, config);
+			ctx.ui.notify("Queued agent conflict resolver", "info");
+			return;
+		}
+		if (choice === "Use local and force push") {
+			await mustGit(["merge", "--abort"]);
+			await mustGit(["push", "--force-with-lease", "origin", config.branch]);
+			ctx.ui.notify("Local config pushed", "info");
+			return;
+		}
+		if (choice === "Use remote and backup local") {
+			const backup = await backupSafe();
+			await mustGit(["merge", "--abort"]);
+			await mustGit(["fetch", "origin", config.branch]);
+			await mustGit(["reset", "--hard", `origin/${config.branch}`]);
+			ctx.ui.notify(`Remote config applied. Backup: ${backup}`, "info");
+			return;
+		}
+		await mustGit(["merge", "--abort"]);
+		return;
+	}
+
+	const ahead = await git(["status", "--porcelain", "--branch"]);
+	if (ahead.stdout.includes("ahead")) await mustGit(["push", "origin", config.branch]);
+	ctx.ui.notify("Pi config synced", "info");
+}
+
+async function showStatus(ctx: ExtensionCommandContext) {
+	const status = await git(["status", "--short", "--branch"]);
+	ctx.ui.notify(status.stdout.trim() || "No git status", "info");
+}
+
+function looksLikeRepo(arg: string) {
+	return /^(git@|https?:\/\/|ssh:\/\/|git:\/\/)/.test(arg) || /^[\w.-]+\/[\w./-]+(\.git)?$/.test(arg);
+}
+
+export default function piGitSync(pi: ExtensionAPI) {
+	pi.registerCommand("sync", {
+		description: "Sync ~/.pi/agent config through git",
+		getArgumentCompletions: (prefix) => ["status"].filter((x) => x.startsWith(prefix)).map((value) => ({ value, label: value })),
+		handler: async (args, ctx) => {
+			await ctx.waitForIdle();
+			const arg = args.trim();
+			let config = await loadConfig();
+
+			if (arg === "status") return showStatus(ctx);
+			if (arg && looksLikeRepo(arg)) {
+				config = { repo: arg, branch };
+				await saveConfig(config);
+			}
+
+			await ensureFiles(config);
+			if (!config) {
+				if (!ctx.hasUI) throw new Error("Run /sync <repo-url> once to set repo URL");
+				const repo = await ctx.ui.input("Pi git sync repo", "git@github.com:user/pi-config.git");
+				if (!repo) return;
+				config = { repo, branch };
+				await saveConfig(config);
+				await ensureFiles(config);
+			}
+
+			if (!existsSync(join(agentDir, ".git"))) await initRepo(config, ctx);
+			else {
+				await ensureRemote(config);
+				await normalSync(pi, config, ctx);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "pi-git-sync",
+  "version": "0.1.0",
+  "description": "Sync Pi agent config through Git",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-agent",
+    "git",
+    "sync",
+    "config"
+  ],
+  "author": "daze",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "extensions"
+  ],
+  "scripts": {
+    "smoke": "npx esbuild extensions/sync.ts --bundle --platform=node --format=esm --outfile=/tmp/pi-git-sync-smoke.mjs --external:@earendil-works/pi-coding-agent"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}