stdout-chat 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to `stdout-chat` (the CLI). Dates are release dates.
 
+## [0.4.0] — 2026-09-20
+
+### What's New
+
+- Type `/` at the prompt and one dim line lists the commands (`commands · /help · /r <id> text · /dm <nick|sid> · /top · /who · /key · /notify · /clear · /quit`) — once per line, the input stays put. `/help` is unchanged.
+- Tab completion: `/n⇥` → `/notify `, `/notify a⇥` → `all` (`mentions|all|off`), `/key ⇥` → `off`, and `@ki⇥` → `@kira ` from the nicks seen this session (most recent first, case-insensitive), anywhere in the line — inside a `/r` reply too. Plain text: Tab does nothing.
+
+### Technical
+
+- New `lib/complete.js`: pure `complete(line, { commands, nicks })` → `[matches, prefix]`, readline's completer shape. Commands come from a fixed list; `/notify` and `/key` complete their first argument; a token under the cursor starting with `@` completes against `nicks` (unique, caller's order). Everything else → `[[], '']`.
+- `lib/ui.js`: `createUI({ completer, hint })`. The completer is handed to `readline.createInterface`. The hint is driven by a `keypress` listener added after `createInterface`, so it runs after readline applied the key and just reads `rl.line`: `'/'` and not yet hinted → print; `''` → reset; `'line'` → reset. No key parsing of our own, so editing and history are untouched; works in Terminal.app and tmux. Off in `--read` / `--tail` / piped modes (no prompt there).
+- `lib/session.js`: `SLASH_HINT`; `nicks()` (most recent first, unique, no `anon`) feeds `@` completion. `bin/stdout-chat.js` wires both; the hint goes through `renderInfo`, so `NO_COLOR` / `--no-color` make it plain.
+- Tests: 82 → 96 (`test/complete.test.js` and `test/ui.test.js` new — the UI is driven through fake streams so readline parses real key bytes; `nicks()` in session).
+
+## [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

package/README.md

@@ -47,12 +47,15 @@ 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) |
 
+type `/` to see the commands · Tab completes commands and @nicks (`/n⇥` → `/notify `, `/notify a⇥` → `all`, `@ki⇥` → `@kira `).
+
 Server errors are printed as the server phrases them (`slow down · retry in 2s`), never as stack traces. Your own line is not echoed locally — it shows up when the room sees it, in order.
 
 ## Flags
