adrpy-tui

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.

A first run: the language, Repository → Initialize, a new decision, Approve, then Explore.

Table of Contents

• Motivation and Benefits
• adrpy-ai and adrpy-tui
• Versions and compatibility
• Installation
• Terminal requirements
• 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.

Whether adrpy-tui then runs from any folder depends on where it was installed. Into a Python whose Scripts folder (Windows) or bin folder (macOS, Linux) is on your PATH, it does. With pip install --user, that folder is often not on PATH, and pip says so ("... which is not on PATH"): add the folder it names to PATH. Into a virtual environment, only while that environment is activated. pipx puts its commands on PATH; if it warns that its folder is not, run pipx ensurepath once and open a new terminal. To check, run where adrpy-tui on Windows (where.exe adrpy-tui in PowerShell) or command -v adrpy-tui on macOS and Linux. Run from any folder, adrpy-tui opens the repository in that folder (see Quick start).

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.

Terminal requirements

• At least 80 columns by 24 rows. Every screen is built for it: what does not fit scrolls, and the tests open every screen and dialog at 80×24. A larger terminal shows more at once (the header alone takes 11 rows). Below 80 columns, a dialog's button can be cut.
• A font for the interface's languages. The language list, and the interface once translated, show Japanese, Korean, Chinese and Russian text: a terminal whose font (or the fonts it falls back to) lacks those scripts draws them as boxes. A font family such as Noto CJK covers them.
• When Ctrl+R runs nothing, a required field (marked *) is empty or not valid: a notification names it and why ("Not run: Decision — Required."), its message shows under it, and the focus moves there. In a list, Enter moves from the filter to the list, and Enter again chooses the highlighted decision.

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 · Editor · Updates
└─ 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.

• A Proposed decision's text in your own editor. Choose it under Editor, by its program's name: vim, nvim, nano, micro, hx, code (VS Code), codium (VSCodium), subl (Sublime Text), kate, gedit, gvim or notepad, as found on your PATH; None is the default, and then you edit the file yourself, its text being the template. With one chosen, a new decision, version, revision or successor can open in it once created, and a Proposed decision's detail offers Edit. The TUI waits while the file is open -- a terminal editor takes the terminal, a window one can be left with Stop waiting -- and runs Check once it is closed; while a command or an editor you left still runs, Edit is refused until it ends, and what is saved in an editor you stopped waiting for is not checked. The TUI never writes the file itself (ADR0007V01). An Accepted decision's text changes through New revision or New version.

• A newer adrpy-tui is said on the main menu. On every start the TUI asks PyPI (https://pypi.org/pypi/adrpy-tui/json) for adrpy-tui's versions, in the background, and names a newer one next to the installed one; it never updates itself. The first start checks too. Under Updates, turn the check off -- the TUI then reaches no network at all -- or include pre-releases, off by default; the screen says what the check found in this run (ADR0008V01).

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, the editor chosen, whether it checks PyPI for a newer version and whether pre-releases count, 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.