node-pptx-templater 1.0.0

package/src/cli/commands/extract.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview `extract` CLI command — extracts XML parts from a PPTX.
+ */
+import chalk from 'chalk';
+import { resolve } from 'path';
+import { writeFileSync } from 'fs';
+import { PPTXTemplater } from '../../index.js';
+
+export async function extractCommand(filePath, opts) {
+  try {
+    const ppt = await PPTXTemplater.load(resolve(filePath));
+
+    if (opts.slide) {
+      const slideNum = parseInt(opts.slide, 10);
+      // Access internal zip via the engine's buffer
+      const buffer = await ppt.toBuffer();
+      const JSZip = (await import('jszip')).default;
+      const zip = await JSZip.loadAsync(buffer);
+      const slideFile = zip.file(`ppt/slides/slide${slideNum}.xml`);
+
+      if (!slideFile) {
+        console.error(chalk.red(`Slide ${slideNum} not found`));
+        process.exit(1);
+      }
+
+      const xml = await slideFile.async('text');
+
+      if (opts.out) {
+        writeFileSync(resolve(opts.out), xml, 'utf-8');
+        console.log(chalk.green(`✓ Extracted slide ${slideNum} to ${opts.out}`));
+      } else {
+        console.log(xml);
+      }
+    } else {
+      console.log(chalk.yellow('Specify --slide <number> to extract'));
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Extract failed: ${err.message}`));
+    process.exit(1);
+  }
+}

package/src/cli/commands/inspect.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview `inspect` CLI command — detailed PPTX structure inspection.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { resolve } from 'path';
+import { PPTXTemplater } from '../../index.js';
+
+export async function inspectCommand(filePath, opts) {
+  const showAll = opts.all;
+  const spinner = ora(`Inspecting: ${filePath}`).start();
+
+  try {
+    const ppt = await PPTXTemplater.load(resolve(filePath));
+    const info = ppt.getInfo();
+    spinner.stop();
+
+    console.log(chalk.bold.cyan('\n═══ PPTX Inspection Report ═══\n'));
+    console.log(chalk.bold('General:'));
+    console.log(`  Title:    ${info.title || chalk.dim('(none)')}`);
+    console.log(`  Author:   ${info.author || chalk.dim('(none)')}`);
+    console.log(`  Created:  ${info.created || chalk.dim('(unknown)')}`);
+    console.log(`  Slides:   ${chalk.cyan(info.slideCount)}`);
+    console.log(`  Media:    ${chalk.cyan(info.mediaCount)} files`);
+
+    if (opts.slides || showAll) {
+      console.log(chalk.bold('\nSlides:'));
+      for (const slide of info.slides) {
+        const tags = slide.tags.length > 0 ? chalk.dim(` [${slide.tags.join(', ')}]`) : '';
+        console.log(`  ${chalk.cyan(slide.index.toString().padStart(2))}. ${slide.zipPath}${tags}`);
+      }
+    }
+
+    console.log('');
+  } catch (err) {
+    spinner.fail(chalk.red(`Inspect failed: ${err.message}`));
+    process.exit(1);
+  }
+}

package/src/cli/commands/validate.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview `validate` CLI command.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { resolve } from 'path';
+import { PPTXTemplater } from '../../index.js';
+
+export async function validateCommand(filePath, opts) {
+  const spinner = ora(`Validating: ${filePath}`).start();
+  try {
+    const ppt = await PPTXTemplater.load(resolve(filePath));
+    const result = ppt.validate();
+    spinner.stop();
+
+    if (result.valid && result.warnings.length === 0) {
+      console.log(chalk.green(`\n✓ Valid PPTX (${ppt.slideCount} slides)\n`));
+    } else {
+      if (result.errors.length > 0) {
+        console.log(chalk.red(`\n✗ Validation errors (${result.errors.length}):\n`));
+        result.errors.forEach(e => console.log(chalk.red(`  • ${e}`)));
+      }
+      if (result.warnings.length > 0) {
+        console.log(chalk.yellow(`\n⚠ Warnings (${result.warnings.length}):\n`));
+        result.warnings.forEach(w => console.log(chalk.yellow(`  • ${w}`)));
+      }
+    }
+
+    if (!result.valid || (opts.strict && result.warnings.length > 0)) {
+      process.exit(1);
+    }
+  } catch (err) {
+    spinner.fail(chalk.red(`Validation failed: ${err.message}`));
+    process.exit(1);
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview CLI entry point for node-pptx-templater.
+ *
+ * Provides command-line access to the template engine's core features.
+ *
+ * Usage:
+ *   node-pptx-templater build template.pptx output.pptx [options]
+ *   node-pptx-templater validate template.pptx
+ *   node-pptx-templater inspect template.pptx
+ *   node-pptx-templater extract template.pptx --slide 1 --out ./slide1.xml
+ *   node-pptx-templater debug template.pptx
+ *
+ * Install globally:
+ *   npm install -g node-pptx-templater
+ *
+ * Then run:
+ *   node-pptx-templater --help
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { PPTXTemplater } from '../index.js';
+import { buildCommand } from './commands/build.js';
+import { validateCommand } from './commands/validate.js';
+import { inspectCommand } from './commands/inspect.js';
+import { extractCommand } from './commands/extract.js';
+import { debugCommand } from './commands/debug.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read version from package.json
+const pkg = JSON.parse(
+  readFileSync(resolve(__dirname, '../../package.json'), 'utf-8')
+);
+
+/**
+ * CLI banner displayed on startup.
+ */
+function printBanner() {
+  console.log(chalk.bold.cyan(`
+╔═══════════════════════════════════════════════╗
+║  node-pptx-templater v${pkg.version.padEnd(17)}║
+║  Low-level OpenXML PowerPoint template engine ║
+╚═══════════════════════════════════════════════╝
+`));
+}
+
+const program = new Command();
+
+program
+  .name('node-pptx-templater')
+  .description('Low-level PowerPoint OpenXML template engine for Node.js')
+  .version(pkg.version, '-v, --version', 'Display version number')
+  .addHelpText('before', chalk.bold.cyan('\nnode-pptx-templater — PowerPoint XML manipulation engine\n'));
+
+// ─── build command ─────────────────────────────────────────────────────────
+program
+  .command('build <template> <output>')
+  .description('Build a PPTX from a template with data injected from a JSON file')
+  .option('-d, --data <file>', 'JSON file with template data (text replacements, etc.)')
+  .option('-s, --slide <numbers>', 'Comma-separated slide numbers to include (e.g., 1,3,5)')
+  .option('--no-banner', 'Suppress the banner')
+  .action(async (template, output, opts) => {
+    if (!opts.noBanner) printBanner();
+    await buildCommand(template, output, opts);
+  });
+
+// ─── validate command ───────────────────────────────────────────────────────
+program
+  .command('validate <file>')
+  .description('Validate the structure of a PPTX file')
+  .option('--strict', 'Exit with error code on warnings too')
+  .action(async (file, opts) => {
+    printBanner();
+    await validateCommand(file, opts);
+  });
+
+// ─── inspect command ────────────────────────────────────────────────────────
+program
+  .command('inspect <file>')
+  .description('Inspect the internal structure of a PPTX file')
+  .option('--slides', 'Show slide details')
+  .option('--charts', 'Show chart details')
+  .option('--tables', 'Show table details')
+  .option('--media', 'Show embedded media files')
+  .option('--rels', 'Show relationship tree')
+  .option('--all', 'Show everything')
+  .action(async (file, opts) => {
+    printBanner();
+    await inspectCommand(file, opts);
+  });
+
+// ─── extract command ────────────────────────────────────────────────────────
+program
+  .command('extract <file>')
+  .description('Extract specific parts from a PPTX file')
+  .option('-s, --slide <number>', 'Slide number to extract XML from')
+  .option('-o, --out <path>', 'Output file path (default: stdout)')
+  .option('--chart <name>', 'Extract chart XML by name')
+  .option('--rels', 'Extract relationship files')
+  .action(async (file, opts) => {
+    await extractCommand(file, opts);
+  });
+
+// ─── debug command ──────────────────────────────────────────────────────────
+program
+  .command('debug <file>')
+  .description('Debug a potentially corrupted PPTX structure')
+  .option('--fix', 'Attempt automatic repairs')
+  .option('-o, --out <path>', 'Output repaired file path')
+  .action(async (file, opts) => {
+    printBanner();
+    await debugCommand(file, opts);
+  });
+
+// ─── Global error handling ──────────────────────────────────────────────────
+program.exitOverride();
+
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+    process.exit(0);
+  }
+  console.error(chalk.red(`\n✗ Error: ${err.message}\n`));
+  process.exit(1);
+}

package/src/core/OutputWriter.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview OutputWriter - Handles PPTX serialization and output.
+ *
+ * Responsibilities:
+ *  1. Flush all pending changes from all managers into the ZipManager
+ *  2. Ensure [Content_Types].xml is up to date
+ *  3. Generate the final ZIP archive
+ *  4. Write to file, buffer, or stream
+ */
+
+import fsExtra from 'fs-extra';
+const { writeFile, ensureDir } = fsExtra;
+import path from 'path';
+import { XMLParser } from '../parsers/XMLParser.js';
+import { createLogger } from '../utils/logger.js';
+import { PPTXError } from '../utils/errors.js';
+import { Readable } from 'stream';
+
+const logger = createLogger('OutputWriter');
+
+/**
+ * @class OutputWriter
+ * @description Serializes the modified PPTX to various output formats.
+ */
+export class OutputWriter {
+  /** @private @type {ZipManager} */
+  #zipManager;
+  /** @private @type {ContentTypesManager} */
+  #contentTypesManager;
+
+  /**
+   * @param {ZipManager} zipManager
+   * @param {ContentTypesManager} contentTypesManager
+   */
+  constructor(zipManager, contentTypesManager) {
+    this.#zipManager = zipManager;
+    this.#contentTypesManager = contentTypesManager;
+  }
+
+  /**
+   * Writes the final PPTX to a file on disk.
+   * Creates parent directories if needed.
+   *
+   * @param {string} filePath - Output file path.
+   * @param {SlideManager} slideManager
+   * @param {ZipManager} zipManager
+   * @returns {Promise<void>}
+   */
+  async saveToFile(filePath, slideManager, zipManager) {
+    try {
+      const buffer = await this.toBuffer(slideManager, zipManager);
+      const dir = path.dirname(filePath);
+      await ensureDir(dir);
+      await writeFile(filePath, buffer);
+      logger.info(`Saved to ${filePath} (${(buffer.length / 1024).toFixed(1)} KB)`);
+    } catch (err) {
+      if (err instanceof PPTXError) throw err;
+      throw new PPTXError(`Failed to save file to ${filePath}: ${err.message}`, err);
+    }
+  }
+
+  /**
+   * Returns the PPTX as a Node.js Buffer.
+   *
+   * @param {SlideManager} slideManager
+   * @param {ZipManager} zipManager
+   * @returns {Promise<Buffer>}
+   */
+  async toBuffer(slideManager, zipManager) {
+    // Ensure all slides are flushed to the ZIP
+    await this.#flushAllSlides(slideManager, zipManager);
+
+    // Flush Content Types safely
+    this.#contentTypesManager.flush(zipManager);
+
+    // Wait for any queued asynchronous writes (like content types, media hashing)
+    await zipManager.waitForPendingWrites();
+
+    const buffer = await zipManager.toBuffer();
+    logger.debug(`Generated buffer: ${(buffer.length / 1024).toFixed(1)} KB`);
+    return buffer;
+  }
+
+  /**
+   * Returns the PPTX as a readable Node.js stream.
+   *
+   * @param {SlideManager} slideManager
+   * @param {ZipManager} zipManager
+   * @returns {Promise<Readable>}
+   */
+  async toStream(slideManager, zipManager) {
+    await this.#flushAllSlides(slideManager, zipManager);
+
+    // Flush Content Types safely
+    this.#contentTypesManager.flush(zipManager);
+
+    await zipManager.waitForPendingWrites();
+    const nodeStream = await zipManager.toStream();
+    return nodeStream;
+  }
+
+  /**
+   * Ensures all dirty slide XML is committed to the ZipManager.
+   * This is called before any output operation.
+   *
+   * @private
+   * @param {SlideManager} slideManager
+   * @param {ZipManager} zipManager
+   * @returns {Promise<void>}
+   */
+  async #flushAllSlides(slideManager, zipManager) {
+    // SlideManager already writes to zipManager via setSlideXml,
+    // so this is mostly a no-op with a validation step.
+    const info = slideManager.getAllSlideInfo();
+
+    for (const slide of info) {
+      if (!zipManager.hasFile(slide.zipPath)) {
+        logger.warn(`Slide file missing in ZIP: ${slide.zipPath}`);
+      }
+    }
+
+    // Update the slide count and titles in docProps/app.xml to prevent repair mode issues
+    if (zipManager.hasFile('docProps/app.xml')) {
+      zipManager.addPendingPromise(
+        zipManager.rawZip.file('docProps/app.xml').async('text').then(content => {
+          const parser = new XMLParser();
+          const appObj = parser.parse(content, 'app.xml');
+          const properties = appObj.Properties;
+
+          if (properties) {
+            // 1. Update Slides count
+            properties.Slides = info.length;
+
+            // 2. Find old slide titles count and update HeadingPairs
+            let oldSlideTitlesCount = 0;
+            const variants = properties.HeadingPairs?.['vt:vector']?.['vt:variant'];
+            if (Array.isArray(variants)) {
+              for (let i = 0; i < variants.length; i++) {
+                if (variants[i]['vt:lpstr'] === 'Slide Titles') {
+                  const countVar = variants[i + 1];
+                  if (countVar) {
+                    oldSlideTitlesCount = parseInt(countVar['vt:i4'], 10) || 0;
+                    countVar['vt:i4'] = info.length;
+                  }
+                  break;
+                }
+              }
+            }
+
+            // 3. Update TitlesOfParts
+            const titlesVector = properties.TitlesOfParts?.['vt:vector'];
+            if (titlesVector) {
+              let lpstrs = titlesVector['vt:lpstr'];
+              if (lpstrs) {
+                if (!Array.isArray(lpstrs)) lpstrs = [lpstrs];
+
+                // Remove the old slide titles (which are at the end)
+                if (oldSlideTitlesCount > 0 && lpstrs.length >= oldSlideTitlesCount) {
+                  lpstrs = lpstrs.slice(0, lpstrs.length - oldSlideTitlesCount);
+                }
+
+                // Append new slide titles
+                const newSlideTitles = info.map(slide => slide.title || `Slide ${slide.index}`);
+                lpstrs.push(...newSlideTitles);
+
+                titlesVector['vt:lpstr'] = lpstrs;
+                titlesVector['@_size'] = String(lpstrs.length);
+              }
+            }
+
+            const declaration = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
+            const updatedXml = parser.build(appObj, declaration);
+            zipManager.writeFile('docProps/app.xml', updatedXml);
+          }
+        })
+      );
+    }
+
+    logger.debug(`Flushed ${info.length} slide(s) to ZIP`);
+  }
+}