@narumitw/pi-sync-daemon 0.7.0 → 0.8.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 (74) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +16 -2
  3. package/dist/consent.js +21 -6
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +30 -9
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/settings/config-file.d.ts +9 -2
  24. package/dist/engine/settings/config-file.js +124 -28
  25. package/dist/engine/settings/config.d.ts +3 -0
  26. package/dist/engine/settings/config.js +93 -7
  27. package/dist/engine/settings/settings-management.d.ts +2 -2
  28. package/dist/engine/settings/settings-management.js +16 -8
  29. package/dist/engine/settings/settings-types.d.ts +23 -2
  30. package/dist/engine/settings/settings-validation.js +23 -5
  31. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  32. package/dist/engine/snapshot/session-paths.js +36 -13
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  34. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  35. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  36. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  37. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  38. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  39. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  40. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  41. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +24 -1
  42. package/dist/engine/snapshot/snapshot-transaction-policy.js +106 -2
  43. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  44. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  46. package/dist/engine/snapshot/snapshot-transaction.js +86 -108
  47. package/dist/engine/snapshot/snapshot-types.d.ts +23 -1
  48. package/dist/engine/snapshot/snapshot-types.js +9 -1
  49. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  50. package/dist/engine/snapshot/snapshot.js +91 -34
  51. package/dist/engine/state/state-types.d.ts +1 -0
  52. package/dist/engine/sync/continuous-sync.js +18 -3
  53. package/dist/engine/sync/continuous-watch.js +4 -1
  54. package/dist/engine/sync/initialization.js +3 -2
  55. package/dist/engine/sync/local-fields.d.ts +3 -1
  56. package/dist/engine/sync/local-fields.js +62 -1
  57. package/dist/engine/sync/merge-apply.js +35 -7
  58. package/dist/engine/sync/merge-journal.d.ts +18 -4
  59. package/dist/engine/sync/merge-journal.js +115 -8
  60. package/dist/engine/sync/merged-sync.d.ts +1 -1
  61. package/dist/engine/sync/merged-sync.js +103 -50
  62. package/dist/engine/sync/remote-snapshot.d.ts +9 -2
  63. package/dist/engine/sync/remote-snapshot.js +56 -17
  64. package/dist/engine/sync/sync-inspection.js +7 -5
  65. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  66. package/dist/engine/sync/sync-mutations.js +110 -47
  67. package/dist/engine/sync/sync-policy.d.ts +24 -8
  68. package/dist/engine/sync/sync-policy.js +127 -16
  69. package/dist/engine/sync/sync-queries.js +8 -1
  70. package/dist/engine/sync/sync-state.d.ts +2 -2
  71. package/dist/engine/sync/sync-state.js +20 -2
  72. package/dist/engine-service.js +24 -2
  73. package/docs/architecture.md +22 -0
  74. package/package.json +2 -1
@@ -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
+ }
@@ -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?.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);
@@ -3,6 +3,9 @@ import type { AnySyncConfig, PartialConfig, PiSyncSettingsV3, StorageConnectionS
3
3
  export declare function loadConfig(setupName?: string): Promise<AnySyncConfig>;
4
4
  /** A background freshness read must never trigger legacy-file publication. */
5
5
  export declare function loadConfigForCheck(): 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. */