@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/home/spend.ts

@@ -0,0 +1,194 @@
+// The home's spend line: today's and this month's review cost, summed from
+// two sources (src/home/ports.ts `SpendPort`):
+//
+//   the home     the app's detached review runs (`<state home>/review/
+//                detached`, the registry the review button starts in): each
+//                run that has ended and whose result says what it cost, in
+//                the day and month it ended
+//   auto-review  the daemon's recorded costs: its status snapshot's
+//                `today_spend_usd` and `month_spend_usd`, read from the
+//                daemon's own state on this machine's compose stack
+//
+// Today and this month are UTC days and months, the daemon's own (its
+// snapshot, `qcr spend`): the two halves are summed over one calendar.
+//
+// When either source cannot be read, the total is unknown, with why (invariant
+// 9): never a zero, and never the half that could be read passed off as the
+// whole. A source that cannot hold a cost is a known zero, as a missing auth
+// file is no login: a registry with no runs yet, a machine with no Docker, or
+// a stack that was never brought up (no state volume) recorded nothing.
+//
+// A run still going is not counted until its result says what it cost; a run
+// whose result names no cost has nothing to add.
+import { listRunViews } from "../reviewdetach.js";
+import type { ProcessRunner } from "../onboard/engine.js";
+import { daemonSnapshot } from "./daemonstatus.js";
+import { known, unknown, type Known, type SpendPort, type SpendTotals } from "./ports.js";
+import { parseRunStatus } from "./reviews.js";
+
+/** One cost, and when it was spent (ms since the epoch). */
+export interface Cost {
+  at: number;
+  usd: number;
+}
+
+/** What auto-review recorded for the UTC day and month of the reading. */
+export interface AutoSpend {
+  today: number;
+  month: number;
+}
+
+export interface SpendSources {
+  /** The home's finished runs' costs. */
+  home(): Promise<Known<readonly Cost[]>>;
+  /** Auto-review's recorded costs for the day and month of `now`. */
+  auto(now: number): Promise<Known<AutoSpend>>;
+}
+
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The UTC day (`YYYY-MM-DD`) and month (`YYYY-MM`) of `ms`. */
+export function utcPeriod(ms: number): { day: string; month: string } {
+  const iso = new Date(ms).toISOString();
+  return { day: iso.slice(0, 10), month: iso.slice(0, 7) };
+}
+
+async function safe<T>(read: () => Promise<Known<T>>): Promise<Known<T>> {
+  try {
+    return await read();
+  } catch (err) {
+    return unknown(message(err));
+  }
+}
+
+/** The spend port over its two sources: both read, or unknown. */
+export function spendPort(src: SpendSources, now: () => number): SpendPort {
+  return {
+    totals: async (): Promise<Known<SpendTotals>> => {
+      const at = now();
+      const [home, auto] = await Promise.all([safe(() => src.home()), safe(() => src.auto(at))]);
+      if (home.kind === "unknown") return unknown(`the home's reviews: ${home.why}`);
+      if (auto.kind === "unknown") return unknown(`auto-review's: ${auto.why}`);
+      const { day, month } = utcPeriod(at);
+      let today = auto.value.today;
+      let thisMonth = auto.value.month;
+      for (const c of home.value) {
+        if (!Number.isFinite(c.at) || !Number.isFinite(c.usd)) continue;
+        const p = utcPeriod(c.at);
+        if (p.month !== month) continue;
+        thisMonth += c.usd;
+        if (p.day === day) today += c.usd;
+      }
+      return known({ today, month: thisMonth });
+    },
+  };
+}
+
+// ---- the home's half: the detached registry -------------------------------
+
+/** Is the process with this pid alive? */
+const alive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The costs of every run in the registry at `registry` that has ended with
+ * a cost, at the time it ended. */
+export function registryCosts(
+  registry: string,
+  o: { now: () => number; alive?: (pid: number) => boolean } = { now: Date.now },
+): SpendSources["home"] {
+  return async () => {
+    let views;
+    try {
+      views = listRunViews(registry, { alive: o.alive ?? alive, now: o.now });
+    } catch (err) {
+      return unknown(`can't read the review runs in ${registry}: ${message(err)}`);
+    }
+    const out: Cost[] = [];
+    for (const v of views) {
+      const s = parseRunStatus(v.view, v.argv);
+      const usd = s?.result?.costUsd;
+      if (s === null || s.state === "running" || usd === null || usd === undefined) continue;
+      out.push({ at: s.endedAt ?? s.startedAt, usd });
+    }
+    return known(out);
+  };
+}
+
+// ---- auto-review's half: the daemon's status snapshot ----------------------
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
+const usd = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** What a status snapshot's text says auto-review spent, for the UTC day and
+ * month of `now`. Pure. A snapshot written on an earlier day is the daemon's
+ * last word: it has recorded nothing since (it writes one every heartbeat
+ * while it runs), so the days after it add nothing. */
+export function snapshotSpend(text: string, now: number): Known<AutoSpend> {
+  let s: unknown;
+  try {
+    s = JSON.parse(text);
+  } catch {
+    return unknown("its status.json is not readable JSON");
+  }
+  if (!isObj(s)) return unknown("its status.json is not an object");
+  const written = typeof s["written_at"] === "string" ? Date.parse(s["written_at"]) : NaN;
+  if (!Number.isFinite(written)) return unknown("its status has no time it was written");
+  const today = usd(s["today_spend_usd"]);
+  const month = usd(s["month_spend_usd"]);
+  if (month === null) return unknown("its status has no month's spend (an older daemon)");
+  if (today === null) return unknown("its status has no day's spend");
+  const at = utcPeriod(written);
+  const want = utcPeriod(now);
+  if (at.month !== want.month) return known({ today: 0, month: 0 });
+  return known({ today: at.day === want.day ? today : 0, month });
+}
+
+export interface ComposeSpendOptions {
+  /** The app's root: the compose project directory. */
+  root: string;
+  runner: ProcessRunner;
+}
+
+/** Auto-review's recorded costs on this machine's compose stack: read from
+ * the daemon's own status.json while it runs (src/home/daemonstatus.ts). A
+ * daemon that is off keeps its costs in its state volume, where the home
+ * cannot read them: unknown. */
+export function composeAutoSpend(o: ComposeSpendOptions): SpendSources["auto"] {
+  return async (now) => {
+    const s = await daemonSnapshot(o.runner, o.root);
+    if (s.kind === "text") return snapshotSpend(s.text, now);
+    if (s.kind === "none") return known({ today: 0, month: 0 });
+    if (s.kind === "off")
+      return unknown("auto-review is off, and its costs are read from it while it runs");
+    return unknown(s.why);
+  };
+}
+
+/** The spend port as the home's env shim builds it: the install's registry
+ * in the state home, and the compose stack at `root` (null: no stack, so
+ * auto-review recorded nothing here). */
+export function realSpendPort(o: {
+  registry: string;
+  root: string | null;
+  runner: ProcessRunner;
+  now?: () => number;
+}): SpendPort {
+  const now = o.now ?? Date.now;
+  return spendPort(
+    {
+      home: registryCosts(o.registry, { now }),
+      auto:
+        o.root === null
+          ? async () => known({ today: 0, month: 0 })
+          : composeAutoSpend({ root: o.root, runner: o.runner }),
+    },
+    now,
+  );
+}

