mavctl 0.2.0__tar.gz

mavctl-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+# Publishing is restricted to formal PEP 440 release tags (vX.Y.Z).
+# Milestone tags such as v0.2.0-phase2 are NEVER published: the broad "v*"
+# trigger exists only so wrong tags fail loudly instead of silently doing
+# nothing; the first step enforces the strict vX.Y.Z pattern.
+#
+# ONE-TIME MANUAL SETUP (required before the first real tag push):
+#   1. On pypi.org, register a Trusted Publisher for this project:
+#        PyPI project name : mavctl
+#        Owner             : LeaderOnePro
+#        Repository        : mavctl
+#        Workflow filename : publish.yml
+#        Environment       : leave empty (no environment is used here);
+#                            if you ever add `environment:` below, the name
+#                            on PyPI must match exactly.
+#   2. Rehearse on TestPyPI first and validate dist/ locally — see
+#      docs/PUBLISHING.md before cutting the first real vX.Y.Z tag.
+#
+# This workflow uses OIDC Trusted Publishing only; it never requires or reads
+# a PyPI token secret.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC identity for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Enforce PEP 440 release tag (vX.Y.Z)
+        env:
+          RELEASE_TAG_PATTERN: '^v[0-9]+\.[0-9]+\.[0-9]+$'
+        run: |
+          if [[ ! "${GITHUB_REF_NAME}" =~ ${RELEASE_TAG_PATTERN} ]]; then
+            echo "::error::'${GITHUB_REF_NAME}' is not a formal release tag." \
+                 "Only vX.Y.Z (e.g. v0.2.0) publishes to PyPI." \
+                 "Milestone tags like v0.2.0-phase2 are never published."
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type-check (mypy)
+        run: uv run mypy .
+
+      - name: Test (non-SITL)
+        run: uv run pytest -m "not sitl"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify tag matches package version
+        run: |
+          expected="v$(grep -m1 '^version' pyproject.toml | cut -d '"' -f2)"
+          if [[ "${GITHUB_REF_NAME}" != "${expected}" ]]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} != package version ${expected}." \
+                 "Land a release commit setting version = \"${GITHUB_REF_NAME#v}\" first."
+            exit 1
+          fi
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mavctl-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs / uv
+.venv/
+venv/
+uv.lock.bak
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mavctl runtime state
+.mavctl/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

mavctl-0.2.0/AGENTS.md

