# Every host binary Sjel assumes is installed. No entry, no check. Read by tools/toolchain-check,
# wrapped by tools/install.sh and tools/doctor; single-line TOML only (tools/lib/toml.sh).
#
#   required    "yes" (a miss fails doctor) | "optional" (a miss warns) | "runtime" (only this
#               machine's container_runtime is checked, the others are alternatives)
#   why         one line: what Sjel uses it for
#   install_macos / install_linux   the copy-paste install hint for that OS
#   bin         the executable name, when it differs from the section name
#   app         the macOS app bundle, so `sjel storage installed` never reports it idle
#   os          "macos" | "linux"; the checker skips the entry elsewhere
#   upstream    the upstreams.toml section id, when this tool is also audited code
#   min_version / version_cmd   an optional floor, checked only when both are present
#   needed_by   where it applies: "workflow:<name>", "capability:<id>",
#               "capability-field:<field>", "overlay". Absent = core, checked on every machine.
#
#   tools/toolchain-check                    # this machine: core + enabled capabilities + runtime
#   tools/toolchain-check --workflow backup  # ...plus what a backup needs, before it holds a service

# ---- always required ------------------------------------------------------------------

[git]
required = "yes"
why = "version control; the spine of update.sh and every repo operation"
install_macos = "preinstalled with Xcode CLT — or: brew install git"
install_linux = "apt-get install -y git"

[bash]
required = "yes"
why = "every tools/*.sh runs here; Sjel targets bash 3.2 (CONTRIBUTING.md#portable-shell)"
install_macos = "preinstalled (3.2)"
install_linux = "preinstalled"

[jq]
required = "yes"
why = "JSON in shell — the secret setup, tools/restore.sh and the security workflow"
install_macos = "brew install jq"
install_linux = "apt-get install -y jq"

[bun]
required = "yes"
upstream = "bun"
min_version = "1.4.0" # UI Security Scanner API; and the lockfileVersion 2 that 1.3.14 cannot parse
version_cmd = "bun --version"
why = "the TS runtime (CONTRIBUTING.md#language-tooling): doctor, packs-codex, the site build and the web clipper"
install_macos = "brew install oven-sh/bun/bun"
install_linux = "curl -fsSL https://bun.sh/install | bash"

[uv]
required = "yes"
why = "the Python runtime (CONTRIBUTING.md#language-tooling): printctl and any uv-run script"
install_macos = "brew install uv"
install_linux = "curl -LsSf https://astral.sh/uv/install.sh | sh"

[gh]
required = "yes"
why = "GitHub CLI: repos.ts, systems.toml visibility checks, the PR workflow"
install_macos = "brew install gh"
install_linux = "apt-get install -y gh   # or: https://cli.github.com"

[bitwarden-cli]
required = "yes"
bin = "bw"
needed_by = ["overlay"]
upstream = "bitwarden-cli"
why = "the canonical secret store CLI (CONTRIBUTING.md#secrets): the secret setup, bw-unlock and backup restore"
install_macos = "brew install bitwarden-cli"
install_linux = "npm i -g @bitwarden/cli   # or the latest GitHub release"

# ---- optional (feature/gate-scoped; absence warns, never fails) ------------------------

[restic]
required = "optional"
needed_by = ["workflow:backup"]
why = "encrypted backups (CONTRIBUTING.md#backups-before-migrations); backup.sh and nothing else"
install_macos = "brew install restic"
install_linux = "apt-get install -y restic"

[sqlite3]
required = "optional"
needed_by = ["capability-field:backup_sqlite", "capability-field:backup_sqlite_online", "workflow:restore"]
why = "cold SQLite backup, the store's live `.backup` copy and isolated restore integrity checks"
install_macos = "preinstalled — or: brew install sqlite"
install_linux = "apt-get install -y sqlite3"

[swift]
required = "optional"
os = "macos"
needed_by = ["workflow:backup"]
why = "Foundation checks that the store's iCloud Drive archive finished uploading and downloads an offloaded predecessor"
install_macos = "install Xcode Command Line Tools: xcode-select --install"

