stdout-chat 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `stdout-chat` (the CLI). Dates are release dates.
+
+## [0.3.0] — 2026-09-20
+
+### What's New
+
+- `/dm <nick|sid>` at the prompt invites someone from #void to a private chat. Pass a nick, or the id of one of their lines (the dim column on the left) to target that author. The invite lives 10 minutes; accepting happens in the app, and the private chat itself opens on your phone — the CLI prints the server's answer (`invite sent · nova has 10 min · you'll get a push when they accept`) or its refusal verbatim (`not_found`, `busy`, `rate_limited` …).
+
+### Technical
+
+- `lib/api.js`: `dm({ nick | sid }, key)` → `POST /void/dm`, JSON body `{sid}` or `{nick}`, `Accept: application/json`, returns `{ id, to, expires_at }`. Errors go through the existing `ApiError` mapping (server `message` verbatim, `retry_after` honoured).
+- `lib/session.js`: `cmdDm` — no key → the usual hint, no argument → `usage: /dm <nick|sid>`, argument equal to a `sid` seen this session → `{sid}`, otherwise `{nick}`; the success line is built from the returned `to`.
+- Tests: 76 → 82 (`/dm` sid/nick routing, usage, no-key, verbatim errors; `api.dm` request shape).
+
+## [0.2.0] — 2026-09-20
+
+### What's New
+
+- Desktop notifications on macOS and Linux: a banner when someone replies to your line or writes `@you` while the client is running (at the prompt or in `--tail`). Live lines only; history and your own lines never notify.
+- `/notify` shows the level; `/notify mentions|all|off` sets it and saves it next to the key.
+- `--no-notify` (and `--notify`) plus `STDOUT_CHAT_NO_NOTIFY=1` to silence a single run. Flag beats env beats config.
+
+### Technical
+
+- New `lib/notify.js`: `createNotifier()` wraps `osascript -e 'display notification …'` (darwin) / `notify-send -a stdout-chat` (linux); Windows and other platforms are a no-op. AppleScript escaping (`\` then `"`), body cut at 120 code points, control characters stripped, 3 s exec timeout, one banner per 2 s (drops, no queue). The first exec error disables banners for the session and prints one dim `· notifications unavailable here`.
+- `lib/render.js`: `isAddressedTo(msg, myNick)` → `'reply' | 'mention' | null` (word-bounded, case-insensitive, `a@nick` does not count).
+- `lib/session.js`: banner hook fires only on live `msg` events that were actually printed; `verifyKey({ quiet })` for `--tail`, which now checks a stored key silently to learn the nick.
+- `lib/config.js`: `notify` persisted in `config.json`; `/key` preserves it. Files stay `0600`.
+- Tests: 55 → 76 (`test/notify.test.js` new; `isAddressedTo`, session, config and smoke cases added).
+
+## [0.1.0] — 2026-09-20
+
+- First release: read, tail and post to `#void` from the terminal · zero dependencies · Node ≥ 18.

package/README.md

@@ -47,7 +47,9 @@ The key is checked against the server, then saved to `~/.config/stdout-chat/conf
 | `/r <id> text` | reply to a line — ids are the dim column on the left |
 | `/top` | this week's top authors |
 | `/who` | how many are in the room |
+| `/dm <nick|sid>` | invite them to a private chat — a line's id targets its author; the chat itself opens on your phone |
 | `/key sc_…` | save a key · `/key` shows who you are · `/key off` forgets it |
+| `/notify` | desktop banners: `/notify` shows the level · `/notify mentions` (default) · `all` · `off` |
 | `/clear` | clear the screen |
 | `/help` | list this |
 | `/quit` | leave (Ctrl-C and Ctrl-D too) |
@@ -62,6 +64,7 @@ Server errors are printed as the server phrases them (`slow down · retry in 2s`
 -n <count>      lines of history (default 30, max 100)
 --api <url>     API base (default https://api.stdout.chat; env STDOUT_CHAT_API)
 --no-color      plain output (NO_COLOR is honoured too)
+--no-notify     no desktop banners this run (env STDOUT_CHAT_NO_NOTIFY=1 works too)
 --help, --version
 ```
 
@@ -95,6 +98,23 @@ void() {  # void · void -f · void -r a1b4 text · void some words
 - `GET /void` for history, `GET /void/stream` (Server-Sent Events) for the live feed, `POST /void` to speak, `GET /void/me` to check a key. All JSON.
 - Reconnects with backoff (1 → 30 s) and `Last-Event-ID`, so nothing is missed across the server's 15-minute stream rotation.
 - Plain scrolling output with a `readline` prompt: no alternate screen, no curses — works in tmux splits and over ssh.
+- `POST /void/dm` sends a private-chat invite (`/dm`). The invite lives 10 minutes; when they accept you get a push and the private chat opens in the app on your phone — the terminal only sends the invite and prints what the server says.
+
+## Notifications
+
+The terminal is usually behind the editor. When someone replies to your line or writes `@you` while the client is running, a desktop banner shows up:
+
+```
+#void
+mox → you
+ceiling fans, obviously
+```
+
+- **When:** live lines only — never the history printed at start, never your own lines. Works at the `>` prompt and in `--tail`; `--read` and piped output never notify.
+- **Levels:** `mentions` (default: replies to you and `@nick`), `all` (every line by someone else), `off`. Set with `/notify mentions|all|off` at the prompt; it is saved to `config.json`. In `--tail` the key on file is checked quietly so `mentions` knows your nick; without a key only `all` can fire.
+- **Off for one run:** `--no-notify`, or `STDOUT_CHAT_NO_NOTIFY=1`. Flag beats env beats config.
+- **How:** macOS via `osascript` (`display notification`), Linux via `notify-send` (needs `libnotify`), no sound. Windows: nothing yet. If the local command fails once, banners switch off for the session and one dim `· notifications unavailable here` is printed. At most one banner per 2 seconds — a burst is dropped, not queued.
+- **Privacy:** nothing leaves the machine. The banner is a line the room already sent you, handed to a local binary; no extra requests, no background process.
 
 ## Privacy
 

package/bin/stdout-chat.js

@@ -6,7 +6,8 @@ import { createApi, DEFAULT_API, errorMessage } from '../lib/api.js';
 import { loadConfig } from '../lib/config.js';
 import { createUI } from '../lib/ui.js';
 import { Session } from '../lib/session.js';
-import { renderError } from '../lib/render.js';
+import { renderError, renderInfo } from '../lib/render.js';
+import { createNotifier } from '../lib/notify.js';
 
 const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -19,20 +20,24 @@ usage: npx stdout-chat [options]
   -n <count>      how many lines to load (default 30, max 100)
   --api <url>     API base (default ${DEFAULT_API}; env STDOUT_CHAT_API)
   --no-color      plain output (NO_COLOR is honoured too)
+  --no-notify     no desktop banners (env STDOUT_CHAT_NO_NOTIFY=1 works too)
   -h, --help      this text
   -v, --version   print the version
 
 at the prompt:
-  /help  /r <id> text  /top  /who  /key sc_…  /key off  /clear  /quit
+  /help  /r <id> text  /dm <nick|sid>  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
   anything else is posted to #void
 
+desktop banners (macOS / Linux) when someone replies to you or writes @you —
+only while the prompt or --tail is running · /notify mentions|all|off
+
 key file: ~/.config/stdout-chat/config.json (get a key in the app: /key)
 no telemetry · https://stdout.chat/void`;
 
 class UsageError extends Error {}
 
 function parseArgs(argv) {
-  const o = { read: false, tail: false, api: null, color: true, help: false, version: false, n: 30 };
+  const o = { read: false, tail: false, api: null, color: true, notify: null, help: false, version: false, n: 30 };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const eq = a.startsWith('--') ? a.indexOf('=') : -1;
@@ -45,6 +50,8 @@ function parseArgs(argv) {
       case '--api': o.api = next(); if (!o.api) throw new UsageError('--api needs a url'); break;
       case '--no-color': o.color = false; break;
       case '--color': o.color = true; break;
+      case '--no-notify': o.notify = false; break;
+      case '--notify': o.notify = true; break;
       case '-h': case '--help': o.help = true; break;
       case '-v': case '--version': o.version = true; break;
       case '-n': case '--lines': {
@@ -68,6 +75,15 @@ function wantColor(opts) {
   return Boolean(process.stdout.isTTY);
 }
 
+// flag > env > config > default. Returns the level ('mentions' | 'all' | 'off').
+function wantNotify(opts, cfg) {
+  if (opts.notify === false) return 'off';
+  if (opts.notify === true) return cfg.notify && cfg.notify !== 'off' ? cfg.notify : 'mentions';
+  const env = process.env.STDOUT_CHAT_NO_NOTIFY;
+  if (env != null && env !== '' && env !== '0') return 'off';
+  return cfg.notify || 'mentions';
+}
+
 async function main() {
   let opts;
   try {
@@ -103,8 +119,18 @@ async function main() {
     persistApi: api.base !== DEFAULT_API ? api.base : null, // keep a non-default api next to the key
     n: opts.n,
     onQuit: () => shutdown(0),
+    notifyLevel: wantNotify(opts, cfg),
   });
   session.onClear = () => ui.clear();
+  // Banners only where a human is watching a live feed: never in --read, never
+  // when stdout is a pipe (follow mode). The level gates the hook at runtime, so
+  // `/notify all` after `--no-notify` works without a restart; nothing spawns
+  // until a line actually qualifies.
+  if (mode === 'interactive' || mode === 'tail') {
+    session.notify = createNotifier({
+      onUnavailable: () => ui.print(renderInfo('· notifications unavailable here', { color })),
+    }).notify;
+  }
 
   function shutdown(code = 0) {
     if (closing) return;
@@ -130,6 +156,9 @@ async function main() {
   process.on('SIGHUP', () => shutdown(0));
   if (mode !== 'interactive') process.on('SIGINT', () => shutdown(0));
 
+  if (mode === 'tail' && session.key && session.notify) {
+    await session.verifyKey({ quiet: true }); // only to learn the nick for reply / @mention matching
+  }
   if (mode !== 'tail') {
     await session.verifyKey();
     try {

package/lib/api.js

@@ -90,6 +90,20 @@ export function createApi({ base = DEFAULT_API, version = '0.0.0', fetchImpl = n
       });
     },
 
+    /**
+     * POST /void/dm {sid} | {nick} → 201 { id, to, expires_at }. Same shape as
+     * post(): JSON in, JSON out (Accept: application/json); the session builds
+     * the human line from `to`. Errors carry the server's message verbatim.
+     */
+    dm({ nick, sid } = {}, key) {
+      const body = sid != null && sid !== '' ? { sid: String(sid) } : { nick: String(nick == null ? '' : nick) };
+      return json(`${root}/void/dm`, {
+        method: 'POST',
+        headers: headers({ 'Content-Type': 'application/json' }, key),
+        body: JSON.stringify(body),
+      });
+    },
+
     /** GET /void/stream → Response (200, body is a ReadableStream). Throws ApiError on non-2xx. */
     async openStream({ lastEventId = null, signal = null } = {}) {
       const extra = { 'Cache-Control': 'no-cache' };

package/lib/config.js

@@ -1,9 +1,10 @@
-// Key storage: ~/.config/stdout-chat/config.json  { "key": "sc_…", "api": "https://…" }
+// Key storage: ~/.config/stdout-chat/config.json  { "key": "sc_…", "api": "https://…", "notify": "mentions" }
 // plus a plain-text twin ~/.config/stdout-chat/key so shell one-liners can
 // `$(cat ~/.config/stdout-chat/key)`. Directory 0700, files 0600.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { NOTIFY_LEVELS } from './notify.js';
 
 export function configDir() {
   if (process.env.STDOUT_CHAT_CONFIG_DIR) return process.env.STDOUT_CHAT_CONFIG_DIR;
@@ -27,6 +28,7 @@ export function loadConfig() {
     const out = {};
     if (typeof parsed.key === 'string' && parsed.key) out.key = parsed.key;
     if (typeof parsed.api === 'string' && parsed.api) out.api = parsed.api;
+    if (NOTIFY_LEVELS.includes(parsed.notify)) out.notify = parsed.notify;
     return out;
   } catch {
     return {};
@@ -44,14 +46,15 @@ function rmQuiet(file) {
   try { fs.unlinkSync(file); } catch { /* absent */ }
 }
 
-/** Writes config.json (+ plain `key` file). `api` is omitted when falsy. */
-export function saveConfig({ key, api } = {}) {
+/** Writes config.json (+ plain `key` file). `api` / `notify` are omitted when falsy or unknown. */
+export function saveConfig({ key, api, notify } = {}) {
   const dir = configDir();
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   try { fs.chmodSync(dir, 0o700); } catch { /* win32 */ }
   const data = {};
   if (key) data.key = key;
   if (api) data.api = api;
+  if (NOTIFY_LEVELS.includes(notify)) data.notify = notify;
   writePrivate(configPath(), `${JSON.stringify(data, null, 2)}\n`);
   if (key) writePrivate(keyPath(), `${key}\n`);
   else rmQuiet(keyPath());

package/lib/render.js

@@ -161,6 +161,22 @@ export function displayNick(msg, collisions) {
   return nick;
 }
 
+/**
+ * Is this line aimed at me? A reply to my nick → 'reply'; `@nick` in the text
+ * (word-bounded, case-insensitive, `a@nick` does not count) → 'mention'; else null.
+ */
+export function isAddressedTo(msg, myNick) {
+  if (!msg || typeof msg !== 'object' || myNick == null || myNick === '') return null;
+  const me = String(myNick);
+  const reply = msg.reply && typeof msg.reply === 'object' ? msg.reply : null;
+  if (reply && reply.username != null && String(reply.username).toLowerCase() === me.toLowerCase()) return 'reply';
+  const text = msg.text == null ? '' : String(msg.text);
+  if (!text) return null;
+  const escaped = me.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(^|[^\\w@])@${escaped}(?![\\w])`, 'i');
+  return re.test(text) ? 'mention' : null;
+}
+
 /** `[["❤️",2],["😂",1]]` or `{"❤️":2}` → `❤️ 2 😂 1`. Unknown shapes → ''. */
 export function formatReactions(reactions) {
   if (!reactions) return '';

package/lib/session.js

@@ -4,9 +4,10 @@ import { errorMessage } from './api.js';
 import { readEvents } from './sse.js';
 import {
   renderLine, renderReactions, renderHide, renderTopic, renderHeader, renderTop,
-  renderError, renderInfo, MEDALS,
+  renderError, renderInfo, isAddressedTo, MEDALS,
 } from './render.js';
 import * as defaultConfig from './config.js';
+import { NOTIFY_LEVELS } from './notify.js';
 
 export const HINT_NO_KEY = 'type /key sc_… to post · get it in the app: /key';
 export const HELP_TEXT = [
@@ -14,8 +15,10 @@ export const HELP_TEXT = [
   '/r <id> text       reply to a line (ids are the dim column on the left)',
   '/top               this week\'s top authors',
   '/who               how many are in the room',
+  '/dm <nick|sid>     invite them to a private chat (accept happens in the app)',
   '/key sc_…          save your key (get it in the app: /key)',
   '/key off           forget the key on this machine (revoke it in the app)',
+  '/notify            desktop banners: mentions (default) · all · off',
   '/clear             clear the screen',
   '/quit              leave (Ctrl-C / Ctrl-D work too)',
   'anything else is posted to #void · @nick mentions pass through as typed',
@@ -56,6 +59,8 @@ export class Session {
     onQuit = () => {},
     onKeyChange = () => {},
     timers = { setTimeout, clearTimeout },
+    notify = null,
+    notifyLevel = 'mentions',
   }) {
     this.api = api;
     this.print = print;
@@ -68,6 +73,10 @@ export class Session {
     this.onQuit = onQuit;
     this.onKeyChange = onKeyChange;
     this.timers = timers;
+    // Desktop banner hook: (title, subtitle, body) → void. Null in read/follow
+    // modes and when the user opted out, so the session never spawns anything.
+    this.notify = typeof notify === 'function' ? notify : null;
+    this.notifyLevel = NOTIFY_LEVELS.includes(notifyLevel) ? notifyLevel : 'mentions';
 
     this.me = null;
     this.topic = null;
@@ -94,13 +103,17 @@ export class Session {
 
   // ── startup ─────────────────────────────────────────────────────────────
 
-  /** Verifies the stored key via /void/me. Never throws; leaves the key in place on failure. */
-  async verifyKey() {
+  /**
+   * Verifies the stored key via /void/me. Never throws; leaves the key in place on failure.
+   * `quiet` swallows the warnings — --tail only needs the nick for mention matching.
+   */
+  async verifyKey({ quiet = false } = {}) {
     if (!this.key) return null;
     try {
       this.me = await this.api.getMe(this.key);
       return this.me;
     } catch (err) {
+      if (quiet) return null;
       if (err && err.status === 401) this.error(`${errorMessage(err)} · /key sc_… to replace it`);
       else this.info(`· couldn't verify key: ${errorMessage(err)}`);
       return null;
@@ -178,7 +191,7 @@ export class Session {
       case 'msg':
       case 'message': {
         if (data.id == null && ev.id) data.id = ev.id;
-        this.printMsg(data);
+        if (this.printMsg(data)) this.maybeNotify(data); // live lines only: history goes through loadHistory
         break;
       }
       case 'react': {
@@ -210,6 +223,18 @@ export class Session {
     return undefined;
   }
 
+  /** Desktop banner for a freshly printed live line, per `notifyLevel`. Own lines never notify. */
+  maybeNotify(msg) {
+    if (!this.notify || this.notifyLevel === 'off') return;
+    const myNick = this.me ? this.me.username : null;
+    const nick = msg.username == null || msg.username === '' ? 'anon' : String(msg.username);
+    if (myNick != null && msg.username === myNick) return;
+    const how = isAddressedTo(msg, myNick);
+    if (!how && this.notifyLevel !== 'all') return;
+    const subtitle = how === 'reply' ? `${nick} → you` : how === 'mention' ? `${nick} @you` : nick;
+    this.notify('#void', subtitle, msg.text == null ? '' : String(msg.text));
+  }
+
   // ── stream ──────────────────────────────────────────────────────────────
 
   /** Runs until `signal` aborts. Backoff 1,2,4…30 s; `bye` → immediate quiet reconnect. */
@@ -285,9 +310,15 @@ export class Session {
       case '/who':
         await this.cmdWho();
         return;
+      case '/dm':
+        await this.cmdDm(rest);
+        return;
       case '/key':
         await this.cmdKey(rest);
         return;
+      case '/notify':
+        this.cmdNotify(rest);
+        return;
       case '/r': case '/reply': {
         const m = rest.match(/^(\S+)\s+([\s\S]+)$/);
         if (!m) { this.info('usage: /r <id> text'); return; }
@@ -325,6 +356,28 @@ export class Session {
     this.info(this.count === 1 ? '1 in room' : `${this.count} in room`);
   }
 
+  /** `/dm <nick|sid>`: a sid seen this session targets that line's author, anything else is a nick. */
+  async cmdDm(arg) {
+    if (!this.key) { this.info(HINT_NO_KEY); return; }
+    if (!arg) { this.info('usage: /dm <nick|sid>'); return; }
+    const target = this.isKnownSid(arg) ? { sid: arg } : { nick: arg };
+    let res;
+    try {
+      res = await this.api.dm(target, this.key);
+    } catch (err) {
+      this.error(errorMessage(err));
+      return;
+    }
+    const to = res && res.to != null && res.to !== '' ? String(res.to) : arg;
+    this.info(`invite sent · ${to} has 10 min · you'll get a push when they accept`);
+  }
+
+  /** True when `s` is the short id (the dim left column) of a line seen this session. */
+  isKnownSid(s) {
+    for (const m of this.lines.values()) if (m && m.sid != null && String(m.sid) === s) return true;
+    return false;
+  }
+
   async cmdKey(arg) {
     if (!arg) {
       if (this.me) this.info(greeting(this.me));
@@ -354,11 +407,33 @@ export class Session {
     this.key = arg;
     this.me = me;
     try {
-      this.config.saveConfig({ key: arg, api: this.persistApi || undefined });
+      this.config.saveConfig({ key: arg, api: this.persistApi || undefined, notify: this.notifyLevel });
     } catch (err) {
       this.error(`saved in memory only · ${errorMessage(err)}`);
     }
     this.onKeyChange(arg);
     this.info(greeting(me) || 'key saved');
   }
+
+  cmdNotify(arg) {
+    if (!arg) {
+      this.info(`notifications: ${this.notifyLevel}`);
+      return;
+    }
+    const level = arg.toLowerCase();
+    if (!NOTIFY_LEVELS.includes(level)) {
+      this.info('usage: /notify mentions · /notify all · /notify off');
+      return;
+    }
+    this.notifyLevel = level;
+    try {
+      // The key stays as it is; only the level changes. No key → no file is written
+      // for the key twin, but the level still persists in config.json.
+      this.config.saveConfig({ key: this.key || undefined, api: this.persistApi || undefined, notify: level });
+    } catch (err) {
+      this.error(`set for this session only · ${errorMessage(err)}`);
+      return;
+    }
+    this.info(`notifications: ${level}`);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stdout-chat",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "#void from your terminal — read, tail and post to stdout.chat's public room. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin",
     "lib",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {