@nmakarov/cli-toolkit 0.14.2 → 0.16.0

package/dist/init.cjs

@@ -1143,20 +1143,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
@@ -1178,12 +1189,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
@@ -1363,6 +1377,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)
    */
@@ -1715,17 +1755,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
@@ -1744,14 +1820,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
     });
   }
   /**
@@ -1761,7 +1838,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
    */
@@ -1775,6 +1852,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
    */
@@ -1893,14 +1983,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}`);
@@ -1921,19 +2016,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 path = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path || path.includes(paramsIndexPath)) continue;
+      const srcMatch = path.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      if (srcMatch) return srcMatch[1];
+    }
+    return "script";
   }
   /**
    * Run all registered getters for a key
@@ -2043,8 +2182,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) {
@@ -2054,32 +2192,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 = {
@@ -2093,20 +2223,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;
@@ -2133,6 +2251,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 });
   }
@@ -2308,12 +2430,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: [],
@@ -2321,6 +2438,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");
@@ -2381,6 +2503,7 @@ async function init(flow, opts = {}) {
     context.isStop = () => stop;
     context = await setupModules(context, opts);
     const stopAfter = context.args.get("stopAfter");
+    const stopAllowance = context.params.get("stopAllowance", "number default 5");
     if (stopAfter === "init") {
       printAllParameters(context);
       process.exit(0);
@@ -2391,13 +2514,8 @@ async function init(flow, opts = {}) {
         process.exit(2);
       }
       stop = true;
-      let allowance = 5;
-      try {
-        allowance = context.params.get("stopAllowance", "number default 5");
-      } catch {
-      }
-      context.logger.info(`>> emitting stop with allowance ${allowance}`);
-      context.emitter.emit("stop", allowance);
+      context.logger.info(`>> emitting stop with allowance ${stopAllowance}`);
+      context.emitter.emit("stop", stopAllowance);
     });
     await flow(context);
   } catch (error) {
@@ -2428,10 +2546,6 @@ async function init(flow, opts = {}) {
           context.logger.warn("[cleanup] error in cleanup function:", error);
         }
       }
-      const unusedArgs = context.args.getUnused();
-      if (unusedArgs.length > 0) {
-        context.logger.warn("Unused CLI args:", unusedArgs.join(", "));
-      }
     }
   }
 }