saterminal 0.3.1 → 0.4.0

package/README.md

@@ -3,3 +3,19 @@ why?
 - i don't like how the official SAT question bank forces u to download PDFs
 - official SAT question bank + other third party question readers display the question difficulty and other metadata (their UIs are also quite chopped)
 - used to use oneprep until i heard they started AI-generating questions, sooo...
+
+usage
+
+```sh
+sat
+```
+
+The package ships `data/question-bank.json.zst` as the initial bank. On first use, Sat materializes it into a plain JSON cache at `~/.saterminal/userlocal/cache/question-bank.json` so regular practice reads directly from local JSON.
+
+maintainers
+
+```sh
+bun run update-bank
+```
+
+This refreshes `data/question-bank.json.zst` from Practice SAT for the next package release.

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "saterminal",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "sat": "src/main.ts"
   },
   "files": [
+    "data",
     "src"
   ],
   "scripts": {
     "dev": "bun run src/main.ts",
     "start": "bun run src/main.ts",
+    "update-bank": "bun run scripts/update-question-bank.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
@@ -24,6 +26,7 @@
     "@types/bun": "^1.2.22",
     "@types/he": "^1.2.3",
     "@types/word-wrap": "^1.2.1",
+    "p-limit": "^7.3.0",
     "typescript": "^5.9.3"
   }
 }

package/src/cli.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { difficultyLabels, domainLabels, focusSummary, skillLabels } from "./focus.ts";
 import { progressBarText } from "./progress.ts";
 import { buildSummaryRows, loadAttemptEvents, loadAttempts, loadFocus } from "./state.ts";
