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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Setup skips the OXC validator `npm ci` only when node_modules exactly matches the last stamped install."""
from __future__ import annotations
import sys
import functools
import json
import os
import re
import shutil
import subprocess
from pathlib import Path
import pytest
from unsloth_pwsh_runner import run_pwsh
REPO_ROOT = Path(__file__).resolve().parents[2]
OXC_DIR = REPO_ROOT / "studio" / "backend" / "core" / "data_recipe" / "oxc-validator"
HELPER = OXC_DIR / "install-stamp.mjs"
SETUP_SH = REPO_ROOT / "studio" / "setup.sh"
SETUP_PS1 = REPO_ROOT / "studio" / "setup.ps1"
NODE = shutil.which("node")
BASH = shutil.which("bash")
PWSH = shutil.which("pwsh") or shutil.which("powershell")
STAMP = Path("node_modules") / ".unsloth-install-stamp.json"
needs_node = pytest.mark.skipif(NODE is None, reason = "needs node")
@functools.cache
def _host() -> tuple[str, str, str]:
out = subprocess.run(
[
NODE,
"-e",
"process.report.excludeNetwork = true; const r = process.report.getReport().header;"
"console.log(process.platform, process.arch,"
" process.platform !== 'linux' ? '' : r.glibcVersionRuntime ? 'glibc' : 'musl')",
],
capture_output = True,
text = True,
check = True,
).stdout.split()
return out[0], out[1], out[2] if len(out) > 2 else ""
def _installs_here(entry: dict) -> bool:
plat, arch, libc = _host()
def allows(value, wanted):
if not wanted:
return True
if f"!{value}" in wanted:
return False
plain = [w for w in wanted if not w.startswith("!")]
return not plain or value in plain
return (
allows(plat, entry.get("os"))
and allows(arch, entry.get("cpu"))
and (not entry.get("libc") or allows(libc, entry.get("libc")))
)
def _template(root: Path) -> Path:
"""What `npm ci` leaves for the committed lockfile, minus the real binaries."""
lock = json.loads((OXC_DIR / "package-lock.json").read_text(encoding = "utf-8"))
wanted = {
key: entry
for key, entry in lock["packages"].items()
if key.startswith("node_modules/") and _installs_here(entry)
}
modules = root / "node_modules"
for key, entry in wanted.items():
pkg = root / key
pkg.mkdir(parents = True)
name = key[len("node_modules/") :]
(pkg / "package.json").write_text(
json.dumps({"name": name, "version": entry["version"]}), encoding = "utf-8"
)
(pkg / "binding.node").write_bytes(name.encode() * 64)
(modules / "oxlint" / "AGENTS.md").write_text("pruned by setup\n", encoding = "utf-8")
(modules / ".package-lock.json").write_text(
json.dumps({"name": lock["name"], "lockfileVersion": 3, "packages": wanted}),
encoding = "utf-8",
)
return modules
def _oxc(tmp_path: Path) -> Path:
oxc = tmp_path / "studio" / "backend" / "core" / "data_recipe" / "oxc-validator"
oxc.mkdir(parents = True)
for name in ("package.json", "package-lock.json", "install-stamp.mjs"):
if (OXC_DIR / name).exists():
shutil.copy2(OXC_DIR / name, oxc / name)
return oxc
def _snapshot(root: Path) -> dict:
return {
str(p.relative_to(root)): p.read_bytes() if p.is_file() else None
for p in sorted(root.rglob("*"))
}
def _helper(
oxc: Path,
mode: str,
env: dict | None = None,
) -> int:
return subprocess.run(
[NODE, str(oxc / "install-stamp.mjs"), mode],
cwd = str(oxc.parent),
env = env,
capture_output = True,
).returncode
@needs_node
def test_helper_writes_and_confirms_an_unchanged_tree(tmp_path):
oxc = _oxc(tmp_path)
assert _helper(oxc, "check") == 1
_template(oxc)
assert _helper(oxc, "check") == 1
assert _helper(oxc, "write") == 0
before = _snapshot(oxc)
assert _helper(oxc, "check") == 0
assert _helper(oxc, "check") == 0
assert _snapshot(oxc) == before
# Setup prunes agent files after install; still the same tree.
(oxc / "node_modules" / "oxlint" / "AGENTS.md").unlink()
assert _helper(oxc, "check") == 0
def _tamper_byte(oxc):
p = oxc / "node_modules" / "oxlint" / "binding.node"
data = bytearray(p.read_bytes())
data[3] ^= 1
p.write_bytes(bytes(data))
def _stamp_field(field, value):
def edit(oxc):
p = oxc / STAMP
doc = json.loads(p.read_text(encoding = "utf-8"))
doc[field] = value
p.write_text(json.dumps(doc), encoding = "utf-8")
return edit
TAMPERS = {
"binary byte flipped": _tamper_byte,
"binary deleted": lambda oxc: (oxc / "node_modules" / "oxlint" / "binding.node").unlink(),
"package dir deleted": lambda oxc: shutil.rmtree(oxc / "node_modules" / "oxc-parser"),
"extra file": lambda oxc: (oxc / "node_modules" / "oxlint" / "extra.js").write_text("x"),
"hidden lockfile deleted": lambda oxc: (oxc / "node_modules" / ".package-lock.json").unlink(),
"hidden lockfile edited": lambda oxc: (oxc / "node_modules" / ".package-lock.json").write_text(
(oxc / "node_modules" / ".package-lock.json").read_text() + " "
),
"lockfile changed": lambda oxc: (oxc / "package-lock.json").write_text(
(oxc / "package-lock.json").read_text() + "\n"
),
"package.json changed": lambda oxc: (oxc / "package.json").write_text(
(oxc / "package.json").read_text() + "\n"
),
"stamp truncated": lambda oxc: (oxc / STAMP).write_text('{"version": 1, "node"'),
"stamp empty": lambda oxc: (oxc / STAMP).write_text(""),
"stamp deleted": lambda oxc: (oxc / STAMP).unlink(),
"stamp from another Node": _stamp_field("node", "v20.19.0"),
"stamp from another arch": _stamp_field("arch", "ia32"),
"stamp from a future format": _stamp_field("version", 2),
"user npmrc changed": lambda oxc: (oxc.parent / "home" / ".npmrc").write_text(
"omit=optional\n"
),
"project npmrc added": lambda oxc: (oxc / ".npmrc").write_text("omit=optional\n"),
}
@needs_node
@pytest.mark.parametrize("name", sorted(TAMPERS))
def test_helper_fails_open_on_any_doubt(tmp_path, name):
oxc = _oxc(tmp_path)
home = oxc.parent / "home"
home.mkdir()
env = {**os.environ, "HOME": str(home), "USERPROFILE": str(home)}
env = {k: v for k, v in env.items() if not k.lower().startswith("npm_config_")}
_template(oxc)
assert _helper(oxc, "write", env) == 0
assert _helper(oxc, "check", env) == 0
TAMPERS[name](oxc)
assert _helper(oxc, "check", env) == 1
@needs_node
@pytest.mark.skipif(sys.platform == "win32", reason = "no POSIX exec bits")
def test_helper_fails_open_when_an_exec_bit_is_lost(tmp_path):
oxc = _oxc(tmp_path)
_template(oxc)
binary = oxc / "node_modules" / "oxlint" / "binding.node"
binary.chmod(0o755)
assert _helper(oxc, "write") == 0
assert _helper(oxc, "check") == 0
binary.chmod(0o644)
assert _helper(oxc, "check") == 1
@needs_node
def test_helper_refuses_a_tree_missing_this_platforms_native_binding(tmp_path):
oxc = _oxc(tmp_path)
modules = _template(oxc)
hidden = json.loads((modules / ".package-lock.json").read_text(encoding = "utf-8"))
bindings = [k for k, e in hidden["packages"].items() if e.get("optional")]
assert bindings, "host has no native binding in the lockfile"
del hidden["packages"][bindings[0]]
shutil.rmtree(oxc / bindings[0])
(modules / ".package-lock.json").write_text(json.dumps(hidden), encoding = "utf-8")
assert _helper(oxc, "write") == 1
assert not (oxc / STAMP).exists()
@needs_node
def test_stamp_never_stores_npm_config_values(tmp_path):
oxc = _oxc(tmp_path)
_template(oxc)
secret = "http://user:[email protected]:8080"
assert _helper(oxc, "write", {**os.environ, "npm_config_https_proxy": secret}) == 0
assert "hunter2" not in (oxc / STAMP).read_text(encoding = "utf-8")
@needs_node
def test_helper_fails_open_when_npm_settings_could_change_the_tree(tmp_path):
oxc = _oxc(tmp_path)
env = {k: v for k, v in os.environ.items() if not k.lower().startswith("npm_config_")}
_template(oxc)
assert _helper(oxc, "write", env) == 0
assert _helper(oxc, "check", {**env, "npm_config_registry": "https://mirror.invalid/"}) == 0
assert _helper(oxc, "check", {**env, "NPM_CONFIG_PREFIX": str(tmp_path)}) == 0
assert _helper(oxc, "check", {**env, "npm_config_omit": "optional"}) == 1
assert _helper(oxc, "check", {**env, "NPM_CONFIG_CPU": "arm64"}) == 1
globalrc = tmp_path / "globalrc"
genv = {**env, "npm_config_globalconfig": str(globalrc)}
assert _helper(oxc, "write", genv) == 0
assert _helper(oxc, "check", genv) == 0
globalrc.write_text("omit=optional\n", encoding = "utf-8")
assert _helper(oxc, "check", genv) == 1
@needs_node
def test_helper_refuses_to_stamp_an_incomplete_tree(tmp_path):
oxc = _oxc(tmp_path)
_template(oxc)
shutil.rmtree(oxc / "node_modules" / "oxlint")
assert _helper(oxc, "write") == 1
assert not (oxc / STAMP).exists()
assert _helper(oxc, "check") == 1
@needs_node
def test_the_tree_check_covers_the_real_lockfile_dependencies():
declared = json.loads((OXC_DIR / "package.json").read_text(encoding = "utf-8"))["dependencies"]
assert {"oxlint", "oxc-parser"} <= set(declared)
lock = json.loads((OXC_DIR / "package-lock.json").read_text(encoding = "utf-8"))
# No install scripts: the tree npm ci builds is fixed by the lockfile and the platform alone.
assert not [k for k, v in lock["packages"].items() if v.get("hasInstallScript")]
def _bash_block() -> str:
text = SETUP_SH.read_text(encoding = "utf-8")
m = re.search(r"^_install_oxc_runtime\(\) \{\n.*?^\}\n", text, re.M | re.S)
assert m, "no _install_oxc_runtime in setup.sh"
return m.group(0)
def _ps1_block() -> str:
lines = SETUP_PS1.read_text(encoding = "utf-8").splitlines()
parts = []
if "function Invoke-OxcInstallStamp {" in lines:
start = lines.index("function Invoke-OxcInstallStamp {")
end = next(i for i in range(start, len(lines)) if lines[i] == "}")
parts.append("\n".join(lines[start : end + 1]))
start = next(
i
for i, line in enumerate(lines)
if line.startswith("if ((Test-Path $OxcValidatorDir) -and $NodeSource -ne")
)
end = next(
i for i in range(start, len(lines)) if lines[i].startswith("Remove-AgentInstructionFiles")
)
parts.append("\n".join(lines[start:end]))
return "\n".join(parts)
def _fake_npm(bindir: Path, template: Path, calls: Path, fail_file: Path) -> None:
"""npm stub: like `npm ci`, wipe node_modules and lay the locked tree down; or fail half way."""
bindir.mkdir()
npm = bindir / "npm"
npm.write_text(
f"#!{BASH}\n"
f'echo "$1" >> "{calls}"\n'
"rm -rf node_modules\n"
f'if [ -f "{fail_file}" ]; then mkdir -p node_modules/oxlint; exit 1; fi\n'
f'cp -R "{template}" node_modules\n',
encoding = "utf-8",
)
npm.chmod(0o755)
(bindir / "node").symlink_to(NODE)
def _run_block(shell: str, tmp_path: Path, oxc: Path, bindir: Path) -> subprocess.CompletedProcess:
env = {"PATH": f"{bindir}{os.pathsep}/usr/bin{os.pathsep}/bin", "HOME": str(tmp_path / "home")}
if shell == "bash":
script = "\n".join(
[
"set -euo pipefail",
'verbose_substep() { echo "verbose: $1"; }',
'substep() { echo "substep: $1"; }',
'run_quiet_no_exit() { local label=$1; shift; "$@"; }',
"_npm_mirror_retry() { return 1; }",
"_suggest_npm_registry() { :; }",
'setup_fail() { echo "FAILED: $2"; exit "$1"; }',
f'SCRIPT_DIR="{oxc.parents[3]}"',
f'_OXC_DIR="{oxc}"',
"NODE_SOURCE=bundled",
"_NPM_REGISTRY_ARGS=()",
_bash_block(),
"_install_oxc_runtime",
'echo "done in $PWD"',
]
)
return subprocess.run([BASH, "-c", script], env = env, capture_output = True, text = True)
script = "\n".join(
[
"$ErrorActionPreference = 'Stop'",
'function step { param($a, $b) Write-Output "step: $a $b" }',
'function substep { param($a, $b) Write-Output "substep: $a" }',
"function Write-StudioLine { param($a) Write-Output $a }",
"function Invoke-SetupCommand { param([scriptblock]$Command) & $Command | Out-Null; return $LASTEXITCODE }",
"function Invoke-NpmMirrorRetry { return $false }",
"function Show-NpmRegistryHint { param($FailureOutput) }",
'function Exit-SetupFailure { param($m) Write-Output "FAILED: $m"; exit 1 }',
f"$OxcValidatorDir = '{oxc}'",
"$NodeSource = 'bundled'",
"$NpmRegistryArgs = @()",
f"Set-Location '{tmp_path}'",
_ps1_block(),
'"done in $((Get-Location).Path)"',
]
)
return run_pwsh(
[PWSH, "-NoProfile", "-NonInteractive", "-Command", script],
env = env,
capture_output = True,
text = True,
)
SHELLS = [
pytest.param(
"bash", marks = pytest.mark.skipif(BASH is None or os.name == "nt", reason = "needs bash")
),
pytest.param(
"pwsh",
marks = pytest.mark.skipif(
PWSH is None or BASH is None or os.name == "nt", reason = "needs pwsh"
),
),
]
@needs_node
@pytest.mark.parametrize("shell", SHELLS)
def test_setup_runs_npm_ci_once_then_skips_until_the_tree_changes(tmp_path, shell):
oxc = _oxc(tmp_path)
(tmp_path / "home").mkdir()
template = _template(tmp_path / "template")
calls = tmp_path / "npm_calls"
fail = tmp_path / "npm_fails"
bindir = tmp_path / "bin"
_fake_npm(bindir, template, calls, fail)
def run():
result = _run_block(shell, tmp_path, oxc, bindir)
n = len(calls.read_text().splitlines()) if calls.exists() else 0
return result, n
result, n = run()
assert result.returncode == 0, result.stdout + result.stderr
assert n == 1
if shell == "pwsh":
assert "step: oxc runtime installed" in result.stdout
installed = _snapshot(oxc)
# The re-run (or a no-op update) leaves the same tree alone and ends where it did before.
result, n = run()
assert result.returncode == 0, result.stdout + result.stderr
assert n == 1, "setup reinstalled an unchanged OXC tree"
assert (oxc / STAMP).is_file()
assert _snapshot(oxc) == installed
assert result.stdout.strip().splitlines()[-1] == (
f"done in {oxc.parents[3]}" if shell == "bash" else f"done in {tmp_path}"
)
if shell == "pwsh":
assert "step: oxc runtime up to date" in result.stdout
# A damaged tree is reinstalled, and the next run trusts the fresh stamp again.
_tamper_byte(oxc)
result, n = run()
assert result.returncode == 0 and n == 2
assert _snapshot(oxc) == installed
result, n = run()
assert result.returncode == 0 and n == 2
# npm ci dying half way leaves no stamp, so the run after it reinstalls.
_tamper_byte(oxc)
fail.touch()
result, n = run()
assert result.returncode != 0 and n == 3
assert "FAILED: OXC validator dependency installation failed" in result.stdout
assert not (oxc / STAMP).exists()
fail.unlink()
result, n = run()
assert result.returncode == 0 and n == 4
assert _snapshot(oxc) == installed
@needs_node
@pytest.mark.parametrize("shell", SHELLS)
def test_setup_never_skips_npm_install_without_a_lockfile(tmp_path, shell):
oxc = _oxc(tmp_path)
(tmp_path / "home").mkdir()
(oxc / "package-lock.json").unlink()
template = _template(tmp_path / "template")
calls = tmp_path / "npm_calls"
bindir = tmp_path / "bin"
_fake_npm(bindir, template, calls, tmp_path / "npm_fails")
for _ in range(2):
result = _run_block(shell, tmp_path, oxc, bindir)
assert result.returncode == 0, result.stdout + result.stderr
assert calls.read_text().split() == ["install", "install"]
assert not (oxc / STAMP).exists()
@needs_node
@pytest.mark.parametrize("shell", SHELLS)
def test_setup_without_the_helper_runs_npm_ci_as_before(tmp_path, shell):
oxc = _oxc(tmp_path)
(tmp_path / "home").mkdir()
template = _template(tmp_path / "template")
calls = tmp_path / "npm_calls"
bindir = tmp_path / "bin"
_fake_npm(bindir, template, calls, tmp_path / "npm_fails")
assert _run_block(shell, tmp_path, oxc, bindir).returncode == 0
(oxc / "install-stamp.mjs").unlink(missing_ok = True)
assert _run_block(shell, tmp_path, oxc, bindir).returncode == 0
assert calls.read_text().split() == ["ci", "ci"]