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.

52.7 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0

"""studio-update only warned on a failed import; llama-update --check said current when unreachable."""

from __future__ import annotations

import os
import shutil
import subprocess
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[2]
STUDIO_UPDATE = REPO_ROOT / "docker" / "unsloth_studio_update.sh"
LLAMA_UPDATE = REPO_ROOT / "docker" / "unsloth_llama_update.sh"

pytestmark = pytest.mark.skipif(
    shutil.which("bash") is None,
    reason = "needs bash",
)


def _stub(directory: Path, name: str, body: str) -> None:
    directory.mkdir(parents = True, exist_ok = True)
    path = directory / name
    path.write_text("#!/usr/bin/env bash\n" + body, encoding = "utf-8")
    path.chmod(0o755)


def _run(
    script: Path,
    args,
    env,
    cwd = None,
):
    return subprocess.run(
        ["bash", str(script), *args],
        capture_output = True,
        text = True,
        env = env,
        cwd = cwd,
        timeout = 120,
    )


def _studio_env(
    tmp_path: Path,
    *,
    import_ok: bool = True,
    dist_ok: bool = True,
    status_exit: int = 0,
    git_ls_exit: int = 0,
    npm_build_ok: bool = True,
    src_link: bool = False,
    restart_exit: int = 0,
) -> dict:
    """Builds a Studio home whose venv runs the real interpreter over a fake studio package so
    import and frontend checks run; pip, supervisorctl, git and npm are recording stubs."""
    home = tmp_path / "studio"
    site = tmp_path / "site"
    (site / "studio" / "backend").mkdir(parents = True)
    (site / "studio" / "__init__.py").write_text("")
    (site / "studio" / "backend" / "__init__.py").write_text("")
    (site / "studio" / "backend" / "main.py").write_text(
        "" if import_ok else "raise ImportError('No module named structlog')\n"
    )
    for name, ver in (("unsloth", "2026.9.4"), ("unsloth_zoo", "2026.9.3")):
        info = site / f"{name}-{ver}.dist-info"
        info.mkdir(parents = True)
        (info / "METADATA").write_text(f"Metadata-Version: 2.1\nName: {name}\nVersion: {ver}\n")
    if dist_ok:
        (site / "studio" / "frontend" / "dist").mkdir(parents = True)
        (site / "studio" / "frontend" / "dist" / "index.html").write_text("<html></html>")
    src = (tmp_path / "app" / "src") if src_link else (home / "src")
    (src / "studio").mkdir(parents = True)
    (src / "OLD_TREE").write_text("previous source tree\n")
    if src_link:
        home.mkdir(parents = True, exist_ok = True)
        (home / "src").symlink_to(src)

    venv_bin = home / "unsloth_studio" / "bin"
    _stub(
        venv_bin,
        "python",
        'if [ "$1" = "-m" ] && [ "$2" = "pip" ]; then\n'
        '  echo "STUB-PIP $*" >> "$STUB_LOG"\n'
        # STUB_FREEZE_EXIT fails every freeze; STUB_FREEZE_EXIT_AFTER only the ones after an install
        '  if [ "$3" = "freeze" ]; then [ -n "${STUB_FREEZE_EXIT:-}" ] && exit "$STUB_FREEZE_EXIT"; [ -n "${STUB_FREEZE_EXIT_AFTER:-}" ] && [ -e "$STUB_LOG.installed" ] && exit "$STUB_FREEZE_EXIT_AFTER"; echo "transformers==4.0.0"; echo "torch==2.11.0+cu128"; [ -e "$STUB_LOG.installed" ] && echo "newdep==1.0"; exit 0; fi\n'
        '  case " $* " in *" -r "*) ;; *" install "*) : > "$STUB_LOG.installed" ;; esac\n'
        '  _c=0; for _a in "$@"; do [ "$_c" = 1 ] && { echo "STUB-PIP-CONSTRAINTS $(tr "\\n" " " < "$_a")" >> "$STUB_LOG"; _c=0; }; [ "$_a" = "-c" ] && _c=1; done\n'
        '  _r=0; for _a in "$@"; do [ "$_r" = 1 ] && { echo "STUB-PIP-REQ $(tr "\\n" " " < "$_a")" >> "$STUB_LOG"; _r=0; }; [ "$_a" = "-r" ] && _r=1; done\n'
        # The updater waits on this child, so the signal lands on it and its trap runs on exit.
        '  case " $* " in *" -e "*) [ -n "${STUB_PIP_INTERRUPT:-}" ] && kill -INT "$PPID" ;; esac\n'
        '  case " $* " in *" -U "*) [ -n "${STUB_PIP_INTERRUPT_RELEASE:-}" ] && kill -INT "$PPID" ;; esac\n'
        '  case " $* " in *" -r "*) [ -n "${STUB_PIP_INTERRUPT_RESTORE:-}" ] && kill -TERM "$PPID" ;; esac\n'
        '  case " $* " in *" -r "*)\n'
        f'    : > "{site}/studio/backend/main.py"\n'
        f'    mkdir -p "{site}/studio/frontend/dist"; echo ok > "{site}/studio/frontend/dist/index.html" ;;\n'
        "  esac\n"
        # STUB_PIP_INSTALL_EXIT spares the restore's -r installs; STUB_PIP_EXIT fails every call.
        '  case " $* " in *" -r "*) ;; *) [ -n "${STUB_PIP_INSTALL_EXIT:-}" ] && exit "$STUB_PIP_INSTALL_EXIT" ;; esac\n'
        '  exit "${STUB_PIP_EXIT:-0}"\n'
        "fi\n"
        f'PYTHONPATH="{site}" exec "{shutil.which("python3")}" "$@"\n',
    )
    _stub(
        home / "node" / "bin",
        "npm",
        'echo "STUB-NPM $* in $PWD" >> "$STUB_LOG"\n'
        'if [ "$1" = "ci" ]; then exit "${STUB_NPM_CI_EXIT:-0}"; fi\n'
        'if [ "$*" = "run build" ]; then\n'
        + (
            "  mkdir -p dist && echo '<html></html>' > dist/index.html; exit 0\n"
            if npm_build_ok
            else "  exit 1\n"
        )
        + "fi\nexit 0\n",
    )
    bin_dir = tmp_path / "bin"
    _stub(
        bin_dir,
        "supervisorctl",
        'echo "STUB-SUPERVISORCTL $*" >> "$STUB_LOG"\n'
        f'if [ "$1" = "status" ]; then [ -e "$STUB_LOG.started" ] && exit 0; exit {status_exit}; fi\n'
        f'if [ "$1" = "restart" ] || [ "$1" = "start" ]; then [ {restart_exit} = 0 ] && : > "$STUB_LOG.started"; exit {restart_exit}; fi\nexit 0\n',
    )
    _stub(
        bin_dir,
        "git",
        'dir=""; if [ "$1" = "-C" ]; then dir="$2"; shift 2; fi\n'
        'case "$1" in\n'
        f"  ls-remote) exit {git_ls_exit} ;;\n"
        '  checkout) mkdir -p "$dir/studio/frontend/src" "$dir/.git"'
        ' "$dir/studio/backend/core/data_recipe/oxc-validator";'
        ' echo "{}" > "$dir/studio/frontend/package.json";'
        ' [ -n "${STUB_LOCKFILE:-}" ] && echo "{}" > "$dir/studio/frontend/package-lock.json";'
        ' echo "{}" > "$dir/studio/backend/core/data_recipe/oxc-validator/package.json";'
        ' [ -n "${STUB_OXC_LOCKFILE:-}" ] && echo "{}" > "$dir/studio/backend/core/data_recipe/oxc-validator/package-lock.json";'
        ' echo new > "$dir/NEW_TREE" ;;\n'
        "esac\nexit 0\n",
    )
    env = dict(os.environ)
    env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
    env["UNSLOTH_STUDIO_HOME"] = str(home)
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "0"
    env["STUB_LOG"] = str(tmp_path / "calls.log")
    return env


