feishu-md-sync 0.1.0

package/dist/publish/block-patch-plan.js

@@ -0,0 +1,223 @@
+import { sha256, stableStringify } from '../core/hash.js';
+import { feishuBlocksToMarkdown } from '../markdown/from-blocks.js';
+import { isTextLikeBlockPairUpdateable } from './block-update.js';
+export function planPublishBlockPatch(input) {
+    const state = {
+        operations: [],
+        warnings: []
+    };
+    const fallbackReason = planSequence({
+        parentBlockId: input.parentBlockId,
+        remoteBlocks: input.remoteBlocks,
+        desiredBlocks: input.desiredBlocks,
+        path: [],
+        state
+    });
+    const requiresCollaborationRiskConfirmation = state.operations.some((operation) => {
+        return operation.kind === 'update' || operation.kind === 'delete';
+    });
+    return {
+        kind: 'publish-block-patch-plan',
+        safeToWrite: fallbackReason === undefined,
+        requiresCollaborationRiskConfirmation,
+        operations: fallbackReason ? [] : state.operations,
+        fallbackReason,
+        warnings: state.warnings
+    };
+}
+function planSequence(input) {
+    if (blocksEquivalent(input.remoteBlocks, input.desiredBlocks))
+        return undefined;
+    const prefixLength = commonPrefixLength(input.remoteBlocks, input.desiredBlocks);
+    const suffixLength = commonSuffixLength(input.remoteBlocks, input.desiredBlocks, prefixLength);
+    const remoteMiddleEnd = input.remoteBlocks.length - suffixLength;
+    const desiredMiddleEnd = input.desiredBlocks.length - suffixLength;
+    const remoteMiddle = input.remoteBlocks.slice(prefixLength, remoteMiddleEnd);
+    const desiredMiddle = input.desiredBlocks.slice(prefixLength, desiredMiddleEnd);
+    if (remoteMiddle.length === 0 && desiredMiddle.length > 0) {
+        const unsupported = desiredMiddle.find((block) => !isWritableMarkdownBlockForPatch(block));
+        if (unsupported) {
+            return `create block_type ${unsupported.block_type} is unsupported at ${formatPath([...input.path, prefixLength])}`;
+        }
+        const insertAfterBlockId = insertAfterBlockIdForCreate(input.remoteBlocks, input.parentBlockId, prefixLength);
+        if (!insertAfterBlockId) {
+            return `create anchor is missing at ${formatPath([...input.path, prefixLength])}`;
+        }
+        input.state.operations.push({
+            kind: 'create',
+            parentBlockId: input.parentBlockId,
+            insertAfterBlockId,
+            index: prefixLength,
+            path: [...input.path, prefixLength],
+            blocks: desiredMiddle
+        });
+        return undefined;
+    }
+    if (remoteMiddle.length > 0 && desiredMiddle.length === 0) {
+        const unsupported = remoteMiddle.find((block) => !isWritableMarkdownBlockForPatch(block));
+        if (unsupported) {
+            return `delete block_type ${unsupported.block_type} is unsupported at ${formatPath([...input.path, prefixLength])}`;
+        }
+        const blockIds = blockIdsForDelete(remoteMiddle);
+        if (blockIds.length !== remoteMiddle.length) {
+            return `delete block id is missing at ${formatPath([...input.path, prefixLength])}`;
+        }
+        input.state.operations.push({
+            kind: 'delete',
+            parentBlockId: input.parentBlockId,
+            blockIds,
+            startIndex: prefixLength,
+            endIndex: remoteMiddleEnd,
+            path: [...input.path, prefixLength]
+        });
+        return undefined;
+    }
+    if (remoteMiddle.length !== desiredMiddle.length) {
+        return `block order or count changed at ${formatPath(input.path)}`;
+    }
+    for (let index = 0; index < remoteMiddle.length; index += 1) {
+        const remote = remoteMiddle[index];
+        const desired = desiredMiddle[index];
+        const absoluteIndex = prefixLength + index;
+        const childPath = [...input.path, absoluteIndex];
+        const fallbackReason = planBlockPair({
+            remote,
+            desired,
+            path: childPath,
+            state: input.state
+        });
+        if (fallbackReason)
+            return fallbackReason;
+    }
+    return undefined;
+}
+function planBlockPair(input) {
+    if (blocksEquivalent([input.remote], [input.desired]))
+        return undefined;
+    if (isWhiteboardBlock(input.remote) || isWhiteboardBlock(input.desired)) {
+        return `whiteboard block changed at ${formatPath(input.path)}`;
+    }
+    if (hasBlockChildren(input.remote) || hasBlockChildren(input.desired)) {
+        if (!input.remote.block_id)
+            return `container block is missing block id at ${formatPath(input.path)}`;
+        if (input.remote.block_type !== input.desired.block_type) {
+            return `container block type changed at ${formatPath(input.path)}`;
+        }
+        if (!hasBlockChildren(input.remote) || !hasBlockChildren(input.desired)) {
+            return `container block structure changed at ${formatPath(input.path)}`;
+        }
+        if (!containerShellEquivalent(input.remote, input.desired)) {
+            return `container block shell changed at ${formatPath(input.path)}`;
+        }
+        return planSequence({
+            parentBlockId: input.remote.block_id,
+            remoteBlocks: input.remote.children,
+            desiredBlocks: input.desired.children,
+            path: input.path,
+            state: input.state
+        });
+    }
+    if (!isTextLikeBlockPairUpdateable(input.remote, input.desired)) {
+        return `unsupported block change at ${formatPath(input.path)}`;
+    }
+    input.state.operations.push({
+        kind: 'update',
+        remoteBlockId: input.remote.block_id,
+        path: input.path,
+        blockType: input.remote.block_type
+    });
+    return undefined;
+}
+function commonPrefixLength(remote, desired) {
+    const maxLength = Math.min(remote.length, desired.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        if (!blocksEquivalent([remote[index]], [desired[index]]))
+            return index;
+    }
+    return maxLength;
+}
+function commonSuffixLength(remote, desired, prefixLength) {
+    const maxLength = Math.min(remote.length, desired.length) - prefixLength;
+    for (let offset = 0; offset < maxLength; offset += 1) {
+        const remoteIndex = remote.length - 1 - offset;
+        const desiredIndex = desired.length - 1 - offset;
+        if (!blocksEquivalent([remote[remoteIndex]], [desired[desiredIndex]]))
+            return offset;
+    }
+    return maxLength;
+}
+function blocksEquivalent(remote, desired) {
+    return hashComparableBlocks(remote) === hashComparableBlocks(desired) ||
+        (canUseCanonicalMarkdown(remote) && canUseCanonicalMarkdown(desired) && canonicalMarkdown(remote) === canonicalMarkdown(desired));
+}
+function containerShellEquivalent(remote, desired) {
+    return hashComparableBlocks([stripContainerChildren(remote)]) === hashComparableBlocks([stripContainerChildren(desired)]);
+}
+function hashComparableBlocks(blocks) {
+    return sha256(stableStringify(blocks.map(normalizeBlockForPatch)));
+}
+function normalizeBlockForPatch(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalizeBlockForPatch);
+    }
+    if (value && typeof value === 'object') {
+        const normalized = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === 'block_id')
+                continue;
+            if (key === 'parent_id')
+                continue;
+            if (key === 'merge_info')
+                continue;
+            normalized[key] = normalizeBlockForPatch(child);
+        }
+        return normalized;
+    }
+    return value;
+}
+function canonicalMarkdown(blocks) {
+    return feishuBlocksToMarkdown(blocks)
+        .replace(/\r\n/g, '\n')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function canUseCanonicalMarkdown(blocks) {
+    return blocks.every((block) => isWritableMarkdownBlockForPatch(block) && block.block_type !== 31);
+}
+function stripContainerChildren(block) {
+    const { children: _children, block_id: _blockId, parent_id: _parentId, ...rest } = block;
+    return rest;
+}
+function hasBlockChildren(block) {
+    return Array.isArray(block.children) && block.children.every(isFeishuBlock);
+}
+function isFeishuBlock(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value) && 'block_type' in value);
+}
+function isWhiteboardBlock(block) {
+    return 'whiteboard' in block;
+}
+function insertAfterBlockIdForCreate(remoteBlocks, parentBlockId, index) {
+    if (index === 0)
+        return parentBlockId;
+    const previous = remoteBlocks[index - 1];
+    return previous?.block_id;
+}
+function blockIdsForDelete(blocks) {
+    return blocks.flatMap((block) => block.block_id ? [block.block_id] : []);
+}
+function isWritableMarkdownBlockForPatch(block) {
+    const writableType = block.block_type === 2 || (block.block_type >= 3 && block.block_type <= 8) || block.block_type === 12 || block.block_type === 13 || block.block_type === 14 || block.block_type === 31;
+    if (!writableType)
+        return false;
+    if (Array.isArray(block.children) && block.children.length > 0)
+        return false;
+    if (block.block_type !== 31)
+        return true;
+    const cells = block.table?.cells ?? [];
+    return cells.every((cell) => isFeishuBlock(cell) && cell.block_type === 2 && (!Array.isArray(cell.children) || cell.children.length === 0));
+}
+function formatPath(path) {
+    return path.length === 0 ? '<root>' : path.join('.');
+}

