@narumitw/pi-sync 0.13.0 → 0.13.1

package/README.md

@@ -187,14 +187,15 @@ Before updating `latest.json`, pi-sync re-reads the current pointer and rejects
 ```txt
 extensions/pi-sync/
 ├── src/
-│   └── sync.ts
+│   ├── sync.ts        # Pi entrypoint and command orchestration
+│   └── *.ts           # Package-local config, snapshot, path, and S3 modules
 ├── README.md
 ├── LICENSE
 ├── tsconfig.json
 └── package.json
 ```
 
-The package exposes its Pi extension through `package.json`:
+Only `sync.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",

package/src/command.ts

@@ -0,0 +1,97 @@
+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" },
+];
+const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]> = {
+	push: [
+		...YES_FLAG_COMPLETIONS,
+		{ value: "--force", label: "--force", description: "Overwrite visible remote changes" },
+	],
+	pull: [
+		...YES_FLAG_COMPLETIONS,
+		{ value: "--force", label: "--force", description: "Overwrite local changes" },
+	],
+	sync: [
+		...YES_FLAG_COMPLETIONS,
+		{ value: "--force", label: "--force", description: "Resolve conflicts by forcing action" },
+	],
+	rollback: YES_FLAG_COMPLETIONS,
+	unlock: [{ value: "--stale", label: "--stale", description: "Remove only a stale lock" }],
+};
+
+export function splitArgs(input: string) {
+	return input.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((arg) => arg.replace(/^['"]|['"]$/g, "")) ?? [];
+}
+
+export function parseOptions(args: string[]): CommandOptions {
+	return {
+		yes: args.includes("--yes") || args.includes("-y"),
+		force: args.includes("--force"),
+		stale: args.includes("--stale"),
+		silent: false,
+		reload: true,
+		auto: false,
+		args: args.filter((arg) => !arg.startsWith("-")),
+	};
+}
+
+export function completeSyncArguments(argumentPrefix: string): CommandArgumentCompletion[] | null {
+	const prefix = argumentPrefix.trimStart();
+	if (prefix === "") return [...SYNC_COMMAND_COMPLETIONS];
+
+	const trailingSpace = /\s$/.test(prefix);
+	const tokens = splitArgs(prefix);
+	if (tokens.length === 0) return [...SYNC_COMMAND_COMPLETIONS];
+
+	const [command] = tokens;
+	if (tokens.length === 1 && !trailingSpace) {
+		const matches = SYNC_COMMAND_COMPLETIONS.filter((item) => item.value.startsWith(command));
+		return matches.length > 0 ? [...matches] : null;
+	}
+
+	const flagCompletions = SYNC_FLAG_COMPLETIONS[command];
+	if (!flagCompletions) return null;
+
+	const args = tokens.slice(1);
+	const completedArgs = trailingSpace ? args : args.slice(0, -1);
+	const completedValues = completedArgs.filter((arg) => !arg.startsWith("-"));
+	if (command === "rollback" ? completedValues.length > 1 : completedValues.length > 0) {
+		return null;
+	}
+
+	const current = trailingSpace ? "" : (args.at(-1) ?? "");
+	if (current && !current.startsWith("-")) return null;
+
+	const currentRaw = trailingSpace ? "" : (prefix.match(/\S+$/)?.[0] ?? "");
+	const completionPrefix = trailingSpace
+		? prefix
+		: prefix.slice(0, prefix.length - currentRaw.length);
+	const matches = flagCompletions.filter((item) => item.value.startsWith(current));
+	return matches.length > 0
+		? matches.map((item) => ({ ...item, value: `${completionPrefix}${item.value}` }))
+		: null;
+}
+
+export function usage() {
+	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).",
+	].join("\n");
+}

package/src/config.ts

@@ -0,0 +1,338 @@
+import { randomUUID } from "node:crypto";
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isDeniedPath, safeName } from "./paths.js";
+import type { LockFile, PartialConfig, Snapshot, SyncConfig, SyncState } from "./types.js";
+
+const VERSION = 1;
+const DEFAULT_PROFILE = "default";
+const DEFAULT_PREFIX = "pi-sync";
+const DEFAULT_REGION = "auto";
+const LOCK_STALE_MS = 30 * 60 * 1000;
+const TOP_LEVEL_FILES = new Set(["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md"]);
+const TOP_LEVEL_FILE_NAMES = new Set([...TOP_LEVEL_FILES].map((name) => name.toLowerCase()));
+const TOP_LEVEL_DIRS = new Set(["skills", "prompts", "themes", "extensions"]);
+const RESERVED_TOP_LEVEL_NAMES = new Set([...TOP_LEVEL_DIRS, "sessions"]);
+
+function trimSlashes(value: string) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+
+function decodeBase64Strict(value: string, filePath: string) {
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) {
+		throw new Error(`Invalid base64 content in snapshot file: ${filePath}`);
+	}
+	return Buffer.from(value, "base64");
+}
+
+function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext) {
+	const manager = ctx.sessionManager as typeof ctx.sessionManager & {
+		usesDefaultSessionDir?: () => boolean;
+	};
+	const usesDefaultSessionDir = manager.usesDefaultSessionDir;
+	if (typeof usesDefaultSessionDir === "function" && usesDefaultSessionDir.call(manager)) {
+		return undefined;
+	}
+	const getSessionDir = manager.getSessionDir;
+	return typeof getSessionDir === "function"
+		? (getSessionDir.call(manager) as string | undefined)
+		: undefined;
+}
+
+export async function withLock<T>(command: string, fn: () => Promise<T>): Promise<T> {
+	await ensureStateDir();
+	const lock: LockFile = {
+		id: randomUUID(),
+		pid: process.pid,
+		command,
+		startedAt: new Date().toISOString(),
+	};
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(lockPath(), "wx");
+		await handle.writeFile(JSON.stringify(lock, null, "\t"));
+		await handle.close();
+		handle = undefined;
+		return await fn();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			const current = await readLock();
+			if (current && isStaleLock(current)) {
+				throw new Error(`pi-sync lock is stale (pid ${current.pid}). Run /pisync unlock --stale, then retry.`);
+			}
+			throw new Error(`pi-sync is already running${current ? ` (${current.command}, pid ${current.pid}, started ${current.startedAt})` : ""}.`);
+		}
+		throw error;
+	} finally {
+		await handle?.close();
+		const current = await readLock();
+		if (current?.id === lock.id) await fs.rm(lockPath(), { force: true });
+	}
+}
+
+export async function loadConfigInternal(): Promise<SyncConfig> {
+	const partial = await loadPartialConfig();
+	const endpoint = partial.endpoint;
+	const bucket = partial.bucket;
+	const accessKeyId = partial.accessKeyId;
+	const secretAccessKey = partial.secretAccessKey;
+	const missing = [
+		["endpoint", endpoint],
+		["bucket", bucket],
+		["accessKeyId", accessKeyId],
+		["secretAccessKey", secretAccessKey],
+	]
+		.filter(([, value]) => !value)
+		.map(([name]) => name);
+	if (missing.length > 0) {
+		throw new Error(`Missing pi-sync config: ${missing.join(", ")}. Run /pisync init or set PI_SYNC_* environment variables.`);
+	}
+
+	return {
+		endpoint: endpoint!,
+		bucket: bucket!,
+		region: partial.region ?? DEFAULT_REGION,
+		accessKeyId: accessKeyId!,
+		secretAccessKey: secretAccessKey!,
+		sessionToken: partial.sessionToken,
+		profile: partial.profile ?? DEFAULT_PROFILE,
+		prefix: trimSlashes(partial.prefix ?? DEFAULT_PREFIX),
+		syncSessions: isExplicitlyEnabled(partial.syncSessions),
+		extraFiles: normalizeExtraFiles(partial.extraFiles),
+	};
+}
+
+export async function loadConfig(): Promise<SyncConfig> {
+	return loadConfigInternal();
+}
+
+export async function loadPartialConfig(): Promise<PartialConfig> {
+	const fileConfig = (await readJsonIfExists<PartialConfig>(localConfigPath())) ?? {};
+	return {
+		...fileConfig,
+		endpoint: process.env.PI_SYNC_ENDPOINT ?? process.env.R2_ENDPOINT ?? fileConfig.endpoint,
+		bucket: process.env.PI_SYNC_BUCKET ?? process.env.R2_BUCKET ?? fileConfig.bucket,
+		region: process.env.PI_SYNC_REGION ?? process.env.AWS_REGION ?? fileConfig.region,
+		accessKeyId: process.env.PI_SYNC_ACCESS_KEY_ID ?? process.env.AWS_ACCESS_KEY_ID ?? fileConfig.accessKeyId,
+		secretAccessKey: process.env.PI_SYNC_SECRET_ACCESS_KEY ?? process.env.AWS_SECRET_ACCESS_KEY ?? fileConfig.secretAccessKey,
+		sessionToken: selectSessionToken(fileConfig.sessionToken),
+		profile: process.env.PI_SYNC_PROFILE ?? fileConfig.profile,
+		prefix: process.env.PI_SYNC_PREFIX ?? fileConfig.prefix,
+		autoSync: process.env.PI_SYNC_AUTO_SYNC ?? fileConfig.autoSync,
+		syncSessions: process.env.PI_SYNC_SESSIONS ?? fileConfig.syncSessions,
+		extraFiles: fileConfig.extraFiles,
+	};
+}
+
+export async function configuredSessionDir() {
+	const envSessionDir = normalizeOptionalString(process.env.PI_CODING_AGENT_SESSION_DIR);
+	if (envSessionDir) return expandHome(envSessionDir);
+	const settings = await readJsonIfExists<{ sessionDir?: string }>(path.join(agentDir(), "settings.json"));
+	return settings?.sessionDir ? expandHome(settings.sessionDir) : undefined;
+}
+
+export async function sessionDirForApply(ctx: ExtensionCommandContext | ExtensionContext, snapshot: Snapshot) {
+	const contextSessionDir = sessionDirFromContext(ctx);
+	const envSessionDir = normalizeOptionalString(process.env.PI_CODING_AGENT_SESSION_DIR);
+	if (envSessionDir) return contextSessionDir ?? expandHome(envSessionDir);
+
+	const localSessionDir = await configuredSessionDir();
+	if (contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")) {
+		return contextSessionDir;
+	}
+	return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
+}
+
+function sessionDirFromSnapshot(snapshot: Snapshot) {
+	const settingsFile = snapshot.files.find((file) => file.path === "settings.json");
+	if (!settingsFile) return undefined;
+	try {
+		const settings = JSON.parse(
+			decodeBase64Strict(settingsFile.contentBase64, settingsFile.path).toString("utf8"),
+		) as { sessionDir?: string };
+		return settings.sessionDir ? expandHome(settings.sessionDir) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function readState(profile: string): Promise<SyncState> {
+	return (
+		(await readJsonIfExists<SyncState>(statePath(profile))) ?? {
+			version: VERSION,
+			profile,
+			lastFileHashes: {},
+		}
+	);
+}
+
+export async function writeState(profile: string, state: SyncState) {
+	await writeJson(statePath(profile), state);
+}
+
+export function agentDir() {
+	const configured = normalizeOptionalString(process.env.PI_CODING_AGENT_DIR);
+	return configured ? expandHome(configured) : path.join(os.homedir(), ".pi", "agent");
+}
+
+function expandHome(value: string) {
+	return value === "~" || value.startsWith("~/")
+		? path.join(os.homedir(), value.slice(2))
+		: value;
+}
+
+export function stateDir() {
+	return path.join(agentDir(), ".pisync");
+}
+
+export function localConfigPath() {
+	return path.join(agentDir(), "pi-sync.local.json");
+}
+
+function statePath(profile: string) {
+	return path.join(stateDir(), `${safeName(profile)}.state.json`);
+}
+
+export function lockPath() {
+	return path.join(stateDir(), "lock");
+}
+
+export async function ensureStateDir() {
+	await fs.mkdir(stateDir(), { recursive: true });
+}
+
+export async function readLock() {
+	return readJsonIfExists<LockFile>(lockPath());
+}
+
+export function isStaleLock(lock: LockFile) {
+	if (!Number.isInteger(lock.pid) || lock.pid <= 0) return true;
+	try {
+		process.kill(lock.pid, 0);
+		return false;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ESRCH") return true;
+		return Date.now() - Date.parse(lock.startedAt) > LOCK_STALE_MS;
+	}
+}
+
+async function readJsonIfExists<T>(filePath: string): Promise<T | undefined> {
+	try {
+		return JSON.parse(await fs.readFile(filePath, "utf8")) as T;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export async function writeJson(filePath: string, value: unknown) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${JSON.stringify(value, null, "\t")}\n`);
+}
+
+function selectSessionToken(fileSessionToken: string | undefined) {
+	if (hasEnv("PI_SYNC_SESSION_TOKEN")) return normalizeOptionalString(process.env.PI_SYNC_SESSION_TOKEN);
+	return normalizeOptionalString(process.env.AWS_SESSION_TOKEN) ?? normalizeOptionalString(fileSessionToken);
+}
+
+export function sessionTokenWarnings(config: { endpoint?: string; sessionToken?: string }) {
+	if (!isCloudflareR2Endpoint(config.endpoint) || !config.sessionToken) return [];
+	return [
+		"session token: configured for Cloudflare R2; if R2 rejects X-Amz-Security-Token, pi-sync retries once without it. R2 static access keys usually do not need a session token.",
+	];
+}
+
+export function syncSessionsWarnings(config: { syncSessions?: boolean }) {
+	if (!config.syncSessions) return [];
+	return [
+		"sessions: enabled; Pi session JSONL can contain prompts, tool output, file paths, images, and secrets. Sync sessions only to storage you trust.",
+	];
+}
+
+function isSecurityTokenInvalidArgument(text: string) {
+	return (
+		text.includes("<Code>InvalidArgument</Code>") &&
+		text.includes("<Message>X-Amz-Security-Token</Message>")
+	);
+}
+
+export function isCloudflareR2Endpoint(endpoint: string | undefined) {
+	const value = endpoint?.trim();
+	if (!value) return false;
+	try {
+		const hostname = new URL(value).hostname.toLowerCase();
+		return hostname === "r2.cloudflarestorage.com" || hostname.endsWith(".r2.cloudflarestorage.com");
+	} catch {
+		return false;
+	}
+}
+
+function normalizeOptionalString(value: string | undefined) {
+	const normalized = value?.trim();
+	return normalized ? normalized : undefined;
+}
+
+export function normalizeExtraFiles(value: unknown) {
+	if (!Array.isArray(value)) return [];
+	const seen = new Set<string>();
+	return value
+		.filter((item): item is string => typeof item === "string")
+		.map((item) => item.trim())
+		.filter((item) => {
+			const lower = item.toLowerCase();
+			if (
+				item === "" ||
+				item === "." ||
+				item === ".." ||
+				item.includes("/") ||
+				item.includes("\\") ||
+				TOP_LEVEL_FILE_NAMES.has(lower) ||
+				isDeniedPath(item) ||
+				RESERVED_TOP_LEVEL_NAMES.has(lower) ||
+				seen.has(lower)
+			) {
+				return false;
+			}
+			seen.add(lower);
+			return true;
+		});
+}
+
+export function extraFilePathsByLower(value: unknown) {
+	return new Map(normalizeExtraFiles(value).map((fileName) => [fileName.toLowerCase(), fileName]));
+}
+
+function selectTopLevelFileEntry(entries: Dirent[], fileName: string) {
+	const exact = entries.find((entry) => entry.isFile() && entry.name === fileName);
+	if (exact) return exact;
+	const lower = fileName.toLowerCase();
+	return entries
+		.filter((entry) => entry.isFile() && entry.name.toLowerCase() === lower)
+		.sort((left, right) => left.name.localeCompare(right.name))[0];
+}
+
+function hasEnv(name: string) {
+	return Object.prototype.hasOwnProperty.call(process.env, name);
+}
+
+export function isEnabled(value: boolean | string | undefined, defaultValue: boolean) {
+	if (value === undefined) return defaultValue;
+	if (typeof value === "boolean") return value;
+	return !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+
+export function isExplicitlyEnabled(value: boolean | string | undefined) {
+	if (typeof value === "boolean") return value;
+	return ["1", "true", "yes", "on"].includes(value?.trim().toLowerCase() ?? "");
+}
+
+export function isMissingConfigError(error: unknown) {
+	return error instanceof Error && error.message.startsWith("Missing pi-sync config:");
+}
+
+function errorMessage(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/paths.ts

@@ -0,0 +1,68 @@
+import path from "node:path";
+
+export function isDeniedPath(relativePath: string) {
+	const normalized = toPosix(relativePath);
+	const lower = normalized.toLowerCase();
+	const segments = lower.split("/");
+	const base = path.posix.basename(lower);
+	return (
+		segments.includes("node_modules") ||
+		segments.includes(".git") ||
+		segments.includes(".pisync") ||
+		base === ".env" ||
+		base.startsWith(".env.") ||
+		base.endsWith(".env") ||
+		base.includes("secret") ||
+		base.includes("token") ||
+		base === "pi-sync.local.json"
+	);
+}
+
+export function isPathInside(parent: string, child: string) {
+	const relative = path.relative(path.resolve(parent), path.resolve(child));
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function safeJoin(root: string, relativePath: string) {
+	const target = path.resolve(root, relativePath);
+	assertWithinRoot(root, target, relativePath);
+	return target;
+}
+
+export function assertWithinRoot(root: string, target: string, label = target) {
+	const resolvedRoot = path.resolve(root);
+	const resolvedTarget = path.resolve(target);
+	if (resolvedTarget !== resolvedRoot && !resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`)) {
+		throw new Error(`Unsafe path in snapshot: ${label}`);
+	}
+}
+
+export function encodeKey(key: string) {
+	return key.split("/").map(encodeURIComponent).join("/");
+}
+
+export function posixJoin(...parts: string[]) {
+	return parts.map((part) => trimSlashes(part)).filter(Boolean).join("/");
+}
+
+export function parentPaths(relativePath: string) {
+	const results: string[] = [];
+	let index = relativePath.lastIndexOf("/");
+	while (index > 0) {
+		results.push(relativePath.slice(0, index));
+		index = relativePath.lastIndexOf("/", index - 1);
+	}
+	return results;
+}
+
+export function toPosix(value: string) {
+	return value.split(path.sep).join("/");
+}
+
+function trimSlashes(value: string) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+
+export function safeName(value: string) {
+	return value.replace(/[^A-Za-z0-9._-]/g, "_");
+}