feishu-md-sync 0.1.0

package/dist/merge/line-merge.js

@@ -0,0 +1,270 @@
+export function mergeLines(input) {
+    if (input.local === input.remote) {
+        return cleanResult(input.local);
+    }
+    const base = splitLines(input.base);
+    const localChanges = changesFromBase(base, splitLines(input.local));
+    const remoteChanges = changesFromBase(base, splitLines(input.remote));
+    const output = [];
+    let baseIndex = 0;
+    let localIndex = 0;
+    let remoteIndex = 0;
+    let conflicts = 0;
+    while (baseIndex < base.length || localIndex < localChanges.length || remoteIndex < remoteChanges.length) {
+        const localChange = localChanges[localIndex];
+        const remoteChange = remoteChanges[remoteIndex];
+        if (!localChange && !remoteChange) {
+            output.push(...base.slice(baseIndex));
+            break;
+        }
+        const nextStart = Math.min(localChange?.baseStart ?? Number.POSITIVE_INFINITY, remoteChange?.baseStart ?? Number.POSITIVE_INFINITY);
+        output.push(...base.slice(baseIndex, nextStart));
+        baseIndex = nextStart;
+        if (localChange && (!remoteChange || isStrictlyBefore(localChange, remoteChange))) {
+            output.push(...localChange.lines);
+            baseIndex = localChange.baseEnd;
+            localIndex += 1;
+            continue;
+        }
+        if (remoteChange && (!localChange || isStrictlyBefore(remoteChange, localChange))) {
+            output.push(...remoteChange.lines);
+            baseIndex = remoteChange.baseEnd;
+            remoteIndex += 1;
+            continue;
+        }
+        const overlap = collectOverlappingChanges({
+            localChanges,
+            remoteChanges,
+            localIndex,
+            remoteIndex
+        });
+        localIndex = overlap.localIndex;
+        remoteIndex = overlap.remoteIndex;
+        baseIndex = overlap.baseEnd;
+        const localLines = applyChangesToBaseSlice(base, overlap.baseStart, overlap.baseEnd, overlap.local);
+        const remoteLines = applyChangesToBaseSlice(base, overlap.baseStart, overlap.baseEnd, overlap.remote);
+        if (joinLines(localLines) === joinLines(remoteLines)) {
+            output.push(...localLines);
+            continue;
+        }
+        if (overlap.baseStart === overlap.baseEnd) {
+            output.push(...combineSamePositionInsertions(localLines, remoteLines));
+            continue;
+        }
+        output.push(...conflictLines(localLines, remoteLines));
+        conflicts += 1;
+    }
+    return resultFromOutput(output, input.local, conflicts);
+}
+export function mergeWithoutBase(input) {
+    if (input.local === input.remote) {
+        return cleanResult(input.local);
+    }
+    const local = splitLines(input.local);
+    const remote = splitLines(input.remote);
+    const table = lcsTable(local, remote);
+    const output = [];
+    let i = 0;
+    let j = 0;
+    let conflicts = 0;
+    while (i < local.length || j < remote.length) {
+        if (i < local.length && j < remote.length && local[i] === remote[j]) {
+            output.push(local[i]);
+            i += 1;
+            j += 1;
+            continue;
+        }
+        const localChunk = [];
+        const remoteChunk = [];
+        while (i < local.length || j < remote.length) {
+            if (i < local.length && j < remote.length && local[i] === remote[j])
+                break;
+            if (i < local.length && (j === remote.length || table[i + 1][j] >= table[i][j + 1])) {
+                localChunk.push(local[i]);
+                i += 1;
+                continue;
+            }
+            if (j < remote.length) {
+                remoteChunk.push(remote[j]);
+                j += 1;
+            }
+        }
+        output.push(...conflictLines(localChunk, remoteChunk));
+        conflicts += 1;
+    }
+    return {
+        markdown: joinLines(output),
+        state: 'conflict',
+        conflicts,
+        changed: true
+    };
+}
+function cleanResult(markdown) {
+    return {
+        markdown,
+        state: 'clean',
+        conflicts: 0,
+        changed: false
+    };
+}
+function resultFromOutput(output, local, conflicts) {
+    const markdown = joinLines(output);
+    if (conflicts > 0) {
+        return {
+            markdown,
+            state: 'conflict',
+            conflicts,
+            changed: markdown !== local
+        };
+    }
+    return {
+        markdown,
+        state: markdown === local ? 'clean' : 'merged',
+        conflicts: 0,
+        changed: markdown !== local
+    };
+}
+function splitLines(markdown) {
+    return markdown.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+function joinLines(lines) {
+    return lines.join('');
+}
+function conflictLines(local, remote) {
+    return [
+        '<<<<<<< LOCAL\n',
+        ...ensureTrailingNewline(local),
+        '=======\n',
+        ...ensureTrailingNewline(remote),
+        '>>>>>>> REMOTE\n'
+    ];
+}
+function ensureTrailingNewline(lines) {
+    if (lines.length === 0)
+        return [];
+    const last = lines.at(-1);
+    if (last?.endsWith('\n'))
+        return lines;
+    return [...lines.slice(0, -1), `${last}\n`];
+}
+function combineSamePositionInsertions(local, remote) {
+    let prefix = 0;
+    while (prefix < local.length && prefix < remote.length && local[prefix] === remote[prefix]) {
+        prefix += 1;
+    }
+    return [
+        ...local.slice(0, prefix),
+        ...local.slice(prefix),
+        ...remote.slice(prefix)
+    ];
+}
+function isStrictlyBefore(left, right) {
+    if (left.baseStart === right.baseStart)
+        return false;
+    return left.baseEnd <= right.baseStart;
+}
+function collectOverlappingChanges(input) {
+    const firstLocal = input.localChanges[input.localIndex];
+    const firstRemote = input.remoteChanges[input.remoteIndex];
+    let baseStart = Math.min(firstLocal?.baseStart ?? Number.POSITIVE_INFINITY, firstRemote?.baseStart ?? Number.POSITIVE_INFINITY);
+    let baseEnd = Math.max(firstLocal?.baseEnd ?? baseStart, firstRemote?.baseEnd ?? baseStart);
+    let localIndex = input.localIndex;
+    let remoteIndex = input.remoteIndex;
+    const local = [];
+    const remote = [];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        while (localIndex < input.localChanges.length && input.localChanges[localIndex].baseStart <= baseEnd) {
+            const change = input.localChanges[localIndex];
+            local.push(change);
+            baseStart = Math.min(baseStart, change.baseStart);
+            baseEnd = Math.max(baseEnd, change.baseEnd);
+            localIndex += 1;
+            changed = true;
+        }
+        while (remoteIndex < input.remoteChanges.length && input.remoteChanges[remoteIndex].baseStart <= baseEnd) {
+            const change = input.remoteChanges[remoteIndex];
+            remote.push(change);
+            baseStart = Math.min(baseStart, change.baseStart);
+            baseEnd = Math.max(baseEnd, change.baseEnd);
+            remoteIndex += 1;
+            changed = true;
+        }
+    }
+    return {
+        baseStart,
+        baseEnd,
+        local,
+        remote,
+        localIndex,
+        remoteIndex
+    };
+}
+function applyChangesToBaseSlice(base, start, end, changes) {
+    const output = [];
+    let index = start;
+    for (const change of changes) {
+        output.push(...base.slice(index, change.baseStart));
+        output.push(...change.lines);
+        index = change.baseEnd;
+    }
+    output.push(...base.slice(index, end));
+    return output;
+}
+function changesFromBase(base, next) {
+    const table = lcsTable(base, next);
+    const changes = [];
+    let i = 0;
+    let j = 0;
+    let pendingStart;
+    let pendingEnd = 0;
+    let pendingLines = [];
+    const startPending = () => {
+        if (pendingStart !== undefined)
+            return;
+        pendingStart = i;
+        pendingEnd = i;
+    };
+    const flush = () => {
+        if (pendingStart === undefined)
+            return;
+        changes.push({
+            baseStart: pendingStart,
+            baseEnd: pendingEnd,
+            lines: pendingLines
+        });
+        pendingStart = undefined;
+        pendingEnd = 0;
+        pendingLines = [];
+    };
+    while (i < base.length || j < next.length) {
+        if (i < base.length && j < next.length && base[i] === next[j]) {
+            flush();
+            i += 1;
+            j += 1;
+            continue;
+        }
+        startPending();
+        if (j < next.length && (i === base.length || table[i][j + 1] >= table[i + 1][j])) {
+            pendingLines.push(next[j]);
+            j += 1;
+            continue;
+        }
+        if (i < base.length) {
+            i += 1;
+            pendingEnd = i;
+        }
+    }
+    flush();
+    return changes;
+}
+function lcsTable(a, b) {
+    const table = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+        for (let j = b.length - 1; j >= 0; j -= 1) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    return table;
+}

