orgnote-api 0.41.50 → 0.42.0

package/models/widget.d.ts

@@ -33,6 +33,8 @@ export interface CommonEmbeddedWidget {
 export interface MultilineEmbeddedWidget extends CommonEmbeddedWidget {
     widgetBuilder?: WidgetBuilder;
     component?: Component;
+    actionsComponent?: Component;
+    actionsComponentProps?: Record<string, unknown>;
     suppressEdit?: boolean;
 }
 export type MultilineEmbeddedWidgets = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orgnote-api",
-  "version": "0.41.50",
+  "version": "0.42.0",
   "description": "Official API for creating extensions for OrgNote app",
   "type": "module",
   "main": "./index.js",
@@ -48,6 +48,7 @@
   "homepage": "https://github.com/artawower/orgnote-api#readme",
   "dependencies": {
     "axios": "1.8.4",
+    "diff-match-patch": "^1.0.5",
     "neverthrow": "^8.2.0",
     "openpgp": "6.3.0",
     "org-mode-ast": "0.11.8",
@@ -58,6 +59,7 @@
     "@eslint/js": "9.25.1",
     "@openapitools/openapi-generator-cli": "2.19.1",
     "@rollup/rollup-linux-arm64-gnu": "4.14.2",
+    "@types/diff-match-patch": "^1.0.36",
     "@types/node": "22.14.1",
     "eslint": "9.25.1",
     "eslint-plugin-sonarjs": "3.0.5",

package/sync/__tests__/is-mergeable.spec.d.ts

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

package/sync/__tests__/is-mergeable.spec.js

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest';
+import { isMergeableFile } from "../types.js";
+test('accepts .org files within size limit', () => {
+    expect(isMergeableFile('notes/todo.org', 1024)).toBe(true);
+});
+test('accepts .md files within size limit', () => {
+    expect(isMergeableFile('readme.md', 2048)).toBe(true);
+});
+test('rejects non-text extensions', () => {
+    expect(isMergeableFile('photo.png', 1024)).toBe(false);
+    expect(isMergeableFile('data.json', 500)).toBe(false);
+    expect(isMergeableFile('archive.zip', 100)).toBe(false);
+});
+test('rejects files exceeding 512KB', () => {
+    const overLimit = 512 * 1024 + 1;
+    expect(isMergeableFile('big.org', overLimit)).toBe(false);
+});
+test('accepts files exactly at 512KB boundary', () => {
+    const exactLimit = 512 * 1024;
+    expect(isMergeableFile('exact.org', exactLimit)).toBe(true);
+});
+test('handles files without extension', () => {
+    expect(isMergeableFile('README', 100)).toBe(false);
+});
+test('handles dotfiles', () => {
+    expect(isMergeableFile('.gitignore', 100)).toBe(false);
+});

package/sync/index.d.ts

@@ -7,5 +7,6 @@ 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';
+export { mergeText } from './merge/index.js';
+export { SyncOperationType, MergeOutcome, isMergeableFile } from './types.js';
+export type { SyncState, SyncStateData, SyncedFile, SyncStatus, LocalFile, RemoteFile, UploadResult, SyncPlan, SyncTask, SyncExecutor, SyncContext, CreateSyncPlanParams, MergeResult, MergeInputs, BaseContentEntry, BaseContentStore, } from './types.js';

package/sync/index.js

@@ -7,4 +7,5 @@ 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 { mergeText } from "./merge/index.js";
+export { SyncOperationType, MergeOutcome, isMergeableFile } from "./types.js";

package/sync/merge/__tests__/text-merge.spec.d.ts

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

package/sync/merge/__tests__/text-merge.spec.js

@@ -0,0 +1,85 @@
+import { expect, test } from 'vitest';
+import { textToUint8Array } from "../../../utils/binary.js";
+import { mergeText } from "../text-merge.js";
+import { MergeOutcome } from "../../types.js";
+const enc = (s) => textToUint8Array(s);
+test('returns remote when base is empty and local is empty', () => {
+    const result = mergeText({
+        base: new Uint8Array(0),
+        local: new Uint8Array(0),
+        remote: enc('remote text'),
+    });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    expect(new TextDecoder().decode(result.mergedContent)).toBe('remote text');
+});
+test('returns local when base is empty and remote is empty', () => {
+    const result = mergeText({
+        base: new Uint8Array(0),
+        local: enc('local text'),
+        remote: new Uint8Array(0),
+    });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    expect(new TextDecoder().decode(result.mergedContent)).toBe('local text');
+});
+test('returns remote when local equals base', () => {
+    const base = enc('* TODO Task one\n');
+    const result = mergeText({
+        base,
+        local: base,
+        remote: enc('* DONE Task one\n'),
+    });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    expect(new TextDecoder().decode(result.mergedContent)).toBe('* DONE Task one\n');
+});
+test('returns local when remote equals base', () => {
+    const base = enc('* TODO Task one\n');
+    const result = mergeText({
+        base,
+        local: enc('* TODO Task one\n** Subtask\n'),
+        remote: base,
+    });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    expect(new TextDecoder().decode(result.mergedContent)).toBe('* TODO Task one\n** Subtask\n');
+});
+test('returns local when all three are identical', () => {
+    const content = enc('* Same content\n');
+    const result = mergeText({ base: content, local: content, remote: content });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    expect(new TextDecoder().decode(result.mergedContent)).toBe('* Same content\n');
+});
+test('merges non-overlapping edits from local and remote', () => {
+    const base = enc('* TODO Task one\n* TODO Task two\n');
+    const local = enc('* DONE Task one\n* TODO Task two\n');
+    const remote = enc('* TODO Task one\n* DONE Task two\n');
+    const result = mergeText({ base, local, remote });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    const merged = new TextDecoder().decode(result.mergedContent);
+    expect(merged).toContain('DONE Task one');
+    expect(merged).toContain('DONE Task two');
+});
+test('diff-match-patch returns ambiguous for overlapping changes on same region', () => {
+    const base = enc('* TODO Task one\n');
+    const local = enc('* DONE Task one\n');
+    const remote = enc('* CANCELLED Task one\n');
+    const result = mergeText({ base, local, remote });
+    expect(result.outcome).toBe(MergeOutcome.Ambiguous);
+    expect(result.mergedContent).toBeUndefined();
+});
+test('merges insertion at different positions', () => {
+    const base = enc('* A\n');
+    const local = enc('* A\n* B\n');
+    const remote = enc('* A\n* C\n');
+    const result = mergeText({ base, local, remote });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+    const merged = new TextDecoder().decode(result.mergedContent);
+    expect(merged).toContain('* B');
+    expect(merged).toContain('* C');
+});
+test('handles empty string content', () => {
+    const result = mergeText({
+        base: enc(''),
+        local: enc(''),
+        remote: enc(''),
+    });
+    expect(result.outcome).toBe(MergeOutcome.Merged);
+});

package/sync/merge/index.d.ts

@@ -0,0 +1 @@
+export { mergeText } from './text-merge.js';

package/sync/merge/index.js

@@ -0,0 +1 @@
+export { mergeText } from "./text-merge.js";

package/sync/merge/text-merge.d.ts

@@ -0,0 +1,2 @@
+import type { MergeInputs, MergeResult } from '../types.js';
+export declare const mergeText: (inputs: MergeInputs) => MergeResult;

package/sync/merge/text-merge.js

@@ -0,0 +1,120 @@
+import DiffMatchPatch from 'diff-match-patch';
+import { textToUint8Array, uint8ArrayToText } from "../../utils/binary.js";
+import { MergeOutcome } from "../types.js";
+const dmp = new DiffMatchPatch();
+const DIFF_EQUAL = 0;
+const DIFF_DELETE = -1;
+const DIFF_INSERT = 1;
+const INITIAL_STATE = {
+    regions: [],
+    basePos: 0,
+    pending: null,
+};
+const commitPending = (state) => {
+    if (!state.pending)
+        return state;
+    const { start, replacement } = state.pending;
+    return {
+        regions: [
+            ...state.regions,
+            { baseStart: start, baseEnd: state.basePos, replacement },
+        ],
+        basePos: state.basePos,
+        pending: null,
+    };
+};
+const ensurePending = (state) => {
+    if (state.pending)
+        return state;
+    return { ...state, pending: { start: state.basePos, replacement: '' } };
+};
+const applyEqual = (state, text) => ({
+    ...commitPending(state),
+    basePos: state.basePos + text.length,
+    pending: null,
+});
+const applyDelete = (state, text) => ({
+    ...ensurePending(state),
+    basePos: state.basePos + text.length,
+});
+const applyInsert = (state, text) => {
+    const opened = ensurePending(state);
+    return {
+        ...opened,
+        pending: {
+            start: opened.pending.start,
+            replacement: opened.pending.replacement + text,
+        },
+    };
+};
+const OP_HANDLERS = {
+    [DIFF_EQUAL]: applyEqual,
+    [DIFF_DELETE]: applyDelete,
+    [DIFF_INSERT]: applyInsert,
+};
+const applyDiffOp = (state, [op, text]) => OP_HANDLERS[op](state, text);
+const diffToChangeRegions = (diffs) => {
+    const finalState = diffs.reduce(applyDiffOp, INITIAL_STATE);
+    return commitPending(finalState).regions;
+};
+const regionsOverlap = (local, remote) => local.some((lr) => remote.some((rr) => lr.baseStart < rr.baseEnd && rr.baseStart < lr.baseEnd));
+const applyRegionsToBase = (baseText, regions) => {
+    const sorted = [...regions].sort((a, b) => a.baseStart - b.baseStart);
+    let lastEnd = 0;
+    return (sorted
+        .map(({ baseStart, baseEnd, replacement }) => {
+        const chunk = baseText.substring(lastEnd, baseStart) + replacement;
+        lastEnd = baseEnd;
+        return chunk;
+    })
+        .join('') + baseText.substring(lastEnd));
+};
+const computeDiffs = (baseText, changedText) => {
+    const diffs = dmp.diff_main(baseText, changedText);
+    dmp.diff_cleanupSemantic(diffs);
+    return diffs;
+};
+const mergeThreeWay = (baseText, localText, remoteText) => {
+    const localRegions = diffToChangeRegions(computeDiffs(baseText, localText));
+    const remoteRegions = diffToChangeRegions(computeDiffs(baseText, remoteText));
+    if (regionsOverlap(localRegions, remoteRegions))
+        return null;
+    return applyRegionsToBase(baseText, [...localRegions, ...remoteRegions]);
+};
+const SHORT_CIRCUIT_RULES = [
+    { matches: ({ base, local }) => base === local, pick: ({ remote }) => remote },
+    { matches: ({ base, remote }) => base === remote, pick: ({ local }) => local },
+    { matches: ({ local, remote }) => local === remote, pick: ({ local }) => local },
+];
+const toTextTriplet = (inputs) => ({
+    base: uint8ArrayToText(inputs.base),
+    local: uint8ArrayToText(inputs.local),
+    remote: uint8ArrayToText(inputs.remote),
+});
+const resolveShortCircuit = (triplet) => SHORT_CIRCUIT_RULES.find((rule) => rule.matches(triplet))?.pick(triplet) ?? null;
+const toMergedResult = (merged) => {
+    if (merged === null)
+        return { outcome: MergeOutcome.Ambiguous };
+    return { outcome: MergeOutcome.Merged, mergedContent: textToUint8Array(merged) };
+};
+const resolveByteShortCircuit = (inputs) => {
+    const baseEmpty = inputs.base.length === 0;
+    const localEmpty = inputs.local.length === 0;
+    const remoteEmpty = inputs.remote.length === 0;
+    if (baseEmpty && localEmpty) {
+        return { outcome: MergeOutcome.Merged, mergedContent: inputs.remote };
+    }
+    if (baseEmpty && remoteEmpty) {
+        return { outcome: MergeOutcome.Merged, mergedContent: inputs.local };
+    }
+    return null;
+};
+export const mergeText = (inputs) => {
+    const shortCircuit = resolveByteShortCircuit(inputs);
+    if (shortCircuit)
+        return shortCircuit;
+    const triplet = toTextTriplet(inputs);
+    const merged = resolveShortCircuit(triplet)
+        ?? mergeThreeWay(triplet.base, triplet.local, triplet.remote);
+    return toMergedResult(merged);
+};

package/sync/operations/__tests__/read-binary-content.spec.d.ts

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

package/sync/operations/__tests__/read-binary-content.spec.js

@@ -0,0 +1,22 @@
+import { expect, test, vi } from 'vitest';
+import { readBinaryContent } from "../read-binary-content.js";
+test('returns Uint8Array as-is', async () => {
+    const content = new TextEncoder().encode('hello');
+    const fs = { readFile: vi.fn(async () => content) };
+    const result = await readBinaryContent(fs, '/test.org');
+    expect(result).toBe(content);
+});
+test('converts string to Uint8Array', async () => {
+    const fs = {
+        readFile: vi.fn(async () => 'hello'),
+    };
+    const result = await readBinaryContent(fs, '/test.org');
+    expect(new TextDecoder().decode(result)).toBe('hello');
+});
+test('handles empty content', async () => {
+    const fs = {
+        readFile: vi.fn(async () => ''),
+    };
+    const result = await readBinaryContent(fs, '/test.org');
+    expect(result.length).toBe(0);
+});

package/sync/operations/__tests__/try-merge-conflict.spec.d.ts

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

package/sync/operations/__tests__/try-merge-conflict.spec.js

@@ -0,0 +1,121 @@
+import { expect, test, vi } from 'vitest';
+import { tryMergeConflict } from "../conflict.js";
+import { createMemorySyncState } from "../../memory-state.js";
+const createMergeContext = (overrides) => ({
+    fs: overrides.fs,
+    executor: (overrides.executor ?? {}),
+    state: createMemorySyncState(),
+    serverTime: '2024-01-01T00:00:00Z',
+    deviceName: 'test-device',
+    isDirtyFile: overrides.isDirtyFile,
+});
+const CONFLICT_RESULT = {
+    status: 'conflict',
+    serverVersion: 5,
+};
+const BASE_CONTENT = new TextEncoder().encode('* TODO Base task\n');
+const LOCAL_CONTENT = new TextEncoder().encode('* DONE Local edit\n');
+const REMOTE_CONTENT = new TextEncoder().encode('* TODO Base task\n* New remote\n');
+test('returns false for non-mergeable file extension', async () => {
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 100 })),
+        },
+    });
+    const result = await tryMergeConflict('/image.png', CONFLICT_RESULT, BASE_CONTENT, ctx);
+    expect(result).toBeNull();
+});
+test('returns false when no base content provided', async () => {
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 100 })),
+        },
+    });
+    const result = await tryMergeConflict('/note.org', CONFLICT_RESULT, null, ctx);
+    expect(result).toBeNull();
+});
+test('returns false when file is dirty in editor', async () => {
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 200 })),
+        },
+        isDirtyFile: async () => true,
+    });
+    const result = await tryMergeConflict('/note.org', CONFLICT_RESULT, BASE_CONTENT, ctx);
+    expect(result).toBeNull();
+});
+test('returns false when remote download fails with 404', async () => {
+    const { AxiosError } = await import('axios');
+    const notFoundResponse = {
+        status: 404,
+        statusText: 'Not Found',
+        headers: {},
+        config: {},
+        data: {},
+    };
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 200 })),
+            readFile: vi.fn(async () => LOCAL_CONTENT),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            download: vi.fn(async () => {
+                throw new AxiosError('Not Found', 'ERR_BAD_REQUEST', undefined, undefined, notFoundResponse);
+            }),
+        },
+    });
+    const result = await tryMergeConflict('/note.org', CONFLICT_RESULT, BASE_CONTENT, ctx);
+    expect(result).toBeNull();
+});
+test('returns false when no base available for merge', async () => {
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 200 })),
+        },
+    });
+    const result = await tryMergeConflict('/note.org', CONFLICT_RESULT, null, ctx);
+    expect(result).toBeNull();
+});
+test('writes merged content when merge succeeds', async () => {
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 200 })),
+            readFile: vi.fn()
+                .mockResolvedValueOnce(LOCAL_CONTENT)
+                .mockResolvedValueOnce(REMOTE_CONTENT),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            download: vi.fn(async () => undefined),
+        },
+    });
+    const result = await tryMergeConflict('/note.org', CONFLICT_RESULT, BASE_CONTENT, ctx);
+    expect(result).toBeTruthy();
+    expect(ctx.fs.writeFile).toHaveBeenCalledWith('/note.org', expect.any(Uint8Array));
+});
+test('reads local content before downloading remote', async () => {
+    const callOrder = [];
+    const ctx = createMergeContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 1, size: 200 })),
+            readFile: vi.fn(async () => {
+                callOrder.push('readLocal');
+                return LOCAL_CONTENT;
+            }),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => {
+                callOrder.push('deleteTemp');
+            }),
+        },
+        executor: {
+            download: vi.fn(async () => {
+                callOrder.push('download');
+            }),
+        },
+    });
+    await tryMergeConflict('/note.org', CONFLICT_RESULT, BASE_CONTENT, ctx);
+    expect(callOrder.indexOf('readLocal')).toBeLessThan(callOrder.indexOf('download'));
+});

