Round-Trip Document Serialization in OfficeCLI: Using the Dump and Batch Feature

OfficeCLI's dump and batch commands enable lossless round-trip document serialization by extracting OOXML documents into replayable command streams and reconstructing them atomically.

The iOfficeAI/OfficeCLI repository provides a powerful round-trip document serialization system that converts Word, PowerPoint, and Excel files into flat, grep-friendly command scripts. These scripts can be version-controlled, inspected, and replayed to recreate identical documents. This guide explains how the dump and batch pipeline works, with references to the actual implementation in the source code.

How the Dump Command Extracts Documents

The dump command transforms a document into a series of JSON-encoded batch commands. This process starts in ResidentServer.cs around lines 1975-1979, where the server validates that --format batch is specified—currently the only supported output format.

When executed, dump walks through every OOXML part in the source file and emits declarative set/add/remove commands that fully describe the document's structure. The WordHandler.cs file (lines 504-527) contains extensive implementation details for how complex elements are captured:

• OLE objects, pictures, and ActiveX controls — serialized with special carriers that preserve binary data
• Styles, borders, and numbering — emitted as raw-set or raw-replace commands
• Custom XML and footnotes — captured with their full semantic context

Each output line is a self-contained JSON batch item. The format is intentionally flat and grep-friendly, making it suitable for diffing, searching, and version control.

How the Batch Command Reconstructs Documents

The batch command serves as the inverse operation, reading dump scripts and rebuilding documents. The entry point in ResidentServer.cs (lines 1152-1156) initializes the batch engine, which accepts input from either a file path or stdin via --input -.

Key characteristics of the batch engine:

• Deferred writes — All changes accumulate in memory until the final commit
• Atomic rollback — If any command fails, the entire batch is discarded and original disk state restored (see lines 1312-1315 in ResidentServer.cs)
• Handler-based replay — The same WordBatchEmitter classes that produced the dump interpret each command and recreate exact OOXML parts

This architecture guarantees that a valid dump script will always produce a bit-for-bit identical reconstruction when executed against a fresh document.

The Complete Round-Trip Pipeline

Combining dump and batch creates a declarative, reversible workflow:

# Step 1: Extract the document to a batch script

officecli dump source.docx --format batch > source.dump.txt

# Step 2: Replay the script to rebuild the document

officecli batch --input source.dump.txt rebuilt.docx

The pipeline supports streaming without intermediate files. In ResidentServer.cs (lines 1984-1989), the implementation ensures dump writes to stdout and batch reads from stdin, enabling this pattern:

officecli dump source.docx --format batch 2>&1 | \
  officecli batch --input - rebuilt.docx

Verifying Lossless Serialization

A proper round-trip should reach fixed-point: dumping the rebuilt document produces identical output to the original dump. This property confirms that the serialization captured all document state without loss.

Supported Document Formats

The dump command currently handles three Office formats. The validation in ResidentServer.cs (lines 2027-2029) throws a CliException for unsupported extensions:

Extension	Description
.docx	Word documents (full feature support)
.pptx	PowerPoint presentations
.xlsx	Excel workbooks

Practical Usage Examples

Example 1: Basic Word Document Round-Trip

officecli dump resume.docx --format batch > resume.dump
officecli batch --input resume.dump rebuilt-resume.docx

Example 2: Pipe-Based Reconstruction (No Temp Files)

officecli dump deck.pptx --format batch 2>&1 | \
  officecli batch --input - rebuilt-deck.pptx

Example 3: Inspecting Document Structure

officecli dump budget.xlsx --format batch | grep 'set /sheet[1]/cell'

All commands accept --json for machine-readable responses, though the dump-to-batch flow works natively with plain text.

Key Implementation Files

Understanding these source files clarifies how the round-trip works:

File	Role
ResidentServer.cs	Command dispatcher; validates dump format, streams output, orchestrates batch execution with rollback
WordHandler.cs	Emits detailed OOXML commands; contains "dump→batch" annotations explaining serialization decisions
SchemaHelpFlatRenderer.cs	Generates flat schema output used by both help and dump --format batch
CommandBuilder.Dump.cs	Command-line parser for dump; enforces supported format constraints
Core/Plugins/DumpReaderInvoker.cs	Plugin hook converting dump files into batch items for execution

Summary

• dump --format batch extracts OOXML documents into JSON-encoded command streams that are flat, grep-friendly, and version-controllable
• batch --input replays these commands atomically, with automatic rollback on failure
• Streaming support allows pipe-based workflows without intermediate files (2>&1 | --input -)
• Fixed-point verification confirms lossless serialization by re-dumping the rebuilt document
• The implementation spans ResidentServer.cs for orchestration and WordHandler.cs for format-specific ooXML handling

Frequently Asked Questions

What makes the batch format "grep-friendly"?

The dump output uses a flat structure with one JSON object per line and consistent path notation like set /document/body/p[1]. This design lets standard Unix tools filter and search document content without parsing complex XML hierarchies. The SchemaHelpFlatRenderer.cs file generates this representation specifically for human and tool consumption.

Can I edit a dump file manually and still rebuild successfully?

Yes, provided you maintain valid JSON syntax and valid command paths. The batch engine validates each command against the document schema. Invalid commands trigger the rollback mechanism in ResidentServer.cs (lines 1312-1315), preventing partial or corrupted rebuilds.

Does the round-trip preserve all document metadata?

According to the WordHandler.cs implementation (lines 504-527), the dump captures OLE objects, embedded images, ActiveX controls, styles, borders, custom XML, footnotes, and numbering. The "dump→batch round‑trip" comments throughout the file indicate comprehensive coverage, though password protection and certain legacy formats may require verification.

How does atomic rollback work in practice?

The batch engine accumulates all changes in memory until the final commit point. If any command throws an exception, the engine discards the in-memory document and leaves any existing disk file untouched. This design, visible in ResidentServer.cs lines 1312-1315, ensures that failed batches never produce partially written files.

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