brain-memory 0.1.0-beta.3 → 0.1.0-beta.5

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.
@@ -0,0 +1,774 @@
1
+ /**
2
+ * Brain Memory — Sync Engine
3
+ *
4
+ * Local-first sync with three-way diff (local vs remote vs last-known sync state).
5
+ * Supports push/pull, conflict resolution, and optional encryption.
6
+ */
7
+
8
+ const crypto = require('crypto');
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+ const { getBrainDir } = require('../index-manager');
12
+ const { getSyncDir, encryptBuffer, decryptBuffer } = require('./crypto-utils');
13
+ const { createProvider } = require('./provider');
14
+ const { loadCredentials, saveCredentials, deleteCredentials } = require('./crypto-utils');
15
+ const { OAUTH_CONFIGS, authorizeWithPKCE, authorizeWithDeviceCode, ensureFreshTokens } = require('./oauth');
16
+
17
+ const CONFIG_FILE = 'config.json';
18
+ const STATE_FILE = 'sync-state.json';
19
+
20
+ // Files/dirs to exclude from sync
21
+ const EXCLUDED = new Set(['.sync']);
22
+
23
+ // ---------------------------------------------------------------------------
24
+ // Config & State Management
25
+ // ---------------------------------------------------------------------------
26
+
27
+ /**
28
+ * Read sync configuration from .brain/.sync/config.json.
29
+ *
30
+ * @param {string} [projectRoot] - Project root directory
31
+ * @returns {Object|null} Config or null if not configured
32
+ */
33
+ function readSyncConfig(projectRoot) {
34
+ const configPath = path.join(getSyncDir(projectRoot), CONFIG_FILE);
35
+ if (!fs.existsSync(configPath)) return null;
36
+ return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
37
+ }
38
+
39
+ /**
40
+ * Write sync configuration to .brain/.sync/config.json.
41
+ *
42
+ * @param {Object} config - Configuration to write
43
+ * @param {string} [projectRoot] - Project root directory
44
+ */
45
+ function writeSyncConfig(config, projectRoot) {
46
+ const syncDir = getSyncDir(projectRoot);
47
+ fs.mkdirSync(syncDir, { recursive: true });
48
+ fs.writeFileSync(
49
+ path.join(syncDir, CONFIG_FILE),
50
+ JSON.stringify(config, null, 2) + '\n'
51
+ );
52
+ }
53
+
54
+ /**
55
+ * Read sync state from .brain/.sync/sync-state.json.
56
+ *
57
+ * @param {string} [projectRoot] - Project root directory
58
+ * @returns {Object} Sync state (defaults to empty state)
59
+ */
60
+ function readSyncState(projectRoot) {
61
+ const statePath = path.join(getSyncDir(projectRoot), STATE_FILE);
62
+ if (!fs.existsSync(statePath)) {
63
+ return { version: 1, files: {}, cursor: null, lastSync: null, pathCache: null };
64
+ }
65
+ return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
66
+ }
67
+
68
+ /**
69
+ * Write sync state to .brain/.sync/sync-state.json.
70
+ *
71
+ * @param {Object} state - State to write
72
+ * @param {string} [projectRoot] - Project root directory
73
+ */
74
+ function writeSyncState(state, projectRoot) {
75
+ const syncDir = getSyncDir(projectRoot);
76
+ fs.mkdirSync(syncDir, { recursive: true });
77
+ fs.writeFileSync(
78
+ path.join(syncDir, STATE_FILE),
79
+ JSON.stringify(state, null, 2) + '\n'
80
+ );
81
+ }
82
+
83
+ // ---------------------------------------------------------------------------
84
+ // Local File Discovery
85
+ // ---------------------------------------------------------------------------
86
+
87
+ /**
88
+ * Recursively walk .brain/ and collect all syncable files.
89
+ * Excludes .brain/.sync/ directory.
90
+ *
91
+ * @param {string} [projectRoot] - Project root directory
92
+ * @returns {Map<string, {hash: string, size: number, modified: string}>} Relative path → file info
93
+ */
94
+ function getLocalFiles(projectRoot) {
95
+ const brainDir = getBrainDir(projectRoot);
96
+ const files = new Map();
97
+
98
+ if (!fs.existsSync(brainDir)) return files;
99
+
100
+ function walk(dir, prefix) {
101
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
102
+ for (const entry of entries) {
103
+ const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
104
+
105
+ if (entry.isDirectory()) {
106
+ if (EXCLUDED.has(entry.name)) continue;
107
+ walk(path.join(dir, entry.name), relativePath);
108
+ } else {
109
+ const fullPath = path.join(dir, entry.name);
110
+ const stat = fs.statSync(fullPath);
111
+ const content = fs.readFileSync(fullPath);
112
+ files.set(relativePath, {
113
+ hash: computeLocalHash(content),
114
+ size: stat.size,
115
+ modified: stat.mtime.toISOString(),
116
+ });
117
+ }
118
+ }
119
+ }
120
+
121
+ walk(brainDir, '');
122
+ return files;
123
+ }
124
+
125
+ /**
126
+ * Compute SHA-256 hash of file content (universal local hash).
127
+ *
128
+ * @param {Buffer|string} content - File content
129
+ * @returns {string} Hex-encoded SHA-256 hash
130
+ */
131
+ function computeLocalHash(content) {
132
+ return crypto.createHash('sha256').update(content).digest('hex');
133
+ }
134
+
135
+ // ---------------------------------------------------------------------------
136
+ // Three-Way Diff
137
+ // ---------------------------------------------------------------------------
138
+
139
+ /**
140
+ * Compute the sync diff using three-way comparison.
141
+ *
142
+ * sync-state.json tracks per file: { localHash, remoteHash, remoteRev, lastSynced }
143
+ *
144
+ * | Local vs SyncState | Remote vs SyncState | Action |
145
+ * |--------------------|---------------------|---------------|
146
+ * | Changed | Unchanged | → toUpload |
147
+ * | Unchanged | Changed | → toDownload |
148
+ * | Changed | Changed | → conflict |
149
+ * | New (not in state) | — | → toUpload |
150
+ * | — | New (not in state) | → toDownload |
151
+ * | Deleted | Unchanged | → toDeleteRemote |
152
+ * | Unchanged | Deleted | → toDeleteLocal |
153
+ *
154
+ * @param {Map<string, Object>} localFiles - From getLocalFiles()
155
+ * @param {Array<Object>} remoteFiles - From provider.listFiles()
156
+ * @param {Object} syncState - From readSyncState()
157
+ * @returns {Object} { toUpload, toDownload, toDeleteRemote, toDeleteLocal, conflicts, unchanged }
158
+ */
159
+ function computeSyncDiff(localFiles, remoteFiles, syncState) {
160
+ const stateFiles = syncState.files || {};
161
+ const remoteMap = new Map();
162
+ for (const rf of remoteFiles) {
163
+ remoteMap.set(rf.path, rf);
164
+ }
165
+
166
+ const toUpload = [];
167
+ const toDownload = [];
168
+ const toDeleteRemote = [];
169
+ const toDeleteLocal = [];
170
+ const conflicts = [];
171
+ const unchanged = [];
172
+
173
+ // All known paths: local + remote + state
174
+ const allPaths = new Set([
175
+ ...localFiles.keys(),
176
+ ...remoteMap.keys(),
177
+ ...Object.keys(stateFiles),
178
+ ]);
179
+
180
+ for (const filePath of allPaths) {
181
+ const local = localFiles.get(filePath);
182
+ const remote = remoteMap.get(filePath);
183
+ const state = stateFiles[filePath];
184
+
185
+ const localExists = !!local;
186
+ const remoteExists = !!remote && !remote.deleted;
187
+ const stateExists = !!state;
188
+
189
+ if (localExists && !remoteExists && !stateExists) {
190
+ // New local file, not known to sync → upload
191
+ toUpload.push({ path: filePath, reason: 'new_local' });
192
+ } else if (!localExists && remoteExists && !stateExists) {
193
+ // New remote file, not known to sync → download
194
+ toDownload.push({ path: filePath, rev: remote.rev, reason: 'new_remote' });
195
+ } else if (localExists && remoteExists && !stateExists) {
196
+ // Both exist but no state — treat as conflict
197
+ conflicts.push({ path: filePath, rev: remote.rev, reason: 'both_new' });
198
+ } else if (localExists && remoteExists && stateExists) {
199
+ const localChanged = local.hash !== state.localHash;
200
+ const remoteChanged = remote.hash !== state.remoteHash;
201
+
202
+ if (localChanged && remoteChanged) {
203
+ conflicts.push({ path: filePath, rev: remote.rev, reason: 'both_modified' });
204
+ } else if (localChanged && !remoteChanged) {
205
+ toUpload.push({ path: filePath, rev: state.remoteRev, reason: 'local_modified' });
206
+ } else if (!localChanged && remoteChanged) {
207
+ toDownload.push({ path: filePath, rev: remote.rev, reason: 'remote_modified' });
208
+ } else {
209
+ unchanged.push({ path: filePath });
210
+ }
211
+ } else if (localExists && !remoteExists && stateExists) {
212
+ // Remote was deleted since last sync
213
+ if (local.hash !== state.localHash) {
214
+ // Local also changed — conflict
215
+ conflicts.push({ path: filePath, reason: 'local_modified_remote_deleted' });
216
+ } else {
217
+ toDeleteLocal.push({ path: filePath, reason: 'remote_deleted' });
218
+ }
219
+ } else if (!localExists && remoteExists && stateExists) {
220
+ // Local was deleted since last sync
221
+ if (remote.hash !== state.remoteHash) {
222
+ // Remote also changed — conflict
223
+ conflicts.push({ path: filePath, rev: remote.rev, reason: 'remote_modified_local_deleted' });
224
+ } else {
225
+ toDeleteRemote.push({ path: filePath, rev: state.remoteRev, reason: 'local_deleted' });
226
+ }
227
+ } else if (!localExists && !remoteExists && stateExists) {
228
+ // Both deleted — just clean up state (handled in unchanged/cleanup)
229
+ unchanged.push({ path: filePath, bothDeleted: true });
230
+ }
231
+ }
232
+
233
+ return { toUpload, toDownload, toDeleteRemote, toDeleteLocal, conflicts, unchanged };
234
+ }
235
+
236
+ // ---------------------------------------------------------------------------
237
+ // Push / Pull Operations
238
+ // ---------------------------------------------------------------------------
239
+
240
+ /**
241
+ * Push local changes to the cloud.
242
+ *
243
+ * @param {string} [projectRoot] - Project root directory
244
+ * @param {Object} [options]
245
+ * @param {boolean} [options.dryRun] - Preview without executing
246
+ * @param {boolean} [options.force] - Force upload even on conflicts
247
+ * @returns {Promise<Object>} Push results
248
+ */
249
+ async function push(projectRoot, options = {}) {
250
+ const config = readSyncConfig(projectRoot);
251
+ if (!config) throw new Error('Sync not configured. Run setup first.');
252
+
253
+ const provider = await _getProvider(config, projectRoot);
254
+ const state = readSyncState(projectRoot);
255
+
256
+ // Get local and remote file lists
257
+ const localFiles = getLocalFiles(projectRoot);
258
+
259
+ let allRemoteFiles = [];
260
+ let cursor = state.cursor;
261
+ if (cursor) {
262
+ // Delta sync
263
+ let result = await provider.listFiles(cursor);
264
+ allRemoteFiles = result.files;
265
+ cursor = result.cursor;
266
+ while (result.hasMore) {
267
+ result = await provider.listFiles(cursor);
268
+ allRemoteFiles = allRemoteFiles.concat(result.files);
269
+ cursor = result.cursor;
270
+ }
271
+ } else {
272
+ // Full listing
273
+ const result = await provider.listFiles(null);
274
+ allRemoteFiles = result.files;
275
+ cursor = result.cursor;
276
+ }
277
+
278
+ const diff = computeSyncDiff(localFiles, allRemoteFiles, state);
279
+
280
+ if (options.dryRun) {
281
+ return { dryRun: true, ...diff };
282
+ }
283
+
284
+ const results = { uploaded: [], deleted: [], conflicts: diff.conflicts, errors: [] };
285
+
286
+ // Upload changed/new files
287
+ for (const item of diff.toUpload) {
288
+ try {
289
+ await _pushFile(provider, item, projectRoot, config, state);
290
+ results.uploaded.push(item.path);
291
+ } catch (err) {
292
+ if (err.code === 'CONFLICT') {
293
+ results.conflicts.push({ path: item.path, reason: 'upload_conflict' });
294
+ } else {
295
+ results.errors.push({ path: item.path, error: err.message });
296
+ }
297
+ }
298
+ }
299
+
300
+ // Delete remote files that were deleted locally
301
+ for (const item of diff.toDeleteRemote) {
302
+ try {
303
+ await provider.deleteFile(item.path);
304
+ delete state.files[item.path];
305
+ results.deleted.push(item.path);
306
+ } catch (err) {
307
+ results.errors.push({ path: item.path, error: err.message });
308
+ }
309
+ }
310
+
311
+ // Handle force mode for conflicts
312
+ if (options.force) {
313
+ for (const item of diff.conflicts) {
314
+ try {
315
+ await _pushFile(provider, { ...item, mode: 'overwrite' }, projectRoot, config, state);
316
+ results.uploaded.push(item.path);
317
+ } catch (err) {
318
+ results.errors.push({ path: item.path, error: err.message });
319
+ }
320
+ }
321
+ results.conflicts = [];
322
+ }
323
+
324
+ // Update path cache for Google Drive
325
+ if (config.provider === 'google-drive' && provider.exportPathCache) {
326
+ state.pathCache = provider.exportPathCache();
327
+ }
328
+
329
+ // Update cursor and timestamp
330
+ state.cursor = cursor;
331
+ state.lastSync = new Date().toISOString();
332
+
333
+ // Clean up state for both-deleted files
334
+ for (const item of diff.unchanged) {
335
+ if (item.bothDeleted) {
336
+ delete state.files[item.path];
337
+ }
338
+ }
339
+
340
+ writeSyncState(state, projectRoot);
341
+
342
+ return results;
343
+ }
344
+
345
+ /**
346
+ * Pull remote changes to local.
347
+ *
348
+ * @param {string} [projectRoot] - Project root directory
349
+ * @param {Object} [options]
350
+ * @param {boolean} [options.dryRun] - Preview without executing
351
+ * @param {boolean} [options.force] - Force download even on conflicts
352
+ * @returns {Promise<Object>} Pull results
353
+ */
354
+ async function pull(projectRoot, options = {}) {
355
+ const config = readSyncConfig(projectRoot);
356
+ if (!config) throw new Error('Sync not configured. Run setup first.');
357
+
358
+ const provider = await _getProvider(config, projectRoot);
359
+ const state = readSyncState(projectRoot);
360
+
361
+ // Get local and remote file lists
362
+ const localFiles = getLocalFiles(projectRoot);
363
+
364
+ let allRemoteFiles = [];
365
+ let cursor = state.cursor;
366
+ if (cursor) {
367
+ let result = await provider.listFiles(cursor);
368
+ allRemoteFiles = result.files;
369
+ cursor = result.cursor;
370
+ while (result.hasMore) {
371
+ result = await provider.listFiles(cursor);
372
+ allRemoteFiles = allRemoteFiles.concat(result.files);
373
+ cursor = result.cursor;
374
+ }
375
+ } else {
376
+ const result = await provider.listFiles(null);
377
+ allRemoteFiles = result.files;
378
+ cursor = result.cursor;
379
+ }
380
+
381
+ const diff = computeSyncDiff(localFiles, allRemoteFiles, state);
382
+
383
+ if (options.dryRun) {
384
+ return { dryRun: true, ...diff };
385
+ }
386
+
387
+ const results = { downloaded: [], deleted: [], conflicts: diff.conflicts, errors: [] };
388
+
389
+ // Download changed/new files
390
+ for (const item of diff.toDownload) {
391
+ try {
392
+ await _pullFile(provider, item, projectRoot, config, state);
393
+ results.downloaded.push(item.path);
394
+ } catch (err) {
395
+ results.errors.push({ path: item.path, error: err.message });
396
+ }
397
+ }
398
+
399
+ // Delete local files that were deleted remotely
400
+ for (const item of diff.toDeleteLocal) {
401
+ try {
402
+ const fullPath = path.join(getBrainDir(projectRoot), item.path);
403
+ if (fs.existsSync(fullPath)) {
404
+ fs.unlinkSync(fullPath);
405
+ }
406
+ delete state.files[item.path];
407
+ results.deleted.push(item.path);
408
+ } catch (err) {
409
+ results.errors.push({ path: item.path, error: err.message });
410
+ }
411
+ }
412
+
413
+ // Handle force mode for conflicts
414
+ if (options.force) {
415
+ for (const item of diff.conflicts) {
416
+ try {
417
+ await _pullFile(provider, item, projectRoot, config, state);
418
+ results.downloaded.push(item.path);
419
+ } catch (err) {
420
+ results.errors.push({ path: item.path, error: err.message });
421
+ }
422
+ }
423
+ results.conflicts = [];
424
+ }
425
+
426
+ // Update path cache for Google Drive
427
+ if (config.provider === 'google-drive' && provider.exportPathCache) {
428
+ state.pathCache = provider.exportPathCache();
429
+ }
430
+
431
+ state.cursor = cursor;
432
+ state.lastSync = new Date().toISOString();
433
+
434
+ for (const item of diff.unchanged) {
435
+ if (item.bothDeleted) {
436
+ delete state.files[item.path];
437
+ }
438
+ }
439
+
440
+ writeSyncState(state, projectRoot);
441
+
442
+ return results;
443
+ }
444
+
445
+ /**
446
+ * Push a single file to the provider (with optional encryption).
447
+ */
448
+ async function _pushFile(provider, item, projectRoot, config, state) {
449
+ const fullPath = path.join(getBrainDir(projectRoot), item.path);
450
+ let content = fs.readFileSync(fullPath);
451
+ const localHash = computeLocalHash(content);
452
+
453
+ // Encrypt if enabled
454
+ if (config.encryption?.enabled && config.encryption?.passphrase) {
455
+ content = encryptBuffer(content, config.encryption.passphrase);
456
+ }
457
+
458
+ const uploadOptions = {};
459
+ if (item.rev) uploadOptions.rev = item.rev;
460
+ if (item.mode) uploadOptions.mode = item.mode;
461
+ else uploadOptions.mode = item.rev ? 'update' : 'add';
462
+
463
+ const result = await provider.uploadFile(item.path, content, uploadOptions);
464
+
465
+ // Update sync state for this file
466
+ if (!state.files) state.files = {};
467
+ state.files[item.path] = {
468
+ localHash,
469
+ remoteHash: result.hash || provider.computeContentHash(content),
470
+ remoteRev: result.rev,
471
+ lastSynced: new Date().toISOString(),
472
+ };
473
+ }
474
+
475
+ /**
476
+ * Pull a single file from the provider (with optional decryption).
477
+ */
478
+ async function _pullFile(provider, item, projectRoot, config, state) {
479
+ const { content: rawContent, rev, hash } = await provider.downloadFile(item.path);
480
+
481
+ // Decrypt if enabled
482
+ let content = rawContent;
483
+ if (config.encryption?.enabled && config.encryption?.passphrase) {
484
+ content = decryptBuffer(rawContent, config.encryption.passphrase);
485
+ }
486
+
487
+ // Write to local filesystem
488
+ const fullPath = path.join(getBrainDir(projectRoot), item.path);
489
+ fs.mkdirSync(path.dirname(fullPath), { recursive: true });
490
+ fs.writeFileSync(fullPath, content);
491
+
492
+ // Update sync state
493
+ if (!state.files) state.files = {};
494
+ state.files[item.path] = {
495
+ localHash: computeLocalHash(content),
496
+ remoteHash: hash || provider.computeContentHash(rawContent),
497
+ remoteRev: rev,
498
+ lastSynced: new Date().toISOString(),
499
+ };
500
+ }
501
+
502
+ /**
503
+ * Get an authenticated provider instance.
504
+ */
505
+ async function _getProvider(config, projectRoot) {
506
+ let tokens = loadCredentials(projectRoot, config.credentialPassphrase);
507
+ if (!tokens) throw new Error('No credentials found. Run login first.');
508
+
509
+ tokens = await ensureFreshTokens(
510
+ tokens, config.provider, config.clientId, projectRoot, config.credentialPassphrase
511
+ );
512
+
513
+ const providerConfig = {
514
+ accessToken: tokens.access_token,
515
+ options: {},
516
+ };
517
+
518
+ // Restore Google Drive path cache
519
+ if (config.provider === 'google-drive') {
520
+ const state = readSyncState(projectRoot);
521
+ if (state.pathCache) {
522
+ providerConfig.options.pathCache = state.pathCache;
523
+ }
524
+ }
525
+
526
+ return createProvider(config.provider, providerConfig);
527
+ }
528
+
529
+ // ---------------------------------------------------------------------------
530
+ // Conflict Resolution
531
+ // ---------------------------------------------------------------------------
532
+
533
+ /**
534
+ * List current conflicts.
535
+ *
536
+ * @param {string} [projectRoot] - Project root directory
537
+ * @returns {Array<Object>} Conflict entries from sync state
538
+ */
539
+ function listConflicts(projectRoot) {
540
+ const state = readSyncState(projectRoot);
541
+ return Object.entries(state.files || {})
542
+ .filter(([, info]) => info.conflict)
543
+ .map(([filePath, info]) => ({
544
+ path: filePath,
545
+ reason: info.conflict,
546
+ localHash: info.localHash,
547
+ remoteHash: info.remoteHash,
548
+ }));
549
+ }
550
+
551
+ /**
552
+ * Resolve a conflict for a specific file.
553
+ *
554
+ * @param {string} [projectRoot] - Project root directory
555
+ * @param {string} filePath - Relative path of conflicted file
556
+ * @param {string} resolution - 'keep-local' | 'keep-remote' | 'keep-both'
557
+ * @returns {Promise<Object>} Resolution result
558
+ */
559
+ async function resolveConflict(projectRoot, filePath, resolution) {
560
+ const config = readSyncConfig(projectRoot);
561
+ if (!config) throw new Error('Sync not configured.');
562
+
563
+ const state = readSyncState(projectRoot);
564
+
565
+ switch (resolution) {
566
+ case 'keep-local': {
567
+ // Push local version to remote
568
+ const provider = await _getProvider(config, projectRoot);
569
+ await _pushFile(provider, { path: filePath, mode: 'overwrite' }, projectRoot, config, state);
570
+ if (state.files[filePath]) delete state.files[filePath].conflict;
571
+ writeSyncState(state, projectRoot);
572
+ return { resolved: true, action: 'pushed local version' };
573
+ }
574
+ case 'keep-remote': {
575
+ // Pull remote version to local
576
+ const provider = await _getProvider(config, projectRoot);
577
+ await _pullFile(provider, { path: filePath }, projectRoot, config, state);
578
+ if (state.files[filePath]) delete state.files[filePath].conflict;
579
+ writeSyncState(state, projectRoot);
580
+ return { resolved: true, action: 'pulled remote version' };
581
+ }
582
+ case 'keep-both': {
583
+ // Rename local file with .local suffix, then pull remote
584
+ const brainDir = getBrainDir(projectRoot);
585
+ const localPath = path.join(brainDir, filePath);
586
+ const ext = path.extname(filePath);
587
+ const base = filePath.slice(0, -ext.length);
588
+ const conflictPath = `${base}.local${ext}`;
589
+ const conflictFullPath = path.join(brainDir, conflictPath);
590
+
591
+ if (fs.existsSync(localPath)) {
592
+ fs.copyFileSync(localPath, conflictFullPath);
593
+ }
594
+
595
+ const provider = await _getProvider(config, projectRoot);
596
+ await _pullFile(provider, { path: filePath }, projectRoot, config, state);
597
+ if (state.files[filePath]) delete state.files[filePath].conflict;
598
+ writeSyncState(state, projectRoot);
599
+ return { resolved: true, action: `kept both (local saved as ${conflictPath})` };
600
+ }
601
+ default:
602
+ throw new Error(`Unknown resolution: ${resolution}. Use keep-local, keep-remote, or keep-both.`);
603
+ }
604
+ }
605
+
606
+ // ---------------------------------------------------------------------------
607
+ // Status & Setup
608
+ // ---------------------------------------------------------------------------
609
+
610
+ /**
611
+ * Get sync status information.
612
+ *
613
+ * @param {string} [projectRoot] - Project root directory
614
+ * @returns {Promise<Object>} Status info
615
+ */
616
+ async function syncStatus(projectRoot) {
617
+ const config = readSyncConfig(projectRoot);
618
+ if (!config) {
619
+ return { configured: false };
620
+ }
621
+
622
+ const state = readSyncState(projectRoot);
623
+ const localFiles = getLocalFiles(projectRoot);
624
+
625
+ // Count pending changes
626
+ let pendingChanges = 0;
627
+ for (const [filePath, local] of localFiles) {
628
+ const stateEntry = state.files?.[filePath];
629
+ if (!stateEntry || stateEntry.localHash !== local.hash) {
630
+ pendingChanges++;
631
+ }
632
+ }
633
+
634
+ const status = {
635
+ configured: true,
636
+ provider: config.provider,
637
+ encryption: config.encryption?.enabled || false,
638
+ lastSync: state.lastSync,
639
+ pendingChanges,
640
+ conflicts: listConflicts(projectRoot),
641
+ trackedFiles: Object.keys(state.files || {}).length,
642
+ };
643
+
644
+ // Test connection
645
+ try {
646
+ const provider = await _getProvider(config, projectRoot);
647
+ const conn = await provider.testConnection();
648
+ status.connected = conn.ok;
649
+ status.account = conn.account;
650
+ } catch {
651
+ status.connected = false;
652
+ status.account = null;
653
+ }
654
+
655
+ return status;
656
+ }
657
+
658
+ /**
659
+ * Set up cloud sync for a brain.
660
+ *
661
+ * @param {string} [projectRoot] - Project root directory
662
+ * @param {string} providerName - Provider: 'dropbox', 'google-drive', 'onedrive'
663
+ * @param {string} clientId - OAuth client ID
664
+ * @param {Object} [options]
665
+ * @param {boolean} [options.encryption] - Enable encryption
666
+ * @param {string} [options.passphrase] - Encryption passphrase
667
+ * @param {boolean} [options.useDeviceCode] - Use Device Code Flow instead of PKCE
668
+ * @param {Function} [options.onUserCode] - Callback for Device Code Flow
669
+ * @returns {Promise<Object>} Setup result
670
+ */
671
+ async function setupSync(projectRoot, providerName, clientId, options = {}) {
672
+ if (!OAUTH_CONFIGS[providerName]) {
673
+ throw new Error(`Unknown provider: ${providerName}. Use: dropbox, google-drive, onedrive`);
674
+ }
675
+
676
+ // Authorize
677
+ let tokens;
678
+ if (options.useDeviceCode) {
679
+ tokens = await authorizeWithDeviceCode({
680
+ provider: providerName,
681
+ clientId,
682
+ onUserCode: options.onUserCode,
683
+ });
684
+ } else {
685
+ tokens = await authorizeWithPKCE({
686
+ provider: providerName,
687
+ clientId,
688
+ });
689
+ }
690
+
691
+ // Save config
692
+ const config = {
693
+ provider: providerName,
694
+ clientId,
695
+ encryption: {
696
+ enabled: options.encryption || false,
697
+ passphrase: options.passphrase || null,
698
+ },
699
+ credentialPassphrase: options.credentialPassphrase || null,
700
+ createdAt: new Date().toISOString(),
701
+ };
702
+ writeSyncConfig(config, projectRoot);
703
+
704
+ // Save credentials
705
+ saveCredentials(tokens, projectRoot, config.credentialPassphrase);
706
+
707
+ // Test connection
708
+ const provider = createProvider(providerName, {
709
+ accessToken: tokens.access_token,
710
+ });
711
+ const connection = await provider.testConnection();
712
+
713
+ // Initialize sync state with a full remote listing
714
+ const listing = await provider.listFiles(null);
715
+ const state = {
716
+ version: 1,
717
+ files: {},
718
+ cursor: listing.cursor,
719
+ lastSync: null,
720
+ };
721
+
722
+ if (providerName === 'google-drive' && provider.exportPathCache) {
723
+ state.pathCache = provider.exportPathCache();
724
+ }
725
+
726
+ writeSyncState(state, projectRoot);
727
+
728
+ return {
729
+ success: true,
730
+ provider: providerName,
731
+ account: connection.account,
732
+ remoteFiles: listing.files.length,
733
+ };
734
+ }
735
+
736
+ /**
737
+ * Log out: delete credentials and clear sync state.
738
+ *
739
+ * @param {string} [projectRoot] - Project root directory
740
+ */
741
+ function logout(projectRoot) {
742
+ const config = readSyncConfig(projectRoot);
743
+ deleteCredentials(projectRoot, config?.credentialPassphrase);
744
+
745
+ // Clear state but keep config
746
+ const syncDir = getSyncDir(projectRoot);
747
+ const statePath = path.join(syncDir, STATE_FILE);
748
+ if (fs.existsSync(statePath)) {
749
+ fs.unlinkSync(statePath);
750
+ }
751
+ }
752
+
753
+ module.exports = {
754
+ // Config & State
755
+ readSyncConfig,
756
+ writeSyncConfig,
757
+ readSyncState,
758
+ writeSyncState,
759
+ // File Discovery
760
+ getLocalFiles,
761
+ computeLocalHash,
762
+ // Diff
763
+ computeSyncDiff,
764
+ // Operations
765
+ push,
766
+ pull,
767
+ // Conflicts
768
+ listConflicts,
769
+ resolveConflict,
770
+ // Status & Setup
771
+ syncStatus,
772
+ setupSync,
773
+ logout,
774
+ };