Installer Module¶

The installer system is split across two layers:

• stackops.jobs.installer for packaged install scripts
• stackops.utils.schemas.installer for the installer catalog and typed schema
• stackops.utils.installer_utils for the runtime engine

This page documents the runtime behavior that the current code exposes.

Core data model¶

The typed schema lives in stackops.utils.schemas.installer.installer_types.

InstallerData¶

from stackops.utils.schemas.installer.installer_types import InstallerData

installer_data: InstallerData = {
    "appName": "fd",
    "license": "MIT",
    "doc": "A simple, fast and user-friendly alternative to find",
    "repoURL": "https://github.com/sharkdp/fd",
    "categoryLabels": ["search-navigation"],
    "fileNamePattern": {
        "amd64": {
            "linux": "fd-v{version}-x86_64-unknown-linux-musl.tar.gz",
            "windows": "fd-v{version}-x86_64-pc-windows-msvc.zip",
            "darwin": "fd-v{version}-x86_64-apple-darwin.tar.gz",
        },
        "arm64": {
            "linux": "fd-v{version}-aarch64-unknown-linux-musl.tar.gz",
            "windows": None,
            "darwin": "fd-v{version}-aarch64-apple-darwin.tar.gz",
        },
    },
}

Fields:

Other types¶

Helpers:

• get_os_name()
• get_normalized_arch()

How installers are resolved¶

stackops.utils.installer_utils.installer_runner.get_installers() loads the catalog from:

• stackops.utils.schemas.installer.INSTALLER_DATA_PATH_REFERENCE
• resolved through stackops.utils.path_reference.get_path_reference_path(...)

It then filters by:

• current OS
• current architecture
• optional package-group list

Example:

from stackops.utils.installer_utils.installer_runner import get_installers
from stackops.utils.schemas.installer.installer_types import (
    get_normalized_arch,
    get_os_name,
)

installers = get_installers(
    os=get_os_name(),
    arch=get_normalized_arch(),
    which_cats=["termabc"],
)

Installation strategies¶

Installer._install_from_value() supports four current strategies.

1. Package-manager commands¶

If the resolved installer value contains a whitespace-separated package-manager token such as bun, npm, pip, uv, winget, powershell, irm, brew, curl, sudo, or cargo, the installer executes that shell command directly.

This is also the path used for entries whose repoURL is "CMD" and whose platform value is a raw command string.

2. Script installers¶

If the resolved installer value ends in:

• .sh
• .ps1
• .py

the installer searches the packaged installer assets under stackops.jobs.installer and runs the matching script.

Current Python installer scripts are expected to expose:

main(installer_data: InstallerData, version: str | None, update: bool)

Extra parameters are allowed only if they are optional.

3. Direct binary or archive URLs¶

If the resolved installer value is an http:// or https:// URL, the installer downloads it to ~/tmp_results/tmp_installers, decompresses supported archives, and then moves the resulting executable or .deb package into place.

4. GitHub releases¶

If repoURL is a GitHub repository URL, Installer.get_github_release() fetches release metadata and matches a release asset against the current platform's fileNamePattern.

Current matching behavior includes:

• {version} substitution with the resolved tag name
• fallback checks for v-prefixed versus unprefixed versions
• hyphen / underscore filename variants before the install fails

Install request handling¶

InstallRequest(version, update) is resolved against the installer kind before installation:

• installs are skipped when the executable already exists unless update=True or version is set
• --version is accepted for GitHub release installers, script installers, and winget install ... commands
• --update is accepted for binary URL, GitHub release, script installers, and winget install ... commands
• unsupported version requests are ignored with a warning; unsupported update requests warn and continue

Installer¶

stackops.utils.installer_utils.installer_class.Installer is the per-package orchestrator.

Main methods¶

Example¶

from stackops.utils.installer_utils.installer_class import Installer
from stackops.utils.schemas.installer.installer_types import InstallRequest

installer = Installer(installer_data)
result = installer.install_robust(
    install_request=InstallRequest(version=None, update=False),
)

print(result["kind"])

install_robust() currently returns one of these result shapes:

• {"kind": "skipped", ...}
• {"kind": "same_version", ...}
• {"kind": "updated", ...}
• {"kind": "failed", ...}

CLI-style entrypoints¶

These helpers live in stackops.utils.installer_utils.installer_cli.

main_installer_cli(...)¶

from stackops.utils.installer_utils.installer_cli import main_installer_cli

main_installer_cli(
    which="fd,bat,rg",
    group=False,
    interactive=False,
    explore=False,
    update=False,
    version=None,
)

Parameters:

Other entrypoints¶

Current CLI aliases:

• agy -> antigravity

