@narumitw/pi-sync-daemon 0.0.0-stage → 0.2.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 (265) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +21 -0
  3. package/README.md +89 -2
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +128 -0
  6. package/dist/client.d.ts +55 -0
  7. package/dist/client.js +484 -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 +11 -0
  241. package/dist/engine-service.js +315 -0
  242. package/dist/identity.d.ts +20 -0
  243. package/dist/identity.js +133 -0
  244. package/dist/index.d.ts +8 -0
  245. package/dist/index.js +4 -0
  246. package/dist/lifecycle-log.d.ts +7 -0
  247. package/dist/lifecycle-log.js +53 -0
  248. package/dist/lifecycle.d.ts +2 -0
  249. package/dist/lifecycle.js +21 -0
  250. package/dist/model-signature.d.ts +2 -0
  251. package/dist/model-signature.js +7 -0
  252. package/dist/monitor.d.ts +11 -0
  253. package/dist/monitor.js +245 -0
  254. package/dist/participant-admission.d.ts +5 -0
  255. package/dist/participant-admission.js +30 -0
  256. package/dist/protocol.d.ts +97 -0
  257. package/dist/protocol.js +90 -0
  258. package/dist/resolver-host.d.ts +11 -0
  259. package/dist/resolver-host.js +78 -0
  260. package/dist/server.d.ts +18 -0
  261. package/dist/server.js +724 -0
  262. package/dist/service-host.d.ts +7 -0
  263. package/dist/service-host.js +174 -0
  264. package/docs/architecture.md +133 -0
  265. package/package.json +54 -4
