@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/tui/archiveops.ts

@@ -0,0 +1,192 @@
+// The operator's archive verbs client — `qcr archive run` and
+// `qcr archive restore <pr>`.
+//
+// The same channel as the lesson kill switch (src/tui/lessonswitch.ts): ONE
+// command file written AS ROOT into the root-sealed `commands/operator/`
+// (`docker exec -u 0`, payload on stdin, tmp+mv), then the daemon's own result
+// file read back as the receipt. The two commands validate ONLY from that
+// sealed directory (src/commands.ts `OPERATOR_COMMANDS`): a file the daemon
+// finds unsealed is served as a session's and refused, and the result says
+// so — this client never infers anything from a successful write.
+//
+// The daemon answers within OPERATOR_WAIT_MS (a tick or a restore still
+// running then says `done: false` and goes on), so the client waits that
+// long plus the usual message timeout.
+import { randomUUID } from "node:crypto";
+import { validateCommand, type Command } from "../commands.js";
+import type { TuiConfig } from "../config.js";
+import {
+  OPERATOR_WAIT_MS,
+  storeEntries,
+  backlogPhrase,
+  dbPhrase,
+  filesPhrase,
+  readArchiveRunFigures,
+  storePhrase,
+} from "../archive/status.js";
+import type { SshRunner } from "./remote.js";
+import { commandResultArgv, commandWriteArgv, resultReason } from "./unwedge.js";
+import { resolveLayout } from "./layout.js";
+
+/** The archive verbs' payloads, read from the daemon's own `Command`. */
+export type ArchiveOpCommand = Extract<Command, { command: "archive-run" | "archive-restore" }>;
+
+export interface ArchiveOpOutcome {
+  ok: boolean;
+  reason?: string;
+  /** Who the daemon decided the writer was. `session` means the operator
+   * directory was NOT sealed and the command was refused. */
+  issuer?: "operator" | "session";
+  /** The daemon's result file, as it wrote it (the verb's own fields). */
+  result?: Record<string, unknown>;
+}
+
+/** The exact daemon-validated payload; throws on a command the daemon's own
+ * validator would refuse from the operator channel. */
+export function archiveOpPayload(cmd: ArchiveOpCommand): string {
+  const v = validateCommand(cmd, { issuer: "operator" });
+  if (!v.ok) throw new Error(v.reason);
+  return `${JSON.stringify(cmd, null, 2)}\n`;
+}
+
+export function archiveOpFileName(now: Date, clientId: string, seq: number): string {
+  const ts = now.toISOString().replace(/[:.]/g, "-");
+  return `${ts}-cli-archive-${clientId}-${String(seq).padStart(4, "0")}.json`;
+}
+
+/** How long the client waits for the daemon's answer. */
+export function archiveOpTimeoutMs(cfg: Pick<TuiConfig, "msg_timeout_s">): number {
+  return OPERATOR_WAIT_MS + cfg.msg_timeout_s * 1000;
+}
+
+export class ArchiveOpSender {
+  private seq = 0;
+  private readonly clientId = randomUUID().slice(0, 12);
+
+  constructor(
+    private readonly cfg: TuiConfig,
+    private readonly ssh: SshRunner,
+    private readonly now: () => Date = () => new Date(),
+    private readonly sleep: (ms: number) => Promise<void> = (ms) =>
+      new Promise((resolve) => setTimeout(resolve, ms)),
+  ) {}
+
+  async send(cmd: ArchiveOpCommand): Promise<ArchiveOpOutcome> {
+    await resolveLayout(this.cfg, this.ssh);
+    let payload: string;
+    try {
+      payload = archiveOpPayload(cmd);
+    } catch (err) {
+      return { ok: false, reason: (err as Error).message };
+    }
+    const name = archiveOpFileName(this.now(), this.clientId, this.seq++);
+    const write = await this.ssh(this.cfg.ssh_host, commandWriteArgv(this.cfg, name), {
+      stdin: payload,
+    });
+    if (!write.ok)
+      return {
+        ok: false,
+        reason: `command write failed (${resultReason(write.stderr, `exit ${write.code}`)})`,
+      };
+    const deadline = this.now().getTime() + archiveOpTimeoutMs(this.cfg);
+    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 === "" || body === "pending") continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        // A concurrent reader can see the daemon still writing its receipt.
+        continue;
+      }
+      // Valid JSON is not yet a receipt: anything but an object is unreadable.
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return { ok: false, reason: "unreadable daemon result" };
+      const v = parsed as Record<string, unknown>;
+      const issuer =
+        v["issuer"] === "operator" || v["issuer"] === "session" ? v["issuer"] : undefined;
+      if (v["ok"] !== true)
+        return {
+          ok: false,
+          reason: resultReason(v["reason"], "no reason given"),
+          ...(issuer ? { issuer } : {}),
+          result: v,
+        };
+      return { ok: true, ...(issuer ? { issuer } : {}), result: v };
+    }
+    return {
+      ok: false,
+      reason: "no result before timeout (daemon down, or the operator channel busy?)",
+    };
+  }
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** One line of untrusted text (the result file sits in a dir sessions can
+ * write): no control bytes, one line. */
+const safe = (v: unknown, fallback: string): string => resultReason(v, fallback);
+
+/** A line for the operator's terminal: the daemon's strings sit in a dir the
+ * sessions can write, so no control byte reaches the terminal. */
+const clean = (line: string): string => line.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ");
+
+/** What `qcr archive run|restore` prints for the daemon's answer. */
+export function renderArchiveOp(cmd: ArchiveOpCommand, out: ArchiveOpOutcome): string[] {
+  const lines: string[] = [];
+  const r = out.result ?? {};
+  if (!out.ok) {
+    lines.push(`✖ refused: ${out.reason ?? "no reason given"}`);
+    if (out.issuer === "session")
+      lines.push(
+        "  the daemon found commands/operator/ UNSEALED (writable by its own uid), so it served the file as a session's — check the directory is root-owned 0755 in the container",
+      );
+    return lines;
+  }
+  if (r["done"] === false) {
+    lines.push(`… ${safe(r["note"], "still running — see `qcr archive status`")}`);
+    return lines;
+  }
+  if (cmd.command === "archive-run") {
+    const state = str(r["state"]) ?? "unknown";
+    const held = str(r["held_reason"]);
+    const until = str(r["held_until"]);
+    lines.push(
+      `✓ tick ran (mode ${safe(r["mode"], "?")}) — ${state === "held" ? `HELD (${safe(held, "reason unknown")})${until ? ` until ${safe(until, "?")}` : ""}` : state}` +
+        `${r["planned"] === true ? "; plan recomputed" : ""}`,
+    );
+    const figures = readArchiveRunFigures(r);
+    if (!figures) {
+      lines.push("  the daemon's figures could not be read whole — see `qcr archive status`");
+      return lines.map(clean);
+    }
+    const view = { ...figures, plan_at: null };
+    lines.push(`  ${backlogPhrase(view)}`);
+    const db = dbPhrase(view);
+    if (db) lines.push(`  ${db}`);
+    const files = filesPhrase(view);
+    if (files) lines.push(`  ${files}`);
+    for (const [label, st] of storeEntries(figures.stores)) {
+      const line = storePhrase(label, st);
+      if (line) lines.push(`  ${line}`);
+    }
+    return lines.map(clean);
+  }
+  const outcome = str(r["outcome"]);
+  if (outcome === "none") {
+    lines.push(`• nothing restored: ${safe(r["note"], "no archive to restore")}`);
+    return lines;
+  }
+  const restored = num(r["restored"]);
+  const present = num(r["present"]);
+  const differs = Array.isArray(r["live_differs"]) ? r["live_differs"].length : 0;
+  lines.push(
+    `✓ pr-${cmd.command === "archive-restore" ? cmd.pr : "?"} restored — ${restored ?? "?"} file(s) back, ${present ?? "?"} already present` +
+      (differs > 0 ? `, ${differs} differing live file(s) left as found` : ""),
+  );
+  return lines;
+}

