Zi Setup

Zi Setup is a terminal client for the versioned guided-setup engine in z-shell/src. It discovers a bounded set of facts, offers the engine-provided profiles, shows the exact generated plan, and applies the reviewed plan hash in separate checkout and file phases.

This pilot supports loader and annex. A discovered zunit profile is shown only as preserved compatibility content.

Install

Versioned releases provide archives for Linux, macOS, and Windows on amd64 and arm64. Each release includes SHA256SUMS and GitHub artifact attestations. Windows execution requires a POSIX sh on PATH, such as Git Bash or MSYS2.

Download the archive for your platform from GitHub Releases, verify it against SHA256SUMS, then place zi-setup on your PATH.

The binary includes a checksum-verified snapshot of the authoritative setup engine, so the normal invocation is:

zi-setup

Use --version to print both the client version and bundled z-shell/src revision.

Build from source

Build the client:

go build -o bin/zi-setup ./cmd/zi-setup

Run with the bundled engine:

bin/zi-setup

Override it with a local engine checkout when developing the engine contract:

bin/zi-setup --engine /path/to/src/public/sh/setup.sh

Use --plain for a linear keyboard interaction. For a disposable test home, pass explicit paths so no real shell configuration is touched:

bin/zi-setup --plain \
  --home /tmp/zi-setup-home \
  --config-home /tmp/zi-setup-config/zi \
  --zshrc /tmp/zi-setup-home/.zshrc

The setup engine remains the sole owner of discovery, planning, generated Zsh, precondition checks, file changes, checkout operations, and receipts.

The terminal UI offers only engine-backed choices: the loader or annex profile, the Zi Git ref, and whether setup should update .zshrc. The discovered zunit profile remains visible only as preserved compatibility content. Plain and headless modes expose the same choices as flags.

An external engine defaults to phase-level progress for backward compatibility. Pass --engine-events only when that engine implements zi-setup-event-v1.

Verification

go test ./...
go test -race ./...
go vet ./...

See architecture.md for the pilot boundary and test strategy.

Engine provenance

The embedded files are copied byte-for-byte from a documented z-shell/src commit. Their SHA-256 values are compiled into the client and verified before extraction. scripts/sync-engine.sh /path/to/src FULL_COMMIT_SHA reads every asset from that exact commit, even when the source checkout has local changes. Maintainers then update the pinned revision and reported hashes in internal/engine/bundle.go and run the full checks.