nugit-cli 0.0.1 → 0.1.0

package/src/stack-view/run-view-entry.js

@@ -0,0 +1,119 @@
+import fs from "fs";
+import { findGitRoot, stackJsonPath } from "../nugit-stack.js";
+import { runStackViewCommand } from "./run-stack-view.js";
+import { runRepoPickerFlow } from "./view-repo-picker-ink.js";
+import { RepoPickerBackError } from "./repo-picker-back.js";
+import { enterAlternateScreen, leaveAlternateScreen } from "./terminal-fullscreen.js";
+import { getRepoFullNameFromGitRoot } from "../git-info.js";
+
+/**
+ * @param {boolean} noTui
+ * @param {() => Promise<void>} fn
+ */
+async function withViewFullscreen(noTui, fn) {
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty && !noTui) {
+    enterAlternateScreen(process.stdout);
+    try {
+      await fn();
+    } finally {
+      leaveAlternateScreen(process.stdout);
+    }
+  } else {
+    await fn();
+  }
+}
+
+/**
+ * Resolve CLI args and open the stack viewer (local file, remote repo, or picker TUI).
+ * @param {string | undefined} repoPos
+ * @param {string | undefined} refPos
+ * @param {{ noTui?: boolean, repo?: string, ref?: string, file?: string, reviewAutoapply?: boolean }} opts
+ */
+export async function runNugitViewEntry(repoPos, refPos, opts) {
+  if (opts.file) {
+    await withViewFullscreen(!!opts.noTui, () =>
+      runStackViewCommand({ file: opts.file, noTui: opts.noTui })
+    );
+    return;
+  }
+
+  const explicitRepo = (repoPos && String(repoPos).trim()) || (opts.repo && String(opts.repo).trim()) || "";
+  const explicitRef = (refPos && String(refPos).trim()) || (opts.ref && String(opts.ref).trim()) || "";
+
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+
+  if (!tty || opts.noTui) {
+    if (explicitRepo) {
+      await withViewFullscreen(!!opts.noTui, () =>
+        runStackViewCommand({
+          repo: explicitRepo,
+          ref: explicitRef || undefined,
+          noTui: opts.noTui,
+          reviewAutoapply: opts.reviewAutoapply
+        })
+      );
+      return;
+    }
+
+    const root = findGitRoot();
+    if (root && fs.existsSync(stackJsonPath(root))) {
+      await withViewFullscreen(!!opts.noTui, () =>
+        runStackViewCommand({ noTui: opts.noTui, reviewAutoapply: opts.reviewAutoapply })
+      );
+      return;
+    }
+
+    throw new Error(
+      "nugit view: pass owner/repo and optional ref, use --file, run inside a repo with .nugit/stack.json, or use a TTY for the repo picker. " +
+        "Sign in with `nugit auth login` or set NUGIT_USER_TOKEN when GitHub returns 401."
+    );
+  }
+
+  /** @type {string | null} */
+  let autoRepo = null;
+  if (explicitRepo) {
+    autoRepo = explicitRepo;
+  } else {
+    const root = findGitRoot();
+    if (root) {
+      try {
+        autoRepo = getRepoFullNameFromGitRoot(root);
+      } catch {
+        autoRepo = null;
+      }
+    }
+  }
+
+  await withViewFullscreen(false, async () => {
+    let firstRun = true;
+    for (;;) {
+      let useRepo;
+      if (firstRun && autoRepo) {
+        useRepo = autoRepo;
+      } else {
+        const picked = await runRepoPickerFlow();
+        if (!picked) {
+          return;
+        }
+        useRepo = picked.repo;
+      }
+      firstRun = false;
+      try {
+        await runStackViewCommand({
+          repo: useRepo,
+          ref: (useRepo === explicitRepo && explicitRef) ? explicitRef : undefined,
+          noTui: false,
+          reviewAutoapply: opts.reviewAutoapply,
+          allowBackToRepoPicker: true
+        });
+        break;
+      } catch (e) {
+        if (e instanceof RepoPickerBackError) {
+          continue;
+        }
+        throw e;
+      }
+    }
+  });
+}

package/src/stack-view/sgr-mouse.js

