memro-cli 0.1.1 → 0.1.5

package/src/clients.js

@@ -59,23 +59,42 @@ export function writeFileSafely(file, text) {
 const writeJSON = (file, data) => writeFileSafely(file, JSON.stringify(data, null, 2) + "\n");
 
 /** A client whose config is a JSON object with servers under `key`. */
-function jsonClient({ id, name, file, detect, key = "mcpServers", entry }) {
+function jsonClient({
+  id,
+  name,
+  aliases = [],
+  file,
+  detect,
+  key = "mcpServers",
+  entry,
+  rules,
+  supportsScope = () => true,
+}) {
   return {
     id,
     name,
-    file,
-    detect,
-    add(conn) {
-      const cfg = readJSON(file());
+    aliases,
+    supportsScope,
+    file: (scope = "user", cwd = process.cwd()) => file(scope, cwd),
+    detect: (opts = {}) => {
+      const scope = typeof opts === "string" ? opts : (opts?.scope || "user");
+      const cwd = opts?.cwd || process.cwd();
+      return detect ? detect(scope, cwd) : false;
+    },
+    rules: rules ? (scope = "user", cwd = process.cwd()) => rules(scope, cwd) : () => null,
+    add(conn, { scope = "user", cwd = process.cwd() } = {}) {
+      const target = file(scope, cwd);
+      const cfg = readJSON(target);
       cfg[key] = { ...(cfg[key] || {}), [SERVER_NAME]: entry(conn) };
-      writeJSON(file(), cfg);
+      writeJSON(target, cfg);
     },
-    remove() {
-      if (!fs.existsSync(file())) return false;
-      const cfg = readJSON(file());
+    remove({ scope = "user", cwd = process.cwd() } = {}) {
+      const target = file(scope, cwd);
+      if (!fs.existsSync(target)) return false;
+      const cfg = readJSON(target);
       if (!cfg[key]?.[SERVER_NAME]) return false;
       delete cfg[key][SERVER_NAME];
-      writeJSON(file(), cfg);
+      writeJSON(target, cfg);
       return true;
     },
   };
@@ -83,6 +102,22 @@ function jsonClient({ id, name, file, detect, key = "mcpServers", entry }) {
 
 const exists = (...p) => fs.existsSync(path.join(...p));
 
+/** An executable called `cmd` on PATH (checked on disk, nothing is run). */
+export function onPath(cmd) {
+  const exts = process.platform === "win32" ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";") : [""];
+  return (process.env.PATH || "").split(path.delimiter).filter(Boolean)
+    .some((dir) => exts.some((ext) => fs.existsSync(path.join(dir, cmd + ext))));
+}
+
+/** A desktop app is installed: its app bundle or program folder exists, or
+ * its command is on PATH. A leftover settings folder does not count. */
+function appInstalled({ mac, win, linux = [], cmd }) {
+  if (cmd && onPath(cmd)) return true;
+  if (process.platform === "darwin") return ["/Applications", path.join(home(), "Applications")].some((d) => exists(d, `${mac}.app`));
+  if (process.platform === "win32") return exists(process.env.LOCALAPPDATA || path.join(home(), "AppData", "Local"), "Programs", win);
+  return linux.some((p) => fs.existsSync(p));
+}
+
 // --- Codex (TOML) ------------------------------------------------------------------
 
 const CODEX_HEADER = `[mcp_servers.${SERVER_NAME}]`;
@@ -107,66 +142,105 @@ const tomlString = (s) => JSON.stringify(s); // JSON strings are valid TOML basi
 const codex = {
   id: "codex",
   name: "Codex",
-  file: () => path.join(process.env.CODEX_HOME || path.join(home(), ".codex"), "config.toml"),
-  detect: () => exists(process.env.CODEX_HOME || path.join(home(), ".codex")),
-  add({ mcpUrl, apiKey }) {
-    const file = codex.file();
-    const current = fs.existsSync(file) ? stripCodexServer(fs.readFileSync(file, "utf8")) : "";
+  aliases: [],
+  supportsScope: () => true,
+  file: (scope = "user", cwd = process.cwd()) => {
+    return scope === "project"
+      ? path.join(cwd, ".codex", "config.toml")
+      : path.join(process.env.CODEX_HOME || path.join(home(), ".codex"), "config.toml");
+  },
+  detect: (opts = {}) => {
+    const scope = typeof opts === "string" ? opts : (opts?.scope || "user");
+    const cwd = opts?.cwd || process.cwd();
+    if (scope === "project") {
+      return exists(cwd, ".codex") || exists(cwd, "AGENTS.md") || exists(process.env.CODEX_HOME || path.join(home(), ".codex"));
+    }
+    return exists(process.env.CODEX_HOME || path.join(home(), ".codex"));
+  },
+  rules: (scope = "user", cwd = process.cwd()) => {
+    return scope === "project"
+      ? path.join(cwd, "AGENTS.md")
+      : path.join(process.env.CODEX_HOME || path.join(home(), ".codex"), "AGENTS.md");
+  },
+  add({ mcpUrl, apiKey }, { scope = "user", cwd = process.cwd() } = {}) {
+    const target = codex.file(scope, cwd);
+    const current = fs.existsSync(target) ? stripCodexServer(fs.readFileSync(target, "utf8")) : "";
     const block = [
       CODEX_HEADER,
       `url = ${tomlString(mcpUrl)}`,
       `http_headers = { Authorization = ${tomlString(`Bearer ${apiKey}`)} }`,
     ].join("\n");
-    writeFileSafely(file, (current ? current + "\n\n" : "") + block + "\n");
+    writeFileSafely(target, (current ? current + "\n\n" : "") + block + "\n");
   },
-  remove() {
-    const file = codex.file();
-    if (!fs.existsSync(file)) return false;
-    const text = fs.readFileSync(file, "utf8");
+  remove({ scope = "user", cwd = process.cwd() } = {}) {
+    const target = codex.file(scope, cwd);
+    if (!fs.existsSync(target)) return false;
+    const text = fs.readFileSync(target, "utf8");
     if (!text.includes(CODEX_HEADER)) return false;
-    writeFileSafely(file, stripCodexServer(text) + "\n");
+    writeFileSafely(target, stripCodexServer(text) + "\n");
     return true;
   },
 };
 
 // --- The catalogue --------------------------------------------------------------------
 
-// Claude Code rewrites ~/.claude.json while it runs, so prefer its own CLI
-// and only edit the file when `claude` is not on PATH.
-const claudeJSON = jsonClient({
-  id: "claude-code",
-  name: "Claude Code",
-  file: () => path.join(home(), ".claude.json"),
-  detect: () => exists(home(), ".claude.json") || exists(home(), ".claude"),
-  entry: ({ mcpUrl, apiKey }) => ({ type: "http", url: mcpUrl, headers: bearer(apiKey) }),
-});
-
-function claudeCLI(...args) {
+export function runClaudeCLI(args, { cwd } = {}) {
   try {
-    execFileSync("claude", args, { stdio: "ignore", timeout: 30_000, shell: process.platform === "win32" });
+    execFileSync("claude", args, { stdio: "ignore", timeout: 30_000, shell: process.platform === "win32", cwd });
     return true;
   } catch {
     return false;
   }
 }
 
-const hasClaudeCLI = () => !process.env.MEMRO_NO_CLAUDE_CLI && claudeCLI("--version");
+const hasClaudeCLI = () => !process.env.MEMRO_NO_CLAUDE_CLI && runClaudeCLI(["--version"]);
 
 const claudeCode = {
-  ...claudeJSON,
-  add(conn) {
+  id: "claude-code",
+  name: "Claude Code",
+  aliases: ["claude", "claudecode"],
+  supportsScope: (scope) => scope === "user" || scope === "project",
+  // Project-scoped servers live in the project's .mcp.json (what
+  // `claude mcp add --scope project` writes); user scope in ~/.claude.json.
+  file: (scope = "user", cwd = process.cwd()) => {
+    return scope === "project" ? path.join(cwd, ".mcp.json") : path.join(home(), ".claude.json");
+  },
+  detect: (opts = {}) => {
+    const scope = typeof opts === "string" ? opts : (opts?.scope || "user");
+    const cwd = opts?.cwd || process.cwd();
+    if (scope === "project") {
+      return exists(cwd, ".mcp.json") || exists(cwd, ".claude") || exists(cwd, "CLAUDE.md") || hasClaudeCLI() || exists(home(), ".claude.json") || exists(home(), ".claude");
+    }
+    return exists(home(), ".claude.json") || exists(home(), ".claude") || hasClaudeCLI();
+  },
+  rules: (scope = "user", cwd = process.cwd()) => {
+    return scope === "project" ? path.join(cwd, "CLAUDE.md") : path.join(home(), ".claude", "CLAUDE.md");
+  },
+  add(conn, { scope = "user", cwd = process.cwd() } = {}) {
     // On Windows the CLI runs through cmd.exe, which splits the header at its
     // spaces, so edit the file there instead.
     if (process.platform !== "win32" && hasClaudeCLI()) {
-      claudeCLI("mcp", "remove", "--scope", "user", SERVER_NAME);
-      if (claudeCLI("mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, conn.mcpUrl,
-        "--header", `Authorization: Bearer ${conn.apiKey}`)) return;
+      runClaudeCLI(["mcp", "remove", "--scope", scope, SERVER_NAME], { cwd });
+      if (runClaudeCLI(["mcp", "add", "--transport", "http", "--scope", scope, SERVER_NAME, conn.mcpUrl,
+        "--header", `Authorization: Bearer ${conn.apiKey}`], { cwd })) return;
     }
-    claudeJSON.add(conn);
+    const target = claudeCode.file(scope, cwd);
+    const cfg = readJSON(target);
+    cfg.mcpServers = { ...(cfg.mcpServers || {}), [SERVER_NAME]: { type: "http", url: conn.mcpUrl, headers: bearer(conn.apiKey) } };
+    writeJSON(target, cfg);
   },
-  remove() {
-    if (hasClaudeCLI()) return claudeCLI("mcp", "remove", "--scope", "user", SERVER_NAME);
-    return claudeJSON.remove();
+  remove({ scope = "user", cwd = process.cwd() } = {}) {
+    if (hasClaudeCLI()) {
+      const ok = runClaudeCLI(["mcp", "remove", "--scope", scope, SERVER_NAME], { cwd });
+      if (ok) return true;
+    }
+    const target = claudeCode.file(scope, cwd);
+    if (!fs.existsSync(target)) return false;
+    const cfg = readJSON(target);
+    if (!cfg.mcpServers?.[SERVER_NAME]) return false;
+    delete cfg.mcpServers[SERVER_NAME];
+    writeJSON(target, cfg);
+    return true;
   },
 };
 
@@ -176,52 +250,71 @@ export const CLIENTS = [
   jsonClient({
     id: "cursor",
     name: "Cursor",
-    file: () => path.join(home(), ".cursor", "mcp.json"),
-    detect: () => exists(home(), ".cursor"),
+    aliases: [],
+    file: (scope, cwd) => (scope === "project" ? path.join(cwd, ".cursor", "mcp.json") : path.join(home(), ".cursor", "mcp.json")),
+    detect: (scope, cwd) => (scope === "project" ? exists(cwd, ".cursor") || exists(home(), ".cursor") : exists(home(), ".cursor")),
     entry: ({ mcpUrl, apiKey }) => ({ url: mcpUrl, headers: bearer(apiKey) }),
   }),
   jsonClient({
     id: "antigravity",
     name: "Antigravity",
-    file: () => path.join(home(), ".gemini", "antigravity", "mcp_config.json"),
-    detect: () => exists(home(), ".gemini", "antigravity"),
+    aliases: ["agy"],
+    file: (scope, cwd) => (scope === "project" ? path.join(cwd, ".gemini", "config", "mcp_config.json") : path.join(home(), ".gemini", "config", "mcp_config.json")),
+    detect: (scope, cwd) => (scope === "project"
+      ? exists(cwd, ".gemini") || exists(cwd, ".agents") || exists(home(), ".gemini", "config") || exists(home(), ".gemini", "antigravity-ide") || exists(home(), ".gemini", "antigravity")
+      : exists(home(), ".gemini", "config") || exists(home(), ".gemini", "antigravity-ide") || exists(home(), ".gemini", "antigravity")),
     entry: ({ mcpUrl, apiKey }) => ({ serverUrl: mcpUrl, headers: bearer(apiKey) }),
+    rules: (scope, cwd) => (scope === "project" ? path.join(cwd, ".agents", "rules", "memro.md") : path.join(home(), ".gemini", "config", "rules", "memro.md")),
   }),
   jsonClient({
     id: "opencode",
     name: "OpenCode",
-    file: () => path.join(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode", "opencode.json"),
-    detect: () => exists(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode"),
+    aliases: [],
+    file: (scope, cwd) => (scope === "project" ? path.join(cwd, "opencode.json") : path.join(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode", "opencode.json")),
+    detect: (scope, cwd) => (scope === "project" ? exists(cwd, "opencode.json") || exists(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode") : exists(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode")),
     key: "mcp",
     entry: ({ mcpUrl, apiKey }) => ({ type: "remote", url: mcpUrl, enabled: true, headers: bearer(apiKey) }),
+    rules: (scope, cwd) => (scope === "project" ? path.join(cwd, "AGENTS.md") : path.join(process.env.XDG_CONFIG_HOME || path.join(home(), ".config"), "opencode", "AGENTS.md")),
   }),
   jsonClient({
     id: "gemini-cli",
     name: "Gemini CLI",
-    file: () => path.join(home(), ".gemini", "settings.json"),
-    detect: () => exists(home(), ".gemini", "settings.json"),
+    aliases: ["gemini"],
+    file: (scope, cwd) => (scope === "project" ? path.join(cwd, ".gemini", "settings.json") : path.join(home(), ".gemini", "settings.json")),
+    detect: (scope, cwd) => (scope === "project" ? exists(cwd, ".gemini") || exists(home(), ".gemini", "settings.json") : exists(home(), ".gemini", "settings.json")),
     entry: ({ mcpUrl, apiKey }) => ({ httpUrl: mcpUrl, headers: bearer(apiKey) }),
+    rules: (scope, cwd) => (scope === "project" ? path.join(cwd, "GEMINI.md") : path.join(home(), ".gemini", "GEMINI.md")),
   }),
   jsonClient({
     id: "vscode",
     name: "VS Code",
-    file: () => appSupport("Code", "User", "mcp.json"),
-    detect: () => fs.existsSync(appSupport("Code", "User")),
+    aliases: ["code"],
+    file: (scope, cwd) => (scope === "project" ? path.join(cwd, ".vscode", "mcp.json") : appSupport("Code", "User", "mcp.json")),
+    detect: (scope, cwd) => (scope === "project" ? exists(cwd, ".vscode") || fs.existsSync(appSupport("Code", "User")) : fs.existsSync(appSupport("Code", "User"))),
     key: "servers",
     entry: ({ mcpUrl, apiKey }) => ({ type: "http", url: mcpUrl, headers: bearer(apiKey) }),
   }),
   jsonClient({
     id: "windsurf",
     name: "Windsurf",
+    aliases: [],
+    // Windsurf reads MCP servers from one user-wide file; it has no
+    // per-project MCP config.
+    supportsScope: (scope) => scope === "user",
     file: () => path.join(home(), ".codeium", "windsurf", "mcp_config.json"),
-    detect: () => exists(home(), ".codeium", "windsurf"),
+    // ~/.codeium/windsurf outlives an uninstall, so it is not proof.
+    detect: () => appInstalled({ mac: "Windsurf", win: "Windsurf", cmd: "windsurf", linux: ["/usr/share/windsurf", "/opt/Windsurf", "/opt/windsurf"] }),
     entry: ({ mcpUrl, apiKey }) => ({ serverUrl: mcpUrl, headers: bearer(apiKey) }),
+    rules: () => path.join(home(), ".codeium", "windsurf", "memories", "global_rules.md"),
   }),
   jsonClient({
     id: "claude-desktop",
     name: "Claude Desktop",
+    aliases: ["desktop"],
+    supportsScope: (scope) => scope === "user",
     file: () => appSupport("Claude", "claude_desktop_config.json"),
     detect: () => fs.existsSync(appSupport("Claude")),
+    rules: () => null,
     // Claude Desktop only launches local servers; mcp-remote bridges to /mcp.
     entry: ({ mcpUrl, apiKey }) => ({
       command: "npx",
@@ -232,4 +325,8 @@ export const CLIENTS = [
   }),
 ];
 
-export const findClient = (id) => CLIENTS.find((c) => c.id === id);
+export function findClient(id) {
+  if (!id) return undefined;
+  const norm = id.toLowerCase().trim();
+  return CLIENTS.find((c) => c.id === norm || c.aliases?.includes(norm));
+}

package/src/instructions.js

@@ -0,0 +1,109 @@
+// The "use Memro automatically" note `memro connect` adds to each tool's
+// global instructions file, between markers so it can be updated in place and
+// removed by `memro disconnect`. The MCP server sends the same guidance to
+// every client on connect (mcp/src/memro_mcp/server.py INSTRUCTIONS); this
+// covers tools that ignore server instructions. Keep the two in step, and
+// keep this short: Windsurf caps global rules at 6,000 characters.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const START = "<!-- memro:start -->";
+export const END = "<!-- memro:end -->";
+
+export const BLOCK = `${START}
+## Memro (long-term memory)
+
+Memro is my long-term memory across tools and sessions (MCP server \`memro\`). Use it without being asked:
+- At the start of a task, call \`recall\` with a short query about it and use what comes back.
+- When I state a preference, make a decision, correct you, or you learn a lasting fact about me or a project, call \`remember\` with one short, self-contained sentence.
+- Before answering about earlier work ("what did we decide about X?"), \`recall\` first.
+
+Never store secrets (keys, passwords, tokens), one-off chatter, or anything I ask you not to keep. Don't announce routine saves.
+${END}`;
+
+export const PROJECT_BLOCK = `${START}
+## Memro — long-term memory
+
+- At the start of a task, recall relevant context from Memro.
+- Remember durable decisions, preferences, and architectural changes.
+- Never store secrets, API keys, passwords, or sensitive client data.
+- Follow this repository's privacy and memory-sharing boundaries.
+${END}`;
+
+const globalBlockPattern = new RegExp(`\\n*${START}[\\s\\S]*?${END}\\n*`, "g");
+
+/** Text without the Memro block (removes all instances and cleans up orphan markers). */
+export function removeBlock(text) {
+  if (!text.includes(START) && !text.includes(END)) return text;
+  let out = text.replace(globalBlockPattern, "\n\n");
+  // Clean up any orphan markers if one was deleted accidentally
+  if (out.includes(START)) {
+    out = out.replace(new RegExp(`\\n*${START}[^\\n]*\\n*`, "g"), "\n\n");
+  }
+  if (out.includes(END)) {
+    out = out.replace(new RegExp(`\\n*${END}\\n*`, "g"), "\n\n");
+  }
+  out = out.replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n");
+  return out.trim() ? out.replace(/\s+$/, "") + "\n" : "";
+}
+
+/** Text with the Memro block added, or replaced if it is already there. */
+export function upsertBlock(text, block = BLOCK) {
+  const cleaned = removeBlock(text).replace(/\s+$/, "");
+  return (cleaned ? cleaned + "\n\n" : "") + block + "\n";
+}
+
+/** Atomically replace a text file, keeping a one-time backup of the original
+ * and the file's existing permissions. */
+function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const existed = fs.existsSync(file);
+  if (existed && !fs.existsSync(`${file}.memro-backup`)) fs.copyFileSync(file, `${file}.memro-backup`);
+  const tmp = `${file}.memro-tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, text, existed ? { mode: fs.statSync(file).mode & 0o777 } : {});
+    fs.renameSync(tmp, file);
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+/** Whether text already tells the agent to use Memro, outside our block
+ * (e.g. guidance the user wrote themselves). */
+export function hasOwnMemroGuidance(text) {
+  const rest = removeBlock(text);
+  return /memro/i.test(rest) && /\brecall\b/i.test(rest);
+}
+
+/**
+ * Add or refresh the block in a tool's instructions file. If the file already
+ * has its own Memro guidance, leave that in charge: add nothing, and drop an
+ * older block of ours so the agent never gets the rules twice. Returns
+ * "added", "updated", "unchanged" or "kept-own".
+ */
+export function installInstructions(file, { scope = "user", block } = {}) {
+  const targetBlock = block || (scope === "project" ? PROJECT_BLOCK : BLOCK);
+  const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (hasOwnMemroGuidance(before)) {
+    const after = removeBlock(before);
+    if (after !== before) writeText(file, after);
+    return "kept-own";
+  }
+  const after = upsertBlock(before, targetBlock);
+  if (after === before) return "unchanged";
+  writeText(file, after);
+  return before.includes(START) ? "updated" : "added";
+}
+
+/** Remove the block; returns whether there was one. Deletes the file if
+ * Memro's block was all it contained. */
+export function uninstallInstructions(file) {
+  if (!fs.existsSync(file)) return false;
+  const before = fs.readFileSync(file, "utf8");
+  const after = removeBlock(before);
+  if (after === before) return false;
+  if (after === "") fs.rmSync(file);
+  else writeText(file, after);
+  return true;
+}

package/src/picker.js

@@ -1,28 +1,30 @@
-// A small multi-select for the terminal: arrow keys (or j/k) move, space
-// toggles, "a" toggles all, Enter confirms, Esc/q/Ctrl-C cancels. No
+// Small prompts for the terminal: multi-select, single-select and text. No
 // dependencies; the state logic is pure so it can be tested without a TTY.
+//
+// Keys: ↑/↓ (or j/k) move, space toggles, "a" toggles all, Enter confirms,
+// Esc/q/Ctrl-C cancels. While a prompt is open it is drawn as an active step
+// (◆); once answered it collapses to its question and answer (◇), so the
+// screen keeps a short record instead of every frame.
 
 import readline from "node:readline";
 
+import { c, S, bar, liveFrame } from "./ui.js";
+
 const ESC = "\x1b[";
-const c = {
-  dim: (s) => `${ESC}2m${s}${ESC}22m`,
-  bold: (s) => `${ESC}1m${s}${ESC}22m`,
-  accent: (s) => `${ESC}38;5;141m${s}${ESC}39m`,
-  green: (s) => `${ESC}32m${s}${ESC}39m`,
-};
 
 /** Initial state: items are { label, hint?, checked }. */
 export function initialState(items) {
   return { items: items.map((i) => ({ ...i })), cursor: 0, done: false, cancelled: false };
 }
 
+const isCancel = (key, name) => (key.ctrl && name === "c") || name === "escape" || name === "q";
+
 /** Apply one key ({ name, ctrl, sequence }) to the state. */
 export function reduce(state, key) {
   const s = { ...state, items: state.items.map((i) => ({ ...i })) };
   const n = s.items.length;
   const name = key.name || key.sequence;
-  if ((key.ctrl && name === "c") || name === "escape" || name === "q") {
+  if (isCancel(key, name)) {
     s.cancelled = true;
   } else if (name === "return" || name === "enter") {
     s.done = true;
@@ -32,53 +34,60 @@ export function reduce(state, key) {
     s.cursor = (s.cursor + 1) % n;
   } else if (name === "space" || name === " ") {
     s.items[s.cursor].checked = !s.items[s.cursor].checked;
-  } else if (name === "a") {
-    const all = s.items.every((i) => i.checked);
-    s.items.forEach((i) => { i.checked = !all; });
+  } else if (name === "a") { // all tools; options below the list keep their state
+    const tools = s.items.filter((i) => !i.option);
+    const all = tools.every((i) => i.checked);
+    tools.forEach((i) => { i.checked = !all; });
   }
   return s;
 }
 
+const header = (title, keys) => [`${c.accent(S.active)}  ${c.bold(title)}`, `${bar()}  ${c.dim(keys)}`, bar()];
+
 /** The lines to draw for a state. */
 export function render(state, title) {
-  const lines = [`  ${c.bold(title)}`, c.dim("  ↑/↓ move · space select · a all · enter confirm · esc cancel"), ""];
+  const lines = header(title, "↑/↓ move · space select · a all · enter confirm · esc cancel");
   state.items.forEach((item, i) => {
+    if (item.option && !state.items[i - 1]?.option) lines.push(bar()); // options sit below the list
     const here = i === state.cursor;
-    const box = item.checked ? c.green("◉") : c.dim("○");
-    const label = here ? c.accent(item.label) : item.label;
+    const box = item.checked ? c.green(S.checkOn) : c.dim(S.checkOff);
+    const label = here ? c.accent(item.label) : item.checked ? item.label : c.dim(item.label);
     const hint = item.hint ? "  " + c.dim(item.hint) : "";
-    lines.push(`  ${here ? c.accent("›") : " "} ${box} ${label}${hint}`);
+    lines.push(`${bar()}  ${here ? c.accent(S.cursor) : " "} ${box} ${label}${hint}`);
   });
-  const count = state.items.filter((i) => i.checked).length;
-  lines.push("", c.dim(`  ${count} selected`));
+  const count = state.items.filter((i) => i.checked && !i.option).length;
+  lines.push(bar(), `${c.gray(S.end)}  ${c.dim(`${count} selected`)}`);
   return lines;
 }
 
+/** One-line answer for a finished multi-select. */
+export function summary(state) {
+  const tools = state.items.filter((i) => i.checked && !i.option).map((i) => i.label);
+  const options = state.items.filter((i) => i.checked && i.option).map((i) => i.summary || i.label);
+  return [tools.join(", ") || "none", ...options].join(" · ");
+}
+
 /**
- * Show the picker and resolve with the selected items, or null if the user
- * cancelled. Requires an interactive terminal on `input`.
+ * Run a prompt: draw it, apply keys, and on Enter/cancel replace the frame
+ * with the collapsed step. Resolves with onDone(state) or null.
  */
-export function pick(items, { title, input = process.stdin, output = process.stdout } = {}) {
+function run({ state, reduceFn, renderFn, title, answer, onDone, input, output }) {
   return new Promise((resolve) => {
-    let state = initialState(items);
-    let drawn = 0;
-    const draw = () => {
-      const lines = render(state, title);
-      if (drawn) output.write(`${ESC}${drawn}A`); // back to the top of the last frame
-      output.write(lines.map((l) => `${ESC}2K${l}`).join("\n") + "\n");
-      drawn = lines.length;
-    };
-    const finish = (value) => {
+    const frame = liveFrame(output);
+    const draw = () => frame.draw(renderFn(state, title));
+    const finish = (value, collapsed) => {
       input.off("keypress", onKey);
+      output.off?.("resize", draw);
       if (input.isTTY) input.setRawMode(false);
       input.pause();
+      frame.draw(collapsed);
       output.write(`${ESC}?25h`); // show the cursor again
       resolve(value);
     };
     const onKey = (_str, key = {}) => {
-      state = reduce(state, key);
-      if (state.cancelled) return finish(null);
-      if (state.done) return finish(state.items.filter((i) => i.checked));
+      state = reduceFn(state, key);
+      if (state.cancelled) return finish(null, [`${c.red(S.cancel)}  ${title}`, `${bar()}  ${c.dim("Cancelled")}`]);
+      if (state.done) return finish(onDone(state), [`${c.green(S.done)}  ${title}`, `${bar()}  ${c.dim(answer(state))}`, bar()]);
       draw();
     };
     readline.emitKeypressEvents(input);
@@ -86,6 +95,79 @@ export function pick(items, { title, input = process.stdin, output = process.std
     input.resume();
     output.write(`${ESC}?25l`); // hide the cursor while choosing
     input.on("keypress", onKey);
+    output.on?.("resize", draw);
     draw();
   });
 }
+
+/**
+ * Show the picker and resolve with the selected items, or null if the user
+ * cancelled. Requires an interactive terminal on `input`.
+ */
+export function pick(items, { title, input = process.stdin, output = process.stdout } = {}) {
+  return run({
+    state: initialState(items), reduceFn: reduce, renderFn: render, title, input, output,
+    answer: summary,
+    onDone: (s) => s.items.filter((i) => i.checked),
+  });
+}
+
+/** Initial state for single-select: items are { label, hint?, value }. */
+export function initialSingleState(items, defaultIndex = 0) {
+  return { items: items.map((i) => ({ ...i })), cursor: defaultIndex, done: false, cancelled: false };
+}
+
+/** Apply key to single-select state. */
+export function reduceSingle(state, key) {
+  const s = { ...state, items: state.items.map((i) => ({ ...i })) };
+  const n = s.items.length;
+  const name = key.name || key.sequence;
+  if (isCancel(key, name)) {
+    s.cancelled = true;
+  } else if (name === "return" || name === "enter") {
+    s.done = true;
+  } else if (name === "up" || name === "k") {
+    s.cursor = (s.cursor - 1 + n) % n;
+  } else if (name === "down" || name === "j" || name === "tab") {
+    s.cursor = (s.cursor + 1) % n;
+  }
+  return s;
+}
+
+/** Render lines for single-select. The hint shows for the highlighted choice. */
+export function renderSingle(state, title) {
+  const lines = header(title, "↑/↓ move · enter select · esc cancel");
+  state.items.forEach((item, i) => {
+    const here = i === state.cursor;
+    const dot = here ? c.green(S.radioOn) : c.dim(S.radioOff);
+    const label = here ? c.accent(item.label) : c.dim(item.label);
+    lines.push(`${bar()}  ${here ? c.accent(S.cursor) : " "} ${dot} ${label}`);
+    if (here && item.hint) lines.push(`${bar()}      ${c.dim(item.hint)}`);
+  });
+  lines.push(c.gray(S.end));
+  return lines;
+}
+
+/**
+ * Show a single-select picker and resolve with the chosen item, or null if cancelled.
+ */
+export function pickOne(items, { title, defaultIndex = 0, input = process.stdin, output = process.stdout } = {}) {
+  return run({
+    state: initialSingleState(items, defaultIndex), reduceFn: reduceSingle, renderFn: renderSingle, title, input, output,
+    answer: (s) => s.items[s.cursor].summary || s.items[s.cursor].label,
+    onDone: (s) => s.items[s.cursor],
+  });
+}
+
+/**
+ * Ask a simple text prompt.
+ */
+export function promptText(query, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output });
+    rl.question(query, (ans) => {
+      rl.close();
+      resolve(ans.trim());
+    });
+  });
+}