[python3]
required = "optional"
needed_by = ["workflow:backup"]
why = "store-only iCloud retention verifies per-archive hashes and invokes an isolated restore"
install_macos = "preinstalled with Xcode Command Line Tools — or: brew install python"
install_linux = "apt-get install -y python3"

[apfel]
required = "optional"
os = "macos"
needed_by = ["capability:foundation-models"]
upstream = "apfel"
version_cmd = "apfel --version"
min_version = "1.9.1"
why = "capabilities/foundation-models runs `apfel --serve`; needs macOS 26+, Apple Silicon and Apple Intelligence enabled"
install_macos = "brew install apfel"

[macmon]
required = "optional"
os = "macos"
needed_by = ["capability:macmon"]
upstream = "macmon"
version_cmd = "macmon --version"
min_version = "0.7.0"
why = "capabilities/macmon runs `macmon serve` for the app's Systems page; tools/sysmon power runs it as a TUI"
install_macos = "cargo install macmon --locked"   # latest; min_version is a floor, not a target

[sqld]
required = "optional"
os = "macos"
needed_by = ["capability:sqld"]
upstream = "libsql-server"
version_cmd = "sqld --version"
min_version = "0.24.32"
why = "capabilities/sqld runs it as the libSQL primary other devices replicate from"
install_macos = "tools/install-sqld.sh"   # pinned version + digest, into ~/.local/bin

[exiftool]
required = "optional"
upstream = "exiftool"
version_cmd = "exiftool -ver"
min_version = "13.55"
why = "media ingest calls it once per staged tree for DateTimeOriginal, and refuses before writing bytes without it"
install_macos = "brew install exiftool"
install_linux = "apt-get install -y libimage-exiftool-perl"

[yt-dlp]
required = "optional"
needed_by = ["capability:comms"]
version_cmd = "yt-dlp --version"
min_version = "2026.08.19"
why = "capabilities/comms/src/media.rs execs it for share-link metadata and subtitles, always with --skip-download"
install_macos = "brew install yt-dlp"
install_linux = "apt-get install -y yt-dlp   # or: uv tool install yt-dlp"

[ollama]
required = "optional"
needed_by = ["capability:comms", "capability:scouting"]
version_cmd = "ollama --version"
min_version = "0.33.0"
why = "serves the `embedding` and `summarization` roles: comms relevance ranking, scouting vectors and the local digest rung"
app = "Ollama.app"
install_macos = "brew install --cask ollama"
install_linux = "curl -fsSL https://ollama.com/install.sh | sh"

[tailscale]
required = "optional"
version_cmd = "tailscale version"
min_version = "1.98.9"
why = "capabilities/host-net execs `tailscale status --json`, `debug prefs` and `lock status` for its tailnet verb"
install_macos = "brew install --cask tailscale"
install_linux = "curl -fsSL https://tailscale.com/install.sh | sh"

[libreoffice]
required = "optional"
bin = "soffice"
why = "headless LibreOffice is the only renderer the slide-deck Pack has, and rendering is its verification step"
app = "LibreOffice.app"
install_macos = "brew install --cask libreoffice"
install_linux = "apt-get install -y libreoffice"

[xcode]
required = "optional"
bin = "xcodebuild"
os = "macos"
app = "Xcode.app"
why = "builds and archives the iOS app through tools/distribution/ios-archive, which `sjel testflight` drives"
install_macos = "xcode-select --install is not enough; install Xcode from the App Store"

# ---- interactive terminal tools (this Mac's shell; absence warns) -----------------------
# No Sjel script execs these; they replace cat, ls and git's default diff for the human at the shell.

[bat]
required = "optional"
os = "macos"
why = "colourised file reading: `cat` and MANPAGER in the personal shell config"
install_macos = "brew install bat"

[eza]
required = "optional"
os = "macos"
why = "`ls`/`ll`/`la`/`lt`/`ltt` in the personal shell config"
install_macos = "brew install eza"

[git-delta]
required = "optional"
os = "macos"
bin = "delta"
why = "git's pager for diff, log and blame, set once in ~/.gitconfig"
install_macos = "brew install git-delta"

