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

# Install into a specific application directory
aro add git@github.com:arolang/csv-tools.git -d ./MyApp

When you run aro add, ARO clones the repository, validates its plugin.yaml manifest, checks ARO version compatibility, compiles native plugins, and installs everything 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 1 .aro file set
   Found 1 Swift plugin source

🔗 Installing to Plugins/csv-tools/
   ✓ Compiled Swift plugin CSVTools

✅ Package "csv-tools" v1.0.0 installed successfully.

Managing Packages

ARO provides commands to list, update, check, 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

# Check compatibility and lock file integrity
aro plugins check

# Validate plugin manifests and dependencies
aro plugins validate

# Recompile native plugins from source
aro plugins rebuild

# Generate documentation for a plugin
aro plugins docs csv-tools

# Export plugin sources for reproducible builds
aro plugins export

# Restore plugins from .aro-sources file
aro plugins restore

# Remove a package (prompts for confirmation)
aro remove csv-tools

# Remove without confirmation
aro remove csv-tools --force

All aro plugins subcommands accept a -d / --directory flag to specify the application directory.

Listing Installed Packages

ARO distinguishes between managed plugins (installed via aro add into Plugins/) and local plugins (placed manually in plugins/):

$ aro plugins list

Managed Plugins (from Plugins/):
────────────────────────────────────────────────────────────────
 Name              Version  Source                    Provides
 csv-tools         1.0.0    github.com                1 .aro, 1 swift
 xml-validator     2.0.0    github.com                1 rust
────────────────────────────────────────────────────────────────
 2 managed plugins

Local Plugins (from plugins/):
────────────────────────────────────────────────────────────────
 Source                          Service           Methods
 MyPlugin.swift                  MyPluginService   doSomething
────────────────────────────────────────────────────────────────
 1 local plugin

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 and a plugins.lock file:

MyProject/
├── main.aro
├── openapi.yaml
├── plugins.lock                 # Lock file for reproducible builds
├── Plugins/                     # Managed plugins (aro add)
│   ├── csv-tools/
│   │   ├── plugin.yaml          # Package manifest
│   │   ├── features/
│   │   │   └── csv-parser.aro
│   │   └── Sources/
│   │       └── CSVParser.swift
│   └── xml-validator/
│       ├── plugin.yaml
│       └── src/
│           └── lib.rs
└── plugins/                     # Local plugins (manual)
    └── MyPlugin.swift

Plugins/ vs plugins/

ARO loads plugins from two directories:

• Plugins/ (uppercase) — Managed plugins installed via aro add. Each subdirectory must contain a plugin.yaml manifest.
• plugins/ (lowercase) — Local plugins for quick prototyping. Supports bare .swift files or Swift packages without a manifest.

Package Types

ARO packages can provide different types of content:

Reproducible Builds

Option 1: Commit Plugins/ — Commit the entire Plugins/ directory and plugins.lock to version control. All team members get identical dependencies without running aro add.

Option 2: Export and restore — Add Plugins/ to .gitignore and use the export/restore workflow:

# Export plugin sources to a file
aro plugins export              # writes .aro-sources

# Commit .aro-sources to version control, then on another machine:
aro plugins restore             # reads .aro-sources, clones and installs all plugins

The .aro-sources file records each plugin's Git URL, ref, and commit hash, so aro plugins restore can reproduce the exact same set of plugins.

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.