Initial import: SBo-danix repo setup, sbshadow, sbpull

slackrepo_setup_SBo-danix.sh rebuilds the personal SBo-danix repo from
upstream plus the personal and pentesting subtree overlays. Shadowing is
delegated to sbshadow, which reconciles both ways against the pristine
current branch (shadow packages now carried in an overlay, restore those
no longer carried) and then runs mkhint -F. sbpull.bash provides the
sbpull shell function that pulls one overlay subtree and runs sbshadow.

Licensed GPLv2 only.

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

1 files changed, 78 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1d2f67f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Single bash script (`slackrepo_setup_SBo-danix.sh`) that builds a personal Slackware SlackBuilds
+repo at `/var/lib/sbopkg/SBo-danix`. The repo feeds **slackrepo** (`../GITHUB/slackrepo/`), the
+tool used to build slackware64-current packages. The repo is regenerated from scratch weekly.
+No build/test tooling; run the script directly.
+
+## The -current dependency problem
+
+SBo SlackBuilds target Slackware **stable**. Some of their build-time REQUIRES are unneeded on
+**-current** because -current already ships them as system packages or newer versions. Examples:
+`google-go-lang` (system package in -current), `rust-opt` (only exists because stable's system
+rust is old). These are "phantom deps" on -current.
+
+slackrepo strips a dep from a package via a per-package **hintfile** (`<prgnam>.hint`) containing
+`DELREQUIRES="rust-opt"`. Relevant slackrepo internals:
+
+- Hintfile search order (`parsefunctions.sh` ~line 414): `$SR_SBREPO/$itemdir`, `$SR_HINTDIR`,
+  `$SR_HINTDIR/$itemdir`, then `$SR_DEFAULT_HINTDIR[/itemdir]`. **First match wins** — only one
+  hintfile per package is sourced.
+- `DELREQUIRES` (`parsefunctions.sh` ~line 595) removes listed deps from that **single** package's
+  REQUIRES. There is **no** repo-wide "delete dep X everywhere" mechanism; every dependent needs
+  its own hintfile. Hintdirs are set in `etc/slackrepo_SBo-danix.conf` (`HINTDIR`,
+  `DEFAULT_HINTDIR`).
+
+Pain point: a package with ~20 REQUIRES may pull in several phantom-dep dependents; hand-writing a
+hintfile per dependent each week is tedious and error-prone.
+
+**Solution does not live here.** Hintfiles are owned by the `mkhint` tool (`../mkhintfile/`), which
+already creates/backs up/reviews them. The phantom-dep auto-strip is implemented there, not in this
+setup script:
+- A phantom-dep list at `~/.config/mkhint/phantom-deps` (one dep per line, `#` comments).
+- `mkhint --new` auto-adds `DELREQUIRES` for any listed dep it sees in the `.info` REQUIRES.
+- `mkhint --fix-current` (`-F`) bulk-sweeps the whole repo after a weekly regen: every package whose
+  REQUIRES hits a phantom dep gets a hintfile with the right `DELREQUIRES` (created if absent, merged
+  in place if present).
+
+Weekly flow: regenerate repo with this script; `sbshadow` runs `mkhint -F` at the end.
+Do **not** add a hintfile generator to this script — it would create a second owner of HINT_DIR and
+fight mkhint's `.bak` handling.
+
+## Run
+
+```bash
+./slackrepo_setup_SBo-danix.sh
+```
+
+Destructive: `rm -rf`s `$REPO` on every run to start clean, then re-clones upstream. Interactive
+`read` prompt inside `sbshadow` is the only confirmation (declining exits 0, run continues).
+
+## Architecture
+
+Pipeline, in order:
+
+1. Clone upstream SBo (`Ponce/slackbuilds`), check out `current`, branch to `danix-current`.
+2. Overlay two personal remotes as **git subtrees** (squashed): `my-slackbuilds` → `personal/`,
+   `Slackware-Pentesting-Suite` → `pentesting/`.
+3. **Shadowing**: delegated to `sbshadow` (separate script, must be on PATH). It reconciles both
+   ways against the pristine `current` branch: any upstream package whose directory name matches a
+   package under `personal/` or `pentesting/` is `git rm`'d (shadow); any upstream package missing
+   from HEAD and no longer carried in an overlay is restored with `git checkout current -- cat/pkg`
+   (unshadow). A package is identified by a `$pkg/$pkg.SlackBuild` file. Match by directory
+   basename only, not content. Then it always runs `mkhint -F`.
+
+`sbshadow` is also called by the `sbpull` bash function (`sbpull.bash`, sourced from root's `.bashrc` on the build VM) after a
+`git subtree pull`, so overlay changes are applied without regenerating the whole repo. It is the
+single owner of shadow logic; do not re-inline it here.
+
+## Constraints
+
+- `set -euo pipefail` — any unhandled failure aborts. Keep new steps failure-safe.
+- Paths under `$REPO`; shadow logic depends on the upstream layout being `category/package/`
+  (`sbshadow` greps `cat/pkg/pkg.SlackBuild` in `git ls-tree current`). Layout change breaks it.
+- Unshadow assumes anything missing from HEAD but present in `current` was removed by shadowing.