@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/tui/viewerinput.ts

@@ -0,0 +1,173 @@
+// The transcript viewer's input line: what the operator types under a
+// worker-hosted PR's transcript (the PR-pane rule in docs/tui.md). The viewer is
+// not a pi surface, so it has an input line of its own — the one exception to
+// "never add a TUI-side input box", and only on the worker, answer and idle
+// panes (`paneSurface`); a debug or takeover pane is a pi terminal and never
+// gets one.
+//
+// Pure on purpose: `viewerInputKey` takes the state and one stdin chunk and
+// answers with the next state and what to do (send a control, ask to confirm an
+// abort, say something), so every key is testable without a screen. Painting is
+// `viewerInputRow`, and the App wires both to the operator control route
+// (`livecontrol.ts`).
+//
+//   ⏎        steers the running session while a round runs; on an idle PR it
+//            sends a `message` (which carries `may_post` when the toggle is on)
+//   Alt-⏎    queues a follow-up behind the running turn (a round must be running)
+//   Alt-p    toggles `may_post` for the next message; shown, and reset on send
+//   Ctrl-c   asks to abort the round; `y` confirms, any other key cancels
+//   Ctrl-u   clears the draft; Esc clears it too, or leaves an empty line alone
+//
+// `[ ] < >` step the viewer's streams and rounds only while the draft is empty:
+// once there is text they are text, so a message can contain brackets.
+import { CONTROL_TEXT_MAX } from "../commands.js";
+import { displayWidth, sanitizeText, truncate } from "./paint.js";
+import { FG, RESET } from "./theme.js";
+
+export interface ViewerInput {
+  text: string;
+  /** The next message may post (the Alt-p toggle). */
+  mayPost: boolean;
+  /** The abort prompt is up: the next key answers it. */
+  confirmAbort: boolean;
+}
+
+export const newViewerInput = (): ViewerInput => ({
+  text: "",
+  mayPost: false,
+  confirmAbort: false,
+});
+
+/** What the line asks the App to do. */
+export type ViewerInputEffect =
+  | { t: "none" }
+  | { t: "send"; kind: "steer" | "follow-up"; text: string }
+  | { t: "send"; kind: "message"; text: string; may_post: boolean }
+  | { t: "abort" }
+  | { t: "notice"; text: string };
+
+export interface ViewerInputResult {
+  state: ViewerInput;
+  effect: ViewerInputEffect;
+  /** The key was the line's. False leaves it to the viewer's own keys. */
+  handled: boolean;
+}
+
+/** The viewer's navigation keys: text once there is a draft. */
+const NAV_KEYS = new Set(["[", "]", "<", ">"]);
+
+/**
+ * One stdin chunk against the line. `running` is whether a round (or an answer)
+ * is running for the PR, which decides what ⏎ is: a steer, or a message.
+ */
+export function viewerInputKey(
+  state: ViewerInput,
+  raw: string,
+  running: boolean,
+): ViewerInputResult {
+  const done = (
+    next: Partial<ViewerInput>,
+    effect: ViewerInputEffect = { t: "none" },
+  ): ViewerInputResult => ({ state: { ...state, ...next }, effect, handled: true });
+
+  // The abort prompt owns the next key: `y` confirms, anything else is "no".
+  if (state.confirmAbort)
+    return raw === "y" || raw === "Y"
+      ? done({ confirmAbort: false }, { t: "abort" })
+      : done({ confirmAbort: false });
+
+  if (raw === "\x03") {
+    if (!running)
+      return done({}, { t: "notice", text: "no round is running — there is nothing to abort" });
+    return done({ confirmAbort: true });
+  }
+  if (raw === "\x1bp") return done({ mayPost: !state.mayPost });
+  if (raw === "\x15" || (raw === "\x1b" && state.text !== "")) return done({ text: "" });
+  if (raw === "\r" || raw === "\n") {
+    const text = state.text.trim();
+    if (text === "") return done({});
+    // The toggle is for a message; it resets on every send, so it never rides
+    // along to the next one.
+    return done(
+      { text: "", mayPost: false },
+      running
+        ? { t: "send", kind: "steer", text }
+        : { t: "send", kind: "message", text, may_post: state.mayPost },
+    );
+  }
+  if (raw === "\x1b\r" || raw === "\x1b\n") {
+    const text = state.text.trim();
+    if (!running)
+      return done(
+        {},
+        { t: "notice", text: "no round is running — ⏎ sends a message to the PR instead" },
+      );
+    if (text === "") return done({});
+    return done({ text: "", mayPost: false }, { t: "send", kind: "follow-up", text });
+  }
+  if (raw === "\x7f" || raw === "\b") return done({ text: [...state.text].slice(0, -1).join("") });
+  if (state.text === "" && NAV_KEYS.has(raw))
+    return { state, effect: { t: "none" }, handled: false };
+  // Text: one key or a paste. Newlines become spaces (the line is one line);
+  // every other control byte, and any escape sequence, is not text.
+  if (raw !== "" && !raw.includes("\x1b") && raw >= " ") {
+    const add = sanitizeText(raw).replace(/\n/g, " ");
+    return done({ text: (state.text + add).slice(0, CONTROL_TEXT_MAX) });
+  }
+  return { state, effect: { t: "none" }, handled: false };
+}
+
+/** What the board paints for the line. */
+export interface ViewerInputView extends ViewerInput {
+  /** A round is running: ⏎ steers (else it sends a message). */
+  running: boolean;
+  /** The pane holds the keyboard. */
+  focused: boolean;
+  pr: number;
+}
+
+/** The toggle as the line shows it: always visible, so a posting message is
+ * never a surprise. */
+export const mayPostLabel = (on: boolean): string => (on ? "post: ON" : "post: off");
+
+/** `text` cut from the left to fit `width` cells, keeping its end (the cursor). */
+function tail(text: string, width: number): string {
+  let out = "";
+  let w = 0;
+  for (const ch of [...text].reverse()) {
+    const cw = displayWidth(ch);
+    if (w + cw > width) break;
+    out = ch + out;
+    w += cw;
+  }
+  return out;
+}
+
+/**
+ * The line as one painted row of `width` cells. Focused it is the draft with a
+ * cursor and, on the right, the may-post toggle; unfocused it says how to reach
+ * it. While the abort prompt is up it is the prompt.
+ */
+export function viewerInputRow(view: ViewerInputView, width: number): string {
+  const w = Math.max(1, width);
+  if (view.confirmAbort)
+    return `${FG.anomaly}${truncate(`abort the running round of #${view.pr}? y = abort · any other key cancels`, w)}${RESET}`;
+  const verb = view.running ? "steer" : "message";
+  if (!view.focused)
+    return `${FG.dim}${truncate(`⏎ focus this pane, then type to ${verb} #${view.pr}`, w)}${RESET}`;
+  const toggle = `[Alt-p ${mayPostLabel(view.mayPost)}]`;
+  const right = view.mayPost ? `${FG.anomaly}${toggle}${RESET}` : `${FG.dim}${toggle}${RESET}`;
+  const rightW = displayWidth(toggle);
+  const prompt = `${view.running ? "steer" : "msg"} › `;
+  const room = w - displayWidth(prompt) - rightW - 2;
+  // Too narrow for the toggle: the end of the line, cursor included, and no more.
+  if (room < 4) return tail(`${prompt}${view.text}▌`, w);
+  const hint = (view.running ? "⏎ steer · Alt-⏎ queue · Ctrl-c abort" : "⏎ send a message").slice(
+    0,
+    room,
+  );
+  const shown = view.text === "" ? hint : `${tail(view.text, room - 1)}▌`;
+  const draft = view.text === "" ? `${FG.dim}${hint}${RESET}` : shown;
+  const gap = " ".repeat(Math.max(1, room - displayWidth(shown) + 1));
+  return `${FG.accent}${prompt}${RESET}${draft}${gap}${right}`;
+}

