@jagilber-org/index-server 1.19.1

package/dist/services/auditLog.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithCorrelation = runWithCorrelation;
+exports.getCurrentCorrelationId = getCurrentCorrelationId;
+exports.resetAuditLogCache = resetAuditLogCache;
+exports.logAudit = logAudit;
+exports.logToolAudit = logToolAudit;
+exports.logHttpAudit = logHttpAudit;
+exports.readAuditEntries = readAuditEntries;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const async_hooks_1 = require("async_hooks");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const toolRegistry_1 = require("./toolRegistry");
+// Append-only JSONL audit log for all server operations.
+// Each line: { ts, kind, action, ids?, meta? }
+// kind: 'mutation' | 'read' | 'http' — classifies the entry type.
+// Path and enablement are driven by runtime configuration (instructions.auditLog).
+// AsyncLocalStorage carries the correlation ID from registry wrapper into handler scope.
+// This lets logAudit() calls inside handlers automatically include correlationId
+// without changing handler signatures or passing context explicitly.
+const auditContext = new async_hooks_1.AsyncLocalStorage();
+/** Run a function with a correlation ID accessible to all logAudit() calls within. */
+function runWithCorrelation(correlationId, fn) {
+    return auditContext.run({ correlationId }, fn);
+}
+/** Get the current correlation ID from the async context (if any). */
+function getCurrentCorrelationId() {
+    return auditContext.getStore()?.correlationId;
+}
+let cachedKey;
+let cachedPath;
+function resolveLogPath() {
+    const { auditLog } = (0, runtimeConfig_1.getRuntimeConfig)().instructions;
+    const key = auditLog.enabled && auditLog.file ? `on:${auditLog.file}` : 'off';
+    if (cachedKey === key && cachedPath !== undefined) {
+        return cachedPath;
+    }
+    cachedKey = key;
+    if (!auditLog.enabled || !auditLog.file) {
+        cachedPath = null;
+        return cachedPath;
+    }
+    const file = auditLog.file;
+    try {
+        const dir = path_1.default.dirname(file);
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.appendFileSync(file, '');
+        cachedPath = file;
+    }
+    catch {
+        cachedPath = null;
+    }
+    return cachedPath;
+}
+/** Reset the cached audit log path, forcing re-resolution on next write. */
+function resetAuditLogCache() {
+    cachedKey = undefined;
+    cachedPath = undefined;
+}
+/**
+ * Append an entry to the audit log file. Silent no-op when logging is disabled.
+ * @param action - Tool or operation name being recorded
+ * @param ids - Instruction IDs affected by this operation (if any)
+ * @param meta - Lightweight result summary (counts, flags, etc.)
+ * @param kind - Entry classification; defaults to `'mutation'`
+ */
+function logAudit(action, ids, meta, kind) {
+    const file = resolveLogPath();
+    if (!file)
+        return; // silent no-op when logging disabled
+    const entry = { ts: new Date().toISOString(), kind: kind ?? 'mutation', action };
+    if (ids) {
+        entry.ids = Array.isArray(ids) ? ids : [ids];
+    }
+    // Auto-inject correlationId from async context if not already present in meta
+    const ctxCorr = getCurrentCorrelationId();
+    if (ctxCorr || meta) {
+        const m = meta ? { ...meta } : {};
+        if (ctxCorr && !m.correlationId)
+            m.correlationId = ctxCorr;
+        entry.meta = m;
+    }
+    try {
+        fs_1.default.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+    }
+    catch { /* swallow logging errors to avoid impacting primary operation path */ }
+}
+/**
+ * Log a tool invocation to the audit trail. Called from the registry wrapper
+ * so ALL tool calls (reads + mutations) are captured automatically.
+ */
+function logToolAudit(toolName, success, durationMs, correlationId, errorType) {
+    const kind = toolRegistry_1.MUTATION.has(toolName) ? 'mutation' : 'read';
+    const meta = { success, durationMs: Math.round(durationMs * 100) / 100 };
+    if (correlationId)
+        meta.correlationId = correlationId;
+    if (!success && errorType)
+        meta.errorType = errorType;
+    logAudit(toolName, undefined, meta, kind);
+}
+/**
+ * Log an HTTP request to the audit trail. Called from dashboard middleware
+ * so all API requests are captured with client IP and user-agent.
+ */
+function logHttpAudit(method, route, statusCode, durationMs, clientIp, userAgent) {
+    const meta = { statusCode, durationMs: Math.round(durationMs * 100) / 100 };
+    if (clientIp)
+        meta.clientIp = clientIp;
+    if (userAgent)
+        meta.userAgent = userAgent;
+    logAudit(`${method} ${route}`, undefined, meta, 'http');
+}
+/**
+ * Read the most recent audit log entries from disk.
+ * @param limit - Maximum number of lines to return from the tail of the file (default 1000)
+ * @returns Parsed audit entries, or an empty array if logging is disabled or the file is missing
+ */
+function readAuditEntries(limit = 1000) {
+    const file = resolveLogPath();
+    if (!file || !fs_1.default.existsSync(file))
+        return [];
+    try {
+        const lines = fs_1.default.readFileSync(file, 'utf8').split(/\r?\n/).filter(l => l.trim());
+        const recent = lines.slice(-limit);
+        const parsed = [];
+        for (const l of recent) {
+            try {
+                parsed.push(JSON.parse(l));
+            }
+            catch { /* ignore */ }
+        }
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/services/autoBackup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run a single auto-backup cycle. Returns the backup zip file path,
+ * or null if the instructions directory is empty / doesn't exist.
+ */
+export declare function runAutoBackupOnce(): string | null;
+/**
+ * Start the periodic auto-backup timer. Returns the interval handle.
+ * No-op if already running.
+ */
+export declare function startAutoBackup(): ReturnType<typeof setInterval> | null;
+/**
+ * Stop the periodic auto-backup timer.
+ */
+export declare function stopAutoBackup(): void;

package/dist/services/autoBackup.js

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAutoBackupOnce = runAutoBackupOnce;
+exports.startAutoBackup = startAutoBackup;
+exports.stopAutoBackup = stopAutoBackup;
+/**
+ * Automatic periodic backup of the instruction index.
+ *
+ * Creates zip archives of all .json files from the instructions directory
+ * into the configured backups directory. Old auto-backups are pruned when
+ * their count exceeds the configured maximum.
+ *
+ * Env vars (via runtimeConfig.mutation):
+ *   INDEX_SERVER_AUTO_BACKUP_INTERVAL_MS — timer interval (default 3600000 = 1h)
+ *   INDEX_SERVER_AUTO_BACKUP_MAX_COUNT   — max retained auto-backups (default 10)
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const backupZip_1 = require("./backupZip");
+const AUTO_BACKUP_PREFIX = 'auto-backup-';
+let _timer = null;
+function getInstructionsDir() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().index.baseDir;
+}
+function getBackupsDir() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().dashboard.admin.backupsDir;
+}
+/**
+ * Run a single auto-backup cycle. Returns the backup zip file path,
+ * or null if the instructions directory is empty / doesn't exist.
+ */
+function runAutoBackupOnce() {
+    const instrDir = getInstructionsDir();
+    if (!fs_1.default.existsSync(instrDir))
+        return null;
+    const backupsRoot = getBackupsDir();
+    fs_1.default.mkdirSync(backupsRoot, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15);
+    let zipPath = path_1.default.join(backupsRoot, `${AUTO_BACKUP_PREFIX}${stamp}.zip`);
+    let i = 1;
+    while (fs_1.default.existsSync(zipPath)) {
+        zipPath = path_1.default.join(backupsRoot, `${AUTO_BACKUP_PREFIX}${stamp}-${i++}.zip`);
+    }
+    // Backup SQLite DB if present — still uses a directory for binary DB files
+    const storageBackend = (0, runtimeConfig_1.getRuntimeConfig)().storage?.backend ?? 'json';
+    if (storageBackend === 'sqlite') {
+        const sqlitePath = (0, runtimeConfig_1.getRuntimeConfig)().storage?.sqlitePath;
+        if (sqlitePath && fs_1.default.existsSync(sqlitePath)) {
+            const backupDir = zipPath.replace(/\.zip$/, '');
+            fs_1.default.mkdirSync(backupDir, { recursive: true });
+            fs_1.default.copyFileSync(sqlitePath, path_1.default.join(backupDir, 'index.db'));
+            if (fs_1.default.existsSync(sqlitePath + '-wal'))
+                fs_1.default.copyFileSync(sqlitePath + '-wal', path_1.default.join(backupDir, 'index.db-wal'));
+            if (fs_1.default.existsSync(sqlitePath + '-shm'))
+                fs_1.default.copyFileSync(sqlitePath + '-shm', path_1.default.join(backupDir, 'index.db-shm'));
+            pruneOldBackups(backupsRoot);
+            try {
+                process.stderr.write(`[auto-backup] created ${backupDir} (sqlite)\n`);
+            }
+            catch { /* ignore */ }
+            return backupDir;
+        }
+    }
+    // Default: backup JSON files into a zip
+    const files = fs_1.default.readdirSync(instrDir).filter(f => f.endsWith('.json'));
+    if (files.length === 0)
+        return null;
+    const { zipPath: resultPath, fileCount } = (0, backupZip_1.createZipBackup)(instrDir, zipPath);
+    // Prune old auto-backups beyond maxCount
+    pruneOldBackups(backupsRoot);
+    try {
+        process.stderr.write(`[auto-backup] created ${resultPath} (${fileCount} files)\n`);
+    }
+    catch { /* ignore */ }
+    return resultPath;
+}
+function pruneOldBackups(backupsRoot) {
+    const maxCount = (0, runtimeConfig_1.getRuntimeConfig)().mutation.autoBackupMaxCount;
+    try {
+        const entries = fs_1.default.readdirSync(backupsRoot)
+            .filter(d => {
+            if (!d.startsWith(AUTO_BACKUP_PREFIX))
+                return false;
+            const full = path_1.default.join(backupsRoot, d);
+            // Accept both zip files and legacy directories
+            return d.endsWith('.zip') ? fs_1.default.statSync(full).isFile() : fs_1.default.statSync(full).isDirectory();
+        })
+            .sort(); // lexicographic = chronological for ISO timestamps
+        while (entries.length > maxCount) {
+            const oldest = entries.shift();
+            const full = path_1.default.join(backupsRoot, oldest);
+            if (oldest.endsWith('.zip')) {
+                fs_1.default.unlinkSync(full);
+            }
+            else {
+                fs_1.default.rmSync(full, { recursive: true, force: true });
+            }
+            try {
+                process.stderr.write(`[auto-backup] pruned old backup: ${oldest}\n`);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch (e) {
+        try {
+            process.stderr.write(`[auto-backup] pruning failed: ${e}\n`);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Start the periodic auto-backup timer. Returns the interval handle.
+ * No-op if already running.
+ */
+function startAutoBackup() {
+    if (_timer)
+        return _timer;
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)().mutation;
+    if (!cfg.autoBackupEnabled) {
+        try {
+            process.stderr.write('[auto-backup] disabled (INDEX_SERVER_AUTO_BACKUP=0)\n');
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    const intervalMs = cfg.autoBackupIntervalMs;
+    if (intervalMs <= 0)
+        return null;
+    _timer = setInterval(() => {
+        try {
+            runAutoBackupOnce();
+        }
+        catch (e) {
+            try {
+                process.stderr.write(`[auto-backup] interval run failed: ${e}\n`);
+            }
+            catch { /* ignore */ }
+        }
+    }, intervalMs);
+    // Unref so the timer doesn't keep the process alive
+    if (_timer && typeof _timer.unref === 'function')
+        _timer.unref();
+    // Run first backup after a short delay (don't block caller)
+    setTimeout(() => { try {
+        runAutoBackupOnce();
+    }
+    catch (e) {
+        try {
+            process.stderr.write(`[auto-backup] initial run failed: ${e}\n`);
+        }
+        catch { /* ignore */ }
+    } }, 5000).unref();
+    try {
+        process.stderr.write(`[auto-backup] started (interval=${intervalMs}ms, maxCount=${(0, runtimeConfig_1.getRuntimeConfig)().mutation.autoBackupMaxCount})\n`);
+    }
+    catch { /* ignore */ }
+    return _timer;
+}
+/**
+ * Stop the periodic auto-backup timer.
+ */
+function stopAutoBackup() {
+    if (_timer) {
+        clearInterval(_timer);
+        _timer = null;
+    }
+}

package/dist/services/autoSplit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Auto-split oversized instruction entries into cross-linked sub-instructions.
+ * Used by the index loader on startup to handle entries written directly to disk
+ * by agents that bypass MCP tool size validation.
+ */
+interface InstructionLike {
+    id: string;
+    title: string;
+    body: string;
+    priority: number;
+    audience: string;
+    requirement: string;
+    categories: string[];
+    schemaVersion?: string;
+    [key: string]: unknown;
+}
+/**
+ * Split an oversized instruction entry into multiple parts that each fit within the body limit.
+ * If the entry body is within the limit, returns a single-element array with the original entry.
+ *
+ * Splitting strategy:
+ * 1. Attempt to split by markdown H2 headings (## Section)
+ * 2. If sections are still too large, split by paragraphs (double newline)
+ * 3. As a last resort, split at character boundaries
+ *
+ * Each part gets:
+ * - Sequential ID: `{original-id}-part-{n}`
+ * - Preserved metadata (priority, audience, requirement, categories)
+ * - Cross-link footer referencing all sibling parts
+ */
+export declare function splitOversizedEntry(entry: InstructionLike, maxLength: number): InstructionLike[];
+export {};

package/dist/services/autoSplit.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Auto-split oversized instruction entries into cross-linked sub-instructions.
+ * Used by the index loader on startup to handle entries written directly to disk
+ * by agents that bypass MCP tool size validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitOversizedEntry = splitOversizedEntry;
+/**
+ * Split an oversized instruction entry into multiple parts that each fit within the body limit.
+ * If the entry body is within the limit, returns a single-element array with the original entry.
+ *
+ * Splitting strategy:
+ * 1. Attempt to split by markdown H2 headings (## Section)
+ * 2. If sections are still too large, split by paragraphs (double newline)
+ * 3. As a last resort, split at character boundaries
+ *
+ * Each part gets:
+ * - Sequential ID: `{original-id}-part-{n}`
+ * - Preserved metadata (priority, audience, requirement, categories)
+ * - Cross-link footer referencing all sibling parts
+ */
+function splitOversizedEntry(entry, maxLength) {
+    if (entry.body.length <= maxLength) {
+        return [{ ...entry }];
+    }
+    // Try heading-based split first
+    let chunks = splitByHeadings(entry.body);
+    // If any chunk is still too large, further split by paragraphs
+    chunks = chunks.flatMap(chunk => chunk.length > maxLength ? splitByParagraphs(chunk, maxLength) : [chunk]);
+    // Last resort: hard split at character boundary
+    chunks = chunks.flatMap(chunk => chunk.length > maxLength ? hardSplit(chunk, maxLength) : [chunk]);
+    // Merge tiny trailing chunks into the previous one when possible
+    const merged = [];
+    for (const chunk of chunks) {
+        if (merged.length > 0 && merged[merged.length - 1].length + chunk.length + 2 <= maxLength) {
+            merged[merged.length - 1] += '\n\n' + chunk;
+        }
+        else {
+            merged.push(chunk);
+        }
+    }
+    // If merging produced a single chunk (edge case), return as-is
+    if (merged.length <= 1) {
+        return [{ ...entry, body: merged[0] || entry.body.slice(0, maxLength) }];
+    }
+    // Generate part IDs
+    const partIds = merged.map((_, i) => `${entry.id}-part-${i + 1}`);
+    // Build cross-link footer
+    const parts = merged.map((chunk, i) => {
+        const siblingIds = partIds.filter((_, j) => j !== i);
+        const crossLinkFooter = `\n\n---\n**Cross-linked parts:** ${siblingIds.join(', ')}`;
+        // Reserve space for footer in body
+        const maxBodyContent = maxLength - crossLinkFooter.length;
+        const bodyContent = chunk.length > maxBodyContent ? chunk.slice(0, maxBodyContent) : chunk;
+        const { body: _body, id: _id, title: _title, ...rest } = entry;
+        return {
+            ...rest,
+            id: partIds[i],
+            title: `${entry.title} (Part ${i + 1}/${merged.length})`,
+            body: bodyContent + crossLinkFooter,
+            categories: [...entry.categories],
+        };
+    });
+    return parts;
+}
+/** Split body text at ## heading boundaries */
+function splitByHeadings(body) {
+    const headingPattern = /^## /m;
+    if (!headingPattern.test(body))
+        return [body];
+    const parts = [];
+    const lines = body.split('\n');
+    let current = [];
+    for (const line of lines) {
+        if (/^## /.test(line) && current.length > 0) {
+            parts.push(current.join('\n').trim());
+            current = [];
+        }
+        current.push(line);
+    }
+    if (current.length > 0) {
+        parts.push(current.join('\n').trim());
+    }
+    return parts.filter(p => p.length > 0);
+}
+/** Split a chunk by double-newline paragraph boundaries */
+function splitByParagraphs(text, maxLength) {
+    const paragraphs = text.split(/\n\n+/);
+    const chunks = [];
+    let current = '';
+    for (const para of paragraphs) {
+        if (current.length + para.length + 2 > maxLength && current.length > 0) {
+            chunks.push(current.trim());
+            current = para;
+        }
+        else {
+            current = current ? current + '\n\n' + para : para;
+        }
+    }
+    if (current.trim()) {
+        chunks.push(current.trim());
+    }
+    return chunks;
+}
+/** Hard split at character boundaries (last resort) */
+function hardSplit(text, maxLength) {
+    const chunks = [];
+    for (let i = 0; i < text.length; i += maxLength) {
+        chunks.push(text.slice(i, i + maxLength));
+    }
+    return chunks;
+}

package/dist/services/backupZip.d.ts

@@ -0,0 +1,25 @@
+/** Create a zip from every .json file in `sourceDir`. Returns the written zip path. */
+export declare function createZipBackup(sourceDir: string, outputZipPath: string): {
+    zipPath: string;
+    fileCount: number;
+};
+/**
+ * Create a zip that also includes a manifest.json entry.
+ * The manifest is written as an in-memory entry (not read from disk).
+ */
+export declare function createZipBackupWithManifest(sourceDir: string, outputZipPath: string, manifest: Record<string, unknown>): {
+    zipPath: string;
+    fileCount: number;
+};
+/** Extract all .json files from a zip into `targetDir`. Returns count of extracted files. */
+export declare function extractZipBackup(zipPath: string, targetDir: string): number;
+/** Read and parse the manifest.json from inside a zip (if present). */
+export declare function readZipManifest(zipPath: string): Record<string, unknown> | null;
+/** List .json filenames inside a zip (excluding manifest.json). */
+export declare function listZipInstructionFiles(zipPath: string): string[];
+/** Read a single file from a zip as parsed JSON. */
+export declare function readZipEntry(zipPath: string, entryName: string): unknown | null;
+/** Get size of a zip file in bytes. */
+export declare function getZipSizeBytes(zipPath: string): number;
+/** Check whether a path is a zip backup (by extension). */
+export declare function isZipBackup(filePath: string): boolean;

package/dist/services/backupZip.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createZipBackup = createZipBackup;
+exports.createZipBackupWithManifest = createZipBackupWithManifest;
+exports.extractZipBackup = extractZipBackup;
+exports.readZipManifest = readZipManifest;
+exports.listZipInstructionFiles = listZipInstructionFiles;
+exports.readZipEntry = readZipEntry;
+exports.getZipSizeBytes = getZipSizeBytes;
+exports.isZipBackup = isZipBackup;
+/**
+ * Shared zip-based backup utilities.
+ *
+ * All backup producers (autoBackup, bulk-delete, AdminPanel) converge here
+ * so there is a single implementation for creating, reading, and extracting
+ * zip backup archives.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+/** Create a zip from every .json file in `sourceDir`. Returns the written zip path. */
+function createZipBackup(sourceDir, outputZipPath) {
+    const zip = new adm_zip_1.default();
+    const files = fs_1.default.readdirSync(sourceDir).filter(f => f.endsWith('.json'));
+    for (const f of files) {
+        zip.addLocalFile(path_1.default.join(sourceDir, f));
+    }
+    zip.writeZip(outputZipPath);
+    return { zipPath: outputZipPath, fileCount: files.length };
+}
+/**
+ * Create a zip that also includes a manifest.json entry.
+ * The manifest is written as an in-memory entry (not read from disk).
+ */
+function createZipBackupWithManifest(sourceDir, outputZipPath, manifest) {
+    const zip = new adm_zip_1.default();
+    const files = fs_1.default.readdirSync(sourceDir).filter(f => f.endsWith('.json'));
+    for (const f of files) {
+        zip.addLocalFile(path_1.default.join(sourceDir, f));
+    }
+    zip.addFile('manifest.json', Buffer.from(JSON.stringify(manifest, null, 2)));
+    zip.writeZip(outputZipPath);
+    return { zipPath: outputZipPath, fileCount: files.length };
+}
+/** Extract all .json files from a zip into `targetDir`. Returns count of extracted files. */
+function extractZipBackup(zipPath, targetDir) {
+    if (!fs_1.default.existsSync(targetDir))
+        fs_1.default.mkdirSync(targetDir, { recursive: true });
+    const zip = new adm_zip_1.default(zipPath);
+    let count = 0;
+    for (const entry of zip.getEntries()) {
+        const name = path_1.default.basename(entry.entryName);
+        if (!name.toLowerCase().endsWith('.json'))
+            continue;
+        if (name.includes('..') || name !== entry.entryName)
+            continue; // path traversal guard
+        fs_1.default.writeFileSync(path_1.default.join(targetDir, name), entry.getData());
+        count++;
+    }
+    return count;
+}
+/** Read and parse the manifest.json from inside a zip (if present). */
+function readZipManifest(zipPath) {
+    try {
+        const zip = new adm_zip_1.default(zipPath);
+        const entry = zip.getEntry('manifest.json');
+        if (!entry)
+            return null;
+        return JSON.parse(entry.getData().toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** List .json filenames inside a zip (excluding manifest.json). */
+function listZipInstructionFiles(zipPath) {
+    const zip = new adm_zip_1.default(zipPath);
+    return zip.getEntries()
+        .map(e => e.entryName)
+        .filter(n => n.toLowerCase().endsWith('.json') && n !== 'manifest.json');
+}
+/** Read a single file from a zip as parsed JSON. */
+function readZipEntry(zipPath, entryName) {
+    try {
+        const zip = new adm_zip_1.default(zipPath);
+        const entry = zip.getEntry(entryName);
+        if (!entry)
+            return null;
+        return JSON.parse(entry.getData().toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Get size of a zip file in bytes. */
+function getZipSizeBytes(zipPath) {
+    try {
+        return fs_1.default.statSync(zipPath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Check whether a path is a zip backup (by extension). */
+function isZipBackup(filePath) {
+    return filePath.toLowerCase().endsWith('.zip');
+}