saterminal 0.1.0

package/src/tui/terminal.ts

@@ -0,0 +1,110 @@
+import { wrapText } from "../text.ts";
+import type { TextSegment } from "../text.ts";
+import { term, gutter, terminalSize } from "./kit.ts";
+
+export { term, gutter, terminalSize, contentBounds } from "./kit.ts";
+
+export function line(y: number, value: string): void {
+  term.moveTo(1, y)(value.slice(0, term.width - 1));
+}
+
+export function lineAt(x: number, y: number, width: number, value: string): void {
+  term.moveTo(x, y)(value.slice(0, width));
+}
+
+export function lineAtColor(
+  x: number,
+  y: number,
+  width: number,
+  value: string,
+  color: "cyan" | "green" | "red" | "yellow",
+  bold = false,
+): void {
+  const output = value.slice(0, width);
+  if (bold) {
+    term.moveTo(x, y).bold[color](output);
+  } else {
+    term.moveTo(x, y)[color](output);
+  }
+}
+
+export function paneLayout(): {
+  leftX: number;
+  leftWidth: number;
+  rightX: number;
+  rightWidth: number;
+} {
+  const { width } = terminalSize();
+  const usable = Math.max(40, width - gutter);
+  const leftWidth = Math.max(20, Math.floor(usable / 2));
+  const rightX = leftWidth + gutter + 1;
+  const rightWidth = Math.max(20, width - rightX);
+
+  return {
+    leftX: 1,
+    leftWidth,
+    rightX,
+    rightWidth,
+  };
+}
+
+export function printWrapped(value: string | undefined, y: number, maxY: number, bold = false): number {
+  return printWrappedAt(value, 1, y, terminalSize().width - 4, maxY, bold);
+}
+
+export function printWrappedAt(
+  value: string | undefined,
+  x: number,
+  y: number,
+  width: number,
+  maxY: number,
+  bold = false,
+): number {
+  for (const row of wrapText(value ?? "", width)) {
+    if (y > maxY) {
+      lineAt(x, y, width, "...");
+      return y + 1;
+    }
+    if (bold) {
+      term.moveTo(x, y++).bold(row.slice(0, width));
+    } else {
+      lineAt(x, y++, width, row);
+    }
+  }
+
+  return y;
+}
+
+export function renderStyledLine(
+  x: number,
+  y: number,
+  width: number,
+  segments: TextSegment[],
+  forceBold = false,
+): void {
+  let col = 0;
+
+  for (const segment of segments) {
+    if (col >= width) {
+      break;
+    }
+
+    const text = segment.text.slice(0, width - col);
+    if (!text) {
+      continue;
+    }
+
+    const bold = forceBold || segment.style.bold;
+    const underline = segment.style.underline;
+    let output = term.moveTo(x + col, y);
+    if (bold && underline) {
+      output = output.bold.underline;
+    } else if (bold) {
+      output = output.bold;
+    } else if (underline) {
+      output = output.underline;
+    }
+    output(text);
+    col += text.length;
+  }
+}

package/src/tui/timer.ts

