open-packet 0.1.0__tar.gz

open_packet-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,108 @@
+name: Build and Publish Documentation
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # Allow manual trigger for testing
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0  # Fetch full history for git info in Hugo
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "stable"
+
+      - name: Set up Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "latest"
+          extended: true
+
+      - name: Build Hugo site
+        run: |
+          cd docs/hugo
+          hugo --minify --baseURL "https://loredous.github.io/open-packet/"
+
+      - name: Generate PDF
+        run: |
+          sudo apt-get install -y chromium-browser
+          chromium-browser --headless --disable-gpu \
+            --print-to-pdf=docs/hugo/public/open-packet-docs.pdf \
+            --no-margins \
+            "file://$(pwd)/docs/hugo/public/docs/print/index.html" 2>/dev/null || \
+          chromium --headless --disable-gpu \
+            --print-to-pdf=docs/hugo/public/open-packet-docs.pdf \
+            --no-margins \
+            "file://$(pwd)/docs/hugo/public/docs/print/index.html" 2>/dev/null || true
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/hugo/public
+
+  attach-pdf:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "stable"
+
+      - name: Set up Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "latest"
+          extended: true
+
+      - name: Build Hugo site for PDF
+        run: |
+          cd docs/hugo
+          hugo --minify --baseURL "file://$(pwd)/public/"
+
+      - name: Generate PDF
+        run: |
+          sudo apt-get install -y chromium-browser
+          chromium-browser --headless --disable-gpu \
+            --print-to-pdf=open-packet-docs.pdf \
+            --no-margins \
+            "file://$(pwd)/docs/hugo/public/docs/print/index.html" 2>/dev/null || \
+          chromium --headless --disable-gpu \
+            --print-to-pdf=open-packet-docs.pdf \
+            --no-margins \
+            "file://$(pwd)/docs/hugo/public/docs/print/index.html" 2>/dev/null
+
+      - name: Attach PDF to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: open-packet-docs.pdf
+
+  deploy-pages:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

open_packet-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

open_packet-0.1.0/.github/workflows/test-and-build.yml

@@ -0,0 +1,32 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.11"
+    - name: Install UV
+      run: pip install uv
+    - name: Run Tests
+      run: uv run pytest
+    - name: Build
+      run: uv build
+      

open_packet-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.superpowers/
+.worktrees/
+__pycache__/
+*.pyc
+.python-version

open_packet-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/hugo/themes/lotusdocs"]
+	path = docs/hugo/themes/lotusdocs
+	url = https://github.com/colinwilson/lotusdocs

