@lifestreamdynamics/vault-cli 1.0.0

package/dist/sync/diff.js

@@ -0,0 +1,166 @@
+/**
+ * Compute the diff between local and remote state for a pull operation.
+ * Pull = download remote changes to local.
+ */
+export function computePullDiff(localFiles, remoteFiles, lastState) {
+    const downloads = [];
+    const deletes = [];
+    // Files on remote that need to be downloaded
+    for (const [docPath, remote] of Object.entries(remoteFiles)) {
+        const local = localFiles[docPath];
+        const lastRemote = lastState.remote[docPath];
+        if (!local) {
+            // File exists remotely but not locally
+            if (lastState.local[docPath]) {
+                // Was previously synced but deleted locally — remote wins on pull
+                downloads.push({
+                    path: docPath,
+                    action: 'create',
+                    direction: 'download',
+                    sizeBytes: remote.size,
+                    reason: 'Deleted locally, exists remotely (pull restores)',
+                });
+            }
+            else {
+                // New remote file
+                downloads.push({
+                    path: docPath,
+                    action: 'create',
+                    direction: 'download',
+                    sizeBytes: remote.size,
+                    reason: 'New remote file',
+                });
+            }
+        }
+        else if (lastRemote && remote.hash !== lastRemote.hash) {
+            // Remote file changed since last sync
+            downloads.push({
+                path: docPath,
+                action: 'update',
+                direction: 'download',
+                sizeBytes: remote.size,
+                reason: 'Remote file updated',
+            });
+        }
+        else if (!lastRemote && remote.hash !== local.hash) {
+            // First sync, files differ — remote wins on pull
+            downloads.push({
+                path: docPath,
+                action: 'update',
+                direction: 'download',
+                sizeBytes: remote.size,
+                reason: 'Content differs (first sync, pull prefers remote)',
+            });
+        }
+    }
+    // Files deleted from remote since last sync
+    for (const docPath of Object.keys(lastState.remote)) {
+        if (!remoteFiles[docPath] && localFiles[docPath]) {
+            deletes.push({
+                path: docPath,
+                action: 'delete',
+                direction: 'download',
+                sizeBytes: 0,
+                reason: 'Deleted from remote',
+            });
+        }
+    }
+    const totalBytes = downloads.reduce((sum, d) => sum + d.sizeBytes, 0);
+    return { uploads: [], downloads, deletes, totalBytes };
+}
+/**
+ * Compute the diff between local and remote state for a push operation.
+ * Push = upload local changes to remote.
+ */
+export function computePushDiff(localFiles, remoteFiles, lastState) {
+    const uploads = [];
+    const deletes = [];
+    // Files locally that need to be uploaded
+    for (const [docPath, local] of Object.entries(localFiles)) {
+        const remote = remoteFiles[docPath];
+        const lastLocal = lastState.local[docPath];
+        if (!remote) {
+            // File exists locally but not remotely
+            if (lastState.remote[docPath]) {
+                // Was previously synced but deleted remotely — local wins on push
+                uploads.push({
+                    path: docPath,
+                    action: 'create',
+                    direction: 'upload',
+                    sizeBytes: local.size,
+                    reason: 'Deleted remotely, exists locally (push restores)',
+                });
+            }
+            else {
+                // New local file
+                uploads.push({
+                    path: docPath,
+                    action: 'create',
+                    direction: 'upload',
+                    sizeBytes: local.size,
+                    reason: 'New local file',
+                });
+            }
+        }
+        else if (lastLocal && local.hash !== lastLocal.hash) {
+            // Local file changed since last sync
+            uploads.push({
+                path: docPath,
+                action: 'update',
+                direction: 'upload',
+                sizeBytes: local.size,
+                reason: 'Local file updated',
+            });
+        }
+        else if (!lastLocal && local.hash !== remote.hash) {
+            // First sync, files differ — local wins on push
+            uploads.push({
+                path: docPath,
+                action: 'update',
+                direction: 'upload',
+                sizeBytes: local.size,
+                reason: 'Content differs (first sync, push prefers local)',
+            });
+        }
+    }
+    // Files deleted locally since last sync
+    for (const docPath of Object.keys(lastState.local)) {
+        if (!localFiles[docPath] && remoteFiles[docPath]) {
+            deletes.push({
+                path: docPath,
+                action: 'delete',
+                direction: 'upload',
+                sizeBytes: 0,
+                reason: 'Deleted locally',
+            });
+        }
+    }
+    const totalBytes = uploads.reduce((sum, u) => sum + u.sizeBytes, 0);
+    return { uploads, downloads: [], deletes, totalBytes };
+}
+/**
+ * Format a diff for human-readable display.
+ */
+export function formatDiff(diff) {
+    const lines = [];
+    const allEntries = [...diff.downloads, ...diff.uploads, ...diff.deletes];
+    if (allEntries.length === 0) {
+        return 'Everything is up to date.';
+    }
+    for (const entry of diff.downloads) {
+        const symbol = entry.action === 'delete' ? '-' : entry.action === 'create' ? '+' : '~';
+        lines.push(`  ${symbol} ${entry.path} (${entry.reason})`);
+    }
+    for (const entry of diff.uploads) {
+        const symbol = entry.action === 'delete' ? '-' : entry.action === 'create' ? '+' : '~';
+        lines.push(`  ${symbol} ${entry.path} (${entry.reason})`);
+    }
+    for (const entry of diff.deletes) {
+        lines.push(`  - ${entry.path} (${entry.reason})`);
+    }
+    const totalFiles = allEntries.length;
+    const totalKB = Math.ceil(diff.totalBytes / 1024);
+    lines.push('');
+    lines.push(`${totalFiles} file(s), ${totalKB} KB to transfer`);
+    return lines.join('\n');
+}

