kokoirc 0.2.2 → 0.2.4

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,17 +32,31 @@ A modern terminal IRC client built with [OpenTUI](https://github.com/anomalyco/o
 
 ## Install
 
+### From npm
+
 ```bash
-git clone https://github.com/kofany/OpenIRC.git
-cd OpenIRC
-bun install
+# Global install (adds `kokoirc` to your PATH)
+bun install -g kokoirc
+
+# Then run from anywhere
+kokoirc
+```
+
+```bash
+# Local install (in a project)
+bun add kokoirc
+bunx kokoirc
 ```
 
-## Usage
+### 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
@@ -74,10 +85,17 @@ address = "irc.libera.chat"
 port = 6697
 tls = true
 autoconnect = true
-channels = ["#kokoirc"]
+channels = ["#kokoirc", "#secret mykey"]   # "channel key" syntax for keyed channels
+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)
@@ -91,16 +109,19 @@ j = "/join"
 
 ## Commands
 
-33 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` |
-| Messaging | `/msg`, `/me`, `/notice`, `/action`, `/slap` |
-| Moderation | `/kick`, `/ban`, `/unban`, `/kb`, `/mode` |
+| 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 | `/version`, `/stats` |
+| Server | `/quote` (`/raw`), `/oper` |
 | Config | `/set`, `/alias`, `/unalias`, `/reload` |
 | Logging | `/log status`, `/log search <query>` |
 | Scripts | `/script load`, `/script unload`, `/script list` |
@@ -191,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/kill.md

@@ -0,0 +1,24 @@
+---
+category: Moderation
+description: Disconnect a user from the network
+---
+
+# /kill
+
+## Syntax
+
+    /kill <nick> [reason]
+
+## Description
+
+Forcefully disconnect a user from the IRC network. This is an operator-only
+command. If no reason is given, the target's nick is used as the reason.
+
+## Examples
+
+    /kill spammer Spamming is not allowed
+    /kill baduser
+
+## See Also
+
+/oper, /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/oper.md

@@ -0,0 +1,24 @@
+---
+category: Server
+description: Authenticate as an IRC operator
+---
+
+# /oper
+
+## Syntax
+
+    /oper <name> <password>
+
+## Description
+
+Authenticate as an IRC operator. Requires valid operator credentials
+configured on the server. Once authenticated, you gain access to
+operator commands like /kill and /wallops.
+
+## Examples
+
+    /oper admin secretpass
+
+## See Also
+
+/kill, /wallops

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/quote.md

@@ -0,0 +1,29 @@
+---
+category: Server
+description: Send a raw IRC command
+---
+
+# /quote
+
+## Syntax
+
+    /quote <raw command>
+
+## Description
+
+Send a raw IRC command directly to the server. This is useful for
+commands not yet implemented, testing, or advanced protocol interaction.
+
+## Aliases
+
+/raw
+
+## Examples
+
+    /quote VERSION
+    /raw LUSERS
+    /quote PRIVMSG #channel :hello
+
+## See Also
+
+/stats

package/docs/commands/server.md

@@ -39,6 +39,12 @@ Add a new server to the configuration.
 - `-label=<name>` — Display name
 - `-password=<pass>` — Server password (saved to .env)
 - `-sasl=<user>:<pass>` — SASL auth (saved to .env)
+- `-autosendcmd=<cmds>` — Commands to run on connect, before autojoin (must be last flag)
+
+Autosendcmd uses erssi-style syntax: commands separated by `;`, with `WAIT <ms>`
+for delays. `$N` is replaced with your nick.
+
+    /server add libera irc.libera.chat:6697 -tls -autosendcmd=MSG NickServ identify pass; WAIT 2000; MODE $N +i
 
 ### remove
 

package/docs/commands/stats.md

@@ -0,0 +1,31 @@
+---
+category: Info
+description: Request server statistics
+---
+
+# /stats
+
+## Syntax
+
+    /stats [type] [server]
+
+## Description
+
+Request statistics from the IRC server. Common stat types include:
+
+- `u` — server uptime
+- `m` — command usage counts
+- `o` — configured operators
+- `l` — connection information
+
+If no type is given, the server may return a summary or help text.
+
+## Examples
+
+    /stats
+    /stats u
+    /stats o irc.libera.chat
+
+## See Also
+
+/quote

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/docs/commands/wallops.md

@@ -0,0 +1,24 @@
+---
+category: Messaging
+description: Send a message to all IRC operators
+---
+
+# /wallops
+
+## Syntax
+
+    /wallops <message>
+
+## Description
+
+Send a message to all connected IRC operators. This is an operator-only
+command typically used for server-wide announcements among staff.
+
+## Examples
+
+    /wallops Server maintenance in 10 minutes
+    /wallops New oper guidelines posted on the wiki
+
+## See Also
+
+/oper, /quote

package/package.json

@@ -1,7 +1,46 @@
 {
   "name": "kokoirc",
-  "version": "0.2.2",
-  "description": "Terminal IRC client built with OpenTUI and React",
+  "version": "0.2.4",
+  "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 openirc",
+    "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()
@@ -37,6 +39,13 @@ export function App() {
       return
     }
 
+    // Dismiss image preview on any keypress
+    if (useStore.getState().imagePreview) {
+      useStore.getState().hideImagePreview()
+      key.preventDefault()
+      return
+    }
+
     // Track standalone Escape keypresses for Esc+N prefix
     if (key.name === "escape" && !key.ctrl && !key.shift) {
       escPressedAt.current = Date.now()
@@ -152,7 +161,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 +209,7 @@ export function App() {
       nicklist={<NickList />}
       input={<CommandInput />}
       statusline={statusbarEnabled ? <StatusLine /> : undefined}
+      overlay={<ImagePreview />}
     />
   )
 }