tjcravey/sojuboy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sojuboy/AGENTS.md

2.5 KiB
Raw Blame History

Repository Guidelines

Architecture Overview

  • Role: Additional IRC client (not a bot) connected to a soju bouncer with your same nick. Uses a distinct clientId/username suffix for per‑client history.
  • Ingestion: Raw IRC via internal/soju with optional CHATHISTORY backfill, quiet hours, and rate limiting for alerts.
  • Storage: SQLite (internal/store) for channel logs and metadata.
  • Notifications: Pushover (internal/notifier) for mentions and scheduled digests.
  • Summaries: OpenAI LLM (internal/summarizer, default gpt‑5) for link and channel summaries.
  • Web UI: internal/httpapi serves SSE live view, link cards, inline article summaries, and an on‑demand summary page.

Project Structure

  • cmd/sojuboy/: entrypoint and service wiring
  • internal/{soju,store,notifier,summarizer,httpapi,scheduler}: core packages
  • Root: Dockerfile, docker-compose.yml, README.md, CHANGELOG.md

Build, Run, and Deploy

  • Local: go build -o sojuboy ./cmd/sojuboy or go run ./cmd/sojuboy
  • Docker (Synology‑friendly): docker compose up --build (exposes 8080)
  • Health: ./sojuboy --health, curl :8080/healthz, curl :8080/ready
  • Example .env: SOJU_HOST=host SOJU_PORT=6697 SOJU_TLS=true IRC_NICK=nick IRC_USERNAME=user/network@sojuboy IRC_PASSWORD=... CHANNELS=#chan1,#chan2 NOTIFIER=pushover PUSHOVER_USER_KEY=... PUSHOVER_API_TOKEN=... LLM_PROVIDER=openai OPENAI_API_KEY=... DIGEST_CRON=0 0 9 * * * HTTP_TOKEN=longtoken

Coding Style & Naming

  • Format: gofmt -s -w .; lint: go vet ./...; deps: go mod tidy
  • Indentation: Go uses tabs; YAML/JS use 2 spaces
  • Naming: packages lower‑case; exported CamelCase; files snake_case.go
  • Logging: use slog via internal/logging; include context

Testing Guidelines

  • Use standard testing with table‑driven tests; place beside code (*_test.go)
  • For store tests, use in‑memory DB: store.Open(ctx, ":memory:")
  • Run: go test ./... and go test -cover ./...

Commits & PRs

  • Commits: short, imperative; conventional tags like feat(ui):, fix(store):, docs: (see history)
  • PRs: description, linked issues, repro/verification steps; screenshots for Web UI changes
  • Update README.md/CHANGELOG.md when flags, endpoints, or UX change

Security & Config

  • Keep secrets in .env (git‑ignored); never commit API keys
  • Synology: map /data volume; protect UI with HTTP_TOKEN (cookie/Bearer/query); bind 127.0.0.1:8080 behind DSM Reverse Proxy if desired