xlsx-for-ai 1.2.0 → 1.3.1

package/README.md

@@ -1,8 +1,16 @@
 # xlsx-for-ai
 
-Converts `.xlsx` files into rich text or JSON dumps that AI coding agents can actually read.
+> 👋 **New here? Not a programmer?** → [Read WHY.md for the plain-English version](WHY.md). The README below is the technical reference.
 
-AI tools — Claude, Cursor, Copilot, ChatGPT, and other LLM coding agents — can read text files but **not** `.xlsx` binaries. This CLI bridges the gap. It extracts everything a human would see in Excel and writes it to a plain text file (or structured JSON):
+Converts spreadsheets into text, **markdown**, JSON, SQL, or schema dumps that AI coding agents can actually read.
+
+AI tools — Claude, Cursor, Copilot, ChatGPT, and other LLM coding agents — can read text files but **not** `.xlsx` binaries. This CLI bridges the gap.
+
+**Input formats:** `.xlsx` `.xls` `.xlsb` `.ods` `.csv` `.tsv`
+
+**Output modes:** text dump, markdown tables (best LLM comprehension per token), JSON, SQL `CREATE TABLE`+`INSERT`, inferred schema, workbook diff.
+
+It extracts everything a human would see in Excel:
 
 - **Values** — strings, numbers, dates
 - **Formulas** — the actual formula expression, plus shared-formula references
@@ -66,18 +74,44 @@ npx xlsx-for-ai data.xlsx "Sheet1" --stdout --max-rows 50 --compact
 
 ### Options
 
+**Output modes** (mutually exclusive; default = text):
+
+| Flag | Description |
+|------|-------------|
+| `--md` | Markdown tables — highest LLM comprehension per token |
+| `--json` | Structured JSON, one object per cell |
+| `--sql` | `CREATE TABLE` + `INSERT` statements (uses inferred schema) |
+| `--schema` | Per-column schema (name, type, nullable, samples) as JSON |
+
+**Selection:**
+
+| Flag | Description |
+|------|-------------|
+| `[sheetName]` | Positional: dump only this sheet |
+| `--range A1:D50` | Dump only this rectangular range |
+| `--named-range NAME` | Dump only the cells covered by a workbook-defined name |
+| `--max-rows N` | Cap at the first N rows per sheet |
+| `--max-cols N` | Cap at the first N columns per sheet |
+
+**Output control:**
+
+| Flag | Description |
+|------|-------------|
+| `--list-sheets` | Print sheet names + dimensions and exit |
+| `--stdout` | Print to stdout instead of writing files in `.xlsx-read/` |
+| `--compact` | Suppress noisy default tags (default colors, "General" format) |
+| `--max-tokens N` | Truncate output to ~N tokens; appends a tail summary noting what was dropped |
+| `--evaluate` | Promote cached formula results to primary value; re-evaluate simple formulas via formulajs |
+
+**Other modes:**
+
 | Flag | Description |
 |------|-------------|
-| `--list-sheets` | Print sheet names, row/column counts, and visibility — then exit |
-| `--stdout` | Print output to stdout instead of writing `.txt` files |
-| `--json` | Emit structured JSON (one object per cell with value/formula/format/style) |
-| `--compact` | Suppress noisy default tags (default text color, white fill, etc.) — reduces token usage for AI agents |
-| `--max-rows N` | Cap output at the first N rows per sheet |
-| `--max-cols N` | Cap output at the first N columns per sheet |
-| `-h`, `--help` | Show help message |
+| `--diff OTHER` | Diff this workbook vs `OTHER` — emit changed/added/removed cells and sheets |
+| `--stream` | Streaming reader for huge `.xlsx` files (>100MB); emits row-by-row, drops some sheet metadata |
+| `-h`, `--help` | Show help |
 
 Output files are written to `.xlsx-read/` in the current working directory.
-Each sheet produces a file named `<filename>--<sheetname>.txt`.
 The path(s) are printed to stdout so your agent knows where to read.
 
 ## Output Format

package/WHY.md

