meshcorectl 0.1.0__tar.gz

meshcorectl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type check (mypy)
+        run: mypy
+
+      - name: Test with coverage gate
+        # Also enforces docs/command-reference.md staying in sync with the
+        # real CLI (tests/unit/test_command_reference.py regenerates it in
+        # memory and diffs against what's committed).
+        run: pytest
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/meshcorectl
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel + sdist
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # A push to main whose version wasn't bumped would otherwise fail
+          # the workflow trying to re-upload an existing release.
+          skip-existing: true

meshcorectl-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

meshcorectl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faradome
+
+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.

meshcorectl-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: meshcorectl
+Version: 0.1.0
+Summary: A kubectl-style command line interface for MeshCore companion radios
+Project-URL: Homepage, https://github.com/Faradome/meshcorectl
+Project-URL: Issues, https://github.com/Faradome/meshcorectl/issues
+Author-email: William Canterbury <william.canterbury@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.22
+Requires-Dist: click>=8.1
+Requires-Dist: meshcore>=2.3.9
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyserial; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# meshcorectl
+
+> **This is an AI-generated application.** The design, code, tests, and documentation in this
+> repository were produced by an AI coding agent (Claude), directed and reviewed by a human
+> maintainer.
+
+A non-interactive, kubectl-style CLI for MeshCore companion radios:
+`meshcorectl VERB [TYPE] [NAME] [flags]`, named connection contexts (BLE/serial/TCP), and
+`-o table|json|yaml|wide|name` output on every read command.
+
+For design rationale and architecture, see [PLAN.md](PLAN.md).
+
+## Install
+
+```bash
+pip install -e ".[dev]"    # from a checkout, until this is published
+```
+
+## Quickstart
+
+```bash
+# Point a named context at your device (BLE, serial, or TCP)
+meshcorectl config set-context home --ble-address AA:BB:CC:DD:EE:FF
+meshcorectl config use-context home
+
+# Read
+meshcorectl get contacts
+meshcorectl get contact alice -o yaml
+meshcorectl describe device
+meshcorectl logs -f
+
+# Write
+meshcorectl send message alice "hello"
+meshcorectl create channel 1 "#general"
+meshcorectl delete contact -l 't=client,u>30d'   # -l selectors batch across matches
+
+# Shell completion
+source <(meshcorectl completion bash)   # or zsh / fish
+```
+
+Every command has real `--help` text; [docs/command-reference.md](docs/command-reference.md) is
+the same text generated into one file. Nothing here is interactive — no REPL, no prompts on the
+happy path (an exception: `login` without `--password`/`--password-stdin` prompts securely for
+one, the same as `ssh` or `git`) — every command is a single invocation that connects, does one
+thing, and exits, which is what makes it scriptable.
+
+## Status
+
+Every command in this README is implemented and tested. A background-agent daemon for
+low-latency repeated invocations (`meshcored`) is planned but not yet built.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                # 100% line+branch coverage enforced
+ruff check .
+mypy
+```
+
+After adding or changing a command, regenerate the reference doc:
+
+```bash
+python3 scripts/generate_command_reference.py
+```
+
+A test (`tests/unit/test_command_reference.py`) fails if it's out of date.
+
+## License
+
+[MIT](LICENSE) — same license as the original
+[meshcore-cli](https://github.com/meshcore-dev/meshcore-cli).

meshcorectl-0.1.0/PLAN.md

@@ -0,0 +1,165 @@
+# meshcorectl — design & architecture
+
+A non-interactive, kubectl-style CLI for MeshCore companion radios. The `meshcore` PyPI package
+provides the BLE/serial/TCP transports, frame parsing, an async client with a `commands.*` API,
+and an `EventType` pub/sub model; this project implements only the CLI layer on top of it.
+
+## Command tree
+
+```
+meshcorectl
+├── get           device | contacts [-l] [-A] | contact NAME | channels [-A] | channel N |
+│                 pending-contacts | path CONTACT | time
+├── describe      device | contact NAME
+├── create        contact --uri URI   (import)
+│                 channel N NAME [KEY]
+├── delete        contact NAME | -l selector
+│                 channel N
+├── send          message [CONTACT | -l selector] TEXT [--wait-ack]
+│                 channel N TEXT
+├── exec          [REPEATER | -l selector] -- CLI_CMD  (raw repeater console command)
+├── login         [REPEATER | -l selector] [--password | --password-stdin]
+├── logout        REPEATER
+├── top           contact NAME [--history]        (telemetry / min-max-avg)
+├── logs          [-f] [--since DURATION] [--rx]   (message stream)
+├── trace         PATH
+├── advert        [--flood]
+├── reboot        --yes
+├── set           device PARAM VALUE               (radio, tx-power, telemetry-mode, …)
+├── scan          [--ble] [--serial] [--timeout]    (non-interactive discovery table)
+├── config        get-contexts | use-context NAME | set-context NAME [flags] |
+│                 current-context | view | delete-context NAME
+├── version
+└── completion    bash | zsh | fish
+```
+
+Every noun gets singular + plural + short form (`contact`/`contacts`/`ct`, `channel`/`channels`/`ch`).
+Every command has real `--help` text, generated into [docs/command-reference.md](docs/command-reference.md).
+
+No `delete pending-contacts`: pending contacts are watched for over one `--timeout` window (see
+`get pending-contacts`), never persisted, so there is nothing for a delete to ever clear.
+
+## kubectl idioms this CLI borrows
+
+| kubectl idiom | meshcorectl equivalent |
+|---|---|
+| `kubectl get pods`, `kubectl get pod foo -o yaml` | `meshcorectl get contacts`, `meshcorectl get contact foo -o yaml` |
+| `kubectl describe pod foo` | `meshcorectl describe contact foo` (telemetry, path, flags, last-seen, one human view) |
+| Resource short names (`po`, `svc`, `deploy`) | `ct` (contact), `ch` (channel), `dev` (device) |
+| `-o json\|yaml\|wide\|name` | Same flag, same values, on every read command |
+| `-l/--selector key=value` batch targeting | Same flag on `get`, `delete`, `send`, `exec`, `login` (`-l t=2,u<24h`) |
+| `kubectl exec pod -- cmd` | `meshcorectl exec repeater-name -- <raw console command>` |
+| `kubectl logs [-f] [--since]` | `meshcorectl logs [-f] [--since]` |
+| `kubectl top node/pod` | `meshcorectl top contact NAME [--history]` |
+| `kubectl config get-contexts/use-context/current-context/view` | `meshcorectl config …` over named connection profiles |
+| `kubectl version` | `meshcorectl version` (CLI version + connected device firmware) |
+| `kubectl completion bash/zsh/fish` | `meshcorectl completion bash/zsh/fish` |
+| `--dry-run` | Same, on every mutating command |
+| Non-CRUD standalone verbs (`cordon`, `drain`) | `advert`, `reboot`, `trace`, `login`, `logout` stay top-level, not shoehorned into `get`/`create`/`delete` |
+
+## Design decisions
+
+### One-shot connections; a background daemon is future work
+
+Each invocation opens a connection, acts, and disconnects. Simplest model; fine for interactive
+use and for scripts that don't call `meshcorectl` in a tight loop (BLE connect is the slow case,
+~1-3s; TCP/serial are fast).
+
+A future `meshcored` background agent would own a persistent BLE/serial/TCP connection and
+expose it over a local socket, making `meshcorectl` a thin client — unlocking `get contacts -w`
+(watch), instant repeated invocations, and event subscriptions that outlive one command.
+`connect.py` is the one seam such a client would replace: every command talks to a small
+`MeshCoreConnection` protocol, never to `meshcore.MeshCore` directly, so swapping the connection
+method touches no command module. This is also what makes command modules testable against a
+fake connection (see Testing, below).
+
+### Click as the CLI framework
+
+Nested `Group`s map directly onto the command tree; a `click.Context` carries the resolved
+connection and output formatter down through subcommands; shell completion is close to free.
+`click.testing.CliRunner` runs any command in-process with captured stdout/stderr/exit code,
+which is what makes full test coverage practical.
+
+### Plain aligned text, no color
+
+Fixed-width columns computed per invocation, consistent left-justification (text and numeric
+columns alike, matching kubectl's own tabwriter), `-` placeholders for empty fields. No ANSI
+color, no `rich`/`colorama` dependency — a ~50-line internal table writer covers it. JSON via
+stdlib `json`; YAML via `pyyaml`.
+
+### `-l/--selector` filtering
+
+A `t=`/`h=`/`u=`/`d`/`f` contact-filter grammar as a `-l/--selector` flag reused across
+`get`/`delete`/`send`/`exec`/`login`, rather than a separate batch-apply command:
+
+```
+meshcorectl delete contact -l 't=1,u>2d'
+meshcorectl login -l 't=2,d' --password-stdin < password.txt
+```
+
+Exactly `kubectl delete pods -l app=foo`'s shape: one flag, reused everywhere.
+
+### Binary name: `meshcorectl`
+
+In the `kubectl`/`systemctl`/`<subject>ctl` family.
+
+## Package layout
+
+```
+meshcorectl/
+├── pyproject.toml
+├── src/meshcorectl/
+│   ├── cli.py             # root Click group: global --context/-o/--timeout/-v
+│   ├── context_store.py   # ~/.config/meshcorectl/config.yaml — named connection contexts
+│   ├── connect.py         # resolve context -> meshcore.MeshCore via create_ble/serial/tcp
+│   ├── mesh_data.py        # Event/payload -> plain dict translation, no Click
+│   ├── selectors.py        # -l filter grammar (parse + match against a contact dict)
+│   ├── output/
+│   │   ├── __init__.py    # dispatch on -o table|wide|json|yaml|name
+│   │   ├── table.py       # dependency-free column writer
+│   │   └── resources.py   # per-resource column definitions
+│   └── commands/          # one module per verb: get.py, describe.py, create.py, ...
+├── tests/
+│   ├── fakes/meshcore_double.py  # fake MeshCore/CommandHandler: scripted Event responses
+│   ├── unit/               # selectors, table/output formatting, context_store, mesh_data
+│   └── commands/           # one test module per commands/*.py, via Click CliRunner + the fake
+└── docs/command-reference.md     # generated from --help
+```
+
+`connect.py` is the only module that imports `meshcore`'s transport classes; every command
+module receives an already-connected client through the Click context, which is what keeps
+`tests/commands/` fast and hardware-free.
+
+## Non-interactive by design
+
+No REPL, chat navigation, line-redirection DSL, alias engine, or interactive device picker. A
+shell already covers these better: pipe to `jq`, redirect with `>`, use shell aliases/functions.
+`scan` prints a plain table of discoverable devices to pick an address from, instead of an
+interactive picker.
+
+## Testing strategy
+
+- **A fake connection is the foundation.** `tests/fakes/meshcore_double.py` implements the same
+  surface every command module calls (`commands.get_contacts`, `commands.send_msg`, `subscribe`,
+  …) and returns scripted `Event`/`EventType` values, including error payloads, timeouts, and
+  disconnects. No command module ever touches real BLE/serial/TCP in a test.
+- **Every command gets a table-driven CliRunner test**: happy path, the device returning
+  `EventType.ERROR`, a not-found argument, and — for mutating commands — `--dry-run` performing
+  no `commands.*` call. Selector-aware commands get matrix cases (matches none/one/many).
+  Commands that only need one connection assert `connect_call_count == 1`.
+- **Pure-logic modules get unit tests with no Click/CLI involvement**: `selectors.py` (grammar
+  parsing, comparison operators, relative-time suffixes), `output/table.py` (column widths, empty
+  placeholders), `context_store.py` (YAML round-trip, missing/corrupt file, unknown context),
+  `mesh_data.py` (Event-to-dict translation for every resource kind).
+- **Coverage gate**: `pytest --cov=meshcorectl --cov-report=term-missing --cov-fail-under=90`.
+  `connect.py`'s transport-selection calls are the one piece that would need real hardware to
+  exercise directly; everything above that seam is covered by the fake.
+- **Out of scope for now**: hardware-in-the-loop tests against a real device in CI. Worth
+  revisiting once a `meshcored` daemon exists, since a long-lived process is a better fit for an
+  opt-in nightly hardware job than a one-shot CLI is.
+
+## Future work
+
+A `meshcored` background agent (see Design decisions, above): a small daemon owns the persistent
+connection and exposes it over a local socket, so `meshcorectl` becomes a thin, instant client.
+Not built yet.

meshcorectl-0.1.0/README.md

@@ -0,0 +1,74 @@
+# meshcorectl
+
+> **This is an AI-generated application.** The design, code, tests, and documentation in this
+> repository were produced by an AI coding agent (Claude), directed and reviewed by a human
+> maintainer.
+
+A non-interactive, kubectl-style CLI for MeshCore companion radios:
+`meshcorectl VERB [TYPE] [NAME] [flags]`, named connection contexts (BLE/serial/TCP), and
+`-o table|json|yaml|wide|name` output on every read command.
+
+For design rationale and architecture, see [PLAN.md](PLAN.md).
+
+## Install
+
+```bash
+pip install -e ".[dev]"    # from a checkout, until this is published
+```
+
+## Quickstart
+
+```bash
+# Point a named context at your device (BLE, serial, or TCP)
+meshcorectl config set-context home --ble-address AA:BB:CC:DD:EE:FF
+meshcorectl config use-context home
+
+# Read
+meshcorectl get contacts
+meshcorectl get contact alice -o yaml
+meshcorectl describe device
+meshcorectl logs -f
+
+# Write
+meshcorectl send message alice "hello"
+meshcorectl create channel 1 "#general"
+meshcorectl delete contact -l 't=client,u>30d'   # -l selectors batch across matches
+
+# Shell completion
+source <(meshcorectl completion bash)   # or zsh / fish
+```
+
+Every command has real `--help` text; [docs/command-reference.md](docs/command-reference.md) is
+the same text generated into one file. Nothing here is interactive — no REPL, no prompts on the
+happy path (an exception: `login` without `--password`/`--password-stdin` prompts securely for
+one, the same as `ssh` or `git`) — every command is a single invocation that connects, does one
+thing, and exits, which is what makes it scriptable.
+
+## Status
+
+Every command in this README is implemented and tested. A background-agent daemon for
+low-latency repeated invocations (`meshcored`) is planned but not yet built.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                # 100% line+branch coverage enforced
+ruff check .
+mypy
+```
+
+After adding or changing a command, regenerate the reference doc:
+
+```bash
+python3 scripts/generate_command_reference.py
+```
+
+A test (`tests/unit/test_command_reference.py`) fails if it's out of date.
+
+## License
+
+[MIT](LICENSE) — same license as the original
+[meshcore-cli](https://github.com/meshcore-dev/meshcore-cli).