aeat.application.operator_surface._help module

Backend-owned help and discovery documents for accepted CLI roots.

The builders return typed HelpDocument and RootLandingReport records for the contract-backed root, config, and app help surfaces declared by application.operator_surface. CLI adapters render these records through the shared output boundary; they do not own the command inventory.

This module is manifest-discovery only: it builds in-memory documents from locale keys and caller-supplied profile state. It does not inspect storage, read environment variables, construct repositories, or decide whether the bare root should render the landing report or the overview status report.

build_help_document(surface)

Return the curated help document for surface.

Accepts a HelpSurface member or its string token and returns a HelpDocument with workflow-ordered HelpSection and HelpEntry records for the requested surface. The returned document is consumed by render_help_text() and by the root/app envelope paths.

Return type:

HelpDocument

Parameters:

surface (HelpSurface | str)

build_root_landing_report(active_profile)

Return the RootLandingReport for caller-supplied profile state.

The caller owns active-profile discovery and passes the projected display label here. A present profile points operators at aeat app overview status; a missing profile points at profile creation. The CLI root callback decides whether this landing report or the full overview status is emitted under root.status.

Return type:

RootLandingReport

Parameters:

active_profile (str | None)

render_help_text(document)

Render a curated HelpDocument as terminal-safe plain text.

The renderer preserves the backend-owned ordering of HelpSection and HelpEntry records, aligns command columns, and returns text for CLI adapters to pass through their normal output boundary. It does not inspect the live CLI tree; conformance tests own the check that rendered command rows still map to mounted command families.

Return type:

str

Parameters:

document (HelpDocument)

render_root_landing_text(report)

Render the compact single-line view of a RootLandingReport.

New root CLI output uses a multi-line entrypoint renderer for the text half of the root.status envelope. This helper remains the application-level plain-text formatter for callers that need the compact message / next-command template.

Return type:

str

Parameters:

report (RootLandingReport)