@kvishal04/library-core 1.0.0

package/dist/spreadsheet/src/models/SpreadsheetTypes.d.ts

@@ -0,0 +1,74 @@
+import ExcelJS from 'exceljs';
+export interface ColumnDef {
+    /** Column key – must match a property on the data rows */
+    key: string;
+    /** Header label shown in row 1 */
+    header: string;
+    /** Column width in characters (default 20) */
+    width?: number;
+    /** Optional number format string, e.g. "#,##0.00" or "dd/mm/yyyy" */
+    numFmt?: string;
+    /** Horizontal alignment */
+    alignment?: ExcelJS.Alignment['horizontal'];
+}
+export interface SheetDef {
+    /** Sheet tab name (max 31 chars) */
+    name: string;
+    /** Row data – each object's keys must align with ColumnDef.key values */
+    rows: Record<string, any>[];
+    /**
+     * Column definitions.
+     * When omitted, columns are derived automatically from the first data row.
+     */
+    columns?: ColumnDef[];
+}
+export type HeaderStyle = 'default' | 'dark' | 'minimal' | 'none';
+export interface ReadSheetResult {
+    /** Sheet name */
+    name: string;
+    /** Parsed rows as plain objects keyed by the header row values */
+    rows: Record<string, any>[];
+    /** Total number of data rows (excludes header) */
+    rowCount: number;
+    /** Column headers found in row 1 */
+    headers: string[];
+}
+export interface ReadWorkbookResult {
+    /** Number of sheets in the workbook */
+    sheetCount: number;
+    sheets: ReadSheetResult[];
+}
+export interface WriteOptions {
+    /** Header row style preset (default: "default") */
+    headerStyle?: HeaderStyle;
+    /** Freeze the first row so it stays visible while scrolling */
+    freezeHeader?: boolean;
+    /** Enable auto-filter on all header columns */
+    autoFilter?: boolean;
+    /** Workbook creator metadata */
+    creator?: string;
+}
+export interface CreateWorkbookOptions extends WriteOptions {
+    sheets: SheetDef[];
+}
+export interface AppendRowsOptions {
+    /** Absolute path to an existing .xlsx file */
+    filePath: string;
+    /** Target sheet name */
+    sheetName: string;
+    /** Rows to append */
+    rows: Record<string, any>[];
+}
+export interface UpdateCellOptions {
+    /** Absolute path to an existing .xlsx file */
+    filePath: string;
+    /** Target sheet name */
+    sheetName: string;
+    /** 1-based row index */
+    row: number;
+    /** 1-based column index or column letter (e.g. "C") */
+    col: number | string;
+    /** New cell value */
+    value: ExcelJS.CellValue;
+}
+//# sourceMappingURL=SpreadsheetTypes.d.ts.map

package/dist/spreadsheet/src/models/SpreadsheetTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpreadsheetTypes.d.ts","sourceRoot":"","sources":["../../../../core/spreadsheet/src/models/SpreadsheetTypes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAI9B,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;CAC7C;AAID,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;CACvB;AAID,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAIlE,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAID,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,qBAAqB;IACrB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC;CAC1B"}

package/dist/spreadsheet/src/models/SpreadsheetTypes.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=SpreadsheetTypes.js.map

package/dist/spreadsheet/src/models/SpreadsheetTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpreadsheetTypes.js","sourceRoot":"","sources":["../../../../core/spreadsheet/src/models/SpreadsheetTypes.ts"],"names":[],"mappings":""}

package/dist/spreadsheet/src/models/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SpreadsheetTypes';
+//# sourceMappingURL=index.d.ts.map

package/dist/spreadsheet/src/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../core/spreadsheet/src/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/spreadsheet/src/models/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./SpreadsheetTypes"), exports);
+//# sourceMappingURL=index.js.map

package/dist/spreadsheet/src/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../core/spreadsheet/src/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC"}

package/dist/spreadsheet/src/service/SpreadsheetService.d.ts

