@ahmd-sh/hntui 0.3.0

package/src/api/hn.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer } from "effect"
+import { HnApiLive, HnTransport, fetchItem, resolveStory } from "./hn"
+
+// A transport made of canned JSON. The REAL HnApiLive layer — schema
+// decoding, the item cache, resolveStory's parent walk — runs on top of it,
+// hermetically. Before Layers this required monkeypatching globalThis.fetch.
+const apiWith = (db: Record<string, unknown>, log?: string[]) =>
+  HnApiLive.pipe(
+    Layer.provide(
+      Layer.succeed(HnTransport, {
+        getJson: (path) =>
+          Effect.sync(() => {
+            log?.push(path)
+            return db[path] ?? null
+          }),
+      }),
+    ),
+  )
+
+const DB = {
+  "item/1.json": { id: 1, type: "story", title: "Root story", kids: [2, 4] },
+  "item/2.json": { id: 2, type: "comment", parent: 1, text: "child" },
+  "item/3.json": { id: 3, type: "comment", parent: 2, text: "grandchild" },
+  "item/4.json": { id: 4, type: "comment", parent: 1, deleted: true },
+  "item/5.json": { id: 5, type: "story", title: "Deleted story", deleted: true },
+  "item/9.json": { id: "not-a-number", type: "story" },
+}
+
+describe("resolveStory (hermetic, via test transport layer)", () => {
+  test("a grandchild comment walks up to the root story and focuses itself", async () => {
+    const r = await Effect.runPromise(Effect.provide(resolveStory({ id: 3 }), apiWith(DB)))
+    expect(r.story.id).toBe(1)
+    expect(r.focusId).toBe(3)
+  })
+
+  test("an explicit #anchor wins over the walked-from comment", async () => {
+    const r = await Effect.runPromise(
+      Effect.provide(resolveStory({ id: 1, anchorId: 2 }), apiWith(DB)),
+    )
+    expect(r.story.id).toBe(1)
+    expect(r.focusId).toBe(2)
+  })
+
+  test("an unknown id fails with HnItemGone", async () => {
+    const e = await Effect.runPromise(
+      Effect.provide(Effect.flip(resolveStory({ id: 404 })), apiWith(DB)),
+    )
+    expect(e._tag).toBe("HnItemGone")
+  })
+
+  test("a deleted story fails with HnItemGone", async () => {
+    const e = await Effect.runPromise(
+      Effect.provide(Effect.flip(resolveStory({ id: 5 })), apiWith(DB)),
+    )
+    expect(e._tag).toBe("HnItemGone")
+  })
+
+  test("a deleted comment still walks through to its living root", async () => {
+    const r = await Effect.runPromise(Effect.provide(resolveStory({ id: 4 }), apiWith(DB)))
+    expect(r.story.id).toBe(1)
+    expect(r.focusId).toBe(4)
+  })
+
+  test("a payload that violates the schema fails with HnDecodeError", async () => {
+    const e = await Effect.runPromise(
+      Effect.provide(Effect.flip(fetchItem(9)), apiWith(DB)),
+    )
+    expect(e._tag).toBe("HnDecodeError")
+  })
+})
+
+describe("item cache (hermetic)", () => {
+  test("repeated fetches of one id hit the transport once", async () => {
+    const log: string[] = []
+    const program = Effect.gen(function* () {
+      yield* fetchItem(1)
+      yield* fetchItem(1)
+      yield* fetchItem(1)
+    })
+    await Effect.runPromise(Effect.provide(program, apiWith(DB, log)))
+    expect(log.filter((p) => p === "item/1.json")).toHaveLength(1)
+  })
+})

package/src/api/hn.ts

