Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
10.6 KB
Raw Blame
/** The DOCX generator (clerum__generate_docx): markdown body, tables and images built with docx. */
import {
  AlignmentType,
  Document as DocxDocument,
  Footer as DocxFooter,
  Header as DocxHeader,
  Table as DocxTable,
  HeadingLevel,
  Packer,
  PageNumber,
  PageOrientation,
  Paragraph,
  TabStopType,
  TextRun,
} from 'docx'
import {
  artifactResult,
  claimOutputFile,
  enforceQuota,
  ensureDir,
  outputFilename,
  replacedBytes,
  writeArtifact,
} from './artifactOutput'
import { EMPTY_DOCUMENT_NOTE, printedBranding } from './documentChrome'
import { type DocxImagePlacement, docxImageParagraph } from './docxImages'
import { textRuns } from './docxInline'
import { bodyHasText, bodyToDocxChildren } from './docxMarkdown'
import { DOCX_COMPLEX_FONT, DOCX_LATIN_FONT, docxDirection } from './docxScript'
import {
  DOCX_CONTENT_WIDTH_TWIPS,
  DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS,
  DOCX_PALETTES,
  DocxListNumbering,
  docxHex,
} from './docxStyle'
import { buildDocxTable, docxSections } from './docxTable'
import { htmlToPlainText } from './inlineMarkup'
import { choose } from './ownEntry'
import { normalizeTableRows } from './tableRows'
import { documentEastAsianScript, eastAsianScript } from './textScript'
import type { InternalToolResult } from './types'

/**
 * Widest a DOCX image is drawn, in pixels at 96 dpi; the page leaves about 601
 * between its margins.
 */
const DOCX_MAX_IMAGE_WIDTH = 560
const DOCX_MAX_IMAGE_HEIGHT = 380

/** Largest logo drawn above the title, in pixels. */
const DOCX_LOGO_BOX = { width: 160, height: 60 }

/** Footer lines kept, as in the PDF. */
const DOCX_MAX_FOOTER_LINES = 6

interface DocxBranding {
  companyName?: string
  logoPath?: string
  footerText?: string
}

interface DocxImageArg {
  width?: number
  height?: number
  alignment?: string
}

interface DocxTableArg {
  headers?: unknown
  rows?: unknown
  layout?: unknown
}

