path: root/docs/plans/2026-07-13-image-builder.md

# sbo-testbuild image builder — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the three chained bash scripts that produce `sbo-testbuild:current` / `sbo-testbuild:15.0` docker images from NAS Slackware trees and push them to a LAN registry, consumed by `.extras/test-build`.

**Architecture:** Adapt the forge `slackware/docker-images` scripts (`bootstrap.sh`, `build-full-image.sh`) into `.extras/image-builder/`. Add a third `build-sbo-testbuild.sh` layer. Share config + helpers via `config` and `lib.sh`. Pure-logic helpers are unit-tested with an assert-based self-check; the docker chain is verified manually on the VM.

**Tech Stack:** bash, docker, slackpkg/installpkg (Slackware), `registry:2`.

**Reference:** design spec at `.extras/docs/specs/2026-07-13-image-builder-design.md`. Forge originals cloned at (scratchpad) `docker-images/scripts/` — re-clone with `git clone slackware_forge:slackware/docker-images.git` if gone.

---

## File Structure

```
.extras/image-builder/
├── config                    REGISTRY, MIRROR, VARIANTS, PKGDIR (sourced by all)
├── lib.sh                    _log/_warn/_err, fetch(), txz_hash(), require_mount()
├── bootstrap.sh              base image FROM scratch (root; installpkg from NAS)
├── build-full-image.sh       full image FROM base (slackpkg all series)
├── build-sbo-testbuild.sh    testbuild image FROM full (installpkg sbopkg + tools)
├── test-image-builder.sh     assert-based self-check for lib.sh logic
└── README                    VM-side setup checklist
```

Responsibilities:
- **config** — the only place hostnames/paths/variants live. No script hardcodes them.
- **lib.sh** — all shared, testable logic. Sourced by the three build scripts and by the test. No side effects at source time (only function defs + nothing else).
- **bootstrap/full/testbuild** — one image each, thin: guard, gate, generate Dockerfile, build, push.
- **test-image-builder.sh** — sources lib.sh, exercises fetch/txz_hash/require_mount with asserts. No docker.

---

## Task 1: config + lib.sh skeleton

**Files:**
- Create: `.extras/image-builder/config`
- Create: `.extras/image-builder/lib.sh`

- [ ] **Step 1: Write config**

Create `.extras/image-builder/config`:

```sh
# Shared configuration for the sbo-testbuild image builder.
# Sourced by bootstrap.sh, build-full-image.sh, build-sbo-testbuild.sh, tests.

REGISTRY="docker.noland.dnx:5000"
MIRROR="file:///mnt/nas"
VARIANTS=(current 15.0)              # x86_64 only for now
PKGDIR="/opt/sbo-testbuild/pkgs"     # sbopkg + sbo-maintainer-tools .txz
HASH_DIR="/var/cache/sbo-testbuild"  # ChangeLog hashes for rebuild gating
```

- [ ] **Step 2: Write lib.sh with logging + require_mount**

Create `.extras/image-builder/lib.sh`:

