jcomprns 0.1.0__tar.gz

jcomprns-0.1.0/LICENSE

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

jcomprns-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: jcomprns
+Version: 0.1.0
+Summary: Pair an RNode over Bluetooth LE and run LXMF messaging, file transfer, and git over Reticulum (RNS).
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rns>=1.3.5
+Requires-Dist: lxmf
+Requires-Dist: bleak
+Requires-Dist: pyserial
+Dynamic: license-file
+
+# jcomprns
+
+Pair an [RNode](https://unsigned.io/rnode/) to this machine over Bluetooth LE and use it for LXMF messaging, file transfer, and `git clone`-able repositories — all over [Reticulum (RNS)](https://reticulum.network/).
+
+Installs as a normal pip package with real terminal commands, the same way `rns` gives you `rnsd`/`rnodeconf`:
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+That installs five commands onto your `PATH`: `jcomprns-pair`, `jcomprns-chat`, `jcomprns-send`, `jcomprns-git`, and `git-remote-jcomprns` (used automatically by `git`, you never run it directly).
+
+All of this app's state — identity, remembered pairing, presence directories, received files, saved config profiles — lives in `~/.jcomprns/`, independent of wherever pip happens to install the package (same idea as RNS's own `~/.reticulum`).
+
+## Why this exists
+
+RNode's BLE firmware requires a bonded (secure) connection before any data can flow, and the OS only lets you create that bond through its own Bluetooth pairing UI — no app, including this one, can drive that dialog programmatically. `jcomprns-pair` automates everything *around* that manual step:
+
+1. Talks to the RNode over USB serial (the same KISS commands `rnodeconf` uses) to switch on Bluetooth and put the device into pairing mode.
+2. Reads back the pairing PIN the firmware generates and opens your OS's Bluetooth settings for you.
+3. Once you've completed the bond, detects the RNode's Bluetooth address and adds a `[[RNode BLE Interface]]` block to your Reticulum config (`port = ble://<address>`).
+4. Creates a Reticulum identity (or reuses one you already have).
+5. Launches `rnsd` in the foreground.
+
+RNS handles the actual data link over BLE itself from there (via `bleak`) — this project only exists to get the one-time OS-level pairing and config wiring out of the way, plus the messaging/file-transfer/git tools built on top.
+
+Once a device has been paired, its address is remembered in `~/.jcomprns/rnode_state.json`, so every run after the first skips straight to updating the config and launching `rnsd` — no re-pairing needed.
+
+## Verbose / debug output
+
+By default, things that are handled silently on purpose — a best-effort OS notification failing, a corrupt state file falling back to a default, garbage announce data from the network being ignored — stay silent, so normal runs stay clean. Pass `-v`/`--verbose` to any command to see that detail instead:
+
+```
+jcomprns-pair --verbose
+jcomprns-chat --verbose
+jcomprns-send --verbose
+jcomprns-git serve --verbose
+```
+
+This also bumps RNS's own internal logging to debug level for that run. It never changes behavior — only whether these diagnostics get printed (to stderr).
+
+For `git-remote-jcomprns`, which git invokes directly with no room for extra flags, set the `JCOMPRNS_VERBOSE=1` environment variable instead.
+
+## Platform support
+
+The core pairing flow (talking to the RNode over USB/KISS, RNS config, identity, `rnsd`) is fully cross-platform — it's all `pyserial`/RNS, which already work identically on macOS, Windows, and Linux. Two pieces are inherently OS-specific and are implemented per-platform:
+
+| | macOS | Windows | Linux |
+|---|---|---|---|
+| Open Bluetooth settings | `open x-apple.systempreferences:...` | `ms-settings:bluetooth` | first available of `gnome-control-center`, `blueman-manager`, `kcmshell5` |
+| Detect the bonded RNode's address | `system_profiler SPBluetoothDataType` | PowerShell `Get-PnpDevice -Class Bluetooth` | `bluetoothctl devices Paired` (BlueZ) |
+
+**macOS is the primary tested platform** (this project was built and verified there). The Windows and Linux paths are implemented against each OS's standard, documented tooling and covered by unit tests with fabricated realistic output, but haven't been run on real Windows/Linux hardware. If auto-detection fails on your platform, the script tells you what to run manually (or pass `--address` to skip detection entirely once you know the address).
+
+Native OS notifications (used by `jcomprns-chat` and `jcomprns-send`) work the same way: `osascript` on macOS, a PowerShell WinRT toast on Windows (no extra modules needed), `notify-send` on Linux (part of `libnotify`, present on most desktop distros). If the relevant tool isn't available, notifications are silently skipped — nothing else in the app depends on them.
+
+## Pairing an RNode
+
+Connect the RNode over USB, then:
+
+```
+jcomprns-pair
+```
+
+First run: walks you through USB → BLE pairing, then writes the config, creates an identity, and launches `rnsd`.
+
+Later runs: automatically reuses the saved address, updates config/identity if needed, and launches `rnsd` — no USB connection required.
+
+Useful flags:
+
+| Flag | Purpose |
+|---|---|
+| `--repair` | Ignore the saved address and pair a (different) device again |
+| `--address <mac>` | Use a specific BLE address directly, skipping pairing/detection |
+| `--no-run` | Update config + identity but don't launch `rnsd` |
+| `--config <dir>` | Reticulum config directory; skips the startup config prompt if given |
+| `--identity <path>` | Identity file to create/reuse (default `~/.jcomprns/identity`) |
+| `--state-file <path>` | Where the paired address is remembered (default `~/.jcomprns/rnode_state.json`) |
+| `--frequency` / `--bandwidth` / `--txpower` / `--spreadingfactor` / `--codingrate` | LoRa radio parameters written into the interface block |
+
+Run `jcomprns-pair --help` for the full list.
+
+## Files this creates (all under `~/.jcomprns/`)
+
+- `rnode_state.json` — remembers the paired RNode's BLE address between runs
+- `identity` — Reticulum identity file (keep this private; anyone with it can decrypt traffic for it), shared by all four tools so your address stays consistent
+- `contacts.json` — the presence directory of LXMF peers seen announcing on the network (created by `jcomprns-chat`)
+- `filetransfer_contacts.json` — the presence directory of file-transfer peers seen announcing on the network (created by `jcomprns-send`)
+- `received_files/` and `received_files.json` — incoming files and the manifest of what was received, when, and from where (created by `jcomprns-send`)
+- `configs/<name>/` — saved Reticulum config profiles (see "Config profiles" below)
+- `~/.reticulum/config` — gets a `[[RNode BLE Interface]]` block appended (existing interfaces are left untouched); a timestamped backup is made before every edit
+
+## Messaging (LXMF)
+
+`jcomprns-chat` is a small interactive [LXMF](https://github.com/markqvist/LXMF) messaging client that runs over the same Reticulum setup. It reuses the identity created by `jcomprns-pair`, so your LXMF address stays the same across every tool here.
+
+```
+jcomprns-chat
+```
+
+It brings up Reticulum itself (attaching to `rnsd` if it's already running as the shared instance, or opening the configured interfaces directly if not), then drops into a single-keypress UI:
+
+- **M** — compose a message: paste a recipient's LXMF address (hex), optionally a title, and the message body
+- **I** — open the inbox: lists received messages and lets you pick one to reply to
+- **P** — open the presence directory: lists every LXMF peer seen announcing on the network, and lets you pick one to message directly
+- **Q** — quit
+
+Incoming messages trigger a terminal alert (with a bell) and a native OS notification. Your own LXMF address is printed on startup — that's what you give other people so they can message you.
+
+Flags: `--config`, `--identity` (same meaning as in `jcomprns-pair`), `--display-name` (shown to peers when you announce), `--stamp-cost` (proof-of-work senders must pay you before delivery; default `0`), `--contacts <path>` (where the presence directory is saved; default `~/.jcomprns/contacts.json`), `--announce-interval <minutes>` (periodically re-announce yourself so others can discover you; default `0` = announce once at startup only).
+
+### Presence directory
+
+Reticulum destinations are namespaced by an app name plus aspects (e.g. LXMF uses `lxmf.delivery`), and any node in the network can listen for announces under a given namespace without already knowing who's out there. `jcomprns-chat` registers a listener for `lxmf.delivery` announces network-wide, so it builds up a contact list of every LXMF peer it's seen — not just people who've messaged you first.
+
+Each contact records their address, display name (if they set one), and first/last seen times, persisted to `contacts.json`. New contacts trigger the same terminal alert as an incoming message. From the **P** screen you can jump straight into composing a message to any saved contact, or trigger `[A]` to re-announce yourself so others can discover you back.
+
+This is mutual: for two peers to find each other, both need to have announced at some point since either was last online. Use `--announce-interval` if you want that to happen automatically instead of only at startup.
+
+## File transfer
+
+`jcomprns-send` is the same idea as the messenger, but for sending files instead of text. It runs over the same Reticulum setup and can share the same identity, but registers its own destination under a different namespace (`jcomprns.filetransfer` vs LXMF's `lxmf.delivery`) — so it has its own address, its own presence directory, and its own contacts, even though it's the same identity underneath.
+
+```
+jcomprns-send
+```
+
+- **S** — send a file: paste a recipient's address (hex) and a local file path
+- **R** — list received files: shows what's been received, when, from whom, and where it was saved on disk (under `~/.jcomprns/received_files/`)
+- **P** — presence directory: same mechanism as the messenger's, scoped to file-transfer peers; pick one to send a file directly, or press `[A]` to re-announce yourself
+- **Q** — quit
+
+Under the hood this uses `RNS.Link` + `RNS.Resource`, which is Reticulum's built-in mechanism for moving arbitrary data with automatic compression, chunking, and integrity checking — a link is established with the recipient first, then the file streams over it with a live progress percentage. Per RNS's own guidance, Resources aren't recommended for very large files (compression/hashing can outrun the receiver's timeout on slow links); this is intended for the kind of file sizes that make sense over a LoRa-connected RNode, not bulk transfer.
+
+Flags: `--config`, `--identity`, `--display-name`, `--announce-interval` (same meaning as in `jcomprns-chat`), `--received-dir` (where incoming files are saved; default `~/.jcomprns/received_files`), `--manifest <path>` (where the received-files log is kept; default `~/.jcomprns/received_files.json`), `--contacts <path>` (default `~/.jcomprns/filetransfer_contacts.json`).
+
+## Git over Reticulum
+
+`jcomprns-git` lets you `git clone`/`fetch`/`push` a repository over Reticulum, using completely normal git commands — no different from an `ssh://` remote from git's point of view.
+
+This works the same way `ssh` does for git: git already knows how to speak its own wire protocol over an arbitrary bidirectional byte stream (that's literally what happens over ssh — `ssh host git-upload-pack '/repo'` pipes git's pack protocol over the ssh channel). This module provides that same stream over an RNS `Link` using `RNS.Buffer.create_bidirectional_buffer()`, and spawns the real `git-upload-pack`/`git-receive-pack` binaries on the serving side. Git itself needs no changes; the `git-remote-jcomprns` command (installed automatically alongside everything else) is what makes `git` recognize the `jcomprns://` URL scheme.
+
+### Serving repositories
+
+```
+jcomprns-git serve --repos-dir /path/to/repos
+```
+
+`--repos-dir` should contain one or more bare repositories (e.g. `myrepo.git`, created with `git init --bare`). The command prints your address and the exact URL to give clients:
+
+```
+Your jcomprns git address: <hex-address>
+Share this with clients as: git clone jcomprns://<hex-address>/<reponame>
+```
+
+Press Enter to announce again, Ctrl+C to quit. Flags: `--config`, `--identity` (same meaning as elsewhere), `--announce-interval <minutes>`.
+
+### Cloning / fetching / pushing
+
+No setup needed beyond installing this package — `pip install -e .` already put `git-remote-jcomprns` on your `PATH`, and git finds it automatically for any `jcomprns://` remote:
+
+```
+git clone jcomprns://<hex-address>/<reponame>
+git remote add origin jcomprns://<hex-address>/<reponame>   # for an existing repo
+git fetch
+git push
+```
+
+By default the client uses your live `~/.reticulum` config and the shared `~/.jcomprns/identity` file — since git invokes the helper directly with its own stdin/stdout already committed to the wire protocol, there's no interactive config-picker prompt here (unlike the other commands). Override with the `JCOMPRNS_CONFIG` and `JCOMPRNS_IDENTITY` environment variables if you need a specific config profile or identity. Having `rnsd` already running in the background (via `jcomprns-pair`) is recommended if you'll be doing git operations repeatedly, so each one doesn't have to bring up interfaces from scratch.
+
+### Security notes
+
+The server only serves directories that already exist directly under `--repos-dir`; requests for repo names containing `..` or resolving outside that directory are rejected. There's no authentication beyond Reticulum's own identity/encryption — anyone with the server's address can attempt `upload-pack` (read) and `receive-pack` (push) against any repo you're serving. Don't serve anything you wouldn't hand out to anyone who obtains the address.
+
+## Config profiles (`~/.jcomprns/configs/`)
+
+`jcomprns-pair`, `jcomprns-chat`, `jcomprns-send`, and `jcomprns-git serve` all prompt at startup (the `git-remote-jcomprns` client helper does not — see above):
+
+```
+Which Reticulum config do you want to use?
+  [0] Your live config (~/.reticulum)
+  [1] default  (/Users/you/.jcomprns/configs/default)
+Choice [0]:
+```
+
+- **[0]** (or just pressing Enter) uses your live `~/.reticulum` config, same as before.
+- Any other number uses that saved profile directory under `~/.jcomprns/configs/` as the Reticulum config directory for this run (its own `config` file, and its own `storage/`/identity cache, isolated from your live setup).
+
+Pass `--config <dir>` on the command line to skip the prompt entirely and use that directory directly (scripting/automation).
+
+To save a new profile, copy a working `config` file into `~/.jcomprns/configs/<name>/config` — it'll show up in the list automatically.
+
+## Publishing (if you want this on PyPI)
+
+This is currently installed via `pip install -e .` (editable, from a local checkout). The package name `jcomprns` is available on PyPI (unclaimed as of this writing) and the build has been validated locally (`python3 -m build` produces a correct wheel — right license metadata, right entry points). Publishing itself is a deliberate step for you to take, not something done as part of this setup.
+
+1. Create a PyPI account at [pypi.org](https://pypi.org/account/register/) if you don't have one, and a [TestPyPI](https://test.pypi.org/account/register/) account too (separate signup, useful for a dry run first).
+2. Generate an API token (PyPI account settings → API tokens) rather than using your password directly with `twine`.
+3. Bump `version` in `pyproject.toml` (start at `0.1.0`, already set).
+4. Build and do a dry run against TestPyPI first:
+   ```
+   python3 -m pip install build twine
+   python3 -m build
+   python3 -m twine upload --repository testpypi dist/*
+   ```
+   When prompted, use `__token__` as the username and your TestPyPI API token as the password. Then sanity-check the install from there: `pip install --index-url https://test.pypi.org/simple/ jcomprns`.
+5. Once that looks right, upload to the real index:
+   ```
+   python3 -m twine upload dist/*
+   ```
+   Same `__token__` / API token pattern, using your real PyPI token this time.
+
+After that, anyone can `pip install jcomprns` directly — no repo checkout needed.

jcomprns-0.1.0/README.md

@@ -0,0 +1,215 @@
+# jcomprns
+
+Pair an [RNode](https://unsigned.io/rnode/) to this machine over Bluetooth LE and use it for LXMF messaging, file transfer, and `git clone`-able repositories — all over [Reticulum (RNS)](https://reticulum.network/).
+
+Installs as a normal pip package with real terminal commands, the same way `rns` gives you `rnsd`/`rnodeconf`:
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+That installs five commands onto your `PATH`: `jcomprns-pair`, `jcomprns-chat`, `jcomprns-send`, `jcomprns-git`, and `git-remote-jcomprns` (used automatically by `git`, you never run it directly).
+
+All of this app's state — identity, remembered pairing, presence directories, received files, saved config profiles — lives in `~/.jcomprns/`, independent of wherever pip happens to install the package (same idea as RNS's own `~/.reticulum`).
+
+## Why this exists
+
+RNode's BLE firmware requires a bonded (secure) connection before any data can flow, and the OS only lets you create that bond through its own Bluetooth pairing UI — no app, including this one, can drive that dialog programmatically. `jcomprns-pair` automates everything *around* that manual step:
+
+1. Talks to the RNode over USB serial (the same KISS commands `rnodeconf` uses) to switch on Bluetooth and put the device into pairing mode.
+2. Reads back the pairing PIN the firmware generates and opens your OS's Bluetooth settings for you.
+3. Once you've completed the bond, detects the RNode's Bluetooth address and adds a `[[RNode BLE Interface]]` block to your Reticulum config (`port = ble://<address>`).
+4. Creates a Reticulum identity (or reuses one you already have).
+5. Launches `rnsd` in the foreground.
+
+RNS handles the actual data link over BLE itself from there (via `bleak`) — this project only exists to get the one-time OS-level pairing and config wiring out of the way, plus the messaging/file-transfer/git tools built on top.
+
+Once a device has been paired, its address is remembered in `~/.jcomprns/rnode_state.json`, so every run after the first skips straight to updating the config and launching `rnsd` — no re-pairing needed.
+
+## Verbose / debug output
+
+By default, things that are handled silently on purpose — a best-effort OS notification failing, a corrupt state file falling back to a default, garbage announce data from the network being ignored — stay silent, so normal runs stay clean. Pass `-v`/`--verbose` to any command to see that detail instead:
+
+```
+jcomprns-pair --verbose
+jcomprns-chat --verbose
+jcomprns-send --verbose
+jcomprns-git serve --verbose
+```
+
+This also bumps RNS's own internal logging to debug level for that run. It never changes behavior — only whether these diagnostics get printed (to stderr).
+
+For `git-remote-jcomprns`, which git invokes directly with no room for extra flags, set the `JCOMPRNS_VERBOSE=1` environment variable instead.
+
+## Platform support
+
+The core pairing flow (talking to the RNode over USB/KISS, RNS config, identity, `rnsd`) is fully cross-platform — it's all `pyserial`/RNS, which already work identically on macOS, Windows, and Linux. Two pieces are inherently OS-specific and are implemented per-platform:
+
+| | macOS | Windows | Linux |
+|---|---|---|---|
+| Open Bluetooth settings | `open x-apple.systempreferences:...` | `ms-settings:bluetooth` | first available of `gnome-control-center`, `blueman-manager`, `kcmshell5` |
+| Detect the bonded RNode's address | `system_profiler SPBluetoothDataType` | PowerShell `Get-PnpDevice -Class Bluetooth` | `bluetoothctl devices Paired` (BlueZ) |
+
+**macOS is the primary tested platform** (this project was built and verified there). The Windows and Linux paths are implemented against each OS's standard, documented tooling and covered by unit tests with fabricated realistic output, but haven't been run on real Windows/Linux hardware. If auto-detection fails on your platform, the script tells you what to run manually (or pass `--address` to skip detection entirely once you know the address).
+
+Native OS notifications (used by `jcomprns-chat` and `jcomprns-send`) work the same way: `osascript` on macOS, a PowerShell WinRT toast on Windows (no extra modules needed), `notify-send` on Linux (part of `libnotify`, present on most desktop distros). If the relevant tool isn't available, notifications are silently skipped — nothing else in the app depends on them.
+
+## Pairing an RNode
+
+Connect the RNode over USB, then:
+
+```
+jcomprns-pair
+```
+
+First run: walks you through USB → BLE pairing, then writes the config, creates an identity, and launches `rnsd`.
+
+Later runs: automatically reuses the saved address, updates config/identity if needed, and launches `rnsd` — no USB connection required.
+
+Useful flags:
+
+| Flag | Purpose |
+|---|---|
+| `--repair` | Ignore the saved address and pair a (different) device again |
+| `--address <mac>` | Use a specific BLE address directly, skipping pairing/detection |
+| `--no-run` | Update config + identity but don't launch `rnsd` |
+| `--config <dir>` | Reticulum config directory; skips the startup config prompt if given |
+| `--identity <path>` | Identity file to create/reuse (default `~/.jcomprns/identity`) |
+| `--state-file <path>` | Where the paired address is remembered (default `~/.jcomprns/rnode_state.json`) |
+| `--frequency` / `--bandwidth` / `--txpower` / `--spreadingfactor` / `--codingrate` | LoRa radio parameters written into the interface block |
+
+Run `jcomprns-pair --help` for the full list.
+
+## Files this creates (all under `~/.jcomprns/`)
+
+- `rnode_state.json` — remembers the paired RNode's BLE address between runs
+- `identity` — Reticulum identity file (keep this private; anyone with it can decrypt traffic for it), shared by all four tools so your address stays consistent
+- `contacts.json` — the presence directory of LXMF peers seen announcing on the network (created by `jcomprns-chat`)
+- `filetransfer_contacts.json` — the presence directory of file-transfer peers seen announcing on the network (created by `jcomprns-send`)
+- `received_files/` and `received_files.json` — incoming files and the manifest of what was received, when, and from where (created by `jcomprns-send`)
+- `configs/<name>/` — saved Reticulum config profiles (see "Config profiles" below)
+- `~/.reticulum/config` — gets a `[[RNode BLE Interface]]` block appended (existing interfaces are left untouched); a timestamped backup is made before every edit
+
+## Messaging (LXMF)
+
+`jcomprns-chat` is a small interactive [LXMF](https://github.com/markqvist/LXMF) messaging client that runs over the same Reticulum setup. It reuses the identity created by `jcomprns-pair`, so your LXMF address stays the same across every tool here.
+
+```
+jcomprns-chat
+```
+
+It brings up Reticulum itself (attaching to `rnsd` if it's already running as the shared instance, or opening the configured interfaces directly if not), then drops into a single-keypress UI:
+
+- **M** — compose a message: paste a recipient's LXMF address (hex), optionally a title, and the message body
+- **I** — open the inbox: lists received messages and lets you pick one to reply to
+- **P** — open the presence directory: lists every LXMF peer seen announcing on the network, and lets you pick one to message directly
+- **Q** — quit
+
+Incoming messages trigger a terminal alert (with a bell) and a native OS notification. Your own LXMF address is printed on startup — that's what you give other people so they can message you.
+
+Flags: `--config`, `--identity` (same meaning as in `jcomprns-pair`), `--display-name` (shown to peers when you announce), `--stamp-cost` (proof-of-work senders must pay you before delivery; default `0`), `--contacts <path>` (where the presence directory is saved; default `~/.jcomprns/contacts.json`), `--announce-interval <minutes>` (periodically re-announce yourself so others can discover you; default `0` = announce once at startup only).
+
+### Presence directory
+
+Reticulum destinations are namespaced by an app name plus aspects (e.g. LXMF uses `lxmf.delivery`), and any node in the network can listen for announces under a given namespace without already knowing who's out there. `jcomprns-chat` registers a listener for `lxmf.delivery` announces network-wide, so it builds up a contact list of every LXMF peer it's seen — not just people who've messaged you first.
+
+Each contact records their address, display name (if they set one), and first/last seen times, persisted to `contacts.json`. New contacts trigger the same terminal alert as an incoming message. From the **P** screen you can jump straight into composing a message to any saved contact, or trigger `[A]` to re-announce yourself so others can discover you back.
+
+This is mutual: for two peers to find each other, both need to have announced at some point since either was last online. Use `--announce-interval` if you want that to happen automatically instead of only at startup.
+
+## File transfer
+
+`jcomprns-send` is the same idea as the messenger, but for sending files instead of text. It runs over the same Reticulum setup and can share the same identity, but registers its own destination under a different namespace (`jcomprns.filetransfer` vs LXMF's `lxmf.delivery`) — so it has its own address, its own presence directory, and its own contacts, even though it's the same identity underneath.
+
+```
+jcomprns-send
+```
+
+- **S** — send a file: paste a recipient's address (hex) and a local file path
+- **R** — list received files: shows what's been received, when, from whom, and where it was saved on disk (under `~/.jcomprns/received_files/`)
+- **P** — presence directory: same mechanism as the messenger's, scoped to file-transfer peers; pick one to send a file directly, or press `[A]` to re-announce yourself
+- **Q** — quit
+
+Under the hood this uses `RNS.Link` + `RNS.Resource`, which is Reticulum's built-in mechanism for moving arbitrary data with automatic compression, chunking, and integrity checking — a link is established with the recipient first, then the file streams over it with a live progress percentage. Per RNS's own guidance, Resources aren't recommended for very large files (compression/hashing can outrun the receiver's timeout on slow links); this is intended for the kind of file sizes that make sense over a LoRa-connected RNode, not bulk transfer.
+
+Flags: `--config`, `--identity`, `--display-name`, `--announce-interval` (same meaning as in `jcomprns-chat`), `--received-dir` (where incoming files are saved; default `~/.jcomprns/received_files`), `--manifest <path>` (where the received-files log is kept; default `~/.jcomprns/received_files.json`), `--contacts <path>` (default `~/.jcomprns/filetransfer_contacts.json`).
+
+## Git over Reticulum
+
+`jcomprns-git` lets you `git clone`/`fetch`/`push` a repository over Reticulum, using completely normal git commands — no different from an `ssh://` remote from git's point of view.
+
+This works the same way `ssh` does for git: git already knows how to speak its own wire protocol over an arbitrary bidirectional byte stream (that's literally what happens over ssh — `ssh host git-upload-pack '/repo'` pipes git's pack protocol over the ssh channel). This module provides that same stream over an RNS `Link` using `RNS.Buffer.create_bidirectional_buffer()`, and spawns the real `git-upload-pack`/`git-receive-pack` binaries on the serving side. Git itself needs no changes; the `git-remote-jcomprns` command (installed automatically alongside everything else) is what makes `git` recognize the `jcomprns://` URL scheme.
+
+### Serving repositories
+
+```
+jcomprns-git serve --repos-dir /path/to/repos
+```
+
+`--repos-dir` should contain one or more bare repositories (e.g. `myrepo.git`, created with `git init --bare`). The command prints your address and the exact URL to give clients:
+
+```
+Your jcomprns git address: <hex-address>
+Share this with clients as: git clone jcomprns://<hex-address>/<reponame>
+```
+
+Press Enter to announce again, Ctrl+C to quit. Flags: `--config`, `--identity` (same meaning as elsewhere), `--announce-interval <minutes>`.
+
+### Cloning / fetching / pushing
+
+No setup needed beyond installing this package — `pip install -e .` already put `git-remote-jcomprns` on your `PATH`, and git finds it automatically for any `jcomprns://` remote:
+
+```
+git clone jcomprns://<hex-address>/<reponame>
+git remote add origin jcomprns://<hex-address>/<reponame>   # for an existing repo
+git fetch
+git push
+```
+
+By default the client uses your live `~/.reticulum` config and the shared `~/.jcomprns/identity` file — since git invokes the helper directly with its own stdin/stdout already committed to the wire protocol, there's no interactive config-picker prompt here (unlike the other commands). Override with the `JCOMPRNS_CONFIG` and `JCOMPRNS_IDENTITY` environment variables if you need a specific config profile or identity. Having `rnsd` already running in the background (via `jcomprns-pair`) is recommended if you'll be doing git operations repeatedly, so each one doesn't have to bring up interfaces from scratch.
+
+### Security notes
+
+The server only serves directories that already exist directly under `--repos-dir`; requests for repo names containing `..` or resolving outside that directory are rejected. There's no authentication beyond Reticulum's own identity/encryption — anyone with the server's address can attempt `upload-pack` (read) and `receive-pack` (push) against any repo you're serving. Don't serve anything you wouldn't hand out to anyone who obtains the address.
+
+## Config profiles (`~/.jcomprns/configs/`)
+
+`jcomprns-pair`, `jcomprns-chat`, `jcomprns-send`, and `jcomprns-git serve` all prompt at startup (the `git-remote-jcomprns` client helper does not — see above):
+
+```
+Which Reticulum config do you want to use?
+  [0] Your live config (~/.reticulum)
+  [1] default  (/Users/you/.jcomprns/configs/default)
+Choice [0]:
+```
+
+- **[0]** (or just pressing Enter) uses your live `~/.reticulum` config, same as before.
+- Any other number uses that saved profile directory under `~/.jcomprns/configs/` as the Reticulum config directory for this run (its own `config` file, and its own `storage/`/identity cache, isolated from your live setup).
+
+Pass `--config <dir>` on the command line to skip the prompt entirely and use that directory directly (scripting/automation).
+
+To save a new profile, copy a working `config` file into `~/.jcomprns/configs/<name>/config` — it'll show up in the list automatically.
+
+## Publishing (if you want this on PyPI)
+
+This is currently installed via `pip install -e .` (editable, from a local checkout). The package name `jcomprns` is available on PyPI (unclaimed as of this writing) and the build has been validated locally (`python3 -m build` produces a correct wheel — right license metadata, right entry points). Publishing itself is a deliberate step for you to take, not something done as part of this setup.
+
+1. Create a PyPI account at [pypi.org](https://pypi.org/account/register/) if you don't have one, and a [TestPyPI](https://test.pypi.org/account/register/) account too (separate signup, useful for a dry run first).
+2. Generate an API token (PyPI account settings → API tokens) rather than using your password directly with `twine`.
+3. Bump `version` in `pyproject.toml` (start at `0.1.0`, already set).
+4. Build and do a dry run against TestPyPI first:
+   ```
+   python3 -m pip install build twine
+   python3 -m build
+   python3 -m twine upload --repository testpypi dist/*
+   ```
+   When prompted, use `__token__` as the username and your TestPyPI API token as the password. Then sanity-check the install from there: `pip install --index-url https://test.pypi.org/simple/ jcomprns`.
+5. Once that looks right, upload to the real index:
+   ```
+   python3 -m twine upload dist/*
+   ```
+   Same `__token__` / API token pattern, using your real PyPI token this time.
+
+After that, anyone can `pip install jcomprns` directly — no repo checkout needed.

jcomprns-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jcomprns"
+version = "0.1.0"
+description = "Pair an RNode over Bluetooth LE and run LXMF messaging, file transfer, and git over Reticulum (RNS)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Communications",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "rns>=1.3.5",
+    "lxmf",
+    "bleak",
+    "pyserial",
+]
+
+[project.scripts]
+jcomprns-pair = "jcomprns.rnode_pair:main"
+jcomprns-chat = "jcomprns.lxmf_messenger:main"
+jcomprns-send = "jcomprns.file_transfer:main"
+jcomprns-git = "jcomprns.rns_git:main"
+git-remote-jcomprns = "jcomprns.rns_git:remote_helper_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

jcomprns-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jcomprns-0.1.0/src/jcomprns/__init__.py

@@ -0,0 +1,4 @@
+"""jcomprns -- pair an RNode over Bluetooth LE and run LXMF messaging, file
+transfer, and git over Reticulum (RNS)."""
+
+__version__ = "0.1.0"