@synqa/cli 1.1.0 → 1.1.1

package/dist/prompt.js

@@ -0,0 +1,330 @@
+// 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: "Switch tier", group: "Session" },
+  { name: "/effort", args: "default|low|medium", desc: "Set reasoning effort", 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: "/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)
+
+  // 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();
+  }
+
+          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.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; this.after(); 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;
+    // 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") {
+        if (pick.args && this.line().toLowerCase() !== pick.name) { this.replaceLine(pick.name + " "); this.after(); return; }
+        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();
+  }
+}

package/dist/statusbar.js

@@ -26,22 +26,29 @@ export function formatRate(tps                    )         {
 }
 
 // Fits `width` columns by dropping segments from the least important end; the tier always stays.
+// Unknown values (routing "?", no TTFT or rate yet) are left out, never shown as "?" or "-".
 export function formatStatus(p             , width         )         {
   const tier = p.tier.display;
   const effort = p.effort === "default" ? "" : `effort ${p.effort}`;
-  const full = [tier, effort, p.routing, `TTFT ${formatTtft(p.ttftMs)}`, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tokens`];
+  const route = p.routing && p.routing !== "?" ? p.routing : "";
+  const ttft = formatTtft(p.ttftMs);
+  const t = ttft === "-" ? "" : `TTFT ${ttft}`;
+  const r = formatRate(p.tokPerSec);
+  const rate = r === "-" ? "" : r;
+  const toks = `${groupDigits(p.tokens)} tokens`;
+  const short = `${groupDigits(p.tokens)} tok`;
   const variants = [
-    full,
-    [tier, p.routing, `TTFT ${formatTtft(p.ttftMs)}`, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tokens`],
-    [tier, p.routing, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tok`],
-    [tier, p.routing, `${groupDigits(p.tokens)} tok`],
-    [tier, p.routing],
+    [tier, effort, route, t, rate, toks],
+    [tier, route, t, rate, toks],
+    [tier, route, rate, short],
+    [tier, route, short],
+    [tier, route],
   ];
   const join = (parts          ) => parts.filter((x) => x !== "").join(" | ");
-  if (width === undefined) return join(full);
+  if (width === undefined) return join(variants[0]            );
   for (const v of variants) {
-    const t = join(v);
-    if (t.length <= width) return t;
+    const s = join(v);
+    if (s.length <= width) return s;
   }
   const last = join(variants[variants.length - 1]            );
   return width > 1 ? last.slice(0, width - 1) + "…" : last.slice(0, width);

package/dist/theme.js

@@ -1,7 +1,8 @@
 // The Synqa palette and every colour escape the CLI emits. This file is the only place that builds
 // an escape sequence for colour; text from the model or from tools never reaches it as a code.
-// 24-bit colour when the terminal says it has it (COLORTERM=truecolor|24bit), otherwise the nearest
-// xterm-256 index. NO_COLOR, a non-TTY or TERM=dumb turn all of it off.
+// 24-bit colour only when the terminal is known to draw it (COLORTERM=truecolor|24bit, or a
+// TERM_PROGRAM known for it); macOS Terminal.app and anything unknown get xterm-256 colours, which
+// every modern terminal draws. NO_COLOR, a non-TTY or TERM=dumb turn all of it off.
 
                                                     
 
@@ -12,8 +13,11 @@ export const SAGE      = [0x4a, 0x7c, 0x59]; // #4a7c59 sage: balance highlights
 
                                 
 
-// depth is optional so a bare { color: true } keeps meaning 24-bit.
-                                                           
+// depth is optional; absent means 256 colours, the safe choice (Terminal.app has no 24-bit colour).
+// bg is the terminal background when the environment says so (COLORFGBG); bone text is used only
+// on a known dark background, plain bold otherwise, so names read on light and dark themes.
+                                          
+                                                                            
 
 export function colorEnabled(env                                    , isTTY         )          {
   if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return false;
@@ -21,9 +25,30 @@ export function colorEnabled(env                                    , isTTY
   return isTTY;
 }
 
+// Terminals that draw 24-bit colour, by TERM_PROGRAM (compared lower case).
+const TRUECOLOR_PROGRAMS = new Set(["iterm.app", "wezterm", "vscode", "ghostty", "hyper", "tabby", "warpterminal", "rio", "kitty", "alacritty", "contour", "zed"]);
+
 export function colorDepth(env                                    )             {
+  const program = (env.TERM_PROGRAM ?? "").toLowerCase();
+  // Terminal.app before macOS 26 misdraws 24-bit escapes, and a COLORTERM copied from another
+  // terminal's profile (or passed through ssh or tmux) must not switch them on there.
+  if (program === "apple_terminal") return 8;
   const c = (env.COLORTERM ?? "").toLowerCase();
-  return c === "truecolor" || c === "24bit" ? 24 : 8;
+  if (c === "truecolor" || c === "24bit") return 24;
+  if (TRUECOLOR_PROGRAMS.has(program)) return 24;
+  const term = (env.TERM ?? "").toLowerCase();
+  if (/(^|-)(kitty|alacritty|direct|truecolor|ghostty|wezterm)($|-)/.test(term) || term.endsWith("-direct")) return 24;
+  return 8;
+}
+
+// COLORFGBG ("15;0", or "15;default;0") names the background colour index when a terminal sets
+// it (rxvt, Konsole, iTerm2 with the option on). 0-6 and 8 are dark; 7 and 9-15 are light.
+export function detectBackground(env                                    )                         {
+  const raw = env.COLORFGBG;
+  if (!raw) return undefined;
+  const bg = Number(raw.split(";").pop());
+  if (!Number.isInteger(bg) || bg < 0 || bg > 15) return undefined;
+  return bg === 7 || bg >= 9 ? "light" : "dark";
 }
 
 const CUBE = [0, 95, 135, 175, 215, 255]         ;
@@ -53,8 +78,17 @@ export function rgbTo256(rgb     )         {
 const RESET = "\x1b[0m";
 
 // The SGR parameters that select `rgb` as the foreground.
+// Hand-picked 256-colour stand-ins where the nearest match loses the brand: the nearest index for
+// terracotta (167) is a pink salmon; 166 (#d75f00) keeps the burnt orange and reads on light and
+// dark backgrounds.
+const TUNED_256 = new Map                ([[TERRACOTTA.join(","), 166]]);
+
+export function to256(rgb     )         {
+  return TUNED_256.get(rgb.join(",")) ?? rgbTo256(rgb);
+}
+
 export function fgParams(depth                        , rgb     )         {
-  return depth === 8 ? `38;5;${rgbTo256(rgb)}` : `38;2;${rgb[0]};${rgb[1]};${rgb[2]}`;
+  return depth === 24 ? `38;2;${rgb[0]};${rgb[1]};${rgb[2]}` : `38;5;${to256(rgb)}`;
 }
 
 function paint(s       , params        , text        )         {
@@ -65,8 +99,14 @@ export function terracotta(s       , text        )         {
   return paint(s, fgParams(s.depth, TERRACOTTA), text);
 }
 
+// Bone on a known dark background; plain bold (the terminal's own text colour) otherwise, because
+// bone is nearly invisible on a light background.
 export function boneBold(s       , text        )         {
-  return paint(s, `1;${fgParams(s.depth, BONE)}`, text);
+  return paint(s, s.bg === "dark" ? `1;${fgParams(s.depth, BONE)}` : "1", text);
+}
+
+export function terracottaBold(s       , text        )         {
+  return paint(s, `1;${fgParams(s.depth, TERRACOTTA)}`, text);
 }
 
 export function stone(s       , text        )         {