@@ -0,0 +1,200 @@
+import { Array as Arr, Cache, Context, Data, Duration, Effect, Layer, Schedule, Schema } from "effect"
+import { ItemSchema } from "./types"
+import type { FeedCategory, Item } from "./types"
+import type { HnItemRef } from "../utils/format"
+
+const BASE = "https://hacker-news.firebaseio.com/v0"
+
+// ---------------------------------------------------------------------------
+// Errors — every way a call can fail, as its own named type.
+// These show up in the *type* of each effect below.
+// ---------------------------------------------------------------------------
+
+export class HnRequestError extends Data.TaggedError("HnRequestError")<{
+  readonly path: string
+  readonly cause: unknown
+}> {}
+
+export class HnStatusError extends Data.TaggedError("HnStatusError")<{
+  readonly path: string
+  readonly status: number
+}> {}
+
+export class HnTimeoutError extends Data.TaggedError("HnTimeoutError")<{
+  readonly path: string
+}> {}
+
+export class HnDecodeError extends Data.TaggedError("HnDecodeError")<{
+  readonly path: string
+  readonly issue: string
+}> {}
+
+export type HnError = HnRequestError | HnStatusError | HnTimeoutError | HnDecodeError
+
+// Not an API failure — a link resolved to nothing viewable.
+export class HnItemGone extends Data.TaggedError("HnItemGone")<{
+  readonly id: number
+}> {}
+
+export interface ResolvedLink {
+  story: Item
+  // the comment the link pointed at, to focus after opening (best effort)
+  focusId?: number
+}
+
+// ---------------------------------------------------------------------------
+// HnTransport — the service that produces raw JSON. This is the app's only
+// contact with the outside world; everything above it is policy and domain
+// logic. Swapping this layer swaps the data source (live / demo / test).
+// ---------------------------------------------------------------------------
+
+export interface HnTransportShape {
+  readonly getJson: (path: string) => Effect.Effect<unknown, HnError>
+}
+
+export class HnTransport extends Context.Tag("HnTransport")<HnTransport, HnTransportShape>() {}
+
+// The live transport: fetch against Firebase. Timeout aborts the underlying
+// request (via the injected AbortSignal); transient failures retry with
+// exponential backoff, client errors don't.
+export const makeLiveGetJson =
+  (): HnTransportShape["getJson"] =>
+  (path) =>
+    Effect.gen(function* () {
+      const res = yield* Effect.tryPromise({
+        try: (signal) => fetch(`${BASE}/${path}`, { signal }),
+        catch: (cause) => new HnRequestError({ path, cause }),
+      })
+      if (!res.ok) {
+        return yield* new HnStatusError({ path, status: res.status })
+      }
+      return yield* Effect.tryPromise({
+        try: () => res.json() as Promise<unknown>,
+        catch: (cause) => new HnRequestError({ path, cause }),
+      })
+    }).pipe(
+      Effect.timeoutFail({
+        duration: "5 seconds",
+        onTimeout: () => new HnTimeoutError({ path }),
+      }),
+      Effect.retry({
+        schedule: Schedule.exponential("250 millis"),
+        times: 2,
+        while: (e) => e._tag !== "HnStatusError" || e.status >= 500,
+      }),
+    )
+
+export const HnTransportLive = Layer.succeed(HnTransport, { getJson: makeLiveGetJson() })
+
+// ---------------------------------------------------------------------------
+// HnApi — the domain service: feeds, items, link resolution. Its layer asks
+// for a transport and builds the item cache, so the cache lives exactly as
+// long as the runtime that built the layer — not "forever, from module
+// import" like the old module-global Effect.runSync version.
+// ---------------------------------------------------------------------------
+
+export interface HnApiShape {
+  readonly fetchIds: (category: FeedCategory) => Effect.Effect<number[], HnError>
+  readonly fetchItem: (id: number) => Effect.Effect<Item | null, HnError>
+  readonly fetchItems: (ids: ReadonlyArray<number>, concurrency?: number) => Effect.Effect<Item[]>
+  readonly resolveStory: (ref: HnItemRef) => Effect.Effect<ResolvedLink, HnError | HnItemGone>
+}
+
+export class HnApi extends Context.Tag("HnApi")<HnApi, HnApiShape>() {}
+
+// HN returns `null` (with a 200) for deleted/nonexistent ids — the schemas
+// say so explicitly instead of a cast papering over it.
+const IdsPayload = Schema.NullOr(Schema.mutable(Schema.Array(Schema.Number)))
+const ItemPayload = Schema.NullOr(ItemSchema)
+
+const isComment = (i: Item) => i.type === "comment" || i.type === "pollopt"
+
+export const HnApiLive = Layer.effect(
+  HnApi,
+  Effect.gen(function* () {
+    const transport = yield* HnTransport
+
+    // GET + validate: the `unknown` from the wire only becomes an A by
+    // passing through the schema.
+    const getDecoded = <A, I>(
+      path: string,
+      schema: Schema.Schema<A, I, never>,
+    ): Effect.Effect<A, HnError> =>
+      transport.getJson(path).pipe(
+        Effect.flatMap(Schema.decodeUnknown(schema)),
+        Effect.catchTag("ParseError", (e) =>
+          Effect.fail(new HnDecodeError({ path, issue: e.message })),
+        ),
+      )
+
+    // Concurrent lookups of the same id share one request, successes are
+    // memoized, failures are evicted so the next attempt refetches.
+    const cache = yield* Cache.make({
+      capacity: 50_000,
+      timeToLive: Duration.infinity,
+      lookup: (id: number) => getDecoded(`item/${id}.json`, ItemPayload),
+    })
+
+    const fetchIds: HnApiShape["fetchIds"] = (category) =>
+      getDecoded(`${category}stories.json`, IdsPayload).pipe(Effect.map((ids) => ids ?? []))
+
+    const fetchItem: HnApiShape["fetchItem"] = (id) =>
+      cache.get(id).pipe(Effect.tapError(() => cache.invalidate(id)))
+
+    // Fetch many items, at most `concurrency` in flight, failures and null
+    // items dropped, input order preserved.
+    const fetchItems: HnApiShape["fetchItems"] = (ids, concurrency = 10) =>
+      Effect.forEach(ids, (id) => fetchItem(id).pipe(Effect.option), {
+        concurrency,
+      }).pipe(
+        Effect.map((opts) => Arr.getSomes(opts).filter((x): x is Item => x !== null)),
+      )
+
+    // An /item?id=N link may point at a comment: walk `parent` upward until
+    // the root story. Every hop inherits retry/timeout/caching from
+    // fetchItem, and interruption aborts mid-chain.
+    const resolveStory: HnApiShape["resolveStory"] = (ref) =>
+      Effect.gen(function* () {
+        const gone = () => new HnItemGone({ id: ref.id })
+        const first = yield* fetchItem(ref.id)
+        if (!first) return yield* gone()
+        // deleted comments still carry `parent`, so we can walk through them
+        const fromComment = isComment(first) ? first.id : undefined
+        let cur: Item = first
+        let hops = 0
+        while (isComment(cur)) {
+          if (cur.parent == null || ++hops > 64) return yield* gone()
+          const parent: Item | null = yield* fetchItem(cur.parent)
+          if (!parent) return yield* gone()
+          cur = parent
+        }
+        if (cur.deleted || cur.dead) return yield* gone()
+        return { story: cur, focusId: ref.anchorId ?? fromComment }
+      })
+
+    return HnApi.of({ fetchIds, fetchItem, fetchItems, resolveStory })
+  }),
+)
+
+// ---------------------------------------------------------------------------
+// Accessors — call sites keep the exact shape they had. The only change is
+// in the type: `HnApi` in the R channel names the dependency, and the
+// compiler refuses to run these until something provides it.
+// ---------------------------------------------------------------------------
+
+export const fetchIds = (category: FeedCategory): Effect.Effect<number[], HnError, HnApi> =>
+  Effect.flatMap(HnApi, (api) => api.fetchIds(category))
+
+export const fetchItem = (id: number): Effect.Effect<Item | null, HnError, HnApi> =>
+  Effect.flatMap(HnApi, (api) => api.fetchItem(id))
+
+export const fetchItems = (
+  ids: ReadonlyArray<number>,
+  concurrency = 10,
+): Effect.Effect<Item[], never, HnApi> =>
+  Effect.flatMap(HnApi, (api) => api.fetchItems(ids, concurrency))
+
+export const resolveStory = (
+  ref: HnItemRef,
+): Effect.Effect<ResolvedLink, HnError | HnItemGone, HnApi> =>
+  Effect.flatMap(HnApi, (api) => api.resolveStory(ref))

