saterminal 0.4.0 → 0.5.1

package/README.md

@@ -1,21 +1,184 @@
-why?
+# saterminal
 
-- 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...
+SAT practice that stays on your computer. The app ships with a compressed question bank, works without an account or network connection, and records progress in a local SQLite database.
 
-usage
+It exists because studying one question at a time should not require downloading worksheets, navigating a website, or looking at difficulty metadata before answering.
+
+## Get started
+
+The development environment is defined by Nix and uses Bun throughout.
 
 ```sh
+direnv allow
+bun install
+bun link
 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.
+Without direnv, enter the shell explicitly:
+
+```sh
+nix develop
+bun install
+bun run dev
+```
+
+Build and run the packaged application directly with Nix:
+
+```sh
+nix build
+./result/bin/sat --help
+```
+
+The first launch asks before creating `~/.saterminal`. Choose a focus, press Enter, and start answering. Everything needed for practice is already in the package.
+
+Practice deliberately hides difficulty, domain, and skill while a question is active. The header shows only the running timer. After submitting, the answer screen restores the complete question beside the marked choices and explanation, then reveals timing and question metadata for review.
+
+## Useful commands
+
+Running `sat` opens normal practice. Reports use the richer terminal layout by default; no `-p` flag is necessary.
+
+```sh
+sat                 # choose a focus and practice
+sat review          # revisit eligible missed and corrected questions
+sat weak            # rank the skills that need attention
+sat stats           # accuracy, timing, streak, and activity
+sat history         # recent question outcomes
+sat history --wrong --since 2w
+sat focus           # inspect the active focus
+sat config          # inspect local preferences
+```
 
-maintainers
+Every report also supports:
 
 ```sh
