kokoirc 0.2.0

package/docs/commands/wii.md

@@ -0,0 +1,23 @@
+---
+category: Info
+description: Whois with idle time
+---
+
+# /wii
+
+## Syntax
+
+    /wii <nick>
+
+## Description
+
+Like `/whois` but also includes idle time and signon time. Sends
+`WHOIS nick nick` to request the idle information from the user's server.
+
+## Examples
+
+    /wii friend
+
+## See Also
+
+/whois, /nick

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "kokoirc",
+  "version": "0.2.0",
+  "description": "Terminal IRC client built with OpenTUI and React",
+  "module": "src/index.tsx",
+  "type": "module",
+  "bin": {
+    "kokoirc": "src/index.tsx"
+  },
+  "files": [
+    "src",
+    "themes",
+    "docs/commands",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "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"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  },
+  "imports": {
+    "@/*": "./src/*"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.83",
+    "@opentui/react": "^0.1.83",
+    "kofany-irc-framework": "^4.14.1",
+    "react": "^19.2.4",
+    "smol-toml": "^1.6.0",
+    "zustand": "^5.0.11"
+  }
+}

package/src/app/App.tsx

@@ -0,0 +1,205 @@
+import { useState, useEffect, useCallback, useRef } from "react"
+import { useRenderer, useKeyboard } from "@opentui/react"
+import { useStore } from "@/core/state/store"
+import { loadConfig } from "@/core/config/loader"
+import { loadTheme } from "@/core/theme/loader"
+import { connectAllAutoconnect } from "@/core/irc"
+import { CONFIG_PATH, THEME_PATH } from "@/core/constants"
+import { loadAllDocs } from "@/core/commands"
+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 { SplashScreen } from "@/ui/splash/SplashScreen"
+import { AppLayout } from "@/ui/layout/AppLayout"
+import { TopicBar } from "@/ui/layout/TopicBar"
+import { BufferList } from "@/ui/sidebar/BufferList"
+import { NickList } from "@/ui/sidebar/NickList"
+import { ChatView } from "@/ui/chat/ChatView"
+import { CommandInput } from "@/ui/input/CommandInput"
+import { StatusLine } from "@/ui/statusbar/StatusLine"
+
+export function App() {
+  const renderer = useRenderer()
+  const setConfig = useStore((s) => s.setConfig)
+  const setTheme = useStore((s) => s.setTheme)
+  const config = useStore((s) => s.config)
+  const [showSplash, setShowSplash] = useState(true)
+
+  // Escape-prefix timestamp for irssi-style Esc+N window switching.
+  // OpenTUI's stdin buffer uses a 5ms timeout — too short for manual Esc then N.
+  // We track when Escape was pressed and check on the next keypress.
+  const escPressedAt = useRef(0)
+
+  useKeyboard((key) => {
+    if (key.name === "q" && key.ctrl) {
+      shutdownStorage().finally(() => renderer.destroy())
+      return
+    }
+
+    // Track standalone Escape keypresses for Esc+N prefix
+    if (key.name === "escape" && !key.ctrl && !key.shift) {
+      escPressedAt.current = Date.now()
+      return
+    }
+
+    // Check if this keypress is an Esc+key combo:
+    // Either key.meta is set (terminal sent Alt+N natively, e.g. iTerm2 with Option-as-Meta)
+    // or Escape was pressed within the last 500ms (manual Esc then N)
+    const isEscCombo = key.meta || (Date.now() - escPressedAt.current < 500)
+
+    if (isEscCombo) {
+      // Reset the escape timestamp so it doesn't trigger again
+      escPressedAt.current = 0
+
+      const s = useStore.getState()
+
+      // Build sorted buffer list (same order as sidebar)
+      const getSortedIds = () => {
+        const bufs = Array.from(s.buffers.values())
+          .filter((b) => b.connectionId !== "_default")
+          .map((b) => ({
+            ...b,
+            connectionLabel: s.connections.get(b.connectionId)?.label ?? b.connectionId,
+          }))
+          .sort((a, b) => {
+            const lc = a.connectionLabel.localeCompare(b.connectionLabel, undefined, { sensitivity: "base" })
+            if (lc !== 0) return lc
+            const ga = getSortGroup(a.type), gb = getSortGroup(b.type)
+            if (ga !== gb) return ga - gb
+            return a.name.localeCompare(b.name, undefined, { sensitivity: "base" })
+          })
+        return bufs.map((b) => b.id)
+      }
+
+      // Esc+1..9 → buffer 1-9, Esc+0 → buffer 10
+      if (key.name >= "1" && key.name <= "9") {
+        const idx = parseInt(key.name, 10) - 1
+        const ids = getSortedIds()
+        if (idx < ids.length) {
+          s.setActiveBuffer(ids[idx])
+          key.preventDefault()
+        }
+        return
+      }
+      if (key.name === "0") {
+        const ids = getSortedIds()
+        if (ids.length >= 10) {
+          s.setActiveBuffer(ids[9])
+          key.preventDefault()
+        }
+        return
+      }
+
+      // Esc+Left/Right → prev/next buffer (wrap)
+      if (key.name === "left" || key.name === "right") {
+        const ids = getSortedIds()
+        if (ids.length === 0) return
+        const currentIdx = s.activeBufferId ? ids.indexOf(s.activeBufferId) : -1
+        let next: number
+        if (key.name === "left") {
+          next = currentIdx <= 0 ? ids.length - 1 : currentIdx - 1
+        } else {
+          next = currentIdx >= ids.length - 1 ? 0 : currentIdx + 1
+        }
+        s.setActiveBuffer(ids[next])
+        key.preventDefault()
+        return
+      }
+    }
+  })
+
+  // Register shutdown handler so commands can close the app
+  useEffect(() => {
+    useStore.getState().setShutdownHandler(() => {
+      shutdownStorage().finally(() => renderer.destroy())
+    })
+  }, [renderer])
+
+  // Load config + theme during splash (but don't connect yet)
+  useEffect(() => {
+    async function init() {
+      await initHomeDir()
+      const config = await loadConfig(CONFIG_PATH)
+      setConfig(config)
+
+      // Initialize persistent log storage before any connections
+      await initStorage(config.logging)
+
+      const themePath = THEME_PATH(config.general.theme)
+      const theme = await loadTheme(themePath)
+      setTheme(theme)
+
+      await loadAllDocs()
+    }
+    init().catch((err) => console.error("[init]", err))
+  }, [])
+
+  // After splash finishes → connect, autoload scripts, switch to Status window
+  const handleSplashDone = useCallback(() => {
+    setShowSplash(false)
+    connectAllAutoconnect()
+    autoloadScripts().catch((err) => console.error("[scripts] autoload error:", err))
+
+    const s = useStore.getState()
+
+    // If no autoconnect created a buffer, create a default Status buffer
+    if (s.buffers.size === 0) {
+      const bufferId = makeBufferId("_default", "Status")
+      s.addBuffer({
+        id: bufferId,
+        connectionId: "_default",
+        type: BufferType.Server,
+        name: "Status",
+        messages: [{
+          id: crypto.randomUUID(),
+          timestamp: new Date(),
+          type: "event" as const,
+          text: "Welcome to kokoIRC. Type /connect to connect to a server.",
+          highlight: false,
+        }],
+        activity: ActivityLevel.None,
+        unreadCount: 0,
+        lastRead: new Date(),
+        users: new Map(),
+        listModes: new Map(),
+      })
+      s.setActiveBuffer(bufferId)
+      return
+    }
+
+    // Activate first Status buffer so user sees connection progress
+    for (const buf of s.buffers.values()) {
+      if (buf.type === BufferType.Server) {
+        s.setActiveBuffer(buf.id)
+        break
+      }
+    }
+  }, [])
+
+  if (showSplash) {
+    return <SplashScreen onDone={handleSplashDone} />
+  }
+
+  // Show loading state until config is loaded
+  if (!config) {
+    return (
+      <box width="100%" height="100%" justifyContent="center" alignItems="center" backgroundColor="#1a1b26">
+        <text><span fg="#565f89">Connecting...</span></text>
+      </box>
+    )
+  }
+
+  const statusbarEnabled = config?.statusbar?.enabled ?? true
+
+  return (
+    <AppLayout
+      topicbar={<TopicBar />}
+      sidebar={<BufferList />}
+      chat={<ChatView />}
+      nicklist={<NickList />}
+      input={<CommandInput />}
+      statusline={statusbarEnabled ? <StatusLine /> : undefined}
+    />
+  )
+}