def _scratch(d: Path, pattern: str = ".src-*") -> list:
    """The updater's scratch entries, minus the lock file it keeps on purpose."""
    return [p for p in d.glob(pattern) if p.name != ".src-update.lock"]


def _calls(env) -> str:
    log = Path(env["STUB_LOG"])
    return log.read_text() if log.exists() else ""


def test_studio_update_restarts_when_the_backend_imports(tmp_path: Path):
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "STUB-SUPERVISORCTL restart studio" in _calls(env), _calls(env)


def test_studio_update_does_not_restart_into_a_backend_that_cannot_import(tmp_path: Path):
    env = _studio_env(tmp_path, import_ok = False)
    res = _run(STUDIO_UPDATE, [], env)
    calls = _calls(env)
    assert "STUB-SUPERVISORCTL restart studio" not in calls, (
        "restarting into code that cannot import kills a process that is serving "
        "fine and parks supervisord's studio program in FATAL:\n" + calls
    )
    assert res.returncode != 0, "a broken update must not report success"
    assert "--with-deps" in res.stdout, "the remedy must still be printed"
    # --force-reinstall: pip treats a same-version editable as already satisfying the pin.
    assert "install --no-deps --force-reinstall -r" in calls, (
        "the previous install must be put back:\n" + calls
    )


def test_studio_update_does_not_restart_into_a_tree_without_a_built_frontend(tmp_path: Path):
    """The --ref failure: a git build has no studio/frontend/dist, `unsloth studio`
    exits 1 on start, and three quick exits leave supervisord's program FATAL."""
    env = _studio_env(tmp_path, dist_ok = False)
    res = _run(STUDIO_UPDATE, [], env)
    calls = _calls(env)
    assert res.returncode != 0
    assert "no built frontend" in res.stdout
    assert "STUB-SUPERVISORCTL restart studio" not in calls, calls
    assert "install --no-deps --force-reinstall -r" in calls, calls


@pytest.mark.parametrize("status_exit, verb", [(0, "restart"), (3, "start")])
def test_studio_update_restarts_a_studio_that_is_not_running(tmp_path: Path, status_exit, verb):
    """`supervisorctl status` exits 3 for STOPPED/EXITED/FATAL. That is still a program
    supervisord manages, and FATAL is what a failed earlier update left behind. It gets
    `start`: `restart` stops it first, which supervisorctl reports as an error."""
    env = _studio_env(tmp_path, status_exit = status_exit)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert f"STUB-SUPERVISORCTL {verb} studio" in _calls(env), _calls(env)
    assert "not managing" not in res.stdout


def test_studio_update_fails_when_supervisor_cannot_restart_studio(tmp_path: Path):
    """The previous tree is kept until the service is up, so a failed restart puts it back and
    starts that tree again instead of leaving Studio down."""
    env = _studio_env(tmp_path, restart_exit = 1)
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env)
    assert res.returncode != 0, res.stdout
    assert "ERROR: supervisorctl restart studio failed" in res.stdout, res.stdout
    assert "previous install is back in place" in res.stderr, res.stderr
    assert (home / "src" / "OLD_TREE").exists(), "the previous source tree was not put back"
    assert not (home / "src" / "NEW_TREE").exists()
    assert not _scratch(home)
    assert "install --no-deps --force-reinstall -r" in calls, calls
    sup = [l for l in calls.splitlines() if l.startswith("STUB-SUPERVISORCTL")]
    assert sup[-1] == "STUB-SUPERVISORCTL status studio", calls
    assert "STUB-SUPERVISORCTL restart studio" in sup[1:], (
        "the previous install must be started again:\n" + calls
    )
    env = _studio_env(tmp_path / "release", restart_exit = 1)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode != 0, res.stdout
    assert "install --no-deps --force-reinstall -r" in _calls(env), _calls(env)


def test_studio_update_refuses_to_run_beside_another_updater(tmp_path: Path):
    """Two updaters at once would take each other's staging and previous trees for
    leftovers and swap over each other's src."""
    fcntl = pytest.importorskip("fcntl")
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    lock = home / ".src-update.lock"
    fd = os.open(lock, os.O_WRONLY | os.O_CREAT)
    fcntl.flock(fd, fcntl.LOCK_EX)
    try:
        res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
        assert res.returncode == 1, res.stderr + res.stdout
        assert "another unsloth-studio-update is running" in res.stderr, res.stderr
        assert "STUB-PIP" not in _calls(env) and "STUB-NPM" not in _calls(env), _calls(env)
        assert (home / "src" / "OLD_TREE").exists()
    finally:
        fcntl.flock(fd, fcntl.LOCK_UN)
        os.close(fd)
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert (home / "src" / "NEW_TREE").exists()
    # The lock file shares the scratch prefix; the startup sweep must not treat it as leftover.
    assert "left behind" not in res.stdout, res.stdout
    assert not _scratch(home), "the lock file must not outlive the run"


def test_studio_update_reports_an_unmanaged_studio(tmp_path: Path):
    env = _studio_env(tmp_path, status_exit = 4)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "STUB-SUPERVISORCTL restart studio" not in _calls(env)
    assert "not managing 'studio'" in res.stdout


