Skip to content

F28.1 — The home contract, env.sh and zsh completions

State Closed
Parent E28
Iteration Release 11
Start Date 2026-11-20
Closed Date 2026-11-20
Predecessors F23.2
Source kiln, 2026-11-20

Stories: 3 Closed

Story State Depends on
S28.1.1 — The home contract, and install writes env.sh Closed (2026-11-20) —
S28.1.2 — doctor reports the shell hookup Closed (2026-11-20) S28.1.1
S28.1.3 — PythonTool links a zsh completion script Closed (2026-11-20) S28.1.1

The rn-forge home gets one contract page. install writes the home's env.sh, doctor reports whether the shell is hooked up, and PythonTool links a zsh completion script. With those in place, <tool> <TAB> works in a fresh zsh that has sourced only env.sh.

Context

Found 2026-11-20 in kiln. kiln's CLI is a CliApp, which is a Typer app: it answers _KILN_COMPLETE=complete_zsh, and --install-completion is listed in --help. Even so, kiln <TAB> completes nothing:

  • install puts bin/<tool> in the home, but nothing puts $RNF_HOME/bin on PATH. Only macsetup's personal profile (macsetup-config's shared/profile.zsh) does that, along with fpath+=$RNF_HOME/completions.
  • No installer writes anything into completions/. macsetup links its own _rnfmac there by hand.

The layout is stated three times today: in this package's lifecycle guide, in shkit's install.sh comments, and in macsetup's runtime-layout.md. None of those statements is normative. ADR-0017 makes one of them the contract.

Design

The contract

S28.1.1 publishes this section, as written, as packages/rn-forge-tooling/docs/guides/home.md ("The rn-forge home").

$RNF_HOME/                  default ~/.rn-forge
  env.sh                    owned by the home; written by every installer
  bin/<command>             links, one per command a product puts on PATH
  completions/_<command>    links, one zsh completion script per command
  <product>/                the product's own; its layout is its business
  • Location. $RNF_HOME, or ~/.rn-forge when that is unset or empty.

  • Ownership. A product writes only inside <product>/ and the links it declares under bin/ and completions/. It never removes env.sh, bin/ or completions/, and it removes only links that still point where it put them.

  • Links point through the product's current, so an upgrade or rollback never touches them.

  • completions/ holds zsh completion functions named _<command>, the fpath convention. Nothing else goes there.

  • env.sh has exactly this text, with <home> replaced by the home's absolute path:

    # rn-forge home environment, schema 1. Written by rn-forge installers; do not edit.
    # Source it from your shell's rc file, before compinit: source "<home>/env.sh"
    export RNF_HOME="<home>"
    case ":${PATH}:" in
      *":${RNF_HOME}/bin:"*) ;;
      *) export PATH="${RNF_HOME}/bin:${PATH}" ;;
    esac
    if [ -n "${ZSH_VERSION:-}" ]; then
      fpath=("${RNF_HOME}/completions" "${fpath[@]}")
    fi
    
  • Writing env.sh. Every install writes env.sh when it is missing, or when its first line names a lower schema than the writer's. A file with the same schema or a higher one is left alone, so an older installer never downgrades it. A file whose first line is not a schema line is the user's: it is left alone, and the installer warns.

  • The hint. When $RNF_HOME/bin is not on PATH, an install ends by printing source "<home>/env.sh" and the advice to add that line to the rc file before compinit. No installer edits an rc file. macsetup, which owns its users' ~/.zshrc, sources env.sh from its profile.

  • Schema changes. A change to env.sh raises the schema number, changes this page, and ships in every writer.

