justfile

# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

set shell := ["bash", "-eu", "-o", "pipefail", "-c"]

export REPO_ROOT := justfile_directory()
export NEMO_RELAY_REPO_ROOT := REPO_ROOT

# Shared knobs used by the CI-oriented build, test, and package targets below.
ci := "false"
output_dir := ""
# When set, package targets use this exact version instead of synthesizing one.
ref_name := ""
# Linux package artifacts target this minimum glibc version for compatibility.
linux_glibc_version := "2.17"
# Supported Node package platform key. CI sets this from its package matrix.
node_platform := ""
node_target := ""
node_build_strategy := "native"
# Release packaging remains the default; source Quick Start runs use host dev builds.
package_profile := "release"
# Release CI packs the metapackage on Linux only; local host runs need both tarballs.
node_metapackage := "false"

bash_helpers := '''
set -euo pipefail

export_uv_python_runtime() {
    local python_runtime_exports=""
    local python_executable=""
    python_executable="$(uv_python_executable)"
    python_runtime_exports="$(
        cd "$NEMO_RELAY_REPO_ROOT"
        "$python_executable" - <<'PY'
import shlex
from pathlib import Path
import os
import sys
import sysconfig

def emit(name, value):
    print(f"export {name}={shlex.quote('' if value is None else str(value))}")

emit("PYO3_PYTHON", sys.executable)
emit("PYTHON_EXE_DIR", Path(sys.executable).parent)
emit("PYTHONHOME", sys.base_prefix)
emit("PYTHON_PATHSEP", os.pathsep)
emit("PYTHON_STDLIB", sysconfig.get_path("stdlib"))
emit("PYTHON_PLATSTDLIB", sysconfig.get_path("platstdlib"))
emit("PYTHON_LIBDIR", sysconfig.get_config_var("LIBDIR"))
PY
    )"

    eval "$python_runtime_exports"
    if command -v cygpath >/dev/null 2>&1; then
        export PATH="$(cygpath -u "$PYTHON_EXE_DIR"):$PATH"
    else
        export PATH="$PYTHON_EXE_DIR:$PATH"
    fi
    export PYTHONPATH="${PYTHON_STDLIB}${PYTHON_PATHSEP}${PYTHON_PLATSTDLIB}"
    export LD_LIBRARY_PATH="${PYTHON_LIBDIR:+${PYTHON_LIBDIR}}${PYTHON_LIBDIR:+${LD_LIBRARY_PATH:+:}}${LD_LIBRARY_PATH:-}"
    export DYLD_LIBRARY_PATH="${PYTHON_LIBDIR:+${PYTHON_LIBDIR}}${PYTHON_LIBDIR:+${DYLD_LIBRARY_PATH:+:}}${DYLD_LIBRARY_PATH:-}"
}

uv_python_executable() {
    (
        cd "$NEMO_RELAY_REPO_ROOT"
        if [[ -n "${UV_PYTHON:-}" ]]; then
            uv python find "$UV_PYTHON"
        else
            uv python find
        fi
    )
}

activate_project_venv() {
    # Ensure PATH-based tool lookups (for example, `zig`) resolve from the
    # synced project environment without asking uv to resync the project.
    local venv_dir=""
    local venv_bin=""
    if [[ -x "$NEMO_RELAY_REPO_ROOT/.venv/bin/python" ]]; then
        venv_dir="$NEMO_RELAY_REPO_ROOT/.venv"
        venv_bin="$venv_dir/bin"
    elif [[ -x "$NEMO_RELAY_REPO_ROOT/.venv/Scripts/python.exe" ]]; then
        venv_dir="$NEMO_RELAY_REPO_ROOT/.venv"
        venv_bin="$venv_dir/Scripts"
    else
        echo "ERROR: expected project virtualenv Python executable under .venv" >&2
        exit 1
    fi
    if command -v cygpath >/dev/null 2>&1; then
        venv_bin="$(cygpath -u "$venv_bin")"
    fi
    export VIRTUAL_ENV="$venv_dir"
    export PATH="$venv_bin:$PATH"
    unset PYTHONHOME
}

project_python_executable() {
    local python_executable=""
    if [[ -x "$NEMO_RELAY_REPO_ROOT/.venv/bin/python" ]]; then
        python_executable="$NEMO_RELAY_REPO_ROOT/.venv/bin/python"
    elif [[ -x "$NEMO_RELAY_REPO_ROOT/.venv/Scripts/python.exe" ]]; then
        python_executable="$NEMO_RELAY_REPO_ROOT/.venv/Scripts/python.exe"
    else
        echo "ERROR: expected project virtualenv Python executable under .venv" >&2
        exit 1
    fi

    if command -v cygpath >/dev/null 2>&1; then
        cygpath -u "$python_executable"
    else
        printf '%s\n' "$python_executable"
    fi
}

prepend_ziglang_to_path() {
    local python_executable="$1"
    local zig_dir=""

    zig_dir="$("$python_executable" - <<'PY'
from pathlib import Path
import importlib.util
import sys

spec = importlib.util.find_spec("ziglang")
if spec is None or spec.origin is None:
    raise SystemExit("ERROR: expected ziglang from the locked uv environment")

zig = Path(spec.origin).resolve().parent / ("zig.exe" if sys.platform == "win32" else "zig")
if not zig.exists():
    raise SystemExit(f"ERROR: expected zig binary at {zig}")

print(zig.parent)
PY
    )"

    export PATH="$zig_dir:$PATH"
}

use_project_python_source() {
    local python_executable="$1"
    local python_pathsep=""
    local python_source_path="$NEMO_RELAY_REPO_ROOT/python"

    python_pathsep="$("$python_executable" - <<'PY'
import os
print(os.pathsep)
PY
    )"
    if command -v cygpath >/dev/null 2>&1; then
        python_source_path="$(cygpath -w "$python_source_path")"
    fi
    export PYTHONPATH="${python_source_path}${PYTHONPATH:+${python_pathsep}${PYTHONPATH}}"
}

docs_dependencies_ready() {
    case "${NEMO_RELAY_DOCS_DEPS_READY:-}" in
        1|true|TRUE|True|yes|YES|Yes|on|ON|On)
            return 0
            ;;
        *)
            return 1
            ;;
    esac
}

ensure_docs_dependencies() {
    if docs_dependencies_ready; then
        return 0
    fi

    cd "$NEMO_RELAY_REPO_ROOT"
    uv sync --inexact --no-default-groups --group dev --no-install-project
    npm install --ignore-scripts
}

ensure_node_docs_declarations() {
    cd "$NEMO_RELAY_REPO_ROOT"
    local types_file="crates/node/dist/index.d.ts"
    local binding_file="crates/node/binding.d.ts"
    local newest_source=""

    if [[ -f "$types_file" && -f "$binding_file" ]]; then
        newest_source="$(
            find crates/node/src crates/node/ts crates/node/Cargo.toml crates/node/build.rs \
                crates/node/binding-types.d.ts crates/node/tsconfig.json \
                -type f -newer "$types_file" -print -quit
        )"
    fi

    if [[ ! -f "$types_file" || ! -f "$binding_file" || -n "$newest_source" ]]; then
        npm run build-debug --workspace=nemo-relay-node
    fi
}

generate_docs_api_references() {
    cd "$NEMO_RELAY_REPO_ROOT"
    uv run --no-sync python scripts/docs/generate_python_library_reference.py
    ensure_node_docs_declarations
    uv run --no-sync python -m unittest scripts.tests.test_node_library_reference
    uv run --no-sync python scripts/docs/generate_node_library_reference.py
    uv run --no-sync python -m unittest scripts.tests.test_rust_library_reference
    uv run --no-sync python scripts/docs/generate_rust_library_reference.py
}

prepare_parent_dir() {
    mkdir -p "$(dirname "$1")"
}

artifact_path() {
    local filename="$1"
    local base_dir="${output_dir:-$NEMO_RELAY_REPO_ROOT/target/coverage}"
    printf '%s/%s\n' "$base_dir" "$filename"
}

prepare_artifact() {
    local path
    path="$(artifact_path "$1")"
    prepare_parent_dir "$path"
    printf '%s\n' "$path"
}

# Package artifacts are grouped by ecosystem so local runs mirror CI layout.
package_output_dir() {
    local channel="$1"
    local base_dir="${output_dir:-$NEMO_RELAY_REPO_ROOT/target/packages}"
    printf '%s/%s\n' "$base_dir" "$channel"
}

prepare_package_dir() {
    local path
    path="$(package_output_dir "$1")"
    mkdir -p "$path"
    printf '%s\n' "$path"
}

head_git_sha() {
    git -C "$NEMO_RELAY_REPO_ROOT" rev-parse --short=8 HEAD
}

# Version helpers intentionally mutate package metadata in-place to match how CI
# sets release and non-release artifact versions before building them.
read_npm_package_version() {
    local pkg_path="$1"

    node - "$pkg_path" <<'NODE'
const fs = require('fs');
const [pkgPath] = process.argv.slice(2);
const manifest = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

if (!manifest.version) {
  throw new Error(`${pkgPath} missing version field`);
}

console.log(manifest.version);
NODE
}

set_npm_package_version() {
    local pkg_path="$1"
    local lock_path="${2:-}"
    local version="$3"
    local lock_package_path="${4:-}"

    node - "$pkg_path" "$lock_path" "$version" "$lock_package_path" <<'NODE'
const fs = require('fs');
const [pkgPath, lockPath, version, lockPackagePath] = process.argv.slice(2);

function readJson(path) {
  return JSON.parse(fs.readFileSync(path, 'utf8'));
}

function writeJson(path, value) {
  fs.writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
}

function requireVersion(value, label) {
  if (
    !Object.prototype.hasOwnProperty.call(value, 'version') ||
    typeof value.version !== 'string' ||
    value.version.length === 0
  ) {
    throw new Error(`${label} missing version field`);
  }
}

try {
  const manifest = readJson(pkgPath);
  requireVersion(manifest, pkgPath);
  const manifestChanged = manifest.version !== version;
  let lock = null;
  let lockChanged = false;
  let lockPackageChanged = false;

  if (lockPath) {
    lock = readJson(lockPath);
    if (!lock.packages) {
      throw new Error(`${lockPath} missing packages`);
    }

    if (typeof lock.version === 'string' && lock.version.length > 0) {
      lockChanged = lock.version !== version;
    }

    const packageEntryKey = lockPackagePath || '';
    const packageEntry = lock.packages[packageEntryKey];
    if (!packageEntry) {
      throw new Error(`${lockPath} missing packages["${packageEntryKey}"]`);
    }
    requireVersion(packageEntry, `${lockPath} packages["${packageEntryKey}"]`);
    lockPackageChanged = packageEntry.version !== version;
  }

  manifest.version = version;
  if (lock) {
    if (typeof lock.version === 'string' && lock.version.length > 0) {
      lock.version = version;
    }
    const packageEntryKey = lockPackagePath || '';
    lock.packages[packageEntryKey].version = version;
  }

  if (manifestChanged) {
    writeJson(pkgPath, manifest);
    console.log(`${pkgPath} version updated to ${version}`);
  } else {
    console.log(`${pkgPath} already set to ${version}`);
  }

  if (lockPath) {
    if (lockChanged || lockPackageChanged) {
      writeJson(lockPath, lock);
      console.log(`${lockPath} version updated to ${version}`);
    } else {
      console.log(`${lockPath} already set to ${version}`);
    }
  }
} catch (error) {
  console.error(`Error updating package version: ${error.message}`);
  process.exit(1);
}
NODE
}

set_npm_package_dependency_version() {
    local pkg_path="$1"
    local lock_path="${2:-}"
    local lock_package_path="$3"
    local dependency_name="$4"
    local version="$5"

    node - "$pkg_path" "$lock_path" "$lock_package_path" "$dependency_name" "$version" <<'NODE'
const fs = require('fs');
const [pkgPath, lockPath, lockPackagePath, dependencyName, version] = process.argv.slice(2);

function readJson(path) {
  return JSON.parse(fs.readFileSync(path, 'utf8'));
}

function writeJson(path, value) {
  fs.writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
}

function requireDependency(container, label) {
  if (
    !container.dependencies ||
    !Object.prototype.hasOwnProperty.call(container.dependencies, dependencyName)
  ) {
    throw new Error(`${label} missing dependencies["${dependencyName}"]`);
  }
}

try {
  const manifest = readJson(pkgPath);
  requireDependency(manifest, pkgPath);
  const manifestChanged = manifest.dependencies[dependencyName] !== version;

  let lock = null;
  let lockChanged = false;
  if (lockPath) {
    lock = readJson(lockPath);
    if (!lock.packages) {
      throw new Error(`${lockPath} missing packages`);
    }
    const packageEntry = lock.packages[lockPackagePath];
    if (!packageEntry) {
      throw new Error(`${lockPath} missing packages["${lockPackagePath}"]`);
    }
    requireDependency(packageEntry, `${lockPath} packages["${lockPackagePath}"]`);
    lockChanged = packageEntry.dependencies[dependencyName] !== version;
  }

  manifest.dependencies[dependencyName] = version;
  if (lock) {
    lock.packages[lockPackagePath].dependencies[dependencyName] = version;
  }

  if (manifestChanged) {
    writeJson(pkgPath, manifest);
  }

  if (lockPath) {
    if (lockChanged) {
      writeJson(lockPath, lock);
    }
  }
} catch (error) {
  console.error(`Error updating package dependency: ${error.message}`);
  process.exit(1);
}
NODE
}

set_coding_agent_plugin_versions() {
    local version="$1"

    node - "$version" <<'NODE'
const fs = require('fs');
const version = process.argv[2];
const manifests = [
  'integrations/coding-agents/claude-code/.claude-plugin/plugin.json',
  'integrations/coding-agents/codex/.codex-plugin/plugin.json',
];

for (const manifestPath of manifests) {
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
  if (!manifest.version) {
    throw new Error(`${manifestPath} missing version field`);
  }
  if (manifest.version === version) {
    console.log(`${manifestPath} already set to ${version}`);
    continue;
  }
  manifest.version = version;
  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
  console.log(`${manifestPath} version updated to ${version}`);
}
NODE
}

read_workspace_version() {
    local python_executable=""
    python_executable="$(uv_python_executable)"
    "$python_executable" - <<'PY'
from pathlib import Path
import re

text = Path("Cargo.toml").read_text()
match = re.search(r'^version = "(.*)"$', text, flags=re.MULTILINE)
if not match:
    raise SystemExit("Failed to read version from Cargo.toml")
print(match.group(1))
PY
}

set_cargo_workspace_version() {
    local version="$1"
    local python_executable=""
    python_executable="$(uv_python_executable)"

    "$python_executable" - "$version" <<'PY'
from pathlib import Path
import re
import sys

version = sys.argv[1]
if version.startswith("v"):
    raise SystemExit("Release tags must not start with 'v'; use raw SemVer such as 0.1.0")
numeric_identifier = r"(?:0|[1-9][0-9]*)"
if not re.fullmatch(
    rf"{numeric_identifier}\.{numeric_identifier}\.{numeric_identifier}"
    rf"(?:-(?:alpha|beta|rc)\.{numeric_identifier})?"
    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?",
    version,
):
    raise SystemExit(
        f"Unsupported Cargo version '{version}'; use 0.1.0, prereleases like "
        "0.1.0-rc.1, or build metadata like 0.1.0+deadbeef"
    )

path = Path("Cargo.toml")
text = path.read_text()
section = ""
output = []
changed = []
found_workspace_version = False
local_dependencies = (
    "nemo-relay-types",
    "nemo-relay-codecs",
    "nemo-relay-model-pricing",
    "nemo-relay-resource-metrics",
    "nemo-relay-observability",
    "nemo-relay-worker-proto",
    "nemo-relay-worker",
    "nemo-relay-diagnostics",
    "nemo-relay-logging",
    "nemo-relay-runtime",
    "nemo-relay-plugin-host",
    "nemo-relay",
    "nemo-relay-plugin",
    "nemo-relay-plugin-abi",
    "nemo-relay-adaptive",
    "nemo-relay-pii-redaction",
    "nemo-relay-builtins",
    "nemo-relay-ffi",
    "nemo-relay-cli",
)
found_dependencies = set()

for line in text.splitlines(keepends=True):
    section_match = re.match(r"^\s*\[([^\]]+)\]\s*(?:#.*)?$", line)
    if section_match:
        section = section_match.group(1)

    updated = line
    if section == "workspace.package":
        updated, count = re.subn(
            r'^(version\s*=\s*")([^"]+)(".*)$',
            rf"\g<1>{version}\g<3>",
            line,
        )
        if count == 1:
            found_workspace_version = True
            if updated != line:
                changed.append("workspace.package.version")
    elif section == "workspace.dependencies":
        for dependency in local_dependencies:
            updated, count = re.subn(
                rf"^({re.escape(dependency)}\s*=\s*\{{[^}}]*\bversion\s*=\s*\")([^\"]+)(\".*)$",
                lambda match: f'{match[1]}{"=" if match[2].startswith("=") else ""}{version}{match[3]}',
                updated,
            )
            if count == 1:
                found_dependencies.add(dependency)
                if updated != line:
                    changed.append(f"workspace.dependencies.{dependency}.version")
                break

    output.append(updated)

missing = []
if not found_workspace_version:
    missing.append("workspace.package.version")
for dependency in local_dependencies:
    if dependency not in found_dependencies:
        missing.append(f"workspace.dependencies.{dependency}.version")
if missing:
    raise SystemExit(f"Failed to find expected Cargo version fields: {', '.join(missing)}")

path.write_text("".join(output))
if changed:
    print(f"Cargo.toml version set to {version}: {', '.join(changed)}")
else:
    print(f"Cargo.toml already set to {version}")
PY

    local metadata_file=""
    metadata_file="$(mktemp)"
    if ! cargo metadata --no-deps --format-version 1 > "$metadata_file"; then
        rm -f "$metadata_file"
        return 1
    fi
    if ! "$python_executable" - "$version" "$metadata_file" <<'PY'
import json
import sys
from pathlib import Path

version = sys.argv[1]
metadata = json.loads(Path(sys.argv[2]).read_text())
workspace_members = set(metadata["workspace_members"])
mismatched = []
checked = 0

for package in metadata["packages"]:
    if package["id"] not in workspace_members or not package["name"].startswith("nemo-relay"):
        continue
    checked += 1
    if package["version"] != version:
        mismatched.append(f"{package['name']}={package['version']}")

if checked == 0:
    raise SystemExit("Cargo metadata did not include any nemo-relay workspace packages")
if mismatched:
    raise SystemExit(f"Cargo workspace packages do not all resolve to {version}: {', '.join(mismatched)}")
print(f"Cargo metadata resolves {checked} nemo-relay workspace packages to {version}")
PY
    then
        rm -f "$metadata_file"
        return 1
    fi
    rm -f "$metadata_file"
}

set_node_package_versions() {
    local version="$1"
    set_npm_package_version crates/node/package.json package-lock.json "$version" crates/node
    set_npm_package_version examples/language-binding-plugin/node/package.json package-lock.json "$version" examples/language-binding-plugin/node
    set_npm_package_version integrations/openclaw/package.json package-lock.json "$version" integrations/openclaw
    set_npm_package_dependency_version integrations/openclaw/package.json package-lock.json integrations/openclaw nemo-relay-node "$version"
    # `nemo-relay-pi` is private and not published, so this bump changes nothing today. It is here
    # so the version cannot already be stale on the day that changes: a workspace member absent
    # from this list drifts silently, with no lockfile mismatch and no CI failure to catch it.
    #
    # The manifest is written at its real path rather than through `integrations/pi`'s symlink to
    # it. A checkout without symlink support leaves a text stub there, and writing through that
    # would overwrite the link target's path with a manifest instead of bumping anything.
    set_npm_package_version crates/cli/assets/pi-extension/package.json package-lock.json "$version" integrations/pi
}

set_example_package_versions() {
    local version="$1"
    local python_version=""
    python_version="$(semver_to_pep440 "$version")"
    local python_executable=""
    python_executable="$(uv_python_executable)"

    "$python_executable" - "$version" "$python_version" <<'PY'
import json
import re
import sys
from pathlib import Path

version = sys.argv[1]
python_version = sys.argv[2]

def replace_one(path: str, pattern: str, replacement: str) -> None:
    file = Path(path)
    text = file.read_text()
    updated, count = re.subn(pattern, replacement, text)
    if count != 1:
        raise SystemExit(f"Failed to update exactly one version in {path}; found {count}")
    if updated != text:
        file.write_text(updated)
        print(f"{path} version updated to {version}")
    else:
        print(f"{path} already set to {version}")

# Rust examples inherit their SDK dependencies from the Cargo workspace.
replace_one(
    "examples/language-binding-plugin/python/pyproject.toml",
    r'(nemo-relay==)[^"\n]+',
    rf'\g<1>{python_version}',
)
replace_one(
    "examples/python-grpc-worker-plugin/pyproject.toml",
    r'(nemo-relay-plugin>=)[^"\n]+',
    rf'\g<1>{python_version}',
)

for manifest in [
    "examples/language-binding-plugin/python/pyproject.toml",
    "examples/python-grpc-worker-plugin/pyproject.toml",
]:
    replace_one(manifest, r'(\nversion = ")[^"]+("\n)', rf'\g<1>{python_version}\2')

node_example = Path("examples/language-binding-plugin/node/package.json")
manifest = json.loads(node_example.read_text())
dependency = manifest.get("dependencies", {}).get("nemo-relay-node")
if dependency != "file:../../../crates/node":
    raise SystemExit(
        "examples/language-binding-plugin/node/package.json must link the local "
        "nemo-relay-node workspace package before the npm package is published"
    )
print("examples/language-binding-plugin/node/package.json links the local workspace package")
PY

}

set_node_package_version() {
    set_node_package_versions "$1"
    set_example_package_versions "$1"
}

set_project_version() {
    local version="$1"
    set_cargo_workspace_version "$version"
    set_node_package_versions "$version"
    set_example_package_versions "$version"
    set_python_package_version "$version" false
    set_python_plugin_package_version "$version"
    set_coding_agent_plugin_versions "$version"
    # Resolve only after every workspace manifest has its final version.
    cargo metadata --format-version 1 >/dev/null
    # Keep existing dependency pins; allow fetching build backends for dynamic metadata.
    uv lock
}

semver_to_pep440() {
    local python_executable=""
    python_executable="$(uv_python_executable)"

    "$python_executable" - "$1" <<'PY'
import re
import sys

pattern = re.compile(
    r"^(?P<release>\d+\.\d+\.\d+)"
    r"(?:-(?P<pre_label>alpha|beta|rc)(?:\.(?P<pre_num>\d+))?)?"
    r"(?:\+(?P<local>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$"
)
match = pattern.fullmatch(sys.argv[1])
if not match:
    raise SystemExit(
        "Unsupported Python package version format. Expected SemVer with optional "
        "alpha/beta/rc prerelease and optional build metadata."
    )

pep440 = match.group("release")
pre_label = match.group("pre_label")
if pre_label:
    pre_map = {"alpha": "a", "beta": "b", "rc": "rc"}
    pre_num = match.group("pre_num") or "0"
    pep440 += f"{pre_map[pre_label]}{pre_num}"

local = match.group("local")
if local:
    normalized_local = ".".join(part.lower() for part in re.split(r"[._-]+", local) if part)
    if not normalized_local:
        raise SystemExit("Python package local version metadata cannot be empty")
    pep440 += f"+{normalized_local}"

print(pep440)
PY
}

set_python_package_version() {
    local cargo_version="$1"
    local materialize_version="${2:-true}"
    local version=""
    local python_executable=""
    version="$(semver_to_pep440 "$cargo_version")"
    python_executable="$(uv_python_executable)"

    "$python_executable" - "$version" "$materialize_version" <<'PY'
from pathlib import Path
import re
import sys

version = sys.argv[1]
materialize_version = sys.argv[2] == "true"
path = Path("pyproject.toml")
text = path.read_text()

if materialize_version and 'dynamic = ["version"]' in text:
    updated = text.replace('dynamic = ["version"]', f'version = "{version}"', 1)
elif materialize_version and re.search(r'^version = "(.*)"$', text, flags=re.MULTILINE):
    updated, count = re.subn(
        r'^version = "(.*)"$',
        f'version = "{version}"',
        text,
        count=1,
        flags=re.MULTILINE,
    )
    if count != 1:
        raise SystemExit("Failed to update version in pyproject.toml")
elif not materialize_version and 'dynamic = ["version"]' in text:
    updated = text
elif not materialize_version and re.search(r'^version = "(.*)"$', text, flags=re.MULTILINE):
    updated, count = re.subn(
        r'^version = "(.*)"$',
        'dynamic = ["version"]',
        text,
        count=1,
        flags=re.MULTILINE,
    )
    if count != 1:
        raise SystemExit("Failed to restore dynamic version in pyproject.toml")
else:
    raise SystemExit("Failed to find version field in pyproject.toml")

if updated != text:
    path.write_text(updated)
if materialize_version:
    print(f"pyproject.toml version updated to {version}")
else:
    print("pyproject.toml uses the dynamic Cargo version")

path = Path("crates/python/Cargo.toml")
text = path.read_text()

if "version.workspace = true" in text:
    updated = text
elif re.search(r'^version = "(.*)"$', text, flags=re.MULTILINE):
    updated, count = re.subn(
        r'^version = "(.*)"$',
        "version.workspace = true",
        text,
        count=1,
        flags=re.MULTILINE,
    )
    if count != 1:
        raise SystemExit("Failed to update version in crates/python/Cargo.toml")
else:
    raise SystemExit("Failed to find workspace or static version field in crates/python/Cargo.toml")

if updated != text:
    path.write_text(updated)
print("crates/python/Cargo.toml uses the workspace version")

path = Path("python/cli-bin/pyproject.toml")
text = path.read_text()
updated, count = re.subn(
    r'^version = "(.*)"$',
    f'version = "{version}"',
    text,
    count=1,
    flags=re.MULTILINE,
)
if count != 1:
    raise SystemExit("Failed to update version in python/cli-bin/pyproject.toml")
if updated != text:
    path.write_text(updated)
print(f"python/cli-bin/pyproject.toml version updated to {version}")

path = Path("pyproject.toml")
text = path.read_text()
updated, count = re.subn(
    r'("nemo-relay-cli-bin==)[^"]+(")',
    rf'\g<1>{version}\g<2>',
    text,
    count=1,
)
if count != 1:
    raise SystemExit("Failed to update the nemo-relay CLI extra version")
if updated != text:
    path.write_text(updated)
print(f"nemo-relay CLI extra updated to {version}")
PY
}

set_python_plugin_package_version() {
    local version=""
    local python_executable=""
    version="$(semver_to_pep440 "$1")"
    python_executable="$(uv_python_executable)"

    "$python_executable" - "$version" <<'PY'
from pathlib import Path
import re
import sys

version = sys.argv[1]
path = Path("python/plugin/pyproject.toml")
text = path.read_text()
updated, count = re.subn(
    r'^version = "(.*)"$',
    f'version = "{version}"',
    text,
    count=1,
    flags=re.MULTILINE,
)
if count != 1:
    raise SystemExit("Failed to update version in python/plugin/pyproject.toml")
path.write_text(updated)
print(f"python/plugin/pyproject.toml version updated to {version}")
PY
}

# Publish dependencies first, including dev dependencies used in package validation.
published_cargo_packages() {
    printf '%s\n' \
        nemo-relay-plugin-abi \
        nemo-relay-types \
        nemo-relay-worker-proto \
        nemo-relay-codecs \
        nemo-relay-plugin \
        nemo-relay-worker \
        nemo-relay-diagnostics \
        nemo-relay-model-pricing \
        nemo-relay-logging \
        nemo-relay-observability \
        nemo-relay-resource-metrics \
        nemo-relay-runtime \
        nemo-relay-plugin-host \
        nemo-relay-adaptive \
        nemo-relay-pii-redaction \
        nemo-relay-builtins \
        nemo-relay-ffi \
        nemo-relay-cli \
        nemo-relay
}

# Keep local wheel packaging aligned with the CI matrix without requiring raw
# maturin flags to be passed through `just --set`.
linux_manylinux_compatibility() {
    local glibc_version="${linux_glibc_version:-2.17}"
    printf 'manylinux_%s\n' "${glibc_version//./_}"
}

python_wheel_build_args() {
    local os_name
    os_name="$(uname -s)"
    case "$os_name" in
        Linux)
            printf '%s\0' --compatibility "$(linux_manylinux_compatibility)" --zig
            ;;
        Darwin)
            printf '%s\0' --compatibility pypi
            ;;
        CYGWIN*|MINGW*|MSYS*)
            printf '%s\0' --compatibility pypi
            ;;
        *)
            echo "ERROR: unsupported OS for package-python: $os_name" >&2
            exit 1
            ;;
    esac
}

python_plugin_grpc_dependencies_supported() {
    local python_executable="$1"
    "$python_executable" - <<'PY'
import platform
import sys

is_windows_arm64 = sys.platform == "win32" and platform.machine().lower() in {"arm64", "aarch64"}
raise SystemExit(1 if is_windows_arm64 else 0)
PY
}

configure_python_plugin_test_environment() {
    local python_executable="$1"
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        unset NEMO_RELAY_SKIP_PYTHON_PLUGIN_TESTS
    else
        echo "Skipping nemo-relay-plugin grpc dependencies on Windows ARM64; plugin SDK tests will be skipped"
        export NEMO_RELAY_SKIP_PYTHON_PLUGIN_TESTS=1
    fi
}

python_plugin_sync_args() {
    local python_executable="$1"
    if ! python_plugin_grpc_dependencies_supported "$python_executable"; then
        printf '%s\0' \
            --no-install-package grpcio \
            --no-install-package nemo-relay-plugin \
            --no-install-package nemo-relay-python-grpc-worker-example
    fi
}

run_python_worker_proto_tests() {
    local python_executable=""
    python_executable="$(uv_python_executable)"
    if ! python_plugin_grpc_dependencies_supported "$python_executable"; then
        echo "Skipping Python worker proto tests on Windows ARM64"
        return
    fi
    local requirements=""
    requirements="$("$python_executable" - <<'PY'
import tomllib
from pathlib import Path

locked = tomllib.loads(Path("uv.lock").read_text())["package"]
for name in ("pytest", "pytest-asyncio"):
    package = next(package for package in locked if package["name"] == name)
    print(f"{name}=={package['version']}")
dependencies = tomllib.loads(Path("python/plugin/pyproject.toml").read_text())["project"]["dependencies"]
print(next(requirement for requirement in dependencies if requirement.startswith("protovalidate==")))
PY
)"
    local test_dependencies=()
    local requirement=""
    while IFS= read -r requirement; do
        test_dependencies+=(--with "$requirement")
    done <<< "$requirements"
    local grpcio_tools_version=""
    grpcio_tools_version="$(python_plugin_grpcio_tools_version)"
    uvx --from "grpcio-tools==$grpcio_tools_version" "${test_dependencies[@]}" python -m pytest \
        python/tests/plugin/test_nvidia_worker_proto_v1.py -q -o asyncio_default_fixture_loop_scope=function
}

python_plugin_grpcio_tools_version() {
    local python_executable=""
    python_executable="$(uv_python_executable)"
    "$python_executable" - <<'PY'
import tomllib
from pathlib import Path

requirements = tomllib.loads(
    Path("python/plugin/pyproject.toml").read_text()
)["build-system"]["requires"]
prefix = "grpcio-tools=="
for requirement in requirements:
    if requirement.startswith(prefix):
        print(requirement.removeprefix(prefix))
        break
else:
    raise SystemExit("python/plugin/pyproject.toml must pin grpcio-tools")
PY
}

generate_python_worker_proto_files() {
    local output_dir="$1"
    local grpcio_tools_version=""
    grpcio_tools_version="$(python_plugin_grpcio_tools_version)"
    uvx --from "grpcio-tools==$grpcio_tools_version" python python/plugin/build_backend.py --generate "$output_dir"
}

prepend_go_bin_to_path() {
    local go_bin
    go_bin="$(go env GOBIN)"
    if [[ -z "$go_bin" ]]; then
        go_bin="$(go env GOPATH)/bin"
    fi
    export PATH="$go_bin:$PATH"
}

prepare_test_plugin_fixtures() {
    # Include instrumented foreign libraries and worker executables in llvm-cov's object scan.
    local target_dir="${CARGO_LLVM_COV_TARGET_DIR:-$NEMO_RELAY_REPO_ROOT/target/test-plugin-fixtures}"
    local native_library=""
    local worker_executable="nemo-relay-worker-plugin-fixture"
    local host_os=""

    host_os="$(uname -s 2>/dev/null || true)"
    case "${RUNNER_OS:-}:${OSTYPE:-}:$host_os" in
        Windows:*|*:msys*:*|*:win32*:*|*:*:MINGW*|*:*:MSYS*|*:*:CYGWIN*)
            native_library="nemo_relay_plugin_fixture.dll"
            worker_executable="${worker_executable}.exe"
            ;;
        *:darwin*:*|*:*:Darwin)
            native_library="libnemo_relay_plugin_fixture.dylib"
            ;;
        *)
            native_library="libnemo_relay_plugin_fixture.so"
            ;;
    esac

    cd "$NEMO_RELAY_REPO_ROOT"
    cargo build --quiet --locked \
        --manifest-path crates/plugin-host/tests/fixtures/native_plugin/Cargo.toml \
        --target-dir "$target_dir"
    cargo build --quiet --locked \
        --manifest-path crates/plugin-host/tests/fixtures/worker_plugin/Cargo.toml \
        --target-dir "$target_dir"

    export NEMO_RELAY_TEST_NATIVE_PLUGIN="$target_dir/debug/$native_library"
    export NEMO_RELAY_TEST_WORKER_PLUGIN="$target_dir/debug/$worker_executable"
    if [[ ! -f "$NEMO_RELAY_TEST_NATIVE_PLUGIN" ]]; then
        echo "ERROR: missing native plugin test fixture: $NEMO_RELAY_TEST_NATIVE_PLUGIN" >&2
        exit 1
    fi
    if [[ ! -f "$NEMO_RELAY_TEST_WORKER_PLUGIN" ]]; then
        echo "ERROR: missing worker plugin test fixture: $NEMO_RELAY_TEST_WORKER_PLUGIN" >&2
        exit 1
    fi

    if command -v cygpath >/dev/null 2>&1; then
        NEMO_RELAY_TEST_NATIVE_PLUGIN="$(cygpath -w "$NEMO_RELAY_TEST_NATIVE_PLUGIN")"
        NEMO_RELAY_TEST_WORKER_PLUGIN="$(cygpath -w "$NEMO_RELAY_TEST_WORKER_PLUGIN")"
        export NEMO_RELAY_TEST_NATIVE_PLUGIN NEMO_RELAY_TEST_WORKER_PLUGIN
    fi
}

prepare_llvm_cov_workspace() {
    eval "$(cargo llvm-cov show-env --sh)"
    cargo llvm-cov clean --workspace
}

# usage: export_llvm_cov_lcov OUTPUT [--package NAME]... -- NEXTEST_LIST_COMMAND...
export_llvm_cov_lcov() {
    local output="$1"
    shift
    local -a export_args=()
    while [[ "$1" != "--" ]]; do
        export_args+=("$1")
        shift
    done
    shift
    local nextest_list
    nextest_list="$(mktemp)"
    "$@" --message-format json > "$nextest_list"
    local nextest_list_native="$nextest_list"
    if command -v cygpath >/dev/null 2>&1; then
        nextest_list_native="$(cygpath -w "$nextest_list")"
    fi
    "$(uv_python_executable)" "$NEMO_RELAY_REPO_ROOT/scripts/coverage/export_llvm_cov_lcov.py" \
        --nextest-list "$nextest_list_native" \
        --output "$output" \
        ${export_args[@]+"${export_args[@]}"}
    rm -f "$nextest_list"
}

rust_source_coverage_supported() {
    local host
    host="$(rustc -vV | sed -n 's/^host: //p')"
    case "$host" in
        aarch64-pc-windows-msvc|*-unknown-linux-musl)
            return 1
            ;;
        *)
            return 0
            ;;
    esac
}

is_true() {
    case "$1" in
        1|true|TRUE|True|yes|YES|Yes|on|ON|On)
            return 0
            ;;
        0|false|FALSE|False|no|NO|No|off|OFF|Off|"")
            return 1
            ;;
        *)
            echo "ERROR: expected a boolean-like value, got: $1" >&2
            exit 1
            ;;
    esac
}
'''

