@nmakarov/cli-toolkit 0.1.0

package/dist/index.js

@@ -0,0 +1,1751 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/args/index.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname, basename, extname, join, isAbsolute } from "path";
+import { config } from "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 = resolve(dotEnvPath, dotEnvFile);
+      if (existsSync(customPath)) {
+        config({ path: customPath, quiet: true });
+      }
+      return;
+    }
+    let dotEnvPathFile = null;
+    const envSpecificFile = `.env.${this.env}`;
+    const envSpecificPath = resolve(dotEnvPath, envSpecificFile);
+    if (existsSync(envSpecificPath)) {
+      dotEnvPathFile = envSpecificPath;
+    }
+    if (!dotEnvPathFile && !this.get("dotEnvPath")) {
+      const examplesPath = resolve(dotEnvPath, "examples");
+      const examplesEnvSpecificPath = resolve(examplesPath, envSpecificFile);
+      if (existsSync(examplesEnvSpecificPath)) {
+        dotEnvPathFile = examplesEnvSpecificPath;
+      }
+    }
+    if (!dotEnvPathFile) {
+      dotEnvPathFile = resolve(dotEnvPath, dotEnvFile);
+      if (!existsSync(dotEnvPathFile)) {
+        if (!this.get("dotEnvPath")) {
+          const examplesPath = resolve(dotEnvPath, "examples");
+          const examplesEnvFile = resolve(examplesPath, dotEnvFile);
+          if (existsSync(examplesEnvFile)) {
+            dotEnvPathFile = examplesEnvFile;
+          } else {
+            dotEnvPathFile = resolve(dotEnvPath, "..", dotEnvFile);
+          }
+        }
+      }
+    }
+    if (dotEnvPathFile && existsSync(dotEnvPathFile)) {
+      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 ? isAbsolute(optConfigFilePath) ? resolve(optConfigFilePath, cfgFile) : resolve(process.cwd(), optConfigFilePath, cfgFile) : isAbsolute(cfgFile) ? cfgFile : 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 = join(dirname(filePath), basename(filePath, extname(filePath)));
+    const extension = extname(filePath).slice(1);
+    return { basePathWithName, extension };
+  }
+  /**
+   * Require a configuration file (supports .js and .json)
+   */
+  requireConfigFile(filePath) {
+    if (!existsSync(filePath)) {
+      throw new Error(`Config file not found: ${filePath}`);
+    }
+    const ext = extname(filePath).toLowerCase();
+    if (ext === ".json") {
+      const content = 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: new Set(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);
+  }
+};
+var instance = null;
+function getArgsInstance() {
+  return instance;
+}
+
+// src/params/index.ts
+import Joi from "joi";
+
+// 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";
+  }
+};
+
+// 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 = Joi.string();
+    } else if (Joi.isSchema(definition)) {
+      type = definition;
+    } else if (Joi.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 = Joi.string();
+    } else {
+      type = Joi.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 = Joi.string();
+    } else if (str.match(/^number|^integer|^int/i)) {
+      type = Joi.number();
+    } else if (str.match(/^boolean|^bool/i)) {
+      type = Joi.boolean();
+    } else if (str.match(/^date/i)) {
+      type = Joi.date();
+    } else if (str.match(/^edate/i)) {
+      type = Joi.custom(joiEdateType);
+    } else if (str.match(/^duration/i)) {
+      type = Joi.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 = Joi.custom(joiStringArrayType(elementTypes));
+    } else {
+      type = Joi.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);
+  }
+};
+var paramsInstance = null;
+var getParamsInstance = () => paramsInstance;
+
+// src/screen/screens.ts
+import { useState as useState2, createElement as h3 } from "react";
+import { render, useInput, Text as Text3 } from "ink";
+
+// src/screen/components.ts
+import { createElement as h } from "react";
+import { Box, Text } from "ink";
+function getScreenWidth(maxWidth = null) {
+  const terminalWidth = process.stdout.columns || 80;
+  const availableWidth = Math.max(20, terminalWidth - 4);
+  return maxWidth ? Math.min(availableWidth, maxWidth) : availableWidth;
+}
+function ScreenContainer({ children }) {
+  const width = getScreenWidth();
+  return h(Box, {
+    flexDirection: "column",
+    marginTop: 1,
+    borderStyle: "single",
+    borderColor: "cyan",
+    paddingX: 1,
+    width
+    // Use the calculated width directly
+  }, children);
+}
+function ScreenRow({ children }) {
+  return h(Box, { flexDirection: "column" }, children);
+}
+function ScreenTitle({ text }) {
+  return h(
+    ScreenRow,
+    {},
+    h(Text, { bold: true, color: "cyan" }, text)
+  );
+}
+function ScreenDivider({ width }) {
+  const dividerWidth = width || getScreenWidth() - 4;
+  return h(Text, { color: "cyan", dimColor: true }, "\u2500".repeat(dividerWidth));
+}
+function ScreenBody({ children, alignItems = "flex-start" }) {
+  return h(Box, { flexDirection: "column", alignItems }, children);
+}
+function ScreenFooter({ lines, textStyle }) {
+  const defaultTextStyle = {
+    dimColor: true,
+    color: "white"
+  };
+  const finalTextStyle = { ...defaultTextStyle, ...textStyle };
+  const flattenAndWrap = (items, keyPrefix = "") => {
+    const result = [];
+    let keyIndex = 0;
+    items.forEach((item, index) => {
+      if (Array.isArray(item)) {
+        const nested = flattenAndWrap(item, `${keyPrefix}-${index}`);
+        result.push(...nested);
+      } else if (typeof item === "string") {
+        result.push(
+          h(Text, { key: `${keyPrefix}-${keyIndex++}`, ...finalTextStyle }, item)
+        );
+      } else {
+        const element = item;
+        if (element.key === null || element.key === void 0) {
+          result.push(
+            h(Text, { key: `${keyPrefix}-${keyIndex++}`, ...finalTextStyle }, element)
+          );
+        } else {
+          result.push(element);
+        }
+      }
+    });
+    return result;
+  };
+  const wrappedItems = flattenAndWrap(lines);
+  return h(
+    Box,
+    { flexDirection: "column" },
+    h(Box, { flexDirection: "row" }, ...wrappedItems)
+  );
+}
+
+// src/screen/list-components.ts
+import React2, { useState, useEffect, useRef, createElement } from "react";
+import { Box as Box2, Text as Text2 } from "ink";
+var h2 = createElement;
+function MultiColumnListComponent({ items, ctx, selectedIndexRef }) {
+  const [, forceUpdate] = useState({});
+  const termWidth = (process.stdout.columns || 80) - 8;
+  const maxItemLength = Math.max(...items.map((w) => w.length));
+  const columnWidth = maxItemLength + 3;
+  const columns = Math.max(1, Math.floor(termWidth / columnWidth));
+  const itemsPerColumn = Math.ceil(items.length / columns);
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      selectedIndexRef.current = Math.max(0, selectedIndexRef.current - 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveLeft", () => {
+      if (selectedIndexRef.current === 0) {
+        ctx.goBack();
+      } else {
+        selectedIndexRef.current = Math.max(0, selectedIndexRef.current - itemsPerColumn);
+        forceUpdate({});
+      }
+    });
+    ctx.setAction("moveRight", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + itemsPerColumn);
+      forceUpdate({});
+    });
+    ctx.setKeyBinding([
+      { key: "leftArrow", caption: "navigate", action: "moveLeft", order: 0 },
+      { key: "rightArrow", caption: "navigate", action: "moveRight", order: 0 },
+      { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+      { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+    ]);
+    ctx.addFooter(`Total: ${items.length} items`);
+  }, []);
+  const selectedIndex = selectedIndexRef.current;
+  const rows = [];
+  for (let row = 0; row < itemsPerColumn; row++) {
+    const cols = [];
+    for (let col = 0; col < columns; col++) {
+      const index = col * itemsPerColumn + row;
+      if (index < items.length) {
+        const isSelected = index === selectedIndex;
+        cols.push(
+          h2(
+            Box2,
+            { key: index, width: columnWidth },
+            h2(Text2, {
+              color: isSelected ? "black" : "white",
+              backgroundColor: isSelected ? "cyan" : void 0,
+              bold: isSelected
+            }, items[index].padEnd(maxItemLength))
+          )
+        );
+      }
+    }
+    rows.push(
+      h2(ScreenRow, { key: row, children: h2(Box2, { flexDirection: "row" }, ...cols) })
+    );
+  }
+  return h2(Box2, { flexDirection: "column" }, ...rows);
+}
+function MultiColumnListWithPreviewComponent({
+  items,
+  getPreviewContent,
+  ctx,
+  selectedIndexRef
+}) {
+  const [, forceUpdate] = useState({});
+  const termWidth = (process.stdout.columns || 80) - 8;
+  const maxItemLength = Math.max(...items.map((w) => w.length));
+  const columnWidth = maxItemLength + 3;
+  const columns = Math.max(1, Math.floor(termWidth / columnWidth));
+  const itemsPerColumn = Math.ceil(items.length / columns);
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      selectedIndexRef.current = Math.max(0, selectedIndexRef.current - 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveLeft", () => {
+      if (selectedIndexRef.current === 0) {
+        ctx.goBack();
+      } else {
+        selectedIndexRef.current = Math.max(0, selectedIndexRef.current - itemsPerColumn);
+        forceUpdate({});
+      }
+    });
+    ctx.setAction("moveRight", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + itemsPerColumn);
+      forceUpdate({});
+    });
+    ctx.setKeyBinding([
+      { key: "leftArrow", caption: "navigate", action: "moveLeft", order: 0 },
+      { key: "rightArrow", caption: "navigate", action: "moveRight", order: 0 },
+      { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+      { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+    ]);
+    ctx.addFooter(`Total: ${items.length} items`);
+  }, []);
+  const selectedIndex = selectedIndexRef.current;
+  const selectedItem = items[selectedIndex];
+  const rows = [];
+  for (let row = 0; row < itemsPerColumn; row++) {
+    const cols = [];
+    for (let col = 0; col < columns; col++) {
+      const index = col * itemsPerColumn + row;
+      if (index < items.length) {
+        const isSelected = index === selectedIndex;
+        cols.push(
+          h2(
+            Box2,
+            { key: index, width: columnWidth },
+            h2(Text2, {
+              color: isSelected ? "black" : "white",
+              backgroundColor: isSelected ? "cyan" : void 0,
+              bold: isSelected
+            }, items[index].padEnd(maxItemLength))
+          )
+        );
+      }
+    }
+    rows.push(
+      h2(ScreenRow, { key: row, children: h2(Box2, { flexDirection: "row" }, ...cols) })
+    );
+  }
+  const previewContent = getPreviewContent ? getPreviewContent(selectedItem) : selectedItem;
+  const previewRows = [];
+  if (typeof previewContent === "string") {
+    previewRows.push(h2(ScreenRow, { key: "preview-string", children: h2(Text2, { bold: true }, previewContent) }));
+  } else if (typeof previewContent === "object" && !React2.isValidElement(previewContent) && previewContent !== null) {
+    Object.entries(previewContent).forEach(([key, value], idx) => {
+      previewRows.push(h2(ScreenRow, { key: `preview-${key}-${idx}`, children: h2(Text2, {}, `${key}: ${value}`) }));
+    });
+  } else if (React2.isValidElement(previewContent)) {
+    previewRows.push(h2(ScreenRow, { key: "preview-element", children: previewContent }));
+  }
+  return h2(
+    Box2,
+    { flexDirection: "column" },
+    ...rows,
+    h2(ScreenRow, { key: "spacer-1", children: h2(Text2, {}, " ") }),
+    h2(ScreenDivider, { key: "divider" }),
+    h2(ScreenRow, { key: "spacer-2", children: h2(Text2, {}, " ") }),
+    ...previewRows
+  );
+}
+function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sortable = false, maxHeight, sortHighlightStyle, selectionMarker = " " }) {
+  const [, forceUpdate] = useState({});
+  const [sortOrder, setSortOrder] = useState("none");
+  const [scrollOffset, setScrollOffset] = useState(0);
+  const scrollStateRef = useRef({ scrollOffset: 0, maxHeight: 0, totalItems: 0 });
+  const defaultGetTitle = (item) => {
+    return getTitle ? getTitle(item) : typeof item.value === "string" ? item.value : item.value?.title || item.name;
+  };
+  const titleGetter = getTitle || defaultGetTitle;
+  const displayItems = sortable && sortOrder !== "none" ? [...items].sort((a, b) => {
+    const titleA = titleGetter(a).toLowerCase();
+    const titleB = titleGetter(b).toLowerCase();
+    if (sortOrder === "asc") {
+      return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+    } else {
+      return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+    }
+  }) : items;
+  const effectiveMaxHeight = maxHeight || displayItems.length;
+  const canScroll = displayItems.length > effectiveMaxHeight;
+  const maxScrollOffset = Math.max(0, displayItems.length - effectiveMaxHeight);
+  const clampedScrollOffset = Math.min(Math.max(0, scrollOffset), maxScrollOffset);
+  const visibleItems = displayItems.slice(clampedScrollOffset, clampedScrollOffset + effectiveMaxHeight);
+  const canScrollUp = clampedScrollOffset > 0;
+  const canScrollDown = clampedScrollOffset < maxScrollOffset;
+  scrollStateRef.current = { scrollOffset, maxHeight: effectiveMaxHeight, totalItems: displayItems.length };
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      const newIndex = Math.max(0, selectedIndexRef.current - 1);
+      selectedIndexRef.current = newIndex;
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
+      if (newIndex < currentClampedScrollOffset) {
+        setScrollOffset(newIndex);
+      }
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      const currentItems = sortable && sortOrder !== "none" ? [...items].sort((a, b) => {
+        const titleA = titleGetter(a).toLowerCase();
+        const titleB = titleGetter(b).toLowerCase();
+        if (sortOrder === "asc") {
+          return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+        } else {
+          return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+        }
+      }) : items;
+      const maxIndex = currentItems.length - 1;
+      const newIndex = Math.min(maxIndex, selectedIndexRef.current + 1);
+      selectedIndexRef.current = newIndex;
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
+      if (newIndex >= currentClampedScrollOffset + currentMaxHeight) {
+        setScrollOffset(newIndex - currentMaxHeight + 1);
+      }
+      forceUpdate({});
+    });
+    ctx.setAction("scrollUp", () => {
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const newScrollOffset = Math.max(0, currentScrollOffset - 1);
+      setScrollOffset(newScrollOffset);
+      forceUpdate({});
+    });
+    ctx.setAction("scrollDown", () => {
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const newScrollOffset = Math.min(currentMaxScrollOffset, currentScrollOffset + 1);
+      setScrollOffset(newScrollOffset);
+      forceUpdate({});
+    });
+    if (sortable) {
+      ctx.setAction("toggleSort", () => {
+        const nextSort = sortOrder === "none" ? "asc" : sortOrder === "asc" ? "desc" : "none";
+        const currentSelectedItem = displayItems[selectedIndexRef.current];
+        setSortOrder(nextSort);
+        const newSortedItems = nextSort !== "none" ? [...items].sort((a, b) => {
+          const titleA = titleGetter(a).toLowerCase();
+          const titleB = titleGetter(b).toLowerCase();
+          if (nextSort === "asc") {
+            return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+          } else {
+            return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+          }
+        }) : items;
+        const newIndex = newSortedItems.findIndex((item) => item === currentSelectedItem);
+        if (newIndex !== -1) {
+          selectedIndexRef.current = newIndex;
+          setScrollOffset(newIndex);
+        } else {
+          selectedIndexRef.current = 0;
+          setScrollOffset(0);
+        }
+        forceUpdate({});
+      });
+      const defaultHighlightStyle = {
+        color: "black",
+        backgroundColor: "green",
+        bold: true
+      };
+      const highlightStyle = { ...defaultHighlightStyle, ...sortHighlightStyle };
+      const sortCaption = () => {
+        if (sortOrder === "none") {
+          return h2(Text2, {}, "s to toggle sort");
+        } else {
+          const sortLabel = sortOrder === "asc" ? "ASC" : "DESC";
+          return h2(
+            Text2,
+            {},
+            "s to toggle ",
+            h2(Text2, { color: "white", bold: true }, "sort"),
+            " ",
+            h2(Text2, highlightStyle, ` ${sortLabel} `)
+          );
+        }
+      };
+      ctx.setKeyBinding([
+        { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+        { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 },
+        {
+          key: "s",
+          caption: sortCaption,
+          action: "toggleSort",
+          order: 5
+        }
+      ]);
+      ctx.update();
+    } else {
+      ctx.setKeyBinding([
+        { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+        { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+      ]);
+    }
+  }, [sortOrder, sortable]);
+  const selectedIndex = selectedIndexRef.current;
+  const defaultRenderItem = (item, isSelected, displayIndex, actualIndex) => {
+    const isFirstVisible = displayIndex === 0;
+    const isLastVisible = displayIndex === visibleItems.length - 1;
+    let arrowPrefix = "";
+    let selectionPrefix = "";
+    if (isFirstVisible && canScrollUp) {
+      arrowPrefix = "\u2191 ";
+    } else if (isLastVisible && canScrollDown) {
+      arrowPrefix = "\u2193 ";
+    } else {
+      arrowPrefix = "  ";
+    }
+    if (isSelected) {
+      selectionPrefix = selectionMarker;
+    } else {
+      selectionPrefix = " ".repeat(selectionMarker.length);
+    }
+    return h2(
+      Box2,
+      { flexDirection: "row" },
+      // Arrow (clickable if functional, not highlighted)
+      h2(Text2, {
+        key: `arrow-${actualIndex}`,
+        color: "white"
+      }, arrowPrefix),
+      // Selection marker space (always same width, not highlighted) 
+      h2(Text2, { key: `marker-${actualIndex}`, color: "white" }, selectionPrefix),
+      // Item name (highlighted if selected)
+      h2(Text2, {
+        key: `name-${actualIndex}`,
+        color: isSelected ? "black" : "white",
+        backgroundColor: isSelected ? "cyan" : void 0,
+        bold: isSelected
+      }, item.name)
+    );
+  };
+  const itemRenderer = renderItem || defaultRenderItem;
+  return h2(
+    Box2,
+    { flexDirection: "column" },
+    ...visibleItems.map((item, displayIndex) => {
+      const actualIndex = clampedScrollOffset + displayIndex;
+      const isSelected = actualIndex === selectedIndex;
+      if (renderItem) {
+        const isFirstVisible = displayIndex === 0;
+        const isLastVisible = displayIndex === visibleItems.length - 1;
+        let arrowPrefix = "";
+        let selectionPrefix = "";
+        if (isFirstVisible && canScrollUp) {
+          arrowPrefix = "\u2191 ";
+        } else if (isLastVisible && canScrollDown) {
+          arrowPrefix = "\u2193 ";
+        } else {
+          arrowPrefix = "  ";
+        }
+        if (isSelected) {
+          selectionPrefix = selectionMarker;
+        } else {
+          selectionPrefix = " ".repeat(selectionMarker.length);
+        }
+        return h2(ScreenRow, {
+          key: `item-${actualIndex}`,
+          children: h2(
+            Box2,
+            { flexDirection: "row" },
+            // Arrow (clickable if functional, not highlighted)
+            h2(Text2, {
+              key: `arrow-${actualIndex}`,
+              color: "white"
+            }, arrowPrefix),
+            // Selection marker space (always same width, not highlighted) 
+            h2(Text2, { key: `marker-${actualIndex}`, color: "white" }, selectionPrefix),
+            // Custom rendered content
+            renderItem(item, isSelected, displayIndex)
+          )
+        });
+      } else {
+        return h2(ScreenRow, {
+          key: `item-${actualIndex}`,
+          children: itemRenderer(item, isSelected, displayIndex, actualIndex)
+        });
+      }
+    })
+  );
+}
+
+// src/screen/screens.ts
+function groupKeyBindings(bindings) {
+  const groups = {};
+  const enabledBindings = bindings.filter((b) => b.enabled !== false);
+  enabledBindings.forEach((binding) => {
+    const caption = typeof binding.caption === "string" ? binding.caption : "";
+    if (!groups[caption]) {
+      groups[caption] = {
+        keys: [],
+        caption,
+        order: binding.order || 999
+      };
+    }
+    groups[caption].keys.push(binding.key);
+  });
+  return Object.values(groups);
+}
+function formatKeyBindings(bindings, mode = "long") {
+  const resolvedBindings = bindings.map((binding) => {
+    let resolvedCaption = binding.caption;
+    if (typeof binding.caption === "function") {
+      resolvedCaption = binding.caption();
+    }
+    return {
+      ...binding,
+      resolvedCaption
+    };
+  });
+  const groups = groupKeyBindings(resolvedBindings.map((b) => ({
+    ...b,
+    caption: typeof b.resolvedCaption === "string" ? b.resolvedCaption : ""
+  })));
+  groups.sort((a, b) => a.order - b.order);
+  const items = [];
+  groups.forEach((group) => {
+    const bindingWithCustom = resolvedBindings.find(
+      (b) => group.keys.includes(b.key) && typeof b.resolvedCaption !== "string"
+    );
+    if (bindingWithCustom && bindingWithCustom.resolvedCaption) {
+      items.push(bindingWithCustom.resolvedCaption);
+    } else {
+      const keyStr = formatKeys(group.keys);
+      if (mode === "long") {
+        items.push(`${keyStr} to ${group.caption}`);
+      } else {
+        items.push(keyStr);
+      }
+    }
+  });
+  return items;
+}
+function formatKeys(keys) {
+  const keyMap = {
+    "escape": "esc",
+    "leftArrow": "\u2190",
+    "rightArrow": "\u2192",
+    "upArrow": "\u2191",
+    "downArrow": "\u2193",
+    "return": "enter"
+  };
+  return keys.map((k) => keyMap[k] || k).join("/");
+}
+async function showScreen(config2) {
+  const {
+    title,
+    onRender,
+    parentData = {}
+  } = config2;
+  return new Promise((resolve2) => {
+    let instance2;
+    const keyBindings = [];
+    const actions = {};
+    const customFooterItems = [];
+    let renderResult = null;
+    let initialized = false;
+    const Screen = () => {
+      const [updateCounter, setUpdateCounter] = useState2(0);
+      if (!initialized) {
+        const defaultBindings = [
+          { key: "escape", caption: "go back", action: "back", protected: true, order: 1 },
+          { key: "leftArrow", caption: "go back", action: "back", protected: false, order: 1 }
+          // Note: 'select' is not a default - components add it if needed
+        ];
+        defaultBindings.forEach((binding) => {
+          keyBindings.push(binding);
+        });
+        actions.back = () => {
+          cleanup(null);
+        };
+        initialized = true;
+      }
+      const context = {
+        setAction: (actionName, handlerFn) => {
+          actions[actionName] = handlerFn;
+        },
+        setKeyBinding: (bindingOrBindings) => {
+          const bindingsToSet = Array.isArray(bindingOrBindings) ? bindingOrBindings : [bindingOrBindings];
+          bindingsToSet.forEach((binding) => {
+            const existingIndex = keyBindings.findIndex((b) => b.key === binding.key);
+            if (existingIndex >= 0) {
+              const existing = keyBindings[existingIndex];
+              if (existing.protected) {
+                console.warn(`Cannot override protected key: ${binding.key}`);
+                return;
+              }
+              keyBindings[existingIndex] = {
+                ...existing,
+                ...binding,
+                order: binding.order !== void 0 ? binding.order : existing.order,
+                enabled: binding.enabled !== void 0 ? binding.enabled : existing.enabled !== void 0 ? existing.enabled : true
+              };
+            } else {
+              keyBindings.push({
+                protected: false,
+                order: 999,
+                enabled: true,
+                ...binding
+              });
+            }
+          });
+        },
+        updateKeyBinding: (keyName, updates) => {
+          const index = keyBindings.findIndex((b) => b.key === keyName);
+          if (index >= 0) {
+            keyBindings[index] = {
+              ...keyBindings[index],
+              ...updates
+            };
+          }
+        },
+        removeKeyBinding: (keyName) => {
+          const index = keyBindings.findIndex((b) => b.key === keyName);
+          if (index >= 0) {
+            if (keyBindings[index].protected) {
+              console.warn(`Cannot remove protected key: ${keyName}`);
+              return;
+            }
+            keyBindings.splice(index, 1);
+          }
+        },
+        addFooter: (item) => {
+          customFooterItems.push(item);
+        },
+        clearFooter: () => {
+          customFooterItems.length = 0;
+        },
+        setFooter: (items) => {
+          customFooterItems.length = 0;
+          const itemsArray = Array.isArray(items) ? items : [items];
+          customFooterItems.push(...itemsArray);
+        },
+        update: () => {
+          setUpdateCounter((c) => c + 1);
+        },
+        goBack: () => {
+          if (actions.back) {
+            actions.back();
+          }
+        },
+        close: (result) => {
+          cleanup(result);
+        },
+        parentData
+      };
+      if (!renderResult) {
+        renderResult = onRender(context);
+      }
+      useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+          cleanup(null);
+          process.exit(0);
+          return;
+        }
+        let matchedBinding = null;
+        for (const binding of keyBindings) {
+          let keyMatches = false;
+          if (key[binding.key]) {
+            keyMatches = true;
+          } else if (input === binding.key) {
+            keyMatches = true;
+          }
+          if (keyMatches) {
+            if (binding.enabled === false) {
+              continue;
+            }
+            if (binding.condition && !binding.condition(context)) {
+              continue;
+            }
+            matchedBinding = binding;
+            break;
+          }
+        }
+        if (matchedBinding && actions[matchedBinding.action]) {
+          const actionResult = actions[matchedBinding.action]({
+            input,
+            key,
+            binding: matchedBinding
+          });
+        }
+      });
+      const footerLines = [];
+      const bindingItems = formatKeyBindings(keyBindings, "long");
+      if (bindingItems.length > 0) {
+        const bindingsLine = [];
+        bindingItems.forEach((item, idx) => {
+          if (idx > 0) {
+            bindingsLine.push(", ");
+          }
+          bindingsLine.push(item);
+        });
+        const allStrings = bindingItems.every((item) => typeof item === "string");
+        if (allStrings) {
+          footerLines.push(bindingsLine.join(""));
+        } else {
+          const wrappedBindingsLine = bindingsLine.map(
+            (item) => typeof item === "string" ? h3(Text3, {}, item) : item
+          );
+          footerLines.push(wrappedBindingsLine);
+        }
+      }
+      customFooterItems.forEach((item) => {
+        if (typeof item === "string") {
+          footerLines.push(item);
+        } else {
+          footerLines.push(item);
+        }
+      });
+      return h3(
+        ScreenContainer,
+        {},
+        h3(ScreenTitle, { text: title }),
+        h3(ScreenDivider),
+        h3(ScreenRow, {}, h3(Text3, {}, " ")),
+        renderResult,
+        h3(ScreenRow, {}, h3(Text3, {}, " ")),
+        h3(ScreenDivider),
+        h3(ScreenFooter, { lines: footerLines })
+      );
+    };
+    const cleanup = (result) => {
+      if (instance2) instance2.unmount();
+      setTimeout(() => resolve2(result), 50);
+    };
+    instance2 = render(h3(Screen));
+  });
+}
+async function showListScreen(config2) {
+  const { title, items, onSelect, onEscape, parentData, initialSelectedIndex = 0, renderItem, getTitle, sortable, maxHeight, sortHighlightStyle, selectionMarker } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected.value, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(ListComponent, { items, ctx, selectedIndexRef, renderItem, getTitle, sortable, maxHeight, sortHighlightStyle, selectionMarker });
+    }
+  });
+}
+async function showMultiColumnListScreen(config2) {
+  const { title, items, onSelect, onEscape, parentData, initialSelectedIndex = 0 } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(MultiColumnListComponent, { items, ctx, selectedIndexRef });
+    }
+  });
+}
+async function showMultiColumnListWithPreviewScreen(config2) {
+  const { title, items, getPreviewContent, onSelect, onEscape, parentData, initialSelectedIndex = 0 } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(MultiColumnListWithPreviewComponent, { items, getPreviewContent, ctx, selectedIndexRef });
+    }
+  });
+}
+var showMenuScreen = showListScreen;
+var showWordGridScreen = showMultiColumnListScreen;
+
+// src/screen/ui-elements.ts
+import { createElement as h4 } from "react";
+import { Box as Box4, Text as Text4 } from "ink";
+function ListItem({
+  children,
+  isSelected = false,
+  color = "white",
+  backgroundColor,
+  bold = false,
+  dimColor = false
+}) {
+  return h4(
+    Box4,
+    {},
+    h4(Text4, {
+      color: isSelected ? backgroundColor || "green" : color,
+      backgroundColor: isSelected ? color : backgroundColor,
+      bold: isSelected || bold,
+      dimColor: !isSelected && dimColor
+    }, children)
+  );
+}
+function TextBlock({
+  text,
+  color = "white",
+  dimmed = false,
+  bold = false,
+  maxWidth
+}) {
+  return h4(
+    Box4,
+    {},
+    h4(Text4, {
+      color,
+      dimColor: dimmed,
+      bold
+    }, text)
+  );
+}
+function Divider({ character = "\u2500", width = 80 }) {
+  return h4(
+    Box4,
+    { marginY: 1 },
+    h4(Text4, { dimColor: true }, character.repeat(width))
+  );
+}
+function GridCell({
+  children,
+  width,
+  color = "white",
+  backgroundColor,
+  bold = false,
+  dimColor = false,
+  align = "left"
+}) {
+  return h4(
+    Box4,
+    { width },
+    h4(Text4, {
+      color,
+      backgroundColor,
+      bold,
+      dimColor,
+      textAlign: align
+    }, children)
+  );
+}
+function InputField({ prompt, value, onChange, onSubmit }) {
+  return h4(
+    Box4,
+    { flexDirection: "column" },
+    h4(Text4, {}, prompt),
+    h4(
+      Box4,
+      { marginTop: 1 },
+      h4(Text4, { color: "cyan" }, " > ", value, "_")
+    )
+  );
+}
+
+// src/screen/utils.ts
+function buildBreadcrumb(parts) {
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return parts.slice(1).map((part) => `\u2190  ${part}`).join("  ");
+}
+function buildDetailBreadcrumb(path, suffix = "") {
+  if (path.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path[0] || "";
+  }
+  const breadcrumb = buildBreadcrumb(path);
+  return suffix ? `${breadcrumb} ${suffix}` : breadcrumb;
+}
+
+// src/screen/footer-builder.ts
+function buildFooter(config2 = {}) {
+  const {
+    navigation = null,
+    actions = null,
+    info = null,
+    escape = "Esc to go back",
+    custom = null
+  } = config2;
+  const lines = [];
+  const mainParts = [];
+  if (navigation) {
+    mainParts.push(navigation);
+  }
+  if (actions) {
+    mainParts.push(actions);
+  }
+  if (escape) {
+    mainParts.push(escape);
+  }
+  if (mainParts.length > 0) {
+    lines.push(mainParts.join(", "));
+  }
+  if (info) {
+    const infoLines = Array.isArray(info) ? info : [info];
+    lines.push(...infoLines);
+  }
+  if (custom) {
+    const customLines = Array.isArray(custom) ? custom : [custom];
+    lines.push(...customLines);
+  }
+  return lines;
+}
+var FooterPresets = {
+  /**
+   * Menu screen footer
+   */
+  menu: (customInfo = null) => buildFooter({
+    navigation: "\u2191/\u2193 to navigate",
+    actions: "Enter to select",
+    escape: "Esc to go back",
+    info: customInfo
+  }),
+  /**
+   * Word grid footer
+   */
+  wordGrid: (totalWords) => buildFooter({
+    navigation: "\u2191\u2193\u2190\u2192 to navigate",
+    actions: "Enter to select",
+    escape: "Esc to go back",
+    info: `Total: ${totalWords} words`
+  }),
+  /**
+   * Text input footer
+   */
+  textInput: () => buildFooter({
+    actions: "Type and press Enter to submit",
+    escape: "Esc to cancel"
+  }),
+  /**
+   * Info/static screen footer
+   */
+  info: () => buildFooter({
+    escape: "Esc to continue"
+  }),
+  /**
+   * Main menu footer (escape exits)
+   */
+  mainMenu: () => buildFooter({
+    navigation: "\u2191/\u2193 to navigate",
+    actions: "Enter to select",
+    escape: "Esc to exit"
+  }),
+  /**
+   * Action menu footer (for word cards, etc.)
+   */
+  actionMenu: (hasAudio = false) => {
+    const parts = buildFooter({
+      navigation: "\u2191/\u2193 to navigate",
+      actions: "Enter to select",
+      escape: "Esc to go back"
+    });
+    if (hasAudio) {
+      parts.push("Audio available");
+    }
+    return parts;
+  }
+};
+function organizeFooterMessages(messages) {
+  if (!messages || messages.length === 0) {
+    return ["Esc to go back"];
+  }
+  const navigation = messages.filter((m) => m.includes("\u2191") || m.includes("\u2193") || m.includes("\u2190") || m.includes("\u2192"));
+  const actions = messages.filter((m) => m.includes("Enter") || m.includes("select") || m.includes("submit"));
+  const escape = messages.filter((m) => m.includes("Esc"));
+  const others = messages.filter(
+    (m) => !navigation.includes(m) && !actions.includes(m) && !escape.includes(m)
+  );
+  const lines = [];
+  const mainLine = [...navigation, ...actions, ...escape].join(", ");
+  if (mainLine) lines.push(mainLine);
+  lines.push(...others);
+  return lines;
+}
+export {
+  Args,
+  Divider,
+  FooterPresets,
+  GridCell,
+  InputField,
+  ListComponent,
+  ListItem,
+  MultiColumnListComponent,
+  MultiColumnListWithPreviewComponent,
+  Params,
+  ScreenBody,
+  ScreenContainer,
+  ScreenDivider,
+  ScreenFooter,
+  ScreenRow,
+  ScreenTitle,
+  TextBlock,
+  buildBreadcrumb,
+  buildDetailBreadcrumb,
+  buildFooter,
+  getArgsInstance,
+  getParamsInstance,
+  joiEdateType,
+  joiStringArrayType,
+  organizeFooterMessages,
+  showListScreen,
+  showMenuScreen,
+  showMultiColumnListScreen,
+  showMultiColumnListWithPreviewScreen,
+  showScreen,
+  showWordGridScreen
+};
+//# sourceMappingURL=index.js.map