pleumrouter 0.2.2 → 0.3.1

package/README.md

@@ -29,12 +29,17 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 
 | 명령 | 설명 |
 |------|------|
+| `pleum` | (인자 없음, TTY) 인터랙티브 런처 메뉴 — 채팅·에이전트 실행·잔액·리더보드를 키보드·마우스로. ↑/↓·휠 이동 · enter·클릭 실행 · →·우클릭 모델 설정 · esc 종료. 미설치 에이전트는 확인 후 자동 설치, 실행 종료 후 메뉴 복귀. 파이프에선 도움말 출력 |
 | `pleum login [--device]` | 브라우저로 로그인 → CLI가 API 키를 자동 발급·저장(`~/.pleum/config.json`). `--device`는 SSH·CI |
 | `pleum logout` | 저장된 키 삭제 |
 | `pleum launch [tool] [--model id] [-- args]` | 에이전트 실행. `--` 뒤 인자는 도구로 그대로 전달. 도구 생략 시 지원 목록·설치 여부 표시 |
-| `pleum run [model] ["프롬프트"]` | 채팅 — 대화형 REPL, 1회 실행, stdin 파이프. 모델 생략 시 인터랙티브 선택 |
+| `pleum run [model] ["프롬프트"]` | 채팅 — 대화형 REPL, 1회 실행, stdin 파이프. 모델 생략 시 화살표로 선택 |
 | `pleum models [query] [--json]` | 모델 목록(공개) — provider·컨텍스트·가격(₩/1M) 컬럼, `--json`은 스크립트용 |
+| `pleum models <id> --info` | 모델 상세 — 가격·컨텍스트·provider별 지연/처리량/업타임·주간 사용량·형제 모델 |
+| `pleum top [--period daily\|weekly\|monthly]` | 라우터 전체 모델 리더보드 + 제공자 점유율(공개 통계) |
 | `pleum balance` | 크레딧 잔액 조회 |
+| `pleum usage [--by model\|provider\|api_key\|day] [--days N]` | 내 지출 리포트(막대 차트) — 최신 로그인 키 필요(`usage:read`) |
+| `pleum health` | 게이트웨이 연결·DB·Redis·환율·로그인 상태 점검(셀프호스트 진단용) |
 | `pleum completion <zsh\|bash>` | 셸 자동완성 스크립트 출력 |
 | `pleum upgrade` | 최신 버전으로 재설치 |
 | `pleum version` | 버전 출력 |
@@ -46,7 +51,7 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 | 명령 | 설명 |
 |------|------|
 | `/help`, `/?` | 명령 도움말 |
-| `/model [id]` | **세션 유지한 채 모델 전환**(여러 모델을 한 대화에서 비교) |
+| `/model [id]` | **세션 유지한 채 모델 전환**(인자 없으면 화살표 셀렉터) |
 | `/system [텍스트]` | 시스템 프롬프트 설정/확인 |
 | `/clear` | 대화 컨텍스트 초기화 |
 | `/models [검색어]` | 모델 목록 보기 |
@@ -54,9 +59,13 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 | `/verbose` | 토큰·속도 통계 토글 |
 | `/exit`, `/quit` | 종료 |
 
+- 응답은 **마크다운 스트리밍 렌더**(굵게·코드블록 하이라이트·리스트) — 파이프로 빼면 자동으로 원문 그대로
+- 응답 후 비용이 PLM으로 표시(스트리밍 마지막 청크 기준)
+- **Ctrl+C**: 생성 중엔 1회로 중단(대화 유지), 대기 중엔 2초 내 2회로 종료
 - 여러 줄 입력: `"""` 한 줄 → 본문 → `"""` 한 줄
 - 이미지: 메시지에 이미지 파일 경로를 그대로 포함 (예: `이 그림 설명해줘 ./shot.png`)
 - `↑` 로 지난 입력 재호출(히스토리는 `~/.pleum/history`에 영속)
+- 색상 끄기: `NO_COLOR=1` (비TTY·파이프에선 자동 무색)
 
 ## 자동 실행 지원 도구
 

