Kordophone/core/README.md

Kordophone Core (Rust Workspace)

This directory contains the shared Rust code and tools used by Kordophone clients.

Workspace members:

• kordophone/ — Rust client library for the Kordophone HTTP/WebSocket API. Cross‑platform.
• kordophone-db/ — Lightweight cache/database and models built with Diesel (SQLite).
• kordophoned/ — Client daemon providing local caching and IPC
  • Linux: D‑Bus
  • macOS: XPC (see notes below)
• kordophoned-client/ — Cross-platform client library for talking to kordophoned (D-Bus/XPC).
• kpcli/ — Command‑line interface for interacting with the API, DB, and daemon.
• kptui/ — Terminal UI client (Ratatui) for reading and replying to chats via the daemon.
• utilities/ — Small helper tools (e.g., testing utilities).

Build

cd core
cargo build            # build all workspace members
cargo test -p kordophone

Build a specific crate:

cargo build -p kordophone
cargo build -p kordophoned --release

Raspberry Pi Zero (cross build)

Recommended approach is cross (https://github.com/cross-rs/cross), which uses a containerized toolchain.

Prereqs:

• Install Docker or Podman
• Install cross: cargo install cross

Build ARMv6 (Pi Zero / Zero W):

cd core
make pi-zero

Build aarch64 (Pi OS 64-bit / Pi 3+):

cd core
make pi-aarch64

Notes:

• The aarch64 cross build uses a Debian 11 (bullseye) container base image to keep glibc compatible with bullseye.

Artifacts:

• target/cross/arm-unknown-linux-gnueabihf/arm-unknown-linux-gnueabihf/release/kordophoned
• target/cross/arm-unknown-linux-gnueabihf/arm-unknown-linux-gnueabihf/release/kpcli
• target/cross/arm-unknown-linux-gnueabihf/arm-unknown-linux-gnueabihf/release/kptui
• target/cross/aarch64-unknown-linux-gnu/aarch64-unknown-linux-gnu/release/kordophoned
• target/cross/aarch64-unknown-linux-gnu/aarch64-unknown-linux-gnu/release/kpcli
• target/cross/aarch64-unknown-linux-gnu/aarch64-unknown-linux-gnu/release/kptui

kordophoned (Client Daemon)

The daemon maintains a local cache, handles update cycles, and exposes IPC for GUI apps.

• Linux: exposes a D‑Bus service (see service file in kordophoned/include).
• macOS: exposes an XPC service named net.buzzert.kordophonecd.

macOS XPC registration (manual during development):

cd core/kordophoned
launchctl load include/net.buzzert.kordophonecd.plist

The macOS GUI app (osx/) can programmatically register this during launch; see osx/README.md.

Packaging (RPM example)

kordophoned is configured for RPM packaging via cargo-generate-rpm.

cargo build --release
strip -s target/release/kordophoned
cargo generate-rpm

Packaging (DEB example)

kordophoned is configured for Debian packaging via cargo-deb.

cargo install cargo-deb
cd core
cargo deb -p kordophoned

kpcli (CLI)

Useful for quick testing and interacting with the daemon/cache.

cargo run -p kpcli -- --help

Notes

• TLS/WebSocket: the kordophone crate includes rustls and installs a crypto provider at process start.
• DB: kordophone-db includes Diesel migrations under kordophone-db/migrations/.