@tiens.nguyen/gu-cli 1.0.865 → 1.0.867

package/README.md

@@ -35,10 +35,11 @@ meaning the whole stack runs on this machine.
 ## The `gu` REPL
 
 ```
-gu [-v|--verbose] [--log] [--license <pro token>]
+gu [-v|--verbose] [--log] [--name <text>] [--license <pro token>]
 ```
 
 - `-v, --verbose` shows RAG index-file activity in the bottom bar.
+- `--name <text>` draws `<text>` instead of the gu logo in the startup banner (this run only). Letters, digits, space, `-` and `_` become block art; anything else, or a name over 12 characters, is shown as plain text.
 - `--log` logs this run in detail to `~/.gonext/worker.log`. Without it only starts, stops and errors are logged.
 - Ctrl-C stops following a turn.
 

package/banner-name.mjs

@@ -0,0 +1,110 @@
+/**
+ * `gu --name <text>` (#224): the startup banner draws <text> instead of the "gu" mark.
+ *
+ * Same material as the built-in mark: half-block elements only (▀ ▄ █), so it renders on any
+ * terminal without a font to install. Two rows of x-height, plus a third row used only by letters
+ * with a descender (g j p q y). Glyphs are separated by one blank column.
+ *
+ * ANYTHING THE FONT CANNOT DRAW (accents, emoji, punctuation) is shown as plain text on a single
+ * row instead of being dropped — a name must never silently turn into a different name.
+ */
+
+const G = {
+  a: ["█▀▀█", "█▀▀█"],
+  b: ["█▀▀▄", "█▄▄▀"],
+  c: ["█▀▀▀", "█▄▄▄"],
+  d: ["▄▀▀█", "▀▄▄█"],
+  e: ["█▀▀█", "█▄▄▄"],
+  f: ["█▀▀▀", "█▀▀ "],
+  g: ["█▀▀█", "█▄▄█", "▄▄▄█"],
+  h: ["█  █", "█▀▀█"],
+  i: ["▄", "█"],
+  j: ["  █", "  █", "▄▄█"],
+  k: ["█ ▄▀", "█▀▄ "],
+  l: ["█  ", "█▄▄"],
+  m: ["█▀▄▀█", "█   █"],
+  n: ["█▀▀█", "█  █"],
+  o: ["█▀▀█", "█▄▄█"],
+  p: ["█▀▀█", "█▀▀▀", "▀   "],
+  q: ["█▀▀█", "█▄▄█", "   █"],
+  r: ["█▀▀█", "█▀▀▄"],
+  s: ["▄▀▀▀", "▄▄▄▀"],
+  t: ["▀█▀", " █ "],
+  u: ["█  █", "█▄▄█"],
+  v: ["█  █", "▀▄▄▀"],
+  w: ["█   █", "█▄█▄█"],
+  x: ["▀▄▀", "▄▀▄"],
+  y: ["█  █", "▀▄▄█", "▄▄▄▀"],
+  z: ["▀▀▀█", "█▄▄▄"],
+  0: ["█▀▀█", "█▄▀█"],
+  1: ["▄█", " █"],
+  2: ["▄▀▀█", "█▄▄▄"],
+  3: ["▀▀▀█", "▄▄▄█"],
+  4: ["█  █", "▀▀▀█"],
+  5: ["█▀▀▀", "▄▄▄█"],
+  6: ["█▀▀▀", "█▄▄█"],
+  7: ["▀▀▀█", "  █ "],
+  8: ["▄▀▀▄", "▀▄▄▀"],
+  9: ["█▀▀█", "▀▀▀█"],
+  "-": ["   ", "▄▄▄"],
+  _: ["    ", "▄▄▄▄"],
+  " ": ["  ", "  "],
+};
+
+/** Longest name accepted at all; longer is cut (and the cut is reported by the caller). */
+export const NAME_MAX = 24;
+/** Most characters drawn as block art; a longer name is shown as plain text. */
+export const ART_MAX = 12;
+
+/** What the user typed → what is shown: trimmed, control chars removed, capped. */
+export function cleanName(raw) {
+  return String(raw ?? "")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .trim()
+    .slice(0, NAME_MAX);
+}
+
+/** Draw `name` as rows of equal visible width. Returns { rows, width, art }; null for an empty name. */
+export function logoFor(raw, maxWidth = Infinity) {
+  const name = cleanName(raw);
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  const drawable = [...lower].every((ch) => G[ch]);
+  if (drawable && lower.length <= ART_MAX) {
+    const rows = ["", "", ""];
+    [...lower].forEach((ch, i) => {
+      const g = G[ch];
+      const w = Math.max(...g.map((r) => r.length));
+      for (let r = 0; r < 3; r++) {
+        rows[r] += (i ? " " : "") + (g[r] ?? "").padEnd(w);
+      }
+    });
+    // The third row only exists for descenders; drop it when it is all blanks.
+    const out = rows[2].trim() ? rows : rows.slice(0, 2);
+    const width = Math.max(...out.map((r) => r.length));
+    if (width <= maxWidth) return { rows: out.map((r) => r.padEnd(width)), width, art: true };
+  }
+  const text = name.slice(0, Math.max(1, Math.min(name.length, maxWidth)));
+  return { rows: [text], width: text.length, art: false };
+}
+
+/**
+ * Read `--name <x>` / `--name=<x>` from argv. { value } | { missing: true } | {} when absent.
+ * A following token that is itself a flag is NOT taken as the value.
+ */
+export function parseNameArg(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  for (let i = 0; i < args.length; i++) {
+    const a = String(args[i]);
+    if (a.startsWith("--name=")) {
+      const value = cleanName(a.slice(7));
+      return value ? { value } : { missing: true };
+    }
+    if (a === "--name") {
+      const next = args[i + 1];
+      const value = next === undefined || String(next).startsWith("-") ? "" : cleanName(next);
+      return value ? { value } : { missing: true };
+    }
+  }
+  return {};
+}

