@narumitw/pi-sync-daemon 0.9.0 → 0.10.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 (102) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +11 -1
  3. package/dist/cli.js +2 -0
  4. package/dist/client-transport.d.ts +14 -0
  5. package/dist/client-transport.js +66 -0
  6. package/dist/client.d.ts +15 -8
  7. package/dist/client.js +116 -86
  8. package/dist/consent.js +33 -11
  9. package/dist/daemon-debug.d.ts +3 -0
  10. package/dist/daemon-debug.js +33 -0
  11. package/dist/daemon-recovery.d.ts +4 -0
  12. package/dist/daemon-recovery.js +75 -0
  13. package/dist/engine/backends/git/git-backend.d.ts +8 -0
  14. package/dist/engine/backends/git/git-backend.js +39 -12
  15. package/dist/engine/backends/git/git-runner.js +6 -1
  16. package/dist/engine/backends/git/git-storage.js +5 -9
  17. package/dist/engine/backends/publication-encoding.d.ts +3 -0
  18. package/dist/engine/backends/publication-encoding.js +19 -0
  19. package/dist/engine/backends/s3/s3-backend.js +10 -12
  20. package/dist/engine/backends/sync-backend.d.ts +4 -0
  21. package/dist/engine/backends/webdav/webdav-backend.d.ts +0 -2
  22. package/dist/engine/backends/webdav/webdav-backend.js +15 -26
  23. package/dist/engine/backends/webdav/webdav-client.js +10 -0
  24. package/dist/engine/commands/command-types.d.ts +1 -0
  25. package/dist/engine/debug-log.d.ts +27 -0
  26. package/dist/engine/debug-log.js +134 -0
  27. package/dist/engine/ignore/ignore-initialization.d.ts +5 -1
  28. package/dist/engine/ignore/ignore-initialization.js +50 -14
  29. package/dist/engine/ignore/ignore-settings.js +11 -14
  30. package/dist/engine/ignore/ignore-source.d.ts +1 -1
  31. package/dist/engine/ignore/ignore-source.js +1 -1
  32. package/dist/engine/paths.d.ts +2 -0
  33. package/dist/engine/paths.js +7 -1
  34. package/dist/engine/settings/config-file.d.ts +10 -1
  35. package/dist/engine/settings/config-file.js +62 -17
  36. package/dist/engine/settings/config.d.ts +7 -0
  37. package/dist/engine/settings/config.js +49 -14
  38. package/dist/engine/snapshot/snapshot-apply.d.ts +2 -1
  39. package/dist/engine/snapshot/snapshot-apply.js +30 -8
  40. package/dist/engine/snapshot/snapshot-codec.js +3 -1
  41. package/dist/engine/snapshot/snapshot-payload.d.ts +4 -0
  42. package/dist/engine/snapshot/snapshot-payload.js +32 -0
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +34 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +4 -1
  46. package/dist/engine/snapshot/snapshot-transaction.js +50 -7
  47. package/dist/engine/snapshot/snapshot-types.d.ts +10 -2
  48. package/dist/engine/snapshot/snapshot.d.ts +3 -1
  49. package/dist/engine/snapshot/snapshot.js +64 -25
  50. package/dist/engine/state/lock.d.ts +2 -1
  51. package/dist/engine/state/lock.js +157 -17
  52. package/dist/engine/sync/continuous-sync.d.ts +10 -1
  53. package/dist/engine/sync/continuous-sync.js +35 -11
  54. package/dist/engine/sync/initialization.d.ts +1 -1
  55. package/dist/engine/sync/initialization.js +2 -2
  56. package/dist/engine/sync/local-fields.d.ts +6 -1
  57. package/dist/engine/sync/local-fields.js +42 -19
  58. package/dist/engine/sync/merged-sync.js +13 -10
  59. package/dist/engine/sync/remote-snapshot.js +18 -3
  60. package/dist/engine/sync/session-push.js +13 -4
  61. package/dist/engine/sync/startup-bootstrap.d.ts +1 -0
  62. package/dist/engine/sync/startup-bootstrap.js +105 -0
  63. package/dist/engine/sync/startup-recovery-evidence.d.ts +1 -0
  64. package/dist/engine/sync/startup-recovery-evidence.js +37 -0
  65. package/dist/engine/sync/startup-timings.d.ts +9 -2
  66. package/dist/engine/sync/startup-timings.js +80 -8
  67. package/dist/engine/sync/sync-error-guidance.js +22 -4
  68. package/dist/engine/sync/sync-inspection.js +4 -7
  69. package/dist/engine/sync/sync-local.d.ts +2 -1
  70. package/dist/engine/sync/sync-local.js +3 -1
  71. package/dist/engine/sync/sync-mutations.js +13 -7
  72. package/dist/engine/sync/sync-policy.d.ts +2 -0
  73. package/dist/engine/sync/sync-policy.js +9 -1
  74. package/dist/engine/sync/sync-state.d.ts +8 -3
  75. package/dist/engine/sync/sync-state.js +12 -4
  76. package/dist/engine/ui/sync-format.d.ts +16 -5
  77. package/dist/engine/ui/sync-format.js +23 -55
  78. package/dist/engine/ui/transfer-review.d.ts +2 -1
  79. package/dist/engine/ui/transfer-review.js +3 -3
  80. package/dist/engine-service.d.ts +6 -0
  81. package/dist/engine-service.js +54 -10
  82. package/dist/identity.d.ts +5 -2
  83. package/dist/identity.js +36 -6
  84. package/dist/index.d.ts +2 -1
  85. package/dist/index.js +2 -1
  86. package/dist/monitor.js +20 -1
  87. package/dist/paged-review.d.ts +35 -0
  88. package/dist/paged-review.js +177 -0
  89. package/dist/participant-ledger.d.ts +16 -0
  90. package/dist/participant-ledger.js +149 -0
  91. package/dist/protocol.d.ts +15 -0
  92. package/dist/protocol.js +4 -0
  93. package/dist/server.d.ts +7 -0
  94. package/dist/server.js +268 -120
  95. package/dist/service-host.d.ts +2 -1
  96. package/dist/service-host.js +29 -9
  97. package/dist/state-wait-jobs.d.ts +8 -0
  98. package/dist/state-wait-jobs.js +23 -0
  99. package/dist/state-wait.d.ts +7 -0
  100. package/dist/state-wait.js +34 -0
  101. package/docs/architecture.md +23 -1
  102. package/package.json +1 -1