package/dist/publish/block-state.d.ts

@@ -0,0 +1,8 @@
+import type { FeishuBlock } from '../feishu/types.js';
+export type PageBlock = FeishuBlock & {
+    block_id: string;
+};
+export declare function findPageBlock(blocks: FeishuBlock[], documentId: string): PageBlock;
+export declare function directChildBlocks(blocks: FeishuBlock[], pageBlock: FeishuBlock): FeishuBlock[];
+export declare function comparableDirectChildBlocks(blocks: FeishuBlock[], pageBlock: FeishuBlock): FeishuBlock[];
+export declare function renderableDirectChildBlocks(blocks: FeishuBlock[], pageBlock: FeishuBlock): FeishuBlock[];

package/dist/publish/block-state.js

@@ -0,0 +1,82 @@
+export function findPageBlock(blocks, documentId) {
+    const page = blocks.find((block) => block.block_type === 1) ?? blocks.find((block) => block.block_id === documentId);
+    if (!page?.block_id) {
+        throw new Error(`Could not find page block for document ${documentId}.`);
+    }
+    return page;
+}
+export function directChildBlocks(blocks, pageBlock) {
+    const byId = blockMapById(blocks);
+    const children = Array.isArray(pageBlock.children) ? pageBlock.children : [];
+    return children
+        .map((child) => (typeof child === 'string' ? byId.get(child) : child))
+        .filter((child) => Boolean(child));
+}
+export function comparableDirectChildBlocks(blocks, pageBlock) {
+    const byId = blockMapById(blocks);
+    return directChildBlocks(blocks, pageBlock).map((block) => comparableBlock(block, byId));
+}
+export function renderableDirectChildBlocks(blocks, pageBlock) {
+    const byId = blockMapById(blocks);
+    return directChildBlocks(blocks, pageBlock).flatMap((block) => renderableBlocks(block, byId));
+}
+function blockMapById(blocks) {
+    return new Map(blocks.flatMap((block) => block.block_id ? [[block.block_id, block]] : []));
+}
+function renderableBlocks(block, byId) {
+    if (block.block_type === 19 && Array.isArray(block.children)) {
+        return [resolveChildContainer(block, byId)];
+    }
+    if (block.block_type !== 49 || !Array.isArray(block.children)) {
+        return [comparableBlock(block, byId)];
+    }
+    return block.children.flatMap((childRef) => {
+        const child = typeof childRef === 'string' ? byId.get(childRef) : asBlock(childRef);
+        return child ? renderableBlocks(child, byId) : [];
+    });
+}
+function resolveChildContainer(block, byId) {
+    const children = Array.isArray(block.children)
+        ? block.children
+            .map((childRef) => (typeof childRef === 'string' ? byId.get(childRef) : asBlock(childRef)))
+            .filter((child) => Boolean(child))
+            .map((child) => comparableBlock(child, byId))
+        : [];
+    return {
+        ...block,
+        children
+    };
+}
+function comparableBlock(block, byId) {
+    if (block.block_type === 49 && Array.isArray(block.children)) {
+        return resolveChildContainer(block, byId);
+    }
+    if (block.block_type !== 31 || !isTableBlock(block)) {
+        return block;
+    }
+    const cellRefs = block.table.cells ?? [];
+    const resolvedCells = cellRefs.map((cellRef) => {
+        const cellBlock = typeof cellRef === 'string' ? byId.get(cellRef) : asBlock(cellRef);
+        const firstChildRef = Array.isArray(cellBlock?.children) ? cellBlock.children[0] : undefined;
+        const firstChild = typeof firstChildRef === 'string' ? byId.get(firstChildRef) : asBlock(firstChildRef);
+        return firstChild ?? { block_type: 2, text: { elements: [], style: { align: 1 } } };
+    });
+    return {
+        ...block,
+        table: {
+            ...block.table,
+            cells: resolvedCells
+        }
+    };
+}
+function isTableBlock(block) {
+    return Boolean(block.table &&
+        typeof block.table === 'object' &&
+        !Array.isArray(block.table));
+}
+function asBlock(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && 'block_type' in value) {
+        return value;
+    }
+    return undefined;
+}

