livery.toolroom.store._engine¶
livery.toolroom.store._engine ¶
The engine: a pinned tool installed from verified tiers, linked, emitted, fetched.
ensure lands a version's artifact by the record's digest through the store's
sources, and through the origin URL unless the store is offline;
extracts it, hoists the root, saves a bare file as its file, applies the
shims, collects the directory as a tree, moves tools/<name>@<version>
to it write-once, and views the tree at the home's tool directory. A
second ensure is a probe. link fills a checkout's bin directory
with one link per executable and removes only links it made. delta
is the PATH prepend and the env a set of installs contributes. fetch
lands every host's artifact into a store at another root, a mirror by
construction.
Nothing here prints; every step reaches the caller through the progress callback. Reach for livery.toolroom.store.Store.
Classes:
| Name | Description |
|---|---|
StoreError |
A tool the store cannot supply; the message names the tool and the reason. |
Event |
One step of the engine's work, as it starts or resolves. |
Ensured |
A tool version the store supplies. |
Delta |
What a set of installs adds to an environment. |
Fetched |
One artifact |
DamagedView |
A view the disk no longer holds whole: tool, version, the paths missing. |
Store |
The tool store: a home's objects, refs and views, driven by specs. |
Functions:
| Name | Description |
|---|---|
silent |
The default progress: drop the event. |
bun_global_project |
The global project bun installs into under install_root, made empty. |
npm_cli |
The |
Attributes:
| Name | Type | Description |
|---|---|---|
BY |
|
|
DEPLOYMENT |
The key beside a |
|
LINKS |
The manifest a bin directory keeps of the links the engine made there. |
|
Progress |
Receives every event; must not raise. |
|
download |
Callable[[str], bytes]
|
Fetches an origin URL. A variable, so a test hands the engine bytes |
run_installer_in |
Callable[[list[str], dict[str, str], Path], int]
|
Runs an installer inside a directory. A variable, so a test supplies the |
run_installer |
Callable[[list[str], dict[str, str]], int]
|
Runs a delegated kind's installer. A variable, so a test supplies the |
read_version |
Callable[[list[str]], str]
|
Reads what a system tool prints for its version flag. A variable, so a |
symlink |
Callable[[Path, Path], None]
|
Makes a symlink. A variable, so a test forces the launcher fallback |
DEPLOYMENT
module-attribute
¶
The key beside a tools/ ref naming the deployment that produced its tree.
LINKS
module-attribute
¶
The manifest a bin directory keeps of the links the engine made there.
Progress
module-attribute
¶
Receives every event; must not raise.
download
module-attribute
¶
Fetches an origin URL. A variable, so a test hands the engine bytes without a network.
run_installer_in
module-attribute
¶
Runs an installer inside a directory. A variable, so a test supplies the install without node.
run_installer
module-attribute
¶
Runs a delegated kind's installer. A variable, so a test supplies the install without uv or bun.
read_version
module-attribute
¶
Reads what a system tool prints for its version flag. A variable, so a test answers for the machine.
symlink
module-attribute
¶
Makes a symlink. A variable, so a test forces the launcher fallback where the platform would have allowed the link.
StoreError ¶
Bases: Exception
A tool the store cannot supply; the message names the tool and the reason.
Event
dataclass
¶
Ensured
dataclass
¶
Ensured(name: str, version: str, installed: bool, tool_dir: Path, deployment: Deployment, tree: Digest | None, answered: str = '')
A tool version the store supplies.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The tool. |
version |
str
|
The version. |
installed |
bool
|
True when this call installed it, False when it was present already. |
tool_dir |
Path
|
The view a shell runs from; a delegated kind's own directory under the home, or a system tool's directory. |
deployment |
Deployment
|
The host's deployment the install followed; for a
delegated kind, the entry points its installer wrote under
|
tree |
Digest | None
|
The tree |
answered |
str
|
The version a system tool printed when it was probed on the machine, so a receipt can say what answered; empty for a tool the store installed, and for one that prints no version. |
paths
property
¶
The directories the deployment puts on PATH, under the tool directory.
Delta
dataclass
¶
Fetched
dataclass
¶
DamagedView ¶
Store ¶
Store(home: Home, *, host: str = '', sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent)
The tool store: a home's objects, refs and views, driven by specs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
home
|
Home
|
The store's directories. |
required |
host
|
str
|
The host key installs follow; the running machine's by default. |
''
|
sources
|
Iterable[Source]
|
The tiers consulted before the origin, in order: a folder or an HTTP base in strongroom's layout. |
()
|
offline
|
bool
|
Never reach an origin; a miss fails closed. |
False
|
progress
|
Progress
|
Receives every event. |
silent
|
Methods:
| Name | Description |
|---|---|
probe |
The tool version when it is present here, else None; no source is consulted. |
ensure |
Supply the tool at version as its record resolves it on this host. |
supply |
Supply name at version from deployment or through its installer. |
stage |
Land deployment's artifact and unpack it into into, installing nothing. |
audit |
The paths of name's view at version the disk lacks; None without a view. |
audit_views |
Every view under the home that lacks files on disk, by tool and version. |
mend_view |
Make name's view at version whole again from the tree the store holds. |
link |
Fill into with one link per executable the installs put on PATH. |
delta |
The PATH prepend and env the installs contribute. |
fetch |
Land every version's artifact for hosts into a store at into. |
Attributes:
| Name | Type | Description |
|---|---|---|
home |
Home
|
|
host |
str
|
|
offline |
bool
|
|
objects |
Store
|
The strongroom store underneath. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
probe ¶
The tool version when it is present here, else None; no source is consulted.
Present means the ref names a tree made from this host's
deployment and a view of it was made at the tool's directory;
for a delegated kind, that its installer's directory holds what
it installed. Whether the view's files are all still on disk is
audit's question, asked by fm doctor and not on every sync.
Raises:
| Type | Description |
|---|---|
RecordError
|
for a version the record does not track, or a version without this host. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
ensure ¶
ensure(record: Record, version: str, *, runtime: Path | None = None, graph: Path | None = None) -> Ensured
Supply the tool at version as its record resolves it on this host.
runtime is the executable of the runtime an npm record
names, node unless it says bun, supplied by the caller first.
graph is the resolved set the lock pins for this version,
which a delegated kind installs instead of resolving.
Raises:
| Type | Description |
|---|---|
RecordError
|
for a version the record does not track, or a version without this host. |
StoreError
|
as |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
supply ¶
supply(name: str, kind: str, version: str, deployment: Deployment | None = None, *, package: str = '', min_version: str = '', runtime: str = '', runtime_exe: Path | None = None, graph: Path | None = None) -> Ensured
Supply name at version from deployment or through its installer.
An archive or binary lands its artifact by the deployment's
digest, extracts it, collects it as a tree and views it. A
pypi is installed by uv into its own directory under the
home, package naming what uv installs when it differs from the
tool's name, and its launchers are the entry points. An npm
tool is installed the same way through runtime_exe, the
executable of the runtime runtime names, node unless it says
bun, which the caller supplied first: npm run on node, or bun's
own installer. Its launchers start with #!/usr/bin/env node,
which the runtime answers on the caller's PATH, bun through the
node shim its record declares. A dotnet tool is installed
the same way through runtime_exe, the dotnet SDK's own
executable, with dotnet tool install --tool-path into its
own directory; its launchers are the shims the SDK writes,
which find the runtime through DOTNET_ROOT, the SDK
record's own environment. A system-check is the machine's
own tool, found on PATH and held to min_version. python
is not supplied through the store yet and refuses naming the
kind.
One process at a time supplies a version: the supply holds the version's lock in the home while it works, and a second supply waits for it, saying so through the progress, then finds the version present.
Raises:
| Type | Description |
|---|---|
StoreError
|
for a kind the store cannot supply, a downloaded
kind with no deployment, an |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
stage ¶
stage(name: str, kind: str, version: str, deployment: Deployment, into: Path, *, exclude: bool = True) -> tuple[str, ...]
Land deployment's artifact and unpack it into into, installing nothing.
The artifact comes from the tiers and, unless offline, the
origin; an archive is extracted and its declared root hoisted,
a bare file saved as its file, and with exclude the
deployment's exclusion patterns are applied. No entry point is
required, no shim is made, no tree is collected and no ref is
set: this is the look a check takes at a deployment for any
host from any machine, and the first half of an install.
Returns:
| Type | Description |
|---|---|
str
|
Every member of the unpacked tree before exclusion, as |
...
|
install-relative forward-slashed paths, in name order. |
Raises:
| Type | Description |
|---|---|
StoreError
|
for a miss while offline, a mismatch at a tier, an archive that will not extract, or a declared root the archive lacks. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
audit ¶
The paths of name's view at version the disk lacks; None without a view.
A walk of every path the view's record names, the check a sync
no longer pays: a view damaged by hand after it was made is
found here, named path by path, and mended by mend_view. An
empty tuple is a whole view. None is a tool with no view at the
directory, a delegated kind or one never supplied, which is the
sync's to supply and nothing to audit.
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
audit_views ¶
audit_views() -> tuple[DamagedView, ...]
Every view under the home that lacks files on disk, by tool and version.
The views are the store's own records, so nothing outside the store is read: no lock, no catalogue. A whole view is not listed. The paths are the view's, relative to the tool's directory.
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
mend_view ¶
Make name's view at version whole again from the tree the store holds.
The repair for a view audit or audit_views found damaged: the
view's record goes, which removes what the store created there
and nothing else, and the same tree is viewed again at the same
directory. The tree's blobs are in the object store already, so
nothing is fetched and no record of the tool is read. A whole
view is dropped and made again the same way.
Raises:
| Type | Description |
|---|---|
StoreError
|
when no view of the tool exists at the directory. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
link ¶
Fill into with one link per executable the installs put on PATH.
A link is a symlink where the platform allows one and a
launcher where it refuses; LINKS in into records what the
engine made, and a link it did not make is never removed. A
name two installs both offer goes to the first.
Returns:
| Type | Description |
|---|---|
tuple[Path, ...]
|
The links made, in order. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
delta ¶
The PATH prepend and env the installs contribute.
With bin_dir, the one directory on PATH is the bin directory
link filled, and the installs contribute their env only.
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
fetch ¶
fetch(records: Iterable[Record], *, hosts: Iterable[str] = HOSTS, into: Path) -> tuple[Fetched, ...]
Land every version's artifact for hosts into a store at into.
The folder is a mirror by construction: a source of this engine's layout. Bytes come from this store's sources and, unless offline, the origin; a mismatch refuses naming the tool.
Raises:
| Type | Description |
|---|---|
StoreError
|
for a miss while offline, or a mismatch. |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
bun_global_project ¶
The global project bun installs into under install_root, made empty.
bun's global install lives at <BUN_INSTALL>/install/global and
looks for the project to install into by walking up from there,
so with no project of its own it installs into the nearest
ancestor holding a package.json, a home directory's included.
An empty project made first is where the walk stops.
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
npm_cli ¶
The npm-cli.js node ships beside node, in either layout node publishes.
A POSIX distribution has bin/node and lib/node_modules/npm; a
Windows one has node.exe and node_modules/npm side by side.
Raises:
| Type | Description |
|---|---|
StoreError
|
naming both places when neither holds it. |