hn-bits 0.2.0

package/README.md

@@ -0,0 +1,122 @@
+# hn-bits
+
+Terminal-first Hacker News client. Fullscreen TUI built with TypeScript + Ink (React for the terminal), backed by the HN Firebase and Algolia APIs. No database. Optional local-AI features (summaries + Ask AI) read a config file; everything else is fully stateless.
+
+## Install
+
+```bash
+npm install
+npm run build
+npm link   # exposes the `hn` binary
+```
+
+## Usage
+
+```bash
+hn                    # fullscreen shell: top/new/best/ask/show tabs
+hn search <query...>  # search results
+hn --theme dracula    # themes: hn (default), mocha, dracula, tokyo, nord, gruvbox
+```
+
+Press `?` from any view for the full keybinding help overlay.
+
+### Local AI (summaries + Ask AI)
+
+Article/thread summaries (`s`) and interactive Q&A (`a`) run against a local [Ollama](https://ollama.com) instance — no cloud calls, no API keys. Optional: the app works fully without it, `s`/`a` just show a setup hint until configured.
+
+![Streaming article summary, then a multi-turn Ask AI conversation grounded in the same story](docs/ai-demo.gif)
+
+**Prerequisites**
+
+```bash
+brew install ollama   # or see ollama.com/download
+ollama serve           # if not already running as a service
+ollama pull llama3.2    # or any other chat-capable model
+```
+
+**Setup** — one-time:
+
+```bash
+hn config set ollama.host http://localhost:11434
+hn config set ollama.model llama3.2
+```
+
+Missing fields fall back to the defaults above; invalid JSON degrades to "AI disabled" with a warning rather than crashing the reader.
+
+### Configuration
+
+`hn config` reads/writes `~/.config/hn-bits/config.json` (override the path with `$HN_BITS_CONFIG`) — no need to hand-edit JSON:
+
+```bash
+hn config list                        # every known key + current value
+hn config get ollama.model            # single value, raw
+hn config set ollama.model llama3.2   # validates + writes
+hn config unset ollama.model          # removes a key
+```
+
+Sensitive values (e.g. a future Telegram bot token) print masked in `list` but raw from `get`, so scripts can still consume them. File format is plain JSON — hand-editing still works if you prefer it.
+
+### Themes
+
+`hn`, `mocha`, `dracula`, `tokyo`, `nord`, `gruvbox` (default: `hn`, HN-orange). Pick with `--theme <name>` or the `HN_THEME` env var — not persisted (no config file yet).
+
+### Keybindings
+
+**Global**
+
+| Key | Action |
+|-----|--------|
+| `q` | quit (suppressed while typing in search) |
+| `?` | help overlay (suppressed while typing in search) |
+
+**Story list**
+
+| Key | Action |
+|-----|--------|
+| `j`/`k` or ↓/↑ | move selection |
+| `←`/`→` | previous/next feed tab |
+| `t`/`n`/`b` | top / new / best directly |
+| `g g` / `G` | top / bottom |
+| `enter` | open comments |
+| `o` | open story URL in browser |
+| `r` | refresh feed |
+| `/` | search |
+| `s` | AI summary (article, or thread if no article) |
+| `a` | Ask AI (chat grounded in the story) |
+
+**Comments**
+
+| Key | Action |
+|-----|--------|
+| `j`/`k` or ↓/↑ | move selection |
+| `space`/`enter` | toggle fold on a comment |
+| `C`/`E` | collapse / expand all |
+| `g g` / `G` | top / bottom |
+| `o` | open story URL in browser |
+| `r` | reload |
+| `s` | AI thread summary |
+| `a` | Ask AI (chat grounded in the story) |
+| `esc`/`b` | back |
+
+**Search results**
+
+Same as story list, minus the tab/feed keys, plus `/` to start a new search. `esc` returns to the list if you got here via `/` in-TUI, or quits if you entered via `hn search`.
+
+## Development
+
+```bash
+npm run dev    # run from source (tsx)
+npm test       # vitest
+npm run build  # tsc
+```
+
+## Tech stack
+
+- TypeScript (strict, ESM) + Ink (React for terminals)
+- Commander CLI, native `fetch`
+- HN Firebase + Algolia APIs — no backend, no database
+- Vitest
+
+## Specs
+
+Implementation specs live in [`specs/`](specs/README.md); phase-by-phase status is tracked in [`PROGRESS.md`](PROGRESS.md). V1, V1.5, V1.6, and V2 (local AI) are feature-complete; V3 (subscriptions/watcher) is spec'd but not started.

package/dist/ai/context.js

@@ -0,0 +1,50 @@
+import { htmlToText } from '../lib/html.js';
+const THREAD_CHAR_BUDGET = 12_000;
+const COMMENT_CHAR_CAP = 1_000;
+const MAX_REPLY_DEPTH = 2;
+function capCommentText(html) {
+    const plain = htmlToText(html);
+    return plain.length > COMMENT_CHAR_CAP ? `${plain.slice(0, COMMENT_CHAR_CAP)}…` : plain;
+}
+function renderNode(node, depth, lines) {
+    lines.push(`${'  '.repeat(depth)}${node.author}: ${capCommentText(node.text)}`);
+    if (depth < MAX_REPLY_DEPTH) {
+        for (const child of node.children)
+            renderNode(child, depth + 1, lines);
+    }
+}
+/** Walks top-level comments in API order, trimming to a char budget once at least one is included. */
+export function buildThreadContext(comments) {
+    const lines = [];
+    let includedTopLevel = 0;
+    let trimmed = false;
+    for (const top of comments) {
+        const candidate = [];
+        renderNode(top, 0, candidate);
+        const projectedLength = lines.join('\n').length + candidate.join('\n').length;
+        if (projectedLength > THREAD_CHAR_BUDGET && includedTopLevel > 0) {
+            trimmed = true;
+            break;
+        }
+        lines.push(...candidate);
+        includedTopLevel++;
+    }
+    return { text: lines.join('\n'), includedTopLevel, trimmed };
+}
+/** Assembles the Ask AI system prompt: story metadata + article text + trimmed discussion. */
+export function buildAskAIContext({ story, article, articleUnavailableReason, comments }) {
+    const articleSection = article ? article.text : `unavailable: ${articleUnavailableReason ?? 'no article'}`;
+    const discussionSection = comments ? buildThreadContext(comments).text : 'not loaded';
+    return [
+        'You are answering questions about a Hacker News story and its discussion.',
+        "Base answers only on the provided material; say so when it doesn't contain the answer.",
+        '',
+        `Story: ${story.title} (${story.url ?? 'text post'}) — ${story.score} points, ${story.descendants} comments`,
+        '',
+        'Article:',
+        articleSection,
+        '',
+        'Discussion:',
+        discussionSection,
+    ].join('\n');
+}

package/dist/ai/ollama.js

@@ -0,0 +1,127 @@
+export class OllamaDownError extends Error {
+}
+export class ModelMissingError extends Error {
+}
+export class OllamaError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class TimeoutError extends Error {
+}
+/** Renders a caught error as a user-facing hint, preferring our typed messages. */
+export function describeError(err) {
+    if (err instanceof OllamaDownError || err instanceof ModelMissingError || err instanceof OllamaError || err instanceof TimeoutError) {
+        return err.message;
+    }
+    return err.message ?? 'unknown error';
+}
+const IDLE_TIMEOUT_MS = 60_000;
+function parseLines(buffer) {
+    const lines = buffer.split('\n');
+    const rest = lines.pop() ?? '';
+    const chunks = lines.filter((line) => line.trim()).map((line) => JSON.parse(line));
+    return { chunks, rest };
+}
+/** Streams content deltas from Ollama's chat endpoint. Yields nothing further and returns on caller-initiated abort. */
+export async function* chatStream(cfg, messages, signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal?.addEventListener('abort', onAbort);
+    let timedOut = false;
+    let idleTimer;
+    const resetIdle = () => {
+        clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, IDLE_TIMEOUT_MS);
+    };
+    try {
+        let res;
+        try {
+            resetIdle();
+            res = await fetch(`${cfg.host}/api/chat`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: cfg.model, messages, stream: true }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                if (timedOut)
+                    throw new TimeoutError(`Ollama request timed out after ${IDLE_TIMEOUT_MS / 1000}s`);
+                return;
+            }
+            throw new OllamaDownError(`Ollama not reachable at ${cfg.host} — is it running?`);
+        }
+        if (!res.ok) {
+            const bodyText = await res.text().catch(() => '');
+            if (res.status === 404 || /model.*not found/i.test(bodyText)) {
+                throw new ModelMissingError(`model ${cfg.model} not found — ollama pull ${cfg.model}`);
+            }
+            throw new OllamaError(res.status, `${res.status} ${bodyText.split('\n')[0]}`);
+        }
+        if (!res.body)
+            throw new OllamaError(res.status, 'empty response body');
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                resetIdle();
+                buffer += decoder.decode(value, { stream: true });
+                const { chunks, rest } = parseLines(buffer);
+                buffer = rest;
+                for (const chunk of chunks) {
+                    if (chunk.message?.content)
+                        yield chunk.message.content;
+                    if (chunk.done)
+                        return;
+                }
+            }
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                if (timedOut)
+                    throw new TimeoutError(`Ollama request timed out after ${IDLE_TIMEOUT_MS / 1000}s`);
+                return;
+            }
+            throw err;
+        }
+    }
+    finally {
+        clearTimeout(idleTimer);
+        signal?.removeEventListener('abort', onAbort);
+    }
+}
+/** Health probe distinguishing "server down" from "model missing" so callers can render tailored hints. */
+export async function checkOllama(cfg) {
+    let res;
+    try {
+        res = await fetch(`${cfg.host}/api/tags`, { signal: AbortSignal.timeout(5000) });
+    }
+    catch {
+        return { ok: false, reason: 'down', detail: `Ollama not reachable at ${cfg.host} — is it running?` };
+    }
+    if (!res.ok) {
+        return { ok: false, reason: 'down', detail: `${res.status} ${res.statusText}` };
+    }
+    const data = (await res.json());
+    const models = data.models ?? [];
+    const hasModel = models.some((m) => m.name === cfg.model || m.name.startsWith(`${cfg.model}:`));
+    if (!hasModel) {
+        return {
+            ok: false,
+            reason: 'model-missing',
+            detail: `model ${cfg.model} not found — ollama pull ${cfg.model}`,
+        };
+    }
+    return { ok: true };
+}

