stdout-chat 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `stdout-chat` (the CLI). Dates are release dates.
 
+## [0.4.1] — 2026-09-20
+
+### What's New
+
+- Your own line shows up once. Hitting Enter used to leave `> hi` on screen and then the feed printed `in  dmitrii  hi` right under it — two copies of everything you said, while the app showed one. Now the typed line is wiped the moment you submit and the feed's copy (with its id, ready for `/r`) is the only one. If the post fails (`slow down · retry in 2s`, revoked key), the line comes back dim above the error so you can see what did not go out — ↑ still recalls it.
+
+### Technical
+
+- `lib/ui.js`: `eraseSubmitted(line)` — cursor up + clear for every row the echoed `> line` took (`ceil((prompt + line) / columns)`), then column 0. Must run synchronously from `onLine`, before any await: readline has just written the newline, so the row above the cursor is exactly the echo; the next `print`/`prompt(true)` re-draws the prompt as usual.
+- `lib/session.js`: `echoesViaStream(line)` — true for plain text and `/r|/reply <id> text`, false for commands, `/r` usage and unknown slashes (the server's 422 keeps its `> /dance` context). `post(text, reply, { unsent })`: on failure prints `> <unsent>` via `info` (dim) before the error; `handleInput` passes the raw line for posts and replies only.
+- `bin/stdout-chat.js`: `onLine` calls `ui.eraseSubmitted(line)` when `echoesViaStream(line)`, then `handleInput`.
+- Tests: 96 → 99 (erase sequences for one row and a wrapped line; `echoesViaStream` table; failed post restores the line, a failed command does not).
+
+## [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, echoesViaStream } 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,
@@ -173,6 +178,9 @@ async function main() {
   if (mode === 'interactive') {
     ui.start({
       onLine: async (line) => {
+        // Synchronous, before any await: the row above the cursor is still
+        // the echoed input. Its rendering arrives over the stream instead.
+        if (echoesViaStream(line)) ui.eraseSubmitted(line);
         try {
           await session.handleInput(line);
         } catch (err) {

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,21 @@ 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';
+
+/**
+ * True for input whose rendering comes back over the stream (a post, or a
+ * `/r <id> text` reply): the typed line is erased on submit so the feed shows
+ * the message once. Commands (`/top`, `/key …`, unknown slashes the server
+ * answers with 422) keep their `> /cmd` line as context.
+ */
+export function echoesViaStream(raw) {
+  const line = String(raw == null ? '' : raw).trim();
+  if (!line) return false;
+  if (line[0] !== '/') return true;
+  return /^\/(r|reply)\s+\S+\s+\S/.test(line);
+}
 export const HELP_TEXT = [
   '/help              this list',
   '/r <id> text       reply to a line (ids are the dim column on the left)',
@@ -291,7 +306,7 @@ export class Session {
   async handleInput(raw) {
     const line = String(raw == null ? '' : raw).trim();
     if (!line) return;
-    if (line[0] !== '/') { await this.post(line); return; }
+    if (line[0] !== '/') { await this.post(line, null, { unsent: line }); return; }
     const cmd = line.split(/\s+/, 1)[0].toLowerCase();
     const rest = line.slice(cmd.length).trim();
     switch (cmd) {
@@ -322,7 +337,7 @@ export class Session {
       case '/r': case '/reply': {
         const m = rest.match(/^(\S+)\s+([\s\S]+)$/);
         if (!m) { this.info('usage: /r <id> text'); return; }
-        await this.post(m[2].trim(), m[1]);
+        await this.post(m[2].trim(), m[1], { unsent: line });
         return;
       }
       default:
@@ -330,12 +345,19 @@ export class Session {
     }
   }
 
-  async post(text, reply = null) {
+  /**
+   * `unsent` is the raw input line to put back (dim, with its prompt) when the
+   * post fails: the UI erased the typed line on submit for lines that echo via
+   * the stream (see `echoesViaStream`), so an error alone would leave "slow
+   * down · retry in 2s" with nothing above it to retry.
+   */
+  async post(text, reply = null, { unsent = null } = {}) {
     if (!this.key) { this.info(HINT_NO_KEY); return false; }
     try {
       await this.api.post({ text, reply }, this.key); // echo arrives via SSE, not from the response
       return true;
     } catch (err) {
+      if (unsent) this.info(`> ${unsent}`);
       this.error(errorMessage(err));
       return false;
     }
@@ -372,6 +394,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();
@@ -43,6 +67,25 @@ export function createUI({ input = process.stdin, output = process.stdout, promp
     if (rl) rl.prompt(true);
   }
 
+  /**
+   * Erase the line the user just submitted (readline has already echoed
+   * `> text` and moved to a fresh row). Call it synchronously from `onLine`,
+   * before anything else prints — the row above the cursor is then exactly
+   * that echo. A long input that wrapped takes several rows; all of them go.
+   * Used for lines whose real rendering comes back over the stream, so the
+   * feed shows a message once, not "> hi" and then "in  dmitrii  hi".
+   */
+  function eraseSubmitted(line) {
+    if (!rl) return;
+    const cols = Math.max(1, output.columns || 80);
+    const rows = Math.max(1, Math.ceil((prompt.length + String(line == null ? '' : line).length) / cols));
+    for (let i = 0; i < rows; i++) {
+      readline.moveCursor(output, 0, -1);
+      readline.clearLine(output, 0);
+    }
+    readline.cursorTo(output, 0);
+  }
+
   /** Remove entries matching `pred` from the in-memory input history (e.g. `/key sc_…`). */
   function scrubHistory(pred) {
     if (rl && Array.isArray(rl.history)) rl.history = rl.history.filter((h) => !pred(h));
@@ -53,6 +96,7 @@ export function createUI({ input = process.stdin, output = process.stdout, promp
     start,
     close,
     clear,
+    eraseSubmitted,
     scrubHistory,
     get interactive() { return rl !== null; },
   };

package/package.json

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