@narumitw/pi-sync-daemon 0.8.0 → 0.9.1

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 (61) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/cli.js +1 -1
  3. package/dist/consent.d.ts +14 -2
  4. package/dist/consent.js +134 -16
  5. package/dist/engine/backends/git/git-backend.d.ts +1 -2
  6. package/dist/engine/backends/git/git-backend.js +61 -30
  7. package/dist/engine/commands/command-types.d.ts +2 -1
  8. package/dist/engine/host.d.ts +1 -0
  9. package/dist/engine/ignore/ignore-initialization.d.ts +8 -1
  10. package/dist/engine/ignore/ignore-initialization.js +142 -40
  11. package/dist/engine/ignore/ignore-settings.d.ts +16 -1
  12. package/dist/engine/ignore/ignore-settings.js +94 -26
  13. package/dist/engine/ignore/ignore-source.d.ts +1 -1
  14. package/dist/engine/ignore/ignore-source.js +1 -1
  15. package/dist/engine/settings/config-file.js +1 -1
  16. package/dist/engine/settings/config.d.ts +3 -2
  17. package/dist/engine/settings/config.js +71 -28
  18. package/dist/engine/settings/settings-management.d.ts +3 -1
  19. package/dist/engine/settings/settings-management.js +8 -2
  20. package/dist/engine/settings/settings-types.d.ts +2 -0
  21. package/dist/engine/snapshot/session-paths.js +7 -2
  22. package/dist/engine/snapshot/snapshot-apply.d.ts +1 -1
  23. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +7 -2
  24. package/dist/engine/snapshot/snapshot-transaction-policy.js +37 -17
  25. package/dist/engine/snapshot/snapshot-transaction.js +55 -13
  26. package/dist/engine/snapshot/snapshot-types.d.ts +4 -0
  27. package/dist/engine/sync/agent-plan.js +1 -0
  28. package/dist/engine/sync/agent-sync.js +8 -1
  29. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  30. package/dist/engine/sync/continuous-sync.js +32 -15
  31. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  32. package/dist/engine/sync/merge-acceptance.js +29 -0
  33. package/dist/engine/sync/merge-apply.js +7 -4
  34. package/dist/engine/sync/merge-journal.d.ts +6 -0
  35. package/dist/engine/sync/merge-journal.js +33 -14
  36. package/dist/engine/sync/merged-sync.js +31 -39
  37. package/dist/engine/sync/remote-snapshot.d.ts +2 -1
  38. package/dist/engine/sync/remote-snapshot.js +17 -2
  39. package/dist/engine/sync/session-push.js +20 -6
  40. package/dist/engine/sync/sync-error-guidance.js +16 -3
  41. package/dist/engine/sync/sync-mutations.js +75 -54
  42. package/dist/engine/sync/sync-policy.d.ts +5 -0
  43. package/dist/engine/sync/sync-policy.js +28 -3
  44. package/dist/engine/sync/sync-state.d.ts +2 -0
  45. package/dist/engine/sync/sync-state.js +3 -8
  46. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  47. package/dist/engine/sync/transfer-freshness.js +82 -0
  48. package/dist/engine/ui/sync-format.d.ts +16 -5
  49. package/dist/engine/ui/sync-format.js +23 -55
  50. package/dist/engine/ui/transfer-review.d.ts +2 -1
  51. package/dist/engine/ui/transfer-review.js +3 -3
  52. package/dist/engine-service.d.ts +1 -1
  53. package/dist/engine-service.js +124 -27
  54. package/dist/monitor.d.ts +4 -1
  55. package/dist/monitor.js +84 -32
  56. package/dist/server.d.ts +1 -0
  57. package/dist/server.js +46 -5
  58. package/dist/service-host.d.ts +1 -1
  59. package/dist/service-host.js +2 -1
  60. package/docs/architecture.md +14 -6
  61. package/package.json +1 -1
