Skip to content

Install

rn_forge.tooling.install

Release sources, workstation installation, and lifecycle operations.

Check = Callable[[ToolHome], Iterable[Finding]] module-attribute

A product-specific doctor check: inspect the install, report what is true of it.

Report a passing check as an info finding rather than nothing, so doctor shows that it ran.

CleanupResult(product, kept, removed=list[str](), dry_run=False) dataclass

Bases: DataclassMixin

What cleanup removed, or would remove.

Parameters:

Name Type Description Default
product str

The product name.

required
kept str

The active version.

required
removed list[str]

The versions removed — or, on a dry run, to be removed.

list[str]()
dry_run bool

Whether anything was actually removed.

False

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

EnvWrite

Bases: StrEnum

What :func:write_env did.

CURRENT = 'current' class-attribute instance-attribute

The file has the same or a newer schema, and was left alone.

FOREIGN = 'foreign' class-attribute instance-attribute

The file has no schema line, so it is not ours, and was left alone.

WRITTEN = 'written' class-attribute instance-attribute

The file was missing or older, and was written.

GitHubReleases(repo, tag_prefix='v', api_url='https://api.github.com', web_url='https://github.com') dataclass

Releases published as tags of a GitHub repository.

The archive is GitHub's generated source tarball for the tag. GitHub publishes no checksum for those, so :meth:checksum returns None and the download is trusted to TLS; a product that attaches a checksum asset to its releases implements :class:ReleaseSource to verify it.

Parameters:

Name Type Description Default
repo str

owner/name.

required
tag_prefix str

What the tag carries before the version — "v" for v1.2.0, "golden-tool-v" in a monorepo.

'v'
api_url str

The GitHub API root, for GitHub Enterprise.

'https://api.github.com'
web_url str

The GitHub web root the tarball is served from.

'https://github.com'

checksum(version)

None: GitHub publishes no checksum for a generated tarball.

download(version, destination)

Download the tag's source tarball into destination.

Raises:

Type Description
AppException

The download failed.

download_commit(sha, destination)

Download the source tarball of commit sha into destination.

Raises:

Type Description
AppException

The download failed.

latest()

Return the version of the repository's latest release.

Raises:

Type Description
AppException

The request failed, or the latest release's tag does not carry :attr:tag_prefix.

resolve(ref)

Return the 40-character commit SHA that a branch, tag or SHA names.

Raises:

Type Description
AppException

The request failed, the ref does not exist, or the response carries no valid SHA.

InstallResult(product, outcome, version=None, previous=None, env=None, hint=None) dataclass

Bases: DataclassMixin

What install, upgrade or uninstall did.

Parameters:

Name Type Description Default
product str

The product name.

required
outcome str

installed, already-current, removed or not-installed.

required
version str | None

The version now active, when there is one.

None
previous str | None

The version that was active before, when there was one.

None
env str | None

What the install did to env.sh (an :class:EnvWrite value), or None when nothing was installed.

None
hint str | None

How to source env.sh, when bin/ is not on PATH after an install; None otherwise.

None

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

InstallStatus(product, version, home, installed=None, versions=list[str](), ref=None, commit=None, package_version=None) dataclass

Bases: DataclassMixin

Where a product is installed, and at what version.

Parameters:

Name Type Description Default
product str

The product name.

required
version str

The version of the running code.

required
home str

The product's directory.

required
installed str | None

The version current points at, or None.

None
versions list[str]

Every version directory present.

list[str]()
ref str | None

What the install was asked for: a branch, tag or commit SHA, or the release tag. None when nothing is recorded.

None
commit str | None

The installed commit's SHA for a ref install, else None.

None
package_version str | None

The package version recorded at install, or None.

None

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

A symlink an install puts in place outside the version directory.

The link points through current, never at a version directory, so an upgrade swaps what it resolves to without touching the link.

Parameters:

Name Type Description Default
path str

Where the link goes, relative to $RNF_HOME — bin/golden-tool.

required
target str

What it points at, relative to the installed version's root.

required

LocalArchive(path, version, sha256=None) dataclass

One archive already on disk, standing in for a release.

Parameters:

Name Type Description Default
path Path

The archive file.

required
version str

The version the archive holds. Not inferred from its contents: reading a version out of a tree is the product's convention, not this module's.

required
sha256 str | None

The digest to verify against, when known.

None

checksum(version)

The digest given at construction, if any.

download(version, destination)

Copy the archive into destination.

