Skip to content

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 fetch landed or found in the mirror.

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 npm-cli.js node ships beside node, in either layout node publishes.

Attributes:

Name Type Description
BY
DEPLOYMENT

The key beside a tools/ ref naming the deployment that produced its tree.

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

BY module-attribute

BY = _by()

DEPLOYMENT module-attribute

DEPLOYMENT = 'deployment'

The key beside a tools/ ref naming the deployment that produced its tree.

LINKS = '.links.json'

The manifest a bin directory keeps of the links the engine made there.

Progress module-attribute

Progress = Callable[[Event], None]

Receives every event; must not raise.

download module-attribute

download: Callable[[str], bytes] = _download

Fetches an origin URL. A variable, so a test hands the engine bytes without a network.

run_installer_in module-attribute

run_installer_in: Callable[[list[str], dict[str, str], Path], int] = _run_installer_in

Runs an installer inside a directory. A variable, so a test supplies the install without node.

run_installer module-attribute

run_installer: Callable[[list[str], dict[str, str]], int] = _run_installer

Runs a delegated kind's installer. A variable, so a test supplies the install without uv or bun.

read_version module-attribute

read_version: Callable[[list[str]], str] = _read_version

Reads what a system tool prints for its version flag. A variable, so a test answers for the machine.

symlink: Callable[[Path, Path], None] = _symlink

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

Event(name: str, version: str, action: str, detail: str = '')

One step of the engine's work, as it starts or resolves.

Attributes:

Name Type Description
name str

The tool.

version str

The version.

action str

A short verb: probe, wait, fetch, install, link.

detail str

Free text a renderer may show: a URL, a path, a reason.

name instance-attribute

name: str

version instance-attribute

version: str

action instance-attribute

action: str

detail class-attribute instance-attribute

detail: str = ''

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 bin, and nothing else.

tree Digest | None

The tree tools/<name>@<version> names; None for a delegated kind, whose bytes never went through the store.

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.

name instance-attribute

name: str

version instance-attribute

version: str

installed instance-attribute

installed: bool

tool_dir instance-attribute

tool_dir: Path

deployment instance-attribute

deployment: Deployment

tree instance-attribute

tree: Digest | None

answered class-attribute instance-attribute

answered: str = ''

paths property

paths: tuple[Path, ...]

The directories the deployment puts on PATH, under the tool directory.

env property

env: dict[str, str]

The deployment's env with PACKAGE_VAR replaced by the tool directory.

Delta dataclass

Delta(paths: tuple[Path, ...] = (), env: dict[str, str] = dict())

What a set of installs adds to an environment.

Attributes:

Name Type Description
paths tuple[Path, ...]

Directories to put in front of PATH, first first.

env dict[str, str]

Variables to set, a later install's value winning.

paths class-attribute instance-attribute

paths: tuple[Path, ...] = ()

env class-attribute instance-attribute

env: dict[str, str] = field(default_factory=dict)

Fetched dataclass

Fetched(name: str, version: str, host: str, digest: Digest, landed: bool)

One artifact fetch landed or found in the mirror.

Attributes:

Name Type Description
name str

The tool.

version str

The version.

host str

The host key.

digest Digest

The artifact's digest.

landed bool

True when the bytes came in on this call.

name instance-attribute

name: str

version instance-attribute

version: str

host instance-attribute

host: str

digest instance-attribute

digest: Digest

landed instance-attribute

landed: bool

DamagedView

Bases: NamedTuple

A view the disk no longer holds whole: tool, version, the paths missing.

Attributes:

Name Type Description
name str
version str
missing tuple[str, ...]

name instance-attribute

name: str

version instance-attribute

version: str

missing instance-attribute

missing: tuple[str, ...]

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
def __init__(
    self,
    home: Home,
    *,
    host: str = "",
    sources: Iterable[Source] = (),
    offline: bool = False,
    progress: Progress = silent,
) -> None:
    self.home: Home = home
    self.host: str = host or _default_host()
    if self.host not in HOSTS:
        raise StoreError(f"host {self.host!r} is not one of {', '.join(HOSTS)}")
    self.offline: bool = offline
    self._progress = progress
    self._objects: ObjectStore = home.open_store(sources=sources, offline=offline)