package/bin/pleum.mjs

@@ -5,12 +5,17 @@ import { launch, launchHelp } from "../src/launch.mjs";
 import { run } from "../src/run.mjs";
 import { listModels } from "../src/models.mjs";
 import { balance } from "../src/balance.mjs";
+import { usage } from "../src/usage.mjs";
+import { top } from "../src/top.mjs";
+import { health } from "../src/health.mjs";
 import { completion } from "../src/completion.mjs";
 import { upgrade } from "../src/upgrade.mjs";
 import { clearConfig } from "../src/config.mjs";
+import { mainMenu } from "../src/menu.mjs";
 
 const HELP = `pleum — PleumRouter 터미널 CLI
 
+  pleum                              (인자 없음) 인터랙티브 런처 메뉴 — 키보드·마우스 (TTY 전용)
   pleum login [--device]             브라우저로 로그인 + 키 자동 저장
                                      --device: 브라우저 없는 환경(SSH·CI)
   pleum logout                       저장된 키 삭제
@@ -18,9 +23,13 @@ const HELP = `pleum — PleumRouter 터미널 CLI
                                      (claude · aider · codex · goose · openhands)
                                      도구 생략 시 지원 목록·설치 여부 표시
   pleum run [model] ["프롬프트"]      터미널 채팅(REPL) / 1회 실행 / 파이프
-                                     모델 생략 시 인터랙티브 선택, /help 로 명령
+                                     모델 생략 시 화살표로 선택, /help 로 명령
   pleum models [query] [--json]      모델 목록(가격·컨텍스트 포함)
+  pleum models <id> --info           모델 상세(가격·성능·provider별 uptime)
+  pleum top [--period weekly]        모델 리더보드·제공자 점유율(daily|weekly|monthly)
   pleum balance                      크레딧 잔액 조회
+  pleum usage [--by model] [--days 30]  내 지출 리포트(model|provider|api_key|day)
+  pleum health                       게이트웨이 연결·로그인 상태 점검
   pleum completion <zsh|bash>        셸 자동완성 스크립트 출력
   pleum upgrade                      최신 버전으로 재설치
   pleum version                      버전 출력
@@ -31,6 +40,8 @@ const HELP = `pleum — PleumRouter 터미널 CLI
   pleum run gpt-4.1                          # 대화형
   pleum run gpt-4.1 "한 줄로 요약: ..."       # 1회 실행
   cat error.log | pleum run gpt-4.1 "원인은?"  # 파이프
+  pleum models deepseek/deepseek-chat --info # 모델 상세
+  pleum usage --by day --days 7              # 최근 1주 일별 지출
   pleum login --device                       # SSH/CI 환경
 
 base_url 덮어쓰기: PLEUM_BASE_URL 환경변수`;
