@idea1/filekit 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @datafabriq/filekit
+
+A reader and writer for the spreadsheets agent-driven data pipelines depend on — CSV and
+XLSX files a client uploads that a downstream process has to parse correctly every time.
+Pure Node (`fs` + `zlib`), no dependencies, no build step.
+
+```js
+const fk = require('@datafabriq/filekit');
+
+fk.parseCsv(text, { headerRow })   // quoted fields, comma-thousands; headerRow skips a preamble
+fk.readXlsx(pathOrBuffer)          // reads .xlsx directly — the unzip is built in
+fk.writeXlsx(path, sheets)         // one tab per dataset; row 0 is the header
+
+fk.num(v)                          // '$1,234.50' → 1234.5; '(312,571.01)' → -312571.01
+fk.excelSerialToYM(n)              // 46143 → '2026-05'
+fk.findMonthColumns(header)        // discover a MON YYYY matrix by header, never by index
+fk.findColumnBySerialMonth(sheet, headerRow, '2026-05')
+fk.findRow(sheet, (row, n) => …)   // locate a block by its label
+```
+
+`readXlsx` returns real sheet names in workbook order; address a sheet by name
+(`wb.sheet('GL 24500 Accrued Bonus')`) rather than by index. Cells are 1-based and
+Excel-shaped: `sheet.at(12, 3)` is cell `C12`.
+
+## Reading messy source files
+
+Two properties of these files break naive parsers, and both are covered by the tests:
+
+- **Month columns move.** A commission ledger's `MON YYYY` matrix grows a column each
+  period, and a bonus workbook's month headers are Excel serial dates. Locate the close
+  month by matching the header; a fixed column index silently reads the wrong month.
+- **A cell's value is not always its text.** Totals are formula cells whose value lives in
+  `<v>`; empty cells are self-closing and carry no value at all; text may be a shared
+  string or an inline string. `filekit` resolves all four.
+
+Locate a block by the labels around it (`Beginning`, `New Accruals`, `Payments`, `Ending`,
+the GL numbers, etc.) rather than by row number, so an inserted row does not shift the read.
+
+## Writing a reference workbook
+
+`writeXlsx` produces workbooks a Custom Files connector can ingest — one tab per dataset,
+`snake_case` headers on row 1, and conventions bronze expects:
+
+- Dates as literal `YYYY-MM-DD` text, never Excel serials, so `TRY_CAST(… AS DATE)` holds.
+- An omitted cell for a null; an empty cell ingests as `NULL`, `0` does not.
+- Values written as numbers, text as inline strings, XML-escaped.
+- Every column ingests as `STRING`; the reading spec does the `TRY_CAST`.
+
+## Tests
+
+```bash
+npm test
+```
+
+Self-contained — every fixture is built in-process, so the suite carries no customer data
+and runs anywhere. It asserts the cell shapes above: formula cells, self-closing cells,
+shared strings with entities, serial dates, a header below a nine-row preamble, and a
+write→read round-trip preserving nulls, negatives, and escaping.
+
+## Origin
+
+Extracted from Concept3D's month-end close kit (`datafabriq-ops` → `context/revenue-reporting/close-tools/`),
+where the same reader already served two teams' file shapes (Concept3D's QuotaPath/bonus
+files, Intake's Amazon/Ed's-workbook files) before this package existed.
+
+## Publishing
+
+Published as `@idea1/filekit` (public), same npm org as `@idea1/cli`. Pushing a
+`filekit-v*.*.*` tag runs `.github/workflows/publish-filekit.yml`, which runs `npm run build`
+(the test suite) then `npm run deploy` (`npm publish --access public`), authenticated via
+the `NPM_TOKEN` repo secret — an npm Automation token for a member of the `idea1` npm org.
+Bump the version in `package.json` first, since npm rejects re-publishing an existing version.

package/filekit.js

