kokoirc 0.2.0

package/docs/commands/log.md

@@ -0,0 +1,82 @@
+---
+category: Logging
+description: Chat log management
+---
+
+# /log
+
+## Syntax
+
+    /log [status|search] [query]
+
+## Description
+
+Manage persistent chat logs. Messages are stored in a local SQLite database
+at `~/.kokoirc/logs.db` with WAL mode for concurrent access.
+
+Only messages that reach the UI are logged — messages filtered by `/ignore`,
+antiflood, or script `stop()` propagation are never stored.
+
+## Subcommands
+
+### status
+
+Show logging status including message count, database size, and encryption mode.
+
+    /log status
+
+This is the default when no subcommand is given.
+
+### search
+
+Full-text search across logged messages (plain text mode only).
+
+    /log search <query>
+
+Searches within the current buffer's network and channel context. Results
+show the 20 most recent matches with timestamps.
+
+Search is not available in encrypted mode since ciphertext cannot be indexed.
+
+## Configuration
+
+```toml
+[logging]
+enabled = true       # enable/disable logging
+encrypt = false      # AES-256-GCM encryption (disables search)
+retention_days = 0   # 0 = keep forever
+exclude_types = []   # filter: "message", "action", "notice", "ctcp", "event"
+```
+
+### Encryption
+
+When `encrypt = true`, message text is encrypted with AES-256-GCM using a
+256-bit key auto-generated in `~/.kokoirc/.env`. No password is required —
+same trust model as irssi logs or SSH keys.
+
+Only the `text` column is encrypted. Network, buffer, nick, timestamp, and
+type remain queryable for the future web frontend.
+
+### Retention
+
+Set `retention_days` to automatically purge old messages on startup.
+`0` means keep forever.
+
+### Excluding Types
+
+Filter specific message types from logging:
+
+```toml
+[logging]
+exclude_types = ["event"]  # skip join/part/quit events
+```
+
+## Examples
+
+    /log
+    /log status
+    /log search ssl certificate
+
+## See Also
+
+/set, /ignore

package/docs/commands/me.md

@@ -0,0 +1,24 @@
+---
+category: Messaging
+description: Send an action message
+---
+
+# /me
+
+## Syntax
+
+    /me <action>
+
+## Description
+
+Send a CTCP ACTION message to the current channel or query. Displayed
+as `* nick action` in the chat.
+
+## Examples
+
+    /me waves hello
+    /me is away for lunch
+
+## See Also
+
+/msg, /notice

package/docs/commands/mode.md

@@ -0,0 +1,29 @@
+---
+category: Info
+description: Set or query channel/user modes
+---
+
+# /mode
+
+## Syntax
+
+    /mode [target] [+/-modes] [params]
+
+## Description
+
+Set or query channel or user modes. With no arguments, queries your
+own user modes. If the first argument starts with `+` or `-`, applies
+the mode change to the current channel. Otherwise, the first argument
+is treated as the target.
+
+## Examples
+
+    /mode
+    /mode +i
+    /mode #linux +o friend
+    /mode +nt
+    /mode #linux +b *!*@bad.host
+
+## See Also
+
+/op, /deop, /voice, /ban

package/docs/commands/msg.md

@@ -0,0 +1,26 @@
+---
+category: Messaging
+description: Send a message to a user or channel
+---
+
+# /msg
+
+## Syntax
+
+    /msg <target> <message>
+
+## Description
+
+Send a private message to a user or channel. For private messages, a
+query window is automatically opened and focused. Messages sent to
+channels appear in the channel buffer.
+
+## Examples
+
+    /msg NickServ IDENTIFY mypassword
+    /msg friend Hey, what's up?
+    /msg #linux Hello everyone
+
+## See Also
+
+/notice, /me

package/docs/commands/nick.md

@@ -0,0 +1,24 @@
+---
+category: Messaging
+description: Change your nickname
+---
+
+# /nick
+
+## Syntax
+
+    /nick <newnick>
+
+## Description
+
+Change your nickname on the current server. The server may reject the
+change if the nick is already in use or contains invalid characters.
+
+## Examples
+
+    /nick newnick
+    /nick myname_away
+
+## See Also
+
+/whois, /set

package/docs/commands/notice.md

@@ -0,0 +1,24 @@
+---
+category: Messaging
+description: Send a notice
+---
+
+# /notice
+
+## Syntax
+
+    /notice <target> <message>
+
+## Description
+
+Send a NOTICE to a user or channel. Notices are typically used for
+automated replies and should not trigger auto-responses from bots.
+
+## Examples
+
+    /notice friend Check out this link
+    /notice #linux Announcement: meeting at 5pm
+
+## See Also
+
+/msg, /me

package/docs/commands/op.md

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

package/docs/commands/part.md

