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.

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

"""The clone walk never sees upstream deletions; remove only files that still match the synced hash."""

from __future__ import annotations

import hashlib
import os
import shutil
import subprocess
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[2]
SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"

behavioural = pytest.mark.skipif(
    any(shutil.which(tool) is None for tool in ("bash", "git", "sha256sum")),
    reason = "needs bash, git and sha256sum",
)


def _sha256(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()


def _git(cwd: Path, *args: str) -> None:
    subprocess.run(
        ["git", *args],
        cwd = cwd,
        check = True,
        capture_output = True,
        env = dict(
            os.environ,
            GIT_AUTHOR_NAME = "t",
            GIT_AUTHOR_EMAIL = "t@e",
            GIT_COMMITTER_NAME = "t",
            GIT_COMMITTER_EMAIL = "t@e",
        ),
    )


FILES = {
    "nb/keep.ipynb": "keep-v1",
    "nb/doomed.ipynb": "doomed-v1",
    "nb/edited.ipynb": "edited-v1",
}


def _setup(tmp_path: Path):
    remote = tmp_path / "remote"
    (remote / "nb").mkdir(parents = True)
    for rel, body in FILES.items():
        (remote / rel).write_text(body, encoding = "utf-8")
    _git(remote, "init", "-q", "-b", "main")
    _git(remote, "add", "-A")
    _git(remote, "commit", "-qm", "one")

    template = tmp_path / "template"
    (template / "nb").mkdir(parents = True)
    dest = tmp_path / "dest"
    (dest / "nb").mkdir(parents = True)
    lines = []
    for rel, body in FILES.items():
        (template / rel).write_text(body, encoding = "utf-8")
        (dest / rel).write_text(body, encoding = "utf-8")
        lines.append(f"{_sha256(dest / rel)}  {rel}")
    (dest / ".unsloth_sync_state").write_text("\n".join(lines) + "\n", encoding = "utf-8")
    return remote, template, dest


def _advance(remote: Path):
    """Upstream drops two notebooks and changes the third."""
    (remote / "nb" / "doomed.ipynb").unlink()
    (remote / "nb" / "edited.ipynb").unlink()
    (remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
    _git(remote, "add", "-A")
    _git(remote, "commit", "-qm", "two")


def _refresh(tmp_path: Path, remote: Path, template: Path, dest: Path, **extra):
    return subprocess.run(
        ["bash", str(SYNC)],
        capture_output = True,
        text = True,
        timeout = 300,
        env = dict(
            os.environ,
            UNSLOTH_NB_REFRESH_CHILD = "1",
            UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
            UNSLOTH_NOTEBOOKS_DIR = str(dest),
            UNSLOTH_NOTEBOOKS_REPO = str(remote),
            UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
            UNSLOTH_KEEP_COLAB_INTRO = "1",
            **extra,
        ),
    )


def _state(dest: Path) -> dict:
    path = dest / ".unsloth_sync_state"
    out = {}
    if path.is_file():
        for line in path.read_text(encoding = "utf-8").splitlines():
            parts = line.split("  ", 1)
            if len(parts) == 2:
                out[parts[1]] = parts[0]
    return out


@behavioural
def test_a_pristine_notebook_deleted_upstream_is_removed(tmp_path: Path):
    remote, template, dest = _setup(tmp_path)
    _advance(remote)
    (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr

    assert not (
        dest / "nb" / "doomed.ipynb"
    ).exists(), "the notebook upstream deleted is still on disk, so the view keeps listing it"
    assert (dest / "nb" / "edited.ipynb").read_text(
        encoding = "utf-8"
    ) == "MY OWN WORK", "a file that no longer hashes to what we wrote is the user's, edited or not"
    assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"

    state = _state(dest)
    assert "nb/doomed.ipynb" not in state
    assert state["nb/keep.ipynb"] == _sha256(dest / "nb" / "keep.ipynb")
    assert "1 removed upstream" in run.stdout, run.stdout


@behavioural
def test_the_removal_can_be_turned_off(tmp_path: Path):
    """Non-vacuity as well as the opt-out: with the switch on, the same run leaves it."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)

    run = _refresh(tmp_path, remote, template, dest, UNSLOTH_KEEP_REMOVED_NOTEBOOKS = "1")
    assert run.returncode == 0, run.stdout + run.stderr

    assert (dest / "nb" / "doomed.ipynb").exists()
    assert "0 removed upstream" in run.stdout, run.stdout


@behavioural
def test_a_case_only_rename_does_not_delete_the_file_just_published(tmp_path: Path):
    """The clone is case-sensitive while the destination may be a macOS or Windows bind
    mount, so the old path would resolve to the file the refresh has just written."""
    remote, template, dest = _setup(tmp_path)
    _git(remote, "mv", "nb/doomed.ipynb", "nb/Doomed.ipynb")
    _git(remote, "commit", "-qm", "rename case only")

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr

    assert (dest / "nb" / "Doomed.ipynb").exists()
    assert "0 removed upstream" in run.stdout, run.stdout


@behavioural
def test_nothing_is_removed_when_upstream_removed_nothing(tmp_path: Path):
    remote, template, dest = _setup(tmp_path)
    (remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
    _git(remote, "add", "-A")
    _git(remote, "commit", "-qm", "two")

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr

    for rel in FILES:
        assert (dest / rel).exists(), rel
    assert "0 removed upstream" in run.stdout, run.stdout


def _refuse_rm(tmp_path: Path, target: Path) -> Path:
    """Stubs rm earlier on PATH to fail for one path, as a writable single-file bind mount does with
    EBUSY; the publish already works around that case for rename."""
    bindir = tmp_path / "bin"
    bindir.mkdir(exist_ok = True)
    stub = bindir / "rm"
    stub.write_text(
        "#!/bin/sh\n"
        'for a in "$@"; do\n'
        f'  [ "$a" = "{target}" ] && exit 1\n'
        "done\n"
        'exec /bin/rm "$@"\n',
        encoding = "utf-8",
    )
    stub.chmod(0o755)
    return bindir


@behavioural
def test_a_removal_that_cannot_be_unlinked_keeps_its_record_and_retries(tmp_path: Path):
    """A removal that fails must keep its record and retry: dropping it leaves the stale copy read
    as user-owned forever, and failed stays zero so the sync marker is stamped."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)
    (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
    doomed = dest / "nb" / "doomed.ipynb"
    bindir = _refuse_rm(tmp_path, doomed)

    run = _refresh(
        tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
    )
    assert run.returncode == 0, run.stdout + run.stderr

    assert doomed.exists(), "precondition: the stub refused the unlink"
    assert _state(dest).get("nb/doomed.ipynb") == _sha256(
        doomed
    ), "the file stayed but its record was dropped, so it is now unmanaged"
    assert "0 removed upstream" in run.stdout, run.stdout
    assert not (
        dest / ".unsloth_sync_commit"
    ).is_file(), "the commit was stamped over a failure, so the next start exits before retrying"

    run2 = _refresh(tmp_path, remote, template, dest)
    assert run2.returncode == 0, run2.stdout + run2.stderr
    assert not doomed.exists()
    assert "nb/doomed.ipynb" not in _state(dest)
    assert "1 removed upstream" in run2.stdout, run2.stdout


@behavioural
def test_the_successful_removal_still_stamps_the_commit(tmp_path: Path):
    """Non-vacuity for the assertion above: without the stub the same run records it,
    so the marker check is testing the failure and not the environment."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)
    (dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr

    assert (dest / ".unsloth_sync_commit").is_file()
    assert "1 removed upstream" in run.stdout, run.stdout


def _refuse_mv_to(tmp_path: Path, target: Path) -> Path:
    """Stubs mv earlier on PATH to fail for one destination, as a full or read-only /workspace does
    when the state file is published; other moves pass through."""
    bindir = tmp_path / "bin"
    bindir.mkdir(exist_ok = True)
    stub = bindir / "mv"
    stub.write_text(
        "#!/bin/sh\n"
        'for a in "$@"; do\n'
        f'  [ "$a" = "{target}" ] && exit 1\n'
        "done\n"
        'exec /bin/mv "$@"\n',
        encoding = "utf-8",
    )
    stub.chmod(0o755)
    return bindir


@behavioural
def test_a_state_that_cannot_be_published_holds_the_sync_marker(tmp_path: Path):
    """Stamping the commit after a failed state publish wedges the tree, as stale hashes read every
    notebook as user-edited; the state failure must hold the marker like failed does."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)
    before = _state(dest)
    bindir = _refuse_mv_to(tmp_path, dest / ".unsloth_sync_state")

    run = _refresh(
        tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
    )
    assert run.returncode == 0, run.stdout + run.stderr

    assert _state(dest) == before, "precondition: the stub refused the state publish"
    assert not (
        dest / ".unsloth_sync_commit"
    ).is_file(), "the commit was stamped over an unpublished state, so the tree is wedged"


@behavioural
def test_the_state_temp_file_is_published_by_a_same_directory_rename(tmp_path: Path):
    """The state temp file must sit beside the state file so publishing it is an atomic rename;
    notebooks publish first, so a standalone state publish failure leaves disk ahead of state."""
    source = SYNC.read_text(encoding = "utf-8")
    assert 'TMPSTATE="$STATE.tmp"' in source, (
        "the refresh state temp file left $DEST, so publishing it is a cross-device "
        "copy that can fail after the notebooks have already landed"
    )
    stray = [
        line.strip()
        for line in source.splitlines()
        if "mktemp" in line and "TMPSTATE=" in line and "||" not in line
    ]
    assert not stray, f"the refresh state must not be staged outside $DEST: {stray}"


@behavioural
def test_a_published_state_still_stamps_the_commit(tmp_path: Path):
    """Non-vacuity for the assertion above: the identical run without the stub records
    the marker, so that check is testing the failure and not the environment."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr
    assert (dest / ".unsloth_sync_commit").is_file()


@behavioural
def test_an_unwritable_dest_publishes_nothing_and_recovers(tmp_path: Path):
    """With DEST unwritable but its notebook subdirs writable (the container shape), staging in /tmp
    would publish bytes it cannot record; the refresh must bail before publishing."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)
    before_state = _state(dest)
    before_bytes = (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8")

    (dest / "nb").chmod(0o755)
    dest.chmod(0o555)  # root writable by nobody; the subdir still is
    try:
        run = _refresh(tmp_path, remote, template, dest)
        assert run.returncode == 0, run.stdout + run.stderr

        assert (dest / "nb" / "keep.ipynb").read_text(
            encoding = "utf-8"
        ) == before_bytes, "notebooks were published with no way to record them"
        assert _state(dest) == before_state
        assert not (
            dest / ".unsloth_sync_commit"
        ).is_file(), "the marker was stamped over a refresh that could not record itself"
    finally:
        dest.chmod(0o755)

    run2 = _refresh(tmp_path, remote, template, dest)
    assert run2.returncode == 0, run2.stdout + run2.stderr
    assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"
    assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
    assert (dest / ".unsloth_sync_commit").is_file()


@behavioural
def test_a_stale_state_temp_file_does_not_block_the_refresh_forever(tmp_path: Path):
    """A stale $STATE.tmp left by a run under another uid must not block the refresh forever;
    unlinking it needs write on DEST, which the real bail case lacks, so the guard holds."""
    remote, template, dest = _setup(tmp_path)
    _advance(remote)

    stale = dest / ".unsloth_sync_state.tmp"
    stale.write_text("LEFTOVER FROM A KILLED RUN\n", encoding = "utf-8")
    stale.chmod(0o444)  # cannot be truncated by this uid; can still be unlinked
    assert not os.access(stale, os.W_OK), "precondition: the leftover is not truncatable"

    run = _refresh(tmp_path, remote, template, dest)
    assert run.returncode == 0, run.stdout + run.stderr

    assert (dest / "nb" / "keep.ipynb").read_text(
        encoding = "utf-8"
    ) == "keep-v2", "a stale temp file the uid cannot truncate blocked the refresh"
    assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
    assert (dest / ".unsloth_sync_commit").is_file()