@narumitw/pi-sync-daemon 0.7.0 → 0.9.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 (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -1,13 +1,14 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { regenerateSnapshotIdentity } from "../snapshot/snapshot.js";
3
3
  import { assertAgentDirectorySnapshotBound } from "../snapshot/snapshot-bounds.js";
4
+ import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion, } from "../snapshot/snapshot-types.js";
4
5
  import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
5
6
  import { normalizeLocalFields } from "./local-field-policy.js";
6
7
  import { compileSyncPolicyExclude, configuredSnapshotPathMatcher, validateSnapshotSelection } from "./sync-policy.js";
7
8
  export { normalizeLocalFields } from "./local-field-policy.js";
8
9
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
9
10
  export function validateSnapshotFieldPolicy(snapshot) {
10
- if (![1, 2, 3, 4, 5].includes(snapshot.version))
11
+ if (!isSupportedSnapshotVersion(snapshot.version))
11
12
  throw new Error("Unsupported snapshot format.");
12
13
  if (snapshot.version === 1 && snapshot.localFields !== undefined)
13
14
  throw new Error("Portable field policy requires snapshot version 2.");
@@ -17,16 +18,76 @@ export function validateSnapshotFieldPolicy(snapshot) {
17
18
  normalizeLocalFields(snapshot.localFields);
18
19
  }
19
20
  }
