Packages

Adding Packages

The aro add command installs packages from Git repositories directly into your project's Plugins/ directory:

# Add a package via SSH
aro add git@github.com:arolang/csv-tools.git

# Add a package via HTTPS
aro add https://github.com/arolang/csv-tools.git

# Add a specific version or branch
aro add git@github.com:arolang/csv-tools.git --ref v1.2.0
aro add git@github.com:arolang/csv-tools.git --branch develop

When you run aro add, ARO clones the repository, validates its plugin.yaml manifest, and installs it into Plugins/.

Example Output

$ aro add git@github.com:arolang/csv-tools.git

📦 Resolving package: csv-tools
   Cloning from git@github.com:arolang/csv-tools.git...
   ✓ Cloned (ref: main, commit: a3f8c21)

📂 Reading plugin.yaml:
   Name:    csv-tools
   Version: 1.0.0
   Found 3 .aro files (feature sets)
   Found 2 Swift plugin sources

🔗 Installing to Plugins/csv-tools/
   ✓ Registered 3 ARO feature sets
   ✓ Compiled 2 Swift plugins

✅ Package "csv-tools" v1.0.0 installed successfully.
   Available actions: FormatCSV, ValidateCSV, ParseCSV

Managing Packages

ARO provides commands to list, update, and remove installed packages:

# List all installed packages
aro plugins list

# Update all packages
aro plugins update

# Update a specific package
aro plugins update csv-tools

# Remove a package
aro remove csv-tools

Listing Installed Packages

$ aro plugins list

Installed Plugins (from Plugins/):
────────────────────────────────────────────────────────────────
 Name              Version  Source                    Provides
 csv-tools         1.0.0    git@github.com:...        3 .aro, 2 swift
 xml-validator     2.0.0    git@github.com:...        1 .aro, 1 rust
 my-local-plugin   0.1.0    (local)                   1 swift
────────────────────────────────────────────────────────────────
 3 plugins loaded, 0 warnings

Using Package Features

Once a package is installed, its feature sets and actions are automatically available in your application. No import statements needed:

(* main.aro - Using actions from csv-tools package *)

(processReport: Report API) {
    Extract the <file> from the <request: body>.

    (* Actions from the csv-tools package *)
    ParseCSV the <data> from the <file>.
    ValidateCSV the <data> against <report-schema>.
    FormatCSV the <output> from the <data> with { delimiter: ";" }.

    Return an <OK: status> with <output>.
}

Project Structure

After installing packages, your project structure will include a Plugins/ directory:

MyProject/
├── main.aro
├── openapi.yaml
└── Plugins/
    ├── csv-tools/               # Installed via aro add
    │   ├── plugin.yaml          # Package manifest
    │   ├── features/
    │   │   ├── csv-parser.aro
    │   │   └── csv-formatter.aro
    │   └── Sources/
    │       └── CSVParser.swift
    └── my-local-plugin/         # Local plugin
        ├── plugin.yaml
        └── Sources/
            └── MyPlugin.swift

Package Types

ARO packages can provide different types of content:

Reproducible Builds

You can commit your entire Plugins/ directory to version control for fully reproducible builds. This ensures all team members have identical dependencies without running aro add.

Alternatively, you can add Plugins/ to .gitignore and rely on the source entries in each plugin.yaml to restore packages.

Manual Installation

Packages can also be installed manually by cloning into Plugins/:

# Manual installation
cd MyProject/Plugins
git clone git@github.com:arolang/csv-tools.git

# The package is automatically detected at next run
aro run ..

As long as the directory contains a valid plugin.yaml, ARO will recognize and load it.