# validate quickstart metadata, referenced files, and checker tests (no guide execution)
check-quickstarts:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    if ! command -v jq >/dev/null 2>&1; then
        echo "Error: jq is required for Quick Start checks. Install jq and rerun just check-quickstarts." >&2
        exit 1
    fi
    uv sync --frozen --inexact --no-default-groups --group dev --no-install-project
    python_executable="$(project_python_executable)"
    # Keep automatic checks explicit: guide shell/Python execution belongs to the manual workflow.
    "$python_executable" -m unittest \
        scripts.tests.test_quickstarts \
        scripts.tests.test_quickstart_jq
    "$python_executable" scripts/check-quickstarts.py check

# Execute credential-free Quick Starts against explicit release, build, or local assets.
[positional-arguments]
test-quickstarts *args:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    uv sync --frozen --inexact --no-default-groups --group dev --no-install-project
    python_executable="$(project_python_executable)"
    "$python_executable" scripts/run-quickstarts.py "$@"

# validate the documentation site, links, navigation, and generated references
docs: docs-examples
    #!/usr/bin/env bash
    {{ bash_helpers }}
    ensure_docs_dependencies
    generate_docs_api_references
    cd "$NEMO_RELAY_REPO_ROOT/fern"
    npx fern check --warnings
    npx fern docs broken-links --strict

