@jacobbubu/md-to-lark 1.5.1 → 1.7.0

package/README.md

@@ -174,13 +174,17 @@ Guardrails:
 - Single-file and recursive directory publish
 - Title derivation, title prefix, and single-H1 promotion
 - Local attachment and image detection with real upload
+- Programmatic image display width control through `imageSizeResolver`
+- Versioned `article-render/v1` contracts with inheritance, capability negotiation, strict pre-publish validation, and render reports
+- Semantic figures, tables, equations, callouts, and GFM footnotes rendered to native Lark block structures
+- Automatic `assets/manifest.yml` image sizing in renderer-contract mode
 - Remote image download and standalone URL preparation
 - Mermaid `text-drawing` and `board` output paths
 - Opt-in single-dollar inline math parsing for LaTeX-heavy papers
 - Table width heuristics and numeric-column right alignment
 - Chinese Markdown formatting preset (`zh-format`)
 - Ordered preset composition from CLI and programmatic usage
-- Stage cache output from `00-source` to `05-publish`
+- Legacy stage cache output from `00-source` to `05-publish`; protocol mode adds contract and semantic stages through `07-publish`
 - Programmatic access through `publishMdToLark`
 
 ## Where To Read Next

package/dist/commands/publish-md/args.js

@@ -1,6 +1,6 @@
 function usage() {
     return [
-        'Usage: npm run publish:md -- --input <file.md|dir> [--title <doc_title_or_prefix>] [--date-prefix|--no-date-prefix] [--preset <preset_name_or_module_path>]... [--document-base-url <base_url>] [--resource-base-dir <dir>] [--folder <folder_token>] [--doc <document_id>] [--download-remote-images|--no-download-remote-images] [--yt-dlp-path <path>] [--yt-dlp-cookies-path <path>] [--pipeline-cache-dir <dir>] [--single-dollar-text-math] [--mermaid-target <text-drawing|board>] [--mermaid-board-syntax-type <int>] [--mermaid-board-style-type <int>] [--mermaid-board-diagram-type <int>] [--dry-run] [--help|-h]',
+        'Usage: npm run publish:md -- --input <file.md|dir> [--renderer lark] [--renderer-contract <path>] [--strict] [--render-report <path>] [--image-size-manifest <path>] [other options]',
         '',
         'Options:',
         '  --input   Markdown file path, or directory path (publish all *.md recursively).',
@@ -10,6 +10,12 @@ function usage() {
         '  --preset  Optional preset module path (js/mjs/cjs/ts) or built-in name (e.g. medium). Repeatable; presets run in the given order before publish pipeline.',
         '  --document-base-url Base URL used to build documentUrl results (for example https://li.feishu.cn).',
         '  --resource-base-dir Base directory used to resolve relative local image/file paths. Default: the current markdown file directory.',
+        '  --renderer Target renderer. Default: lark.',
+        '  --renderer-contract Explicit article-render/v1 contract path.',
+        '  --renderer-default-contract Fallback renderer contract path when no article contract is found.',
+        '  --strict Require a valid renderer contract and fail before publish on semantic errors.',
+        '  --render-report Write the article-render/v1 JSON report to this path.',
+        '  --image-size-manifest Explicit assets/manifest.yml path for image display sizing.',
         '  --folder  Feishu folder token. Default: LARK_FOLDER_TOKEN from .env',
         '  --doc     Existing Feishu document id (single-file only). If set, publish directly into this doc (and clear content first).',
         '  --download-remote-images    Enable prepare-stage remote image pre-download + link rewrite.',
@@ -58,6 +64,12 @@ export function parsePublishMdArgs(argv, env = process.env) {
     const presetPaths = [];
     let documentBaseUrl = '';
     let resourceBaseDir = '';
+    let renderer = '';
+    let rendererContractPath = '';
+    let rendererDefaultContractPath = '';
+    let strict;
+    let renderReportPath = '';
+    let imageSizeManifestPath = '';
     let folderToken = (env.LARK_FOLDER_TOKEN ?? '').trim();
     let documentId;
     let downloadRemoteImages;
@@ -137,6 +149,50 @@ export function parsePublishMdArgs(argv, env = process.env) {
             i += 1;
             continue;
         }
+        if (arg === '--renderer') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer.');
+            renderer = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--renderer-contract') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer-contract.');
+            rendererContractPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--renderer-default-contract') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --renderer-default-contract.');
+            rendererDefaultContractPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--strict') {
+            strict = true;
+            continue;
+        }
+        if (arg === '--render-report') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --render-report.');
+            renderReportPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg === '--image-size-manifest') {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error('Missing value for --image-size-manifest.');
+            imageSizeManifestPath = value;
+            i += 1;
+            continue;
+        }
         if (arg === '--doc') {
             const value = argv[i + 1];
             if (!value)
@@ -245,6 +301,12 @@ export function parsePublishMdArgs(argv, env = process.env) {
             : {}),
         ...(documentBaseUrl.trim() ? { documentBaseUrl: documentBaseUrl.trim() } : {}),
         ...(resourceBaseDir.trim() ? { resourceBaseDir: resourceBaseDir.trim() } : {}),
+        ...(renderer.trim() ? { renderer: renderer.trim() } : {}),
+        ...(rendererContractPath.trim() ? { rendererContractPath: rendererContractPath.trim() } : {}),
+        ...(rendererDefaultContractPath.trim() ? { rendererDefaultContractPath: rendererDefaultContractPath.trim() } : {}),
+        ...(strict === undefined ? {} : { strict }),
+        ...(renderReportPath.trim() ? { renderReportPath: renderReportPath.trim() } : {}),
+        ...(imageSizeManifestPath.trim() ? { imageSizeManifestPath: imageSizeManifestPath.trim() } : {}),
         folderToken,
         ...(documentId ? { documentId: documentId.trim() } : {}),
         ...(downloadRemoteImages === undefined ? {} : { downloadRemoteImages }),

package/dist/commands/publish-md/command.js

@@ -1,10 +1,11 @@
-import { getPublishMdUsage, hasPublishMdHelpFlag, parsePublishMdArgs } from './args.js';
+import { getPublishMdUsage, hasPublishMdHelpFlag, parsePublishMdArgs, } from './args.js';
 import { resolvePublishInputSet } from './input-resolver.js';
 import { loadMarkdownPresets } from './preset-loader.js';
 import { createDocument, listFolderChildren, normalizeDocumentId } from '../../lark/docx/ops.js';
 import { processSingleMarkdownFile } from '../../publish/process-file.js';
 import { buildPublishRuntime, logPublishRuntimeSummary } from '../../publish/runtime.js';
 import { sleep } from '../../shared/rate-limiter.js';
+import { getRendererCapabilities, validateRendererContract } from '../../protocol/index.js';
 export { getPublishMdUsage, parsePublishMdArgs };
 function resolveMarkdownPresetRefs(options) {
     if (options.presetPaths && options.presetPaths.length > 0) {
@@ -65,19 +66,29 @@ function createFolderDocumentResolver(runtime, options) {
     };
 }
 export async function publishMdToLark(options, env = process.env) {
-    const inputSet = await resolvePublishInputSet(options.inputPath);
-    const markdownPresets = await loadMarkdownPresets(resolveMarkdownPresetRefs(options));
-    if (options.documentId && inputSet.markdownFiles.length !== 1) {
+    const publishOptions = {
+        ...options,
+        folderToken: options.folderToken?.trim() || env.LARK_FOLDER_TOKEN?.trim() || '',
+        dryRun: options.dryRun ?? false,
+    };
+    if (!publishOptions.documentId && !publishOptions.folderToken) {
+        throw new Error('Folder token is required when documentId is not provided.');
+    }
+    const inputSet = await resolvePublishInputSet(publishOptions.inputPath);
+    const markdownPresets = await loadMarkdownPresets(resolveMarkdownPresetRefs(publishOptions));
+    if (publishOptions.documentId && inputSet.markdownFiles.length !== 1) {
         throw new Error('--doc only supports single markdown input file.');
     }
-    const runtime = buildPublishRuntime(options, env, markdownPresets);
+    const runtime = buildPublishRuntime(publishOptions, env, markdownPresets);
     logPublishRuntimeSummary(runtime, inputSet.markdownFiles.length, inputSet.mode);
-    const normalizedDocumentId = options.documentId ? normalizeDocumentId(options.documentId) : undefined;
-    const resolveTargetDocumentId = options.dryRun || normalizedDocumentId ? undefined : createFolderDocumentResolver(runtime, options);
+    const normalizedDocumentId = publishOptions.documentId ? normalizeDocumentId(publishOptions.documentId) : undefined;
+    const resolveTargetDocumentId = publishOptions.dryRun || normalizedDocumentId ? undefined : createFolderDocumentResolver(runtime, publishOptions);
     const results = [];
     for (let index = 0; index < inputSet.markdownFiles.length; index += 1) {
         const markdownPath = inputSet.markdownFiles[index];
-        const perFileOptions = normalizedDocumentId ? { ...options, documentId: normalizedDocumentId } : options;
+        const perFileOptions = normalizedDocumentId
+            ? { ...publishOptions, documentId: normalizedDocumentId }
+            : publishOptions;
         const result = await processSingleMarkdownFile({
             runtime,
             inputSet,
@@ -92,7 +103,7 @@ export async function publishMdToLark(options, env = process.env) {
             status: result.status,
             documentUrl: result.documentUrl,
         });
-        if (!options.dryRun && index < inputSet.markdownFiles.length - 1 && runtime.publishCooldownMs > 0) {
+        if (!publishOptions.dryRun && index < inputSet.markdownFiles.length - 1 && runtime.publishCooldownMs > 0) {
             console.error(`[${index + 1}/${inputSet.markdownFiles.length}] Cooldown ${runtime.publishCooldownMs}ms before next markdown...`);
             await sleep(runtime.publishCooldownMs);
         }
@@ -104,6 +115,21 @@ export async function runPublishMdToLarkCli(argv, env = process.env) {
         console.log(getPublishMdUsage());
         return;
     }
+    if (argv.includes('--print-capabilities')) {
+        const rendererIndex = argv.indexOf('--renderer');
+        const renderer = rendererIndex >= 0 ? argv[rendererIndex + 1] : undefined;
+        console.log(JSON.stringify(getRendererCapabilities(renderer), null, 2));
+        return;
+    }
+    const validateIndex = argv.indexOf('--validate-contract');
+    if (validateIndex >= 0) {
+        const contractPath = argv[validateIndex + 1];
+        if (!contractPath)
+            throw new Error('Missing value for --validate-contract.');
+        const resolved = await validateRendererContract(contractPath);
+        console.log(JSON.stringify(resolved, null, 2));
+        return;
+    }
     const options = parsePublishMdArgs(argv, env);
     const results = await publishMdToLark(options, env);
     process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);

package/dist/index.js

@@ -1 +1,2 @@
 export { publishMdToLark } from './commands/publish-md/index.js';
+export { getRendererCapabilities, parseArticleFrontmatter, resolveRendererContract, validateRendererContract, } from './protocol/index.js';