Initial commit: sbo-batch-test

Batch-test SlackBuilds against a clean Slackware 15.0 overlay chroot.
Non-interactive, local-tree-only dependency resolution with topological
sort, per-target disposable overlay, persistent per-package logs, and a
color summary.

Includes README.md, CLAUDE.md working notes, the reference overlay-chroot.sh,
the original spec, and test-logic.sh (resolver + BLOCKED-BY-DEP self-check,
12 checks passing).

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

1 files changed, 161 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b98197a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,161 @@
+# sbo-batch-test
+
+Batch-test SlackBuilds against a clean Slackware 15.0 overlay chroot.
+
+Resolves the full SBo dependency tree (locally, never network), topologically
+sorts it, builds and installs every package in a fresh disposable overlay over
+a read-only 15.0 base, captures persistent per-package logs, and prints a
+color-coded summary.
+
+Built for an SBo maintainer whose daily driver is Slackware64-current but whose
+packages target 15.0 stable. It verifies that SlackBuilds BUILD and install
+cleanly against the 15.0 userland/toolchain/libraries, which is where
+current-vs-15.0 drift bites.
+
+## Scope and limits
+
+- Shares the host kernel (the current VM's kernel, not a 15.0 kernel). It does
+  NOT test kernel-module packages or anything tied to the running kernel
+  version. Those still want a real 15.0 VM.
+- Resolution is LOCAL-tree-only. No network, no sbopkg. The local SBo tree is
+  the single source of truth (it contains unpublished personal/pentesting
+  packages that do not exist upstream).
+- Does not integrate with, wrap, or drive slackrepo. Separate, independent tool.
+- Built packages are throwaway. The point is "does it build on clean 15.0",
+  not producing redistributable output.
+
+## Prerequisites
+
+You need three things in place, all configured in the CONFIG block at the top
+of `sbo-batch-test`:
+
+1. **`SLACKWARE_BASE`** - a LOCAL (non-NFS) full Slackware 15.0 install tree.
+   This is the overlay lowerdir. It MUST be local (ext4/xfs). overlayfs over an
+   NFS lowerdir is fragile and a known source of intermittent failures.
+
+2. **`LOCAL_MIRROR_15`** - the NFS-mounted Slackware 15.0 mirror. Used only as a
+   package SOURCE to populate and patch `SLACKWARE_BASE`. Read-only is fine.
+
+3. **`SBO_TREE_ROOTS`** - one or more LOCAL SBo tree roots, resolved in order
+   (first match wins). Standard SBo layout
+   `<root>/<category>/<prog>/{prog.SlackBuild,prog.info,...}`. Read in place,
+   never copied or synced.
+
+Also: run as root (overlay + chroot require it).
+
+## Populating SLACKWARE_BASE
+
+Populate from the NFS mirror with the FULL package set, not a minimal install.
+A minimal base causes false "missing dependency" results that would not happen
+on a normal user's full Slackware install.
+
+```sh
+mkdir -p /sbo-base/15.0
+for p in /mnt/nfs/slackware64-15.0/slackware64/*/*.t?z; do
+  installpkg --root /sbo-base/15.0 "$p"
+done
+```
+
+Adjust the two paths to your `SLACKWARE_BASE` and `LOCAL_MIRROR_15`. The tool
+will not auto-bootstrap the base unattended; if the base is missing or
+incomplete it fails fast with this exact hint.
+
+The base is kept patched automatically on each run: when the mirror's
+ChangeLog head differs from the recorded marker, new packages from
+`patches/packages/` are applied to the local base via `upgradepkg`.
+
+## Usage
+
+```
+sbo-batch-test [OPTIONS] <program-name>
+sbo-batch-test [OPTIONS] <category-folder>
+```
+
+### Single-package mode
+
+Resolve a program's full dep tree, build+install every dep in order, then the
+target. The whole chain shares ONE overlay, torn down at the end.
+
+```sh
+sbo-batch-test playwright-cli
+```
+
+### Category-folder mode
+
+Every SlackBuild dir inside the folder is an independent target. Each target
+gets its OWN fresh overlay against pristine 15.0, so one target's installed
+deps never leak into the next. Deps may live in other categories.
+
+```sh
+sbo-batch-test ./network
+sbo-batch-test /path/to/SBo-danix/pentesting
+```
+
+### Dry run
+
+Resolve and print the build order, build nothing.
+
+```sh
+sbo-batch-test --dry-run playwright-cli
+```
+
+### Options
+
+| Option            | Effect                                                       |
+|-------------------|--------------------------------------------------------------|
+| `-h`, `--help`    | Usage text.                                                  |
+| `--no-color`      | Disable ANSI color (auto-disabled when stdout is not a TTY). |
+| `--dry-run`       | Resolve and print build order, do not build.                 |
+| `--with-x`        | Enable X passthrough (`xhost +local:hosts`). Headless by default. Security caveat: allows local non-network connections to your X server. |
+| `-j`, `--jobs N`  | Reserved. No-op stub today (builds are serial).              |
+
+## Per-package status values
+
+| Status           | Meaning                                                   |
+|------------------|-----------------------------------------------------------|
+| `SUCCESS`        | Built and installed.                                      |
+| `DOWNLOAD-FAILED`| Source download failed.                                   |
+| `MD5-MISMATCH`   | Source MD5 did not match the .info. Hard failure.         |
+| `BUILD-FAILED`   | The .SlackBuild failed or produced no package.            |
+| `INSTALL-FAILED` | `installpkg` of the resulting package failed.             |
+| `BLOCKED-BY-DEP` | A dependency failed, so this was not attempted.           |
+| `UNMET-DEP`      | A required package is neither in the SBo tree nor in base. Also covers dependency cycles. |
+
+Packages whose REQUIRES carry `%README%` are flagged in the summary as a
+reminder to check manual/optional configuration steps. `%README%` is not a
+package and is skipped for build ordering.
+
+## Logs
+
+Written outside the overlay so they survive teardown, under `LOG_ROOT`:
+
+```
+$LOG_ROOT/2026-06-22_14-30-05/
+  <category>_<prog>.log   per-package full build/install output
+  summary.log             plain-text recap (same facts as the screen summary, no color)
+  build-order.txt         the resolved topological order actually used
+```
+
+Each per-package log captures the full build/install output, the resolved
+`.info` build context (PRGNAM/VERSION/BUILD/TAG/REQUIRES), and the installed
+file list from the package db. That is everything worth inspecting, so the
+overlay is always disposed and there is no keep-overlay option.
+
+## Design tradeoffs (on the record)
+
+- **Shared deps are rebuilt per target.** Each category target starts from a
+  clean base, so a dep shared by N targets is rebuilt N times. Correct for
+  isolation, slow for heavy shared deps (qt5, boost). A future optional
+  package-output cache (keep built `.tgz` outside the overlay, `installpkg` a
+  cached dep when its SlackBuild + version are unchanged) is marked TODO in the
+  source, not yet implemented.
+- **overlayfs sharp edges.** A build that fails ONLY in the overlay but works on
+  bare 15.0 is more likely an overlayfs quirk (rename/whiteout) than a real
+  build bug. Noted near the build step in the source.
+
+## Reference
+
+Overlay/chroot mount + teardown machinery follows the patterns in
+`overlay-chroot.sh` by Jeremy Hansen (bassmadrigal). The teardown ordering
+(pts, dev/proc/sys, resolv.conf, dbus machine-id, overlay last) is preserved
+deliberately.