package/src/api/hnDemo.ts

@@ -0,0 +1,70 @@
+import { Effect, Layer } from "effect"
+import { HnTransport, makeLiveGetJson } from "./hn"
+import type { HnTransportShape } from "./hn"
+
+// Demo transport: the live data source, plus one synthetic comment spliced
+// into the first story of the first feed the app loads. This is the typed
+// replacement for the old globalThis.fetch monkeypatch preload — select it
+// with HN_DEMO=1 (see src/runtime.ts). Real HN is never touched.
+//
+//   HN_DEMO=1 bun src/index.tsx
+//
+// The comment carries four links:
+//   1. a real HN story link   → opens in the TUI (item 1, pg's first post)
+//   2. a real HN comment link → walks to its story, cursor lands on the comment
+//   3. a broken HN link       → Not Found state
+//   4. an external link       → opens in the browser
+
+const REAL_STORY_LINK = "https://news.ycombinator.com/item?id=1"
+const REAL_COMMENT_LINK = "https://news.ycombinator.com/item?id=15"
+const BROKEN_LINK = "https://news.ycombinator.com/item?id=999999999999"
+const FAKE_ID = 999_999_001
+
+export const HnTransportLinkDemo = Layer.sync(HnTransport, () => {
+  const live = makeLiveGetJson()
+  let hookedStoryId: number | null = null
+
+  const getJson: HnTransportShape["getJson"] = (path) => {
+    // hook the first story of the first feed the app loads
+    if (/^(top|new|best|ask|show|job)stories\.json$/.test(path)) {
+      return live(path).pipe(
+        Effect.tap((ids) =>
+          Effect.sync(() => {
+            if (Array.isArray(ids) && ids.length > 0) hookedStoryId ??= ids[0] as number
+          }),
+        ),
+      )
+    }
+    if (hookedStoryId !== null && path === `item/${hookedStoryId}.json`) {
+      return live(path).pipe(
+        Effect.map((raw) => {
+          const item = raw as { kids?: number[]; descendants?: number } | null
+          if (!item) return raw
+          return {
+            ...item,
+            kids: [FAKE_ID, ...(item.kids ?? [])],
+            descendants: (item.descendants ?? 0) + 1,
+          }
+        }),
+      )
+    }
+    if (path === `item/${FAKE_ID}.json`) {
+      return Effect.succeed({
+        id: FAKE_ID,
+        type: "comment",
+        by: "link-demo",
+        time: Math.floor(Date.now() / 1000),
+        parent: hookedStoryId ?? undefined,
+        text:
+          `[SIMULATED COMMENT] Press ⏎ on me to list my links: ` +
+          `<a href="${REAL_STORY_LINK}">the first HN post ever</a>, ` +
+          `<a href="${REAL_COMMENT_LINK}">a comment under it</a>, ` +
+          `<a href="${BROKEN_LINK}">a broken HN link</a>, ` +
+          `and <a href="https://example.com/">an external link</a>.`,
+      })
+    }
+    return live(path)
+  }
+
+  return { getJson }
+})