rn-forge-tooling

  • rn_forge.tooling.install.home gains:

    • ENV_SCHEMA = 1, and ENV_TEMPLATE, the text above;
    • ToolHome.env_path (<home>/env.sh) and ToolHome.completions_dir (<home>/completions);
    • write_env(root: Path) -> EnvWrite, which applies the writing rule and returns which case happened: written, current (left alone, same or higher schema) or foreign (left alone, no schema line).
  • install calls write_env after it puts the links in place and before it migrates, as one more step of its transaction. On rollback it restores the previous file, or removes the file it created. A foreign result is a warning in the verb's output. When $RNF_HOME/bin is not on PATH, the verb's last output is the hint. upgrade does the same, because it installs. uninstall and cleanup never touch env.sh.

  • doctor gains three rows:

    Code Severity Meaning
    home.env-missing warning no env.sh
    home.env-stale warning env.sh names a lower schema; any install rewrites it
    home.not-on-path warning $RNF_HOME/bin is not on PATH; the message is the hint

    They are warnings, as install.not-installed is, because a development checkout has no hooked-up home and nothing is wrong with it.

  • PythonTool:

    • its build, after uv tool install, runs <version_dir>/bin/<name> with _<NAME>_COMPLETE=source_zsh, where <NAME> is the name upper-cased with - turned into _ (Click's rule: kiln-devops → _KILN_DEVOPS_COMPLETE). Its standard output is written to <version_dir>/completions/_<name>. A non-zero exit, or output whose first line is not #compdef <name>, is an AppException, and the install rolls back;
    • its default artifacts() becomes (Link("bin/<name>", "bin/<name>"), Link("completions/_<name>", "completions/_<name>")).

    The generated script is Typer's: a stub that asks the installed command for completions at <TAB> time. It stays correct across upgrades, because the command it calls resolves through current.

  • A non-Python product that ships a completion script declares a completions/_<name> link itself. This needs no new API.

  • Release. The new default link changes PythonTool.artifacts(), so this is rn-forge-tooling 0.4.0.

S28.1.1 — The home contract, and install writes env.sh

State: Closed (2026-11-20)

Acceptance:

  • packages/rn-forge-tooling/docs/guides/home.md holds The contract section as written, and is linked from the guides index. The lifecycle guide's layout section links to it and keeps only what is specific to this package (versions/, state.json, .lock/).
  • ENV_TEMPLATE rendered for a home equals the code block on that page, byte for byte. This is a test that reads the page, so the page and the code cannot drift.
  • write_env returns written for a missing file and for a schema-0 file; current for a schema-1 file and for a schema-2 file, which stays unchanged; and foreign for a file without a schema line, which stays unchanged. There is one test for each.
  • install into an empty home leaves env.sh. A failure injected after write_env restores the earlier env.sh, or removes it if it was created. There is one test for each.
  • uninstall leaves env.sh, bin/ and completions/ in place. This is a test.
  • install with $RNF_HOME/bin absent from PATH ends with the hint, and with it present does not. This is a test.
  • Sourcing env.sh in zsh -f puts $RNF_HOME/bin on PATH once, even when it is sourced twice, and puts $RNF_HOME/completions first on fpath. Sourcing it in bash sets PATH and does not fail. This is a test, skipped when zsh is not installed.
  • InstallResult carries env (the EnvWrite value, None when nothing was installed) and hint (env_hint, set on installed and already-current); the CLI prints a foreign warning, then the hint as its last output.

S28.1.2 — doctor reports the shell hookup

State: Closed (2026-11-20) · Depends on: S28.1.1

Acceptance:

  • doctor reports home.env-missing, home.env-stale and home.not-on-path as the Design table says, each as a warning, and none of them when the home is hooked up. There is one test for each.
  • The lifecycle guide's doctor table lists the three codes.
  • The home rows follow the install rows and precede the product's checks, and are reported whether or not the product is installed. A foreign env.sh gets no row.

State: Closed (2026-11-20) · Depends on: S28.1.1

Acceptance:

  • PythonTool.build, run on a minimal Typer tool tree (a CliApp is a Typer app), leaves <version_dir>/completions/_<name>, whose first line is #compdef <name>. After install, $RNF_HOME/completions/_<name> resolves through current. This is a test that needs uv, and is skipped without it.
  • In a tool whose name has a hyphen, the build uses _<NAME_WITH_UNDERSCORES>_COMPLETE. This is a test.
  • A console script that ignores the completion variable fails the build, and the install rolls back with nothing left under versions/. This is a test.
  • PythonTool().artifacts() is the two links in the Design. uninstall removes both. This is a test.
  • In zsh -f, after source $RNF_HOME/env.sh; autoload -Uz compinit; compinit, completing <tool> offers the tool's commands. This is a test that drives zsh with zpty, skipped when zsh is not installed.
  • The lifecycle guide's Python tools section covers the completion script.
  • The build strips the leading blank lines of Typer's script (compinit reads only the first line for #compdef) and appends a call to the script's compdef function, so the first <TAB> in a shell completes (owner, 2026-11-20). A script without #compdef <name> or a compdef line fails the build.
  • rn-forge-tooling is 0.4.0, and its changelog's [0.4.0] names the new default link as a change consumers see. After the release merge, the rn-forge-tooling-v0.4.0 tag exists on the remote and 0.4.0 installs from PyPI.

Acceptance

set -euo pipefail
task test -- rn-forge-tooling   # S28.1.1 S28.1.2 S28.1.3

Not scriptable: kiln F7.10 installs kiln from a ref into a fresh home, sources only env.sh in a new zsh, and records that kiln <TAB> lists kiln's commands.

Considered and rejected

  • Generate the completion script from a template in this package, instead of asking the built command. That would duplicate Typer's script and drift when Typer changes it. Asking the command also proves the command runs.
  • Bash completion as well. Bash has no fpath, so it would need a second file per command and a sourcing loop in env.sh. rn-forge tools run on macOS zsh. Add it with a schema bump when someone needs it.
  • Write env.sh outside the transaction, after current swaps. A failure there would leave a complete install that reports an error. Inside the transaction, the install and the hookup succeed or roll back together.