pi-filler

Deterministic DOCX, PDF, PPTX, and XLSX tooling for Pi.

pi-filler covers document tasks that do not fit an ordinary Markdown workflow. It delegates conversion and PDF extraction to mature command-line tools while keeping DOCX, PPTX, and XLSX mutations narrow, transactional, and inspectable.

The project is experimental and pre-1.0. The README documents the current main branch; the npm badge shows the currently published version, which may not yet contain every feature described here.

Install

Install the published package:

pi install npm:pi-filler

Or install the current main branch for development and unreleased features:

pi install git:https://gitlab.com/Joao-O-Santos/pi-filler.git

External programs are required only for the operations listed under External tools. XLSX operations run locally through Node.js and do not require an office suite.

Tool and operation matrix

The extension exposes one filler tool:

format: docx | pdf | pptx | xlsx
action: read | search | write | patch
view: text | formatting | image | structure

format names the document or target format, not every input: DOCX and PPTX writes take Markdown at path, and XLSX writes take a workbook template at path plus CSV at source_csv. Choose a supported combination and supply only its relevant fields:

Format	Action	View	Required additional fields
DOCX	read	text or formatting	none
DOCX	read	image	output; optional first_page, last_page
DOCX	search	text or omitted	query; optional ignore_case
DOCX	write	omitted	Markdown path, output; optional reference_docx
DOCX	patch	omitted	output, patches; optional dry_run
PPTX	read	text or formatting	none
PPTX	read	image	output; optional first_page, last_page
PPTX	search	text or omitted	query; optional ignore_case
PPTX	write	omitted	Markdown path, output; optional reference_pptx
PPTX	patch	omitted	output, pptx_patches; optional dry_run
PDF	read	text	optional first_page, last_page
PDF	read	image	output; optional first_page, last_page
PDF	search	text or omitted	query; optional first_page, last_page, literal, ignore_case
XLSX	read	structure	none
XLSX	read	image	output; optional first_page, last_page select resulting workbook print pages
XLSX	write	omitted	template path, source_csv, sheet, A1 start_cell, output; optional column_map
XLSX	patch	omitted	sheet, A1 range, xlsx_patches, output

PDF write and patch, and XLSX search, are unsupported. Parameters irrelevant to the chosen operation fail explicitly instead of being ignored.

Paths resolve relative to Pi's current working directory; absolute paths and Pi-style paths prefixed with @ are also accepted. A write or patch output must differ from its input. For image reads, output is an existing directory or PNG prefix; the operation creates page images rather than one final PNG file.

first_page and last_page select 1-based inclusive pages. Both must be positive, and first_page cannot exceed last_page. Use start_cell like A2 and range like A2:D10; a range may also be one cell.

PDF search interprets query as a regular expression by default; set literal: true for literal text. It is case-sensitive unless ignore_case: true is set. XLSX writes skip the first CSV record by default and preserve fields as text by default. dry_run: true still requires output, but it does not create or replace it.

Example calls:

filler({
  format: "pdf",
  action: "search",
  path: "paper.pdf",
  query: "registered report",
  ignore_case: true
})

filler({
  format: "xlsx",
  action: "write",
  path: "template.xlsx",
  source_csv: "results.csv",
  sheet: "Results",
  start_cell: "A2",
  output: "completed.xlsx",
  dry_run: true
})

Results may be truncated. For a truncated PDF text read, use a page range; for PDF, DOCX, or PPTX search, narrow the query. PDF search can also use a page range. Dry runs still read and validate all local inputs.

PDF operations

• Text reads use layout-preserving extraction and optional page ranges.
• Search returns page-aware matches and supports 1-based inclusive page ranges, case-insensitive matching, and literal rather than regular-expression queries.
• Image reads render selected pages to numbered PNG files.
• A failed render preserves previous files for the requested output prefix.

DOCX operations

• Text reads and search convert DOCX through Pandoc.
• Image reads convert DOCX through LibreOffice and then render the resulting PDF pages.
• Writes convert a Markdown input into a validated DOCX, optionally using a reference DOCX for styles and layout.
• Formatting reads inspect page setup, margins, sections, line and page numbering, comments, inserted/deleted tracked-change markers, and common core metadata.
• Patches change first-section page setup, margins, line numbering, page numbering, and common core metadata.

