saterminal 0.2.0 → 0.3.0

package/test/cli.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, test } from "bun:test";
+import { defaultFocus } from "../src/focus.ts";
+import {
+  formatFocus,
+  formatHistory,
+  formatStats,
+  formatWeak,
+  parseArgs,
+} from "../src/cli.ts";
+import { buildSummaryRows, recordAttempt } from "../src/state.ts";
+import type { AttemptEvent, Focus, QuestionMeta } from "../src/types.ts";
+
+describe("cli", () => {
+  test("uses subcommands for report selection and flags for format", () => {
+    expect(parseArgs([])).toEqual({ kind: "tui" });
+    expect(parseArgs(["history"])).toEqual({ kind: "command", command: "history", format: "text" });
+    expect(parseArgs(["history", "-p"])).toEqual({ kind: "command", command: "history", format: "pretty" });
+    expect(parseArgs(["--json", "stats"])).toEqual({ kind: "command", command: "stats", format: "json" });
+    expect(parseArgs(["weak", "--pretty", "--no-color"])).toEqual({ kind: "command", command: "weak", format: "pretty", color: false });
+    expect(parseArgs(["review"])).toEqual({ kind: "review" });
+    expect(parseArgs(["--history"])).toEqual({ kind: "error", message: "Unknown option: --history" });
+  });
+
+  test("rejects conflicting output format flags", () => {
+    expect(parseArgs(["focus", "--json", "--pretty"])).toEqual({
+      kind: "error",
+      message: "Choose either `--pretty` or `--json`, not both.",
+    });
+  });
+
+  test("parses and applies history filters", () => {
+    expect(parseArgs(["history", "--wrong", "--corrected", "--limit", "5", "--since=7d"])).toEqual({
+      kind: "command",
+      command: "history",
+      format: "text",
+      filters: { wrong: true, corrected: true, limit: 5, since: "7d" },
+    });
+    expect(parseArgs(["stats", "--wrong"])).toEqual({
+      kind: "error",
+      message: "History filters only work with `sat history`.",
+    });
+
+    const attempts = new Map();
+    recordAttempt(attempts, "old", false, 10, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "wrong", false, 20, new Date("2026-01-08T00:00:00.000Z"));
+    recordAttempt(attempts, "fixed", false, 30, new Date("2026-01-08T00:00:00.000Z"));
+    recordAttempt(attempts, "fixed", true, 40, new Date("2026-01-09T00:00:00.000Z"));
+
+    expect(JSON.parse(formatHistory([...attempts.values()], "json", { filters: { wrong: true }, now: new Date("2026-01-10T00:00:00.000Z") }))).toEqual([
+      {
+        question_id: "wrong",
+        outcome: "incorrect",
+        updated_at: "2026-01-08T00:00:00.000Z",
+        elapsed_seconds: 20,
+      },
+      {
+        question_id: "old",
+        outcome: "incorrect",
+        updated_at: "2026-01-01T00:00:00.000Z",
+        elapsed_seconds: 10,
+      },
+    ]);
+    expect(JSON.parse(formatHistory([...attempts.values()], "json", {
+      filters: { corrected: true, since: "7d", limit: 1 },
+      now: new Date("2026-01-10T00:00:00.000Z"),
+    }))).toEqual([
+      {
+        question_id: "fixed",
+        outcome: "corrected",
+        updated_at: "2026-01-09T00:00:00.000Z",
+        elapsed_seconds: 40,
+      },
+    ]);
+  });
+
+  test("formats history as sorted JSON and pretty table output", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "older", false, 65, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "newer", true, 5, new Date("2026-01-02T00:00:00.000Z"));
+
+    expect(JSON.parse(formatHistory([...attempts.values()], "json"))).toEqual([
+      {
+        question_id: "newer",
+        outcome: "correct",
+        updated_at: "2026-01-02T00:00:00.000Z",
+        elapsed_seconds: 5,
+      },
+      {
+        question_id: "older",
+        outcome: "incorrect",
+        updated_at: "2026-01-01T00:00:00.000Z",
+        elapsed_seconds: 65,
+      },
+    ]);
+
+    const pretty = formatHistory([...attempts.values()], "pretty");
+    expect(pretty).toContain("\x1b[");
+    expect(stripAnsi(pretty)).toContain("history\n2 attempts  1 mastered  1 needs review");
+    expect(stripAnsi(pretty)).toContain("newer");
+    expect(stripAnsi(pretty)).toContain("correct");
+    expect(stripAnsi(pretty)).toContain("1:05");
+  });
+
+  test("formats stats with numeric JSON and human percentages", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "a", true, 20, new Date("2026-01-01T00:00:00.000Z"));
+    recordAttempt(attempts, "b", false, 40, new Date("2026-01-01T00:00:00.000Z"));
+    const rows = buildSummaryRows(attempts, new Date("2026-01-02T00:00:00.000Z"));
+
+    expect(JSON.parse(formatStats(rows, "json"))).toEqual({
+      answered: 2,
+      correct: 1,
+      incorrect: 1,
+      corrected: 0,
+      accuracy: 0.5,
+      avg_seconds: 30,
+    });
+    const pretty = formatStats(rows, "pretty");
+    expect(pretty).toContain("\x1b[");
+    expect(stripAnsi(pretty)).toContain("stats\n2 answered  50% accuracy  0:30 avg");
+    expect(stripAnsi(pretty)).toContain("correct     1");
+    expect(stripAnsi(pretty)).toContain("incorrect   1");
+    expect(pretty).toContain("\x1b[42m            \x1b[0m\x1b[100m            \x1b[0m");
+    expect(stripAnsi(pretty)).not.toContain("#");
+    expect(stripAnsi(pretty)).not.toContain("░");
+    expect(formatStats(rows, "text")).toContain("avg seconds  30.0s");
+
+    const noColor = formatStats(rows, "pretty", { color: false });
+    expect(noColor).not.toContain("\x1b[");
+    expect(noColor).toContain("[████████████            ]");
+  });
+
+  test("formats stats with streak and activity when events are available", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "a", true, 20, new Date("2026-01-09T12:00:00"));
+    const rows = buildSummaryRows(attempts, new Date("2026-01-10T12:00:00"));
+    const events: AttemptEvent[] = [
+      attemptEvent("a", true, "2026-01-08T12:00:00"),
+      attemptEvent("b", false, "2026-01-09T12:00:00"),
+    ];
+
+    expect(JSON.parse(formatStats(rows, "json", { events, now: new Date("2026-01-10T12:00:00") })).activity).toMatchObject({
+      streak: 2,
+      activeDays: 2,
+      todayCount: 0,
+      totalEvents: 2,
+    });
+
+    const rawPretty = formatStats(rows, "pretty", { events, now: new Date("2026-01-10T12:00:00") });
+    const pretty = stripAnsi(rawPretty);
+    expect(pretty).toContain("2 day streak");
+    expect(pretty).toContain("activity\nlast 12 weeks");
+    expect(pretty).toContain("Mon");
+    expect(pretty).toContain("Wed");
+    expect(pretty).toContain("Fri");
+    expect(pretty).toContain("Oct");
+    expect(pretty).toContain("Jan");
+    expect(rawPretty).toContain("\x1b[38;5;238m■\x1b[0m");
+    expect(rawPretty).toContain("\x1b[38;5;22m■\x1b[0m");
+    expect(rawPretty).not.toContain("·");
+  });
+
+  test("formats focus as raw selections or labeled pretty output", () => {
+    const focus: Focus = { difficulties: ["H"], domains: ["CAS"], skills: ["WIC"] };
+
+    expect(formatFocus(focus, "json")).toBe(JSON.stringify(focus));
+    expect(formatFocus(focus, "text")).toBe("difficulties: H\ndomains: CAS\nskills: WIC");
+    expect(formatFocus(focus, "pretty")).toContain("\x1b[");
+    expect(stripAnsi(formatFocus(focus, "pretty"))).toContain("H   Hard");
+    expect(stripAnsi(formatFocus(defaultFocus, "pretty"))).toContain("10 skills");
+  });
+
+  test("formats weak spots from metadata-backed attempts", () => {
+    const attempts = new Map();
+    recordAttempt(attempts, "wic1", false, 50, new Date("2026-01-01T00:00:00.000Z"), sampleMeta);
+    recordAttempt(
+      attempts,
+      "ctc1",
+      true,
+      20,
+      new Date("2026-01-02T00:00:00.000Z"),
+      { ...sampleMeta, questionId: "ctc1", skill_cd: "CTC", skill_desc: "Cross-Text Connections" },
+    );
+
+    expect(JSON.parse(formatWeak([...attempts.values()], "json"))[0]).toMatchObject({
+      skill: "WIC",
+      missed: 1,
+      total: 1,
+      accuracy: 0,
+    });
+    expect(formatWeak([...attempts.values()], "text")).toContain("WIC    0%");
+    expect(stripAnsi(formatWeak([...attempts.values()], "pretty"))).toContain("weak spots\nWIC has 1 misses");
+  });
+});
+
+function stripAnsi(value: string): string {
+  return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function attemptEvent(questionId: string, correct: boolean, answeredAt: string): AttemptEvent {
+  return {
+    question_id: questionId,
+    correct,
+    answered_at: answeredAt,
+    elapsed_seconds: 20,
+    difficulty: "M",
+    domain: "CAS",
+    domain_desc: "Craft and Structure",
+    skill: "WIC",
+    skill_desc: "Words in Context",
+  };
+}
+
+const sampleMeta: QuestionMeta = {
+  questionId: "wic1",
+  uId: "wic1",
+  external_id: "external-1",
+  difficulty: "M",
+  primary_class_cd: "CAS",
+  primary_class_cd_desc: "Craft and Structure",
+  skill_cd: "WIC",
+  skill_desc: "Words in Context",
+};

package/test/frame.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { Frame, FrameRenderer, type FrameOutput, type TextAttr } from "../src/tui/frame.ts";
+
+class RecordingOutput implements FrameOutput {
+  ops: string[] = [];
+
+  clear(): void {
+    this.ops.push("clear");
+  }
+
+  moveTo(x: number, y: number): void {
+    this.ops.push(`move:${x},${y}`);
+  }
+
+  eraseLineAfter(): void {
+    this.ops.push("erase");
+  }
+
+  reset(): void {
+    this.ops.push("reset");
+  }
+
+  write(value: string, attr: TextAttr = {}): void {
+    const color = typeof attr.color === "string" ? attr.color : "default";
+    const bold = attr.bold ? ":bold" : "";
+    this.ops.push(`write:${color}${bold}:${value}`);
+  }
+}
+
+describe("frame renderer", () => {
+  test("clips and truncates writes inside frame bounds", () => {
+    const frame = new Frame(6, 2);
+
+    frame.writeText(2, 0, "abcdef", { color: "cyan" }, 4);
+    frame.writeText(-1, 1, "xyz", { color: "red" });
+    frame.writeText(0, 5, "ignored");
+
+    expect(frame.rowRuns(0)).toEqual([{ x: 2, text: "abc…", attr: { color: "cyan" } }]);
+    expect(frame.rowRuns(1)).toEqual([{ x: 0, text: "yz", attr: { color: "red" } }]);
+  });
+
+  test("emits no operations when the next frame is unchanged", () => {
+    const output = new RecordingOutput();
+    const renderer = new FrameRenderer(output);
+    const frame = new Frame(10, 3);
+    frame.writeText(0, 0, "sat", { bold: true });
+
+    renderer.draw(frame);
+    output.ops = [];
+    renderer.draw(frame);
+
+    expect(output.ops).toEqual([]);
+  });
+
+  test("only repaints rows whose rendered content changed", () => {
+    const output = new RecordingOutput();
+    const renderer = new FrameRenderer(output);
+    const first = new Frame(20, 3);
+    first.writeText(0, 0, "sat", { bold: true });
+    first.writeText(0, 1, "----------", { color: "gray" });
+    renderer.draw(first);
+
+    output.ops = [];
+    const second = new Frame(20, 3);
+    second.writeText(0, 0, "sat", { bold: true });
+    second.writeText(0, 1, "----------", { color: "gray" });
+    second.writeText(7, 0, "time 0:02", { color: "gray" });
+    renderer.draw(second);
+
+    expect(output.ops).toEqual([
+      "move:1,1",
+      "reset",
+      "erase",
+      "move:1,1",
+      "write:default:bold:sat",
+      "move:8,1",
+      "write:gray:time 0:02",
+      "reset",
+    ]);
+  });
+
+  test("clears a row when content is removed", () => {
+    const output = new RecordingOutput();
+    const renderer = new FrameRenderer(output);
+    const first = new Frame(20, 2);
+    first.writeText(0, 0, "temporary");
+    renderer.draw(first);
+
+    output.ops = [];
+    renderer.draw(new Frame(20, 2));
+
+    expect(output.ops).toEqual(["move:1,1", "reset", "erase", "reset"]);
+  });
+});

package/test/progress.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { progressBarText } from "../src/progress.ts";
+
+describe("progress", () => {
+  test("renders a block progress bar with empty cells", () => {
+    expect(progressBarText(0.5, 8)).toBe("████    ");
+  });
+
+  test("uses partial block cells for fractional progress", () => {
+    expect(progressBarText(0.3125, 8)).toBe("██▌     ");
+  });
+
+  test("clamps invalid ratios", () => {
+    expect(progressBarText(-1, 4)).toBe("    ");
+    expect(progressBarText(2, 4)).toBe("████");
+    expect(progressBarText(Number.NaN, 4)).toBe("    ");
+  });
+});

package/test/state.test.ts

@@ -6,6 +6,8 @@ import { defaultFocus, normalizeFocus } from "../src/focus.ts";
 import {
   buildSummaryRows,
   displayStateDir,
+  appendAttemptEvent,
+  loadAttemptEvents,
   loadAttempts,
   loadFocus,
   nextOutcome,
@@ -15,6 +17,7 @@ import {
   saveFocus,
   stateDirExists,
 } from "../src/state.ts";
+import type { QuestionMeta } from "../src/types.ts";
 
 describe("state", () => {
   test("resolves state dir under the user home directory", () => {
@@ -43,12 +46,16 @@ describe("state", () => {
 
     try {
       const attempts = await loadAttempts(path);
-      recordAttempt(attempts, "abc12345", false, 42, new Date("2026-01-01T00:00:00.000Z"));
+      recordAttempt(attempts, "abc12345", false, 42, new Date("2026-01-01T00:00:00.000Z"), sampleMeta);
       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",
+        [
+          "question_id,outcome,updated_at,elapsed_seconds,difficulty,domain,domain_desc,skill,skill_desc",
+          "abc12345,incorrect,2026-01-01T00:00:00.000Z,42,H,CAS,Craft and Structure,WIC,Words in Context",
+          "",
+        ].join("\n"),
       );
       expect(await loadAttempts(path)).toEqual(attempts);
     } finally {
@@ -71,7 +78,11 @@ describe("state", () => {
     try {
       await writeFile(
         path,
-        "question_id,outcome,updated_at,elapsed_seconds\n\"abc,123\",correct,\"2026-01-01T00:00:00.000Z\",12\n",
+        [
+          "question_id,outcome,updated_at,elapsed_seconds,difficulty,domain,domain_desc,skill,skill_desc",
+          "\"abc,123\",correct,\"2026-01-01T00:00:00.000Z\",12,M,INI,\"Information, Ideas\",CID,Central Ideas",
+          "",
+        ].join("\n"),
         "utf8",
       );
 
@@ -81,6 +92,11 @@ describe("state", () => {
           outcome: "correct",
           updated_at: "2026-01-01T00:00:00.000Z",
           elapsed_seconds: 12,
+          difficulty: "M",
+          domain: "INI",
+          domain_desc: "Information, Ideas",
+          skill: "CID",
+          skill_desc: "Central Ideas",
         }],
       ]));
     } finally {
@@ -110,6 +126,49 @@ describe("state", () => {
     });
   });
 
+  test("appends and loads attempt events", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "events.csv");
+
+    try {
+      await appendAttemptEvent(sampleMeta, true, 31, new Date("2026-01-01T12:00:00.000Z"), path);
+      await appendAttemptEvent(
+        { ...sampleMeta, questionId: "def67890", skill_cd: "CTC", skill_desc: "Cross-Text Connections" },
+        false,
+        44,
+        new Date("2026-01-02T12:00:00.000Z"),
+        path,
+      );
+
+      expect(await loadAttemptEvents(path)).toEqual([
+        {
+          question_id: "abc12345",
+          correct: true,
+          answered_at: "2026-01-01T12:00:00.000Z",
+          elapsed_seconds: 31,
+          difficulty: "H",
+          domain: "CAS",
+          domain_desc: "Craft and Structure",
+          skill: "WIC",
+          skill_desc: "Words in Context",
+        },
+        {
+          question_id: "def67890",
+          correct: false,
+          answered_at: "2026-01-02T12:00:00.000Z",
+          elapsed_seconds: 44,
+          difficulty: "H",
+          domain: "CAS",
+          domain_desc: "Craft and Structure",
+          skill: "CTC",
+          skill_desc: "Cross-Text Connections",
+        },
+      ]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("normalizes invalid focus selections to valid defaults", () => {
     expect(normalizeFocus({ difficulties: [], domains: ["NOPE"], skills: ["CID"] })).toEqual({
       difficulties: defaultFocus.difficulties,
@@ -165,3 +224,14 @@ describe("state", () => {
     }
   });
 });
+
+const sampleMeta: QuestionMeta = {
+  questionId: "abc12345",
+  uId: "abc12345",
+  external_id: "external-1",
+  difficulty: "H",
+  primary_class_cd: "CAS",
+  primary_class_cd_desc: "Craft and Structure",
+  skill_cd: "WIC",
+  skill_desc: "Words in Context",
+};

package/src/tui/terminal.ts

@@ -1,110 +0,0 @@
-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;
-  }
-}