Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
#!/usr/bin/env python3
"""bin/ci: run, on your machine, the CI checks that your change affects.
It reads the files that differ from the merge base with origin/main (plus
anything uncommitted), picks the checks those files can break, runs them in
parallel and prints the exact command that fixes each failure. The commands
are the ones the GitHub workflows run; `bin/ci --verify-sync` fails when a
workflow stops running one of them, so the two cannot drift apart unseen.
bin/ci checks for the files you changed (default)
bin/ci --quick seconds: formatting, lockfiles, headers, lint; no builds
(use this on shared hosts; heavy checks go to CI or a VM)
bin/ci --full every check, whatever you changed
bin/ci --fix apply the safe fixers (formatters, lockfiles,
generators), then check again
bin/ci --list show the plan without running it
bin/ci --only ID,... run only these checks (ids from --list)
bin/ci --signoff after a green run, set the `local-ci` commit status
bin/ci --install-hook run bin/ci before every git push (opt-in)
Disk safety: heavy checks (cargo test/clippy/build, cross-target checks) run one
at a time, lean (no incremental, no debuginfo, sccache if installed) in a
per-run target dir that is deleted on exit (--keep-target keeps it). They are
skipped when free disk is below CUA_CI_MIN_FREE_GB (default 40), and stopped
when the target dir passes CUA_CI_MAX_TARGET_GB (default 15) or free disk drops
below CUA_CI_MIN_FREE_FLOOR_GB (default 25). Exit code 3 means a guard stopped
the run: rerun in CI.
Run `bin/ci --help` for every option. Docs: docs/contributing/CI.md.
"""
from __future__ import annotations
import argparse
import atexit
import contextlib
import concurrent.futures
import json
import os
import re
import shlex
import shutil
import signal
import subprocess
import sys
import tempfile
import threading
import time
from dataclasses import dataclass, field
from pathlib import Path
from typing import Callable, Dict, Iterable, List, Optional, Sequence, Tuple
# CUA_CI_ROOT runs this copy against another checkout (used to replay old commits).
ROOT = Path(os.environ.get("CUA_CI_ROOT") or Path(__file__).resolve().parent.parent).resolve()
HOOK_MARKER = "# bin/ci pre-push hook"
CHAINED_HOOK = "pre-push.pre-bin-ci"
STATUS_CONTEXT = "local-ci"
IS_WINDOWS = os.name == "nt"
def find_bash() -> str:
"""The bash that runs the checks' commands (they are bash). On Windows that is Git for
Windows' bash (CUA_CI_BASH overrides it): a bare `bash` there is usually System32\\bash.exe,
which is WSL and would run the checks inside a Linux distribution."""
if not IS_WINDOWS:
return "bash"
given = os.environ.get("CUA_CI_BASH")
if given:
return given
git = shutil.which("git")
if git:
# .../Git/cmd/git.exe, .../Git/bin/git.exe or .../Git/mingw64/bin/git.exe: the Git root is above it.
for root in list(Path(git).resolve().parents)[:3]:
for rel in (("bin", "bash.exe"), ("usr", "bin", "bash.exe")):
candidate = root.joinpath(*rel)
if candidate.exists():
return str(candidate)
sys.exit("bin/ci: needs Git for Windows' bash (install Git for Windows, or set CUA_CI_BASH to its bash.exe); it will not use `bash` from PATH, which may be WSL")
BASH = find_bash()
_shim_dir: Optional[str] = None
def python3_shim_dir() -> Optional[str]:
"""Windows: a directory with a `python3` for the checks (Python there is `python`, or the Store stub)."""
global _shim_dir
if not IS_WINDOWS:
return None
if _shim_dir is None:
_shim_dir = tempfile.mkdtemp(prefix="bin-ci-shim-")
exe = Path(sys.executable).as_posix()
for name in ("python3", "python"):
with open(os.path.join(_shim_dir, name), "w", newline="\n") as fh:
fh.write(f'#!/bin/sh\nexec "{exe}" "$@"\n')
atexit.register(shutil.rmtree, _shim_dir, True)
return _shim_dir
# ---------------------------------------------------------------- model
@dataclass
class Check:
id: str
title: str
cmd: str # bash, run from `cwd`
cwd: str = "."
fix: Optional[str] = None # shell command that repairs a failure
safe_fix: bool = False # bin/ci --fix may run `fix` on its own
fix_from_output: Optional[str] = None # regex: group 1 is a fix command
hint: str = "" # shown on failure when there is no fix command
tools: Tuple[str, ...] = () # executables that must exist
requires: Tuple[Tuple[str, str], ...] = () # (path that must exist, how to create it)
group: Optional[str] = None # checks in one group run one at a time
heavy: bool = False # builds something large; skipped by --quick
tier: str = "quick" # quick | build (skipped by --quick)
env: Dict[str, str] = field(default_factory=dict)
ci: Tuple[Tuple[str, str], ...] = () # (workflow, text it must contain)
advisory: bool = False # never fails the run
isolate_home: bool = False # run with an empty HOME, as on a fresh CI runner
classify: Optional[Callable[[str, int], Tuple[str, str]]] = None # (log, rc) -> (status, detail)
skip_reason: Optional[str] = None # planned but cannot run here
@dataclass
class Result:
check: Check
status: str # pass | FAIL | skip | fixed | warn
seconds: float = 0.0
log: Optional[Path] = None
detail: str = ""
# ---------------------------------------------------------------- disk guard
GUARD_EXIT = 3
GUARD_WATCH_SECS = 15.0
def env_gb(name: str, default: float) -> float:
try:
return float(os.environ[name])
except (KeyError, ValueError):
return default
def min_free_gb() -> float:
return env_gb("CUA_CI_MIN_FREE_GB", 40.0)
def floor_free_gb() -> float:
return env_gb("CUA_CI_MIN_FREE_FLOOR_GB", 25.0)
def max_target_gb() -> float:
return env_gb("CUA_CI_MAX_TARGET_GB", 15.0)
def is_heavy(c: "Check") -> bool:
"""Checks that build something large: the ones the disk guard watches."""
return c.heavy or c.tier == "build"
def disk_free_gb(path: Path) -> float:
"""Free GB on the volume holding `path` (its nearest existing parent).
CUA_CI_FAKE_FREE_GB overrides it, for tests of the guard.
"""
fake = os.environ.get("CUA_CI_FAKE_FREE_GB")
if fake:
try:
return float(fake)
except ValueError:
pass
p = Path(path)
while not p.exists() and p != p.parent:
p = p.parent
return shutil.disk_usage(p).free / 1e9
def dir_size_gb(path: Path) -> float:
if not Path(path).exists():
return 0.0
try:
out = subprocess.run(["du", "-sk", str(path)], capture_output=True, text=True)
return int(out.stdout.split()[0]) * 1024 / 1e9
except (IndexError, ValueError, OSError):
total = 0
for dp, _, files in os.walk(path):
for f in files:
try:
total += os.lstat(os.path.join(dp, f)).st_size
except OSError:
pass
return total / 1e9
def preflight_reason(free_gb: float, min_free: float) -> Optional[str]:
"""Why heavy checks must not start, or None."""
if free_gb < min_free:
return f"skipped: low disk ({free_gb:.0f} GB free, need {min_free:.0f} GB); CI will run these"
return None
def watch_reason(free_gb: float, target_gb: float, floor: float, cap: float) -> Optional[str]:
"""Why a running heavy check must be stopped, or None."""
if target_gb > cap:
return f"target dir is {target_gb:.1f} GB, over the {cap:.0f} GB cap (CUA_CI_MAX_TARGET_GB)"
if free_gb < floor:
return f"free disk is {free_gb:.0f} GB, under the {floor:.0f} GB floor (CUA_CI_MIN_FREE_FLOOR_GB)"
return None
class DiskGuard:
"""Watches the target dir and free disk while cargo runs; stops it when over budget."""
def __init__(self, target: Path, interval: Optional[float] = None) -> None:
self.target = Path(target)
self.interval = interval if interval is not None else env_gb("CUA_CI_WATCH_SECS", GUARD_WATCH_SECS)
self.tripped: Optional[str] = None
self.procs: Dict[int, subprocess.Popen] = {}
self.lock = threading.Lock()
self.stop = threading.Event()
self.thread = threading.Thread(target=self._loop, daemon=True)
def start(self) -> None:
self.thread.start()
def close(self) -> None:
self.stop.set()
def register(self, proc: subprocess.Popen) -> None:
with self.lock:
self.procs[proc.pid] = proc
def unregister(self, proc: subprocess.Popen) -> None:
with self.lock:
self.procs.pop(proc.pid, None)
def check_once(self) -> Optional[str]:
reason = watch_reason(disk_free_gb(self.target), dir_size_gb(self.target), floor_free_gb(), max_target_gb())
if reason and not self.tripped:
self.tripped = reason
self.kill_all()
return reason
def kill_all(self) -> None:
with self.lock:
procs = list(self.procs.values())
if IS_WINDOWS:
for p in procs:
subprocess.run(["taskkill", "/T", "/F", "/PID", str(p.pid)], capture_output=True)
return
for sig in (signal.SIGTERM, signal.SIGKILL):
for p in procs:
try:
os.killpg(p.pid, sig)
except (ProcessLookupError, PermissionError):
pass
if sig == signal.SIGTERM:
deadline = time.monotonic() + 5
while time.monotonic() < deadline and any(p.poll() is None for p in procs):
time.sleep(0.1)
def _loop(self) -> None:
while not self.stop.wait(self.interval):
if self.check_once():
return
def lean_env() -> Dict[str, str]:
"""Defaults that keep cargo's disk use small; anything already in the environment wins."""
env = {"CARGO_INCREMENTAL": "0", "CARGO_PROFILE_DEV_DEBUG": "0", "CARGO_PROFILE_TEST_DEBUG": "0"}
if have("sccache"):
env["RUSTC_WRAPPER"] = "sccache"
return {k: v for k, v in env.items() if k not in os.environ}
def run_target_dir(keep: bool) -> Tuple[Path, bool]:
"""(target dir, delete it on exit). A CARGO_TARGET_DIR you set is never deleted."""
if os.environ.get("CARGO_TARGET_DIR"):
return Path(os.environ["CARGO_TARGET_DIR"]).resolve(), False
if keep:
return ROOT / ".bin-ci-target", False
return ROOT / f".bin-ci-target-{os.getpid()}", True
def sweep_stale_targets() -> None:
"""Delete per-run target dirs left by runs that were killed."""
for d in ROOT.glob(".bin-ci-target-*"):
m = re.fullmatch(r"\.bin-ci-target-(\d+)", d.name)
if not m:
continue
try:
os.kill(int(m.group(1)), 0)
except ProcessLookupError:
shutil.rmtree(d, ignore_errors=True)
except PermissionError:
pass
def per_crate(template: str, names: Sequence[str], tail: str = "") -> str:
"""One cargo invocation per crate (smaller builds), failing if any failed.
template has a `{p}` placeholder, e.g. "cargo clippy --locked {p} --all-targets".
"""
if len(names) <= 1:
return template.format(p=" ".join(f"-p {n}" for n in names)) + tail
steps = "; ".join(f"{template.format(p='-p ' + n)}{tail} || rc=1" for n in names)
return f"rc=0; {steps}; exit $rc"
# ---------------------------------------------------------------- shell helpers
def sh(cmd: Sequence[str], cwd: Optional[Path] = None, check: bool = False) -> str:
out = subprocess.run(list(cmd), cwd=str(cwd or ROOT), capture_output=True, text=True)
if check and out.returncode != 0:
raise RuntimeError(f"{' '.join(cmd)}: {out.stderr.strip()}")
return out.stdout
def git(*args: str) -> str:
return sh(["git", *args])
def have(tool: str) -> bool:
return shutil.which(tool) is not None
def color(text: str, code: str) -> str:
if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
return text
return f"\033[{code}m{text}\033[0m"
# ---------------------------------------------------------------- toolchains
def pinned_rust_channel() -> Optional[str]:
"""The toolchain CI pins (dtolnay/[email protected] and rust-toolchain.toml)."""
for p in (ROOT / "libs/cua/rust-toolchain.toml", ROOT / "libs/cua-driver/rust/rust-toolchain.toml"):
if p.exists():
m = re.search(r'^channel\s*=\s*"([^"]+)"', p.read_text(), re.M)
if m:
return m.group(1)
return None
def rust_env(notes: List[str]) -> Dict[str, str]:
"""PATH and RUSTUP_TOOLCHAIN so `cargo` is the pinned rustup toolchain.
A Homebrew `cargo` ahead of the rustup proxies ignores rust-toolchain.toml,
and a newer rustfmt or clippy reports different findings than CI does.
"""
env: Dict[str, str] = {}
channel = pinned_rust_channel()
rustup = shutil.which("rustup")
if not rustup or not channel:
if have("cargo"):
notes.append("rustup not found: using the cargo on PATH; rustfmt and clippy may differ from CI")
return env
installed = sh([rustup, "toolchain", "list"])
if not any(line.startswith(channel) for line in installed.splitlines()):
notes.append(
f"Rust {channel} (the CI toolchain) is not installed; using the default toolchain. "
f"Install it: rustup toolchain install {channel} --component clippy,rustfmt"
)
return env
env["RUSTUP_TOOLCHAIN"] = channel
proxy_dirs = [Path(rustup).resolve().parent, Path(rustup).parent]
brew = Path(rustup).resolve().parent.parent / "bin" # Homebrew keeps the proxies next to rustup
for d in (Path("/opt/homebrew/opt/rustup/bin"), Path("/usr/local/opt/rustup/bin"), Path.home() / ".cargo/bin", brew, *proxy_dirs):
if (d / "cargo").exists() and (d / "cargo-clippy").exists():
current = shutil.which("cargo")
if current is None or Path(current).parent != d:
env["PATH"] = f"{d}{os.pathsep}{os.environ.get('PATH', '')}"
break
return env
def pnpm_cmd(version: Optional[str]) -> str:
"""pnpm at the version a package pins (CI's pnpm/action-setup reads packageManager)."""
if not version:
return "pnpm"
# Ask from outside the repo: pnpm reports the root packageManager version
# inside it, whatever version actually runs.
local = sh(["pnpm", "--version"], cwd=Path(tempfile.gettempdir())).strip() if have("pnpm") else ""
if local.split(".")[0] == version.split(".")[0]:
return "pnpm"
return f"npx -y pnpm@{version}"
def package_manager(pkg_dir: Path) -> Optional[str]:
p = pkg_dir / "package.json"
if not p.exists():
return None
m = re.match(r"pnpm@([0-9.]+)", json.loads(p.read_text()).get("packageManager", ""))
return m.group(1) if m else None
# ---------------------------------------------------------------- change set
@dataclass
class Changes:
base: str
base_desc: str
files: List[str] # every changed path, deleted ones included
full: bool = False
def touches(self, pattern: str) -> List[str]:
if self.full:
return ["(full run)"]
rx = re.compile(pattern)
return [f for f in self.files if rx.search(f)]
def existing(self, pattern: str, suffixes: Iterable[str] = ()) -> List[str]:
rx = re.compile(pattern)
suf = tuple(suffixes)
return [f for f in self.files if rx.search(f) and (ROOT / f).is_file() and (not suf or f.endswith(suf))]
def find_base(explicit: Optional[str]) -> Tuple[str, str]:
if explicit:
sha = git("rev-parse", "--verify", f"{explicit}^{{commit}}").strip()
if not sha:
sys.exit(f"bin/ci: cannot resolve --base {explicit}")
return sha, explicit
for ref in ("origin/main", "main"):
if git("rev-parse", "-q", "--verify", ref).strip():
mb = git("merge-base", "HEAD", ref).strip()
if mb:
return mb, f"merge base with {ref}"
sys.exit("bin/ci: cannot find origin/main; run `git fetch origin main` or pass --base REF")
def changed_files(base: str) -> List[str]:
out = set()
for args in (("diff", "--name-only", f"{base}...HEAD"), ("diff", "--name-only", "HEAD"), ("ls-files", "--others", "--exclude-standard")):
out.update(line for line in git(*args).splitlines() if line)
return sorted(out)
# ---------------------------------------------------------------- Rust workspaces
# The Windows CI lane of each workspace, read from its workflow so the
# cross-compiled local run checks exactly the packages CI does:
# workspace -> (workflow, regex whose group 1 is the cargo arguments, local cargo subcommand)
WINDOWS_LANES = {
"libs/cua": ("ci-cua-sdk.yml", r"- name: Clippy \(native\)\s+run: >\s+cargo clippy (--locked .*? -- -D warnings)", "clippy"),
"libs/cua-spacesd": ("ci-cua-spacesd.yml", r"- name: Clippy\s+run: cargo clippy (--workspace --all-targets --locked -- -D warnings)", "clippy"),
"libs/cua-driver/rust": ("ci-rust-windows.yml", r"run: cargo test (-p cua-driver .*?--all-targets) --no-run --locked", "check"),
}
def windows_lane(root: str) -> Optional[Tuple[str, List[str]]]:
"""(cargo args, packages) of the workspace's Windows CI lane, or None."""
lane = WINDOWS_LANES.get(root)
if not lane:
return None
path = ROOT / ".github/workflows" / lane[0]
m = re.search(lane[1], path.read_text(), re.S) if path.exists() else None
if not m:
return None
args = " ".join(m.group(1).split())
return args, re.findall(r"-p (\S+)", args)
@dataclass
class Workspace:
root: str # repo-relative dir
members: Dict[str, str] # package name -> repo-relative dir
path_deps: Dict[str, List[str]] # package -> in-workspace packages it depends on
_ws_cache: Dict[str, Optional[Workspace]] = {}
_ws_lock = threading.Lock()
def package_of(path: str) -> Optional[Tuple[str, str]]:
"""(package dir, package name) of the crate that owns `path`."""
d = (ROOT / path).parent
while d != ROOT and ROOT in d.parents:
manifest = d / "Cargo.toml"
if manifest.exists():
text = manifest.read_text(errors="replace")
m = re.search(r'^\[package\][^\[]*?^name\s*=\s*"([^"]+)"', text, re.M | re.S)
if m:
return d.relative_to(ROOT).as_posix(), m.group(1)
d = d.parent
return None
def workspace_of(pkg_dir: str, env: Dict[str, str]) -> Optional[Workspace]:
out = subprocess.run(
["cargo", "locate-project", "--workspace", "--message-format", "plain"],
cwd=str(ROOT / pkg_dir), capture_output=True, text=True, env={**os.environ, **env},
)
if out.returncode != 0:
return None
root = str(Path(out.stdout.strip()).parent.relative_to(ROOT))
with _ws_lock:
if root in _ws_cache:
return _ws_cache[root]
meta = subprocess.run(
["cargo", "metadata", "--no-deps", "--format-version", "1", "--offline"],
cwd=str(ROOT / root), capture_output=True, text=True, env={**os.environ, **env},
)
ws: Optional[Workspace] = None
if meta.returncode == 0:
data = json.loads(meta.stdout)
members = {p["name"]: str(Path(p["manifest_path"]).parent.relative_to(ROOT)) for p in data["packages"]}
deps = {p["name"]: sorted({d["name"] for d in p["dependencies"] if d.get("path") and d["name"] in members}) for p in data["packages"]}
ws = Workspace(root, members, deps)
with _ws_lock:
_ws_cache[root] = ws
return ws
def dependents(ws: Workspace, changed: Iterable[str]) -> List[str]:
rev: Dict[str, List[str]] = {}
for pkg, deps in ws.path_deps.items():
for d in deps:
rev.setdefault(d, []).append(pkg)
seen, todo = set(changed), list(changed)
while todo:
for r in rev.get(todo.pop(), []):
if r not in seen:
seen.add(r)
todo.append(r)
return sorted(seen - set(changed))
def deps_closure(ws: Workspace, roots: Iterable[str]) -> set:
seen, todo = set(), [r for r in roots if r in ws.members]
while todo:
p = todo.pop()
if p not in seen:
seen.add(p)
todo.extend(ws.path_deps.get(p, []))
return seen
def changed_crates(changes: Changes, env: Dict[str, str]) -> Dict[str, Tuple[Workspace, set]]:
"""workspace root -> (workspace, changed package names)."""
out: Dict[str, Tuple[Workspace, set]] = {}
for f in changes.files:
if not (f.endswith(".rs") or f.endswith("Cargo.toml") or "/src/" in f or "/tests/" in f or "/benches/" in f):
continue
owner = package_of(f)
if not owner:
continue
pkg_dir, name = owner
ws = workspace_of(pkg_dir, env)
if not ws or name not in ws.members:
continue
out.setdefault(ws.root, (ws, set()))[1].add(name)
return out
# ---------------------------------------------------------------- the checks
LOCKFILE_RX = r"(^|/)(Cargo\.(toml|lock)|package(-lock)?\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|uv\.lock|pyproject\.toml|rust-toolchain\.toml)$|^scripts/ci/(check-lockfiles\.sh|lockfile-drift-allowlist\.txt)$"
TSX = "node docs/node_modules/tsx/dist/cli.mjs"
# CI's pnpm/action-setup reads the root package.json packageManager for docs.
DOCS_DEPS = ("docs/node_modules/tsx/dist/cli.mjs", "{pnpm} --dir docs install --frozen-lockfile")
def docs_install() -> str:
return DOCS_DEPS[1].format(pnpm=pnpm_cmd(package_manager(ROOT)))
# Docs generators that build Rust (or need extra tools) before they can compare.
DOCS_GENERATOR_NEEDS: Dict[str, Tuple[Tuple[str, ...], Tuple[Tuple[str, str], ...], bool]] = {
# library: (tools, requires, heavy)
"cua-driver": (("cargo",), (), True),
"cua-sdk": (("cargo", "protoc"), (), True),
"cua-cli": (("cargo", "protoc"), (), True),
"cua-rust": (("cargo", "protoc", "rustup"), (), True),
"cua-proto": (("buf",), (), False),
"cua-sdk-python": (("uv",), (), False),
"cua-bench": (("uv",), (), False),
"cua-sdk-ts": ((), (("libs/cua/typescript/node_modules", "npm --prefix libs/cua/typescript ci --ignore-scripts"),), False),
"lume": (("swift",), (), True),
}
# Web packages: (dir, trigger regex, pnpm version or "npm", install, [(id, title, cmd, fix)])
WEB_PACKAGES = [
("apps/cua-spaces-web", r"^(apps/cua-spaces-web/|apps/cua-spaces/core-wasm/|libs/cua/crates/cua-spaces-app-core/)",
"11.20.0", "pnpm install --ignore-workspace --frozen-lockfile", [
("typecheck", "typecheck", "pnpm typecheck", None),
("design-lint", "design lint (drift guard)", "pnpm exec vitest run src/lib/design-lint.test.ts", None),
("test", "tests and bridge contract", "pnpm test", None),
]),
("apps/cua-spaces-desktop", r"^apps/cua-spaces-desktop/", None, "pnpm install --frozen-lockfile", [
("typecheck", "typecheck", "pnpm typecheck", None),
("test", "tests and router contract", "pnpm test", None),
]),
("apps/cua-spaces", r"^(apps/cua-spaces/(?!src-tauri/)|libs/cua/crates/cua-spaces-app-core/)", "9.0.4", "pnpm install --frozen-lockfile", [
("typecheck", "typecheck (builds the core wasm)", "pnpm typecheck", None),
("test", "vitest (app core parity)", "pnpm test", None),
]),
("libs/typescript", r"^libs/typescript/", None, "pnpm install --frozen-lockfile", [
("typecheck", "typecheck", "pnpm typecheck", None),
("format", "prettier", "pnpm format:check", "pnpm exec prettier --write ."),
]),
("libs/cua/typescript", r"^libs/cua/typescript/", "npm", "npm ci --ignore-scripts", [
("typecheck", "typecheck", "npm run typecheck", None),
]),
("libs/cua-driver/typescript", r"^libs/cua-driver/typescript/", "npm", "npm ci", [
("typecheck", "typecheck", "npm run typecheck", None),
]),
]
# Text CI must keep containing for each local check (checked by --verify-sync).
SYNC_REFS: List[Tuple[str, str, str]] = [
# (check id prefix, workflow, text)
("rust-fmt", "ci-cua-sdk.yml", "-- --check"),
("rust-clippy", "ci-cua-sdk.yml", "--all-targets --features cua-daemon/test-fixtures,cua-media-client/media-decode,cua-spaces-cli/contrib-modal -- -D warnings"),
("rust-test", "ci-cua-sdk.yml", "CUA_ENV_TEST_SANDBOX: \"1\""),
("web:apps/cua-spaces-web", "ci-cua-spaces-web.yml", "pnpm install --ignore-workspace --frozen-lockfile"),
("web:apps/cua-spaces-web", "ci-cua-spaces-web.yml", "run: pnpm typecheck"),
("web:apps/cua-spaces", "ci-cua-spaces.yml", "- run: pnpm typecheck"),
("web:libs/typescript", "ci-lint-typescript.yml", "pnpm -C libs/typescript typecheck"),
("web:libs/typescript", "ci-lint-typescript.yml", "pnpm -C libs/typescript format:check"),
# The standalone workflows for spdx, lockfiles, actionlint, larger runners, image refs, Python lint and
# rustfmt are gone: `CI: Quick` runs them through this script, with missing tools made fatal.
("quick", "ci-quick.yml", "python3 bin/ci --quick"),
("quick", "ci-quick.yml", 'CUA_CI_REQUIRE_TOOLS: "1"'),
("docs-ref", "ci-check-docs.yml", "runner.ts --changed-files-file"),
("docs-ref", "ci-check-docs.yml", "runner.ts --library ${{ matrix.library }} --check"),
]
# Checks whose standalone GitHub workflow was deleted because `CI: Quick` runs them (CUA-3558). On a
# runner (CUA_CI_REQUIRE_TOOLS=1, set by ci-quick.yml) a missing tool fails them instead of skipping
# them, so a runner image change can never turn one of these checks into a silent pass.
QUICK_COVERED_IDS = "spdx,spdx-driver,lockfiles,actionlint,larger-runners,image-refs,image-tests,python,rust-fmt,docs-image-refs"
REQUIRED_TOOL_CHECKS = set(QUICK_COVERED_IDS.split(",")) if os.environ.get("CUA_CI_REQUIRE_TOOLS") == "1" else set()
def static_checks(changes: Changes, ctx: "Context") -> List[Check]:
checks: List[Check] = []
add = checks.append
if changes.touches(r"\.(rs|py|ts|tsx|js|mjs|swift|sh)$|^scripts/spdx-headers\.py$"):
add(Check("spdx", "SPDX headers (FSL)", "python3 scripts/spdx-headers.py --fsl --check",
fix="python3 scripts/spdx-headers.py --fsl --apply", safe_fix=True))
if changes.touches(r"^libs/cua-driver/.*\.(rs|swift)$"):
add(Check("spdx-driver", "SPDX headers (Cua Driver, MIT)", "python3 scripts/spdx-headers.py --check libs/cua-driver",
fix="python3 scripts/spdx-headers.py --apply libs/cua-driver", safe_fix=True))
lock_hits = changes.touches(LOCKFILE_RX)
if lock_hits:
kinds = set()
for f in lock_hits:
if changes.full or re.search(r"(Cargo\.(toml|lock)|rust-toolchain\.toml)$", f):
kinds.add("cargo")
if changes.full or re.search(r"(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml)$", f):
kinds.update({"pnpm", "npm"})
if changes.full or re.search(r"(package-lock\.json)$", f):
kinds.add("npm")
if changes.full or re.search(r"(pyproject\.toml|uv\.lock)$", f):
kinds.add("uv")
if re.search(r"^scripts/ci/", f):
kinds.update({"cargo", "pnpm", "npm", "uv"})
# check-lockfiles.sh falls back to `npx pnpm@<version>`, so a runner without pnpm still checks.
tools = {"cargo": "cargo", "pnpm": "npx", "npm": "npm", "uv": "uv"}
add(Check("lockfiles", f"lockfiles match manifests ({', '.join(sorted(kinds))})",
"scripts/ci/check-lockfiles.sh " + " ".join(f"--kind {k}" for k in sorted(kinds)),
fix_from_output=r"^FAIL .*?; fix: (.+)$", safe_fix=True,
tools=tuple(sorted(tools[k] for k in kinds)), group="lockfiles"))
if changes.touches(r"^\.github/(workflows|actions)/|^\.github/actionlint\.yaml$"):
add(Check("actionlint", "actionlint (workflows)", "actionlint -shellcheck= -pyflakes=",
tools=("actionlint",), hint="install: brew install actionlint (CI pins v1.7.12)"))
if changes.touches(r"^\.github/(workflows/|larger-runners-allowed\.txt|scripts/check_no_larger_runners\.py)"):
add(Check("larger-runners", "no paid larger runners in workflows",
"python3 .github/scripts/check_no_larger_runners.py",
hint="use ubuntu-latest, macos-26 or windows-latest; opt-outs: .github/larger-runners-allowed.txt"))
# Repo-wide gate (no path filter in CI): every image ref comes from the catalog.
if changes.files or changes.full:
add(Check("image-refs", "image refs come from the catalog",
"python3 scripts/images/check-image-refs.py && python3 scripts/images/gen-image-constants.py --check "
"&& python3 scripts/images/record-image-sizes.py --check",
hint="reference images through the catalog (scripts/images/README.md) or allowlist them in scripts/images/image-refs-allowlist.json; stale constants: python3 scripts/images/gen-image-constants.py"))
if changes.touches(r"^(scripts/images/|libs/images/)"):
add(Check("image-tests", "image tooling unit tests", "python3 -m unittest discover -s scripts/images/tests"))
if changes.touches(r"^docs/content/|^docs/code-block-(baseline|policy)\.json$|^tests/e2e/cua-sdk/docs/"):
add(Check("docs-code-blocks", "docs code blocks have a disposition",
f'b="$(mktemp)"; git show {changes.base}:docs/code-block-baseline.json > "$b" 2>/dev/null '
f'&& args=(--baseline-base "$b") || args=(); python3 tests/e2e/cua-sdk/docs/extract.py --lint "${{args[@]}}"; rc=$?; rm -f "$b"; exit $rc',
hint='give each new fence a disposition: test="<lane>" id="<id>", skip="<reason>" or output (tests/e2e/cua-sdk/docs/README.md)',
ci=(("ci-check-docs-links.yml", "python3 tests/e2e/cua-sdk/docs/extract.py --lint"),)))
docs_img = changes.touches(r"^(docs/|skills/|README\.md$|libs/.*README\.md$|libs/cua/crates/cua-image/src/(canonical|resolve)\.rs$|scripts/images/(check-docs-image-refs|doctor_ledger)\.py$|scripts/images/docs-image-refs-baseline\.json$)")
if docs_img:
c = Check("docs-image-refs", "docs image refs have passing doctor reports",
f'set -e; l="$(mktemp -d)"; trap \'rm -rf "$l"\' EXIT; '
f'git fetch -q origin image-doctor-ledger 2>/dev/null && git archive FETCH_HEAD | tar -x -C "$l" || true; '
f'b="$l/.base.json"; args=(--ledger "$l"); git show {changes.base}:scripts/images/docs-image-refs-baseline.json > "$b" 2>/dev/null && args+=(--baseline-base "$b"); '
f'python3 scripts/images/check-docs-image-refs.py "${{args[@]}}"',
tools=("crane",), hint="install crane: brew install crane")
add(c)
# Generated reference docs: the docs runner itself says which generators a change affects.
if changes.files or changes.full:
for lib in ctx.docs_generators(changes):
tools, requires, heavy = DOCS_GENERATOR_NEEDS.get(lib, ((), (), False))
add(Check(f"docs-ref:{lib}", f"generated reference is current ({lib})",
f"{TSX} scripts/docs-generators/runner.ts --library {lib} --check",
fix=f"{TSX} scripts/docs-generators/runner.ts --library {lib} # = pnpm --dir docs docs:generate:{lib}",
safe_fix=True, tools=("node",) + tools, requires=((DOCS_DEPS[0], docs_install()),) + requires,
heavy=heavy, tier="build" if heavy else "quick",
group="cargo:libs/cua" if lib in ("cua-sdk", "cua-cli", "cua-rust") else ("cargo:libs/cua-driver/rust" if lib == "cua-driver" else None),
ci=(("ci-check-docs.yml", "runner.ts --library ${{ matrix.library }} --check"),)))
# Generated bindings and contract manifests.
if changes.touches(r"^libs/cua/(crates/cua-sdk/|crates/cua-bindgen/|VERSION$|scripts/generate-uniffi-bindings\.mjs$|scripts/uniffi-python-postprocess\.mjs$|typescript/package-lock\.json$|python/|swift/|kotlin/|typescript/src/generated/|Cargo\.lock$)"):
add(Check("sdk-bindings", "cua SDK UniFFI bindings are current (Python, Swift, Kotlin, TS)",
"node libs/cua/scripts/generate-uniffi-bindings.mjs --check",
fix="node libs/cua/scripts/generate-uniffi-bindings.mjs", safe_fix=True,
tools=("node", "cargo"), requires=(("libs/cua/typescript/node_modules", "npm --prefix libs/cua/typescript ci --ignore-scripts"),),
group="cargo:libs/cua", heavy=True, tier="build",
ci=(("ci-cua-sdk.yml", "node libs/cua/scripts/generate-uniffi-bindings.mjs --check"),)))
if ctx.crate_trigger(changes, "libs/cua", ["cua-spaces-contract", "cua-spaces"], r"^libs/cua/spaces-contract/"):
add(Check("spaces-contract", "Spaces contract manifest and control fixtures are current",
"cargo run --locked -q -p cua-spaces-contract --bin cua-spaces-contract-gen -- --check && "
"cargo run --locked -q -p cua-spaces --bin cua-spaces-control-fixtures -- --check",
cwd="libs/cua",
fix="(cd libs/cua && cargo run --locked -q -p cua-spaces-contract --bin cua-spaces-contract-gen && "
"cargo run --locked -q -p cua-spaces --bin cua-spaces-control-fixtures)",
safe_fix=True, tools=("cargo", "protoc"), group="cargo:libs/cua", tier="build",
ci=(("ci-cua-sdk.yml", "cargo run --locked -q -p cua-spaces-contract --bin cua-spaces-contract-gen -- --check"),
("ci-cua-sdk.yml", "cargo run --locked -q -p cua-spaces --bin cua-spaces-control-fixtures -- --check"))))
if ctx.crate_trigger(changes, "libs/cua-driver/rust", ["cua-driver-contract"], r"^libs/cua-driver/contract/"):
add(Check("driver-contract", "Cua Driver contract files are current",
"cargo run --locked -q -p cua-driver-contract --bin cua-contract-gen -- all --check", cwd="libs/cua-driver/rust",
fix="(cd libs/cua-driver/rust && cargo run --locked -q -p cua-driver-contract --bin cua-contract-gen -- all)",
safe_fix=True, tools=("cargo",), group="cargo:libs/cua-driver/rust", tier="build",
ci=(("ci-cua-driver-contract-clients.yml", "cargo run --locked -p cua-driver-contract --bin cua-contract-gen -- all --check"),)))
if ctx.crate_trigger(changes, "libs/cua-driver/rust", ["cua-driver-sdk", "cua-driver-bindgen"],
r"^libs/cua-driver/(scripts/generate-uniffi-bindings\.mjs$|python/src/cua_driver/_native|typescript/src/native/)"):
add(Check("driver-bindings", "Cua Driver UniFFI bindings are current (release build)",
"node scripts/generate-uniffi-bindings.mjs --check", cwd="libs/cua-driver",
fix="(cd libs/cua-driver && node scripts/generate-uniffi-bindings.mjs)", safe_fix=True,
tools=("node", "cargo"), requires=(("libs/cua-driver/typescript/node_modules", "npm --prefix libs/cua-driver/typescript ci"),),
group="cargo:libs/cua-driver/rust", heavy=True, tier="build",
ci=(("ci-cua-driver-contract-clients.yml", "node scripts/generate-uniffi-bindings.mjs --check"),)))
# The Spaces app library (cua-spaces-ffi) re-exports the SDK; only UniFFI crates change its interface.
if changes.touches(r"^libs/cua/crates/(cua-sdk|cua-spaces-ffi)/.*\.rs$|^apps/cua-spaces-desktop/src/native/generated/|^libs/spaces-app-swift/"):
desk_pnpm = pnpm_cmd(package_manager(ROOT / "apps/cua-spaces-desktop"))
add(Check("spaces-app-bindings", "Electron app bindings are current (release build of cua-spaces-ffi)",
f"{desk_pnpm} native -- --check-bindings", cwd="apps/cua-spaces-desktop",
fix=f"(cd apps/cua-spaces-desktop && {desk_pnpm} native -- --bindings)", safe_fix=True,
tools=("node", "cargo"), requires=(("apps/cua-spaces-desktop/node_modules", f"(cd apps/cua-spaces-desktop && {desk_pnpm} install --frozen-lockfile)"),),
group="cargo:libs/cua", heavy=True, tier="build",
ci=(("ci-cua-spaces-macos.yml", "pnpm native -- --skip-build --check-bindings"),)))
if sys.platform == "darwin":
add(Check("spaces-swift-bindings", "SwiftUI app binding is current (release build of cua-spaces-ffi)",
"node libs/spaces-app-swift/scripts/generate-bindings.mjs --check",
fix="node libs/spaces-app-swift/scripts/generate-bindings.mjs", safe_fix=True,
tools=("node", "cargo"), group="cargo:libs/cua", heavy=True, tier="build",
ci=(("ci-cua-spaces-macos.yml", "node libs/spaces-app-swift/scripts/generate-bindings.mjs --check --skip-build"),)))
# Self-tests for this tool and the CI helper scripts.
if changes.touches(r"^(bin/ci$|scripts/ci/|\.github/workflows/)"):
add(Check("bin-ci-tests", "bin/ci tests and workflow sync", "python3 -m unittest discover -s scripts/ci/tests -q && python3 bin/ci --verify-sync",
ci=(("ci-test-scripts.yml", "python3 -m unittest discover -s scripts/ci/tests"),)))
if changes.touches(r"^\.github/scripts/"):
add(Check("gh-scripts-tests", ".github/scripts tests",
"cd .github/scripts && uv run --no-project -q --with pytest --with cryptography --with jsonschema --with pyyaml --with toml pytest tests/ -q",
tools=("uv",), tier="build", ci=(("ci-test-scripts.yml", "pytest tests/ -v"),)))
return checks
def python_checks(changes: Changes) -> List[Check]:
# The same command and paths as CI (whole tree, seconds with the tools'
# caches): a formatter bump in uv.lock can fail files the change never touched.
if not changes.touches(r"^(libs/python/|tests/).*\.pyi?$|^(pyproject\.toml|uv\.lock)$"):
return []
paths = "libs/python tests"
return [Check("python", "Python isort, black, ruff (libs/python, tests)",
f"uv run -q isort --check-only {paths} && uv run -q black --check {paths} && uv run -q ruff check {paths}",
fix=f"uv run -q isort {paths} && uv run -q black {paths} && uv run -q ruff check --fix {paths}",
safe_fix=True, tools=("uv",), group="uv")]
def web_checks(changes: Changes) -> List[Check]:
out: List[Check] = []
for pkg, rx, pm, install, steps in WEB_PACKAGES:
if not (ROOT / pkg / "package.json").exists() or not changes.touches(rx):
continue
if pm == "npm":
runner, inst = "npm", install
else:
runner = pnpm_cmd(pm or package_manager(ROOT / pkg))
inst = install.replace("pnpm", runner, 1)
for sid, title, cmd, fix in steps:
cmd = cmd.replace("pnpm", runner, 1) if cmd.startswith("pnpm") else cmd
heavy = "core wasm" in title or "parity" in title or pkg == "apps/cua-spaces"
out.append(Check(f"web:{pkg}:{sid}", f"{pkg}: {title}", cmd, cwd=pkg,
fix=f"(cd {pkg} && {fix.replace('pnpm', runner, 1)})" if fix else None, safe_fix=bool(fix),
tools=("node",) + (("pnpm",) if runner == "pnpm" else ()),
requires=((f"{pkg}/node_modules", f"(cd {pkg} && {inst})"),),
group=f"web:{pkg}", heavy=heavy, tier="build" if sid == "test" or heavy else "quick"))
return out
UNIX_ONLY_RX = re.compile(r"std::os::unix|\bUnix(Stream|Listener|Datagram)\b|\blibc::(?!c_)|\bnix::|PermissionsExt|\.mode\(0o|std::os::fd|symlink\(")
def unix_api_scan(changes: Changes) -> List[str]:
"""Added lines that use Unix-only APIs in files with no cfg(unix) at all."""
hits = []
for f in changes.existing(r"\.rs$"):
text = (ROOT / f).read_text(errors="replace")
if re.search(r"cfg\((all\()?(unix|not\(windows\)|not\(target_os = \"windows\"\)|target_os = \"(linux|macos)\")", text):
continue
if re.search(r"(^|/)(unix|linux|macos|darwin)[^/]*\.rs$|/platform-(linux|macos)/", f):
continue
diff = git("diff", "-U0", changes.base, "--", f)
for line in diff.splitlines():
if line.startswith("+") and not line.startswith("+++") and UNIX_ONLY_RX.search(line):
hits.append(f"{f}: {line[1:].strip()[:100]}")
return hits
def classify_xwin(log: str, rc: int) -> Tuple[str, str]:
"""A C dependency that cannot be cross-built here is not a finding.
`--keep-going` checks every crate that does not need it; only rustc
errors in those crates fail the check.
"""
if rc == 0:
return "pass", ""
if re.search(r"could not compile `[^`]+`", log):
return "FAIL", ""
blocked = sorted(set(re.findall(r"failed to run custom build command for `([^`]+)`", log)))
if blocked:
return "warn", (f"could not cross-build {', '.join(blocked)} for Windows on this machine; "
"the crates that need it were not checked, every other crate passed")
return "FAIL", ""
def rust_checks(changes: Changes, ctx: "Context") -> List[Check]:
out: List[Check] = []
if not have("cargo"):
return [Check("rust", "Rust checks", "true", skip_reason="cargo not installed")] if changes.existing(r"\.rs$") else []
if changes.full:
crates = {}
for root in ("libs/cua", "libs/cua-driver/rust", "libs/cua-spacesd"):
ws = workspace_of(root, ctx.rust_env)
if ws:
crates[ws.root] = (ws, set(ws.members))
else:
crates = changed_crates(changes, ctx.rust_env)
for root, (ws, names) in sorted(crates.items()):
names = sorted(names)
plist = " ".join(f"-p {n}" for n in names)
label = f"{root}: {', '.join(names) if len(names) <= 4 else f'{len(names)} crates'}"
group = f"cargo:{root}"
out.append(Check(f"rust-fmt:{root}", f"rustfmt ({label})", f"cargo fmt {plist} -- --check", cwd=root,
fix=f"(cd {root} && cargo fmt {plist})", safe_fix=True, tools=("cargo",)))
lint = names + ([] if changes.full else dependents(ws, names))
if not changes.full and len(lint) > len(names) + 12: # a core crate: lint its direct dependents only
direct = sorted({p for p, deps in ws.path_deps.items() if set(deps) & set(names)} - set(names))
ctx.notes.append(f"{root}: {len(lint) - len(names)} crates depend on the {len(names)} you changed; linting the {len(direct)} direct ones (bin/ci --full for all)")
lint = names + direct
lflags = "--workspace" if changes.full else " ".join(f"-p {n}" for n in sorted(set(lint)))
llabel = f"{root}: {len(set(lint))} crates" if len(set(lint)) > 4 else label
clippy_cmd = (f"cargo clippy --locked {lflags} --all-targets -- -D warnings" if changes.full
else per_crate("cargo clippy --locked {p} --all-targets", sorted(set(lint)), " -- -D warnings"))
out.append(Check(f"rust-clippy:{root}", f"clippy -D warnings ({llabel})",
clippy_cmd, cwd=root,
tools=("cargo",), group=group, tier="build",
hint="fix the warnings above; `cargo clippy --fix --allow-dirty` applies the machine-applicable ones"))
lane = windows_lane(root)
if lane:
args, lane_pkgs = lane
closure = deps_closure(ws, lane_pkgs) if lane_pkgs else set(ws.members)
if changes.full or set(names) & closure:
sub = WINDOWS_LANES[root][2]
if "--locked" not in args:
args += " --locked"
if sub == "check":
cmd = f"cargo xwin check --keep-going --target x86_64-pc-windows-msvc {args}"
else:
cmd = f"cargo xwin clippy --keep-going --target x86_64-pc-windows-msvc {args}"
wf = WINDOWS_LANES[root][0]
if ctx.xwin:
out.append(Check(f"rust-windows:{root}", f"Windows {sub}, cross-compiled (the {wf} Windows lane)", cmd,
cwd=root, tools=("cargo",), group="xwin", tier="build", heavy=True, classify=classify_xwin,
hint="code that only Unix uses must be #[cfg(unix)] too (or #[cfg_attr(windows, allow(dead_code))] with a reason)"))
else:
hits = unix_api_scan(changes)
out.append(Check(f"rust-windows:{root}", "Windows cfg (grep for Unix-only APIs; cargo-xwin not installed)",
"printf '%s\\n' " + " ".join(shlex.quote(h) for h in hits) + " && exit 1" if hits else "true",
advisory=True,
hint="these lines use Unix-only APIs outside #[cfg(unix)]; for a real Windows compile: "
"cargo install cargo-xwin && rustup target add x86_64-pc-windows-msvc"))
tflags = "--workspace" if changes.full else plist
test_cmd = (f"cargo test --locked --no-fail-fast {tflags} -- --test-threads=4" if changes.full
else per_crate("cargo test --locked --no-fail-fast {p}", names, " -- --test-threads=4"))
out.append(Check(f"rust-test:{root}", f"unit tests ({label})",
test_cmd, cwd=root,
tools=("cargo",), group=group, tier="build",
env={"CUA_ENV_TEST_SANDBOX": "1", "RUST_MIN_STACK": "8388608"}, isolate_home=True))
return out
# ---------------------------------------------------------------- context and plan
class Context:
def __init__(self, args: argparse.Namespace) -> None:
self.args = args
self.notes: List[str] = []
self.rust_env = rust_env(self.notes)
self.xwin = have("cargo") and subprocess.run(
["cargo", "xwin", "--version"], capture_output=True, env={**os.environ, **self.rust_env}
).returncode == 0
self.docs_ready = (ROOT / DOCS_DEPS[0]).exists()
self.target, self.delete_target = run_target_dir(getattr(args, "keep_target", False))
self.lean = lean_env()
self.guard: Optional[DiskGuard] = None
def env(self) -> Dict[str, str]:
env = {**self.lean, **os.environ, **self.rust_env, "CARGO_TARGET_DIR": str(self.target), "CUA_TELEMETRY": "0", "DO_NOT_TRACK": "1"}
shim = python3_shim_dir()
if shim:
key = next((k for k in env if k.upper() == "PATH"), "PATH")
env[key] = shim + os.pathsep + env.get(key, "")
return env
def cleanup_target(self) -> None:
if self.guard:
self.guard.close()
if self.delete_target and self.target.exists():
shutil.rmtree(self.target, ignore_errors=True)
def ensure_docs_deps(self) -> bool:
if self.docs_ready:
return True
if self.args.no_install or not have("node"):
return False
print(f"bin/ci: installing docs dependencies ({docs_install()}) to route the docs generators ...", flush=True)
ok = subprocess.run(docs_install(), shell=True, cwd=str(ROOT), stdout=subprocess.DEVNULL, env=self.env()).returncode == 0
self.docs_ready = ok and (ROOT / DOCS_DEPS[0]).exists()
return self.docs_ready
def docs_generators(self, changes: Changes) -> List[str]:
if changes.full:
return ["cua-driver", "cua-bench", "sandbox", "cua-cli", "cua-sdk", "cua-sdk-python", "cua-sdk-ts", "cua-rust", "cua-proto", "spaces"] + (["lume"] if sys.platform == "darwin" else [])
if not self.ensure_docs_deps():
self.notes.append(f"docs generators not routed: run {docs_install()}")
return []
with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False) as fh:
fh.write("\n".join(changes.files) + "\n")
try:
out = subprocess.run([BASH, "-c", f"{TSX} scripts/docs-generators/runner.ts --changed-files-file {shlex.quote(Path(fh.name).as_posix())}"],
cwd=str(ROOT), capture_output=True, text=True, env=self.env())
finally:
os.unlink(fh.name)
if out.returncode != 0:
self.notes.append("the docs generator router failed: " + out.stderr.strip()[-200:])
return []
return out.stdout.split()
def crate_trigger(self, changes: Changes, ws_root: str, roots: List[str], path_rx: str) -> bool:
if changes.full or changes.touches(path_rx):
return True
if not have("cargo"):
return False
ws = workspace_of(ws_root, self.rust_env)
if not ws:
return False
closure = deps_closure(ws, roots)
crates = changed_crates(changes, self.rust_env)
return bool(crates.get(ws.root, (None, set()))[1] & closure)
def build_plan(changes: Changes, ctx: Context) -> List[Check]:
checks = static_checks(changes, ctx) + rust_checks(changes, ctx) + python_checks(changes) + web_checks(changes)
seen, plan = set(), []
for c in checks:
if c.id not in seen:
seen.add(c.id)
plan.append(c)
if ctx.args.only:
wanted = [w.strip() for w in ctx.args.only.split(",") if w.strip()]
plan = [c for c in plan if any(c.id == w or c.id.startswith(w + ":") or c.id.startswith(w) for w in wanted)]
for c in plan:
if c.skip_reason:
continue
if ctx.args.quick and c.tier != "quick":
c.skip_reason = "--quick"
continue
missing = [t for t in c.tools if not have(t)]
if missing and c.id.split(":")[0] in REQUIRED_TOOL_CHECKS:
continue # CI: a missing tool must fail the check, never skip it (the standalone workflow is gone)
if missing:
c.skip_reason = f"{', '.join(missing)} not installed" + (f"; {c.hint}" if c.hint and "install" in c.hint else "")
return plan
# ---------------------------------------------------------------- running
ERROR_RX = re.compile(r"(error|Diff in|would reformat|FAIL|stale|out of sync|drift|panicked|not up to date|missing|no disposition|differ|warning: unused|✗|❌)", re.I)
def excerpt(log: Path, limit: int = 14) -> List[str]:
lines = [l.rstrip() for l in log.read_text(errors="replace").splitlines() if l.strip()]
rustc = [l for l in lines if re.match(r"(error(\[E\d+\])?: (?!failed to run custom build|could not compile|build failed)|\s+--> )", l)]
if rustc:
return [l[:220] for l in rustc[:limit]]
hits = [l for l in lines if ERROR_RX.search(l) and not l.lstrip().startswith(("Compiling", "Checking", "Downloaded", "test ", "Running"))]
pick = hits[:limit] if hits else lines[-limit:]
return [l[:220] for l in pick]
class Runner:
def __init__(self, ctx: Context, logdir: Path, quiet: bool = False) -> None:
self.ctx = ctx
self.quiet = quiet
self.logdir = logdir
self.locks: Dict[str, threading.Lock] = {}
self.print_lock = threading.Lock()
self.installs: Dict[str, threading.Lock] = {}
self.heavy_lock = threading.Lock() # heavy checks run one at a time
def _lock(self, name: Optional[str], table: Dict[str, threading.Lock]) -> threading.Lock:
with self.print_lock:
return table.setdefault(name or "", threading.Lock()) if name else threading.Lock()
def _prepare(self, c: Check, log) -> Optional[str]:
for path, how in c.requires:
with self._lock(path, self.installs):
if (ROOT / path).exists():
continue
if self.ctx.args.no_install:
return f"missing {path}: run {how}"
log.write(f"$ {how}\n".encode())
log.flush()
rc = subprocess.run([BASH, "-c", how], cwd=str(ROOT), stdout=log, stderr=subprocess.STDOUT, env=self.ctx.env()).returncode
if rc != 0 or not (ROOT / path).exists():
return f"could not install {path} ({how}); see the log"
return None
def run(self, c: Check) -> Result:
if c.skip_reason:
return Result(c, "skip", detail=c.skip_reason)
logfile = self.logdir / (re.sub(r"[^A-Za-z0-9._-]+", "_", c.id) + ".log")
start = time.monotonic()
heavy = is_heavy(c)
with self._lock(c.group, self.locks), (self.heavy_lock if heavy else contextlib.nullcontext()):
with open(logfile, "wb") as log:
if heavy:
guard = self.ctx.guard
if guard and guard.tripped:
return Result(c, "skip", time.monotonic() - start, logfile, f"stopped earlier: {guard.tripped}; rerun in CI")
why = preflight_reason(disk_free_gb(self.ctx.target), min_free_gb())
if why:
return Result(c, "skip", time.monotonic() - start, logfile, why)
problem = self._prepare(c, log)
if problem:
return Result(c, "skip", time.monotonic() - start, logfile, problem)
log.write(f"$ (cd {c.cwd} && {c.cmd})\n".encode())
log.flush()
env = {**self.ctx.env(), **c.env}
home = None
if c.isolate_home:
# Tests that read the host's apps or config pass on a clean
# runner and fail here; keep the toolchains where they are.
real = Path.home()
env.setdefault("CARGO_HOME", str(real / ".cargo"))
env.setdefault("RUSTUP_HOME", str(real / ".rustup"))
home = tempfile.mkdtemp(prefix="bin-ci-home-")
env["HOME"] = home
proc = subprocess.Popen([BASH, "-o", "pipefail", "-c", c.cmd], cwd=str(ROOT / c.cwd), stdout=log, stderr=subprocess.STDOUT,
stdin=subprocess.DEVNULL, env=env, start_new_session=not IS_WINDOWS)
guard = self.ctx.guard if heavy else None
if guard:
guard.register(proc)
try:
rc = proc.wait()
finally:
if guard:
guard.unregister(proc)
if home:
shutil.rmtree(home, ignore_errors=True)
status = "pass" if rc == 0 else ("warn" if c.advisory else "FAIL")
detail = ""
if heavy and self.ctx.guard and self.ctx.guard.tripped and rc != 0:
res = Result(c, "FAIL", time.monotonic() - start, logfile, f"stopped by the disk guard: {self.ctx.guard.tripped}")
if not self.quiet:
self.report(res)
return res
if c.classify:
status, detail = c.classify(logfile.read_text(errors="replace"), rc)
res = Result(c, status, time.monotonic() - start, logfile, detail)
if not self.quiet:
self.report(res)
return res
def report(self, r: Result) -> None:
with self.print_lock:
print_result(r)
def fix_commands(r: Result) -> List[str]:
c = r.check
cmds = []
if c.fix_from_output and r.log and r.log.exists():
rx = re.compile(c.fix_from_output)
for line in r.log.read_text(errors="replace").splitlines():
m = rx.search(line.strip())
if m and m.group(1) not in cmds:
cmds.append(m.group(1))
if c.fix and not cmds:
cmds.append(c.fix)
return cmds
def fmt_secs(s: float) -> str:
return f"{s:.1f}s" if s < 60 else f"{int(s // 60)}m{int(s % 60):02d}s"
def print_result(r: Result) -> None:
tag = {"pass": color("ok ", "32"), "FAIL": color("FAIL", "31;1"), "skip": color("skip", "33"),
"fixed": color("fixed", "36"), "warn": color("warn", "33")}[r.status]
secs = fmt_secs(r.seconds) if r.seconds else ""
print(f" {tag} {r.check.title} {color(secs, '2')}".rstrip(), flush=True)
if r.status == "skip":
print(f" {r.detail}")
if r.status == "FAIL" and r.detail.startswith("stopped by the disk guard"):
print(f" {r.detail}")
print(" rerun in CI: push the branch and let CI run this check, or run it on a VM")
return
if r.status == "warn" and r.detail:
print(f" {r.detail}")
elif r.status in ("FAIL", "warn") and r.log:
for line in excerpt(r.log):
print(f" | {line}")
fixes = fix_commands(r)
for f in fixes:
print(f" {color('fix:', '1')} {f}")
if not fixes and r.check.hint:
print(f" {color('fix:', '1')} {r.check.hint}")
rel = os.path.relpath(r.log, ROOT)
print(f" log: {rel if not rel.startswith('..') else r.log}")
if r.status == "fixed":
print(f" {r.detail}")
def run_plan(plan: List[Check], ctx: Context, logdir: Path) -> List[Result]:
runner = Runner(ctx, logdir)
results: Dict[str, Result] = {}
order = sorted(plan, key=lambda c: (c.skip_reason is None, c.heavy, c.tier != "quick"))
for c in order:
if c.skip_reason:
results[c.id] = Result(c, "skip", detail=c.skip_reason)
print_result(results[c.id])
jobs = ctx.args.jobs or max(2, min(6, (os.cpu_count() or 4) // 2))
with concurrent.futures.ThreadPoolExecutor(max_workers=jobs) as pool:
futures = {pool.submit(runner.run, c): c for c in order if not c.skip_reason}
for fut in concurrent.futures.as_completed(futures):
r = fut.result()
results[r.check.id] = r
if r.status == "skip" and r.log is not None:
runner.report(r)
return [results[c.id] for c in plan]
def apply_fixes(results: List[Result], ctx: Context, logdir: Path) -> List[Result]:
out = []
for r in results:
cmds = fix_commands(r) if r.status == "FAIL" and r.check.safe_fix else []
if not cmds:
out.append(r)
continue
print(f" {color('fixing', '36')} {r.check.title}: {'; '.join(cmds)}", flush=True)
ok = all(subprocess.run([BASH, "-c", cmd], cwd=str(ROOT), env=ctx.env()).returncode == 0 for cmd in cmds)
again = Runner(ctx, logdir, quiet=True).run(r.check) if ok else r
if again.status == "pass":
again.status, again.detail = "fixed", "fixed; review and commit the changes"
print_result(again)
out.append(again)
return out
# ---------------------------------------------------------------- state, sign-off, hook
def state_dir() -> Path:
d = Path(git("rev-parse", "--absolute-git-dir").strip()) / "bin-ci"
(d / "logs").mkdir(parents=True, exist_ok=True)
return d
def worktree_clean() -> bool:
return not git("status", "--porcelain", "--untracked-files=normal").strip()
def save_state(results: List[Result], mode: str, seconds: float) -> dict:
data = {
"head": git("rev-parse", "HEAD").strip(), "clean": worktree_clean(), "mode": mode,
"seconds": round(seconds, 1),
"passed": [r.check.id for r in results if r.status in ("pass", "fixed")],
"failed": [r.check.id for r in results if r.status == "FAIL"],
"skipped": [r.check.id for r in results if r.status == "skip"],
"at": int(time.time()),
}
(state_dir() / "last-run.json").write_text(json.dumps(data, indent=2))
return data
def github_repo() -> Optional[str]:
url = git("remote", "get-url", "origin").strip()
m = re.search(r"github\.com[:/]([^/]+/[^/]+?)(\.git)?$", url)
return m.group(1) if m else None
def signoff(state: dict) -> int:
if state["failed"] or not state["passed"]:
print("bin/ci: not signing off: the run is not green")
return 1
if not state["clean"]:
print("bin/ci: not signing off: uncommitted changes; commit them and run again")
return 1
if state["skipped"]:
print(f"bin/ci: not signing off: {len(state['skipped'])} check(s) skipped ({', '.join(state['skipped'])}); install what they need")
return 1
repo = github_repo()
if not repo or not have("gh"):
print("bin/ci: not signing off: needs the gh CLI and a GitHub origin")
return 1
desc = f"bin/ci {state['mode']}: {len(state['passed'])} checks passed in {fmt_secs(state['seconds'])} ({sys.platform})"
out = subprocess.run(["gh", "api", "-X", "POST", f"repos/{repo}/statuses/{state['head']}", "-f", "state=success",
"-f", f"context={STATUS_CONTEXT}", "-f", f"description={desc[:140]}"], capture_output=True, text=True)
if out.returncode != 0:
if "No commit found" in out.stdout + out.stderr or "422" in out.stderr:
print(f"bin/ci: {state['head'][:10]} is not on GitHub yet; push, then run `bin/ci --signoff` again (it reuses this green run)")
else:
print("bin/ci: gh api failed: " + (out.stderr.strip() or out.stdout.strip())[:300])
return 1
print(f"bin/ci: set {STATUS_CONTEXT} = success on {state['head'][:10]} ({desc})")
return 0
HOOK_SCRIPT = f"""#!/bin/sh
{HOOK_MARKER} (installed by `bin/ci --install-hook`; remove: `bin/ci --uninstall-hook`).
# Runs the checks your push affects. Skip it once: CUA_SKIP_LOCAL_CI=1 git push ...
# (`git push --no-verify` also skips it, and every other pre-push hook with it.)
here=$(cd "$(dirname "$0")" && pwd)
refs=$(mktemp) || exit 1
trap 'rm -f "$refs"' EXIT
cat > "$refs"
if [ -x "$here/{CHAINED_HOOK}" ]; then
"$here/{CHAINED_HOOK}" "$@" < "$refs" || exit $?
fi
if [ "${{CUA_SKIP_LOCAL_CI:-0}}" = 1 ]; then
echo "bin/ci: skipped (CUA_SKIP_LOCAL_CI=1)" >&2
exit 0
fi
root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
[ -x "$root/bin/ci" ] || exit 0
"$root/bin/ci" --hook ${{CUA_LOCAL_CI_ARGS:-}} < "$refs"
"""
def install_hook(force: bool) -> int:
hooks = Path(git("rev-parse", "--path-format=absolute", "--git-common-dir").strip()) / "hooks"
hooks.mkdir(exist_ok=True)
hook = hooks / "pre-push"
if hook.exists() and HOOK_MARKER not in hook.read_text(errors="replace"):
chained = hooks / CHAINED_HOOK
if chained.exists() and not force:
print(f"bin/ci: {hook} exists and so does {chained}; pass --force to replace {hook}")
return 1
hook.rename(chained)
print(f"bin/ci: kept your existing pre-push hook as {chained}; it still runs first")
hook.write_text(HOOK_SCRIPT)
hook.chmod(0o755)
print(f"bin/ci: installed {hook}")
hooks_path = git("config", "--get", "core.hooksPath").strip()
if hooks_path:
dispatch = Path(os.path.expanduser(hooks_path)) / "pre-push"
chains = dispatch.exists() and "git-common-dir" in dispatch.read_text(errors="replace") + (
(dispatch.parent / "_dispatch").read_text(errors="replace") if (dispatch.parent / "_dispatch").exists() else "")
if chains:
print(f"bin/ci: core.hooksPath is {hooks_path}; its pre-push runs first and then chains to this hook")
else:
print(f"bin/ci: warning: core.hooksPath is {hooks_path}, so git will not run {hook}. "
f"Call it from {dispatch}, or run bin/ci yourself before pushing.")
return 0
def uninstall_hook() -> int:
hooks = Path(git("rev-parse", "--path-format=absolute", "--git-common-dir").strip()) / "hooks"
hook = hooks / "pre-push"
if not hook.exists() or HOOK_MARKER not in hook.read_text(errors="replace"):
print("bin/ci: no bin/ci pre-push hook installed")
return 0
hook.unlink()
chained = hooks / CHAINED_HOOK
if chained.exists():
chained.rename(hook)
print(f"bin/ci: removed the hook and restored your previous {hook}")
else:
print(f"bin/ci: removed {hook}")
return 0
def hook_refs_are_deletions(stdin_text: str) -> bool:
lines = [l.split() for l in stdin_text.splitlines() if l.strip()]
return bool(lines) and all(len(p) >= 2 and set(p[1]) == {"0"} for p in lines)
# ---------------------------------------------------------------- sync check
def all_check_refs() -> List[Tuple[str, str, str]]:
"""Every (check id, workflow, text) pair, from a full plan without running anything."""
class Dummy:
notes: List[str] = []
rust_env: Dict[str, str] = {}
def docs_generators(self, changes):
return ["cua-sdk"]
def crate_trigger(self, *a):
return True
full = Changes("HEAD", "HEAD", ["x.rs", "x.py", ".github/workflows/x.yml", "Cargo.toml", "docs/content/x.mdx", "libs/cua/crates/cua-sdk/x.rs", ".github/scripts/x.py", "libs/cua-driver/x.rs", "scripts/images/x.py", "bin/ci"], full=False)
refs = []
for c in static_checks(full, Dummy()): # type: ignore[arg-type]
refs.extend((c.id, wf, text) for wf, text in c.ci)
for c in python_checks(Changes("HEAD", "HEAD", [], full=True)):
refs.extend((c.id, wf, text) for wf, text in c.ci)
refs.extend(SYNC_REFS)
return refs
def verify_sync() -> int:
bad = 0
for root, (wf, _, _) in WINDOWS_LANES.items():
if not windows_lane(root):
bad += 1
print(f"out of sync: rust-windows:{root}: cannot find the Windows lane command in .github/workflows/{wf}")
for cid, wf, text in all_check_refs():
path = ROOT / ".github/workflows" / wf
body = path.read_text() if path.exists() else ""
if text not in body:
bad += 1
print(f"out of sync: {cid}: .github/workflows/{wf} no longer contains: {text}")
if bad:
print("bin/ci --verify-sync: update bin/ci so it runs what CI runs (or put the text back in the workflow)")
return 1
print(f"bin/ci --verify-sync: {len(all_check_refs())} workflow commands match")
return 0
# ---------------------------------------------------------------- main
def parse_args(argv: Sequence[str]) -> argparse.Namespace:
p = argparse.ArgumentParser(prog="bin/ci", description=__doc__.split("\n\n")[0],
formatter_class=argparse.RawDescriptionHelpFormatter, epilog="\n\n".join(__doc__.split("\n\n")[1:]))
p.add_argument("--full", action="store_true", help="run every check, not only the affected ones")
p.add_argument("--quick", action="store_true", help="only checks that build nothing (seconds)")
p.add_argument("--keep-target", action="store_true", help="keep the cargo target dir (.bin-ci-target) between runs instead of deleting a per-run one")
p.add_argument("--fix", action="store_true", help="apply the safe fixers for failed checks, then re-check")
p.add_argument("--list", action="store_true", help="print the plan and exit")
p.add_argument("--only", metavar="IDS", help="comma-separated check ids or prefixes (see --list)")
p.add_argument("--base", metavar="REF", help="compare with REF (default: merge base with origin/main)")
p.add_argument("--jobs", "-j", type=int, help="checks to run at once (default: half the CPUs, 2 to 6)")
p.add_argument("--no-install", action="store_true", help="never install node_modules a check needs; skip it instead")
p.add_argument("--signoff", action="store_true", help=f"set the `{STATUS_CONTEXT}` commit status after a green run")
p.add_argument("--install-hook", action="store_true", help="install the opt-in pre-push hook")
p.add_argument("--uninstall-hook", action="store_true", help="remove the pre-push hook")
p.add_argument("--force", action="store_true", help=argparse.SUPPRESS)
p.add_argument("--hook", action="store_true", help=argparse.SUPPRESS)
p.add_argument("--verify-sync", action="store_true", help="fail if a workflow no longer runs a command bin/ci mirrors")
return p.parse_args(argv)
def raise_open_file_limit(want: int = 65536) -> None:
"""macOS shells default to 256 open files; a parallel cargo build under sccache
hits "Too many open files" and fails the test checks for no code reason."""
try:
import resource
soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
target = want if hard == resource.RLIM_INFINITY else min(want, hard)
if soft == resource.RLIM_INFINITY or soft >= target:
return
try:
resource.setrlimit(resource.RLIMIT_NOFILE, (target, hard))
except (ValueError, OSError): # macOS caps at kern.maxfilesperproc
resource.setrlimit(resource.RLIMIT_NOFILE, (10240, hard))
except (ImportError, ValueError, OSError):
pass
def main(argv: Sequence[str]) -> int:
if IS_WINDOWS and not sys.flags.utf8_mode:
# Windows reads files in the ANSI code page by default; the repo is UTF-8. Run again in UTF-8
# mode (children inherit PYTHONUTF8).
return subprocess.run([sys.executable, "-X", "utf8", str(Path(__file__).resolve()), *argv], env={**os.environ, "PYTHONUTF8": "1"}).returncode
args = parse_args(argv)
os.chdir(ROOT)
raise_open_file_limit()
if args.verify_sync:
return verify_sync()
if args.install_hook:
return install_hook(args.force)
if args.uninstall_hook:
return uninstall_hook()
if args.hook:
stdin_text = sys.stdin.read() if not sys.stdin.isatty() else ""
if hook_refs_are_deletions(stdin_text):
return 0
print("bin/ci: checking what this push changes (skip once: CUA_SKIP_LOCAL_CI=1 git push)", flush=True)
mode = "full" if args.full else ("quick" if args.quick else "affected")
if args.signoff and not args.full and not args.quick and not args.only:
last = state_dir() / "last-run.json"
if last.exists():
state = json.loads(last.read_text())
if state.get("head") == git("rev-parse", "HEAD").strip() and state.get("clean") and worktree_clean() and state.get("mode") in ("affected", "full"):
print(f"bin/ci: reusing the {state['mode']} run of {state['head'][:10]}")
return signoff(state)
base, base_desc = find_base(args.base)
changes = Changes(base, base_desc, changed_files(base), full=args.full)
if not changes.files and not args.full:
print(f"bin/ci: nothing changed against {base[:10]} ({base_desc})")
return 0
ctx = Context(args)
started = time.monotonic()
plan = build_plan(changes, ctx)
scope = "every check" if args.full else f"{len(changes.files)} changed file(s) since {base[:10]} ({base_desc})"
print(f"bin/ci: {mode} mode, {scope}: {len(plan)} check(s)")
for n in ctx.notes:
print(f" note: {n}")
if args.list:
for c in plan:
extra = f" [{c.skip_reason}]" if c.skip_reason else (" (heavy)" if c.heavy else "")
print(f" {c.id:<38} {c.title}{extra}")
print(f" {'':<38} $ (cd {c.cwd} && {c.cmd[:160]}{'...' if len(c.cmd) > 160 else ''})")
return 0
if not plan:
print("bin/ci: no local check covers these files")
return 0
logdir = state_dir() / "logs"
for old in logdir.glob("*.log"):
try:
old.unlink()
except OSError: # Windows: a log another bin/ci run (a test of this one) still has open
pass
sweep_stale_targets()
atexit.register(ctx.cleanup_target)
signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))
if any(is_heavy(c) and not c.skip_reason for c in plan):
ctx.guard = DiskGuard(ctx.target)
ctx.guard.start()
print(f"bin/ci: disk guard on: heavy checks need {min_free_gb():.0f} GB free, stop at a {max_target_gb():.0f} GB target dir or {floor_free_gb():.0f} GB free; "
f"target dir {ctx.target.name}{'' if not ctx.delete_target else ' (deleted on exit)'}")
try:
results = run_plan(plan, ctx, logdir)
finally:
ctx.cleanup_target()
if args.fix and any(r.status == "FAIL" for r in results):
results = apply_fixes(results, ctx, logdir)
elapsed = time.monotonic() - started
state = save_state(results, mode, elapsed)
failed = [r for r in results if r.status == "FAIL"]
counts = {s: sum(1 for r in results if r.status == s) for s in ("pass", "fixed", "FAIL", "skip", "warn")}
summary = ", ".join(f"{n} {label}" for label, n in (("passed", counts["pass"]), ("fixed", counts["fixed"]), ("failed", counts["FAIL"]),
("skipped", counts["skip"]), ("warnings", counts["warn"])) if n)
print(f"bin/ci: {summary} in {fmt_secs(elapsed)}")
if ctx.guard and ctx.guard.tripped:
print(f"bin/ci: STOPPED by the disk guard: {ctx.guard.tripped}. Rerun in CI (push the branch) or on a VM; `bin/ci --quick` runs only the cheap checks.")
return GUARD_EXIT
if failed:
safe = [r for r in failed if r.check.safe_fix and fix_commands(r)]
if safe and not args.fix:
print(f"bin/ci: `bin/ci --fix` repairs {len(safe)} of the {len(failed)} failure(s): {', '.join(r.check.id for r in safe)}")
if args.hook:
print("bin/ci: push stopped. Fix the failures, or push anyway with CUA_SKIP_LOCAL_CI=1 git push")
return 1
if args.signoff:
return signoff(state)
return 0
if __name__ == "__main__":
try:
sys.exit(main(sys.argv[1:]))
except KeyboardInterrupt:
sys.exit(130)