xmemcli 0.0.1__py3-none-any.whl

xmemcli/_help.py

@@ -0,0 +1,720 @@
+"""Styled help pages for ``xmemcli`` (scsh-inspired layout, xmemory palette).
+
+Stdlib-only ANSI styling — no ``rich``. Color is stripped when stdout is not a
+TTY or ``NO_COLOR`` is set, so tests and pipes still see plain text.
+"""
+
+import argparse
+import os
+import re
+import sys
+from typing import Any, IO, NoReturn
+
+from ._version import CLI_NAME, __version__
+
+OPTIONS_HELP_TOPIC = "options"
+_LABEL_WIDTH = 28  # overview command list only
+_OPTION_DESC_INDENT = "      "  # description lines under a flag name
+_INTERNAL_DESTS = frozenset(
+    {
+        "command",
+        "instance_command",
+        "org_command",
+        "org_list_target",
+        "cluster_command",
+        "cluster_list_target",
+        "auth_command",
+        "schema_command",
+        "schema_migrations_command",
+        "xmd_command",
+        "help",
+        "func",
+    }
+)
+# argparse alias names we hide from the auto-generated overview (canonical names only).
+_HIDDEN_COMMAND_NAMES = frozenset(
+    {
+        "write_status",
+        "writestatus",
+        "async_write_status",
+    }
+)
+_RESET = "\x1b[0m"
+_BOLD = "\x1b[1m"
+_DIM = "\x1b[2m"
+# Console-aligned accent green (matches public Console theme tokens).
+_GREEN = "\x1b[38;2;159;232;112m"  # --xm-green / agenda accent
+
+# Short ``xmemcli help <topic>`` paths → canonical parser path (auth, write-status, quota aliases).
+_HELP_TOPIC_ALIASES: dict[tuple[str, ...], tuple[str, ...]] = {
+    ("login",): ("auth", "login"),
+    ("logout",): ("auth", "logout"),
+    ("signin",): ("auth", "login"),
+    ("signout",): ("auth", "logout"),
+    ("logoff",): ("auth", "logout"),
+    ("sign", "in"): ("auth", "login"),
+    ("sign", "out"): ("auth", "logout"),
+    ("auth", "signin",): ("auth", "login"),
+    ("auth", "signout",): ("auth", "logout"),
+    ("auth", "logoff",): ("auth", "logout"),
+    ("auth", "sign", "in"): ("auth", "login"),
+    ("auth", "sign", "out"): ("auth", "logout"),
+    ("auth", "log", "in"): ("auth", "login"),
+    ("auth", "log", "out"): ("auth", "logout"),
+    ("log", "in"): ("auth", "login"),
+    ("log", "out"): ("auth", "logout"),
+    ("write-status",): ("write-status",),
+    ("write_status",): ("write-status",),
+    ("writestatus",): ("write-status",),
+    ("async_write_status",): ("write-status",),
+    ("asyncwritestatus",): ("write-status",),
+    ("async-write-status",): ("write-status",),
+    ("quota", "get"): ("quota",),
+    ("quota-get",): ("quota",),
+}
+
+# Top-level shortcuts → canonical command paths (also listed in the overview Shortcuts section).
+
+# Curated overview — grouped; canonical command names only.
+_OVERVIEW_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
+    (
+        "Data",
+        (
+            ("write", "Write a fact to the active instance"),
+            ("write-status", "Poll async writes until they complete (one or more write_ids)"),
+            ("read", "Read from the active instance"),
+        ),
+    ),
+    (
+        "Org",
+        (
+            ("org list clusters", "Clusters visible to this credential"),
+            ("org list instances", "Instances visible to this credential"),
+            ("org list keys", "API keys visible to this credential"),
+        ),
+    ),
+    (
+        "Instances",
+        (
+            ("instance list", "List instances visible to this credential (alias for org list instances)"),
+            ("instance get", "Get a single instance by id"),
+            ("instance create", "Create a new instance from an XMD/JSON schema"),
+        ),
+    ),
+    (
+        "Schema & XMD",
+        (
+            ("schema get", "Get the live schema of an instance"),
+            ("schema update", "Replace the schema of an existing instance"),
+            ("schema dry-run", "Preview a schema migration without applying it"),
+            ("schema migrations list", "Migration history for an instance (newest first)"),
+            ("schema migrations get", "One applied migration record by id"),
+            ("xmd generate", "Synthesize an XMD schema from a description"),
+            ("xmd enhance", "Enhance (augment) an existing XMD schema"),
+            ("xmd validate", "Validate an XMD schema (format inferred from file extension)"),
+            ("xmd validate-yaml", "Validate an XMD YAML schema against the server"),
+            ("xmd validate-json", "Validate a JSON Schema against the server"),
+            ("xmd convert", "Convert JSON Schema to XMD YAML via the API"),
+        ),
+    ),
+    (
+        "Auth & meta",
+        (
+            ("auth login", "Acquire a key via Console PKCE handoff → .xmemrc.json"),
+            ("auth logout", "Remove the credential from the active .xmemrc.json"),
+            ("auth status", "Report whose key the CLI is holding (via /whoami)"),
+            ("version", "Print the CLI release version (no network)"),
+            ("status", "Local health: version and whether .xmemrc.json is present"),
+        ),
+    ),
+)
+
+
+def _use_color(stream: IO[str]) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR") or os.environ.get("CLICOLOR_FORCE"):
+        return True
+    try:
+        return stream.isatty()
+    except (OSError, AttributeError, ValueError):
+        return False
+
+
+class _Style:
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def green_bold(self, text: str) -> str:
+        if not self.enabled:
+            return text
+        return f"{_BOLD}{_GREEN}{text}{_RESET}"
+
+    def bold(self, text: str) -> str:
+        if not self.enabled:
+            return text
+        return f"{_BOLD}{text}{_RESET}"
+
+    def dim(self, text: str) -> str:
+        if not self.enabled:
+            return text
+        return f"{_DIM}{text}{_RESET}"
+
+
+def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _visible_actions(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+    # argparse exposes actions only via private _actions; there is no stable public API.
+    return [a for a in parser._actions if a.help is not argparse.SUPPRESS and a.option_strings]
+
+
+def _option_label(action: argparse.Action) -> str:
+    opts = [o for o in action.option_strings if o.startswith("-")]
+    if opts:
+        longest = opts[-1]
+        if action.metavar:
+            return f"{longest} {action.metavar}"
+        if action.nargs in (argparse.ONE_OR_MORE, argparse.ZERO_OR_MORE, "+", "*"):
+            return f"{longest} …"
+        return longest
+    if action.metavar:
+        return action.metavar
+    return action.dest
+
+
+def _help_row(style: _Style, name: str, desc: str, *, width: int = _LABEL_WIDTH) -> str:
+    bullet = style.dim("•")
+    label = style.bold(f"{name:<{width}}")
+    return f"  {bullet} {label} {style.dim(desc)}"
+
+
+def _emit(stream: IO[str], text: str = "") -> None:
+    stream.write(text + "\n")
+
+
+def _split_help_two_lines(text: str, *, first_max: int = 48) -> tuple[str, str]:
+    """Split a help blurb across two lines for the options page."""
+    collapsed = " ".join(text.split())
+    for sep in (". ", "; "):
+        if sep in collapsed:
+            head, tail = collapsed.split(sep, 1)
+            tail = tail.strip()
+            if head and tail:
+                return head + ("" if sep == "; " else "."), tail
+    if len(collapsed) <= first_max:
+        return collapsed, ""
+    cut = collapsed.rfind(" ", 0, first_max + 1)
+    if cut < 20:
+        cut = collapsed.find(" ", first_max)
+    if cut < 0:
+        return collapsed, ""
+    return collapsed[:cut], collapsed[cut + 1:]
+
+
+# Two-line blurbs for global flags (overview lists `help options` instead).
+_GLOBAL_OPTION_LINES: dict[str, tuple[str, str]] = {
+    "api_url": (
+        "API origin.",
+        "Default $XMEM_API_URL or https://api.xmemory.ai.",
+    ),
+    "api_key": (
+        "API key.",
+        "Default $XMEM_API_KEY.",
+    ),
+    "instance_id": (
+        "Target instance id.",
+        "Default $XMEM_INSTANCE_ID.",
+    ),
+    "rc_dir": (
+        "Directory for .xmemrc.json (auth login writes here).",
+        "Reads walk up toward $HOME.",
+    ),
+    "json": (
+        "Force JSON output — one JSON document on stdout.",
+        "TTY default is pretty text; pipes and redirects already emit JSON.",
+    ),
+    "verbose": (
+        "Add trace_id and console_url when the server sends them.",
+        "Never shows SQL, diff plans, or other server internals.",
+    ),
+}
+
+
+def _option_desc_lines(action: argparse.Action) -> tuple[str, str]:
+    override = _GLOBAL_OPTION_LINES.get(action.dest)
+    if override is not None:
+        return override
+    return _split_help_two_lines(action.help or "")
+
+
+def _emit_option_two_lines(
+    stream: IO[str],
+    style: _Style,
+    label: str,
+    line1: str,
+    line2: str,
+) -> None:
+    bullet = style.dim("•")
+    _emit(stream, f"  {bullet} {style.bold(label)}")
+    _emit(stream, f"{_OPTION_DESC_INDENT}{style.dim(line1)}")
+    if line2:
+        _emit(stream, f"{_OPTION_DESC_INDENT}{style.dim(line2)}")
+
+
+def normalize_help_path(path: tuple[str, ...]) -> tuple[str, ...]:
+    """Map short help topics (``help login``, ``help write-status``) to parser paths."""
+    if not path:
+        return path
+    alias = _HELP_TOPIC_ALIASES.get(path)
+    if alias is not None:
+        return alias
+    if len(path) == 1:
+        single = _HELP_TOPIC_ALIASES.get((path[0],))
+        if single is not None:
+            return single
+    return path
+
+
+def _global_options_document(root: argparse.ArgumentParser) -> dict[str, Any]:
+    return {
+        "kind": "options",
+        "cli": CLI_NAME,
+        "version": __version__,
+        "title": "Global flags for every command",
+        "usage": f"{CLI_NAME} help options",
+        "note": f"These flags apply before any subcommand, e.g. `{CLI_NAME} --json read q`.",
+        "options": [
+            {
+                "name": _option_label(action),
+                "dest": action.dest,
+                "description": list(filter(None, _option_desc_lines(action))),
+            }
+            for action in _visible_actions(root)
+        ],
+        "see_also": [f"{CLI_NAME} for the command list."],
+    }
+
+
+def _overview_document(root: argparse.ArgumentParser) -> dict[str, Any]:
+    del root  # overview is curated; parser kept for API symmetry with command topics.
+    return {
+        "kind": "overview",
+        "cli": CLI_NAME,
+        "version": __version__,
+        "title": "xmemory CLI",
+        "tagline": "Read, write, and manage xmemory instances over the HTTP API.",
+        "credentials": "Credentials: `.xmemrc.json`, `$XMEM_API_KEY`, or `auth login`.",
+        "usage": f"{CLI_NAME} <command> [options]",
+        "prefix_commands": [
+            {
+                "name": "help options",
+                "description": "Global flags (`--api-url`, `--api-key`, `--json`, …).",
+            },
+        ],
+        "sections": [
+            {
+                "name": section,
+                "commands": [{"name": name, "description": desc} for name, desc in commands],
+            }
+            for section, commands in _OVERVIEW_SECTIONS
+        ],
+        "notes": [
+            f"Global flags: `{CLI_NAME} help options`.",
+            f"More: `{CLI_NAME} help <topic>` (e.g. `{CLI_NAME} help write-status`, `{CLI_NAME} help org`).",
+            "Output: interactive terminals get one-line summaries; pipes and `--json` emit a single JSON document.",
+        ],
+    }
+
+
+def _local_command_options(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+    return [
+        a
+        for a in parser._actions
+        if a.help is not argparse.SUPPRESS
+        and a.dest not in _INTERNAL_DESTS
+        and not (
+            a.option_strings
+            and a.dest in ("json", "verbose", "api_url", "api_key", "instance_id", "rc_dir", "cluster_id")
+        )
+    ]
+
+
+def _command_usage(parser: argparse.ArgumentParser, path: tuple[str, ...]) -> str:
+    usage_parts = [CLI_NAME, *path]
+    sub = _subparsers_action(parser)
+    for action in parser._actions:
+        if action.dest in _INTERNAL_DESTS or action.option_strings:
+            continue
+        if action.metavar:
+            usage_parts.append(f"<{action.metavar}>")
+        elif action.nargs in (argparse.ONE_OR_MORE, "+"):
+            usage_parts.append("<…>")
+        else:
+            usage_parts.append(f"<{action.dest}>")
+    if sub is not None and not any(
+        a.dest not in _INTERNAL_DESTS and not a.option_strings for a in parser._actions
+    ):
+        usage_suffix = " <command> [options]"
+    else:
+        usage_suffix = " [options]"
+    return " ".join(usage_parts) + usage_suffix
+
+
+def _command_help_document(
+    root: argparse.ArgumentParser,
+    path: tuple[str, ...],
+    parser: argparse.ArgumentParser,
+) -> dict[str, Any]:
+    command = " ".join(path)
+    sub = _subparsers_action(parser)
+    subcommands: list[dict[str, str]] = []
+    if sub is not None:
+        for name, child in sub.choices.items():
+            if name in _HIDDEN_COMMAND_NAMES:
+                continue
+            label = f"{command} {name}".strip()
+            subcommands.append(
+                {
+                    "name": label,
+                    "description": _choice_help(sub, name, child),
+                }
+            )
+    return {
+        "kind": "command",
+        "cli": CLI_NAME,
+        "command": command,
+        "title": _parser_title(root, path, parser),
+        "usage": _command_usage(parser, path),
+        "options": [
+            {"name": _option_label(action), "description": action.help or ""}
+            for action in _local_command_options(parser)
+        ],
+        "subcommands": subcommands,
+        "see_also": f"{CLI_NAME} help options",
+    }
+
+
+def build_help_document(root: argparse.ArgumentParser, path: tuple[str, ...]) -> dict[str, Any]:
+    """Single source of truth for help — rendered as human text or emitted as JSON."""
+    path = normalize_help_path(path)
+    if path == (OPTIONS_HELP_TOPIC,):
+        return _global_options_document(root)
+    if not path:
+        return _overview_document(root)
+    parser = navigate_parser(root, path)
+    if parser is None:
+        topic = " ".join(path)
+        return {
+            "kind": "unknown",
+            "cli": CLI_NAME,
+            "topic": list(path),
+            "message": f"Unknown help topic: {topic} (try `{CLI_NAME}` or `{CLI_NAME} help options`).",
+        }
+    return _command_help_document(root, path, parser)
+
+
+def _render_overview_document(doc: dict[str, Any], stream: IO[str], style: _Style) -> None:
+    _emit(stream)
+    _emit(
+        stream,
+        f"{style.green_bold(doc['cli'])} {style.dim(doc['version'])} {style.bold('—')} {style.bold(doc['title'])}",
+    )
+    _emit(stream, style.dim(doc["tagline"]))
+    _emit(stream, style.dim(doc["credentials"]))
+    _emit(stream)
+    cli_name = doc["cli"]
+    _emit(
+        stream,
+        f"{style.green_bold('Usage:')} {style.bold(doc['usage'])} "
+        f"{style.dim(f'— a bare `{cli_name}` prints this help')}",
+    )
+    _emit(stream)
+    _emit(stream, style.green_bold("Commands:"))
+    for entry in doc["prefix_commands"]:
+        _emit(stream, _help_row(style, entry["name"], entry["description"]))
+    for section in doc["sections"]:
+        _emit(stream)
+        _emit(stream, style.green_bold(f"{section['name']}:"))
+        for entry in section["commands"]:
+            _emit(stream, _help_row(style, entry["name"], entry["description"]))
+    for note in doc["notes"]:
+        _emit(stream)
+        _emit(stream, style.dim(note))
+
+
+def _render_options_document(doc: dict[str, Any], stream: IO[str], style: _Style) -> None:
+    _emit(stream)
+    _emit(
+        stream,
+        f"{style.green_bold('help options')} {style.bold('—')} {style.bold(doc['title'])}",
+    )
+    _emit(stream)
+    _emit(stream, f"{style.green_bold('Usage:')} {style.bold(doc['usage'])}")
+    _emit(stream, style.dim(doc["note"]))
+    _emit(stream)
+    _emit(stream, style.green_bold("Options:"))
+    for option in doc["options"]:
+        lines = option["description"]
+        line1 = lines[0] if lines else ""
+        line2 = lines[1] if len(lines) > 1 else ""
+        _emit_option_two_lines(stream, style, option["name"], line1, line2)
+    _emit(stream)
+    _emit(stream, f"{style.green_bold('More help:')} {style.dim(f'`{doc['see_also'][0]}`.')}")
+
+
+def _render_command_document(doc: dict[str, Any], stream: IO[str], style: _Style) -> None:
+    command = doc["command"]
+    _emit(stream)
+    _emit(
+        stream,
+        f"{style.green_bold(command)} {style.bold('—')} {style.bold(doc['title'])}",
+    )
+    _emit(stream)
+    _emit(stream, f"{style.green_bold('Usage:')} {style.bold(doc['usage'])}")
+    _emit(stream)
+    if doc["options"]:
+        _emit(stream, style.green_bold("Options:"))
+        for option in doc["options"]:
+            _emit(stream, _help_row(style, option["name"], option["description"]))
+    if doc["subcommands"]:
+        _emit(stream)
+        _emit(stream, style.green_bold("Subcommands:"))
+        for entry in doc["subcommands"]:
+            _emit(stream, _help_row(style, entry["name"], entry["description"]))
+    _emit(stream)
+    _emit(
+        stream,
+        style.dim(f"Global flags (`--api-url`, `--api-key`, `--json`, …): `{doc['see_also']}`.")
+    )
+
+
+def _render_unknown_document(doc: dict[str, Any], stream: IO[str], style: _Style) -> None:
+    _emit(stream, doc["message"])
+
+
+def render_help_document(doc: dict[str, Any], *, stream: IO[str] | None = None) -> None:
+    """Render a :func:`build_help_document` payload for human terminals."""
+    out = stream if stream is not None else sys.stdout
+    style = _Style(_use_color(out))
+    kind = doc.get("kind")
+    if kind == "overview":
+        _render_overview_document(doc, out, style)
+    elif kind == "options":
+        _render_options_document(doc, out, style)
+    elif kind == "command":
+        _render_command_document(doc, out, style)
+    else:
+        _render_unknown_document(doc, out, style)
+
+
+class CliParseError(Exception):
+    """Raised instead of argparse ``SystemExit`` for human-friendly usage errors."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+_INVALID_CHOICE_RE = re.compile(
+    r"argument (?P<arg>\S+): invalid choice: '(?P<choice>[^']+)'(?: \(choose from (?P<choices>[^)]+)\))?"
+)
+
+
+def _format_cli_parse_error(message: str) -> str:
+    match = _INVALID_CHOICE_RE.search(message)
+    if match:
+        arg = match.group("arg")
+        choice = match.group("choice")
+        if arg == "command":
+            return (
+                f'{CLI_NAME}: unknown command "{choice}"\n\n'
+                f"Run `{CLI_NAME}` for an overview, or `{CLI_NAME} help <topic>`."
+            )
+        choices_raw = match.group("choices") or ""
+        choices = [part.strip().strip("'\"") for part in choices_raw.split(",") if part.strip()]
+        if choices:
+            lines = [f'{CLI_NAME}: invalid {arg.replace("_", " ")} "{choice}"', "", "Choose one of:"]
+            lines.extend(f"  {name}" for name in choices)
+            return "\n".join(lines)
+        return f'{CLI_NAME}: invalid {arg.replace("_", " ")} "{choice}"'
+
+    if message.startswith("the following arguments are required:"):
+        missing = message.split(":", 1)[1].strip()
+        return f"{CLI_NAME}: missing required argument {missing}"
+
+    if message.startswith("unrecognized arguments:"):
+        extra = message.split(":", 1)[1].strip()
+        return f"{CLI_NAME}: unrecognized argument(s): {extra}"
+
+    return f"{CLI_NAME}: {message}"
+
+
+class XmemCliArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that raises :class:`CliParseError` instead of dumping usage."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("usage", argparse.SUPPRESS)
+        kwargs.setdefault("add_help", False)
+        super().__init__(*args, **kwargs)
+
+    def error(self, message: str) -> NoReturn:
+        raise CliParseError(_format_cli_parse_error(message))
+
+
+def print_parse_error(message: str, *, stream: IO[str] | None = None) -> None:
+    out = stream if stream is not None else sys.stderr
+    style = _Style(_use_color(out))
+    for line in message.splitlines():
+        if not line:
+            _emit(out)
+            continue
+        if line.endswith(":") and line[:-1] in ("Shortcuts", "Choose one of"):
+            _emit(out, style.green_bold(line))
+            continue
+        if line.startswith(f"{CLI_NAME}:"):
+            _emit(out, style.bold(line))
+            continue
+        if line.startswith("  "):
+            _emit(out, line)
+            continue
+        if line.startswith("Run `"):
+            _emit(out, style.dim(line))
+            continue
+        _emit(out, line)
+
+
+def _strip_trailing_globals(argv: list[str]) -> list[str]:
+    """Drop trailing ``--json`` / global flags from a help topic path."""
+    out = list(argv)
+    while out:
+        tok = out[-1]
+        if tok in _GLOBAL_STORE_TRUE_FLAGS:
+            out.pop()
+            continue
+        if tok in _GLOBAL_OPTION_FLAGS:
+            out.pop()
+            if out and not out[-1].startswith("-"):
+                out.pop()
+            continue
+        break
+    return out
+
+
+def help_target(argv: list[str]) -> tuple[str, ...] | None:
+    """Return the command path before ``--help``/``-h``, ``()`` for overview, or ``None``."""
+    if not argv:
+        return ()
+    if argv in (["-h"], ["--help"]):
+        return ()
+    if argv[0] == "help":
+        return normalize_help_path(tuple(_strip_trailing_globals(argv[1:])))
+    for index, token in enumerate(argv):
+        if token in ("-h", "--help"):
+            return normalize_help_path(tuple(_strip_trailing_globals(argv[:index])))
+    return None
+
+
+# Root-level flags that may appear before the subcommand (``xmemcli --api-url … write …``).
+_GLOBAL_OPTION_FLAGS = frozenset(
+    {
+        "--api-url",
+        "--api-key",
+        "--instance-id",
+        "--rc-dir",
+        "--cluster-id",
+    }
+)
+_GLOBAL_STORE_TRUE_FLAGS = frozenset({"--json", "--verbose"})
+
+# Public aliases for xmem._parse_argv (argparse has no stable global-flag API).
+GLOBAL_OPTION_FLAGS = _GLOBAL_OPTION_FLAGS
+GLOBAL_STORE_TRUE_FLAGS = _GLOBAL_STORE_TRUE_FLAGS
+
+
+def collect_global_flags(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split *argv* into root global flags (any position) and the remaining tokens."""
+    globals_out: list[str] = []
+    command: list[str] = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok in _GLOBAL_STORE_TRUE_FLAGS:
+            globals_out.append(tok)
+            i += 1
+            continue
+        if tok in _GLOBAL_OPTION_FLAGS:
+            globals_out.append(tok)
+            if i + 1 < len(argv) and not argv[i + 1].startswith("-"):
+                globals_out.append(argv[i + 1])
+                i += 2
+            else:
+                i += 1
+            continue
+        command.append(tok)
+        i += 1
+    return globals_out, command
+
+
+def argv_without_globals(argv: list[str]) -> list[str]:
+    """Drop *leading* root-level global flags so ``--rc-dir …`` alone can mean "show overview".
+
+    Trailing globals (e.g. ``read q --json``) are preserved so machine mode stays active.
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok in _GLOBAL_STORE_TRUE_FLAGS:
+            i += 1
+            continue
+        if tok in _GLOBAL_OPTION_FLAGS:
+            i += 2 if i + 1 < len(argv) and not argv[i + 1].startswith("-") else 1
+            continue
+        break
+    while i < len(argv):
+        out.append(argv[i])
+        i += 1
+    return out
+
+
+def navigate_parser(root: argparse.ArgumentParser, path: tuple[str, ...]) -> argparse.ArgumentParser | None:
+    current = root
+    for part in path:
+        sub = _subparsers_action(current)
+        if sub is None or part not in sub.choices:
+            return None
+        current = sub.choices[part]
+    return current
+
+
+def _choice_help(sub: argparse._SubParsersAction, name: str, child: argparse.ArgumentParser) -> str:
+    for pseudo in sub._choices_actions:
+        if pseudo.dest == name:
+            return pseudo.help or ""
+    return child.description or ""
+
+
+def _parser_title(root: argparse.ArgumentParser, path: tuple[str, ...], parser: argparse.ArgumentParser) -> str:
+    if parser.description:
+        return parser.description
+    if not path:
+        return ""
+    parent = navigate_parser(root, path[:-1]) if len(path) > 1 else root
+    sub = _subparsers_action(parent) if parent is not None else None
+    if sub is not None:
+        return _choice_help(sub, path[-1], parser)
+    return " ".join(path)
+
+
+def print_help(
+    root: argparse.ArgumentParser,
+    path: tuple[str, ...],
+    *,
+    stream: IO[str] | None = None,
+) -> None:
+    render_help_document(build_help_document(root, path), stream=stream)