# validate documentation links and navigation without a full site build
docs-linkcheck: docs-examples
    #!/usr/bin/env bash
    {{ bash_helpers }}
    ensure_docs_dependencies
    generate_docs_api_references
    cd "$NEMO_RELAY_REPO_ROOT/fern"
    npx fern check --warnings
    npx fern docs broken-links --strict

# compile and run Rust examples shared with the documentation
docs-examples:
    cargo test --locked -p nemo-relay-types -p nemo-relay --test documentation_examples

# regenerate the ignored Fern API reference pages
docs-api-reference:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    ensure_docs_dependencies
    generate_docs_api_references

# --set [package_profile=release|dev]
build-cli:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    cargo build --locked --profile "{{ package_profile }}" -p nemo-relay-cli

# --set [ci=true|false]
build-rust:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    export_uv_python_runtime
    cd "$NEMO_RELAY_REPO_ROOT"
    if is_true "{{ ci }}"; then
        prepare_llvm_cov_workspace
        cargo test --workspace --no-run
    else
        # Maturin supplies the platform-specific linker configuration for the
        # Python extension in build-python.
        cargo build --workspace --exclude nemo-relay-python
    fi

# --set [ci=true|false]
build-python:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    uv sync --inexact --no-install-project --no-install-package nemo-relay --extra langchain --extra langgraph --extra deepagents --extra google-adk --group google-adk-test
    activate_project_venv
    if is_true "{{ ci }}"; then
        prepare_llvm_cov_workspace
    fi
    python_executable="$(project_python_executable)"
    "$python_executable" -m maturin develop