```sh
# Shared helpers for the image builder. Source, do not execute.
# Sourcing must have no side effects beyond defining functions.

_log()  { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [${LOG_TAG:-image-builder}] $*"; }
_warn() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [${LOG_TAG:-image-builder}] WARNING: $*" >&2; }
_err()  { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [${LOG_TAG:-image-builder}] ERROR: $*" >&2; exit 1; }

# mirror_path MIRROR RELPATH
# Join a MIRROR (file:///... or http(s)://...) with a relative path.
mirror_path() {
    local mirror="$1" rel="$2"
    printf '%s/%s' "${mirror%/}" "${rel#/}"
}

# is_local_mirror MIRROR -> 0 if file:// or bare absolute path, else 1
is_local_mirror() {
    case "$1" in
        file://*) return 0 ;;
        http://*|https://*) return 1 ;;
        /*) return 0 ;;
        *) return 1 ;;
    esac
}

# strip_scheme URL -> filesystem path for a file:// or bare-local URL
strip_scheme() {
    local u="$1"
    case "$u" in
        file://*) printf '%s' "${u#file://}" ;;
        *) printf '%s' "$u" ;;
    esac
}

# fetch SRC DEST
# Copy SRC (a full mirror URL) to DEST. Local mirror -> cp, http -> curl.
# Returns non-zero on failure; caller decides whether that is fatal.
fetch() {
    local src="$1" dest="$2"
    if is_local_mirror "$src"; then
        local path; path="$(strip_scheme "$src")"
        [[ -f "$path" ]] || return 1
        cp "$path" "$dest"
    else
        curl -sSfL --connect-timeout 60 "$src" -o "$dest"
    fi
}

# txz_hash DIR
# Stable hash of the set of .txz files in DIR (names + contents), order
# independent. Empty/absent dir -> empty string.
txz_hash() {
    local dir="$1"
    [[ -d "$dir" ]] || { printf ''; return 0; }
    local files; files=$(find "$dir" -maxdepth 1 -name '*.txz' -type f | sort)
    [[ -n "$files" ]] || { printf ''; return 0; }
    # Hash sorted "name  sha256" lines so reordering does not change output.
    while IFS= read -r f; do
        printf '%s  %s\n' "$(basename "$f")" "$(sha256sum "$f" | cut -d' ' -f1)"
    done <<< "$files" | sha256sum | cut -d' ' -f1
}

# require_mount VERSION
# Assert the NAS tree for VERSION is mounted (file:// mirror only).
# x86_64 tree dir is slackware64-${VERSION}.
require_mount() {
    local version="$1"
    is_local_mirror "$MIRROR" || return 0   # http mirror: nothing to check
    local base; base="$(strip_scheme "$MIRROR")"
    local dir="${base}/slackware64-${version}"
    [[ -d "$dir" ]] || _err "NAS tree not mounted: ${dir}"
}
```

- [ ] **Step 3: Commit**

```bash
git add .extras/image-builder/config .extras/image-builder/lib.sh
git commit -m 'image-builder: config + lib.sh helpers'
```

---

## Task 2: lib.sh self-check

**Files:**
- Create: `.extras/image-builder/test-image-builder.sh`

- [ ] **Step 1: Write the test**

Create `.extras/image-builder/test-image-builder.sh`:

