@narumitw/pi-sync-daemon 0.0.0-stage → 0.3.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 (267) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/LICENSE +21 -0
  3. package/README.md +91 -2
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +127 -0
  6. package/dist/client.d.ts +57 -0
  7. package/dist/client.js +534 -0
  8. package/dist/consent.d.ts +24 -0
  9. package/dist/consent.js +205 -0
  10. package/dist/document.d.ts +10 -0
  11. package/dist/document.js +6 -0
  12. package/dist/endpoint.d.ts +8 -0
  13. package/dist/endpoint.js +91 -0
  14. package/dist/engine/backends/backend-factory.d.ts +6 -0
  15. package/dist/engine/backends/backend-factory.js +16 -0
  16. package/dist/engine/backends/backend-identity.d.ts +3 -0
  17. package/dist/engine/backends/backend-identity.js +38 -0
  18. package/dist/engine/backends/backend-types.d.ts +70 -0
  19. package/dist/engine/backends/backend-types.js +1 -0
  20. package/dist/engine/backends/git/git-backend.d.ts +55 -0
  21. package/dist/engine/backends/git/git-backend.js +700 -0
  22. package/dist/engine/backends/git/git-config.d.ts +5 -0
  23. package/dist/engine/backends/git/git-config.js +118 -0
  24. package/dist/engine/backends/git/git-runner.d.ts +25 -0
  25. package/dist/engine/backends/git/git-runner.js +232 -0
  26. package/dist/engine/backends/git/git-storage.d.ts +39 -0
  27. package/dist/engine/backends/git/git-storage.js +226 -0
  28. package/dist/engine/backends/s3/s3-backend.d.ts +32 -0
  29. package/dist/engine/backends/s3/s3-backend.js +436 -0
  30. package/dist/engine/backends/s3/s3-client.d.ts +36 -0
  31. package/dist/engine/backends/s3/s3-client.js +352 -0
  32. package/dist/engine/backends/s3/s3-conditions.d.ts +4 -0
  33. package/dist/engine/backends/s3/s3-conditions.js +66 -0
  34. package/dist/engine/backends/snapshot-pointer.d.ts +6 -0
  35. package/dist/engine/backends/snapshot-pointer.js +22 -0
  36. package/dist/engine/backends/sync-backend.d.ts +71 -0
  37. package/dist/engine/backends/sync-backend.js +23 -0
  38. package/dist/engine/backends/webdav/webdav-backend.d.ts +34 -0
  39. package/dist/engine/backends/webdav/webdav-backend.js +534 -0
  40. package/dist/engine/backends/webdav/webdav-client.d.ts +36 -0
  41. package/dist/engine/backends/webdav/webdav-client.js +326 -0
  42. package/dist/engine/backends/webdav/webdav-config.d.ts +5 -0
  43. package/dist/engine/backends/webdav/webdav-config.js +73 -0
  44. package/dist/engine/commands/command-types.d.ts +31 -0
  45. package/dist/engine/commands/command-types.js +1 -0
  46. package/dist/engine/host.d.ts +70 -0
  47. package/dist/engine/host.js +16 -0
  48. package/dist/engine/paths.d.ts +9 -0
  49. package/dist/engine/paths.js +71 -0
  50. package/dist/engine/settings/config-errors.d.ts +1 -0
  51. package/dist/engine/settings/config-errors.js +4 -0
  52. package/dist/engine/settings/config-file.d.ts +33 -0
  53. package/dist/engine/settings/config-file.js +630 -0
  54. package/dist/engine/settings/config.d.ts +24 -0
  55. package/dist/engine/settings/config.js +200 -0
  56. package/dist/engine/settings/settings-management.d.ts +24 -0
  57. package/dist/engine/settings/settings-management.js +191 -0
  58. package/dist/engine/settings/settings-store.d.ts +8 -0
  59. package/dist/engine/settings/settings-store.js +41 -0
  60. package/dist/engine/settings/settings-types.d.ts +134 -0
  61. package/dist/engine/settings/settings-types.js +1 -0
  62. package/dist/engine/settings/settings-validation.d.ts +15 -0
  63. package/dist/engine/settings/settings-validation.js +356 -0
  64. package/dist/engine/snapshot/session-paths.d.ts +12 -0
  65. package/dist/engine/snapshot/session-paths.js +91 -0
  66. package/dist/engine/snapshot/snapshot-apply.d.ts +22 -0
  67. package/dist/engine/snapshot/snapshot-apply.js +262 -0
  68. package/dist/engine/snapshot/snapshot-case-replacement.d.ts +15 -0
  69. package/dist/engine/snapshot/snapshot-case-replacement.js +82 -0
  70. package/dist/engine/snapshot/snapshot-codec.d.ts +6 -0
  71. package/dist/engine/snapshot/snapshot-codec.js +53 -0
  72. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -0
  73. package/dist/engine/snapshot/snapshot-exclude-safety.js +47 -0
  74. package/dist/engine/snapshot/snapshot-mutation-queues.d.ts +9 -0
  75. package/dist/engine/snapshot/snapshot-mutation-queues.js +133 -0
  76. package/dist/engine/snapshot/snapshot-paths.d.ts +1 -0
  77. package/dist/engine/snapshot/snapshot-paths.js +11 -0
  78. package/dist/engine/snapshot/snapshot-root-transition.d.ts +25 -0
  79. package/dist/engine/snapshot/snapshot-root-transition.js +122 -0
  80. package/dist/engine/snapshot/snapshot-transaction-directory.d.ts +2 -0
  81. package/dist/engine/snapshot/snapshot-transaction-directory.js +16 -0
  82. package/dist/engine/snapshot/snapshot-transaction-plan.d.ts +12 -0
  83. package/dist/engine/snapshot/snapshot-transaction-plan.js +68 -0
  84. package/dist/engine/snapshot/snapshot-transaction.d.ts +15 -0
  85. package/dist/engine/snapshot/snapshot-transaction.js +787 -0
  86. package/dist/engine/snapshot/snapshot-types.d.ts +48 -0
  87. package/dist/engine/snapshot/snapshot-types.js +1 -0
  88. package/dist/engine/snapshot/snapshot.d.ts +30 -0
  89. package/dist/engine/snapshot/snapshot.js +364 -0
  90. package/dist/engine/state/json-file.d.ts +6 -0
  91. package/dist/engine/state/json-file.js +49 -0
  92. package/dist/engine/state/lock-policy.d.ts +2 -0
  93. package/dist/engine/state/lock-policy.js +2 -0
  94. package/dist/engine/state/lock.d.ts +20 -0
  95. package/dist/engine/state/lock.js +259 -0
  96. package/dist/engine/state/lockfile-fs.d.ts +13 -0
  97. package/dist/engine/state/lockfile-fs.js +13 -0
  98. package/dist/engine/state/merge-baseline-store.d.ts +11 -0
  99. package/dist/engine/state/merge-baseline-store.js +187 -0
  100. package/dist/engine/state/mutation-directory-sync.d.ts +5 -0
  101. package/dist/engine/state/mutation-directory-sync.js +34 -0
  102. package/dist/engine/state/operation-availability.d.ts +49 -0
  103. package/dist/engine/state/operation-availability.js +40 -0
  104. package/dist/engine/state/state-directory.d.ts +14 -0
  105. package/dist/engine/state/state-directory.js +225 -0
  106. package/dist/engine/state/state-types.d.ts +27 -0
  107. package/dist/engine/state/state-types.js +1 -0
  108. package/dist/engine/state/sync-state-store.d.ts +11 -0
  109. package/dist/engine/state/sync-state-store.js +54 -0
  110. package/dist/engine/sync/agent-candidate.d.ts +44 -0
  111. package/dist/engine/sync/agent-candidate.js +207 -0
  112. package/dist/engine/sync/agent-plan.d.ts +8 -0
  113. package/dist/engine/sync/agent-plan.js +84 -0
  114. package/dist/engine/sync/agent-policy.d.ts +9 -0
  115. package/dist/engine/sync/agent-policy.js +10 -0
  116. package/dist/engine/sync/agent-refusal-retry.d.ts +4 -0
  117. package/dist/engine/sync/agent-refusal-retry.js +39 -0
  118. package/dist/engine/sync/agent-request.d.ts +14 -0
  119. package/dist/engine/sync/agent-request.js +13 -0
  120. package/dist/engine/sync/agent-runner.d.ts +6 -0
  121. package/dist/engine/sync/agent-runner.js +183 -0
  122. package/dist/engine/sync/agent-store.d.ts +7 -0
  123. package/dist/engine/sync/agent-store.js +177 -0
  124. package/dist/engine/sync/agent-sync.d.ts +4 -0
  125. package/dist/engine/sync/agent-sync.js +132 -0
  126. package/dist/engine/sync/apply-review.d.ts +8 -0
  127. package/dist/engine/sync/apply-review.js +51 -0
  128. package/dist/engine/sync/conflict-artifact-ownership.d.ts +4 -0
  129. package/dist/engine/sync/conflict-artifact-ownership.js +53 -0
  130. package/dist/engine/sync/conflict-artifacts.d.ts +32 -0
  131. package/dist/engine/sync/conflict-artifacts.js +158 -0
  132. package/dist/engine/sync/conflict-groups.d.ts +9 -0
  133. package/dist/engine/sync/conflict-groups.js +76 -0
  134. package/dist/engine/sync/conflict-preview.d.ts +4 -0
  135. package/dist/engine/sync/conflict-preview.js +53 -0
  136. package/dist/engine/sync/conflict-resolution.d.ts +13 -0
  137. package/dist/engine/sync/conflict-resolution.js +53 -0
  138. package/dist/engine/sync/conflict-retention.d.ts +5 -0
  139. package/dist/engine/sync/conflict-retention.js +61 -0
  140. package/dist/engine/sync/conflict-review.d.ts +4 -0
  141. package/dist/engine/sync/conflict-review.js +73 -0
  142. package/dist/engine/sync/content-conflicts.d.ts +10 -0
  143. package/dist/engine/sync/content-conflicts.js +70 -0
  144. package/dist/engine/sync/continuous-errors.d.ts +14 -0
  145. package/dist/engine/sync/continuous-errors.js +66 -0
  146. package/dist/engine/sync/continuous-lease.d.ts +9 -0
  147. package/dist/engine/sync/continuous-lease.js +206 -0
  148. package/dist/engine/sync/continuous-record.d.ts +31 -0
  149. package/dist/engine/sync/continuous-record.js +199 -0
  150. package/dist/engine/sync/continuous-storage.d.ts +14 -0
  151. package/dist/engine/sync/continuous-storage.js +59 -0
  152. package/dist/engine/sync/continuous-sync.d.ts +15 -0
  153. package/dist/engine/sync/continuous-sync.js +496 -0
  154. package/dist/engine/sync/continuous-watch.d.ts +3 -0
  155. package/dist/engine/sync/continuous-watch.js +65 -0
  156. package/dist/engine/sync/exclude-policy.d.ts +5 -0
  157. package/dist/engine/sync/exclude-policy.js +79 -0
  158. package/dist/engine/sync/field-migration.d.ts +5 -0
  159. package/dist/engine/sync/field-migration.js +20 -0
  160. package/dist/engine/sync/file-merge-planner.d.ts +36 -0
  161. package/dist/engine/sync/file-merge-planner.js +123 -0
  162. package/dist/engine/sync/initialization.d.ts +12 -0
  163. package/dist/engine/sync/initialization.js +75 -0
  164. package/dist/engine/sync/json-document.d.ts +29 -0
  165. package/dist/engine/sync/json-document.js +172 -0
  166. package/dist/engine/sync/local-field-policy.d.ts +2 -0
  167. package/dist/engine/sync/local-field-policy.js +26 -0
  168. package/dist/engine/sync/local-fields.d.ts +9 -0
  169. package/dist/engine/sync/local-fields.js +116 -0
  170. package/dist/engine/sync/merge-apply.d.ts +5 -0
  171. package/dist/engine/sync/merge-apply.js +386 -0
  172. package/dist/engine/sync/merge-journal.d.ts +31 -0
  173. package/dist/engine/sync/merge-journal.js +179 -0
  174. package/dist/engine/sync/merge-transfer-error.d.ts +3 -0
  175. package/dist/engine/sync/merge-transfer-error.js +64 -0
  176. package/dist/engine/sync/merged-sync.d.ts +6 -0
  177. package/dist/engine/sync/merged-sync.js +618 -0
  178. package/dist/engine/sync/mutation-owner.d.ts +2 -0
  179. package/dist/engine/sync/mutation-owner.js +18 -0
  180. package/dist/engine/sync/package-merge.d.ts +3 -0
  181. package/dist/engine/sync/package-merge.js +82 -0
  182. package/dist/engine/sync/partial-progress.d.ts +15 -0
  183. package/dist/engine/sync/partial-progress.js +39 -0
  184. package/dist/engine/sync/remote-snapshot.d.ts +28 -0
  185. package/dist/engine/sync/remote-snapshot.js +62 -0
  186. package/dist/engine/sync/resolver-stream.d.ts +4 -0
  187. package/dist/engine/sync/resolver-stream.js +34 -0
  188. package/dist/engine/sync/session-merge.d.ts +3 -0
  189. package/dist/engine/sync/session-merge.js +178 -0
  190. package/dist/engine/sync/session-push.d.ts +5 -0
  191. package/dist/engine/sync/session-push.js +32 -0
  192. package/dist/engine/sync/settings-conflicts.d.ts +8 -0
  193. package/dist/engine/sync/settings-conflicts.js +56 -0
  194. package/dist/engine/sync/settings-merge.d.ts +13 -0
  195. package/dist/engine/sync/settings-merge.js +93 -0
  196. package/dist/engine/sync/signals.d.ts +2 -0
  197. package/dist/engine/sync/signals.js +8 -0
  198. package/dist/engine/sync/startup-timings.d.ts +11 -0
  199. package/dist/engine/sync/startup-timings.js +44 -0
  200. package/dist/engine/sync/sync-decision.d.ts +35 -0
  201. package/dist/engine/sync/sync-decision.js +66 -0
  202. package/dist/engine/sync/sync-error-guidance.d.ts +2 -0
  203. package/dist/engine/sync/sync-error-guidance.js +55 -0
  204. package/dist/engine/sync/sync-errors.d.ts +9 -0
  205. package/dist/engine/sync/sync-errors.js +18 -0
  206. package/dist/engine/sync/sync-inspection.d.ts +26 -0
  207. package/dist/engine/sync/sync-inspection.js +40 -0
  208. package/dist/engine/sync/sync-loaders.d.ts +7 -0
  209. package/dist/engine/sync/sync-loaders.js +8 -0
  210. package/dist/engine/sync/sync-local.d.ts +5 -0
  211. package/dist/engine/sync/sync-local.js +40 -0
  212. package/dist/engine/sync/sync-mutations.d.ts +30 -0
  213. package/dist/engine/sync/sync-mutations.js +589 -0
  214. package/dist/engine/sync/sync-operations.d.ts +2 -0
  215. package/dist/engine/sync/sync-operations.js +3 -0
  216. package/dist/engine/sync/sync-policy.d.ts +85 -0
  217. package/dist/engine/sync/sync-policy.js +356 -0
  218. package/dist/engine/sync/sync-queries.d.ts +7 -0
  219. package/dist/engine/sync/sync-queries.js +195 -0
  220. package/dist/engine/sync/sync-state.d.ts +31 -0
  221. package/dist/engine/sync/sync-state.js +92 -0
  222. package/dist/engine/sync/text-merge.d.ts +19 -0
  223. package/dist/engine/sync/text-merge.js +124 -0
  224. package/dist/engine/types.d.ts +5 -0
  225. package/dist/engine/types.js +2 -0
  226. package/dist/engine/ui/merge-review.d.ts +2 -0
  227. package/dist/engine/ui/merge-review.js +7 -0
  228. package/dist/engine/ui/merged-sync-summary.d.ts +25 -0
  229. package/dist/engine/ui/merged-sync-summary.js +86 -0
  230. package/dist/engine/ui/sync-format.d.ts +13 -0
  231. package/dist/engine/ui/sync-format.js +150 -0
  232. package/dist/engine/ui/sync-status.d.ts +9 -0
  233. package/dist/engine/ui/sync-status.js +30 -0
  234. package/dist/engine/ui/terminal-text.d.ts +3 -0
  235. package/dist/engine/ui/terminal-text.js +9 -0
  236. package/dist/engine/ui/transfer-changes.d.ts +12 -0
  237. package/dist/engine/ui/transfer-changes.js +24 -0
  238. package/dist/engine/ui/transfer-review.d.ts +3 -0
  239. package/dist/engine/ui/transfer-review.js +19 -0
  240. package/dist/engine-service.d.ts +14 -0
  241. package/dist/engine-service.js +322 -0
  242. package/dist/identity.d.ts +20 -0
  243. package/dist/identity.js +133 -0
  244. package/dist/idle-exit.d.ts +17 -0
  245. package/dist/idle-exit.js +77 -0
  246. package/dist/index.d.ts +8 -0
  247. package/dist/index.js +4 -0
  248. package/dist/lifecycle-log.d.ts +7 -0
  249. package/dist/lifecycle-log.js +53 -0
  250. package/dist/lifecycle.d.ts +2 -0
  251. package/dist/lifecycle.js +21 -0
  252. package/dist/model-signature.d.ts +2 -0
  253. package/dist/model-signature.js +7 -0
  254. package/dist/monitor.d.ts +14 -0
  255. package/dist/monitor.js +272 -0
  256. package/dist/participant-admission.d.ts +5 -0
  257. package/dist/participant-admission.js +30 -0
  258. package/dist/protocol.d.ts +102 -0
  259. package/dist/protocol.js +97 -0
  260. package/dist/resolver-host.d.ts +11 -0
  261. package/dist/resolver-host.js +78 -0
  262. package/dist/server.d.ts +24 -0
  263. package/dist/server.js +808 -0
  264. package/dist/service-host.d.ts +7 -0
  265. package/dist/service-host.js +174 -0
  266. package/docs/architecture.md +162 -0
  267. package/package.json +54 -4
