@ahmd-sh/hntui 0.3.0

package/src/spinner.ts

@@ -0,0 +1,243 @@
+// Adapted from opentui-spinner (MIT) — examples/knight-rider/utils.ts by Matt Simpson
+import type { ColorInput } from "@opentui/core"
+import { RGBA } from "@opentui/core"
+import type { ColorGenerator } from "opentui-spinner"
+
+interface AdvancedGradientOptions {
+  colors: ColorInput[]
+  trailLength: number
+  defaultColor?: ColorInput
+  direction?: "forward" | "backward" | "bidirectional"
+  holdFrames?: { start?: number; end?: number }
+}
+
+interface ScannerState {
+  activePosition: number
+  isHolding: boolean
+  holdProgress: number
+  holdTotal: number
+  movementProgress: number
+  movementTotal: number
+  isMovingForward: boolean
+}
+
+function getScannerState(
+  frameIndex: number,
+  totalChars: number,
+  options: Pick<AdvancedGradientOptions, "direction" | "holdFrames">,
+): ScannerState {
+  const { direction = "forward", holdFrames = {} } = options
+
+  if (direction === "bidirectional") {
+    const forwardFrames = totalChars
+    const holdEndFrames = holdFrames.end ?? 0
+    const backwardFrames = totalChars - 1
+
+    if (frameIndex < forwardFrames) {
+      return {
+        activePosition: frameIndex,
+        isHolding: false,
+        holdProgress: 0,
+        holdTotal: 0,
+        movementProgress: frameIndex,
+        movementTotal: forwardFrames,
+        isMovingForward: true,
+      }
+    } else if (frameIndex < forwardFrames + holdEndFrames) {
+      return {
+        activePosition: totalChars - 1,
+        isHolding: true,
+        holdProgress: frameIndex - forwardFrames,
+        holdTotal: holdEndFrames,
+        movementProgress: 0,
+        movementTotal: 0,
+        isMovingForward: true,
+      }
+    } else if (frameIndex < forwardFrames + holdEndFrames + backwardFrames) {
+      const backwardIndex = frameIndex - forwardFrames - holdEndFrames
+      return {
+        activePosition: totalChars - 2 - backwardIndex,
+        isHolding: false,
+        holdProgress: 0,
+        holdTotal: 0,
+        movementProgress: backwardIndex,
+        movementTotal: backwardFrames,
+        isMovingForward: false,
+      }
+    } else {
+      return {
+        activePosition: 0,
+        isHolding: true,
+        holdProgress: frameIndex - forwardFrames - holdEndFrames - backwardFrames,
+        holdTotal: holdFrames.start ?? 0,
+        movementProgress: 0,
+        movementTotal: 0,
+        isMovingForward: false,
+      }
+    }
+  } else if (direction === "backward") {
+    return {
+      activePosition: totalChars - 1 - (frameIndex % totalChars),
+      isHolding: false,
+      holdProgress: 0,
+      holdTotal: 0,
+      movementProgress: frameIndex % totalChars,
+      movementTotal: totalChars,
+      isMovingForward: false,
+    }
+  } else {
+    return {
+      activePosition: frameIndex % totalChars,
+      isHolding: false,
+      holdProgress: 0,
+      holdTotal: 0,
+      movementProgress: frameIndex % totalChars,
+      movementTotal: totalChars,
+      isMovingForward: true,
+    }
+  }
+}
+
+function calculateColorIndex(
+  frameIndex: number,
+  charIndex: number,
+  totalChars: number,
+  options: Pick<AdvancedGradientOptions, "direction" | "holdFrames" | "trailLength">,
+): number {
+  const { trailLength } = options
+  const { activePosition, isHolding, holdProgress, isMovingForward } = getScannerState(
+    frameIndex,
+    totalChars,
+    options,
+  )
+
+  const directionalDistance = isMovingForward ? activePosition - charIndex : charIndex - activePosition
+
+  if (isHolding) {
+    return directionalDistance + holdProgress
+  }
+
+  if (directionalDistance > 0 && directionalDistance < trailLength) {
+    return directionalDistance
+  }
+
+  if (directionalDistance === 0) {
+    return 0
+  }
+
+  return -1
+}
+
+function createKnightRiderTrail(options: AdvancedGradientOptions): ColorGenerator {
+  const { colors, defaultColor } = options
+
+  const defaultRgba =
+    defaultColor instanceof RGBA ? defaultColor : RGBA.fromHex((defaultColor as string) || "#000000")
+
+  return (frameIndex: number, charIndex: number, _totalFrames: number, totalChars: number) => {
+    const index = calculateColorIndex(frameIndex, charIndex, totalChars, options)
+
+    const { isHolding, holdProgress, holdTotal, movementProgress, movementTotal } = getScannerState(
+      frameIndex,
+      totalChars,
+      options,
+    )
+
+    let alpha = 1.0
+    if (isHolding && holdTotal > 0) {
+      const progress = Math.min(holdProgress / holdTotal, 1)
+      alpha = Math.max(0, 1 - progress)
+    } else if (!isHolding && movementTotal > 0) {
+      const progress = Math.min(movementProgress / Math.max(1, movementTotal - 1), 1)
+      alpha = progress
+    }
+
+    defaultRgba.a = alpha
+
+    if (index === -1) {
+      return defaultRgba
+    }
+
+    return colors[index] ?? defaultRgba
+  }
+}
+
+export type KnightRiderStyle = "blocks" | "diamonds"
+
+export interface KnightRiderOptions {
+  width?: number
+  style?: KnightRiderStyle
+  holdStart?: number
+  holdEnd?: number
+  colors?: ColorInput[]
+  defaultColor?: ColorInput
+}
+
+export function createFrames(options: KnightRiderOptions = {}): string[] {
+  const width = options.width ?? 8
+  const style = options.style ?? "diamonds"
+  const holdStart = options.holdStart ?? 30
+  const holdEnd = options.holdEnd ?? 9
+
+  const colors = options.colors ?? [
+    RGBA.fromHex("#ff0000"),
+    RGBA.fromHex("#ff5555"),
+    RGBA.fromHex("#dd0000"),
+    RGBA.fromHex("#aa0000"),
+    RGBA.fromHex("#770000"),
+    RGBA.fromHex("#440000"),
+  ]
+
+  const trailOptions = {
+    colors,
+    trailLength: colors.length,
+    defaultColor: options.defaultColor ?? RGBA.fromHex("#330000"),
+    direction: "bidirectional" as const,
+    holdFrames: { start: holdStart, end: holdEnd },
+  }
+
+  const totalFrames = width + holdEnd + (width - 1) + holdStart
+
+  const frames = Array.from({ length: totalFrames }, (_, frameIndex) => {
+    return Array.from({ length: width }, (_, charIndex) => {
+      const index = calculateColorIndex(frameIndex, charIndex, width, trailOptions)
+
+      if (style === "diamonds") {
+        const shapes = ["⬥", "◆", "⬩", "⬪"]
+        if (index >= 0 && index < trailOptions.colors.length) {
+          return shapes[Math.min(index, shapes.length - 1)]
+        }
+        return "·"
+      }
+
+      const isActive = index >= 0 && index < trailOptions.colors.length
+      return isActive ? "■" : "⬝"
+    }).join("")
+  })
+
+  return frames
+}
+
+export function createColors(options: KnightRiderOptions = {}): ColorGenerator {
+  const holdStart = options.holdStart ?? 30
+  const holdEnd = options.holdEnd ?? 9
+
+  const colors = options.colors ?? [
+    RGBA.fromHex("#ff0000"),
+    RGBA.fromHex("#ff5555"),
+    RGBA.fromHex("#dd0000"),
+    RGBA.fromHex("#aa0000"),
+    RGBA.fromHex("#770000"),
+    RGBA.fromHex("#440000"),
+  ]
+
+  const trailOptions = {
+    colors,
+    trailLength: colors.length,
+    defaultColor: options.defaultColor ?? RGBA.fromHex("#330000"),
+    direction: "bidirectional" as const,
+    holdFrames: { start: holdStart, end: holdEnd },
+  }
+
+  return createKnightRiderTrail(trailOptions)
+}