package/dist/publish/block-update.d.ts

@@ -0,0 +1,4 @@
+import type { FeishuBlock, FeishuBlockUpdateRequest, TextElement } from '../feishu/types.js';
+export declare function isTextLikeBlockPairUpdateable(remote: FeishuBlock, desired: FeishuBlock): boolean;
+export declare function buildTextLikeBlockUpdateRequest(remote: FeishuBlock, desired: FeishuBlock): FeishuBlockUpdateRequest;
+export declare function elementsForBlock(block: FeishuBlock): TextElement[] | null;

package/dist/publish/block-update.js

@@ -0,0 +1,40 @@
+const TEXT_LIKE_KEYS = {
+    2: 'text',
+    3: 'heading1',
+    4: 'heading2',
+    5: 'heading3',
+    6: 'heading4',
+    7: 'heading5',
+    8: 'heading6',
+    12: 'bullet',
+    13: 'ordered',
+    14: 'code'
+};
+export function isTextLikeBlockPairUpdateable(remote, desired) {
+    if (!remote.block_id)
+        return false;
+    if (remote.block_type !== desired.block_type)
+        return false;
+    return Boolean(TEXT_LIKE_KEYS[remote.block_type] && elementsForBlock(desired));
+}
+export function buildTextLikeBlockUpdateRequest(remote, desired) {
+    if (!remote.block_id || !isTextLikeBlockPairUpdateable(remote, desired)) {
+        throw new Error(`Block ${remote.block_id ?? '<missing id>'} cannot be updated in place.`);
+    }
+    return {
+        block_id: remote.block_id,
+        update_text_elements: {
+            elements: elementsForBlock(desired) ?? []
+        }
+    };
+}
+export function elementsForBlock(block) {
+    const key = TEXT_LIKE_KEYS[block.block_type];
+    if (!key)
+        return null;
+    const value = block[key];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const elements = value.elements;
+    return Array.isArray(elements) ? elements : null;
+}

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

