orgnote-api 0.41.35 → 0.41.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orgnote-api",
-  "version": "0.41.35",
+  "version": "0.41.36",
   "description": "Official API for creating extensions for OrgNote app",
   "type": "module",
   "main": "./index.js",

package/sync/__tests__/create-sync-plan.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/__tests__/create-sync-plan.spec.js

@@ -0,0 +1,55 @@
+import { expect, test, vi } from 'vitest';
+import { createMemorySyncState } from "../memory-state.js";
+import { createSyncPlan } from "../create-sync-plan.js";
+const createSyncApiMock = () => {
+    const syncChangesGet = vi.fn(async () => ({
+        data: {
+            data: {
+                changes: [],
+                hasMore: false,
+                serverTime: '2024-01-01T00:00:00Z',
+            },
+        },
+    }));
+    return { syncChangesGet };
+};
+const createFsMock = (entries, readFileImpl) => {
+    const readFile = vi.fn(readFileImpl);
+    return {
+        readDir: vi.fn(async () => entries),
+        readFile,
+    };
+};
+test('createSyncPlan falls back to original file when hash read fails', async () => {
+    const fs = createFsMock([{ name: 'a.org', path: '/a.org', type: 'file', size: 10, mtime: 10 }], async () => {
+        throw new Error('file locked');
+    });
+    const api = createSyncApiMock();
+    const state = createMemorySyncState();
+    const plan = await createSyncPlan({
+        fs,
+        api,
+        state,
+        rootPath: '/',
+        enableContentHashCheck: true,
+    });
+    expect(plan.toUpload).toHaveLength(1);
+    expect(plan.toUpload[0].path).toBe('/a.org');
+    expect(plan.toUpload[0].contentHash).toBeUndefined();
+});
+test('createSyncPlan skips hashing when enableContentHashCheck is false', async () => {
+    const fs = createFsMock([{ name: 'a.org', path: '/a.org', type: 'file', size: 10, mtime: 10 }], async () => {
+        throw new Error('must not be called');
+    });
+    const api = createSyncApiMock();
+    const state = createMemorySyncState();
+    const plan = await createSyncPlan({
+        fs,
+        api,
+        state,
+        rootPath: '/',
+        enableContentHashCheck: false,
+    });
+    expect(plan.toUpload).toHaveLength(1);
+    expect(fs.readFile).toHaveBeenCalledTimes(0);
+});

package/sync/__tests__/fetch.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/__tests__/fetch.spec.js

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest';
+import { fetchRemoteChanges } from "../fetch.js";
+test('fetchRemoteChanges maps contentHash from API changes', async () => {
+    const api = {
+        syncChangesGet: async () => ({
+            data: {
+                data: {
+                    changes: [
+                        {
+                            id: '1',
+                            path: '/a.org',
+                            version: 1,
+                            deleted: false,
+                            updatedAt: '2024-01-01T00:00:00Z',
+                            contentHash: 'hash-1',
+                        },
+                    ],
+                    hasMore: false,
+                    serverTime: '2024-01-01T00:00:00Z',
+                },
+            },
+        }),
+    };
+    const result = await fetchRemoteChanges(api);
+    expect(result.files).toHaveLength(1);
+    expect(result.files[0].contentHash).toBe('hash-1');
+});

package/sync/__tests__/plan.spec.js

@@ -4,7 +4,13 @@ const emptyState = { files: {} };
 const serverTime = '2024-01-01T00:00:00Z';
 test('new local file → upload', () => {
     const localFiles = [{ path: 'a.org', mtime: 1000, size: 100 }];
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles: [], stateData: emptyState, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData: emptyState,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(1);
     expect(plan.toUpload[0].path).toBe('a.org');
 });
@@ -12,7 +18,13 @@ test('new remote file → download', () => {
     const remoteFiles = [
         { path: 'b.org', version: 1, deleted: false, updatedAt: '' },
     ];
-    const plan = createPlan({ localFiles: [], deletedLocally: [], remoteFiles, stateData: emptyState, serverTime });
+    const plan = createPlan({
+        localFiles: [],
+        deletedLocally: [],
+        remoteFiles,
+        stateData: emptyState,
+        serverTime,
+    });
     expect(plan.toDownload).toHaveLength(1);
     expect(plan.toDownload[0].path).toBe('b.org');
 });