open_packet-0.1.0/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+uv sync                        # install dependencies
+uv run pytest                  # run full test suite
+uv run pytest tests/test_store # run tests in one directory
+uv run pytest tests/test_store/test_store.py::test_list_outbox_excludes_sent_and_deleted  # run single test
+uv run open-packet             # run the app (requires config.yaml)
+uv run open-packet test.yaml   # run with a specific config file
+uv run textual run --dev open_packet/ui/tui/app.py  # run with Textual live-reload + DOM inspector
+```
+
+`asyncio_mode = "auto"` is set in `pyproject.toml`, so async tests do not need `@pytest.mark.asyncio`.
+
+## Architecture
+
+The codebase is layered: **Transport → Link → AX.25 → Node → Engine → Store / TUI**. Each layer communicates only with its immediate neighbors via well-defined interfaces.
+
+```
+Transport (tcp.py / serial.py)   — raw byte I/O
+  └─ Link / KISSLink (kiss.py)   — KISS framing; implements ConnectionBase
+       └─ AX25Connection          — AX.25 v2.2 state machine; implements ConnectionBase
+            └─ BPQNode            — BBS protocol (L/R/S/K commands); implements NodeBase
+                 └─ Engine        — command/event loop running in a daemon thread
+                      ├─ Store    — SQLite message persistence
+                      └─ TUI      — Textual app, polls Engine event queue every 100ms
+```
+
+### Engine (`engine/`)
+
+`Engine` runs in a background thread. The TUI sends it `Command` objects via a `queue.Queue` and reads `Event` objects from a second queue, polled every 100 ms in `OpenPacketApp._poll_events()`. Commands and events are defined in `commands.py` and `events.py`. Adding a new capability means adding a Command, an Event, a `_do_*` handler in `Engine`, and a handler branch in `app._handle_event()`.
+
+### Store (`store/`)
+
+- `models.py` — plain dataclasses: `Operator`, `Node`, `Message`, `Bulletin`
+- `database.py` — raw SQLite DDL, schema migrations, and low-level insert/query helpers
+- `store.py` — higher-level query methods used by the engine and TUI (`list_messages`, `list_outbox`, `count_folder_stats`, etc.)
+
+Schema migrations use `ALTER TABLE ... ADD COLUMN` in `Database.initialize()` with `except sqlite3.OperationalError: pass`. Always use `self._conn.execute()` for migrations — never `executescript()` (which issues an implicit COMMIT).
+
+**Message state matrix:**
+| Type | `queued` | `sent` |
+|------|----------|--------|
+| Received from BBS | 0 | 0 |
+| Composed, awaiting send | 1 | 0 |
+| Composed, transmitted | 1 | 1 |
+
+**Bulletin body sentinel:** `Bulletin.body` is `Optional[str]` — `None` means header-only (not yet retrieved). Because the SQLite `body` column has `NOT NULL`, header-only rows are stored as `"\x00"` (NUL byte); `_row_to_bulletin` maps `"\x00"` back to `None`. Do not change this to `""` — empty string is a valid retrieved body. `wants_retrieval: bool` records user intent to fetch the body on the next sync.
+
+The TUI calls `self._store` directly for lightweight operations that don't need connectivity (e.g. `mark_message_read`, `mark_bulletin_wants_retrieval`). Only operations that require a BBS connection go through the engine command queue.
+
+### TUI (`ui/tui/`)
+
+- `app.py` (`OpenPacketApp`) — top-level Textual `App`; owns the engine, store, and active operator; handles all cross-widget coordination
+- `screens/main.py` — primary layout; key bindings defined here in `BINDINGS`
+- `widgets/folder_tree.py` — uses `node.data` (not `str(node.label)`) for folder routing so count suffixes don't break selection
+- `widgets/console_panel.py` — receives `ConsoleEvent` objects from the engine via `log_frame(direction, text)`
+
+Operator identity and node configuration are stored in SQLite and managed via TUI screens, not the config file. The config file (`~/.config/open-packet/config.yaml`) covers connection and storage settings only.
+
+### AX.25 / Node (`ax25/`, `node/`)
+
+`AX25Connection` implements the AX.25 v2.2 data-link state machine (SABM/UA/DISC/I-frames, T1/T3 timers, Go-Back-N windowing). `BPQNode` sits on top and speaks the BPQ32 BBS text protocol. `connect_node()` sends `BBS\r`, waits for a prompt ending in `>`, and handles name prompts by replying with the operator callsign.
+
+## Documentation
+
+The user-facing documentation lives in `docs/hugo/` as a [Hugo](https://gohugo.io/) static site using the [Lotus Docs](https://github.com/colinwilson/lotusdocs) theme (included as a Git submodule at `docs/hugo/themes/lotusdocs`). Hugo module dependencies (Bootstrap SCSS) are declared in `docs/hugo/go.mod`.
+
+Content lives under `docs/hugo/content/docs/` organised into three sections: `user-guide/`, `reference/`, and `development/`. A print/PDF view of the full documentation is available at `/docs/print/`.
+
+**When to update docs:** Update the relevant page in `docs/hugo/content/docs/` whenever you:
+- Add or change a user-visible feature → update `user-guide/`
+- Add, remove, or change a keyboard shortcut → update `reference/keyboard-shortcuts.md`
+- Change the config file format → update `reference/configuration.md`
+- Change the architecture (new commands, events, layers) → update `development/architecture.md`
+
+**To preview docs locally:**
+```bash
+cd docs/hugo
+git submodule update --init --recursive
+hugo server        # then open http://localhost:1313
+```
+
+The documentation is built and published to GitHub Pages automatically when a release is published. A combined PDF is also generated and attached to the release. See `.github/workflows/docs.yml`.

open_packet-0.1.0/LICENSE

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

open_packet-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: open-packet
+Version: 0.1.0
+Summary: Amateur radio packet messaging client
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual-serve>=1.1.3
+Requires-Dist: textual>=0.60.0
+Description-Content-Type: text/markdown
+
+# open-packet
+
+An open-source packet messaging client for amateur radio operators.
+
+> **Early development:** v0.1 — expect breaking changes between releases.
+
+![Screenshot of the open-packet terminal UI showing the message inbox](images/image.png)
+
+---
+
+## Quickstart
+
+**Requirements:**
+- Linux (Windows and MacOS are currently untested, but should probably work)
+- Python >= 3.11
+- A KISS-capable TNC connected via TCP or serial port. If you don't have hardware, [Direwolf](https://github.com/wb2osz/direwolf) is a good software TNC.
+
+**Install:**
+
+```bash
+uv tool install git+https://github.com/loredous/open-packet
+```
+
+**Configure:**
+
+Create `~/.config/open-packet/config.yaml`:
+
+```yaml
+connection:
+  type: kiss_tcp          # kiss_tcp | kiss_serial
+  host: localhost         # TCP only
+  port: 8001              # TCP only
+```
+
+**Run:**
+
+```bash
+open-packet
+```
+
+On first launch, you'll be prompted to enter your callsign and BBS node details. You can update these later via the Settings screen (`s`).
+
+---
+
+## How It Works
+
+open-packet connects to a BBS node over AX.25 packet radio via a KISS TNC, syncing your personal messages and bulletins to a local SQLite database. The core engine is interface-agnostic — the terminal client is the first frontend, with a web client and other interfaces planned.
+
+---
+
+## Configuration
+
+The config file lives at `~/.config/open-packet/config.yaml` (or pass a custom path as the first argument to `open-packet`).
+
+```yaml
+connection:
+  type: kiss_tcp          # kiss_tcp | kiss_serial
+  host: localhost         # TCP only
+  port: 8001              # TCP only
+  # device: /dev/ttyUSB0  # serial only
+  # baud: 9600            # serial only
+
+store:
+  db_path: ~/.local/share/open-packet/messages.db    # SQLite message database
+  export_path: ~/.local/share/open-packet/export     # flat-file export directory
+
+ui:
+  console_visible: false       # show AX.25 frame console on startup
+  console_buffer: 500          # number of lines to keep in the console ring buffer
+  # console_log: ~/.local/share/open-packet/console.log  # log frame traffic to file (omit to disable)
+```
+
+Operator identity (callsign, SSID) and BBS node configuration are managed interactively through the TUI rather than in the config file. Access them via the Settings screen (`s`).
+
+---
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone https://github.com/loredous/open-packet.git
+cd open-packet
+uv sync
+
+# Run the app
+uv run open-packet
+
+# Run tests
+uv run pytest
+
+# Run with Textual's dev tools (live reload + DOM inspector)
+# Note: this launches OpenPacketApp directly, bypassing main() — config loads from the default path
+uv run textual run --dev open_packet/ui/tui/app.py
+```
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+- Fork the repo and create a feature branch
+- Write tests for new functionality
+- Run `uv run pytest` before opening a pull request
+- Open a pull request with a clear description of the change
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