package/sync/operations/__tests__/upload-merge.spec.d.ts

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

package/sync/operations/__tests__/upload-merge.spec.js

@@ -0,0 +1,211 @@
+import { expect, test, vi } from 'vitest';
+import { processUpload } from "../upload.js";
+import { createMemorySyncState } from "../../memory-state.js";
+vi.mock('../content-hash', () => ({
+    resolveContentHash: vi.fn(async () => 'mock-hash'),
+}));
+const createUploadContext = (overrides) => ({
+    fs: overrides.fs,
+    executor: (overrides.executor ?? {}),
+    state: createMemorySyncState(),
+    serverTime: '2024-01-01T00:00:00Z',
+    deviceName: 'test-device',
+    isDirtyFile: overrides.isDirtyFile,
+    baseStore: overrides.baseStore,
+});
+const LOCAL_FILE = {
+    path: '/note.org',
+    mtime: 100,
+    size: 50,
+    contentHash: 'abc123',
+};
+const createBaseStore = (storedBase) => ({
+    get: vi.fn(async () => storedBase ?? null),
+    set: vi.fn(async () => undefined),
+    remove: vi.fn(async () => undefined),
+});
+test('upload without baseStore uses fallback conflict on 409', async () => {
+    const ctx = createUploadContext({
+        fs: {
+            copyFile: vi.fn(async () => undefined),
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 50 })),
+            readFile: vi.fn(async () => new TextEncoder().encode('server content')),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            upload: vi.fn(async () => ({
+                status: 'conflict',
+                serverVersion: 3,
+            })),
+            download: vi.fn(async () => undefined),
+        },
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.version).toBe(3);
+    expect(stored?.conflictPath).toContain('.sync-conflict-');
+});
+test('successful upload without baseStore persists synced state', async () => {
+    const ctx = createUploadContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 50 })),
+            readFile: vi.fn(async () => new TextEncoder().encode('content')),
+        },
+        executor: {
+            upload: vi.fn(async () => ({ status: 'ok', version: 2 })),
+        },
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.version).toBe(2);
+});
+test('successful upload with baseStore updates base', async () => {
+    const fileContent = new TextEncoder().encode('* Task\n');
+    const baseStore = createBaseStore();
+    const ctx = createUploadContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 50 })),
+            readFile: vi.fn(async () => fileContent),
+        },
+        executor: {
+            upload: vi.fn(async () => ({ status: 'ok', version: 4 })),
+        },
+        baseStore,
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    expect(baseStore.set).toHaveBeenCalledWith('/note.org', expect.objectContaining({
+        path: '/note.org',
+        version: 4,
+        content: fileContent,
+    }));
+});
+test('merge-retry flow: conflict → merge → retry success → synced', async () => {
+    const baseContent = new TextEncoder().encode('* TODO Base\n');
+    const localContent = new TextEncoder().encode('* DONE Local\n');
+    const remoteContent = new TextEncoder().encode('* TODO Base\n* New\n');
+    const baseStore = createBaseStore({
+        path: '/note.org',
+        version: 2,
+        contentHash: 'old-hash',
+        content: baseContent,
+        updatedAt: '2024-01-01T00:00:00Z',
+    });
+    let uploadCallCount = 0;
+    const ctx = createUploadContext({
+        fs: {
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 200 })),
+            readFile: vi.fn()
+                .mockResolvedValueOnce(localContent)
+                .mockResolvedValueOnce(remoteContent)
+                .mockResolvedValueOnce(localContent),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            upload: vi.fn(async () => {
+                uploadCallCount++;
+                if (uploadCallCount === 1) {
+                    return { status: 'conflict', serverVersion: 3 };
+                }
+                return { status: 'ok', version: 4 };
+            }),
+            download: vi.fn(async () => undefined),
+        },
+        baseStore,
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    expect(uploadCallCount).toBe(2);
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.version).toBe(4);
+    expect(stored?.conflictPath).toBeUndefined();
+});
+test('merge-retry flow: conflict → merge fails → fallback conflict', async () => {
+    const baseContent = new TextEncoder().encode('* TODO Task\n');
+    const localContent = new TextEncoder().encode('* DONE Task\n');
+    const remoteContent = new TextEncoder().encode('* CANCELLED Task\n');
+    const baseStore = createBaseStore({
+        path: '/note.org',
+        version: 2,
+        contentHash: 'old-hash',
+        content: baseContent,
+        updatedAt: '2024-01-01T00:00:00Z',
+    });
+    const ctx = createUploadContext({
+        fs: {
+            copyFile: vi.fn(async () => undefined),
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 200 })),
+            readFile: vi.fn()
+                .mockResolvedValueOnce(localContent)
+                .mockResolvedValueOnce(remoteContent)
+                .mockResolvedValueOnce(new TextEncoder().encode('server')),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            upload: vi.fn(async () => ({
+                status: 'conflict',
+                serverVersion: 3,
+            })),
+            download: vi.fn(async () => undefined),
+        },
+        baseStore,
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.conflictPath).toContain('.sync-conflict-');
+});
+test('merge-retry flow: merge succeeds but retry conflicts → fallback', async () => {
+    const baseContent = new TextEncoder().encode('* TODO Base\n');
+    const localContent = new TextEncoder().encode('* DONE Local\n');
+    const remoteContent = new TextEncoder().encode('* TODO Base\n* New\n');
+    const baseStore = createBaseStore({
+        path: '/note.org',
+        version: 2,
+        contentHash: 'old-hash',
+        content: baseContent,
+        updatedAt: '2024-01-01T00:00:00Z',
+    });
+    const ctx = createUploadContext({
+        fs: {
+            copyFile: vi.fn(async () => undefined),
+            fileInfo: vi.fn(async () => ({ mtime: 100, size: 200 })),
+            readFile: vi.fn()
+                .mockResolvedValueOnce(localContent)
+                .mockResolvedValueOnce(remoteContent)
+                .mockResolvedValueOnce(localContent)
+                .mockResolvedValueOnce(new TextEncoder().encode('server')),
+            writeFile: vi.fn(async () => undefined),
+            deleteFile: vi.fn(async () => undefined),
+        },
+        executor: {
+            upload: vi.fn(async () => ({
+                status: 'conflict',
+                serverVersion: 3,
+            })),
+            download: vi.fn(async () => undefined),
+        },
+        baseStore,
+    });
+    await processUpload(LOCAL_FILE, ctx);
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('synced');
+    expect(stored?.conflictPath).toContain('.sync-conflict-');
+});
+test('upload error stores error status and rethrows', async () => {
+    const ctx = createUploadContext({
+        fs: {},
+        executor: {
+            upload: vi.fn(async () => {
+                throw new Error('network failure');
+            }),
+        },
+    });
+    await expect(processUpload(LOCAL_FILE, ctx)).rejects.toThrow('network failure');
+    const stored = await ctx.state.getFile('/note.org');
+    expect(stored?.status).toBe('error');
+    expect(stored?.errorMessage).toContain('network failure');
+});