Raises:

Type Description
AppException

version is not the archive's, or the file is missing.

latest()

The archive's own version — it is the only one there is.

PythonTool(name, version, repo=None, release_source=None, state_schema_version=1) dataclass

Bases: ToolProduct

A Python tool installed with uv tool install.

The package must declare a console script named :attr:name, and that script must be a Typer (or Click) command: the build asks it for its zsh completion script. uv must be on PATH; it is a program, not a dependency.

source property

The release source to fetch from.

Raises:

Type Description
AppException

Neither release_source nor repo was given.

artifacts()

The links bin/<name> to the console script and completions/_<name>.

build(release_root, version_dir)

Install the package at release_root into version_dir.

The console script ends up at <version_dir>/bin/<name> and its zsh completion script at <version_dir>/completions/_<name>.

Raises:

Type Description
AppException

uv tool install failed, or the command did not answer the completion variable with a zsh completion script.

checks()

Product-specific doctor checks. Default: none.

migrate(frm, to)

Move the product's state from version frm to version to. Default: nothing.

Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.

preflight()

Refuse the install when uv is not on PATH.

Raises:

Type Description
AppException

uv was not found.

ReleaseSource

Bases: Protocol

Where a product's releases are published.

checksum(version)

Return the SHA-256 hex digest version's archive must match, if published.

download(version, destination)

Write the archive for version into the directory destination.

Returns:

Type Description
Path

The archive file.

latest()

Return the newest released version.

ToolHome(name, root=None)

The on-disk layout of one product under $RNF_HOME.

Initialize :class:ToolHome.

Parameters:

Name Type Description Default
name str

The product name; its directory under root.

required
root str | Path | None

The home directory. Defaults to :func:rnf_home, resolved now rather than per access, so one instance never straddles a change to the environment.

None

Raises:

Type Description
AppException

name is not a single path segment.

completions_dir property

<home>/completions/.

current property

The current symlink. May not exist.

env_path property

<home>/env.sh, owned by the home rather than the product.

product_dir property

<home>/<product>/.

state_path property

<home>/<product>/state.json.

versions_dir property

<home>/<product>/versions/.

work_dir property

Scratch space holding unique transaction directories.

A failed restoration retains its displaced version here; cleanup keeps it.

activate(version)

Point current at version, atomically.

The link is relative (versions/<version>), so moving the whole home does not break it.

current_version()

The version current points at, or None when there is no link.

installed_versions()

Every version directory present, in name order.

lock(*, timeout=30.0)

The lock every lifecycle verb that writes holds for its whole duration.

version_dir(version)

<home>/<product>/versions/<version>/.

Raises:

Type Description
AppException

version is not a single path segment — a release source is remote input, and ../.. is a version string too.

ToolProduct(name, version, repo=None, release_source=None, state_schema_version=1) dataclass

An installable tool, as the lifecycle verbs see it.

Parameters:

Name Type Description Default
name str

The product's name, and its directory under $RNF_HOME.

required
version str

The version of the running code — normally the package's __version__.

required
repo str | None

owner/name of the GitHub repository releases are tagged in. Used only when release_source is not given.

None
release_source ReleaseSource | None

Where releases come from. Defaults to :class:GitHubReleases of repo.

None
state_schema_version int

The version of whatever state the product keeps under its home. doctor reports an install recorded at another one; :meth:migrate is what moves it.

1

source property

The release source to fetch from.

Raises:

Type Description
AppException

Neither release_source nor repo was given.

artifacts()

What an install puts in place beside the version directory. Default: nothing.

build(release_root, version_dir)

Turn an extracted release into an installed version directory.

The default copies the release tree. Implementations that create path-dependent artifacts must build them directly in version_dir.

Parameters:

Name Type Description Default
release_root Path

The extracted release's root directory.

required
version_dir Path

The directory to populate. Does not exist yet.

required

checks()

Product-specific doctor checks. Default: none.

migrate(frm, to)

Move the product's state from version frm to version to. Default: nothing.

Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.

preflight()

Called by install before anything is written. Default: nothing.

Raises:

Type Description
AppException

To refuse the install.

cleanup(product, *, home=None, dry_run=False)

Remove every installed version except the active one, and leftover scratch space.

Raises:

Type Description
AppException

There is no active version to keep.

doctor(product, *, home=None)

Inspect the install, then run the product's own checks.

