stdout-chat 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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

package/README.md

@@ -54,6 +54,8 @@ The key is checked against the server, then saved to `~/.config/stdout-chat/conf
 | `/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
@@ -97,7 +99,7 @@ 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';
 
@@ -26,7 +27,7 @@ usage: npx stdout-chat [options]
 
 at the prompt:
   /help  /r <id> text  /dm <nick|sid>  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
-  anything else is posted to #void
+  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/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,6 +10,8 @@ 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)',
@@ -372,6 +374,20 @@ export class Session {
     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;

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.3.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": {