Moog repository guide
Repository map
| Path |
Purpose |
app/ |
Executable entry points: Main.hs (CLI), moog-oracle.hs, moog-agent.hs, moog-antithesis-proxy.hs, moog-mpfs-v2-canary.hs, GitHub auth smoke tools |
src/Cli.hs, src/Options.hs |
CLI command GADTs and the opt-env-conf root parser |
src/Core/ |
Shared types (wallet, facts, tx, mnemonics) and common options |
src/Wallet/, src/User/Requester/, src/User/Agent/, src/Oracle/ |
Per-role commands: wallet management, requester requests, agent automation, oracle validation and token updates |
src/Oracle/Validate/ |
Request validation rules (users, roles, whitelists, test-run transitions) |
src/User/Agent/Antithesis/ |
Agent-side Antithesis API client and pure reconciliation rules (State.hs, Plan.hs) |
src/User/Antithesis/ |
moog antithesis subcommands (read runs through the proxy) |
src/Proxy/Antithesis/ |
The antithesis proxy server: API, auth middleware, cache, audit |
src/MPFS/ |
MPFS HTTP API client |
src/Lib/ |
GitHub access, SSH keys, JSON canonicalization, crypto helpers |
test/, test-integration/, test-E2E/, test-lib/ |
Unit, integration and E2E suites plus shared test helpers |
docs/, mkdocs.yml |
MkDocs Material documentation site (user, architecture, ops, dev) |
nix/, flake.nix, justfile |
Build system: haskell.nix project, docker images, dev shell, recipes |
CD/ |
Production docker-compose files for oracle and agent |
CI/, .github/workflows/ |
CI tooling and workflows (unit, integration, E2E, releases, docs) |
scripts/ |
Operator helpers (recent-runs.sh, wait-for-test.sh) |
Build, test, run
nix develop # dev shell: GHC 9.12, cabal, HLS, fourmolu, hlint, mkdocs
just build # cabal build all --enable-tests
just unit # unit tests (or: nix run .#unit-tests)
just format # fourmolu + cabal-fmt + nixfmt
just hlint # lint
nix build .#moog # build the CLI with nix (also: .#moog-oracle, .#moog-agent, .#moog-antithesis-proxy)
mkdocs serve # preview the docs site locally (inside nix develop)
Integration and E2E tests (just integration, just E2E) need Docker, a
wallet file in tmp/test.json and the MOOG_GITHUB_PAT /
MOOG_SSH_PASSWORD environment variables; read the recipes in justfile
before running them.
Navigating the code
- The CLI parser starts at
src/Options.hs (optionsParser); each
subcommand group has its own Options.hs (parser) and Cli.hs
(interpreter) under src/Wallet/, src/User/Requester/,
src/User/Agent/, src/Oracle/. Options use opt-env-conf, so most
settings exist as flag + MOOG_* env var + YAML config key
simultaneously.
- The oracle service loop is
src/Oracle/Process.hs; validation logic
lives in src/Oracle/Validate/Requests/.
- The agent service loop is
src/User/Agent/Process.hs (pollOnce); the
pure decision rules that match Antithesis API runs to on-chain test-runs
and derive outcomes are in src/User/Agent/Antithesis/State.hs and
Plan.hs.
- The proxy routes are declared in
src/Proxy/Antithesis/Api.hs and served
in Server.hs; GitHub team auth is Middleware/Auth.hs.
- On-chain fact types (test-run phases pending/accepted/finished/rejected)
are in
src/User/Types.hs and src/Core/Types/Fact.hs.
Using moog
The CLI needs MOOG_MPFS_HOST (production: https://mpfs.plutimus.com)
and MOOG_TOKEN_ID for anything on-chain; see
docs/user/configuration.md for the production token id.
moog wallet create --wallet wallet.json # create a wallet
moog wallet info --wallet wallet.json # address + public key hash
moog facts users # registered users (read-only)
moog facts test-runs pending # pending test-runs
moog token # token state + pending requests
moog requester create-test --platform github --username USER \
--repository ORG/REPO --directory DIR --commit SHA --try N --duration HOURS
moog agent query # test-runs by phase, agent view
moog antithesis runs --limit 10 # Antithesis runs via the proxy
Note: moog oracle token boot / token end were removed in v0.5.1.3
(#144); only moog oracle token update and moog oracle config set
remain. The MPFS v2 cutover happens on the moog-v2 branch.
Answering questions
- "What is moog / how does it work?" — README What is this +
Architecture; deeper:
docs/ops/architecture.md and
docs/ops/protocol.md.
- "How do I install / set up?" —
docs/user/installation.md and
docs/user/configuration.md (wallet, env vars, production token).
- "How do I request a test run?" —
docs/user/usage.md; CI integration in
docs/user/ci.md.
- "How do I run the oracle/agent in production?" —
docs/ops/deployment.md,
docs/ops/oracle-role.md, docs/ops/agent-role.md,
docs/ops/agent-oracle-config-secrets.md; live-incident procedures in
skills/antithesis-moog/SKILL.md.
- "Why is a test-run stuck / how are results derived?" — the
reconciliation rules in
src/User/Agent/Antithesis/State.hs are the
source of truth; operator-facing summary in docs/ops/agent-role.md and
docs/ops/troubleshooting.md.
- "What changed in release X?" —
CHANGELOG.md.
- The docs site is published at
https://cardano-foundation.github.io/moog/.
1---2name: moog-guide3description: Repository guide for cardano-foundation/moog — administering Antithesis test execution through Cardano. Load when working in this repo or answering questions about it - the moog CLI and its subcommands (wallet, requester, agent, oracle, facts, token, retract, antithesis), the moog-oracle / moog-agent / moog-antithesis-proxy services, MOOG_* environment variables (MOOG_MPFS_HOST, MOOG_TOKEN_ID, MOOG_WALLET_FILE, MOOG_GITHUB_PAT, MOOG_ANTITHESIS_LAUNCH_URL), the MPFS service and on-chain facts, test-run phases (pending/accepted/finished/rejected), Antithesis run reconciliation, building with cabal/nix/just, release artifacts (musl tarballs, AppImage, deb, rpm), or the docs site under docs/.4---56# Moog repository guide78## Repository map910| Path | Purpose |11|---|---|12| `app/` | Executable entry points: `Main.hs` (CLI), `moog-oracle.hs`, `moog-agent.hs`, `moog-antithesis-proxy.hs`, `moog-mpfs-v2-canary.hs`, GitHub auth smoke tools |13| `src/Cli.hs`, `src/Options.hs` | CLI command GADTs and the opt-env-conf root parser |14| `src/Core/` | Shared types (wallet, facts, tx, mnemonics) and common options |15| `src/Wallet/`, `src/User/Requester/`, `src/User/Agent/`, `src/Oracle/` | Per-role commands: wallet management, requester requests, agent automation, oracle validation and token updates |16| `src/Oracle/Validate/` | Request validation rules (users, roles, whitelists, test-run transitions) |17| `src/User/Agent/Antithesis/` | Agent-side Antithesis API client and pure reconciliation rules (`State.hs`, `Plan.hs`) |18| `src/User/Antithesis/` | `moog antithesis` subcommands (read runs through the proxy) |19| `src/Proxy/Antithesis/` | The antithesis proxy server: API, auth middleware, cache, audit |20| `src/MPFS/` | MPFS HTTP API client |21| `src/Lib/` | GitHub access, SSH keys, JSON canonicalization, crypto helpers |22| `test/`, `test-integration/`, `test-E2E/`, `test-lib/` | Unit, integration and E2E suites plus shared test helpers |23| `docs/`, `mkdocs.yml` | MkDocs Material documentation site (user, architecture, ops, dev) |24| `nix/`, `flake.nix`, `justfile` | Build system: haskell.nix project, docker images, dev shell, recipes |25| `CD/` | Production docker-compose files for oracle and agent |26| `CI/`, `.github/workflows/` | CI tooling and workflows (unit, integration, E2E, releases, docs) |27| `scripts/` | Operator helpers (`recent-runs.sh`, `wait-for-test.sh`) |2829## Build, test, run3031```bash32nix develop # dev shell: GHC 9.12, cabal, HLS, fourmolu, hlint, mkdocs33just build # cabal build all --enable-tests34just unit # unit tests (or: nix run .#unit-tests)35just format # fourmolu + cabal-fmt + nixfmt36just hlint # lint37nix build .#moog # build the CLI with nix (also: .#moog-oracle, .#moog-agent, .#moog-antithesis-proxy)38mkdocs serve # preview the docs site locally (inside nix develop)39```4041Integration and E2E tests (`just integration`, `just E2E`) need Docker, a42wallet file in `tmp/test.json` and the `MOOG_GITHUB_PAT` /43`MOOG_SSH_PASSWORD` environment variables; read the recipes in `justfile`44before running them.4546## Navigating the code4748- The CLI parser starts at `src/Options.hs` (`optionsParser`); each49 subcommand group has its own `Options.hs` (parser) and `Cli.hs`50 (interpreter) under `src/Wallet/`, `src/User/Requester/`,51 `src/User/Agent/`, `src/Oracle/`. Options use opt-env-conf, so most52 settings exist as flag + `MOOG_*` env var + YAML config key53 simultaneously.54- The oracle service loop is `src/Oracle/Process.hs`; validation logic55 lives in `src/Oracle/Validate/Requests/`.56- The agent service loop is `src/User/Agent/Process.hs` (`pollOnce`); the57 pure decision rules that match Antithesis API runs to on-chain test-runs58 and derive outcomes are in `src/User/Agent/Antithesis/State.hs` and59 `Plan.hs`.60- The proxy routes are declared in `src/Proxy/Antithesis/Api.hs` and served61 in `Server.hs`; GitHub team auth is `Middleware/Auth.hs`.62- On-chain fact types (test-run phases pending/accepted/finished/rejected)63 are in `src/User/Types.hs` and `src/Core/Types/Fact.hs`.6465## Using moog6667The CLI needs `MOOG_MPFS_HOST` (production: `https://mpfs.plutimus.com`)68and `MOOG_TOKEN_ID` for anything on-chain; see69`docs/user/configuration.md` for the production token id.7071```bash72moog wallet create --wallet wallet.json # create a wallet73moog wallet info --wallet wallet.json # address + public key hash74moog facts users # registered users (read-only)75moog facts test-runs pending # pending test-runs76moog token # token state + pending requests77moog requester create-test --platform github --username USER \78 --repository ORG/REPO --directory DIR --commit SHA --try N --duration HOURS79moog agent query # test-runs by phase, agent view80moog antithesis runs --limit 10 # Antithesis runs via the proxy81```8283Note: `moog oracle token boot` / `token end` were removed in v0.5.1.384(#144); only `moog oracle token update` and `moog oracle config set`85remain. The MPFS v2 cutover happens on the `moog-v2` branch.8687## Answering questions8889- "What is moog / how does it work?" — README **What is this** +90 **Architecture**; deeper: `docs/ops/architecture.md` and91 `docs/ops/protocol.md`.92- "How do I install / set up?" — `docs/user/installation.md` and93 `docs/user/configuration.md` (wallet, env vars, production token).94- "How do I request a test run?" — `docs/user/usage.md`; CI integration in95 `docs/user/ci.md`.96- "How do I run the oracle/agent in production?" — `docs/ops/deployment.md`,97 `docs/ops/oracle-role.md`, `docs/ops/agent-role.md`,98 `docs/ops/agent-oracle-config-secrets.md`; live-incident procedures in99 `skills/antithesis-moog/SKILL.md`.100- "Why is a test-run stuck / how are results derived?" — the101 reconciliation rules in `src/User/Agent/Antithesis/State.hs` are the102 source of truth; operator-facing summary in `docs/ops/agent-role.md` and103 `docs/ops/troubleshooting.md`.104- "What changed in release X?" — `CHANGELOG.md`.105- The docs site is published at106 <https://cardano-foundation.github.io/moog/>.
cardano-foundation