package/src/api/types.ts

@@ -0,0 +1,40 @@
+import { Schema } from "effect"
+
+export type FeedCategory = "top" | "new" | "best" | "ask" | "show" | "job"
+export type Category = FeedCategory | "saved" | "history"
+
+export const FEED_CATEGORIES: { key: FeedCategory; label: string }[] = [
+  { key: "top", label: "Top" },
+  { key: "new", label: "New" },
+  { key: "best", label: "Best" },
+  { key: "ask", label: "Ask" },
+  { key: "show", label: "Show" },
+  { key: "job", label: "Jobs" },
+]
+
+export const ALL_CATEGORIES: Category[] = [
+  ...FEED_CATEGORIES.map((c) => c.key),
+  "history",
+  "saved",
+]
+
+// Backwards-compat alias used in older imports
+export const CATEGORIES = FEED_CATEGORIES
+
+export const ItemSchema = Schema.Struct({
+  id: Schema.Number,
+  type: Schema.Literal("story", "comment", "job", "poll", "pollopt"),
+  by: Schema.optional(Schema.String),
+  time: Schema.optional(Schema.Number),
+  text: Schema.optional(Schema.String),
+  dead: Schema.optional(Schema.Boolean),
+  deleted: Schema.optional(Schema.Boolean),
+  parent: Schema.optional(Schema.Number),
+  kids: Schema.optional(Schema.mutable(Schema.Array(Schema.Number))),
+  url: Schema.optional(Schema.String),
+  score: Schema.optional(Schema.Number),
+  title: Schema.optional(Schema.String),
+  descendants: Schema.optional(Schema.Number),
+})
+
+export type Item = typeof ItemSchema.Type

