pythonnative
diff --git a/‎docs/api/cli.md‎
Lines changed: 4 additions & 1 deletion b/‎docs/api/cli.md‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎src/pythonnative/cli/pn.py‎
Lines changed: 37 additions & 6 deletions b/‎src/pythonnative/cli/pn.py‎
Lines changed: 37 additions & 6 deletions
diff --git a/‎src/pythonnative/project/devices.py‎
Lines changed: 14 additions & 1 deletion b/‎src/pythonnative/project/devices.py‎
Lines changed: 14 additions & 1 deletion
diff --git a/‎tests/test_cli.py‎
Lines changed: 198 additions & 3 deletions b/‎tests/test_cli.py‎
Lines changed: 198 additions & 3 deletions
@@ -18,7 +18,9 @@ the documented behavior never drifts from the code.
   `--width`, `--height`, `--title`, `--no-hot-reload`. See the
   [Desktop preview guide](../guides/desktop-preview.md).
 - `pn devices [android|ios]`: list connected devices, emulators, and
-  simulators with the identifiers `--device` accepts.
+  simulators with the identifiers `--device` accepts. Flag: `--json` to
+  print a JSON array to stdout for scripting; the "no devices" hints go
+  to stderr instead, and an empty list prints `[]` and exits 0.
 - `pn run android|ios`: build and run on a connected device or
   simulator. Flags: `--device` (target a specific device by identifier
   or name), `--prepare-only`, `--hot-reload`, `--no-logs`.
@@ -31,6 +33,7 @@ the documented behavior never drifts from the code.
 - `pn app-id android|ios`: print the resolved application id (Android)
   or bundle id (iOS), handy for scripts and CI.
 - `pn clean`: remove the local `build/` directory.
+- `pn --version` (`-V`): print the installed PythonNative version.
 
 ::: pythonnative.cli.pn
     options:
 
@@ -9,7 +9,7 @@
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
   with Fast Refresh, the fast inner dev loop, no device required.
 - `pn devices [platform]`: list connected devices, emulators, and
-  simulators.
+  simulators, as a table or as JSON with `--json`.
 - `pn run android|ios [--device D]`: stage + build + install + launch on
   a device, emulator, or simulator, with optional on-device hot reload.
 - `pn logs android|ios`: stream logs from the running app without
@@ -38,7 +38,7 @@
 import time
 from importlib.metadata import version as pkg_version
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, TextIO
 
 from ..project import builder as builder_mod
 from ..project import devices as devices_mod
@@ -298,18 +298,46 @@ def _preview_entry(project_dir: Path) -> str:
 # ======================================================================
 
 
+def _print_no_devices_hints(stream: TextIO) -> None:
+    """Print the "no devices" guidance to ``stream``.
+
+    Shared by both output modes so the wording can't drift between the
+    table (which sends it to stdout) and ``--json`` (stderr).
+
+    Args:
+        stream: Where to write, ``sys.stdout`` or ``sys.stderr``.
+    """
+    print("No devices found.", file=stream)
+    print("Android: start an emulator or connect a device with USB debugging enabled.", file=stream)
+    print("iOS: open Xcode once to install Simulators, or plug in a device.", file=stream)
+
+
 def devices_command(args: argparse.Namespace) -> None:
     """List connected devices, emulators, and simulators.
 
+    Prints an aligned table and exits 1 when nothing is connected.
+
+    With ``--json``, stdout carries a JSON array and nothing else, one
+    object per device (see ``Device.to_dict``), so it stays parseable.
+    The "no devices" hints go to stderr instead, an empty result prints
+    ``[]``, and the exit status is 0 either way, since "no devices" is a
+    valid answer for a script rather than a failure.
+
     Args:
-        args: Parsed namespace with optional ``platform``.
+        args: Parsed namespace with optional ``platform`` and ``json``.
     """
     platform: Optional[str] = getattr(args, "platform", None)
+    as_json: bool = getattr(args, "json", False)
     devices = devices_mod.list_devices(platform)
+
+    if as_json:
+        if not devices:
+            _print_no_devices_hints(sys.stderr)
+        print(json.dumps([device.to_dict() for device in devices], indent=2))
+        return
+
     if not devices:
-        print("No devices found.")
-        print("Android: start an emulator or connect a device with USB debugging enabled.")
-        print("iOS: open Xcode once to install Simulators, or plug in a device.")
+        _print_no_devices_hints(sys.stdout)
         sys.exit(1)
     print(f"  {'IDENTIFIER':<40} {'KIND':<10} {'STATE':<10} NAME")
     for device in devices:
@@ -943,6 +971,9 @@ def _build_parser() -> argparse.ArgumentParser:
 
     parser_devices = subparsers.add_parser("devices", help="List devices, emulators, and simulators")
     parser_devices.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict to a platform")
+    parser_devices.add_argument(
+        "--json", action="store_true", help="Print a JSON array to stdout for scripting (hints go to stderr)"
+    )
     parser_devices.set_defaults(func=devices_command)
 
     parser_run = subparsers.add_parser("run", help="Build, install, and launch on a device/simulator")
 