@@ -0,0 +1,134 @@
1
+ import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync, writeSync, } from "node:fs";
2
+ import path from "node:path";
3
+ import { DEBUG_LOG_FILENAME } from "./paths.js";
4
+ import { isStartupTimingReport } from "./sync/startup-timings.js";
5
+ const OPERATIONS = [
6
+ "initialize",
7
+ "inspect",
8
+ "status",
9
+ "diff",
10
+ "doctor",
11
+ "history",
12
+ "push",
13
+ "pull",
14
+ "sync",
15
+ "startup-transfer",
16
+ "shutdown",
17
+ "conflicts",
18
+ "rollback",
19
+ "unlock",
20
+ "migrate-state",
21
+ "daemon.authorize",
22
+ "daemon.authorize-connected",
23
+ "daemon.handover",
24
+ ];
25
+ const OUTCOMES = ["started", "completed", "failed", "cancelled", "blocked", "skipped"];
26
+ const JOB_ID = /^[a-f0-9]{16}-[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u;
27
+ const MAX_RECORD_BYTES = 4_096;
28
+ const CYCLE_REASONS = [
29
+ "transient",
30
+ "contention",
31
+ "stale",
32
+ "authentication",
33
+ "storage",
34
+ "unsafe",
35
+ "model",
36
+ "budget",
37
+ "unknown",
38
+ ];
39
+ export function debugOperation(operation) {
40
+ return OPERATIONS.find((known) => known === operation);
41
+ }
42
+ function safeFields(event) {
43
+ switch (event.event) {
44
+ case "startup-timings":
45
+ if (typeof event.report === "string" &&
46
+ event.report.length <= MAX_RECORD_BYTES &&
47
+ isStartupTimingReport(event.report))
48
+ return { event: event.event, report: event.report };
49
+ break;
50
+ case "connection":
51
+ if (["completed", "failed", "cancelled", "skipped"].includes(event.outcome))
52
+ return { event: event.event, outcome: event.outcome };
53
+ break;
54
+ case "lifecycle":
55
+ if (["starting", "ready", "drained", "failed"].includes(event.outcome))
56
+ return { event: event.event, outcome: event.outcome };
57
+ break;
58
+ case "job":
59
+ if (debugOperation(event.operation) && OUTCOMES.includes(event.outcome))
60
+ return {
61
+ event: event.event,
62
+ operation: event.operation,
63
+ outcome: event.outcome,
64
+ ...(typeof event.operationId === "string" && JOB_ID.test(event.operationId)
65
+ ? { operationId: event.operationId }
66
+ : {}),
67
+ };
68
+ break;
69
+ case "continuous-cycle":
70
+ if (["completed", "failed", "cancelled", "blocked", "skipped"].includes(event.outcome))
71
+ return {
72
+ event: event.event,
73
+ outcome: event.outcome,
74
+ ...(event.reason && CYCLE_REASONS.includes(event.reason) ? { reason: event.reason } : {}),
75
+ };
76
+ break;
77
+ }
78
+ }
79
+ function owned(stat) {
80
+ return process.getuid === undefined || stat.uid === BigInt(process.getuid());
81
+ }
82
+ function privateFile(stat) {
83
+ return (stat.isFile() && stat.nlink === 1n && owned(stat) && (process.platform === "win32" || (stat.mode & 63n) === 0n));
84
+ }
85
+ function safeRoot(stat) {
86
+ return stat.isDirectory() && owned(stat) && (process.platform === "win32" || (stat.mode & 18n) === 0n);
87
+ }
88
+ function sameIdentity(left, right) {
89
+ return left.dev === right.dev && left.ino === right.ino;
90
+ }
91
+ export function appendDebugEvent(root, source, event) {
92
+ try {
93
+ if (source !== "pi-sync" && source !== "pi-sync-daemon")
94
+ return false;
95
+ const fields = safeFields(event);
96
+ if (!fields)
97
+ return false;
98
+ const bytes = Buffer.from(`${JSON.stringify({ time: new Date().toISOString(), source, pid: process.pid, ...fields })}\n`);
99
+ if (bytes.length > MAX_RECORD_BYTES)
100
+ return false;
101
+ const directory = lstatSync(root, { bigint: true });
102
+ if (!safeRoot(directory) || realpathSync(root) !== root)
103
+ return false;
104
+ const target = path.join(root, DEBUG_LOG_FILENAME);
105
+ const previous = lstatSync(target, { bigint: true, throwIfNoEntry: false });
106
+ if (previous && !privateFile(previous))
107
+ return false;
108
+ const fd = openSync(target, constants.O_CREAT |
109
+ constants.O_WRONLY |
110
+ constants.O_APPEND |
111
+ (constants.O_NOFOLLOW ?? 0) |
112
+ (constants.O_NONBLOCK ?? 0), 0o600);
113
+ try {
114
+ const opened = fstatSync(fd, { bigint: true });
115
+ const current = lstatSync(target, { bigint: true });
116
+ const currentRoot = lstatSync(root, { bigint: true });
117
+ if (!privateFile(opened) ||
118
+ !privateFile(current) ||
119
+ !sameIdentity(opened, current) ||
120
+ (previous && !sameIdentity(previous, opened)) ||
121
+ !safeRoot(currentRoot) ||
122
+ !sameIdentity(directory, currentRoot) ||
123
+ realpathSync(root) !== root)
124
+ return false;
125
+ return writeSync(fd, bytes) === bytes.length;
126
+ }
127
+ finally {
128
+ closeSync(fd);
129
+ }
130
+ }
131
+ catch {
132
+ return false;
133
+ }
134
+ }
@@ -2,8 +2,12 @@ import { type IgnoreSource } from "./ignore-source.js";
2
2
  export declare class AutomaticIgnoreCreationUnavailable extends Error {
3
3
  }
4
4
  export declare function checkAutomaticIgnoreCreation(root: string, signal: AbortSignal): Promise<void>;
5
+ export declare function readPendingIgnoreCreation(root: string, signal: AbortSignal): Promise<{
6
+ token: string;
7
+ text: string;
8
+ }>;
5
9
  export declare function initializeDefaultIgnoreSource(root: string, signal?: AbortSignal): Promise<IgnoreSource>;
6
- export declare function prepareDefaultIgnoreSource(root: string, signal?: AbortSignal): Promise<{
10
+ export declare function prepareDefaultIgnoreSource(root: string, signal?: AbortSignal, reviewedCreation?: string | null): Promise<{
7
11
  source: IgnoreSource;
8
12
  created: boolean;
9
13
  }>;
@@ -2,8 +2,11 @@ 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;
9
12
  const openExisting = process.platform === "win32" ? constants.O_RDWR | noFollow : openRead;
@@ -28,10 +31,35 @@ export async function checkAutomaticIgnoreCreation(root, signal) {
28
31
  signal.throwIfAborted();
29
32
  }
30
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
+ }
31
59
  export async function initializeDefaultIgnoreSource(root, signal) {
32
60
  return (await prepareDefaultIgnoreSource(root, signal)).source;
33
61
  }
34
- export async function prepareDefaultIgnoreSource(root, signal) {
62
+ export async function prepareDefaultIgnoreSource(root, signal, reviewedCreation) {
35
63
  signal?.throwIfAborted();
36
64
  root = path.resolve(root);
37
65
  try {
@@ -43,6 +71,10 @@ export async function prepareDefaultIgnoreSource(root, signal) {
43
71
  };
44
72
  checkRoot();
45
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
+ }
46
78
  if (!priorRecord) {
47
79
  const source = await readIgnoreSource(root, DEFAULT_IGNORE_FILENAME, signal);
48
80
  checkRoot();
@@ -67,7 +99,8 @@ export async function prepareDefaultIgnoreSource(root, signal) {
67
99
  throw error;
68
100
  });
69
101
  try {
70
- const markerStat = await flushAndVerify(marker, markerPath, path.join(root, DEFAULT_IGNORE_CREATION_RECORD), record, priorRecord ? checkRoot : verifyRoot, priorRecord, true);
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);
71
104
  await flushDirectory();
72
105
  checkRoot();
73
106
  assertCurrent(markerPath, markerStat);
@@ -85,7 +118,7 @@ export async function prepareDefaultIgnoreSource(root, signal) {
85
118
  });
86
119
  try {
87
120
  const checkTargetRoot = priorFile ? checkRoot : verifyRoot;
88
- const fileStat = await flushAndVerify(file, target, path.join(root, DEFAULT_IGNORE_FILENAME), starter, () => {
121
+ const { stat: fileStat } = await verifyCreationFile(file, target, path.join(root, DEFAULT_IGNORE_FILENAME), [starter], () => {
89
122
  checkTargetRoot();
90
123
  assertCurrent(markerPath, markerStat);
91
124
  }, priorFile);
@@ -98,7 +131,7 @@ export async function prepareDefaultIgnoreSource(root, signal) {
98
131
  checkRoot();
99
132
  const source = await readIgnoreSource(root, DEFAULT_IGNORE_FILENAME, signal);
100
133
  checkRoot();
101
- if (source.identity !== ignoreFileIdentity(fileStat) || source.text !== DEFAULT_IGNORE_RULES) {
134
+ if (source.identity !== ignoreFileIdentity(fileStat) || source.text !== starter.toString("utf8")) {
102
135
  changed(DEFAULT_IGNORE_FILENAME);
103
136
  }
104
137
  return { source, created: priorFile === undefined };
@@ -210,8 +243,9 @@ function assertOwned(stat, name, privateRecord) {
210
243
  throw new Error(`unsafe "${name}"; preserve it for manual recovery`);
211
244
  }
212
245
  }
213
- async function flushAndVerify(handle, target, canonical, expected, checkRoot, prior, privateRecord = false) {
246
+ async function verifyCreationFile(handle, target, canonical, expected, checkRoot, prior, persist = true) {
214
247
  const name = path.basename(target);
248
+ const privateRecord = name === DEFAULT_IGNORE_CREATION_RECORD;
215
249
  const opened = await handle.stat({ bigint: true });
216
250
  assertOwned(opened, name, privateRecord);
217
251
  if (prior && !sameFile(prior, opened))
@@ -221,15 +255,15 @@ async function flushAndVerify(handle, target, canonical, expected, checkRoot, pr
221
255
  throw new Error(`use the exact on-disk filename "${name}"`);
222
256
  checkRoot();
223
257
  assertCurrent(target, opened);
224
- if (!prior)
225
- await handle.writeFile(expected);
258
+ if (!prior && persist)
259
+ await handle.writeFile(expected[0]);
226
260
  const before = await handle.stat({ bigint: true });
227
261
  assertOwned(before, name, privateRecord);
228
262
  if (!(prior ? sameFile(opened, before) : sameIdentity(opened, before)))
229
263
  changed(name);
230
264
  checkRoot();
231
265
  assertCurrent(target, before);
232
- const observed = Buffer.alloc(expected.length + 1);
266
+ const observed = Buffer.alloc(Math.max(...expected.map((bytes) => bytes.length)) + 1);
233
267
  let count = 0;
234
268
  while (count < observed.length) {
235
269
  checkRoot();
@@ -238,15 +272,17 @@ async function flushAndVerify(handle, target, canonical, expected, checkRoot, pr
238
272
  break;
239
273
  count += bytesRead;
240
274
  }
241
- 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) {
242
277
  throw new Error(privateRecord
243
278
  ? `invalid creation record "${name}"; preserve it for manual recovery`
244
- : `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`);
245
280
  }
246
- await handle.sync();
281
+ if (persist)
282
+ await handle.sync();
247
283
  if (!sameFile(before, await handle.stat({ bigint: true })))
248
284
  changed(name);
249
285
  checkRoot();
250
286
  assertCurrent(target, before);
251
- return before;
287
+ return { stat: before, bytes };
252
288
  }
@@ -21,7 +21,7 @@ import { requireNoMergeJournal } from "../sync/merge-journal.js";
21
21
  import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
22
22
  import { safeTerminalText, snapshotPathLabel } from "../ui/terminal-text.js";
23
23
  import { compileEffectiveIgnorePolicy } from "./effective-ignore-policy.js";
24
- import { AutomaticIgnoreCreationUnavailable, checkAutomaticIgnoreCreation, prepareDefaultIgnoreSource, } from "./ignore-initialization.js";
24
+ import { AutomaticIgnoreCreationUnavailable, checkAutomaticIgnoreCreation, prepareDefaultIgnoreSource, readPendingIgnoreCreation, } from "./ignore-initialization.js";
25
25
  import { assertCurrentIgnoreMigrationOffer } from "./ignore-migration-prompt.js";
26
26
  import { compileIgnoreRules, DEFAULT_IGNORE_CREATION_RECORD, DEFAULT_IGNORE_FILENAME, DEFAULT_IGNORE_RULES, IgnoreCreationPendingError, ignoreSourceDigest, readIgnoreSource, validateIgnoreFilename, } from "./ignore-source.js";
27
27
  export function runIgnorePolicyChange(operation, payload, execution) {
@@ -93,18 +93,14 @@ async function readSetupSource(root, filename, signal) {
93
93
  !(error instanceof Error) ||
94
94
  !(error.cause instanceof IgnoreCreationPendingError))
95
95
  throw error;
96
- if ((await fs.realpath(root)) !== root)
97
- throw error;
98
- const marker = await fs.lstat(path.join(root, DEFAULT_IGNORE_CREATION_RECORD), { bigint: true });
96
+ const { text, token } = await readPendingIgnoreCreation(root, signal);
99
97
  signal.throwIfAborted();
100
- if (!marker.isFile() || marker.nlink !== 1n)
101
- throw error;
102
98
  return {
103
99
  filename,
104
100
  present: false,
105
- text: DEFAULT_IGNORE_RULES,
106
- sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(DEFAULT_IGNORE_RULES)),
107
- pendingCreation: `${marker.dev}:${marker.ino}:${marker.size}:${marker.ctimeNs}:${marker.mtimeNs}`,
101
+ text,
102
+ sourceDigest: ignoreSourceDigest(filename, false, Buffer.from(text)),
103
+ pendingCreation: token,
108
104
  };
109
105
  }
110
106
  }
@@ -170,7 +166,7 @@ export async function prepareReviewedIgnoreSource(root, reviewed, execution) {
170
166
  stale();
171
167
  if (current.present)
172
168
  return { source: current, created: false };
173
- const prepared = await prepareDefaultIgnoreSource(root, execution.signal).catch((error) => {
169
+ const prepared = await prepareDefaultIgnoreSource(root, execution.signal, current.pendingCreation ?? null).catch((error) => {
174
170
  execution.validate();
175
171
  throw creationFailure(root, current, error);
176
172
  });
@@ -342,11 +338,12 @@ export async function migrateIgnoreSetup(execution, setupName, offerToken) {
342
338
  }));
343
339
  }
344
340
  function describeSource(source) {
345
- if (source.pendingCreation)
346
- return "Verify or complete the interrupted creation of the starter rules. Incomplete content will not be used.";
347
- return source.present
348
- ? "Keep the existing rule file unchanged."
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."
349
345
  : "Create the default rule file with the starter rules.";
346
+ return `${action}\n${source.text.trimEnd()}`;
350
347
  }
351
348
  function describeChanges(label, before, after) {
352
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;
@@ -1,3 +1,5 @@
1
+ export declare const DEBUG_LOG_FILENAME = "pi-sync.log";
2
+ export declare function isDebugLogPath(relativePath: string): boolean;
1
3
  export declare function isDeniedPath(relativePath: string): boolean;
2
4
  export declare function isPathInside(parent: string, child: string): boolean;
3
5
  export declare function safeJoin(root: string, relativePath: string): string;
@@ -1,10 +1,16 @@
1
1
  import path from "node:path";
2
+ export const DEBUG_LOG_FILENAME = "pi-sync.log";
3
+ export function isDebugLogPath(relativePath) {
4
+ const root = relativePath.split(/[/\\:]/u, 1)[0].toLowerCase();
5
+ return root.startsWith(DEBUG_LOG_FILENAME) && /^[ .]*$/u.test(root.slice(DEBUG_LOG_FILENAME.length));
6
+ }
2
7
  export function isDeniedPath(relativePath) {
3
8
  const normalized = toPosix(relativePath);
4
9
  const lower = normalized.toLowerCase();
5
10
  const segments = lower.split("/");
6
11
  const base = path.posix.basename(lower);
7
- return (segments.includes("node_modules") ||
12
+ return (isDebugLogPath(normalized) ||
13
+ segments.includes("node_modules") ||
8
14
  segments.includes(".git") ||
9
15
  segments.includes(".pisync") ||
10
16
  segments.includes("pi-sync") ||
@@ -28,6 +28,15 @@ export declare function consumeLocalConfigMigrationNotice(): string | undefined;
28
28
  export declare function readActiveLocalConfigDocumentForRepair(): Promise<LocalConfigDocument | undefined>;
29
29
  /** Read-only bootstrap: no authority recursion, migration, or document creation. */
30
30
  export declare function peekLocalConfigDocument(): Promise<LocalConfigDocument | undefined>;
31
+ export declare function readLocalConfigForDiagnostics(root: string): Promise<{
32
+ document: {
33
+ bytes: Buffer;
34
+ identity: FileIdentity;
35
+ parsed: Record<string, unknown>;
36
+ path: string;
37
+ };
38
+ stillCurrent(): boolean;
39
+ } | undefined>;
31
40
  export declare function withLockedLocalConfigDocument<T>(run: (document: LocalConfigDocument | undefined, recheck: () => void) => Promise<T>, signal?: AbortSignal, forWrite?: boolean, { securePermissions }?: {
32
41
  securePermissions?: boolean;
33
42
  }): Promise<T>;
@@ -36,5 +45,5 @@ export declare function updateLocalConfigDocument<T extends Record<string, unkno
36
45
  export declare function createLocalConfigDocument(value: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
37
46
  export declare function replaceLocalConfigDocument(document: LocalConfigDocument, value: Record<string, unknown>): Promise<void>;
38
47
  export declare function quarantineAndRemoveConfigIfMatches(filePath: string, identity: FileIdentity, expectedBytes: Buffer): Promise<boolean>;
39
- export declare function withLocalConfigFileLock<T>(run: () => Promise<T>): Promise<T>;
48
+ export declare function withLocalConfigFileLock<T>(run: () => Promise<T>, readOnly?: boolean): Promise<T>;
40
49
  export {};
@@ -24,6 +24,9 @@ const LOCKFILE_FS_ADAPTER = {
24
24
  utimesSync,
25
25
  };
26
26
  let configUpdateQueue = Promise.resolve();
27
+ let pendingMutations = 0;
28
+ let mutationGeneration = 0;
29
+ let localReadLock;
27
30
  let publishConfigFile = publishFileWithGuard;
28
31
  let beforeConfigPublicationHook = async () => undefined;
29
32
  let afterMissingConfigReadProbeHook = async () => undefined;
@@ -118,6 +121,31 @@ async function peekUnlocked(maxBytes, securePermissions = true) {
118
121
  const filePath = (await pathExists(canonicalPath)) ? canonicalPath : legacyLocalConfigPath();
119
122
  return readConfigDocumentIfExists(filePath, maxBytes, securePermissions);
120
123
  }
124
+ export async function readLocalConfigForDiagnostics(root) {
125
+ if (pendingMutations)
126
+ return undefined;
127
+ const generation = mutationGeneration;
128
+ const canonical = path.join(root, CONFIG_FILE_NAME);
129
+ const legacy = path.join(root, LEGACY_CONFIG_FILE_NAME);
130
+ const filePath = (await pathExists(canonical)) ? canonical : legacy;
131
+ if (filePath === legacy)
132
+ await assertNoInterruptedConfigReplacement(canonical);
133
+ const document = await readConfigDocumentIfExists(filePath, MAX_SETTINGS_BYTES, false);
134
+ if (!document)
135
+ return undefined;
136
+ const locked = () => pendingMutations ||
137
+ mutationGeneration !== generation ||
138
+ (localReadLock !== canonical && lstatSync(configMutationLockPath(canonical), { throwIfNoEntry: false }));
139
+ return {
140
+ document,
141
+ stillCurrent() {
142
+ if (locked())
143
+ return false;
144
+ assertCurrentDocument(document, canonical, legacy);
145
+ return !locked();
146
+ },
147
+ };
148
+ }
121
149
  async function readConfigDocumentIfExists(filePath, maxBytes, securePermissions = true) {
122
150
  const snapshot = await readConfigSnapshotIfExists(filePath, maxBytes, securePermissions);
123
151
  return snapshot ? { path: filePath, ...snapshot } : undefined;
@@ -136,7 +164,7 @@ export function withLockedLocalConfigDocument(run, signal, forWrite = false, { s
136
164
  assertCurrentDocument(document);
137
165
  });
138
166
  });
139
- });
167
+ }, forWrite);
140
168
  }
141
169
  export async function readMigratingLocalConfigDocument(validateForMigration) {
142
170
  const authority = engineHost().config;
@@ -158,17 +186,24 @@ export async function readMigratingLocalConfigDocument(validateForMigration) {
158
186
  }
159
187
  async function withLocalConfigReadLockIfNeeded(read) {
160
188
  if ((await pathExists(localConfigPath())) || (await pathExists(legacyLocalConfigPath()))) {
161
- return withLocalConfigFileLock(read);
189
+ return withLocalConfigFileLock(read, true);
162
190
  }
163
191
  await afterMissingConfigReadProbeHook();
164
192
  if (await pathExists(configMutationLockPath()))
165
- return withLocalConfigFileLock(read);
193
+ return withLocalConfigFileLock(read, true);
166
194
  await assertNoInterruptedConfigReplacement();
167
195
  return read();
168
196
  }
169
- function queueConfigOperation(run) {
197
+ function beginConfigMutation() {
198
+ pendingMutations++;
199
+ mutationGeneration++;
200
+ return () => pendingMutations--;
201
+ }
202
+ function queueConfigOperation(run, mayMutate = false) {
170
203
  // Mutation callbacks use the unlocked helpers below, never a queued public read.
171
- const operation = configUpdateQueue.then(run);
204
+ const finished = mayMutate ? beginConfigMutation() : undefined;
205
+ const queued = configUpdateQueue.then(run);
206
+ const operation = finished ? queued.finally(finished) : queued;
172
207
  configUpdateQueue = operation.then(() => undefined, () => undefined);
173
208
  return operation;
174
209
  }
@@ -218,7 +253,7 @@ export function updateLocalConfigDocument(defaultValue, update, validate, signal
218
253
  await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next), signal, review);
219
254
  return next;
220
255
  });
221
- });
256
+ }, true);
222
257
  }
