@tiens.nguyen/gu-cli 1.0.869 → 1.0.871

package/hints.mjs

@@ -0,0 +1,67 @@
+/**
+ * TIPS UNDER THE THINKING WORD (#234) — one line that teaches a command or a key while the model
+ * works, the way Claude Code's "⎿ Tip: …" does.
+ *
+ * Pure: the REPL picks one per turn and draws it under the playful word. Every "/command" named
+ * here must be a real one (hints.test.mjs checks them against the REPL's COMMANDS list), because a
+ * tip that names a command that does not exist is worse than no tip.
+ */
+
+export const HINTS = [
+  "/model switches the coding model for this session",
+  "/quick-models picks two models; then ← / → at the prompt flips between them",
+  "/agent-model switches the model that talks to you (the agent model)",
+  "Type / then Tab to complete a command; /help lists them all",
+  "shift+tab switches between accept edits and manually edit",
+  "ctrl+t opens the model's full thought while it works",
+  "ctrl+c stops the turn; type continue to pick it up again",
+  "ctrl+k replaces the coding model's API key without leaving the terminal",
+  "/new starts a new conversation in this folder — the old one is kept",
+  "/doctor checks that every configured model really answers",
+  "/tokens shows how big the last prompt was and how much of it was RAG",
+  "/prices shows what the last turn and this session cost",
+  "/context-window tells gu how big your coding model's context is",
+  "/mcp lists the MCP servers and adds one step by step",
+  "/hooks lists the commands gu runs on start, ask and turn end",
+  "/shells shows long commands the agent left running in the background",
+  "/budget shows your API provider balances (Pro)",
+  "/browser checks the gu Chrome extension the agent uses to click web pages",
+  "/support sends the gu team a request with your logs attached (secrets masked)",
+  "/clear-logs shows what gu's logs and indexes take on disk, then asks what to clear",
+  "/switch-skill chooses whose skills and MCP servers this folder uses: Claude's or gu's",
+  "/use-presets applies a saved setup after showing what changes",
+  "/save-settings writes your providers and models to a file you can load on another machine",
+];
+
+/**
+ * One tip index, never `last` when there is a choice (so two turns in a row do not repeat).
+ * `rand` is injectable (0 <= rand() < 1) for tests.
+ */
+export function pickHint(rand = Math.random, last = -1, list = HINTS) {
+  if (list.length === 0) return -1;
+  if (list.length === 1) return 0;
+  let i = Math.floor(rand() * list.length) % list.length;
+  if (i === last) i = (i + 1) % list.length;
+  return i;
+}
+
+/** The glyph and label in front of a tip — plain text, painted dim by the caller. */
+export const HINT_PREFIX = "⎿ Tip: ";
+
+/**
+ * The tip as ONE row no wider than `width` - 1 columns including `indent` spaces: cut with "…" and
+ * never wrapped (a wrapped row in the live block is the #109/#138 failure). "" when there is no room
+ * for anything readable.
+ */
+export function hintRow(text, { width = 80, indent = 3 } = {}) {
+  const room = Math.max(0, (width || 80) - 1 - indent);
+  const full = HINT_PREFIX + String(text ?? "").trim();
+  if (!String(text ?? "").trim() || room < 20) return "";
+  return full.length <= room ? full : full.slice(0, room - 1).replace(/\s+$/, "") + "…";
+}
+
+/** How long the model must have been working before the tip appears, in seconds. */
+export const HINT_AFTER_SECONDS = 4;
+
+/** Is there room for the tip row? Not on a very short terminal, where every row counts. */
+export const hintFits = (rows) => (rows || 24) >= 16;

package/model-doctor.mjs

@@ -12,7 +12,7 @@ import { open, mkdir, readdir, writeFile } from "node:fs/promises";
 import { arch, homedir, platform, totalmem } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ensureSupportedPython, isBuildToolsMissing } from "./platform-tools.mjs";
+import { ensureSupportedPython, isBuildToolsMissing, buildFailureMessage } from "./platform-tools.mjs";
 
 // Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
 const MIN_CHAT_RAM_GB = 16;
