xlsx-for-ai 1.5.0 → 1.5.1

package/README.md

@@ -94,6 +94,7 @@ npx xlsx-for-ai data.xlsx "Sheet1" --stdout --max-rows 50 --compact
 | `[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 |
+| `--region` | Auto-detect the dominant contiguous data block (Excel "current region" / Ctrl+Shift+*). Picks the largest region by populated-cell count when multiple disjoint blocks exist. Compatible with `--max-rows` / `--max-cols`. |
 | `--max-rows N` | Cap at the first N rows per sheet |
 | `--max-cols N` | Cap at the first N columns per sheet |
 
@@ -318,7 +319,22 @@ A future release may apply these dep upgrades via `patch-package` so they travel
 
 ## Reporting bugs
 
-**The privacy contract: we never auto-send your data.** xlsx-for-ai has no telemetry endpoint and no consent dialog to maintain — there's nothing to opt out of, because nothing leaves your machine unless you choose to attach it to a GitHub issue.
+**The privacy contract: we never auto-send workbook data.** Anonymous crash telemetry is opt-in via `--enable-telemetry`; even then, we receive only error type, error message (sanitized — paths scrubbed, capped at 200 chars), tool version, Node version, and OS/arch. No paths, no cell values, no identifiers.
+
+To enable or manage crash telemetry:
+
+```bash
+# Opt in — prints the exact payload schema so you can see what gets sent
+xlsx-for-ai --enable-telemetry
+
+# Opt out
+xlsx-for-ai --disable-telemetry
+
+# Check current state and config path
+xlsx-for-ai --telemetry-status
+```
+
+Consent is stored at `~/.xlsx-for-ai/config.json` and persists across `npm install -g xlsx-for-ai@latest` upgrades. If the telemetry shape ever changes, the tool pauses sending and prompts you to re-opt-in — we never silently expand what we collect under old consent.
 
 When something breaks on a real workbook, two flags help us reproduce locally without asking you to share the original file:
 

package/WHY.md

@@ -92,3 +92,7 @@ Spreadsheet libraries are designed for developers building software *on top of*
 `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, and a real `.xlsx` writer that produces a file you can hand back to a human along with a built-in note explaining everything that changed.
 
 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.
+
+## Privacy contract
+
+We never auto-send workbook data. Anonymous crash telemetry is opt-in via `xlsx-for-ai --enable-telemetry`; even then, we receive only error type, error message (sanitized — paths scrubbed, capped at 200 chars), and tool/Node/OS version — no paths, no cell values, no identifiers. Nothing leaves your machine unless you choose to enable it.

package/index.js

