Help us shape the future of Go! Take the 2026 Go Developer Survey

bentoolkit

module
v0.34.0 Latest Latest
Warning

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

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

README

Bentoolkit

Release Go

Command-line tools for maintainers of the Bentoo Gentoo overlay: keep its ebuilds current with upstream, validate every bump before it ships, publish notices, and protect the machine with btrfs snapshots.

Modules

Command What for
bentoo overlay The overlay's git workflow (status, add, commit with a generated message, push, pull), compare against ::gentoo, prune what ::gentoo already ships identically, manifest, rename
bentoo overlay autoupdate Read each package's upstream version (--check), then stage, validate and commit the bump (--apply); packages.toml says where each version is read
bentoo overlay validate Check that an ebuild still matches the source it points at, on a ladder of depths from build options to a full install
bentoo distfile fetch Download a distfile Portage cannot fetch by itself (behind a registration form or a POST) into DISTDIR
bentoo notice Write a notice once, as a GLEP 42 news item in the overlay and an entry in the website's feed
bentoo snapshot Declarative btrfs snapshots: btrbk and snapper, cloud copies with restic or rclone, systemd timers, rollback
bentoo-tray A desktop notifier that announces the notices that concern the packages you have installed

Installation

Add the Bentoo overlay, then install the packages:

eselect repository add bentoo git https://github.com/obentoo/bentoo.git
emerge --sync bentoo
emerge --ask app-portage/bentoolkit    # bentoo
emerge --ask app-portage/bentoo-tray   # optional: the desktop notifier

Or build from source. Go comes from the toolchain line in go.mod, which go downloads on first use:

git clone https://github.com/obentoo/bentoolkit.git
cd bentoolkit
make build                # build/bentoo and build/bentoo-tray
sudo make install         # into /usr/local, with the tray's desktop entry and user unit

Builds are reproducible: -trimpath, and a build date taken from SOURCE_DATE_EPOCH or the last commit.

Quick start

make install-config       # or copy config.example.yaml to ~/.config/bentoo/config.yaml
$EDITOR ~/.config/bentoo/config.yaml      # set overlay.path to your checkout

bentoo overlay status                      # what changed in the overlay
bentoo overlay autoupdate --check          # which packages have a newer upstream
bentoo overlay autoupdate --list           # the updates found, waiting to be applied
bentoo overlay autoupdate --apply all      # stage, validate and commit them

bentoo --help lists every command, and bentoo <command> --help explains one. Secrets (API tokens) never go in the config file; see Configuration.

Documentation

Contributing

See CONTRIBUTING.md. In short: make check while you work (make test for the tests alone), then ./scripts/ci-vm-gate.sh, which runs the whole CI (tests, linters, CodeQL, scanners) on a clean checkout in a local VM.

Report security problems privately, as SECURITY.md describes.

License

MIT. See LICENSE.

Directories

Path Synopsis
cmd
bentoo command
Command bentoo is the command-line tool for Bentoo overlay maintainers: it manages the overlay's git workflow, checks and applies upstream version updates, fetches gated distfiles, authors notices, and drives btrfs snapshots.
 Command bentoo is the command-line tool for Bentoo overlay maintainers: it manages the overlay's git workflow, checks and applies upstream version updates, fetches gated distfiles, authors notices, and drives btrfs snapshots.
bentoo-tray command
Command bentoo-tray is the session tray that announces bentoo notices.
 Command bentoo-tray is the session tray that announces bentoo notices.
internal
autoupdate
Package autoupdate provides automated version checking and update application for ebuilds in the Bentoo overlay.
 Package autoupdate provides automated version checking and update application for ebuilds in the Bentoo overlay.
autoupdate/ebuilds
Package ebuilds reads the ebuild tree of an overlay: it locates a package directory, lists its ebuilds, selects the current ebuild for a slot or a version series, splits package atoms, labels and slots, and extracts EbuildMetadata from an ebuild file.
 Package ebuilds reads the ebuild tree of an overlay: it locates a package directory, lists its ebuilds, selects the current ebuild for a slot or a version series, splits package atoms, labels and slots, and extracts EbuildMetadata from an ebuild file.
autoupdate/fetch
Package fetch is autoupdate's HTTP layer: the retrying client with its circuit breaker, per-host policies and body caps, the rate limiter, the response and fetch caches, header allow-listing with credential scoping, and authenticated distfile fetching driven by a record's meta.fetch_* keys, including the spec parser that --lint reuses.
 Package fetch is autoupdate's HTTP layer: the retrying client with its circuit breaker, per-host policies and body caps, the rate limiter, the response and fetch caches, header allow-listing with credential scoping, and authenticated distfile fetching driven by a record's meta.fetch_* keys, including the spec parser that --lint reuses.