-bun run update-bank
+sat stats --plain    # compact, stable text
+sat stats --json     # machine-readable output
+sat stats --no-color
+NO_COLOR=1 sat weak
 ```
 
-This refreshes `data/question-bank.json.zst` from Practice SAT for the next package release.
+Use `sat <command> --help` for command-specific filters.
+
+## Review spacing
+
+A missed or corrected question enters `sat review` only after both default spacing requirements are met:
+
+- at least 7 days have passed since its latest answer;
+- at least 100 answer events were recorded after that answer.
+
+This prevents an immediate retry from masquerading as durable recall. Change either threshold with:
+
+```sh
+sat config set --minimum-days 14
+sat config set --minimum-answers-after 200
+sat config set --minimum-days 14 --minimum-answers-after 200
+sat config reset
+```
+
+## Result detail
+
+Choose how much learner-facing context appears after an answer:
+
+```sh
+sat config set --result-detail brief     # time
+sat config set --result-detail standard  # time and difficulty (default)
+sat config set --result-detail detailed  # time, difficulty, and taxonomy
+```
+
+The verdict, answer choices, and explanation remain visible at every level. Internal question IDs stay available through `sat show`, not the result screen.
+
+## Preferences file
+
+You can also edit `~/.saterminal/preferences.json` directly:
+
+```json
+{
+  "$schema": "./preferences.schema.json",
+  "review": {
+    "minimumDays": 7,
+    "minimumAnswersAfter": 100
+  },
+  "display": {
+    "resultDetail": "standard"
+  }
+}
+```
+
+Set `display.resultDetail` to `brief`, `standard`, or `detailed` to control answer-result context. Brief shows time, standard adds difficulty, and detailed adds taxonomy codes and labels. The adjacent JSON Schema provides editor validation, descriptions, and completions. Omitted values use their defaults. Unknown, negative, fractional, or malformed values are rejected with the path to the invalid file.
+
+## Interactive keys
+
+The footer always shows the keys available on the current screen. The common ones are:
+
+| Key | Action |
+| --- | --- |
+| `j` / `k`, arrows | Move through focus options and answers; scroll the active review pane |
+| `Tab`, left/right | Move between focus groups or question/answer panes |
+| `Space` | Toggle a focus option; pause a running question timer |
+| `Enter` | Start, submit, continue, or open a history item |
+| `A`–`D` | Select an answer directly |
+| `[` / `]`, Page Up/Down | Scroll the active question, answer, or explanation pane |
+| `t` | Show or hide the timer while actively answering |
+| `f` / `h` / `s` / `p` | Focus / history / summary / practice |
+| `q` | Quit |
+
+Questions containing HTML tables can be opened on Practice SAT with `o`; the rest of the practice flow remains local.
+
+## Local data
+
+- `~/.saterminal/sat.db` contains focus, latest outcomes, and answer events.
+- `~/.saterminal/.ignore` keeps the generated cache out of supporting editor file pickers.
+- `~/.saterminal/preferences.json` contains optional review-spacing and display preferences.
+- `~/.saterminal/preferences.schema.json` provides local editor validation and completions.
+- `~/.saterminal/cache/question-bank.json` is the local materialized question bank.
+- `data/question-bank.json.zst` is the bundled offline source used to create that cache.
+
+Answer recording is transactional: the event history and latest per-question outcome either both commit or both roll back. Existing schema-version-one databases are migrated in place.
+
+Deleting `~/.saterminal` resets local progress. There is deliberately no cloud account, sync service, server, or authentication layer.
+
+## Project map
+
+The source tree is organized by ownership rather than file size:
+
+```text
+src/
+  questions/   normalized SAT questions, taxonomy, focus, local bank
+  progress/    attempts and read-only analysis of recorded study
+  practice/    live study workflows and outcome transitions
+  preferences/ validated local user preferences
+  database/    SQLite schema, migration, and repositories
+  cli/         Pastel command routes and report presentation
+  tui/         Ink application, screens, and terminal components
+  text/        HTML/media normalization and terminal wrapping
+  local-data/  local filesystem locations
+```
+
+Only the bank update script knows the upstream Practice SAT field names. Runtime code works with the normalized question model.
+
+## Maintain the question bank
+
+Refresh the bundled bank for a future release with:
+
+```sh
+nix develop -c bun run update-bank
+```
+
+This is the only normal workflow that needs the network. It downloads Practice SAT data, normalizes it, and writes `data/question-bank.json.zst`.
+
+## Verify changes
+
+```sh
+nix develop -c bun run typecheck
+nix develop -c bun test
+nix develop -c bun run src/cli/index.ts --help
+nix build
+./result/bin/sat --version
+```
+
+When `bun.lock` changes, regenerate the committed Nix dependency expression before building:
+
+```sh
+nix develop -c bun run nix:deps
+```

package/package.json

@@ -1,32 +1,38 @@
 {
   "name": "saterminal",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "bin": {
-    "sat": "src/main.ts"
+    "sat": "src/cli/index.ts"
   },
   "files": [
     "data",
-    "src"
+    "src",
+    "tsconfig.json"
   ],
   "scripts": {
-    "dev": "bun run src/main.ts",
-    "start": "bun run src/main.ts",
+    "dev": "bun run src/cli/index.ts",
+    "start": "bun run src/cli/index.ts",
+    "nix:deps": "bun2nix -o nix/bun.nix",
     "update-bank": "bun run scripts/update-question-bank.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@inkjs/ui": "2.0.0",
     "he": "^1.2.0",
-    "node-html-parser": "^8.0.4",
-    "terminal-kit": "^3.1.2",
-    "word-wrap": "^1.2.5"
+    "ink": "6.8.0",
+    "node-html-parser": "^9.0.0",
+    "pastel": "4.0.1",
+    "react": "19.2.0",
+    "zod": "4"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.22",
+    "@types/bun": "^1.3.14",
     "@types/he": "^1.2.3",
-    "@types/word-wrap": "^1.2.1",
+    "@types/react": "19.2.0",
     "p-limit": "^7.3.0",
-    "typescript": "^5.9.3"
+    "react-devtools-core": "7.0.1",
+    "typescript": "^7.0.2"
   }
 }

package/src/cli/commands/_app.tsx

@@ -0,0 +1,10 @@
+import { defaultTheme, ThemeProvider } from "@inkjs/ui";
+import type { AppProps } from "pastel";
+
+export default function CommandApp({ Component, commandProps }: AppProps) {
+  return (
+    <ThemeProvider theme={defaultTheme}>
+      <Component {...commandProps} />
+    </ThemeProvider>
+  );
+}

package/src/cli/commands/config/index.tsx

@@ -0,0 +1,21 @@
+import { CommandAction } from "@/cli/components/command-action.tsx";
+import { displayPath, preferencesPath } from "@/local-data/paths.ts";
+import { loadPreferences } from "@/preferences/index.ts";
+
+export const description = "Show local preferences";
+
+export default function ConfigCommand() {
+  return <CommandAction dependencies={[]} run={async () => {
+    const preferences = await loadPreferences();
+    return [
+      "preferences",
+      displayPath(preferencesPath),
+      "",
+      `review minimum days           ${preferences.review.minimumDays}`,
+      `review minimum answers after  ${preferences.review.minimumAnswersAfter}`,
+      `result detail                 ${preferences.display.resultDetail}`,
+      "",
+      "Update with: sat config set --minimum-days 7 --minimum-answers-after 100 --result-detail detailed",
+    ].join("\n");
+  }} />;
+}

package/src/cli/commands/config/reset.tsx

@@ -0,0 +1,12 @@
+import { CommandAction } from "@/cli/components/command-action.tsx";
+import { displayPath, preferencesPath } from "@/local-data/paths.ts";
+import { defaultPreferences, savePreferences } from "@/preferences/index.ts";
+
+export const description = "Restore default preferences";
+
+export default function ResetConfigCommand() {
+  return <CommandAction dependencies={[]} run={async () => {
+    await savePreferences(defaultPreferences);
+    return `Reset ${displayPath(preferencesPath)} to the defaults.`;
+  }} />;
+}

package/src/cli/commands/config/set.tsx

@@ -0,0 +1,34 @@
+import { option } from "pastel";
+import { z } from "zod";
+import { CommandAction } from "@/cli/components/command-action.tsx";
+import { displayPath, preferencesPath } from "@/local-data/paths.ts";
+import { loadPreferences, resultDetailLevels, savePreferences } from "@/preferences/index.ts";
+
+export const description = "Update local preferences";
+export const options = z.object({
+  minimumDays: z.number().int().nonnegative().optional().describe(option({ description: "Days before a question can be reviewed", valueDescription: "days" })),
+  minimumAnswersAfter: z.number().int().nonnegative().optional().describe(option({ description: "Later answers required before review", valueDescription: "count" })),
+  resultDetail: z.enum(resultDetailLevels).optional().describe(option({ description: "Set answer-result detail", valueDescription: "level" })),
+});
+type Options = z.infer<typeof options>;
+
+export default function SetConfigCommand({ options }: { options: Options }) {
+  return <CommandAction dependencies={[options.minimumDays, options.minimumAnswersAfter, options.resultDetail]} run={async () => {
+    if (options.minimumDays === undefined && options.minimumAnswersAfter === undefined && options.resultDetail === undefined) {
+      throw new Error("provide --minimum-days, --minimum-answers-after, or --result-detail");
+    }
+    const current = await loadPreferences();
+    const next = {
+      ...current,
+      review: {
+        minimumDays: options.minimumDays ?? current.review.minimumDays,
+        minimumAnswersAfter: options.minimumAnswersAfter ?? current.review.minimumAnswersAfter,
+      },
+      display: {
+        resultDetail: options.resultDetail ?? current.display.resultDetail,
+      },
+    };
+    await savePreferences(next);
+    return `Updated ${displayPath(preferencesPath)}\nreview: ${next.review.minimumDays} days · ${next.review.minimumAnswersAfter} later answers\nresult detail: ${next.display.resultDetail}`;
+  }} />;
+}

package/src/cli/commands/focus.tsx

@@ -0,0 +1,12 @@
+import { loadFocus } from "@/database/focus-repository.ts";
+import { Report } from "@/cli/components/report.tsx";
+import { formatFocus } from "@/cli/reports/focus.ts";
+import { outputMode, reportColor, reportOptions, type ReportOptions } from "@/cli/report-options.ts";
+
+export const description = "Show the current question focus";
+export const options = reportOptions;
+
+export default function FocusCommand({ options }: { options: ReportOptions }) {
+  const output = formatFocus(loadFocus(), { mode: outputMode(options), color: reportColor(options) });
+  return <Report raw={options.json}>{output}</Report>;
+}

package/src/cli/commands/history.tsx

@@ -0,0 +1,21 @@
+import { option } from "pastel";
+import { z } from "zod";
+import { loadAttempts } from "@/database/progress-repository.ts";
+import { history } from "@/progress/history.ts";
+import { Report } from "@/cli/components/report.tsx";
+import { formatHistory } from "@/cli/reports/history.ts";
+import { outputMode, reportColor, reportOptions } from "@/cli/report-options.ts";
+
+export const description = "Show answered questions";
+export const options = reportOptions.extend({
+  wrong: z.boolean().describe(option({ description: "Show currently missed questions" })),
+  corrected: z.boolean().describe(option({ description: "Show corrected questions" })),
+  limit: z.number().int().positive().optional().describe(option({ description: "Limit rows", valueDescription: "count" })),
+  since: z.string().optional().describe(option({ description: "Show rows since an ISO date, 7d, or 2w", valueDescription: "when" })),
+});
+type Options = z.infer<typeof options>;
+
+export default function HistoryCommand({ options }: { options: Options }) {
+  const output = formatHistory(history(loadAttempts().values(), options), { mode: outputMode(options), color: reportColor(options) });
+  return <Report raw={options.json}>{output}</Report>;
+}

package/src/cli/commands/index.tsx

@@ -0,0 +1,7 @@
+import { PracticeSession } from "@/tui/app.tsx";
+
+export const description = "Open interactive SAT practice";
+
+export default function PracticeCommand() {
+  return <PracticeSession />;
+}

package/src/cli/commands/review.tsx

@@ -0,0 +1,7 @@
+import { ReviewSession } from "@/tui/app.tsx";
+
+export const description = "Practice eligible missed and corrected questions";
+
+export default function ReviewCommand() {
+  return <ReviewSession />;
+}

package/src/cli/commands/show.tsx

@@ -0,0 +1,36 @@
+import { useApp } from "ink";
+import { useEffect } from "react";
+import { argument } from "pastel";
+import { z } from "zod";
+import { formatQuestion } from "@/cli/reports/question.ts";
+import { findQuestion } from "@/questions/local-bank.ts";
+
+export const description = "Inspect a question by ID";
+export const args = z.tuple([
+  z.string().describe(argument({ name: "id", description: "Question ID" })),
+]);
+
+export default function ShowCommand({ args: [id] }: { args: z.infer<typeof args> }) {
+  const { exit } = useApp();
+
+  useEffect(() => {
+    void (async () => {
+      try {
+        const question = await findQuestion(id);
+        if (!question) {
+          process.stderr.write(`sat: question ${id} was not found.\n`);
+          process.exitCode = 1;
+          return;
+        }
+        process.stdout.write(`${formatQuestion(question)}\n`);
+      } catch (error) {
+        process.stderr.write(`sat: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+      } finally {
+        exit();
+      }
+    })();
+  }, [exit, id]);
+
+  return null;
+}