package/src/core/commands/docs.ts

@@ -0,0 +1,183 @@
+// ─── Command Documentation Parser & Cache ──────────────────
+// Parses docs/commands/*.md into structured help objects.
+// Single source of truth for /help output and subcommand tab completion.
+
+import { DOCS_DIR } from "@/core/constants"
+
+export interface SubcommandHelp {
+  name: string
+  aliases: string[]
+  description: string   // first paragraph of prose
+  syntax: string        // indented code lines
+  body: string          // full subsection text
+}
+
+export interface CommandHelp {
+  category: string
+  description: string   // from frontmatter
+  syntax: string        // from ## Syntax
+  body: string          // from ## Description
+  subcommands: SubcommandHelp[]
+  examples: string[]
+  seeAlso: string[]
+}
+
+const helpCache = new Map<string, CommandHelp>()
+
+// ─── Parsing ────────────────────────────────────────────────
+
+function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
+  const meta: Record<string, string> = {}
+  if (!raw.startsWith("---")) return { meta, body: raw }
+
+  const end = raw.indexOf("---", 3)
+  if (end === -1) return { meta, body: raw }
+
+  const block = raw.slice(3, end).trim()
+  for (const line of block.split("\n")) {
+    const idx = line.indexOf(":")
+    if (idx > 0) {
+      meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim()
+    }
+  }
+  return { meta, body: raw.slice(end + 3).trim() }
+}
+
+function splitSections(body: string): Map<string, string> {
+  const sections = new Map<string, string>()
+  const parts = body.split(/^## /m)
+  for (const part of parts) {
+    if (!part.trim()) continue
+    const nlIdx = part.indexOf("\n")
+    if (nlIdx === -1) continue
+    const heading = part.slice(0, nlIdx).trim()
+    const content = part.slice(nlIdx + 1).trim()
+    sections.set(heading.toLowerCase(), content)
+  }
+  return sections
+}
+
+function extractIndented(text: string): string {
+  return text
+    .split("\n")
+    .filter((l) => l.startsWith("    "))
+    .map((l) => l.slice(4))
+    .join("\n")
+    .trim()
+}
+
+function parseSubcommands(text: string): SubcommandHelp[] {
+  const subs: SubcommandHelp[] = []
+  const parts = text.split(/^### /m)
+
+  for (const part of parts) {
+    if (!part.trim()) continue
+    const nlIdx = part.indexOf("\n")
+    if (nlIdx === -1) continue
+
+    const name = part.slice(0, nlIdx).trim().toLowerCase()
+    const body = part.slice(nlIdx + 1).trim()
+
+    const syntax = extractIndented(body)
+
+    // Extract aliases from "Aliases: del, rm" line
+    const aliases: string[] = []
+    const aliasMatch = body.match(/^Aliases?:\s*(.+)$/im)
+    if (aliasMatch) {
+      for (const a of aliasMatch[1].split(",")) {
+        const trimmed = a.trim().toLowerCase()
+        if (trimmed) aliases.push(trimmed)
+      }
+    }
+
+    // First paragraph of prose (skip indented lines and Aliases line)
+    const descLines: string[] = []
+    for (const line of body.split("\n")) {
+      if (line.startsWith("    ")) continue
+      if (/^Aliases?:/i.test(line)) continue
+      if (line.startsWith("**Flags:**")) break
+      const trimmed = line.trim()
+      if (trimmed) descLines.push(trimmed)
+      else if (descLines.length > 0) break
+    }
+
+    subs.push({
+      name,
+      aliases,
+      description: descLines.join(" "),
+      syntax,
+      body,
+    })
+  }
+  return subs
+}
+
+function parseDoc(raw: string): CommandHelp {
+  const { meta, body } = parseFrontmatter(raw)
+  const sections = splitSections(body)
+
+  const syntax = sections.has("syntax") ? extractIndented(sections.get("syntax")!) : ""
+  const description = meta.description ?? ""
+  const category = meta.category ?? "Other"
+  const bodyText = sections.get("description") ?? ""
+
+  const subcommands = sections.has("subcommands")
+    ? parseSubcommands(sections.get("subcommands")!)
+    : []
+
+  const examples = sections.has("examples")
+    ? extractIndented(sections.get("examples")!).split("\n").filter(Boolean)
+    : []
+
+  const seeAlso = sections.has("see also")
+    ? sections.get("see also")!
+        .split(",")
+        .map((s) => s.trim().replace(/^\//, ""))
+        .filter(Boolean)
+    : []
+
+  return { category, description, syntax, body: bodyText, subcommands, examples, seeAlso }
+}
+
+// ─── Cache & Public API ─────────────────────────────────────
+
+export async function loadAllDocs(): Promise<void> {
+  helpCache.clear()
+  const glob = new Bun.Glob("*.md")
+  for await (const file of glob.scan(DOCS_DIR)) {
+    const name = file.replace(/\.md$/, "").toLowerCase()
+    try {
+      const raw = await Bun.file(`${DOCS_DIR}/${file}`).text()
+      helpCache.set(name, parseDoc(raw))
+    } catch {
+      // skip unreadable files
+    }
+  }
+}
+
+export function getHelp(command: string): CommandHelp | null {
+  return helpCache.get(command.toLowerCase()) ?? null
+}
+
+export function getSubcommands(command: string): string[] {
+  const help = helpCache.get(command.toLowerCase())
+  if (!help) return []
+  const names: string[] = []
+  for (const sub of help.subcommands) {
+    names.push(sub.name)
+    for (const alias of sub.aliases) names.push(alias)
+  }
+  return names.sort()
+}
+
+export function getCategories(): Map<string, string[]> {
+  const cats = new Map<string, string[]>()
+  for (const [name, help] of helpCache) {
+    const list = cats.get(help.category) ?? []
+    list.push(name)
+    cats.set(help.category, list)
+  }
+  // Sort commands within each category
+  for (const list of cats.values()) list.sort()
+  return cats
+}

package/src/core/commands/execution.ts

@@ -0,0 +1,114 @@
+import { useStore } from "@/core/state/store"
+import { parseCommand } from "./parser"
+import type { ParsedCommand } from "./parser"
+import { commands, aliasMap, findByAlias } from "./registry"
+import { addLocalEvent } from "./helpers"
+import { eventBus } from "@/core/scripts/event-bus"
+import { scriptCommands } from "@/core/scripts/api"
+
+const MAX_ALIAS_DEPTH = 10
+
+/** Expand a user alias template with positional args and context variables. */
+function expandAlias(template: string, args: string[], connectionId: string): string {
+  let body = template
+
+  // Auto-append $* if body contains no $ references
+  if (!body.includes("$")) {
+    body += " $*"
+  }
+
+  // Context variables
+  const s = useStore.getState()
+  const conn = s.connections.get(connectionId)
+  const buf = s.activeBufferId ? s.buffers.get(s.activeBufferId) : null
+
+  body = body.replace(/\$\{?C\}?/g, buf?.name ?? "")
+  body = body.replace(/\$\{?N\}?/g, conn?.nick ?? "")
+  body = body.replace(/\$\{?S\}?/g, conn?.label ?? "")
+  body = body.replace(/\$\{?T\}?/g, buf?.name ?? "")
+
+  // Range args: $0-, $1-, $2-, etc.
+  body = body.replace(/\$(\d)-/g, (_match, n) => {
+    const idx = parseInt(n, 10)
+    return args.slice(idx).join(" ")
+  })
+
+  // $* — all args
+  body = body.replace(/\$\*/g, args.join(" "))
+
+  // Single positional: $0 .. $9
+  body = body.replace(/\$(\d)/g, (_match, n) => {
+    const idx = parseInt(n, 10)
+    return args[idx] ?? ""
+  })
+
+  return body.trim()
+}
+
+export function executeCommand(parsed: ParsedCommand, connectionId: string, depth = 0): boolean {
+  // Recursion guard
+  if (depth > MAX_ALIAS_DEPTH) {
+    addLocalEvent(`%Zf7768eAlias recursion limit reached (max ${MAX_ALIAS_DEPTH})%N`)
+    return false
+  }
+
+  // Emit command_input event (scripts can intercept/block commands)
+  if (depth === 0) {
+    const proceed = eventBus.emit("command_input", {
+      command: parsed.command,
+      args: parsed.args,
+      connectionId,
+    })
+    if (!proceed) return true // script stopped propagation
+  }
+
+  // 1. Built-in command or built-in alias
+  const def = commands[parsed.command] ?? findByAlias(parsed.command)
+  if (def) {
+    def.handler(parsed.args, connectionId)
+    return true
+  }
+
+  // 2. Script command
+  const scriptCmd = scriptCommands.get(parsed.command)
+  if (scriptCmd) {
+    scriptCmd.def.handler(parsed.args, connectionId)
+    return true
+  }
+
+  // 3. User alias
+  const config = useStore.getState().config
+  const aliasBody = config?.aliases[parsed.command]
+  if (aliasBody) {
+    const expanded = expandAlias(aliasBody, parsed.args, connectionId)
+    // Split by ; for command chaining
+    const parts = expanded.split(";").map((p) => p.trim()).filter(Boolean)
+    for (const part of parts) {
+      const sub = parseCommand(part)
+      if (sub) {
+        executeCommand(sub, connectionId, depth + 1)
+      }
+    }
+    return true
+  }
+
+  // 4. Unknown
+  addLocalEvent(`%Zf7768eUnknown command: /${parsed.command}. Type /help for available commands.%N`)
+  return false
+}
+
+/** All registered command names + built-in aliases + script commands + user aliases, sorted. For tab completion. */
+export function getCommandNames(): string[] {
+  const names = Object.keys(commands)
+  for (const alias of Object.keys(aliasMap)) {
+    names.push(alias)
+  }
+  for (const name of scriptCommands.keys()) {
+    names.push(name)
+  }
+  const userAliases = useStore.getState().config?.aliases ?? {}
+  for (const name of Object.keys(userAliases)) {
+    names.push(name)
+  }
+  return names.sort()
+}