@@ -0,0 +1,5 @@
+import type { PublishProfileName } from '../profiles/publish-profile.js';
+export declare function applyPublishTransformForProfile(markdown: string, profile: PublishProfileName): {
+    markdown: string;
+    warnings: string[];
+};

package/dist/publish/profile-transform.js

@@ -0,0 +1,6 @@
+import { applyZillizPublishTransform } from '../transform/zilliz-publish.js';
+export function applyPublishTransformForProfile(markdown, profile) {
+    if (profile === 'zilliz')
+        return applyZillizPublishTransform(markdown);
+    return { markdown, warnings: [] };
+}

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

@@ -0,0 +1,35 @@
+import type { PublishProfileName } from '../profiles/publish-profile.js';
+import { type PublishReceipt, type PublishReceiptTarget } from '../receipts/publish-receipt.js';
+import type { PublishBlockPatchPlan } from './block-patch-plan.js';
+export type PublishStrategy = 'no-op' | 'block-patch' | 'section-replace' | 'document-replace' | 'create-document';
+export type PublishPlan = {
+    target: PublishReceiptTarget;
+    profile: PublishProfileName;
+    strategy: PublishStrategy;
+    safeToWrite: boolean;
+    remoteChanged: boolean;
+    localSourceHash: string;
+    publishDraftHash: string;
+    remoteSnapshotHash: string;
+    requiresCollaborationRiskConfirmation: boolean;
+    requiresUntrackedRemoteConfirmation: boolean;
+    blockPatch?: {
+        operations: PublishBlockPatchPlan['operations'];
+        requiresCollaborationRiskConfirmation: boolean;
+        fallbackReason?: string;
+        warnings: string[];
+    };
+    risks: string[];
+    warnings: string[];
+};
+export declare function buildPublishPlan(input: {
+    target: PublishReceiptTarget;
+    profile: PublishProfileName;
+    localSource: string;
+    publishDraft: string;
+    remoteMarkdown: string;
+    receipt: PublishReceipt | undefined;
+    transformWarnings: string[];
+    createDocument?: boolean;
+    blockPatch?: PublishBlockPatchPlan;
+}): PublishPlan;

package/dist/publish/publish-plan.js

