phpbotscout

module
v0.13.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT

README

phpbotscout

Support and moderation bot bridging Discord and GitLab

Built on gtb, the phpboyscout framework for Go CLI tools and services.

What is this?

Support happens in two places that do not talk to each other. Questions arrive in Discord, get answered from memory, scroll away, and are asked again a fortnight later. The problems worth tracking rarely become GitLab issues, and the ones that do lose the conversation that produced them. Meanwhile the answer usually already existed, in a README nobody read at 22:40.

phpbotscout is built to close both loops. It sits in your Discord server and answers what is already documented, with citations. When it cannot answer, it is to offer to raise a GitLab issue on the asker's behalf with the thread attached, and it is to watch for moderation risk and route it to a private mod queue rather than to nobody. The answering half is running; the other two are not built yet.

The side effect is the point: every question it cannot answer is a documentation gap with a timestamp on it. The escalation stream is a prioritised docs backlog that writes itself.

Status: in development, and released. The daemon watches Discord and answers addressed questions in shadow mode: it composes the answer and does not post it, except in a server that opts in with post_answers. Moderation and issue raising are not built; what phpbotscout does not do has the list. See phpbotscout: draft requirements for the governing requirements and delivery phases.

Prerequisites

  • Go 1.27.2 or newer (the go line in go.mod) and a C toolchain, to build from source.
  • glibc 2.34 or newer, to run the binary. See runtime requirements.

The following tools are only needed for development (they are not required to install or run the binary). Each is invoked by a just recipe:

  • just, the task runner used by this repo.
  • golangci-lint for linting (just lint).
  • pre-commit for the repo hooks (just check).
  • zensical for the docs site (just docs-serve).
  • goreleaser for local snapshot builds (just snapshot).

Install

The supported install is the linux/amd64 release archive, from the releases page. phpbotscout is an internal tool that happens to be open source, and cross-platform builds are not something this project undertakes to provide.

Each release publishes phpbotscout_Linux_x86_64.tar.gz and checksums.txt. Releases are checksummed, not signed.

The binary needs glibc 2.34 or newer (Debian 12, Ubuntu 22.04) and nothing else. v0.5.0 alone also needed libdave.so; later releases do not. Getting started has the download and checksum steps.

Building from source
just build          # → bin/phpbotscout

Needs Go 1.27.2 or newer and a C toolchain: the SQLite driver is the native one, under cgo.

go install still works and is a development convenience, but it needs both build tags spelled out:

go install -tags sqlite_fts5,discord_novoice gitlab.com/phpboyscout/phpbotscout/cmd/phpbotscout@latest

sqlite_fts5 gives the driver full-text search. discord_novoice keeps the Discord adapter's voice support, and the libdave.so it links, out of a cgo build. Leave either off and the build stops with an error naming it. just build sets both for you, which is why it is the recommended route. Getting started has more.

The main package lives at cmd/phpbotscout/, so the install path ends in /cmd/phpbotscout. Installing the module root fails, because it has no main package.

Build & run

This repository ships a justfile with the common tasks. Build the binary with the default recipe:

just            # tidy + generate + build → bin/phpbotscout
just build      # the same, explicitly

Then run it:

./bin/phpbotscout --help

To install the built binary into $GOPATH/bin:

just install

Develop

Clone & verify
just test        # unit tests with coverage
just test-race   # tests under the race detector
just lint        # golangci-lint
just check       # pre-commit hooks across the tree
just ci          # the full local CI suite (tidy, generate, test, test-race, lint)

Run just ci before opening a merge request. It covers the lint and unit-test half of the pipeline; CI also runs the E2E scenarios (just test-e2e), the embedding integration tests, the security scans and a release smoke test.

Project layout
Path What lives there
cmd/phpbotscout/ The main package, and the imports that wire in the chat providers, the GitLab forge, the keychain and MCP.
pkg/cmd/ The commands: serve, ask, index and review, plus the generated root command.
pkg/cmd/root/assets/init/config.yaml The starting configuration phpbotscout init writes.
pkg/ The library the commands are built from. Components says what each package is for.
internal/version/ Build-time version metadata (injected via ldflags).
docs/ The documentation site source (served by zensical).
.gtb/manifest.yaml The generator manifest (see below).

Add your own commands under pkg/cmd/<command>/ and your reusable packages under pkg/.

The manifest & regeneration model

phpbotscout is scaffolded and kept in sync by GTB's generator. The .gtb/manifest.yaml file is the source of truth for the command tree and project settings. Two flows operate on it:

  • gtb generate command <name> scaffolds a new command, recording it in the manifest.
  • gtb regenerate re-renders the project from the manifest and the current GTB templates.

