@hex4c59/pi-ext-config-sync 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/files.ts ADDED
@@ -0,0 +1,430 @@
1
+ import { randomBytes, randomUUID } from "node:crypto";
2
+ import type { Dirent, Stats } from "node:fs";
3
+ import { copyFile, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
4
+ import { dirname, join, resolve, sep } from "node:path";
5
+ import { setTimeout as sleep } from "node:timers/promises";
6
+ import {
7
+ AGENT_PATH_PREFIX,
8
+ AUTH_PROVIDER_ID,
9
+ CONFIG_SYNC_DIR,
10
+ DEFAULT_EXCLUDE_AUTH_PROVIDERS,
11
+ DEFAULT_LOCAL_SETTINGS_KEYS,
12
+ SyncError,
13
+ } from "./types.ts";
14
+ import type { SyncConfig, SyncState } from "./types.ts";
15
+
16
+ const CONFIG_FILE = "config.json";
17
+ const STATE_FILE = "state.json";
18
+ const AUTH_FILE = "auth.json";
19
+ const MAX_BACKUPS = 10;
20
+ const AUTH_LOCK_RETRIES = 20;
21
+ const AUTH_LOCK_RETRY_MS = 100;
22
+ const AUTH_LOCK_STALE_MS = 60_000;
23
+
24
+ export function isRecord(value: unknown): value is Record<string, unknown> {
25
+ return typeof value === "object" && value !== null && !Array.isArray(value);
26
+ }
27
+
28
+ export function normalizeRelativePath(input: string): string {
29
+ if (input.length === 0) throw new SyncError("Empty file path in sync data.");
30
+ if (input.startsWith("/")) throw new SyncError(`Absolute path is not allowed: ${input}`);
31
+ if (input.includes("\\") || input.includes("\0") || input.includes(":")) {
32
+ throw new SyncError(`Unsafe file path in sync data: ${input}`);
33
+ }
34
+ const segments = input.split("/");
35
+ if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
36
+ throw new SyncError(`Unsafe file path in sync data: ${input}`);
37
+ }
38
+ return segments.join("/");
39
+ }
40
+
41
+ export function localToRemotePath(relativePath: string): string {
42
+ return `${AGENT_PATH_PREFIX}${normalizeRelativePath(relativePath)}`;
43
+ }
44
+
45
+ export function remoteToLocalPath(agentDir: string, remotePath: string): string {
46
+ if (!remotePath.startsWith(AGENT_PATH_PREFIX)) {
47
+ throw new SyncError(`Unexpected remote path: ${remotePath}`);
48
+ }
49
+ const relativePath = normalizeRelativePath(remotePath.slice(AGENT_PATH_PREFIX.length));
50
+ return resolveAgentPath(agentDir, relativePath);
51
+ }
52
+
53
+ export function resolveAgentPath(agentDir: string, relativePath: string): string {
54
+ const root = resolve(agentDir);
55
+ const target = resolve(root, ...normalizeRelativePath(relativePath).split("/"));
56
+ if (!target.startsWith(`${root}${sep}`)) {
57
+ throw new SyncError(`File path escapes the agent directory: ${relativePath}`);
58
+ }
59
+ return target;
60
+ }
61
+
62
+ export function isAgentRemotePath(remotePath: string): boolean {
63
+ if (!remotePath.startsWith(AGENT_PATH_PREFIX)) return false;
64
+ try {
65
+ normalizeRelativePath(remotePath.slice(AGENT_PATH_PREFIX.length));
66
+ return true;
67
+ } catch {
68
+ return false;
69
+ }
70
+ }
71
+
72
+ export async function lstatOrUndefined(path: string): Promise<Stats | undefined> {
73
+ try {
74
+ return await lstat(path);
75
+ } catch (error) {
76
+ if (errorCode(error) === "ENOENT") return undefined;
77
+ throw error;
78
+ }
79
+ }
80
+
81
+ export async function readdirOrUndefined(path: string): Promise<Dirent[] | undefined> {
82
+ try {
83
+ return await readdir(path, { withFileTypes: true });
84
+ } catch (error) {
85
+ if (errorCode(error) === "ENOENT") return undefined;
86
+ throw error;
87
+ }
88
+ }
89
+
90
+ export async function readTextFile(path: string): Promise<string | undefined> {
91
+ try {
92
+ return await readFile(path, "utf8");
93
+ } catch (error) {
94
+ if (errorCode(error) === "ENOENT") return undefined;
95
+ throw error;
96
+ }
97
+ }
98
+
99
+ export async function readJsonFile(path: string): Promise<unknown | undefined> {
100
+ const text = await readTextFile(path);
101
+ if (text === undefined) return undefined;
102
+ try {
103
+ return JSON.parse(text);
104
+ } catch {
105
+ throw new SyncError(`Invalid JSON in ${path}. Fix the file before syncing.`);
106
+ }
107
+ }
108
+
109
+ export async function writeJsonFile(path: string, value: unknown): Promise<void> {
110
+ await atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
111
+ }
112
+
113
+ export async function writeBytesFile(path: string, bytes: Buffer): Promise<void> {
114
+ await atomicWrite(path, bytes);
115
+ }
116
+
117
+ async function atomicWrite(target: string, data: Buffer | string, mode?: number): Promise<void> {
118
+ await mkdir(dirname(target), { recursive: true });
119
+ const temp = `${target}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
120
+ try {
121
+ await writeFile(temp, data, mode === undefined ? undefined : { mode });
122
+ try {
123
+ await rename(temp, target);
124
+ } catch (error) {
125
+ const code = errorCode(error);
126
+ if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES") throw error;
127
+ await rm(target, { force: true });
128
+ await rename(temp, target);
129
+ }
130
+ } finally {
131
+ await rm(temp, { force: true });
132
+ }
133
+ }
134
+
135
+ export function syncDir(agentDir: string): string {
136
+ return join(agentDir, CONFIG_SYNC_DIR);
137
+ }
138
+
139
+ function configPath(agentDir: string): string {
140
+ return join(syncDir(agentDir), CONFIG_FILE);
141
+ }
142
+
143
+ function statePath(agentDir: string): string {
144
+ return join(syncDir(agentDir), STATE_FILE);
145
+ }
146
+
147
+ export function authPath(agentDir: string): string {
148
+ return join(agentDir, AUTH_FILE);
149
+ }
150
+
151
+ export function defaultConfig(): SyncConfig {
152
+ return {
153
+ version: 1,
154
+ clientId: "",
155
+ repo: "",
156
+ branch: "",
157
+ autoPull: false,
158
+ allowPublicRepo: false,
159
+ localSettingsKeys: [...DEFAULT_LOCAL_SETTINGS_KEYS],
160
+ includeAuthProviders: [],
161
+ excludeAuthProviders: [...DEFAULT_EXCLUDE_AUTH_PROVIDERS],
162
+ };
163
+ }
164
+
165
+ export async function loadConfig(agentDir: string): Promise<SyncConfig> {
166
+ const raw = await readJsonFile(configPath(agentDir));
167
+ const defaults = defaultConfig();
168
+ if (raw === undefined) return defaults;
169
+ if (!isRecord(raw)) throw new SyncError("config-sync config must be a JSON object.");
170
+ if (raw.version !== undefined && raw.version !== 1) {
171
+ throw new SyncError(`Unsupported config-sync config version: ${String(raw.version)}`);
172
+ }
173
+ return {
174
+ version: 1,
175
+ clientId: readString(raw.clientId, defaults.clientId, "clientId"),
176
+ repo: readString(raw.repo, defaults.repo, "repo"),
177
+ branch: readString(raw.branch, defaults.branch, "branch"),
178
+ autoPull: readBoolean(raw.autoPull, defaults.autoPull, "autoPull"),
179
+ allowPublicRepo: readBoolean(raw.allowPublicRepo, defaults.allowPublicRepo, "allowPublicRepo"),
180
+ localSettingsKeys: readStringArray(
181
+ raw.localSettingsKeys,
182
+ defaults.localSettingsKeys,
183
+ "localSettingsKeys",
184
+ ),
185
+ includeAuthProviders: readStringArray(
186
+ raw.includeAuthProviders,
187
+ defaults.includeAuthProviders,
188
+ "includeAuthProviders",
189
+ ),
190
+ excludeAuthProviders: readStringArray(
191
+ raw.excludeAuthProviders,
192
+ defaults.excludeAuthProviders,
193
+ "excludeAuthProviders",
194
+ ),
195
+ };
196
+ }
197
+
198
+ export async function saveConfig(agentDir: string, config: SyncConfig): Promise<void> {
199
+ await writeJsonFile(configPath(agentDir), config);
200
+ }
201
+
202
+ function readString(value: unknown, fallback: string, field: string): string {
203
+ if (value === undefined) return fallback;
204
+ if (typeof value !== "string") throw new SyncError(`config-sync config field "${field}" must be a string.`);
205
+ return value;
206
+ }
207
+
208
+ function readBoolean(value: unknown, fallback: boolean, field: string): boolean {
209
+ if (value === undefined) return fallback;
210
+ if (typeof value !== "boolean") throw new SyncError(`config-sync config field "${field}" must be a boolean.`);
211
+ return value;
212
+ }
213
+
214
+ function readStringArray(value: unknown, fallback: string[], field: string): string[] {
215
+ if (value === undefined) return [...fallback];
216
+ if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
217
+ throw new SyncError(`config-sync config field "${field}" must be an array of strings.`);
218
+ }
219
+ return [...value];
220
+ }
221
+
222
+ function newState(): SyncState {
223
+ return {
224
+ version: 1,
225
+ deviceId: randomUUID(),
226
+ login: "",
227
+ scopes: [],
228
+ base: null,
229
+ lastSync: null,
230
+ };
231
+ }
232
+
233
+ export async function loadState(agentDir: string): Promise<{ state: SyncState; warning?: string }> {
234
+ const path = statePath(agentDir);
235
+ const text = await readTextFile(path);
236
+ if (text === undefined) {
237
+ const state = newState();
238
+ await saveState(agentDir, state);
239
+ return { state };
240
+ }
241
+ try {
242
+ const parsed: unknown = JSON.parse(text);
243
+ return { state: parseState(parsed) };
244
+ } catch (error) {
245
+ const backup = `${path}.corrupt-${Date.now()}`;
246
+ try {
247
+ await rename(path, backup);
248
+ } catch (renameError) {
249
+ if (errorCode(renameError) !== "ENOENT") throw renameError;
250
+ }
251
+ const state = newState();
252
+ await saveState(agentDir, state);
253
+ return {
254
+ state,
255
+ warning: `config-sync state was invalid and was moved to ${backup}: ${errorMessage(error)}`,
256
+ };
257
+ }
258
+ }
259
+
260
+ function parseState(value: unknown): SyncState {
261
+ if (!isRecord(value) || value.version !== 1) throw new SyncError("Invalid state version.");
262
+ if (typeof value.deviceId !== "string" || value.deviceId.length === 0) {
263
+ throw new SyncError("Invalid state deviceId.");
264
+ }
265
+ const login = typeof value.login === "string" ? value.login : "";
266
+ const scopes = Array.isArray(value.scopes) && value.scopes.every((entry) => typeof entry === "string")
267
+ ? [...value.scopes]
268
+ : [];
269
+ const base = value.base === null || value.base === undefined ? null : parseBase(value.base);
270
+ const lastSync = value.lastSync === null || value.lastSync === undefined
271
+ ? null
272
+ : parseRecord(value.lastSync);
273
+ return { version: 1, deviceId: value.deviceId, login, scopes, base, lastSync };
274
+ }
275
+
276
+ function parseBase(value: unknown): SyncState["base"] {
277
+ if (!isRecord(value) || typeof value.commit !== "string" || !isRecord(value.hashes)) {
278
+ throw new SyncError("Invalid state base.");
279
+ }
280
+ const hashes: Record<string, string> = {};
281
+ for (const [path, hash] of Object.entries(value.hashes)) {
282
+ if (typeof hash !== "string") throw new SyncError("Invalid state file hash.");
283
+ hashes[path] = hash;
284
+ }
285
+ return { commit: value.commit, hashes };
286
+ }
287
+
288
+ function parseRecord(value: unknown): SyncState["lastSync"] {
289
+ if (!isRecord(value)) throw new SyncError("Invalid state record.");
290
+ const action = value.action === "pull" || value.action === "push" ? value.action : null;
291
+ if (action === null) throw new SyncError("Invalid state record action.");
292
+ if (typeof value.at !== "string" || typeof value.commit !== "string") {
293
+ throw new SyncError("Invalid state record fields.");
294
+ }
295
+ const files = typeof value.files === "number" ? value.files : 0;
296
+ const conflicts = typeof value.conflicts === "number" ? value.conflicts : 0;
297
+ return { action, at: value.at, commit: value.commit, files, conflicts };
298
+ }
299
+
300
+ export async function saveState(agentDir: string, state: SyncState): Promise<void> {
301
+ await writeJsonFile(statePath(agentDir), state);
302
+ }
303
+
304
+ export async function readAuthObject(agentDir: string): Promise<Record<string, unknown>> {
305
+ const text = await readTextFile(authPath(agentDir));
306
+ if (text === undefined) return {};
307
+ try {
308
+ const parsed: unknown = JSON.parse(text);
309
+ if (!isRecord(parsed)) throw new SyncError("auth.json must contain a JSON object.");
310
+ return parsed;
311
+ } catch (error) {
312
+ if (error instanceof SyncError) throw error;
313
+ throw new SyncError("auth.json is not valid JSON. Fix it before syncing credentials.");
314
+ }
315
+ }
316
+
317
+ export async function readSyncToken(agentDir: string): Promise<string | null> {
318
+ const auth = await readAuthObject(agentDir);
319
+ const entry = auth[AUTH_PROVIDER_ID];
320
+ if (!isRecord(entry) || typeof entry.key !== "string" || entry.key.length === 0) return null;
321
+ return entry.key;
322
+ }
323
+
324
+ export async function storeSyncToken(agentDir: string, token: string | null): Promise<void> {
325
+ await withAuthLock(agentDir, async () => {
326
+ const auth = await readAuthObject(agentDir);
327
+ if (token === null) {
328
+ if (auth[AUTH_PROVIDER_ID] === undefined) return;
329
+ delete auth[AUTH_PROVIDER_ID];
330
+ } else {
331
+ auth[AUTH_PROVIDER_ID] = { type: "api_key", key: token };
332
+ }
333
+ const text = `${JSON.stringify(auth, null, 2)}\n`;
334
+ await atomicWrite(authPath(agentDir), text, 0o600);
335
+ });
336
+ }
337
+
338
+ export async function updateAuthEntries(
339
+ agentDir: string,
340
+ update: (auth: Record<string, unknown>) => void,
341
+ ): Promise<void> {
342
+ await withAuthLock(agentDir, async () => {
343
+ const auth = await readAuthObject(agentDir);
344
+ update(auth);
345
+ const text = `${JSON.stringify(auth, null, 2)}\n`;
346
+ await atomicWrite(authPath(agentDir), text, 0o600);
347
+ });
348
+ }
349
+
350
+ // 与 proper-lockfile 使用同名的 "<auth.json>.lock" 目录,避免 pi 和本扩展同时写入 auth.json。
351
+ async function withAuthLock<T>(agentDir: string, fn: () => Promise<T>): Promise<T> {
352
+ const path = authPath(agentDir);
353
+ await mkdir(dirname(path), { recursive: true });
354
+ const lockPath = `${path}.lock`;
355
+ let acquired = false;
356
+ for (let attempt = 0; attempt < AUTH_LOCK_RETRIES; attempt++) {
357
+ try {
358
+ await mkdir(lockPath);
359
+ acquired = true;
360
+ break;
361
+ } catch (error) {
362
+ if (errorCode(error) !== "EEXIST") throw error;
363
+ const info = await lstatOrUndefined(lockPath);
364
+ if (info !== undefined && Date.now() - info.mtimeMs > AUTH_LOCK_STALE_MS) {
365
+ await rm(lockPath, { recursive: true, force: true });
366
+ continue;
367
+ }
368
+ await sleep(AUTH_LOCK_RETRY_MS);
369
+ }
370
+ }
371
+ if (!acquired) {
372
+ throw new SyncError("auth.json is locked by another process. Wait a moment and retry.");
373
+ }
374
+ try {
375
+ return await fn();
376
+ } finally {
377
+ await rm(lockPath, { recursive: true, force: true });
378
+ }
379
+ }
380
+
381
+ export async function backupLocalFiles(
382
+ agentDir: string,
383
+ relativePaths: string[],
384
+ ): Promise<string | null> {
385
+ if (relativePaths.length === 0) return null;
386
+ const stamp = new Date().toISOString().replace(/[:.]/g, "-");
387
+ const backupRoot = join(syncDir(agentDir), "backups", stamp);
388
+ let copied = 0;
389
+ for (const relativePath of relativePaths) {
390
+ const source = resolveAgentPath(agentDir, relativePath);
391
+ const info = await lstatOrUndefined(source);
392
+ if (info === undefined || !info.isFile()) continue;
393
+ const target = join(backupRoot, AGENT_PATH_PREFIX, ...relativePath.split("/"));
394
+ await mkdir(dirname(target), { recursive: true });
395
+ await copyFile(source, target);
396
+ copied++;
397
+ }
398
+ if (copied === 0) {
399
+ await rm(backupRoot, { recursive: true, force: true });
400
+ return null;
401
+ }
402
+ await pruneBackups(agentDir);
403
+ return backupRoot;
404
+ }
405
+
406
+ async function pruneBackups(agentDir: string): Promise<void> {
407
+ const root = join(syncDir(agentDir), "backups");
408
+ const entries = await readdirOrUndefined(root);
409
+ if (entries === undefined) return;
410
+ const directories = entries
411
+ .filter((entry) => entry.isDirectory())
412
+ .map((entry) => entry.name)
413
+ .sort()
414
+ .reverse();
415
+ for (const name of directories.slice(MAX_BACKUPS)) {
416
+ await rm(join(root, name), { recursive: true, force: true });
417
+ }
418
+ }
419
+
420
+ export function errorCode(error: unknown): string | undefined {
421
+ if (typeof error === "object" && error !== null && "code" in error) {
422
+ const code = error.code;
423
+ if (typeof code === "string") return code;
424
+ }
425
+ return undefined;
426
+ }
427
+
428
+ export function errorMessage(error: unknown): string {
429
+ return error instanceof Error ? error.message : String(error);
430
+ }