@@ -0,0 +1,72 @@
+import type { SheetDef, ReadSheetResult, ReadWorkbookResult, CreateWorkbookOptions, AppendRowsOptions, UpdateCellOptions, WriteOptions } from '../models/SpreadsheetTypes';
+export declare class SpreadsheetService {
+    private initWorkbook;
+    private populateSheet;
+    /**
+     * Create an in-memory workbook buffer from one or more sheet definitions.
+     * Use this when you want to stream the file or upload it without saving to disk.
+     */
+    createBuffer(opts: CreateWorkbookOptions): Promise<Buffer>;
+    /**
+     * Create a workbook and save it to the given absolute file path.
+     * Parent directories are created automatically.
+     */
+    createFile(filePath: string, opts: CreateWorkbookOptions): Promise<void>;
+    /**
+     * Read all sheets from an .xlsx file on disk.
+     * Each sheet is returned as an array of plain objects keyed by header values.
+     */
+    readFile(filePath: string): Promise<ReadWorkbookResult>;
+    /**
+     * Read all sheets from an .xlsx buffer (e.g. a multer upload).
+     */
+    readBuffer(buffer: Buffer): Promise<ReadWorkbookResult>;
+    /**
+     * Read a single named sheet from a file.
+     * Throws if the sheet is not found.
+     */
+    readSheet(filePath: string, sheetName: string): Promise<ReadSheetResult>;
+    private parseWorkbook;
+    /**
+     * Append rows to an existing sheet in an .xlsx file on disk.
+     * Adds rows after the last occupied row; does not touch headers.
+     */
+    appendRows(opts: AppendRowsOptions): Promise<void>;
+    /**
+     * Update the value of a single cell in an existing .xlsx file.
+     *
+     * @param opts.row  1-based row index
+     * @param opts.col  1-based column index or letter (e.g. "C")
+     */
+    updateCell(opts: UpdateCellOptions): Promise<void>;
+    /**
+     * Remove a sheet from an existing .xlsx file by name.
+     */
+    deleteSheet(filePath: string, sheetName: string): Promise<void>;
+    /**
+     * Rename a sheet in an existing .xlsx file.
+     */
+    renameSheet(filePath: string, oldName: string, newName: string): Promise<void>;
+    /**
+     * Add a new sheet to an existing .xlsx file.
+     */
+    addSheet(filePath: string, sheet: SheetDef, writeOpts?: WriteOptions): Promise<void>;
+    /**
+     * Write a workbook directly to an Express `res` stream.
+     * Sets the appropriate Content-Type and Content-Disposition headers.
+     *
+     * @param res      Express Response object
+     * @param opts     Workbook creation options
+     * @param fileName Download filename (default: "export.xlsx")
+     */
+    streamToResponse(res: any, opts: CreateWorkbookOptions, fileName?: string): Promise<void>;
+    /**
+     * Convert a column letter (e.g. "A", "AB") to a 1-based column number.
+     */
+    private colLetterToNumber;
+    /**
+     * List the sheet names in an .xlsx file without loading all data.
+     */
+    listSheets(filePath: string): Promise<string[]>;
+}
+//# sourceMappingURL=SpreadsheetService.d.ts.map

package/dist/spreadsheet/src/service/SpreadsheetService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpreadsheetService.d.ts","sourceRoot":"","sources":["../../../../core/spreadsheet/src/service/SpreadsheetService.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACb,MAAM,4BAA4B,CAAC;AAIpC,qBAAa,kBAAkB;IAI7B,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;IA2BrB;;;OAGG;IACG,YAAY,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAWhE;;;OAGG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9E;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAM7D;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAM7D;;;OAGG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAO9E,OAAO,CAAC,aAAa;IA0CrB;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxD;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrE;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpF;;OAEG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,QAAQ,EACf,SAAS,GAAE,YAAiB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;OAOG;IACG,gBAAgB,CACpB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,SAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAoBhB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAKtD"}