@@ -0,0 +1,498 @@
+'use strict';
+/*
+ * filekit — messy-file reader toolkit for the close kit.
+ *
+ * Reads the uploaded spreadsheets a month-end close depends on: CSVs with a
+ * preamble before the real header, and .xlsx workbooks (read directly — the
+ * unzip is built in, no npm dependency, no pre-unzipping).
+ *
+ * Pure Node (fs + zlib). No external packages. Same reader serves every team:
+ *   Concept3D — QuotaPath commission CSV (MON YYYY matrix), accrued-bonus XLSX.
+ *   Intake    — Amazon Main report CSV (header on row 10), Ed's XLSX.
+ *
+ * Exports: parseCsv, readXlsx, num, excelSerialToDate, excelSerialToYM,
+ *          findMonthColumns, findRow, unzip.
+ */
+
+const fs = require('fs');
+const zlib = require('zlib');
+
+/* ------------------------------------------------------------------ *
+ * Numbers & dates
+ * ------------------------------------------------------------------ */
+
+/** Coerce a spreadsheet cell to a number, tolerating $ , % whitespace and (parens) negatives. */
+function num(v) {
+  if (v == null || v === '') return 0;
+  let s = String(v).trim();
+  let neg = false;
+  if (/^\(.*\)$/.test(s)) { neg = true; s = s.slice(1, -1); }
+  s = s.replace(/[$,%\s]/g, '');
+  const x = parseFloat(s);
+  if (isNaN(x)) return 0;
+  return neg ? -x : x;
+}
+
+/** Excel serial date (1900 system) → JS Date (UTC). */
+function excelSerialToDate(n) {
+  return new Date(Date.UTC(1899, 11, 30) + Math.round(Number(n)) * 86400000);
+}
+
+/** Excel serial date → "YYYY-MM". */
+function excelSerialToYM(n) {
+  const d = excelSerialToDate(n);
+  return d.getUTCFullYear() + '-' + String(d.getUTCMonth() + 1).padStart(2, '0');
+}
+
+/* ------------------------------------------------------------------ *
+ * CSV
+ * ------------------------------------------------------------------ */
+
+/** RFC-4180-ish tokenizer: handles quoted fields, "" escapes, CRLF. → string[][] */
+function tokenizeCsv(text) {
+  const rows = [];
+  let row = [], field = '', inQ = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inQ) {
+      if (ch === '"') { if (text[i + 1] === '"') { field += '"'; i++; } else inQ = false; }
+      else field += ch;
+    } else {
+      if (ch === '"') inQ = true;
+      else if (ch === ',') { row.push(field); field = ''; }
+      else if (ch === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+      else if (ch === '\r') { /* skip */ }
+      else field += ch;
+    }
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+/**
+ * Parse CSV text into header + row objects.
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {number} [opts.headerRow=0]  0-based index of the header line. Set to skip a
+ *                                     preamble (e.g. 9 for Amazon's row-10 header).
+ * @returns {{header:string[], rows:Array<Object>, raw:string[][]}}
+ *          Each row is keyed by header name; `row._cells` keeps positional access.
+ */
+function parseCsv(text, opts = {}) {
+  const headerRow = opts.headerRow ?? 0;
+  const raw = tokenizeCsv(text);
+  const header = (raw[headerRow] || []).map(h => h.trim());
+  const rows = [];
+  for (let r = headerRow + 1; r < raw.length; r++) {
+    const cells = raw[r];
+    if (!cells || (cells.length === 1 && cells[0] === '')) continue; // blank line
+    const o = { _cells: cells };
+    for (let c = 0; c < header.length; c++) o[header[c]] = cells[c];
+    rows.push(o);
+  }
+  return { header, rows, raw };
+}
+
+/**
+ * Find the `MON YYYY` matrix columns in a CSV header (e.g. QuotaPath's amortization
+ * schedule). Never rely on a fixed index — the matrix grows a column each month.
+ * @returns {Array<{name:string, index:number}>} in header order.
+ */
+function findMonthColumns(header) {
+  const re = /^[A-Za-z]{3}\s+\d{4}$/;
+  return header
+    .map((h, i) => ({ name: (h || '').trim(), index: i }))
+    .filter(c => re.test(c.name));
+}
+
+/* ------------------------------------------------------------------ *
+ * ZIP (minimal, dependency-free) — enough to open an .xlsx
+ * ------------------------------------------------------------------ */
+
+/** Unzip a Buffer via its central directory. → Map<name, Buffer>. Handles stored + deflate. */
+function unzip(buf) {
+  const files = new Map();
+  // Locate End Of Central Directory (scan back from the end; max 64k comment).
+  let eocd = -1;
+  const minEnd = Math.max(0, buf.length - 22 - 0xffff);
+  for (let i = buf.length - 22; i >= minEnd; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('filekit.unzip: not a zip (no EOCD signature)');
+  const count = buf.readUInt16LE(eocd + 10);
+  let p = buf.readUInt32LE(eocd + 16); // central directory offset
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) break; // central file header
+    const method   = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const nameLen  = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const cmtLen   = buf.readUInt16LE(p + 32);
+    const localOff = buf.readUInt32LE(p + 42);
+    const name     = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    // Jump to the local header to compute where the data actually starts.
+    const lNameLen  = buf.readUInt16LE(localOff + 26);
+    const lExtraLen = buf.readUInt16LE(localOff + 28);
+    const dataStart = localOff + 30 + lNameLen + lExtraLen;
+    const comp = buf.subarray(dataStart, dataStart + compSize);
+    let content;
+    if (method === 0) content = Buffer.from(comp);
+    else if (method === 8) content = zlib.inflateRawSync(comp);
+    else throw new Error('filekit.unzip: unsupported compression method ' + method + ' for ' + name);
+    files.set(name, content);
+    p += 46 + nameLen + extraLen + cmtLen;
+  }
+  return files;
+}
+
+/* ------------------------------------------------------------------ *
+ * XLSX
+ * ------------------------------------------------------------------ */
+
+function colToNum(letters) {
+  let n = 0;
+  for (const ch of letters) n = n * 26 + (ch.charCodeAt(0) - 64);
+  return n;
+}
+
+const XML_ENT = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&#10;': ' ', '&#39;': "'" };
+function unescapeXml(s) {
+  return s.replace(/&amp;|&lt;|&gt;|&quot;|&apos;|&#10;|&#39;/g, m => XML_ENT[m]);
+}
+
+function parseSharedStrings(xml) {
+  const out = [];
+  let m; const re = /<si>([\s\S]*?)<\/si>/g;
+  while ((m = re.exec(xml))) {
+    const parts = [...m[1].matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map(x => x[1]);
+    out.push(unescapeXml(parts.join('')));
+  }
+  return out;
+}
+
+/** One worksheet: sparse cell grid with a 1-based Excel-style accessor. */
+function makeSheet(xml, shared) {
+  const cells = Object.create(null); // cells[row][col] = value (1-based)
+  let maxRow = 0, maxCol = 0;
+  let rm; const rowRe = /<row[^>]*\br="(\d+)"[^>]*>([\s\S]*?)<\/row>/g;
+  while ((rm = rowRe.exec(xml))) {
+    const rn = +rm[1];
+    const line = (cells[rn] = cells[rn] || Object.create(null));
+    let cm; const cellRe = /<c r="([A-Z]+)(\d+)"([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g;
+    while ((cm = cellRe.exec(rm[2]))) {
+      const col = colToNum(cm[1]);
+      const attrs = cm[3] || '';
+      const inner = cm[4] || '';
+      const t = (attrs.match(/t="([^"]*)"/) || [])[1];
+      let val = '';
+      const isMatch = inner.match(/<is>[\s\S]*?<t[^>]*>([\s\S]*?)<\/t>[\s\S]*?<\/is>/);
+      if (isMatch) val = unescapeXml(isMatch[1]);            // inline string
+      else {
+        const v = (inner.match(/<v>([\s\S]*?)<\/v>/) || [])[1];
+        if (v !== undefined) val = (t === 's') ? (shared[+v] ?? '') : v; // shared str vs number/formula
+      }
+      line[col] = val;
+      if (col > maxCol) maxCol = col;
+    }
+    if (rn > maxRow) maxRow = rn;
+  }
+  return {
+    rowCount: maxRow,
+    colCount: maxCol,
+    /** 1-based, Excel-style: at(12, 3) === cell C12. */
+    at(row, col) { return (cells[row] && cells[row][col]) ?? ''; },
+    /** the row's cells as a 1-based-ish object (col → value). */
+    row(row) { return cells[row] || {}; },
+  };
+}
+
+/**
+ * Resolve the workbook's real sheet names, in workbook order, to their part paths.
+ * workbook.xml gives name + r:id; workbook.xml.rels maps r:id → worksheets/sheetN.xml.
+ * @returns {Array<{name:string, path:string}>}
+ */
+function resolveSheets(files) {
+  const wbXml = (files.get('xl/workbook.xml') || Buffer.from('')).toString('utf8');
+  const relsXml = (files.get('xl/_rels/workbook.xml.rels') || Buffer.from('')).toString('utf8');
+
+  const rels = {}; // rId → target part path
+  for (const m of relsXml.matchAll(/<Relationship\b[^>]*>/g)) {
+    const id = (m[0].match(/Id="([^"]+)"/) || [])[1];
+    let target = (m[0].match(/Target="([^"]+)"/) || [])[1];
+    if (!id || !target) continue;
+    target = target.replace(/^\/?xl\//, '').replace(/^\.\//, '');
+    rels[id] = 'xl/' + target;
+  }
+
+  const out = [];
+  for (const m of wbXml.matchAll(/<sheet\b[^>]*\/?>/g)) {
+    const name = (m[0].match(/name="([^"]*)"/) || [])[1];
+    const rid = (m[0].match(/r:id="([^"]+)"/) || [])[1];
+    const path = rels[rid];
+    if (name && path && files.has(path)) out.push({ name: unescapeXml(name), path });
+  }
+  if (out.length) return out;
+
+  // Fallback: no workbook.xml — order sheetN.xml numerically, name them by index.
+  return [...files.keys()]
+    .filter(k => /^xl\/worksheets\/sheet\d+\.xml$/.test(k))
+    .sort((a, b) => (+a.match(/(\d+)/)[1]) - (+b.match(/(\d+)/)[1]))
+    .map((path, i) => ({ name: `Sheet${i + 1}`, path }));
+}
+
+/**
+ * Read an .xlsx directly (path or Buffer). Unzip is built in.
+ * @returns {{sheetNames:string[], sheet:(nameOrIndex?:string|number)=>Sheet, sharedStrings:string[]}}
+ *          `sheet()` accepts a real sheet name ("GL 24500 Accrued Bonus") or a 0-based index.
+ */
+function readXlsx(pathOrBuffer) {
+  const buf = Buffer.isBuffer(pathOrBuffer) ? pathOrBuffer : fs.readFileSync(pathOrBuffer);
+  const files = unzip(buf);
+  const ssXml = files.has('xl/sharedStrings.xml') ? files.get('xl/sharedStrings.xml').toString('utf8') : '';
+  const shared = parseSharedStrings(ssXml);
+  const sheets = resolveSheets(files);
+  const cache = {};
+  return {
+    sheetNames: sheets.map(s => s.name),
+    sharedStrings: shared,
+    sheet(nameOrIndex = 0) {
+      const i = (typeof nameOrIndex === 'number')
+        ? nameOrIndex
+        : sheets.findIndex(s => s.name === nameOrIndex);
+      if (i < 0 || !sheets[i]) throw new Error('filekit.readXlsx: no sheet ' + JSON.stringify(nameOrIndex));
+      if (!cache[i]) cache[i] = makeSheet(files.get(sheets[i].path).toString('utf8'), shared);
+      return cache[i];
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * XLSX writing — generate a reference workbook to hand a client.
+ * Stored (uncompressed) zip + the minimal OOXML parts. No dependencies.
+ * ------------------------------------------------------------------ */
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  if (typeof zlib.crc32 === 'function') return zlib.crc32(buf) >>> 0;
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+/** 1-based column number → Excel letters (1 → A, 27 → AA). */
+function numToCol(n) {
+  let s = '';
+  while (n > 0) { const m = (n - 1) % 26; s = String.fromCharCode(65 + m) + s; n = Math.floor((n - 1) / 26); }
+  return s;
+}
+
+function escXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/\r/g, '')
+    // strip control chars XML 1.0 forbids
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+}
+
+/**
+ * Build a ZIP from Map<name, Buffer>. Deterministic: fixed timestamps, and each
+ * entry is deflated when that shrinks it, else stored — so output is byte-stable
+ * for a given input and stays comparable in size to the file it replaces.
+ */
+function zipStore(files) {
+  const DOS_DATE = 33, DOS_TIME = 0; // 1980-01-01, so output is byte-stable
+  const locals = [], centrals = [];
+  let offset = 0;
+
+  for (const [name, data] of files) {
+    const nameBuf = Buffer.from(name, 'utf8');
+    const crc = crc32(data); // always over the UNCOMPRESSED bytes
+
+    const deflated = zlib.deflateRawSync(data, { level: 9 });
+    const useDeflate = deflated.length < data.length;
+    const method = useDeflate ? 8 : 0;
+    const payload = useDeflate ? deflated : data;
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);   // version needed
+    local.writeUInt16LE(0, 6);    // flags
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(payload.length, 18);  // compressed size
+    local.writeUInt32LE(data.length, 22);     // uncompressed size
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, nameBuf, payload);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);   // version made by
+    central.writeUInt16LE(20, 6);   // version needed
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(DOS_TIME, 12);
+    central.writeUInt16LE(DOS_DATE, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(payload.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(nameBuf.length, 28);
+    central.writeUInt16LE(0, 30);  // extra
+    central.writeUInt16LE(0, 32);  // comment
+    central.writeUInt16LE(0, 34);  // disk
+    central.writeUInt16LE(0, 36);  // internal attrs
+    central.writeUInt32LE(0, 38);  // external attrs
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, nameBuf);
+
+    offset += local.length + nameBuf.length + payload.length;
+  }
+
+  const localPart = Buffer.concat(locals);
+  const centralPart = Buffer.concat(centrals);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.size, 8);
+  eocd.writeUInt16LE(files.size, 10);
+  eocd.writeUInt32LE(centralPart.length, 12);
+  eocd.writeUInt32LE(localPart.length, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([localPart, centralPart, eocd]);
+}
+
+const SHEET_NAME_BAD = /[\[\]:*?/\\]/;
+
+function sheetXml(rows) {
+  const out = [
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
+    '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheetData>',
+  ];
+  rows.forEach((row, r) => {
+    const cells = [];
+    row.forEach((v, c) => {
+      if (v === null || v === undefined || v === '') return; // empty cell = null on ingest
+      const ref = numToCol(c + 1) + (r + 1);
+      if (typeof v === 'number' && Number.isFinite(v)) {
+        cells.push(`<c r="${ref}"><v>${v}</v></c>`);
+      } else {
+        cells.push(`<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${escXml(v)}</t></is></c>`);
+      }
+    });
+    if (cells.length) out.push(`<row r="${r + 1}">${cells.join('')}</row>`);
+  });
+  out.push('</sheetData></worksheet>');
+  return Buffer.from(out.join(''), 'utf8');
+}
+
+/**
+ * Write a multi-tab .xlsx. One tab per dataset — the tab name becomes the bronze table suffix.
+ * @param {string|null} filePath  write here, or null to only return the buffer
+ * @param {Array<{name:string, rows:Array<Array<string|number|null>>}>} sheets  row 0 = header
+ * @returns {Buffer} the .xlsx bytes
+ */
+function writeXlsx(filePath, sheets) {
+  if (!sheets || !sheets.length) throw new Error('filekit.writeXlsx: need at least one sheet');
+  for (const s of sheets) {
+    if (!s.name || s.name.length > 31 || SHEET_NAME_BAD.test(s.name)) {
+      throw new Error('filekit.writeXlsx: invalid sheet name ' + JSON.stringify(s.name));
+    }
+  }
+  const names = sheets.map(s => s.name);
+  if (new Set(names).size !== names.length) throw new Error('filekit.writeXlsx: duplicate sheet names');
+
+  const files = new Map();
+  const stylesRid = 'rId' + (sheets.length + 1);
+
+  files.set('[Content_Types].xml', Buffer.from(
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+    '<Default Extension="xml" ContentType="application/xml"/>' +
+    '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+    sheets.map((_, i) => `<Override PartName="/xl/worksheets/sheet${i + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`).join('') +
+    '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>' +
+    '</Types>', 'utf8'));
+
+  files.set('_rels/.rels', Buffer.from(
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>' +
+    '</Relationships>', 'utf8'));
+
+  files.set('xl/workbook.xml', Buffer.from(
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ' +
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets>' +
+    sheets.map((s, i) => `<sheet name="${escXml(s.name)}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`).join('') +
+    '</sheets></workbook>', 'utf8'));
+
+  files.set('xl/_rels/workbook.xml.rels', Buffer.from(
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    sheets.map((_, i) => `<Relationship Id="rId${i + 1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet${i + 1}.xml"/>`).join('') +
+    `<Relationship Id="${stylesRid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>` +
+    '</Relationships>', 'utf8'));
+
+  files.set('xl/styles.xml', Buffer.from(
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">' +
+    '<fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>' +
+    '<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>' +
+    '<borders count="1"><border/></borders>' +
+    '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>' +
+    '<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs>' +
+    '</styleSheet>', 'utf8'));
+
+  sheets.forEach((s, i) => files.set(`xl/worksheets/sheet${i + 1}.xml`, sheetXml(s.rows)));
+
+  const buf = zipStore(files);
+  if (filePath) fs.writeFileSync(filePath, buf);
+  return buf;
+}
+
+/* ------------------------------------------------------------------ *
+ * Small grid helpers
+ * ------------------------------------------------------------------ */
+
+/**
+ * Find the first Excel row (1-based) whose cells satisfy a predicate.
+ * @param {Sheet} sheet
+ * @param {(rowObj:object, rowNum:number)=>boolean} predicate
+ */
+function findRow(sheet, predicate) {
+  for (let r = 1; r <= sheet.rowCount; r++) {
+    if (predicate(sheet.row(r), r)) return r;
+  }
+  return -1;
+}
+
+/** In a header row of Excel serial dates, find the column whose date is `ym` ("YYYY-MM"). */
+function findColumnBySerialMonth(sheet, headerRowNum, ym) {
+  const line = sheet.row(headerRowNum);
+  for (const col of Object.keys(line)) {
+    const n = num(line[col]);
+    if (n > 40000 && n < 60000 && excelSerialToYM(n) === ym) return +col;
+  }
+  return -1;
+}
+
+module.exports = {
+  num, excelSerialToDate, excelSerialToYM,
+  parseCsv, tokenizeCsv, findMonthColumns,
+  unzip, readXlsx, resolveSheets, findRow, findColumnBySerialMonth,
+  zipStore, writeXlsx, numToCol, crc32,
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@idea1/filekit",
+  "version": "1.0.0",
+  "description": "Messy-file reader/writer toolkit (CSV + XLSX) for the close kit and similar agent-driven data pipelines. Pure Node, no dependencies.",
+  "main": "filekit.js",
+  "files": [
+    "filekit.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node filekit.test.js",
+    "build": "npm test",
+    "prepublishOnly": "npm run build",
+    "deploy": "npm publish --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datafabriq-co/datafabriq.git",
+    "directory": "packages/filekit"
+  },
+  "license": "MIT"
+}