@synqa/cli 1.1.0 → 1.1.1

package/README.md

@@ -12,7 +12,7 @@ Blink 5.5, Sonata 6.0 and Aeon 6.5.
 - [Slash commands](#slash-commands)
 - [Welcome panel and turn footer](#welcome-panel-and-turn-footer)
 - [Diff preview](#diff-preview)
-- [Status bar](#status-bar)
+- [Status line](#status-line)
 - [AGENTS.md and /init](#agentsmd-and-init)
 - [Undo](#undo)
 - [Settings and environment](#settings-and-environment)
@@ -22,7 +22,7 @@ Blink 5.5, Sonata 6.0 and Aeon 6.5.
 
 ## Install
 
-Needs Node.js 22.18 or newer (or 23.6 or newer) and npm. There are no other dependencies. **Not published to npm yet:** `npx` and the installer work only after the first release.
+Needs Node.js 22.18 or newer (or 23.6 or newer) and npm. There are no other dependencies.
 
 Try it without installing:
 
@@ -65,7 +65,7 @@ Or skip login and set `SYNQA_API_KEY` in your shell. The variable wins over the
 
 - `synqa` : interactive session in the current folder.
 - `synqa "fix the failing test"` : one task, then exit.
-- `synqa --yes "..."` : run unattended. **`--yes` runs shell commands without asking, so use it only in repositories you trust**
+- `synqa --yes "..."` : approve ordinary file writes and edits inside the folder without asking. **Shell commands always ask, even with `--yes`** (any file the agent reads could carry an injected command), and `--yes` is not allowed in your home folder
   (text in a README or a web page can steer the model). Some things still ask, and are denied when nobody can answer:
   writes that can run code later (git hooks and other `.git` files, `package.json`, Makefiles, `.envrc`, `.vscode`
   settings, CI workflows, shell startup files, dotfiles, executables), writes to secrets files, every write and
@@ -85,46 +85,62 @@ Or skip login and set `SYNQA_API_KEY` in your shell. The variable wins over the
 | `/compact` | Ask the model to summarize the conversation and continue from the summary, to save context. |
 | `/undo` | Revert the last file the agent wrote. Run it again to go further back. |
 | `/clear` | Start a fresh conversation (reloads `AGENTS.md`). |
-| `/help` | List the commands. |
+| `/help` | List the commands, grouped, with the keys of the command menu. |
 | `/exit` | Leave (also `/quit`, or Ctrl-D). |
 
 `/status` reads your balance from the Synqa account service with your key. If the service does not
 answer, it says so and shows everything else; your balance is always on the
 [dashboard](https://synqa.ca/client-dashboard).
 
-## Welcome panel and turn footer
+## Start screen, prompt and turn footer
 
-In an interactive terminal the session opens with a welcome panel: the CLI version, the tier id and
-name, the workspace folder (your home folder shown as `~`), whether `AGENTS.md` project notes were
-loaded, and your credit and weekly pool balance from the Synqa account service. The balance lookup
-waits at most 2 seconds; if it fails the panel says `balance unavailable`, and `balance not available yet`
-when the service does not offer it to API keys yet. Your key is never shown.
+In an interactive terminal the session opens with the Synqa wordmark (on a window of 60 columns or
+more; a one-line bold `Synqa.` below that), then dim lines with the CLI version, tier and effort, and
+the workspace folder (your home folder shown as `~`), then short `⎿` notes: whether `AGENTS.md`
+project notes were loaded, and your credit and weekly pool balance from the Synqa account service.
+The balance lookup waits at most 2 seconds; if it fails the note says `balance unavailable`, and
+`balance not available yet` when the service does not offer it to API keys yet. Your key is never shown.
 
 ```
-╭─ Synqa. CLI v1.1.0 ───────────────────────────────────────────╮
-│ ╭────╮  Tier       synqa-sonata-6.0 (Sonata 6.0)              │
-│ │ S. │  Workspace  ~/proj                                     │
-│ ╰────╯  Notes      AGENTS.md loaded (1,234 chars)             │
-│         Balance    $9.98 credit · weekly pool $4.00 of $10.00 │
-╰───────────────────────────────────────────────────────────────╯
+  ▄▀▀▀
+   ▀▀▄ █  █ █▀▀▄ ▄▀▀█ ▄▀▀█
+  ▄▄▄▀ ▀▄▄█ █  █ ▀▄▄█ ▀▄▄█ ▄
+       ▄▄▄▀         █
+
+  v1.1.1 · Blink 5.5 · default effort
+  ~/synqa-test
+  ⎿ no AGENTS.md yet: /init writes one
+  ⎿ $9.98 credit · weekly pool $4.00 of $10.00
+───────────────────────────────────────────────────────────────────────────────
+❯ Try "explain this project", or type / for commands
+───────────────────────────────────────────────────────────────────────────────
+Blink 5.5 · synqa-test · 0 tokens                                  $9.98 credit
+/ commands · ↑↓ history · tab complete · ctrl+c quit
 ```
 
-On a terminal that is not UTF-8 (or `TERM=dumb`, or a very old Windows console) the panel is plain ASCII:
-
-```
-[S.] Synqa. CLI v1.1.0
-  Tier       synqa-sonata-6.0 (Sonata 6.0)
-  Workspace  ~/proj
-  Notes      AGENTS.md loaded (1,234 chars)
-  Balance    $9.98 credit | weekly pool $4.00 of $10.00
-```
-
-Colours: terracotta for the period, spinner, `❯` prompt and monogram; warm bone for the name and the
-tier; warm stone for borders, labels and the footer; sage for the balance and added diff lines
-(removed lines stay red). 24-bit colour is used when `COLORTERM` is `truecolor` or `24bit`, otherwise
-the nearest of the 256 terminal colours. Stone is a mid grey: row labels are bold to stay readable,
-but on a light terminal background borders and the footer are faint.
-
+The letters are drawn in your terminal's own text colour, so they read as ink on a light theme and
+light on a dark one; the full stop is terracotta. The input sits between two thin rules, with a dim
+hint while it is empty. Under it the status line shows only what is known (see below) and a line of
+key hints.
+
+Type `/` and a menu of commands opens under the input, filtered as you type, with a short
+description of each. Up and Down move the highlight, Tab or Enter completes it (Enter runs a command
+that takes no argument), Esc closes the menu. An unknown command gets a one-line hint with the
+nearest name. The menu is drawn with Node's own readline key events, no extra package.
+
+On a terminal that is not UTF-8 (or `TERM=dumb`, or a very old Windows console) everything is plain
+ASCII and there is no menu or frame: the status is printed above a plain `>` prompt.
+
+Colours: terracotta for the full stop, spinner, `❯` prompt, tier name and the selected menu row;
+the terminal's own text colour (bold) for names, or warm bone when the terminal reports a dark
+background (`COLORFGBG`); warm stone for rules and labels; sage for the balance and added diff lines
+(removed lines stay red). 24-bit colour is used only where it is known to work: `COLORTERM` is
+`truecolor` or `24bit`, or `TERM_PROGRAM` is iTerm2, WezTerm, VS Code, Ghostty and similar. macOS
+Terminal.app (`TERM_PROGRAM=Apple_Terminal`) and unknown terminals get the 256 standard colours, with
+terracotta mapped to colour 166 so it stays burnt orange; Terminal.app gets them even when a
+`COLORTERM` was copied into the shell profile, because it misdraws 24-bit escapes. Every line is
+measured by its visible width (colour codes not counted, wide characters counted as two) and kept
+one column short of the window, so nothing wraps.
 
 While the agent waits for the first token a spinner with the elapsed seconds is shown (`⠋ waiting 1.2s`)
 and is erased when output starts. Each tool call is drawn as a card: a header with the tool and its
@@ -143,10 +159,10 @@ file or command, the diff preview for edits inside it, and a one line result.
 After every turn a dim footer line stays in the scrollback: time to first token, output speed,
 routing (`local` or `hybrid`) and your credit left (only when the balance is known).
 
-The panel, spinner, cards and footer degrade on their own: with `NO_COLOR` they have no colour; when
+The start screen, spinner, cards and footer degrade on their own: with `NO_COLOR` they have no colour; when
 output is not a terminal (a pipe, a file, a one-shot task) there is no spinner, no cursor control and
 the old plain output; when the terminal is not UTF-8, is `TERM=dumb`, or is the old Windows console
-(Windows Terminal is fine), the panel, cards and spinner use plain ASCII (`[S.]`, `+-`, `| / - \`). Long paths are cut with an
+(Windows Terminal is fine), the start screen, cards and spinner use plain ASCII (`+-`, `| / - \`). Long paths are cut with an
 ellipsis to fit narrow windows. Text from the model or from tools never reaches the terminal as
 control sequences.
 
@@ -161,24 +177,26 @@ shell startup files, other dotfiles): those are always shown in full.
 Colour is off when output is not a terminal or when `NO_COLOR` is set; the diff is then plain `+`/`-`
 text. Control characters in file content are shown as `\x1b`-style escapes, never sent to your terminal.
 
-## Status bar
+## Status line
 
-In an interactive terminal the last row of the screen stays pinned and shows:
+In an interactive terminal the line under the input shows only values that are known:
 
 ```
-Blink 5.5 | local | TTFT 0.42s | 87.3 tok/s | 1,234 tokens
+Blink 5.5 · low effort · synqa-test · ctx 10% · hybrid · 1,234 tokens          $9.98 credit
 ```
 
-- Tier display name (`Blink 5.5`, `Sonata 6.0` or `Aeon 6.5`), plus `effort low` or `effort medium` when set.
+- Tier display name (`Blink 5.5`, `Sonata 6.0` or `Aeon 6.5`), plus `low effort` or `medium effort` when set.
+- The workspace folder name.
+- `ctx`: how much of the context window the last request used (after the first request).
 - Routing: `local` or `hybrid`, read from the `x-synqa-routing` response header of the last request
-  (`fallback` for a fallback route, `?` if the server did not say).
-- TTFT: seconds from sending the request to the first token. tok/s: output tokens per second of
-  generation over the last turn. A dash means the number was not reported.
+  (`fallback` for a fallback route); left out when the server did not say.
 - Session tokens: input plus output so far.
+- On the right, your credit when the balance is known.
 
-On a narrow terminal the least important parts drop off first. When the output is not a terminal
-(a pipe, a file, a very small window, `TERM=dumb`) there is no pinned bar: the same line is printed
-above each prompt, and after a one-shot task.
+On a narrow terminal the least important parts drop off first. Time to first token and output speed
+are in the footer after each turn. When the output is not a terminal (a pipe, a file, `TERM=dumb`)
+a plain line (`Blink 5.5 | local | TTFT 0.42s | 87.3 tok/s | 1,234 tokens`, unknown parts left out)
+is printed above each prompt, and after a one-shot task.
 
 ## AGENTS.md and /init
 
@@ -203,7 +221,7 @@ it. Use git for that.
 
 | Name | Meaning |
 |---|---|
-| `SYNQA_API_KEY` | Your key; wins over the saved one. Never passed to commands the agent runs. |
+| `SYNQA_API_KEY` | Your key; wins over the saved one (the start screen says so, and `synqa login` warns when it differs from the key you just saved). Never passed to commands the agent runs. |
 | `NO_COLOR` | Any non-empty value turns colour off. |
 | `~/.config/synqa/config.json` | Saved key and default tier (mode 0600). |
 
@@ -211,7 +229,7 @@ it. Use git for that.
 
 - File tools only touch files inside the folder you started in (`..`, absolute paths and symlinks
   out of it are refused).
-- Writes, edits and shell commands ask `y/N` first, also in one-shot mode, unless `--yes`. Without a
+- Writes and edits ask `y/N` first, also in one-shot mode, unless `--yes`; shell commands always ask. Every question shows the whole diff (only the display after a `--yes` approval is cut). Commands run without credential-looking environment variables (tokens, secrets, keys and passwords by name, `AWS_*` except region and profile, git askpass helpers, connection strings with a password in them, the API key, and `SSH_AUTH_SOCK`: run `git push` over SSH in your own terminal). `grep` stops a pattern that runs longer than 10 seconds. Without a
   terminal the answer is no.
 - Shell commands are not confined to the folder: read each one before you answer.
 - Writes to `.git/hooks`, `package.json`, shell startup files and other dotfiles carry a warning, because
@@ -220,21 +238,33 @@ it. Use git for that.
   delimited block as conventions only, you are told when it is loaded, and while it is loaded shell
   commands always ask first, even with `--yes`.
 - Files that hold secrets (`.env` and `.env.*` except examples, `.envrc`, `*.pem`, `*.key`, `*.tfvars`, `id_*`
-  private keys, `keys.json`, `credentials.json`, `secrets.*`, `.ssh/`, `.aws/`, `.gnupg/`, `.kube/config`,
-  `.docker/config.json`, `.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, `.dev.vars`, this CLI's own config)
-  are opened (read or edit) only after you say yes, never with `--yes`, and are skipped by `grep` and `glob`.
+  private keys, `keys.json`, `credentials.json`, `secrets.*`, `.ssh/`, `.aws/`, `.gnupg/`, `.kube/`,
+  `.docker/config.json`, `.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, `.dev.vars`, `.config/gh`,
+  `.config/gcloud`, `.azure/`, `.password-store/`, macOS keychains (`Library/Keychains`, `*.keychain-db`),
+  browser profiles (Chrome, Chromium, Brave, Edge, Arc, Firefox, Safari, cookies and saved logins), this
+  CLI's own config) are never read, written or edited by the agent, with or without `--yes`, and are
+  skipped by `grep` and `glob`. A shell command that names one always asks first, even with `--yes`.
   Names match without regard to case or full-width letters, as on a case-insensitive Mac.
-- The CLI refuses to start in your home folder or the filesystem root (it could reach your keys and
-  settings there). Pass `--allow-home` only if you mean it.
+- The CLI starts in any folder, your home folder included, like other coding CLIs. Inside your home
+  folder everything under a dot entry at its top (`~/.zsh_history`, `~/.config/...`, `~/.cargo/...`,
+  any tool's settings) and everything under `~/Library` is protected as a rule, whether or not it is
+  named above; your projects' own dot files (`~/proj/.github`) are not affected. `--yes` is refused
+  in the home folder itself. Writes to launchd agents, autostart entries, systemd units, fish and
+  other shell startup files and `~/.local/bin` always ask. Only the filesystem root (`/`) is refused
+  as a start folder. `--allow-home` is still accepted and does nothing.
 - Your key is never printed, never put on a command line, and removed from the environment of every
   command the agent runs.
 
 ## Troubleshooting
 
 - `No API key`: run `synqa login` or set `SYNQA_API_KEY`.
-- `the key was rejected`: the key was revoked or mistyped; make a new one on the dashboard.
+- `Your API key was rejected`: run `synqa login` again, or check on the dashboard that the key is
+  active. If `SYNQA_API_KEY` is set in your shell, that key is used instead of the saved one: remove it
+  (`unset SYNQA_API_KEY`, and the line in `~/.zshrc`).
+- `synqa login` checks the key against the same key check the chat uses, and refuses a key with no
+  chat access.
 - `request timed out`: a request is cut off after 10 minutes.
-- Status bar garbled after resizing: it repaints on resize.
+- Stray characters or a broken layout in Terminal.app: update to 1.1.1, which uses 256 colours there.
 - No colour: check `NO_COLOR` and that stdout is a terminal.
 
 ## Develop

package/dist/api.js

@@ -1,4 +1,5 @@
-import { API_BASE } from "./config.js";
+import { API_BASE, DASHBOARD_URL } from "./config.js";
+import { sanitize } from "./sanitize.js";
 import { REQUEST_TIMEOUT_MS, MAX_OUTPUT_TOKENS, usageFrom } from "./tiers.js";
                                         
 
@@ -90,9 +91,48 @@ export class ApiError extends Error {
   }
 }
 
+export const KEY_REJECTED = `Your API key was rejected. Run \`synqa login\` again, or check the key is active in your Synqa dashboard (${DASHBOARD_URL}).`;
+
+// The gateway's short reason ({"detail": "..."}), already white-labelled by the server; sanitized
+// and cut here because it is network text.
+async function detailOf(res          )                  {
+  try {
+    const text = (await res.text()).slice(0, 4000);
+    const v = JSON.parse(text)                                                       ;
+    const d = typeof v.detail === "string" ? v.detail : typeof v.error?.message === "string" ? v.error.message : "";
+    return sanitize(d).replace(/\s+/g, " ").trim().slice(0, 200);
+  } catch {
+    return "";
+  }
+}
+
+// A plain sentence for a failed request, by status. Never the raw body.
+export function friendlyStatus(status        , detail = "")         {
+  const why = detail ? ` (${detail})` : "";
+  if (status === 401) return KEY_REJECTED;
+  if (status === 402) return `Your Synqa balance is used up or your plan is not active${why}. Top up in your Synqa dashboard (${DASHBOARD_URL}).`;
+  if (status === 403) return `This key is not allowed to do that${why}. Check the key's access in your Synqa dashboard (${DASHBOARD_URL}).`;
+  if (status === 404) return "The Synqa service did not recognise this request (404). Update the CLI: npm i -g @synqa/cli";
+  if (status === 413) return `The conversation is too large to send${why}. Run /compact or /clear and try again.`;
+  if (status === 429) return `Rate limit reached${why}. Wait a moment and try again.`;
+  if (status === 503) return `Synqa is busy or paused right now${why}. Try again in a minute.`;
+  if (status >= 500) return `The Synqa service had a problem (status ${status}). Try again in a minute.`;
+  return `The request failed with status ${status}${why}.`;
+}
+
+// Login check: GET /v1/models goes through the same key check as chat (the gateway's caller_key),
+// and the list is empty for a key without the chat capability, so an empty list is refused too.
 export async function checkKey(apiKey        , fetchFn            = fetch)                {
   const res = await fetchFn(`${API_BASE}/models`, { headers: { authorization: `Bearer ${apiKey}` } });
-  if (!res.ok) throw new ApiError(res.status, res.status === 401 || res.status === 403 ? "the key was rejected" : `unexpected status ${res.status}`);
+  if (!res.ok) throw new ApiError(res.status, res.status === 401 ? "the key was rejected" : friendlyStatus(res.status, await detailOf(res)));
+  let ids            = [];
+  try {
+    const body = (await res.json())                      ;
+    ids = Array.isArray(body.data) ? body.data : [];
+  } catch {
+    throw new ApiError(res.status, "the service answer was not understood");
+  }
+  if (ids.length === 0) throw new ApiError(403, "this key has no chat access; check it in your Synqa dashboard");
 }
 
                            
@@ -128,7 +168,8 @@ export async function chat(o             )                      {
       }),
       signal: ac.signal,
     });
-    if (!res.ok || !res.body) throw new ApiError(res.status, `request failed with status ${res.status}`);
+    if (!res.ok) throw new ApiError(res.status, friendlyStatus(res.status, res.status === 401 ? "" : await detailOf(res)));
+    if (!res.body) throw new ApiError(res.status, "the service sent an empty answer");
     const acc = new StreamAccumulator();
     let firstAt                    ;
     for await (const ev of sseEvents(res.body                                        )) {

package/dist/commands.js

@@ -15,6 +15,8 @@ import { groupDigits } from "./statusbar.js";
 import { CONTEXT_TOKENS, EFFORTS, findEffort, findTier, TIERS } from "./tiers.js";
                                                       
                                         
+import { renderHelp, SLASH_HELP, unknownCommandHint } from "./prompt.js";
+                                  
 
                             
                  
@@ -36,23 +38,14 @@ import { CONTEXT_TOKENS, EFFORTS, findEffort, findTier, TIERS } from "./tiers.js
                              
                                                   
                
+                                                                        
                       
                      
   
 
                                                                  
 
-export const SLASH_HELP = [
-  "/model blink|sonata|aeon       switch tier",
-  "/effort default|low|medium     set reasoning effort",
-  "/status                        tier, routing, session tokens, credit and weekly pool",
-  "/init                          write a starter AGENTS.md for this project",
-  "/compact                       summarize the conversation to save context",
-  "/undo                          revert the last file the agent wrote (not shell commands)",
-  "/clear                         start a fresh conversation",
-  "/help                          this text",
-  "/exit                          leave",
-].join("\n");
+export { SLASH_HELP };
 
 export function statusParts(st              )              {
   return {
@@ -141,7 +134,7 @@ export async function runCommand(line        , st              , io           )
     case "/quit":
       return { handled: true, exit: true };
     case "/help":
-      io.print(SLASH_HELP);
+      io.print(io.ui ? renderHelp(io.ui).join("\n") : SLASH_HELP);
       break;
     case "/clear":
       st.history = freshHistory(st);
@@ -184,7 +177,7 @@ export async function runCommand(line        , st              , io           )
       await cmdUndo(st, io);
       break;
     default:
-      io.print("Unknown command. /help lists them.");
+      io.print(unknownCommandHint(first));
   }
   return { handled: true };
 }