@synqa/cli 1.1.0 → 1.2.0

package/dist/paths.js

@@ -1,6 +1,6 @@
 import { closeSync, constants, lstatSync, openSync, realpathSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { configDir } from "./config.js";
 
 export class ConfineError extends Error {}
@@ -62,47 +62,171 @@ export function fold(s        )         {
   return s.normalize("NFKC").toLowerCase();
 }
 
-// Folders whose contents are credentials.
-const SENSITIVE_DIRS = new Set([".ssh", ".aws", ".gnupg"]);
+// The protected tables. isSensitivePath (file tools) and commandTouchesSecrets (shell) are both
+// built from these, so a name added here is protected everywhere at once.
+// Folders whose contents are credentials, matched as any one path segment.
+export const SENSITIVE_DIRS                    = [".ssh", ".aws", ".gnupg", ".kube", ".password-store", ".mozilla", ".azure", "keychains"];
+// Runs of path segments that hold credentials, browser profiles or tokens, matched anywhere in the
+// path (folded). Inside the home folder every dot entry and Library is protected anyway (see
+// homeHidden); these runs also protect copies of such folders elsewhere.
+export const SENSITIVE_RUNS                                   = [
+  [".config", "synqa"], [".config", "gh"], [".config", "hub"], [".config", "gcloud"], [".config", "op"], [".config", "heroku"],
+  [".config", "google-chrome"], [".config", "chromium"], [".config", "bravesoftware"], [".config", "microsoft-edge"],
+  [".docker", "config.json"], [".local", "share", "keyrings"], [".cargo", "credentials.toml"], [".gem", "credentials"],
+  [".terraform.d", "credentials.tfrc.json"], [".m2", "settings.xml"], [".oci", "config"],
+  ["library", "cookies"], ["library", "safari"], ["library", "mail"], ["library", "messages"],
+  ["library", "application support", "google", "chrome"], ["library", "application support", "chromium"],
+  ["library", "application support", "bravesoftware"], ["library", "application support", "microsoft edge"],
+  ["library", "application support", "arc"], ["library", "application support", "firefox"],
+  ["library", "application support", "1password"], ["library", "group containers"],
+];
 // Exact file names that hold secrets (compared folded).
-const SENSITIVE_NAMES = new Set([
+export const SENSITIVE_NAMES                    = [
   ".env", ".envrc", ".netrc", ".npmrc", ".pypirc", ".git-credentials", ".dev.vars", "keys.json", "credentials.json", ".yarnrc.yml", ".pgpass", ".my.cnf",
-]);
+  "_netrc", ".boto", ".s3cfg", ".vault-token", ".terraformrc", "login data", "cookies", "cookies.binarycookies", "key4.db", "logins.json",
+  ".zsh_history", ".bash_history", ".python_history", ".node_repl_history", ".psql_history", ".mysql_history", ".lesshst",
+  ".yarnrc",
+];
+// File extensions of private keys, certificates with keys, key stores and infrastructure state.
+export const SENSITIVE_EXTENSIONS                    = [
+  "pem", "key", "p12", "p8", "pfx", "jks", "keystore", "ppk", "tfvars", "tfstate", "keychain", "keychain-db", "kdbx",
+];
+// Name patterns, each with the looser form a shell command is checked with. One table for both.
+// `word` rules guess from a word in the name, so they skip source code (src/auth/credentials.ts is
+// code about credentials, not credentials).
+export const SENSITIVE_PATTERNS                                                              = [
+  { name: /^\.env\.|\.env$/, shell: /\.env/ }, // .env.local, prod.env, config.env
+  { name: /\.tfstate(\.|$)/, shell: /\.tfstate/ }, // terraform.tfstate, terraform.tfstate.backup
+  { name: /service[-_]?account.*\.json$/, shell: /service[-_]?account/ },
+  // credential(s) or secret(s) as a word ("client_secret.json", "aws-secrets.yaml"; not "secretary.ts")
+  { name: /(^|[^a-z])(credential|secret)s?([^a-z]|$)/, shell: /credential|secret/, word: true },
+  // shell and REPL histories (.zsh_history, .python_history, history): the name ends in "history"
+  { name: /history$/, shell: /history/ }, // only a name that ends in "history": history.md and chat_history.ts never match
+  { name: /^id_[a-z0-9_]+$/, shell: /\bid_[a-z0-9]/ }, // id_rsa, id_ed25519; id_rsa.pub is not matched
+];
+// Source files: a word rule never applies to these (named secret files still do).
+export const SOURCE_EXTENSIONS                    = [
+  "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "go", "rs", "rb", "java", "kt", "swift", "c", "cc", "cpp", "h", "cs", "php", "vue", "svelte",
+];
+const SOURCE_RE = new RegExp(`\\.(${SOURCE_EXTENSIONS.join("|")})$`);
+// Source files whose whole stem says secret (secrets.py, credentials.js, client_secret.ts) often
+// hold real keys: the word rules let them through, so read_file asks first and grep and glob skip
+// them. A longer name (secret_manager.go, credentials_form.ts) is ordinary code.
+export const SECRET_STEMS                    = ["secret", "secrets", "credential", "credentials", "client_secret", "client_secrets"];
+
+export function isSecretStemSource(abs        )          {
+  const name = fold(abs.split(sep).join("/")).split("/").pop() ?? "";
+  if (!SOURCE_RE.test(name)) return false;
+  return SECRET_STEMS.includes(name.slice(0, name.lastIndexOf(".")));
+}
+// First segments of SENSITIVE_RUNS that are credential folders in their own right, so a shell
+// command that names the folder (ls .docker, cat ~/.docker/*) asks too. .config and .local hold
+// much else and are covered by the home rule.
+const RUN_FOLDERS = [...new Set(SENSITIVE_RUNS.map((r) => r[0]          ))].filter((f) => f.startsWith(".") && f !== ".config" && f !== ".local");
+const NAME_SET = new Set(SENSITIVE_NAMES);
+const DIR_SET = new Set(SENSITIVE_DIRS);
 const EXAMPLE_SUFFIX = /\.(example|sample|template|dist)$/;
+const EXT_RE = new RegExp(`\\.(${SENSITIVE_EXTENSIONS.map((e) => e.replace(/[.-]/g, "\\$&")).join("|")})$`);
 
-// Files and folders that hold secrets: .env files, private keys, cloud, package manager and
-// container credentials, and this CLI's own config (which holds the API key). Names only, no file
-// is opened. Every segment is folded first (see fold).
-export function isSensitivePath(abs        , cfg         = configDir())          {
-  const norm = fold(abs.split(sep).join("/"));
-  const parts = norm.split("/").filter(Boolean);
-  if (parts.some((d) => SENSITIVE_DIRS.has(d))) return true;
-  for (let i = 0; i + 1 < parts.length; i++) {
-    if (parts[i] === ".config" && parts[i + 1] === "synqa") return true;
-    if (parts[i] === ".kube" && parts[i + 1] === "config") return true;
-    if (parts[i] === ".docker" && parts[i + 1] === "config.json") return true;
+function hasRun(parts          , run                   )          {
+  for (let i = 0; i + run.length <= parts.length; i++) {
+    if (run.every((seg, j) => parts[i + j] === seg)) return true;
   }
-  const c = fold(cfg.split(sep).join("/")).replace(/\/+$/, "");
+  return false;
+}
+
+// One slash form for every comparison. On win32 both separators count and the drive letter and
+// every name are folded, so a Windows AppData folder in any letter case matches. The platform is
+// a parameter so the Windows rules are tested on any machine.
+const slashed = (p        , platform         = process.platform) =>
+  fold(platform === "win32" ? p.replace(/\\/g, "/") : p.split(sep).join("/")).replace(/\/+$/, "");
+
+// The home folder, as given and with symlinks resolved, folded.
+function homeForms(home        , platform         = process.platform)           {
+  const out = [slashed(home, platform)];
+  try {
+    out.push(slashed(realpathSync(home), platform));
+  } catch {
+    // a home that does not exist is compared as given
+  }
+  return out.filter((h) => h !== "" && h !== "/");
+}
+
+// Inside the home folder, everything under a dot entry at its top (~/.zsh_history, ~/.config/**,
+// ~/.cargo/**, any tool's credential store, known or not) and everything under
+// ~/Library is protected. This is the structural rule: it does not depend on naming each store.
+// A project's own dot files (~/proj/.github, ~/proj/.eslintrc) are below a normal folder and stay usable.
+// On Windows the same rule covers AppData (browser profiles, tokens, credential stores) and the
+// per-user registry hive NTUSER.DAT with its log and backup files.
+export function homeHidden(abs        , home         = homedir(), platform         = process.platform)          {
+  const norm = slashed(abs, platform);
+  for (const h of homeForms(home, platform)) {
+    if (!norm.startsWith(h + "/")) continue;
+    const first = norm.slice(h.length + 1).split("/")[0] ?? "";
+    if (first.startsWith(".") || first === "library") return true;
+    if (platform === "win32" && (first === "appdata" || first.startsWith("ntuser.dat") || first === "ntuser.ini")) return true;
+  }
+  return false;
+}
+
+// True when `cwd` is the home folder itself.
+export function isHomeDir(cwd        , home         = homedir(), platform         = process.platform)          {
+  let real = slashed(cwd, platform);
+  try {
+    real = slashed(realpathSync(cwd), platform);
+  } catch {
+    // compared as given
+  }
+  return homeForms(home, platform).includes(real) || homeForms(home, platform).includes(slashed(cwd, platform));
+}
+
+// Files and folders that hold secrets: the home folder's dot entries and Library (homeHidden),
+// env files, private keys, cloud, package manager and container credentials, keychains, browser
+// profiles, histories, and this CLI's own config (which holds the API key). Names only, no file is
+// opened. Every segment is folded first (see fold). read_file, write_file and edit_file refuse
+// these outright; grep and glob skip them.
+export function isSensitivePath(abs        , cfg         = configDir(), home         = homedir(), platform         = process.platform)          {
+  if (homeHidden(abs, home, platform)) return true;
+  const norm = slashed(abs, platform);
+  const parts = norm.split("/").filter(Boolean);
+  if (parts.some((d) => DIR_SET.has(d))) return true;
+  if (SENSITIVE_RUNS.some((run) => hasRun(parts, run))) return true;
+  const c = slashed(cfg, platform);
   if (c && (norm === c || norm.startsWith(c + "/"))) return true;
   const name = parts[parts.length - 1] ?? "";
   // Remotes can hold tokens: .git/config, .git/config.worktree, .git/worktrees/<name>/config, at any depth.
   if (parts.slice(0, -1).includes(".git") && (name === "config" || name.startsWith("config."))) return true;
-  if (SENSITIVE_NAMES.has(name)) return true;
-  if (name.startsWith(".env.") && !EXAMPLE_SUFFIX.test(name)) return true;
-  if (/\.(pem|key|p12|pfx|tfvars|tfstate)$/.test(name)) return true;
-  if (/^secrets\./.test(name) && !EXAMPLE_SUFFIX.test(name)) return true;
-  return /^id_[a-z0-9_]+$/.test(name); // id_rsa, id_ed25519; id_rsa.pub is not matched
+  if (NAME_SET.has(name)) return true;
+  if (EXAMPLE_SUFFIX.test(name)) return false;
+  if (EXT_RE.test(name)) return true;
+  const source = SOURCE_RE.test(name);
+  return SENSITIVE_PATTERNS.some((x) => x.name.test(name) && !(x.word && source));
 }
 
-// Names a shell command can use to reach a secret, including globs that expand to them. Heuristic:
-// it makes an unattended (--yes) command ask when it looks at secrets, it does not make bash safe.
-const SECRET_WORDS = [
-  /\.env/, /\.ssh/, /\.aws/, /\.gnupg/, /\.kube/, /\.docker/, /\.netrc/, /\.npmrc/, /\.pypirc/, /\.git-credentials/,
-  /\.dev\.vars/, /keys\.json/, /credentials/, /\.tfvars/, /\bsecrets?\b/, /\.(pem|key|p12|pfx)\b/, /\bid_[a-z0-9]/,
-  /\.config\/synqa/, /synqa\/config/, /(^|[\s/])\.[\w.-]*[*?[]/, /~\/?\./,
+const escRe = (s        ) => s.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+
+// Names a shell command can use to reach a secret, including globs that expand to them, built from
+// the same tables as isSensitivePath. Heuristic: it makes an unattended (--yes) command ask when it
+// looks at secrets, it does not make bash safe.
+const SECRET_WORDS                    = [
+  ...SENSITIVE_DIRS.map((d) => new RegExp(escRe(d))),
+  ...SENSITIVE_RUNS.map((r) => new RegExp(r.map(escRe).join("/"))),
+  ...SENSITIVE_NAMES.map((n) => new RegExp(escRe(n))),
+  ...RUN_FOLDERS.map((f) => new RegExp(`${escRe(f)}\\b`)),
+  new RegExp(`\\.(${SENSITIVE_EXTENSIONS.map(escRe).join("|")})\\b`),
+  ...SENSITIVE_PATTERNS.map((x) => x.shell),
+  /\.git\/config/,
+  // Dumping the environment (where tokens live): printenv, env or export -p or set with no arguments.
+  /\bprintenv\b/, /(^|[;&|(]\s*)env\s*($|[;&|)>])/, /\bexport\s+-p\b/, /(^|[;&|(]\s*)(set|declare\s+-x)\s*($|[;&|)>])/,
+  /\.config\/synqa/, /synqa\/config/,
+  /(^|[\s/])\.[\w.-]*[*?[]/, // a dot glob such as .e* or .*
+  /~\/?\./, /\$\{?home\}?\/?\./, /~\/library/, /\$\{?home\}?\/library/, // the home folder's dot entries and Library
+  /\bsecurity\s+(find|dump|export)-/, /\.binarycookies/,
 ];
 
 export function commandTouchesSecrets(command        , cfg         = configDir())          {
+  // Escapes that can spell any name ($'\x2eenv', \056, printf '\x2e'): always ask.
+  if (/\$'|\\x[0-9a-f]{2}|\\[0-7]{3}|\\u[0-9a-f]{4}/i.test(command)) return true;
   // Quotes and backslashes are dropped first so .e""nv and .\env read as .env.
   const c = fold(command).replace(/["'\\`]/g, "");
   if (SECRET_WORDS.some((re) => re.test(c))) return true;
@@ -110,22 +234,17 @@ export function commandTouchesSecrets(command        , cfg         = configDir()
   return dir !== "" && c.includes(dir);
 }
 
-// A start folder this CLI refuses without --allow-home: the home folder or the filesystem root.
-// Returns the reason, or undefined when the folder is fine.
-export function unsafeStartDir(cwd        , home         = homedir())                     {
+// The one start folder this CLI refuses: the filesystem root, where the working directory would be
+// the whole disk. Anywhere else, the home folder included, it starts like any other coding CLI;
+// secrets there are protected by isSensitivePath, not by refusing to start. Returns the reason,
+// or undefined when the folder is fine.
+export function unsafeStartDir(cwd        )                     {
   let real        ;
-  let realHome        ;
   try {
     real = realpathSync(cwd);
   } catch {
     return undefined;
   }
-  try {
-    realHome = realpathSync(home);
-  } catch {
-    realHome = home;
-  }
   if (real === parse(real).root) return "the filesystem root";
-  if (real === realHome) return "your home folder";
   return undefined;
 }

package/dist/prompt.js

@@ -0,0 +1,381 @@
+// The interactive prompt: the slash command table, the inline command menu, /help, and the frame
+// drawn around the input line (a rule above, a rule, the status line and key hints below).
+//
+// The frame and menu use only node:readline keypress events, no extra package. Keys from the
+// terminal are read here and forwarded to readline through a PassThrough, so the menu can take the
+// arrow keys, Tab, Enter and Esc for itself while it is open. The only control sequences written
+// are the fixed strings in this file (cursor up and column, erase line); every piece of text is our
+// own table or the user's own typing, already shown by readline.
+import { PassThrough } from "node:stream";
+import { emitKeypressEvents } from "node:readline";
+                                                        
+import { bold, dim, stone, terracottaBold } from "./theme.js";
+import { fit, oneLine, pad, PLACEHOLDER, rule, styleOf, textWidth } from "./ui.js";
+                                                    
+                                  
+
+                                                                                                                   
+
+export const SLASH_COMMANDS                          = [
+  { name: "/model", args: "blink|sonata|aeon", desc: "Choose the model (arrow keys)", group: "Session" },
+  { name: "/effort", args: "default|low|medium|high", desc: "Set reasoning effort (arrow keys)", group: "Session" },
+  { name: "/provider", desc: "Switch provider: Synqa Cloud, OpenCode, ...", group: "Session" },
+  { name: "/login", desc: "Sign in to a provider", group: "Session" },
+  { name: "/logout", desc: "Sign out of a provider or fully", group: "Session" },
+  { name: "/status", desc: "Tier, routing, tokens, credit and weekly pool", group: "Session" },
+  { name: "/compact", desc: "Summarize the conversation to save context", group: "Session" },
+  { name: "/clear", desc: "Start a fresh conversation", group: "Session" },
+  { name: "/init", desc: "Write a starter AGENTS.md for this project", group: "Project" },
+  { name: "/undo", desc: "Revert the last file the agent wrote", group: "Project" },
+  { name: "/hooks", desc: "List hooks and switch them on or off", group: "General" },
+  { name: "/update", desc: "Install the latest @synqa/cli", group: "General" },
+  { name: "/help", desc: "Show commands and keys", group: "General" },
+  { name: "/exit", desc: "Leave Synqa", group: "General" },
+];
+
+// Commands whose name starts with what was typed, then those that contain it.
+export function matchCommands(typed        )                 {
+  const t = typed.toLowerCase();
+  if (!t.startsWith("/")) return [];
+  const starts = SLASH_COMMANDS.filter((c) => c.name.startsWith(t));
+  const contains = SLASH_COMMANDS.filter((c) => !c.name.startsWith(t) && c.name.includes(t.slice(1)));
+  return [...starts, ...contains];
+}
+
+function distance(a        , b        )         {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array        (b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) (d[0]            )[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const row = d[i]            ;
+      const prev = d[i - 1]            ;
+      row[j] = Math.min((prev[j]          ) + 1, (row[j - 1]          ) + 1, (prev[j - 1]          ) + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return (d[a.length]            )[b.length]          ;
+}
+
+// One line for an unknown command, with the nearest name when one is close.
+export function unknownCommandHint(word        )         {
+  const w = oneLine(word).toLowerCase().slice(0, 40);
+  const near = matchCommands(w)[0] ?? SLASH_COMMANDS
+    .map((c) => ({ c, d: distance(w, c.name) }))
+    .filter((x) => x.d <= 2)
+    .sort((a, b) => a.d - b.d)[0]?.c;
+  return near ? `Unknown command ${w}. Did you mean ${near.name}? Type / to see all commands.` : `Unknown command ${w}. Type / to see all commands.`;
+}
+
+const usage = (c              ) => (c.args ? `${c.name} ${c.args}` : c.name);
+
+// /help: grouped, aligned, names bold and descriptions dim.
+export function renderHelp(ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const w = Math.max(...SLASH_COMMANDS.map((c) => usage(c).length)) + 3;
+  const out           = [];
+  for (const group of ["Session", "Project", "General"]         ) {
+    out.push(stone(s, group));
+    for (const c of SLASH_COMMANDS.filter((x) => x.group === group)) {
+      const u = usage(c);
+      if (4 + w >= room) { out.push("  " + bold(s, fit(u, room - 2, ui))); continue; }
+      out.push("  " + bold(s, c.name) + (c.args ? dim(s, " " + c.args) : "") + " ".repeat(w - u.length) + dim(s, fit(c.desc, room - 2 - w, ui)));
+    }
+  }
+  out.push(dim(s, fit("Type / for the command menu: arrows move, Tab or Enter completes, Esc closes.", room, ui)));
+  return out;
+}
+
+export const SLASH_HELP = renderHelp({ color: false, unicode: true, tty: false, columns: 100 }).join("\n");
+
+const MENU_MAX = 8;
+
+// The menu under the input: the selected row has a terracotta pointer and a bold name.
+export function renderMenu(items                         , selected        , ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const pointer = ui.unicode ? "❯" : ">";
+  const nameW = Math.max(...SLASH_COMMANDS.map((c) => c.name.length)) + 2;
+  const start = Math.max(0, Math.min(selected - MENU_MAX + 1, items.length - MENU_MAX));
+  return items.slice(start, start + MENU_MAX).map((c, i) => {
+    const on = start + i === selected;
+    const lead = on ? terracottaBold(s, pointer) + " " : "  ";
+    const name = pad(c.name, nameW);
+    const descRoom = room - 2 - nameW;
+    const desc = descRoom > 4 ? fit(c.desc, descRoom, ui) : "";
+    if (descRoom <= 4) return lead + (on ? terracottaBold(s, fit(c.name, room - 2, ui)) : fit(c.name, room - 2, ui));
+    return lead + (on ? terracottaBold(s, name) + stone(s, desc) : name + dim(s, desc));
+  });
+}
+
+// ---------------------------------------------------------------- the frame
+
+                                                                                                 
+                                                                                                           
+                                                                       
+
+const ESC = "\x1b";
+
+// Draws below the input line and routes keys. One per session, TTY only.
+export class PromptFrame                      {
+           input                                                                     ;
+          rl                       ;
+          shown = 0; // rows drawn below the input line
+          active = false; // the main prompt is being answered (not a y/N question, not a turn)
+          selected = 0;
+          dismissed = false;
+          placeholder = false;
+          lastLine = "";
+          started = false;
+          pasting = false; // between the terminal's paste-start and paste-end marks
+          ctrlC = false; // Ctrl+C was pressed (typed, not pasted)
+          capture                                           ; // a selector or secret prompt owns the keys
+          lastCols = 0;
+          promptStr = "";
+  // Shift+Tab at the prompt (cycles the permission mode); the footer is redrawn after it.
+  onShiftTab                          ;
+
+  // True once the person pressed Ctrl+C. An end of input is not an interrupt.
+  get interrupted()          {
+    return this.ctrlC;
+  }
+          onKey = (s                    , key                 ) => this.key(s, key);
+
+          stdin           ;
+          out          ;
+          ui    ;
+          below                ; // the status lines
+          promptWidth        ;
+
+          paste         ; // bracketed paste is switched on (stdout is the terminal)
+          pasteOk = false; // a prompt that takes typed text is open: pasted text is typed in
+
+  // `opts.paste` false when stdout is not the terminal (a piped one-shot): the escape that switches
+  // bracketed paste on would land in the output instead.
+  constructor(stdin           , out          , ui    , below                , promptWidth        , opts                      = {}) {
+    this.paste = opts.paste ?? true;
+    this.stdin = stdin;
+    this.out = out;
+    this.ui = ui;
+    this.below = below;
+    this.promptWidth = promptWidth;
+    const pass = new PassThrough()                                                                       ;
+    pass.isTTY = true;
+    pass.setRawMode = () => {};
+    this.input = pass;
+  }
+
+  start(rl           )       {
+    this.rl = rl;
+    emitKeypressEvents(this.stdin);
+    this.stdin.setRawMode?.(true);
+    this.stdin.on("keypress", this.onKey);
+    this.stdin.resume();
+    // Bracketed paste: the terminal marks pasted text, so a pasted newline is not an Enter.
+    if (this.paste) this.out.write(`${ESC}[?2004h`);
+    this.started = true;
+    rl.on("close", () => this.stop());
+  }
+
+  // Gives the terminal back: raw mode and bracketed paste off. Safe to call any number of times.
+  stop()       {
+    if (!this.started) return;
+    this.started = false;
+    this.stdin.off("keypress", this.onKey);
+    if (this.paste) this.out.write(`${ESC}[?2004l`);
+    this.stdin.setRawMode?.(false);
+    this.stdin.pause();
+    this.input.end();
+  }
+
+  // KeySource: gives every key to fn and none to readline until the returned function is called.
+  // Pasted text reaches fn only when asked for (a secret), with its line breaks dropped.
+  subscribe(fn       , opts                      = {})             {
+    const mine = { fn, paste: opts.paste === true };
+    this.capture = mine;
+    return () => { if (this.capture === mine) this.capture = undefined; };
+  }
+
+  // The window changed: when the columns differ, redraw the whole frame (see redrawFrame).
+  onResize()       {
+    const cols = this.cols();
+    const prev = this.lastCols || cols;
+    this.lastCols = cols;
+    if (this.active && !this.capture && cols !== prev) this.redrawFrame(prev);
+  }
+
+  // Rebuilds the framed prompt at the current width: the old top rule is erased (it may have
+  // reflowed onto several rows if the window got narrower), then the top rule, the prompt with the
+  // typed text, the bottom rule and the footer are drawn again, so no half-width border is left.
+  redrawFrame(prevCols        )       {
+    if (!this.active) return;
+    const cols = this.cols();
+    const ruleRows = Math.max(1, Math.ceil(Math.max(1, prevCols - 1) / Math.max(1, cols)));
+    this.out.write(`\r${ESC}[${ruleRows}A${ESC}[J` + rule(this.ui) + "\n" + this.promptStr + this.line());
+    this.shown = 0;
+    this.placeholder = false;
+    this.draw();
+  }
+
+          line()         {
+    return (this.rl                                            )?.line ?? "";
+  }
+
+          menuItems()                 {
+    const l = this.line();
+    if (!this.active || this.dismissed || !l.startsWith("/") || /\s/.test(l)) return [];
+    return matchCommands(l);
+  }
+
+  // The rule above the prompt; then the prompt itself is asked by the caller.
+  async ask(promptText        )                  {
+    const rl = this.rl             ;
+    this.promptStr = promptText;
+    this.lastCols = this.cols();
+    this.out.write(rule(this.ui) + "\n");
+    this.active = true;
+    this.pasteOk = true;
+    this.selected = 0;
+    this.dismissed = false;
+    this.lastLine = "";
+    const answer = rl.question(promptText);
+    this.draw();
+    try {
+      return await answer;
+    } finally {
+      this.active = false;
+      this.pasteOk = false;
+    }
+  }
+
+  // A plain prompt with no frame or menu (an ASCII terminal): pasted text is typed in, nothing drawn.
+  async askPlain(promptText        )                  {
+    this.pasteOk = true;
+    try {
+      return await (this.rl             ).question(promptText);
+    } finally {
+      this.pasteOk = false;
+    }
+  }
+
+  // Erases what is drawn below the input line (before Enter, so the transcript stays clean).
+  clear()       {
+    if (this.shown === 0) return;
+    let s = "";
+    for (let i = 0; i < this.shown; i++) s += `\r\n${ESC}[2K`;
+    s += `${ESC}[${this.shown}A${ESC}[${this.cursorCol()}G`;
+    this.out.write(s);
+    this.shown = 0;
+  }
+
+          cursorCol()         {
+    const pos = (this.rl                                                                                  )?.getCursorPos?.();
+    return (pos?.cols ?? this.promptWidth + textWidth(this.line())) + 1;
+  }
+
+          cols()         {
+    return this.ui.columns;
+  }
+
+  // What goes under the input: the rule, then the menu or the status lines.
+  belowLines()           {
+    const items = this.menuItems();
+    if (this.selected >= items.length) this.selected = 0;
+    const body = items.length ? renderMenu(items, this.selected, this.ui) : this.below();
+    return [rule(this.ui), ...body];
+  }
+
+  draw()       {
+    if (!this.active) return;
+    const l = this.line();
+    // A line that wraps would put the frame in the wrong place: draw nothing until it is short.
+    if (this.promptWidth + textWidth(l) >= this.cols() - 1) { this.clear(); return; }
+    const lines = this.belowLines();
+    const n = Math.max(lines.length, this.shown);
+    let s = "";
+    for (let i = 0; i < n; i++) s += `\r\n${ESC}[2K` + (lines[i] ?? "");
+    const col = this.cursorCol();
+    s += `${ESC}[${n}A${ESC}[${col}G`;
+    if (l === "") {
+      s += dim(styleOf(this.ui), fit(PLACEHOLDER, this.cols() - 1 - col, this.ui)) + `${ESC}[${col}G`;
+      this.placeholder = true;
+    } else if (this.placeholder) {
+      s = `${ESC}[K` + s;
+      this.placeholder = false;
+    }
+    this.out.write(s);
+    this.shown = lines.length;
+  }
+
+          forward(seq        )       {
+    this.input.write(seq);
+  }
+
+          replaceLine(text        )       {
+    // ctrl+e (end of line), ctrl+u (delete to the start), then the new text.
+    this.forward("\x05\x15" + text);
+  }
+
+          key(s                    , key                 )       {
+    const seq = key?.sequence ?? s ?? "";
+    if (key?.name === "paste-start") { this.pasting = true; return; }
+    if (key?.name === "paste-end") { this.pasting = false; if (!this.capture) this.after(); return; }
+    if (this.capture) {
+      if (this.pasting) {
+        const k = key?.name;
+        if (this.capture.paste && k !== "return" && k !== "enter" && seq !== "\r" && seq !== "\n") this.capture.fn(s, key);
+        return;
+      }
+      this.capture.fn(s, key);
+      return;
+    }
+    if (!this.pasting && seq === "\x03") this.ctrlC = true;
+    if (this.pasting) {
+      // Pasted text is never a key press. While a y/N question (or a turn) holds the input it is
+      // dropped, so a pasted "y" and newline cannot approve anything. At the prompt it is typed
+      // as text, with each newline as a space so a paste never sends the line.
+      if (!this.pasteOk) return;
+      const name = key?.name;
+      this.forward(name === "return" || name === "enter" || seq === "\r" || seq === "\n" ? " " : seq);
+      return;
+    }
+    if (!this.active) { this.forward(seq); return; }
+    const items = this.menuItems();
+    const name = key?.name;
+    if (name === "tab" && key?.shift) { this.onShiftTab?.(); this.draw(); return; }
+    // A lone Esc closes the menu (node reports it with meta set on some versions).
+    if (items.length && name === "escape") { this.dismissed = true; this.draw(); return; }
+    if (items.length && !key?.ctrl && !key?.meta) {
+      if (name === "up" || name === "down") {
+        this.selected = (this.selected + (name === "up" ? -1 : 1) + items.length) % items.length;
+        this.draw();
+        return;
+      }
+      const pick = items[this.selected]                ;
+      if (name === "tab") { this.replaceLine(pick.args ? pick.name + " " : pick.name); this.after(); return; }
+      if (name === "return" || name === "enter") {
+        this.clear();
+        this.replaceLine(pick.name);
+        this.forward("\r");
+        return;
+      }
+    }
+    if (name === "return" || name === "enter") { this.clear(); this.forward(seq); return; }
+    if (name === "escape" && this.line() === "") return; // nothing to dismiss; a lone Esc is ignored
+    this.forward(seq);
+    this.after();
+  }
+
+  // Readline handles the forwarded keys on the next tick; redraw after it has.
+          after()       {
+    setImmediate(() => {
+      const l = this.line();
+      if (l !== this.lastLine) { this.dismissed = false; this.selected = 0; }
+      this.lastLine = l;
+      this.draw();
+    });
+  }
+
+  redraw()       {
+    this.draw();
+  }
+}