Skip to content

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 source line away from working completion. A tool installed with macsetup needs no extra step.
  • macsetup's profile sources env.sh and stops restating the PATH and fpath lines.
  • 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 default artifacts() gains a second link, so a product that asserts its exact links sees a change. That makes the rn-forge-tooling release that carries it a minor one.
  • Completion covers zsh only. A bash user gets PATH but 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-tooling already is that library.
  • macsetup's profile owns the hookup. It is personal machine configuration, so anyone without macsetup gets no PATH and 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.