@nmakarov/cli-toolkit 0.14.2 → 0.18.0

package/dist/tasks.cjs

@@ -0,0 +1,2295 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tasks.ts
+var tasks_exports = {};
+__export(tasks_exports, {
+  TaskMaster: () => TaskMaster,
+  TaskPing: () => TaskPing,
+  TaskSampleProcess: () => TaskSampleProcess,
+  TaskShellCommand: () => TaskShellCommand,
+  TaskStopRunner: () => TaskStopRunner,
+  TaskSumAB: () => TaskSumAB,
+  TaskSystemInfo: () => TaskSystemInfo,
+  TasksManager: () => TasksManager,
+  TasksRegistry: () => TasksRegistry,
+  appendTaskIpcLog: () => appendTaskIpcLog,
+  defaultTasksRegistry: () => defaultTasksRegistry,
+  enqueueStopTask: () => enqueueStopTask,
+  enqueueTask: () => enqueueTask,
+  ensureTaskTables: () => ensureTaskTables,
+  queueToTableNames: () => queueToTableNames,
+  runNodeTaskScript: () => runNodeTaskScript,
+  runTasksLoop: () => runTasksLoop,
+  updateTaskProgress: () => updateTaskProgress,
+  waitForTaskResult: () => waitForTaskResult
+});
+module.exports = __toCommonJS(tasks_exports);
+
+// 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/utils/fs-utils.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+async function ensurePath(...pathParts) {
+  const fullPath = import_path.default.resolve(...pathParts);
+  if (!import_fs.default.existsSync(fullPath)) {
+    await import_fs.default.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/os-utils.ts
+var import_fs2 = __toESM(require("fs"), 1);
+var import_path2 = __toESM(require("path"), 1);
+var import_child_process = require("child_process");
+function getFreeDiskSpace(targetPath) {
+  try {
+    let pathToCheck = targetPath;
+    if (!import_fs2.default.existsSync(targetPath)) {
+      const parentDir = import_path2.default.dirname(targetPath);
+      if (import_fs2.default.existsSync(parentDir)) {
+        pathToCheck = parentDir;
+      } else {
+        pathToCheck = process.platform === "win32" ? "C:\\" : "/";
+      }
+    }
+    if (process.platform === "win32") {
+      return null;
+    } else {
+      const stdout = (0, import_child_process.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/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/core-utils.ts
+function sleepMs(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function toJsonColumn(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
+
+// src/tasks/taskUtils.ts
+var import_node_crypto = require("crypto");
+function getDb(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
+  }
+  return db;
+}
+function queueToTableNames(queue) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
+    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
+  }
+  return {
+    tasksTable: queue,
+    historyTable: `${queue}_history`
+  };
+}
+async function ensureTaskTables(context, options = {}) {
+  const queue = options.queue ?? "tasks";
+  const recreate = options.recreate ?? false;
+  const db = getDb(context);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
+  const needsHistory = recreate ? true : !await db.tableExists(historyTable);
+  if (recreate) {
+    await db.schema.dropTableIfExists(historyTable);
+    await db.schema.dropTableIfExists(tasksTable);
+  }
+  if (needsTasks) {
+    await db.raw(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+    await db.schema.createTable(tasksTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+      t.timestamp("started_at");
+      t.timestamp("completed_at");
+      t.integer("priority").notNullable().defaultTo(0);
+      t.text("schedule");
+      t.timestamp("past_due").defaultTo(null);
+      t.text("target").notNullable();
+      t.text("task").notNullable();
+      t.json("params");
+      t.text("opid");
+      t.timestamp("paused_at").defaultTo(null);
+      t.text("progress");
+      t.boolean("success");
+      t.json("results");
+    });
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.index(["target", "started_at", "created_at"], `${tasksTable}_target_started_created_idx`);
+      t.index(["target", "past_due", "priority", "created_at"], `${tasksTable}_target_past_due_priority_created_idx`);
+      t.index(["target", "task"], `${tasksTable}_target_task_idx`);
+    });
+  }
+  const tasksHasOpid = await db.schema.hasColumn(tasksTable, "opid");
+  if (!tasksHasOpid) {
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.text("opid");
+    });
+  }
+  const tasksHasPausedAt = await db.schema.hasColumn(tasksTable, "paused_at");
+  if (!tasksHasPausedAt) {
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.timestamp("paused_at").defaultTo(null);
+    });
+  }
+  if (needsHistory) {
+    await db.schema.createTable(historyTable, (t) => {
+      t.uuid("id").notNullable();
+      t.timestamp("created_at").notNullable();
+      t.timestamp("started_at");
+      t.timestamp("completed_at");
+      t.integer("priority").notNullable().defaultTo(0);
+      t.text("schedule");
+      t.timestamp("past_due").defaultTo(null);
+      t.text("target").notNullable();
+      t.text("task").notNullable();
+      t.json("params");
+      t.text("opid");
+      t.text("progress");
+      t.boolean("success");
+      t.json("results");
+    });
+    await db.schema.alterTable(historyTable, (t) => {
+      t.index(["target", "created_at"], `${historyTable}_target_created_idx`);
+      t.index(["task", "created_at"], `${historyTable}_task_created_idx`);
+    });
+  }
+  const historyHasOpid = await db.schema.hasColumn(historyTable, "opid");
+  if (!historyHasOpid) {
+    await db.schema.alterTable(historyTable, (t) => {
+      t.text("opid");
+    });
+  }
+}
+async function enqueueTask(context, options) {
+  const db = getDb(context);
+  const queue = options.queue ?? "tasks";
+  const { tasksTable } = queueToTableNames(queue);
+  const id = (0, import_node_crypto.randomUUID)();
+  await db(tasksTable).insert({
+    id,
+    target: options.target,
+    task: options.task,
+    params: toJsonColumn(options.params ?? null),
+    opid: options.opid ?? null,
+    priority: options.priority ?? 0,
+    schedule: options.schedule ?? null
+  });
+  return id;
+}
+async function updateTaskProgress(context, tasksTable, taskId, progress) {
+  const db = getDb(context);
+  await db(tasksTable).where({ id: taskId }).update({
+    progress: typeof progress === "string" ? progress : JSON.stringify(progress)
+  });
+}
+
+// src/filedatabase/index.ts
+var import_fs3 = __toESM(require("fs"), 1);
+var import_path3 = __toESM(require("path"), 1);
+
+// 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/errors.ts
+var FrameworkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FrameworkError";
+  }
+};
+var ParamError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "ParamError";
+  }
+};
+var FileDatabaseError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
+
+// 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 import_path3.default.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 = import_path3.default.resolve(this.getDestinationPath(), versions.shift());
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      await import_fs3.default.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 import_fs3.default.promises.readdir(destPath);
+      const versions = items.filter((item) => {
+        const itemPath = import_path3.default.join(destPath, item);
+        const stat = import_fs3.default.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 (!import_fs3.default.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await import_fs3.default.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 (!import_fs3.default.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await import_fs3.default.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await import_fs3.default.promises.readFile(import_path3.default.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = import_path3.default.join(tablePath, item);
+      const stat = import_fs3.default.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = import_path3.default.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(), version, "metadata.json");
+    if (import_fs3.default.existsSync(metadataFile)) {
+      try {
+        const rawData = await import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(), version);
+    if (!import_fs3.default.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await import_fs3.default.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 = import_path3.default.join(versionPath, fileName);
+      try {
+        const rawData = await import_fs3.default.promises.readFile(filePath, "utf8");
+        const extension = import_path3.default.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 = import_path3.default.join(this.getDestinationPath(), version);
+    if (!import_fs3.default.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await import_fs3.default.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 = import_path3.default.join(versionPath, firstFile.fileName);
+    const firstFileRaw = await import_fs3.default.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 = import_path3.default.join(versionPath, lastFile.fileName);
+        const lastFileRaw = await import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = import_path3.default.join(this.getDestinationPath(), "metadata.json");
+    }
+    await import_fs3.default.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 = import_path3.default.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 = import_path3.default.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 = import_path3.default.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 import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(), "metadata.json");
+          if (import_fs3.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs3.default.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 = import_path3.default.join(destPath, "metadata.json");
+          if (import_fs3.default.existsSync(metadataPath)) {
+            try {
+              const rawData = await import_fs3.default.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 = import_path3.default.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(import_path3.default.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(import_path3.default.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 = import_path3.default.join(destPath, filename);
+      try {
+        const rawData = await import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await import_fs3.default.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 = import_path3.default.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await import_fs3.default.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 ? import_path3.default.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    try {
+      const entries = await import_fs3.default.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 ? import_path3.default.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = import_path3.default.join(destPath, filename);
+    try {
+      await import_fs3.default.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 = import_path3.default.join(destPath, filename);
+    try {
+      await import_fs3.default.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 = import_path3.default.join(destPath, fileEntry.fileName);
+          const fileData = await import_fs3.default.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 = import_path3.default.join(destPath, fileEntry.fileName);
+            const fileData = await import_fs3.default.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/tasks/taskLogs.ts
+function getLogsState(context) {
+  const holder = context;
+  if (holder.__tasksLogsState) return holder.__tasksLogsState;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") || "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") || "tasks-logs";
+  const tableName = holder.params?.get?.("tasksLogsTable") || "runner";
+  const errorTableName = holder.params?.get?.("tasksErrorLogsTable") || `${tableName}-errors`;
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const errorDb = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: errorTableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) {
+    const disabledState = {
+      db: null,
+      errorDb,
+      queue: Promise.resolve(),
+      initialized: true,
+      errorInitialized: false
+    };
+    holder.__tasksLogsState = disabledState;
+    return disabledState;
+  }
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  holder.__tasksLogsState = state;
+  return state;
+}
+function isErrorPayload(payload) {
+  if (!payload) return false;
+  if (typeof payload === "object") {
+    const level = typeof payload.level === "string" ? payload.level.toLowerCase() : "";
+    if (level === "error" || level === "fatal") return true;
+    if (typeof payload.message === "string" && /\berror\b/i.test(payload.message)) return true;
+    return false;
+  }
+  if (typeof payload === "string") {
+    return /\berror\b/i.test(payload);
+  }
+  return false;
+}
+function buildLogRecord(task, payload) {
+  const params = task.params && typeof task.params === "object" ? task.params : {};
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    opid: task.opid ?? null,
+    taskId: task.id,
+    taskName: task.task,
+    target: task.target,
+    source: typeof params.source === "string" ? params.source : null,
+    resource: typeof params.resource === "string" ? params.resource : null,
+    payload
+  };
+}
+function appendTaskIpcLog(context, task, payload) {
+  const state = getLogsState(context);
+  if (!state.db && !state.errorDb) return;
+  const record = buildLogRecord(task, payload);
+  state.queue = state.queue.then(async () => {
+    if (state.db) {
+      await state.db.write([record], { forceNewVersion: !state.initialized });
+      state.initialized = true;
+    }
+    if (state.errorDb && isErrorPayload(payload)) {
+      await state.errorDb.write([record], { forceNewVersion: !state.errorInitialized });
+      state.errorInitialized = true;
+    }
+  }).catch((error) => {
+    context.logger.warn?.("[tasks] failed to persist IPC log entry:", error);
+  });
+}
+
+// src/tasks/time-matcher.ts
+var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
+function resolveAsterisks(field, range) {
+  return field.includes("*") ? field.replace("*", range) : field;
+}
+function resolveRanges(field) {
+  const regex = /(\d+)-(\d+)/;
+  let current = field;
+  while (true) {
+    const match = regex.exec(current);
+    if (!match) break;
+    const raw = match[0];
+    let first = Number(match[1]);
+    let last = Number(match[2]);
+    if (last < first) {
+      [first, last] = [last, first];
+    }
+    const values = [];
+    for (let i = first; i <= last; i += 1) {
+      values.push(i);
+    }
+    current = current.replace(raw, values.join(","));
+  }
+  return current;
+}
+function resolveSteps(field) {
+  const match = /^(.+)\/(\d+)$/.exec(field);
+  if (!match) return field;
+  const base = match[1];
+  const step = Number(match[2]);
+  if (!Number.isFinite(step) || step <= 0) return field;
+  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
+}
+function convertPattern(pattern) {
+  const parts = pattern.trim().split(/\s+/);
+  if (parts.length !== 6) {
+    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
+  }
+  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
+}
+function fieldMatches(field, value) {
+  const allowed = field.split(",").map((v) => Number(v));
+  return allowed.includes(value);
+}
+function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
+  const parsed = convertPattern(pattern);
+  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+}
+
+// src/tasks/TaskMaster.ts
+var TaskMaster = class {
+  context;
+  task;
+  constructor(context, task) {
+    this.context = context;
+    this.task = task;
+  }
+  cantRunReason() {
+    return false;
+  }
+  requestStop(_allowanceMs) {
+  }
+};
+
+// src/tasks/coreTasks/TaskPing.ts
+var TaskPing = class extends TaskMaster {
+  async run() {
+    this.context.logger.info?.(`[TaskPing] pong (${this.task.id})`);
+    return { success: true, results: "pong" };
+  }
+};
+
+// src/tasks/coreTasks/TaskSampleProcess.ts
+var TaskSampleProcess = class extends TaskMaster {
+  stopRequested = false;
+  stopAllowanceMs = 0;
+  stopDecisionLogged = false;
+  requestStop(allowanceMs) {
+    this.stopRequested = true;
+    this.stopAllowanceMs = Number.isFinite(allowanceMs) && allowanceMs > 0 ? allowanceMs : 0;
+    this.context.logger.warn?.(
+      `[TaskSampleProcess] stop signal received (${this.task.id}), allowanceMs=${this.stopAllowanceMs}`
+    );
+  }
+  async run(reportProgress) {
+    const totalRaw = this.task?.params?.total ?? 10;
+    const delayRaw = this.task?.params?.delay ?? 1e3;
+    const nameRaw = this.task?.params?.name;
+    const total = Number(totalRaw);
+    const delay = Number(delayRaw);
+    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "sampleProcess";
+    const errors = [];
+    if (!Number.isInteger(total) || total <= 0) {
+      errors.push('param "total" must be a positive integer');
+    }
+    if (!Number.isInteger(delay) || delay < 0) {
+      errors.push('param "delay" must be an integer >= 0');
+    }
+    if (errors.length > 0) {
+      return {
+        success: false,
+        results: {
+          error: `Validation failed: ${errors.join(", ")}`,
+          received: { total: totalRaw, delay: delayRaw, name: nameRaw }
+        }
+      };
+    }
+    const startedAt = Date.now();
+    for (let i = 1; i <= total; i += 1) {
+      if (this.stopRequested) {
+        const remainingMs = Math.max(0, (total - i + 1) * delay);
+        if (remainingMs <= this.stopAllowanceMs) {
+          if (!this.stopDecisionLogged) {
+            this.stopDecisionLogged = true;
+            this.context.logger.warn?.(
+              `[TaskSampleProcess] continue to finish (${this.task.id}): remainingMs=${remainingMs} <= allowanceMs=${this.stopAllowanceMs}`
+            );
+          }
+        } else {
+          this.context.logger.warn?.(
+            `[TaskSampleProcess] stopping gracefully at iteration ${i}/${total} (${this.task.id}), remainingMs=${remainingMs} > allowanceMs=${this.stopAllowanceMs}`
+          );
+          return {
+            success: false,
+            results: {
+              message: `Stopped before completion at iteration ${i}/${total}`,
+              completed: i - 1,
+              total,
+              name,
+              remainingMs,
+              allowanceMs: this.stopAllowanceMs
+            }
+          };
+        }
+      }
+      const elapsed = Date.now() - startedAt;
+      const remaining = Math.max(0, (total - i) * delay);
+      const progress = {
+        name,
+        count: i,
+        total,
+        elapsedMs: elapsed,
+        remainingMs: remaining,
+        status: `running ${name}: ${i}/${total}`
+      };
+      this.context.logger.progress("running", {
+        prefix: name,
+        count: i,
+        total
+      });
+      await reportProgress(progress);
+      await sleepMs(delay);
+    }
+    return {
+      success: true,
+      results: {
+        message: `Completed ${total} iterations`,
+        total,
+        delay,
+        name
+      }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskShellCommand.ts
+var import_node_child_process = require("child_process");
+function runShellCommand(command, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)(command, {
+      shell: true,
+      cwd: cwd || process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      resolve({
+        exitCode,
+        output: output.trim(),
+        stderr: stderr.trim(),
+        signal
+      });
+    });
+  });
+}
+var TaskShellCommand = class extends TaskMaster {
+  async run() {
+    const params = this.task?.params;
+    const commandRaw = typeof params === "string" ? params : params?.command;
+    const cwdRaw = typeof params === "string" ? void 0 : params?.cwd;
+    const command = typeof commandRaw === "string" ? commandRaw.trim() : "";
+    const cwd = typeof cwdRaw === "string" && cwdRaw.trim() ? cwdRaw.trim() : void 0;
+    if (!command) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "command" must be a non-empty string',
+          received: this.task?.params ?? null
+        }
+      };
+    }
+    try {
+      const result = await runShellCommand(command, cwd);
+      const success = result.exitCode === 0;
+      this.context.logger.info?.(
+        `[TaskShellCommand] command="${command}" exitCode=${String(result.exitCode)} (${this.task.id})`
+      );
+      return {
+        success,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: result.output,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+          signal: result.signal
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: "",
+          stderr: "",
+          exitCode: null,
+          error: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSystemInfo.ts
+var import_node_os = __toESM(require("os"), 1);
+var import_promises = __toESM(require("fs/promises"), 1);
+function toGb(valueBytes) {
+  return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
+}
+function toMb(valueBytes) {
+  return `${(valueBytes / 1024 ** 2).toFixed(2)} MB`;
+}
+async function getDiskStats() {
+  const stats = await import_promises.default.statfs("/");
+  const total = Number(stats.bsize) * Number(stats.blocks);
+  const free = Number(stats.bsize) * Number(stats.bavail);
+  const used = total - free;
+  return {
+    total: toGb(total),
+    used: toGb(used),
+    free: toGb(free)
+  };
+}
+var TaskSystemInfo = class extends TaskMaster {
+  async run() {
+    try {
+      const totalMemory = import_node_os.default.totalmem();
+      const freeMemory = import_node_os.default.freemem();
+      const usedMemory = totalMemory - freeMemory;
+      const cpus = import_node_os.default.cpus();
+      const cpuUtilization = cpus.map((cpu) => {
+        const total = Object.values(cpu.times).reduce((acc, time) => acc + time, 0);
+        const usage = (total - cpu.times.idle) / total * 100;
+        return Number(usage.toFixed(2));
+      });
+      const processMemory = process.memoryUsage();
+      const disk = await getDiskStats();
+      const results = {
+        memory: {
+          total: toGb(totalMemory),
+          used: toGb(usedMemory),
+          free: toGb(freeMemory)
+        },
+        processMemory: {
+          rss: toMb(processMemory.rss),
+          heapTotal: toMb(processMemory.heapTotal),
+          heapUsed: toMb(processMemory.heapUsed),
+          external: toMb(processMemory.external)
+        },
+        disk,
+        cpu: {
+          cores: cpuUtilization.length,
+          utilization: cpuUtilization
+        },
+        runtime: {
+          platform: import_node_os.default.platform(),
+          arch: import_node_os.default.arch(),
+          uptimeSec: import_node_os.default.uptime(),
+          hostname: import_node_os.default.hostname()
+        }
+      };
+      this.context.logger.info?.(`[TaskSystemInfo] collected system metrics (${this.task.id})`);
+      return { success: true, results };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          error: "Can't collect system stats",
+          message: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSumAB.ts
+var TaskSumAB = class extends TaskMaster {
+  async run() {
+    const a = this.task?.params?.a;
+    const b = this.task?.params?.b;
+    if (typeof a !== "number" || Number.isNaN(a)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "a" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    if (typeof b !== "number" || Number.isNaN(b)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "b" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    const sum = a + b;
+    this.context.logger.info?.(`[TaskSumAB] ${a} + ${b} = ${sum} (${this.task.id})`);
+    return {
+      success: true,
+      results: { a, b, sum }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskStopRunner.ts
+var TaskStopRunner = class extends TaskMaster {
+  async run() {
+    const allowanceMs = Number(this.task?.params?.allowanceMs ?? 5e3);
+    this.context.logger.warn?.(`[TaskStopRunner] stop requested (allowanceMs=${allowanceMs})`);
+    return {
+      success: true,
+      results: {
+        stopRunner: true,
+        allowanceMs,
+        message: "Runner stop requested"
+      }
+    };
+  }
+};
+
+// src/tasks/TasksRegistry.ts
+var TasksRegistry = class _TasksRegistry {
+  map = {};
+  constructor(initial) {
+    if (initial) {
+      this.addMany(initial);
+    }
+  }
+  static withCoreTasks() {
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner);
+  }
+  add(taskName, taskClass) {
+    this.map[taskName] = taskClass;
+    return this;
+  }
+  addMany(entries) {
+    for (const [name, klass] of Object.entries(entries)) {
+      this.add(name, klass);
+    }
+    return this;
+  }
+  get(taskName) {
+    return this.map[taskName];
+  }
+  listSupportedTasks() {
+    return Object.keys(this.map).sort();
+  }
+  toObject() {
+    return { ...this.map };
+  }
+};
+
+// src/tasks/taskScriptRunner.ts
+var import_node_child_process2 = require("child_process");
+function toCliArgs(args = []) {
+  return args.filter((a) => typeof a === "string" && a.length > 0);
+}
+function formatChildLogPrefix(task) {
+  return `${task.task}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
+}
+async function runNodeTaskScript(context, options) {
+  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+  const inheritedExecArgs = Array.isArray(process.execArgv) ? [...process.execArgv] : [];
+  const hasTsRuntimeInParent = inheritedExecArgs.some((arg) => /tsx|ts-node/i.test(arg));
+  const nodeArgs = hasTsRuntimeInParent ? [...inheritedExecArgs, options.scriptPath, ...cliArgs] : ["--import", "tsx", options.scriptPath, ...cliArgs];
+  const child = (0, import_node_child_process2.spawn)(
+    process.execPath,
+    nodeArgs,
+    {
+      cwd: options.cwd || process.cwd(),
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+      env: {
+        ...process.env,
+        TASK_ID: options.task.id,
+        TASK_NAME: options.task.task,
+        TASK_OPID: options.task.opid || ""
+      }
+    }
+  );
+  let stdout = "";
+  let stderr = "";
+  let workerResult = null;
+  let hadErrorMessage = false;
+  const prefix = formatChildLogPrefix(options.task);
+  const db = context.db;
+  const tasksTable = context.params?.get?.("table") || "tasks";
+  let progressWriteChain = Promise.resolve();
+  let progressCallbackChain = Promise.resolve();
+  const updateProgress = (text) => {
+    if (!db || !text || !text.trim()) return;
+    progressWriteChain = progressWriteChain.then(async () => {
+      await db(tasksTable).where({ id: options.task.id }).update({ progress: text.slice(0, 4e3) });
+    }).catch((error) => {
+      context.logger.warn?.(
+        `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
+      );
+    });
+    if (options.onProgress) {
+      progressCallbackChain = progressCallbackChain.then(async () => {
+        await options.onProgress?.(text.slice(0, 4e3));
+      }).catch((error) => {
+        context.logger.warn?.(
+          `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
+        );
+      });
+    }
+  };
+  const payloadToProgressText = (payload) => {
+    if (!payload) return "";
+    if (typeof payload === "string") return payload;
+    if (typeof payload.message === "string" && payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
+      const pfx = payload.prefix ? `${payload.prefix} ` : "";
+      return `${pfx}${payload.message} ${payload.count}/${payload.total}`;
+    }
+    if (typeof payload.message === "string") return payload.message;
+    if (payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
+      const pfx = payload.prefix ? `${payload.prefix} ` : "";
+      return `${pfx}${payload.count}/${payload.total}`;
+    }
+    return "";
+  };
+  child.stdout.on("data", (chunk) => {
+    const text = String(chunk);
+    stdout += text;
+    if (text.trim()) {
+      context.logger.info?.(`[child:${prefix}] ${text.trimEnd()}`);
+      updateProgress(text.trim().replace(/\s+/g, " ").slice(0, 400));
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    const text = String(chunk);
+    stderr += text;
+    if (text.trim()) {
+      context.logger.warn?.(`[child:${prefix}] ${text.trimEnd()}`);
+    }
+  });
+  child.on("message", (message) => {
+    if (message && typeof message === "object" && "__taskWorkerResult" in message) {
+      workerResult = message.__taskWorkerResult;
+      return;
+    }
+    if (message && typeof message === "object") {
+      const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
+      if (level === "error" || level === "fatal") {
+        hadErrorMessage = true;
+      }
+    }
+    appendTaskIpcLog(context, options.task, message);
+    const progressText = payloadToProgressText(message);
+    if (progressText) {
+      updateProgress(progressText);
+      if (typeof message === "object" && message?.level === "progress" && message.count !== void 0 && message.total !== void 0) {
+        const countNum = Number(String(message.count).trim());
+        const totalNum = Number(message.total);
+        if (Number.isFinite(countNum) && Number.isFinite(totalNum) && totalNum > 0) {
+          context.logger.progress(message.message || "progress", {
+            prefix: message.prefix || prefix,
+            count: countNum,
+            total: totalNum
+          });
+        } else {
+          context.logger.info?.(`[child:${prefix}] ${progressText}`);
+        }
+      } else {
+        context.logger.info?.(`[child:${prefix}] ${progressText}`);
+      }
+    }
+  });
+  return await new Promise((resolve, reject) => {
+    child.on("error", (error) => reject(error));
+    child.on("close", (exitCode, signal) => {
+      Promise.allSettled([progressWriteChain, progressCallbackChain]).finally(() => {
+        resolve({
+          exitCode,
+          signal,
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          workerResult,
+          hadErrorMessage
+        });
+      });
+    });
+  });
+}
+
+// src/tasks/index.ts
+var LOCKED_BY_ERROR_MESSAGE = "locked by error";
+var defaultTasksRegistry = TasksRegistry.withCoreTasks();
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
+  }
+  return db;
+}
+function normalizeRegistry(registry) {
+  if (!registry) return defaultTasksRegistry;
+  if (registry instanceof TasksRegistry) return registry;
+  return new TasksRegistry().addMany(registry);
+}
+function normalizeAllowedTasks(value) {
+  if (!value) return void 0;
+  if (Array.isArray(value)) {
+    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
+    return out2.length ? out2 : void 0;
+  }
+  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return out.length ? out : void 0;
+}
+async function enqueueStopTask(context, target, queue = "tasks", allowanceMs = 5e3) {
+  return enqueueTask(context, {
+    queue,
+    target,
+    task: "stopRunner",
+    params: { allowanceMs },
+    priority: 1e6
+  });
+}
+async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
+  context.logger.warn?.(`[tasks] signaling ${runningTaskInstances.size} running task(s) to stop`);
+  for (const [, taskInstance] of runningTaskInstances) {
+    if (typeof taskInstance.requestStop === "function") {
+      try {
+        await taskInstance.requestStop(allowanceMs);
+      } catch (error) {
+        context.logger.warn?.("[tasks] task requestStop failed:", error);
+      }
+    }
+  }
+  context.emitter.emit("stop", allowanceMs);
+}
+async function executeClaimedTask(context, tasksTable, historyTable, row, registry, runningTaskInstances) {
+  const db = getDb2(context);
+  const taskName = row.task;
+  const TaskClass = registry.get(taskName);
+  const { paused_at: _pausedAt, ...rowForHistory } = row;
+  if (!TaskClass) {
+    const err = { message: `Unknown task "${taskName}"` };
+    await db(historyTable).insert({
+      ...rowForHistory,
+      completed_at: /* @__PURE__ */ new Date(),
+      success: false,
+      params: toJsonColumn(row.params),
+      results: toJsonColumn(err)
+    });
+    if (row.schedule) {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success: false,
+        results: toJsonColumn(err),
+        past_due: null,
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).delete();
+    }
+    return { stopRunnerRequested: false, stopAllowanceMs: 0 };
+  }
+  let success = false;
+  let results = null;
+  let taskInstance = null;
+  try {
+    taskInstance = new TaskClass(context, row);
+    runningTaskInstances.set(row.id, taskInstance);
+    const runResult = await taskInstance.run((progress) => updateTaskProgress(context, tasksTable, row.id, progress));
+    success = !!runResult?.success;
+    results = runResult?.results ?? null;
+  } catch (error) {
+    success = false;
+    results = {
+      message: error?.message ?? String(error),
+      name: error?.name ?? "Error",
+      stack: error?.stack ?? null
+    };
+  } finally {
+    runningTaskInstances.delete(row.id);
+  }
+  await db(historyTable).insert({
+    ...rowForHistory,
+    completed_at: /* @__PURE__ */ new Date(),
+    success,
+    params: toJsonColumn(row.params),
+    results: toJsonColumn(results)
+  });
+  if (!success) {
+    const dbName = String(context?.params?.get?.("dbName") || "local");
+    const tableName = String(context?.params?.get?.("table") || "tasks");
+    const fallbackRecoverCommand = [
+      "npx",
+      "tsx",
+      "examples/tasks/recover-task.ts",
+      `--dbName='${dbName.replace(/'/g, `'\\''`)}'`,
+      `--table='${tableName.replace(/'/g, `'\\''`)}'`,
+      `--id='${String(row.id).replace(/'/g, `'\\''`)}'`
+    ].join(" ");
+    const rerunCommand = results && typeof results === "object" && results.rerunCommand ? results.rerunCommand : fallbackRecoverCommand;
+    appendTaskIpcLog(context, row, {
+      level: "error",
+      message: `[tasks] task failed: ${row.task} id=${row.id}. Once problem is fixed, re-run: ${rerunCommand}`,
+      details: results
+    });
+  }
+  if (row.schedule) {
+    if (success) {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success,
+        results: toJsonColumn(results),
+        progress: null,
+        past_due: null
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success,
+        results: toJsonColumn(results),
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE,
+        past_due: null
+      });
+    }
+  } else {
+    await db(tasksTable).where({ id: row.id }).delete();
+  }
+  const stopRunnerRequested = !!(results && typeof results === "object" && results.stopRunner === true);
+  const stopAllowanceMs = stopRunnerRequested ? Number(results.allowanceMs ?? 5e3) : 0;
+  return { stopRunnerRequested, stopAllowanceMs };
+}
+async function claimNextRunnableTask(context, tasksTable, target, registry, scanLimit, taskNames) {
+  const db = getDb2(context);
+  let query = db(tasksTable).whereNull("started_at").whereNull("paused_at").where({ target }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "desc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
+  if (taskNames && taskNames.length > 0) {
+    query = query.whereIn("task", taskNames);
+  }
+  const candidates = await query;
+  for (const row of candidates) {
+    if (!row.past_due && row.schedule && !timeMatcher(row.schedule)) {
+      continue;
+    }
+    const TaskClass = registry.get(row.task);
+    if (TaskClass) {
+      const taskInstance = new TaskClass(context, row);
+      const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
+      if (reason) {
+        if (!row.past_due) {
+          await db(tasksTable).where({ id: row.id }).update({
+            past_due: db.fn.now(),
+            progress: String(reason)
+          });
+        }
+        continue;
+      }
+    }
+    const updated = await db(tasksTable).where({ id: row.id }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).returning("*");
+    const claimed = Array.isArray(updated) ? updated[0] : null;
+    if (claimed) return claimed;
+  }
+  return null;
+}
+async function runTasksLoop(context, options) {
+  const queue = options.queue ?? "tasks";
+  const target = options.target;
+  const pollMs = options.pollMs ?? 1e3;
+  const maxParallel = options.maxParallel ?? 1;
+  const scanLimit = options.scanLimit ?? 100;
+  const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
+  const registry = normalizeRegistry(options.registry);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  if (!target) throw new Error("runTasksLoop: target is required");
+  const runningPromises = /* @__PURE__ */ new Set();
+  const runningTaskInstances = /* @__PURE__ */ new Map();
+  let runningStopControlPromise = null;
+  let stopRequested = false;
+  let stopAllowanceMs = 5e3;
+  context.__tasksRunnerStop = false;
+  while (!context.isStop() && !stopRequested && !context.__tasksRunnerStop) {
+    if (!runningStopControlPromise) {
+      const claimedStopTask = await claimNextRunnableTask(
+        context,
+        tasksTable,
+        target,
+        registry,
+        10,
+        ["stopRunner", "stop"]
+      );
+      if (claimedStopTask) {
+        runningStopControlPromise = executeClaimedTask(
+          context,
+          tasksTable,
+          historyTable,
+          claimedStopTask,
+          registry,
+          runningTaskInstances
+        ).then(async (outcome) => {
+          if (outcome.stopRunnerRequested && !stopRequested) {
+            stopRequested = true;
+            stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+            context.__tasksRunnerStop = true;
+            await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+          }
+        }).finally(() => {
+          runningStopControlPromise = null;
+        });
+      }
+    }
+    while (runningPromises.size < maxParallel) {
+      const claimed = await claimNextRunnableTask(
+        context,
+        tasksTable,
+        target,
+        registry,
+        scanLimit,
+        allowedTasks
+      );
+      if (!claimed) break;
+      const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
+        if (outcome.stopRunnerRequested && !stopRequested) {
+          stopRequested = true;
+          stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+          context.__tasksRunnerStop = true;
+          await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+        }
+      }).finally(() => {
+        runningPromises.delete(p);
+      });
+      runningPromises.add(p);
+    }
+    await sleepMs(pollMs);
+  }
+  if (context.isStop() && !stopRequested) {
+    await signalRunningTasksStop(context, runningTaskInstances, 5e3);
+  }
+  if (runningPromises.size > 0) {
+    if (stopRequested) {
+      await Promise.race([
+        Promise.allSettled(Array.from(runningPromises)),
+        sleepMs(stopAllowanceMs).then(() => {
+          context.logger.warn?.(
+            `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
+          );
+        })
+      ]);
+    } else {
+      await Promise.allSettled(Array.from(runningPromises));
+    }
+  }
+}
+async function waitForTaskResult(context, taskId, options = {}) {
+  const db = getDb2(context);
+  const queue = options.queue ?? "tasks";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const pollMs = options.pollMs ?? 500;
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    const done = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
+    if (done) return done;
+    const pending = await db(tasksTable).where({ id: taskId }).first();
+    if (!pending) {
+      const maybeDone = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
+      return maybeDone ?? null;
+    }
+    await sleepMs(pollMs);
+  }
+  return null;
+}
+var TasksManager = class _TasksManager {
+  context;
+  queue;
+  target;
+  recreateTaskTables;
+  pollMs;
+  maxParallel;
+  scanLimit;
+  allowedTasks;
+  registry;
+  constructor(context, options = {}) {
+    this.context = context;
+    this.queue = options.queue ?? "tasks";
+    this.target = options.target ?? "localRunner";
+    this.recreateTaskTables = options.recreateTaskTables ?? false;
+    this.pollMs = options.pollMs ?? 1e3;
+    this.maxParallel = options.maxParallel ?? 1;
+    this.scanLimit = options.scanLimit ?? 100;
+    this.allowedTasks = normalizeAllowedTasks(options.allowedTasks);
+    this.registry = normalizeRegistry(options.registry);
+  }
+  static init(context, options = {}) {
+    const defs = {
+      table: "string default tasks",
+      target: "string default localRunner",
+      recreateTaskTables: "boolean default false",
+      pollMs: "number default 1000",
+      maxParallel: "number default 1",
+      scanLimit: "number default 100",
+      allowedTasks: "string"
+    };
+    const discovered = context.params.getAllForModule(defs);
+    const resolved = {
+      queue: discovered.table,
+      target: discovered.target,
+      recreateTaskTables: discovered.recreateTaskTables,
+      pollMs: discovered.pollMs,
+      maxParallel: discovered.maxParallel,
+      scanLimit: discovered.scanLimit,
+      allowedTasks: discovered.allowedTasks,
+      ...options
+    };
+    return new _TasksManager(context, resolved);
+  }
+  async ensureTaskTables(options = {}) {
+    await ensureTaskTables(this.context, {
+      queue: this.queue,
+      recreate: options.recreate ?? this.recreateTaskTables
+    });
+  }
+  async runTasksLoop(options = {}) {
+    await runTasksLoop(this.context, {
+      queue: options.queue ?? this.queue,
+      target: options.target ?? this.target,
+      pollMs: options.pollMs ?? this.pollMs,
+      maxParallel: options.maxParallel ?? this.maxParallel,
+      scanLimit: options.scanLimit ?? this.scanLimit,
+      allowedTasks: options.allowedTasks ?? this.allowedTasks,
+      registry: options.registry ?? this.registry
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskMaster,
+  TaskPing,
+  TaskSampleProcess,
+  TaskShellCommand,
+  TaskStopRunner,
+  TaskSumAB,
+  TaskSystemInfo,
+  TasksManager,
+  TasksRegistry,
+  appendTaskIpcLog,
+  defaultTasksRegistry,
+  enqueueStopTask,
+  enqueueTask,
+  ensureTaskTables,
+  queueToTableNames,
+  runNodeTaskScript,
+  runTasksLoop,
+  updateTaskProgress,
+  waitForTaskResult
+});
+//# sourceMappingURL=tasks.cjs.map