saterminal 0.2.0 → 0.3.0

package/src/main.ts

@@ -1,4 +1,13 @@
 #!/usr/bin/env bun
+import { parseArgs, runCliCommand } from "./cli.ts";
 import { runTui } from "./tui.ts";
 
-await runTui();
+const parsed = parseArgs(process.argv.slice(2));
+
+if (parsed.kind === "tui") {
+  await runTui();
+} else if (parsed.kind === "review") {
+  await runTui({ mode: "review" });
+} else {
+  process.exitCode = await runCliCommand(parsed);
+}

package/src/progress.ts

@@ -0,0 +1,48 @@
+const partialBlocks = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"] as const;
+
+export type ProgressBar = {
+  filled: string;
+  partial: string;
+  empty: string;
+  fullCells: number;
+  emptyCells: number;
+};
+
+export function progressBar(ratio: number, width: number): ProgressBar {
+  const normalized = Number.isFinite(ratio) ? Math.min(1, Math.max(0, ratio)) : 0;
+  const cells = Math.max(0, Math.floor(width));
+  const exact = normalized * cells;
+  const full = Math.floor(exact);
+  const partial = Math.round((exact - full) * 8);
+
+  if (cells === 0) {
+    return { filled: "", partial: "", empty: "", fullCells: 0, emptyCells: 0 };
+  }
+
+  if (partial === 8 && full < cells) {
+    const fullCells = full + 1;
+    const emptyCells = cells - fullCells;
+    return {
+      filled: "█".repeat(fullCells),
+      partial: "",
+      empty: " ".repeat(emptyCells),
+      fullCells,
+      emptyCells,
+    };
+  }
+
+  const partialBlock = full < cells ? partialBlocks[partial] : "";
+  const emptyCells = cells - full - (partialBlock ? 1 : 0);
+  return {
+    filled: "█".repeat(full),
+    partial: partialBlock,
+    empty: " ".repeat(emptyCells),
+    fullCells: full,
+    emptyCells,
+  };
+}
+
+export function progressBarText(ratio: number, width: number): string {
+  const bar = progressBar(ratio, width);
+  return `${bar.filled}${bar.partial}${bar.empty}`;
+}

package/src/state.ts

@@ -1,8 +1,8 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, sep } from "node:path";
 import { defaultFocus, normalizeFocus } from "./focus.ts";