@@ -0,0 +1,61 @@
+# mavctl
+
+Headless ground control station CLI for MAVLink vehicles (ArduPilot-first),
+designed to be driven by AI coding agents (Claude Code, Codex, etc.) as well as humans.
+
+## 架构（不可违背的核心决策）
+
+三层架构，依赖方向严格单向：CLI → Daemon → Adapter
+
+1. **CLI 层**（`mavctl/cli/`）：Typer 实现。薄壳，只做参数解析、
+   调用 daemon、格式化输出。不含任何业务逻辑。
+2. **Daemon 层**（`mavctl/daemon/`）：常驻进程，维持 MAVLink 连接、
+   缓存遥测状态、执行安全护栏检查。通过 Unix domain socket
+   （JSON-RPC 风格）与 CLI 通信。
+3. **Adapter 层**（`mavctl/adapter/`）：pymavlink 的唯一使用场所。
+   pymavlink 的 import 不得出现在其他任何层。
+
+## 技术栈
+
+- Python >= 3.10，包管理用 uv，构建配置 pyproject.toml
+- CLI: typer | 数据模型: pydantic v2 | MAVLink: pymavlink
+- 测试: pytest + pytest-asyncio | Lint: ruff | 类型: mypy（strict）
+- Daemon 内部用 asyncio；pymavlink 的阻塞调用包在 executor 里
+
+## 铁律
+
+- **所有命令支持 `--json`**：输出结构化 JSON 到 stdout；人类可读格式为默认
+- **退出码语义**：0=成功 1=通用错误 2=参数错误 3=daemon 未运行
+  4=飞控未连接 5=安全护栏拒绝 6=飞控 NACK/超时
+- **安全护栏**：arm / takeoff / mode / rtl 等改变载具状态的命令
+  必须要求 `--confirm` 标志，否则拒绝执行（退出码 5）并说明原因
+- **危险命令支持 `--dry-run`**
+- 错误信息输出到 stderr，JSON 模式下为 `{"error": {...}}`
+- 每个公共函数写类型注解；不写无意义的注释
+
+## 设计原则（Phase 2 起贯彻，与铁律同等约束力）
+
+- **异步操作语义**：所有会改变载具状态且需要时间完成的命令
+  （takeoff / land / rtl / mode 等）必须支持两种模式：
+  - 默认：发出指令并确认飞控 ACK 后立即返回
+  - `--wait`：阻塞直到目标状态达成（如到达目标高度、完成降落），
+    配套 `--timeout <秒>`（默认 60），超时返回退出码 6
+- **status 输出自描述**：`mavctl status` 的输出必须让 agent 单次查询
+  就能重建对载具的完整认知，至少包含：connected、armed、mode、
+  system_status、relative_alt、landed_state（若可用）、battery、
+  gps_fix、home_position（若已设置）
+- **幂等友好**：重复执行已达成的状态变更应返回成功而非报错
+  （如对已 armed 的载具执行 arm，返回 exit 0 并在输出中标注
+  "already armed"），确保 agent 重试时不被绊倒
+
+## 测试要求
+
+- Adapter 层：用 mock MAVLink 连接做单元测试
+- 集成测试：标记 `@pytest.mark.sitl`，需要本地 ArduPilot SITL
+  （默认 udp:127.0.0.1:14550），CI 中可跳过
+- 每次修改后运行：`ruff check . && mypy . && pytest -m "not sitl"`
+
+## 常用命令
+
+- 安装依赖：`uv sync`
+- 启动 SITL（若已安装）：`sim_vehicle.py -v ArduCopter --out udp:127.0.0.1:14550`

mavctl-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