package/dist/ai/summaryPrompts.js

@@ -0,0 +1,49 @@
+import { fetchComments } from '../api/algolia.js';
+import { ExtractionError, extractArticle } from '../lib/article.js';
+import { htmlToText } from '../lib/html.js';
+import { buildThreadContext } from './context.js';
+function buildArticlePrompt(title, articleText) {
+    return `Summarize this article in 3-5 sentences, then list 2-3 key takeaways as short dashes.\n\nTitle: ${title}\n\n${articleText}`;
+}
+function buildThreadPrompt(title, threadText) {
+    return `Summarize this Hacker News discussion: main viewpoints, notable disagreements, and any strong consensus. 4-6 sentences.\n\nStory: ${title}\n\nComments:\n${threadText}`;
+}
+function threadNotice(thread) {
+    return thread.trimmed ? `thread trimmed to first ${thread.includedTopLevel} comments` : undefined;
+}
+async function fallbackPrompt(story, extractionNoticePrefix) {
+    if (story.text) {
+        const notice = extractionNoticePrefix ? `${extractionNoticePrefix} — summarizing post text instead` : undefined;
+        return { prompt: buildArticlePrompt(story.title, htmlToText(story.text)), notice };
+    }
+    const comments = await fetchComments(story.id);
+    const thread = buildThreadContext(comments);
+    const notice = [
+        extractionNoticePrefix ? `${extractionNoticePrefix} — summarizing thread instead` : undefined,
+        threadNotice(thread),
+    ]
+        .filter(Boolean)
+        .join('; ');
+    return { prompt: buildThreadPrompt(story.title, thread.text), notice: notice || undefined };
+}
+/** Story-list `s`: article summary, falling back to post text then thread on extraction failure. */
+export async function buildListSummaryPrompt(story, signal) {
+    if (!story.url)
+        return fallbackPrompt(story);
+    try {
+        const article = await extractArticle(story.url, signal);
+        return {
+            prompt: buildArticlePrompt(story.title, article.text),
+            notice: article.truncated ? 'article truncated to 16k chars' : undefined,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof ExtractionError ? err.reason : 'unknown';
+        return fallbackPrompt(story, `article unavailable (${reason})`);
+    }
+}
+/** Comments view `s`: thread summary from the already-loaded comment tree. */
+export function buildCommentsSummaryPrompt(story, comments) {
+    const thread = buildThreadContext(comments);
+    return { prompt: buildThreadPrompt(story.title, thread.text), notice: threadNotice(thread) };
+}

package/dist/api/algolia.js

@@ -0,0 +1,51 @@
+const BASE = 'https://hn.algolia.com/api/v1';
+async function getJson(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`${res.status} ${res.statusText} for ${url}`);
+    return res.json();
+}
+function toNode(item) {
+    // Deleted/dead comments come back with null author or text
+    if (item.type !== 'comment' || item.author == null || item.text == null) {
+        return null;
+    }
+    return {
+        id: item.id,
+        author: item.author,
+        text: item.text,
+        time: item.created_at_i,
+        children: item.children
+            .map(toNode)
+            .filter((c) => c != null),
+    };
+}
+/** Fetch the full comment tree of a story in one request. */
+export async function fetchComments(storyId) {
+    const item = await getJson(`${BASE}/items/${storyId}`);
+    return item.children.map(toNode).filter((c) => c != null);
+}
+export async function searchStories(query, page = 0) {
+    const params = new URLSearchParams({
+        query,
+        tags: 'story',
+        page: String(page),
+        hitsPerPage: '20',
+    });
+    const res = await getJson(`${BASE}/search?${params}`);
+    return {
+        stories: res.hits
+            .filter((h) => h.title != null)
+            .map((h) => ({
+            id: Number(h.objectID),
+            title: h.title,
+            url: h.url ?? undefined,
+            by: h.author ?? '?',
+            score: h.points ?? 0,
+            descendants: h.num_comments ?? 0,
+            time: h.created_at_i,
+        })),
+        hasMore: page + 1 < res.nbPages,
+        totalHits: res.nbHits,
+    };
+}

