@tiens.nguyen/gu-cli 1.0.792 → 1.0.794

package/clear-state.mjs

@@ -30,6 +30,10 @@ export const STATE_ITEMS = [
     what: "the account link (worker key + API base)", cost: "you sign in again" },
   { path: "client-expert.json", group: "identity",
     what: "Local-mode setup progress and the chosen mode", cost: "setup starts over" },
+  // With the setup it belongs to (#337): a leftover port file would send a fresh setup to a
+  // port chosen for a clash that may no longer exist.
+  { path: "local-api.port", group: "identity",
+    what: "the port the local API moved to (4100 was taken)", cost: "setup picks again" },
   { path: "instance", group: "identity",
     what: "this machine's id", cost: "it gets a new one" },
   { path: "cli-token.json", group: "identity",

package/cli-token.mjs

@@ -328,6 +328,10 @@ export async function readState(dir) {
     return {
       token: typeof s.token === "string" ? s.token : "",
       lastAttemptAt: isIso(s.lastAttemptAt) ? s.lastAttemptAt : null,
+      // Why the last automatic fetch failed (absent when it worked) — so the bar can tell "the gu
+      // service had a problem" from "this machine is not signed in" (#102).
+      // Present only when the last try failed: the shape is unchanged for a state that never did.
+      ...(typeof s.lastAttemptWhy === "string" && s.lastAttemptWhy ? { lastAttemptWhy: s.lastAttemptWhy } : {}),
     };
   } catch {
     return { token: "", lastAttemptAt: null };
@@ -339,7 +343,7 @@ export async function writeState(dir, state) {
   const file = join(dir, STATE_FILE);
   await mkdir(dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.tmp`;
-  await writeFile(tmp, JSON.stringify({ token: state.token ?? "", lastAttemptAt: state.lastAttemptAt ?? null }, null, 2) + "\n", {
+  await writeFile(tmp, JSON.stringify({ token: state.token ?? "", lastAttemptAt: state.lastAttemptAt ?? null, ...(state.lastAttemptWhy ? { lastAttemptWhy: state.lastAttemptWhy } : {}) }, null, 2) + "\n", {
     encoding: "utf8",
     mode: 0o600,
   });
@@ -450,7 +454,7 @@ export function shortDate(iso) {
  *
  * Never the word "licence". Returns null when the feature is off (no public key).
  */
-export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempted = false, site = DEFAULT_SITE }) {
+export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempted = false, site = DEFAULT_SITE, why = "" }) {
   if (!publicKeyB64) return null;
   const host = site.replace(/^https?:\/\//, "");
   // Shown without the scheme — shorter on a narrow bar, and still what a person types.
@@ -506,6 +510,12 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
     return null;
   } else {
     // Hosted client, its automatic fetch has failed: the bar is the only place this is said.
+    //
+    // SAY WHICH FAILURE (#102). "gu isn't signed in · run gu login" was shown on a machine that WAS
+    // signed in — its worker key worked and turns ran — because the gu service answered HTTP 502 to
+    // the token fetch. `gu login` does not fix a server error; the next automatic try does.
+    const trouble = fetchTrouble(why);
+    if (trouble) return { kind: "unchecked", urgent: false, text: `plan not checked — ${trouble} · gu will try again` };
     return { kind: "missing", urgent: false, text: "gu isn't signed in · run gu login" };
   }
 
@@ -515,6 +525,19 @@ export function barNotice({ token, publicKeyB64, mode, now = new Date(), attempt
     : { kind: "stale", urgent: false, text: "gu token is old · run gu login" };
 }
 
+/**
+ * A failed token fetch that is the SERVICE's or the network's doing, in words — or "" when it is
+ * this machine's (a refused key: http-401/403), or unknown. `why` is renewToken's.
+ */
+export function fetchTrouble(why) {
+  const w = String(why ?? "");
+  const http = /^http-(\d{3})$/.exec(w);
+  if (http) return Number(http[1]) >= 500 ? `the gu service had an error (HTTP ${http[1]})` : "";
+  if (w === "network" || w === "timeout" || w === "no-api") return "the gu service could not be reached";
+  if (w === "bad-response") return "the gu service sent an unexpected answer";
+  return "";
+}
+
 /** "Free plan" / "Pro plan" — the name a person uses. */
 const planName = (plan) => (plan === "pro" ? "Pro plan" : plan === "trial" ? "free trial" : "Free plan");
 /** "1 computer" / "4 computers" — "computer", not "device": a device is also a phone. */

package/client-expert-api.mjs

@@ -27,9 +27,64 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-/** Where the local API listens. 4100 keeps clear of the hosted API and of Vite's 5173. */
-export const LOCAL_API_PORT = Number(process.env.GONEXT_LOCAL_API_PORT ?? "4100") || 4100;
-export const LOCAL_API_BASE = `http://127.0.0.1:${LOCAL_API_PORT}`;
+/** Where the local API listens by default. 4100 keeps clear of the hosted API and of Vite's 5173. */
+export const DEFAULT_LOCAL_API_PORT = 4100;
+/** The port setup had to move to, when 4100 belonged to another program (task #337). */
+export const API_PORT_FILE = join(homedir(), ".gonext", "local-api.port");
+
+const validPort = (v) => {
+  const n = Number.parseInt(String(v ?? "").trim(), 10);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+};
+
+/**
+ * WHICH PORT THE LOCAL API USES, and why (task #337).
+ *
+ *   env   — GONEXT_LOCAL_API_PORT: someone chose it; gu never moves away from it on its own.
+ *   saved — ~/.gonext/local-api.port: 4100 was taken by ANOTHER PROGRAM when the API was first
+ *           started, and gu moved. Every later process — `gu`, `gu-cli api …`, the worker's
+ *           terminal — reads the same file, so they all follow the move.
+ *   default — 4100. A machine where 4100 was free has no file and behaves exactly as before.
+ *
+ * Pure: the file's text is passed in.
+ */
+export function resolveApiPort({ env = process.env, saved = "" } = {}) {
+  const fromEnv = validPort(env.GONEXT_LOCAL_API_PORT);
+  if (fromEnv) return { port: fromEnv, source: "env" };
+  const fromFile = validPort(saved);
+  if (fromFile) return { port: fromFile, source: "saved" };
+  return { port: DEFAULT_LOCAL_API_PORT, source: "default" };
+}
+
+function readSavedPort() {
+  try {
+    return readFileSync(API_PORT_FILE, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * LIVE BINDINGS, not constants: thirty readers across gu take the port from these two names. When
+ * setup moves the API in THIS process they must all see the new port at once — an ES module's
+ * exported `let` does exactly that for every importer, and a default parameter reads it at call
+ * time. Other processes get it from the file when they start.
+ */
+export let LOCAL_API_PORT = resolveApiPort({ saved: readSavedPort() }).port;
+export let LOCAL_API_BASE = `http://127.0.0.1:${LOCAL_API_PORT}`;
+
+/** Use `port` from now on in this process (and, with save, in every later one). */
+export async function useApiPort(port, { save = true } = {}) {
+  const n = validPort(port);
+  if (!n) throw new Error(`not a port: ${port}`);
+  LOCAL_API_PORT = n;
+  LOCAL_API_BASE = `http://127.0.0.1:${n}`;
+  if (save) {
+    await mkdir(join(homedir(), ".gonext"), { recursive: true });
+    await writeFile(API_PORT_FILE, `${n}\n`, "utf8");
+  }
+  return n;
+}
 export const LOCAL_MONGO_URI = process.env.GONEXT_LOCAL_MONGO_URI || "mongodb://127.0.0.1:27017";
 export const LOCAL_DB_NAME = process.env.GONEXT_LOCAL_DB_NAME || "gu";
 
@@ -189,7 +244,39 @@ export function npmInstallCommand(platform = process.platform) {
   };
 }
 
-export function installApiDeps(apiDir, { onLine } = {}) {
+/**
+ * A DROPPED CONNECTION IS NOT A FAILED INSTALL (task #333). The Windows 11 test box fetched
+ * single packages in 30 s and then got "npm error network read ECONNRESET" — twice in a row, on
+ * the first install, which then stopped with "Run `gu` again". A rerun went through. npm keeps
+ * what it already downloaded, so trying again in place is cheap and is what the user would do.
+ * Only NETWORK failures are retried: a real error (a bad package, a full disk) fails the same way
+ * every time, and three copies of it would only bury it.
+ */
+export function isNetworkNpmError(text) {
+  return /\b(ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|ENETUNREACH|EPIPE|ERR_SOCKET_TIMEOUT)\b|socket hang up|network (read|request)/i.test(
+    String(text ?? "")
+  );
+}
+
+/** npm on Windows exits with a NEGATIVE errno that arrives unsigned: 4294963219 is -4077. */
+export function signedExitCode(code) {
+  return typeof code === "number" && code > 0x7fffffff ? code - 0x100000000 : code;
+}
+
+export const API_DEPS_ATTEMPTS = 3;
+
+export async function installApiDeps(apiDir, { onLine, attempts = API_DEPS_ATTEMPTS, once = installApiDepsOnce } = {}) {
+  for (let i = 1; ; i++) {
+    try {
+      return await once(apiDir, { onLine });
+    } catch (e) {
+      if (i >= attempts || !isNetworkNpmError(`${e?.output ?? ""}\n${e?.message ?? ""}`)) throw e;
+      onLine?.(`network error — trying again (${i + 1} of ${attempts}); what was downloaded is kept`);
+    }
+  }
+}
+
+function installApiDepsOnce(apiDir, { onLine } = {}) {
   const { cmd, args, shell, line } = npmInstallCommand();
   return new Promise((resolve, reject) => {
     let child;
@@ -212,7 +299,11 @@ export function installApiDeps(apiDir, { onLine } = {}) {
     });
     child.on("error", (e) => reject(new Error(`could not run ${cmd} in ${apiDir}: ${e.message}`)));
     child.on("exit", (code) =>
-      code === 0 ? resolve() : reject(new Error(`npm install failed (exit ${code}) ${err.slice(-400)}`))
+      code === 0
+        ? resolve()
+        : // `output` keeps ALL of stderr: the 400-char tail in the message had already lost the
+          // "ECONNRESET" line on the real Windows failure, so the retry never saw it.
+          reject(Object.assign(new Error(`npm install failed (exit ${signedExitCode(code)}) ${err.slice(-400)}`), { output: err }))
     );
   });
 }
@@ -257,6 +348,150 @@ export async function seedDatabase({
   }
 }
 
+/**
+ * WHO IS ON A PORT → "free" | "gu" | "other" (task #337).
+ *
+ * "gu" is anything that answers /api/health the way this API does — usable or not, this home's
+ * or another's: it is our program and moving away from it would start a second one. "other" is a
+ * port that accepts a connection and is not that: someone else's server. Only "other" is a
+ * reason to move.
+ */
+export async function whoHoldsPort(port, { fetchImpl = fetch, connects = tcpConnects } = {}) {
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(2500) });
+    const body = await res.json().catch(() => null);
+    if (body && typeof body === "object" && ("dataBackend" in body || "persistence" in body)) return "gu";
+    return "other";
+  } catch {
+    return (await connects(port)) ? "other" : "free";
+  }
+}
+
+/** Does anything accept a TCP connection on 127.0.0.1:port? */
+async function tcpConnects(port, timeoutMs = 1500) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const sock = net.connect({ host: "127.0.0.1", port });
+    const done = (v) => {
+      sock.destroy();
+      resolve(v);
+    };
+    sock.setTimeout(timeoutMs, () => done(false));
+    sock.once("connect", () => done(true));
+    sock.once("error", () => done(false));
+  });
+}
+
+/** Can a server be opened on `port` right now? The only honest test of "free". */
+async function canListen(port) {
+  const net = await import("node:net");
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.listen(port, () => srv.close(() => resolve(true)));
+  });
+}
+
+/** How many ports after the taken one are tried before asking the system for any free one. */
+export const API_PORT_TRIES = 10;
+
+/** The first port after `taken` that a server can open — else one the system picks. */
+export async function findFreePort(taken, { isFree = canListen, tries = API_PORT_TRIES, anyFree = systemFreePort } = {}) {
+  for (let p = taken + 1; p <= taken + tries && p < 65536; p++) {
+    if (await isFree(p)) return p;
+  }
+  return anyFree();
+}
+
+async function systemFreePort() {
+  const net = await import("node:net");
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.once("error", reject);
+    srv.listen(0, () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * What to do about the port before starting the API. Pure.
+ *   use    — it is free, or gu's own API is already there.
+ *   move   — another program has it and nobody insisted on this port.
+ *   refuse — another program has it and GONEXT_LOCAL_API_PORT asked for exactly this port:
+ *            an explicit choice is not overridden, it is reported.
+ */
+export function portDecision({ holder, source }) {
+  if (holder !== "other") return "use";
+  return source === "env" ? "refuse" : "move";
+}
+
+/**
+ * MAKE SURE THE API HAS A PORT IT CAN OPEN, moving off one that belongs to another program.
+ *
+ * The first install used to end in "The API started but is not usable: not up yet" when 4100
+ * was somebody else's — the API could not bind, and nothing said why. Now gu says which program
+ * has the port, takes the next free one, REMEMBERS it (API_PORT_FILE), and re-points worker.env
+ * when there is one, so the terminal and the worker follow.
+ *
+ * → { moved, port, from?, holder? }. Never throws: a port problem must not hide the real error.
+ */
+export async function settleApiPort({
+  log = (l) => console.log(l),
+  env = process.env,
+  holds = whoHoldsPort,
+  nameOf = null,
+  freePort = findFreePort,
+} = {}) {
+  const from = LOCAL_API_PORT;
+  try {
+    const source = resolveApiPort({ env, saved: readSavedPort() }).source;
+    const holder = await holds(from);
+    const action = portDecision({ holder, source });
+    if (action === "use") return { moved: false, port: from };
+    // The program's name when the system gives it; on Windows it often does not (seen live),
+    // and "another program (another program)" is not a sentence.
+    const name = (await (nameOf ?? (await import("./mongo-native.mjs")).portHolder)(from).catch(() => null)) || "";
+    const who = name || "another program";
+    if (action === "refuse") {
+      log(`  Port ${from} (set by GONEXT_LOCAL_API_PORT) is in use by ${who}.`);
+      log("  Stop that program, or choose another port, then run gu again.");
+      return { moved: false, port: from, holder: who, refused: true };
+    }
+    const to = await freePort(from);
+    await useApiPort(to);
+    log(`  Port ${from} is used by another program${name ? ` (${name})` : ""} — gu's API uses ${to}.`);
+    // An install that was already working: its terminal and its worker read worker.env. The
+    // worker read it ONCE, at start, so it is restarted — or it would poll the old port forever.
+    if (await repointWorkerEnv(from, to)) {
+      try {
+        const ctl = await import("./daemon-control.mjs");
+        if ((await ctl.daemonStatus()).running) {
+          await ctl.stopDaemon();
+          await ctl.startDaemon();
+          log("  · restarted the background worker so it uses the new port");
+        }
+      } catch {
+        log("  · restart the background worker to pick up the new port: gu-cli restart");
+      }
+    }
+    return { moved: true, port: to, from, holder: who };
+  } catch {
+    return { moved: false, port: from };
+  }
+}
+
+/** worker.env pointed at the local API on the old port → point it at the new one. */
+async function repointWorkerEnv(from, to) {
+  const path = join(GONEXT_DIR, "worker.env");
+  const text = await readFile(path, "utf8").catch(() => "");
+  const re = new RegExp(`^(GONEXT_API_BASE=https?://(?:127\\.0\\.0\\.1|localhost)):${from}\\b`, "m");
+  if (!re.test(text)) return false;
+  await writeFile(path, text.replace(re, `$1:${to}`));
+  return true;
+}
+
 /**
  * Start the API so it OUTLIVES this terminal — including an SSH session.
  *
@@ -271,8 +506,16 @@ export async function startLocalApi({
   port = LOCAL_API_PORT,
   mongoUri = localMongoUri(),
   dbName = LOCAL_DB_NAME,
+  log = (l) => console.log(l),
 } = {}) {
   await mkdir(GONEXT_DIR, { recursive: true });
+  // Every start goes through here — setup, `gu-cli api start|restart|upgrade`, doctor, the
+  // terminal's own restart — so this is where a port taken by another program is noticed.
+  // A caller that named a port keeps it.
+  if (port === LOCAL_API_PORT) {
+    const settled = await settleApiPort({ log });
+    port = settled.port;
+  }
   const res = await spawnSurviving({
     cmd: process.execPath,
     args: ["index.js"],
@@ -286,7 +529,7 @@ export async function startLocalApi({
   // we spawned. Recorded after the server is up, by the caller's waitForApi.
   const pid = res.pid ?? null;
   if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
-  return { pid, how: res.how };
+  return { pid, how: res.how, port };
 }
 
 /** Record whoever is serving the port, so `api stop` has something to stop. */

package/client-expert-run.mjs

@@ -20,11 +20,13 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
+import { localModeNodeProblem } from "./node-version.mjs";
 import {
   apiDepsInstalled,
   installApiDeps,
   seedDatabase,
   startLocalApi,
+  settleApiPort,
   waitForApi,
   probeLocalApi,
   writeWorkerEnv,
@@ -515,7 +517,7 @@ export async function preflightLocalMongo({
   log("\n  " + red("gu: MongoDB is not answering") + dim(` at ${host}:${port}`) +
     red(mongo.installed || mongo.silentPort || !local ? "." : " — it is not installed on this machine."));
   log(dim("  Local mode keeps your conversations, models and keys in that database, so"));
-  log(dim("  nothing can start without it. The API on :4100 is fine — it is waiting on this."));
+  log(dim(`  nothing can start without it. The API on :${LOCAL_API_PORT} is fine — it is waiting on this.`));
   if (!local) {
     log(dim(`\n  That database is on another machine (${host}). Start it there, then run gu again.\n`));
     return { ok: false, fixed: false, installed: false };
@@ -925,6 +927,16 @@ export function markInterruptedOnExit(getState, stepId) {
   };
 }
 
+/** The last few non-empty lines of the API log, clipped to the screen — [] when there is none. */
+export async function apiLogTail(file, { lines = 3, width = 72 } = {}) {
+  try {
+    const all = (await readFile(file, "utf8")).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return all.slice(-lines).map((l) => (l.length > width ? l.slice(0, width - 1) + "…" : l));
+  } catch {
+    return [];
+  }
+}
+
 export async function runClientExpertSetup({
   ask,
   // #301/#300: a MASKED line reader (API keys, the MongoDB password). Absent → no key is asked.
@@ -940,6 +952,15 @@ export async function runClientExpertSetup({
     return { complete: false, stoppedAt: "gate" };
   }
 
+  // BEFORE ANYTHING IS INSTALLED (task #333): the API needs a newer Node than gu does. Not part
+  // of the gate on purpose — a gate "no" makes the first run settle on Cloud mode for good,
+  // while the fix here is a Node upgrade, after which `gu` must resume Local setup.
+  const nodeProblem = localModeNodeProblem(process.version, machine.platform);
+  if (nodeProblem) {
+    console.log("\n  " + red("✗ ") + nodeProblem + "\n");
+    return { complete: false, stoppedAt: "node" };
+  }
+
   let state = await loadState();
   const mongo = await probeMongo();
   const probe = {
@@ -1165,13 +1186,27 @@ export async function runClientExpertSetup({
   // --- the API itself -------------------------------------------------------------------
   let health = await probeLocalApi(LOCAL_API_PORT);
   if (!health.ok) {
-    console.log("\n  " + bold(`Starting the local API on port ${LOCAL_API_PORT}`));
-    await startLocalApi({ apiDir, mongoUri });
-    health = await waitForApi({ port: LOCAL_API_PORT });
+    // THE PORT FIRST (task #337): 4100 may belong to another program on this machine. Settled
+    // before the "Starting…" line so that line names the port the API will really use —
+    // LOCAL_API_PORT and LOCAL_API_BASE are live and change with it.
+    console.log("");
+    const settled = await settleApiPort({ log: (l) => console.log(l) });
+    console.log("  " + bold(`Starting the local API on port ${LOCAL_API_PORT}`));
+    if (!settled.refused) {
+      await startLocalApi({ apiDir, mongoUri });
+      health = await waitForApi({ port: LOCAL_API_PORT });
+    }
   }
   if (!health.ok) {
     // apiIsUsable, not a 200: a wrong DATA_BACKEND answers 200 and stores nothing.
     console.log("\n  " + red("✗ ") + `The API started but is not usable: ${health.why}`);
+    // WHAT THE API SAID, not only where it said it (task #333): on Windows the whole log was
+    // one line, "Access is denied.", and the screen showed only a path to go and open.
+    const said = await apiLogTail(API_LOG_FILE);
+    if (said.length) {
+      console.log(dim("  The last thing its log says:"));
+      for (const l of said) console.log(dim("    " + l));
+    }
     console.log(dim(`  Its log is ${API_LOG_FILE}`));
     console.log(dim("  Run `gu` again to retry — nothing else has been changed.\n"));
     state = recordStep(state, "api-running", "failed", { reason: health.why });

package/client-expert-setup.mjs

@@ -834,12 +834,30 @@ export function validateLicenseVerdict({ licenseToken, expertAvailable }, result
  * validateLicenseToken by default; injectable for tests. Never throws — a validation that errors
  * is treated as unverifiable, not a crash.
  */
+/**
+ * What to say when a license token could not be CONFIRMED (#102) — it is still used: the licence
+ * is soft, and an outage never blocks a paid user. But "couldn't reach the license server" was
+ * printed when the server had been reached and answered HTTP 502; say which it was.
+ * `detail` is validateLicenseToken's: "http-NNN" | "timeout" | "network" | "bad-response" | …
+ */
+export function licenseUnverifiedLine(detail) {
+  const http = /^http-(\d{3})$/.exec(String(detail ?? ""));
+  if (http) return `The license server answered with an error (HTTP ${http[1]}), so the token was not confirmed — showing the menu anyway.`;
+  if (detail === "bad-response") return "The license server sent an unexpected answer, so the token was not confirmed — showing the menu anyway.";
+  return "Couldn't reach the license server to confirm the token — showing the menu anyway.";
+}
+
 export async function promptForLicenseToken(ask, initialToken, {
   validate = validateLicenseToken,
   validateOpts = {},
   warn = (msg) => console.log(msg),
   maxTries = 5,
+  // A MASKED reader (#100). A license token is a credential — whoever holds one can renew it —
+  // and the plain reader echoed it into the terminal and its scrollback (and into a test log).
+  // The first run and the REPL both have one; without it (a caller that has none) it is `ask`.
+  askSecret = null,
 } = {}) {
+  const read = typeof askSecret === "function" ? askSecret : ask;
   let token = String(initialToken ?? "").trim();
   for (let attempt = 0; attempt < maxTries; attempt += 1) {
     // Format gate first — a malformed token is warned about WITHOUT a network round-trip.
@@ -851,7 +869,9 @@ export async function promptForLicenseToken(ask, initialToken, {
       if (result.ok || result.reason === "unverified") return { token, result, declined: false };
       warn(`  That license token was not accepted (${result.detail ?? result.reason}).`);
     }
-    const again = String(await ask("  Paste a pro license token to choose a hosted mode, or press Enter to keep this machine private: ") ?? "").trim();
+    // Esc in the masked reader resolves with a symbol (SKIP_ALL): that is "no token", like Enter.
+    const typed = await read("  Paste a pro license token to choose a hosted mode, or press Enter to keep this machine private: ");
+    const again = typeof typed === "string" ? typed.trim() : "";
     if (!again) return { token: "", result: null, declined: true };
     token = again;
   }

package/first-run-steps.mjs

@@ -169,3 +169,29 @@ export function truncateDetail(detail, max = 160) {
   if (oneLine.length <= max) return oneLine;
   return "…" + oneLine.slice(oneLine.length - (max - 1));
 }
+
+/**
+ * Ctrl+C or Ctrl+D while a first-run question is waiting (task #333).
+ *
+ * `interrupt` (Ctrl+C): when setup has a step in progress it registered a SIGINT listener on the
+ * process (markInterruptedOnExit) that records where it stopped and exits — hand over to it.
+ * Otherwise say so and exit 130 here. `eof` (Ctrl+D): input is over; nothing more can be asked.
+ *
+ * Everything it touches is passed in, so the branches are tested without a terminal.
+ */
+export function stopFirstRun({ reason, hasProcessListener, emitSigint, log, exit, style = {} }) {
+  const yellow = style.yellow ?? ((t) => t);
+  const dim = style.dim ?? ((t) => t);
+  if (reason === "interrupt") {
+    if (hasProcessListener) {
+      emitSigint();
+      return;
+    }
+    log("\n\n  " + yellow("Stopped.") + dim(" Run `gu` again and setup continues from this step.\n"));
+    exit(130); // 128 + SIGINT
+    return;
+  }
+  log("\n\n  " + dim("input ended (Ctrl+D) — nothing further will be asked or started."));
+  log("  " + dim("Run `gu` again and setup continues from this step.\n"));
+  exit(0);
+}