package/src/components/CommentNode.tsx

@@ -0,0 +1,81 @@
+import { useRef } from "react"
+import type { CommentNode as CN } from "../hooks/useCommentTree"
+import { htmlToText, relativeTime } from "../utils/format"
+import { selectionColors, useTheme } from "../theme"
+
+interface Props {
+  node: CN
+  depth: number
+  collapsed: boolean
+  selected: boolean
+  hiddenChildren: number
+  onSelect: () => void
+  onToggle: () => void
+  onOpenLinks: () => void
+}
+
+export function CommentNode({
+  node,
+  depth,
+  collapsed,
+  selected,
+  hiddenChildren,
+  onSelect,
+  onToggle,
+  onOpenLinks,
+}: Props) {
+  const t = useTheme()
+  const author = node.item.by ?? "?"
+  const age = relativeTime(node.item.time)
+  const body = htmlToText(node.item.text)
+  const accent = t.commentDepth[depth % t.commentDepth.length]
+  const indent = depth * 2
+  const bg = selected ? t.rowHighlight : undefined
+
+  const lastClick = useRef(0)
+  const checkDouble = () => {
+    const now = Date.now()
+    const isDouble = now - lastClick.current < 400
+    lastClick.current = now
+    return isDouble
+  }
+
+  const handleHeaderClick = () => {
+    onSelect()
+    onToggle()
+  }
+
+  const handleBodyClick = () => {
+    if (checkDouble()) {
+      onOpenLinks()
+    } else {
+      onSelect()
+    }
+  }
+
+  return (
+    <box
+      id={`comment-${node.item.id}`}
+      flexDirection="column"
+      marginLeft={indent}
+      marginTop={1}
+      backgroundColor={bg}
+    >
+      <text {...selectionColors(t)} onMouseDown={handleHeaderClick}>
+        <span fg={accent}>{selected ? "▶ " : "│ "}</span>
+        <span fg={t.accent}>{author}</span>
+        <span fg={t.textDim}>{` · ${age}`}</span>
+        {hiddenChildren > 0 || collapsed ? (
+          <span fg={t.textMuted}>
+            {` · ${collapsed ? "[+]" : "[-]"} ${hiddenChildren} repl${hiddenChildren === 1 ? "y" : "ies"}`}
+          </span>
+        ) : null}
+      </text>
+      {!collapsed && body ? (
+        <text fg={t.textBody} {...selectionColors(t)} wrapMode="word" onMouseDown={handleBodyClick}>
+          {body}
+        </text>
+      ) : null}
+    </box>
+  )
+}

package/src/components/ContextMenu.tsx

@@ -0,0 +1,78 @@
+import { useTerminalDimensions } from "@opentui/react"
+import { selectionColors, useTheme } from "../theme"
+
+export interface MenuItem {
+  label: string
+  action: () => void
+  disabled?: boolean
+}
+
+interface Props {
+  x: number
+  y: number
+  items: MenuItem[]
+  cursor: number
+  onSelect: (idx: number) => void
+  onActivate: (idx: number) => void
+  onClose: () => void
+}
+
+export function ContextMenu({ x, y, items, cursor, onSelect, onActivate, onClose }: Props) {
+  const t = useTheme()
+  const { width: termW, height: termH } = useTerminalDimensions()
+  const longest = items.reduce((n, it) => Math.max(n, it.label.length), 0)
+  const menuW = Math.min(longest + 4, 40)
+  const menuH = items.length + 2
+  const left = Math.min(Math.max(0, x), termW - menuW)
+  const top = Math.min(Math.max(0, y), termH - menuH - 1)
+
+  const hoverFg = t.name === "dark" ? "#000000" : "#ffffff"
+
+  return (
+    <box
+      position="absolute"
+      top={0}
+      left={0}
+      width="100%"
+      height="100%"
+      zIndex={200}
+      onMouseDown={onClose}
+    >
+      <box
+        position="absolute"
+        top={top}
+        left={left}
+        width={menuW}
+        flexDirection="column"
+        backgroundColor={t.menuBg}
+        border={true}
+        borderStyle="single"
+        borderColor={t.textMuted}
+        onMouseDown={(ev) => ev.stopPropagation()}
+      >
+        {items.map((item, idx) => {
+          const selected = idx === cursor
+          const fg = item.disabled ? t.textDim : selected ? hoverFg : t.text
+          const bg = selected && !item.disabled ? t.textMuted : undefined
+          return (
+            <box
+              key={idx}
+              backgroundColor={bg}
+              paddingLeft={1}
+              paddingRight={1}
+              onMouseDown={() => {
+                if (item.disabled) return
+                onActivate(idx)
+              }}
+              onMouseOver={() => {
+                if (!item.disabled) onSelect(idx)
+              }}
+            >
+              <text fg={fg} {...selectionColors(t)}>{item.label}</text>
+            </box>
+          )
+        })}
+      </box>
+    </box>
+  )
+}

