@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
@@ -1,5 +1,9 @@
1
1
  export declare const CONFIG_FILE_NAME = "pi-sync.json";
2
- type PublishFile = (source: string, destination: string, expected?: LocalConfigDocument, signal?: AbortSignal) => Promise<void>;
2
+ type PublicationReview = {
3
+ document: LocalConfigDocument | undefined;
4
+ check: () => Promise<void>;
5
+ };
6
+ type PublishFile = (source: string, destination: string, expected?: LocalConfigDocument, signal?: AbortSignal, review?: PublicationReview) => Promise<void>;
3
7
  export type FileIdentity = {
4
8
  dev: number;
5
9
  ino: number;
@@ -24,8 +28,11 @@ export declare function consumeLocalConfigMigrationNotice(): string | undefined;
24
28
  export declare function readActiveLocalConfigDocumentForRepair(): Promise<LocalConfigDocument | undefined>;
25
29
  /** Read-only bootstrap: no authority recursion, migration, or document creation. */
26
30
  export declare function peekLocalConfigDocument(): Promise<LocalConfigDocument | undefined>;
31
+ export declare function withLockedLocalConfigDocument<T>(run: (document: LocalConfigDocument | undefined, recheck: () => void) => Promise<T>, signal?: AbortSignal, forWrite?: boolean, { securePermissions }?: {
32
+ securePermissions?: boolean;
33
+ }): Promise<T>;
27
34
  export declare function readMigratingLocalConfigDocument(validateForMigration: (settings: Record<string, unknown>) => void): Promise<LocalConfigDocument | undefined>;
28
- export declare function updateLocalConfigDocument<T extends Record<string, unknown>>(defaultValue: T, update: (current: T) => T, validate: (value: Record<string, unknown>) => void, signal?: AbortSignal, validateSource?: (document: LocalConfigDocument | undefined) => void): Promise<T>;
35
+ export declare function updateLocalConfigDocument<T extends Record<string, unknown>>(defaultValue: T, update: (current: T) => T, validate: (value: Record<string, unknown>) => void, signal?: AbortSignal, validateSource?: (document: LocalConfigDocument | undefined) => void, beforePublish?: (document: LocalConfigDocument | undefined, next: T) => Promise<void>): Promise<T>;
29
36
  export declare function createLocalConfigDocument(value: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
30
37
  export declare function replaceLocalConfigDocument(document: LocalConfigDocument, value: Record<string, unknown>): Promise<void>;
31
38
  export declare function quarantineAndRemoveConfigIfMatches(filePath: string, identity: FileIdentity, expectedBytes: Buffer): Promise<boolean>;
@@ -1,8 +1,9 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { mkdir, mkdirSync, realpath, realpathSync, rmdir, rmdirSync, stat, statSync, utimes, utimesSync, } from "node:fs";
2
+ import { closeSync, constants, fstatSync, lstatSync, mkdir, mkdirSync, openSync, readSync, realpath, realpathSync, rmdir, rmdirSync, stat, statSync, utimes, utimesSync, } from "node:fs";
3
3
  import fs from "node:fs/promises";
4
4
  import path from "node:path";
5
5
  import lockfile from "proper-lockfile";
6
+ import { MAX_SETTINGS_BYTES } from "../../protocol.js";
6
7
  import { engineHost, getEngineRoot as getAgentDir } from "../host.js";
7
8
  export const CONFIG_FILE_NAME = "pi-sync.json";
8
9
  const LEGACY_CONFIG_FILE_NAME = "pi-sync.local.json";
@@ -110,13 +111,32 @@ export async function readActiveLocalConfigDocumentForRepair() {
110
111
  }
111
112
  /** Read-only bootstrap: no authority recursion, migration, or document creation. */
112
113
  export async function peekLocalConfigDocument() {
114
+ return queueConfigOperation(() => withLocalConfigReadLockIfNeeded(peekUnlocked));
115
+ }
116
+ async function peekUnlocked(maxBytes, securePermissions = true) {
113
117
  const canonicalPath = localConfigPath();
114
- const legacyPath = legacyLocalConfigPath();
115
- return queueConfigOperation(() => withLocalConfigReadLockIfNeeded(async () => {
116
- const filePath = (await pathExists(canonicalPath)) ? canonicalPath : legacyPath;
117
- const snapshot = await readConfigSnapshotIfExists(filePath);
118
- return snapshot ? { path: filePath, ...snapshot } : undefined;
119
- }));
118
+ const filePath = (await pathExists(canonicalPath)) ? canonicalPath : legacyLocalConfigPath();
119
+ return readConfigDocumentIfExists(filePath, maxBytes, securePermissions);
120
+ }
121
+ async function readConfigDocumentIfExists(filePath, maxBytes, securePermissions = true) {
122
+ const snapshot = await readConfigSnapshotIfExists(filePath, maxBytes, securePermissions);
123
+ return snapshot ? { path: filePath, ...snapshot } : undefined;
124
+ }
125
+ export function withLockedLocalConfigDocument(run, signal, forWrite = false, { securePermissions = true } = {}) {
126
+ if (engineHost().config)
127
+ throw new Error("This operation requires the authoritative settings writer.");
128
+ return queueConfigOperation(() => {
129
+ signal?.throwIfAborted();
130
+ const withLock = forWrite ? withLocalConfigFileLock : withLocalConfigReadLockIfNeeded;
131
+ return withLock(async () => {
132
+ const document = await peekUnlocked(MAX_SETTINGS_BYTES, securePermissions);
133
+ signal?.throwIfAborted();
134
+ return run(document, () => {
135
+ signal?.throwIfAborted();
136
+ assertCurrentDocument(document);
137
+ });
138
+ });
139
+ });
120
140
  }
121
141
  export async function readMigratingLocalConfigDocument(validateForMigration) {
122
142
  const authority = engineHost().config;
@@ -133,9 +153,7 @@ export async function readMigratingLocalConfigDocument(validateForMigration) {
133
153
  return document;
134
154
  }
135
155
  return queueConfigOperation(() => withLocalConfigReadLockIfNeeded(async () => {
136
- const configPath = await prepareLocalConfigPath(validateForMigration);
137
- const snapshot = await readConfigSnapshotIfExists(configPath);
138
- return snapshot ? { path: configPath, ...snapshot } : undefined;
156
+ return readConfigDocumentIfExists(await prepareLocalConfigPath(validateForMigration));
139
157
  }));
140
158
  }
141
159
  async function withLocalConfigReadLockIfNeeded(read) {
@@ -154,10 +172,10 @@ function queueConfigOperation(run) {
154
172
  configUpdateQueue = operation.then(() => undefined, () => undefined);
155
173
  return operation;
156
174
  }
157
- export function updateLocalConfigDocument(defaultValue, update, validate, signal, validateSource) {
175
+ export function updateLocalConfigDocument(defaultValue, update, validate, signal, validateSource, beforePublish) {
158
176
  const authority = engineHost().config;
159
177
  if (authority) {
160
- if (validateSource)
178
+ if (validateSource || beforePublish)
161
179
  throw new Error("Source validators must run in the authoritative settings writer.");
162
180
  return authority.update(defaultValue, update, validate, signal);
163
181
  }
@@ -165,11 +183,11 @@ export function updateLocalConfigDocument(defaultValue, update, validate, signal
165
183
  signal?.throwIfAborted();
166
184
  return withLocalConfigFileLock(async () => {
167
185
  signal?.throwIfAborted();
168
- const configPath = await prepareLocalConfigPath(validate);
186
+ const reviewed = validateSource !== undefined || beforePublish !== undefined;
187
+ const configPath = reviewed ? undefined : await prepareLocalConfigPath(validate);
169
188
  signal?.throwIfAborted();
170
- const snapshot = await readConfigSnapshotIfExists(configPath);
189
+ const document = configPath ? await readConfigDocumentIfExists(configPath) : await peekUnlocked();
171
190
  signal?.throwIfAborted();
172
- const document = snapshot ? { path: configPath, ...snapshot } : undefined;
173
191
  validateSource?.(document);
174
192
  if (document)
175
193
  validate(document.parsed);
@@ -179,10 +197,25 @@ export function updateLocalConfigDocument(defaultValue, update, validate, signal
179
197
  signal?.throwIfAborted();
180
198
  if (document && JSON.stringify(document.parsed) === JSON.stringify(next))
181
199
  return next;
200
+ if (beforePublish && document && document.path !== localConfigPath()) {
201
+ throw new Error("This reviewed settings change requires pi-sync.json. No settings were saved; use the canonical filename and reopen the review.");
202
+ }
203
+ const review = reviewed
204
+ ? {
205
+ document,
206
+ check: async () => {
207
+ if (beforePublish) {
208
+ assertCurrentDocument(document);
209
+ await beforePublish(document, next);
210
+ }
211
+ validateSource?.(document);
212
+ },
213
+ }
214
+ : undefined;
182
215
  if (document)
183
- await replaceLocalConfigDocumentUnlocked(document, next, signal);
216
+ await replaceLocalConfigDocumentUnlocked(document, next, signal, review);
184
217
  else
185
- await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next), signal);
218
+ await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next), signal, review);
186
219
  return next;
187
220
  });
188
221
  });
@@ -214,7 +247,7 @@ export function replaceLocalConfigDocument(document, value) {
214
247
  return authority.replace(document, value);
215
248
  return queueConfigOperation(() => withLocalConfigFileLock(() => replaceLocalConfigDocumentUnlocked(document, value)));
216
249
  }
217
- async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
250
+ async function replaceLocalConfigDocumentUnlocked(document, value, signal, review) {
218
251
  const nextBytes = serializedConfig(value);
219
252
  const canonicalPath = localConfigPath();
220
253
  if (document.path !== canonicalPath) {
@@ -222,7 +255,7 @@ async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
222
255
  throw settingsChangedError();
223
256
  let installed;
224
257
  try {
225
- installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, signal);
258
+ installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, signal, review);
226
259
  }
227
260
  catch (error) {
228
261
  if (error.code === "EEXIST") {
@@ -259,7 +292,7 @@ async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
259
292
  let published = false;
260
293
  try {
261
294
  signal?.throwIfAborted();
262
- await publishConfigFile(temporaryPath, canonicalPath, document, signal);
295
+ await publishConfigFile(temporaryPath, canonicalPath, document, signal, review);
263
296
  published = true;
264
297
  await syncParentDirectory(canonicalPath);
265
298
  await afterReplacementInstalledHook();
@@ -374,7 +407,46 @@ async function secureIgnoredLegacyIfPresent(filePath) {
374
407
  await handle?.close().catch(() => undefined);
375
408
  }
376
409
  }
377
- async function readConfigSnapshotIfExists(filePath) {
410
+ function assertCurrentDocument(document) {
411
+ const canonical = localConfigPath();
412
+ const legacy = legacyLocalConfigPath();
413
+ const filePath = lstatSync(canonical, { throwIfNoEntry: false }) ? canonical : legacy;
414
+ const before = lstatSync(filePath, { throwIfNoEntry: false });
415
+ if (!document) {
416
+ if (before)
417
+ throw settingsChangedError();
418
+ return;
419
+ }
420
+ const matches = (stat) => stat?.isFile() &&
421
+ stat.size === document.bytes.length &&
422
+ stat.dev === document.identity.dev &&
423
+ stat.ino === document.identity.ino;
424
+ if (filePath !== document.path || !matches(before))
425
+ throw settingsChangedError();
426
+ const fd = openSync(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
427
+ try {
428
+ if (!matches(fstatSync(fd)))
429
+ throw settingsChangedError();
430
+ const buffer = Buffer.alloc(document.bytes.length + 1);
431
+ let offset = 0;
432
+ while (offset < buffer.length) {
433
+ const read = readSync(fd, buffer, offset, buffer.length - offset, offset);
434
+ if (!read)
435
+ break;
436
+ offset += read;
437
+ }
438
+ if (offset !== document.bytes.length ||
439
+ !buffer.subarray(0, offset).equals(document.bytes) ||
440
+ !matches(fstatSync(fd)) ||
441
+ !matches(lstatSync(filePath, { throwIfNoEntry: false })) ||
442
+ (filePath === legacy && lstatSync(canonical, { throwIfNoEntry: false })))
443
+ throw settingsChangedError();
444
+ }
445
+ finally {
446
+ closeSync(fd);
447
+ }
448
+ }
449
+ async function readConfigSnapshotIfExists(filePath, maxBytes, securePermissions = true) {
378
450
  let pathStat;
379
451
  try {
380
452
  pathStat = await fs.lstat(filePath);
@@ -389,16 +461,35 @@ async function readConfigSnapshotIfExists(filePath) {
389
461
  }
390
462
  if (!pathStat.isFile())
391
463
  throw new Error(`pi-sync config is not a regular file: ${filePath}`);
392
- const handle = await fs.open(filePath, "r");
464
+ if (maxBytes !== undefined && pathStat.size > maxBytes)
465
+ throw new Error("Settings exceed the editable local API byte limit.");
466
+ const handle = await fs.open(filePath, maxBytes === undefined ? "r" : constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
393
467
  try {
394
468
  const openedStat = await handle.stat();
395
469
  if (openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
396
470
  throw new Error(`pi-sync config changed while opening: ${filePath}`);
397
471
  }
398
- if (process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
472
+ if (securePermissions && process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
399
473
  await handle.chmod(0o600);
400
474
  }
401
- const bytes = await handle.readFile();
475
+ let bytes;
476
+ if (maxBytes === undefined)
477
+ bytes = await handle.readFile();
478
+ else {
479
+ if (openedStat.size > maxBytes)
480
+ throw new Error("Settings exceed the editable local API byte limit.");
481
+ const buffer = Buffer.alloc(openedStat.size + 1);
482
+ let offset = 0;
483
+ while (offset < buffer.length) {
484
+ const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
485
+ if (bytesRead === 0)
486
+ break;
487
+ offset += bytesRead;
488
+ }
489
+ if (offset !== openedStat.size)
490
+ throw settingsChangedError();
491
+ bytes = buffer.subarray(0, offset);
492
+ }
402
493
  return {
403
494
  bytes,
404
495
  identity: { dev: openedStat.dev, ino: openedStat.ino },
@@ -425,10 +516,10 @@ function parseConfigObject(bytes, filePath) {
425
516
  }
426
517
  return parsed;
427
518
  }
428
- async function installPrivateConfigExclusively(filePath, bytes, signal) {
519
+ async function installPrivateConfigExclusively(filePath, bytes, signal, review) {
429
520
  return withPrivateConfigTemporary(filePath, bytes, async (temporaryPath, installed) => {
430
521
  signal?.throwIfAborted();
431
- await publishConfigFile(temporaryPath, filePath, undefined, signal);
522
+ await publishConfigFile(temporaryPath, filePath, undefined, signal, review);
432
523
  try {
433
524
  if (!(await fileIdentityAndContentsMatch(filePath, installed, bytes))) {
434
525
  throw new Error(`Published pi-sync settings changed concurrently: ${filePath}`);
@@ -584,12 +675,17 @@ async function syncParentDirectory(filePath) {
584
675
  await handle?.close().catch(() => undefined);
585
676
  }
586
677
  }
587
- async function publishFileWithGuard(source, destination, expected, signal) {
678
+ async function publishFileWithGuard(source, destination, expected, signal, review) {
588
679
  await beforeConfigPublicationHook();
589
680
  signal?.throwIfAborted();
681
+ if (review) {
682
+ await review.check();
683
+ signal?.throwIfAborted();
684
+ assertCurrentDocument(review.document);
685
+ }
590
686
  if (expected) {
591
687
  // The shared lock orders Pi Sync writers; rename has no CAS for noncooperating writers.
592
- if (!(await configDocumentStillMatches(expected)))
688
+ if (!review && !(await configDocumentStillMatches(expected)))
593
689
  throw settingsChangedError();
594
690
  signal?.throwIfAborted();
595
691
  await fs.rename(source, destination);
@@ -1,8 +1,11 @@
1
1
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
2
  import type { AnySyncConfig, PartialConfig, PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
3
- export declare function loadConfig(setupName?: string): Promise<AnySyncConfig>;
3
+ export declare function loadConfig(setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
4
4
  /** A background freshness read must never trigger legacy-file publication. */
5
- export declare function loadConfigForCheck(): Promise<AnySyncConfig>;
5
+ export declare function loadConfigForCheck(setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
6
+ export declare function loadSettingsConfig(setupName?: string): Promise<AnySyncConfig>;
7
+ export declare function requireLegacyOperationConfig(config: AnySyncConfig): AnySyncConfig;
8
+ export declare function resolveIgnoreConfig(settings: PiSyncSettingsV3, setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
6
9
  export declare function configFromSettings(settings: PiSyncSettingsV3, setupName?: string): AnySyncConfig;
7
10
  export type SyncSetupStorageReview = Pick<PartialConfig, "connectionName" | "storageKind" | "storagePath" | "bucket" | "branch">;
8
11
  /** A validated setup-facing projection used by manager and settings UI. */
@@ -13,6 +16,7 @@ export declare function syncConfigReviewIdentity(config: AnySyncConfig): string;
13
16
  export declare function syncConfigReviewFingerprint(config: AnySyncConfig): string;
14
17
  /** Internal freshness token, including credentials; never display or persist it. */
15
18
  export declare function syncCheckConfigFingerprint(config: AnySyncConfig): string;
19
+ export declare function syncSettingsConfigFingerprint(config: AnySyncConfig): string;
16
20
  export declare function sessionTokenWarnings(config: {
17
21
  endpoint?: string;
18
22
  sessionToken?: string;
@@ -1,23 +1,125 @@
1
1
  import { createHash } from "node:crypto";
2
+ import path from "node:path";
3
+ import { documentFingerprint } from "../../document.js";
2
4
  import { backendIdentityCoordinates } from "../backends/backend-identity.js";
3
5
  import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote } from "../backends/git/git-config.js";
4
6
  import { normalizeWebDavPath, normalizeWebDavUrl } from "../backends/webdav/webdav-config.js";
7
+ import { engineHost, getEngineRoot } from "../host.js";
8
+ import { compileEffectiveIgnorePolicy } from "../ignore/effective-ignore-policy.js";
9
+ import { DEFAULT_IGNORE_FILENAME, readIgnoreSource, validateIgnoreFilename } from "../ignore/ignore-source.js";
5
10
  import { normalizeSyncExclude } from "../sync/exclude-policy.js";
6
11
  import { normalizeLocalFields } from "../sync/local-field-policy.js";
7
- import { normalizeDirectoryRules, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "../sync/sync-policy.js";
8
- import { localConfigPath, readActiveLocalConfigDocumentForRepair } from "./config-file.js";
9
- import { requireSettings } from "./settings-store.js";
12
+ import { localIgnorePolicyKey, normalizeDirectoryRules, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "../sync/sync-policy.js";
13
+ import { safeTerminalText } from "../ui/terminal-text.js";
14
+ import { localConfigPath, readActiveLocalConfigDocumentForRepair, withLockedLocalConfigDocument, } from "./config-file.js";
15
+ import { readLocalConfigDocument, requireSettings } from "./settings-store.js";
10
16
  import { DEFAULT_ON_SWITCH, isCloudflareR2Endpoint, normalizeS3Bucket, normalizeS3Endpoint, normalizeStoragePath, optionalString, ownObject, requiredString, validateConfigName, validateSettingsDocument, } from "./settings-validation.js";
11
- export async function loadConfig(setupName) {
12
- return configFromSettings(await requireSettings(), setupName);
17
+ export async function loadConfig(setupName, signal) {
18
+ signal?.throwIfAborted();
19
+ const document = await readLocalConfigDocument();
20
+ if (!document)
21
+ throw new Error(`Missing pi-sync settings. Open /sync and choose Set up sync, or create ${localConfigPath()}.`);
22
+ return operationalConfig(document, setupName, signal);
13
23
  }
14
24
  /** A background freshness read must never trigger legacy-file publication. */
15
- export async function loadConfigForCheck() {
16
- const document = await readActiveLocalConfigDocumentForRepair();
25
+ export async function loadConfigForCheck(setupName, signal) {
26
+ signal?.throwIfAborted();
27
+ return operationalConfig(await readActiveLocalConfigDocumentForRepair(), setupName, signal);
28
+ }
29
+ async function operationalConfig(document, setupName, signal) {
30
+ signal?.throwIfAborted();
31
+ const config = configFromSettings(settingsFromCheckDocument(document), setupName);
32
+ if (!config.reservedIgnoreNames)
33
+ return config;
34
+ if (engineHost().ignoreFileOperationsAvailable === false)
35
+ return requireLegacyOperationConfig(config);
36
+ return resolveOperationPolicy(config, setupName, signal, document);
37
+ }
38
+ export async function loadSettingsConfig(setupName) {
39
+ return configFromSettings(await readSettingsForCheck(), setupName);
40
+ }
41
+ async function readSettingsForCheck() {
42
+ return settingsFromCheckDocument(await readActiveLocalConfigDocumentForRepair());
43
+ }
44
+ function settingsFromCheckDocument(document) {
17
45
  if (!document)
18
46
  throw new Error(`Missing pi-sync settings: ${localConfigPath()}`);
19
- validateSettingsDocument(document.parsed);
20
- return configFromSettings(document.parsed);
47
+ return validateSettingsDocument(document.parsed);
48
+ }
49
+ export function requireLegacyOperationConfig(config) {
50
+ if (config.pathPolicy === "ignore-file" || config.ignorePolicy || config.reservedIgnoreNames !== undefined) {
51
+ throw new Error("This Pi Sync operation does not yet support settings with ignore-file policies.");
52
+ }
53
+ return config;
54
+ }
55
+ export async function resolveIgnoreConfig(settings, setupName, signal) {
56
+ signal?.throwIfAborted();
57
+ return resolveOperationPolicy(configFromSettings(validateSettingsDocument(settings), setupName), setupName, signal);
58
+ }
59
+ function settingsDocumentFingerprint(document) {
60
+ return documentFingerprint(document && { bytes: document.bytes.toString("base64"), identity: document.identity });
61
+ }
62
+ async function resolveOperationPolicy(config, setupName, signal, original) {
63
+ if (!config.reservedIgnoreNames)
64
+ return config;
65
+ const root = getEngineRoot();
66
+ const validateRoot = () => {
67
+ signal?.throwIfAborted();
68
+ if (root !== getEngineRoot())
69
+ throw new Error("The Pi agent directory changed; reopen the review before continuing.");
70
+ };
71
+ const configDocumentFingerprint = original && settingsDocumentFingerprint(original);
72
+ const settingsFingerprint = syncCheckConfigFingerprint(config);
73
+ const validateSettings = (document) => {
74
+ validateRoot();
75
+ if ((original &&
76
+ (document?.path !== original.path || settingsDocumentFingerprint(document) !== configDocumentFingerprint)) ||
77
+ settingsFingerprint !==
78
+ syncCheckConfigFingerprint(configFromSettings(settingsFromCheckDocument(document), setupName))) {
79
+ throw new Error("Pi Sync settings changed; reopen the review before continuing.");
80
+ }
81
+ };
82
+ const source = config.pathPolicy === "ignore-file" ? await readIgnoreSource(root, config.ignoreFile, signal) : undefined;
83
+ validateRoot();
84
+ if (original && source && !source.present) {
85
+ throw new Error(`Ignore file is missing: ${safeTerminalText(path.join(root, source.filename))}. Create it and reopen Pi Sync; starter rules are only a preview.`);
86
+ }
87
+ if (original && source)
88
+ validateSettings(await readActiveLocalConfigDocumentForRepair());
89
+ return {
90
+ ...config,
91
+ ...(configDocumentFingerprint ? { configDocumentFingerprint } : {}),
92
+ ...(source ? { ignorePolicy: compileEffectiveIgnorePolicy(source, ignorePolicyInput(config)) } : {}),
93
+ ...(source?.identity ? { ignoreSourceIdentity: source.identity } : {}),
94
+ validateIgnorePolicy: async () => {
95
+ validateRoot();
96
+ await withLockedLocalConfigDocument(async (document, recheck) => {
97
+ validateSettings(document);
98
+ if (source) {
99
+ const current = await readIgnoreSource(root, source.filename, signal);
100
+ validateRoot();
101
+ recheck();
102
+ if (current.sourceDigest !== source.sourceDigest || current.identity !== source.identity) {
103
+ throw new Error("Pi Sync ignore policy changed; reopen the review before continuing.");
104
+ }
105
+ if (!current.present) {
106
+ throw new Error(`Ignore file "${source.filename}" is missing; starter rules can only be used for a preview.`);
107
+ }
108
+ }
109
+ else {
110
+ recheck();
111
+ }
112
+ }, signal, true);
113
+ validateRoot();
114
+ },
115
+ };
116
+ }
117
+ function ignorePolicyInput(config) {
118
+ return {
119
+ filename: config.ignoreFile,
120
+ sessions: config.include.includes("sessions"),
121
+ configuredFilenames: config.reservedIgnoreNames ?? [],
122
+ };
21
123
  }
22
124
  export function configFromSettings(settings, setupName) {
23
125
  const selectedName = setupName ?? settings.activeSyncSetup;
@@ -32,19 +134,28 @@ export function configFromSettings(settings, setupName) {
32
134
  if (!connection) {
33
135
  throw new Error(`Invalid pi-sync settings: sync setup “${selectedName}” references missing storage connection “${connectionName}”.`);
34
136
  }
137
+ const ignoreNames = new Set();
138
+ for (const { sync } of Object.values(settings.syncSetups)) {
139
+ if (sync.pathPolicy === "ignore-file")
140
+ ignoreNames.add(validateIgnoreFilename(sync.ignoreFile ?? DEFAULT_IGNORE_FILENAME).toLowerCase());
141
+ }
142
+ if (ignoreNames.size > 0)
143
+ ignoreNames.add(DEFAULT_IGNORE_FILENAME);
35
144
  return {
36
145
  ...resolveSyncConfig(selectedName, setup, connectionName, connection, settings.onSwitch, settings.skipSecretScan ?? false, settings.showStatus ?? true),
37
146
  debug: settings.debug ?? false,
147
+ ...(ignoreNames.size > 0 ? { reservedIgnoreNames: [...ignoreNames].sort() } : {}),
38
148
  };
39
149
  }
40
150
  /** A validated setup-facing projection used by manager and settings UI. */
41
151
  export async function loadPartialConfig(setupName) {
42
- const config = await loadConfig(setupName);
152
+ const config = configFromSettings(await requireSettings(), setupName);
43
153
  return {
44
154
  setupName: config.setupName,
45
155
  ...storageReviewFromConfig(config),
46
156
  include: [...config.include],
47
157
  ...(config.scope === undefined ? {} : { scope: config.scope }),
158
+ ...(config.pathPolicy === undefined ? {} : { pathPolicy: config.pathPolicy, ignoreFile: config.ignoreFile }),
48
159
  ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
49
160
  ...(config.reinclude === undefined ? {} : { reinclude: [...config.reinclude] }),
50
161
  automatic: config.automatic,
@@ -62,7 +173,10 @@ export function syncSetupReviewIdentity(setupName, setup, connectionName, connec
62
173
  return syncConfigReviewIdentity(resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false, true));
63
174
  }
64
175
  export function syncConfigReviewIdentity(config) {
65
- const directoryPolicy = syncDirectoryPolicyKey(config);
176
+ const localPolicy = localIgnorePolicyKey(config);
177
+ const directoryPolicy = config.pathPolicy === "ignore-file" && !config.ignorePolicy
178
+ ? JSON.stringify([config.pathPolicy, config.ignoreFile])
179
+ : syncDirectoryPolicyKey(config);
66
180
  return JSON.stringify([
67
181
  config.setupName,
68
182
  config.connectionName,
@@ -82,6 +196,7 @@ export function syncConfigReviewIdentity(config) {
82
196
  : config.exclude === undefined
83
197
  ? []
84
198
  : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
199
+ ...(localPolicy ? [localPolicy] : []),
85
200
  ]);
86
201
  }
87
202
  export function syncConfigReviewFingerprint(config) {
@@ -93,6 +208,14 @@ export function syncCheckConfigFingerprint(config) {
93
208
  .update(JSON.stringify({ ...config, showStatus: undefined, debug: undefined }))
94
209
  .digest("hex");
95
210
  }
211
+ export function syncSettingsConfigFingerprint(config) {
212
+ return syncCheckConfigFingerprint({
213
+ ...config,
214
+ configDocumentFingerprint: undefined,
215
+ ignoreSourceIdentity: undefined,
216
+ ignorePolicy: undefined,
217
+ });
218
+ }
96
219
  function storageReviewFromConfig(config) {
97
220
  return {
98
221
  connectionName: config.connectionName,
@@ -113,6 +236,12 @@ function resolveSyncConfig(setupName, setup, connectionName, connection, onSwitc
113
236
  ? {
114
237
  scope: policy.scope,
115
238
  include: policy.sessions ? ["sessions"] : [],
239
+ ...(policy.pathPolicy === "ignore-file"
240
+ ? {
241
+ pathPolicy: policy.pathPolicy,
242
+ ignoreFile: validateIgnoreFilename(policy.ignoreFile ?? DEFAULT_IGNORE_FILENAME),
243
+ }
244
+ : {}),
116
245
  ...(policy.exclude === undefined ? {} : { exclude: normalizeDirectoryRules(policy.exclude) }),
117
246
  ...(policy.reinclude === undefined ? {} : { reinclude: normalizeDirectoryRules(policy.reinclude) }),
118
247
  }
@@ -1,5 +1,5 @@
1
1
  import { type SyncSetupStorageReview } from "./config.js";
2
- import type { StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
2
+ import type { PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
3
3
  export declare class SyncSetupReviewChangedError extends Error {
4
4
  constructor(message: string);
5
5
  }
@@ -8,7 +8,7 @@ export declare function saveNewV3Settings(input: {
8
8
  connectionName: string;
9
9
  connection: StorageConnectionSettings;
10
10
  setup: SyncSetupSettings;
11
- }, signal?: AbortSignal): Promise<import("./settings-types.js").PiSyncSettingsV3>;
11
+ }, signal?: AbortSignal): Promise<PiSyncSettingsV3>;
12
12
  export declare function addStorageConnection(name: string, connection: StorageConnectionSettings, signal?: AbortSignal): Promise<void>;
13
13
  export declare function updateStorageConnection(name: string, update: (connection: StorageConnectionSettings) => StorageConnectionSettings, expectedSetups?: readonly string[], signal?: AbortSignal): Promise<void>;
14
14
  export declare function addSyncSetup(name: string, setup: SyncSetupSettings, signal?: AbortSignal, expectedConnection?: StorageConnectionSettings): Promise<void>;
@@ -20,5 +20,7 @@ export declare function updateSyncSetup(name: string, update: (setup: SyncSetupS
20
20
  upgradeExclude?: boolean;
21
21
  signal?: AbortSignal;
22
22
  }): Promise<void>;
23
- export declare function removeSyncSetup(name: string, signal?: AbortSignal): Promise<void>;
23
+ export declare function removeSyncSetup(name: string, signal?: AbortSignal): Promise<{
24
+ revertedToLegacyOnly: boolean;
25
+ }>;
24
26
  export declare function removeStorageConnection(name: string, signal?: AbortSignal): Promise<void>;
@@ -22,7 +22,7 @@ export async function saveNewV3Settings(input, signal) {
22
22
  }
23
23
  return {
24
24
  ...current,
25
- version: setup.sync.scope === "agent-directory" ? 7 : current.version,
25
+ version: setupSettingsVersion(current.version, setup),
26
26
  activeSyncSetup: setupName,
27
27
  storageConnections: { [connectionName]: connection },
28
28
  syncSetups: { [setupName]: setup },
@@ -76,7 +76,7 @@ export async function addSyncSetup(name, setup, signal, expectedConnection) {
76
76
  assertUniqueLocations(nextSetups, settings.storageConnections);
77
77
  return {
78
78
  ...settings,
79
- version: setup.sync.scope === "agent-directory" ? 7 : settings.version,
79
+ version: setupSettingsVersion(settings.version, setup),
80
80
  syncSetups: nextSetups,
81
81
  ...(settings.activeSyncSetup ? {} : { activeSyncSetup: name }),
82
82
  };
@@ -113,18 +113,19 @@ export async function updateSyncSetup(name, update, options = {}) {
113
113
  }
114
114
  const nextSetups = { ...settings.syncSetups, [name]: nextSetup };
115
115
  assertUniqueLocations(nextSetups, settings.storageConnections);
116
- const version = nextSetup.sync.scope === "agent-directory"
117
- ? 7
118
- : options.upgradeExclude && settings.version < 6
119
- ? 6
120
- : settings.version;
121
- return { ...settings, version, syncSetups: nextSetups };
116
+ return {
117
+ ...settings,
118
+ version: setupSettingsVersion(settings.version, nextSetup, options.upgradeExclude),
119
+ syncSetups: nextSetups,
120
+ };
122
121
  }, options.signal);
123
122
  }
124
123
  export async function removeSyncSetup(name, signal) {
125
124
  validateConfigName(name, "sync setup");
126
- await updateLocalConfig((settings) => {
127
- if (!Object.hasOwn(settings.syncSetups, name))
125
+ let removedLastIgnoreSetup = false;
126
+ const saved = await updateLocalConfig((settings) => {
127
+ const setup = settings.syncSetups[name];
128
+ if (!Object.hasOwn(settings.syncSetups, name) || !setup)
128
129
  throw new Error(`Sync setup not found: ${name}`);
129
130
  const isCurrent = settings.activeSyncSetup === name;
130
131
  if (isCurrent && Object.keys(settings.syncSetups).length > 1) {
@@ -132,11 +133,15 @@ export async function removeSyncSetup(name, signal) {
132
133
  }
133
134
  const syncSetups = { ...settings.syncSetups };
134
135
  delete syncSetups[name];
136
+ removedLastIgnoreSetup =
137
+ setup.sync.pathPolicy === "ignore-file" &&
138
+ !Object.values(syncSetups).some((remaining) => remaining.sync.pathPolicy === "ignore-file");
135
139
  const next = { ...settings, syncSetups };
136
140
  if (isCurrent)
137
141
  delete next.activeSyncSetup;
138
142
  return next;
139
143
  }, signal);
144
+ return { revertedToLegacyOnly: removedLastIgnoreSetup && saved.activeSyncSetup !== undefined };
140
145
  }
141
146
  export async function removeStorageConnection(name, signal) {
142
147
  validateConfigName(name, "storage connection");
@@ -153,6 +158,15 @@ export async function removeStorageConnection(name, signal) {
153
158
  return { ...settings, storageConnections };
154
159
  }, signal);
155
160
  }
161
+ function setupSettingsVersion(current, setup, upgradeExclude) {
162
+ if (setup.sync.pathPolicy === "ignore-file")
163
+ return 8;
164
+ if (current < 7 && setup.sync.scope === "agent-directory")
165
+ return 7;
166
+ if (current < 6 && upgradeExclude)
167
+ return 6;
168
+ return current;
169
+ }
156
170
  function referencingSetupNames(setups, connection) {
157
171
  return Object.entries(setups)
158
172
  .filter(([, setup]) => setup.storage.connection === connection)