package/src/updatenotice.ts

@@ -0,0 +1,178 @@
+// The "a newer qcr exists" notice. At most once a day an installed qcr asks
+// the npm registry for its package's latest version, in a detached child that
+// nobody waits for, and keeps the answer under the state home. Any later run
+// reads that file and, when the registry had a newer version, says so on
+// stderr after its own output. Never in CI, never on a machine-readable run
+// (`--json`, no terminal), never from the release image or a checkout, and
+// never blocking: a slow or failing registry costs nothing but a missed notice.
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** How often the registry is asked: once a day. */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60_000;
+/** How long the detached check waits for the registry. */
+export const UPDATE_FETCH_TIMEOUT_MS = 10_000;
+/** The file under the state home that keeps the last answer. */
+export const UPDATE_CACHE_FILE = "update-check.json";
+export const REGISTRY = "https://registry.npmjs.org";
+
+export interface UpdateCache {
+  /** When the registry was last asked (ms since the epoch). */
+  checked_at: number;
+  /** The registry's latest version then; null when it could not be read. */
+  latest: string | null;
+}
+
+export function updateCachePath(stateHome: string): string {
+  return join(stateHome, UPDATE_CACHE_FILE);
+}
+
+export function readUpdateCache(path: string): UpdateCache | null {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const at = raw["checked_at"];
+    const latest = raw["latest"];
+    if (typeof at !== "number" || !Number.isFinite(at)) return null;
+    return { checked_at: at, latest: typeof latest === "string" ? latest : null };
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCache(path: string, c: UpdateCache): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(c) + "\n");
+  renameSync(tmp, path);
+}
+
+/** `x.y.z` → numbers; null for anything else (a prerelease included: the
+ * notice only ever points at a release). */
+function release(v: string): [number, number, number] | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Is `latest` a release newer than `current`? */
+export function isNewer(current: string, latest: string): boolean {
+  const a = release(current);
+  const b = release(latest);
+  if (a === null || b === null) return false;
+  for (let i = 0; i < 3; i++) if (b[i]! !== a[i]!) return b[i]! > a[i]!;
+  return false;
+}
+
+/** Is a CI environment's flag set? (`CI=false` and `CI=0` are not CI.) */
+export function inCi(env: Readonly<Record<string, string | undefined>>): boolean {
+  const ci = (env["CI"] ?? "").trim().toLowerCase();
+  return (ci !== "" && ci !== "false" && ci !== "0") || env["GITHUB_ACTIONS"] === "true";
+}
+
+export interface NoticeInput {
+  current: string;
+  cachePath: string;
+  env: Readonly<Record<string, string | undefined>>;
+  /** stderr is a terminal: somebody reads the notice. */
+  tty: boolean;
+  /** The run's output is machine-readable (`--json`). */
+  json: boolean;
+  /** Installed by a package manager (src/npmverbs.ts `detectInstall`). */
+  installed: boolean;
+  now: number;
+  /** Start the registry check without waiting for it. */
+  refresh: () => void;
+}
+
+/** The notice line to print, or null; starts the day's registry check when
+ * it is due. Reads one small file and never waits on the network. */
+export function updateNotice(o: NoticeInput): string | null {
+  if (!o.installed || !o.tty || o.json || inCi(o.env)) return null;
+  if ((o.env["QCR_NO_UPDATE_NOTICE"] ?? "").trim() !== "") return null;
+  const cache = readUpdateCache(o.cachePath);
+  if (cache === null || o.now - cache.checked_at >= UPDATE_CHECK_INTERVAL_MS) {
+    // Stamp the check first, so runs in the next minutes do not start another.
+    try {
+      writeUpdateCache(o.cachePath, { checked_at: o.now, latest: cache?.latest ?? null });
+      o.refresh();
+    } catch {
+      // a state home that cannot be written means no check today, and no harm
+    }
+  }
+  if (cache?.latest && isNewer(o.current, cache.latest))
+    return `qcr ${cache.latest} is available (this is ${o.current}): run \`qcr update\`. (QCR_NO_UPDATE_NOTICE=1 silences this.)`;
+  return null;
+}
+
+/** The registry URL of `pkg`'s latest version (a scoped name keeps its `@`
+ * and escapes its `/`). */
+export function latestUrl(pkg: string, registry: string = REGISTRY): string {
+  return `${registry.replace(/\/+$/, "")}/${pkg.replace("/", "%2f")}/latest`;
+}
+
+/** Ask the registry for `pkg`'s latest version and keep the answer at
+ * `cachePath`. A failure keeps the previous answer, stamped now: the next try
+ * is tomorrow. */
+export async function refreshUpdateCache(o: {
+  cachePath: string;
+  pkg: string;
+  fetchFn: typeof fetch;
+  now: () => number;
+  timeoutMs?: number;
+}): Promise<UpdateCache> {
+  const prev = readUpdateCache(o.cachePath);
+  let latest: string | null = prev?.latest ?? null;
+  try {
+    const res = await o.fetchFn(latestUrl(o.pkg), {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(o.timeoutMs ?? UPDATE_FETCH_TIMEOUT_MS),
+    });
+    if (res.ok) {
+      const body = (await res.json()) as { version?: unknown };
+      if (typeof body.version === "string" && release(body.version) !== null) latest = body.version;
+    }
+  } catch {
+    // offline, slow or refused: the previous answer stands
+  }
+  const c: UpdateCache = { checked_at: o.now(), latest };
+  try {
+    writeUpdateCache(o.cachePath, c);
+  } catch {
+    // nowhere to keep it: the check simply happens again
+  }
+  return c;
+}
+
+const REFRESH_FLAG = "--refresh-update-cache";
+
+/** Start the registry check in a detached child of this very module, which
+ * outlives this run and is never waited for. */
+export function spawnRefresh(cachePath: string, pkg: string): void {
+  const child = spawn(
+    process.execPath,
+    [fileURLToPath(import.meta.url), REFRESH_FLAG, cachePath, pkg],
+    { detached: true, stdio: "ignore" },
+  );
+  child.on("error", () => {});
+  child.unref();
+}
+
+function isThisModule(entry: string | undefined): boolean {
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+// The detached child: `node updatenotice.js --refresh-update-cache <cache> <pkg>`.
+if (isThisModule(process.argv[1]) && process.argv[2] === REFRESH_FLAG) {
+  const [cachePath, pkg] = process.argv.slice(3);
+  if (cachePath && pkg)
+    void refreshUpdateCache({ cachePath, pkg, fetchFn: fetch, now: Date.now }).then(
+      () => process.exit(0),
+      () => process.exit(0),
+    );
+}