Split tools.func into five parts behind an unchanged loader

tools.func was 10,449 lines and 134 functions, a third of the whole engine in
one unsectioned file. The implementations now sit in shared/tools/ by domain --
system, forge, runtime, db, hwaccel -- and shared/tools.func is an 80-line
loader, so every caller still sources exactly one file.

Nothing about the API changed. The split was done by segmenting on top-level
definitions and proven lossless two ways: concatenating the segments in original
order reproduces the file byte for byte, and sourcing the loader yields the same
133 functions with byte-identical bodies as sourcing the original.

That proof mattered. get_current_ip looks like a 134th top-level definition but
is payload inside a heredoc that setup_local_ip_helper writes to disk. Splitting
on brace balance would have cut that function in half; splitting on the next
definition kept it whole, and it happened to land in the same part as its
parent. Had it been classified elsewhere, the heredoc would have been torn
across two files and the generated helper truncated -- visible only on a user's
host, at install time.

So shared/tools/API.txt records the exported set and a workflow diffs against it
on any change under shared/tools/, alongside a parse check of every part.

Two pre-existing documentation errors surfaced while cross-checking the
published reference: it lists get_current_ip, which is heredoc payload and not
an API at all, and is_alpine, which exists in core.func and alpine-tools.func
rather than here.

Author: MickLesk

.github/workflows/verify-tools-split.yml

@@ -0,0 +1,48 @@
+name: Verify tools split
+
+# shared/tools.func is the published helper API for script authors, and its
+# implementation is split across shared/tools/*.func. A split can silently lose
+# a function -- most easily by cutting through a heredoc that contains a
+# column-0 function definition, which looks like a definition but is payload.
+# That only surfaces on a user's host, so it is checked here instead.
+
+on:
+  pull_request:
+    paths:
+      - "shared/tools.func"
+      - "shared/tools/**"
+  push:
+    branches: [main]
+    paths:
+      - "shared/tools.func"
+      - "shared/tools/**"
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Every part parses
+        run: |
+          set -euo pipefail
+          for f in shared/tools.func shared/tools/*.func; do
+            bash -n "$f" || { echo "::error file=$f::syntax error"; exit 1; }
+          done
+
+      - name: The loader still defines the whole API
+        run: |
+          set -euo pipefail
+          COMMUNITY_SCRIPTS_CORE_DIR="$PWD"
+          _cs_source_func() { source "$COMMUNITY_SCRIPTS_CORE_DIR/$1"; }
+          export -f _cs_source_func 2>/dev/null || true
+          source shared/tools.func >/dev/null 2>&1
+          declare -F | awk '{print $3}' \
+            | grep -v '^_cs_source_func$\|^_tools_source_part$' | sort > /tmp/actual.txt
+          if ! diff -u shared/tools/API.txt /tmp/actual.txt; then
+            echo "::error::the set of exported functions changed."
+            echo "Intentional? Regenerate shared/tools/API.txt in the same PR."
+            exit 1
+          fi
+          echo "$(wc -l < /tmp/actual.txt) functions, unchanged"

README.md

@@ -71,7 +71,12 @@ shared/     platform-agnostic engine
   build.func           entry point, origin resolution, platform dispatch
   build-ui.func        whiptail wizard, validators, advanced settings
   core.func            colors, spinners, messaging, silent()
-  tools.func           helper library used by install scripts
+  tools.func           helper library used by install scripts (loader)
+  tools/system.func      packages, repositories, OS probes, services
+  tools/forge.func       GitHub, GitLab and Codeberg releases
+  tools/runtime.func     language runtimes and application installers
+  tools/db.func          databases and search engines
+  tools/hwaccel.func     GPU detection and hardware acceleration
   install.func         in-container bootstrap (multi-distro)
   alpine-install.func  in-container bootstrap for Alpine
   alpine-tools.func    helper library for Alpine
@@ -233,6 +238,9 @@ Before opening a PR:
   on Proxmox VE belongs in `pve/`.
 - Never hardcode a raw URL. Use `_cs_source_func "shared/<name>.func"` (or
   `pve/…`, `incus/…`) so both roots keep resolving and forks keep working.
+- `shared/tools.func` is the published helper API. Source that, not the parts
+  under `shared/tools/`. If you add or rename a function there, regenerate
+  `shared/tools/API.txt` in the same PR — CI compares against it.
 - New files go in the folder that matches their root. Nothing resolves by
   basename, so `incus/tools.func` and `shared/tools.func` are both fine.
 - `shellcheck` and `shfmt` the files you touched.