kokoirc 0.2.0

package/README.md

@@ -0,0 +1,227 @@
+# kokoIRC
+
+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 │          │
+└───────────┴──────────────────────────────────────────┴──────────┘
+```
+
+## Features
+
+- **Full IRC protocol** — channels, queries, CTCP, SASL, TLS, channel modes, ban lists
+- **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
+- **Flood protection** — blocks CTCP and nick-change spam from botnets
+- **Persistent logging** — SQLite with optional AES-256-GCM encryption, FTS5 full-text search
+- **Theming** — irssi-compatible format strings with 24-bit color, custom abstracts
+- **Scripting** — TypeScript scripts with event bus, custom commands, IRC access
+- **Single binary** — compiles to a standalone executable with `bun build --compile`
+
+## Requirements
+
+- [Bun](https://bun.sh) v1.2+
+- A terminal with 256-color or truecolor support
+
+## Install
+
+```bash
+git clone https://github.com/kofany/OpenIRC.git
+cd OpenIRC
+bun install
+```
+
+## Usage
+
+```bash
+# Run directly
+bun run src/index.tsx
+
+# Or build a standalone binary
+bun run build
+./openirc
+```
+
+## Configuration
+
+Config lives at `~/.kokoirc/config.toml`. Created on first run with defaults.
+
+```toml
+[general]
+nick = "mynick"
+username = "mynick"
+realname = "kokoIRC user"
+theme = "default"
+flood_protection = true
+
+[display]
+nick_column_width = 8
+scrollback_lines = 2000
+
+[servers.libera]
+label = "Libera"
+address = "irc.libera.chat"
+port = 6697
+tls = true
+autoconnect = true
+channels = ["#kokoirc"]
+# sasl_user = "mynick"
+# sasl_pass = "hunter2"
+
+[logging]
+enabled = true
+encrypt = false       # AES-256-GCM (key auto-generated in ~/.kokoirc/.env)
+retention_days = 0    # 0 = keep forever
+exclude_types = []    # filter: "event", "notice", "ctcp", etc.
+
+[aliases]
+wc = "/close"
+j = "/join"
+```
+
+## Commands
+
+33 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` |
+| Nick/Ops | `/nick`, `/op`, `/deop`, `/voice`, `/devoice` |
+| User | `/whois`, `/wii`, `/ignore`, `/unignore` |
+| Config | `/set`, `/alias`, `/unalias`, `/reload` |
+| Logging | `/log status`, `/log search <query>` |
+| Scripts | `/script load`, `/script unload`, `/script list` |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Esc+1-9` | Switch to window 1-9 |
+| `Esc+0` | Switch to window 10 |
+| `Esc+Left/Right` | Previous/next window |
+| `Page Up/Down` | Scroll chat history |
+| `Tab` | Nick completion |
+| `Ctrl+Q` | Quit |
+
+## Theming
+
+Themes use TOML with an irssi-inspired format string language. Place custom themes in `~/.kokoirc/themes/` and set `theme = "mytheme"` in config.
+
+```toml
+[meta]
+name = "Nightfall"
+description = "Modern dark theme with subtle accents"
+
+[colors]
+accent = "#7aa2f7"
+fg = "#a9b1d6"
+
+[abstracts]
+timestamp = "%Z6e738d$*%N"
+msgnick = "%Z565f89$0$1%Z7aa2f7>%N%| "
+action = "%Ze0af68* $*%N"
+
+[formats.messages]
+pubmsg = "{msgnick $2 $0}$1"
+action = "{action $0} $1"
+```
+
+Format codes: `%r` red, `%g` green, `%ZRRGGBB` hex color, `%_` bold, `%u` underline, `$0 $1 $2` positional args, `{abstract $args}` template references.
+
+## Scripting
+
+Scripts are TypeScript files loaded from `~/.kokoirc/scripts/`. See `examples/scripts/` for samples.
+
+```typescript
+import type { KokoAPI } from "kokoirc-client/api"
+
+export default function slap(api: KokoAPI) {
+  api.command("slap", ({ args, buffer }) => {
+    const target = args[0] ?? "everyone"
+    api.irc.action(buffer.connectionId, buffer.name,
+      `slaps ${target} around a bit with a large trout`)
+  })
+}
+```
+
+Scripts can register commands, listen to IRC events, send messages, and interact with the store:
+
+```typescript
+export default function highlights(api: KokoAPI) {
+  api.on("irc.privmsg", (event) => {
+    if (event.message.highlight) {
+      api.ui.addLocalEvent(event.bufferId,
+        `Highlight from ${event.nick}: ${event.text}`)
+    }
+  })
+}
+```
+
+Configure autoloading in `config.toml`:
+
+```toml
+[scripts]
+autoload = ["slap", "spam-filter"]
+```
+
+## Logging
+
+Messages are stored in `~/.kokoirc/logs.db` (SQLite WAL mode). The log system supports:
+
+- **Batched writes** — flushes at 50 messages or every second
+- **Full-text search** — FTS5 index for instant `/log search` results
+- **Optional encryption** — AES-256-GCM per message, key auto-generated
+- **Read markers** — per-client unread tracking (ready for web frontend)
+- **Retention** — auto-purge messages older than N days
+
+## Architecture
+
+```
+src/
+├── index.tsx              # Entry point — creates OpenTUI renderer
+├── app/
+│   └── 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
+```
+
+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.
+
+## Development
+
+```bash
+bun run dev          # Start with --watch (auto-reload on file changes)
+bun test             # Run test suite
+bun run build        # Compile to standalone binary
+```
+
+## License
+
+MIT

package/docs/commands/alias.md

@@ -0,0 +1,42 @@
+---
+category: Configuration
+description: Define, list, or remove user aliases
+---
+
+# /alias
+
+## Syntax
+
+    /alias [[-]name] [body]
+
+## Description
+
+Define custom command aliases. Aliases expand before execution and support
+template variables and command chaining with semicolons.
+
+With no arguments, lists all defined aliases.
+With just a name, shows that alias's body.
+With `-name`, removes the alias.
+With name and body, defines or replaces the alias.
+
+Template variables:
+- `$0`-`$9` — positional arguments
+- `$*` — all arguments
+- `$C` — current channel name
+- `$N` — current nick
+- `$S` — current server label
+- `$T` — current buffer name
+
+Cannot override built-in commands.
+
+## Examples
+
+    /alias
+    /alias ns /msg NickServ $*
+    /alias cs /msg ChanServ $*
+    /alias j /join $0; /msg $0 hello everyone
+    /alias -ns
+
+## See Also
+
+/unalias

package/docs/commands/ban.md

@@ -0,0 +1,26 @@
+---
+category: Moderation
+description: Ban a user or hostmask
+---
+
+# /ban
+
+## Syntax
+
+    /ban <nick|mask>
+
+## Description
+
+Ban a user or hostmask from the current channel. If a plain nick is
+given, it's converted to `nick!*@*`. If the argument contains `!` or `@`,
+it's used as a literal hostmask.
+
+## Examples
+
+    /ban troll
+    /ban *!*@bad.host.com
+    /ban *!*ident@*.isp.net
+
+## See Also
+
+/unban, /kick, /kb, /mode

package/docs/commands/close.md

@@ -0,0 +1,25 @@
+---
+category: Channel
+description: Close current buffer
+---
+
+# /close
+
+## Syntax
+
+    /close [reason]
+
+## Description
+
+Close the current buffer. For channels, parts the channel with an
+optional reason. For query windows, closes the window. Server buffers
+cannot be closed.
+
+## Examples
+
+    /close
+    /close Window closed
+
+## See Also
+
+/part, /quit

package/docs/commands/connect.md

@@ -0,0 +1,26 @@
+---
+category: Connection
+description: Connect to a server by id, label, or address
+---
+
+# /connect
+
+## Syntax
+
+    /connect <server-id|label|address>[:<port>] [-tls] [-bind=<ip>]
+
+## Description
+
+Connect to an IRC server. Accepts a configured server ID, label, or a
+raw address for ad-hoc connections. If the server is already configured,
+flags override its settings for this connection only.
+
+## Examples
+
+    /connect libera
+    /connect irc.libera.chat:6697 -tls
+    /connect mynet -bind=192.168.1.100
+
+## See Also
+
+/server, /disconnect, /quit

package/docs/commands/deop.md

@@ -0,0 +1,24 @@
+---
+category: Moderation
+description: Remove operator status
+---
+
+# /deop
+
+## Syntax
+
+    /deop <nick> [nick2 ...]
+
+## Description
+
+Remove channel operator status (-o) from one or more users in the current
+channel. You must be a channel operator to use this command.
+
+## Examples
+
+    /deop troublemaker
+    /deop user1 user2
+
+## See Also
+
+/op, /devoice, /mode

package/docs/commands/devoice.md

@@ -0,0 +1,24 @@
+---
+category: Moderation
+description: Remove voice status
+---
+
+# /devoice
+
+## Syntax
+
+    /devoice <nick> [nick2 ...]
+
+## Description
+
+Remove voice status (-v) from one or more users in the current channel.
+You must be a channel operator to use this command.
+
+## Examples
+
+    /devoice user1
+    /devoice user1 user2
+
+## See Also
+
+/voice, /deop, /mode

package/docs/commands/disconnect.md

@@ -0,0 +1,26 @@
+---
+category: Connection
+description: Disconnect from a server
+---
+
+# /disconnect
+
+## Syntax
+
+    /disconnect [server-id|label] [message]
+
+## Description
+
+Disconnect from an IRC server. With no arguments, disconnects from the
+server associated with the current buffer. Optionally specify a server
+by ID or label, and a quit message.
+
+## Examples
+
+    /disconnect
+    /disconnect libera
+    /disconnect libera Goodbye!
+
+## See Also
+
+/connect, /quit, /server

package/docs/commands/help.md

@@ -0,0 +1,28 @@
+---
+category: Info
+description: Show help for commands
+---
+
+# /help
+
+## Syntax
+
+    /help [command] [subcommand]
+
+## Description
+
+Show help for commands. With no arguments, lists all commands grouped
+by category. With a command name, shows detailed usage, subcommands,
+and examples. With a command and subcommand, shows help for that
+specific subcommand.
+
+## Examples
+
+    /help
+    /help server
+    /help server add
+    /help items format
+
+## See Also
+
+/set

package/docs/commands/ignore.md

@@ -0,0 +1,47 @@
+---
+category: Moderation
+description: Add an ignore rule
+---
+
+# /ignore
+
+## Syntax
+
+    /ignore [mask] [levels...] [-channels #a,#b]
+
+## Description
+
+Add an ignore rule to suppress messages and events from matching
+users. Without arguments, lists current ignore rules.
+
+A bare nick pattern (e.g., `troll`) matches the nick only.
+A pattern containing `!` (e.g., `*!*@bad.host`) matches the
+full `nick!user@host` mask with wildcard support (`*`, `?`).
+
+## Levels
+
+    MSGS      Private messages
+    PUBLIC    Channel messages
+    NOTICES   Notices
+    ACTIONS   CTCP ACTIONs (/me)
+    JOINS     Join events
+    PARTS     Part events
+    QUITS     Quit events
+    NICKS     Nick change events
+    KICKS     Kick events
+    CTCPS     CTCP requests and responses
+    ALL       All of the above
+
+If no levels are specified, ALL is assumed.
+
+## Examples
+
+    /ignore
+    /ignore troll
+    /ignore *!*@bad.host.com
+    /ignore spammer PUBLIC NOTICES
+    /ignore bot CTCPS -channels #help,#support
+
+## See Also
+
+/unignore

package/docs/commands/items.md

@@ -0,0 +1,95 @@
+---
+category: Statusbar
+description: Manage statusbar items and formats
+---
+
+# /items
+
+## Syntax
+
+    /items [list|add|remove|move|format|separator|available|reset] [args...]
+
+## Description
+
+Manage the statusbar layout. Add, remove, reorder items and customize
+their format strings. Use `/items available` to see all possible items
+and their format variables.
+
+## Subcommands
+
+### list
+
+Show current statusbar items with their positions and formats.
+
+    /items list
+
+This is the default when no subcommand is given.
+
+### add
+
+Add an item to the statusbar.
+
+    /items add <item>
+
+### remove
+
+Remove an item from the statusbar.
+
+    /items remove <item>
+
+Aliases: del
+
+### move
+
+Move an item to a new position.
+
+    /items move <item> <position>
+
+Position is 1-based.
+
+### format
+
+View or set the format string for an item.
+
+    /items format <item> [format_string]
+
+Format variables: `$win`, `$activity`, `$nick`, `$modes`, `$name`, `$lag`, `$time`.
+
+Aliases: fmt
+
+### separator
+
+View or set the separator string between items.
+
+    /items separator [string]
+
+Aliases: sep
+
+### available
+
+List all available statusbar items and their default formats.
+
+    /items available
+
+Shows which items are currently active and which are unused.
+
+### reset
+
+Reset statusbar to default items, formats, and separator.
+
+    /items reset
+
+## Examples
+
+    /items list
+    /items add clock
+    /items remove lag
+    /items move clock 1
+    /items format window_name [$win] $name
+    /items separator  |
+    /items available
+    /items reset
+
+## See Also
+
+/set

package/docs/commands/join.md

@@ -0,0 +1,25 @@
+---
+category: Channel
+description: Join a channel
+---
+
+# /join
+
+## Syntax
+
+    /join <channel> [key]
+
+## Description
+
+Join an IRC channel. A `#` prefix is auto-added if missing.
+Optionally provide a channel key for key-protected channels.
+
+## Examples
+
+    /join #linux
+    /join linux
+    /join #secret mysecretkey
+
+## See Also
+
+/part, /close

package/docs/commands/kb.md

@@ -0,0 +1,26 @@
+---
+category: Moderation
+description: Kickban a user (kick then ban *!*ident@host)
+---
+
+# /kb
+
+## Syntax
+
+    /kb <nick> [reason]
+
+## Description
+
+Kick and ban a user from the current channel. Looks up the user's
+ident and host via USERHOST to create a proper `*!*ident@host` ban mask,
+then kicks with the given reason. Falls back to `nick!*@*` if the
+lookup times out after 5 seconds.
+
+## Examples
+
+    /kb troll
+    /kb spammer Enough is enough
+
+## See Also
+
+/kick, /ban, /unban, /mode

package/docs/commands/kick.md

@@ -0,0 +1,25 @@
+---
+category: Moderation
+description: Kick a user from the channel
+---
+
+# /kick
+
+## Syntax
+
+    /kick <nick> [reason]
+
+## Description
+
+Kick a user from the current channel. If no reason is given, the
+user's nick is used as the reason. You must be a channel operator
+to use this command.
+
+## Examples
+
+    /kick troll
+    /kick spammer Stop spamming
+
+## See Also
+
+/ban, /kb, /mode