@narumitw/pi-sync-daemon 0.7.0 → 0.9.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.
Files changed (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -0,0 +1,393 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { lstatSync } from "node:fs";
3
+ import fs from "node:fs/promises";
4
+ import path from "node:path";
5
+ import { requireHandover } from "../../consent.js";
6
+ import { documentFingerprint } from "../../document.js";
7
+ import { MAX_REVIEW_BYTES, record } from "../../protocol.js";
8
+ import { createServiceContext } from "../../service-host.js";
9
+ import { createSyncBackend } from "../backends/backend-factory.js";
10
+ import { engineHost } from "../host.js";
11
+ import { configFromSettings } from "../settings/config.js";
12
+ import { peekLocalConfigDocument, updateLocalConfigDocument, } from "../settings/config-file.js";
13
+ import { validateConfigName, validateSettingsDocument } from "../settings/settings-validation.js";
14
+ import { resolvedSnapshotOptionsForContext } from "../snapshot/session-paths.js";
15
+ import { createSnapshot } from "../snapshot/snapshot.js";
16
+ import { pendingTransactionEntries } from "../snapshot/snapshot-transaction-directory.js";
17
+ import { syncDirectory } from "../state/json-file.js";
18
+ import { withLock } from "../state/lock.js";
19
+ import { stateDir, withStateDirectoryAccess } from "../state/state-directory.js";
20
+ import { requireNoMergeJournal } from "../sync/merge-journal.js";
21
+ import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
22
+ import { safeTerminalText, snapshotPathLabel } from "../ui/terminal-text.js";
23
+ import { compileEffectiveIgnorePolicy } from "./effective-ignore-policy.js";
24
+ import { AutomaticIgnoreCreationUnavailable, checkAutomaticIgnoreCreation, prepareDefaultIgnoreSource, } from "./ignore-initialization.js";
25
+ import { assertCurrentIgnoreMigrationOffer } from "./ignore-migration-prompt.js";
26
+ import { compileIgnoreRules, DEFAULT_IGNORE_CREATION_RECORD, DEFAULT_IGNORE_FILENAME, DEFAULT_IGNORE_RULES, IgnoreCreationPendingError, ignoreSourceDigest, readIgnoreSource, validateIgnoreFilename, } from "./ignore-source.js";
27
+ export function runIgnorePolicyChange(operation, payload, execution) {
28
+ if (!record(payload) || typeof payload.setup !== "string")
29
+ throw new Error("Invalid ignore-file policy request.");
30
+ const { setup } = payload;
31
+ validateConfigName(setup, "sync setup");
32
+ if (operation === "ignore.migrate") {
33
+ const { offerToken } = payload;
34
+ if (Object.keys(payload).some((key) => key !== "setup" && key !== "offerToken") ||
35
+ (offerToken !== undefined && (typeof offerToken !== "string" || !/^[a-f0-9]{64}$/u.test(offerToken))))
36
+ throw new Error("Invalid ignore-file migration request.");
37
+ if (offerToken !== undefined && execution.facts()?.mode !== "tui")
38
+ throw new Error("Ignore migration offers require an attached TUI client.");
39
+ return migrateIgnoreSetup(execution, setup, offerToken);
40
+ }
41
+ const { filename, expectedFilename } = payload;
42
+ if (typeof filename !== "string" ||
43
+ typeof expectedFilename !== "string" ||
44
+ Object.keys(payload).some((key) => key !== "setup" && key !== "filename" && key !== "expectedFilename"))
45
+ throw new Error("Invalid ignore-file switch request.");
46
+ return switchIgnoreFile(execution, setup, filename, expectedFilename);
47
+ }
48
+ function sourceToken(document) {
49
+ return documentFingerprint(document ? { bytes: document.bytes.toString("base64"), identity: document.identity } : undefined);
50
+ }
51
+ function settingsReviewGuard(document, execution) {
52
+ const token = sourceToken(document);
53
+ return (candidate) => {
54
+ execution.validate();
55
+ if (document.path !== candidate?.path || token !== sourceToken(candidate))
56
+ stale();
57
+ };
58
+ }
59
+ function ignoreFilename(setup) {
60
+ return setup?.sync.pathPolicy === "ignore-file"
61
+ ? validateIgnoreFilename(setup.sync.ignoreFile ?? DEFAULT_IGNORE_FILENAME)
62
+ : undefined;
63
+ }
64
+ function configuredFilenames(settings) {
65
+ return Object.values(settings.syncSetups).flatMap((setup) => {
66
+ const filename = ignoreFilename(setup);
67
+ return filename ? [filename] : [];
68
+ });
69
+ }
70
+ export function newIgnoreFilename(before, next) {
71
+ let added;
72
+ for (const [name, setup] of Object.entries(next.syncSetups)) {
73
+ const previous = before && Object.hasOwn(before.syncSetups, name) ? before.syncSetups[name] : undefined;
74
+ const filename = ignoreFilename(setup);
75
+ if (previous && ignoreFilename(previous) !== filename) {
76
+ throw new Error("Use the reviewed Pi Sync ignore-file settings flow to change an existing setup policy.");
77
+ }
78
+ if (!previous && filename) {
79
+ if (added !== undefined)
80
+ throw new Error("Create one ignore-file setup at a time so its policy can be reviewed.");
81
+ added = filename;
82
+ }
83
+ }
84
+ return added;
85
+ }
86
+ async function readSetupSource(root, filename, signal) {
87
+ try {
88
+ return await readIgnoreSource(root, filename, signal);
89
+ }
90
+ catch (error) {
91
+ signal.throwIfAborted();
92
+ if (filename !== DEFAULT_IGNORE_FILENAME ||
93
+ !(error instanceof Error) ||
94
+ !(error.cause instanceof IgnoreCreationPendingError))
95
+ throw error;
96
+ if ((await fs.realpath(root)) !== root)
97
+ throw error;
98
+ const marker = await fs.lstat(path.join(root, DEFAULT_IGNORE_CREATION_RECORD), { bigint: true });
99
+ signal.throwIfAborted();
100
+ if (!marker.isFile() || marker.nlink !== 1n)
101
+ throw error;
102
+ return {
103
+ filename,
104
+ present: false,
105
+ text: DEFAULT_IGNORE_RULES,
106
+ sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(DEFAULT_IGNORE_RULES)),
107
+ pendingCreation: `${marker.dev}:${marker.ino}:${marker.size}:${marker.ctimeNs}:${marker.mtimeNs}`,
108
+ };
109
+ }
110
+ }
111
+ async function readPolicyReviewSource(root, filename, execution, allowCreation) {
112
+ const { signal } = execution;
113
+ execution.validate();
114
+ signal.throwIfAborted();
115
+ filename = validateIgnoreFilename(filename);
116
+ if (filename !== DEFAULT_IGNORE_FILENAME &&
117
+ lstatSync(path.resolve(root), { throwIfNoEntry: false })?.isDirectory() &&
118
+ !lstatSync(path.resolve(root, filename), { throwIfNoEntry: false })) {
119
+ throw manualCreationRequired(root, filename);
120
+ }
121
+ const source = await (allowCreation
122
+ ? readSetupSource(root, filename, signal)
123
+ : readIgnoreSource(root, filename, signal));
124
+ execution.validate();
125
+ if (source.present)
126
+ return source;
127
+ if (!allowCreation)
128
+ throw manualCreationRequired(root, filename);
129
+ await checkAutomaticIgnoreCreation(root, signal).catch((error) => {
130
+ execution.validate();
131
+ throw creationFailure(root, source, error);
132
+ });
133
+ execution.validate();
134
+ return source;
135
+ }
136
+ function manualCreationRequired(root, filename, cause) {
137
+ return new Error(`Ignore file does not exist: ${snapshotPathLabel(path.resolve(root, filename))}\n` +
138
+ `${cause ? `${cause.message}. ` : ""}Create a regular UTF-8 text file there manually with these starter rules, then retry the Pi Sync policy change:\n${DEFAULT_IGNORE_RULES}`, { cause });
139
+ }
140
+ function creationFailure(root, source, error) {
141
+ if (!(error instanceof AutomaticIgnoreCreationUnavailable))
142
+ return error;
143
+ if (!source.pendingCreation)
144
+ return manualCreationRequired(root, source.filename, error);
145
+ return new Error(`Interrupted creation of ${snapshotPathLabel(path.resolve(root, source.filename))}. ${error.message}. ` +
146
+ `Preserve the rule file and creation record ${snapshotPathLabel(path.resolve(root, DEFAULT_IGNORE_CREATION_RECORD))}. ` +
147
+ "Retry the reviewed Pi Sync policy change where safe automatic recovery is available.", { cause: error });
148
+ }
149
+ export async function reviewNewIgnoreSource(root, filename, execution) {
150
+ const ctx = requireInteractive(execution);
151
+ const source = await readPolicyReviewSource(root, filename, execution, true);
152
+ compileIgnoreRules(source.text);
153
+ const description = describeSource(source);
154
+ if (!(await confirm(ctx, execution, "Review ignore-file policy", [
155
+ `Rules: ${safeTerminalText(path.join(root, filename))}`,
156
+ description,
157
+ "Every eligible path not excluded by the rules can be synced, including new files added later.",
158
+ "Saving this setup does not transfer files. Review the selected content before transferring.",
159
+ ].join("\n"))))
160
+ throw new Error("Setup cancelled; no settings or rule files were saved.");
161
+ return source;
162
+ }
163
+ export async function prepareReviewedIgnoreSource(root, reviewed, execution) {
164
+ execution.validate();
165
+ const current = await readSetupSource(root, reviewed.filename, execution.signal);
166
+ execution.validate();
167
+ if (current.sourceDigest !== reviewed.sourceDigest ||
168
+ current.identity !== reviewed.identity ||
169
+ current.pendingCreation !== reviewed.pendingCreation)
170
+ stale();
171
+ if (current.present)
172
+ return { source: current, created: false };
173
+ const prepared = await prepareDefaultIgnoreSource(root, execution.signal).catch((error) => {
174
+ execution.validate();
175
+ throw creationFailure(root, current, error);
176
+ });
177
+ execution.validate();
178
+ if (!prepared.source.present ||
179
+ prepared.source.text !== reviewed.text ||
180
+ (!current.pendingCreation && !prepared.created))
181
+ stale();
182
+ return prepared;
183
+ }
184
+ export async function switchIgnoreFile(execution, setupName, filename, expectedFilename) {
185
+ const ctx = requireInteractive(execution);
186
+ filename = validateIgnoreFilename(filename);
187
+ expectedFilename = validateIgnoreFilename(expectedFilename);
188
+ if (expectedFilename !== filename) {
189
+ await readPolicyReviewSource(execution.root, filename, execution, false);
190
+ execution.validate();
191
+ }
192
+ await requireHandover(execution);
193
+ execution.validate();
194
+ return withStateDirectoryAccess(() => withLock("sync", async () => {
195
+ const document = await peekLocalConfigDocument();
196
+ execution.validate();
197
+ if (!document)
198
+ throw new Error("No Pi Sync settings are configured.");
199
+ const settings = validateSettingsDocument(document.parsed);
200
+ const setup = Object.hasOwn(settings.syncSetups, setupName) ? settings.syncSetups[setupName] : undefined;
201
+ if (ignoreFilename(setup) !== expectedFilename)
202
+ stale();
203
+ if (expectedFilename === filename)
204
+ return "saved";
205
+ if ((await pendingTransactionEntries()).some((entry) => entry.isDirectory()))
206
+ throw new Error("Resolve pending local recovery before changing the content policy.");
207
+ await requireNoMergeJournal(configFromSettings(settings, setupName));
208
+ const source = await readPolicyReviewSource(execution.root, filename, execution, false);
209
+ execution.validate();
210
+ compileIgnoreRules(source.text);
211
+ if (!(await confirm(ctx, execution, "Review changing the ignore file", [
212
+ `Setup: ${safeTerminalText(setupName)}`,
213
+ `Existing rule file to use: ${safeTerminalText(path.join(execution.root, filename))}`,
214
+ "Changing the file can add or remove paths from future transfers. No transfer starts when you save.",
215
+ ].join("\n"))))
216
+ return "cancelled";
217
+ await updateLocalConfigDocument(settings, (next) => {
218
+ next.syncSetups[setupName].sync.ignoreFile = filename;
219
+ return next;
220
+ }, validateSettingsDocument, execution.signal, settingsReviewGuard(document, execution), async () => {
221
+ await prepareReviewedIgnoreSource(execution.root, source, execution);
222
+ });
223
+ execution.committed();
224
+ return "saved";
225
+ }));
226
+ }
227
+ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
228
+ const ctx = requireInteractive(execution);
229
+ await readPolicyReviewSource(execution.root, DEFAULT_IGNORE_FILENAME, execution, true);
230
+ execution.validate();
231
+ await requireHandover(execution);
232
+ execution.validate();
233
+ return withStateDirectoryAccess(() => withLock("sync", async () => {
234
+ const document = await peekLocalConfigDocument();
235
+ execution.validate();
236
+ if (!document)
237
+ throw new Error("No Pi Sync settings to migrate.");
238
+ const guardSettings = settingsReviewGuard(document, execution);
239
+ const validateReview = (candidate) => {
240
+ guardSettings(candidate);
241
+ if (offerToken !== undefined)
242
+ assertCurrentIgnoreMigrationOffer(candidate, execution.root, setupName, offerToken);
243
+ };
244
+ validateReview(document);
245
+ const before = validateSettingsDocument(document.parsed);
246
+ const setup = Object.hasOwn(before.syncSetups, setupName) ? before.syncSetups[setupName] : undefined;
247
+ if (!setup || ignoreFilename(setup))
248
+ throw new Error("Choose a legacy Pi Sync setup to migrate.");
249
+ const previous = configFromSettings(before, setupName);
250
+ if ((await pendingTransactionEntries()).some((entry) => entry.isDirectory())) {
251
+ throw new Error("Resolve pending local recovery before changing the content policy.");
252
+ }
253
+ await requireNoMergeJournal(previous);
254
+ execution.validate();
255
+ const next = structuredClone(before);
256
+ const policy = next.syncSetups[setupName].sync;
257
+ const { include: _include, exclude: _exclude, reinclude: _reinclude, ...common } = policy;
258
+ const sessions = policy.scope === "agent-directory" ? policy.sessions === true : previous.include.includes("sessions");
259
+ next.syncSetups[setupName].sync = { ...common, scope: "agent-directory", sessions, pathPolicy: "ignore-file" };
260
+ next.version = 8;
261
+ validateSettingsDocument(next);
262
+ const source = await readPolicyReviewSource(execution.root, DEFAULT_IGNORE_FILENAME, execution, true);
263
+ execution.validate();
264
+ const current = {
265
+ ...configFromSettings(next, setupName),
266
+ ignorePolicy: compileEffectiveIgnorePolicy(source, {
267
+ sessions,
268
+ configuredFilenames: configuredFilenames(next),
269
+ }),
270
+ };
271
+ const backend = await createSyncBackend(previous);
272
+ execution.validate();
273
+ const head = await backend.readHead(execution.signal);
274
+ execution.validate();
275
+ const remote = head ? await backend.readSnapshot(head.snapshotRef, execution.signal) : undefined;
276
+ execution.validate();
277
+ if (head && remote?.id !== head.snapshotId)
278
+ throw new Error("The remote snapshot changed during inspection.");
279
+ const collectPaths = async (config) => {
280
+ const options = await resolvedSnapshotOptionsForContext(ctx, config, execution.signal);
281
+ execution.validate();
282
+ const image = await createSnapshot(config.snapshotIdentity, options);
283
+ execution.validate();
284
+ return image.files.map(({ path }) => path).sort();
285
+ };
286
+ const collect = async (createdStarter) => {
287
+ const oldPaths = (await collectPaths(previous)).filter((name) => name !== createdStarter);
288
+ const newPaths = await collectPaths(current);
289
+ const fingerprint = createHash("sha256")
290
+ .update(JSON.stringify([oldPaths, newPaths]))
291
+ .digest("hex");
292
+ return { oldPaths, newPaths, fingerprint };
293
+ };
294
+ const review = await collect();
295
+ execution.validate();
296
+ const remotePaths = remote?.files.map(({ path }) => path) ?? [];
297
+ const content = [
298
+ `Destination: ${safeTerminalText(backend.destination)}`,
299
+ `Ignore file: ${safeTerminalText(path.join(execution.root, source.filename))}`,
300
+ describeSource(source),
301
+ "Directory-wide selection also applies to future files. Legacy rules are not translated automatically.",
302
+ "Migration changes this setup only. No transfer starts and retained history is not erased.",
303
+ ...describeChanges("Local", review.oldPaths, review.newPaths),
304
+ ...(remote
305
+ ? describeChanges("Remote", remotePaths.filter(configuredSnapshotPathMatcher(previous)), remotePaths.filter(configuredSnapshotPathMatcher(current)))
306
+ : ["Remote: no published snapshot."]),
307
+ ].join("\n");
308
+ if (!(await confirm(ctx, execution, "Review migration to ignore-file policy", content)))
309
+ return "cancelled";
310
+ const verifyHead = (fresh) => {
311
+ if (head
312
+ ? !fresh || head.snapshotId !== fresh.snapshotId || !backend.sameRevision(head.revision, fresh.revision)
313
+ : fresh)
314
+ stale();
315
+ };
316
+ await updateLocalConfigDocument(next, () => next, validateSettingsDocument, execution.signal, validateReview, async () => {
317
+ verifyHead(await backend.readHead(execution.signal));
318
+ execution.validate();
319
+ if (!source.present && (await collect()).fingerprint !== review.fingerprint)
320
+ stale();
321
+ execution.validate();
322
+ const { source: prepared, created } = await prepareReviewedIgnoreSource(execution.root, source, execution);
323
+ execution.validate();
324
+ await preserveLegacySettings(document);
325
+ execution.validate();
326
+ verifyHead(await backend.readHead(execution.signal));
327
+ execution.validate();
328
+ if ((await collect(created ? prepared.filename : undefined)).fingerprint !== review.fingerprint)
329
+ stale();
330
+ execution.validate();
331
+ verifyHead(await backend.readHead(execution.signal));
332
+ execution.validate();
333
+ const finalSource = await readIgnoreSource(execution.root, source.filename, execution.signal);
334
+ execution.validate();
335
+ if (!finalSource.present ||
336
+ finalSource.sourceDigest !== prepared.sourceDigest ||
337
+ finalSource.identity !== prepared.identity)
338
+ stale();
339
+ });
340
+ execution.committed();
341
+ return "saved";
342
+ }));
343
+ }
344
+ function describeSource(source) {
345
+ if (source.pendingCreation)
346
+ return "Verify or complete the interrupted creation of the starter rules. Incomplete content will not be used.";
347
+ return source.present
348
+ ? "Keep the existing rule file unchanged."
349
+ : "Create the default rule file with the starter rules.";
350
+ }
351
+ function describeChanges(label, before, after) {
352
+ const oldPaths = new Set(before);
353
+ const newPaths = new Set(after);
354
+ return [
355
+ `${label} — enters scope:`,
356
+ ...difference(newPaths, oldPaths),
357
+ `${label} — leaves scope:`,
358
+ ...difference(oldPaths, newPaths),
359
+ ];
360
+ }
361
+ function difference(left, right) {
362
+ const paths = [...left].filter((item) => !right.has(item)).sort();
363
+ return paths.length ? paths.map((item) => ` ${safeTerminalText(item)}`) : [" none"];
364
+ }
365
+ async function preserveLegacySettings(document) {
366
+ const directory = stateDir();
367
+ const target = path.join(directory, `settings-before-ignore-${randomUUID()}.json`);
368
+ const file = await fs.open(target, "wx", 0o600);
369
+ try {
370
+ await file.writeFile(document.bytes);
371
+ await file.sync();
372
+ }
373
+ finally {
374
+ await file.close();
375
+ }
376
+ await syncDirectory(directory);
377
+ }
378
+ function requireInteractive(execution) {
379
+ const ctx = createServiceContext(execution);
380
+ if (!ctx.hasUI || !["tui", "rpc"].includes(ctx.mode))
381
+ throw new Error("This policy change requires an interactive review.");
382
+ return ctx;
383
+ }
384
+ async function confirm(ctx, execution, title, content) {
385
+ if (Buffer.byteLength(content) > MAX_REVIEW_BYTES)
386
+ throw new Error("The policy review exceeds its supported size; no changes were saved.");
387
+ const result = await engineHost().review(ctx, { title, content, confirmationLabel: "Save local policy" }, execution.signal, () => !execution.signal.aborted);
388
+ execution.validate();
389
+ return result;
390
+ }
391
+ function stale() {
392
+ throw new Error("Settings, rule source, or visible content changed. Reopen the Pi Sync policy review.");
393
+ }
@@ -0,0 +1,27 @@
1
+ import { type BigIntStats } from "node:fs";
2
+ export declare const DEFAULT_IGNORE_FILENAME = ".syncignore";
3
+ export declare const DEFAULT_IGNORE_CREATION_RECORD = ".pi-sync.json.syncignore-creation";
4
+ export declare const DEFAULT_IGNORE_RULES = "/npm/\n/sessions/\n/auth.json\n/truth.json\n";
5
+ export declare const MAX_IGNORE_BYTES: number;
6
+ export type IgnoreSource = {
7
+ filename: string;
8
+ text: string;
9
+ sourceDigest: string;
10
+ } & ({
11
+ present: false;
12
+ identity?: undefined;
13
+ } | {
14
+ present: true;
15
+ identity: string;
16
+ });
17
+ export declare function validateIgnoreFilename(value: unknown): string;
18
+ export declare class IgnoreCreationPendingError extends Error {
19
+ constructor();
20
+ }
21
+ export declare function readIgnoreSource(root: string, filename?: string, signal?: AbortSignal): Promise<IgnoreSource>;
22
+ export declare function ignoreFileIdentity(stat: BigIntStats): string;
23
+ export declare function sameIdentity(left: BigIntStats, right: BigIntStats): boolean;
24
+ export declare function sameFile(left: BigIntStats, right: BigIntStats): boolean;
25
+ export declare function ignoreSourceDigest(filename: string, present: boolean, bytes: Buffer): string;
26
+ export declare function ignorePolicyFingerprint(text: string, sessions: boolean): string;
27
+ export declare function compileIgnoreRules(text: string): (path: string, directory?: boolean) => boolean;
@@ -0,0 +1,250 @@
1
+ import { createHash } from "node:crypto";
2
+ import { constants, lstatSync } from "node:fs";
3
+ import fs from "node:fs/promises";
4
+ import path from "node:path";
5
+ import ignore from "ignore";
6
+ import { isDeniedPath } from "../paths.js";
7
+ export const DEFAULT_IGNORE_FILENAME = ".syncignore";
8
+ export const DEFAULT_IGNORE_CREATION_RECORD = ".pi-sync.json.syncignore-creation";
9
+ export const DEFAULT_IGNORE_RULES = "/npm/\n/sessions/\n/auth.json\n/truth.json\n";
10
+ export const MAX_IGNORE_BYTES = 64 * 1024;
11
+ const MAX_MATCH_PATH_BYTES = 4_096;
12
+ const MATCH_CACHE_PATH_BUDGET = 2_048;
13
+ const RESERVED_FILENAMES = new Set([
14
+ "auth.json",
15
+ "auth.json.lock",
16
+ "trust.json",
17
+ "trust.json.lock",
18
+ "settings.json",
19
+ "settings.json.lock",
20
+ "models.json",
21
+ "models-store.json",
22
+ "models-store.json.lock",
23
+ "keybindings.json",
24
+ "agents.md",
25
+ "system.md",
26
+ "append_system.md",
27
+ "crashes.json",
28
+ "pi-debug.log",
29
+ "extensions",
30
+ "skills",
31
+ "prompts",
32
+ "themes",
33
+ "npm",
34
+ "sessions",
35
+ ]);
36
+ export function validateIgnoreFilename(value) {
37
+ if (typeof value !== "string" || !/^[A-Za-z0-9._ -]{1,255}$/u.test(value) || /^[ ]|[. ]$/u.test(value)) {
38
+ throw new Error("Invalid sync.ignoreFile: use one safe filename in the Pi agent directory.");
39
+ }
40
+ const lower = value.toLowerCase();
41
+ if (/^(?:con|prn|aux|nul|com[0-9]|lpt[0-9]) *(?:\.|$)/u.test(lower) ||
42
+ (lower === DEFAULT_IGNORE_FILENAME && value !== DEFAULT_IGNORE_FILENAME) ||
43
+ RESERVED_FILENAMES.has(lower) ||
44
+ isDeniedPath(lower)) {
45
+ throw new Error(`Invalid sync.ignoreFile: "${value}" is a reserved filename.`);
46
+ }
47
+ return value;
48
+ }
49
+ export class IgnoreCreationPendingError extends Error {
50
+ constructor() {
51
+ super(`unfinished creation record "${DEFAULT_IGNORE_CREATION_RECORD}"; retry confirmed setup or migration to verify the starter file, or repair the incomplete creation first`);
52
+ }
53
+ }
54
+ export async function readIgnoreSource(root, filename = DEFAULT_IGNORE_FILENAME, signal) {
55
+ signal?.throwIfAborted();
56
+ filename = validateIgnoreFilename(filename);
57
+ try {
58
+ const absoluteRoot = path.resolve(root);
59
+ const rootStat = await fs.lstat(absoluteRoot, { bigint: true });
60
+ if (!rootStat.isDirectory())
61
+ throw new Error("the Pi agent directory is not a regular directory");
62
+ const canonicalRoot = await fs.realpath(absoluteRoot);
63
+ const checkRoot = async () => {
64
+ const currentRealpath = await fs.realpath(absoluteRoot);
65
+ const current = await fs.lstat(absoluteRoot, { bigint: true });
66
+ if (currentRealpath !== canonicalRoot || !current.isDirectory() || !sameIdentity(rootStat, current))
67
+ changed();
68
+ signal?.throwIfAborted();
69
+ checkCreationRecord();
70
+ };
71
+ const target = path.join(canonicalRoot, filename);
72
+ const checkCreationRecord = () => {
73
+ if (filename === DEFAULT_IGNORE_FILENAME &&
74
+ lstatSync(path.join(canonicalRoot, DEFAULT_IGNORE_CREATION_RECORD), { throwIfNoEntry: false })) {
75
+ throw new IgnoreCreationPendingError();
76
+ }
77
+ };
78
+ checkCreationRecord();
79
+ const before = await statIfPresent(target);
80
+ await checkRoot();
81
+ if (!before) {
82
+ if (filename !== DEFAULT_IGNORE_FILENAME)
83
+ throw new Error("the selected file does not exist");
84
+ checkCreationRecord();
85
+ if (lstatSync(target, { throwIfNoEntry: false }))
86
+ changed();
87
+ signal?.throwIfAborted();
88
+ return {
89
+ filename,
90
+ text: DEFAULT_IGNORE_RULES,
91
+ sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(DEFAULT_IGNORE_RULES)),
92
+ present: false,
93
+ };
94
+ }
95
+ if (!before.isFile() || before.nlink !== 1n)
96
+ throw new Error("use a regular file with no symlinks or hard links");
97
+ assertIgnoreSize(before.size);
98
+ if ((await fs.realpath(target)) !== target)
99
+ throw new Error("use the exact on-disk filename, not a path alias");
100
+ const bytes = await readIgnoreBytes(target, before, checkRoot, signal);
101
+ await checkRoot();
102
+ checkCreationRecord();
103
+ const current = lstatSync(target, { bigint: true, throwIfNoEntry: false });
104
+ if (!current || !sameFile(before, current))
105
+ changed();
106
+ signal?.throwIfAborted();
107
+ let text;
108
+ try {
109
+ text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
110
+ }
111
+ catch (cause) {
112
+ throw new Error("the file is not valid UTF-8", { cause });
113
+ }
114
+ if (text.includes("\0"))
115
+ throw new Error("the file contains NUL characters");
116
+ return {
117
+ filename,
118
+ text,
119
+ sourceDigest: ignoreSourceDigest(filename, true, bytes),
120
+ present: true,
121
+ identity: ignoreFileIdentity(before),
122
+ };
123
+ }
124
+ catch (cause) {
125
+ signal?.throwIfAborted();
126
+ const detail = cause.code
127
+ ? "could not verify or read the file"
128
+ : cause.message;
129
+ throw new Error(`Ignore file "${filename}": ${detail}.`, { cause });
130
+ }
131
+ }
132
+ async function statIfPresent(target) {
133
+ try {
134
+ return await fs.lstat(target, { bigint: true });
135
+ }
136
+ catch (error) {
137
+ if (error.code === "ENOENT")
138
+ return undefined;
139
+ throw error;
140
+ }
141
+ }
142
+ export function ignoreFileIdentity(stat) {
143
+ return `${stat.dev}:${stat.ino}:${stat.birthtimeNs}`;
144
+ }
145
+ export function sameIdentity(left, right) {
146
+ return left.dev === right.dev && left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
147
+ }
148
+ export function sameFile(left, right) {
149
+ return (sameIdentity(left, right) &&
150
+ left.mode === right.mode &&
151
+ left.uid === right.uid &&
152
+ left.gid === right.gid &&
153
+ left.nlink === right.nlink &&
154
+ left.size === right.size &&
155
+ left.mtimeNs === right.mtimeNs &&
156
+ left.ctimeNs === right.ctimeNs);
157
+ }
158
+ function changed() {
159
+ throw new Error("the file or Pi agent directory changed during the read; retry");
160
+ }
161
+ async function readIgnoreBytes(target, before, checkRoot, signal) {
162
+ signal?.throwIfAborted();
163
+ const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
164
+ const handle = await fs.open(target, flags);
165
+ try {
166
+ if (!sameFile(before, await handle.stat({ bigint: true })))
167
+ changed();
168
+ await checkRoot();
169
+ const buffer = Buffer.alloc(Number(before.size) + 1);
170
+ let count = 0;
171
+ while (count < buffer.length) {
172
+ signal?.throwIfAborted();
173
+ const { bytesRead } = await handle.read(buffer, count, buffer.length - count, count);
174
+ if (bytesRead === 0)
175
+ break;
176
+ count += bytesRead;
177
+ }
178
+ if (count !== Number(before.size))
179
+ changed();
180
+ if (!sameFile(before, await fs.lstat(target, { bigint: true })))
181
+ changed();
182
+ await checkRoot();
183
+ if (!sameFile(before, await handle.stat({ bigint: true })))
184
+ changed();
185
+ return buffer.subarray(0, count);
186
+ }
187
+ finally {
188
+ await handle.close();
189
+ }
190
+ }
191
+ function assertIgnoreSize(bytes) {
192
+ if (bytes > MAX_IGNORE_BYTES)
193
+ throw new Error(`rules exceed the ${MAX_IGNORE_BYTES}-byte limit`);
194
+ }
195
+ export function ignoreSourceDigest(filename, present, bytes) {
196
+ return createHash("sha256")
197
+ .update("pi-sync-ignore-source-v1\0")
198
+ .update(filename)
199
+ .update(present ? "\0present\0" : "\0absent\0")
200
+ .update(bytes)
201
+ .digest("hex");
202
+ }
203
+ export function ignorePolicyFingerprint(text, sessions) {
204
+ return createHash("sha256")
205
+ .update(JSON.stringify(["pi-sync-ignore-policy-v1", sessions, text]))
206
+ .digest("hex");
207
+ }
208
+ function gitByteString(value) {
209
+ return Buffer.from(value, "utf8").toString("latin1");
210
+ }
211
+ export function compileIgnoreRules(text) {
212
+ assertIgnoreSize(Buffer.byteLength(text, "utf8"));
213
+ if (!text.isWellFormed() || text.includes("\0"))
214
+ throw new Error("Ignore rules must be UTF-8 text without NULs.");
215
+ const rules = text.replace(/^\uFEFF/u, "");
216
+ for (const [index, line] of rules.split("\n").entries()) {
217
+ if (line.startsWith("#"))
218
+ continue;
219
+ for (let position = 0; position < line.length; position++) {
220
+ if (line[position] !== "\\")
221
+ continue;
222
+ if (line[++position] === "/") {
223
+ throw new Error(`Ignore rule on line ${index + 1} uses an unsupported escaped path separator.`);
224
+ }
225
+ }
226
+ }
227
+ const compiled = ignore({ ignorecase: false }).add(gitByteString(rules));
228
+ let matcher = ignore({ ignorecase: false }).add(compiled);
229
+ let cachedPathUpperBound = 0;
230
+ return (relativePath, directory = false) => {
231
+ if (Buffer.byteLength(relativePath, "utf8") > MAX_MATCH_PATH_BYTES) {
232
+ throw new Error(`Ignore matching path exceeds the ${MAX_MATCH_PATH_BYTES}-byte limit.`);
233
+ }
234
+ const segments = relativePath.split("/");
235
+ if (!relativePath.isWellFormed() ||
236
+ relativePath.includes("\\") ||
237
+ relativePath.includes("\0") ||
238
+ /^[a-z]:/iu.test(relativePath) ||
239
+ segments.some((part) => !part || part === "." || part === "..")) {
240
+ throw new Error("Ignore matching requires a canonical relative path with / separators.");
241
+ }
242
+ if (cachedPathUpperBound + segments.length > MATCH_CACHE_PATH_BUDGET) {
243
+ matcher = ignore({ ignorecase: false }).add(compiled);
244
+ cachedPathUpperBound = 0;
245
+ }
246
+ cachedPathUpperBound += segments.length;
247
+ const serializedPath = gitByteString(relativePath);
248
+ return matcher.ignores(directory ? `${serializedPath}/` : serializedPath);
249
+ };
250
+ }