mavctl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LeaderOnePro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mavctl-0.2.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: mavctl
+Version: 0.2.0
+Summary: Headless, agent-first MAVLink ground-control CLI for ArduPilot vehicles
+Project-URL: Homepage, https://github.com/LeaderOnePro/mavctl
+Project-URL: Repository, https://github.com/LeaderOnePro/mavctl
+Project-URL: Issues, https://github.com/LeaderOnePro/mavctl/issues
+Project-URL: Documentation, https://github.com/LeaderOnePro/mavctl/tree/main/docs
+Author: LeaderOnePro
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pymavlink>=2.4.40
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# mavctl
+
+> Headless, agent-first MAVLink ground-control CLI for ArduPilot vehicles.
+
+mavctl is **ArduPilot-first** and built to be driven by both humans on a
+terminal and AI coding agents (Claude Code, Codex, OpenClaw, …). A resident
+daemon keeps the MAVLink link alive and caches vehicle state; every CLI call
+is one short, structured request to that daemon.
+
+**Status:** developed and verified against ArduPilot SITL. It has not been
+proven across the breadth of real MAVLink vehicles and is **not** presented as
+ready for production flight on a real aircraft.
+
+## Why mavctl
+
+GUI ground stations such as Mission Planner or QGroundControl are excellent
+for a human at the controls — and a poor interface for a shell script or an
+LLM agent: clickable UIs, no stable exit codes, no machine-readable output.
+
+mavctl takes the other side of that trade:
+
+- the daemon owns the MAVLink connection and continuously caches telemetry,
+  so each command is quick and stateless;
+- every command prints human-readable output by default and structured JSON
+  with `--json`;
+- failures carry explicit exit codes (3 daemon down, 4 link lost, 5 guard
+  rejection, 6 vehicle NACK / timeout) instead of stack traces;
+- dangerous operations pass safety guards before anything reaches the vehicle;
+- mavctl embeds no LLM — it is designed to be *called* by agents such as
+  Claude Code, Codex or OpenClaw, or by plain bash.
+
+## Current capabilities
+
+Implemented commands — this is the complete list:
+
+```bash
+mavctl daemon start|stop|status
+mavctl status
+mavctl telemetry
+mavctl arm
+mavctl disarm
+mavctl mode <MODE>
+mavctl takeoff --alt <metres>
+mavctl land
+mavctl rtl
+```
+
+Cross-cutting behaviour:
+
+| Flag / behaviour | Meaning |
+| ---------------- | ------- |
+| `--json` | structured output on stdout; errors as `{"error": {...}}` on stderr |
+| `--confirm` | required on every state-changing command; without it exit code 5 |
+| `--dry-run` | run the exact same guards, never reach the vehicle |
+| `--wait --timeout <s>` | block until the target state is reached (default 60 s) |
+| idempotent repeats | re-applying an achieved change succeeds ("already armed") |
+| transaction safety | ACK/NACK handling, serialized commands, link-loss abort |
+
+Not implemented — current scope only, not a roadmap promise:
+
+```text
+Mission upload/download/start
+Parameters
+Geofence
+Log download / analysis
+Firmware flashing
+Multi-vehicle orchestration
+```
+
+## Quickstart with ArduPilot SITL
+
+Requires Python >= 3.10 and [uv](https://docs.astral.sh/uv/). Always bring up
+SITL first; do not point an agent-driven workflow at a real vehicle.
+
+Terminal 1 — start ArduPilot SITL:
+
+```bash
+sim_vehicle.py -v ArduCopter --out udp:127.0.0.1:14550
+```
+
+Terminal 2 — install from source and connect:
+
+```bash
+uv sync
+uv run mavctl daemon start --connect udp:127.0.0.1:14550
+uv run mavctl status --json
+```
+
+Safe takeoff to 10 m and return to launch:
+
+```bash
+uv run mavctl mode GUIDED --confirm --wait
+uv run mavctl arm --confirm
+# Poll status --json until armed=true (the arm ACK can beat the heartbeat)
+uv run mavctl takeoff --alt 10 --confirm --wait --timeout 45
+uv run mavctl rtl --confirm --wait --timeout 120
+uv run mavctl daemon stop
+```
+
+Safety notes — read before pointing mavctl at anything that flies:
+
+- Validate every workflow in SITL first; treat real-aircraft use as its own
+  review process.
+- After `arm`, poll `status --json` until `armed=true` before takeoff: the
+  COMMAND_ACK can arrive about one heartbeat before reported state catches up.
+- End flights with `rtl` / `land`, not `disarm`. Ordinary `disarm` requires
+  provable ground contact (`ground_state_unknown` otherwise).
+- `disarm --force` is an emergency motor stop only — in flight it can cause a
+  crash.
+- There is no `arm --force` anywhere in mavctl; pre-arm checks cannot be
+  bypassed.
+
+## Installation
+
+### From PyPI
+
+mavctl's first production release (`0.2.0`) is being prepared. After the
+PyPI release is published, install with:
+
+```bash
+uv tool install mavctl
+uvx mavctl --help
+pipx install mavctl
+```
+
+Until that release is published these commands have nothing to fetch from
+production PyPI; TestPyPI rehearsal artifacts are not production releases.
+Release status and the publishing runbook live in
+[docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+### From source
+
+For development from source, use `uv sync` and `uv run mavctl …`:
+
+```bash
+git clone https://github.com/LeaderOnePro/mavctl.git
+cd mavctl
+uv sync
+uv run mavctl --help
+```
+
+## Agent Skill
+
+The repository ships a portable agent Skill under `skills/mavctl-flight/`
+(entrypoint plus workflows / safety / troubleshooting references). It is a
+source asset of this repo, not an installed package.
+
+To use it with an agent runtime, install or symlink this directory according
+to that runtime's current Skill discovery convention.
+
+Example for Claude Code, project-local to this repository:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../skills/mavctl-flight .claude/skills/mavctl-flight
+```
+
+That is one concrete example, not a universal convention — runtimes differ.
+
+## Safety model
+
+Short version; full details in
+[skills/mavctl-flight/references/safety.md](skills/mavctl-flight/references/safety.md):
+
+- the daemon owns the vehicle link; CLI calls are short transactions;
+- state-changing commands require `--confirm`; `--dry-run` previews decisions;
+- exit 4 = no live vehicle state (link lost / heartbeat expired), including
+  mid-`--wait` loss (`link_lost_during_wait`);
+- exit 5 = guard rejection with structured `reason` + `hint`;
+- exit 6 = vehicle NACK / ACK timeout / wait timeout;
+- force-arm does not exist at any layer (CLI option, RPC field, adapter verb);
+- ordinary `disarm` needs positive ground evidence, else `ground_state_unknown`
+  (exit 5);
+- after link loss, `status` reflects stale cache: `armed` renders unknown/n/a,
+  never silently disarmed.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run mypy .
+uv run pytest -m "not sitl"
+uv run pytest -m sitl   # requires a running ArduPilot SITL
+```
+
+Further reading:
+
+- [docs/SITL_ACCEPTANCE.md](docs/SITL_ACCEPTANCE.md)
+- [docs/SITL_ACCEPTANCE_PHASE2.md](docs/SITL_ACCEPTANCE_PHASE2.md)
+- [AGENTS.md](AGENTS.md) — architecture rules and contribution constraints
+- [skills/mavctl-flight/SKILL.md](skills/mavctl-flight/SKILL.md) — agent-facing flight guidance
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 LeaderOnePro.

mavctl-0.2.0/README.md

@@ -0,0 +1,196 @@
+# mavctl
+
+> Headless, agent-first MAVLink ground-control CLI for ArduPilot vehicles.
+
+mavctl is **ArduPilot-first** and built to be driven by both humans on a
+terminal and AI coding agents (Claude Code, Codex, OpenClaw, …). A resident
+daemon keeps the MAVLink link alive and caches vehicle state; every CLI call
+is one short, structured request to that daemon.
+
+**Status:** developed and verified against ArduPilot SITL. It has not been
+proven across the breadth of real MAVLink vehicles and is **not** presented as
+ready for production flight on a real aircraft.
+
+## Why mavctl
+
+GUI ground stations such as Mission Planner or QGroundControl are excellent
+for a human at the controls — and a poor interface for a shell script or an
+LLM agent: clickable UIs, no stable exit codes, no machine-readable output.
+
+mavctl takes the other side of that trade:
+
+- the daemon owns the MAVLink connection and continuously caches telemetry,
+  so each command is quick and stateless;
+- every command prints human-readable output by default and structured JSON
+  with `--json`;
+- failures carry explicit exit codes (3 daemon down, 4 link lost, 5 guard
+  rejection, 6 vehicle NACK / timeout) instead of stack traces;
+- dangerous operations pass safety guards before anything reaches the vehicle;
+- mavctl embeds no LLM — it is designed to be *called* by agents such as
+  Claude Code, Codex or OpenClaw, or by plain bash.
+
+## Current capabilities
+
+Implemented commands — this is the complete list:
+
+```bash
+mavctl daemon start|stop|status
+mavctl status
+mavctl telemetry
+mavctl arm
+mavctl disarm
+mavctl mode <MODE>
+mavctl takeoff --alt <metres>
+mavctl land
+mavctl rtl
+```
+
+Cross-cutting behaviour:
+
+| Flag / behaviour | Meaning |
+| ---------------- | ------- |
+| `--json` | structured output on stdout; errors as `{"error": {...}}` on stderr |
+| `--confirm` | required on every state-changing command; without it exit code 5 |
+| `--dry-run` | run the exact same guards, never reach the vehicle |
+| `--wait --timeout <s>` | block until the target state is reached (default 60 s) |
+| idempotent repeats | re-applying an achieved change succeeds ("already armed") |
+| transaction safety | ACK/NACK handling, serialized commands, link-loss abort |
+
+Not implemented — current scope only, not a roadmap promise:
+
+```text
+Mission upload/download/start
+Parameters
+Geofence
+Log download / analysis
+Firmware flashing
+Multi-vehicle orchestration
+```
+
+## Quickstart with ArduPilot SITL
+
+Requires Python >= 3.10 and [uv](https://docs.astral.sh/uv/). Always bring up
+SITL first; do not point an agent-driven workflow at a real vehicle.
+
+Terminal 1 — start ArduPilot SITL:
+
+```bash
+sim_vehicle.py -v ArduCopter --out udp:127.0.0.1:14550
+```
+
+Terminal 2 — install from source and connect:
+
+```bash
+uv sync
+uv run mavctl daemon start --connect udp:127.0.0.1:14550
+uv run mavctl status --json
+```
+
+Safe takeoff to 10 m and return to launch:
+
+```bash
+uv run mavctl mode GUIDED --confirm --wait
+uv run mavctl arm --confirm
+# Poll status --json until armed=true (the arm ACK can beat the heartbeat)
+uv run mavctl takeoff --alt 10 --confirm --wait --timeout 45
+uv run mavctl rtl --confirm --wait --timeout 120
+uv run mavctl daemon stop
+```
+
+Safety notes — read before pointing mavctl at anything that flies:
+
+- Validate every workflow in SITL first; treat real-aircraft use as its own
+  review process.
+- After `arm`, poll `status --json` until `armed=true` before takeoff: the
+  COMMAND_ACK can arrive about one heartbeat before reported state catches up.
+- End flights with `rtl` / `land`, not `disarm`. Ordinary `disarm` requires
+  provable ground contact (`ground_state_unknown` otherwise).
+- `disarm --force` is an emergency motor stop only — in flight it can cause a
+  crash.
+- There is no `arm --force` anywhere in mavctl; pre-arm checks cannot be
+  bypassed.
+
+## Installation
+
+### From PyPI
+
+mavctl's first production release (`0.2.0`) is being prepared. After the
+PyPI release is published, install with:
+
+```bash
+uv tool install mavctl
+uvx mavctl --help
+pipx install mavctl
+```
+
+Until that release is published these commands have nothing to fetch from
+production PyPI; TestPyPI rehearsal artifacts are not production releases.
+Release status and the publishing runbook live in
+[docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+### From source
+
+For development from source, use `uv sync` and `uv run mavctl …`:
+
+```bash
+git clone https://github.com/LeaderOnePro/mavctl.git
+cd mavctl
+uv sync
+uv run mavctl --help
+```
+
+## Agent Skill
+
+The repository ships a portable agent Skill under `skills/mavctl-flight/`
+(entrypoint plus workflows / safety / troubleshooting references). It is a
+source asset of this repo, not an installed package.
+
+To use it with an agent runtime, install or symlink this directory according
+to that runtime's current Skill discovery convention.
+
+Example for Claude Code, project-local to this repository:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../skills/mavctl-flight .claude/skills/mavctl-flight
+```
+
+That is one concrete example, not a universal convention — runtimes differ.
+
+## Safety model
+
+Short version; full details in
+[skills/mavctl-flight/references/safety.md](skills/mavctl-flight/references/safety.md):
+
+- the daemon owns the vehicle link; CLI calls are short transactions;
+- state-changing commands require `--confirm`; `--dry-run` previews decisions;
+- exit 4 = no live vehicle state (link lost / heartbeat expired), including
+  mid-`--wait` loss (`link_lost_during_wait`);
+- exit 5 = guard rejection with structured `reason` + `hint`;
+- exit 6 = vehicle NACK / ACK timeout / wait timeout;
+- force-arm does not exist at any layer (CLI option, RPC field, adapter verb);
+- ordinary `disarm` needs positive ground evidence, else `ground_state_unknown`
+  (exit 5);
+- after link loss, `status` reflects stale cache: `armed` renders unknown/n/a,
+  never silently disarmed.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run mypy .
+uv run pytest -m "not sitl"
+uv run pytest -m sitl   # requires a running ArduPilot SITL
+```
+
+Further reading:
+
+- [docs/SITL_ACCEPTANCE.md](docs/SITL_ACCEPTANCE.md)
+- [docs/SITL_ACCEPTANCE_PHASE2.md](docs/SITL_ACCEPTANCE_PHASE2.md)
+- [AGENTS.md](AGENTS.md) — architecture rules and contribution constraints
+- [skills/mavctl-flight/SKILL.md](skills/mavctl-flight/SKILL.md) — agent-facing flight guidance
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 LeaderOnePro.