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()

# Skip dependency synchronization when the project environment is already fully synced.
no_uv := "false"
# When set, versioning and packaging targets use this exact release version.
ref_name := ""
# Linux wheel artifacts target this minimum glibc version for compatibility.
linux_glibc_version := "2.17"

python_projects := ". sdk/python/nemo-fabric sdk/python/nemo-fabric-runtime sdk/python/nemo-fabric-collector adapter-contract/python adapters/python/common adapters/python/claude adapters/python/codex adapters/python/deepagents adapters/python/hermes adapters/python/mini-swe-agent adapters/python/nooa adapters/python/remote-agent"

python_packages := "sdk/python/nemo-fabric sdk/python/nemo-fabric-runtime sdk/python/nemo-fabric-collector adapter-contract/python adapters/python/common adapters/python/claude adapters/python/codex adapters/python/deepagents adapters/python/hermes adapters/python/mini-swe-agent adapters/python/nooa adapters/python/remote-agent"

# List Python package paths, one per line.
python-package-paths:
    @printf '%s\n' {{ python_packages }}

bash_helpers := '''
set -euo pipefail

uv_python_executable() {
    (
        cd "$REPO_ROOT"
        uv python find
    )
}

activate_project_venv() {
    local venv_dir="$REPO_ROOT/.venv"
    local venv_bin=""
    if [[ -x "$REPO_ROOT/.venv/bin/python" ]]; then
        venv_bin="$REPO_ROOT/.venv/bin"
    elif [[ -x "$REPO_ROOT/.venv/Scripts/python.exe" ]]; then
        venv_bin="$REPO_ROOT/.venv/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
}

prepend_ziglang_to_path() {
    local python_executable="$1"
    local zig_dir=""
    zig_dir="$("$python_executable" - <<'PY'
from pathlib import Path
import importlib.util

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"
if not zig.exists():
    raise SystemExit(f"ERROR: expected zig binary at {zig}")

print(zig.parent)
PY
    )"
    export PATH="$zig_dir:$PATH"
}

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|CYGWIN*|MINGW*|MSYS*)
            printf '%s\0' --compatibility pypi
            ;;
        *)
            echo "ERROR: unsupported OS for wheels: $os_name" >&2
            exit 1
            ;;
    esac
}

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 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_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")
if not re.fullmatch(
    r"\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)(?:\.\d+)?)?"
    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?",
    version,
):
    raise SystemExit(
        f"Unsupported release version '{version}'; use 0.1.0 or a supported "
        "prerelease such as 0.1.0-rc.1"
    )

path = Path("Cargo.toml")
text = path.read_text()
section = ""
output = []
changed = []
found_workspace_version = False
found_nemo_fabric_core = False

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":
        updated, count = re.subn(
            r'^(nemo-fabric-core\s*=\s*\{[^}]*\bversion\s*=\s*")([^"]+)(".*)$',
            rf"\g<1>{version}\g<3>",
            line,
        )
        if count == 1:
            found_nemo_fabric_core = True
            if updated != line:
                changed.append("workspace.dependencies.nemo-fabric-core.version")

    output.append(updated)

missing = []
if not found_workspace_version:
    missing.append("workspace.package.version")
if not found_nemo_fabric_core:
    missing.append("workspace.dependencies.nemo-fabric-core.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)"
    # Resolve dependencies so Cargo refreshes workspace package versions in Cargo.lock.
    if ! cargo metadata --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:
        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 Fabric workspace packages")
if mismatched:
    raise SystemExit(
        f"Cargo workspace packages do not all resolve to {version}: {', '.join(mismatched)}"
    )
print(f"Cargo metadata resolves {checked} Fabric workspace packages to {version}")
PY
    then
        rm -f "$metadata_file"
        return 1
    fi
    rm -f "$metadata_file"
}

set_python_project_versions() {
    local version=""
    local python_executable=""
    version="$(semver_to_pep440 "$1")"
    python_executable="$(uv_python_executable)"
    "$python_executable" scripts/ci/set_python_project_versions.py "$version"
}

set_typescript_project_version() {
    local version="$1"
    local python_executable=""
    python_executable="$(uv_python_executable)"
    "$python_executable" scripts/ci/set_typescript_project_version.py "$version"
}

set_project_version() {
    local version="$1"
    set_cargo_workspace_version "$version"
    set_python_project_versions "$version"
    set_typescript_project_version "$version"
}
'''