package/client-expert-run.mjs

@@ -14,7 +14,7 @@
  * that does not work — and that state is much harder to get out of than an unfinished setup.
  */
 import { execFile, spawn } from "node:child_process";
-import { readFile, writeFile, mkdir, rm, rename } from "node:fs/promises";
+import { readFile, writeFile, mkdir, rm, rename, cp } from "node:fs/promises";
 import { writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -867,6 +867,43 @@ export async function probeApiInstall(version) {
   }
 }
 
+/** Errors Windows raises while another process (antivirus, indexer) holds a handle in a folder. */
+const LOCKED = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+
+/**
+ * Put the unpacked folder at its final path. WINDOWS REFUSES TO RENAME OR DELETE A DIRECTORY
+ * while any process has a handle inside it, and the files `tar` has just written are exactly what
+ * Defender and the indexer open (issue #223: "EPERM: operation not permitted, rename ...incoming").
+ * So retry with backoff, then fall back to copy + remove, then say which folder is locked.
+ * `fs` is injectable for the tests.
+ */
+export async function moveIntoPlace(staging, dir, fs = {}) {
+  const { rename: mv = rename, rm: del = rm, cp: copy = cp, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = fs;
+  const tries = fs.tries ?? 10;
+  let last;
+  for (let i = 0; i < tries; i++) {
+    try {
+      await del(dir, { recursive: true, force: true });
+      await mv(staging, dir);
+      return;
+    } catch (e) {
+      last = e;
+      if (!LOCKED.has(e?.code)) throw e;
+      await sleep(Math.min(250 * 2 ** i, 3000));
+    }
+  }
+  try {
+    await del(dir, { recursive: true, force: true });
+    await copy(staging, dir, { recursive: true });
+    await del(staging, { recursive: true, force: true }).catch(() => {});
+  } catch (e) {
+    throw new Error(
+      `Could not move the unpacked API into ${dir} (${e?.code ?? last?.code}): a program is holding a file in it. ` +
+      "Close gu and any terminal or editor open in that folder, pause antivirus scanning for it, and run the install again."
+    );
+  }
+}
+
 /**
  * Download and unpack the published API.
  *
@@ -908,9 +945,8 @@ export async function downloadApiPackage(manifest, { onProgress = () => {} } = {
   // ends in "gzip: stdin: unexpected end of file". A path with no drive letter works for GNU and bsdtar.
   await run("tar", ["xzf", "package.tar.gz", "-C", "."], { cwd: staging });
   await rm(tmpTar, { force: true });
-  await rm(dir, { recursive: true, force: true });
   await mkdir(join(homedir(), ".gonext", "api"), { recursive: true });
-  await rename(staging, dir);
+  await moveIntoPlace(staging, dir);
   onProgress(`installed ${manifest.version} → ${dir}`);
   return { dir, version: manifest.version };
 }

package/gu-repl.mjs

@@ -193,6 +193,7 @@ import { EditCardStream, isEditCardHeader } from "./edit-card-render.mjs";
 // Task #240: what a failed agent-payload call means, and when a rejected key may be recovered
 // from in place instead of ending the session.
 import { payloadError, recoveryPlan } from "./credential-recovery.mjs";
+import { logoFor, parseNameArg } from "./banner-name.mjs";
 import { isNoCodeRetry, splitVerboseLine, stepHasCode } from "./verbose-lines.mjs";
 import {
   createTranscript,
@@ -382,8 +383,9 @@ const vwidth = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "").length;
 // square, read as a box; with an all-caps "GU AGENT" beside it the banner shouted its name twice.
 // The product is written "gu", so the mark is too: a g with a real descender and a u — a wordmark,
 // one row shorter, and the only coloured thing on the banner.
-const LOGO = ["█▀▀█ █  █", "█▄▄█ █▄▄█", "▄▄▄█"];
-const LOGO_W = 9;
+// `let`: `gu --name <text>` (#224) swaps in that name's art once argv has been read.
+let LOGO = ["█▀▀█ █  █", "█▄▄█ █▄▄█", "▄▄▄█"];
+let LOGO_W = 9;
 // Lay the LOGO and the status rows SIDE BY SIDE (logo left, facts right), or STACK them (logo
 // then facts) when the terminal is too narrow to fit both without wrapping — so the banner is
 // never the soft-wrapped jumble the plain "· … · …" lines used to be (task #131). Side-by-side
@@ -402,7 +404,7 @@ const renderBanner = (statusRows) => {
       out.push(GUTTER + left + gap + (statusRows[i] ?? ""));
     }
   } else {
-    for (const r of LOGO) out.push(GUTTER + accent(r));
+    for (const r of LOGO) out.push(GUTTER + accent(clipVisible(r, cols - 1 - GUTTER.length)));
     for (const r of statusRows) out.push(GUTTER + clipVisible(r, cols - 1 - GUTTER.length));
   }
   return out.join("\n");
@@ -622,7 +624,7 @@ if (cliVerdict.kind === "run") {
 } else if (argv.includes("--help") || argv.includes("-h")) {
   console.log(
     "gu — terminal agent REPL for the current folder\n\n" +
-      "Usage: gu [-v|--verbose] [--log] [--color] [--license <pro token>]\n" +
+      "Usage: gu [-v|--verbose] [--log] [--color] [--name <text>] [--license <pro token>]\n" +
       "       gu status                 # worker + a table of the running model servers\n" +
       "       gu start|stop|restart|logs # manage the background worker\n" +
       "       gu logs <port|pid> [-f]   # tail a running model server's log\n" +
@@ -633,6 +635,8 @@ if (cliVerdict.kind === "run") {
       "                  stops and errors are logged. Ends when this gu closes.\n" +
       "  --color         colour the thinking spinner and its playful word (cycling colours).\n" +
       "                  Without it they are plain white.\n" +
+      "  --name <text>   show <text> instead of the gu logo in the startup banner\n" +
+      "                  (this run only; letters, digits, space - _ are drawn as art)\n" +
       "  --license <token>  pro license: a first install ASKS how this machine runs (hosted\n" +
       "                     client / MLX host / private). Without it, a first install is\n" +
       "                     private by default — the whole stack on this machine.\n" +
@@ -660,6 +664,21 @@ const REPL_LOG = argv.includes("--log");
 // --color (#216): the thinking spinner and its playful word cycle through colours only on a run
 // started with this flag; by default they are plain white.
 const REPL_COLOR = argv.includes("--color");
+// --name <text> (#224): the startup banner draws <text> in place of the "gu" mark. Per run only.
+{
+  const named = parseNameArg(argv);
+  if (named.missing) {
+    console.error(red("gu: --name needs a name, e.g.  gu --name acme"));
+    process.exit(2);
+  }
+  if (named.value) {
+    const l = logoFor(named.value, Math.max(8, (process.stdout.columns || 80) - 6));
+    if (l) {
+      LOGO = l.rows;
+      LOGO_W = l.width;
+    }
+  }
+}
 if (REPL_LOG) {
   const ll = await import("./log-level.mjs");
   await ll.takeLease().catch(() => {});
@@ -2916,7 +2935,7 @@ const footerBuilt = () =>
     identity: identityLineText(),
     token: tokenLineText(),
     mode: modeLineText(),
-    // Task #34: "rag: embedder down → grep fallback" as a soft yellow note beside the mode, not an
+    // Task #34: "rag: using grep as fallback" as a soft yellow note beside the mode, not an
     // alarming red segment on the token row. yellow goes through paint(), so NO_COLOR turns it off.
     // Issue #120: an auto-compaction this turn outranks the rag note (same soft yellow slot).
     modeNote: compactLockNote() || compactBarNote(lastPromptBreakdown) || ragBarNote(lastPromptBreakdown),

package/model-doctor.mjs

@@ -12,6 +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";
 
 // Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
 const MIN_CHAT_RAM_GB = 16;
@@ -144,7 +145,8 @@ export function isPipMissing(output) {
 /** Run pip once. Resolves { code, err } — never rejects, so the caller owns the policy. */
 function runPip(python, pkgs, extraArgs = []) {
   return new Promise((resolve) => {
-    const child = spawn(python, ["-m", "pip", "install", "-U", ...extraArgs, ...pkgs], {
+    // --prefer-binary: take an older wheel over a newer source build (a compiler is not a given, #225).
+    const child = spawn(python, ["-m", "pip", "install", "-U", "--prefer-binary", ...extraArgs, ...pkgs], {
       // stderr is PIPED so the PEP 668 marker can be recognised, and echoed as it arrives so
       // the user still watches a real install rather than a frozen line.
       stdio: ["ignore", "inherit", "pipe"],
@@ -198,9 +200,19 @@ async function ensureVenv(log) {
  * venv cannot be built, --break-system-packages, which is announced rather than done quietly.
  */
 async function pipInstall(pkgs, log) {
+  // A Python newer than the wheels (3.15 -> PyYAML builds from source -> "Visual C++ 14.0 is required"): #225.
+  const sp = await ensureSupportedPython({ log });
+  if (!sp.ok) throw new Error(sp.message);
+  if (sp.switched) await pinPythonForDaemon({ 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."
+    );
+  }
   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.865",
+  "version": "1.0.867",
   "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",
@@ -101,6 +101,7 @@
     "rag-job-config.mjs",
     "completed-flush.mjs",
     "verbose-lines.mjs",
+    "banner-name.mjs",
     "agent-model-label.mjs",
     "coding-choice-tags.mjs",
     "coding-provider-setup.mjs",

package/platform-tools.mjs

@@ -233,6 +233,92 @@ export async function resolvePython() {
     : { cmd: "python3", args: [] };
 }
 
+/* ------------------------------------------- a Python new enough to lack wheels (#225) ---- */
+
+/**
+ * The newest Python that gu's packages (PyYAML via smolagents, pillow, ...) ship prebuilt wheels for.
+ * Above it pip BUILDS FROM SOURCE, which on Windows asks for Visual C++ 14 and ends in
+ * "Microsoft Visual C++ 14.0 or greater is required" (reported with Python 3.15). Raise it as wheels land.
+ */
+export const PYTHON_WHEELS_MAX = [3, 14];
+
+/** "3.15.0" / "3.15" -> [3, 15], or null when it is not a version. */
+export function parsePyVersion(out) {
+  const m = /^\s*(\d+)\.(\d+)/.exec(String(out ?? ""));
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+
+/** Is this [major, minor] newer than the newest Python with wheels? */
+export function pythonTooNew(v, max = PYTHON_WHEELS_MAX) {
+  return Array.isArray(v) && (v[0] > max[0] || (v[0] === max[0] && v[1] > max[1]));
+}
+
+/** Older interpreters to fall back to, best first (3.13, 3.12 are the most widely wheeled). */
+export function altPythonCandidates(platform = process.platform) {
+  const minors = [13, 12, 14, 11, 10];
+  return platform === "win32"
+    ? minors.map((m) => ({ cmd: "py", args: [`-3.${m}`] }))
+    : minors.map((m) => ({ cmd: `python3.${m}`, args: [] }));
+}
+
+const EXE_PROBE = ["-c", "import sys; print(sys.executable)"];
+const VER_PROBE = ["-c", "import sys; print('%d.%d' % sys.version_info[:2])"];
+
+/**
+ * The first older interpreter that runs, as { cmd, args, exe } (exe = its real path), or null.
+ * `probe(cmd, args)` resolves stdout or null; injectable for the tests.
+ */
+export async function findSupportedPython({ platform = process.platform, probe = (c, a) => run(c, a, { timeout: 8000 }) } = {}) {
+  for (const c of altPythonCandidates(platform)) {
+    const exe = String((await probe(c.cmd, [...c.args, ...EXE_PROBE])) ?? "").trim();
+    if (exe && !/\n/.test(exe)) return { ...c, exe };
+  }
+  return null;
+}
+
+/**
+ * Make sure the Python gu will install packages into is one that has wheels.
+ * - GONEXT_PROBE_PYTHON set: the user chose; leave it.
+ * - default Python fine: nothing to do.
+ * - default too new: switch to an older one (sets GONEXT_PROBE_PYTHON in `env`, so every spawn in
+ *   this process follows) or say plainly what to install. Never starts a build that cannot succeed.
+ * Resolves { ok, switched?, from?, message? }.
+ */
+export async function ensureSupportedPython({
+  platform = process.platform,
+  env = process.env,
+  probe = (c, a) => run(c, a, { timeout: 8000 }),
+  log = () => {},
+} = {}) {
+  if ((env.GONEXT_PROBE_PYTHON ?? env.GONEXT_MLX_LM_PYTHON ?? "").trim()) return { ok: true };
+  let version = null;
+  for (const c of pythonCandidates(platform)) {
+    version = parsePyVersion(await probe(c.cmd, [...c.args, ...VER_PROBE]));
+    if (version) break;
+  }
+  if (!version || !pythonTooNew(version)) return { ok: true };
+  const from = version.join(".");
+  const alt = await findSupportedPython({ platform, probe });
+  if (alt) {
+    env.GONEXT_PROBE_PYTHON = alt.exe;
+    log(`  Python ${from} is too new for gu's packages (no prebuilt wheels yet) - using ${alt.exe} instead.`);
+    return { ok: true, switched: alt.exe, from };
+  }
+  const how = platform === "win32" ? "winget install Python.Python.3.13, or python.org" : "your package manager, or python.org";
+  return {
+    ok: false,
+    from,
+    message:
+      `Python ${from} is too new: gu's packages (PyYAML and others) have no prebuilt ${platform === "win32" ? "Windows " : ""}` +
+      `wheels for it yet, so pip would try to compile them. Install Python 3.13 (${how}), open a new terminal, then run gu doctor again.`,
+  };
+}
+
+/** pip's "I had to compile and there is no compiler" failure. */
+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 ?? ""));
+}
+
 /** How to SAY the resolved interpreter in a log line or error message. */
 export const pythonLabel = (py) => [py.cmd, ...py.args].join(" ");
 

package/terminal-layout.mjs

@@ -148,7 +148,7 @@ export function ragSegmentLabel(b) {
   switch (b.ragState) {
     // Task #34: no "✗" — search still works through grep, so this is a notice, not an error.
     case "unreachable":
-      return "rag: embedder down → grep fallback";
+      return "rag: using grep as fallback";
     case "no-index":
       return "rag — not indexed";
     case "unavailable":