@@ -22,9 +34,17 @@ test('unchanged file → skip', () => {
         { path: 'c.org', version: 1, deleted: false, updatedAt: '' },
     ];
     const stateData = {
-        files: { 'c.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'c.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(0);
     expect(plan.toDownload).toHaveLength(0);
 });
@@ -34,9 +54,17 @@ test('local changed → upload', () => {
         { path: 'd.org', version: 1, deleted: false, updatedAt: '' },
     ];
     const stateData = {
-        files: { 'd.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'd.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(1);
 });
 test('remote changed → download', () => {
@@ -45,29 +73,58 @@ test('remote changed → download', () => {
         { path: 'e.org', version: 2, deleted: false, updatedAt: '' },
     ];
     const stateData = {
-        files: { 'e.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'e.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toDownload).toHaveLength(1);
 });
 test('both changed → upload (conflict handled by server)', () => {
     const localFiles = [{ path: 'f.org', mtime: 3000, size: 100 }];
     const remoteFiles = [
-        { path: 'f.org', version: 2, deleted: false, updatedAt: '1970-01-01T00:00:02.000Z' },
+        {
+            path: 'f.org',
+            version: 2,
+            deleted: false,
+            updatedAt: '1970-01-01T00:00:02.000Z',
+        },
     ];
     const stateData = {
-        files: { 'f.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'f.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(1);
     expect(plan.toDownload).toHaveLength(0);
 });
 test('deleted locally → delete remote', () => {
     const deletedLocally = ['g.org'];
     const stateData = {
-        files: { 'g.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'g.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles: [], deletedLocally, remoteFiles: [], stateData, serverTime });
+    const plan = createPlan({
+        localFiles: [],
+        deletedLocally,
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
     expect(plan.toDeleteRemote).toContain('g.org');
 });
 test('deleted remotely → delete local', () => {
@@ -76,9 +133,17 @@ test('deleted remotely → delete local', () => {
         { path: 'h.org', version: 2, deleted: true, updatedAt: '' },
     ];
     const stateData = {
-        files: { 'h.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'h.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toDeleteLocal).toContain('h.org');
 });
 test('deleted locally but modified remotely → download', () => {
@@ -87,30 +152,183 @@ test('deleted locally but modified remotely → download', () => {
         { path: 'i.org', version: 2, deleted: false, updatedAt: '' },
     ];
     const stateData = {
-        files: { 'i.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'i.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles: [], deletedLocally, remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles: [],
+        deletedLocally,
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toDownload).toHaveLength(1);
     expect(plan.toDeleteRemote).toHaveLength(0);
 });
 test('deleted remotely but modified locally → upload (local changes win)', () => {
     const localFiles = [{ path: 'j.org', mtime: 3000, size: 100 }];
     const remoteFiles = [
-        { path: 'j.org', version: 2, deleted: true, updatedAt: '1970-01-01T00:00:02.000Z' },
+        {
+            path: 'j.org',
+            version: 2,
+            deleted: true,
+            updatedAt: '1970-01-01T00:00:02.000Z',
+        },
     ];
     const stateData = {
-        files: { 'j.org': { mtime: 1000, size: 100, version: 1, status: 'synced' } },
+        files: {
+            'j.org': { mtime: 1000, size: 100, version: 1, status: 'synced' },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles, stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(1);
     expect(plan.toDeleteLocal).toHaveLength(0);
 });
 test('file with error status → retry upload', () => {
     const localFiles = [{ path: 'k.org', mtime: 1000, size: 100 }];
     const stateData = {
-        files: { 'k.org': { mtime: 1000, size: 100, version: 1, status: 'error', errorMessage: 'some error' } },
+        files: {
+            'k.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'error',
+                errorMessage: 'some error',
+            },
+        },
     };
-    const plan = createPlan({ localFiles, deletedLocally: [], remoteFiles: [], stateData, serverTime });
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
     expect(plan.toUpload).toHaveLength(1);
     expect(plan.toUpload[0].path).toBe('k.org');
 });
+test('mtime changed but same contentHash → skip upload', () => {
+    const localFiles = [
+        { path: 'l.org', mtime: 2000, size: 100, contentHash: 'same-hash' },
+    ];
+    const stateData = {
+        files: {
+            'l.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'synced',
+                contentHash: 'same-hash',
+            },
+        },
+    };
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
+    expect(plan.toUpload).toHaveLength(0);
+});
+test('mtime same but different contentHash → upload', () => {
+    const localFiles = [
+        { path: 'm.org', mtime: 1000, size: 100, contentHash: 'new-hash' },
+    ];
+    const stateData = {
+        files: {
+            'm.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'synced',
+                contentHash: 'old-hash',
+            },
+        },
+    };
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
+    expect(plan.toUpload).toHaveLength(1);
+    expect(plan.toUpload[0].path).toBe('m.org');
+});
+test('both hashes missing → fallback to mtime', () => {
+    const localFiles = [{ path: 'n.org', mtime: 2000, size: 100 }];
+    const stateData = {
+        files: {
+            'n.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'synced',
+            },
+        },
+    };
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
+    expect(plan.toUpload).toHaveLength(1);
+    expect(plan.toUpload[0].path).toBe('n.org');
+});
+test('local hash present and stored hash absent → fallback to mtime', () => {
+    const localFiles = [
+        { path: 'o.org', mtime: 1000, size: 100, contentHash: 'new-hash' },
+    ];
+    const stateData = {
+        files: {
+            'o.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'synced',
+            },
+        },
+    };
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
+    expect(plan.toUpload).toHaveLength(0);
+});
+test('local hash present, stored hash absent, different mtime → upload', () => {
+    const localFiles = [
+        { path: 'p.org', mtime: 2000, size: 100, contentHash: 'some-hash' },
+    ];
+    const stateData = {
+        files: {
+            'p.org': {
+                mtime: 1000,
+                size: 100,
+                version: 1,
+                status: 'synced',
+            },
+        },
+    };
+    const plan = createPlan({
+        localFiles,
+        deletedLocally: [],
+        remoteFiles: [],
+        stateData,
+        serverTime,
+    });
+    expect(plan.toUpload).toHaveLength(1);
+    expect(plan.toUpload[0].path).toBe('p.org');
+});

package/sync/create-sync-plan.js

@@ -2,12 +2,32 @@ import { scanLocalFiles, findDeletedLocally } from "./scan.js";
 import { fetchRemoteChanges } from "./fetch.js";
 import { createPlan } from "./plan.js";
 import { getOldestSyncedAt } from "./utils/oldest-synced-at.js";
+import { hashContent } from "./utils/content-hash.js";
+const enrichLocalFilesWithHash = async (fs, localFiles) => {
+    const hashResults = await Promise.allSettled(localFiles.map(async (file) => {
+        const content = await fs.readFile(file.path, 'binary');
+        return {
+            ...file,
+            contentHash: await hashContent(content),
+        };
+    }));
+    return hashResults.map((result, index) => result.status === 'fulfilled' ? result.value : localFiles[index]);
+};
 export async function createSyncPlan(params) {
-    const { fs, api, state, rootPath, ignorePatterns } = params;
+    const { fs, api, state, rootPath, ignorePatterns, enableContentHashCheck } = params;
     const stateData = await state.get();
     const localFiles = await scanLocalFiles(fs, rootPath, ignorePatterns);
-    const deletedLocally = findDeletedLocally(localFiles, stateData);
+    const localFilesWithHashes = enableContentHashCheck
+        ? await enrichLocalFilesWithHash(fs, localFiles)
+        : localFiles;
+    const deletedLocally = findDeletedLocally(localFilesWithHashes, stateData);
     const since = getOldestSyncedAt(stateData);
     const { files: remoteFiles, serverTime } = await fetchRemoteChanges(api, since);
-    return createPlan({ localFiles, deletedLocally, remoteFiles, stateData, serverTime });
+    return createPlan({
+        localFiles: localFilesWithHashes,
+        deletedLocally,
+        remoteFiles,
+        stateData,
+        serverTime,
+    });
 }

package/sync/fetch.js

@@ -29,4 +29,5 @@ const toRemoteFile = (change) => ({
     version: change.version,
     deleted: change.deleted,
     updatedAt: change.updatedAt,
+    contentHash: change.contentHash,
 });

package/sync/index.d.ts

@@ -5,6 +5,7 @@ export { scanLocalFiles, findDeletedLocally } from './scan.js';
 export { fetchRemoteChanges } from './fetch.js';
 export { recoverState } from './recovery.js';
 export { getOldestSyncedAt } from './utils/oldest-synced-at.js';
+export { hashContent, hashBytes } from './utils/content-hash.js';
 export { processUpload, processDownload, processDeleteLocal, processDeleteRemote, handleConflict, generateConflictPath, hasConflict, } from './operations/index.js';
 export { SyncOperationType } from './types.js';
 export type { SyncState, SyncStateData, SyncedFile, SyncStatus, LocalFile, RemoteFile, UploadResult, SyncPlan, SyncTask, SyncExecutor, SyncContext, CreateSyncPlanParams, } from './types.js';

package/sync/index.js

@@ -5,5 +5,6 @@ export { scanLocalFiles, findDeletedLocally } from "./scan.js";
 export { fetchRemoteChanges } from "./fetch.js";
 export { recoverState } from "./recovery.js";
 export { getOldestSyncedAt } from "./utils/oldest-synced-at.js";
+export { hashContent, hashBytes } from "./utils/content-hash.js";
 export { processUpload, processDownload, processDeleteLocal, processDeleteRemote, handleConflict, generateConflictPath, hasConflict, } from "./operations/index.js";
 export { SyncOperationType } from "./types.js";

package/sync/operations/__tests__/conflict.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/operations/__tests__/conflict.spec.js

@@ -0,0 +1,62 @@
+import { expect, test, vi } from 'vitest';
+import { AxiosError } from 'axios';
+import { ErrorFileNotFound } from "../../../models/file-system.js";
+import { handleConflict } from "../conflict.js";
+import { createContext, SHA256_OF_ABC } from "./fixtures.js";
+test('handleConflict stores computed contentHash after server download', async () => {
+    const fs = {
+        copyFile: vi.fn(async () => undefined),
+        fileInfo: vi.fn(async () => ({ mtime: 100, size: 3 })),
+        readFile: vi.fn(async () => new TextEncoder().encode('abc')),
+    };
+    const executor = {
+        download: vi.fn(async () => undefined),
+    };
+    const ctx = createContext({ fs, executor, deviceName: 'dev' });
+    await handleConflict('/c.org', { status: 'conflict', serverVersion: 7 }, ctx);
+    const stored = await ctx.state.getFile('/c.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.version).toBe(7);
+    expect(stored?.contentHash).toBe(SHA256_OF_ABC);
+    expect(stored?.conflictPath).toContain('.sync-conflict-');
+});
+test('handleConflict removes local file and state when server version is missing', async () => {
+    const fs = {
+        copyFile: vi.fn(async () => undefined),
+        deleteFile: vi.fn(async () => undefined),
+    };
+    const notFoundResponse = {
+        status: 404,
+        statusText: 'Not Found',
+        headers: {},
+        config: {},
+        data: {},
+    };
+    const executor = {
+        download: vi.fn(async () => {
+            throw new AxiosError('Not Found', 'ERR_BAD_REQUEST', undefined, undefined, notFoundResponse);
+        }),
+    };
+    const ctx = createContext({ fs, executor, deviceName: 'dev' });
+    await handleConflict('/missing.org', { status: 'conflict', serverVersion: 7 }, ctx);
+    const stored = await ctx.state.getFile('/missing.org');
+    expect(fs.deleteFile).toHaveBeenCalledWith('/missing.org');
+    expect(stored).toBeNull();
+});
+test('handleConflict stores undefined contentHash when read fails with ErrorFileNotFound', async () => {
+    const fs = {
+        copyFile: vi.fn(async () => undefined),
+        fileInfo: vi.fn(async () => ({ mtime: 100, size: 3 })),
+        readFile: vi.fn(async () => {
+            throw new ErrorFileNotFound('/c.org');
+        }),
+    };
+    const executor = {
+        download: vi.fn(async () => undefined),
+    };
+    const ctx = createContext({ fs, executor, deviceName: 'dev' });
+    await handleConflict('/c.org', { status: 'conflict', serverVersion: 7 }, ctx);
+    const stored = await ctx.state.getFile('/c.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.contentHash).toBeUndefined();
+});

package/sync/operations/__tests__/content-hash.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/operations/__tests__/content-hash.spec.js

@@ -0,0 +1,37 @@
+import { expect, test, vi } from 'vitest';
+import { ErrorFileNotFound } from "../../../models/file-system.js";
+import { resolveContentHash } from "../content-hash.js";
+import { SHA256_OF_ABC } from "./fixtures.js";
+test('resolveContentHash returns preferredHash without reading file', async () => {
+    const fs = {
+        readFile: vi.fn(async () => new TextEncoder().encode('abc')),
+    };
+    const result = await resolveContentHash(fs, '/a.org', 'remote-hash');
+    expect(result).toBe('remote-hash');
+    expect(fs.readFile).toHaveBeenCalledTimes(0);
+});
+test('resolveContentHash computes hash when preferredHash is absent', async () => {
+    const fs = {
+        readFile: vi.fn(async () => new TextEncoder().encode('abc')),
+    };
+    const result = await resolveContentHash(fs, '/a.org');
+    expect(result).toBe(SHA256_OF_ABC);
+    expect(fs.readFile).toHaveBeenCalledTimes(1);
+});
+test('resolveContentHash returns undefined for ErrorFileNotFound', async () => {
+    const fs = {
+        readFile: vi.fn(async () => {
+            throw new ErrorFileNotFound('/missing.org');
+        }),
+    };
+    const result = await resolveContentHash(fs, '/missing.org');
+    expect(result).toBeUndefined();
+});
+test('resolveContentHash rethrows unexpected errors', async () => {
+    const fs = {
+        readFile: vi.fn(async () => {
+            throw new Error('permission denied');
+        }),
+    };
+    await expect(resolveContentHash(fs, '/a.org')).rejects.toThrow('permission denied');
+});

package/sync/operations/__tests__/download.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/operations/__tests__/download.spec.js

@@ -0,0 +1,69 @@
+import { expect, test, vi } from 'vitest';
+import { processDownload } from "../download.js";
+import { createContext, SHA256_OF_ABC } from "./fixtures.js";
+test('processDownload stores remote contentHash when provided', async () => {
+    const fs = {
+        fileInfo: vi.fn(async () => ({ mtime: 42, size: 10 })),
+        readFile: vi.fn(async () => {
+            throw new Error('must not be called');
+        }),
+    };
+    const executor = {
+        download: vi.fn(async () => undefined),
+    };
+    const ctx = createContext({ fs, executor });
+    const file = {
+        path: '/a.org',
+        version: 2,
+        deleted: false,
+        updatedAt: '2024-01-01T00:00:00Z',
+        contentHash: 'remote-hash',
+    };
+    await processDownload(file, ctx);
+    const stored = await ctx.state.getFile('/a.org');
+    expect(stored?.contentHash).toBe('remote-hash');
+    expect(fs.readFile).toHaveBeenCalledTimes(0);
+});
+test('processDownload computes contentHash when remote hash is absent', async () => {
+    const fs = {
+        fileInfo: vi.fn(async () => ({ mtime: 42, size: 10 })),
+        readFile: vi.fn(async () => new TextEncoder().encode('abc')),
+    };
+    const executor = {
+        download: vi.fn(async () => undefined),
+    };
+    const ctx = createContext({ fs, executor });
+    const file = {
+        path: '/b.org',
+        version: 3,
+        deleted: false,
+        updatedAt: '2024-01-01T00:00:00Z',
+    };
+    await processDownload(file, ctx);
+    const stored = await ctx.state.getFile('/b.org');
+    expect(stored?.contentHash).toBe(SHA256_OF_ABC);
+    expect(fs.readFile).toHaveBeenCalledTimes(1);
+});
+test('processDownload stores error status and rethrows when download fails', async () => {
+    const fs = {
+        fileInfo: vi.fn(async () => ({ mtime: 42, size: 10 })),
+        readFile: vi.fn(async () => new TextEncoder().encode('abc')),
+    };
+    const downloadError = new Error('network');
+    const executor = {
+        download: vi.fn(async () => {
+            throw downloadError;
+        }),
+    };
+    const ctx = createContext({ fs, executor });
+    const file = {
+        path: '/d.org',
+        version: 3,
+        deleted: false,
+        updatedAt: '2024-01-01T00:00:00Z',
+    };
+    await expect(processDownload(file, ctx)).rejects.toThrow('network');
+    const stored = await ctx.state.getFile('/d.org');
+    expect(stored?.status).toBe('error');
+    expect(stored?.errorMessage).toContain('network');
+});

package/sync/operations/__tests__/fixtures.d.ts

@@ -0,0 +1,10 @@
+import type { FileSystem } from '../../../models/file-system.js';
+import type { SyncContext, SyncExecutor } from '../../types.js';
+export declare const SHA256_OF_ABC = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad";
+interface CreateContextParams {
+    fs: FileSystem;
+    executor: SyncExecutor;
+    deviceName?: string;
+}
+export declare const createContext: ({ fs, executor, deviceName, }: CreateContextParams) => SyncContext;
+export {};

package/sync/operations/__tests__/fixtures.js

@@ -0,0 +1,9 @@
+import { createMemorySyncState } from "../../memory-state.js";
+export const SHA256_OF_ABC = 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad';
+export const createContext = ({ fs, executor, deviceName, }) => ({
+    fs,
+    executor,
+    state: createMemorySyncState(),
+    serverTime: '2024-01-01T00:00:00Z',
+    deviceName,
+});

package/sync/operations/__tests__/synced-file.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/operations/__tests__/synced-file.spec.js

@@ -0,0 +1,10 @@
+import { expect, test } from 'vitest';
+import { createSyncedFile } from "../synced-file.js";
+test('createSyncedFile preserves contentHash from metadata', () => {
+    const result = createSyncedFile({ mtime: 1, size: 2, contentHash: 'abc' }, { status: 'synced' });
+    expect(result.contentHash).toBe('abc');
+});
+test('createSyncedFile keeps contentHash undefined when absent', () => {
+    const result = createSyncedFile({ mtime: 1, size: 2 }, { status: 'synced' });
+    expect(result.contentHash).toBeUndefined();
+});

package/sync/operations/conflict.js

@@ -1,4 +1,6 @@
 import { createSyncedFile } from "./synced-file.js";
+import { resolveContentHash } from "./content-hash.js";
+import axios from 'axios';
 export const generateConflictPath = (path, deviceName = 'device') => {
     const lastDot = path.lastIndexOf('.');
     const ext = lastDot >= 0 ? path.substring(lastDot) : '';
@@ -15,10 +17,7 @@ const copyFile = async (fs, src, dest) => {
     await fs.writeFile(dest, content);
 };
 const isNotFoundError = (error) => {
-    if (typeof error !== 'object' || error === null)
-        return false;
-    const axiosError = error;
-    return axiosError.response?.status === 404;
+    return axios.isAxiosError(error) && error.response?.status === 404;
 };
 const tryDownloadServerVersion = async (path, serverVersion, ctx) => {
     try {
@@ -46,7 +45,12 @@ export const handleConflict = async (path, conflictResult, ctx) => {
         return;
     }
     const fileInfo = await ctx.fs.fileInfo(path);
-    const meta = { mtime: fileInfo?.mtime ?? 0, size: fileInfo?.size ?? 0 };
+    const contentHash = await resolveContentHash(ctx.fs, path);
+    const meta = {
+        mtime: fileInfo?.mtime ?? 0,
+        size: fileInfo?.size ?? 0,
+        contentHash,
+    };
     await ctx.state.setFile(path, createSyncedFile(meta, {
         version: conflictResult.serverVersion,
         status: 'synced',

package/sync/operations/content-hash.d.ts

@@ -0,0 +1,2 @@
+import { type FileSystem } from '../../models/file-system.js';
+export declare const resolveContentHash: (fs: FileSystem, path: string, preferredHash?: string) => Promise<string | undefined>;

package/sync/operations/content-hash.js

@@ -0,0 +1,17 @@
+import { ErrorFileNotFound } from "../../models/file-system.js";
+import { hashContent } from "../utils/content-hash.js";
+export const resolveContentHash = async (fs, path, preferredHash) => {
+    if (preferredHash !== undefined) {
+        return preferredHash;
+    }
+    try {
+        const content = await fs.readFile(path, 'binary');
+        return hashContent(content);
+    }
+    catch (error) {
+        if (error instanceof ErrorFileNotFound) {
+            return undefined;
+        }
+        throw error;
+    }
+};

package/sync/operations/download.js

@@ -1,20 +1,48 @@
 import { createSyncedFile } from "./synced-file.js";
+import { resolveContentHash } from "./content-hash.js";
 const storedMeta = (stored) => ({
     mtime: stored?.mtime ?? 0,
     size: stored?.size ?? 0,
 });
+const markDownloading = async (file, stored, ctx) => {
+    await ctx.state.setFile(file.path, createSyncedFile(storedMeta(stored), {
+        version: stored?.version,
+        status: 'downloading',
+    }));
+};
+const resolveDownloadedMeta = async (file, ctx) => {
+    const fileInfo = await ctx.fs.fileInfo(file.path);
+    const contentHash = await resolveContentHash(ctx.fs, file.path, file.contentHash);
+    return {
+        mtime: fileInfo?.mtime ?? 0,
+        size: fileInfo?.size ?? 0,
+        contentHash,
+    };
+};
+const markSynced = async (file, meta, ctx) => {
+    await ctx.state.setFile(file.path, createSyncedFile(meta, {
+        version: file.version,
+        status: 'synced',
+        syncedAt: ctx.serverTime,
+    }));
+};
+const markError = async (file, stored, error, ctx) => {
+    await ctx.state.setFile(file.path, createSyncedFile(storedMeta(stored), {
+        version: stored?.version,
+        status: 'error',
+        errorMessage: String(error),
+    }));
+};
 export const processDownload = async (file, ctx) => {
     const stored = await ctx.state.getFile(file.path);
-    const meta = storedMeta(stored);
-    await ctx.state.setFile(file.path, createSyncedFile(meta, { version: stored?.version, status: 'downloading' }));
+    await markDownloading(file, stored, ctx);
     try {
         await ctx.executor.download(file);
-        const fileInfo = await ctx.fs.fileInfo(file.path);
-        const downloadedMeta = { mtime: fileInfo?.mtime ?? 0, size: fileInfo?.size ?? 0 };
-        await ctx.state.setFile(file.path, createSyncedFile(downloadedMeta, { version: file.version, status: 'synced', syncedAt: ctx.serverTime }));
+        const downloadedMeta = await resolveDownloadedMeta(file, ctx);
+        await markSynced(file, downloadedMeta, ctx);
     }
     catch (error) {
-        await ctx.state.setFile(file.path, createSyncedFile(meta, { version: stored?.version, status: 'error', errorMessage: String(error) }));
+        await markError(file, stored, error, ctx);
         throw error;
     }
 };

package/sync/operations/synced-file.d.ts

@@ -2,6 +2,7 @@ import type { SyncedFile, SyncStatus } from '../types.js';
 interface FileMeta {
     mtime: number;
     size: number;
+    contentHash?: string;
 }
 export interface SyncedFileOptions {
     version?: number;

package/sync/operations/synced-file.js

@@ -1,5 +1,6 @@
 export const createSyncedFile = (meta, options) => ({
     mtime: meta.mtime,
     size: meta.size,
+    contentHash: meta.contentHash,
     ...options,
 });

package/sync/plan.js

@@ -1,25 +1,43 @@
 import { SyncOperationType } from "./types.js";
 export const createPlan = ({ localFiles, deletedLocally, remoteFiles, stateData, serverTime, }) => {
     const index = buildFileIndex(localFiles, deletedLocally, remoteFiles);
-    const localActions = localFiles.map(local => resolveLocalFile(local, index.remoteByPath.get(local.path), stateData.files[local.path]));
-    const deletedActions = deletedLocally.map(path => resolveDeletedLocally(path, index.remoteByPath.get(path), stateData.files[path]));
+    const localActions = localFiles.map((local) => resolveLocalFile(local, index.remoteByPath.get(local.path), stateData.files[local.path]));
+    const deletedActions = deletedLocally.map((path) => resolveDeletedLocally(path, index.remoteByPath.get(path), stateData.files[path]));
     const remoteActions = remoteFiles
-        .filter(remote => isNewRemote(remote, index))
+        .filter((remote) => isNewRemote(remote, index))
         .map(resolveNewRemote);
     return buildPlanFromActions([...localActions, ...deletedActions, ...remoteActions], serverTime);
 };
 const buildFileIndex = (localFiles, deletedLocally, remoteFiles) => ({
-    remoteByPath: new Map(remoteFiles.map(f => [f.path, f])),
-    localByPath: new Map(localFiles.map(f => [f.path, f])),
+    remoteByPath: new Map(remoteFiles.map((f) => [f.path, f])),
+    localByPath: new Map(localFiles.map((f) => [f.path, f])),
     deletedSet: new Set(deletedLocally),
 });
 const isNewRemote = (remote, index) => !index.localByPath.has(remote.path) && !index.deletedSet.has(remote.path);
-const buildPlanFromActions = (actions, serverTime) => actions.reduce((plan, action) => applyAction(plan, action), { toUpload: [], toDownload: [], toDeleteLocal: [], toDeleteRemote: [], serverTime });
+const buildPlanFromActions = (actions, serverTime) => actions.reduce((plan, action) => applyAction(plan, action), {
+    toUpload: [],
+    toDownload: [],
+    toDeleteLocal: [],
+    toDeleteRemote: [],
+    serverTime,
+});
 const actionHandlers = {
-    [SyncOperationType.Upload]: (plan, action) => ({ ...plan, toUpload: [...plan.toUpload, action.file] }),
-    [SyncOperationType.Download]: (plan, action) => ({ ...plan, toDownload: [...plan.toDownload, action.file] }),
-    [SyncOperationType.DeleteLocal]: (plan, action) => ({ ...plan, toDeleteLocal: [...plan.toDeleteLocal, action.path] }),
-    [SyncOperationType.DeleteRemote]: (plan, action) => ({ ...plan, toDeleteRemote: [...plan.toDeleteRemote, action.path] }),
+    [SyncOperationType.Upload]: (plan, action) => ({
+        ...plan,
+        toUpload: [...plan.toUpload, action.file],
+    }),
+    [SyncOperationType.Download]: (plan, action) => ({
+        ...plan,
+        toDownload: [...plan.toDownload, action.file],
+    }),
+    [SyncOperationType.DeleteLocal]: (plan, action) => ({
+        ...plan,
+        toDeleteLocal: [...plan.toDeleteLocal, action.path],
+    }),
+    [SyncOperationType.DeleteRemote]: (plan, action) => ({
+        ...plan,
+        toDeleteRemote: [...plan.toDeleteRemote, action.path],
+    }),
     none: (plan) => plan,
 };
 const applyAction = (plan, action) => actionHandlers[action.type](plan, action);
@@ -45,13 +63,31 @@ const resolveDeletedLocally = (path, remote, stored) => {
     if (!remote || remote.deleted) {
         return deleteRemote(path);
     }
-    return isRemoteChanged(remote, stored) ? download(remote) : deleteRemote(path);
+    return isRemoteChanged(remote, stored)
+        ? download(remote)
+        : deleteRemote(path);
 };
 const resolveNewRemote = (remote) => remote.deleted ? none() : download(remote);
-const isLocalChanged = (local, stored) => !stored || local.mtime !== stored.mtime || stored.status === 'error';
+const isLocalChanged = (local, stored) => !stored ||
+    stored.status === 'error' ||
+    (local.contentHash && stored.contentHash
+        ? local.contentHash !== stored.contentHash
+        : local.mtime !== stored.mtime);
 const isRemoteChanged = (remote, stored) => !stored || remote.version > (stored.version ?? 0);
-const upload = (file) => ({ type: SyncOperationType.Upload, file });
-const download = (file) => ({ type: SyncOperationType.Download, file });
-const deleteLocal = (path) => ({ type: SyncOperationType.DeleteLocal, path });
-const deleteRemote = (path) => ({ type: SyncOperationType.DeleteRemote, path });
+const upload = (file) => ({
+    type: SyncOperationType.Upload,
+    file,
+});
+const download = (file) => ({
+    type: SyncOperationType.Download,
+    file,
+});
+const deleteLocal = (path) => ({
+    type: SyncOperationType.DeleteLocal,
+    path,
+});
+const deleteRemote = (path) => ({
+    type: SyncOperationType.DeleteRemote,
+    path,
+});
 const none = () => ({ type: 'none' });

package/sync/types.d.ts

@@ -11,6 +11,7 @@ export declare enum SyncOperationType {
 export interface SyncedFile {
     mtime: number;
     size: number;
+    contentHash?: string;
     version?: number;
     status: SyncStatus;
     syncedAt?: string;
@@ -31,8 +32,9 @@ export interface LocalFile {
     path: string;
     mtime: number;
     size: number;
+    contentHash?: string;
 }
-export type RemoteFile = Pick<FileChange, 'path' | 'version' | 'deleted' | 'updatedAt'>;
+export type RemoteFile = Pick<FileChange, 'path' | 'version' | 'deleted' | 'updatedAt' | 'contentHash'>;
 export type UploadResult = {
     status: 'ok';
     version: number;
@@ -64,6 +66,7 @@ export interface CreateSyncPlanParams {
     state: SyncState;
     rootPath: string;
     ignorePatterns?: string[];
+    enableContentHashCheck?: boolean;
 }
 export interface SyncContext {
     executor: SyncExecutor;

package/sync/utils/__tests__/content-hash.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/sync/utils/__tests__/content-hash.spec.js

@@ -0,0 +1,38 @@
+import { expect, test } from 'vitest';
+import { hashBytes, hashContent } from "../content-hash.js";
+const toBytes = (value) => new TextEncoder().encode(value);
+test('hashContent returns deterministic SHA-256 digest', async () => {
+    const digest = await hashContent(toBytes('abc'));
+    expect(digest).toMatchInlineSnapshot('"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"');
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+});
+test('hashContent returns the same digest for the same content', async () => {
+    const content = toBytes('orgnote');
+    const first = await hashContent(content);
+    const second = await hashContent(content);
+    expect(first).toBe(second);
+});
+test('hashContent returns different digests for different content', async () => {
+    const first = await hashContent(toBytes('orgnote-a'));
+    const second = await hashContent(toBytes('orgnote-b'));
+    expect(first).not.toBe(second);
+});
+test('hashBytes is an alias of hashContent', async () => {
+    const content = toBytes('alias-check');
+    const first = await hashContent(content);
+    const second = await hashBytes(content);
+    expect(first).toBe(second);
+});
+test('hashContent handles long text deterministically', async () => {
+    const content = toBytes('orgnote-long-text-'.repeat(2000));
+    const first = await hashContent(content);
+    const second = await hashContent(content);
+    expect(first).toBe(second);
+    expect(first).toMatch(/^[0-9a-f]{64}$/);
+});
+test('hashContent handles binary bytes', async () => {
+    const bytes = new Uint8Array([0, 255, 1, 128, 64, 32, 16, 8, 4, 2, 1, 0]);
+    const digest = await hashContent(bytes);
+    expect(digest).toMatchInlineSnapshot('"c7e3c80490776a8af2e44e522fd67583434ab733dfa0488f535ebe6db5bd7f34"');
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+});

package/sync/utils/content-hash.d.ts

@@ -0,0 +1,2 @@
+export declare const hashContent: (content: Uint8Array) => Promise<string>;
+export declare const hashBytes: (content: Uint8Array) => Promise<string>;

package/sync/utils/content-hash.js

@@ -0,0 +1,23 @@
+const bytesToHex = (bytes) => {
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+};
+let subtleCrypto = null;
+const getSubtleCrypto = () => {
+    if (subtleCrypto) {
+        return subtleCrypto;
+    }
+    if (!globalThis.crypto?.subtle) {
+        throw new Error('Web Crypto API is not available');
+    }
+    subtleCrypto = globalThis.crypto.subtle;
+    return subtleCrypto;
+};
+export const hashContent = async (content) => {
+    const digest = await getSubtleCrypto().digest('SHA-256', content);
+    return bytesToHex(new Uint8Array(digest));
+};
+export const hashBytes = hashContent;