A product that is not installed is a warning, not an error: the same command runs from a development checkout, where there is nothing under $RNF_HOME and nothing wrong. The home.* rows are warnings for the same reason: a development checkout has no hooked-up home. Both they and the product's checks run either way.

Returns:

Type Description
list[Finding]

Every finding, product checks last. Only an error should fail the

list[Finding]

command.

env_hint(root)

Return how to source env.sh, or None when <root>/bin is on PATH.

env_schema(root)

Return the schema number on the first line of <root>/env.sh.

Returns:

Type Description
int | None

The number, or None when the file is missing or empty, or its first

int | None

line is not the schema line, so the file is not ours.

extract_archive(archive, destination, *, filter='data')

Extract a .tar/.zip archive into destination, returning its root dir.

Parameters:

Name Type Description Default
archive str | Path

The archive file. Tar formats (.tar, .tar.gz, .tar.bz2, ...) are detected by content; anything else is treated as a zip.

required
destination str | Path

Directory the archive's contents are extracted into. Created if absent.

required
filter Literal['data', 'tar', 'fully_trusted']

The :func:tarfile.TarFile.extractall extraction filter for tar archives. Zip extraction has no equivalent parameter.

'data'

Returns:

Type Description
Path

The single top-level directory the archive extracted into.

Raises:

Type Description
AppException

The archive's root does not contain exactly one directory.

fetch_release(source, version, workdir)

Download version from source into workdir, verify it, and extract it.

Parameters:

Name Type Description Default
source ReleaseSource

Where the release is published.

required
version str

The version to fetch.

required
workdir str | Path

A scratch directory; created if absent. The archive and its extracted tree are left here for the caller to clean up.

required

Returns:

Type Description
Path

The archive's single root directory.

Raises:

Type Description
AppException

The download failed, the archive does not match the published checksum, or it does not have exactly one root directory.

install(product, *, version=None, source=None, home=None, force=False, ref=None)

Install version of product, or the commit ref names, and make it active.

Parameters:

Name Type Description Default
product ToolProduct

The product to install.

required
version str | None

The version to install. Defaults to the source's latest. Not combined with ref.

None
source ReleaseSource | None

Where to fetch from. Defaults to product.source.

None
home ToolHome | None

The home to install into. Defaults to the product's.

None
force bool

Reinstall even when version is already active.

False
ref str | None

A branch, tag or commit SHA of the source's GitHub repository. The install is recorded under the first 12 characters of the commit.

None

Raises:

Type Description
AppException

Both version and ref were given, ref was given for a source that is not a :class:GitHubReleases, the product's preflight refused, or a step failed; all undo steps were attempted, with any recovery failures and retained displaced version's path reported.

BaseException

An interruption, re-raised after recovery with any recovery failures and retained path logged at error level.

rnf_home()

Return $RNF_HOME, or ~/.rn-forge when it is unset or empty.

status(product, *, home=None)

Report the running version and what is installed. Writes nothing.

uninstall(product, *, home=None)

Remove the product's links and its whole directory under the home.

Works over an install that never completed: nothing here assumes current or state.json exists. A link is removed only when it still points where this product put it — a path someone has since replaced with their own file or link is left alone.

upgrade(product, *, source=None, home=None)

Move an existing install forward.

A ref install re-resolves its recorded ref and installs that commit, or returns already-current when it has not moved. Any other install moves to the source's latest version.

Raises:

Type Description
AppException

The product is not installed, or the install failed.

write_env(root)

Write <root>/env.sh when it is missing or names a lower schema.

Parameters:

Name Type Description Default
root Path

The home directory; created when absent.

required

Returns:

Type Description
EnvWrite

Which case applied. A file with the same or a higher schema, or with no

EnvWrite

schema line, is left unchanged.

Home

rn_forge.tooling.install.home

Filesystem layout and activation for installed tools.

DEFAULT_RNF_HOME = '~/.rn-forge' module-attribute

The home used when :data:RNF_HOME_ENV is unset or empty.

ENV_SCHEMA = 1 module-attribute

The schema number of the env.sh this package writes.

ENV_TEMPLATE = '# rn-forge home environment, schema 1. Written by rn-forge installers; do not edit.\n# Source it from your shell\'s rc file, before compinit: source "<home>/env.sh"\nexport RNF_HOME="<home>"\ncase ":${PATH}:" in\n *":${RNF_HOME}/bin:"*) ;;\n *) export PATH="${RNF_HOME}/bin:${PATH}" ;;\nesac\nif [ -n "${ZSH_VERSION:-}" ]; then\n fpath=("${RNF_HOME}/completions" "${fpath[@]}")\nfi\n' module-attribute