@@ -0,0 +1,113 @@
+import { hashText } from '../receipts/publish-receipt.js';
+export function buildPublishPlan(input) {
+    const localSourceHash = hashText(input.localSource);
+    const publishDraftHash = hashText(input.publishDraft);
+    const remoteSnapshotHash = hashText(input.remoteMarkdown);
+    if (input.target.kind === 'folder' || input.createDocument === true) {
+        return {
+            target: input.target,
+            profile: input.profile,
+            strategy: 'create-document',
+            safeToWrite: true,
+            remoteChanged: false,
+            localSourceHash,
+            publishDraftHash,
+            remoteSnapshotHash,
+            requiresCollaborationRiskConfirmation: false,
+            requiresUntrackedRemoteConfirmation: false,
+            risks: [],
+            warnings: input.transformWarnings
+        };
+    }
+    const remoteChanged = input.receipt ? input.receipt.remoteSnapshotHash !== remoteSnapshotHash : false;
+    const risks = [];
+    if (!input.receipt)
+        risks.push('untracked remote: no publish receipt exists for this target');
+    if (remoteChanged)
+        risks.push('remote changed since last publish receipt');
+    if (publishDraftHash === remoteSnapshotHash) {
+        return {
+            target: input.target,
+            profile: input.profile,
+            strategy: 'no-op',
+            safeToWrite: true,
+            remoteChanged,
+            localSourceHash,
+            publishDraftHash,
+            remoteSnapshotHash,
+            requiresCollaborationRiskConfirmation: false,
+            requiresUntrackedRemoteConfirmation: false,
+            risks,
+            warnings: input.transformWarnings
+        };
+    }
+    if (input.blockPatch?.safeToWrite === true && !remoteChanged) {
+        if (input.blockPatch.operations.length === 0) {
+            return {
+                target: input.target,
+                profile: input.profile,
+                strategy: 'no-op',
+                safeToWrite: true,
+                remoteChanged,
+                localSourceHash,
+                publishDraftHash,
+                remoteSnapshotHash,
+                requiresCollaborationRiskConfirmation: false,
+                requiresUntrackedRemoteConfirmation: false,
+                blockPatch: {
+                    operations: [],
+                    requiresCollaborationRiskConfirmation: false,
+                    fallbackReason: input.blockPatch.fallbackReason,
+                    warnings: input.blockPatch.warnings
+                },
+                risks,
+                warnings: input.transformWarnings
+            };
+        }
+        if (!input.receipt) {
+            risks.push('untracked remote block-patch requires explicit confirmation');
+        }
+        if (input.blockPatch.requiresCollaborationRiskConfirmation) {
+            risks.push('changed blocks may lose comments, anchors, or block identity when replaced');
+        }
+        return {
+            target: input.target,
+            profile: input.profile,
+            strategy: 'block-patch',
+            safeToWrite: Boolean(input.receipt) && !input.blockPatch.requiresCollaborationRiskConfirmation,
+            remoteChanged,
+            localSourceHash,
+            publishDraftHash,
+            remoteSnapshotHash,
+            requiresCollaborationRiskConfirmation: input.blockPatch.requiresCollaborationRiskConfirmation,
+            requiresUntrackedRemoteConfirmation: !input.receipt,
+            blockPatch: {
+                operations: input.blockPatch.operations,
+                requiresCollaborationRiskConfirmation: input.blockPatch.requiresCollaborationRiskConfirmation,
+                fallbackReason: input.blockPatch.fallbackReason,
+                warnings: input.blockPatch.warnings
+            },
+            risks,
+            warnings: input.transformWarnings
+        };
+    }
+    if (input.blockPatch && !input.blockPatch.safeToWrite && input.blockPatch.fallbackReason) {
+        risks.push(`block-patch unavailable: ${input.blockPatch.fallbackReason}`);
+    }
+    const strategy = 'document-replace';
+    risks.push('document replace can affect comments, anchors, block identity, and collaboration context');
+    return {
+        target: input.target,
+        profile: input.profile,
+        strategy,
+        safeToWrite: false,
+        remoteChanged,
+        localSourceHash,
+        publishDraftHash,
+        remoteSnapshotHash,
+        requiresCollaborationRiskConfirmation: false,
+        requiresUntrackedRemoteConfirmation: false,
+        risks,
+        warnings: input.transformWarnings
+    };
+}

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

@@ -0,0 +1,25 @@
+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 PublishPlan, type PublishStrategy } from './publish-plan.js';
+export type RunPublishResult = {
+    mode: 'dry-run' | 'write';
+    plan: PublishPlan;
+    document?: {
+        documentId: string;
+        url?: string;
+    };
+};
+export declare function runPublish(input: {
+    cwd: string;
+    file: string;
+    target: PublishReceiptTarget;
+    profile: PublishProfileName;
+    write: boolean;
+    create: boolean;
+    strategy: 'auto' | PublishStrategy;
+    confirmDestructive: boolean;
+    confirmCollaborationRisk?: boolean;
+    confirmUntrackedRemote?: boolean;
+    adapter: FeishuAdapter;
+}): Promise<RunPublishResult>;