def test_studio_update_ref_builds_the_frontend_and_swaps_the_source_tree(tmp_path: Path):
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    calls = _calls(env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode == 0, res.stderr + res.stdout
    assert "STUB-NPM run build" in calls, calls
    assert (home / "src" / "NEW_TREE").exists(), "src was not replaced by the fetched ref"
    assert (home / "src" / "studio" / "frontend" / "dist" / "index.html").exists()
    assert not (home / "src" / ".git").exists()
    assert not _scratch(home, ".src-prev.*"), "the previous tree was not cleaned up"
    assert not _scratch(home, ".src-update.*"), "the staging tree was not cleaned up"
    assert f"install --no-deps -e {home / 'src'}" in calls, calls


def test_studio_update_ref_writes_through_a_linked_source_tree(tmp_path: Path):
    """Replacing that link with a directory would put the tree outside the image's copy,
    where the next container start relinks over it and the update is silently gone."""
    env = _studio_env(tmp_path, src_link = True)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    real_src = tmp_path / "app" / "src"
    assert res.returncode == 0, res.stderr + res.stdout
    assert (home / "src").is_symlink(), "the link was replaced by a directory"
    assert (real_src / "NEW_TREE").exists(), "the ref was not installed where the code lives"
    assert not _scratch(home), "staging trees must not land in the data volume"
    assert not _scratch(real_src.parent, ".src-prev.*")
    assert f"install --no-deps -e {home / 'src'}" in _calls(env), _calls(env)


def test_studio_update_ref_with_a_failed_frontend_build_changes_nothing(tmp_path: Path):
    env = _studio_env(tmp_path, npm_build_ok = False)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env)
    assert res.returncode != 0
    assert (home / "src" / "OLD_TREE").exists(), "the running source tree was touched"
    assert "STUB-PIP" not in calls, calls
    assert not _scratch(home, ".src-update.*")
    # errexit is off inside `( ... ) || return`, so the build step must stop by itself.
    assert "npm run build failed" in res.stdout, res.stdout
    assert "oxc-validator" not in calls, (
        "a failed build must not go on to the oxc install:\n" + calls
    )


def test_studio_update_ref_installs_the_oxc_runtime_after_a_good_build(tmp_path: Path):
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    oxc = [
        l
        for l in _calls(env).splitlines()
        if "STUB-NPM install" in l and l.endswith("oxc-validator")
    ]
    assert oxc, _calls(env)
    env = _studio_env(tmp_path / "locked")
    env["STUB_OXC_LOCKFILE"] = "1"
    env["UNSLOTH_NPM_REGISTRY"] = "https://mirror.example/npm/"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    oxc = [l for l in _calls(env).splitlines() if "STUB-NPM" in l and l.endswith("oxc-validator")]
    assert len(oxc) == 1 and oxc[0].startswith("STUB-NPM ci "), _calls(env)
    assert "--registry https://mirror.example/npm/" in oxc[0], oxc[0]
    env = _studio_env(tmp_path / "drift")
    env["STUB_OXC_LOCKFILE"] = "1"
    env["STUB_NPM_CI_EXIT"] = "1"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode != 0
    assert "npm ci failed for the oxc validator" in res.stdout, res.stdout
    assert not [
        l
        for l in _calls(env).splitlines()
        if "STUB-NPM install" in l and l.endswith("oxc-validator")
    ], "lockfile drift must not be re-resolved:\n" + _calls(env)
    assert (Path(env["UNSLOTH_STUDIO_HOME"]) / "src" / "OLD_TREE").exists()


def test_studio_update_rollback_keeps_the_editable_uri_pip_recorded(tmp_path: Path):
    """direct_url.json holds a file:// URI; a path with a space comes back percent
    encoded, and pip rejects that as a bare path but takes it as the URI."""
    env = _studio_env(tmp_path, import_ok = False)
    site = tmp_path / "site"
    info = site / "unsloth-2026.9.4.dist-info"  # seeded by _studio_env
    (info / "direct_url.json").write_text(
        '{"url": "file:///opt/my%20studio/src", "dir_info": {"editable": true}}'
    )
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    assert res.returncode != 0
    assert "STUB-PIP-REQ -e file:///opt/my%20studio/src" in _calls(env), _calls(env)


def test_studio_update_ref_restores_the_tree_when_interrupted_after_the_swap(tmp_path: Path):
    """An interrupt (Ctrl-C or docker stop) between the swap and the checks left the half-installed
    tree and the old one as .src-prev entries, which the next start links into the Studio home."""
    env = _studio_env(tmp_path)
    env["STUB_PIP_INTERRUPT"] = "1"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode == 130, res.stderr + res.stdout
    assert (home / "src" / "OLD_TREE").exists(), "the previous source tree was not put back"
    assert not (home / "src" / "NEW_TREE").exists()
    assert not _scratch(home, ".src-prev.*"), "the previous tree was left beside src"
    assert not _scratch(home, ".src-update.*")
    assert "interrupted" in res.stdout, res.stdout


def test_studio_update_release_restores_the_pins_when_interrupted_during_pip(tmp_path: Path):
    """The release path swaps nothing, but a pip interrupted half-way can have replaced
    the packages already; the recorded previous install goes back the same way."""
    env = _studio_env(tmp_path)
    env["STUB_PIP_INTERRUPT_RELEASE"] = "1"
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    calls = _calls(env)
    assert res.returncode == 130, res.stderr + res.stdout
    assert "install --no-deps --force-reinstall -r" in calls, (
        "the previous install was not put back:\n" + calls
    )
    assert "interrupted" in res.stdout, res.stdout


def test_studio_update_restores_once_and_leaves_no_temp_files_when_signalled_mid_restore(
    tmp_path: Path,
):
    """After a failed tree check the script restores explicitly, so the exit trap must not restore a
    second time and a signal mid-restore must not skip temp-file cleanup."""
    env = _studio_env(tmp_path, dist_ok = False)
    env["STUB_PIP_INTERRUPT_RESTORE"] = "1"
    tmpd = tmp_path / "tmpd"
    tmpd.mkdir()
    env["TMPDIR"] = str(tmpd)
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    calls = _calls(env)
    assert res.returncode != 0
    assert calls.count("--force-reinstall -r") == 1, "restore ran more than once:\n" + calls
    assert not list(tmpd.iterdir()), "temp files left behind: " + str(list(tmpd.iterdir()))


