@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/tui/actions.ts

@@ -0,0 +1,484 @@
+// Companion → TUI action channel.
+//
+// The companion (a local pi in a docker container, no VM credentials, no
+// keyboard) drives the operator's TUI by dropping request files into
+// `<alerts_dir>/tui-actions/<iso-ts>-<slug>.json`. The TUI sweeps the
+// directory on its poll cadence, validates each request against a strict
+// schema, and executes it against the `TuiDriver` the wiring supplies.
+//
+// Actions execute instantly — there is no confirm gate, by design: everything
+// a request can do is something the operator's own keyboard can do on the TUI
+// (tab switches, selections, filters, quick-messages, the deploy-tab buttons),
+// the request files are on the operator's own machine, and the executed trace
+// lands on the notice line, so a surprising action is visible the moment it
+// happens. Do not add a confirmation step here.
+//
+// One memory verb, and only one (`memory_pin`, the companion boundary): the
+// companion may pin or unpin an EXISTING entry, and the TUI performs it
+// through its one `MemoryStore` — the same copy-then-stub move as the memory
+// tab's `p`, against the entry as a fresh read finds it, and the result file
+// carries the store's answer. Nothing else about memory rides this channel:
+// the companion writes its own entries with its own keys, and no other
+// memory write may be requested through a file.
+//
+// The companion's tier (rule 8: everything the owner can). `operator_command` carries one command of that tier — steer,
+// follow-up, abort-round, takeover, debug-round, release, message (with
+// `may_post`), drain and the rest of the owner's column — and the TUI forwards
+// it down the operator route the viewer's own input line uses
+// (src/tui/livecontrol.ts). The command is validated here against the
+// daemon's own schema (`validateCommand`, as the operator channel would) and
+// authorised against the companion's tier (`authorizeCompanionCommand`), so a
+// malformed or out-of-tier verb is refused before anything is written. The
+// companion's `commands/` directory (`/qcr-state/commands/`, where the seeded
+// EOD sweep writes its receipt) is swept the same way: each file is one bare
+// command, read by `parseCompanionCommand` and forwarded once.
+//
+// Idempotency (archive before execute): a request is archived to `.done/`
+// BEFORE it is executed — a crash mid-execute must not re-run it on the next
+// sweep (msg_session would double-send, deploy_tab would
+// double-arm). A crash after archive but before execute
+// loses one request; the companion sees the missing result and re-requests —
+// the safer failure. Results are written to `<name>.result.json` beside the
+// request; malformed/unknown requests produce a refused result, never a
+// crash.
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { authorizeCompanionCommand, validateCommand, type Command } from "../commands.js";
+import type { BoardFilter } from "./filters.js";
+import { STATE_GLYPHS } from "./model.js";
+import { isValidSessionName } from "./msg.js";
+import { TABS, isTab, type Tab } from "./tabs.js";
+
+// ---- the executor seam ------------------------------------------------------
+
+/** What the TUI exposes to the action channel — supplied at wiring time
+ * (see docs/tui-actions-wiring.md for the ~30-line production impl). */
+export interface TuiDriver {
+  switchTab(tab: Tab): void;
+  selectPr(pr: number): void;
+  metricsWindow(w: ActionMetricsWindow): void;
+  metricsPr(pr: number): void;
+  /** The digest tab, paged to that day. */
+  digestDay(date: string): void;
+  /** The memory tab: `tag` filters the timeline, `day` jumps to that day's entries. */
+  memoryView(opts: { day?: string; tag?: string }): void;
+  /** Pin or unpin one EXISTING memory entry through the TUI's ONE
+   * `MemoryStore` — the same verb as the memory tab's `p`: the entry MOVES
+   * into `preferences/pinned/` (the round's guaranteed head) or back out.
+   * `entry` is the TUI's id (`reviewer:experiences/x.md`) or the entry's
+   * `viking://user/<user>/memories/…` URI. Resolves with the store's message;
+   * REJECTS on a refusal, so the result file says it failed. Pin and unpin
+   * ONLY — the driver has no other memory method. */
+  memoryPin(entry: string, pin: boolean): Promise<string>;
+  setBoardFilter(f: BoardFilter | null): void;
+  setMemoryFilter(tag: string | null): void;
+  /** A quick-message to `session`. Resolves with the sender's label — delivered, queued behind a busy
+   * session, or unconfirmed; REJECTS only on a definite non-delivery, so a
+   * failed result file never asks for a re-send of a message still queued. */
+  msgSession(session: string, text: string): Promise<string>;
+  deployTab(action: DeployTabAction): void;
+  /** Forward one validated command of the companion's tier down the operator
+   * route. Resolves with the daemon's answer (queued, handled, or unconfirmed);
+   * REJECTS when the daemon refused it or the write failed. */
+  operatorCommand(command: Command): Promise<string>;
+}
+
+// ---- the schema -------------------------------------------------------------
+
+/** The metrics windows a `metrics` request may name. */
+export const METRICS_WINDOWS = ["7d", "30d", "all"] as const;
+export type ActionMetricsWindow = (typeof METRICS_WINDOWS)[number];
+/** The deploy tab's buttons a `deploy_tab` request may press. */
+export const DEPLOY_TAB_ACTIONS = ["deploy", "stop", "start", "abort"] as const;
+export type DeployTabAction = (typeof DEPLOY_TAB_ACTIONS)[number];
+
+export type TuiAction =
+  | { verb: "switch_tab"; tab: Tab }
+  | { verb: "select_pr"; pr: number }
+  | { verb: "metrics"; window: ActionMetricsWindow }
+  | { verb: "metrics"; pr: number }
+  | { verb: "digest_day"; date: string }
+  | { verb: "memory_view"; day?: string; tag?: string }
+  | { verb: "board_filter"; filter: BoardFilter | null }
+  | { verb: "memory_filter"; tag: string | null }
+  | { verb: "memory_pin"; entry: string; pin: boolean }
+  | { verb: "msg_session"; session: string; text: string }
+  | { verb: "deploy_tab"; action: DeployTabAction }
+  | { verb: "operator_command"; command: Command };
+
+export const ACTION_TEXT_MAX = 2000;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** The only params `memory_pin` takes. Anything else is REFUSED, not
+ * ignored: a request that reads like an edit (`text`, `op`, `content`) must
+ * fail loudly rather than quietly pin (pin and unpin only). */
+const MEMORY_PIN_PARAMS = new Set(["entry", "pin"]);
+/** The daemon's lifecycle state strings — the only values a board state
+ * filter can name (a typo would silently filter the board to nothing). */
+const STATES = new Set(Object.keys(STATE_GLYPHS));
+
+/** Positive-integer PR number; digit strings are coerced (the companion is an
+ * LLM — the same courtesy verdicts.ts extends to pr/round_no) and then held
+ * to the same bar, so `"0"` or an overflowing string is refused like `0`. */
+function prNumber(v: unknown): number | undefined {
+  const n = typeof v === "string" && /^\d+$/.test(v) ? Number(v) : v;
+  return typeof n === "number" && Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+
+function isOneOf<T extends string>(values: readonly T[], v: unknown): v is T {
+  return typeof v === "string" && (values as readonly string[]).includes(v);
+}
+
+function boundedText(v: unknown): string | undefined {
+  if (typeof v !== "string") return undefined;
+  const t = v.trim();
+  if (t.length === 0 || t.length > ACTION_TEXT_MAX) return undefined;
+  return t;
+}
+
+function tagText(v: unknown): string | undefined {
+  if (typeof v !== "string") return undefined;
+  const t = v.trim().replace(/^#+/, "");
+  if (t.length === 0 || t.length > 100) return undefined;
+  return t;
+}
+
+/** Strict parse of one request file's text. Unknown verbs, malformed params,
+ * oversized text → a refusal (recorded in the result file), never a throw. */
+export function parseTuiAction(
+  text: string,
+): { ok: true; action: TuiAction } | { ok: false; error: string } {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "not JSON" };
+  }
+  if (typeof raw !== "object" || raw === null) return { ok: false, error: "not an object" };
+  const r = raw as Record<string, unknown>;
+  const verb = r["verb"];
+  if (typeof verb !== "string") return { ok: false, error: "missing verb" };
+  const pRaw = r["params"] ?? {};
+  if (typeof pRaw !== "object" || pRaw === null || Array.isArray(pRaw))
+    return { ok: false, error: "params must be an object" };
+  const p = pRaw as Record<string, unknown>;
+
+  switch (verb) {
+    case "switch_tab": {
+      const tab = p["tab"];
+      // The eight surfaces, by the one name each has everywhere (src/tui/tabs.ts).
+      if (!isTab(tab)) return { ok: false, error: `switch_tab needs tab: ${TABS.join("|")}` };
+      return { ok: true, action: { verb, tab } };
+    }
+    case "select_pr": {
+      const pr = prNumber(p["pr"]);
+      if (pr === undefined) return { ok: false, error: "select_pr needs a positive integer pr" };
+      return { ok: true, action: { verb, pr } };
+    }
+    case "metrics": {
+      const hasWindow = p["window"] !== undefined;
+      const hasPr = p["pr"] !== undefined;
+      if (hasWindow === hasPr)
+        return { ok: false, error: "metrics needs exactly one of window|pr" };
+      if (hasWindow) {
+        const w = p["window"];
+        if (!isOneOf(METRICS_WINDOWS, w))
+          return { ok: false, error: `metrics window must be ${METRICS_WINDOWS.join("|")}` };
+        return { ok: true, action: { verb, window: w } };
+      }
+      const pr = prNumber(p["pr"]);
+      if (pr === undefined) return { ok: false, error: "metrics pr must be a positive integer" };
+      return { ok: true, action: { verb, pr } };
+    }
+    case "digest_day": {
+      const date = p["date"];
+      if (typeof date !== "string" || !DATE_RE.test(date))
+        return { ok: false, error: "digest_day needs date: YYYY-MM-DD" };
+      return { ok: true, action: { verb, date } };
+    }
+    case "memory_view": {
+      const out: { verb: "memory_view"; day?: string; tag?: string } = { verb };
+      if (p["day"] !== undefined) {
+        if (typeof p["day"] !== "string" || !DATE_RE.test(p["day"]))
+          return { ok: false, error: "memory_view day must be YYYY-MM-DD" };
+        out.day = p["day"];
+      }
+      if (p["tag"] !== undefined) {
+        const tag = tagText(p["tag"]);
+        if (tag === undefined)
+          return { ok: false, error: "memory_view tag must be a short non-empty string" };
+        out.tag = tag;
+      }
+      return { ok: true, action: out };
+    }
+    case "board_filter": {
+      if (p["clear"] === true) return { ok: true, action: { verb, filter: null } };
+      const filter: BoardFilter = {};
+      if (p["author"] !== undefined) {
+        if (
+          typeof p["author"] !== "string" ||
+          p["author"].trim().length === 0 ||
+          p["author"].length > 100
+        )
+          return { ok: false, error: "board_filter author must be a short non-empty string" };
+        filter.author = p["author"].trim();
+      }
+      if (p["state"] !== undefined) {
+        if (typeof p["state"] !== "string" || !STATES.has(p["state"]))
+          return { ok: false, error: `board_filter state must be one of ${[...STATES].join("|")}` };
+        filter.state = p["state"];
+      }
+      if (filter.author === undefined && filter.state === undefined)
+        return { ok: false, error: "board_filter needs author and/or state, or clear: true" };
+      return { ok: true, action: { verb, filter } };
+    }
+    case "memory_filter": {
+      if (p["clear"] === true) return { ok: true, action: { verb, tag: null } };
+      const tag = tagText(p["tag"]);
+      if (tag === undefined)
+        return { ok: false, error: "memory_filter needs tag (or clear: true)" };
+      return { ok: true, action: { verb, tag } };
+    }
+    case "memory_pin": {
+      const extra = Object.keys(p).filter((k) => !MEMORY_PIN_PARAMS.has(k));
+      if (extra.length > 0)
+        return {
+          ok: false,
+          error: `memory_pin takes only entry and pin — it pins or unpins an existing entry and writes nothing else (refused: ${extra.join(", ")})`,
+        };
+      const entry = p["entry"];
+      if (
+        typeof entry !== "string" ||
+        entry.trim() === "" ||
+        entry.length > 300 ||
+        /\s|\.\./.test(entry.trim())
+      )
+        return {
+          ok: false,
+          error:
+            "memory_pin needs entry: the TUI's id (reviewer:experiences/<file>.md) or its viking:// URI",
+        };
+      if (p["pin"] !== true && p["pin"] !== false)
+        return { ok: false, error: "memory_pin needs pin: true (pin) or false (unpin)" };
+      return { ok: true, action: { verb, entry: entry.trim(), pin: p["pin"] } };
+    }
+    case "msg_session": {
+      const session = p["session"];
+      // The overseer is retired (rule 8: the companion injects into no session
+      // of its own); a PR's session or the main one is all that is left to name.
+      if (typeof session !== "string" || session === "overseer" || !isValidSessionName(session))
+        return { ok: false, error: "msg_session session must be pr-<n> or main" };
+      const text = boundedText(p["text"]);
+      if (text === undefined)
+        return { ok: false, error: `msg_session text must be 1..${ACTION_TEXT_MAX} chars` };
+      return { ok: true, action: { verb, session, text } };
+    }
+    case "deploy_tab": {
+      const action = p["action"];
+      if (!isOneOf(DEPLOY_TAB_ACTIONS, action))
+        return { ok: false, error: `deploy_tab needs action: ${DEPLOY_TAB_ACTIONS.join("|")}` };
+      return { ok: true, action: { verb, action } };
+    }
+    case "operator_command":
+      return companionCommand(p["command"]);
+    default:
+      return { ok: false, error: `unknown verb '${verb}'` };
+  }
+}
+
+/** One command of the companion's tier: valid by the daemon's own schema as
+ * the operator channel validates it, and within the companion's tier. */
+function companionCommand(
+  raw: unknown,
+): { ok: true; action: TuiAction } | { ok: false; error: string } {
+  const valid = validateCommand(raw, { issuer: "operator" });
+  if (!valid.ok) return { ok: false, error: `operator_command: ${valid.reason}` };
+  const tier = authorizeCompanionCommand(valid.command);
+  if (!tier.ok) return { ok: false, error: `operator_command: ${tier.reason}` };
+  return { ok: true, action: { verb: "operator_command", command: valid.command } };
+}
+
+/** One file of the companion's `commands/` directory: a bare command (the
+ * shape the seeded EOD sweep writes), forwarded as `operator_command`. */
+export function parseCompanionCommand(
+  text: string,
+): { ok: true; action: TuiAction } | { ok: false; error: string } {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "not JSON" };
+  }
+  return companionCommand(raw);
+}
+
+// ---- execution --------------------------------------------------------------
+
+/** Run one parsed action against the driver; returns the one-line human trace
+ * for the notice line. The driver's methods are the whole side-effect surface.
+ * The verbs that wait on an answer (`memory_pin` — pin/unpin of an existing
+ * entry — plus `msg_session` and `operator_command`) return a Promise that
+ * resolves once the store or the daemon has answered; every other verb is
+ * synchronous. */
+export function executeTuiAction(a: TuiAction, driver: TuiDriver): string | Promise<string> {
+  switch (a.verb) {
+    case "switch_tab":
+      driver.switchTab(a.tab);
+      return `companion ▸ tab → ${a.tab}`;
+    case "select_pr":
+      driver.selectPr(a.pr);
+      return `companion ▸ board → #${a.pr}`;
+    case "metrics":
+      if ("window" in a) {
+        driver.metricsWindow(a.window);
+        return `companion ▸ metrics window → ${a.window}`;
+      }
+      driver.metricsPr(a.pr);
+      return `companion ▸ metrics → #${a.pr} timeline`;
+    case "digest_day":
+      driver.digestDay(a.date);
+      return `companion ▸ digest → ${a.date}`;
+    case "memory_view": {
+      const opts: { day?: string; tag?: string } = {};
+      if (a.day !== undefined) opts.day = a.day;
+      if (a.tag !== undefined) opts.tag = a.tag;
+      driver.memoryView(opts);
+      const bits = [a.day, a.tag ? `#${a.tag}` : undefined].filter((b) => b !== undefined);
+      return `companion ▸ memory view${bits.length > 0 ? ` · ${bits.join(" · ")}` : ""}`;
+    }
+    case "board_filter":
+      driver.setBoardFilter(a.filter);
+      return a.filter === null
+        ? "companion ▸ board filter cleared"
+        : `companion ▸ board filter → ${[a.filter.author ? `author:${a.filter.author}` : undefined, a.filter.state ? `state:${a.filter.state}` : undefined].filter(Boolean).join(" · ")}`;
+    case "memory_filter":
+      driver.setMemoryFilter(a.tag);
+      return a.tag === null
+        ? "companion ▸ memory filter cleared"
+        : `companion ▸ memory filter → #${a.tag}`;
+    case "memory_pin":
+      return driver
+        .memoryPin(a.entry, a.pin)
+        .then((message) => `companion ▸ memory ${a.pin ? "pin" : "unpin"} → ${message}`);
+    case "msg_session":
+      return driver
+        .msgSession(a.session, a.text)
+        .then((label) => `companion ▸ msg ${a.session} (${a.text.length} chars) → ${label}`);
+    case "deploy_tab":
+      driver.deployTab(a.action);
+      return `companion ▸ deploy tab → ${a.action}`;
+    case "operator_command":
+      return driver.operatorCommand(a.command).then((label) => {
+        // A takeover or debug round the companion asked for opens its pane in
+        // the owner's TUI. The command is already delivered: a TUI too busy to
+        // switch now leaves the PR where the owner can open it.
+        const pr = (a.command as { pr?: unknown }).pr;
+        if (
+          (a.command.command === "takeover" || a.command.command === "debug-round") &&
+          typeof pr === "number"
+        ) {
+          try {
+            driver.selectPr(pr);
+          } catch {
+            /* delivered either way */
+          }
+        }
+        return `companion ▸ ${label}`;
+      });
+  }
+}
+
+// ---- the sweep --------------------------------------------------------------
+
+export interface ProcessedAction {
+  file: string;
+  ok: boolean;
+  /** Refusal reason, or the executed trace. */
+  message: string;
+  /** Set iff executed — the notice-line text. */
+  trace?: string;
+}
+
+/** Result files older than this are swept; `.done/` keeps the newest N. */
+const RESULT_TTL_MS = 24 * 3600 * 1000;
+const DONE_KEEP = 200;
+
+/** One sweep of `<alerts_dir>/tui-actions/`. Serialized by the caller's poll
+ * cadence (busy flag at the wiring site — see docs/tui-actions-wiring.md).
+ * Archive-BEFORE-execute per the module header; a driver throw records a
+ * failed result and the sweep moves on. */
+export async function processTuiActions(
+  dir: string,
+  driver: TuiDriver,
+  parse: (text: string) => ReturnType<typeof parseTuiAction> = parseTuiAction,
+): Promise<ProcessedAction[]> {
+  const out: ProcessedAction[] = [];
+  if (!existsSync(dir)) return out;
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".json") && !f.endsWith(".result.json"))
+    .sort();
+  const doneDir = join(dir, ".done");
+  if (files.length > 0) mkdirSync(doneDir, { recursive: true });
+  for (const file of files) {
+    let text: string;
+    try {
+      text = readFileSync(join(dir, file), "utf8");
+      renameSync(join(dir, file), join(doneDir, file));
+    } catch {
+      continue; // vanished mid-sweep (companion rewrote it?) — next sweep sees the survivor
+    }
+    let ok = false;
+    let message: string;
+    let trace: string | undefined;
+    const parsed = parse(text);
+    if (!parsed.ok) {
+      message = `refused: ${parsed.error}`;
+    } else {
+      try {
+        trace = await executeTuiAction(parsed.action, driver);
+        ok = true;
+        message = trace;
+      } catch (err) {
+        message = `execute failed: ${String(err instanceof Error ? err.message : err)}`;
+      }
+    }
+    try {
+      writeFileSync(
+        join(dir, `${file.replace(/\.json$/, "")}.result.json`),
+        JSON.stringify({ ok, message, file }, null, 2) + "\n",
+      );
+    } catch {
+      /* a result we cannot write must not kill the sweep */
+    }
+    out.push(trace !== undefined ? { file, ok, message, trace } : { file, ok, message });
+  }
+  cleanup(dir, doneDir);
+  return out;
+}
+
+/** Bounded housekeeping: results past their TTL, `.done/` past its cap. */
+function cleanup(dir: string, doneDir: string): void {
+  try {
+    const now = Date.now();
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".result.json")) continue;
+      if (now - statSync(join(dir, f)).mtimeMs > RESULT_TTL_MS)
+        rmSync(join(dir, f), { force: true });
+    }
+    if (!existsSync(doneDir)) return;
+    const done = readdirSync(doneDir).sort(); // iso-ts names: oldest first
+    for (const f of done.slice(0, Math.max(0, done.length - DONE_KEEP)))
+      rmSync(join(doneDir, f), { force: true });
+  } catch {
+    /* housekeeping is best-effort */
+  }
+}