build-python-plugin:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    python_executable="$(uv_python_executable)"
    sync_args=(--inexact --no-install-project)
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        sync_args+=(--package nemo-relay-plugin --reinstall-package nemo-relay-plugin)
    fi
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    python_executable="$(project_python_executable)"
    configure_python_plugin_test_environment "$python_executable"
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        "$python_executable" -c 'import nemo_relay_plugin; print(f"nemo-relay-plugin import ok: {nemo_relay_plugin.__name__}")'
    else
        echo "nemo-relay-plugin is unsupported on Windows ARM64"
    fi

generate-python-worker-proto:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    generate_python_worker_proto_files python/plugin/src/nemo_relay_plugin/_proto

# Lint, format, and independently test the current worker contract.
# Install Buf 1.75.0 or newer, or set BUF to its executable path.
check-worker-proto:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    buf_executable="${BUF:-buf}"
    "$buf_executable" lint crates/worker-proto
    "$buf_executable" format crates/worker-proto --path crates/worker-proto/proto/nvidia/nemo/relay/worker/v1 --diff --exit-code
    run_python_worker_proto_tests

# Resolve the locked validation dependency into the ignored build cache.
resolve-worker-proto-deps:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    python_executable="$(uv_python_executable)"
    "$python_executable" scripts/proto_dependencies.py

check-python-worker-proto:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    run_python_worker_proto_tests


generate-test-plugin-lockfiles:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    cargo metadata --format-version 1 >/dev/null

generate-worker-plugin-lockfile: generate-test-plugin-lockfiles

# Build frozen native ABI generations in independent Cargo workspaces.
build-native-abi-test-fixtures:
    #!/usr/bin/env bash
    "$BASH" scripts/build_native_abi_fixtures.sh

# Explicitly refresh lockfiles for the independently built ABI fixtures.
generate-native-abi-test-lockfiles:
    #!/usr/bin/env bash
    "$BASH" scripts/build_native_abi_fixtures.sh --update-lockfiles

# Check unchanged ABI fixture binaries across the active and comparison compilers.
test-native-abi-toolchains toolchain:
    #!/usr/bin/env bash
    uv run --no-sync python scripts/check_native_abi_toolchains.py {{ quote(toolchain) }}

# Compare real native middleware paths with a separate source checkout.
benchmark-native-plugins baseline:
    #!/usr/bin/env bash
    uv run --no-sync python scripts/native_plugin_benchmark/run.py {{ quote(baseline) }}

# Build the native and worker dynamic-plugin fixtures once for test processes.
build-test-plugin-fixtures:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    prepare_test_plugin_fixtures
    printf 'Native plugin fixture: %s\n' "$NEMO_RELAY_TEST_NATIVE_PLUGIN"
    printf 'Worker plugin fixture: %s\n' "$NEMO_RELAY_TEST_WORKER_PLUGIN"


# --set [ci=true|false]
build-go:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    if is_true "{{ ci }}"; then
        cargo build -p nemo-relay-ffi
    else
        cargo build --release -p nemo-relay-ffi
    fi


# --set [ci=true|false]
build-node:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    if is_true "{{ ci }}"; then
        prepare_llvm_cov_workspace
    fi
    cd "$NEMO_RELAY_REPO_ROOT"
    npm install --workspace=nemo-relay-node --ignore-scripts
    if is_true "{{ ci }}"; then
        npm run build-debug --workspace=nemo-relay-node
    else
        npm run build --workspace=nemo-relay-node
    fi

build-all: build-rust build-python build-python-plugin build-go build-node

