saterminal 0.1.0

package/src/state.ts

@@ -0,0 +1,203 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defaultFocus, normalizeFocus } from "./focus.ts";
+import type { Attempt, Focus, Outcome, SummaryRow } from "./types.ts";
+
+export const stateDir = "userlocal";
+export const attemptsPath = join(stateDir, "attempts.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 summaryHeader = "metric,value,updated_at";
+
+export async function ensureStateFiles(): Promise<void> {
+  await mkdir(stateDir, { recursive: true });
+  await ensureFile(attemptsPath, `${attemptsHeader}\n`);
+  await ensureFile(summaryPath, `${summaryHeader}\n`);
+  await ensureFile(focusPath, `${JSON.stringify(defaultFocus, null, 2)}\n`);
+}
+
+export async function loadAttempts(path = attemptsPath): Promise<Map<string, Attempt>> {
+  await ensureFile(path, `${attemptsHeader}\n`);
+  const raw = await readFile(path, "utf8");
+  const rows = parseCsv(raw);
+  const attempts = new Map<string, Attempt>();
+
+  for (const row of rows.slice(1)) {
+    const [question_id, outcome, updated_at, elapsed_seconds] = row;
+    if (!question_id || !isOutcome(outcome) || !updated_at) {
+      continue;
+    }
+
+    attempts.set(question_id, {
+      question_id,
+      outcome,
+      updated_at,
+      elapsed_seconds: readElapsedSeconds(elapsed_seconds),
+    });
+  }
+
+  return attempts;
+}
+
+export async function saveAttempts(attempts: Map<string, Attempt>, path = attemptsPath): Promise<void> {
+  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)]);
+
+  await writeFile(path, formatCsv([attemptsHeader.split(","), ...rows]), "utf8");
+}
+
+export function recordAttempt(
+  attempts: Map<string, Attempt>,
+  questionId: string,
+  wasCorrect: boolean,
+  elapsedSeconds = 0,
+  now = new Date(),
+): 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 };
+  attempts.set(questionId, attempt);
+  return attempt;
+}
+
+export function nextOutcome(previous: Outcome | undefined, wasCorrect: boolean): Outcome {
+  if (previous === "correct" || previous === "corrected") {
+    return previous;
+  }
+
+  if (previous === "incorrect" && wasCorrect) {
+    return "corrected";
+  }
+
+  return wasCorrect ? "correct" : "incorrect";
+}
+
+export function buildSummaryRows(attempts: Map<string, Attempt>, now = new Date()): SummaryRow[] {
+  const updated_at = now.toISOString();
+  const values = [...attempts.values()];
+  const total = values.length;
+  const correct = values.filter((attempt) => attempt.outcome === "correct").length;
+  const incorrect = values.filter((attempt) => attempt.outcome === "incorrect").length;
+  const corrected = values.filter((attempt) => attempt.outcome === "corrected").length;
+  const mastered = correct + corrected;
+  const accuracy = total === 0 ? "0.00" : (mastered / total).toFixed(2);
+  const totalSeconds = values.reduce((sum, attempt) => sum + attempt.elapsed_seconds, 0);
+  const avgSeconds = total === 0 ? 0 : totalSeconds / total;
+
+  return [
+    { metric: "answered", value: String(total), updated_at },
+    { metric: "correct", value: String(correct), updated_at },
+    { metric: "incorrect", value: String(incorrect), updated_at },
+    { metric: "corrected", value: String(corrected), updated_at },
+    { metric: "accuracy", value: accuracy, updated_at },
+    { metric: "avg_seconds", value: avgSeconds.toFixed(1), updated_at },
+  ];
+}
+
+export async function saveSummary(attempts: Map<string, Attempt>, path = summaryPath): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const rows = buildSummaryRows(attempts).map((row) => [row.metric, row.value, row.updated_at]);
+  await writeFile(path, formatCsv([summaryHeader.split(","), ...rows]), "utf8");
+}
+
+export async function loadFocus(path = focusPath): Promise<Focus> {
+  await ensureFile(path, `${JSON.stringify(defaultFocus, null, 2)}\n`);
+  try {
+    return normalizeFocus(JSON.parse(await readFile(path, "utf8")));
+  } catch {
+    return defaultFocus;
+  }
+}
+
+export async function saveFocus(focus: Focus, path = focusPath): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(normalizeFocus(focus), null, 2)}\n`, "utf8");
+}
+
+function isOutcome(value: string | undefined): value is Outcome {
+  return value === "correct" || value === "incorrect" || value === "corrected";
+}
+
+function readElapsedSeconds(value: string | undefined): number {
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : 0;
+}
+
+async function ensureFile(path: string, contents: string): Promise<void> {
+  try {
+    await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents, "utf8");
+  }
+}
+
+function parseCsv(raw: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index];
+    const next = raw[index + 1];
+
+    if (quoted) {
+      if (char === "\"" && next === "\"") {
+        field += "\"";
+        index += 1;
+      } else if (char === "\"") {
+        quoted = false;
+      } else {
+        field += char;
+      }
+      continue;
+    }
+
+    if (char === "\"") {
+      quoted = true;
+    } else if (char === ",") {
+      row.push(field.trim());
+      field = "";
+    } else if (char === "\n") {
+      row.push(field.trim());
+      if (row.some((value) => value.length > 0)) {
+        rows.push(row);
+      }
+      row = [];
+      field = "";
+    } else if (char !== "\r") {
+      field += char;
+    }
+  }
+
+  if (field.length > 0 || row.length > 0) {
+    row.push(field.trim());
+    if (row.some((value) => value.length > 0)) {
+      rows.push(row);
+    }
+  }
+
+  return rows;
+}
+
+function formatCsv(rows: string[][]): string {
+  return `${rows.map((row) => row.map(csvEscape).join(",")).join("\n")}\n`;
+}
+
+function csvEscape(value: string): string {
+  if (!/[",\n\r]/.test(value)) {
+    return value;
+  }
+
+  return `"${value.replaceAll("\"", "\"\"")}"`;
+}