package/src/theme.ts

@@ -0,0 +1,131 @@
+import { createContext, useContext } from "react"
+import type { ColorInput } from "@opentui/core"
+
+export interface Theme {
+  name: "dark" | "light"
+
+  body: ColorInput
+  strip: ColorInput
+  border: ColorInput
+
+  brandTileBg: ColorInput
+  brandTileFg: ColorInput
+  brandText: ColorInput
+  brandSubtle: ColorInput
+
+  tabActiveBg: ColorInput
+  tabActiveFg: ColorInput
+  tabInactiveFg: ColorInput
+
+  statusHint: ColorInput
+
+  text: ColorInput
+  textBody: ColorInput
+  textMuted: ColorInput
+  textDim: ColorInput
+  textVisited: ColorInput
+
+  accent: ColorInput
+  stripAccent: ColorInput
+  link: ColorInput
+
+  rowHighlight: ColorInput
+  menuBg: ColorInput
+
+  selectionBg: ColorInput
+  selectionFg: ColorInput
+
+  scrollTrack: ColorInput
+  scrollThumb: ColorInput
+
+  commentDepth: readonly ColorInput[]
+}
+
+export const darkTheme: Theme = {
+  name: "dark",
+  body: "#0a0a0acc",
+  strip: "#0e0e0e",
+  border: "#2a2a2a",
+
+  brandTileBg: "#ff6600",
+  brandTileFg: "#000000",
+  brandText: "#ff6600",
+  brandSubtle: "#888888",
+
+  tabActiveBg: "#ff6600",
+  tabActiveFg: "#000000",
+  tabInactiveFg: "#cccccc",
+
+  statusHint: "#888888",
+
+  text: "#ffffff",
+  textBody: "#dddddd",
+  textMuted: "#aaaaaa",
+  textDim: "#666666",
+  textVisited: "#666666",
+
+  accent: "#ff6600",
+  stripAccent: "#ff6600",
+  link: "#4488ff",
+
+  rowHighlight: "#ffffff1a",
+  menuBg: "#1a1a1a",
+
+  selectionBg: "#ffffff",
+  selectionFg: "#000000",
+
+  scrollTrack: "#1a1a1a",
+  scrollThumb: "#555555",
+
+  commentDepth: ["#ff6600", "#ffaa44", "#ffd58a", "#88ccff", "#aa88ff", "#ff88cc"],
+}
+
+export const lightTheme: Theme = {
+  name: "light",
+  body: "#f6f6ef",
+  strip: "#ff6600",
+  border: "#f6f6ef",
+
+  brandTileBg: "#ffffff",
+  brandTileFg: "#000000",
+  brandText: "#000000",
+  brandSubtle: "#5a2200",
+
+  tabActiveBg: "#ffffff",
+  tabActiveFg: "#000000",
+  tabInactiveFg: "#000000",
+
+  statusHint: "#000000",
+
+  text: "#000000",
+  textBody: "#000000",
+  textMuted: "#000000",
+  textDim: "#000000",
+  textVisited: "#828282",
+
+  accent: "#ff6600",
+  stripAccent: "#000000",
+  link: "#4488ff",
+
+  rowHighlight: "#ffffff",
+  menuBg: "#f6f6ef",
+
+  selectionBg: "#000000",
+  selectionFg: "#ffffff",
+
+  scrollTrack: "#ffffff",
+  scrollThumb: "#828282",
+
+  commentDepth: ["#ff6600", "#cc5200", "#993d00", "#0066cc", "#6633aa", "#aa3366"],
+}
+
+export const ThemeContext = createContext<Theme>(darkTheme)
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext)
+}
+
+/** Spread onto <text> so mouse selection inverts properly in both themes. */
+export function selectionColors(t: Theme): { selectionBg: ColorInput; selectionFg: ColorInput } {
+  return { selectionBg: t.selectionBg, selectionFg: t.selectionFg }
+}

