saterminal 0.1.0 → 0.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "saterminal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
-    "sat": "./src/main.ts"
+    "sat": "src/main.ts"
   },
   "scripts": {
     "dev": "bun run src/main.ts",

package/src/state.ts

@@ -1,9 +1,27 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
 import { defaultFocus, normalizeFocus } from "./focus.ts";
 import type { Attempt, Focus, Outcome, SummaryRow } from "./types.ts";
 
-export const stateDir = "userlocal";
+export function resolveStateDir(home = homedir()): string {
+  return join(home, ".saterminal", "userlocal");
+}
+
+export function displayStateDir(dir: string, home = homedir()): string {
+  if (dir === home) {
+    return "~";
+  }
+
+  const prefix = `${home}${sep}`;
+  if (dir.startsWith(prefix)) {
+    return `~${dir.slice(home.length)}`;
+  }
+
+  return dir;
+}
+
+export const stateDir = resolveStateDir();
 export const attemptsPath = join(stateDir, "attempts.csv");
 export const summaryPath = join(stateDir, "summary.csv");
 export const focusPath = join(stateDir, "focus.json");
@@ -11,11 +29,23 @@ 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 stateDirExists(dir = stateDir): Promise<boolean> {
+  try {
+    return (await stat(dir)).isDirectory();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+export async function ensureStateFiles(dir = stateDir): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await ensureFile(join(dir, "attempts.csv"), `${attemptsHeader}\n`);
+  await ensureFile(join(dir, "summary.csv"), `${summaryHeader}\n`);
+  await ensureFile(join(dir, "focus.json"), `${JSON.stringify(defaultFocus, null, 2)}\n`);
 }
 
 export async function loadAttempts(path = attemptsPath): Promise<Map<string, Attempt>> {
@@ -107,11 +137,15 @@ export async function saveSummary(attempts: Map<string, Attempt>, path = summary
 
 export async function loadFocus(path = focusPath): Promise<Focus> {
   await ensureFile(path, `${JSON.stringify(defaultFocus, null, 2)}\n`);
+  const raw = await readFile(path, "utf8");
+  let parsed: unknown;
   try {
-    return normalizeFocus(JSON.parse(await readFile(path, "utf8")));
-  } catch {
-    return defaultFocus;
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Invalid focus file at ${path}: ${error instanceof Error ? error.message : String(error)}`);
   }
+
+  return normalizeFocus(parsed);
 }
 
 export async function saveFocus(focus: Focus, path = focusPath): Promise<void> {

package/src/tui/app.ts

@@ -1,10 +1,20 @@
 import { defaultFocus } from "../focus.ts";
-import { ensureStateFiles, loadAttempts, loadFocus } from "../state.ts";
+import { ensureStateFiles, loadAttempts, loadFocus, stateDirExists } 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";
 
+async function loadPersistedState(state: AppState): Promise<void> {
+  await ensureStateFiles();
+  state.attempts = await loadAttempts();
+  state.focus = await loadFocus();
+  state.focusIndex = 1;
+  state.focusColumn = 0;
+  state.focusRow = 1;
+  state.view = "focus";
+}
+
 export async function runTui(): Promise<void> {
   const state: AppState = {
     attempts: new Map(),
@@ -13,7 +23,7 @@ export async function runTui(): Promise<void> {
     focusIndex: 1,
     focusColumn: 0,
     focusRow: 1,
-    view: "focus",
+    view: "loading",
     selected: 0,
     questionScroll: 0,
     answerScroll: 0,
@@ -44,6 +54,20 @@ export async function runTui(): Promise<void> {
 
   process.on("SIGINT", cleanup);
   term.on("resize", () => render(doc, state));
+
+  try {
+    if (await stateDirExists()) {
+      await loadPersistedState(state);
+    } else {
+      state.view = "setup";
+    }
+  } catch (error) {
+    state.view = "error";
+    state.error = error instanceof Error ? error.message : String(error);
+  }
+
+  render(doc, state);
+
   term.on("key", async (name: string, _matches?: string[], data?: KeyData) => {
     try {
       if (name === "CTRL_C" || name === "q") {
@@ -51,6 +75,18 @@ export async function runTui(): Promise<void> {
         return;
       }
 
+      if (state.view === "setup") {
+        if (name === "y" || name === "ENTER") {
+          await loadPersistedState(state);
+        } else if (name === "n") {
+          cleanup();
+          return;
+        }
+
+        render(doc, state);
+        return;
+      }
+
       await handleKey(state, name, data);
       render(doc, state);
     } catch (error) {
@@ -59,19 +95,4 @@ export async function runTui(): Promise<void> {
       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/render.ts

@@ -1,4 +1,4 @@
-import { buildSummaryRows } from "../state.ts";
+import { buildSummaryRows, displayStateDir, stateDir } from "../state.ts";
 import { focusSummary } from "../focus.ts";
 import { htmlToText, wrapText } from "../text.ts";
 import type { TextSegment } from "../text.ts";
@@ -41,7 +41,9 @@ export function render(doc: TkDocument, state: AppState): void {
   header(doc, state);
 
   if (state.view === "loading") {
-    text(doc, 0, 3, "Loading...");
+    renderLoading(doc);
+  } else if (state.view === "setup") {
+    renderSetup(doc);
   } else if (state.view === "focus") {
     renderFocus(doc, state);
   } else if (state.view === "practice") {
@@ -62,6 +64,20 @@ export function render(doc: TkDocument, state: AppState): void {
   doc.draw();
 }
 
+function renderLoading(doc: TkDocument): void {
+  text(doc, 0, 3, "Loading...");
+}
+
+function renderSetup(doc: TkDocument): void {
+  const { width } = terminalSize();
+  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, 7, "Allow creating this directory?", { bold: true }, width);
+  text(doc, 0, 9, location, { color: "cyan" }, width);
+}
+
 function renderPaused(doc: TkDocument): void {
   const { width, height } = terminalSize();
   const label = "PAUSED";
@@ -79,7 +95,9 @@ function header(doc: TkDocument, state: AppState): void {
 
 function footer(doc: TkDocument, state: AppState): void {
   const { width, height } = terminalSize();
-  const controls = state.view === "practice"
+  const controls = state.view === "setup"
+    ? "y allow | n decline | q quit"
+    : state.view === "practice"
     ? practiceControls(state)
     : state.view === "focus"
       ? "up/down or j/k row | tab/shift-tab group | space toggle | enter start | q quit"

package/src/tui/types.ts

@@ -2,7 +2,7 @@ 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 View = "setup" | "focus" | "loading" | "practice" | "review" | "history" | "summary" | "detail" | "error";
 
 export type AppState = {
   attempts: Map<string, Attempt>;

package/test/state.test.ts

@@ -5,15 +5,38 @@ import { join } from "node:path";
 import { defaultFocus, normalizeFocus } from "../src/focus.ts";
 import {
   buildSummaryRows,
+  displayStateDir,
   loadAttempts,
   loadFocus,
   nextOutcome,
   recordAttempt,
+  resolveStateDir,
   saveAttempts,
   saveFocus,
+  stateDirExists,
 } from "../src/state.ts";
 
 describe("state", () => {
+  test("resolves state dir under the user home directory", () => {
+    expect(resolveStateDir("/home/user")).toBe("/home/user/.saterminal/userlocal");
+  });
+
+  test("displays state dir with a tilde prefix", () => {
+    expect(displayStateDir("/home/user/.saterminal/userlocal", "/home/user")).toBe("~/.saterminal/userlocal");
+    expect(displayStateDir("/home/user", "/home/user")).toBe("~");
+  });
+
+  test("detects whether the state directory exists", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+
+    try {
+      expect(await stateDirExists(dir)).toBe(true);
+      expect(await stateDirExists(join(dir, "missing"))).toBe(false);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("creates and reads a compact attempts csv", async () => {
     const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
     const path = join(dir, "attempts.csv");
@@ -103,6 +126,18 @@ describe("state", () => {
     });
   });
 
+  test("creates default focus when file is missing", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "focus.json");
+
+    try {
+      expect(await loadFocus(path)).toEqual(defaultFocus);
+      expect(await readFile(path, "utf8")).toContain("\"difficulties\"");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("saves and loads focus json", async () => {
     const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
     const path = join(dir, "focus.json");
@@ -117,4 +152,16 @@ describe("state", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("throws when focus json is invalid", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "saterminal-"));
+    const path = join(dir, "focus.json");
+
+    try {
+      await writeFile(path, "{not json", "utf8");
+      await expect(loadFocus(path)).rejects.toThrow(/Invalid focus file/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });