From 4de3c416cb17814217a5df4cf2d999e3838102a6 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Wed, 21 Oct 2026 09:46:54 +0200 Subject: Spec: version compare, hint column, Repository tab Packages gets a real version compare (new status newer: built ahead of the target, e.g. a dropped pin) and a hint column with a hint: query prefix. A new Repository tab reads slackrepo's built package repo from the local /repo mount: stats, published state, ChangeLog per package. Co-Authored-By: Claude Opus 5.5 --- .../2026-10-21-sb-builder-repository-design.md | 112 +++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/design/2026-10-21-sb-builder-repository-design.md diff --git a/docs/design/2026-10-21-sb-builder-repository-design.md b/docs/design/2026-10-21-sb-builder-repository-design.md new file mode 100644 index 0000000..45dc9a6 --- /dev/null +++ b/docs/design/2026-10-21-sb-builder-repository-design.md @@ -0,0 +1,112 @@ +# sb-builder: version compare, hint column, Repository tab + +Date: 2026-10-21 +Status: approved +Builds on: `2026-10-19-sb-builder-phase2-design.md`, `2026-10-20-sb-builder-ui-design.md` + +## Goal + +Three gaps found browsing the Packages tab: + +- A package's hint is visible only after selecting it: nothing in the list + says whether it has one, or whether it pins a version or only drops + shadowed deps. +- `outdated` is `built_version != version`. A package built at 1.4.5 whose + target is now 1.4.2 (a pin dropped from its hint) shows as `outdated`, + and Update would downgrade it. +- Nothing shows what slackrepo produced: the built package repository. + +## Facts + +- The inventory already carries `hint_path` and the parsed `hints` of each + row: the hint column needs no helper change. +- slackrepo's `PKGREPO` is `/repo` on the VM (virtiofs). The desktop sees + the same tree at the same path, `/repo` (a link to an NFS mount). It holds + `//---.txz`, plus the + gen_repos_files output at the top: `PACKAGES.TXT` (first line + `PACKAGES.TXT; `, then per package `PACKAGE NAME`, `PACKAGE + LOCATION`, both `PACKAGE SIZE` lines in K, `PACKAGE DESCRIPTION` with + `:` lines) and `ChangeLog.txt` (entries separated by + `+--------------------------+`, a date line, then + `//.txz: ` items, continuation lines + indented). On 2026-10-21: 546 packages, 4.8G. + +## Packages tab + +### Version compare + +`vercmp(a, b)` in `packages.py` returns -1, 0 or 1 (stdlib has no version +compare, `packaging` is third-party): + +- split each version into runs of digits and runs of letters; `.`, `_`, + `-`, `+` and `~` separate and are dropped; +- compare run by run: two digit runs numerically, two letter runs as + lower-cased strings, a digit run beats a letter run; +- when one side runs out: if the other continues with a pre-release word + (`alpha`, `beta`, `pre`, `rc`, `dev`) it is the older one + (`1.0rc1 < 1.0`), otherwise it is the newer one (`1.0.1 > 1.0`, + `4.3.5b > 4.3.5`); +- `ponytail:` comment: single-letter pre-releases (`1.0b1`) count as newer + than the release; snapshot versions (`20240101_ab12cd`) order by date, + their hash part orders arbitrarily. + +`status(row)`: `never` and `failed` as today, then by `vercmp(built, +version)`: `ok` (0), `outdated` (built older), `newer` (built newer than the +target). `STATUSES` gains `newer` with its own chip and colour. + +### Hint column + +New column `hint` after `built`, one word from the row's `hints`: + +- `skip`: `SKIP` set and not `no`; +- `pin`: `VERSION` set; +- `deps`: only `DELREQUIRES` and/or `ADDREQUIRES` (shadowed dep removal, + phantom deps); +- `other`: a hint with none of the above (ARCH, options...); +- empty: no hint. + +First match wins in that order. The cell tooltip lists the hint's keys. The +query gains a `hint:` prefix matching that word, plus `hint:none` for rows +without a hint. + +## Repository tab (`sb_builder/repository.py`) + +Local only, no ssh: works while the VM is off. + +- Config: `[repository] path`, default `/repo`. A missing or unreadable + path shows a one-line message in the tab, never a warning dialog. +- Loads on first show and on Refresh, off the GUI thread (NFS can be slow): + - walk `/*/*/*.t?z`: category, then name, version, arch and build + from the file name (the last three `-` fields are version, arch, build), + size and mtime from `stat`; + - `PACKAGES.TXT`: per `PACKAGE LOCATION`/`PACKAGE NAME`, the description + and the uncompressed size; its first line is the last publish time; + - `ChangeLog.txt`: entries per `category/pkg`, with their dates. +- Stats line above the table: packages, size on disk (sum of the `.txz`), + uncompressed total, last publish, counts per overlay (personal, + pentesting, upstream as in Packages), unpublished (a `.txz` on disk with + no matching `PACKAGE NAME` in `PACKAGES.TXT`). +- Table: name, version, build, category, size, date, published. Search + field (name and description), overlay chips and an `unpublished` chip, as + in Packages. No tick boxes: the tab has no change actions. +- Detail pane: description, both sizes, file path, the package's ChangeLog + entries newest first, and an "Open in Packages" link (navigation, as + "Open in Hints" is in Packages). +- Ribbon: no actions (Publish stays in Packages). View actions: Refresh. + +## Testing + +- `vercmp`: equal, numeric runs (`1.4.10 > 1.4.9`), pre-release + (`1.0rc1 < 1.0`), longer release (`1.0.1 > 1.0`), letter suffix + (`4.3.5b > 4.3.5`); `status` gives `newer` for built 1.4.5, target 1.4.2. +- Hint word for each case, `hint:` filter. +- Repository parsing against a temp tree with two `.txz`, a two-entry + `PACKAGES.TXT` (one listed, one not) and a short `ChangeLog.txt`: names, + versions, sizes, unpublished count, changelog entries. GUI test loads the + tab offscreen from that tree; a missing path shows the message. + +## Out + +Stale `.txz` whose SlackBuild left the repo, several versions of one +package side by side, file lists (`FILELIST.TXT`, `MANIFEST.bz2`), reading +the repository through the helper. -- cgit v1.2.3