@ahmd-sh/hntui 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,10 @@
-# hntui
+<h1 align="center">hntui: Hacker News in your terminal!</h1>
 
-Hacker News in your terminal! (formerly published as `@ahmd-sh/hackernuis`)
+<p align="center">A sleek and elegant tui for browsing one of the best tech news sources.</p>
+
+<p align="center">
+  <img src=".github/assets/hntui-showcase.webp" alt="hntui — Hacker News in your terminal" width="800">
+</p>
 
 ```
 curl -fsSL https://raw.githubusercontent.com/ahmd-sh/hntui/main/install.sh | sh
@@ -30,7 +34,7 @@ The prebuilt binaries have no dependencies. Installing through npm (or hacking o
 curl -fsSL https://raw.githubusercontent.com/ahmd-sh/hntui/main/install.sh | sh
 ```
 
-Installs a self-contained binary (runtime included, nothing else needed) to `~/.local/bin`. You can also grab a binary for your platform directly from the [releases page](https://github.com/ahmd-sh/hntui/releases).
+Installs a self-contained binary to `~/.local/bin`. You can also grab a binary for your platform directly from the [releases page](https://github.com/ahmd-sh/hntui/releases). Binaries cover macOS (Apple Silicon) and Linux (x64, arm64) — on an Intel Mac, use the Bun install below.
 
 ### With Bun
 
@@ -38,7 +42,7 @@ Installs a self-contained binary (runtime included, nothing else needed) to `~/.
 bun add -g @ahmd-sh/hntui
 ```
 
-Either way the command is `hntui`. Or run it once without installing:
+Or run it once without installing:
 
 ```bash
 bunx @ahmd-sh/hntui
@@ -52,6 +56,14 @@ hntui
 
 Press `q` (or `Ctrl-C`) to quit.
 
+## Updating
+
+```bash
+hntui update
+```
+
+Checks the latest release and, for binary installs, replaces itself in place. Bun installs update with `bun add -g @ahmd-sh/hntui` instead (`hntui update` will tell you so). When a newer release exists, the status bar shows a quiet hint. `hntui --version` prints the installed version.
+
 ## Keybindings
 
 ### Story list
@@ -59,13 +71,13 @@ Press `q` (or `Ctrl-C`) to quit.
 | Key | Action |
 |---|---|
 | `j` / `↓`, `k` / `↑` | Move cursor |
-| `gg`, `Shift-G` | Jump to first or last |
+| `gg`, `G` | Jump to first or last |
 | `Ctrl-D`, `Ctrl-U`, `PgDown`, `PgUp` | Scroll a half page |
 | `c`, `Enter` | Open the story and read its comments |
 | `h` / `←`, `l` / `→` | Previous or next tab |
 | `Tab`, `Shift-Tab` | Cycle through tabs |
 | `1` through `6` | Jump to a specific category |
-| `Shift-S` | Jump to the Saved list |
+| `S` | Jump to the Saved list |
 | `s` | Save or unsave the highlighted post |
 | `o` | Open the story's URL in your browser |
 | `r` | Refresh the current feed |
@@ -77,7 +89,7 @@ Press `q` (or `Ctrl-C`) to quit.
 | Key | Action |
 |---|---|
 | `j` / `↓`, `k` / `↑` | Move the comment cursor |
-| `gg`, `Shift-G` | Jump to first or last comment |
+| `gg`, `G` | Jump to first or last comment |
 | `Ctrl-D`, `Ctrl-U`, `PgDown`, `PgUp` | Scroll a half page |
 | `Space` | Collapse or expand the current subtree |
 | `Enter` | Open the links popup for the current comment |
@@ -92,7 +104,7 @@ Press `q` (or `Ctrl-C`) to quit.
 | Key | Action |
 |---|---|
 | `j`, `k`, `↑`, `↓` | Move |
-| `gg`, `Shift-G` | First or last link |
+| `gg`, `G` | First or last link |
 | `o`, `Enter` | Open the highlighted link |
 | `Esc`, `Backspace` | Close the popup |
 
@@ -133,7 +145,7 @@ Press `t` to toggle. The dark theme is mostly black with orange accents. The lig
 
 Press `s` on any story to save it. Saved posts get a small star next to the title and show up in the Saved tab on the right side of the tab strip. The list persists across sessions in `~/.config/hntui/saved.json` as a small JSON file. (Config from the app's `hackernuis` days is migrated automatically on first run.) Press `s` again to remove a post from the list.
 
-`Shift-S` jumps straight to the Saved list from anywhere.
+`S` jumps straight to the Saved list from anywhere.
 
 ## Development
 
@@ -164,6 +176,7 @@ git push --follow-tags
 
 - [OpenTUI](https://github.com/anomalyco/opentui) by Anomaly. The native TUI core that makes all of this possible.
 - [opentui-spinner](https://github.com/msmps/opentui-spinner) by Matt Simpson. The Knight Rider loading scanner is adapted from `examples/knight-rider/utils.ts` (MIT).
+- [Effect](https://effect.website) for empowering the data layer under the hood.
 - [Hacker News](https://news.ycombinator.com) for the content and the open API.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmd-sh/hntui",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Beautiful Hacker News browser for the terminal, built on OpenTUI + React + Bun",
   "type": "module",
   "module": "src/index.tsx",

package/src/App.tsx

@@ -12,6 +12,7 @@ import { useItems } from "./hooks/useItems"
 import { flattenTree, useCommentTree } from "./hooks/useCommentTree"
 import { useSaved } from "./hooks/useSaved"
 import { useHistory } from "./hooks/useHistory"
+import { useUpdateCheck } from "./hooks/useUpdateCheck"
 import { ALL_CATEGORIES, FEED_CATEGORIES } from "./api/types"
 import type { Category, FeedCategory, Item } from "./api/types"
 import { openUrl } from "./utils/openUrl"
@@ -20,6 +21,7 @@ import { resolveStory } from "./api/hn"
 import type { HnError, HnItemGone } from "./api/hn"
 import { AppRuntime } from "./runtime"
 import { hnErrorMessage } from "./utils/errors"
+import { startThemeWipe } from "./utils/themeWipe"
 import { LinksPopup } from "./components/LinksPopup"
 import { HelpOverlay } from "./components/HelpOverlay"
 import { ContextMenu, type MenuItem } from "./components/ContextMenu"
@@ -49,6 +51,7 @@ export function App() {
   const { items: feedItems, loading: feedItemsLoading } = useItems(visibleIds)
   const { entries: savedEntries, idSet: savedIds, isSaved, toggle: toggleSave } = useSaved()
   const { entries: historyEntries, idSet: viewedIds, markViewed, clear: clearHistory } = useHistory()
+  const updateAvailable = useUpdateCheck()
 
   const savedIdList = useMemo(() => savedEntries.map((e) => e.id), [savedEntries])
   const { items: savedItemsRaw, loading: savedLoading } = useItems(
@@ -360,7 +363,10 @@ export function App() {
     }
 
     if (name === "t") {
-      setTheme((cur) => (cur.name === "dark" ? lightTheme : darkTheme))
+      const next = theme.name === "dark" ? lightTheme : darkTheme
+      // snapshot the old-theme frame BEFORE React re-renders in the new theme
+      if (renderer) startThemeWipe(renderer, String(next.accent))
+      setTheme(next)
       return
     }
 
@@ -580,6 +586,7 @@ export function App() {
           view={view.kind === "detail" ? "detail" : "list"}
           category={category}
           loading={statusLoading}
+          updateAvailable={updateAvailable}
           message={
             view.kind === "resolveError"
               ? view.error._tag === "HnItemGone"

package/src/components/StatusBar.tsx

@@ -7,9 +7,10 @@ interface Props {
   category?: Category
   loading?: boolean
   message?: string
+  updateAvailable?: string | null
 }
 
-export function StatusBar({ view, category, loading, message }: Props) {
+export function StatusBar({ view, category, loading, message, updateAvailable }: Props) {
   const t = useTheme()
   const hints =
     view === "list"
@@ -34,6 +35,9 @@ export function StatusBar({ view, category, loading, message }: Props) {
       {loading ? <Loader /> : null}
       <text fg={t.statusHint} {...selectionColors(t)}>{message ?? hints}</text>
       <box flexGrow={1} />
+      {updateAvailable ? (
+        <text fg={t.textDim} {...selectionColors(t)}>{`v${updateAvailable} · hntui update`}</text>
+      ) : null}
       <text fg={t.statusHint} {...selectionColors(t)}>? help</text>
     </box>
   )

package/src/hooks/useUpdateCheck.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from "react"
+import { Effect, Fiber } from "effect"
+import { AppRuntime } from "../runtime"
+import { VERSION } from "../version"
+import { compareVersions, fetchLatestVersion } from "../utils/selfUpdate"
+
+// One check per app launch, silently skipped when offline: returns the newer
+// version string when a release is ahead of this build, otherwise null.
+export function useUpdateCheck(): string | null {
+  const [latest, setLatest] = useState<string | null>(null)
+
+  useEffect(() => {
+    const fiber = AppRuntime.runFork(
+      // fetchLatestVersion never throws (5s timeout, null on any failure)
+      Effect.promise(() => fetchLatestVersion()).pipe(
+        Effect.andThen((v) =>
+          Effect.sync(() => {
+            if (v && compareVersions(v, VERSION) > 0) setLatest(v)
+          }),
+        ),
+      ),
+    )
+    return () => {
+      AppRuntime.runFork(Fiber.interrupt(fiber))
+    }
+  }, [])
+
+  return latest
+}

package/src/index.tsx

@@ -3,6 +3,19 @@ import { createCliRenderer } from "@opentui/core"
 import { createRoot } from "@opentui/react"
 import "opentui-spinner/react"
 import { App } from "./App"
+import { VERSION } from "./version"
+import { selfUpdate } from "./utils/selfUpdate"
 
-const renderer = await createCliRenderer({ useMouse: true })
-createRoot(renderer).render(<App />)
+const arg = process.argv[2]
+if (arg === "--version" || arg === "-v" || arg === "version") {
+  console.log(`hntui ${VERSION}`)
+  process.exit(0)
+} else if (arg === "update") {
+  process.exit(await selfUpdate())
+} else if (arg) {
+  console.error(`hntui: unknown command "${arg}"\nusage: hntui [update | --version]`)
+  process.exit(1)
+} else {
+  const renderer = await createCliRenderer({ useMouse: true })
+  createRoot(renderer).render(<App />)
+}

package/src/utils/selfUpdate.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test"
+import { compareVersions, releaseAsset } from "./selfUpdate"
+
+describe("compareVersions", () => {
+  test("orders plain versions", () => {
+    expect(compareVersions("0.4.0", "0.3.0")).toBeGreaterThan(0)
+    expect(compareVersions("0.3.0", "0.4.0")).toBeLessThan(0)
+    expect(compareVersions("0.4.0", "0.4.0")).toBe(0)
+  })
+
+  test("compares numerically, not lexically", () => {
+    expect(compareVersions("0.10.0", "0.9.0")).toBeGreaterThan(0)
+    expect(compareVersions("1.0.0", "0.99.99")).toBeGreaterThan(0)
+  })
+
+  test("tolerates missing segments", () => {
+    expect(compareVersions("1.0", "1.0.0")).toBe(0)
+    expect(compareVersions("1", "1.0.1")).toBeLessThan(0)
+  })
+})
+
+describe("releaseAsset", () => {
+  test("maps supported platforms", () => {
+    expect(releaseAsset("darwin", "arm64")).toBe("hntui-darwin-arm64.tar.gz")
+    expect(releaseAsset("linux", "x64")).toBe("hntui-linux-x64.tar.gz")
+    expect(releaseAsset("linux", "arm64")).toBe("hntui-linux-arm64.tar.gz")
+  })
+
+  test("unsupported platforms get null (Intel macOS, windows)", () => {
+    expect(releaseAsset("darwin", "x64")).toBeNull()
+    expect(releaseAsset("win32", "x64")).toBeNull()
+  })
+})

package/src/utils/selfUpdate.ts

@@ -0,0 +1,120 @@
+import { chmodSync, mkdtempSync, renameSync, rmSync } from "fs"
+import { dirname, join } from "path"
+import { VERSION } from "../version"
+
+const REPO = "ahmd-sh/hntui"
+const LATEST_URL = `https://github.com/${REPO}/releases/latest`
+
+// "1.2.3" vs "1.10.0" → negative if a < b, 0 if equal, positive if a > b
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+// which release tarball serves this machine, or null if none exists
+export function releaseAsset(platform: string, arch: string): string | null {
+  if (platform === "darwin" && arch === "arm64") return "hntui-darwin-arm64.tar.gz"
+  if (platform === "linux" && (arch === "x64" || arch === "arm64"))
+    return `hntui-linux-${arch}.tar.gz`
+  return null
+}
+
+// The releases/latest page redirects to .../tag/vX.Y.Z — the version is in a
+// header of a tiny response: no API, no auth, no rate-limit concerns.
+export async function fetchLatestVersion(timeoutMs = 5000): Promise<string | null> {
+  try {
+    const res = await fetch(LATEST_URL, {
+      redirect: "manual",
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    const location = res.headers.get("location") ?? ""
+    const m = location.match(/\/tag\/v(\d+\.\d+\.\d+)$/)
+    return m ? m[1]! : null
+  } catch {
+    return null
+  }
+}
+
+type Channel = "binary" | "bun" | "dev"
+
+// A compiled executable runs from bun's virtual filesystem; under the bun
+// runtime, a global install lives in node_modules, a source checkout doesn't.
+function installChannel(): Channel {
+  if (import.meta.url.includes("$bunfs")) return "binary"
+  return import.meta.path.includes("node_modules") ? "bun" : "dev"
+}
+
+// `hntui update` — returns a process exit code.
+export async function selfUpdate(): Promise<number> {
+  const latest = await fetchLatestVersion()
+  if (!latest) {
+    console.error("hntui: couldn't reach GitHub to check the latest release.")
+    return 1
+  }
+  if (compareVersions(latest, VERSION) <= 0) {
+    console.log(`hntui ${VERSION} is up to date (latest release is v${latest}).`)
+    return 0
+  }
+
+  console.log(`hntui ${VERSION} → v${latest} available.`)
+  const channel = installChannel()
+  if (channel === "bun") {
+    console.log("This copy was installed with Bun — update it with:\n  bun add -g @ahmd-sh/hntui")
+    return 0
+  }
+  if (channel === "dev") {
+    console.log("Running from a source checkout — update it with git pull.")
+    return 0
+  }
+
+  const asset = releaseAsset(process.platform, process.arch)
+  if (!asset) {
+    console.error(
+      `hntui: no prebuilt binary for ${process.platform}-${process.arch}.\n` +
+        "Install with Bun instead:  bun add -g @ahmd-sh/hntui",
+    )
+    return 1
+  }
+
+  const target = process.execPath
+  const targetDir = dirname(target)
+  console.log(`downloading ${asset} ...`)
+  const res = await fetch(`https://github.com/${REPO}/releases/latest/download/${asset}`)
+  if (!res.ok) {
+    console.error(`hntui: download failed (HTTP ${res.status}).`)
+    return 1
+  }
+
+  // extract in the target's own directory: the final rename must not cross
+  // filesystems, and renaming over a running executable is safe (the running
+  // process keeps its inode; the path points at the new file)
+  let tmpDir: string | null = null
+  try {
+    tmpDir = mkdtempSync(join(targetDir, ".hntui-update-"))
+    const tarPath = join(tmpDir, asset)
+    await Bun.write(tarPath, res)
+    const tar = Bun.spawn(["tar", "-xzf", tarPath, "-C", tmpDir], {
+      stdout: "ignore",
+      stderr: "pipe",
+    })
+    if ((await tar.exited) !== 0) {
+      console.error(`hntui: extract failed: ${await new Response(tar.stderr).text()}`)
+      return 1
+    }
+    const fresh = join(tmpDir, "hntui")
+    chmodSync(fresh, 0o755)
+    renameSync(fresh, target)
+    console.log(`updated to v${latest}  (${target})`)
+    return 0
+  } catch (err) {
+    console.error(`hntui: update failed: ${err}\nIs ${targetDir} writable?`)
+    return 1
+  } finally {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true })
+  }
+}

package/src/utils/themeWipe.ts

@@ -0,0 +1,109 @@
+import { RGBA } from "@opentui/core"
+import type { CliRenderer, OptimizedBuffer } from "@opentui/core"
+
+// Animated theme switch: a wave sweeps out of a random point on a random
+// screen edge and every cell flips to the new theme as the front passes it.
+//
+// It works as a renderer post-process, below React entirely: at trigger time
+// we snapshot the last OLD-theme frame (char/fg/bg/attributes per cell), let
+// React re-render the whole tree in the NEW theme underneath, and then — for
+// the duration — repaint the snapshot onto every cell the wave hasn't reached
+// yet. Cells just behind the front glow in the accent color for a beat.
+
+const DURATION_MS = 500
+const EDGE_WIDTH = 1.5
+const X_SCALE = 0.55
+
+let cancelActive: (() => void) | null = null
+
+export function startThemeWipe(renderer: CliRenderer, accentHex: string): void {
+  // re-triggering mid-wipe restarts from whatever is on screen right now
+  cancelActive?.()
+
+  const src = renderer.currentRenderBuffer
+  const width = src.width
+  const height = src.height
+  const cells = width * height
+  const snap = src.buffers
+  const snapChar = snap.char.slice(0, cells)
+  const snapAttr = snap.attributes.slice(0, cells)
+  const snapFg = snap.fg.slice(0, cells * 4)
+  const snapBg = snap.bg.slice(0, cells * 4)
+
+  // a fresh origin per wipe: anywhere along any edge (0 top, 1 right, 2 bottom, 3 left)
+  const edge = (Math.random() * 4) | 0
+  const ox = edge === 1 ? width - 1 : edge === 3 ? 0 : Math.random() * (width - 1)
+  const oy = edge === 0 ? 0 : edge === 2 ? height - 1 : Math.random() * (height - 1)
+
+  // distance of every cell from the origin
+  const dist = new Float32Array(cells)
+  let maxDist = 0
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const dx = (x - ox) * X_SCALE
+      const dy = y - oy
+      const d = Math.sqrt(dx * dx + dy * dy)
+      dist[y * width + x] = d
+      if (d > maxDist) maxDist = d
+    }
+  }
+
+  const accent = RGBA.fromHex(accentHex)
+  const fgScratch = RGBA.fromValues(0, 0, 0, 1)
+  const bgScratch = RGBA.fromValues(0, 0, 0, 1)
+  const start = performance.now()
+
+  let fn: (buffer: OptimizedBuffer, deltaTime: number) => void
+
+  const cancel = () => {
+    renderer.removePostProcessFn(fn)
+    renderer.dropLive()
+    if (cancelActive === cancel) cancelActive = null
+  }
+
+  fn = (buffer) => {
+    // terminal resized mid-wipe: the snapshot grid no longer applies
+    if (buffer.width !== width || buffer.height !== height) return cancel()
+
+    const t = Math.min(1, (performance.now() - start) / DURATION_MS)
+    const eased = 1 - (1 - t) * (1 - t) // ease-out: fast ignition, soft landing
+    const r = eased * (maxDist + EDGE_WIDTH)
+    const live = buffer.buffers
+
+    for (let i = 0; i < cells; i++) {
+      const d = dist[i]!
+      if (d <= r - EDGE_WIDTH) continue // wave passed: new theme shows through
+
+      const x = i % width
+      const y = (i / width) | 0
+      const o = i * 4
+
+      if (d <= r) {
+        // wavefront band: the just-flipped cell glows on an accent background
+        fgScratch.buffer[0] = live.fg[o]!
+        fgScratch.buffer[1] = live.fg[o + 1]!
+        fgScratch.buffer[2] = live.fg[o + 2]!
+        fgScratch.buffer[3] = live.fg[o + 3]!
+        buffer.drawChar(live.char[i]!, x, y, fgScratch, accent, live.attributes[i]!)
+        continue
+      }
+
+      // not reached yet: hold the old-theme snapshot in place
+      fgScratch.buffer[0] = snapFg[o]!
+      fgScratch.buffer[1] = snapFg[o + 1]!
+      fgScratch.buffer[2] = snapFg[o + 2]!
+      fgScratch.buffer[3] = snapFg[o + 3]!
+      bgScratch.buffer[0] = snapBg[o]!
+      bgScratch.buffer[1] = snapBg[o + 1]!
+      bgScratch.buffer[2] = snapBg[o + 2]!
+      bgScratch.buffer[3] = snapBg[o + 3]!
+      buffer.drawChar(snapChar[i]!, x, y, fgScratch, bgScratch, snapAttr[i]!)
+    }
+
+    if (t >= 1) cancel()
+  }
+
+  cancelActive = cancel
+  renderer.addPostProcessFn(fn)
+  renderer.requestLive()
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+import pkg from "../package.json"
+
+// Inlined at build time — compiled binaries carry their version with them.
+export const VERSION: string = pkg.version