@@ -0,0 +1,179 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { readJsonIfExists, syncDirectory, writeJson } from "../state/json-file.js";
5
+ import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
6
+ import { normalizeSyncExclude } from "./exclude-policy.js";
7
+ import { planFileMerge } from "./file-merge-planner.js";
8
+ import { portableSnapshot, sameLocalFields, validatePortableSnapshot, validateSnapshotFieldPolicy, } from "./local-fields.js";
9
+ import { fileHashMap, sameHashes } from "./sync-state.js";
10
+ export function mergeJournalIdentity(config, backendIdentity) {
11
+ return JSON.stringify([
12
+ config.setupName,
13
+ backendIdentity,
14
+ [...config.include].sort(),
15
+ config.localFields ?? null,
16
+ ...(config.exclude === undefined
17
+ ? []
18
+ : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
19
+ ]);
20
+ }
21
+ export function mergeJournalPath(config) {
22
+ return `${statePathForConfig(config)}.merge-journal.json`;
23
+ }
24
+ export async function readMergeJournal(config) {
25
+ let journal;
26
+ try {
27
+ const stat = await fs.lstat(mergeJournalPath(config));
28
+ if (!stat.isFile() || stat.size > 384 * 1024 * 1024)
29
+ throw new Error("Unsafe or oversized journal.");
30
+ journal = await readJsonIfExists(mergeJournalPath(config));
31
+ }
32
+ catch (error) {
33
+ if (error.code === "ENOENT")
34
+ return;
35
+ // A JSON parser error may quote sensitive journal contents; do not retain it in a public error.
36
+ throw new Error("Cannot read the private merge journal; preserve it and review recovery.");
37
+ }
38
+ if (!journal)
39
+ return;
40
+ if (journal.version !== 1 ||
41
+ typeof journal.identity !== "string" ||
42
+ typeof journal.backup !== "string" ||
43
+ typeof journal.stateIdentity !== "string" ||
44
+ (journal.applyOnly !== undefined &&
45
+ (journal.applyOnly !== true ||
46
+ !journal.committedHead ||
47
+ journal.committedHead.revision !== journal.expectedHead?.revision ||
48
+ journal.committedHead.snapshotId !== journal.expectedHead?.snapshotId ||
49
+ journal.upload?.id !== journal.expectedHead?.snapshotId)) ||
50
+ (journal.sessionRoot !== undefined &&
51
+ (typeof journal.sessionRoot !== "string" ||
52
+ !path.isAbsolute(journal.sessionRoot) ||
53
+ path.resolve(journal.sessionRoot) !== journal.sessionRoot)) ||
54
+ (journal.warnings !== undefined &&
55
+ (!Array.isArray(journal.warnings) ||
56
+ journal.warnings.length > 64 ||
57
+ journal.warnings.some((item) => typeof item !== "string"))) ||
58
+ !journal.expectedHead ||
59
+ typeof journal.expectedHead.revision !== "string" ||
60
+ !journal.before ||
61
+ !journal.after ||
62
+ !journal.upload ||
63
+ !Array.isArray(journal.before.files) ||
64
+ !Array.isArray(journal.after.files) ||
65
+ !Array.isArray(journal.upload.files))
66
+ throw new Error("Unsupported or damaged merge journal; preserve it and review recovery before syncing.");
67
+ // Verify every path and byte, including the unmanaged remote files retained for publication.
68
+ try {
69
+ const pinnedPaths = new Set(journal.progress?.groups.flatMap((group) => group.paths) ?? []);
70
+ for (const snapshot of [
71
+ journal.before,
72
+ journal.after,
73
+ journal.upload,
74
+ ...(journal.accepted ? [journal.accepted] : []),
75
+ ]) {
76
+ validateSnapshotFieldPolicy(snapshot);
77
+ if ((snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3 && snapshot.version !== 4) ||
78
+ typeof snapshot.id !== "string" ||
79
+ typeof snapshot.profile !== "string" ||
80
+ snapshot.files.length > 16_384 ||
81
+ snapshot.files.reduce((bytes, file) => bytes + (typeof file?.contentBase64 === "string" ? file.contentBase64.length * 0.75 : Infinity), 0) >
82
+ 64 * 1024 * 1024)
83
+ throw new Error("Invalid journal input.");
84
+ const plan = planFileMerge({ baseline: {}, local: snapshot.files, remote: [], selectionCompatible: true });
85
+ if (plan.kind !== "planned" ||
86
+ plan.conflicts.some((conflict) => conflict.reason !== "path-collision" || !pinnedPaths.has(conflict.path)))
87
+ throw new Error("Invalid journal collision group.");
88
+ }
89
+ validatePortableSnapshot(journal.upload);
90
+ if (journal.upload.version >= 2 && !journal.accepted)
91
+ throw new Error("Portable merge journal requires an explicit accepted projection.");
92
+ if (journal.accepted)
93
+ validatePortableSnapshot(journal.accepted);
94
+ }
95
+ catch {
96
+ throw new Error("Invalid merge journal paths, metadata, or bytes; preserve evidence for review.");
97
+ }
98
+ // Integrity is intrinsic to the recorded transaction, not the user's current recovery policy.
99
+ // completeJournal separately checks that the recorded policy matches the current setup.
100
+ try {
101
+ if (journal.accepted &&
102
+ (!sameLocalFields(journal.accepted.localFields, journal.upload.localFields) ||
103
+ !sameHashes(fileHashMap(portableSnapshot(journal.after, journal.upload.localFields)), fileHashMap(portableSnapshot(journal.accepted, journal.upload.localFields)))))
104
+ throw new Error("Projection mismatch.");
105
+ }
106
+ catch {
107
+ throw new Error("Invalid accepted merge projection; preserve journal evidence.");
108
+ }
109
+ if (journal.progress) {
110
+ const known = new Set([
111
+ ...Object.keys(journal.progress.previous?.lastFileHashes ?? {}),
112
+ ...[...journal.before.files, ...journal.after.files, ...journal.upload.files].map((file) => file.path),
113
+ ]);
114
+ const progress = journal.progress;
115
+ if (!config.partialSync ||
116
+ !progress.previous ||
117
+ syncStateFingerprint(progress.previous) !== journal.stateIdentity ||
118
+ !Array.isArray(progress.groups) ||
119
+ progress.groups.length > 16_384 ||
120
+ progress.groups.some((group) => !Array.isArray(group.paths) ||
121
+ !group.paths.length ||
122
+ group.paths.length > 16_384 ||
123
+ group.paths.some((filePath) => !known.has(filePath)) ||
124
+ !/^[a-f0-9-]{36}$/u.test(group.artifact)))
125
+ throw new Error("Invalid partial acceptance metadata; preserve journal evidence.");
126
+ }
127
+ if (journal.progress) {
128
+ const before = fileHashMap(journal.before);
129
+ const after = fileHashMap(journal.after);
130
+ const { readConflictArtifact } = await import("./conflict-artifacts.js");
131
+ const backendIdentity = JSON.parse(journal.identity)[1];
132
+ if (typeof backendIdentity !== "string")
133
+ throw new Error("Invalid partial backend identity.");
134
+ const byArtifact = new Map();
135
+ for (const group of journal.progress.groups) {
136
+ const groups = byArtifact.get(group.artifact) ?? [];
137
+ groups.push(group);
138
+ byArtifact.set(group.artifact, groups);
139
+ }
140
+ for (const [token, groups] of byArtifact) {
141
+ const artifact = await readConflictArtifact(config, backendIdentity, token);
142
+ const retainedGroups = new Set(artifact.groups.map((group) => JSON.stringify(group.paths)));
143
+ const remote = fileHashMap(artifact.remote);
144
+ const upload = fileHashMap(journal.upload);
145
+ for (const group of groups) {
146
+ if (!retainedGroups.has(JSON.stringify(group.paths)))
147
+ throw new Error("Partial group does not match retained artifact evidence.");
148
+ for (const filePath of group.paths)
149
+ if (before[filePath] !== after[filePath] ||
150
+ remote[filePath] !== upload[filePath] ||
151
+ journal.progress.previous.lastFileHashes[filePath] !== artifact.state.lastFileHashes[filePath])
152
+ throw new Error("Withheld version changed in journal; preserve evidence.");
153
+ }
154
+ }
155
+ }
156
+ return journal;
157
+ }
158
+ export async function writeMergeJournal(config, journal) {
159
+ await writeJson(mergeJournalPath(config), journal, { maxBytes: 384 * 1024 * 1024 });
160
+ }
161
+ export async function clearMergeJournal(config) {
162
+ await fs.rm(mergeJournalPath(config), { force: true });
163
+ await syncDirectory(path.dirname(mergeJournalPath(config)));
164
+ }
165
+ export async function retireMergeJournal(config) {
166
+ if (!(await readMergeJournal(config)))
167
+ return;
168
+ const file = mergeJournalPath(config);
169
+ await fs.rename(file, `${file}.${randomUUID()}.resolved`);
170
+ await syncDirectory(path.dirname(file));
171
+ }
172
+ export async function requireNoMergeJournal(config, options = {}) {
173
+ const journal = await readMergeJournal(config);
174
+ if (options.force || !journal)
175
+ return;
176
+ if (journal) {
177
+ throw new Error("A merged transfer needs recovery. Run /sync sync to reconcile it. If newer local edits or remote revisions prevent recovery, review /sync diff and explicitly choose push --force or pull --force; the selected directional result will archive the old journal, not restore old bytes. Keep its backup; do not downgrade while recovery is pending.");
178
+ }
179
+ }
@@ -0,0 +1,3 @@
1
+ import type { ResolvedSyncBackend } from "../backends/backend-types.js";
2
+ /** Only the sanitized message is displayed; retain the original cause for outcome handling. */
3
+ export declare function mergeTransferError(error: unknown, backend: ResolvedSyncBackend): Error;
@@ -0,0 +1,64 @@
1
+ import { safeTerminalText } from "../ui/terminal-text.js";
2
+ const MAX_CAUSES = 4;
3
+ const MAX_DETAIL_LENGTH = 600;
4
+ /** Only the sanitized message is displayed; retain the original cause for outcome handling. */
5
+ export function mergeTransferError(error, backend) {
6
+ const messages = [];
7
+ const seen = new Set();
8
+ let current = error;
9
+ while (current instanceof Error && !seen.has(current) && seen.size < MAX_CAUSES) {
10
+ seen.add(current);
11
+ const code = current.code;
12
+ const status = current.status;
13
+ const metadata = [
14
+ typeof code === "string" && /^[A-Z][A-Z0-9_]{1,63}$/u.test(code) ? code : undefined,
15
+ typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599
16
+ ? `HTTP ${status}`
17
+ : undefined,
18
+ ].filter(Boolean);
19
+ const message = `${current.message}${metadata.length ? ` (${metadata.join(", ")})` : ""}`;
20
+ if (message && !messages.includes(message))
21
+ messages.push(message);
22
+ current = current.cause;
23
+ }
24
+ let detail = messages.join(" → ") || "No error details available.";
25
+ // Redact before truncation or terminal escaping, including overlapping and encoded credentials.
26
+ for (const secret of credentialVariants(backend))
27
+ detail = detail.replaceAll(secret, "[REDACTED]");
28
+ detail = detail.replace(/\b(Bearer|Basic)\s+[^\s<>"']+/giu, "$1 [REDACTED]");
29
+ detail = safeTerminalText(detail);
30
+ if (detail.length > MAX_DETAIL_LENGTH)
31
+ detail = `${detail.slice(0, MAX_DETAIL_LENGTH)}… (details truncated)`;
32
+ return new Error(`Merged transfer interrupted; journal and backup retained. Run /sync sync to reconcile before further mutations. Transfer failure: ${detail}`, { cause: error });
33
+ }
34
+ function credentialVariants(backend) {
35
+ const secrets = [];
36
+ let address;
37
+ switch (backend.type) {
38
+ case "s3":
39
+ secrets.push(backend.profile.accessKeyId, backend.profile.secretAccessKey, backend.profile.sessionToken ?? "");
40
+ address = backend.profile.endpoint;
41
+ break;
42
+ case "webdav":
43
+ secrets.push(backend.profile.username, backend.profile.password, Buffer.from(`${backend.profile.username}:${backend.profile.password}`).toString("base64"));
44
+ address = backend.profile.url;
45
+ break;
46
+ case "git":
47
+ address = backend.profile.remote;
48
+ break;
49
+ }
50
+ try {
51
+ const url = new URL(address);
52
+ secrets.push(url.username, url.password, ...url.searchParams.values());
53
+ for (const value of [url.username, url.password])
54
+ secrets.push(decodeURIComponent(value));
55
+ }
56
+ catch {
57
+ // Git SSH shorthand is not a URL; configured Git remotes cannot contain credentials.
58
+ }
59
+ return [
60
+ ...new Set(secrets
61
+ .filter(Boolean)
62
+ .flatMap((value) => [value, encodeURIComponent(value), JSON.stringify(value).slice(1, -1)])),
63
+ ].sort((left, right) => right.length - left.length);
64
+ }
@@ -0,0 +1,6 @@
1
+ import { type SyncBackendFactory } from "../backends/backend-factory.js";
2
+ import type { CommandOptions } from "../commands/command-types.js";
3
+ import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
4
+ import { type ConflictResolution } from "./conflict-resolution.js";
5
+ /** Established-baseline sync only. First-source selection remains in the existing command flow. */
6
+ export declare function mergeSync(ctx: ExtensionContext | ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, resolution?: ConflictResolution): Promise<"applied" | "cancelled" | undefined>;