thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/core/extension_starter_unpacker.py

@@ -0,0 +1,493 @@
+"""Pure-logic helpers for the ``tb extension`` command group.
+
+The Typer surface lives in :mod:`thingsboard_cli.commands.extension`. This
+module contains the parts that have nothing to do with Click — edition
+resolution, the vendored-snapshot copy, lock acquisition, pom.xml
+patching, and the parsers that read state back out of a project's
+``extension/`` tree.
+
+Keeping these separate makes them easy to test in isolation and keeps the
+command file focused on user-facing wiring and subprocess management.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import stat
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from pathlib import Path
+from typing import IO
+from urllib.parse import urlparse
+
+# CLI-known editions and the Maven artifact ID each one maps to. The
+# vendored snapshot ships with PaaS as the default; the unpack code patches
+# pom.xml to match the resolved edition. CE is intentionally NOT supported
+# — the CLI authenticates via tb-pe-client, which targets PE/PaaS only.
+EDITION_TO_ARTIFACT_ID: dict[str, str] = {
+    "PE": "thingsboard-pe-client",
+    "PaaS": "thingsboard-paas-client",
+}
+
+ARTIFACT_ID_TO_EDITION: dict[str, str] = {v: k for k, v in EDITION_TO_ARTIFACT_ID.items()}
+
+# Host-suffix allowlist for cloud-edition inference. Any active profile URL
+# whose host ends in one of these is treated as ThingsBoard Cloud (PaaS).
+# Kept minimal on purpose — we only need to catch the obvious cases; the
+# user can always pass --edition to override.
+_CLOUD_HOST_SUFFIXES: tuple[str, ...] = (
+    "thingsboard.cloud",
+    "tb-cloud.io",
+)
+
+# Files that ship in the snapshot but must be executable after unpack.
+# Hatchling/wheel zip strips the +x bit, so we restore it at copy time.
+_EXEC_FILES: tuple[str, ...] = ("extension/src/main/resources/docker/start-extension.sh",)
+
+# Lock file name inside the extension dir. Holds the writer PID so we can
+# tell a live writer from a stale lock.
+LOCK_FILENAME = ".tb-extension.lock"
+
+# .gitignore entries appended by ``tb extension new``. Idempotent.
+# ``**/`` covers nested Maven modules (the main module at extension/extension/
+# and the examples module at extension/examples/) — a bare ``extension/target/``
+# wouldn't match either, since the Maven targets live one level deeper.
+GITIGNORE_LINES: tuple[str, ...] = (
+    "extension/**/target/",
+    "extension/.idea/",
+    "extension/**/*.iml",
+    "extension/.env",
+    f"extension/{LOCK_FILENAME}",
+    "extension/.last-build-error.log",
+)
+
+_DEFAULT_PORT = 8090
+_RECENT_BUILD_THRESHOLD_SECONDS = 60
+
+
+# ---------------------------------------------------------------------------
+# Edition resolution
+# ---------------------------------------------------------------------------
+
+
+def infer_edition_from_url(url: str | None) -> str | None:
+    """Return ``"PaaS"`` if the URL host looks like ThingsBoard Cloud, else None."""
+    if not url:
+        return None
+    try:
+        host = urlparse(url).hostname or ""
+    except ValueError:
+        return None
+    host = host.lower()
+    for suffix in _CLOUD_HOST_SUFFIXES:
+        if host == suffix or host.endswith("." + suffix):
+            return "PaaS"
+    return None
+
+
+def resolve_edition(flag: str | None, profile_url: str | None) -> tuple[str, str]:
+    """Resolve the target edition. Returns (edition, source_label).
+
+    Priority: explicit ``--edition`` flag > URL-inferred PaaS > default PE.
+    The CLI is bound to ``tb-pe-client``, so the only supported targets are
+    PE (self-hosted ThingsBoard Professional Edition) and PaaS (ThingsBoard
+    Cloud); PE is the safe default.
+    """
+    if flag is not None:
+        if flag not in EDITION_TO_ARTIFACT_ID:
+            raise ValueError(f"Unknown edition '{flag}'. Must be one of {sorted(EDITION_TO_ARTIFACT_ID)}.")
+        return flag, "flag"
+    inferred = infer_edition_from_url(profile_url)
+    if inferred is not None:
+        return inferred, "inferred from URL"
+    return "PE", "default"
+
+
+# ---------------------------------------------------------------------------
+# Vendored snapshot access
+# ---------------------------------------------------------------------------
+
+
+def vendored_starter_root() -> Path:
+    """Return the on-disk path to the vendored extension-starter snapshot.
+
+    Works both for installed wheels (where hatch force-includes the
+    directory at ``<site-packages>/thingsboard_cli/extension-starter/``)
+    and for source checkouts (where it lives at the repo root, sibling of
+    ``scaffold/``). Mirrors the dual-lookup pattern used by
+    :func:`thingsboard_cli.commands.project._find_scaffold_dir`.
+    """
+    # Installed package: force-included into the wheel under thingsboard_cli/
+    pkg_path = Path(__file__).resolve().parent.parent / "extension-starter"
+    if pkg_path.is_dir():
+        return pkg_path
+    # Development checkout: directory lives at the repo root
+    dev_path = Path(__file__).resolve().parents[3] / "extension-starter"
+    if dev_path.is_dir():
+        return dev_path
+    raise FileNotFoundError(f"extension-starter not found at {pkg_path} or {dev_path}. Reinstall the CLI.")
+
+
+# ---------------------------------------------------------------------------
+# Lock file
+# ---------------------------------------------------------------------------
+
+
+def _pid_alive(pid: int) -> bool:
+    """Best-effort liveness check using signal 0."""
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but we lack permission — treat as alive.
+        return True
+    return True
+
+
+class LockError(RuntimeError):
+    """Raised when :func:`acquire_lock` cannot take the per-extension lock."""
+
+
+@contextmanager
+def acquire_lock(lock_path: Path) -> Iterator[None]:
+    """Atomic per-extension lock, scoped to a ``with`` block.
+
+    Uses ``open(..., 'x')`` for atomic create. If the lock already exists,
+    the file contents are interpreted as a PID; a dead PID means the lock
+    is stale and we take it over.
+    """
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    while True:
+        try:
+            fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            try:
+                existing = lock_path.read_text(encoding="utf-8").strip()
+                holder = int(existing) if existing.isdigit() else 0
+            except OSError:
+                holder = 0
+            if not _pid_alive(holder):
+                # Stale lock — remove and retry.
+                with suppress(FileNotFoundError):
+                    lock_path.unlink()
+                continue
+            raise LockError(
+                f"{lock_path} is held by PID {holder}. Wait for it to finish or `tb extension stop` first."
+            ) from None
+        else:
+            try:
+                os.write(fd, f"{os.getpid()}\n".encode())
+            finally:
+                os.close(fd)
+            break
+    try:
+        yield
+    finally:
+        with suppress(FileNotFoundError):
+            lock_path.unlink()
+
+
+# ---------------------------------------------------------------------------
+# Unpack
+# ---------------------------------------------------------------------------
+
+
+class UnpackError(RuntimeError):
+    """Raised when ``unpack_starter`` cannot proceed safely."""
+
+
+def has_recent_build(extension_dir: Path, threshold_seconds: int = _RECENT_BUILD_THRESHOLD_SECONDS) -> bool:
+    """True if ``extension/target/`` has a file modified in the last ``threshold_seconds``."""
+    target = extension_dir / "extension" / "target"
+    if not target.is_dir():
+        return False
+    now = _now()
+    for path in target.rglob("*"):
+        try:
+            if path.is_file() and (now - path.stat().st_mtime) < threshold_seconds:
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def _now() -> float:
+    """Indirection so tests can monkeypatch time."""
+    import time
+
+    return time.time()
+
+
+def unpack_starter(
+    extension_dir: Path,
+    edition: str,
+    *,
+    force: bool = False,
+    git_status_clean: bool = True,
+    allow_dirty: bool = False,
+) -> None:
+    """Copy the vendored snapshot into ``extension_dir`` and patch it for ``edition``.
+
+    Caller must have acquired :func:`acquire_lock` on ``extension_dir / LOCK_FILENAME``
+    before invoking this. Caller must also ensure the parent directory exists.
+    """
+    if edition not in EDITION_TO_ARTIFACT_ID:
+        raise UnpackError(f"Unknown edition '{edition}'. Pick from {sorted(EDITION_TO_ARTIFACT_ID)}.")
+
+    if extension_dir.exists() and any(p.name != LOCK_FILENAME for p in extension_dir.iterdir()):
+        if not force:
+            raise UnpackError(
+                f"{extension_dir} already exists. Pass --force to overwrite "
+                "(refuses if there are uncommitted changes unless --allow-dirty)."
+            )
+        if not allow_dirty and not git_status_clean:
+            raise UnpackError(
+                f"--force refused: {extension_dir} has uncommitted changes. Commit/stash them or pass --allow-dirty."
+            )
+        if has_recent_build(extension_dir):
+            raise UnpackError(
+                f"--force refused: {extension_dir}/target has been modified in the last 60s "
+                "(build likely in flight). Run `tb extension stop` first."
+            )
+        _wipe_contents(extension_dir)
+
+    source = vendored_starter_root()
+    if not source.is_dir():
+        raise UnpackError(f"Vendored snapshot is missing at {source}. Reinstall the CLI.")
+    extension_dir.mkdir(parents=True, exist_ok=True)
+    _copytree(source, extension_dir)
+
+    # Rename README.md → STARTER.md so the agent-managed README.md can live
+    # at the top of the extension dir without clobbering starter docs.
+    readme = extension_dir / "README.md"
+    starter_doc = extension_dir / "STARTER.md"
+    if readme.is_file():
+        # If a previous unpack left STARTER.md behind, overwrite it.
+        if starter_doc.exists():
+            starter_doc.unlink()
+        readme.rename(starter_doc)
+
+    # Patch the artifact ID to match the requested edition.
+    patch_pom_edition(extension_dir / "pom.xml", edition)
+
+    # Restore +x bits that wheel packaging strips.
+    restore_exec_bits(extension_dir)
+
+
+def _wipe_contents(directory: Path) -> None:
+    """Remove everything inside ``directory`` except the active lock file."""
+    for child in directory.iterdir():
+        if child.name == LOCK_FILENAME:
+            continue
+        if child.is_dir() and not child.is_symlink():
+            shutil.rmtree(child)
+        else:
+            child.unlink()
+
+
+def _copytree(src: Path, dst: Path) -> None:
+    """Recursive copy that handles ``importlib.resources`` paths uniformly.
+
+    Uses ``shutil.copy2`` so timestamps survive; the alternative would be
+    extracting from a zip stream when installed as a wheel.
+    """
+    for entry in src.iterdir():
+        target = dst / entry.name
+        if entry.is_dir():
+            target.mkdir(exist_ok=True)
+            _copytree(entry, target)
+        else:
+            shutil.copy2(entry, target)
+
+
+def patch_pom_edition(pom_path: Path, edition: str) -> None:
+    """Rewrite ``<thingsboard-client.artifactId>...</thingsboard-client.artifactId>`` in place.
+
+    String substitution (not XML parsing) on purpose: comments and
+    formatting in the upstream pom should survive untouched.
+    """
+    if not pom_path.is_file():
+        return
+    artifact_id = EDITION_TO_ARTIFACT_ID.get(edition)
+    if artifact_id is None:
+        raise UnpackError(f"Unknown edition '{edition}'")
+    text = pom_path.read_text(encoding="utf-8")
+    new_text = re.sub(
+        r"(<thingsboard-client\.artifactId>)[^<]*(</thingsboard-client\.artifactId>)",
+        rf"\g<1>{artifact_id}\g<2>",
+        text,
+    )
+    if new_text != text:
+        pom_path.write_text(new_text, encoding="utf-8")
+
+
+def restore_exec_bits(extension_dir: Path) -> None:
+    """Re-add the user-exec bit on shell scripts that lose it via wheel zip."""
+    for relative in _EXEC_FILES:
+        target = extension_dir / relative
+        if target.is_file():
+            mode = target.stat().st_mode
+            target.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def append_gitignore_entries(project_root: Path) -> list[str]:
+    """Idempotently append GITIGNORE_LINES to ``<project>/.gitignore``.
+
+    Returns the list of lines actually added (for reporting). Existing
+    entries (exact match, ignoring leading/trailing whitespace) are kept
+    as-is.
+    """
+    gitignore = project_root / ".gitignore"
+    existing: set[str] = set()
+    if gitignore.is_file():
+        existing = {line.strip() for line in gitignore.read_text(encoding="utf-8").splitlines() if line.strip()}
+    added: list[str] = []
+    block: list[str] = []
+    for entry in GITIGNORE_LINES:
+        if entry in existing:
+            continue
+        added.append(entry)
+        block.append(entry)
+    if not block:
+        return added
+    header = "\n# Extension (managed by `tb extension`)\n"
+    text = gitignore.read_text(encoding="utf-8") if gitignore.is_file() else ""
+    if text and not text.endswith("\n"):
+        text += "\n"
+    text += header + "\n".join(block) + "\n"
+    gitignore.write_text(text, encoding="utf-8")
+    return added
+
+
+# ---------------------------------------------------------------------------
+# Read-back parsers (used by ``tb extension status``)
+# ---------------------------------------------------------------------------
+
+
+def parse_pom_artifact_id(pom_path: Path) -> str | None:
+    """Extract the configured ``thingsboard-client.artifactId`` from ``pom.xml``."""
+    if not pom_path.is_file():
+        return None
+    text = pom_path.read_text(encoding="utf-8")
+    m = re.search(r"<thingsboard-client\.artifactId>\s*([^<\s]+)\s*</thingsboard-client\.artifactId>", text)
+    return m.group(1) if m else None
+
+
+def edition_from_artifact_id(artifact_id: str | None) -> str | None:
+    """Inverse of EDITION_TO_ARTIFACT_ID."""
+    if artifact_id is None:
+        return None
+    return ARTIFACT_ID_TO_EDITION.get(artifact_id)
+
+
+def application_yml_path(extension_dir: Path) -> Path:
+    """Real location of the Spring Boot application.yml inside the starter.
+
+    The design referred to ``extension/config/application.yml`` for the
+    runtime port; in the actual starter the file lives under
+    ``extension/src/main/resources/application.yml``. We read the truth.
+    """
+    return extension_dir / "extension" / "src" / "main" / "resources" / "application.yml"
+
+
+def read_extension_port(extension_dir: Path) -> int:
+    """Discover the extension's HTTP port.
+
+    Resolution: ``EXTENSION_PORT`` env var > literal in ``application.yml`` >
+    placeholder default in ``application.yml`` > ``8090``. The env-var name
+    matches the placeholder in the generated ``application.yml`` and the var
+    referenced by both compose files, so users only need to learn one name.
+    """
+    env_port = os.environ.get("EXTENSION_PORT")
+    if env_port and env_port.isdigit():
+        return int(env_port)
+    yml_port = _read_port_from_yaml(application_yml_path(extension_dir))
+    return yml_port if yml_port is not None else _DEFAULT_PORT
+
+
+def _read_port_from_yaml(yml_path: Path) -> int | None:
+    if not yml_path.is_file():
+        return None
+    text = yml_path.read_text(encoding="utf-8")
+    # We avoid pulling in PyYAML for one key; the file shape is stable.
+    # Match ``server:`` followed by an indented ``port:`` value.
+    m = re.search(r"(?ms)^server:\s*\n(?:\s+\S.*\n)*?\s+port:\s*(.+?)\s*$", text)
+    if not m:
+        return None
+    value = m.group(1).strip()
+    return _coerce_yaml_port(value)
+
+
+def _coerce_yaml_port(value: str) -> int | None:
+    """Turn a ``server.port`` value into an int.
+
+    Handles plain numbers and Spring Boot placeholders like
+    ``${EXTENSION_PORT:8090}`` or ``${EXTENSION_PORT}``.
+    """
+    if value.isdigit():
+        return int(value)
+    m = re.match(r"\$\{([^:}]+)(?::([^}]+))?\}", value)
+    if m:
+        env_name, default = m.group(1), m.group(2)
+        env_val = os.environ.get(env_name)
+        if env_val and env_val.isdigit():
+            return int(env_val)
+        if default and default.isdigit():
+            return int(default)
+    return None
+
+
+def latest_target_jar(extension_dir: Path) -> Path | None:
+    """Return the most recently modified runnable JAR under ``extension/target/``.
+
+    Spring Boot's ``repackage`` goal leaves the pre-repackage artifact next
+    to the runnable JAR as ``*.jar.original``; ``-sources.jar`` and
+    ``-javadoc.jar`` are also commonly present. Skip those so the status
+    display always reflects the actually-runnable artifact, even when one
+    of the variants happens to be newer.
+    """
+    target = extension_dir / "extension" / "target"
+    if not target.is_dir():
+        return None
+    jars = [
+        p
+        for p in target.glob("*.jar")
+        if p.is_file()
+        and not p.name.endswith(".jar.original")
+        and not p.name.endswith("-sources.jar")
+        and not p.name.endswith("-javadoc.jar")
+    ]
+    if not jars:
+        return None
+    return max(jars, key=lambda p: p.stat().st_mtime)
+
+
+def is_inside_solution_dir(cwd: Path, project_root: Path) -> bool:
+    """True if ``cwd`` is inside ``<project>/solutions/<slug>/``.
+
+    Used to surface a heads-up when the user runs ``tb extension`` from
+    inside a solution dir — the command still works (it operates on the
+    project root), but the visual cue helps avoid confusion.
+    """
+    try:
+        rel = cwd.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        return False
+    parts = rel.parts
+    return len(parts) >= 2 and parts[0] == "solutions"
+
+
+def write_initial_readme(extension_dir: Path, project_name: str) -> None:
+    """Render and write the fresh agent-managed README.md."""
+    from thingsboard_cli.core.extension_manifest import render_initial
+
+    (extension_dir / "README.md").write_text(render_initial(project_name), encoding="utf-8")
+
+
+def write_pid(fd: IO[bytes], pid: int) -> None:  # pragma: no cover — kept for symmetry
+    fd.write(f"{pid}\n".encode())

thingsboard_cli/core/git_dirty.py

@@ -0,0 +1,118 @@
+"""Narrow git-dirty check helper for ``tb pull``.
+
+Single responsibility: given a list of absolute paths, ask git whether any of
+them have uncommitted changes (modified, staged, or untracked). No staging,
+no committing, no branch inspection — just a subset porcelain query.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DirtyCheckResult:
+    """Outcome of a git dirty check over a list of paths.
+
+    Attributes:
+        in_git_repo: True if ``repo_root`` is inside a git work tree.
+        dirty_paths: Absolute paths reported as dirty by ``git status``. Always
+            empty when ``in_git_repo`` is False.
+    """
+
+    in_git_repo: bool
+    dirty_paths: list[Path] = field(default_factory=list)
+
+
+def is_inside_work_tree(repo_root: Path) -> bool:
+    """Return True iff ``repo_root`` is inside a git work tree.
+
+    Mirrors the pattern used in ``commands/project.py``: a non-zero exit (or a
+    missing ``git`` binary) means "not in a git repo" — no exception is raised.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            cwd=repo_root,
+        )
+    except FileNotFoundError:
+        return False
+    if result.returncode != 0:
+        return False
+    return result.stdout.strip() == "true"
+
+
+def _parse_porcelain_z(stdout: str, repo_root: Path) -> list[Path]:
+    """Parse NUL-separated ``git status -z --porcelain`` output.
+
+    With ``-z`` git emits records as ``XY <space> <path>\\x00`` with no quoting,
+    so paths containing spaces or non-ASCII bytes round-trip cleanly. Renames
+    and copies (status starting with ``R`` or ``C``) emit *two* NUL-separated
+    chunks — the new path first, then the old path — and we report the new
+    path (that's what the caller's pull would overwrite).
+    """
+    dirty: list[Path] = []
+    records = stdout.split("\x00")
+    # split() on a trailing NUL gives an empty final element; iterate by index
+    # so a rename can consume the next record without re-entering the loop.
+    i = 0
+    while i < len(records):
+        record = records[i]
+        i += 1
+        if len(record) < 4:
+            # Empty trailer or stray short record — skip.
+            continue
+        status = record[:2]
+        path = record[3:]
+        if status[0] in ("R", "C"):
+            # Consume the paired old-path record; we only report the new path.
+            i += 1
+        dirty.append((repo_root / path).resolve())
+    return dirty
+
+
+def check_paths_dirty(repo_root: Path, paths: Iterable[Path]) -> DirtyCheckResult:
+    """Return a structured report of which of *paths* are dirty in git.
+
+    ``repo_root`` is the project root (the directory git commands run from).
+    ``paths`` are absolute file paths the caller wants to check.
+
+    If ``repo_root`` is not inside a git work tree (or ``git`` isn't
+    installed), returns ``DirtyCheckResult(in_git_repo=False, dirty_paths=[])``
+    without raising. Otherwise runs ``git status -z --porcelain -- <paths>``
+    and returns the list of dirty paths (any porcelain entry counts).
+
+    Raises:
+        RuntimeError: if ``git status`` exits non-zero after we've already
+            confirmed we're inside a work tree. Silently downgrading this to
+            "not in repo" would let ``tb pull`` overwrite local files when the
+            real problem is a corrupt repo or a permissions issue.
+    """
+    path_list = list(paths)
+
+    if not is_inside_work_tree(repo_root):
+        return DirtyCheckResult(in_git_repo=False, dirty_paths=[])
+
+    if not path_list:
+        # Empty subset → trivially clean. Skip the subprocess call.
+        return DirtyCheckResult(in_git_repo=True, dirty_paths=[])
+
+    cmd = ["git", "status", "-z", "--porcelain", "--"]
+    cmd.extend(str(p) for p in path_list)
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        cwd=repo_root,
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "no output"
+        raise RuntimeError(f"git status failed: {detail}")
+
+    dirty = _parse_porcelain_z(result.stdout, repo_root)
+    return DirtyCheckResult(in_git_repo=True, dirty_paths=dirty)

thingsboard_cli/core/interactive_pull/__init__.py

@@ -0,0 +1,41 @@
+"""Interactive picker for ``tb pull -i``.
+
+Public entry: :func:`run_interactive_pull`. Opens a Textual app, blocks
+until the user confirms a selection or cancels, and returns either a list
+of ``{"entityType", "id"}`` dicts (for the ``internalIds`` field on
+``/api/solution/export``) or ``None`` on cancel.
+
+Textual is imported lazily *inside* :func:`run_interactive_pull` so that
+non-interactive ``tb`` invocations pay zero Textual startup cost.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from thingsboard_cli.commands.pull import _PullOptions
+
+
+def run_interactive_pull(
+    *,
+    opts: _PullOptions,
+    solution_dir: Path,
+    client: Any,
+    profile_label: str | None = None,
+) -> list[dict[str, str]] | None:
+    """Open the Textual picker. Block until confirm or cancel.
+
+    Returns a list of ``{"entityType": str, "id": str}`` dicts suitable for
+    posting as ``internalIds`` on ``/api/solution/export``, or ``None`` if
+    the user cancelled. *profile_label* is the resolved profile name shown in
+    the picker chrome (falls back to ``opts.profile`` then ``default``).
+    """
+    from thingsboard_cli.core.interactive_pull.app import PickerApp
+
+    app = PickerApp(opts=opts, solution_dir=solution_dir, client=client, profile_label=profile_label)
+    app.run()
+    # The confirmed selection lives on ``app.result``; ``App.run()`` returns the
+    # value passed to ``exit()``, which the picker leaves at None.
+    return app.result