@@ -22,10 +22,11 @@ if (!process.env.XLSX_FOR_AI_RESPAWNED) {
 const path = require('path');
 const fs   = require('fs');
 // All xlsx-engine access goes through the engine abstraction in lib/engine.js
-// — never require the underlying engine directly. To swap engines (fork,
-// different library, server-side service), replace lib/engine.js. Nothing
-// else changes. Current engine: @protobi/exceljs (drop-in fork of exceljs
-// with active maintenance + preservation patches; see ROADMAP for rationale).
+// — lib/engine.js is the ONLY place in lib/ that requires @protobi/exceljs.
+// To swap engines (fork, different library, server-side service), replace
+// lib/engine.js; nothing else changes. Current engine: @protobi/exceljs
+// (drop-in fork of exceljs with active maintenance + preservation patches;
+// see ROADMAP for rationale).
 const engine = require('./lib/engine');
 
 // Lazy-load heavy deps only when their feature is used (keeps cold start fast
@@ -55,12 +56,16 @@ function parseArgs(argv) {
     diff: null,
     range: null,
     namedRange: null,
+    region: false,
     maxRows: null,
     maxCols: null,
     maxTokens: null,
     reportBug: null,
     exportRedactedWorkbook: null,
     help: false,
+    enableTelemetry: false,
+    disableTelemetry: false,
+    telemetryStatus: false,
   };
   let i = 0;
   while (i < argv.length) {
@@ -77,11 +82,15 @@ function parseArgs(argv) {
     else if (arg === '--diff')        { opts.diff = argv[++i]; }
     else if (arg === '--range')       { opts.range = argv[++i]; }
     else if (arg === '--named-range') { opts.namedRange = argv[++i]; }
+    else if (arg === '--region')       opts.region = 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 === '--max-tokens')  { opts.maxTokens = parseInt(argv[++i], 10); }
     else if (arg === '--report-bug')              { opts.reportBug = argv[++i]; }
     else if (arg === '--export-redacted-workbook'){ opts.exportRedactedWorkbook = argv[++i]; }
+    else if (arg === '--enable-telemetry')        opts.enableTelemetry = true;
+    else if (arg === '--disable-telemetry')       opts.disableTelemetry = true;
+    else if (arg === '--telemetry-status')        opts.telemetryStatus = true;
     else if (arg === '-h' || arg === '--help') opts.help = true;
     else                                opts.positional.push(arg);
     i++;
@@ -111,6 +120,10 @@ Selection:
   [sheetName]       Positional second arg, dump only this sheet
   --range A1:D50    Dump only this rectangular range
   --named-range NM  Dump only the cells covered by this defined name
+  --region          Auto-detect the dominant contiguous data block (Excel
+                    "current region" semantics); picks the largest region
+                    by populated-cell count when multiple disjoint blocks
+                    exist. Compatible with --max-rows / --max-cols.
   --max-rows N      Limit to first N rows per sheet
   --max-cols N      Limit to first N columns per sheet
 
@@ -141,6 +154,21 @@ Bug reporting (privacy-by-design — no data leaves your machine):
                     structure, styles, named ranges preserved. Optional
                     attachment for hard-to-repro bugs.
 
+Crash telemetry (opt-in only):
+  --enable-telemetry
+                    Opt in to anonymous crash telemetry. Only error type,
+                    sanitized error message (paths scrubbed, ≤200 chars),
+                    tool version, Node version, and OS/arch are sent.
+                    No paths, no cell values, no identifiers.
+                    Payload: { v, ts, error_type, error_message, command,
+                               xlsx_for_ai_version, node_version, os_arch }
+                    Consent persists at ~/.xlsx-for-ai/config.json across
+                    upgrades.
+  --disable-telemetry
+                    Opt out. Config file is kept (explicit "no" is recorded).
+  --telemetry-status
+                    Show current state and config path.
+
 Misc:
   -h, --help        Show this help
 
@@ -150,6 +178,8 @@ Examples:
   npx xlsx-for-ai data.xlsx --json --max-tokens 8000 --stdout
   npx xlsx-for-ai data.csv --md --stdout
   npx xlsx-for-ai data.xlsx --range B2:F100 --stdout
+  npx xlsx-for-ai data.xlsx --region --stdout
+  npx xlsx-for-ai data.xlsx --region --max-rows 50 --stdout
   npx xlsx-for-ai data.xlsx --named-range MyTotals --stdout
   npx xlsx-for-ai data.xlsx --sql --stdout > schema.sql
   npx xlsx-for-ai old.xlsx --diff new.xlsx --stdout
@@ -325,6 +355,103 @@ function resolveNamedRange(wb, name) {
   return { sheet: sheetName, range: parseRange(rangeStr) };
 }
 
+// ---------------------------------------------------------------------------
+// Region detection — "current region" semantics (Excel Ctrl+Shift+*)
+//
+// Finds the dominant contiguous data block on a worksheet. Algorithm:
+//   1. Scan the sheet to collect all populated cells.
+//   2. Build connected components using 8-neighbor flood fill (cells that
+//      share a corner or edge are in the same region).
+//   3. For each component, compute the bounding rectangle and the count of
+//      populated cells inside it.
+//   4. Return the bounding box of the component with the most populated cells
+//      (tie-break: largest populated count; if still tied, the first found).
+//
+// Returns {startRow, startCol, endRow, endCol} (1-indexed), or null if the
+// sheet has no populated cells.
+// ---------------------------------------------------------------------------
+
+function detectRegion(ws) {
+  // Step 1: collect all populated cells into a Set for O(1) lookup.
+  // We store them as "row,col" strings and also keep a list for iteration.
+  const populated = new Set();
+  const cells = [];
+
+  const rowCount = ws.rowCount;
+  const colCount = ws.columnCount;
+  if (rowCount === 0 || colCount === 0) return null;
+
+  for (let r = 1; r <= rowCount; r++) {
+    const row = ws.getRow(r);
+    for (let c = 1; c <= colCount; c++) {
+      const v = row.getCell(c).value;
+      if (v != null && v !== '') {
+        const key = `${r},${c}`;
+        populated.add(key);
+        cells.push([r, c]);
+      }
+    }
+  }
+
+  if (cells.length === 0) return null;
+
+  // Step 2: flood-fill connected components (8-neighbor).
+  const visited = new Set();
+  const components = [];
+
+  for (const [startR, startC] of cells) {
+    const key = `${startR},${startC}`;
+    if (visited.has(key)) continue;
+
+    // BFS from this seed cell.
+    const component = [];
+    const queue = [[startR, startC]];
+    visited.add(key);
+
+    while (queue.length > 0) {
+      const [r, c] = queue.shift();
+      component.push([r, c]);
+      // 8 neighbors
+      for (let dr = -1; dr <= 1; dr++) {
+        for (let dc = -1; dc <= 1; dc++) {
+          if (dr === 0 && dc === 0) continue;
+          const nr = r + dr;
+          const nc = c + dc;
+          if (nr < 1 || nc < 1) continue;
+          const nk = `${nr},${nc}`;
+          if (!visited.has(nk) && populated.has(nk)) {
+            visited.add(nk);
+            queue.push([nr, nc]);
+          }
+        }
+      }
+    }
+    components.push(component);
+  }
+
+  // Step 3: pick the component with the most populated cells.
+  let best = null;
+  let bestCount = -1;
+  for (const comp of components) {
+    if (comp.length > bestCount) {
+      bestCount = comp.length;
+      best = comp;
+    }
+  }
+
+  // Step 4: compute bounding rectangle of the winning component.
+  let minR = Infinity, maxR = -Infinity;
+  let minC = Infinity, maxC = -Infinity;
+  for (const [r, c] of best) {
+    if (r < minR) minR = r;
+    if (r > maxR) maxR = r;
+    if (c < minC) minC = c;
+    if (c > maxC) maxC = c;
+  }
+
+  return { startRow: minR, endRow: maxR, startCol: minC, endCol: maxC };
+}
+
 // ---------------------------------------------------------------------------
 // Selection bounds — combines --range, --named-range, --max-rows/cols, sheet
 // dimensions into a single {startRow, startCol, endRow, endCol}.
@@ -336,6 +463,9 @@ function selectionBounds(ws, opts) {
     bounds = parseRange(opts.range);
   } else if (opts.namedRangeBounds) {
     bounds = opts.namedRangeBounds;
+  } else if (opts.region) {
+    bounds = detectRegion(ws);
+    // bounds may be null (empty sheet); handled below by falling back to sheet dimensions.
   }
   const startRow = bounds ? bounds.startRow : 1;
   const startCol = bounds ? bounds.startCol : 1;
@@ -1709,6 +1839,56 @@ async function main() {
 
   if (opts.help) { printHelp(); process.exit(0); }
 
+  // ---------------------------------------------------------------------------
+  // Telemetry management flags — handled before crash hooks are registered.
+  // ---------------------------------------------------------------------------
+  if (opts.enableTelemetry || opts.disableTelemetry || opts.telemetryStatus) {
+    const telCfg = require('./lib/telemetry-config');
+
+    if (opts.enableTelemetry) {
+      telCfg.enableTelemetry();
+      console.log('Crash telemetry enabled.');
+      console.log('');
+      console.log('When a crash occurs, this payload will be sent:');
+      console.log(JSON.stringify({
+        v: 1,
+        ts: '<ISO-timestamp>',
+        error_type: '<e.g. TypeError>',
+        error_message: '<sanitized, ≤200 chars — paths scrubbed>',
+        command: '<first CLI arg from allowlist, or "<other>">',
+        xlsx_for_ai_version: require('./package.json').version,
+        node_version: process.version,
+        os_arch: `${process.platform}-${process.arch}`,
+      }, null, 2));
+      console.log('');
+      console.log('No paths, no cell values, no identifiers. Consent stored at:');
+      console.log(telCfg.configPath());
+      return;
+    }
+
+    if (opts.disableTelemetry) {
+      telCfg.disableTelemetry();
+      console.log('Crash telemetry disabled.');
+      console.log('Config kept at: ' + telCfg.configPath());
+      return;
+    }
+
+    if (opts.telemetryStatus) {
+      const status = telCfg.telemetryStatus();
+      console.log(`Telemetry status: ${status}`);
+      console.log(`Config path:      ${telCfg.configPath()}`);
+      return;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Register process-level crash hooks (no-op if user hasn't opted in).
+  // ---------------------------------------------------------------------------
+  {
+    const { registerCrashHooks } = require('./lib/telemetry-hooks');
+    registerCrashHooks(require('./package.json').version);
+  }
+
   // Bug-report and redacted-workbook modes consume their input via the
   // flag itself, so they bypass the normal positional / loader path.
   if (opts.reportBug) {
@@ -1838,6 +2018,16 @@ async function main() {
 
   const baseName = path.basename(filePath, path.extname(filePath));
 
+  // --region: warn per-sheet if no data block was found (empty sheet).
+  if (opts.region) {
+    for (const ws of sheets) {
+      const r = detectRegion(ws);
+      if (!r) {
+        console.error(`note: --region: no data found in sheet "${ws.name}"; dumping full sheet dimensions.`);
+      }
+    }
+  }
+
   // Pick output formatter.
   const renderText  = (ws) => dumpSheet(ws, wb, perSheetOpts);
   const renderMd    = (ws) => dumpSheetMarkdown(ws, wb, perSheetOpts);
@@ -1965,4 +2155,7 @@ module.exports = {
   trySimpleEval,
   // budget
   applyTokenBudget,
+  // region detection
+  detectRegion,
+  selectionBounds,
 };

package/lib/bugReport.js

@@ -21,7 +21,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const JSZip = require('jszip');
-const ExcelJS = require('@protobi/exceljs');
+const engine = require('./engine');
 
 const PKG_VERSION = require('../package.json').version;
 
@@ -117,21 +117,6 @@ function inventoryFeatures(filenames) {
   return out;
 }
 
-// Given the workbook.xml, extract the sheet relationship Ids and order
-// without reading any user content. We just need names and rIds so we
-// can pair them with worksheet parts to compute per-sheet stats.
-function listSheetPartNames(zip) {
-  // Resolve via workbook rels: xl/_rels/workbook.xml.rels.
-  const out = [];
-  const relsFile = zip.file('xl/_rels/workbook.xml.rels');
-  if (!relsFile) return out;
-  // Sync — we already have the file in memory inside JSZip.
-  // We use a lightweight regex; structural only, no values inside.
-  // Each Relationship: <Relationship Id="rId1" Type="..." Target="worksheets/sheet1.xml"/>
-  // We can't do sync read without loading; caller already loaded.
-  return out;
-}
-
 async function generateBugReport(filePath) {
   if (!fs.existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
@@ -167,8 +152,7 @@ async function generateBugReport(filePath) {
   let exceljsError = null;
 
   try {
-    const wb = new ExcelJS.Workbook();
-    await wb.xlsx.readFile(filePath);
+    const wb = await engine.loadWorkbook(filePath);
     sheetCount = wb.worksheets.length;
     for (const ws of wb.worksheets) {
       const merges = ws.model && ws.model.merges ? ws.model.merges.length : 0;

package/lib/redactWorkbook.js

@@ -130,6 +130,75 @@ function redactThreadedCommentsXml(xml) {
   return xml.replace(/\btext="[^"]*"/g, 'text="x"');
 }
 
+// docProps/core.xml — strip author, title, subject, description, keywords,
+// category, lastModifiedBy, and any other user-text elements.
+// The timestamp elements (dcterms:created / dcterms:modified) and structural
+// elements (the xmlns declarations, DocSecurity, etc.) are left alone because
+// they're non-identifying metadata needed for round-trip fidelity.
+//
+// Elements scrubbed:
+//   dc:creator         → the file's original author name
+//   dc:title           → document title set by author
+//   dc:subject         → subject field
+//   dc:description     → description field
+//   cp:keywords        → keyword tags
+//   cp:category        → category field
+//   cp:lastModifiedBy  → last editor's name
+//   cp:contentStatus   → rarely set, but can contain user text
+const CORE_SCRUB_TAGS = [
+  'dc:creator',
+  'dc:title',
+  'dc:subject',
+  'dc:description',
+  'cp:keywords',
+  'cp:category',
+  'cp:lastModifiedBy',
+  'cp:contentStatus',
+];
+
+function redactCoreXml(xml) {
+  let out = xml;
+  for (const tag of CORE_SCRUB_TAGS) {
+    // Replace inner content: <dc:creator>...</dc:creator> → <dc:creator></dc:creator>
+    // Handles attributes on the opening tag and multi-line content.
+    out = out.replace(
+      new RegExp(`(<${tag}\\b[^>]*>)[\\s\\S]*?(<\\/${tag}>)`, 'g'),
+      '$1$2'
+    );
+  }
+  return out;
+}
+
+// docProps/app.xml — strip Company, Manager, and HyperlinkBase which can
+// contain user-identifying strings. The Application, AppVersion, DocSecurity,
+// HeadingPairs, and TitlesOfParts (sheet names) fields are structural and left
+// alone — sheet names are part of workbook structure, not cell values.
+const APP_SCRUB_TAGS = [
+  'Company',
+  'Manager',
+  'HyperlinkBase',
+];
+
+function redactAppXml(xml) {
+  let out = xml;
+  for (const tag of APP_SCRUB_TAGS) {
+    out = out.replace(
+      new RegExp(`(<${tag}\\b[^>]*>)[\\s\\S]*?(<\\/${tag}>)`, 'g'),
+      '$1$2'
+    );
+  }
+  return out;
+}
+
+// docProps/custom.xml — custom properties are arbitrary user-defined key/value
+// pairs. Strip the value payloads; keep the property names so the file remains
+// structurally valid.
+function redactCustomPropsXml(xml) {
+  // Custom property values live inside <vt:*> typed-value elements.
+  // Replace their inner text with empty string (preserves type nodes).
+  return xml.replace(/(<vt:[a-zA-Z]+\b[^>]*>)[^<]*(.*?)(<\/vt:[a-zA-Z]+>)/g, '$1$3');
+}
+
 async function exportRedactedWorkbook(inputPath, outputPath) {
   if (!fs.existsSync(inputPath)) {
     throw new Error(`File not found: ${inputPath}`);
@@ -160,6 +229,15 @@ async function exportRedactedWorkbook(inputPath, outputPath) {
     } else if (/^xl\/threadedComments\/threadedComment\d+\.xml$/i.test(name)) {
       const xml = await file.async('string');
       zip.file(name, redactThreadedCommentsXml(xml));
+    } else if (/^docProps\/core\.xml$/i.test(name)) {
+      const xml = await file.async('string');
+      zip.file(name, redactCoreXml(xml));
+    } else if (/^docProps\/app\.xml$/i.test(name)) {
+      const xml = await file.async('string');
+      zip.file(name, redactAppXml(xml));
+    } else if (/^docProps\/custom\.xml$/i.test(name)) {
+      const xml = await file.async('string');
+      zip.file(name, redactCustomPropsXml(xml));
     }
     // All other parts pass through untouched.
   }
@@ -180,4 +258,7 @@ module.exports = {
   // exported for unit testing
   _redactSheetXml: redactSheetXml,
   _redactSharedStringsXml: redactSharedStringsXml,
+  _redactCoreXml: redactCoreXml,
+  _redactAppXml: redactAppXml,
+  _redactCustomPropsXml: redactCustomPropsXml,
 };

package/lib/telemetry-config.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Persistent user-level telemetry config at ~/.xlsx-for-ai/config.json.
+ *
+ * Stored outside node_modules so consent survives `npm install -g xlsx-for-ai@latest`
+ * upgrades. Path is resolved via os.homedir() for cross-platform support.
+ *
+ * Config shape:
+ *   { "telemetry": true, "consented_at": "ISO-string", "consent_version": 1 }
+ *
+ * consent_version: bump CURRENT_CONSENT_VERSION when the telemetry shape changes.
+ * If the file's version is older, telemetry is PAUSED until the user re-runs
+ * --enable-telemetry. Never silently expand data shape under old consent.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const CURRENT_CONSENT_VERSION = 1;
+
+/**
+ * Return the path to the config file. Uses XFA_CONFIG_DIR env var for test
+ * isolation; otherwise defaults to ~/.xlsx-for-ai/config.json.
+ */
+function configDir() {
+  return process.env.XFA_CONFIG_DIR || path.join(os.homedir(), '.xlsx-for-ai');
+}
+
+function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+/**
+ * Read config from disk. Returns null if file doesn't exist or is unreadable.
+ */
+function readConfig() {
+  try {
+    const raw = fs.readFileSync(configPath(), 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Write config to disk atomically. Creates the directory if needed.
+ */
+function writeConfig(data) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Telemetry status as one of:
+ *   'enabled'                  - opt-in, consent_version matches
+ *   'disabled'                 - explicitly opted out
+ *   'not configured'           - no config file yet
+ *   'paused (consent_version mismatch)' - opted in but consent_version is stale
+ */
+function telemetryStatus() {
+  const cfg = readConfig();
+  if (!cfg) return 'not configured';
+  if (cfg.telemetry === false) return 'disabled';
+  if (cfg.telemetry === true) {
+    if (cfg.consent_version !== CURRENT_CONSENT_VERSION) {
+      return 'paused (consent_version mismatch)';
+    }
+    return 'enabled';
+  }
+  return 'not configured';
+}
+
+/**
+ * Returns true only if telemetry is fully active (opted in AND version matches).
+ */
+function isTelemetryActive() {
+  return telemetryStatus() === 'enabled';
+}
+
+/**
+ * Enable telemetry — write consent with current version.
+ * Idempotent.
+ */
+function enableTelemetry() {
+  const existing = readConfig() || {};
+  writeConfig({
+    ...existing,
+    telemetry: true,
+    consented_at: new Date().toISOString(),
+    consent_version: CURRENT_CONSENT_VERSION,
+  });
+}
+
+/**
+ * Disable telemetry — write explicit false (keeps the file so we can distinguish
+ * "user said no" from "never asked").
+ */
+function disableTelemetry() {
+  const existing = readConfig() || {};
+  writeConfig({ ...existing, telemetry: false });
+}
+
+module.exports = {
+  CURRENT_CONSENT_VERSION,
+  configPath,
+  readConfig,
+  writeConfig,
+  telemetryStatus,
+  isTelemetryActive,
+  enableTelemetry,
+  disableTelemetry,
+};

package/lib/telemetry-hooks.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Process-level crash telemetry hooks for xlsx-for-ai.
+ *
+ * Registers uncaughtException + unhandledRejection handlers only when the user
+ * has opted in (isTelemetryActive() === true). On crash, sends a minimal,
+ * sanitized payload and then re-throws the original error so the user still
+ * sees the stack trace and gets a non-zero exit code.
+ *
+ * Endpoint: XLSX_FOR_AI_TELEMETRY_ENDPOINT env var if set, else default below.
+ * // Endpoint deployment tracked separately — see project memory
+ * // project_xlsx_for_ai_telemetry_endpoint.md (TBD).
+ */
+
+const https  = require('https');
+const http   = require('http');
+const { URL } = require('url');
+
+const { isTelemetryActive, telemetryStatus } = require('./telemetry-config');
+const { buildPayload } = require('./telemetry-sanitize');
+
+const SEND_TIMEOUT_MS = 2000;
+
+// Endpoint deployment tracked separately — see project memory
+// project_xlsx_for_ai_telemetry_endpoint.md (TBD).
+const DEFAULT_ENDPOINT = 'https://telemetry.xlsx-for-ai.dev/v1/crash';
+
+function resolveEndpoint() {
+  return process.env.XLSX_FOR_AI_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT;
+}
+
+/**
+ * Send payload to the telemetry endpoint. Returns a Promise that:
+ *   - resolves on success (2xx)
+ *   - resolves (with a warning) on non-2xx or send failure
+ *   - resolves on timeout (after SEND_TIMEOUT_MS)
+ *
+ * The Promise ALWAYS resolves — never rejects. A hung send must not block exit.
+ */
+function sendPayload(payload) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify(payload);
+    const endpoint = resolveEndpoint();
+
+    let parsed;
+    try {
+      parsed = new URL(endpoint);
+    } catch (_) {
+      resolve();
+      return;
+    }
+
+    const transport = parsed.protocol === 'http:' ? http : https;
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'http:' ? 80 : 443),
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    };
+
+    const timer = setTimeout(() => {
+      try { req.destroy(); } catch (_) { /* ignore */ }
+      resolve();
+    }, SEND_TIMEOUT_MS);
+
+    const req = transport.request(options, (res) => {
+      clearTimeout(timer);
+      // Drain response body to free the socket.
+      res.resume();
+      res.on('end', resolve);
+      res.on('error', resolve);
+    });
+
+    req.on('error', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Register process-level crash handlers if telemetry is active.
+ * Call once at startup. No-op if telemetry is not enabled.
+ *
+ * Prints a one-line notice if telemetry was opted in but consent_version is stale.
+ */
+function registerCrashHooks(version) {
+  const status = telemetryStatus();
+
+  if (status === 'paused (consent_version mismatch)') {
+    process.stderr.write(
+      'xlsx-for-ai: telemetry has been updated. Run `xlsx-for-ai --enable-telemetry`' +
+      ' to resume on the new shape, or `--telemetry-status` for details.\n'
+    );
+    return;
+  }
+
+  if (status !== 'enabled') return;
+
+  async function handleCrash(err) {
+    const payload = buildPayload(err, version);
+    try {
+      await sendPayload(payload);
+    } catch (_) {
+      // Never let telemetry mask the real error.
+    }
+    // Re-throw so the original stack + non-zero exit still happens.
+    // We use process.exit(1) here because re-throwing from an
+    // uncaughtException handler after it fires causes Node to call the
+    // handler again, creating an infinite loop.
+    process.stderr.write((err && (err.stack || err.message)) ? (err.stack || err.message) + '\n' : String(err) + '\n');
+    process.exit(1);
+  }
+
+  process.on('uncaughtException', (err) => {
+    handleCrash(err);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    handleCrash(reason instanceof Error ? reason : new Error(String(reason)));
+  });
+}
+
+module.exports = {
+  registerCrashHooks,
+  sendPayload,
+  resolveEndpoint,
+  DEFAULT_ENDPOINT,
+  SEND_TIMEOUT_MS,
+};

package/lib/telemetry-sanitize.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * Sanitization for crash telemetry payloads.
+ *
+ * INVARIANTS (non-negotiable):
+ * - No file paths: scrub /Users/<x>/..., C:\Users\<x>\..., /home/<x>/...
+ * - Cap error_message at 200 chars (after scrubbing)
+ * - No cell values, no workbook structure (not available post-crash anyway)
+ * - No env vars, no argv beyond a hardcoded allowlist
+ * - No machine identifier (no hostname, MAC, install ID)
+ *
+ * Future maintainers: do NOT enrich this payload. The consent_version gates
+ * any shape expansion. Bump CURRENT_CONSENT_VERSION in telemetry-config.js
+ * before adding new fields.
+ */
+
+const os = require('os');
+
+const MAX_MESSAGE_LENGTH = 200;
+
+// Allowlisted first-arg values for the command field.
+// Everything else becomes '<other>'.
+const ALLOWED_COMMANDS = new Set([
+  'xlsx-for-ai',
+  'cursor-reads-xlsx',
+  'write',
+  '--json',
+  '--md',
+  '--stdout',
+  '--sql',
+  '--schema',
+  '--compact',
+  '--evaluate',
+  '--stream',
+  '--list-sheets',
+  '--diff',
+  '--range',
+  '--named-range',
+  '--max-rows',
+  '--max-cols',
+  '--max-tokens',
+  '--report-bug',
+  '--export-redacted-workbook',
+  '--enable-telemetry',
+  '--disable-telemetry',
+  '--telemetry-status',
+  '--help',
+  '--version',
+  '-h',
+  '-v',
+]);
+
+/**
+ * Scrub filesystem paths from a string.
+ *
+ * Covers:
+ *   /Users/<name>/...             (macOS)
+ *   /home/<name>/...              (Linux)
+ *   C:\Users\<name>\...           (Windows, forward or back slash variants)
+ *   /var/folders/...              (macOS temp)
+ *   /tmp/...                      (Linux/macOS tmp)
+ *   /private/tmp/...              (macOS private tmp — e.g. worktrees)
+ *   URL-encoded forms of the above (%2FUsers%2F<name>%2F...)
+ *   $HOME and %USERPROFILE% references
+ */
+function scrubPaths(str) {
+  if (typeof str !== 'string') return str;
+
+  // URL-decode once before scanning, then re-check on the decoded copy.
+  // We do NOT modify `str` in-place with decoded content because the
+  // caller's downstream display may want the original encoding. Instead
+  // we run two passes: one on the raw string, one on the decoded copy,
+  // and use the more-scrubbed result.
+  let decoded;
+  try {
+    decoded = decodeURIComponent(str);
+  } catch (_) {
+    decoded = str;
+  }
+
+  function scrubLiteral(s) {
+    // Windows: C:\Users\<name>\... or C:/Users/<name>/...
+    let out = s.replace(
+      /[A-Za-z]:[/\\][Uu]sers[/\\][^/\\:\s]+([/\\][^\s]*)*/g,
+      '<path>'
+    );
+
+    // Unix home dirs: /Users/<name>/... or /home/<name>/...
+    out = out.replace(
+      /\/(Users|home)\/[^/\s:]+([^\s:])*/g,
+      '<path>'
+    );
+
+    // /tmp/... and /private/tmp/...
+    out = out.replace(
+      /\/(?:private\/)?tmp\/[^\s:]+/g,
+      '<path>'
+    );
+
+    // /var/folders/...
+    out = out.replace(
+      /\/var\/folders\/[^\s:]+/g,
+      '<path>'
+    );
+
+    // $HOME/... or ${HOME}/... (env-var style references to home dir)
+    out = out.replace(
+      /\$\{?HOME\}?\/[^\s]*/gi,
+      '<path>'
+    );
+
+    // %USERPROFILE%\... (Windows env-var style)
+    out = out.replace(
+      /%USERPROFILE%[/\\][^\s]*/gi,
+      '<path>'
+    );
+
+    return out;
+  }
+
+  const scrubbed = scrubLiteral(str);
+  const scrubbedDecoded = scrubLiteral(decoded);
+
+  // If the decoded version produced additional scrubbing (URL-encoded path),
+  // return the scrubbed-decoded version so the sensitive data is removed.
+  // Heuristic: if scrubbing the decoded string was MORE aggressive (fewer
+  // remaining path fragments) use that result.
+  if (scrubbedDecoded.length < scrubbed.length) {
+    return scrubbedDecoded;
+  }
+  return scrubbed;
+}
+
+/**
+ * Sanitize error message: scrub paths, cap at 200 chars.
+ */
+function sanitizeMessage(message) {
+  if (!message) return '';
+  const scrubbed = scrubPaths(String(message));
+  return scrubbed.slice(0, MAX_MESSAGE_LENGTH);
+}
+
+/**
+ * Build the outgoing crash payload from an Error object.
+ * Returns a plain object with only the allowed fields.
+ */
+function buildPayload(err, version) {
+  const errorType  = (err && err.constructor && err.constructor.name) || 'Error';
+  const rawMessage = (err && err.message) ? err.message : String(err);
+  const message    = sanitizeMessage(rawMessage);
+
+  // First arg from process.argv — only if in allowlist.
+  let command = '<other>';
+  try {
+    const firstArg = process.argv[2];
+    if (firstArg && ALLOWED_COMMANDS.has(firstArg)) {
+      command = firstArg;
+    }
+  } catch (_) { /* ignore */ }
+
+  return {
+    v: 1,
+    ts: new Date().toISOString(),
+    error_type: errorType,
+    error_message: message,
+    command,
+    xlsx_for_ai_version: version || 'unknown',
+    node_version: process.version,
+    os_arch: `${process.platform}-${process.arch}`,
+  };
+}
+
+module.exports = {
+  scrubPaths,
+  sanitizeMessage,
+  buildPayload,
+  MAX_MESSAGE_LENGTH,
+  ALLOWED_COMMANDS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xlsx-for-ai",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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": {
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/round-trip.test.js test/output-matrix.test.js test/unit/*.test.js"
+    "test": "node --test test/round-trip.test.js test/output-matrix.test.js test/unit/*.test.js tests/telemetry-sanitize.test.js tests/telemetry-config.test.js tests/telemetry-consent-version.test.js tests/telemetry-flags.test.js"
   },
   "keywords": [
     "xlsx",
@@ -50,6 +50,7 @@
     "@formulajs/formulajs": "^4.6.0",
     "@protobi/exceljs": "^4.4.0-protobi.9",
     "gpt-tokenizer": "^3.4.0",
+    "jszip": "^3.10.1",
     "papaparse": "^5.5.3",
     "xlsx": "^0.18.5"
   },