# Red Bear OS — Build System Tools Reference **Round 14** | **15 tools** | `local/scripts/` This is the canonical reference for build-system operator tools. Test scripts (~120) are excluded; see `local/scripts/test-*.sh` for QEMU/runtime validation helpers. ## Quick Reference | Tool | Purpose | Example | |------|---------|---------| | **patch-status.sh** | Consolidated status report | `./local/scripts/patch-status.sh` (--brief, --json) | | **sync-versions.sh** | Cat 0+1+2 version sync + lockfile regen | `./local/scripts/sync-versions.sh --check` | | **verify-patch-content.py** | Orphan patch detection + decision support | `python3 local/scripts/verify-patch-content.py --report action` | | **verify-fork-versions.sh** | Cat 2 fork supremacy + content check | `./local/scripts/verify-fork-versions.sh` | | **verify-collision-detection.py** | Config [[files]] vs recipe installs/files collision | `python3 local/scripts/verify-collision-detection.py --strict` | | **pre-push-checks.sh** | 7-check pre-push safety net (opt-in hook) | `cp local/scripts/pre-push-checks.sh .git/hooks/pre-push` | | **push-fork-branches.sh** | Operator-reviewed fork push helper | `./local/scripts/push-fork-branches.sh` (--execute) | | **unblock-base-push.sh** | Base fork deadlock resolver (3 operator paths) | `./local/scripts/unblock-base-push.sh path-a` | | **commit-msg** | Auto-phase-prefix hook (opt-in) | `cp local/scripts/commit-msg .git/hooks/commit-msg` | | **build-preflight.sh** | Build-time validation (called by build-redbear.sh) | `./local/scripts/build-preflight.sh --config=redbear-mini` | | **bump-release.sh** | Canonical release-bump orchestrator | `./local/scripts/bump-release.sh --with-sources --with-external` | | **check-external-versions.sh** | External desktop-stack version reporter | `./local/scripts/check-external-versions.sh --strict` | | **bump-graphics-recipes.sh** | Map-driven Qt6/KF6/Plasma recipe bumper | `./local/scripts/bump-graphics-recipes.sh --dry-run` | | **post-checkout-version-sync.sh** | Auto label-sync on semver branch switch (opt-in hook) | `cp local/scripts/post-checkout-version-sync.sh .git/hooks/post-checkout` | | **install-git-hooks.sh** | Idempotent opt-in hook installer | `./local/scripts/install-git-hooks.sh --all` | ## Modes and Flags ### patch-status.sh ``` --brief One-line summary: [orph=0/122 col=0 sync=OK fork=OK cargo=OK] --json Machine-readable JSON (default) Full text report with fork push status ``` ### sync-versions.sh ``` --check Verify only, exit 1 on drift --regen Apply version sync + regen Cargo.lock files (opt-in) --dry-run Preview: show what --regen WOULD change, revert after --no-regen Apply version sync, skip Cargo.lock regen (same as default) --regen-only Only regenerate Cargo.lock files (default) Apply version sync only (lockfile regen is opt-in) ``` ### verify-patch-content.py ``` --strict Exit 1 on any orphan --report action Operator-decision suggestions (INTEGRATED/SUPERSEDED/etc.) --report detail Per-orphan listing with file paths --selftest 5 regression test cases (default) Per-component summary ``` ### verify-collision-detection.py ``` --strict Exit 1 on any collision --selftest 8 regression test cases (default) Per-config summary ``` ### verify-fork-versions.sh ``` REDBEAR_SKIP_FORK_VERIFY=1 Skip entirely REDBEAR_STRICT_DIVERGED_CHECK=1 Treat diverged as ERROR (default) Diverged = WARN (advisory) ``` ### pre-push-checks.sh ``` --soft Warn-only, don't block push (default) Block push on any check failure ``` ### push-fork-branches.sh ``` --execute Actually push (default = print-only with 5-second abort) (default) Show status + commands ``` ### bump-release.sh (canonical release-bump orchestrator) `bump-release.sh` is the single entry point for a Red Bear OS release bump. It DECIDES what needs to move (per-fork routing, external group) and DELEGATES execution to existing single-purpose tools (`sync-versions.sh` for label rewrites, `upgrade-forks.sh --to=` for source rebases, `bump-graphics-recipes.sh` for the desktop stack). It never duplicates sed logic and never auto-commits. See `local/docs/RELEASE-BUMP-WORKFLOW.md` for the full runbook and decision tree. ``` (no args) Label sync (sync-versions.sh --no-regen) + fork upstream REPORT. Fast, local + cached network. (The post-checkout hook calls sync-versions.sh --no-regen directly — not this script. External version report is only via --with-external or a standalone check-external-versions.sh run.) --with-sources Additionally perform fork source bumps for eligible forks (mode snapshot/tracked, newer upstream semver tag) via upgrade-forks.sh --to=, then re-sync labels and update local/fork-upstream-map.toml column 3 in place. --with-external Additionally run the rewritten bump-graphics-recipes.sh for the Qt6/KF6/Plasma desktop stack (group-coherent). --check Read-only: report drift + upgradeable-found; exit 1 if any. CI-friendly. --dry-run Print intended changes only; no file mutations. --no-fetch Use cached upstream lookups; no network. --regen Also regenerate Cargo.lock files (sync-versions.sh --regen). --force-diverged Allow source-bump attempts on `diverged` forks (kernel/bootloader/installer). Default = report-only. --fork= Scope to a single fork (e.g. --fork=relibc). ``` Map input: `local/fork-upstream-map.toml` (columns: name, url, tag, mode). Never auto-commits. Prints exact commit commands (parent repo + the relevant `submodule/` branch) for the operator to run. ### check-external-versions.sh (external desktop-stack version reporter) Reads `local/external-upstream-map.toml` (`[groups.*]` for Qt6/KF6/Plasma and `[packages.*]` for singletons like mesa/libdrm/libwayland/sddm) and resolves the latest published version per group/package. Index fetches are cached under `.redbear-recipe-bump/` so `--no-fetch` can reuse a prior run. ``` (no args) Print table: name current latest CURRENT|OUTDATED. Exit 0 always (report). --strict Exit 1 if any package is OUTDATED. --no-fetch Reuse cached index from .redbear-recipe-bump/. --json Emit machine-readable JSON instead of a table. ``` ### bump-graphics-recipes.sh (rewritten, map-driven) Map-driven recipe bumper for the external desktop stack. Driven by `local/external-upstream-map.toml`. Group version resolved ONCE per group (Qt6/KF6/Plasma); per-recipe realpath dedup (symlinked recipes bumped exactly once). tar sources: download → `b3sum` → sed `tar =` + `blake3 =` (+ sync `[package] version =` if semver-mismatched). git-rev sources: `git ls-remote --tags` → latest tag commit sha → sed `rev =`. ``` (no args) Apply bumps; run `repo validate-patches` per recipe; write stabilization report to .redbear-recipe-bump/last-report.txt. --dry-run Print intended changes only (recipe= old= new=). --no-fetch Reuse cached tarballs / index from .redbear-recipe-bump/. ``` Report format (one line per evaluated recipe): `recipe= old= new= patches_total= patches_pass= patches_fail= fail_details=` Never commits. Never removes a recipe for failing validation (per AGENTS.md ABSOLUTE RULE) — failures land in the report for the stabilization phase. ### post-checkout-version-sync.sh (opt-in hook) ``` (installed as .git/hooks/post-checkout) (no args) On semver branch switch with clean tree: run sync-versions.sh --no-regen (labels only). Always exits 0. REDBEAR_NO_AUTO_SYNC=1 Bypass for a single checkout. ``` Guards: `$3==1`, anchored semver branch, no rebase/cherry-pick/merge in progress, `REDBEAR_NO_AUTO_SYNC` unset, clean tree. Never network, never regen, never commit. See `local/docs/HOOKS.md`. ### install-git-hooks.sh (hook installer) ``` (no args) Install post-checkout only (default, least surprise). --all Also install pre-push-checks.sh and commit-msg. --uninstall Remove installed hooks (restores .bak if present). --uninstall --all Remove the full --all set. ``` Idempotent: up-to-date installs are no-ops; differing existing hooks are backed up to `.bak` (rotated) before overwrite. ## Where each tool runs ``` build-preflight.sh ├── sync-versions.sh --check ├── verify-fork-versions.sh ├── verify-patch-content.py └── verify-collision-detection.py pre-push-checks.sh (opt-in git hook) ├── sync-versions.sh --check ├── verify-fork-versions.sh ├── verify-patch-content.py ├── verify-patch-content.py --report action ├── verify-patch-content.py --selftest ├── verify-collision-detection.py └── verify-collision-detection.py --selftest post-checkout-version-sync.sh (opt-in git hook) └── sync-versions.sh --no-regen (label-only; NEVER --regen) bump-release.sh (canonical release-bump orchestrator) ├── sync-versions.sh --no-regen (labels) ├── update_map_tag_inplace() (in-script map column-3 update; │ refresh-fork-upstream-map.sh is a │ standalone complement that also │ appends missing fork rows) ├── upgrade-forks.sh --to= (source bumps, --with-sources) └── bump-graphics-recipes.sh (desktop stack, --with-external) └── repo validate-patches install-git-hooks.sh (operator opt-in hook installer) └── cp into .git/hooks/{post-checkout,pre-push,commit-msg} ``` ## See also - `local/docs/HOOKS.md` — git hooks documentation - `local/docs/RELEASE-BUMP-WORKFLOW.md` — release-bump operator runbook - `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` — cumulative rounds 0-12 - `local/fork-upstream-map.toml` — fork → upstream tag/mode map - `local/external-upstream-map.toml` — external desktop-stack version map - `local/patches/README.md` — patch archive structure --- **Last updated:** 2026-07-18 (Round 14 — release-bump pipeline)