The env.sh text, with <home> standing for the home's absolute path.

RNF_HOME_ENV = 'RNF_HOME' module-attribute

The environment variable that relocates every installed tool.

EnvWrite

Bases: StrEnum

What :func:write_env did.

CURRENT = 'current' class-attribute instance-attribute

The file has the same or a newer schema, and was left alone.

FOREIGN = 'foreign' class-attribute instance-attribute

The file has no schema line, so it is not ours, and was left alone.

WRITTEN = 'written' class-attribute instance-attribute

The file was missing or older, and was written.

ToolHome(name, root=None)

The on-disk layout of one product under $RNF_HOME.

Initialize :class:ToolHome.

Parameters:

Name Type Description Default
name str

The product name; its directory under root.

required
root str | Path | None

The home directory. Defaults to :func:rnf_home, resolved now rather than per access, so one instance never straddles a change to the environment.

None

Raises:

Type Description
AppException

name is not a single path segment.

completions_dir property

<home>/completions/.

current property

The current symlink. May not exist.

env_path property

<home>/env.sh, owned by the home rather than the product.

product_dir property

<home>/<product>/.

state_path property

<home>/<product>/state.json.

versions_dir property

<home>/<product>/versions/.

work_dir property

Scratch space holding unique transaction directories.

A failed restoration retains its displaced version here; cleanup keeps it.

activate(version)

Point current at version, atomically.

The link is relative (versions/<version>), so moving the whole home does not break it.

current_version()

The version current points at, or None when there is no link.

installed_versions()

Every version directory present, in name order.

lock(*, timeout=30.0)

The lock every lifecycle verb that writes holds for its whole duration.

version_dir(version)

<home>/<product>/versions/<version>/.

Raises:

Type Description
AppException

version is not a single path segment — a release source is remote input, and ../.. is a version string too.

env_hint(root)

Return how to source env.sh, or None when <root>/bin is on PATH.

env_schema(root)

Return the schema number on the first line of <root>/env.sh.

Returns:

Type Description
int | None

The number, or None when the file is missing or empty, or its first

int | None

line is not the schema line, so the file is not ours.

render_env(root)

Return :data:ENV_TEMPLATE for the home at root, as an absolute path.

rnf_home()

Return $RNF_HOME, or ~/.rn-forge when it is unset or empty.

write_env(root)

Write <root>/env.sh when it is missing or names a lower schema.

Parameters:

Name Type Description Default
root Path

The home directory; created when absent.

required

Returns:

Type Description
EnvWrite

Which case applied. A file with the same or a higher schema, or with no

EnvWrite

schema line, is left unchanged.

Product

rn_forge.tooling.install.product

Product description consumed by tool lifecycle operations.

Check = Callable[[ToolHome], Iterable[Finding]] module-attribute

A product-specific doctor check: inspect the install, report what is true of it.

Report a passing check as an info finding rather than nothing, so doctor shows that it ran.

A symlink an install puts in place outside the version directory.

The link points through current, never at a version directory, so an upgrade swaps what it resolves to without touching the link.

Parameters:

Name Type Description Default
path str

Where the link goes, relative to $RNF_HOME — bin/golden-tool.

required
target str

What it points at, relative to the installed version's root.

required

ToolProduct(name, version, repo=None, release_source=None, state_schema_version=1) dataclass

An installable tool, as the lifecycle verbs see it.

Parameters:

Name Type Description Default
name str

The product's name, and its directory under $RNF_HOME.

required
version str

The version of the running code — normally the package's __version__.

required
repo str | None

owner/name of the GitHub repository releases are tagged in. Used only when release_source is not given.

None
release_source ReleaseSource | None

Where releases come from. Defaults to :class:GitHubReleases of repo.

None
state_schema_version int

The version of whatever state the product keeps under its home. doctor reports an install recorded at another one; :meth:migrate is what moves it.

1

source property

The release source to fetch from.

Raises:

Type Description
AppException

Neither release_source nor repo was given.

artifacts()

What an install puts in place beside the version directory. Default: nothing.

build(release_root, version_dir)

Turn an extracted release into an installed version directory.

The default copies the release tree. Implementations that create path-dependent artifacts must build them directly in version_dir.

Parameters:

Name Type Description Default
release_root Path

The extracted release's root directory.

required
version_dir Path

