@nmakarov/cli-toolkit 0.14.2 → 0.16.0

package/dist/index.cjs

@@ -1117,7 +1117,6 @@ __export(src_exports, {
   dbInit: () => dbInit,
   defaultFileSynopsisFunction: () => defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction: () => defaultVersionSynopsisFunction,
-  fileDatabaseInit: () => fileDatabaseInit,
   getArgsInstance: () => getArgsInstance,
   h: () => import_react5.createElement,
   joiEdateType: () => joiEdateType,
@@ -1160,20 +1159,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
@@ -1195,12 +1205,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
@@ -1380,6 +1393,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)
    */
@@ -1605,6 +1644,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) => {
@@ -1730,17 +1775,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
@@ -1759,14 +1840,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
     });
   }
   /**
@@ -1776,7 +1858,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
    */
@@ -1790,6 +1872,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
    */
@@ -1908,14 +2003,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}`);
@@ -1936,19 +2036,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
@@ -2170,13 +2314,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;
@@ -2213,18 +2351,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;
     }
@@ -2242,6 +2370,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
    */
@@ -3107,9 +3242,6 @@ function listSources(basePath) {
     return [];
   }
 }
-function fileDatabaseInit(context, options = {}) {
-  return new FileDatabase(context, options);
-}
 
 // src/db/index.ts
 var import_knex = __toESM(require("knex"), 1);
@@ -3408,6 +3540,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);
@@ -3421,7 +3560,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",
@@ -3471,7 +3610,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;
@@ -3563,8 +3702,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) {
@@ -3574,32 +3712,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 = {
@@ -3613,20 +3743,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;
@@ -3653,6 +3771,10 @@ var Logger = class _Logger {
     }
     this.options.mode = mode;
   }
+  /** Returns a styled string (bright white) for highlighting; keeps chalk inside logger. */
+  highlight(text) {
+    return import_chalk.default.whiteBright(text);
+  }
   debug(message, ...chunks) {
     this.out({ level: "debug", message, chunks });
   }
@@ -3828,12 +3950,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 import_events.EventEmitter(),
     isStop: () => false,
     cleanupFunctions: [],
@@ -3841,6 +3958,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");
@@ -3894,7 +4016,6 @@ function setupContext(opts = {}) {
   dbInit,
   defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction,
-  fileDatabaseInit,
   getArgsInstance,
   h,
   joiEdateType,