feishu-md-sync 0.1.0

package/dist/cli/env.d.ts

@@ -0,0 +1,27 @@
+export type CliEnvLoadOptions = {
+    argv?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    moduleUrl?: string;
+};
+export type CliEnvLoadReport = {
+    cwd: string;
+    explicitEnvFile?: string;
+    attemptedFiles: string[];
+    loadedFiles: string[];
+};
+export type AuthDoctorReport = {
+    envFiles: Array<{
+        path: string;
+        loaded: boolean;
+        explicit: boolean;
+    }>;
+    larkCli: {
+        command: string;
+        identity: 'auto' | 'bot' | 'user';
+        identityEnv?: string;
+        warning?: string;
+    };
+};
+export declare function loadCliEnv(options?: CliEnvLoadOptions): CliEnvLoadReport;
+export declare function buildAuthDoctorReport(report: CliEnvLoadReport, env?: NodeJS.ProcessEnv): AuthDoctorReport;

package/dist/cli/env.js

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { config as loadDotenv } from 'dotenv';
+export function loadCliEnv(options = {}) {
+    const argv = options.argv ?? process.argv;
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const explicitEnvFile = envFileFromArgv(argv, cwd);
+    const attemptedFiles = candidateEnvFiles({
+        cwd,
+        explicitEnvFile,
+        moduleUrl: options.moduleUrl
+    });
+    const loadedFiles = [];
+    for (const file of attemptedFiles) {
+        if (!existsSync(file)) {
+            if (file === explicitEnvFile) {
+                throw new Error(`--env-file does not exist: ${file}`);
+            }
+            continue;
+        }
+        const result = loadDotenv({
+            path: file,
+            processEnv: env,
+            override: file === explicitEnvFile
+        });
+        if (result.error)
+            throw result.error;
+        loadedFiles.push(file);
+    }
+    return {
+        cwd,
+        explicitEnvFile,
+        attemptedFiles,
+        loadedFiles
+    };
+}
+export function buildAuthDoctorReport(report, env = process.env) {
+    const identityEnv = env.FEISHU_MD_SYNC_LARK_AS;
+    const identity = identityEnv === 'bot' || identityEnv === 'user' ? identityEnv : 'auto';
+    return {
+        envFiles: report.attemptedFiles.map((file) => ({
+            path: file,
+            loaded: report.loadedFiles.includes(file),
+            explicit: file === report.explicitEnvFile
+        })),
+        larkCli: {
+            command: 'lark-cli auth status',
+            identity,
+            identityEnv,
+            warning: identityEnv && identity === 'auto'
+                ? 'FEISHU_MD_SYNC_LARK_AS must be "bot" or "user"; falling back to lark-cli default identity.'
+                : undefined
+        }
+    };
+}
+function candidateEnvFiles(input) {
+    const files = [];
+    if (input.explicitEnvFile)
+        files.push(input.explicitEnvFile);
+    files.push(resolve(input.cwd, '.env'));
+    for (const root of packageRootsFromModule(input.moduleUrl)) {
+        files.push(join(root, '.env'));
+    }
+    return Array.from(new Set(files));
+}
+function envFileFromArgv(argv, cwd) {
+    for (let index = argv.length - 1; index >= 0; index -= 1) {
+        const arg = argv[index];
+        if (arg === '--env-file') {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error('--env-file requires a path.');
+            return resolveEnvPath(value, cwd);
+        }
+        if (arg.startsWith('--env-file=')) {
+            return resolveEnvPath(arg.slice('--env-file='.length), cwd);
+        }
+    }
+    return undefined;
+}
+function resolveEnvPath(value, cwd) {
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+function packageRootsFromModule(moduleUrl) {
+    if (!moduleUrl?.startsWith('file:'))
+        return [];
+    let current = dirname(fileURLToPath(moduleUrl));
+    const roots = [];
+    while (true) {
+        const packagePath = join(current, 'package.json');
+        if (existsSync(packagePath)) {
+            roots.push(current);
+            if (isWorkspaceRoot(packagePath))
+                break;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return roots;
+}
+function isWorkspaceRoot(packagePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(packagePath, 'utf8'));
+        return Array.isArray(parsed.workspaces) || Boolean(parsed.workspaces);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerCoreCommands } from './commands/core.js';
+import { registerPublishCommand } from './commands/publish.js';
+import { buildAuthDoctorReport, loadCliEnv } from './env.js';
+import { printFormatted } from './output.js';
+const topLevelCommands = ['publish', 'status', 'pull', 'diff', 'merge', 'doctor', 'help'];
+main().catch((error) => {
+    const message = error.message;
+    console.error(message);
+    process.exitCode = 1;
+});
+async function main() {
+    const envLoadReport = loadCliEnv({ moduleUrl: import.meta.url });
+    const program = new Command();
+    program
+        .name('feishu-md-sync')
+        .description('Sync local Markdown with Feishu/Lark online documents. Defaults to dry-run for remote writes.');
+    registerPublishCommand(program);
+    registerCoreCommands(program);
+    const doctor = program
+        .command('doctor')
+        .description('inspect local feishu-md-sync configuration');
+    doctor
+        .command('auth')
+        .description('show lark-cli auth hints and loaded .env files')
+        .option('--format <format>', 'output format: pretty | json', 'pretty')
+        .action(async (opts) => {
+        printFormatted(buildAuthDoctorReport(envLoadReport), opts.format);
+    });
+    const unknownCommand = findUnknownTopLevelCommand(process.argv.slice(2), topLevelCommands);
+    if (unknownCommand) {
+        throw new Error(`error: unknown command '${unknownCommand}'`);
+    }
+    await program.parseAsync();
+}
+function findUnknownTopLevelCommand(args, knownCommands) {
+    const known = new Set(knownCommands);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--env-file') {
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--env-file='))
+            continue;
+        if (arg.startsWith('-'))
+            continue;
+        return known.has(arg) ? undefined : arg;
+    }
+    return undefined;
+}

package/dist/cli/output.d.ts

@@ -0,0 +1,4 @@
+export type OutputFormat = 'pretty' | 'json';
+export declare function printJson(value: unknown): void;
+export declare function printFormatted(value: unknown, format: string | undefined): void;
+export declare function setFailedExitCode(condition: boolean): void;

package/dist/cli/output.js

@@ -0,0 +1,18 @@
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+export function printFormatted(value, format) {
+    if (format === 'json') {
+        printJson(value);
+        return;
+    }
+    if (typeof value === 'string') {
+        console.log(value);
+        return;
+    }
+    printJson(value);
+}
+export function setFailedExitCode(condition) {
+    if (condition)
+        process.exitCode = 1;
+}

package/dist/config/sync-config.d.ts

@@ -0,0 +1,13 @@
+import { type PublishProfileConfig, type PublishProfileName } from '../profiles/publish-profile.js';
+export type SyncConfig = {
+    defaultProfile?: PublishProfileName;
+    profiles: Record<string, PublishProfileConfig>;
+};
+export type LoadSyncConfigInput = {
+    cwd: string;
+};
+export declare function resolvePublishProfile(input: {
+    cliProfile?: string;
+    config: SyncConfig;
+}): PublishProfileName;
+export declare function loadSyncConfig(input: LoadSyncConfigInput): Promise<SyncConfig>;

package/dist/config/sync-config.js

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parsePublishProfileName } from '../profiles/publish-profile.js';
+export function resolvePublishProfile(input) {
+    if (input.cliProfile)
+        return parsePublishProfileName(input.cliProfile, '--profile');
+    return input.config.defaultProfile ?? 'none';
+}
+export async function loadSyncConfig(input) {
+    const path = join(input.cwd, 'feishu-md-sync.config.json');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { profiles: {} };
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error('feishu-md-sync.config.json must contain a JSON object.');
+    }
+    const defaultProfile = typeof parsed.defaultProfile === 'string'
+        ? parsePublishProfileName(parsed.defaultProfile, 'defaultProfile')
+        : undefined;
+    return {
+        defaultProfile,
+        profiles: parseProfiles(parsed.profiles)
+    };
+}
+function parseProfiles(value) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        throw new Error('profiles must be a JSON object.');
+    const profiles = {};
+    for (const [name, rawProfile] of Object.entries(value)) {
+        parsePublishProfileName(name, 'profile name');
+        if (!isRecord(rawProfile))
+            throw new Error(`profiles.${name} must be a JSON object.`);
+        profiles[name] = {
+            includeTargets: parseStringArray(rawProfile.includeTargets, `profiles.${name}.includeTargets`),
+            excludeTargets: parseStringArray(rawProfile.excludeTargets, `profiles.${name}.excludeTargets`),
+            productNameMarkup: typeof rawProfile.productNameMarkup === 'boolean' ? rawProfile.productNameMarkup : undefined
+        };
+    }
+    return profiles;
+}
+function parseStringArray(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new Error(`${label} must be an array of strings.`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/core/diff.d.ts

@@ -0,0 +1 @@
+export declare function unifiedDiff(leftName: string, rightName: string, left: string, right: string): string;

package/dist/core/diff.js

@@ -0,0 +1,20 @@
+export function unifiedDiff(leftName, rightName, left, right) {
+    const leftLines = left.split('\n');
+    const rightLines = right.split('\n');
+    const max = Math.max(leftLines.length, rightLines.length);
+    const lines = [`--- ${leftName}`, `+++ ${rightName}`];
+    for (let index = 0; index < max; index += 1) {
+        const a = leftLines[index];
+        const b = rightLines[index];
+        if (a === b) {
+            if (a !== undefined)
+                lines.push(` ${a}`);
+            continue;
+        }
+        if (a !== undefined)
+            lines.push(`-${a}`);
+        if (b !== undefined)
+            lines.push(`+${b}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/core/doc-id.d.ts

@@ -0,0 +1,12 @@
+export type FeishuTarget = {
+    kind: 'docx';
+    token: string;
+} | {
+    kind: 'wiki';
+    token: string;
+} | {
+    kind: 'folder';
+    token: string;
+};
+export declare function parseFeishuDocId(input: string): string;
+export declare function parseFeishuTarget(input: string): FeishuTarget;

package/dist/core/doc-id.js

@@ -0,0 +1,41 @@
+const DOC_ID_PATTERN = /^[A-Za-z0-9]{16,}$/;
+export function parseFeishuDocId(input) {
+    const target = parseFeishuTarget(input);
+    if (target.kind !== 'docx') {
+        throw new Error(`Wiki URL requires API resolution before it can be used as a docx document: ${input}`);
+    }
+    return target.token;
+}
+export function parseFeishuTarget(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error('Feishu document ID or URL is required.');
+    }
+    if (DOC_ID_PATTERN.test(trimmed)) {
+        return { kind: 'docx', token: trimmed };
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`Invalid Feishu document ID or URL: ${input}`);
+    }
+    const docxMatch = url.pathname.match(/\/docx\/([A-Za-z0-9]+)/);
+    if (docxMatch) {
+        return { kind: 'docx', token: docxMatch[1] };
+    }
+    const docsMatch = url.pathname.match(/\/docs\/([A-Za-z0-9]+)/);
+    if (docsMatch) {
+        return { kind: 'docx', token: docsMatch[1] };
+    }
+    const wikiMatch = url.pathname.match(/\/wiki\/([A-Za-z0-9]+)/);
+    if (wikiMatch) {
+        return { kind: 'wiki', token: wikiMatch[1] };
+    }
+    const folderMatch = url.pathname.match(/\/drive\/folder\/([A-Za-z0-9]+)/);
+    if (folderMatch) {
+        return { kind: 'folder', token: folderMatch[1] };
+    }
+    throw new Error(`Could not find a supported Feishu token in URL: ${input}`);
+}

package/dist/core/hash.d.ts

@@ -0,0 +1,6 @@
+import type { FeishuBlock } from '../feishu/types.js';
+export declare function sha256(value: string): string;
+export declare function hashSource(content: string): string;
+export declare function stableStringify(value: unknown): string;
+export declare function normalizeBlockForHash(block: FeishuBlock): unknown;
+export declare function hashBlocks(blocks: FeishuBlock[]): string;

package/dist/core/hash.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+export function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+export function hashSource(content) {
+    return sha256(content);
+}
+export function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function normalizeBlockForHash(block) {
+    return normalizeValue(block);
+}
+export function hashBlocks(blocks) {
+    return sha256(stableStringify(blocks.map(normalizeBlockForHash)));
+}
+function normalizeValue(value) {
+    if (Array.isArray(value)) {
+        return mergeAdjacentTextRuns(value.map(normalizeValue));
+    }
+    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 === 'children')
+                continue;
+            if (key === 'merge_info')
+                continue;
+            if (key === 'column_width' && isDefaultColumnWidth(child))
+                continue;
+            if (key === 'folded' && child === false)
+                continue;
+            if (key === 'align' && child === 1)
+                continue;
+            if (key === 'wrap' && child === false)
+                continue;
+            normalized[key] = normalizeValue(child);
+        }
+        return normalized;
+    }
+    return value;
+}
+function isDefaultColumnWidth(value) {
+    return Array.isArray(value) && value.every((item) => item === 100);
+}
+function mergeAdjacentTextRuns(values) {
+    const merged = [];
+    for (const value of values) {
+        const previous = merged[merged.length - 1];
+        if (isTextRun(previous) && isTextRun(value) && sameTextRunStyle(previous, value)) {
+            const previousRun = previous.text_run;
+            const currentRun = value.text_run;
+            previousRun.content = `${previousRun.content}${currentRun.content}`;
+            continue;
+        }
+        merged.push(value);
+    }
+    return merged;
+}
+function sameTextRunStyle(previous, current) {
+    if (!isTextRun(previous) || !isTextRun(current))
+        return false;
+    return stableStringify(previous.text_run.text_element_style) === stableStringify(current.text_run.text_element_style);
+}
+function isTextRun(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const textRun = value.text_run;
+    return Boolean(textRun &&
+        typeof textRun === 'object' &&
+        !Array.isArray(textRun) &&
+        typeof textRun.content === 'string');
+}

package/dist/core/markdown-canonical.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalMarkdown(markdown: string): string;
+export declare function canonicalMarkdownHash(markdown: string): string;

package/dist/core/markdown-canonical.js

@@ -0,0 +1,11 @@
+import { hashText } from '../receipts/publish-receipt.js';
+export function canonicalMarkdown(markdown) {
+    return markdown
+        .replace(/\r\n/g, '\n')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function canonicalMarkdownHash(markdown) {
+    return hashText(canonicalMarkdown(markdown));
+}

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

@@ -0,0 +1,23 @@
+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 PublishStatusResult } from '../status/run-status.js';
+export type RunDiffResult = {
+    mode: 'read-only';
+    target: PublishReceiptTarget;
+    sourcePath: string;
+    profile: PublishProfileName;
+    left: 'remote-current';
+    right: 'publish-draft';
+    hasDiff: boolean;
+    diff: string;
+    status: PublishStatusResult;
+};
+export declare function runDiff(input: {
+    cwd: string;
+    sourcePath: string;
+    target: PublishReceiptTarget;
+    profile: PublishProfileName;
+    adapter: FeishuAdapter;
+}): Promise<RunDiffResult>;
+export declare function diffSummaryLines(result: RunDiffResult): string[];

package/dist/diff/run-diff.js

@@ -0,0 +1,33 @@
+import { unifiedDiff } from '../core/diff.js';
+import { loadPublishStatusContext, statusFromContext } from '../status/run-status.js';
+export async function runDiff(input) {
+    const context = await loadPublishStatusContext(input);
+    const hasDiff = context.remoteCanonical !== context.publishDraftCanonical;
+    return {
+        mode: 'read-only',
+        target: input.target,
+        sourcePath: input.sourcePath,
+        profile: input.profile,
+        left: 'remote-current',
+        right: 'publish-draft',
+        hasDiff,
+        diff: hasDiff ? unifiedDiff('remote-current', 'publish-draft', context.remoteCanonical, context.publishDraftCanonical) : '',
+        status: statusFromContext(context)
+    };
+}
+export function diffSummaryLines(result) {
+    const lines = [
+        `state: ${result.status.state}`,
+        `local changed: ${result.status.localChanged}`,
+        `remote changed: ${result.status.remoteChanged}`,
+        `content matches remote: ${result.status.contentMatchesRemote}`,
+        `recommendation: ${result.status.recommendation.action} - ${result.status.recommendation.reason}`,
+        ''
+    ];
+    if (!result.hasDiff) {
+        lines.push('no diff');
+        return lines;
+    }
+    lines.push(result.diff.trimEnd());
+    return lines;
+}

package/dist/feishu/types.d.ts

@@ -0,0 +1,101 @@
+export type TextElementStyle = {
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    underline?: boolean;
+    inline_code?: boolean;
+    background_color?: number;
+    link?: {
+        url: string;
+    };
+};
+export type TextElement = {
+    text_run?: {
+        content: string;
+        text_element_style: TextElementStyle;
+    };
+    mention_doc?: {
+        title?: string;
+        url?: string;
+        token?: string;
+        obj_type?: number;
+        text_element_style?: TextElementStyle;
+    };
+    [key: string]: unknown;
+};
+export type FeishuBlock = {
+    block_id?: string;
+    block_type: number;
+    children?: string[] | FeishuBlock[];
+    [key: string]: unknown;
+};
+export type FeishuBlocksState = {
+    documentId: string;
+    blocks: FeishuBlock[];
+};
+export type FeishuBlockUpdateRequest = {
+    block_id: string;
+    update_text_elements?: {
+        elements: TextElement[];
+    };
+    update_text_style?: {
+        fields: string;
+        style: {
+            language?: number;
+        };
+    };
+    replace_image?: {
+        token: string;
+        width?: number;
+        height?: number;
+    };
+};
+export type WriteResult = {
+    deleted: number;
+    created: number;
+    updated?: number;
+    skipped: boolean;
+};
+export type FeishuDriveFile = {
+    token?: string;
+    document_id?: string;
+    obj_token?: string;
+    revision_id?: number;
+    name?: string;
+    type?: string;
+    url?: string;
+    [key: string]: unknown;
+};
+export type BitableTable = {
+    table_id?: string;
+    name?: string;
+    [key: string]: unknown;
+};
+export type BitableField = {
+    field_id?: string;
+    field_name?: string;
+    type?: number;
+    [key: string]: unknown;
+};
+export type BitableRecord = {
+    record_id?: string;
+    fields?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export interface FeishuDocClient {
+    getDocumentBlocks(documentId: string): Promise<FeishuBlock[]>;
+    overwriteDocumentMarkdown?(documentId: string, markdown: string): Promise<void>;
+    uploadMediaFile?(input: {
+        filePath: string;
+        parentNode: string;
+        parentType: string;
+    }): Promise<{
+        token: string;
+        contentType?: string;
+    }>;
+    deleteChildren(documentId: string, parentBlockId: string, startIndex: number, endIndex: number): Promise<void>;
+    createChildren(documentId: string, parentBlockId: string, blocks: FeishuBlock[], options?: {
+        index?: number;
+    }): Promise<FeishuBlock[]>;
+    batchUpdateBlocks?(documentId: string, requests: FeishuBlockUpdateRequest[]): Promise<FeishuBlock[]>;
+}

package/dist/feishu/types.js

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

package/dist/markdown/blocks.d.ts

@@ -0,0 +1,5 @@
+import type { FeishuBlock, TextElement } from '../feishu/types.js';
+export declare const LANG_IDS: Record<string, number>;
+export declare function languageIdForMarkdownLanguage(language: string): number;
+export declare function markdownToFeishuBlocks(markdown: string): FeishuBlock[];
+export declare function parseInlineText(text: string): TextElement[];