Generated files are hash-tracked in the manifest. If you hand-edit a generated file, the next regenerate detects the change as a conflict and prompts before overwriting it, so your edits are never silently lost. This README is one of those files: it is yours to edit, and regeneration will ask before replacing it.

Do not hand-edit generated files expecting silent re-generation. Put custom logic in your own packages, or accept the conflict prompt on the next regenerate.

Configuration

Configuration is layered, highest precedence first: flags you changed, environment variables, a project-local .phpbotscout.yaml, then the config files. There is no shipped-defaults layer: a key no layer sets takes the default compiled into the code. pkg/cmd/root/assets/init/config.yaml is only the starting file phpbotscout init writes. The configuration reference lists every key.

Any setting can be overridden from the environment using the PHPBOTSCOUT prefix. For example, a log.level setting is overridden by PHPBOTSCOUT_LOG_LEVEL.

Enabled built-ins

GTB provides built-in commands. The following are always available in this project: self-update, first-run init, MCP server, embedded documentation, doctor checks, and changelog.

The following opt-in built-ins are also enabled:

  • AI: docs ask over the embedded documentation, and the provider setup init offers. Answering questions is phpbotscout's own ask, not this.
  • Config management: the config command, to inspect and edit configuration.
  • Telemetry: the telemetry command, for opt-in usage reporting.

Change the feature set with gtb enable <feature> / gtb disable <feature> (e.g. gtb enable ai). That updates .gtb/manifest.yaml and re-renders the root command, so the change survives gtb regenerate project. Do not hand-edit pkg/cmd/root/cmd.go; it is generated and will be overwritten.

Run phpbotscout --help to see the full command list.

Documentation

The documentation site source lives in docs/ and is built with zensical. Serve it locally with:

just docs-serve

Then open the printed local URL in your browser.

Releasing

Releases are driven by Conventional Commits. colophon, the release component in .gitlab-ci.yml, keeps a release merge request open on main and works out the next version from the commits since the last tag. Merging that merge request tags the release. The tag pipeline runs GoReleaser (.goreleaser.yaml), which publishes the archive and checksums.txt to the release store, and deploys the docs site.

A docs: commit does not cut a release.

Contributing

  • Follow Conventional Commits for every commit. The changelog and version bumps are computed from them.
  • Run just ci before opening a merge request.
  • Do not hand-edit generated files (those tracked in .gtb/manifest.yaml); the next gtb regenerate will flag them as conflicts.

Go deeper

GTB documentation:

Directories

Path Synopsis
cmd
phpbotscout command
Registers the chat providers this tool ships, one module per line.
Registers the chat providers this tool ships, one module per line.
internal
pkg
answer
Package answer turns a question into a grounded answer, or into an honest refusal to answer.
Package answer turns a question into a grounded answer, or into an honest refusal to answer.
budget
Package budget bounds how often the bot will answer.
Package budget bounds how often the bot will answer.
cmd/index/session
Package session wires the index commands to their dependencies.
Package session wires the index commands to their dependencies.
corpus
Package corpus decides what the bot is allowed to know.
Package corpus decides what the bot is allowed to know.
embed
Package embed turns text into a vector, in process, with no network call.
Package embed turns text into a vector, in process, with no network call.
events
Package events owns what an event is: the subject names, the CloudEvent types, the schema URNs, and the Go types the bus encodes and decodes.
Package events owns what an event is: the subject names, the CloudEvent types, the schema URNs, and the Go types the bus encodes and decodes.
gateway
Package gateway turns permitted Discord messages into events on the bus.
Package gateway turns permitted Discord messages into events on the bus.
index
Package index stores the corpus and answers questions against it.
Package index stores the corpus and answers questions against it.
indexer
Package indexer builds and refreshes the knowledge index.
Package indexer builds and refreshes the knowledge index.
ingest
Package ingest reads messages from a chat platform and does nothing else with them.
Package ingest reads messages from a chat platform and does nothing else with them.
respond
Package respond decides whether to speak, and how.
Package respond decides whether to speak, and how.
review
Package review records a person's verdict on the answers the bot composed in shadow mode, which is what stands between shadow mode and posting (spec 0010 D12, spec 0023).
Package review records a person's verdict on the answers the bot composed in shadow mode, which is what stands between shadow mode and posting (spec 0010 D12, spec 0023).
store
Package store owns phpbotscout's single SQLite database.
Package store owns phpbotscout's single SQLite database.
transport
Package transport owns the Discord connection for the life of a generation and nothing else for the life of the process (0018 D8).
Package transport owns the Discord connection for the life of a generation and nothing else for the life of the process (0018 D8).
test
e2e/steps
Package steps holds the Godog step definitions for phpbotscout's E2E behaviour tests.
Package steps holds the Godog step definitions for phpbotscout's E2E behaviour tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL