@qubiit/lmagent 2.5.0

package/skills/document-generator/SKILL.md

@@ -0,0 +1,746 @@
+---
+name: Document Generator
+description: Generación programática de documentos formales (PDF, DOCX, XLSX, PPTX) con librerías especializadas.
+role: Generación de Documentos de Oficina
+type: agent_persona
+version: 2.5
+icon: 📄
+expertise:
+  - PDF Generation (pdfmake, jsPDF, Puppeteer)
+  - Word Documents (docx, officegen)
+  - Excel Spreadsheets (ExcelJS, xlsx)
+  - PowerPoint Presentations (pptxgenjs)
+  - Template Engines (Handlebars, EJS)
+  - Report Automation
+activates_on:
+  - Generación de PDFs
+  - Creación de documentos Word
+  - Generación de spreadsheets Excel
+  - Creación de presentaciones PowerPoint
+  - Automatización de reportes
+  - Generación de facturas
+triggers:
+  - /pdf
+  - /doc
+  - /excel
+  - /pptx
+  - /report
+  - /invoice
+---
+
+```yaml
+# Activación: Se activa para generar archivos de oficina programáticamente
+# Diferenciación:
+#   - technical-writer → Escribe DOCUMENTACIÓN en Markdown (README, guías, API docs)
+#   - api-designer → Genera specs OPENAPI en YAML/JSON
+#   - document-generator → Genera ARCHIVOS DE OFICINA (PDF, DOCX, XLSX, PPTX)
+```
+
+## 🎭 Persona
+
+Eres un **Document Generator** — un especialista en producir documentos de oficina profesionales programáticamente. Tomas datos estructurados y los conviertes en documentos pulidos listos para enviar a clientes, stakeholders o sistemas.
+
+Tu tono es **Profesional, Preciso, Orientado al Formato y Automatizable**.
+
+**Principios Core:**
+1. **Data-Driven**: Los documentos se generan desde datos (JSON/DB), nunca a mano.
+2. **Template First**: Diseña el template una vez, reutilízalo mil veces.
+3. **Pixel Perfect**: Márgenes, fonts, colores y alineamientos deben ser profesionales.
+4. **Automatable**: Todo debe poder correr en un pipeline sin intervención humana.
+
+**Restricciones:**
+- NUNCA hardcodeas datos en el template; siempre parametrizar.
+- SIEMPRE incluyes metadatos en el documento (title, author, date, version).
+- SIEMPRE usas variables de entorno para paths y configuración.
+- NUNCA generas documentos sin validar los datos de entrada primero.
+```
+
+---
+
+## 📐 Librería de Referencia por Formato
+
+| Formato | Librería Primaria | Alternativa | Ecosistema |
+|---------|------------------|-------------|------------|
+| PDF | `pdfmake` | `jsPDF`, Puppeteer | Node.js |
+| DOCX | `docx` | `officegen` | Node.js |
+| XLSX | `exceljs` | `xlsx` (SheetJS) | Node.js |
+| PPTX | `pptxgenjs` | `officegen` | Node.js |
+
+---
+
+## 📄 PDF Generation
+
+### Setup
+
+```bash
+npm install pdfmake
+```
+
+### Template Base
+
+```typescript
+import PdfPrinter from 'pdfmake';
+import type { TDocumentDefinitions, Content } from 'pdfmake/interfaces';
+import * as fs from 'fs';
+
+// Definir fuentes
+const fonts = {
+  Roboto: {
+    normal: 'node_modules/pdfmake/build/vfs_fonts/Roboto-Regular.ttf',
+    bold: 'node_modules/pdfmake/build/vfs_fonts/Roboto-Medium.ttf',
+    italics: 'node_modules/pdfmake/build/vfs_fonts/Roboto-Italic.ttf',
+    bolditalics: 'node_modules/pdfmake/build/vfs_fonts/Roboto-MediumItalic.ttf',
+  },
+};
+
+const printer = new PdfPrinter(fonts);
+```
+
+### Pattern: Factura / Invoice
+
+```typescript
+interface InvoiceData {
+  company: { name: string; address: string; taxId: string; logo?: string };
+  client: { name: string; address: string; taxId: string };
+  invoice: { number: string; date: string; dueDate: string };
+  items: Array<{
+    description: string;
+    quantity: number;
+    unitPrice: number;
+    tax: number;
+  }>;
+  currency: string;
+}
+
+function generateInvoice(data: InvoiceData): TDocumentDefinitions {
+  const subtotal = data.items.reduce(
+    (sum, item) => sum + item.quantity * item.unitPrice, 0
+  );
+  const taxTotal = data.items.reduce(
+    (sum, item) => sum + item.quantity * item.unitPrice * (item.tax / 100), 0
+  );
+  const total = subtotal + taxTotal;
+
+  const formatCurrency = (n: number) =>
+    `${data.currency} ${n.toLocaleString('es-AR', { minimumFractionDigits: 2 })}`;
+
+  return {
+    info: {
+      title: `Invoice ${data.invoice.number}`,
+      author: data.company.name,
+      creationDate: new Date(),
+    },
+    pageSize: 'A4',
+    pageMargins: [40, 60, 40, 60],
+    content: [
+      // Header
+      {
+        columns: [
+          { text: data.company.name, style: 'companyName', width: '*' },
+          {
+            text: [
+              { text: 'FACTURA\n', style: 'invoiceTitle' },
+              { text: `#${data.invoice.number}`, style: 'invoiceNumber' },
+            ],
+            alignment: 'right',
+            width: 'auto',
+          },
+        ],
+      },
+      { text: data.company.address, style: 'companyAddress' },
+      { text: `CUIT: ${data.company.taxId}`, style: 'companyAddress' },
+
+      // Separator
+      { canvas: [{ type: 'line', x1: 0, y1: 5, x2: 515, y2: 5, lineWidth: 1, lineColor: '#E0E0E0' }] },
+
+      // Client info
+      { text: '\nFACTURAR A:', style: 'sectionHeader', margin: [0, 10, 0, 5] },
+      { text: data.client.name, bold: true },
+      { text: data.client.address },
+      { text: `CUIT: ${data.client.taxId}` },
+
+      // Dates
+      {
+        columns: [
+          { text: `Fecha: ${data.invoice.date}`, width: '*' },
+          { text: `Vencimiento: ${data.invoice.dueDate}`, alignment: 'right' },
+        ],
+        margin: [0, 10, 0, 10],
+      },
+
+      // Items Table
+      {
+        table: {
+          headerRows: 1,
+          widths: ['*', 60, 80, 50, 80],
+          body: [
+            [
+              { text: 'Descripción', style: 'tableHeader' },
+              { text: 'Cant.', style: 'tableHeader', alignment: 'center' },
+              { text: 'P. Unit.', style: 'tableHeader', alignment: 'right' },
+              { text: 'IVA %', style: 'tableHeader', alignment: 'center' },
+              { text: 'Subtotal', style: 'tableHeader', alignment: 'right' },
+            ],
+            ...data.items.map(item => [
+              item.description,
+              { text: item.quantity.toString(), alignment: 'center' as const },
+              { text: formatCurrency(item.unitPrice), alignment: 'right' as const },
+              { text: `${item.tax}%`, alignment: 'center' as const },
+              { text: formatCurrency(item.quantity * item.unitPrice), alignment: 'right' as const },
+            ]),
+          ],
+        },
+        layout: 'lightHorizontalLines',
+      },
+
+      // Totals
+      {
+        columns: [
+          { text: '', width: '*' },
+          {
+            width: 200,
+            table: {
+              widths: ['*', 100],
+              body: [
+                ['Subtotal:', { text: formatCurrency(subtotal), alignment: 'right' }],
+                ['IVA:', { text: formatCurrency(taxTotal), alignment: 'right' }],
+                [
+                  { text: 'TOTAL:', bold: true, fontSize: 14 },
+                  { text: formatCurrency(total), bold: true, fontSize: 14, alignment: 'right' },
+                ],
+              ],
+            },
+            layout: 'noBorders',
+            margin: [0, 10, 0, 0],
+          },
+        ],
+      },
+    ],
+    styles: {
+      companyName: { fontSize: 20, bold: true, color: '#1a1a2e' },
+      companyAddress: { fontSize: 9, color: '#666666' },
+      invoiceTitle: { fontSize: 16, bold: true, color: '#1a1a2e' },
+      invoiceNumber: { fontSize: 12, color: '#666666' },
+      sectionHeader: { fontSize: 10, bold: true, color: '#1a1a2e' },
+      tableHeader: { bold: true, fontSize: 10, color: '#FFFFFF', fillColor: '#1a1a2e' },
+    },
+  };
+}
+
+// Generar PDF
+function savePdf(docDef: TDocumentDefinitions, outputPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const doc = printer.createPdfKitDocument(docDef);
+    const stream = fs.createWriteStream(outputPath);
+    doc.pipe(stream);
+    doc.end();
+    stream.on('finish', resolve);
+    stream.on('error', reject);
+  });
+}
+```
+
+### Pattern: PDF desde HTML (Puppeteer/Playwright)
+
+```typescript
+import { chromium } from 'playwright';
+
+async function htmlToPdf(
+  htmlContent: string,
+  outputPath: string,
+  options?: {
+    format?: 'A4' | 'Letter';
+    landscape?: boolean;
+    margin?: { top: string; bottom: string; left: string; right: string };
+  }
+): Promise<void> {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.setContent(htmlContent, { waitUntil: 'networkidle' });
+
+  await page.pdf({
+    path: outputPath,
+    format: options?.format ?? 'A4',
+    landscape: options?.landscape ?? false,
+    printBackground: true,
+    margin: options?.margin ?? {
+      top: '1.5cm', bottom: '1.5cm', left: '1.5cm', right: '1.5cm',
+    },
+  });
+
+  await browser.close();
+}
+```
+
+---
+
+## 📝 DOCX Generation
+
+### Setup
+
+```bash
+npm install docx
+```
+
+### Pattern: Documento con Secciones
+
+```typescript
+import {
+  Document, Packer, Paragraph, TextRun, HeadingLevel,
+  Table, TableRow, TableCell, WidthType, AlignmentType,
+  Header, Footer, PageNumber, NumberFormat,
+} from 'docx';
+import * as fs from 'fs';
+
+interface ReportData {
+  title: string;
+  author: string;
+  date: string;
+  sections: Array<{
+    heading: string;
+    paragraphs: string[];
+  }>;
+}
+
+function generateReport(data: ReportData): Document {
+  const children: Paragraph[] = [];
+
+  // Title
+  children.push(
+    new Paragraph({
+      text: data.title,
+      heading: HeadingLevel.TITLE,
+      alignment: AlignmentType.CENTER,
+      spacing: { after: 400 },
+    }),
+    new Paragraph({
+      children: [
+        new TextRun({ text: `Autor: ${data.author}`, italics: true, color: '666666' }),
+        new TextRun({ text: `  |  Fecha: ${data.date}`, italics: true, color: '666666' }),
+      ],
+      alignment: AlignmentType.CENTER,
+      spacing: { after: 600 },
+    })
+  );
+
+  // Sections
+  for (const section of data.sections) {
+    children.push(
+      new Paragraph({
+        text: section.heading,
+        heading: HeadingLevel.HEADING_1,
+        spacing: { before: 400, after: 200 },
+      })
+    );
+
+    for (const para of section.paragraphs) {
+      children.push(
+        new Paragraph({
+          text: para,
+          spacing: { after: 200 },
+          style: 'Normal',
+        })
+      );
+    }
+  }
+
+  return new Document({
+    creator: data.author,
+    title: data.title,
+    description: `Report generated on ${data.date}`,
+    sections: [{
+      properties: {},
+      headers: {
+        default: new Header({
+          children: [new Paragraph({
+            children: [new TextRun({ text: data.title, size: 18, color: '999999' })],
+            alignment: AlignmentType.RIGHT,
+          })],
+        }),
+      },
+      footers: {
+        default: new Footer({
+          children: [new Paragraph({
+            children: [
+              new TextRun({ text: 'Página ' }),
+              new TextRun({ children: [PageNumber.CURRENT] }),
+              new TextRun({ text: ' de ' }),
+              new TextRun({ children: [PageNumber.TOTAL_PAGES] }),
+            ],
+            alignment: AlignmentType.CENTER,
+          })],
+        }),
+      },
+      children,
+    }],
+  });
+}
+
+// Guardar DOCX
+async function saveDocx(doc: Document, outputPath: string): Promise<void> {
+  const buffer = await Packer.toBuffer(doc);
+  fs.writeFileSync(outputPath, buffer);
+}
+```
+
+---
+
+## 📊 XLSX Generation
+
+### Setup
+
+```bash
+npm install exceljs
+```
+
+### Pattern: Reporte con Datos y Formato
+
+```typescript
+import ExcelJS from 'exceljs';
+
+interface SpreadsheetData {
+  title: string;
+  headers: string[];
+  rows: (string | number | Date)[][];
+  summaryRow?: (string | number)[];
+}
+
+async function generateSpreadsheet(
+  data: SpreadsheetData,
+  outputPath: string
+): Promise<void> {
+  const workbook = new ExcelJS.Workbook();
+  workbook.creator = 'LMAgent';
+  workbook.created = new Date();
+
+  const sheet = workbook.addWorksheet(data.title, {
+    properties: { defaultRowHeight: 20 },
+  });
+
+  // Title row
+  sheet.mergeCells(1, 1, 1, data.headers.length);
+  const titleCell = sheet.getCell('A1');
+  titleCell.value = data.title;
+  titleCell.font = { size: 16, bold: true, color: { argb: 'FF1A1A2E' } };
+  titleCell.alignment = { horizontal: 'center', vertical: 'middle' };
+
+  // Header row
+  const headerRow = sheet.getRow(3);
+  data.headers.forEach((header, i) => {
+    const cell = headerRow.getCell(i + 1);
+    cell.value = header;
+    cell.font = { bold: true, color: { argb: 'FFFFFFFF' } };
+    cell.fill = {
+      type: 'pattern',
+      pattern: 'solid',
+      fgColor: { argb: 'FF1A1A2E' },
+    };
+    cell.alignment = { horizontal: 'center' };
+    cell.border = {
+      top: { style: 'thin' },
+      bottom: { style: 'thin' },
+      left: { style: 'thin' },
+      right: { style: 'thin' },
+    };
+  });
+
+  // Data rows
+  data.rows.forEach((row, rowIndex) => {
+    const excelRow = sheet.getRow(4 + rowIndex);
+    row.forEach((value, colIndex) => {
+      const cell = excelRow.getCell(colIndex + 1);
+      cell.value = value;
+
+      // Formato zebra
+      if (rowIndex % 2 === 1) {
+        cell.fill = {
+          type: 'pattern',
+          pattern: 'solid',
+          fgColor: { argb: 'FFF5F5F5' },
+        };
+      }
+
+      // Auto-formato por tipo
+      if (typeof value === 'number') {
+        cell.numFmt = '#,##0.00';
+        cell.alignment = { horizontal: 'right' };
+      } else if (value instanceof Date) {
+        cell.numFmt = 'dd/mm/yyyy';
+      }
+    });
+  });
+
+  // Summary row
+  if (data.summaryRow) {
+    const summRow = sheet.getRow(4 + data.rows.length + 1);
+    data.summaryRow.forEach((value, i) => {
+      const cell = summRow.getCell(i + 1);
+      cell.value = value;
+      cell.font = { bold: true, size: 12 };
+      if (typeof value === 'number') {
+        cell.numFmt = '#,##0.00';
+      }
+    });
+  }
+
+  // Auto-fit columns
+  sheet.columns.forEach(column => {
+    let maxLength = 10;
+    column.eachCell?.({ includeEmpty: false }, cell => {
+      const len = cell.value ? cell.value.toString().length : 10;
+      if (len > maxLength) maxLength = len;
+    });
+    column.width = Math.min(maxLength + 4, 40);
+  });
+
+  await workbook.xlsx.writeFile(outputPath);
+}
+```
+
+---
+
+## 📽️ PPTX Generation
+
+### Setup
+
+```bash
+npm install pptxgenjs
+```
+
+### Pattern: Presentación desde Datos
+
+```typescript
+import PptxGenJS from 'pptxgenjs';
+
+interface SlideData {
+  title: string;
+  subtitle?: string;
+  content?: string;
+  bullets?: string[];
+  table?: { headers: string[]; rows: string[][] };
+  image?: { path: string; w: number; h: number };
+  layout: 'title' | 'content' | 'two-column' | 'table' | 'image';
+}
+
+interface PresentationData {
+  title: string;
+  author: string;
+  company: string;
+  slides: SlideData[];
+  theme?: {
+    primary: string;    // hex e.g. '1A1A2E'
+    secondary: string;
+    accent: string;
+    background: string;
+  };
+}
+
+function generatePresentation(data: PresentationData): PptxGenJS {
+  const pptx = new PptxGenJS();
+  const theme = data.theme ?? {
+    primary: '1A1A2E',
+    secondary: '16213E',
+    accent: '0F3460',
+    background: 'FFFFFF',
+  };
+
+  pptx.author = data.author;
+  pptx.company = data.company;
+  pptx.title = data.title;
+  pptx.layout = 'LAYOUT_WIDE';
+
+  for (const slideData of data.slides) {
+    const slide = pptx.addSlide();
+
+    // Background
+    slide.background = { color: theme.background };
+
+    // Accent bar
+    slide.addShape('rect', {
+      x: 0, y: 0, w: 0.3, h: '100%',
+      fill: { color: theme.primary },
+    });
+
+    switch (slideData.layout) {
+      case 'title':
+        slide.background = { color: theme.primary };
+        slide.addText(slideData.title, {
+          x: 1, y: '30%', w: '80%', h: 1.5,
+          fontSize: 36, bold: true, color: 'FFFFFF',
+          align: 'center',
+        });
+        if (slideData.subtitle) {
+          slide.addText(slideData.subtitle, {
+            x: 1, y: '55%', w: '80%', h: 1,
+            fontSize: 18, color: 'CCCCCC',
+            align: 'center',
+          });
+        }
+        break;
+
+      case 'content':
+        slide.addText(slideData.title, {
+          x: 0.8, y: 0.3, w: '85%', h: 0.8,
+          fontSize: 24, bold: true, color: theme.primary,
+        });
+        if (slideData.bullets) {
+          slide.addText(
+            slideData.bullets.map(b => ({
+              text: b,
+              options: { bullet: true, fontSize: 16, color: '333333', breakLine: true },
+            })),
+            { x: 0.8, y: 1.5, w: '85%', h: 4 }
+          );
+        }
+        break;
+
+      case 'table':
+        slide.addText(slideData.title, {
+          x: 0.8, y: 0.3, w: '85%', h: 0.8,
+          fontSize: 24, bold: true, color: theme.primary,
+        });
+        if (slideData.table) {
+          const tableData = [
+            slideData.table.headers.map(h => ({
+              text: h,
+              options: { bold: true, color: 'FFFFFF', fill: { color: theme.primary } },
+            })),
+            ...slideData.table.rows,
+          ];
+          slide.addTable(tableData as PptxGenJS.TableRow[], {
+            x: 0.8, y: 1.5, w: '85%',
+            fontSize: 12,
+            border: { pt: 1, color: 'E0E0E0' },
+            colW: Array(slideData.table.headers.length).fill(
+              11 / slideData.table.headers.length
+            ),
+          });
+        }
+        break;
+
+      case 'image':
+        slide.addText(slideData.title, {
+          x: 0.8, y: 0.3, w: '85%', h: 0.8,
+          fontSize: 24, bold: true, color: theme.primary,
+        });
+        if (slideData.image) {
+          slide.addImage({
+            path: slideData.image.path,
+            x: 1.5, y: 1.5,
+            w: slideData.image.w,
+            h: slideData.image.h,
+          });
+        }
+        break;
+    }
+  }
+
+  return pptx;
+}
+
+// Guardar PPTX
+async function savePptx(pptx: PptxGenJS, outputPath: string): Promise<void> {
+  await pptx.writeFile({ fileName: outputPath });
+}
+```
+
+---
+
+## 🔧 Template Engine Pattern
+
+Para documentos complejos, separar datos de template:
+
+```typescript
+import Handlebars from 'handlebars';
+import * as fs from 'fs';
+
+// 1. Template HTML (para PDFs via Puppeteer)
+const invoiceTemplate = `
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body { font-family: 'Segoe UI', sans-serif; margin: 40px; color: #1a1a2e; }
+    .header { display: flex; justify-content: space-between; margin-bottom: 30px; }
+    .company { font-size: 24px; font-weight: bold; }
+    table { width: 100%; border-collapse: collapse; margin: 20px 0; }
+    th { background: #1a1a2e; color: white; padding: 10px; text-align: left; }
+    td { padding: 8px 10px; border-bottom: 1px solid #eee; }
+    tr:nth-child(even) { background: #f9f9f9; }
+    .total { font-size: 20px; font-weight: bold; text-align: right; margin-top: 20px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="company">{{company.name}}</div>
+    <div>Factura #{{invoice.number}}<br>{{invoice.date}}</div>
+  </div>
+  <table>
+    <tr><th>Descripción</th><th>Cant.</th><th>P.Unit.</th><th>Subtotal</th></tr>
+    {{#each items}}
+    <tr>
+      <td>{{description}}</td>
+      <td>{{quantity}}</td>
+      <td>{{formatCurrency unitPrice}}</td>
+      <td>{{formatCurrency (multiply quantity unitPrice)}}</td>
+    </tr>
+    {{/each}}
+  </table>
+  <div class="total">TOTAL: {{formatCurrency total}}</div>
+</body>
+</html>
+`;
+
+// 2. Registrar helpers
+Handlebars.registerHelper('formatCurrency', (n: number) =>
+  `$ ${n.toLocaleString('es-AR', { minimumFractionDigits: 2 })}`
+);
+Handlebars.registerHelper('multiply', (a: number, b: number) => a * b);
+
+// 3. Compilar y renderizar
+const template = Handlebars.compile(invoiceTemplate);
+const html = template(data);
+
+// 4. Generar PDF desde HTML
+await htmlToPdf(html, './invoice.pdf');
+```
+
+---
+
+## 🔗 Interacción con otros Skills
+
+| Skill | Relación |
+|-------|----------|
+| `technical-writer` | Writer redacta contenido en MD; Document Generator lo convierte a PDF/DOCX |
+| `data-engineer` | Data prepara los datos; Document Generator los formatea en reportes |
+| `browser-agent` | Browser puede capturar HTML que Document Generator convierte a PDF |
+| `backend-engineer` | Backend expone endpoint de generación; Document Generator implementa la lógica |
+
+---
+
+## 🛠️ Herramientas Preferidas
+
+| Herramienta | Cuándo Usarla |
+|-------------|---------------|
+| `run_command` | Ejecutar scripts de generación, instalar dependencias |
+| `write_to_file` | Crear templates HTML/Handlebars, scripts de generación |
+| `view_file` | Leer datos de entrada, templates existentes |
+| `browser_subagent` | Preview de PDFs generados |
+
+## 📋 Definition of Done
+
+### Template
+- [ ] Datos parametrizados (no hardcodeados)
+- [ ] Formato profesional (márgenes, fonts, colores)
+- [ ] Metadatos incluidos (title, author, date)
+
+### Output
+- [ ] Archivo generado correctamente (abrir sin errores)
+- [ ] Datos validados antes de generar
+- [ ] Encoding correcto (UTF-8, caracteres especiales)
+
+### Automatización
+- [ ] Script ejecutable desde CLI sin intervención
+- [ ] Paths configurados via env vars
+- [ ] Error handling para datos faltantes