@alcyone-labs/arg-parser 2.9.0 → 2.10.0

package/dist/index.mjs

@@ -1468,7 +1468,7 @@ const zodFlagSchema = z.object({
   ),
   enum: z.array(z.any()).optional().describe("Array of allowed values for the flag."),
   env: z.union([z.string(), z.array(z.string())]).optional().describe(
-    "Environment variables that should be set from this flag's value in DXT packages."
+    "Environment variable(s) to map to this flag. Logic: Fallback (Env -> Flag) and Sync (Flag -> Env). Precedence: Flag > Env > Default."
   ),
   dxtOptions: zodDxtOptionsSchema.optional().describe(
     "DXT-specific configuration options for enhanced DXT manifest generation"
@@ -4013,7 +4013,7 @@ class ArgParserBase {
   }
   async #_handleGlobalChecks(processArgs, options) {
     const isRootCliParser = !this.#parentParser && !!this.#appCommandName;
-    if (processArgs.length === 0 && isRootCliParser && !this.#handler) {
+    if (processArgs.length === 0 && isRootCliParser && !this.#handler && !options?.skipHelpHandling) {
       console.log(this.helpText());
       return this._handleExit(0, "Help displayed", "help");
     }
@@ -4313,6 +4313,54 @@ class ArgParserBase {
       }
     }
   }
+  #_applyEnvFallback(finalArgs, finalParser) {
+    for (const flag of finalParser.#flagManager.flags) {
+      const flagName = flag["name"];
+      if (!flag["env"]) continue;
+      if (finalArgs[flagName] !== void 0) {
+        continue;
+      }
+      const envVars = Array.isArray(flag["env"]) ? flag["env"] : [flag["env"]];
+      let foundVal;
+      for (const envKey of envVars) {
+        if (process.env[envKey] !== void 0) {
+          foundVal = process.env[envKey];
+          break;
+        }
+      }
+      if (foundVal !== void 0) {
+        try {
+          const typedVal = this.#configurationManager.convertValueToFlagType(foundVal, flag);
+          if (flag["allowMultiple"]) {
+            finalArgs[flagName] = Array.isArray(typedVal) ? typedVal : [typedVal];
+          } else {
+            finalArgs[flagName] = typedVal;
+          }
+        } catch (e) {
+          console.warn(simpleChalk.yellow(`Warning: Failed to parse env var for flag '${flagName}': ${e}`));
+        }
+      }
+    }
+  }
+  #_syncToEnv(finalArgs, finalParser) {
+    for (const flag of finalParser.#flagManager.flags) {
+      if (!flag["env"]) continue;
+      const flagName = flag["name"];
+      const value = finalArgs[flagName];
+      if (value !== void 0) {
+        const envVars = Array.isArray(flag["env"]) ? flag["env"] : [flag["env"]];
+        let strVal = "";
+        if (typeof value === "object") {
+          strVal = JSON.stringify(value);
+        } else {
+          strVal = String(value);
+        }
+        for (const envKey of envVars) {
+          process.env[envKey] = strVal;
+        }
+      }
+    }
+  }
   #_prepareAndExecuteHandler(handlerToExecute, finalArgs, skipHandlers) {
     if (skipHandlers || !handlerToExecute) {
       return;
@@ -4524,7 +4572,9 @@ class ArgParserBase {
     }
     const argsForCurrentLevel = subCommandIndex === -1 ? argsToParse : argsToParse.slice(0, subCommandIndex);
     const { parsedArgs: currentLevelArgs, firstUnconsumedIndex } = await currentParser.#parseFlags(argsForCurrentLevel, options);
+    this.#_applyEnvFallback(currentLevelArgs, currentParser);
     currentParser.#_applyDefaultValues(currentLevelArgs, currentParser);
+    this.#_syncToEnv(currentLevelArgs, currentParser);
     const combinedArgsFromThisAndParents = {
       ...accumulatedParentArgs,
       ...currentLevelArgs
@@ -8898,6 +8948,527 @@ class ArgParserFuzzyTester {
     };
   }
 }
