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:
installputsbin/<tool>in the home, but nothing puts$RNF_HOME/binonPATH. Only macsetup's personal profile (macsetup-config'sshared/profile.zsh) does that, along withfpath+=$RNF_HOME/completions.- No installer writes anything into
completions/. macsetup links its own_rnfmacthere 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-forgewhen that is unset or empty. -
Ownership. A product writes only inside
<product>/and the links it declares underbin/andcompletions/. It never removesenv.sh,bin/orcompletions/, 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>, thefpathconvention. Nothing else goes there. -
env.shhas 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 writesenv.shwhen 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/binis not onPATH, an install ends by printingsource "<home>/env.sh"and the advice to add that line to the rc file beforecompinit. No installer edits an rc file. macsetup, which owns its users'~/.zshrc, sourcesenv.shfrom its profile. -
Schema changes. A change to
env.shraises the schema number, changes this page, and ships in every writer.
rn-forge-tooling
-
rn_forge.tooling.install.homegains:ENV_SCHEMA = 1, andENV_TEMPLATE, the text above;ToolHome.env_path(<home>/env.sh) andToolHome.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) orforeign(left alone, no schema line).
-
installcallswrite_envafter 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. Aforeignresult is a warning in the verb's output. When$RNF_HOME/binis not onPATH, the verb's last output is the hint.upgradedoes the same, because it installs.uninstallandcleanupnever touchenv.sh. -
doctorgains three rows:Code Severity Meaning home.env-missingwarning no env.shhome.env-stalewarning env.shnames a lower schema; any install rewrites ithome.not-on-pathwarning $RNF_HOME/binis not onPATH; the message is the hintThey are warnings, as
install.not-installedis, because a development checkout has no hooked-up home and nothing is wrong with it. -
PythonTool:- its
build, afteruv 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 anAppException, 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 throughcurrent. - its
-
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 isrn-forge-tooling0.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.mdholds 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_TEMPLATErendered 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_envreturnswrittenfor a missing file and for a schema-0 file;currentfor a schema-1 file and for a schema-2 file, which stays unchanged; andforeignfor a file without a schema line, which stays unchanged. There is one test for each.installinto an empty home leavesenv.sh. A failure injected afterwrite_envrestores the earlierenv.sh, or removes it if it was created. There is one test for each.uninstallleavesenv.sh,bin/andcompletions/in place. This is a test.installwith$RNF_HOME/binabsent fromPATHends with the hint, and with it present does not. This is a test.- Sourcing
env.shinzsh -fputs$RNF_HOME/binonPATHonce, even when it is sourced twice, and puts$RNF_HOME/completionsfirst onfpath. Sourcing it inbashsetsPATHand does not fail. This is a test, skipped whenzshis not installed. InstallResultcarriesenv(theEnvWritevalue,Nonewhen nothing was installed) andhint(env_hint, set oninstalledandalready-current); the CLI prints aforeignwarning, 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:
doctorreportshome.env-missing,home.env-staleandhome.not-on-pathas 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
doctortable 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.shgets no row.
S28.1.3 — PythonTool links a zsh completion script
State: Closed (2026-11-20) · Depends on: S28.1.1
Acceptance:
PythonTool.build, run on a minimal Typer tool tree (aCliAppis a Typer app), leaves<version_dir>/completions/_<name>, whose first line is#compdef <name>. Afterinstall,$RNF_HOME/completions/_<name>resolves throughcurrent. This is a test that needsuv, 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.uninstallremoves both. This is a test.- In
zsh -f, aftersource $RNF_HOME/env.sh; autoload -Uz compinit; compinit, completing<tool>offers the tool's commands. This is a test that drives zsh withzpty, skipped whenzshis not installed. - The lifecycle guide's Python tools section covers the completion script.
- The build strips the leading blank lines of Typer's script (
compinitreads only the first line for#compdef) and appends a call to the script'scompdeffunction, so the first<TAB>in a shell completes (owner, 2026-11-20). A script without#compdef <name>or acompdefline fails the build. rn-forge-toolingis 0.4.0, and its changelog's[0.4.0]names the new default link as a change consumers see. After the release merge, thern-forge-tooling-v0.4.0tag exists on the remote and 0.4.0 installs from PyPI.
Acceptance
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 inenv.sh. rn-forge tools run on macOS zsh. Add it with a schema bump when someone needs it. - Write
env.shoutside the transaction, aftercurrentswaps. 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.