myaidev-method 0.2.22 → 0.2.24-1

package/src/lib/html-conversion-utils.js

@@ -0,0 +1,843 @@
+/**
+ * HTML Conversion Utilities
+ *
+ * Converts HTML/CSS templates and D2 diagrams to PNG, PDF, and PPTX formats.
+ * Provides precise control over typography, layout, and data visualization.
+ *
+ * @module html-conversion-utils
+ */
+
+import puppeteer from 'puppeteer';
+import PptxGenJS from 'pptxgenjs';
+import { execSync, exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const execAsync = promisify(exec);
+
+// ES Module __dirname equivalent
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const DEFAULT_VIEWPORT = { width: 1200, height: 800 };
+const DEFAULT_PDF_FORMAT = 'A4';
+const DEFAULT_D2_THEME = 200; // Neutral theme
+
+/**
+ * Get the templates directory path
+ */
+export function getTemplatesPath() {
+  // Check multiple possible locations
+  const locations = [
+    path.join(process.cwd(), '.myaidev-method', 'templates'),
+    path.join(process.cwd(), 'src', 'templates'),
+    path.join(__dirname, '..', 'templates'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      return loc;
+    }
+  }
+
+  // Default to src/templates relative to this file
+  return path.join(__dirname, '..', 'templates');
+}
+
+/**
+ * Get the output assets directory
+ */
+export function getAssetsPath() {
+  return process.env.VISUAL_ASSETS_PATH || path.join(process.cwd(), 'content-assets');
+}
+
+// ============================================================================
+// HTML to PNG Conversion
+// ============================================================================
+
+/**
+ * Convert HTML string to PNG image
+ *
+ * @param {string} html - HTML content to render
+ * @param {Object} options - Conversion options
+ * @param {number} options.width - Viewport width (default: 1200)
+ * @param {number} options.height - Viewport height (default: 800)
+ * @param {boolean} options.fullPage - Capture full page (default: true)
+ * @param {string} options.output - Output file path (optional)
+ * @param {number} options.deviceScaleFactor - Scale factor for retina (default: 2)
+ * @returns {Promise<{buffer: Buffer, path?: string}>}
+ */
+export async function htmlToPng(html, options = {}) {
+  const {
+    width = DEFAULT_VIEWPORT.width,
+    height = DEFAULT_VIEWPORT.height,
+    fullPage = true,
+    output = null,
+    deviceScaleFactor = 2,
+    waitForSelector = null,
+    waitTime = 100,
+  } = options;
+
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: 'new',
+      args: [
+        '--no-sandbox',
+        '--disable-setuid-sandbox',
+        '--disable-dev-shm-usage',
+        '--disable-gpu',
+      ],
+    });
+
+    const page = await browser.newPage();
+
+    await page.setViewport({
+      width,
+      height,
+      deviceScaleFactor,
+    });
+
+    // Set content and wait for rendering
+    await page.setContent(html, {
+      waitUntil: ['load', 'networkidle0'],
+    });
+
+    // Optional: wait for specific selector
+    if (waitForSelector) {
+      await page.waitForSelector(waitForSelector, { timeout: 5000 });
+    }
+
+    // Small delay for final rendering
+    await new Promise(resolve => setTimeout(resolve, waitTime));
+
+    // Take screenshot
+    const screenshotOptions = {
+      type: 'png',
+      fullPage,
+      omitBackground: false,
+    };
+
+    const buffer = await page.screenshot(screenshotOptions);
+
+    // Save to file if output path provided
+    let outputPath = null;
+    if (output) {
+      outputPath = output;
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeFile(outputPath, buffer);
+    }
+
+    return {
+      buffer,
+      path: outputPath,
+      width: fullPage ? undefined : width,
+      height: fullPage ? undefined : height,
+    };
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+}
+
+// ============================================================================
+// HTML to PDF Conversion
+// ============================================================================
+
+/**
+ * Convert HTML string to PDF document
+ *
+ * @param {string} html - HTML content to render
+ * @param {Object} options - Conversion options
+ * @param {string} options.format - PDF format (default: 'A4')
+ * @param {boolean} options.landscape - Landscape orientation (default: false)
+ * @param {string} options.output - Output file path (optional)
+ * @param {Object} options.margin - Page margins
+ * @returns {Promise<{buffer: Buffer, path?: string}>}
+ */
+export async function htmlToPdf(html, options = {}) {
+  const {
+    format = DEFAULT_PDF_FORMAT,
+    landscape = false,
+    output = null,
+    margin = { top: '20mm', right: '20mm', bottom: '20mm', left: '20mm' },
+    printBackground = true,
+    displayHeaderFooter = false,
+    headerTemplate = '',
+    footerTemplate = '',
+  } = options;
+
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: 'new',
+      args: [
+        '--no-sandbox',
+        '--disable-setuid-sandbox',
+        '--disable-dev-shm-usage',
+      ],
+    });
+
+    const page = await browser.newPage();
+
+    await page.setContent(html, {
+      waitUntil: ['load', 'networkidle0'],
+    });
+
+    // Small delay for final rendering
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    const pdfOptions = {
+      format,
+      landscape,
+      margin,
+      printBackground,
+      displayHeaderFooter,
+      headerTemplate,
+      footerTemplate,
+    };
+
+    const buffer = await page.pdf(pdfOptions);
+
+    // Save to file if output path provided
+    let outputPath = null;
+    if (output) {
+      outputPath = output;
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeFile(outputPath, buffer);
+    }
+
+    return {
+      buffer,
+      path: outputPath,
+      format,
+      landscape,
+    };
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+}
+
+// ============================================================================
+// D2 Diagram Support
+// ============================================================================
+
+/**
+ * Check if D2 CLI is installed and available
+ * @returns {boolean}
+ */
+export function isD2Available() {
+  try {
+    execSync('d2 --version', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get D2 CLI version
+ * @returns {string|null}
+ */
+export function getD2Version() {
+  try {
+    const output = execSync('d2 --version', { encoding: 'utf-8' });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert D2 diagram script to SVG
+ *
+ * @param {string} d2Script - D2 diagram script
+ * @param {Object} options - Conversion options
+ * @param {number} options.theme - D2 theme ID (default: 200)
+ * @param {string} options.layout - Layout engine (default: 'dagre')
+ * @param {string} options.output - Output file path (optional)
+ * @returns {Promise<{svg: string, path?: string}>}
+ */
+export async function d2ToSvg(d2Script, options = {}) {
+  if (!isD2Available()) {
+    throw new Error(
+      'D2 CLI is not installed. Install it with:\n' +
+      '  macOS: brew install d2\n' +
+      '  Linux: curl -fsSL https://d2lang.com/install.sh | sh -s --'
+    );
+  }
+
+  const {
+    theme = DEFAULT_D2_THEME,
+    layout = 'dagre',
+    output = null,
+    pad = 20,
+  } = options;
+
+  // Create temp files
+  const tempDir = os.tmpdir();
+  const inputFile = path.join(tempDir, `d2-input-${Date.now()}.d2`);
+  const outputFile = path.join(tempDir, `d2-output-${Date.now()}.svg`);
+
+  try {
+    // Write D2 script to temp file
+    await fs.writeFile(inputFile, d2Script);
+
+    // Execute D2 CLI
+    const command = `d2 --theme=${theme} --layout=${layout} --pad=${pad} "${inputFile}" "${outputFile}"`;
+    await execAsync(command);
+
+    // Read generated SVG
+    const svg = await fs.readFile(outputFile, 'utf-8');
+
+    // Save to final output if provided
+    let finalPath = null;
+    if (output) {
+      finalPath = output;
+      await fs.ensureDir(path.dirname(finalPath));
+      await fs.writeFile(finalPath, svg);
+    }
+
+    return {
+      svg,
+      path: finalPath,
+      theme,
+      layout,
+    };
+  } finally {
+    // Cleanup temp files
+    await fs.remove(inputFile).catch(() => {});
+    await fs.remove(outputFile).catch(() => {});
+  }
+}
+
+/**
+ * Convert D2 diagram script to PNG
+ *
+ * @param {string} d2Script - D2 diagram script
+ * @param {Object} options - Conversion options
+ * @returns {Promise<{buffer: Buffer, path?: string}>}
+ */
+export async function d2ToPng(d2Script, options = {}) {
+  const { output = null, ...d2Options } = options;
+
+  // First convert to SVG
+  const { svg } = await d2ToSvg(d2Script, d2Options);
+
+  // Wrap SVG in HTML for Puppeteer rendering
+  const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    * { margin: 0; padding: 0; }
+    body {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      background: white;
+      min-height: 100vh;
+    }
+    svg { max-width: 100%; height: auto; }
+  </style>
+</head>
+<body>
+  ${svg}
+</body>
+</html>
+  `.trim();
+
+  // Convert to PNG
+  return await htmlToPng(html, {
+    ...options,
+    output,
+    fullPage: true,
+  });
+}
+
+// ============================================================================
+// Template System
+// ============================================================================
+
+/**
+ * Get list of available templates
+ * @returns {Object} Object with html and d2 template arrays
+ */
+export function getAvailableTemplates() {
+  const templatesPath = getTemplatesPath();
+  const templates = { html: [], d2: [] };
+
+  // HTML templates
+  const htmlDir = path.join(templatesPath, 'infographics');
+  if (fs.existsSync(htmlDir)) {
+    templates.html = fs.readdirSync(htmlDir)
+      .filter(f => f.endsWith('.html'))
+      .map(f => f.replace('.html', ''));
+  }
+
+  // D2 templates
+  const d2Dir = path.join(templatesPath, 'diagrams');
+  if (fs.existsSync(d2Dir)) {
+    templates.d2 = fs.readdirSync(d2Dir)
+      .filter(f => f.endsWith('.d2'))
+      .map(f => f.replace('.d2', ''));
+  }
+
+  return templates;
+}
+
+/**
+ * Render an HTML template with data
+ *
+ * @param {string} templateName - Name of the template (without extension)
+ * @param {Object} data - Data to inject into template
+ * @returns {string} Rendered HTML
+ */
+export function renderTemplate(templateName, data = {}) {
+  const templatesPath = getTemplatesPath();
+  const templateFile = path.join(templatesPath, 'infographics', `${templateName}.html`);
+
+  if (!fs.existsSync(templateFile)) {
+    throw new Error(`Template not found: ${templateName}`);
+  }
+
+  let html = fs.readFileSync(templateFile, 'utf-8');
+
+  // Simple template variable replacement: {{variableName}}
+  html = html.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return data[key] !== undefined ? String(data[key]) : match;
+  });
+
+  // Handle arrays for items: {{#items}}...{{/items}}
+  html = html.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (match, key, template) => {
+    const items = data[key];
+    if (!Array.isArray(items)) return '';
+
+    return items.map(item => {
+      let itemHtml = template;
+      for (const [k, v] of Object.entries(item)) {
+        itemHtml = itemHtml.replace(new RegExp(`\\{\\{${k}\\}\\}`, 'g'), String(v));
+      }
+      return itemHtml;
+    }).join('');
+  });
+
+  // Handle JSON data injection: {{json:variableName}}
+  html = html.replace(/\{\{json:(\w+)\}\}/g, (match, key) => {
+    return data[key] !== undefined ? JSON.stringify(data[key]) : 'null';
+  });
+
+  return html;
+}
+
+/**
+ * Render a D2 template with data
+ *
+ * @param {string} templateName - Name of the template (without extension)
+ * @param {Object} data - Data to inject into template
+ * @returns {string} Rendered D2 script
+ */
+export function renderD2Template(templateName, data = {}) {
+  const templatesPath = getTemplatesPath();
+  const templateFile = path.join(templatesPath, 'diagrams', `${templateName}.d2`);
+
+  if (!fs.existsSync(templateFile)) {
+    throw new Error(`D2 template not found: ${templateName}`);
+  }
+
+  let d2Script = fs.readFileSync(templateFile, 'utf-8');
+
+  // Simple variable replacement: {{variableName}}
+  d2Script = d2Script.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return data[key] !== undefined ? String(data[key]) : match;
+  });
+
+  // Handle components array: {{#components}}...{{/components}}
+  d2Script = d2Script.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (match, key, template) => {
+    const items = data[key];
+    if (!Array.isArray(items)) return '';
+
+    return items.map(item => {
+      let itemD2 = template;
+      for (const [k, v] of Object.entries(item)) {
+        itemD2 = itemD2.replace(new RegExp(`\\{\\{${k}\\}\\}`, 'g'), String(v));
+      }
+      return itemD2;
+    }).join('\n');
+  });
+
+  return d2Script;
+}
+
+/**
+ * Convert a template to visual output
+ *
+ * @param {string} templateName - Name of the template
+ * @param {Object} data - Data to inject
+ * @param {string} format - Output format: 'png', 'pdf', 'svg'
+ * @param {Object} options - Additional options
+ * @returns {Promise<{buffer?: Buffer, svg?: string, path?: string}>}
+ */
+export async function templateToVisual(templateName, data, format = 'png', options = {}) {
+  const html = renderTemplate(templateName, data);
+
+  switch (format.toLowerCase()) {
+    case 'png':
+      return await htmlToPng(html, options);
+    case 'pdf':
+      return await htmlToPdf(html, options);
+    default:
+      throw new Error(`Unsupported format: ${format}. Use 'png' or 'pdf'.`);
+  }
+}
+
+/**
+ * Convert a D2 template to visual output
+ *
+ * @param {string} templateName - Name of the D2 template
+ * @param {Object} data - Data to inject
+ * @param {string} format - Output format: 'png', 'svg'
+ * @param {Object} options - Additional options
+ * @returns {Promise<{buffer?: Buffer, svg?: string, path?: string}>}
+ */
+export async function d2TemplateToVisual(templateName, data, format = 'png', options = {}) {
+  const d2Script = renderD2Template(templateName, data);
+
+  switch (format.toLowerCase()) {
+    case 'svg':
+      return await d2ToSvg(d2Script, options);
+    case 'png':
+      return await d2ToPng(d2Script, options);
+    default:
+      throw new Error(`Unsupported format: ${format}. Use 'png' or 'svg'.`);
+  }
+}
+
+// ============================================================================
+// PPTX Generation
+// ============================================================================
+
+/**
+ * Create a PPTX presentation from HTML slides
+ *
+ * @param {Array<{html: string, title?: string}>} slides - Array of slide objects
+ * @param {Object} options - Presentation options
+ * @param {string} options.output - Output file path
+ * @param {string} options.title - Presentation title
+ * @param {string} options.author - Author name
+ * @param {Object} options.slideSize - Slide dimensions
+ * @returns {Promise<{buffer: Buffer, path?: string}>}
+ */
+export async function htmlToPptx(slides, options = {}) {
+  const {
+    output = null,
+    title = 'Presentation',
+    author = 'MyAIDev Method',
+    subject = '',
+    slideSize = { width: 10, height: 7.5 }, // inches (standard 4:3)
+  } = options;
+
+  const pptx = new PptxGenJS();
+
+  // Set presentation properties
+  pptx.title = title;
+  pptx.author = author;
+  pptx.subject = subject;
+  pptx.layout = 'LAYOUT_WIDE'; // 13.33 x 7.5 inches (16:9)
+
+  // Process each slide
+  for (let i = 0; i < slides.length; i++) {
+    const slideData = slides[i];
+    const { html, title: slideTitle } = slideData;
+
+    // Render HTML to PNG
+    const { buffer } = await htmlToPng(html, {
+      width: 1920,
+      height: 1080,
+      deviceScaleFactor: 2,
+    });
+
+    // Create slide
+    const slide = pptx.addSlide();
+
+    // Add background image (the rendered HTML)
+    const base64 = buffer.toString('base64');
+    slide.addImage({
+      data: `data:image/png;base64,${base64}`,
+      x: 0,
+      y: 0,
+      w: '100%',
+      h: '100%',
+    });
+
+    // Optionally add title as text box for accessibility
+    if (slideTitle) {
+      slide.addText(slideTitle, {
+        x: 0.5,
+        y: 0.3,
+        w: '90%',
+        fontSize: 24,
+        bold: true,
+        color: '363636',
+        transparency: 100, // Hidden but accessible
+      });
+    }
+  }
+
+  // Generate PPTX buffer
+  const buffer = await pptx.write({ outputType: 'nodebuffer' });
+
+  // Save to file if output path provided
+  let outputPath = null;
+  if (output) {
+    outputPath = output;
+    await fs.ensureDir(path.dirname(outputPath));
+    await fs.writeFile(outputPath, buffer);
+  }
+
+  return {
+    buffer,
+    path: outputPath,
+    slideCount: slides.length,
+  };
+}
+
+/**
+ * Create PPTX from D2 diagrams
+ *
+ * @param {Array<{d2: string, title?: string}>} slides - Array of D2 slide objects
+ * @param {Object} options - Presentation options
+ * @returns {Promise<{buffer: Buffer, path?: string}>}
+ */
+export async function d2ToPptx(slides, options = {}) {
+  // Convert D2 scripts to HTML slides
+  const htmlSlides = await Promise.all(
+    slides.map(async ({ d2, title }) => {
+      const { svg } = await d2ToSvg(d2);
+      const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    * { margin: 0; padding: 0; }
+    body {
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      align-items: center;
+      background: white;
+      width: 1920px;
+      height: 1080px;
+      padding: 40px;
+      box-sizing: border-box;
+    }
+    h1 {
+      font-family: system-ui, sans-serif;
+      font-size: 48px;
+      margin-bottom: 40px;
+      color: #333;
+    }
+    .diagram {
+      flex: 1;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      width: 100%;
+    }
+    svg { max-width: 100%; max-height: 100%; }
+  </style>
+</head>
+<body>
+  ${title ? `<h1>${title}</h1>` : ''}
+  <div class="diagram">${svg}</div>
+</body>
+</html>
+      `.trim();
+      return { html, title };
+    })
+  );
+
+  return await htmlToPptx(htmlSlides, options);
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Validate HTML string
+ * @param {string} html - HTML to validate
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateHtml(html) {
+  const errors = [];
+
+  if (!html || typeof html !== 'string') {
+    errors.push('HTML must be a non-empty string');
+    return { valid: false, errors };
+  }
+
+  if (!html.includes('<')) {
+    errors.push('HTML appears to have no tags');
+  }
+
+  // Check for common issues
+  const openTags = (html.match(/<[a-z][^>]*[^/]>/gi) || []).length;
+  const closeTags = (html.match(/<\/[a-z]+>/gi) || []).length;
+
+  if (openTags > closeTags + 5) {
+    errors.push('HTML may have unclosed tags');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validate D2 script
+ * @param {string} d2Script - D2 script to validate
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateD2(d2Script) {
+  const errors = [];
+
+  if (!d2Script || typeof d2Script !== 'string') {
+    errors.push('D2 script must be a non-empty string');
+    return { valid: false, errors };
+  }
+
+  // Basic D2 syntax checks
+  if (d2Script.trim().length === 0) {
+    errors.push('D2 script is empty');
+  }
+
+  // Check for common syntax patterns
+  const hasArrows = d2Script.includes('->') || d2Script.includes('<-');
+  const hasColons = d2Script.includes(':');
+  const hasNodes = /\w+/.test(d2Script);
+
+  if (!hasNodes) {
+    errors.push('D2 script must define at least one node');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Estimate render time based on HTML complexity
+ * @param {string} html - HTML content
+ * @returns {number} Estimated time in milliseconds
+ */
+export function estimateRenderTime(html) {
+  const baseTime = 500; // Base Puppeteer overhead
+
+  // Add time for content complexity
+  const charCount = html.length;
+  const tagCount = (html.match(/<[^>]+>/g) || []).length;
+  const imageCount = (html.match(/<img/gi) || []).length;
+  const svgCount = (html.match(/<svg/gi) || []).length;
+
+  let estimate = baseTime;
+  estimate += Math.min(charCount / 100, 500); // Up to 500ms for large content
+  estimate += tagCount * 0.5; // 0.5ms per tag
+  estimate += imageCount * 200; // 200ms per image (network)
+  estimate += svgCount * 50; // 50ms per SVG
+
+  return Math.round(estimate);
+}
+
+/**
+ * Generate a unique filename for output
+ * @param {string} type - Type of content (e.g., 'infographic', 'diagram')
+ * @param {string} slug - Content slug
+ * @param {string} extension - File extension
+ * @returns {string} Unique filename
+ */
+export function generateFilename(type, slug, extension) {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 6);
+  const safeSlug = slug
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 50);
+
+  return `${type}-${safeSlug}-${timestamp}-${random}.${extension}`;
+}
+
+/**
+ * Save visual to assets directory with proper organization
+ * @param {Buffer} buffer - File buffer
+ * @param {Object} metadata - File metadata
+ * @returns {Promise<string>} Output file path
+ */
+export async function saveToAssets(buffer, metadata = {}) {
+  const {
+    type = 'visual',
+    slug = 'output',
+    extension = 'png',
+    category = 'images', // images, documents, diagrams
+  } = metadata;
+
+  const assetsPath = getAssetsPath();
+  const date = new Date().toISOString().split('T')[0];
+  const outputDir = path.join(assetsPath, category, date);
+
+  await fs.ensureDir(outputDir);
+
+  const filename = generateFilename(type, slug, extension);
+  const outputPath = path.join(outputDir, filename);
+
+  await fs.writeFile(outputPath, buffer);
+
+  return outputPath;
+}
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+export default {
+  // HTML Conversion
+  htmlToPng,
+  htmlToPdf,
+  htmlToPptx,
+
+  // D2 Conversion
+  isD2Available,
+  getD2Version,
+  d2ToSvg,
+  d2ToPng,
+  d2ToPptx,
+
+  // Templates
+  getAvailableTemplates,
+  renderTemplate,
+  renderD2Template,
+  templateToVisual,
+  d2TemplateToVisual,
+
+  // Utilities
+  validateHtml,
+  validateD2,
+  estimateRenderTime,
+  generateFilename,
+  saveToAssets,
+  getTemplatesPath,
+  getAssetsPath,
+};