@quickchatai/quickreview 0.0.0-stage → 1.2.0

package/src/tui/issuesink.ts

@@ -0,0 +1,238 @@
+// The pluggable issue sink: where auto-filed defect flags land.
+//
+// One seam in the MemoryStore style: every method is total (a broken backend
+// is a refusal-as-answer, never a throw — the TUI poll loop must survive any
+// sink), and the kinds are a closed set chosen by `[sink] kind` in
+// config.toml:
+//
+//   * `wayfinder` — the auto-filer in src/tui/autofile.ts: tickets into a
+//     local filesystem tracker, with the effort/parent carried by config.
+//   * `github`    — defects filed as issues on the reviewed repo. The TUI has
+//     no MutationGate and must never grow one, so this sink executes nothing
+//     itself: it writes a `file-issue` command file into the daemon's
+//     operator command channel, commands/operator/ (the same ssh idiom as src/tui/unwedge.ts)
+//     and reads back the daemon's verdict. The daemon's whitelist re-validates
+//     the payload, and `fileIssue` (src/improvements.ts) enforces the day cap,
+//     the jaccard title dedup and the bot label behind the one gate — in
+//     dry-run the gate writes an intent instead of creating anything.
+//   * `none`      — clean off. `SinkReport` is always `{ filed: [] }`.
+//
+// Dedup discipline is shared: every sink checks the entry's own `filed=` tag
+// first and stamps it back through the injected MemoryStore only after the
+// filing exists on the other side, so a crash between the two costs a
+// re-check, never a lost filing. The backstop differs per sink — wayfinder
+// scans ticket `Memory-key:` lines, github leans on the daemon's title dedup
+// (the re-filed duplicate is refused, not doubled).
+import { validateCommand } from "../commands.js";
+import type { Config, IssueSinkKind, TuiConfig } from "../config.js";
+import { sinkTicketsEffort } from "../config.js";
+import {
+  autofileDefects,
+  filedAs,
+  entryProse,
+  MEMORY_KEY_LINE,
+  memoryKey,
+  stampFiled,
+  type TrackerPaths,
+} from "./autofile.js";
+import type { MemoryEntry, MemoryStore } from "./memory.js";
+import { resolveLayout } from "./layout.js";
+import type { SshRunner } from "./remote.js";
+import { commandFileName, commandResultArgv, commandWriteArgv, resultReason } from "./unwedge.js";
+
+/** One filing the sink performed: `id` is the human handle ("FT-0123",
+ * "#456", "dry-run intent"), `key` the entry's stable dedup key. */
+export interface SinkFiled {
+  id: string;
+  key: string;
+}
+
+/** A sink's total answer. `refused` carries the FIRST refusal reason of the
+ * batch (a cap, a dead channel) — filings before it still count. */
+export interface SinkReport {
+  filed: SinkFiled[];
+  refused?: string;
+}
+
+/** The seam. `file` takes the CURRENT defect set (already filtered to
+ * defect-tagged entries by the caller) and files whatever is not yet filed. */
+export interface IssueSink {
+  readonly kind: IssueSinkKind;
+  file(defects: MemoryEntry[], nowIso: string): Promise<SinkReport>;
+}
+
+/** `none`: auto-filing is off, and off is inert — no reads, no writes. */
+export class NoneIssueSink implements IssueSink {
+  readonly kind = "none" as const;
+  file(): Promise<SinkReport> {
+    return Promise.resolve({ filed: [] });
+  }
+}
+
+/** The filesystem wayfinder tracker — a thin adapter over the auto-filer,
+ * so the ticket format, the id claim, the crash-safe order and the
+ * quiet-skip on an unavailable tracker are exactly autofile.ts's. */
+export class WayfinderIssueSink implements IssueSink {
+  readonly kind = "wayfinder" as const;
+
+  constructor(
+    private readonly paths: TrackerPaths,
+    private readonly store?: MemoryStore,
+  ) {}
+
+  async file(defects: MemoryEntry[], nowIso: string): Promise<SinkReport> {
+    const filed = await autofileDefects(this.paths, defects, nowIso, this.store);
+    return { filed: filed.map((f) => ({ id: f.ticketId, key: f.key })) };
+  }
+}
+
+/** The prose of an entry — `#tags`, `k=v` tokens (the memory vocabulary's
+ * one grammar) and `[[links]]` are not title material, wherever they sit. */
+export function issueTitleFor(e: MemoryEntry): string {
+  const prose = entryProse(e.text);
+  const head = (prose || "memory defect").slice(0, 90).trim();
+  return `Auto-filed defect: ${head}`;
+}
+
+/** The issue body mirrors the wayfinder ticket: provenance line, the
+ * `Memory-key:` backstop (searchable if the `filed=` stamp is ever refused),
+ * then the flagged entry verbatim. */
+export function issueBodyFor(e: MemoryEntry): string {
+  return `The reviewer's overseer flagged an operational defect in the review system (memory entry ${e.id} @ ${e.ts}, auto-filed by the TUI). Diagnose, fix, and close — or close as duplicate/stale with a note.
+
+${MEMORY_KEY_LINE} ${memoryKey(e)}
+
+## Flagged entry
+
+${e.text}
+`;
+}
+
+type FileOneOutcome = { ok: true; id: string; stamp: string } | { ok: false; reason: string };
+
+/**
+ * GitHub issues via the daemon's command channel. Where this executes is the
+ * point: the filer runs PC-side in the TUI, which holds no GitHub credential
+ * and no gate — so the sink's only write is a command file, validated here
+ * against the daemon's own `validateCommand` before it is ever sent, and
+ * re-validated, tier-checked, capped and gated daemon-side. The TUI inherits
+ * the `local`-dir belt exactly like unwedge does, instead of bypassing it.
+ */
+export class GithubIssueSink implements IssueSink {
+  readonly kind = "github" as const;
+  private seq = 0;
+
+  constructor(
+    private readonly cfg: TuiConfig,
+    private readonly ssh: SshRunner,
+    private readonly store?: MemoryStore,
+    private readonly now: () => Date = () => new Date(),
+    private readonly sleep: (ms: number) => Promise<void> = (ms) =>
+      new Promise((r) => setTimeout(r, ms)),
+  ) {}
+
+  async file(defects: MemoryEntry[], _nowIso: string): Promise<SinkReport> {
+    const filed: SinkFiled[] = [];
+    let refused: string | undefined;
+    for (const e of defects) {
+      if (filedAs(e) !== undefined) continue;
+      let outcome: FileOneOutcome;
+      try {
+        outcome = await this.fileOne(e);
+      } catch (err) {
+        outcome = { ok: false, reason: `issue channel failed: ${(err as Error).message}` };
+      }
+      if (!outcome.ok) {
+        refused = refused ?? outcome.reason;
+        continue;
+      }
+      filed.push({ id: outcome.id, key: memoryKey(e) });
+      // Best-effort stamp, after the daemon's receipt — same crash-safe order
+      // as the wayfinder filer. A refused stamp costs a re-check next tick,
+      // where the daemon's title dedup refuses the duplicate.
+      if (this.store) await stampFiled(this.store, e, outcome.stamp);
+    }
+    return refused === undefined ? { filed } : { filed, refused };
+  }
+
+  private async fileOne(e: MemoryEntry): Promise<FileOneOutcome> {
+    const payload = { command: "file-issue", title: issueTitleFor(e), body: issueBodyFor(e) };
+    // The daemon's own schema, checked before anything leaves this process:
+    // this module can never produce a command the whitelist would not accept.
+    const valid = validateCommand(payload);
+    if (!valid.ok) return { ok: false, reason: `refused locally: ${valid.reason}` };
+    // Resolve the container layout first, as every other command sender does:
+    // the write path is built from the root it holds.
+    await resolveLayout(this.cfg, this.ssh);
+    const name = commandFileName(this.now(), this.seq++);
+    const write = await this.ssh(this.cfg.ssh_host, commandWriteArgv(this.cfg, name), {
+      stdin: `${JSON.stringify(payload, null, 2)}\n`,
+    });
+    if (!write.ok)
+      return {
+        ok: false,
+        reason: `command write failed (${resultReason(write.stderr, `exit ${write.code}`).slice(0, 200)})`,
+      };
+    // Read the daemon's verdict, not the write's: a cap or dedup refusal is a
+    // real answer, and only a receipt may stamp the entry as filed.
+    const deadline = this.now().getTime() + this.cfg.msg_timeout_s * 1000;
+    while (this.now().getTime() < deadline) {
+      await this.sleep(2000);
+      const probe = await this.ssh(this.cfg.ssh_host, commandResultArgv(this.cfg, name));
+      if (!probe.ok) continue;
+      const body = probe.stdout.trim();
+      if (body === "pending" || body === "") continue;
+      let result: { ok?: unknown; reason?: unknown; issue?: unknown; duplicate_of?: unknown };
+      try {
+        result = JSON.parse(body) as typeof result;
+      } catch {
+        // A concurrent reader can see the daemon still writing its receipt.
+        continue;
+      }
+      if (typeof result !== "object" || result === null || Array.isArray(result)) continue;
+      if (
+        result.ok !== true &&
+        typeof result.duplicate_of === "number" &&
+        Number.isInteger(result.duplicate_of) &&
+        result.duplicate_of > 0
+      )
+        return { ok: true, id: `#${result.duplicate_of}`, stamp: `#${result.duplicate_of}` };
+      if (result.ok !== true)
+        return { ok: false, reason: resultReason(result.reason, "refused, no reason given") };
+      const issue = typeof result.issue === "number" && result.issue > 0 ? result.issue : null;
+      // Dry-run leaves no issue number, but the intent is on record (the
+      // gate's dryrun/ file plus the day-cap row) — so the entry is stamped
+      // anyway: re-filing the same defect every refresh would burn the cap on
+      // rehearsal duplicates.
+      return issue !== null
+        ? { ok: true, id: `#${issue}`, stamp: `#${issue}` }
+        : { ok: true, id: "dry-run intent", stamp: "dry-run" };
+    }
+    return { ok: false, reason: "no daemon result before the deadline" };
+  }
+}
+
+/** The configured sink. The wayfinder guard is a belt — parseConfig already
+ * refuses a wayfinder sink missing its root/effort/parent. */
+export function buildIssueSink(full: Config, ssh: SshRunner, store?: MemoryStore): IssueSink {
+  switch (full.sink.kind) {
+    case "github":
+      return new GithubIssueSink(full.tui, ssh, store);
+    case "wayfinder": {
+      const { root, effort, parent } = full.sink;
+      if (!root || !effort || !parent) return new NoneIssueSink();
+      return new WayfinderIssueSink({ root, effort, parent }, store);
+    }
+    case "none":
+      return new NoneIssueSink();
+  }
+}
+
+/** Where the TUI's read-only ticket projection reads from, or undefined when
+ * no effort is configured. The root falls back to the companion's tracker
+ * mount. */
+export function ticketProjection(full: Config): { root: string; effort: string } | undefined {
+  const effort = sinkTicketsEffort(full);
+  const root = full.sink.root || full.companion.tracker_dir;
+  return effort && root ? { root, effort } : undefined;
+}