@@ -207,12 +207,7 @@ async function pipInstall(pkgs, log) {
   log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
   let r = await runPip(python3Bin(), pkgs);
   if (r.code === 0) return;
-  if (isBuildToolsMissing(r.err)) {
-    throw new Error(
-      "pip had to compile a package and this machine has no C++ compiler. Use Python 3.13 or 3.12 (64-bit), which " +
-      "has prebuilt packages: " + pythonInstallHint() + ". Then run gu doctor again."
-    );
-  }
+  if (isBuildToolsMissing(r.err)) throw new Error(buildFailureMessage(r.err));
   const noPip = isPipMissing(r.err);
   if (!noPip && !isExternallyManaged(r.err)) {
     throw new Error(`pip install ${pkgs.join(" ")} exited ${r.code}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.869",
+  "version": "1.0.871",
   "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",
@@ -114,6 +114,7 @@
     "ollama-setup.mjs",
     "s3-setup.mjs",
     "doctor-check.mjs",
+    "service-check.mjs",
     "embed-model-command.mjs",
     "proxy-command.mjs",
     "proxy-selftest.mjs",
@@ -122,6 +123,8 @@
     "model-doctor.mjs",
     "coding-key-prompt.mjs",
     "model-fallback.mjs",
+    "quick-models.mjs",
+    "hints.mjs",
     "terminal-title.mjs",
     "gu-relaunch.mjs",
     "server-keys.mjs",

package/platform-tools.mjs

@@ -314,9 +314,37 @@ export async function ensureSupportedPython({
   };
 }
 
-/** pip's "I had to compile and there is no compiler" failure. */
+/**
+ * pip's "I had to compile and could not" failure. Newer pip words it "error: failed-wheel-build-for-install /
+ * Failed to build installable wheels for some pyproject.toml based projects" (reported on a Windows 11
+ * customer installing smolagents + openai, #232), older pip "Failed building wheel for X".
+ */
 export function isBuildToolsMissing(output) {
-  return /Microsoft Visual C\+\+ 14\.0 or greater is required|Failed building wheel for|error: command '(?:gcc|cl\.exe)' failed/i.test(String(output ?? ""));
+  return /Microsoft Visual C\+\+ 14\.0 or greater is required|Failed building wheel for|failed-wheel-build-for-install|Failed to build installable wheels|error: command '(?:gcc|cl\.exe)' failed|could not find (?:`?cargo`?|rustc)|metadata-generation-failed/i.test(String(output ?? ""));
+}
+
+/** The packages pip could not build: ["pydantic-core", "jiter"], from either pip wording. */
+export function failedBuildPackages(output) {
+  const text = String(output ?? "");
+  const names = new Set();
+  for (const m of text.matchAll(/Failed building wheel for ([A-Za-z0-9_.-]+)/g)) names.add(m[1]);
+  // New pip: "╰─> pydantic-core" (or "-> pydantic-core") under the failed-wheel-build summary.
+  const at = text.search(/Failed to build installable wheels/i);
+  if (at >= 0) for (const m of text.slice(at).matchAll(/^\s*(?:╰─>|\+->|->)\s*([A-Za-z0-9_.-]+)\s*$/gm)) names.add(m[1]);
+  return [...names];
+}
+
+/** What to tell the user when pip could not build wheels: which package, and the fix that works. */
+export function buildFailureMessage(output, { platform = process.platform } = {}) {
+  const names = failedBuildPackages(output);
+  const what = names.length ? `pip could not build ${names.join(", ")}` : "pip had to compile a package and could not";
+  const rust = /rustc|cargo|maturin|pydantic[-_]core|jiter|rpds/i.test(String(output ?? "")) || names.some((n) => /pydantic[-_]core|jiter|rpds/i.test(n));
+  const how = platform === "win32" ? "winget install Python.Python.3.13" : "your package manager, e.g. python3.13";
+  return (
+    `${what}. That happens when this Python has no prebuilt package for it (too new, 32-bit, or ARM) and the machine ` +
+    `has no compiler${rust ? " (these packages need the Rust toolchain)" : ""}. Install 64-bit Python 3.13 (${how}), ` +
+    `open a new terminal, then run gu doctor again.`
+  );
 }
 
 /** How to SAY the resolved interpreter in a log line or error message. */

package/quick-models.mjs

@@ -0,0 +1,64 @@
+/**
+ * QUICK MODELS (#233) — two coding models to flip between with ← / → at the prompt.
+ *
+ * Pure helpers only (no I/O, no terminal): the picker, the key and the bar live in gu-repl.mjs and
+ * call these, so the rules below are testable. A quick model is the same (backend, model) PAIR
+ * /model offers — { id, model, kind, url } — stored whole, so a switch needs no network round trip
+ * to find out what "claude-opus" meant. At most TWO: the point is a flip, not a menu.
+ */
+
+export const QUICK_MAX = 2;
+
+/** At most QUICK_MAX distinct choices, each with an id; anything else in the saved list is dropped. */
+export function normalizeQuick(list) {
+  const out = [];
+  for (const c of Array.isArray(list) ? list : []) {
+    const id = typeof c?.id === "string" ? c.id.trim() : "";
+    if (!id || out.some((o) => o.id === id)) continue;
+    out.push({
+      id,
+      model: typeof c.model === "string" && c.model ? c.model : id,
+      kind: typeof c.kind === "string" ? c.kind : "",
+      url: typeof c.url === "string" ? c.url : "",
+    });
+    if (out.length === QUICK_MAX) break;
+  }
+  return out;
+}
+
+/** The ← / → flip needs exactly two. One quick model is a pin, not a flip. */
+export const quickReady = (quick) => normalizeQuick(quick).length === QUICK_MAX;
+
+/**
+ * Where ← / → goes. Active is one of the two → the OTHER one. Active is neither (the user picked
+ * something else with /model) → the first one, so a key press always lands somewhere defined.
+ * null when fewer than two are chosen.
+ */
+export function quickTarget(quick, activeId) {
+  const q = normalizeQuick(quick);
+  if (q.length < QUICK_MAX) return null;
+  const at = q.findIndex((c) => c.id === activeId);
+  return at < 0 ? q[0] : q[1 - at];
+}
+
+/** Does a model id match a quick choice? The session stores "" for the account default. */
+export const isQuickActive = (quick, activeId) => normalizeQuick(quick).some((c) => c.id === activeId);
+
+/** The dim hint beside the mode on the bar: only when the keys do something. */
+export const quickBarHint = (quick) => (quickReady(quick) ? "← → switch model" : "");
+
+/**
+ * The yellow warning row: quick models are chosen but the model in use is not one of them, so ← / →
+ * would not toggle what the user thinks it toggles. Plain text, cut to `width` with an ellipsis.
+ */
+export function quickWarning(quick, activeId, { width = 80, gutter = "   " } = {}) {
+  const q = normalizeQuick(quick);
+  if (q.length === 0 || isQuickActive(q, activeId)) return "";
+  const full = q.length === QUICK_MAX
+    ? `⚠ not on a quick model — ← → goes to ${q[0].model} · /quick-models`
+    : "⚠ not on your quick model · pick 2 with /quick-models to use ← →";
+  const short = "⚠ not on a quick model · /quick-models";
+  const room = Math.max(8, (width || 80) - 1 - gutter.length);
+  const pick = full.length <= room ? full : short;
+  return pick.length <= room ? pick : pick.slice(0, Math.max(1, room - 1)) + "…";
+}

package/service-check.mjs

@@ -0,0 +1,181 @@
+/**
+ * Can this machine reach the gu service — and if not, why? (task #413, GH #240)
+ *
+ *     node --test tests/service-check.test.mjs
+ *
+ * Reported on a Windows VM: the agent model answered "hi", but every coding turn failed with
+ * "the gu service couldn't be reached". The coding turn is the only one that needs the gu service:
+ * the local API fetches the agent's instructions from it first, with Node's plain fetch. The
+ * Python agent and the terminal's model calls reach the internet by other routes (the proxy,
+ * the system certificates), so "the internet works" and "the local API can't get out" are both
+ * true at once. The usual causes on a work machine need different fixes:
+ *
+ *   · a network that inspects HTTPS — Node does not trust its certificate, Python does
+ *   · a network that needs a proxy — the local API does not use gu's /proxy
+ *   · an address that is blocked or cannot be looked up
+ *
+ * So the check makes the request the local API makes, then the variations that tell the causes
+ * apart, and says which one it is. The decisions are pure (serviceVerdict) so they are tested
+ * without a network; checkGuService only gathers the facts.
+ */
+import { spawn } from "node:child_process";
+
+/** Why a fetch failed, as a kind, a code and words. Node says "fetch failed" and keeps the reason in `cause`. */
+export function describeNetError(err) {
+  if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+    return { kind: "timeout", code: "TIMEOUT", words: "no answer in time" };
+  }
+  const code = String(err?.cause?.code ?? err?.code ?? "");
+  if (/CERT|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)|ERR_TLS/i.test(code)) {
+    return { kind: "cert", code, words: "this computer doesn't trust the certificate it was shown" };
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return { kind: "dns", code, words: "the address could not be looked up" };
+  if (["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "ENETUNREACH", "EHOSTUNREACH"].includes(code)) {
+    return { kind: "blocked", code, words: code === "ECONNREFUSED" ? "the connection was refused" : code === "ECONNRESET" ? "the connection was cut" : "the connection didn't go through" };
+  }
+  return { kind: "other", code, words: code || String(err?.cause?.message ?? err?.message ?? err ?? "network error") };
+}
+
+/** One GET; any HTTP answer means the server was reached (401 included — no token was sent). */
+async function reach(url, { fetchImpl = fetch, dispatcher, timeoutMs = 10_000 } = {}) {
+  try {
+    const r = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs), ...(dispatcher ? { dispatcher } : {}) });
+    return { ok: true, status: r.status };
+  } catch (err) {
+    return { ok: false, ...describeNetError(err) };
+  }
+}
+
+/**
+ * The same request from a NODE STARTED WITH --use-system-ca: does trusting this computer's own
+ * certificates (Windows' store, macOS' keychain) fix it? A Node without the flag says "bad option".
+ */
+export function reachWithSystemCa(url, { execPath = process.execPath, timeoutMs = 15_000, spawnImpl = spawn } = {}) {
+  const script =
+    `fetch(${JSON.stringify(url)},{signal:AbortSignal.timeout(${timeoutMs - 3000})})` +
+    `.then(r=>process.stdout.write("ok "+r.status))` +
+    `.catch(e=>process.stdout.write("err "+((e.cause&&e.cause.code)||e.name||e.message)))`;
+  return new Promise((resolveP) => {
+    let out = "";
+    let err = "";
+    let child;
+    try {
+      child = spawnImpl(execPath, ["--use-system-ca", "-e", script], { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      resolveP({ ok: false, unsupported: false, words: e?.message ?? String(e) });
+      return;
+    }
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout?.on("data", (d) => { out += d; });
+    child.stderr?.on("data", (d) => { err += d; });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolveP({ ok: false, unsupported: false, words: e?.message ?? String(e) });
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      if (/bad option|unknown option/i.test(err)) resolveP({ ok: false, unsupported: true, words: "" });
+      else if (out.startsWith("ok ")) resolveP({ ok: true, status: Number(out.slice(3)) });
+      else resolveP({ ok: false, unsupported: false, words: out.replace(/^err /, "") || err.trim().split("\n").pop() || "no answer" });
+    });
+  });
+}
+
+/**
+ * THE VERDICT, from the facts. Pure.
+ *
+ *   direct    { ok, status } | { ok:false, kind, words }   Node's plain fetch (what the local API does)
+ *   viaProxy  same, or null when no proxy is set
+ *   systemCa  { ok } | { ok:false, unsupported, words }, or null when not tried
+ *   localApi  { ok, version } | { ok:false, error }, or null when this machine has no local API
+ *
+ * Returns { ok, lines }: lines are for the terminal, a ✓ / ✗ line first and the reason after.
+ */
+export function serviceVerdict({ host, direct, viaProxy = null, systemCa = null, localApi = null, nodeVersion = process.version }) {
+  const lines = [];
+  if (localApi?.ok) {
+    lines.push(`✓ gu service — private mode can fetch the agent's instructions (v${localApi.version})`);
+    return { ok: true, lines };
+  }
+  if (direct.ok) {
+    if (!localApi) {
+      lines.push(`✓ gu service — ${host} answers`);
+      return { ok: true, lines };
+    }
+    lines.push(`✗ gu service — ${host} answers this computer, but the local API couldn't get the agent's instructions:`);
+    lines.push(`    ${localApi.error}`);
+    // A token problem says its own fix; anything else is most often a local API started before
+    // the network came up, or an older one.
+    if (!/gu token/.test(localApi.error)) lines.push("    restart the local API (`gu api restart`) and try again.");
+    return { ok: false, lines };
+  }
+  lines.push(`✗ gu service — ${host} can't be reached: ${direct.words}`);
+  lines.push("    a coding turn needs it (the agent's instructions come from it); a plain reply like \"hi\" does not.");
+  if (direct.kind === "cert") {
+    if (systemCa?.ok) {
+      lines.push("    It works when Node trusts this computer's own certificates: this network inspects HTTPS.");
+      lines.push("    gu doesn't start its local API that way yet (#413) — ask IT, or use another network meanwhile.");
+    } else if (systemCa?.unsupported) {
+      lines.push(`    This network probably inspects HTTPS. Node ${nodeVersion} can't use the system certificates;`);
+      lines.push("    Node 22.15 or newer can. Ask IT, or use another network.");
+    } else {
+      lines.push("    Even with this computer's own certificates it fails — ask IT which certificate the network uses.");
+    }
+  } else if (viaProxy?.ok) {
+    lines.push("    It works through your /proxy: this network needs it, and the local API doesn't use it yet (#413).");
+  } else if (viaProxy && !viaProxy.ok) {
+    lines.push(`    Through your /proxy it fails too: ${viaProxy.words}. Check the proxy settings with /proxy.`);
+  } else if (direct.kind === "dns") {
+    lines.push("    Check this computer's DNS, or whether the network blocks the address.");
+  } else {
+    lines.push(`    Allow ${host} on this network (firewall), or set /proxy if the network needs one.`);
+  }
+  if (localApi && !localApi.ok) lines.push(`    the local API says: ${localApi.error}`);
+  return { ok: false, lines };
+}
+
+/**
+ * Gather the facts and judge them. `hostedBase` is where the local API forwards to; `apiBase` +
+ * `workerKey` reach this machine's local API, asked only when `localApi` is true (Client Expert).
+ */
+export async function checkGuService({
+  hostedBase,
+  apiBase = "",
+  workerKey = "",
+  localApi = false,
+  proxy = null,
+  dispatcherFor = null,
+  fetchImpl = fetch,
+  systemCaImpl = reachWithSystemCa,
+  timeoutMs = 10_000,
+} = {}) {
+  const base = String(hostedBase ?? "").replace(/\/+$/, "");
+  const host = (() => { try { return new URL(base).host; } catch { return base; } })();
+  const url = `${base}/api/health`;
+  const direct = await reach(url, { fetchImpl, timeoutMs });
+
+  let viaProxy = null;
+  if (!direct.ok && proxy?.enabled && typeof dispatcherFor === "function") {
+    const dispatcher = await dispatcherFor(proxy).catch(() => null);
+    if (dispatcher) viaProxy = await reach(url, { fetchImpl, dispatcher, timeoutMs });
+  }
+  const systemCa = !direct.ok && direct.kind === "cert" ? await systemCaImpl(url) : null;
+
+  let local = null;
+  if (localApi && apiBase) {
+    try {
+      const r = await fetchImpl(`${apiBase.replace(/\/+$/, "")}/api/worker/prompt-scaffold/refresh`, {
+        method: "POST",
+        headers: { "X-Worker-Key": workerKey },
+        signal: AbortSignal.timeout(timeoutMs + 5000),
+      });
+      const body = await r.json().catch(() => null);
+      local = body?.ok
+        ? { ok: true, version: body.version }
+        : { ok: false, error: String(body?.error ?? `HTTP ${r.status}`) };
+    } catch (err) {
+      local = { ok: false, error: `the local API didn't answer (${describeNetError(err).words})` };
+    }
+  }
+  return serviceVerdict({ host, direct, viaProxy, systemCa, localApi: local });
+}