How OfficeCLI Round-Trip Dump Serializes Documents into Replayable Batch JSON

OfficeCLI's dump command exports Office documents as batch JSON containing low-level edit operations that can be piped back through the batch command to reconstruct the original file byte-for-byte.

The round-trip dump feature in iOfficeAI/OfficeCLI provides a deterministic, lossless serialization mechanism for Word, PowerPoint, and Excel documents. By traversing a document's OpenXML structure and emitting a linear sequence of operations, OfficeCLI creates a replayable JSON payload that serves as both an archive and a transport format for document manipulation.

Understanding the Batch JSON Format

The batch JSON schema defines a list of edit operations: add, set, replace, and delete. When dumping a document, OfficeCLI generates raw-set or replace operations that capture:

• Verbatim XML fragments (e.g., <w:tbl> table elements, paragraph structures)
• Data-URI encoded binary blobs (OLE objects, embedded images, fonts, ActiveX controls)

This granular approach ensures every component of the source file is preserved. The WordHandler explicitly identifies these elements as "dump→batch round-trip carriers" for complex document parts.

Three-Stage Serialization Process

Stage 1: Command Parsing and Validation

The dump sub-command is processed in src/officecli/ResidentServer.cs. The command validates that --format is set to batch — any other format triggers an error:

// ResidentServer.cs lines 1975-1979
if (format != "batch")
{
    throw new ArgumentException("Dump format must be 'batch'");
}

This strict enforcement ensures output compatibility with the batch command's input requirements.

Stage 2: Document Traversal and Operation Generation

The WordHandler (and equivalent PowerPoint/Excel handlers) walks each OpenXML part in the source document. For every structural element, it emits operations containing either raw XML or base64-encoded binary data.

In src/officecli/Handlers/WordHandler.cs, this logic handles:

• OLE objects (lines 504-527): Embedded spreadsheets, equations, and legacy content
• ActiveX controls (lines 655-657): Form controls and scripted elements
• Charts, fonts, and media: All binary relationships in the OpenXML package

The handler preserves exact document state by capturing complete XML subtrees and binary attachments as data URIs.

Stage 3: JSON Emission and Output

The generated operations are serialized to JSON with a wrapper containing:

• operations: The linear operation list
• success: Boolean completion status
• warnings: Any non-fatal issues during traversal

The output structure in ResidentServer.cs (lines 846-852) ensures self-contained, parseable results suitable for piping or file storage.

Round-Trip Execution Examples

Command-Line Usage

# Serialize DOCX to batch JSON

officecli dump report.docx --format batch > report.dump.json

# Replay to recreate original document

cat report.dump.json | officecli batch --input - > recreated.docx

Node SDK Programmatic Access

const { dump } = require('@officecli/sdk');

(async () => {
  // Generate batch JSON from document
  const batch = await dump('report.docx', { format: 'batch' });
  
  // `batch` is a JSON string suitable for storage or transmission
  fs.writeFileSync('report.dump.json', batch);
  
  // Later: replay through batch command or SDK
  const recreated = await batchFromJSON(batch, 'recreated.docx');
})();

Key Implementation Files

File	Purpose
src/officecli/ResidentServer.cs	Command parsing, format validation, JSON streaming
src/officecli/Handlers/WordHandler.cs	Core traversal logic, operation generation for Word documents
src/officecli/Help/SchemaHelpFlatRenderer.cs	Schema documentation and validation definitions
sdk/node/index.d.ts	TypeScript definitions for SDK dump method

Summary

• Round-trip dump serializes Office documents as batch JSON through three stages: command validation, document traversal, and JSON emission.
• The WordHandler and related handlers capture verbatim XML and data-URI binary blobs to ensure lossless serialization.
• Output conforms to the batch command schema, enabling immediate replay via pipe or SDK.
• Implementation spans ResidentServer.cs for orchestration and handler classes for format-specific traversal.

Frequently Asked Questions

What makes the dump format "replayable"?

The batch JSON uses the same schema consumed by the batch command. Each raw-set or replace operation in the dump corresponds to a valid batch instruction, so piping the output directly into officecli batch --input - reconstructs the original document without transformation.

Does round-trip dump preserve binary content like images and OLE objects?

Yes. The WordHandler specifically encodes binary elements — images, fonts, OLE objects, and ActiveX controls — as data URIs within the JSON. The source code comments (lines 504-527, 655-657) identify these as critical "round-trip carriers" that maintain document fidelity.

Can I use round-trip dump without the command-line interface?

Yes. The Node SDK exposes a dump method with identical behavior. As defined in sdk/node/index.d.ts, this method accepts a file path and format option, returning the same JSON structure available through the CLI.

What happens if I specify a format other than "batch"?

The ResidentServer.cs parser (lines 1975-1979) rejects non-batch formats with an ArgumentException. This design choice enforces output compatibility with the replay pipeline and prevents accidental generation of unsupported serialization formats.

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