@@ -0,0 +1,56 @@
+/**
+ * xterm SGR mouse protocol (CSI ?1006 h).
+ * Sequence: ESC [ < Pb ; Px ; Py M  (press) or m (release)
+ * Px = column (1-based), Py = row (1-based).
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+ */
+
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
+
+/**
+ * @param {string} input
+ * @returns {{ button: number, col: number, row: number, release: boolean } | null}
+ */
+export function parseSgrMouse(input) {
+  if (typeof input !== "string" || !input.startsWith("\x1b[<")) {
+    return null;
+  }
+  const m = SGR_MOUSE_RE.exec(input);
+  if (!m) {
+    return null;
+  }
+  const button = Number.parseInt(m[1], 10);
+  const col = Number.parseInt(m[2], 10);
+  const row = Number.parseInt(m[3], 10);
+  const release = m[4] === "m";
+  return { button, col, row, release };
+}
+
+/** Wheel (motion bit 32 may be set by some terminals). */
+export function isWheelUp(btn) {
+  return (btn & ~32) === 64;
+}
+
+export function isWheelDown(btn) {
+  return (btn & ~32) === 65;
+}
+
+/**
+ * @param {import('node:stream').Writable} stdout
+ */
+export function enableSgrMouse(stdout) {
+  if (!stdout?.isTTY) {
+    return;
+  }
+  stdout.write("\x1b[?1000h\x1b[?1002h\x1b[?1006h");
+}
+
+/**
+ * @param {import('node:stream').Writable} stdout
+ */
+export function disableSgrMouse(stdout) {
+  if (!stdout?.isTTY) {
+    return;
+  }
+  stdout.write("\x1b[?1006l\x1b[?1002l\x1b[?1000l");
+}

package/src/stack-view/stack-branch-graph.js

@@ -0,0 +1,95 @@
+import chalk from "chalk";
+
+/**
+ * Compact ASCII “git graph” for stacked PRs (linear chain), aligned with row index.
+ * Tip is drawn first (top); base last (bottom). Selection uses a filled node + branch tint.
+ *
+ * @param {Array<{ entry: { pr_number: number }, pull?: unknown }>} rows
+ * @param {number} selectedIndex
+ * @param {number} maxLines
+ * @param {number} w
+ * @param {{ muted?: boolean, fullBranchNames?: boolean }} [opts] muted = dim stack-picker cards; fullBranchNames = no ellipsis (stack picker)
+ * @returns {string[]}
+ */
+export function buildStackBranchGraphLines(rows, selectedIndex, maxLines, w, opts) {
+  const muted = opts?.muted === true;
+  const fullBranchNames = opts?.fullBranchNames === true;
+  const n = rows.length;
+  if (n === 0) return [];
+
+  const labels = rows.map((r) => {
+    const pull = r.pull && typeof r.pull === "object" ? /** @type {Record<string, unknown>} */ (r.pull) : {};
+    const head = pull.head && typeof pull.head === "object" ? /** @type {Record<string, unknown>} */ (pull.head) : {};
+    const href = typeof head.ref === "string" ? head.ref : "";
+    const refLabel = fullBranchNames ? href : href.length > 10 ? `${href.slice(0, 9)}\u2026` : href;
+    return { pr: r.entry.pr_number, ref: refLabel };
+  });
+
+  /** @type {string[]} */
+  const out = [];
+  const tailChalk = muted ? (/** @param {string} s */ (s) => chalk.gray.dim(s)) : chalk.white;
+
+  for (let i = n - 1; i >= 0; i--) {
+    const sel = !muted && i === selectedIndex;
+    const node = muted
+      ? chalk.gray.dim("\u25cb")
+      : sel
+        ? chalk.yellow("\u25cf")
+        : chalk.gray("\u25cb");
+    /** @type {string} */
+    let prefix;
+    if (i === n - 1) {
+      if (n === 1) {
+        prefix = "  ";
+      } else if (muted) {
+        prefix = chalk.gray("\u2502 ");
+      } else {
+        prefix = sel ? chalk.yellow("\u2502 ") : chalk.gray("\u2502 ");
+      }
+    } else if (i === 0) {
+      prefix = muted ? chalk.gray("\u2514\u2500") : sel ? chalk.yellow("\u2514\u2500") : chalk.gray("\u2514\u2500");
+    } else {
+      prefix = muted ? chalk.gray("\u2502 ") : sel ? chalk.yellow("\u2502 ") : chalk.gray("\u2502 ");
+    }
+    const prefixPlain = stripAnsi(prefix).length;
+    const nodePlain = stripAnsi(node).length;
+    const budget = Math.max(4, w - prefixPlain - nodePlain - 1);
+    const tailPlain = `#${labels[i].pr}${labels[i].ref ? " " + labels[i].ref : ""}`;
+    const tailOut = fullBranchNames ? tailPlain : truncPlain(tailPlain, budget);
+    const line = `${prefix}${node} ${tailChalk(tailOut)}`;
+    out.push(line);
+    if (out.length >= maxLines) break;
+  }
+
+  return out;
+}
+
+/**
+ * Map a discovery stack’s `prs` (position-sorted, base → tip) to rows for {@link buildStackBranchGraphLines}.
+ *
+ * @param {{ prs?: { pr_number: number, head_branch?: string }[] }} stack
+ * @returns {Array<{ entry: { pr_number: number }, pull: { head: { ref: string } } }>}
+ */
+export function discoveryPrsToGraphRows(stack) {
+  const prs = stack && Array.isArray(stack.prs) ? stack.prs : [];
+  return prs.map((p) => ({
+    entry: { pr_number: p.pr_number },
+    pull: { head: { ref: typeof p.head_branch === "string" ? p.head_branch : "" } }
+  }));
+}
+
+/**
+ * @param {string} s
+ */
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * @param {string} s
+ * @param {number} w
+ */
+function truncPlain(s, w) {
+  if (s.length <= w) return s;
+  return s.slice(0, Math.max(0, w - 1)) + "\u2026";
+}

