@thesimonharms/basa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Harms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# basa
+
+A TUI language-learning flashcard app built on [Mudah](https://github.com/thesimonharms/mudah). Decks are plain YAML or JSON files you can edit, commit, and share. Each side of a card can be a string, or a list of `text` / `image` / `audio` fields — handy for scripts your terminal can't render reliably.
+
+## Quick start
+
+```sh
+# Run without installing — uses npx and the scoped package.
+npx @thesimonharms/basa --help
+npx @thesimonharms/basa list
+npx @thesimonharms/basa study spanish-101
+
+# Or install globally and use the short `basa` command.
+npm install -g @thesimonharms/basa
+basa list
+basa study spanish-101
+```
+
+Requires Node.js 26 or later.
+
+## Install
+
+```sh
+npm install -g @thesimonharms/basa
+```
+
+That puts a `basa` command on your `PATH`. To use a specific deck directory, set the `BASA_DECKS_DIR` env var.
+
+For local development:
+
+```sh
+git clone https://github.com/thesimonharms/basa
+cd basa
+npm install
+npm run study spanish-101
+```
+
+## Usage
+
+```sh
+# List bundled and user decks, with due-card counts.
+basa list
+
+# Open a study session. Without an argument, opens the only deck in
+# ~/basa/decks.
+basa study
+basa study spanish-101
+
+# Create an empty deck scaffold (YAML by default; --format=json for JSON).
+basa new italian-101
+basa new italian-101 --format=json
+```
+
+While studying:
+
+| Key                 | Action                                                  |
+| ------------------- | ------------------------------------------------------- |
+| `space` / `enter`   | Reveal the back of the card (with a type-on animation)   |
+| `1` … `4`           | Grade: Again / Hard / Good / Easy                       |
+| type                | Buffer your answer; submit by grading                   |
+| `n`                 | Skip the card (shown again in 30 seconds, no progress)  |
+| `esc` / `ctrl+c`    | Save and quit                                           |
+
+The first time you grade `Easy` you'll get a confetti burst; grading `Again`
+makes the card shake. Right or wrong plays a short tone if your system has
+`paplay`, `pw-play`, or `aplay` on `PATH`. No audio? Nothing happens — no
+errors.
+
+## Deck format
+
+Decks live in `~/basa/decks/*.yml` (or `.yaml`/`.json`) by default. Override
+with the `BASA_DECKS_DIR` env var or by editing `config/app.ts`.
+
+Sample decks live in the [GitHub repo](https://github.com/thesimonharms/basa/tree/main/decks) — they're not shipped in the npm package.
+
+### Minimal
+
+```yaml
+name: Spanish 101
+description: First-year Spanish vocab
+cards:
+  - front: hola
+    back: hello
+  - front: adiós
+    back: goodbye
+```
+
+### With image and audio fields
+
+Any field can be a list of `{text?, image?, audio?}` blocks. The renderer
+walks the list top-to-bottom, leaving a blank line between fields. Images
+are decoded with ImageMagick (`magick` on `PATH`) and rendered as ANSI
+half-block cells in truecolor — works in any modern terminal, no
+Kitty/SIXEL required.
+
+```yaml
+name: Japanese greetings
+cards:
+  - front:
+      - text: こんにちは
+      - image: ./assets/konnichiwa.png
+    back: hello / good afternoon
+    hint: spelled K-O-N-N-I-CHI-W-A
+  - front: ありがとう
+    back: thank you
+    audio: ./assets/aratou.wav
+```
+
+`./assets/...` is resolved relative to the deck file's directory.
+
+### Why images for scripts?
+
+Terminal font coverage for CJK, Arabic, Devanagari, and other complex
+scripts is uneven — boxes, missing glyphs, or wrong widths are common. The
+`image:` field lets you point at a PNG/JPEG of the rendered text and
+guarantee a beautiful card on every machine. Pre-render with `magick
+-font /usr/share/fonts/... -pointsize 64 label:'こんにちは' out.png` or
+whatever font pipeline you like.
+
+## Storage
+
+Progress is stored in a sibling file next to each deck: `spanish-101.yml.progress.json`.
+It holds SRS state per card, keyed by index. Delete it to start over.
+
+## Sound
+
+| Setting | Effect                                                  |
+| ------- | ------------------------------------------------------- |
+| `on`    | Always try to play (still degrades to silent if no tool) |
+| `off`   | Never play                                              |
+| `auto`  | Default. Probe `pw-play` / `paplay` / `aplay` on `PATH`  |
+
+Override per-invocation with `--no-sound`, or globally in `config/app.ts` by
+setting `sound: 'off'`.
+
+## Structure
+
+- `bin/basa.js` — executable entrypoint
+- `src/flashcards/` — pure logic (types, SRS, deck I/O, sound, image, render)
+- `src/tui/` — the TUI widgets (CardView, Header, Footer, StudyApp, effects)
+- `src/commands/` — one `*.command.ts` per CLI command
+- `decks/` — sample decks (GitHub only; not in the npm tarball)
+- `test/` — vitest unit tests
+- `config/app.ts` — schema-validated defaults
+
+## Development
+
+```sh
+npm test             # vitest run
+npm run typecheck    # tsc --noEmit
+```
+
+## Adding a command
+
+```sh
+node bin/basa.js make command quiz
+```
+
+## License
+
+[MIT](./LICENSE) © Simon Harms.

package/bin/basa.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '@mudah-cli/mudah';
+
+process.exitCode = await run();

package/config/app.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from '@mudah-cli/mudah';
+
+export default defineConfig({
+  name: 'basa',
+  env: 'local',
+  decksDir: '~/basa/decks',
+  sound: 'auto',
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@thesimonharms/basa",
+  "version": "0.1.0",
+  "description": "Basa — language-learning flashcards in your terminal",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "basa": "./bin/basa.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "config",
+    "test",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=26"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thesimonharms/basa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thesimonharms/basa/issues"
+  },
+  "homepage": "https://github.com/thesimonharms/basa#readme",
+  "scripts": {
+    "start": "node bin/basa.js",
+    "study": "node bin/basa.js study",
+    "list": "node bin/basa.js list",
+    "dev": "node bin/basa.js dev welcome",
+    "doctor": "node bin/basa.js doctor",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "publish": "./scripts/publish.sh"
+  },
+  "dependencies": {
+    "@mudah-cli/audio": "^0.5.0",
+    "@mudah-cli/mudah": "^0.5.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.0.0"
+  }
+}

package/src/commands/list.command.ts

@@ -0,0 +1,65 @@
+import { Command } from '@mudah-cli/mudah';
+import { defaultDecksDir, listDecks, loadDeck, loadReviewCards } from '../flashcards/deck.js';
+import { isDue } from '../flashcards/srs.js';
+import { renderTable, type TableColumn } from '@mudah-cli/ui';
+
+export default class ListCommand extends Command {
+  signature = 'list [--all] [--dir=]';
+  description = 'List decks (and per-deck card counts)';
+
+  async handle(): Promise<number> {
+    const flag = this.option('dir');
+    const dir = typeof flag === 'string' && flag.length > 0
+      ? flag
+      : (this.app.config().get<string>('app.decksDir') ?? defaultDecksDir());
+    const paths = await listDecks(dir);
+    if (paths.length === 0) {
+      this.output.muted(`No decks found in ${dir}.`);
+      this.output.hint(`Create one with \`basa new <name>\`, or pass --dir=<path>.`);
+      return 0;
+    }
+
+    const showAll = this.option('all') === true;
+    const now = Date.now();
+    const rows: string[][] = [];
+    let totalCards = 0;
+    let totalDue = 0;
+
+    for (const path of paths) {
+      const deck = await loadDeck(path);
+      const cards = await loadReviewCards(deck, path);
+      const due = cards.filter((c) => isDue(c.state, now)).length;
+      totalCards += cards.length;
+      totalDue += due;
+      const description = (deck.description ?? '').replace(/\s+/g, ' ').trim();
+      rows.push([
+        deck.name,
+        String(cards.length),
+        String(due),
+        truncate(description, 50),
+      ]);
+    }
+
+    if (showAll) {
+      for (const path of paths) this.output.muted(`• ${path}`);
+      this.output.raw('');
+    }
+
+    const columns: TableColumn[] = [
+      { header: 'Deck', align: 'left' },
+      { header: 'Cards', align: 'right' },
+      { header: 'Due', align: 'right' },
+      { header: 'Description', align: 'left' },
+    ];
+
+    this.output.raw(renderTable(columns, rows, { level: 0, unicode: true }));
+    this.output.raw('');
+    this.output.muted(`${totalDue} of ${totalCards} cards due across ${paths.length} decks.`);
+    return 0;
+  }
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}…`;
+}

package/src/commands/new.command.ts

@@ -0,0 +1,25 @@
+import { join } from 'node:path';
+import { Command } from '@mudah-cli/mudah';
+import { createDeck, defaultDecksDir, expandHome } from '../flashcards/deck.js';
+
+export default class NewCommand extends Command {
+  signature = 'new {name} [--format=yaml] [--dir=]';
+  description = 'Create a new empty deck';
+
+  async handle(): Promise<number> {
+    const name = this.arg('name');
+    if (name === undefined) throw new Error('Deck name is required.');
+    const format = (this.option('format') as string | undefined) ?? 'yaml';
+    const flag = this.option('dir');
+    const baseDir = typeof flag === 'string' && flag.length > 0
+      ? flag
+      : (this.app.config().get<string>('app.decksDir') ?? defaultDecksDir());
+    const dir = expandHome(baseDir);
+    const ext = format === 'json' ? '.json' : '.yml';
+    const file = join(dir, `${name}${ext}`);
+    const path = await createDeck(file, name);
+    this.output.success(`Created ${path}`);
+    this.output.hint(`Edit it, then run \`basa study ${name}\`.`);
+    return 0;
+  }
+}