The directory to populate. Does not exist yet.

required

checks()

Product-specific doctor checks. Default: none.

migrate(frm, to)

Move the product's state from version frm to version to. Default: nothing.

Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.

preflight()

Called by install before anything is written. Default: nothing.

Raises:

Type Description
AppException

To refuse the install.

Python tool

rn_forge.tooling.install.python

A product whose release is a Python package with a console script.

PythonTool(name, version, repo=None, release_source=None, state_schema_version=1) dataclass

Bases: ToolProduct

A Python tool installed with uv tool install.

The package must declare a console script named :attr:name, and that script must be a Typer (or Click) command: the build asks it for its zsh completion script. uv must be on PATH; it is a program, not a dependency.

source property

The release source to fetch from.

Raises:

Type Description
AppException

Neither release_source nor repo was given.

artifacts()

The links bin/<name> to the console script and completions/_<name>.

build(release_root, version_dir)

Install the package at release_root into version_dir.

The console script ends up at <version_dir>/bin/<name> and its zsh completion script at <version_dir>/completions/_<name>.

Raises:

Type Description
AppException

uv tool install failed, or the command did not answer the completion variable with a zsh completion script.

checks()

Product-specific doctor checks. Default: none.

migrate(frm, to)

Move the product's state from version frm to version to. Default: nothing.

Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.

preflight()

Refuse the install when uv is not on PATH.

Raises:

Type Description
AppException

uv was not found.

Release

rn_forge.tooling.install.release

Release sources, download verification, and extraction.

GitHubReleases(repo, tag_prefix='v', api_url='https://api.github.com', web_url='https://github.com') dataclass

Releases published as tags of a GitHub repository.

The archive is GitHub's generated source tarball for the tag. GitHub publishes no checksum for those, so :meth:checksum returns None and the download is trusted to TLS; a product that attaches a checksum asset to its releases implements :class:ReleaseSource to verify it.

Parameters:

Name Type Description Default
repo str

owner/name.

required
tag_prefix str

What the tag carries before the version — "v" for v1.2.0, "golden-tool-v" in a monorepo.

'v'
api_url str

The GitHub API root, for GitHub Enterprise.

'https://api.github.com'
web_url str

The GitHub web root the tarball is served from.

'https://github.com'

checksum(version)

None: GitHub publishes no checksum for a generated tarball.

download(version, destination)

Download the tag's source tarball into destination.

Raises:

Type Description
AppException

The download failed.

download_commit(sha, destination)

Download the source tarball of commit sha into destination.

Raises:

Type Description
AppException

The download failed.

latest()

Return the version of the repository's latest release.

Raises:

Type Description
AppException

The request failed, or the latest release's tag does not carry :attr:tag_prefix.

resolve(ref)

Return the 40-character commit SHA that a branch, tag or SHA names.

Raises:

Type Description
AppException

The request failed, the ref does not exist, or the response carries no valid SHA.

LocalArchive(path, version, sha256=None) dataclass

One archive already on disk, standing in for a release.

Parameters:

Name Type Description Default
path Path

The archive file.

required
version str

The version the archive holds. Not inferred from its contents: reading a version out of a tree is the product's convention, not this module's.

required
sha256 str | None

The digest to verify against, when known.

None

checksum(version)

The digest given at construction, if any.

download(version, destination)

Copy the archive into destination.

Raises:

Type Description
AppException

version is not the archive's, or the file is missing.

latest()

The archive's own version — it is the only one there is.

ReleaseSource

Bases: Protocol

Where a product's releases are published.

checksum(version)

Return the SHA-256 hex digest version's archive must match, if published.

download(version, destination)

Write the archive for version into the directory destination.

Returns:

Type Description
Path

The archive file.

latest()

Return the newest released version.

fetch_release(source, version, workdir)

Download version from source into workdir, verify it, and extract it.

Parameters:

Name Type Description Default
source ReleaseSource

Where the release is published.

required
version str

The version to fetch.

required
workdir str | Path

A scratch directory; created if absent. The archive and its extracted tree are left here for the caller to clean up.

required

Returns:

Type Description
Path

The archive's single root directory.

Raises:

Type Description
AppException

The download failed, the archive does not match the published checksum, or it does not have exactly one root directory.

Lifecycle

rn_forge.tooling.install.lifecycle

Transactional install, upgrade, removal, status, and diagnostic operations.

CleanupResult(product, kept, removed=list[str](), dry_run=False) dataclass

