feat(cli): add remote tree command for device directories

Add mpy-cli tree with --path support, backend typed directory listing, README updates, and tests. Validate behavior with full test suite and on a connected MicroPython device.

Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

Author: LanternCX

README.md

@@ -149,6 +149,7 @@ mpy-cli deploy
 mpy-cli upload
 mpy-cli run
 mpy-cli delete
+mpy-cli tree
 ```
 
 说明：
@@ -284,6 +285,24 @@ mpy-cli delete --path obsolete.py
 若配置 `device_upload_dir = "apps/demo"`，则会删除 `:apps/demo/obsolete.py`。
 当 `--path` 指向目录时，默认递归删除整个目录。
 
+### `mpy-cli tree`
+
+```bash
+mpy-cli tree [--path PATH] [--port PORT] [--no-interactive]
+```
+
+- `--path`：设备目标目录路径，语义为相对 `device_upload_dir`；不传时默认读取 `device_upload_dir` 根目录。
+- `--port`：指定设备端口。
+- `--no-interactive`：禁用交互提问；此时需通过 `--port` 或配置文件提供端口。
+
+推荐用法：
+
+```bash
+mpy-cli tree --path .
+```
+
+若配置 `device_upload_dir = "apps/demo"`，则默认读取 `:apps/demo`；例如 `--path services` 会读取 `:apps/demo/services`。
+
 ---
 
 ## 常见问题

docs/plans/2026-03-06-tree-command-design.md

@@ -0,0 +1,69 @@
+# tree 命令功能设计文档
+
+## 背景
+
+当前 `mpy-cli` 已支持 `upload/run/delete`，但缺少“查看设备端目录结构”的能力。用户在部署前后无法快速确认设备上的目录层级，尤其在设置了 `device_upload_dir` 后，不容易判断目标目录是否符合预期。
+
+## 目标
+
+- 新增 `mpy-cli tree` 子命令。
+- 默认读取设备端 `device_upload_dir` 对应目录树。
+- 支持通过 `--path` 指定相对 `device_upload_dir` 的子目录。
+- 输出采用类似 `tree` 的文本结构，便于快速阅读。
+
+## 命令设计
+
+```bash
+mpy-cli tree [--path PATH] [--port PORT] [--no-interactive]
+```
+
+- `--path`：设备目标目录，语义为相对 `device_upload_dir`；为空时读取 `device_upload_dir` 根。
+- `--port`：指定设备串口。
+- `--no-interactive`：禁用交互提问；无 `--port` 时按既有规则处理。
+
+## 方案对比
+
+### 方案 A（推荐）主机递归 + 设备单层目录读取
+
+- 每次请求设备一个目录的直接子项（文件/目录），主机侧递归构建树并打印。
+- 优点：结构清晰，错误定位直接，便于测试。
+- 缺点：深层目录会产生多次设备往返。
+
+### 方案 B 设备端一次性递归回传
+
+- 在设备端执行完整递归脚本，直接输出最终树文本。
+- 优点：设备往返少。
+- 缺点：设备脚本复杂，兼容性与可测试性较差。
+
+最终采用方案 A。
+
+## 架构与数据流
+
+1. CLI 解析 `tree` 子命令参数。
+2. 复用 `_resolve_port()` 解析端口。
+3. 按 `device_upload_dir` + `--path` 计算目标设备目录。
+4. `MpremoteBackend` 提供“单层目录读取”能力，返回结构化条目（名称 + 是否目录）。
+5. CLI 递归请求并生成树形文本输出。
+
+## 错误处理
+
+- 配置错误、端口缺失、`mpremote` 不可用：返回 `1`。
+- 目录读取失败（目录不存在、权限问题、设备异常）：返回 `2`。
+
+## 测试策略
+
+- `tests/test_mpremote_backend.py`
+  - 校验目录读取命令构建。
+  - 校验目录读取输出解析（`D\tname` / `F\tname`）。
+- `tests/test_cli.py`
+  - 校验 `tree` 命令在 `device_upload_dir` 语义下拼接目标路径。
+  - 校验 `tree` 读取失败时返回退出码 `2`。
+- `tests/test_docs_and_ci.py` + `README.md`
+  - 保持命令列表和参数说明同步。
+
+## 验收标准
+
+- 可执行 `mpy-cli tree --path <dir>` 查看设备目录树。
+- 未传 `--path` 时默认查看 `device_upload_dir` 根目录。
+- 输出有稳定树结构，目录优先排序。
+- 新增测试通过，不影响现有命令行为。

docs/plans/2026-03-06-tree-command-implementation.md

@@ -0,0 +1,237 @@
+# Tree Command Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add `mpy-cli tree` to print a remote directory tree on the MicroPython device, scoped by `device_upload_dir` and optional `--path`.
+
+**Architecture:** Extend CLI command routing with a new read-only `tree` subcommand. Add a backend API that reads exactly one remote directory level and returns typed entries, then build tree output recursively in CLI for deterministic sorting and formatting. Keep existing port/config/error flow unchanged to minimize behavioral risk.
+
+**Tech Stack:** Python 3.10+, argparse, mpremote backend adapter, pytest.
+
+---
+
+### Task 1: Backend typed directory listing API
+
+**Files:**
+- Modify: `mpy_cli/backend/mpremote.py`
+- Test: `tests/test_mpremote_backend.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_list_dir_parses_typed_entries() -> None:
+    called: list[list[str]] = []
+
+    def fake_runner(command, capture_output, text, check):  # noqa: ANN001
+        called.append(command)
+        return subprocess.CompletedProcess(
+            args=command,
+            returncode=0,
+            stdout="D\tapps\nF\tmain.py\n",
+            stderr="",
+        )
+
+    backend = MpremoteBackend(binary="mpremote", runner=fake_runner, resolver=lambda _: "/usr/bin/mpremote")
+    entries = backend.list_dir(port="/dev/ttyACM0", remote_path="apps/demo")
+
+    assert called[0][0:5] == ["mpremote", "connect", "/dev/ttyACM0", "resume", "exec"]
+    assert [entry.name for entry in entries] == ["apps", "main.py"]
+    assert [entry.is_dir for entry in entries] == [True, False]
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_mpremote_backend.py::test_list_dir_parses_typed_entries`
+Expected: FAIL with missing `list_dir` or related symbol.
+
+**Step 3: Write minimal implementation**
+
+```python
+@dataclass(frozen=True)
+class RemoteDirEntry:
+    name: str
+    is_dir: bool
+
+def list_dir(self, port: str, remote_path: str) -> list[RemoteDirEntry]:
+    cmd = self.build_list_dir_command(port=port, remote=remote_path)
+    result = self._run(cmd)
+    return _parse_remote_dir_entries(result.stdout)
+```
+
+Also add `_build_remote_list_dir_script()` and parser for `D\tname` / `F\tname` lines.
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_mpremote_backend.py::test_list_dir_parses_typed_entries`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add mpy_cli/backend/mpremote.py tests/test_mpremote_backend.py
+git commit -m "feat: add typed remote directory listing API"
+```
+
+### Task 2: CLI `tree` command routing and execution
+
+**Files:**
+- Modify: `mpy_cli/cli.py`
+- Test: `tests/test_cli.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_tree_executes_remote_list_with_device_upload_prefix(...):
+    # setup config with device_upload_dir="apps/demo"
+    # run main(["tree", "--no-interactive", "--port", "COM3", "--path", "services"])
+    # assert backend.list_dir called with "apps/demo/services"
+```
+
+Add another test for backend failure returning `2`.
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_cli.py::test_tree_executes_remote_list_with_device_upload_prefix`
+Expected: FAIL because `tree` command does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+```python
+tree_parser = subparsers.add_parser("tree", help="读取设备端目录树")
+tree_parser.add_argument("--path", help="设备目标目录路径")
+tree_parser.add_argument("--port", help="设备串口")
+tree_parser.add_argument("--no-interactive", action="store_true", help="禁用 questionary 交互")
+```
+
+Implement `_cmd_tree(args)`:
+- load config and setup logging
+- resolve port (reuse existing function)
+- resolve target directory with `_join_upload_target`
+- call backend recursively and print tree lines
+- map failure to exit code `2`
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_cli.py::test_tree_executes_remote_list_with_device_upload_prefix tests/test_cli.py::test_tree_returns_failure_code_when_backend_list_fails`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add mpy_cli/cli.py tests/test_cli.py
+git commit -m "feat: add tree command for remote directory view"
+```
+
+### Task 3: Tree output formatting and deterministic order
+
+**Files:**
+- Modify: `mpy_cli/cli.py`
+- Test: `tests/test_cli.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_tree_prints_nested_structure_in_tree_style(...):
+    # fake backend returns nested entries
+    # assert stdout contains ├── / └── / │ formatting and stable order
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_cli.py::test_tree_prints_nested_structure_in_tree_style`
+Expected: FAIL because output is not formatted yet.
+
+**Step 3: Write minimal implementation**
+
+Implement helper recursion in `cli.py`:
+
+```python
+def _render_remote_tree(...):
+    # sort: directories first, then by name
+    # render with connectors
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_cli.py::test_tree_prints_nested_structure_in_tree_style`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add mpy_cli/cli.py tests/test_cli.py
+git commit -m "feat: format tree command output as hierarchical view"
+```
+
+### Task 4: README and docs consistency
+
+**Files:**
+- Modify: `README.md`
+- Modify: `tests/test_docs_and_ci.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_readme_lists_tree_command_parameters() -> None:
+    content = Path("README.md").read_text(encoding="utf-8")
+    for token in ["mpy-cli tree", "--path"]:
+        assert token in content
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_docs_and_ci.py::test_readme_lists_tree_command_parameters`
+Expected: FAIL because README has no tree section.
+
+**Step 3: Write minimal implementation**
+
+Update README command list and CLI 参数总览 with:
+
+```bash
+mpy-cli tree [--path PATH] [--port PORT] [--no-interactive]
+```
+
+Include semantics: path is relative to `device_upload_dir`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_docs_and_ci.py::test_readme_lists_tree_command_parameters`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add README.md tests/test_docs_and_ci.py
+git commit -m "docs: document tree command parameters"
+```
+
+### Task 5: Verification sweep
+
+**Files:**
+- No code changes required unless failures appear.
+
+**Step 1: Run focused suites**
+
+Run: `python3 -m pytest -q tests/test_mpremote_backend.py tests/test_cli.py tests/test_docs_and_ci.py`
+Expected: PASS.
+
+**Step 2: Run full suite**
+
+Run: `python3 -m pytest -q`
+Expected: PASS.
+
+**Step 3: Optional syntax check**
+
+Run: `python3 -m compileall mpy_cli`
+Expected: No syntax errors.
+
+**Step 4: Final diff review**
+
+Run:
+
+```bash
+git status
+git diff -- mpy_cli/cli.py mpy_cli/backend/mpremote.py tests/test_cli.py tests/test_mpremote_backend.py tests/test_docs_and_ci.py README.md
+```
+
+Expected: Only intended files changed.