@@ -16,6 +17,7 @@ export type HistoryFilters = {
 export type ParsedCli =
   | { kind: "tui" }
   | { kind: "review" }
+  | { kind: "version" }
   | { kind: "help" }
   | { kind: "error"; message: string }
   | {
@@ -107,6 +109,10 @@ export function parseArgs(args: string[]): ParsedCli {
       return { kind: "help" };
     }
 
+    if (arg === "-V" || arg === "--version") {
+      return { kind: "version" };
+    }
+
     if (arg === "-p" || arg === "--pretty") {
       pretty = true;
       continue;
@@ -222,6 +228,11 @@ export async function runCliCommand(
     return 0;
   }
 
+  if (parsed.kind === "version") {
+    stdout.write(`sat ${await packageVersion()}\n`);
+    return 0;
+  }
+
   if (parsed.kind === "error") {
     stderr.write(`${parsed.message}\n\n${helpText()}\n`);
     return 1;
@@ -392,12 +403,19 @@ export function helpText(): string {
     "  -p, --pretty    Use colorized human-readable output",
     "      --json      Output JSON",
     "      --no-color  Disable ANSI color in pretty output",
+    "  -V, --version   Show version",
     "  -h, --help      Show this help",
     "",
     "Run `sat` with no command to open the interactive TUI.",
   ].join("\n");
 }
 
+async function packageVersion(): Promise<string> {
+  const packageJson = await readFile(new URL("../package.json", import.meta.url), "utf8");
+  const parsed = JSON.parse(packageJson) as { version?: unknown };
+  return typeof parsed.version === "string" && parsed.version ? parsed.version : "unknown";
+}
+
 export function filterHistory(attempts: Attempt[], filters: HistoryFilters = {}, now = new Date()): Attempt[] {
   let rows = [...attempts].sort((a, b) => b.updated_at.localeCompare(a.updated_at));
 

package/src/question-bank.ts

@@ -0,0 +1,219 @@
+import { mkdir, rename, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stateDir } from "./state.ts";
+import type { Difficulty, Focus, PracticeQuestion, QuestionMeta, Skill } from "./types.ts";
+
+export const questionBankVersion = 1;
+export const questionBankPath = join(stateDir, "cache", "question-bank.json");
+export const bundledQuestionBankPath = fileURLToPath(new URL("../data/question-bank.json.zst", import.meta.url));
+
+export type QuestionBank = {
+  version: typeof questionBankVersion;
+  source: string;
+  synced_at: string;
+  questions: PracticeQuestion[];
+};
+
+export type QuestionBankStatus = {
+  path: string;
+  exists: boolean;
+  size_bytes?: number;
+  source?: string;
+  synced_at?: string;
+  questions?: number;
+};
+
+let memoryBank: Promise<QuestionBank | undefined> | undefined;
+
+export async function getPracticeQuestion(attemptedIds: Iterable<string>, focus: Focus): Promise<PracticeQuestion> {
+  const question = selectPracticeQuestion(await requireQuestionBank(), attemptedIds, focus);
+  if (!question) {
+    throw new Error("No unanswered questions matched the current filters.");
+  }
+
+  return question;
+}
+
+export async function getQuestionByShortId(questionId: string): Promise<PracticeQuestion | undefined> {
+  return findQuestionInBank(await requireQuestionBank(), questionId);
+}
+
+export function selectPracticeQuestion(
+  bank: QuestionBank,
+  attemptedIds: Iterable<string>,
+  focus: Focus,
+  random = Math.random,
+): PracticeQuestion | undefined {
+  const attempted = new Set(attemptedIds);
+  const candidates = bank.questions.filter((question) =>
+    !attempted.has(question.meta.questionId) && questionMatchesFocus(question.meta, focus)
+  );
+
+  if (candidates.length === 0) {
+    return undefined;
+  }
+
+  const index = Math.min(candidates.length - 1, Math.floor(random() * candidates.length));
+  return candidates[index];
+}
+
+export function findQuestionInBank(bank: QuestionBank, questionId: string): PracticeQuestion | undefined {
+  return bank.questions.find((question) => question.meta.questionId === questionId);
+}
+
+export async function loadQuestionBank(path = questionBankPath): Promise<QuestionBank | undefined> {
+  if (path === questionBankPath) {
+    memoryBank ??= materializeQuestionBankCache();
+    return memoryBank;
+  }
+
+  return readQuestionBank(path);
+}
+
+export async function materializeQuestionBankCache(
+  cachePath = questionBankPath,
+  bundledPath = bundledQuestionBankPath,
+): Promise<QuestionBank | undefined> {
+  const cached = await readQuestionBank(cachePath);
+  if (cached) {
+    return cached;
+  }
+
+  const bundled = await readQuestionBank(bundledPath);
+  if (!bundled) {
+    return undefined;
+  }
+
+  await saveQuestionBank(bundled, cachePath);
+  return bundled;
+}
+
+export async function questionBankStatus(path = questionBankPath): Promise<QuestionBankStatus> {
+  try {
+    const bank = await loadQuestionBank(path);
+    if (!bank) {
+      return { path, exists: false };
+    }
+    const file = await stat(path);
+
+    return {
+      path,
+      exists: true,
+      size_bytes: file.size,
+      source: bank.source,
+      synced_at: bank.synced_at,
+      questions: bank.questions.length,
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { path, exists: false };
+    }
+
+    throw error;
+  }
+}
+
+export async function saveQuestionBank(bank: QuestionBank, path = questionBankPath): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.tmp`;
+  await Bun.write(tempPath, `${JSON.stringify(bank)}\n`);
+  await rename(tempPath, path);
+}
+
+export function resetQuestionBankMemoryCache(): void {
+  memoryBank = undefined;
+}
+
+async function requireQuestionBank(path = questionBankPath): Promise<QuestionBank> {
+  const bank = await loadQuestionBank(path);
+  if (!bank) {
+    throw new Error("Question bank is missing from the package.");
+  }
+
+  return bank;
+}
+
+async function readQuestionBank(path: string): Promise<QuestionBank | undefined> {
+  try {
+    if (path.endsWith(".zst")) {
+      const compressed = await Bun.file(path).arrayBuffer();
+      const payload = Bun.zstdDecompressSync(new Uint8Array(compressed));
+      return parseQuestionBank(JSON.parse(new TextDecoder().decode(payload)));
+    }
+
+    return parseQuestionBank(await Bun.file(path).json());
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+function parseQuestionBank(value: unknown): QuestionBank {
+  if (!value || typeof value !== "object") {
+    throw new Error("Question bank cache is not an object.");
+  }
+
+  const bank = value as Partial<QuestionBank>;
+  if (bank.version !== questionBankVersion) {
+    throw new Error(`Question bank cache version ${String(bank.version)} is not supported.`);
+  }
+
+  if (typeof bank.source !== "string" || !bank.source) {
+    throw new Error("Question bank cache is missing its source.");
+  }
+
+  if (typeof bank.synced_at !== "string" || Number.isNaN(new Date(bank.synced_at).getTime())) {
+    throw new Error("Question bank cache has an invalid sync timestamp.");
+  }
+
+  if (!Array.isArray(bank.questions)) {
+    throw new Error("Question bank cache is missing questions.");
+  }
+
+  const questions = bank.questions.filter(isPracticeQuestion);
+  if (questions.length !== bank.questions.length) {
+    throw new Error("Question bank cache contains invalid question entries.");
+  }
+
+  return {
+    version: questionBankVersion,
+    source: bank.source,
+    synced_at: bank.synced_at,
+    questions,
+  };
+}
+
+function isPracticeQuestion(value: unknown): value is PracticeQuestion {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const question = value as Partial<PracticeQuestion>;
+  return isQuestionMeta(question.meta) && isQuestionDetail(question.detail);
+}
+
+function isQuestionMeta(value: unknown): value is QuestionMeta {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const meta = value as Partial<QuestionMeta>;
+  return Boolean(meta.questionId && meta.external_id && meta.difficulty && meta.primary_class_cd && meta.skill_cd);
+}
+
+function isQuestionDetail(value: unknown): value is PracticeQuestion["detail"] {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const detail = value as Partial<PracticeQuestion["detail"]>;
+  return Boolean(detail.type && typeof detail.stem === "string" && detail.answerOptions && Array.isArray(detail.correct_answer));
+}
+
+function questionMatchesFocus(meta: QuestionMeta, focus: Focus): boolean {
+  return focus.difficulties.includes(meta.difficulty as Difficulty) && focus.skills.includes(meta.skill_cd as Skill);
+}

package/src/tui/app.ts

@@ -1,4 +1,5 @@
 import { defaultFocus } from "../focus.ts";
+import { questionBankStatus } from "../question-bank.ts";
 import { ensureStateFiles, loadAttempts, loadFocus, stateDirExists } from "../state.ts";
 import { handleKey, loadNextQuestion } from "./input.ts";
 import { createFrameRenderer, render } from "./render.ts";
@@ -19,6 +20,11 @@ async function loadPersistedState(state: AppState, options: TuiOptions = {}): Pr
   state.focusRow = 1;
   state.notice = undefined;
 
+  const bank = await questionBankStatus();
+  if (bank.exists && bank.questions) {
+    state.notice = `${bank.questions} questions loaded.`;
+  }
+
   if (options.mode === "review") {
     state.reviewMode = true;
     state.reviewQuestionIds = reviewQuestionIds(state.attempts);

package/src/tui/input.ts

@@ -1,4 +1,4 @@
-import { fetchPracticeQuestion, findQuestionByShortId } from "../api.ts";
+import { getPracticeQuestion, getQuestionByShortId } from "../question-bank.ts";
 import { appendAttemptEvent, recordAttempt, saveAttempts, saveFocus, saveSummary } from "../state.ts";
 import { focusGrid, moveFocusGridPosition, normalizeFocusGridPosition, toggleFocusGridRow } from "./focus-grid.ts";
 import {
@@ -147,7 +147,7 @@ export async function handleKey(state: AppState, name: string, data?: KeyData):
     } else if (name === "ENTER" && attempts[state.historyIndex]) {
       state.view = "loading";
       resetPaneScroll(state);
-      state.detailQuestion = await findQuestionByShortId(attempts[state.historyIndex].question_id);
+      state.detailQuestion = await getQuestionByShortId(attempts[state.historyIndex].question_id);
       state.view = "detail";
     }
     return;
@@ -244,7 +244,7 @@ async function takeNextQuestion(state: AppState) {
     }
   }
 
-  return fetchPracticeQuestion(questionExclusions(state), state.focus);
+  return getPracticeQuestion(questionExclusions(state), state.focus);
 }
 
 async function takeReviewQuestion(state: AppState): Promise<PracticeQuestion | undefined> {
@@ -254,7 +254,7 @@ async function takeReviewQuestion(state: AppState): Promise<PracticeQuestion | u
       continue;
     }
 
-    const question = await findQuestionByShortId(id);
+    const question = await getQuestionByShortId(id);
     if (question) {
       return question;
     }
@@ -268,7 +268,7 @@ function cacheNextQuestion(state: AppState): void {
     return;
   }
 
-  state.nextQuestion = fetchPracticeQuestion(questionExclusions(state), state.focus).catch(() => undefined);
+  state.nextQuestion = getPracticeQuestion(questionExclusions(state), state.focus).catch(() => undefined);
 }
 
 function questionExclusions(state: AppState): string[] {

package/src/tui/question.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { hasHtmlTable, parseHtmlSegments, wrapSegments } from "../text.ts";
 import type { PracticeQuestion, QuestionDetail } from "../types.ts";
+import { apiBaseUrl, siteUrl } from "../urls.ts";
 import type { DisplayRow } from "./types.ts";
 
 export function answerKeys(question?: PracticeQuestion): string[] {
@@ -30,11 +31,11 @@ export function questionRows(detail: QuestionDetail, width: number): DisplayRow[
 }
 
 export function practiceQuestionUrl(question: PracticeQuestion): string {
-  return `https://practicesat.vercel.app/question?questionId=${encodeURIComponent(question.meta.questionId)}`;
+  return `${siteUrl}/question/${encodeURIComponent(question.meta.questionId)}`;
 }
 
 export function practiceQuestionApiUrl(question: PracticeQuestion): string {
-  return `https://practicesat.vercel.app/api/question/${encodeURIComponent(question.meta.external_id)}`;
+  return `${apiBaseUrl}/question/${encodeURIComponent(question.meta.external_id)}`;
 }
 
 export function openExternalQuestion(question: PracticeQuestion): void {

package/src/tui/render.ts

@@ -70,7 +70,7 @@ function renderSetup(doc: Frame): void {
   const location = displayStateDir(stateDir);
 
   text(doc, 0, 3, "storage location", { bold: true });
-  text(doc, 0, 5, "Sat saves progress, focus settings, and summary stats locally.", { color: "gray" }, width);
+  text(doc, 0, 5, "Sat saves progress, focus settings, summary stats, and the local question cache.", { color: "gray" }, width);
   text(doc, 0, 7, "Allow creating this directory?", { bold: true }, width);
   text(doc, 0, 9, location, { color: "cyan" }, width);
 }
@@ -124,6 +124,9 @@ function renderFocus(doc: Frame, state: AppState): void {
   text(doc, 0, 3, "study focus", { bold: true });
   text(doc, Math.max(0, width - summary.length - 1), 3, summary, { color: "cyan" });
   text(doc, 0, 4, "Space toggles the selected row. Enter starts practice.", { color: "gray" }, width);
+  if (state.notice) {
+    text(doc, 0, 5, state.notice, { color: "yellow" }, width);
+  }
 
   renderDifficultyColumn(doc, columns[0], position.column === 0 ? position.row : -1);
   renderDomainColumns(doc, columns.slice(1), position.column - 1, position.row);

package/src/urls.ts

@@ -0,0 +1,2 @@
+export const siteUrl = "https://practicesat.vercel.app";
+export const apiBaseUrl = `${siteUrl}/api`;

package/src/api.ts

@@ -1,78 +0,0 @@
-import { defaultFocus, domainsForSkills } from "./focus.ts";
-import type { Focus, PracticeQuestion, QuestionDetail, QuestionMeta } from "./types.ts";
-
-const baseUrl = "https://practicesat.vercel.app/api";
-
-type ApiEnvelope<T> = {
-  success: boolean;
-  data: T;
-  message?: string;
-};
-
-export async function fetchQuestionBank(excludeIds: Iterable<string> = [], focus: Focus = defaultFocus): Promise<QuestionMeta[]> {
-  const params = focusParams(focus);
-  const excluded = [...excludeIds].filter(Boolean);
-  if (excluded.length > 0) {
-    params.set("excludeIds", excluded.join(","));
-  }
-
-  const response = await fetchJson<ApiEnvelope<QuestionMeta[]>>(`${baseUrl}/get-questions?${params}`);
-  if (!response.success || !Array.isArray(response.data)) {
-    throw new Error(response.message || "Question bank fetch failed.");
-  }
-
-  return response.data.filter((item) => item.questionId && item.external_id);
-}
-
-export async function fetchQuestion(id: string): Promise<QuestionDetail> {
-  const response = await fetchJson<ApiEnvelope<QuestionDetail>>(`${baseUrl}/question/${id}`);
-  if (!response.success || !response.data) {
-    throw new Error(response.message || `Question ${id} fetch failed.`);
-  }
-
-  return response.data;
-}
-
-export async function fetchPracticeQuestion(attemptedIds: Iterable<string>, focus: Focus = defaultFocus): Promise<PracticeQuestion> {
-  const bank = await fetchQuestionBank(attemptedIds, focus);
-  if (bank.length === 0) {
-    throw new Error("No unanswered questions matched the current filters.");
-  }
-
-  const meta = bank[Math.floor(Math.random() * bank.length)];
-  const detail = await fetchQuestion(meta.external_id);
-  return { meta, detail };
-}
-
-export async function findQuestionByShortId(questionId: string): Promise<PracticeQuestion | undefined> {
-  const bank = await fetchQuestionBank();
-  const meta = bank.find((item) => item.questionId === questionId);
-  if (!meta) {
-    return undefined;
-  }
-
-  return { meta, detail: await fetchQuestion(meta.external_id) };
-}
-
-function focusParams(focus: Focus): URLSearchParams {
-  return new URLSearchParams({
-    assessment: "SAT",
-    domains: domainsForSkills(focus.skills).join(","),
-    difficulties: focus.difficulties.join(","),
-    skills: focus.skills.join(","),
-  });
-}
-
-async function fetchJson<T>(url: string): Promise<T> {
-  const response = await fetch(url, {
-    headers: {
-      accept: "application/json",
-    },
-  });
-
-  if (!response.ok) {
-    throw new Error(`${response.status} ${response.statusText}`);
-  }
-
-  return (await response.json()) as T;
-}