expand facilities for inspecting the active config

[plobsing]

Feature Overview

aqua info and aqua which are a good start for inspecting the active aqua configuration, but there are some queries I'd like to make that I haven't found a way to do. Specifically, I'd like to be able to

• find out what policies might apply in the current directory and whether they've been allowed, denied, or neither. Also, whether any allow/deny for these policies is current or stale.
• enumerate what packages are included by the config, which config file brought each of them in, and what files they each install

Why is the feature needed?

Querying the state of the system, without making modifications, can be useful in diagnostic contexts. My immediate interest is in diagnosing why some teammate's install isn't working as intended. Do they need to create symlinks with aqua install? Do they need to allow a certain policy? Did they previously deny an important policy? Do they have aliasing tools earlier on their $PATH? There's a few different ways a setup can be broken and I'd like to check on those, ideally in a automated way. I have a script that does similar things for other foundational tools in my repos, I'd like to extend the diagnostics to the repos' use of Aqua as well. I can build most of the debug-specific stuff myself in my own scripts, but determining Aqua's view of the world seems like something that should come from Aqua itself.

Workaround

I've considered replicating Aqua's config-file search process and evaluation semantics in my own tools, but these seem just intricate enough for me to have doubts that a reimplementation would faithfully reproduce the exact same behaviour as the original.

Example Code

I don't have a strong opinion on what the exact commands to get this should look like, nor the format of their output. I think the solution here could probably take a few different forms. So long as the information is made available, I'm happy. Maybe it could look something like

# List the policies relevant to the config. Include allow/deny information.
# Action attribution from allow-/deny-file mtime and perms to help remind forgetful users that they in fact did take certain actions.
$ aqua policy list
/Users/peter/repo/.aqua/aqua-policy.yaml           allowed by peter at 2023-11-12 12:43:00Z
$ cd ../another-repo; aqua policy list
/Users/peter/another-repo/.aqua/policy.yaml        denied by peter at 2023-12-01 08:24:33Z
$ cd ../brand-new-repo; aqua policy list
/Users/peter/brand-new-repo/.aqua/my-policy.yaml   new

# Only list packages requested by local config. Include provenance for each package.
$ aqua list --local
standard,99designs/aws-vault  from /Users/peter/repo/.aqua/aqua-policy.yaml
standard,fluxcd/flux2         from /Users/peter/repo/.aqua/imports/flux.yaml via /Users/peter/repo/.aqua/aqua-policy.yaml

# Dump the definition of a single package (in JSON format to mirror existing aqua info output).
# Filtering to extract parts I need (what executables get installed).
$ aqua info package standard,fluxcd/flux2 | jq --raw-output '.files[]'
flux

Note

No response

[suzuki-shunsuke]

Thank you for your feedback.
It makes sense.

Regarding aqua policy list, I think we can also add the list of policies to the output of aqua info command.

[plobsing]

Adding policy information into the output of aqua info works for me. So long as the information is available somehow, I'm happy.

Looking at what I described above again, I'm not sure I even need aqua to read the FS metadata to put together the allowed by peter at 2023-11-12 12:43:00Z parts of the status strings. All I really need to know about policies is which ones to look up under $(aqua root-dir)/policies/$(aqua root-dir)/policy-warnings; from there I can read the FS metadata on my end to fetch and format whatever info my scripts need.