+class Terminal {
+  constructor() {
+  }
+  static getInstance() {
+    if (!Terminal.instance) {
+      Terminal.instance = new Terminal();
+    }
+    return Terminal.instance;
+  }
+  get width() {
+    return process.stdout.columns || 80;
+  }
+  get height() {
+    return process.stdout.rows || 24;
+  }
+  write(text) {
+    process.stdout.write(text);
+  }
+  clear() {
+    process.stdout.write("\x1B[2J\x1B[3J\x1B[H");
+  }
+  hideCursor() {
+    process.stdout.write("\x1B[?25l");
+  }
+  showCursor() {
+    process.stdout.write("\x1B[?25h");
+  }
+  moveCursor(x, y) {
+    (void 0)(process.stdout, x, y);
+  }
+  enableRawMode() {
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding("utf8");
+    }
+  }
+  enableMouse() {
+    process.stdout.write("\x1B[?1000h\x1B[?1002h\x1B[?1006h");
+  }
+  disableMouse() {
+    process.stdout.write("\x1B[?1000l\x1B[?1002l\x1B[?1006l");
+  }
+  disableRawMode() {
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+  }
+  onKey(callback) {
+    process.stdin.on("data", (data2) => {
+      const char2 = data2.toString();
+      if (char2 === "") {
+        this.cleanup();
+        process.exit(0);
+      }
+      callback(char2, false);
+    });
+  }
+  cleanup() {
+    this.showCursor();
+    this.disableMouse();
+    this.disableRawMode();
+  }
+}
+class Component {
+  constructor(config = {}) {
+    this.x = 0;
+    this.y = 0;
+    this.width = 0;
+    this.height = 0;
+    this.config = config;
+    this.id = config.id || `component_${Math.random().toString(36).substr(2, 9)}`;
+  }
+  resize(x, y, width, height) {
+    this.x = x;
+    this.y = y;
+    this.width = width;
+    this.height = height;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  handleInput(_key) {
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  handleMouse(_event) {
+  }
+}
+class SplitLayout extends Component {
+  constructor(config) {
+    super(config);
+    this.direction = config.direction;
+    this.first = config.first;
+    this.second = config.second;
+    this.splitRatio = config.splitRatio ?? 0.5;
+  }
+  resize(x, y, width, height) {
+    super.resize(x, y, width, height);
+    if (this.direction === "horizontal") {
+      const splitX = Math.floor(width * this.splitRatio);
+      this.first.resize(x, y, splitX, height);
+      this.second.resize(x + splitX, y, width - splitX, height);
+    } else {
+      const splitY = Math.floor(height * this.splitRatio);
+      this.first.resize(x, y, width, splitY);
+      this.second.resize(x, y + splitY, width, height - splitY);
+    }
+  }
+  render() {
+    const lines = [];
+    const firstLines = this.first.render();
+    const secondLines = this.second.render();
+    if (this.direction === "horizontal") {
+      const maxHeight = Math.max(firstLines.length, secondLines.length);
+      for (let i = 0; i < maxHeight; i++) {
+        const line1 = firstLines[i] || " ".repeat(this.first["width"]);
+        const line2 = secondLines[i] || " ".repeat(this.second["width"]);
+        lines.push(line1 + line2);
+      }
+    } else {
+      lines.push(...firstLines);
+      lines.push(...secondLines);
+    }
+    return lines;
+  }
+  handleInput(key) {
+    this.first.handleInput(key);
+    this.second.handleInput(key);
+  }
+  handleMouse(event) {
+    this.first.handleMouse(event);
+    this.second.handleMouse(event);
+  }
+}
+class App {
+  constructor() {
+    this.isRunning = false;
+    this.lastRenderedLines = [];
+    this.terminal = Terminal.getInstance();
+  }
+  run(root) {
+    this.root = root;
+    this.isRunning = true;
+    this.terminal.enableRawMode();
+    this.terminal.enableMouse();
+    this.terminal.hideCursor();
+    this.terminal.clear();
+    this.render();
+    const cleanup = () => this.terminal.cleanup();
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => {
+      cleanup();
+      process.exit(0);
+    });
+    process.on("uncaughtException", (err) => {
+      cleanup();
+      console.error(err);
+      process.exit(1);
+    });
+    this.terminal.onKey((key) => {
+      if (key.startsWith("\x1B[<")) {
+        const parts = key.substring(3).split(";");
+        if (parts.length === 3) {
+          let buttonCode = parseInt(parts[0]);
+          const x = parseInt(parts[1]) - 1;
+          const lastPart = parts[2];
+          const y = parseInt(lastPart.substring(0, lastPart.length - 1)) - 1;
+          const type2 = lastPart.charAt(lastPart.length - 1);
+          let action = "press";
+          let button = 0;
+          if (type2 === "m") {
+            action = "release";
+          } else {
+            if (buttonCode >= 64) {
+              action = buttonCode === 64 ? "scroll_up" : "scroll_down";
+              buttonCode -= 64;
+            } else {
+              if (buttonCode === 0) button = 0;
+              else if (buttonCode === 1) button = 1;
+              else if (buttonCode === 2) button = 2;
+              if ((buttonCode & 32) === 32) {
+                action = "drag";
+                buttonCode -= 32;
+                if (buttonCode === 0) button = 0;
+              }
+            }
+          }
+          const event = { x, y, button, action };
+          if (this.root) {
+            this.root.handleMouse(event);
+            this.render();
+          }
+          return;
+        }
+      }
+      if (key === "\x1B" || key === "") {
+        this.stop();
+        return;
+      }
+      if (this.root) {
+        this.root.handleInput(key);
+        this.render();
+      }
+    });
+    process.stdout.on("resize", () => {
+      this.render();
+    });
+  }
+  stop() {
+    this.isRunning = false;
+    this.terminal.cleanup();
+    process.exit(0);
+  }
+  render() {
+    if (!this.root || !this.isRunning) return;
+    const width = this.terminal.width;
+    const height = this.terminal.height;
+    this.root.resize(0, 0, width, height);
+    const lines = this.root.render();
+    const maxLines = Math.min(lines.length, height - 1);
+    this.terminal.write("\x1B[H");
+    for (let i = 0; i < maxLines; i++) {
+      const line = lines[i];
+      const lastLine = this.lastRenderedLines[i];
+      if (line !== lastLine) {
+        this.terminal.moveCursor(0, i);
+        this.terminal.write(line);
+        this.terminal.write("\x1B[K");
+      }
+    }
+    this.lastRenderedLines = [...lines];
+  }
+}
+const Themes = {
+  Default: {
+    // Dark Mode
+    base: simpleChalk.white,
+    muted: simpleChalk.gray,
+    accent: simpleChalk.cyan,
+    highlight: simpleChalk.cyan,
+    // Was bgBlue.white
+    success: simpleChalk.green,
+    warning: simpleChalk.yellow,
+    error: simpleChalk.red,
+    border: simpleChalk.gray,
+    scrollbarThumb: simpleChalk.white,
+    scrollbarTrack: simpleChalk.gray
+  },
+  Light: {
+    // "Ocean" theme (High contrast on dark)
+    base: simpleChalk.white,
+    muted: simpleChalk.gray,
+    accent: simpleChalk.cyan,
+    highlight: simpleChalk.cyan,
+    // Fallback since bgCyan not supported
+    success: simpleChalk.green,
+    warning: simpleChalk.yellow,
+    error: simpleChalk.red,
+    border: simpleChalk.cyan,
+    scrollbarThumb: simpleChalk.cyan,
+    scrollbarTrack: simpleChalk.gray
+  },
+  Monokai: {
+    base: simpleChalk.white,
+    muted: simpleChalk.gray,
+    accent: simpleChalk.magenta,
+    highlight: simpleChalk.magenta,
+    // Was bgMagenta.white
+    success: simpleChalk.green,
+    warning: simpleChalk.yellow,
+    error: simpleChalk.red,
+    border: simpleChalk.gray,
+    scrollbarThumb: simpleChalk.magenta,
+    scrollbarTrack: simpleChalk.gray
+  }
+};
+const _ThemeManager = class _ThemeManager {
+  static get current() {
+    return this._current;
+  }
+  static setTheme(name) {
+    if (Themes[name]) {
+      this._current = Themes[name];
+    }
+  }
+  static setCustomTheme(theme) {
+    this._current = theme;
+  }
+};
+_ThemeManager._current = Themes["Default"];
+let ThemeManager = _ThemeManager;
+class List extends Component {
+  constructor(config) {
+    super(config);
+    this.selectedIndex = 0;
+    this.scrollOffset = 0;
+    this.items = config.items;
+    this.onSelect = config.onSelect;
+    this.onSubmit = config.onSubmit;
+  }
+  setItems(items2) {
+    this.items = items2;
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+  }
+  render() {
+    const lines = [];
+    const visibleCount = this.height;
+    if (this.selectedIndex < this.scrollOffset) {
+      this.scrollOffset = this.selectedIndex;
+    } else if (this.selectedIndex >= this.scrollOffset + visibleCount) {
+      this.scrollOffset = this.selectedIndex - visibleCount + 1;
+    }
+    const visibleItems = this.items.slice(this.scrollOffset, this.scrollOffset + visibleCount);
+    for (let i = 0; i < this.height; i++) {
+      const itemIndex = this.scrollOffset + i;
+      const item = visibleItems[i];
+      if (!item) {
+        lines.push(" ".repeat(this.width));
+        continue;
+      }
+      const isSelected = itemIndex === this.selectedIndex;
+      const theme = ThemeManager.current;
+      let line = "";
+      if (isSelected) {
+        line = theme.highlight("> " + item.label);
+      } else {
+        line = theme.base("  " + item.label);
+      }
+      const rawLabelLength = item.label.length + 2;
+      const padding = Math.max(0, this.width - rawLabelLength);
+      if (isSelected) {
+        line = theme.highlight("> " + item.label + " ".repeat(padding));
+      } else {
+        line = theme.base("  " + item.label + " ".repeat(padding));
+      }
+      lines.push(line);
+    }
+    return lines;
+  }
+  handleInput(key) {
+    if (this.items.length === 0) return;
+    if (key === "\x1B[A") {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      if (this.onSelect) this.onSelect(this.items[this.selectedIndex]);
+    } else if (key === "\x1B[B") {
+      this.selectedIndex = Math.min(this.items.length - 1, this.selectedIndex + 1);
+      if (this.onSelect) this.onSelect(this.items[this.selectedIndex]);
+    } else if (key === "\r" || key === "\x1B[C") {
+      if (this.onSubmit) this.onSubmit(this.items[this.selectedIndex]);
+    }
+  }
+}
+class ScrollArea extends Component {
+  constructor(config) {
+    super(config);
+    this.contentLines = [];
+    this.scrollOffset = 0;
+    this.content = config.content;
+    this.updateContentLines();
+  }
+  setContent(content) {
+    this.content = typeof content === "string" ? content : String(content || "");
+    this.scrollOffset = 0;
+    this.updateContentLines();
+  }
+  updateContentLines() {
+    this.contentLines = this.content.split("\n");
+  }
+  render() {
+    const lines = [];
+    const visibleLines = this.contentLines.slice(this.scrollOffset, this.scrollOffset + this.height);
+    const showScrollbar = this.contentLines.length > this.height;
+    let scrollbarHeight = 0;
+    let scrollbarTop = 0;
+    if (showScrollbar) {
+      const ratio = this.height / this.contentLines.length;
+      scrollbarHeight = Math.max(1, Math.floor(this.height * ratio));
+      const scrollPercent = this.scrollOffset / (this.contentLines.length - this.height);
+      const maxTop = this.height - scrollbarHeight;
+      scrollbarTop = Math.floor(scrollPercent * maxTop);
+    }
+    const stripAnsi = (str) => str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, "");
+    for (let i = 0; i < this.height; i++) {
+      const lineContent = visibleLines[i] || "";
+      let prefix = "";
+      if (showScrollbar) {
+        const isThumb = i >= scrollbarTop && i < scrollbarTop + scrollbarHeight;
+        const theme = ThemeManager.current;
+        prefix = isThumb ? theme.scrollbarThumb("█") : theme.scrollbarTrack("│");
+        prefix += " ";
+      }
+      const visibleWidth = showScrollbar ? this.width - 2 : this.width;
+      const visibleLength = stripAnsi(lineContent).length;
+      const rawLength = lineContent.length;
+      const invisibleLength = rawLength - visibleLength;
+      let renderedContent = "";
+      if (visibleLength > visibleWidth) {
+        renderedContent = lineContent.substring(0, visibleWidth + invisibleLength);
+      } else {
+        const padding = Math.max(0, visibleWidth - visibleLength);
+        renderedContent = lineContent + " ".repeat(padding);
+      }
+      lines.push(prefix + renderedContent);
+    }
+    return lines;
+  }
+  handleMouse(event) {
+    if (event.x >= this.x && event.x < this.x + this.width && event.y >= this.y && event.y < this.y + this.height) {
+      if (event.action === "scroll_up") {
+        this.scrollOffset = Math.max(0, this.scrollOffset - 3);
+      } else if (event.action === "scroll_down") {
+        const maxScroll = Math.max(0, this.contentLines.length - this.height);
+        this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 3);
+      }
+    }
+  }
+  handleInput(key) {
+    if (key === "\x1B[A") {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+    } else if (key === "\x1B[B") {
+      const maxScroll = Math.max(0, this.contentLines.length - this.height);
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+    } else if (key === "\x1B[5~") {
+      this.scrollOffset = Math.max(0, this.scrollOffset - this.height);
+    } else if (key === "\x1B[6~") {
+      const maxScroll = Math.max(0, this.contentLines.length - this.height);
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + this.height);
+    }
+  }
+}
+class Input extends Component {
+  constructor(config) {
+    super(config);
+    this.prefix = config.prefix || "";
+    this.placeholder = config.placeholder || "";
+    this.value = config.value || "";
+    this.onChange = config.onChange;
+    this.onSubmit = config.onSubmit;
+  }
+  setValue(value) {
+    this.value = value;
+    if (this.onChange) this.onChange(this.value);
+  }
+  getValue() {
+    return this.value;
+  }
+  render() {
+    const lines = [];
+    const theme = ThemeManager.current;
+    let text = this.prefix + (this.value || theme.muted(this.placeholder));
+    if (text.length > this.width) {
+      text = text.substring(0, this.width - 1) + "…";
+    }
+    lines.push((text + " ".repeat(Math.max(0, this.width - text.length))).substring(0, this.width));
+    return lines;
+  }
+  handleInput(key) {
+    if (key === "\r") {
+      if (this.onSubmit) this.onSubmit(this.value);
+    } else if (key === "" || key === "\b") {
+      if (this.value.length > 0) {
+        this.value = this.value.substring(0, this.value.length - 1);
+        if (this.onChange) this.onChange(this.value);
+      }
+    } else if (key.length === 1 && key >= " " && key <= "~") {
+      this.value += key;
+      if (this.onChange) this.onChange(this.value);
+    }
+  }
+}
+class StackNavigator extends Component {
+  constructor(config) {
+    super(config);
+    this.stack = [];
+    this.stack.push(config.initialComponent);
+  }
+  push(component) {
+    this.stack.push(component);
+    component.resize(this.x, this.y, this.width, this.height);
+  }
+  pop() {
+    if (this.stack.length > 1) {
+      this.stack.pop();
+    }
+  }
+  get currentComponent() {
+    return this.stack[this.stack.length - 1];
+  }
+  resize(x, y, width, height) {
+    super.resize(x, y, width, height);
+    this.currentComponent.resize(x, y, width, height);
+  }
+  render() {
+    return this.currentComponent.render();
+  }
+  handleInput(key) {
+    if ((key === "\x1B" || key === "\x1B[D") && this.stack.length > 1) {
+      this.pop();
+      this.currentComponent.resize(this.x, this.y, this.width, this.height);
+      return;
+    }
+    this.currentComponent.handleInput(key);
+  }
+  handleMouse(event) {
+    this.currentComponent.handleMouse(event);
+  }
+}
+const index$2 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  App,
+  Component,
+  Input,
+  List,
+  ScrollArea,
+  SplitLayout,
+  StackNavigator,
+  Terminal,
+  ThemeManager,
+  Themes
+}, Symbol.toStringTag, { value: "Module" }));
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 const DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26";
 const SUPPORTED_PROTOCOL_VERSIONS = [
@@ -25593,6 +26164,7 @@ export {
   OutputSchemaPatterns,
   simpleChalk as SimpleChalk,
   TomlConfigPlugin,
+  index$2 as UI,
   YamlConfigPlugin,
   absolutePath,
   convertFlagToJsonSchemaProperty,