open_packet-0.1.0/README.md

@@ -0,0 +1,111 @@
+# open-packet
+
+An open-source packet messaging client for amateur radio operators.
+
+> **Early development:** v0.1 — expect breaking changes between releases.
+
+![Screenshot of the open-packet terminal UI showing the message inbox](images/image.png)
+
+---
+
+## Quickstart
+
+**Requirements:**
+- Linux (Windows and MacOS are currently untested, but should probably work)
+- Python >= 3.11
+- A KISS-capable TNC connected via TCP or serial port. If you don't have hardware, [Direwolf](https://github.com/wb2osz/direwolf) is a good software TNC.
+
+**Install:**
+
+```bash
+uv tool install git+https://github.com/loredous/open-packet
+```
+
+**Configure:**
+
+Create `~/.config/open-packet/config.yaml`:
+
+```yaml
+connection:
+  type: kiss_tcp          # kiss_tcp | kiss_serial
+  host: localhost         # TCP only
+  port: 8001              # TCP only
+```
+
+**Run:**
+
+```bash
+open-packet
+```
+
+On first launch, you'll be prompted to enter your callsign and BBS node details. You can update these later via the Settings screen (`s`).
+
+---
+
+## How It Works
+
+open-packet connects to a BBS node over AX.25 packet radio via a KISS TNC, syncing your personal messages and bulletins to a local SQLite database. The core engine is interface-agnostic — the terminal client is the first frontend, with a web client and other interfaces planned.
+
+---
+
+## Configuration
+
+The config file lives at `~/.config/open-packet/config.yaml` (or pass a custom path as the first argument to `open-packet`).
+
+```yaml
+connection:
+  type: kiss_tcp          # kiss_tcp | kiss_serial
+  host: localhost         # TCP only
+  port: 8001              # TCP only
+  # device: /dev/ttyUSB0  # serial only
+  # baud: 9600            # serial only
+
+store:
+  db_path: ~/.local/share/open-packet/messages.db    # SQLite message database
+  export_path: ~/.local/share/open-packet/export     # flat-file export directory
+
+ui:
+  console_visible: false       # show AX.25 frame console on startup
+  console_buffer: 500          # number of lines to keep in the console ring buffer
+  # console_log: ~/.local/share/open-packet/console.log  # log frame traffic to file (omit to disable)
+```
+
+Operator identity (callsign, SSID) and BBS node configuration are managed interactively through the TUI rather than in the config file. Access them via the Settings screen (`s`).
+
+---
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone https://github.com/loredous/open-packet.git
+cd open-packet
+uv sync
+
+# Run the app
+uv run open-packet
+
+# Run tests
+uv run pytest
+
+# Run with Textual's dev tools (live reload + DOM inspector)
+# Note: this launches OpenPacketApp directly, bypassing main() — config loads from the default path
+uv run textual run --dev open_packet/ui/tui/app.py
+```
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+- Fork the repo and create a feature branch
+- Write tests for new functionality
+- Run `uv run pytest` before opening a pull request
+- Open a pull request with a clear description of the change
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

open_packet-0.1.0/docs/hugo/.gitignore

@@ -0,0 +1,3 @@
+public/
+resources/
+.hugo_build.lock

open_packet-0.1.0/docs/hugo/content/_index.md

@@ -0,0 +1,34 @@
+---
+title: "open-packet Documentation"
+description: "Open-source amateur radio packet messaging client for Linux"
+---
+
+# open-packet
+
+**open-packet** is an open-source amateur radio packet messaging client for Linux. It connects to a BBS node over AX.25 packet radio via a KISS TNC, syncing your personal messages and bulletins to a local SQLite database and presenting them through a terminal user interface (TUI).
+
+> **Early development:** v0.1 — expect breaking changes between releases.
+
+## Features
+
+- **Messages** — read, compose, reply, archive, and delete personal packet messages
+- **Bulletins** — browse bulletin categories and retrieve full bulletin bodies on demand
+- **BBS Files** — list and download files from BBS file directories
+- **ICS Forms** — compose and send structured ICS/standard forms messages
+- **Terminal Connect** — open a raw terminal session to any AX.25 node
+- **Multiple Operators & Nodes** — manage multiple callsigns and BBS nodes in a single installation
+- **Offline-first** — all messages are stored locally in SQLite; connectivity is only needed to sync
+
+## Quick Navigation
+
+### [Getting Started]({{< relref "/docs/user-guide/getting-started" >}})
+New to open-packet? Start here with installation and first-launch setup.
+
+### [User Guide]({{< relref "/docs/user-guide" >}})
+Learn how to use messages, bulletins, BBS files, forms, and the terminal.
+
+### [Reference]({{< relref "/docs/reference" >}})
+Configuration file reference and keyboard shortcuts.
+
+### [Development]({{< relref "/docs/development" >}})
+Architecture overview and contribution guide.

open_packet-0.1.0/docs/hugo/content/docs/_index.md

@@ -0,0 +1,14 @@
+---
+title: "Documentation"
+description: "open-packet documentation home"
+icon: "menu_book"
+weight: 1
+---
+
+Welcome to the open-packet documentation. Use the sidebar to navigate between sections.
+
+| Section | Description |
+|---------|-------------|
+| [User Guide]({{< relref "user-guide" >}}) | Install, configure, and use open-packet day-to-day |
+| [Reference]({{< relref "reference" >}}) | Keyboard shortcuts and configuration reference |
+| [Development]({{< relref "development" >}}) | Architecture guide and contribution information |

open_packet-0.1.0/docs/hugo/content/docs/development/_index.md

@@ -0,0 +1,11 @@
+---
+title: "Development"
+description: "Architecture and contribution guide for open-packet"
+icon: "code"
+weight: 3
+---
+
+| Topic | Description |
+|-------|-------------|
+| [Architecture]({{< relref "architecture" >}}) | Codebase layers and design principles |
+| [Contributing]({{< relref "contributing" >}}) | How to contribute to open-packet |