package/src/commands/study.command.ts

@@ -0,0 +1,84 @@
+import { Command } from '@mudah-cli/mudah';
+import { Program } from '@mudah-cli/tui';
+import { loadDeck, loadReviewCards, resolveDeckPath, defaultDecksDir } from '../flashcards/deck.js';
+import { BasaFx } from '../flashcards/sound.js';
+import { StudyApp } from '../tui/StudyApp.js';
+
+export default class StudyCommand extends Command {
+  signature = 'study {name?} [--no-sound] [--dir=]';
+  description = 'Open a flashcard deck in the terminal';
+
+  async handle(): Promise<number> {
+    const decksDir = this.configDecksDir();
+    const deckPath = await resolveDeckPath(decksDir, this.arg('name'));
+    const deck = await loadDeck(deckPath);
+    const cards = await loadReviewCards(deck, deckPath);
+
+    const fx = await openFx(this.configSound());
+    let study: StudyApp | undefined;
+    let resizeListener: (() => void) | undefined;
+
+    const program = new Program({ mouse: true, keyboard: true, stdin: process.stdin });
+
+    const width = (process.stdout as { columns?: number }).columns ?? 80;
+    const height = (process.stdout as { rows?: number }).rows ?? 24;
+    study = new StudyApp({
+      deck,
+      deckPath,
+      cards,
+      width,
+      height,
+      fx,
+    });
+    program.mount(study.root);
+
+    // Repaint loop: Program repaints every 16ms via setInterval, but we
+    // want the StudyApp to also tick (advance animations, swap card).
+    const ticker = setInterval(() => {
+      study?.tick();
+      program.requestFrame();
+    }, 16);
+
+    // Handle terminal resize. Program's diff renderer adapts automatically
+    // to the new column count, but we need to re-render images and layout.
+    resizeListener = (): void => {
+      const w = (process.stdout as { columns?: number }).columns ?? width;
+      const h = (process.stdout as { rows?: number }).rows ?? height;
+      study?.resize(w, h);
+      program.requestFrame();
+    };
+    process.stdout.on('resize', resizeListener);
+
+    try {
+      return await program.run();
+    } finally {
+      clearInterval(ticker);
+      if (resizeListener !== undefined) process.stdout.off('resize', resizeListener);
+      await study?.persist();
+      await fx.dispose();
+    }
+  }
+
+  private configDecksDir(): string {
+    const flag = this.option('dir');
+    if (typeof flag === 'string' && flag.length > 0) return flag;
+    return this.app.config().get<string>('app.decksDir') ?? defaultDecksDir();
+  }
+
+  private configSound(): 'on' | 'off' | 'auto' {
+    const noSound = this.option('no-sound') === true;
+    if (noSound) return 'off';
+    const value = this.app.config().get<string>('app.sound');
+    if (value === 'on' || value === 'off' || value === 'auto') return value;
+    return 'auto';
+  }
+}
+
+async function openFx(setting: 'on' | 'off' | 'auto'): Promise<BasaFx> {
+  // BasaFx already handles all three settings via the same open() call:
+  // it probes for an audio backend and falls back to silent if none is
+  // available. The `setting` is reserved for future per-setting behavior
+  // (e.g. a sound-test command, a "play even in CI" override).
+  void setting;
+  return BasaFx.open();
+}

