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.

Studio setup: skip the OXC validator npm ci when its installed tree is unchanged (#15947)

Daniel Hand692510a7ec0
diff --git a/studio/backend/core/data_recipe/oxc-validator/install-stamp.mjs b/studio/backend/core/data_recipe/oxc-validator/install-stamp.mjs
new file mode 100644
index 00000000000..2ec95747226
--- /dev/null
+++ b/studio/backend/core/data_recipe/oxc-validator/install-stamp.mjs
@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// `write` stamps node_modules after a successful `npm ci`; `check` exits 0 only on an exact match, so setup can skip `npm ci`.
+import { createHash } from "node:crypto";
+import {
+ lstatSync,
+ readdirSync,
+ readFileSync,
+ readlinkSync,
+ renameSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(fileURLToPath(import.meta.url));
+const MODULES = join(ROOT, "node_modules");
+const STAMP_NAME = ".unsloth-install-stamp.json";
+const STAMP = join(MODULES, STAMP_NAME);
+// Setup deletes these from node_modules after every install.
+const PRUNED = new Set(["AGENTS.md", "CLAUDE.md"]);
+// npm settings that only pick where packages come from or how npm talks; they never change the tree.
+const NEUTRAL_CONFIG = /(registry|^prefix|^cache|^loglevel|^fund|^audit|^progress|^update_notifier|^userconfig|^globalconfig)$/;
+
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const fileHash = (path) => sha256(readFileSync(path));
+const optionalHash = (path) => {
+ try {
+ return fileHash(path);
+ } catch {
+ return null;
+ }
+};
+
+const LIBC = (() => {
+ if (process.platform !== "linux") return "";
+ try {
+ process.report.excludeNetwork = true;
+ return process.report.getReport().header.glibcVersionRuntime ? "glibc" : "musl";
+ } catch {
+ return "unknown";
+ }
+})();
+
+// npm-install-checks checkList: none of the negated values, and one of the plain ones if any.
+function allows(value, list) {
+ if (!list) return true;
+ list = [].concat(list);
+ if (list.length === 1 && list[0] === "any") return true;
+ if (list.includes(`!${value}`)) return false;
+ const wanted = list.filter((v) => !v.startsWith("!"));
+ return !wanted.length || wanted.includes(value);
+}
+
+function inputs() {
+ const config = Object.keys(process.env)
+ .map((k) => [k.toLowerCase(), process.env[k]])
+ .filter(([k]) => k.startsWith("npm_config_"))
+ .map(([k, v]) => [k.slice("npm_config_".length).replace(/-/g, "_"), v])
+ .filter(([k]) => !NEUTRAL_CONFIG.test(k))
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+ const env = (name) => process.env[`npm_config_${name}`] || process.env[`NPM_CONFIG_${name.toUpperCase()}`];
+ const userrc = env("userconfig") || join(homedir(), ".npmrc");
+ const nodeBin = dirname(process.execPath);
+ const prefix = env("prefix") || (process.platform === "win32" ? nodeBin : dirname(nodeBin));
+ const globalrc = env("globalconfig") || join(prefix, "etc", "npmrc");
+ return {
+ version: 1,
+ node: process.version,
+ platform: process.platform,
+ arch: process.arch,
+ libc: LIBC,
+ package: fileHash(join(ROOT, "package.json")),
+ lock: fileHash(join(ROOT, "package-lock.json")),
+ config: sha256(JSON.stringify(config)),
+ npmrc: optionalHash(join(ROOT, ".npmrc")),
+ userNpmrc: optionalHash(userrc),
+ globalNpmrc: optionalHash(globalrc),
+ };
+}
+
+function treeHash() {
+ const digest = createHash("sha256");
+ const walk = (dir, rel) => {
+ for (const name of readdirSync(dir).sort()) {
+ const path = join(dir, name);
+ const relPath = rel ? `${rel}/${name}` : name;
+ if (!rel && name.startsWith(STAMP_NAME)) continue;
+ const st = lstatSync(path);
+ if (st.isSymbolicLink()) {
+ digest.update(`L\0${relPath}\0${readlinkSync(path)}\n`);
+ } else if (st.isDirectory()) {
+ digest.update(`D\0${relPath}\n`);
+ walk(path, relPath);
+ } else if (!PRUNED.has(name)) {
+ digest.update(`F\0${relPath}\0${st.size}\0${st.mode & 0o111}\0${fileHash(path)}\n`);
+ }
+ }
+ };
+ walk(MODULES, "");
+ return digest.digest("hex");
+}
+
+function packagesPresent() {
+ const lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8")).packages || {};
+ const hidden = JSON.parse(readFileSync(join(MODULES, ".package-lock.json"), "utf8")).packages || {};
+ const declared = Object.keys(JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).dependencies || {});
+ if (!declared.length || !declared.includes("oxlint") || !declared.includes("oxc-parser")) return false;
+ // npm ci exits 0 when an optional native binding fails to download; never trust that tree.
+ for (const [key, entry] of Object.entries(lock)) {
+ if (!key.startsWith("node_modules/") || hidden[key]) continue;
+ if (allows(process.platform, entry.os) && allows(process.arch, entry.cpu) && (!entry.libc || allows(LIBC, entry.libc))) return false;
+ }
+ for (const [key, entry] of Object.entries(hidden)) {
+ if (!key.startsWith("node_modules/") || !lock[key] || lock[key].version !== entry.version) return false;
+ const manifest = JSON.parse(readFileSync(join(ROOT, key, "package.json"), "utf8"));
+ if (manifest.version !== entry.version) return false;
+ }
+ return true;
+}
+
+function current() {
+ return {
+ ...inputs(),
+ hiddenLock: fileHash(join(MODULES, ".package-lock.json")),
+ tree: treeHash(),
+ };
+}
+
+function check() {
+ const recorded = JSON.parse(readFileSync(STAMP, "utf8"));
+ return JSON.stringify(recorded) === JSON.stringify(current()) && packagesPresent();
+}
+
+function write() {
+ if (!packagesPresent()) return false;
+ const tmp = `${STAMP}.${process.pid}.tmp`;
+ try {
+ writeFileSync(tmp, JSON.stringify(current()));
+ renameSync(tmp, STAMP);
+ } catch (error) {
+ rmSync(tmp, { force: true });
+ throw error;
+ }
+ return true;
+}
+
+const mode = process.argv[2];
+let ok = false;
+try {
+ if (mode === "check") ok = check();
+ else if (mode === "write") ok = write();
+} catch {
+ ok = false;
+}
+process.exitCode = ok ? 0 : 1;
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 0b6de215d02..fda949fc26e 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -3222,6 +3222,21 @@ function Invoke-NpmMirrorRetry {
return $true
}
+# install-stamp.mjs check/write; any doubt returns $false so setup runs `npm ci`.
+function Invoke-OxcInstallStamp {
+ param([Parameter(Mandatory = $true)][ValidateSet("check", "write")][string]$Mode)
+ $helper = Join-Path $OxcValidatorDir "install-stamp.mjs"
+ if (-not (Test-Path -LiteralPath $helper -PathType Leaf)) { return $false }
+ # Resolved first: a lookup failure must never read an earlier command's exit code as a pass.
+ $node = Get-Command node -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+ if (-not $node) { return $false }
+ try {
+ $global:LASTEXITCODE = 1
+ & $node.Source $helper $Mode *> $null
+ return ($LASTEXITCODE -eq 0)
+ } catch { return $false }
+}
+
function Show-NpmRegistryHint {
param([string]$FailureOutput = "")
if ($FailureOutput) {
@@ -5625,18 +5640,27 @@ if ((Test-Path $OxcValidatorDir) -and $NodeSource -ne "skip" -and (Get-Command n
$ErrorActionPreference = "Continue"
Push-Location $OxcValidatorDir
$NpmInstallVerb = if (Test-Path "package-lock.json") { "ci" } else { "install" }
- $oxcInstallExit = Invoke-SetupCommand { npm $NpmInstallVerb @NpmRegistryArgs }
- if ($oxcInstallExit -ne 0 -and (Invoke-NpmMirrorRetry)) { $oxcInstallExit = 0 }
- if ($oxcInstallExit -ne 0) {
+ if ($NpmInstallVerb -eq "ci" -and (Invoke-OxcInstallStamp -Mode check)) {
+ Pop-Location
+ $ErrorActionPreference = $prevEAP_oxc
+ step "oxc runtime" "up to date"
+ } else {
+ # Gone before npm touches the tree, so an interrupted install is never trusted.
+ Remove-Item -LiteralPath (Join-Path $OxcValidatorDir "node_modules\.unsloth-install-stamp.json") -Force -ErrorAction SilentlyContinue
+ $oxcInstallExit = Invoke-SetupCommand { npm $NpmInstallVerb @NpmRegistryArgs }
+ if ($oxcInstallExit -ne 0 -and (Invoke-NpmMirrorRetry)) { $oxcInstallExit = 0 }
+ if ($oxcInstallExit -ne 0) {
+ Pop-Location
+ $ErrorActionPreference = $prevEAP_oxc
+ Write-StudioLine "[ERROR] OXC validator npm $NpmInstallVerb failed (exit code $oxcInstallExit)" -ForegroundColor Red
+ Show-NpmRegistryHint -FailureOutput $script:SetupCommandOutput
+ Exit-SetupFailure "OXC validator dependency installation failed (exit code $oxcInstallExit)"
+ }
+ if ($NpmInstallVerb -eq "ci") { $null = Invoke-OxcInstallStamp -Mode write }
Pop-Location
$ErrorActionPreference = $prevEAP_oxc
- Write-StudioLine "[ERROR] OXC validator npm $NpmInstallVerb failed (exit code $oxcInstallExit)" -ForegroundColor Red
- Show-NpmRegistryHint -FailureOutput $script:SetupCommandOutput
- Exit-SetupFailure "OXC validator dependency installation failed (exit code $oxcInstallExit)"
+ step "oxc runtime" "installed"
}
- Pop-Location
- $ErrorActionPreference = $prevEAP_oxc
- step "oxc runtime" "installed"
} elseif ((Test-Path $OxcValidatorDir) -and $NodeSource -ne "skip") {
substep "OXC validator runtime skipped (no npm found); code validation degrades until Node is available" "Yellow"
}
diff --git a/studio/setup.sh b/studio/setup.sh
index 351c62ae838..7a56ddadada 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -1999,8 +1999,15 @@ _packaged_frontend_available() {
_install_oxc_runtime() {
# Skip when the user opted out of Node (NODE_SOURCE=skip): there is no suitable
# Node, so do not run npm install against an unsuitable/absent system Node.
-if [ -d "$_OXC_DIR" ] && [ "${NODE_SOURCE:-}" != skip ] && command -v npm &>/dev/null; then
+if [ -d "$_OXC_DIR" ] && [ "${NODE_SOURCE:-}" != skip ] && command -v npm &>/dev/null \
+ && [ -f "$_OXC_DIR/package-lock.json" ] && [ -f "$_OXC_DIR/install-stamp.mjs" ] \
+ && node "$_OXC_DIR/install-stamp.mjs" check >/dev/null 2>&1; then
+ verbose_substep "oxc validator runtime up to date"
+ cd "$SCRIPT_DIR"
+elif [ -d "$_OXC_DIR" ] && [ "${NODE_SOURCE:-}" != skip ] && command -v npm &>/dev/null; then
cd "$_OXC_DIR"
+ # Gone before npm touches the tree, so an interrupted install is never trusted.
+ rm -f "$_OXC_DIR/node_modules/.unsloth-install-stamp.json" 2>/dev/null || :
_OXC_INSTALL_LOG=$(mktemp)
_CAPTURE_LOG="$_OXC_INSTALL_LOG"
# `|| _oxc_install_rc=$?` keeps this off `set -e`'s exit path so the hint branch
@@ -2019,6 +2026,7 @@ if [ -d "$_OXC_DIR" ] && [ "${NODE_SOURCE:-}" != skip ] && command -v npm &>/dev
setup_fail "$_oxc_install_rc" "OXC validator dependency installation failed (exit code $_oxc_install_rc)"
fi
rm -f "$_OXC_INSTALL_LOG"
+ [ "$_NPM_INSTALL" != ci ] || node "$_OXC_DIR/install-stamp.mjs" write >/dev/null 2>&1 || :
cd "$SCRIPT_DIR"
elif [ -d "$_OXC_DIR" ] && [ "${NODE_SOURCE:-}" != skip ]; then
# No npm on PATH: skip rather than abort; the backend Node resolver degrades
diff --git a/tests/python/test_oxc_install_stamp.py b/tests/python/test_oxc_install_stamp.py
new file mode 100644
index 00000000000..63edece12e7
--- /dev/null
+++ b/tests/python/test_oxc_install_stamp.py
@@ -0,0 +1,460 @@
+# 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")
+
+
+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
[email protected]("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
[email protected](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
[email protected]("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
[email protected]("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
[email protected]("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"]