DOCX page dimensions and margins use twips (twentieths of a point); 1 inch is 1,440 twips. Page setup, margins, line numbering, and page numbering patches apply to the first section only. Core-metadata patches apply to the document.

clearCoreMetadata clears common docProps/core.xml fields. It does not remove comment authors, revision authors, or every possible identity-bearing property and must not be described as anonymization.

Untouched ZIP package parts remain content-identical. Edited XML parts are parsed and serialized again, so their lexical formatting, prefixes, or element ordering may change.

XLSX operations and privacy

Spreadsheet cell values, CSV fields, formula contents, and comments are processed locally and are not returned to the model. When a deterministic XLSX write or patch does not require inspection, do not read CSV or cell contents into model context merely to perform it. Structural results may contain sheet names, ranges, dimensions, counts, merged-range addresses, hidden row and column ranges, changed package parts, and write status---not cell or CSV contents. Layout-range arrays are capped and report whether they were truncated; this metadata can reveal limited layout and occupancy information.

• read with view: "structure" reports workbook and worksheet shape.
• read with view: "image" renders workbook print pages through LibreOffice to numbered PNG files; it does not select a sheet. first_page and last_page select resulting print pages.
• write fills an existing workbook template from CSV.
• patch changes formatting or layout while preserving cell contents.

CSV writes skip the first record by default (has_header: true) and preserve fields as text by default (value_mode: "text"). Automatic mode recognizes only empty values, numbers, and booleans; it does not infer dates or formulas. column_map optionally maps either all 1-based CSV ordinals or all exact CSV headers to absolute XLSX column letters, such as { "1": "A", "2": "C" }. Header mappings require unique CSV headers; destinations must be unique. The entire write fails if its mapped destination cells intersect an existing formula or merged range.

XLSX patches support bold, italic, font size, six-digit RGB fills, horizontal and vertical alignment, wrapping, Excel number-format codes, uniform borders, column width, and row height. Output is validated and atomically replaced only after successful processing.

XLSX support does not provide cell-content reads or search, formula calculation or generation, spreadsheet scripting, or manipulation of charts, pivots, macros, comments, named ranges, tables, data validation, conditional formatting, or external data.

PPTX operations

• Text reads and search convert PPTX through Pandoc to GFM Markdown.
• Writes convert GFM Markdown into a validated PPTX; an optional reference PPTX supplies Pandoc presentation styles.
• Formatting reads report slide dimensions, slide count, and common core metadata.
• Patches change slide dimensions, common core metadata, and targeted text in slide text paragraphs. Text replacements may target one 1-based slide or all slides. They can span formatted text runs, with replacement text inheriting the first run's formatting.
• PPTX-to-Markdown extraction is semantic and lossy: it is not a reversible representation of positions, animations, themes, or all presentation objects.

Slide dimensions use EMUs (English Metric Units); 914,400 EMUs equal one inch. PPTX image reads convert slides through LibreOffice to PDF and render numbered PNG files; first_page and last_page select slides.

Output and mutation behavior

DOCX, PPTX, and XLSX writes and patches use temporary sibling files, validate the result, and rename it into place only after success. Source files are not modified. PDF and office image rendering similarly protects prior output until the new render succeeds.

dry_run validates the requested operation and inputs without creating or replacing output; its required output path is still validated.

External tools

Required for the corresponding operations:

• pandoc for DOCX/PPTX text conversion, search, and generation;
• libreoffice for DOCX, PPTX, and XLSX image rendering;
• pdftotext for PDF text extraction;
• pdftocairo for PDF, DOCX, PPTX, and XLSX page rendering; and
• pdfgrep for page-aware PDF search.

A missing executable produces an explicit error naming the unavailable program.

Development and release

npm install
make verify
make site

make verify runs typechecking, lint and formatting checks, deterministic tests, project-wide line/function coverage checks, and npm pack --dry-run. make site regenerates the tracked static site after documentation changes.

Dependencies and CI actions follow current upstream releases rather than being pinned. GitLab is canonical and the only release authority. GitHub may mirror the repository, verify it, and publish GitHub Pages. A vX.Y.Z GitLab tag must match package.json; after verification it publishes to npm with provenance.

License

MIT