cursor-reads-xlsx 1.0.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,158 @@
+# cursor-reads-xlsx
+
+Converts `.xlsx` files into rich text dumps that AI coding agents can actually read.
+
+AI tools like Cursor, Claude, Copilot, etc. 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:
+
+- **Values** — strings, numbers, dates
+- **Formulas** — the actual formula expression, not just the result
+- **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
+
+## Install
+
+```bash
+npm install -g cursor-reads-xlsx
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx cursor-reads-xlsx budget.xlsx
+```
+
+## Usage
+
+```bash
+# Dump all sheets
+npx cursor-reads-xlsx data.xlsx
+
+# Dump a specific sheet
+npx cursor-reads-xlsx data.xlsx "Sheet1"
+
+# List sheet names and dimensions without dumping
+npx cursor-reads-xlsx data.xlsx --list-sheets
+
+# Print to stdout instead of writing files
+npx cursor-reads-xlsx data.xlsx --stdout
+
+# Limit to first 200 rows per sheet (useful for huge files)
+npx cursor-reads-xlsx data.xlsx --max-rows 200
+
+# Combine flags
+npx cursor-reads-xlsx data.xlsx "Sheet1" --stdout --max-rows 50
+```
+
+### 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 |
+| `--max-rows N` | Cap output at the first N rows 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
+
+```
+=== 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  [formula: =B3+C3] [numFmt: #,##0]
+--- Row 4 (empty) [hidden] ---
+```
+
+### 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 |
+| `[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 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/cursor-reads-xlsx/cursor-rule-template/read-xlsx.mdc .cursor/rules/
+```
+
+Or if you installed globally / use npx, copy the template from the repo:
+
+```bash
+mkdir -p .cursor/rules
+curl -o .cursor/rules/read-xlsx.mdc https://raw.githubusercontent.com/senoff/cursor-reads-xlsx/main/cursor-rule-template/read-xlsx.mdc
+```
+
+## Why This Exists
+
+Spreadsheets are everywhere in real projects — financial models, data exports, config files. AI coding agents choke on binary formats. This tool makes spreadsheets legible to AI with zero information loss.
+
+## License
+
+MIT

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

@@ -0,0 +1,46 @@
+---
+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 cursor-reads-xlsx <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)]` if the cell has one
+     - **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
+- `--max-rows N` — limit output to first N rows (use for large 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` or request a single sheet to keep output manageable.

package/index.js

@@ -0,0 +1,381 @@
+#!/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, maxRows: 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 === '--max-rows')   { opts.maxRows = 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 cursor-reads-xlsx <file.xlsx> [sheetName] [options]
+
+Converts .xlsx to rich text 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
+  --max-rows N    Limit output to the first N rows per sheet
+  -h, --help      Show this help message
+
+Examples:
+  npx cursor-reads-xlsx data.xlsx
+  npx cursor-reads-xlsx data.xlsx "Sheet1"
+  npx cursor-reads-xlsx data.xlsx --list-sheets
+  npx cursor-reads-xlsx data.xlsx --stdout --max-rows 100`);
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+function describeFill(fill) {
+  if (!fill || (fill.type === 'pattern' && fill.pattern === 'none')) return null;
+  if (fill.type === 'pattern' && fill.fgColor?.argb) return `fill:${fill.fgColor.argb}`;
+  return null;
+}
+
+function describeFont(font) {
+  const parts = [];
+  if (font?.bold)   parts.push('bold');
+  if (font?.italic) parts.push('italic');
+  if (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}"`;
+  }
+  if (typeof v === 'object' && v.formula) {
+    return String(v.result ?? '');
+  }
+  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, maxRows) {
+  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 colWidths = [];
+  const hiddenCols = [];
+  for (let c = 1; c <= ws.columnCount; 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(', ')}`);
+
+  // 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 <= ws.columnCount; c++) {
+      const cell = row.getCell(c);
+      const raw = cell.value;
+      if (raw == null || raw === '') continue;
+
+      const ref = `${colLetter(c)}${r}`;
+      const tags = [];
+
+      // Formula
+      if (cell.type === ExcelJS.ValueType.Formula) {
+        const formula = typeof raw === 'object' ? raw.formula : null;
+        if (formula) tags.push(`formula: =${formula}`);
+      }
+
+      // Number format
+      if (cell.numFmt && cell.numFmt !== 'General') {
+        tags.push(`numFmt: ${cell.numFmt}`);
+      }
+
+      // Font
+      const fontTags = describeFont(cell.font);
+      if (fontTags.length) tags.push(...fontTags);
+
+      // Fill
+      const fillDesc = describeFill(cell.fill);
+      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');
+}
+
+// ---------------------------------------------------------------------------
+// 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));
+
+  // --stdout: print to console
+  if (opts.stdout) {
+    for (const ws of sheets) {
+      console.log(dumpSheet(ws, wb, opts.maxRows));
+      console.log('');
+    }
+    process.exit(0);
+  }
+
+  // Default: write 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, opts.maxRows);
+    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,30 @@
+{
+  "name": "cursor-reads-xlsx",
+  "version": "1.0.0",
+  "description": "Converts .xlsx files into rich text dumps that AI coding agents (Cursor, Claude, etc.) can read — preserving values, formulas, formatting, colors, column widths, and frozen panes.",
+  "main": "index.js",
+  "bin": {
+    "cursor-reads-xlsx": "index.js"
+  },
+  "files": [
+    "index.js",
+    "cursor-rule-template",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "xlsx",
+    "excel",
+    "cursor",
+    "ai",
+    "cli",
+    "spreadsheet",
+    "text",
+    "converter"
+  ],
+  "author": "senoff",
+  "license": "MIT",
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  }
+}