@nmakarov/cli-toolkit 0.4.0 → 0.5.0

package/dist/init.cjs

@@ -0,0 +1,1110 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/init.ts
+var init_exports = {};
+__export(init_exports, {
+  init: () => init,
+  setupContext: () => setupContext
+});
+module.exports = __toCommonJS(init_exports);
+
+// src/args/index.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_dotenv = require("dotenv");
+var Args = class {
+  args = {};
+  flags = {};
+  options = {};
+  commands = [];
+  usedKeys = /* @__PURE__ */ new Set();
+  aliases = {};
+  overrides = {};
+  defaults = {};
+  prefixes = [];
+  nots = [];
+  configValues = {};
+  configsLoaded = [];
+  env = "local";
+  constructor(config2 = {}) {
+    this.aliases = config2.aliases || {};
+    this.overrides = config2.overrides || {};
+    this.defaults = config2.defaults || {};
+    this.prefixes = config2.prefixes || ["not", "no"];
+    const args = config2.args || process.argv.slice(2);
+    this.parseArgs(args);
+    this.env = this.get("env")?.toLowerCase() || "local";
+    this.loadDotEnv();
+    this.loadConfigFiles();
+    this.checkConflicts();
+  }
+  /**
+   * Parse command line arguments
+   */
+  parseArgs(args) {
+    let i = 0;
+    while (i < args.length) {
+      const arg = args[i];
+      if (arg.startsWith("--")) {
+        const [key, value] = this.parseLongOption(arg);
+        this.setValue(key, value);
+        i++;
+      } else if (arg.startsWith("-")) {
+        const result = this.parseShortOption(arg, args, i);
+        if (result.consumed > 0) {
+          i += result.consumed;
+        } else {
+          i++;
+        }
+      } else {
+        this.commands.push(arg);
+        i++;
+      }
+    }
+  }
+  /**
+   * Parse long option (--key=value or --key)
+   */
+  parseLongOption(arg) {
+    const key = arg.slice(2);
+    const prefix = this.prefixes.find((p) => key.startsWith(p));
+    if (prefix) {
+      let strippedKey = key.slice(prefix.length);
+      if (strippedKey.startsWith("-")) {
+        strippedKey = strippedKey.slice(1);
+      }
+      this.nots.push(key);
+      return [strippedKey, false];
+    }
+    if (key.includes("=")) {
+      const eqIndex = key.indexOf("=");
+      const optionKey = key.slice(0, eqIndex);
+      const value = key.slice(eqIndex + 1);
+      return [optionKey, this.parseValue(value)];
+    } else {
+      return [key, true];
+    }
+  }
+  /**
+   * Parse short option (-k=value, -k, or bundled -vsd)
+   */
+  parseShortOption(arg, args, index) {
+    const key = arg.slice(1);
+    if (key.length === 1 && index + 1 < args.length && !args[index + 1].startsWith("-")) {
+      const value = args[index + 1];
+      this.setValue(key, this.parseValue(value));
+      return { consumed: 2 };
+    }
+    if (key.length > 1 && !key.includes("=")) {
+      for (let i = 0; i < key.length; i++) {
+        const shortKey = key[i];
+        if (shortKey in this.aliases) {
+          this.setValue(shortKey, true);
+        } else {
+          this.args[shortKey] = true;
+        }
+      }
+      return { consumed: 1 };
+    }
+    if (key.includes("=")) {
+      const eqIndex = key.indexOf("=");
+      const optionKey = key.slice(0, eqIndex);
+      const value = key.slice(eqIndex + 1);
+      if (optionKey.length > 1) {
+        for (let i = 0; i < optionKey.length - 1; i++) {
+          const shortKey = optionKey[i];
+          if (shortKey in this.aliases) {
+            this.setValue(shortKey, true);
+          } else {
+            this.args[shortKey] = true;
+          }
+        }
+        const lastKey = optionKey[optionKey.length - 1];
+        if (lastKey in this.aliases) {
+          this.setValue(lastKey, this.parseValue(value));
+        } else {
+          this.args[lastKey] = this.parseValue(value);
+        }
+      } else {
+        this.setValue(optionKey, this.parseValue(value));
+      }
+      return { consumed: 1 };
+    } else {
+      this.setValue(key, true);
+      return { consumed: 1 };
+    }
+  }
+  /**
+   * Parse value (handle quotes)
+   */
+  parseValue(value) {
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      return value.slice(1, -1);
+    }
+    return value;
+  }
+  /**
+   * Set a value with proper categorization
+   */
+  setValue(key, value) {
+    const resolvedKey = this.aliases[key] || key;
+    if (typeof value === "boolean") {
+      this.flags[resolvedKey] = value;
+    } else {
+      this.options[resolvedKey] = value;
+    }
+    this.args[resolvedKey.toLowerCase()] = value;
+  }
+  /**
+   * Check for conflicts (short + long form of same option)
+   */
+  checkConflicts() {
+    const conflicts = [];
+    for (const [shortKey, longKey] of Object.entries(this.aliases)) {
+      const hasShort = this.args[shortKey] !== void 0;
+      const hasLong = this.args[longKey] !== void 0;
+      if (hasShort && hasLong) {
+        conflicts.push(`Both -${shortKey} and --${longKey} specified`);
+      }
+    }
+    if (conflicts.length > 0) {
+      throw new Error(`Argument conflicts: ${conflicts.join(", ")}`);
+    }
+  }
+  /**
+   * Get a value with precedence order
+   */
+  get(key) {
+    const resolvedKey = this.aliases[key] || key;
+    this.usedKeys.add(resolvedKey);
+    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];
+    } else if (this.args[lcKey] !== void 0) {
+      return this.args[lcKey];
+    }
+    if (this.configValues[resolvedKey] !== void 0) {
+      return this.configValues[resolvedKey];
+    }
+    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);
+    if (envSpecificKey) {
+      return process.env[envSpecificKey];
+    } else if (envKeyFound) {
+      return process.env[envKeyFound];
+    }
+    if (this.defaults[resolvedKey] !== void 0) {
+      return this.defaults[resolvedKey];
+    }
+    if (resolvedKey === "env" && process.env.NODE_ENV !== void 0) {
+      return process.env.NODE_ENV;
+    }
+    return void 0;
+  }
+  /**
+   * Set a value (for testing/internal use)
+   */
+  set(key, value) {
+    this.args[key] = value;
+  }
+  /**
+   * Check if a command exists (case-insensitive)
+   */
+  hasCommand(cmd) {
+    return this.commands.some((command) => command.toLowerCase() === cmd.toLowerCase());
+  }
+  /**
+   * Get all commands
+   */
+  getCommands() {
+    return [...this.commands];
+  }
+  /**
+   * Get used keys (as array)
+   */
+  getUsed() {
+    return Array.from(this.usedKeys);
+  }
+  /**
+   * Get unused keys (as array)
+   */
+  getUnused() {
+    const unused = [];
+    for (const key of Object.keys(this.args)) {
+      if (!this.usedKeys.has(key) && !this.nots.includes(key)) {
+        unused.push(key);
+      }
+    }
+    return unused;
+  }
+  /**
+   * Convert key to environment variable format
+   */
+  toEnvKey(key) {
+    return key.replace(
+      /[A-Z0-9]/g,
+      (match, offset) => offset === 0 ? match : "_" + match.toLowerCase()
+    ).toUpperCase();
+  }
+  /**
+   * Load .env file
+   */
+  loadDotEnv() {
+    const dotEnvPath = this.get("dotEnvPath") || process.cwd();
+    const dotEnvFile = this.get("dotEnvFile") || ".env";
+    if (this.get("dotEnvFile")) {
+      const customPath = (0, import_path.resolve)(dotEnvPath, dotEnvFile);
+      if ((0, import_fs.existsSync)(customPath)) {
+        (0, import_dotenv.config)({ path: customPath, quiet: true });
+      }
+      return;
+    }
+    let dotEnvPathFile = null;
+    const envSpecificFile = `.env.${this.env}`;
+    const envSpecificPath = (0, import_path.resolve)(dotEnvPath, envSpecificFile);
+    if ((0, import_fs.existsSync)(envSpecificPath)) {
+      dotEnvPathFile = envSpecificPath;
+    }
+    if (!dotEnvPathFile && !this.get("dotEnvPath")) {
+      const examplesPath = (0, import_path.resolve)(dotEnvPath, "examples");
+      const examplesEnvSpecificPath = (0, import_path.resolve)(examplesPath, envSpecificFile);
+      if ((0, import_fs.existsSync)(examplesEnvSpecificPath)) {
+        dotEnvPathFile = examplesEnvSpecificPath;
+      }
+    }
+    if (!dotEnvPathFile) {
+      dotEnvPathFile = (0, import_path.resolve)(dotEnvPath, dotEnvFile);
+      if (!(0, import_fs.existsSync)(dotEnvPathFile)) {
+        if (!this.get("dotEnvPath")) {
+          const examplesPath = (0, import_path.resolve)(dotEnvPath, "examples");
+          const examplesEnvFile = (0, import_path.resolve)(examplesPath, dotEnvFile);
+          if ((0, import_fs.existsSync)(examplesEnvFile)) {
+            dotEnvPathFile = examplesEnvFile;
+          } else {
+            dotEnvPathFile = (0, import_path.resolve)(dotEnvPath, "..", dotEnvFile);
+          }
+        }
+      }
+    }
+    if (dotEnvPathFile && (0, import_fs.existsSync)(dotEnvPathFile)) {
+      (0, import_dotenv.config)({ path: dotEnvPathFile, quiet: true });
+    }
+  }
+  /**
+   * Load configuration files
+   */
+  loadConfigFiles() {
+    this.configsLoaded = [];
+    this.configValues = {};
+    const _defaultConfigExtension = this.get("defaultConfigExtension") || "js";
+    const optConfigFiles = this.get("config") || this.get("configs") || "";
+    const configFiles = optConfigFiles ? optConfigFiles.split(/,\s*/) : [];
+    const optConfigFilePath = this.get("configPath");
+    if (configFiles.length > 0) {
+      for (const cfgFile of configFiles) {
+        let notLoaded = false;
+        let notLoadedEnvSpecific = false;
+        const cfgFileWithPath = this.resolveFileWithPath(optConfigFilePath, cfgFile);
+        try {
+          const cfgContents = this.requireConfigFile(cfgFileWithPath);
+          this.configValues = { ...this.configValues, ...cfgContents };
+          this.configsLoaded.push(cfgFileWithPath);
+        } catch {
+          notLoaded = true;
+        }
+        const cfgEnvFileWithPath = this.resolveFileWithPath(
+          optConfigFilePath,
+          cfgFile,
+          this.env
+        );
+        if (cfgEnvFileWithPath !== cfgFileWithPath) {
+          try {
+            const cfgContents = this.requireConfigFile(cfgEnvFileWithPath);
+            this.configValues = { ...this.configValues, ...cfgContents };
+            this.configsLoaded.push(cfgEnvFileWithPath);
+          } catch {
+            notLoadedEnvSpecific = true;
+          }
+        } else {
+          notLoadedEnvSpecific = true;
+        }
+        if (notLoaded && notLoadedEnvSpecific) {
+          throw new Error(`can't load config file "${cfgFileWithPath}"`);
+        }
+      }
+    }
+  }
+  /**
+   * Resolve file path with environment-specific naming
+   */
+  resolveFileWithPath(optConfigFilePath, cfgFile, env) {
+    let cfgFileWithPath = optConfigFilePath ? (0, import_path.isAbsolute)(optConfigFilePath) ? (0, import_path.resolve)(optConfigFilePath, cfgFile) : (0, import_path.resolve)(process.cwd(), optConfigFilePath, cfgFile) : (0, import_path.isAbsolute)(cfgFile) ? cfgFile : (0, import_path.resolve)(process.cwd(), cfgFile);
+    const { basePathWithName, extension } = this.splitPath(cfgFileWithPath);
+    if (env) {
+      cfgFileWithPath = `${basePathWithName}.${env}.${extension || "js"}`;
+    } else {
+      cfgFileWithPath = `${basePathWithName}.${extension || "js"}`;
+    }
+    return cfgFileWithPath;
+  }
+  /**
+   * Split file path into base path and extension
+   */
+  splitPath(filePath) {
+    const basePathWithName = (0, import_path.join)((0, import_path.dirname)(filePath), (0, import_path.basename)(filePath, (0, import_path.extname)(filePath)));
+    const extension = (0, import_path.extname)(filePath).slice(1);
+    return { basePathWithName, extension };
+  }
+  /**
+   * Require a configuration file (supports .js and .json)
+   */
+  requireConfigFile(filePath) {
+    if (!(0, import_fs.existsSync)(filePath)) {
+      throw new Error(`Config file not found: ${filePath}`);
+    }
+    const ext = (0, import_path.extname)(filePath).toLowerCase();
+    if (ext === ".json") {
+      const content = (0, import_fs.readFileSync)(filePath, "utf8");
+      return JSON.parse(content);
+    } else if (ext === ".js") {
+      try {
+        delete require.cache[require.resolve(filePath)];
+        return require(filePath);
+      } catch (error) {
+        throw new Error(`Failed to load JS config file: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    } else {
+      throw new Error(`Unsupported file extension: ${ext}`);
+    }
+  }
+  /**
+   * Get all parsed data
+   */
+  getParsed() {
+    return {
+      command: this.commands[0] || "",
+      flags: { ...this.flags },
+      options: { ...this.options },
+      usedKeys: Array.from(this.usedKeys)
+    };
+  }
+  /**
+   * Set prefixes dynamically and re-parse arguments (like legacy)
+   */
+  setPrefixes(prefixes) {
+    const arr = Array.isArray(prefixes) ? prefixes : prefixes.split(/,\s*/);
+    const sortedArr = arr.sort(
+      (a, b) => a.length < b.length ? 1 : a.length > b.length ? -1 : 0
+    );
+    this.prefixes = sortedArr.map((el) => el.toLowerCase());
+    const args = process.argv.slice(2);
+    this.parseArgs(args);
+  }
+};
+
+// src/params/index.ts
+var import_joi = __toESM(require("joi"), 1);
+
+// src/errors.ts
+var FrameworkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FrameworkError";
+  }
+};
+var ParamError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "ParamError";
+  }
+};
+var InitError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+};
+
+// src/params/custom-types.ts
+var joiEdateType = (value, helpers) => {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(value)) {
+    const testDate = new Date(value);
+    if (!isNaN(testDate.getTime())) {
+      return value;
+    }
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value !== "string") {
+    value = String(value);
+  }
+  if (value.toLowerCase() === "now") {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const referenceRegex = /^@(\w+)([+-]\d+[smhdwy])$/i;
+  const referenceMatch = value.match(referenceRegex);
+  if (referenceMatch) {
+    const [, paramName, relativeExpr] = referenceMatch;
+    const context = helpers.prefs?.context;
+    if (!context || !context.params) {
+      throw new ParamError(`Cannot resolve cross-parameter reference @${paramName}: context not available. Ensure parameters are processed with proper context.`);
+    }
+    const referencedValue = context.params[paramName];
+    if (referencedValue === void 0 || referencedValue === null) {
+      throw new ParamError(`Cannot resolve @${paramName}: parameter "${paramName}" is not defined or has no value. Parameters are evaluated left-to-right.`);
+    }
+    let referenceDate;
+    if (referencedValue instanceof Date) {
+      referenceDate = referencedValue;
+    } else if (typeof referencedValue === "string") {
+      referenceDate = new Date(referencedValue);
+      if (isNaN(referenceDate.getTime())) {
+        throw new ParamError(`Referenced parameter @${paramName} has invalid date value: ${referencedValue}`);
+      }
+    } else {
+      throw new ParamError(`Referenced parameter @${paramName} is not a valid date type (found: ${typeof referencedValue})`);
+    }
+    const relativeMatch2 = relativeExpr.match(/^([+-])(\d+)([smhdwy])$/i);
+    if (!relativeMatch2) {
+      throw new ParamError(`Invalid relative time expression in @${paramName}${relativeExpr}`);
+    }
+    const [, sign, amount, unit] = relativeMatch2;
+    const offset = calculateTimeOffset(parseInt(amount, 10), unit, sign);
+    const resultDate = new Date(referenceDate.getTime() + offset);
+    return resultDate.toISOString();
+  }
+  const relativeTimeRegex = /^([+-])(\d+)([smhdwy])$/i;
+  const relativeMatch = value.match(relativeTimeRegex);
+  if (relativeMatch) {
+    const [, sign, amount, unit] = relativeMatch;
+    const numAmount = parseInt(amount, 10);
+    if (isNaN(numAmount)) {
+      throw new ParamError(`Invalid relative time amount: ${amount}`);
+    }
+    const offset = calculateTimeOffset(numAmount, unit, sign);
+    const resultDate = new Date(Date.now() + offset);
+    return resultDate.toISOString();
+  }
+  const parsedDate = new Date(value);
+  if (isNaN(parsedDate.getTime())) {
+    throw new ParamError(`Invalid date format: ${value}. Expected a valid date string, "now", relative time expression (e.g., "-2h", "+1d"), or cross-parameter reference (e.g., "@startTime+2h")`);
+  }
+  return parsedDate.toISOString();
+};
+function calculateTimeOffset(amount, unit, sign) {
+  let multiplier = 1;
+  switch (unit.toLowerCase()) {
+    case "s":
+      multiplier = 1e3;
+      break;
+    case "m":
+      multiplier = 60 * 1e3;
+      break;
+    case "h":
+      multiplier = 60 * 60 * 1e3;
+      break;
+    case "d":
+      multiplier = 24 * 60 * 60 * 1e3;
+      break;
+    case "w":
+      multiplier = 7 * 24 * 60 * 60 * 1e3;
+      break;
+    case "y":
+      multiplier = 365 * 24 * 60 * 60 * 1e3;
+      break;
+    default:
+      throw new ParamError(`Invalid time unit: ${unit}. Supported units: s, m, h, d, w, y`);
+  }
+  return sign === "+" ? amount * multiplier : -amount * multiplier;
+}
+var joiStringArrayType = (type) => (value, helpers) => {
+  if (value === void 0 || typeof value === "function") {
+    return [];
+  }
+  const arr = value.split(/,\s*/).map((el) => {
+    if (type === "number") {
+      const v = parseInt(el, 10);
+      if (isNaN(v)) {
+        throw new ParamError(`array element "${el}" should be numeric`);
+      }
+      return v;
+    } else if (type === "boolean") {
+      const v = el.match(/true|t|yes|1/i) ? true : el.match(/false|f|no|0/i) ? false : null;
+      if (v === null) {
+        throw new ParamError(`array element "${el}" should be boolean`);
+      }
+      return v;
+    } else if (type === "string") {
+      return el;
+    } else {
+      throw new ParamError(`unknown type "${type}" for array elements`);
+    }
+  });
+  return arr;
+};
+
+// src/params/index.ts
+var Params = class {
+  params = {};
+  definitions = {};
+  args;
+  paramSetters = [];
+  paramGetters = [];
+  constructor({ args }, opts = {}) {
+    this.args = args;
+    for (const [k, v] of Object.entries(opts)) {
+      this.params[k] = v;
+    }
+  }
+  /**
+   * Assign a parameter definition
+   */
+  assignDefinition(key, definition) {
+    if (this.definitions[key] && !definition) {
+      return this.definitions[key];
+    }
+    let type;
+    if (!definition) {
+      type = import_joi.default.string();
+    } else if (import_joi.default.isSchema(definition)) {
+      type = definition;
+    } else if (import_joi.default.isSchema(definition.type)) {
+      type = definition.type;
+    } else if (typeof definition === "string") {
+      type = this.toJoi(definition);
+    } else if (typeof definition.type === "string") {
+      type = this.toJoi(definition.type);
+    } else if (!definition.type) {
+      type = import_joi.default.string();
+    } else {
+      type = import_joi.default.string();
+    }
+    if (!this.definitions[key]) {
+      this.definitions[key] = {};
+    }
+    this.definitions[key].type = type;
+    if (definition && definition.values) {
+      if (Array.isArray(definition.values)) {
+        this.definitions[key].values = definition.values;
+      }
+    }
+    return this.definitions[key];
+  }
+  /**
+   * Convert string definition to Joi schema
+   */
+  toJoi(str) {
+    let type;
+    if (str.match(/^string|^text/i)) {
+      type = import_joi.default.string();
+    } else if (str.match(/^number|^integer|^int/i)) {
+      type = import_joi.default.number();
+    } else if (str.match(/^boolean|^bool/i)) {
+      type = import_joi.default.boolean();
+    } else if (str.match(/^date/i)) {
+      type = import_joi.default.custom(joiEdateType);
+    } else if (str.match(/^duration/i)) {
+      type = import_joi.default.string().isoDuration();
+    } else if (str.match(/^array/i)) {
+      let elementTypes = "string";
+      const tmp = str.match(/\((.*)\)/);
+      if (tmp && tmp[1].match(/string/i)) {
+        elementTypes = "string";
+      } else if (tmp && tmp[1].match(/number|integer|int/i)) {
+        elementTypes = "number";
+      } else if (tmp && tmp[1].match(/boolean|bool/i)) {
+        elementTypes = "boolean";
+      }
+      type = import_joi.default.custom(joiStringArrayType(elementTypes));
+    } else {
+      type = import_joi.default.string();
+    }
+    const regexForDefault = /\bdefault\s+([^\s]+)/;
+    const matchForDefault = str.match(regexForDefault);
+    if (matchForDefault) {
+      const defValObj = type.validate(matchForDefault[1]);
+      if (defValObj.error) {
+        throw new ParamError(`default value "${defValObj.value}" type mismatch`);
+      }
+      type = type.default(defValObj.value);
+    } else if (str.match(/required/)) {
+      type = type.required();
+    }
+    return type;
+  }
+  /**
+   * Validate a value against a definition
+   */
+  validate(key, val, def) {
+    const { value, error } = def.type.validate(val, { context: { params: this.params } });
+    if (error) {
+      const errs = error.details.map((el) => el.message).join(", ");
+      throw new ParamError(`"${key}" validation error: ${errs}`);
+    }
+    return value;
+  }
+  /**
+   * Get a parameter value with validation
+   */
+  get(key, definition) {
+    const def = this.assignDefinition(key, definition);
+    let valFromGetters = void 0;
+    if (def.volatile || true) {
+      valFromGetters = this.runAllRegisteredGetters(key);
+    }
+    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)) {
+      throw new ParamError(`key ${key} should be one of ${def.values}`);
+    }
+    return res;
+  }
+  /**
+   * Set a parameter value with validation
+   */
+  set(key, val, definition) {
+    if (val && val.type && val.value) {
+      definition = val;
+      val = val.value;
+    }
+    const def = this.assignDefinition(key, definition);
+    if (!this.runAllRegisteredSetters(key, val)) {
+      this.params[key] = val;
+    }
+  }
+  /**
+   * Get all parameters from definitions
+   * Processes parameters left-to-right to support 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 res;
+  }
+  /**
+   * Run all registered getters for a key
+   */
+  runAllRegisteredGetters(key) {
+    let val = null;
+    for (const getter of this.paramGetters) {
+      val = getter(key, this.definitions[key]);
+      if (val !== void 0) {
+        break;
+      }
+    }
+    return val;
+  }
+  /**
+   * Run all registered setters for a key
+   */
+  runAllRegisteredSetters(key, value) {
+    let setterUsed = false;
+    for (const setter of this.paramSetters) {
+      setterUsed = setter(key, value);
+      if (setterUsed) {
+        break;
+      }
+    }
+    return setterUsed;
+  }
+  /**
+   * Register a parameter getter
+   */
+  registerParamGetter(fn) {
+    this.paramGetters.push(fn);
+  }
+  /**
+   * Register a parameter setter
+   */
+  registerParamSetter(fn) {
+    this.paramSetters.push(fn);
+  }
+};
+
+// src/logger/index.ts
+var import_chalk = __toESM(require("chalk"), 1);
+var import_util = __toESM(require("util"), 1);
+
+// src/logger/transports.ts
+var ConsoleTransport = class {
+  write(payload) {
+    console.info(payload);
+  }
+};
+var ParentProcessTransport = class {
+  write(payload) {
+    if (process.env.VITEST || process.env.NODE_ENV === "test") {
+      console.info(payload);
+      return;
+    }
+    if (typeof process.send === "function" && process.connected === true) {
+      process.send(payload);
+    } else {
+      console.info(payload);
+    }
+  }
+};
+
+// src/logger/index.ts
+var ALL_LEVELS = [
+  "silly",
+  "debug",
+  "logic",
+  "info",
+  "notice",
+  "warn",
+  "error",
+  "results",
+  "request",
+  "response",
+  "progress"
+];
+var LEVEL_COLORS = {
+  error: import_chalk.default.red.bold,
+  warn: import_chalk.default.rgb(255, 165, 0),
+  notice: import_chalk.default.cyan,
+  info: import_chalk.default.white.bold,
+  logic: import_chalk.default.gray,
+  debug: import_chalk.default.gray,
+  silly: import_chalk.default.gray,
+  request: import_chalk.default.green,
+  response: import_chalk.default.yellow,
+  progress: import_chalk.default.green,
+  results: import_chalk.default.magenta
+};
+var CliToolkitLogger = class {
+  options;
+  transport;
+  startTimes = {};
+  lastProgressTimes = {};
+  constructor(options = {}) {
+    this.options = this.normalizeOptions(options);
+    this.transport = this.options.route === "ipc" ? new ParentProcessTransport() : new ConsoleTransport();
+  }
+  setMode(mode) {
+    if (!this.isValidMode(mode)) {
+      throw new Error(`Unsupported logger mode: ${mode}`);
+    }
+    this.options.mode = mode;
+  }
+  debug(message, ...chunks) {
+    this.out({ level: "debug", message, chunks });
+  }
+  info(message, ...chunks) {
+    this.out({ level: "info", message, chunks });
+  }
+  notice(message, ...chunks) {
+    this.out({ level: "notice", message, chunks });
+  }
+  warn(message, ...chunks) {
+    this.out({ level: "warn", message, chunks });
+  }
+  error(message, ...chunks) {
+    this.out({ level: "error", message, chunks });
+  }
+  logic(message, ...chunks) {
+    this.out({ level: "logic", message, chunks });
+  }
+  silly(message, ...chunks) {
+    this.out({ level: "silly", message, chunks });
+  }
+  results(results) {
+    this.out({ level: "results", message: "results", results });
+  }
+  request(operation, ...chunks) {
+    const message = this.inspectChunks([operation, ...chunks]);
+    this.out({ level: "request", message });
+  }
+  response(operation, ...chunks) {
+    const message = this.inspectChunks([operation, ...chunks]);
+    this.out({ level: "response", message });
+  }
+  progress(message, opts) {
+    const { prefix, count, total } = opts;
+    const paddedTotal = String(total).length;
+    const paddedCount = String(count).padStart(paddedTotal, " ");
+    const payload = {
+      level: "progress",
+      message,
+      count: paddedCount,
+      total,
+      prefix
+    };
+    if (!this.startTimes[prefix ?? ""]) {
+      this.startTimes[prefix ?? ""] = Date.now();
+    }
+    if (this.options.progressTimes) {
+      const elapsedSeconds = (Date.now() - this.startTimes[prefix ?? ""]) / 1e3;
+      let remaining = -1;
+      if (count > 1) {
+        const rate = elapsedSeconds / (count - 1);
+        remaining = (total - count) * rate;
+      }
+      payload.elapsed = this.round(elapsedSeconds, 2);
+      payload.remaining = remaining >= 0 ? this.round(remaining, 2) : remaining;
+    }
+    if (count >= total) {
+      delete this.startTimes[prefix ?? ""];
+      delete this.lastProgressTimes[prefix ?? ""];
+    }
+    if (this.shouldOutputProgress(prefix ?? "", count, total)) {
+      this.out(payload);
+      if (this.options.progressThrottle && prefix) {
+        this.lastProgressTimes[prefix] = Date.now();
+      }
+    }
+  }
+  shouldOutputProgress(prefix, count, total) {
+    if (!this.options.progressThrottle) {
+      return true;
+    }
+    if (count === 1 || count === total || !prefix) {
+      return true;
+    }
+    const lastTime = this.lastProgressTimes[prefix];
+    if (!lastTime) {
+      return true;
+    }
+    return Date.now() - lastTime >= this.options.progressThrottle;
+  }
+  out(struct) {
+    if (this.options.silent) {
+      return;
+    }
+    if (!this.options.levels.includes(struct.level)) {
+      return;
+    }
+    if (this.options.prefix && !struct.prefix) {
+      struct.prefix = this.options.prefix;
+    }
+    const output = this.options.mode === "json" ? struct : this.formatLog(struct);
+    this.transport.write(output);
+  }
+  formatLog(struct) {
+    const parts = [];
+    const now = /* @__PURE__ */ new Date();
+    if (this.options.timestamp) {
+      parts.push(now.toISOString());
+    }
+    if (this.options.showLevel) {
+      parts.push(struct.level.toUpperCase());
+    }
+    if (struct.level === "progress") {
+      if (struct.prefix) {
+        parts.push(LEVEL_COLORS[struct.level].bold(struct.prefix));
+      }
+      if (struct.count !== void 0 && struct.total !== void 0) {
+        parts.push(LEVEL_COLORS[struct.level](`${struct.count}/${struct.total}`));
+      }
+    } else if (struct.prefix) {
+      parts.push(import_chalk.default.cyan(`[${struct.prefix}]`));
+    }
+    if (struct.message) {
+      const formatter = LEVEL_COLORS[struct.level] ?? import_chalk.default.white;
+      parts.push(formatter.bold(struct.message));
+    }
+    if (struct.level === "progress") {
+      if (struct.elapsed !== void 0 && struct.remaining !== void 0) {
+        const formatter = LEVEL_COLORS[struct.level];
+        parts.push(formatter(`${struct.elapsed}/${struct.remaining}`));
+      }
+    }
+    if (struct.chunks && struct.chunks.length) {
+      parts.push(this.inspectChunks(struct.chunks));
+    }
+    if (struct.results) {
+      const formatter = LEVEL_COLORS[struct.level] ?? import_chalk.default.white;
+      parts.push(formatter(JSON.stringify(struct.results, null, 4)));
+    }
+    return parts.join(" ");
+  }
+  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;
+    }
+    return typeof process.send === "function" && process.connected === true;
+  }
+  normalizeLevels(levels) {
+    if (!levels || !levels.length) {
+      return ALL_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));
+    if (unknown.length) {
+      console.warn(`[Logger] Unknown level(s): ${unknown.join(", ")}`);
+    }
+    const base = includes.length ? includes : ALL_LEVELS;
+    return base.filter((level) => !excludes.includes(level));
+  }
+  isValidMode(mode) {
+    return mode === void 0 || mode === null || mode === "text" || mode === "json";
+  }
+  round(value, places) {
+    const factor = Math.pow(10, places);
+    return Math.round(value * factor) / factor;
+  }
+};
+
+// src/init/index.ts
+var import_events = require("events");
+function setup(opts = {}) {
+  const args = new Args({
+    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 = {
+    args,
+    params,
+    logger,
+    emitter: new import_events.EventEmitter(),
+    isStop: () => false,
+    // Will be set in init function
+    cleanupFunctions,
+    registerCleanup: (fn) => {
+      cleanupFunctions.push(fn);
+    }
+  };
+  logger.debug("[setup] completed successfully");
+  return context;
+}
+async function setupModules(context, opts = {}) {
+  if (opts.modules && opts.modules.length > 0) {
+    context.logger.debug(`[setupModules] modules specified: ${opts.modules.join(", ")} (not yet implemented)`);
+  }
+  context.logger.debug("[setupModules] completed successfully");
+  return context;
+}
+async function init(flow, opts = {}) {
+  let stop = false;
+  let context = null;
+  try {
+    context = setup(opts);
+    context.isStop = () => stop;
+    context = await setupModules(context, opts);
+    process.on("SIGINT", async () => {
+      if (stop) {
+        context.logger.warn("[process] killed");
+        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);
+    });
+    await flow(context);
+  } catch (error) {
+    const errorLocation = error instanceof Error && error.stack ? error.stack.split("\n")[1]?.trim() || "Unknown location" : "Unknown location";
+    if (error instanceof ParamError) {
+      context?.logger.error(`[params]: ${error.message} (${errorLocation})`);
+      process.exitCode = 3;
+    } else if (error instanceof InitError) {
+      context?.logger.error(`[init]: ${error.message} (${errorLocation})`);
+      process.exitCode = 4;
+    } else {
+      context?.logger.error(`[other] error:`, error, errorLocation);
+      process.exitCode = 5;
+    }
+  } finally {
+    if (context) {
+      for (const fn of context.cleanupFunctions.reverse()) {
+        try {
+          await fn(context);
+        } catch (error) {
+          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(", "));
+      }
+    }
+  }
+}
+function setupContext(opts = {}) {
+  return setup(opts);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  init,
+  setupContext
+});
+//# sourceMappingURL=init.cjs.map