Revisit bootstrapping options and entrypoints

[kergoth]

Background

The script/bootstrap script was originally intended as a curl-based entrypoint for getting up and running with dotfiles:

1. Install git, bash, curl, unzip
2. Clone the repo
3. Run setup

However, it has grown beyond its original scope and doesn't cleanly fit with the OS/root-level setup scripts.

Current State

• script/bootstrap - User-level entrypoint, installs deps + chezmoi, runs bootstrap scripts
• script/arch/setup-root - Root-level, creates user, sets up sudo
• script/arch/os-install - Bare-metal installation
• script/setup, script/setup-full, script/setup-system - User-level setup

Issues

1. ArchWSL chicken-and-egg: Bootstrap can't run on fresh ArchWSL because pacman needs keyring init first, but bootstrap uses pacman -Sy to install git
2. Root vs User divide: Bootstrap assumes a user exists with sudo access. On fresh systems (ArchWSL, bare-metal), you need to create the user first via setup-root
3. Scope creep: Bootstrap does more than its comments describe
4. pacman -Sy: Uses partial upgrade (should be -Syu)

Questions to Consider

1. Should bootstrap handle keyring init for Arch/ArchWSL before installing git?
2. Should there be a unified "smart" entrypoint that detects context (root vs user, fresh vs existing) and calls appropriate scripts?
3. Should bootstrap stay focused on just "clone repo + install chezmoi" and leave all setup to explicit setup scripts?
4. How should the wget-based flow work for systems without git (download setup-root directly)?

Related

• Issue Update arch setup, particularly for WSL #26 (Update arch setup for WSL)
• The Chimera Linux pattern in README shows clean phase separation

[kergoth]

Additional consideration: Minimal bootstrap approach

Another option is to make bootstrap truly minimal - only responsible for:

1. Install essential deps (git, curl)
2. Clone the repository
3. Exit (or print instructions for next steps)

This would make bootstrap a pure "get the code in place" script, deferring all actual setup to the existing stage scripts:

• setup-root for root-level user creation
• setup-system for system-level configuration
• setup for user-level dotfiles

Benefits:

• Clear single responsibility
• No overlap with stage scripts
• Works for all contexts (fresh install, existing system, root, user)
• Avoids the "what does bootstrap actually run?" confusion

The user would then explicitly run the appropriate stage script(s) based on their context:

• Fresh ArchWSL as root: bootstrap → setup-root → (switch to user) → bootstrap as user → setup-full
• Existing system as user: bootstrap → setup or setup-full

This matches the documented purpose better: "getting it in place and letting the other scripts do the work."

[kergoth]

Current callers of script/bootstrap

Any changes to bootstrap will require accounting for all current callers. Currently bootstrap installs chezmoi, inits it, and runs its bootstrap scripts, which callers depend on.

File	Line	Call
script/setup	12	"$scriptdir/bootstrap"
script/setup-system	19	"$scriptdir/bootstrap"
script/setup.ps1	8	& "$PSScriptRoot/bootstrap.ps1"
script/setup-system.ps1	3	& "$PSScriptRoot/bootstrap.ps1"

[kergoth]

Follow-up: Splitting bootstrap for chezmoi needs

Building on the minimal bootstrap approach, we'll likely need two levels:

1. bootstrap (entrypoint) - Stays minimal: clone repo, install baseline deps (git, bash, curl, unzip), ensure the repo exists. No chezmoi.

2. Internal chezmoi bootstrap (not an entrypoint) - Installs chezmoi, inits it, runs chezmoi bootstrap scripts. Called by scripts that need chezmoi templates.

This way:

• Scripts needing chezmoi templates (setup, setup-system, etc.) call the internal chezmoi bootstrap
• The bootstrap entrypoint remains a clean "just get me the repo and minimal deps" path
• Scripts that don't need templates can rely on the setup entrypoint directly

[kergoth]

Findings from container testing work

While building test containers for Ubuntu, Chimera, and Arch (#57), we hit the ordering issue directly: setup-system calls bootstrap, which runs chezmoi bootstrap scripts, which triggered install-tools (eget/cargo/uv tool installation) before setup-system-chimera had a chance to install system-level prerequisites.

Analysis: What actually needs to run during bootstrap?

Evaluated all scripts matching the before_.*(install|bootstrap)- grep pattern:

Script	Needed at bootstrap?	Why
00_install-1password-cli	Yes	Age key bootstrap depends on op
10_bootstrap-age-identity-key	Yes	Encrypted files need age key
12_bootstrap-chezmoi-github-token	Yes	Externals auth needs token
20_install-homebrew (macOS)	Yes	Brewfiles need it
25_install-tools	No	Convenience tools, no blocker
40_bootstrap-bindir-repo	No	One-time init, no blocker

Scripts 25 and 40 were being pulled in by the overly broad install|bootstrap grep.

Analysis: Do setup-system scripts need the full bootstrap chain?

Examined all setup-system-*.tmpl files for template dependencies:

Script	Needs full bootstrap?	Notes
setup-system-macos.tmpl	Yes	Uses includeTemplate for Brewfiles
All others (arch, chimera, linux, freebsd, steamos, fedora, windows)	No	Only use simple config flags from chezmoi init

Key finding: Only macOS's setup-system needs the secrets chain. All Linux/FreeBSD setup-system scripts work with just chezmoi init.

Tactical fix applied

Rather than the full bootstrap split (which this issue tracks), we applied a naming convention:

• Renamed install-1password-cli → bootstrap-1password-cli
• Renamed install-homebrew → bootstrap-homebrew
• Renamed bootstrap-bindir-repo → init-bindir-repo (not a bootstrap prerequisite)
• Tightened grep from before_.*(install|bootstrap)- to before_.*bootstrap-

Convention: bootstrap-* = must run during bootstrap phase (secrets, Homebrew). install-* / init-* = normal chezmoi apply phase.

Support for the split approach

This analysis directly supports the split bootstrap comment:

1. bootstrap (entrypoint) — deps, clone, chezmoi init. No chezmoi scripts.
2. Internal chezmoi bootstrap — secrets chain + bootstrap-* scripts. Called by setup and setup-system on macOS only.

For Linux/FreeBSD, setup-system only needs chezmoi init to template its scripts. The full bootstrap chain (age key, GitHub token) is only needed before chezmoi apply in script/setup.

[kergoth]

Correction to the above: the final paragraph should read:

For Linux/FreeBSD, setup-system only needs chezmoi init to template its scripts. The full bootstrap chain (age key, GitHub token) doesn't need to be split out separately — script/setup runs chezmoi apply, which naturally executes all before_* scripts (including bootstrap-*) in the correct order before applying dotfiles. The problem was setup-system calling bootstrap and prematurely triggering these scripts before system-level prerequisites were in place.

[kergoth]

Further correction:

• script/setup: Runs chezmoi apply, which naturally executes all before_* scripts (including bootstrap-*) in the correct order. No need to split out an internal chezmoi bootstrap here.
• setup-system on Linux/FreeBSD: Only needs chezmoi init to template its scripts. Should not run bootstrap scripts at all.
• setup-system-macos: Still the one case that needs the internal chezmoi bootstrap (secrets chain) split out, because it uses includeTemplate for Brewfiles that may reference encrypted content.

So the split proposed in the earlier comment is still needed, but the internal chezmoi bootstrap caller is just setup-system-macos, not setup.