zalos-sheetops 0.4.2__tar.gz

zalos_sheetops-0.4.2/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish the verified package to PyPI
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - run: uv sync --all-groups --locked
+      - name: Install rtk shim
+        run: |
+          mkdir -p "$HOME/.local/bin"
+          printf '#!/usr/bin/env bash\nexec "$@"\n' > "$HOME/.local/bin/rtk"
+          chmod +x "$HOME/.local/bin/rtk"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - run: rtk uv run pytest
+      - run: rtk uv run ruff check .
+      - run: rtk uv run ruff format --check .
+      - run: uv build --no-sources
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    if: github.event_name == 'workflow_dispatch' && inputs.publish && github.ref == 'refs/heads/main'
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - run: uv publish --trusted-publishing always dist/*

zalos_sheetops-0.4.2/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.superpowers/
+.benchmarks/

zalos_sheetops-0.4.2/AGENTS.md

@@ -0,0 +1,64 @@
+# Zalos SheetOps Agent Instructions
+
+This repo builds spreadsheet tools that Codex, Claude Code, and other AI agents
+can trust for precise Excel and CSV work.
+
+## Non-Negotiable Rules
+
+- Use test-driven development for every behavior change.
+- Write the failing test first and verify it fails for the expected reason.
+- Add return type annotations to every function.
+- Use built-in collection types such as `list` and `dict`.
+- Do not add a CLI command without JSON contract tests.
+- Do not silently guess workbook structure.
+- Fail closed with a stable `errorCode` and compact JSON details.
+- Keep output deterministic so agents can parse it safely.
+- Record provenance for copied or adapted upstream tests.
+- Keep `skills/claude/SKILL.md` as a symlink to `skills/codex/SKILL.md`.
+
+## Command Contract
+
+Every command returns a JSON object with this successful shape:
+
+```json
+{
+  "ok": true,
+  "command": "inspect",
+  "data": {},
+  "warnings": [],
+  "artifacts": []
+}
+```
+
+Every failure returns this shape:
+
+```json
+{
+  "ok": false,
+  "command": "inspect",
+  "errorCode": "file_not_found",
+  "message": "Workbook file does not exist",
+  "details": {},
+  "warnings": [],
+  "artifacts": []
+}
+```
+
+## Required Verification
+
+Before completing a change, run:
+
+```bash
+rtk uv run pytest
+rtk uv run ruff check .
+rtk uv run ruff format --check .
+```
+
+## Contribution Flow
+
+1. Pick one public behavior.
+2. Add or port the failing test first.
+3. Run the focused test and confirm the red state.
+4. Implement the smallest code that passes.
+5. Run the focused tests and relevant suite.
+6. Update examples or skills only after behavior is stable.

zalos_sheetops-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zalos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zalos_sheetops-0.4.2/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: zalos-sheetops
+Version: 0.4.2
+Summary: Agent-native Excel and CSV operations toolkit
+Project-URL: Repository, https://github.com/Zalos-io/zalos-sheetops
+Project-URL: Issues, https://github.com/Zalos-io/zalos-sheetops/issues
+Author: Zalos
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: openpyxl<4,>=3.1.0
+Description-Content-Type: text/markdown
+
+# Zalos SheetOps
+
+Agent-native Excel and CSV operations toolkit.
+
+The project prioritizes precise, deterministic spreadsheet operations for AI
+agents. Features are added test-first and exposed through machine-readable CLI
+contracts before agents are encouraged to rely on them.
+
+## Agent Examples
+
+Every command prints one line of compact JSON by default. Pass `--pretty` when
+a human needs to read the output; `--raw-output` remains accepted as a
+deprecated alias for the default.
+
+```bash
+sheetops doctor libreoffice
+sheetops inspect --json '{"path":"output.xlsx","engine":"auto","maxFormulaCells":20}'
+sheetops read-table --json '{"path":"output.xlsx","sheet":"Data","headerStrategy":"row","headerRow":1,"maxRows":50}'
+sheetops cells read --json '{"path":"output.xlsx","sheet":"Summary","range":"A1:D20","include":["values","formulas","cachedValues","numberFormats"]}'
+sheetops cells search --json '{"path":"output.xlsx","query":"#4BACC6","fields":["fillColors"],"sheet":"Summary","range":"A1:Z200","limit":100,"offset":0}'
+sheetops hyperlinks assert --json '{"path":"output.xlsx","sheet":"Summary","checks":[{"cell":"B2","target":"https://example.com/customer","display":"Customer portal"}]}'
+sheetops styles assert --json '{"path":"output.xlsx","sheet":"Merchant","checks":[{"cell":"E2","fill":"#D9EAF7"},{"cell":"H2","commentContains":"Method of Payment Code"},{"cell":"G3","fill":"#D9EAF7","formula":true}]}'
+sheetops formulas scan --json '{"path":"output.xlsx","sheet":"Summary","range":"A1:D50","include":["errors"],"failFast":true,"engine":"auto"}'
+sheetops normalize preview --json '{"path":"input.xlsx","sheet":"Data","headerStrategy":"detect","columns":[{"source":"Amount","kind":"amount","name":"amount"}]}'
+sheetops recalc --json '{"path":"output.xlsx","outputDir":"outputs/recalc"}'
+sheetops diff --json '{"left":{"path":"actual.csv"},"right":{"path":"expected.csv"},"keyColumns":["reference"],"compareColumns":["amount"],"amountTolerance":"0.00"}'
+sheetops reconcile --json '{"left":{"path":"bank.csv"},"right":{"path":"processor.csv"},"leftKeyColumns":["reference"],"rightKeyColumns":["reference"],"leftAmountColumn":"amount","rightAmountColumn":"amount","amountTolerance":"0.01"}'
+```
+
+Run `scripts/setup-libreoffice` when `sheetops doctor libreoffice`
+reports that LibreOffice is missing or broken. The script prints the appropriate
+macOS or Linux install command and never runs `sudo` automatically.
+
+`inspect` defaults to the XML engine so large workbook metadata checks do not
+materialize every worksheet through OpenPyXL. Keep OpenPyXL read-only usage to
+bounded cell or range commands where the requested area is explicit.
+Inspection reports exact sheet visibility, defined names, bounded merged ranges,
+and chart/image anchors. `cells search` stops at `maxCells` and reports
+`stoppedEarly` rather than silently claiming a complete result.
+
+Keep responses token-bounded: `maxRows` on table reads, `maxFormulaCells` on
+inspect (default 20), `maxResults` on scans, and explicit `include` lists on
+cell reads. `read-table` returns `headers` plus positional `rows` arrays and
+stops scanning at `maxRows` under `headerStrategy` `row`, reporting
+`"rowCount": null` with `"truncated": true` when the total is unknown.
+`cells read` omits blank cells and null formulas; compare `returnedCellCount`
+with `cellCount` to see how many cells were blank.
+
+## Verification
+
+Run these before claiming a change is ready:
+
+```bash
+rtk uv run pytest
+rtk uv run ruff check .
+rtk uv run ruff format --check .
+```
+
+## Releases
+
+`v0.4.2` is the first public release, with MIT licensing and public package metadata.
+It preserves the `v0.4.1` behavior baseline. It fixes worksheet bounds inspection
+when dimension metadata is missing or invalid, including implicit row and cell
+coordinates. This prevents non-empty worksheets from being reported as `A1`.
+
+The `v0.4.0` release added deterministic, bounded
+`cells search` across values, formulas, cached values, number formats, font
+colors, and fill colors, with regex, pagination, hidden-sheet control, and
+explicit scan limits. XML inspection now reports exact sheet states, defined
+names, merged-range metadata, and chart/image anchors while failing closed
+with `invalid_workbook` for malformed drawing relationships. Metadata output
+is independently truncated without hiding total counts.
+
+It builds on the `v0.3.1` performance and agent-output release, including the
+packaging guard that keeps `zalos_sheetops.__version__` aligned with the
+distribution version. The CLI dropped typer/click/rich for a zero-dependency
+dispatcher, so cold start halved again and `--help` renders plain text.
+`read-table` and `normalize preview` stop streaming at `maxRows` under
+explicit header rows (about 80x faster on 100k-row workbooks), `validate`
+runs about twice as fast, and `formulas scan` streams through the shared
+expat engine instead of ElementTree. Output is compact JSON by default with
+`--pretty` opt-in, `read-table` rows are positional arrays under `headers`,
+`cells read` omits blank cells and null formulas and reports
+`returnedCellCount`, `styles read` drops redundant row/column fields, and
+`inspect` caps `formulaCells` at 20 by default (`formulaCellsTruncated`
+signals more). The XML engine now expands shared formulas natively using
+openpyxl's translator, so `cells read`, `formulas scan`, and
+`compare labeled-cells` report the real per-cell formula instead of "=" for
+shared-formula followers, and formula scans on shared-formula workbooks no
+longer fall back to the slow openpyxl load. Two precision fixes validated
+against 100MB+ production workbooks: `inspect` tag counting no longer drops
+tags that straddle its internal 1MB scan-chunk boundaries, and `maxResults`
+on `formulas scan` caps returned items across the whole workbook on both
+engines instead of per sheet. The envelope contract
+(`ok`/`command`/`data`/`warnings`/`artifacts`) is unchanged. Consumers upgrading from `v0.2.11` must adapt to
+the new `data` payload shapes for `read-table`, `cells read`, and
+`styles read`, and to the compact default output.
+
+It includes the `v0.1.0` `inspect`, `read-table`, `validate`, and
+`formulas scan` baseline, plus fixture-backed `cells read`, scoped formula
+scanning, validation rules, LibreOffice doctor/recalc support, normalization,
+diff, reconciliation, style/comment assertion commands, display overflow
+scanning, italic style assertions, style extraction for bounded cell ranges,
+and a fast XML-backed style assertion path for targeted formula, fill, and
+comment checks. Formula scanning defaults to the faster XML engine, supports
+formula/error category selection, supports fail-fast formula error checks,
+and falls back to `openpyxl` for unsupported workbook features. Hyperlink
+assertion supports cell-targeted XML validation for external or internal
+targets, display text, and tooltips. Workbook inspection defaults to the XML
+engine for full-workbook metadata scans, and CLI help explains command
+intent, JSON payloads, and bounded range guidance.
+
+## Install
+
+```bash
+python -m pip install zalos-sheetops==0.4.2
+```
+
+The public repository is https://github.com/Zalos-io/zalos-sheetops.
+Until the initial PyPI release is available, install from its reviewed release tag.
+The internal repository and its history are not part of this public distribution.
+
+## License
+
+MIT. Borrowed test fixtures retain their upstream licenses and attribution in
+`tests/fixtures/manifest.json` and the adjacent upstream license files.

zalos_sheetops-0.4.2/README.md

@@ -0,0 +1,126 @@
+# Zalos SheetOps
+
+Agent-native Excel and CSV operations toolkit.
+
+The project prioritizes precise, deterministic spreadsheet operations for AI
+agents. Features are added test-first and exposed through machine-readable CLI
+contracts before agents are encouraged to rely on them.
+
+## Agent Examples
+
+Every command prints one line of compact JSON by default. Pass `--pretty` when
+a human needs to read the output; `--raw-output` remains accepted as a
+deprecated alias for the default.
+
+```bash
+sheetops doctor libreoffice
+sheetops inspect --json '{"path":"output.xlsx","engine":"auto","maxFormulaCells":20}'
+sheetops read-table --json '{"path":"output.xlsx","sheet":"Data","headerStrategy":"row","headerRow":1,"maxRows":50}'
+sheetops cells read --json '{"path":"output.xlsx","sheet":"Summary","range":"A1:D20","include":["values","formulas","cachedValues","numberFormats"]}'
+sheetops cells search --json '{"path":"output.xlsx","query":"#4BACC6","fields":["fillColors"],"sheet":"Summary","range":"A1:Z200","limit":100,"offset":0}'
+sheetops hyperlinks assert --json '{"path":"output.xlsx","sheet":"Summary","checks":[{"cell":"B2","target":"https://example.com/customer","display":"Customer portal"}]}'
+sheetops styles assert --json '{"path":"output.xlsx","sheet":"Merchant","checks":[{"cell":"E2","fill":"#D9EAF7"},{"cell":"H2","commentContains":"Method of Payment Code"},{"cell":"G3","fill":"#D9EAF7","formula":true}]}'
+sheetops formulas scan --json '{"path":"output.xlsx","sheet":"Summary","range":"A1:D50","include":["errors"],"failFast":true,"engine":"auto"}'
+sheetops normalize preview --json '{"path":"input.xlsx","sheet":"Data","headerStrategy":"detect","columns":[{"source":"Amount","kind":"amount","name":"amount"}]}'
+sheetops recalc --json '{"path":"output.xlsx","outputDir":"outputs/recalc"}'
+sheetops diff --json '{"left":{"path":"actual.csv"},"right":{"path":"expected.csv"},"keyColumns":["reference"],"compareColumns":["amount"],"amountTolerance":"0.00"}'
+sheetops reconcile --json '{"left":{"path":"bank.csv"},"right":{"path":"processor.csv"},"leftKeyColumns":["reference"],"rightKeyColumns":["reference"],"leftAmountColumn":"amount","rightAmountColumn":"amount","amountTolerance":"0.01"}'
+```
+
+Run `scripts/setup-libreoffice` when `sheetops doctor libreoffice`
+reports that LibreOffice is missing or broken. The script prints the appropriate
+macOS or Linux install command and never runs `sudo` automatically.
+
+`inspect` defaults to the XML engine so large workbook metadata checks do not
+materialize every worksheet through OpenPyXL. Keep OpenPyXL read-only usage to
+bounded cell or range commands where the requested area is explicit.
+Inspection reports exact sheet visibility, defined names, bounded merged ranges,
+and chart/image anchors. `cells search` stops at `maxCells` and reports
+`stoppedEarly` rather than silently claiming a complete result.
+
+Keep responses token-bounded: `maxRows` on table reads, `maxFormulaCells` on
+inspect (default 20), `maxResults` on scans, and explicit `include` lists on
+cell reads. `read-table` returns `headers` plus positional `rows` arrays and
+stops scanning at `maxRows` under `headerStrategy` `row`, reporting
+`"rowCount": null` with `"truncated": true` when the total is unknown.
+`cells read` omits blank cells and null formulas; compare `returnedCellCount`
+with `cellCount` to see how many cells were blank.
+
+## Verification
+
+Run these before claiming a change is ready:
+
+```bash
+rtk uv run pytest
+rtk uv run ruff check .
+rtk uv run ruff format --check .
+```
+
+## Releases
+
+`v0.4.2` is the first public release, with MIT licensing and public package metadata.
+It preserves the `v0.4.1` behavior baseline. It fixes worksheet bounds inspection
+when dimension metadata is missing or invalid, including implicit row and cell
+coordinates. This prevents non-empty worksheets from being reported as `A1`.
+
+The `v0.4.0` release added deterministic, bounded
+`cells search` across values, formulas, cached values, number formats, font
+colors, and fill colors, with regex, pagination, hidden-sheet control, and
+explicit scan limits. XML inspection now reports exact sheet states, defined
+names, merged-range metadata, and chart/image anchors while failing closed
+with `invalid_workbook` for malformed drawing relationships. Metadata output
+is independently truncated without hiding total counts.
+
+It builds on the `v0.3.1` performance and agent-output release, including the
+packaging guard that keeps `zalos_sheetops.__version__` aligned with the
+distribution version. The CLI dropped typer/click/rich for a zero-dependency
+dispatcher, so cold start halved again and `--help` renders plain text.
+`read-table` and `normalize preview` stop streaming at `maxRows` under
+explicit header rows (about 80x faster on 100k-row workbooks), `validate`
+runs about twice as fast, and `formulas scan` streams through the shared
+expat engine instead of ElementTree. Output is compact JSON by default with
+`--pretty` opt-in, `read-table` rows are positional arrays under `headers`,
+`cells read` omits blank cells and null formulas and reports
+`returnedCellCount`, `styles read` drops redundant row/column fields, and
+`inspect` caps `formulaCells` at 20 by default (`formulaCellsTruncated`
+signals more). The XML engine now expands shared formulas natively using
+openpyxl's translator, so `cells read`, `formulas scan`, and
+`compare labeled-cells` report the real per-cell formula instead of "=" for
+shared-formula followers, and formula scans on shared-formula workbooks no
+longer fall back to the slow openpyxl load. Two precision fixes validated
+against 100MB+ production workbooks: `inspect` tag counting no longer drops
+tags that straddle its internal 1MB scan-chunk boundaries, and `maxResults`
+on `formulas scan` caps returned items across the whole workbook on both
+engines instead of per sheet. The envelope contract
+(`ok`/`command`/`data`/`warnings`/`artifacts`) is unchanged. Consumers upgrading from `v0.2.11` must adapt to
+the new `data` payload shapes for `read-table`, `cells read`, and
+`styles read`, and to the compact default output.
+
+It includes the `v0.1.0` `inspect`, `read-table`, `validate`, and
+`formulas scan` baseline, plus fixture-backed `cells read`, scoped formula
+scanning, validation rules, LibreOffice doctor/recalc support, normalization,
+diff, reconciliation, style/comment assertion commands, display overflow
+scanning, italic style assertions, style extraction for bounded cell ranges,
+and a fast XML-backed style assertion path for targeted formula, fill, and
+comment checks. Formula scanning defaults to the faster XML engine, supports
+formula/error category selection, supports fail-fast formula error checks,
+and falls back to `openpyxl` for unsupported workbook features. Hyperlink
+assertion supports cell-targeted XML validation for external or internal
+targets, display text, and tooltips. Workbook inspection defaults to the XML
+engine for full-workbook metadata scans, and CLI help explains command
+intent, JSON payloads, and bounded range guidance.
+
+## Install
+
+```bash
+python -m pip install zalos-sheetops==0.4.2
+```
+
+The public repository is https://github.com/Zalos-io/zalos-sheetops.
+Until the initial PyPI release is available, install from its reviewed release tag.
+The internal repository and its history are not part of this public distribution.
+
+## License
+
+MIT. Borrowed test fixtures retain their upstream licenses and attribution in
+`tests/fixtures/manifest.json` and the adjacent upstream license files.

zalos_sheetops-0.4.2/docs/architecture-and-references.md

@@ -0,0 +1,218 @@
+# SheetOps Architecture And Reference Repositories
+
+This document is the orientation file for future AI agents contributing to
+`zalos-sheetops`. It explains the package architecture, the trust model, and
+the external repositories we studied or borrowed fixtures from.
+
+## Product Goal
+
+`zalos-sheetops` is an agent-native Excel and CSV toolkit for Codex, Claude
+Code, and financial-agent workflows. Its job is to make common spreadsheet
+operations precise, deterministic, and safe enough that agents can call a
+tested command instead of rewriting spreadsheet logic inside every financial
+agent.
+
+The package favors a small set of trusted operations over a large set of
+loosely-tested helpers.
+
+## Architecture
+
+The public surface is a JSON-first CLI plus small Python library modules behind
+each command.
+
+```text
+src/zalos_sheetops/
+  cli.py                 # JSON CLI dispatcher
+  command_registry.py    # machine-readable command manifest
+  contracts.py           # success/error response helpers
+  errors.py              # stable SheetOpsError
+  paths.py               # path hardening and local file validation
+
+  io/
+    inspect.py           # workbook/sheet/cell metadata
+    search_cells.py      # bounded, paginated value/formula/style search
+    headers.py           # header detection and canonicalization
+    read_table.py        # XLSX table extraction
+    read_csv_table.py    # planned CSV table extraction
+
+  validation/
+    workbook.py          # required sheets/columns and uniqueness checks
+
+  normalize/
+    text.py              # header/text canonicalization
+    amounts.py           # planned amount normalization
+    dates.py             # planned date normalization
+    preview.py           # planned normalize-preview command logic
+
+  formulas/
+    scan.py              # formula and formula-error discovery
+
+  recalc/
+    libreoffice.py       # planned LibreOffice recalculation wrapper
+
+  diff/
+    tabular.py           # planned table diff helpers
+
+  reconcile/
+    exact.py             # planned exact reconciliation helpers
+```
+
+## Command Contract
+
+Every command returns structured JSON. Agents should parse these fields and
+avoid parsing human prose.
+
+Success:
+
+```json
+{
+  "ok": true,
+  "command": "inspect",
+  "data": {},
+  "warnings": [],
+  "artifacts": []
+}
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "command": "inspect",
+  "errorCode": "file_not_found",
+  "message": "Workbook file does not exist",
+  "details": {},
+  "warnings": [],
+  "artifacts": []
+}
+```
+
+## Trust Model
+
+- Public behavior starts with a failing test.
+- Tests must verify exact JSON shapes for CLI behavior.
+- Real workbook behavior should use fixture-backed tests where possible.
+- Fixture provenance is mandatory for borrowed files.
+- Commands fail closed when inputs are ambiguous.
+- Source files are not mutated by default.
+- Recalculation and generated outputs must go to explicit output paths.
+
+## Fixture Strategy
+
+Fixtures live under `tests/fixtures/`.
+
+```text
+tests/fixtures/
+  README.md
+  manifest.json
+  upstream/
+    calamine/
+    fastexcel/
+    openpyxl/
+    xlsx2csv/
+    xlsxwriter/
+```
+
+Every upstream fixture must be registered in
+`tests/fixtures/manifest.json` with:
+
+- `fixtureId`
+- `sourceRepo`
+- `sourcePath`
+- `license`
+- `destination`
+- `sha256`
+- `behavior`
+
+The manifest hash-locks fixture files so agents cannot unknowingly change test
+ground truth.
+
+## Reference Repositories
+
+These repositories were used as design or fixture references.
+
+### Spreadsheet Agent Skill
+
+| Repo | Used For |
+| --- | --- |
+| `anthropics/skills` | `xlsx` skill conventions: formula-first workbooks, LibreOffice recalc, formula-error scans, color conventions, and agent-facing spreadsheet workflows |
+| `dust-tt/dust@dc59bd33` (`front/lib/api/sandbox/image/profile/soffice/xlsx_inspect.py`) | MIT-licensed design reference for drawing-aware inspection, defined names, displayed color resolution, and paginated workbook search. No upstream implementation or tests were copied; SheetOps behavior was specified and tested independently. |
+
+### Core Workbook IO And Writing
+
+| Repo | License | Used For |
+| --- | --- | --- |
+| `openpyxl` | MIT | Existing workbook inspection, formula text vs cached values, hidden sheets, hyperlinks, comments, defined names, formula token/translation behavior, XLSX fixtures |
+| `XlsxWriter` | BSD-2-Clause | Generated workbook guardrails, formula writing, tables, data validation, conditional formatting, overlap checks, comparison XLSX fixtures |
+| `fastexcel` | MIT | Fast Excel ingestion patterns, `header_row`, `skip_rows`, whitespace, duplicate columns, sheet visibility, table-offset fixtures |
+| `calamine` | MIT | Cross-format spreadsheet parsing behavior, formula edge cases, shared formulas, `.xls`/`.xlsb`/`.ods` future support, fixtures |
+
+### Data Processing
+
+| Repo | Used For |
+| --- | --- |
+| `polars` | DataFrame transform patterns: `select`, `with_columns`, `filter`, `group_by`, `join`, `concat`, lazy scans |
+| `pandas` | Excel/CSV IO option reference: sheet selection, `header`, `dtype`, `parse_dates`, `thousands`, `decimal`, `skipfooter` |
+| `numpy` | Numeric behavior reference only; not a primary SheetOps dependency |
+
+### Validation And Data Contracts
+
+| Repo | Used For |
+| --- | --- |
+| `pandera` | Schema/check design: required columns, strict schemas, uniqueness, nullable/coerce behavior, dataframe-level checks |
+| `frictionless-py` | File/table diagnostics: dialect, header rows, missing values, checklist-style validation |
+| `great_expectations` | Expectation-style validation concepts and reporting vocabulary |
+
+### Matching And Reconciliation
+
+| Repo | Used For |
+| --- | --- |
+| `RapidFuzz` | Future fuzzy matching, string similarity thresholds, scorer behavior |
+
+### CSV, Diff, And Conversion
+
+| Repo | License | Used For |
+| --- | --- | --- |
+| `xlsx2csv` | MIT | XLSX-to-CSV fixtures and expected CSV baselines for datetimes, UTF-8, empty rows, hyperlinks, delimiters |
+| `csvkit` | MIT | CSV dialect and cleanup edge cases: BOM, Latin-1, short/long rows, no-header files, newline behavior |
+| `csv-diff` | Apache-2.0 | Keyed row diff shape: added rows, removed rows, changed rows |
+| `daff` | MIT | Table diff concepts, row/column alignment, patch-style comparison behavior |
+
+### Formula Evaluation And Recalculation
+
+| Repo | Used For |
+| --- | --- |
+| `xlcalculator` | Offline formula-evaluation reference and limitations |
+| `formulas` | Formula parser/evaluator reference, supported function landscape, compare-method ideas |
+| LibreOffice | Primary future recalculation path because it recalculates real XLSX workbooks instead of approximating Excel behavior |
+
+## Borrowed Fixture Sources
+
+The current fixture manifest borrows files from:
+
+- `fastexcel`
+- `calamine`
+- `openpyxl`
+- `xlsx2csv`
+- `XlsxWriter`
+
+See `tests/fixtures/manifest.json` for exact source paths, destination paths,
+licenses, SHA256 hashes, and the behavior each fixture protects.
+
+## How To Add A New Reference Or Fixture
+
+1. Prefer a small synthetic fixture if it proves the behavior.
+2. Borrow an upstream fixture only when real workbook structure matters.
+3. Copy the file into `tests/fixtures/upstream/<repo>/`.
+4. Record source repo, source path, license, destination, SHA256, and protected
+   behavior in `tests/fixtures/manifest.json`.
+5. Add or update a test that fails before the implementation change.
+6. Run:
+
+```bash
+rtk uv run pytest
+rtk uv run ruff check .
+rtk uv run ruff format --check .
+```
+