@tiens.nguyen/gu-cli 1.0.863 → 1.0.864

package/support-bundle.mjs

@@ -0,0 +1,389 @@
+/**
+ * `gu support` / `/support` (#220) — send the support team a request WITH gu's logs attached.
+ *
+ * Asked for because a customer whose install failed had no idea who to contact, or what to send.
+ * support-report.mjs already wrote a masked health report; this adds the rest, the way Claude
+ * Code's /bug does it: collect, SHOW what will go, ask, send, and give back a reference.
+ *
+ *   1. collectSupportFiles — the report plus gu's own logs, each one MASKED (support-report's
+ *      redactReport) and cut to its END (the end is where the failure is). Chosen by an explicit
+ *      list, never by a sweep: conversations (sessions/), keys (worker.env) and RAG data are not
+ *      logs and never go. Also the Windows installer's log and the newest npm debug logs that
+ *      mention gu, because an install that failed has no gu logs at all.
+ *   2. zipFiles — one .zip in ~/.gonext/support/, owner-only. Pure JS: no `zip`/`tar` on PATH needed.
+ *   3. sendSupportRequest — POST /api/support/requests (the same queue the web Support page fills)
+ *      → a GU-XXXXXX reference and a one-time upload key, then the zip to …/:ref/logs.
+ *   4. When sending fails, the zip stays and supportFallbackLines says where to email it.
+ *
+ * Nothing here asks a question: gu-cli.mjs and gu-repl.mjs do that, each in its own way.
+ * Everything takes `home` / `fetchImpl` so the tests run on a temp folder and offline.
+ */
+import { open, readdir, stat, mkdir, writeFile, unlink } from "node:fs/promises";
+import { homedir, tmpdir, platform as osPlatform, release, arch } from "node:os";
+import { join, basename } from "node:path";
+import { deflateRawSync } from "node:zlib";
+import { redactReport, buildSupportReport } from "./support-report.mjs";
+import { LIVE_LOGS, LOG_DIRS, humanSize } from "./clear-logs.mjs";
+import { netErrorDetail } from "./cli-token.mjs";
+
+/** Where people are told to write. Same address as the web Support page (web-v2 supportText.mjs). */
+export const SUPPORT_EMAIL = "tien@getmarsic.cc";
+/** The hosted API — the one device login and the free token use (device-login.mjs DEFAULT_API_BASE). */
+export const SUPPORT_API_BASE = "https://chat-api-v2.gucli.com";
+export const SUPPORT_DIR = "support";
+/** Old bundles kept in ~/.gonext/support — they are ours to remove, and each holds logs. */
+export const KEEP_BUNDLES = 5;
+
+export const LIMITS = {
+  perFile: 512 * 1024, // the END of each log
+  total: 6 * 1024 * 1024, // all text, before compression
+  zip: 1000 * 1024, // what the API takes (api/src/routes/support.ts LOGS_MAX_BYTES)
+  dirFiles: 10, // newest files from run-logs/ and logs/
+  npmLogs: 3,
+};
+
+export function supportApiBase(env = process.env) {
+  const v = String(env.GU_SUPPORT_API_BASE ?? "").trim() || String(env.GU_TOKEN_API_BASE ?? "").trim() || SUPPORT_API_BASE;
+  return v.replace(/\/+$/, "");
+}
+
+async function mtimeOf(p) {
+  try {
+    const s = await stat(p);
+    return s.isFile() ? { size: s.size, mtime: s.mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The last `max` bytes of a file, from the first whole line. Never loads a 2 GB log. */
+async function readTail(path, max) {
+  const fh = await open(path, "r");
+  try {
+    const { size } = await fh.stat();
+    const start = Math.max(0, size - max);
+    const buf = Buffer.alloc(size - start);
+    await fh.read(buf, 0, buf.length, start);
+    let text = buf.toString("utf8");
+    if (start > 0) {
+      const nl = text.indexOf("\n");
+      text = nl >= 0 ? text.slice(nl + 1) : text;
+      text = `[gu support: the first ${humanSize(start)} of this file are left out — only its end is included]\n` + text;
+    }
+    return { text, size, cut: start > 0 };
+  } finally {
+    await fh.close();
+  }
+}
+
+/** Newest first; at most `n` of the files in `dir` whose names pass `keep`. */
+async function newestFiles(dir, n, keep) {
+  let names = [];
+  try {
+    names = (await readdir(dir, { withFileTypes: true })).filter((e) => e.isFile() && keep(e.name)).map((e) => e.name);
+  } catch {
+    return [];
+  }
+  const withTime = [];
+  for (const name of names) {
+    const info = await mtimeOf(join(dir, name));
+    if (info) withTime.push({ path: join(dir, name), name, ...info });
+  }
+  return withTime.sort((a, b) => b.mtime - a.mtime).slice(0, n);
+}
+
+/** Where npm keeps its debug logs on this machine (the first that exists wins per path). */
+export function npmLogDirs({ home = homedir(), env = process.env } = {}) {
+  const dirs = [];
+  if (env.npm_config_cache) dirs.push(join(env.npm_config_cache, "_logs"));
+  dirs.push(join(home, ".npm", "_logs"));
+  if (env.LOCALAPPDATA) dirs.push(join(env.LOCALAPPDATA, "npm-cache", "_logs"));
+  return [...new Set(dirs)];
+}
+
+/**
+ * What would be sent, in order of use to support: the live logs, the installer's log, npm's logs
+ * of a gu install, the newest run logs, then rotations. → [{ name, path }] (name = path in the zip).
+ */
+export async function listSupportSources({ home = homedir(), env = process.env, tmp = tmpdir(), limits = LIMITS } = {}) {
+  const root = join(home, ".gonext");
+  const out = [];
+  let names = [];
+  try {
+    names = await readdir(root);
+  } catch {
+    /* a fresh machine: no gu home yet */
+  }
+  for (const live of LIVE_LOGS) if (names.includes(live)) out.push({ name: `logs/${live}`, path: join(root, live) });
+  const installLog = join(tmp, "gu-install.log"); // install.ps1 writes npm's output here
+  if (await mtimeOf(installLog)) out.push({ name: "install/gu-install.log", path: installLog });
+  const seen = new Set();
+  let npmCount = 0;
+  for (const dir of npmLogDirs({ home, env })) {
+    for (const f of await newestFiles(dir, 20, (n) => /-debug(-\d+)?\.log$/.test(n))) {
+      if (npmCount >= limits.npmLogs || seen.has(f.name)) continue;
+      // Only npm runs that were about gu: someone's other projects' logs are none of ours.
+      const head = await readTail(f.path, 256 * 1024).then((t) => t.text).catch(() => "");
+      if (!/gu-cli|@tiens\.nguyen/.test(head)) continue;
+      seen.add(f.name);
+      npmCount++;
+      out.push({ name: `npm/${f.name}`, path: f.path });
+    }
+  }
+  for (const dir of LOG_DIRS) {
+    for (const f of await newestFiles(join(root, dir), limits.dirFiles, (n) => /\.log(\.\d+)?$/.test(n))) {
+      out.push({ name: `logs/${dir}/${f.name}`, path: f.path });
+    }
+  }
+  for (const live of LIVE_LOGS) {
+    const rotations = names
+      .filter((n) => n.startsWith(live + ".") && /^\d+$/.test(n.slice(live.length + 1)))
+      .sort((a, b) => Number(a.slice(live.length + 1)) - Number(b.slice(live.length + 1)));
+    for (const r of rotations) out.push({ name: `logs/${r}`, path: join(root, r) });
+  }
+  return out;
+}
+
+/**
+ * Read and mask every source, within the limits. → { files: [{ name, text, size, cut }], skipped }
+ * `skipped` = sources left out because the total was reached.
+ */
+export async function collectSupportFiles({ sources, limits = LIMITS } = {}) {
+  const files = [];
+  const skipped = [];
+  let total = 0;
+  for (const s of sources) {
+    if (total >= limits.total) {
+      skipped.push(s.name);
+      continue;
+    }
+    try {
+      const t = await readTail(s.path, Math.min(limits.perFile, limits.total - total));
+      const text = redactReport(t.text);
+      total += Buffer.byteLength(text);
+      files.push({ name: s.name, text, size: t.size, cut: t.cut });
+    } catch {
+      /* gone or unreadable between the listing and the read — leave it out */
+    }
+  }
+  return { files, skipped };
+}
+
+// ---------------------------------------------------------------- zip ----------------------
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+export function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function dosTime(d) {
+  const time = (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2);
+  const date = ((Math.max(1980, d.getFullYear()) - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate();
+  return { time, date };
+}
+
+/** entries [{ name, data: Buffer|string }] → a .zip Buffer (deflate). Opens in Finder, Explorer, unzip. */
+export function zipFiles(entries, now = new Date()) {
+  const { time, date } = dosTime(now);
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const e of entries) {
+    const data = Buffer.isBuffer(e.data) ? e.data : Buffer.from(String(e.data), "utf8");
+    const packed = deflateRawSync(data);
+    const name = Buffer.from(e.name, "utf8");
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(8, 8); // deflate
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(packed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(8, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(packed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt32LE(offset, 42);
+    locals.push(local, name, packed);
+    centrals.push(central, name);
+    offset += local.length + name.length + packed.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+const stamp = (d) => d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+
+/**
+ * Build the bundle: the health report + the masked logs, zipped, saved owner-only in
+ * ~/.gonext/support/. Shrinks the per-file cut until the zip fits what the API takes.
+ * → { file, bytes, zip, files: [{ name, size, cut }], skipped, reportLines }
+ */
+export async function prepareSupportBundle(opts = {}) {
+  const home = opts.home ?? homedir();
+  const now = opts.now ?? new Date();
+  const limits = { ...LIMITS, ...(opts.limits ?? {}) };
+  const reportLines = opts.reportLines ?? (await buildSupportReport({ ...opts, home, now }));
+  const sources = opts.sources ?? (await listSupportSources({ home, env: opts.env, tmp: opts.tmp, limits }));
+  let perFile = limits.perFile;
+  let built;
+  for (let round = 0; round < 6; round++) {
+    const { files, skipped } = await collectSupportFiles({ sources, limits: { ...limits, perFile } });
+    const readme = [
+      "gu support bundle",
+      `made ${now.toISOString()} on ${opts.platform ?? osPlatform()} ${release()} ${arch()}`,
+      "Every file is masked (tokens, keys, passwords) and cut to its end. Conversations are not included.",
+      "",
+      ...files.map((f) => `${f.name}  (${humanSize(f.size)}${f.cut ? ", end only" : ""})`),
+      ...(skipped.length ? ["", "left out (size limit): " + skipped.join(", ")] : []),
+    ].join("\n");
+    const zip = zipFiles([
+      { name: "README.txt", data: readme + "\n" },
+      { name: "report.txt", data: reportLines.join("\n") + "\n" },
+      ...files.map((f) => ({ name: f.name, data: f.text })),
+    ], now);
+    built = { zip, files: files.map(({ name, size, cut }) => ({ name, size, cut })), skipped };
+    if (zip.length <= limits.zip || perFile < 16 * 1024) break;
+    perFile = Math.floor(perFile / 2);
+  }
+  const dir = join(home, ".gonext", SUPPORT_DIR);
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, `gu-support-${stamp(now)}.zip`);
+  await writeFile(file, built.zip, { mode: 0o600 });
+  await pruneBundles(dir, KEEP_BUNDLES).catch(() => {});
+  return { file, bytes: built.zip.length, ...built, reportLines };
+}
+
+/** Keep the newest `keep` gu-support-*.zip; nothing else in the folder is touched. */
+export async function pruneBundles(dir, keep = KEEP_BUNDLES) {
+  const old = (await newestFiles(dir, 1000, (n) => /^gu-support-[\d-]+\.zip$/.test(n))).slice(keep);
+  for (const f of old) await unlink(f.path).catch(() => {});
+  return old.length;
+}
+
+/** One row per file for the "this is what will be sent" list. */
+export function bundleSummaryLines(bundle) {
+  const rows = [`report.txt  (version, OS, service checks)`];
+  for (const f of bundle.files) rows.push(`${f.name}  ${humanSize(f.size)}${f.cut ? " · end only" : ""}`);
+  if (bundle.skipped.length) rows.push(`(${bundle.skipped.length} older log${bundle.skipped.length === 1 ? "" : "s"} left out to keep it small)`);
+  return rows;
+}
+
+/** "darwin 25.6.0 arm64" — what the request row shows as OS. */
+export const osLine = (platform = osPlatform()) => `${platform} ${release()} ${arch()}`;
+
+/**
+ * Send the request, then the zip. → { ok: true, ref, uploaded, uploadWhy } | { ok: false, why }
+ * The request is what matters: a failed upload still leaves a reference the support team can see.
+ */
+export async function sendSupportRequest({
+  base = supportApiBase(),
+  message,
+  email,
+  version = "",
+  os = osLine(),
+  zip = null,
+  fetchImpl = fetch,
+  timeoutMs = 20_000,
+} = {}) {
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/support/requests`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ topic: "gu-cli", source: "cli", message, email, guVersion: version, os, browser: "", page: "gu support", attach: Boolean(zip) }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    return { ok: false, why: `cannot reach ${base} (${netErrorDetail(e, timeoutMs)})` };
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok || !body?.ref) return { ok: false, why: body?.error || `the server answered HTTP ${res.status}` };
+  const ref = String(body.ref);
+  if (!zip) return { ok: true, ref, uploaded: false, uploadWhy: "" };
+  if (!body.uploadKey) return { ok: true, ref, uploaded: false, uploadWhy: "this server does not take attachments yet" };
+  try {
+    const up = await fetchImpl(`${base}/api/support/requests/${encodeURIComponent(ref)}/logs`, {
+      method: "POST",
+      headers: { "content-type": "application/zip", "x-upload-key": String(body.uploadKey) },
+      body: zip,
+      signal: AbortSignal.timeout(timeoutMs * 3),
+    });
+    if (up.ok) return { ok: true, ref, uploaded: true, uploadWhy: "" };
+    const j = await up.json().catch(() => ({}));
+    return { ok: true, ref, uploaded: false, uploadWhy: j?.error || `HTTP ${up.status}` };
+  } catch (e) {
+    return { ok: true, ref, uploaded: false, uploadWhy: e?.name === "TimeoutError" ? "the upload timed out" : String(e?.message || e) };
+  }
+}
+
+/** The subject support replies keep (api replyEmail: "Re: [gu support GU-…] gu CLI / terminal"). */
+export const supportSubject = (ref = "") => `[gu support${ref ? " " + ref : ""}] gu CLI / terminal`;
+
+export function mailtoLink({ ref = "", message = "", file = "" } = {}) {
+  const body = [message || "(what went wrong)", "", file ? `Logs: please attach ${basename(file)} (saved at ${file}).` : ""].join("\n");
+  return `mailto:${SUPPORT_EMAIL}?subject=${encodeURIComponent(supportSubject(ref))}&body=${encodeURIComponent(body)}`;
+}
+
+/** When the request could not be sent, or the logs did not go with it: how to get them there. */
+export function supportFallbackLines({ ref = "", file = "", why = "" } = {}) {
+  const lines = [];
+  if (why) lines.push(`Not sent: ${why}.`);
+  lines.push(`Email ${SUPPORT_EMAIL}, subject "${supportSubject(ref)}"`);
+  if (file) lines.push(`and attach ${file}`);
+  return lines;
+}
+
+/** Reads the account email from the saved token, if any — the default answer to "reply to". */
+export async function defaultReplyEmail({ home = homedir(), env = process.env, token = null } = {}) {
+  try {
+    const ct = token ?? (await import("./cli-token.mjs"));
+    const st = await ct.readState(join(home, ".gonext"));
+    if (!st?.token) return "";
+    const check = ct.verifyCliToken(st.token, ct.publicKey(env));
+    return check.ok && ct.isEmail(check.payload?.email) ? String(check.payload.email).trim() : "";
+  } catch {
+    return "";
+  }
+}
+
+export const isEmail = (v) => /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/.test(String(v ?? "").trim());
+
+/** The API wants at least 10 characters; an empty answer still gets a useful message. */
+export function supportMessage(typed) {
+  const t = String(typed ?? "").trim();
+  if (t.length >= 10) return t.slice(0, 4000);
+  return t ? `gu CLI problem: ${t}` : "gu CLI problem (no description given) — logs attached.";
+}
+
+
+export const bundleSize = (b) => humanSize(b.bytes);

package/support-command.mjs

@@ -0,0 +1,106 @@
+/**
+ * `gu support` in a plain shell (#220) — the same flow as /support in the gu terminal, for when
+ * the terminal itself will not start (a failed install, a crash on launch).
+ *
+ *   gu support                 make the bundle, show what is in it, ask, send
+ *   gu support -m "…" --email a@b.c --yes   send without questions (scripts, a support call)
+ *   gu support --no-send       only make the bundle and say where to email it
+ *   gu support --report        print the old health report (support-report.mjs) and stop
+ *
+ * No terminal to ask on and no --yes = --no-send: never send what nobody agreed to.
+ */
+import * as sb from "./support-bundle.mjs";
+
+export function parseSupportArgs(args = []) {
+  const o = { report: false, send: null, yes: false, message: "", email: "" };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--report") o.report = true;
+    else if (a === "--no-send") o.send = false;
+    else if (a === "--send") o.send = true;
+    else if (a === "-y" || a === "--yes") o.yes = true;
+    else if ((a === "-m" || a === "--message") && i + 1 < args.length) o.message = args[++i];
+    else if (a.startsWith("--message=")) o.message = a.slice(10);
+    else if (a === "--email" && i + 1 < args.length) o.email = args[++i];
+    else if (a.startsWith("--email=")) o.email = a.slice(8);
+  }
+  return o;
+}
+
+/**
+ * → exit code. `ask(question) → answer` is the only input; `print(line)` the only output.
+ * `interactive` false = there is no one to ask.
+ */
+export async function runSupportCommand({
+  args = [],
+  version = "",
+  ask = async () => "",
+  print = (l) => console.log(l),
+  interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  home,
+  env = process.env,
+  fetchImpl = fetch,
+  bundleOpts = {},
+} = {}) {
+  const o = parseSupportArgs(args);
+  if (o.report) {
+    const { writeSupportReport } = await import("./support-report.mjs");
+    const { lines, file } = await writeSupportReport({ version, home, env, fetchImpl, ...bundleOpts });
+    for (const l of lines) print(l);
+    print("");
+    print(`  Saved to ${file}. Send it with: gu support`);
+    return 0;
+  }
+
+  print("  Collecting gu's logs (secrets are masked)…");
+  const bundle = await sb.prepareSupportBundle({ version, home, env, fetchImpl, ...bundleOpts });
+  print("");
+  print(`  Support bundle: ${bundle.file}  (${sb.bundleSize(bundle)})`);
+  for (const row of sb.bundleSummaryLines(bundle)) print(`    ${row}`);
+  print("");
+
+  const canAsk = interactive && !o.yes;
+  const willSend = o.send === false ? false : o.yes || o.send === true || canAsk;
+  if (!willSend) {
+    for (const l of sb.supportFallbackLines({ file: bundle.file })) print("  " + l);
+    if (!interactive && o.send !== false) print("  (or run `gu support --yes -m \"what went wrong\" --email you@example.com` to send it from here)");
+    return 0;
+  }
+
+  let message = o.message;
+  let email = o.email || (await sb.defaultReplyEmail({ home, env }));
+  if (canAsk) {
+    if (!message) message = await ask("  What went wrong? (one or two sentences, Enter to skip): ");
+    const typed = (await ask(`  Email for the answer${email ? ` [${email}]` : ""}: `)).trim();
+    if (typed) email = typed;
+  }
+  if (!sb.isEmail(email)) {
+    print("  No reply email — the support team could not answer you.");
+    for (const l of sb.supportFallbackLines({ file: bundle.file })) print("  " + l);
+    return 1;
+  }
+  if (canAsk) {
+    const go = (await ask(`  Send this to the gu support team (${sb.SUPPORT_EMAIL})? [Y/n] `)).trim();
+    if (!/^(|y|yes)$/i.test(go)) {
+      print("  Not sent. The bundle stays where it is:");
+      for (const l of sb.supportFallbackLines({ file: bundle.file })) print("  " + l);
+      return 0;
+    }
+  }
+
+  print("  Sending…");
+  const r = await sb.sendSupportRequest({ base: sb.supportApiBase(env), message: sb.supportMessage(message), email, version, zip: bundle.zip, fetchImpl });
+  print("");
+  if (!r.ok) {
+    for (const l of sb.supportFallbackLines({ file: bundle.file, why: r.why })) print("  " + l);
+    return 1;
+  }
+  print(`  ✓ Sent. Your reference is ${r.ref} — the answer goes to ${email}.`);
+  if (!r.uploaded) {
+    print(`  The logs did not go with it (${r.uploadWhy}).`);
+    for (const l of sb.supportFallbackLines({ ref: r.ref, file: bundle.file })) print("  " + l);
+    return 0;
+  }
+  print(`  Logs attached. To add anything, email ${sb.SUPPORT_EMAIL} with ${r.ref} in the subject.`);
+  return 0;
+}

package/terminal-layout.mjs

@@ -591,6 +591,44 @@ export function pasteHint({ platform = process.platform, images = false } = {})
 /** At least this many spaces between the mode text and the hint, or the hint is left out. */
 const HINT_MIN_GAP = 3;
 
+/** The footer's always-there help link (#220): clicking it runs /support. Plain text; painted underlined. */
+export const SUPPORT_LINK_TEXT = "? support";
+/** Spaces kept between a row's own text and the link, or the link goes to the next row / is left out. */
+const LINK_MIN_GAP = 3;
+
+/**
+ * Put a link at the RIGHT end of the first footer row that has room for it — the identity row, else
+ * the token row. Never at the cost of that row's own text: the link is dropped whole instead
+ * (every footer row stays one physical row, #109/#132/#138).
+ * → { row: "identity" | "token", from, to } (0-based columns, `to` exclusive) or null.
+ */
+export function footerLinkPlacement({ width, gutter = "   ", identity = "", token = "", link = SUPPORT_LINK_TEXT }) {
+  if (!link) return null;
+  const w = Math.max(20, width || 80);
+  for (const [row, text] of [["identity", identity], ["token", token]]) {
+    if (row === "identity" && !text) continue;
+    const used = visibleLen(gutter + text);
+    const from = w - 1 - visibleLen(link) - 1; // one column of air before the edge
+    if (used + LINK_MIN_GAP <= from) return { row, from, to: from + visibleLen(link) };
+  }
+  return null;
+}
+
+/** buildFooterRows, plus where the help link landed: → { rows, link: { rowIndex, from, to } | null }. */
+export function buildFooter({ link = "", linkPaint = (x) => x, ...args }) {
+  const place = footerLinkPlacement({ width: args.width, gutter: args.gutter, identity: args.identity, token: args.token, link });
+  const rows = buildFooterRows(args);
+  if (!place) return { rows, link: null };
+  // The identity row sits after the rule (and the rag row, when there is one).
+  const rowIndex = place.row === "identity" ? 1 + (args.rag ? 1 : 0) : 1 + (args.rag ? 1 : 0) + (args.identity ? 1 : 0);
+  const w = Math.max(20, args.width || 80);
+  const gutter = args.gutter ?? "   ";
+  const left = clipVisible(gutter + (place.row === "identity" ? args.identity : args.token), place.from);
+  rows[rowIndex] = left + " ".repeat(Math.max(1, place.from - visibleLen(left))) + linkPaint(link);
+  void w;
+  return { rows, link: { rowIndex, from: place.from, to: place.to } };
+}
+
 export function buildFooterRows({
   width,
   gutter = "   ",
@@ -2236,7 +2274,9 @@ export function scaffoldStartupNotice({ local = null, refresh = null, private: p
     const url = (/(https?:\/\/[^\s)]+\/account)/.exec(why)?.[1] ?? "https://gu.getmarsic.cc/account").replace(/^https?:\/\//, "");
     return {
       kind: "link",
-      text: "This computer isn't linked to your gu account yet.",
+      // ONE line (#222): gu asks for the token at the first message anyway, and that question has
+      // the steps behind "?". `steps` stays for a caller that wants them (`gu token`'s help).
+      text: "This computer isn't linked to your gu account yet — gu asks for a token.",
       steps: [
         `1. Copy your gu CLI token from ${url}`,
         "2. Run: gu token <your token>   (or just ask something — gu will ask for it)",