Botstrap architecture

Botstrap is a cross-platform bootstrap that turns a fresh Mac, Linux, or Windows machine into a configured developer environment with an AI-agent-friendly layout. This document describes how the system is structured and how components interact. For a plain-language walkthrough, see Introduction.

Goals

• One command on each platform that runs the same logical flow (implementation details differ; see Cross-platform notes).
• Registry-driven tool definitions (YAML) instead of hardcoded install lists in orchestration code.
• Phased install: prerequisites, interactive TUI (core + optional choices where supported), apply installs and dotfiles, verification.
• AI-first defaults: predictable PATH, non-interactive core installs, structured agent scaffolding under configs/agent/.

Entry points and boot sequence

Platform	One-liner
macOS / Linux	curl -fsSL https://botstrap.dev/install | bash
Windows	irm https://botstrap.dev/install.ps1 | iex

The site may serve scripts by URL or User-Agent; explicit .sh / .ps1 URLs are also valid.

Boot scripts (boot.sh, boot.ps1) do not run install phases themselves. They:

1. Ensure Git is available: Unix boot sources install/boot-prereqs-git.sh (from the same tree or fetched from raw GitHub when BOTSTRAP_REPO is GitHub-shaped) and runs botstrap_ensure_git_curl; Windows boot uses winget when possible. If git cannot be installed, exit with instructions (see Getting started).
2. Clone BOTSTRAP_REPO into BOTSTRAP_HOME when that path is not already a Git checkout. Defaults: repo https://github.com/an-lee/botstrap.git, home ~/.botstrap (Unix) or %USERPROFILE%\.botstrap (Windows).
3. Exec install.sh (Unix) or install.ps1 (Windows) from that checkout.

Orchestrators (install.sh, install.ps1) load lib/detect (or equivalent), then run phases in order.

Repository layout

botstrap/
  boot.sh / boot.ps1          # curl / irm entry (clone + handoff)
  install/boot-prereqs-git.*  # Shared git (and Unix curl) bootstrap for boot + Phase 0
  install.sh / install.ps1    # Orchestrators
  bin/botstrap                # Thin CLI (update / reconfigure / doctor / version)
  lib/                        # Shared primitives (detect, log, pkg)
  install/                    # Phases and per-tool modules
  configs/                    # Templates for shell, git, editor, agent; OS tuning YAML
  themes/                     # Theme bundles (terminal, prompt, editor)
  registry/                   # prerequisites.yaml, core.yaml, optional.yaml
  docs/                       # User and contributor documentation
  version                     # Semver string for reporting and `botstrap version`

See Registry specification for the YAML schema and Cross-platform notes for package-manager mapping.

Installation phases

Phase	Script	Purpose
0	install/phase-0-prerequisites.sh / .ps1	Installs tools listed in registry/prerequisites.yaml (git, curl, jq, yq, gum) via lib/pkg after a minimal yq bootstrap (Unix: inline binary; Windows: Mike Farah yq via winget before registry reads). Unix git/curl logic lives in install/boot-prereqs-git.sh.
0b	install/phase-0b-os-tune.ps1	Windows only: developer-oriented OS settings from configs/os/windows.yaml via install/modules/os-tune-windows.ps1.
2	install/phase-2-tui.sh / .ps1	Interactive gum flows when gum is available: core multi-select (all selected by default; choices from registry/core.yaml), then optional groups; otherwise non-interactive defaults (all core names unless BOTSTRAP_CORE_TOOLS is preset).
3	install/phase-3-configure.sh / .ps1	Persists core_tools= to ~/.config/botstrap/core-tools.env; installs selected core from registry/core.yaml, then optional from registry/optional.yaml, then dotfiles from configs/. See Configuration file map and Defaults & customization.
4	install/phase-4-verify.sh / .ps1	Verifies every tool in registry/prerequisites.yaml, then selected core (from BOTSTRAP_CORE_TOOLS, else core-tools.env, else all core.yaml names for legacy installs). Windows also verifies optional TUI rows when BOTSTRAP_* are set. See Reference.

Optional per-tool scripts under install/modules/ hold logic that is too complex for inline YAML (extra guards, post-steps). Simple tools can be YAML-only.

lib/ primitives

The lib/ directory contains shared helpers sourced by orchestrators and phases.

