samagotchi 0.4.0 → 0.5.0

data/lib/samagotchi/web/public/timing.js

@@ -20,11 +20,15 @@ export function turnTimingText(number, durationMs, { running = false, canceled =
   return `${turn}${running ? " running" : ""} · ${formatDuration(durationMs)}${canceled ? " · canceled" : ""}`;
 }
 
-// The line a canceled turn ends with: "✕ canceled (user)", live from
+// A cancel's reason as the terminal UIs name it too (Formatting::
+// CANCEL_REASONS); anything else as it is.
+const CANCEL_REASONS = { ctrl_c: "Ctrl-C", user: "stopped", hook: "by a hook" };
+
+// The line a canceled turn ends with: "✕ canceled (stopped)", live from
 // turn_canceled's reason and after a re-render from the turn record's
 // cancellation_reason (records saved before it existed: no reason).
 export function cancelLineText(reason) {
-  return "\u2715 canceled" + (reason ? ` (${reason})` : "");
+  return "\u2715 canceled" + (reason ? ` (${CANCEL_REASONS[reason] || reason})` : "");
 }
 
 // A re-rendered turn's cancel line (a .bubble.cancel), or "" when the turn

data/lib/samagotchi/web/public/turn_events.js

@@ -82,13 +82,16 @@ export function isCommandLine(text) {
   return /^[/!]/.test(String(text || "").trim());
 }
 
-// The terminal's own commands that have a button in the web: the reply
-// the page shows itself (they never go to the worker, which doesn't know
-// them), or null.
+// The terminal's own commands (a button in the web, or none yet): the
+// reply the page shows itself (they never go to the worker, which doesn't
+// know them), or null.
 const WEB_LOCAL_REPLIES = {
   "/archive": "/archive: use the archive button in the session bar",
+  "/detach": "/detach: a terminal's command; close the tab to leave, the worker keeps running",
   "/exit": "/exit: close the tab to leave; stop in the session bar stops the worker",
   "/quit": "/quit: close the tab to leave; stop in the session bar stops the worker",
+  "/recap": "/recap: not in the web yet; a recap shows here by itself when you come back to an idle session, and /recap in a terminal (chi --attach) makes one now",
+  "/stats": "/stats: not in the web yet; each turn shows its time and the context use, and /stats in a terminal (chi --attach) has the totals",
 };
 
 export function webLocalReply(text) {
@@ -233,11 +236,12 @@ export function snapshotEvents({ current_turn: turn = null, queued = [], started
           closeText();
           const call = { iteration: part.iteration, call_index: part.call_index, tool: part.tool };
           if (part.label) call.label = part.label;
-          events.push({ type: "tool_call_started", ...call, params: part.params });
+          const title = part.title ? { title: part.title } : {};
+          events.push({ type: "tool_call_started", ...call, params: part.params, ...title });
           if (part.status !== "running") {
             const completed = {
               type: "tool_call_completed", ...call, output: part.output, output_truncated: !!part.output_truncated,
-              activity: { status: part.status, params: part.params },
+              activity: { status: part.status, params: part.params, ...title },
             };
             if (part.diff) completed.diff = part.diff;
             events.push(withImages(completed, part.images));

data/lib/samagotchi/web/public/turn_model.js

@@ -169,18 +169,26 @@ export function applyEvent(turn, event) {
   }
 }
 
+function cut(line) {
+  return line.length > LABEL_MAX ? `${line.slice(0, LABEL_MAX).trimEnd()}…` : line;
+}
+
 function toolCallsText(n) {
   return `${n} tool call${n === 1 ? "" : "s"}`;
 }
 
-// The collapsed row of a gen: its narration's first line, else the tools it
-// worked with, else "thinking"; then its call count.
+// The collapsed row of a gen: its narration's first line, else its first
+// call's title ("edit lib/a.rb"), else the tools it worked with, else
+// "thinking"; then its call count.
 export function genLabel(gen) {
   const line = String(gen.text || "").trim().split("\n")[0].trim();
   const calls = gen.tools.length;
+  const first = gen.tools[0];
   let head;
   if (line) {
-    head = line.length > LABEL_MAX ? `${line.slice(0, LABEL_MAX).trimEnd()}…` : line;
+    head = cut(line);
+  } else if (first?.title) {
+    head = cut(`${toolName(first)} ${first.title}`);
   } else if (calls) {
     const names = [...new Set(gen.tools.map(toolName))];
     head = `working with ${names.slice(0, LABEL_TOOLS).join(", ")}${names.length > LABEL_TOOLS ? ", …" : ""}`;

data/lib/samagotchi/web/public/turn_view.js

@@ -23,7 +23,31 @@ import { createTicker } from "./thinking_ticker.js";
 import * as model from "./turn_model.js";
 import { createHold } from "./hold.js";
 
-export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawText, sessionId }) {
+// The container seams (the stage view composes this view, stage_view.js):
+//   blockHost(el)  puts the turn's block in the page (default: the history);
+//   follow()       keeps the live part in view (default: the history's
+//                  tail), called only when isNearBottom() said so before
+//                  the change;
+//   placeAnswer(pieces, { plain, blockEl }) puts the promoted answer (a
+//                  plain answer's thinking, cards, bubble) in the page
+//                  (default: in the block's place for a plain answer,
+//                  else after it in the history);
+//   useHold        the answer's pop at the narration box's height (hold.js);
+//   newestFirst    a new step goes on top of the block while the turn runs
+//                  (chronological() restores the order);
+//   onChange()     after anything in the turn changed (the stage redraws
+//                  its slots from current());
+//   onThinkingLine(sentence) the live step's ticker showed a new line.
+export function createTurnView({
+  historyEl, appendToHistory, isNearBottom, sawText, sessionId,
+  blockHost = appendToHistory,
+  follow = () => { historyEl.scrollTop = historyEl.scrollHeight; },
+  placeAnswer = defaultPlaceAnswer(appendToHistory),
+  useHold = true,
+  newestFirst = false,
+  onChange = () => {},
+  onThinkingLine = () => {},
+}) {
   let turn = null;
   let blockEl = null;
   let blockSummaryEl = null;
@@ -36,7 +60,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
   let rafPending = false;
   // The promoted answer bubble while it is held at the box's height (the
   // pop, D6).
-  const hold = createHold({ isNearBottom, follow: () => { historyEl.scrollTop = historyEl.scrollHeight; } });
+  const hold = createHold({ isNearBottom, follow });
 
   function removeHint() {
     const hint = historyEl.querySelector(".hint");
@@ -58,7 +82,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     blockEl.appendChild(blockSummaryEl);
     rememberToggle(blockSummaryEl, () => { blockToggled = true; });
     updateBlockSummary();
-    appendToHistory(blockEl);
+    blockHost(blockEl);
   }
 
   function updateBlockSummary() {
@@ -86,9 +110,10 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
       feed: createSentenceFeed(), box: null };
     rememberToggle(summary, () => { entry.toggled = true; });
     genEls.set(gen, entry);
-    const follow = isNearBottom();
-    blockEl.appendChild(el);
-    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+    const stick = isNearBottom();
+    if (newestFirst) blockEl.insertBefore(el, blockSummaryEl.nextSibling);
+    else blockEl.appendChild(el);
+    if (stick) follow();
     return entry;
   }
 
@@ -135,6 +160,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     entry.thinkingLine.classList.remove("thinking-fade");
     void entry.thinkingLine.offsetWidth;
     entry.thinkingLine.classList.add("thinking-fade");
+    onThinkingLine(sentence);
   }
 
   // Feed the step's ticker from its accumulated thinking; the caller's timer
@@ -228,10 +254,11 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     rafPending = false;
     // Runs every animation frame while streaming — must not yank a user who
     // scrolled up to read; only follow when they were already near the bottom.
-    const follow = isNearBottom();
+    const stick = isNearBottom();
     for (const gen of dirty) writeGen(gen, { follow: true });
     dirty.clear();
-    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+    if (stick) follow();
+    onChange();
   }
 
   function scheduleFlush(gen) {
@@ -291,6 +318,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     if (r.closed) closeGenEl(r.closed);
     if (r.opened) createGenEl(r.gen);
     if (r.closed || r.opened) updateBlockSummary();
+    onChange();
   }
 
   function toolEvent(r) {
@@ -311,14 +339,15 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
       }
       el.querySelector(".activity-output").style.display = "none";
       entry.rows.set(r.row.key, el);
-      const follow = isNearBottom();
+      const stick = isNearBottom();
       body.appendChild(el);
       fillActivityRow(el, r.row, sessionId());
-      if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+      if (stick) follow();
     } else {
       fillActivityRow(el, r.row, sessionId());
     }
     updateBlockSummary();
+    onChange();
   }
 
   // A hook's line (hook_notice) as a row of the current step, above the row
@@ -333,9 +362,9 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     const el = document.createElement("div");
     el.className = "hook-notice" + (data.level === "warn" ? " warn" : "");
     el.textContent = data.line || `${hookNoticeLabel(data.hook)}: ${data.text || ""}`;
-    const follow = isNearBottom();
+    const stick = isNearBottom();
     activityEl(r.gen).appendChild(el);
-    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+    if (stick) follow();
     return true;
   }
 