package/src/cli/commands/stats.tsx

@@ -0,0 +1,15 @@
+import { loadAttemptEvents, loadAttempts } from "@/database/progress-repository.ts";
+import { activity } from "@/progress/activity.ts";
+import { progressStatistics } from "@/progress/statistics.ts";
+import { Report } from "@/cli/components/report.tsx";
+import { formatStats } from "@/cli/reports/stats.ts";
+import { outputMode, reportColor, reportOptions, type ReportOptions } from "@/cli/report-options.ts";
+
+export const description = "Show progress, streak, and recent activity";
+export const options = reportOptions;
+
+export default function StatsCommand({ options }: { options: ReportOptions }) {
+  const attempts = loadAttempts();
+  const output = formatStats(progressStatistics(attempts.values()), activity(loadAttemptEvents()), { mode: outputMode(options), color: reportColor(options) });
+  return <Report raw={options.json}>{output}</Report>;
+}

package/src/cli/commands/weak.tsx

@@ -0,0 +1,13 @@
+import { loadAttempts } from "@/database/progress-repository.ts";
+import { weaknesses } from "@/progress/weaknesses.ts";
+import { Report } from "@/cli/components/report.tsx";
+import { formatWeaknesses } from "@/cli/reports/weaknesses.ts";
+import { outputMode, reportColor, reportOptions, type ReportOptions } from "@/cli/report-options.ts";
+
+export const description = "Rank skills that need the most work";
+export const options = reportOptions;
+
+export default function WeakCommand({ options }: { options: ReportOptions }) {
+  const output = formatWeaknesses(weaknesses(loadAttempts().values()), { mode: outputMode(options), color: reportColor(options) });
+  return <Report raw={options.json}>{output}</Report>;
+}