# Remove local Rust, Python, and TypeScript build and test artifacts.
clean:
    #!/usr/bin/env bash
    set -euo pipefail
    cargo clean
    rm -rf \
        .coverage \
        build \
        dist \
        adapter-contract/python/build \
        adapter-contract/python/dist \
        docs/node_modules \
        adapter-contract/typescript/node_modules \
        adapter-contract/typescript/dist \
        adapters/typescript/node_modules \
        adapters/typescript/common/dist \
        adapters/typescript/pi/dist \
        adapters/typescript/opencode/dist \
        adapters/python/*/build \
        adapters/python/*/dist \
        sdk/python/*/build \
        sdk/python/*/dist \
        adapter-contract/typescript/*.tgz \
        adapters/typescript/common/*.tgz \
        adapters/typescript/pi/*.tgz \
        adapters/typescript/opencode/*.tgz
    find . \
        \( -path './.venv' -o -path './.git' \) -prune -o \
        -type d \( \
            -name .pytest_cache -o \
            -name __pycache__ -o \
            -name '*.egg-info' \
        \) -prune -exec rm -rf {} +
    find . \
        \( -path './.venv' -o -path './.git' \) -prune -o \
        -type f \( -name '*.so' -o -name coverage.xml \) -exec rm -f {} +

# Build the Rust workspace using the locked dependency set.
build-rust:
    cargo build --workspace --locked
    cargo install --path crates/fabric-cli --locked --force

# Build and install the Python distribution and native runtime in the project environment.
# --set [no_uv=true|false]
build-python:
    #!/usr/bin/env bash
    set -euo pipefail
    if [[ "{{ no_uv }}" == "true" ]]; then
        editable_projects=()
        for project in {{ python_packages }}; do
            editable_projects+=(--editable "$project")
        done
        uv pip install --python .venv/bin/python --no-deps --reinstall \
            --group adapters \
            "${editable_projects[@]}"
    else
        uv sync --no-default-groups --group adapters --group collector \
            --reinstall-package nemo-fabric \
            --reinstall-package nemo-fabric-collector \
            --reinstall-package nemo-fabric-runtime
    fi

# Install the TypeScript adapter contract dependencies from its lockfile.
install-typescript-contract:
    npm ci --prefix adapter-contract/typescript --ignore-scripts

# Install the TypeScript adapter workspace dependencies from its lockfile.
install-typescript-adapters:
    npm ci --prefix adapters/typescript --workspaces --include-workspace-root --ignore-scripts

# Install the Pi adapter and its pinned SDK harness for source development.
install-typescript-pi: install-typescript-contract
    npm ci --prefix adapters/typescript --workspace nemo-fabric-adapters-pi --include-workspace-root --ignore-scripts

# Install the OpenCode adapter and its pinned SDK harness for source development.
install-typescript-opencode: install-typescript-contract
    npm ci --prefix adapters/typescript --workspace nemo-fabric-adapters-opencode --include-workspace-root --ignore-scripts

# Install every maintained TypeScript package.
install-typescript: install-typescript-contract install-typescript-adapters

# Install the Hermes Agent into the Fabric virtualenv for local development
# and testing.
# Hermes Agent no longer publishes a PyPI package, so we need to install it
# from source.
# The documented https://hermes-agent.nousresearch.com/install.sh script is
# tied directly to Python 3.11, we also want to ensure that we are installing
# into our Fabric virtualenv
# 29112bef099274229cadff79cdff7bf7b99c4b77 aligns with Hermes Agent v0.21.0.
# metadata-propagate.patch forwards OpenAI request metadata into Hermes Relay
# turn metadata. Remove it when the pinned Hermes revision includes that behavior.
# Install the pinned Hermes Agent source with Fabric Relay metadata propagation.
install-hermes-agent:
    #!/usr/bin/env bash
    set -euo pipefail
    hermes_commit="29112bef099274229cadff79cdff7bf7b99c4b77"
    hermes_checkout="$REPO_ROOT/external/hermes-agent"
    hermes_patch="$REPO_ROOT/adapters/python/hermes/metadata-propagate.patch"
    hermes_diff_pathspec=()

    if [[ ! -f "$hermes_patch" ]]; then
        echo "ERROR: Hermes Agent patch not found: $hermes_patch" >&2
        exit 1
    fi

    if [[ -e "$hermes_checkout" && ! -d "$hermes_checkout/.git" ]]; then
        echo "ERROR: expected a Git checkout at $hermes_checkout" >&2
        exit 1
    fi
    if [[ ! -d "$hermes_checkout/.git" ]]; then
        mkdir -p "$(dirname "$hermes_checkout")"
        git init --quiet "$hermes_checkout"
        git -C "$hermes_checkout" remote add origin https://github.com/NousResearch/hermes-agent.git
    fi
    # This revision contains two contributor metadata paths that differ only by
    # case. Ignore the resulting false modification on case-insensitive filesystems.
    if [[ "$(git -C "$hermes_checkout" config --bool core.ignorecase)" == "true" ]]; then
        hermes_diff_pathspec=(-- . ":(exclude)contributors/emails/agent@Agents-Mac-mini.local")
    fi
    hermes_head="$(git -C "$hermes_checkout" rev-parse --verify HEAD 2>/dev/null || true)"
    if [[ "$hermes_head" != "$hermes_commit" ]]; then
        if [[ -n "$hermes_head" ]] && { ! git -C "$hermes_checkout" diff --quiet "${hermes_diff_pathspec[@]}" || ! git -C "$hermes_checkout" diff --cached --quiet; }; then
            echo "ERROR: Hermes Agent checkout has tracked changes at an unpinned revision: $hermes_checkout" >&2
            exit 1
        fi
        git -C "$hermes_checkout" fetch --depth 1 origin "$hermes_commit"
        git -C "$hermes_checkout" checkout --quiet --detach FETCH_HEAD
    fi
    if ! git -C "$hermes_checkout" diff --cached --quiet; then
        echo "ERROR: Hermes Agent checkout has staged changes: $hermes_checkout" >&2
        exit 1
    fi
    if git -C "$hermes_checkout" diff --quiet "${hermes_diff_pathspec[@]}"; then
        if ! git -C "$hermes_checkout" apply --check "$hermes_patch"; then
            echo "ERROR: Hermes Agent patch does not apply to $hermes_commit" >&2
            exit 1
        fi
        git -C "$hermes_checkout" apply "$hermes_patch"
    else
        # Validate the already-applied patch without depending on Git's
        # platform-specific diff serialization.
        patch_reversed=false
        restore_hermes_patch() {
            if [[ "$patch_reversed" == true ]]; then
                git -C "$hermes_checkout" apply "$hermes_patch" || \
                    echo "ERROR: failed to restore Hermes Agent metadata patch" >&2
            fi
        }
        trap restore_hermes_patch EXIT
        if ! git -C "$hermes_checkout" apply --reverse --check "$hermes_patch"; then
            echo "ERROR: Hermes Agent checkout has changes other than metadata-propagate.patch: $hermes_checkout" >&2
            exit 1
        fi
        git -C "$hermes_checkout" apply --reverse "$hermes_patch"
        patch_reversed=true
        if ! git -C "$hermes_checkout" diff --quiet "${hermes_diff_pathspec[@]}"; then
            echo "ERROR: Hermes Agent checkout has changes other than metadata-propagate.patch: $hermes_checkout" >&2
            exit 1
        fi
        git -C "$hermes_checkout" apply "$hermes_patch"
        patch_reversed=false
        trap - EXIT
    fi
    uv sync --inexact --reinstall-package hermes-agent

# Build the TypeScript contract and adapter packages using their locked dependencies.
build-typescript: install-typescript
    npm run build --prefix adapter-contract/typescript
    npm run build --prefix adapters/typescript

# Generate the TypeScript adapter contract from the committed JSON Schemas.
generate-typescript-contract: install-typescript
    npm run generate --prefix adapter-contract/typescript

# Verify the TypeScript contract and adapter package tarballs.
pack-typescript: install-typescript
    npm run pack:check --prefix adapter-contract/typescript
    npm run pack:check --prefix adapters/typescript

# Generate the JSON Schema files from the Rust configuration types.
schemas:
    cargo run -p nemo-fabric-core --example generate-schemas -- schemas

# Build all supported language packages.
build-all: build-rust build-python schemas build-typescript

# Create or update the lockfile for every Python project.
lock-python:
    #!/usr/bin/env bash
    set -euo pipefail
    projects=({{ python_projects }})
    for project in "${projects[@]}"; do
        uv lock --project "$project"
    done

# Normalize a release tag to the version used by package metadata.
normalize-release-tag tag:
    @uv run --no-project --no-cache python scripts/ci/normalize_release_tag.py {{ quote(tag) }}

# Convert a release tag to the PEP 440 version used by Python package metadata.
release-tag-to-py-version tag:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    tag={{ quote(tag) }}
    tag="$(just normalize-release-tag "$tag")"
    semver_to_pep440 "$tag"

# Apply a release version only to Cargo workspace metadata and Cargo.lock.
# Tag publication uses this narrow recipe in a disposable checkout.
set-cargo-version version="":
    #!/usr/bin/env bash
    {{ bash_helpers }}
    version={{ quote(version) }}
    if [[ -z "$version" ]]; then
        version={{ quote(ref_name) }}
    fi
    if [[ -z "$version" ]]; then
        echo "Error: version is required for set-cargo-version" >&2
        exit 1
    fi
    version="$(just normalize-release-tag "$version")"
    cd "$REPO_ROOT"
    set_cargo_workspace_version "$version"

# [version-or-tag] or --set ref_name=<version-or-tag>
set-version version="":
    #!/usr/bin/env bash
    {{ bash_helpers }}
    version={{ quote(version) }}
    if [[ -z "$version" ]]; then
        version={{ quote(ref_name) }}
    fi
    if [[ -z "$version" ]]; then
        echo "Error: version is required for set-version" >&2
        exit 1
    fi
    version="$(just normalize-release-tag "$version")"
    cd "$REPO_ROOT"
    set_project_version "$version"
    just lock-python

# Generate the Python and Rust API references and validate the Fern configuration.
# --set [no_uv=true|false]
docs:
    #!/usr/bin/env bash
    set -euo pipefail
    if [[ "{{ no_uv }}" != "true" ]]; then
        uv sync --frozen --no-default-groups --group docs
    fi
    npm ci --prefix docs --ignore-scripts
    PATH="{{ REPO_ROOT }}/.venv/bin:$PATH" bash scripts/generate_api_docs.sh
    uv run --no-sync python scripts/docs/generate_rust_library_reference.py
    npx --prefix docs --no-install fern check --warnings
    fern_validation_root="$(mktemp -d)"
    trap 'rm -rf "$fern_validation_root"' EXIT
    uv run --no-sync python scripts/docs/sync_fern_docs_branch.py sync-dev \
        --source-root "$REPO_ROOT" \
        --target-root "$fern_validation_root"
    (
        cd "$fern_validation_root/fern"
        "$REPO_ROOT/docs/node_modules/.bin/fern" docs broken-links --strict
    )

# Launch Jupyter Lab for the onboarding notebooks under examples/notebooks/.
# Jupyter is fetched on demand so it stays out of the project lockfile.
notebooks:
    uv run --no-sync --with jupyterlab --with ipykernel jupyter lab examples/notebooks

# Run the Python test suite with the same optional integrations used by CI.
# --set [no_uv=true|false]
test-python:
    #!/usr/bin/env bash
    set -euo pipefail
    if [[ "{{ no_uv }}" != "true" ]]; then
        uv sync --no-default-groups --group adapters --group adapter-tests --group collector --group test --extra harbor --extra relay
    fi
    uv run --no-sync pytest

# Run the Rust workspace test suite using the locked dependency set.
test-rust:
    cargo test --workspace --locked

# Run the TypeScript adapter contract checks using the locked dependency set.
test-typescript-contract: install-typescript-contract
    npm test --prefix adapter-contract/typescript

# Run the TypeScript adapter checks using the locked dependency set.
test-typescript-adapters: install-typescript
    npm run build --prefix adapter-contract/typescript
    npm test --prefix adapters/typescript

# Run every maintained TypeScript package check.
test-typescript: test-typescript-contract test-typescript-adapters

# Run all Rust, Python, and TypeScript tests.
test-all: test-rust test-python test-typescript

# Build wheels for every Python project into the repository dist directory.
wheels:
    #!/usr/bin/env bash
    {{ bash_helpers }}
    linux_glibc_version="{{ linux_glibc_version }}"
    uv sync --inexact --only-group package
    activate_project_venv
    if [[ "$(uname -s)" == "Linux" ]]; then
        prepend_ziglang_to_path "$(uv_python_executable)"
    fi
    projects=({{ python_packages }})
    uv build --wheel --clear --out-dir dist sdk/python/nemo-fabric
    for project in "${projects[@]}"; do
        if [[ "$project" == "sdk/python/nemo-fabric" || "$project" == "sdk/python/nemo-fabric-runtime" ]]; then
            # The metapackage was built first so --clear applies exactly once.
            # The native runtime needs Maturin's platform compatibility handling.
            continue
        fi
        uv build --wheel --out-dir dist "$project"
    done
    # uv build forces Maturin compatibility off, producing non-portable linux_* tags.
    build_args=()
    while IFS= read -r -d '' arg; do
        build_args+=("$arg")
    done < <(python_wheel_build_args)
    (
        cd sdk/python/nemo-fabric-runtime
        maturin build \
            --release \
            --locked \
            "${build_args[@]}" \
            --out "$REPO_ROOT/dist"
    )

# Verify every built wheel contains the canonical repository license.
check-wheel-licenses:
    uv run --no-project --no-cache python scripts/ci/check_wheel_licenses.py