@@ -18,7 +18,7 @@
 import re
 import subprocess
 import tempfile
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -64,6 +64,19 @@ def is_ready(self) -> bool:
             return self.state in ("booted", "shutdown")
         return self.state in ("booted", "connected")
 
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-serializable view of this target.
+
+        Derived from the dataclass fields so a field added later is
+        carried into the payload automatically, plus the computed
+        ``is_ready`` that consumers would otherwise have to re-derive
+        from ``kind`` and ``state``.
+
+        Returns:
+            The declared fields in declaration order, then ``is_ready``.
+        """
+        return {**asdict(self), "is_ready": self.is_ready}
+
     def format(self) -> str:
         """Return one aligned listing row for the CLI."""
         os_part = f" ({self.os_version})" if self.os_version else ""
 
@@ -1,20 +1,23 @@
+import argparse
+import json
 import os
 import shutil
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
-from typing import List
+from typing import Callable, Dict, List, Optional
 
 import pytest
 
 import pythonnative.cli.pn as pn_cli
 import pythonnative.hot_reload as hot_reload_module
+from pythonnative.project.devices import Device
 
 
-def run_pn(args: List[str], cwd: str) -> "subprocess.CompletedProcess[str]":
+def run_pn(args: List[str], cwd: str, env: Optional[Dict[str, str]] = None) -> "subprocess.CompletedProcess[str]":
     cmd = [sys.executable, "-m", "pythonnative.cli.pn"] + args
-    return subprocess.run(cmd, cwd=cwd, check=False, capture_output=True, text=True)
+    return subprocess.run(cmd, cwd=cwd, check=False, capture_output=True, text=True, env=env)
 
 
 def test_cli_version(tmp_path: Path) -> None:
@@ -339,6 +342,198 @@ def _raise(*args: object, **kwargs: object) -> None:
     assert pn_cli._booted_ios_udid() is None
 
 
+# `pn devices` tests run devices_command() in-process rather than through run_pn,
+# because run_pn spawns a child interpreter that monkeypatch can't reach: it would
+# re-import the real list_devices and shell out to adb/xcrun, making the result
+# depend on whatever hardware the test machine has attached. The one run_pn test
+# below empties PATH instead, so every list_* call hits FileNotFoundError.
+
+# A naive `state == "booted"` readiness check disagrees with is_ready on two of
+# these: the connected Android device (ready, not booted) and the shutdown
+# simulator (ready, because simulators boot on demand).
+_FAKE_DEVICES = [
+    Device("android", "device", "R5CT12345XYZ", "Pixel 8 Pro", "", "connected"),
+    Device("android", "device", "OFFLINE99", "Galaxy S24", "", "offline"),
+    Device("ios", "simulator", "ABC-123", "iPhone 17 Pro", "iOS 26.4", "booted"),
+    Device("ios", "simulator", "DEF-456", "iPad Pro 13-inch (M4)", "iOS 26.4", "shutdown"),
+]
+
+_NO_DEVICES_HINTS = (
+    "No devices found.\n"
+    "Android: start an emulator or connect a device with USB debugging enabled.\n"
+    "iOS: open Xcode once to install Simulators, or plug in a device.\n"
+)
+
+_DEVICE_TABLE = (
+    "  IDENTIFIER                               KIND       STATE      NAME\n"
+    "  R5CT12345XYZ                             device     connected  Pixel 8 Pro\n"
+    "  OFFLINE99                                device     offline    Galaxy S24\n"
+    "  ABC-123                                  simulator  booted     iPhone 17 Pro (iOS 26.4)\n"
+    "  DEF-456                                  simulator  shutdown   iPad Pro 13-inch (M4) (iOS 26.4)\n"
+    "\n"
+    "Target one with: pn run <platform> --device <identifier or name>\n"
+)
+
+
+def _fake_list_devices(
+    devices: List[Device], calls: Optional[List[Optional[str]]] = None
+) -> Callable[..., List[Device]]:
+    """Stand in for list_devices, filtering by platform and recording the argument."""
+
+    def _list(platform: Optional[str] = None) -> List[Device]:
+        if calls is not None:
+            calls.append(platform)
+        return [device for device in devices if platform in (None, device.platform)]
+
+    return _list
+
+
+def test_devices_json_emits_parseable_array(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices(_FAKE_DEVICES))
+
+    # Returns rather than exiting, so a populated listing stays exit 0.
+    pn_cli.devices_command(argparse.Namespace(platform=None, json=True))
+
+    payload = json.loads(capsys.readouterr().out)
+    assert [entry["identifier"] for entry in payload] == [
+        "R5CT12345XYZ",
+        "OFFLINE99",
+        "ABC-123",
+        "DEF-456",
+    ]
+    for entry in payload:
+        assert set(entry) == {
+            "platform",
+            "kind",
+            "identifier",
+            "name",
+            "os_version",
+            "state",
+            "is_ready",
+        }
+    ready = {entry["identifier"]: entry["is_ready"] for entry in payload}
+    assert ready == {"R5CT12345XYZ": True, "OFFLINE99": False, "ABC-123": True, "DEF-456": True}
+
+    # The two entries a naive `state == "booted"` check would get wrong.
+    by_id = {entry["identifier"]: entry for entry in payload}
+    assert by_id["DEF-456"]["state"] == "shutdown" and by_id["DEF-456"]["is_ready"] is True
+    assert by_id["R5CT12345XYZ"]["state"] == "connected" and by_id["R5CT12345XYZ"]["is_ready"] is True
+    assert by_id["OFFLINE99"]["kind"] == "device" and by_id["OFFLINE99"]["is_ready"] is False
+
+
+def test_devices_json_empty_prints_array_and_hints_to_stderr(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices([]))
+
+    # No SystemExit: an empty result is exit 0 under --json, unlike the table.
+    pn_cli.devices_command(argparse.Namespace(platform=None, json=True))
+
+    captured = capsys.readouterr()
+    assert captured.out == "[]\n"
+    assert json.loads(captured.out) == []
+    assert captured.err == _NO_DEVICES_HINTS
+
+
+@pytest.mark.parametrize(
+    ("platform", "expected"),
+    [("android", ["R5CT12345XYZ", "OFFLINE99"]), ("ios", ["ABC-123", "DEF-456"])],
+)
+def test_devices_json_respects_platform_filter(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    platform: str,
+    expected: List[str],
+) -> None:
+    calls: List[Optional[str]] = []
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices(_FAKE_DEVICES, calls))
+
+    pn_cli.devices_command(argparse.Namespace(platform=platform, json=True))
+
+    assert calls == [platform]
+    payload = json.loads(capsys.readouterr().out)
+    assert {entry["platform"] for entry in payload} == {platform}
+    assert [entry["identifier"] for entry in payload] == expected
+
+
+@pytest.mark.parametrize("devices", [[], _FAKE_DEVICES], ids=["empty", "populated"])
+def test_devices_json_keeps_human_text_off_stdout(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], devices: List[Device]
+) -> None:
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices(devices))
+
+    pn_cli.devices_command(argparse.Namespace(platform=None, json=True))
+
+    out = capsys.readouterr().out
+    json.loads(out)
+    # Every non-JSON source the table mode prints: the three hints, the column
+    # header, each aligned row, and the trailer.
+    for hint in _NO_DEVICES_HINTS.splitlines():
+        assert hint not in out
+    assert "IDENTIFIER" not in out
+    assert "Target one with:" not in out
+    for device in devices:
+        assert device.format() not in out
+
+
+def test_devices_human_output_unchanged_when_empty(tmp_path: Path) -> None:
+    # An empty PATH makes adb/xcrun unresolvable, so every list_* call returns [].
+    env = {**os.environ, "PATH": str(tmp_path)}
+    result = run_pn(["devices"], str(tmp_path), env=env)
+
+    assert result.returncode == 1
+    assert result.stdout == _NO_DEVICES_HINTS
+    assert result.stderr == ""
+
+
+def test_devices_human_output_unchanged_when_populated(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices(_FAKE_DEVICES))
+
+    pn_cli.devices_command(argparse.Namespace(platform=None, json=False))
+
+    captured = capsys.readouterr()
+    assert captured.out == _DEVICE_TABLE
+    assert captured.err == ""
+
+
+def test_devices_json_flag_is_wired_through_argparse(tmp_path: Path) -> None:
+    # The other JSON tests call devices_command() directly, so only this one
+    # proves the subparser actually accepts --json and routes it through.
+    env = {**os.environ, "PATH": str(tmp_path)}
+    result = run_pn(["devices", "--json"], str(tmp_path), env=env)
+
+    assert result.returncode == 0
+    assert json.loads(result.stdout) == []
+    assert result.stdout == "[]\n"
+    assert result.stderr == _NO_DEVICES_HINTS
+
+
+def test_devices_json_serializes_awkward_field_values(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    # Quotes, a newline, non-ASCII, and the two empty-string defaults all survive
+    # the round trip today; nothing pinned them before.
+    awkward = Device("android", "device", "SER!@#123", 'M\u00e1laga "Pixel"\nLab', "", "")
+    monkeypatch.setattr(pn_cli.devices_mod, "list_devices", _fake_list_devices([awkward]))
+
+    pn_cli.devices_command(argparse.Namespace(platform=None, json=True))
+
+    (entry,) = json.loads(capsys.readouterr().out)
+    assert entry == {
+        "platform": "android",
+        "kind": "device",
+        "identifier": "SER!@#123",
+        "name": 'M\u00e1laga "Pixel"\nLab',
+        "os_version": "",
+        "state": "",
+        "is_ready": False,
+    }
+
+
 def test_hot_reload_manifest_payload_maps_files_to_modules(tmp_path: Path) -> None:
     app_dir = tmp_path / "app"
     app_dir.mkdir()