Skip to content

docs(zi-install): document machine setup interface #650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ss-o wants to merge 1 commit into from
Closed

docs(zi-install): document machine setup interface #650

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions .github/skills/zi-install/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,15 @@ Canonical long-form user guidance lives in the [Z-Shell Wiki: Installation](http

## Choose the profile

The installer entrypoint defaults to the `loader` profile. Supported profiles for agent-driven installation:
The installer entrypoint defaults to the `loader` profile. Profiles offered for a new installation:

| Profile | Command suffix | Effect on `.zshrc` |
| ------------ | -------------- | -------------------------------------------------------------- |
| Loader | `-a loader` | Adds the short managed block sourcing `setup.zsh` (default) |
| Annex | `-a annex` | Adds the short managed block with recommended annexes deferred |
| ZUnit | `-a zunit` | Adds the short managed block with annexes and ZUnit deferred |
| Install only | `-i skip` | No `.zshrc` change; the user integrates Zi themselves |

Prefer Loader for a new setup. Use `-i skip` when the user manages their dotfiles elsewhere; then hand them the block from the [installation page](https://wiki.zshell.dev/docs/getting_started/installation) instead of editing anything. `-b <ref>` selects a Zi branch or tag (defaults to `main`). Note that the direct profile (`-a direct`) is deprecated and mapped to `loader`.
Prefer Loader for a new setup. Never offer the `zunit` profile (`-a zunit`) for a new setup; it is compatibility-only and retained strictly so existing installations can be migrated without data loss. Use `-i skip` when the user manages their dotfiles elsewhere; then hand them the block from the [installation page](https://wiki.zshell.dev/docs/getting_started/installation) instead of editing anything. `-b <ref>` selects a Zi branch or tag (defaults to `main`). Note that the direct profile (`-a direct`) is deprecated and mapped to `loader`.

## Resolve the environment first

Expand Down Expand Up @@ -63,7 +62,7 @@ Report a failed fetch or a failed verification as a failed install; never procee
Read the result, do not assume it:

- exit 0 and `Successfully installed at <dir>`: proceed to verification. The closing `Successfully installed Zi.` banner confirms completion;
- `Zi installer: recipe installation is deferred to the first shell start.`: expected output when installing with `-a annex` or `-a zunit`; recipes install on first shell launch;
- `Zi installer: recipe installation is deferred to the first shell start.`: expected output when installing with `-a annex` (or compatibility `-a zunit`); recipes install on first shell launch;
- `Zi installer: the direct zi.zsh profile is deprecated; using the guided loader profile.`: informative notice if `-a direct` was passed;
- `managed .zshrc block changed outside Zi setup; apply the printed patch manually or restore the receipt state`: the managed block was modified; show the printed patch to the user and stop, do not overwrite;
- `unrecognised Zi integration remains in .zshrc; refusing to initialise Zi twice`: an existing unmanaged Zi integration was detected; report it as a conflict and let the user decide; do not edit `.zshrc` to force it;
Expand All @@ -78,7 +77,7 @@ Rerunning the installer is the update path: it fetches and fast-forwards the exi

## The managed .zshrc block

For integrated profiles (`loader`, `annex`, `zunit`), the installer writes or updates a short 3-line marker-delimited block in `${ZDOTDIR:-$HOME}/.zshrc`:
For integrated profiles (`loader`, `annex`, or compatibility `zunit`), the installer writes or updates a short 3-line marker-delimited block in `${ZDOTDIR:-$HOME}/.zshrc`:

```zsh
# >>> zi setup >>>
Expand All @@ -88,6 +87,22 @@ source '/absolute/path/to/config/zi/setup.zsh'

User dotfiles stay readable and minimal. Implementation details, path checks, error handling, loader startup (`init.zsh && zzinit`), and post-load recipes (`setup/shell.zsh`) are encapsulated in the generated `setup.zsh` entrypoint.

## Machine interface

When driving `setup.sh` directly or integrating with the setup engine, use the versioned machine interface rather than parsing human stdout or stderr:

- **Directory artifacts:** Commands communicate through private directory artifacts with fixed relative paths containing raw bytes or restricted tokens (avoiding shell-level JSON escaping):
- `setup.sh describe --output DIR`: Publishes a `zi-setup-describe-v1` artifact containing `facts/` and `profiles/` (`loader` and `annex`; legacy `zunit` is marked `selectable=no` if detected). Exits 3 if all profiles are blocked.
- `setup.sh plan --plan DIR`: Publishes a deterministic `zi-setup-plan-v1` artifact containing `plan.id`, `plan.meta`, `checkout/`, `targets/`, `operations/`, and `warnings/`.
- `setup.sh apply --plan DIR --phase checkout|files [--expect SHA256] [--result DIR]`: Applies the plan phase-by-phase.
- **Exact plan-id approval:** The plan hash covers all artifact files except `plan.id`. Clients must record the reviewed `plan.id` and pass it via `--expect` for both checkout and files phases. Changed artifact content produces `plan-changed`; changed live checkout or file preconditions produce `checkout-drift` or `target-drift`.
- **Result artifacts:** Passing `--result DIR` to `apply` publishes a `zi-setup-result-v1` artifact containing `format`, `plan.id`, `phase`, `status` (`succeeded`, `failed`, `cancelled`), `operations/`, `error/code`, `error/operation`, `error/detail`, and `receipt/path`.
- **Stable exit statuses and error codes:**
- Exit statuses: `0` (success), `2` (invocation or unsupported version), `3` (non-actionable discovery/plan), `4` (precondition changed / plan changed / drift), `5` (apply operation began but did not complete), `6` (cancelled).
- Error codes (`error/code`): stable ASCII identifiers including `unsupported-version`, `plan-changed`, `target-drift`, `checkout-drift`, `lock-held`, `network-failed`, `checkout-failed`, `write-failed`, and `cancelled`.
- **Untrusted display text:** Operation summaries and warnings are display text. Clients must treat them as untrusted terminal content and strip or visibly escape control sequences. Decisions must rely solely on IDs and restricted tokens, never on display text.
- **Do not parse human stdout/stderr:** Engine stdout and stderr are strictly for user presentation or diagnostics; their wording carries no compatibility promise. Never parse human stdout or stderr to make decisions; consume only documented directory artifacts and exit statuses.

## Verify

Start a fresh interactive shell, the way the user will, and ask Zi for its help text:
Expand Down Expand Up @@ -118,4 +133,4 @@ For `-i skip`, verify only that `zi.zsh` exists beneath the directory the instal

## Report

State the profile used, the exact files created or changed, what was preserved, any installer messages or refusals verbatim, and the next step for the user: `exec zsh` after integrated installation (`loader`, `annex`, `zunit`); or for `-i skip`, first add the integration block from the [installation page](https://wiki.zshell.dev/docs/getting_started/installation) to their own `.zshrc`, then `exec zsh`.
State the profile used, the exact files created or changed, what was preserved, any installer messages or refusals verbatim, and the next step for the user: `exec zsh` after integrated installation (`loader`, `annex`, or compatibility `zunit`); or for `-i skip`, first add the integration block from the [installation page](https://wiki.zshell.dev/docs/getting_started/installation) to their own `.zshrc`, then `exec zsh`.
Loading