```sh
#!/bin/bash
# Assert-based self-check for lib.sh pure logic. No docker, no network.
# Run: bash .extras/image-builder/test-image-builder.sh
set -u
cd "$(dirname "$0")"
source ./lib.sh

pass=0 fail=0
check() { # DESC EXPECTED ACTUAL
    if [[ "$2" == "$3" ]]; then pass=$((pass+1));
    else fail=$((fail+1)); echo "FAIL: $1"; echo "  expected: [$2]"; echo "  actual:   [$3]"; fi
}
check_rc() { # DESC EXPECTED_RC ACTUAL_RC
    if [[ "$2" == "$3" ]]; then pass=$((pass+1));
    else fail=$((fail+1)); echo "FAIL: $1 (rc expected $2 got $3)"; fi
}

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT

# --- mirror_path ---
check "mirror_path trailing slash" \
    "file:///mnt/nas/slackware64-current/PACKAGES.TXT" \
    "$(mirror_path 'file:///mnt/nas/' 'slackware64-current/PACKAGES.TXT')"
check "mirror_path no trailing slash" \
    "file:///mnt/nas/x/y" "$(mirror_path 'file:///mnt/nas' '/x/y')"

# --- is_local_mirror ---
is_local_mirror "file:///mnt/nas"; check_rc "is_local file://" 0 $?
is_local_mirror "/mnt/nas";        check_rc "is_local bare abs" 0 $?
is_local_mirror "https://x/y";     check_rc "is_local https" 1 $?

# --- strip_scheme ---
check "strip_scheme file://" "/mnt/nas" "$(strip_scheme 'file:///mnt/nas')"
check "strip_scheme bare" "/mnt/nas" "$(strip_scheme '/mnt/nas')"

# --- fetch: local file resolves ---
echo hello > "$tmp/src.txt"
fetch "file://$tmp/src.txt" "$tmp/dst.txt"; check_rc "fetch local ok" 0 $?
check "fetch local content" "hello" "$(cat "$tmp/dst.txt" 2>/dev/null)"

# --- fetch: missing local file errors ---
fetch "file://$tmp/nope.txt" "$tmp/x.txt"; check_rc "fetch local missing" 1 $?

# --- txz_hash: stable + content-sensitive ---
mkdir -p "$tmp/pkgs"
printf a > "$tmp/pkgs/sbopkg-1.txz"
printf b > "$tmp/pkgs/tools-1.txz"
h1="$(txz_hash "$tmp/pkgs")"
h2="$(txz_hash "$tmp/pkgs")"
check "txz_hash stable" "$h1" "$h2"
printf c > "$tmp/pkgs/tools-1.txz"   # change content
h3="$(txz_hash "$tmp/pkgs")"
check_rc "txz_hash changes on content" 0 "$([[ "$h1" != "$h3" ]] && echo 0 || echo 1)"
check "txz_hash empty dir" "" "$(txz_hash "$tmp/empty-nope")"

# --- require_mount: missing mount errors (subshell to catch _err exit) ---
MIRROR="file://$tmp/no-such-root"
( require_mount current ) 2>/dev/null; check_rc "require_mount missing" 1 $?
mkdir -p "$tmp/mnt/slackware64-current"
MIRROR="file://$tmp/mnt"
( require_mount current ) 2>/dev/null; check_rc "require_mount present" 0 $?
MIRROR="https://example/x"
( require_mount current ) 2>/dev/null; check_rc "require_mount http skips" 0 $?

echo "----"
echo "PASS: $pass  FAIL: $fail"
[[ "$fail" -eq 0 ]]
```

- [ ] **Step 2: Run — expect PASS**

Run: `bash .extras/image-builder/test-image-builder.sh`
Expected: final line `PASS: N  FAIL: 0`, exit 0.

If any FAIL, fix `lib.sh` (the test encodes the intended behavior).

- [ ] **Step 3: Commit**

```bash
git add .extras/image-builder/test-image-builder.sh
git commit -m 'image-builder: lib.sh self-check'
```

---

## Task 3: bootstrap.sh (base image)

**Files:**
- Create: `.extras/image-builder/bootstrap.sh`
- Reference: forge `docker-images/scripts/bootstrap.sh`

This is the forge `bootstrap.sh` adapted: source `config`+`lib.sh`, drop i586,
`file://` fetch via `fetch()`, LAN registry, `sbo-base` name, mount guard.

- [ ] **Step 1: Write bootstrap.sh**

Create `.extras/image-builder/bootstrap.sh`. Start from the forge original and apply exactly these changes; everything else (the `download_pkgtxt`, `find_package`, rootfs configuration, cleanup, Dockerfile-from-scratch blocks) is copied verbatim from the forge script:

1. Header block:

```sh
#!/bin/bash
# bootstrap.sh — build the sbo-base:{ver} image FROM scratch from NAS trees.
# Run as root (installpkg). Adapted from forge slackware/docker-images.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
source "${HERE}/config"
LOG_TAG=bootstrap
source "${HERE}/lib.sh"

REGISTRY_IMAGE="${REGISTRY}/sbo-base"
[[ "${EUID}" -eq 0 ]] || _err "run as root."
mkdir -p "${HASH_DIR}"
```

2. Argument parsing: keep `--force` and `--version` only; **remove `--arch`**
   (x86_64 fixed). Variant list comes from config:

