@nmakarov/cli-toolkit 0.16.0 → 0.18.0

package/dist/http-client2.js

@@ -1,3 +1,6 @@
+// src/http-client2/index.ts
+import path4 from "path";
+
 // src/errors.ts
 var FrameworkError = class extends Error {
   constructor(message) {
@@ -5,6 +8,12 @@ var FrameworkError = class extends Error {
     this.name = "FrameworkError";
   }
 };
+var ParamError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "ParamError";
+  }
+};
 var HttpClientError = class extends FrameworkError {
   constructor(message, cause) {
     super(message);
@@ -12,6 +21,12 @@ var HttpClientError = class extends FrameworkError {
     this.name = "HttpClientError";
   }
 };
+var FileDatabaseError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
 
 // src/http-client2/errors.ts
 function classifyError(error) {
@@ -113,6 +128,1201 @@ function shouldRetryError(classification) {
   return classification.retryable;
 }
 
+// src/filedatabase/index.ts
+import fs3 from "fs";
+import path3 from "path";
+
+// src/utils/os-utils.ts
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+function getFreeDiskSpace(targetPath) {
+  try {
+    let pathToCheck = targetPath;
+    if (!fs.existsSync(targetPath)) {
+      const parentDir = path.dirname(targetPath);
+      if (fs.existsSync(parentDir)) {
+        pathToCheck = parentDir;
+      } else {
+        pathToCheck = process.platform === "win32" ? "C:\\" : "/";
+      }
+    }
+    if (process.platform === "win32") {
+      return null;
+    } else {
+      const stdout = execSync(`df -k "${pathToCheck}"`, { encoding: "utf8" });
+      const lines = stdout.trim().split("\n");
+      const parts = lines[1].split(/\s+/);
+      const freeKb = parseInt(parts[3], 10);
+      return freeKb * 1024;
+    }
+  } catch (error) {
+    return null;
+  }
+}
+
+// src/utils/fs-utils.ts
+import fs2 from "fs";
+import path2 from "path";
+async function ensurePath(...pathParts) {
+  const fullPath = path2.resolve(...pathParts);
+  if (!fs2.existsSync(fullPath)) {
+    await fs2.promises.mkdir(fullPath, { recursive: true });
+  }
+  return fullPath;
+}
+function getFileExtension(dataType) {
+  switch (dataType) {
+    case "json-array":
+    case "json-object":
+      return "json";
+    case "text":
+      return "txt";
+    case "xml":
+      return "xml";
+    default:
+      return "json";
+  }
+}
+
+// src/utils/format-utils.ts
+function bytesToHumanReadable(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+// src/utils/date-utils.ts
+function isTimestampFolder(folderName) {
+  const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|\.\d{3}Z)$/;
+  if (!isoRegex.test(folderName)) {
+    return false;
+  }
+  const date = new Date(folderName);
+  return !isNaN(date.getTime()) && date.getTime() > 0;
+}
+
+// src/filedatabase/serializers.ts
+function detectDataType(data) {
+  if (Array.isArray(data)) {
+    return "json-array";
+  } else if (typeof data === "object" && data !== null) {
+    return "json-object";
+  } else if (typeof data === "string") {
+    const trimmed = data.trim();
+    if (trimmed.startsWith("<?xml") || trimmed.startsWith("<")) {
+      return "xml";
+    }
+    return "text";
+  } else {
+    return "text";
+  }
+}
+function serializeData(data) {
+  const dataType = detectDataType(data);
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.stringify(data, null, 4);
+  } else {
+    return String(data);
+  }
+}
+function deserializeData(rawData, dataType) {
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.parse(rawData);
+  } else {
+    return rawData;
+  }
+}
+
+// src/filedatabase/index.ts
+var FileDatabase = class _FileDatabase {
+  basePath;
+  namespace;
+  tableName = null;
+  versioned;
+  maxVersions;
+  pageSize;
+  useMetadata;
+  freeSpaceThreshold;
+  logger;
+  // Current operation state
+  currentVersion = null;
+  currentVersionFolder = null;
+  currentFileNumber = 0;
+  currentRecord = 0;
+  hasReadFirstPage = false;
+  lastFileData = null;
+  metadata;
+  // Synopsis calculation functions
+  fileSynopsisFunction = null;
+  versionSynopsisFunction = null;
+  /**
+   * Constructor - accepts context as first parameter (new pattern)
+   * or config object (legacy pattern for backward compatibility)
+   */
+  constructor(contextOrConfig, options) {
+    let config;
+    if (contextOrConfig && typeof contextOrConfig === "object" && "params" in contextOrConfig) {
+      const context = contextOrConfig;
+      const opts = options || {};
+      const defs = {
+        basePath: "string default ./data",
+        namespace: "string default default",
+        tableName: "string",
+        maxVersions: "number default 5",
+        pageSize: "number default 5000"
+      };
+      const discovered = context.params.getAllForModule(defs);
+      config = { ...discovered, ...opts, logger: context.logger };
+    } else {
+      config = contextOrConfig;
+    }
+    if (!config.basePath) {
+      throw new ParamError("[FileDatabase] basePath is required");
+    }
+    this.basePath = config.basePath;
+    this.namespace = config.namespace || "default";
+    this.tableName = config.tableName || null;
+    this.versioned = config.versioned ?? true;
+    this.maxVersions = config.maxVersions || 5;
+    this.pageSize = config.pageSize || 5e3;
+    this.useMetadata = config.useMetadata !== false;
+    this.freeSpaceThreshold = config.freeSpaceThreshold || 100 * 1024 * 1024;
+    this.logger = config.logger || console;
+    this.metadata = this.getDefaultMetadata();
+  }
+  /**
+   * Initialize FileDatabase from context and options.
+   * Params are read via getAllForModule("filedatabase", defs) for --showUsedParams grouping.
+   */
+  static init(context, options) {
+    return new _FileDatabase(context, options ?? {});
+  }
+  /**
+   * Get default metadata structure
+   */
+  getDefaultMetadata() {
+    return {
+      version: this.currentVersion || null,
+      files: [],
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      modifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalRecords: 0,
+      synopsis: null,
+      dataType: null
+    };
+  }
+  /**
+   * Get the destination path (basePath/namespace/tableName[/version])
+   */
+  getDestinationPath(version) {
+    const errors = ["basePath", "namespace", "tableName"].filter((prop) => !this[prop]).map((prop) => `${prop} is not set`);
+    if (errors.length) {
+      throw new FileDatabaseError(`[FileDatabase] ${errors.join("; ")}`);
+    }
+    let parts = [this.basePath, this.namespace];
+    if (this.tableName) {
+      parts.push(...this.tableName.split("/"));
+    }
+    if (this.versioned && version) {
+      parts.push(version);
+    }
+    return path3.resolve(...parts);
+  }
+  /**
+   * Set current version and version folder
+   */
+  async setCurrentVersion(version) {
+    this.currentVersion = version;
+    this.currentVersionFolder = await ensurePath(this.getDestinationPath(), version);
+  }
+  /**
+   * Create a new version folder with comprehensive timestamp logic
+   * Only works in versioned mode
+   */
+  async makeNewVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("makeNewVersion() only works in versioned mode");
+    }
+    this.metadata = this.getDefaultMetadata();
+    const existingVersions = await this.getVersions();
+    let versionName;
+    if (existingVersions.length > 0) {
+      const maxTimestamp = existingVersions.reduce((max, version) => {
+        const versionDate = new Date(version.replace("Z", ""));
+        const maxDate2 = new Date(max.replace("Z", ""));
+        return versionDate > maxDate2 ? version : max;
+      });
+      const maxDate = new Date(maxTimestamp.replace("Z", ""));
+      const nextDate = new Date(maxDate.getTime() + 1e3);
+      versionName = nextDate.toISOString().split(".")[0] + "Z";
+    } else {
+      const now = /* @__PURE__ */ new Date();
+      versionName = now.toISOString().split(".")[0] + "Z";
+    }
+    await this.setCurrentVersion(versionName);
+    this.currentFileNumber = 0;
+    const versions = await this.getVersions();
+    while (versions.length > this.maxVersions) {
+      const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
+    }
+    return versionName;
+  }
+  /**
+   * Get list of all versions (sorted chronologically)
+   * Only works in versioned mode
+   */
+  async getVersions() {
+    if (!this.versioned) {
+      return [];
+    }
+    const destPath = this.getDestinationPath();
+    try {
+      await ensurePath(destPath);
+      const items = await fs3.promises.readdir(destPath);
+      const versions = items.filter((item) => {
+        const itemPath = path3.join(destPath, item);
+        const stat = fs3.statSync(itemPath);
+        return stat.isDirectory() && isTimestampFolder(item);
+      });
+      return versions.sort();
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get the latest version (most recent timestamp)
+   * Only works in versioned mode
+   * @returns Latest version string or null if no versions
+   */
+  async getLatestVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("getLatestVersion() only works in versioned mode");
+    }
+    const versions = await this.getVersions();
+    if (versions.length === 0) {
+      return null;
+    }
+    return versions[versions.length - 1];
+  }
+  /**
+   * Check if any data exists in this table
+   * Works for both versioned and non-versioned modes
+   * @returns true if data exists
+   */
+  async hasData() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await fs3.promises.readdir(tablePath);
+      return items.some(
+        (item) => item === "metadata.json" || item.match(/^\d{6}\.(json|txt|xml)$/) || item.endsWith(".json")
+      );
+    }
+  }
+  /**
+   * Auto-detect the data format in this table
+   * Used when reading existing data
+   * @returns Format detection result
+   */
+  async detectDataFormat() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await fs3.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await fs3.promises.readFile(path3.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = path3.join(tablePath, item);
+      const stat = fs3.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = path3.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: fs3.existsSync(versionMetadataPath),
+        dataType: null
+      };
+    }
+    const dataFiles = items.filter((f) => f.match(/^\d{6}\.(json|txt|xml)$/));
+    if (dataFiles.length > 0) {
+      return {
+        versioned: false,
+        hasMetadata: false,
+        dataType: null
+      };
+    }
+    return { versioned: false, hasMetadata: false, dataType: null };
+  }
+  /**
+   * Load metadata from JSON file
+   */
+  async loadMetadataJson(version) {
+    const metadataFile = path3.join(this.getDestinationPath(), version, "metadata.json");
+    if (fs3.existsSync(metadataFile)) {
+      try {
+        const rawData = await fs3.promises.readFile(metadataFile, "utf8");
+        return JSON.parse(rawData);
+      } catch (e) {
+        throw new FileDatabaseError(`Failed to read metadata for version "${version}": ${e.message}`);
+      }
+    }
+    return null;
+  }
+  /**
+   * Build metadata by scanning files in a version folder (backward compatibility)
+   * Reads all files to get accurate counts - used when synopsis calculation is needed
+   */
+  async figureMetadataFromVersionFiles(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = [];
+    let totalRecords = 0;
+    let detectedDataType = null;
+    for (let i = 0; i < files.length; i++) {
+      const fileName = files[i];
+      const filePath = path3.join(versionPath, fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const extension = path3.extname(fileName).toLowerCase();
+        let dataType = "text";
+        if (extension === ".json") {
+          dataType = "json-array";
+        } else if (extension === ".xml") {
+          dataType = "xml";
+        }
+        const fileData = deserializeData(rawData, dataType);
+        const recordsCount = Array.isArray(fileData) ? fileData.length : 1;
+        if (detectedDataType === null) {
+          detectedDataType = detectDataType(fileData);
+        }
+        const fileInfo = {
+          number: i + 1,
+          recordsCount,
+          fileName
+        };
+        metadata.files.push(fileInfo);
+        totalRecords += recordsCount;
+      } catch (error) {
+        this.logger.error?.(`[FileDatabase] Failed to read file ${fileName}: ${error.message}`);
+      }
+    }
+    metadata.totalRecords = totalRecords;
+    metadata.dataType = detectedDataType;
+    return metadata;
+  }
+  /**
+   * Build metadata optimized - only reads first and last files
+   * Assumes all middle files have the same record count as the first file
+   * Much faster for large datasets with many files
+   */
+  async buildMetadataOptimized(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    if (files.length === 0) {
+      return this.getDefaultMetadata();
+    }
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = files.map((fileName, index) => ({
+      number: index + 1,
+      recordsCount: 0,
+      fileName
+    }));
+    const firstFile = metadata.files[0];
+    const firstFilePath = path3.join(versionPath, firstFile.fileName);
+    const firstFileRaw = await fs3.promises.readFile(firstFilePath, "utf8");
+    let firstFileData;
+    try {
+      firstFileData = JSON.parse(firstFileRaw);
+    } catch (e) {
+      firstFileData = firstFileRaw;
+    }
+    metadata.dataType = detectDataType(firstFileData);
+    if (metadata.dataType === "json-array") {
+      const firstFileCount = Array.isArray(firstFileData) ? firstFileData.length : 1;
+      firstFile.recordsCount = firstFileCount;
+      for (let i = 1; i < metadata.files.length - 1; i++) {
+        metadata.files[i].recordsCount = firstFileCount;
+      }
+      if (files.length > 1) {
+        const lastFile = metadata.files[metadata.files.length - 1];
+        const lastFilePath = path3.join(versionPath, lastFile.fileName);
+        const lastFileRaw = await fs3.promises.readFile(lastFilePath, "utf8");
+        const lastFileData = deserializeData(lastFileRaw, metadata.dataType);
+        lastFile.recordsCount = Array.isArray(lastFileData) ? lastFileData.length : 1;
+      }
+      metadata.totalRecords = metadata.files.reduce((sum, file) => sum + file.recordsCount, 0);
+    } else {
+      metadata.files.forEach((file) => {
+        file.recordsCount = 1;
+      });
+      metadata.totalRecords = files.length;
+    }
+    return metadata;
+  }
+  /**
+   * Figure out metadata - tries JSON first, then builds from files
+   * Uses optimized building when no synopsis calculation is needed
+   */
+  async figureMetadata(version, useOptimized = true) {
+    if (this.useMetadata) {
+      const metadata = await this.loadMetadataJson(version);
+      if (metadata) {
+        return metadata;
+      }
+    }
+    if (useOptimized && !this.fileSynopsisFunction && !this.versionSynopsisFunction) {
+      return await this.buildMetadataOptimized(version);
+    }
+    return await this.figureMetadataFromVersionFiles(version);
+  }
+  /**
+   * Load version metadata (main entry point for loading)
+   */
+  async loadVersionMetadata(version) {
+    const metadata = await this.figureMetadata(version);
+    this.metadata = metadata;
+    return metadata;
+  }
+  /**
+   * Save version metadata to file
+   */
+  async saveVersionMetadata(metadata) {
+    if (!this.useMetadata) {
+      return;
+    }
+    const metadataToSave = metadata || this.metadata;
+    let metadataFile;
+    if (this.versioned) {
+      if (!this.currentVersion) {
+        return;
+      }
+      metadataFile = path3.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = path3.join(this.getDestinationPath(), "metadata.json");
+    }
+    await fs3.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
+  }
+  /**
+   * Create a new file entry in metadata
+   */
+  makeNewFile() {
+    this.currentFileNumber = (this.currentFileNumber || 0) + 1;
+    const dataType = this.metadata.dataType || "json-array";
+    const fileEntry = {
+      number: this.currentFileNumber,
+      recordsCount: 0,
+      fileName: `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(dataType)}`
+    };
+    this.metadata.files.push(fileEntry);
+    this.lastFileData = null;
+    this.logger.silly?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+  }
+  /**
+   * Figure out what data to write and which file to use (for pagination)
+   * @param data - Data to write
+   * @param targetFileIndex - Optional index of existing file to overwrite (when customMetadata matches)
+   * @param forceNewFile - If true, always create a new file (when customMetadata provided but no match)
+   */
+  figureOutDataAndFileToWrite(data, targetFileIndex = null, forceNewFile = false) {
+    let dataToWrite;
+    let dataLeftOver;
+    const incomingDataType = detectDataType(data);
+    if (this.metadata.dataType !== incomingDataType) {
+      this.metadata.dataType = incomingDataType;
+    }
+    if (targetFileIndex !== null && targetFileIndex < this.metadata.files.length) {
+      const targetFile = this.metadata.files[targetFileIndex];
+      if (!Array.isArray(data)) {
+        dataToWrite = data;
+        dataLeftOver = null;
+        return { dataToWrite, dataLeftOver, fileName: targetFile.fileName };
+      } else {
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+        return { dataToWrite, dataLeftOver, fileName: targetFile.fileName };
+      }
+    }
+    let newlyCreatedFileIndex = null;
+    if (forceNewFile) {
+      const filesBeforeCreate = this.metadata.files.length;
+      this.makeNewFile();
+      newlyCreatedFileIndex = filesBeforeCreate;
+      this.logger.silly?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
+    } else if (this.metadata.files.length === 0) {
+      this.makeNewFile();
+    }
+    const lastFile = this.metadata.files[this.metadata.files.length - 1];
+    const lastFileRecordsCount = lastFile.recordsCount;
+    if (forceNewFile && newlyCreatedFileIndex !== null) {
+      const newlyCreatedFile = this.metadata.files[newlyCreatedFileIndex];
+      if (newlyCreatedFile && newlyCreatedFile.fileName !== lastFile.fileName) {
+        this.logger.warn?.(`[FileDatabase] Warning: Newly created file ${newlyCreatedFile.fileName} doesn't match last file ${lastFile.fileName}`);
+      }
+    }
+    if (!Array.isArray(data) && !forceNewFile) {
+      const lastFileExtension = path3.extname(lastFile.fileName);
+      const expectedExtension = `.${getFileExtension(incomingDataType)}`;
+      if (lastFileExtension !== expectedExtension) {
+        if (lastFileRecordsCount > 0) {
+          this.makeNewFile();
+        } else {
+          lastFile.fileName = `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(incomingDataType)}`;
+        }
+      }
+    } else if (!Array.isArray(data) && forceNewFile) {
+      const lastFileExtension = path3.extname(lastFile.fileName);
+      const expectedExtension = `.${getFileExtension(incomingDataType)}`;
+      if (lastFileExtension !== expectedExtension) {
+        lastFile.fileName = `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(incomingDataType)}`;
+      }
+    }
+    if (Array.isArray(data)) {
+      if (forceNewFile) {
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+      } else if (lastFileRecordsCount < this.pageSize) {
+        dataToWrite = [...this.lastFileData || [], ...data.slice(0, this.pageSize - lastFileRecordsCount)];
+        dataLeftOver = data.slice(this.pageSize - lastFileRecordsCount);
+        this.lastFileData = dataToWrite;
+      } else {
+        this.makeNewFile();
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+      }
+    } else {
+      dataToWrite = data;
+      dataLeftOver = null;
+    }
+    const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
+    this.logger.silly?.(
+      `[FileDatabase] figureOutDataAndFileToWrite: filename=${fileName}, forceNewFile=${forceNewFile}, targetFileIndex=${targetFileIndex}, dataToWrite.length=${Array.isArray(dataToWrite) ? dataToWrite.length : "N/A"}, lastFileRecordsCount=${lastFileRecordsCount}`
+    );
+    return { dataToWrite, dataLeftOver, fileName };
+  }
+  /**
+   * Calculate file-level synopsis if function is set
+   */
+  calculateFileSynopsis(data, fileIndex = this.metadata.files.length - 1) {
+    if (!this.fileSynopsisFunction) {
+      return;
+    }
+    const fileInfo = this.metadata.files[fileIndex];
+    const enhancedFileInfo = this.fileSynopsisFunction(fileInfo, data);
+    this.metadata.files[fileIndex] = enhancedFileInfo;
+  }
+  /**
+   * Calculate version-level synopsis if function is set
+   */
+  calculateVersionSynopsis() {
+    if (!this.versionSynopsisFunction) {
+      return;
+    }
+    const enhancedMetadata = this.versionSynopsisFunction(this.metadata);
+    this.metadata = enhancedMetadata;
+  }
+  /**
+   * Update metadata after writing data
+   */
+  updateMetadata(dataToWrite, fileName, customMetadata) {
+    let currentFile;
+    if (fileName) {
+      const foundFile = this.metadata.files.find((file) => file.fileName === fileName);
+      if (!foundFile) {
+        this.logger.warn?.(`[FileDatabase] File ${fileName} not found in metadata, using last file`);
+        currentFile = this.metadata.files[this.metadata.files.length - 1];
+      } else {
+        currentFile = foundFile;
+      }
+    } else {
+      currentFile = this.metadata.files[this.metadata.files.length - 1];
+    }
+    const recordsCount = Array.isArray(dataToWrite) ? dataToWrite.length : 1;
+    currentFile.recordsCount = recordsCount;
+    if (customMetadata) {
+      Object.assign(currentFile, customMetadata);
+    }
+    const fileIndex = this.metadata.files.indexOf(currentFile);
+    if (fileIndex !== -1) {
+      this.calculateFileSynopsis(dataToWrite, fileIndex);
+    }
+    this.metadata.version = this.currentVersion;
+    this.metadata.modifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.metadata.dataType = detectDataType(dataToWrite);
+    this.metadata.totalRecords = this.metadata.files.reduce((sum, file) => sum + (file.recordsCount || 0), 0);
+    this.logger.silly?.(
+      `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
+    );
+  }
+  /**
+   * Safe write with disk space check
+   */
+  async safeWrite(filePath, data) {
+    const serializedData = serializeData(data);
+    const dir = path3.dirname(filePath);
+    const requiredBytes = Buffer.byteLength(serializedData, "utf8");
+    const freeBytes = getFreeDiskSpace(dir);
+    if (freeBytes !== null) {
+      if (freeBytes < requiredBytes) {
+        throw new FileDatabaseError(
+          `Not enough disk space. Required: ${bytesToHumanReadable(requiredBytes)}, Free: ${bytesToHumanReadable(freeBytes)}`
+        );
+      }
+      if (freeBytes < this.freeSpaceThreshold) {
+        this.logger.warn?.(`Low disk space warning: only ${bytesToHumanReadable(freeBytes)} left`);
+      }
+    }
+    try {
+      await fs3.promises.writeFile(filePath, serializedData, "utf8");
+      this.logger.silly?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+    } catch (error) {
+      throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
+    }
+  }
+  /**
+   * Prepare the instance for read or write operations
+   * This discovers state and sets up internal members based on mode and current data
+   */
+  async prepare({ write, read, version }) {
+    if (write) {
+      if (this.versioned) {
+        if (this.currentVersion === null) {
+          await this.makeNewVersion();
+          this.metadata = this.getDefaultMetadata();
+          this.metadata.version = this.currentVersion;
+          this.makeNewFile();
+        } else {
+          if (!this.metadata.files.length) {
+            this.metadata = await this.figureMetadata(this.currentVersion);
+            if (this.metadata.files && this.metadata.files.length > 0) {
+              this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+            } else {
+              this.currentFileNumber = 0;
+            }
+          }
+        }
+      } else {
+        await ensurePath(this.getDestinationPath());
+        if (this.useMetadata === true) {
+          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+              if (this.metadata.files && this.metadata.files.length > 0) {
+                this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+              } else {
+                this.currentFileNumber = 0;
+              }
+            } catch (e) {
+              this.metadata = this.getDefaultMetadata();
+              this.currentFileNumber = 0;
+            }
+          } else {
+            this.metadata = this.getDefaultMetadata();
+            this.currentFileNumber = 0;
+          }
+        } else {
+          this.metadata = this.getDefaultMetadata();
+          this.currentFileNumber = 0;
+        }
+      }
+    } else if (read) {
+      if (this.versioned) {
+        const versions = await this.getVersions();
+        if (versions.length === 0) {
+          throw new FileDatabaseError("[FileDatabase] No versions found, cannot read");
+        }
+        if (version) {
+          if (!versions.includes(version)) {
+            throw new FileDatabaseError(`[FileDatabase] Version "${version}" not found`);
+          }
+          await this.setCurrentVersion(version);
+        } else {
+          await this.setCurrentVersion(versions[versions.length - 1]);
+        }
+        if (!this.metadata.files.length) {
+          this.metadata = await this.figureMetadata(this.currentVersion);
+          if (this.metadata.files && this.metadata.files.length > 0) {
+            this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+          } else {
+            this.currentFileNumber = 0;
+          }
+        }
+      } else {
+        this.currentVersion = null;
+        if (this.useMetadata === void 0) {
+          const format = await this.detectDataFormat();
+          this.useMetadata = format.hasMetadata;
+        }
+        if (this.useMetadata) {
+          const destPath = this.getDestinationPath();
+          const metadataPath = path3.join(destPath, "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+              if (this.metadata.files && this.metadata.files.length > 0) {
+                this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+              } else {
+                this.currentFileNumber = 0;
+              }
+            } catch (e) {
+              throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
+            }
+          } else {
+            throw new FileDatabaseError(
+              `[FileDatabase] No metadata found in non-versioned mode. Looked for: ${metadataPath} (table path: ${destPath})`
+            );
+          }
+        } else {
+          this.metadata = await this.figureMetadataFromVersionFiles("");
+          if (this.metadata.files && this.metadata.files.length > 0) {
+            this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+          } else {
+            this.currentFileNumber = 0;
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Write data to the file database
+   */
+  async write(data, options = {}) {
+    if (options.filename) {
+      const destPath2 = this.getDestinationPath();
+      await ensurePath(destPath2);
+      const filePath = path3.join(destPath2, options.filename);
+      await this.safeWrite(filePath, data);
+      return;
+    }
+    if (options.forceNewVersion && !this.versioned) {
+      throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
+    }
+    await this.prepare({ write: true });
+    const incomingDataType = detectDataType(data);
+    this.metadata.dataType = incomingDataType;
+    if (options.forceNewVersion) {
+      await this.makeNewVersion();
+      this.metadata = this.getDefaultMetadata();
+      this.metadata.version = this.currentVersion;
+      this.metadata.dataType = incomingDataType;
+      this.makeNewFile();
+    }
+    let targetFileIndex = null;
+    const hasCustomMetadata = options.customMetadata && Object.keys(options.customMetadata).length > 0;
+    if (hasCustomMetadata) {
+      for (let i = 0; i < this.metadata.files.length; i++) {
+        const fileEntry = this.metadata.files[i];
+        const matches = Object.keys(options.customMetadata).every((key) => {
+          return key in fileEntry && fileEntry[key] === options.customMetadata[key];
+        });
+        if (matches) {
+          targetFileIndex = i;
+          this.logger.silly?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
+          break;
+        } else {
+          this.logger.silly?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
+        }
+      }
+      if (targetFileIndex === null) {
+        this.logger.silly?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
+      }
+    } else {
+      this.logger.silly?.(`[FileDatabase] No custom metadata provided, will create new file`);
+    }
+    if (targetFileIndex !== null) {
+      const targetFile = this.metadata.files[targetFileIndex];
+      this.currentFileNumber = targetFile.number;
+      this.lastFileData = null;
+      this.currentRecord = 0;
+      this.hasReadFirstPage = false;
+    }
+    const forceNewFile = hasCustomMetadata && targetFileIndex === null;
+    let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data, targetFileIndex, forceNewFile);
+    const destPath = this.getDestinationPath(this.currentVersion || void 0);
+    await this.safeWrite(path3.join(destPath, fileName), dataToWrite);
+    this.updateMetadata(dataToWrite, fileName, options.customMetadata);
+    while (dataLeftOver && dataLeftOver.length > 0 && targetFileIndex === null) {
+      const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
+      await this.safeWrite(path3.join(destPath, writeContext.fileName), writeContext.dataToWrite);
+      this.updateMetadata(writeContext.dataToWrite, writeContext.fileName, options.customMetadata);
+      dataLeftOver = writeContext.dataLeftOver;
+    }
+    this.calculateVersionSynopsis();
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
+  /**
+   * Read data from the file database
+   */
+  async read(options = {}) {
+    const { version, nextPage = false, pageSize, filename } = options;
+    if (filename) {
+      const destPath = this.getDestinationPath(version);
+      const filePath = path3.join(destPath, filename);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return JSON.parse(rawData);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${filename}: ${error.message}`);
+      }
+    }
+    await this.prepare({ read: true, version });
+    const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
+    if (isNonPaginatedData) {
+      const file = this.metadata.files[0];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return deserializeData(rawData, this.metadata.dataType);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    let effectivePageSize;
+    if (nextPage && this.hasReadFirstPage) {
+      effectivePageSize = pageSize || this.pageSize;
+      this.currentRecord += effectivePageSize;
+    } else if (!nextPage) {
+      effectivePageSize = pageSize !== void 0 ? pageSize : this.metadata.totalRecords;
+      this.currentRecord = 0;
+    } else {
+      effectivePageSize = pageSize || this.pageSize;
+    }
+    if (this.currentRecord >= this.metadata.totalRecords) {
+      return [];
+    }
+    const result = [];
+    let recordsRead = 0;
+    let currentFileIndex = 0;
+    let currentFileOffset = 0;
+    let totalRecords = 0;
+    for (let i = 0; i < this.metadata.files.length; i++) {
+      const file = this.metadata.files[i];
+      if (this.currentRecord < totalRecords + file.recordsCount) {
+        currentFileIndex = i;
+        currentFileOffset = totalRecords;
+        break;
+      }
+      totalRecords += file.recordsCount;
+    }
+    let cumulativeRecords = currentFileOffset;
+    for (let i = currentFileIndex; i < this.metadata.files.length && recordsRead < effectivePageSize; i++) {
+      const file = this.metadata.files[i];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const fileData = deserializeData(rawData, this.metadata.dataType);
+        let startIndex = 0;
+        if (i === currentFileIndex) {
+          startIndex = this.currentRecord - cumulativeRecords;
+        }
+        const endIndex = Math.min(startIndex + (effectivePageSize - recordsRead), fileData.length);
+        const recordsFromThisFile = fileData.slice(startIndex, endIndex);
+        result.push(...recordsFromThisFile);
+        recordsRead += recordsFromThisFile.length;
+        cumulativeRecords += file.recordsCount;
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    if (result.length > 0) {
+      if (nextPage || pageSize !== void 0 && pageSize < this.metadata.totalRecords) {
+        this.hasReadFirstPage = true;
+      }
+    }
+    return result;
+  }
+  /**
+   * Set the starting record for pagination (1-based index)
+   */
+  setStartRecord(startRecord) {
+    this.currentRecord = startRecord - 1;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * Reset read pagination state
+   */
+  resetPagination() {
+    this.currentRecord = 0;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * List filenames in the table directory.
+   * For catalog/key-value usage (files written with { filename }).
+   * Returns data file names (.json, .txt, .xml) excluding metadata.json.
+   */
+  async listFilenames() {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    try {
+      const entries = await fs3.promises.readdir(destPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile() && e.name !== "metadata.json" && /\.(json|txt|xml)$/i.test(e.name)).map((e) => e.name);
+    } catch (err) {
+      if (err?.code === "ENOENT") return [];
+      throw new FileDatabaseError(`Failed to list files: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file from the table directory (catalog mode).
+   * Use with listFilenames() to manage individual files.
+   */
+  async removeFile(filename) {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") return;
+      throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file and its metadata entry (non-versioned mode with useMetadata).
+   * Use with findData() to get fileName, then call removeFileEntry to delete.
+   */
+  async removeFileEntry(filename) {
+    if (this.versioned) {
+      throw new FileDatabaseError("removeFileEntry is only supported in non-versioned mode");
+    }
+    await this.prepare({ read: true });
+    const idx = this.metadata.files.findIndex((f) => f.fileName === filename);
+    if (idx === -1) {
+      throw new FileDatabaseError(`File entry ${filename} not found in metadata`);
+    }
+    const entry = this.metadata.files[idx];
+    const recordsCount = entry.recordsCount || 0;
+    this.metadata.files.splice(idx, 1);
+    this.metadata.totalRecords = Math.max(0, (this.metadata.totalRecords || 0) - recordsCount);
+    const destPath = this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        this.logger.warn?.(`[FileDatabase] File ${filename} already missing on disk`);
+      } else {
+        throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+      }
+    }
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
+  /**
+   * Set file-level synopsis calculation function
+   */
+  setFileSynopsisFunction(fn) {
+    this.fileSynopsisFunction = fn;
+  }
+  /**
+   * Set version-level synopsis calculation function
+   */
+  setVersionSynopsisFunction(fn) {
+    this.versionSynopsisFunction = fn;
+  }
+  /**
+   * Get current version name
+   */
+  getCurrentVersion() {
+    return this.currentVersion;
+  }
+  /**
+   * Get current metadata
+   */
+  getMetadata() {
+    return { ...this.metadata };
+  }
+  /**
+   * Find data by custom metadata fields
+   * Searches through all versions and files to find entries matching the search criteria
+   * 
+   * @param searchCriteria - Object with field names and values to search for (e.g., { ListingKey: "123", id: "456" })
+   * @returns Array of found entries with their file paths and metadata
+   */
+  async findData(searchCriteria) {
+    const results = [];
+    if (!this.versioned) {
+      await this.prepare({ read: true });
+      const metadata = this.getMetadata();
+      for (const fileEntry of metadata.files) {
+        const matches = Object.keys(searchCriteria).every((key) => {
+          return fileEntry[key] === searchCriteria[key];
+        });
+        if (matches) {
+          const destPath = this.getDestinationPath();
+          const filePath = path3.join(destPath, fileEntry.fileName);
+          const fileData = await fs3.promises.readFile(filePath, "utf8");
+          const data = deserializeData(fileData, metadata.dataType || "json-object");
+          results.push({
+            filePath,
+            fileName: fileEntry.fileName,
+            version: null,
+            metadata: fileEntry,
+            data
+          });
+        }
+      }
+    } else {
+      const versions = await this.getVersions();
+      for (const version of versions) {
+        await this.prepare({ read: true, version });
+        const metadata = this.getMetadata();
+        for (const fileEntry of metadata.files) {
+          const matches = Object.keys(searchCriteria).every((key) => {
+            return fileEntry[key] === searchCriteria[key];
+          });
+          if (matches) {
+            const destPath = this.getDestinationPath(version);
+            const filePath = path3.join(destPath, fileEntry.fileName);
+            const fileData = await fs3.promises.readFile(filePath, "utf8");
+            const data = deserializeData(fileData, metadata.dataType || "json-object");
+            results.push({
+              filePath,
+              fileName: fileEntry.fileName,
+              version,
+              metadata: fileEntry,
+              data
+            });
+          }
+        }
+      }
+    }
+    return results;
+  }
+};
+
+// src/mock-server/mock-storage.ts
+function stableStringify(obj) {
+  if (obj === null) return "null";
+  if (obj === void 0) return "undefined";
+  if (typeof obj !== "object") return JSON.stringify(obj);
+  if (Array.isArray(obj)) return "[" + obj.map(stableStringify).join(",") + "]";
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+function normalizeQuery(query) {
+  if (!query) return "";
+  const params = new URLSearchParams(query);
+  const sorted = [...params.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  return new URLSearchParams(sorted).toString();
+}
+function buildCriteria(method, host, pathname, query, requestData) {
+  return {
+    method: method.toUpperCase(),
+    host,
+    pathname: pathname || "/",
+    query: normalizeQuery(query),
+    requestBody: requestData != null ? stableStringify(requestData) : ""
+  };
+}
+var MockStorage = class {
+  fileDb;
+  logger;
+  constructor(config) {
+    this.logger = config.logger ?? console;
+    this.fileDb = new FileDatabase({
+      basePath: config.basePath,
+      namespace: "mocks",
+      tableName: "responses",
+      versioned: false,
+      useMetadata: true,
+      logger: this.logger
+    });
+  }
+  /**
+   * Store a mock response.
+   */
+  async store(method, requestUrl, requestData, responseData) {
+    const url = new URL(requestUrl);
+    const criteria = buildCriteria(method, url.host, url.pathname, url.search.slice(1), requestData);
+    await this.fileDb.write(responseData, { customMetadata: criteria });
+  }
+  /**
+   * Find a mock response by request criteria. Returns null if not found.
+   */
+  async find(method, host, pathname, query, requestData) {
+    const criteria = buildCriteria(method, host, pathname, query, requestData);
+    try {
+      const results = await this.fileDb.findData(criteria);
+      if (results.length === 0) return null;
+      return results[0].data;
+    } catch (err) {
+      if (err instanceof FileDatabaseError && /No metadata found/.test(err.message)) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  /**
+   * List all stored mock keys (opaque identifiers for remove)
+   */
+  async listKeys() {
+    const files = await this.fileDb.listFilenames();
+    return files.sort();
+  }
+  /**
+   * Remove a mock by key (from listKeys)
+   */
+  async remove(fileName) {
+    const name = fileName.endsWith(".json") ? fileName : `${fileName}.json`;
+    try {
+      await this.fileDb.removeFileEntry(name);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Remove a mock by request criteria (method, host, pathname, query, requestData)
+   */
+  async removeByCriteria(method, host, pathname, query, requestData) {
+    const criteria = buildCriteria(method, host, pathname, query, requestData);
+    try {
+      const results = await this.fileDb.findData(criteria);
+      if (results.length === 0) return false;
+      await this.fileDb.removeFileEntry(results[0].fileName);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
 // src/http-client2/index.ts
 function buildUrl(baseURL, url, params) {
   let full = url;
@@ -165,14 +1375,50 @@ function mapStatusToCustom(httpStatus) {
   if (httpStatus >= 500) return "serverError";
   return "unknown";
 }
+function formatForDisplay(value, maxKeys, maxArrayItems, maxChars) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  if (typeof value === "string") {
+    if (value.length <= maxChars) return JSON.stringify(value);
+    return JSON.stringify(value.slice(0, maxChars) + `... (+${value.length - maxChars} chars)`);
+  }
+  if (Array.isArray(value)) {
+    const head = value.slice(0, maxArrayItems);
+    const rest = value.length - maxArrayItems;
+    const items = head.map((v) => formatForDisplay(v, maxKeys, maxArrayItems, maxChars));
+    if (rest <= 0) return `[${items.join(", ")}]`;
+    return `[${items.join(", ")}, ... +${rest} more]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    const shown = keys.slice(0, maxKeys);
+    const rest = keys.length - maxKeys;
+    const pairs = shown.map((k) => `${JSON.stringify(k)}: ${formatForDisplay(value[k], maxKeys, maxArrayItems, maxChars)}`);
+    if (rest <= 0) return `{${pairs.join(", ")}}`;
+    return `{${pairs.join(", ")}, ... +${rest} more keys}`;
+  }
+  return String(value);
+}
 var HttpClient = class _HttpClient {
   context;
   config;
   logger;
+  mockStorage = null;
   constructor(context, options = {}) {
     this.context = context;
     this.config = options;
     this.logger = options.logger ?? context?.logger ?? console;
+    if (options.saveMock || options.useMock) {
+      const mocksPath = options.mocksPath;
+      if (!mocksPath) {
+        throw new ParamError("[http-client2] mocksPath is required when saveMock or useMock is set");
+      }
+      const absoluteMocksPath = path4.resolve(mocksPath);
+      this.mockStorage = new MockStorage({ basePath: absoluteMocksPath, logger: this.logger });
+      const mode = [options.saveMock && "saveMock", options.useMock && "useMock"].filter(Boolean).join(", ");
+      this.logger.debug?.(`[HttpClient] mocks enabled (${mode}), mocksPath=${absoluteMocksPath}`);
+    }
   }
   /**
    * Static init - discovers params via context.params.getAllForModule("http-client2", defs). Whatever is in options goes.
@@ -185,27 +1431,85 @@ var HttpClient = class _HttpClient {
       maxRetryDelay: "number default 30000",
       retryJitter: "number default 0.1",
       userAgent: "string default HttpClient/v1.0",
-      baseURL: "string"
+      baseURL: "string",
+      saveMock: "boolean default false",
+      useMock: "boolean default false",
+      mocksPath: "string",
+      useTestServer: "string",
+      showRequest: "boolean default false",
+      showResponse: "boolean default false",
+      showRequestHeaders: "boolean default false",
+      showResponseHeaders: "boolean default false",
+      showMaxKeys: "number default 20",
+      showMaxArrayItems: "number default 5",
+      showMaxChars: "number default 300"
     };
     const discovered = context?.params?.getAllForModule?.(defs) ?? {};
     const merged = { ...discovered, ...options };
+    if ((merged.saveMock || merged.useMock) && !merged.mocksPath) {
+      throw new ParamError("[http-client2] mocksPath is required when saveMock or useMock is set");
+    }
+    if ((merged.saveMock || merged.useMock) && merged.useTestServer) {
+      throw new ParamError("[http-client2] saveMock/useMock cannot be used with useTestServer");
+    }
     return new _HttpClient(context, merged);
   }
   async request(method, url, options = {}) {
     const startTime = Date.now();
     const timeout = options.timeout ?? this.config.timeout;
-    const retryCount = options.retryCount ?? this.config.retryCount;
-    const retryDelay = options.retryDelay ?? this.config.retryDelay;
-    const fullUrl = buildUrl(this.config.baseURL, url, options.params);
+    const retryCount = options.retryCount ?? this.config.retryCount ?? 3;
+    const retryDelay = options.retryDelay ?? this.config.retryDelay ?? 1e3;
+    let fullUrl = buildUrl(this.config.baseURL, url, options.params);
+    if (this.config.useMock && this.mockStorage) {
+      try {
+        const urlObj = new URL(fullUrl);
+        const mock = await this.mockStorage.find(
+          method,
+          urlObj.host,
+          urlObj.pathname,
+          urlObj.search.slice(1),
+          options.data
+        );
+        if (mock) {
+          const duration = Date.now() - startTime;
+          if (this.config.showResponse) {
+            this.logRequestResponse(method, fullUrl, options, null, mock, duration, true);
+          }
+          return {
+            status: mapStatusToCustom(mock.status),
+            code: mock.status,
+            headers: mock.headers || {},
+            data: mock.data,
+            duration,
+            retryCount: 0,
+            finalUrl: fullUrl
+          };
+        }
+        throw new HttpClientError(`Mock not found for ${method} ${fullUrl}`);
+      } catch (e) {
+        if (e instanceof HttpClientError) throw e;
+        this.logger.warn?.("[HttpClient] Mock lookup failed:", e);
+        throw new HttpClientError(`Mock not found for ${method} ${fullUrl} (lookup failed: ${e.message})`);
+      }
+    }
+    let fetchUrl = fullUrl;
     const headers = {
-      "User-Agent": options.userAgent ?? this.config.userAgent,
+      "User-Agent": options.userAgent ?? this.config.userAgent ?? "HttpClient/v1.0",
       ...options.headers
     };
+    if (this.config.useTestServer) {
+      const urlObj = new URL(fullUrl);
+      fetchUrl = this.config.useTestServer.replace(/\/$/, "") + urlObj.pathname + urlObj.search;
+      headers["XAXIOSOrigin"] = fullUrl;
+    }
     let body;
     if (options.data != null && ["POST", "PUT", "PATCH"].includes(method)) {
       body = typeof options.data === "string" ? options.data : JSON.stringify(options.data);
       if (!headers["content-type"]) headers["Content-Type"] = "application/json";
     }
+    if (this.config.showRequest) {
+      this.logRequestResponse(method, fullUrl, options, headers, null, 0, false);
+    }
     let lastError = null;
     for (let attempt = 1; attempt <= retryCount + 1; attempt++) {
       let abortedByTimeout = false;
@@ -218,7 +1522,7 @@ var HttpClient = class _HttpClient {
           abortedByTimeout = true;
           controller.abort();
         }, timeout);
-        const response = await fetch(fullUrl, {
+        const response = await fetch(fetchUrl, {
           method,
           headers,
           body: method !== "GET" && method !== "HEAD" ? body : void 0,
@@ -233,7 +1537,7 @@ var HttpClient = class _HttpClient {
           if (options.debug) {
             this.logger.debug?.(`[HttpClient] ${method} ${fullUrl} \u2192 ${response.status} success (${duration}ms)`);
           }
-          return {
+          const result = {
             status: mapStatusToCustom(response.status),
             code: response.status,
             headers: resHeaders,
@@ -242,14 +1546,38 @@ var HttpClient = class _HttpClient {
             retryCount: attempt - 1,
             finalUrl: response.url || fullUrl
           };
+          if (this.config.saveMock && this.mockStorage) {
+            try {
+              const responseData = {
+                status: response.status,
+                headers: resHeaders,
+                data: data2
+              };
+              await this.mockStorage.store(
+                method,
+                fullUrl,
+                options.data,
+                responseData
+              );
+            } catch (e) {
+              this.logger.warn?.("[HttpClient] Failed to save mock:", e);
+            }
+          }
+          if (this.config.showResponse) {
+            this.logRequestResponse(method, fullUrl, options, headers, { status: response.status, headers: resHeaders, data: data2 }, duration, false);
+          }
+          return result;
         }
         const data = await parseBody(response);
         const classification2 = classifyError({ response: { status: response.status, headers: resHeaders, data } });
+        if (this.config.showResponse) {
+          this.logRequestResponse(method, fullUrl, options, headers, { status: response.status, headers: resHeaders, data }, duration, false);
+        }
         if (options.debug) {
           this.logger.debug?.(`[HttpClient] ${method} ${fullUrl} \u2192 ${response.status} ${classification2.status} (${duration}ms)`);
         }
         if (attempt <= retryCount && shouldRetryError(classification2)) {
-          const delay = calculateRetryDelay(attempt, retryDelay, this.config.maxRetryDelay, this.config.retryJitter);
+          const delay = calculateRetryDelay(attempt, retryDelay, this.config.maxRetryDelay ?? 3e4, this.config.retryJitter ?? 0.1);
           this.logger.warn?.(`[HttpClient] ${method} ${fullUrl} failed (${classification2.type}). Retrying in ${delay}ms...`);
           if (options.debug) this.logger.debug?.(`[HttpClient] Waiting ${delay}ms before retry ${attempt + 1}`);
           await sleep(delay);
@@ -279,7 +1607,7 @@ var HttpClient = class _HttpClient {
           this.logger.error?.(`[HttpClient] ${method} ${fullUrl} failed (${classification2.type}): ${getErrorDescription(classification2.type)}`);
         }
         if (attempt <= retryCount && shouldRetryError(classification2)) {
-          const delay = calculateRetryDelay(attempt, retryDelay, this.config.maxRetryDelay, this.config.retryJitter);
+          const delay = calculateRetryDelay(attempt, retryDelay, this.config.maxRetryDelay ?? 3e4, this.config.retryJitter ?? 0.1);
           if (options.debug) this.logger.debug?.(`[HttpClient] Waiting ${delay}ms before retry ${attempt + 1}`);
           await sleep(delay);
           continue;
@@ -308,6 +1636,28 @@ var HttpClient = class _HttpClient {
       finalUrl: fullUrl
     };
   }
+  logRequestResponse(method, url, options, reqHeaders, res, durationMs, fromMock) {
+    const maxKeys = this.config.showMaxKeys ?? 20;
+    const maxArray = this.config.showMaxArrayItems ?? 5;
+    const maxChars = this.config.showMaxChars ?? 300;
+    const log = this.logger.info ?? this.logger.log ?? console.log;
+    log(`[HttpClient] ${method} ${url}`);
+    if (this.config.showRequestHeaders && reqHeaders && Object.keys(reqHeaders).length > 0) {
+      log(`  Request headers: ${formatForDisplay(reqHeaders, maxKeys, maxArray, maxChars)}`);
+    }
+    if (options.data != null) {
+      log(`  Request body: ${formatForDisplay(options.data, maxKeys, maxArray, maxChars)}`);
+    }
+    if (res) {
+      log(`  \u2192 ${res.status}${fromMock ? " (from mock)" : ""} ${durationMs}ms`);
+      if (this.config.showResponseHeaders && res.headers && Object.keys(res.headers).length > 0) {
+        log(`  Response headers: ${formatForDisplay(res.headers, maxKeys, maxArray, maxChars)}`);
+      }
+      if (res.data != null) {
+        log(`  Response body: ${formatForDisplay(res.data, maxKeys, maxArray, maxChars)}`);
+      }
+    }
+  }
   async get(url, options = {}) {
     return this.request("GET", url, options);
   }