@tiens.nguyen/gu-cli 1.0.767 → 1.0.769

package/ollama-setup.mjs

@@ -21,6 +21,14 @@
 import { isLikelyEmbedder } from "./agent-model-command.mjs";
 import { EMBED_CHOICES } from "./embed-model-command.mjs";
 import { isCancelWord } from "./coding-provider-setup.mjs";
+import {
+  SKIP_ALL,
+  createHinter,
+  keyConfirmation,
+  needsKeyAfterStatus,
+  readStepAnswer,
+  shouldAskKey,
+} from "./model-setup-ui.mjs";
 
 /** Ollama's native port, used when someone types a bare host or an IP with no port. */
 export const OLLAMA_DEFAULT_PORT = 11434;
@@ -649,21 +657,83 @@ export async function askOllamaSetup(
     // Injected so the tests can drive it; defaults to a real request with a short deadline,
     // because this runs while someone is waiting at a prompt.
     probeStatus = defaultProbeStatus,
+    // #301: the MASKED prompt for an API key. Without one no key is ever asked — a secret is
+    // never read through a prompt that echoes it.
+    askSecret = null,
+    // #301: the hint under each model prompt — full the first time, short after.
+    hint = createHinter(),
   } = {},
 ) {
+  // #301: every key typed for a server, by its HOSTNAME. "" = asked, left empty. Not by URL: the
+  // key is asked before listing, for the first reading of what was typed, and a different reading
+  // (another port or scheme) may be the one that answers.
+  const keys = new Map();
+  const SKIPPED = { skipped: true, keys: [] };
+  // #301: a step SKIPPED ON PURPOSE, as against a server that never answered. Nothing chosen
+  // because of a skip means "leave the models unset"; nothing chosen because nothing answered
+  // stays null, and the caller falls back to the shared box as it always has.
+  let declined = false;
+  // Dim, like the other guidance lines under a question; one line, above the prompt it explains.
+  const say = (h) => log(`    \x1b[2m${h}\x1b[0m`);
+
+  /**
+   * The key question for a TYPED address, before its models are listed (so a server that needs
+   * one can list them). Returns the key, "" for none, or SKIP_ALL.
+   */
+  const askKeyFor = async (host) => {
+    if (keys.has(host)) return keys.get(host); // same server for both roles → asked once
+    if (typeof askSecret !== "function") return "";
+    say(hint());
+    const raw = await askSecret(`  API key for ${host} (Enter for none): `);
+    if (raw === SKIP_ALL) return SKIP_ALL;
+    const key = String(raw ?? "").trim();
+    keys.set(host, key);
+    log(`  ${keyConfirmation(host, key)}`);
+    return key;
+  };
+
+  /**
+   * List the models of what was typed (or the default), asking for a key when the address is
+   * public or the server refuses without one. { ok, normalized, models } | { failed } | SKIP_ALL.
+   */
+  const loadServer = async (typed, fallbackUrl, reuse) => {
+    const raw = typed || fallbackUrl;
+    const first = urlCandidates(raw)[0];
+    if (reuse && first && reuse.normalized.url === first.url) return reuse;
+    let key = "";
+    if (first && shouldAskKey({ typed, host: first.host })) {
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+    }
+    let tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    // A server that refused for want of credentials: ask now, whatever the address looked like,
+    // and list again with the key. Once — a second refusal is a wrong key, reported as such.
+    if (tried?.failed && needsKeyAfterStatus(tried.status) && !key && first) {
+      log(`  ${first.host} needs an API key to list its models.`);
+      keys.delete(first.host);
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+      if (key) tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    }
+    return tried;
+  };
+
   // ---- SERVER 1: the agent model and the embedder -------------------------------------
   // These two are REQUIRED and not a free choice (see REQUIRED_AGENT_MODEL). A box without
   // them is "not ready" rather than "wrong": it may still be a perfectly good coder host, which
   // is why this refusal does not end the flow.
   let agent = null;
   for (let attempt = 0; attempt < attempts && !agent; attempt++) {
-    const typed = (await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `)).trim();
-    if (isDecline(typed)) break;
-    const tried = await loadFirstThatAnswers(typed || defaultUrl, fetchTags, log);
+    say(hint());
+    const a = readStepAnswer(await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
+    const tried = await loadServer(a.text, defaultUrl, null);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || defaultUrl, probeStatus, log, describeOpenAiAgent);
+      const explained = await explainIfOpenAi(a.text || defaultUrl, probeStatus, log, describeOpenAiAgent);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -676,7 +746,9 @@ export async function askOllamaSetup(
     const need = checkRequired(models);
     if (!need.ok) {
       for (const l of describeNotReady(normalized.host, need.missing)) log(`  ${l}`);
-      log("  (or press Enter with no address to skip — you can set it later with /model)");
+      // #301: this used to tell people to press Enter to skip — but Enter takes the DEFAULT
+      // server. "s" is the skip.
+      log("  (or type s to skip — you can set it later with /model)");
       continue;
     }
     log(`  ✓ ${normalized.host} has the ${REQUIRED_AGENT_PREFIX} family and the embedder`);
@@ -690,18 +762,21 @@ export async function askOllamaSetup(
   const coderDefault = agent?.normalized?.url ?? defaultUrl;
   let coder = null;
   for (let attempt = 0; attempt < attempts && !coder; attempt++) {
-    const typed = (await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `)).trim();
-    if (isDecline(typed)) break;
+    say(hint());
+    const a = readStepAnswer(await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
     // Same box as the agent server → reuse the list we already have rather than fetching twice.
-    const same = normalizeOllamaUrl(typed || coderDefault);
+    const same = normalizeOllamaUrl(a.text || coderDefault);
     const tried =
       agent && same && same.url === agent.normalized.url
         ? { normalized: same, models: agent.models }
-        : await loadFirstThatAnswers(typed || coderDefault, fetchTags, log);
+        : await loadServer(a.text, coderDefault, agent);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || coderDefault, probeStatus, log, describeOpenAiCoder);
+      const explained = await explainIfOpenAi(a.text || coderDefault, probeStatus, log, describeOpenAiCoder);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -718,7 +793,7 @@ export async function askOllamaSetup(
   // A real answer, not a failure. The machine finishes setup unconfigured, the bar shows the
   // roles as unset, and the first question says so instead of hanging — which is the entire
   // reason declining is allowed to be this easy.
-  if (!agent && !coder) return null;
+  if (!agent && !coder) return declined ? SKIPPED : null;
 
   // ---- PICK THE MODELS -----------------------------------------------------------------
   // THE AGENT IS CHOSEN, not assumed (user, 2026-09-06). The gate above proved the family is
@@ -729,7 +804,6 @@ export async function askOllamaSetup(
   // Seed the embedder the box ACTUALLY has: the shipped default when present, else whichever
   // accepted embedder passed the gate — a qwen3-embedding-only box must not be told it now
   // embeds with a model it never had.
-  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let chat = "";
   if (agent) {
     const cands = agentCandidates(agent.models);
@@ -741,13 +815,18 @@ export async function askOllamaSetup(
       log("  AGENT model — routes every turn and writes the plain replies");
       for (const row of renderModelMenu(cands, { defaultModel: agentDefault, formatSize })) log(row);
       for (let t = 0; t < attempts && !chat; t++) {
-        const answer = await ask(`  agent [${agentDefault}]: `);
-        chat = parseMenuChoice(answer, cands, agentDefault) ?? "";
+        say(hint());
+        const a = readStepAnswer(await ask(`  agent [${agentDefault}]: `));
+        if (a.kind === "all") return SKIPPED;
+        // #301: "s" here skips the AGENT role — its server was chosen, its model is not.
+        if (a.kind === "skip") { agent = null; break; }
+        chat = parseMenuChoice(a.text, cands, agentDefault) ?? "";
         if (!chat) log(`  no model called that — type its number, or Enter for ${agentDefault}`);
       }
-      chat = chat || agentDefault;
+      if (agent) chat = chat || agentDefault;
     }
   }
+  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let code = "";
   let extras = [];
   if (coder) {
@@ -756,20 +835,37 @@ export async function askOllamaSetup(
     log("  CODING model — writes the code; worth waiting for");
     for (const row of renderModelMenu(coder.models, { defaultModel: roles.code, formatSize })) log(row);
     for (let t = 0; t < attempts && !code; t++) {
-      const answer = await ask(`  code [${roles.code}]: `);
-      code = parseMenuChoice(answer, coder.models, roles.code) ?? "";
+      say(hint());
+      const a = readStepAnswer(await ask(`  code [${roles.code}]: `));
+      if (a.kind === "all") return SKIPPED;
+      if (a.kind === "skip") { coder = null; break; }
+      code = parseMenuChoice(a.text, coder.models, roles.code) ?? "";
       if (!code) log(`  no model called that — type its number, or Enter for ${roles.code}`);
     }
-    code = code || roles.code;
+    if (coder) code = code || roles.code;
 
-    const rest = coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code);
+    const rest = coder ? coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code) : [];
     if (rest.length) {
       log("");
       log("  Also offer in /model?  (numbers separated by commas, or Enter for none)");
       for (const row of renderModelMenu(rest, { formatSize })) log(row);
-      extras = parseMultiChoice(await ask("  also: "), rest);
+      say(hint());
+      const a = readStepAnswer(await ask("  also: "));
+      if (a.kind === "all") return SKIPPED;
+      extras = a.kind === "skip" ? [] : parseMultiChoice(a.text, rest);
     }
   }
+  // Both roles skipped at the model menus: as much a decision as skipping both servers.
+  if (!agent && !coder) return SKIPPED;
+
+  // #301: the keys typed, only for the servers actually used, never the empty ones — each under
+  // the URL that ANSWERED, which is the one the settings rows are written with.
+  const used = [agent?.normalized, coder?.normalized].filter(Boolean);
+  const keyList = [];
+  for (const [host, key] of keys) {
+    const n = key && used.find((u) => u.host === host);
+    if (n && !keyList.some((k) => k.url === n.url)) keyList.push({ url: n.url, key });
+  }
 
   // HALF-CONFIGURED IS A REAL STATE and must be representable. Someone with an agent box but no
   // coder yet, or a coder but no agent box, has made progress worth keeping — forcing both or
@@ -786,6 +882,7 @@ export async function askOllamaSetup(
     ...(embed ? { embed } : {}),
     altCoders: (extras ?? []).filter((n) => n !== code),
     ready: Boolean(agent && coder),
+    ...(keyList.length ? { keys: keyList } : {}),
   };
 }
 
@@ -848,7 +945,7 @@ async function explainIfOpenAi(raw, probeStatus, log, describe) {
   return true;
 }
 
-async function loadFirstThatAnswers(raw, fetchTags, log) {
+async function loadFirstThatAnswers(raw, fetchTags, log, apiKey = "") {
   const candidates = urlCandidates(raw);
   if (!candidates.length) {
     return { failed: ["that is not a server address — try 192.168.1.40, ollama.local, or a full URL"] };
@@ -856,7 +953,10 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   let last = null;
   for (const normalized of candidates) {
     try {
-      const models = await fetchTags(tagsUrlFor(normalized));
+      // #301: the key goes along only when there is one — a keyless call stays byte-identical.
+      const models = apiKey
+        ? await fetchTags(tagsUrlFor(normalized), { apiKey })
+        : await fetchTags(tagsUrlFor(normalized));
       // Say WHICH reading answered, but only when we had to guess — otherwise it is noise
       // repeating what the user just typed.
       if (candidates.length > 1) log(`  using ${displayUrl(normalized.url)}`);
@@ -869,6 +969,11 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   // NOT PRINTED HERE ANY MORE. "check that Ollama is running there" is exactly the wrong thing
   // to say about a correct address for a hosted provider, and the caller is the only one that
   // knows whether it found a better explanation. It prints one message or the other, never both.
-  return { failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
+  // #301: an HTTP status (401/403 = needs a key) travels with the failure so the caller can ask.
+  const status = Number(last?.status ?? last?.httpStatus) || 0;
+  if (needsKeyAfterStatus(status)) {
+    return { status, failed: [`${candidates[0].host} refused the request (HTTP ${status}) — ${apiKey ? "that key was not accepted" : "it needs an API key"}.`] };
+  }
+  return { status, failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
                     "check the address, or that Ollama is running there and listening on the network."] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.767",
+  "version": "1.0.769",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,9 @@
     "accent.mjs",
     "gu-cli.mjs",
     "gu-repl.mjs",
+    "step-tokens.mjs",
+    "model-setup-ui.mjs",
+    "setup-prompts.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/setup-prompts.mjs

@@ -0,0 +1,82 @@
+/**
+ * THE FIRST-RUN PROMPTS THAT PLAIN rl.question CANNOT BE (#301, #300).
+ *
+ * First-run setup runs before the REPL exists, on its own readline (gu-repl.mjs `rl0`), and every
+ * question there was `rl0.question` — which echoes. Two things need more than that:
+ *
+ *   · ESC. The model questions offer "Esc = skip all model setup". Esc submits nothing in readline,
+ *     so the pending question is cancelled through its AbortSignal and resolved with SKIP_ALL.
+ *   · A SECRET. An API key, or the MongoDB password (#300), must never reach the screen or the
+ *     scrollback. Readline's echo and line refresh are muted for the question, one "•" per
+ *     character is drawn instead (the only proof a keystroke registered), and the answer is taken
+ *     back out of readline's history — which keeps every submitted line, so the secret would
+ *     otherwise come back in plain text on the next press of Up.
+ *
+ * The REPL has its own askSecret with the same guarantees (task #127/#191); this is the version for
+ * the one stretch of the program that runs before it.
+ */
+import { SKIP_ALL, isEscapeKey } from "./model-setup-ui.mjs";
+
+/**
+ * One question on `rl`. Options: `secret` (mask + keep out of history), `esc` (Esc → SKIP_ALL).
+ * `style` decorates the label (the accent colour). Resolves with the answer string, or SKIP_ALL.
+ */
+export function askOn(rl, q, { secret = false, esc = false, style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const shown = style(q);
+    const ac = new AbortController();
+    const origWrite = rl._writeToOutput;
+    const origRefresh = rl._refreshLine;
+    let done = false;
+
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      input.removeListener?.("keypress", onKey);
+      if (secret) {
+        rl._writeToOutput = origWrite;
+        rl._refreshLine = origRefresh;
+        if (Array.isArray(rl.history) && value && rl.history[0] === value) rl.history.shift();
+        rl.historyIndex = -1;
+      }
+      // A muted Enter printed no newline, and an Esc left the caret on the prompt's row.
+      if (secret || value === SKIP_ALL) output.write("\n");
+      resolve(value);
+    };
+
+    // Runs AFTER readline's own keypress handler (registered when rl was created), so rl.line is
+    // already the updated text when the bullets are drawn.
+    function onKey(_s, key) {
+      if (done) return;
+      if (esc && isEscapeKey(key)) {
+        ac.abort();
+        // The cancelled question leaves what was typed in rl.line; the next question must not
+        // start with it.
+        rl.line = "";
+        rl.cursor = 0;
+        finish(SKIP_ALL);
+        return;
+      }
+      if (secret && output.isTTY) {
+        output.write(`\r\x1b[2K${shown}${"•".repeat(String(rl.line ?? "").length)}`);
+      }
+    }
+
+    input.on?.("keypress", onKey);
+    // question() draws the label synchronously — mute only AFTER, or the label is muted too.
+    rl.question(shown, { signal: ac.signal }, (a) => finish(String(a ?? "")));
+    if (secret) {
+      rl._writeToOutput = () => {};
+      rl._refreshLine = () => {};
+    }
+  });
+}
+
+/** The three readers setup takes: plain, Esc-aware (model questions), masked (keys, passwords). */
+export function setupPrompts(rl, { style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return {
+    ask: (q) => askOn(rl, q, { style, input, output }),
+    askStep: (q) => askOn(rl, q, { esc: true, style, input, output }),
+    askSecret: (q) => askOn(rl, q, { secret: true, esc: true, style, input, output }),
+  };
+}

package/step-tokens.mjs

@@ -0,0 +1,55 @@
+/**
+ * THIS STEP'S TOKENS, for the thinking line (task #298).
+ *
+ * The thinking line showed "· ↑ 478k · ↓ 4.3k" — the turn's running totals, which are exactly the
+ * bar's "sent 478k" and "↓ out 4.3k" one row below. Same numbers twice. What the line can say that
+ * the bar cannot is what the CURRENT model call is costing: its own prompt (↑) and its own output
+ * (↓), starting from zero at each new step.
+ *
+ * Python already knows both per call (`stepInput`, `stepOutput`) and tags them with `step`. The API
+ * only stores job fields it knows, but it passes agentPromptBreakdown through as-is — so the worker
+ * rides these three figures on that object (liveStep / liveStepIn / liveStepOut) and no API release
+ * is needed. Everything that reads the breakdown does so by named bucket, so extra keys are inert.
+ */
+
+/** The state before any step of a turn. */
+export const NO_STEP = Object.freeze({ step: 0, stepIn: 0, stepOut: 0 });
+
+/**
+ * Fold one python "tokens" event into the current step's figures.
+ *
+ * A new `step` number starts from zero: its output is not known until the call returns, so the old
+ * step's ↓ must not linger beside the new step's ↑. Input can arrive twice for one step — the
+ * estimate at send time, then the server's exact count if higher — and the larger one wins.
+ */
+export function foldStepTokens(prev, event) {
+  let { step, stepIn, stepOut } = prev ?? NO_STEP;
+  if (!event || typeof event !== "object") return { step, stepIn, stepOut };
+  if (Number.isFinite(event.step) && event.step !== step) {
+    step = event.step;
+    stepIn = 0;
+    stepOut = 0;
+  }
+  if (Number.isFinite(event.stepInput) && event.stepInput > stepIn) stepIn = event.stepInput;
+  if (Number.isFinite(event.stepOutput) && event.stepOutput >= 0) stepOut = event.stepOutput;
+  return { step, stepIn, stepOut };
+}
+
+/** The breakdown the worker PATCHes, carrying the step's figures. */
+export function withStepTokens(breakdown, s) {
+  if (!breakdown || typeof breakdown !== "object" || !s || !s.step) return breakdown;
+  return { ...breakdown, liveStep: s.step, liveStepIn: s.stepIn, liveStepOut: s.stepOut };
+}
+
+/**
+ * What the terminal reads back from a polled breakdown: this step's figures, or null when the
+ * breakdown carries none (an older worker, or no step reported yet) — then the line shows nothing
+ * rather than a total dressed up as a step.
+ */
+export function readStepTokens(breakdown) {
+  if (!breakdown || typeof breakdown !== "object") return null;
+  const step = Number(breakdown.liveStep);
+  if (!Number.isFinite(step) || step <= 0) return null;
+  const n = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : 0);
+  return { step, stepIn: n(breakdown.liveStepIn), stepOut: n(breakdown.liveStepOut) };
+}

package/terminal-layout.mjs

@@ -468,6 +468,27 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
  * `identity` is optional so callers that have nothing to put there (and the tests that predate
  * it) keep producing the same rows as before.
  */
+/**
+ * HOW TO PASTE, for this platform (issue #67). Two different things share the word: TEXT is pasted
+ * by the terminal app (gu only sees the result), an IMAGE by gu's own keys (#284).
+ *
+ *   macOS    text ⌘V            image ctrl+v — a terminal's ⌘V sends nothing for an image
+ *   Windows  text ctrl+v        image alt+v  — Windows Terminal keeps ctrl+v for itself
+ *   Linux    text ctrl+shift+v  image ctrl+v
+ *
+ * The image half only when the coder can take one (a Claude coder); offering a key that then
+ * answers "images need a Claude coder" would be a hint that leads to a warning.
+ */
+export function pasteHint({ platform = process.platform, images = false } = {}) {
+  const text = platform === "darwin" ? "⌘V" : platform === "win32" ? "ctrl+v" : "ctrl+shift+v";
+  if (!images) return `${text} to paste`;
+  const image = platform === "win32" ? "alt+v" : "ctrl+v";
+  return `${text} paste · ${image} image`;
+}
+
+/** At least this many spaces between the mode text and the hint, or the hint is left out. */
+const HINT_MIN_GAP = 3;
+
 export function buildFooterRows({
   width,
   gutter = "   ",
@@ -475,16 +496,25 @@ export function buildFooterRows({
   identity = "",
   token = "",
   mode = "",
+  // Right-aligned on the mode row (issue #67), dim. DROPPED WHOLE when it does not fit: every
+  // footer row must stay one physical row (#109/#132/#138), and half a key name is worse than none.
+  modeHint = "",
   notice = "",
   missing = "",
 }) {
   const w = Math.max(20, width || 80);
+  const modeLeft = gutter + mode;
+  const hintGap = modeHint ? w - 1 - visibleLen(modeLeft) - visibleLen(modeHint) : -1;
+  const modeRow =
+    hintGap >= HINT_MIN_GAP
+      ? modeLeft + " ".repeat(hintGap) + dim(modeHint)
+      : clipVisible(modeLeft, w - 1);
   return [
     dim("─".repeat(w)),
     ...(rag ? [clipVisible(gutter + rag, w - 1)] : []),
     ...(identity ? [clipVisible(gutter + identity, w - 1)] : []),
     clipVisible(gutter + token, w - 1),
-    clipVisible(gutter + mode, w - 1),
+    modeRow,
     // A passing notice (the image-paste warning, #54) gets its OWN row, under the mode row — it
     // used to be appended to that row and was clipped at the right edge ("…pick one with /mo").
     // Present only while it shows; paintBar re-cuts the frozen zone when the count changes.