```sh
FORCE=false
OPT_VERSION=""
while [[ $# -gt 0 ]]; do
    case "$1" in
        --version) OPT_VERSION="$2"; shift 2 ;;
        --force)   FORCE=true;       shift   ;;
        *) _err "unknown argument: $1" ;;
    esac
done
if [[ -n "${OPT_VERSION}" ]]; then
    BUILD_VARIANTS=("${OPT_VERSION}")
else
    BUILD_VARIANTS=("${VARIANTS[@]}")
fi
```

3. Copy the forge `PACKAGES=( ... )` array verbatim (lines 80–187 of the forge
   original — the full base package list).

4. Replace `changelog_changed`: read ChangeLog via `fetch` from the NAS,
   x86_64-only repo key:

```sh
# changelog_changed VERSION -> 0 if changed (or --force), else 1
changelog_changed() {
    local version="$1"
    local repo_key="slackware64-${version}"
    local hash_file="${HASH_DIR}/${repo_key}.sha256"
    local url; url="$(mirror_path "${MIRROR}" "${repo_key}/ChangeLog.txt")"
    local tmp; tmp="$(mktemp)"
    if ! fetch "${url}" "${tmp}"; then
        rm -f "${tmp}"
        _warn "${repo_key}: cannot read ChangeLog (${url}); skipping."
        return 1
    fi
    local live; live=$(sha256sum "${tmp}" | cut -d' ' -f1); rm -f "${tmp}"
    if [[ "${FORCE}" == "true" ]]; then
        echo "${live}" > "${hash_file}"; return 0
    fi
    local stored=""; [[ -f "${hash_file}" ]] && stored=$(cat "${hash_file}")
    if [[ "${live}" == "${stored}" ]]; then
        _log "${repo_key}: ChangeLog unchanged; skipping."; return 1
    fi
    _log "${repo_key}: ChangeLog changed."; echo "${live}" > "${hash_file}"; return 0
}
```

5. Copy `download_pkgtxt` and `find_package` verbatim from the forge original,
   but change the two `curl -sfL ... "${URL}" -o "${DEST}"` download lines in
   `download_pkgtxt` to `fetch "${URL}" "${DEST}"` (drops the http assumption).

6. `build_variant`: take `VERSION` only (no ARCH). Set:

```sh
build_variant() {
    local VERSION="$1"
    require_mount "${VERSION}"
    local REPO_KEY="slackware64-${VERSION}"
    local PKG_PATH; PKG_PATH="$(mirror_path "${MIRROR}" "${REPO_KEY}")"
    local TAG="${REGISTRY_IMAGE}:${VERSION}"
    local SLACKPKG_MIRROR="https://slackware.nl/slackware/slackware64-${VERSION}/"
    ...
}
```

   The `SLACKPKG_MIRROR` written into the image stays an https slackware.nl URL
   (it is used later by slackpkg inside the container, which has internet; the
   NAS `file://` mount only feeds the host-side build). Keep the rest of the
   forge `build_variant` body verbatim, except:
   - the package **download loop** uses `fetch "${URL}" "${PKGCACHE}/${FILENAME}"`
     instead of `curl`.
   - the final `docker build ... && docker push` targets `${TAG}` as above.

7. Main loop over `BUILD_VARIANTS`, one arg:

```sh
for VERSION in "${BUILD_VARIANTS[@]}"; do
    if changelog_changed "${VERSION}"; then
        build_variant "${VERSION}"
    fi
done
```

- [ ] **Step 2: Syntax check**

Run: `bash -n .extras/image-builder/bootstrap.sh`
Expected: no output, exit 0.

- [ ] **Step 3: shellcheck (if available)**

Run: `shellcheck -x .extras/image-builder/bootstrap.sh || true`
Expected: no errors (warnings about unreachable `_err` exit are fine). If shellcheck absent, skip.

- [ ] **Step 4: Commit**

```bash
git add .extras/image-builder/bootstrap.sh
git commit -m 'image-builder: bootstrap.sh base image from NAS'
```

---

## Task 4: build-full-image.sh

**Files:**
- Create: `.extras/image-builder/build-full-image.sh`
- Reference: forge `docker-images/scripts/build-full-image.sh`

