Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

51.2 KB
Raw Blame
#!/usr/bin/env python3
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Installs isolated Node.js 24+ LTS into <UNSLOTH_HOME>/node, never touching system Node/npm;
archives sha256-checked against in-tree node_prebuilt_pins.json, not from the archive origin;
exit 0 success, 1 error, 2 fallback, 3 busy, 4 access denied; setup scripts grep the already
matches line."""

from __future__ import annotations

import argparse
import errno
import hashlib
import http.client
import json
import os
import stat
import platform
import random
import shutil
import socket
import subprocess
import sys
import tarfile
import tempfile
import time
import urllib.error
import urllib.parse
import urllib.request
import zipfile
from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
from typing import Iterator

_STUDIO_DIR = str(Path(__file__).resolve().parent)
if _STUDIO_DIR not in sys.path:
    sys.path.insert(0, _STUDIO_DIR)

from prebuilt_core import DownloadProgress, copy_response_body, make_staging_dir  # noqa: E402

try:
    from filelock import FileLock, Timeout as FileLockTimeout
except ImportError:
    FileLock = None
    FileLockTimeout = None


EXIT_SUCCESS = 0
EXIT_ERROR = 1
EXIT_FALLBACK = 2
EXIT_BUSY = 3
# Separate from EXIT_ERROR, whose "install Node yourself" advice is wrong here.
EXIT_DENIED = 4
# setup.ps1 reads these back to name the object actually refused (lock and .staging live in the parent).
DENIED_PATH_MARKER = "denied-path: "
DENIED_SCOPE_MARKER = "denied-scope: "
DENIED_SCOPE_INSTALL_DIR = "install-dir"
DENIED_SCOPE_PARENT = "parent"

# Node 24 LTS bundles npm 11, clearing Vite 8's floor.
NODE_MIN_LTS_MAJOR = 24
NPM_MIN_MAJOR = 11

NODE_DIST_BASE = "https://nodejs.org/dist"
NODE_MIRROR_ENV = "UNSLOTH_NODE_MIRROR"

RETRYABLE_HTTP_STATUS = {408, 429, 500, 502, 503, 504}
HTTP_FETCH_ATTEMPTS = 4
HTTP_FETCH_BASE_DELAY_SECONDS = 0.75
INSTALL_LOCK_TIMEOUT_SECONDS = 300
# The record is an optimisation: wait for the lock only briefly, never the full install timeout.
RECORD_LOCK_TIMEOUT_SECONDS = 5
INSTALL_STAGING_ROOT_NAME = ".staging"
METADATA_FILENAME = "UNSLOTH_NODE_PREBUILT_INFO.json"
METADATA_SCHEMA_VERSION = 1

# Trust anchor: in-tree, code-reviewed pins, not a same-origin checksum.
PINS_FILENAME = "node_prebuilt_pins.json"
PINS_SCHEMA_VERSION = 1
DEFAULT_NODE_CHANNEL = "pinned"
# Opt-in to install an unpinned version, trusting the same-origin SHASUMS256.txt.
ALLOW_UNVERIFIED_ENV = "UNSLOTH_NODE_ALLOW_UNVERIFIED"

_LOG_TO_STDOUT = False


class PrebuiltFallback(RuntimeError):
    """Recoverable failure -- caller should fall back (exit code 2)."""


class UnpinnedNodeRefused(PrebuiltFallback):
    """Unpinned Node requested without opt-in. Distinct type so the orchestrator
    re-raises it instead of letting the keep-existing path swallow the refusal."""


class BusyInstallConflict(RuntimeError):
    """Another process holds the install lock (exit code 3)."""


def log(message: str) -> None:
    print(f"[node-prebuilt] {message}", file = sys.stdout if _LOG_TO_STDOUT else sys.stderr)


# ── Host detection ──
@dataclass(frozen = True)
class HostInfo:
    system: str
    machine: str
    node_os: str
    node_arch: str
    archive_ext: str  # .tar.gz | .zip
    is_windows: bool


def tar_archive_ext() -> str:
    # Import, not find_spec: lzma.py exists even when _lzma was not built.
    try:
        import lzma  # noqa: F401
    except ImportError:
        return ".tar.gz"
    return ".tar.xz"


def gzip_alternative(asset: str) -> str:
    return asset[: -len(".tar.xz")] + ".tar.gz" if asset.endswith(".tar.xz") else asset


def detect_host() -> HostInfo:
    system = platform.system()
    machine = platform.machine().lower()
    is_windows = system == "Windows"

    if system == "Linux":
        node_os = "linux"
    elif system == "Darwin":
        node_os = "darwin"
    elif is_windows:
        node_os = "win"
    else:
        raise PrebuiltFallback(f"unsupported operating system for Node prebuilt: {system}")

    if machine in {"x86_64", "amd64", "x64"}:
        node_arch = "x64"
    elif machine in {"arm64", "aarch64"}:
        node_arch = "arm64"
    else:
        # Node 24 ships no linux-armv7l build.
        raise PrebuiltFallback(f"unsupported CPU architecture for Node prebuilt: {machine}")

    archive_ext = ".zip" if is_windows else tar_archive_ext()
    return HostInfo(
        system = system,
        machine = machine,
        node_os = node_os,
        node_arch = node_arch,
        archive_ext = archive_ext,
        is_windows = is_windows,
    )


# ── URL / asset construction (pure, unit tested) ──
def node_asset_stem(version: str, host: HostInfo) -> str:
    """e.g. node-v24.4.1-linux-x64 (no extension)."""
    return f"node-v{version}-{host.node_os}-{host.node_arch}"


def node_asset_name(version: str, host: HostInfo) -> str:
    return f"{node_asset_stem(version, host)}{host.archive_ext}"


def node_dist_base() -> str:
    return (os.environ.get(NODE_MIRROR_ENV, "").strip() or NODE_DIST_BASE).rstrip("/")


def node_dist_index_url() -> str:
    return f"{node_dist_base()}/index.json"


def node_download_url(version: str, asset_name: str) -> str:
    return f"{node_dist_base()}/v{version}/{asset_name}"


def node_shasums_url(version: str) -> str:
    return f"{node_dist_base()}/v{version}/SHASUMS256.txt"


def expected_sha256_for(shasums_text: str, asset_name: str) -> str | None:
    """Parse a nodejs.org SHASUMS256.txt ('<hex>  <filename>' per line)."""
    for line in shasums_text.splitlines():
        parts = line.split()
        if len(parts) == 2 and parts[1] == asset_name:
            digest = parts[0].lower()
            if len(digest) == 64 and all(c in "0123456789abcdef" for c in digest):
                return digest
    return None


def _version_tuple(value: str) -> tuple[int, ...]:
    try:
        return tuple(int(p) for p in value.lstrip("v").split("."))
    except ValueError:
        return ()


def _meets_node_floor(version: str) -> bool:
    """True iff version clears the setup floor (^20.19 || >=22.12 || >=23)."""
    parts = _version_tuple(version)
    if not parts:
        return False
    major = parts[0]
    minor = parts[1] if len(parts) > 1 else 0
    return (major == 20 and minor >= 19) or (major == 22 and minor >= 12) or major >= 23


def select_node_version(index: list[dict], *, channel: str, min_major: int) -> str:
    """Picks a concrete Node version from index.json: channel lts takes the newest LTS line and
    latest the newest overall, both with major >= min_major; any other channel is an explicit
    version string."""
    if channel not in {"lts", "latest"}:
        return channel.lstrip("v")

    best: tuple[int, ...] | None = None
    best_version: str | None = None
    for entry in index:
        version = str(entry.get("version", "")).lstrip("v")
        parsed = _version_tuple(version)
        if not parsed or parsed[0] < min_major:
            continue
        if channel == "lts" and not entry.get("lts"):
            continue
        if best is None or parsed > best:
            best = parsed
            best_version = version
    if best_version is None:
        raise PrebuiltFallback(
            f"no Node '{channel}' release found at or above major {min_major} in {node_dist_index_url()}"
        )
    return best_version


# ── HTTP (retry/backoff) ──
def _auth_headers() -> dict[str, str]:
    return {"User-Agent": "unsloth-studio-node-prebuilt"}


def is_retryable_url_error(exc: Exception) -> bool:
    if isinstance(exc, urllib.error.HTTPError):
        return exc.code in RETRYABLE_HTTP_STATUS
    if isinstance(exc, (urllib.error.URLError, TimeoutError, socket.timeout)):
        return True
    if isinstance(exc, (ConnectionError, http.client.IncompleteRead)):
        return True
    return False


def sleep_backoff(attempt: int) -> None:
    delay = HTTP_FETCH_BASE_DELAY_SECONDS * (2 ** max(attempt - 1, 0))
    delay += random.uniform(0.0, 0.2)
    time.sleep(delay)


def download_bytes(url: str, *, timeout: int = 60) -> bytes:
    last_exc: Exception | None = None
    for attempt in range(1, HTTP_FETCH_ATTEMPTS + 1):
        try:
            request = urllib.request.Request(url, headers = _auth_headers())
            with urllib.request.urlopen(request, timeout = timeout) as response:
                return response.read()
        except Exception as exc:  # noqa: BLE001
            last_exc = exc
            if attempt >= HTTP_FETCH_ATTEMPTS or not is_retryable_url_error(exc):
                raise
            log(f"fetch failed ({attempt}/{HTTP_FETCH_ATTEMPTS}) for {url}: {exc}; retrying")
            sleep_backoff(attempt)
    assert last_exc is not None
    raise last_exc


def fetch_json(url: str) -> object:
    return json.loads(download_bytes(url, timeout = 30).decode("utf-8"))


def atomic_replace_from_tempfile(tmp_path: Path, destination: Path) -> None:
    # Rename-over needs DELETE access on the destination, so a scanner can fail the swap; retry.
    destination.parent.mkdir(parents = True, exist_ok = True)
    _replace_with_retry(tmp_path, destination)


def download_file(url: str, destination: Path) -> None:
    destination.parent.mkdir(parents = True, exist_ok = True)
    last_exc: Exception | None = None
    for attempt in range(1, HTTP_FETCH_ATTEMPTS + 1):
        tmp_path: Path | None = None
        try:
            request = urllib.request.Request(url, headers = _auth_headers())
            with tempfile.NamedTemporaryFile(
                prefix = destination.name + ".tmp-",
                dir = destination.parent,
                delete = False,
            ) as handle:
                tmp_path = Path(handle.name)
                with urllib.request.urlopen(request, timeout = 120) as response:
                    content_length = response.headers.get("Content-Length")
                    total_bytes = (
                        int(content_length) if content_length and content_length.isdigit() else None
                    )
                    progress = DownloadProgress(f"Downloading {destination.name}", total_bytes)
                    if _LOG_TO_STDOUT:
                        progress.stream = sys.stdout
                        progress.is_tty = progress.is_tty and sys.stdout.isatty()
                    copy_response_body(
                        response, handle.write, total_bytes = total_bytes, progress = progress
                    )
                handle.flush()
                os.fsync(handle.fileno())
            if not tmp_path.exists() or tmp_path.stat().st_size == 0:
                raise RuntimeError(f"downloaded empty file from {url}")
            atomic_replace_from_tempfile(tmp_path, destination)
            return
        except Exception as exc:  # noqa: BLE001
            last_exc = exc
            if tmp_path is not None:
                try:
                    tmp_path.unlink(missing_ok = True)
                except Exception:  # noqa: BLE001
                    pass
            if attempt >= HTTP_FETCH_ATTEMPTS or not is_retryable_url_error(exc):
                raise
            log(f"download failed ({attempt}/{HTTP_FETCH_ATTEMPTS}) for {url}: {exc}; retrying")
            sleep_backoff(attempt)
    assert last_exc is not None
    raise last_exc


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def download_file_verified(
    url: str, destination: Path, *, expected_sha256: str, label: str
) -> None:
    for attempt in range(1, 3):
        download_file(url, destination)
        actual = sha256_file(destination)
        if actual == expected_sha256:
            log(f"verified {label} sha256={actual}")
            return
        log(f"{label} checksum mismatch {attempt}/2: expected={expected_sha256} actual={actual}")
        destination.unlink(missing_ok = True)
        if attempt == 2:
            raise PrebuiltFallback(f"{label} checksum mismatch after retry")


# ── Pinned digest manifest (trust anchor) ──
def pins_path() -> Path:
    return Path(__file__).resolve().parent / PINS_FILENAME


def load_pins() -> dict:
    path = pins_path()
    try:
        data = json.loads(path.read_text(encoding = "utf-8"))
    except FileNotFoundError as exc:
        raise PrebuiltFallback(f"pinned Node manifest missing: {path}") from exc
    except (json.JSONDecodeError, OSError) as exc:
        raise PrebuiltFallback(f"pinned Node manifest unreadable ({path}): {exc}") from exc
    if not isinstance(data, dict) or data.get("schema_version") != PINS_SCHEMA_VERSION:
        raise PrebuiltFallback(f"pinned Node manifest has an unexpected schema: {path}")
    return data


def pinned_default_version(pins: dict) -> str:
    version = str(pins.get("default_version", "")).lstrip("v")
    if not _version_tuple(version):
        raise PrebuiltFallback("pinned Node manifest is missing a valid 'default_version'")
    return version


def pinned_sha256(pins: dict, version: str, asset_name: str) -> str | None:
    versions = pins.get("versions")
    if not isinstance(versions, dict):
        return None
    entry = versions.get(version.lstrip("v"))
    if not isinstance(entry, dict):
        return None
    digest = entry.get(asset_name)
    if not isinstance(digest, str):
        return None
    digest = digest.strip().lower()
    if len(digest) == 64 and all(c in "0123456789abcdef" for c in digest):
        return digest
    return None


def allow_unverified_node() -> bool:
    return os.environ.get(ALLOW_UNVERIFIED_ENV, "").strip().lower() in {"1", "true", "yes", "on"}


def resolve_expected_sha256(pins: dict, version: str, asset: str, *, allow_unverified: bool) -> str:
    """Sha256 to verify the archive against: the committed pin, or (only with explicit
    opt-in) the same-origin SHASUMS256.txt. Unpinned without opt-in is refused."""
    pinned = pinned_sha256(pins, version, asset)
    if pinned is not None:
        log(f"verifying {asset} against pinned sha256 from {PINS_FILENAME}")
        return pinned

    if not allow_unverified:
        raise UnpinnedNodeRefused(
            f"refusing to install Node v{version}: {asset} is not in the pinned manifest "
            f"({PINS_FILENAME}); its only checksum would arrive over the same channel as the "
            f"archive. Use the pinned default version (unset UNSLOTH_NODE_VERSION), add a pin "
            f"for {asset}, or set {ALLOW_UNVERIFIED_ENV}=1 to trust the upstream SHASUMS256.txt "
            f"at your own risk."
        )

    log(
        f"WARNING: {asset} is not pinned; trusting upstream SHASUMS256.txt because "
        f"{ALLOW_UNVERIFIED_ENV} is set. This checksum shares the archive's origin and is "
        f"not an independent integrity guarantee."
    )
    shasums = download_bytes(node_shasums_url(version), timeout = 30).decode("utf-8", "replace")
    expected = expected_sha256_for(shasums, asset)
    if not expected:
        raise PrebuiltFallback(f"no sha256 for {asset} in SHASUMS256.txt (v{version})")
    return expected


# ── Safe archive extraction (zip + tar.gz + tar.xz, traversal/symlink guarded) ──
def _safe_extract_path(base: Path, member_name: str) -> Path:
    member_path = Path(member_name.replace("\\", "/"))
    if member_path.is_absolute():
        raise PrebuiltFallback(f"archive member used an absolute path: {member_name}")
    target = (base / member_path).resolve()
    try:
        target.relative_to(base.resolve())
    except ValueError as exc:
        raise PrebuiltFallback(f"archive member escaped destination: {member_name}") from exc
    return target


def _extract_zip_safely(source: Path, base: Path) -> None:
    with zipfile.ZipFile(source) as archive:
        for member in archive.infolist():
            target = _safe_extract_path(base, member.filename)
            mode = (member.external_attr >> 16) & 0o170000
            if mode == 0o120000:
                raise PrebuiltFallback(f"zip archive contained a symlink entry: {member.filename}")
            if member.is_dir():
                target.mkdir(parents = True, exist_ok = True)
                continue
            target.parent.mkdir(parents = True, exist_ok = True)
            with archive.open(member, "r") as src, target.open("wb") as dst:
                shutil.copyfileobj(src, dst)


def _extract_tar_safely(source: Path, base: Path) -> None:
    # bin/npm, npx, corepack are relative symlinks into lib/node_modules; resolve after files.
    pending_links: list[tuple[tarfile.TarInfo, Path]] = []
    with tarfile.open(source, "r:*") as archive:
        for member in archive.getmembers():
            target = _safe_extract_path(base, member.name)
            if member.isdir():
                target.mkdir(parents = True, exist_ok = True)
                continue
            if member.islnk() or member.issym():
                pending_links.append((member, target))
                continue
            if not member.isfile():
                raise PrebuiltFallback(f"tar archive contained an unsupported entry: {member.name}")
            target.parent.mkdir(parents = True, exist_ok = True)
            extracted = archive.extractfile(member)
            if extracted is None:
                raise PrebuiltFallback(f"tar archive entry could not be read: {member.name}")
            with extracted, target.open("wb") as dst:
                shutil.copyfileobj(extracted, dst)
            if member.mode & 0o111:
                os.chmod(target, target.stat().st_mode | 0o111)

    for member, target in pending_links:
        link_name = member.linkname.replace("\\", "/")
        link_path = Path(link_name)
        if link_path.is_absolute() or not link_name:
            raise PrebuiltFallback(
                f"archive link used an unsafe target: {member.name} -> {link_name}"
            )
        # tar symlink names are link-parent relative; hard-link names are archive-root relative.
        resolved = (target.parent / link_path if member.issym() else base / link_path).resolve()
        try:
            resolved.relative_to(base.resolve())
        except ValueError as exc:
            raise PrebuiltFallback(
                f"archive link escaped destination: {member.name} -> {link_name}"
            ) from exc
        target.parent.mkdir(parents = True, exist_ok = True)
        if target.exists() or target.is_symlink():
            target.unlink()
        if member.issym():
            target.symlink_to(link_name)
        else:
            shutil.copy2(resolved, target)


def extract_archive(archive_path: Path, destination: Path) -> None:
    destination.mkdir(parents = True, exist_ok = True)
    if archive_path.name.endswith(".zip"):
        _extract_zip_safely(archive_path, destination)
    elif archive_path.name.endswith((".tar.gz", ".tar.xz")):
        _extract_tar_safely(archive_path, destination)
    else:
        raise PrebuiltFallback(f"unsupported archive format: {archive_path.name}")


# ── Install lock (concurrent setup runs share one UNSLOTH_HOME) ──
def install_lock_path(install_dir: Path) -> Path:
    return install_dir.parent / f".{install_dir.name}.install.lock"


def _pid_is_alive(pid: int) -> bool:
    """Best-effort process liveness check that never signals the process on Windows."""
    if pid <= 0:
        return False
    if sys.platform == "win32":
        try:
            result = subprocess.run(
                ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
                capture_output = True,
                text = True,
                encoding = "utf-8",
                errors = "replace",
                timeout = 5,
                **_windows_hidden_kwargs(),
            )
        except (OSError, ValueError, subprocess.SubprocessError):
            return True
        return f'"{pid}"' in result.stdout
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    except ValueError:
        return False
    return True


@contextmanager
def install_lock(lock_path: Path, *, timeout: float | None = None) -> Iterator[None]:
    seconds = INSTALL_LOCK_TIMEOUT_SECONDS if timeout is None else timeout
    lock_path.parent.mkdir(parents = True, exist_ok = True)
    if FileLock is None:
        fd: int | None = None
        deadline = time.monotonic() + seconds
        while True:
            try:
                fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_RDWR)
                os.write(fd, f"{os.getpid()}\n".encode())
                os.fsync(fd)
                break
            except FileExistsError:
                try:
                    # errors="replace" so an undecodable lock is treated as stale, not retried forever.
                    raw = lock_path.read_text(encoding = "utf-8", errors = "replace").strip()
                except FileNotFoundError:
                    continue
                stale = False
                if raw:
                    try:
                        stale = not _pid_is_alive(int(raw))
                    except ValueError:
                        stale = True
                if stale:
                    # Rename before unlinking so only one racer removes the stale lock.
                    try:
                        stale_path = lock_path.with_name(f"{lock_path.name}.stale.{os.getpid()}")
                        os.replace(str(lock_path), str(stale_path))
                        stale_path.unlink(missing_ok = True)
                    except (OSError, ValueError):
                        pass
                    continue
                if time.monotonic() >= deadline:
                    raise BusyInstallConflict(
                        f"timed out after {seconds}s waiting for install lock: {lock_path}"
                    )
                time.sleep(0.5)
        try:
            yield
        finally:
            if fd is not None:
                os.close(fd)
            lock_path.unlink(missing_ok = True)
        return

    try:
        with FileLock(str(lock_path), timeout = seconds):
            yield
    except FileLockTimeout as exc:
        raise BusyInstallConflict(
            f"timed out after {seconds}s waiting for install lock: {lock_path}"
        ) from exc


# ── Install layout / metadata / health ──
def node_binary_path(install_dir: Path, host: HostInfo) -> Path:
    return install_dir / "node.exe" if host.is_windows else install_dir / "bin" / "node"


def npm_cli_path(install_dir: Path, host: HostInfo) -> Path:
    if host.is_windows:
        return install_dir / "node_modules" / "npm" / "bin" / "npm-cli.js"
    return install_dir / "lib" / "node_modules" / "npm" / "bin" / "npm-cli.js"


def _windows_hidden_kwargs() -> dict[str, object]:
    if sys.platform != "win32":
        return {}
    kwargs: dict[str, object] = {}
    flag = getattr(subprocess, "CREATE_NO_WINDOW", 0)
    if flag:
        kwargs["creationflags"] = flag
    return kwargs


def _run_node(
    install_dir: Path,
    host: HostInfo,
    args: list[str],
    *,
    timeout: int = 120,
) -> str:
    node_bin = node_binary_path(install_dir, host)
    env = os.environ.copy()
    # Windows npm otherwise defaults its global prefix to %APPDATA%\npm.
    env["NPM_CONFIG_PREFIX"] = str(install_dir)
    env["npm_config_prefix"] = str(install_dir)
    env.pop("NODE_PATH", None)
    result = subprocess.run(
        [str(node_bin), *args],
        capture_output = True,
        text = True,
        encoding = "utf-8",
        errors = "replace",
        timeout = timeout,
        env = env,
        **_windows_hidden_kwargs(),
    )
    if result.returncode != 0:
        raise RuntimeError(
            f"node {' '.join(args)} failed: {result.stderr.strip() or result.stdout.strip()}"
        )
    return result.stdout.strip()


def installed_node_version(install_dir: Path, host: HostInfo) -> str | None:
    node_bin = node_binary_path(install_dir, host)
    if not node_bin.exists():
        return None
    try:
        return _run_node(install_dir, host, ["-v"], timeout = 30).lstrip("v")
    except Exception:  # noqa: BLE001
        return None


def installed_npm_major(install_dir: Path, host: HostInfo) -> int | None:
    cli = npm_cli_path(install_dir, host)
    if not cli.exists():
        return None
    try:
        out = _run_node(install_dir, host, [str(cli), "--version"], timeout = 60)
        return _version_tuple(out)[0]
    except Exception:  # noqa: BLE001
        return None


def metadata_path(install_dir: Path) -> Path:
    return install_dir / METADATA_FILENAME


def _write_metadata_payload(install_dir: Path, payload: dict) -> None:
    """Replace the marker atomically, or leave the previous one exactly as it was.

    load_metadata reads a truncated or unparseable file as "no install", so a crash,
    a full disk or a killed installer partway through a plain write_text retires the
    install the marker described: the next run refetches ~110 MB of Node. Same shape as
    download_file -- a sibling temp file, flushed and fsynced, then os.replace, which is
    atomic within a directory on POSIX and Windows alike.

    The temp file is removed on every failure path. A stranded `.tmp-` sibling would sit
    inside the install directory forever, and _swap_into_place would carry one written
    here into the live tree.

    Raises: the caller decides. write_metadata is writing into a staging tree that is
    discarded on failure, so a raise there aborts an install that never landed.
    """
    destination = metadata_path(install_dir)
    destination.parent.mkdir(parents = True, exist_ok = True)
    try:
        original: os.stat_result | None = destination.stat()
    except OSError:
        original = None
    original_mode: int | None = stat.S_IMODE(original.st_mode) if original is not None else None
    handle = tempfile.NamedTemporaryFile(
        prefix = destination.name + ".tmp-",
        dir = destination.parent,
        delete = False,
        mode = "w",
        encoding = "utf-8",
    )
    tmp_path: Path | None = Path(handle.name)
    try:
        with handle:
            handle.write(json.dumps(payload, indent = 2) + "\n")
            handle.flush()
            os.fsync(handle.fileno())
        # NamedTemporaryFile is 0600 and os.replace keeps it, so restore the shared marker's mode.
        replacing_an_existing_marker = original_mode is not None
        if original_mode is None:
            mask = os.umask(0)
            os.umask(mask)
            original_mode = 0o666 & ~mask
        try:
            os.chmod(tmp_path, original_mode)
        except OSError:
            # Only a refresh raises: a first-write chmod failure must not abort the install.
            if replacing_an_existing_marker:
                raise
        if original is not None:
            # Owner then group, as prebuilt_core.write_live_marker explains.
            try:
                os.chown(tmp_path, original.st_uid, original.st_gid)
            except (OSError, AttributeError):
                try:
                    os.chown(tmp_path, -1, original.st_gid)
                except (OSError, AttributeError):
                    pass
        atomic_replace_from_tempfile(tmp_path, destination)
        tmp_path = None
    finally:
        if tmp_path is not None:
            try:
                tmp_path.unlink(missing_ok = True)
            except Exception:  # noqa: BLE001
                pass


def write_metadata(install_dir: Path, *, version: str, asset: str, sha256: str) -> None:
    payload = {
        "schema_version": METADATA_SCHEMA_VERSION,
        "kind": "node",
        "version": version,
        "asset": asset,
        "sha256": sha256,
    }
    _write_metadata_payload(install_dir, payload)


def load_metadata(install_dir: Path) -> dict | None:
    path = metadata_path(install_dir)
    if not path.exists():
        return None
    try:
        data = json.loads(path.read_text(encoding = "utf-8"))
    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
        return None
    return data if isinstance(data, dict) else None


_PREBUILT_FULL_CHECK_ENV = "UNSLOTH_PREBUILT_FULL_CHECK"


def prebuilt_full_check_requested() -> bool:
    """Escape hatch forcing a full Node revalidation past the recorded-runtime shortcut; defined
    here rather than imported from the llama module so this installer stays independent, spelled
    as llama and whisper spell it."""
    return os.environ.get(_PREBUILT_FULL_CHECK_ENV, "").strip().lower() in (
        "1",
        "true",
        "yes",
        "on",
    )


def _file_record(path: Path) -> dict | None:
    """size, mtime_ns and sha256 for one file, or None when it cannot be read."""
    try:
        info = path.stat()
        digest = sha256_file(path)
    except (OSError, MemoryError):
        return None
    return {"size": info.st_size, "mtime_ns": info.st_mtime_ns, "sha256": digest}


def _file_record_matches(path: Path, recorded: object) -> bool:
    """Compares only size and mtime_ns: hashing the node binary on every launch would cost more than
    the node -v spawn it avoids; a node that no longer runs is still caught by the npm-cli.js
    probe, and the record was never a tamper defence."""
    if not isinstance(recorded, dict):
        return False
    try:
        info = path.stat()
    except OSError:
        return False
    return info.st_size == recorded.get("size") and info.st_mtime_ns == recorded.get("mtime_ns")


def record_runtime_verification(
    install_dir: Path, host: HostInfo, *, version: str, npm_major: int
) -> None:
    """Remember that THESE bytes answered `node -v` and `npm --version`.

    Only the node half is later trusted in place of a spawn: npm_major_checked records that
    the npm probe cleared the floor at the time, not that it still would. See
    _recorded_runtime_matches.

    Read-modify-write, never raises, and never leaves a half-written marker: this
    rewrites a file that already describes a good install, so a torn write here is
    strictly worse than not writing at all.
    """
    meta = load_metadata(install_dir)
    if meta is None:
        return
    node_record = _file_record(node_binary_path(install_dir, host))
    npm_record = _file_record(npm_cli_path(install_dir, host))
    if node_record is None or npm_record is None:
        return
    fresh = {
        "node_binary": node_record,
        "npm_cli": npm_record,
        "node_version_checked": version,
        "npm_major_checked": npm_major,
    }
    if all(meta.get(key) == value for key, value in fresh.items()):
        # Nothing learned: rewriting would churn mtime, inode, mode and owner forever.
        return
    meta.update(fresh)
    try:
        _write_metadata_payload(install_dir, meta)
    except Exception:  # noqa: BLE001
        pass


def _recorded_runtime_matches(install_dir: Path, host: HostInfo, meta: dict, version: str) -> bool:
    """Whether a previous run already proved this exact node binary reports this version.

    `node -v` is an interpreter start of a 110 MB runtime, re-run on every install and
    every update to re-derive an answer that cannot have changed while the binary has not.
    Absent records mean an install made before this existed, so it pays the spawn once and
    then records it.

    What this deliberately does NOT prove is npm. The npm record covers npm-cli.js alone,
    a launcher that bootstraps thousands of files under npm/lib: deleting npm/lib/cli.js
    leaves the recorded launcher byte-identical while `npm --version` fails. So the npm
    record is only used as "this file is still the one the last probe ran", and
    npm_major_checked only as "that probe cleared the floor" -- the caller still pays the
    npm probe, because only npm can show npm's own module tree still loads.
    """
    if prebuilt_full_check_requested():
        return False
    if meta.get("node_version_checked") != version:
        return False
    npm_major = meta.get("npm_major_checked")
    if not isinstance(npm_major, int) or npm_major < NPM_MIN_MAJOR:
        return False
    if not _file_record_matches(node_binary_path(install_dir, host), meta.get("node_binary")):
        return False
    if not _file_record_matches(npm_cli_path(install_dir, host), meta.get("npm_cli")):
        return False
    # chmod -x moves ctime only, so the records still match a node that cannot run.
    return host.is_windows or os.access(node_binary_path(install_dir, host), os.X_OK)


def _record_runtime_verification_under_lock(
    install_dir: Path, host: HostInfo, meta: dict, *, version: str, npm_major: int
) -> bool:
    """record_runtime_verification for a caller that does not hold the install lock.

    The record is a read-modify-write of the marker, and the pre-lock check in
    install_prebuilt is exactly where another installer can be mid-swap: it reads the
    old marker, the other process swaps a new tree into place, and the old version and
    checksum are written over the new tree's marker. So the write takes the lock and
    goes ahead only if the marker is still the one that was read.

    Returns whether the marker was still the one that was read. False means another
    installer replaced the tree while this one waited, so what was just verified is no
    longer what is installed; the caller re-checks rather than reporting it current.
    A write that failed for any other reason still answers True: the install is the one
    that was verified, and the record merely costs the two spawns again next time.
    """
    try:
        with install_lock(install_lock_path(install_dir), timeout = RECORD_LOCK_TIMEOUT_SECONDS):
            current = load_metadata(install_dir)
            if current is None:
                return False
            if any(current.get(key) != meta.get(key) for key in ("version", "sha256", "asset")):
                return False
            record_runtime_verification(install_dir, host, version = version, npm_major = npm_major)
    except BusyInstallConflict:
        # Busy is not evidence; answering False would make the first launch beside an installer exit busy.
        log("another installer holds the lock; keeping the verified install without a record")
    except Exception:  # noqa: BLE001
        pass
    return True


def pin_to_keep(pins: dict, version: str, asset: str, install_dir: Path) -> str | None:
    """Pin of the recorded archive when it is the same Node build in another format, so a format switch does not re-download."""
    recorded = (load_metadata(install_dir) or {}).get("asset")
    stem = gzip_alternative(asset)[: -len(".tar.gz")] if ".tar." in asset else None
    if stem and recorded in (stem + ".tar.gz", stem + ".tar.xz"):
        return pinned_sha256(pins, version, recorded) or pinned_sha256(pins, version, asset)
    return pinned_sha256(pins, version, asset)


def _download_asset(staging: Path, version: str, asset: str, expected_sha: str) -> Path:
    archive_path = staging / asset
    log(f"downloading {node_download_url(version, asset)}")
    download_file_verified(
        node_download_url(version, asset),
        archive_path,
        expected_sha256 = expected_sha,
        label = asset,
    )
    return archive_path


def existing_install_matches(
    install_dir: Path,
    host: HostInfo,
    *,
    version: str,
    expected_sha: str | None = None,
    under_lock: bool = False,
) -> bool:
    """True iff the on-disk install is exactly this version, runs, and (when
    expected_sha is given) was recorded with that digest, so a non-pinned or
    tampered artifact is not kept just because its version string matches."""
    meta = load_metadata(install_dir)
    if not meta or meta.get("version") != version:
        return False
    if expected_sha is not None and meta.get("sha256") != expected_sha:
        return False
    if _recorded_runtime_matches(install_dir, host, meta, version):
        npm_major = installed_npm_major(install_dir, host)
        return npm_major is not None and npm_major >= NPM_MIN_MAJOR
    if installed_node_version(install_dir, host) != version:
        return False
    npm_major = installed_npm_major(install_dir, host)
    if npm_major is None or npm_major < NPM_MIN_MAJOR:
        return False
    if under_lock:
        record_runtime_verification(install_dir, host, version = version, npm_major = npm_major)
        return True
    return _record_runtime_verification_under_lock(
        install_dir, host, meta, version = version, npm_major = npm_major
    )


def existing_install_usable(install_dir: Path, host: HostInfo) -> bool:
    """True iff the on-disk install runs and clears the npm floor, ignoring version."""
    if not load_metadata(install_dir):
        return False
    if installed_node_version(install_dir, host) is None:
        return False
    npm_major = installed_npm_major(install_dir, host)
    return npm_major is not None and npm_major >= NPM_MIN_MAJOR


# Retried (scanners raise it after extraction), but unreadable ACLs raise it too.
_ERROR_ACCESS_DENIED = 5


def _access_denied_recovery_lines(paths: tuple[tuple[Path, bool], ...]) -> list[str]:
    """Repair commands for a rename still failing with ``ERROR_ACCESS_DENIED``.

    One command per line: joined, takeown swallows the rest as arguments.
    """
    lines = [
        "if this was not a scanner, the ACLs on one of these rename paths may be "
        "unreadable -- even icacls/Get-Acl report access denied in that state",
        "from an elevated PowerShell, restore access for each affected path, "
        "then run the install again:",
    ]
    # Non-recursive for the parent: /R would rewrite sibling installs.
    for path, recursive in dict.fromkeys(paths):
        takeown_flags = " /R /D Y" if recursive else ""
        icacls_flags = " /T /C" if recursive else ""
        lines.extend(
            (
                f'  takeown /F "{path}"{takeown_flags}',
                f'  icacls "{path}" /reset{icacls_flags}',
            )
        )
    return lines


def _replace_with_retry(
    src: Path,
    dst: Path,
    *,
    attempts: int = 8,
    access_denied_paths: tuple[tuple[Path, bool], ...] | None = None,
) -> None:
    """os.replace, retried against transient Windows sharing violations.

    A directory rename fails with WinError 5/32 while any process holds a handle inside
    it, and Defender or the indexer routinely does right after extraction (seen in CI on
    a fresh install, with no existing directory to conflict with). Handles clear in a
    second or two, so a bounded backoff turns the failure into a pause; other errors
    raise immediately rather than stalling on a real problem.

    An exhausted WinError 5 may be an ACL fault, not a scanner (#9928): with
    ``access_denied_paths`` the repair lines ride on the error, printed only if an existing
    Node is kept (otherwise main() exits 4 and setup.ps1 prints its own, #10533).
    """
    delay = 0.25
    for attempt in range(attempts):
        try:
            os.replace(src, dst)
            return
        except OSError as exc:
            winerror = getattr(exc, "winerror", None)
            transient = os.name == "nt" and winerror in (_ERROR_ACCESS_DENIED, 32, 145)
            if not transient or attempt == attempts - 1:
                if transient and winerror == _ERROR_ACCESS_DENIED and access_denied_paths:
                    log(f"rename still blocked (5) after {attempts} attempts")
                    exc._unsloth_acl_recovery_lines = _access_denied_recovery_lines(
                        access_denied_paths
                    )
                raise
            if winerror == _ERROR_ACCESS_DENIED:
                cause = "a scanner may still hold the files, or the ACLs are unreadable"
            else:
                cause = "a scanner is likely still holding the extracted files"
            log(f"rename blocked ({winerror}), retrying in {delay:.2f}s -- {cause}")
            time.sleep(delay)
            delay = min(delay * 2, 4.0)


def _swap_into_place(extracted_root: Path, install_dir: Path) -> None:
    """Atomically replace install_dir with extracted_root (same filesystem)."""
    install_dir.parent.mkdir(parents = True, exist_ok = True)
    backup: Path | None = None
    if install_dir.exists():
        backup = install_dir.parent / f".{install_dir.name}.old-{os.getpid()}"
        _replace_with_retry(
            install_dir,
            backup,
            access_denied_paths = ((install_dir, True), (install_dir.parent, False)),
        )
    try:
        _replace_with_retry(
            extracted_root,
            install_dir,
            access_denied_paths = ((extracted_root, True), (install_dir.parent, False)),
        )
    except OSError:
        # The rollback gets the same backoff, else a scanner on the backup leaves no install_dir.
        if backup is not None and not install_dir.exists():
            try:
                _replace_with_retry(
                    backup,
                    install_dir,
                    access_denied_paths = ((backup, True), (install_dir.parent, False)),
                )
            except OSError as rollback_exc:
                log(f"could not restore the previous Node install from {backup}: {rollback_exc}")
        raise
    if backup is not None:
        shutil.rmtree(backup, ignore_errors = True)


def _ensure_npm_floor(install_dir: Path, host: HostInfo) -> None:
    """Self-upgrade npm inside the isolated prefix if a pinned build ships npm < 11 (no-op on Node 24+)."""
    npm_major = installed_npm_major(install_dir, host)
    if npm_major is not None and npm_major >= NPM_MIN_MAJOR:
        return
    log(f"bundled npm {npm_major} below {NPM_MIN_MAJOR}; upgrading npm inside the isolated prefix")
    cli = npm_cli_path(install_dir, host)
    _run_node(install_dir, host, [str(cli), "install", "-g", f"npm@^{NPM_MIN_MAJOR}"], timeout = 300)


# ── Orchestration ──
def install_prebuilt(install_dir: Path, *, channel: str, min_major: int, force: bool) -> int:
    host = detect_host()
    pins = load_pins()

    if channel in {"", "pinned", "default"}:
        version = pinned_default_version(pins)
    elif channel in {"lts", "latest"}:
        try:
            index = fetch_json(node_dist_index_url())
        except Exception as exc:  # noqa: BLE001
            if not force and existing_install_usable(install_dir, host):
                log(f"Node dist index unreachable ({exc}); keeping existing isolated Node")
                return EXIT_SUCCESS
            raise
        if not isinstance(index, list):
            raise PrebuiltFallback(f"unexpected index.json payload from {node_dist_index_url()}")
        version = select_node_version(index, channel = channel, min_major = min_major)
    else:
        version = channel.lstrip("v")
        if not _meets_node_floor(version):
            raise PrebuiltFallback(
                f"requested Node v{version} is below the floor (^20.19 || >=22.12 || >=23)"
            )

    asset = node_asset_name(version, host)
    log(f"target Node v{version} ({asset})")

    # Keep an existing install only if it matches the pin (or pinning is opted out).
    pin = pin_to_keep(pins, version, asset, install_dir)
    allow_unverified = allow_unverified_node()
    may_keep = pin is not None or allow_unverified

    if (
        not force
        and may_keep
        and existing_install_matches(install_dir, host, version = version, expected_sha = pin)
    ):
        log(f"existing Node install already matches v{version}; nothing to do")
        return EXIT_SUCCESS

    with install_lock(install_lock_path(install_dir)):
        # Another installer may have switched archive format while we waited.
        pin = pin_to_keep(pins, version, asset, install_dir)
        may_keep = pin is not None or allow_unverified
        if (
            not force
            and may_keep
            and existing_install_matches(
                install_dir, host, version = version, expected_sha = pin, under_lock = True
            )
        ):
            log(f"existing Node install already matches v{version}; nothing to do")
            return EXIT_SUCCESS

        try:
            expected_sha = resolve_expected_sha256(
                pins, version, asset, allow_unverified = allow_unverified
            )

            staging_root = install_dir.parent / INSTALL_STAGING_ROOT_NAME
            staging_root.mkdir(parents = True, exist_ok = True)
            staging = make_staging_dir(staging_root, f"{install_dir.name}.staging-")
            try:
                try:
                    archive_path = _download_asset(staging, version, asset, expected_sha)
                except Exception as exc:  # noqa: BLE001
                    # A mirror may carry only .tar.gz.
                    if gzip_alternative(asset) == asset:
                        raise
                    log(f"{asset} unavailable ({exc}); trying {gzip_alternative(asset)}")
                    asset = gzip_alternative(asset)
                    expected_sha = resolve_expected_sha256(
                        pins, version, asset, allow_unverified = allow_unverified
                    )
                    archive_path = _download_asset(staging, version, asset, expected_sha)
                extract_dir = staging / "extracted"
                extract_archive(archive_path, extract_dir)

                roots = [p for p in extract_dir.iterdir() if p.is_dir()]
                if len(roots) != 1:
                    raise PrebuiltFallback(f"unexpected archive layout: {[p.name for p in roots]}")
                extracted_root = roots[0]

                _ensure_npm_floor(extracted_root, host)
                write_metadata(extracted_root, version = version, asset = asset, sha256 = expected_sha)
                _swap_into_place(extracted_root, install_dir)
            finally:
                shutil.rmtree(staging, ignore_errors = True)
                try:
                    staging_root.rmdir()
                except OSError:
                    pass
        except UnpinnedNodeRefused:
            # A policy refusal: fail closed, never keep-existing.
            raise
        except Exception as exc:  # noqa: BLE001
            # Never keep a same-version install whose recorded digest is not the pin.
            meta = load_metadata(install_dir)
            pin_mismatch = (
                pin is not None
                and bool(meta)
                and meta.get("version") == version
                and meta.get("sha256") != pin
            )
            if not force and not pin_mismatch and existing_install_usable(install_dir, host):
                recovery = getattr(exc, "_unsloth_acl_recovery_lines", None)
                if recovery:
                    for line in recovery:
                        log(line)
                    log(
                        f"existing Node could not be replaced ({exc}); keeping existing isolated Node"
                    )
                else:
                    log(f"Node download failed ({exc}); keeping existing isolated Node")
                return EXIT_SUCCESS
            raise

    final_version = installed_node_version(install_dir, host)
    npm_major = installed_npm_major(install_dir, host)
    if final_version != version or npm_major is None or npm_major < NPM_MIN_MAJOR:
        raise PrebuiltFallback(
            f"post-install verification failed: node={final_version} npm_major={npm_major}"
        )
    installed_meta = load_metadata(install_dir) or {}
    _record_runtime_verification_under_lock(
        install_dir, host, installed_meta, version = final_version, npm_major = npm_major
    )
    log(f"installed isolated Node v{final_version} (npm {npm_major}.x) at {install_dir}")
    return EXIT_SUCCESS


def main(argv: list[str] | None = None) -> int:
    global _LOG_TO_STDOUT
    _LOG_TO_STDOUT = True

    parser = argparse.ArgumentParser(description = "Install an isolated Node.js for Unsloth Studio")
    parser.add_argument(
        "--install-dir", required = True, help = "isolated Node directory, e.g. <UNSLOTH_HOME>/node"
    )
    parser.add_argument(
        "--node-version",
        default = os.environ.get("UNSLOTH_NODE_VERSION", DEFAULT_NODE_CHANNEL),
        help = (
            f"'pinned' (default; installs the digest-pinned version from {PINS_FILENAME}), "
            f"'lts', 'latest', or an explicit version like 24.4.1. Non-pinned versions require "
            f"{ALLOW_UNVERIFIED_ENV}=1."
        ),
    )
    parser.add_argument("--min-major", type = int, default = NODE_MIN_LTS_MAJOR)
    parser.add_argument(
        "--force", action = "store_true", help = "reinstall even if the version matches"
    )
    args = parser.parse_args(argv)

    install_dir = Path(args.install_dir).expanduser().resolve()
    try:
        return install_prebuilt(
            install_dir,
            channel = args.node_version,
            min_major = args.min_major,
            force = args.force,
        )
    except BusyInstallConflict as exc:
        log(str(exc))
        return EXIT_BUSY
    except UnpinnedNodeRefused as exc:
        # Catch before PrebuiltFallback (its base class) so the refusal logs its own message.
        log(str(exc))
        return EXIT_FALLBACK
    except PrebuiltFallback as exc:
        log(f"prebuilt unavailable: {exc}")
        return EXIT_FALLBACK
    except PermissionError as exc:
        return _report_access_denied(exc, install_dir)
    except OSError as exc:
        # Windows ACL / filter-driver denials arrive as winerror 5, not always PermissionError.
        if getattr(exc, "winerror", None) == 5 or exc.errno == errno.EACCES:
            return _report_access_denied(exc, install_dir)
        log(f"unexpected error: {exc}")
        return EXIT_ERROR
    except Exception as exc:  # noqa: BLE001
        log(f"unexpected error: {exc}")
        return EXIT_ERROR


def _report_access_denied(exc: OSError, install_dir: Path) -> int:
    """Log the denial, and say which object was refused so the caller can name it."""
    path = getattr(exc, "filename", None) or ""
    if path:
        log(f"{DENIED_PATH_MARKER}{path}")
        scope = DENIED_SCOPE_INSTALL_DIR if _within(path, install_dir) else DENIED_SCOPE_PARENT
        log(f"{DENIED_SCOPE_MARKER}{scope}")
    log(_access_denied_message(exc))
    return EXIT_DENIED


def _within(path: str, root: Path) -> bool:
    """Whether path is root or under it, by spelling alone; both sides come from the same
    --install-dir string, and resolving links would need the access that was just denied."""
    normalized = os.path.normcase(os.path.abspath(path))
    base = os.path.normcase(os.path.abspath(root))
    return normalized == base or normalized.startswith(base.rstrip(os.sep) + os.sep)


def _access_denied_message(exc: OSError) -> str:
    """Say that this is a permission problem, and that elevation may not fix it.

    Reported as "unexpected error" before, which the caller then followed with
    "install Node yourself, or check your network". Neither is the fix, and a
    user whose antivirus is holding the folder can spend a long time on the
    second one. Antivirus ransomware protection and Controlled folder access
    both deny regardless of privilege, so running elevated is not the answer
    either.
    """
    path = getattr(exc, "filename", None) or ""
    where = f" writing {path}" if path else ""
    return (
        f"access denied{where}. This is a permissions or security-software block, "
        "not a download problem. Antivirus ransomware protection (Bitdefender Safe Files, "
        "Defender Controlled folder access and the like) denies this whatever your "
        "privileges are, so running elevated may not clear it. Allow or exclude the "
        "Unsloth folder in your antivirus, or delete or rename it (it is a managed cache "
        "and setup reinstalls it), then re-run setup."
    )


if __name__ == "__main__":
    raise SystemExit(main())