Merge pull request #5 from LanternCX/dev

v1.1.0

Author: LanternCX

.progress/PROGRESS.md

@@ -40,3 +40,4 @@ abc123d (or TBD)
 | --- | --- | --- | --- | --- |
 | 2026-03-03-1 | 2026-03-03 | Stabilized full deploy flow and improved onboarding UX | `.progress/entries/2026/2026-03-03-1.md` | deploy, mpremote, config-wizard, docs |
 | 2026-03-04-1 | 2026-03-04 | Added configurable device upload directory with scoped full wipe | `.progress/entries/2026/2026-03-04-1.md` | sync, device-upload-dir, full-mode, planner, mpremote |
+| 2026-03-06-1 | 2026-03-06 | 统一 source_dir 为远端根映射语义 | `.progress/entries/2026/2026-03-06-1.md` | source-dir, scanner, incremental, upload, docs |

.progress/entries/2026/2026-03-06-1.md

@@ -0,0 +1,25 @@
+# 2026-03-06-1
+
+## Date
+2026-03-06
+
+## Title
+统一 source_dir 为远端根映射语义
+
+## Background / Issue
+用户反馈 `source_dir = "src"` 时上传仍保留 `src/` 前缀，不符合“source_dir 作为本地根并直接映射远端根”的期望。仓库内 full、incremental、upload 默认路径和 `.mpyignore` 的路径语言存在语义分裂。
+
+## Actions / Outcome
+- Approach 1: 仅调整 incremental 前缀拼接逻辑 -> 可修复增量路径，但无法覆盖 full 扫描和 upload 默认值，语义仍不统一。
+- Approach 2: 增加新旧语义开关兼容 -> 兼容性更强，但引入长期维护和测试矩阵负担。
+- Final approach: 采用统一语义改造（scanner/full、cli/incremental、upload 默认路径、README 与测试同步） -> full/incremental 一致输出 source-relative 路径，`source_dir="src"` 不再保留 `src/` 远端前缀。
+
+## Lessons / Refinements
+- 路径语义必须跨命令保持单一定义，否则用户会在不同命令间反复切换心智模型。
+- 配置语义变更需要同步更新文档断言测试，避免 README 与实际行为偏移。
+
+## Related Commit Message
+fix(path): align source_dir to source-relative remote mapping
+
+## Related Commit Hash
+TBD

README.md

@@ -147,6 +147,9 @@ mpy-cli config
 mpy-cli plan
 mpy-cli deploy
 mpy-cli upload
+mpy-cli run
+mpy-cli delete
+mpy-cli tree
 ```
 
 说明：
@@ -185,6 +188,10 @@ mpy-cli config
 
 常用配置项说明：
 
+- `source_dir`：本地源码根目录。`plan/deploy` 计算远端路径时以该目录为根，不保留 `source_dir` 前缀。
+- `.mpyignore`：规则匹配对象为“相对 `source_dir` 的路径”。
+- 当 `source_dir = "src"` 时，本地 `src/main.py` 对应远端 `:main.py`。
+- 若历史 `.mpyignore` 规则包含 `src/...` 前缀，需迁移为相对 `source_dir` 的写法。
 - `device_upload_dir`：设备端上传目录前缀，留空表示设备根目录。
 - 当 `device_upload_dir = "apps/demo"` 时，本地 `main.py` 会上传到设备 `:apps/demo/main.py`。
 - `full` 模式会清空该上传目录，而不是整机设备根目录。
@@ -226,7 +233,7 @@ mpy-cli upload [--local LOCAL] [--remote REMOTE] [--port PORT] [--no-interactive
 ```
 
 - `--local`：本地文件路径（如 `seekfree_demo/E01_demo.py`）。
-- `--remote`：设备目标路径；不传时交互模式默认与本地路径一致，可手动修改。
+- `--remote`：设备目标路径；不传时交互模式默认优先使用“相对 `source_dir` 路径”，若本地文件不在 `source_dir` 下则回退为本地输入路径，可手动修改。
 - `--port`：指定设备端口。
 - `--no-interactive`：禁用交互提问；此时需显式提供 `--local` 和 `--remote`。
 - `--yes`：跳过执行前确认。
@@ -239,6 +246,63 @@ mpy-cli upload --local <LOCAL>
 
 填写字段 `LOCAL` 指定本地文件路径之后交互式确认远程路径
 