package/dist/api/firebase.js

@@ -0,0 +1,35 @@
+const BASE = 'https://hacker-news.firebaseio.com/v0';
+const FEED_PATHS = {
+    top: 'topstories',
+    new: 'newstories',
+    best: 'beststories',
+    ask: 'askstories',
+    show: 'showstories',
+};
+async function getJson(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`${res.status} ${res.statusText} for ${url}`);
+    return res.json();
+}
+export function fetchStoryIds(feed) {
+    return getJson(`${BASE}/${FEED_PATHS[feed]}.json`);
+}
+export async function fetchStories(ids) {
+    const items = await Promise.all(ids.map((id) => getJson(`${BASE}/item/${id}.json`)));
+    return items
+        .filter((it) => it != null && !it.deleted && !it.dead && it.title != null)
+        .map((it) => ({
+        id: it.id,
+        title: it.title,
+        url: it.url,
+        text: it.text,
+        by: it.by ?? '?',
+        score: it.score ?? 0,
+        descendants: it.descendants ?? 0,
+        time: it.time ?? 0,
+    }));
+}
+export function hnItemUrl(id) {
+    return `https://news.ycombinator.com/item?id=${id}`;
+}

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Command } from 'commander';
+import { render } from 'ink';
+const alternateScreen = process.stdout.isTTY === true;
+function applyTheme(options) {
+    if (options.theme)
+        process.env['HN_THEME'] = options.theme;
+}
+const program = new Command();
+program
+    .name('hn')
+    .description('Terminal-first Hacker News client')
+    .version('0.1.0')
+    .option('-t, --theme <name>', 'color theme (see `hn theme` for the list)');
+program.action(async () => {
+    applyTheme(program.opts());
+    const { App } = await import('./ui/App.js');
+    render(_jsx(App, {}), { alternateScreen });
+});
+program
+    .command('search <query...>')
+    .description('Search stories by keyword')
+    .action(async (queryParts) => {
+    applyTheme(program.opts());
+    const { App } = await import('./ui/App.js');
+    render(_jsx(App, { initialQuery: queryParts.join(' ') }), { alternateScreen });
+});
+program
+    .command('theme')
+    .description('Show the active color theme and available palettes')
+    .action(async () => {
+    const { paletteNames, resolvePaletteName } = await import('./ui/theme.js');
+    const activeName = resolvePaletteName(program.opts().theme);
+    console.log(`Active theme: ${activeName}`);
+    console.log(`Available: ${paletteNames().join(', ')}`);
+    console.log('Set with `hn --theme <name>` or the HN_THEME environment variable.');
+});
+const config = program.command('config').description('Get or set hn-bits config values');
+config
+    .command('list')
+    .description('List all known config keys and their current values')
+    .action(async () => {
+    const { listConfigEntries } = await import('./lib/configStore.js');
+    for (const { key, value } of listConfigEntries()) {
+        console.log(`${key}=${value ?? '(not set)'}`);
+    }
+});
+config
+    .command('get <key>')
+    .description('Print a single config value')
+    .action(async (key) => {
+    const { getConfigValue } = await import('./lib/configStore.js');
+    try {
+        const value = getConfigValue(key);
+        if (value === undefined) {
+            console.error(`${key} is not set`);
+            process.exit(1);
+        }
+        console.log(value);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+});
+config
+    .command('set <key> <value>')
+    .description('Set a config value')
+    .action(async (key, value) => {
+    const { setConfigValue } = await import('./lib/configStore.js');
+    try {
+        setConfigValue(key, value);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+});
+config
+    .command('unset <key>')
+    .description('Remove a config value')
+    .action(async (key) => {
+    const { unsetConfigValue } = await import('./lib/configStore.js');
+    try {
+        unsetConfigValue(key);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/lib/article.js

@@ -0,0 +1,71 @@
+import pkg from '../../package.json' with { type: 'json' };
+export class ExtractionError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const TEXT_BUDGET_CHARS = 16_000;
+async function readCappedBody(res) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return '';
+    const decoder = new TextDecoder();
+    let bytesRead = 0;
+    let text = '';
+    while (bytesRead < MAX_BODY_BYTES) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        bytesRead += value.byteLength;
+        text += decoder.decode(value, { stream: true });
+    }
+    await reader.cancel().catch(() => { });
+    return text;
+}
+function normalize(text) {
+    return text
+        .split(/\n{2,}/)
+        .map((paragraph) => paragraph.trim())
+        .filter(Boolean)
+        .join('\n\n');
+}
+function truncate(text, budget) {
+    if (text.length <= budget)
+        return { text, truncated: false };
+    const cut = text.lastIndexOf('\n\n', budget);
+    return { text: text.slice(0, cut > 0 ? cut : budget), truncated: true };
+}
+/** Fetches a story URL and extracts readable article text. Throws ExtractionError; callers define fallback. */
+export async function extractArticle(url, signal) {
+    const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { 'User-Agent': `hn-bits/${pkg.version}`, Accept: 'text/html' },
+            signal: combinedSignal,
+        });
+    }
+    catch {
+        throw new ExtractionError('fetch-failed');
+    }
+    if (!res.ok)
+        throw new ExtractionError('fetch-failed');
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('text/html'))
+        throw new ExtractionError('not-html');
+    const html = await readCappedBody(res);
+    const { JSDOM, VirtualConsole } = await import('jsdom');
+    const { Readability } = await import('@mozilla/readability');
+    const virtualConsole = new VirtualConsole();
+    const dom = new JSDOM(html, { url, virtualConsole });
+    const parsed = new Readability(dom.window.document).parse();
+    if (!parsed?.textContent?.trim())
+        throw new ExtractionError('unreadable');
+    const { text, truncated } = truncate(normalize(parsed.textContent), TEXT_BUDGET_CHARS);
+    return { title: parsed.title ?? '', text, truncated };
+}