File	Platform	Purpose
lib/detect.sh / lib/detect.ps1	Unix / Windows	Detect OS, architecture, distro, and package manager; export BOTSTRAP_OS, BOTSTRAP_ARCH, etc.
lib/log.sh / lib/log.ps1	Unix / Windows	Structured logging helpers used by all phases (see below).
lib/pkg.sh / lib/pkg.ps1	Unix / Windows	Registry-driven install and verify helpers (see below).
lib/os-tune-windows.ps1	Windows only	Applies OS tuning items from configs/os/windows.yaml.

Logging helpers

Unix (lib/log.sh) functions:

Function	Description
botstrap_log_info <msg>	Cyan [botstrap] … line.
botstrap_log_warn <msg>	Yellow [botstrap] … line.
botstrap_log_err <msg>	Red [botstrap] … line to stderr.
botstrap_log_phase <num> <total> <label>	Prominent phase header (gum rounded border when available; bold magenta fallback).
botstrap_log_step <current> <total> <label>	[N/M] label progress line via botstrap_log_info.

Color output is controlled by BOTSTRAP_LOG_COLOR (default 1; set to 0 for plain text in CI or non-terminal environments).

Windows (lib/log.ps1) equivalents:

Function	Description
Write-BotstrapInfo <msg>	Cyan [botstrap] … line.
Write-BotstrapWarn <msg>	Yellow [botstrap] … line.
Write-BotstrapErr <msg>	Red [botstrap] … line.
Write-BotstrapPhase <num> <total> <label>	Phase header (gum border or == Step N/M: … == fallback).
Write-BotstrapStep <current> <total> <label>	[N/M] label line + Write-Progress bar.
Write-BotstrapProgressComplete	Clears the Write-Progress bar.

Registry-driven package layer

lib/pkg.sh (and lib/pkg.ps1 on Windows) provide:

• botstrap_pkg_install / Install-BotstrapPackageFromRegistry — resolve a tool in a registry YAML (registry/core.yaml, registry/prerequisites.yaml, etc.), pick the install snippet for the current OS/distro, and execute it.
• botstrap_pkg_verify — run the tool’s verify command from the registry.
• botstrap_pkg_install_tools_from_csv / Install-BotstrapToolsFromCsv — install a comma-separated subset of tool names in registry file order.
• Optional-group helpers used by Phase 3 to install selected registry/optional.yaml items.

Orchestrators treat the registry as the source of truth; modules supplement where needed.

TUI (Phase 2)

On macOS/Linux, when gum is available, the TUI uses Charmbracelet Gum. Typical steps:

1. Welcome banner.
2. Git identity (gum input).
3. Core tools (gum choose --no-limit, every registry/core.yaml name; all pre-selected by default, or seeded from ~/.config/botstrap/core-tools.env on reconfigure).
4. Editor (single select).
5. Programming languages (multi select).
6. Databases (multi select; Docker-first in registry).
7. AI agent CLIs (multi select).
8. Theme (single select).
9. Optional apps (multi select).
10. Confirm summary (gum confirm).

Selections are exported as BOTSTRAP_* environment variables for Phase 3 (BOTSTRAP_CORE_TOOLS, optional installs from registry/optional.yaml, and file copies from configs/). Exact names are documented in Reference and in the header of install/phase-2-tui.sh.

bin/botstrap CLI

The checkout-local CLI implements:

Command	Behavior
botstrap version	Print semver from the version file.
botstrap update	git pull --ff-only in the repository root. Does not automatically re-run install phases.
botstrap reconfigure	Re-run Phase 2 and Phase 3 only (same repo root as bin/).
botstrap doctor	Run Phase 4 verification (install/phase-4-verify.sh / .ps1): prerequisites, selected core, and (Windows) optional rows.

There is no uninstall subcommand in the current implementation.

Security and trust

• Pipe-to-shell installs are inherently trust-based; users should read boot.sh / boot.ps1 and this repo before running.
• Registry install fields are executed as shell on Unix; keep entries auditable and avoid fetching unaudited third-party scripts where a package manager suffices.

Related documents

• Introduction — What Botstrap does, end to end.
• Getting started — One-liners, local dev, non-interactive behavior.
• Reference — CLI, env vars, artifacts.
• After install — installed stack and usage.
• Defaults & customization — defaults and customization.
• Configuration file map — configs/ → destination paths.
• Registry specification — YAML schema.
• Tool selection — Why each core and optional tool is included.
• Cross-platform notes — OS and package-manager strategy.
• AI agent friendliness — Agent-oriented design choices.
• Contributing — How to contribute.