package/src/stack-view/stack-pick-graph.js

@@ -0,0 +1,93 @@
+import chalk from "chalk";
+import { hasPickerViewingContext, pickViewingHighlightIndex } from "./stack-pick-sort.js";
+
+/**
+ * Overview row: nodes for up to 10 stacks; cursor column in yellow; open-in-viewer in cyan (when set).
+ * @param {{ tip_pr_number: number, tip_head_branch?: string }[]} stacks rows shown (often visible subset)
+ * @param {number} selectedIndex cursor (j/k)
+ * @param {number} w
+ * @param {number | null | undefined} [viewingTipPrNumber]
+ * @param {string | null | undefined} [viewingHeadRef] tip branch for matching inferred / discovery rows
+ * @param {unknown[] | null | undefined} [matchContextStacks] full picker list for head-ref disambiguation (defaults to `stacks`)
+ * @returns {string[]}
+ */
+export function buildPickStackOverviewLines(
+  stacks,
+  selectedIndex,
+  w,
+  viewingTipPrNumber,
+  viewingHeadRef,
+  matchContextStacks
+) {
+  const matchCtx = matchContextStacks ?? stacks;
+  if (stacks.length === 0) {
+    return [];
+  }
+  const viewingIdx = pickViewingHighlightIndex(stacks, viewingTipPrNumber, viewingHeadRef, matchCtx);
+  const n = stacks.length;
+  const gap = "   ";
+  /** @type {string[]} */
+  const out = [];
+  const legend = hasPickerViewingContext(viewingTipPrNumber, viewingHeadRef)
+    ? "Yellow = cursor · cyan = open in viewer · gray = other"
+    : "Top stacks by GitHub PR update time — cursor highlights one chain:";
+  out.push(chalk.dim(legend));
+  const nodeParts = [];
+  for (let i = 0; i < n; i++) {
+    const sel = i === selectedIndex;
+    const open = viewingIdx >= 0 && i === viewingIdx;
+    /** @type {string} */
+    let node;
+    if (sel) {
+      node = chalk.yellow("\u25cf ");
+    } else if (open) {
+      node = chalk.cyan("\u25cf ");
+    } else {
+      node = chalk.gray("\u25cb ");
+    }
+    /** @type {string} */
+    let pr;
+    if (sel) {
+      pr = chalk.yellowBright(`#${stacks[i].tip_pr_number}`);
+    } else if (open) {
+      pr = chalk.cyan(`#${stacks[i].tip_pr_number}`);
+    } else {
+      pr = chalk.gray(`#${stacks[i].tip_pr_number}`);
+    }
+    nodeParts.push(node + pr);
+  }
+  const line1 = nodeParts.join(gap);
+  out.push(line1.length > w ? chalk.dim(truncPlain(stripAnsi(line1), w)) : line1);
+  const brParts = [];
+  for (let i = 0; i < n; i++) {
+    const sel = i === selectedIndex;
+    const open = viewingIdx >= 0 && i === viewingIdx;
+    const raw = String(stacks[i].tip_head_branch || "").slice(0, 14);
+    if (sel) {
+      brParts.push(chalk.white(truncPlain(raw, 14)));
+    } else if (open) {
+      brParts.push(chalk.cyan(truncPlain(raw, 14)));
+    } else {
+      brParts.push(chalk.gray(truncPlain(raw, 14)));
+    }
+  }
+  const line2 = brParts.join(gap);
+  out.push(line2.length > w ? chalk.dim(truncPlain(stripAnsi(line2), w)) : line2);
+  return out;
+}
+
+/**
+ * @param {string} s
+ */
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * @param {string} s
+ * @param {number} maxW
+ */
+function truncPlain(s, maxW) {
+  if (s.length <= maxW) return s;
+  return s.slice(0, Math.max(1, maxW - 1)) + "\u2026";
+}

