@narumitw/pi-sync-daemon 0.7.0 → 0.8.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 (74) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +16 -2
  3. package/dist/consent.js +21 -6
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +30 -9
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/settings/config-file.d.ts +9 -2
  24. package/dist/engine/settings/config-file.js +124 -28
  25. package/dist/engine/settings/config.d.ts +3 -0
  26. package/dist/engine/settings/config.js +93 -7
  27. package/dist/engine/settings/settings-management.d.ts +2 -2
  28. package/dist/engine/settings/settings-management.js +16 -8
  29. package/dist/engine/settings/settings-types.d.ts +23 -2
  30. package/dist/engine/settings/settings-validation.js +23 -5
  31. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  32. package/dist/engine/snapshot/session-paths.js +36 -13
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  34. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  35. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  36. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  37. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  38. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  39. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  40. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  41. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +24 -1
  42. package/dist/engine/snapshot/snapshot-transaction-policy.js +106 -2
  43. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  44. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  46. package/dist/engine/snapshot/snapshot-transaction.js +86 -108
  47. package/dist/engine/snapshot/snapshot-types.d.ts +23 -1
  48. package/dist/engine/snapshot/snapshot-types.js +9 -1
  49. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  50. package/dist/engine/snapshot/snapshot.js +91 -34
  51. package/dist/engine/state/state-types.d.ts +1 -0
  52. package/dist/engine/sync/continuous-sync.js +18 -3
  53. package/dist/engine/sync/continuous-watch.js +4 -1
  54. package/dist/engine/sync/initialization.js +3 -2
  55. package/dist/engine/sync/local-fields.d.ts +3 -1
  56. package/dist/engine/sync/local-fields.js +62 -1
  57. package/dist/engine/sync/merge-apply.js +35 -7
  58. package/dist/engine/sync/merge-journal.d.ts +18 -4
  59. package/dist/engine/sync/merge-journal.js +115 -8
  60. package/dist/engine/sync/merged-sync.d.ts +1 -1
  61. package/dist/engine/sync/merged-sync.js +103 -50
  62. package/dist/engine/sync/remote-snapshot.d.ts +9 -2
  63. package/dist/engine/sync/remote-snapshot.js +56 -17
  64. package/dist/engine/sync/sync-inspection.js +7 -5
  65. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  66. package/dist/engine/sync/sync-mutations.js +110 -47
  67. package/dist/engine/sync/sync-policy.d.ts +24 -8
  68. package/dist/engine/sync/sync-policy.js +127 -16
  69. package/dist/engine/sync/sync-queries.js +8 -1
  70. package/dist/engine/sync/sync-state.d.ts +2 -2
  71. package/dist/engine/sync/sync-state.js +20 -2
  72. package/dist/engine-service.js +24 -2
  73. package/docs/architecture.md +22 -0
  74. package/package.json +2 -1
@@ -2,22 +2,91 @@ import { createHash } from "node:crypto";
2
2
  import { backendIdentityCoordinates } from "../backends/backend-identity.js";
3
3
  import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote } from "../backends/git/git-config.js";
4
4
  import { normalizeWebDavPath, normalizeWebDavUrl } from "../backends/webdav/webdav-config.js";
5
+ import { getEngineRoot } from "../host.js";
6
+ import { loadEffectiveIgnorePolicy } from "../ignore/effective-ignore-policy.js";
7
+ import { DEFAULT_IGNORE_FILENAME, readIgnoreSource, validateIgnoreFilename } from "../ignore/ignore-source.js";
5
8
  import { normalizeSyncExclude } from "../sync/exclude-policy.js";
6
9
  import { normalizeLocalFields } from "../sync/local-field-policy.js";