def test_studio_update_ref_refuses_a_venv_without_a_source_tree(tmp_path: Path):
    """A wheel-only install has no src; `mv` of a missing tree must not be the error."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    shutil.rmtree(home / "src")
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode != 0
    assert "no source tree" in res.stderr, res.stderr
    assert "STUB-NPM" not in _calls(
        env
    ), "nothing should be built for a tree that cannot be swapped"


def test_studio_update_with_deps_puts_the_dependency_set_back(tmp_path: Path):
    """--with-deps lets pip move every dependency; restoring unsloth alone would leave
    the new dependency set under the old code."""
    env = _studio_env(tmp_path, import_ok = False)
    res = _run(STUDIO_UPDATE, ["--with-deps"], env)
    calls = _calls(env)
    assert res.returncode != 0
    assert "STUB-PIP -m pip freeze --exclude-editable" in calls, calls
    assert calls.count("install --no-deps -r") == 1, "dependency snapshot:\n" + calls
    assert calls.count("install --no-deps --force-reinstall -r") == 1, "previous install:\n" + calls
    # torch/CUDA must not be re-resolved: the venv's nvidia libs are linked into the base venv.
    assert "unsloth[studio]" in calls, calls
    assert "STUB-PIP-CONSTRAINTS torch==2.11.0+cu128" in calls, calls
    assert "transformers==4.0.0" not in [
        l for l in calls.splitlines() if l.startswith("STUB-PIP-CONSTRAINTS")
    ], "only the torch/CUDA stack is a constraint"
    env = _studio_env(tmp_path / "nodeps", import_ok = False)
    res = _run(STUDIO_UPDATE, [], env)
    assert "freeze" not in _calls(env), "a --no-deps update has nothing to snapshot"
    assert " -c " not in _calls(env)


def test_studio_update_ref_with_deps_installs_the_studio_extra(tmp_path: Path):
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--with-deps", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode == 0, res.stderr + res.stdout
    assert f"-e {home / 'src'}[studio]" in _calls(env), _calls(env)
    assert "STUB-PIP-CONSTRAINTS torch==2.11.0+cu128" in _calls(env), _calls(env)


def test_studio_update_ref_puts_the_old_tree_back_when_the_new_one_cannot_start(tmp_path: Path):
    env = _studio_env(tmp_path, import_ok = False)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode != 0
    assert (home / "src" / "OLD_TREE").exists(), "the previous source tree was not restored"
    assert not (home / "src" / "NEW_TREE").exists()


def _zoo_spec(calls: str) -> str:
    for line in calls.splitlines():
        for token in line.split():
            if token.startswith("git+https://github.com/unslothai/unsloth-zoo.git@"):
                return token
    return ""


def test_studio_update_mirrors_the_ref_when_the_zoo_has_it(tmp_path: Path):
    env = _studio_env(tmp_path, git_ls_exit = 0)
    res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert _zoo_spec(_calls(env)).endswith("@v2026.7.5#egg=unsloth_zoo"), _calls(env)


def test_studio_update_falls_back_to_zoo_main_when_the_ref_is_absent(tmp_path: Path):
    env = _studio_env(tmp_path, git_ls_exit = 2)
    res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert _zoo_spec(_calls(env)).endswith("@main#egg=unsloth_zoo"), _calls(env)
    assert "has no ref" in res.stdout, res.stdout


def test_studio_update_aborts_when_the_zoo_lookup_never_reached_the_remote(tmp_path: Path):
    # Exit 2 and 128 differ: conflating them pairs unrelated unsloth and zoo revisions.
    env = _studio_env(tmp_path, git_ls_exit = 128)
    res = _run(STUDIO_UPDATE, ["--ref", "v2026.7.5", "--no-restart"], env)
    calls = _calls(env)
    assert "STUB-PIP" not in calls, "a transport failure must not install anything:\n" + calls
    assert res.returncode != 0, "an unresolvable zoo ref must not report success"
    assert "has no ref" not in res.stdout, (
        "an unreachable remote must not be reported as a missing ref:\n" + res.stdout
    )
    assert "--zoo-ref" in res.stderr, "the remedy must be printed"


def test_studio_update_puts_the_install_back_when_pip_itself_fails(tmp_path: Path):
    env = _studio_env(tmp_path)
    env["STUB_PIP_INSTALL_EXIT"] = "1"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode != 0
    assert "previous install is back in place" in res.stderr, res.stderr
    assert (home / "src" / "OLD_TREE").exists(), "the previous source tree was not put back"
    assert not _scratch(home)
    assert "STUB-SUPERVISORCTL" not in _calls(env)


def test_a_signal_during_the_health_wait_puts_the_service_back_too(tmp_path: Path):
    """A Ctrl-C while waiting for /api/health must restart the service on the restored install, as
    back_out does, since restoring files alone leaves a mix of versions."""
    env = _studio_env(tmp_path)
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "30"
    _stub(
        tmp_path / "bin",
        "curl",
        'echo "STUB-CURL $*" >> "$STUB_LOG"\nkill -TERM "$PPID"\nexit 22\n',
    )
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env).splitlines()
    assert res.returncode == 143, res.stdout + res.stderr
    assert "interrupted after the install started" in res.stdout, res.stdout
    assert (home / "src" / "OLD_TREE").exists() and not (home / "src" / "NEW_TREE").exists()
    reinst = [i for i, l in enumerate(calls) if "install --no-deps --force-reinstall -r" in l]
    assert reinst, calls
    after = calls[reinst[-1] + 1 :]
    assert "STUB-SUPERVISORCTL restart studio" in after, calls
    assert "the previous install is running again" in res.stdout, res.stdout
    assert not _scratch(home)


def test_a_health_wait_that_expires_before_its_first_check_still_asks_once(tmp_path: Path):
    """The deadline check must run at least once, or a Studio that was never probed gets rolled back."""
    env = _studio_env(tmp_path)
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "1"
    clock = tmp_path / "clock"
    clock.write_text("1000000000", encoding = "utf-8")
    _stub(
        tmp_path / "bin",
        "date",
        'if [ "$*" = "+%s" ]; then\n'
        f'  t=$(( $(cat "{clock}") + 5 )); echo "$t" > "{clock}"; echo "$t"; exit 0\n'
        "fi\n"
        'exec /bin/date "$@"\n',
    )
    _stub(tmp_path / "bin", "curl", 'echo "STUB-CURL $*" >> "$STUB_LOG"\nexit 0\n')
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env)
    assert "STUB-CURL" in calls, "the wait expired without probing Studio once:\n" + calls
    assert res.returncode == 0, res.stdout + res.stderr
    assert "answering on port 8000" in res.stdout, res.stdout
    assert (home / "src" / "NEW_TREE").exists(), "a healthy update was rolled back"


def test_studio_update_fails_when_studio_does_not_answer_after_the_restart(tmp_path: Path):
    """A backend that imports can still die at startup; the previous tree is kept
    until /api/health answers, and goes back when it does not."""
    env = _studio_env(tmp_path)
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "1"
    _stub(tmp_path / "bin", "curl", 'echo "STUB-CURL $*" >> "$STUB_LOG"\nexit 22\n')
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env)
    assert res.returncode != 0, res.stdout
    assert "did not answer on port 8000" in res.stdout, res.stdout
    assert "STUB-CURL" in calls
    # A container-wide HTTP_PROXY must not answer for the loopback probe.
    assert "--noproxy * http://127.0.0.1:8000/api/health" in calls, calls
    assert "previous install is back in place" in res.stderr, res.stderr
    assert (home / "src" / "OLD_TREE").exists(), "the previous source tree was not put back"
    assert not (home / "src" / "NEW_TREE").exists()
    assert not _scratch(home)
    assert "install --no-deps --force-reinstall -r" in calls, calls
    assert calls.splitlines()[-1] == "STUB-SUPERVISORCTL status studio", calls
    env = _studio_env(tmp_path / "ok")
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "5"
    _stub(tmp_path / "ok" / "bin", "curl", "exit 0\n")
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode == 0, res.stdout
    assert "answering on port 8000" in res.stdout
    assert (home / "src" / "NEW_TREE").exists()
    assert not _scratch(home), "the previous tree must go once Studio is up"
    env = _studio_env(tmp_path / "junk")
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "soon"
    _stub(tmp_path / "junk" / "bin", "curl", "exit 0\n")
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stdout
    assert "not a number" in res.stdout


def test_studio_update_health_wait_zero_commits_once_the_restart_command_succeeds(tmp_path: Path):
    """0 asks for no validation: the previous tree goes as soon as the restart command
    returns, and nothing is fetched from port 8000."""
    env = _studio_env(tmp_path)
    env["UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT"] = "0"
    _stub(tmp_path / "bin", "curl", 'echo "STUB-CURL $*" >> "$STUB_LOG"\nexit 22\n')
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode == 0, res.stderr + res.stdout
    assert "the update is committed" in res.stdout, res.stdout
    assert "STUB-CURL" not in _calls(env)
    assert (home / "src" / "NEW_TREE").exists()
    assert not _scratch(home)
    env = _studio_env(tmp_path / "down", restart_exit = 1)
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode != 0
    assert (home / "src" / "OLD_TREE").exists()


def test_studio_update_clears_leftovers_of_a_killed_run_before_it_starts(tmp_path: Path):
    """SIGKILL from docker stop runs no trap, so leftover previous and staging trees can sit beside
    src; a pid-derived name could be reused and mv would nest into it."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / ".src-prev.4242" / "junk").mkdir(parents = True)
    (home / ".src-update.abc123" / "node_modules").mkdir(parents = True)
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "left behind by an earlier update" in res.stdout, res.stdout
    assert (home / "src" / "NEW_TREE").exists()
    assert not (home / "src" / "junk").exists(), "the tree was nested into the stale dir"
    assert not _scratch(home)