Forge `build-full-image.sh` adapted: source config+lib, drop i586, LAN
registry, `sbo-base`→`sbo-full` names.

- [ ] **Step 1: Write build-full-image.sh**

Create `.extras/image-builder/build-full-image.sh`. From the forge original, apply exactly:

1. Header:

```sh
#!/bin/bash
# build-full-image.sh — sbo-full:{ver} FROM sbo-base:{ver}, all series.
# Adapted from forge slackware/docker-images. No root needed.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
source "${HERE}/config"
LOG_TAG=full
source "${HERE}/lib.sh"

BASE_IMAGE="${REGISTRY}/sbo-base"
FULL_IMAGE="${REGISTRY}/sbo-full"
DIGEST_LABEL="sbo.full.base-digest"
```

2. Arg parsing: `--force` and `--version` only (no `--arch`), variant list from
   config — identical shape to bootstrap Task 3 Step 1.2, but `BUILD_VARIANTS`.

3. `derive_tags VERSION`:

```sh
derive_tags() {
    local VERSION="$1"
    BASE_TAG="${BASE_IMAGE}:${VERSION}"
    FULL_TAG="${FULL_IMAGE}:${VERSION}"
}
```

4. Keep `needs_rebuild` verbatim from the forge original (it already takes
   BASE_TAG/FULL_TAG args and uses `_log`/`_warn`/`FORCE`).

5. `build_variant VERSION`: drop the ARCH/ARCH_SUFFIX lines; call
   `derive_tags "${VERSION}"`. Keep the forge Dockerfile heredoc **verbatim**
   (the `slackpkg update` + all-series install + cleanup + labels). Only the
   `LABEL org.opencontainers.image.title/description` strings lose the
   `(${ARCH})` suffix; leave them or hardcode `(x86_64)`.

6. Main loop over `BUILD_VARIANTS`:

```sh
for VERSION in "${BUILD_VARIANTS[@]}"; do
    build_variant "${VERSION}"
done
```

- [ ] **Step 2: Syntax check**

Run: `bash -n .extras/image-builder/build-full-image.sh`
Expected: exit 0.

- [ ] **Step 3: shellcheck (if available)**

Run: `shellcheck -x .extras/image-builder/build-full-image.sh || true`

- [ ] **Step 4: Commit**

```bash
git add .extras/image-builder/build-full-image.sh
git commit -m 'image-builder: build-full-image.sh'
```

---

## Task 5: build-sbo-testbuild.sh

**Files:**
- Create: `.extras/image-builder/build-sbo-testbuild.sh`

New script (no forge equivalent). FROM sbo-full, installpkg the two .txz,
gate on full digest AND .txz-set hash.

- [ ] **Step 1: Write build-sbo-testbuild.sh**

Create `.extras/image-builder/build-sbo-testbuild.sh`:

