ubuligan 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# ubuligan (TUI)
+
+```
+ ██    ██ ██████  ██    ██ ██      ██  ██████   █████  ███    ██
+ ██    ██ ██   ██ ██    ██ ██      ██ ██       ██   ██ ████   ██
+ ██    ██ ██████  ██    ██ ██      ██ ██   ███ ███████ ██ ██  ██
+ ██    ██ ██   ██ ██    ██ ██      ██ ██    ██ ██   ██ ██  ██ ██
+  ██████  ██████   ██████  ███████ ██  ██████  ██   ██ ██   ████
+        [ markdown recon // terminal access // v2 ]
+```
+
+A full-screen terminal UI for browsing Markdown content from a public GitHub
+repo. Built with [ink](https://github.com/vadimdemedes/ink) (React for the
+terminal). Sibling of the `promaster` CLI in `../cli` — same content source,
+different front-end.
+
+- Browse content folders and files without leaving the terminal.
+- **Preview Markdown right in the terminal** (rendered with `marked-terminal`).
+- Open any file in the browser as styled HTML (temporary, auto-cleaned on exit).
+- Podcast folders open their link directly.
+
+## Install
+
+### Option A — npm (global)
+
+```bash
+npm install -g ubuligan
+ubuligan list      # interactive TUI
+ubuligan help      # usage
+```
+
+### Option B — npx (no install)
+
+```bash
+npx ubuligan list
+```
+
+### Option C — from source
+
+```bash
+git clone https://github.com/jsznpm/proman
+cd proman/cli2
+npm install
+node bin/ubuligan.js list
+```
+
+### Option D — standalone binary
+
+Grab a prebuilt executable from `dist/` (or build it — see below), then run it
+directly. No Node required.
+
+```bash
+./ubuligan-linux list          # Linux
+./ubuligan-mac-arm64 list      # macOS (Apple Silicon)
+ubuligan-win.exe list          # Windows
+```
+
+## Usage
+
+```bash
+ubuligan list      # the interactive TUI
+ubuligan help      # usage
+```
+
+Point it at a different content repo:
+
+```bash
+PROMASTER_REPO=owner/repo ubuligan list
+GITHUB_TOKEN=...   # optional, raises the GitHub API rate limit above 60/hr
+```
+
+Or set it per-project in `package.json`:
+
+```json
+{ "ubuligan": { "repo": "owner/repo" } }
+```
+
+## Keys
+
+| Screen   | Keys |
+|----------|------|
+| Folders  | `↑`/`↓` move · `n`/`p` page · `Enter` open · `q` quit |
+| Files    | `↑`/`↓` move · `Space` select · `Enter` preview · `o` open in browser · `n`/`p` page · `b`/`Esc` back |
+| Preview  | `↑`/`↓` scroll · `Space` page down · `g`/`G` top/bottom · `o` open in browser · `b`/`Esc` back |
+
+## Development
+
+```bash
+npm test                          # node --test, runs all test/*.test.js
+node --test test/github.test.js   # a single file
+```
+
+The I/O layer (`github.js`, `config.js`, `render.js`, `download.js`, `open.js`)
+is copied verbatim from `../cli`; only the interactive layer (`src/ui/*`) is
+new. Network code lives solely in `github.js` so it stays testable by
+monkey-patching `globalThis.fetch`.
+
+## Build standalone executables
+
+Requires [bun](https://bun.sh):
+
+```bash
+npm run build:all   # or build:win / build:mac / build:mac-intel / build:linux
+```
+
+Output lands in `dist/` (`ubuligan-win.exe`, `ubuligan-mac-arm64`,
+`ubuligan-mac-x64`, `ubuligan-linux`).
+
+Verified with bun 1.2.21: ink's yoga WebAssembly bundles into the executable
+fine. `react-devtools-core` is listed as a direct dependency on purpose — ink
+imports it, and without it `bun --compile` fails with `Could not resolve
+"react-devtools-core"`. Keep it installed.
+
+> If a future bun version cannot embed `yoga.wasm`
+> ([bun#13552](https://github.com/oven-sh/bun/issues/13552)), ship `yoga.wasm`
+> next to the executable or use the plain `npm`/`npx` install — that path
+> always works.

package/bin/ubuligan.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { runList } from "../src/commands/list.js";
+import { HttpError } from "../src/github.js";
+import { printBanner } from "../src/banner.js";
+
+const USAGE = `ubuligan - browse Markdown from a GitHub repo in a full-screen TUI
+
+Usage:
+  ubuligan list      Pick a category, browse files, preview in the terminal,
+                     or open in the browser.
+
+Config:
+  PROMASTER_REPO=owner/repo   Source repo (or "ubuligan".repo in package.json).
+  GITHUB_TOKEN=...            Optional, raises the GitHub API rate limit.`;
+
+async function main() {
+  const cmd = process.argv[2];
+  switch (cmd) {
+    case "list":
+      await runList();
+      break;
+    case undefined:
+    case "-h":
+    case "--help":
+    case "help":
+      printBanner();
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      printBanner();
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  if (err && err.name === "ExitPromptError") {
+    process.exitCode = 130;
+    return;
+  }
+  if (err instanceof HttpError) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  console.error(err?.message || String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ubuligan",
+  "version": "1.0.0",
+  "description": "Full-screen TUI (ink) to browse Markdown from a public GitHub repo, preview it in the terminal, and open it in the browser.",
+  "type": "module",
+  "bin": {
+    "ubuligan": "./bin/ubuligan.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "build:win": "bun build ./bin/ubuligan.js --compile --target=bun-windows-x64 --outfile dist/ubuligan-win.exe",
+    "build:mac": "bun build ./bin/ubuligan.js --compile --target=bun-darwin-arm64 --outfile dist/ubuligan-mac-arm64",
+    "build:mac-intel": "bun build ./bin/ubuligan.js --compile --target=bun-darwin-x64 --outfile dist/ubuligan-mac-x64",
+    "build:linux": "bun build ./bin/ubuligan.js --compile --target=bun-linux-x64 --outfile dist/ubuligan-linux",
+    "build:all": "bun run build:win && bun run build:mac && bun run build:mac-intel && bun run build:linux"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "tui",
+    "ink",
+    "markdown",
+    "github"
+  ],
+  "license": "MIT",
+  "ubuligan": {
+    "repo": "jsznpm/proman"
+  },
+  "dependencies": {
+    "htm": "^3.1.1",
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "marked": "^14.0.0",
+    "marked-terminal": "^7.3.0",
+    "react": "^18.3.1",
+    "react-devtools-core": "^4.28.5"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
+  }
+}

package/src/actions.js

@@ -0,0 +1,60 @@
+import { rmSync } from "node:fs";
+import { fetchRaw } from "./github.js";
+import { saveTemp } from "./download.js";
+import { openInBrowser } from "./open.js";
+import { extractUrl } from "./util.js";
+import { isPodcastFolder } from "./config.js";
+
+// Temp dirs created for browser previews. Cleaned up best-effort on exit so
+// nothing is left on disk after the TUI quits.
+const tempDirs = [];
+
+function cleanup() {
+  while (tempDirs.length) {
+    try {
+      rmSync(tempDirs.pop(), { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+let registered = false;
+function ensureCleanupRegistered() {
+  if (registered) return;
+  registered = true;
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(130);
+  });
+}
+
+/**
+ * Fetch a file's raw Markdown content.
+ */
+export function fetchContent(file, ctx) {
+  return fetchRaw(file.download_url, ctx);
+}
+
+/**
+ * Open a file in the browser. For podcast folders the file holds a link, which
+ * is opened directly; otherwise the Markdown is rendered to a temporary HTML
+ * file and opened. Returns { ok, msg } for status display.
+ */
+export async function openInBrowserFromFile(file, folder, ctx) {
+  ensureCleanupRegistered();
+  const content = await fetchRaw(file.download_url, ctx);
+
+  if (isPodcastFolder(folder.name)) {
+    const url = extractUrl(content);
+    if (!url) return { ok: false, msg: `No link found in ${file.name}` };
+    openInBrowser(url);
+    return { ok: true, msg: `Opened ${file.name} → ${url}` };
+  }
+
+  const { path, dir } = await saveTemp(file, content);
+  tempDirs.push(dir);
+  openInBrowser(path);
+  return { ok: true, msg: `Opened in browser: ${file.name}` };
+}

package/src/banner.js

@@ -0,0 +1,29 @@
+const G = "\x1b[32m"; // green
+const GB = "\x1b[1;92m"; // bright green bold
+const DIM = "\x1b[2;32m"; // dim green
+const R = "\x1b[0m"; // reset
+
+const ART = String.raw`
+ ██    ██ ██████  ██    ██ ██      ██  ██████   █████  ███    ██
+ ██    ██ ██   ██ ██    ██ ██      ██ ██       ██   ██ ████   ██
+ ██    ██ ██████  ██    ██ ██      ██ ██   ███ ███████ ██ ██  ██
+ ██    ██ ██   ██ ██    ██ ██      ██ ██    ██ ██   ██ ██  ██ ██
+  ██████  ██████   ██████  ███████ ██  ██████  ██   ██ ██   ████
+`;
+
+const TOP = "╔══════════════════════════════════════════════════════════════╗";
+const BOT = "╚══════════════════════════════════════════════════════════════╝";
+
+const BANNER = [
+  "",
+  `${G}${TOP}${R}`,
+  `${GB}${ART.replace(/^\n+|\n+$/g, "")}${R}`,
+  `${DIM}      [ markdown recon // terminal access // v2 ]${R}`,
+  `${G}${BOT}${R}`,
+  `${DIM}  > By Javid Salimov | Software Engineer | https://github.com/javidselimov${R}`,
+  "",
+].join("\n");
+
+export function printBanner() {
+  console.log(BANNER);
+}

package/src/commands/list.js

@@ -0,0 +1,16 @@
+import { render } from "ink";
+import { resolveRepo } from "../config.js";
+import { App } from "../ui/app.js";
+import { html } from "../ui/html.js";
+import { HttpError } from "../github.js";
+
+/**
+ * Mount the full-screen TUI and wait until the user quits.
+ */
+export async function runList() {
+  const ctx = resolveRepo();
+  const { waitUntilExit } = render(html`<${App} ctx=${ctx} />`);
+  await waitUntilExit();
+}
+
+export { HttpError };

package/src/config.js

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Default content repo (this git repo). Override with PROMASTER_REPO if the repo name differs.
+const DEFAULT_REPO = "jsznpm/proman";
+
+// Top-level folders never shown as content categories (the CLIs' own source).
+// Dot-folders (.git, .github, ...) are skipped separately by listFolders.
+export const EXCLUDED_FOLDERS = ["cli", "cli2"];
+
+// Folder whose files hold a podcast link instead of Markdown to render.
+// Selecting such a file opens its link straight in the browser.
+export const PODCAST_FOLDER = "podcast";
+
+export function isPodcastFolder(name) {
+  return name.toLowerCase() === PODCAST_FOLDER;
+}
+
+function parseRepo(value) {
+  if (typeof value !== "string") return null;
+  const match = value.trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+function fromPackageJson() {
+  try {
+    const raw = readFileSync(resolve(process.cwd(), "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    return pkg?.ubuligan?.repo ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the source repo in priority order:
+ *   1. env PROMASTER_REPO
+ *   2. "ubuligan".repo in the current dir's package.json
+ *   3. DEFAULT_REPO constant
+ * Returns { owner, repo, token }. Throws if none is a valid "owner/repo".
+ */
+export function resolveRepo() {
+  const candidates = [process.env.PROMASTER_REPO, fromPackageJson(), DEFAULT_REPO];
+  for (const candidate of candidates) {
+    const parsed = parseRepo(candidate);
+    if (parsed) {
+      return { ...parsed, token: process.env.GITHUB_TOKEN || null };
+    }
+  }
+  throw new Error(
+    "No source repo configured. Set PROMASTER_REPO=owner/repo, add { \"ubuligan\": { \"repo\": \"owner/repo\" } } to package.json, or edit DEFAULT_REPO."
+  );
+}

package/src/download.js

@@ -0,0 +1,59 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { mdToHtml } from "./render.js";
+
+export const OUTPUT_ROOT = "ubuligan-data";
+
+/**
+ * Sanitize a GitHub file name to a safe basename (no traversal, no slashes).
+ */
+export function safeName(name) {
+  const base = basename(String(name).replace(/\\/g, "/"));
+  if (!base || base === "." || base === "..") {
+    throw new Error(`Unsafe file name: ${name}`);
+  }
+  return base;
+}
+
+/**
+ * Safe basename with its extension replaced by ".html".
+ */
+export function htmlName(name) {
+  const base = safeName(name);
+  const ext = extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  return `${stem}.html`;
+}
+
+/**
+ * Render markdown to a styled HTML document and save it under
+ * ./ubuligan-data/<category>/<name>.html. Returns the absolute path.
+ */
+export async function save(category, file, content) {
+  const dir = resolve(process.cwd(), OUTPUT_ROOT, safeName(category));
+  await mkdir(dir, { recursive: true });
+  const base = safeName(file.name);
+  const ext = extname(base);
+  const title = ext ? base.slice(0, -ext.length) : base;
+  const html = mdToHtml(content, { title });
+  const dest = resolve(dir, htmlName(file.name));
+  await writeFile(dest, html, "utf8");
+  return dest;
+}
+
+/**
+ * Render markdown to HTML in a fresh OS temp directory (never under
+ * ubuligan-data). Returns { path, dir } so the caller can delete `dir`
+ * once the user is done viewing — nothing is persisted.
+ */
+export async function saveTemp(file, content) {
+  const dir = await mkdtemp(resolve(tmpdir(), "ubuligan-"));
+  const base = safeName(file.name);
+  const ext = extname(base);
+  const title = ext ? base.slice(0, -ext.length) : base;
+  const html = mdToHtml(content, { title });
+  const path = resolve(dir, htmlName(file.name));
+  await writeFile(path, html, "utf8");
+  return { path, dir };
+}

package/src/github.js

@@ -0,0 +1,111 @@
+const API = "https://api.github.com";
+
+function headers({ token }) {
+  const h = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "ubuligan-cli",
+  };
+  if (token) h.Authorization = `Bearer ${token}`;
+  return h;
+}
+
+class HttpError extends Error {
+  constructor(message, { status, rateLimited } = {}) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.rateLimited = Boolean(rateLimited);
+  }
+}
+
+async function request(url, ctx) {
+  const res = await fetch(url, { headers: headers(ctx) });
+  if (res.ok) return res;
+  const rateLimited =
+    res.status === 403 && res.headers.get("x-ratelimit-remaining") === "0";
+  if (rateLimited) {
+    throw new HttpError(
+      "GitHub API rate limit reached (60/hr unauthenticated). Wait and retry, or set GITHUB_TOKEN.",
+      { status: 403, rateLimited: true }
+    );
+  }
+  let snippet = "";
+  try {
+    snippet = (await res.text()).slice(0, 200);
+  } catch {
+    /* ignore */
+  }
+  throw new HttpError(`GitHub API ${res.status} ${res.statusText}: ${snippet}`, {
+    status: res.status,
+  });
+}
+
+/**
+ * List top-level directories of the repo, sorted alphabetically.
+ * Skips dot-folders and any names in `exclude`.
+ * Returns [{ name, path }].
+ */
+export async function listFolders(ctx, { exclude = [] } = {}) {
+  const url = `${API}/repos/${ctx.owner}/${ctx.repo}/contents/`;
+  let res;
+  try {
+    res = await request(url, ctx);
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) return [];
+    throw err;
+  }
+  const items = await res.json();
+  if (!Array.isArray(items)) return [];
+  const skip = new Set(exclude);
+  return items
+    .filter((it) => it.type === "dir")
+    .filter((it) => !it.name.startsWith(".") && !skip.has(it.name))
+    .map((it) => ({ name: it.name, path: it.path }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * List .md files in a top-level category folder of the repo.
+ * Returns [{ name, path, download_url }].
+ */
+export async function listMarkdown(category, ctx) {
+  const url = `${API}/repos/${ctx.owner}/${ctx.repo}/contents/${encodeURIComponent(category)}`;
+  let res;
+  try {
+    res = await request(url, ctx);
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) return [];
+    throw err;
+  }
+  const items = await res.json();
+  if (!Array.isArray(items)) return [];
+  return items
+    .filter((it) => it.type === "file" && it.name.endsWith(".md"))
+    .map((it) => ({ name: it.name, path: it.path, download_url: it.download_url }));
+}
+
+/**
+ * Last commit date (ms epoch) touching a path. Returns 0 on failure.
+ */
+export async function lastCommitDate(path, ctx) {
+  const url = `${API}/repos/${ctx.owner}/${ctx.repo}/commits?path=${encodeURIComponent(path)}&per_page=1`;
+  try {
+    const res = await request(url, ctx);
+    const commits = await res.json();
+    const iso = commits?.[0]?.commit?.committer?.date;
+    const ms = iso ? Date.parse(iso) : NaN;
+    return Number.isNaN(ms) ? 0 : ms;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Fetch raw file content (utf-8 text).
+ */
+export async function fetchRaw(url, ctx) {
+  const res = await request(url, ctx);
+  return res.text();
+}
+
+export { HttpError };

package/src/markdown.js

@@ -0,0 +1,17 @@
+import { Marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+
+// Isolated Marked instance so the terminal renderer never mutates the global
+// `marked` singleton used by render.js for browser HTML.
+let instance;
+
+/**
+ * Render Markdown source to an ANSI-colored string for terminal display.
+ */
+export function renderMarkdownToAnsi(src) {
+  if (!instance) {
+    instance = new Marked();
+    instance.use(markedTerminal());
+  }
+  return String(instance.parse(String(src)));
+}

package/src/open.js

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+
+/**
+ * Open a file path OR a URL in the OS default application (browser for
+ * .html and http(s) links).
+ * Non-blocking and best-effort: failures are reported but never throw.
+ */
+export function openInBrowser(filePath) {
+  let cmd, args;
+  if (platform === "win32") {
+    // empty "" is the window title arg required by `start`
+    cmd = "cmd";
+    args = ["/c", "start", "", filePath];
+  } else if (platform === "darwin") {
+    cmd = "open";
+    args = [filePath];
+  } else {
+    cmd = "xdg-open";
+    args = [filePath];
+  }
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    child.on("error", (err) => {
+      console.error(`Could not open ${filePath}: ${err.message}`);
+    });
+    child.unref();
+  } catch (err) {
+    console.error(`Could not open ${filePath}: ${err.message}`);
+  }
+}

package/src/pagination.js

@@ -0,0 +1,34 @@
+// Pure page-math used by the TUI list screens. Page index is clamped to
+// [0, totalPages-1].
+
+/**
+ * Stateful pager over a fixed array.
+ */
+export function createPaginator(items, pageSize = 10) {
+  let page = 0;
+  const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
+  return {
+    get page() {
+      return page;
+    },
+    get totalPages() {
+      return totalPages;
+    },
+    get hasNext() {
+      return page < totalPages - 1;
+    },
+    get hasPrev() {
+      return page > 0;
+    },
+    next() {
+      if (page < totalPages - 1) page++;
+    },
+    prev() {
+      if (page > 0) page--;
+    },
+    pageItems() {
+      const start = page * pageSize;
+      return items.slice(start, start + pageSize);
+    },
+  };
+}

package/src/render.js

@@ -0,0 +1,77 @@
+import { marked } from "marked";
+
+const ESCAPE = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+
+function escapeHtml(str) {
+  return String(str).replace(/[&<>"]/g, (ch) => ESCAPE[ch]);
+}
+
+const STYLE = `
+  :root { color-scheme: light dark; }
+  body {
+    max-width: 760px;
+    margin: 2.5rem auto;
+    padding: 0 1.25rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    line-height: 1.65;
+    color: #1a1a1a;
+    background: #ffffff;
+  }
+  h1, h2, h3, h4 { line-height: 1.25; margin-top: 1.8em; }
+  h1 { border-bottom: 1px solid #e1e4e8; padding-bottom: .3em; }
+  a { color: #0969da; }
+  code {
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    font-size: .9em;
+    background: rgba(127,127,127,.15);
+    padding: .15em .35em;
+    border-radius: 4px;
+  }
+  pre {
+    background: #f6f8fa;
+    padding: 1rem;
+    border-radius: 8px;
+    overflow-x: auto;
+  }
+  pre code { background: none; padding: 0; }
+  blockquote {
+    margin: 0;
+    padding: 0 1em;
+    color: #57606a;
+    border-left: .25em solid #d0d7de;
+  }
+  table { border-collapse: collapse; width: 100%; }
+  th, td { border: 1px solid #d0d7de; padding: .5em .75em; }
+  img { max-width: 100%; }
+  @media (prefers-color-scheme: dark) {
+    body { color: #e6edf3; background: #0d1117; }
+    h1 { border-bottom-color: #30363d; }
+    a { color: #4493f8; }
+    pre { background: #161b22; }
+    blockquote { color: #8b949e; border-left-color: #30363d; }
+    th, td { border-color: #30363d; }
+  }
+`;
+
+/**
+ * Convert markdown text into a standalone, styled HTML document.
+ * @param {string} markdown raw markdown source
+ * @param {{ title?: string }} [opts]
+ * @returns {string} full HTML document
+ */
+export function mdToHtml(markdown, { title = "Document" } = {}) {
+  const body = marked.parse(String(markdown));
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}

package/src/ui/app.js

@@ -0,0 +1,86 @@
+import { useState } from "react";
+import { useApp } from "ink";
+import { html } from "./html.js";
+import { FolderList } from "./folder-list.js";
+import { FileList } from "./file-list.js";
+import { Preview } from "./preview.js";
+import { isPodcastFolder } from "../config.js";
+import { openInBrowserFromFile } from "../actions.js";
+
+/**
+ * Top-level TUI. Screen state machine: folders → files → preview.
+ */
+export function App({ ctx }) {
+  const { exit } = useApp();
+  const [screen, setScreen] = useState("folders");
+  const [folder, setFolder] = useState(null);
+  const [previewFile, setPreviewFile] = useState(null);
+  const [status, setStatus] = useState("");
+
+  async function handleOpen(picks) {
+    const msgs = [];
+    for (const f of picks) {
+      try {
+        const r = await openInBrowserFromFile(f, folder, ctx);
+        msgs.push(r.msg);
+      } catch (e) {
+        msgs.push(e?.message || String(e));
+      }
+    }
+    setStatus(msgs.join("   |   "));
+  }
+
+  async function handlePreview(file) {
+    // Podcast files hold a link, not Markdown — open it directly.
+    if (isPodcastFolder(folder.name)) {
+      await handleOpen([file]);
+      return;
+    }
+    setStatus("");
+    setPreviewFile(file);
+    setScreen("preview");
+  }
+
+  if (screen === "folders") {
+    return html`
+      <${FolderList}
+        ctx=${ctx}
+        onSelect=${(f) => {
+          setStatus("");
+          setFolder(f);
+          setScreen("files");
+        }}
+        onQuit=${exit}
+      />
+    `;
+  }
+
+  if (screen === "files") {
+    return html`
+      <${FileList}
+        ctx=${ctx}
+        folder=${folder}
+        status=${status}
+        onPreview=${handlePreview}
+        onOpen=${handleOpen}
+        onBack=${() => {
+          setStatus("");
+          setScreen("folders");
+        }}
+      />
+    `;
+  }
+
+  if (screen === "preview") {
+    return html`
+      <${Preview}
+        ctx=${ctx}
+        file=${previewFile}
+        onOpen=${() => handleOpen([previewFile])}
+        onBack=${() => setScreen("files")}
+      />
+    `;
+  }
+
+  return null;
+}

package/src/ui/file-list.js

@@ -0,0 +1,139 @@
+import { useState, useEffect } from "react";
+import { Box, Text, useInput } from "ink";
+import Spinner from "ink-spinner";
+import { html } from "./html.js";
+import { Frame } from "./frame.js";
+import { useAsync } from "./use-data.js";
+import { listMarkdown, lastCommitDate } from "../github.js";
+import { mapLimit, fmtDate } from "../util.js";
+import { COLORS } from "./theme.js";
+
+const PAGE_SIZE = 10;
+const CONCURRENCY = 5;
+
+/**
+ * Paginated multi-select over a folder's .md files. Page + cursor-within-page
+ * model so each page can be re-sorted by commit date (newest first), matching
+ * the original CLI. Commit dates are fetched lazily, per visible page.
+ *
+ * Keys: ↑/↓ move · n/p page · Space toggle · Enter preview · o open in
+ * browser · b/Esc back.
+ */
+export function FileList({ ctx, folder, status, onPreview, onOpen, onBack }) {
+  const { loading, data: files, error } = useAsync(
+    () => listMarkdown(folder.name, ctx),
+    [folder.name]
+  );
+  const [page, setPage] = useState(0);
+  const [cursor, setCursor] = useState(0);
+  const [selected, setSelected] = useState(() => new Set());
+  const [dates, setDates] = useState(() => new Map());
+
+  const totalPages = files ? Math.max(1, Math.ceil(files.length / PAGE_SIZE)) : 1;
+  const pageItems = files ? files.slice(page * PAGE_SIZE, page * PAGE_SIZE + PAGE_SIZE) : [];
+
+  // Fetch commit dates for the current page only.
+  useEffect(() => {
+    if (!files) return;
+    const missing = pageItems.filter((f) => !dates.has(f.path));
+    if (!missing.length) return;
+    let alive = true;
+    mapLimit(missing, CONCURRENCY, (f) => lastCommitDate(f.path, ctx)).then((ds) => {
+      if (!alive) return;
+      setDates((prev) => {
+        const m = new Map(prev);
+        missing.forEach((f, i) => m.set(f.path, ds[i]));
+        return m;
+      });
+    });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [files, page]);
+
+  const sorted = [...pageItems].sort(
+    (a, b) => (dates.get(b.path) ?? 0) - (dates.get(a.path) ?? 0)
+  );
+  const highlighted = sorted[Math.min(cursor, sorted.length - 1)];
+
+  useInput((input, key) => {
+    if (loading) return;
+    if (error || !files || !files.length) {
+      if (input === "b" || key.escape) onBack();
+      return;
+    }
+    const len = sorted.length;
+    if (key.downArrow || input === "j") {
+      if (cursor < len - 1) setCursor(cursor + 1);
+      else if (page < totalPages - 1) {
+        setPage(page + 1);
+        setCursor(0);
+      }
+    } else if (key.upArrow || input === "k") {
+      if (cursor > 0) setCursor(cursor - 1);
+      else if (page > 0) {
+        setPage(page - 1);
+        setCursor(PAGE_SIZE - 1);
+      }
+    } else if (input === "n" || key.rightArrow) {
+      if (page < totalPages - 1) {
+        setPage(page + 1);
+        setCursor(0);
+      }
+    } else if (input === "p" || key.leftArrow) {
+      if (page > 0) {
+        setPage(page - 1);
+        setCursor(0);
+      }
+    } else if (input === " ") {
+      if (highlighted) {
+        setSelected((prev) => {
+          const s = new Set(prev);
+          if (s.has(highlighted.path)) s.delete(highlighted.path);
+          else s.add(highlighted.path);
+          return s;
+        });
+      }
+    } else if (key.return) {
+      if (highlighted) onPreview(highlighted);
+    } else if (input === "o") {
+      const picks = selected.size
+        ? files.filter((f) => selected.has(f.path))
+        : highlighted
+        ? [highlighted]
+        : [];
+      if (picks.length) onOpen(picks);
+    } else if (input === "b" || key.escape) {
+      onBack();
+    }
+  });
+
+  if (loading)
+    return html`<${Frame} title=${folder.name}><${Text}><${Spinner} type="dots" /> Loading files…<//><//>`;
+  if (error)
+    return html`<${Frame} title=${folder.name} hint="b/Esc back"><${Text} color=${COLORS.error}>${error.message}<//><//>`;
+  if (!files.length)
+    return html`<${Frame} title=${folder.name} hint="b/Esc back"><${Text}>No .md files in "${folder.name}".<//><//>`;
+
+  return html`
+    <${Frame}
+      title=${`${folder.name} — page ${page + 1}/${totalPages} · ${selected.size} selected`}
+      status=${status}
+      hint="↑/↓ move · Space select · Enter preview · o browser · n/p page · b back"
+    >
+      ${sorted.map((f, i) => {
+        const active = i === Math.min(cursor, sorted.length - 1);
+        const checked = selected.has(f.path);
+        return html`
+          <${Box} key=${f.path}>
+            <${Text} color=${active ? COLORS.marker : COLORS.dim}>${active ? "› " : "  "}<//>
+            <${Text} color=${checked ? COLORS.selected : COLORS.dim}>${checked ? "[x] " : "[ ] "}<//>
+            <${Text} color=${active ? COLORS.selected : undefined} bold=${active}>${f.name}<//>
+            <${Text} color=${COLORS.dim}>${"  (" + fmtDate(dates.get(f.path)) + ")"}<//>
+          <//>
+        `;
+      })}
+    <//>
+  `;
+}

package/src/ui/folder-list.js

@@ -0,0 +1,68 @@
+import { useState } from "react";
+import { Text, useInput } from "ink";
+import Spinner from "ink-spinner";
+import { html } from "./html.js";
+import { Frame } from "./frame.js";
+import { useAsync } from "./use-data.js";
+import { listFolders } from "../github.js";
+import { EXCLUDED_FOLDERS } from "../config.js";
+import { COLORS } from "./theme.js";
+
+const PAGE_SIZE = 10;
+
+/**
+ * Paginated single-select over content folders. Cursor is an absolute index
+ * into the full list; the visible page is derived from it.
+ */
+export function FolderList({ ctx, onSelect, onQuit }) {
+  const { loading, data: folders, error } = useAsync(
+    () => listFolders(ctx, { exclude: EXCLUDED_FOLDERS }),
+    []
+  );
+  const [cursor, setCursor] = useState(0);
+
+  useInput((input, key) => {
+    if (loading) return;
+    if (error || !folders || !folders.length) {
+      if (input === "q") onQuit();
+      return;
+    }
+    const n = folders.length;
+    if (key.downArrow || input === "j") setCursor((c) => Math.min(n - 1, c + 1));
+    else if (key.upArrow || input === "k") setCursor((c) => Math.max(0, c - 1));
+    else if (input === "n" || key.rightArrow)
+      setCursor((c) => Math.min(n - 1, (Math.floor(c / PAGE_SIZE) + 1) * PAGE_SIZE));
+    else if (input === "p" || key.leftArrow)
+      setCursor((c) => Math.max(0, (Math.floor(c / PAGE_SIZE) - 1) * PAGE_SIZE));
+    else if (key.return) onSelect(folders[cursor]);
+    else if (input === "q") onQuit();
+  });
+
+  if (loading)
+    return html`<${Frame}><${Text}><${Spinner} type="dots" /> Loading folders…<//><//>`;
+  if (error)
+    return html`<${Frame} hint="q quit"><${Text} color=${COLORS.error}>${error.message}<//><//>`;
+  if (!folders.length)
+    return html`<${Frame} hint="q quit"><${Text}>No folders found.<//><//>`;
+
+  const page = Math.floor(cursor / PAGE_SIZE);
+  const totalPages = Math.max(1, Math.ceil(folders.length / PAGE_SIZE));
+  const start = page * PAGE_SIZE;
+  const visible = folders.slice(start, start + PAGE_SIZE);
+
+  return html`
+    <${Frame}
+      title=${`Folders — page ${page + 1}/${totalPages}`}
+      hint="↑/↓ move · n/p page · Enter open · q quit"
+    >
+      ${visible.map((f, i) => {
+        const active = start + i === cursor;
+        return html`
+          <${Text} key=${f.path} color=${active ? COLORS.selected : undefined} bold=${active}>
+            ${active ? "› " : "  "}${f.name}
+          <//>
+        `;
+      })}
+    <//>
+  `;
+}

package/src/ui/frame.js

@@ -0,0 +1,29 @@
+import { Box, Text } from "ink";
+import { html } from "./html.js";
+import { COLORS, LOGO } from "./theme.js";
+
+/**
+ * Shared screen chrome: logo header, optional subtitle, a bordered content
+ * box, and an optional key-hint / status footer.
+ */
+export function Frame({ title, hint, status, children }) {
+  return html`
+    <${Box} flexDirection="column" paddingX=${1} paddingY=${0}>
+      <${Box}>
+        <${Text} color=${COLORS.accent} bold=${true}>${LOGO}<//>
+        ${title ? html`<${Text} color=${COLORS.dim}>${"  ·  " + title}<//>` : null}
+      <//>
+      <${Box}
+        flexDirection="column"
+        borderStyle="round"
+        borderColor=${COLORS.accent}
+        paddingX=${1}
+        marginTop=${1}
+      >
+        ${children}
+      <//>
+      ${status ? html`<${Box} marginTop=${1}><${Text} color=${COLORS.warn}>${status}<//><//>` : null}
+      ${hint ? html`<${Box} marginTop=${status ? 0 : 1}><${Text} color=${COLORS.dim}>${hint}<//><//>` : null}
+    <//>
+  `;
+}

package/src/ui/html.js

@@ -0,0 +1,6 @@
+import htm from "htm";
+import { createElement } from "react";
+
+// htm bound to React.createElement — lets us write JSX-like markup with no
+// build step (plain Node ESM).
+export const html = htm.bind(createElement);

package/src/ui/preview.js

@@ -0,0 +1,61 @@
+import { useState, useMemo } from "react";
+import { Box, Text, useInput } from "ink";
+import Spinner from "ink-spinner";
+import { html } from "./html.js";
+import { Frame } from "./frame.js";
+import { useAsync } from "./use-data.js";
+import { fetchContent } from "../actions.js";
+import { renderMarkdownToAnsi } from "../markdown.js";
+import { COLORS } from "./theme.js";
+
+/**
+ * Scrollable in-terminal Markdown preview. ↑/↓ scroll one line, Space/PgDn a
+ * page, o opens in the browser, b/Esc go back.
+ */
+export function Preview({ ctx, file, onOpen, onBack }) {
+  const { loading, data: content, error } = useAsync(
+    () => fetchContent(file, ctx),
+    [file.path]
+  );
+  const [offset, setOffset] = useState(0);
+
+  const lines = useMemo(
+    () => (content != null ? renderMarkdownToAnsi(content).replace(/\n$/, "").split("\n") : []),
+    [content]
+  );
+
+  const rows = process.stdout.rows || 24;
+  const viewport = Math.max(5, rows - 8);
+  const maxOffset = Math.max(0, lines.length - viewport);
+
+  useInput((input, key) => {
+    if (input === "o") onOpen();
+    else if (input === "b" || key.escape) onBack();
+    else if (loading || error) return;
+    else if (key.downArrow || input === "j") setOffset((o) => Math.min(maxOffset, o + 1));
+    else if (key.upArrow || input === "k") setOffset((o) => Math.max(0, o - 1));
+    else if (input === " " || key.pageDown) setOffset((o) => Math.min(maxOffset, o + viewport));
+    else if (key.pageUp) setOffset((o) => Math.max(0, o - viewport));
+    else if (input === "g") setOffset(0);
+    else if (input === "G") setOffset(maxOffset);
+  });
+
+  if (loading)
+    return html`<${Frame} title=${file.name}><${Text}><${Spinner} type="dots" /> Loading…<//><//>`;
+  if (error)
+    return html`<${Frame} title=${file.name} hint="b/Esc back"><${Text} color=${COLORS.error}>${error.message}<//><//>`;
+
+  const view = lines.slice(offset, offset + viewport);
+  const atEnd = offset >= maxOffset;
+
+  return html`
+    <${Frame}
+      title=${`${file.name} — ${offset + 1}-${Math.min(offset + viewport, lines.length)}/${lines.length}`}
+      hint=${`↑/↓ scroll · Space page · g/G top/bottom · o browser · b back${atEnd ? "" : " · ▼ more"}`}
+    >
+      <${Box} flexDirection="column">
+        ${view.map((line, i) => html`<${Text} key=${offset + i} wrap="truncate-end">${line || " "}<//>`)}
+      <//>
+    <//>
+  `;
+}

package/src/ui/theme.js

@@ -0,0 +1,12 @@
+// Shared colors for the TUI. Color names are passed straight to ink's <Text>
+// / <Box> color props.
+export const COLORS = {
+  accent: "cyan",
+  selected: "green",
+  marker: "magenta",
+  dim: "gray",
+  warn: "yellow",
+  error: "red",
+};
+
+export const LOGO = "UBULIGAN";

package/src/ui/use-data.js

@@ -0,0 +1,28 @@
+import { useState, useEffect } from "react";
+
+/**
+ * Run an async function and track { loading, data, error }. Re-runs when
+ * `deps` change. Ignores results after unmount / dep change.
+ */
+export function useAsync(fn, deps) {
+  const [state, setState] = useState({ loading: true, data: null, error: null });
+  useEffect(() => {
+    let alive = true;
+    setState({ loading: true, data: null, error: null });
+    Promise.resolve()
+      .then(fn)
+      .then(
+        (data) => {
+          if (alive) setState({ loading: false, data, error: null });
+        },
+        (error) => {
+          if (alive) setState({ loading: false, data: null, error });
+        }
+      );
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+  return state;
+}

package/src/util.js

@@ -0,0 +1,32 @@
+// Pure helpers shared by the UI and tests.
+
+/**
+ * Run an async mapper over items with a bounded number of in-flight tasks.
+ * Preserves input order in the result array.
+ */
+export async function mapLimit(items, limit, mapper) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await mapper(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+/** Format a commit timestamp (ms epoch) as YYYY-MM-DD. */
+export function fmtDate(ms) {
+  return ms ? new Date(ms).toISOString().slice(0, 10) : "????-??-??";
+}
+
+/**
+ * First http(s) URL in the content. Handles a bare URL or a Markdown link
+ * like [title](https://...). Returns null if none found.
+ */
+export function extractUrl(content) {
+  const match = String(content).match(/https?:\/\/[^\s)<>"']+/);
+  return match ? match[0] : null;
+}