Bases: DataclassMixin

What cleanup removed, or would remove.

Parameters:

Name Type Description Default
product str

The product name.

required
kept str

The active version.

required
removed list[str]

The versions removed — or, on a dry run, to be removed.

list[str]()
dry_run bool

Whether anything was actually removed.

False

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

InstallResult(product, outcome, version=None, previous=None, env=None, hint=None) dataclass

Bases: DataclassMixin

What install, upgrade or uninstall did.

Parameters:

Name Type Description Default
product str

The product name.

required
outcome str

installed, already-current, removed or not-installed.

required
version str | None

The version now active, when there is one.

None
previous str | None

The version that was active before, when there was one.

None
env str | None

What the install did to env.sh (an :class:EnvWrite value), or None when nothing was installed.

None
hint str | None

How to source env.sh, when bin/ is not on PATH after an install; None otherwise.

None

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

InstallStatus(product, version, home, installed=None, versions=list[str](), ref=None, commit=None, package_version=None) dataclass

Bases: DataclassMixin

Where a product is installed, and at what version.

Parameters:

Name Type Description Default
product str

The product name.

required
version str

The version of the running code.

required
home str

The product's directory.

required
installed str | None

The version current points at, or None.

None
versions list[str]

Every version directory present.

list[str]()
ref str | None

What the install was asked for: a branch, tag or commit SHA, or the release tag. None when nothing is recorded.

None
commit str | None

The installed commit's SHA for a ref install, else None.

None
package_version str | None

The package version recorded at install, or None.

None

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

cleanup(product, *, home=None, dry_run=False)

Remove every installed version except the active one, and leftover scratch space.

Raises:

Type Description
AppException

There is no active version to keep.

doctor(product, *, home=None)

Inspect the install, then run the product's own checks.

A product that is not installed is a warning, not an error: the same command runs from a development checkout, where there is nothing under $RNF_HOME and nothing wrong. The home.* rows are warnings for the same reason: a development checkout has no hooked-up home. Both they and the product's checks run either way.

Returns:

Type Description
list[Finding]

Every finding, product checks last. Only an error should fail the

list[Finding]

command.

install(product, *, version=None, source=None, home=None, force=False, ref=None)

Install version of product, or the commit ref names, and make it active.

Parameters:

Name Type Description Default
product ToolProduct

The product to install.

required
version str | None

The version to install. Defaults to the source's latest. Not combined with ref.

None
source ReleaseSource | None

Where to fetch from. Defaults to product.source.

None
home ToolHome | None

The home to install into. Defaults to the product's.

None
force bool

Reinstall even when version is already active.

False
ref str | None

A branch, tag or commit SHA of the source's GitHub repository. The install is recorded under the first 12 characters of the commit.

None

Raises:

Type Description
AppException

Both version and ref were given, ref was given for a source that is not a :class:GitHubReleases, the product's preflight refused, or a step failed; all undo steps were attempted, with any recovery failures and retained displaced version's path reported.

BaseException

An interruption, re-raised after recovery with any recovery failures and retained path logged at error level.

status(product, *, home=None)

Report the running version and what is installed. Writes nothing.

uninstall(product, *, home=None)

Remove the product's links and its whole directory under the home.

Works over an install that never completed: nothing here assumes current or state.json exists. A link is removed only when it still points where this product put it — a path someone has since replaced with their own file or link is left alone.

upgrade(product, *, source=None, home=None)

Move an existing install forward.

A ref install re-resolves its recorded ref and installs that commit, or returns already-current when it has not moved. Any other install moves to the source's latest version.

Raises:

Type Description
AppException

The product is not installed, or the install failed.

Archive

rn_forge.tooling.install.archive

Safe extraction of single-root tar and zip release bundles.

extract_archive(archive, destination, *, filter='data')

Extract a .tar/.zip archive into destination, returning its root dir.

Parameters:

Name Type Description Default
archive str | Path

The archive file. Tar formats (.tar, .tar.gz, .tar.bz2, ...) are detected by content; anything else is treated as a zip.

required
destination str | Path

Directory the archive's contents are extracted into. Created if absent.

required
filter Literal['data', 'tar', 'fully_trusted']

The :func:tarfile.TarFile.extractall extraction filter for tar archives. Zip extraction has no equivalent parameter.

'data'

Returns:

Type Description
Path

The single top-level directory the archive extracted into.

Raises:

Type Description
AppException

The archive's root does not contain exactly one directory.