def test_studio_update_recovers_a_source_tree_a_killed_run_moved_aside(tmp_path: Path):
    """SIGKILL between the two moves of the swap leaves no src at all, only .src-prev.*.
    A later plain update must put it back rather than fail on a missing tree."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / "src").rename(home / ".src-prev.abc123")
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "recovering the source tree" in res.stdout, res.stdout
    assert (home / "src" / "OLD_TREE").exists()
    assert not _scratch(home, ".src-prev.*")


def test_studio_update_puts_back_a_previous_tree_a_killed_run_never_committed(tmp_path: Path):
    """A killed update leaves the previous tree beside src; restoring it keeps the only known-good tree."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / "src").rename(home / ".src-prev.abc123")
    (home / "src" / "studio").mkdir(parents = True)
    (home / "src" / "UNVERIFIED").write_text("never passed the health check\n")
    (home / ".src-update.rollback").write_text("-e file:///opt/prev-src\n")
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "putting it back over the unverified one" in res.stdout, res.stdout
    assert (home / "src" / "OLD_TREE").exists()
    assert not (home / "src" / "UNVERIFIED").exists()
    assert not _scratch(home), "the unverified tree was left behind"


def test_studio_update_reads_the_install_record_from_the_venv_not_the_cwd(tmp_path: Path):
    """python - searches the current directory first, so a checkout there with its own dist-info
    would answer for the venv's unsloth and a rollback would reinstall the wrong thing."""
    env = _studio_env(tmp_path, import_ok = False)
    site = tmp_path / "site"
    info = site / "unsloth-2026.9.4.dist-info"  # seeded by _studio_env
    (info / "direct_url.json").write_text(
        '{"url": "file:///opt/venv-src", "dir_info": {"editable": true}}'
    )
    checkout = tmp_path / "checkout"
    decoy = checkout / "unsloth-0.0.1.dist-info"
    decoy.mkdir(parents = True)
    (decoy / "METADATA").write_text("Metadata-Version: 2.1\nName: unsloth\nVersion: 0.0.1\n")
    (decoy / "direct_url.json").write_text(
        '{"url": "file:///checkout", "dir_info": {"editable": true}}'
    )
    res = _run(STUDIO_UPDATE, ["--no-restart"], env, cwd = checkout)
    assert res.returncode != 0
    assert "STUB-PIP-REQ -e file:///opt/venv-src" in _calls(env), _calls(env)
    assert "checkout" not in _calls(env), _calls(env)
    assert "before: unsloth 2026.9.4" in res.stdout, res.stdout


def test_studio_update_records_every_packages_target_for_the_rollback(tmp_path: Path):
    """--packages can name targets beyond unsloth and unsloth_zoo; the rollback must record all of
    them, or an extra target stays upgraded while the restore reports success."""
    env = _studio_env(tmp_path, import_ok = False)
    site = tmp_path / "site"
    info = site / "bar-1.0.dist-info"
    info.mkdir()
    (info / "METADATA").write_text("Metadata-Version: 2.1\nName: bar\nVersion: 1.0\n")
    res = _run(
        STUDIO_UPDATE, ["--no-restart", "--packages", "unsloth unsloth_zoo bar>=2 foo==2"], env
    )
    calls = _calls(env)
    assert res.returncode != 0
    req = [l for l in calls.splitlines() if l.startswith("STUB-PIP-REQ")][0]
    assert "bar==1.0" in req, req
    assert "# absent: foo" in req, req
    assert "STUB-PIP -m pip uninstall -y foo" in calls, calls
    assert "uninstall -y bar" not in calls


def test_studio_update_with_deps_stops_when_the_dependency_snapshot_fails(tmp_path: Path):
    """An empty snapshot would let the install run with nothing to pin back."""
    env = _studio_env(tmp_path, import_ok = False)
    env["STUB_FREEZE_EXIT"] = "1"
    res = _run(STUDIO_UPDATE, ["--with-deps"], env)
    assert res.returncode != 0
    assert "pip freeze failed" in res.stderr and "nothing was changed" in res.stderr, res.stderr
    assert "install" not in _calls(env), _calls(env)