package/dist/spreadsheet/src/service/SpreadsheetService.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpreadsheetService = void 0;
+const exceljs_1 = __importDefault(require("exceljs"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const styleUtils_1 = require("../utils/styleUtils");
+// ─── SpreadsheetService ───────────────────────────────────────────────────────
+class SpreadsheetService {
+    // ─── Private helpers ────────────────────────────────────────────────────────
+    initWorkbook(creator = 'SpreadsheetService') {
+        const wb = new exceljs_1.default.Workbook();
+        wb.creator = creator;
+        wb.created = new Date();
+        wb.modified = new Date();
+        return wb;
+    }
+    populateSheet(worksheet, sheet, opts = {}) {
+        const { rows, columns: colDefs } = sheet;
+        worksheet.columns = (0, styleUtils_1.buildColumns)(colDefs, rows[0]);
+        rows.forEach((row) => worksheet.addRow(row).commit());
+        (0, styleUtils_1.applyHeaderStyle)(worksheet, opts.headerStyle ?? 'default');
+        if (colDefs?.length)
+            (0, styleUtils_1.applyColumnStyles)(worksheet, colDefs);
+        if (opts.freezeHeader) {
+            worksheet.views = [{ state: 'frozen', ySplit: 1, xSplit: 0, topLeftCell: 'A2', activeCell: 'A2' }];
+        }
+        if (opts.autoFilter && rows.length) {
+            const lastCol = worksheet.columnCount;
+            worksheet.autoFilter = { from: 'A1', to: { row: 1, column: lastCol } };
+        }
+    }
+    // ─── Create ─────────────────────────────────────────────────────────────────
+    /**
+     * Create an in-memory workbook buffer from one or more sheet definitions.
+     * Use this when you want to stream the file or upload it without saving to disk.
+     */
+    async createBuffer(opts) {
+        const wb = this.initWorkbook(opts.creator);
+        for (const sheet of opts.sheets) {
+            const ws = wb.addWorksheet((0, styleUtils_1.sanitiseSheetName)(sheet.name));
+            this.populateSheet(ws, sheet, opts);
+        }
+        return wb.xlsx.writeBuffer().then((buf) => Buffer.from(buf));
+    }
+    /**
+     * Create a workbook and save it to the given absolute file path.
+     * Parent directories are created automatically.
+     */
+    async createFile(filePath, opts) {
+        const wb = this.initWorkbook(opts.creator);
+        for (const sheet of opts.sheets) {
+            const ws = wb.addWorksheet((0, styleUtils_1.sanitiseSheetName)(sheet.name));
+            this.populateSheet(ws, sheet, opts);
+        }
+        await promises_1.default.mkdir(path_1.default.dirname(filePath), { recursive: true });
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Read ────────────────────────────────────────────────────────────────────
+    /**
+     * Read all sheets from an .xlsx file on disk.
+     * Each sheet is returned as an array of plain objects keyed by header values.
+     */
+    async readFile(filePath) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        return this.parseWorkbook(wb);
+    }
+    /**
+     * Read all sheets from an .xlsx buffer (e.g. a multer upload).
+     */
+    async readBuffer(buffer) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.load(buffer);
+        return this.parseWorkbook(wb);
+    }
+    /**
+     * Read a single named sheet from a file.
+     * Throws if the sheet is not found.
+     */
+    async readSheet(filePath, sheetName) {
+        const result = await this.readFile(filePath);
+        const sheet = result.sheets.find((s) => s.name === sheetName);
+        if (!sheet)
+            throw new Error(`Sheet "${sheetName}" not found in workbook`);
+        return sheet;
+    }
+    parseWorkbook(wb) {
+        const sheets = [];
+        wb.eachSheet((worksheet) => {
+            const allRows = [];
+            worksheet.eachRow((row) => allRows.push(row));
+            if (!allRows.length) {
+                sheets.push({ name: worksheet.name, rows: [], rowCount: 0, headers: [] });
+                return;
+            }
+            // Row 1 = headers
+            const headers = allRows[0].values
+                .slice(1) // exceljs row.values is 1-based (index 0 = undefined)
+                .map((v) => (v == null ? '' : String(v)));
+            const rows = [];
+            for (let i = 1; i < allRows.length; i++) {
+                const raw = allRows[i].values;
+                const record = {};
+                headers.forEach((header, idx) => {
+                    const cell = raw[idx + 1];
+                    // Unwrap rich-text objects
+                    record[header] = cell?.richText
+                        ? cell.richText.map((r) => r.text).join('')
+                        : cell ?? null;
+                });
+                rows.push(record);
+            }
+            sheets.push({ name: worksheet.name, rows, rowCount: rows.length, headers });
+        });
+        return { sheetCount: sheets.length, sheets };
+    }
+    // ─── Append ──────────────────────────────────────────────────────────────────
+    /**
+     * Append rows to an existing sheet in an .xlsx file on disk.
+     * Adds rows after the last occupied row; does not touch headers.
+     */
+    async appendRows(opts) {
+        const { filePath, sheetName, rows } = opts;
+        if (!rows.length)
+            return;
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        const ws = wb.getWorksheet(sheetName);
+        if (!ws)
+            throw new Error(`Sheet "${sheetName}" not found in "${path_1.default.basename(filePath)}"`);
+        rows.forEach((row) => ws.addRow(row).commit());
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Update cell ─────────────────────────────────────────────────────────────
+    /**
+     * Update the value of a single cell in an existing .xlsx file.
+     *
+     * @param opts.row  1-based row index
+     * @param opts.col  1-based column index or letter (e.g. "C")
+     */
+    async updateCell(opts) {
+        const { filePath, sheetName, row, col, value } = opts;
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        const ws = wb.getWorksheet(sheetName);
+        if (!ws)
+            throw new Error(`Sheet "${sheetName}" not found in "${path_1.default.basename(filePath)}"`);
+        ws.getCell(row, typeof col === 'string' ? this.colLetterToNumber(col) : col).value = value;
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Delete sheet ─────────────────────────────────────────────────────────────
+    /**
+     * Remove a sheet from an existing .xlsx file by name.
+     */
+    async deleteSheet(filePath, sheetName) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        const ws = wb.getWorksheet(sheetName);
+        if (!ws)
+            throw new Error(`Sheet "${sheetName}" not found`);
+        wb.removeWorksheet(ws.id);
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Rename sheet ─────────────────────────────────────────────────────────────
+    /**
+     * Rename a sheet in an existing .xlsx file.
+     */
+    async renameSheet(filePath, oldName, newName) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        const ws = wb.getWorksheet(oldName);
+        if (!ws)
+            throw new Error(`Sheet "${oldName}" not found`);
+        ws.name = (0, styleUtils_1.sanitiseSheetName)(newName);
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Add sheet ───────────────────────────────────────────────────────────────
+    /**
+     * Add a new sheet to an existing .xlsx file.
+     */
+    async addSheet(filePath, sheet, writeOpts = {}) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        const ws = wb.addWorksheet((0, styleUtils_1.sanitiseSheetName)(sheet.name));
+        this.populateSheet(ws, sheet, writeOpts);
+        await wb.xlsx.writeFile(filePath);
+    }
+    // ─── Stream to response ───────────────────────────────────────────────────────
+    /**
+     * Write a workbook directly to an Express `res` stream.
+     * Sets the appropriate Content-Type and Content-Disposition headers.
+     *
+     * @param res      Express Response object
+     * @param opts     Workbook creation options
+     * @param fileName Download filename (default: "export.xlsx")
+     */
+    async streamToResponse(res, opts, fileName = 'export.xlsx') {
+        const wb = this.initWorkbook(opts.creator);
+        for (const sheet of opts.sheets) {
+            const ws = wb.addWorksheet((0, styleUtils_1.sanitiseSheetName)(sheet.name));
+            this.populateSheet(ws, sheet, opts);
+        }
+        res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+        res.setHeader('Content-Disposition', `attachment; filename="${fileName}"`);
+        await wb.xlsx.write(res);
+        res.end();
+    }
+    // ─── Utility ──────────────────────────────────────────────────────────────────
+    /**
+     * Convert a column letter (e.g. "A", "AB") to a 1-based column number.
+     */
+    colLetterToNumber(letter) {
+        return letter
+            .toUpperCase()
+            .split('')
+            .reduce((acc, ch) => acc * 26 + ch.charCodeAt(0) - 64, 0);
+    }
+    /**
+     * List the sheet names in an .xlsx file without loading all data.
+     */
+    async listSheets(filePath) {
+        const wb = new exceljs_1.default.Workbook();
+        await wb.xlsx.readFile(filePath);
+        return wb.worksheets.map((ws) => ws.name);
+    }
+}
+exports.SpreadsheetService = SpreadsheetService;
+//# sourceMappingURL=SpreadsheetService.js.map

package/dist/spreadsheet/src/service/SpreadsheetService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpreadsheetService.js","sourceRoot":"","sources":["../../../../core/spreadsheet/src/service/SpreadsheetService.ts"],"names":[],"mappings":"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"}

package/dist/spreadsheet/src/utils/styleUtils.d.ts

@@ -0,0 +1,31 @@
+import ExcelJS from 'exceljs';
+import type { ColumnDef, HeaderStyle } from '../models/SpreadsheetTypes';
+/**
+ * Apply fill + font styling to a worksheet's header row.
+ *
+ * @param worksheet Target worksheet
+ * @param style     Preset name ('default' | 'dark' | 'minimal' | 'none')
+ */
+export declare function applyHeaderStyle(worksheet: ExcelJS.Worksheet, style?: HeaderStyle): void;
+/**
+ * Build the ExcelJS column definitions for a worksheet.
+ * When `colDefs` is supplied, uses those; otherwise derives columns
+ * from the keys of the first data row.
+ *
+ * @param colDefs  Explicit column definitions (optional)
+ * @param firstRow First data row used to infer columns when colDefs is absent
+ */
+export declare function buildColumns(colDefs?: ColumnDef[], firstRow?: Record<string, any>): Partial<ExcelJS.Column>[];
+/**
+ * Apply column-level number formatting and alignment after rows are written.
+ * Only applied when explicit ColumnDef definitions are provided.
+ *
+ * @param worksheet Target worksheet
+ * @param colDefs   Column definitions carrying numFmt / alignment
+ */
+export declare function applyColumnStyles(worksheet: ExcelJS.Worksheet, colDefs: ColumnDef[]): void;
+/**
+ * Sanitise a sheet name to be valid in Excel (max 31 chars, no special chars).
+ */
+export declare function sanitiseSheetName(name: string): string;
+//# sourceMappingURL=styleUtils.d.ts.map

package/dist/spreadsheet/src/utils/styleUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styleUtils.d.ts","sourceRoot":"","sources":["../../../../core/spreadsheet/src/utils/styleUtils.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAgBzE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,KAAK,GAAE,WAAuB,GAC7B,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,CAAC,EAAE,SAAS,EAAE,EACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAmB3B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,OAAO,EAAE,SAAS,EAAE,GACnB,IAAI,CAYN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/spreadsheet/src/utils/styleUtils.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyHeaderStyle = applyHeaderStyle;
+exports.buildColumns = buildColumns;
+exports.applyColumnStyles = applyColumnStyles;
+exports.sanitiseSheetName = sanitiseSheetName;
+// ─── Header fill presets ──────────────────────────────────────────────────────
+const HEADER_FILLS = {
+    default: { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE0E0E0' } },
+    dark: { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF2F75B6' } },
+    minimal: { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF2F2F2' } },
+};
+const HEADER_FONTS = {
+    default: { bold: true, color: { argb: 'FF000000' } },
+    dark: { bold: true, color: { argb: 'FFFFFFFF' } },
+    minimal: { bold: true, color: { argb: 'FF333333' } },
+};
+/**
+ * Apply fill + font styling to a worksheet's header row.
+ *
+ * @param worksheet Target worksheet
+ * @param style     Preset name ('default' | 'dark' | 'minimal' | 'none')
+ */
+function applyHeaderStyle(worksheet, style = 'default') {
+    if (style === 'none')
+        return;
+    const headerRow = worksheet.getRow(1);
+    headerRow.font = HEADER_FONTS[style];
+    headerRow.fill = HEADER_FILLS[style];
+    headerRow.alignment = { vertical: 'middle', horizontal: 'left', wrapText: false };
+    headerRow.height = 20;
+    headerRow.commit();
+}
+/**
+ * Build the ExcelJS column definitions for a worksheet.
+ * When `colDefs` is supplied, uses those; otherwise derives columns
+ * from the keys of the first data row.
+ *
+ * @param colDefs  Explicit column definitions (optional)
+ * @param firstRow First data row used to infer columns when colDefs is absent
+ */
+function buildColumns(colDefs, firstRow) {
+    if (colDefs?.length) {
+        return colDefs.map((c) => ({
+            key: c.key,
+            header: c.header,
+            width: c.width ?? 20,
+            ...(c.numFmt && { style: { numFmt: c.numFmt } }),
+        }));
+    }
+    if (firstRow) {
+        return Object.keys(firstRow).map((key) => ({
+            key,
+            header: key,
+            width: 20,
+        }));
+    }
+    return [];
+}
+/**
+ * Apply column-level number formatting and alignment after rows are written.
+ * Only applied when explicit ColumnDef definitions are provided.
+ *
+ * @param worksheet Target worksheet
+ * @param colDefs   Column definitions carrying numFmt / alignment
+ */
+function applyColumnStyles(worksheet, colDefs) {
+    colDefs.forEach((def, idx) => {
+        const col = worksheet.getColumn(idx + 1);
+        if (def.numFmt) {
+            col.numFmt = def.numFmt;
+        }
+        if (def.alignment) {
+            col.alignment = { horizontal: def.alignment };
+        }
+    });
+}
+/**
+ * Sanitise a sheet name to be valid in Excel (max 31 chars, no special chars).
+ */
+function sanitiseSheetName(name) {
+    return name.replace(/[:\\/?*\[\]]/g, '').slice(0, 31) || 'Sheet';
+}
+//# sourceMappingURL=styleUtils.js.map

package/dist/spreadsheet/src/utils/styleUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styleUtils.js","sourceRoot":"","sources":["../../../../core/spreadsheet/src/utils/styleUtils.ts"],"names":[],"mappings":"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"}

package/dist/system/config-manager/config-loader.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Config Loader
+ *
+ * Scans all .config files under APP_CONFIG_ROOT recursively at startup,
+ * evaluates them (supports JS object expression format: `({...})`),
+ * and stores them in AppConfig as a key→value map where:
+ *   key   = relative path  e.g. "myapp/all/vi.config"
+ *   value = evaluated JS object from the file
+ *
+ * Usage anywhere in the app:
+ *   import { getConfig, getAllConfigs, reloadConfigs } from '@server/core/config-loader';
+ *   const viConfig = getConfig('myapp/all/vi.config');
+ */
+/**
+ * Loads (or reloads) all .config files from APP_CONFIG_ROOT into AppConfig.
+ * Called once at startup and again via the /reload-configs API.
+ * Returns the full map of { relativePath → configObject }.
+ */
+export declare function loadAllConfigs(): Record<string, any>;
+/**
+ * Re-scans and re-evaluates all config files.
+ * Call this from the reload API after adding or editing a file.
+ */
+export declare function reloadConfigs(): Record<string, any>;
+/**
+ * Reloads a single config file by its relative path into the in-memory map.
+ * Returns the updated config object, or null if the file doesn't exist.
+ */
+export declare function reloadConfig(relativePath: string): any;
+/**
+ * Get a single config by its relative path.
+ * Returns null if not found — call reloadConfigs() first if you just added the file.
+ */
+export declare function getConfig(relativePath: string): any;
+/**
+ * Returns the full key→value map of all loaded configs.
+ * Functions inside configs (e.g. `load`) are present but will be stripped
+ * by JSON.stringify — use getConfig() and call them directly server-side.
+ */
+export declare function getAllConfigs(): Record<string, any>;
+/**
+ * Returns a JSON-safe summary of all loaded configs.
+ * Functions are replaced with the string "[Function]" so the output is serialisable.
+ */
+export declare function getAllConfigsSafe(): Record<string, any>;
+/**
+ * Renames a key inside the in-memory map: removes the old key and adds the
+ * evaluated content under the new key. The caller is responsible for the
+ * actual file rename on disk before calling this.
+ */
+export declare function renameConfigInMemory(oldRelativePath: string, newRelativePath: string): any;
+/**
+ * Removes a single config from the in-memory map without touching the file.
+ * Call this when a config file is marked inactive.
+ */
+export declare function unloadConfig(relativePath: string): void;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/system/config-manager/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../../core/system/config-manager/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsCH;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwCpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEnD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CA4BtD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQvD;AAeD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,GAAG,CAgB1F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAQvD"}