7
10
  import { normalizeDirectoryRules, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "../sync/sync-policy.js";
8
- import { localConfigPath, readActiveLocalConfigDocumentForRepair } from "./config-file.js";
11
+ import { localConfigPath, readActiveLocalConfigDocumentForRepair, withLockedLocalConfigDocument, } from "./config-file.js";
9
12
  import { requireSettings } from "./settings-store.js";
10
13
  import { DEFAULT_ON_SWITCH, isCloudflareR2Endpoint, normalizeS3Bucket, normalizeS3Endpoint, normalizeStoragePath, optionalString, ownObject, requiredString, validateConfigName, validateSettingsDocument, } from "./settings-validation.js";
11
14
  export async function loadConfig(setupName) {
12
- return configFromSettings(await requireSettings(), setupName);
15
+ return requireLegacyOperationConfig(configFromSettings(await requireSettings(), setupName));
13
16
  }
14
17
  /** A background freshness read must never trigger legacy-file publication. */
15
18
  export async function loadConfigForCheck() {
16
- const document = await readActiveLocalConfigDocumentForRepair();
19
+ return requireLegacyOperationConfig(configFromSettings(await readSettingsForCheck()));
20
+ }
21
+ export async function loadSettingsConfig(setupName) {
22
+ return configFromSettings(await readSettingsForCheck(), setupName);
23
+ }
24
+ async function readSettingsForCheck() {
25
+ return settingsFromCheckDocument(await readActiveLocalConfigDocumentForRepair());
26
+ }
27
+ function settingsFromCheckDocument(document) {
17
28
  if (!document)
18
29
  throw new Error(`Missing pi-sync settings: ${localConfigPath()}`);
19
- validateSettingsDocument(document.parsed);
20
- return configFromSettings(document.parsed);
30
+ return validateSettingsDocument(document.parsed);
31
+ }
32
+ export function requireLegacyOperationConfig(config) {
33
+ if (config.pathPolicy === "ignore-file" || config.ignorePolicy || config.reservedIgnoreNames !== undefined) {
34
+ throw new Error("This Pi Sync operation does not yet support settings with ignore-file policies.");
35
+ }
36
+ return config;
37
+ }
38
+ export async function resolveIgnoreConfig(settings, setupName, signal) {
39
+ signal?.throwIfAborted();
40
+ const config = configFromSettings(validateSettingsDocument(settings), setupName);
41
+ if (config.pathPolicy !== "ignore-file")
42
+ return requireLegacyOperationConfig(config);
43
+ const root = getEngineRoot();
44
+ const validateRoot = () => {
45
+ if (root !== getEngineRoot())
46
+ throw new Error("The Pi agent directory changed; reopen the review before continuing.");
47
+ };
48
+ const settingsFingerprint = syncCheckConfigFingerprint(config);
49
+ const validateSettings = (document) => {
50
+ signal?.throwIfAborted();
51
+ validateRoot();
52
+ const current = configFromSettings(document, setupName);
53
+ if (settingsFingerprint !== syncCheckConfigFingerprint(current)) {
54
+ throw new Error("Pi Sync settings changed; reopen the review before continuing.");
55
+ }
56
+ return current;
57
+ };
58
+ const ignorePolicy = await loadEffectiveIgnorePolicy(root, ignorePolicyInput(config), signal);
59
+ signal?.throwIfAborted();
60
+ validateRoot();
61
+ return {
62
+ ...config,
63
+ ignorePolicy,
64
+ validateIgnorePolicy: async () => {
65
+ signal?.throwIfAborted();
66
+ validateRoot();
67
+ await withLockedLocalConfigDocument(async (document, recheck) => {
68
+ const current = validateSettings(settingsFromCheckDocument(document));
69
+ const source = await readIgnoreSource(root, current.ignoreFile, signal);
70
+ validateRoot();
71
+ recheck();
72
+ if (source.sourceDigest !== ignorePolicy.sourceDigest) {
73
+ throw new Error("Pi Sync ignore policy changed; reopen the review before continuing.");
74
+ }
75
+ if (!source.present) {
76
+ throw new Error(`Ignore file "${source.filename}" is missing; starter rules can only be used for a preview.`);
77
+ }
78
+ }, signal, true);
79
+ signal?.throwIfAborted();
80
+ validateRoot();
81
+ },
82
+ };
83
+ }
84
+ function ignorePolicyInput(config) {
85
+ return {
86
+ filename: config.ignoreFile,
87
+ sessions: config.include.includes("sessions"),
88
+ configuredFilenames: config.reservedIgnoreNames ?? [],
89
+ };
21
90
  }
22
91
  export function configFromSettings(settings, setupName) {
23
92
  const selectedName = setupName ?? settings.activeSyncSetup;
@@ -32,19 +101,28 @@ export function configFromSettings(settings, setupName) {
32
101
  if (!connection) {
33
102
  throw new Error(`Invalid pi-sync settings: sync setup “${selectedName}” references missing storage connection “${connectionName}”.`);
34
103
  }
104
+ const ignoreNames = new Set();
105
+ for (const { sync } of Object.values(settings.syncSetups)) {
106
+ if (sync.pathPolicy === "ignore-file")
107
+ ignoreNames.add(validateIgnoreFilename(sync.ignoreFile ?? DEFAULT_IGNORE_FILENAME).toLowerCase());
108
+ }
109
+ if (ignoreNames.size > 0)
110
+ ignoreNames.add(DEFAULT_IGNORE_FILENAME);
35
111
  return {
36
112
  ...resolveSyncConfig(selectedName, setup, connectionName, connection, settings.onSwitch, settings.skipSecretScan ?? false, settings.showStatus ?? true),
37
113
  debug: settings.debug ?? false,
114
+ ...(ignoreNames.size > 0 ? { reservedIgnoreNames: [...ignoreNames].sort() } : {}),
38
115
  };
39
116
  }
40
117
  /** A validated setup-facing projection used by manager and settings UI. */
41
118
  export async function loadPartialConfig(setupName) {
42
- const config = await loadConfig(setupName);
119
+ const config = configFromSettings(await requireSettings(), setupName);
43
120
  return {
44
121
  setupName: config.setupName,
45
122
  ...storageReviewFromConfig(config),
46
123
  include: [...config.include],
47
124
  ...(config.scope === undefined ? {} : { scope: config.scope }),
125
+ ...(config.pathPolicy === undefined ? {} : { pathPolicy: config.pathPolicy, ignoreFile: config.ignoreFile }),
48
126
  ...(config.exclude === undefined ? {} : { exclude: [...config.exclude] }),
49
127
  ...(config.reinclude === undefined ? {} : { reinclude: [...config.reinclude] }),
50
128
  automatic: config.automatic,
@@ -62,7 +140,9 @@ export function syncSetupReviewIdentity(setupName, setup, connectionName, connec
62
140
  return syncConfigReviewIdentity(resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false, true));
63
141
  }
64
142
  export function syncConfigReviewIdentity(config) {
65
- const directoryPolicy = syncDirectoryPolicyKey(config);
143
+ const directoryPolicy = config.pathPolicy === "ignore-file" && !config.ignorePolicy
144
+ ? JSON.stringify([config.pathPolicy, config.ignoreFile])
145
+ : syncDirectoryPolicyKey(config);
66
146
  return JSON.stringify([
67
147
  config.setupName,
68
148
  config.connectionName,
@@ -113,6 +193,12 @@ function resolveSyncConfig(setupName, setup, connectionName, connection, onSwitc
113
193
  ? {
114
194
  scope: policy.scope,
115
195
  include: policy.sessions ? ["sessions"] : [],
196
+ ...(policy.pathPolicy === "ignore-file"
197
+ ? {
198
+ pathPolicy: policy.pathPolicy,
199
+ ignoreFile: validateIgnoreFilename(policy.ignoreFile ?? DEFAULT_IGNORE_FILENAME),
200
+ }
201
+ : {}),
116
202
  ...(policy.exclude === undefined ? {} : { exclude: normalizeDirectoryRules(policy.exclude) }),
117
203
  ...(policy.reinclude === undefined ? {} : { reinclude: normalizeDirectoryRules(policy.reinclude) }),
118
204
  }
@@ -1,5 +1,5 @@
1
1
  import { type SyncSetupStorageReview } from "./config.js";
2
- import type { StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
2
+ import type { PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./settings-types.js";
3
3
  export declare class SyncSetupReviewChangedError extends Error {
4
4
  constructor(message: string);
5
5
  }
@@ -8,7 +8,7 @@ export declare function saveNewV3Settings(input: {
8
8
  connectionName: string;
9
9
  connection: StorageConnectionSettings;
10
10
  setup: SyncSetupSettings;
11
- }, signal?: AbortSignal): Promise<import("./settings-types.js").PiSyncSettingsV3>;
11
+ }, signal?: AbortSignal): Promise<PiSyncSettingsV3>;
12
12
  export declare function addStorageConnection(name: string, connection: StorageConnectionSettings, signal?: AbortSignal): Promise<void>;
13
13
  export declare function updateStorageConnection(name: string, update: (connection: StorageConnectionSettings) => StorageConnectionSettings, expectedSetups?: readonly string[], signal?: AbortSignal): Promise<void>;
14
14
  export declare function addSyncSetup(name: string, setup: SyncSetupSettings, signal?: AbortSignal, expectedConnection?: StorageConnectionSettings): Promise<void>;
@@ -22,7 +22,7 @@ export async function saveNewV3Settings(input, signal) {
22
22
  }
23
23
  return {
24
24
  ...current,
25
- version: setup.sync.scope === "agent-directory" ? 7 : current.version,
25
+ version: setupSettingsVersion(current.version, setup),
26
26
  activeSyncSetup: setupName,
27
27
  storageConnections: { [connectionName]: connection },
28
28
  syncSetups: { [setupName]: setup },
@@ -76,7 +76,7 @@ export async function addSyncSetup(name, setup, signal, expectedConnection) {
76
76
  assertUniqueLocations(nextSetups, settings.storageConnections);
77
77
  return {
78
78
  ...settings,
79
- version: setup.sync.scope === "agent-directory" ? 7 : settings.version,
79
+ version: setupSettingsVersion(settings.version, setup),
80
80
  syncSetups: nextSetups,
81
81
  ...(settings.activeSyncSetup ? {} : { activeSyncSetup: name }),
82
82
  };
@@ -113,12 +113,11 @@ export async function updateSyncSetup(name, update, options = {}) {
113
113
  }
114
114
  const nextSetups = { ...settings.syncSetups, [name]: nextSetup };
115
115
  assertUniqueLocations(nextSetups, settings.storageConnections);
116
- const version = nextSetup.sync.scope === "agent-directory"
117
- ? 7
118
- : options.upgradeExclude && settings.version < 6
119
- ? 6
120
- : settings.version;
121
- return { ...settings, version, syncSetups: nextSetups };
116
+ return {
117
+ ...settings,
118
+ version: setupSettingsVersion(settings.version, nextSetup, options.upgradeExclude),
119
+ syncSetups: nextSetups,
120
+ };
122
121
  }, options.signal);
123
122
  }
124
123
  export async function removeSyncSetup(name, signal) {
@@ -153,6 +152,15 @@ export async function removeStorageConnection(name, signal) {
153
152
  return { ...settings, storageConnections };
154
153
  }, signal);
155
154
  }
155
+ function setupSettingsVersion(current, setup, upgradeExclude) {
156
+ if (setup.sync.pathPolicy === "ignore-file")
157
+ return 8;
158
+ if (current < 7 && setup.sync.scope === "agent-directory")
159
+ return 7;
160
+ if (current < 6 && upgradeExclude)
161
+ return 6;
162
+ return current;
163
+ }
156
164
  function referencingSetupNames(setups, connection) {
157
165
  return Object.entries(setups)
158
166
  .filter(([, setup]) => setup.storage.connection === connection)
@@ -1,4 +1,5 @@
1
1
  import type { ResolvedS3Backend, ResolvedSyncBackend } from "../backends/backend-types.js";
2
+ import type { EffectiveIgnorePolicy, SnapshotOptions } from "../snapshot/snapshot-types.js";
2
3
  export type StorageConnectionType = "s3" | "git" | "webdav";
3
4
  export type OnSwitchAction = "ask-before-pull" | "pull-after-switch" | "switch-only";
4
5
  export interface S3CredentialsSettings {
@@ -59,7 +60,6 @@ export interface WebDavSyncSetupStorageSettings extends CommonSyncSetupStorageSe
59
60
  }
60
61
  export type SyncSetupStorageSettings = S3SyncSetupStorageSettings | GitSyncSetupStorageSettings | WebDavSyncSetupStorageSettings;
61
62
  interface CommonSyncPolicySettings {
62
- exclude?: string[];
63
63
  automatic: boolean;
64
64
  /** Explicit opt-in, separate from the legacy observe/shutdown policy. */
65
65
  automaticTransfer?: boolean;
@@ -76,14 +76,28 @@ interface CommonSyncPolicySettings {
76
76
  }
77
77
  export type SyncPolicySettings = CommonSyncPolicySettings & ({
78
78
  scope?: never;
79
+ pathPolicy?: never;
80
+ ignoreFile?: never;
79
81
  include: string[];
82
+ exclude?: string[];
80
83
  reinclude?: never;
81
84
  sessions?: never;
82
85
  } | {
83
86
  scope: "agent-directory";
87
+ pathPolicy?: never;
88
+ ignoreFile?: never;
84
89
  include?: never;
90
+ exclude?: string[];
85
91
  reinclude?: string[];
86
92
  sessions?: boolean;
93
+ } | {
94
+ scope: "agent-directory";
95
+ pathPolicy: "ignore-file";
96
+ ignoreFile?: string;
97
+ include?: never;
98
+ exclude?: never;
99
+ reinclude?: never;
100
+ sessions?: boolean;
87
101
  });
88
102
  export interface SyncSetupSettings {
89
103
  storage: SyncSetupStorageSettings;
@@ -91,7 +105,7 @@ export interface SyncSetupSettings {
91
105
  [key: string]: unknown;
92
106
  }
93
107
  export interface PiSyncSettingsV3 {
94
- version: 3 | 4 | 5 | 6 | 7;
108
+ version: 3 | 4 | 5 | 6 | 7 | 8;
95
109
  activeSyncSetup?: string;
96
110
  onSwitch: OnSwitchAction;
97
111
  skipSecretScan?: boolean;
@@ -109,6 +123,11 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
109
123
  snapshotIdentity: string;
110
124
  include: string[];
111
125
  scope?: "agent-directory";
126
+ pathPolicy?: "ignore-file";
127
+ ignoreFile?: string;
128
+ reservedIgnoreNames?: readonly string[];
129
+ ignorePolicy?: EffectiveIgnorePolicy;
130
+ validateIgnorePolicy?: SnapshotOptions["validateIgnorePolicy"];
112
131
  exclude?: string[];
113
132
  reinclude?: string[];
114
133
  automatic: boolean;
@@ -134,6 +153,8 @@ export interface PartialConfig {
134
153
  storagePath: string;
135
154
  include: string[];
136
155
  scope?: "agent-directory";
156
+ pathPolicy?: "ignore-file";
157
+ ignoreFile?: string;
137
158
  exclude?: string[];
138
159
  reinclude?: string[];
139
160
  automatic: boolean;
@@ -1,6 +1,7 @@
1
1
  import { normalizeEndpointIdentity } from "../backends/backend-identity.js";
2
2
  import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote, normalizeGitRemoteIdentity, } from "../backends/git/git-config.js";
3
3
  import { normalizeWebDavIdentityUrl, normalizeWebDavPath, normalizeWebDavUrl, validateWebDavCredentials, } from "../backends/webdav/webdav-config.js";
4
+ import { validateIgnoreFilename } from "../ignore/ignore-source.js";
4
5
  import { normalizeSyncExclude } from "../sync/exclude-policy.js";
5
6
  import { normalizeLocalFields } from "../sync/local-field-policy.js";
6
7
  import { normalizeDirectoryRules, normalizeSyncInclude } from "../sync/sync-policy.js";
@@ -14,8 +15,8 @@ export function normalizeOnSwitch(value) {
14
15
  }
15
16
  export function validateSettingsDocument(value) {
16
17
  const version = value.version;
17
- if (version !== 3 && version !== 4 && version !== 5 && version !== 6 && version !== 7) {
18
- throw new Error(`Unsupported pi-sync settings: version 3, 4, 5, 6 or 7 is required. Keep the existing ${CONFIG_FILE_NAME} for recovery and use a compatible pi-sync client or review a separate supported setup; do not downgrade portable policies. pi-sync will not migrate or overwrite unsupported settings.`);
18
+ if (version !== 3 && version !== 4 && version !== 5 && version !== 6 && version !== 7 && version !== 8) {
19
+ throw new Error(`Unsupported pi-sync settings: version 3 through 8 is required. Keep the existing ${CONFIG_FILE_NAME} for recovery and use a compatible pi-sync client or review a separate supported setup; do not downgrade portable policies. pi-sync will not migrate or overwrite unsupported settings.`);
19
20
  }
20
21
  rejectLegacyFields(value, [
21
22
  "profiles",
@@ -149,7 +150,24 @@ function validateSyncSetup(name, value, connections, version) {
149
150
  }
150
151
  }
151
152
  const localFields = normalizeLocalFields(sync.localFields);
152
- if (Object.hasOwn(sync, "scope")) {
153
+ if (Object.hasOwn(sync, "pathPolicy")) {
154
+ if (sync.pathPolicy !== "ignore-file")
155
+ throw new Error("Invalid pi-sync settings: unsupported sync.pathPolicy.");
156
+ if (version < 8)
157
+ throw new Error("sync.pathPolicy requires explicit settings version 8.");
158
+ if (!Object.hasOwn(sync, "scope") || sync.scope !== "agent-directory")
159
+ throw new Error("Invalid pi-sync settings: sync.pathPolicy requires agent-directory scope.");
160
+ for (const key of ["include", "exclude", "reinclude"]) {
161
+ if (Object.hasOwn(sync, key))
162
+ throw new Error(`Invalid pi-sync settings: ignore-file policy cannot use sync.${key}.`);
163
+ }
164
+ if (Object.hasOwn(sync, "ignoreFile"))
165
+ validateIgnoreFilename(sync.ignoreFile);
166
+ }
167
+ else if (Object.hasOwn(sync, "ignoreFile")) {
168
+ throw new Error("Invalid pi-sync settings: sync.ignoreFile requires ignore-file pathPolicy.");
169
+ }
170
+ else if (Object.hasOwn(sync, "scope")) {
153
171
  if (sync.scope !== "agent-directory")
154
172
  throw new Error("Invalid pi-sync settings: unsupported sync.scope.");
155
173
  if (version < 7)
@@ -158,8 +176,6 @@ function validateSyncSetup(name, value, connections, version) {
158
176
  throw new Error("Invalid pi-sync settings: agent-directory scope cannot use sync.include.");
159
177
  normalizeDirectoryRules(sync.exclude);
160
178
  normalizeDirectoryRules(sync.reinclude);
161
- if (sync.sessions !== undefined && typeof sync.sessions !== "boolean")
162
- throw new Error("Invalid pi-sync settings: sync.sessions must be boolean.");
163
179
  }
164
180
  else {
165
181
  if (Object.hasOwn(sync, "sessions") || Object.hasOwn(sync, "reinclude"))
@@ -171,6 +187,8 @@ function validateSyncSetup(name, value, connections, version) {
171
187
  if (localFields.length > 0 && !include.includes("settings.json"))
172
188
  throw new Error("Nonempty localFields requires settings.json in sync.include.");
173
189
  }
190
+ if (sync.sessions !== undefined && typeof sync.sessions !== "boolean")
191
+ throw new Error("Invalid pi-sync settings: sync.sessions must be boolean.");
174
192
  if (sync.localFields !== undefined && version < 4)
175
193
  throw new Error("localFields requires explicit settings version 4; older binaries must refuse portable state.");
176
194
  if (sync.exclude !== undefined && version < 6)
@@ -3,7 +3,7 @@ import type { AnySyncConfig } from "../settings/settings-types.js";
3
3
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
4
4
  import type { Snapshot, SnapshotOptions } from "./snapshot-types.js";
5
5
  export declare function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext): string | undefined;
6
- export declare function configuredSessionDir(): Promise<string | undefined>;
6
+ export declare function configuredSessionDir(options?: Pick<SnapshotOptions, "reservedIgnoreNames" | "signal">): Promise<string | undefined>;
7
7
  export declare function effectiveSessionRoot(ctx: ExtensionCommandContext | ExtensionContext, policy?: SyncSelectionConfig, signal?: AbortSignal): Promise<string>;
8
8
  export declare function sessionDirForApply(ctx: ExtensionCommandContext | ExtensionContext, snapshot: Snapshot, options?: SnapshotOptions): Promise<string | undefined>;
9
9
  /** Hash-only merge plans cannot describe installation into a different session root. */
@@ -3,7 +3,7 @@ import os from "node:os";
3
3
  import path from "node:path";
4
4
  import { getEngineRoot as getAgentDir, } from "../host.js";
5
5
  import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
6
- import { agentDirectorySessionRoot } from "./snapshot-exclude-safety.js";
6
+ import { agentDirectorySessionRoot, reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
7
7
  import { sessionStorageRoot } from "./snapshot-paths.js";
8
8
  export function sessionDirFromContext(ctx) {
9
9
  const manager = ctx.sessionManager;
@@ -14,10 +14,19 @@ export function sessionDirFromContext(ctx) {
14
14
  const getSessionDir = manager.getSessionDir;
15
15
  return typeof getSessionDir === "function" ? getSessionDir.call(manager) : undefined;
16
16
  }
17
- export async function configuredSessionDir() {
17
+ export async function configuredSessionDir(options = {}) {
18
+ const root = agentDir();
19
+ const target = path.join(root, "settings.json");
20
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
18
21
  let content;
19
22
  try {
20
- content = await fs.readFile(path.join(agentDir(), "settings.json"), "utf8");
23
+ if (guardReserved) {
24
+ const { readLegacySnapshotSource } = await import("./snapshot.js");
25
+ content = (await readLegacySnapshotSource(target, guardReserved, options.signal)).toString("utf8");
26
+ }
27
+ else {
28
+ content = await fs.readFile(target, "utf8");
29
+ }
21
30
  }
22
31
  catch (error) {
23
32
  if (error.code === "ENOENT")
@@ -36,31 +45,41 @@ export async function configuredSessionDir() {
36
45
  }
37
46
  export async function effectiveSessionRoot(ctx, policy, signal) {
38
47
  const sessionDir = sessionDirFromContext(ctx);
48
+ const root = agentDir();
39
49
  if (policy?.scope === "agent-directory") {
40
- const root = agentDir();
41
50
  if (sessionDir !== undefined || ctx.sessionManager.usesDefaultSessionDir?.())
42
- return agentDirectorySessionRoot(root, sessionDir);
51
+ return agentDirectorySessionRoot(root, sessionDir, policy.ignorePolicy, policy.reservedIgnoreNames);
43
52
  if (!configuredSnapshotPathMatcher(policy)("settings.json"))
44
53
  throw new Error("Pi session storage is unknown and settings.json is excluded. Use an active Pi context to sync.");
45
54
  const { agentDirectoryConfiguredSessionDir } = await import("./snapshot.js");
46
55
  signal?.throwIfAborted();
47
- return agentDirectorySessionRoot(root, await agentDirectoryConfiguredSessionDir(signal));
56
+ const configured = await agentDirectoryConfiguredSessionDir(signal, root, policy);
57
+ return agentDirectorySessionRoot(root, configured, policy.ignorePolicy, policy.reservedIgnoreNames);
48
58
  }
49
- return path.resolve(sessionStorageRoot(agentDir(), sessionDir ?? (await configuredSessionDir())));
59
+ const resolved = sessionStorageRoot(root, sessionDir ?? (await configuredSessionDir({ ...policy, signal })));
60
+ const guardReserved = reservedIgnoreTargetGuard(root, policy ?? {});
61
+ if (guardReserved)
62
+ await guardReserved(resolved);
63
+ return resolved;
50
64
  }
51
65
  export async function sessionDirForApply(ctx, snapshot, options = {}) {
52
66
  const contextSessionDir = sessionDirFromContext(ctx);
53
67
  if (options.scope === "agent-directory") {
54
68
  const root = await effectiveSessionRoot(ctx, options, options.signal);
55
- if (root !== agentDirectorySessionRoot(agentDir(), options.sessionDir))
69
+ if (root !==
70
+ agentDirectorySessionRoot(agentDir(), options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames))
56
71
  throw new Error("Pi session storage changed during transfer; retry from a fresh review.");
57
72
  return root;
58
73
  }
59
- const localSessionDir = await configuredSessionDir();
60
- if (contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")) {
61
- return contextSessionDir;
62
- }
63
- return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
74
+ const localSessionDir = await configuredSessionDir(options);
75
+ const sessionDir = contextSessionDir && path.resolve(contextSessionDir) !== path.resolve(localSessionDir ?? "")
76
+ ? contextSessionDir
77
+ : (sessionDirFromSnapshot(snapshot) ?? contextSessionDir);
78
+ const root = agentDir();
79
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
80
+ if (guardReserved)
81
+ await guardReserved(sessionStorageRoot(root, sessionDir));
82
+ return sessionDir;
64
83
  }
65
84
  /** Hash-only merge plans cannot describe installation into a different session root. */
66
85
  export function requireStableMergeSessionRoot(before, after, scope) {
@@ -123,8 +142,12 @@ export function snapshotOptionsForContext(ctx, config) {
123
142
  return {
124
143
  include: config.include,
125
144
  ...(config.scope === undefined ? {} : { scope: config.scope }),
145
+ ...(config.ignorePolicy
146
+ ? { ignorePolicy: config.ignorePolicy, validateIgnorePolicy: config.validateIgnorePolicy }
147
+ : {}),
126
148
  ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
127
149
  ...(config.reinclude === undefined ? {} : { reinclude: config.reinclude }),
150
+ ...(config.reservedIgnoreNames === undefined ? {} : { reservedIgnoreNames: config.reservedIgnoreNames }),
128
151
  sessionDir: sessionDirFromContext(ctx) ?? defaultScopedSessionDir,
129
152
  };
130
153
  }
@@ -1,5 +1,5 @@
1
- import type { Snapshot, SnapshotApplyPlan, SnapshotOptions } from "./snapshot-types.js";
2
- export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "expectedFileHashes"> & {
1
+ import { type Snapshot, type SnapshotApplyPlan, type SnapshotOptions } from "./snapshot-types.js";
2
+ export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "validateIgnorePolicy" | "expectedFileHashes"> & {
3
3
  reviewedLocal?: Pick<Snapshot, "files">;
4
4
  }): Promise<{
5
5
  [k: string]: string;
@@ -10,7 +10,7 @@ export declare function addTopLevelCaseVariantDeletes(root: string, plan: Snapsh
10
10
  export declare function appliedFileHashMap(snapshot: Snapshot, current: Snapshot, protectedRelativePaths: Set<string>): {
11
11
  [k: string]: string;
12
12
  };
13
- type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude" | "scope" | "include" | "reinclude">;
13
+ type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation" | "exclude" | "scope" | "include" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames">;
14
14
  export declare function preflightSnapshotMutations(root: string, plan: {
15
15
  deletes: string[];
16
16
  writes: Array<{
@@ -4,7 +4,7 @@ import path from "node:path";
4
4
  import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "../paths.js";
5
5
  import { syncDirectory } from "../state/json-file.js";
6
6
  import { stateDir } from "../state/state-directory.js";
7
- import { compileSyncPolicyExclude } from "../sync/sync-policy.js";
7
+ import { compileSyncPolicyExclude, requireLegacyTransferPolicy, sameSnapshotSelection, selectionForSnapshot, } from "../sync/sync-policy.js";
8
8
  import { agentDir } from "./session-paths.js";
9
9
  import { agentDirectoryConfiguredSessionDir, agentDirectoryInventory, createSnapshot, isSessionFilePath, isSessionPath, sessionStorageRoot, snapshotIncludesSessions, snapshotTarget, } from "./snapshot.js";
10
10
  import { assertAgentDirectorySnapshotBound } from "./snapshot-bounds.js";
@@ -13,18 +13,34 @@ import { agentDirectoryPhysicalSessionPath, assertUnexcludedTargets } from "./sn
13
13
  import { decodeBase64Strict } from "./snapshot-payload.js";
14
14
  import { reviewedSnapshotPreimages } from "./snapshot-reviewed-preimages.js";
15
15
  import { applySnapshotTransaction, recoverPendingSnapshotTransactions } from "./snapshot-transaction.js";
16
+ import { ignorePolicyValidator } from "./snapshot-transaction-policy.js";
17
+ import { IGNORE_SNAPSHOT_VERSION, } from "./snapshot-types.js";
16
18
  function sha256(value) {
17
19
  return createHash("sha256").update(value).digest("hex");
18
20
  }
19
21
  function fileHashMap(snapshot) {
20
22
  return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
21
23
  }
24
+ function assertSnapshotApplyPolicy(snapshot, options) {
25
+ if (snapshot.version !== IGNORE_SNAPSHOT_VERSION) {
26
+ requireLegacyTransferPolicy(snapshot);
27
+ if (options.ignorePolicy)
28
+ throw new Error("Project the snapshot into the reviewed local ignore-file policy before applying it.");
29
+ return;
30
+ }
31
+ if (options.scope !== "agent-directory" || !options.ignorePolicy)
32
+ requireLegacyTransferPolicy(snapshot);
33
+ if (!sameSnapshotSelection(snapshot.selection, selectionForSnapshot(undefined, undefined, options)))
34
+ throw new Error("Snapshot does not match the local ignore-file policy; review and project it before applying it.");
35
+ }
22
36
  export async function applySnapshot(snapshot, protectedRelativePaths = new Set(), options = {}) {
37
+ assertSnapshotApplyPolicy(snapshot, options);
38
+ const validateIgnorePolicy = ignorePolicyValidator(options);
23
39
  const root = agentDir();
24
40
  if (snapshot.version === 5 && options.scope !== "agent-directory")
25
41
  throw new Error("Agent-directory snapshot apply requires the local agent-directory policy.");
26
42
  const sessionDir = options.scope === "agent-directory"
27
- ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root)))
43
+ ? sessionStorageRoot(root, options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options)))
28
44
  : options.sessionDir;
29
45
  options.validateMutation?.();
30
46
  options = { ...options, sessionDir };
@@ -41,6 +57,8 @@ export async function applySnapshot(snapshot, protectedRelativePaths = new Set()
41
57
  ])),
42
58
  };
43
59
  options.validateMutation?.();
60
+ if (validateIgnorePolicy)
61
+ await validateIgnorePolicy();
44
62
  await recoverPendingSnapshotTransactions(transactionOptions);
45
63
  const current = await createSnapshot(snapshot.profile, {
46
64
  ...options,
@@ -95,6 +113,7 @@ function sameReviewedFiles(scanned, reviewed) {
95
113
  reviewed.files.every((file) => hashes.get(file.path) === file.sha256));
96
114
  }
97
115
  export function preflightSnapshotApply(root, snapshot, current, options = {}) {
116
+ assertSnapshotApplyPolicy(snapshot, options);
98
117
  const seenPaths = new Set();
99
118
  const remotePaths = new Set();
100
119
  const writes = [];
@@ -154,7 +173,7 @@ export function protectSnapshotApplyPlan(root, plan, protectedRelativePaths, ses
154
173
  };
155
174
  }
156
175
  export async function addTopLevelCaseVariantDeletes(root, plan, snapshot, options = {}) {
157
- if (options.scope === "agent-directory" || snapshot.selection?.version === 3)
176
+ if (options.scope === "agent-directory" || snapshot.selection?.scope === "agent-directory")
158
177
  return plan;
159
178
  const excluded = compileSyncPolicyExclude(options);
160
179
  const topLevelPaths = new Map();
@@ -219,7 +238,7 @@ function excludedApplyPath(root, options) {
219
238
  const excluded = compileSyncPolicyExclude(options);
220
239
  if (options.scope !== "agent-directory")
221
240
  return excluded;
222
- const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir);
241
+ const physicalSessionPath = agentDirectoryPhysicalSessionPath(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames);
223
242
  return (relative) => excluded(relative) ||
224
243
  (/^sessions(?:\/|$)/iu.test(relative) ? !isSessionFilePath(relative) : physicalSessionPath(relative));
225
244
  }
@@ -1,4 +1,4 @@
1
- import type { Snapshot } from "./snapshot-types.js";
1
+ import { type Snapshot } from "./snapshot-types.js";
2
2
  export declare function encodeSnapshot(snapshot: Snapshot): Promise<NonSharedBuffer>;
3
3
  export declare function decodeSnapshot(buffer: Buffer, options?: {
4
4
  signal?: AbortSignal;
@@ -1,16 +1,21 @@
1
+ import { isUtf8 } from "node:buffer";
1
2
  import { Readable, Writable } from "node:stream";
2
3
  import { pipeline } from "node:stream/promises";
3
4
  import { promisify } from "node:util";
4
5
  import { createGunzip, gzip } from "node:zlib";
5
6
  import { throwIfAborted } from "../sync/signals.js";
6
7
  import { snapshotSelectionInclude, validateSnapshotSelection } from "../sync/sync-policy.js";
8
+ import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion } from "./snapshot-types.js";
7
9
  const VERSION = 1;
8
10
  const MAX_DECOMPRESSED_SNAPSHOT_BYTES = 512 * 1024 * 1024;
9
11
  const gzipAsync = promisify(gzip);
10
12
  export async function encodeSnapshot(snapshot) {
11
- snapshotSelectionInclude(snapshot);
13
+ if (!isSupportedSnapshotVersion(snapshot?.version))
14
+ throw new Error("Unsupported snapshot format.");
15
+ if (snapshot.version !== IGNORE_SNAPSHOT_VERSION)
16
+ snapshotSelectionInclude(snapshot);
12
17
  validateSnapshotSelection(snapshot);
13
- if (snapshot.version === 4 || snapshot.version === 5) {
18
+ if (snapshot.version === 4 || snapshot.version === 5 || snapshot.version === IGNORE_SNAPSHOT_VERSION) {
14
19
  const { validatePortableSnapshot } = await import("../sync/local-fields.js");
15
20
  validatePortableSnapshot(snapshot);
16
21
  }
@@ -34,10 +39,13 @@ export async function decodeSnapshot(buffer, options = {}) {
34
39
  });
35
40
  await pipeline(Readable.from([buffer]), createGunzip(), sink, { signal: options.signal });
36
41
  throwIfAborted(options.signal);
37
- const parsed = JSON.parse(Buffer.concat(chunks, total).toString("utf8"));
38
- if (![VERSION, 2, 3, 4, 5].includes(parsed.version) || !Array.isArray(parsed.files)) {
42
+ const payload = Buffer.concat(chunks, total);
43
+ const parsed = JSON.parse(payload.toString("utf8"));
44
+ if (!isSupportedSnapshotVersion(parsed?.version) || !Array.isArray(parsed.files)) {
39
45
  throw new Error("Unsupported snapshot format.");
40
46
  }
47
+ if (parsed.version === IGNORE_SNAPSHOT_VERSION && !isUtf8(payload))
48
+ throw new Error("Invalid snapshot UTF-8.");
41
49
  validateSnapshotSelection(parsed);
42
50
  if (parsed.version !== VERSION) {
43
51
  const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
@@ -47,6 +55,7 @@ export async function decodeSnapshot(buffer, options = {}) {
47
55
  }
48
56
  else if (parsed.localFields !== undefined)
49
57
  throw new Error("Portable field policy requires snapshot version 2.");
50
- snapshotSelectionInclude(parsed);
58
+ if (parsed.version !== IGNORE_SNAPSHOT_VERSION)
59
+ snapshotSelectionInclude(parsed);
51
60
  return parsed;
52
61
  }
@@ -1,7 +1,9 @@
1
1
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
+ import type { DirectoryScope, EffectiveIgnorePolicy } from "./snapshot-types.js";
2
3
  export declare function agentDirectoryAnchor(root: string, boundary: string): string;
3
- export declare function agentDirectorySessionRoot(root: string, sessionDir?: string): string;
4
- export declare function agentDirectoryPhysicalSessionPath(root: string, sessionDir?: string): (relativePath: string) => boolean;
4
+ export declare function agentDirectorySessionRoot(root: string, sessionDir?: string, ignorePolicy?: EffectiveIgnorePolicy, reservedIgnoreNames?: DirectoryScope["reservedIgnoreNames"]): string;
5
+ export declare function agentDirectoryPhysicalSessionPath(root: string, sessionDir?: string, ignorePolicy?: EffectiveIgnorePolicy, reservedIgnoreNames?: DirectoryScope["reservedIgnoreNames"]): (relativePath: string) => boolean;
6
+ export declare function reservedIgnoreTargetGuard(root: string, options: Pick<DirectoryScope, "reservedIgnoreNames">): ((target: string) => Promise<string>) | undefined;
5
7
  /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
6
8
  export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: SyncSelectionConfig & {
7
9
  sessionDir?: string;