21
+ export function validateIgnoreSnapshotSessionFlag(selection, syncSessions) {
22
+ if ((syncSessions !== undefined && typeof syncSessions !== "boolean") ||
23
+ (syncSessions === true && !selection.sessions))
24
+ throw new Error("Invalid ignore snapshot session metadata.");
25
+ }
26
+ export function validateIgnoreSnapshotIdentity({ id, createdAt, machine, profile, }) {
27
+ if (typeof id !== "string" ||
28
+ id.length > 512 ||
29
+ id === "." ||
30
+ id === ".." ||
31
+ !/^[A-Za-z0-9._-]+(?![\s\S])/u.test(id) ||
32
+ typeof createdAt !== "string" ||
33
+ createdAt.length > 64 ||
34
+ /[\p{Cc}\p{Cs}]/u.test(createdAt) ||
35
+ Number.isNaN(Date.parse(createdAt)) ||
36
+ typeof machine !== "string" ||
37
+ machine.length > 256 ||
38
+ /[\p{Cc}\p{Cs}]/u.test(machine) ||
39
+ typeof profile !== "string" ||
40
+ !profile ||
41
+ profile.length > 256 ||
42
+ /[\p{Cc}\p{Cs}]/u.test(profile))
43
+ throw new Error("Invalid ignore snapshot identity.");
44
+ }
45
+ function validateIgnoreSnapshotEnvelope(snapshot, selection) {
46
+ validateIgnoreSnapshotIdentity(snapshot);
47
+ validateIgnoreSnapshotSessionFlag(selection, snapshot.syncSessions);
48
+ if (!Array.isArray(snapshot.files) ||
49
+ Object.keys(snapshot).some((key) => ![
50
+ "version",
51
+ "id",
52
+ "createdAt",
53
+ "machine",
54
+ "profile",
55
+ "syncSessions",
56
+ "selection",
57
+ "localFields",
58
+ "files",
59
+ ].includes(key)))
60
+ throw new Error("Invalid ignore snapshot payload.");
61
+ }
62
+ function validateIgnoreSnapshotFiles(files) {
63
+ for (const file of files) {
64
+ if (Object.keys(file).length !== 3 ||
65
+ !Object.hasOwn(file, "path") ||
66
+ !Object.hasOwn(file, "contentBase64") ||
67
+ !Object.hasOwn(file, "sha256") ||
68
+ typeof file.sha256 !== "string" ||
69
+ file.sha256.length !== 64)
70
+ throw new Error("Invalid ignore snapshot file.");
71
+ const content = Buffer.from(file.contentBase64, "base64");
72
+ if (content.toString("base64") !== file.contentBase64 ||
73
+ createHash("sha256").update(content).digest("hex") !== file.sha256)
74
+ throw new Error("Ignore snapshot file checksum or encoding mismatch.");
75
+ }
76
+ }
20
77
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
21
78
  export function validatePortableSnapshot(snapshot) {
22
79
  validateSnapshotFieldPolicy(snapshot);
23
80
  validateSnapshotSelection(snapshot);
24
81
  const selection = snapshot.selection;
82
+ if (selection?.version === 4)
83
+ validateIgnoreSnapshotEnvelope(snapshot, selection);
25
84
  if (selection?.scope) {
26
85
  const selected = configuredSnapshotPathMatcher(selection);
27
86
  if (snapshot.files.some((file) => typeof file?.path !== "string" || !selected(file.path)))
28
87
  throw new Error("Portable snapshot retains excluded or unsafe agent-directory paths.");
29
88
  assertAgentDirectorySnapshotBound(snapshot.files);
89
+ if (snapshot.version === IGNORE_SNAPSHOT_VERSION)
90
+ validateIgnoreSnapshotFiles(snapshot.files);
30
91
  }
31
92
  else {
32
93
  const excludedPath = compileSyncPolicyExclude(selection ?? {});
@@ -0,0 +1,8 @@
1
+ import type { RemoteHead } from "../backends/sync-backend.js";
2
+ import type { AnySyncConfig } from "../settings/settings-types.js";
3
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
4
+ import type { SyncState } from "../state/state-types.js";
5
+ import { type PartialProgress } from "./partial-progress.js";
6
+ export declare function matchesAcceptedState(state: SyncState, config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, progress?: PartialProgress): boolean;
7
+ export declare function acceptedState(config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, progress?: PartialProgress, canonical?: boolean): SyncState;
8
+ export declare function writeAcceptedState(config: AnySyncConfig, head: RemoteHead, snapshot: Snapshot, validate: () => Promise<void>, progress?: PartialProgress): Promise<void>;
@@ -0,0 +1,29 @@
1
+ import { stageMergeBaseline } from "../state/merge-baseline-store.js";
2
+ import { syncStateFingerprint, writeStateForConfig } from "../state/sync-state-store.js";
3
+ import { portableSnapshot } from "./local-fields.js";
4
+ import { progressState } from "./partial-progress.js";
5
+ import { acceptedSelection, fileHashMap } from "./sync-state.js";
6
+ export function matchesAcceptedState(state, config, head, snapshot, progress) {
7
+ return [true, false].some((canonical) => syncStateFingerprint(state) === syncStateFingerprint(acceptedState(config, head, snapshot, progress, canonical)));
8
+ }
9
+ export function acceptedState(config, head, snapshot, progress, canonical = true) {
10
+ if (progress)
11
+ return progressState(config, head, snapshot, progress);
12
+ return {
13
+ version: 1,
14
+ profile: config.snapshotIdentity,
15
+ lastAppliedSnapshot: head.snapshotId,
16
+ lastRemoteRevision: head.revision,
17
+ lastFileHashes: fileHashMap(canonical ? portableSnapshot(snapshot, config.localFields) : snapshot),
18
+ ...acceptedSelection(config),
19
+ ...(config.localFields !== undefined ? { localFields: config.localFields } : {}),
20
+ };
21
+ }
22
+ export async function writeAcceptedState(config, head, snapshot, validate, progress) {
23
+ const accepted = portableSnapshot(snapshot, config.localFields);
24
+ const state = acceptedState(config, head, accepted, progress);
25
+ await stageMergeBaseline(config, accepted, state, progress?.previous);
26
+ await validate();
27
+ await writeStateForConfig(config, state);
28
+ await validate();
29
+ }
@@ -12,6 +12,8 @@ import { assertUnexcludedTargets } from "../snapshot/snapshot-exclude-safety.js"
12
12
  import { assertCanonicalMutationTargets } from "../snapshot/snapshot-mutation-queues.js";
13
13
  import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
14
14
  import { snapshotBase64Size } from "../snapshot/snapshot-payload.js";
15
+ import { recheckScopedImage, scopedTransactionImage } from "../snapshot/snapshot-transaction-images.js";
16
+ import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
15
17
  import { syncDirectory } from "../state/json-file.js";
16
18
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
17
19
  import { mergePathIdentity } from "./file-merge-planner.js";
@@ -251,11 +253,12 @@ async function assertFilesystemTarget(root, relative, options, removedTargets =
251
253
  }
252
254
  /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
253
255
  export async function applyMergedSnapshot(before, after, protectedPaths, options, validate, protectedTarget) {
256
+ const validateIgnore = ignorePolicyValidator(options);
254
257
  const root = agentDir();
255
258
  if (options.scope === "agent-directory" && options.sessionDir === undefined) {
256
259
  options = {
257
260
  ...options,
258
- sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root)),
261
+ sessionDir: sessionStorageRoot(root, await agentDirectoryConfiguredSessionDir(options.signal, root, options)),
259
262
  };
260
263
  options.validateMutation?.();
261
264
  options.signal?.throwIfAborted();
@@ -279,8 +282,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
279
282
  const targetSet = new Set(targets);
280
283
  await assertDistinctMergedTargets(root, paths, new Set(changed), options, protectedTarget, new Set(Object.keys(afterHashes)));
281
284
  await assertCanonicalMutationTargets(targets, options);
282
- if (options.scope === "agent-directory")
283
- await assertUnexcludedTargets(root, targets, options);
285
+ await assertUnexcludedTargets(root, targets, options);
284
286
  // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
285
287
  // missing destination separately only after deleting its reviewed preimage.
286
288
  const targetsByQueue = new Map();
@@ -312,6 +314,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
312
314
  if (target)
313
315
  return withFileMutationQueue(target, () => acquire(index + 1));
314
316
  await validate();
317
+ if (validateIgnore)
318
+ await validateIgnore();
315
319
  await assertCanonicalMergedTargets(root, changed, options);
316
320
  await validate();
317
321
  const current = await createSnapshot(before.profile, options);
@@ -378,21 +382,38 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
378
382
  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
379
383
  await assertCanonicalMergedTargets(root, changed, options);
380
384
  await validate();
385
+ if (options.validateApplyReview)
386
+ await options.validateApplyReview();
387
+ const requireReviewedHash = (relative, hash) => {
388
+ if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
389
+ throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
390
+ };
381
391
  const revalidateTarget = async (target) => {
382
392
  await validate();
383
393
  const relative = relativeByTarget.get(target);
384
394
  if (!relative)
385
395
  throw new Error("Unowned merge target.");
386
- if (options.scope === "agent-directory") {
396
+ if (validateIgnore || options.scope === "agent-directory") {
387
397
  await assertCanonicalMutationTargets([target], options);
388
398
  await assertUnexcludedTargets(root, [target], options);
389
399
  }
390
400
  await assertFilesystemTarget(root, relative, options, removedTargets, currentHashes);
401
+ if (validateIgnore) {
402
+ const image = await scopedTransactionImage(target, options);
403
+ if (image.kind === "directory" && (!removed.has(relative) || image.children.length))
404
+ throw new Error("Reviewed directory has remaining contents; journal retained for review.");
405
+ requireReviewedHash(relative, image.kind === "file" ? image.value.slice("file:".length) : undefined);
406
+ await validateIgnore();
407
+ await recheckScopedImage(target, image, options);
408
+ return image.kind;
409
+ }
391
410
  await validate();
411
+ let kind = "missing";
392
412
  let hash;
393
413
  try {
394
414
  const stat = await fs.lstat(target);
395
415
  if (stat.isDirectory() && removed.has(relative)) {
416
+ kind = "directory";
396
417
  if ((await fs.readdir(target)).length)
397
418
  throw new Error("Reviewed directory has remaining contents; journal retained for review.");
398
419
  }
@@ -400,6 +421,7 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
400
421
  if (!stat.isFile() || stat.nlink > 1)
401
422
  throw new Error("Merged transfer target is no longer an independent regular file.");
402
423
  hash = await hashReviewedFile(target, stat, options);
424
+ kind = "file";
403
425
  }
404
426
  }
405
427
  catch (error) {
@@ -408,19 +430,22 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
408
430
  }
409
431
  options.signal?.throwIfAborted();
410
432
  options.validateMutation?.();
411
- if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
412
- throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
433
+ requireReviewedHash(relative, hash);
434
+ return kind;
413
435
  };
414
436
  if (options.scope === "agent-directory" && plan.deletes.length)
415
437
  await recheckAgentDirectoryBudget(root, plan, options);
416
438
  for (const target of plan.deletes) {
417
- await revalidateTarget(target);
439
+ let kind = await revalidateTarget(target);
418
440
  try {
419
- const stat = await fs.lstat(target);
420
- await validate();
421
- if (stat.isDirectory())
441
+ if (!validateIgnore) {
442
+ const stat = await fs.lstat(target);
443
+ await validate();
444
+ kind = stat.isDirectory() ? "directory" : "file";
445
+ }
446
+ if (kind === "directory")
422
447
  await fs.rmdir(target); // Only an empty, reviewed directory may be replaced.
423
- else
448
+ else if (kind === "file")
424
449
  await fs.rm(target, { force: true });
425
450
  }
426
451
  catch (error) {
@@ -451,6 +476,10 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
451
476
  // Writers registered after deletion must finish first; never accept their
452
477
  // bytes as our own, even if they match a recognizable pre/postimage.
453
478
  await requireAbsentDestinations();
479
+ if (deferredTargets.length && options.validateApplyReview)
480
+ await options.validateApplyReview();
481
+ if (validateIgnore)
482
+ await validateIgnore();
454
483
  await writeTargets();
455
484
  }
456
485
  await requireAbsentDestinations();
@@ -465,6 +494,8 @@ export async function applyMergedSnapshot(before, after, protectedPaths, options
465
494
  const relative = relativeByTarget.get(item.target);
466
495
  if (!relative)
467
496
  throw new Error("Unowned merge write target.");
497
+ if (validateIgnore)
498
+ await validateIgnore();
468
499
  await assertFilesystemTarget(root, relative, options, new Set());
469
500
  await fs.mkdir(path.dirname(item.target), { recursive: true });
470
501
  const temporary = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
@@ -1,9 +1,24 @@
1
- import type { RemoteHead } from "../backends/sync-backend.js";
1
+ import type { RemoteHead, SyncBackend } from "../backends/sync-backend.js";
2
+ import type { CommandOptions } from "../commands/command-types.js";
3
+ import type { EngineContext } from "../host.js";
2
4
  import type { AnySyncConfig } from "../settings/settings-types.js";
3
- import type { Snapshot } from "../snapshot/snapshot-types.js";
5
+ import { type TransactionJournalPolicy } from "../snapshot/snapshot-transaction-policy.js";
6
+ import { type Snapshot } from "../snapshot/snapshot-types.js";
4
7
  import type { PartialProgress } from "./partial-progress.js";
5
- export interface MergeJournal {
8
+ type MergeJournalPolicy = {
6
9
  version: 1;
10
+ ignoreSource?: never;
11
+ localPolicyKey?: never;
12
+ } | {
13
+ version: 2;
14
+ ignoreSource: NonNullable<TransactionJournalPolicy["ignoreSource"]>;
15
+ localPolicyKey?: never;
16
+ } | {
17
+ version: 3;
18
+ ignoreSource?: TransactionJournalPolicy["ignoreSource"];
19
+ localPolicyKey: string;
20
+ };
21
+ export type MergeJournal = MergeJournalPolicy & {
7
22
  identity: string;
8
23
  before: Snapshot;
9
24
  after: Snapshot;
@@ -19,13 +34,18 @@ export interface MergeJournal {
19
34
  /** Effective collection/apply root; absent legacy evidence cannot authorize session recovery. */
20
35
  sessionRoot?: string;
21
36
  warnings?: string[];
22
- }
37
+ };
38
+ export declare function mergeJournalPolicy(config: AnySyncConfig): MergeJournalPolicy;
39
+ export declare function assertMergeJournalPolicy(journal: MergeJournal, config: AnySyncConfig): void;
23
40
  export declare function mergeJournalIdentity(config: AnySyncConfig, backendIdentity: string): string;
24
41
  export declare function mergeJournalPath(config: AnySyncConfig): string;
25
42
  export declare function readMergeJournal(config: AnySyncConfig): Promise<MergeJournal | undefined>;
26
43
  export declare function writeMergeJournal(config: AnySyncConfig, journal: MergeJournal): Promise<void>;
27
44
  export declare function clearMergeJournal(config: AnySyncConfig): Promise<void>;
28
45
  export declare function retireMergeJournal(config: AnySyncConfig): Promise<void>;
46
+ export declare function reviewInactiveIgnoreMerge(ctx: EngineContext, config: AnySyncConfig, backend: SyncBackend, journal: MergeJournal, head: RemoteHead, options: CommandOptions, validateFresh: () => Promise<void>, isCurrent?: () => boolean): Promise<"archived" | "cancelled">;
47
+ export declare function sameMergeRecoveryHead(backend: SyncBackend, left: RemoteHead | undefined, right: RemoteHead | undefined): boolean;
29
48
  export declare function requireNoMergeJournal(config: AnySyncConfig, options?: {
30
49
  force?: boolean;
31
50
  }): Promise<void>;
51
+ export {};
@@ -1,14 +1,65 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
+ import { assertRecoveryPolicy, BOUND_DIRECTORY_JOURNAL_VERSION, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, recoveryPolicyKey, validateJournalPolicy, } from "../snapshot/snapshot-transaction-policy.js";
5
+ import { IGNORE_SNAPSHOT_VERSION } from "../snapshot/snapshot-types.js";
4
6
  import { readJsonIfExists, syncDirectory, writeJson } from "../state/json-file.js";
5
- import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
7
+ import { readStateForConfig, statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
8
+ import { confirmMergeReview } from "../ui/merge-review.js";
9
+ import { safeTerminalText } from "../ui/terminal-text.js";
6
10
  import { normalizeSyncExclude } from "./exclude-policy.js";
7
11
  import { planFileMerge } from "./file-merge-planner.js";
8
12
  import { portableSnapshot, sameLocalFields, validatePortableSnapshot, validateSnapshotFieldPolicy, } from "./local-fields.js";
9
- import { configuredSnapshotPathMatcher, syncDirectoryPolicyKey, validateSnapshotSelection } from "./sync-policy.js";
13
+ import { compileSyncPolicyExclude, configuredSnapshotPathMatcher, sameSnapshotSelection, syncDirectoryPolicyKey, validateSnapshotSelection, } from "./sync-policy.js";
10
14
  import { fileHashMap, sameHashes } from "./sync-state.js";
15
+ export function mergeJournalPolicy(config) {
16
+ const localPolicyKey = recoveryPolicyKey(config);
17
+ const ignoreSource = config.ignorePolicy ? ignoreSourceBinding(config.ignorePolicy) : undefined;
18
+ if (localPolicyKey)
19
+ return { version: 3, localPolicyKey, ...(ignoreSource ? { ignoreSource } : {}) };
20
+ return ignoreSource ? { version: 2, ignoreSource } : { version: 1 };
21
+ }
22
+ function ignoreRecoveryPolicy(journal) {
23
+ return {
24
+ version: journal.version === 3 ? BOUND_DIRECTORY_JOURNAL_VERSION : IGNORE_POLICY_JOURNAL_VERSION,
25
+ ignoreSource: journal.ignoreSource,
26
+ localPolicyKey: journal.localPolicyKey,
27
+ selection: journal.upload.selection,
28
+ };
29
+ }
30
+ export function assertMergeJournalPolicy(journal, config) {
31
+ if (journal.localPolicyKey !== recoveryPolicyKey(config))
32
+ throw new Error("Pending merge lacks matching setup or ignore-file policy evidence; preserve its journal for reviewed recovery.");
33
+ if (journal.version === 1 && !config.ignorePolicy && config.pathPolicy !== "ignore-file")
34
+ return;
35
+ if (journal.ignoreSource || config.ignorePolicy || config.pathPolicy === "ignore-file")
36
+ assertRecoveryPolicy(ignoreRecoveryPolicy(journal), config);
37
+ try {
38
+ const identity = JSON.parse(journal.identity);
39
+ if (!Array.isArray(identity) ||
40
+ typeof identity[1] !== "string" ||
41
+ journal.identity !== mergeJournalIdentity(config, identity[1]))
42
+ throw new Error("Inconsistent merge identity.");
43
+ }
44
+ catch {
45
+ throw new Error("Pending merge belongs to a different setup or local policy; preserve its journal.");
46
+ }
47
+ const configured = configuredSnapshotPathMatcher(config);
48
+ const excluded = compileSyncPolicyExclude(config);
49
+ if (!journal.applyOnly && journal.upload.files.some((file) => excluded(file.path)))
50
+ throw new Error("Pending publication contains protected paths; preserve its journal.");
51
+ for (const snapshot of [
52
+ journal.before,
53
+ journal.after,
54
+ journal.accepted,
55
+ journal.ignoreSource && !journal.applyOnly ? journal.upload : undefined,
56
+ ]) {
57
+ if (snapshot?.files.some((file) => !configured(file.path)))
58
+ throw new Error("Pending merge contains paths outside the current ignore-file policy; preserve its journal.");
59
+ }
60
+ }
11
61
  export function mergeJournalIdentity(config, backendIdentity) {
62
+ const localPolicyKey = recoveryPolicyKey(config);
12
63
  return JSON.stringify([
13
64
  config.setupName,
14
65
  backendIdentity,
@@ -19,6 +70,7 @@ export function mergeJournalIdentity(config, backendIdentity) {
19
70
  : config.exclude === undefined
20
71
  ? []
21
72
  : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
73
+ ...(localPolicyKey ? [localPolicyKey] : []),
22
74
  ]);
23
75
  }
24
76
  export function mergeJournalPath(config) {
@@ -38,9 +90,15 @@ export async function readMergeJournal(config) {
38
90
  // A JSON parser error may quote sensitive journal contents; do not retain it in a public error.
39
91
  throw new Error("Cannot read the private merge journal; preserve it and review recovery.");
40
92
  }
41
- if (!journal)
93
+ if (journal === undefined)
42
94
  return;
43
- if (journal.version !== 1 ||
95
+ if (!journal ||
96
+ ![1, 2, 3].includes(journal.version) ||
97
+ (journal.version === 1 && journal.ignoreSource !== undefined) ||
98
+ (journal.version === 2 && !journal.ignoreSource) ||
99
+ (journal.version === 3
100
+ ? typeof journal.localPolicyKey !== "string" || !/^[0-9a-f]{64}$/u.test(journal.localPolicyKey)
101
+ : journal.localPolicyKey !== undefined) ||
44
102
  typeof journal.identity !== "string" ||
45
103
  typeof journal.backup !== "string" ||
46
104
  typeof journal.stateIdentity !== "string" ||
@@ -69,6 +127,11 @@ export async function readMergeJournal(config) {
69
127
  throw new Error("Unsupported or damaged merge journal; preserve it and review recovery before syncing.");
70
128
  // Verify every path and byte, including the unmanaged remote files retained for publication.
71
129
  try {
130
+ if (journal.ignoreSource !== undefined) {
131
+ validateJournalPolicy(ignoreRecoveryPolicy(journal));
132
+ if ([journal.expectedHead.selection, journal.committedHead?.selection].some((selection) => selection !== undefined && !sameSnapshotSelection(selection, journal.upload.selection)))
133
+ throw new Error("Inconsistent merge head policy.");
134
+ }
72
135
  const pinnedPaths = new Set(journal.progress?.groups.flatMap((group) => group.paths) ?? []);
73
136
  for (const snapshot of [
74
137
  journal.before,
@@ -78,7 +141,10 @@ export async function readMergeJournal(config) {
78
141
  ]) {
79
142
  validateSnapshotFieldPolicy(snapshot);
80
143
  validateSnapshotSelection(snapshot);
81
- if (![1, 2, 3, 4, 5].includes(snapshot.version) ||
144
+ if ((journal.ignoreSource !== undefined
145
+ ? snapshot.version !== IGNORE_SNAPSHOT_VERSION ||
146
+ !sameSnapshotSelection(snapshot.selection, journal.upload.selection)
147
+ : ![1, 2, 3, 4, 5].includes(snapshot.version)) ||
82
148
  typeof snapshot.id !== "string" ||
83
149
  typeof snapshot.profile !== "string" ||
84
150
  snapshot.files.length > 16_384 ||
@@ -172,17 +238,77 @@ export async function clearMergeJournal(config) {
172
238
  await syncDirectory(path.dirname(mergeJournalPath(config)));
173
239
  }
174
240
  export async function retireMergeJournal(config) {
175
- if (!(await readMergeJournal(config)))
241
+ const journal = await readMergeJournal(config);
242
+ if (!journal)
176
243
  return;
244
+ assertMergeJournalPolicy(journal, config);
245
+ const validateIgnore = ignorePolicyValidator(config);
246
+ if (validateIgnore)
247
+ await validateIgnore();
248
+ if (journal.ignoreSource)
249
+ throw new Error(ignoreMergeRecoveryGuidance);
250
+ await archiveMergeJournal(config);
251
+ }
252
+ async function archiveMergeJournal(config) {
177
253
  const file = mergeJournalPath(config);
178
254
  await fs.rename(file, `${file}.${randomUUID()}.resolved`);
179
255
  await syncDirectory(path.dirname(file));
180
256
  }
257
+ export async function reviewInactiveIgnoreMerge(ctx, config, backend, journal, head, options, validateFresh, isCurrent) {
258
+ if (!isCurrent ||
259
+ options.auto ||
260
+ options.background ||
261
+ options.agentAcceptance ||
262
+ options.yes ||
263
+ !ctx.hasUI ||
264
+ (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
265
+ throw new Error(ignoreMergeRecoveryGuidance);
266
+ }
267
+ await validateFresh();
268
+ if (!(await confirmMergeReview(ctx, "Archive the inactive merge journal?", [
269
+ `Setup: ${safeTerminalText(config.setupName)}`,
270
+ "The original remote head and accepted baseline still match the journal, but local files changed.",
271
+ "Archive only the journal. Keep its backup and all current local and remote files. Do not change the baseline.",
272
+ "Run Sync now again to review a fresh plan.",
273
+ ].join("\n"), options.signal, isCurrent, "archive journal only")))
274
+ return "cancelled";
275
+ const state = await readStateForConfig(config);
276
+ await validateFresh();
277
+ const latest = await backend.readHead(options.signal);
278
+ if (!isCurrent())
279
+ return "cancelled";
280
+ await validateFresh();
281
+ if (!sameMergeRecoveryHead(backend, head, latest) ||
282
+ syncStateFingerprint(state) !== journal.stateIdentity ||
283
+ syncStateFingerprint(await readStateForConfig(config)) !== journal.stateIdentity) {
284
+ throw new Error("Remote head or sync baseline changed during recovery review; journal and backup retained.");
285
+ }
286
+ await validateFresh();
287
+ await archiveMergeJournal(config);
288
+ if (!options.silent && isCurrent())
289
+ ctx.ui.notify("Archived the inactive merge journal. Local files, remote files, baseline and backup were kept. Run Sync now again for a fresh plan.", "info");
290
+ return "archived";
291
+ }
292
+ export function sameMergeRecoveryHead(backend, left, right) {
293
+ if (!left || !right)
294
+ return left === right;
295
+ return (backend.sameRevision(left.revision, right.revision) &&
296
+ left.snapshotId === right.snapshotId &&
297
+ left.snapshotRef === right.snapshotRef &&
298
+ sameSnapshotSelection(left.selection, right.selection));
299
+ }
300
+ const ignoreMergeRecoveryGuidance = "An ignore-file merged transfer needs recovery; directional --force cannot bypass it. Inactive journal archiving requires foreground review where supported; --yes does not approve it. Preserve the journal, backup and current files if recovery is unavailable. Do not downgrade or restore old bytes blindly.";
181
301
  export async function requireNoMergeJournal(config, options = {}) {
182
302
  const journal = await readMergeJournal(config);
183
- if (options.force || !journal)
303
+ if (!journal)
184
304
  return;
185
- if (journal) {
305
+ assertMergeJournalPolicy(journal, config);
306
+ const validateIgnore = ignorePolicyValidator(config);
307
+ if (validateIgnore)
308
+ await validateIgnore();
309
+ if (journal.ignoreSource)
310
+ throw new Error(ignoreMergeRecoveryGuidance);
311
+ if (!options.force) {
186
312
  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.");
187
313
  }
188
314
  }
@@ -3,4 +3,4 @@ import type { CommandOptions } from "../commands/command-types.js";
3
3
  import type { EngineContext as ExtensionCommandContext, EngineContext as ExtensionContext } from "../host.js";
4
4
  import { type ConflictResolution } from "./conflict-resolution.js";
5
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>;
6
+ export declare function mergeSync(ctx: ExtensionContext | ExtensionCommandContext, options: CommandOptions, factory?: SyncBackendFactory, resolution?: ConflictResolution): Promise<"applied" | "archived" | "cancelled" | undefined>;