```sh
#!/bin/bash
# build-sbo-testbuild.sh — sbo-testbuild:{ver} FROM sbo-full:{ver}.
# Adds sbopkg + sbo-maintainer-tools from prebuilt .txz in PKGDIR.
# Rebuilds when the full image OR the .txz set changes.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
source "${HERE}/config"
LOG_TAG=testbuild
source "${HERE}/lib.sh"

FULL_IMAGE="${REGISTRY}/sbo-full"
TB_IMAGE="${REGISTRY}/sbo-testbuild"
DIGEST_LABEL="sbo.testbuild.full-digest"
PKGS_LABEL="sbo.testbuild.pkgs-hash"

FORCE=false
OPT_VERSION=""
while [[ $# -gt 0 ]]; do
    case "$1" in
        --version) OPT_VERSION="$2"; shift 2 ;;
        --force)   FORCE=true;       shift   ;;
        *) _err "unknown argument: $1" ;;
    esac
done
if [[ -n "${OPT_VERSION}" ]]; then
    BUILD_VARIANTS=("${OPT_VERSION}")
else
    BUILD_VARIANTS=("${VARIANTS[@]}")
fi

# Verify the required .txz are present before doing anything.
require_pkgs() {
    [[ -d "${PKGDIR}" ]] || _err "PKGDIR missing: ${PKGDIR}"
    compgen -G "${PKGDIR}/sbopkg-*.txz" >/dev/null \
        || _err "no sbopkg-*.txz in ${PKGDIR}"
    compgen -G "${PKGDIR}/sbo-maintainer-tools-*.txz" >/dev/null \
        || _err "no sbo-maintainer-tools-*.txz in ${PKGDIR}"
}

# needs_rebuild FULL_TAG TB_TAG PKGS_HASH -> 0 if rebuild needed
needs_rebuild() {
    local full_tag="$1" tb_tag="$2" pkgs_hash="$3"
    [[ "${FORCE}" == "true" ]] && { _log "  --force."; return 0; }

    local full_digest
    full_digest=$(docker inspect --format '{{index .RepoDigests 0}}' \
        "${full_tag}" 2>/dev/null || echo "")
    [[ -n "${full_digest}" ]] || { _warn "  no full digest; rebuilding."; return 0; }

    local rec_digest rec_pkgs
    rec_digest=$(docker inspect \
        --format "{{index .Config.Labels \"${DIGEST_LABEL}\"}}" \
        "${tb_tag}" 2>/dev/null || echo "")
    rec_pkgs=$(docker inspect \
        --format "{{index .Config.Labels \"${PKGS_LABEL}\"}}" \
        "${tb_tag}" 2>/dev/null || echo "")

    if [[ "${full_digest}" == "${rec_digest}" && "${pkgs_hash}" == "${rec_pkgs}" ]]; then
        _log "  full image and .txz set unchanged; skipping."
        return 1
    fi
    _log "  full image or .txz set changed; rebuilding."
    return 0
}

build_variant() {
    local VERSION="$1"
    local FULL_TAG="${FULL_IMAGE}:${VERSION}"
    local TB_TAG="${TB_IMAGE}:${VERSION}"
    _log "=== ${TB_TAG} ==="

    _log "  Pulling ${FULL_TAG}..."
    docker pull "${FULL_TAG}"

    local PKGS_HASH; PKGS_HASH="$(txz_hash "${PKGDIR}")"

    if ! needs_rebuild "${FULL_TAG}" "${TB_TAG}" "${PKGS_HASH}"; then
        return 0
    fi

    local FULL_DIGEST
    FULL_DIGEST=$(docker inspect --format '{{index .RepoDigests 0}}' "${FULL_TAG}")

    local WORKDIR; WORKDIR="$(mktemp -d /tmp/sbo-testbuild.XXXXXX)"
    trap "rm -rf '${WORKDIR}'" RETURN
    mkdir -p "${WORKDIR}/pkgs"
    cp "${PKGDIR}"/sbopkg-*.txz "${PKGDIR}"/sbo-maintainer-tools-*.txz "${WORKDIR}/pkgs/"

    cat > "${WORKDIR}/Dockerfile" <<DOCKERFILE
FROM ${FULL_TAG}
LABEL maintainer="danix <danix@danix.xyz>"
COPY pkgs/*.txz /tmp/pkgs/
RUN installpkg /tmp/pkgs/*.txz && rm -rf /tmp/pkgs
RUN /sbin/ldconfig
LABEL org.opencontainers.image.created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
LABEL org.opencontainers.image.title="SBo test-build env ${VERSION} (x86_64)"
LABEL org.opencontainers.image.description="Slackware ${VERSION} full + sbopkg + sbo-maintainer-tools"
LABEL slackware.version="${VERSION}"
LABEL ${DIGEST_LABEL}="${FULL_DIGEST}"
LABEL ${PKGS_LABEL}="${PKGS_HASH}"
CMD ["/bin/bash"]
DOCKERFILE

    local BUILD_FLAGS=()
    [[ "${FORCE}" == "true" ]] && BUILD_FLAGS+=(--no-cache)
    _log "  Building ${TB_TAG}..."
    docker build "${BUILD_FLAGS[@]}" -t "${TB_TAG}" "${WORKDIR}"
    _log "  Pushing ${TB_TAG}..."
    docker push "${TB_TAG}"
    _log "=== Done: ${TB_TAG} ==="
}

require_pkgs
for VERSION in "${BUILD_VARIANTS[@]}"; do
    build_variant "${VERSION}"
done
```