@@ -0,0 +1,25 @@
+---
+category: Channel
+description: Leave a channel
+---
+
+# /part
+
+## Syntax
+
+    /part [channel] [message]
+
+## Description
+
+Leave an IRC channel. With no arguments, leaves the current channel.
+Optionally specify a channel name and part message.
+
+## Examples
+
+    /part
+    /part #linux
+    /part #linux See you later
+
+## See Also
+
+/join, /close

package/docs/commands/quit.md

@@ -0,0 +1,24 @@
+---
+category: Connection
+description: Quit all connections and close kIRC
+---
+
+# /quit
+
+## Syntax
+
+    /quit [message]
+
+## Description
+
+Disconnect from all servers and close the application. An optional quit
+message is sent to each server. Default message is "kIRC".
+
+## Examples
+
+    /quit
+    /quit Goodnight!
+
+## See Also
+
+/disconnect, /close

package/docs/commands/reload.md

@@ -0,0 +1,19 @@
+---
+category: Configuration
+description: Reload theme and config
+---
+
+# /reload
+
+## Syntax
+
+    /reload
+
+## Description
+
+Reload the configuration file and theme from disk. Useful after manually
+editing `config/config.toml` or theme files.
+
+## See Also
+
+/set, /items

package/docs/commands/script.md

@@ -0,0 +1,126 @@
+---
+category: Scripts
+description: Manage user scripts
+---
+
+# /script
+
+## Syntax
+
+    /script [list|available|load|unload|reload] [name]
+
+## Description
+
+Manage user scripts. Scripts are TypeScript files in `~/.kokoirc/scripts/`
+that extend kokoIRC with custom commands, event hooks, filters, and automation.
+
+Scripts have full access to the IRC client, store, and UI — same trust model
+as irssi Perl scripts.
+
+## Subcommands
+
+### list
+
+Show currently loaded scripts with version and description.
+
+    /script list
+
+This is the default when no subcommand is given.
+
+### available
+
+Show all script files found in `~/.kokoirc/scripts/`.
+
+    /script available
+
+Loaded scripts are marked with a filled circle (●).
+
+### load
+
+Load a script by name or absolute path.
+
+    /script load <name>
+    /script load /path/to/script.ts
+
+When given a name without a path, looks for `~/.kokoirc/scripts/<name>.ts`.
+
+### unload
+
+Unload a script. All event handlers, commands, and timers registered by
+the script are automatically cleaned up.
+
+    /script unload <name>
+
+### reload
+
+Unload and reload a script (cache-busted import).
+
+    /script reload <name>
+
+## Autoloading
+
+Add script names to `config.toml` to load them on startup:
+
+```toml
+[scripts]
+autoload = ["auto-away", "spam-filter"]
+debug = false
+```
+
+## Writing Scripts
+
+Scripts are `.ts` files that export a default init function:
+
+```ts
+import type { KokoAPI, IrcMessageEvent } from "@/core/scripts/types"
+
+export const meta = { name: "my-script", version: "1.0.0", description: "..." }
+export const config = { timeout: 300 }  // defaults for [scripts.my-script]
+
+export default function init(api: KokoAPI) {
+  // Use api.EventPriority for priority constants (HIGHEST, HIGH, NORMAL, LOW, LOWEST)
+  api.on("irc.privmsg", (event: IrcMessageEvent, ctx) => {
+    // ctx.stop() prevents lower-priority handlers + built-in store update
+  }, api.EventPriority.LOW)
+
+  api.command("mycommand", { handler(args, connId) { /* ... */ }, description: "..." })
+
+  return () => { /* cleanup on unload */ }
+}
+```
+
+**Import rules:** Scripts live outside the project, so `@/` path aliases only work
+with `import type` (stripped at runtime). For values like `EventPriority`, use
+`api.EventPriority` instead of importing.
+
+### Available Events
+
+**IRC events:** `irc.privmsg`, `irc.action`, `irc.notice`, `irc.join`, `irc.part`,
+`irc.quit`, `irc.kick`, `irc.nick`, `irc.topic`, `irc.mode`, `irc.invite`,
+`irc.ctcp_request`, `irc.ctcp_response`, `irc.wallops`
+
+**App events:** `command_input`, `connected`, `disconnected`
+
+### Per-Script Config
+
+Declare defaults with `export const config = {...}`. Users override in TOML:
+
+```toml
+[scripts.auto-away]
+timeout = 300
+message = "AFK"
+```
+
+Access via `api.config.get("timeout", 300)`.
+
+## Examples
+
+    /script available
+    /script load auto-away
+    /script list
+    /script reload auto-away
+    /script unload auto-away
+
+## See Also
+
+/set, /alias

package/docs/commands/server.md

