28 lines
1.7 KiB
Markdown
28 lines
1.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
Sox is a Campfire bot written in Go. It runs as an HTTP server (default port `4567`, overridable via `PORT` env var) that receives webhook POST requests from Campfire and responds with HTML-formatted text.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
make build # builds binary to bin/sox
|
|
make test # runs all tests with verbose output
|
|
go test -run TestSplitFirstWord ./... # run a single test
|
|
```
|
|
|
|
The `math` command requires `qalc` (libqalculate) on PATH. Tests that need it skip automatically if it's absent.
|
|
|
|
## Architecture
|
|
|
|
**Plugin system** (`plugin.go`): Each command is a struct implementing the `Plugin` interface (`Name()`, `ShortHelp()`, `DetailedHelp()`, `Execute()`). Plugins self-register via `registerPlugin()` called from `init()` in `main.go`. The global `registry` map (`map[string]Plugin`) routes commands by name.
|
|
|
|
**Request handling** (`main.go`): `commandHandler` decodes the Campfire JSON webhook into `BotMessage`, then `executeCommand` splits the plain-text body into command + arguments. If the command isn't recognized, it falls back to the user's last successfully used command (stored in `userLastCommandType`, a `map[string]string` keyed by username). The `help` command is excluded from last-command memory.
|
|
|
|
**Adding a new command**: Create a `cmd_<name>.go` file, implement the `Plugin` interface, and add `registerPlugin(YourPlugin{})` to `init()` in `main.go`.
|
|
|
|
**HTTP tracing** (`request_trace.go`, `cmd_trace.go`): `TraceRequest` uses `net/http/httptrace` to instrument a GET request with a 3-second timeout and returns a `RequestTrace` struct with timestamps for each phase (DNS, connect, TLS, headers, first byte, last byte).
|