def test_studio_update_finishes_the_package_restore_a_killed_run_left(tmp_path: Path):
    """SIGKILL after pip replaced packages but before the commit leaves a rollback record beside the
    tree; the next run finishes that restore before recording a new previous install."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / ".src-update.rollback").write_text("-e file:///opt/prev-src\n# absent: foo\n")
    (home / ".src-update.freeze").write_text("transformers==3.9.0\n")
    res = _run(STUDIO_UPDATE, [], env)
    calls = _calls(env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "putting the previous packages back first" in res.stdout, res.stdout
    reqs = [l for l in calls.splitlines() if l.startswith("STUB-PIP-REQ")]
    assert reqs[0] == "STUB-PIP-REQ transformers==3.9.0 ", reqs
    assert "-e file:///opt/prev-src" in reqs[1], reqs
    assert "STUB-PIP -m pip uninstall -y foo" in calls, calls
    assert not _scratch(home, ".src-update.*")


@pytest.mark.parametrize("status_exit, verb", [(0, "restart"), (3, "start")])
def test_studio_update_recovery_puts_the_service_on_the_restored_install(
    tmp_path: Path, status_exit, verb
):
    """A killed run may have left Studio FATAL, so recovery restarts it on the restored install first."""
    env = _studio_env(tmp_path, status_exit = status_exit, git_ls_exit = 1)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / ".src-update.rollback").write_text("-e file:///opt/prev-src\n")
    res = _run(STUDIO_UPDATE, ["--ref", "main"], env)
    calls = _calls(env)
    assert res.returncode != 0, res.stdout
    assert "the previous packages are back" in res.stdout, res.stdout
    assert "running the restored install" in res.stdout, res.stdout
    sup = [l for l in calls.splitlines() if l.startswith("STUB-SUPERVISORCTL")]
    assert sup[1] == f"STUB-SUPERVISORCTL {verb} studio", sup
    assert not (home / ".src-update.rollback").exists()
    env = _studio_env(tmp_path / "noreset", git_ls_exit = 1)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / ".src-update.rollback").write_text("-e file:///opt/prev-src\n")
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert "STUB-SUPERVISORCTL" not in _calls(env), _calls(env)
    assert "restart it to load the restored install" in res.stdout, res.stdout


def test_studio_update_with_deps_rollback_fails_when_pip_cannot_list_packages(tmp_path: Path):
    """The packages the update pulled in come from a second pip freeze; if that fails nothing can be
    removed, so the restore is reported unfinished and the record stays."""
    env = _studio_env(tmp_path, import_ok = False)
    env["STUB_FREEZE_EXIT_AFTER"] = "1"
    res = _run(STUDIO_UPDATE, ["--with-deps", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode != 0
    assert "could not list the installed packages" in res.stdout, res.stdout
    assert "could not be restored cleanly" in res.stdout, res.stdout
    assert (
        home / ".src-update.rollback"
    ).is_file(), "the record was dropped after a failed restore"


def test_recover_finishes_a_killed_update_and_does_nothing_else(tmp_path: Path):
    """The container start runs --recover before supervisord starts Studio: a previous tree goes
    back over the unverified src, recorded packages are reinstalled, and no update runs."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / "src" / "OLD_TREE").unlink()
    (home / "src" / "NEW_TREE").write_text("unverified\n")
    (home / ".src-prev.k9x2Qa" / "studio").mkdir(parents = True)
    (home / ".src-prev.k9x2Qa" / "OLD_TREE").write_text("previous\n")
    (home / ".src-update.rollback").write_text("-e file:///opt/prev-src\n")
    res = _run(STUDIO_UPDATE, ["--recover"], env)
    calls = _calls(env)
    assert res.returncode == 0, res.stdout + res.stderr
    assert "recovery done" in res.stdout, res.stdout
    assert (home / "src" / "OLD_TREE").exists() and not (home / "src" / "NEW_TREE").exists()
    assert not (home / ".src-prev.k9x2Qa").exists()
    assert not (home / ".src-update.rollback").exists()
    assert "install --no-deps --force-reinstall -r" in calls, calls
    assert "install -U" not in calls and "STUB-GIT" not in calls, calls
    assert not _scratch(home)
    env = _studio_env(tmp_path / "clean")
    res = _run(STUDIO_UPDATE, ["--recover"], env)
    assert res.returncode == 0 and "nothing to recover" in res.stdout, res.stdout
    assert "STUB-PIP -m pip install" not in _calls(env)


def test_studio_update_says_when_the_restore_did_not_finish(tmp_path: Path):
    """pip failing during the restore itself must not be reported as the previous
    install being back; the record stays so the next run finishes it."""
    env = _studio_env(tmp_path, import_ok = False)
    env["STUB_PIP_EXIT"] = "1"
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    assert res.returncode != 0
    assert "back in place" not in res.stderr, res.stderr
    assert "could not put every previous package back" in res.stderr, res.stderr
    assert (
        home / ".src-update.rollback"
    ).is_file(), "the record was dropped after a failed restore"
    del env["STUB_PIP_EXIT"]
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    assert "putting the previous packages back first" in res.stdout, res.stdout
    assert not (home / ".src-update.rollback").exists()


