Files

T

vasilito f3f4f15557 phase 12.1: add TOOLS.md — build-system tools reference (Round 13)

Creates local/scripts/TOOLS.md as a companion to HOOKS.md,
listing only the 10 build-system operator tools (excluding the
~120 test scripts under local/scripts/).

Each tool has:
  - One-line purpose
  - Usage example
  - All mode flags documented

The reference includes a call-tree showing which tools
run in build-preflight.sh vs pre-push-checks.sh.

Added README.md link to TOOLS.md in the Documentation section.

2026-07-12 12:51:18 +03:00

3.6 KiB

Raw Blame History

Red Bear OS — Build System Tools Reference

Round 13 | 10 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`

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
--no-regen     Apply version sync, skip Cargo.lock regen
--regen-only   Only regenerate Cargo.lock files
(default)      Apply sync + regen lockfiles

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

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

3.6 KiB Raw Blame History