package/dist/merge/merge-state.d.ts

@@ -0,0 +1,33 @@
+import type { PublishProfileName } from '../profiles/publish-profile.js';
+import type { PublishReceiptTarget } from '../receipts/publish-receipt.js';
+export type MergeStateFile = {
+    version: 1;
+    filePath: string;
+    target?: PublishReceiptTarget;
+    profile: PublishProfileName;
+    startedAt: string;
+};
+export declare function mergeStateDir(input: {
+    cwd: string;
+    filePath: string;
+}): string;
+export declare function assertNoMergeState(input: {
+    cwd: string;
+    filePath: string;
+}): Promise<void>;
+export declare function writeMergeState(input: {
+    cwd: string;
+    filePath: string;
+    originalMarkdown: string;
+    target?: PublishReceiptTarget;
+    profile: PublishProfileName;
+}): Promise<{
+    statePath: string;
+}>;
+export declare function restoreMergeState(input: {
+    cwd: string;
+    filePath: string;
+}): Promise<{
+    restored: boolean;
+    statePath: string;
+}>;

package/dist/merge/merge-state.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+export function mergeStateDir(input) {
+    const key = createHash('sha256').update(input.filePath).digest('hex').slice(0, 24);
+    return join(input.cwd, '.sync', 'feishu-md-sync', 'merge-state', key);
+}
+export async function assertNoMergeState(input) {
+    try {
+        await readFile(join(mergeStateDir(input), 'state.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    throw new Error('A merge is already in progress for this file. Resolve it or run merge --abort before starting another merge.');
+}
+export async function writeMergeState(input) {
+    await assertNoMergeState({ cwd: input.cwd, filePath: input.filePath });
+    const dir = mergeStateDir({ cwd: input.cwd, filePath: input.filePath });
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'original.md'), input.originalMarkdown, 'utf8');
+    const state = {
+        version: 1,
+        filePath: relative(input.cwd, input.filePath),
+        target: input.target,
+        profile: input.profile,
+        startedAt: new Date().toISOString()
+    };
+    const statePath = join(dir, 'state.json');
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    return { statePath };
+}
+export async function restoreMergeState(input) {
+    const dir = mergeStateDir(input);
+    const statePath = join(dir, 'state.json');
+    const originalPath = join(dir, 'original.md');
+    const original = await readFile(originalPath, 'utf8');
+    await mkdir(dirname(input.filePath), { recursive: true });
+    await writeFile(input.filePath, original, 'utf8');
+    await rm(dir, { recursive: true, force: true });
+    return { restored: true, statePath };
+}

package/dist/merge/run-merge.d.ts

@@ -0,0 +1,38 @@
+import type { FeishuAdapter } from '../adapters/feishu-adapter.js';
+import type { PublishProfileName } from '../profiles/publish-profile.js';
+import { type PublishReceiptTarget } from '../receipts/publish-receipt.js';
+import { type MergeState } from './line-merge.js';
+export type RunMergeMode = 'write' | 'check' | 'dry-run' | 'abort';
+export type RunMergeState = MergeState | 'aborted';
+export type RunMergeResult = {
+    mode: RunMergeMode;
+    state: RunMergeState;
+    file: string;
+    profile: PublishProfileName;
+    base?: {
+        source: 'explicit' | 'receipt' | 'current-local' | 'none';
+        hash?: string;
+    };
+    remote?: {
+        source: 'target' | 'remote-file';
+        hash: string;
+        savedPath?: string;
+        revision?: string;
+    };
+    summary: {
+        conflicts: number;
+        changed: boolean;
+    };
+    warnings: string[];
+};
+export declare function runMerge(input: {
+    cwd: string;
+    filePath: string;
+    profile: PublishProfileName;
+    mode: RunMergeMode;
+    target?: PublishReceiptTarget;
+    remotePath?: string;
+    basePath?: string;
+    saveRemotePath?: string;
+    adapter: FeishuAdapter;
+}): Promise<RunMergeResult>;

package/dist/merge/run-merge.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { hashText, readLocalBaseSnapshot, readPublishReceipt } from '../receipts/publish-receipt.js';
+import { applyPullTransformForProfile } from '../transform/zilliz-pull.js';
+import { mergeLines, mergeWithoutBase } from './line-merge.js';
+import { assertNoMergeState, restoreMergeState, writeMergeState } from './merge-state.js';
+export async function runMerge(input) {
+    if (input.mode === 'abort') {
+        await restoreMergeState({ cwd: input.cwd, filePath: input.filePath });
+        return {
+            mode: 'abort',
+            state: 'aborted',
+            file: input.filePath,
+            profile: input.profile,
+            summary: { conflicts: 0, changed: true },
+            warnings: []
+        };
+    }
+    if (!input.target && !input.remotePath) {
+        throw new Error('merge requires either --target or --remote');
+    }
+    if (input.target && input.remotePath) {
+        throw new Error('merge accepts only one of --target or --remote');
+    }
+    const local = await readFile(input.filePath, 'utf8');
+    assertNoConflictMarkers(local);
+    await assertNoMergeState({ cwd: input.cwd, filePath: input.filePath });
+    const remote = await resolveRemoteMarkdown(input);
+    const base = await resolveBaseMarkdown({ ...input, localMarkdown: local });
+    const merge = base.markdown === undefined
+        ? mergeWithoutBase({ local, remote: remote.markdown })
+        : mergeLines({ base: base.markdown, local, remote: remote.markdown });
+    if (input.mode === 'write' && merge.changed) {
+        await writeMergeState({
+            cwd: input.cwd,
+            filePath: input.filePath,
+            originalMarkdown: local,
+            target: input.target,
+            profile: input.profile
+        });
+        await writeFile(input.filePath, merge.markdown, 'utf8');
+    }
+    return {
+        mode: input.mode,
+        state: merge.state,
+        file: input.filePath,
+        profile: input.profile,
+        base: base.summary,
+        remote: remote.summary,
+        summary: {
+            conflicts: merge.conflicts,
+            changed: merge.changed
+        },
+        warnings: [...base.warnings, ...remote.warnings]
+    };
+}
+function assertNoConflictMarkers(markdown) {
+    if (/^<<<<<<< |^=======\s*$|^>>>>>>> /m.test(markdown)) {
+        throw new Error('Refusing to merge because the local file contains unresolved conflict markers.');
+    }
+}
+async function resolveRemoteMarkdown(input) {
+    if (input.remotePath) {
+        const raw = await readFile(input.remotePath, 'utf8');
+        const transformed = applyPullTransformForProfile(raw, input.profile);
+        return {
+            markdown: transformed.markdown,
+            warnings: transformed.warnings,
+            summary: {
+                source: 'remote-file',
+                hash: hashText(transformed.markdown)
+            }
+        };
+    }
+    const fetched = await input.adapter.fetchDocMarkdown({ doc: input.target.token });
+    const transformed = applyPullTransformForProfile(fetched.markdown, input.profile);
+    if (input.saveRemotePath) {
+        await mkdir(dirname(input.saveRemotePath), { recursive: true });
+        await writeFile(input.saveRemotePath, transformed.markdown, 'utf8');
+    }
+    return {
+        markdown: transformed.markdown,
+        warnings: transformed.warnings,
+        summary: {
+            source: 'target',
+            hash: hashText(transformed.markdown),
+            savedPath: input.saveRemotePath,
+            revision: fetched.revision
+        }
+    };
+}
+async function resolveBaseMarkdown(input) {
+    if (input.basePath) {
+        const markdown = await readFile(input.basePath, 'utf8');
+        return {
+            markdown,
+            summary: {
+                source: 'explicit',
+                hash: hashText(markdown)
+            },
+            warnings: []
+        };
+    }
+    if (input.target) {
+        const receipt = await readPublishReceipt({ cwd: input.cwd, target: input.target });
+        if (receipt?.localBaseSnapshot) {
+            const markdown = await readLocalBaseSnapshot({ cwd: input.cwd, snapshot: receipt.localBaseSnapshot });
+            if (markdown !== undefined) {
+                return {
+                    markdown,
+                    summary: {
+                        source: 'receipt',
+                        hash: hashText(markdown)
+                    },
+                    warnings: []
+                };
+            }
+        }
+        if (receipt?.localSourceHash === hashText(input.localMarkdown)) {
+            return {
+                markdown: input.localMarkdown,
+                summary: {
+                    source: 'current-local',
+                    hash: hashText(input.localMarkdown)
+                },
+                warnings: [
+                    'receipt has no readable local base snapshot; using current local file as merge base because it still matches the last published source'
+                ]
+            };
+        }
+    }
+    return {
+        markdown: undefined,
+        summary: {
+            source: 'none'
+        },
+        warnings: []
+    };
+}

package/dist/profiles/publish-profile.d.ts

@@ -0,0 +1,9 @@
+export declare const PUBLISH_PROFILES: readonly ["zilliz", "milvus", "none"];
+export type PublishProfileName = typeof PUBLISH_PROFILES[number];
+export type PublishProfileConfig = {
+    includeTargets?: string[];
+    excludeTargets?: string[];
+    productNameMarkup?: boolean;
+};
+export declare function isPublishProfileName(value: string): value is PublishProfileName;
+export declare function parsePublishProfileName(value: string, label: string): PublishProfileName;

package/dist/profiles/publish-profile.js

@@ -0,0 +1,9 @@
+export const PUBLISH_PROFILES = ['zilliz', 'milvus', 'none'];
+export function isPublishProfileName(value) {
+    return PUBLISH_PROFILES.includes(value);
+}
+export function parsePublishProfileName(value, label) {
+    if (isPublishProfileName(value))
+        return value;
+    throw new Error(`Invalid ${label} ${value}. Expected zilliz, milvus, or none.`);
+}

package/dist/publish/block-patch-plan.d.ts

@@ -0,0 +1,34 @@
+import type { FeishuBlock } from '../feishu/types.js';
+export type PublishBlockPatchOperation = {
+    kind: 'update';
+    remoteBlockId: string;
+    path: number[];
+    blockType: number;
+} | {
+    kind: 'create';
+    parentBlockId: string;
+    insertAfterBlockId: string;
+    index: number;
+    path: number[];
+    blocks: FeishuBlock[];
+} | {
+    kind: 'delete';
+    parentBlockId: string;
+    blockIds: string[];
+    startIndex: number;
+    endIndex: number;
+    path: number[];
+};
+export type PublishBlockPatchPlan = {
+    kind: 'publish-block-patch-plan';
+    safeToWrite: boolean;
+    requiresCollaborationRiskConfirmation: boolean;
+    operations: PublishBlockPatchOperation[];
+    fallbackReason?: string;
+    warnings: string[];
+};
+export declare function planPublishBlockPatch(input: {
+    parentBlockId: string;
+    remoteBlocks: FeishuBlock[];
+    desiredBlocks: FeishuBlock[];
+}): PublishBlockPatchPlan;