def test_studio_update_keeps_the_lock_file(tmp_path: Path):
    """Unlinking the lock would let a run that opened the old inode take the lock after
    this one exits while a later run locks a fresh file at the same path."""
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, ["--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert (Path(env["UNSLOTH_STUDIO_HOME"]) / ".src-update.lock").is_file()


def test_studio_update_treats_a_previous_tree_without_a_record_as_scratch(tmp_path: Path):
    """The record is unlinked before the previous tree is deleted, so a previous tree without a
    record is scratch from a committed update killed mid-delete; src is the healthy tree."""
    env = _studio_env(tmp_path)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    (home / ".src-prev.abc123" / "studio").mkdir(parents = True)
    (home / ".src-prev.abc123" / "COMMITTED_AWAY").write_text("")
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert (home / "src" / "OLD_TREE").exists()
    assert "putting it back" not in res.stdout, res.stdout
    assert not _scratch(home)


def test_studio_update_with_deps_adds_the_studio_extra_to_a_qualified_unsloth_spec(tmp_path: Path):
    """--packages can pin or qualify unsloth; the studio extra must still ride along,
    and unsloth_zoo must not be mistaken for it."""
    env = _studio_env(tmp_path)
    res = _run(
        STUDIO_UPDATE,
        ["--with-deps", "--no-restart", "--packages", "unsloth==2026.9.1 unsloth_zoo"],
        env,
    )
    assert res.returncode == 0, res.stderr + res.stdout
    calls = _calls(env)
    assert "unsloth[studio]==2026.9.1" in calls, calls
    assert "unsloth[studio]_zoo" not in calls and " unsloth_zoo" in calls, calls
    env = _studio_env(tmp_path / "extras")
    res = _run(
        STUDIO_UPDATE, ["--with-deps", "--no-restart", "--packages", "unsloth[cu128]>=2026.9"], env
    )
    assert "unsloth[studio,cu128]>=2026.9" in _calls(env), _calls(env)


def test_studio_update_with_deps_rollback_removes_what_the_update_pulled_in(tmp_path: Path):
    """Reinstalling the snapshot puts back what was there; a dependency the update
    introduced would otherwise stay and become part of the next snapshot."""
    env = _studio_env(tmp_path, import_ok = False)
    res = _run(STUDIO_UPDATE, ["--with-deps", "--no-restart"], env)
    assert res.returncode != 0
    calls = _calls(env)
    assert "STUB-PIP -m pip uninstall -y newdep" in calls, calls
    assert "uninstall -y transformers" not in calls and "uninstall -y torch" not in calls, calls


def test_studio_update_ref_uses_the_lockfile_and_does_not_fall_back_to_npm_install(tmp_path: Path):
    env = _studio_env(tmp_path)
    env["STUB_LOCKFILE"] = "1"
    env["STUB_NPM_CI_EXIT"] = "1"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    home = Path(env["UNSLOTH_STUDIO_HOME"])
    calls = _calls(env)
    assert res.returncode != 0
    assert "npm ci failed" in res.stdout, res.stdout
    frontend_installs = [
        l for l in calls.splitlines() if "STUB-NPM install" in l and l.endswith("frontend")
    ]
    assert not frontend_installs, (
        "a lockfile that does not apply must not be re-resolved:\n" + calls
    )
    assert (home / "src" / "OLD_TREE").exists()
    env = _studio_env(tmp_path / "nolock")
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    calls = _calls(env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "STUB-NPM ci" not in calls, calls
    assert "no package-lock.json" in res.stdout, res.stdout


def test_studio_update_ref_threads_the_npm_registry_override(tmp_path: Path):
    env = _studio_env(tmp_path)
    env["STUB_LOCKFILE"] = "1"
    env["UNSLOTH_NPM_REGISTRY"] = "https://mirror.example/npm/"
    res = _run(STUDIO_UPDATE, ["--ref", "main", "--no-restart"], env)
    assert res.returncode == 0, res.stderr + res.stdout
    for line in [
        l for l in _calls(env).splitlines() if "STUB-NPM ci" in l or "STUB-NPM install" in l
    ]:
        assert "--registry https://mirror.example/npm/" in line, line


def test_studio_update_help_prints_only_the_header(tmp_path: Path):
    env = _studio_env(tmp_path)
    res = _run(STUDIO_UPDATE, ["--help"], env)
    assert res.returncode == 0
    assert "set -euo pipefail" not in res.stdout
    assert "UNSLOTH_STUDIO_UPDATE_HEALTH_WAIT" in res.stdout


def _llama_env(
    tmp_path: Path,
    *,
    latest: str | None,
    marker: str = '{"tag": "b1111-old"}',
) -> dict:
    install = tmp_path / "llama.cpp"
    install.mkdir(parents = True)
    (install / "UNSLOTH_PREBUILT_INFO.json").write_text(
        marker + "\n",
        encoding = "utf-8",
    )
    fetcher = tmp_path / "fetch_llama_prebuilt.py"
    resolve = (
        "    raise RuntimeError('unreachable')\n" if latest is None else f"    return {latest!r}\n"
    )
    fetcher.write_text(
        "def resolve_latest_tag(repo):\n" + resolve,
        encoding = "utf-8",
    )
    env = dict(os.environ)
    env["UNSLOTH_LLAMA_CPP_PATH"] = str(install)
    env["UNSLOTH_LLAMA_FETCHER"] = str(fetcher)
    return env


def _llama_check(tmp_path: Path, latest, **kwargs):
    env = _llama_env(tmp_path, latest = latest, **kwargs)
    return _run(LLAMA_UPDATE, ["--check"], env)


def test_llama_check_reports_an_available_update(tmp_path: Path):
    res = _llama_check(tmp_path, "b2222-new")
    assert res.returncode == 0, res.stderr
    assert "an update is available" in res.stdout


def test_llama_check_reports_up_to_date(tmp_path: Path):
    res = _llama_check(tmp_path, "b1111-old")
    assert res.returncode == 0, res.stderr
    assert "up to date" in res.stdout


def test_llama_check_reads_the_full_release_tag_not_the_base_build(tmp_path: Path):
    # The latest pointer is the full tag_name; reading the normalized tag offers updates forever.
    res = _llama_check(
        tmp_path,
        "b10715-mix-86bd2d3",
        marker = '{"tag": "b10715", "release_tag": "b10715-mix-86bd2d3"}',
    )
    assert res.returncode == 0, res.stderr
    assert "up to date" in res.stdout, (
        "the installed release IS the latest release; reporting an update here nags "
        "forever because applying it cannot change the comparison:\n" + res.stdout
    )
    assert "installed:   b10715-mix-86bd2d3" in res.stdout, (
        "the reported installed version must be the full release identity it is "
        "compared against:\n" + res.stdout
    )


def test_llama_check_still_offers_a_genuinely_newer_release(tmp_path: Path):
    res = _llama_check(
        tmp_path,
        "b10800-mix-aaaaaaa",
        marker = '{"tag": "b10715", "release_tag": "b10715-mix-86bd2d3"}',
    )
    assert res.returncode == 0, res.stderr
    assert "an update is available" in res.stdout


def test_llama_check_does_not_claim_up_to_date_when_it_could_not_look(tmp_path: Path):
    res = _llama_check(tmp_path, None)
    assert "up to date" not in res.stdout, (
        "--check exists to report update status; saying 'up to date' for a lookup "
        "that never happened is the one answer it must never give:\n" + res.stdout
    )
    assert res.returncode != 0, "an unperformed check must not exit 0"
    assert "UNKNOWN" in res.stdout + res.stderr


def _llama_inplace_env(tmp_path: Path, old: list[str], new: list[str]) -> dict:
    """An in-place (volume-mounted) install whose activation fails part-way."""
    install = tmp_path / "llama.cpp"
    install.mkdir(parents = True)
    for name in old:
        (install / name).write_text("OLD\n", encoding = "utf-8")
    (install / "UNSLOTH_PREBUILT_INFO.json").write_text(
        '{"tag": "b1111-old"}\n',
        encoding = "utf-8",
    )
    fetcher = tmp_path / "fetch_llama_prebuilt.py"
    fetcher.write_text(
        "import os, sys\n"
        "def resolve_latest_tag(repo):\n"
        "    return 'b2222-new'\n"
        "if __name__ == '__main__':\n"
        "    dest = sys.argv[3]\n"
        "    os.makedirs(dest, exist_ok = True)\n"
        f"    for name in {new!r}:\n"
        "        open(os.path.join(dest, name), 'w').write('NEW\\n')\n"
        "    open(os.path.join(dest, 'UNSLOTH_PREBUILT_INFO.json'), 'w')"
        '.write(\'{"tag": "b2222-new"}\\n\')\n',
        encoding = "utf-8",
    )
    bin_dir = tmp_path / "bin"
    _stub(
        bin_dir,
        "mv",
        'if [ "$1" = "-t" ] && [ "$2" = "$FAIL_MV_TARGET" ]; then\n'
        "  shift 2\n"
        '  for _s in "$@"; do /bin/mv "$_s" "$FAIL_MV_TARGET/"; done\n'
        "  exit 1\n"
        "fi\n"
        'exec /bin/mv "$@"\n',
    )
    env = dict(os.environ)
    env["PATH"] = f"{bin_dir}{os.pathsep}" + env["PATH"]
    env["UNSLOTH_LLAMA_CPP_PATH"] = str(install)
    env["UNSLOTH_LLAMA_FETCHER"] = str(fetcher)
    env["UNSLOTH_LLAMA_UPDATE_IN_PLACE"] = "1"
    env["FAIL_MV_TARGET"] = str(install)
    return env


def test_llama_rollback_leaves_no_new_release_files_behind(tmp_path: Path):
    # Only in the new release, so a rollback over the backup's entries cannot remove it.
    old = ["libggml-base.so", "libggml-cpu-icelake.so", "llama-cli"]
    new = [
        "libggml-base.so",
        "libggml-cpu-icelake.so",
        "llama-cli",
        "libggml-hexagon.so",
        "llama-mtmd-cli",
    ]
    env = _llama_inplace_env(tmp_path, old, new)
    res = _run(LLAMA_UPDATE, [], env)
    assert res.returncode != 0, "a failed swap must not report success"
    install = tmp_path / "llama.cpp"
    present = sorted(p.name for p in install.iterdir())
    leftovers = [n for n in ("libggml-hexagon.so", "llama-mtmd-cli") if n in present]
    assert not leftovers, f"new-release-only files survived the rollback: {leftovers} in {present}"
    for name in old:
        assert (
            install / name
        ).read_text() == "OLD\n", f"{name} was not restored from the backup: {present}"


def test_llama_rollback_keeps_every_old_file_when_the_drain_is_interrupted(tmp_path: Path):
    old = ["libggml-base.so", "libggml-cpu-icelake.so", "llama-cli", "llama-quantize"]
    env = _llama_inplace_env(tmp_path, old, old)
    install = tmp_path / "llama.cpp"
    _stub(
        tmp_path / "bin",
        "mv",
        'case "${1:-}:${2:-}" in\n'
        "  -t:*/.old.*)\n"
        '    _t="$2"; shift 2\n'
        '    [ $# -gt 0 ] && /bin/mv "$1" "$_t/"\n'
        "    exit 1;;\n"
        "esac\n"
        'exec /bin/mv "$@"\n',
    )
    res = _run(LLAMA_UPDATE, [], env)
    assert res.returncode != 0
    survivors = sorted(p.name for p in install.rglob("*") if p.is_file())
    for name in old:
        assert name in survivors, f"{name} was lost during an interrupted drain: {survivors}"


def _fetcher_module():
    """Import the build-time fetcher by path; stdlib-only, with a __main__ guard."""
    import importlib.util

    path = REPO_ROOT / "docker" / "fetch_llama_prebuilt.py"
    spec = importlib.util.spec_from_file_location("_fetch_llama_prebuilt", path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


@pytest.mark.parametrize(
    "release_tag, expected",
    [
        ("b10715-mix-86bd2d3", "b10715"),
        ("b10715", "b10715"),
        ("  b9596-mix-e6f2453  ", "b9596"),
        ("not-a-build-tag", "not-a-build-tag"),
    ],
)
def test_fetcher_normalizes_the_base_build_for_the_marker_tag(release_tag, expected):
    assert _fetcher_module().base_build_tag(release_tag) == expected


def test_a_failed_studio_update_puts_the_previous_install_back(tmp_path: Path):
    """Not restarting protected only already-imported code while the venv stayed replaced, so lazy
    imports and later restarts failed; a failed update now reinstalls its starting set."""
    env = _studio_env(tmp_path, import_ok = False)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode != 0, "a broken update must not report success"
    assert "previous install was restored" in res.stdout, res.stdout
    assert "not restarted" in res.stdout, res.stdout


def _managed_node(
    tmp_path: Path,
    env,
    installer_exit: int = 0,
    kept: bool = False,
) -> None:
    """The image's managed Node (installer metadata) and a recording installer in the package."""
    (Path(env["UNSLOTH_STUDIO_HOME"]) / "node" / "UNSLOTH_NODE_PREBUILT_INFO.json").write_text("{}")
    (tmp_path / "site" / "studio" / "install_node_prebuilt.py").write_text(
        "import os, sys\n"
        "with open(os.environ['STUB_LOG'], 'a') as f:\n"
        "    f.write('STUB-NODE ' + ' '.join(sys.argv[1:]) + '\\n')\n"
        + ("print('Node download failed (x); keeping existing isolated Node')\n" if kept else "")
        + f"sys.exit({installer_exit})\n"
    )


def test_studio_update_moves_the_managed_node_to_the_new_pin(tmp_path: Path):
    env = _studio_env(tmp_path)
    _managed_node(tmp_path, env)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    node_dir = Path(env["UNSLOTH_STUDIO_HOME"]) / "node"
    assert f"STUB-NODE --install-dir {node_dir}" in _calls(env), _calls(env)
    assert "STUB-SUPERVISORCTL restart studio" in _calls(env), _calls(env)


@pytest.mark.parametrize("installer_exit, kept", [(1, False), (0, True)])
def test_studio_update_keeps_the_current_node_when_the_new_pin_cannot_install(
    tmp_path: Path, installer_exit: int, kept: bool
):
    env = _studio_env(tmp_path)
    _managed_node(tmp_path, env, installer_exit = installer_exit, kept = kept)
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "keeping the current one" in res.stdout, res.stdout
    assert "matches the new pin" not in res.stdout, res.stdout
    assert "STUB-SUPERVISORCTL restart studio" in _calls(env), _calls(env)


@pytest.mark.parametrize("skip", ["0", "1"])
def test_studio_update_leaves_a_node_it_does_not_manage(tmp_path: Path, skip: str):
    env = _studio_env(tmp_path)
    _managed_node(tmp_path, env)
    env["UNSLOTH_SKIP_NODE_INSTALL"] = skip
    if skip == "0":
        (Path(env["UNSLOTH_STUDIO_HOME"]) / "node" / "UNSLOTH_NODE_PREBUILT_INFO.json").unlink()
    res = _run(STUDIO_UPDATE, [], env)
    assert res.returncode == 0, res.stderr + res.stdout
    assert "STUB-NODE" not in _calls(env), _calls(env)