package/src/tui/jsonfile.ts

@@ -0,0 +1,42 @@
+// A JSON state file the TUI keeps on the operator's machine: read with its
+// three answers kept apart, written whole. Shared by the stores whose history
+// a merge-then-save could otherwise destroy (the survey candidates, the change
+// register); each keeps its own schema check and its own recovery policy.
+import { readTextIfPresent, writeAtomic } from "../channelfs.js";
+
+export function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * `absent` (no file yet) and `unreadable` (a file that exists and could not be
+ * read or parsed — a torn write, EACCES, EISDIR) are different facts: the
+ * first means there is no history, the second that there is one nobody can
+ * see. `parsed` is JSON, not yet the caller's schema.
+ */
+export type JsonFileRead =
+  | { state: "parsed"; value: unknown }
+  | { state: "absent" }
+  | { state: "unreadable"; reason: string };
+
+export function readJsonFile(path: string): JsonFileRead {
+  let raw: string | null;
+  try {
+    raw = readTextIfPresent(path);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    return { state: "unreadable", reason: code ?? errText(err) };
+  }
+  if (raw === null) return { state: "absent" };
+  try {
+    return { state: "parsed", value: JSON.parse(raw) as unknown };
+  } catch (err) {
+    return { state: "unreadable", reason: errText(err) };
+  }
+}
+
+/** `value` as pretty JSON, written beside `path` and renamed over it, so a
+ * reader never sees half a file. */
+export function writeJsonFile(path: string, value: unknown): void {
+  writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/src/tui/keys.ts

@@ -0,0 +1,109 @@
+// Board-mode key decoding. Only the tab / help / msg screens parse keys; a
+// focused embedded terminal (the board's pi pane, the companion column) is a
+// raw passthrough — nothing here runs for it except the Ctrl-q release.
+//
+// `o`, `M` and `w` are deliberately not decoded: the TUI never attaches to a
+// VM session and has no full-screen detail page (it would duplicate the side
+// pane). All three letters are plain text to the companion column.
+import { tabDigit, tabForDigit, type Tab } from "./tabs.js";
+
+export type BoardKey =
+  | { kind: "up"; arrow?: boolean; wheel?: boolean }
+  | { kind: "down"; arrow?: boolean; wheel?: boolean }
+  | { kind: "enter" }
+  | { kind: "attach" }
+  | { kind: "alt-enter" }
+  | { kind: "escape" }
+  | { kind: "backspace" }
+  | { kind: "tab"; tab: Tab }
+  | { kind: "quit" }
+  | { kind: "help" }
+  | { kind: "message" }
+  | { kind: "unwedge" }
+  | { kind: "github" }
+  | { kind: "events" }
+  | { kind: "refresh" }
+  | { kind: "reconnect" }
+  | { kind: "older" }
+  | { kind: "newer" }
+  | { kind: "char"; ch: string }
+  | { kind: "other"; raw: Buffer };
+
+/** The board verbs typed as one printable — ONE table, read both ways:
+ * `decodeKey` maps the letter to the verb, `keyChar` folds the verb back to
+ * the letter. (`q` also answers to Ctrl-c; `j`/`k` move and are not here.) */
+const PRINTABLE_VERBS = [
+  ["a", "attach"], // ⏎'s twin: focus the board's embedded pi pane
+  ["q", "quit"],
+  ["?", "help"],
+  ["m", "message"],
+  ["u", "unwedge"],
+  ["g", "github"],
+  ["e", "events"],
+  ["r", "refresh"],
+  ["s", "reconnect"],
+  ["[", "older"],
+  ["]", "newer"],
+] as const;
+
+type PrintableVerb = (typeof PRINTABLE_VERBS)[number][1];
+
+const VERB_OF = new Map<string, PrintableVerb>(PRINTABLE_VERBS.map(([ch, kind]) => [ch, kind]));
+const CHAR_OF = new Map<string, string>(PRINTABLE_VERBS.map(([ch, kind]) => [kind, ch]));
+
+/** The control keys both decoders share: ⏎, Alt-⏎, Esc, Backspace. */
+function decodeControl(s: string): BoardKey | undefined {
+  if (s === "\r" || s === "\n") return { kind: "enter" };
+  if (s === "\x1b\r" || s === "\x1b\n") return { kind: "alt-enter" };
+  if (s === "\x1b") return { kind: "escape" };
+  if (s === "\x7f" || s === "\b") return { kind: "backspace" };
+  return undefined;
+}
+
+/** Typed text: one or more printables, no escape. */
+function isText(s: string): boolean {
+  return s.length > 0 && !s.includes("\x1b") && s >= " ";
+}
+
+/** One stdin chunk → one key. Chunks are decoded whole: interactive typing
+ * delivers one key per chunk; paste lands as a single `char` run. */
+export function decodeKey(buf: Buffer): BoardKey {
+  const s = buf.toString("utf8");
+  if (s === "\x1b[A") return { kind: "up", arrow: true };
+  if (s === "\x1b[B") return { kind: "down", arrow: true };
+  const control = decodeControl(s);
+  if (control) return control;
+  if (s === "j") return { kind: "down" };
+  if (s === "k") return { kind: "up" };
+  const tab = tabForDigit(s);
+  if (tab !== undefined) return { kind: "tab", tab };
+  if (s === "\x03") return { kind: "quit" };
+  const verb = VERB_OF.get(s);
+  if (verb !== undefined) return { kind: verb };
+  if (isText(s)) return { kind: "char", ch: s };
+  return { kind: "other", raw: buf };
+}
+
+/**
+ * The printable a decoded key was typed as, or undefined for keys that were
+ * never a single printable (arrows, ⏎, Esc, chords). The metrics tab's `# <pr>`
+ * box reads digits through this — `1`…`8` decode as tab switches before any
+ * tab handler sees them — and the feedback tab's armed revert reads its `y`.
+ */
+export function keyChar(key: BoardKey): string | undefined {
+  if (key.kind === "char") return key.ch;
+  if (key.kind === "tab") return tabDigit(key.tab);
+  return CHAR_OF.get(key.kind);
+}
+
+/** Msg-box decoding reuses decodeKey but must keep letters as text — the
+ * caller routes on mode: in the input box only enter/alt-enter/escape/
+ * backspace act; everything printable is text. */
+export function decodeInputKey(buf: Buffer): BoardKey {
+  const s = buf.toString("utf8");
+  const control = decodeControl(s);
+  if (control) return control;
+  if (s === "\x03") return { kind: "quit" };
+  if (isText(s)) return { kind: "char", ch: s };
+  return { kind: "other", raw: buf };
+}

package/src/tui/layout.ts

@@ -0,0 +1,108 @@
+// The container-layout resolver: where the app root lives inside the daemon
+// container, for every TUI remote path (inject files, the digest, evidence,
+// the operator command channel, the deploy marker, the viewer's reads).
+//
+// The container says which layout it is: the release image carries the label
+// `qcr.layout=release` (app root /opt/qcr); the legacy container carries no
+// label (app root /opt/quickreview/sandbox). The cutover recreates the container
+// mid-connection, so the answer is tied to the container's ID: the probe reads
+// both in one `docker inspect`, and the root is re-resolved whenever the ID
+// changes. The owner therefore edits no TUI key at the cutover, and a drain
+// sent a moment before the recreate still lands in the legacy container's
+// directory.
+//
+// An explicit `[tui] remote_sandbox_root` wins and is never probed. Until a
+// probe has answered, the root is the legacy one: that is the only layout a
+// container can have had before this resolver existed, and a probe that fails
+// (ssh down, no container) never overwrites an answer already held.
+import type { TuiConfig } from "../config.js";
+import type { SshRunner } from "./remote.js";
+
+export const LEGACY_LAYOUT_ROOT = "/opt/quickreview/sandbox";
+export const RELEASE_LAYOUT_ROOT = "/opt/qcr";
+export const LAYOUT_LABEL = "qcr.layout";
+
+export type ContainerLayout = "legacy" | "release";
+
+export interface LayoutProbe {
+  /** The container's ID: a recreate changes it. */
+  id: string;
+  layout: ContainerLayout;
+}
+
+/** The root a layout keeps the app at. */
+export function rootForLayout(layout: ContainerLayout): string {
+  return layout === "release" ? RELEASE_LAYOUT_ROOT : LEGACY_LAYOUT_ROOT;
+}
+
+/** `docker inspect` of the daemon container: its ID and its layout label, one
+ * line. An absent label prints as the empty string. */
+export function layoutProbeArgv(cfg: TuiConfig): string[] {
+  return [
+    ...(cfg.sudo_docker ? ["sudo"] : []),
+    "docker",
+    "inspect",
+    "-f",
+    `{{.Id}} {{index .Config.Labels "${LAYOUT_LABEL}"}}`,
+    cfg.container,
+  ];
+}
+
+/** Total: anything that is not `<hex id> [label]` is no answer. Only the label
+ * `release` means release; any other value, or none, is the legacy layout. */
+export function parseLayoutProbe(stdout: string): LayoutProbe | undefined {
+  const m = /^([0-9a-f]{12,64})(?:[ \t]+(\S+))?\s*$/.exec(stdout.trim());
+  if (!m) return undefined;
+  return { id: m[1]!, layout: m[2] === "release" ? "release" : "legacy" };
+}
+
+interface Held {
+  id: string;
+  root: string;
+}
+
+/** One answer per connection (transport, host, container), shared by every
+ * copy of the config object. */
+const held = new Map<string, Held>();
+
+const keyOf = (cfg: TuiConfig): string => `${cfg.target}|${cfg.ssh_host}|${cfg.container}`;
+
+/** Forget what was resolved (tests; a new connection). */
+export function resetLayoutCache(): void {
+  held.clear();
+}
+
+/** The app root inside the container, for building a remote path. Pure: it
+ * reads what `resolveLayout` last held. */
+export function remoteSandboxRoot(
+  cfg: Pick<TuiConfig, "remote_sandbox_root"> & Partial<TuiConfig>,
+): string {
+  if (cfg.remote_sandbox_root) return cfg.remote_sandbox_root;
+  return held.get(keyOf(cfg as TuiConfig))?.root ?? LEGACY_LAYOUT_ROOT;
+}
+
+/** Whether the root is the operator's explicit choice. */
+export function rootIsExplicit(cfg: Pick<TuiConfig, "remote_sandbox_root">): boolean {
+  return cfg.remote_sandbox_root !== "";
+}
+
+/**
+ * Probe the container and update the held root when its ID is new. Returns the
+ * root now in force. Never throws and never lowers an answer to "unknown": a
+ * failed or unparseable probe leaves the previous one standing.
+ */
+export async function resolveLayout(cfg: TuiConfig, ssh: SshRunner): Promise<string> {
+  if (rootIsExplicit(cfg)) return cfg.remote_sandbox_root;
+  const key = keyOf(cfg);
+  try {
+    const res = await ssh(cfg.ssh_host, layoutProbeArgv(cfg), { timeoutMs: 10_000 });
+    const probe = res.ok ? parseLayoutProbe(res.stdout) : undefined;
+    if (probe) {
+      const prev = held.get(key);
+      if (prev?.id !== probe.id) held.set(key, { id: probe.id, root: rootForLayout(probe.layout) });
+    }
+  } catch {
+    /* a runner that throws is a probe that did not answer */
+  }
+  return remoteSandboxRoot(cfg);
+}