package/src/cli/components/command-action.tsx

@@ -0,0 +1,23 @@
+import { useApp } from "ink";
+import { useEffect } from "react";
+
+export function CommandAction({ run, dependencies }: { run: () => string | Promise<string>; dependencies: readonly unknown[] }) {
+  const { exit } = useApp();
+  useEffect(() => {
+    void (async () => {
+      try {
+        process.stdout.write(`${await run()}\n`);
+      } catch (error) {
+        process.stderr.write(`sat: ${message(error)}\n`);
+        process.exitCode = 1;
+      } finally {
+        exit();
+      }
+    })();
+  }, [exit, ...dependencies]);
+  return null;
+}
+
+function message(value: unknown): string {
+  return value instanceof Error ? value.message : String(value);
+}

package/src/cli/components/report.tsx

@@ -0,0 +1,16 @@
+import { Text, useApp } from "ink";
+import { useEffect } from "react";
+
+export function Report({ children, raw = false }: { children: string; raw?: boolean }) {
+  if (raw) return <RawOutput value={children} />;
+  return <Text>{children}</Text>;
+}
+
+function RawOutput({ value }: { value: string }) {
+  const { exit } = useApp();
+  useEffect(() => {
+    process.stdout.write(`${value}\n`);
+    exit();
+  }, [exit, value]);
+  return null;
+}

