aloic 0.1.7

package/lib/login.mjs

@@ -0,0 +1,135 @@
+/* Signing a terminal in.
+ *
+ * THE DEVICE AUTHORIZATION SHAPE, and it is the only one that fits. A terminal
+ * cannot receive an email, and asking somebody to paste an account password
+ * into a command is how passwords end up in shell history. So the tool makes a
+ * request, opens a browser at it, and waits; the browser is already signed in,
+ * shows what is being asked for in words, and approves.
+ *
+ * THE TERMINAL HOLDS A SECRET THE BROWSER NEVER SEES. The request carries only
+ * the hash of it. That is what stops somebody who reads the link over your
+ * shoulder from collecting the key: they can approve the request, and the key
+ * still goes only to the process that can prove it made it.
+ *
+ * NO LOCAL WEB SERVER, and that is worth saying because it is the usual way to
+ * do this. A callback server means binding a port, which fails on locked down
+ * machines, breaks over SSH, and puts the tool's security on a socket anyone
+ * on the box can talk to. Polling an endpoint has none of those problems and
+ * works identically over SSH, in a container, and on a laptop. */
+
+import { randomBytes, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { API, PROJECT } from "./api.mjs";
+import { deviceName } from "./config.mjs";
+
+const FS = `https://firestore.googleapis.com/v1/projects/${PROJECT}/databases/(default)/documents`;
+
+const rand = n => randomBytes(n).toString("base64url").slice(0, n);
+const sha256 = s => createHash("sha256").update(s).digest("hex");
+
+/* The browser that will do the approving. Opened rather than printed when
+   there is one, printed as well as opened always: a link that only exists
+   inside a window that failed to open is a dead end, and this runs over SSH
+   often enough for that to matter. */
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startLogin(web) {
+  const rid = rand(24);
+  const token = rand(32);
+  const expiresAt = Date.now() + 10 * 60_000;
+
+  /* Created unauthenticated, which the rules allow because the document is
+     worth nothing on its own: a device name, the hash of a secret, and an
+     expiry. See cliRequests in firestore.rules. */
+  const r = await fetch(`${FS}/cliRequests?documentId=${rid}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      fields: {
+        tokenHash: { stringValue: sha256(token) },
+        device: { stringValue: deviceName() },
+        createdAt: { integerValue: String(Date.now()) },
+        expiresAt: { integerValue: String(expiresAt) }
+      }
+    })
+  });
+  if (!r.ok) {
+    const body = await r.text();
+    throw new Error(`Could not start sign in. ${body.slice(0, 200)}`);
+  }
+
+  /* THROUGH THE CONSOLE, NOT STRAIGHT AT THE APPROVAL PAGE.
+     Setting a terminal up is an authenticated act, and /dashboard is the door
+     that establishes a real session: arriving there signed out runs the
+     ordinary sign-in and comes back here, so by the time the approval screen
+     appears the browser is signed in exactly as it is for everything else.
+     Pointing at /auth directly skipped that and made this the one flow in the
+     product with its own idea of what being signed in means. */
+  return { rid, token, expiresAt, url: `${web}/dashboard/cli?code=${rid}` };
+}
+
+/* Asked for repeatedly until somebody approves it, which is what the 202 is
+   for: waiting is the expected answer, not a failure, and it must not read
+   like one in a log. */
+export async function awaitApproval({ rid, token, expiresAt }, onTick) {
+  for (;;) {
+    if (Date.now() > expiresAt) throw new Error("That sign in expired. Run it again.");
+    const r = await fetch(`${API}/api/signin/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ cli: rid, token })
+    });
+    if (r.status === 200) {
+      const got = await r.json();
+      /* Refused in the browser. Thrown with a name the caller can recognise,
+         because "cancelled" deserves different words and different choices
+         from "the network failed". */
+      if (got.status === "denied") {
+        /* CLOSING THE TAB IS NOT THE SAME AS PRESSING CANCEL. One is a
+           decision and the other is usually an accident, and the way back
+           from them is different: a decision deserves a menu, a closed tab
+           deserves the setup opening again. */
+        const no = new Error(got.closed
+          ? "The setup tab was closed."
+          : "Authentication cancelled.");
+        no.cancelled = true;
+        no.closed = got.closed === true;
+        throw no;
+      }
+      return got;
+    }
+    if (r.status === 202) {
+      /* WHICH KIND OF WAITING. "waiting" is nobody has looked at the browser
+         yet; "setup" is they approved it and are choosing how the tool should
+         work. The caller shows a different line for each, because a spinner
+         that says the same thing through both is a spinner that never
+         acknowledged the thing the person just did. */
+      const st = await r.json().then(b => b?.status, () => null);
+      onTick?.(st || "waiting");
+      /* Two seconds. Fast enough that approving feels immediate, slow enough
+         that a browser left open for ten minutes is three hundred requests
+         rather than thirty thousand. */
+      await new Promise(s => setTimeout(s, 2000));
+      continue;
+    }
+    const body = await r.json().catch(() => ({}));
+    const why = {
+      expired: "That sign in expired. Run it again.",
+      "not-yours": "That request belongs to another terminal.",
+      unknown: "That request no longer exists. Run it again."
+    }[body.error] || `Sign in failed (${r.status}).`;
+    throw new Error(why);
+  }
+}