-import type { Attempt, Focus, Outcome, SummaryRow } from "./types.ts";
+import type { Attempt, AttemptEvent, Focus, Outcome, QuestionMeta, SummaryRow } from "./types.ts";
 
 export function resolveStateDir(home = homedir()): string {
   return join(home, ".saterminal", "userlocal");
@@ -23,10 +23,12 @@ export function displayStateDir(dir: string, home = homedir()): string {
 
 export const stateDir = resolveStateDir();
 export const attemptsPath = join(stateDir, "attempts.csv");
+export const eventsPath = join(stateDir, "events.csv");
 export const summaryPath = join(stateDir, "summary.csv");
 export const focusPath = join(stateDir, "focus.json");
 
-const attemptsHeader = "question_id,outcome,updated_at,elapsed_seconds";
+const attemptsHeader = "question_id,outcome,updated_at,elapsed_seconds,difficulty,domain,domain_desc,skill,skill_desc";
+const eventsHeader = "question_id,correct,answered_at,elapsed_seconds,difficulty,domain,domain_desc,skill,skill_desc";
 const summaryHeader = "metric,value,updated_at";
 
 export async function stateDirExists(dir = stateDir): Promise<boolean> {
@@ -44,6 +46,7 @@ export async function stateDirExists(dir = stateDir): Promise<boolean> {
 export async function ensureStateFiles(dir = stateDir): Promise<void> {
   await mkdir(dir, { recursive: true });
   await ensureFile(join(dir, "attempts.csv"), `${attemptsHeader}\n`);
+  await ensureFile(join(dir, "events.csv"), `${eventsHeader}\n`);
   await ensureFile(join(dir, "summary.csv"), `${summaryHeader}\n`);
   await ensureFile(join(dir, "focus.json"), `${JSON.stringify(defaultFocus, null, 2)}\n`);
 }
@@ -55,7 +58,7 @@ export async function loadAttempts(path = attemptsPath): Promise<Map<string, Att
   const attempts = new Map<string, Attempt>();
 
   for (const row of rows.slice(1)) {
-    const [question_id, outcome, updated_at, elapsed_seconds] = row;
+    const [question_id, outcome, updated_at, elapsed_seconds, difficulty, domain, domain_desc, skill, skill_desc] = row;
     if (!question_id || !isOutcome(outcome) || !updated_at) {
       continue;
     }
@@ -65,6 +68,7 @@ export async function loadAttempts(path = attemptsPath): Promise<Map<string, Att
       outcome,
       updated_at,
       elapsed_seconds: readElapsedSeconds(elapsed_seconds),
+      ...optionalMetadata({ difficulty, domain, domain_desc, skill, skill_desc }),
     });
   }
 
@@ -75,22 +79,91 @@ export async function saveAttempts(attempts: Map<string, Attempt>, path = attemp
   await mkdir(dirname(path), { recursive: true });
   const rows = [...attempts.values()]
     .sort((a, b) => a.updated_at.localeCompare(b.updated_at))
-    .map((attempt) => [attempt.question_id, attempt.outcome, attempt.updated_at, String(attempt.elapsed_seconds)]);
+    .map((attempt) => [
+      attempt.question_id,
+      attempt.outcome,
+      attempt.updated_at,
+      String(attempt.elapsed_seconds),
+      attempt.difficulty ?? "",
+      attempt.domain ?? "",
+      attempt.domain_desc ?? "",
+      attempt.skill ?? "",
+      attempt.skill_desc ?? "",
+    ]);
 
   await writeFile(path, formatCsv([attemptsHeader.split(","), ...rows]), "utf8");
 }
 
+export async function loadAttemptEvents(path = eventsPath): Promise<AttemptEvent[]> {
+  await ensureFile(path, `${eventsHeader}\n`);
+  const raw = await readFile(path, "utf8");
+  const rows = parseCsv(raw);
+  const events: AttemptEvent[] = [];
+
+  for (const row of rows.slice(1)) {
+    const [question_id, correct, answered_at, elapsed_seconds, difficulty, domain, domain_desc, skill, skill_desc] = row;
+    if (!question_id || !isBooleanText(correct) || !answered_at) {
+      continue;
+    }
+
+    events.push({
+      question_id,
+      correct: correct === "true",
+      answered_at,
+      elapsed_seconds: readElapsedSeconds(elapsed_seconds),
+      difficulty: difficulty ?? "",
+      domain: domain ?? "",
+      domain_desc: domain_desc || undefined,
+      skill: skill ?? "",
+      skill_desc: skill_desc || undefined,
+    });
+  }
+
+  return events;
+}
+
+export async function appendAttemptEvent(
+  meta: QuestionMeta,
+  correct: boolean,
+  elapsedSeconds = 0,
+  now = new Date(),
+  path = eventsPath,
+): Promise<AttemptEvent> {
+  const event: AttemptEvent = {
+    question_id: meta.questionId,
+    correct,
+    answered_at: now.toISOString(),
+    elapsed_seconds: elapsedSeconds,
+    difficulty: meta.difficulty,
+    domain: meta.primary_class_cd,
+    domain_desc: meta.primary_class_cd_desc,
+    skill: meta.skill_cd,
+    skill_desc: meta.skill_desc,
+  };
+
+  await ensureFile(path, `${eventsHeader}\n`);
+  await appendFile(path, formatCsv([attemptEventRow(event)]), "utf8");
+  return event;
+}
+
 export function recordAttempt(
   attempts: Map<string, Attempt>,
   questionId: string,
   wasCorrect: boolean,
   elapsedSeconds = 0,
   now = new Date(),
+  meta?: QuestionMeta,
 ): Attempt {
   const existing = attempts.get(questionId);
   const updated_at = now.toISOString();
   const outcome = nextOutcome(existing?.outcome, wasCorrect);
-  const attempt = { question_id: questionId, outcome, updated_at, elapsed_seconds: elapsedSeconds };
+  const attempt = {
+    question_id: questionId,
+    outcome,
+    updated_at,
+    elapsed_seconds: elapsedSeconds,
+    ...metadataFromQuestionMeta(meta),
+  };
   attempts.set(questionId, attempt);
   return attempt;
 }
@@ -157,11 +230,47 @@ function isOutcome(value: string | undefined): value is Outcome {
   return value === "correct" || value === "incorrect" || value === "corrected";
 }
 
+function isBooleanText(value: string | undefined): value is "true" | "false" {
+  return value === "true" || value === "false";
+}
+
 function readElapsedSeconds(value: string | undefined): number {
   const seconds = Number(value);
   return Number.isFinite(seconds) && seconds >= 0 ? seconds : 0;
 }
 
+function metadataFromQuestionMeta(meta: QuestionMeta | undefined): Partial<Attempt> {
+  if (!meta) {
+    return {};
+  }
+
+  return optionalMetadata({
+    difficulty: meta.difficulty,
+    domain: meta.primary_class_cd,
+    domain_desc: meta.primary_class_cd_desc,
+    skill: meta.skill_cd,
+    skill_desc: meta.skill_desc,
+  });
+}
+
+function optionalMetadata(metadata: Pick<Attempt, "difficulty" | "domain" | "domain_desc" | "skill" | "skill_desc">): Partial<Attempt> {
+  return Object.fromEntries(Object.entries(metadata).filter(([, value]) => value)) as Partial<Attempt>;
+}
+
+function attemptEventRow(event: AttemptEvent): string[] {
+  return [
+    event.question_id,
+    String(event.correct),
+    event.answered_at,
+    String(event.elapsed_seconds),
+    event.difficulty,
+    event.domain,
+    event.domain_desc ?? "",
+    event.skill,
+    event.skill_desc ?? "",
+  ];
+}
+
 async function ensureFile(path: string, contents: string): Promise<void> {
   try {
     await readFile(path, "utf8");

package/src/tui/app.ts

@@ -1,24 +1,45 @@
 import { defaultFocus } from "../focus.ts";
 import { ensureStateFiles, loadAttempts, loadFocus, stateDirExists } from "../state.ts";
-import { handleKey } from "./input.ts";
-import { createDocument, render } from "./render.ts";
-import { term } from "./terminal.ts";
+import { handleKey, loadNextQuestion } from "./input.ts";
+import { createFrameRenderer, render } from "./render.ts";
+import { term } from "./kit.ts";
 import type { AppState, KeyData } from "./types.ts";
+import type { Attempt } from "../types.ts";
 
-async function loadPersistedState(state: AppState): Promise<void> {
+export type TuiOptions = {
+  mode?: "practice" | "review";
+};
+
+async function loadPersistedState(state: AppState, options: TuiOptions = {}): Promise<void> {
   await ensureStateFiles();
   state.attempts = await loadAttempts();
   state.focus = await loadFocus();
   state.focusIndex = 1;
   state.focusColumn = 0;
   state.focusRow = 1;
+  state.notice = undefined;
+
+  if (options.mode === "review") {
+    state.reviewMode = true;
+    state.reviewQuestionIds = reviewQuestionIds(state.attempts);
+    if (state.reviewQuestionIds.length === 0) {
+      state.notice = "No review queue yet. Miss or correct a question first.";
+      state.view = "history";
+      return;
+    }
+
+    await loadNextQuestion(state);
+    return;
+  }
+
   state.view = "focus";
 }
 
-export async function runTui(): Promise<void> {
+export async function runTui(options: TuiOptions = {}): Promise<void> {
   const state: AppState = {
     attempts: new Map(),
     skippedIds: new Set(),
+    reviewMode: options.mode === "review",
     focus: defaultFocus,
     focusIndex: 1,
     focusColumn: 0,
@@ -36,16 +57,17 @@ export async function runTui(): Promise<void> {
 
   term.fullscreen(true);
   term.hideCursor();
-  const doc = createDocument();
+  term.grabInput(true);
+  const renderer = createFrameRenderer();
+  renderer.clear();
   const tick = setInterval(() => {
     if (state.view === "practice" && !state.timerPaused) {
-      render(doc, state);
+      render(renderer, state);
     }
   }, 1000);
 
   const cleanup = () => {
     clearInterval(tick);
-    doc.destroy();
     term.grabInput(false);
     term.hideCursor(false);
     term.fullscreen(false);
@@ -53,11 +75,14 @@ export async function runTui(): Promise<void> {
   };
 
   process.on("SIGINT", cleanup);
-  term.on("resize", () => render(doc, state));
+  term.on("resize", () => {
+    renderer.clear();
+    render(renderer, state);
+  });
 
   try {
     if (await stateDirExists()) {
-      await loadPersistedState(state);
+      await loadPersistedState(state, options);
     } else {
       state.view = "setup";
     }
@@ -66,7 +91,7 @@ export async function runTui(): Promise<void> {
     state.error = error instanceof Error ? error.message : String(error);
   }
 
-  render(doc, state);
+  render(renderer, state);
 
   term.on("key", async (name: string, _matches?: string[], data?: KeyData) => {
     try {
@@ -77,22 +102,33 @@ export async function runTui(): Promise<void> {
 
       if (state.view === "setup") {
         if (name === "y" || name === "ENTER") {
-          await loadPersistedState(state);
+          await loadPersistedState(state, options);
         } else if (name === "n") {
           cleanup();
           return;
         }
 
-        render(doc, state);
+        render(renderer, state);
         return;
       }
 
       await handleKey(state, name, data);
-      render(doc, state);
+      render(renderer, state);
     } catch (error) {
       state.view = "error";
       state.error = error instanceof Error ? error.message : String(error);
-      render(doc, state);
+      render(renderer, state);
     }
   });
 }
+
+function reviewQuestionIds(attempts: Map<string, Attempt>): string[] {
+  return [...attempts.values()]
+    .filter((attempt) => attempt.outcome === "incorrect" || attempt.outcome === "corrected")
+    .sort((a, b) => reviewPriority(a) - reviewPriority(b) || a.updated_at.localeCompare(b.updated_at))
+    .map((attempt) => attempt.question_id);
+}
+
+function reviewPriority(attempt: Attempt): number {
+  return attempt.outcome === "incorrect" ? 0 : 1;
+}

package/src/tui/frame.ts

@@ -0,0 +1,210 @@
+import type { Terminal } from "terminal-kit";
+
+export type TextAttr = Record<string, unknown>;
+
+type FrameCell = {
+  char: string;
+  attr: TextAttr;
+};
+
+export type FrameRun = {
+  x: number;
+  text: string;
+  attr: TextAttr;
+};
+
+export type FrameOutput = {
+  clear(): void;
+  moveTo(x: number, y: number): void;
+  eraseLineAfter(): void;
+  reset(): void;
+  write(value: string, attr?: TextAttr): void;
+};
+
+const emptyAttr: TextAttr = {};
+
+export class Frame {
+  readonly rows: FrameCell[][];
+
+  constructor(readonly width: number, readonly height: number) {
+    this.rows = Array.from({ length: height }, () => []);
+  }
+
+  writeText(x: number, y: number, value: string, attr: TextAttr = {}, width = this.width - x): void {
+    if (y < 0 || y >= this.height || x >= this.width || width <= 0) {
+      return;
+    }
+
+    const start = Math.max(0, x);
+    const content = truncate(value, width);
+    if (!content) {
+      return;
+    }
+
+    const row = this.rows[y];
+    const chars = [...content].slice(Math.max(0, -x), Math.max(0, -x) + this.width - start);
+    for (const [offset, char] of chars.entries()) {
+      row[start + offset] = { char, attr };
+    }
+  }
+
+  rowRuns(y: number): FrameRun[] {
+    const row = this.rows[y] ?? [];
+    const runs: FrameRun[] = [];
+    let x = 0;
+
+    while (x < this.width) {
+      while (x < this.width && cellAt(row, x).char === " ") {
+        x++;
+      }
+
+      if (x >= this.width) {
+        break;
+      }
+
+      const start = x;
+      const attr = cellAt(row, x).attr;
+      const key = attrKey(attr);
+      const chars: string[] = [];
+
+      while (x < this.width && attrKey(cellAt(row, x).attr) === key) {
+        chars.push(cellAt(row, x).char);
+        x++;
+      }
+
+      const text = chars.join("").trimEnd();
+      if (text) {
+        runs.push({ x: start, text, attr });
+      }
+    }
+
+    return runs;
+  }
+
+  rowKey(y: number): string {
+    return this.rowRuns(y)
+      .map((run) => `${run.x}:${attrKey(run.attr)}:${run.text}`)
+      .join("\u001f");
+  }
+}
+
+export class FrameRenderer {
+  private previous?: {
+    width: number;
+    height: number;
+    rowKeys: string[];
+  };
+  private cleared = false;
+
+  constructor(private readonly output: FrameOutput) {}
+
+  clear(): void {
+    this.previous = undefined;
+    this.cleared = true;
+    this.output.reset();
+    this.output.clear();
+  }
+
+  draw(frame: Frame): void {
+    const rowKeys = Array.from({ length: frame.height }, (_, y) => frame.rowKey(y));
+    const force = !this.previous || this.previous.width !== frame.width || this.previous.height !== frame.height;
+    if (force && !this.cleared) {
+      this.output.reset();
+      this.output.clear();
+    }
+
+    const previous = force ? undefined : this.previous;
+    let changed = false;
+    for (let y = 0; y < frame.height; y++) {
+      if (previous && previous.rowKeys[y] === rowKeys[y]) {
+        continue;
+      }
+      if (!previous && !rowKeys[y]) {
+        continue;
+      }
+
+      this.output.moveTo(1, y + 1);
+      if (previous) {
+        this.output.reset();
+        this.output.eraseLineAfter();
+      }
+
+      for (const run of frame.rowRuns(y)) {
+        this.output.moveTo(run.x + 1, y + 1);
+        this.output.write(run.text, run.attr);
+      }
+      changed = true;
+    }
+
+    if (changed) {
+      this.output.reset();
+    }
+    this.previous = { width: frame.width, height: frame.height, rowKeys };
+    this.cleared = false;
+  }
+}
+
+type StyledTerminal = Terminal & Record<string, Terminal>;
+
+export class TerminalFrameOutput implements FrameOutput {
+  constructor(private readonly terminal: Terminal) {}
+
+  clear(): void {
+    this.terminal.clear();
+  }
+
+  moveTo(x: number, y: number): void {
+    this.terminal.moveTo(x, y);
+  }
+
+  eraseLineAfter(): void {
+    this.terminal.eraseLineAfter();
+  }
+
+  reset(): void {
+    this.terminal.styleReset();
+  }
+
+  write(value: string, attr: TextAttr = {}): void {
+    let output = this.terminal as StyledTerminal;
+
+    if (attr.bold) {
+      output = output.bold as StyledTerminal;
+    }
+    if (attr.underline) {
+      output = output.underline as StyledTerminal;
+    }
+    if (attr.italic) {
+      output = output.italic as StyledTerminal;
+    }
+
+    const color = typeof attr.color === "string" ? attr.color : undefined;
+    if (color && typeof output[color] === "function") {
+      output = output[color] as StyledTerminal;
+    }
+
+    output(value);
+  }
+}
+
+export function truncate(value: string, width: number): string {
+  const chars = [...value];
+  if (chars.length <= width) {
+    return value;
+  }
+  if (width <= 1) {
+    return chars.slice(0, width).join("");
+  }
+  return `${chars.slice(0, width - 1).join("")}…`;
+}
+
+function cellAt(row: FrameCell[], x: number): FrameCell {
+  return row[x] ?? { char: " ", attr: emptyAttr };
+}
+
+function attrKey(attr: TextAttr): string {
+  return Object.keys(attr)
+    .sort()
+    .map((key) => `${key}:${String(attr[key])}`)
+    .join(";");
+}

package/src/tui/input.ts

@@ -1,5 +1,5 @@
 import { fetchPracticeQuestion, findQuestionByShortId } from "../api.ts";
-import { recordAttempt, saveAttempts, saveFocus, saveSummary } from "../state.ts";
+import { appendAttemptEvent, recordAttempt, saveAttempts, saveFocus, saveSummary } from "../state.ts";
 import { focusGrid, moveFocusGridPosition, normalizeFocusGridPosition, toggleFocusGridRow } from "./focus-grid.ts";
 import {
   answerKeys,
@@ -120,7 +120,9 @@ export async function handleKey(state: AppState, name: string, data?: KeyData):
       state.lastCorrect = correct;
       pauseTimer(state);
       if (state.question) {
-        recordAttempt(state.attempts, state.question.meta.questionId, correct, elapsedSeconds);
+        const answeredAt = new Date();
+        recordAttempt(state.attempts, state.question.meta.questionId, correct, elapsedSeconds, answeredAt, state.question.meta);
+        await appendAttemptEvent(state.question.meta, correct, elapsedSeconds, answeredAt);
         await saveAttempts(state.attempts);
         await saveSummary(state.attempts);
       }
@@ -211,6 +213,11 @@ async function handleFocusKey(state: AppState, name: string, data?: KeyData): Pr
 export async function loadNextQuestion(state: AppState): Promise<void> {
   state.view = "loading";
   state.question = await takeNextQuestion(state);
+  if (!state.question) {
+    state.notice = "Review queue complete.";
+    state.view = "history";
+    return;
+  }
   state.selected = 0;
   resetPaneScroll(state);
   state.elapsedMs = 0;
@@ -223,6 +230,10 @@ export async function loadNextQuestion(state: AppState): Promise<void> {
 }
 
 async function takeNextQuestion(state: AppState) {
+  if (state.reviewMode) {
+    return takeReviewQuestion(state);
+  }
+
   const cached = state.nextQuestion;
   state.nextQuestion = undefined;
 
@@ -236,7 +247,27 @@ async function takeNextQuestion(state: AppState) {
   return fetchPracticeQuestion(questionExclusions(state), state.focus);
 }
 
+async function takeReviewQuestion(state: AppState): Promise<PracticeQuestion | undefined> {
+  while (state.reviewQuestionIds && state.reviewQuestionIds.length > 0) {
+    const id = state.reviewQuestionIds.shift();
+    if (!id) {
+      continue;
+    }
+
+    const question = await findQuestionByShortId(id);
+    if (question) {
+      return question;
+    }
+  }
+
+  return undefined;
+}
+
 function cacheNextQuestion(state: AppState): void {
+  if (state.reviewMode) {
+    return;
+  }
+
   state.nextQuestion = fetchPracticeQuestion(questionExclusions(state), state.focus).catch(() => undefined);
 }
 

package/src/tui/kit.ts

@@ -1,29 +1,9 @@
 import terminalKit from "terminal-kit";
 
-export const tk = terminalKit;
 export const term = terminalKit.terminal;
-export const gutter = 2;
-
-export type TkDocument = InstanceType<typeof terminalKit.Document>;
-export type TkColumnMenuMulti = InstanceType<typeof terminalKit.ColumnMenuMulti>;
-export type TkWindow = InstanceType<typeof terminalKit.Window>;
 
 export function terminalSize(): { width: number; height: number } {
   const width = Number.isFinite(term.width) ? term.width : 80;
   const height = Number.isFinite(term.height) ? term.height : 24;
   return { width, height };
 }
-
-export function contentBounds(): { x: number; y: number; width: number; height: number } {
-  const { width, height } = terminalSize();
-  return {
-    x: 1,
-    y: 4,
-    width: Math.max(40, width),
-    height: Math.max(10, height - 5),
-  };
-}
-
-export function menuItem(content: string, value: string): { content: string; value: string } {
-  return { content, value };
-}