saterminal 0.4.0 → 0.5.0

package/src/cli/reports/terminal-format.ts

@@ -0,0 +1,28 @@
+export { formatDuration as duration } from "@/text/duration.ts";
+
+export type OutputMode = "pretty" | "plain" | "json";
+export type FormatSettings = { mode: OutputMode; color: boolean };
+
+export const ansi = {
+  reset: "\x1b[0m", bold: "\x1b[1m", gray: "\x1b[90m", red: "\x1b[31m",
+  green: "\x1b[32m", yellow: "\x1b[33m", cyan: "\x1b[36m",
+};
+
+export function table(headers: string[], rows: (string | number)[][]): string {
+  const values = [headers, ...rows.map((row) => row.map(String))];
+  const widths = headers.map((_, column) => Math.max(...values.map((row) => Bun.stringWidth(row[column] ?? ""))));
+  return values.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join("  ").trimEnd()).join("\n");
+}
+
+export function meter(ratio: number, width: number, settings: FormatSettings, color: string): string {
+  const full = Math.round(Math.max(0, Math.min(1, ratio)) * width);
+  return paint("█".repeat(full), settings, color) + paint("░".repeat(width - full), settings, ansi.gray);
+}
+
+export function percent(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
+export function paint(value: string, settings: FormatSettings, ...codes: string[]): string {
+  return settings.color && settings.mode === "pretty" ? `${codes.join("")}${value}${ansi.reset}` : value;
+}

package/src/cli/reports/weaknesses.ts

@@ -0,0 +1,36 @@
+import { ansi, duration, meter, paint, percent, table, type FormatSettings } from "@/cli/reports/terminal-format.ts";
+import type { Weakness } from "@/progress/weaknesses.ts";
+
+export function formatWeaknesses(rows: Weakness[], settings: FormatSettings): string {
+  if (settings.mode === "json") return JSON.stringify(rows);
+  if (!rows.length) return settings.mode === "plain"
+    ? "No metadata-backed attempts yet."
+    : `${paint("weak", settings, ansi.bold, ansi.cyan)}\n${paint("No skill data yet.", settings, ansi.gray)}`;
+  if (settings.mode === "plain") return table(["skill", "accuracy", "missed", "total", "avg", "focus"], rows.map((row) => [row.skill, percent(row.accuracy), row.missed, row.total, duration(row.averageSeconds), row.label]));
+
+  const skillWidth = Math.max(...rows.map((row) => Bun.stringWidth(skillName(row))), 5);
+  return [
+    paint("weak", settings, ansi.bold, ansi.cyan),
+    paint(`${"skill".padEnd(skillWidth)}  acc   miss  avg   mastery`, settings, ansi.gray),
+    ...rows.map((row) => weaknessRow(row, skillWidth, settings)),
+  ].join("\n");
+}
+
+function weaknessRow(row: Weakness, skillWidth: number, settings: FormatSettings): string {
+  const color = accuracyColor(row.accuracy);
+  return [
+    paint(skillName(row).padEnd(skillWidth), settings, color),
+    paint(percent(row.accuracy).padStart(4), settings, color, ansi.bold),
+    paint(`${row.missed}/${row.total}`.padStart(5), settings, row.missed ? ansi.red : ansi.gray),
+    paint(duration(row.averageSeconds).padStart(4), settings, ansi.cyan),
+    meter(row.accuracy, 20, settings, color),
+  ].join("  ");
+}
+
+function skillName(row: Weakness): string {
+  return `${row.skill}  ${row.label}`;
+}
+
+function accuracyColor(value: number): string {
+  return value >= 0.9 ? ansi.green : value >= 0.75 ? ansi.yellow : ansi.red;
+}

package/src/database/focus-repository.ts

@@ -0,0 +1,26 @@
+import type { Focus } from "@/questions/focus.ts";
+import { defaultFocus, normalizeFocus } from "@/questions/focus.ts";
+import { databasePath } from "@/local-data/paths.ts";
+import { openDatabase } from "@/database/index.ts";
+
+export function loadFocus(path = databasePath): Focus {
+  const database = openDatabase(path);
+  try {
+    const row = database.query("select difficulties, skills from focus where id = 1").get() as { difficulties: string; skills: string } | null;
+    return row ? normalizeFocus({ difficulties: JSON.parse(row.difficulties), skills: JSON.parse(row.skills) }) : defaultFocus;
+  } finally {
+    database.close();
+  }
+}
+
+export function saveFocus(focus: Focus, path = databasePath): void {
+  const normalized = normalizeFocus(focus);
+  const database = openDatabase(path);
+  try {
+    database.query(`insert into focus (id, difficulties, skills, updated_at) values (1, ?, ?, ?)
+      on conflict(id) do update set difficulties = excluded.difficulties, skills = excluded.skills, updated_at = excluded.updated_at`)
+      .run(JSON.stringify(normalized.difficulties), JSON.stringify(normalized.skills), new Date().toISOString());
+  } finally {
+    database.close();
+  }
+}

package/src/database/index.ts

@@ -0,0 +1,28 @@
+import { mkdirSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Database } from "bun:sqlite";
+import { dataDirectory, databasePath } from "@/local-data/paths.ts";
+import { migrate } from "@/database/migrations.ts";
+
+export function openDatabase(path = databasePath): Database {
+  mkdirSync(dirname(path), { recursive: true });
+  const database = new Database(path);
+  database.exec("pragma journal_mode = WAL; pragma foreign_keys = ON; pragma busy_timeout = 5000;");
+  migrate(database);
+  return database;
+}
+
+export function ensureDatabase(path = databasePath): void {
+  const database = openDatabase(path);
+  database.close();
+}
+
+export async function dataDirectoryExists(path = dataDirectory): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/database/migrations.ts

@@ -0,0 +1,100 @@
+import type { Database } from "bun:sqlite";
+
+export const schemaVersion = 2;
+
+export function migrate(database: Database): void {
+  const version = userVersion(database);
+  if (version > schemaVersion) throw new Error(`Database schema ${version} is newer than this app supports.`);
+  if (version === 0) createSchema(database);
+  else if (version === 1) migrateFromVersionOne(database);
+}
+
+export function userVersion(database: Database): number {
+  const row = database.query("pragma user_version").get() as { user_version?: number } | undefined;
+  return row?.user_version ?? 0;
+}
+
+function createSchema(database: Database): void {
+  database.exec(`
+    begin;
+    create table attempts (
+      question_id text primary key,
+      outcome text not null check (outcome in ('correct', 'incorrect', 'corrected')),
+      answered_at text not null,
+      duration_seconds integer not null default 0,
+      difficulty text,
+      domain text,
+      skill text
+    );
+    create table attempt_events (
+      id integer primary key autoincrement,
+      question_id text not null,
+      correct integer not null check (correct in (0, 1)),
+      answered_at text not null,
+      duration_seconds integer not null default 0,
+      difficulty text not null,
+      domain text not null,
+      skill text not null
+    );
+    create table focus (
+      id integer primary key check (id = 1),
+      difficulties text not null,
+      skills text not null,
+      updated_at text not null
+    );
+    create index attempt_events_answered_at_idx on attempt_events(answered_at);
+    create index attempt_events_question_id_idx on attempt_events(question_id);
+    create index attempts_answered_at_idx on attempts(answered_at);
+    pragma user_version = ${schemaVersion};
+    commit;
+  `);
+}
+
+function migrateFromVersionOne(database: Database): void {
+  database.exec(`
+    begin;
+    create table attempts_v2 (
+      question_id text primary key,
+      outcome text not null check (outcome in ('correct', 'incorrect', 'corrected')),
+      answered_at text not null,
+      duration_seconds integer not null default 0,
+      difficulty text,
+      domain text,
+      skill text
+    );
+    insert into attempts_v2 select question_id, outcome, updated_at, elapsed_seconds, difficulty, domain, skill from attempts;
+    drop table attempts;
+    alter table attempts_v2 rename to attempts;
+
+    create table attempt_events_v2 (
+      id integer primary key autoincrement,
+      question_id text not null,
+      correct integer not null check (correct in (0, 1)),
+      answered_at text not null,
+      duration_seconds integer not null default 0,
+      difficulty text not null,
+      domain text not null,
+      skill text not null
+    );
+    insert into attempt_events_v2 (id, question_id, correct, answered_at, duration_seconds, difficulty, domain, skill)
+      select id, question_id, correct, answered_at, elapsed_seconds, difficulty, domain, skill from attempt_events;
+    drop table attempt_events;
+    alter table attempt_events_v2 rename to attempt_events;
+
+    create table focus_v2 (
+      id integer primary key check (id = 1),
+      difficulties text not null,
+      skills text not null,
+      updated_at text not null
+    );
+    insert into focus_v2 (id, difficulties, skills, updated_at) select id, difficulties, skills, updated_at from focus;
+    drop table focus;
+    alter table focus_v2 rename to focus;
+
+    create index attempt_events_answered_at_idx on attempt_events(answered_at);
+    create index attempt_events_question_id_idx on attempt_events(question_id);
+    create index attempts_answered_at_idx on attempts(answered_at);
+    pragma user_version = ${schemaVersion};
+    commit;
+  `);
+}

package/src/database/progress-repository.ts

@@ -0,0 +1,90 @@
+import type { Database } from "bun:sqlite";
+import type { Difficulty, DomainCode, SkillCode } from "@/questions/question.ts";
+import type { AnswerRecord, Attempt, AttemptEvent, Outcome } from "@/progress/attempt.ts";
+import { databasePath } from "@/local-data/paths.ts";
+import { openDatabase } from "@/database/index.ts";
+
+export function loadAttempts(path = databasePath): Map<string, Attempt> {
+  return usingDatabase(path, (database) => {
+    const rows = database.query(`select question_id, outcome, answered_at, duration_seconds, difficulty, domain, skill from attempts order by answered_at`).all() as AttemptRow[];
+    return new Map(rows.map((row) => {
+      const attempt = readAttempt(row);
+      return [attempt.questionId, attempt];
+    }));
+  });
+}
+
+export function loadAttemptEvents(path = databasePath): AttemptEvent[] {
+  return usingDatabase(path, (database) => {
+    const rows = database.query(`select question_id, correct, answered_at, duration_seconds, difficulty, domain, skill from attempt_events order by answered_at, id`).all() as EventRow[];
+    return rows.map((row) => ({
+      questionId: row.question_id,
+      correct: row.correct === 1,
+      answeredAt: row.answered_at,
+      durationSeconds: row.duration_seconds,
+      difficulty: row.difficulty as Difficulty,
+      domain: row.domain as DomainCode,
+      skill: row.skill as SkillCode,
+    }));
+  });
+}
+
+export function recordAnswer(record: AnswerRecord, path = databasePath): void {
+  usingDatabase(path, (database) => {
+    const transaction = database.transaction(() => {
+      const { event, attempt } = record;
+      database.query(`insert into attempt_events (question_id, correct, answered_at, duration_seconds, difficulty, domain, skill) values (?, ?, ?, ?, ?, ?, ?)`)
+        .run(event.questionId, event.correct ? 1 : 0, event.answeredAt, event.durationSeconds, event.difficulty, event.domain, event.skill);
+      database.query(`insert into attempts (question_id, outcome, answered_at, duration_seconds, difficulty, domain, skill) values (?, ?, ?, ?, ?, ?, ?)
+        on conflict(question_id) do update set outcome = excluded.outcome, answered_at = excluded.answered_at, duration_seconds = excluded.duration_seconds, difficulty = excluded.difficulty, domain = excluded.domain, skill = excluded.skill`)
+        .run(attempt.questionId, attempt.outcome, attempt.answeredAt, attempt.durationSeconds, attempt.difficulty ?? null, attempt.domain ?? null, attempt.skill ?? null);
+    });
+    transaction();
+  });
+}
+
+type AttemptRow = {
+  question_id: string;
+  outcome: string;
+  answered_at: string;
+  duration_seconds: number;
+  difficulty: string | null;
+  domain: string | null;
+  skill: string | null;
+};
+
+type EventRow = {
+  question_id: string;
+  correct: number;
+  answered_at: string;
+  duration_seconds: number;
+  difficulty: string;
+  domain: string;
+  skill: string;
+};
+
+function readAttempt(row: AttemptRow): Attempt {
+  return {
+    questionId: row.question_id,
+    outcome: readOutcome(row.outcome),
+    answeredAt: row.answered_at,
+    durationSeconds: row.duration_seconds,
+    ...(row.difficulty ? { difficulty: row.difficulty as Difficulty } : {}),
+    ...(row.domain ? { domain: row.domain as DomainCode } : {}),
+    ...(row.skill ? { skill: row.skill as SkillCode } : {}),
+  };
+}
+
+function readOutcome(value: string): Outcome {
+  if (value === "correct" || value === "incorrect" || value === "corrected") return value;
+  throw new Error(`Invalid attempt outcome in database: ${value}`);
+}
+
+function usingDatabase<T>(path: string, work: (database: Database) => T): T {
+  const database = openDatabase(path);
+  try {
+    return work(database);
+  } finally {
+    database.close();
+  }
+}

package/src/local-data/paths.ts

@@ -0,0 +1,17 @@
+import { homedir } from "node:os";
+import { join, sep } from "node:path";
+
+export function resolveDataDirectory(home = homedir()): string {
+  return join(home, ".saterminal");
+}
+
+export const dataDirectory = resolveDataDirectory();
+export const databasePath = join(dataDirectory, "sat.db");
+export const preferencesPath = join(dataDirectory, "preferences.json");
+export const preferencesSchemaPath = join(dataDirectory, "preferences.schema.json");
+export const questionBankCachePath = join(dataDirectory, "cache", "question-bank.json");
+
+export function displayPath(path: string, home = homedir()): string {
+  if (path === home) return "~";
+  return path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+}

package/src/local-data/setup.ts

@@ -0,0 +1,25 @@
+import { mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { ensureDatabase } from "@/database/index.ts";
+import { dataDirectory } from "@/local-data/paths.ts";
+import { ensurePreferences } from "@/preferences/index.ts";
+
+export async function ensureLocalData(directory = dataDirectory): Promise<void> {
+  await mkdir(directory, { recursive: true });
+  ensureDatabase(join(directory, "sat.db"));
+  await ensurePreferences(join(directory, "preferences.json"));
+  await createIgnoreFile(join(directory, ".ignore"));
+}
+
+async function createIgnoreFile(path: string): Promise<void> {
+  try {
+    const file = await open(path, "wx", 0o600);
+    try {
+      await file.writeFile("cache\n");
+    } finally {
+      await file.close();
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+}

package/src/practice/answer-question.ts

@@ -0,0 +1,25 @@
+import { recordAnswer } from "@/database/progress-repository.ts";
+import type { Question } from "@/questions/question.ts";
+import type { Attempt, AnswerRecord } from "@/progress/attempt.ts";
+import { createAnswerRecord } from "@/progress/attempt.ts";
+
+export type AnswerQuestionInput = {
+  attempts: ReadonlyMap<string, Attempt>;
+  question: Question;
+  answer: string;
+  durationSeconds?: number;
+  answeredAt?: Date;
+  databasePath?: string;
+};
+
+export async function answerQuestion(input: AnswerQuestionInput): Promise<AnswerRecord> {
+  const record = createAnswerRecord(
+    input.attempts.get(input.question.id),
+    input.question,
+    input.answer,
+    input.durationSeconds,
+    input.answeredAt,
+  );
+  await recordAnswer(record, input.databasePath);
+  return record;
+}

package/src/practice/question-queue.ts

@@ -0,0 +1,58 @@
+import type { Attempt, AttemptEvent } from "@/progress/attempt.ts";
+import { reviewQueue, type ReviewRequirements } from "@/progress/review-queue.ts";
+import type { Focus } from "@/questions/focus.ts";
+import { findQuestion, nextQuestion } from "@/questions/local-bank.ts";
+import type { Question } from "@/questions/question.ts";
+
+export type QuestionQueue =
+  | { kind: "unanswered"; skippedIds: ReadonlySet<string> }
+  | { kind: "review"; pendingIds: readonly string[] };
+
+export type QueueResult = {
+  queue: QuestionQueue;
+  question?: Question;
+};
+
+export function unansweredQuestions(): QuestionQueue {
+  return { kind: "unanswered", skippedIds: new Set() };
+}
+
+export function questionsToReview(
+  attempts: Iterable<Attempt>,
+  events: Iterable<AttemptEvent>,
+  requirements: ReviewRequirements,
+  now = new Date(),
+): QuestionQueue {
+  return { kind: "review", pendingIds: reviewQueue(attempts, events, requirements, now) };
+}
+
+export function skipQuestion(queue: QuestionQueue, questionId: string): QuestionQueue {
+  if (queue.kind === "review") return queue;
+  return { ...queue, skippedIds: new Set([...queue.skippedIds, questionId]) };
+}
+
+export async function takeNextQuestion(
+  queue: QuestionQueue,
+  attempts: ReadonlyMap<string, Attempt>,
+  focus: Focus,
+): Promise<QueueResult> {
+  if (queue.kind === "unanswered") {
+    return {
+      queue,
+      question: await nextQuestion([...attempts.keys(), ...queue.skippedIds], focus),
+    };
+  }
+
+  const pendingIds = [...queue.pendingIds];
+  while (pendingIds.length) {
+    const question = await findQuestion(pendingIds.shift()!);
+    if (question) return { queue: { kind: "review", pendingIds }, question };
+  }
+  return { queue: { kind: "review", pendingIds } };
+}
+
+export function emptyQueueMessage(queue: QuestionQueue): string {
+  return queue.kind === "review"
+    ? "Review queue complete."
+    : "No unanswered questions match this focus.";
+}

package/src/preferences/index.ts

@@ -0,0 +1,131 @@
+import { chmod, mkdir, rename } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { preferencesPath } from "@/local-data/paths.ts";
+
+export const resultDetailLevels = ["brief", "standard", "detailed"] as const;
+export type ResultDetail = typeof resultDetailLevels[number];
+export const bundledPreferencesSchemaPath = fileURLToPath(new URL("./preferences.schema.json", import.meta.url));
+
+export type ReviewPreferences = {
+  minimumDays: number;
+  minimumAnswersAfter: number;
+};
+
+export type Preferences = {
+  review: ReviewPreferences;
+  display: {
+    resultDetail: ResultDetail;
+  };
+};
+
+export const defaultPreferences: Preferences = {
+  review: {
+    minimumDays: 7,
+    minimumAnswersAfter: 100,
+  },
+  display: {
+    resultDetail: "standard",
+  },
+};
+
+export async function ensurePreferences(path = preferencesPath): Promise<void> {
+  if (await Bun.file(path).exists()) await savePreferences(await loadPreferences(path), path);
+  else await savePreferences(defaultPreferences, path);
+}
+
+export async function loadPreferences(path = preferencesPath): Promise<Preferences> {
+  let source: string;
+  try {
+    source = await Bun.file(path).text();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return structuredClone(defaultPreferences);
+    throw error;
+  }
+
+  try {
+    return parsePreferences(JSON.parse(source));
+  } catch (error) {
+    throw new Error(`Invalid preferences at ${path}: ${message(error)}`);
+  }
+}
+
+export async function savePreferences(preferences: Preferences, path = preferencesPath): Promise<void> {
+  const normalized = parsePreferences(preferences);
+  await mkdir(dirname(path), { recursive: true });
+  await writePreferencesSchema(path);
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  const document = { $schema: `./${basename(schemaPathFor(path))}`, ...normalized };
+  await Bun.write(temporaryPath, `${JSON.stringify(document, null, 2)}\n`);
+  await chmod(temporaryPath, 0o600);
+  await rename(temporaryPath, path);
+}
+
+export function parsePreferences(value: unknown): Preferences {
+  const root = record(value, "preferences");
+  knownKeys(root, ["$schema", "review", "display"], "preferences");
+  if (root.$schema !== undefined && typeof root.$schema !== "string") throw new Error("$schema must be a string");
+  const review = root.review === undefined ? {} : record(root.review, "review");
+  knownKeys(review, ["minimumDays", "minimumAnswersAfter"], "review");
+  const display = root.display === undefined ? {} : record(root.display, "display");
+  knownKeys(display, ["resultDetail", "showTaxonomy"], "display");
+  const legacyTaxonomy = optionalBoolean(display.showTaxonomy, "display.showTaxonomy");
+  return {
+    review: {
+      minimumDays: nonNegativeInteger(review.minimumDays, "review.minimumDays", defaultPreferences.review.minimumDays),
+      minimumAnswersAfter: nonNegativeInteger(review.minimumAnswersAfter, "review.minimumAnswersAfter", defaultPreferences.review.minimumAnswersAfter),
+    },
+    display: {
+      resultDetail: resultDetail(display.resultDetail, legacyTaxonomy),
+    },
+  };
+}
+
+async function writePreferencesSchema(path: string): Promise<void> {
+  const schemaPath = schemaPathFor(path);
+  const temporaryPath = `${schemaPath}.${process.pid}.tmp`;
+  await Bun.write(temporaryPath, Bun.file(bundledPreferencesSchemaPath));
+  await chmod(temporaryPath, 0o600);
+  await rename(temporaryPath, schemaPath);
+}
+
+function schemaPathFor(path: string): string {
+  return join(dirname(path), "preferences.schema.json");
+}
+
+function record(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function knownKeys(value: Record<string, unknown>, allowed: readonly string[], name: string): void {
+  const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`unknown ${name} setting: ${unknown}`);
+}
+
+function nonNegativeInteger(value: unknown, name: string, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || (value as number) < 0) throw new Error(`${name} must be a non-negative integer`);
+  return value as number;
+}
+
+function optionalBoolean(value: unknown, name: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
+  return value;
+}
+
+function resultDetail(value: unknown, legacyTaxonomy: boolean | undefined): ResultDetail {
+  if (value === undefined) {
+    if (legacyTaxonomy !== undefined) return legacyTaxonomy ? "detailed" : "standard";
+    return defaultPreferences.display.resultDetail;
+  }
+  if (!resultDetailLevels.includes(value as ResultDetail)) {
+    throw new Error(`display.resultDetail must be one of: ${resultDetailLevels.join(", ")}`);
+  }
+  return value as ResultDetail;
+}
+
+function message(value: unknown): string {
+  return value instanceof Error ? value.message : String(value);
+}

package/src/preferences/preferences.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "saterminal preferences",
+  "description": "Local preferences for SAT practice and answer review.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Editor schema association. Managed by saterminal."
+    },
+    "review": {
+      "type": "object",
+      "description": "Spacing requirements for missed and corrected questions.",
+      "additionalProperties": false,
+      "properties": {
+        "minimumDays": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 7,
+          "description": "Days before a question becomes eligible for review."
+        },
+        "minimumAnswersAfter": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 100,
+          "description": "Later answers required before a question becomes eligible for review."
+        }
+      }
+    },
+    "display": {
+      "type": "object",
+      "description": "Controls learner-facing information in the terminal interface.",
+      "additionalProperties": false,
+      "properties": {
+        "resultDetail": {
+          "type": "string",
+          "enum": ["brief", "standard", "detailed"],
+          "default": "standard",
+          "description": "Answer-result context: brief shows time; standard adds difficulty; detailed adds taxonomy codes and labels."
+        }
+      }
+    }
+  }
+}