package/src/utils/configDir.ts

@@ -0,0 +1,22 @@
+import { homedir } from "os"
+import { join } from "path"
+import { existsSync, renameSync } from "fs"
+
+const OLD_DIR = join(homedir(), ".config", "hackernuis")
+const NEW_DIR = join(homedir(), ".config", "hntui")
+
+let checked = false
+
+// The app was renamed from hackernuis to hntui: move existing config
+// (saved posts, view history) to the new location. Once, best-effort.
+export function configDir(): string {
+  if (!checked) {
+    checked = true
+    try {
+      if (!existsSync(NEW_DIR) && existsSync(OLD_DIR)) renameSync(OLD_DIR, NEW_DIR)
+    } catch {
+      // fall through — the stores create the dir on write anyway
+    }
+  }
+  return NEW_DIR
+}

package/src/utils/errors.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test"
+import { HnDecodeError, HnRequestError, HnStatusError, HnTimeoutError } from "../api/hn"
+import { hnErrorMessage } from "./errors"
+
+describe("hnErrorMessage", () => {
+  test("network failure suggests checking the connection", () => {
+    expect(hnErrorMessage(new HnRequestError({ path: "x", cause: 1 }))).toMatch(/connection/)
+  })
+
+  test("timeout says so", () => {
+    expect(hnErrorMessage(new HnTimeoutError({ path: "x" }))).toMatch(/too long/)
+  })
+
+  test("status errors surface the HTTP code", () => {
+    expect(hnErrorMessage(new HnStatusError({ path: "x", status: 503 }))).toContain("503")
+  })
+
+  test("decode errors are covered", () => {
+    expect(hnErrorMessage(new HnDecodeError({ path: "x", issue: "bad" }))).toMatch(/understand/)
+  })
+})

