xlsx-for-ai 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 senoff
+
+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.

package/README.md

@@ -0,0 +1,195 @@
+# xlsx-for-ai
+
+Converts `.xlsx` files into rich text or JSON 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. It extracts everything a human would see in Excel and writes it to a plain text file (or structured JSON):
+
+- **Values** — strings, numbers, dates
+- **Formulas** — the actual formula expression, plus shared-formula references
+- **Formatting** — bold, italic, font colors, background fills
+- **Number formats** — percentages, currency, custom patterns
+- **Layout** — column widths, frozen panes, merged cells, alignment
+- **Hyperlinks** — URLs embedded in cells
+- **Comments / notes** — cell annotations
+- **Named ranges** — workbook-defined names and their references
+- **Hidden rows & columns** — flagged so the AI knows data is suppressed
+- **Data validation** — dropdown lists, numeric constraints
+- **Tables** — Excel Table objects with their names and column headers
+- **Images & charts** — existence and position noted (content not rendered)
+- **Auto-filters** — active filter ranges
+- **Print areas** — defined print regions
+
+> Previously published as **`cursor-reads-xlsx`**. The old name still works as an alias on the CLI, but please install the new package: `npm install -g xlsx-for-ai`.
+
+## Install
+
+```bash
+npm install -g xlsx-for-ai
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx xlsx-for-ai budget.xlsx
+```
+
+## Usage
+
+```bash
+# Dump all sheets
+npx xlsx-for-ai data.xlsx
+
+# Dump a specific sheet
+npx xlsx-for-ai data.xlsx "Sheet1"
+
+# List sheet names and dimensions without dumping
+npx xlsx-for-ai data.xlsx --list-sheets
+
+# Print to stdout instead of writing files
+npx xlsx-for-ai data.xlsx --stdout
+
+# Limit to first 200 rows per sheet (useful for huge files)
+npx xlsx-for-ai data.xlsx --max-rows 200
+
+# Limit to first 8 columns (useful for very wide sheets)
+npx xlsx-for-ai data.xlsx --max-cols 8
+
+# Suppress noisy default tags (default text colors, white fills, etc.)
+npx xlsx-for-ai data.xlsx --stdout --compact
+
+# Emit structured JSON (one entry per cell) instead of the text dump
+npx xlsx-for-ai data.xlsx --json --stdout > out.json
+
+# Combine flags
+npx xlsx-for-ai data.xlsx "Sheet1" --stdout --max-rows 50 --compact
+```
+
+### Options
+
+| 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 |
+
+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
+
+### Text dump (default)
+
+```
+=== Sheet: Sales ===
+Frozen: row 1, col 0
+Columns: A(12) B(20) C(15) D(10)
+Auto-filter: A1:D20
+Named ranges:
+  Totals: Sales!$D$2:$D$20
+Table: "SalesTable" A1:D20 — columns: Region, Q1, Q2, Total
+
+--- Row 1 [bold] ---
+  A1: "Region"  [bold]
+  B1: "Q1"  [bold] [align:center]
+  C1: "Q2"  [bold] [align:center]
+  D1: "Total"  [bold] [align:center]
+--- Row 2 ---
+  A2: "North"  [link: https://example.com/north]
+  B2: 14500  [numFmt: #,##0]
+  C2: 17200  [numFmt: #,##0]
+  D2: 31700  [formula: =B2+C2] [numFmt: #,##0] [note: Includes returns]
+--- Row 3 ---
+  A3: "South"  [fill:FFFFFF00]
+  B3: 9800  [numFmt: #,##0] [validation: list [North,South,East,West]]
+  C3: 11050  [numFmt: #,##0]
+  D3: 20850  [shared formula ref: D2] [numFmt: #,##0]
+--- Row 4 (empty) [hidden] ---
+```
+
+### JSON dump (`--json`)
+
+```json
+{
+  "name": "Sales",
+  "rowCount": 4,
+  "columnCount": 4,
+  "frozen": { "rowSplit": 1, "colSplit": 0 },
+  "columns": [{ "letter": "A", "width": 12 }, ...],
+  "namedRanges": [{ "name": "Totals", "ranges": ["Sales!$D$2:$D$20"] }],
+  "tables": [{ "name": "SalesTable", "ref": "A1:D20", "columns": ["Region", "Q1", "Q2", "Total"] }],
+  "cells": [
+    { "ref": "D2", "row": 2, "col": 4, "value": { "formula": "B2+C2", "result": 31700 }, "numFmt": "#,##0" },
+    { "ref": "D3", "row": 3, "col": 4, "value": { "sharedFormulaRef": "D2", "result": 20850 }, "numFmt": "#,##0" }
+  ]
+}
+```
+
+### Sheet Metadata
+
+| Line | Meaning |
+|------|---------|
+| `Frozen: row 1, col 2` | Frozen panes position |
+| `Columns: A(12) B(20)` | Column widths (Excel character units) |
+| `Hidden columns: E, F` | Columns hidden in the spreadsheet |
+| `Merged: A1:B1` | Merged cell ranges |
+| `Auto-filter: A1:D20` | Active auto-filter range |
+| `Print area: A1:D50` | Defined print area |
+| `Named ranges:` | Workbook-defined names referencing this sheet |
+| `Table: "Name" A1:D20` | Excel Table objects with column headers |
+| `Image: A1 to C5` | Embedded image position |
+
+### Cell Tags
+
+| Tag | Meaning |
+|-----|---------|
+| `[formula: =SUM(A1:A10)]` | Cell contains this formula (master cell) |
+| `[shared formula ref: D2]` | Cell shares D2's formula (Excel "shared formula" — common when you drag-fill) |
+| `[numFmt: 0.00%]` | Number format (when not "General") |
+| `[bold]` | Bold font |
+| `[italic]` | Italic font |
+| `[color:FF8B0000]` | Font color (ARGB hex) |
+| `[fill:FFFFFF00]` | Cell background color (ARGB hex) |
+| `[align:center]` | Horizontal alignment (when not default) |
+| `[link: https://...]` | Hyperlink URL |
+| `[note: ...]` | Cell comment or note text |
+| `[validation: list [...]]` | Data validation (dropdown values or constraints) |
+| `[hidden]` | Row is hidden in the spreadsheet |
+
+### `--list-sheets` Output
+
+```
+Sales  250 rows × 12 cols
+Config  15 rows × 4 cols
+Archive  1200 rows × 8 cols [hidden]
+```
+
+## Cursor / Claude / Agent Rule Template
+
+Copy the included rule template into your project so your AI agent automatically uses this tool when it encounters `.xlsx` files:
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/xlsx-for-ai/cursor-rule-template/read-xlsx.mdc .cursor/rules/
+```
+
+Or fetch it directly:
+
+```bash
+mkdir -p .cursor/rules
+curl -o .cursor/rules/read-xlsx.mdc https://raw.githubusercontent.com/senoff/xlsx-for-ai/main/cursor-rule-template/read-xlsx.mdc
+```
+
+The same rule works for Claude Code (`.claude/rules/`), Copilot (`.github/copilot-instructions.md`), or any other agent — just adjust the path.
+
+## Why This Exists
+
+Spreadsheets are everywhere in real projects — financial models, data exports, config files, tax estimates. AI coding agents choke on binary formats. This tool makes spreadsheets legible to AI with zero information loss, including the tricky bits like shared formulas, named ranges, and merged cells that other tools drop.
+
+## License
+
+MIT

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

@@ -0,0 +1,50 @@
+---
+description: Reading .xlsx spreadsheet files
+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)
+
+## 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.
+- The package was previously named `cursor-reads-xlsx` — that command name still works as an alias.

package/index.js

@@ -0,0 +1,606 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs   = require('fs');
+const ExcelJS = require('exceljs');
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    positional: [],
+    listSheets: false,
+    stdout: false,
+    json: false,
+    compact: false,
+    maxRows: null,
+    maxCols: null,
+    help: false,
+  };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--list-sheets')       opts.listSheets = true;
+    else if (arg === '--stdout')       opts.stdout = true;
+    else if (arg === '--json')         opts.json = true;
+    else if (arg === '--compact')      opts.compact = true;
+    else if (arg === '--max-rows')   { opts.maxRows = parseInt(argv[++i], 10); }
+    else if (arg === '--max-cols')   { opts.maxCols = parseInt(argv[++i], 10); }
+    else if (arg === '-h' || arg === '--help') opts.help = true;
+    else                               opts.positional.push(arg);
+    i++;
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`Usage: npx xlsx-for-ai <file.xlsx> [sheetName] [options]
+
+Converts .xlsx to rich text (or JSON) that AI coding agents can read.
+
+Options:
+  --list-sheets   List sheet names, dimensions, and visibility then exit
+  --stdout        Print output to stdout instead of writing files
+  --json          Emit structured JSON instead of the human-readable text dump
+                  (one object per cell with value/formula/format/style)
+  --compact       Suppress noisy default tags (default text color, default font,
+                  General number format, etc.) to reduce token usage
+  --max-rows N    Limit output to the first N rows per sheet
+  --max-cols N    Limit output to the first N columns per sheet
+  -h, --help      Show this help message
+
+Examples:
+  npx xlsx-for-ai data.xlsx
+  npx xlsx-for-ai data.xlsx "Sheet1"
+  npx xlsx-for-ai data.xlsx --list-sheets
+  npx xlsx-for-ai data.xlsx --stdout --max-rows 100
+  npx xlsx-for-ai data.xlsx --stdout --compact
+  npx xlsx-for-ai data.xlsx --json --stdout > out.json
+
+Note: this package was previously published as 'cursor-reads-xlsx';
+that command name still works as an alias.`);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function colLetter(n) {
+  let s = '';
+  for (; n > 0; n = Math.floor((n - 1) / 26))
+    s = String.fromCharCode(65 + ((n - 1) % 26)) + s;
+  return s;
+}
+
+// Colors that are visually indistinguishable from the default Excel text (near-black).
+// In --compact mode we suppress these to reduce token noise.
+const DEFAULT_TEXT_COLORS = new Set([
+  'FF000000', // pure black
+  'FF1F1F1F', // dark gray (Excel auto-text on some themes)
+  'FF222120', // dark gray variant
+  'FF333333',
+]);
+
+function isDefaultTextColor(argb) {
+  return argb && DEFAULT_TEXT_COLORS.has(argb.toUpperCase());
+}
+
+function describeFill(fill, compact) {
+  if (!fill || (fill.type === 'pattern' && fill.pattern === 'none')) return null;
+  if (fill.type === 'pattern' && fill.fgColor?.argb) {
+    // White / no-fill patterns are noise in compact mode
+    if (compact && /^FF?FFFFFF$/i.test(fill.fgColor.argb)) return null;
+    return `fill:${fill.fgColor.argb}`;
+  }
+  return null;
+}
+
+function describeFont(font, compact) {
+  const parts = [];
+  if (font?.bold)   parts.push('bold');
+  if (font?.italic) parts.push('italic');
+  if (font?.color?.argb) {
+    if (!(compact && isDefaultTextColor(font.color.argb))) {
+      parts.push(`color:${font.color.argb}`);
+    }
+  }
+  return parts;
+}
+
+function formatValue(v) {
+  if (v == null) return '""';
+  if (v instanceof Date) return `"${v.toISOString().slice(0, 10)}"`;
+  if (typeof v === 'object' && v.richText) {
+    return `"${v.richText.map(r => r.text).join('')}"`;
+  }
+  if (typeof v === 'object' && v.hyperlink) {
+    return `"${v.text || v.hyperlink}"`;
+  }
+  // Formula cells: 'formula' on master, 'sharedFormula' on follow-ups, 'result' is the computed value
+  if (typeof v === 'object' && (v.formula || v.sharedFormula)) {
+    const result = v.result;
+    if (result == null) return '""';
+    // Result may itself be a rich object (error, richText, etc.)
+    if (typeof result === 'object') {
+      if (result.error) return `"#${result.error}"`;
+      if (result.richText) return `"${result.richText.map(r => r.text).join('')}"`;
+      return JSON.stringify(result);
+    }
+    if (typeof result === 'string') return `"${result}"`;
+    return String(result);
+  }
+  if (typeof v === 'object' && v.error) return `"#${v.error}"`;
+  if (typeof v === 'string') return `"${v}"`;
+  return String(v);
+}
+
+function describeNote(note) {
+  if (!note) return null;
+  if (typeof note === 'string') return note;
+  if (note.texts) {
+    return note.texts.map(t => (typeof t === 'string' ? t : t.text || '')).join('');
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Named ranges (workbook-level, filtered to a sheet if name provided)
+// ---------------------------------------------------------------------------
+
+function getNamedRanges(wb, sheetName) {
+  const results = [];
+  try {
+    const model = wb.definedNames?.model;
+    if (!Array.isArray(model)) return results;
+    for (const def of model) {
+      if (!def.ranges?.length) continue;
+      if (sheetName) {
+        const relevant = def.ranges.filter(r => r.includes(sheetName + '!'));
+        if (relevant.length) results.push({ name: def.name, ranges: relevant });
+      } else {
+        results.push({ name: def.name, ranges: def.ranges });
+      }
+    }
+  } catch (_) {}
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Sheet dump
+// ---------------------------------------------------------------------------
+
+function dumpSheet(ws, wb, opts = {}) {
+  const { maxRows = null, maxCols = null, compact = false } = opts;
+  const lines = [];
+
+  lines.push(`=== Sheet: ${ws.name} ===`);
+
+  // Frozen panes
+  const views = ws.views || [];
+  const frozen = views.find(v => v.state === 'frozen');
+  if (frozen) {
+    lines.push(`Frozen: row ${frozen.ySplit ?? 0}, col ${frozen.xSplit ?? 0}`);
+  }
+
+  // Column widths + hidden columns
+  const totalCols = maxCols ? Math.min(ws.columnCount, maxCols) : ws.columnCount;
+  const colWidths = [];
+  const hiddenCols = [];
+  for (let c = 1; c <= totalCols; c++) {
+    const col = ws.getColumn(c);
+    const letter = colLetter(c);
+    if (col.hidden) hiddenCols.push(letter);
+    if (col.width) colWidths.push(`${letter}(${Math.round(col.width)})`);
+  }
+  if (colWidths.length) lines.push(`Columns: ${colWidths.join(' ')}`);
+  if (hiddenCols.length) lines.push(`Hidden columns: ${hiddenCols.join(', ')}`);
+  if (maxCols && ws.columnCount > maxCols) {
+    lines.push(`(${ws.columnCount - maxCols} more columns truncated at --max-cols ${maxCols})`);
+  }
+
+  // Merged cells
+  const merges = Object.keys(ws._merges || {});
+  if (merges.length) lines.push(`Merged: ${merges.join(', ')}`);
+
+  // Auto-filter
+  if (ws.autoFilter) {
+    const af = typeof ws.autoFilter === 'string'
+      ? ws.autoFilter
+      : (ws.autoFilter.ref || JSON.stringify(ws.autoFilter));
+    lines.push(`Auto-filter: ${af}`);
+  }
+
+  // Print area
+  try {
+    if (ws.pageSetup?.printArea) {
+      lines.push(`Print area: ${ws.pageSetup.printArea}`);
+    }
+  } catch (_) {}
+
+  // Named ranges relevant to this sheet
+  const namedRanges = getNamedRanges(wb, ws.name);
+  if (namedRanges.length) {
+    lines.push(`Named ranges:`);
+    for (const nr of namedRanges) {
+      lines.push(`  ${nr.name}: ${nr.ranges.join(', ')}`);
+    }
+  }
+
+  // Tables
+  try {
+    const tableMap = ws.tables;
+    if (tableMap && typeof tableMap === 'object') {
+      const tables = typeof tableMap.forEach === 'function'
+        ? (() => { const a = []; tableMap.forEach(t => a.push(t)); return a; })()
+        : Object.values(tableMap);
+      for (const t of tables) {
+        const model = t.table || t.model || t;
+        const name = model.name || model.displayName || '(unnamed)';
+        const ref = model.ref || model.tableRef || '';
+        const cols = (model.columns || []).map(c => c.name).filter(Boolean);
+        let desc = `Table: "${name}" ${ref}`;
+        if (cols.length) desc += ` — columns: ${cols.join(', ')}`;
+        lines.push(desc);
+      }
+    }
+  } catch (_) {}
+
+  // Images
+  try {
+    const images = typeof ws.getImages === 'function' ? ws.getImages() : [];
+    for (const img of images) {
+      if (img.range) {
+        const tl = img.range.tl;
+        const br = img.range.br;
+        if (tl && br) {
+          lines.push(`Image: ${colLetter(Math.floor(tl.col) + 1)}${Math.floor(tl.row) + 1} to ${colLetter(Math.floor(br.col) + 1)}${Math.floor(br.row) + 1}`);
+        } else if (tl) {
+          lines.push(`Image at: ${colLetter(Math.floor(tl.col) + 1)}${Math.floor(tl.row) + 1}`);
+        }
+      } else {
+        lines.push(`Image: (position unknown)`);
+      }
+    }
+  } catch (_) {}
+
+  lines.push('');
+
+  // Rows
+  const rowLimit = maxRows ? Math.min(ws.rowCount, maxRows) : ws.rowCount;
+
+  for (let r = 1; r <= rowLimit; r++) {
+    const row = ws.getRow(r);
+    const cells = [];
+    const isHidden = row.hidden;
+
+    for (let c = 1; c <= totalCols; c++) {
+      const cell = row.getCell(c);
+      const raw = cell.value;
+      if (raw == null || raw === '') continue;
+
+      const ref = `${colLetter(c)}${r}`;
+      const tags = [];
+
+      // Formula (handle both standalone and shared formulas)
+      if (cell.type === ExcelJS.ValueType.Formula) {
+        if (typeof raw === 'object') {
+          if (raw.formula) {
+            tags.push(`formula: =${raw.formula}`);
+          } else if (raw.sharedFormula) {
+            tags.push(`shared formula ref: ${raw.sharedFormula}`);
+          }
+        }
+      }
+
+      // Number format
+      if (cell.numFmt && cell.numFmt !== 'General') {
+        tags.push(`numFmt: ${cell.numFmt}`);
+      }
+
+      // Font
+      const fontTags = describeFont(cell.font, compact);
+      if (fontTags.length) tags.push(...fontTags);
+
+      // Fill
+      const fillDesc = describeFill(cell.fill, compact);
+      if (fillDesc) tags.push(fillDesc);
+
+      // Alignment
+      if (cell.alignment?.horizontal && cell.alignment.horizontal !== 'general') {
+        tags.push(`align:${cell.alignment.horizontal}`);
+      }
+
+      // Hyperlink
+      if (cell.hyperlink) {
+        tags.push(`link: ${cell.hyperlink}`);
+      } else if (typeof raw === 'object' && raw.hyperlink) {
+        tags.push(`link: ${raw.hyperlink}`);
+      }
+
+      // Comment / note
+      const noteText = describeNote(cell.note);
+      if (noteText) {
+        tags.push(`note: ${noteText.replace(/\n/g, ' ').trim()}`);
+      }
+
+      // Data validation
+      if (cell.dataValidation) {
+        const dv = cell.dataValidation;
+        if (dv.type === 'list' && dv.formulae?.length) {
+          tags.push(`validation: list [${dv.formulae[0]}]`);
+        } else if (dv.type) {
+          const parts = [dv.type];
+          if (dv.operator) parts.push(dv.operator);
+          if (dv.formulae?.length) parts.push(dv.formulae.join(', '));
+          tags.push(`validation: ${parts.join(' ')}`);
+        }
+      }
+
+      const displayVal = formatValue(raw);
+      const tagStr = tags.length ? `  [${tags.join('] [')}]` : '';
+      cells.push(`  ${ref}: ${displayVal}${tagStr}`);
+    }
+
+    if (cells.length === 0) {
+      const hiddenTag = isHidden ? ' [hidden]' : '';
+      lines.push(`--- Row ${r} (empty)${hiddenTag} ---`);
+    } else {
+      const rowBold = row.font?.bold ? ' [bold]' : '';
+      const hiddenTag = isHidden ? ' [hidden]' : '';
+      lines.push(`--- Row ${r}${rowBold}${hiddenTag} ---`);
+      lines.push(...cells);
+    }
+  }
+
+  if (maxRows && ws.rowCount > maxRows) {
+    lines.push('');
+    lines.push(`... ${ws.rowCount - maxRows} more rows (truncated at --max-rows ${maxRows})`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// JSON dump (structured per-cell output)
+// ---------------------------------------------------------------------------
+
+function jsonValue(v) {
+  if (v == null) return null;
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === 'object') {
+    if (v.richText) return v.richText.map(r => r.text).join('');
+    if (v.hyperlink) return { text: v.text || v.hyperlink, hyperlink: v.hyperlink };
+    if (v.formula || v.sharedFormula) {
+      const out = {};
+      if (v.formula) out.formula = v.formula;
+      if (v.sharedFormula) out.sharedFormulaRef = v.sharedFormula;
+      const result = v.result;
+      if (result == null) {
+        out.result = null;
+      } else if (typeof result === 'object') {
+        if (result.error) out.result = `#${result.error}`;
+        else if (result.richText) out.result = result.richText.map(r => r.text).join('');
+        else out.result = result;
+      } else {
+        out.result = result;
+      }
+      return out;
+    }
+    if (v.error) return `#${v.error}`;
+  }
+  return v;
+}
+
+function dumpSheetJSON(ws, wb, opts = {}) {
+  const { maxRows = null, maxCols = null } = opts;
+  const totalCols = maxCols ? Math.min(ws.columnCount, maxCols) : ws.columnCount;
+  const rowLimit = maxRows ? Math.min(ws.rowCount, maxRows) : ws.rowCount;
+
+  const out = {
+    name: ws.name,
+    state: ws.state || 'visible',
+    rowCount: ws.rowCount,
+    columnCount: ws.columnCount,
+    truncated: {
+      rows: maxRows && ws.rowCount > maxRows ? ws.rowCount - maxRows : 0,
+      cols: maxCols && ws.columnCount > maxCols ? ws.columnCount - maxCols : 0,
+    },
+    frozen: null,
+    columns: [],
+    hiddenColumns: [],
+    merges: Object.keys(ws._merges || {}),
+    autoFilter: null,
+    printArea: null,
+    namedRanges: getNamedRanges(wb, ws.name),
+    tables: [],
+    images: [],
+    cells: [],
+  };
+
+  // Frozen panes
+  const frozen = (ws.views || []).find(v => v.state === 'frozen');
+  if (frozen) out.frozen = { rowSplit: frozen.ySplit ?? 0, colSplit: frozen.xSplit ?? 0 };
+
+  // Columns
+  for (let c = 1; c <= totalCols; c++) {
+    const col = ws.getColumn(c);
+    const letter = colLetter(c);
+    if (col.hidden) out.hiddenColumns.push(letter);
+    out.columns.push({ letter, width: col.width || null, hidden: !!col.hidden });
+  }
+
+  // Auto-filter
+  if (ws.autoFilter) {
+    out.autoFilter = typeof ws.autoFilter === 'string'
+      ? ws.autoFilter
+      : (ws.autoFilter.ref || null);
+  }
+
+  // Print area
+  try { if (ws.pageSetup?.printArea) out.printArea = ws.pageSetup.printArea; } catch (_) {}
+
+  // Tables
+  try {
+    const tableMap = ws.tables;
+    if (tableMap && typeof tableMap === 'object') {
+      const tables = typeof tableMap.forEach === 'function'
+        ? (() => { const a = []; tableMap.forEach(t => a.push(t)); return a; })()
+        : Object.values(tableMap);
+      for (const t of tables) {
+        const model = t.table || t.model || t;
+        out.tables.push({
+          name: model.name || model.displayName || null,
+          ref: model.ref || model.tableRef || null,
+          columns: (model.columns || []).map(c => c.name).filter(Boolean),
+        });
+      }
+    }
+  } catch (_) {}
+
+  // Images
+  try {
+    const images = typeof ws.getImages === 'function' ? ws.getImages() : [];
+    for (const img of images) {
+      if (img.range) {
+        const tl = img.range.tl, br = img.range.br;
+        out.images.push({
+          tl: tl ? `${colLetter(Math.floor(tl.col) + 1)}${Math.floor(tl.row) + 1}` : null,
+          br: br ? `${colLetter(Math.floor(br.col) + 1)}${Math.floor(br.row) + 1}` : null,
+        });
+      }
+    }
+  } catch (_) {}
+
+  // Cells
+  for (let r = 1; r <= rowLimit; r++) {
+    const row = ws.getRow(r);
+    for (let c = 1; c <= totalCols; c++) {
+      const cell = row.getCell(c);
+      const raw = cell.value;
+      if (raw == null || raw === '') continue;
+
+      const entry = {
+        ref: `${colLetter(c)}${r}`,
+        row: r,
+        col: c,
+        value: jsonValue(raw),
+      };
+      if (cell.numFmt && cell.numFmt !== 'General') entry.numFmt = cell.numFmt;
+      if (cell.font?.bold) entry.bold = true;
+      if (cell.font?.italic) entry.italic = true;
+      if (cell.font?.color?.argb) entry.color = cell.font.color.argb;
+      if (cell.fill?.type === 'pattern' && cell.fill.fgColor?.argb) entry.fill = cell.fill.fgColor.argb;
+      if (cell.alignment?.horizontal && cell.alignment.horizontal !== 'general') entry.align = cell.alignment.horizontal;
+      if (cell.hyperlink) entry.hyperlink = cell.hyperlink;
+      if (cell.note) entry.note = describeNote(cell.note);
+      if (cell.dataValidation) entry.dataValidation = cell.dataValidation;
+      if (row.hidden) entry.rowHidden = true;
+      out.cells.push(entry);
+    }
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// List sheets mode
+// ---------------------------------------------------------------------------
+
+function listSheets(wb) {
+  const lines = [];
+  for (const ws of wb.worksheets) {
+    const vis = ws.state === 'hidden' ? ' [hidden]'
+              : ws.state === 'veryHidden' ? ' [very hidden]'
+              : '';
+    lines.push(`${ws.name}  ${ws.rowCount} rows × ${ws.columnCount} cols${vis}`);
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) { printHelp(); process.exit(0); }
+  if (opts.positional.length < 1) { printHelp(); process.exit(1); }
+
+  const xlsxPath = path.resolve(opts.positional[0]);
+  const sheetFilter = opts.positional[1] || null;
+
+  if (!fs.existsSync(xlsxPath)) {
+    console.error(`File not found: ${xlsxPath}`);
+    process.exit(1);
+  }
+
+  const wb = new ExcelJS.Workbook();
+  await wb.xlsx.readFile(xlsxPath);
+
+  // --list-sheets: print summary and exit
+  if (opts.listSheets) {
+    console.log(listSheets(wb));
+    process.exit(0);
+  }
+
+  const sheets = sheetFilter
+    ? [wb.getWorksheet(sheetFilter)].filter(Boolean)
+    : wb.worksheets;
+
+  if (sheets.length === 0) {
+    console.error(sheetFilter
+      ? `Sheet "${sheetFilter}" not found. Available: ${wb.worksheets.map(s => s.name).join(', ')}`
+      : 'No sheets in workbook');
+    process.exit(1);
+  }
+
+  const baseName = path.basename(xlsxPath, path.extname(xlsxPath));
+
+  const dumpOpts = { maxRows: opts.maxRows, maxCols: opts.maxCols, compact: opts.compact };
+
+  // --json mode: structured per-cell output
+  if (opts.json) {
+    const payload = sheets.map(ws => dumpSheetJSON(ws, wb, dumpOpts));
+    const json = JSON.stringify(sheets.length === 1 ? payload[0] : payload, null, 2);
+
+    if (opts.stdout) {
+      process.stdout.write(json + '\n');
+      process.exit(0);
+    }
+    const outDir = path.join(process.cwd(), '.xlsx-read');
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, `${baseName}.json`);
+    fs.writeFileSync(outFile, json, 'utf8');
+    console.log(outFile);
+    process.exit(0);
+  }
+
+  // --stdout: print text dump to console
+  if (opts.stdout) {
+    for (const ws of sheets) {
+      console.log(dumpSheet(ws, wb, dumpOpts));
+      console.log('');
+    }
+    process.exit(0);
+  }
+
+  // Default: write text dump to .xlsx-read/ files
+  const outDir = path.join(process.cwd(), '.xlsx-read');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  for (const ws of sheets) {
+    const content = dumpSheet(ws, wb, dumpOpts);
+    const safeName = ws.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const outFile = path.join(outDir, `${baseName}--${safeName}.txt`);
+    fs.writeFileSync(outFile, content, 'utf8');
+    console.log(outFile);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "xlsx-for-ai",
+  "version": "1.1.0",
+  "description": "CLI that converts .xlsx files into rich text or JSON dumps that AI coding agents (Claude, Cursor, Copilot, ChatGPT, etc.) can read — preserving values, formulas, formatting, colors, column widths, frozen panes, named ranges, tables, and more.",
+  "main": "index.js",
+  "bin": {
+    "xlsx-for-ai": "index.js",
+    "cursor-reads-xlsx": "index.js"
+  },
+  "files": [
+    "index.js",
+    "cursor-rule-template",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "xlsx",
+    "excel",
+    "ai",
+    "claude",
+    "cursor",
+    "copilot",
+    "chatgpt",
+    "llm",
+    "agent",
+    "cli",
+    "spreadsheet",
+    "text",
+    "json",
+    "converter",
+    "ai-readable"
+  ],
+  "author": "senoff",
+  "license": "MIT",
+  "homepage": "https://github.com/senoff/xlsx-for-ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/senoff/xlsx-for-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/senoff/xlsx-for-ai/issues"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  }
+}