Architecture

Architecture

Directory structure

bin/
  _bootstrap      # resolves CLI_TOOL_ROOT; sourced by all bin scripts
  cache-gpg       # warms GPG agent cache
  convert-video   # wrapper → convert_vid()
  gh-actions-sast # GitHub Actions workflow version scanner
  gitprune        # wrapper → gitprune()
  gitrefresh      # wrapper → gitrefresh()
  sast            # Claude plugin frontmatter scanner
lib/
  common.sh       # shared color vars, gecho, show_progress
  ffmpegcmds.sh   # convert_vid() implementation
  gitcmds.sh      # gitprune() and gitrefresh() implementations
tests/
  test_bootstrap.bats
  test_cache_gpg.bats
  test_common.bats
  test_gh_actions_sast.bats
  test_gitcmds.bats
  test_sast.bats

_bootstrap and CLI_TOOL_ROOT

When installed via Homebrew, bin/ scripts are symlinked into the brew prefix (e.g. /opt/homebrew/bin/). Naively using dirname "${BASH_SOURCE[0]}" would point at the symlink directory, not the actual repo, making ../lib/ lookups fail.

bin/_bootstrap resolves this once by crawling the symlink chain:

_src="${BASH_SOURCE[0]}"
while [ -L "$_src" ]; do
  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
  _src="$(readlink "$_src")"
  [[ "$_src" != /* ]] && _src="$_dir/$_src"
done
CLI_TOOL_ROOT="$(cd -P "$(dirname "$_src")/.." && pwd)"
export CLI_TOOL_ROOT

Because _bootstrap is in bin/, Homebrew symlinks it alongside the other scripts. Each bin script sources it with a single line:

source "${BASH_SOURCE[0]%/*}/_bootstrap"

${BASH_SOURCE[0]%/*} strips the filename to give the directory of the calling script — which, whether it's a symlink or the real file, is always in the same directory as _bootstrap.

All lib/ files are then sourced via $CLI_TOOL_ROOT:

source "$CLI_TOOL_ROOT/lib/gitcmds.sh"

Shared library (lib/common.sh)

lib/common.sh provides utilities used across commands:

• GREEN, GREY, RESET — ANSI color codes
• gecho — prints a green-colored line
• show_progress — reads stdin line-by-line and overwrites a single terminal line (used to suppress noisy git/ffmpeg output)