package/src/progress/activity.ts

@@ -0,0 +1,55 @@
+import type { AttemptEvent } from "@/progress/attempt.ts";
+
+export type ActivityDay = { date: string; count: number };
+export type Activity = {
+  streak: number;
+  activeDays: number;
+  todayCount: number;
+  totalAnswers: number;
+  days: ActivityDay[];
+};
+
+export function activity(events: readonly AttemptEvent[], now = new Date(), dayCount = 84): Activity {
+  const counts = new Map<string, number>();
+  for (const event of events) {
+    const date = new Date(event.answeredAt);
+    if (!Number.isNaN(date.getTime())) counts.set(dateKey(date), (counts.get(dateKey(date)) ?? 0) + 1);
+  }
+  const today = startOfDay(now);
+  const days = Array.from({ length: dayCount }, (_, offset) => {
+    const date = addDays(today, offset - dayCount + 1);
+    const key = dateKey(date);
+    return { date: key, count: counts.get(key) ?? 0 };
+  });
+  return {
+    streak: streak(counts, today),
+    activeDays: days.filter((day) => day.count > 0).length,
+    todayCount: counts.get(dateKey(today)) ?? 0,
+    totalAnswers: events.length,
+    days,
+  };
+}
+
+function streak(counts: Map<string, number>, today: Date): number {
+  let cursor = counts.get(dateKey(today)) ? today : addDays(today, -1);
+  let value = 0;
+  while ((counts.get(dateKey(cursor)) ?? 0) > 0) {
+    value += 1;
+    cursor = addDays(cursor, -1);
+  }
+  return value;
+}
+
+function startOfDay(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+
+function addDays(date: Date, amount: number): Date {
+  const next = new Date(date);
+  next.setDate(next.getDate() + amount);
+  return startOfDay(next);
+}
+
+function dateKey(date: Date): string {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}