kevinveenbirkenbachandClaude Opus 4.7
a26bfc4e94
Module moves (with imports, paths, argv literals, scripts, docs, and
parents[N] formulas updated in lockstep):
- cli/deploy -> cli/administration/deploy
- cli/validate/inventory -> cli/administration/inventory/validate
- cli/vault -> cli/administration/secrets/vault
- cli/administration/inventory/encrypt -> cli/administration/secrets/seal
- cli/mirror -> cli/contributing/mirror
The new cli/administration/secrets cluster collocates the whole-file
ansible-vault wrapper next to the inventory-aware per-field sealer.
The user-facing CLI subcommand paths follow the package layout, e.g.
"infinito administration deploy dedicated <inv>" and
"infinito administration inventory validate <inv>".
Help system redesign in cli/core/{discovery,help,app}.py:
- Discovery now distinguishes runnable commands (directories with
__main__.py) from category folders (directories that only group
further commands). Empty support packages are filtered out.
- Each category folder MAY carry a README.md; its H1 heading is used
as the title and its first paragraph as the one-line description in
the help output.
- "infinito" / "infinito --help" prints only the top-level entries
(one level deep). "infinito <category>" navigates into a folder and
shows its sub-folders and commands one level deep, with the README
title as the page heading and the invocation as a dim subtitle.
- New "--tree [N]" flag walks the tree under the (optional) path
prefix recursively. N caps the depth (1-based); omit N for an
unbounded walk. The output uses Unicode tree connectors, an emoji
per entry (folder for categories, gear for commands), a globally
aligned description column, and multi-line wrapped descriptions
with tree-continuity bars on continuation lines.
- Category and command listings use the full invocation
("infinito meta callorder") rather than the bare leaf name, so the
output is copy-pasteable.
Convention doc + 17 CLI READMEs:
- New docs/contributing/artefact/files/cli/readme_md.md describes the
H1+paragraph layout the help system reads, and how it differs from
role/docs READMEs.
- README.md added for cli/{administration, build, contributing, meta}
and their immediate sub-folders, plus cli/meta/roles/applications
and its resolution sub-folder. Each follows the "title with trailing
emoji + single descriptive paragraph" convention.
Mirror resolver/sync description strings (the help system reads them
from argparse --help output) added so they no longer surface as
"options:" in the global index. cli/mirror/cleanup already had a
description and is unchanged.
Fixes uncovered by the move:
- import unittest.mock added to four dedicated-deploy tests so
unittest.mock.patch resolves under stdlib unittest discovery
(Python 3.13 no longer surfaces unittest.mock through "import
unittest" alone).
- parents[N] index in the new
cli/administration/inventory/validate/__init__.py corrected from
3 to 4 to match the deeper layout.
- test_paths.INVENTORY_VALIDATOR_PATH assertion and test_runner
substring assertions updated to match the new validator path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.9 KiB
CLI README 📄
This page covers README.md files stored inside cli/ category folders (directories under cli/ that group sub-commands but do not themselves contain a __main__.py).
For general documentation rules such as links, writing style, RFC 2119 keywords, and emoji placement, see documentation.md.
Purpose 🎯
A CLI category folder MAY contain a README.md that describes the category.
The first paragraph of that file is read by the CLI help system (help.py) and surfaced as the category's one-line description in infinito --help, infinito <category>, and infinito --tree.
Scope 📋
A CLI README.md MUST stay focused on what kind of sub-commands the category groups.
A CLI README.md MUST NOT list the sub-commands themselves, because the CLI help system already does that automatically.
A CLI README.md MUST NOT describe individual sub-command flags or option signatures, because each runnable sub-command exposes its own argparse --help.
Structure 📐
A CLI README.md MUST contain at least an H1 title and one description paragraph.
Further sections are OPTIONAL and MAY be added when contributors need extra context that does not belong in the runtime help.
1. Title (required) 🏷️
The H1 heading MUST be the human-readable name of the category, ending with a single trailing emoji that hints at the topic.
# Administration 🛠️
2. Description (required) 📖
A single paragraph (one or two sentences) immediately below the H1. It MUST explain what kind of commands live in the directory. It MUST NOT name the sub-commands explicitly. It MUST stand on its own when extracted by the CLI help system, which collapses multi-line paragraphs into a single line.
# Administration 🛠️
Operator-facing tooling for provisioning inventories, running dedicated deploys, and managing host secrets.
3. Further sections (optional) ➕
Additional sections (for example "When to use", "Conventions", "Background") MAY follow the description paragraph.
They MUST be separated from the description paragraph by a blank line so the help-extraction heuristic stops at the right place.
They MUST NOT duplicate content that the sub-commands' own --help output already exposes.
Formatting Rules 📏
- The H1 emoji MUST come after the title text, not before it.
- The description paragraph MUST be a single paragraph (no blank lines inside it).
- Link text MUST follow the link rules in documentation.md.
- Body text MAY use emojis when they aid readability.
Runnable sub-commands ⚙️
Sub-commands inside a category folder (directories with their own __main__.py) MUST NOT carry a README.md.
Their description is taken from the argparse description= argument that the help system reads via python -m <module> --help.
For an example see help.py.