# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`mgt` is a Rust CLI tool for working with the WildFly management model graph. It serves two main purposes:

1. **Analysis Pipeline** — Orchestrates starting WildFly containers, spinning up Neo4J databases, running the Java-based [analyzer](https://github.com/model-graph-tools/analyzer), and building self-contained Neo4J images.
2. **Model Container Management** — Starts and stops Neo4J model containers, making the management model graph available for querying and exploration.

`mgt` is a key component of the [model graph tools](https://model-graph-tools.github.io/) ecosystem and powers the [Model Graph Tools Claude Code Plugin](https://github.com/model-graph-tools/claude-plugin), which provides an MCP server for exploring the WildFly management model directly from Claude Code.

## Build Commands

```shell
cargo build              # debug build
cargo build --release    # release build (uses LTO)
cargo run -- analyze 34  # run with arguments
cargo test               # run tests
cargo clippy             # lint
cargo fmt                # format
```

The binary is named `mgt`. Rust edition 2024.

## Architecture

The codebase is organized into top-level modules and a `command/` submodule tree:

### Top-Level Modules

- **`main.rs`** — Entry point. Parses CLI args via clap, dispatches to subcommands.
- **`app.rs`** — Defines the clap `Command` tree (subcommands, args, styling). Separated from `main.rs` so both the runtime and the completion system can build the command tree independently.
- **`args.rs`** — Helpers to extract typed arguments from clap `ArgMatches`.
- **`command/`** — Subcommand implementations (see below).
- **`constants.rs`** — Analyzer version/URL, Neo4J version/image, and Dockerfile generation.
- **`container.rs`** — Container runtime abstraction. Prefers `podman`, falls back to `docker`.
- **`neo4j.rs`** — Neo4J container, image, and port management.
- **`registry.rs`** — Global `OnceLock`-based access to `wildfly_meta` registries for clap parsers.
- **`download.rs`** — HTTP download helpers (analyzer JAR).
- **`progress.rs`** — Progress bar and status display utilities.
- **`completion.rs`** — Dynamic shell completion logic for identifiers.
- **`label.rs`** — Display formatting for sources.

### Command Submodules (`src/command/`)

- **`analyze/`** — Core analysis pipeline, split into focused files:
  - `mod.rs` — Entry point, parallel orchestration across sources.
  - `runner.rs` — Per-source analysis workflow (start containers → run analyzer → build image → cleanup).
  - `wildfly.rs` — WildFly container start/stop for analysis.
  - `neo4j_ops.rs` — Neo4J container start/stop for analysis.
  - `feature_pack.rs` — Feature pack resolution and container setup.
  - `cleanup.rs` — Resource cleanup after analysis.
- **`push.rs`** — Push Neo4J model DB images to quay.io.
- **`start.rs`** — Start Neo4J model DB containers.
- **`stop.rs`** — Stop Neo4J model DB containers.
- **`browse.rs`** — Open Neo4J browser for running containers.
- **`versions.rs`** — List supported WildFly versions.
- **`feature_packs.rs`** — List supported feature packs.
- **`images.rs`** — List locally available Neo4J model DB images.
- **`ps.rs`** — List running Neo4J model DB containers.
- **`update.rs`** — Update WildFly and feature pack configuration files from `wildfly_meta`.
- **`completions.rs`** — Shell completion generation and installation.

## Key Dependencies

- **`wildfly_meta`** — WildFly image and feature pack metadata (registries, version parsing, completions). Loaded from TOML files in `~/.config/wildfly-meta/`.
- **`clap`** / **`clap_complete`** — CLI argument parsing with dynamic shell completions.
- **`tokio`** — Async runtime for concurrent container orchestration.
- **`reqwest`** — Downloads the analyzer JAR from GitHub releases.

## Runtime Requirements

- `podman` or `docker` must be available on PATH
- Network access to pull container images and download the analyzer JAR

## Identifiers

Commands accept WildFly versions, feature pack shortcuts, or a mix. WildFly versions are specified as `<major>[.<minor>]` where major >= 10 and minor 0-9. Supports comma-separated lists (`10,26.1,34`) and ranges (`20..29`). Feature packs use shortcut names (e.g. `ai`, `graphql`).

## Release Process

Uses `cargo-release` with `release.toml`. Run `./release.sh <version>` to bump version, update changelog, tag, and push. The GitHub Actions release workflow then creates a GitHub release, publishes to crates.io, uploads platform binaries, and updates the Homebrew formula.
