thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/commands/extension.py

@@ -0,0 +1,1364 @@
+"""``tb extension`` command group.
+
+Lifecycle commands for the per-project ThingsBoard extension: unpack the
+vendored starter, build/run/test it, tail logs, and stop a running
+instance. Heavy lifting (snapshot copy, edition resolution, pom patching)
+lives in :mod:`thingsboard_cli.core.extension_starter_unpacker`; this
+file owns the user-facing wiring and subprocess management.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import textwrap
+import time
+from contextlib import suppress
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from thingsboard_cli.commands.project import find_project_root
+from thingsboard_cli.config.resolver import resolve_profile
+from thingsboard_cli.core import extension_starter_unpacker as unpacker
+from thingsboard_cli.core.extension_manifest import parse_file
+from thingsboard_cli.core.git_dirty import is_inside_work_tree
+from thingsboard_cli.core.local import (
+    ExtensionNameError,
+    atomic_write_text,
+    diagnose_extension_name,
+    read_extension_name,
+    validate_extension_name,
+    write_extension_name,
+)
+from thingsboard_cli.core.maven_runner import run_mvn
+from thingsboard_cli.core.output import console, error, success, warning
+
+extension_app = typer.Typer(help="Manage a custom backend extension for the project.")
+
+
+# ---------------------------------------------------------------------------
+# Hint templates
+# ---------------------------------------------------------------------------
+#
+# Single-source-of-truth strings for the lifecycle "Next:" hints printed by
+# ``tb extension new``/``build``/``run``/``push``. The HAProxy snippet is the
+# canonical copy-paste payload — kept here as a literal so the run and push
+# hints stay in sync without drifting from each other.
+
+HAPROXY_SNIPPET = (
+    "  acl is_extension path_beg /api/extension/\n"
+    "  use_backend thingsboard_extension if is_extension\n"
+    "\n"
+    "  backend thingsboard_extension\n"
+    "      server extension 127.0.0.1:8090 check"
+)
+
+
+NEW_HINT_TEMPLATE = (
+    "Next:\n  tb extension build      build the docker image\n  tb extension run        start it locally on :8090"
+)
+
+
+BUILD_HINT_TEMPLATE = (
+    "Next:\n"
+    "  tb extension run                          smoke test locally\n"
+    "  tb extension push --image-name <reg>/foo  publish to a registry"
+)
+
+
+# ``{haproxy}`` is filled with HAPROXY_SNIPPET; ``{port}`` is the resolved
+# extension port (from ``application.yml``'s ``server.port`` — see
+# ``unpacker.read_extension_port``). The literal ``{on-premise,cloud}`` brace
+# pair is doubled so ``.format()`` emits it verbatim.
+#
+# The ``restart`` wording deliberately does NOT promise "reload after code
+# edit" — in docker mode, ``restart`` reuses the same image (rebuild via
+# ``tb extension build`` first to pick up new code).
+RUN_HINT_TEMPLATE = (
+    "Local:\n"
+    "  tb extension logs -f       tail logs\n"
+    "  tb extension restart       bounce the container (rebuild first with `tb extension build`)\n"
+    "  tb extension stop          stop the container\n"
+    "\n"
+    "Wire from a rule chain (REST API Call node):\n"
+    "  POST http://localhost:{port}/api/extension/<your-endpoint>\n"
+    "  Header: X-Authorization: ApiKey <your-api-key>\n"
+    "  (Reachable on-prem only — Cloud calls your published image.)\n"
+    "\n"
+    "Wire from a widget (when ThingsBoard runs on this host) — add to your\n"
+    "existing HAProxy frontend, before the TB backend ACL:\n"
+    "\n"
+    "{haproxy}\n"
+    "\n"
+    "Widget JS templates: extension/examples/widgets/{{on-premise,cloud}}-button.js"
+)
+
+
+# ``{ref}`` is the user-supplied --image-name. ``{haproxy_indented}`` is
+# HAPROXY_SNIPPET indented by 5 spaces so it lines up under the "5."
+# numbered-list step.
+PUSH_HINT_TEMPLATE = (
+    "Deploy on the host that runs ThingsBoard:\n"
+    "\n"
+    "  1. Copy this project's extension/deploy/ directory to that host, then cd into it\n"
+    "  2. cp .env.example .env\n"
+    "  3. Edit .env: set IMAGE_NAME={ref}\n"
+    "       (Cloud TB: also set CORS_ALLOWED_ORIGINS, or widget calls get blocked)\n"
+    "  4. docker compose up -d\n"
+    "  5. For dashboard widgets, apply this snippet to your HAProxy frontend:\n"
+    "\n"
+    "{haproxy_indented}"
+)
+
+
+SET_EDITION_HINT = "Next:\n  tb extension build      rebuild to regenerate API docs for the new edition"
+
+
+# Default platform passed to ``docker build --platform``. The literal lives in
+# one place so the build/run defaults, restart's reuse, and JAR-mode warning
+# checks all derive from the same value. ``--platform`` is exposed as
+# ``Annotated[str | None, ...] = None`` on user-facing commands so we can
+# distinguish "user typed --platform" from "user accepted the default" — the
+# JAR-mode warning fires only on an explicit value.
+_DEFAULT_PLATFORM = "linux/amd64"
+
+
+# ---------------------------------------------------------------------------
+# Shared resolution helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_project_root() -> Path:
+    """Return ``find_project_root()`` or exit with a clear error."""
+    project_root = find_project_root()
+    if project_root is None:
+        error("Not inside a ThingsBoard project. Run `tb init` first.")
+    return project_root
+
+
+def _extension_dir(project_root: Path) -> Path:
+    return project_root / "extension"
+
+
+def _git_status_is_clean(extension_dir: Path) -> bool:
+    """Return True if ``extension/`` has no uncommitted changes.
+
+    Uses ``git rev-parse --is-inside-work-tree`` so layouts where the
+    extension lives inside a parent repo (monorepo, dev clone under a
+    larger workspace) are detected — a literal ``.git``-exists check
+    would miss those and let ``--force`` silently overwrite a dirty
+    surrounding tree.
+    """
+    # No git on PATH (or not inside a work tree) → can't check. Treat as
+    # clean and let the user pass --allow-dirty if they want to be explicit.
+    if not is_inside_work_tree(extension_dir.parent):
+        return True
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain", "--", str(extension_dir.name)],
+            cwd=extension_dir.parent,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return True
+    return result.returncode == 0 and not result.stdout.strip()
+
+
+def _resolve_profile_url(profile_name: str | None = None) -> str | None:
+    """Return the active profile's URL, or None if no profile is configured."""
+    try:
+        profile = resolve_profile(profile_name=profile_name)
+        return profile.url or None
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# tb extension new
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("new", help="Create a new extension scaffold under <project>/extension/.")
+def new(
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            help="Local Docker image name for this extension (written to thingsboard.json).",
+        ),
+    ] = None,
+    edition: Annotated[
+        str | None,
+        typer.Option("--edition", help="Target edition (PE for self-hosted, PaaS for ThingsBoard Cloud)."),
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing extension/ dir.")] = False,
+    allow_dirty: Annotated[
+        bool,
+        typer.Option(
+            "--allow-dirty",
+            help="With --force, proceed even if extension/ has uncommitted changes.",
+        ),
+    ] = False,
+) -> None:
+    project_root = _require_project_root()
+    cwd_in_solution = unpacker.is_inside_solution_dir(Path.cwd(), project_root)
+    if cwd_in_solution:
+        warning("Running from inside a solutions/<slug>/ dir — operating on the project root.")
+
+    extension_dir = _extension_dir(project_root)
+    profile_url = _resolve_profile_url()
+    try:
+        resolved_edition, source = unpacker.resolve_edition(edition, profile_url)
+    except ValueError as exc:
+        error(str(exc))
+    console.print(f"Edition: {resolved_edition} ({source})")
+
+    # Resolve the name BEFORE unpacking so an invalid --name never reaches
+    # the disk-edit phase. The interactive prompt loops on invalid input
+    # without ever touching extension/.
+    if name is None:
+        if not _stdin_is_a_tty():
+            error("Pass `--name <name>` — running in non-interactive mode.")
+        resolved_name = _prompt_for_extension_name()
+    else:
+        try:
+            validate_extension_name(name)
+        except ExtensionNameError as exc:
+            error(str(exc))
+        resolved_name = name
+
+    lock_path = extension_dir / unpacker.LOCK_FILENAME
+    git_clean = _git_status_is_clean(extension_dir)
+    try:
+        with unpacker.acquire_lock(lock_path):
+            try:
+                unpacker.unpack_starter(
+                    extension_dir,
+                    resolved_edition,
+                    force=force,
+                    git_status_clean=git_clean,
+                    allow_dirty=allow_dirty,
+                )
+            except unpacker.UnpackError as exc:
+                error(str(exc))
+            project_name = project_root.name
+            unpacker.write_initial_readme(extension_dir, project_name)
+    except unpacker.LockError as exc:
+        error(str(exc))
+
+    added = unpacker.append_gitignore_entries(project_root)
+    if added:
+        console.print(f"Updated .gitignore: appended {len(added)} entr{'y' if len(added) == 1 else 'ies'}.")
+
+    # Only claim the name in the manifest once the scaffold is in place —
+    # if unpack failed and we exited above, the manifest is left untouched.
+    # Catch ExtensionNameError so a malformed thingsboard.json surfaces as a
+    # clean error() panel instead of leaking the class name through the
+    # global exception fallback in main.py.
+    try:
+        write_extension_name(project_root, resolved_name)
+    except ExtensionNameError as exc:
+        error(str(exc))
+
+    # The success panel is the LAST happy-path output — printing it before
+    # the manifest write would let a write failure produce a "succeeded"
+    # line the user has already seen.
+    _print_success_panel(
+        "Created",
+        [f"Created extension '{resolved_name}' at extension/"],
+        next_hint=NEW_HINT_TEMPLATE,
+    )
+
+
+def _stdin_is_a_tty() -> bool:
+    """Return True iff this process's stdin is attached to a terminal.
+
+    Split out from ``new()`` so tests can monkeypatch a single function on the
+    module rather than fight ``sys.stdin`` replacement under ``CliRunner``.
+    """
+    return sys.stdin.isatty()
+
+
+def _prompt_for_extension_name() -> str:
+    """Print the orientation paragraph (once), then prompt + validate until valid.
+
+    Empty input or a name that fails :func:`validate_extension_name` re-prompts.
+    The orientation paragraph fires exactly once; the prompt label is kept
+    short ("Extension name") because the paragraph above it carries the
+    explanation.
+    """
+    console.print(
+        "This name will be used as the local Docker image name for your extension\n"
+        "(will appear as <name>:latest, <name>:1.2.3, etc. depending on your build).\n"
+        "Pick something descriptive — your project's slug, your company short-name, etc.\n"
+        "You can change it later with `tb extension rename <new-name>`."
+    )
+    while True:
+        candidate = typer.prompt("Extension name", default="", show_default=False).strip()
+        if not candidate:
+            console.print("[red]Extension name cannot be empty.[/red]")
+            continue
+        try:
+            validate_extension_name(candidate)
+        except ExtensionNameError as exc:
+            console.print(f"[red]{exc}[/red]")
+            continue
+        return candidate
+
+
+# ---------------------------------------------------------------------------
+# tb extension rename
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("rename", help="Change the local Docker image name for this project's extension.")
+def rename(
+    new_name: Annotated[
+        str,
+        typer.Argument(help="New local Docker image name (written to thingsboard.json)."),
+    ],
+) -> None:
+    project_root = _require_project_root()
+    try:
+        validate_extension_name(new_name)
+    except ExtensionNameError as exc:
+        error(str(exc))
+
+    # Read the previous name BEFORE the write so the rename message can show
+    # the old → new transition. ``read_extension_name`` returns ``None`` for
+    # malformed manifests; ``write_extension_name`` is the one that surfaces
+    # the malformed-manifest error path.
+    old_name = read_extension_name(project_root)
+    try:
+        write_extension_name(project_root, new_name)
+    except ExtensionNameError as exc:
+        error(str(exc))
+
+    if old_name is None:
+        success(f"Set extension name to {new_name}.")
+        return
+    success(f"Renamed extension: {old_name} → {new_name}")
+    console.print(
+        f"[dim]Note: existing local docker images tagged `{old_name}:*` remain on your daemon\n"
+        f"      until you remove them (e.g. `docker image rm {old_name}:latest`).[/dim]"
+    )
+
+
+# ---------------------------------------------------------------------------
+# tb extension set-edition
+# ---------------------------------------------------------------------------
+
+
+class _SetEditionTarget(StrEnum):
+    """Closed enum of editions accepted by ``tb extension set-edition``."""
+
+    PE = "pe"
+    PAAS = "paas"
+
+
+_SET_EDITION_TO_ARTIFACT_ID: dict[_SetEditionTarget, str] = {
+    _SetEditionTarget.PE: "thingsboard-pe-client",
+    _SetEditionTarget.PAAS: "thingsboard-paas-client",
+}
+
+
+_SET_EDITION_DISPLAY: dict[_SetEditionTarget, str] = {
+    _SetEditionTarget.PE: "PE",
+    _SetEditionTarget.PAAS: "PaaS",
+}
+
+
+# Line-anchored on purpose: the spec mandates a single-line surgical edit so
+# the rest of pom.xml — comments, formatting, neighboring properties — never
+# moves. Matches the artifactId tag plus surrounding whitespace; the
+# capturing group preserves the original indentation.
+_ARTIFACT_ID_LINE_RE = re.compile(
+    r"^(\s*)<thingsboard-client\.artifactId>.*?</thingsboard-client\.artifactId>\s*$",
+    re.MULTILINE,
+)
+
+
+class _ArtifactIdLineMissingError(Exception):
+    """Raised when ``pom.xml`` has no ``<thingsboard-client.artifactId>`` line to patch."""
+
+
+def _patch_root_pom_edition(pom_path: Path, artifact_id: str) -> None:
+    """Rewrite the single ``<thingsboard-client.artifactId>`` line in ``pom_path`` in place.
+
+    Reads the file as text (no XML parsing) and performs a regex-anchored
+    single-line substitution that preserves the original indentation. Writes
+    back via :func:`atomic_write_text` so an interrupted call can never leave
+    a half-written pom on disk. Raises :class:`_ArtifactIdLineMissingError`
+    when no matching line exists — the caller decides how to surface that.
+    """
+    text = pom_path.read_text(encoding="utf-8")
+    new_text, count = _ARTIFACT_ID_LINE_RE.subn(
+        rf"\g<1><thingsboard-client.artifactId>{artifact_id}</thingsboard-client.artifactId>",
+        text,
+    )
+    if count == 0:
+        raise _ArtifactIdLineMissingError()
+    # Idempotent no-op: avoid an atomic-write cycle when the file already
+    # holds the desired value. ``atomic_write_text`` is safe either way; the
+    # short-circuit is purely about not bumping mtime on a no-op call.
+    if new_text == text:
+        return
+    atomic_write_text(pom_path, new_text)
+
+
+@extension_app.command(
+    "set-edition",
+    help="Switch the extension's ThingsBoard edition (pe/paas).",
+)
+def set_edition(
+    edition: Annotated[
+        _SetEditionTarget,
+        typer.Argument(
+            help="Target edition: pe or paas.",
+        ),
+    ],
+) -> None:
+    # ``_require_extension_present()`` already checks for both
+    # ``thingsboard.json`` (via ``_require_project_root``) AND the existence
+    # of ``extension/pom.xml`` — exactly the two preconditions the spec
+    # requires before we touch the pom.
+    extension_dir = _require_extension_present()
+    pom_path = extension_dir / "pom.xml"
+    artifact_id = _SET_EDITION_TO_ARTIFACT_ID[edition]
+    try:
+        _patch_root_pom_edition(pom_path, artifact_id)
+    except _ArtifactIdLineMissingError:
+        error("Could not find `<thingsboard-client.artifactId>` in `pom.xml`. Add it under `<properties>` first.")
+    display = _SET_EDITION_DISPLAY[edition]
+    _print_success_panel(
+        "Set edition",
+        [f"Set edition to {display} ({artifact_id})"],
+        next_hint=SET_EDITION_HINT,
+    )
+
+
+# ---------------------------------------------------------------------------
+# tb extension status
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("status", help="Show the extension's state, exposed features, and health.")
+def status() -> None:
+    project_root = _require_project_root()
+    extension_dir = _extension_dir(project_root)
+
+    if not extension_dir.is_dir():
+        console.print("Extension: [yellow]not present[/yellow] — run `tb extension new`.")
+        raise typer.Exit(code=0)
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column(style="bold")
+    table.add_column(overflow="fold")
+
+    # ``diagnose_extension_name`` raises on malformed manifest — catch it so the
+    # rest of the status table still prints (the user gets actionable info even
+    # when the JSON is broken).
+    _NAME_UNSET = "[yellow]not set[/yellow] — run `tb extension rename <name>`"
+    try:
+        ext_name = diagnose_extension_name(project_root)
+    except ExtensionNameError:
+        ext_name_cell = "[red]thingsboard.json malformed[/red]"
+    else:
+        ext_name_cell = ext_name if ext_name is not None else _NAME_UNSET
+    table.add_row("Extension name", ext_name_cell)
+
+    pom_path = extension_dir / "pom.xml"
+    artifact_id = unpacker.parse_pom_artifact_id(pom_path)
+    resolved_edition = unpacker.edition_from_artifact_id(artifact_id)
+    edition_label = resolved_edition if resolved_edition is not None else "[yellow]unknown[/yellow]"
+    table.add_row(
+        "Edition",
+        f"{edition_label} ({artifact_id or 'pom.xml missing thingsboard-client.artifactId'})",
+    )
+
+    readme_path = extension_dir / "README.md"
+    features_summary = "[dim]none[/dim]"
+    if readme_path.is_file():
+        manifest = parse_file(readme_path)
+        if manifest.features:
+            features_summary = ", ".join(f.slug for f in manifest.features)
+    table.add_row("Features", features_summary)
+
+    jar = unpacker.latest_target_jar(extension_dir)
+    if jar is None:
+        table.add_row("Last build", "[dim]no JAR in extension/extension/target/[/dim]")
+    else:
+        mtime = _dt.datetime.fromtimestamp(jar.stat().st_mtime, _dt.UTC).isoformat(timespec="seconds")
+        table.add_row("Last build", f"{jar.name} ({mtime})")
+
+    port = unpacker.read_extension_port(extension_dir)
+    health = _probe_health(port)
+    table.add_row("Health", f"http://localhost:{port}/api/health → {health}")
+
+    console.print(table)
+
+
+def _probe_health(port: int, timeout: float = 1.5) -> str:
+    """Best-effort GET /api/health probe. Returns a Rich-markup one-liner for the status table.
+
+    Color picks the user's at-a-glance signal:
+    - 2xx → green (the extension is up and reachable)
+    - other HTTP statuses → yellow (responded but unhealthy — needs attention)
+    - connection refused / DNS / timeout → dim (likely just not running)
+    """
+    import urllib.error
+    import urllib.request
+
+    url = f"http://localhost:{port}/api/health"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            color = "green" if 200 <= resp.status < 300 else "yellow"
+            return f"[{color}]{resp.status} OK[/{color}]"
+    except urllib.error.HTTPError as exc:
+        return f"[yellow]{exc.code} {exc.reason}[/yellow]"
+    except (urllib.error.URLError, OSError):
+        return "[dim]no response (not running?)[/dim]"
+
+
+# ---------------------------------------------------------------------------
+# tb extension build / test
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("build", help="Build the extension as a Docker image (use --jar for the Maven JAR path).")
+def build(
+    jar: Annotated[bool, typer.Option("--jar", help="Use the Maven JAR path instead of Docker.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress Maven output (JAR mode only).")] = False,
+    image_tag: Annotated[
+        str | None,
+        typer.Option("--image-tag", help="Tag for the built image. Defaults to 'latest'."),
+    ] = None,
+    platform: Annotated[
+        str | None,
+        typer.Option(
+            "--platform",
+            help=(
+                "Target platform for the docker image (e.g. linux/amd64, linux/arm64). "
+                f"Defaults to {_DEFAULT_PLATFORM} for portability."
+            ),
+        ),
+    ] = None,
+) -> None:
+    extension_dir = _require_extension_present()
+    if jar:
+        # ``--platform`` only applies to docker mode; the JAR is the same
+        # bytecode regardless of host architecture. Warn whenever the user
+        # passed it explicitly — including the default ``linux/amd64`` — so
+        # script writers get feedback that the flag does nothing here.
+        if platform is not None:
+            warning("--platform is only meaningful with docker mode; ignored in --jar mode.")
+        _require_java()
+        # Tests have their own command (`tb extension test`); build skips them
+        # so users can iterate without paying the test phase every time.
+        args = ["-B", "package", "-DskipTests"]
+        if quiet:
+            args.append("-q")
+        run_mvn(args, cwd=extension_dir)
+        # Maven scrolls a wall of [INFO] lines past the user; a single green "OK" line gets
+        # mistaken for one of them. A green-bordered panel is unmistakable.
+        jar_path = _find_extension_jar(extension_dir)
+        if jar_path is not None:
+            size_mb = jar_path.stat().st_size / 1_048_576
+            _print_build_success_panel([f"{jar_path.name} ({size_mb:.1f} MB)"])
+        else:
+            _print_build_success_panel(["Build complete."])
+        return
+    # Docker is the default mode.
+    if quiet:
+        warning("--quiet is only meaningful with --jar; ignored in docker mode.")
+    image_name = _require_extension_name()
+    _require_docker()
+    _require_java()
+    _build_docker_image(extension_dir, image_name, image_tag, platform or _DEFAULT_PLATFORM)
+
+
+@extension_app.command("test", help="Run the extension's tests.")
+def test() -> None:
+    extension_dir = _require_extension_present()
+    _require_java()
+    run_mvn(["-B", "test"], cwd=extension_dir)
+
+
+def _print_success_panel(title: str, body_lines: list[str], *, next_hint: str | None = None) -> None:
+    """Render a green-bordered Rich panel — used by lifecycle commands to surface a result
+    line plus an optional next-step hint, visually distinct from regular console output.
+
+    ``next_hint`` appends a blank line and the supplied multi-line hint below the body so
+    the user sees the "Next:" prompt in the same visual chunk as the success line.
+    """
+    body = "\n".join(f"[green]•[/green] [bold]{line}[/bold]" for line in body_lines)
+    if next_hint:
+        body = f"{body}\n\n{next_hint}"
+    console.print("")
+    console.print(Panel(body, title=f"[bold green]{title}[/bold green]", border_style="green", expand=False))
+
+
+def _print_build_success_panel(artifact_lines: list[str]) -> None:
+    """Thin wrapper for the JAR-mode minimal-hint build path.
+
+    The docker-mode build path calls :func:`_print_success_panel` directly so its next-step
+    hint stays explicit at the call site.
+    """
+    _print_success_panel("Build succeeded", artifact_lines)
+
+
+# ---------------------------------------------------------------------------
+# tb extension run / restart / logs / stop
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("run", help="Run the extension as a Docker container (use --jar for the Maven JAR path).")
+def run(
+    jar: Annotated[bool, typer.Option("--jar", help="Use the Maven JAR path instead of Docker.")] = False,
+    detach: Annotated[bool, typer.Option("--detach", "-d", help="Run in the background (Docker mode only).")] = False,
+    image_tag: Annotated[
+        str | None,
+        typer.Option("--image-tag", help="Tag for the built image. Defaults to 'latest'."),
+    ] = None,
+    platform: Annotated[
+        str | None,
+        typer.Option(
+            "--platform",
+            help=(
+                "Target platform for the docker image (e.g. linux/amd64, linux/arm64). "
+                f"Defaults to {_DEFAULT_PLATFORM} for portability."
+            ),
+        ),
+    ] = None,
+) -> None:
+    extension_dir = _require_extension_present()
+    port = unpacker.read_extension_port(extension_dir)
+    if _port_in_use(port):
+        offender = _pid_for_port(port)
+        hint = f" (PID {offender})" if offender else ""
+        # If the leftover is a docker compose stack we started, plain `tb extension stop` (which
+        # runs `docker compose down`) is the right move — `--force` would just SIGTERM the
+        # docker-proxy PID, which won't free the port. Tailor the hint to the actual state.
+        stop_cmd = "tb extension stop" if _docker_running(extension_dir) else "tb extension stop --force"
+        error(f"Port {port} is already in use{hint}. `{stop_cmd}` to clear it.")
+    if jar:
+        if detach:
+            warning("--detach is only meaningful with docker; running JAR in the foreground.")
+        if platform is not None:
+            warning("--platform is only meaningful with docker mode; ignored in --jar mode.")
+        _require_java()
+        _run_extension_jar(extension_dir)
+        return
+    # Docker is the default mode.
+    image_name = _require_extension_name()
+    _require_docker()
+    _run_extension_docker(
+        extension_dir,
+        image_name=image_name,
+        image_tag=image_tag,
+        detach=detach,
+        platform=platform or _DEFAULT_PLATFORM,
+    )
+
+
+@extension_app.command("restart", help="Stop the running extension and start it again.")
+def restart() -> None:
+    extension_dir = _require_extension_present()
+    if _docker_running(extension_dir):
+        _require_docker()
+        # Read what's ACTUALLY running before we tear down — the manifest's
+        # extension.name may not match the live image (e.g. user launched
+        # ``tb extension run --image-tag 1.2.3`` against a registry path).
+        ref = _discover_running_compose_image(extension_dir)
+        if ref is None:
+            error(
+                "Could not determine the running image (docker compose ps returned no image). "
+                "Stop the stack with `tb extension stop` and start it again with `tb extension run`. "
+                "(Usually orphan containers from a previous compose project — "
+                "`docker compose down -v` clears those if `tb extension stop` alone doesn't help.)"
+            )
+        image_name, image_tag = _split_image_ref(ref)
+        resolved_image = f"{image_name}:{image_tag or 'latest'}"
+        # ``restart`` reuses the already-built image. If the local image was
+        # removed between ``run`` and ``restart``, silently rebuilding here
+        # would lose the user's original ``--platform`` choice — so refuse
+        # and steer the user back through ``build`` where they can set it.
+        if not _docker_image_exists(resolved_image):
+            error(
+                f"Image `{resolved_image}` is no longer available locally. "
+                "Run `tb extension build` (pass `--platform` if you need a non-default architecture), "
+                "then `tb extension restart` again to bring the stack back up."
+            )
+        _run_subprocess(["docker", "compose", "down"], cwd=extension_dir, check=False)
+        # Image presence verified above, so ``_run_extension_docker``'s
+        # auto-build branch can never fire here. The ``platform`` value below
+        # is therefore dead — pass the default for signature consistency.
+        _run_extension_docker(
+            extension_dir,
+            image_name=image_name,
+            image_tag=image_tag,
+            detach=True,
+            platform=_DEFAULT_PLATFORM,
+        )
+        return
+    _require_java()
+    port = unpacker.read_extension_port(extension_dir)
+    pid = _pid_for_port(port)
+    if pid is not None:
+        _kill_pid(pid, port)
+    _run_extension_jar(extension_dir)
+
+
+@extension_app.command("logs", help="Tail the extension's logs (Docker only).")
+def logs(
+    follow: Annotated[bool, typer.Option("-f", "--follow", help="Stream new logs as they arrive.")] = False,
+) -> None:
+    extension_dir = _require_extension_present()
+    if not _docker_running(extension_dir):
+        error("No docker compose stack is running. `tb extension run --detach` to start one.")
+    cmd = ["docker", "compose", "logs"]
+    if follow:
+        cmd.append("-f")
+    _run_subprocess(cmd, cwd=extension_dir, forward_signals=True)
+
+
+@extension_app.command("stop", help="Stop the extension.")
+def stop(
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Force-stop any leftover process holding the extension's port.",
+        ),
+    ] = False,
+) -> None:
+    extension_dir = _require_extension_present()
+    if _docker_running(extension_dir):
+        _run_subprocess(["docker", "compose", "down"], cwd=extension_dir)
+        return
+    if not force:
+        console.print("Nothing to stop (no docker compose running). Pass --force to kill any port-bound java pid.")
+        return
+    port = unpacker.read_extension_port(extension_dir)
+    pid = _pid_for_port(port)
+    if pid is None:
+        console.print(f"Nothing listening on port {port}.")
+        return
+    _kill_pid(pid, port)
+
+
+def _kill_pid(pid: int, port: int) -> None:
+    """SIGTERM the PID listening on ``port``; escalate to SIGKILL after 5s if it stays alive."""
+    cmdline = _process_cmdline(pid) or "<unknown>"
+    console.print(f"Sending SIGTERM to PID {pid} ({cmdline}) on port {port}...")
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        console.print(f"PID {pid} already gone.")
+        return
+    if _wait_for_death(pid, timeout=5.0):
+        success(f"PID {pid} stopped.")
+        return
+    console.print(f"PID {pid} did not exit after 5s — sending SIGKILL.")
+    with suppress(ProcessLookupError):
+        os.kill(pid, signal.SIGKILL)
+    success(f"PID {pid} killed.")
+
+
+# ---------------------------------------------------------------------------
+# tb extension mvn-path
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command(
+    "mvn-path",
+    help="Print the absolute path to the user-resident Maven wrapper (for IDE Maven settings).",
+)
+def mvn_path() -> None:
+    from thingsboard_cli.core.maven_runner import mvnw_path
+
+    console.print(str(mvnw_path()))
+
+
+# ---------------------------------------------------------------------------
+# tb extension push
+# ---------------------------------------------------------------------------
+
+
+@extension_app.command("push", help="Push the locally-built Docker image to a registry.")
+def push(
+    image_name: Annotated[
+        str,
+        typer.Option(
+            "--image-name",
+            help=(
+                "Publish target including any registry/org prefix "
+                "(e.g. myuser/acme-ext, registry.example.com/team/foo)."
+            ),
+        ),
+    ],
+    image_tag: Annotated[
+        str | None,
+        typer.Option("--image-tag", help="Tag to push. Defaults to 'latest'."),
+    ] = None,
+    no_latest: Annotated[
+        bool,
+        typer.Option(
+            "--no-latest",
+            help=(
+                "Skip the implicit `:latest` push when --image-tag is set. Use this for RC/preview "
+                "tags so you don't overwrite the registry's `:latest`."
+            ),
+        ),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the confirmation prompt."),
+    ] = False,
+) -> None:
+    # Reject bare names like ``foo`` up front. Docker Hub only accepts pushes
+    # to ``<user>/<image>`` (or to ``library/<image>`` for the official org,
+    # which users can't publish to), so a slash-less name without an explicit
+    # ``localhost`` registry prefix is guaranteed to fail later inside
+    # ``docker push`` with an unfriendly error. The ``localhost`` carve-out is
+    # narrow on purpose — only ``localhost/...`` and ``localhost:<port>/...``
+    # are legitimate local-registry refs; bare ``localhost`` or ``localhost-foo``
+    # would still fail in ``docker push`` and should be rejected here.
+    if "/" not in image_name and not image_name.startswith(("localhost/", "localhost:")):
+        error(
+            f"--image-name `{image_name}` looks unpushable. "
+            "Use `<user>/<image>` for Docker Hub (e.g. `myuser/acme-ext`) "
+            "or include a registry host (e.g. `registry.example.com/team/foo`)."
+        )
+
+    local_name = _require_extension_name()
+    # Fast-fail on a missing docker daemon BEFORE rendering the confirmation
+    # panel — otherwise the user types `y` only to get a cryptic docker error.
+    _require_docker()
+
+    tag = image_tag or "latest"
+    local_ref = f"{local_name}:{tag}"
+    if not _docker_image_exists(local_ref):
+        error(f"Local image `{local_ref}` not found. Run `tb extension build` first.")
+
+    # `tag == "latest"` (the default when `--image-tag` is omitted) → single
+    # target ref. Any explicit non-latest tag → dual: <target>:<tag> AND :latest
+    # so the registry always has a `:latest` that mirrors the freshly pushed
+    # build, UNLESS the user passed --no-latest (opt out for RC/preview builds
+    # so they don't overwrite the registry's ``:latest``).
+    if tag == "latest":
+        target_refs = [f"{image_name}:latest"]
+        if no_latest:
+            warning("--no-latest is a no-op without --image-tag (you'd be pushing only `:latest` anyway).")
+    elif no_latest:
+        target_refs = [f"{image_name}:{tag}"]
+    else:
+        target_refs = [f"{image_name}:{tag}", f"{image_name}:latest"]
+
+    registry_host = _registry_host_for(image_name)
+    body_lines = ["About to push:"]
+    for ref in target_refs:
+        body_lines.append(f"  {ref}")
+    body_lines.append(f"to registry: {registry_host}")
+    if len(target_refs) > 1:
+        body_lines.append("`:latest` will also be pushed so the registry's `:latest` matches this build.")
+        body_lines.append("Pass --no-latest to skip it.")
+    console.print(Panel("\n".join(body_lines), border_style="cyan", expand=False))
+
+    if not yes:
+        prompt = "Push this image?" if len(target_refs) == 1 else "Push these images?"
+        if not typer.confirm(prompt, default=False):
+            console.print("Push cancelled.")
+            return
+
+    _push_docker_image(local_ref, target_refs)
+    # The success panel reflects the user's INTENT (single primary ref) rather
+    # than the dual-tag mechanics — when an explicit tag is given we also
+    # push :latest, but surfacing that on top of the panel would muddle the
+    # "what did I just publish?" answer.
+    haproxy_indented = textwrap.indent(HAPROXY_SNIPPET, "     ")
+    _print_success_panel(
+        "Pushed",
+        [f"Pushed {image_name}:{tag}"],
+        next_hint=PUSH_HINT_TEMPLATE.format(ref=image_name, haproxy_indented=haproxy_indented),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Subprocess + environment helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_extension_present() -> Path:
+    project_root = _require_project_root()
+    extension_dir = _extension_dir(project_root)
+    if not (extension_dir / "pom.xml").is_file():
+        error(f"No extension at {extension_dir.relative_to(project_root)}/. Run `tb extension new` first.")
+    return extension_dir
+
+
+def _require_extension_name() -> str:
+    """Return ``extension.name`` from the project manifest or exit with a remediation hint.
+
+    Used by docker-touching commands (``build``, ``run``, ``restart`` when a stack is up)
+    that need a local image name. Distinguishes two failure modes so the user sees the
+    right remediation:
+
+    - ``thingsboard.json`` is malformed or not a JSON object — surface that directly so
+      the user fixes the file (``tb extension rename`` would also refuse to write to a
+      malformed manifest, so steering them there is a dead-end).
+    - The manifest is valid but ``extension.name`` is unset — point at ``tb extension
+      rename`` to claim a name. This is the common upgrade path for projects that
+      pre-date the new naming model.
+    """
+    project_root = _require_project_root()
+    try:
+        name = diagnose_extension_name(project_root)
+    except ExtensionNameError as exc:
+        error(str(exc))
+    if name is None:
+        error("No extension.name set in thingsboard.json. Run `tb extension rename <name>` to set it.")
+    return name
+
+
+def _require_java() -> None:
+    """Bail if Java < 17 is the active JDK (or none is installed)."""
+    java = shutil.which("java")
+    if java is None:
+        error("Java is not on PATH. Install JDK 17+ (e.g. `brew install openjdk@17`) and re-run.")
+    try:
+        result = subprocess.run([java, "-version"], capture_output=True, text=True, check=False)
+    except OSError as exc:
+        error(f"Failed to invoke java: {exc}")
+    # java -version writes to stderr.
+    output = (result.stderr or result.stdout or "").strip()
+    major = _java_major_version(output)
+    if major is not None and major < 17:
+        error(f"Java {major} found but JDK 17+ is required. Set JAVA_HOME to a 17+ JDK.")
+
+
+def _java_major_version(version_output: str) -> int | None:
+    """Pull the numeric major version out of ``java -version`` output."""
+    import re
+
+    m = re.search(r'version "([^"]+)"', version_output)
+    if not m:
+        return None
+    parts = m.group(1).split(".")
+    try:
+        if parts[0] == "1" and len(parts) > 1:
+            return int(parts[1])  # Java 8 reports as "1.8.0_..."
+        return int(parts[0])
+    except (ValueError, IndexError):
+        return None
+
+
+def _require_docker() -> None:
+    """Bail if the docker daemon isn't reachable."""
+    docker = shutil.which("docker")
+    if docker is None:
+        error("`docker` is not on PATH. Install Docker Desktop / docker-engine and re-run.")
+    # ``OSError`` covers the race where ``docker`` disappears (uninstalled,
+    # path change) between ``shutil.which`` and the actual invocation — surface
+    # the same clean error() panel as the unreachable-daemon case.
+    try:
+        result = subprocess.run([docker, "info"], capture_output=True, text=True, check=False)
+    except OSError:
+        error("Docker daemon is not reachable. Start Docker Desktop (or `systemctl start docker`) and re-run.")
+    if result.returncode != 0:
+        error("Docker daemon is not reachable. Start Docker Desktop (or `systemctl start docker`) and re-run.")
+
+
+def _docker_running(extension_dir: Path) -> bool:
+    """Best-effort: are there containers from the extension's compose project?"""
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "compose", "ps", "-q"],
+            cwd=extension_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return False
+    return result.returncode == 0 and bool(result.stdout.strip())
+
+
+def _discover_running_compose_image(extension_dir: Path) -> str | None:
+    """Return the image ref of the first running compose container, or ``None``.
+
+    Uses ``docker compose ps --format '{{.Image}}'`` so ``restart`` can bounce
+    the stack with the SAME image the user launched — the manifest's
+    ``extension.name`` is irrelevant once a container is up (the user may
+    have launched a registry path or a specific tag via ``--image-tag``).
+    """
+    if shutil.which("docker") is None:
+        return None
+    try:
+        result = subprocess.run(
+            ["docker", "compose", "ps", "--format", "{{.Image}}"],
+            cwd=extension_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    for line in result.stdout.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return None
+
+
+def _split_image_ref(ref: str) -> tuple[str, str | None]:
+    """Split a docker image reference into ``(image_name, image_tag)``.
+
+    ``rsplit(":", 1)`` is intentional — registry-path refs like
+    ``localhost:5000/foo:1.2.3`` contain a port colon on the left, and we
+    want the LAST colon (the tag separator) to do the split. A ref without
+    any colon (``foo``) returns ``("foo", None)``; a ref where the last
+    colon is part of a port (``localhost:5000/foo``) is misclassified by
+    naive rsplit, so we recover by checking that the right-hand side does
+    not contain a slash.
+    """
+    if ":" not in ref:
+        return ref, None
+    left, right = ref.rsplit(":", 1)
+    # If the "tag" contains a slash, the colon we split on was actually a
+    # port separator (``localhost:5000/foo``) — restore the original ref
+    # and treat it as untagged.
+    if "/" in right:
+        return ref, None
+    return left, right
+
+
+def _registry_host_for(image_name: str) -> str:
+    """Return the registry host portion of *image_name* for display.
+
+    Mirrors docker's own reference-parsing rule: the first ``/``-segment is
+    treated as a registry host if it contains a ``.`` or ``:`` or equals
+    ``localhost``. Otherwise the implicit registry is Docker Hub.
+    """
+    first = image_name.split("/", 1)[0]
+    if "." in first or ":" in first or first == "localhost":
+        return first
+    return "docker.io"
+
+
+def _find_extension_jar(extension_dir: Path) -> Path | None:
+    """Return the executable Spring Boot fat JAR under ``extension/extension/target/``.
+
+    Spring Boot's repackage goal renames the pre-repackage artifact to
+    ``*.jar.original``, so we exclude that suffix to land on the runnable
+    JAR. ``-sources.jar`` and ``-javadoc.jar`` are also skipped.
+    """
+    target = extension_dir / "extension" / "target"
+    if not target.is_dir():
+        return None
+    candidates = [
+        p
+        for p in target.glob("thingsboard-extension-*.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 candidates:
+        return None
+    # Multiple matches shouldn't happen in practice, but if they do, prefer
+    # the most recently built JAR.
+    return max(candidates, key=lambda p: p.stat().st_mtime)
+
+
+def _run_extension_jar(extension_dir: Path) -> None:
+    """Find (or build, once) the extension JAR and run it with ``java -jar``."""
+    jar = _find_extension_jar(extension_dir)
+    if jar is None:
+        console.print("No extension JAR in extension/extension/target/ — building first (one-time)...")
+        run_mvn(["-B", "package", "-DskipTests"], cwd=extension_dir)
+        jar = _find_extension_jar(extension_dir)
+        if jar is None:
+            error("Build did not produce a JAR — check extension/extension/target/.")
+    console.print(f"Starting ThingsBoard Extension from {jar}...")
+    _run_subprocess(["java", "-jar", str(jar)], cwd=extension_dir, forward_signals=True)
+
+
+def _build_docker_image(
+    extension_dir: Path,
+    image_name: str,
+    image_tag: str | None,
+    platform: str,
+) -> None:
+    """Package the extension and build a Docker image.
+
+    Tagging rules (uniform across ``build`` and ``run``'s auto-build):
+
+    - ``image_tag is None`` → single ``-t <image_name>:latest``.
+    - ``image_tag`` set → dual ``-t <image_name>:<image_tag>`` AND
+      ``-t <image_name>:latest`` so the most recent local build always wins
+      under the canonical ``:latest`` name.
+
+    ``platform`` is forwarded to ``docker build --platform`` so the resulting
+    image is portable to the deployment host's architecture. The caller is
+    expected to resolve the default before invoking us.
+
+    Shared between ``tb extension build`` (docker default) and the "image
+    missing" branch of ``tb extension run`` (docker default).
+    """
+    run_mvn(["package", "-DskipTests", "-q"], cwd=extension_dir)
+    if image_tag is None:
+        docker_cmd = ["docker", "build", "--platform", platform, "-t", f"{image_name}:latest", "."]
+        artifact_lines = [f"{image_name}:latest"]
+    else:
+        docker_cmd = [
+            "docker",
+            "build",
+            "--platform",
+            platform,
+            "-t",
+            f"{image_name}:{image_tag}",
+            "-t",
+            f"{image_name}:latest",
+            ".",
+        ]
+        artifact_lines = [f"{image_name}:{image_tag}", f"{image_name}:latest"]
+    _run_subprocess(docker_cmd, cwd=extension_dir)
+    # Docker build output is a wall of layer hashes; a single "OK" line is easy to miss in the
+    # scrollback. Surface produced tags inside a green-bordered panel, plus a next-step hint
+    # so users learn how to publish without hunting through `--help`.
+    _print_success_panel("Build succeeded", artifact_lines, next_hint=BUILD_HINT_TEMPLATE)
+
+
+def _push_docker_image(local_ref: str, target_refs: list[str]) -> None:
+    """Tag ``local_ref`` as each ``target_refs`` entry and ``docker push`` it.
+
+    ``docker tag`` is skipped when source equals target (defensive — slashes
+    aren't allowed in the manifest name so collisions are unlikely, but the
+    no-op tag would just clutter the output).
+    """
+    project_root = _require_project_root()
+    extension_dir = _extension_dir(project_root)
+    for target in target_refs:
+        if target != local_ref:
+            _run_subprocess(["docker", "tag", local_ref, target], cwd=extension_dir)
+        _run_subprocess(["docker", "push", target], cwd=extension_dir)
+
+
+def _docker_image_exists(image: str) -> bool:
+    """Return True iff ``docker image inspect <image>`` reports the image is local."""
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "image", "inspect", image],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
+def _run_extension_docker(
+    extension_dir: Path,
+    *,
+    image_name: str,
+    image_tag: str | None,
+    detach: bool,
+    platform: str,
+) -> None:
+    """Bring up the docker compose stack, building the image once if absent.
+
+    The resolved ``<image_name>:<tag>`` is passed to compose via the
+    ``TB_EXTENSION_IMAGE`` env var so ``compose.yaml`` picks it up. When not
+    detaching, also tails container logs so the user sees the boot output.
+
+    ``platform`` is only consulted by the auto-build branch (when the image
+    is missing) — the compose stack itself runs whichever local image already
+    matches the resolved tag.
+    """
+    resolved_tag = image_tag or "latest"
+    resolved_image = f"{image_name}:{resolved_tag}"
+    if not _docker_image_exists(resolved_image):
+        console.print(f"No image {resolved_image} found — building first...")
+        # Pass the user's original ``image_tag`` (None when ``--image-tag`` was
+        # omitted) so the auto-build behaves identically to an explicit
+        # ``tb extension build``: missing tag → single ``-t :latest``, explicit
+        # tag → dual ``-t :<tag>`` and ``-t :latest``.
+        _build_docker_image(extension_dir, image_name, image_tag, platform)
+    # Export EXTENSION_PORT so compose maps host:container ports consistently
+    # and Spring inside the container listens on the same port the success
+    # panel advertises. ``read_extension_port`` is the single source of truth
+    # (env > application.yml > default 8090).
+    port = unpacker.read_extension_port(extension_dir)
+    env = {**os.environ, "TB_EXTENSION_IMAGE": resolved_image, "EXTENSION_PORT": str(port)}
+    # Always start detached so the parent owns container lifetime explicitly. For foreground
+    # mode we attach a ``logs -f`` tail and tear the stack down once it exits — Ctrl-C then
+    # behaves like a normal ``docker compose up`` (stop everything) instead of leaving the
+    # container bound to the extension's port.
+    #
+    # ``--progress=plain`` swaps compose's animated TUI for line-by-line output. The TUI
+    # uses cursor moves + ``\r`` to redraw a single status line, which wraps and clobbers
+    # itself when the line exceeds the terminal width (e.g. the platform-mismatch warning).
+    # Plain output renders the same info as a tidy log instead of a smearing redraw.
+    # ``--progress`` is a top-level ``docker compose`` flag, not an ``up`` subcommand flag,
+    # so it must precede ``up`` — older compose versions reject it in the trailing position.
+    _run_subprocess(["docker", "compose", "--progress=plain", "up", "-d"], cwd=extension_dir, env=env)
+    # Print the run hint once the stack is up — surfaced for BOTH detach and
+    # foreground modes so users always see the rule-chain / widget / HAProxy
+    # wiring info. Foreground mode then continues into ``logs -f`` below.
+    _print_success_panel(
+        "Running",
+        [f"Running '{image_name}' at http://localhost:{port}"],
+        next_hint=RUN_HINT_TEMPLATE.format(port=port, haproxy=HAPROXY_SNIPPET),
+    )
+    if detach:
+        return
+    try:
+        _run_subprocess(
+            ["docker", "compose", "logs", "-f"],
+            cwd=extension_dir,
+            env=env,
+            forward_signals=True,
+        )
+    finally:
+        _run_subprocess(["docker", "compose", "down"], cwd=extension_dir, env=env, check=False)
+
+
+def _run_subprocess(
+    cmd: list[str],
+    *,
+    cwd: Path,
+    check: bool = True,
+    forward_signals: bool = False,
+    env: dict[str, str] | None = None,
+) -> None:
+    """Run ``cmd`` and inherit stdin/stdout/stderr.
+
+    If ``forward_signals``, Ctrl-C is passed through to the child rather
+    than killing the CLI process group abruptly — important for foreground
+    run modes where the child needs a clean shutdown signal.
+
+    ``env`` defaults to ``None``, which means the child inherits the parent's
+    environment as-is. Pass a fully-populated mapping to override.
+    """
+    console.print(f"[dim]$ {' '.join(cmd)} (in {cwd})[/dim]")
+    process = subprocess.Popen(cmd, cwd=cwd, env=env)
+    if forward_signals:
+
+        def _forward(signum: int, _frame: object) -> None:
+            with suppress(ProcessLookupError):
+                process.send_signal(signum)
+
+        previous_int = signal.signal(signal.SIGINT, _forward)
+        previous_term = signal.signal(signal.SIGTERM, _forward)
+        try:
+            returncode = process.wait()
+        finally:
+            signal.signal(signal.SIGINT, previous_int)
+            signal.signal(signal.SIGTERM, previous_term)
+        # 128 + SIGINT/SIGTERM. With forward_signals=True the user just sent that signal via
+        # Ctrl-C (or a stop command), so the non-zero exit is the requested shutdown — not a
+        # failure the CLI should announce.
+        if returncode in (130, 143):
+            return
+    else:
+        returncode = process.wait()
+    if check and returncode != 0:
+        error(f"{cmd[0]} exited with status {returncode}.")
+
+
+def _port_in_use(port: int) -> bool:
+    """Return True if anything is listening on ``port`` (best-effort)."""
+    return _pid_for_port(port) is not None
+
+
+def _pid_for_port(port: int) -> int | None:
+    """Return one PID listening on ``port``, preferring lsof, falling back to fuser."""
+    lsof = shutil.which("lsof")
+    if lsof is not None:
+        try:
+            result = subprocess.run(
+                [lsof, "-ti", f"tcp:{port}", "-sTCP:LISTEN"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            result = None
+        if result is not None and result.returncode == 0 and result.stdout.strip():
+            first = result.stdout.strip().splitlines()[0].strip()
+            if first.isdigit():
+                return int(first)
+    fuser = shutil.which("fuser")
+    if fuser is not None:
+        try:
+            result = subprocess.run(
+                [fuser, "-n", "tcp", str(port)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            result = None
+        if result is not None and result.returncode == 0 and result.stdout.strip():
+            tokens = result.stdout.replace("/", " ").split()
+            for token in tokens:
+                if token.isdigit():
+                    return int(token)
+    return None
+
+
+def _process_cmdline(pid: int) -> str | None:
+    """Best-effort ``ps -o command=`` lookup. Returns None on any error."""
+    ps = shutil.which("ps")
+    if ps is None:
+        return None
+    try:
+        result = subprocess.run(
+            [ps, "-p", str(pid), "-o", "command="],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    return result.stdout.strip()
+
+
+def _wait_for_death(pid: int, timeout: float = 5.0, poll_interval: float = 0.1) -> bool:
+    """Poll for process exit. Returns True if the PID is gone within ``timeout``."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return True
+        except PermissionError:
+            return False
+        time.sleep(poll_interval)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return True
+    return False