Interactive mode currently:

• lists package groups first, prefixed with 📦
• lists installer options using Installer.get_description()
• uses choose_from_dict_with_preview() when tv exists
• falls back to choose_from_options() otherwise

Package groups¶

The installer runtime consumes the groups defined in stackops.utils.schemas.installer.package_groups.PACKAGE_GROUP2NAMES.

Current group names:

• sysabc
• shell
• search
• sys-monitor
• code-analysis
• termabc
• dev
• dev-utils
• eye
• agents
• terminal
• browsers
• editors
• db-all
• db-cli
• db-desktop
• db-web
• db-tui
• media
• gui
• nw
• file-sharing
• productivity

Example:

from stackops.utils.schemas.installer.package_groups import PACKAGE_GROUP2NAMES

print(PACKAGE_GROUP2NAMES["agents"])

Bulk installation¶

stackops.utils.installer_utils.installer_runner.install_bulk() is the multi-package entrypoint.

from stackops.utils.installer_utils.installer_runner import install_bulk
from stackops.utils.schemas.installer.installer_types import InstallRequest

install_bulk(
    installers_data=installers,
    install_request=InstallRequest(version=None, update=False),
    safe=False,
    jobs=10,
    fresh=False,
)

Current behavior:

• the first installer runs serially
• the remaining installers run through a stdlib process pool
• fresh=True clears the version cache first
• safe is accepted but currently has no behavior
• a Rich summary is rendered after the batch finishes

Direct URL installers¶

Two URL-oriented helpers are exposed separately:

from stackops.utils.installer_utils.install_from_url import (
    install_from_binary_url,
    install_from_github_url,
)

install_from_github_url(github_url)¶

• fetches the latest release
• lets the user choose a release asset interactively
• downloads, extracts, and installs it
• records the resolved version in the install-version cache when a tool name can be derived from the selected asset or repository

install_from_binary_url(binary_url)¶

• downloads a binary or archive directly
• extracts and installs it
• records "latest" in the install-version cache only when a tool name can be derived during finalization

Version tracking and install paths¶

Current constants come from stackops.utils.source_of_truth:

Each installed tool gets a version marker file under INSTALL_VERSION_ROOT.

Security checks¶

Security and reporting helpers live under stackops.jobs.installer.checks.*. They are part of the installer subsystem, but they are not on the main install path described above. Use them when you need auditing or reporting around already installed tools rather than installation itself.

API reference¶

Installer schema¶

get_os_name() -> OPERATING_SYSTEMS

get_normalized_arch() -> CPU_ARCHITECTURES

Package groups¶

Installer class¶

Installer(installer_data: InstallerData)

get_github_release(
    repo_url: str, version: str | None
) -> tuple[str | None, str | None]

Installer runner¶

Install request logic¶

Installer helper utilities¶

handle_installer_not_found(
    search_term: str, app_apps: list[InstallerData]
) -> list[str]

Installer locator utilities¶

GitHub release scraper¶

fetch_expanded_assets(
    username: str,
    repo_name: str,
    tag_name: str,
    headers: dict[str, str],
) -> list[dict[str, Any]]

scrape_github_release_page(
    username: str,
    repo_name: str,
    version: str | None = None,
) -> dict[str, Any] | None

GitHub release bulk helpers¶

is_github_repo(url: str) -> bool

extract_github_repos_from_json(
    json_file_path: Path,
) -> Set[str]

get_repo_name_from_url(
    repo_url: str,
) -> tuple[str, str] | None

fetch_github_release_data(
    username: str,
    repo_name: str,
    version: str | None = None,
) -> Dict[str, Any] | None

get_release_info(
    username: str,
    repo_name: str,
    version: str | None = None,
) -> ReleaseInfo | None

extract_release_info(
    release_data: Dict[str, Any],
) -> ReleaseInfo | None

Install from URL helpers¶

Installer CLI helpers¶

Installer Python script main protocol¶

Installer explore helpers¶

Installer summary helpers¶

Offline installer entrypoint¶

Offline installer models¶

Offline installer constants¶

Offline installer publish helpers¶

Offline installer render helpers¶

Offline installer script helpers¶

Offline installer steps¶

Offline installer uv helpers¶

Installation check utilities¶

upload_app(path: Path) -> str | None

download_google_drive_file(url: str) -> Path

install_cli_app(app_url: str) -> bool

load_app_metadata_report() -> list[dict[str, str]]

load_engine_results_report() -> list[dict[str, str]]

download_safe_apps(name: str = 'essentials') -> bool

Installation checks¶

Security CLI helpers¶

Security helper utilities¶

Security report utilities¶

VirusTotal utilities¶