package/sync/operations/conflict.d.ts

@@ -3,6 +3,7 @@ type ConflictUploadResult = Extract<UploadResult, {
     status: 'conflict';
 }>;
 export declare const generateConflictPath: (path: string, deviceName?: string) => string;
+export declare const tryMergeConflict: (path: string, conflictResult: ConflictUploadResult, baseContent: Uint8Array | null, ctx: SyncContext) => Promise<Uint8Array | null>;
 export declare const handleConflict: (path: string, conflictResult: ConflictUploadResult, ctx: SyncContext) => Promise<void>;
 export declare const hasConflict: (file: {
     conflictPath?: string;

package/sync/operations/conflict.js

@@ -1,12 +1,18 @@
+import axios from 'axios';
+import { MergeOutcome } from "../types.js";
 import { createSyncedFile } from "./synced-file.js";
 import { resolveContentHash } from "./content-hash.js";
-import axios from 'axios';
+import { readBinaryContent } from "./read-binary-content.js";
+import { mergeText } from "../merge/text-merge.js";
+import { isMergeableFile } from "../types.js";
+import { to } from "../../utils/to-error.js";
 export const generateConflictPath = (path, deviceName = 'device') => {
     const lastDot = path.lastIndexOf('.');
     const ext = lastDot >= 0 ? path.substring(lastDot) : '';
     const base = lastDot >= 0 ? path.substring(0, lastDot) : path;
     const timestamp = Date.now();
-    return `${base}.sync-conflict-${timestamp}-${deviceName}${ext}`;
+    const safeDeviceName = deviceName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return `${base}.sync-conflict-${timestamp}-${safeDeviceName}${ext}`;
 };
 const copyFile = async (fs, src, dest) => {
     if (fs.copyFile) {
@@ -16,24 +22,106 @@ const copyFile = async (fs, src, dest) => {
     const content = await fs.readFile(src, 'binary');
     await fs.writeFile(dest, content);
 };
-const isNotFoundError = (error) => {
-    return axios.isAxiosError(error) && error.response?.status === 404;
+const isAxiosNotFound = (error) => {
+    if (!axios.isAxiosError(error))
+        return false;
+    return error.response?.status === 404;
 };
-const tryDownloadServerVersion = async (path, serverVersion, ctx) => {
+const refreshBaseStore = async (path, version, contentHash, ctx) => {
+    if (!ctx.baseStore)
+        return;
+    const content = await readBinaryContent(ctx.fs, path);
+    await ctx.baseStore.set(path, {
+        path,
+        version,
+        contentHash,
+        content,
+        updatedAt: ctx.serverTime,
+    });
+};
+const removeBaseStoreEntry = async (path, ctx) => {
+    if (!ctx.baseStore)
+        return;
+    await ctx.baseStore.remove(path);
+};
+const downloadRemoteContent = async (path, version, ctx) => {
+    const result = await to(ctx.executor.download)({
+        path,
+        version,
+        deleted: false,
+        updatedAt: new Date().toISOString(),
+    });
+    if (result.isErr()) {
+        if (isAxiosNotFound(result.error))
+            return null;
+        throw result.error;
+    }
+    return readBinaryContent(ctx.fs, path);
+};
+const isDirty = async (path, ctx) => {
+    if (!ctx.isDirtyFile)
+        return false;
+    return ctx.isDirtyFile(path);
+};
+const canAttemptMerge = async (path, baseContent, ctx) => {
+    const fileInfo = await ctx.fs.fileInfo(path);
+    if (!fileInfo) {
+        return false;
+    }
+    if (!isMergeableFile(path, fileInfo.size)) {
+        return false;
+    }
+    if (!baseContent) {
+        return false;
+    }
+    const dirty = await isDirty(path, ctx);
+    if (dirty) {
+        return false;
+    }
+    return true;
+};
+export const tryMergeConflict = async (path, conflictResult, baseContent, ctx) => {
+    if (!(await canAttemptMerge(path, baseContent, ctx)))
+        return null;
+    const localContent = await readBinaryContent(ctx.fs, path);
+    let remoteContent;
     try {
-        await ctx.executor.download({
-            path,
-            version: serverVersion,
-            deleted: false,
-            updatedAt: new Date().toISOString(),
-        });
-        return true;
+        remoteContent = await downloadRemoteContent(path, conflictResult.serverVersion, ctx);
     }
     catch (error) {
-        if (isNotFoundError(error))
-            return false;
+        await ctx.fs.writeFile(path, localContent);
         throw error;
     }
+    if (!remoteContent) {
+        await ctx.fs.writeFile(path, localContent);
+        return null;
+    }
+    const inputs = {
+        base: baseContent,
+        local: localContent,
+        remote: remoteContent,
+    };
+    const mergeResult = mergeText(inputs);
+    if (mergeResult.outcome !== MergeOutcome.Merged ||
+        !mergeResult.mergedContent) {
+        return null;
+    }
+    await ctx.fs.writeFile(path, mergeResult.mergedContent);
+    return mergeResult.mergedContent;
+};
+const tryDownloadServerVersion = async (path, serverVersion, ctx) => {
+    const result = await to(ctx.executor.download)({
+        path,
+        version: serverVersion,
+        deleted: false,
+        updatedAt: new Date().toISOString(),
+    });
+    if (result.isErr()) {
+        if (isAxiosNotFound(result.error))
+            return false;
+        throw result.error;
+    }
+    return true;
 };
 export const handleConflict = async (path, conflictResult, ctx) => {
     const conflictPath = generateConflictPath(path, ctx.deviceName);
@@ -42,6 +130,7 @@ export const handleConflict = async (path, conflictResult, ctx) => {
     if (!downloaded) {
         await ctx.fs.deleteFile(path);
         await ctx.state.removeFile(path);
+        await removeBaseStoreEntry(path, ctx);
         return;
     }
     const fileInfo = await ctx.fs.fileInfo(path);
@@ -56,5 +145,6 @@ export const handleConflict = async (path, conflictResult, ctx) => {
         status: 'synced',
         conflictPath,
     }));
+    await refreshBaseStore(path, conflictResult.serverVersion, contentHash, ctx);
 };
 export const hasConflict = (file) => file.conflictPath !== undefined;

package/sync/operations/delete-local.js

@@ -2,6 +2,7 @@ export const processDeleteLocal = async (path, ctx) => {
     try {
         await ctx.fs.deleteFile(path);
         await ctx.state.removeFile(path);
+        await removeBaseStoreEntry(path, ctx);
     }
     catch (error) {
         const stored = await ctx.state.getFile(path);
@@ -15,3 +16,8 @@ export const processDeleteLocal = async (path, ctx) => {
         throw error;
     }
 };
+const removeBaseStoreEntry = async (path, ctx) => {
+    if (!ctx.baseStore)
+        return;
+    await ctx.baseStore.remove(path);
+};

package/sync/operations/delete-remote.js

@@ -8,10 +8,12 @@ export const processDeleteRemote = async (path, ctx) => {
     try {
         await ctx.executor.deleteRemote(path, stored?.version ?? 0);
         await ctx.state.removeFile(path);
+        await removeBaseStoreEntry(path, ctx);
     }
     catch (error) {
         if (isNotFoundError(error)) {
             await ctx.state.removeFile(path);
+            await removeBaseStoreEntry(path, ctx);
             return;
         }
         if (stored) {
@@ -24,3 +26,8 @@ export const processDeleteRemote = async (path, ctx) => {
         throw error;
     }
 };
+const removeBaseStoreEntry = async (path, ctx) => {
+    if (!ctx.baseStore)
+        return;
+    await ctx.baseStore.remove(path);
+};

package/sync/operations/download.js

@@ -1,5 +1,6 @@
 import { createSyncedFile } from "./synced-file.js";
 import { resolveContentHash } from "./content-hash.js";
+import { readBinaryContent } from "./read-binary-content.js";
 const storedMeta = (stored) => ({
     mtime: stored?.mtime ?? 0,
     size: stored?.size ?? 0,
@@ -33,6 +34,18 @@ const markError = async (file, stored, error, ctx) => {
         errorMessage: String(error),
     }));
 };
+const refreshBaseStoreAfterDownload = async (path, version, contentHash, ctx) => {
+    if (!ctx.baseStore)
+        return;
+    const content = await readBinaryContent(ctx.fs, path);
+    await ctx.baseStore.set(path, {
+        path,
+        version,
+        contentHash,
+        content,
+        updatedAt: ctx.serverTime,
+    });
+};
 export const processDownload = async (file, ctx) => {
     const stored = await ctx.state.getFile(file.path);
     await markDownloading(file, stored, ctx);
@@ -40,6 +53,7 @@ export const processDownload = async (file, ctx) => {
         await ctx.executor.download(file);
         const downloadedMeta = await resolveDownloadedMeta(file, ctx);
         await markSynced(file, downloadedMeta, ctx);
+        await refreshBaseStoreAfterDownload(file.path, file.version, downloadedMeta.contentHash ?? '', ctx);
     }
     catch (error) {
         await markError(file, stored, error, ctx);

package/sync/operations/index.d.ts

@@ -2,4 +2,5 @@ export { processUpload } from './upload.js';
 export { processDownload } from './download.js';
 export { processDeleteLocal } from './delete-local.js';
 export { processDeleteRemote } from './delete-remote.js';
-export { handleConflict, generateConflictPath, hasConflict } from './conflict.js';
+export { handleConflict, generateConflictPath, hasConflict, } from './conflict.js';
+export { readBinaryContent } from './read-binary-content.js';

package/sync/operations/index.js

@@ -2,4 +2,5 @@ export { processUpload } from "./upload.js";
 export { processDownload } from "./download.js";
 export { processDeleteLocal } from "./delete-local.js";
 export { processDeleteRemote } from "./delete-remote.js";
-export { handleConflict, generateConflictPath, hasConflict } from "./conflict.js";
+export { handleConflict, generateConflictPath, hasConflict, } from "./conflict.js";
+export { readBinaryContent } from "./read-binary-content.js";

package/sync/operations/read-binary-content.d.ts

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

package/sync/operations/read-binary-content.js

@@ -0,0 +1,6 @@
+export const readBinaryContent = async (fs, path) => {
+    const content = await fs.readFile(path, 'binary');
+    return content instanceof Uint8Array
+        ? content
+        : new TextEncoder().encode(String(content));
+};

package/sync/operations/upload.js

@@ -1,30 +1,74 @@
-import { handleConflict } from "./conflict.js";
+import { handleConflict, tryMergeConflict } from "./conflict.js";
 import { createSyncedFile } from "./synced-file.js";
-const executeUpload = async (file, expectedVersion, ctx) => {
-    const result = await ctx.executor.upload(file, expectedVersion);
-    if (result.status === 'ok') {
-        await ctx.state.setFile(file.path, createSyncedFile(file, {
-            version: result.version,
-            status: 'synced',
-            syncedAt: ctx.serverTime,
-        }));
-        return;
-    }
-    await handleConflict(file.path, result, ctx);
+import { resolveContentHash } from "./content-hash.js";
+import { readBinaryContent } from "./read-binary-content.js";
+import { hashContent } from "../utils/content-hash.js";
+import { to } from "../../utils/to-error.js";
+const persistErrorState = async (file, expectedVersion, error, ctx) => {
+    await ctx.state.setFile(file.path, createSyncedFile(file, {
+        version: expectedVersion,
+        status: 'error',
+        errorMessage: String(error),
+    }));
 };
 export const processUpload = async (file, ctx) => {
     const stored = await ctx.state.getFile(file.path);
     const expectedVersion = stored?.version;
     await ctx.state.setFile(file.path, createSyncedFile(file, { version: expectedVersion, status: 'uploading' }));
-    try {
-        await executeUpload(file, expectedVersion, ctx);
+    const execute = ctx.baseStore
+        ? to(() => executeUploadWithMergeRetry(file, expectedVersion, ctx))
+        : to(() => executeUpload(file, expectedVersion, ctx));
+    const result = await execute();
+    if (result.isOk())
+        return;
+    await persistErrorState(file, expectedVersion, result.error, ctx);
+    throw result.error;
+};
+const executeUpload = async (file, expectedVersion, ctx) => {
+    const result = await ctx.executor.upload(file, expectedVersion);
+    if (result.status !== 'ok') {
+        await handleConflict(file.path, result, ctx);
+        return;
     }
-    catch (error) {
-        await ctx.state.setFile(file.path, createSyncedFile(file, {
-            version: expectedVersion,
-            status: 'error',
-            errorMessage: String(error),
-        }));
-        throw error;
+    await persistSyncedSnapshot(file.path, result.version, ctx);
+};
+const executeUploadWithMergeRetry = async (file, expectedVersion, ctx) => {
+    const result = await ctx.executor.upload(file, expectedVersion);
+    if (result.status === 'ok') {
+        await persistSyncedSnapshot(file.path, result.version, ctx);
+        return;
+    }
+    const baseEntry = ctx.baseStore ? await ctx.baseStore.get(file.path) : null;
+    const mergedContent = await tryMergeConflict(file.path, result, baseEntry?.content ?? null, ctx);
+    if (!mergedContent) {
+        await handleConflict(file.path, result, ctx);
+        return;
+    }
+    const contentHash = await hashContent(mergedContent);
+    const mergedFile = { ...file, contentHash };
+    const retryResult = await ctx.executor.upload(mergedFile, result.serverVersion);
+    if (retryResult.status !== 'ok') {
+        await handleConflict(file.path, retryResult, ctx);
+        return;
     }
+    await persistSyncedSnapshot(file.path, retryResult.version, ctx);
+};
+const persistSyncedSnapshot = async (path, version, ctx) => {
+    const fileInfo = await ctx.fs.fileInfo(path);
+    const contentHash = fileInfo ? await resolveContentHash(ctx.fs, path) : '';
+    await ctx.state.setFile(path, createSyncedFile({
+        mtime: fileInfo?.mtime ?? 0,
+        size: fileInfo?.size ?? 0,
+        contentHash,
+    }, { version, status: 'synced', syncedAt: ctx.serverTime }));
+    if (!ctx.baseStore)
+        return;
+    const content = await readBinaryContent(ctx.fs, path);
+    await ctx.baseStore.set(path, {
+        path,
+        version,
+        contentHash,
+        content,
+        updatedAt: ctx.serverTime,
+    });
 };

package/sync/types.d.ts

@@ -74,4 +74,32 @@ export interface SyncContext {
     fs: FileSystem;
     serverTime: string;
     deviceName?: string;
+    isDirtyFile?: (path: string) => Promise<boolean> | boolean;
+    baseStore?: BaseContentStore;
 }
+export declare enum MergeOutcome {
+    Merged = "merged",
+    Ambiguous = "ambiguous"
+}
+export interface MergeResult {
+    outcome: MergeOutcome;
+    mergedContent?: Uint8Array;
+}
+export interface BaseContentEntry {
+    path: string;
+    version: number;
+    contentHash: string;
+    content: Uint8Array;
+    updatedAt: string;
+}
+export interface BaseContentStore {
+    get(path: string): Promise<BaseContentEntry | null>;
+    set(path: string, entry: BaseContentEntry): Promise<void>;
+    remove(path: string): Promise<void>;
+}
+export interface MergeInputs {
+    base: Uint8Array;
+    local: Uint8Array;
+    remote: Uint8Array;
+}
+export declare const isMergeableFile: (path: string, size: number) => boolean;

package/sync/types.js

@@ -5,3 +5,15 @@ export var SyncOperationType;
     SyncOperationType["DeleteLocal"] = "deleteLocal";
     SyncOperationType["DeleteRemote"] = "deleteRemote";
 })(SyncOperationType || (SyncOperationType = {}));
+export var MergeOutcome;
+(function (MergeOutcome) {
+    MergeOutcome["Merged"] = "merged";
+    MergeOutcome["Ambiguous"] = "ambiguous";
+})(MergeOutcome || (MergeOutcome = {}));
+const MERGEABLE_EXTENSIONS = new Set(['.org', '.md']);
+const MAX_MERGEABLE_SIZE_BYTES = 512 * 1024;
+export const isMergeableFile = (path, size) => {
+    const lastDot = path.lastIndexOf('.');
+    const ext = lastDot >= 0 ? path.substring(lastDot) : '';
+    return MERGEABLE_EXTENSIONS.has(ext) && size <= MAX_MERGEABLE_SIZE_BYTES;
+};