package/src/tui/autofile.ts

@@ -0,0 +1,233 @@
+// Defect-flag auto-filer: defect-tagged memory entries become issue-tracker
+// tickets automatically. Runs PC-side in the TUI (the tracker is a local
+// directory on the operator's machine — the VM cannot reach it) and writes as
+// tracker actor `qcr-tui`. Disabled entirely when no tracker dir is
+// configured.
+//
+// Dedup is a tag. Filing stamps `filed=FT-NNNN` into the entry's own
+// header `k=v` run — the vocabulary of `src/memory/eventtags.ts`, mirrored onto
+// OpenViking's native retrieval tags by the store — so "already filed" is a
+// property of the memory the filer reads, not of a ledger it keeps on the side.
+// The `Memory-key:` line stamped into each ticket is the backstop: the
+// tag write is a store mutation and can be refused (stale hash, store down),
+// and a refused stamp must not produce a duplicate ticket on the next tick.
+// Both keys are stable across pin and across the stamp itself — `memoryKey`
+// normalizes those mutations and the pin provenance header away.
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { EVENT_TAG_RE, parseEventTags } from "../memory/eventtags.js";
+import { memoryTextKey } from "../memory/textidentity.js";
+import { withHeaderTags, withoutHeaderTag } from "../memory/layout.js";
+import { claimTrackerId } from "../trackerid.js";
+import { refOf, type MemoryEntry, type MemoryStore } from "./memory.js";
+
+export const MEMORY_KEY_LINE = "Memory-key:";
+
+/** The event tag that records where a defect entry was filed. */
+export const FILED_TAG = "filed";
+
+/** Dedup key = hash of the entry's TEXT with the tokens the system itself
+ * writes removed (`#pinned`, and the header's `from=…` and `filed=…` — only the header's:
+ * a `filed=` word in the prose is the reporter's, and part of the defect),
+ * not its (ts,id,block) address: retiring an entry shifts indices, pinning
+ * rewrites the text, and the filer's own stamp rewrites it again — any of
+ * those would make an already-filed defect look new and file a duplicate
+ * ticket. Same words = same defect. */
+export function memoryKey(e: MemoryEntry): string {
+  return memoryTextKey(withoutHeaderTag(withoutHeaderTag(e.text, FILED_TAG), "from"));
+}
+
+/** The ticket a previous run filed this entry as, read off its own tag. */
+export function filedAs(e: MemoryEntry): string | undefined {
+  const value = parseEventTags(e.text)[FILED_TAG];
+  return value === undefined || value === "" ? undefined : value;
+}
+
+/**
+ * Insert `filed=<ticket>` into the entry's HEADER — the memory vocabulary's
+ * one header editor (`withHeaderTags`), so the stamp lands where
+ * `parseEventTags` reads it back and the prose keeps its own line breaks. A
+ * tag appended to the body would not be readable back (and, conversely, prose
+ * quoting `filed=FT-9999` can never mint one).
+ */
+export function withFiledTag(text: string, ticketId: string): string {
+  return withHeaderTags(text, { [FILED_TAG]: ticketId });
+}
+
+/** Stamp `filed=<ticketId>` onto the entry the store holds — best-effort,
+ * and only ever AFTER the ticket exists: a refused stamp leaves the
+ * Memory-key backstop holding the dedup, so the worst case is that the entry
+ * is re-checked, never re-filed. */
+export async function stampFiled(
+  store: MemoryStore,
+  entry: MemoryEntry,
+  ticketId: string,
+): Promise<void> {
+  try {
+    await store.apply({ op: "edit", ...refOf(entry), text: withFiledTag(entry.text, ticketId) });
+  } catch {
+    /* the seam resolves refusals; only a broken transport lands here */
+  }
+}
+
+export interface AutoFiled {
+  ticketId: string;
+  file: string;
+  key: string;
+}
+
+export interface TrackerPaths {
+  /** The tracker root (the local issue tracker's root directory). */
+  root: string;
+  effort: string; // "review-sandbox"
+  parent: string; // the effort's map id, "FT-NNNN"
+}
+
+/** The effort's tickets directory, relative to the tracker root. */
+function ticketsRel(paths: TrackerPaths): string {
+  return `efforts/${paths.effort}/tickets`;
+}
+
+/** Keys already present in the effort's tickets — the dedup set. */
+export function filedKeys(paths: TrackerPaths, marker = MEMORY_KEY_LINE): Set<string> {
+  const literal = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const line = new RegExp(`^${literal} (.+)$`, "gm");
+  const keys = new Set<string>();
+  const dir = join(paths.root, ticketsRel(paths));
+  if (!existsSync(dir)) return keys;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    const body = readFileSync(join(dir, f), "utf8");
+    for (const m of body.matchAll(line)) keys.add(m[1]!.trim());
+  }
+  return keys;
+}
+
+/** Claim the next free FT id via exclusive-create of `.ids/<NNNN>` (the
+ * tracker's claim-is-the-lock protocol). Returns the zero-padded number. */
+export function claimNextId(root: string, ticketRelPath: (n: string) => string): string {
+  return claimTrackerId(root, ticketRelPath);
+}
+
+/** The prose of an entry text — `#tags`, `k=v` tokens (the memory vocabulary's
+ * one grammar) and `[[links]]` are not title material, wherever they sit. */
+export function entryProse(text: string): string {
+  return text
+    .split(/\s+/)
+    .filter(
+      (t) => t !== "" && !t.startsWith("#") && !EVENT_TAG_RE.test(t) && !/^\[\[[^\]]*\]\]$/.test(t),
+    )
+    .join(" ");
+}
+
+function slugify(text: string): string {
+  const words = text
+    .replace(/(^|\s)#[\w-]+/g, " ") // tags are not title material
+    .replace(/\[\[[^\]]*\]\]/g, " ")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 6);
+  return words.join("-") || "memory-defect";
+}
+
+export function ticketBody(
+  id: string,
+  e: MemoryEntry,
+  paths: TrackerPaths,
+  nowIso: string,
+): { name: string; content: string } {
+  const firstSentence = entryProse(e.text).slice(0, 110);
+  const slug = slugify(firstSentence);
+  const name = `FT-${id}-${slug}.md`;
+  const content = `# Auto-filed defect: ${slugify(firstSentence).replace(/-/g, " ")}
+
+Id: FT-${id}
+Effort: ${paths.effort}
+Type: impl
+Status: open
+Role: —
+Category: —
+Labels: review-ops, auto-filed
+Assignee: —
+Blocked-by: —
+Parent: ${paths.parent}
+Spec: —
+Branch: —
+PR: —
+Created: ${nowIso} by qcr-tui
+Updated: ${nowIso}
+Claimed: —
+Closed: —
+
+## Question
+
+The overseer flagged an operational defect in the review system (memory
+entry ${e.id} @ ${e.ts}, auto-filed by the TUI). Diagnose,
+fix, and resolve — or close as duplicate/stale with a note.
+
+${MEMORY_KEY_LINE} ${memoryKey(e)}
+
+## Flagged entry
+
+${e.text}
+`;
+  return { name, content };
+}
+
+/**
+ * File every unfiled defect entry; returns what was filed. Never throws — a
+ * broken tracker (or an unreachable memory store) must not take down the TUI
+ * poll loop.
+ *
+ * Two dedup guards, in this order: the entry's own `filed=` tag (checked
+ * first — it survives a tracker that was rebuilt, and the tracker is scanned
+ * only once an entry without one turns up), then the `Memory-key:` scan over
+ * the effort's tickets. A ticket appears whole (written aside, then renamed),
+ * so the scan never takes a torn one for a filing. Only after the ticket is
+ * on disk is the tag written back, so a crash between the two costs a
+ * re-check, never a lost ticket.
+ */
+export async function autofileDefects(
+  paths: TrackerPaths,
+  defects: MemoryEntry[],
+  nowIso: string,
+  store?: MemoryStore,
+): Promise<AutoFiled[]> {
+  const filed: AutoFiled[] = [];
+  const stamps: Array<{ entry: MemoryEntry; ticketId: string }> = [];
+  try {
+    let seen: Set<string> | undefined;
+    const ticketsDir = join(paths.root, ticketsRel(paths));
+    for (const e of defects) {
+      if (filedAs(e) !== undefined) continue;
+      seen ??= filedKeys(paths);
+      const key = memoryKey(e);
+      if (seen.has(key)) continue;
+      mkdirSync(ticketsDir, { recursive: true });
+      const id = claimNextId(
+        paths.root,
+        (n) => `${ticketsRel(paths)}/${ticketBody(n, e, paths, nowIso).name}`,
+      );
+      const { name, content } = ticketBody(id, e, paths, nowIso);
+      const tmp = join(ticketsDir, `.${name}.tmp`);
+      writeFileSync(tmp, content);
+      renameSync(tmp, join(ticketsDir, name));
+      seen.add(key);
+      filed.push({ ticketId: `FT-${id}`, file: name, key });
+      stamps.push({ entry: e, ticketId: `FT-${id}` });
+    }
+  } catch {
+    /* tracker unavailable — quietly do nothing this tick */
+  }
+  if (store) for (const { entry, ticketId } of stamps) await stampFiled(store, entry, ticketId);
+  return filed;
+}