- [ ] **Step 2: Syntax check**

Run: `bash -n .extras/image-builder/build-sbo-testbuild.sh`
Expected: exit 0.

- [ ] **Step 3: shellcheck (if available)**

Run: `shellcheck -x .extras/image-builder/build-sbo-testbuild.sh || true`

- [ ] **Step 4: Commit**

```bash
git add .extras/image-builder/build-sbo-testbuild.sh
git commit -m 'image-builder: build-sbo-testbuild.sh'
```

---

## Task 6: per-variant isolation

The spec requires one variant failing not to block the other, non-zero exit at
the end. Add this to all three scripts' main loops.

**Files:**
- Modify: `.extras/image-builder/bootstrap.sh` (main loop)
- Modify: `.extras/image-builder/build-full-image.sh` (main loop)
- Modify: `.extras/image-builder/build-sbo-testbuild.sh` (main loop)

- [ ] **Step 1: Wrap each main loop**

In each script, replace the plain `for VERSION ...` main loop with an
isolation wrapper. For **bootstrap.sh** (which also has the changelog gate):

```sh
rc=0
for VERSION in "${BUILD_VARIANTS[@]}"; do
    if changelog_changed "${VERSION}"; then
        if ! ( build_variant "${VERSION}" ); then
            _warn "variant ${VERSION} failed; continuing."
            rc=1
        fi
    fi
done
exit "${rc}"
```

For **build-full-image.sh** and **build-sbo-testbuild.sh** (no changelog gate):

```sh
rc=0
for VERSION in "${BUILD_VARIANTS[@]}"; do
    if ! ( build_variant "${VERSION}" ); then
        _warn "variant ${VERSION} failed; continuing."
        rc=1
    fi
done
exit "${rc}"
```

Note: `build_variant` runs in a subshell `( )` so a `set -e` abort inside it
(or an `_err` exit) is contained and the loop proceeds to the next variant.
For build-sbo-testbuild.sh keep the `require_pkgs` call **before** the loop
(a missing .txz is fatal for all variants, not per-variant).

- [ ] **Step 2: Syntax check all three**

Run: `for f in bootstrap build-full-image build-sbo-testbuild; do bash -n .extras/image-builder/$f.sh; done`
Expected: exit 0, no output.

- [ ] **Step 3: Re-run lib self-check (unaffected, sanity)**

Run: `bash .extras/image-builder/test-image-builder.sh`
Expected: `FAIL: 0`.

- [ ] **Step 4: Commit**

```bash
git add .extras/image-builder/bootstrap.sh .extras/image-builder/build-full-image.sh .extras/image-builder/build-sbo-testbuild.sh
git commit -m 'image-builder: per-variant isolation, non-zero exit on failure'
```

---

## Task 7: README

**Files:**
- Create: `.extras/image-builder/README`

- [ ] **Step 1: Write README**

Create `.extras/image-builder/README` with the VM-side setup, verbatim:

