adrpy-tui

A rich terminal interface for adrpy-ai: guided, human-friendly management of Architecture Decision Records.

adrpy-tui puts menus, forms, lists and previews on top of adrpy-ai, the JSON-only ADR lifecycle CLI. Installing adrpy-tui with pip installs adrpy-ai with it (the 0.1 series), so one install gives you both: the screens to work in, and the adrpy command they drive. Every change still goes through adrpy -- the interface shows you the exact command before it runs, and adrpy's rules are the only ones that apply.

Table of Contents

• Motivation and Benefits
• adrpy-ai and adrpy-tui
• Versions and compatibility
• Installation
• Quick start
• Features
• Keys
• Appearance and accessibility
• Where adrpy-tui keeps its settings
• Documentation
• Contributing, security and license

Motivation and Benefits

• The whole ADR lifecycle without memorizing a flag. Every adrpy and adrpy-skills command has its screen: menus by use, forms that ask only for what the command needs, and a decision picked from a list.
• Nothing runs behind your back. The confirmation shows the exact adrpy command line before it runs, and adrpy's own rules are the only ones that apply -- the interface never writes a file itself.
• Mistakes caught before running. A form checks what it can, suggests the values the repository already uses, and offers a decision only to the commands its state allows.
• Read before you decide. Any decision or log entry opens rendered, from every list of them, following its links to the others.
• Accessible and in your language. Every screen meets WCAG contrast in the Default, Light and High contrast presets, keys can be changed, and the interface speaks the eleven languages adrpy supports.

adrpy-ai and adrpy-tui

They are two packages by the same author, with one clear split:

adrpy-tui runs the adrpy installed next to it, through its own Python interpreter (python -m adrpy), never whichever adrpy comes first on PATH (ADR0003V01). A repository managed with adrpy-tui is an ordinary adrpy repository: you can switch between the two, or use both, at any time.

Versions and compatibility

Each adrpy-tui is validated against one series of adrpy-ai, and requires it:

• At install time, pip installs an adrpy-ai in that range, or refuses one outside it.
• If adrpy-ai is upgraded or downgraded later, on its own (pip install -U adrpy-ai), pip installs it anyway: it prints a dependency conflict ("ERROR: pip's dependency resolver ... adrpy-tui requires adrpy-ai<0.2,>=0.1.dev0, but you have adrpy-ai 0.2.0") and still finishes successfully. adrpy-tui notices at start-up: the main menu names the adrpy-ai found and the range expected. It keeps working, but a command whose flags changed may be refused by adrpy, and that refusal is shown as adrpy gives it. Install an adrpy-ai in the range again (pip install "adrpy-ai>=0.1.dev0,<0.2"), or an adrpy-tui validated with the newer series.
• The header shows both versions, and adrpy-tui --version prints them.

The range moves one series at a time, when adrpy-tui is validated against the next adrpy-ai: its forms are checked against adrpy's own help by the tests (ADR0004V01).

Installation

Requires Python 3.11 or later, on Windows, macOS or Linux.

pip install adrpy-tui
adrpy-tui

It installs adrpy-ai with it (see Versions and compatibility), so the same environment also has adrpy-ai's adrpy and adrpy-skills commands. As a command-line tool in its own environment, with pipx: pipx install adrpy-tui -- pipx puts only adrpy-tui on your PATH (the interface runs its own adrpy either way); for the adrpy command as well, also run pipx install adrpy-ai. Straight from GitHub, a branch or a commit, without cloning: pip install git+https://github.com/FRACerqueira/adrpy-tui.git.

adrpy-ai's package is adrpy-ai; ADRpy on PyPI is an unrelated project. Don't install it in the same environment as adrpy-tui: on Windows and macOS their import folders (adrpy and ADRpy) are the same folder, and their files mix.

To install from a clone instead:

git clone https://github.com/FRACerqueira/adrpy-tui.git
cd adrpy-tui
pip install .
adrpy-tui

The source install needs a git clone: the version is read from git, so a folder from GitHub's "Download ZIP" does not install. On Windows, some file names under doc/ are long; if git clone reports "Filename too long", clone with git clone -c core.longpaths=true https://github.com/FRACerqueira/adrpy-tui.git.

To work on adrpy-tui itself (running the test suite), see Contributing.

Quick start

adrpy-tui                 # the repository in the current folder
adrpy-tui --path <repo>   # another repository
adrpy-tui --version       # the installed adrpy-tui and adrpy-ai

1. The first run asks for the interface language -- one of the eleven adrpy supports, your system's preselected. The main menu's Language changes it later. Messages that come from adrpy itself (why a command failed, a command's help) are shown as adrpy sends them, in English (ADR0005V01).
2. The main menu lists everything by use. In a folder that is not an ADR repository yet, choose Repository → Initialize; the other groups come alive once it is.
3. A form asks only for what its command needs, suggests values the repository already uses, and checks what it can before running. Ctrl+R runs it: a confirmation shows the exact adrpy command line; nothing runs until you confirm.
4. The result shows what adrpy did, its warnings, or why it refused -- with a hint to repair it when adrpy gives one.

Features

Main menu
├─ Decisions             New decision · Approve · Reject · Undo status · New version · New revision · Supersede
├─ Explore and validate  Explore (every decision → its detail and the actions its state allows) · Check
├─ Decision log          New entry · Browse the entries
├─ Repository            Initialize · Configuration · Migrate (a guided builder for hand-written files)
├─ Install config        the per-user default configuration
├─ AI skills             List · Install · Remove (adrpy-skills)
├─ Command help          the full contract of every adrpy and adrpy-skills command
├─ Change repository
├─ Language · Appearance · Keys
└─ Exit

• Choosing a decision is picking it from a list, filtered by name, showing only the ones the command can take (F2 shows them all).
• Every list shows eight rows a page, with where you are when there are more.
• Any decision or log entry can be read rendered from any list of them (F3), following its links to other decisions.

Every screen, form and component is described in Screens and forms.

Keys

The three in bold can be changed in the main menu's Keys. The line at the bottom of every screen always names the keys that work there.

Appearance and accessibility

• Three presets, in the main menu's Appearance: Default (dark), Light and High contrast, previewed as you move through them. Any color can be customized on top of the chosen preset.
• Every text meets WCAG AA contrast (4.5:1), and every state indicator and the focus border WCAG's 3:1, in every preset -- measured by the tests on everything each screen draws.
• Keyboard first: every screen opens with the keys acting where they should -- a list's arrows, a form's first field. The mouse works too.
• NO_COLOR is honored.

Where adrpy-tui keeps its settings

adrpy-tui writes one file of its own, never in your repositories: the language, the appearance and customized colors, the changed keys and the last item chosen in each menu. Next to it, error.log holds the details of the last failure of adrpy-tui itself, if one happened.

Deleting it starts again from the language choice.

Documentation

Contributing, security and license

• Contributions are welcome -- read CONTRIBUTING.md first. The interface's translations beyond English have not been reviewed by native speakers yet; reviews are very welcome.
• Report a vulnerability privately, as SECURITY.md explains. Vulnerabilities in adrpy itself belong to adrpy-ai.
• This project follows its Code of Conduct.
• MIT licensed -- see LICENSE.