meshcore-irc-bridge 0.1.0__tar.gz

meshcore_irc_bridge-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: mypy
+      - run: pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - id: version
+        run: |
+          echo "version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Check whether this version is already on PyPI
+        id: check
+        run: |
+          VERSION="${{ needs.build.outputs.version }}"
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/meshcore-irc-bridge/${VERSION}/json")
+          if [ "$STATUS" = "200" ]; then
+            echo "Version ${VERSION} is already published; skipping upload."
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to PyPI
+        if: steps.check.outputs.exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

meshcore_irc_bridge-0.1.0/.gitignore

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

meshcore_irc_bridge-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.

meshcore_irc_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: meshcore-irc-bridge
+Version: 0.1.0
+Summary: A one-way bridge relaying MeshCore companion radio channel messages into IRC channels
+Project-URL: Homepage, https://github.com/Faradome/meshcore-irc-bridge
+Project-URL: Issues, https://github.com/Faradome/meshcore-irc-bridge/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 :: Chat :: Internet Relay Chat
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.22
+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
+
+# meshcore-irc-bridge
+
+> **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 one-way bridge: it connects to a [MeshCore](https://meshcore.co.uk/) companion
+radio, listens for channel messages, and relays them into IRC channels — one
+mesh channel mapped to one IRC channel. It never sends anything back to the
+mesh; IRC messages are received and ignored.
+
+Built on the [`meshcore`](https://pypi.org/project/meshcore/) Python package
+for the radio side (BLE, serial, or TCP companion connection). The IRC side is
+a small hand-rolled asyncio client with first-class
+[IRCv3 SASL](https://ircv3.net/specs/extensions/sasl-3.1) support, a NickServ
+`IDENTIFY` fallback (with a configurable wait before joining channels), and
+support for connecting with a fully unregistered nickname.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"    # from a checkout, until this is published
+```
+
+## Configure
+
+Copy [`config.example.yaml`](config.example.yaml) to `config.yaml` and edit it:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+- `mesh.connection` — how to reach your companion radio: `type: ble` (with
+  `address`), `type: serial` (with `port`/`baudrate`), or `type: tcp` (with
+  `host`/`port`).
+- `irc` — the IRC server and how to authenticate. `irc.auth.mode` is one of:
+  - `sasl` — authenticate with `AUTHENTICATE PLAIN` before registration
+    completes. Requires `irc.auth.sasl.username`/`password`.
+  - `nickserv` — connect without SASL, wait for the welcome (`001`), send
+    `PRIVMSG NickServ :IDENTIFY <password>`, then wait
+    `irc.auth.nickserv.join_wait_seconds` before joining channels (long
+    enough for services to apply your cloak/account before you join gated
+    channels). Requires `irc.auth.nickserv.password`.
+  - `none` — connect with a fully unregistered nickname and join immediately.
+
+  The auth mode is fixed by config — if it fails (e.g. the server doesn't
+  offer SASL, or the password is rejected), the bridge logs the failure and
+  retries the *same* mode on reconnect rather than silently switching
+  methods.
+
+  Secrets support `${ENV_VAR}` interpolation so passwords don't need to sit
+  in the YAML file in plaintext, e.g. `password: "${IRC_SASL_PASSWORD}"`.
+
+- `channels` — the mesh-channel-to-IRC-channel mapping, e.g.:
+
+  ```yaml
+  channels:
+    - mesh_channel: 0
+      irc_channel: "#mesh-general"
+    - mesh_channel: 1
+      irc_channel: "#mesh-emergency"
+  ```
+
+  Several mesh channels may map to the same IRC channel. When they do,
+  each relayed line is prefixed with `[<mesh_channel>] ` so messages from
+  either stay attributable once interleaved there (e.g. `[0] hello`,
+  `[1] hi`); a mesh channel with an IRC channel all to itself is left
+  unprefixed.
+
+### Setting up a channel on the radio itself
+
+This bridge only *reads* channel messages — it never creates, renames, or
+rekeys a channel on the companion radio. To set one up (or check what's
+already configured), use [`meshcorectl`](https://github.com/Faradome/meshcorectl),
+a companion CLI for MeshCore radios:
+
+```bash
+meshcorectl create channel 0 "General"   # create/rename channel 0
+meshcorectl get channels                  # list what's configured on the radio
+```
+
+## Run
+
+```bash
+meshcore-irc-bridge --config config.yaml
+# or
+python -m meshcore_irc_bridge --config config.yaml
+```
+
+`--log-level` (default `INFO`) controls verbosity.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                # 100% line+branch coverage enforced
+ruff check .
+mypy
+```
+
+Tests never touch real hardware or a real IRC network: the mesh side is
+exercised against a hardware-free double of `meshcore.MeshCore`
+(`tests/fakes/meshcore_double.py`), and the IRC client is exercised against a
+real (loopback-only) asyncio TCP server that scripts IRC protocol exchanges
+(`tests/fakes/fake_irc_server.py`).
+
+Real end-to-end verification against an actual radio and IRC network is out
+of scope for the automated test suite — run the bridge against your own
+setup once installed to confirm it end-to-end.
+
+## License
+
+[MIT](LICENSE)

meshcore_irc_bridge-0.1.0/README.md

@@ -0,0 +1,117 @@
+# meshcore-irc-bridge
+
+> **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 one-way bridge: it connects to a [MeshCore](https://meshcore.co.uk/) companion
+radio, listens for channel messages, and relays them into IRC channels — one
+mesh channel mapped to one IRC channel. It never sends anything back to the
+mesh; IRC messages are received and ignored.
+
+Built on the [`meshcore`](https://pypi.org/project/meshcore/) Python package
+for the radio side (BLE, serial, or TCP companion connection). The IRC side is
+a small hand-rolled asyncio client with first-class
+[IRCv3 SASL](https://ircv3.net/specs/extensions/sasl-3.1) support, a NickServ
+`IDENTIFY` fallback (with a configurable wait before joining channels), and
+support for connecting with a fully unregistered nickname.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"    # from a checkout, until this is published
+```
+
+## Configure
+
+Copy [`config.example.yaml`](config.example.yaml) to `config.yaml` and edit it:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+- `mesh.connection` — how to reach your companion radio: `type: ble` (with
+  `address`), `type: serial` (with `port`/`baudrate`), or `type: tcp` (with
+  `host`/`port`).
+- `irc` — the IRC server and how to authenticate. `irc.auth.mode` is one of:
+  - `sasl` — authenticate with `AUTHENTICATE PLAIN` before registration
+    completes. Requires `irc.auth.sasl.username`/`password`.
+  - `nickserv` — connect without SASL, wait for the welcome (`001`), send
+    `PRIVMSG NickServ :IDENTIFY <password>`, then wait
+    `irc.auth.nickserv.join_wait_seconds` before joining channels (long
+    enough for services to apply your cloak/account before you join gated
+    channels). Requires `irc.auth.nickserv.password`.
+  - `none` — connect with a fully unregistered nickname and join immediately.
+
+  The auth mode is fixed by config — if it fails (e.g. the server doesn't
+  offer SASL, or the password is rejected), the bridge logs the failure and
+  retries the *same* mode on reconnect rather than silently switching
+  methods.
+
+  Secrets support `${ENV_VAR}` interpolation so passwords don't need to sit
+  in the YAML file in plaintext, e.g. `password: "${IRC_SASL_PASSWORD}"`.
+
+- `channels` — the mesh-channel-to-IRC-channel mapping, e.g.:
+
+  ```yaml
+  channels:
+    - mesh_channel: 0
+      irc_channel: "#mesh-general"
+    - mesh_channel: 1
+      irc_channel: "#mesh-emergency"
+  ```
+
+  Several mesh channels may map to the same IRC channel. When they do,
+  each relayed line is prefixed with `[<mesh_channel>] ` so messages from
+  either stay attributable once interleaved there (e.g. `[0] hello`,
+  `[1] hi`); a mesh channel with an IRC channel all to itself is left
+  unprefixed.
+
+### Setting up a channel on the radio itself
+
+This bridge only *reads* channel messages — it never creates, renames, or
+rekeys a channel on the companion radio. To set one up (or check what's
+already configured), use [`meshcorectl`](https://github.com/Faradome/meshcorectl),
+a companion CLI for MeshCore radios:
+
+```bash
+meshcorectl create channel 0 "General"   # create/rename channel 0
+meshcorectl get channels                  # list what's configured on the radio
+```
+
+## Run
+
+```bash
+meshcore-irc-bridge --config config.yaml
+# or
+python -m meshcore_irc_bridge --config config.yaml
+```
+
+`--log-level` (default `INFO`) controls verbosity.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                # 100% line+branch coverage enforced
+ruff check .
+mypy
+```
+
+Tests never touch real hardware or a real IRC network: the mesh side is
+exercised against a hardware-free double of `meshcore.MeshCore`
+(`tests/fakes/meshcore_double.py`), and the IRC client is exercised against a
+real (loopback-only) asyncio TCP server that scripts IRC protocol exchanges
+(`tests/fakes/fake_irc_server.py`).
+
+Real end-to-end verification against an actual radio and IRC network is out
+of scope for the automated test suite — run the bridge against your own
+setup once installed to confirm it end-to-end.
+
+## License
+
+[MIT](LICENSE)

meshcore_irc_bridge-0.1.0/config.example.yaml

@@ -0,0 +1,91 @@
+# meshcore-irc-bridge configuration.
+#
+# Copy this file to config.yaml and edit it for your setup:
+#   cp config.example.yaml config.yaml
+#
+# Secrets support ${ENV_VAR} interpolation, so passwords don't need to sit
+# in this file in plaintext -- e.g. password: "${IRC_SASL_PASSWORD}".
+
+mesh:
+  connection:
+    # One of: ble | serial | tcp
+    type: ble
+
+    # --- ble ---
+    address: "AA:BB:CC:DD:EE:FF"
+
+    # --- serial (uncomment and remove the ble fields above) ---
+    # type: serial
+    # port: /dev/ttyUSB0
+    # baudrate: 115200
+
+    # --- tcp (uncomment and remove the ble fields above) ---
+    # type: tcp
+    # host: 192.168.1.50
+    # port: 5000
+
+  # Let the meshcore library itself retry a dropped transport before this
+  # bridge gives up and reconnects from scratch.
+  auto_reconnect: true
+  max_reconnect_attempts: 5
+
+irc:
+  server: irc.libera.chat
+  port: 6697
+  tls: true
+  nickname: meshcore-bridge
+  # Defaults to `nickname` if omitted.
+  username: meshcore
+  realname: MeshCore IRC Bridge
+
+  auth:
+    # One of: sasl | nickserv | none
+    #
+    # The mode is fixed here -- if it fails (server doesn't offer SASL, a
+    # password is rejected, ...) the bridge logs the failure and retries
+    # the *same* mode on reconnect, it does not silently fall back to a
+    # different method.
+    mode: sasl
+
+    # --- sasl (AUTHENTICATE PLAIN, before registration completes) ---
+    sasl:
+      username: mynick
+      password: "${IRC_SASL_PASSWORD}"
+
+    # --- nickserv (connect unauthenticated, IDENTIFY, then wait before
+    #     joining channels -- for networks without SASL) ---
+    # auth:
+    #   mode: nickserv
+    #   nickserv:
+    #     password: "${IRC_NICKSERV_PASSWORD}"
+    #     join_wait_seconds: 5   # default 5
+
+    # --- none (fully unregistered nickname, joins immediately) ---
+    # auth:
+    #   mode: none
+
+  reconnect:
+    initial_delay_seconds: 1
+    max_delay_seconds: 60
+
+  # A dead peer (netsplit, a middlebox silently dropping the connection,
+  # the server being killed) can look identical to an idle one from here
+  # -- both send nothing. After this many seconds of silence the bridge
+  # sends its own PING; if nothing at all comes back within
+  # ping_timeout_seconds after that, the link is declared dead and
+  # reconnected. Tune ping_idle_seconds down if your network pings less
+  # often than the default assumes.
+  ping_idle_seconds: 120
+  ping_timeout_seconds: 60
+
+# Mesh channel index -> IRC channel mapping. Each mesh channel maps to
+# exactly one IRC channel; several mesh channels may map to the same IRC
+# channel. To create or rename a channel on the radio itself, use
+# meshcorectl (https://github.com/Faradome/meshcorectl):
+#   meshcorectl create channel 0 "General"
+#   meshcorectl get channels
+channels:
+  - mesh_channel: 0
+    irc_channel: "#mesh-general"
+  - mesh_channel: 1
+    irc_channel: "#mesh-emergency"

meshcore_irc_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "meshcore-irc-bridge"
+version = "0.1.0"
+description = "A one-way bridge relaying MeshCore companion radio channel messages into IRC channels"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "William Canterbury", email = "william.canterbury@gmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Communications :: Ham Radio",
+    "Topic :: Communications :: Chat :: Internet Relay Chat",
+]
+dependencies = [
+    "meshcore>=2.3.9",
+    "bleak>=0.22",
+    "pyserial>=3.5",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "types-PyYAML",
+    "types-pyserial",
+    "build>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Faradome/meshcore-irc-bridge"
+Issues = "https://github.com/Faradome/meshcore-irc-bridge/issues"
+
+[project.scripts]
+meshcore-irc-bridge = "meshcore_irc_bridge.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/meshcore_irc_bridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov=meshcore_irc_bridge --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+source = ["meshcore_irc_bridge"]
+branch = true
+# A 3-line launcher shim, exercised for real by a subprocess smoke test
+# (tests/cli/test_cli.py) -- subprocess coverage isn't worth the
+# `COVERAGE_PROCESS_START` machinery for something this thin.
+omit = ["*/__main__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "meshcore.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "serial.*"
+ignore_missing_imports = true

meshcore_irc_bridge-0.1.0/src/meshcore_irc_bridge/__main__.py

@@ -0,0 +1,4 @@
+from meshcore_irc_bridge.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())