MAILUO

A private, dark-net-aesthetic technician information management & query TUI — Bun + TypeScript + OpenTUI + SQLite, with application-level AES-256-GCM encryption of sensitive fields and an encrypted video vault.

See ARCHITECTURE.md for the full design (directory tree, DB schema, state machine, crypto/media-release workflow).

Requirements

• Bun ≥ 1.3
• macOS / Linux / WSL (a Unix open/xdg-open player for video playback)

Install

bun install

Run

bun start                 # launches the TUI (first run asks for a passphrase)
bun run dev               # watch mode

Data lives in a mailuo/ folder next to the program:

• Compiled binary (bun build --compile): next to the executable (<binary_dir>/mailuo/), regardless of the current working directory. If the executable itself is named mailuo (so the paths would collide), the data folder is named mailuo-data/ instead.
• Dev mode (bun start / bun run …): next to the current working directory ($cwd/mailuo/). Override with MAILUO_DATA=/path bun start.

Scripts

bun run typecheck                       # tsc --noEmit
bun run src/scripts/smoke-test.ts       # headless end-to-end verification
bun run src/scripts/init-db.ts          # create/verify DB without launching TUI
bun run src/scripts/reset-db.ts --yes   # DESTRUCTIVE wipe

Usage

• First run: create a passphrase (≥6 chars). This derives the AES-256 master key via scrypt; the key is held in memory only and never persisted.
• Press / to enter command mode, then type a command and Enter:
  • /update — add a technician (browser form)
  • /city <city> — search by city
  • /price <tag> — search by price tag (1P 2P 1h 1D BY)
  • /find <name> — search by name (substring)
  • /all — clear the active filter
  • /edit — edit the currently open technician
  • /help — command reference
  • /lock — wipe the master key, return to the passphrase screen
  • /quit — exit
• In the list: ↑ ↓ select, Enter open.
• In a detail view: M media · R add rating · E edit · C view selected rating's note · Esc back.
• In the media viewer: ← → switch · Enter decrypt + play video in the system player (temp file wiped on exit) · Esc back.
• In forms: Tab next field · Ctrl+S save · Esc cancel.
• In the web form (opened by /update or /edit), the province/city/district comboboxes support pinyin-initial search: type js to find 江苏, wx for 无锡, eeds for 鄂尔多斯, py for 番禺. Multi-tone names like 重庆 (cq) and 番禺 (py) are handled correctly.
• In the web form, the 标签 (tags) field above 备注 lets you type #tag then press Enter to add a tag chip; repeat for multiple tags. Tags are encrypted at rest and shown in the TUI detail view.
• Ctrl+C always exits.

Version control

Fossil. Stage with fossil addremove, commit with fossil commit -m "…". Do not push to a remote.