kokoirc 0.2.3 → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kofany
+
+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

@@ -2,23 +2,20 @@
 
 A modern terminal IRC client built with [OpenTUI](https://github.com/anomalyco/opentui), React, and Bun. Inspired by irssi, designed for the future.
 
-```
-┌─ Buffers ─┬─────────────────────────────────────────┬─ Users ──┐
-│ IRCnet    │ 12:34:05 <kofany> hey everyone           │ @kofany  │
-│  #chat    │ 12:34:08 <alice> welcome back!           │ +alice   │
-│  #dev     │ 12:34:12  * kofany waves                 │  bob     │
-│  #music   │ 12:34:15 <bob> what's new?               │  charlie │
-│           │                                          │          │
-│           ├──────────────────────────────────────────┤          │
-│           │ [IRCnet❱ /msg alice check this out       │          │
-│           ├──────────────────────────────────────────┤          │
-│           │ 12:34 | kofany(+i) | #chat(+nt) | lag:2 │          │
-└───────────┴──────────────────────────────────────────┴──────────┘
-```
+**[Documentation](https://kofany.github.io/kokoIRC/)** | **[GitHub](https://github.com/kofany/kokoIRC)**
+
+![Splash screen](docs/screenshots/splash.png)
+
+![Chat view with multiple networks](docs/screenshots/chat.png)
+
+![Help command list](docs/screenshots/help.png)
+
+![Configuration and settings](docs/screenshots/config.png)
 
 ## Features
 
 - **Full IRC protocol** — channels, queries, CTCP, SASL, TLS, channel modes, ban lists
+- **Inline image preview** — kitty, iTerm2, sixel, and Unicode fallback with tmux support
 - **irssi-style navigation** — `Esc+1-9` window switching, `/commands`, aliases
 - **Mouse support** — click buffers/nicks, drag to resize sidepanels
 - **Netsplit detection** — batches join/part floods into single events
@@ -35,21 +32,35 @@ A modern terminal IRC client built with [OpenTUI](https://github.com/anomalyco/o
 
 ## Install
 
+### From npm
+
 ```bash
-git clone https://github.com/kofany/kokoIRC.git
-cd kokoIRC
-bun install
+# Global install (adds `kokoirc` to your PATH)
+bun install -g kokoirc
+
+# Then run from anywhere
+kokoirc
 ```
 
-## Usage
+```bash
+# Local install (in a project)
+bun add kokoirc
+bunx kokoirc
+```
+
+### From source
 
 ```bash
+git clone https://github.com/kofany/kokoIRC.git
+cd kokoIRC
+bun install
+
 # Run directly
-bun run src/index.tsx
+bun run start
 
 # Or build a standalone binary
 bun run build
-./openirc
+./kokoirc
 ```
 
 ## Configuration
@@ -79,6 +90,12 @@ autosendcmd = "MSG NickServ identify pass; WAIT 2000; MODE $N +i"
 # sasl_user = "mynick"
 # sasl_pass = "hunter2"
 
+[image_preview]
+enabled = true
+max_width = 800
+max_height = 400
+protocol = "auto"     # "auto", "kitty", "iterm2", "sixel", "unicode"
+
 [logging]
 enabled = true
 encrypt = false       # AES-256-GCM (key auto-generated in ~/.kokoirc/.env)
@@ -92,17 +109,18 @@ j = "/join"
 
 ## Commands
 
-38 built-in commands. Type `/help` for the full list, `/help <command>` for details.
+44 built-in commands. Type `/help` for the full list, `/help <command>` for details.
 
 | Category | Commands |
 |----------|----------|
 | Connection | `/connect`, `/disconnect`, `/quit`, `/server` |
-| Channel | `/join`, `/part`, `/close`, `/topic`, `/list` |
+| Channel | `/join`, `/part`, `/close`, `/clear`, `/topic`, `/names`, `/invite`, `/list` |
 | Messaging | `/msg`, `/me`, `/notice`, `/action`, `/slap`, `/wallops` |
 | Moderation | `/kick`, `/ban`, `/unban`, `/kb`, `/kill`, `/mode` |
 | Nick/Ops | `/nick`, `/op`, `/deop`, `/voice`, `/devoice` |
+| Media | `/image`, `/preview` |
 | User | `/whois`, `/wii`, `/ignore`, `/unignore` |
-| Info | `/stats` |
+| Info | `/version`, `/stats` |
 | Server | `/quote` (`/raw`), `/oper` |
 | Config | `/set`, `/alias`, `/unalias`, `/reload` |
 | Logging | `/log status`, `/log search <query>` |
@@ -194,25 +212,32 @@ Messages are stored in `~/.kokoirc/logs.db` (SQLite WAL mode). The log system su
 
 ```
 src/
-├── index.tsx              # Entry point — creates OpenTUI renderer
+├── index.tsx                # Entry point — creates OpenTUI renderer
 ├── app/
-│   └── App.tsx            # Lifecycle: config → storage → theme → connect
+│   └── App.tsx              # Lifecycle: config → storage → theme → connect
 ├── core/
-│   ├── irc/               # IRC client, event binding, middlewares
-│   ├── state/             # Zustand store (UI-agnostic)
-│   ├── commands/          # Command registry and parser
-│   ├── config/            # TOML loader, defaults, merge logic
-│   ├── storage/           # SQLite logging, encryption, queries
-│   ├── scripts/           # Script loader, API, event bus
-│   └── theme/             # Format string parser, theme loader
-├── ui/                    # React components (no IRC imports)
-│   ├── AppLayout.tsx      # 3-column layout with resizable panels
-│   ├── ChatView.tsx       # Message scrollback
-│   ├── BufferList.tsx     # Left sidebar
-│   ├── NickList.tsx       # Right sidebar
-│   ├── CommandInput.tsx   # Input line with prompt
-│   └── StatusLine.tsx     # Status bar
-└── types/                 # TypeScript definitions
+│   ├── init.ts              # Application initialization
+│   ├── constants.ts         # Global constants
+│   ├── irc/                 # IRC client, event binding, middlewares
+│   ├── state/               # Zustand store (UI-agnostic)
+│   ├── commands/            # Command registry, parser, help system
+│   ├── config/              # TOML loader, defaults, merge logic
+│   ├── storage/             # SQLite logging, encryption, queries
+│   ├── scripts/             # Script loader, API, event bus
+│   ├── theme/               # Format string parser, theme loader
+│   ├── image-preview/       # Inline image display (kitty, iTerm2, sixel)
+│   └── utils/               # Message ID generator
+├── ui/                      # React components (no IRC imports)
+│   ├── layout/              # AppLayout, TopicBar
+│   ├── chat/                # ChatView, MessageLine
+│   ├── input/               # CommandInput
+│   ├── sidebar/             # BufferList, NickList
+│   ├── statusbar/           # StatusLine
+│   ├── overlay/             # ImagePreview
+│   ├── splash/              # SplashScreen
+│   ├── hooks/               # useStatusbarColors
+│   └── ErrorBoundary.tsx    # React error boundary
+└── types/                   # TypeScript definitions
 ```
 
 The UI layer never imports from `core/irc/` — all communication goes through the Zustand store. This keeps the architecture clean and makes it possible to drive the same store from a web frontend.

package/docs/commands/clear.md

@@ -0,0 +1,26 @@
+---
+category: Channel
+description: Clear current buffer's messages
+---
+
+# /clear
+
+## Syntax
+
+    /clear
+
+## Description
+
+Clears all messages from the current buffer's display. This is a visual-only
+operation — chat logs in the database are not affected. Messages remain
+searchable via `/log search`.
+
+Works on any buffer type: channels, queries, and server buffers.
+
+## Examples
+
+    /clear
+
+## See Also
+
+/close, /log

package/docs/commands/image.md

@@ -0,0 +1,47 @@
+---
+category: Media
+description: Manage image preview cache
+---
+
+# /image
+
+## Syntax
+
+    /image [stats|clear]
+
+## Description
+
+Manage the image preview cache. Without arguments, shows current status.
+
+All image preview settings are persistent via `/set`:
+
+    /set image_preview.enabled true|false
+    /set image_preview.protocol auto|kitty|iterm2|sixel|symbols
+    /set image_preview.max_width 0
+    /set image_preview.cache_max_mb 100
+
+## Subcommands
+
+### stats
+
+Show cache file count and disk usage.
+
+    /image stats
+
+### clear
+
+Delete all cached images.
+
+    /image clear
+
+## Examples
+
+    /image
+    /image stats
+    /image clear
+    /set image_preview.enabled false
+    /set image_preview.protocol kitty
+
+## See Also
+
+/preview, /set

package/docs/commands/invite.md

@@ -0,0 +1,23 @@
+---
+category: Channel
+description: Invite a user to a channel
+---
+
+# /invite
+
+## Syntax
+
+    /invite <nick> [channel]
+
+## Description
+
+Invite a user to join a channel. Without a channel argument, invites to the current channel. You typically need channel operator status to send invites.
+
+## Examples
+
+    /invite friend              # invite to current channel
+    /invite friend #secret      # invite to #secret
+
+## See Also
+
+/kick, /ban

package/docs/commands/names.md

@@ -0,0 +1,25 @@
+---
+category: Channel
+description: List users in a channel
+---
+
+# /names
+
+## Syntax
+
+    /names [channel]
+
+## Description
+
+Display the list of users in a channel. Without arguments, lists users in the current channel. Also sends a NAMES request to the server to refresh the nick list panel.
+
+The output shows each user with their mode prefix (@, +, etc.) and a total user count.
+
+## Examples
+
+    /names              # list users in current channel
+    /names #help        # list users in #help
+
+## See Also
+
+/who, /whois

package/docs/commands/preview.md

@@ -0,0 +1,31 @@
+---
+category: Media
+description: Preview an image URL in the terminal
+---
+
+# /preview
+
+## Syntax
+
+    /preview <url>
+
+## Description
+
+Fetches an image URL and displays it as a popup overlay in the terminal.
+Supports direct image links (jpg, png, gif, webp) and pages with og:image
+metadata (imgur, imgbb, etc.).
+
+The display protocol is auto-detected based on your terminal:
+kitty, iTerm2, sixel, or Unicode half-block fallback.
+Works through tmux with DCS passthrough.
+
+Press any key or click to dismiss the preview.
+
+## Examples
+
+    /preview https://i.imgur.com/abc123.jpg
+    /preview https://imgur.com/gallery/xyz
+
+## See Also
+
+/image

package/docs/commands/topic.md

@@ -7,18 +7,24 @@ description: Set or view channel topic
 
 ## Syntax
 
-    /topic [channel] <text>
+    /topic
+    /topic <text>
+    /topic <channel>
+    /topic <channel> <text>
 
 ## Description
 
-Set the topic for a channel. With just text, sets the topic for the
-current channel. Specify a channel name to set a different channel's topic.
+View or set the channel topic.
+
+Without arguments, displays the current topic for the active channel. With only a channel name, requests the topic from the server. With text, sets the topic on the active channel (or on the specified channel).
 
 ## Examples
 
-    /topic Welcome to the channel!
-    /topic #linux Welcome to #linux
+    /topic                          # show current topic
+    /topic #help                    # request topic for #help
+    /topic Welcome to the channel   # set topic on current channel
+    /topic #help Welcome!           # set topic on #help
 
 ## See Also
 
-/join, /mode
+/mode, /names

package/docs/commands/version.md

@@ -0,0 +1,23 @@
+---
+category: Info
+description: Query server or user client version
+---
+
+# /version
+
+## Syntax
+
+    /version [nick]
+
+## Description
+
+Without arguments, queries the IRC server version. With a nick, sends a CTCP VERSION request to that user to find out what client they are using. The reply is displayed in the active buffer.
+
+## Examples
+
+    /version                # query server version
+    /version someone        # query someone's client version
+
+## See Also
+
+/whois

package/package.json

@@ -1,7 +1,46 @@
 {
   "name": "kokoirc",
-  "version": "0.2.3",
-  "description": "Terminal IRC client built with OpenTUI and React",
+  "version": "0.2.5",
+  "description": "Modern terminal IRC client with inline image preview, SASL, scripting, encrypted logging, and theming — built with OpenTUI, React, and Bun",
+  "license": "MIT",
+  "author": {
+    "name": "kofany",
+    "url": "https://github.com/kofany"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kofany/kokoIRC.git"
+  },
+  "homepage": "https://kofany.github.io/kokoIRC/",
+  "bugs": {
+    "url": "https://github.com/kofany/kokoIRC/issues"
+  },
+  "keywords": [
+    "irc",
+    "irc-client",
+    "terminal",
+    "tui",
+    "cli",
+    "client",
+    "chat",
+    "opentui",
+    "react",
+    "bun",
+    "sasl",
+    "sixel",
+    "image-preview",
+    "theming",
+    "scripting",
+    "sqlite",
+    "encrypted-logging"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
   "module": "src/index.tsx",
   "type": "module",
   "bin": {
@@ -17,11 +56,13 @@
     "start": "bun run src/index.tsx",
     "dev": "bun --watch run src/index.tsx",
     "test": "bun test",
-    "build": "bun build --compile src/index.tsx --outfile openirc"
+    "build": "bun build --compile src/index.tsx --outfile kokoirc",
+    "docs:build": "bun run docs/build.ts"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",
     "@types/react": "^19.2.14",
+    "@types/sharp": "^0.32.0",
     "typescript": "^5.9.3"
   },
   "imports": {
@@ -32,6 +73,8 @@
     "@opentui/react": "^0.1.83",
     "kofany-irc-framework": "^4.14.1",
     "react": "^19.2.4",
+    "sharp": "^0.34.5",
+    "sixel": "^0.16.0",
     "smol-toml": "^1.6.0",
     "zustand": "^5.0.11"
   }

package/src/app/App.tsx

@@ -10,6 +10,7 @@ import { initHomeDir } from "@/core/init"
 import { autoloadScripts } from "@/core/scripts/manager"
 import { initStorage, shutdownStorage } from "@/core/storage"
 import { BufferType, ActivityLevel, makeBufferId, getSortGroup } from "@/types"
+import { nextMsgId } from "@/core/utils/id"
 import { SplashScreen } from "@/ui/splash/SplashScreen"
 import { AppLayout } from "@/ui/layout/AppLayout"
 import { TopicBar } from "@/ui/layout/TopicBar"
@@ -18,6 +19,7 @@ import { NickList } from "@/ui/sidebar/NickList"
 import { ChatView } from "@/ui/chat/ChatView"
 import { CommandInput } from "@/ui/input/CommandInput"
 import { StatusLine } from "@/ui/statusbar/StatusLine"
+import { ImagePreview } from "@/ui/overlay/ImagePreview"
 
 export function App() {
   const renderer = useRenderer()
@@ -33,7 +35,17 @@ export function App() {
 
   useKeyboard((key) => {
     if (key.name === "q" && key.ctrl) {
-      shutdownStorage().finally(() => renderer.destroy())
+      shutdownStorage().finally(() => {
+        renderer.destroy()
+        process.exit(0)
+      })
+      return
+    }
+
+    // Dismiss image preview on any keypress
+    if (useStore.getState().imagePreview) {
+      useStore.getState().hideImagePreview()
+      key.preventDefault()
       return
     }
 
@@ -112,7 +124,10 @@ export function App() {
   // Register shutdown handler so commands can close the app
   useEffect(() => {
     useStore.getState().setShutdownHandler(() => {
-      shutdownStorage().finally(() => renderer.destroy())
+      shutdownStorage().finally(() => {
+        renderer.destroy()
+        process.exit(0)
+      })
     })
   }, [renderer])
 
@@ -131,6 +146,14 @@ export function App() {
       setTheme(theme)
 
       await loadAllDocs()
+
+      // Run image cache cleanup (fire-and-forget)
+      const imgConfig = config.image_preview
+      if (imgConfig?.enabled) {
+        import("@/core/image-preview/cache").then(({ cleanupCache }) => {
+          cleanupCache(imgConfig.cache_max_mb ?? 100, imgConfig.cache_max_days ?? 7).catch(() => {})
+        })
+      }
     }
     init().catch((err) => console.error("[init]", err))
   }, [])
@@ -152,7 +175,7 @@ export function App() {
         type: BufferType.Server,
         name: "Status",
         messages: [{
-          id: crypto.randomUUID(),
+          id: nextMsgId(),
           timestamp: new Date(),
           type: "event" as const,
           text: "Welcome to kokoIRC. Type /connect to connect to a server.",
@@ -200,6 +223,7 @@ export function App() {
       nicklist={<NickList />}
       input={<CommandInput />}
       statusline={statusbarEnabled ? <StatusLine /> : undefined}
+      overlay={<ImagePreview />}
     />
   )
 }

package/src/core/commands/help-formatter.ts

@@ -7,7 +7,7 @@ import { commands, findByAlias, getCanonicalName } from "./registry"
 
 const CATEGORY_ORDER = [
   "Connection", "Channel", "Messaging", "Moderation",
-  "Configuration", "Statusbar", "Info",
+  "Media", "Configuration", "Statusbar", "Info",
 ]
 
 // ─── /help (no args) — categorized command list ─────────────

package/src/core/commands/helpers.ts

@@ -1,6 +1,7 @@
 import { useStore } from "@/core/state/store"
 import { makeBufferId, BufferType } from "@/types"
 import type { AppConfig } from "@/types/config"
+import { nextMsgId } from "@/core/utils/id"
 import { CREDENTIAL_FIELDS } from "./types"
 import type { ResolvedConfig } from "./types"
 
@@ -10,7 +11,7 @@ export function addLocalEvent(text: string) {
   const buf = s.activeBufferId
   if (!buf) return
   s.addMessage(buf, {
-    id: crypto.randomUUID(),
+    id: nextMsgId(),
     timestamp: new Date(),
     type: "event",
     text,
@@ -155,6 +156,7 @@ export function listAllSettings(config: AppConfig): void {
   showSection("sidepanel.left", "sidepanel.left", config.sidepanel.left)
   showSection("sidepanel.right", "sidepanel.right", config.sidepanel.right)
   showSection("statusbar", "statusbar", config.statusbar)
+  showSection("image_preview", "image_preview", config.image_preview)
 
   if (Object.keys(config.aliases).length > 0) {
     showSection("aliases", "aliases", config.aliases)