[zoxide]
required = "optional"
os = "macos"
why = "`z` and `zi`, the frecent-directory jump"
install_macos = "brew install zoxide"

[fzf]
required = "optional"
os = "macos"
why = "Ctrl-R history search, Ctrl-T file picking and completion, and the selector zoxide's `zi` reaches for"
install_macos = "brew install fzf"

# ---- the Rust command-line baseline ----------------------------------------------------

[cargo]
required = "yes"
why = "the Rust toolchain: builds sjel-cli and every capability's `build` command"
install_macos = "brew install rustup && rustup default stable   # or: brew install rust"
install_linux = "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh"

[ripgrep]
required = "yes"
bin = "rg"
why = "the search tool Sjel's agents and scripts use instead of grep (AGENTS.md)"
install_macos = "brew install ripgrep"
install_linux = "apt-get install -y ripgrep"

[fd]
required = "yes"
why = "the file finder Sjel uses instead of find"
install_macos = "brew install fd"
# Debian and Ubuntu ship the binary as `fdfind` because of a name clash with an older package.
install_linux = "apt-get install -y fd-find && ln -sf \"$(command -v fdfind)\" ~/.local/bin/fd"

[sd]
required = "optional"
os = "macos"
why = "search and replace with one regex syntax on every OS, instead of sed"
install_macos = "brew install sd"

[jaq]
required = "optional"
os = "macos"
why = "a faster jq clone; [jq] stays the required JSON tool and no script calls this yet"
install_macos = "brew install jaq"

[hyperfine]
required = "optional"
os = "macos"
why = "command benchmarks, for measuring a script against its sjel-cli port"
install_macos = "brew install hyperfine"

[tokei]
required = "optional"
os = "macos"
why = "line counts per language, for how much shell and TypeScript is left to port"
install_macos = "brew install tokei"

[dust]
required = "optional"
os = "macos"
why = "disk usage as a tree for the interactive shell"
install_macos = "brew install dust"

[procs]
required = "optional"
os = "macos"
why = "process listing for the interactive shell, with ports and a tree view"
install_macos = "brew install procs"

# ---- container runtimes (the checker validates only this machine's chosen one) ---------

[docker]
required = "runtime"
why = "container runtime (machine.toml container_runtime = docker); tools/agentbox depends on the CLI by name"
install_macos = "brew install --cask orbstack   # or --cask docker, or colima — Sjel assumes the docker CLI, never one provider of it"
install_linux = "apt-get install -y docker.io   # or Docker Engine per docs.docker.com"

[podman]
required = "runtime"
why = "rootless container runtime alternative (machine.toml container_runtime = podman)"
install_macos = "brew install podman"
install_linux = "apt-get install -y podman"

# ---- audit scanners (absence warns) ----------------------------------------------------

[gitleaks]
required = "optional"
needed_by = ["workflow:audit"]
upstream = "gitleaks"
why = "secret scan over git history — tools/audit"
install_macos = "brew install gitleaks"
install_linux = "apt-get install -y gitleaks   # or the latest GitHub release"

[osv-scanner]
required = "optional"
needed_by = ["workflow:audit"]
bin = "osv-scanner"
upstream = "osv-scanner"
why = "dependency-CVE scan over every lockfile and this machine's globally installed packages — tools/audit"
install_macos = "brew install osv-scanner"
install_linux = "go install github.com/google/osv-scanner/cmd/osv-scanner@latest"

[grype]
required = "optional"
needed_by = ["workflow:audit"]
upstream = "grype"
why = "container-image CVE scan by hand, `grype registry:<image>:<tag>`, with no container runtime"
install_macos = "brew install grype"
install_linux = "apt-get install -y grype   # or the latest GitHub release"

[rsync]
required = "optional"
needed_by = ["workflow:backup", "workflow:restore"]
why = "the file-copy path for backup staging and restore placement; backup.sh refuses to start without it"
install_macos = "preinstalled — or: brew install rsync"
install_linux = "apt-get install -y rsync"