@synqa/cli 0.0.0-stage → 1.1.0

package/dist/ui.js

@@ -0,0 +1,514 @@
+// 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 { accent, bold, boneBold, colorDepth, colorEnabled, red, sage, stone, stoneBold, terracotta } 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),
+    unicode: detectUnicode(env, platform),
+    tty,
+    get columns() { return Math.max(20, cols()); },
+  };
+}
+
+export const styleOf = (ui    )        => ({ color: ui.color, depth: ui.depth });
+
+               
+                                                                       
+                                                                                  
+  
+
+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;
+}
+
+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;
+}
+
+// ---------------------------------------------------------------- banner
+
+                          
+                  
+             
+              
+                
+                     
+                   
+  
+
+// "Synqa. CLI v1.1.0" with the name in bold bone and the period in terracotta. `text` may have
+// been cut by fit(); anything that no longer starts with "Synqa." is painted whole.
+function paintTitle(s       , text        )         {
+  if (!text.startsWith("Synqa.")) return boneBold(s, text);
+  return boneBold(s, "Synqa") + terracotta(s, ".") + boneBold(s, text.slice(6));
+}
+
+const TILE_W = 6;
+const TILE_GAP = 2;
+
+// The 3-line monogram: a rounded terracotta tile with a bold bone S and a terracotta period.
+function monogram(s       )           {
+  return [
+    terracotta(s, "╭────╮"),
+    terracotta(s, "│ ") + boneBold(s, "S") + terracotta(s, ". │"),
+    terracotta(s, "╰────╯"),
+  ];
+}
+
+// A boxed welcome panel. Fields are plain text built from our own tables or sanitized; the API key
+// is never an input. On a terminal that is not UTF-8, or a very narrow one, there is no box or
+// tile: a "[S.] Synqa. CLI v..." line and the rows.
+export function renderBanner(info            , ui    )           {
+  const s = styleOf(ui);
+  const sep = ui.unicode ? " · " : " | ";
+  const notes = info.notesChars > 0 ? `AGENTS.md loaded (${groupDigits(info.notesChars)} chars)` : "no AGENTS.md";
+  const balance = balanceLine(info.balance).replace(" · ", sep);
+  const balancePaint = (t        ) => (info.balance.kind === "ok" ? sage(s, t) : stone(s, t));
+  const rows                                                 = [
+    ["Tier", `${info.tier.id} (${info.tier.display})`, (t) => boneBold(s, t)],
+    ["Workspace", oneLine(shortenHome(info.cwd, info.home)), (t) => t],
+    ["Notes", notes, (t) => t],
+    ["Balance", balance, balancePaint],
+  ];
+  const version = oneLine(info.version);
+  const title = `Synqa. CLI v${version}`;
+  const labelW = Math.max(...rows.map((r) => r[0].length)) + 2;
+  const minBox = 30;
+  if (!ui.unicode || ui.columns < minBox) {
+    const room = ui.columns - 1;
+    const head = fit(`[S.] ${title}`, room, ui);
+    const first = head.startsWith("[S.] ")
+      ? terracotta(s, "[S.]") + " " + paintTitle(s, head.slice(5))
+      : boneBold(s, head);
+    return [first, ...rows.map(([l, v, p]) => {
+      const text = fit(`  ${pad(l, labelW)}${v}`, room, ui);
+      const lead = 2 + labelW;
+      return text.length <= lead ? stoneBold(s, text) : stoneBold(s, text.slice(0, lead)) + p(text.slice(lead));
+    })];
+  }
+  const tile = ui.columns >= 46;
+  const left = tile ? TILE_W + TILE_GAP : 0;
+  const natural = Math.max(textWidth(title) + 4, left + Math.max(...rows.map((r) => labelW + textWidth(r[1])))) + 4;
+  const width = Math.min(natural, ui.columns - 1);
+  const inner = width - 4; // "│ " ... " │"
+  const edge = (t        ) => stone(s, t);
+  const top = (() => {
+    const t = fit(title, width - 6, ui);
+    const fill = width - 5 - textWidth(t); // "╭─ " + title + " " + fill + "╮"
+    return edge("╭─ ") + paintTitle(s, t) + edge(" " + "─".repeat(Math.max(0, fill)) + "╮");
+  })();
+  const mono = tile ? monogram(s) : [];
+  const body = rows.map(([label, value, paint], i) => {
+    const lead = tile ? (mono[i] ?? " ".repeat(TILE_W)) + " ".repeat(TILE_GAP) : "";
+    const v = fit(value, inner - left - labelW, ui);
+    const gap = " ".repeat(Math.max(0, inner - left - labelW - textWidth(v)));
+    return edge("│") + " " + lead + stoneBold(s, pad(label, labelW)) + paint(v) + gap + " " + edge("│");
+  });
+  const bottom = edge("╰" + "─".repeat(width - 2) + "╯");
+  return [top, ...body, bottom];
+}
+
+// ---------------------------------------------------------------- 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.0",
+  "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"
+}