@tiens.nguyen/gu-cli 1.0.686

package/first-run-steps.mjs

@@ -0,0 +1,171 @@
+/**
+ * The mandatory first-run steps, and what to say when one of them failed (task #159).
+ *
+ * WHY THIS MODULE EXISTS. Three of the four things `gu` asks on a fresh folder are not
+ * really questions — the product does not work if you answer no. A background worker that
+ * never starts means every turn hangs; an unregistered workspace means a coding agent that
+ * cannot read the code; a missing smolagents means every turn dies at import. The user's
+ * instruction (2026-08-09) was to stop asking and just say what is happening.
+ *
+ * WHICH CREATES THE PROBLEM THIS MODULE ACTUALLY SOLVES. A prompt has one accidental virtue:
+ * the user is present when it fails, so they see the failure. Doing the work silently moves
+ * the failure somewhere nobody is looking — and a mandatory step that failed quietly is worse
+ * than the prompt it replaced, because the next symptom is a turn that hangs with no
+ * explanation. So every step's outcome is RECORDED, and a failure that is still unfixed is
+ * REPORTED on the next start, with what to do about it.
+ *
+ * PURE ON PURPOSE. Nothing here starts a daemon, installs a package or touches the network:
+ * it takes facts (is the daemon up? are the libs importable?) and returns decisions and
+ * strings. That is what lets the interesting cases — a step that failed twice, a step that
+ * fixed itself, a step that is not applicable on this machine — be tested without a machine
+ * in each of those states. The IO lives at the call sites in gu-repl.mjs.
+ */
+
+/**
+ * The steps, in the order a first run does them.
+ *
+ * `mandatory` marks the ones with no workable "no" — those get done and announced. The trust
+ * question (allow the agent to RUN build/test commands) is deliberately NOT here: it is the one
+ * prompt of the four where "no" leaves a working configuration (a read/edit-only workspace) and
+ * where "yes" has a security consequence, so it stays a question until the user says otherwise.
+ *
+ * `retry` is the command a user can run by hand. Every failure notice ends with one, because
+ * "something failed" without a next move is just anxiety.
+ */
+export const FIRST_RUN_STEPS = [
+  {
+    id: "workspace",
+    mandatory: true,
+    title: "registering this folder",
+    // Present tense, because it is printed WHILE it happens. "Registered" is the past-tense
+    // confirmation and belongs in the result line, not here.
+    doing: "registering this folder so the agent can read and edit code here",
+    why: "the agent cannot read or edit any file in a folder that is not a registered workspace",
+    retry: "gu",
+  },
+  {
+    id: "agentLibs",
+    mandatory: true,
+    doing: "installing the agent framework (smolagents + openai)",
+    why: "every turn fails at import without it — \"No module named 'smolagents'\"",
+    retry: "gu doctor",
+  },
+  {
+    id: "daemon",
+    mandatory: true,
+    doing: "starting the background worker",
+    why: "nothing claims your turns without it, so a question would hang forever",
+    retry: "gu start",
+  },
+];
+
+const BY_ID = new Map(FIRST_RUN_STEPS.map((s) => [s.id, s]));
+
+/** The step definition, or undefined for an id nothing knows about. */
+export const stepById = (id) => BY_ID.get(id);
+
+/**
+ * What still needs doing, given what is already true of this machine.
+ *
+ * `satisfied` is a map of stepId -> boolean, gathered by the caller from the real world
+ * (daemonStatus().running, hasAgentLibs(), the workspaces file). A step already satisfied is
+ * not "skipped" — there is simply nothing to do, and saying "starting the background worker"
+ * when one is already running would be a lie.
+ *
+ * clientMode is honoured here rather than at the call site because of a live failure recorded
+ * in gu-repl.mjs:4583 — a model-less droplet started a worker, won the race for a job, and
+ * failed it with no smolagents. A client-only machine runs no worker, so the step does not
+ * apply to it at all.
+ */
+export function planFirstRun({ satisfied = {}, clientMode = false } = {}) {
+  return FIRST_RUN_STEPS.filter((step) => {
+    if (step.id === "daemon" && clientMode) return false;
+    return satisfied[step.id] !== true;
+  });
+}
+
+/**
+ * Record what happened to one step. Pure: returns the NEW state, never mutates the old one.
+ *
+ * A failure keeps its first-seen time and counts repeats, so the notice can distinguish "this
+ * failed once, probably transient" from "this has failed five times, stop trying to fix it by
+ * running the same command again". A success clears the record entirely — a step that recovered
+ * has nothing to report, and a stale warning about a problem that no longer exists is how users
+ * learn to ignore warnings.
+ */
+export function recordOutcome(state, { id, ok, detail = "", at = new Date().toISOString() } = {}) {
+  const next = { ...(state || {}) };
+  const failures = { ...(next.failures || {}) };
+  if (ok) {
+    delete failures[id];
+  } else {
+    const prev = failures[id];
+    failures[id] = {
+      detail: String(detail || "").trim(),
+      // firstAt survives the repeat so "since yesterday" stays true; lastAt moves.
+      firstAt: prev?.firstAt || at,
+      lastAt: at,
+      count: (prev?.count || 0) + 1,
+    };
+  }
+  next.failures = failures;
+  return next;
+}
+
+/**
+ * The failures worth telling the user about right now.
+ *
+ * TWO FILTERS, and both matter. A step that is satisfied NOW is dropped even though it failed
+ * before — the user may have installed the package by hand, or the port freed up, and nagging
+ * about a fixed problem trains people to skip the startup text. A step that does not apply to
+ * this machine (the worker on a client-only box) is dropped for the same reason.
+ *
+ * Returned in FIRST_RUN_STEPS order, not in failure order: the list should read the same way
+ * every time, and the order steps happen in is the order that makes causal sense (no workspace
+ * explains a lot of downstream noise).
+ */
+export function pendingFailures(state, { satisfied = {}, clientMode = false } = {}) {
+  const failures = state?.failures || {};
+  return FIRST_RUN_STEPS.filter((step) => {
+    if (!failures[step.id]) return false;
+    if (satisfied[step.id] === true) return false;
+    if (step.id === "daemon" && clientMode) return false;
+    return true;
+  }).map((step) => ({ ...failures[step.id], id: step.id, step }));
+}
+
+/**
+ * The lines shown at the top of a later run, one per unresolved failure.
+ *
+ * Returns an ARRAY OF PLAIN STRINGS with no colour and no gutter — the caller owns presentation,
+ * and a test that asserts on ANSI escapes is asserting on the wrong thing. Empty array means
+ * print nothing at all, which is the common case and must stay silent: an "all good" banner on
+ * every start is noise.
+ *
+ * Each line says WHAT failed, WHY it matters, and WHAT TO RUN. The detail (the actual error) is
+ * included when there is one, truncated — a pip resolver backtrace is not a startup banner.
+ */
+export function failureNotice(failures = []) {
+  const lines = [];
+  for (const f of failures) {
+    const times = f.count > 1 ? ` (failed ${f.count} times)` : "";
+    lines.push(`last time, ${f.step.doing} failed${times} — ${f.step.why}`);
+    if (f.detail) lines.push(`  ${truncateDetail(f.detail)}`);
+    lines.push(`  run \`${f.step.retry}\` to try again`);
+  }
+  return lines;
+}
+
+/**
+ * Keep an error to one readable line.
+ *
+ * From the TAIL, not the head: the useful part of a Python traceback or an npm error is the last
+ * line ("No matching distribution found for smolagents"), while the head is boilerplate. This is
+ * the same lesson as the plain-reply truncation fix — truncating a traceback from the front
+ * throws away the only sentence that says what went wrong.
+ */
+export function truncateDetail(detail, max = 160) {
+  const oneLine = String(detail).replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) return oneLine;
+  return "…" + oneLine.slice(oneLine.length - (max - 1));
+}