keystream-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lihao Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,457 @@
+# Keystream
+
+Keystream is a real-time terminal chat app built with Bun. It is designed to do two jobs at once:
+
+- let multiple users chat live from the CLI
+- turn normal chat usage into Vim-style keyboard practice
+
+The app has a standalone Bun WebSocket server, a full-screen terminal client, persistent SQLite history, room-based chat, and a modal UI with `NORMAL`, `INSERT`, `COMMAND`, and `SEARCH` modes.
+
+## Key Features
+
+- Real-time multi-user chat over WebSockets
+- Persistent message history stored in SQLite
+- Room-based messaging with live room switching
+- Full-screen terminal UI built for keyboard-first use
+- Vim-style modal interaction
+- Motion counts like `5j`
+- Feed jumps with `gg` and `G`
+- Search mode with `/`
+- Command mode with `:`
+- Strict Vim mode that blocks arrow keys and tracks violations
+- Lightweight training stats for mode time, streaks, and arrow-key usage
+- Auto-reconnect behavior in the CLI client
+- Local multi-client practice launcher with `tmux`
+
+## Current Scope
+
+This version is intentionally narrow:
+
+- authentication is username-only
+- chat is room-first
+- direct messages are not implemented
+- file upload, reactions, and message editing are not implemented
+- this is best suited for trusted users or local/LAN usage unless you add TLS and stronger access control around it
+
+## Requirements
+
+- [Bun](https://bun.sh/) 1.3+
+- macOS, Linux, or another environment where Bun and terminal WebSocket clients work
+- `tmux` only if you want to use `bun run dev:stack`
+
+## Install
+
+```bash
+bun install
+```
+
+## Quick Start
+
+### Option 1: Run the full local practice stack
+
+This is the fastest way to try Keystream as a Vim practice tool.
+
+```bash
+bun run dev:stack
+```
+
+What it does:
+
+- starts one server
+- opens three CLI clients in a tiled `tmux` session
+- connects them to the same `general` room
+- enables `--strict-vim` in each client
+
+If `tmux` is not installed, use the manual setup below.
+
+### Option 2: Run server and clients manually
+
+Start the server:
+
+```bash
+bun --cwd apps/server src/index.ts --host 0.0.0.0 --port 3088 --db ./data/keystream.sqlite
+```
+
+Start a client:
+
+```bash
+bun --cwd apps/cli src/index.ts --url ws://127.0.0.1:3088 --username alice --room general --strict-vim
+```
+
+Start another client in a second terminal:
+
+```bash
+bun --cwd apps/cli src/index.ts --url ws://127.0.0.1:3088 --username bob --room general --strict-vim
+```
+
+You can omit `--strict-vim` if you want arrow keys to translate to motions instead of being counted as violations.
+
+## Public Install And Distribution
+
+### Install the public npm CLI
+
+Once published, the CLI can be installed globally with npm:
+
+```bash
+npm install -g keystream-cli
+keystream --help
+```
+
+The installed command is `keystream`, while the package name is `keystream-cli`.
+
+### Run the published CLI
+
+```bash
+keystream --url ws://127.0.0.1:3088 --username alice --room general --strict-vim
+```
+
+### Pull the backend Docker image
+
+Once a tagged GitHub release has published the backend image:
+
+```bash
+docker pull ghcr.io/lihaowang/keystream-server:v0.0.1
+```
+
+### Run the backend Docker image with persistent storage
+
+```bash
+mkdir -p ./keystream-data
+
+docker run --rm \
+  -p 3088:3088 \
+  -e KEYSTREAM_HOST=0.0.0.0 \
+  -e KEYSTREAM_PORT=3088 \
+  -e KEYSTREAM_DB=/data/keystream.sqlite \
+  -v "$(pwd)/keystream-data:/data" \
+  ghcr.io/lihaowang/keystream-server:v0.0.1
+```
+
+This mounted `/data` path is the persistent SQLite store. If you do not mount it, history will not survive container replacement.
+
+## CLI Flags And Env Vars
+
+### Server
+
+Command:
+
+```bash
+bun --cwd apps/server src/index.ts --host 0.0.0.0 --port 3088 --db ./data/keystream.sqlite
+```
+
+Flags:
+
+- `--host` bind address, default `0.0.0.0`
+- `--port` listening port, default `3088`
+- `--db` SQLite database path, default `./data/keystream.sqlite`
+
+Environment variables:
+
+- `KEYSTREAM_HOST`
+- `KEYSTREAM_PORT`
+- `KEYSTREAM_DB`
+
+### Client
+
+Command:
+
+```bash
+bun --cwd apps/cli src/index.ts --url ws://127.0.0.1:3088 --username alice --room general --strict-vim
+```
+
+Flags:
+
+- `--url` WebSocket server URL, default `ws://127.0.0.1:3088`
+- `--username` username to claim on connect
+- `--room` initial room name, default `general`
+- `--strict-vim` block arrow keys and record violations
+
+Environment variables:
+
+- `KEYSTREAM_URL`
+- `KEYSTREAM_USERNAME`
+- `KEYSTREAM_ROOM`
+- `KEYSTREAM_STRICT_VIM=1`
+
+Flag precedence is higher than environment variables.
+
+Published npm usage:
+
+```bash
+keystream --url ws://127.0.0.1:3088 --username alice --room general --strict-vim
+```
+
+## How To Use Keystream
+
+### Screen layout
+
+The client screen has four regions:
+
+- left pane: room list
+- main pane: message feed for the current room
+- bottom input pane: mode-specific input area
+- status line: mode, username, room, training stats, and status messages
+
+### Modes
+
+Keystream is modal. Most interaction starts in `NORMAL` mode.
+
+#### `NORMAL`
+
+Use this mode to navigate rooms and messages.
+
+- `i`, `a`, `o`: enter `INSERT` mode
+- `:`: enter `COMMAND` mode
+- `/`: enter `SEARCH` mode
+- `h` and `l`: move between rooms
+- `j` and `k`: move through messages in the current feed
+- `5j`, `10k`, etc.: counted motions
+- `gg`: jump to the top of the current feed
+- `G`: jump to the bottom of the current feed
+- `Ctrl-u`: move up 10 messages
+- `Ctrl-d`: move down 10 messages
+- `Ctrl-c`: quit immediately
+
+#### `INSERT`
+
+Use this mode to compose and send a message.
+
+- type to edit the current message buffer
+- `Backspace`: delete one character
+- `Enter`: send the message to the active room
+- `Esc`: return to `NORMAL`
+
+#### `COMMAND`
+
+Use this mode for room and app commands.
+
+- starts with `:`
+- type a command, then press `Enter`
+- `Esc` cancels command mode
+
+#### `SEARCH`
+
+Use this mode to filter the current room feed.
+
+- starts with `/`
+- type a search term, then press `Enter`
+- search is case-insensitive
+- only the current room feed is filtered
+- empty search clears the filter
+- `Esc` cancels search mode
+
+### Built-in commands
+
+- `:join <room>`: join or create a room and switch to it
+- `:leave`: leave the current room on the server
+- `:rooms`: show known rooms in the status line
+- `:users`: show active occupants in the current room
+- `:history [limit]`: load older messages before the earliest loaded message
+- `:stats`: show mode timing, streak, and arrow-key stats
+- `:help`: print the command list
+- `:commands`: alias for `:help`
+- `:quit`: exit the client
+- `:q`: alias for `:quit`
+
+### Vim training behavior
+
+Keystream is not just a terminal chat client with some Vim keys added. The app is intentionally structured to train habits through repetition.
+
+- Navigation is concentrated in `NORMAL` mode.
+- Writing happens in `INSERT` mode.
+- Commands happen in `COMMAND` mode.
+- Search happens in `SEARCH` mode.
+- The status line tracks clean-motion streaks and arrow-key violations.
+- In strict mode, arrow keys are blocked and replaced with a hint to use `h`, `j`, `k`, `l`.
+
+### Typical workflow
+
+1. Start the server.
+2. Open one or more clients.
+3. Land in `NORMAL` mode.
+4. Press `i` to enter `INSERT` mode and type a message.
+5. Press `Enter` to send it.
+6. Press `Esc` to go back to `NORMAL`.
+7. Use `j`, `k`, `gg`, `G`, and search to move through the feed.
+8. Use `:join dev` to switch into another room.
+9. Use `:stats` to check your mode time and arrow-key violations.
+
+## Development Guide
+
+### Repository layout
+
+```text
+apps/
+  cli/      Terminal client
+  server/   Bun WebSocket server + SQLite persistence
+packages/
+  shared/   Shared protocol, types, and validation
+scripts/
+  dev-stack.ts   Local tmux-based practice launcher
+test/
+  integration/   End-to-end server integration tests
+```
+
+### Main modules
+
+- `packages/shared/src/protocol.ts`: typed wire protocol and runtime validation
+- `apps/server/src/chat-server.ts`: WebSocket lifecycle and room/message coordination
+- `apps/server/src/store.ts`: SQLite schema and persistence logic
+- `apps/cli/src/app.ts`: modal terminal UI and client-side state machine
+- `apps/cli/src/client.ts`: reconnecting WebSocket transport
+- `apps/cli/src/modal-state.ts`: Vim training state and motion logic
+- `apps/cli/src/commands.ts`: command parsing
+
+### Install dependencies
+
+```bash
+bun install
+```
+
+### Run tests
+
+Run all tests:
+
+```bash
+bun test
+```
+
+Run the TypeScript checks:
+
+```bash
+bunx tsc -p packages/shared/tsconfig.json --noEmit
+bunx tsc -p apps/server/tsconfig.json --noEmit
+bunx tsc -p apps/cli/tsconfig.json --noEmit
+```
+
+### Build release artifacts locally
+
+Build the Node-compatible npm CLI bundle:
+
+```bash
+bun run build:cli
+```
+
+Dry-run the npm package tarball:
+
+```bash
+bun run pack:cli --dry-run
+```
+
+Build the backend Docker image:
+
+```bash
+bun run docker:build:server
+```
+
+Run the backend Docker smoke test:
+
+```bash
+bun run docker:smoke:server
+```
+
+### Recommended development loop
+
+1. Start the server in one terminal.
+2. Start one or more clients in separate terminals.
+3. Use `bun test` after behavior changes.
+4. Re-run the TypeScript checks before finishing a change.
+5. Use `bun run dev:stack` when you want rapid multi-user keyboard practice.
+
+### Manual smoke test
+
+Use this after touching the server-client interaction path:
+
+1. Start the server on a local port.
+2. Open two clients with different usernames.
+3. Confirm both receive `welcome` and `room_snapshot` behavior.
+4. Send messages from one client and confirm the other updates live.
+5. Join a new room with `:join`.
+6. Use `/` search and `:history`.
+7. Run `:stats` and confirm Vim training counters update.
+
+### Persistence notes
+
+- The server uses SQLite and creates the database directory automatically.
+- The default database path is `./data/keystream.sqlite`.
+- The local dev stack uses `./data/dev-stack.sqlite`.
+- Message history survives server restarts when you reuse the same database path.
+
+### Networking notes
+
+- The server speaks WebSocket only.
+- The client reconnects automatically if the connection drops.
+- Duplicate active usernames are rejected.
+- Room message ordering is assigned by the server per room using monotonically increasing sequence numbers.
+
+## Scripts
+
+- `bun run build`: workspace build/typecheck script entrypoint
+- `bun run check`: alias for `bun test`
+- `bun run build:cli`: build the public Node-compatible CLI package into `apps/cli/dist`
+- `bun run pack:cli --dry-run`: generate and inspect the npm tarball from `apps/cli/dist`
+- `bun run docker:build:server`: build the local backend container image
+- `bun run docker:smoke:server`: build, run, restart, and verify the Dockerized backend with persisted SQLite data
+- `bun run release:check`: run the release validation path used before tagging
+- `bun run dev:server`: run the server package script
+- `bun run dev:cli`: run the CLI package script
+- `bun run dev:stack`: launch the tmux multi-client practice environment
+
+## Deployment Guide
+
+### Backend container
+
+The Docker image targets the backend only. It does not package the CLI.
+
+- Registry: `ghcr.io/lihaowang/keystream-server`
+- Default internal port: `3088`
+- Default container DB path: `/data/keystream.sqlite`
+- Supported runtime configuration: `KEYSTREAM_HOST`, `KEYSTREAM_PORT`, `KEYSTREAM_DB`
+
+Recommended deployment pattern:
+
+1. Mount a persistent volume to `/data`
+2. Expose port `3088` or reverse-proxy it
+3. Front the service with TLS if it is reachable outside a trusted LAN
+4. Reuse the same mounted database volume across restarts
+
+### GitHub Container Registry release path
+
+The backend image is published by GitHub Actions on version tags:
+
+- workflow: `.github/workflows/release-server-image.yml`
+- trigger: `v*` tags
+- image tags:
+  - `ghcr.io/lihaowang/keystream-server:<tag>`
+  - `ghcr.io/lihaowang/keystream-server:latest`
+
+### npm CLI release path
+
+The CLI release path is manual for final publish, but validated in CI:
+
+1. Build the CLI package with `bun run build:cli`
+2. Validate the package with `bun run pack:cli --dry-run`
+3. Log in to npm with `npm login`
+4. Publish from `apps/cli/dist` with:
+
+```bash
+npm publish ./apps/cli/dist --access public
+```
+
+See [docs/releasing.md](/Users/leowang1/Documents/keystream/docs/releasing.md) for the maintainer flow.
+
+## Known Limitations
+
+- `:leave` acknowledges on the server but the UI does not implement a separate “roomless” screen state.
+- Presence updates are modeled in the protocol but not yet rendered as live status changes in the UI.
+- The README examples use direct Bun entrypoints because they are the most explicit and reliable during development.
+- Public internet deployment should be fronted by TLS and stronger access control if you plan to expose it beyond a trusted environment.
+
+## Future Improvements
+
+- Direct messages
+- Better presence rendering
+- Message editing and reactions
+- Room privacy and invitations
+- Richer training metrics and drills
+- PTY-level end-to-end tests for the full terminal UI

package/keystream.js

@@ -0,0 +1,881 @@
+#!/usr/bin/env node
+
+// apps/cli/src/app.ts
+import blessed from "blessed";
+
+// apps/cli/src/commands.ts
+function parseCommand(input) {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith(":")) {
+    return null;
+  }
+  const tokens = trimmed.slice(1).trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return null;
+  }
+  return {
+    name: tokens[0].toLowerCase(),
+    args: tokens.slice(1)
+  };
+}
+
+// apps/cli/src/modal-state.ts
+var arrowKeys = new Set(["up", "down", "left", "right"]);
+function transitionMode(currentMode, key) {
+  if (currentMode === "INSERT" && key === "escape") {
+    return "NORMAL";
+  }
+  if (currentMode === "NORMAL") {
+    if (key === "i" || key === "a" || key === "o") {
+      return "INSERT";
+    }
+    if (key === ":") {
+      return "COMMAND";
+    }
+    if (key === "/") {
+      return "SEARCH";
+    }
+  }
+  if ((currentMode === "COMMAND" || currentMode === "SEARCH") && key === "escape") {
+    return "NORMAL";
+  }
+  return currentMode;
+}
+function createTrainingStats(overrides = {}) {
+  return {
+    strictVim: false,
+    pendingCount: "",
+    pendingOperator: null,
+    arrowViolations: 0,
+    cleanMotionStreak: 0,
+    lastMotion: null,
+    lastHint: null,
+    ...overrides
+  };
+}
+function handleNormalModeKey(state, key) {
+  if (arrowKeys.has(key)) {
+    return {
+      ...state,
+      arrowViolations: state.strictVim ? state.arrowViolations + 1 : state.arrowViolations,
+      lastHint: state.strictVim ? "Use h j k l instead of arrow keys." : null
+    };
+  }
+  if (/^[1-9]$/.test(key) || state.pendingCount !== "" && /^[0-9]$/.test(key)) {
+    return {
+      ...state,
+      pendingCount: `${state.pendingCount}${key}`,
+      lastHint: null
+    };
+  }
+  if (key === "g") {
+    if (state.pendingOperator === "g") {
+      return finalizeMotion(state, "gg");
+    }
+    return {
+      ...state,
+      pendingOperator: "g",
+      lastHint: null
+    };
+  }
+  if (["j", "k", "h", "l", "G"].includes(key)) {
+    return finalizeMotion(state, key);
+  }
+  return {
+    ...state,
+    pendingCount: "",
+    pendingOperator: null,
+    lastHint: null
+  };
+}
+function finalizeMotion(state, key) {
+  const count = state.pendingCount === "" ? 1 : Number(state.pendingCount);
+  return {
+    ...state,
+    pendingCount: "",
+    pendingOperator: null,
+    cleanMotionStreak: state.cleanMotionStreak + 1,
+    lastMotion: {
+      key,
+      count
+    },
+    lastHint: null
+  };
+}
+
+// packages/shared/src/protocol.ts
+import { z } from "zod";
+var isoDateString = z.string().datetime({ offset: true });
+var clientPayloadSchemas = {
+  connect: z.object({
+    username: z.string().min(1),
+    room: z.string().min(1),
+    sessionId: z.string().min(1).nullable()
+  }),
+  join_room: z.object({
+    room: z.string().min(1)
+  }),
+  leave_room: z.object({
+    roomId: z.string().min(1)
+  }),
+  send_message: z.object({
+    roomId: z.string().min(1),
+    body: z.string().min(1)
+  }),
+  load_history: z.object({
+    roomId: z.string().min(1),
+    beforeSeq: z.number().int().positive().nullable(),
+    limit: z.number().int().positive().max(100).default(50)
+  }),
+  set_presence: z.object({
+    state: z.enum(["active", "idle"])
+  }),
+  ping: z.object({
+    at: isoDateString
+  })
+};
+var messageSchema = z.object({
+  id: z.string().min(1),
+  roomId: z.string().min(1),
+  sender: z.string().min(1),
+  body: z.string().min(1),
+  seq: z.number().int().positive(),
+  createdAt: isoDateString
+});
+var roomSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  topic: z.string().default(""),
+  isPrivate: z.boolean().default(false)
+});
+var presenceSchema = z.object({
+  username: z.string().min(1),
+  state: z.enum(["active", "idle", "offline"]),
+  lastSeenAt: isoDateString
+});
+var serverPayloadSchemas = {
+  welcome: z.object({
+    username: z.string().min(1),
+    rooms: z.array(roomSchema),
+    joinedRoomId: z.string().min(1),
+    sessionId: z.string().min(1)
+  }),
+  room_snapshot: z.object({
+    room: roomSchema,
+    occupants: z.array(z.string().min(1)),
+    messages: z.array(messageSchema),
+    unreadCount: z.number().int().nonnegative()
+  }),
+  message_created: messageSchema,
+  presence_changed: presenceSchema,
+  history_page: z.object({
+    roomId: z.string().min(1),
+    messages: z.array(messageSchema),
+    hasMore: z.boolean(),
+    nextBeforeSeq: z.number().int().positive().nullable()
+  }),
+  ack: z.object({
+    action: z.string().min(1),
+    ok: z.literal(true)
+  }),
+  error: z.object({
+    action: z.string().min(1),
+    message: z.string().min(1)
+  })
+};
+var clientEventTypes = Object.keys(clientPayloadSchemas);
+var serverEventTypes = Object.keys(serverPayloadSchemas);
+function createProtocolEnvelope(direction, type, payload) {
+  return {
+    direction,
+    type,
+    payload
+  };
+}
+function makeClientEvent(type, payload) {
+  return createProtocolEnvelope("client", type, payload);
+}
+function makeServerEvent(type, payload) {
+  return createProtocolEnvelope("server", type, payload);
+}
+function parseProtocolEnvelope(input) {
+  const baseEnvelope = z.object({
+    direction: z.enum(["client", "server"]),
+    type: z.string().min(1),
+    payload: z.unknown()
+  }).parse(input);
+  if (baseEnvelope.direction === "client") {
+    const schema2 = clientPayloadSchemas[baseEnvelope.type];
+    if (!schema2) {
+      throw new Error(`Unsupported client event type: ${baseEnvelope.type}`);
+    }
+    return makeClientEvent(baseEnvelope.type, schema2.parse(baseEnvelope.payload));
+  }
+  const schema = serverPayloadSchemas[baseEnvelope.type];
+  if (!schema) {
+    throw new Error(`Unsupported server event type: ${baseEnvelope.type}`);
+  }
+  return makeServerEvent(baseEnvelope.type, schema.parse(baseEnvelope.payload));
+}
+// apps/cli/src/client.ts
+class ChatTransport {
+  options;
+  ws = null;
+  closedByClient = false;
+  reconnectTimer = null;
+  sessionId;
+  constructor(options) {
+    this.options = options;
+    this.sessionId = options.sessionId;
+  }
+  connect() {
+    this.closedByClient = false;
+    this.openSocket();
+  }
+  updateRoom(room) {
+    this.options.room = room;
+  }
+  updateSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+  send(type, payload) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.options.onStatus("Socket is not connected yet.");
+      return;
+    }
+    this.ws.send(JSON.stringify(makeClientEvent(type, payload)));
+  }
+  close() {
+    this.closedByClient = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+  }
+  openSocket() {
+    this.options.onStatus(`Connecting to ${this.options.url}...`);
+    const ws = new WebSocket(this.options.url);
+    this.ws = ws;
+    ws.addEventListener("open", () => {
+      this.options.onStatus(`Connected as ${this.options.username}`);
+      this.send("connect", {
+        username: this.options.username,
+        room: this.options.room,
+        sessionId: this.sessionId
+      });
+    });
+    ws.addEventListener("message", (event) => {
+      const parsed = parseProtocolEnvelope(JSON.parse(String(event.data)));
+      this.options.onEvent(parsed);
+    });
+    ws.addEventListener("close", () => {
+      if (this.closedByClient) {
+        return;
+      }
+      this.options.onStatus("Disconnected. Reconnecting in 1.5s...");
+      this.reconnectTimer = setTimeout(() => this.openSocket(), 1500);
+    });
+    ws.addEventListener("error", () => {
+      this.options.onStatus("Socket error.");
+    });
+  }
+}
+
+// apps/cli/src/app.ts
+function startCliApp(options) {
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: "Keystream",
+    fullUnicode: true
+  });
+  const roomsBox = blessed.box({
+    parent: screen,
+    top: 0,
+    left: 0,
+    width: "24%",
+    height: "100%-4",
+    border: "line",
+    label: " Rooms ",
+    tags: false
+  });
+  const messagesBox = blessed.box({
+    parent: screen,
+    top: 0,
+    left: "24%",
+    width: "76%",
+    height: "100%-4",
+    border: "line",
+    label: " Feed ",
+    tags: false,
+    scrollable: true,
+    alwaysScroll: true
+  });
+  const inputBox = blessed.box({
+    parent: screen,
+    bottom: 1,
+    left: 0,
+    width: "100%",
+    height: 3,
+    border: "line",
+    label: " Input ",
+    tags: false
+  });
+  const statusBox = blessed.box({
+    parent: screen,
+    bottom: 0,
+    left: 0,
+    width: "100%",
+    height: 1,
+    tags: false
+  });
+  let state = {
+    mode: "NORMAL",
+    rooms: [],
+    currentRoomId: null,
+    messagesByRoom: new Map,
+    occupantsByRoom: new Map,
+    unreadByRoom: new Map,
+    selectedMessageIndex: 0,
+    composeBuffer: "",
+    commandBuffer: "",
+    searchBuffer: "",
+    searchTerm: "",
+    status: "Starting Keystream...",
+    sessionId: null,
+    training: createTrainingStats({ strictVim: options.strictVim }),
+    modeDurations: {
+      NORMAL: 0,
+      INSERT: 0,
+      COMMAND: 0,
+      SEARCH: 0
+    },
+    modeStartedAt: Date.now()
+  };
+  const transport = new ChatTransport({
+    url: options.url,
+    username: options.username,
+    room: options.room,
+    sessionId: state.sessionId,
+    onEvent: (event) => {
+      state = reduceEvent(state, event);
+      if (event.type === "welcome") {
+        transport.updateSessionId(event.payload.sessionId);
+      }
+      render();
+    },
+    onStatus: (message) => {
+      state = {
+        ...state,
+        status: message
+      };
+      render();
+    }
+  });
+  const setMode = (nextMode) => {
+    if (nextMode === state.mode) {
+      return;
+    }
+    const now = Date.now();
+    const elapsed = now - state.modeStartedAt;
+    state = {
+      ...state,
+      mode: nextMode,
+      modeStartedAt: now,
+      modeDurations: {
+        ...state.modeDurations,
+        [state.mode]: state.modeDurations[state.mode] + elapsed
+      }
+    };
+  };
+  const render = () => {
+    const roomLines = state.rooms.map((room) => {
+      const currentMarker = room.id === state.currentRoomId ? ">" : " ";
+      const unread = state.unreadByRoom.get(room.id) ?? 0;
+      const unreadLabel = unread > 0 ? ` (${unread})` : "";
+      return `${currentMarker} ${room.name}${unreadLabel}`;
+    });
+    const visibleMessages = applySearch(getCurrentMessages(state), state.searchTerm);
+    const selected = clamp(state.selectedMessageIndex, 0, Math.max(visibleMessages.length - 1, 0));
+    state.selectedMessageIndex = selected;
+    const messageLines = visibleMessages.map((message, index) => {
+      const marker = index === selected ? ">" : " ";
+      return `${marker} [${String(message.seq).padStart(3, " ")}] ${message.sender}: ${message.body}`;
+    });
+    roomsBox.setContent(roomLines.join(`
+`) || "No rooms");
+    messagesBox.setLabel(` Feed ${state.searchTerm ? `(search: ${state.searchTerm})` : ""} `);
+    messagesBox.setContent(messageLines.join(`
+`) || "No messages yet");
+    messagesBox.setScrollPerc(100);
+    inputBox.setLabel(` ${state.mode} `);
+    inputBox.setContent(currentInputValue(state));
+    statusBox.setContent(buildStatusLine(state, options.username));
+    screen.render();
+  };
+  screen.on("keypress", (ch, key) => {
+    const rawKey = normalizeKey(ch, key);
+    if (rawKey === "C-c") {
+      shutdown();
+      return;
+    }
+    if (state.mode === "NORMAL") {
+      if (handleNormalBindings(rawKey)) {
+        render();
+      }
+      return;
+    }
+    if (state.mode === "INSERT") {
+      handleInsertMode(rawKey, ch);
+      render();
+      return;
+    }
+    if (state.mode === "COMMAND") {
+      handleCommandMode(rawKey, ch);
+      render();
+      return;
+    }
+    handleSearchMode(rawKey, ch);
+    render();
+  });
+  transport.connect();
+  render();
+  function handleNormalBindings(rawKey) {
+    const nextMode = transitionMode(state.mode, rawKey);
+    if (nextMode !== state.mode) {
+      if (nextMode === "COMMAND") {
+        state.commandBuffer = ":";
+      }
+      if (nextMode === "SEARCH") {
+        state.searchBuffer = "/";
+      }
+      setMode(nextMode);
+      return true;
+    }
+    const previousTraining = state.training;
+    state = {
+      ...state,
+      training: handleNormalModeKey(state.training, rawKey)
+    };
+    if (state.training.lastHint) {
+      state.status = state.training.lastHint;
+    }
+    if (state.training.lastMotion !== previousTraining.lastMotion && state.training.lastMotion) {
+      applyMotion(state.training.lastMotion.key, state.training.lastMotion.count);
+      return true;
+    }
+    if (rawKey === "C-u") {
+      moveSelection(-10);
+      return true;
+    }
+    if (rawKey === "C-d") {
+      moveSelection(10);
+      return true;
+    }
+    if (!state.training.strictVim && arrowToMotion(rawKey)) {
+      applyMotion(arrowToMotion(rawKey), 1);
+      return true;
+    }
+    return true;
+  }
+  function handleInsertMode(rawKey, ch) {
+    if (rawKey === "escape") {
+      setMode("NORMAL");
+      state.status = "Returned to NORMAL mode";
+      return;
+    }
+    if (rawKey === "backspace") {
+      state.composeBuffer = state.composeBuffer.slice(0, -1);
+      return;
+    }
+    if (rawKey === "enter") {
+      const roomId = state.currentRoomId;
+      const message = state.composeBuffer.trim();
+      if (!roomId || !message) {
+        state.status = "Nothing to send";
+        return;
+      }
+      transport.send("send_message", {
+        roomId,
+        body: message
+      });
+      state.composeBuffer = "";
+      state.status = "Message sent";
+      return;
+    }
+    if (isPrintable(ch)) {
+      state.composeBuffer += ch;
+    }
+  }
+  function handleCommandMode(rawKey, ch) {
+    if (rawKey === "escape") {
+      state.commandBuffer = "";
+      setMode("NORMAL");
+      state.status = "Command canceled";
+      return;
+    }
+    if (rawKey === "backspace") {
+      state.commandBuffer = state.commandBuffer.slice(0, -1);
+      return;
+    }
+    if (rawKey === "enter") {
+      executeCommand(state.commandBuffer);
+      state.commandBuffer = "";
+      setMode("NORMAL");
+      return;
+    }
+    if (isPrintable(ch)) {
+      state.commandBuffer += ch;
+    }
+  }
+  function handleSearchMode(rawKey, ch) {
+    if (rawKey === "escape") {
+      state.searchBuffer = "";
+      setMode("NORMAL");
+      state.status = "Search canceled";
+      return;
+    }
+    if (rawKey === "backspace") {
+      state.searchBuffer = state.searchBuffer.slice(0, -1);
+      return;
+    }
+    if (rawKey === "enter") {
+      state.searchTerm = state.searchBuffer.slice(1).trim().toLowerCase();
+      state.searchBuffer = "";
+      setMode("NORMAL");
+      const firstMatch = applySearch(getCurrentMessages(state), state.searchTerm).findIndex(() => true);
+      state.selectedMessageIndex = firstMatch >= 0 ? firstMatch : 0;
+      state.status = state.searchTerm ? `Search applied for "${state.searchTerm}"` : "Search cleared";
+      return;
+    }
+    if (isPrintable(ch)) {
+      state.searchBuffer += ch;
+    }
+  }
+  function executeCommand(input) {
+    const parsed = parseCommand(input);
+    if (!parsed) {
+      state.status = "Not a command";
+      return;
+    }
+    switch (parsed.name) {
+      case "join": {
+        const roomName = parsed.args[0];
+        if (!roomName) {
+          state.status = "Usage: :join <room>";
+          return;
+        }
+        transport.updateRoom(roomName);
+        transport.send("join_room", { room: roomName });
+        state.status = `Joining ${roomName}...`;
+        return;
+      }
+      case "leave":
+        if (!state.currentRoomId) {
+          state.status = "No active room";
+          return;
+        }
+        transport.send("leave_room", { roomId: state.currentRoomId });
+        state.status = "Left current room";
+        return;
+      case "rooms":
+        state.status = state.rooms.map((room) => room.name).join(", ") || "No rooms";
+        return;
+      case "users":
+        state.status = (state.currentRoomId ? state.occupantsByRoom.get(state.currentRoomId)?.join(", ") : "") || "No active occupants";
+        return;
+      case "history": {
+        if (!state.currentRoomId) {
+          state.status = "No active room";
+          return;
+        }
+        const currentMessages = getCurrentMessages(state);
+        const earliestSeq = currentMessages[0]?.seq ?? null;
+        const limit = Number(parsed.args[0] ?? "20");
+        transport.send("load_history", {
+          roomId: state.currentRoomId,
+          beforeSeq: earliestSeq,
+          limit: Number.isFinite(limit) && limit > 0 ? limit : 20
+        });
+        state.status = "Loading older messages...";
+        return;
+      }
+      case "stats":
+        state.status = formatStats(state);
+        return;
+      case "help":
+      case "commands":
+        state.status = ":join :leave :rooms :users :history :stats :help :quit";
+        return;
+      case "quit":
+      case "q":
+        shutdown();
+        return;
+      default:
+        state.status = `Unknown command: ${parsed.name}`;
+    }
+  }
+  function applyMotion(key, count) {
+    switch (key) {
+      case "j":
+        moveSelection(count);
+        return;
+      case "k":
+        moveSelection(-count);
+        return;
+      case "h":
+        moveRoom(-count);
+        return;
+      case "l":
+        moveRoom(count);
+        return;
+      case "gg":
+        state.selectedMessageIndex = 0;
+        state.status = "Top of feed";
+        return;
+      case "G":
+        state.selectedMessageIndex = Math.max(applySearch(getCurrentMessages(state), state.searchTerm).length - 1, 0);
+        state.status = "Bottom of feed";
+        return;
+      default:
+        return;
+    }
+  }
+  function moveSelection(delta) {
+    const visibleMessages = applySearch(getCurrentMessages(state), state.searchTerm);
+    const nextIndex = clamp(state.selectedMessageIndex + delta, 0, Math.max(visibleMessages.length - 1, 0));
+    state.selectedMessageIndex = nextIndex;
+    state.status = `Selected message ${nextIndex + 1}/${Math.max(visibleMessages.length, 1)}`;
+  }
+  function moveRoom(delta) {
+    if (state.rooms.length === 0) {
+      return;
+    }
+    const currentIndex = state.rooms.findIndex((room) => room.id === state.currentRoomId);
+    const safeCurrent = currentIndex >= 0 ? currentIndex : 0;
+    const nextIndex = clamp(safeCurrent + delta, 0, state.rooms.length - 1);
+    const nextRoom = state.rooms[nextIndex];
+    if (!nextRoom) {
+      return;
+    }
+    transport.updateRoom(nextRoom.name);
+    transport.send("join_room", { room: nextRoom.name });
+    state.status = `Switching to #${nextRoom.name}`;
+  }
+  function shutdown() {
+    transport.close();
+    screen.destroy();
+    process.exit(0);
+  }
+}
+function reduceEvent(state, event) {
+  if (event.direction !== "server") {
+    return state;
+  }
+  switch (event.type) {
+    case "welcome": {
+      const unreadByRoom = new Map(state.unreadByRoom);
+      const rooms = upsertRooms(state.rooms, event.payload.rooms);
+      event.payload.rooms.forEach((room) => unreadByRoom.set(room.id, unreadByRoom.get(room.id) ?? 0));
+      return {
+        ...state,
+        rooms,
+        currentRoomId: event.payload.joinedRoomId,
+        sessionId: event.payload.sessionId,
+        status: `Connected to ${roomNameForId(rooms, event.payload.joinedRoomId)}`
+      };
+    }
+    case "room_snapshot": {
+      const rooms = upsertRooms(state.rooms, [event.payload.room]);
+      const messagesByRoom = new Map(state.messagesByRoom);
+      const occupantsByRoom = new Map(state.occupantsByRoom);
+      const unreadByRoom = new Map(state.unreadByRoom);
+      messagesByRoom.set(event.payload.room.id, event.payload.messages);
+      occupantsByRoom.set(event.payload.room.id, event.payload.occupants);
+      unreadByRoom.set(event.payload.room.id, 0);
+      return {
+        ...state,
+        rooms,
+        currentRoomId: event.payload.room.id,
+        messagesByRoom,
+        occupantsByRoom,
+        unreadByRoom,
+        selectedMessageIndex: Math.max(event.payload.messages.length - 1, 0),
+        status: `Loaded #${event.payload.room.name}`
+      };
+    }
+    case "message_created": {
+      const messagesByRoom = new Map(state.messagesByRoom);
+      const existing = messagesByRoom.get(event.payload.roomId) ?? [];
+      if (!existing.some((message) => message.id === event.payload.id)) {
+        messagesByRoom.set(event.payload.roomId, [...existing, event.payload]);
+      }
+      const unreadByRoom = new Map(state.unreadByRoom);
+      if (event.payload.roomId !== state.currentRoomId) {
+        unreadByRoom.set(event.payload.roomId, (unreadByRoom.get(event.payload.roomId) ?? 0) + 1);
+      }
+      return {
+        ...state,
+        messagesByRoom,
+        unreadByRoom,
+        selectedMessageIndex: event.payload.roomId === state.currentRoomId ? Math.max((messagesByRoom.get(event.payload.roomId) ?? []).length - 1, 0) : state.selectedMessageIndex,
+        status: `New message from ${event.payload.sender}`
+      };
+    }
+    case "history_page": {
+      const messagesByRoom = new Map(state.messagesByRoom);
+      const current = messagesByRoom.get(event.payload.roomId) ?? [];
+      const merged = dedupeMessages([...event.payload.messages, ...current]);
+      messagesByRoom.set(event.payload.roomId, merged);
+      return {
+        ...state,
+        messagesByRoom,
+        status: event.payload.hasMore ? "Loaded older history" : "Reached start of history"
+      };
+    }
+    case "ack":
+      return {
+        ...state,
+        status: `${event.payload.action} ok`
+      };
+    case "error":
+      return {
+        ...state,
+        status: `Error: ${event.payload.message}`
+      };
+    case "presence_changed":
+      return state;
+  }
+}
+function buildStatusLine(state, username) {
+  const currentRoomName = state.currentRoomId ? roomNameForId(state.rooms, state.currentRoomId) : "none";
+  return `${state.mode} | ${username} | room:${currentRoomName} | streak:${state.training.cleanMotionStreak} | arrows:${state.training.arrowViolations} | ${state.status}`;
+}
+function currentInputValue(state) {
+  switch (state.mode) {
+    case "INSERT":
+      return state.composeBuffer || "Compose a message...";
+    case "COMMAND":
+      return state.commandBuffer || ":";
+    case "SEARCH":
+      return state.searchBuffer || "/";
+    default:
+      return "NORMAL mode: i insert, : command, / search, h/j/k/l move";
+  }
+}
+function normalizeKey(ch, key) {
+  if (key.full) {
+    return key.full;
+  }
+  if (key.ctrl && key.name) {
+    return `C-${key.name}`;
+  }
+  return key.name ?? ch;
+}
+function isPrintable(ch) {
+  return Boolean(ch && ch >= " " && ch !== "");
+}
+function getCurrentMessages(state) {
+  return state.currentRoomId ? state.messagesByRoom.get(state.currentRoomId) ?? [] : [];
+}
+function dedupeMessages(messages) {
+  return [...new Map(messages.map((message) => [message.id, message])).values()].sort((left, right) => left.seq - right.seq);
+}
+function applySearch(messages, searchTerm) {
+  if (!searchTerm) {
+    return messages;
+  }
+  return messages.filter((message) => `${message.sender} ${message.body}`.toLowerCase().includes(searchTerm));
+}
+function upsertRooms(existing, incoming) {
+  const merged = new Map(existing.map((room) => [room.id, room]));
+  incoming.forEach((room) => merged.set(room.id, room));
+  return [...merged.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+function roomNameForId(rooms, roomId) {
+  return rooms.find((room) => room.id === roomId)?.name ?? roomId;
+}
+function formatStats(state) {
+  const now = Date.now();
+  const liveDurations = {
+    ...state.modeDurations,
+    [state.mode]: state.modeDurations[state.mode] + (now - state.modeStartedAt)
+  };
+  const formatMs = (value) => `${Math.round(value / 1000)}s`;
+  return `normal:${formatMs(liveDurations.NORMAL)} insert:${formatMs(liveDurations.INSERT)} command:${formatMs(liveDurations.COMMAND)} search:${formatMs(liveDurations.SEARCH)} streak:${state.training.cleanMotionStreak} arrows:${state.training.arrowViolations}`;
+}
+function arrowToMotion(key) {
+  switch (key) {
+    case "up":
+      return "k";
+    case "down":
+      return "j";
+    case "left":
+      return "h";
+    case "right":
+      return "l";
+    default:
+      return null;
+  }
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+// apps/cli/src/args.ts
+function parseCliArgs(argv, env = process.env, randomSuffix = () => Math.floor(Math.random() * 1000)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    return { command: "help" };
+  }
+  if (argv.includes("--version")) {
+    return { command: "version" };
+  }
+  const url = readFlag(argv, "--url") ?? env.KEYSTREAM_URL ?? "ws://127.0.0.1:3088";
+  const username = readFlag(argv, "--username") ?? env.KEYSTREAM_USERNAME ?? `guest-${randomSuffix()}`;
+  const room = readFlag(argv, "--room") ?? env.KEYSTREAM_ROOM ?? "general";
+  const strictVim = argv.includes("--strict-vim") || env.KEYSTREAM_STRICT_VIM === "1";
+  return {
+    command: "run",
+    url,
+    username,
+    room,
+    strictVim
+  };
+}
+function formatCliHelp() {
+  return [
+    "keystream - real-time terminal chat with Vim-style navigation",
+    "",
+    "Usage:",
+    "  keystream [--url ws://host:port] [--username name] [--room room] [--strict-vim]",
+    "  keystream --help",
+    "  keystream --version",
+    "",
+    "Options:",
+    "  --url         WebSocket server URL",
+    "  --username    Username to claim on connect",
+    "  --room        Initial room name",
+    "  --strict-vim  Block arrow keys and track violations",
+    "  -h, --help    Show this help",
+    "  --version     Show package version"
+  ].join(`
+`);
+}
+function readFlag(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+// apps/cli/src/bin.ts
+var options = parseCliArgs(process.argv.slice(2));
+if (options.command === "help") {
+  console.log(formatCliHelp());
+  process.exit(0);
+}
+if (options.command === "version") {
+  console.log("0.0.1");
+  process.exit(0);
+}
+if (options.command === "run") {
+  startCliApp(options);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "keystream-cli",
+  "version": "0.0.1",
+  "description": "Real-time terminal chat with Vim-style navigation training.",
+  "type": "module",
+  "main": "./keystream.js",
+  "bin": {
+    "keystream": "./keystream.js"
+  },
+  "files": [
+    "keystream.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "chat",
+    "cli",
+    "terminal",
+    "vim",
+    "websocket"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LihaoWang/keystream.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "pino": "^9.9.0",
+    "zod": "^4.1.8"
+  }
+}