@wyattjoh/demur 0.4.2 → 0.5.0

package/src/cli.ts

@@ -1,5 +1,15 @@
 #!/usr/bin/env bun
+import { createInterface } from "node:readline/promises";
 import { Predicate } from "effect";
+import { loadCostTotals } from "../extensions/demur/cost-tracker.ts";
+import {
+  loadTrainingRecords,
+  loadTrainingReviews,
+  recordTrainingReview,
+  type TrainingRecord,
+  type TrainingReview,
+  type TrainingReviewInput,
+} from "../extensions/demur/training-store.ts";
 import { guard } from "./guard.ts";
 import {
   deleteApiKey,
@@ -7,12 +17,20 @@ import {
   storeApiKey,
   type ResolvedApiKey,
 } from "./key.ts";
+import {
+  buildTrainingReviewEntries,
+  getTrainingReviewFilter,
+  type TrainingReviewSnapshot,
+} from "./training-review-model.ts";
+import type { TrainingReviewTuiResult } from "./training-review-tui.tsx";
 import type { Verdict } from "./types.ts";
 
 const USAGE = `Usage:
+  demur
   demur auth login
   demur auth status
   demur auth logout
+  demur training review [--plain]
   demur judge "<command>" [--cwd=<path>]`;
 
 /**
@@ -23,18 +41,49 @@ export type CliDependencies = {
   resolveApiKey(): Promise<ResolvedApiKey | undefined>;
   storeApiKey(value: string): Promise<void>;
   deleteApiKey(): Promise<boolean>;
+  loadTrainingRecords(): Promise<ReadonlyArray<TrainingRecord>>;
+  loadTrainingReviews(): Promise<ReadonlyArray<TrainingReview>>;
+  loadGlobalEstimatedCostUsd(): Promise<number>;
+  recordTrainingReview(input: TrainingReviewInput): Promise<TrainingReview>;
+  runTrainingReviewTui(
+    snapshot: TrainingReviewSnapshot,
+    reloadSnapshot: () => Promise<TrainingReviewSnapshot>,
+    recordReview: (input: TrainingReviewInput) => Promise<TrainingReview>,
+  ): Promise<TrainingReviewTuiResult>;
+  isInteractive(): boolean;
   readSecret(prompt: string): Promise<string>;
+  readLine(prompt: string): Promise<string>;
   cwd(): string;
   stdout(message: string): void;
   stderr(message: string): void;
 };
 
+let lineInput:
+  | {
+    terminal: ReturnType<typeof createInterface>;
+    lines: AsyncIterator<string>;
+  }
+  | undefined;
+
 const defaultDependencies: CliDependencies = {
   judge: (command, cwd) => guard(command, cwd, "cli"),
   resolveApiKey,
   storeApiKey,
   deleteApiKey,
+  loadTrainingRecords,
+  loadTrainingReviews,
+  loadGlobalEstimatedCostUsd: async () =>
+    (await loadCostTotals()).estimatedCostUsd,
+  recordTrainingReview,
+  runTrainingReviewTui: async (snapshot, reloadSnapshot, recordReview) => {
+    const { runTrainingReviewTui } = await import(
+      "./training-review-tui.tsx"
+    );
+    return runTrainingReviewTui(snapshot, reloadSnapshot, recordReview);
+  },
+  isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
   readSecret,
+  readLine,
   cwd: () => process.cwd(),
   stdout: (message) => console.log(message),
   stderr: (message) => console.error(message),
@@ -52,10 +101,24 @@ export async function runCli(
   dependencies: CliDependencies = defaultDependencies,
 ): Promise<number> {
   try {
+    if (args.length === 0) {
+      if (!dependencies.isInteractive()) {
+        dependencies.stderr(
+          "demur: the interactive app requires a terminal; use `demur training review --plain` for line-oriented review.",
+        );
+        return 2;
+      }
+      return await runTraining(["review"], dependencies);
+    }
+
     if (args[0] === "auth") {
       return await runAuth(args.slice(1), dependencies);
     }
 
+    if (args[0] === "training") {
+      return await runTraining(args.slice(1), dependencies);
+    }
+
     if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
       dependencies.stdout(USAGE);
       return 0;
@@ -66,6 +129,8 @@ export async function runCli(
   } catch (error: unknown) {
     dependencies.stderr(`demur: ${errorDetail(error)}`);
     return 1;
+  } finally {
+    closeLineInput();
   }
 }
 
@@ -136,6 +201,158 @@ async function runAuth(
   return 2;
 }
 
+async function runTraining(
+  args: ReadonlyArray<string>,
+  dependencies: CliDependencies,
+): Promise<number> {
+  const plain = args.includes("--plain");
+  const operands = args.filter((arg) => arg !== "--plain");
+  if (
+    operands.length !== 1 ||
+    operands[0] !== "review" ||
+    args.filter((arg) => arg === "--plain").length > 1
+  ) {
+    dependencies.stderr(USAGE);
+    return 2;
+  }
+
+  const loadSnapshot = () => loadTrainingReviewSnapshot(dependencies);
+  const snapshot = await loadSnapshot();
+
+  if (!plain && dependencies.isInteractive()) {
+    const result = await dependencies.runTrainingReviewTui(
+      snapshot,
+      loadSnapshot,
+      dependencies.recordTrainingReview,
+    );
+    printReviewSummary(result, dependencies);
+    return 0;
+  }
+
+  const pending = buildTrainingReviewEntries(snapshot)
+    .filter((entry) => getTrainingReviewFilter(entry) === "unreviewed")
+    .map((entry) => entry.record);
+  if (pending.length === 0) {
+    dependencies.stdout("No unreviewed demur training records.");
+    return 0;
+  }
+
+  return runPlainTrainingReview(pending, dependencies);
+}
+
+async function loadTrainingReviewSnapshot(
+  dependencies: CliDependencies,
+): Promise<TrainingReviewSnapshot> {
+  const [records, reviews, globalEstimatedCostUsd] = await Promise.all([
+    dependencies.loadTrainingRecords(),
+    dependencies.loadTrainingReviews(),
+    dependencies.loadGlobalEstimatedCostUsd(),
+  ]);
+  return { records, reviews, globalEstimatedCostUsd };
+}
+
+async function runPlainTrainingReview(
+  pending: ReadonlyArray<TrainingRecord>,
+  dependencies: CliDependencies,
+): Promise<number> {
+  let reviewed = 0;
+  let corrected = 0;
+  let skipped = 0;
+  for (const [index, record] of pending.entries()) {
+    printTrainingRecord(record, index + 1, pending.length, dependencies);
+    const expectedDecision = await readExpectedDecision(record, dependencies);
+    if (expectedDecision === "quit") break;
+    if (expectedDecision === "skip") {
+      skipped += 1;
+      continue;
+    }
+
+    const isCorrection = expectedDecision !== record.verdict.decision;
+    const note = isCorrection
+      ? (await dependencies.readLine("Correction note (optional): ")).trim() ||
+        undefined
+      : undefined;
+    await dependencies.recordTrainingReview({
+      recordId: record.id,
+      originalDecision: record.verdict.decision,
+      expectedDecision,
+      note,
+    });
+    reviewed += 1;
+    if (isCorrection) corrected += 1;
+    dependencies.stdout(
+      isCorrection
+        ? `Recorded correction: ${record.verdict.decision} → ${expectedDecision}.`
+        : `Accepted ${record.verdict.decision} decision.`,
+    );
+  }
+
+  printReviewSummary({ reviewed, corrected, skipped }, dependencies);
+  return 0;
+}
+
+function printReviewSummary(
+  result: TrainingReviewTuiResult,
+  dependencies: CliDependencies,
+): void {
+  const skipped = result.skipped === 0
+    ? "."
+    : `; ${result.skipped} skipped.`;
+  dependencies.stdout(
+    `Reviewed ${result.reviewed} record${result.reviewed === 1 ? "" : "s"}; ${result.corrected} corrected${skipped}`,
+  );
+}
+
+async function readExpectedDecision(
+  record: TrainingRecord,
+  dependencies: CliDependencies,
+): Promise<"allow" | "ask" | "deny" | "skip" | "quit"> {
+  while (true) {
+    const input = (
+      await dependencies.readLine(
+        `Expected decision [enter=${record.verdict.decision}, allow, ask, deny, skip, quit]: `,
+      )
+    ).trim().toLowerCase();
+
+    if (input === "") return record.verdict.decision;
+    if (
+      input === "allow" ||
+      input === "ask" ||
+      input === "deny" ||
+      input === "skip" ||
+      input === "quit"
+    ) {
+      return input;
+    }
+    dependencies.stderr(`Unknown review choice: ${input}`);
+  }
+}
+
+function printTrainingRecord(
+  record: TrainingRecord,
+  index: number,
+  total: number,
+  dependencies: CliDependencies,
+): void {
+  dependencies.stdout("");
+  dependencies.stdout(
+    `[${index}/${total}] ${record.recordedAt} · ${record.mode} · host ${record.hostAction}`,
+  );
+  dependencies.stdout(`cwd: ${record.cwd}`);
+  dependencies.stdout(`command: ${record.command}`);
+  dependencies.stdout(
+    `verdict: ${record.verdict.decision.toUpperCase()} — ${record.verdict.reason}`,
+  );
+  if (record.verdict.judgments !== undefined) {
+    dependencies.stdout(
+      `judgments: ${JSON.stringify(record.verdict.judgments)}`,
+    );
+  }
+  if (record.verdict.failure !== undefined) {
+    dependencies.stdout(`failure: ${record.verdict.failure}`);
+  }
+}
+
 async function runJudge(
   args: ReadonlyArray<string>,
   dependencies: CliDependencies,
@@ -186,6 +403,26 @@ async function runJudge(
   return 0;
 }
 
+async function readLine(prompt: string): Promise<string> {
+  if (lineInput === undefined) {
+    const terminal = createInterface({ input: process.stdin });
+    lineInput = {
+      terminal,
+      lines: terminal[Symbol.asyncIterator](),
+    };
+  }
+
+  process.stderr.write(prompt);
+  const next = await lineInput.lines.next();
+  if (next.done) throw new Error("training review input ended");
+  return next.value;
+}
+
+function closeLineInput(): void {
+  lineInput?.terminal.close();
+  lineInput = undefined;
+}
+
 async function readSecret(prompt: string): Promise<string> {
   if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== "function") {
     return (await Bun.stdin.text()).trim();

package/src/training-review-model.ts

@@ -0,0 +1,176 @@
+import type {
+  TrainingRecord,
+  TrainingReview,
+  TrainingReviewInput,
+} from "../extensions/demur/training-store.ts";
+import type { Decision } from "./types.ts";
+
+/**
+ * Complete append-only training evidence and human review state.
+ */
+export type TrainingReviewSnapshot = {
+  records: ReadonlyArray<TrainingRecord>;
+  reviews: ReadonlyArray<TrainingReview>;
+  globalEstimatedCostUsd: number;
+};
+
+/**
+ * One training record paired with every review appended for its stable ID.
+ */
+export type TrainingReviewEntry = {
+  record: TrainingRecord;
+  reviews: ReadonlyArray<TrainingReview>;
+};
+
+/**
+ * Latest human-review status derived for one training entry.
+ */
+export type TrainingReviewStatus = "unreviewed" | Decision;
+
+/**
+ * Status tabs available in the interactive training-review queue.
+ */
+export type TrainingReviewFilter = "all" | TrainingReviewStatus;
+
+/**
+ * Pair each captured record with its append-only review history.
+ *
+ * @param snapshot - Complete record and review state
+ * @returns Entries in capture order with reviews in append order
+ */
+export function buildTrainingReviewEntries(
+  snapshot: TrainingReviewSnapshot,
+): ReadonlyArray<TrainingReviewEntry> {
+  const reviewsByRecord = new Map<string, Array<TrainingReview>>();
+  for (const review of snapshot.reviews) {
+    const reviews = reviewsByRecord.get(review.recordId) ?? [];
+    reviews.push(review);
+    reviewsByRecord.set(review.recordId, reviews);
+  }
+
+  return snapshot.records.map((record) => ({
+    record,
+    reviews: reviewsByRecord.get(record.id) ?? [],
+  }));
+}
+
+/**
+ * Return the latest append-only human review for an entry.
+ *
+ * @param entry - Training record and its review history
+ * @returns Latest review, or undefined when the record is unreviewed
+ */
+export function getLatestTrainingReview(
+  entry: TrainingReviewEntry,
+): TrainingReview | undefined {
+  return entry.reviews.at(-1);
+}
+
+/**
+ * Classify an entry by its latest human answer.
+ *
+ * @param entry - Training record and its review history
+ * @returns Unreviewed or the latest expected decision
+ */
+export function getTrainingReviewFilter(
+  entry: TrainingReviewEntry,
+): TrainingReviewStatus {
+  return getLatestTrainingReview(entry)?.expectedDecision ?? "unreviewed";
+}
+
+/**
+ * Select one status tab and fuzzy-search matching working directories.
+ *
+ * @param entries - Complete training history
+ * @param filter - Active latest-answer status
+ * @param cwdQuery - Optional fuzzy working-directory query
+ * @returns Matching entries, ranked by path match when a query is present
+ */
+export function filterTrainingReviewEntries(
+  entries: ReadonlyArray<TrainingReviewEntry>,
+  filter: TrainingReviewFilter,
+  cwdQuery: string,
+): ReadonlyArray<TrainingReviewEntry> {
+  const statusMatches = filter === "all"
+    ? entries
+    : entries.filter((entry) => getTrainingReviewFilter(entry) === filter);
+  const query = cwdQuery.trim().toLowerCase();
+  if (query === "") return statusMatches;
+
+  return statusMatches
+    .map((entry, index) => ({
+      entry,
+      index,
+      score: fuzzyPathScore(entry.record.cwd, query),
+    }))
+    .filter(
+      (candidate): candidate is {
+        entry: TrainingReviewEntry;
+        index: number;
+        score: number;
+      } => candidate.score !== undefined,
+    )
+    .sort((left, right) => right.score - left.score || left.index - right.index)
+    .map((candidate) => candidate.entry);
+}
+
+/**
+ * Build an append-only review revision from a human decision.
+ *
+ * @param record - Training evidence being reviewed
+ * @param expectedDecision - Human-selected expected outcome
+ * @param note - Optional correction explanation
+ * @returns Normalized review input for persistence
+ */
+export function createTrainingReviewInput(
+  record: TrainingRecord,
+  expectedDecision: Decision,
+  note: string | undefined,
+): TrainingReviewInput {
+  const corrected = expectedDecision !== record.verdict.decision;
+  return {
+    recordId: record.id,
+    originalDecision: record.verdict.decision,
+    expectedDecision,
+    note: corrected ? note?.trim() || undefined : undefined,
+  };
+}
+
+function fuzzyPathScore(path: string, query: string): number | undefined {
+  const candidate = path.toLowerCase();
+  const substringIndex = candidate.indexOf(query);
+  if (substringIndex >= 0) {
+    return 10_000 + segmentStartBonus(candidate, substringIndex) -
+      substringIndex;
+  }
+
+  const positions: Array<number> = [];
+  let candidateIndex = 0;
+  for (const character of query) {
+    const matchIndex = candidate.indexOf(character, candidateIndex);
+    if (matchIndex < 0) return undefined;
+    positions.push(matchIndex);
+    candidateIndex = matchIndex + 1;
+  }
+
+  const first = positions[0];
+  const last = positions.at(-1);
+  if (first === undefined || last === undefined) return undefined;
+
+  const span = last - first + 1;
+  let consecutive = 0;
+  let segmentStarts = 0;
+  for (const [index, position] of positions.entries()) {
+    if (index > 0 && position === positions[index - 1]! + 1) {
+      consecutive += 1;
+    }
+    segmentStarts += segmentStartBonus(candidate, position);
+  }
+
+  return query.length * 100 - span * 4 - first + consecutive * 12 +
+    segmentStarts;
+}
+
+function segmentStartBonus(path: string, index: number): number {
+  return index === 0 || path[index - 1] === "/" ? 40 : 0;
+}