@nmakarov/cli-toolkit 0.14.2 → 0.18.0

package/dist/index.js

@@ -1073,20 +1073,31 @@ var Args = class _Args {
   configValues = {};
   configsLoaded = [];
   env = "local";
-  constructor(config2 = {}) {
+  constructor(contextOrConfig = {}, config2) {
+    const hasContext = config2 !== void 0;
+    const configToUse = hasContext ? config2 ?? {} : contextOrConfig ?? {};
+    const context = hasContext ? contextOrConfig : void 0;
     this.aliases = {};
     this.overrides = {};
     this.defaults = {};
     this.prefixes = ["not", "no"];
-    if (Object.keys(config2).length > 0) {
-      this.configure(config2);
+    if (Object.keys(configToUse).length > 0) {
+      this.configure(configToUse);
     }
-    const args = config2.args || process.argv.slice(2);
+    const args = configToUse.args || process.argv.slice(2);
     this.parseArgs(args);
     this.env = this.get("env")?.toLowerCase() || "local";
     this.loadDotEnv();
     this.loadConfigFiles();
     this.checkConflicts();
+    if (context && typeof context.registerCleanup === "function") {
+      context.registerCleanup((ctx) => {
+        const unusedArgs = ctx.args.getUnused();
+        if (unusedArgs.length > 0) {
+          ctx.logger.warn("Unused CLI args:", unusedArgs.join(", "));
+        }
+      });
+    }
   }
   /**
    * Configure Args options
@@ -1108,12 +1119,15 @@ var Args = class _Args {
     }
   }
   /**
-   * Initialize Args instance
-   * Note: Args is special - it's initialized first, so it can't take context
-   * This static method is for consistency with other components
+   * Initialize Args instance.
+   * Args.init(context, config) when used from init/setup: context has registerCleanup, Args registers unused-args cleanup.
+   * Args.init(config) for standalone use (no cleanup).
    */
-  static init(config2 = {}) {
-    return new _Args(config2);
+  static init(contextOrConfig, config2) {
+    if (config2 !== void 0) {
+      return new _Args(contextOrConfig, config2);
+    }
+    return new _Args(contextOrConfig ?? {});
   }
   /**
    * Parse command line arguments
@@ -1293,6 +1307,32 @@ var Args = class _Args {
     }
     return void 0;
   }
+  /**
+   * Return which layer provided the value for get(key): overrides, cli, config, env, or default.
+   * Does not add key to usedKeys. Use after get(key) when you need the origin.
+   */
+  getSource(key) {
+    const resolvedKey = this.aliases[key] || key;
+    const lcKey = resolvedKey.toLowerCase();
+    const overrideKey = Object.keys(this.overrides).find((k) => k.toLowerCase() === lcKey);
+    if (overrideKey !== void 0) return "overrides";
+    const lcKeyWithEnv = `${lcKey}${this.env ? `_${this.env.toLowerCase()}` : ""}`;
+    if (this.env && this.args[lcKeyWithEnv] !== void 0) return "cli";
+    if (this.args[lcKey] !== void 0) return "cli";
+    const configKey = Object.keys(this.configValues).find((k) => k.toLowerCase() === lcKey);
+    if (configKey !== void 0) return "config";
+    const envKey = this.toEnvKey(resolvedKey);
+    const envKeyWithEnv = `${envKey}${this.env ? `_${this.env.toUpperCase()}` : ""}`;
+    const envSpecificKey = Object.keys(process.env).find((k) => this.env && k.toUpperCase() === envKeyWithEnv);
+    const envKeyFound = Object.keys(process.env).find((k) => k.toUpperCase() === envKey);
+    const envKeyAlt = envKey.replace(/_([0-9])/g, "$1");
+    const envKeyAltFound = !envKeyFound ? Object.keys(process.env).find((k) => k.toUpperCase() === envKeyAlt) : null;
+    if (envSpecificKey || envKeyFound || envKeyAltFound) return "env";
+    const defaultKey = Object.keys(this.defaults).find((k) => k.toLowerCase() === lcKey);
+    if (defaultKey !== void 0) return "default";
+    if (lcKey === "env" && process.env.NODE_ENV !== void 0) return "env";
+    return void 0;
+  }
   /**
    * Set a value (for testing/internal use)
    */
@@ -1518,6 +1558,12 @@ var ParamError = class extends FrameworkError {
     this.name = "ParamError";
   }
 };
+var FileDatabaseError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
 
 // src/params/custom-types.ts
 var joiEdateType = (value, helpers) => {
@@ -1643,17 +1689,53 @@ var Params = class _Params {
   context;
   // Partial context during initialization
   params = {};
+  paramSources = {};
   definitions = {};
   args;
   paramSetters = [];
   paramGetters = [];
   trackedParams = [];
+  _currentModule = "script";
+  /** Resolved early in constructor so cleanup does not read params lazily */
+  _showUsedParams = false;
   constructor(context, options = {}) {
     this.context = context;
     this.args = context.args;
     if (Object.keys(options).length > 0) {
       this.configure(options);
     }
+    this._showUsedParams = this.get("showUsedParams", "boolean default false");
+    if (context && typeof context.registerCleanup === "function") {
+      context.registerCleanup((ctx) => {
+        if (!ctx.params.getShowUsedParams()) return;
+        const byModule = ctx.params.getFiguredByModule();
+        const modules = Object.keys(byModule).sort();
+        if (modules.length === 0) return;
+        const logger = ctx.logger;
+        logger.debug("[Params]: list of used params:");
+        if (typeof logger.highlight !== "function") {
+          for (const mod of modules) {
+            logger.debug(`  [${mod}]`);
+            for (const [key, entry] of Object.entries(byModule[mod])) {
+              logger.debug(`    ${key}: ${JSON.stringify(entry.value)} (${entry.source})`);
+            }
+          }
+          return;
+        }
+        for (const mod of modules) {
+          logger.debug(`  [${mod}]`);
+          for (const [key, entry] of Object.entries(byModule[mod])) {
+            const valueStr = JSON.stringify(entry.value);
+            const display = entry.source === "default" ? valueStr : logger.highlight(valueStr);
+            logger.debug(`    ${key}: ${display} (${entry.source})`);
+          }
+        }
+      });
+    }
+  }
+  /** Whether --showUsedParams was requested (resolved in constructor). */
+  getShowUsedParams() {
+    return this._showUsedParams;
   }
   /**
    * Configure parameters
@@ -1672,14 +1754,15 @@ var Params = class _Params {
     return new _Params(context, options || {});
   }
   /**
-   * Track a parameter request for --stopAfter=init feature
+   * Track a parameter request for --stopAfter=init and --showUsedParams
    */
-  trackParam(key, definition, value, source) {
+  trackParam(key, definition, value, source, moduleName) {
     this.trackedParams.push({
       key,
       definition,
       value,
-      source
+      source,
+      module: moduleName ?? this._currentModule
     });
   }
   /**
@@ -1689,7 +1772,7 @@ var Params = class _Params {
     return [...this.trackedParams];
   }
   /**
-   * Get all figured parameters as a record
+   * Get all figured parameters as a record (flat, last occurrence per key)
    * Returns all parameters that were collected during initialization,
    * whether from CLI args, options, or defaults
    */
@@ -1703,6 +1786,19 @@ var Params = class _Params {
     }
     return result;
   }
+  /**
+   * Get figured parameters grouped by module name.
+   * Same param can appear in multiple modules (e.g. source, resource).
+   */
+  getFiguredByModule() {
+    const byModule = {};
+    for (const param of this.trackedParams) {
+      const mod = param.module;
+      if (!byModule[mod]) byModule[mod] = {};
+      byModule[mod][param.key] = { value: param.value, source: param.source };
+    }
+    return byModule;
+  }
   /**
    * Clear tracked parameters
    */
@@ -1821,14 +1917,19 @@ var Params = class _Params {
       source = "options";
     } else if (valFromArgs !== void 0 && valFromArgs !== null) {
       value = this.validate(key, valFromArgs, def);
-      source = "cli";
+      const argsSource = this.args.getSource?.(key);
+      if (argsSource === "overrides") source = "options";
+      else if (argsSource === "cli" || argsSource === "env" || argsSource === "config") source = argsSource;
+      else if (argsSource === "default") source = "default";
+      else source = "cli";
     } else if (valFromParams !== void 0 && valFromParams !== null) {
       value = this.validate(key, valFromParams, def);
-      source = "options";
+      source = this.paramSources[key] ?? "options";
     } else {
       value = this.validate(key, void 0, def);
       source = "default";
     }
+    this.paramSources[key] = source;
     this.trackParam(key, definition || "string", value, source);
     if (value !== void 0 && def.values && !def.values.includes(value)) {
       throw new ParamError(`key ${key} should be one of ${def.values}`);
@@ -1849,19 +1950,63 @@ var Params = class _Params {
     }
   }
   /**
-   * Get all parameters from definitions
-   * Processes parameters left-to-right to support cross-parameter references
+   * Get all parameters from definitions (main script).
+   * Same as getAllForModule("script", defs). Processes left-to-right for cross-parameter references.
    */
   getAll(defs) {
-    const res = {};
-    for (const [k, def] of Object.entries(defs)) {
-      const value = this.get(k, def);
-      res[k] = value;
-      if (value !== void 0) {
-        this.params[k] = value;
+    return this.getAllForModule("script", defs);
+  }
+  /**
+   * Get all parameters from definitions for a given module name.
+   * Figured params are grouped by module when using --showUsedParams.
+   * Processes parameters left-to-right to support cross-parameter references.
+   * If moduleName is omitted, it is inferred from the caller's file path (directory name under src/).
+   */
+  getAllForModule(moduleNameOrDefs, defs) {
+    let moduleName;
+    let definitions;
+    if (defs !== void 0) {
+      moduleName = moduleNameOrDefs;
+      definitions = defs;
+    } else {
+      definitions = moduleNameOrDefs;
+      moduleName = this._inferModuleNameFromStack();
+    }
+    const prev = this._currentModule;
+    this._currentModule = moduleName;
+    try {
+      const res = {};
+      for (const [k, def] of Object.entries(definitions)) {
+        const value = this.get(k, def);
+        res[k] = value;
+        if (value !== void 0) {
+          this.params[k] = value;
+        }
       }
+      return res;
+    } finally {
+      this._currentModule = prev;
     }
-    return res;
+  }
+  /**
+   * Infer module name from call stack: first caller outside params/index gives path like .../src/<moduleName>/...
+   */
+  _inferModuleNameFromStack() {
+    const stack = new Error().stack;
+    if (!stack) return "script";
+    const lines = stack.split("\n");
+    const paramsIndexPath = "params" + (typeof process !== "undefined" && process.platform === "win32" ? "\\" : "/") + "index.";
+    for (const line of lines) {
+      const parenMatch = line.match(/\(([^)]+)\)/);
+      if (!parenMatch) continue;
+      const parts = parenMatch[1].split(":");
+      if (parts.length < 3) continue;
+      const path4 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path4 || path4.includes(paramsIndexPath)) continue;
+      const srcMatch = path4.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      if (srcMatch) return srcMatch[1];
+    }
+    return "script";
   }
   /**
    * Run all registered getters for a key
@@ -2083,13 +2228,7 @@ function defaultVersionSynopsisFunction(metadata) {
 }
 
 // src/filedatabase/index.ts
-var FileDatabaseError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FileDatabaseError";
-  }
-};
-var FileDatabase = class {
+var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
   tableName = null;
@@ -2126,18 +2265,8 @@ var FileDatabase = class {
         maxVersions: "number default 5",
         pageSize: "number default 5000"
       };
-      const paramsConfig = context.params.getAll(defs);
-      config2 = {
-        basePath: opts.basePath ?? paramsConfig.basePath,
-        namespace: opts.namespace ?? paramsConfig.namespace,
-        tableName: opts.tableName ?? paramsConfig.tableName ?? null,
-        versioned: opts.versioned ?? true,
-        maxVersions: opts.maxVersions ?? paramsConfig.maxVersions,
-        pageSize: opts.pageSize ?? paramsConfig.pageSize,
-        useMetadata: opts.useMetadata ?? true,
-        freeSpaceThreshold: opts.freeSpaceThreshold ?? 100 * 1024 * 1024,
-        logger: context.logger
-      };
+      const discovered = context.params.getAllForModule(defs);
+      config2 = { ...discovered, ...opts, logger: context.logger };
     } else {
       config2 = contextOrConfig;
     }
@@ -2155,6 +2284,13 @@ var FileDatabase = class {
     this.logger = config2.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
    */
@@ -2222,7 +2358,7 @@ var FileDatabase = class {
     const versions = await this.getVersions();
     while (versions.length > this.maxVersions) {
       const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
-      this.logger.debug?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
       await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
     }
     return versionName;
@@ -2500,7 +2636,7 @@ var FileDatabase = class {
     };
     this.metadata.files.push(fileEntry);
     this.lastFileData = null;
-    this.logger.debug?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+    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)
@@ -2533,7 +2669,7 @@ var FileDatabase = class {
       const filesBeforeCreate = this.metadata.files.length;
       this.makeNewFile();
       newlyCreatedFileIndex = filesBeforeCreate;
-      this.logger.debug?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
+      this.logger.silly?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
     } else if (this.metadata.files.length === 0) {
       this.makeNewFile();
     }
@@ -2582,7 +2718,7 @@ var FileDatabase = class {
       dataLeftOver = null;
     }
     const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
-    this.logger.debug?.(
+    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 };
@@ -2637,7 +2773,7 @@ var FileDatabase = class {
     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.debug?.(
+    this.logger.silly?.(
       `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
     );
   }
@@ -2661,7 +2797,7 @@ var FileDatabase = class {
     }
     try {
       await fs3.promises.writeFile(filePath, serializedData, "utf8");
-      this.logger.debug?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+      this.logger.silly?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
     } catch (error) {
       throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
     }
@@ -2743,7 +2879,8 @@ var FileDatabase = class {
           this.useMetadata = format.hasMetadata;
         }
         if (this.useMetadata) {
-          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          const destPath = this.getDestinationPath();
+          const metadataPath = path3.join(destPath, "metadata.json");
           if (fs3.existsSync(metadataPath)) {
             try {
               const rawData = await fs3.promises.readFile(metadataPath, "utf8");
@@ -2757,7 +2894,9 @@ var FileDatabase = class {
               throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
             }
           } else {
-            throw new FileDatabaseError("[FileDatabase] No metadata found in non-versioned mode");
+            throw new FileDatabaseError(
+              `[FileDatabase] No metadata found in non-versioned mode. Looked for: ${metadataPath} (table path: ${destPath})`
+            );
           }
         } else {
           this.metadata = await this.figureMetadataFromVersionFiles("");
@@ -2774,6 +2913,13 @@ var FileDatabase = class {
    * 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");
     }
@@ -2797,17 +2943,17 @@ var FileDatabase = class {
         });
         if (matches) {
           targetFileIndex = i;
-          this.logger.debug?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
           break;
         } else {
-          this.logger.debug?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
         }
       }
       if (targetFileIndex === null) {
-        this.logger.debug?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
+        this.logger.silly?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
       }
     } else {
-      this.logger.debug?.(`[FileDatabase] No custom metadata provided, will create new file`);
+      this.logger.silly?.(`[FileDatabase] No custom metadata provided, will create new file`);
     }
     if (targetFileIndex !== null) {
       const targetFile = this.metadata.files[targetFileIndex];
@@ -2836,7 +2982,17 @@ var FileDatabase = class {
    * Read data from the file database
    */
   async read(options = {}) {
-    const { version, nextPage = false, pageSize } = 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) {
@@ -2917,6 +3073,67 @@ var FileDatabase = class {
     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
    */
@@ -3020,9 +3237,6 @@ function listSources(basePath) {
     return [];
   }
 }
-function fileDatabaseInit(context, options = {}) {
-  return new FileDatabase(context, options);
-}
 
 // src/db/index.ts
 import knex from "knex";
@@ -3321,6 +3535,13 @@ var Db = class {
   isConnectedToDb() {
     return this.isConnected && this.knexInstance !== null;
   }
+  /**
+   * Initialize Db with context (connects and registers disconnect cleanup).
+   * Params are read via getAllForModule("db", defs). Same as dbInit(context, dbNameOrConnectionString).
+   */
+  static async init(context, dbNameOrConnectionString) {
+    return dbFindAndConnect(context, dbNameOrConnectionString);
+  }
 };
 function capitalizeFirstLetter(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
@@ -3334,7 +3555,7 @@ async function dbConnect(context, connectionString, name, dbProfile) {
     acquireConnectionTimeout: "number default 10000",
     sslRejectUnauthorized: "boolean default false"
   };
-  const paramsConfig = context.params.getAll(defs);
+  const paramsConfig = context.params.getAllForModule(defs);
   const config2 = {
     connectionString,
     name: paramsConfig.name || name || "default",
@@ -3384,7 +3605,7 @@ async function dbFindAndConnect(context, dbNameOrConnectionString) {
       dbConnectionString: "string",
       dbProfile: "boolean default false"
     };
-    const paramsConfig = context.params.getAll(defs);
+    const paramsConfig = context.params.getAllForModule(defs);
     dbName = paramsConfig.dbName;
     dbConnectionString = paramsConfig.dbConnectionString;
     dbProfile = paramsConfig.dbProfile;
@@ -3446,6 +3667,7 @@ var ALL_LEVELS = [
   "response",
   "progress"
 ];
+var DEFAULT_LEVELS = ALL_LEVELS.filter((l) => l !== "silly");
 var MAX_LEVEL_LENGTH = Math.max(...ALL_LEVELS.map((level) => level.toUpperCase().length));
 var LEVEL_COLORS = {
   error: chalk.red.bold,
@@ -3476,8 +3698,7 @@ var Logger = class _Logger {
     this.updateTransport();
   }
   /**
-   * Configure logger options
-   * Only parameters present in options are updated
+   * Configure logger options. Accepts both LoggerOptions shape and flat param names (levels string, progressWithTimes, progressThrottleMs).
    */
   configure(options) {
     if (options.mode !== void 0) {
@@ -3487,32 +3708,24 @@ var Logger = class _Logger {
       this.options.route = options.route;
       this.updateTransport();
     }
-    if (options.prefix !== void 0) {
-      this.options.prefix = options.prefix;
-    }
-    if (options.silent !== void 0) {
-      this.options.silent = options.silent;
-    }
-    if (options.showLevel !== void 0) {
-      this.options.showLevel = options.showLevel;
-    }
-    if (options.timestamp !== void 0) {
-      this.options.timestamp = options.timestamp;
-    }
+    if (options.prefix !== void 0) this.options.prefix = options.prefix;
+    if (options.silent !== void 0) this.options.silent = options.silent;
+    if (options.showLevel !== void 0) this.options.showLevel = options.showLevel;
+    if (options.timestamp !== void 0) this.options.timestamp = options.timestamp;
     if (options.levels !== void 0) {
-      this.options.levels = this.normalizeLevels(options.levels);
+      const levels = typeof options.levels === "string" ? options.levels.split(",") : options.levels;
+      this.options.levels = this.normalizeLevels(levels);
     }
     if (options.progress !== void 0) {
-      if (options.progress.withTimes !== void 0) {
-        this.options.progressTimes = options.progress.withTimes;
-      }
-      if (options.progress.throttleMs !== void 0) {
-        this.options.progressThrottle = options.progress.throttleMs;
-      }
+      if (options.progress.withTimes !== void 0) this.options.progressTimes = options.progress.withTimes;
+      if (options.progress.throttleMs !== void 0) this.options.progressThrottle = options.progress.throttleMs;
     }
+    const flat = options;
+    if (flat.progressWithTimes !== void 0) this.options.progressTimes = flat.progressWithTimes;
+    if (flat.progressThrottleMs !== void 0) this.options.progressThrottle = flat.progressThrottleMs;
   }
   /**
-   * Initialize logger from context and CLI parameters
+   * Initialize logger from context and CLI parameters. Whatever is in options goes (after discovered params).
    */
   static init(context, options) {
     const paramDefs = {
@@ -3526,20 +3739,8 @@ var Logger = class _Logger {
       progressWithTimes: "boolean default false",
       progressThrottleMs: "number"
     };
-    const cliParams = context.params.getAll(paramDefs);
-    const config2 = {
-      mode: options?.mode ?? cliParams.mode,
-      route: options?.route ?? cliParams.route,
-      prefix: options?.prefix ?? cliParams.prefix,
-      silent: options?.silent ?? cliParams.silent,
-      showLevel: options?.showLevel ?? cliParams.showLevel,
-      timestamp: options?.timestamp ?? cliParams.timestamp,
-      levels: options?.levels ?? (cliParams.levels ? cliParams.levels.split(",") : void 0),
-      progress: options?.progress ?? {
-        withTimes: cliParams.progressWithTimes,
-        throttleMs: cliParams.progressThrottleMs
-      }
-    };
+    const discovered = context.params.getAllForModule(paramDefs);
+    const config2 = { ...discovered, ...options };
     const logger = new _Logger(context, config2);
     context.logger = logger;
     return logger;
@@ -3552,7 +3753,7 @@ var Logger = class _Logger {
       silent: false,
       showLevel: false,
       timestamp: false,
-      levels: ALL_LEVELS,
+      levels: DEFAULT_LEVELS,
       progressTimes: false,
       progressThrottle: void 0
     };
@@ -3566,6 +3767,10 @@ var Logger = class _Logger {
     }
     this.options.mode = mode;
   }
+  /** Returns a styled string (bright white) for highlighting; keeps chalk inside logger. */
+  highlight(text) {
+    return chalk.whiteBright(text);
+  }
   debug(message, ...chunks) {
     this.out({ level: "debug", message, chunks });
   }
@@ -3708,15 +3913,17 @@ var Logger = class _Logger {
   }
   normalizeLevels(levels) {
     if (!levels || !levels.length) {
-      return ALL_LEVELS;
+      return DEFAULT_LEVELS;
     }
-    const includes = levels.filter((level) => !level.startsWith("-"));
-    const excludes = levels.filter((level) => level.startsWith("-")).map((level) => level.slice(1));
-    const unknown = [...includes, ...excludes].filter((level) => !ALL_LEVELS.includes(level));
+    const tokens = levels.map((t) => String(t).trim()).filter(Boolean);
+    const explicitIncludes = tokens.filter((t) => !t.startsWith("+") && !t.startsWith("-")).map((t) => t);
+    const addIncludes = tokens.filter((t) => t.startsWith("+")).map((t) => t.slice(1));
+    const excludes = tokens.filter((t) => t.startsWith("-")).map((t) => t.slice(1));
+    const unknown = [...explicitIncludes, ...addIncludes, ...excludes].filter((level) => !ALL_LEVELS.includes(level));
     if (unknown.length) {
       console.warn(`[Logger] Unknown level(s): ${unknown.join(", ")}`);
     }
-    const base = includes.length ? includes : ALL_LEVELS;
+    const base = explicitIncludes.length ? explicitIncludes : Array.from(/* @__PURE__ */ new Set([...DEFAULT_LEVELS, ...addIncludes]));
     return base.filter((level) => !excludes.includes(level));
   }
   isValidMode(mode) {
@@ -3741,12 +3948,7 @@ function extractComponentOptions(opts, componentName) {
   return componentOptions;
 }
 function setup(opts = {}) {
-  const args = Args.init({
-    overrides: opts.overrides || {},
-    defaults: opts.defaults || {}
-  });
   const partialContext = {
-    args,
     emitter: new EventEmitter(),
     isStop: () => false,
     cleanupFunctions: [],
@@ -3754,6 +3956,11 @@ function setup(opts = {}) {
       partialContext.cleanupFunctions.push(fn);
     }
   };
+  const args = Args.init(partialContext, {
+    overrides: opts.overrides || {},
+    defaults: opts.defaults || {}
+  });
+  partialContext.args = args;
   const params = Params.init(partialContext, opts.overrides || {});
   partialContext.params = params;
   const loggerOptions = extractComponentOptions(opts, "logger");
@@ -3774,6 +3981,1107 @@ function setup(opts = {}) {
 function setupContext(opts = {}) {
   return setup(opts);
 }
+
+// src/utils/core-utils.ts
+function sleepMs(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function toJsonColumn(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
+
+// src/tasks/taskUtils.ts
+import { randomUUID } from "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 = 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/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
+import { spawn } from "child_process";
+function runShellCommand(command, cwd) {
+  return new Promise((resolve2, reject) => {
+    const child = 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) => {
+      resolve2({
+        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
+import os from "os";
+import fs4 from "fs/promises";
+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 fs4.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 = os.totalmem();
+      const freeMemory = os.freemem();
+      const usedMemory = totalMemory - freeMemory;
+      const cpus = os.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: os.platform(),
+          arch: os.arch(),
+          uptimeSec: os.uptime(),
+          hostname: os.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
+import { spawn as spawn2 } from "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 = spawn2(
+    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((resolve2, reject) => {
+    child.on("error", (error) => reject(error));
+    child.on("close", (exitCode, signal) => {
+      Promise.allSettled([progressWriteChain, progressCallbackChain]).finally(() => {
+        resolve2({
+          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
+    });
+  }
+};
 export {
   Args,
   Box5 as Box,
@@ -3796,8 +5104,18 @@ export {
   ScreenFooter,
   ScreenRow,
   ScreenTitle,
+  TaskMaster,
+  TaskPing,
+  TaskSampleProcess,
+  TaskShellCommand,
+  TaskStopRunner,
+  TaskSumAB,
+  TaskSystemInfo,
+  TasksManager,
+  TasksRegistry,
   Text5 as Text,
   TextBlock,
+  appendTaskIpcLog,
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
@@ -3805,8 +5123,11 @@ export {
   dbFindAndConnect,
   dbInit,
   defaultFileSynopsisFunction,
+  defaultTasksRegistry,
   defaultVersionSynopsisFunction,
-  fileDatabaseInit,
+  enqueueStopTask,
+  enqueueTask,
+  ensureTaskTables,
   getArgsInstance,
   createElement2 as h,
   joiEdateType,
@@ -3815,6 +5136,9 @@ export {
   listTables,
   load,
   organizeFooterMessages,
+  queueToTableNames,
+  runNodeTaskScript,
+  runTasksLoop,
   setupContext,
   showListScreen,
   showMenuScreen,
@@ -3822,11 +5146,13 @@ export {
   showMultiColumnListWithPreviewScreen,
   showScreen,
   showWordGridScreen,
+  updateTaskProgress,
   useCallback,
   useEffect3 as useEffect,
   useInput2 as useInput,
   useMemo,
   useRef3 as useRef,
-  useState3 as useState
+  useState3 as useState,
+  waitForTaskResult
 };
 //# sourceMappingURL=index.js.map