package/lib/selfupdate.mjs

@@ -0,0 +1,136 @@
+/* Replacing this tool with a newer copy of itself.
+ *
+ * WHY THIS IS ALLOWED TO EXIST NOW. The note next door in update.mjs says a
+ * deploy tool that changes its own version by itself cannot be reasoned about,
+ * and that is still true of a tool that does it without being asked. What
+ * changed is that it is a setting somebody chose during setup, and it is only
+ * ever honoured where the answer is obviously safe:
+ *
+ *   NEVER IN A PIPELINE. No terminal means a build machine, and a build
+ *   machine that quietly moves to a version nobody pinned is the exact failure
+ *   the old note was written about.
+ *
+ *   NEVER MID-COMMAND. It runs after the work is finished, so the deploy that
+ *   just happened was done by the version that was asked for, and the new one
+ *   takes over on the next run.
+ *
+ *   NEVER OVER SOMEBODY ELSE'S INSTALL. If these files are not under
+ *   ~/.aloic/versions then something else owns them, npm or a checkout, and
+ *   quietly writing into it would be a worse bug than being out of date.
+ *
+ * The mechanics are exactly what install.sh does, in Node: read the manifest,
+ * fetch each file, check it against its published hash, and only once every
+ * one of them is verified move the whole directory into place and swing the
+ * `current` link at it. A failure at any point leaves the version that is
+ * running exactly where it was. */
+
+import { createHash } from "node:crypto";
+import { mkdir, rm, writeFile, symlink, unlink, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const GET = process.env.ALOIC_GET || "https://get.aloic.ai";
+
+const dir = () => process.env.ALOIC_HOME || join(homedir(), ".aloic");
+
+/* Whether this copy is one the installer put here, which is the only kind we
+   are entitled to replace. */
+export function installed() {
+  try {
+    const here = resolve(fileURLToPath(import.meta.url), "..", "..");
+    return here.startsWith(resolve(dir(), "versions") + sep);
+  } catch { return false; }
+}
+
+const sha256 = buf => createHash("sha256").update(buf).digest("hex");
+
+/* Fetch, verify, stage, swap. Returns the version installed. */
+export async function installVersion(version) {
+  const r = await fetch(`${GET}/manifest.json`, { signal: AbortSignal.timeout(10_000) });
+  if (!r.ok) throw new Error("Could not read the release manifest.");
+  const man = await r.json();
+  if (man?.version !== version) {
+    throw new Error(`${version} is not the published release (${man?.version}).`);
+  }
+  if (!Array.isArray(man.files) || !man.files.length) {
+    throw new Error("The release manifest is empty.");
+  }
+
+  const stage = join(dir(), `.staging-${process.pid}`);
+  await rm(stage, { recursive: true, force: true });
+  await mkdir(stage, { recursive: true });
+
+  try {
+    for (const f of man.files) {
+      if (typeof f?.path !== "string" || !/^[a-zA-Z0-9._/-]+$/.test(f.path)
+        || f.path.includes("..")) {
+        throw new Error("The release manifest names a file it should not.");
+      }
+      const hit = await fetch(`${GET}/${version}/${f.path}`,
+        { signal: AbortSignal.timeout(20_000) });
+      if (!hit.ok) throw new Error(`Could not download ${f.path}.`);
+      const body = Buffer.from(await hit.arrayBuffer());
+      if (sha256(body) !== f.sha256) {
+        throw new Error(`${f.path} did not match its published hash.`);
+      }
+      const at = join(stage, f.path);
+      await mkdir(dirname(at), { recursive: true });
+      await writeFile(at, body);
+    }
+
+    const target = join(dir(), "versions", version);
+    await mkdir(join(dir(), "versions"), { recursive: true });
+    await rm(target, { recursive: true, force: true });
+    /* The move is the moment it becomes real, and it happens only after every
+       byte has been checked. */
+    const { rename } = await import("node:fs/promises");
+    await rename(stage, target);
+
+    /* THE LINK IS SWUNG LAST. The launcher runs whatever `current` points at,
+       so until this line the running version is still the one on disk and a
+       failure above changes nothing at all. */
+    const link = join(dir(), "current");
+    await unlink(link).catch(() => {});
+    await symlink(target, link);
+    return version;
+  } finally {
+    await rm(stage, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/* What the installer published, or null if it cannot be reached. */
+export async function latest() {
+  try {
+    const r = await fetch(`${GET}/latest`, { signal: AbortSignal.timeout(4000) });
+    if (!r.ok) return null;
+    const v = (await r.text()).trim();
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch { return null; }
+}
+
+/* Whether the files sitting in `current` are byte for byte the ones the
+   manifest publishes. Cheap: a dozen small files hashed locally, one request.
+   Any missing or altered file answers false, which is the honest answer for
+   "is this install the release it claims to be". */
+export async function matches(version) {
+  try {
+    const r = await fetch(`${GET}/manifest.json`, { signal: AbortSignal.timeout(8000) });
+    if (!r.ok) return true;               /* cannot tell, so do not churn */
+    const man = await r.json();
+    if (man?.version !== version || !Array.isArray(man.files)) return true;
+    const at = join(dir(), "current");
+    const { readFile } = await import("node:fs/promises");
+    for (const f of man.files) {
+      const body = await readFile(join(at, f.path)).catch(() => null);
+      if (!body || sha256(body) !== f.sha256) return false;
+    }
+    return true;
+  } catch { return true; }
+}
+
+/* Whether the directory we would write into is actually ours to write into. */
+export async function writable() {
+  try { await stat(join(dir(), "versions")); return true; }
+  catch { return false; }
+}

package/lib/ui.mjs

@@ -0,0 +1,308 @@
+/* The parts of a terminal that make a tool feel like a tool.
+ *
+ * NO DEPENDENCIES HERE EITHER. Every one of these is thirty lines of escape
+ * codes that have worked since the 1970s, and taking a package for them means
+ * a deploy tool that stops working when that package does.
+ *
+ * EVERYTHING DEGRADES. A pipe is not a terminal: there is no cursor to move,
+ * no colour worth printing and nobody to press a key. Each of these checks and
+ * falls back to plain lines, because the same command runs on a laptop and
+ * inside a build machine and only one of those has a person watching. */
+
+import { stdin, stdout } from "node:process";
+
+const ESC = "";
+export const tty = () => !!stdout.isTTY && !!stdin.isTTY;
+
+/* Colour, unless something says otherwise. NO_COLOR is honoured because it is
+   the one convention every tool agrees on, and FORCE_COLOR because CI logs are
+   often colour capable while failing every other test for it. */
+const plain = !!process.env.NO_COLOR
+  || (!stdout.isTTY && process.env.FORCE_COLOR !== "1");
+const wrap = (a, b) => s => (plain ? String(s) : `${ESC}[${a}m${s}${ESC}[${b}m`);
+export const c = {
+  bold: wrap(1, 22), dim: wrap(2, 22), under: wrap(4, 24),
+  red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39),
+  blue: wrap(34, 39), grey: wrap(90, 39), cyan: wrap(36, 39)
+};
+
+export const out = s => stdout.write(s + "\n");
+
+/* A step with a mark in front of it, so a transcript can be skimmed for the
+   line that went wrong rather than read. */
+export const ok = s => out(`${c.green("✓")} ${s}`);
+export const bad = s => out(`${c.red("✗")} ${s}`);
+export const info = s => out(`${c.grey("·")} ${s}`);
+
+/* A spinner that knows it might not be watched. In a pipe it prints the label
+   once and returns a no-op, so a build log gets one line instead of two
+   hundred frames of animation. */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼",
+                "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function spin(label, note = "") {
+  if (!tty()) {
+    info(label);
+    if (note) info(note);
+    return { stop(final) { if (final) out(final); }, set() {}, say(n) { if (n) info(n); } };
+  }
+  let i = 0, text = label, under = note;
+
+  /* A SECOND LINE UNDER THE RING, WITHOUT LOSING THE RING'S LINE.
+   *
+   * The spinner redraws itself with a carriage return, which only ever reaches
+   * the line the cursor is on, so anything printed after it would be the line
+   * the next frame overwrites. Drawing the note and then stepping back up one
+   * row leaves the cursor where the ring lives: the note is written once per
+   * frame and never moves, and the ring goes on turning above it.
+   *
+   * This exists because a spinner alone cannot say why it is spinning. Waiting
+   * on somebody in a browser is a wait with an instruction attached, and the
+   * instruction has to be visible for the whole of it. */
+  const clear = () => {
+    stdout.write(`\r${ESC}[2K`);
+    if (under) stdout.write(`\n${ESC}[2K${ESC}[1A`);
+  };
+  const draw = () => {
+    stdout.write(`\r${ESC}[2K${c.cyan(FRAMES[i++ % FRAMES.length])} ${text}`);
+    if (under) stdout.write(`\n${ESC}[2K${c.grey(under)}${ESC}[1A`);
+  };
+  stdout.write(`${ESC}[?25l`);
+  draw();
+  const t = setInterval(draw, 80);
+  return {
+    set(s) { text = s; },
+    /* Added or changed while it is running: the wait changes character when
+       the browser hands over, and so does what somebody should be doing. */
+    say(n) {
+      /* Taking a note away has to erase the row it was on before the cursor
+         stops visiting it. */
+      if (under && !n) { stdout.write(`\n${ESC}[2K${ESC}[1A`); }
+      under = n || "";
+    },
+    stop(final) {
+      clearInterval(t);
+      clear();
+      stdout.write(`${ESC}[?25h`);
+      if (final) out(final);
+    }
+  };
+}
+
+/* A progress bar for the one part of a deploy that takes real time. */
+export function bar(done, total, width = 22) {
+  const filled = total ? Math.round((done / total) * width) : width;
+  return c.grey("[") + c.cyan("█".repeat(filled))
+    + c.grey("░".repeat(Math.max(0, width - filled))) + c.grey("]");
+}
+
+/* ---------- a box ----------
+ *
+ * WHY A BOX AT ALL, when every other line this tool prints is a mark and a
+ * sentence. Because this one is not about what the command is doing. Every
+ * other line belongs to the deploy somebody asked for; the update notice
+ * interrupts it to talk about the tool itself, and a line that reads like
+ * output but is not output is the kind of thing people learn to skim past.
+ * A frame says "this is an aside" before a word of it has been read, and it
+ * says so in one glance rather than one sentence.
+ *
+ * MEASURED WITHOUT THE COLOUR. The whole thing is alignment, and a colour code
+ * is several invisible bytes that String.length counts anyway: measure the
+ * painted string and every right hand edge lands short by however much colour
+ * that line happened to use.
+ *
+ * IT GIVES UP RATHER THAN WRAP. A frame narrower than the thing inside it is
+ * worse than no frame, so in a small terminal the lines are simply printed. */
+
+const CODES = new RegExp(ESC + "\\[[0-9;]*m", "g");
+export const wide = s => String(s).replace(CODES, "").length;
+
+export function box(lines, { title = "", tone = "yellow", pad = 2 } = {}) {
+  const paint = c[tone] || (s => s);
+  const rule = n => "─".repeat(Math.max(0, n));
+  const inner = Math.max(wide(title) + 6, ...lines.map(l => wide(l) + pad * 2));
+
+  /* Not enough room to draw one honestly, so do not draw one. */
+  if ((stdout.columns || 80) < inner + 3) {
+    if (title) out(c.bold(paint(title)));
+    lines.filter(l => wide(l)).forEach(l => out(`  ${l}`));
+    return;
+  }
+
+  /* The title sits in the top edge rather than on a line of its own: it is two
+     words, and a whole row for two words is a taller box saying no more. */
+  out(title
+    ? paint("╭─ ") + c.bold(paint(title)) + " "
+      + paint(rule(inner - 3 - wide(title)) + "╮")
+    : paint("╭" + rule(inner) + "╮"));
+
+  for (const line of lines) {
+    out(paint("│") + " ".repeat(pad) + line
+      + " ".repeat(inner - pad - wide(line)) + paint("│"));
+  }
+
+  out(paint("╰" + rule(inner) + "╯"));
+}
+
+/* ---------- asking ---------- */
+
+const readKey = () => new Promise(resolve => {
+  const onData = buf => {
+    stdin.removeListener("data", onData);
+    stdin.setRawMode(false);
+    stdin.pause();
+    resolve(buf.toString());
+  };
+  stdin.resume();
+  stdin.setRawMode(true);
+  stdin.once("data", onData);
+});
+
+/* PICK ONE, WITH ARROW KEYS, which is what makes a setup feel like a program
+   rather than a form. It falls back to a numbered list when there is no
+   terminal to drive, because the same command runs unattended.
+ *
+ * The list is redrawn in place rather than reprinted, and only a window of it
+ * is drawn at all, so somebody with forty projects does not lose their shell
+ * history to a menu. */
+export async function pick(title, items, render = String, nudge = null) {
+  if (!items.length) throw new Error("There is nothing to choose from.");
+  if (items.length === 1) {
+    out(`${title} ${c.cyan(render(items[0]))}`);
+    return items[0];
+  }
+
+  if (!tty()) {
+    /* THE ONE MESSAGE THAT FIRES EXACTLY WHEN SOMEBODY IS STUCK, so it names
+       the flag and shows it being used with a real value from the list above.
+       It used to say "name the project as an argument", which reads as a
+       positional and is not: following it literally fails with this same
+       message and no new information, which is a dead end with a signpost. */
+    out(title);
+    items.forEach(it => out(`  ${render(it)}`));
+    throw new Error(nudge ? nudge(items) : "No terminal to choose from.");
+  }
+
+  const WINDOW = Math.min(items.length, 8);
+  let at = 0, top = 0;
+
+  const draw = first => {
+    if (!first) stdout.write(`${ESC}[${WINDOW + 1}A`);
+    stdout.write(`${ESC}[2K${title}\n`);
+    for (let r = 0; r < WINDOW; r++) {
+      const i = top + r;
+      const on = i === at;
+      const line = i < items.length
+        ? `${on ? c.cyan("❯") : " "} ${on ? c.bold(render(items[i])) : render(items[i])}`
+        : "";
+      stdout.write(`${ESC}[2K${line}\n`);
+    }
+  };
+
+  stdout.write(`${ESC}[?25l`);
+  draw(true);
+  for (;;) {
+    const k = await readKey();
+    /* Ctrl-C, by hand: raw mode swallows the signal, so a tool that reads keys
+       has to honour it itself or it cannot be quit. */
+    if (k === "") { stdout.write(`${ESC}[?25h`); out(""); process.exit(130); }
+    if (k === "\r" || k === "\n") break;
+    if (k === `${ESC}[A` || k === "k") at = (at - 1 + items.length) % items.length;
+    else if (k === `${ESC}[B` || k === "j") at = (at + 1) % items.length;
+    else continue;
+    if (at < top) top = at;
+    if (at >= top + WINDOW) top = at - WINDOW + 1;
+    if (at === 0) top = 0;
+    if (at === items.length - 1) top = Math.max(0, items.length - WINDOW);
+    draw(false);
+  }
+  stdout.write(`${ESC}[?25h`);
+
+  /* Leave the ANSWER on screen and take the menu away. A finished prompt that
+     is still a menu is a transcript nobody can read afterwards. */
+  stdout.write(`${ESC}[${WINDOW + 1}A${ESC}[2K${title} ${c.cyan(render(items[at]))}\n`);
+  for (let r = 0; r < WINDOW; r++) stdout.write(`${ESC}[2K\n`);
+  stdout.write(`${ESC}[${WINDOW}A`);
+  return items[at];
+}
+
+export async function confirm(question, yes = true) {
+  if (!tty()) return yes;
+  stdout.write(`${question} ${c.grey(yes ? "[Y/n]" : "[y/N]")} `);
+  for (;;) {
+    const k = await readKey();
+
+    /* THE FIRST CHARACTER THAT MEANS ANYTHING, not the first byte.
+     *
+     * This tested `k.toLowerCase().startsWith("y")`, and a keypress does not
+     * reliably begin with the letter: a terminal can put an escape sequence in
+     * front of it, a paste arrives wrapped in bracketed-paste markers, and a
+     * pty can deliver a control byte glued to the character behind it. Every
+     * one of those read as "neither yes nor no" and fell through to the
+     * default, so on a question about deleting things somebody could type y,
+     * watch it print "no", and be told nothing was removed. It is worth being
+     * careful here in both directions: the same fall-through on a [Y/n]
+     * question would have taken yes from noise.
+     *
+     * Control characters out, whitespace off, then look. */
+    const said = k.replace(/[\u0000-\u001f\u007f]/g, "").trim().toLowerCase();
+
+    if (said.startsWith("y")) { out("yes"); return true; }
+    if (said.startsWith("n")) { out("no"); return false; }
+
+    /* Ctrl-C and Ctrl-D both mean stop, and raw mode swallows both, so a tool
+       that reads keys has to honour them itself or it cannot be quit. */
+    if (!said && /[\u0003\u0004]/.test(k)) { out(""); process.exit(130); }
+    /* Return on its own takes the default, which is exactly what the capital
+       letter in the prompt promises. */
+    if (!said && /[\r\n]/.test(k)) { out(yes ? "yes" : "no"); return yes; }
+    /* Anything else is asked again rather than guessed at. */
+  }
+}
+
+/* A line typed in, for the one question that cannot be a menu. Hidden while
+   typing, because the answer is a secret and a key echoed into a terminal is a
+   key in a screen recording. */
+export async function secret(question) {
+  if (!tty()) throw new Error("No terminal to type into.");
+  stdout.write(question + " ");
+  stdin.resume();
+  stdin.setRawMode(true);
+  let buf = "";
+  for (;;) {
+    const k = await new Promise(r => stdin.once("data", d => r(d.toString())));
+    if (k === "\u0003") { stdin.setRawMode(false); stdin.pause(); out(""); process.exit(130); }
+    if (k === "\r" || k === "\n") break;
+    if (k === "\u007f" || k === "\b") { buf = buf.slice(0, -1); continue; }
+    /* Anything that is not a printable run is an arrow key or worse. */
+    if (/^[\x20-\x7e]+$/.test(k)) buf += k;
+  }
+  stdin.setRawMode(false);
+  stdin.pause();
+  out("");
+  return buf.trim();
+}
+
+/* A line of ordinary text, echoed as it is typed. The counterpart to secret()
+   for answers that are not secrets. */
+export async function ask(question, hint) {
+  if (!tty()) return "";
+  if (hint) out(`  ${c.grey(hint)}`);
+  stdout.write(question + " ");
+  stdin.resume();
+  stdin.setRawMode(true);
+  let buf = "";
+  for (;;) {
+    const k = await new Promise(r => stdin.once("data", d => r(d.toString())));
+    if (k === "\u0003") { stdin.setRawMode(false); stdin.pause(); out(""); process.exit(130); }
+    if (k === "\r" || k === "\n") break;
+    if (k === "\u007f" || k === "\b") {
+      if (buf) { buf = buf.slice(0, -1); stdout.write("\b \b"); }
+      continue;
+    }
+    if (/^[\x20-\x7e]+$/.test(k)) { buf += k; stdout.write(k); }
+  }
+  stdin.setRawMode(false);
+  stdin.pause();
+  out("");
+  return buf.trim();
+}

package/lib/update.mjs

@@ -0,0 +1,101 @@
+/* Telling somebody a newer version exists.
+ *
+ * QUIETLY, ONCE A DAY, AND NEVER IN THE WAY. An update notice is the smallest
+ * feature in a tool and the easiest one to make hateful: check on every run and
+ * you have added a network round trip to a deploy; check loudly and you have
+ * put a banner between somebody and the output they ran the command for; check
+ * blocking and one slow registry response makes the whole tool feel broken.
+ *
+ * So: at most once a day, after the work is done, on a socket that is allowed
+ * to fail, and never at all when nobody is watching. A build machine has no use
+ * for this and its logs should not carry it.
+ *
+ * IT NEVER UPDATES ANYTHING BY ITSELF. A deploy tool that changes its own
+ * version mid-pipeline is a deploy tool that cannot be reasoned about. It says
+ * what to run and leaves the decision where it belongs. */
+
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { saveConfig } from "./config.mjs";
+import { box, c, out, tty } from "./ui.mjs";
+
+/* WHERE THE RELEASES ACTUALLY ARE. This asked the npm registry, and there is
+   no `aloic` package on it: the check ran, quietly found nothing, and reported
+   nothing, forever. The releases are hosted by us at get.aloic.ai, which is
+   also what the one line installer reads, so the tool and the installer agree
+   about what the current version is by reading the same file. */
+const GET = process.env.ALOIC_GET || "https://get.aloic.ai";
+
+/* HOW THIS COPY GOT HERE, so the suggestion is the one that will work.
+   Installed by the script, the files live under ~/.aloic/versions and the way
+   to upgrade is to run it again. Anywhere else it came through npm. */
+function viaInstaller() {
+  try {
+    const here = resolve(fileURLToPath(import.meta.url), "..", "..");
+    return here.startsWith(resolve(homedir(), ".aloic") + sep);
+  } catch { return false; }
+}
+
+/* Newer, by the ordinary three number comparison, ignoring any prerelease
+   suffix: somebody on a release candidate asked for it and does not need to be
+   told about the stable one. */
+function newer(a, b) {
+  const nums = v => String(v).split("-")[0].split(".").map(n => parseInt(n, 10) || 0);
+  const [x, y] = [nums(a), nums(b)];
+  for (let i = 0; i < 3; i++) {
+    if ((x[i] || 0) > (y[i] || 0)) return true;
+    if ((x[i] || 0) < (y[i] || 0)) return false;
+  }
+  return false;
+}
+
+export async function checkForUpdate(version) {
+  if (!tty() || process.env.ALOIC_NO_UPDATE_CHECK) return null;
+  try {
+    /* EVERY TIME, NOT ONCE A DAY.
+     *
+     * This was cached for twenty-four hours, which is the right shape for a
+     * notice printed after the work and the wrong one for a notice printed
+     * before it: somebody who updates and then runs a command should not be
+     * told for the rest of the day that they are out of date, and somebody on
+     * a build from last week should be told on the first command rather than
+     * whenever the cache happens to lapse.
+     *
+     * It costs one request for a file of eight bytes, and the whole thing is
+     * abandoned after two seconds. `checkedAt` and `latest` are still written
+     * so anything reading them keeps working. */
+    const r = await fetch(`${GET}/latest`, { signal: AbortSignal.timeout(2000) });
+    if (!r.ok) return null;
+    const latest = (await r.text()).trim();
+    if (!/^\d+\.\d+\.\d+/.test(latest)) return null;
+    void saveConfig({ checkedAt: Date.now(), latest }).catch(() => {});
+    return newer(latest, version) ? latest : null;
+  } catch {
+    /* Never a reason to say anything. */
+    return null;
+  }
+}
+
+/* THE NOTICE ITSELF, IN A FRAME.
+ *
+ * It is the one thing this tool prints that is not about the command somebody
+ * ran, and it used to be a grey line among the grey lines of a deploy, which
+ * is where a notice goes to be scrolled past. See the note on box() for why a
+ * border does the work here that another sentence could not.
+ *
+ * WHAT IT TELLS SOMEBODY TO RUN DEPENDS ON HOW THEY GOT IT. `aloic update`
+ * only replaces an install this tool made; over an npm copy or a checkout it
+ * has nothing to write to, so those are told the command that will actually
+ * work rather than the one that reads best. */
+export function tellAboutUpdate(latest, version, how = null) {
+  if (!latest) return;
+  const run = how || (viaInstaller()
+    ? "curl -fsSL https://get.aloic.ai | sh"
+    : "npm i -g aloic");
+  out("");
+  box([
+    `${c.grey(version)} ${c.grey("\u2192")} ${c.bold(c.yellow(latest))}`,
+    `Run ${c.bold(c.cyan(run))} to install it.`
+  ], { title: "Update available", tone: "yellow" });
+}