# 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.
Column widths, sort order, splitter positions and the window size are kept
across runs in `~/.config/sb-builder/state.conf` (delete it to reset them; on
Wayland the compositor may still pick the window size).

## Usage

    sb-builder

The window has five tabs, always open: Dashboard, Packages, Hints, Results,
Jobs (Ctrl+PgUp/PgDn cycle them). The ribbon at the top holds the current
tab's actions, in the order a task uses them; the smaller bar under it holds
its view controls (select, clear, refresh). An action that does not apply is
greyed out, its tooltip says why. Actions act on the **ticked** rows: a click
anywhere on a row ticks or unticks it, Ctrl+A ticks every visible row,
Ctrl+Shift+A unticks all.

Starting a job keeps you where you are; the Jobs tab shows "(running)" and
then the end status. When a job you started ends, its next step comes to you
as a dialog: after a preview, its log with **Run it** (and a **publish** box);
after a hint change, the diff with **Revert** and **Build these**. **Not
now** loses nothing: **Run it** in the Jobs tab, on a finished preview,
reopens it.

- **Dashboard**: VM load, uptime and free disk, package counts, slackrepo
  build results, last overlay pull, recent jobs. Refreshes while visible.
  The tiles open Packages, Results (one result kind) and Jobs.
- **Packages**: 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, and **orphaned** for the packages SBo lists without a maintainer. The detail pane shows the package's versions, its dependencies after
  hints (dropped ones struck through), what its hint file does, and a link
  to it in Hints. **Build**, **Update**, **Rebuild**, **Remove** and **Update
  all** run a slackrepo `--preview` first; **New hint** creates hints, pinned
  at the `.info` version, for the ticked packages without one; **Publish**
  pushes the package repository (untick **publish** at Run it to hold a run
  back and publish later).
- **Hints**: 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; with
  **No download** on, `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`, revertable from
  the dialog that follows. **Phantom deps…** keeps the list of deps
  -current ships, which SBo packages still require (SBo drops a package once
  it is official): add names, or tick suggestions, the required names no
  package of the tree has; **Apply to hints** writes them into the
  `DELREQUIRES` of every package that requires them (sbshadow does the same
  after each sync). neovim is refused for now: its bundled deps still need
  mkhint on the VM.
- **Results**: 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).
- **Jobs**: every job with its live log. **Pull overlay** (`sbpull <overlay>`)
  and **Check shadowing** (`sbshadow`) run as previews; when one finds
  `shadow:` or `unshadow:` lines, its dialog offers **Apply shadowing**.
  **Kill** stops the selected running job.
- 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.