@particle-academy/holy-sheet 2.10.1 → 2.11.0

package/CHANGELOG.md

@@ -10,6 +10,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.0] - 2026-10-27
+
+### Added
+
+- **Excel `.xltx` templates read, and `.ots` templates marked.** `read()` /
+  `describe()` read an `.xltx` exactly as its `.xlsx` twin and add
+  `sourceKind: "template"`; an `.ots` (already read, unmarked) now says so too.
+  `Workbook` gains a trailing optional `sourceKind` (default `"document"`).
+  Document reads are unchanged and carry no `sourceKind` key, so nothing to do
+  unless you want to tell the two apart. Mirrors PHP holy-sheet.
+- **`Agent.convertTemplate(bytes, to?)`** (also on `HolySheet`) and the new
+  `holy-sheet` bin, `npx holy-sheet template:convert <in> <out>
+  [--to=document|template] [--force]`, turn a template into its workbook twin
+  and back. Only the declaration is rewritten: the workbook part's content-type
+  value (OOXML), or the `mimetype` entry plus the manifest root's `media-type`
+  (ODF 1.3 Part 2 section 3.3 requires them to agree). Every other zip member is
+  copied as its original record, byte for byte; `mimetype` stays first and
+  stored. The bin is Node-only and never imported by the isomorphic index.
+- `OfficeTemplateRefused` with a constant `reason`.
+
+### Changed
+
+- **A macro-enabled template (`.xltm`) is now refused** with
+  `OfficeTemplateRefused("macro_enabled")`; it used to be read as a workbook with
+  its VBA silently ignored. So is an `.xltx` carrying a `vbaProject.bin`. An
+  `.xlsm` still reads as before but is never converted.
+- A package that declares a template of another family is refused with
+  `family_mismatch` instead of being read as whatever its parts looked like.
+
+## [2.10.2] - 2026-10-26
+
+### Security
+
+- Route XLSX/ODS and public `unzipSync` reads through bounded ZIP validation:
+  coherent local/central records, safe unique member names, CRC and exact sizes,
+  archive/part/total/ratio limits and bounded DEFLATE output. Reject truncated or
+  invalid codes and back-references with typed `ArchiveRefused`; Node file input
+  is bounded before allocation. Defaults: 64 MiB archive/part, 256 MiB expanded,
+  16,384 entries and 1000:1 ratio. `unzipSync(bytes, limits)` supports lower host
+  ceilings. Existing valid payload bytes and spreadsheet projections are retained.
+
+- Update Vitest to 4.1.12 for security fixes; dev toolchain only, nothing to do.
+
+- **Dev toolchain only — no runtime change, nothing for consumers to do.** The
+  lockfile now resolves `vite` 8.3.5 (was 8.2.2), whose bundled
+  `launch-editor` fixes GHSA-587h-7wmj-h5pm (HIGH, `fs.existsSync()` check
+  bypassable on Windows), GHSA-698v-4r3x-3vcv (`escapeCmdArgs()` omits `%`
+  escaping on Windows) and GHSA-r825-w8mm-5pxw (editor CLI flag
+  misinterpretation). `vite` is only reached through the test/dev toolchain
+  and the published package does not ship our lockfile, so the exposure was
+  this repo's own dev server.
+
 ## [2.10.1] — 2026-10-19
 
 ### Fixed

package/README.md

@@ -37,6 +37,13 @@ await Agent.write(schema, "sales.xlsx");
 
 ## API
 
+Spreadsheet reads and `unzipSync` validate ZIP structure, CRC, unique safe names
+and expansion before XML parsing. Unsafe ZIPs throw exported `ArchiveRefused`
+with a bounded `reason`; ordinary non-spreadsheet formats retain
+`UnsupportedFormatException`. Defaults are 64 MiB archive/part, 256 MiB expanded,
+16,384 entries and 1000:1 ratio. `unzipSync(bytes, limits)` accepts lower host
+ceilings via `ArchiveLimits`. This input layer does not add lossless editing.
+
 `Agent` (static) mirrors the PHP surface:
 
 - `validate(schema)` → structured errors `{path, expected, got, value, hint}[]`
@@ -69,6 +76,33 @@ when there is one). What maps and what does not is listed in the PHP package's
 [`docs/ReadPath.md`](https://github.com/Particle-Academy/holy-sheet/blob/main/docs/ReadPath.md#opendocument-spreadsheets-ods);
 this port reads the same fixtures and is diffed against it.
 
+### Excel and LibreOffice templates (.xltx, .ots)
+
+An `.xltx` is an `.xlsx` whose workbook part is declared a template; an `.ots`
+is an `.ods` whose `mimetype` (and manifest root entry) says
+`spreadsheet-template`. `read()` / `describe()` read both exactly as their twins
+and add `sourceKind: "template"` (also `Workbook#sourceKind` from
+`readWorkbook()`). A document read has no `sourceKind` key, as before.
+
+```ts
+Agent.read(xltxBytes);                 // { ..., sourceKind: "template" }
+Agent.convertTemplate(xltxBytes);      // .xlsx bytes ("document" | "template" | null = flip)
+```
+
+```
+npx holy-sheet template:convert budget.xltx budget.xlsx
+npx holy-sheet template:convert budget.ods budget.ots --to=template
+```
+
+Conversion rewrites only the declaration: the content-type value in
+`[Content_Types].xml`, or the ODF `mimetype` entry plus the manifest's root
+`media-type` (ODF 1.3 requires the two to match). Every other member is copied
+as its original zip record, byte for byte; `mimetype` stays first and stored.
+Refused with `OfficeTemplateRefused` (a constant `reason`): macro-enabled `.xltm`
+(`macro_enabled`; an `.xlsm` is never converted either) and a package declaring
+a template of another family (`family_mismatch`). The archive guards apply
+first. Mirrors PHP `Agent::convertTemplate()`.
+
 ### Versions as diffs
 
 `Agent.diff(a, b)` returns the ops that turn one schema into another, and