+### `mpy-cli run`
+
+```bash
+mpy-cli run [--path PATH] [--port PORT] [--no-interactive] [--yes]
+```
+
+- `--path`：设备目标文件路径，语义为相对 `device_upload_dir`。
+- `--port`：指定设备端口。
+- `--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
+- `--yes`：跳过执行前确认。
+
+推荐用法：
+
+```bash
+mpy-cli run --path main.py
+```
+
+若配置 `device_upload_dir = "apps/demo"`，则会执行 `:apps/demo/main.py`。
+
+### `mpy-cli delete`
+
+```bash
+mpy-cli delete [--path PATH] [--port PORT] [--no-interactive] [--yes]
+```
+
+- `--path`：设备目标路径，语义为相对 `device_upload_dir`，可为文件或目录。
+- `--port`：指定设备端口。
+- `--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
+- `--yes`：跳过执行前确认。
+
+推荐用法：
+
+```bash
+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-05-run-command-design.md

@@ -0,0 +1,84 @@
+# run 命令功能设计文档
+
+## 背景
+
+当前 `mpy-cli` 已支持 `plan/deploy/upload`，但缺少“直接执行设备端已存在脚本”的入口。
+在调试场景中，用户经常希望指定设备目标目录下的某个文件直接运行，而不触发上传流程。
+
+## 目标
+
+- 新增 `mpy-cli run` 子命令。
+- 支持通过 `--path` 指定设备端目标文件。
+- `--path` 语义为相对 `device_upload_dir`，与现有 `upload --remote` 规则一致。
+- 复用现有端口解析与执行前确认体验。
+
+## 非目标
+
+- 不在本次支持“先上传再执行”。
+- 不新增批量执行、多文件通配等能力。
+- 不改动 `plan/deploy/upload` 现有语义。
+
+## 命令设计
+
+```bash
+mpy-cli run [--path PATH] [--port PORT] [--no-interactive] [--yes]
+```
+
+- `--path`：设备目标文件路径（相对 `device_upload_dir`）。
+- `--port`：设备串口。
+- `--no-interactive`：禁用交互提问；缺少 `--path` 时直接报错。
+- `--yes`：跳过执行前确认。
+
+## 交互流程
+
+1. 加载配置并解析端口（沿用现有优先级：`--port` > 配置 > 扫描/手输）。
+2. 解析 `--path`：
+   - 有值：直接使用。
+   - 无值且交互模式：提示输入。
+   - 无值且非交互：报错退出。
+3. 计算最终设备路径：`device_upload_dir + path`。
+4. 打印执行预览并确认（`--yes` 可跳过）。
+5. 执行设备端脚本并输出结果。
+
+## 执行架构
+
+- `mpy_cli/cli.py`
+  - 新增 `run` 子命令解析与 `_cmd_run` 流程。
+  - 复用 `_resolve_port()` 与 `_join_upload_target()`。
+- `mpy_cli/backend/mpremote.py`
+  - 新增 `build_run_command()` 与 `run_file()`。
+  - 通过 `mpremote connect <port> resume exec <script>` 在设备端执行目标文件。
+
+## 设备端脚本语义
+
+- 优先尝试用户给定路径。
+- 若设备存在 `/flash`，额外尝试 `/flash/<path>` 兜底。
+- 使用 `open + compile + exec` 执行脚本，并设置：
+  - `__name__ = "__main__"`
+  - `__file__ = <resolved path>`
+
+## 错误处理与返回码
+
+- 参数缺失、配置错误、端口缺失、用户取消：返回 `1`。
+- 设备执行失败（文件不存在、运行时报错、命令失败）：返回 `2`。
+- 执行成功：返回 `0`。
+
+## 测试策略
+
+- `tests/test_cli.py`
+  - `run` 非交互缺少 `--path` 报错。
+  - 交互模式支持输入 `--path`。
+  - `--path` 会按 `device_upload_dir` 拼接。
+  - 执行失败返回 `2`，成功返回 `0`。
+- `tests/test_mpremote_backend.py`
+  - `build_run_command()` 命令拼装正确。
+  - `run_file()` 调用正确命令。
+- `tests/test_docs_and_ci.py`
+  - README 包含 `mpy-cli run` 与 `--path`。
+
+## 验收标准
+
+- 用户可以执行 `mpy-cli run --path <target.py>`。
+- 当配置 `device_upload_dir` 时，`--path` 作为相对路径拼接执行。
+- 有清晰预览与确认，`--yes` 可跳过。
+- 新增测试通过，且不影响现有功能。

docs/plans/2026-03-05-run-command-implementation.md

@@ -0,0 +1,185 @@
+# Run Command Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add `mpy-cli run` to execute an existing file on the MicroPython device using a path relative to `device_upload_dir`.
+
+**Architecture:** Extend CLI routing with a dedicated `run` subcommand that reuses existing config loading, port resolution, confirmation flow, and remote-path joining logic. Add backend support in `MpremoteBackend` to execute a remote file via `mpremote ... exec` with a robust path-resolution script on the device side.
+
+**Tech Stack:** Python, argparse, pathlib, mpremote, pytest.
+
+---
+
+### Task 1: Add backend run command builder and executor
+
+**Files:**
+- Modify: `mpy_cli/backend/mpremote.py`
+- Test: `tests/test_mpremote_backend.py`
+
+**Step 1: Write the failing tests**
+
+```python
+def test_run_builds_expected_command() -> None:
+    backend = MpremoteBackend(binary="mpremote")
+
+    cmd = backend.build_run_command(port="/dev/ttyACM0", remote="apps/demo/main.py")
+
+    assert cmd[0:4] == ["mpremote", "connect", "/dev/ttyACM0", "resume"]
+    assert cmd[4] == "exec"
+    assert "apps/demo/main.py" in cmd[5]
+
+
+def test_run_file_invokes_exec_command() -> 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="ok\n",
+            stderr="",
+        )
+
+    backend = MpremoteBackend(
+        binary="mpremote",
+        runner=fake_runner,
+        resolver=lambda _: "/usr/bin/mpremote",
+    )
+
+    backend.run_file(port="/dev/ttyACM0", remote_path="apps/demo/main.py")
+
+    assert called
+    assert called[0][0:5] == ["mpremote", "connect", "/dev/ttyACM0", "resume", "exec"]
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `python3 -m pytest -q tests/test_mpremote_backend.py -k run`
+Expected: FAIL because `build_run_command/run_file` do not exist.
+
+**Step 3: Write minimal implementation**
+
+Implement `build_run_command()` and `run_file()` in `MpremoteBackend`.
+
+**Step 4: Run tests to verify they pass**
+
+Run: `python3 -m pytest -q tests/test_mpremote_backend.py -k run`
+Expected: PASS.
+
+### Task 2: Add CLI `run` subcommand routing and argument parsing
+
+**Files:**
+- Modify: `mpy_cli/cli.py`
+- Test: `tests/test_cli.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_run_non_interactive_requires_path(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    main(["init", "--no-interactive"])
+
+    code = main(["run", "--no-interactive", "--port", "COM3", "--yes"])
+
+    assert code == 1
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_cli.py -k run_non_interactive_requires_path`
+Expected: FAIL because parser does not include `run`.
+
+**Step 3: Write minimal implementation**
+
+Add parser entry and command dispatch for `run`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_cli.py -k run_non_interactive_requires_path`
+Expected: PASS.
+
+### Task 3: Implement `_cmd_run` flow with path join, confirmation, and execution
+
+**Files:**
+- Modify: `mpy_cli/cli.py`
+- Test: `tests/test_cli.py`
+
+**Step 1: Write the failing tests**
+
+```python
+def test_run_executes_remote_file_with_device_upload_prefix(tmp_path: Path, monkeypatch) -> None:
+    ...
+
+
+def test_run_returns_failure_code_when_backend_run_fails(tmp_path: Path, monkeypatch) -> None:
+    ...
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `python3 -m pytest -q tests/test_cli.py -k "run_executes_remote_file or run_returns_failure_code"`
+Expected: FAIL because `_cmd_run` is not implemented.
+
+**Step 3: Write minimal implementation**
+
+Implement `_cmd_run()` in `cli.py`:
+- load config
+- resolve port
+- resolve/validate path input
+- compute final remote path via `_join_upload_target`
+- preview + confirmation
+- `backend.ensure_available()` and `backend.run_file(...)`
+- return code `0/1/2` per design
+
+**Step 4: Run tests to verify they pass**
+
+Run: `python3 -m pytest -q tests/test_cli.py -k "run_executes_remote_file or run_returns_failure_code or run_non_interactive_requires_path"`
+Expected: PASS.
+
+### Task 4: Update README and docs consistency tests
+
+**Files:**
+- Modify: `README.md`
+- Modify: `tests/test_docs_and_ci.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_readme_lists_run_command_parameters() -> None:
+    content = Path("README.md").read_text(encoding="utf-8")
+    for token in ["mpy-cli run", "--path"]:
+        assert token in content
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest -q tests/test_docs_and_ci.py -k run`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+Add `run` command section to README and include `--path` semantics relative to `device_upload_dir`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest -q tests/test_docs_and_ci.py -k run`
+Expected: PASS.
+
+### Task 5: Regression verification
+
+**Files:**
+- Test: `tests/test_cli.py`
+- Test: `tests/test_mpremote_backend.py`
+- Test: `tests/test_docs_and_ci.py`
+- Test: `tests/test_executor.py`
+
+**Step 1: Run focused suites**
+
+Run: `python3 -m pytest -q tests/test_cli.py tests/test_mpremote_backend.py tests/test_docs_and_ci.py`
+Expected: PASS.
+
+**Step 2: Run full regression**
+
+Run: `python3 -m pytest -q`
+Expected: PASS with no new failures.