export async function runGenerateDocx(
  args: Record<string, unknown>,
  outputDir: string
): Promise<InternalToolResult> {
  try {
    const filename = outputFilename(args.filename, 'docx', 'output')
    const title = args.title ? htmlToPlainText(String(args.title)) : undefined
    const headline = args.headline ? htmlToPlainText(String(args.headline)) : undefined
    const body = String(args.body ?? '')
    const branding: DocxBranding = printedBranding(args.branding)
    const images: unknown[] = Array.isArray(args.images) ? args.images : []
    const tables: unknown[] = Array.isArray(args.tables) ? args.tables : []
    const warnings: string[] = []
    const palette =
      DOCX_PALETTES[
        choose(args.palette, Object.keys(DOCX_PALETTES), 'default', 'palette', warnings)
      ]
    const numbering = new DocxListNumbering()
    const imageBox = { width: DOCX_MAX_IMAGE_WIDTH, height: DOCX_MAX_IMAGE_HEIGHT }
    let embedded = 0
    let imageLeftOut = false
    const embed = (
      ref: unknown,
      label: string,
      box: { width: number; height: number },
      placement: DocxImagePlacement
    ): Paragraph | undefined => {
      // Word needs each drawing's id unique in the document; the next one is unused.
      const id = embedded + 1
      const paragraph = docxImageParagraph(ref, outputDir, box, placement, warnings, label, id)
      if (paragraph) embedded++
      else imageLeftOut = true
      return paragraph
    }

    const children: (Paragraph | DocxTable)[] = []

    if (branding.logoPath) {
      const logo = embed(branding.logoPath, 'branding.logoPath', DOCX_LOGO_BOX, {
        spacing: { after: 160 },
      })
      if (logo) children.push(logo)
    }
    if (title) {
      children.push(
        new Paragraph({
          ...docxDirection(title),
          heading: HeadingLevel.TITLE,
          spacing: { after: 120 },
          children: textRuns(
            title,
            { bold: true, color: docxHex(palette.primary), size: 48 },
            eastAsianScript(title)
          ),
        })
      )
    }
    if (headline) {
      children.push(
        new Paragraph({
          ...docxDirection(headline),
          spacing: { after: 240 },
          children: textRuns(
            headline,
            { italics: true, color: docxHex(palette.muted), size: 26 },
            eastAsianScript(headline)
          ),
        })
      )
    }

    children.push(
      ...bodyToDocxChildren(body, {
        palette,
        numbering,
        warnings,
        image: (file, alt) =>
          embed(file, 'body', imageBox, {
            altText: alt,
            spacing: { before: 120, after: 120 },
          }),
      })
    )

    let tablesWritten = 0
    const tableTexts: unknown[] = []
    tables.forEach((table, i) => {
      const spec = (table && typeof table === 'object' ? table : {}) as DocxTableArg
      const headers = Array.isArray(spec.headers) ? spec.headers : []
      if (headers.length === 0) {
        warnings.push(
          `tables[${i}] has no headers and was left out; give it a headers array of column names.`
        )
        return
      }
      const rows = normalizeTableRows(spec.rows, headers, `tables[${i}]`, warnings)
      tableTexts.push(...headers)
      for (const row of rows) tableTexts.push(...row)
      const layout = spec.layout === 'minimal' || spec.layout === 'grid' ? spec.layout : 'striped'
      children.push(buildDocxTable(headers, rows, palette, layout, warnings, `tables[${i}]`))
      children.push(new Paragraph({ children: [new TextRun({ text: '' })] }))
      tablesWritten++
    })

    images.forEach((img, i) => {
      const spec = (img && typeof img === 'object' ? img : {}) as DocxImageArg
      const paragraph = embed(img, `images[${i}]`, imageBox, {
        width: spec.width,
        height: spec.height,
        alignment: spec.alignment,
        spacing: { before: 160, after: 160 },
      })
      if (paragraph) children.push(paragraph)
    })

    if (embedded === 0 && !title && !headline && tablesWritten === 0 && !bodyHasText(body)) {
      if (warnings.length > 0) {
        const hint = imageLeftOut
          ? ' Pass images as file names in the output folder, such as those clerum__generate_chart returns.'
          : ''
        return {
          success: false,
          error: `Nothing could be written to ${filename}. ${[...new Set(warnings)].join(' ')}${hint}`,
        }
      }
      warnings.push(EMPTY_DOCUMENT_NOTE)
    }

    // The page number follows the first footer line; the docx lib writes it as
    // a field Word fills in on open. The other lines are run from a leading
    // newline and lose its empty run, so each starts on a line of its own.
    const footerMuted = { color: docxHex(palette.muted), size: 18 }
    const footerLines = (branding.footerText ?? '').replace(/\r\n?/g, '\n').split('\n')
    if (footerLines.length > DOCX_MAX_FOOTER_LINES) {
      warnings.push(
        `branding.footerText takes ${footerLines.length} lines, but only ` +
          `${DOCX_MAX_FOOTER_LINES} fit in the footer, so the rest was cut. Keep it to a line or two.`
      )
      footerLines.length = DOCX_MAX_FOOTER_LINES
      footerLines[DOCX_MAX_FOOTER_LINES - 1] += '...'
    }
    const [firstFooterLine, ...moreFooterLines] = footerLines
    const headerMuted = { color: docxHex(palette.muted), size: 18 }
    const companyName = branding.companyName ?? ''
    // The page number and the title sit at the right margin, on a right tab
    // stop at the width of the section's page.
    const running = (width: number) => {
      const tabStops = [{ type: TabStopType.RIGHT, position: width }]
      const footer = new DocxFooter({
        children: [
          new Paragraph({
            alignment: AlignmentType.LEFT,
            tabStops,
            children: [
              ...textRuns(firstFooterLine, footerMuted, eastAsianScript(firstFooterLine)),
              new TextRun({ text: '\t', ...footerMuted }),
              new TextRun({ children: ['Page ', PageNumber.CURRENT], ...footerMuted }),
              new TextRun({ children: [' / ', PageNumber.TOTAL_PAGES], ...footerMuted }),
              ...(moreFooterLines.length > 0
                ? textRuns(
                    `\n${moreFooterLines.join('\n')}`,
                    footerMuted,
                    eastAsianScript(moreFooterLines.join(' '))
                  ).slice(1)
                : []),
            ],
          }),
        ],
      })
      const header = new DocxHeader({
        children: [
          new Paragraph({
            alignment: AlignmentType.LEFT,
            tabStops,
            children: [
              ...textRuns(companyName, headerMuted, eastAsianScript(companyName)),
              new TextRun({ text: '\t', ...headerMuted }),
              ...textRuns(title ?? '', headerMuted, eastAsianScript(title ?? '')),
            ],
          }),
        ],
      })
      return { header, footer }
    }
    const portrait = running(DOCX_CONTENT_WIDTH_TWIPS)
    const landscape = running(DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS)

    // Runs of Han characters alone name no East Asian face and take this one.
    const eastAsia = documentEastAsianScript(
      [title, headline, body, branding.companyName, branding.footerText, ...tableTexts]
        .filter((text): text is string => typeof text === 'string')
        .join('\n')
    )
    const doc = new DocxDocument({
      creator: branding.companyName ?? '',
      title: title ?? 'Report',
      description: headline,
      styles: {
        default: {
          document: {
            run: {
              font: {
                ascii: DOCX_LATIN_FONT,
                hAnsi: DOCX_LATIN_FONT,
                cs: DOCX_COMPLEX_FONT,
                ...(eastAsia ? { eastAsia: eastAsia.font } : {}),
              },
              ...(eastAsia ? { language: { eastAsia: eastAsia.lang } } : {}),
              size: 22,
              color: docxHex(palette.text),
            },
            paragraph: { spacing: { line: 320, after: 80 } },
          },
        },
      },
      numbering: { config: numbering.config() },
      sections: docxSections(children).map(section => ({
        properties: section.landscape
          ? { page: { size: { orientation: PageOrientation.LANDSCAPE } } }
          : {},
        headers: { default: (section.landscape ? landscape : portrait).header },
        footers: { default: (section.landscape ? landscape : portrait).footer },
        children: section.children,
      })),
    })

    const buffer = await Packer.toBuffer(doc)
    ensureDir(outputDir)
    const target = claimOutputFile(outputDir, filename)
    enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))
    writeArtifact(target, buffer)

    return artifactResult(target, 'docx', { warnings: [...new Set(warnings)] })
  } catch (err) {
    return { success: false, error: err instanceof Error ? err.message : String(err) }
  }
}