termkit 2.3.0 → 2.4.0

package/dist/index.js

@@ -32,7 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   Bar: () => Bar,
   Chart: () => Chart_exports,
-  Color: () => import_cosmetic4.default,
+  Color: () => import_cosmetic5.default,
   Column: () => Column,
   Command: () => Command,
   Input: () => Input,
@@ -43,6 +43,7 @@ __export(index_exports, {
   Program: () => Program,
   Scrollbox: () => Scrollbox,
   Select: () => Select,
+  Shell: () => Shell,
   Spinner: () => Spinner,
   Table: () => Table,
   TermKit: () => TermKit,
@@ -191,6 +192,8 @@ function findCommand(array, commands) {
 var RESET = "\x1B[0m";
 var SHOW_CURSOR = "\x1B[?25h";
 var HIDE_CURSOR = "\x1B[?25l";
+var DISABLE_WRAP = "\x1B[?7l";
+var ENABLE_WRAP = "\x1B[?7h";
 var BOLD = "\x1B[1m";
 var FAINT = "\x1B[2m";
 var GREEN = "\x1B[32m";
@@ -557,15 +560,22 @@ var Select = class {
     if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Select requires an interactive terminal");
     let selectedIndex = 0;
     let viewportOffset = 0;
+    let visibleStart = 0;
     let searchQuery = "";
     let lastDrawnLines = 0;
     const skipItem = { label: this.skipLabel };
+    const computeMaxHeight = () => {
+      const termRows = process.stdout.rows ?? 24;
+      const reserved = 1 + (this.searchEnabled ? 1 : 0);
+      const fit = Math.max(1, termRows - reserved - 1);
+      return this.maxHeight ? Math.min(this.maxHeight, fit) : fit;
+    };
     const getFiltered = () => {
       if (!this.searchEnabled || searchQuery === "") return items;
       const q = searchQuery.toLowerCase();
       return items.filter((item) => item.label.toLowerCase().includes(q) || (item.description?.toLowerCase().includes(q) ?? false));
     };
-    process.stdout.write(HIDE_CURSOR);
+    process.stdout.write(HIDE_CURSOR + DISABLE_WRAP);
     const glyph = this.promptGlyph ? `${colorText(this.promptColor, this.promptGlyph)} ` : "";
     const indent = " ".repeat(this.promptGlyph ? stringLength(this.promptGlyph) + 1 : 0);
     process.stdout.write(`${glyph}${prompt}
@@ -574,13 +584,17 @@ var Select = class {
       const filtered = getFiltered();
       const allItems = [...filtered, skipItem];
       if (selectedIndex >= allItems.length) selectedIndex = allItems.length - 1;
-      if (this.maxHeight) {
+      const maxHeight = computeMaxHeight();
+      const useViewport = allItems.length > maxHeight;
+      if (useViewport) {
         if (selectedIndex < viewportOffset) viewportOffset = selectedIndex;
-        else if (selectedIndex >= viewportOffset + this.maxHeight) viewportOffset = selectedIndex - this.maxHeight + 1;
-        viewportOffset = Math.max(0, Math.min(viewportOffset, Math.max(0, allItems.length - this.maxHeight)));
+        else if (selectedIndex >= viewportOffset + maxHeight) viewportOffset = selectedIndex - maxHeight + 1;
+        viewportOffset = Math.max(0, Math.min(viewportOffset, Math.max(0, allItems.length - maxHeight)));
+      } else {
+        viewportOffset = 0;
       }
-      const visibleStart = this.maxHeight ? viewportOffset : 0;
-      const visibleEnd = this.maxHeight ? Math.min(allItems.length, viewportOffset + this.maxHeight) : allItems.length;
+      visibleStart = useViewport ? viewportOffset : 0;
+      const visibleEnd = useViewport ? Math.min(allItems.length, viewportOffset + maxHeight) : allItems.length;
       if (redraw) {
         if (lastDrawnLines > 0) process.stdout.write(CURSOR_UP(lastDrawnLines));
         process.stdout.write("\r\x1B[0J");
@@ -596,8 +610,7 @@ var Select = class {
         const item = allItems[i];
         const isSelected = i === selectedIndex;
         const isSkip = i === filtered.length;
-        const relativeNum = i - visibleStart + 1;
-        const numStr = isSkip ? "0." : `${relativeNum}.`;
+        const numStr = isSkip ? "0." : `${i + 1}.`;
         const desc = item.description ? ` ${colorText(this.descriptionColor, `\u2014 ${item.description}`)}` : "";
         let marker, tail;
         if (isSelected && pulse) {
@@ -624,7 +637,7 @@ var Select = class {
         process.stdin.setRawMode(false);
         process.stdin.pause();
         process.stdin.removeListener("data", onKey);
-        process.stdout.write(SHOW_CURSOR);
+        process.stdout.write(ENABLE_WRAP + SHOW_CURSOR);
       });
       const cleanup = () => {
         deregisterCleanup();
@@ -635,7 +648,7 @@ var Select = class {
         process.stdin.setRawMode(false);
         process.stdin.pause();
         process.stdin.removeListener("data", onKey);
-        process.stdout.write(SHOW_CURSOR);
+        process.stdout.write(ENABLE_WRAP + SHOW_CURSOR);
       };
       if (this._parsedColors.length >= 2) {
         timer = setInterval(() => {
@@ -678,8 +691,7 @@ var Select = class {
         } else {
           const n = parseInt(str);
           if (!isNaN(n) && n >= 0 && n <= Math.min(items.length, 9)) {
-            const visibleStart = this.maxHeight ? viewportOffset : 0;
-            selectedIndex = n === 0 ? allItems.length - 1 : visibleStart + n - 1;
+            selectedIndex = n === 0 ? allItems.length - 1 : n - 1;
             selectedIndex = Math.max(0, Math.min(selectedIndex, allItems.length - 1));
             renderList(true);
           }
@@ -860,7 +872,7 @@ var Command = class {
   constructor(data) {
     this.actionFunction = null;
     this.commandsArray = [];
-    this.commandStrings = ["help"];
+    this.commandStrings = ["help", "version"];
     this.info = null;
     this.middlewaresArray = [];
     this.name = null;
@@ -930,6 +942,9 @@ var Command = class {
     const recursive = source?.includes("-r") === true || source?.includes("--recursive") === true;
     this.printHelp(this.name ?? "Program", recursive);
   }
+  printVersion() {
+    console.log(this.versionString ?? "");
+  }
   printHelp(fullName, recursive) {
     const table = [];
     let program = fullName;
@@ -989,29 +1004,32 @@ var Command = class {
       }
     }
   }
-  async parse(input2) {
-    const array = [...input2];
-    array.splice(0, 2);
+  async _execute(tokens) {
+    const array = [...tokens];
     let command = this;
     const options = { _source: Array.from(array) };
+    if (this.versionString && (array.includes("--version") || array.includes("-V"))) {
+      return this.printVersion();
+    }
     const ddIdx = array.indexOf("--");
     if (ddIdx !== -1) {
       options._ = array.splice(ddIdx + 1);
       array.splice(ddIdx, 1);
     }
     while (array.length) {
-      if (!array.includes("help")) {
+      if (!array.includes("help") && !array.includes("version")) {
         Object.assign(options, await findOptions(array, command));
         const cmdVars = await findCommandVariables(array, command);
         if (cmdVars) Object.assign(options, cmdVars);
         Object.assign(options, await findOptions(array, command));
       }
       if (array.length) {
-        if (!array.includes("help")) {
+        if (!array.includes("help") && !array.includes("version")) {
           for (const mw of command.middlewaresArray) await mw(options);
         }
         const next = findCommand(array, command.commandsArray);
         if (!next && array[0] === "help") return command.help(options._source);
+        if (!next && array[0] === "version") return this.printVersion();
         if (!next) throw new SyntaxError(`Unknown command: ${array[0]}`);
         const name = command.name ?? "_base";
         if (!options._parents) options._parents = {};
@@ -1035,14 +1053,229 @@ var Command = class {
     }
     for (const mw of command.middlewaresArray) await mw(options);
     if (command.actionFunction) return command.actionFunction(options);
-    if (options._source.length === 2) return command.help(options._source);
-    throw new Error(`No action for command: ${command.name ?? "_base"}`);
+    return command.help(options._source);
+  }
+  async parse(input2) {
+    return this._execute(input2.slice(2));
+  }
+};
+
+// src/models/Shell.ts
+var import_cosmetic2 = __toESM(require("cosmetic"));
+var readline = __toESM(require("readline"));
+var Shell = class {
+  constructor(root, opts = {}) {
+    this.rl = null;
+    this.root = root;
+    this.opts = {
+      mode: opts.mode ?? "drill",
+      prompt: opts.prompt ?? root.name ?? "shell",
+      promptColor: opts.promptColor ?? "",
+      banner: opts.banner ?? "",
+      exitCommands: opts.exitCommands ?? ["exit", "quit"],
+      historySize: opts.historySize ?? 100
+    };
+  }
+  async run() {
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+      historySize: this.opts.historySize,
+      completer: this.opts.mode === "free" ? makeCompleter(this.root) : void 0
+    });
+    if (this.opts.banner) console.log(this.opts.banner);
+    try {
+      if (this.opts.mode === "free") {
+        await this.freeLoop();
+      } else {
+        await this.drillLoop();
+      }
+    } finally {
+      this.rl.close();
+    }
+  }
+  // ── Drill mode ────────────────────────────────────────────────────────
+  async drillLoop() {
+    while (true) {
+      const exited = await this.drillFrom(this.root, [this.root.name ?? "shell"]);
+      if (exited) return;
+    }
+  }
+  async drillFrom(cmd, breadcrumb) {
+    while (true) {
+      const token = await this.promptDrill(cmd, breadcrumb);
+      if (token === null) {
+        return breadcrumb.length === 1;
+      }
+      if (this.opts.exitCommands.includes(token)) process.exit(0);
+      if (token === "..") return false;
+      if (token === "help") {
+        cmd.help();
+        continue;
+      }
+      const sub = cmd.commandsArray.find((c) => c.name === token);
+      if (!sub) {
+        process.stderr.write(`Unknown command: ${token}
+`);
+        continue;
+      }
+      if (sub.commandsArray.length > 0) {
+        const exited = await this.drillFrom(sub, [...breadcrumb, sub.name ?? ""]);
+        if (exited) return true;
+        continue;
+      }
+      const vars = await this.gatherVariables(sub);
+      const tokens = buildTokens(sub, vars);
+      try {
+        await sub._execute(tokens);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : err}
+`);
+      }
+      return false;
+    }
+  }
+  async promptDrill(cmd, breadcrumb) {
+    const subs = cmd.commandsArray.map((c) => c.name ?? "").filter(Boolean);
+    const label = this.colorize(breadcrumb.join(" "));
+    const choices = [...subs, "help"].join(", ");
+    process.stdout.write(`
+  ${label}  ${choices}
+`);
+    return new Promise((resolve) => {
+      let resolved = false;
+      const done = (val) => {
+        if (!resolved) {
+          resolved = true;
+          resolve(val);
+        }
+      };
+      this.rl.question("> ", (answer) => done(answer.trim() || null));
+      this.rl.once("close", () => done(null));
+    });
+  }
+  async gatherVariables(cmd) {
+    const result = {};
+    if (!cmd.variables) return result;
+    for (const v of cmd.variables) {
+      const name = v.name ?? "value";
+      const hint = v.hint ? ` ${v.hint}` : "";
+      while (true) {
+        const answer = await new Promise((resolve) => {
+          let resolved = false;
+          const done = (val) => {
+            if (!resolved) {
+              resolved = true;
+              resolve(val);
+            }
+          };
+          this.rl.question(`  ${name}${hint}: `, (ans) => done(ans.trim() || null));
+          this.rl.once("close", () => done(null));
+        });
+        const value = answer ?? v.default ?? null;
+        if (!value && v.required) {
+          process.stderr.write(`  ${name} is required
+`);
+          continue;
+        }
+        if (value) {
+          if (v.type === "enum" && v.enum && !v.enum.includes(value)) {
+            process.stderr.write(`  Must be one of: ${v.enum.join(", ")}
+`);
+            continue;
+          }
+          result[name] = value;
+        }
+        break;
+      }
+    }
+    return result;
+  }
+  // ── Free mode ─────────────────────────────────────────────────────────
+  async freeLoop() {
+    const prompt = `${this.colorize(this.opts.prompt)} > `;
+    this.rl.setPrompt(prompt);
+    this.rl.prompt();
+    for await (const line of this.rl) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        this.rl.prompt();
+        continue;
+      }
+      if (this.opts.exitCommands.includes(trimmed)) break;
+      const tokens = tokenize(trimmed);
+      try {
+        await this.root._execute(tokens);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : err}
+`);
+      }
+      this.rl.prompt();
+    }
+  }
+  // ── Helpers ───────────────────────────────────────────────────────────
+  colorize(text) {
+    const c = this.opts.promptColor;
+    if (!c || !process.stdout.isTTY) return text;
+    try {
+      if (c.startsWith("#")) return import_cosmetic2.default.hex(c).encoder(text);
+      if (/^\d+$/.test(c)) return import_cosmetic2.default.xterm(Number(c)).encoder(text);
+      const style = import_cosmetic2.default[c];
+      if (style && typeof style.encoder === "function") return style.encoder(text);
+    } catch {
+    }
+    return text;
   }
 };
+function tokenize(line) {
+  const tokens = [];
+  let current = "";
+  let inQuote = null;
+  for (const ch of line) {
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === " " || ch === "	") {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function buildTokens(cmd, vars) {
+  if (!cmd.variables) return [];
+  return cmd.variables.map((v) => vars[v.name ?? ""]).filter((v) => v !== void 0 && v !== "");
+}
+function makeCompleter(root) {
+  return (line) => {
+    const tokens = tokenize(line);
+    let cmd = root;
+    for (const token of tokens.slice(0, -1)) {
+      const sub = cmd.commandsArray.find((c) => c.name === token);
+      if (!sub) break;
+      cmd = sub;
+    }
+    const partial = tokens[tokens.length - 1] ?? "";
+    const names = [...cmd.commandsArray.map((c) => c.name ?? "").filter(Boolean), "help"];
+    const hits = names.filter((n) => n.startsWith(partial));
+    return [hits.length ? hits : names, partial];
+  };
+}
 
 // src/models/Bar.ts
-var Bar = class {
-  constructor(options = {}) {
+var _Bar = class _Bar {
+  constructor(text, options) {
     // used by MultiBar — not intended for direct external use
     this._isManaged = false;
     this._managedFinalLine = null;
@@ -1060,37 +1293,38 @@ var Bar = class {
     this._tickCount = 0;
     this._startTime = null;
     this._etaSuffix = "";
+    const opts = typeof text === "string" ? { ...options, text } : text ?? {};
     this.running = false;
     this.forwardMotion = true;
-    this._autoLength = options.length === void 0;
-    this.length = options.length ?? process.stdout.columns ?? 80;
-    this.prefixString = options.prefix ?? "[";
-    this.suffixString = options.suffix ?? "]";
-    this.character = options.character ?? "\u2500\u2500";
-    this.beforeEmpty = options.before ?? " ";
-    this.afterEmpty = options.after ?? " ";
+    this._autoLength = opts.length === void 0;
+    this.length = opts.length ?? process.stdout.columns ?? 80;
+    this.prefixString = opts.prefix ?? "[";
+    this.suffixString = opts.suffix ?? "]";
+    this.character = opts.character ?? "\u2500\u2500";
+    this.beforeEmpty = opts.before ?? " ";
+    this.afterEmpty = opts.after ?? " ";
     this.position = 1;
-    this.interval = options.interval ?? 35;
-    this.mode = options.mode ?? "bounce";
-    this.progress = options.progress;
-    this.colorFill = options.colorFill ?? false;
-    this.colorCycle = options.colorCycle ?? 0.5;
-    this.shimmer = options.shimmer ?? 0;
-    this.text = options.text ?? "";
-    this.reverse = options.reverse ?? false;
-    this.onBounce = options.onBounce;
-    this.onLoop = options.onLoop;
-    this.onComplete = options.onComplete;
-    this.colors = options.colors ?? ["#c026d3", "#e879f9"];
-    this.bgColors = options.bgColors ?? [];
-    this._successColor = options.successColor ?? GREEN;
-    this._failColor = options.failColor ?? RED;
-    this._warnColor = options.warnColor ?? YELLOW;
-    this._infoColor = options.infoColor ?? BLUE;
-    this._glyphs = options.glyphs ?? true;
-    this._showRate = options.showRate ?? false;
-    this._showEta = options.showEta ?? false;
-    this._rateUnit = options.rateUnit ?? "";
+    this.interval = opts.interval ?? 35;
+    this.mode = opts.mode ?? "bounce";
+    this.progress = opts.progress;
+    this.colorFill = opts.colorFill ?? false;
+    this.colorCycle = opts.colorCycle ?? 0.5;
+    this.shimmer = opts.shimmer ?? 0;
+    this.text = opts.text ?? "";
+    this.reverse = opts.reverse ?? false;
+    this.onBounce = opts.onBounce;
+    this.onLoop = opts.onLoop;
+    this.onComplete = opts.onComplete;
+    this.colors = opts.colors ?? ["#c026d3", "#e879f9"];
+    this.bgColors = opts.bgColors ?? [];
+    this._successColor = opts.successColor ?? GREEN;
+    this._failColor = opts.failColor ?? RED;
+    this._warnColor = opts.warnColor ?? YELLOW;
+    this._infoColor = opts.infoColor ?? BLUE;
+    this._glyphs = opts.glyphs ?? true;
+    this._showRate = opts.showRate ?? false;
+    this._showEta = opts.showEta ?? false;
+    this._rateUnit = opts.rateUnit ?? "";
   }
   get colors() {
     return this._colors;
@@ -1139,6 +1373,7 @@ var Bar = class {
     if (this._isManaged) return;
     if (!process.stdout.isTTY) return;
     this.running = true;
+    _Bar.current = this;
     process.stdout.write(HIDE_CURSOR);
     this._cleanupDeregister = registerCleanup(() => {
       this.running = false;
@@ -1164,6 +1399,7 @@ var Bar = class {
       this._managedFinalLine = message ?? "";
       return this;
     }
+    if (_Bar.current === this) _Bar.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -1178,10 +1414,18 @@ var Bar = class {
 `);
     return this;
   }
