Docs ready to publish: VM setup, specs in docs/designHEADmaster

README says what the GUI does today and what is planned, which defaults
are the author's setup, and how to set up the VM. The specs move to
docs/design/; the implementation plans are dropped (working files, now
kept out of git). AGENTS.md links slackrepo upstream instead of a local
clone path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 292 insertions, 0 deletions

diff --git a/docs/design/2026-10-19-sb-builder-phase2-design.md b/docs/design/2026-10-19-sb-builder-phase2-design.md
new file mode 100644
index 0000000..e0eb794
--- /dev/null
+++ b/docs/design/2026-10-19-sb-builder-phase2-design.md
@@ -0,0 +1,292 @@
+# sb-builder phase 2: packages and slackrepo builds
+
+Date: 2026-10-19
+Status: approved
+Builds on: `2026-10-19-sb-builder-phase1-design.md` (helper, job model, GUI shell)
+
+## Goal
+
+Browse and search the ~10k packages of the SBo-danix tree, select packages
+and run slackrepo `build`, `rebuild`, `update` and `remove` on them, plus
+`update` of everything, as jobs. Every run is previewed first. Publishing
+(the rsync push of the package repository) can be held back per run and
+done later with a separate Publish action. Package signing works from the
+GUI although jobs have no terminal.
+
+## Facts this design rests on
+
+Verified on the VM and in the slackrepo source ([slackrepo](https://github.com/aclemons/slackrepo)):
+
+- slackrepo usage: `slackrepo {build|rebuild|update|remove} [--preview|--dry-run] [item...]`,
+  `--repo=SBo-danix`. Items may be bare package names.
+- `--preview` on build/update does **not** set `OPT_DRY_RUN` (only revert and
+  remove do, `libexec/functions.d/cmdfunctions.sh:231,398`). Finish hooks that
+  test only `OPT_DRY_RUN` still run during a preview: today `gotify_hook`
+  sends a message and `manage_packages_hook` runs without `--dry-run`.
+- The live config `/etc/slackrepo/slackrepo_SBo-danix.conf` defines start hook
+  `danix_gitfetch_hook` (fetch, rebase `danix-current` onto upstream; runs on
+  every invocation, previews included) and finish hooks
+  `manage_packages_hook bell_hook genrepos_hook gen_web_hook dep_template_hook rsync_push_hook recap_hook gotify_hook`.
+- `genrepos_hook` runs `gen_repos_files.sh`, which signs with gpg.
+  `/root/.genreprc` sets `USE_GPGAGENT=1` and `REPOSOWNERGPG=<fingerprint>`.
+  The agent uses `pinentry-curses` (needs a tty) with
+  `default-cache-ttl 14400`, `max-cache-ttl 21600`. With the key uncached
+  and no tty, `gen_repos_files.sh` aborts ("GPG test failed").
+- slackrepo DB (`database_SBo-danix_x86_64.sqlite3`): `revisions` row with
+  `dep='/'` holds the built `version` and `built` time per itemid
+  (`category/pkg`); `buildresults` holds the last `result` per itemid
+  (`ok`, `failed`, `bad`, `aborted`, `removed`). 213 of 799 `buildresults`
+  rows have legacy keys without a `/` and match no package.
+- Hints: 623 in `/etc/slackrepo/SBo-danix/hintfiles/`; the default hint dir
+  (`default_hintfiles/15.0`) is empty. Real usage: 594 `DELREQUIRES`, 13 each
+  of `VERSION`, `DOWNLOAD`, `MD5SUM`, `ARCH`, 1 `OPTIONS`.
+- Hint grammar (`libexec/functions.d/parsefunctions.sh:405-640`,
+  `man/man5/slackrepo.hint.5`): slackrepo searches `<SBREPO>/<cat>/<pkg>/`,
+  `HINTDIR/`, `HINTDIR/<cat>/<pkg>/`, `DEFAULT_HINTDIR/`,
+  `DEFAULT_HINTDIR/<cat>/<pkg>/` for `<pkg>.hint`, first match wins, and
+  sources it. Recognised keys: `SKIP VERSION OPTIONS GROUPADD USERADD
+  NOWARNING NOWARNINGS ADDREQUIRES DELREQUIRES BUILDTIME CONFLICTS INSTALL
+  NUMJOBS ANSWER CLEANUP PRAGMA SPECIAL ARCH DOWNLOAD MD5SUM SHA256SUM`, plus
+  `DOWNLOAD_<arch>`, `MD5SUM_<arch>`, `SHA256SUM_<arch>` resolved through
+  `ARCH`. The man page says `ANSWERS`; the code reads `ANSWER`.
+- mkhint `--no-dl` writes `NODOWNLOAD=yes`, which slackrepo does not read
+  (its switch is `DOWNLOAD="no"`). No current hint has it. Phase 4 changes
+  mkhint to write `DOWNLOAD="no"`.
+
+## Part 1: VM side, in the slackrepo_setup repo
+
+slackrepo_setup becomes the source of truth for the slackrepo config.
+
+- `slackrepo_SBo-danix.conf`: imported from the VM. Site values move out to
+  `/etc/slackrepo/SBo-danix.local` (root-only, mode 600, not in git), which the
+  config sources: rsync target, rsync password and excludes files, Gotify URL
+  and key. The repo ships `SBo-danix.local.example` with placeholders.
+- `sb-publish`: new script, the rsync push of `PKGREPO` that
+  `rsync_push_hook` does today. Reads its settings from the `.local` file.
+  `rsync_push_hook` calls it.
+- Gates in the config:
+  - `rsync_push_hook`: return 0 when `SBB_PUBLISH=n`.
+  - `gotify_hook`: return 0 when `OPT_PREVIEW=y` (as well as `OPT_DRY_RUN=y`).
+  - `manage_packages_hook`: pass `--dry-run` when `OPT_PREVIEW=y` too.
+- `gpg-agent.conf` for root, managed here: today's content plus
+  `allow-preset-passphrase`. Deploy runs `gpgconf --reload gpg-agent`.
+- Terminal runs without `SBB_PUBLISH` behave as today, except that previews
+  no longer notify Gotify or touch packages.
+- A stale untracked copy of the old config is deleted after asking the user.
+- Deploy (asks first): config to `/etc/slackrepo/`, `.local` created from the
+  current live values only if missing, `sb-publish` to `/usr/local/bin`,
+  `gpg-agent.conf` to `/root/.gnupg/`.
+
+## Part 2: helper (`sbb-remote` 0.2.0)
+
+### New config keys
+
+```toml
+slackrepo_repo = "SBo-danix"
+hintdir        = "/etc/slackrepo/SBo-danix/hintfiles"
+default_hintdir = ""          # optional, searched after hintdir
+genreprc       = "/root/.genreprc"
+```
+
+### `inventory`
+
+One JSON object `{"columns": [...], "rows": [[...], ...]}`, a row per
+package directory `<cat>/<pkg>/<pkg>.SlackBuild` in `repo_dir`:
+
+| column | source |
+|---|---|
+| `path` | `cat/pkg` |
+| `version` | hint `VERSION` if the hint has one, else `.info` `VERSION` |
+| `info_version` | `.info` `VERSION` |
+| `hint_version` | hint `VERSION` or `null` |
+| `built_version`, `built_time` | `revisions`, `dep='/'`, by path; `null` if none |
+| `result` | `buildresults` by path; `null` if none |
+| `maintainer`, `requires` | `.info` `MAINTAINER`, `REQUIRES` (list) |
+| `summary` | `slack-desc` line 1, text inside the parentheses |
+| `hint_path` | the hint found by slackrepo's search order (repo package dir, `hintdir`, `hintdir/<cat>/<pkg>`, `default_hintdir`, `default_hintdir/<cat>/<pkg>`), or `null` |
+| `hints` | `{key: raw value}` of every assignment in that hint, or `null` |
+
+`.info` and hint files are parsed, never sourced: continuation lines joined,
+then `shlex.split(line, comments=True)`, keeping `NAME=value` tokens. A
+value containing `$` is kept as written and flagged `"shell": true` for the
+GUI, since it would be expanded by the shell. A missing DB yields `null` build
+fields, not an error.
+
+### Job kinds
+
+| kind | argv | env |
+|---|---|---|
+| `slackrepo <action> [--preview] [--no-publish] [pkg...]` | `slackrepo --repo=<slackrepo_repo> <action> [--preview] pkg...` | `SBB_PUBLISH=n` with `--no-publish` |
+| `publish` | `sb-publish` | |
+
+- `action` is one of `build`, `rebuild`, `update`, `remove`.
+- Package names match `^[A-Za-z0-9._+-]+$` and must name a package in the
+  tree. Duplicates are dropped.
+- `build`, `rebuild`, `remove` need at least one package; `update` with none
+  means all.
+- Kinds now return `(argv, env)`; `_run` merges `env` into the environment.
+  Existing kinds return an empty env. `meta.json` records `env`.
+- While the signing key is locked, `job-start` refuses a non-preview
+  `slackrepo` job with `{"error": "signing key locked"}`. Previews and
+  `publish` (which does not sign) are not affected.
+
+### Signing key
+
+- Key: `REPOSOWNERGPG` read from `genreprc` with a regex over
+  `REPOSOWNERGPG="..."` (never sourced). Keygrips from
+  `gpg --with-colons --with-keygrip --list-secret-keys <key>` (`grp` lines).
+- `gpg-status`: `gpg-connect-agent "keyinfo <grip>" /bye` per keygrip; the key
+  is unlocked when every keygrip reports cached. Returns
+  `{"unlocked": bool, "key": "<fingerprint>"}`; `{"unlocked": null}` when no
+  key is configured.
+- `gpg-unlock`: reads the passphrase from stdin, runs
+  `gpg-preset-passphrase --preset <grip>` per keygrip with the passphrase on
+  its stdin, then verifies by signing a temp file with
+  `gpg --batch --pinentry-mode error -u <key> -bas`. On failure it runs
+  `gpg-preset-passphrase --forget` per keygrip and returns
+  `{"error": "bad passphrase"}`. The passphrase is never put on a command
+  line, in the environment, in a log or on disk.
+- Found 2026-10-20: the preset passphrase is lost when gpg-agent exits, and
+  it exits when root's last login session ends. elogind then removes
+  `/run/user/0` (root does not linger), where the agent's sockets live; the
+  agent notices its socket is gone and terminates. The GUI's ssh
+  ControlMaster keeps a session open while sb-builder runs, so the key stays
+  unlocked as long as the GUI does, and locks about 10 minutes after it
+  quits (ControlPersist). Accepted as is; `loginctl enable-linger root`
+  would keep the agent across sessions. The GUI checks state before every
+  real run either way.
+
+### Version
+
+`VERSION = "0.2.0"` in both helper and GUI; the existing banner asks for
+`./install.sh --remote` until the VM is updated.
+
+## Part 3: GUI
+
+### Packages tab (`sb_builder/packages.py`, `Open > Packages`)
+
+Layout B from brainstorming: query bar, chip rows, table, detail pane, action
+bar.
+
+- Model: `QAbstractTableModel` over the cached inventory, with a
+  `QSortFilterProxyModel` subclass doing the filtering. Columns: check, name,
+  category, version, built, status, maintainer. Sortable.
+- Status, derived in the GUI:
+
+  | status | rule |
+  |---|---|
+  | `never` | no `built_version` and no `result` |
+  | `failed` | `result` in `failed`, `bad`, `aborted` |
+  | `outdated` | `built_version` != `version` |
+  | `ok` | otherwise |
+
+  Shown as a colored glyph plus the word (status colors from the Dashboard).
+  `# ponytail:` outdated compares versions only; slackrepo also rebuilds on
+  SlackBuild or dependency changes, which its preview shows.
+- Query bar: whitespace-separated terms, all must match, case-insensitive
+  substring. Plain term: name or summary. `cat:`, `maint:`, `req:`,
+  `status:` match that field.
+- Chips: overlay group (`personal`, `pentesting`, `upstream` = any other
+  category) and status group (`ok`, `failed`, `never`, `outdated`). OR within
+  a group, AND across groups and with the query; an empty group does not
+  filter.
+- Detail pane for the current row: path, summary, `.info`, hint and built
+  versions, built time, last result, maintainer, and the hint view below.
+
+### Hint view (`sb_builder/hints.py`, in the detail pane)
+
+Read-only and structured; never the raw file. `hints.interpret(hints, info)`
+returns sections, the detail pane renders only those that apply:
+
+| section | keys | shown as |
+|---|---|---|
+| Skipped (banner) | `SKIP` | `no` = no banner; `yes` = always skipped; other text = skipped, the text as reason |
+| Version override | `VERSION`, `ARCH`, `DOWNLOAD[_arch]`, `MD5SUM[_arch]`, `SHA256SUM[_arch]` | `.info` version -> hint version; URLs after `ARCH` resolution (`DOWNLOAD_<ARCH>` wins when set); "checksums not checked" when `MD5SUM="no"` or `VERSION` set without `MD5SUM` (slackrepo forces `no`); "no download, source must be in the cache" for `DOWNLOAD="no"` and for `NODOWNLOAD=yes` (shown identically, by user decision) |
+| Dependencies | `.info` `REQUIRES`, `DELREQUIRES`, `ADDREQUIRES`, `BUILDTIME`, `PRAGMA python3`, `CONFLICTS` | one chip row computed as slackrepo does: `.info` deps minus `DELREQUIRES` and `%README%` (struck through), `python3` added by the pragma, `ADDREQUIRES` added (+), `BUILDTIME` added and marked build-time only (not in package metadata); `CONFLICTS` listed apart. With no `.info` `REQUIRES`, `ADDREQUIRES` alone defines the deps |
+| Build settings | `OPTIONS`, `NUMJOBS`, `INSTALL`, `ANSWER`, `NOWARNING`/`NOWARNINGS` | rows; `OPTIONS` split into `OPT=value` pairs; `INSTALL` as yes/no by its first letter (`Y`/`1`, `N`/`n`/`0`); `ANSWER` with `\n` shown as a return glyph; `NOWARNING` labelled as a regex |
+| Pragmas | `PRAGMA`, `SPECIAL` | one row per pragma with its meaning from `slackrepo.hint(5)`; `x86arch=<arch>` and `unset_<VAR>` parsed; unknown pragmas shown as unknown |
+| Host changes | `GROUPADD`, `USERADD` | table rows: gid, name; uid, name, group, home, shell, extra args, with slackrepo's defaults filled in (name = package, group = user, home `/dev/null`, shell `/bin/false`) |
+| On uninstall | `CLEANUP` | the command |
+| Ignored | any other key | "not read by slackrepo" (except `NODOWNLOAD`, see above) |
+
+Values flagged `shell` show as written, marked "expanded by the shell". The
+footer shows `hint_path`.
+- Selection: check column, "Select visible", "Clear", "N selected" label.
+  Actions apply to the checked packages, or to the current row when none is
+  checked.
+- Action bar: Build, Update, Rebuild, Remove, Update all, and Publish
+  (confirm dialog, starts the `publish` job).
+- Build/Update/Rebuild/Remove/Update all start the preview job
+  (`slackrepo <action> --preview ...`) and open it in the Jobs tab.
+- Inventory: fetched when the tab opens, on its Refresh button, and after any
+  `slackrepo` or `publish` job ends. While loading, the old rows stay and the
+  status line says "loading...".
+
+### Jobs tab additions
+
+- A finished `ok` preview of kind `slackrepo` shows [Run it] and a ☑ publish
+  checkbox (initial state from config `builds.publish`). Run it starts the
+  same action and packages without `--preview`, adding `--no-publish` when the
+  box is unticked.
+- Before starting any non-preview `slackrepo` job (Run it, or anywhere else)
+  the GUI calls `gpg-status`; when locked it asks for the passphrase
+  (`QInputDialog` in password mode), calls `gpg-unlock` with the passphrase on
+  stdin, repeats on `bad passphrase`, then starts the job. Cancel aborts.
+- `remote.call` gains an optional `stdin` bytes argument, written to the
+  QProcess and closed.
+
+### Main window and Dashboard
+
+- Status bar: signing key state, 🔒 locked / 🔓 unlocked, refreshed with the
+  stats poll; hidden when the helper reports no key.
+- Dashboard: clicking the Packages tile opens the Packages tab, clicking the
+  Recent jobs card opens the Jobs tab.
+- `Open` menu: Packages, Jobs.
+
+### GUI config
+
+```toml
+[builds]
+publish = true   # initial state of the publish checkbox
+```
+
+## Error handling
+
+| case | behaviour |
+|---|---|
+| inventory slow (cold disk ~7s) | async; old rows stay, "loading..." |
+| inventory call fails | status bar message, old rows stay |
+| preview fails | no [Run it]; the log says why |
+| key locked | password dialog; `bad passphrase` asks again; Cancel aborts |
+| `job-start` refuses (locked) | same dialog, then retry once |
+| busy | existing busy dialog |
+| `genrepos` fails anyway | job `failed`, notification, slackrepo's message in the log |
+| unknown package | helper rejects by name |
+
+## Testing
+
+stdlib `unittest`, headless, no VM.
+
+- Helper: `inventory` on a fake tree, hint dirs and sqlite DB (hint version
+  wins, hint search order precedence, shlex parsing with quotes, comments and
+  continuation lines, `$` values flagged, legacy DB keys ignored, missing DB
+  gives nulls);
+  `slackrepo` kind (unknown package, `build` without packages, `update`
+  without packages, duplicate names, `--no-publish` sets
+  `SBB_PUBLISH=n` in env and in the child process); locked key refuses a real
+  run, not a preview (gpg check patched); `gpg-unlock` feeds stdin to a fake
+  `gpg-preset-passphrase` on `PATH` and forgets on failed verification.
+- GUI: `hints.interpret` table-driven per key and derived rule (ARCH
+  resolution, forced checksum skip, dependency computation incl. python3
+  pragma and `ADDREQUIRES`-only, USERADD/GROUPADD defaults, SKIP forms,
+  INSTALL letters, `NODOWNLOAD` shown as `DOWNLOAD="no"`, ignored keys,
+  shell-flagged values); query parser and filter (prefixes, chips, OR/AND); status
+  derivation; action target is checked rows else current row; [Run it] after
+  an ok preview, with `--no-publish` when unticked; locked key opens the
+  dialog before the real job (dialog patched); Dashboard tile clicks open
+  tabs.
+- slackrepo_setup: `bash -n` on config and `sb-publish`; source the config
+  with stub `rsync`, `curl` and `manage-packages.sh` on `PATH` and check the
+  gates with and without `SBB_PUBLISH=n` and `OPT_PREVIEW=y`.
+- First real run with the user: unlock, preview an update of one package,
+  run it without publish, then Publish.