package/src/cli/index.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+import Pastel from "pastel";
+
+const cli = new Pastel({
+  name: "sat",
+  description: "Local-first SAT practice in your terminal",
+  importMeta: import.meta,
+});
+
+await cli.run();

package/src/cli/report-options.ts

@@ -0,0 +1,19 @@
+import { option } from "pastel";
+import { z } from "zod";
+
+export const reportOptions = z.object({
+  plain: z.boolean().describe(option({ description: "Use a compact plain-text layout" })),
+  json: z.boolean().describe(option({ description: "Output machine-readable JSON" })),
+  color: z.boolean().default(true).describe(option({ description: "Disable ANSI color" })),
+});
+
+export type ReportOptions = z.infer<typeof reportOptions>;
+
+export function outputMode(options: ReportOptions): "pretty" | "plain" | "json" {
+  if (options.plain && options.json) throw new Error("Choose either --plain or --json, not both.");
+  return options.json ? "json" : options.plain ? "plain" : "pretty";
+}
+
+export function reportColor(options: ReportOptions): boolean {
+  return options.color && process.env.NO_COLOR === undefined && process.stdout.isTTY;
+}

package/src/cli/reports/focus.ts

@@ -0,0 +1,20 @@
+import type { Focus } from "@/questions/focus.ts";
+import { selectedDomains } from "@/questions/focus.ts";
+import { difficultyLabels, domainLabels, skillLabels } from "@/questions/taxonomy.ts";
+import { ansi, paint, type FormatSettings } from "@/cli/reports/terminal-format.ts";
+
+export function formatFocus(focus: Focus, settings: FormatSettings): string {
+  const domains = selectedDomains(focus);
+  if (settings.mode === "json") return JSON.stringify({ ...focus, domains });
+  if (settings.mode === "plain") return `difficulties: ${focus.difficulties.join(",")}\ndomains: ${domains.join(",")}\nskills: ${focus.skills.join(",")}`;
+  return [
+    paint("focus", settings, ansi.bold, ansi.cyan),
+    paint(`${focus.skills.length} skills · ${focus.difficulties.join(",")} · ${domains.length} domains`, settings, ansi.gray),
+    "", paint("difficulty", settings, ansi.bold),
+    ...focus.difficulties.map((value) => `  ${paint(value.padEnd(3), settings, ansi.yellow, ansi.bold)} ${difficultyLabels[value]}`),
+    "", paint("domains", settings, ansi.bold),
+    ...domains.map((value) => `  ${paint(value.padEnd(3), settings, ansi.cyan, ansi.bold)} ${domainLabels[value]}`),
+    "", paint("skills", settings, ansi.bold),
+    ...focus.skills.map((value) => `  ${paint(value.padEnd(3), settings, ansi.green, ansi.bold)} ${skillLabels[value]}`),
+  ].join("\n");
+}