home instance-attribute

home: Home = home

host instance-attribute

host: str = host or _default_host()

offline instance-attribute

offline: bool = offline

objects property

objects: Store

The strongroom store underneath.

probe

probe(record: Record, version: str) -> Ensured | None

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
def probe(self, record: Record, version: str) -> Ensured | None:
    """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:
        RecordError: for a version the record does not track, or a
            version without this host.
    """
    if record.kind not in DOWNLOAD_KINDS:
        return self._probe_delegated(record.name, record.kind, version)
    deployment = resolve(record, version, self.host)
    return self._probe_download(record.name, version, deployment)

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 supply raises.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def ensure(
    self,
    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:
        RecordError: for a version the record does not track, or a
            version without this host.
        StoreError: as `supply` raises.
    """
    deployment = (
        resolve(record, version, self.host)
        if record.kind in DOWNLOAD_KINDS
        else None
    )
    return self.supply(
        record.name,
        record.kind,
        version,
        deployment,
        package=record.package,
        min_version=record.min_version,
        runtime=record.runtime,
        runtime_exe=runtime,
        graph=graph,
    )

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 npm tool with no runtime handed over or a node with no npm beside it, a miss while offline, a mismatch at a tier, an archive that will not extract, an installer that failed or placed a launcher outside the tool's directory, a system tool missing or below its floor, or a ref already naming another tree.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def supply(
    self,
    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:
        StoreError: for a kind the store cannot supply, a downloaded
            kind with no deployment, an `npm` tool with no runtime
            handed over or a node with no npm beside it, a miss
            while offline, a mismatch at a tier, an archive that
            will not extract, an installer that failed or placed a
            launcher outside the tool's directory, a system tool
            missing or below its floor, or a ref already naming
            another tree.
    """
    waiting = partial(
        self._progress, Event(name, version, "wait", "another process supplies it")
    )
    with exclusive(self.home.lock(name, version), waiting=waiting):
        return self._supply(
            name,
            kind,
            version,
            deployment,
            package=package,
            min_version=min_version,
            runtime=runtime,
            runtime_exe=runtime_exe,
            graph=graph,
        )

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
def stage(
    self,
    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:
        Every member of the unpacked tree before exclusion, as
        install-relative forward-slashed paths, in name order.

    Raises:
        StoreError: for a miss while offline, a mismatch at a tier,
            an archive that will not extract, or a declared root
            the archive lacks.
    """
    digest = Digest("sha256", deployment.sha256)
    artifact = self._land(name, version, deployment.url, digest)
    self._unpack(name, kind, deployment, artifact, into)
    members = tuple(sorted(p.relative_to(into).as_posix() for p in into.rglob("*")))
    if exclude:
        _exclude(deployment, into)
    return members

audit

audit(name: str, version: str) -> tuple[str, ...] | None

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
def audit(self, name: str, version: str) -> tuple[str, ...] | None:
    """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.
    """
    tool_dir = self.home.tool_dir(name, version)
    record = self._view_of(tool_dir)
    if record is None:
        return None
    return tuple(
        entry.path
        for entry in record.entries
        if entry.rung != "parked" and not (tool_dir / entry.path).exists()
    )

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
def audit_views(self) -> 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.
    """
    found: list[DamagedView] = []
    for record in self._objects.views():
        at = Path(record.at)
        if at.parent != self.home.tools or "@" not in at.name:
            continue
        name, _, version = at.name.rpartition("@")
        missing = tuple(
            entry.path
            for entry in record.entries
            if entry.rung != "parked" and not (at / entry.path).exists()
        )
        if missing:
            found.append(DamagedView(name, version, missing))
    return tuple(found)

mend_view

mend_view(name: str, version: str) -> None

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
def mend_view(self, name: str, version: str) -> None:
    """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:
        StoreError: when no view of the tool exists at the directory.
    """
    tool_dir = self.home.tool_dir(name, version)
    stale = self._view_of(tool_dir)
    if stale is None:
        raise StoreError(f"{name} {version}: no view at {tool_dir} to mend")
    self._objects.drop_view(stale.id)
    tool_dir.parent.mkdir(parents=True, exist_ok=True)
    self._objects.view(stale.tree, tool_dir)
link(ensured: Iterable[Ensured], into: Path) -> tuple[Path, ...]

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
def link(self, ensured: Iterable[Ensured], into: Path) -> tuple[Path, ...]:
    """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:
        The links made, in order.
    """
    into.mkdir(parents=True, exist_ok=True)
    manifest = into / LINKS
    previous: list[str] = (
        json.loads(manifest.read_text("utf-8")) if manifest.is_file() else []
    )
    for name in previous:
        stale = into / name
        if stale.is_symlink() or stale.is_file():
            stale.unlink()
    made: list[Path] = []
    names: set[str] = set()
    for item in ensured:
        # The entry points are the annotation, never a directory
        # scan: a bundle's own interpreter stays off the bin
        # directory unless the deployment names it.
        for entry in item.deployment.entry_points:
            candidate = item.tool_dir / entry
            if not candidate.is_file() or candidate.name in names:
                continue
            link = into / candidate.name
            _make_link(candidate, link)
            names.add(candidate.name)
            made.append(link)
            self._progress(Event(item.name, item.version, "link", str(link)))
    manifest.write_text(json.dumps([p.name for p in made]) + "\n", encoding="utf-8")
    return tuple(made)

delta

delta(ensured: Iterable[Ensured], bin_dir: Path | None = None) -> 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
def delta(self, ensured: Iterable[Ensured], bin_dir: Path | None = None) -> 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.
    """
    paths: list[Path] = [bin_dir] if bin_dir is not None else []
    env: dict[str, str] = {}
    for item in ensured:
        if bin_dir is None:
            for directory in item.paths:
                if directory not in paths:
                    paths.append(directory)
        env.update(item.env)
    return Delta(tuple(paths), env)

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
def fetch(
    self, 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:
        StoreError: for a miss while offline, or a mismatch.
    """
    wanted = tuple(hosts)
    mirror = Home(into).open_store()
    landed: list[Fetched] = []
    for record in records:
        if record.kind not in DOWNLOAD_KINDS:
            continue
        for delta in record.deltas:
            for host, artifact in delta.artifacts.items():
                if host not in wanted:
                    continue
                digest = Digest("sha256", artifact.sha256)
                if mirror.state(digest) == "present":
                    landed.append(
                        Fetched(record.name, delta.version, host, digest, False)
                    )
                    continue
                path = self._land(record.name, delta.version, artifact.url, digest)
                with path.open("rb") as handle:
                    mirror.land(handle, expected=digest)
                landed.append(
                    Fetched(record.name, delta.version, host, digest, True)
                )
    return tuple(landed)

silent

silent(_event: Event) -> None

The default progress: drop the event.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def silent(_event: Event) -> None:
    """The default progress: drop the event."""

bun_global_project

bun_global_project(install_root: Path) -> Path

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
def bun_global_project(install_root: Path) -> Path:
    """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.
    """
    project = install_root / "install" / "global"
    project.mkdir(parents=True, exist_ok=True)
    manifest = project / "package.json"
    if not manifest.is_file():
        manifest.write_text("{}\n", encoding="utf-8")
    return manifest

npm_cli

npm_cli(node: Path) -> Path

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.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def npm_cli(node: Path) -> Path:
    """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:
        StoreError: naming both places when neither holds it.
    """
    candidates = (
        node.parent.parent / "lib" / "node_modules" / "npm" / "bin" / "npm-cli.js",
        node.parent / "node_modules" / "npm" / "bin" / "npm-cli.js",
    )
    for candidate in candidates:
        if candidate.is_file():
            return candidate
    raise StoreError(
        f"{node}: no npm beside it; looked for {candidates[0]} and {candidates[1]}"
    )