@@ -84,6 +95,15 @@ try {
     case "balance":
       await balance();
       break;
+    case "usage":
+      await usage(rest);
+      break;
+    case "top":
+      await top(rest);
+      break;
+    case "health":
+      await health();
+      break;
     case "completion":
       completion(rest[0]);
       break;
@@ -96,6 +116,9 @@ try {
       version();
       break;
     case undefined:
+      // TTY면 ollama풍 런처 메뉴, 파이프/스크립트면 기존 도움말.
+      if (!(await mainMenu())) console.log(HELP);
+      break;
     case "-h":
     case "--help":
     case "help":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pleumrouter",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Official PleumRouter terminal CLI — launch any coding agent against PleumRouter.",
   "type": "module",
   "bin": {

package/src/ansi.mjs

@@ -0,0 +1,102 @@
+// 색상/스타일 프리미티브 — zero-dep. NO_COLOR·비TTY·dumb 터미널이면 자동 무색.
+// 브랜드 컬러는 frontend globals.css의 --plum-bright(#936c89) 계열.
+
+// 색상 지원 레벨: 0=무색, 1=16색, 2=256색, 3=truecolor. env/stream 주입 가능(테스트용).
+export function detectColorLevel(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR != null) return 0;
+  if (env.FORCE_COLOR != null) {
+    const n = Number(env.FORCE_COLOR);
+    return Number.isFinite(n) ? Math.max(0, Math.min(3, n)) : 3;
+  }
+  if (!stream.isTTY || env.TERM === "dumb") return 0;
+  if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") return 3;
+  if (/-256(color)?$/.test(env.TERM || "")) return 2;
+  return 1;
+}
+
+const PLUM = [147, 108, 137]; // #936c89 — 다크 터미널에서 가독성 있는 브랜드 보라
+
+// RGB → xterm 256색 큐브 근사(16 + 36r + 6g + b, 각 축 0–5 양자화).
+function rgbTo256([r, g, b]) {
+  const q = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+// 각 wrap은 \x1b[0m 완전 리셋 — 중첩 보존보다 색 누수 방지 우선(zero-dep 트레이드오프).
+export function createStyler(level = detectColorLevel()) {
+  const wrap = (open) => (s) => (level ? `${open}${s}\x1b[0m` : String(s));
+  const rgb = (c, fallback16) =>
+    level >= 3
+      ? wrap(`\x1b[38;2;${c.join(";")}m`)
+      : level === 2
+        ? wrap(`\x1b[38;5;${rgbTo256(c)}m`)
+        : wrap(`\x1b[${fallback16}m`);
+  return {
+    level,
+    bold: wrap("\x1b[1m"),
+    dim: wrap("\x1b[2m"),
+    italic: wrap("\x1b[3m"),
+    plum: rgb(PLUM, 35), // 16색 폴백=마젠타
+    green: wrap("\x1b[32m"),
+    red: wrap("\x1b[31m"),
+    yellow: wrap("\x1b[33m"),
+    cyan: wrap("\x1b[36m"),
+    gray: wrap("\x1b[90m"),
+  };
+}
+
+// CLI 런타임 싱글턴 — 파이프/NO_COLOR면 모든 함수가 항등이라 호출부 분기 불필요.
+export const style = createStyler();
+
+export function stripAnsi(s) {
+  // CSI(색·커서·마우스) + OSC(하이퍼링크) — displayWidth가 폭을 잘못 세지 않게 둘 다 제거.
+  return String(s)
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-9;<]*[A-Za-z]/g, "");
+}
+
+// OSC 8 클릭 가능한 하이퍼링크. 무색(파이프·NO_COLOR·dumb)이면 텍스트만.
+export function hyperlink(url, text = url, level = style.level) {
+  return level ? `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\` : text;
+}
+
+// 터미널 표시 폭 — CJK(한글 등) 전각 문자는 2칸. 정렬·줄수 계산용.
+export function displayWidth(s) {
+  let w = 0;
+  for (const ch of stripAnsi(s)) {
+    const c = ch.codePointAt(0);
+    const wide =
+      c >= 0x1100 &&
+      (c <= 0x115f || // 한글 자모
+        (c >= 0x2e80 && c <= 0xa4cf) || // CJK 부수·한자·가나
+        (c >= 0xac00 && c <= 0xd7a3) || // 한글 음절
+        (c >= 0xf900 && c <= 0xfaff) ||
+        (c >= 0xfe30 && c <= 0xfe4f) ||
+        (c >= 0xff00 && c <= 0xff60) || // 전각 영숫자
+        (c >= 0xffe0 && c <= 0xffe6) ||
+        (c >= 0x20000 && c <= 0x3fffd));
+    w += wide ? 2 : 1;
+  }
+  return w;
+}
+
+// 표시 폭 기준 오른쪽 패딩 — ANSI·전각 섞여도 컬럼이 맞는다(String.padEnd 대체).
+export function padDisplay(s, width) {
+  const pad = width - displayWidth(s);
+  return pad > 0 ? s + " ".repeat(pad) : s;
+}
+
+export function terminalWidth(fallback = 80) {
+  return process.stdout.columns || fallback;
+}
+
+export function divider(width = Math.min(terminalWidth(), 60), styler = style) {
+  return styler.gray("─".repeat(Math.max(1, width)));
+}
+
+// "█████░░░░░" 수평 막대(순수 함수) — usage/top 공용.
+export function barChart(value, max, width = 20) {
+  if (!Number.isFinite(value) || !max || max <= 0) return "░".repeat(width);
+  const filled = Math.round(Math.min(Math.max(value / max, 0), 1) * width);
+  return "█".repeat(filled) + "░".repeat(Math.max(0, width - filled));
+}

package/src/balance.mjs

@@ -1,5 +1,5 @@
-import { V1 } from "./config.mjs";
-import { requireKey } from "./config.mjs";
+import { V1, requireKey } from "./config.mjs";
+import { style } from "./ansi.mjs";
 
 export async function balance() {
   const key = requireKey();
@@ -8,11 +8,18 @@ export async function balance() {
   });
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    console.error(`잔액 조회 실패 (HTTP ${res.status})${body ? `: ${body}` : ""}`);
+    console.error(`잔액 조회 실패 (HTTP ${res.status})${body ? `: ${body.slice(0, 200)}` : ""}`);
+    if (res.status === 401) {
+      console.error(style.dim("서버가 아직 API 키 잔액 조회를 지원하지 않거나 키가 만료됐을 수 있습니다 — pleum login 재시도."));
+    }
     process.exit(1);
   }
   const data = await res.json();
   const plm = data.balance_krw;
-  const usd = data.balance_usd != null ? ` / $${data.balance_usd.toFixed(4)}` : "";
-  console.log(`잔액: ${plm.toLocaleString("ko-KR")} PLM${usd}`);
+  const usd = data.balance_usd != null ? style.dim(` / $${data.balance_usd.toFixed(4)}`) : "";
+  console.log(`잔액: ${style.bold(style.plum(`${plm.toLocaleString("ko-KR")} PLM`))}${usd}`);
+  const threshold = data.auto_charge_threshold_krw;
+  if (threshold != null && plm < threshold) {
+    console.log(style.yellow(`⚠ 잔액이 자동충전 임계값(${threshold.toLocaleString("ko-KR")} PLM) 아래입니다.`));
+  }
 }

package/src/completion.mjs

@@ -1,6 +1,6 @@
 // Shell 자동완성 스크립트 출력. 명령·도구는 정적, 모델명은 `pleum models`에서 동적으로 채운다.
 // 설치: pleum completion zsh >> ~/.zshrc  ·  pleum completion bash >> ~/.bashrc
-const COMMANDS = "login logout launch run models balance version upgrade completion help";
+const COMMANDS = "login logout launch run models top balance usage health version upgrade completion help";
 const TOOLS = "claude aider codex goose openhands opencode crush";
 
 function bash() {

package/src/health.mjs

@@ -0,0 +1,55 @@
+// `pleum health` — 게이트웨이 연결성 + 로그인 상태 한눈에.
+// 셀프호스트/스테이징(PLEUM_BASE_URL) 점검·고객지원 트리아지용. 공개 /v1/health 재사용.
+
+import { ROOT, V1, readConfig } from "./config.mjs";
+import { style, divider } from "./ansi.mjs";
+
+const ok = (s) => `${style.green("●")} ${s}`;
+const bad = (s) => `${style.red("●")} ${s}`;
+const warn = (s) => `${style.yellow("●")} ${s}`;
+
+// health 응답 + 로컬 상태 → 표시 문자열(순수 함수 — fixture 테스트 대상).
+export function renderHealth({ root, health, error, ms, keyPrefix }, styler = style) {
+  const lines = [];
+  lines.push(`${styler.bold(styler.plum("pleum health"))} ${styler.dim(`· ${root}`)}`);
+  lines.push(divider(undefined, styler));
+  if (error) {
+    lines.push(bad(`게이트웨이 연결 실패: ${error}`));
+  } else {
+    const isOk = (v) => v === "ok" || v === true; // 백엔드는 "ok" 문자열
+    lines.push((isOk(health.status) ? ok : warn)(`게이트웨이 ${health.status}${ms != null ? styler.dim(` (${ms}ms)`) : ""}`));
+    if (health.db != null) lines.push((isOk(health.db) ? ok : bad)(`DB ${isOk(health.db) ? "정상" : health.db}`));
+    if (health.redis != null) lines.push((isOk(health.redis) ? ok : bad)(`Redis ${isOk(health.redis) ? "정상" : health.redis}`));
+    if (health.providers_configured != null) lines.push(ok(`providers ${health.providers_configured}개 구성됨`));
+    const fx = health.fx_rate;
+    if (fx != null) {
+      const rate = typeof fx === "object" ? fx.rate : fx; // {rate, applied_rate, source}
+      const src = typeof fx === "object" && fx.source ? styler.dim(` (${fx.source})`) : "";
+      if (rate != null) lines.push(ok(`환율 USD/KRW ${rate}${src}`));
+    }
+  }
+  lines.push(
+    keyPrefix
+      ? ok(`로그인됨 ${styler.dim(`(키 ${keyPrefix}…)`)}`)
+      : warn(`로그인 안 됨 ${styler.dim("— pleum login")}`),
+  );
+  return lines.join("\n");
+}
+
+export async function health() {
+  const cfg = readConfig();
+  const keyPrefix = cfg?.key ? cfg.key.slice(0, 8) : null;
+  const t0 = Date.now();
+  let data = null;
+  let error = null;
+  try {
+    const res = await fetch(`${V1}/health`);
+    if (!res.ok) error = `HTTP ${res.status}`;
+    else data = await res.json();
+  } catch (e) {
+    error = e.message;
+  }
+  const ms = Date.now() - t0;
+  console.log(renderHealth({ root: ROOT, health: data, error, ms, keyPrefix }));
+  if (error) process.exit(1);
+}

package/src/interactive.mjs

@@ -0,0 +1,252 @@
+// 스피너 + raw-mode 화살표 셀렉터 — zero-dep 라인 플로우 인터랙션.
+
+import { style, displayWidth, terminalWidth } from "./ansi.mjs";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+// 브레일 스피너. 기본 stderr — stdout 파이프를 더럽히지 않는다. 비TTY면 no-op.
+export function spinner(text, { stream = process.stderr, intervalMs = 80 } = {}) {
+  if (!stream.isTTY) return { update() {}, stop() {} };
+  let i = 0;
+  let msg = text;
+  let stopped = false;
+  stream.write("\x1b[?25l"); // 커서 숨김
+  const draw = () => stream.write(`\r\x1b[2K${style.plum(FRAMES[i++ % FRAMES.length])} ${style.dim(msg)}`);
+  draw();
+  const t = setInterval(draw, intervalMs);
+  return {
+    update(m) {
+      msg = m;
+    },
+    stop() {
+      if (stopped) return; // 멱등 — 중복 stop이 이후 출력 줄을 지우지 않게
+      stopped = true;
+      clearInterval(t);
+      stream.write("\r\x1b[2K\x1b[?25h");
+    },
+  };
+}
+
+// 마우스 리포팅 켬/끔 — bubbletea와 동일 조합(1002 버튼추적 + 1003 모든모션 + 1006 SGR 좌표).
+// 미지원 모드는 터미널이 무시하므로 셋 다 켜고, 끌 때도 셋 다 리셋한다.
+export const MOUSE_ON = "\x1b[?1002h\x1b[?1003h\x1b[?1006h";
+export const MOUSE_OFF = "\x1b[?1002l\x1b[?1003l\x1b[?1006l";
+
+// raw-mode 입력 청크 → 키 이벤트 배열(순수 함수 — 테스트 대상).
+// 화살표(\x1b[A/B)와 일반 문자가 한 청크에 섞여 와도 순서대로 분해한다.
+// 청크 끝의 외톨이 ESC는 escape(취소)로 처리 — 실터미널은 화살표 3바이트를
+// 한 이벤트로 보내므로 실사용에서 오인될 일은 거의 없다.
+// SGR 마우스(\x1b[<Cb;Cx;CyM|m): Cb 비트 0-1=버튼(0좌 2우), 32=모션, 64=휠(64업 65다운).
+// CPR(\x1b[row;colR): DSR \x1b[6n 응답 — 인라인 렌더의 마우스 좌표 매핑용.
+export function parseKeys(chunk) {
+  const out = [];
+  for (let i = 0; i < chunk.length; ) {
+    const ch = chunk[i];
+    if (ch === "\x1b") {
+      if (chunk[i + 1] === "[") {
+        const rest = chunk.slice(i + 2);
+        const mouse = /^<(\d+);(\d+);(\d+)([Mm])/.exec(rest);
+        if (mouse) {
+          const cb = Number(mouse[1]);
+          out.push({
+            type: "mouse",
+            btn: cb & 0b11,
+            x: Number(mouse[2]),
+            y: Number(mouse[3]),
+            motion: Boolean(cb & 32),
+            release: mouse[4] === "m",
+            wheel: cb & 64 ? ((cb & 0b11) === 0 ? "up" : (cb & 0b11) === 1 ? "down" : null) : null,
+          });
+          i += 2 + mouse[0].length;
+          continue;
+        }
+        const m = /^([0-9;]*)([A-Za-z~])/.exec(rest);
+        if (m) {
+          const code = m[2];
+          if (code === "A") out.push({ type: "up" });
+          else if (code === "B") out.push({ type: "down" });
+          else if (code === "C") out.push({ type: "right" });
+          else if (code === "D") out.push({ type: "left" });
+          else if (code === "R") {
+            const [row, col] = m[1].split(";").map(Number);
+            out.push({ type: "cpr", row: row || 0, col: col || 0 });
+          } else out.push({ type: "unknown" }); // 기타 CSI는 무시
+          i += 2 + m[1].length + 1;
+          continue;
+        }
+      }
+      out.push({ type: "escape" });
+      i += 1;
+      continue;
+    }
+    if (ch === "\r" || ch === "\n") out.push({ type: "enter" });
+    else if (ch === "\x03") out.push({ type: "ctrlc" });
+    else if (ch === "\x7f" || ch === "\b") out.push({ type: "backspace" });
+    else if (ch >= " ") out.push({ type: "char", value: ch });
+    else out.push({ type: "unknown" });
+    i += 1;
+  }
+  return out;
+}
+
+// 청크 경계에서 잘린 CSI/SGR 시퀀스를 다음 청크와 이어 붙이는 스트림 래퍼(순수 폐쇄 — 테스트 대상).
+// 1003 모션 홍수에서 \x1b[<… 가 중간에 잘리면 escape로 오인돼 UI가 닫히는 것을 방지.
+// 외톨이 \x1b(=ESC 키)는 즉시 escape 처리(기존 트레이드오프 유지).
+export function keyFeeder() {
+  let carry = "";
+  return (chunk) => {
+    let data = carry + chunk;
+    const cut = /\x1b\[[<0-9;]*$/.exec(data);
+    carry = cut ? cut[0] : "";
+    if (cut) data = data.slice(0, cut.index);
+    return parseKeys(data);
+  };
+}
+
+// 절대 y(1-기반)를 인라인 프레임의 라인 인덱스로 변환(순수 함수 — 테스트 대상).
+// endRow = 프레임 마지막 줄의 절대 행(CPR로 얻음). 줄바꿈은 rowsFor(라인별 시각 행수)로 반영.
+export function lineIndexAt(y, endRow, lines, rowsFor) {
+  if (!endRow) return -1;
+  const total = lines.reduce((n, l) => n + rowsFor(l), 0);
+  const top = endRow - total + 1;
+  if (y < top || y > endRow) return -1;
+  let row = top;
+  for (let i = 0; i < lines.length; i++) {
+    const h = rowsFor(lines[i]);
+    if (y < row + h) return i;
+    row += h;
+  }
+  return -1;
+}
+
+// 마우스 리포팅 토글 + 비정상 종료 안전망(프로세스 exit 시 터미널 모드 복원).
+let mouseActive = false;
+let exitHooked = false;
+export function setMouse(output, on) {
+  if (!exitHooked) {
+    exitHooked = true;
+    process.on("exit", () => {
+      if (mouseActive) process.stdout.write(MOUSE_OFF + "\x1b[?25h");
+    });
+  }
+  mouseActive = on;
+  output.write(on ? MOUSE_ON : MOUSE_OFF);
+}
+
+// 화살표 이동 · 타이핑 필터 · Enter 선택 · Esc/Ctrl+C 취소(null).
+// 마우스: 호버=하이라이트, 휠=이동, 좌클릭=선택.
+// 비TTY면 즉시 null — 호출자가 기존 번호 피커 등으로 폴백한다.
+// process.exit는 절대 호출하지 않는다(취소 처리는 호출자 몫).
+export async function select(items, {
+  message = "선택",
+  formatItem = String,
+  matches = (all, q) => (q ? all.filter((it) => String(formatItem(it)).toLowerCase().includes(q.toLowerCase())) : all),
+  limit = 10,
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") return null;
+
+  return new Promise((resolve) => {
+    let query = "";
+    let cursor = 0;
+    let lastRows = 0;
+    let lastLines = [];
+    let shownCount = 0;
+    let cprRow = 0; // 프레임 마지막 줄의 절대 행 — DSR \x1b[6n 응답으로 갱신
+
+    const rowsFor = (s) => Math.max(1, Math.ceil(displayWidth(s) / Math.max(terminalWidth(), 1)));
+    const erase = () => {
+      if (!lastRows) return;
+      output.write("\r" + (lastRows > 1 ? `\x1b[${lastRows - 1}A` : "") + "\x1b[0J");
+      lastRows = 0;
+    };
+
+    const render = () => {
+      const pool = matches(items, query);
+      if (cursor >= pool.length) cursor = Math.max(0, pool.length - 1);
+      const shown = pool.slice(0, limit);
+      const lines = [
+        `${style.plum("?")} ${style.bold(message)} ${style.dim("타이핑=필터 · ↑↓=이동 · Enter=선택 · Esc=취소")}`,
+        `${style.gray("›")} ${query}`,
+        ...shown.map((it, i) =>
+          i === cursor ? `${style.plum("❯")} ${style.bold(formatItem(it))}` : `  ${style.dim(formatItem(it))}`,
+        ),
+      ];
+      if (pool.length > shown.length) lines.push(style.dim(`  … ${pool.length - shown.length}개 더 — 타이핑으로 좁히기`));
+      if (!pool.length) lines.push(style.dim("  일치 없음"));
+      erase();
+      const frame = lines.join("\n");
+      output.write(frame);
+      lastRows = lines.reduce((n, l) => n + rowsFor(l), 0);
+      lastLines = lines;
+      shownCount = shown.length;
+      output.write("\x1b[6n"); // CPR 질의 — 마우스 좌표 매핑용
+      return pool;
+    };
+
+    // 클릭/호버 y좌표 → 표시 중인 항목 인덱스(항목 라인은 3번째 줄부터). 밖이면 -1.
+    const itemAt = (y) => {
+      const li = lineIndexAt(y, cprRow, lastLines, rowsFor);
+      return li >= 2 && li < 2 + shownCount ? li - 2 : -1;
+    };
+
+    const finish = (value) => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      setMouse(output, false);
+      output.write("\x1b[?25h");
+      erase();
+      if (value != null) output.write(`${style.green("✓")} ${formatItem(value)}\n`);
+      resolve(value);
+    };
+
+    const feed = keyFeeder();
+    const onData = (chunk) => {
+      let dirty = false; // CPR만 온 턴에 재렌더하면 렌더→CPR 질의→응답 무한 루프
+      for (const key of feed(chunk)) {
+        if (key.type === "ctrlc" || key.type === "escape") return finish(null);
+        if (key.type === "cpr") {
+          cprRow = key.row;
+          continue;
+        }
+        if (key.type === "enter") {
+          const pool = matches(items, query);
+          return finish(pool[cursor] ?? null);
+        }
+        if (key.type === "mouse") {
+          if (key.wheel === "up") cursor = Math.max(0, cursor - 1);
+          else if (key.wheel === "down") cursor = Math.min(limit - 1, cursor + 1);
+          else if (key.motion) {
+            const idx = itemAt(key.y);
+            if (idx < 0 || idx === cursor) continue;
+            cursor = idx;
+          } else if (key.btn === 0 && !key.release) {
+            const idx = itemAt(key.y);
+            if (idx < 0) continue;
+            cursor = idx;
+            const pool = matches(items, query);
+            return finish(pool[cursor] ?? null);
+          } else continue;
+        } else if (key.type === "up") cursor = Math.max(0, cursor - 1);
+        else if (key.type === "down") cursor = Math.min(limit - 1, cursor + 1);
+        else if (key.type === "backspace") query = query.slice(0, -1);
+        else if (key.type === "char") {
+          query += key.value;
+          cursor = 0;
+        } else continue;
+        dirty = true;
+      }
+      if (dirty) render();
+    };
+
+    input.setEncoding("utf8"); // 멀티바이트(한글) 조각 자동 재조립
+    input.setRawMode(true);
+    input.resume();
+    output.write("\x1b[?25l");
+    setMouse(output, true);
+    input.on("data", onData);
+    render();
+  });
+}

package/src/launch.mjs

@@ -5,8 +5,8 @@ import { join, delimiter } from "node:path";
 import { requireKey } from "./config.mjs";
 import { RECIPES, MANUAL, codexToml } from "./recipes.mjs";
 
-// PATH에서 실행 파일을 찾는다(설치 여부 표시용).
-function onPath(bin) {
+// PATH에서 실행 파일을 찾는다(설치 여부 표시용). menu.mjs도 사용.
+export function onPath(bin) {
   const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
   return (process.env.PATH || "")
     .split(delimiter)
@@ -28,7 +28,8 @@ export function launchHelp() {
   console.log("\n예: pleum launch claude --model claude-sonnet-4");
 }
 
-export async function launch(tool, model, passthrough) {
+// exit:false면 process.exit 대신 자식 종료 코드를 반환 — 런처 메뉴의 실행 후 복귀용.
+export async function launch(tool, model, passthrough, { exit = true } = {}) {
   const key = requireKey();
   const r = RECIPES[tool];
 
@@ -59,20 +60,27 @@ export async function launch(tool, model, passthrough) {
   if (r.note) console.log(`ℹ ${r.note}`);
   console.log(`▶ ${r.label} 실행: ${r.bin} ${args.join(" ")}\n`);
 
-  const child = spawn(r.bin, args, {
-    env,
-    stdio: "inherit",
-    shell: process.platform === "win32",
+  return await new Promise((resolve) => {
+    const child = spawn(r.bin, args, {
+      env,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", (e) => {
+      if (e.code === "ENOENT") {
+        console.error(`✗ '${r.bin}'를 찾을 수 없습니다. 설치:\n  ${r.install}`);
+        if (exit) process.exit(127);
+        return resolve(127);
+      }
+      console.error(`✗ ${e.message}`);
+      if (exit) process.exit(1);
+      resolve(1);
+    });
+    child.on("exit", (code) => {
+      if (exit) process.exit(code ?? 0);
+      resolve(code ?? 0);
+    });
   });
-  child.on("error", (e) => {
-    if (e.code === "ENOENT") {
-      console.error(`✗ '${r.bin}'를 찾을 수 없습니다. 설치:\n  ${r.install}`);
-      process.exit(127);
-    }
-    console.error(`✗ ${e.message}`);
-    process.exit(1);
-  });
-  child.on("exit", (code) => process.exit(code ?? 0));
 }
 
 function printManual(tool, key) {