package/src/cli/reports/history.ts

@@ -0,0 +1,21 @@
+import type { Attempt } from "@/progress/attempt.ts";
+import { ansi, duration, paint, table, type FormatSettings } from "@/cli/reports/terminal-format.ts";
+
+export function formatHistory(attempts: Attempt[], settings: FormatSettings): string {
+  if (settings.mode === "json") return JSON.stringify(attempts);
+  if (!attempts.length) return settings.mode === "pretty" ? `${paint("history", settings, ansi.bold, ansi.cyan)}\n${paint("No attempts matched.", settings, ansi.gray)}` : "No attempts matched.";
+  if (settings.mode === "plain") return table(["question", "outcome", "answered at", "time"], attempts.map((attempt) => [attempt.questionId, attempt.outcome, attempt.answeredAt, duration(attempt.durationSeconds)]));
+  const mastered = attempts.filter((attempt) => attempt.outcome !== "incorrect").length;
+  const missed = attempts.length - mastered;
+  return [
+    paint("history", settings, ansi.bold, ansi.cyan),
+    `${attempts.length} attempts  ${paint(String(mastered), settings, ansi.green, ansi.bold)} mastered  ${paint(String(missed), settings, missed ? ansi.red : ansi.gray, ansi.bold)} needs review`,
+    "",
+    table(["question", "result", "skill", "time", "updated"], attempts.map((attempt) => [attempt.questionId, attempt.outcome, attempt.skill ?? "-", duration(attempt.durationSeconds), timestamp(attempt.answeredAt)])),
+  ].join("\n");
+}
+
+function timestamp(value: string): string {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : `${String(date.getMonth() + 1).padStart(2, "0")}/${String(date.getDate()).padStart(2, "0")} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}

package/src/cli/reports/question.ts

@@ -0,0 +1,24 @@
+import type { Question } from "@/questions/question.ts";
+import { difficultyLabels, domainLabels, skillLabels } from "@/questions/taxonomy.ts";
+import { htmlToText } from "@/text/html.ts";
+
+export function formatQuestion(question: Question): string {
+  const passage = question.passage ? `${htmlToText(question.passage)}\n\n` : "";
+  const choices = question.choices
+    .map((choice) => `${choice.key}. ${htmlToText(choice.content)}`)
+    .join("\n");
+
+  return [
+    `Question ${question.id}`,
+    `${difficultyLabels[question.difficulty]} · ${domainLabels[question.domain]} · ${skillLabels[question.skill]}`,
+    "",
+    `${passage}${htmlToText(question.prompt)}`,
+    "",
+    choices,
+    "",
+    `Correct answer: ${question.correctAnswers.join(", ")}`,
+    "",
+    "Explanation",
+    htmlToText(question.explanation ?? "No explanation is available."),
+  ].join("\n");
+}