package/dist/sync/engine.d.ts

@@ -0,0 +1,41 @@
+import type { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
+import type { SyncConfig, FileState } from './types.js';
+import { computePullDiff, computePushDiff, type SyncDiff, type SyncDiffEntry } from './diff.js';
+export interface SyncProgress {
+    phase: 'scanning' | 'computing' | 'transferring' | 'complete';
+    current: number;
+    total: number;
+    currentFile?: string;
+    bytesTransferred: number;
+    totalBytes: number;
+}
+export type ProgressCallback = (progress: SyncProgress) => void;
+export interface SyncResult {
+    filesUploaded: number;
+    filesDownloaded: number;
+    filesDeleted: number;
+    bytesTransferred: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Scan local directory recursively for .md files.
+ * Returns a map of relative doc paths -> FileState.
+ */
+export declare function scanLocalFiles(localPath: string, ignorePatterns: string[]): Record<string, FileState>;
+/**
+ * Scan remote vault for document list.
+ * Returns a map of doc paths -> FileState.
+ */
+export declare function scanRemoteFiles(client: LifestreamVaultClient, vaultId: string, ignorePatterns: string[]): Promise<Record<string, FileState>>;
+/**
+ * Execute a pull operation: download remote changes to local.
+ */
+export declare function executePull(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback): Promise<SyncResult>;
+/**
+ * Execute a push operation: upload local changes to remote.
+ */
+export declare function executePush(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback): Promise<SyncResult>;
+export { computePullDiff, computePushDiff, type SyncDiff, type SyncDiffEntry };

package/dist/sync/engine.js

@@ -0,0 +1,233 @@
+/**
+ * Core sync engine — performs pull and push operations.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from './state.js';
+import { updateLastSync } from './config.js';
+import { shouldIgnore } from './ignore.js';
+import { computePullDiff, computePushDiff } from './diff.js';
+/**
+ * Scan local directory recursively for .md files.
+ * Returns a map of relative doc paths -> FileState.
+ */
+export function scanLocalFiles(localPath, ignorePatterns) {
+    const files = {};
+    function walk(dir, prefix) {
+        if (!fs.existsSync(dir))
+            return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!shouldIgnore(relPath + '/', ignorePatterns)) {
+                    walk(path.join(dir, entry.name), relPath);
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                if (!shouldIgnore(relPath, ignorePatterns)) {
+                    const absPath = path.join(dir, entry.name);
+                    const content = fs.readFileSync(absPath);
+                    const stat = fs.statSync(absPath);
+                    files[relPath] = {
+                        path: relPath,
+                        hash: hashFileContent(content),
+                        mtime: stat.mtime.toISOString(),
+                        size: stat.size,
+                    };
+                }
+            }
+        }
+    }
+    walk(localPath, '');
+    return files;
+}
+/**
+ * Scan remote vault for document list.
+ * Returns a map of doc paths -> FileState.
+ */
+export async function scanRemoteFiles(client, vaultId, ignorePatterns) {
+    const docs = await client.documents.list(vaultId);
+    const files = {};
+    for (const doc of docs) {
+        if (!shouldIgnore(doc.path, ignorePatterns)) {
+            files[doc.path] = {
+                path: doc.path,
+                hash: '', // We don't have content hash from list; will use mtime for comparison
+                mtime: doc.fileModifiedAt,
+                size: doc.sizeBytes,
+            };
+        }
+    }
+    return files;
+}
+/**
+ * Write a file atomically using a temp file + rename.
+ * Prevents partial reads if the process is interrupted mid-write.
+ */
+function atomicWriteFileSync(targetPath, content, encoding = 'utf-8') {
+    const tmpFile = targetPath + '.tmp.' + randomBytes(4).toString('hex');
+    fs.writeFileSync(tmpFile, content, encoding);
+    fs.renameSync(tmpFile, targetPath);
+}
+/**
+ * Shared sync operation executor used by both pull and push.
+ * Handles result initialization, state loading, progress callbacks,
+ * quota error handling, state saving, and lastSync update.
+ */
+async function executeSyncOperation(config, diff, handlers, onProgress) {
+    const result = {
+        filesUploaded: 0,
+        filesDownloaded: 0,
+        filesDeleted: 0,
+        bytesTransferred: 0,
+        errors: [],
+    };
+    const state = loadSyncState(config.id);
+    const allOps = [...handlers.transfers, ...handlers.deletes];
+    let current = 0;
+    for (const entry of handlers.transfers) {
+        current++;
+        onProgress?.({
+            phase: 'transferring',
+            current,
+            total: allOps.length,
+            currentFile: entry.path,
+            bytesTransferred: result.bytesTransferred,
+            totalBytes: diff.totalBytes,
+        });
+        try {
+            const content = await handlers.transferFile(entry, config);
+            result[handlers.transferCounterKey]++;
+            result.bytesTransferred += entry.sizeBytes;
+            // Update state
+            state.local[entry.path] = {
+                path: entry.path,
+                hash: hashFileContent(content),
+                mtime: new Date().toISOString(),
+                size: Buffer.byteLength(content, 'utf-8'),
+            };
+            state.remote[entry.path] = buildRemoteFileState(entry.path, content, new Date().toISOString());
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (isQuotaError(message)) {
+                result.errors.push({ path: entry.path, error: message });
+                break; // Stop immediately on quota errors
+            }
+            result.errors.push({ path: entry.path, error: message });
+        }
+    }
+    for (const entry of handlers.deletes) {
+        current++;
+        onProgress?.({
+            phase: 'transferring',
+            current,
+            total: allOps.length,
+            currentFile: entry.path,
+            bytesTransferred: result.bytesTransferred,
+            totalBytes: diff.totalBytes,
+        });
+        try {
+            await handlers.deleteFile(entry, config);
+            result.filesDeleted++;
+            delete state.local[entry.path];
+            delete state.remote[entry.path];
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.errors.push({ path: entry.path, error: message });
+        }
+    }
+    saveSyncState(state);
+    updateLastSync(config.id);
+    onProgress?.({
+        phase: 'complete',
+        current: allOps.length,
+        total: allOps.length,
+        bytesTransferred: result.bytesTransferred,
+        totalBytes: diff.totalBytes,
+    });
+    return result;
+}
+/**
+ * Execute a pull operation: download remote changes to local.
+ */
+export async function executePull(client, config, diff, onProgress) {
+    return executeSyncOperation(config, diff, {
+        transfers: diff.downloads,
+        deletes: diff.deletes,
+        transferCounterKey: 'filesDownloaded',
+        async transferFile(entry, cfg) {
+            const { content } = await retryWithBackoff(() => client.documents.get(cfg.vaultId, entry.path));
+            const localFile = path.join(cfg.localPath, entry.path);
+            const localDir = path.dirname(localFile);
+            if (!fs.existsSync(localDir)) {
+                fs.mkdirSync(localDir, { recursive: true });
+            }
+            atomicWriteFileSync(localFile, content, 'utf-8');
+            return content;
+        },
+        async deleteFile(entry, cfg) {
+            const localFile = path.join(cfg.localPath, entry.path);
+            if (fs.existsSync(localFile)) {
+                fs.unlinkSync(localFile);
+            }
+        },
+    }, onProgress);
+}
+/**
+ * Execute a push operation: upload local changes to remote.
+ */
+export async function executePush(client, config, diff, onProgress) {
+    return executeSyncOperation(config, diff, {
+        transfers: diff.uploads,
+        deletes: diff.deletes,
+        transferCounterKey: 'filesUploaded',
+        async transferFile(entry, cfg) {
+            const localFile = path.join(cfg.localPath, entry.path);
+            const content = fs.readFileSync(localFile, 'utf-8');
+            await retryWithBackoff(() => client.documents.put(cfg.vaultId, entry.path, content));
+            return content;
+        },
+        async deleteFile(entry, cfg) {
+            await retryWithBackoff(() => client.documents.delete(cfg.vaultId, entry.path));
+        },
+    }, onProgress);
+}
+/**
+ * Retry a function with exponential backoff (max 3 retries).
+ */
+async function retryWithBackoff(fn, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            const message = err instanceof Error ? err.message : String(err);
+            // Don't retry on non-transient errors
+            if (isQuotaError(message) || isPermissionError(message)) {
+                throw err;
+            }
+            if (attempt < maxRetries) {
+                const delay = Math.pow(2, attempt) * 500; // 500ms, 1s, 2s
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+function isQuotaError(message) {
+    return /quota|storage limit|limit exceeded/i.test(message);
+}
+function isPermissionError(message) {
+    return /permission|forbidden|unauthorized|access denied/i.test(message);
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// Re-export diff functions for convenience
+export { computePullDiff, computePushDiff };

package/dist/sync/ignore.d.ts

@@ -0,0 +1,16 @@
+/** Default patterns that are always ignored. */
+export declare const DEFAULT_IGNORE_PATTERNS: string[];
+/**
+ * Load ignore patterns from a .lsvault-ignore file.
+ * Returns empty array if file doesn't exist.
+ */
+export declare function loadIgnoreFile(localPath: string): string[];
+/**
+ * Combine default patterns, config-level patterns, and .lsvault-ignore patterns.
+ */
+export declare function resolveIgnorePatterns(configIgnore: string[], localPath: string): string[];
+/**
+ * Check if a document path should be ignored.
+ * The docPath should be a relative path using forward slashes.
+ */
+export declare function shouldIgnore(docPath: string, patterns: string[]): boolean;

package/dist/sync/ignore.js

@@ -0,0 +1,72 @@
+/**
+ * Ignore pattern matching for sync operations.
+ * Supports .lsvault-ignore files and built-in default patterns.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { minimatch } from 'minimatch';
+/** Default patterns that are always ignored. */
+export const DEFAULT_IGNORE_PATTERNS = [
+    '.git/',
+    '.svn/',
+    '.hg/',
+    'node_modules/',
+    '*.tmp',
+    '.DS_Store',
+    'Thumbs.db',
+    '.lsvault/',
+    '.lsvault-*',
+];
+/**
+ * Load ignore patterns from a .lsvault-ignore file.
+ * Returns empty array if file doesn't exist.
+ */
+export function loadIgnoreFile(localPath) {
+    const ignoreFile = path.join(localPath, '.lsvault-ignore');
+    if (!fs.existsSync(ignoreFile))
+        return [];
+    try {
+        const content = fs.readFileSync(ignoreFile, 'utf-8');
+        return content
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line.length > 0 && !line.startsWith('#'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Combine default patterns, config-level patterns, and .lsvault-ignore patterns.
+ */
+export function resolveIgnorePatterns(configIgnore, localPath) {
+    const filePatterns = loadIgnoreFile(localPath);
+    // Deduplicate
+    const all = new Set([...DEFAULT_IGNORE_PATTERNS, ...configIgnore, ...filePatterns]);
+    return [...all];
+}
+/**
+ * Check if a document path should be ignored.
+ * The docPath should be a relative path using forward slashes.
+ */
+export function shouldIgnore(docPath, patterns) {
+    for (const pattern of patterns) {
+        // Directory patterns (ending with /)
+        if (pattern.endsWith('/')) {
+            const dirPattern = pattern.slice(0, -1);
+            if (docPath.startsWith(dirPattern + '/') || docPath === dirPattern) {
+                return true;
+            }
+        }
+        // Glob patterns
+        if (minimatch(docPath, pattern, { dot: true })) {
+            return true;
+        }
+        // Also check basename for file-level patterns (e.g., ".DS_Store" matches "sub/.DS_Store")
+        const basename = path.posix.basename(docPath);
+        if (minimatch(basename, pattern, { dot: true })) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/sync/remote-poller.d.ts

@@ -0,0 +1,23 @@
+import type { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
+import type { SyncConfig } from './types.js';
+export interface PollerOptions {
+    /** Patterns to ignore */
+    ignorePatterns: string[];
+    /** Poll interval in ms (default: 30000) */
+    intervalMs?: number;
+    /** Callback for log messages */
+    onLog?: (message: string) => void;
+    /** Callback for conflict log messages */
+    onConflictLog?: (message: string) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+    /** Callback when a file is written locally (for watcher loop prevention) */
+    onLocalWrite?: (docPath: string) => void;
+}
+/**
+ * Creates and starts a remote poller for a sync configuration.
+ * Returns a stop function.
+ */
+export declare function createRemotePoller(client: LifestreamVaultClient, config: SyncConfig, options: PollerOptions): {
+    stop: () => void;
+};