@@ -0,0 +1,43 @@
+import type { AppState } from "./types.ts";
+
+export function toggleTimer(state: AppState): void {
+  if (state.timerPaused) {
+    resumeTimer(state);
+  } else {
+    pauseTimer(state);
+  }
+}
+
+export function pauseTimer(state: AppState): void {
+  if (state.timerPaused || state.timerStartedAt === undefined) {
+    return;
+  }
+
+  state.elapsedMs += Date.now() - state.timerStartedAt;
+  state.timerStartedAt = undefined;
+  state.timerPaused = true;
+}
+
+export function resumeTimer(state: AppState): void {
+  if (!state.timerPaused || state.view !== "practice") {
+    return;
+  }
+
+  state.timerStartedAt = Date.now();
+  state.timerPaused = false;
+}
+
+export function elapsedQuestionSeconds(state: AppState): number {
+  const activeMs = state.timerPaused || state.timerStartedAt === undefined ? 0 : Date.now() - state.timerStartedAt;
+  return Math.max(0, Math.round((state.elapsedMs + activeMs) / 1000));
+}
+
+export function formatElapsed(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}:${String(remainingSeconds).padStart(2, "0")}`;
+}
+
+export function timerStatus(state: AppState): string {
+  return state.view === "practice" && state.timerPaused ? " paused" : "";
+}

package/src/tui/types.ts

@@ -0,0 +1,48 @@
+import type { Attempt, Focus, PracticeQuestion } from "../types.ts";
+import type { TextSegment } from "../text.ts";
+import type { PaneId } from "./viewport.ts";
+
+export type View = "focus" | "loading" | "practice" | "review" | "history" | "summary" | "detail" | "error";
+
+export type AppState = {
+  attempts: Map<string, Attempt>;
+  skippedIds: Set<string>;
+  nextQuestion?: Promise<PracticeQuestion | undefined>;
+  focus: Focus;
+  focusIndex: number;
+  focusColumn: number;
+  focusRow: number;
+  view: View;
+  question?: PracticeQuestion;
+  selected: number;
+  questionScroll: number;
+  answerScroll: number;
+  activePane: PaneId;
+  elapsedMs: number;
+  timerStartedAt?: number;
+  timerPaused: boolean;
+  timerHidden: boolean;
+  lastAnswer?: string;
+  lastCorrect?: boolean;
+  detailQuestion?: PracticeQuestion;
+  historyIndex: number;
+  error?: string;
+};
+
+export type KeyData = {
+  code?: string | Buffer | number;
+  codepoint?: number;
+  isCharacter?: boolean;
+};
+
+export type DisplayRow = {
+  segments: TextSegment[];
+  bold?: boolean;
+};
+
+export type PaneLayout = {
+  leftX: number;
+  leftWidth: number;
+  rightX: number;
+  rightWidth: number;
+};

package/src/tui/viewport.ts

@@ -0,0 +1,60 @@
+export type PaneId = "question" | "answers";
+
+export type PaneViewport = {
+  scroll: number;
+  height: number;
+  contentRows: number;
+};
+
+export function alternatePane(pane: PaneId): PaneId {
+  return pane === "question" ? "answers" : "question";
+}
+
+export function maxScroll(viewport: PaneViewport): number {
+  return Math.max(0, viewport.contentRows - viewport.height);
+}
+
+export function clampScroll(viewport: PaneViewport): number {
+  return Math.max(0, Math.min(viewport.scroll, maxScroll(viewport)));
+}
+
+export function scrollBy(viewport: PaneViewport, delta: number): number {
+  return clampScroll({ ...viewport, scroll: viewport.scroll + delta });
+}
+
+export function scrollPage(viewport: PaneViewport, direction: 1 | -1): number {
+  return scrollBy(viewport, direction * Math.max(1, viewport.height - 1));
+}
+
+export function scrollToEdge(viewport: PaneViewport, edge: "top" | "bottom"): number {
+  return edge === "top" ? 0 : maxScroll(viewport);
+}
+
+export function ensureRowVisible(viewport: PaneViewport, row: number): number {
+  const scroll = clampScroll(viewport);
+  if (row < scroll) {
+    return clampScroll({ ...viewport, scroll: row });
+  }
+
+  const lastVisible = scroll + viewport.height - 1;
+  if (row > lastVisible) {
+    return clampScroll({ ...viewport, scroll: row - viewport.height + 1 });
+  }
+
+  return scroll;
+}
+
+export function ensureRangeVisible(viewport: PaneViewport, start: number, end: number): number {
+  const scroll = clampScroll(viewport);
+  const lastVisible = scroll + viewport.height - 1;
+
+  if (start < scroll) {
+    return clampScroll({ ...viewport, scroll: start });
+  }
+
+  if (end > lastVisible) {
+    return clampScroll({ ...viewport, scroll: end - viewport.height + 1 });
+  }
+
+  return scroll;
+}

package/src/tui.ts

@@ -0,0 +1 @@
+export { runTui } from "./tui/app.ts";

package/src/types/terminal-kit.d.ts

@@ -0,0 +1,118 @@
+declare module "terminal-kit" {
+  type KeyData = {
+    code?: string | Buffer | number;
+    codepoint?: number;
+    isCharacter?: boolean;
+  };
+
+  export type Terminal = {
+    width: number;
+    height: number;
+    clear(): Terminal;
+    moveTo(x: number, y: number): Terminal;
+    bold: Terminal & Record<string, Terminal>;
+    gray: Terminal;
+    cyan: Terminal;
+    green: Terminal;
+    red: Terminal;
+    yellow: Terminal;
+    underline: Terminal;
+    inverse: Terminal;
+    defaultColor: Terminal;
+    fullscreen(enabled: boolean): void;
+    hideCursor(enabled?: boolean): void;
+    grabInput(enabled?: boolean): void;
+    processExit(code: number): void;
+    on(event: "key", listener: (name: string, matches?: string[], data?: KeyData) => void): void;
+    on(event: "resize", listener: (width: number, height: number) => void): void;
+    off(event: "resize", listener: (width: number, height: number) => void): void;
+    (value: string): void;
+  };
+
+  export type DocumentOptions = {
+    inlineTerm?: Terminal;
+    eventSource?: Terminal;
+    outputDst?: Terminal;
+    outputX?: number;
+    outputY?: number;
+    outputWidth?: number;
+    outputHeight?: number;
+    backgroundAttr?: Record<string, unknown>;
+    noInput?: boolean;
+  };
+
+  export type MenuItem = {
+    content: string;
+    value: string;
+    disabled?: boolean;
+  };
+
+  export type ColumnMenuMultiOptions = {
+    parent?: unknown;
+    id?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    items?: MenuItem[];
+    value?: Record<string, boolean>;
+    multiLineItems?: boolean;
+    master?: MenuItem;
+  };
+
+  export type WindowOptions = {
+    parent?: unknown;
+    title?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+  };
+
+  export type TextOptions = {
+    parent?: unknown;
+    content?: string | string[];
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    attr?: Record<string, unknown>;
+    contentHasMarkup?: boolean | "ansi" | "legacyAnsi";
+    noDraw?: boolean;
+  };
+
+  export class Document {
+    constructor(options: DocumentOptions);
+    clear(): void;
+    draw(): void;
+    destroy(): void;
+    focusNext(): void;
+    giveFocusTo(element: unknown, type?: string): void;
+    on(event: "key", listener: (key: string) => void): void;
+  }
+
+  export class ColumnMenuMulti {
+    constructor(options: ColumnMenuMultiOptions);
+    value: Record<string, boolean>;
+    setValue(value: Record<string, boolean>, noDraw?: boolean): void;
+    on(event: "itemToggle", listener: (key: string, enabled: boolean) => void): void;
+    on(event: "submit", listener: (...args: unknown[]) => void): void;
+  }
+
+  export class Window {
+    constructor(options: WindowOptions);
+  }
+
+  export class Text {
+    constructor(options: TextOptions);
+  }
+
+  const terminalKit: {
+    terminal: Terminal;
+    Document: typeof Document;
+    ColumnMenuMulti: typeof ColumnMenuMulti;
+    Window: typeof Window;
+    Text: typeof Text;
+  };
+
+  export default terminalKit;
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export type Outcome = "correct" | "incorrect" | "corrected";
+
+export type Attempt = {
+  question_id: string;
+  outcome: Outcome;
+  updated_at: string;
+  elapsed_seconds: number;
+};
+
+export type SummaryRow = {
+  metric: string;
+  value: string;
+  updated_at: string;
+};
+
+export type Difficulty = "E" | "M" | "H";
+export type Domain = "INI" | "CAS" | "EOI" | "SEC";
+export type Skill = "CID" | "INF" | "COE" | "WIC" | "TSP" | "CTC" | "SYN" | "TRA" | "BOU" | "FSS";
+
+export type Focus = {
+  difficulties: Difficulty[];
+  domains: Domain[];
+  skills: Skill[];
+};
+
+export type QuestionMeta = {
+  questionId: string;
+  uId: string;
+  external_id: string;
+  difficulty: string;
+  primary_class_cd: string;
+  primary_class_cd_desc?: string;
+  program?: string;
+  skill_cd: string;
+  skill_desc?: string;
+  score_band_range_cd?: number;
+};
+
+export type QuestionDetail = {
+  externalid: string;
+  type: string;
+  stimulus?: string;
+  stem: string;
+  answerOptions: Record<string, string>;
+  correct_answer: string[];
+  rationale?: string;
+};
+
+export type PracticeQuestion = {
+  meta: QuestionMeta;
+  detail: QuestionDetail;
+};

package/test/api.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { fetchQuestionBank } from "../src/api.ts";
+
+describe("api", () => {
+  test("passes excluded short question ids to the question bank endpoint", async () => {
+    const originalFetch = globalThis.fetch;
+    let requested = "";
+    globalThis.fetch = ((input: RequestInfo | URL) => {
+      requested = String(input);
+      return Promise.resolve(
+        new Response(JSON.stringify({ success: true, data: [] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+      );
+    }) as typeof fetch;
+
+    try {
+      await fetchQuestionBank(["a", "b"]);
+      expect(requested).toContain("assessment=SAT");
+      expect(requested).toContain("excludeIds=a%2Cb");
+      expect(requested).toContain("difficulties=M%2CH");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("passes focus filters to the question bank endpoint", async () => {
+    const originalFetch = globalThis.fetch;
+    let requested = "";
+    globalThis.fetch = ((input: RequestInfo | URL) => {
+      requested = String(input);
+      return Promise.resolve(
+        new Response(JSON.stringify({ success: true, data: [] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+      );
+    }) as typeof fetch;
+
+    try {
+      await fetchQuestionBank([], {
+        difficulties: ["H"],
+        domains: ["SEC"],
+        skills: ["BOU", "FSS"],
+      });
+      expect(requested).toContain("difficulties=H");
+      expect(requested).toContain("domains=SEC");
+      expect(requested).toContain("skills=BOU%2CFSS");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("derives domain filters from selected skill filters", async () => {
+    const originalFetch = globalThis.fetch;
+    let requested = "";
+    globalThis.fetch = ((input: RequestInfo | URL) => {
+      requested = String(input);
+      return Promise.resolve(
+        new Response(JSON.stringify({ success: true, data: [] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+      );
+    }) as typeof fetch;
+
+    try {
+      await fetchQuestionBank([], {
+        difficulties: ["H"],
+        domains: ["INI"],
+        skills: ["WIC"],
+      });
+      expect(requested).toContain("domains=CAS");
+      expect(requested).toContain("skills=WIC");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});

package/test/focus.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { focusRows, toggleFocusRow } from "../src/focus.ts";
+import { focusGrid, moveFocusGridPosition, toggleFocusGridRow } from "../src/tui/focus-grid.ts";
+import type { Focus } from "../src/types.ts";
+
+describe("focus", () => {
+  test("renders skills as nested domain children", () => {
+    const rows = focusRows({ difficulties: ["H"], domains: ["CAS"], skills: ["WIC"] });
+    const cas = rows.find((row) => row.kind === "option" && row.value === "CAS");
+    const wic = rows.find((row) => row.kind === "option" && row.value === "WIC");
+
+    expect(cas).toMatchObject({ kind: "option", checked: true, partial: true, depth: 0 });
+    expect(wic).toMatchObject({ kind: "option", checked: true, depth: 1 });
+  });
+
+  test("domain toggles operate on their child skills", () => {
+    const focus: Focus = { difficulties: ["H"], domains: ["CAS"], skills: ["WIC"] };
+    const cas = focusRows(focus).find((row) => row.kind === "option" && row.value === "CAS");
+
+    expect(toggleFocusRow(focus, cas)).toEqual({
+      difficulties: ["H"],
+      domains: ["CAS"],
+      skills: ["WIC", "TSP", "CTC"],
+    });
+  });
+
+  test("grid navigation moves predictably across columns and rows", () => {
+    const focus: Focus = { difficulties: ["H"], domains: ["CAS"], skills: ["WIC"] };
+    const columns = focusGrid(focus);
+
+    expect(moveFocusGridPosition(columns, { column: 0, row: 1 }, "down")).toEqual({ column: 0, row: 2 });
+    expect(moveFocusGridPosition(columns, { column: 0, row: 2 }, "down")).toEqual({ column: 0, row: 2 });
+    expect(moveFocusGridPosition(columns, { column: 0, row: 2 }, "next")).toEqual({ column: 1, row: 2 });
+    expect(moveFocusGridPosition(columns, { column: 0, row: 2 }, "previous")).toEqual({ column: 4, row: 2 });
+  });
+
+  test("grid navigation clamps row when moving into shorter columns", () => {
+    const focus: Focus = { difficulties: ["H"], domains: ["INI"], skills: ["CID", "INF", "COE"] };
+    const columns = focusGrid(focus);
+
+    expect(moveFocusGridPosition(columns, { column: 1, row: 3 }, "next")).toEqual({ column: 2, row: 3 });
+    expect(moveFocusGridPosition(columns, { column: 2, row: 3 }, "next")).toEqual({ column: 3, row: 2 });
+  });
+
+  test("grid toggles use focus constraints", () => {
+    const focus: Focus = { difficulties: ["H"], domains: ["CAS"], skills: ["WIC"] };
+
+    expect(toggleFocusGridRow(focus, { column: 0, row: 2 })).toBe(focus);
+    expect(toggleFocusGridRow(focus, { column: 2, row: 0 })).toEqual({
+      difficulties: ["H"],
+      domains: ["CAS"],
+      skills: ["WIC", "TSP", "CTC"],
+    });
+  });
+});

package/test/state.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultFocus, normalizeFocus } from "../src/focus.ts";
+import {
+  buildSummaryRows,
+  loadAttempts,
+  loadFocus,
+  nextOutcome,
+  recordAttempt,
+  saveAttempts,
+  saveFocus,
+} from "../src/state.ts";
+
+describe("state", () => {
+  test("creates and reads a compact attempts csv", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "attempts.csv");
+
+    try {
+      const attempts = await loadAttempts(path);
+      recordAttempt(attempts, "abc12345", false, 42, new Date("2026-01-01T00:00:00.000Z"));
+      await saveAttempts(attempts, path);
+
+      const raw = await readFile(path, "utf8");
+      expect(raw).toBe(
+        "question_id,outcome,updated_at,elapsed_seconds\nabc12345,incorrect,2026-01-01T00:00:00.000Z,42\n",
+      );
+      expect(await loadAttempts(path)).toEqual(attempts);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("uses corrected for a later right answer after a miss", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "abc12345", false, 12, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "abc12345", true, 10, new Date("2026-01-02T00:00:00.000Z"));
+
+    expect(attempts.get("abc12345")?.outcome).toBe("corrected");
+  });
+
+  test("loads escaped csv fields", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "attempts.csv");
+
+    try {
+      await writeFile(
+        path,
+        "question_id,outcome,updated_at,elapsed_seconds\n\"abc,123\",correct,\"2026-01-01T00:00:00.000Z\",12\n",
+        "utf8",
+      );
+
+      expect(await loadAttempts(path)).toEqual(new Map([
+        ["abc,123", {
+          question_id: "abc,123",
+          outcome: "correct",
+          updated_at: "2026-01-01T00:00:00.000Z",
+          elapsed_seconds: 12,
+        }],
+      ]));
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("does not downgrade mastered outcomes", () => {
+    expect(nextOutcome("correct", false)).toBe("correct");
+    expect(nextOutcome("corrected", false)).toBe("corrected");
+  });
+
+  test("builds summary rows from attempts", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "a", true, 20, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "b", false, 10, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "b", true, 40, new Date("2026-01-02T00:00:00.000Z"));
+
+    const rows = buildSummaryRows(attempts, new Date("2026-01-03T00:00:00.000Z"));
+    expect(Object.fromEntries(rows.map((row) => [row.metric, row.value]))).toEqual({
+      answered: "2",
+      correct: "1",
+      incorrect: "0",
+      corrected: "1",
+      accuracy: "1.00",
+      avg_seconds: "30.0",
+    });
+  });
+
+  test("normalizes invalid focus selections to valid defaults", () => {
+    expect(normalizeFocus({ difficulties: [], domains: ["NOPE"], skills: ["CID"] })).toEqual({
+      difficulties: defaultFocus.difficulties,
+      domains: ["INI"],
+      skills: ["CID"],
+    });
+  });
+
+  test("derives focus domains from selected skills", () => {
+    expect(normalizeFocus({ difficulties: ["H"], domains: ["INI"], skills: ["WIC"] })).toEqual({
+      difficulties: ["H"],
+      domains: ["CAS"],
+      skills: ["WIC"],
+    });
+  });
+
+  test("saves and loads focus json", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "focus.json");
+
+    try {
+      await saveFocus({ difficulties: ["H"], domains: ["SEC"], skills: ["BOU", "FSS"] }, path);
+      expect(await loadFocus(path)).toEqual({ difficulties: ["H"], domains: ["SEC"], skills: ["BOU", "FSS"] });
+
+      await writeFile(path, "{\"difficulties\":[],\"domains\":[],\"skills\":[]}", "utf8");
+      expect(await loadFocus(path)).toEqual(defaultFocus);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});