aqua-registry Documentation

aqua installs commands into a specific directory in your PATH (AQUA_ROOT_DIR/bin). Because of this design, aqua cannot support tools that require plugins to be installed in specific, non-standard locations.

Examples of tools that may have compatibility issues include:

• GitHub CLI Extensions
• Terraform providers
• Gauge plugins

If you are submitting a pull request to add a plugin to aqua-registry, you must verify that the plugin works when installed via aqua's mechanism. If the plugin requires a specific installation path, please explain this behavior in your pull request description so the maintainers can evaluate it.

Files located at pkgs/**/pkg.yaml serve as test data within the registry. Their primary purpose is to verify that specific packages can be installed properly.

Important: These files are not exhaustive lists of all available versions. You can still install any version of a package that is not explicitly listed in a pkg.yaml file.

To prevent name conflicts, all tool names in registry.yaml must include a namespace-like prefix using a /.

• Format: namespace/tool-name (e.g., hashicorp/terraform instead of terraform).
• GitHub-managed tools: Match the repository name. If a single repository contains multiple tools, differentiate them by adding a suffix (e.g., winebarrel/cronplan/cronmatch).
• Version retrieval: aqua-renovate-config assumes a package name without a period (e.g., owner/repo) refers to a GitHub repository and attempts to fetch versions from GitHub Releases or Tags. If the package is not hosted on GitHub, include a period in the name as a workaround.
• Cargo packages: Use the format crates.io/<crate name> (e.g., crates.io/skim).
• GitLab: Use the format gitlab.com/<repository name>.

When deciding whether to regenerate a package, check the version_constraint and version_overrides syntax in the package configuration:

• New Style: Uses a root version_constraint: "false" and a list of version_overrides. Constraints typically use <= (e.g., semver("<= 0.1.0")) and end with a version_constraint: "true" entry for the latest version.
• Old Style: Often lacks a version_overrides definition entirely. If you encounter this style, it is usually better to regenerate the package from scratch.

version_constraint: "false" # Root version_constraint is "false"
version_overrides:
  - version_constraint: semver("<= 0.1.0")
    # ...
  - version_constraint: "true" # End with "true" for latest version configuration
    # ...

aqua does not support dynamic $PATH modification. For a programming language to be supported, its commands and libraries must be installable in a way that allows aqua to manage them without breaking the environment.

Key constraints:

• Command Location: If a language installs commands in its own directory rather than a directory that can be added to $PATH, aqua cannot execute them.
• Library Isolation: If a language installs libraries in the same directory as the language itself, the language may fail to reference the correct libraries when aqua switches between different versions of that language.

Example: Node.js Support Node.js is supported because the installation path can be redirected using the NPM_CONFIG_PREFIX environment variable, preventing npm i -g from installing into the same directory as the Node.js binary itself.

Package-related code and configuration are organized within the pkgs/<package name> directory. Each package directory typically contains three key files:

• registry.yaml: The primary configuration for a specific tool. These individual files are merged to generate the master registry.yaml located at the repository root.
• pkg.yaml: Contains test data, specifically a list of versions installed during testing. Note that pkg.yaml is only for testing; you can install versions that are not listed in this file.
• scaffold.yaml (Optional): Used to configure commands that auto-generate pkg.yaml and registry.yaml. This file is required if you need to modify the auto-generation behavior.

If a package uses version_overrides, you should test more than just the latest version. Add both the latest version and older versions to the packages list to ensure backward compatibility and proper installation of legacy versions.

packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli
    version: v2.4.0

When reporting an issue, provide as much detail as possible to avoid misunderstandings. For a high-quality How to reproduce section, include the following information:

• Environment:
  • OS (e.g., Windows, macOS, Ubuntu)
  • Arch (e.g., amd64, arm64)
  • Tool versions (list all tool versions if multiple are used)
• Code: Provide minimum, reproducible, and executable code. Do not use partial code or private resources (like private Docker images) if public ones can reproduce the issue.
• Command and Result: The exact command used and its output.
• Expected Behavior vs. Actual Behavior: Be specific. Avoid ambiguous phrases like "an error occurs". Instead, paste the exact command and standard (error) output.
• Debug Log: Include relevant logs.

If you are testing multiple versions, describe the results for each.

If auto-generation fails or produces errors that are difficult to resolve via configuration, you can modify the files manually.

Steps for manual troubleshooting:

1. If multiple versions are failing, comment out some versions in pkg.yaml to isolate the issue.
2. Apply fixes following the Registry Style Guide.
3. Crucial: After any manual modification, run argd t to verify that the package can be installed correctly.
4. Repeat the modification and argd t cycle until the installation succeeds.
5. Once fixed, submit your Pull Request.

# Verify manual changes
argd t