@nmakarov/cli-toolkit 0.7.2 → 0.9.0

package/dist/index.cjs

@@ -1113,7 +1113,6 @@ __export(src_exports, {
   defaultFileSynopsisFunction: () => defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction: () => defaultVersionSynopsisFunction,
   getArgsInstance: () => getArgsInstance,
-  getParamsInstance: () => getParamsInstance,
   h: () => import_react5.createElement,
   joiEdateType: () => joiEdateType,
   joiStringArrayType: () => joiStringArrayType,
@@ -1139,7 +1138,7 @@ module.exports = __toCommonJS(src_exports);
 var import_fs = require("fs");
 var import_path = require("path");
 var import_dotenv = require("dotenv");
-var Args = class {
+var Args = class _Args {
   args = {};
   flags = {};
   options = {};
@@ -1154,10 +1153,13 @@ var Args = class {
   configsLoaded = [];
   env = "local";
   constructor(config2 = {}) {
-    this.aliases = config2.aliases || {};
-    this.overrides = config2.overrides || {};
-    this.defaults = config2.defaults || {};
-    this.prefixes = config2.prefixes || ["not", "no"];
+    this.aliases = {};
+    this.overrides = {};
+    this.defaults = {};
+    this.prefixes = ["not", "no"];
+    if (Object.keys(config2).length > 0) {
+      this.configure(config2);
+    }
     const args = config2.args || process.argv.slice(2);
     this.parseArgs(args);
     this.env = this.get("env")?.toLowerCase() || "local";
@@ -1165,6 +1167,33 @@ var Args = class {
     this.loadConfigFiles();
     this.checkConflicts();
   }
+  /**
+   * Configure Args options
+   * Only parameters present in config are updated
+   * Note: Args is special - it's initialized first, so it can't take context
+   */
+  configure(config2) {
+    if (config2.aliases !== void 0) {
+      this.aliases = config2.aliases;
+    }
+    if (config2.overrides !== void 0) {
+      this.overrides = config2.overrides;
+    }
+    if (config2.defaults !== void 0) {
+      this.defaults = config2.defaults;
+    }
+    if (config2.prefixes !== void 0) {
+      this.prefixes = config2.prefixes;
+    }
+  }
+  /**
+   * 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
+   */
+  static init(config2 = {}) {
+    return new _Args(config2);
+  }
   /**
    * Parse command line arguments
    */
@@ -1303,11 +1332,11 @@ var Args = class {
    */
   get(key) {
     const resolvedKey = this.aliases[key] || key;
-    this.usedKeys.add(resolvedKey);
+    const lcKey = resolvedKey.toLowerCase();
+    this.usedKeys.add(lcKey);
     if (this.overrides[resolvedKey] !== void 0) {
       return this.overrides[resolvedKey];
     }
-    const lcKey = resolvedKey.toLowerCase();
     const lcKeyWithEnv = `${lcKey}${this.env ? `_${this.env.toLowerCase()}` : ""}`;
     if (this.env && this.args[lcKeyWithEnv] !== void 0) {
       return this.args[lcKeyWithEnv];
@@ -1678,18 +1707,76 @@ var joiStringArrayType = (type) => (value, helpers) => {
 };
 
 // src/params/index.ts
-var Params = class {
+var Params = class _Params {
+  context;
+  // Partial context during initialization
   params = {};
   definitions = {};
   args;
   paramSetters = [];
   paramGetters = [];
-  constructor({ args }, opts = {}) {
-    this.args = args;
-    for (const [k, v] of Object.entries(opts)) {
+  trackedParams = [];
+  constructor(context, options = {}) {
+    this.context = context;
+    this.args = context.args;
+    if (Object.keys(options).length > 0) {
+      this.configure(options);
+    }
+  }
+  /**
+   * Configure parameters
+   * Only parameters present in options are updated
+   */
+  configure(options) {
+    for (const [k, v] of Object.entries(options)) {
       this.params[k] = v;
     }
   }
+  /**
+   * Initialize Params from context and CLI parameters
+   * Note: Params is special - it's initialized early with partial context
+   */
+  static init(context, options) {
+    return new _Params(context, options || {});
+  }
+  /**
+   * Track a parameter request for --stopAfter=init feature
+   */
+  trackParam(key, definition, value, source) {
+    this.trackedParams.push({
+      key,
+      definition,
+      value,
+      source
+    });
+  }
+  /**
+   * Get all tracked parameters (for --stopAfter=init)
+   */
+  getTrackedParams() {
+    return [...this.trackedParams];
+  }
+  /**
+   * Get all figured parameters as a record
+   * Returns all parameters that were collected during initialization,
+   * whether from CLI args, options, or defaults
+   */
+  getAllFigured() {
+    const result = {};
+    for (const param of this.trackedParams) {
+      result[param.key] = {
+        value: param.value,
+        source: param.source
+      };
+    }
+    return result;
+  }
+  /**
+   * Clear tracked parameters
+   */
+  clearTrackedParams() {
+    this.trackedParams = [];
+  }
   /**
    * Assign a parameter definition
    */
@@ -1763,6 +1850,8 @@ var Params = class {
       type = type.default(defValObj.value);
     } else if (str.match(/required/)) {
       type = type.required();
+    } else {
+      type = type.optional();
     }
     return type;
   }
@@ -1770,7 +1859,12 @@ var Params = class {
    * Validate a value against a definition
    */
   validate(key, val, def) {
-    const { value, error } = def.type.validate(val, { context: { params: this.params } });
+    const normalizedVal = val === null ? void 0 : val;
+    const { value, error } = def.type.validate(normalizedVal, {
+      context: { params: this.params },
+      abortEarly: false,
+      allowUnknown: false
+    });
     if (error) {
       const errs = error.details.map((el) => el.message).join(", ");
       throw new ParamError(`"${key}" validation error: ${errs}`);
@@ -1788,11 +1882,26 @@ var Params = class {
     }
     const valFromArgs = this.args.get(key);
     const valFromParams = this.params[key];
-    const res = valFromGetters ? this.validate(key, valFromGetters, def) : valFromArgs ? this.validate(key, valFromArgs, def) : this.validate(key, valFromParams, def);
-    if (res !== void 0 && def.values && !def.values.includes(res)) {
+    let source = "default";
+    let value;
+    if (valFromGetters !== void 0 && valFromGetters !== null) {
+      value = this.validate(key, valFromGetters, def);
+      source = "options";
+    } else if (valFromArgs !== void 0 && valFromArgs !== null) {
+      value = this.validate(key, valFromArgs, def);
+      source = "cli";
+    } else if (valFromParams !== void 0 && valFromParams !== null) {
+      value = this.validate(key, valFromParams, def);
+      source = "options";
+    } else {
+      value = this.validate(key, void 0, def);
+      source = "default";
+    }
+    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}`);
     }
-    return res;
+    return value;
   }
   /**
    * Set a parameter value with validation
@@ -1826,10 +1935,10 @@ var Params = class {
    * Run all registered getters for a key
    */
   runAllRegisteredGetters(key) {
-    let val = null;
+    let val = void 0;
     for (const getter of this.paramGetters) {
       val = getter(key, this.definitions[key]);
-      if (val !== void 0) {
+      if (val !== void 0 && val !== null) {
         break;
       }
     }
@@ -1861,8 +1970,6 @@ var Params = class {
     this.paramSetters.push(fn);
   }
 };
-var paramsInstance = null;
-var getParamsInstance = () => paramsInstance;
 
 // src/screen.ts
 init_screen();
@@ -3088,6 +3195,7 @@ var ALL_LEVELS = [
   "response",
   "progress"
 ];
+var MAX_LEVEL_LENGTH = Math.max(...ALL_LEVELS.map((level) => level.toUpperCase().length));
 var LEVEL_COLORS = {
   error: import_chalk.default.red.bold,
   warn: import_chalk.default.rgb(255, 165, 0),
@@ -3101,13 +3209,104 @@ var LEVEL_COLORS = {
   progress: import_chalk.default.green,
   results: import_chalk.default.magenta
 };
-var CliToolkitLogger = class {
+var Logger = class _Logger {
+  context;
+  // Partial context during initialization
   options;
   transport;
   startTimes = {};
   lastProgressTimes = {};
-  constructor(options = {}) {
-    this.options = this.normalizeOptions(options);
+  constructor(context, options = {}) {
+    this.context = context;
+    this.options = this.getDefaultOptions();
+    if (options) {
+      this.configure(options);
+    }
+    this.updateTransport();
+  }
+  /**
+   * Configure logger options
+   * Only parameters present in options are updated
+   */
+  configure(options) {
+    if (options.mode !== void 0) {
+      this.options.mode = this.isValidMode(options.mode) ? options.mode : "text";
+    }
+    if (options.route !== void 0) {
+      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.levels !== void 0) {
+      this.options.levels = this.normalizeLevels(options.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;
+      }
+    }
+  }
+  /**
+   * Initialize logger from context and CLI parameters
+   */
+  static init(context, options) {
+    const paramDefs = {
+      mode: "string default text",
+      route: "string default console",
+      prefix: "string",
+      silent: "boolean default false",
+      showLevel: "boolean default true",
+      timestamp: "boolean default false",
+      levels: "string",
+      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 logger = new _Logger(context, config2);
+    context.logger = logger;
+    return logger;
+  }
+  getDefaultOptions() {
+    return {
+      mode: "text",
+      route: this.shouldUseIpcRoute() ? "ipc" : "console",
+      prefix: void 0,
+      silent: false,
+      showLevel: true,
+      timestamp: false,
+      levels: ALL_LEVELS,
+      progressTimes: false,
+      progressThrottle: void 0
+    };
+  }
+  updateTransport() {
     this.transport = this.options.route === "ipc" ? new ParentProcessTransport() : new ConsoleTransport();
   }
   setMode(mode) {
@@ -3216,7 +3415,7 @@ var CliToolkitLogger = class {
       parts.push(now.toISOString());
     }
     if (this.options.showLevel) {
-      parts.push(struct.level.toUpperCase());
+      parts.push(struct.level.toUpperCase().padEnd(MAX_LEVEL_LENGTH));
     }
     if (struct.level === "progress") {
       if (struct.prefix) {
@@ -3250,22 +3449,6 @@ var CliToolkitLogger = class {
   inspectChunks(chunks) {
     return chunks.map((chunk) => import_util.default.inspect(chunk, { colors: true, depth: null })).join(" ");
   }
-  normalizeOptions(options) {
-    const { route, mode, prefix, silent, showLevel, timestamp, levels, progress } = options;
-    const shouldUseIpc = this.shouldUseIpcRoute();
-    const normalized = {
-      mode: this.isValidMode(mode) ? mode : "text",
-      route: route ?? (shouldUseIpc ? "ipc" : "console"),
-      prefix,
-      silent: silent ?? false,
-      showLevel: showLevel ?? true,
-      timestamp: timestamp ?? false,
-      levels: this.normalizeLevels(levels),
-      progressTimes: progress?.withTimes ?? false,
-      progressThrottle: progress?.throttleMs
-    };
-    return normalized;
-  }
   shouldUseIpcRoute() {
     if (process.env.VITEST || process.env.NODE_ENV === "test") {
       return false;
@@ -3296,35 +3479,44 @@ var CliToolkitLogger = class {
 
 // src/init/index.ts
 var import_events = require("events");
+function extractComponentOptions(opts, componentName) {
+  const reservedKeys = ["overrides", "defaults", "modules"];
+  const componentOptions = {};
+  for (const [key, value] of Object.entries(opts)) {
+    if (!reservedKeys.includes(key)) {
+      componentOptions[key] = value;
+    }
+  }
+  return componentOptions;
+}
 function setup(opts = {}) {
-  const args = new Args({
+  const args = Args.init({
     overrides: opts.overrides || {},
     defaults: opts.defaults || {}
   });
-  const params = new Params({ args }, opts.overrides || {});
-  const loggerOptions = opts.logger || {};
-  const logger = new CliToolkitLogger({
-    mode: loggerOptions.mode || "text",
-    route: loggerOptions.route || "console",
-    prefix: loggerOptions.prefix,
-    silent: loggerOptions.silent,
-    showLevel: loggerOptions.showLevel,
-    timestamp: loggerOptions.timestamp,
-    levels: loggerOptions.levels
-  });
-  const cleanupFunctions = [];
-  const context = {
+  const partialContext = {
     args,
-    params,
-    logger,
     emitter: new import_events.EventEmitter(),
     isStop: () => false,
-    // Will be set in init function
-    cleanupFunctions,
+    cleanupFunctions: [],
     registerCleanup: (fn) => {
-      cleanupFunctions.push(fn);
+      partialContext.cleanupFunctions.push(fn);
     }
   };
+  const params = Params.init(partialContext, opts.overrides || {});
+  partialContext.params = params;
+  const loggerOptions = extractComponentOptions(opts, "logger");
+  const logger = Logger.init(partialContext, loggerOptions);
+  partialContext.logger = logger;
+  const context = {
+    args,
+    params,
+    logger,
+    emitter: partialContext.emitter,
+    isStop: partialContext.isStop,
+    cleanupFunctions: partialContext.cleanupFunctions,
+    registerCleanup: partialContext.registerCleanup
+  };
   logger.debug("[setup] completed successfully");
   return context;
 }
@@ -3362,7 +3554,6 @@ function setupContext(opts = {}) {
   defaultFileSynopsisFunction,
   defaultVersionSynopsisFunction,
   getArgsInstance,
-  getParamsInstance,
   h,
   joiEdateType,
   joiStringArrayType,