@@ -368,9 +397,9 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     const entry = gen && genEls.get(gen);
     if (!entry) return false;
     if (!gen.text) entry.text.textContent = "";
-    const follow = isNearBottom();
+    const stick = isNearBottom();
     activityEl(gen).appendChild(el);
-    if (follow) historyEl.scrollTop = historyEl.scrollHeight;
+    if (stick) follow();
     return true;
   }
 
@@ -384,7 +413,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     bubble.className = "bubble output";
     if (!gen.text) bubble.textContent = "";
     // A hidden tab gets no pop: nobody sees it, and its timers are throttled.
-    const holding = heldHeight > 0 && !!gen.text && !document.hidden;
+    const holding = useHold && heldHeight > 0 && !!gen.text && !document.hidden;
     let holdHeight = 0;
     if (holding) {
       // Bubbles are border-box: the box's height plus the bubble's own
@@ -425,12 +454,11 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
       }
       pieces.push(...cards);
       if (gen.text) pieces.push(bubble);
-      blockEl.replaceWith(...pieces);
+      placeAnswer(pieces, { plain: true, blockEl });
       blockEl = null;
       blockSummaryEl = null;
     } else {
-      cards.forEach((el) => appendToHistory(el));
-      if (gen.text) appendToHistory(bubble);
+      placeAnswer(gen.text ? [...cards, bubble] : cards, { plain: false, blockEl });
       // The last step, left with its thinking only, reads "thinking" once.
       if (!gen.tools.length && gen.thinking) unwrapThinking(entry);
     }