223
258
  export function createLocalConfigDocument(value, signal) {
224
259
  const authority = engineHost().config;
@@ -239,13 +274,13 @@ export function createLocalConfigDocument(value, signal) {
239
274
  throw error;
240
275
  }
241
276
  });
242
- });
277
+ }, true);
243
278
  }
244
279
  export function replaceLocalConfigDocument(document, value) {
245
280
  const authority = engineHost().config;
246
281
  if (authority)
247
282
  return authority.replace(document, value);
248
- return queueConfigOperation(() => withLocalConfigFileLock(() => replaceLocalConfigDocumentUnlocked(document, value)));
283
+ return queueConfigOperation(() => withLocalConfigFileLock(() => replaceLocalConfigDocumentUnlocked(document, value)), true);
249
284
  }
250
285
  async function replaceLocalConfigDocumentUnlocked(document, value, signal, review) {
251
286
  const nextBytes = serializedConfig(value);
@@ -353,6 +388,15 @@ async function prepareLocalConfigPath(validateForMigration) {
353
388
  if (!legacy)
354
389
  return canonicalPath;
355
390
  validateForMigration(legacy.parsed);
391
+ const finished = beginConfigMutation();
392
+ try {
393
+ return await migrateLegacyConfig(canonicalPath, legacyPath, legacy);
394
+ }
395
+ finally {
396
+ finished();
397
+ }
398
+ }
399
+ async function migrateLegacyConfig(canonicalPath, legacyPath, legacy) {
356
400
  let installedIdentity;
357
401
  try {
358
402
  installedIdentity = await installPrivateConfigExclusively(canonicalPath, legacy.bytes);
@@ -407,9 +451,7 @@ async function secureIgnoredLegacyIfPresent(filePath) {
407
451
  await handle?.close().catch(() => undefined);
408
452
  }
409
453
  }
410
- function assertCurrentDocument(document) {
411
- const canonical = localConfigPath();
412
- const legacy = legacyLocalConfigPath();
454
+ function assertCurrentDocument(document, canonical = localConfigPath(), legacy = legacyLocalConfigPath()) {
413
455
  const filePath = lstatSync(canonical, { throwIfNoEntry: false }) ? canonical : legacy;
414
456
  const before = lstatSync(filePath, { throwIfNoEntry: false });
415
457
  if (!document) {
@@ -568,7 +610,7 @@ async function configSnapshotStillMatches(filePath, snapshot) {
568
610
  return fileIdentityAndContentsMatch(filePath, snapshot.identity, snapshot.bytes);
569
611
  }
570
612
  export function quarantineAndRemoveConfigIfMatches(filePath, identity, expectedBytes) {
571
- return queueConfigOperation(() => withLocalConfigFileLock(() => quarantineAndRemoveConfigIfMatchesUnlocked(filePath, identity, expectedBytes)));
613
+ return queueConfigOperation(() => withLocalConfigFileLock(() => quarantineAndRemoveConfigIfMatchesUnlocked(filePath, identity, expectedBytes)), true);
572
614
  }
573
615
  async function quarantineAndRemoveConfigIfMatchesUnlocked(filePath, identity, expectedBytes) {
574
616
  const quarantinePath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.migration-retired`);
@@ -634,10 +676,10 @@ async function restoreQuarantinedConfig(filePath, quarantinePath) {
634
676
  // Preserve the quarantine rather than risk deleting settings that changed concurrently.
635
677
  }
636
678
  }
637
- function configMutationLockPath() {
638
- return `${localConfigPath()}.mutation-lock`;
679
+ function configMutationLockPath(configPath = localConfigPath()) {
680
+ return `${configPath}.mutation-lock`;
639
681
  }
640
- export async function withLocalConfigFileLock(run) {
682
+ export async function withLocalConfigFileLock(run, readOnly = false) {
641
683
  const configPath = localConfigPath();
642
684
  await fs.mkdir(path.dirname(configPath), { recursive: true });
643
685
  let compromisedError;
@@ -652,6 +694,8 @@ export async function withLocalConfigFileLock(run) {
652
694
  compromisedError = error;
653
695
  },
654
696
  });
697
+ if (readOnly)
698
+ localReadLock = configPath;
655
699
  try {
656
700
  await assertNoInterruptedConfigReplacement();
657
701
  const result = await run();
@@ -660,6 +704,8 @@ export async function withLocalConfigFileLock(run) {
660
704
  return result;
661
705
  }
662
706
  finally {
707
+ if (readOnly)
708
+ localReadLock = undefined;
663
709
  await release();
664
710
  }
665
711
  }
@@ -701,8 +747,7 @@ async function renameFileWithoutReplacement(source, destination, signal) {
701
747
  signal?.throwIfAborted();
702
748
  await fs.rename(source, destination);
703
749
  }
704
- async function assertNoInterruptedConfigReplacement() {
705
- const configPath = localConfigPath();
750
+ async function assertNoInterruptedConfigReplacement(configPath = localConfigPath()) {
706
751
  if (await pathExists(configPath))
707
752
  return;
708
753
  let names;
@@ -1,4 +1,5 @@
1
1
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ import { type LocalConfigDocument } from "./config-file.js";
2
3
  import type { AnySyncConfig, PartialConfig, PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
3
4
  export declare function loadConfig(setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
4
5
  /** A background freshness read must never trigger legacy-file publication. */
@@ -6,6 +7,12 @@ export declare function loadConfigForCheck(setupName?: string, signal?: AbortSig
6
7
  export declare function loadSettingsConfig(setupName?: string): Promise<AnySyncConfig>;
7
8
  export declare function requireLegacyOperationConfig(config: AnySyncConfig): AnySyncConfig;
8
9
  export declare function resolveIgnoreConfig(settings: PiSyncSettingsV3, setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
10
+ export declare function createSettingsConfigView(document: LocalConfigDocument): {
11
+ activeSetupName: string | undefined;
12
+ setupNames: string[];
13
+ metadata: (setupName?: string) => AnySyncConfig;
14
+ observe(setupName?: string, signal?: AbortSignal): Promise<AnySyncConfig>;
15
+ };
9
16
  export declare function configFromSettings(settings: PiSyncSettingsV3, setupName?: string): AnySyncConfig;
10
17
  export type SyncSetupStorageReview = Pick<PartialConfig, "connectionName" | "storageKind" | "storagePath" | "bucket" | "branch">;
11
18
  /** A validated setup-facing projection used by manager and settings UI. */