package/src/stack-view/stack-pick-ink.js

@@ -0,0 +1,270 @@
+import React, { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import chalk from "chalk";
+import { buildPickerVisibleStacks, pickViewingHighlightIndex } from "./stack-pick-sort.js";
+import { buildPickStackOverviewLines } from "./stack-pick-graph.js";
+import { buildStackBranchGraphLines, discoveryPrsToGraphRows } from "./stack-branch-graph.js";
+import { stackPickTerminalLayout } from "./stack-pick-layout.js";
+
+const PICKER_GRAPH_MAX = 12;
+
+/**
+ * @param {object} props
+ * @param {{ tip_pr_number: number, tip_head_branch: string, pr_count: number, created_by: string, prs: { pr_number: number, title?: string, head_branch?: string }[], tip_updated_at?: string, inferChainIndex?: number, inferDiffAdd?: number, inferDiffDel?: number, picker_merged_stack?: boolean }[]} props.stacks
+ * @param {(stack: (typeof props.stacks)[0] | null) => void} props.onPick
+ * @param {string} [props.title]
+ * @param {() => void} [props.onRequestBack] Backspace: return to repo picker (infer flow only)
+ * @param {boolean} [props.escapeToRepo] when true with onRequestBack, Esc and q also go to repo (repo-picker loop)
+ * @param {number | null | undefined} [props.viewingTipPrNumber] tip PR# of the stack currently open in the viewer
+ * @param {string | null | undefined} [props.viewingHeadRef] tip branch ref for matching inferred / discovery rows
+ */
+export function StackPickInk({
+  stacks,
+  onPick,
+  title = "Choose stack to view",
+  onRequestBack,
+  escapeToRepo = false,
+  viewingTipPrNumber,
+  viewingHeadRef
+}) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const { cols, innerW } = stackPickTerminalLayout(stdout?.columns);
+
+  const openRows = useMemo(
+    () => stacks.filter((s) => s && typeof s === "object" && s.picker_merged_stack !== true),
+    [stacks]
+  );
+  const closedRows = useMemo(
+    () => stacks.filter((s) => s && typeof s === "object" && s.picker_merged_stack === true),
+    [stacks]
+  );
+
+  const [pickerSection, setPickerSection] = useState(() =>
+    openRows.length > 0 ? "open" : "closed"
+  );
+
+  const activeRows = useMemo(
+    () => (pickerSection === "open" ? openRows : closedRows),
+    [pickerSection, openRows, closedRows]
+  );
+
+  const visible = useMemo(
+    () => buildPickerVisibleStacks(activeRows, { viewingTipPrNumber, viewingHeadRef }),
+    [activeRows, viewingTipPrNumber, viewingHeadRef]
+  );
+
+  const [cursor, setCursor] = useState(0);
+
+  const stacksRef = useRef(stacks);
+  stacksRef.current = stacks;
+
+  useLayoutEffect(() => {
+    const all = stacksRef.current;
+    const openR = all.filter((s) => s && typeof s === "object" && s.picker_merged_stack !== true);
+    const closedR = all.filter((s) => s && typeof s === "object" && s.picker_merged_stack === true);
+    const act = pickerSection === "open" ? openR : closedR;
+    const vis = buildPickerVisibleStacks(act, { viewingTipPrNumber, viewingHeadRef });
+    const hi = pickViewingHighlightIndex(vis, viewingTipPrNumber, viewingHeadRef, all);
+    setCursor(hi >= 0 ? hi : 0);
+    // Only snap when switching tabs or viewer match context — not on every stacks[] identity churn (would break j/k).
+  }, [pickerSection, viewingTipPrNumber, viewingHeadRef]);
+
+  const visibleRef = useRef(visible);
+  visibleRef.current = visible;
+
+  const safe = visible.length ? Math.min(cursor, visible.length - 1) : 0;
+  const safeRef = useRef(safe);
+  safeRef.current = safe;
+
+  const viewingHighlightIdx = useMemo(
+    () => pickViewingHighlightIndex(visible, viewingTipPrNumber, viewingHeadRef, stacks),
+    [visible, viewingTipPrNumber, viewingHeadRef, stacks]
+  );
+
+  const sectionLabel =
+    pickerSection === "open"
+      ? chalk.green("Open stacks")
+      : chalk.gray.dim("Merged / closed (tip PR not open)");
+  const backHint =
+    onRequestBack && escapeToRepo
+      ? " · Esc/Backspace/q: repo list"
+      : onRequestBack
+        ? " · Backspace: repo list · Esc/q: cancel"
+        : " · Esc/q: cancel";
+  const hintLine = `${sectionLabel}${chalk.reset("")} · Tab: switch · Showing ${visible.length} of ${activeRows.length} in tab (${openRows.length} open / ${closedRows.length} merged) · j/k · 1-9 · Enter${backHint}`;
+
+  useInput((input, key) => {
+    const backKey = key.backspace || key.delete || input === "\x7f" || input === "\b";
+    if (backKey && onRequestBack) {
+      onRequestBack();
+      exit();
+      return;
+    }
+    if (input === "q" || key.escape) {
+      if (escapeToRepo && onRequestBack) {
+        onRequestBack();
+      } else {
+        onPick(null);
+      }
+      exit();
+      return;
+    }
+    if (key.tab) {
+      setPickerSection((sec) => {
+        if (sec === "open") {
+          return closedRows.length > 0 ? "closed" : "open";
+        }
+        return openRows.length > 0 ? "open" : "closed";
+      });
+      return;
+    }
+    if (input === "j" || key.downArrow) {
+      setCursor((c) => {
+        const vis = visibleRef.current;
+        const max = Math.max(0, vis.length - 1);
+        return Math.min(c + 1, max);
+      });
+      return;
+    }
+    if (input === "k" || key.upArrow) {
+      setCursor((c) => Math.max(c - 1, 0));
+      return;
+    }
+    if (/^[1-9]$/.test(input)) {
+      const n = Number.parseInt(input, 10) - 1;
+      const vis = visibleRef.current;
+      if (n < vis.length) {
+        onPick(vis[n] ?? null);
+        exit();
+      }
+      return;
+    }
+    if (key.return || input === " ") {
+      const vis = visibleRef.current;
+      if (vis.length === 0) {
+        return;
+      }
+      const i = Math.min(Math.max(0, safeRef.current), vis.length - 1);
+      onPick(vis[i] ?? null);
+      exit();
+    }
+  });
+
+  const overview = buildPickStackOverviewLines(visible, safe, innerW, viewingTipPrNumber, viewingHeadRef, stacks);
+
+  const emptyTab =
+    visible.length === 0
+      ? React.createElement(
+          Text,
+          { color: "gray", dimColor: true },
+          "No stacks in this tab — press Tab to switch."
+        )
+      : null;
+
+  return React.createElement(
+    Box,
+    { flexDirection: "column", padding: 1, width: cols },
+    React.createElement(Text, { color: "cyan", bold: true }, title),
+    React.createElement(Text, { color: "gray" }, hintLine),
+    React.createElement(
+      Box,
+      { flexDirection: "column", marginY: 1, width: cols },
+      ...overview.map((ln, i) => React.createElement(Text, { key: `ov-${i}` }, ln))
+    ),
+    emptyTab,
+    ...visible.map((s, i) => {
+      const sel = i === safe;
+      const isViewing = viewingHighlightIdx >= 0 && i === viewingHighlightIdx;
+      const mark = sel ? "\u25b6 " : "  ";
+      const inferTag =
+        s && typeof s === "object" && (s.inferredOnly || s.inferredFromViewerDoc)
+          ? chalk.dim(" (inferred)")
+          : "";
+      const head =
+        chalk.white(mark) +
+        chalk.yellow("[" + (i + 1) + "]") +
+        " " +
+        (sel ? chalk.yellowBright("tip #" + s.tip_pr_number) : chalk.white("tip #" + s.tip_pr_number)) +
+        inferTag;
+      const graphRows = discoveryPrsToGraphRows(s);
+      const tipIdx = graphRows.length ? graphRows.length - 1 : 0;
+      const graphW = Math.max(10, innerW - 4);
+      const graphMuted = !sel && !isViewing;
+      const graphLines =
+        graphRows.length === 0
+          ? []
+          : buildStackBranchGraphLines(graphRows, tipIdx, PICKER_GRAPH_MAX, graphW, {
+              muted: graphMuted,
+              fullBranchNames: true
+            });
+
+      /** @type {import('react').ReactNode[]} */
+      const diffBlock =
+        typeof s.inferDiffAdd === "number" || typeof s.inferDiffDel === "number"
+          ? [
+              React.createElement(
+                Text,
+                { key: "diff", color: sel ? "white" : "gray" },
+                `${chalk.dim("Lines: ")}${chalk.green("+" + (s.inferDiffAdd ?? 0))} ${chalk.red("-" + (s.inferDiffDel ?? 0))}`
+              )
+            ]
+          : [];
+
+      let core = React.createElement(
+        Box,
+        { flexDirection: "column" },
+        React.createElement(Text, { key: "head" }, head),
+        React.createElement(Text, { key: "pc", color: sel ? "white" : "gray" }, `PR count: ${s.pr_count}`),
+        ...diffBlock,
+        React.createElement(Text, { key: "br", color: sel ? "cyan" : "gray" }, `branch ${s.tip_head_branch}`),
+        React.createElement(Text, { key: "by", color: "gray" }, `by ${s.created_by}`),
+        React.createElement(Text, { key: "lbl", color: sel ? "white" : "gray", dimColor: !sel }, "Branch"),
+        ...graphLines.map((ln, gi) => React.createElement(Text, { key: `br-${gi}` }, ln))
+      );
+
+      if (isViewing) {
+        core = React.createElement(
+          Box,
+          {
+            borderStyle: "round",
+            borderColor: "cyan",
+            paddingLeft: 1,
+            paddingRight: 1,
+            paddingTop: 1,
+            paddingBottom: 1,
+            flexDirection: "column"
+          },
+          React.createElement(Text, { key: "open", color: "cyan" }, "  Open in viewer"),
+          core
+        );
+      }
+
+      if (sel) {
+        core = React.createElement(
+          Box,
+          {
+            borderStyle: "round",
+            borderColor: "yellow",
+            paddingLeft: 1,
+            paddingRight: 1,
+            paddingTop: 1,
+            paddingBottom: 1,
+            flexDirection: "column"
+          },
+          core
+        );
+      }
+
+      return React.createElement(
+        Box,
+        {
+          key: String(s.tip_pr_number) + "-" + i,
+          flexDirection: "column",
+          marginBottom: 1
+        },
+        core
+      );
+    })
+  );
+}

package/src/stack-view/stack-pick-layout.js

@@ -0,0 +1,19 @@
+/**
+ * Stack picker layout derived from the TTY width.
+ *
+ * Previously `Math.max(40, cols - 4)` forced a minimum content width **wider than the
+ * terminal** when `stdout.columns < 44`. Ink then reflowed on every j/k render, so the
+ * title appeared to flash. Moving the cursor also changes which row has bordered Boxes
+ * (padding), which can shift total height slightly. A shared large `minHeight` on every card
+ * was avoided—it caused huge empty gaps between stacks in typical terminals.
+ * Ink `Static` is not used for the title: it only renders newly appended `items` by length,
+ * so a fixed single-item header would disappear after the first frame.
+ *
+ * @param {number | undefined} stdoutColumns
+ * @returns {{ cols: number, innerW: number }}
+ */
+export function stackPickTerminalLayout(stdoutColumns) {
+  const cols = Math.max(20, stdoutColumns ?? 80);
+  const innerW = Math.max(16, cols - 4);
+  return { cols, innerW };
+}