Metadata-Version: 2.5
Name: aw-index-cli
Version: 0.5.0
Summary: Consumer CLI for the autoware-index registry
Project-URL: Homepage, https://github.com/autowarefoundation/aw-index-cli
Project-URL: Repository, https://github.com/autowarefoundation/aw-index-cli
Project-URL: Issues, https://github.com/autowarefoundation/aw-index-cli/issues
Author-email: Mete Fatih Cırıt <mfc@autoware.org>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: autoware,registry,ros,ros2,vcs2l,vcstool
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# aw-index-cli

[![ci](https://github.com/autowarefoundation/aw-index-cli/actions/workflows/ci.yaml/badge.svg)](https://github.com/autowarefoundation/aw-index-cli/actions/workflows/ci.yaml)

`aw-index-cli` is the consumer CLI for the [Autoware Index][index] registry.
It reads a distribution manifest (`distributions/<rosdistro>.yaml`) and composes a [vcs2l][vcs2l] `.repos` file you can `vcs import` into a workspace.

The registry is **repository-keyed**: each entry is one repository with **exactly one `ref`** and the packages it hosts.

The CLI accepts registry schema v4 only.
Schema v4 packages may declare `index_dependencies`, a list of other registered package names in the same ROS distribution.
`compose` includes these packages' repositories recursively.

[index]: https://autowarefoundation.github.io/autoware-index/
[vcs2l]: https://github.com/ros-infrastructure/vcs2l

## Install

With [pipx][pipx] (recommended for an isolated CLI):

```bash
pipx install aw-index-cli   # first install
pipx upgrade aw-index-cli   # update to the latest release
```

[pipx]: https://pipx.pypa.io/

## Commands

- `compose`: render a `.repos` file from a distribution.
- `check`: gate a composed `.repos` against the registry and sweep history.
- `list`: list registry packages with their latest validation status.

## `compose`

Select what you need by package, repository, tag, or reference design.
The distribution is fetched from GitHub by default, so no registry checkout is required.

```bash
# Recommended: compose just the packages you want.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter

# …or pull in whole repository entries by their registry key.
aw-index-cli compose --rosdistro jazzy \
  --repository autoware_livox_tag_filter

# Narrow by tag (filters can be combined; they are ANDed). Aliases from the
# registry vocabulary resolve too: --tags ai selects the same as --tags ml.
aw-index-cli compose --rosdistro jazzy --tags sensing perception

# Compose entries marked as a reference design.
aw-index-cli compose --rosdistro jazzy --reference-design --stdout | vcs import src

# Print to stdout instead of writing a file.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter --stdout
```

> [!TIP]
> Omitting all of `--packages`, `--repository`, `--tags`, and `--reference-design` composes the **entire** distribution.
> That is supported, but usually you want to name what you consume.

Example output for `compose --rosdistro jazzy --repository livox-tools` (a monorepo entry hosting two registered packages):

```yaml
# aw-index-cli 0.5.0
# source: autowarefoundation/autoware-index@main
# rosdistro: jazzy
# tags: all
# repository: livox-tools
# generated_at: 2026-06-11T12:00:00+00:00
# selected packages by repository:
#   livox-tools: autoware_livox_decoder, autoware_livox_tag_filter
# Generated file. Re-run 'aw-index-cli compose …' to update; do not edit by hand.

repositories:
  livox-tools:
    type: git
    url: https://github.com/autowarefoundation/autoware_livox_tag_filter
    version: main
```

Less common sources are a local registry checkout, or a fork / specific git ref:

```bash
# Read from a local registry checkout instead of GitHub.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter \
  --registry-path /path/to/autoware-index

# Fetch the distribution from a fork at a specific branch/tag/sha.
aw-index-cli compose --rosdistro jazzy \
  --packages autoware_livox_tag_filter \
  --registry-repo me/autoware-index-fork --registry-ref dev
```

### How entries are composed

- **Entry keys are registry repository keys**, the directory `vcs import` clones into.
- **Filters are ANDed to choose root packages.**
  In schema v4, each root's `index_dependencies` are then included transitively, regardless of the filters.
  For example, selecting a planning package also imports its indexed common library even when that library does not match `--tags planning`.
  Unknown dependency names and dependency cycles are errors.
- An unknown `--packages` name or `--repository` key is a hard error, never a silent empty result.
- **A monorepo collapses to one entry** at its single `ref`, however many of its packages are selected or required as dependencies.
- **Each entry is pure vcs2l**: `type`/`url`/`version` only.
  The selected and dependency package names live in the `# selected packages by repository:` header comment, not the YAML body.
  `check` reads this header to verify the included packages.

For example, a schema v4 package can declare:

```yaml
packages:
  my_planner:
    tags: [planning]
    index_dependencies: [my_map_library]
```

`my_map_library` must be registered in the same distribution.
The `.repos` file imports its repository automatically when you compose `my_planner`.
Registration derives these Index edges from upstream `package.xml` dependency names.
If a dependency also has a ROS build farm binary, the Index source is included in the workspace.
Install remaining dependencies with rosdep after importing:

```bash
rosdep install --from-paths src --ignore-src --rosdistro jazzy -y
colcon build --packages-up-to my_planner
```

`--ignore-src` skips binary installation for packages in the source workspace.

> [!NOTE]
> A clone may include unregistered sibling packages the index makes no claims about.
> To build only the packages you selected, pass their names to colcon:

```bash
colcon build --packages-up-to autoware_livox_tag_filter  # names from the header comment
```

### Key options

- `--rosdistro` (required): ROS distribution, e.g. `jazzy`.
- `--packages` / `--repository` / `--tags`: selection filters.
- `--autoware`: informational only; recorded in the header, not a ref selector.
- `--registry-path`: read a local file or registry directory instead of GitHub.
- `--registry-repo` / `--registry-ref`: GitHub source repo (default `autowarefoundation/autoware-index`) and git ref (default `main`).
- `--repo-root` / `--name` / `--output`: where and under what name to write the `.repos` (default `<repo-root>/repositories/autoware-index.repos`).
- `--stdout`: print instead of writing a file.
- `--no-timestamp`: omit `generated_at` for byte-identical output.

> [!IMPORTANT]
> There is no `import` command; pipe `compose` straight into vcs:

```bash
aw-index-cli compose --rosdistro jazzy --packages autoware_livox_tag_filter --stdout \
  | vcs import src
```

## `check`

Verify a composed `.repos` is still current: every repository at the registry's ref, and each package passing its latest **sweep**, the registry's periodic build/test against the current Autoware release.
Intended as a **CI gate** after `vcs import`.

```bash
# Auto-discovers ./autoware-index.repos or ./*/autoware-index.repos; rosdistro is
# read from the file's header. Exit code is the gate.
aw-index-cli check

# Or point at a specific file.
aw-index-cli check --repos repositories/autoware-index.repos --rosdistro jazzy
```

Per repository it reports ref drift, removal from the registry, each package's latest status (`pass`/`fail`/`-`) and the Autoware version tested, and, for `branch` refs, whether the branch advanced past the last sweep.

- **Exit `0`**: all pass, no drift.
- **Exit `1`**: any failing validation, ref drift, or removed package (with `--strict`, also unvalidated packages or a branch that advanced since the sweep).
- **Exit `2`**: could not run (bad/missing `.repos`, registry load error).

Options mirror `compose`, plus `--data-ref` (default `data`), `--strict`, and `--format {table,json}`.

> [!NOTE]
> Without `git` on PATH the branch-drift check is silently skipped, so a green check isn't a complete guarantee.

## `list`

Enumerate the packages registered for a distro with their latest sweep status: discovery plus a health readout, without composing anything.

```bash
aw-index-cli list --rosdistro jazzy
aw-index-cli list --rosdistro jazzy --tags sensing --format json
```

Accepts the same selection filters as `compose`.
Exit `0` normally; with `--strict`, exit `1` if any selected package is failing or unvalidated; exit `2` on a registry load error.
`list` displays packages matching the filters; it does not expand their `index_dependencies`.

## License

Apache-2.0. See [LICENSE](LICENSE).
