@synqa/cli 0.0.0-stage → 1.1.1

package/dist/ui.js

@@ -0,0 +1,574 @@
+// Terminal chrome: the welcome panel, the waiting spinner, tool-call cards and the per-turn footer.
+// Everything here is pure or takes a stream-like object, so it is tested with fakes.
+//
+// Safety: the only control sequences this file ever writes are the fixed strings below (carriage
+// return and "erase line" for the spinner). Every piece of text that comes from the model, a tool
+// or the network goes through sanitize() first, which removes escape sequences and control
+// characters, so chrome around it cannot be turned into cursor control.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { formatUsd } from "./account.js";
+                                                           
+import { sanitize, visibleEscapes } from "./sanitize.js";
+import { groupDigits } from "./statusbar.js";
+import { CONTEXT_TOKENS } from "./tiers.js";
+                                               
+import { bold, colorDepth, colorEnabled, detectBackground, dim, red, sage, stone, terracotta, terracottaBold } from "./theme.js";
+                                                                
+
+// ---------------------------------------------------------------- terminal capabilities
+
+                  
+                                
+                                                                            
+                                                                             
+                  
+                                                                        
+                                                                                        
+  
+
+                                              
+
+// UTF-8 detection from the locale variables; Windows Terminal, VS Code and ConEmu are UTF-8 safe
+// even without a locale. TERM=dumb and the old Windows console get ASCII.
+export function detectUnicode(env     , platform         = process.platform)          {
+  if (env.TERM === "dumb") return false;
+  if (platform === "win32") return Boolean(env.WT_SESSION || env.TERM_PROGRAM === "vscode" || env.ConEmuANSI === "ON");
+  const loc = env.LC_ALL || env.LC_CTYPE || env.LANG || "";
+  if (loc === "") return true; // unset: modern terminals are UTF-8
+  return /utf-?8/i.test(loc);
+}
+
+                                                            
+
+export function makeUi(env     , out         , platform         = process.platform)     {
+  const tty = Boolean(out.isTTY) && env.TERM !== "dumb";
+  // `columns` is read on every use, so a resized window is picked up by the next render.
+  const cols = () => (typeof out.columns === "number" && out.columns > 0 ? Math.floor(out.columns) : 80);
+  return {
+    color: colorEnabled(env, tty),
+    depth: colorDepth(env),
+    bg: detectBackground(env),
+    unicode: detectUnicode(env, platform),
+    tty,
+    get columns() { return Math.max(20, cols()); },
+  };
+}
+
+export const styleOf = (ui    )        => ({ color: ui.color, depth: ui.depth, bg: ui.bg });
+
+               
+                                                                       
+                                                                                  
+  
+
+const UNI         = {
+  tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│",
+  ell: "…", dot: "·", bolt: "⚡", ok: "✓", bad: "✗",
+  spin: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+};
+const ASCII         = {
+  tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|",
+  ell: "...", dot: "|", bolt: "*", ok: "ok", bad: "x",
+  spin: ["|", "/", "-", "\\"],
+};
+export const glyphs = (ui    )         => (ui.unicode ? UNI : ASCII);
+
+// ---------------------------------------------------------------- text fitting
+
+// Terminal cell width of one code point: 0 for combining marks, 2 for wide East Asian and emoji.
+// Emoji with emoji presentation in the U+2000-2BFF blocks: terminals draw them two cells wide.
+// Text-presentation symbols such as the check mark (U+2713) stay one cell.
+const WIDE_SYMBOLS                                           = [
+  [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3], [0x25fd, 0x25fe], [0x2614, 0x2615],
+  [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693], [0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be],
+  [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa], [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c],
+  [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797], [0x27b0, 0x27b0], [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+];
+
+// Terminal cell width of one code point: 0 for combining marks and variation selectors (all of
+// \p{M}) and zero width format characters, 2 for wide East Asian characters and emoji.
+function cellWidth(cp        )         {
+  if (cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0x2060) return 0;
+  if (/^\p{M}$/u.test(String.fromCodePoint(cp))) return 0;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe6f) || (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x1f300 && cp <= 0x1faff) || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) return 2;
+  for (const [lo, hi] of WIDE_SYMBOLS) if (cp >= lo && cp <= hi) return 2;
+  return 1;
+}
+
+export function textWidth(s        )         {
+  let w = 0;
+  for (const ch of s) w += cellWidth(ch.codePointAt(0)          );
+  return w;
+}
+
+// One safe printable line: escapes and control characters removed, whitespace collapsed.
+export function oneLine(s        )         {
+  return sanitize(s).replace(/\s+/g, " ").trim();
+}
+
+// Cuts to `max` cells, keeping the start, ending with an ellipsis.
+export function fit(s        , max        , ui    )         {
+  if (max <= 0) return "";
+  if (textWidth(s) <= max) return s;
+  const ell = glyphs(ui).ell;
+  const room = max - ell.length;
+  if (room <= 0) return ell.slice(0, max);
+  let out = "";
+  let w = 0;
+  for (const ch of s) {
+    const cw = cellWidth(ch.codePointAt(0)          );
+    if (w + cw > room) break;
+    out += ch;
+    w += cw;
+  }
+  return out + ell;
+}
+
+// Cuts to `max` cells, keeping the END (the file name matters most in a path).
+export function fitPath(s        , max        , ui    )         {
+  if (max <= 0) return "";
+  if (textWidth(s) <= max) return s;
+  const ell = glyphs(ui).ell;
+  const room = max - ell.length;
+  if (room <= 0) return ell.slice(0, max);
+  const chars = Array.from(s);
+  let out = "";
+  let w = 0;
+  for (let i = chars.length - 1; i >= 0; i--) {
+    const cw = cellWidth((chars[i]          ).codePointAt(0)          );
+    if (w + cw > room) break;
+    out = chars[i] + out;
+    w += cw;
+  }
+  return ell + out;
+}
+
+export function shortenHome(path        , home         = homedir())         {
+  if (!home || home === "/" ) return path;
+  if (path === home) return "~";
+  if (path.startsWith(home + "/") || path.startsWith(home + "\\")) return "~" + path.slice(home.length);
+  return path;
+}
+
+export const pad = (s        , w        ) => s + " ".repeat(Math.max(0, w - textWidth(s)));
+
+// ---------------------------------------------------------------- version
+
+// package.json sits next to src/ and dist/, in a checkout and in the installed package.
+export function readVersion()         {
+  try {
+    const raw = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))                         ;
+    return typeof raw.version === "string" && /^[\w.+-]{1,32}$/.test(raw.version) ? raw.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// ---------------------------------------------------------------- balance
+
+                     
+                                    
+                                                                             
+                            
+
+export function balanceFrom(r               )          {
+  if (r.ok) return { kind: "ok", account: r.account };
+  return r.notFound ? { kind: "not-yet" } : { kind: "unavailable" };
+}
+
+export function balanceLine(b         )         {
+  if (b.kind === "not-yet") return "balance not available yet";
+  if (b.kind === "unavailable") return "balance unavailable";
+  const a = b.account;
+  const credit = `${formatUsd(a.creditRemaining)} credit`;
+  if (a.poolRemaining !== null && a.poolLimit !== null) return `${credit} · weekly pool ${formatUsd(a.poolRemaining)} of ${formatUsd(a.poolLimit)}`;
+  return credit;
+}
+
+// ---------------------------------------------------------------- start screen
+
+                          
+                  
+             
+                  
+              
+                
+                     
+                   
+                                                                                          
+  
+
+// "Synqa." on one line: the name bold in the terminal's own text colour, the period terracotta.
+function paintName(s       )         {
+  return bold(s, "Synqa") + terracotta(s, ".");
+}
+
+// The wordmark in half-block letters, four rows: the S at cap height, y n q a at x-height with the
+// y and q descenders on the last row. Letters carry no colour code, so they are drawn in the
+// terminal's own text colour (ink on a light background, bone-like on a dark one); the full stop
+// is a terracotta square on the baseline.
+const LETTERS                                    = {
+  S: ["▄▀▀▀", " ▀▀▄", "▄▄▄▀", "    "],
+  y: ["    ", "█  █", "▀▄▄█", "▄▄▄▀"],
+  n: ["    ", "█▀▀▄", "█  █", "    "],
+  q: ["    ", "▄▀▀█", "▀▄▄█", "   █"],
+  a: ["    ", "▄▀▀█", "▀▄▄█", "    "],
+};
+export const WORDMARK                    = [0, 1, 2, 3].map((r) => ["S", "y", "n", "q", "a"].map((c) => (LETTERS[c]            )[r]).join(" ").trimEnd());
+export const WORDMARK_W = Math.max(...WORDMARK.map(textWidth)) + 2; // plus a space and the dot
+const DOT_ROW = 2;
+
+// The start screen header, in the style of modern coding CLIs, with no box: the Synqa wordmark (60 columns and up,
+// on a UTF-8 terminal), or a one-line bold "Synqa." below that; then dim lines with the version,
+// tier and effort, and the workspace; then dim "⎿" lines for notes and warnings. Every line fits
+// in columns - 1 cells (visible width, escapes not counted), so nothing wraps. Fields are our own
+// tables or sanitized; the API key is never an input.
+export function renderBanner(info            , ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const sep = ui.unicode ? " · " : " | ";
+  const version = `v${oneLine(info.version)}`;
+  const effort = `${info.effort ?? "default"} effort`;
+  const where = oneLine(shortenHome(info.cwd, info.home));
+  const notes                                         = [];
+  notes.push([info.notesChars > 0 ? `AGENTS.md loaded (${groupDigits(info.notesChars)} chars)` : "no AGENTS.md yet: /init writes one", (t) => dim(s, t)]);
+  if (info.balance.kind === "ok") notes.push([balanceLine(info.balance).replace(" · ", sep), (t) => sage(s, t)]);
+  else notes.push([balanceLine(info.balance), (t) => dim(s, t)]);
+  for (const w of info.warnings ?? []) notes.push([oneLine(w), (t) => dim(s, t)]);
+  const lead = "  ";
+  const hook = ui.unicode ? "⎿ " : "- ";
+  const noteLines = notes.map(([t, p]) => dim(s, lead + hook) + p(fit(t, room - lead.length - hook.length, ui)));
+  const w = room - lead.length;
+  const meta = [
+    lead + dim(s, fit(`${version}${sep}${info.tier.display}${sep}${effort}`, w, ui)),
+    lead + dim(s, fitPath(where, w, ui)),
+  ];
+  if (!ui.unicode || ui.columns < 60) {
+    const name = w >= 6 ? lead + paintName(s) : lead + bold(s, fit("Synqa.", w, ui));
+    return [name, ...meta, ...noteLines];
+  }
+  const mark = WORDMARK.map((row, i) => lead + row + (i === DOT_ROW ? " " + terracotta(s, "▄") : ""));
+  return [...mark, "", ...meta, ...noteLines];
+}
+
+// A thin rule across the terminal, one cell short of the edge so it never wraps.
+export function rule(ui    )         {
+  return stone(styleOf(ui), (ui.unicode ? "─" : "-").repeat(Math.max(1, ui.columns - 1)));
+}
+
+export const PROMPT_MARK = (ui    ) => (ui.unicode ? "❯" : ">");
+
+export function promptText(ui    )         {
+  return `${terracottaBold(styleOf(ui), PROMPT_MARK(ui))} `;
+}
+
+export const PLACEHOLDER = 'Try "explain this project", or type / for commands';
+
+                          
+             
+                 
+              
+                
+                                  
+                                                            
+                      
+                                                                          
+                    
+  
+
+// The two lines under the input: what is known about the session, then key hints. Unknown values
+// are left out (no "?" or "-" placeholders); separators are dim. The least important parts drop
+// first when the line would not fit in columns - 1 cells.
+export function renderStatusLines(p            , ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const sep = ui.unicode ? " · " : " | ";
+  const home = shortenHome(p.cwd, p.home);
+  const ws = home === "~" ? "~" : oneLine(home.split(/[\\/]/).filter(Boolean).pop() ?? home);
+                                                                     
+  const st = (t        ) => stone(s, t);
+  const parts         = [{ k: "tier", t: p.tier.display, paint: (t) => terracottaBold(s, t) }];
+  if (p.effort !== "default") parts.push({ k: "effort", t: `${p.effort} effort`, paint: st });
+  parts.push({ k: "ws", t: Array.from(ws).slice(0, 32).join(""), paint: st });
+  const ctxMax = p.contextMax ?? CONTEXT_TOKENS;
+  if (p.contextTokens) parts.push({ k: "ctx", t: `ctx ${Math.min(100, Math.round((100 * p.contextTokens) / ctxMax))}%`, paint: st });
+  if (p.routing && p.routing !== "?") parts.push({ k: "routing", t: Array.from(oneLine(p.routing)).slice(0, 12).join(""), paint: st });
+  parts.push({ k: "tokens", t: `${groupDigits(p.tokens)} tokens`, paint: st });
+  const right = p.balance && p.balance.kind === "ok" ? `${formatUsd(p.balance.account.creditRemaining)} credit` : "";
+  const kept = parts.slice();
+  let showRight = right !== "";
+  const leftW = () => kept.reduce((w, x, i) => w + textWidth(x.t) + (i ? sep.length : 0), 0);
+  const fits = () => leftW() + (showRight ? 2 + textWidth(right) : 0) <= room;
+  // Dropped first to last: routing, ctx, workspace, effort, the balance, then tokens.
+  for (const k of ["routing", "ctx", "ws", "effort", "right", "tokens"]) {
+    if (fits()) break;
+    if (k === "right") { showRight = false; continue; }
+    const i = kept.findIndex((x) => x.k === k);
+    if (i > 0) kept.splice(i, 1);
+  }
+  let line = kept.map((x) => x.paint(x.t)).join(dim(s, sep));
+  if (!fits()) line = terracottaBold(s, fit(p.tier.display, room, ui));
+  else if (showRight) line += " ".repeat(Math.max(2, room - leftW() - textWidth(right))) + sage(s, right);
+  return [line, keyHints(ui)];
+}
+
+// "/ commands · ↑↓ history · esc clear · ctrl+c quit": keys bold, labels dim, cut to fit.
+export function keyHints(ui    )         {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const hints                          = [["/", "commands"], [ui.unicode ? "↑↓" : "up/down", "history"], ["tab", "complete"], ["ctrl+c", "quit"]];
+  const sep = ui.unicode ? " · " : " | ";
+  const kept = hints.slice();
+  const w = () => kept.reduce((n, [k, l], i) => n + k.length + 1 + l.length + (i ? sep.length : 0), 0);
+  while (kept.length > 1 && w() > room) kept.splice(kept.length - 2, 1);
+  if (w() > room) return dim(s, fit("/ for commands", room, ui));
+  return kept.map(([k, l]) => bold(s, k) + " " + dim(s, l)).join(dim(s, sep));
+}
+
+// ---------------------------------------------------------------- spinner
+
+                                                       
+                              
+                                                                                              
+         
+                     
+                                                     
+                                    
+                      
+  
+
+const CR_ERASE = "\r\x1b[2K";
+
+export class Spinner {
+          out            ;
+          o                ;
+          timer          = undefined;
+          t0 = 0;
+          frame = 0;
+          drawn = false;
+
+  constructor(out            , o                ) {
+    this.out = out;
+    this.o = o;
+  }
+
+  get active()          {
+    return this.timer !== undefined;
+  }
+
+  start()       {
+    if (!this.o.enabled || this.timer !== undefined) return;
+    const now = this.o.now ?? (() => Date.now());
+    this.t0 = now();
+    this.frame = 0;
+    this.draw();
+    const set = this.o.setTimer ?? ((fn            , ms        ) => {
+      const h = setInterval(fn, ms);
+      (h                          ).unref?.();
+      return h;
+    });
+    this.timer = set(() => this.draw(), this.o.intervalMs ?? 80);
+  }
+
+  elapsedText()         {
+    const now = this.o.now ?? (() => Date.now());
+    return `${(Math.max(0, now() - this.t0) / 1000).toFixed(1)}s`;
+  }
+
+          draw()       {
+    const g = glyphs(this.o.ui);
+    const f = g.spin[this.frame++ % g.spin.length]          ;
+    const st = styleOf(this.o.ui);
+    const text = fit(`${f} waiting ${this.elapsedText()}`, this.o.ui.columns - 1, this.o.ui);
+    // The frame is terracotta, the rest stone. fit() keeps the frame first, so the split is safe.
+    this.out.write(CR_ERASE + terracotta(st, text.slice(0, f.length)) + stone(st, text.slice(f.length)));
+    this.drawn = true;
+  }
+
+  // Clears the line and stops. Safe to call at any time, any number of times.
+  stop()       {
+    if (this.timer !== undefined) {
+      (this.o.clearTimer ?? ((h         ) => clearInterval(h                                  )))(this.timer);
+      this.timer = undefined;
+    }
+    if (this.drawn) {
+      this.out.write(CR_ERASE);
+      this.drawn = false;
+    }
+  }
+}
+
+// ---------------------------------------------------------------- tool cards
+
+// The one piece of an argument list worth showing in a card header.
+export function toolLabel(name        , rawArgs        )         {
+  let a                          = {};
+  try {
+    const v = JSON.parse(rawArgs || "{}");
+    if (v && typeof v === "object" && !Array.isArray(v)) a = v                           ;
+  } catch { /* shown as no label */ }
+  const pick = (k        ) => (typeof a[k] === "string" ? (a[k]          ) : "");
+  switch (name) {
+    case "read_file": case "write_file": case "edit_file": return visibleEscapes(pick("path"));
+    case "glob": case "grep": return visibleEscapes(pick("pattern"));
+    case "bash": return visibleEscapes(pick("command"));
+    default: return "";
+  }
+}
+
+export function cardHeader(name        , rawArgs        , ui    )         {
+  const g = glyphs(ui);
+  const s = styleOf(ui);
+  const prefix = `${g.tl}${g.h} `;
+  const n = fit(Array.from(oneLine(name)).slice(0, 40).join("") || "tool", Math.max(8, ui.columns - 1 - textWidth(prefix)), ui);
+  const label = oneLine(toolLabel(name, rawArgs));
+  const room = ui.columns - 1 - textWidth(prefix) - textWidth(n);
+  if (!label) return stone(s, prefix) + bold(s, n);
+  const sepText = ` ${g.dot} `;
+  const shown = name === "bash" ? fit(label, room - sepText.length, ui) : fitPath(label, room - sepText.length, ui);
+  return stone(s, prefix) + bold(s, n) + stone(s, sepText + shown);
+}
+
+// One short line about what a tool returned. No file contents are shown for read, glob or grep.
+export function summarizeResult(name        , result        )                                {
+  const lines = result.split("\n");
+  const first = oneLine(lines[0] ?? "");
+  if (result === "denied by user") return { ok: false, text: "denied" };
+  if (result.startsWith("error:")) return { ok: false, text: first.replace(/^error:\s*/, "") || "error" };
+  switch (name) {
+    case "read_file": return { ok: true, text: `${groupDigits(lines.length)} lines` };
+    case "glob": case "grep": {
+      const n = result.trim() === "" || /^no (matches|files)/i.test(result.trim()) ? 0 : lines.filter((l) => l.trim() !== "").length;
+      return { ok: true, text: `${groupDigits(n)} ${n === 1 ? "match" : "matches"}` };
+    }
+    case "bash": {
+      const body = lines.filter((l) => l.trim() !== "");
+      const code = /^\[(exit \d+|signal [^\]]*)\]$/.exec(body[body.length - 1] ?? "");
+      const status = code ? (code[1]          ) : "done";
+      const firstOut = oneLine(body[0] ?? "");
+      const hasOut = code ? body.length > 1 : body.length > 0;
+      return { ok: status === "exit 0" || !code, text: hasOut ? `${status} · ${firstOut}` : status };
+    }
+    default: return { ok: true, text: first || "done" };
+  }
+}
+
+export function cardFooter(name        , result        , ui    )         {
+  const g = glyphs(ui);
+  const s = styleOf(ui);
+  const r = summarizeResult(name, result);
+  const prefix = `${g.bl}${g.h} `;
+  const mark = r.ok ? sage(s, g.ok) : red(s, g.bad);
+  const text = r.text.replace(" · ", ui.unicode ? " · " : " | ");
+  const room = ui.columns - 1 - prefix.length - (r.ok ? g.ok.length : g.bad.length) - 1;
+  return stone(s, prefix) + mark + " " + stone(s, fit(text, room, ui));
+}
+
+// Puts the card's left edge in front of every line of a block (the diff preview).
+export function cardBody(text        , ui    )         {
+  const bar = stone(styleOf(ui), glyphs(ui).v);
+  return text.split("\n").map((l) => bar + l).join("\n");
+}
+
+// ---------------------------------------------------------------- footer
+
+                           
+                  
+                     
+                                                    
+                                              
+  
+
+export function formatMs(ms        )         {
+  return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
+}
+
+const good = (n                    )              => n !== undefined && Number.isFinite(n);
+
+// `⚡ 340ms TTFT · 68.4 tok/s · local · $9.98 left`. Parts that are unknown are left out, and the
+// least important parts drop first when the line would not fit.
+export function formatFooter(p             , ui    )         {
+  const g = glyphs(ui);
+  const ttft = good(p.ttftMs) && p.ttftMs >= 0 ? `${formatMs(p.ttftMs)} TTFT` : "";
+  const rate = good(p.tokPerSec) && p.tokPerSec > 0 ? `${p.tokPerSec.toFixed(1)} tok/s` : "";
+  const route = p.routing && p.routing !== "?" ? Array.from(oneLine(p.routing)).slice(0, 12).join("") : "";
+  const left = good(p.creditLeft) ? `${formatUsd(p.creditLeft)} left` : "";
+  const join = (parts          ) => {
+    const kept = parts.filter((x) => x !== "");
+    return kept.length ? `${g.bolt} ${kept.join(` ${g.dot} `)}` : "";
+  };
+  const width = ui.columns - 1;
+  const variants = [[ttft, rate, route, left], [ttft, rate, route], [ttft, rate], [ttft], [rate]];
+  for (const v of variants) {
+    const t = join(v);
+    if (t !== "" && textWidth(t) <= width) return t;
+  }
+  const any = join([ttft, rate, route, left]);
+  return any === "" ? "" : fit(any, width, ui);
+}
+
+// ---------------------------------------------------------------- turn renderer
+
+                                                      
+
+// Turns agent events into terminal output. One instance per session.
+export class TurnRenderer {
+          out           ;
+          ui    ;
+          spinner         ;
+          midLine = false; // the last thing written was model text with no trailing newline
+
+  constructor(out           , ui    , spinner         ) {
+    this.out = out;
+    this.ui = ui;
+    this.spinner = spinner;
+  }
+
+  // A request is about to be sent: show that we are waiting for the first token.
+  requestStart()       {
+    this.spinner.start();
+  }
+
+  // Model text. The spinner is erased first; the text is stripped of every escape sequence.
+  text(t        )       {
+    this.spinner.stop();
+    const clean = sanitize(t);
+    if (clean === "") return;
+    this.out.write(clean);
+    this.midLine = !clean.endsWith("\n");
+  }
+
+  // The request finished (with or without a tool call).
+  requestEnd()       {
+    this.spinner.stop();
+  }
+
+  toolStart(name        , rawArgs        )       {
+    this.spinner.stop();
+    this.out.write((this.midLine ? "\n" : "") + cardHeader(name, rawArgs, this.ui) + "\n");
+    this.midLine = false;
+  }
+
+  toolResult(name        , result        )       {
+    this.out.write(cardFooter(name, result, this.ui) + "\n");
+  }
+
+  // The diff preview, inside the card.
+  body(text        )         {
+    return cardBody(text, this.ui);
+  }
+
+  // Leaves the cursor at the start of a line after a turn.
+  turnEnd()       {
+    this.spinner.stop();
+    if (this.midLine) this.out.write("\n");
+    this.midLine = false;
+  }
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@synqa/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Synqa terminal coding agent",
+  "type": "module",
+  "bin": {
+    "synqa": "bin/synqa.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.18.0 || >=23.6.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "test": "node --test \"test/*.test.ts\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://synqa.ca",
+  "bugs": {
+    "url": "https://synqa.ca/client-dashboard#support"
+  },
+  "keywords": [
+    "synqa",
+    "cli",
+    "coding-agent",
+    "terminal",
+    "ai"
+  ],
+  "license": "UNLICENSED"
+}