@@ -0,0 +1,93 @@
1
+ import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
2
+ import { mergePackageVersions } from "./package-merge.js";
3
+ export const COUPLED_FIELDS = [
4
+ ["defaultProvider", "defaultModel"],
5
+ ["queueMode", "steeringMode"],
6
+ ["websockets", "transport"],
7
+ ["skills", "enableSkillCommands"],
8
+ ["enableAnalytics", "trackingId"],
9
+ ];
10
+ function selectPackages(base, left, right) {
11
+ const packages = mergePackageVersions(base.root.members.get("packages")?.node.value, left.root.members.get("packages")?.node.value, right.root.members.get("packages")?.node.value);
12
+ if (!packages)
13
+ return undefined;
14
+ const document = [left, right].find((source) => jsonEqual(source.root.members.get("packages")?.node.value, packages)) ??
15
+ parseSettingsDocument(Buffer.from(JSON.stringify({ packages })));
16
+ const node = document.root.members.get("packages")?.node;
17
+ return node ? { document, node } : undefined;
18
+ }
19
+ /** Accepted files need only a package override, not another full-document field merge. */
20
+ export function mergeAcceptedSettingsPackages(ancestor, local, remote, accepted) {
21
+ try {
22
+ const base = parseSettingsDocument(ancestor);
23
+ const left = parseSettingsDocument(local);
24
+ const right = parseSettingsDocument(remote);
25
+ const document = parseSettingsDocument(accepted);
26
+ const packages = selectPackages(base, left, right);
27
+ if (!packages || jsonEqual(packages.node.value, document.root.members.get("packages")?.node.value))
28
+ return undefined;
29
+ const selected = new Map([...document.root.members].map(([key, member]) => [key, { document, node: member.node }]));
30
+ selected.set("packages", packages);
31
+ return renderSettingsMembers(document, selected);
32
+ }
33
+ catch {
34
+ // Unsupported settings must not replace an accepted file with a reconstructed document.
35
+ return undefined;
36
+ }
37
+ }
38
+ /** Only global settings.json; objects/arrays are atomic units until their invariants are proven. */
39
+ export function mergeSettingsJson(ancestor, local, remote, selections = new Map(), preferHigherPackageVersions = false) {
40
+ let documents;
41
+ try {
42
+ documents = [ancestor, local, remote].map(parseSettingsDocument);
43
+ }
44
+ catch {
45
+ return { kind: "review", reason: "unsupported-format", fields: [] };
46
+ }
47
+ const [base, left, right] = documents;
48
+ const selected = new Map();
49
+ const fields = new Set(documents.flatMap((document) => [...document.root.members.keys()]));
50
+ const units = COUPLED_FIELDS.map((group) => [...group]);
51
+ const coupled = new Set(units.flat());
52
+ units.push(...[...fields].filter((field) => !coupled.has(field)).map((field) => [field]));
53
+ const conflicts = [];
54
+ for (const unit of units) {
55
+ if (preferHigherPackageVersions && unit[0] === "packages") {
56
+ const packages = selectPackages(base, left, right);
57
+ if (packages) {
58
+ selected.set("packages", packages);
59
+ continue;
60
+ }
61
+ }
62
+ const equal = (first, second) => unit.every((field) => jsonEqual(first.root.members.get(field)?.node.value, second.root.members.get(field)?.node.value));
63
+ const choice = selections.get(unit[0] ?? "");
64
+ const source = equal(left, right)
65
+ ? left
66
+ : equal(left, base)
67
+ ? right
68
+ : equal(right, base)
69
+ ? left
70
+ : choice === "local"
71
+ ? left
72
+ : choice === "remote"
73
+ ? right
74
+ : undefined;
75
+ if (!source) {
76
+ conflicts.push(...unit.filter((field) => fields.has(field)));
77
+ continue;
78
+ }
79
+ for (const field of unit) {
80
+ const member = source.root.members.get(field);
81
+ if (member)
82
+ selected.set(field, { document: source, node: member.node });
83
+ }
84
+ }
85
+ if (conflicts.length)
86
+ return { kind: "review", reason: "field-conflict", fields: conflicts };
87
+ try {
88
+ return { kind: "merged", content: renderSettingsMembers(left, selected) };
89
+ }
90
+ catch {
91
+ return { kind: "review", reason: "unsupported-format", fields: [] };
92
+ }
93
+ }
@@ -0,0 +1,2 @@
1
+ export declare function throwIfAborted(signal?: AbortSignal): void;
2
+ export declare function combineSignals(primary: AbortSignal, secondary?: AbortSignal): AbortSignal;
@@ -0,0 +1,8 @@
1
+ export function throwIfAborted(signal) {
2
+ if (!signal?.aborted)
3
+ return;
4
+ throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
5
+ }
6
+ export function combineSignals(primary, secondary) {
7
+ return secondary ? AbortSignal.any([primary, secondary]) : primary;
8
+ }
@@ -0,0 +1,11 @@
1
+ import type { EngineContext as ExtensionContext } from "../host.js";
2
+ type StartupStage = "daemon initialization" | "transaction recovery" | "settings read" | "config resolution" | "inspection import" | "inspection and guards" | "backend initialization" | "local snapshot" | "sync state read" | "remote head" | "operations import" | "automatic transfer" | "transfer authorization" | "transfer backend initialization" | "transfer journal read" | "transfer journal recovery" | "transfer state read" | "transfer local snapshot" | "transfer remote head" | "transfer snapshot download" | "transfer unchanged verification" | "transfer merge planning" | "transfer settings merge" | "transfer content merge" | "transfer preflight" | "transfer backup" | "transfer journal write" | "transfer remote publication" | "transfer local apply" | "transfer baseline write" | "transfer cleanup";
3
+ export type StartupTimingPublisher = (ctx: ExtensionContext, report: string) => void;
4
+ /** Fixed labels and durations only: never retain errors, paths, settings, or payloads. */
5
+ export declare function createStartupTimings(publishReport?: StartupTimingPublisher): {
6
+ markUnchanged(): void;
7
+ measure<T>(stage: StartupStage, run: () => T | Promise<T>): Promise<T>;
8
+ publish(ctx: ExtensionContext, enabled: boolean, sessionSignal: AbortSignal, scope: "local initialization" | "background startup" | "continuous startup" | "daemon inspection" | "daemon transfer", outcome?: "completed" | "stopped"): void;
9
+ };
10
+ export type StartupTimings = ReturnType<typeof createStartupTimings>;
11
+ export {};
@@ -0,0 +1,44 @@
1
+ import { performance } from "node:perf_hooks";
2
+ /** Fixed labels and durations only: never retain errors, paths, settings, or payloads. */
3
+ export function createStartupTimings(publishReport = (ctx, report) => ctx.ui.notify(report, "info")) {
4
+ const started = performance.now();
5
+ const stages = new Map();
6
+ let unchanged = false;
7
+ return {
8
+ markUnchanged() {
9
+ unchanged = true;
10
+ },
11
+ async measure(stage, run) {
12
+ const start = performance.now();
13
+ let completed = false;
14
+ try {
15
+ const result = await run();
16
+ completed = true;
17
+ return result;
18
+ }
19
+ finally {
20
+ const previous = stages.get(stage);
21
+ stages.set(stage, {
22
+ ms: (previous?.ms ?? 0) + performance.now() - start,
23
+ calls: (previous?.calls ?? 0) + 1,
24
+ interrupted: Boolean(previous?.interrupted || !completed),
25
+ });
26
+ }
27
+ },
28
+ publish(ctx, enabled, sessionSignal, scope, outcome = "completed") {
29
+ if (!enabled || !ctx.hasUI || sessionSignal.aborted)
30
+ return;
31
+ try {
32
+ publishReport(ctx, [
33
+ `pi-sync debug: ${scope} (${outcome})`,
34
+ ...Array.from(stages, ([stage, value]) => `${stage}: ${value.ms.toFixed(1)} ms${value.calls > 1 ? ` (${value.calls} calls)` : ""}${value.interrupted ? " (interrupted)" : ""}`),
35
+ ...(unchanged ? ["transfer result: unchanged (fast path)"] : []),
36
+ `total: ${(performance.now() - started).toFixed(1)} ms`,
37
+ ].join("\n"));
38
+ }
39
+ catch {
40
+ // Diagnostics must not change sync behavior if the UI is unavailable during teardown.
41
+ }
42
+ },
43
+ };
44
+ }
@@ -0,0 +1,35 @@
1
+ import type { AnySyncConfig } from "../settings/settings-types.js";
2
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
3
+ import type { SyncState } from "../state/state-types.js";
4
+ import { SyncDecisionRequiredError } from "./sync-errors.js";
5
+ export type SyncDecisionKind = "remote-or-policy-changed" | "both-changed" | "first-sync-settings-diverged" | "first-sync-sessions-diverged" | "remote-empty";
6
+ export type SyncResolutionDirection = "push" | "pull";
7
+ export interface SyncDecision {
8
+ kind: SyncDecisionKind;
9
+ setupName: string;
10
+ configIdentity: string;
11
+ causes: {
12
+ localChanged: boolean;
13
+ remoteChanged: boolean;
14
+ policyChanged: boolean;
15
+ };
16
+ previousInclude?: readonly string[];
17
+ currentInclude: readonly string[];
18
+ previousExclude?: readonly string[];
19
+ currentExclude?: readonly string[];
20
+ review: string;
21
+ directions: readonly SyncResolutionDirection[];
22
+ directMessage: string;
23
+ }
24
+ export { isSyncDecisionRequiredError, SyncDecisionRequiredError, } from "./sync-errors.js";
25
+ interface CreateSyncDecisionOptions {
26
+ kind: SyncDecisionKind;
27
+ config: AnySyncConfig;
28
+ state: SyncState;
29
+ local: Snapshot;
30
+ remote?: Snapshot;
31
+ localChanged: boolean;
32
+ remoteChanged: boolean;
33
+ directMessage: string;
34
+ }
35
+ export declare function createSyncDecision(options: CreateSyncDecisionOptions): SyncDecisionRequiredError;
@@ -0,0 +1,66 @@
1
+ import { syncConfigReviewIdentity } from "../settings/config.js";
2
+ import { formatDiff, formatSnapshotOnlyDiff } from "../ui/sync-format.js";
3
+ import { safeTerminalText } from "../ui/terminal-text.js";
4
+ import { SyncDecisionRequiredError } from "./sync-errors.js";
5
+ import { includeFromSelectionConfig } from "./sync-policy.js";
6
+ import { syncPolicyChanged } from "./sync-state.js";
7
+ export { isSyncDecisionRequiredError, SyncDecisionRequiredError, } from "./sync-errors.js";
8
+ export function createSyncDecision(options) {
9
+ const { config, state, local, remote, kind } = options;
10
+ const policyChanged = Boolean(state.lastAppliedSnapshot) && syncPolicyChanged(state, config);
11
+ const previousInclude = includeFromSelectionConfig(state);
12
+ const currentInclude = [...config.include];
13
+ const causes = {
14
+ localChanged: options.localChanged,
15
+ remoteChanged: options.remoteChanged,
16
+ policyChanged,
17
+ };
18
+ const causeLines = kind === "first-sync-settings-diverged"
19
+ ? ["This machine and the remote have different Pi settings on first sync."]
20
+ : kind === "first-sync-sessions-diverged"
21
+ ? ["Pi settings match, but local and remote sessions differ on first sync."]
22
+ : kind === "remote-empty"
23
+ ? ["The remote storage location is empty."]
24
+ : [
25
+ ...(causes.localChanged ? ["Local content changed since the last sync."] : []),
26
+ ...(causes.remoteChanged ? ["Remote content changed since the last sync."] : []),
27
+ ...(causes.policyChanged ? ["Included content changed since the last sync."] : []),
28
+ ];
29
+ const comparison = remote
30
+ ? formatDiff(local, remote)
31
+ : formatSnapshotOnlyDiff("Remote is empty. Local push would upload", local);
32
+ const review = [
33
+ `Sync setup: ${safeTerminalText(config.setupName)}`,
34
+ "",
35
+ "Why a decision is required:",
36
+ ...causeLines,
37
+ ...(policyChanged
38
+ ? [
39
+ "",
40
+ `Previously included: ${safeList(previousInclude)}`,
41
+ `Currently included: ${safeList(currentInclude)}`,
42
+ `Previously excluded: ${safeList(state.exclude ?? [])}`,
43
+ `Currently excluded: ${safeList(config.exclude ?? [])}`,
44
+ ]
45
+ : []),
46
+ "",
47
+ "Observed differences:",
48
+ ...comparison.split("\n").map(safeTerminalText),
49
+ ].join("\n");
50
+ return new SyncDecisionRequiredError({
51
+ kind,
52
+ setupName: config.setupName,
53
+ configIdentity: syncConfigReviewIdentity(config),
54
+ causes,
55
+ ...(policyChanged ? { previousInclude: [...previousInclude] } : {}),
56
+ currentInclude,
57
+ ...(policyChanged && state.exclude !== undefined ? { previousExclude: [...state.exclude] } : {}),
58
+ ...(config.exclude === undefined ? {} : { currentExclude: [...config.exclude] }),
59
+ review,
60
+ directions: kind === "remote-empty" ? ["push"] : ["push", "pull"],
61
+ directMessage: options.directMessage,
62
+ });
63
+ }
64
+ function safeList(values) {
65
+ return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
66
+ }
@@ -0,0 +1,2 @@
1
+ /** Add recovery advice without changing backend outcome semantics or printing error causes. */
2
+ export declare function syncErrorGuidance(error: unknown): string;
@@ -0,0 +1,55 @@
1
+ import { errorMessage } from "./sync-errors.js";
2
+ /** Add recovery advice without changing backend outcome semantics or printing error causes. */
3
+ export function syncErrorGuidance(error) {
4
+ const detail = errorMessage(error);
5
+ const message = detail.length > 1200 ? `${detail.slice(0, 1200)}… (details truncated)` : detail;
6
+ const code = error?.code;
7
+ const status = error?.status;
8
+ let next;
9
+ if (code === "ENOSPC") {
10
+ next = "Free disk space for the private pi-sync settings/state directory, then retry.";
11
+ }
12
+ else if (code && ["EACCES", "EPERM", "EROFS"].includes(code)) {
13
+ next = "Check write access to the private pi-sync settings/state directory, then retry.";
14
+ }
15
+ else if (code && ["EBUSY", "EIO", "EMFILE", "ENFILE"].includes(code)) {
16
+ next = "Check local disk availability and other processes using the private settings file, then retry.";
17
+ }
18
+ else if (/changed while|type changed|reopen/iu.test(message)) {
19
+ next = "Reopen the item in /sync and review its current settings before saving again.";
20
+ }
21
+ else if (status === 401 ||
22
+ status === 403 ||
23
+ /Permission denied|Authentication failed|HTTP (401|403)|failed \((401|403)\)/iu.test(message)) {
24
+ next = "Check the storage connection's credentials and remote permissions in /sync → More → Storage connections.";
25
+ }
26
+ else if (status === 404 || /HTTP 404|failed \(404\)/iu.test(message)) {
27
+ next =
28
+ "Verify the connection address and setup's bucket, branch, or path with your provider; this response alone does not prove which resource is missing.";
29
+ }
30
+ else if (status !== undefined && status >= 500) {
31
+ next = "Check your storage provider's service status, then retry Check setup before syncing.";
32
+ }
33
+ else if (/timed out|timeout|request failed|resolve host|Could not resolve|ENOTFOUND|ECONNREFUSED/iu.test(message)) {
34
+ next = "Check the server address and network connection, then run /sync doctor for the affected setup.";
35
+ }
36
+ else if (/strong ETag|If-Match|If-None-Match|precondition|conditional header/iu.test(message)) {
37
+ next =
38
+ "Ask your provider to check strong ETags and conditional writes, including proxy behavior, or choose compatible storage. Do not bypass these safety checks.";
39
+ }
40
+ else if (/spawn git ENOENT/iu.test(message)) {
41
+ next = "Install Git 2.30 or newer and make sure Pi can find git on PATH, then retry.";
42
+ }
43
+ else if (/response exceeds.*byte limit/iu.test(message)) {
44
+ next =
45
+ "Verify the storage endpoint; the server returned an unexpectedly large response. Check your provider's logs before retrying.";
46
+ }
47
+ else if (/settings|config|already exists|duplicates|same normalized/iu.test(message)) {
48
+ next =
49
+ "Correct the named field or item in /sync. If the settings file is invalid, repair it before retrying; do not replace it with defaults.";
50
+ }
51
+ else {
52
+ next = "Open /sync → More → Check setup and review the reported checks before retrying.";
53
+ }
54
+ return `${message}\n${next}`;
55
+ }
@@ -0,0 +1,9 @@
1
+ import type { SyncDecision } from "./sync-decision.js";
2
+ export declare class SetupPullRequiresUiError extends Error {
3
+ }
4
+ export declare class SyncDecisionRequiredError extends Error {
5
+ readonly decision: SyncDecision;
6
+ constructor(decision: SyncDecision);
7
+ }
8
+ export declare function isSyncDecisionRequiredError(error: unknown): error is SyncDecisionRequiredError;
9
+ export declare function errorMessage(error: unknown): string;
@@ -0,0 +1,18 @@
1
+ export class SetupPullRequiresUiError extends Error {
2
+ }
3
+ export class SyncDecisionRequiredError extends Error {
4
+ decision;
5
+ constructor(decision) {
6
+ super(decision.directMessage);
7
+ this.name = "SyncDecisionRequiredError";
8
+ this.decision = decision;
9
+ }
10
+ }
11
+ export function isSyncDecisionRequiredError(error) {
12
+ return error instanceof SyncDecisionRequiredError;
13
+ }
14
+ export function errorMessage(error) {
15
+ const message = error instanceof Error ? error.message : String(error);
16
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
17
+ return message.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");
18
+ }
@@ -0,0 +1,26 @@
1
+ import { type SyncBackendFactory } from "../backends/backend-factory.js";
2
+ import type { AnySyncConfig } from "../settings/settings-types.js";
3
+ import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
4
+ import { type StartupTimings } from "./startup-timings.js";
5
+ /** Advisory baseline-relative observation, never an authorization to transfer files. */
6
+ export declare function inspectSync(config: AnySyncConfig, options: SnapshotOptions, signal?: AbortSignal, factory?: SyncBackendFactory, timings?: StartupTimings): Promise<{
7
+ localIdentity?: string;
8
+ head: import("../backends/sync-backend.js").RemoteHead | undefined;
9
+ selectionState: import("./sync-policy.js").RemoteSelectionState | undefined;
10
+ localFiles: number;
11
+ localChanged: boolean;
12
+ remoteChanged: boolean;
13
+ firstSync: boolean;
14
+ emptyInclude: boolean;
15
+ stateIdentity: string;
16
+ destination: string;
17
+ capability: import("../backends/sync-backend.js").PublicationCapability;
18
+ }>;
19
+ export type SyncInspection = Awaited<ReturnType<typeof inspectSync>>;
20
+ export interface StartupObservation {
21
+ setupName: string;
22
+ configIdentity: string;
23
+ checkedAt: string;
24
+ automaticTransfer?: boolean;
25
+ inspection: SyncInspection;
26
+ }
@@ -0,0 +1,40 @@
1
+ import { createHash } from "node:crypto";
2
+ import { createSyncBackend } from "../backends/backend-factory.js";
3
+ import { createSnapshot } from "../snapshot/snapshot.js";
4
+ import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
5
+ import { throwIfAborted } from "./signals.js";
6
+ import { createStartupTimings } from "./startup-timings.js";
7
+ import { inspectRemoteSelection } from "./sync-policy.js";
8
+ import { fileHashMap, hasLocalChanges, remoteChangedSinceState } from "./sync-state.js";
9
+ /** Advisory baseline-relative observation, never an authorization to transfer files. */
10
+ export async function inspectSync(config, options, signal, factory = createSyncBackend, timings = createStartupTimings()) {
11
+ throwIfAborted(signal);
12
+ const backend = await timings.measure("backend initialization", () => factory(config));
13
+ throwIfAborted(signal);
14
+ const local = await timings.measure("local snapshot", () => createSnapshot(config.snapshotIdentity, { ...options, signal }));
15
+ throwIfAborted(signal);
16
+ const state = await timings.measure("sync state read", () => readStateForConfig(config));
17
+ throwIfAborted(signal);
18
+ const head = await timings.measure("remote head", () => backend.readHead(signal));
19
+ throwIfAborted(signal);
20
+ const freshness = {
21
+ localIdentity: createHash("sha256")
22
+ .update(JSON.stringify(fileHashMap(local)))
23
+ .digest("hex"),
24
+ };
25
+ return {
26
+ ...freshness,
27
+ head,
28
+ selectionState: head
29
+ ? inspectRemoteSelection(config.include, { selection: head.selection, files: [] }, config.exclude)
30
+ : undefined,
31
+ localFiles: local.files.length,
32
+ localChanged: hasLocalChanges(local, state, config),
33
+ remoteChanged: remoteChangedSinceState(head, state, config, (left, right) => backend.sameRevision(left, right)),
34
+ firstSync: !state.lastAppliedSnapshot,
35
+ emptyInclude: config.include.length === 0,
36
+ stateIdentity: syncStateFingerprint(state),
37
+ destination: backend.destination,
38
+ capability: backend.capability,
39
+ };
40
+ }
@@ -0,0 +1,7 @@
1
+ export interface SyncLoaders {
2
+ inspection(): Promise<Pick<typeof import("./sync-inspection.js"), "inspectSync">>;
3
+ snapshot(): Promise<Pick<typeof import("../snapshot/snapshot.js"), "createSnapshot">>;
4
+ syncState(): Promise<Pick<typeof import("./sync-state.js"), "hasLocalChanges">>;
5
+ operations(): Promise<typeof import("./sync-operations.js")>;
6
+ }
7
+ export declare function createEngineLoaders(): SyncLoaders;
@@ -0,0 +1,8 @@
1
+ export function createEngineLoaders() {
2
+ return {
3
+ inspection: () => import("./sync-inspection.js"),
4
+ snapshot: () => import("../snapshot/snapshot.js"),
5
+ syncState: () => import("./sync-state.js"),
6
+ operations: () => import("./sync-operations.js"),
7
+ };
8
+ }
@@ -0,0 +1,5 @@
1
+ import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
2
+ import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
3
+ export declare function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext, sessionRoot?: string | undefined): Set<string>;
4
+ export { captureMutationOwner } from "./mutation-owner.js";
5
+ export declare function backupLocal(profile: string, options?: SnapshotOptions, signal?: AbortSignal): Promise<string>;
@@ -0,0 +1,40 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { sessionDirFromContext } from "../snapshot/session-paths.js";
4
+ import { createSnapshot, sessionSnapshotPathFromAbsolute } from "../snapshot/snapshot.js";
5
+ import { encodeSnapshot } from "../snapshot/snapshot-codec.js";
6
+ import { syncDirectory } from "../state/json-file.js";
7
+ import { stateDir } from "../state/state-directory.js";
8
+ import { throwIfAborted } from "./signals.js";
9
+ export function protectedSessionPaths(ctx, sessionRoot = sessionDirFromContext(ctx)) {
10
+ const sessions = [...(ctx.protectedSessionFiles ?? [])];
11
+ const current = ctx.sessionManager.getSessionFile?.();
12
+ if (current)
13
+ sessions.push(current);
14
+ return new Set(sessions.flatMap((file) => {
15
+ const relative = sessionSnapshotPathFromAbsolute(file, sessionRoot);
16
+ return relative ? [relative] : [];
17
+ }));
18
+ }
19
+ export { captureMutationOwner } from "./mutation-owner.js";
20
+ export async function backupLocal(profile, options = {}, signal) {
21
+ throwIfAborted(signal);
22
+ const snapshot = await createSnapshot(profile, { ...options, signal });
23
+ throwIfAborted(signal);
24
+ const backupDirectory = path.join(stateDir(), "backups");
25
+ await fs.mkdir(backupDirectory, { recursive: true, mode: 0o700 });
26
+ throwIfAborted(signal);
27
+ const backupPath = path.join(backupDirectory, `${snapshot.id}.json.gz`);
28
+ const encoded = await encodeSnapshot(snapshot);
29
+ throwIfAborted(signal);
30
+ const handle = await fs.open(backupPath, "wx", 0o600);
31
+ try {
32
+ await handle.writeFile(encoded);
33
+ await handle.sync();
34
+ }
35
+ finally {
36
+ await handle.close();
37
+ }
38
+ await syncDirectory(backupDirectory);
39
+ return backupPath;
40
+ }
@@ -0,0 +1,30 @@
1
+ import { type SyncBackendFactory } from "../backends/backend-factory.js";
2
+ import { type RemoteHead, type SyncBackend } from "../backends/sync-backend.js";
3
+ import type { CommandOptions } from "../commands/command-types.js";
4
+ import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
5
+ import type { AnySyncConfig } from "../settings/settings-types.js";
6
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
7
+ import type { SyncState } from "../state/state-types.js";
8
+ export declare class PublicationStatePersistenceError extends Error {
9
+ readonly head: RemoteHead;
10
+ readonly backupPath?: string;
11
+ constructor(head: RemoteHead, cause: unknown, backupPath?: string);
12
+ }
13
+ export declare class RollbackPublicationError extends Error {
14
+ readonly backupPath: string;
15
+ constructor(backupPath: string, cause: unknown);
16
+ }
17
+ interface PushInput {
18
+ config: AnySyncConfig;
19
+ state: SyncState;
20
+ local: Snapshot;
21
+ backend?: SyncBackend;
22
+ }
23
+ export declare function push(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, input?: PushInput, factory?: SyncBackendFactory): Promise<"applied" | "cancelled" | undefined>;
24
+ export declare function pull(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "cancelled">;
25
+ export declare function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions, factory?: SyncBackendFactory): Promise<"applied" | "cancelled" | undefined>;
26
+ export declare function rollback(ctx: ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, expectedSelection?: {
27
+ backendIdentity: string;
28
+ setup?: string;
29
+ }): Promise<void>;
30
+ export { backupLocal } from "./sync-local.js";