package/src/components/Header.tsx

@@ -0,0 +1,89 @@
+import { TextAttributes } from "@opentui/core"
+import type { Category } from "../api/types"
+import { FEED_CATEGORIES } from "../api/types"
+import { selectionColors, useTheme } from "../theme"
+
+interface Props {
+  category: Category
+  onSelect: (c: Category) => void
+  onHome: () => void
+  showTabs?: boolean
+  // how many views are stacked beneath the current one (internal-link navigation)
+  depth?: number
+}
+
+export function Header({ category, onSelect, onHome, showTabs = true, depth = 0 }: Props) {
+  const t = useTheme()
+  return (
+    <box
+      flexDirection="column"
+      flexShrink={0}
+      height={showTabs ? 5 : 3}
+      paddingTop={1}
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={t.strip}
+      border={["bottom"]}
+      borderStyle="single"
+      borderColor={t.border}
+    >
+      <box flexDirection="row" flexShrink={0} height={1} alignItems="center" gap={2}>
+        <text
+          bg={t.brandTileBg}
+          fg={t.brandTileFg}
+          {...selectionColors(t)}
+          attributes={TextAttributes.BOLD}
+          onMouseDown={onHome}
+        >
+          {" Y "}
+        </text>
+        <text fg={t.brandText} {...selectionColors(t)} attributes={TextAttributes.BOLD}>
+          HackerNews
+        </text>
+        <text fg={t.brandSubtle} {...selectionColors(t)}>· TUI</text>
+        <box flexGrow={1} />
+        {depth > 0 ? (
+          <text fg={t.brandSubtle} {...selectionColors(t)}>{`↩ ${depth}`}</text>
+        ) : null}
+      </box>
+      {showTabs ? (
+        <box flexDirection="row" flexShrink={0} height={1} marginTop={1} gap={1}>
+          {FEED_CATEGORIES.map((c, i) => {
+            const active = c.key === category
+            return (
+              <box
+                key={c.key}
+                flexShrink={0}
+                onMouseDown={() => onSelect(c.key)}
+                backgroundColor={active ? t.tabActiveBg : undefined}
+              >
+                <text fg={active ? t.tabActiveFg : t.tabInactiveFg} {...selectionColors(t)}>
+                  {` ${i + 1} ${c.label} `}
+                </text>
+              </box>
+            )
+          })}
+          <box flexGrow={1} />
+          <box
+            flexShrink={0}
+            onMouseDown={() => onSelect("history")}
+            backgroundColor={category === "history" ? t.tabActiveBg : undefined}
+          >
+            <text fg={category === "history" ? t.tabActiveFg : t.tabInactiveFg} {...selectionColors(t)}>
+              {" [H]istory "}
+            </text>
+          </box>
+          <box
+            flexShrink={0}
+            onMouseDown={() => onSelect("saved")}
+            backgroundColor={category === "saved" ? t.tabActiveBg : undefined}
+          >
+            <text fg={category === "saved" ? t.tabActiveFg : t.tabInactiveFg} {...selectionColors(t)}>
+              {" [S]aved "}
+            </text>
+          </box>
+        </box>
+      ) : null}
+    </box>
+  )
+}