@@ -468,6 +496,7 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
     }
     dirty.clear();
     rafPending = false;
+    onChange();
     return kept;
   }
 
@@ -545,6 +574,30 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
       return !!entry && (entry.text.contains(el) || !!entry.thinking?.contains(el));
     },
     reset,
+    // For a view that composes this one (the stage): the turn's model and
+    // block, a step's elements by index, and the steps back in
+    // chronological order after newestFirst.
+    current() { return { turn, blockEl }; },
+    step(i) {
+      const entry = turn && genEls.get(turn.gens[i]);
+      return entry ? { el: entry.el, summary: entry.summary, thinkingWrap: entry.thinkingWrap } : null;
+    },
+    chronological() {
+      if (!blockEl || !turn) return;
+      for (const gen of turn.gens) {
+        const el = genEls.get(gen)?.el;
+        if (el?.parentNode === blockEl) blockEl.appendChild(el);
+      }
+    },
+  };
+}
+
+// The turn view's answer placement: a plain answer's pieces in its block's
+// place (the block goes), else after the block in the history.
+function defaultPlaceAnswer(appendToHistory) {
+  return (pieces, { plain, blockEl }) => {
+    if (plain) blockEl.replaceWith(...pieces);
+    else pieces.forEach((el) => appendToHistory(el));
   };
 }
 