package/src/text.ts

@@ -0,0 +1,256 @@
+import he from "he";
+import { HTMLElement, NodeType, parse, type Node } from "node-html-parser";
+import wrap from "word-wrap";
+
+export type TextStyle = {
+  bold?: boolean;
+  underline?: boolean;
+  italic?: boolean;
+};
+
+export type TextSegment = {
+  text: string;
+  style: TextStyle;
+};
+
+export function htmlToText(html = ""): string {
+  const text = parseHtmlSegments(html)
+    .map((segment) => segment.text)
+    .join("")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+
+  return normalizeDisplayText(text);
+}
+
+export function parseHtmlSegments(html = ""): TextSegment[] {
+  const root = parse(prepareHtml(html), { lowerCaseTagName: true });
+  const segments: TextSegment[] = [];
+  walkNodes(root, {}, segments);
+
+  return finalizeSegments(segments).map((segment, index, all) => ({
+    text: normalizeDisplayText(normalizeSegmentWhitespace(trimSegmentEdges(segment.text, index, all.length))),
+    style: segment.style,
+  }));
+}
+
+export function wrapSegments(segments: TextSegment[], width: number): TextSegment[][] {
+  const usableWidth = Math.max(1, width);
+  const lines: TextSegment[][] = [];
+  let currentLine: TextSegment[] = [];
+  let currentWidth = 0;
+
+  const flushLine = () => {
+    lines.push(currentLine);
+    currentLine = [];
+    currentWidth = 0;
+  };
+
+  const appendToLine = (text: string, style: TextStyle) => {
+    if (!text) {
+      return;
+    }
+
+    const last = currentLine[currentLine.length - 1];
+    if (last && stylesEqual(last.style, style)) {
+      last.text += text;
+    } else {
+      currentLine.push({ text, style: { ...style } });
+    }
+    currentWidth += text.length;
+  };
+
+  for (const segment of segments) {
+    const parts = segment.text.split("\n");
+    for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
+      if (partIndex > 0) {
+        flushLine();
+      }
+
+      const words = parts[partIndex].split(/\s+/).filter(Boolean);
+      for (const word of words) {
+        const needed = (currentWidth === 0 ? 0 : 1) + word.length;
+
+        if (currentWidth > 0 && currentWidth + needed > usableWidth) {
+          flushLine();
+        }
+
+        appendToLine(`${currentWidth === 0 ? "" : " "}${word}`, segment.style);
+      }
+    }
+  }
+
+  if (currentLine.length > 0 || lines.length === 0) {
+    flushLine();
+  }
+
+  return lines;
+}
+
+export function hasHtmlTable(...values: Array<string | undefined>): boolean {
+  return values.some((value) => parse(value ?? "").querySelector("table") !== null);
+}
+
+export function decodeEntities(value: string): string {
+  return he.decode(value);
+}
+
+export function wrapText(value: string, width: number): string[] {
+  return wrap(value, {
+    width: Math.max(1, width),
+    trim: true,
+    indent: "",
+    newline: "\n",
+  }).split("\n");
+}
+
+function walkNodes(node: Node, style: TextStyle, segments: TextSegment[]): void {
+  if (node.nodeType === NodeType.TEXT_NODE) {
+    pushText(segments, node.text, style);
+    return;
+  }
+
+  if (!(node instanceof HTMLElement)) {
+    return;
+  }
+
+  if (!node.tagName) {
+    for (const child of node.childNodes) {
+      walkNodes(child, style, segments);
+    }
+    return;
+  }
+
+  const tag = node.tagName.toLowerCase();
+  if (tag === "br") {
+    pushText(segments, "\n", style);
+    return;
+  }
+
+  const nextStyle = styleForElement(node, style);
+  for (const child of node.childNodes) {
+    walkNodes(child, nextStyle, segments);
+  }
+
+  if (isBlockTag(tag)) {
+    pushText(segments, "\n", nextStyle);
+  }
+}
+
+function styleForElement(node: HTMLElement, style: TextStyle): TextStyle {
+  const tag = node.tagName.toLowerCase();
+  const next = { ...style };
+
+  if (tag === "u" || hasUnderlineStyle(node.getAttribute("style") ?? "")) {
+    next.underline = true;
+  }
+  if (tag === "strong" || tag === "b") {
+    next.bold = true;
+  }
+  if (tag === "em" || tag === "i") {
+    next.italic = true;
+  }
+
+  return next;
+}
+
+function isBlockTag(tag: string): boolean {
+  return tag === "p" || tag === "div" || tag === "li" || /^h[1-6]$/.test(tag);
+}
+
+function hasUnderlineStyle(style: string): boolean {
+  return /text-decoration\s*:\s*[^;"]*underline/i.test(style);
+}
+
+function prepareHtml(html: string): string {
+  return html
+    .replace(/<\s*svg\b([^>]*)>[\s\S]*?<\s*\/\s*svg\s*>/gi, (_match, attrs: string) => mediaLabel("Graph", attrs))
+    .replace(/<\s*img\b([^>]*)>/gi, (_match, attrs: string) => mediaLabel("Image", attrs));
+}
+
+function pushText(segments: TextSegment[], text: string, style: TextStyle): void {
+  if (!text) {
+    return;
+  }
+
+  if (text === "\n") {
+    appendSegment(segments, "\n", style);
+    return;
+  }
+
+  const normalized = decodeEntities(text).replace(/[ \t\r\f\v]+/g, " ");
+  if (!normalized.trim()) {
+    return;
+  }
+
+  appendSegment(segments, normalized, style);
+}
+
+function appendSegment(segments: TextSegment[], text: string, style: TextStyle): void {
+  const last = segments[segments.length - 1];
+  if (last && stylesEqual(last.style, style)) {
+    last.text += text;
+    return;
+  }
+
+  segments.push({ text, style: { ...style } });
+}
+
+function stylesEqual(left: TextStyle, right: TextStyle): boolean {
+  return !!left.bold === !!right.bold && !!left.underline === !!right.underline && !!left.italic === !!right.italic;
+}
+
+function finalizeSegments(segments: TextSegment[]): TextSegment[] {
+  const merged: TextSegment[] = [];
+  for (const segment of segments) {
+    const last = merged[merged.length - 1];
+    if (last && stylesEqual(last.style, segment.style)) {
+      last.text += segment.text;
+    } else {
+      merged.push({ text: segment.text, style: { ...segment.style } });
+    }
+  }
+  return merged;
+}
+
+function mediaLabel(kind: string, attrs: string): string {
+  const label = readAttribute(attrs, "aria-label") ?? readAttribute(attrs, "alt");
+  return label ? `\n[${kind}: ${label}]\n` : `\n[${kind}]\n`;
+}
+
+function readAttribute(attrs: string, name: string): string | undefined {
+  const pattern = new RegExp(`${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i");
+  const match = attrs.match(pattern);
+  return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+
+function normalizeDisplayText(value: string): string {
+  return value
+    .replace(/\u2019/g, "'")
+    .replace(/\u2018/g, "'")
+    .replace(/\u2014/g, "-")
+    .replace(/\u2013/g, "-")
+    .replace(/_{3,}\s*blank\b/gi, "_______");
+}
+
+function normalizeSegmentWhitespace(value: string): string {
+  return value
+    .replace(/[ \t]*\n[ \t]*/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/^\n+/, "\n")
+    .replace(/\n+$/, (match) => (match.length > 1 ? "\n\n" : match));
+}
+
+function trimSegmentEdges(value: string, index: number, total: number): string {
+  let text = value;
+  if (index === 0) {
+    text = text.replace(/^\n+/, "");
+    text = text.replace(/^[ \t]+/, "");
+  }
+  if (index === total - 1) {
+    text = text.replace(/\n+$/, "");
+    text = text.replace(/[ \t]+$/, "");
+  }
+  return text;
+}

package/src/tui/app.ts

@@ -0,0 +1,77 @@
+import { defaultFocus } from "../focus.ts";
+import { ensureStateFiles, loadAttempts, loadFocus } from "../state.ts";
+import { handleKey } from "./input.ts";
+import { createDocument, render } from "./render.ts";
+import { term } from "./terminal.ts";
+import type { AppState, KeyData } from "./types.ts";
+
+export async function runTui(): Promise<void> {
+  const state: AppState = {
+    attempts: new Map(),
+    skippedIds: new Set(),
+    focus: defaultFocus,
+    focusIndex: 1,
+    focusColumn: 0,
+    focusRow: 1,
+    view: "focus",
+    selected: 0,
+    questionScroll: 0,
+    answerScroll: 0,
+    activePane: "answers",
+    elapsedMs: 0,
+    timerPaused: false,
+    timerHidden: false,
+    historyIndex: 0,
+  };
+
+  term.fullscreen(true);
+  term.hideCursor();
+  const doc = createDocument();
+  const tick = setInterval(() => {
+    if (state.view === "practice" && !state.timerPaused) {
+      render(doc, state);
+    }
+  }, 1000);
+
+  const cleanup = () => {
+    clearInterval(tick);
+    doc.destroy();
+    term.grabInput(false);
+    term.hideCursor(false);
+    term.fullscreen(false);
+    term.processExit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  term.on("resize", () => render(doc, state));
+  term.on("key", async (name: string, _matches?: string[], data?: KeyData) => {
+    try {
+      if (name === "CTRL_C" || name === "q") {
+        cleanup();
+        return;
+      }
+
+      await handleKey(state, name, data);
+      render(doc, state);
+    } catch (error) {
+      state.view = "error";
+      state.error = error instanceof Error ? error.message : String(error);
+      render(doc, state);
+    }
+  });
+
+  try {
+    await ensureStateFiles();
+    state.attempts = await loadAttempts();
+    state.focus = await loadFocus();
+    state.focusIndex = 1;
+    state.focusColumn = 0;
+    state.focusRow = 1;
+    state.view = "focus";
+  } catch (error) {
+    state.view = "error";
+    state.error = error instanceof Error ? error.message : String(error);
+  }
+
+  render(doc, state);
+}

package/src/tui/focus-grid.ts

@@ -0,0 +1,113 @@
+import {
+  difficultyLabels,
+  difficultyOptions,
+  domainLabels,
+  domainOptions,
+  skillsForDomain,
+  skillLabels,
+  toggleFocusRow,
+  type FocusRow,
+} from "../focus.ts";
+import type { Domain, Focus, Skill } from "../types.ts";
+
+export type FocusGridRow = Extract<FocusRow, { kind: "option" }>;
+
+export type FocusGridColumn = {
+  id: "difficulty" | Domain;
+  title: string;
+  rows: FocusGridRow[];
+};
+
+export type FocusGridPosition = {
+  column: number;
+  row: number;
+};
+
+export function focusGrid(focus: Focus): FocusGridColumn[] {
+  return [
+    {
+      id: "difficulty",
+      title: "Difficulty",
+      rows: difficultyOptions.map((value) => ({
+        kind: "option",
+        group: "difficulties",
+        value,
+        label: `${value}  ${difficultyLabels[value]}`,
+        checked: focus.difficulties.includes(value),
+        depth: 0,
+      })),
+    },
+    ...domainOptions.map((domain) => domainColumn(domain, focus)),
+  ];
+}
+
+export function normalizeFocusGridPosition(columns: FocusGridColumn[], position: FocusGridPosition): FocusGridPosition {
+  const column = clamp(position.column, 0, Math.max(0, columns.length - 1));
+  const row = clamp(position.row, 0, Math.max(0, (columns[column]?.rows.length ?? 1) - 1));
+  return { column, row };
+}
+
+export function moveFocusGridPosition(
+  columns: FocusGridColumn[],
+  position: FocusGridPosition,
+  direction: "up" | "down" | "next" | "previous",
+): FocusGridPosition {
+  const current = normalizeFocusGridPosition(columns, position);
+
+  if (direction === "up") {
+    return { ...current, row: Math.max(0, current.row - 1) };
+  }
+
+  if (direction === "down") {
+    return { ...current, row: Math.min(columns[current.column].rows.length - 1, current.row + 1) };
+  }
+
+  const delta = direction === "previous" ? -1 : 1;
+  const column = (current.column + delta + columns.length) % columns.length;
+  return normalizeFocusGridPosition(columns, { column, row: current.row });
+}
+
+export function selectedFocusGridRow(focus: Focus, position: FocusGridPosition): FocusGridRow {
+  const columns = focusGrid(focus);
+  const current = normalizeFocusGridPosition(columns, position);
+  return columns[current.column].rows[current.row];
+}
+
+export function toggleFocusGridRow(focus: Focus, position: FocusGridPosition): Focus {
+  return toggleFocusRow(focus, selectedFocusGridRow(focus, position));
+}
+
+function domainColumn(domain: Domain, focus: Focus): FocusGridColumn {
+  const skills = skillsForDomain(domain);
+  const selected = skills.filter((skill) => focus.skills.includes(skill));
+  const checked = selected.length > 0;
+  const partial = checked && selected.length < skills.length;
+
+  return {
+    id: domain,
+    title: `${domain}  ${domainLabels[domain]}`,
+    rows: [
+      {
+        kind: "option",
+        group: "domains",
+        value: domain,
+        label: "All skills",
+        checked,
+        partial,
+        depth: 0,
+      },
+      ...skills.map((skill) => ({
+        kind: "option" as const,
+        group: "skills" as const,
+        value: skill as Skill,
+        label: `${skill}  ${skillLabels[skill]}`,
+        checked: focus.skills.includes(skill),
+        depth: 1,
+      })),
+    ],
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/tui/history.ts

@@ -0,0 +1,6 @@
+import type { Attempt } from "../types.ts";
+import type { AppState } from "./types.ts";
+
+export function historyRows(state: AppState): Attempt[] {
+  return [...state.attempts.values()].sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+}