package/src/home/switches.ts

@@ -0,0 +1,293 @@
+// The home's two switches, as the person meets them: the questions, in
+// order, and what each answer does. A key and the `home_auto_review` /
+// `home_memory` tools both start them (extensions/home.ts), and every
+// question is asked of the person in the home: a tool can start a switch but
+// can never answer for them, so the one confirm is always theirs.
+//
+// Auto-review on:   machine checks → where it runs → the memory offer (when
+//                   memory is off) → one confirm → the steps
+//                   (src/home/switchon.ts): it comes up in dry-run
+// Go live:          the proof round (one real pull request reviewed in
+//                   dry-run, its review shown) → one more confirm → the
+//                   go-live step. From switch-off's question while in
+//                   dry-run, or Advanced's "Dry-run or live"
+// Auto-review off:  a warning naming the running round → stop at once, data
+//                   kept, memory untouched
+// Memory:           its RAM cost → on or off, auto-review untouched
+import type {
+  AutoReviewControl,
+  AutoReviewStatus,
+  HomeAdapters,
+  Known,
+  MemoryControl,
+  MemoryState,
+  Slot,
+} from "./ports.js";
+import { known } from "./ports.js";
+import { runningWarning } from "./autoreview.js";
+
+/** How a switch asks the person: pi's own select. */
+export interface Ask {
+  select(title: string, options: string[]): Promise<string | undefined>;
+}
+
+/** The answers the person picks from, each its own words. */
+export const CHOICE = {
+  cancel: "Cancel",
+  turnOn: "Turn on auto-review",
+  here: "This machine",
+  elsewhere: "Another server, over ssh (advanced)",
+  notNow: "Not now",
+  memoryOn: "Turn on memory",
+  keepOn: "Keep it on",
+  switchOff: "Switch it off",
+  goLive: "Go live",
+  proofRound: "Review it now, in dry-run",
+} as const;
+
+/** What the switches need of the home's model. */
+export interface SwitchHost {
+  autoReview(): Slot<AutoReviewStatus>;
+  memory(): Slot<MemoryState>;
+  /** The trigger label, when known. */
+  trigger(): string | null;
+  repo(): string | null;
+  /** The selected pull request: the proof round's, when one is needed. */
+  selected(): number | null;
+  say(text: string, kind?: "info" | "ok" | "warn"): void;
+  /** Show this in the slot until released, whatever a refresh reads. */
+  hold(slot: "autoReview", v: Known<AutoReviewStatus>): void;
+  hold(slot: "memory", v: Known<MemoryState>): void;
+  release(slot: "autoReview" | "memory"): void;
+  refresh(): Promise<string>;
+}
+
+const NEEDS_PERSON =
+  "this switch asks the person in the home, and no one can answer here; nothing changed";
+
+/** What auto-review picks up: the trigger label (unknown when it can't be
+ * read) or a review request. */
+export function pickUpPhrase(trigger: string | null): string {
+  return trigger === null
+    ? "pull requests with the trigger label (which one is unknown) or a review request"
+    : `pull requests labelled "${trigger}" or with a review request`;
+}
+
+/** The same, as a sentence. */
+export function pickUpLine(trigger: string | null): string {
+  return `It picks up ${pickUpPhrase(trigger)}.`;
+}
+
+/** Is auto-review, as last read, something to switch off? */
+function isOn(s: Slot<AutoReviewStatus>): boolean {
+  return s.kind === "known" && s.value.state !== "off";
+}
+
+export async function switchAutoReview(
+  host: SwitchHost,
+  adapters: HomeAdapters,
+  ask: Ask | undefined,
+): Promise<string> {
+  const control = adapters.autoReview.control;
+  if (!control) return "auto-review can't be switched from this home";
+  if (!ask) return NEEDS_PERSON;
+  return isOn(host.autoReview())
+    ? switchOff(host, control, ask)
+    : switchOn(host, adapters, control, ask);
+}
+
+async function switchOn(
+  host: SwitchHost,
+  adapters: HomeAdapters,
+  control: AutoReviewControl,
+  ask: Ask,
+): Promise<string> {
+  // 1. the machine checks, before anything is asked
+  host.say("Checking this machine: Docker, disk, ports…");
+  const checks = await control.machineChecks();
+  if (!checks.ok) {
+    host.say(`Auto-review can't run on this machine yet: ${checks.detail}`, "warn");
+    return `machine checks failed: ${checks.detail}`;
+  }
+  // 2. where it runs
+  const where = await ask.select("Where should auto-review run?", [
+    `${CHOICE.here} — ${checks.detail}`,
+    CHOICE.elsewhere,
+  ]);
+  if (where === undefined) return cancelled(host);
+  if (where === CHOICE.elsewhere) {
+    host.say(
+      'Auto-review on another server is set up in the advanced steps: Advanced (alt+x), "Auto-review on another server, over ssh". Nothing changed here.',
+    );
+    return "another server: the advanced steps set it up";
+  }
+  // 3. the memory offer, when memory is off
+  let memory: boolean | null = null;
+  const mem = host.memory();
+  const memoryControl = adapters.memory.control;
+  if (memoryControl && mem.kind === "known" && mem.value === "off") {
+    const m = await ask.select(
+      `Turn on memory too? Reviews learn this repository. It uses ${memoryControl.ramCost()}.`,
+      [CHOICE.notNow, CHOICE.memoryOn],
+    );
+    if (m === undefined) return cancelled(host);
+    memory = m === CHOICE.memoryOn;
+  }
+  // 4. the one confirm: it comes up in dry-run unless the config is live
+  const dry = await control.dryRun();
+  const repo = host.repo() ?? "your repository";
+  const picks = pickUpPhrase(host.trigger());
+  const posture =
+    dry.kind === "unknown"
+      ? `Auto-review reviews ${picks} in ${repo}. Whether it posts to GitHub is unknown: ${dry.why}.`
+      : !dry.value
+        ? `Auto-review reviews ${picks} in ${repo}, and posts each review to GitHub.`
+        : `Auto-review starts in dry-run: it reviews ${picks} in ${repo}, and records what it would post instead of posting it. Going live is its own step later: one review you read, then one more confirm.`;
+  const go = await ask.select(
+    `${posture} It keeps running, across reboots, until you switch it off.`,
+    [CHOICE.cancel, CHOICE.turnOn],
+  );
+  if (go !== CHOICE.turnOn) return cancelled(host);
+  // the steps
+  host.hold("autoReview", known({ state: "starting" }));
+  if (memory === true) host.hold("memory", known("starting"));
+  host.say("Starting auto-review…");
+  let outcome;
+  try {
+    outcome = await control.switchOn({ memory, confirmed: true }, (l) => host.say(l));
+  } catch (err) {
+    outcome = { ok: false, live: null, detail: String(err), steps: [] as string[] };
+  } finally {
+    host.release("autoReview");
+    host.release("memory");
+  }
+  await host.refresh();
+  if (outcome.ok) host.say(`${outcome.detail} ${pickUpLine(host.trigger())}`, "ok");
+  else host.say(`Auto-review did not start: ${outcome.detail}`, "warn");
+  return outcome.ok
+    ? `${outcome.detail}\n${outcome.steps.join("\n")}`
+    : `auto-review did not start: ${outcome.detail}\n${outcome.steps.join("\n")}`;
+}
+
+async function switchOff(host: SwitchHost, control: AutoReviewControl, ask: Ask): Promise<string> {
+  const a = host.autoReview();
+  const dry = a.kind === "known" && a.value.state === "on-dry";
+  const warning = runningWarning(await control.running());
+  const answer = await ask.select(
+    `Switch auto-review off? ${warning} All its data is kept, so switching it on again is quick.`,
+    [CHOICE.keepOn, ...(dry ? [CHOICE.goLive] : []), CHOICE.switchOff],
+  );
+  if (answer === CHOICE.goLive) return goLive(host, control, ask);
+  if (answer !== CHOICE.switchOff) return cancelled(host);
+  const r = await control.switchOff();
+  await host.refresh();
+  if (!r.ok) {
+    host.say(`Couldn't switch auto-review off: ${r.detail}`, "warn");
+    return `couldn't switch auto-review off: ${r.detail}`;
+  }
+  host.say("Auto-review is off. Its data is kept, and memory is as it was.", "ok");
+  return `auto-review is off (${r.detail}). ${warning}`;
+}
+
+/** What going live needs of the home. */
+export interface GoLiveHost {
+  say(text: string, kind?: "info" | "ok" | "warn"): void;
+  refresh(): Promise<string>;
+  /** The selected pull request, for a proof round. */
+  selected(): number | null;
+}
+
+/**
+ * Go live, from dry-run: a proof round first, then one more confirm, then
+ * the go-live step (which re-checks the proof against the daemon's own
+ * state). The proof round is the wizard's: the daemon reviews one real pull
+ * request now, in dry-run, and the person reads what it would have posted.
+ * A proof already recorded stands; the go-live step judges it.
+ */
+export async function goLive(
+  host: GoLiveHost,
+  control: AutoReviewControl,
+  ask: Ask,
+): Promise<string> {
+  let proven = (await control.proof())?.pr ?? null;
+  if (proven === null) {
+    const pr = host.selected();
+    if (pr === null) {
+      const said =
+        "Going live needs a proof round first: one pull request reviewed in dry-run, which you read before anything posts. Select a pull request, then choose Go live again.";
+      host.say(said, "warn");
+      return "not live: no proof round yet, and no pull request is selected";
+    }
+    const run = await ask.select(
+      `Going live needs a proof round first: auto-review reviews #${pr} now, in dry-run, and shows you what it would post. Nothing is posted.`,
+      [CHOICE.cancel, CHOICE.proofRound],
+    );
+    if (run !== CHOICE.proofRound) return cancelled(host);
+    host.say(`Reviewing #${pr} in dry-run: the proof round…`);
+    let r;
+    try {
+      r = await control.proofRound(pr, (l) => host.say(l));
+    } catch (err) {
+      r = { ok: false as const, detail: String(err) };
+    }
+    if (!r.ok) {
+      host.say(`The proof round did not finish: ${r.detail}`, "warn");
+      return `not live: the proof round did not finish: ${r.detail}`;
+    }
+    host.say(r.detail, "ok");
+    proven = pr;
+  }
+  const go = await ask.select(
+    `Go live? You have read the review of #${proven}. Auto-review then posts each review to GitHub under your name.`,
+    [CHOICE.cancel, CHOICE.goLive],
+  );
+  if (go !== CHOICE.goLive) return cancelled(host);
+  const r = await control.goLive({ confirmed: true });
+  await host.refresh();
+  host.say(r.ok ? r.detail : `Not live: ${r.detail}`, r.ok ? "ok" : "warn");
+  return r.ok ? r.detail : `not live: ${r.detail}`;
+}
+
+function cancelled(host: Pick<SwitchHost, "say">): string {
+  host.say("Nothing changed.");
+  return "cancelled: nothing changed";
+}
+
+export async function switchMemory(
+  host: SwitchHost,
+  adapters: HomeAdapters,
+  ask: Ask | undefined,
+): Promise<string> {
+  const control: MemoryControl | undefined = adapters.memory.control;
+  if (!control) return "memory can't be switched from this home";
+  if (!ask) return NEEDS_PERSON;
+  const s = host.memory();
+  if (s.kind === "known" && s.value !== "off") {
+    const a = await ask.select("Switch memory off? What it learned is kept.", [
+      CHOICE.keepOn,
+      CHOICE.switchOff,
+    ]);
+    if (a !== CHOICE.switchOff) return cancelled(host);
+    const r = await control.switchOff();
+    await host.refresh();
+    host.say(r.ok ? r.detail : `Couldn't switch memory off: ${r.detail}`, r.ok ? "ok" : "warn");
+    return r.ok ? "memory is off" : `couldn't switch memory off: ${r.detail}`;
+  }
+  const a = await ask.select(
+    `Turn on memory? Reviews remember this repository's conventions and past findings. It uses ${control.ramCost()}.`,
+    [CHOICE.notNow, CHOICE.memoryOn],
+  );
+  if (a !== CHOICE.memoryOn) return cancelled(host);
+  host.hold("memory", known("starting"));
+  let r;
+  try {
+    r = await control.switchOn((l) => host.say(l));
+  } catch (err) {
+    r = { ok: false as const, detail: String(err) };
+  } finally {
+    host.release("memory");
+  }
+  await host.refresh();
+  host.say(r.ok ? r.detail : `Memory did not start: ${r.detail}`, r.ok ? "ok" : "warn");
+  return r.ok ? "memory is on" : `memory did not start: ${r.detail}`;
+}