pi-filler 0.0.0 → 0.2.0

package/README.md

@@ -1,82 +1,235 @@
 # pi-filler
 
-<p align="center"><img src="logo.png" alt="pi-filler logo" width="220"></p>
+![pi-filler logo](logo.png)
 
-Deterministic DOCX and PDF tooling for Pi.
+[![pipeline
+status](https://gitlab.com/Joao-O-Santos/pi-filler/badges/main/pipeline.svg)](https://gitlab.com/Joao-O-Santos/pi-filler/-/commits/main)
+[![npm
+version](https://img.shields.io/npm/v/pi-filler.svg)](https://www.npmjs.com/package/pi-filler)
+[![npm
+downloads](https://img.shields.io/npm/dt/pi-filler.svg)](https://www.npmjs.com/package/pi-filler)
+[![license](https://img.shields.io/npm/l/pi-filler.svg)](https://gitlab.com/Joao-O-Santos/pi-filler/-/blob/main/LICENSE)
 
-`pi-filler` fills document-handling gaps between ordinary Markdown
-workflows and final office-format requirements. It delegates common
-conversion and PDF extraction to mature command-line tools while keeping
-Word-specific mutations narrow and inspectable.
+**Deterministic DOCX, PDF, and XLSX tooling for Pi.**
 
-## Status
+`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 and XLSX mutations narrow,
+transactional, and inspectable.
 
-Early experimental release. The tool schema and supported document
-operations may change before 1.0.0.
+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.
 
-## Tool
+## Install
+
+Install the published package:
+
+``` sh
+pi install npm:pi-filler
+```
+
+Or install the current main branch for development and unreleased
+features:
+
+``` sh
+pi install git:https://gitlab.com/Joao-O-Santos/pi-filler.git
+```
+
+External programs are required only for the operations listed under
+[External tools](#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:
 
-```text
-format: docx | pdf
+``` text
+format: docx | pdf | xlsx
 action: read | search | write | patch
-view: text | formatting | image
+view: text | formatting | image | structure
+```
+
+`format` names the document or target format, not every input: DOCX
+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` |
+| 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`; all 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:
+
+``` ts
+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
+})
 ```
 
-Unsupported combinations and operation-irrelevant parameters fail
-explicitly. DOCX patching also accepts `dry_run: true` to validate and
-report the requested result without writing the output file.
+Results may be truncated. For a truncated PDF text read, use a page
+range; for PDF or DOCX search, narrow the query. PDF search can also use
+a page range. Dry runs still read and validate all local inputs.
 
-## PDF
+## PDF operations
 
-- Read text with layout preservation and optional page ranges.
-- Search with literal or regular-expression queries and page numbers.
-- Restrict searches to optional page ranges.
-- Render selected pages to PNG files without destroying prior output
-  when rendering fails.
-- PDF writing and patching are not supported.
+- 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
+## DOCX operations
 
-- Read and search text through Pandoc.
-- Render selected pages to PNG through LibreOffice and the existing PDF
-  rendering path.
-- Generate DOCX from Markdown with an optional reference document.
-- Validate generated DOCX before replacing the requested output.
-- Inspect page setup, margins, sections, line numbering, page
+- 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.
-- Patch page setup, margins, line numbering, page numbering, and common
-  core metadata.
-- Use `clearCoreMetadata` to clear common `docProps/core.xml` fields.
-  This does **not** remove comment authors, revision authors, or every
-  possible identity-bearing property in a DOCX.
-
-Page setup, margins, line numbering, and page numbering patches affect
-the first section only. Core-metadata patches are document-level.
-Untouched ZIP package parts remain content-identical. XML parts that are
-edited are parsed and serialized again, so lexical formatting, prefix
-choices, or element ordering inside those edited parts may change.
+- 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, formulas, comments, and other
+workbook text are processed locally and are not returned to the model.
+Structural results contain sheet names, ranges, dimensions, counts,
+merged-range addresses, hidden row and column ranges, changed package
+parts, and write status---not workbook 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 all workbook print pages through
+  LibreOffice to numbered PNG files; it does not select a sheet.
+- `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.
+
+## Output and mutation behavior
+
+DOCX 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 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 text conversion and generation.
-- `libreoffice` for DOCX image rendering.
-- `pdftotext` for PDF text extraction.
-- `pdftocairo` for PDF and DOCX page rendering.
+- `pandoc` for DOCX text conversion, search, and generation;
+- `libreoffice` for DOCX and XLSX image rendering;
+- `pdftotext` for PDF text extraction;
+- `pdftocairo` for PDF, DOCX, and XLSX page rendering; and
 - `pdfgrep` for page-aware PDF search.
 
-## Development
+A missing executable produces an explicit error naming the unavailable
+program.
+
+## Development and release
 
-```sh
+``` sh
 npm install
 make verify
 make site
 ```
 
+`make verify` runs typechecking, lint and formatting checks,
+deterministic tests, 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.
+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](LICENSE)

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "pi-filler",
-	"version": "0.0.0",
-	"description": "Deterministic DOCX and PDF tooling for Pi",
+	"version": "0.2.0",
+	"description": "Deterministic DOCX, PDF, and XLSX tooling for Pi",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
 		"docx",
 		"pdf",
+		"xlsx",
 		"pandoc",
 		"document-processing"
 	],
@@ -46,6 +47,11 @@
 			"./src/index.ts"
 		]
 	},
+	"allowScripts": {
+		"@google/genai": false,
+		"esbuild": true,
+		"protobufjs": false
+	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
@@ -63,6 +69,7 @@
 		"typescript": "latest"
 	},
 	"dependencies": {
+		"csv-parse": "latest",
 		"fast-xml-parser": "latest",
 		"fflate": "latest"
 	}

package/src/docx.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, posix, resolve } from "node:path";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
-import { unzipSync, zipSync } from "fflate";
+import { type OfficePackage, packOfficePackage, unpackOfficePackage } from "./ooxml.js";
 
 export interface DocxPatchSet {
 	page?: { width?: number; height?: number; orientation?: "portrait" | "landscape" };
@@ -50,7 +50,7 @@ export interface DocxPatchResult {
 	written: boolean;
 }
 
-type Package = Record<string, Uint8Array>;
+type Package = OfficePackage;
 type XmlObject = Record<string, unknown>;
 
 const WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
@@ -86,11 +86,7 @@ function serializeXml(value: XmlObject): Uint8Array {
 }
 
 function unpack(bytes: Uint8Array): Package {
-	try {
-		return unzipSync(bytes);
-	} catch (error) {
-		throw new Error(`Invalid DOCX ZIP package: ${error instanceof Error ? error.message : error}`);
-	}
+	return unpackOfficePackage(bytes, "DOCX");
 }
 
 function findAll(value: unknown, suffix: string, found: XmlObject[] = []): XmlObject[] {
@@ -507,7 +503,7 @@ export async function patchDocx(
 	const temporary = join(dirname(output), `.${output.split(/[\\/]/).pop()}.${randomUUID()}.tmp`);
 	await mkdir(dirname(output), { recursive: true });
 	try {
-		await writeFile(temporary, zipSync(pkg));
+		await writeFile(temporary, packOfficePackage(pkg));
 		await inspectDocx(temporary);
 		await rename(temporary, output);
 		result.written = true;