@@ -96,7 +99,8 @@ 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.
+- Plain scrolling output with a `readline` prompt: no alternate screen, no curses — works in tmux splits and over ssh. Tab completion is readline's own `completer`; the `/` hint is one dim line printed above the prompt the first time a line starts with `/`.
+- `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
 

package/bin/stdout-chat.js

@@ -5,7 +5,8 @@ import process from 'node:process';
 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 { Session, SLASH_HINT } from '../lib/session.js';
+import { complete } from '../lib/complete.js';
 import { renderError, renderInfo } from '../lib/render.js';
 import { createNotifier } from '../lib/notify.js';
 
@@ -25,8 +26,8 @@ usage: npx stdout-chat [options]
   -v, --version   print the version
 
 at the prompt:
-  /help  /r <id> text  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
-  anything else is posted to #void
+  /help  /r <id> text  /dm <nick|sid>  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
+  anything else is posted to #void · type / to see the commands · Tab completes commands and @nicks
 
 desktop banners (macOS / Linux) when someone replies to you or writes @you —
 only while the prompt or --tail is running · /notify mentions|all|off
@@ -106,11 +107,15 @@ async function main() {
       : (process.stdin.isTTY && process.stdout.isTTY) ? 'interactive'
         : 'follow'; // piped: history + stream, no prompt
 
-  const ui = createUI();
+  let session = null; // assigned below; the completer only runs on Tab, at the prompt
+  const ui = createUI({
+    completer: (line) => complete(line, { nicks: session ? session.nicks() : [] }),
+    hint: renderInfo(SLASH_HINT, { color }),
+  });
   const stop = new AbortController();
   let closing = false;
 
-  const session = new Session({
+  session = new Session({
     api,
     print: ui.print,
     color,

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/complete.js

@@ -0,0 +1,41 @@
+// Tab completion for the `> ` prompt. Pure: (line, { commands, nicks }) →
+// [matches, prefix], the shape readline's `completer` option expects. `line`
+// is the input up to the cursor; `prefix` is the part of it that the matches
+// replace (readline appends what the common prefix adds beyond it).
+export const COMMANDS = ['/help', '/r ', '/dm ', '/top', '/who', '/key ', '/notify ', '/clear', '/quit'];
+export const NOTIFY_ARGS = ['mentions', 'all', 'off'];
+export const KEY_ARGS = ['off'];
+const NONE = [[], ''];
+
+function startsWithFold(s, prefix) {
+  return s.slice(0, prefix.length).toLowerCase() === prefix.toLowerCase();
+}
+
+/** `@ki` under the cursor → `@kira ` (unique nicks, caller's order, case-insensitive). */
+function completeNick(line, nicks) {
+  const token = line.slice(line.search(/\S*$/));
+  if (token[0] !== '@') return NONE;
+  const want = token.slice(1);
+  const seen = new Set();
+  const matches = [];
+  for (const raw of nicks || []) {
+    const nick = String(raw == null ? '' : raw);
+    if (!nick || seen.has(nick) || !startsWithFold(nick, want)) continue;
+    seen.add(nick);
+    matches.push(`@${nick} `);
+  }
+  return [matches, token];
+}
+
+export function complete(line, { commands = COMMANDS, nicks = [] } = {}) {
+  const s = String(line == null ? '' : line);
+  if (s[0] === '/') {
+    const sp = s.search(/\s/);
+    if (sp < 0) return [commands.filter((c) => startsWithFold(c, s)), s]; // still typing the command
+    const cmd = s.slice(0, sp).toLowerCase();
+    const arg = s.slice(sp).trimStart();
+    const args = cmd === '/notify' ? NOTIFY_ARGS : cmd === '/key' ? KEY_ARGS : null;
+    if (args && !/\s/.test(arg)) return [args.filter((a) => startsWithFold(a, arg)), arg];
+  }
+  return completeNick(s, nicks);
+}

package/lib/session.js

@@ -10,11 +10,14 @@ 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';
+// Printed once above the prompt when a line starts with `/` (see lib/ui.js).
+export const SLASH_HINT = 'commands · /help · /r <id> text · /dm <nick|sid> · /top · /who · /key · /notify · /clear · /quit';
 export const HELP_TEXT = [
   '/help              this list',
   '/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',
@@ -309,6 +312,9 @@ export class Session {
       case '/who':
         await this.cmdWho();
         return;
+      case '/dm':
+        await this.cmdDm(rest);
+        return;
       case '/key':
         await this.cmdKey(rest);
         return;
@@ -352,6 +358,42 @@ 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`);
+  }
+
+  /** Nicks seen this session, most recent line first, unique; `anon` is not a nick. Feeds @-completion. */
+  nicks() {
+    const seen = new Set();
+    const out = [];
+    for (const m of [...this.lines.values()].reverse()) {
+      if (!m || m.username == null || m.username === '') continue;
+      const nick = String(m.username);
+      if (seen.has(nick)) continue;
+      seen.add(nick);
+      out.push(nick);
+    }
+    return out;
+  }
+
+  /** 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));

package/lib/ui.js

@@ -2,9 +2,15 @@
 // bottom. No alternate screen, no curses — works in tmux splits and pipes.
 import readline from 'node:readline';
 
-export function createUI({ input = process.stdin, output = process.stdout, prompt = '> ' } = {}) {
+/**
+ * `completer(line) → [matches, prefix]` is handed to readline as-is (see
+ * lib/complete.js). `hint` is one already-rendered line printed above the
+ * prompt the first time an input line becomes exactly `/`.
+ */
+export function createUI({ input = process.stdin, output = process.stdout, prompt = '> ', completer = null, hint = null } = {}) {
   let rl = null;
   let closed = false;
+  let hinted = false; // the `/` hint was shown for the line being typed
 
   function print(text) {
     if (closed && !rl) { output.write(`${text}\n`); return; }
@@ -16,14 +22,32 @@ export function createUI({ input = process.stdin, output = process.stdout, promp
     if (rl) rl.prompt(true);
   }
 
+  // Why a keypress listener that reads `rl.line` (and not our own key parser):
+  // readline installs its keypress handler in createInterface, so a listener
+  // added afterwards runs after readline has already applied the key — `rl.line`
+  // is the edited line, whatever the key was (typed char, paste, backspace,
+  // Ctrl-U, history arrow). We never touch the key ourselves, so editing and
+  // history behave exactly as before, in Terminal.app and in tmux alike. The
+  // flag resets on submit ('line') and whenever the line is empty again.
+  function onKeypress() {
+    if (!rl || !hint) return;
+    if (rl.line === '') { hinted = false; return; }
+    if (rl.line === '/' && !hinted) { hinted = true; print(hint); }
+  }
+
   function start({ onLine, onClose }) {
-    rl = readline.createInterface({ input, output, prompt, terminal: true, historySize: 200 });
-    rl.on('line', (line) => { Promise.resolve(onLine(line)).catch(() => {}).then(() => { if (rl) rl.prompt(true); }); });
+    const opts = { input, output, prompt, terminal: true, historySize: 200 };
+    if (typeof completer === 'function') opts.completer = completer;
+    rl = readline.createInterface(opts);
+    hinted = false;
+    input.on('keypress', onKeypress);
+    rl.on('line', (line) => { hinted = false; Promise.resolve(onLine(line)).catch(() => {}).then(() => { if (rl) rl.prompt(true); }); });
     rl.on('SIGINT', () => close());
     rl.on('close', () => {
       const wasOpen = !closed;
       closed = true;
       rl = null;
+      input.removeListener('keypress', onKeypress);
       if (wasOpen && onClose) onClose();
     });
     rl.prompt();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stdout-chat",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "#void from your terminal — read, tail and post to stdout.chat's public room. Zero dependencies.",
   "type": "module",
   "bin": {