# sb-builder

Desktop GUI for managing a Slackware SlackBuilds build VM from one place. It
runs slackrepo builds, overlay syncs (sbpull, sbshadow), hint file updates
and SBo orphan discovery on the VM over ssh, as background jobs that
keep running when the GUI disconnects and can be reattached later. A
dashboard shows VM and repository state, and the GUI can start the VM through
libvirt when it is off.

Work in progress. See `docs/superpowers/specs/` for the design.

## Requirements

- Desktop: Python 3.11 or newer, PyQt6 (with QtDBus), ssh access to the VM,
  optionally `virsh` for starting the VM and `nvchecker` for upstream checks
- VM: Python 3.11 or newer, root ssh login, the
  [slackrepo_setup](https://forge.slackware.nl/danix/slackrepo_setup) tools (`sbpull`, `sbshadow`)

## Install

    ./install.sh             # ~/bin/sb-builder and menu entry -> this repo, GUI config if missing
    ./install.sh --remote    # helper to the VM, its config if missing (asks first)

`BINDIR` changes the launcher directory, `SBB_TARGET` the ssh destination for
`--remote` (default `buildsystem`). Configs:

- GUI: `~/.config/sb-builder/config.toml`, see `config.example.toml`
- VM: `/etc/sb-builder/config.toml`, see `remote/config.example.toml`

Every key is optional. `File > Reload config` rereads the GUI config.

## Usage

    sb-builder

- **Dashboard**: VM load, uptime and free disk, package counts, slackrepo
  build results, last overlay pull, recent jobs. Refreshes while visible.
- **Open > Jobs**: start a job from the Start menu (`sbpull <overlay>`
  preview, `sbshadow` preview or apply), follow its log live, kill it. After a
  preview that lists `shadow:` or `unshadow:` lines, "Apply shadowing" runs
  `sbshadow --yes`.

- **Open > Packages** (or click the Packages tile): every package of the
  repository, with built version and status (`ok`, `failed`, `never`,
  `outdated`). Search by name or summary, or with `cat:`, `maint:`, `req:`,
  `status:`; toggle the overlay and status chips. Ctrl+A ticks every visible
  package, Ctrl+Shift+A unticks all (here and in Hints). The detail pane shows the
  package's versions, its dependencies after hints (dropped ones struck
  through), and what its hint file does, section by section.
- Tick packages and press Build, Update, Rebuild or Remove (they act on the
  ticked packages only); Update all updates everything. Each first runs a slackrepo
  `--preview` job. When the preview is fine, **Run it** in the Jobs tab starts
  the real run; untick **publish** to keep the packages local and press
  **Publish** later to push them.
- **Results** (ribbon, or click a result in the Dashboard's slackrepo bar or
  legend): slackrepo's last build attempt per package, newest first, filterable
  by result. **Show build log** (or double-click) opens the end of the log of
  the package's last attempt (slackrepo keeps one per command: `build.log`,
  `update.log`, `rebuild.log`, `remove.log`), where it reports the failure,
  with its `resource.log` (load, memory, tmp over the build).
- **Hints** (ribbon): every package with a hint or an nvchecker stanza, with
  hint, `.info` and upstream version. **Check upstream** runs nvchecker on the
  desktop over `nvchecker.toml` in this repo (stanza name = package name, edit
  it by hand to track a package; `hints.nvchecker_keyfile` gives it a GitHub
  token) and ticks the outdated packages. **Update selected** rewrites their
  hints on the VM (version, URLs, md5 of the downloaded source; **no download**
  writes `DOWNLOAD="no"` instead; a hint sbshadow wrote, `DELREQUIRES` only,
  gets the `.info` version lines added). **Delete hint** removes the ticked
  packages' hints, each kept as a `.bak`. The Packages detail pane has **New hint** for a package
  without one.
- After a hint job or a delete a dialog shows the diff of each changed hint, with
  **Revert** per package and **Build these** (a slackrepo update preview).
  neovim and openvino are refused for now: their bundled deps still need
  mkhint on the VM.
- Real runs sign the repository. When the package signing key is locked
  (status bar 🔒), the GUI asks for its passphrase first and hands it to the
  VM's gpg-agent; it is never stored.

Jobs run on the VM detached from the ssh session, one at a time. Closing the
GUI or losing the connection does not stop them; reopening the job resumes
the log. Job state and logs live in `/var/lib/sb-builder/jobs/` on the VM.

When ssh fails and `vm.domain` is set, the status bar shows the libvirt state
of the VM and offers to start or resume it. Desktop notifications report
finished, failed, killed and lost jobs, and the VM coming up.

## License

Copyright (C) 2026 Danilo M. <danix@danix.xyz>

GPLv2 only. See [LICENSE](LICENSE) for the full text.

## Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.