@@ -0,0 +1,47 @@
+# Why xlsx-for-ai exists
+
+*A plain-English version. For the technical reference, see [README.md](README.md).*
+
+## The problem you've probably hit
+
+You have a spreadsheet — a budget, a financial model, a tax estimate, a list of customers. You ask Claude (or ChatGPT, or Cursor) for help with it.
+
+So you copy and paste a section into the chat. The AI gives you advice that sounds reasonable but feels generic. It misses the broken formula in row 47. It doesn't notice that one tab's totals don't match another tab's source. It can't tell you why the gross margin number changes when you add a new column. It treats your spreadsheet as a blob of numbers — because that's all it can see.
+
+You're not going crazy. The AI literally cannot read the file. It can read text, code, even images of your spreadsheet — but the actual `.xlsx` binary is invisible to it. Formulas, formatting, named ranges, links between sheets — all of that disappears the moment you hit copy-paste.
+
+## What changes when you install this
+
+Once `xlsx-for-ai` is on your machine, your AI tools (Claude, Cursor, Copilot, ChatGPT desktop apps with code execution) can finally **read your spreadsheet the way they read everything else** — every formula, every colored cell, every hidden row, every formula reference between sheets.
+
+Now when you ask for help, you get a real review:
+
+- *"Cell B47 has `#REF!` — it's pointing at a sheet you renamed last week."*
+- *"Your gross margin formula in row 12 references the wrong column on the COGS tab — it's pulling Q3 numbers into the Q4 totals."*
+- *"This 'Total' cell on the Summary tab shows $312k, but if I add up the source rows on the Detail tab I get $327k. Something's off."*
+
+That's the difference between a friend skimming the printed numbers and an analyst who actually opens the file.
+
+## Things that become possible
+
+A few examples people find useful:
+
+- **Have your AI find errors in a financial model** before you send it to your accountant or your board.
+- **Compare two versions of the same spreadsheet** ("what changed between V11 and V14?") and get a list of every cell that moved.
+- **Turn a CSV export from QuickBooks into a clean SQL database table** in one command, with the column types figured out automatically.
+- **Walk through a 50-tab model someone else built** and have the AI explain how the sheets reference each other.
+- **Process a folder of legacy `.xls` files** that won't even open in modern Excel without complaint.
+
+## How to actually use it
+
+It's a small command-line tool. Once a programmer sets it up (one line: `npm install -g xlsx-for-ai`), you don't have to think about it again — your AI tools pick it up automatically and start using it whenever they encounter a spreadsheet.
+
+If you're the programmer doing the install, the [README](README.md) has the full reference. If you're handing this to a programmer to set up for you, that link is what they'll need.
+
+## Why this didn't exist before
+
+Spreadsheet libraries are designed for developers building software *on top of* spreadsheets. They output JavaScript objects, database rows, raw bytes — formats other programs consume. None of them were designed for the case where the consumer is a language model and the goal is a text format the model can actually understand.
+
+`xlsx-for-ai` is the first one built specifically for that. The output is shaped for an LLM's context window — markdown tables when the model just needs to read, structured JSON when it needs to reason, token-aware truncation when the spreadsheet is too big to fit.
+
+It's a small tool. It just happens to fix the one thing standing between AI assistants and the file format most knowledge work actually lives in.

package/cursor-rule-template/read-xlsx.mdc

@@ -1,50 +1,100 @@
 ---
-description: Reading .xlsx spreadsheet files
+description: Reading and converting spreadsheets (.xlsx, .xls, .xlsb, .ods, .csv, .tsv) for AI agents
 globs:
 alwaysApply: true
 ---
 