package/src/utils/errors.ts

@@ -0,0 +1,13 @@
+import { Match } from "effect"
+import type { HnError } from "../api/hn"
+
+// The last mile of typed errors: every HnError member must map to copy a
+// human can act on. Match.exhaustive makes this a compile-time guarantee —
+// adding a new error to HnError breaks this build until it gets a message.
+export const hnErrorMessage: (e: HnError) => string = Match.type<HnError>().pipe(
+  Match.tag("HnRequestError", () => "Couldn't reach Hacker News — check your connection."),
+  Match.tag("HnTimeoutError", () => "Hacker News took too long to respond."),
+  Match.tag("HnStatusError", (e) => `Hacker News returned HTTP ${e.status}.`),
+  Match.tag("HnDecodeError", () => "Hacker News sent a response the app couldn't understand."),
+  Match.exhaustive,
+)

package/src/utils/format.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test"
+import { parseHnItemLink } from "./format"
+
+describe("parseHnItemLink", () => {
+  test("story link", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=8863")).toEqual({
+      id: 8863,
+      anchorId: undefined,
+    })
+  })
+
+  test("story link with comment anchor", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=8863#8917")).toEqual({
+      id: 8863,
+      anchorId: 8917,
+    })
+  })
+
+  test("www and http variants", () => {
+    expect(parseHnItemLink("http://www.news.ycombinator.com/item?id=1")).toEqual({
+      id: 1,
+      anchorId: undefined,
+    })
+  })
+
+  test("extra query params are tolerated", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=42&p=2")?.id).toBe(42)
+  })
+
+  test("non-item HN pages are external", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/user?id=pg")).toBeNull()
+    expect(parseHnItemLink("https://news.ycombinator.com/newest")).toBeNull()
+  })
+
+  test("other hosts are external", () => {
+    expect(parseHnItemLink("https://example.com/item?id=1")).toBeNull()
+    expect(parseHnItemLink("https://hn.algolia.com/item?id=1")).toBeNull()
+  })
+
+  test("missing or malformed ids are external", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/item")).toBeNull()
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=abc")).toBeNull()
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=-5")).toBeNull()
+  })
+
+  test("non-numeric anchor is ignored, link still internal", () => {
+    expect(parseHnItemLink("https://news.ycombinator.com/item?id=7#up_8")).toEqual({
+      id: 7,
+      anchorId: undefined,
+    })
+  })
+
+  test("garbage is external", () => {
+    expect(parseHnItemLink("not a url")).toBeNull()
+  })
+})

package/src/utils/format.ts