@@ -555,7 +608,9 @@ export function createTurnView({ historyEl, appendToHistory, isNearBottom, sawTe
 // parts; without them the row has the record's name, status and duration
 // only. +thumbs(images)+ draws the images, as the live row does.
 function reloadRowHtml(r, thumbs) {
-  const params = r.params ? `<span class="activity-params">${escapeHtml(r.params)}</span>` : "";
+  const shown = r.title || r.params;
+  const hover = r.title && r.params ? ` title="${escapeHtml(r.params)}"` : "";
+  const params = shown ? `<span class="activity-params"${hover}>${escapeHtml(shown)}</span>` : "";
   const duration = formatDuration(r.duration_ms);
   const full = String(r.output || "").replace(/^\[[^\]]*\]\s*/, "");
   const output = full

data/lib/samagotchi/web/qr.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rqrcode_core"
+
+module Samagotchi
+  module Web
+    # A QR code for the terminal: two module rows per line in half blocks
+    # (▀ ▄ █), black on white whatever the terminal's theme, so a phone's
+    # camera reads it on a dark terminal too.
+    module QR
+      # Modules of white around the code. The standard asks for 4; the
+      # white background makes 2 enough for a phone at a screen.
+      QUIET = 2
+      COLORS = "\e[30;107m"
+      RESET = "\e[0m"
+
+      module_function
+
+      # @return [Array<String>] the lines, colors included
+      def lines(text, quiet: QUIET, color: true)
+        rows = matrix(text, quiet: quiet)
+        rows << Array.new(rows.first.size, false) if rows.size.odd?
+        rows.each_slice(2).map do |top, bottom|
+          line = top.zip(bottom).map { |t, b| t ? (b ? "█" : "▀") : (b ? "▄" : " ") }.join
+          color ? "#{COLORS}#{line}#{RESET}" : line
+        end
+      end
+
+      # Dark modules as true, the quiet zone around them.
+      # Level L: the code is read off a screen, never damaged, and stays small.
+      def matrix(text, quiet: QUIET)
+        code = RQRCodeCore::QRCode.new(text, level: :l)
+        size = code.module_count
+        blank = Array.new(size + (2 * quiet), false)
+        body = Array.new(size) { |r| Array.new(quiet, false) + Array.new(size) { |c| code.checked?(r, c) } + Array.new(quiet, false) }
+        Array.new(quiet) { blank.dup } + body + Array.new(quiet) { blank.dup }
+      end
+    end
+  end
+end

data/lib/samagotchi/web/server.rb

@@ -8,7 +8,10 @@ require "uri"
 require "webrick"
 
 require_relative "app"
+require_relative "lan"
+require_relative "qr"
 require_relative "session_hub"
+require_relative "token"
 require_relative "../config"
 require_relative "../project_scope"
 require_relative "../log"
@@ -18,7 +21,9 @@ module Samagotchi
   module Web
     # Launcher for the single-port Web UI.
     #
-    # Binds strictly to 127.0.0.1 (localhost-only). Use `bin/chi web` to start.
+    # Binds to loopback (127.0.0.1 by default); with web.host lan (or a LAN
+    # address) also to that address, where requests need the access token.
+    # Use `bin/chi web` to start.
     class Server
       # WEBrick logs every exception out of its request loop as an ERROR with
       # a backtrace, among them a browser dropping a kept-alive connection
@@ -51,25 +56,44 @@ module Samagotchi
       # URL. If a chi web already runs on the port, print (and with --open,
       # open) its page for +dir+ and leave it be; else start one.
       # @param scope ["project", "all"] "all": the plain page, every session
+      # @param new_token [Boolean] replace the LAN access token first
+      #   (--new-token): a running server takes the new one at once
       # @return [Integer] the exit status
-      def self.launch(port: nil, host: nil, scope: "project", dir: Dir.pwd, open_browser: false, markdown: false, turn_view: true,
-                      annotate_presets: Config::BY_KEY["web.annotate_presets"].default)
-        host = resolve_host(host)
+      def self.launch(port: nil, host: nil, scope: "project", dir: Dir.pwd, open_browser: false, markdown: false, view: "turn",
+                      annotate_presets: Config::BY_KEY["web.annotate_presets"].default, new_token: false)
+        rotate_token if new_token
+        setting = host_setting(host)
+        lan = Lan.wanted?(setting) ? Lan.choose(setting) : nil
+        host = resolve_host(setting)
         port = resolve_port(port)
         url = scope_url(host, port, dir: dir, scope: scope)
         found = probe(host, port)
         case found
         when Hash
+          if lan && !found["lan"]
+            warn "chi web already runs on port #{port} without LAN access; stop it (Ctrl-C in its terminal, " \
+                 "or kill #{found["pid"]}) and run this again"
+            return 1
+          end
           puts "chi web already runs on port #{port} (pid #{found["pid"]}): #{url}"
+          puts running_lan_lines(found["lan"], port) if found["lan"]
+          puts lan_off_line(setting) if new_token && !found["lan"]
           open_url(url) if open_browser
           0
         when :other
           warn in_use_message(port)
           1
         else
-          start(port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, turn_view: turn_view,
-                annotate_presets: annotate_presets) ? 0 : 1
+          if new_token && !lan
+            puts lan_off_line(setting)
+            return 0
+          end
+          start(port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
+                annotate_presets: annotate_presets, lan: lan) ? 0 : 1
         end
+      rescue Lan::Error => e
+        warn "Error: #{e.message}"
+        1
       rescue Interrupt
         # Ctrl-C: the server has stopped (start's ensure); one line, and the
         # status a shell gives a command it interrupted.
@@ -79,22 +103,32 @@ module Samagotchi
 
       # @param hub [SessionHub, nil] the session projection the page streams
       #   from; built over the app's state dir unless given
+      # @param lan [Lan::Choice, nil] also listen on this LAN address, where
+      #   every request but this machine's needs the access token
+      # @param token_path [String] the LAN access token's file
       # @return [Boolean] false when the port was taken (said so on stderr)
       def self.start(port: nil, host: nil, url: nil, open_browser: false, state_dir: nil, manager: nil, markdown: false,
-                     turn_view: true, annotate_presets: Config::BY_KEY["web.annotate_presets"].default, hub: nil)
+                     view: "turn", annotate_presets: Config::BY_KEY["web.annotate_presets"].default, hub: nil, lan: nil,
+                     token_path: Token.path)
         port = resolve_port(port)
         host = resolve_host(host)
         url ||= "http://#{url_host(host)}:#{port}/"
 
         hub ||= SessionHub.new(state_dir: state_dir || Session.default_state_dir, manager: manager || SessionManager)
-        app = App.new(manager: manager, state_dir: state_dir, markdown: markdown, turn_view: turn_view,
-                      annotate_presets: annotate_presets, hub: hub)
+        if lan
+          Token.load_or_create(token_path)
+          lan_option = { ip: lan.ip, token: Token::Source.new(token_path) }
+        end
+        app = App.new(manager: manager, state_dir: state_dir, markdown: markdown, view: view,
+                      annotate_presets: annotate_presets, hub: hub, lan: lan_option)
         Samagotchi::Log.info(:web, "start", url: "http://#{host}:#{port}", version: Samagotchi::VERSION)
+        Samagotchi::Log.info(:web, "lan", ip: lan.ip, interface: lan.interface) if lan
         hub.start
         # Said once the port is bound: a second chi web racing for it gets
         # the in-use line instead.
         started = lambda do
           puts "Chi Web on #{url} (public: #{File.expand_path("public", __dir__)})"
+          puts lan_lines(ip: lan.ip, port: port, token: Token.read(token_path), others: lan.others, public: lan.public) if lan
           puts "Press Ctrl-C to stop."
           $stdout.flush # a log file isn't line-buffered
           if open_browser
@@ -110,20 +144,44 @@ module Samagotchi
         Rackup::Handler::WEBrick.run(app, Host: host, Port: port, AccessLog: [], Logger: Log.new($stderr, WEBrick::Log::WARN),
                                           StartCallback: started) do |server|
           app.server_running = -> { server.status == :Running }
+          listen_lan(server, lan, port) if lan
         end
         true
       rescue Errno::EADDRINUSE
         warn in_use_message(port)
         false
+      rescue LanListenError => e
+        warn "Error: can't listen on #{lan.ip}:#{port} (#{e.message}); did the address change? Run chi web again"
+        false
       ensure
         hub&.stop
         Samagotchi::Log.info(:web, "stop") if app
       end
 
+      class LanListenError < StandardError; end
+
+      # The LAN address's listener, next to the loopback one WEBrick made.
+      # The loopback socket is bound by now: on a failure it is closed
+      # here, as WEBrick never starts.
+      def self.listen_lan(server, lan, port)
+        server.listen(lan.ip, port)
+      rescue Errno::EADDRNOTAVAIL, Errno::EADDRINUSE, SocketError => e
+        server.listeners.each(&:close)
+        raise LanListenError, e.message
+      end
+
+      def self.host_setting(host)
+        (host || Samagotchi::Config.get("web.host")).to_s.strip
+      end
+
+      # The address the server binds: loopback. For web.host lan or a LAN
+      # address it is 127.0.0.1, and the LAN address is a second listener
+      # (start's lan:).
       def self.resolve_host(host)
-        host = (host || ENV.fetch("SAMAGOTCHI_WEB_HOST", DEFAULT_HOST)).to_s.strip
+        host = host_setting(host)
         host = DEFAULT_HOST if host.empty?
         return host if %w[127.0.0.1 ::1 localhost].include?(host)
+        return DEFAULT_HOST if Lan.wanted?(host)
 
         Samagotchi::Log.warn(:web, "bind_forced", echo: "Web server only binds to 127.0.0.1 (got #{host}); forcing 127.0.0.1", host: host.to_s)
         DEFAULT_HOST
@@ -162,12 +220,44 @@ module Samagotchi
         :other
       end
 
+      # What a phone needs: the LAN link with the token, the warnings, and
+      # the link's QR code (at a terminal only).
+      def self.lan_lines(ip:, port:, token:, others: [], public: false, qr: $stdout.tty?)
+        unless token
+          return ["LAN: http://#{ip}:#{port}/ (no access token: its file is gone; chi web --new-token makes one)"]
+        end
+
+        link = "http://#{ip}:#{port}/?token=#{token}"
+        lines = ["LAN: #{link}   ← anyone with this link can run commands as you",
+                 "Plain http: the link and your traffic can be read by anyone on this Wi-Fi."]
+        lines << "also: #{others.map(&:to_s).join(", ")}; set web.host to pick one" unless others.empty?
+        lines << "#{ip} isn't a private LAN address: anyone who can reach it can try to get in" if public
+        lines.concat(QR.lines(link)) if qr
+        lines
+      end
+
+      # A second chi web, when the running one has LAN access: the same
+      # lines, the token read from its file here.
+      def self.running_lan_lines(ip, port, token_path: Token.path)
+        lan_lines(ip: ip, port: port, token: Token.read(token_path))
+      end
+
+      def self.lan_off_line(setting)
+        "LAN access is off (web.host is #{setting.empty? ? DEFAULT_HOST : setting}): chi web --web-host lan uses the new token"
+      end
+
+      def self.rotate_token(path = Token.path)
+        Token.rotate(path)
+        Samagotchi::Log.info(:web, "token_rotated")
+        puts "New LAN access token: links and QR codes made with the old one stop working."
+      end
+
       def self.in_use_message(port)
         "Error: port #{port} is in use (an older chi web? restart it, or use --port)"
       end
 
       def self.resolve_port(port)
-        raw = port || ENV.fetch("SAMAGOTCHI_WEB_PORT", DEFAULT_PORT.to_s)
+        raw = port || Samagotchi::Config.get("web.port")
         parsed = raw.to_s.to_i
         parsed.positive? ? parsed : DEFAULT_PORT
       end

data/lib/samagotchi/web/token.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+
+require_relative "../session"
+
+module Samagotchi
+  module Web
+    # The access token of `chi web` on the LAN (web.host: lan): anyone
+    # who has it can run commands as you, so it lives in one file only you
+    # can read, $XDG_STATE_HOME/samagotchi/web-token (0600). It is made on
+    # the first LAN start and kept, so a phone's bookmark survives
+    # restarts; `chi web --new-token` replaces it. A loopback-only chi web
+    # never reads it.
+    module Token
+      FILE = "web-token"
+      # 32 random bytes: 43 URL-safe characters.
+      BYTES = 32
+
+      module_function
+
+      def path(env: ENV)
+        File.join(File.dirname(Session.default_state_dir(env: env)), FILE)
+      end
+
+      # @return [String, nil] the token in +path+, nil when there is none
+      def read(path = self.path)
+        token = File.read(path).strip
+        token.empty? ? nil : token
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # @return [String] the token in +path+, made (and saved) if there is none
+      def load_or_create(path = self.path)
+        read(path) || write(path, generate)
+      end
+
+      # A new token in +path+: every link made with the old one stops working.
+      # @return [String] the new token
+      def rotate(path = self.path)
+        write(path, generate)
+      end
+
+      def generate
+        SecureRandom.urlsafe_base64(BYTES)
+      end
+
+      # Written whole under a temporary name, then renamed over +path+: a
+      # reader never sees half a token. The file is 0600 from the start,
+      # its folder 0700 when this makes it.
+      def write(path, token)
+        dir = File.dirname(path)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        tmp = File.join(dir, ".#{File.basename(path)}.#{Process.pid}.#{SecureRandom.hex(4)}")
+        File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |io| io.write("#{token}\n") }
+        File.rename(tmp, path)
+        token
+      ensure
+        FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+      end
+
+      # The token a running server checks against: the file is re-read when
+      # its mtime changes (one stat per check), so `chi web --new-token`
+      # takes effect at once, without a restart.
+      class Source
+        attr_reader :path
+
+        def initialize(path = Token.path)
+          @path = path
+          @mutex = Mutex.new
+          @stamp = nil
+          @token = nil
+        end
+
+        # @return [String, nil] the current token; nil when the file is gone
+        #   (then nothing matches)
+        def current
+          stamp = begin
+            stat = File.stat(@path)
+            [stat.mtime, stat.size, stat.ino]
+          rescue Errno::ENOENT
+            nil
+          end
+          @mutex.synchronize do
+            unless stamp == @stamp
+              @token = stamp && Token.read(@path)
+              @stamp = stamp
+            end
+            @token
+          end
+        end
+      end
+    end
+  end
+end