# remove local build and test artifacts
clean:
    #!/usr/bin/env bash
    set -euo pipefail
    shopt -s nullglob globstar
    rm -rf \
        .coverage \
        .pytest_cache \
        *.profraw \
        crates/**/*.profraw \
        crates/node/*.node \
        crates/node/coverage \
        crates/node/binding.d.ts \
        crates/node/binding.js \
        crates/node/dist \
        crates/node/junit.xml \
        crates/node/node_modules \
        integrations/openclaw/*.profraw \
        integrations/openclaw/.test-dist \
        integrations/openclaw/dist \
        integrations/openclaw/node_modules \
        integrations/pi/node_modules \
        node_modules \
        docs/_build/ \
        docs/reference/api/**/_generated/ \
        docs/reference/api/**/_source/ \
        go/nemo_relay/coverage.out \
        python/nemo_relay/*.so \
        python/nemo_relay/__pycache__ \
        python/nemo_relay/_native*.pyd \
        python/plugin/build \
        python/plugin/dist \
        python/plugin/proto \
        python/plugin/src/nemo_relay_plugin/__pycache__ \
        python/plugin/src/nemo_relay_plugin/_proto/__pycache__ \
        python/plugin/src/nemo_relay_plugin/_proto/plugin_worker_pb2.py \
        python/plugin/src/nemo_relay_plugin/_proto/plugin_worker_pb2_grpc.py \
        python/plugin/src/nemo_relay_plugin.egg-info \
        python/tests/__pycache__ \
        python/tests/plugin/__pycache__ \
        examples/python-grpc-worker-plugin/.pytest_cache \
        examples/python-grpc-worker-plugin/.venv \
        examples/python-grpc-worker-plugin/build \
        examples/python-grpc-worker-plugin/dist \
        examples/python-grpc-worker-plugin/__pycache__ \
        examples/python-grpc-worker-plugin/nemo_relay_python_grpc_worker_example/__pycache__ \
        examples/python-grpc-worker-plugin/*.egg-info \
        examples/rust-native-plugin/target \
        target

# Opt-in: requires a supported Codex installation and is intentionally outside test-rust/CI.
test-codex-plugin-e2e:
    ./scripts/test-codex-plugin-e2e.sh

# Opt-in: requires a supported Claude Code installation and is intentionally outside test-rust/CI.
test-claude-plugin-e2e:
    ./scripts/test-claude-plugin-e2e.sh

# Opt-in: builds the release CLI and runs configurable local latency suites.
[positional-arguments]
latency-benchmark *benchmark_args:
    #!/usr/bin/env bash
    set -euo pipefail
    result_dir={{ quote(output_dir) }}
    result_dir="${result_dir:-target/benchmark-results}"
    for argument in "$@"; do
        if [[ "$argument" == "-h" || "$argument" == "--help" ]]; then
            exec uv run --locked python -m scripts.latency_benchmark.src "$@"
        fi
    done
    cargo build --locked --release -p nemo-relay-cli
    uv run --locked python -m scripts.latency_benchmark.src \
        --relay-bin target/release/nemo-relay \
        --output "$result_dir/nemo-relay-latency-report.json" \
        "$@"

# Runs the fast latency benchmark fixture tests without building Relay.
test-latency-benchmark:
    uv run --locked python -m pytest scripts/latency_benchmark/tests

# Focused checks for the transport benchmark workspace member.
check-daemon-transport-benchmark:
    cargo fmt -p nemo-relay-daemon-transport-benchmark -- --check
    cargo clippy --locked -p nemo-relay-daemon-transport-benchmark --all-targets -- -D warnings

# Small deterministic daemon transport check. Informational timings; stream integrity is required.
daemon-transport-benchmark-smoke:
    #!/usr/bin/env bash
    set -euo pipefail
    result_dir={{ quote(output_dir) }}
    result_dir="${result_dir:-target/benchmark-results}"
    cargo run --locked --profile daemon-transport \
        -p nemo-relay-daemon-transport-benchmark \
        --target-dir target/daemon-transport-driver \
        -- smoke \
        --output "$result_dir/daemon-transport-smoke.json"

# Opt-in sustained daemon transport benchmark against already-running topology endpoints.
[positional-arguments]
daemon-transport-benchmark *benchmark_args:
    cargo run --locked --profile daemon-transport \
        -p nemo-relay-daemon-transport-benchmark \
        --target-dir target/daemon-transport-driver \
        -- load "$@"

# Deterministic provider used by the opt-in daemon transport benchmark.
[positional-arguments]
daemon-transport-benchmark-provider *provider_args:
    cargo run --locked --profile daemon-transport \
        -p nemo-relay-daemon-transport-benchmark \
        --target-dir target/daemon-transport-driver \
        -- provider "$@"

# Build the current size-optimized release and an isolated opt-level=3 candidate.
daemon-transport-benchmark-build-candidates:
    cargo build --locked --release -p nemo-relay-cli
    CARGO_PROFILE_RELEASE_OPT_LEVEL=3 cargo build --locked --release \
        --target-dir target/daemon-benchmark-opt3 \
        -p nemo-relay-cli

# --set [output_dir=<path>] [ci=true|false]
test-rust:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    "$BASH" "$NEMO_RELAY_REPO_ROOT/scripts/build_native_abi_fixtures.sh"
    junit_out=""
    test_config_root="$(mktemp -d)"
    cleanup_test_config_root() {
        rm -rf "$test_config_root"
    }
    trap cleanup_test_config_root EXIT

    host_os="$(uname -s 2>/dev/null || true)"
    is_windows=false
    case "${RUNNER_OS:-}:${OSTYPE:-}:$host_os" in
        Windows:*|*:msys*:*|*:win32*:*|*:*:MINGW*|*:*:MSYS*|*:*:CYGWIN*)
            is_windows=true
            ;;
    esac
    nextest_command=(cargo nextest)
    if [[ "$is_windows" == true ]]; then
        # Cargo's Windows job forbids breakaway. Run nextest directly so the lifecycle
        # tests can detach workers from their own jobs while testing cleanup normally.
        nextest_command=(cargo-nextest nextest)
        # Keep temporary child builds on the same toolchain as the workspace.
        if [[ -z "${RUSTUP_TOOLCHAIN:-}" ]]; then
            active_toolchain="$(rustup show active-toolchain)"
            export RUSTUP_TOOLCHAIN="${active_toolchain%% *}"
        fi
    fi
    native_test_config_path() {
        if [[ "$is_windows" == true ]] && command -v cygpath >/dev/null 2>&1; then
            cygpath -w "$1"
        else
            printf '%s\n' "$1"
        fi
    }

    xdg_config_home="$test_config_root/xdg"
    mkdir -p "$xdg_config_home"
    export XDG_CONFIG_HOME="$(native_test_config_path "$xdg_config_home")"
    system_config_home="$test_config_root/system"
    mkdir -p "$system_config_home"
    export NEMO_RELAY_TEST_SYSTEM_CONFIG_DIR="$(native_test_config_path "$system_config_home")"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    if [[ "$is_windows" == true ]]; then
        appdata_home="$test_config_root/AppData/Roaming"
        localappdata_home="$test_config_root/AppData/Local"
        mkdir -p "$appdata_home" "$localappdata_home"
        export APPDATA="$(native_test_config_path "$appdata_home")"
        export LOCALAPPDATA="$(native_test_config_path "$localappdata_home")"
    fi

    export_uv_python_runtime
    cd "$NEMO_RELAY_REPO_ROOT"
    nextest_args=(--locked --workspace --exclude nemo-relay-python --exclude nemo-relay-node --features nemo-relay/__skip-implicit-config,nemo-relay-cli/__test-cli-port-override,nemo-relay-cli/__skip-implicit-config --profile ci)
    run_windows_symlink_cleanup_test() {
        if [[ "$is_windows" != true ]]; then
            return
        fi
        local probe_status=0
        local python_executable
        python_executable="$(uv_python_executable)"
        "$python_executable" - <<'PY' || probe_status=$?
    import os
    import pathlib
    import tempfile

    try:
        with tempfile.TemporaryDirectory() as directory:
            root = pathlib.Path(directory)
            (root / "directory").mkdir()
            (root / "file").write_bytes(b"probe")
            for name, is_directory in (("directory", True), ("file", False)):
                os.symlink(root / name, root / f"{name}-link", target_is_directory=is_directory)
    except OSError as error:
        if getattr(error, "winerror", None) == 1314:  # ERROR_PRIVILEGE_NOT_HELD
            print(f"Windows symlink cleanup test remains ignored: {error}")
            raise SystemExit(77)
        raise
    PY
        case "$probe_status" in
            0)
                "${nextest_command[@]}" run --locked -p nemo-relay-cli --lib --features __test-cli-port-override,__skip-implicit-config --run-ignored only --profile default -E 'test(windows_managed_environment_cleanup_unlinks_directory_and_file_symlinks)'
                ;;
            77) ;; # The main run already reports this test as ignored.
            *) return "$probe_status" ;;
        esac
    }
    if is_true "{{ ci }}"; then
        coverage_out="$(prepare_artifact rust-workspace.lcov)"
        junit_out="$(prepare_artifact rust_junit_report.xml)"
        if rust_source_coverage_supported; then
            prepare_llvm_cov_workspace
        fi
        prepare_test_plugin_fixtures
        "${nextest_command[@]}" run "${nextest_args[@]}" --no-fail-fast
        run_windows_symlink_cleanup_test
        cp "$NEMO_RELAY_REPO_ROOT/target/nextest/ci/rust_junit_report.xml" "$junit_out"
        if rust_source_coverage_supported; then
            export_llvm_cov_lcov "$coverage_out" -- "${nextest_command[@]}" list "${nextest_args[@]}"
        fi
    else
        prepare_test_plugin_fixtures
        "${nextest_command[@]}" run "${nextest_args[@]}" --no-fail-fast
        run_windows_symlink_cleanup_test
    fi

# --set [output_dir=<path>] [ci=true|false]
test-python:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    pytest_cmd=(pytest)
    coverage_out=""
    junit_out=""
    rust_coverage_out=""
    cd "$NEMO_RELAY_REPO_ROOT"
    test_config_home="$(mktemp -d)"
    trap 'rm -rf "$test_config_home"' EXIT
    export XDG_CONFIG_HOME="$test_config_home"
    mkdir -p "$test_config_home/system"
    export NEMO_RELAY_TEST_SYSTEM_CONFIG_DIR="$test_config_home/system"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    export_uv_python_runtime
    if is_true "{{ ci }}"; then
        coverage_out="$(prepare_artifact python-coverage.xml)"
        junit_out="$(prepare_artifact python-junit.xml)"
        pytest_cmd+=(--cov=nemo_relay --cov=nemo_relay_plugin --cov-report term-missing --cov-report "xml:$coverage_out")
        pytest_cmd+=(--junit-xml "$junit_out")
        if rust_source_coverage_supported; then
            rust_coverage_out="$(prepare_artifact python-rust.lcov)"
            prepare_llvm_cov_workspace
        fi
    fi
    nextest_args=(--locked -p nemo-relay-python --features __skip-implicit-config --lib --profile ci)
    cargo nextest run "${nextest_args[@]}"
    python_executable="$(uv_python_executable)"
    sync_args=(--inexact --all-packages --no-install-project --no-install-package nemo-relay)
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        sync_args+=(--reinstall-package nemo-relay-plugin)
    fi
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    export_uv_python_runtime
    python_executable="$(project_python_executable)"
    configure_python_plugin_test_environment "$python_executable"
    if ! python_plugin_grpc_dependencies_supported "$python_executable"; then
        pytest_cmd+=(--ignore=python/tests/plugin)
    fi
    use_project_python_source "$python_executable"
    "$python_executable" -m maturin develop --features __skip-implicit-config --skip-install
    prepare_test_plugin_fixtures
    pytest_cmd+=(--durations=25)
    "$python_executable" -m "${pytest_cmd[@]}" --ignore=python/tests/integrations
    (cd examples/language-binding-plugin/python && uv run --locked --no-sync --package nemo-relay-python-language-binding-plugin-example --group test pytest)
    if is_true "{{ ci }}" && [[ -n "$rust_coverage_out" ]]; then
        export_llvm_cov_lcov "$rust_coverage_out" --package nemo-relay-python -- cargo nextest list "${nextest_args[@]}"
    fi

test-python-plugin:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    python_executable="$(uv_python_executable)"
    sync_args=(--inexact --all-packages --no-install-project --no-install-package nemo-relay)
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        sync_args+=(--reinstall-package nemo-relay-plugin)
    fi
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    python_executable="$(project_python_executable)"
    configure_python_plugin_test_environment "$python_executable"
    if ! python_plugin_grpc_dependencies_supported "$python_executable"; then
        exit 0
    fi
    "$python_executable" -m pytest \
        python/tests/plugin \
        --cov=nemo_relay_plugin \
        --cov-report term-missing \
        --cov-fail-under=95
    (cd examples/python-grpc-worker-plugin && uv run --locked --package nemo-relay-python-grpc-worker-example --group test --reinstall-package nemo-relay-plugin pytest)
    (cd examples/language-binding-plugin/python && uv run --locked --package nemo-relay-python-language-binding-plugin-example --group test --reinstall-package nemo-relay pytest)
    just test-python-plugin-e2e

test-python-plugin-e2e:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    python_executable="$(uv_python_executable)"
    sync_args=(--inexact --all-packages --no-install-project --no-install-package nemo-relay)
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        sync_args+=(--reinstall-package nemo-relay-plugin)
    fi
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    python_executable="$(project_python_executable)"
    configure_python_plugin_test_environment "$python_executable"
    if ! python_plugin_grpc_dependencies_supported "$python_executable"; then
        exit 0
    fi
    tmp="$(mktemp -d)"
    # Keep the worker lifecycle independent of ambient user and system plugins.
    export XDG_CONFIG_HOME="$tmp/user-config"
    export NEMO_RELAY_TEST_SYSTEM_CONFIG_DIR="$tmp/system-config"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    gateway_pid=""
    cleanup() {
        if [[ -n "$gateway_pid" ]]; then
            kill "$gateway_pid" 2>/dev/null || true
            wait "$gateway_pid" 2>/dev/null || true
        fi
        rm -rf "$tmp"
    }
    trap cleanup EXIT

    uv build --wheel --out-dir "$tmp/wheels" python/plugin
    worker_wheels=("$tmp"/wheels/nemo_relay_plugin-*.whl)
    "$python_executable" -c 'from pathlib import Path; import sys; print("nemo-relay-plugin @ " + Path(sys.argv[1]).resolve().as_uri())' "${worker_wheels[0]}" > "$tmp/worker-constraints.txt"
    cargo build -p nemo-relay-cli --features __skip-implicit-config
    cli="$NEMO_RELAY_REPO_ROOT/target/debug/nemo-relay"
    config="$tmp/gateway.toml"
    # Explicit --config paths must exist; plugin policy and state are sibling files.
    : > "$config"
    printf '[plugins.policy.defaults]\nattestation = "integrity_only"\n' > "$tmp/plugins.toml"
    manifest="$NEMO_RELAY_REPO_ROOT/examples/python-grpc-worker-plugin/relay-plugin.toml"
    PIP_FIND_LINKS="$tmp/wheels" PIP_CONSTRAINT="$tmp/worker-constraints.txt" NEMO_RELAY_PYTHON="$python_executable" \
        "$cli" --config "$config" plugins add "$manifest"
    "$cli" --config "$config" plugins enable examples.python_grpc_worker
    environment_ref="$("$python_executable" -c \
        'import json, sys; print(json.load(open(sys.argv[1]))["records"][0]["source"]["environment_ref"])' \
        "$tmp/.dynamic-plugins.json")"
    test -x "$environment_ref/bin/python" || test -x "$environment_ref/Scripts/python.exe"

    port="$("$python_executable" -c \
        'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()')"
    "$cli" --config "$config" --bind "127.0.0.1:$port" >"$tmp/gateway.log" 2>&1 &
    gateway_pid=$!
    gateway_ready_timeout_seconds=30
    gateway_ready_deadline=$((SECONDS + gateway_ready_timeout_seconds))
    ready=false
    while ((SECONDS < gateway_ready_deadline)); do
        if "$python_executable" -c \
            'import sys, urllib.request; urllib.request.urlopen(sys.argv[1], timeout=0.2).read()' \
            "http://127.0.0.1:$port/healthz" 2>/dev/null; then
            ready=true
            break
        fi
        if ! kill -0 "$gateway_pid" 2>/dev/null; then
            break
        fi
        sleep 0.1
    done
    if [[ "$ready" != true ]]; then
        if kill -0 "$gateway_pid" 2>/dev/null; then
            echo "gateway remained alive but did not become ready within ${gateway_ready_timeout_seconds}s" >&2
        else
            echo "gateway exited before becoming ready" >&2
        fi
        cat "$tmp/gateway.log"
        exit 1
    fi
    NEMO_RELAY_PYTHON_PLUGIN_TEST_ENVIRONMENT="$environment_ref" \
        cargo nextest run --locked -p nemo-relay-plugin-host --features __skip-implicit-config \
        --lib \
        -E 'test(python_worker_host_runtime_mark_and_mutated_request_round_trip) + test(python_worker_execution_codec_context_round_trips_host_codecs) + test(python_worker_message_limits_follow_plugin_defaults)' \
        --no-capture \
        --profile ci
    kill "$gateway_pid" 2>/dev/null || true
    wait "$gateway_pid" 2>/dev/null || true
    gateway_pid=""
    "$cli" --config "$config" plugins remove examples.python_grpc_worker
    test ! -e "$environment_ref"

test-python-langchain:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    pytest_cmd=(pytest)
    cd "$NEMO_RELAY_REPO_ROOT"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    uv sync --inexact --no-install-project --no-install-package nemo-relay --extra langchain --extra langchain-nvidia --extra langgraph --extra deepagents
    activate_project_venv
    export_uv_python_runtime
    python_executable="$(project_python_executable)"
    use_project_python_source "$python_executable"
    "$python_executable" -m maturin develop --features __skip-implicit-config --skip-install
    "$python_executable" -m "${pytest_cmd[@]}" \
        python/tests/integrations/deepagents_tests \
        python/tests/integrations/langchain_tests \
        python/tests/integrations/langgraph_tests

# --set [output_dir=<path>] [ci=true|false]
test-python-google-adk:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    pytest_cmd=(pytest)
    cd "$NEMO_RELAY_REPO_ROOT"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    if is_true "{{ ci }}"; then
        coverage_out="$(prepare_artifact python-google-adk-coverage.xml)"
        pytest_cmd+=(--cov --cov-config=python/tests/integrations/google_adk_tests/coverage.toml)
        pytest_cmd+=(--cov-report term-missing --cov-report "xml:$coverage_out")
    fi
    uv sync --inexact --no-install-project --no-install-package nemo-relay --extra google-adk --group google-adk-test
    activate_project_venv
    export_uv_python_runtime
    python_executable="$(project_python_executable)"
    use_project_python_source "$python_executable"
    "$python_executable" -m maturin develop --features __skip-implicit-config --skip-install
    "$python_executable" -m "${pytest_cmd[@]}" python/tests/integrations/google_adk_tests

# --set [output_dir=<path>] [ci=true|false]
test-go:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"

    target="release"
    flag="--release"
    go_test_cmd=(go test -v)
    go_ldflags=()
    if is_true "{{ ci }}"; then
        target="debug"
        flag=""
    fi
    coverage_out=""
    junit_out=""
    lib_dir="$NEMO_RELAY_REPO_ROOT/target/$target"
    host_os="$(uname -s 2>/dev/null || true)"
    is_windows=false
    case "${RUNNER_OS:-}:${OSTYPE:-}:$host_os" in
        Windows:*|*:msys*:*|*:win32*:*|*:*:MINGW*|*:*:MSYS*|*:*:CYGWIN*)
            is_windows=true
            ;;
    esac
    cd "$NEMO_RELAY_REPO_ROOT"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    cargo build $flag -p nemo-relay-ffi --features __skip-implicit-config
    prepare_test_plugin_fixtures

    if [[ "$is_windows" == true ]]; then
        export CC=clang
        export CXX=clang++
        # Go's Windows linker checks -extldflags before deciding whether to
        # inject a GNU linker script; CGO_LDFLAGS is too late for that check.
        go_ldflags+=(-extldflags=-fuse-ld=lld)
        if command -v cygpath >/dev/null 2>&1; then
            export PATH="$(cygpath -u "$lib_dir"):$PATH"
        else
            export PATH="$lib_dir:$PATH"
        fi
    fi
    if [[ "$OSTYPE" == "darwin"* ]]; then
        export CGO_LDFLAGS="-Wl,-w ${CGO_LDFLAGS:-}"
    fi
    export CGO_LDFLAGS="-L$lib_dir ${CGO_LDFLAGS:-}"
    export LD_LIBRARY_PATH="$lib_dir${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
    export DYLD_LIBRARY_PATH="$lib_dir${DYLD_LIBRARY_PATH:+:${DYLD_LIBRARY_PATH}}"
    if is_true "{{ ci }}"; then
        coverage_out="$(prepare_artifact go-coverage.xml)"
        junit_out="$(prepare_artifact go-junit.xml)"
        # Include the root binding package when shorthand-package tests exercise
        # its delegated implementation so those calls are represented once the
        # per-package profiles are merged.
        go_test_cmd+=(-coverprofile=coverage.out -coverpkg=./...)
        if [[ "$is_windows" == true ]]; then
            go_ldflags+=(-w)
        fi
        go install github.com/jstemmer/go-junit-report/v2@latest
        go install github.com/boumenot/gocover-cobertura@latest
        prepend_go_bin_to_path
    fi
    if [[ "$is_windows" == true ]]; then
        echo "Go Windows linker: RUNNER_OS=${RUNNER_OS:-} OSTYPE=${OSTYPE:-} uname=$host_os CC=$CC CXX=$CXX ldflags=${go_ldflags[*]:-}"
    fi
    if [[ ${#go_ldflags[@]} -gt 0 ]]; then
        go_test_cmd+=("-ldflags=${go_ldflags[*]}")
    fi
    go_test_cmd+=(./...)
    cd "$NEMO_RELAY_REPO_ROOT/go/nemo_relay"
    if is_true "{{ ci }}"; then
        # Work-around /dev/stderr not being available on Windows
        "${go_test_cmd[@]}" 2>&1 | tee >(cat >&2) | go-junit-report -set-exit-code > "$junit_out"
        gocover-cobertura < coverage.out > "$coverage_out"
    else
        "${go_test_cmd[@]}"
    fi

# --set [output_dir=<path>] [ci=true|false]
test-node:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    coverage_out=""
    junit_out=""
    rust_coverage_out=""
    cd "$NEMO_RELAY_REPO_ROOT"
    # Keep temporary plugin builds on the same toolchain as coverage reports.
    if [[ -z "${RUSTUP_TOOLCHAIN:-}" ]]; then
        active_toolchain="$(rustup show active-toolchain)"
        export RUSTUP_TOOLCHAIN="${active_toolchain%% *}"
    fi
    test_config_home="$(mktemp -d)"
    trap 'rm -rf "$test_config_home"' EXIT
    export XDG_CONFIG_HOME="$test_config_home"
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    if is_true "{{ ci }}"; then
        coverage_out="$(prepare_artifact node-coverage.xml)"
        junit_out="$(prepare_artifact node-junit.xml)"
        if rust_source_coverage_supported; then
            rust_coverage_out="$(prepare_artifact node-rust.lcov)"
            prepare_llvm_cov_workspace
        fi
    fi
    nextest_args=(--locked -p nemo-relay-node --features __skip-implicit-config --lib --profile ci)
    cargo nextest run "${nextest_args[@]}"
    npm install --workspace=nemo-relay-node --ignore-scripts
    if is_true "{{ ci }}"; then
        npm run coverage --workspace=nemo-relay-node
        cp crates/node/coverage/cobertura-coverage.xml "$coverage_out"
        cp crates/node/junit.xml "$junit_out"
        cd "$NEMO_RELAY_REPO_ROOT"
        if [[ -n "$rust_coverage_out" ]]; then
            export_llvm_cov_lcov "$rust_coverage_out" --package nemo-relay-node -- cargo nextest list "${nextest_args[@]}"
        fi
    else
        npm test --workspace=nemo-relay-node
    fi
    npm test --workspace=nemo-relay-node-language-binding-plugin-example

# run each checked plugin authoring example from its own project directory
test-plugin-examples:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    export NEMO_RELAY_TEST_SKIP_IMPLICIT_CONFIG=1
    (cd examples/rust-native-plugin && cargo nextest run --config-file "$NEMO_RELAY_REPO_ROOT/.config/nextest.toml" --profile ci)
    (cd examples/rust-grpc-worker-plugin && cargo nextest run --config-file "$NEMO_RELAY_REPO_ROOT/.config/nextest.toml" --profile ci)
    (cd examples/language-binding-plugin/rust && cargo nextest run --config-file "$NEMO_RELAY_REPO_ROOT/.config/nextest.toml" --profile ci)
    python_executable="$(uv_python_executable)"
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        (cd examples/python-grpc-worker-plugin && uv run --locked --package nemo-relay-python-grpc-worker-example --group test --reinstall-package nemo-relay-plugin pytest)
    fi
    sync_args=(--locked --inexact --all-packages --group test --no-install-project --no-install-package nemo-relay)
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    python_executable="$(project_python_executable)"
    use_project_python_source "$python_executable"
    "$python_executable" -m maturin develop --features __skip-implicit-config --skip-install
    (cd examples/language-binding-plugin/python && uv run --locked --no-sync --package nemo-relay-python-language-binding-plugin-example --group test pytest)
    npm test --workspace=nemo-relay-node-language-binding-plugin-example

# --set [ci=true|false]
test-openclaw:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    if is_true "{{ ci }}"; then
        npm ci --ignore-scripts
        npm run build-debug --workspace=nemo-relay-node
    else
        npm install --ignore-scripts
    fi
    npm run typecheck --workspace=nemo-relay-openclaw
    npm test --workspace=nemo-relay-openclaw
    npm run test:live --workspace=nemo-relay-openclaw
    npm run pack:check --workspace=nemo-relay-openclaw

# --set [ci=true|false]
test-pi:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    if is_true "{{ ci }}"; then
        npm ci --ignore-scripts
    else
        npm install --ignore-scripts
    fi
    # No `build-debug` for the Node binding: the pi extension is a sidecar HTTP
    # client and loads no native addon, so nothing here depends on it.
    npm run typecheck --workspace=nemo-relay-pi
    npm test --workspace=nemo-relay-pi
    node_modules/.bin/tsc -p crates/cli/src/daemon/managed/pi_extension/tsconfig.json --noEmit
    node --test crates/cli/tests/managed_pi_extension_tests.mjs

# --set [output_dir=<path>] [ci=true|false]
test-all: test-rust test-python test-python-langchain test-python-google-adk test-go test-node test-openclaw test-pi

# Print a SemVer version in the PEP 440 form used for Python packages.
semver-to-pep440 version:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    semver_to_pep440 {{ quote(version) }}

# Print the crates published to crates.io, one per line.
published-cargo-packages:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    cd "$NEMO_RELAY_REPO_ROOT"
    published_cargo_packages

# Print and validate the native ABI contract and its package release metadata.
native-abi-contract:
    #!/usr/bin/env bash
    uv run --no-sync python scripts/native_abi_contract.py

# [version] or --set ref_name=<version>
set-version version="":
    #!/usr/bin/env bash
    {{ bash_helpers }}
    version="{{ version }}"
    if [[ -z "$version" ]]; then
        version="{{ ref_name }}"
    fi
    if [[ -z "$version" ]]; then
        echo "Error: version is required for set-version" >&2
        exit 1
    fi
    cd "$NEMO_RELAY_REPO_ROOT"
    set_project_version "$version"

# Set only the Cargo workspace version for release artifact builds.
# [version] or --set ref_name=<version>
set-cargo-version version="":
    #!/usr/bin/env bash
    {{ bash_helpers }}
    version="{{ version }}"
    if [[ -z "$version" ]]; then
        version="{{ ref_name }}"
    fi
    if [[ -z "$version" ]]; then
        echo "Error: version is required for set-cargo-version" >&2
        exit 1
    fi
    cd "$NEMO_RELAY_REPO_ROOT"
    set_cargo_workspace_version "$version"

# --set [output_dir=<path>] [ref_name=<name>]
package-rust:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir crates)"
    package_target_dir="$(mktemp -d)"
    cleanup_package_target_dir() {
        rm -rf "$package_target_dir"
    }
    trap cleanup_package_target_dir EXIT
    ref_name={{ quote(ref_name) }}
    if [[ -n "$ref_name" ]]; then
        echo "Using explicit version $ref_name"
        set_cargo_workspace_version "$ref_name"
    fi
    while IFS= read -r package; do
        cargo_package_config=()
        cargo_package_args=(--locked --package "$package" --target-dir "$package_target_dir")
        if [[ -n "$ref_name" ]]; then
            cargo_package_args+=(--allow-dirty)
        fi
        case "$package" in
            nemo-relay-plugin-host)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-runtime.path="crates/runtime"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-resource-metrics.path="crates/resource-metrics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-observability.path="crates/observability"')
                ;;
            nemo-relay-logging)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                ;;
            nemo-relay-diagnostics)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                ;;
            nemo-relay-observability)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                ;;
            nemo-relay|nemo-relay-runtime)
                if [[ "$package" == nemo-relay ]]; then
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-builtins.path="crates/builtins"')
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-adaptive.path="crates/adaptive"')
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-pii-redaction.path="crates/pii-redaction"')
                fi
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-host.path="crates/plugin-host"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                if [[ "$package" != nemo-relay-runtime ]]; then
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-runtime.path="crates/runtime"')
                fi
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-observability.path="crates/observability"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-resource-metrics.path="crates/resource-metrics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                ;;
            nemo-relay-adaptive)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-host.path="crates/plugin-host"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-runtime.path="crates/runtime"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-observability.path="crates/observability"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-resource-metrics.path="crates/resource-metrics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                ;;
            nemo-relay-worker)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                ;;
            nemo-relay-resource-metrics|nemo-relay-model-pricing)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                ;;
            nemo-relay-plugin|nemo-relay-codecs|nemo-relay-worker-proto)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                if [[ "$package" == nemo-relay-plugin ]]; then
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                fi
                ;;
            nemo-relay-pii-redaction)
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-host.path="crates/plugin-host"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-runtime.path="crates/runtime"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-observability.path="crates/observability"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-resource-metrics.path="crates/resource-metrics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                ;;
            nemo-relay-builtins|nemo-relay-ffi|nemo-relay-cli)
                if [[ "$package" != nemo-relay-builtins ]]; then
                    cargo_package_config+=(--config 'patch.crates-io.nemo-relay-builtins.path="crates/builtins"')
                fi
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-codecs.path="crates/codecs"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-diagnostics.path="crates/diagnostics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-logging.path="crates/logging"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-host.path="crates/plugin-host"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-runtime.path="crates/runtime"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-types.path="crates/types"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-worker-proto.path="crates/worker-proto"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-observability.path="crates/observability"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-resource-metrics.path="crates/resource-metrics"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-model-pricing.path="crates/model-pricing"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin.path="crates/plugin"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-plugin-abi.path="crates/plugin-abi"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-adaptive.path="crates/adaptive"')
                cargo_package_config+=(--config 'patch.crates-io.nemo-relay-pii-redaction.path="crates/pii-redaction"')
                ;;
        esac
        if ((${#cargo_package_config[@]} == 0)); then
            cargo package "${cargo_package_args[@]}"
        else
            cargo package "${cargo_package_args[@]}" "${cargo_package_config[@]}"
        fi
    done < <(published_cargo_packages)
    find "$package_target_dir/package" -maxdepth 1 -type f -name '*.crate' -exec cp {} "$package_dir"/ \;
    shopt -s nullglob
    packages=("$package_dir"/*.crate)
    if ((${#packages[@]} == 0)); then
        echo "Error: No Cargo package artifacts found in $package_dir"
        exit 1
    fi

# --set [output_dir=<path>] [ref_name=<name>] [package_profile=release|dev] [node_metapackage=true|false]
package-node:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    # If `ref_name` is empty, append the current short HEAD SHA to the version.
    # If `ref_name` is set, write it as the exact package version before packing.
    node_platform="{{ node_platform }}"
    node_target="{{ node_target }}"
    node_build_strategy="{{ node_build_strategy }}"
    python_executable="python"
    if ! command -v "$python_executable" >/dev/null 2>&1; then
        python_executable="python3"
    fi
    output_dir="{{ output_dir }}"
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir npm)"
    if [[ -z "{{ ref_name }}" ]]; then
        sha="$(head_git_sha)"
        version="$(read_npm_package_version crates/node/package.json)"
        package_version="${version}+${sha}"
        echo "Non-release build: appending commit hash to version"
        set_npm_package_version crates/node/package.json package-lock.json "$package_version" crates/node
        set_npm_package_dependency_version integrations/openclaw/package.json package-lock.json integrations/openclaw nemo-relay-node "$package_version"
        set_npm_package_dependency_version examples/language-binding-plugin/node/package.json package-lock.json examples/language-binding-plugin/node nemo-relay-node "$package_version"
    else
        package_version="{{ ref_name }}"
        echo "Using explicit version {{ ref_name }}"
        set_npm_package_version crates/node/package.json package-lock.json "$package_version" crates/node
        set_npm_package_dependency_version integrations/openclaw/package.json package-lock.json integrations/openclaw nemo-relay-node "$package_version"
        set_npm_package_dependency_version examples/language-binding-plugin/node/package.json package-lock.json examples/language-binding-plugin/node nemo-relay-node "$package_version"
    fi
    case "{{ package_profile }}" in
        release) build_args=(build --) ;;
        dev) build_args=(build-debug --) ;;
        *) echo "Error: package_profile must be release or dev" >&2; exit 1 ;;
    esac
    case "$node_build_strategy" in
        native)
            if [[ -n "$node_target" ]]; then
                build_args+=(--target "$node_target")
            fi
            ;;
        napi-cross)
            # Links against glibc 2.17.
            if [[ "$node_target" != *-unknown-linux-gnu ]]; then
                echo "Error: node_build_strategy=napi-cross needs a *-unknown-linux-gnu node_target, got '$node_target'" >&2
                exit 1
            fi
            build_args+=(--use-napi-cross --target "$node_target")
            ;;
        zig)
            # Zig is provided by the uv.lock `ziglang` entry.
            if [[ "$node_target" != *-unknown-linux-musl ]]; then
                echo "Error: node_build_strategy=zig needs a *-unknown-linux-musl node_target, got '$node_target'" >&2
                exit 1
            fi
            uv sync --inexact --no-install-project --no-install-package nemo-relay --no-default-groups --group dev
            activate_project_venv
            prepend_ziglang_to_path "$(project_python_executable)"
            build_args+=(--cross-compile --target "$node_target")
            ;;
        *)
            echo "Error: unsupported node_build_strategy '$node_build_strategy' (native, napi-cross, zig)" >&2
            exit 1
            ;;
    esac
    npm install --workspace=nemo-relay-node --ignore-scripts
    npm run --workspace=nemo-relay-node "${build_args[@]}"
    if [[ -z "$node_platform" ]]; then
        case "$(uname -s)-$(uname -m)" in
            Linux-x86_64) node_platform="linux-amd64" ;;
            Linux-aarch64|Linux-arm64) node_platform="linux-arm64" ;;
            Darwin-arm64) node_platform="macos-arm64" ;;
            MINGW*|MSYS*|CYGWIN*)
                if [[ "$(uname -m)" == "aarch64" || "$(uname -m)" == "arm64" ]]; then
                    node_platform="windows-arm64"
                else
                    node_platform="windows-amd64"
                fi
                ;;
            *)
                echo "Error: unsupported Node package host $(uname -s)/$(uname -m)" >&2
                exit 1
                ;;
        esac
    fi
    package_args=(
        --node-dir crates/node
        --platform "$node_platform"
        --version "$package_version"
        --output-dir "$package_dir"
    )
    if [[ "$node_platform" == "linux-amd64" ]] || is_true "{{ node_metapackage }}"; then
        package_args+=(--metapackage)
    fi
    "$python_executable" scripts/package-node-bin.py "${package_args[@]}"
    shopt -s nullglob
    packages=("$package_dir"/*.tgz)
    if ((${#packages[@]} == 0)); then
        echo "Error: No npm packages found in $package_dir"
        exit 1
    fi

# --set [output_dir=<path>] [ref_name=<name>] [ci=true|false]
package-openclaw:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    # If `ref_name` is empty, append the current short HEAD SHA to the version.
    # If `ref_name` is set, write it as the exact package version before packing.
    output_dir="{{ output_dir }}"
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir openclaw)"
    if [[ -z "{{ ref_name }}" ]]; then
        sha="$(head_git_sha)"
        version="$(read_npm_package_version integrations/openclaw/package.json)"
        package_version="${version}+${sha}"
        echo "Non-release build: appending commit hash to version"
        set_npm_package_version crates/node/package.json package-lock.json "$package_version" crates/node
        set_npm_package_version integrations/openclaw/package.json package-lock.json "$package_version" integrations/openclaw
        set_npm_package_dependency_version integrations/openclaw/package.json package-lock.json integrations/openclaw nemo-relay-node "$package_version"
        set_npm_package_dependency_version examples/language-binding-plugin/node/package.json package-lock.json examples/language-binding-plugin/node nemo-relay-node "$package_version"
    else
        package_version="{{ ref_name }}"
        echo "Using explicit version {{ ref_name }}"
        set_npm_package_version crates/node/package.json package-lock.json "$package_version" crates/node
        set_npm_package_version integrations/openclaw/package.json package-lock.json "$package_version" integrations/openclaw
        set_npm_package_dependency_version integrations/openclaw/package.json package-lock.json integrations/openclaw nemo-relay-node "$package_version"
        set_npm_package_dependency_version examples/language-binding-plugin/node/package.json package-lock.json examples/language-binding-plugin/node nemo-relay-node "$package_version"
    fi
    npm install --workspace=nemo-relay-node --workspace=nemo-relay-openclaw --ignore-scripts
    if is_true "{{ ci }}"; then
        npm run build-debug --workspace=nemo-relay-node
    else
        npm run build --workspace=nemo-relay-node
    fi
    npm pack --workspace=nemo-relay-openclaw --pack-destination "$package_dir"
    shopt -s nullglob
    packages=("$package_dir"/*.tgz)
    if ((${#packages[@]} == 0)); then
        echo "Error: No OpenClaw npm packages found in $package_dir"
        exit 1
    fi

# --set [output_dir=<path>] [ref_name=<name>] [package_profile=release|dev]
package-python:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    # An explicit ref_name is synced into the Cargo workspace version first,
    # so the compiled extension embeds the same version reported by the
    # Python package, then written into pyproject.toml using PEP 440 before
    # building a platform wheel.
    output_dir="{{ output_dir }}"
    linux_glibc_version="{{ linux_glibc_version }}"
    export_uv_python_runtime
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir wheels)"
    sync_args=(--no-install-project --no-install-package nemo-relay)
    if [[ "{{ package_profile }}" == dev ]]; then
        sync_args+=(--frozen --no-default-groups --group dev)
    fi
    uv sync --inexact "${sync_args[@]}"
    activate_project_venv
    if [[ -z "{{ ref_name }}" ]]; then
        sha="$(head_git_sha)"
        version="$(read_workspace_version)"
        echo "Non-release build: appending commit hash to version"
        set_python_package_version "${version}+${sha}" true
    else
        echo "Using explicit version {{ ref_name }}"
        set_cargo_workspace_version "{{ ref_name }}"
        set_python_package_version "{{ ref_name }}" true
    fi
    case "{{ package_profile }}" in
        release)
            build_args=(--release)
            while IFS= read -r -d '' arg; do
                build_args+=("$arg")
            done < <(python_wheel_build_args)
            ;;
        dev)
            # Host execution needs an installable wheel, without release cross-compilation.
            build_args=(--locked --profile dev --interpreter "$(project_python_executable)")
            ;;
        *) echo "Error: package_profile must be release or dev" >&2; exit 1 ;;
    esac
    maturin build "${build_args[@]}" --out "$package_dir"
    shopt -s nullglob
    wheels=("$package_dir"/*.whl)
    if ((${#wheels[@]} == 0)); then
        echo "Error: No wheels found in $package_dir"
        exit 1
    fi

# --set [output_dir=<path>] [ref_name=<name>]
package-python-sdist:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    export_uv_python_runtime
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir sdists)"
    sync_args=(--no-install-project --no-install-package nemo-relay)
    uv sync --inexact "${sync_args[@]}"
    activate_project_venv
    if [[ -z "{{ ref_name }}" ]]; then
        sha="$(head_git_sha)"
        version="$(read_workspace_version)"
        echo "Non-release build: appending commit hash to version"
        set_python_package_version "${version}+${sha}" true
    else
        echo "Using explicit version {{ ref_name }}"
        set_python_package_version "{{ ref_name }}" true
    fi
    maturin sdist --out "$package_dir"
    shopt -s nullglob
    sdists=("$package_dir"/nemo_relay-*.tar.gz)
    if ((${#sdists[@]} == 0)); then
        echo "Error: No nemo-relay source distributions found in $package_dir"
        exit 1
    fi

# --set [output_dir=<path>] [ref_name=<name>]
package-python-plugin:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    output_dir="{{ output_dir }}"
    ref_name={{ quote(ref_name) }}
    cd "$NEMO_RELAY_REPO_ROOT"
    package_dir="$(prepare_package_dir plugin-wheels)"
    python_executable="$(uv_python_executable)"
    # This pure-Python wheel does not import grpcio while building. On Windows
    # ARM64, python_plugin_sync_args excludes the unavailable runtime packages.
    sync_args=(--inexact --no-install-project)
    if python_plugin_grpc_dependencies_supported "$python_executable"; then
        sync_args+=(--package nemo-relay-plugin)
    fi
    while IFS= read -r -d '' arg; do
        sync_args+=("$arg")
    done < <(python_plugin_sync_args "$python_executable")
    uv sync "${sync_args[@]}"
    activate_project_venv
    if [[ -z "$ref_name" ]]; then
        sha="$(head_git_sha)"
        version="$(read_workspace_version)"
        echo "Non-release build: appending commit hash to version"
        set_python_plugin_package_version "${version}+${sha}"
    else
        echo "Using explicit version $ref_name"
        set_python_plugin_package_version "$ref_name"
    fi
    uv build --wheel --package nemo-relay-plugin --out-dir "$package_dir"
    shopt -s nullglob
    wheels=("$package_dir"/*.whl)
    if ((${#wheels[@]} == 0)); then
        echo "Error: No Python plugin wheels found in $package_dir"
        exit 1
    fi
    python_executable="$(project_python_executable)"
    "$python_executable" scripts/validate_python_plugin_package.py

# Package a prebuilt CLI binary for PyPI.
package-cli-bin binary target version package_dir:
    #!/usr/bin/env bash
    set -euo pipefail
    cd "$NEMO_RELAY_REPO_ROOT"
    args=(
        --binary "{{ binary }}"
        --target "{{ target }}"
        --version "{{ version }}"
        --output-dir "{{ package_dir }}"
    )
    uv run --no-project python scripts/package-cli-bin.py "${args[@]}"