```
sbo-testbuild image builder
===========================

Builds the docker images that .extras/test-build consumes:
  docker.noland.dnx:5000/sbo-testbuild:current
  docker.noland.dnx:5000/sbo-testbuild:15.0

Three scripts, chained (see .extras/docs/specs/2026-07-13-image-builder-design.md):
  bootstrap.sh           sbo-base:{ver}       FROM scratch, base pkgs from NAS
  build-full-image.sh    sbo-full:{ver}       FROM base, all series
  build-sbo-testbuild.sh sbo-testbuild:{ver}  FROM full, + sbopkg + tools

All settings live in ./config.

VM setup (docker.noland.dnx, Slackware x86_64, 4 vCPU / 4 GB / 80 GB)
--------------------------------------------------------------------
1. Install docker; enable the daemon.

2. NFS-mount the two NAS trees read-only, named to match:
     /mnt/nas/slackware64-current   -> -current mirror tree
     /mnt/nas/slackware64-15.0      -> 15.0 mirror tree
   Each is a full mirror (PACKAGES.TXT, ChangeLog.txt, slackware64/, patches/,
   extra/). Root must be able to read them (bootstrap runs installpkg as root).

3. Run a LAN registry:
     docker run -d --restart=always -p 5000:5000 \
       -v /opt/registry/data:/var/lib/registry --name registry registry:2

4. Mark the registry insecure (plain HTTP) on the VM AND every pulling client
   (this dev box, the buildsystem VM). In /etc/docker/daemon.json:
     { "insecure-registries": ["docker.noland.dnx:5000"] }
   then restart docker.

5. Drop the two prebuilt packages (built once, re-drop on upstream bumps):
     /opt/sbo-testbuild/pkgs/sbopkg-*.txz
     /opt/sbo-testbuild/pkgs/sbo-maintainer-tools-*.txz

6. Install the nightly cron (root):
      0 4 * * *  /path/to/.extras/image-builder/bootstrap.sh           >> /var/log/sbo-testbuild.log 2>&1
     15 4 * * *  /path/to/.extras/image-builder/build-full-image.sh    >> /var/log/sbo-testbuild.log 2>&1
     30 4 * * *  /path/to/.extras/image-builder/build-sbo-testbuild.sh >> /var/log/sbo-testbuild.log 2>&1

7. Ensure docker.noland.dnx resolves on the LAN (static IP or DNS).

Manual first run
----------------
   ./bootstrap.sh --version current --force
   ./build-full-image.sh --version current --force
   ./build-sbo-testbuild.sh --version current --force
Then confirm:
   docker pull docker.noland.dnx:5000/sbo-testbuild:current
   docker run --rm docker.noland.dnx:5000/sbo-testbuild:current sbopkg -V

Flags: --force (rebuild unconditionally), --version <current|15.0> (one variant).

Tests
-----
   bash test-image-builder.sh     # pure-logic self-check, no docker
```

- [ ] **Step 2: Commit**

```bash
git add .extras/image-builder/README
git commit -m 'image-builder: README with VM setup checklist'
```

---

## Task 8: executable bits + final check

**Files:**
- Modify (mode): the four `.sh` scripts

- [ ] **Step 1: chmod +x the scripts**

```bash
chmod +x .extras/image-builder/bootstrap.sh \
         .extras/image-builder/build-full-image.sh \
         .extras/image-builder/build-sbo-testbuild.sh \
         .extras/image-builder/test-image-builder.sh
```

- [ ] **Step 2: Run the self-check once more**

Run: `bash .extras/image-builder/test-image-builder.sh`
Expected: `PASS: N  FAIL: 0`, exit 0.

- [ ] **Step 3: Syntax-check all four**

Run: `for f in .extras/image-builder/*.sh; do bash -n "$f" || echo "SYNTAX FAIL: $f"; done`
Expected: no `SYNTAX FAIL` lines.

- [ ] **Step 4: Commit**

```bash
git add .extras/image-builder
git commit -m 'image-builder: mark scripts executable'
```

---

## Deferred (not in this plan)

- **Real end-to-end chain** on the VM (bootstrap→full→testbuild producing a
  pushed `sbo-testbuild:current`): the user runs it once the VM/registry/mounts
  exist, and reports back. Mirrors `.extras/test-build` Task 10.
- **`installed_in_base`** in `.extras/test-build`: now unblockable (query the
  built image's package db) but tracked separately in the project memory
  `test-build-image-builder-todo`.
- **i586** variants.
- **Registry auth/TLS** (LAN plain HTTP for now).
```