hn-bits 0.6.0 → 0.7.0

package/README.md

@@ -79,9 +79,9 @@ 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
+### Subscriptions + 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.
+`hn sub` tracks topic queries; `hn watch --once` checks each one, dedups against past matches, and sends new ones to Telegram and/or macOS desktop notifications. 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
@@ -103,6 +103,17 @@ 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.
 
+**macOS desktop notifications** (optional, works alone or alongside Telegram) use the [alerter](https://github.com/vjeantet/alerter) binary (`brew install vjeantet/tap/alerter`):
+
+```bash
+hn config set desktopNotifications.enabled true
+hn config set desktopNotifications.timeoutSeconds 10   # optional, default 10
+```
+
+Clicking a notification opens the story URL (HN discussion for text posts): clicks act only while the notification is on screen (`timeoutSeconds`); stale entries in Notification Center just dismiss. Desktop delivery is best-effort: if `alerter` is missing, the watcher warns and skips it (exit 0, nothing marked seen when it's the only channel).
+
+One-time macOS setup: alerter sends as Terminal.app, and macOS silently drops notifications from senders without permission. Check System Settings > Notifications > Terminal is allowed (banner style): there is no prompt and no error when it isn't.
+
 ```bash
 hn watch --once   # one pass: query subscriptions, notify new matches, exit
 ```

package/dist/notify/desktop.js

@@ -0,0 +1,62 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { hnItemUrl } from '../api/firebase.js';
+// Story data reaches the shell only as positional parameters, never spliced
+// into the script, so titles containing quotes or $() cannot inject.
+// $7 is the absolute alerter path: under cron the child PATH lacks it too.
+const WRAPPER_SCRIPT = 'r=$("$7" --title "$1" --subtitle "$2" --message "$3" --actions Open --timeout "$4" --group "$5"); ' +
+    'case "$r" in @TIMEOUT|@CLOSED) ;; *) open "$6" ;; esac';
+// Cron runs with PATH=/usr/bin:/bin, which contains neither the Homebrew
+// prefix nor ~/.local/bin, so PATH alone would never find alerter under cron.
+const FALLBACK_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', join(homedir(), '.local', 'bin')];
+export function findAlerter() {
+    const pathDirs = (process.env.PATH ?? '').split(delimiter);
+    for (const dir of [...pathDirs, ...FALLBACK_DIRS]) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, 'alerter');
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // not here, keep scanning
+        }
+    }
+    return null;
+}
+function wrapperArguments({ subscription, story }, timeoutSeconds, alerterPath) {
+    return [
+        'sh',
+        `🔔 ${subscription.name}`,
+        `${story.score} pts · ${story.descendants} comments`,
+        story.title,
+        String(timeoutSeconds),
+        `hn-${subscription.id}-${story.id}`,
+        story.url ?? hnItemUrl(story.id),
+        alerterPath,
+    ];
+}
+/** Returns null (after one stderr warning) when alerter is not on PATH. */
+export function createDesktopNotifier(config) {
+    const alerterPath = findAlerter();
+    if (alerterPath == null) {
+        console.error('desktop: alerter not found (brew install vjeantet/tap/alerter), skipping');
+        return null;
+    }
+    return {
+        name: 'desktop',
+        // Fire-and-forget: the detached wrapper waits out the notification;
+        // failures log but never reject, so the watcher's markSeen is not blocked.
+        send: async (match) => {
+            const child = spawn('sh', ['-c', WRAPPER_SCRIPT, ...wrapperArguments(match, config.timeoutSeconds, alerterPath)], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.on('error', (err) => console.error(`desktop: spawn failed - ${err.message}`));
+            child.unref();
+        },
+    };
+}

package/dist/watch.js

@@ -2,6 +2,7 @@ import { searchRecent } from './api/algolia.js';
 import { isSeen, markSeen } from './db/seen.js';
 import { listSubscriptions, touchLastRun } from './db/subscriptions.js';
 import { loadConfig } from './lib/config.js';
+import { createDesktopNotifier } from './notify/desktop.js';
 import { createTelegramNotifier } from './notify/telegram.js';
 const SIX_HOURS = 6 * 60 * 60;
 const TWENTY_FOUR_HOURS = 24 * 60 * 60;
@@ -15,11 +16,21 @@ function windowStart(lastRunAt, now) {
 }
 function buildNotifiers() {
     const config = loadConfig();
+    const notifiers = [];
+    let desktopSkipped = false;
     const telegram = config?.telegram;
     if (telegram?.enabled && telegram.botToken && telegram.chatId) {
-        return [createTelegramNotifier({ botToken: telegram.botToken, chatId: telegram.chatId })];
+        notifiers.push(createTelegramNotifier({ botToken: telegram.botToken, chatId: telegram.chatId }));
     }
-    return [];
+    const desktop = config?.desktopNotifications;
+    if (desktop?.enabled) {
+        const notifier = createDesktopNotifier({ timeoutSeconds: desktop.timeoutSeconds });
+        if (notifier)
+            notifiers.push(notifier);
+        else
+            desktopSkipped = true;
+    }
+    return { notifiers, desktopSkipped };
 }
 async function notifyStory(sub, story, notifiers) {
     try {
@@ -75,9 +86,11 @@ async function processSubscription(sub, notifiers, now, dryRun) {
 }
 /** hn watch --once: one-shot pass over all subscriptions. Returns the process exit code. */
 export async function runWatch(options) {
-    const notifiers = buildNotifiers();
+    const { notifiers, desktopSkipped } = buildNotifiers();
     if (notifiers.length === 0) {
-        console.error('no notifier configured: hn config set telegram.enabled true (and botToken/chatId)');
+        if (desktopSkipped)
+            return 0;
+        console.error('no notifier configured: hn config set telegram.enabled true (and botToken/chatId) or desktopNotifications.enabled true');
         return 2;
     }
     const subs = listSubscriptions();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hn-bits",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Terminal-first Hacker News client",
   "type": "module",
   "repository": {