@@ -0,0 +1,97 @@
+export function relativeTime(unixSec?: number): string {
+  if (!unixSec) return ""
+  const diff = Math.floor(Date.now() / 1000 - unixSec)
+  if (diff < 60) return `${diff}s ago`
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
+  if (diff < 86400 * 30) return `${Math.floor(diff / 86400)}d ago`
+  if (diff < 86400 * 365) return `${Math.floor(diff / 2592000)}mo ago`
+  return `${Math.floor(diff / 31536000)}y ago`
+}
+
+export function hostname(url?: string): string {
+  if (!url) return ""
+  try {
+    return new URL(url).hostname.replace(/^www\./, "")
+  } catch {
+    return ""
+  }
+}
+
+const ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#x27;": "'",
+  "&#39;": "'",
+  "&#x2F;": "/",
+  "&#47;": "/",
+  "&nbsp;": " ",
+}
+
+export function decodeEntities(s: string): string {
+  return s
+    .replace(/&(amp|lt|gt|quot|nbsp|#x27|#39|#x2F|#47);/g, (m) => ENTITIES[m] ?? m)
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCharCode(parseInt(n, 16)))
+}
+
+export interface Link {
+  text: string
+  url: string
+}
+
+export function extractLinks(html?: string): Link[] {
+  if (!html) return []
+  const re = /<a\s+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi
+  const out: Link[] = []
+  const seen = new Set<string>()
+  let m: RegExpExecArray | null
+  while ((m = re.exec(html))) {
+    const url = decodeEntities(m[1]!)
+    if (seen.has(url)) continue
+    seen.add(url)
+    const text = decodeEntities(m[2]!.replace(/<[^>]+>/g, "")).trim()
+    out.push({ text: text || url, url })
+  }
+  return out
+}
+
+// A link into HN itself: /item?id=POSTID or /item?id=POSTID#COMMENTID.
+// `id` may be a story OR a comment id
+export interface HnItemRef {
+  id: number
+  anchorId?: number
+}
+
+export function parseHnItemLink(url: string): HnItemRef | null {
+  try {
+    const u = new URL(url)
+    const host = u.hostname.replace(/^www\./, "")
+    if (host !== "news.ycombinator.com" || u.pathname !== "/item") return null
+    const id = Number(u.searchParams.get("id"))
+    if (!Number.isInteger(id) || id <= 0) return null
+    const anchor = Number(u.hash.slice(1))
+    const anchorId =
+      u.hash.length > 1 && Number.isInteger(anchor) && anchor > 0 ? anchor : undefined
+    return { id, anchorId }
+  } catch {
+    return null
+  }
+}
+
+export function htmlToText(html?: string): string {
+  if (!html) return ""
+  return decodeEntities(
+    html
+      .replace(/<p>/gi, "\n\n")
+      .replace(/<\/p>/gi, "")
+      .replace(/<br\s*\/?>/gi, "\n")
+      .replace(/<i>(.*?)<\/i>/gi, "$1")
+      .replace(/<a\s+href="([^"]+)"[^>]*>(.*?)<\/a>/gi, "$2 ($1)")
+      .replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/gi, "\n$1\n")
+      .replace(/<code>(.*?)<\/code>/gi, "`$1`")
+      .replace(/<[^>]+>/g, "")
+  ).trim()
+}

package/src/utils/historyStore.ts

@@ -0,0 +1,38 @@
+import { join } from "path"
+import { mkdirSync } from "fs"
+import { configDir } from "./configDir"
+
+export interface HistoryEntry {
+  id: number
+  viewedAt: number
+}
+
+export const HISTORY_CAP = 1000
+
+const HISTORY_PATH = join(configDir(), "history.json")
+
+export async function loadHistory(): Promise<HistoryEntry[]> {
+  try {
+    const file = Bun.file(HISTORY_PATH)
+    if (!(await file.exists())) return []
+    const data = await file.json()
+    if (!Array.isArray(data)) return []
+    return data
+      .filter(
+        (e): e is HistoryEntry =>
+          e && typeof e.id === "number" && typeof e.viewedAt === "number",
+      )
+      .slice(0, HISTORY_CAP)
+  } catch {
+    return []
+  }
+}
+
+export async function persistHistory(entries: HistoryEntry[]): Promise<void> {
+  try {
+    mkdirSync(configDir(), { recursive: true })
+    await Bun.write(HISTORY_PATH, JSON.stringify(entries, null, 2))
+  } catch {
+    // fail silently — view history is best-effort
+  }
+}

package/src/utils/openUrl.ts

@@ -0,0 +1,10 @@
+export function openUrl(url: string): void {
+  if (!url) return
+  const cmd =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url]
+  Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" })
+}

package/src/utils/savedStore.ts

@@ -0,0 +1,34 @@
+import { join } from "path"
+import { mkdirSync } from "fs"
+import { configDir } from "./configDir"
+
+export interface SavedEntry {
+  id: number
+  savedAt: number
+}
+
+const SAVED_PATH = join(configDir(), "saved.json")
+
+export async function loadSaved(): Promise<SavedEntry[]> {
+  try {
+    const file = Bun.file(SAVED_PATH)
+    if (!(await file.exists())) return []
+    const data = await file.json()
+    if (!Array.isArray(data)) return []
+    return data.filter(
+      (e): e is SavedEntry =>
+        e && typeof e.id === "number" && typeof e.savedAt === "number",
+    )
+  } catch {
+    return []
+  }
+}
+
+export async function persistSaved(entries: SavedEntry[]): Promise<void> {
+  try {
+    mkdirSync(configDir(), { recursive: true })
+    await Bun.write(SAVED_PATH, JSON.stringify(entries, null, 2))
+  } catch {
+    // fail silently — saved state is best-effort
+  }
+}