ADR-0017: The rn-forge home is a written contract that every installer implements, and the home owns the shell hookup
Status: accepted (2026-11-20) · Scope: rn_forge.tooling.install, and
every rn-forge installer in any language
Decision
$RNF_HOME (default ~/.rn-forge) is defined by one contract page,
packages/rn-forge-tooling/docs/guides/home.md. pykit owns the page. Each
installer implements it in its own language: rn-forge-tooling for Python
tools, and shkit's install.sh for shell products. No shared package carries
it.
The contract covers only what products share: bin/, completions/, env.sh,
and the rule that a product writes only inside <product>/ and its own links.
What a product keeps under <product>/ is the product's business.
The home owns one shell file, $RNF_HOME/env.sh. It puts bin/ on PATH and,
under zsh, puts completions/ on fpath. Every installer writes it when it is
missing or has an older schema, and prints the line that sources it when bin/
is not on PATH. No installer edits a user's rc file.
A Python tool's install also links a zsh completion script, generated from its
own CLI, into completions/.
Consequences
- A tool installed without macsetup is one
sourceline away from working completion. A tool installed with macsetup needs no extra step. - macsetup's profile sources
env.shand stops restating the PATH andfpathlines. - Two writers, one in Python and one in shell, write the same file. Each repo pins its output to the text on the contract page with a test, and the schema line decides which writer may replace it.
PythonTool's defaultartifacts()gains a second link, so a product that asserts its exact links sees a change. That makes thern-forge-toolingrelease that carries it a minor one.- Completion covers zsh only. A bash user gets
PATHbut no completion.
Influences
- F28.1 implements this decision.
- Found 2026-11-20 in kiln:
kiln <TAB>completed nothing outside macsetup's profile, though kiln's Typer CLI answers completion requests.
Alternatives considered
- A shared package that every tool imports. The products are both shell and
Python, so no single library can serve them all. For Python tools,
rn-forge-toolingalready is that library. - macsetup's profile owns the hookup. It is personal machine configuration,
so anyone without macsetup gets no
PATHand no completion. - Installers edit
~/.zshrc. It is invasive, hard to undo, and breaks people who manage their own rc files. Printing the line is what rustup and sdkman do. - Typer's
--install-completion, writing to~/.zfunc. It is per tool and per user action, lives outside the home, and survives an uninstall. It stays available, but it is not the supported route.