How the OfficeCLI Plugin System Extends Support for .doc, .hwpx, and PDF Export

The OfficeCLI plugin system extends format support through three distinct plugin types—dump‑reader for legacy formats like .doc, format‑handler for regional standards like .hwpx, and exporter for PDF conversion—allowing the core binary to remain lean while delegating non-native document operations to specialized external processes.

The OfficeCLI plugin system powers the iOfficeAI/OfficeCLI repository’s ability to handle document formats beyond the native OOXML trio (.docx, .xlsx, .pptx). By implementing the OfficeCli Plugin Protocol (v1), the architecture delegates format-specific processing to external plugins, enabling the CLI to open legacy Word files, edit Hangul documents, and export to PDF without recompiling the core binary.

The Three Plugin Architecture Types

The OfficeCLI plugin system defines three distinct plugin kinds, each designed for a specific conversion workflow.

Dump-Reader Plugins for Legacy Formats (.doc)

Dump‑reader plugins convert foreign source files into OfficeCLI batch commands that recreate the document in a native OOXML format. When opening a .doc file, OfficeCLI spawns the registered dump‑reader plugin, which streams JSONL batch items (e.g., {"command":"add","parent":"/body","type":"paragraph",...}) to generate a sibling .docx file cached for subsequent operations.

According to plugins/plugin-protocol.md (lines 30–45), the plugin declares its source extension (.doc) and target native format (docx), allowing the system to invoke the correct translator automatically.

Format-Handler Plugins for Regional Formats (.hwpx)

Format‑handler plugins provide first-class support for non-native formats by owning the document for the entire session. Unlike dump-readers, these plugins implement a full command vocabulary (add, set, get, etc.) over stdin/stdout, enabling direct editing of formats like .hwpx (Hangul Word Processor).

The plugin reports its capabilities via the open handshake described in plugins/plugin-protocol.md (lines 95–110), allowing the CLI to autocomplete properties specific to the Hangul format model.

Exporter Plugins for PDF Output

Exporter plugins handle one-way conversion from native OOXML formats to foreign output formats like PDF. The exporter reads the native file (.docx, .xlsx, or .pptx) read-only and writes the target .pdf without creating intermediate files.

This workflow is defined in plugins/plugin-protocol.md (lines 67–88), ensuring that PDF generation occurs as a pure one-shot conversion operation.

Plugin Discovery and Resolution

When OfficeCLI requires a plugin for a specific (kind, ext) pair, it follows a fixed resolution order defined in plugins/plugin-protocol.md (lines 34–47):

1. Environment variable lookup
2. User-plugins directory
3. Bundled plugins directory
4. System PATH

The first match wins. The PluginRegistry.cs file (lines 30–35) implements this scanning logic, handling manifest parsing and protocol version compatibility, while DocumentHandlerFactory.cs (lines 60–63) acts as the central dispatcher, choosing between native handlers, dump-readers, or format-handlers based on the file extension.

Working with Plugins: Code Examples

Adding .doc Support (Dump-Reader)

# Install the official .doc → .docx dump-reader plugin

officecli plugins install officecli-doc

# Open a legacy Word file; OfficeCLI automatically invokes the plugin,

# produces a sibling .docx, and works with it as native

officecli view report.doc

What happens: DocumentHandlerFactory detects the .doc extension and locates the dump-reader plugin. The plugin executes <plugin> dump report.doc, streams batch commands, and OfficeCLI replays them into report.docx, caching the result.

Adding .hwpx Support (Format-Handler)

# Install the Hangul Word Processor format-handler

officecli plugins install officecli-hwpx

# Edit a Hangul document directly using the plugin's command vocabulary

officecli get manuscript.hwpx /body/p[1] --json
officecli set manuscript.hwpx /body/p[1] --prop text="새로운 텍스트"
officecli save manuscript.hwpx

What happens: The format-handler launches with open <file> and remains alive for the session. All subsequent commands travel as JSON envelopes over stdin/stdout, with FormatHandlerSession.cs managing the long-lived process and request/response protocol.

Exporting to PDF (Exporter)

# Install the PDF exporter plugin

officecli plugins install officecli-pdf

# Export native OOXML files to PDF

officecli view deck.pptx pdf --out deck.pdf
officecli view budget.xlsx pdf --out budget.pdf

What happens: OfficeCLI resolves the exporter plugin for the .pdf extension, spawns <plugin> export <source> --out <target>, and performs the conversion without modifying the source OOXML file.

Core Implementation Files

The OfficeCLI plugin system relies on these key source files:

• plugins/plugin-protocol.md – Canonical definition of the three plugin kinds, manifest schema, discovery rules, and IPC details.
• src/officecli/Core/Plugins/PluginRegistry.cs – Scans the filesystem, parses plugin manifests, caches results, and enforces protocol version compatibility.
• src/officecli/Handlers/DocumentHandlerFactory.cs – Central dispatcher that selects native handlers, dump-reader plugins, or format-handler plugins based on file extension.
• src/officecli/Core/Plugins/FormatHandlerSession.cs – Manages long-lived format-handler processes, handling the JSON request/response protocol over stdin/stdout.
• src/officecli/CommandBuilder.Plugins.cs – CLI entry point (officecli plugins …) for installing, listing, and validating plugins.

Summary

• Three plugin kinds extend OfficeCLI: dump‑reader for legacy import (.doc), format‑handler for regional editing (.hwpx), and exporter for PDF conversion.
• Automatic resolution follows a fixed search order (env-var → user → bundled → PATH) implemented in PluginRegistry.cs.
• Zero core bloat – plugins run as external processes, keeping the main binary small while supporting diverse formats.
• Protocol-based communication uses JSON over stdin/stdout, with specific workflows defined in plugin-protocol.md.

Frequently Asked Questions

How does OfficeCLI open .doc files without native support?

OfficeCLI uses a dump‑reader plugin that converts the legacy .doc binary into a stream of batch commands. These commands recreate the document as a native .docx file, which OfficeCLI then caches and treats as the working document. The process is transparent to the user and occurs automatically when the plugin is installed.

What is the difference between a dump-reader and a format-handler plugin?

A dump‑reader performs one-time conversion from a foreign format to OOXML, after which the plugin exits and OfficeCLI works with the generated native file. A format‑handler remains active for the entire session, maintaining its own document model and exposing a custom command vocabulary for direct editing of the non-native format (such as .hwpx).

Where does OfficeCLI search for installed plugins?

The system searches in a specific priority order: environment variables first, then the user-plugins directory, followed by bundled plugins, and finally the system PATH. This discovery mechanism is implemented in PluginRegistry.cs and documented in plugin-protocol.md (lines 34–47).

Can I create a custom exporter for formats other than PDF?

Yes. The exporter plugin kind is designed for any one-way conversion from native OOXML to a foreign output format. By implementing the exporter protocol defined in plugin-protocol.md (lines 67–88), developers can add support for formats like ODT, RTF, or XPS without modifying the OfficeCLI core binary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}