-  message(string) {
+  update(string) {
     this.text = string;
     return this;
   }
+  log(message, glyph = `${FAINT}\xB7${RESET}`) {
+    if (process.stdout.isTTY) {
+      this.clear();
+    }
+    process.stdout.write(`${glyph ? `${glyph} ` : ""}${message}
+`);
+    return this;
+  }
   track(total, options) {
     this._total = total;
     this._tickCount = 0;
@@ -1228,6 +1472,7 @@ var Bar = class {
   }
   succeed(string) {
     this.running = false;
+    if (_Bar.current === this) _Bar.current = null;
     if (this._isManaged) {
       const glyph = this._glyphs ? colorText(this._successColor, "\u2714") + " " : "";
       this._managedFinalLine = `${glyph}${string ?? ""}`;
@@ -1251,6 +1496,7 @@ var Bar = class {
   }
   fail(string) {
     this.running = false;
+    if (_Bar.current === this) _Bar.current = null;
     if (this._isManaged) {
       const glyph = this._glyphs ? colorText(this._failColor, "\u2716") + " " : "";
       this._managedFinalLine = `${glyph}${string ?? ""}`;
@@ -1274,6 +1520,7 @@ var Bar = class {
   }
   warn(string) {
     this.running = false;
+    if (_Bar.current === this) _Bar.current = null;
     if (this._isManaged) {
       const glyph = this._glyphs ? colorText(this._warnColor, "\u26A0") + " " : "";
       this._managedFinalLine = `${glyph}${string ?? ""}`;
@@ -1297,6 +1544,7 @@ var Bar = class {
   }
   info(string) {
     this.running = false;
+    if (_Bar.current === this) _Bar.current = null;
     if (this._isManaged) {
       const glyph = this._glyphs ? colorText(this._infoColor, "\u2139") + " " : "";
       this._managedFinalLine = `${glyph}${string ?? ""}`;
@@ -1464,7 +1712,8 @@ var Bar = class {
     }, this.interval);
   }
 };
-Bar.COLORS = {
+_Bar.current = null;
+_Bar.COLORS = {
   blueRed: ["#0000ff", "#ff0000"],
   redBlue: ["#ff0000", "#0000ff"],
   rainbow: ["#ff0000", "#ff7f00", "#ffff00", "#00ff00", "#0000ff", "#8b00ff"],
@@ -1472,6 +1721,7 @@ Bar.COLORS = {
   cool: ["#00ffff", "#0000ff", "#8b00ff"],
   sunset: ["#8b00ff", "#ff0000", "#ff7f00"]
 };
+var Bar = _Bar;
 
 // src/models/Chart.ts
 var Chart_exports = {};
@@ -1483,7 +1733,7 @@ __export(Chart_exports, {
   Sparkline: () => Sparkline,
   VerticalBar: () => VerticalBar
 });
-var import_cosmetic2 = __toESM(require("cosmetic"));
+var import_cosmetic3 = __toESM(require("cosmetic"));
 
 // src/utils/padLeft.ts
 var padLeft = (string, padding) => {
@@ -1504,9 +1754,9 @@ function formatNum(n) {
 }
 function applyConfigColor(s) {
   const c = config.color;
-  if (typeof c === "number") return import_cosmetic2.default.xterm(c).encoder(s);
-  if (c.startsWith("#")) return import_cosmetic2.default.hex(c).encoder(s);
-  return import_cosmetic2.default[c].encoder(s);
+  if (typeof c === "number") return import_cosmetic3.default.xterm(c).encoder(s);
+  if (c.startsWith("#")) return import_cosmetic3.default.hex(c).encoder(s);
+  return import_cosmetic3.default[c].encoder(s);
 }
 function applyPadding(str, paddingX, paddingY) {
   const lines = str.split("\n");
@@ -1532,7 +1782,7 @@ var Bar2 = class {
     const cols = options.width ?? process.stdout.columns ?? 80;
     const available = cols - maxKeyLen - maxValueLen - 3;
     const scale = maxValue > 0 && available > 0 ? available / maxValue : 0;
-    const encodeKey = (s) => typeof config.color === "number" ? import_cosmetic2.default.xterm(config.color).encoder(s) : config.color.startsWith("#") ? import_cosmetic2.default.hex(config.color).encoder(s) : import_cosmetic2.default[config.color].encoder(s);
+    const encodeKey = (s) => typeof config.color === "number" ? import_cosmetic3.default.xterm(config.color).encoder(s) : config.color.startsWith("#") ? import_cosmetic3.default.hex(config.color).encoder(s) : import_cosmetic3.default[config.color].encoder(s);
     for (const item of data) {
       if (!item) {
         this.string += "\n";
@@ -1542,7 +1792,7 @@ var Bar2 = class {
       const keyPart = (rawKey ? encodeKey(rawKey) : "") + " ".repeat(maxKeyLen - stringLength(rawKey));
       const barWidth = Math.max(1, Math.floor(item.value * scale));
       let bar = (item.character ?? " ").repeat(barWidth);
-      bar = item.style ? item.style(bar) : import_cosmetic2.default.background.white.encoder(bar);
+      bar = item.style ? item.style(bar) : import_cosmetic3.default.background.white.encoder(bar);
       this.string += `${keyPart}|${bar} ${item.value}
 `;
     }
@@ -1591,7 +1841,7 @@ var VerticalBar = class {
     }
     this.string += "\u2500".repeat(data.length * colWidth) + "\n";
     if (data.some((item) => item?.key)) {
-      const encodeLabel = (s) => typeof config.color === "number" ? import_cosmetic2.default.xterm(config.color).encoder(s) : config.color.startsWith("#") ? import_cosmetic2.default.hex(config.color).encoder(s) : import_cosmetic2.default[config.color].encoder(s);
+      const encodeLabel = (s) => typeof config.color === "number" ? import_cosmetic3.default.xterm(config.color).encoder(s) : config.color.startsWith("#") ? import_cosmetic3.default.hex(config.color).encoder(s) : import_cosmetic3.default[config.color].encoder(s);
       let labels = "";
       for (const item of data) {
         if (!item?.key) {
@@ -1995,7 +2245,7 @@ var MultiBar = class {
     this._interval = options.interval ?? 35;
   }
   // Add a bar to the group. Must be called before start().
-  // Returns the Bar instance — use .message(), .progress, .tick(), .succeed(), etc.
+  // Returns the Bar instance — use .update(), .progress, .tick(), .succeed(), etc.
   add(options = {}) {
     const bar = new Bar(options);
     bar._isManaged = true;
@@ -2091,7 +2341,7 @@ var MultiSelect = class {
     const checked = /* @__PURE__ */ new Set();
     let error = null;
     let lastDrawnLines = 0;
-    process.stdout.write(HIDE_CURSOR);
+    process.stdout.write(HIDE_CURSOR + DISABLE_WRAP);
     const glyph = this.promptGlyph ? `${colorText(this.promptColor, this.promptGlyph)} ` : "";
     const indent = " ".repeat(this.promptGlyph ? stringLength(this.promptGlyph) + 1 : 0);
     process.stdout.write(`${glyph}${prompt}
@@ -2101,16 +2351,26 @@ var MultiSelect = class {
       const q = searchQuery.toLowerCase();
       return items.map((item, i) => ({ item, originalIndex: i })).filter(({ item }) => item.label.toLowerCase().includes(q) || (item.description?.toLowerCase().includes(q) ?? false));
     };
+    const computeMaxHeight = () => {
+      const termRows = process.stdout.rows ?? 24;
+      const reserved = 1 + (this.searchEnabled ? 1 : 0) + 1 + 1;
+      const fit = Math.max(1, termRows - reserved - 1);
+      return this.maxHeight ? Math.min(this.maxHeight, fit) : fit;
+    };
     const renderList = (redraw) => {
       const filtered = getFiltered();
       if (cursor >= filtered.length) cursor = Math.max(0, filtered.length - 1);
-      if (this.maxHeight) {
+      const maxHeight = computeMaxHeight();
+      const useViewport = filtered.length > maxHeight;
+      if (useViewport) {
         if (cursor < viewportOffset) viewportOffset = cursor;
-        else if (cursor >= viewportOffset + this.maxHeight) viewportOffset = cursor - this.maxHeight + 1;
-        viewportOffset = Math.max(0, Math.min(viewportOffset, Math.max(0, filtered.length - this.maxHeight)));
+        else if (cursor >= viewportOffset + maxHeight) viewportOffset = cursor - maxHeight + 1;
+        viewportOffset = Math.max(0, Math.min(viewportOffset, Math.max(0, filtered.length - maxHeight)));
+      } else {
+        viewportOffset = 0;
       }
-      const visibleStart = this.maxHeight ? viewportOffset : 0;
-      const visibleEnd = this.maxHeight ? Math.min(filtered.length, viewportOffset + this.maxHeight) : filtered.length;
+      const visibleStart = useViewport ? viewportOffset : 0;
+      const visibleEnd = useViewport ? Math.min(filtered.length, viewportOffset + maxHeight) : filtered.length;
       if (redraw) {
         if (lastDrawnLines > 0) process.stdout.write(CURSOR_UP3(lastDrawnLines));
         process.stdout.write("\r\x1B[0J");
@@ -2126,14 +2386,15 @@ var MultiSelect = class {
         const { item, originalIndex } = filtered[vi];
         const isCursor = vi === cursor;
         const isChecked = checked.has(originalIndex);
+        const numStr = `${vi + 1}.`;
         const desc = item.description ? ` ${colorText(this.descriptionColor, `\u2014 ${item.description}`)}` : "";
         const checkMark = isChecked ? pulse ? `${pulse}${this.checkedPrefix}${RESET}` : colorText(this.promptColor, this.checkedPrefix) : this.uncheckedPrefix;
         const label = isCursor ? pulse ? `${pulse}${item.label}${RESET}` : colorText(this.promptColor, item.label) : item.label;
-        process.stdout.write(`\r${indent}${checkMark} ${label}${desc}
+        process.stdout.write(`\r${indent}${numStr} ${checkMark} ${label}${desc}
 `);
         lastDrawnLines++;
       }
-      const hintContent = `\u2191\u2193 move  space/tab toggle  \u2190\u2192 deselect/select${this.searchEnabled ? "  type to filter" : "  a all"}  enter confirm`;
+      const hintContent = `\u2191\u2193 move  space/tab toggle  \u2190\u2192 deselect/select${this.searchEnabled ? "  type to filter" : "  1-9 jump  a all"}  enter confirm`;
       const maxHintCols = Math.max(10, (process.stdout.columns ?? 80) - stringLength(indent) - 1);
       const hint = stringLength(hintContent) > maxHintCols ? hintContent.slice(0, maxHintCols) : hintContent;
       process.stdout.write(`\r${indent}${DIM2}${hint}${RESET}
@@ -2156,7 +2417,7 @@ var MultiSelect = class {
         process.stdin.setRawMode(false);
         process.stdin.pause();
         process.stdin.removeListener("data", onKey);
-        process.stdout.write(SHOW_CURSOR);
+        process.stdout.write(ENABLE_WRAP + SHOW_CURSOR);
       });
       const cleanup = (result) => {
         deregisterCleanup();
@@ -2166,6 +2427,7 @@ var MultiSelect = class {
         }
         if (lastDrawnLines > 0) process.stdout.write(CURSOR_UP3(lastDrawnLines));
         process.stdout.write("\x1B[0J");
+        process.stdout.write(ENABLE_WRAP);
         const bulletWidth = stringLength(this.checkedPrefix) + 1;
         for (let i = 0; i < items.length; i++) {
           const item = items[i];
@@ -2177,7 +2439,7 @@ var MultiSelect = class {
         process.stdin.setRawMode(false);
         process.stdin.pause();
         process.stdin.removeListener("data", onKey);
-        process.stdout.write(SHOW_CURSOR);
+        process.stdout.write(ENABLE_WRAP + SHOW_CURSOR);
         resolve(result);
       };
       if (this._parsedColors.length >= 2) {
@@ -2266,7 +2528,7 @@ var MultiSelect = class {
           process.stdin.setRawMode(false);
           process.stdin.pause();
           process.stdin.removeListener("data", onKey);
-          process.stdout.write(SHOW_CURSOR);
+          process.stdout.write(ENABLE_WRAP + SHOW_CURSOR);
           process.exit(130);
         } else if (this.searchEnabled) {
           if (str === "\x7F" || str === "\b") {
@@ -2286,7 +2548,7 @@ var MultiSelect = class {
           const n = parseInt(str);
           if (!isNaN(n) && n >= 1 && n <= Math.min(filtered.length, 9)) {
             error = null;
-            cursor = viewportOffset + n - 1;
+            cursor = n - 1;
             renderList(true);
           }
         }
@@ -2463,7 +2725,7 @@ async function scrollbox(lines, options) {
 
 // src/models/Spinner.ts
 var _Spinner = class _Spinner {
-  constructor(options = {}) {
+  constructor(text, options) {
     this._colors = [];
     this._parsedColors = [];
     this._bgColors = [];
@@ -2472,24 +2734,25 @@ var _Spinner = class _Spinner {
     this._shimmerPhase = 0;
     this._lastLineLength = 0;
     this._cleanupDeregister = null;
+    const opts = typeof text === "string" ? { ...options, text } : text ?? {};
     this.running = false;
     this.frameIndex = 0;
-    this.frames = options.frames ?? (config.glyphs ? _Spinner.FRAMES.braille : _Spinner.FRAMES.line);
-    this.prefixString = options.prefix ?? "";
-    this.suffixString = options.suffix ?? "";
-    this.text = options.text ?? "";
-    this.reverse = options.reverse ?? false;
-    this.interval = options.interval ?? 80;
-    this.colorCycle = options.colorCycle ?? 1;
-    this.shimmer = options.shimmer ?? 0;
-    this.onSpin = options.onSpin;
-    this.colors = options.colors ?? ["#c026d3", "#e879f9"];
-    this.bgColors = options.bgColors ?? [];
-    this._successColor = options.successColor ?? GREEN;
-    this._failColor = options.failColor ?? RED;
-    this._warnColor = options.warnColor ?? YELLOW;
-    this._infoColor = options.infoColor ?? BLUE;
-    this._glyphs = options.glyphs ?? config.glyphs;
+    this.frames = opts.frames ?? (config.glyphs ? _Spinner.FRAMES.braille : _Spinner.FRAMES.line);
+    this._prefix = opts.prefix ?? "";
+    this._suffix = opts.suffix ?? "";
+    this.text = opts.text ?? "";
+    this.reverse = opts.reverse ?? false;
+    this.interval = opts.interval ?? 80;
+    this.colorCycle = opts.colorCycle ?? 1;
+    this.shimmer = opts.shimmer ?? 0;
+    this.onSpin = opts.onSpin;
+    this.colors = opts.colors ?? ["#c026d3", "#e879f9"];
+    this.bgColors = opts.bgColors ?? [];
+    this._successColor = opts.successColor ?? GREEN;
+    this._failColor = opts.failColor ?? RED;
+    this._warnColor = opts.warnColor ?? YELLOW;
+    this._infoColor = opts.infoColor ?? BLUE;
+    this._glyphs = opts.glyphs ?? config.glyphs;
   }
   get colors() {
     return this._colors;
@@ -2508,6 +2771,7 @@ var _Spinner = class _Spinner {
   start() {
     if (!process.stdout.isTTY) return;
     this.running = true;
+    _Spinner.current = this;
     process.stdout.write(HIDE_CURSOR);
     this._cleanupDeregister = registerCleanup(() => {
       this.running = false;
@@ -2518,6 +2782,7 @@ var _Spinner = class _Spinner {
   }
   stop(message) {
     this.running = false;
+    if (_Spinner.current === this) _Spinner.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -2532,8 +2797,17 @@ var _Spinner = class _Spinner {
     this.text = string;
     return this;
   }
+  prefix(string) {
+    this._prefix = string;
+    return this;
+  }
+  suffix(string) {
+    this._suffix = string;
+    return this;
+  }
   succeed(string) {
     this.running = false;
+    if (_Spinner.current === this) _Spinner.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -2549,6 +2823,7 @@ var _Spinner = class _Spinner {
   }
   fail(string) {
     this.running = false;
+    if (_Spinner.current === this) _Spinner.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -2564,6 +2839,7 @@ var _Spinner = class _Spinner {
   }
   warn(string) {
     this.running = false;
+    if (_Spinner.current === this) _Spinner.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -2579,6 +2855,7 @@ var _Spinner = class _Spinner {
   }
   info(string) {
     this.running = false;
+    if (_Spinner.current === this) _Spinner.current = null;
     this._cleanupDeregister?.();
     this._cleanupDeregister = null;
     if (process.stdout.isTTY) {
@@ -2614,9 +2891,9 @@ var _Spinner = class _Spinner {
   }
   run() {
     const frame = this.coloredFrame();
-    const t = this.text;
-    const content = this.reverse ? t ? `${t} ${frame}` : frame : t ? `${frame} ${t}` : frame;
-    const raw = `${this.prefixString}${content}${this.suffixString}`;
+    const label = [this._prefix, this.text, this._suffix].filter(Boolean).join(" ");
+    const content = this.reverse ? label ? `${label} ${frame}` : frame : label ? `${frame} ${label}` : frame;
+    const raw = content;
     const displayLen = stringLength(raw);
     const padding = " ".repeat(Math.max(0, this._lastLineLength - displayLen));
     this._lastLineLength = displayLen;
@@ -2634,6 +2911,7 @@ var _Spinner = class _Spinner {
     }, this.interval);
   }
 };
+_Spinner.current = null;
 _Spinner.FRAMES = {
   braille: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
   dots: ["\u28FE", "\u28FD", "\u28FB", "\u28BF", "\u287F", "\u28DF", "\u28EF", "\u28F7"],
@@ -2644,7 +2922,7 @@ _Spinner.FRAMES = {
 var Spinner = _Spinner;
 
 // src/models/Table.ts
-var import_cosmetic3 = __toESM(require("cosmetic"));
+var import_cosmetic4 = __toESM(require("cosmetic"));
 
 // src/utils/padSides.ts
 var padSides = (string, padding) => {
@@ -2722,7 +3000,7 @@ var Table = class {
       header += pad(column.title, column.padding + this.margin);
       if (i < keys.length - 1) header += this.separator;
     }
-    const styled = typeof config.color === "number" ? import_cosmetic3.default.xterm(config.color) : config.color.startsWith("#") ? import_cosmetic3.default.hex(config.color) : import_cosmetic3.default[config.color];
+    const styled = typeof config.color === "number" ? import_cosmetic4.default.xterm(config.color) : config.color.startsWith("#") ? import_cosmetic4.default.hex(config.color) : import_cosmetic4.default[config.color];
     this.string += `${styled.underline.encoder(header)}
 `;
     for (const [ri, row] of this.rows.entries()) {
@@ -2793,13 +3071,13 @@ _TermKit.commandDefaults = {};
 var TermKit = _TermKit;
 
 // src/index.ts
-var import_cosmetic4 = __toESM(require("cosmetic"));
+var import_cosmetic5 = __toESM(require("cosmetic"));
 var base = null;
 var commandDefaults = {};
 var Program = {
   command: (name, variables, info) => {
     const cmd = new Command(Object.assign({ name, variables, info }, commandDefaults));
-    if (!base) base = cmd;
+    base = cmd;
     return cmd;
   },
   option: (short, long, variables, info) => new Option({ short, long, variables, info }),
@@ -2822,6 +3100,10 @@ var Program = {
   },
   setDefaults: (data) => {
     commandDefaults = data;
+  },
+  shell: async (options) => {
+    if (!base) throw new Error("No command defined");
+    return new Shell(base, options).run();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -2839,6 +3121,7 @@ var Program = {
   Program,
   Scrollbox,
   Select,
+  Shell,
   Spinner,
   Table,
   TermKit,