myaidev-method 0.3.4 → 0.3.5

package/src/lib/payloadcms-utils.js

@@ -4,9 +4,95 @@
  * Optimized for Claude Code 2.0 agent integration
  */
 
-import { readFileSync } from 'fs';
-import { parse } from 'dotenv';
-import { marked } from 'marked';
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { parse } from "dotenv";
+import { createHeadlessEditor } from "@payloadcms/richtext-lexical/lexical/headless";
+import {
+  $convertFromMarkdownString,
+  CHECK_LIST,
+  TRANSFORMERS,
+} from "@payloadcms/richtext-lexical/lexical/markdown";
+import {
+  ListNode,
+  ListItemNode,
+} from "@payloadcms/richtext-lexical/lexical/list";
+import {
+  HeadingNode,
+  QuoteNode,
+} from "@payloadcms/richtext-lexical/lexical/rich-text";
+import { TableNode, TableRowNode, TableCellNode } from "@lexical/table";
+
+// PayloadCMS internal nodes and transformers (file:// import to bypass exports map)
+const _base = new URL(
+  "../../node_modules/@payloadcms/richtext-lexical/",
+  import.meta.url,
+).href;
+const { HorizontalRuleServerNode } = await import(
+  _base + "dist/features/horizontalRule/server/nodes/HorizontalRuleNode.js"
+);
+const { MarkdownTransformer: HRTransformer } = await import(
+  _base + "dist/features/horizontalRule/server/markdownTransformer.js"
+);
+const { LinkMarkdownTransformer } = await import(
+  _base + "dist/features/link/markdownTransformer.js"
+);
+const { LinkNode } = await import(
+  _base + "dist/features/link/nodes/LinkNode.js"
+);
+const { TableMarkdownTransformer: TableTransformerFactory } = await import(
+  _base + "dist/features/experimental_table/markdownTransformer.js"
+);
+const { UploadServerNode } = await import(
+  _base + "dist/features/upload/server/nodes/UploadNode.js"
+);
+const { ServerBlockNode } = await import(
+  _base + "dist/features/blocks/server/nodes/BlocksNode.js"
+);
+const { getBlockMarkdownTransformers } = await import(
+  _base + "dist/features/blocks/server/markdown/markdownTransformer.js"
+);
+const { CodeBlock } = await import(
+  _base + "dist/features/blocks/premade/CodeBlock/index.js"
+);
+
+// Build transformers: CHECK_LIST must precede UNORDERED_LIST to match first
+const BASE_TRANSFORMERS = [
+  CHECK_LIST,
+  ...TRANSFORMERS,
+  HRTransformer,
+  LinkMarkdownTransformer,
+];
+
+// Code block support via PayloadCMS Blocks feature (converts ```lang blocks to block nodes)
+const codeBlockDef = CodeBlock();
+const blockTransformerFactories = getBlockMarkdownTransformers({
+  blocks: [codeBlockDef],
+  inlineBlocks: [],
+});
+const LEXICAL_NODES = [
+  HeadingNode,
+  QuoteNode,
+  ListNode,
+  ListItemNode,
+  LinkNode,
+  HorizontalRuleServerNode,
+  TableNode,
+  TableRowNode,
+  TableCellNode,
+  UploadServerNode,
+  ServerBlockNode,
+];
+const resolvedBlockTransformers = blockTransformerFactories.map((f) =>
+  typeof f === "function"
+    ? f({ allNodes: LEXICAL_NODES, allTransformers: BASE_TRANSFORMERS })
+    : f,
+);
+const LEXICAL_TRANSFORMERS = [
+  ...BASE_TRANSFORMERS,
+  TableTransformerFactory({ allTransformers: BASE_TRANSFORMERS }),
+  ...resolvedBlockTransformers,
+];
 
 export class PayloadCMSUtils {
   constructor(config = {}) {
@@ -16,7 +102,7 @@ export class PayloadCMSUtils {
       config = { ...envConfig, ...config };
     }
 
-    this.url = config.url?.replace(/\/$/, '');
+    this.url = config.url?.replace(/\/$/, "");
     this.email = config.email;
     this.password = config.password;
     this.token = null;
@@ -24,17 +110,19 @@ export class PayloadCMSUtils {
 
   loadEnvConfig() {
     try {
-      const envPath = process.env.ENV_PATH || '.env';
-      const envContent = readFileSync(envPath, 'utf8');
+      const envPath = process.env.ENV_PATH || ".env";
+      const envContent = readFileSync(envPath, "utf8");
       const parsed = parse(envContent);
 
       return {
         url: parsed.PAYLOADCMS_URL,
         email: parsed.PAYLOADCMS_EMAIL,
-        password: parsed.PAYLOADCMS_PASSWORD
+        password: parsed.PAYLOADCMS_PASSWORD,
       };
     } catch (error) {
-      throw new Error(`Failed to load PayloadCMS configuration: ${error.message}`);
+      throw new Error(
+        `Failed to load PayloadCMS configuration: ${error.message}`,
+      );
     }
   }
 
@@ -44,19 +132,21 @@ export class PayloadCMSUtils {
    */
   async authenticate() {
     if (!this.email || !this.password) {
-      throw new Error('PAYLOADCMS_EMAIL and PAYLOADCMS_PASSWORD required for authentication');
+      throw new Error(
+        "PAYLOADCMS_EMAIL and PAYLOADCMS_PASSWORD required for authentication",
+      );
     }
 
     try {
       const response = await fetch(`${this.url}/api/users/login`, {
-        method: 'POST',
+        method: "POST",
         headers: {
-          'Content-Type': 'application/json'
+          "Content-Type": "application/json",
         },
         body: JSON.stringify({
           email: this.email,
-          password: this.password
-        })
+          password: this.password,
+        }),
       });
 
       if (!response.ok) {
@@ -69,9 +159,9 @@ export class PayloadCMSUtils {
 
       return {
         success: true,
-        method: 'jwt',
+        method: "jwt",
         user: data.user,
-        token: this.token
+        token: this.token,
       };
     } catch (error) {
       throw new Error(`PayloadCMS authentication failed: ${error.message}`);
@@ -88,21 +178,24 @@ export class PayloadCMSUtils {
 
     const url = `${this.url}${endpoint}`;
     const headers = {
-      'Content-Type': 'application/json',
-      'Authorization': `JWT ${this.token}`,
-      ...options.headers
+      "Content-Type": "application/json",
+      Authorization: `JWT ${this.token}`,
+      ...options.headers,
     };
 
     try {
       const response = await fetch(url, {
         ...options,
-        headers
+        headers,
       });
 
       const data = await response.json().catch(() => ({}));
 
       if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${data.message || response.statusText}`);
+        const detail = data.errors
+          ? JSON.stringify(data.errors)
+          : data.message || response.statusText;
+        throw new Error(`HTTP ${response.status}: ${detail}`);
       }
 
       return data;
@@ -112,479 +205,27 @@ export class PayloadCMSUtils {
   }
 
   /**
-   * Convert markdown to Lexical rich text format
-   * PayloadCMS uses Lexical editor by default
+   * Convert markdown to Lexical rich text format using PayloadCMS's own Lexical
+   * node classes and markdown transformers via a headless editor. This produces
+   * serialized JSON identical to what PayloadCMS's editor generates, so
+   * parseEditorState() on the server will find all registered node types.
    */
   convertMarkdownToLexical(markdown) {
-    const tokens = marked.lexer(markdown);
-
-    const convertToken = (token) => {
-      switch (token.type) {
-        case 'heading':
-          return {
-            type: 'heading',
-            tag: `h${token.depth}`,
-            children: [{ type: 'text', text: token.text, format: 0 }],
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-
-        case 'paragraph':
-          return {
-            type: 'paragraph',
-            children: this.parseInlineText(token.text),
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-
-        case 'list':
-          return {
-            type: 'list',
-            listType: token.ordered ? 'number' : 'bullet',
-            start: token.start || 1,
-            tag: token.ordered ? 'ol' : 'ul',
-            children: token.items.map(item => ({
-              type: 'listitem',
-              value: 1,
-              children: [{
-                type: 'paragraph',
-                children: this.parseInlineText(item.text),
-                direction: 'ltr',
-                format: '',
-                indent: 0
-              }],
-              direction: 'ltr',
-              format: '',
-              indent: 0
-            })),
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-
-        case 'code':
-          return {
-            type: 'code',
-            language: token.lang || 'plaintext',
-            children: [{ type: 'text', text: token.text, format: 0 }],
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-
-        case 'blockquote':
-          return {
-            type: 'quote',
-            children: [{
-              type: 'paragraph',
-              children: this.parseInlineText(token.text),
-              direction: 'ltr',
-              format: '',
-              indent: 0
-            }],
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-
-        case 'hr':
-          return {
-            type: 'horizontalrule',
-            version: 1
-          };
-
-        default:
-          return {
-            type: 'paragraph',
-            children: [{ type: 'text', text: token.raw || '', format: 0 }],
-            direction: 'ltr',
-            format: '',
-            indent: 0,
-            version: 1
-          };
-      }
-    };
-
-    // Filter out space tokens and convert remaining tokens
-    const children = tokens
-      .filter(token => token.type !== 'space')
-      .map(convertToken);
-
-    return {
-      root: {
-        type: 'root',
-        format: '',
-        indent: 0,
-        version: 1,
-        children,
-        direction: 'ltr'
-      }
-    };
-  }
-
-  /**
-   * Parse inline text with formatting (bold, italic, code, links)
-   * Supports markdown formatters and converts to Lexical format codes:
-   * - **bold** → format: 1
-   * - *italic* → format: 2
-   * - `code` → format: 16
-   * - ***bold+italic*** → format: 3
-   */
-  parseInlineText(text) {
-    const children = [];
-
-    // Strip HTML tags first
-    text = text.replace(/<[^>]+>/g, '');
-
-    // Parse markdown inline formatting using marked's inline lexer
-    try {
-      const tokens = marked.lexer(text);
-
-      // Extract inline tokens from paragraph if present
-      let inlineTokens = [];
-      if (tokens[0]?.type === 'paragraph' && tokens[0].tokens) {
-        inlineTokens = tokens[0].tokens;
-      } else if (tokens[0]?.tokens) {
-        inlineTokens = tokens[0].tokens;
-      } else {
-        // No inline tokens, return plain text
-        return [{
-          type: 'text',
-          text: text,
-          format: 0,
-          mode: 'normal',
-          style: '',
-          detail: 0,
-          version: 1
-        }];
-      }
-
-      // Convert each inline token to Lexical format
-      for (const token of inlineTokens) {
-        switch (token.type) {
-          case 'text':
-            children.push({
-              type: 'text',
-              text: token.text,
-              format: 0,
-              mode: 'normal',
-              style: '',
-              detail: 0,
-              version: 1
-            });
-            break;
-
-          case 'strong':
-            children.push({
-              type: 'text',
-              text: token.text,
-              format: 1, // IS_BOLD
-              mode: 'normal',
-              style: '',
-              detail: 0,
-              version: 1
-            });
-            break;
-
-          case 'em':
-            children.push({
-              type: 'text',
-              text: token.text,
-              format: 2, // IS_ITALIC
-              mode: 'normal',
-              style: '',
-              detail: 0,
-              version: 1
-            });
-            break;
-
-          case 'codespan':
-            children.push({
-              type: 'text',
-              text: token.text,
-              format: 16, // IS_CODE
-              mode: 'normal',
-              style: '',
-              detail: 0,
-              version: 1
-            });
-            break;
-
-          case 'link':
-            children.push({
-              type: 'link',
-              url: token.href,
-              children: [{
-                type: 'text',
-                text: token.text,
-                format: 0,
-                mode: 'normal',
-                style: '',
-                detail: 0,
-                version: 1
-              }],
-              direction: 'ltr',
-              format: '',
-              indent: 0,
-              version: 3
-            });
-            break;
-
-          default:
-            // Fallback for any unhandled token types
-            children.push({
-              type: 'text',
-              text: token.raw || token.text || '',
-              format: 0,
-              mode: 'normal',
-              style: '',
-              detail: 0,
-              version: 1
-            });
-        }
-      }
-    } catch (error) {
-      // If parsing fails, return plain text
-      children.push({
-        type: 'text',
-        text: text,
-        format: 0,
-        mode: 'normal',
-        style: '',
-        detail: 0,
-        version: 1
-      });
-    }
-
-    return children.length > 0 ? children : [{
-      type: 'text',
-      text: text,
-      format: 0,
-      mode: 'normal',
-      style: '',
-      detail: 0,
-      version: 1
-    }];
-  }
-
-  /**
-   * Validate Lexical JSON structure
-   * Ensures output matches PayloadCMS Lexical editor format
-   * @param {Object} lexicalJSON - The Lexical JSON to validate
-   * @param {Object} options - Validation options
-   * @returns {Object} Validation result with errors array
-   */
-  validateLexicalStructure(lexicalJSON, options = {}) {
-    const errors = [];
-    const warnings = [];
-
-    // Check root structure
-    if (!lexicalJSON || typeof lexicalJSON !== 'object') {
-      errors.push('Lexical JSON must be an object');
-      return { valid: false, errors, warnings };
-    }
-
-    if (!lexicalJSON.root) {
-      errors.push('Missing root node');
-      return { valid: false, errors, warnings };
-    }
-
-    const root = lexicalJSON.root;
-
-    // Validate root node
-    if (root.type !== 'root') {
-      errors.push(`Root type must be 'root', got '${root.type}'`);
-    }
-
-    if (!Array.isArray(root.children)) {
-      errors.push('Root must have children array');
-      return { valid: false, errors, warnings };
-    }
-
-    // Validate each child node
-    const validateNode = (node, path = 'root') => {
-      if (!node || typeof node !== 'object') {
-        errors.push(`${path}: Node must be an object`);
-        return;
-      }
-
-      if (!node.type) {
-        errors.push(`${path}: Node missing type property`);
-        return;
-      }
-
-      // Validate based on node type
-      switch (node.type) {
-        case 'heading':
-          if (!node.tag || !/^h[1-6]$/.test(node.tag)) {
-            errors.push(`${path}: Heading must have tag h1-h6, got '${node.tag}'`);
-          }
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Heading must have children array`);
-          }
-          break;
-
-        case 'paragraph':
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Paragraph must have children array`);
-          }
-          break;
-
-        case 'list':
-          if (!['bullet', 'number', 'check'].includes(node.listType)) {
-            errors.push(`${path}: List listType must be bullet/number/check, got '${node.listType}'`);
-          }
-          if (!['ul', 'ol'].includes(node.tag)) {
-            errors.push(`${path}: List tag must be ul/ol, got '${node.tag}'`);
-          }
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: List must have children array`);
-          }
-          // Validate list items
-          node.children?.forEach((item, i) => {
-            if (item.type !== 'listitem') {
-              errors.push(`${path}.children[${i}]: List child must be listitem, got '${item.type}'`);
-            }
-          });
-          break;
-
-        case 'listitem':
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Listitem must have children array`);
-          }
-          break;
-
-        case 'text':
-          if (typeof node.text !== 'string') {
-            errors.push(`${path}: Text node must have string text property`);
-          }
-          if (typeof node.format !== 'number') {
-            errors.push(`${path}: Text node format must be number, got ${typeof node.format}`);
-          }
-          // Validate format is valid bitwise combination
-          if (node.format !== 0 && options.strictFormat) {
-            const validFormats = [1, 2, 3, 4, 8, 16, 32, 64, 128];
-            const isValidCombination = (format) => {
-              // Check if format is valid bitwise combination of base values
-              return format <= 255 && (format & ~255) === 0;
-            };
-            if (!isValidCombination(node.format)) {
-              warnings.push(`${path}: Unusual format value ${node.format}, expected bitwise combination`);
-            }
-          }
-          break;
-
-        case 'link':
-          if (typeof node.url !== 'string') {
-            errors.push(`${path}: Link must have string url property`);
-          }
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Link must have children array`);
-          }
-          break;
-
-        case 'code':
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Code must have children array`);
-          }
-          break;
-
-        case 'quote':
-          if (!Array.isArray(node.children)) {
-            errors.push(`${path}: Quote must have children array`);
-          }
-          break;
-
-        case 'horizontalrule':
-          // HR nodes don't have children
-          break;
-
-        default:
-          if (options.strict) {
-            warnings.push(`${path}: Unknown node type '${node.type}'`);
-          }
-      }
-
-      // Recursively validate children
-      if (Array.isArray(node.children)) {
-        node.children.forEach((child, i) => {
-          validateNode(child, `${path}.children[${i}]`);
-        });
-      }
-    };
-
-    // Validate all root children
-    root.children.forEach((child, i) => {
-      validateNode(child, `root.children[${i}]`);
-    });
-
-    return {
-      valid: errors.length === 0,
-      errors,
-      warnings
-    };
-  }
-
-  /**
-   * Validate and optionally fix Lexical format codes
-   * Ensures format codes follow Lexical bitwise specification
-   * @param {number} format - The format code to validate
-   * @returns {Object} Validation result
-   */
-  validateFormatCode(format) {
-    const VALID_FORMATS = {
-      BOLD: 1,            // 1 << 0
-      ITALIC: 2,          // 1 << 1
-      STRIKETHROUGH: 4,   // 1 << 2
-      UNDERLINE: 8,       // 1 << 3
-      CODE: 16,           // 1 << 4
-      SUBSCRIPT: 32,      // 1 << 5
-      SUPERSCRIPT: 64,    // 1 << 6
-      HIGHLIGHT: 128      // 1 << 7
-    };
-
-    if (typeof format !== 'number') {
-      return {
-        valid: false,
-        error: `Format must be number, got ${typeof format}`
-      };
-    }
-
-    if (format < 0 || format > 255) {
-      return {
-        valid: false,
-        error: `Format must be between 0 and 255, got ${format}`
-      };
-    }
-
-    // Decompose format into individual flags
-    const flags = [];
-    Object.entries(VALID_FORMATS).forEach(([name, value]) => {
-      if ((format & value) === value) {
-        flags.push(name);
-      }
-    });
-
-    return {
-      valid: true,
-      format,
-      flags,
-      description: flags.length > 0 ? flags.join(' + ') : 'Plain text'
-    };
+    const editor = createHeadlessEditor({ nodes: LEXICAL_NODES });
+    editor.update(
+      () => {
+        $convertFromMarkdownString(markdown, LEXICAL_TRANSFORMERS);
+      },
+      { discrete: true },
+    );
+    return editor.getEditorState().toJSON();
   }
 
   /**
    * List all collections
    */
   async listCollections() {
-    return await this.request('/api');
+    return await this.request("/api");
   }
 
   /**
@@ -592,11 +233,11 @@ export class PayloadCMSUtils {
    */
   async getDocuments(collection, options = {}) {
     const params = new URLSearchParams();
-    if (options.limit) params.append('limit', options.limit);
-    if (options.page) params.append('page', options.page);
-    if (options.where) params.append('where', JSON.stringify(options.where));
+    if (options.limit) params.append("limit", options.limit);
+    if (options.page) params.append("page", options.page);
+    if (options.where) params.append("where", JSON.stringify(options.where));
 
-    const query = params.toString() ? `?${params.toString()}` : '';
+    const query = params.toString() ? `?${params.toString()}` : "";
     return await this.request(`/api/${collection}${query}`);
   }
 
@@ -612,8 +253,8 @@ export class PayloadCMSUtils {
    */
   async createDocument(collection, data) {
     return await this.request(`/api/${collection}`, {
-      method: 'POST',
-      body: JSON.stringify(data)
+      method: "POST",
+      body: JSON.stringify(data),
     });
   }
 
@@ -622,8 +263,8 @@ export class PayloadCMSUtils {
    */
   async updateDocument(collection, id, data) {
     return await this.request(`/api/${collection}/${id}`, {
-      method: 'PATCH',
-      body: JSON.stringify(data)
+      method: "PATCH",
+      body: JSON.stringify(data),
     });
   }
 
@@ -632,38 +273,59 @@ export class PayloadCMSUtils {
    */
   async deleteDocument(collection, id) {
     return await this.request(`/api/${collection}/${id}`, {
-      method: 'DELETE'
+      method: "DELETE",
     });
   }
 
   /**
    * Upload media file
+   * Uses Node.js native FormData + Blob (requires Node 20+)
    */
-  async uploadMedia(filePath, altText = '') {
+  async uploadMedia(filePath, altText = "") {
     if (!this.token) {
       await this.authenticate();
     }
 
-    const FormData = (await import('form-data')).default;
-    const fs = await import('fs');
+    const { readFileSync } = await import("fs");
+    const { basename, extname } = await import("path");
+
+    const MIME_TYPES = {
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".webp": "image/webp",
+      ".svg": "image/svg+xml",
+      ".avif": "image/avif",
+      ".ico": "image/x-icon",
+      ".bmp": "image/bmp",
+      ".pdf": "application/pdf",
+      ".mp4": "video/mp4",
+      ".webm": "video/webm",
+    };
+
+    const fileName = basename(filePath);
+    const mimeType =
+      MIME_TYPES[extname(filePath).toLowerCase()] || "application/octet-stream";
+    const fileBuffer = readFileSync(filePath);
+    const blob = new Blob([fileBuffer], { type: mimeType });
 
     const formData = new FormData();
-    formData.append('file', fs.createReadStream(filePath));
-    if (altText) formData.append('alt', altText);
+    formData.append("file", blob, fileName);
+    if (altText) formData.append("alt", altText);
 
     try {
       const response = await fetch(`${this.url}/api/media`, {
-        method: 'POST',
+        method: "POST",
         headers: {
-          'Authorization': `JWT ${this.token}`,
-          ...formData.getHeaders()
+          Authorization: `JWT ${this.token}`,
         },
-        body: formData
+        body: formData,
       });
 
       if (!response.ok) {
         const error = await response.text();
-        throw new Error(`Upload failed: ${error}`);
+        throw new Error(`Upload failed (${response.status}): ${error}`);
       }
 
       return await response.json();
@@ -672,26 +334,139 @@ export class PayloadCMSUtils {
     }
   }
 
+  /**
+   * Pre-process markdown for publishing: strip HTML wrappers, upload images,
+   * and return cleaned markdown + a map of upload placeholders to media IDs.
+   */
+  async preprocessMarkdownForPublish(markdown, markdownFilePath, frontmatter = {}) {
+    const fs = await import("fs");
+    const uploads = []; // { placeholder, mediaId }
+
+    // Strip leading H1 if it duplicates the frontmatter title (title is rendered by the page template)
+    let cleaned = markdown.trimStart();
+    if (frontmatter.title) {
+      cleaned = cleaned.replace(/^#\s+.+\n+/, '');
+    }
+
+    // Strip <div class="infographic" ...> and </div> wrapper lines
+    cleaned = cleaned.replace(
+      /^<div\s+class="infographic"[^>]*>\s*$/gm,
+      "",
+    );
+    cleaned = cleaned.replace(/^<\/div>\s*$/gm, "");
+
+    // Collapse runs of 3+ consecutive newlines into exactly 2 (one blank line)
+    // This prevents div stripping from leaving excessive blank lines
+    cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+
+    // Find all markdown images: ![alt](path)
+    const imageRegex = /^!\[([^\]]*)\]\(([^)]+)\)\s*$/gm;
+    const images = [];
+    let match;
+    while ((match = imageRegex.exec(cleaned)) !== null) {
+      images.push({ full: match[0], alt: match[1], path: match[2] });
+    }
+
+    // Upload each image and replace with placeholder
+    const baseDir = markdownFilePath
+      ? dirname(markdownFilePath)
+      : process.cwd();
+    for (const img of images) {
+      const filePath = resolve(baseDir, img.path);
+      if (!fs.existsSync(filePath)) continue;
+
+      try {
+        const result = await this.uploadMedia(filePath, img.alt);
+        const mediaId = result.doc?.id || result.id;
+        if (mediaId) {
+          const placeholder = `%%UPLOAD:${mediaId}%%`;
+          cleaned = cleaned.replace(img.full, placeholder);
+          uploads.push({ placeholder, mediaId });
+        }
+      } catch (err) {
+        console.error(`Warning: Failed to upload ${img.path}: ${err.message}`);
+      }
+    }
+
+    return { markdown: cleaned, uploads };
+  }
+
+  /**
+   * Post-process Lexical JSON to replace upload placeholders with upload nodes.
+   * Handles cases where Lexical merges the placeholder with adjacent inline
+   * content (e.g. an italic caption on the next line) into a single paragraph.
+   */
+  injectUploadNodes(lexicalJson, uploads) {
+    if (!uploads.length) return lexicalJson;
+
+    const placeholderMap = new Map(
+      uploads.map((u) => [u.placeholder, u.mediaId]),
+    );
+    const newChildren = [];
+
+    for (const node of lexicalJson.root.children) {
+      if (
+        node.type === "paragraph" &&
+        node.children?.length >= 1 &&
+        node.children[0].type === "text"
+      ) {
+        const text = node.children[0].text.trim();
+        const mediaId = placeholderMap.get(text);
+        if (mediaId) {
+          // Emit the upload node
+          newChildren.push({
+            type: "upload",
+            version: 3,
+            format: "",
+            relationTo: "media",
+            value: mediaId,
+            id: crypto.randomUUID().replace(/-/g, "").slice(0, 24),
+            fields: {},
+          });
+          // If the paragraph had additional children (e.g. merged italic caption),
+          // emit them as a separate paragraph
+          if (node.children.length > 1) {
+            newChildren.push({ ...node, children: node.children.slice(1) });
+          }
+          continue;
+        }
+      }
+      newChildren.push(node);
+    }
+
+    return {
+      ...lexicalJson,
+      root: { ...lexicalJson.root, children: newChildren },
+    };
+  }
+
   /**
    * Publish markdown content to PayloadCMS
    */
   async publishContent(markdownFile, collection, options = {}) {
-    const fs = await import('fs');
-    const grayMatter = (await import('gray-matter')).default;
+    const fs = await import("fs");
+    const grayMatter = (await import("gray-matter")).default;
 
     // Read and parse markdown file
-    const fileContent = fs.readFileSync(markdownFile, 'utf8');
+    const fileContent = fs.readFileSync(markdownFile, "utf8");
     const { data: frontmatter, content } = grayMatter(fileContent);
 
+    // Pre-process: strip HTML wrappers, duplicate H1 title, upload images
+    const { markdown: cleanedContent, uploads } =
+      await this.preprocessMarkdownForPublish(content, markdownFile, frontmatter);
+
     // Convert markdown to Lexical format
-    const richText = this.convertMarkdownToLexical(content);
+    let richText = this.convertMarkdownToLexical(cleanedContent);
+
+    // Inject upload nodes where placeholders exist
+    richText = this.injectUploadNodes(richText, uploads);
 
     // Prepare document data
     const documentData = {
       ...frontmatter,
       content: richText,
-      status: options.status || frontmatter.status || 'draft',
-      ...options.additionalFields
+      status: options.status || frontmatter.status || "draft",
+      ...options.additionalFields,
     };
 
     // Create or update document