autoupdate/fixer
Package fixer holds autoupdate's agent fixers: LLM agents, run through the Claude Code CLI with the least-privilege profile from llm, that repair a failed bump — the manifest fixer, the build fixer, the bump reviewer and the registry fixer.
 Package fixer holds autoupdate's agent fixers: LLM agents, run through the Claude Code CLI with the least-privilege profile from llm, that repair a failed bump — the manifest fixer, the build fixer, the bump reviewer and the registry fixer.
autoupdate/llm
Package llm holds autoupdate's LLM providers: the OpenAI and Ollama HTTP clients and the Claude Code client that drives the local `claude` CLI, the least-privilege permission profile every agent run is given, and the classification of how a `claude` run ended.
 Package llm holds autoupdate's LLM providers: the OpenAI and Ollama HTTP clients and the Claude Code client that drives the local `claude` CLI, the least-privilege permission profile every agent run is given, and the classification of how a `claude` run ended.
autoupdate/parse
Package parse extracts versions from upstream content: JSON paths, regular expressions and HTML/XPath, version transforms and series selection, version-history extraction, and the validation of an extracted version against a registry record.
 Package parse extracts versions from upstream content: JSON paths, regular expressions and HTML/XPath, version transforms and series selection, version-history extraction, and the validation of an extracted version against a registry record.
autoupdate/registry
Package registry is the packages.toml registry: it loads and saves the file, validates each record (including its meta.fetch_* spec, judged by the fetch package's own parser), lints and repairs it, renders a record, prunes and removes records, and migrates auto-disabled entries.
 Package registry is the packages.toml registry: it loads and saves the file, validates each record (including its meta.fetch_* spec, judged by the fetch package's own parser), lints and repairs it, renders a record, prunes and removes records, and migrates auto-disabled entries.
autoupdate/statefile
Package statefile reads, merges and saves autoupdate's JSON state files under the inter-process file lock, so concurrent bentoo processes never lose each other's writes.
 Package statefile reads, merges and saves autoupdate's JSON state files under the inter-process file lock, so concurrent bentoo processes never lose each other's writes.
autoupdate/validate
Package validate answers one question about an ebuild without building it: does it still match the source it points at?
 Package validate answers one question about an ebuild without building it: does it still match the source it points at?
common/config
Package config loads and saves ~/.config/bentoo/config.yaml: the overlay, git identity, autoupdate, validation, UI, notice and tray settings.
 Package config loads and saves ~/.config/bentoo/config.yaml: the overlay, git identity, autoupdate, validation, UI, notice and tray settings.
common/distfiles
Package distfiles resolves and prepares the directory pkgdev is given as --distdir, and holds the single implementation every caller shares.
 Package distfiles resolves and prepares the directory pkgdev is given as --distdir, and holds the single implementation every caller shares.
common/ebuild
Package ebuild parses ebuild paths into category, package and version, and compares Gentoo versions (suffixes such as _rc and _p, and -r revisions) the way Portage orders them.
 Package ebuild parses ebuild paths into category, package and version, and compares Gentoo versions (suffixes such as _rc and _p, and -r revisions) the way Portage orders them.
common/filelock
Package filelock is an inter-process exclusive lock on one path.
 Package filelock is an inter-process exclusive lock on one path.
common/fileutil
Package fileutil provides shared helpers for file modes and for writing files that survive a crash, so every write site uses one source for permissions and one audited sequence of temp file, sync and rename.
 Package fileutil provides shared helpers for file modes and for writing files that survive a crash, so every write site uses one source for permissions and one audited sequence of temp file, sync and rename.
common/git
Package git runs the git commands the overlay workflow needs (status, add, commit, push, pull, fetch) under a context, with network and local timeouts, and parses their output.
 Package git runs the git commands the overlay workflow needs (status, add, commit, push, pull, fetch) under a context, with network and local timeouts, and parses their output.
common/github
Package github is a small GitHub Contents API client that lists the ebuild versions a repository holds for a package, with an on-disk response cache, rate-limit detection and a token resolved from the secrets chain.
 Package github is a small GitHub Contents API client that lists the ebuild versions a repository holds for a package, with an on-disk response cache, rate-limit detection and a token resolved from the secrets chain.
common/httpx
Package httpx provides centralized outbound HTTP transport tuning for the bentoolkit.
 Package httpx provides centralized outbound HTTP transport tuning for the bentoolkit.
common/logging
Package logging builds bentoo's diagnostics logger on log/slog.
 Package logging builds bentoo's diagnostics logger on log/slog.
common/output
Package output holds the terminal helpers the commands print with: the color palette, status and package formatting, and terminal detection that turns color off when stdout is not a terminal or NO_COLOR is set.
 Package output holds the terminal helpers the commands print with: the color palette, status and package formatting, and terminal detection that turns color off when stdout is not a terminal or NO_COLOR is set.
common/procgroup
Package procgroup stops a child process — and, on Unix, every process that child started — when the context it was started under is done.
 Package procgroup stops a child process — and, on Unix, every process that child started — when the context it was started under is done.
common/provider
Package provider reads another repository's ebuild versions, for comparing the overlay against it and reviving packages from it.
 Package provider reads another repository's ebuild versions, for comparing the overlay against it and reviving packages from it.
common/report
Package report is the view model of one `overlay autoupdate` run: the packages it scanned, the validation it planned, what the gates answered, and the counts that summarize all of it.
 Package report is the view model of one `overlay autoupdate` run: the packages it scanned, the validation it planned, what the gates answered, and the counts that summarize all of it.
common/report/render
Package render turns the view model in internal/common/report into text for a terminal: it decides how wide a column is, how a value that does not fit is cut, and how much room the line has to begin with.
 Package render turns the view model in internal/common/report into text for a terminal: it decides how wide a column is, how a value that does not fit is cut, and how much room the line has to begin with.
common/secrets
Package secrets resolves a named secret (an API token, a serial, ...) from a fixed, security-conscious chain and nothing else.
 Package secrets resolves a named secret (an API token, a serial, ...) from a fixed, security-conscious chain and nothing else.
common/tui
Package tui is a single Bubble Tea-based TUI foundation for bentoolkit.
 Package tui is a single Bubble Tea-based TUI foundation for bentoolkit.
common/version
Package version holds bentoo's build version, commit and date, stamped at link time through -ldflags -X by the Makefile and the ebuild.
 Package version holds bentoo's build version, commit and date, stamped at link time through -ldflags -X by the Makefile and the ebuild.
common/xdg
Package xdg resolves XDG Base Directory locations.
 Package xdg resolves XDG Base Directory locations.
desktop/dbustest
Package dbustest starts private D-Bus message buses for integration tests, so no test ever talks to the developer's own session or system bus.
 Package dbustest starts private D-Bus message buses for integration tests, so no test ever talks to the developer's own session or system bus.
desktop/dbusx
Package dbusx opens bentoo-tray's private D-Bus connections and owns its well-known bus name.
 Package dbusx opens bentoo-tray's private D-Bus connections and owns its well-known bus name.
desktop/netmon
Package netmon reports whether NetworkManager considers the machine online and the connection metered, and when either of those changes.
 Package netmon reports whether NetworkManager considers the machine online and the connection metered, and when either of those changes.
desktop/notify
Package notify sends desktop notifications over org.freedesktop.Notifications and reports the actions the user takes on them.
 Package notify sends desktop notifications over org.freedesktop.Notifications and reports the actions the user takes on them.
desktop/portal
Package portal opens a notice's URL in the user's browser: through the desktop portal's OpenURI when it answers, through xdg-open when it definitely did not act.
 Package portal opens a notice's URL in the user's browser: through the desktop portal's OpenURI when it answers, through xdg-open when it definitely did not act.
desktop/sni
Package sni exports a StatusNotifierItem (the freedesktop/KDE system tray protocol) over D-Bus.
 Package sni exports a StatusNotifierItem (the freedesktop/KDE system tray protocol) over D-Bus.
gentoo/news
Package news reads the portage news of one repository as notices, the tray's offline source: the unread list portage keeps under /var/lib/gentoo/news and the GLEP 42 news items that list names.
 Package news reads the portage news of one repository as notices, the tray's offline source: the unread list portage keeps under /var/lib/gentoo/news and the GLEP 42 news items that list names.
gentoo/pkgdb
Package pkgdb reads Portage's installed-package database (/var/db/pkg): one directory per installed package at <root>/<CATEGORY>/<PF>/, holding a SLOT file and, for packages installed from a named repository, a repository file.
 Package pkgdb reads Portage's installed-package database (/var/db/pkg): one directory per installed package at <root>/<CATEGORY>/<PF>/, holding a SLOT file and, for packages installed from a named repository, a repository file.
gentoo/repo
Package repo scans the category/package/*.ebuild layout of a Gentoo repository (an overlay) and reports the packages and versions it holds.
 Package repo scans the category/package/*.ebuild layout of a Gentoo repository (an overlay) and reports the packages and versions it holds.
notice
Package notice authors bentoo notices: one input becomes a GLEP 42 news item in the overlay and a YAML file in the site repository, sharing one ID.
 Package notice authors bentoo notices: one input becomes a GLEP 42 news item in the overlay and a YAML file in the site repository, sharing one ID.
notices
Package notices holds the bentoo notices feed contract: the types a notice is carried in, and the parser that turns the site's JSON Feed 1.1 document into them.
 Package notices holds the bentoo notices feed contract: the types a notice is carried in, and the parser that turns the site's JSON Feed 1.1 document into them.
overlay
Package overlay implements the overlay operations behind `bentoo overlay`: the git workflow (status, add, commit with a generated message, push, pull), version renames, Manifest regeneration, pruning of superseded ebuilds, and compare, which reads each package against a baseline repository, classifies how it diverges and, with a model available, reviews the divergence.
 Package overlay implements the overlay operations behind `bentoo overlay`: the git workflow (status, add, commit with a generated message, push, pull), version renames, Manifest regeneration, pruning of superseded ebuilds, and compare, which reads each package against a baseline repository, classifies how it diverges and, with a model available, reviews the divergence.
realign
Package realign proves a proposed realignment of an overlay ebuild towards its ::gentoo baseline, and proving is the whole of what it does: the staged-bump ladder in internal/autoupdate/validate decides whether the realignment builds, and this package is only the composition that hands the proposal to it.
 Package realign proves a proposed realignment of an overlay ebuild towards its ::gentoo baseline, and proving is the whole of what it does: the staged-bump ladder in internal/autoupdate/validate decides whether the realignment builds, and this package is only the composition that hands the proposal to it.
snapshot
Package snapshot orchestrates btrfs snapshot tooling (btrbk, systemd) through a single declarative TOML config.
 Package snapshot orchestrates btrfs snapshot tooling (btrbk, systemd) through a single declarative TOML config.
snapshot/snapshottest
Package snapshottest provides test doubles for package snapshot.
 Package snapshottest provides test doubles for package snapshot.
tray
Package tray is bentoo-tray's event loop and its notification and icon policy.
 Package tray is bentoo-tray's event loop and its notification and icon policy.
tray/feed
Package feed fetches the bentoo notices feed over HTTPS with ETag revalidation, a body size cap and a request deadline.
 Package feed fetches the bentoo notices feed over HTTPS with ETag revalidation, a body size cap and a request deadline.
tray/icons
Package icons holds the tray icon as SNI pixmaps.
 Package icons holds the tray icon as SNI pixmaps.
tray/messages
Package messages is bentoo-tray's message catalog: every menu label, notification text and summary format the tray shows, in English, in one place.
 Package messages is bentoo-tray's message catalog: every menu label, notification text and summary format the tray shows, in English, in one place.
tray/schedule
Package schedule holds the pure timing functions of bentoo-tray: the startup delay, the jittered check interval and the failure backoff.
 Package schedule holds the pure timing functions of bentoo-tray: the startup delay, the jittered check interval and the failure backoff.
tray/state
Package state persists bentoo-tray's state: the feed ETag and serial, the read state and source of every notice, the pause end, the backoff and the earliest next fetch.
 Package state persists bentoo-tray's state: the feed ETag and serial, the read state and source of every notice, the pause end, the backoff and the earliest next fetch.
tray/version
Package version is bentoo-tray's own version, independent of the bentoolkit release it ships in.
 Package version is bentoo-tray's own version, independent of the bentoolkit release it ships in.
misc
design/design-system
Package designsystem is the catalogue of everything the bentoo terminal UI draws, and the single place its visual vocabulary is defined.
 Package designsystem is the catalogue of everything the bentoo terminal UI draws, and the single place its visual vocabulary is defined.
design/design-system/component
Package component holds one type per shape the bentoo commands actually print.
 Package component holds one type per shape the bentoo commands actually print.
design/design-system/gallery command
Command gallery renders every component of the bentoo design system so the catalogue can be looked at rather than imagined.
 Command gallery renders every component of the bentoo design system so the catalogue can be looked at rather than imagined.
design/design-system/theme
Package theme is the vocabulary every bentoo component draws with: how much of the terminal a render may assume, which colour a role gets, and which glyph set is safe to emit.
 Package theme is the vocabulary every bentoo component draws with: how much of the terminal a render may assume, which colour a role gets, and which glyph set is safe to emit.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.