@narumitw/pi-sync-daemon 0.6.2 → 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 (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +17 -3
  3. package/dist/consent.js +26 -1
  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 +39 -13
  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/paths.js +1 -1
  24. package/dist/engine/settings/config-file.d.ts +9 -2
  25. package/dist/engine/settings/config-file.js +126 -28
  26. package/dist/engine/settings/config.d.ts +5 -4
  27. package/dist/engine/settings/config.js +114 -13
  28. package/dist/engine/settings/settings-management.js +34 -32
  29. package/dist/engine/settings/settings-types.d.ts +40 -5
  30. package/dist/engine/settings/settings-validation.js +52 -24
  31. package/dist/engine/snapshot/session-paths.d.ts +6 -4
  32. package/dist/engine/snapshot/session-paths.js +84 -15
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +7 -8
  34. package/dist/engine/snapshot/snapshot-apply.js +107 -21
  35. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  36. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  37. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  38. package/dist/engine/snapshot/snapshot-codec.js +15 -7
  39. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  40. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +9 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +239 -24
  43. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  45. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  46. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  47. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  48. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  49. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +39 -0
  50. package/dist/engine/snapshot/snapshot-transaction-images.js +387 -0
  51. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +73 -0
  52. package/dist/engine/snapshot/snapshot-transaction-policy.js +276 -0
  53. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  54. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  55. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  56. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  57. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -11
  58. package/dist/engine/snapshot/snapshot-transaction.js +390 -364
  59. package/dist/engine/snapshot/snapshot-types.d.ts +47 -2
  60. package/dist/engine/snapshot/snapshot-types.js +9 -1
  61. package/dist/engine/snapshot/snapshot.d.ts +22 -3
  62. package/dist/engine/snapshot/snapshot.js +357 -43
  63. package/dist/engine/state/merge-baseline-store.js +20 -9
  64. package/dist/engine/state/state-types.d.ts +3 -0
  65. package/dist/engine/sync/apply-review.d.ts +3 -3
  66. package/dist/engine/sync/apply-review.js +5 -4
  67. package/dist/engine/sync/continuous-sync.js +37 -12
  68. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  69. package/dist/engine/sync/continuous-watch.js +90 -15
  70. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  71. package/dist/engine/sync/exclude-policy.js +8 -1
  72. package/dist/engine/sync/initialization.js +9 -4
  73. package/dist/engine/sync/local-fields.d.ts +3 -1
  74. package/dist/engine/sync/local-fields.js +88 -8
  75. package/dist/engine/sync/merge-apply.js +190 -47
  76. package/dist/engine/sync/merge-journal.d.ts +18 -4
  77. package/dist/engine/sync/merge-journal.js +126 -10
  78. package/dist/engine/sync/merged-sync.d.ts +1 -1
  79. package/dist/engine/sync/merged-sync.js +124 -68
  80. package/dist/engine/sync/partial-progress.js +5 -3
  81. package/dist/engine/sync/remote-snapshot.d.ts +10 -2
  82. package/dist/engine/sync/remote-snapshot.js +59 -17
  83. package/dist/engine/sync/session-push.js +7 -6
  84. package/dist/engine/sync/sync-decision.d.ts +4 -0
  85. package/dist/engine/sync/sync-decision.js +17 -2
  86. package/dist/engine/sync/sync-inspection.js +8 -6
  87. package/dist/engine/sync/sync-mutations.d.ts +10 -2
  88. package/dist/engine/sync/sync-mutations.js +245 -101
  89. package/dist/engine/sync/sync-policy.d.ts +36 -10
  90. package/dist/engine/sync/sync-policy.js +285 -20
  91. package/dist/engine/sync/sync-queries.js +49 -32
  92. package/dist/engine/sync/sync-state.d.ts +11 -0
  93. package/dist/engine/sync/sync-state.js +42 -5
  94. package/dist/engine/ui/sync-format.js +22 -7
  95. package/dist/engine-service.js +24 -2
  96. package/docs/architecture.md +28 -0
  97. 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
+ }
@@ -23,7 +23,7 @@ export function isDeniedPath(relativePath) {
23
23
  }
24
24
  export function isPathInside(parent, child) {
25
25
  const relative = path.relative(path.resolve(parent), path.resolve(child));
26
- return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
26
+ return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
27
27
  }
28
28
  export function safeJoin(root, relativePath) {
29
29
  const target = path.resolve(root, relativePath);
@@ -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,22 +183,39 @@ 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);
192
+ if (document)
193
+ validate(document.parsed);
174
194
  const current = document ? structuredClone(document.parsed) : structuredClone(defaultValue);
175
195
  const next = update(current);
176
196
  validate(next);
177
197
  signal?.throwIfAborted();
178
198
  if (document && JSON.stringify(document.parsed) === JSON.stringify(next))
179
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;
180
215
  if (document)
181
- await replaceLocalConfigDocumentUnlocked(document, next, signal);
216
+ await replaceLocalConfigDocumentUnlocked(document, next, signal, review);
182
217
  else
183
- await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next), signal);
218
+ await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next), signal, review);
184
219
  return next;
185
220
  });
186
221
  });
@@ -212,7 +247,7 @@ export function replaceLocalConfigDocument(document, value) {
212
247
  return authority.replace(document, value);
213
248
  return queueConfigOperation(() => withLocalConfigFileLock(() => replaceLocalConfigDocumentUnlocked(document, value)));
214
249
  }
215
- async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
250
+ async function replaceLocalConfigDocumentUnlocked(document, value, signal, review) {
216
251
  const nextBytes = serializedConfig(value);
217
252
  const canonicalPath = localConfigPath();
218
253
  if (document.path !== canonicalPath) {
@@ -220,7 +255,7 @@ async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
220
255
  throw settingsChangedError();
221
256
  let installed;
222
257
  try {
223
- installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, signal);
258
+ installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, signal, review);
224
259
  }
225
260
  catch (error) {
226
261
  if (error.code === "EEXIST") {
@@ -257,7 +292,7 @@ async function replaceLocalConfigDocumentUnlocked(document, value, signal) {
257
292
  let published = false;
258
293
  try {
259
294
  signal?.throwIfAborted();
260
- await publishConfigFile(temporaryPath, canonicalPath, document, signal);
295
+ await publishConfigFile(temporaryPath, canonicalPath, document, signal, review);
261
296
  published = true;
262
297
  await syncParentDirectory(canonicalPath);
263
298
  await afterReplacementInstalledHook();
@@ -372,7 +407,46 @@ async function secureIgnoredLegacyIfPresent(filePath) {
372
407
  await handle?.close().catch(() => undefined);
373
408
  }
374
409
  }
375
- 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) {
376
450
  let pathStat;
377
451
  try {
378
452
  pathStat = await fs.lstat(filePath);
@@ -387,16 +461,35 @@ async function readConfigSnapshotIfExists(filePath) {
387
461
  }
388
462
  if (!pathStat.isFile())
389
463
  throw new Error(`pi-sync config is not a regular file: ${filePath}`);
390
- 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));
391
467
  try {
392
468
  const openedStat = await handle.stat();
393
469
  if (openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
394
470
  throw new Error(`pi-sync config changed while opening: ${filePath}`);
395
471
  }
396
- if (process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
472
+ if (securePermissions && process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
397
473
  await handle.chmod(0o600);
398
474
  }
399
- 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
+ }
400
493
  return {
401
494
  bytes,
402
495
  identity: { dev: openedStat.dev, ino: openedStat.ino },
@@ -423,10 +516,10 @@ function parseConfigObject(bytes, filePath) {
423
516
  }
424
517
  return parsed;
425
518
  }
426
- async function installPrivateConfigExclusively(filePath, bytes, signal) {
519
+ async function installPrivateConfigExclusively(filePath, bytes, signal, review) {
427
520
  return withPrivateConfigTemporary(filePath, bytes, async (temporaryPath, installed) => {
428
521
  signal?.throwIfAborted();
429
- await publishConfigFile(temporaryPath, filePath, undefined, signal);
522
+ await publishConfigFile(temporaryPath, filePath, undefined, signal, review);
430
523
  try {
431
524
  if (!(await fileIdentityAndContentsMatch(filePath, installed, bytes))) {
432
525
  throw new Error(`Published pi-sync settings changed concurrently: ${filePath}`);
@@ -582,12 +675,17 @@ async function syncParentDirectory(filePath) {
582
675
  await handle?.close().catch(() => undefined);
583
676
  }
584
677
  }
585
- async function publishFileWithGuard(source, destination, expected, signal) {
678
+ async function publishFileWithGuard(source, destination, expected, signal, review) {
586
679
  await beforeConfigPublicationHook();
587
680
  signal?.throwIfAborted();
681
+ if (review) {
682
+ await review.check();
683
+ signal?.throwIfAborted();
684
+ assertCurrentDocument(review.document);
685
+ }
588
686
  if (expected) {
589
687
  // The shared lock orders Pi Sync writers; rename has no CAS for noncooperating writers.
590
- if (!(await configDocumentStillMatches(expected)))
688
+ if (!review && !(await configDocumentStillMatches(expected)))
591
689
  throw settingsChangedError();
592
690
  signal?.throwIfAborted();
593
691
  await fs.rename(source, destination);
@@ -1,7 +1,11 @@
1
+ import { type SyncSelectionConfig } from "../sync/sync-policy.js";
1
2
  import type { AnySyncConfig, PartialConfig, PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
2
3
  export declare function loadConfig(setupName?: string): Promise<AnySyncConfig>;
3
4
  /** A background freshness read must never trigger legacy-file publication. */
4
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>;
5
9
  export declare function configFromSettings(settings: PiSyncSettingsV3, setupName?: string): AnySyncConfig;
6
10
  export type SyncSetupStorageReview = Pick<PartialConfig, "connectionName" | "storageKind" | "storagePath" | "bucket" | "branch">;
7
11
  /** A validated setup-facing projection used by manager and settings UI. */
@@ -16,9 +20,6 @@ export declare function sessionTokenWarnings(config: {
16
20
  endpoint?: string;
17
21
  sessionToken?: string;
18
22
  }): string[];
19
- export declare function syncSessionsWarnings(config: {
20
- include: readonly string[];
21
- exclude?: readonly string[];
22
- }): string[];
23
+ export declare function syncSessionsWarnings(config: SyncSelectionConfig): string[];
23
24
  export declare function isEnabled(value: boolean | string | undefined, defaultValue: boolean): boolean;
24
25
  export declare function isExplicitlyEnabled(value: boolean | string | undefined): boolean;