package/dist/lib/commentTree.js

@@ -0,0 +1,60 @@
+import { countDescendants } from './comments.js';
+/** Depth-first flatten; children are skipped when a node is folded or header-only. */
+export function flattenTree(nodes, folded, headerOnly) {
+    return nodes.flatMap((node) => flattenNode(node, 0, folded, headerOnly));
+}
+function flattenNode(node, depth, folded, headerOnly) {
+    const isHeaderOnly = headerOnly.has(node.id);
+    const childrenHidden = isHeaderOnly || folded.has(node.id);
+    const entry = {
+        node,
+        depth,
+        descendantCount: countDescendants(node),
+        childrenHidden,
+        headerOnly: isHeaderOnly,
+    };
+    if (childrenHidden)
+        return [entry];
+    return [entry, ...node.children.flatMap((child) => flattenNode(child, depth + 1, folded, headerOnly))];
+}
+export function toggleFold(folded, id) {
+    const next = new Set(folded);
+    if (next.has(id))
+        next.delete(id);
+    else
+        next.add(id);
+    return next;
+}
+/** Moves an id from header-only into revealed, so C-originated leaves can toggle back. */
+export function revealHeaderOnly(state, id) {
+    const headerOnly = new Set(state.headerOnly);
+    headerOnly.delete(id);
+    return { headerOnly, revealed: new Set(state.revealed).add(id) };
+}
+/** Moves a revealed id back to header-only — the leaf half of the header ↔ body toggle. */
+export function rehideRevealed(state, id) {
+    const revealed = new Set(state.revealed);
+    revealed.delete(id);
+    return { headerOnly: new Set(state.headerOnly).add(id), revealed };
+}
+/** Every id that has children — the default/collapsed fold set (body shown, children hidden). */
+export function collapseAll(nodes) {
+    const ids = new Set();
+    const visit = (node) => {
+        if (node.children.length > 0)
+            ids.add(node.id);
+        node.children.forEach(visit);
+    };
+    nodes.forEach(visit);
+    return ids;
+}
+/** Every id, parents and leaves — the header-only set produced by `C` (collapse all). */
+export function headerOnlyAll(nodes) {
+    const ids = new Set();
+    const visit = (node) => {
+        ids.add(node.id);
+        node.children.forEach(visit);
+    };
+    nodes.forEach(visit);
+    return ids;
+}

package/dist/lib/comments.js

@@ -0,0 +1,3 @@
+export function countDescendants(node) {
+    return node.children.reduce((total, child) => total + 1 + countDescendants(child), 0);
+}