@@ -2,47 +2,90 @@ import { constants, lstatSync, realpathSync, unlinkSync } from "node:fs";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { DEFAULT_IGNORE_CREATION_RECORD, DEFAULT_IGNORE_FILENAME, DEFAULT_IGNORE_RULES, ignoreFileIdentity, readIgnoreSource, sameFile, sameIdentity, } from "./ignore-source.js";
5
- const starter = Buffer.from(DEFAULT_IGNORE_RULES);
6
- const record = Buffer.from(`pi-sync-ignore-creation-v1\n${DEFAULT_IGNORE_RULES}`);
5
+ const recordPrefix = "pi-sync-ignore-creation-v1\n";
6
+ const records = [
7
+ Buffer.from(`${recordPrefix}${DEFAULT_IGNORE_RULES}`),
8
+ Buffer.from(`${recordPrefix}/npm/\n/sessions/\n/auth.json\n/truth.json\n`),
9
+ ];
7
10
  const noFollow = (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
8
11
  const openRead = constants.O_RDONLY | noFollow;
12
+ const openExisting = process.platform === "win32" ? constants.O_RDWR | noFollow : openRead;
9
13
  const openExclusive = constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | noFollow;
14
+ export class AutomaticIgnoreCreationUnavailable extends Error {
15
+ }
16
+ export async function checkAutomaticIgnoreCreation(root, signal) {
17
+ signal.throwIfAborted();
18
+ root = path.resolve(root);
19
+ const expected = await fs.lstat(root, { bigint: true });
20
+ signal.throwIfAborted();
21
+ assertRoot(root, expected);
22
+ await checkCreationAccess(root);
23
+ const { directory } = await openCreationDirectory(root, expected);
24
+ try {
25
+ signal.throwIfAborted();
26
+ await syncCreationDirectory(directory);
27
+ assertRoot(root, expected);
28
+ }
29
+ finally {
30
+ await directory?.close();
31
+ signal.throwIfAborted();
32
+ }
33
+ }
34
+ function creationRecordToken(stat) {
35
+ return `${ignoreFileIdentity(stat)}:${stat.size}:${stat.ctimeNs}:${stat.mtimeNs}`;
36
+ }
37
+ export async function readPendingIgnoreCreation(root, signal) {
38
+ signal.throwIfAborted();
39
+ root = path.resolve(root);
40
+ const initialRoot = await fs.lstat(root, { bigint: true });
41
+ const checkRoot = () => {
42
+ signal.throwIfAborted();
43
+ assertRoot(root, initialRoot);
44
+ };
45
+ checkRoot();
46
+ const target = path.join(root, DEFAULT_IGNORE_CREATION_RECORD);
47
+ const prior = await fs.lstat(target, { bigint: true });
48
+ assertOwned(prior, DEFAULT_IGNORE_CREATION_RECORD, true);
49
+ const marker = await fs.open(target, openRead);
50
+ try {
51
+ const { stat, bytes } = await verifyCreationFile(marker, target, target, records, checkRoot, prior, false);
52
+ return { token: creationRecordToken(stat), text: bytes.toString("utf8", recordPrefix.length) };
53
+ }
54
+ finally {
55
+ await marker.close();
56
+ signal.throwIfAborted();
57
+ }
58
+ }
10
59
  export async function initializeDefaultIgnoreSource(root, signal) {
11
60
  return (await prepareDefaultIgnoreSource(root, signal)).source;
12
61
  }
13
- export async function prepareDefaultIgnoreSource(root, signal) {
62
+ export async function prepareDefaultIgnoreSource(root, signal, reviewedCreation) {
14
63
  signal?.throwIfAborted();
15
64
  root = path.resolve(root);
16
65
  try {
17
66
  const initialRoot = await fs.lstat(root, { bigint: true });
18
- const assertRoot = () => {
19
- const current = lstatSync(root, { bigint: true });
20
- if (!current.isDirectory() || !sameIdentity(initialRoot, current) || realpathSync(root) !== root) {
21
- throw new Error("the Pi agent directory is not canonical or changed during initialization");
22
- }
23
- };
67
+ const verifyRoot = () => assertRoot(root, initialRoot);
24
68
  const checkRoot = () => {
25
69
  signal?.throwIfAborted();
26
- assertRoot();
70
+ verifyRoot();
27
71
  };
28
72
  checkRoot();
29
73
  const priorRecord = statAt(path.join(root, DEFAULT_IGNORE_CREATION_RECORD));
74
+ if (reviewedCreation !== undefined &&
75
+ reviewedCreation !== (priorRecord ? creationRecordToken(priorRecord) : null)) {
76
+ changed(DEFAULT_IGNORE_CREATION_RECORD);
77
+ }
30
78
  if (!priorRecord) {
31
79
  const source = await readIgnoreSource(root, DEFAULT_IGNORE_FILENAME, signal);
32
80
  checkRoot();
33
81
  if (source.present)
34
82
  return { source, created: false };
35
83
  }
36
- if (!constants.O_DIRECTORY || !constants.O_NOFOLLOW || !constants.O_NONBLOCK || process.platform === "win32") {
37
- throw new Error("this platform does not support durable directory-relative creation; use an existing ignore file");
38
- }
39
- const directory = await fs.open(root, openRead | constants.O_DIRECTORY);
84
+ await checkCreationAccess(root);
85
+ const { directory, anchor } = await openCreationDirectory(root, initialRoot);
40
86
  try {
41
- if (!sameIdentity(initialRoot, await directory.stat({ bigint: true })))
42
- changed("Pi agent directory");
43
- const anchor = await directoryAnchor(directory, initialRoot);
44
87
  checkRoot();
45
- await directory.sync();
88
+ const flushDirectory = await syncCreationDirectory(directory);
46
89
  checkRoot();
47
90
  const markerPath = path.join(anchor, DEFAULT_IGNORE_CREATION_RECORD);
48
91
  const target = path.join(anchor, DEFAULT_IGNORE_FILENAME);
@@ -50,40 +93,45 @@ export async function prepareDefaultIgnoreSource(root, signal) {
50
93
  assertOwned(priorRecord, DEFAULT_IGNORE_CREATION_RECORD, true);
51
94
  else if (statAt(target))
52
95
  changed(DEFAULT_IGNORE_FILENAME);
53
- const marker = await fs.open(markerPath, priorRecord ? openRead : openExclusive, 0o600);
96
+ const marker = await fs.open(markerPath, priorRecord ? openExisting : openExclusive, 0o600).catch((error) => {
97
+ if (!priorRecord)
98
+ checkCreationError(error);
99
+ throw error;
100
+ });
54
101
  try {
55
- const markerStat = await flushAndVerify(marker, markerPath, path.join(root, DEFAULT_IGNORE_CREATION_RECORD), record, priorRecord ? checkRoot : assertRoot, priorRecord, true);
56
- await directory.sync();
102
+ const { stat: markerStat, bytes } = await verifyCreationFile(marker, markerPath, path.join(root, DEFAULT_IGNORE_CREATION_RECORD), records, priorRecord ? checkRoot : verifyRoot, priorRecord);
103
+ const starter = bytes.subarray(recordPrefix.length);
104
+ await flushDirectory();
57
105
  checkRoot();
58
106
  assertCurrent(markerPath, markerStat);
59
107
  const priorFile = priorRecord ? statAt(target) : undefined;
60
108
  if (priorFile)
61
109
  assertOwned(priorFile, DEFAULT_IGNORE_FILENAME, false);
62
- const file = await fs.open(target, priorFile ? openRead : openExclusive, 0o600).catch(async (cause) => {
110
+ const file = await fs.open(target, priorFile ? openExisting : openExclusive, 0o600).catch(async (cause) => {
63
111
  if (!priorRecord && cause.code === "EEXIST") {
64
- assertRoot();
112
+ verifyRoot();
65
113
  assertCurrent(markerPath, markerStat);
66
114
  unlinkSync(markerPath);
67
- await directory.sync();
115
+ await flushDirectory();
68
116
  }
69
117
  throw cause;
70
118
  });
71
119
  try {
72
- const checkTargetRoot = priorFile ? checkRoot : assertRoot;
73
- const fileStat = await flushAndVerify(file, target, path.join(root, DEFAULT_IGNORE_FILENAME), starter, () => {
120
+ const checkTargetRoot = priorFile ? checkRoot : verifyRoot;
121
+ const { stat: fileStat } = await verifyCreationFile(file, target, path.join(root, DEFAULT_IGNORE_FILENAME), [starter], () => {
74
122
  checkTargetRoot();
75
123
  assertCurrent(markerPath, markerStat);
76
124
  }, priorFile);
77
- await directory.sync();
125
+ await flushDirectory();
78
126
  checkTargetRoot();
79
127
  assertCurrent(target, fileStat);
80
128
  assertCurrent(markerPath, markerStat);
81
129
  unlinkSync(markerPath);
82
- await directory.sync();
130
+ await flushDirectory();
83
131
  checkRoot();
84
132
  const source = await readIgnoreSource(root, DEFAULT_IGNORE_FILENAME, signal);
85
133
  checkRoot();
86
- if (source.identity !== ignoreFileIdentity(fileStat) || source.text !== DEFAULT_IGNORE_RULES) {
134
+ if (source.identity !== ignoreFileIdentity(fileStat) || source.text !== starter.toString("utf8")) {
87
135
  changed(DEFAULT_IGNORE_FILENAME);
88
136
  }
89
137
  return { source, created: priorFile === undefined };
@@ -97,12 +145,14 @@ export async function prepareDefaultIgnoreSource(root, signal) {
97
145
  }
98
146
  }
99
147
  finally {
100
- await directory.close();
148
+ await directory?.close();
101
149
  signal?.throwIfAborted();
102
150
  }
103
151
  }
104
152
  catch (cause) {
105
153
  signal?.throwIfAborted();
154
+ if (cause instanceof AutomaticIgnoreCreationUnavailable)
155
+ throw cause;
106
156
  const code = cause.code;
107
157
  const detail = code === "EEXIST"
108
158
  ? "a file or creation record appeared concurrently; review the current files and retry"
@@ -112,6 +162,56 @@ export async function prepareDefaultIgnoreSource(root, signal) {
112
162
  throw new Error(`Ignore file "${DEFAULT_IGNORE_FILENAME}" initialization: ${detail}.`, { cause });
113
163
  }
114
164
  }
165
+ function checkCreationError(error) {
166
+ if (["EACCES", "EPERM", "EROFS", "ENOTSUP", "EOPNOTSUPP"].includes(error.code ?? "")) {
167
+ throw new AutomaticIgnoreCreationUnavailable("the filesystem does not permit automatic creation", { cause: error });
168
+ }
169
+ }
170
+ async function checkCreationAccess(root) {
171
+ try {
172
+ await fs.access(root, constants.W_OK);
173
+ }
174
+ catch (error) {
175
+ checkCreationError(error);
176
+ throw error;
177
+ }
178
+ }
179
+ function assertRoot(root, expected) {
180
+ const current = lstatSync(root, { bigint: true });
181
+ if (!current.isDirectory() || !sameIdentity(expected, current) || realpathSync(root) !== root) {
182
+ throw new Error("the Pi agent directory is not canonical or changed during initialization");
183
+ }
184
+ }
185
+ async function openCreationDirectory(root, expected) {
186
+ if (process.platform === "win32")
187
+ return { anchor: root };
188
+ const directory = await fs.open(root, openRead | (constants.O_DIRECTORY ?? 0));
189
+ try {
190
+ if (!sameIdentity(expected, await directory.stat({ bigint: true })))
191
+ changed("Pi agent directory");
192
+ return { directory, anchor: (await directoryAnchor(directory, expected)) ?? root };
193
+ }
194
+ catch (error) {
195
+ await directory.close();
196
+ throw error;
197
+ }
198
+ }
199
+ async function syncCreationDirectory(directory) {
200
+ if (!directory)
201
+ return async () => { };
202
+ try {
203
+ await directory.sync();
204
+ return () => directory.sync();
205
+ }
206
+ catch (error) {
207
+ if (["EBADF", "EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM"].includes(error.code ?? "")) {
208
+ if (process.platform === "darwin")
209
+ return async () => { };
210
+ throw new AutomaticIgnoreCreationUnavailable("the filesystem does not support flushing the Pi agent directory");
211
+ }
212
+ throw error;
213
+ }
214
+ }
115
215
  async function directoryAnchor(directory, expected) {
116
216
  for (const base of ["/proc/self/fd", "/dev/fd"]) {
117
217
  const candidate = `${base}/${directory.fd}`;
@@ -123,7 +223,6 @@ async function directoryAnchor(directory, expected) {
123
223
  if (observed?.isDirectory() && sameIdentity(expected, observed))
124
224
  return candidate;
125
225
  }
126
- throw new Error("directory-relative creation is unavailable; use an existing ignore file");
127
226
  }
128
227
  function statAt(target) {
129
228
  return lstatSync(target, { bigint: true, throwIfNoEntry: false });
@@ -140,12 +239,13 @@ function assertOwned(stat, name, privateRecord) {
140
239
  if (!stat.isFile() ||
141
240
  stat.nlink !== 1n ||
142
241
  (process.getuid && stat.uid !== BigInt(process.getuid())) ||
143
- (privateRecord && (stat.mode & 63n) !== 0n)) {
242
+ (privateRecord && process.platform !== "win32" && (stat.mode & 63n) !== 0n)) {
144
243
  throw new Error(`unsafe "${name}"; preserve it for manual recovery`);
145
244
  }
146
245
  }
147
- async function flushAndVerify(handle, target, canonical, expected, checkRoot, prior, privateRecord = false) {
246
+ async function verifyCreationFile(handle, target, canonical, expected, checkRoot, prior, persist = true) {
148
247
  const name = path.basename(target);
248
+ const privateRecord = name === DEFAULT_IGNORE_CREATION_RECORD;
149
249
  const opened = await handle.stat({ bigint: true });
150
250
  assertOwned(opened, name, privateRecord);
151
251
  if (prior && !sameFile(prior, opened))
@@ -155,15 +255,15 @@ async function flushAndVerify(handle, target, canonical, expected, checkRoot, pr
155
255
  throw new Error(`use the exact on-disk filename "${name}"`);
156
256
  checkRoot();
157
257
  assertCurrent(target, opened);
158
- if (!prior)
159
- await handle.writeFile(expected);
258
+ if (!prior && persist)
259
+ await handle.writeFile(expected[0]);
160
260
  const before = await handle.stat({ bigint: true });
161
261
  assertOwned(before, name, privateRecord);
162
262
  if (!(prior ? sameFile(opened, before) : sameIdentity(opened, before)))
163
263
  changed(name);
164
264
  checkRoot();
165
265
  assertCurrent(target, before);
166
- const observed = Buffer.alloc(expected.length + 1);
266
+ const observed = Buffer.alloc(Math.max(...expected.map((bytes) => bytes.length)) + 1);
167
267
  let count = 0;
168
268
  while (count < observed.length) {
169
269
  checkRoot();
@@ -172,15 +272,17 @@ async function flushAndVerify(handle, target, canonical, expected, checkRoot, pr
172
272
  break;
173
273
  count += bytesRead;
174
274
  }
175
- if (count !== expected.length || !observed.subarray(0, count).equals(expected)) {
275
+ const bytes = expected.find((candidate) => observed.subarray(0, count).equals(candidate));
276
+ if (!bytes) {
176
277
  throw new Error(privateRecord
177
278
  ? `invalid creation record "${name}"; preserve it for manual recovery`
178
- : `unfinished creation of "${name}"; move the incomplete file outside the Pi agent directory or restore the full starter rules, then retry confirmed setup or migration`);
279
+ : `unfinished creation of "${name}"; move the incomplete file outside the Pi agent directory or restore the full starter rules recorded in "${DEFAULT_IGNORE_CREATION_RECORD}", then retry confirmed setup or migration`);
179
280
  }
180
- await handle.sync();
281
+ if (persist)
282
+ await handle.sync();
181
283
  if (!sameFile(before, await handle.stat({ bigint: true })))
182
284
  changed(name);
183
285
  checkRoot();
184
286
  assertCurrent(target, before);
185
- return before;
287
+ return { stat: before, bytes };
186
288
  }
@@ -1,11 +1,26 @@
1
1
  import { type Execution } from "../../protocol.js";
2
2
  import type { PiSyncSettingsV3 } from "../settings/settings-types.js";
3
3
  import { type IgnoreSource } from "./ignore-source.js";
4
+ export declare function runIgnorePolicyChange(operation: "ignore.migrate" | "ignore.switch", payload: unknown, execution: Execution): Promise<"cancelled" | "saved">;
4
5
  export declare function newIgnoreFilename(before: PiSyncSettingsV3 | undefined, next: PiSyncSettingsV3): string | undefined;
5
6
  type ReviewedIgnoreSource = IgnoreSource & {
6
7
  pendingCreation?: string;
7
8
  };
8
- export declare function reviewNewIgnoreSource(root: string, filename: string, execution: Execution): Promise<ReviewedIgnoreSource>;
9
+ export declare function reviewNewIgnoreSource(root: string, filename: string, execution: Execution): Promise<({
10
+ filename: string;
11
+ text: string;
12
+ sourceDigest: string;
13
+ } & {
14
+ present: false;
15
+ identity?: undefined;
16
+ }) | ({
17
+ filename: string;
18
+ text: string;
19
+ sourceDigest: string;
20
+ } & {
21
+ present: true;
22
+ identity: string;
23
+ })>;
9
24
  export declare function prepareReviewedIgnoreSource(root: string, reviewed: ReviewedIgnoreSource, execution: Execution): Promise<{
10
25
  source: IgnoreSource;
11
26
  created: boolean;
@@ -1,15 +1,16 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
+ import { lstatSync } from "node:fs";
2
3
  import fs from "node:fs/promises";
3
4
  import path from "node:path";
4
5
  import { requireHandover } from "../../consent.js";
5
6
  import { documentFingerprint } from "../../document.js";
6
- import { MAX_REVIEW_BYTES } from "../../protocol.js";
7
+ import { MAX_REVIEW_BYTES, record } from "../../protocol.js";
7
8
  import { createServiceContext } from "../../service-host.js";
8
9
  import { createSyncBackend } from "../backends/backend-factory.js";
9
10
  import { engineHost } from "../host.js";
10
11
  import { configFromSettings } from "../settings/config.js";
11
12
  import { peekLocalConfigDocument, updateLocalConfigDocument, } from "../settings/config-file.js";
12
- import { validateSettingsDocument } from "../settings/settings-validation.js";
13
+ import { validateConfigName, validateSettingsDocument } from "../settings/settings-validation.js";
13
14
  import { resolvedSnapshotOptionsForContext } from "../snapshot/session-paths.js";
14
15
  import { createSnapshot } from "../snapshot/snapshot.js";
15
16
  import { pendingTransactionEntries } from "../snapshot/snapshot-transaction-directory.js";
@@ -18,11 +19,32 @@ import { withLock } from "../state/lock.js";
18
19
  import { stateDir, withStateDirectoryAccess } from "../state/state-directory.js";
19
20
  import { requireNoMergeJournal } from "../sync/merge-journal.js";
20
21
  import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
21
- import { safeTerminalText } from "../ui/terminal-text.js";
22
+ import { safeTerminalText, snapshotPathLabel } from "../ui/terminal-text.js";
22
23
  import { compileEffectiveIgnorePolicy } from "./effective-ignore-policy.js";
23
- import { prepareDefaultIgnoreSource } from "./ignore-initialization.js";
24
+ import { AutomaticIgnoreCreationUnavailable, checkAutomaticIgnoreCreation, prepareDefaultIgnoreSource, readPendingIgnoreCreation, } from "./ignore-initialization.js";
24
25
  import { assertCurrentIgnoreMigrationOffer } from "./ignore-migration-prompt.js";
25
26
  import { compileIgnoreRules, DEFAULT_IGNORE_CREATION_RECORD, DEFAULT_IGNORE_FILENAME, DEFAULT_IGNORE_RULES, IgnoreCreationPendingError, ignoreSourceDigest, readIgnoreSource, validateIgnoreFilename, } from "./ignore-source.js";
27
+ export function runIgnorePolicyChange(operation, payload, execution) {
28
+ if (!record(payload) || typeof payload.setup !== "string")
29
+ throw new Error("Invalid ignore-file policy request.");
30
+ const { setup } = payload;
31
+ validateConfigName(setup, "sync setup");
32
+ if (operation === "ignore.migrate") {
33
+ const { offerToken } = payload;
34
+ if (Object.keys(payload).some((key) => key !== "setup" && key !== "offerToken") ||
35
+ (offerToken !== undefined && (typeof offerToken !== "string" || !/^[a-f0-9]{64}$/u.test(offerToken))))
36
+ throw new Error("Invalid ignore-file migration request.");
37
+ if (offerToken !== undefined && execution.facts()?.mode !== "tui")
38
+ throw new Error("Ignore migration offers require an attached TUI client.");
39
+ return migrateIgnoreSetup(execution, setup, offerToken);
40
+ }
41
+ const { filename, expectedFilename } = payload;
42
+ if (typeof filename !== "string" ||
43
+ typeof expectedFilename !== "string" ||
44
+ Object.keys(payload).some((key) => key !== "setup" && key !== "filename" && key !== "expectedFilename"))
45
+ throw new Error("Invalid ignore-file switch request.");
46
+ return switchIgnoreFile(execution, setup, filename, expectedFilename);
47
+ }
26
48
  function sourceToken(document) {
27
49
  return documentFingerprint(document ? { bytes: document.bytes.toString("base64"), identity: document.identity } : undefined);
28
50
  }
@@ -71,25 +93,58 @@ async function readSetupSource(root, filename, signal) {
71
93
  !(error instanceof Error) ||
72
94
  !(error.cause instanceof IgnoreCreationPendingError))
73
95
  throw error;
74
- if ((await fs.realpath(root)) !== root)
75
- throw error;
76
- const marker = await fs.lstat(path.join(root, DEFAULT_IGNORE_CREATION_RECORD), { bigint: true });
96
+ const { text, token } = await readPendingIgnoreCreation(root, signal);
77
97
  signal.throwIfAborted();
78
- if (!marker.isFile() || marker.nlink !== 1n)
79
- throw error;
80
98
  return {
81
99
  filename,
82
100
  present: false,
83
- text: DEFAULT_IGNORE_RULES,
84
- sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(DEFAULT_IGNORE_RULES)),
85
- pendingCreation: `${marker.dev}:${marker.ino}:${marker.size}:${marker.ctimeNs}:${marker.mtimeNs}`,
101
+ text,
102
+ sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(text)),
103
+ pendingCreation: token,
86
104
  };
87
105
  }
88
106
  }
107
+ async function readPolicyReviewSource(root, filename, execution, allowCreation) {
108
+ const { signal } = execution;
109
+ execution.validate();
110
+ signal.throwIfAborted();
111
+ filename = validateIgnoreFilename(filename);
112
+ if (filename !== DEFAULT_IGNORE_FILENAME &&
113
+ lstatSync(path.resolve(root), { throwIfNoEntry: false })?.isDirectory() &&
114
+ !lstatSync(path.resolve(root, filename), { throwIfNoEntry: false })) {
115
+ throw manualCreationRequired(root, filename);
116
+ }
117
+ const source = await (allowCreation
118
+ ? readSetupSource(root, filename, signal)
119
+ : readIgnoreSource(root, filename, signal));
120
+ execution.validate();
121
+ if (source.present)
122
+ return source;
123
+ if (!allowCreation)
124
+ throw manualCreationRequired(root, filename);
125
+ await checkAutomaticIgnoreCreation(root, signal).catch((error) => {
126
+ execution.validate();
127
+ throw creationFailure(root, source, error);
128
+ });
129
+ execution.validate();
130
+ return source;
131
+ }
132
+ function manualCreationRequired(root, filename, cause) {
133
+ return new Error(`Ignore file does not exist: ${snapshotPathLabel(path.resolve(root, filename))}\n` +
134
+ `${cause ? `${cause.message}. ` : ""}Create a regular UTF-8 text file there manually with these starter rules, then retry the Pi Sync policy change:\n${DEFAULT_IGNORE_RULES}`, { cause });
135
+ }
136
+ function creationFailure(root, source, error) {
137
+ if (!(error instanceof AutomaticIgnoreCreationUnavailable))
138
+ return error;
139
+ if (!source.pendingCreation)
140
+ return manualCreationRequired(root, source.filename, error);
141
+ return new Error(`Interrupted creation of ${snapshotPathLabel(path.resolve(root, source.filename))}. ${error.message}. ` +
142
+ `Preserve the rule file and creation record ${snapshotPathLabel(path.resolve(root, DEFAULT_IGNORE_CREATION_RECORD))}. ` +
143
+ "Retry the reviewed Pi Sync policy change where safe automatic recovery is available.", { cause: error });
144
+ }
89
145
  export async function reviewNewIgnoreSource(root, filename, execution) {
90
146
  const ctx = requireInteractive(execution);
91
- const source = await readSetupSource(root, filename, execution.signal);
92
- execution.validate();
147
+ const source = await readPolicyReviewSource(root, filename, execution, true);
93
148
  compileIgnoreRules(source.text);
94
149
  const description = describeSource(source);
95
150
  if (!(await confirm(ctx, execution, "Review ignore-file policy", [
@@ -111,7 +166,10 @@ export async function prepareReviewedIgnoreSource(root, reviewed, execution) {
111
166
  stale();
112
167
  if (current.present)
113
168
  return { source: current, created: false };
114
- const prepared = await prepareDefaultIgnoreSource(root, execution.signal);
169
+ const prepared = await prepareDefaultIgnoreSource(root, execution.signal, current.pendingCreation ?? null).catch((error) => {
170
+ execution.validate();
171
+ throw creationFailure(root, current, error);
172
+ });
115
173
  execution.validate();
116
174
  if (!prepared.source.present ||
117
175
  prepared.source.text !== reviewed.text ||
@@ -123,6 +181,10 @@ export async function switchIgnoreFile(execution, setupName, filename, expectedF
123
181
  const ctx = requireInteractive(execution);
124
182
  filename = validateIgnoreFilename(filename);
125
183
  expectedFilename = validateIgnoreFilename(expectedFilename);
184
+ if (expectedFilename !== filename) {
185
+ await readPolicyReviewSource(execution.root, filename, execution, false);
186
+ execution.validate();
187
+ }
126
188
  await requireHandover(execution);
127
189
  execution.validate();
128
190
  return withStateDirectoryAccess(() => withLock("sync", async () => {
@@ -139,10 +201,8 @@ export async function switchIgnoreFile(execution, setupName, filename, expectedF
139
201
  if ((await pendingTransactionEntries()).some((entry) => entry.isDirectory()))
140
202
  throw new Error("Resolve pending local recovery before changing the content policy.");
141
203
  await requireNoMergeJournal(configFromSettings(settings, setupName));
142
- const source = await readIgnoreSource(execution.root, filename, execution.signal);
204
+ const source = await readPolicyReviewSource(execution.root, filename, execution, false);
143
205
  execution.validate();
144
- if (!source.present)
145
- throw new Error(`Ignore file does not exist: ${safeTerminalText(path.join(execution.root, filename))}`);
146
206
  compileIgnoreRules(source.text);
147
207
  if (!(await confirm(ctx, execution, "Review changing the ignore file", [
148
208
  `Setup: ${safeTerminalText(setupName)}`,
@@ -162,6 +222,8 @@ export async function switchIgnoreFile(execution, setupName, filename, expectedF
162
222
  }
163
223
  export async function migrateIgnoreSetup(execution, setupName, offerToken) {
164
224
  const ctx = requireInteractive(execution);
225
+ await readPolicyReviewSource(execution.root, DEFAULT_IGNORE_FILENAME, execution, true);
226
+ execution.validate();
165
227
  await requireHandover(execution);
166
228
  execution.validate();
167
229
  return withStateDirectoryAccess(() => withLock("sync", async () => {
@@ -169,8 +231,13 @@ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
169
231
  execution.validate();
170
232
  if (!document)
171
233
  throw new Error("No Pi Sync settings to migrate.");
172
- if (offerToken !== undefined)
173
- assertCurrentIgnoreMigrationOffer(document, execution.root, setupName, offerToken);
234
+ const guardSettings = settingsReviewGuard(document, execution);
235
+ const validateReview = (candidate) => {
236
+ guardSettings(candidate);
237
+ if (offerToken !== undefined)
238
+ assertCurrentIgnoreMigrationOffer(candidate, execution.root, setupName, offerToken);
239
+ };
240
+ validateReview(document);
174
241
  const before = validateSettingsDocument(document.parsed);
175
242
  const setup = Object.hasOwn(before.syncSetups, setupName) ? before.syncSetups[setupName] : undefined;
176
243
  if (!setup || ignoreFilename(setup))
@@ -188,7 +255,7 @@ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
188
255
  next.syncSetups[setupName].sync = { ...common, scope: "agent-directory", sessions, pathPolicy: "ignore-file" };
189
256
  next.version = 8;
190
257
  validateSettingsDocument(next);
191
- const source = await readSetupSource(execution.root, DEFAULT_IGNORE_FILENAME, execution.signal);
258
+ const source = await readPolicyReviewSource(execution.root, DEFAULT_IGNORE_FILENAME, execution, true);
192
259
  execution.validate();
193
260
  const current = {
194
261
  ...configFromSettings(next, setupName),
@@ -242,7 +309,7 @@ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
242
309
  : fresh)
243
310
  stale();
244
311
  };
245
- await updateLocalConfigDocument(next, () => next, validateSettingsDocument, execution.signal, settingsReviewGuard(document, execution), async () => {
312
+ await updateLocalConfigDocument(next, () => next, validateSettingsDocument, execution.signal, validateReview, async () => {
246
313
  verifyHead(await backend.readHead(execution.signal));
247
314
  execution.validate();
248
315
  if (!source.present && (await collect()).fingerprint !== review.fingerprint)
@@ -271,11 +338,12 @@ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
271
338
  }));
272
339
  }
273
340
  function describeSource(source) {
274
- if (source.pendingCreation)
275
- return "Verify or complete the interrupted creation of the starter rules. Incomplete content will not be used.";
276
- return source.present
277
- ? "Keep the existing rule file unchanged."
341
+ if (source.present)
342
+ return "Keep the existing rule file unchanged.";
343
+ const action = source.pendingCreation
344
+ ? "Verify or complete the interrupted creation of the starter rules. Incomplete content will not be used."
278
345
  : "Create the default rule file with the starter rules.";
346
+ return `${action}\n${source.text.trimEnd()}`;
279
347
  }
280
348
  function describeChanges(label, before, after) {
281
349
  const oldPaths = new Set(before);
@@ -1,7 +1,7 @@
1
1
  import { type BigIntStats } from "node:fs";
2
2
  export declare const DEFAULT_IGNORE_FILENAME = ".syncignore";
3
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";
4
+ export declare const DEFAULT_IGNORE_RULES = "/auth.json\n/git/\n/npm/\n/sessions/\n/truth.json\n";
5
5
  export declare const MAX_IGNORE_BYTES: number;
6
6
  export type IgnoreSource = {
7
7
  filename: string;
@@ -6,7 +6,7 @@ import ignore from "ignore";
6
6
  import { isDeniedPath } from "../paths.js";
7
7
  export const DEFAULT_IGNORE_FILENAME = ".syncignore";
8
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";
9
+ export const DEFAULT_IGNORE_RULES = "/auth.json\n/git/\n/npm/\n/sessions/\n/truth.json\n";
10
10
  export const MAX_IGNORE_BYTES = 64 * 1024;
11
11
  const MAX_MATCH_PATH_BYTES = 4_096;
12
12
  const MATCH_CACHE_PATH_BUDGET = 2_048;
@@ -197,7 +197,7 @@ export function updateLocalConfigDocument(defaultValue, update, validate, signal
197
197
  signal?.throwIfAborted();
198
198
  if (document && JSON.stringify(document.parsed) === JSON.stringify(next))
199
199
  return next;
200
- if (beforePublish && document?.path !== localConfigPath()) {
200
+ if (beforePublish && document && document.path !== localConfigPath()) {
201
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
202
  }
203
203
  const review = reviewed
@@ -1,8 +1,8 @@
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
6
  export declare function loadSettingsConfig(setupName?: string): Promise<AnySyncConfig>;
7
7
  export declare function requireLegacyOperationConfig(config: AnySyncConfig): AnySyncConfig;
8
8
  export declare function resolveIgnoreConfig(settings: PiSyncSettingsV3, setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
@@ -16,6 +16,7 @@ export declare function syncConfigReviewIdentity(config: AnySyncConfig): string;
16
16
  export declare function syncConfigReviewFingerprint(config: AnySyncConfig): string;
17
17
  /** Internal freshness token, including credentials; never display or persist it. */
18
18
  export declare function syncCheckConfigFingerprint(config: AnySyncConfig): string;
19
+ export declare function syncSettingsConfigFingerprint(config: AnySyncConfig): string;
19
20
  export declare function sessionTokenWarnings(config: {
20
21
  endpoint?: string;
21
22
  sessionToken?: string;