@@ -0,0 +1,61 @@
+---
+category: Connection
+description: Manage server configurations
+---
+
+# /server
+
+## Syntax
+
+    /server [list|add|remove] [args...]
+
+## Description
+
+Manage IRC server configurations. Add, remove, and list servers.
+Server credentials (passwords, SASL) are stored in `.env`.
+
+## Subcommands
+
+### list
+
+List all configured servers with their connection status.
+
+    /server list
+
+This is the default when no subcommand is given.
+
+### add
+
+Add a new server to the configuration.
+
+    /server add <id> <address>[:<port>] [flags...]
+
+**Flags:**
+- `-tls` — Enable TLS (auto-sets port to 6697)
+- `-noauto` — Don't auto-connect on startup
+- `-notlsverify` — Skip TLS certificate verification
+- `-bind=<ip>` — Bind to local IP (vhost)
+- `-nick=<nick>` — Server-specific nick override
+- `-label=<name>` — Display name
+- `-password=<pass>` — Server password (saved to .env)
+- `-sasl=<user>:<pass>` — SASL auth (saved to .env)
+
+### remove
+
+Remove a server and disconnect if connected.
+
+    /server remove <id>
+
+Aliases: del
+
+## Examples
+
+    /server list
+    /server add libera irc.libera.chat:6697 -tls
+    /server add libera irc.libera.chat:6697 -tls -sasl=user:pass
+    /server add local 127.0.0.1:6667 -noauto -label=dev
+    /server remove libera
+
+## See Also
+
+/connect, /disconnect, /set

package/docs/commands/set.md

@@ -0,0 +1,37 @@
+---
+category: Configuration
+description: View or change configuration
+---
+
+# /set
+
+## Syntax
+
+    /set [section.field] [value]
+
+## Description
+
+View or change runtime configuration. Settings use dot-notation paths
+like `general.nick` or `servers.libera.port`. Changes are saved to
+`config/config.toml` immediately. Credentials (passwords, SASL) are
+stored in `.env` instead.
+
+With no arguments, lists all settings grouped by section.
+With just a path, shows the current value.
+With a path and value, sets the value and saves.
+
+Boolean values accept: `true`/`false`, `on`/`off`, `yes`/`no`.
+Array values use comma-separated format: `#chan1,#chan2`.
+
+## Examples
+
+    /set
+    /set general.nick
+    /set general.nick newnick
+    /set general.theme tokyo-night
+    /set servers.libera.tls true
+    /set servers.libera.channels #linux,#irc
+
+## See Also
+
+/reload, /server, /items

package/docs/commands/topic.md

@@ -0,0 +1,24 @@
+---
+category: Channel
+description: Set or view channel topic
+---
+
+# /topic
+
+## Syntax
+
+    /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.
+
+## Examples
+
+    /topic Welcome to the channel!
+    /topic #linux Welcome to #linux
+
+## See Also
+
+/join, /mode

package/docs/commands/unalias.md

@@ -0,0 +1,22 @@
+---
+category: Configuration
+description: Remove a user alias
+---
+
+# /unalias
+
+## Syntax
+
+    /unalias <name>
+
+## Description
+
+Remove a user-defined alias. Equivalent to `/alias -name`.
+
+## Examples
+
+    /unalias ns
+
+## See Also
+
+/alias

package/docs/commands/unban.md

@@ -0,0 +1,25 @@
+---
+category: Moderation
+description: Remove a ban
+---
+
+# /unban
+
+## Syntax
+
+    /unban <nick|mask>
+
+## Description
+
+Remove a ban 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
+
+    /unban friend
+    /unban *!*@good.host.com
+
+## See Also
+
+/ban, /kick, /kb, /mode

package/docs/commands/unignore.md

@@ -0,0 +1,25 @@
+---
+category: Moderation
+description: Remove an ignore rule
+---
+
+# /unignore
+
+## Syntax
+
+    /unignore <number|mask>
+
+## Description
+
+Remove an ignore rule by its number (from `/ignore` list) or
+by the exact mask pattern.
+
+## Examples
+
+    /unignore 1
+    /unignore troll
+    /unignore *!*@bad.host.com
+
+## See Also
+
+/ignore

package/docs/commands/voice.md

@@ -0,0 +1,25 @@
+---
+category: Moderation
+description: Give voice status
+---
+
+# /voice
+
+## Syntax
+
+    /voice <nick> [nick2 ...]
+
+## Description
+
+Give voice status (+v) to one or more users in the current channel.
+Voiced users can speak in moderated (+m) channels. You must be a
+channel operator to use this command.
+
+## Examples
+
+    /voice user1
+    /voice user1 user2
+
+## See Also
+
+/devoice, /op, /mode

package/docs/commands/whois.md

@@ -0,0 +1,24 @@
+---
+category: Info
+description: Look up user information
+---
+
+# /whois
+
+## Syntax
+
+    /whois <nick>
+
+## Description
+
+Look up information about a user including their hostname, real name,
+channels, server, and account status.
+
+## Examples
+
+    /whois friend
+    /whois ChanServ
+
+## See Also
+
+/wii, /nick