@nmakarov/cli-toolkit 0.25.0 → 0.27.0

package/dist/index.cjs

@@ -1810,46 +1810,83 @@ var Params = class _Params {
   paramGetters = [];
   trackedParams = [];
   _currentModule = "script";
-  /** Resolved early in constructor so cleanup does not read params lazily */
-  _showUsedParams = false;
+  /**
+   * Resolved early in constructor so cleanup does not read params lazily.
+   * One of: false (off) | "end" (print at exit) | "top" (print after init,
+   * via context.showUsedParamsIfNeeded()).
+   */
+  _showUsedParamsMode = false;
+  /** Guard so the dump prints at most once (top OR end, never both). */
+  _usedParamsPrinted = 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");
+    this._resolveShowUsedParams();
     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})`);
-          }
-        }
+        if (!ctx.params.getShowUsedParamsMode()) return;
+        ctx.params.printUsedParams(ctx.logger);
       });
     }
   }
-  /** Whether --showUsedParams was requested (resolved in constructor). */
+  /**
+   * Resolve the --showUsedParams mode. The flag is intentionally dual-typed:
+   *   (absent) / --no-showUsedParams / =false   -> false  (off)
+   *   --showUsedParams / =true                   -> "end"  (print at exit)
+   *   --showUsedParams=top                       -> "top"  (print after init)
+   * Read raw (uncoerced) from args so the string "top" isn't forced to a
+   * boolean, then track it under the "script" module for the dump itself.
+   */
+  _resolveShowUsedParams() {
+    const raw = this.args.get("showUsedParams");
+    const source = this.args.getSource?.("showUsedParams") ?? "default";
+    let mode = false;
+    if (raw === void 0 || raw === null) {
+      mode = false;
+    } else if (typeof raw === "string" && raw.trim().toLowerCase() === "top") {
+      mode = "top";
+    } else {
+      const s = typeof raw === "string" ? raw.trim().toLowerCase() : raw;
+      const falsey = s === false || s === "false" || s === "0" || s === "no" || s === "off";
+      mode = falsey ? false : "end";
+    }
+    this._showUsedParamsMode = mode;
+    this.trackParam("showUsedParams", "string", mode, raw === void 0 ? "default" : source, "script");
+    return mode;
+  }
+  /** Whether --showUsedParams was requested in any mode (truthy = on). */
   getShowUsedParams() {
-    return this._showUsedParams;
+    return this._showUsedParamsMode !== false;
+  }
+  /** Resolved mode: false | "end" | "top". */
+  getShowUsedParamsMode() {
+    return this._showUsedParamsMode;
+  }
+  /**
+   * Print the module-grouped list of figured params (the --showUsedParams
+   * dump). Idempotent: only the first call prints, so callers can invoke it
+   * at the top (long-running services) without double-printing at exit.
+   */
+  printUsedParams(logger) {
+    if (this._usedParamsPrinted) return;
+    const byModule = this.getFiguredByModule();
+    const modules = Object.keys(byModule).sort();
+    if (modules.length === 0) return;
+    this._usedParamsPrinted = true;
+    logger = logger ?? this.context?.logger ?? console;
+    const hasHighlight = typeof logger.highlight === "function";
+    logger.debug("[Params]: list of used params:");
+    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 = hasHighlight && entry.source !== "default" ? logger.highlight(valueStr) : valueStr;
+        logger.debug(`    ${key}: ${display} (${entry.source})`);
+      }
+    }
   }
   /**
    * Configure parameters
@@ -4385,7 +4422,16 @@ function setup(opts = {}) {
     emitter: partialContext.emitter,
     isStop: partialContext.isStop,
     cleanupFunctions: partialContext.cleanupFunctions,
-    registerCleanup: partialContext.registerCleanup
+    registerCleanup: partialContext.registerCleanup,
+    // For long-running scripts (servers): with --showUsedParams=top, print
+    // the used-params list now (after the script has initialized all its
+    // own components), instead of at exit. No-op for the default mode,
+    // which prints at exit via the cleanup registered by Params.
+    showUsedParamsIfNeeded: () => {
+      if (params.getShowUsedParamsMode?.() === "top") {
+        params.printUsedParams(logger);
+      }
+    }
   };
   logger.debug("[setup] completed successfully");
   return context;