package/src/flashcards/deck.ts

@@ -0,0 +1,218 @@
+import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import yaml from 'js-yaml';
+import type { Deck, SrsState, ReviewCard } from './types.js';
+import { freshState } from './srs.js';
+
+export class DeckLoadError extends Error {
+  readonly path: string;
+  constructor(message: string, path: string) {
+    super(`${path}: ${message}`);
+    this.path = path;
+  }
+}
+
+/** Resolve a leading `~` to the user's home directory. */
+export function expandHome(p: string): string {
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  if (p === '~') return homedir();
+  return p;
+}
+
+/** The default location for user decks: `~/basa/decks`. */
+export function defaultDecksDir(): string {
+  return join(homedir(), 'basa', 'decks');
+}
+
+/** Find every supported deck file in a directory (non-recursive). */
+export async function listDecks(dir: string): Promise<string[]> {
+  const path = expandHome(dir);
+  if (!existsSync(path)) return [];
+  const entries = await readdir(path, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isFile() && /\.(ya?ml|json)$/i.test(e.name))
+    .map((e) => join(path, e.name))
+    .sort();
+}
+
+export async function loadDeck(file: string): Promise<Deck> {
+  const path = isAbsolute(file) ? file : expandHome(file);
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    throw new DeckLoadError(
+      `cannot read file: ${(err as NodeJS.ErrnoException).message}`,
+      path,
+    );
+  }
+  let parsed: unknown;
+  const ext = extname(path).toLowerCase();
+  try {
+    if (ext === '.json') {
+      parsed = JSON.parse(raw);
+    } else {
+      parsed = yaml.load(raw);
+    }
+  } catch (err) {
+    throw new DeckLoadError(
+      `parse error: ${(err as Error).message}`,
+      path,
+    );
+  }
+  return validateDeck(parsed, path);
+}
+
+function validateDeck(value: unknown, path: string): Deck {
+  if (value === null || typeof value !== 'object') {
+    throw new DeckLoadError('deck must be a mapping (name + cards)', path);
+  }
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    throw new DeckLoadError('deck.name must be a non-empty string', path);
+  }
+  if (!Array.isArray(obj.cards)) {
+    throw new DeckLoadError('deck.cards must be an array', path);
+  }
+  const cards = obj.cards.map((c, i) => validateCard(c, path, i));
+  return {
+    name: obj.name,
+    description: typeof obj.description === 'string' ? obj.description : undefined,
+    cards,
+  };
+}
+
+function validateCard(value: unknown, path: string, index: number): Deck['cards'][number] {
+  if (value === null || typeof value !== 'object') {
+    throw new DeckLoadError(`card #${index + 1} must be a mapping`, path);
+  }
+  const obj = value as Record<string, unknown>;
+  if (obj.front === undefined || obj.back === undefined) {
+    throw new DeckLoadError(`card #${index + 1} is missing front or back`, path);
+  }
+  return {
+    front: validateSide(obj.front, `card #${index + 1}.front`, path),
+    back: validateSide(obj.back, `card #${index + 1}.back`, path),
+    tags: Array.isArray(obj.tags) ? obj.tags.filter((t): t is string => typeof t === 'string') : undefined,
+    hint: typeof obj.hint === 'string' ? obj.hint : undefined,
+  };
+}
+
+function validateSide(value: unknown, where: string, path: string): Deck['cards'][number]['front'] {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map((f, i) => validateField(f, `${where}[${i}]`, path));
+  if (value !== null && typeof value === 'object') {
+    return [validateField(value, where, path)];
+  }
+  throw new DeckLoadError(`${where} must be a string, mapping, or list of fields`, path);
+}
+
+function validateField(value: unknown, where: string, path: string): { text?: string; image?: string; audio?: string } {
+  if (value === null || typeof value !== 'object') {
+    throw new DeckLoadError(`${where} must be a mapping`, path);
+  }
+  const field = value as Record<string, unknown>;
+  const out: { text?: string; image?: string; audio?: string } = {};
+  if (typeof field.text === 'string') out.text = field.text;
+  if (typeof field.image === 'string') out.image = field.image;
+  if (typeof field.audio === 'string') out.audio = field.audio;
+  if (out.text === undefined && out.image === undefined && out.audio === undefined) {
+    throw new DeckLoadError(`${where} has no text, image, or audio`, path);
+  }
+  return out;
+}
+
+/** Sibling file where SRS state is persisted, keyed by absolute deck path. */
+function progressPathFor(deckPath: string): string {
+  return `${deckPath}.progress.json`;
+}
+
+/** Load SRS state for every card, defaulting to a fresh state. */
+export async function loadReviewCards(deck: Deck, deckPath: string): Promise<ReviewCard[]> {
+  const path = progressPathFor(deckPath);
+  let saved: Record<string, SrsState> = {};
+  if (existsSync(path)) {
+    try {
+      const raw = await readFile(path, 'utf8');
+      const parsed = JSON.parse(raw) as { states?: Record<string, SrsState> };
+      if (parsed && typeof parsed === 'object' && parsed.states) saved = parsed.states;
+    } catch {
+      // Corrupt progress file: ignore and start fresh.
+    }
+  }
+  return deck.cards.map((card, i) => {
+    const key = String(i);
+    const state = saved[key] ?? freshState();
+    return { card, state };
+  });
+}
+
+/** Persist SRS state for every card. Stable across deck reorders by index. */
+export async function saveReviewCards(
+  deckPath: string,
+  cards: readonly ReviewCard[],
+): Promise<void> {
+  const path = progressPathFor(deckPath);
+  const states: Record<string, SrsState> = {};
+  cards.forEach((c, i) => {
+    states[String(i)] = c.state;
+  });
+  await writeFile(path, JSON.stringify({ version: 1, states }, null, 2) + '\n', 'utf8');
+}
+
+/** Create an empty deck file at the given path. Auto-creates parent directories. */
+export async function createDeck(file: string, name: string): Promise<string> {
+  const path = isAbsolute(file) ? file : expandHome(file);
+  if (existsSync(path)) {
+    throw new DeckLoadError('file already exists', path);
+  }
+  await mkdir(dirname(path), { recursive: true });
+  const stub: Deck = {
+    name,
+    description: 'A new Basa deck.',
+    cards: [
+      { front: 'hello', back: 'a greeting' },
+      { front: 'thanks', back: 'an expression of gratitude' },
+    ],
+  };
+  if (path.endsWith('.json')) {
+    await writeFile(path, JSON.stringify(stub, null, 2) + '\n', 'utf8');
+  } else {
+    await writeFile(path, yaml.dump(stub, { lineWidth: 120 }), 'utf8');
+  }
+  return path;
+}
+
+/** Resolve a deck name or path. With a `dir`, looks for `dir/<name>.{yml,yaml,json}`. */
+export async function resolveDeckPath(dir: string, nameOrPath: string | undefined): Promise<string> {
+  if (nameOrPath === undefined) {
+    const decks = await listDecks(dir);
+    if (decks.length === 0) {
+      throw new Error(
+        `No decks found in ${expandHome(dir)}. Create one with \`basa new <name>\`.`,
+      );
+    }
+    if (decks.length === 1) return decks[0]!;
+    throw new Error(
+      `Multiple decks in ${expandHome(dir)} — pass a deck name (e.g. \`basa study ${basename(decks[0]!, extname(decks[0]!))}\`).`,
+    );
+  }
+  // If it's a path that exists, use it directly.
+  const direct = isAbsolute(nameOrPath) ? nameOrPath : expandHome(nameOrPath);
+  if (existsSync(direct)) return direct;
+  // Otherwise try `dir/<name>.{yml,yaml,json}`.
+  const base = join(expandHome(dir), nameOrPath);
+  for (const ext of ['.yml', '.yaml', '.json']) {
+    const candidate = base + ext;
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Deck not found: ${nameOrPath} (looked in ${expandHome(dir)})`);
+}
+
+/** A relative `image` or `audio` path is resolved against the deck file's directory. */
+export function resolveMediaPath(deckPath: string, ref: string): string {
+  if (isAbsolute(ref) || ref.startsWith('~')) return expandHome(ref);
+  return resolve(dirname(deckPath), ref);
+}