hn-bits 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,45 @@
 # 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.
+A fullscreen terminal client for Hacker News, built with TypeScript + Ink. Optional local AI summaries via Ollama, topic subscriptions with Telegram alerts, no cloud required beyond what you opt into.
+
+![npm version](https://img.shields.io/npm/v/hn-bits)
+[![CI](https://img.shields.io/github/actions/workflow/status/navinrc/hn-bits/release.yml)](https://github.com/navinrc/hn-bits/actions)
+[![Release](https://img.shields.io/github/v/release/navinrc/hn-bits)](https://github.com/navinrc/hn-bits/releases)
+[![npm downloads](https://img.shields.io/npm/dt/hn-bits)](https://www.npmjs.com/package/hn-bits)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+![Streaming article summary, then a multi-turn Ask AI conversation grounded in the same story](docs/ai-demo.gif)
+
+![Subs tab: manage topic subscriptions, browse per-topic matches](docs/subs-demo.gif)
+
+![Saved tab: bookmark a story with B, browse it from hn bookmarks](docs/saved-demo.gif)
+
+## Features
+
+- Fullscreen TUI: top/new/best/ask/show/saved/subs tabs, vim-style navigation
+- Threaded comments view with fold/collapse
+- Search across stories
+- 6 built-in themes (`hn`, `mocha`, `dracula`, `tokyo`, `nord`, `gruvbox`)
+- Local AI article/thread summaries via Ollama, no cloud calls
+- Ask AI: multi-turn Q&A grounded in the current story
+- Subscriptions + `hn watch --once` radar with Telegram notifications
+- Bookmarks: `B` to save a story, `hn bookmarks` to browse them
+- SQLite storage (subscriptions, dedup, bookmarks); config file for AI/Telegram settings
 
 ## Install
 
+```bash
+npm install -g hn-bits
+```
+
+Or run without installing:
+
+```bash
+npx hn-bits
+```
+
+### From source
+
 ```bash
 npm install
 npm run build
@@ -13,8 +49,10 @@ npm link   # exposes the `hn` binary
 ## Usage
 
 ```bash
-hn                    # fullscreen shell: top/new/best/ask/show tabs
+hn                    # fullscreen shell: top/new/best/ask/show/saved/subs tabs
 hn search <query...>  # search results
+hn bookmarks          # opens straight into the saved tab
+hn subs               # opens straight into the subs tab
 hn --theme dracula    # themes: hn (default), mocha, dracula, tokyo, nord, gruvbox
 ```
 
@@ -22,9 +60,7 @@ 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)
+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.
 
 **Prerequisites**
 
@@ -34,7 +70,7 @@ ollama serve           # if not already running as a service
 ollama pull llama3.2    # or any other chat-capable model
 ```
 
-**Setup** — one-time:
+**Setup** (one-time):
 
 ```bash
 hn config set ollama.host http://localhost:11434
@@ -43,9 +79,43 @@ 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.
 
+### Subscriptions + Telegram notifications
+
+`hn sub` tracks topic queries; `hn watch --once` checks each one, dedups against past matches, and sends new ones to Telegram. No daemon: schedule `hn watch --once` with cron or launchd.
+
+```bash
+hn sub add apple "Apple" --min-points 50   # topic name, Algolia query, min score
+hn sub list
+hn sub rm apple
+```
+
+**Telegram setup** (one-time):
+
+1. Message [`@BotFather`](https://t.me/BotFather) on Telegram, run `/newbot`, copy the token it gives you.
+2. Message your new bot once (anything, e.g. "hi").
+3. Fetch `https://api.telegram.org/bot<TOKEN>/getUpdates` and read `result[0].message.chat.id`.
+
+```bash
+hn config set telegram.botToken 123456:ABC-...
+hn config set telegram.chatId 987654321
+hn config set telegram.enabled true
+```
+
+All three keys are required, `telegram.enabled` alone is not enough. With nothing enabled, `hn watch --once` exits with code 2.
+
+```bash
+hn watch --once   # one pass: query subscriptions, notify new matches, exit
+```
+
+Schedule it, e.g. every 30 minutes via crontab:
+
+```
+*/30 * * * * cd /path/to/hn-bits && hn watch --once
+```
+
 ### Configuration
 
-`hn config` reads/writes `~/.config/hn-bits/config.json` (override the path with `$HN_BITS_CONFIG`) — no need to hand-edit JSON:
+`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
@@ -54,11 +124,11 @@ 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.
+Sensitive values (e.g. `telegram.botToken`) 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).
+`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
 
@@ -83,6 +153,7 @@ Sensitive values (e.g. a future Telegram bot token) print masked in `list` but r
 | `/` | search |
 | `s` | AI summary (article, or thread if no article) |
 | `a` | Ask AI (chat grounded in the story) |
+| `B` | bookmark |
 
 **Comments**
 
@@ -96,11 +167,31 @@ Sensitive values (e.g. a future Telegram bot token) print masked in `list` but r
 | `r` | reload |
 | `s` | AI thread summary |
 | `a` | Ask AI (chat grounded in the story) |
+| `B` | bookmark |
 | `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`.
+Same as story list, minus the tab/feed keys, plus `/` to start a new search and `S` to subscribe (prefills a topic from the query). `esc` returns to the list if you got here via `/` in-TUI, or quits if you entered via `hn search`.
+
+**Saved** (`hn bookmarks`, or the Saved tab)
+
+Same as story list, minus search; `B` removes a bookmark instead of adding one.
+
+**Subs** (`hn subs`, or the Subs tab)
+
+| Key | Action |
+|-----|--------|
+| `j`/`k` or ↓/↑ | move selection |
+| `←`/`→` | previous/next tab |
+| `enter` | browse matches for the selected topic |
+| `a` | add subscription |
+| `e` | edit subscription |
+| `d` | delete subscription |
+
+**Sub matches** (opened from Subs via `enter`)
+
+Same as story list, minus search/tab-switch; `r` refetches, `esc` returns to Subs.
 
 ## Development
 
@@ -114,9 +205,10 @@ npm run build  # tsc
 
 - TypeScript (strict, ESM) + Ink (React for terminals)
 - Commander CLI, native `fetch`
-- HN Firebase + Algolia APIs — no backend, no database
+- HN Firebase + Algolia APIs, no backend
+- `better-sqlite3` for subscriptions/dedup/bookmarks
 - 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.
+Implementation specs live in [`specs/`](specs/README.md); phase-by-phase status is tracked in [`PROGRESS.md`](PROGRESS.md). V1, V1.5, V1.6, V2 (local AI), and V3 (subscriptions/watcher/notifications/bookmarks) are feature-complete.

package/dist/api/algolia.js

@@ -25,6 +25,17 @@ export async function fetchComments(storyId) {
     const item = await getJson(`${BASE}/items/${storyId}`);
     return item.children.map(toNode).filter((c) => c != null);
 }
+function hitToStory(hit) {
+    return {
+        id: Number(hit.objectID),
+        title: hit.title,
+        url: hit.url ?? undefined,
+        by: hit.author ?? '?',
+        score: hit.points ?? 0,
+        descendants: hit.num_comments ?? 0,
+        time: hit.created_at_i,
+    };
+}
 export async function searchStories(query, page = 0) {
     const params = new URLSearchParams({
         query,
@@ -34,18 +45,27 @@ export async function searchStories(query, page = 0) {
     });
     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,
-        })),
+        stories: res.hits.filter((h) => h.title != null).map(hitToStory),
         hasMore: page + 1 < res.nbPages,
         totalHits: res.nbHits,
     };
 }
+/**
+ * Recency-ordered search (subscription matching + watcher window rescans),
+ * as opposed to searchStories' relevance ordering.
+ */
+export async function searchRecent(query, options) {
+    const numericFilters = [`created_at_i>${options.createdAfter}`];
+    if (options.minPoints)
+        numericFilters.push(`points>=${options.minPoints}`);
+    const params = new URLSearchParams({
+        query,
+        tags: 'story',
+        numericFilters: numericFilters.join(','),
+        hitsPerPage: String(options.hitsPerPage ?? 50),
+        typoTolerance: 'false',
+        queryType: 'prefixNone',
+    });
+    const res = await getJson(`${BASE}/search_by_date?${params}`);
+    return res.hits.filter((h) => h.title != null).map(hitToStory);
+}

package/dist/db/bookmarks.js

@@ -0,0 +1,37 @@
+import { openDb } from './db.js';
+function toStory(row) {
+    return {
+        id: row.story_id,
+        title: row.title,
+        url: row.url ?? undefined,
+        by: row.by,
+        score: row.score,
+        descendants: row.descendants,
+        time: row.time,
+    };
+}
+let lastBookmarkedAt = 0;
+/** Monotonic ms timestamp — Date.now() alone can tie on rapid successive bookmarks. */
+function nextBookmarkedAt() {
+    lastBookmarkedAt = Math.max(Date.now(), lastBookmarkedAt + 1);
+    return lastBookmarkedAt;
+}
+export function isBookmarked(storyId) {
+    const row = openDb().prepare('SELECT 1 FROM bookmarks WHERE story_id = ?').get(storyId);
+    return row != null;
+}
+/** Toggles the bookmark for a story; returns the new state (true = now bookmarked). */
+export function toggleBookmark(story) {
+    const db = openDb();
+    if (isBookmarked(story.id)) {
+        db.prepare('DELETE FROM bookmarks WHERE story_id = ?').run(story.id);
+        return false;
+    }
+    db.prepare(`INSERT INTO bookmarks (story_id, title, url, by, score, descendants, time, bookmarked_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(story.id, story.title, story.url ?? null, story.by, story.score, story.descendants, story.time, nextBookmarkedAt());
+    return true;
+}
+export function listBookmarks() {
+    const rows = openDb().prepare('SELECT * FROM bookmarks ORDER BY bookmarked_at DESC').all();
+    return rows.map(toStory);
+}

package/dist/db/db.js

@@ -0,0 +1,64 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import DatabaseConstructor from 'better-sqlite3';
+const MIGRATIONS = [
+    `
+  CREATE TABLE subscriptions (
+    id          INTEGER PRIMARY KEY,
+    name        TEXT NOT NULL UNIQUE,
+    query       TEXT NOT NULL,
+    min_points  INTEGER NOT NULL DEFAULT 0,
+    created_at  INTEGER NOT NULL,
+    last_run_at INTEGER
+  );
+
+  CREATE TABLE seen_items (
+    story_id        INTEGER NOT NULL,
+    subscription_id INTEGER NOT NULL REFERENCES subscriptions(id) ON DELETE CASCADE,
+    notified_at     INTEGER NOT NULL,
+    PRIMARY KEY (story_id, subscription_id)
+  );
+
+  CREATE TABLE bookmarks (
+    story_id      INTEGER PRIMARY KEY,
+    title         TEXT NOT NULL,
+    url           TEXT,
+    by            TEXT NOT NULL,
+    score         INTEGER NOT NULL,
+    descendants   INTEGER NOT NULL,
+    time          INTEGER NOT NULL,
+    bookmarked_at INTEGER NOT NULL
+  );
+  `,
+];
+export function dbPath() {
+    return process.env.HN_BITS_DB || join(homedir(), '.local', 'share', 'hn-bits', 'hn-bits.db');
+}
+let cached = null;
+function migrate(db) {
+    const currentVersion = db.pragma('user_version', { simple: true });
+    for (let i = currentVersion; i < MIGRATIONS.length; i++) {
+        db.transaction(() => {
+            db.exec(MIGRATIONS[i]);
+            db.pragma(`user_version = ${i + 1}`);
+        })();
+    }
+}
+/** Opens (or returns the cached handle for) the app database, running pending migrations. */
+export function openDb() {
+    const path = dbPath();
+    if (cached && cached.path === path)
+        return cached.db;
+    mkdirSync(dirname(path), { recursive: true });
+    const db = new DatabaseConstructor(path);
+    db.pragma('journal_mode = WAL');
+    migrate(db);
+    cached = { path, db };
+    return db;
+}
+/** Test-only: drops the cached handle so the next openDb() re-resolves HN_BITS_DB. */
+export function resetDbCache() {
+    cached?.db.close();
+    cached = null;
+}

package/dist/db/seen.js

@@ -0,0 +1,12 @@
+import { openDb } from './db.js';
+export function isSeen(storyId, subscriptionId) {
+    const row = openDb()
+        .prepare('SELECT 1 FROM seen_items WHERE story_id = ? AND subscription_id = ?')
+        .get(storyId, subscriptionId);
+    return row != null;
+}
+export function markSeen(storyId, subscriptionId, at) {
+    openDb()
+        .prepare('INSERT OR IGNORE INTO seen_items (story_id, subscription_id, notified_at) VALUES (?, ?, ?)')
+        .run(storyId, subscriptionId, at);
+}

package/dist/db/subscriptions.js

@@ -0,0 +1,44 @@
+import { openDb } from './db.js';
+function fromRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        query: row.query,
+        minPoints: row.min_points,
+        createdAt: row.created_at,
+        lastRunAt: row.last_run_at,
+    };
+}
+function assertNameFree(name, excludeId) {
+    const db = openDb();
+    const conflict = excludeId === undefined
+        ? db.prepare('SELECT 1 FROM subscriptions WHERE name = ?').get(name)
+        : db.prepare('SELECT 1 FROM subscriptions WHERE name = ? AND id != ?').get(name, excludeId);
+    if (conflict)
+        throw new Error(`subscription '${name}' already exists`);
+}
+export function addSubscription(name, query, minPoints) {
+    assertNameFree(name);
+    const createdAt = Math.floor(Date.now() / 1000);
+    const info = openDb()
+        .prepare('INSERT INTO subscriptions (name, query, min_points, created_at) VALUES (?, ?, ?, ?)')
+        .run(name, query, minPoints, createdAt);
+    return { id: Number(info.lastInsertRowid), name, query, minPoints, createdAt, lastRunAt: null };
+}
+export function listSubscriptions() {
+    const rows = openDb().prepare('SELECT * FROM subscriptions ORDER BY created_at ASC').all();
+    return rows.map(fromRow);
+}
+export function removeSubscription(name) {
+    const info = openDb().prepare('DELETE FROM subscriptions WHERE name = ?').run(name);
+    return info.changes > 0;
+}
+export function updateSubscription(id, fields) {
+    assertNameFree(fields.name, id);
+    const db = openDb();
+    db.prepare('UPDATE subscriptions SET name = ?, query = ?, min_points = ? WHERE id = ?').run(fields.name, fields.query, fields.minPoints, id);
+    return fromRow(db.prepare('SELECT * FROM subscriptions WHERE id = ?').get(id));
+}
+export function touchLastRun(id, at) {
+    openDb().prepare('UPDATE subscriptions SET last_run_at = ? WHERE id = ?').run(at, id);
+}

package/dist/index.js

@@ -26,6 +26,22 @@ program
     const { App } = await import('./ui/App.js');
     render(_jsx(App, { initialQuery: queryParts.join(' ') }), { alternateScreen });
 });
+program
+    .command('bookmarks')
+    .description('Open the TUI on the Saved tab')
+    .action(async () => {
+    applyTheme(program.opts());
+    const { App } = await import('./ui/App.js');
+    render(_jsx(App, { initialView: "saved" }), { alternateScreen });
+});
+program
+    .command('subs')
+    .description('Open the TUI on the Subs tab')
+    .action(async () => {
+    applyTheme(program.opts());
+    const { App } = await import('./ui/App.js');
+    render(_jsx(App, { initialView: "subs" }), { alternateScreen });
+});
 program
     .command('theme')
     .description('Show the active color theme and available palettes')
@@ -90,4 +106,63 @@ config
         process.exit(1);
     }
 });
+const sub = program.command('sub').description('Manage topic subscriptions');
+sub
+    .command('add <name> <query...>')
+    .description('Add a subscription')
+    .option('--min-points <n>', 'minimum points threshold', '0')
+    .action(async (name, queryParts, options) => {
+    const minPoints = Number(options.minPoints);
+    if (!Number.isInteger(minPoints) || minPoints < 0) {
+        console.error(`--min-points must be a non-negative integer, got '${options.minPoints}'`);
+        process.exit(1);
+    }
+    const { addSubscription } = await import('./db/subscriptions.js');
+    try {
+        addSubscription(name, queryParts.join(' '), minPoints);
+        console.log(`added '${name}'`);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+});
+sub
+    .command('list')
+    .description('List subscriptions')
+    .action(async () => {
+    const { listSubscriptions } = await import('./db/subscriptions.js');
+    const { formatAge } = await import('./lib/format.js');
+    const subs = listSubscriptions();
+    if (subs.length === 0) {
+        console.log('no subscriptions yet');
+        return;
+    }
+    const nameWidth = Math.max(...subs.map((s) => s.name.length));
+    for (const s of subs) {
+        const points = s.minPoints === 0 ? 'any' : `>=${s.minPoints}`;
+        const lastRun = s.lastRunAt == null ? 'never' : `${formatAge(s.lastRunAt)} ago`;
+        console.log(`${s.name.padEnd(nameWidth)}  "${s.query}"  ${points}  ${lastRun}`);
+    }
+});
+sub
+    .command('rm <name>')
+    .description('Remove a subscription')
+    .action(async (name) => {
+    const { removeSubscription } = await import('./db/subscriptions.js');
+    if (!removeSubscription(name)) {
+        console.error(`subscription '${name}' not found`);
+        process.exit(1);
+    }
+    console.log(`removed '${name}'`);
+});
+program
+    .command('watch')
+    .description('Check subscriptions for new matches and notify (one-shot; cron owns scheduling)')
+    .requiredOption('--once', 'run a single pass and exit (required; guards against future daemon semantics)')
+    .option('--dry-run', 'print would-notify matches without sending or writing seen_items')
+    .action(async (options) => {
+    const { runWatch } = await import('./watch.js');
+    process.exit(await runWatch({ dryRun: Boolean(options.dryRun) }));
+});
 program.parse();

package/dist/lib/listNavigation.js

@@ -7,12 +7,12 @@ const FEED_KEYS = { t: 'top', n: 'new', b: 'best' };
 export function mapFeedKey(key) {
     return FEED_KEYS[key];
 }
-const FEED_ORDER = ['top', 'new', 'best', 'ask', 'show'];
-export function nextFeed(current) {
-    const index = FEED_ORDER.indexOf(current);
-    return FEED_ORDER[(index + 1) % FEED_ORDER.length];
+const TAB_ORDER = ['top', 'new', 'best', 'ask', 'show', 'saved', 'subs'];
+export function nextTab(current) {
+    const index = TAB_ORDER.indexOf(current);
+    return TAB_ORDER[(index + 1) % TAB_ORDER.length];
 }
-export function previousFeed(current) {
-    const index = FEED_ORDER.indexOf(current);
-    return FEED_ORDER[(index - 1 + FEED_ORDER.length) % FEED_ORDER.length];
+export function previousTab(current) {
+    const index = TAB_ORDER.indexOf(current);
+    return TAB_ORDER[(index - 1 + TAB_ORDER.length) % TAB_ORDER.length];
 }

package/dist/notify/notifier.js

@@ -0,0 +1 @@
+export {};

package/dist/notify/telegram.js

@@ -0,0 +1,58 @@
+import { hnItemUrl } from '../api/firebase.js';
+const SEND_TIMEOUT_MS = 10_000;
+export class NotifyError extends Error {
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function buildMessage({ subscription, story }) {
+    const lines = [`🔔 <b>${escapeHtml(subscription.name)}</b>`];
+    if (story.url) {
+        lines.push(`<a href="${story.url}">${escapeHtml(story.title)}</a>`);
+        lines.push(`${story.score} points · ${story.descendants} comments · by ${escapeHtml(story.by)}`);
+        lines.push(`<a href="${hnItemUrl(story.id)}">HN discussion</a>`);
+    }
+    else {
+        lines.push(`<a href="${hnItemUrl(story.id)}">${escapeHtml(story.title)}</a>`);
+        lines.push(`${story.score} points · ${story.descendants} comments · by ${escapeHtml(story.by)}`);
+    }
+    return lines.join('\n');
+}
+async function post(config, text) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+    try {
+        return await fetch(`https://api.telegram.org/bot${config.botToken}/sendMessage`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                chat_id: config.chatId,
+                text,
+                parse_mode: 'HTML',
+                disable_web_page_preview: false,
+            }),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function sendMessage(config, text, retried = false) {
+    const res = await post(config, text);
+    const body = (await res.json().catch(() => null));
+    if (res.ok && body?.ok)
+        return;
+    if (res.status === 429 && !retried) {
+        const retryAfter = body?.parameters?.retry_after ?? 1;
+        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+        return sendMessage(config, text, true);
+    }
+    throw new NotifyError(`telegram sendMessage failed: ${res.status}`);
+}
+export function createTelegramNotifier(config) {
+    return {
+        name: 'telegram',
+        send: (match) => sendMessage(config, buildMessage(match)),
+    };
+}