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 <noreply@anthropic.com>

1 files changed, 112 insertions, 0 deletions

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
+  `<category>/<pkg>/<pkg>-<version>-<arch>-<build>.txz`, plus the
+  gen_repos_files output at the top: `PACKAGES.TXT` (first line
+  `PACKAGES.TXT;  <date>`, then per package `PACKAGE NAME`, `PACKAGE
+  LOCATION`, both `PACKAGE SIZE` lines in K, `PACKAGE DESCRIPTION` with
+  `<pkg>:` lines) and `ChangeLog.txt` (entries separated by
+  `+--------------------------+`, a date line, then
+  `<category>/<pkg>/<file>.txz: <text>` 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 `<path>/*/*/*.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.