-# Reading .xlsx Files
-
-The Read tool cannot open `.xlsx` files directly. When you need to inspect a spreadsheet:
-
-1. **Run the converter** from the project root:
-   ```bash
-   npx xlsx-for-ai <path-to-file.xlsx> [sheetName]
-   ```
-   - If `sheetName` is omitted, all sheets are dumped.
-   - Output is written to `.xlsx-read/<filename>--<sheet>.txt` (project root).
-   - The script prints the output path(s) to stdout.
-
-2. **Read the output file** with the Read tool. It contains:
-   - Sheet metadata (frozen panes, column widths, merged cells, auto-filters, print areas)
-   - Named ranges referencing the sheet
-   - Table definitions (name, range, columns)
-   - Image positions
-   - Every row with its cells, showing:
-     - **Value** — always present
-     - **Formula** — `[formula: =SUM(A1:A10)]` (master cell) or `[shared formula ref: D2]` (drag-fill follow-up)
-     - **Number format** — `[numFmt: 0.00%]` if not "General"
-     - **Font** — `[bold]`, `[italic]`, `[color:FF8B0000]`
-     - **Fill** — `[fill:FFFFFF00]` if background color set
-     - **Alignment** — `[align:center]` if non-default
-     - **Hyperlink** — `[link: https://...]` if the cell contains a URL
-     - **Comment** — `[note: ...]` if the cell has a comment or note
-     - **Validation** — `[validation: list [...]]` if the cell has data validation
-     - **Hidden** — `[hidden]` on the row header if the row is hidden
-   - Empty cells are omitted; empty rows show `(empty)`.
-
-3. **Do not ask the user** before running this. Just run it when you need to see an `.xlsx` file.
-
-## Useful flags
-- `--list-sheets` — list sheet names and dimensions without dumping content
-- `--stdout` — print directly to stdout instead of writing files
-- `--json` — emit structured JSON (one object per cell) for easier programmatic use
-- `--compact` — suppress noisy default tags (default text colors, white fills) to reduce token usage
-- `--max-rows N` — limit output to first N rows (use for large sheets)
-- `--max-cols N` — limit output to first N columns (use for very wide sheets)
+# Reading Spreadsheet Files
+
+The Read tool cannot open binary spreadsheet files directly. When you need to inspect or process a spreadsheet, use `xlsx-for-ai`.
+
+**Supported input:** `.xlsx` `.xls` `.xlsb` `.ods` `.csv` `.tsv`
+
+## Basic usage
+
+```bash
+npx xlsx-for-ai <file> [sheetName]
+```
+
+- If `sheetName` is omitted, all sheets are dumped.
+- Default output: text dump to `.xlsx-read/<filename>--<sheet>.txt` (project root).
+- Path(s) printed to stdout for the agent to read next.
+
+**Do not ask the user before running this.** Just run it when you encounter a spreadsheet.
+
+## Pick the right output mode
+
+| When you want… | Use | Why |
+|---|---|---|
+| To read a sheet for context | `--md --stdout` | Markdown tables — best LLM comprehension per token |
+| Programmatic per-cell access | `--json --stdout` | Structured, one object per cell with formula/format/style |
+| To bound output to a context window | `--max-tokens 8000 --stdout` | Truncates with a tail summary noting what was dropped |
+| To understand columns / build a query | `--schema --stdout` | Inferred types per column (INTEGER / NUMERIC / DATE / BOOLEAN / TEXT) |
+| To import data into a database | `--sql --stdout` | `CREATE TABLE` + `INSERT` statements, types from --schema |
+| To compare two versions | `--diff OTHER --stdout` | Emits added/removed/changed sheets and cells |
+| To list sheets without parsing | `--list-sheets` | Fast probe; lighter than full read |
+| To handle huge files (>100MB) | `--stream --stdout` | Row-by-row reader, drops some sheet metadata |
+
+## Selection (focus the output)
+
+| Flag | Effect |
+|---|---|
+| `[sheetName]` | Positional second arg — only this sheet |
+| `--range A1:D50` | Only this rectangular range |
+| `--named-range NAME` | Only the cells covered by a workbook-defined name |
+| `--max-rows N` | Cap rows per sheet |
+| `--max-cols N` | Cap columns per sheet |
+
+Combine selection flags with any output mode. Use `--range` aggressively when you only need a section of a large model — it can reduce context 50× vs. dumping the whole sheet.
+
+## Other useful flags
+
+- `--compact` — suppress noisy default tags (default colors, "General" format, white fills)
+- `--evaluate` — promote cached formula results to the primary value; recompute simple formulas via formulajs
+- `--stdout` — print directly instead of writing files
+
+## What the default text dump contains
+
+- Sheet metadata (frozen panes, column widths, merged cells, auto-filters, print areas)
+- Named ranges referencing the sheet
+- Table definitions (name, range, columns)
+- Image positions
+- Every non-empty row with its cells, showing:
+  - **Value** — always present
+  - **Formula** — `[formula: =SUM(A1:A10)]` (master) or `[shared formula ref: D2]` (drag-fill follow-up)
+  - **Number format** — `[numFmt: 0.00%]` if not "General"
+  - **Font** — `[bold]`, `[italic]`, `[color:FF8B0000]`
+  - **Fill** — `[fill:FFFFFF00]`
+  - **Alignment** — `[align:center]` if non-default
+  - **Hyperlink** — `[link: https://...]`
+  - **Comment** — `[note: ...]`
+  - **Validation** — `[validation: list [...]]`
+  - **Hidden** — `[hidden]` on the row header
+
+## Examples
+
+```bash
+# Quick read of a financial model — markdown is most context-efficient
+npx xlsx-for-ai model.xlsx --md --stdout
+
+# Just one sheet, fits in a small context window
+npx xlsx-for-ai model.xlsx "Assumptions" --md --stdout --max-tokens 4000
+
+# Schema for a CSV before writing SQL
+npx xlsx-for-ai data.csv --schema --stdout
+
+# Surgical extraction — only one section of a huge sheet
+npx xlsx-for-ai model.xlsx "Detail" --range B5:H50 --stdout
+
+# Compare two model versions, get a change summary
+npx xlsx-for-ai v1.xlsx --diff v2.xlsx --stdout
+
+# Huge file (>100MB) — streaming mode keeps memory bounded
+npx xlsx-for-ai dump.xlsx --stream --stdout --max-rows 1000
+```
 
 ## Important
-- Output goes to `.xlsx-read/` in the current working directory — make sure this directory is in your `.gitignore`.
-- For large files, use `--max-rows`, `--max-cols`, or request a single sheet to keep output manageable.
+
+- Output goes to `.xlsx-read/` in the current working directory — add this to `.gitignore`.
+- For huge files, prefer `--max-tokens` over `--max-rows` if you're targeting an LLM context window — token count and row count don't correlate.
 - The package was previously named `cursor-reads-xlsx` — that command name still works as an alias.