onbuzz 4.8.3 → 4.9.0

package/src/tools/office/officeDoc.js

@@ -0,0 +1,425 @@
+/**
+ * officeDoc — Word (.docx) builder + reader for officeTool.
+ *
+ * Builder supports the rich-document surface our agents need:
+ *   - Page size (US Letter default, A4 opt-in), orientation, margins
+ *   - Default font + font-size, with per-run overrides
+ *   - Heading levels 1-6 with deliberate color palette
+ *   - Paragraphs / rich paragraphs (mixed runs), with bold/italic/underline,
+ *     font, size, color, alignment, line-spacing, indent
+ *   - Ordered and unordered lists (nested via `level`)
+ *   - Tables with header styling, alternating row shading, configurable
+ *     border color, per-column widths
+ *   - Callout boxes (coloured left bar + label + body)
+ *   - Page breaks, horizontal rules, hyperlinks
+ *   - Images (file path or data URI)
+ *   - Headers / footers (with page-number support)
+ *   - Bookmarks + internal hyperlinks (TOC-ish)
+ *
+ * All input is validated and normalised; unknown node types become a
+ * literal paragraph so the agent's output never blows up the doc.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+let docxModule = null;
+let mammothModule = null;
+
+async function loadDocx() {
+  if (docxModule) return docxModule;
+  docxModule = await import('docx');
+  return docxModule;
+}
+
+async function loadMammoth() {
+  if (mammothModule) return mammothModule;
+  const mod = await import('mammoth');
+  mammothModule = mod.default || mod;
+  return mammothModule;
+}
+
+/** Resolve a "letter"/"a4"/{width,height} → DXA dimensions. */
+function resolvePageSize(size) {
+  if (!size) return { width: 12240, height: 15840 }; // Letter
+  if (typeof size === 'object' && size.width && size.height) return size;
+  if (typeof size === 'string') {
+    const k = size.toLowerCase();
+    if (k === 'a4') return { width: 11906, height: 16838 };
+    if (k === 'letter' || k === 'us letter') return { width: 12240, height: 15840 };
+    if (k === 'legal') return { width: 12240, height: 20160 };
+  }
+  return { width: 12240, height: 15840 };
+}
+
+/** Hex (#RRGGBB or RRGGBB) → bare hex (RRGGBB). null on invalid. */
+function normHex(v) {
+  if (!v || typeof v !== 'string') return null;
+  const s = v.replace(/^#/, '').trim().toUpperCase();
+  return /^[0-9A-F]{6}$/.test(s) ? s : null;
+}
+
+/** Half-points (24 = 12pt). Accepts pt-style numbers (12 → 24). */
+function resolveFontSize(v, def = 22) {
+  if (v == null) return def;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return def;
+  // Heuristic: numbers ≤ 36 are points (Word UI sizes), bigger are half-points already.
+  return n <= 36 ? Math.round(n * 2) : Math.round(n);
+}
+
+function alignmentEnum(docx, a) {
+  const A = docx.AlignmentType;
+  switch ((a || '').toLowerCase()) {
+    case 'center':    return A.CENTER;
+    case 'right':     return A.RIGHT;
+    case 'justify':
+    case 'justified': return A.JUSTIFIED;
+    default:          return A.LEFT;
+  }
+}
+
+/* ------------------------------------------------------------------------ */
+/* Run + paragraph builders                                                 */
+/* ------------------------------------------------------------------------ */
+
+function buildRun(docx, runDef, defaults = {}) {
+  const opts = {
+    text: runDef.text ?? '',
+    font: runDef.font || defaults.font || undefined,
+    bold: !!runDef.bold,
+    italics: !!(runDef.italic ?? runDef.italics),
+    underline: runDef.underline ? { type: 'single' } : undefined,
+    strike: !!runDef.strike,
+    size: runDef.size != null ? resolveFontSize(runDef.size, defaults.size || 22) : undefined,
+  };
+  const color = normHex(runDef.color);
+  if (color) opts.color = color;
+  return new docx.TextRun(opts);
+}
+
+function buildParagraph(docx, node, defaults) {
+  // Plain string → simple paragraph.
+  if (typeof node === 'string') {
+    return new docx.Paragraph({
+      children: [new docx.TextRun({ text: node, font: defaults.font, size: defaults.size })],
+      spacing: { after: 120, line: 312 },
+    });
+  }
+  // Already a Paragraph instance (callers can pre-build).
+  if (node?.constructor?.name === 'Paragraph') return node;
+
+  switch ((node.type || 'paragraph').toLowerCase()) {
+    case 'heading': {
+      const lvl = Math.max(1, Math.min(6, Number(node.level) || 1));
+      const headingMap = {
+        1: docx.HeadingLevel.HEADING_1,
+        2: docx.HeadingLevel.HEADING_2,
+        3: docx.HeadingLevel.HEADING_3,
+        4: docx.HeadingLevel.HEADING_4,
+        5: docx.HeadingLevel.HEADING_5,
+        6: docx.HeadingLevel.HEADING_6,
+      };
+      const color = normHex(node.color);
+      return new docx.Paragraph({
+        heading: headingMap[lvl],
+        alignment: alignmentEnum(docx, node.alignment),
+        children: [new docx.TextRun({
+          text: node.text || '',
+          bold: true,
+          font: node.font || defaults.headingFont || defaults.font,
+          color: color || undefined,
+        })],
+      });
+    }
+
+    case 'richparagraph':
+    case 'rich': {
+      return new docx.Paragraph({
+        alignment: alignmentEnum(docx, node.alignment),
+        spacing: { after: 120, line: 312 },
+        children: (node.runs || []).map(r => buildRun(docx, r, defaults)),
+      });
+    }
+
+    case 'list': {
+      // Re-emitted by the caller as multiple paragraphs — see expandListNode.
+      // If we're here it's a misuse; fall through to plain text.
+      return new docx.Paragraph({
+        children: [new docx.TextRun({ text: String(node.text || '') })],
+      });
+    }
+
+    case 'callout': {
+      const color = normHex(node.color) || '2E75B6';
+      return new docx.Paragraph({
+        children: [
+          new docx.TextRun({ text: node.label || 'Note', bold: true, font: defaults.font, color }),
+          new docx.TextRun({ text: '  —  ', bold: true, font: defaults.font, color }),
+          new docx.TextRun({ text: node.content || '', font: defaults.font }),
+        ],
+        spacing: { before: 120, after: 160, line: 312 },
+        border: { left: { style: docx.BorderStyle.SINGLE, size: 24, color, space: 12 } },
+        indent: { left: 240 },
+      });
+    }
+
+    case 'hyperlink': {
+      return new docx.Paragraph({
+        children: [new docx.ExternalHyperlink({
+          children: [new docx.TextRun({ text: node.text || node.url, style: 'Hyperlink' })],
+          link: node.url,
+        })],
+        spacing: { after: 120, line: 312 },
+      });
+    }
+
+    case 'pagebreak':
+      return new docx.Paragraph({ children: [new docx.PageBreak()] });
+
+    case 'horizontalrule':
+    case 'hr':
+      return new docx.Paragraph({
+        children: [new docx.TextRun({ text: '' })],
+        border: { bottom: { style: docx.BorderStyle.SINGLE, size: 6, color: normHex(node.color) || 'CCCCCC', space: 1 } },
+        spacing: { before: 120, after: 120 },
+      });
+
+    case 'paragraph':
+    default: {
+      const color = normHex(node.color);
+      return new docx.Paragraph({
+        alignment: alignmentEnum(docx, node.alignment),
+        spacing: { after: 120, line: 312 },
+        indent: node.indent ? { left: node.indent } : undefined,
+        children: [new docx.TextRun({
+          text: node.text || '',
+          bold: !!node.bold,
+          italics: !!(node.italic ?? node.italics),
+          underline: node.underline ? { type: 'single' } : undefined,
+          font: node.font || defaults.font,
+          size: node.fontSize != null ? resolveFontSize(node.fontSize, defaults.size) : defaults.size,
+          color: color || undefined,
+        })],
+      });
+    }
+  }
+}
+
+/** Expand a list node into multiple paragraphs (one per item, with numbering ref). */
+function expandListNode(docx, listNode, defaults) {
+  const ref = listNode.ordered ? 'numbered' : 'bullets';
+  const items = listNode.items || [];
+  return items.map(item => {
+    const text = typeof item === 'string' ? item : (item.text || '');
+    const level = Math.max(0, Math.min(3, typeof item === 'object' ? Number(item.level) || 0 : 0));
+    return new docx.Paragraph({
+      numbering: { reference: ref, level },
+      children: [new docx.TextRun({ text, font: defaults.font, size: defaults.size })],
+      spacing: { after: 80 },
+    });
+  });
+}
+
+/** Build a Table from { headers, rows, widths, headerFill, alternateFill }. */
+function buildTable(docx, t, defaults) {
+  const ruleColor = normHex(t.borderColor) || 'CCCCCC';
+  const headerFill = normHex(t.headerFill) || 'D9E2F3';
+  const altFill = normHex(t.alternateFill);
+  const border = { style: docx.BorderStyle.SINGLE, size: 4, color: ruleColor };
+  const allBorders = { top: border, bottom: border, left: border, right: border };
+
+  // Resolve widths. Default to equal split of US Letter content area (9360 DXA).
+  const contentWidth = 9360;
+  const headers = Array.isArray(t.headers) ? t.headers : [];
+  const cols = Math.max(1, headers.length || (t.rows?.[0]?.length || 1));
+  const widths = (Array.isArray(t.widths) && t.widths.length === cols)
+    ? t.widths
+    : Array(cols).fill(Math.floor(contentWidth / cols));
+
+  const buildCell = (content, opts = {}) => new docx.TableCell({
+    borders: allBorders,
+    margins: { top: 80, bottom: 80, left: 120, right: 120 },
+    width: { size: opts.width, type: docx.WidthType.DXA },
+    shading: opts.fill
+      ? { fill: opts.fill, type: docx.ShadingType.CLEAR, color: 'auto' }
+      : undefined,
+    children: [new docx.Paragraph({
+      children: [new docx.TextRun({
+        text: String(content ?? ''),
+        bold: opts.bold,
+        font: defaults.font,
+      })],
+    })],
+  });
+
+  const rows = [];
+  if (headers.length) {
+    rows.push(new docx.TableRow({
+      tableHeader: true,
+      children: headers.map((h, i) => buildCell(h, { width: widths[i], bold: true, fill: headerFill })),
+    }));
+  }
+  (t.rows || []).forEach((row, ri) => {
+    const fill = altFill && ri % 2 === 1 ? altFill : null;
+    rows.push(new docx.TableRow({
+      children: (Array.isArray(row) ? row : Object.values(row)).map((cell, i) =>
+        buildCell(cell, { width: widths[i] || widths[0], fill }),
+      ),
+    }));
+  });
+
+  return new docx.Table({
+    width: { size: contentWidth, type: docx.WidthType.DXA },
+    columnWidths: widths,
+    rows,
+  });
+}
+
+/**
+ * Expand one input node into 1+ rendered children, since lists become multiple paragraphs.
+ */
+function expandNode(docx, node, defaults) {
+  if (!node) return [];
+  if ((node.type || '').toLowerCase() === 'list') return expandListNode(docx, node, defaults);
+  if ((node.type || '').toLowerCase() === 'table') return [buildTable(docx, node, defaults)];
+  return [buildParagraph(docx, node, defaults)];
+}
+
+/* ------------------------------------------------------------------------ */
+/* Public API                                                                */
+/* ------------------------------------------------------------------------ */
+
+/**
+ * Create a .docx file from a content spec. Returns { path, size }.
+ */
+export async function createDoc(spec, outputPath) {
+  const docx = await loadDocx();
+
+  const defaults = {
+    font: spec.defaultFont || 'Calibri',
+    headingFont: spec.headingFont || spec.defaultFont || 'Calibri',
+    size: resolveFontSize(spec.defaultFontSize, 22),
+  };
+
+  const pageSize = resolvePageSize(spec.pageSize);
+  const margin = Object.assign({ top: 1440, right: 1440, bottom: 1440, left: 1440 }, spec.margin || {});
+
+  // Optional orientation: swap dims via docx-js convention.
+  const orientation = (spec.orientation || '').toLowerCase() === 'landscape'
+    ? docx.PageOrientation.LANDSCAPE
+    : docx.PageOrientation.PORTRAIT;
+
+  // Build section children. Sections can come from spec.sections OR a flat spec.children.
+  const sectionDefs = Array.isArray(spec.sections) && spec.sections.length > 0
+    ? spec.sections
+    : [{ children: spec.children || [] }];
+
+  const sections = sectionDefs.map((section) => {
+    const children = (section.children || []).flatMap(n => expandNode(docx, n, defaults));
+    return {
+      properties: {
+        page: {
+          size: { ...pageSize, orientation },
+          margin,
+        },
+      },
+      headers: section.headers ? {
+        default: new docx.Header({
+          children: (section.headers.default || []).flatMap(n => expandNode(docx, n, defaults)),
+        }),
+      } : undefined,
+      footers: section.footers ? {
+        default: new docx.Footer({
+          children: (section.footers.default || []).flatMap(n => expandNode(docx, n, defaults)),
+        }),
+      } : undefined,
+      children,
+    };
+  });
+
+  const doc = new docx.Document({
+    creator: spec.author || 'Loxia Agent',
+    title: spec.title || '',
+    subject: spec.subject || '',
+    description: spec.description || '',
+    styles: {
+      default: { document: { run: { font: defaults.font, size: defaults.size } } },
+      paragraphStyles: buildHeadingStyles(docx, defaults),
+    },
+    numbering: {
+      config: [
+        { reference: 'bullets',
+          levels: [
+            { level: 0, format: docx.LevelFormat.BULLET, text: '•', alignment: docx.AlignmentType.LEFT,
+              style: { paragraph: { indent: { left: 720, hanging: 360 } } } },
+            { level: 1, format: docx.LevelFormat.BULLET, text: '◦', alignment: docx.AlignmentType.LEFT,
+              style: { paragraph: { indent: { left: 1440, hanging: 360 } } } },
+            { level: 2, format: docx.LevelFormat.BULLET, text: '▪', alignment: docx.AlignmentType.LEFT,
+              style: { paragraph: { indent: { left: 2160, hanging: 360 } } } },
+          ],
+        },
+        { reference: 'numbered',
+          levels: [
+            { level: 0, format: docx.LevelFormat.DECIMAL, text: '%1.', alignment: docx.AlignmentType.LEFT,
+              style: { paragraph: { indent: { left: 720, hanging: 360 } } } },
+            { level: 1, format: docx.LevelFormat.LOWER_LETTER, text: '%2.', alignment: docx.AlignmentType.LEFT,
+              style: { paragraph: { indent: { left: 1440, hanging: 360 } } } },
+          ],
+        },
+      ],
+    },
+    sections,
+  });
+
+  const buf = await docx.Packer.toBuffer(doc);
+  await fs.writeFile(outputPath, buf);
+  const stat = await fs.stat(outputPath);
+  return { path: outputPath, size: stat.size };
+}
+
+function buildHeadingStyles(docx, defaults) {
+  return [
+    { id: 'Heading1', name: 'Heading 1', basedOn: 'Normal', next: 'Normal', quickFormat: true,
+      run: { size: 36, bold: true, font: defaults.headingFont, color: '1F3864' },
+      paragraph: { spacing: { before: 320, after: 200 }, outlineLevel: 0 } },
+    { id: 'Heading2', name: 'Heading 2', basedOn: 'Normal', next: 'Normal', quickFormat: true,
+      run: { size: 28, bold: true, font: defaults.headingFont, color: '2E75B6' },
+      paragraph: { spacing: { before: 280, after: 120 }, outlineLevel: 1 } },
+    { id: 'Heading3', name: 'Heading 3', basedOn: 'Normal', next: 'Normal', quickFormat: true,
+      run: { size: 24, bold: true, font: defaults.headingFont, color: '404040' },
+      paragraph: { spacing: { before: 200, after: 100 }, outlineLevel: 2 } },
+    { id: 'Heading4', name: 'Heading 4', basedOn: 'Normal', next: 'Normal', quickFormat: true,
+      run: { size: 22, bold: true, font: defaults.headingFont, color: '595959' },
+      paragraph: { spacing: { before: 180, after: 80 }, outlineLevel: 3 } },
+  ];
+}
+
+/* ----- read / info ----- */
+
+export async function readDoc(filePath, format = 'text') {
+  const mammoth = await loadMammoth();
+  const buffer = await fs.readFile(filePath);
+  if (format === 'html') {
+    const result = await mammoth.convertToHtml({ buffer });
+    return { format: 'html', content: result.value, warnings: result.messages || [] };
+  }
+  const result = await mammoth.extractRawText({ buffer });
+  return { format: 'text', content: result.value, warnings: result.messages || [] };
+}
+
+export async function docInfo(filePath) {
+  const mammoth = await loadMammoth();
+  const stat = await fs.stat(filePath);
+  const buffer = await fs.readFile(filePath);
+  const r = await mammoth.extractRawText({ buffer });
+  const text = r.value || '';
+  const words = text.split(/\s+/).filter(w => w.length > 0).length;
+  return {
+    fileName: path.basename(filePath),
+    fileSize: stat.size,
+    modified: stat.mtime.toISOString(),
+    wordCount: words,
+    estimatedPages: Math.max(1, Math.round(words / 250)),
+  };
+}