feishu-md-sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liyun95
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,5 @@
+This project is an independent Markdown-to-Feishu CLI.
+
+Feishu API endpoint shapes and block-conversion behavior were informed by
+separate internal reference tooling. No runtime dependency on that tooling is
+used.

package/README.md

@@ -0,0 +1,107 @@
+# feishu-md-sync
+
+`feishu-md-sync` is a dry-run-first sync bridge between local Markdown and Feishu/Lark online documents. It uses the official `lark-cli` for authentication and Feishu document IO, then adds profiles, receipts, safety gates, status, diff, pull, merge, and publish UX.
+
+Docs site: <https://liyun95.github.io/feishu-md-sync/>
+
+## Install
+
+Install and authenticate the official Lark CLI:
+
+```bash
+npx @larksuite/cli@latest install
+lark-cli auth login --domain docs,wiki,drive
+lark-cli auth status --verify
+```
+
+Install `feishu-md-sync` globally:
+
+```bash
+npm install --global feishu-md-sync
+feishu-md-sync --help
+```
+
+The selected `lark-cli` identity must have access to the target document, Drive folder, or Wiki parent.
+
+## Main Commands
+
+| Need | Command |
+| --- | --- |
+| Publish local Markdown to Feishu | `feishu-md-sync publish` |
+| Create a new Feishu document from Markdown | `feishu-md-sync publish --create` |
+| Pull a remote Markdown snapshot | `feishu-md-sync pull` |
+| Check local/remote state | `feishu-md-sync status` |
+| Inspect publish diff | `feishu-md-sync diff` |
+| Merge remote edits into local Markdown | `feishu-md-sync merge` |
+
+## Common Flow
+
+The default profile is `none`. Start with a read-only status check and diff:
+
+```bash
+feishu-md-sync status ./doc.md --target DocToken
+feishu-md-sync diff ./doc.md --target DocToken
+```
+
+Preview a publish without writing to Feishu:
+
+```bash
+feishu-md-sync publish ./doc.md --target DocToken
+```
+
+Write to an existing remote document for the first time after reviewing the plan:
+
+```bash
+feishu-md-sync publish ./doc.md --target DocToken --write --confirm-untracked-remote
+feishu-md-sync status ./doc.md --target DocToken
+```
+
+If the remote document changed, pull a reviewable snapshot and merge it locally:
+
+```bash
+feishu-md-sync pull --target DocToken --output doc.remote.md --write-receipt
+feishu-md-sync merge ./doc.md --target DocToken
+feishu-md-sync publish ./doc.md --target DocToken --write
+```
+
+When the merge already makes the publish draft match Feishu, the final write is a no-op remote update that refreshes the local receipt and merge base.
+
+Create a new document under a Drive folder or Wiki parent:
+
+```bash
+feishu-md-sync publish ./doc.md --target FolderOrWikiToken --create --write
+```
+
+Inspect local auth loading without printing secrets:
+
+```bash
+feishu-md-sync doctor auth --format json
+```
+
+## Profiles
+
+Omit `--profile` or use `--profile none` for general Markdown sync.
+
+Use `--profile zilliz` when local Markdown uses Milvus wording but the Feishu document is a Zilliz Cloud publishing draft. Use `--profile milvus` mainly when pulling or merging that content back into the local Milvus-shaped source.
+
+## Safety Model
+
+- Remote writes require `publish --write`.
+- The first write to an existing untracked document also requires `--confirm-untracked-remote`.
+- Block-patch updates or deletions that may affect comments, anchors, or block identity require `--confirm-collaboration-risk`.
+- Whole-document replacement requires `--strategy document-replace --confirm-destructive`.
+- `status` and `diff` are read-only; `merge` writes only local files and supports `--abort`.
+
+## Development
+
+From a repository checkout:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm test
+npm run test:package
+```
+
+Generated outputs such as `dist/` and `coverage/` should not be committed.

package/dist/adapters/feishu-adapter.d.ts

@@ -0,0 +1,44 @@
+import type { FeishuBlock } from '../feishu/types.js';
+export type RemoteMarkdown = {
+    markdown: string;
+    revision?: string;
+};
+export type RemoteBlocks = {
+    blocks: FeishuBlock[];
+};
+export type CreatedDocument = {
+    documentId: string;
+    url?: string;
+    revision?: string;
+};
+export type FeishuAdapter = {
+    fetchDocMarkdown(input: {
+        doc: string;
+    }): Promise<RemoteMarkdown>;
+    fetchDocBlocks?(input: {
+        doc: string;
+    }): Promise<RemoteBlocks>;
+    replaceDocument(input: {
+        doc: string;
+        markdown: string;
+    }): Promise<void>;
+    replaceBlock?(input: {
+        doc: string;
+        blockId: string;
+        markdown: string;
+    }): Promise<void>;
+    insertBlocksAfter?(input: {
+        doc: string;
+        blockId: string;
+        markdown: string;
+    }): Promise<void>;
+    deleteBlocks?(input: {
+        doc: string;
+        blockIds: string[];
+    }): Promise<void>;
+    createDocument(input: {
+        title: string;
+        markdown: string;
+        parentToken: string;
+    }): Promise<CreatedDocument>;
+};

package/dist/adapters/feishu-adapter.js

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

package/dist/adapters/lark-cli-adapter.d.ts

@@ -0,0 +1,45 @@
+import type { CreatedDocument, FeishuAdapter, RemoteBlocks, RemoteMarkdown } from './feishu-adapter.js';
+export type LarkCliExecResult = {
+    stdout: string;
+    stderr: string;
+};
+export type LarkCliExecutor = (args: string[]) => Promise<LarkCliExecResult>;
+export type LarkCliIdentity = 'auto' | 'bot' | 'user';
+export declare class LarkCliAdapter implements FeishuAdapter {
+    private readonly exec;
+    private readonly identity;
+    constructor(input?: {
+        exec?: LarkCliExecutor;
+        identity?: LarkCliIdentity;
+    });
+    fetchDocMarkdown(input: {
+        doc: string;
+    }): Promise<RemoteMarkdown>;
+    fetchDocBlocks(input: {
+        doc: string;
+    }): Promise<RemoteBlocks>;
+    replaceDocument(input: {
+        doc: string;
+        markdown: string;
+    }): Promise<void>;
+    replaceBlock(input: {
+        doc: string;
+        blockId: string;
+        markdown: string;
+    }): Promise<void>;
+    insertBlocksAfter(input: {
+        doc: string;
+        blockId: string;
+        markdown: string;
+    }): Promise<void>;
+    deleteBlocks(input: {
+        doc: string;
+        blockIds: string[];
+    }): Promise<void>;
+    createDocument(input: {
+        title: string;
+        markdown: string;
+        parentToken: string;
+    }): Promise<CreatedDocument>;
+    private updateMarkdownBlock;
+}

package/dist/adapters/lark-cli-adapter.js

@@ -0,0 +1,229 @@
+import { execFile } from 'node:child_process';
+export class LarkCliAdapter {
+    exec;
+    identity;
+    constructor(input = {}) {
+        this.exec = input.exec ?? runLarkCli;
+        this.identity = input.identity ?? larkCliIdentityFromEnv();
+    }
+    async fetchDocMarkdown(input) {
+        const result = await this.exec(withIdentity([
+            'docs',
+            '+fetch',
+            '--doc',
+            input.doc,
+            '--doc-format',
+            'markdown',
+            '--format',
+            'json'
+        ], this.identity));
+        const data = parseLarkCliJson(result);
+        const content = markdownContentFromData(data.data);
+        if (typeof content !== 'string') {
+            throw new Error('lark-cli docs +fetch did not return document content.');
+        }
+        const revision = revisionFromData(data.data);
+        return { markdown: content, revision };
+    }
+    async fetchDocBlocks(input) {
+        const blocks = [];
+        let pageToken;
+        do {
+            const params = {
+                page_size: 500,
+                document_revision_id: -1
+            };
+            if (pageToken)
+                params.page_token = pageToken;
+            const result = await this.exec(withIdentity([
+                'api',
+                'GET',
+                `/open-apis/docx/v1/documents/${input.doc}/blocks`,
+                '--params',
+                JSON.stringify(params),
+                '--format',
+                'json'
+            ], this.identity));
+            const parsed = parseLarkCliJson(result);
+            const page = blockPageFromData(parsed.data);
+            blocks.push(...page.items);
+            pageToken = page.hasMore ? page.pageToken : undefined;
+        } while (pageToken);
+        return { blocks };
+    }
+    async replaceDocument(input) {
+        parseLarkCliJson(await this.exec(withIdentity([
+            'docs',
+            '+update',
+            '--doc',
+            input.doc,
+            '--command',
+            'overwrite',
+            '--doc-format',
+            'markdown',
+            '--content',
+            input.markdown,
+            '--format',
+            'json'
+        ], this.identity)));
+    }
+    async replaceBlock(input) {
+        await this.updateMarkdownBlock({
+            doc: input.doc,
+            command: 'block_replace',
+            blockId: input.blockId,
+            markdown: input.markdown
+        });
+    }
+    async insertBlocksAfter(input) {
+        await this.updateMarkdownBlock({
+            doc: input.doc,
+            command: 'block_insert_after',
+            blockId: input.blockId,
+            markdown: input.markdown
+        });
+    }
+    async deleteBlocks(input) {
+        parseLarkCliJson(await this.exec(withIdentity([
+            'docs',
+            '+update',
+            '--doc',
+            input.doc,
+            '--command',
+            'block_delete',
+            '--block-id',
+            input.blockIds.join(','),
+            '--format',
+            'json'
+        ], this.identity)));
+    }
+    async createDocument(input) {
+        const data = parseLarkCliJson(await this.exec(withIdentity([
+            'docs',
+            '+create',
+            '--title',
+            input.title,
+            '--doc-format',
+            'markdown',
+            '--content',
+            input.markdown,
+            '--parent-token',
+            input.parentToken,
+            '--format',
+            'json'
+        ], this.identity)));
+        const document = documentFromData(data.data);
+        if (!document) {
+            throw new Error('lark-cli docs +create did not return data.document.');
+        }
+        const documentId = typeof document.document_id === 'string' ? document.document_id : undefined;
+        if (!documentId) {
+            throw new Error('lark-cli docs +create did not return document.document_id.');
+        }
+        return {
+            documentId,
+            url: typeof document.url === 'string' ? document.url : undefined,
+            revision: typeof document.revision_id === 'string' || typeof document.revision_id === 'number'
+                ? String(document.revision_id)
+                : undefined
+        };
+    }
+    async updateMarkdownBlock(input) {
+        parseLarkCliJson(await this.exec(withIdentity([
+            'docs',
+            '+update',
+            '--doc',
+            input.doc,
+            '--command',
+            input.command,
+            '--block-id',
+            input.blockId,
+            '--doc-format',
+            'markdown',
+            '--content',
+            input.markdown,
+            '--format',
+            'json'
+        ], this.identity)));
+    }
+}
+function withIdentity(args, identity) {
+    return identity === 'auto' ? args : [...args, '--as', identity];
+}
+function larkCliIdentityFromEnv() {
+    const value = process.env.FEISHU_MD_SYNC_LARK_AS;
+    return value === 'bot' || value === 'user' ? value : 'auto';
+}
+function runLarkCli(args) {
+    return new Promise((resolve, reject) => {
+        execFile('lark-cli', args, { encoding: 'utf8' }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+function parseLarkCliJson(result) {
+    const raw = result.stdout.trim() || result.stderr.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`lark-cli returned non-JSON output: ${raw}`);
+    }
+    if (parsed.ok === false) {
+        throw new Error(`lark-cli failed: ${parsed.error?.message ?? 'unknown error'}`);
+    }
+    return parsed;
+}
+function markdownContentFromData(data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    if ('content' in data && typeof data.content === 'string') {
+        return data.content;
+    }
+    if ('document' in data) {
+        const document = data.document;
+        if (document && typeof document === 'object' && typeof document.content === 'string') {
+            return document.content;
+        }
+    }
+    return undefined;
+}
+function revisionFromData(data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    if (typeof data.revision === 'string') {
+        return data.revision;
+    }
+    if ('document' in data) {
+        const document = data.document;
+        const revision = document && typeof document === 'object'
+            ? document.revision_id
+            : undefined;
+        return typeof revision === 'string' || typeof revision === 'number' ? String(revision) : undefined;
+    }
+    return undefined;
+}
+function documentFromData(data) {
+    if (!data || typeof data !== 'object' || !('document' in data))
+        return undefined;
+    const document = data.document;
+    return document && typeof document === 'object' ? document : undefined;
+}
+function blockPageFromData(data) {
+    if (!data || typeof data !== 'object') {
+        return { items: [], hasMore: false };
+    }
+    const record = data;
+    const items = Array.isArray(record.items) ? record.items.filter(isFeishuBlock) : [];
+    const hasMore = record.has_more === true;
+    const pageToken = typeof record.page_token === 'string' ? record.page_token : undefined;
+    return { items, hasMore, pageToken };
+}
+function isFeishuBlock(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value) && 'block_type' in value);
+}

package/dist/cli/commands/core.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerCoreCommands(program: Command): void;

package/dist/cli/commands/core.js

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { LarkCliAdapter } from '../../adapters/lark-cli-adapter.js';
+import { loadSyncConfig, resolvePublishProfile } from '../../config/sync-config.js';
+import { parseFeishuTarget } from '../../core/doc-id.js';
+import { diffSummaryLines, runDiff } from '../../diff/run-diff.js';
+import { runMerge } from '../../merge/run-merge.js';
+import { runPull } from '../../pull/run-pull.js';
+import { runStatus } from '../../status/run-status.js';
+import { printFormatted } from '../output.js';
+export function registerCoreCommands(program) {
+    program
+        .command('status')
+        .description('show local/remote publish status without writing')
+        .argument('<markdown-file>', 'local Markdown file')
+        .requiredOption('--target <url-or-token>', 'Feishu/Lark docx or wiki URL/token')
+        .option('--profile <profile>', 'publish profile: zilliz | milvus | none')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (markdownFile, opts) => {
+        const cwd = process.cwd();
+        const target = parseNonFolderTarget(opts.target ?? '', 'status');
+        const config = await loadSyncConfig({ cwd });
+        const profile = resolvePublishProfile({ cliProfile: opts.profile, config });
+        const result = await runStatus({
+            cwd,
+            sourcePath: path.resolve(cwd, markdownFile),
+            target,
+            profile,
+            adapter: new LarkCliAdapter()
+        });
+        printFormatted(result, opts.format);
+    });
+    program
+        .command('pull')
+        .description('export current Feishu/Lark content as a local Markdown snapshot')
+        .requiredOption('--target <url-or-token>', 'Feishu/Lark docx or wiki URL/token')
+        .requiredOption('-o, --output <file>', 'write remote Markdown to a local file')
+        .option('--profile <profile>', 'pull profile: zilliz | milvus | none')
+        .option('--overwrite', 'allow pull to replace an existing output file')
+        .option('--write-receipt', 'write a local pull snapshot receipt')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const target = parseNonFolderTarget(opts.target ?? '', 'pull');
+        const config = await loadSyncConfig({ cwd });
+        const profile = resolvePublishProfile({ cliProfile: opts.profile, config });
+        const result = await runPull({
+            cwd,
+            target,
+            outputPath: path.resolve(cwd, opts.output ?? ''),
+            profile,
+            overwrite: opts.overwrite === true,
+            writeReceipt: opts.writeReceipt === true,
+            adapter: new LarkCliAdapter()
+        });
+        printFormatted(result, opts.format);
+    });
+    program
+        .command('diff')
+        .description('show a publish-draft diff against current Feishu/Lark content')
+        .argument('<markdown-file>', 'local Markdown file')
+        .requiredOption('--target <url-or-token>', 'Feishu/Lark docx or wiki URL/token')
+        .option('--profile <profile>', 'publish profile: zilliz | milvus | none')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (markdownFile, opts) => {
+        const cwd = process.cwd();
+        const target = parseNonFolderTarget(opts.target ?? '', 'diff');
+        const config = await loadSyncConfig({ cwd });
+        const profile = resolvePublishProfile({ cliProfile: opts.profile, config });
+        const result = await runDiff({
+            cwd,
+            sourcePath: path.resolve(cwd, markdownFile),
+            target,
+            profile,
+            adapter: new LarkCliAdapter()
+        });
+        if (opts.format === 'json') {
+            printFormatted(result, opts.format);
+            return;
+        }
+        for (const line of diffSummaryLines(result))
+            console.log(line);
+    });
+    program
+        .command('merge')
+        .description('merge remote Feishu/Lark Markdown changes into a local Markdown file')
+        .argument('<markdown-file>', 'local Markdown file')
+        .option('--target <url-or-token>', 'Feishu/Lark docx or wiki URL/token to fetch before merging')
+        .option('--remote <file>', 'local remote snapshot Markdown file')
+        .option('--base <file>', 'explicit merge base Markdown file')
+        .option('--profile <profile>', 'local authoring profile: milvus | zilliz | none')
+        .option('--check', 'check whether merge would conflict without writing')
+        .option('--dry-run', 'show merge metadata without writing')
+        .option('--abort', 'restore the local file from the previous merge state')
+        .option('--save-remote <file>', 'save fetched remote snapshot when using --target')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (markdownFile, opts) => {
+        const cwd = process.cwd();
+        const config = await loadSyncConfig({ cwd });
+        const profile = resolvePublishProfile({ cliProfile: opts.profile, config });
+        const target = opts.target ? parseNonFolderTarget(opts.target, 'merge') : undefined;
+        const result = await runMerge({
+            cwd,
+            filePath: path.resolve(cwd, markdownFile),
+            target,
+            remotePath: opts.remote ? path.resolve(cwd, opts.remote) : undefined,
+            basePath: opts.base ? path.resolve(cwd, opts.base) : undefined,
+            saveRemotePath: opts.saveRemote ? path.resolve(cwd, opts.saveRemote) : undefined,
+            profile,
+            mode: resolveMergeMode(opts),
+            adapter: new LarkCliAdapter()
+        });
+        printFormatted(result, opts.format);
+        if (result.state === 'conflict')
+            process.exitCode = 1;
+    });
+}
+function parseNonFolderTarget(raw, command) {
+    const target = parseFeishuTarget(raw);
+    if (target.kind === 'folder') {
+        throw new Error(`${command} --target does not support Drive folder targets.`);
+    }
+    return target;
+}
+function resolveMergeMode(opts) {
+    const selected = [opts.check, opts.dryRun, opts.abort].filter(Boolean).length;
+    if (selected > 1)
+        throw new Error('Choose only one of --check, --dry-run, or --abort.');
+    if (opts.abort)
+        return 'abort';
+    if (opts.check)
+        return 'check';
+    if (opts.dryRun)
+        return 'dry-run';
+    return 'write';
+}

package/dist/cli/commands/publish.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerPublishCommand(program: Command): void;

package/dist/cli/commands/publish.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { LarkCliAdapter } from '../../adapters/lark-cli-adapter.js';
+import { loadSyncConfig, resolvePublishProfile } from '../../config/sync-config.js';
+import { parseFeishuTarget } from '../../core/doc-id.js';
+import { runPublish } from '../../publish/run-publish.js';
+import { printFormatted } from '../output.js';
+export function registerPublishCommand(program) {
+    program
+        .command('publish')
+        .description('publish local Markdown to an existing Feishu/Lark online document')
+        .argument('<markdown-file>', 'local Markdown file')
+        .requiredOption('--target <url-or-token>', 'existing Feishu/Lark docx URL or token')
+        .option('--profile <profile>', 'publish profile: zilliz | milvus | none')
+        .option('--write', 'write to Feishu/Lark; omitted means dry-run')
+        .option('--create', 'create a new document under a folder or wiki target')
+        .option('--strategy <strategy>', 'write strategy: auto | block-patch | document-replace', 'auto')
+        .option('--confirm-destructive', 'confirm destructive document replacement in non-interactive mode')
+        .option('--confirm-collaboration-risk', 'confirm block replacement/deletion may affect comments or block identity')
+        .option('--confirm-untracked-remote', 'confirm adopting an existing remote document without a publish receipt')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (markdownFile, opts) => {
+        const requested = publishRequestFromArgv(opts);
+        if (requested.write && requested.strategy === 'document-replace' && !requested.confirmDestructive) {
+            throw new Error('--confirm-destructive is required with --strategy document-replace --write');
+        }
+        const target = parseFeishuTarget(opts.target ?? '');
+        const cwd = process.cwd();
+        const config = await loadSyncConfig({ cwd });
+        const profile = resolvePublishProfile({ cliProfile: opts.profile, config });
+        const result = await runPublish({
+            cwd,
+            file: path.resolve(cwd, markdownFile),
+            target,
+            profile,
+            write: requested.write,
+            create: requested.create,
+            strategy: requested.strategy,
+            confirmDestructive: requested.confirmDestructive,
+            confirmCollaborationRisk: requested.confirmCollaborationRisk,
+            confirmUntrackedRemote: requested.confirmUntrackedRemote,
+            adapter: new LarkCliAdapter()
+        });
+        printFormatted(result, opts.format);
+    });
+}
+function publishRequestFromArgv(opts) {
+    const strategy = optionValueFromArgv('--strategy') ?? opts.strategy ?? 'auto';
+    if (strategy !== 'auto' && strategy !== 'block-patch' && strategy !== 'document-replace') {
+        throw new Error(`Invalid --strategy ${strategy}. Expected auto, block-patch, or document-replace.`);
+    }
+    return {
+        write: opts.write === true || process.argv.includes('--write'),
+        create: opts.create === true || process.argv.includes('--create'),
+        strategy,
+        confirmDestructive: opts.confirmDestructive === true || process.argv.includes('--confirm-destructive'),
+        confirmCollaborationRisk: opts.confirmCollaborationRisk === true || process.argv.includes('--confirm-collaboration-risk'),
+        confirmUntrackedRemote: opts.confirmUntrackedRemote === true || process.argv.includes('--confirm-untracked-remote')
+    };
+}
+function optionValueFromArgv(name) {
+    const index = process.argv.indexOf(name);
+    return index === -1 ? undefined : process.argv[index + 1];
+}