solstone-linux 0.1.0__tar.gz

solstone_linux-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.venv/
+.installed
+uv.lock

solstone_linux-0.1.0/AGENTS.md

@@ -0,0 +1,158 @@
+# AGENTS.md
+
+Development guidelines for solstone-linux, a standalone Linux desktop observer.
+
+## Project Overview
+
+solstone-linux is a companion app that runs alongside the main [solstone](https://solstone.app) journal. It is one of the owner's observers — it experiences screen and audio along with the owner on a Linux desktop using PipeWire and GStreamer, stores segments locally, and syncs them to your solstone journal. It runs as a systemd user service on GNOME Wayland sessions.
+
+This is **not** part of the solstone monorepo. It is a standalone package with its own release lifecycle, installed via pipx alongside system-provided PyGObject/GStreamer bindings.
+
+## Source Layout
+
+```
+src/solstone_linux/
+    __init__.py             Package version
+    cli.py                  CLI entry point (run, setup, install-service, status)
+    solstone-linux.service.in        Systemd unit template (rendered by install-service)
+    config.py               Config loading/persistence (~/.local/share/solstone-linux/)
+    observer.py             Main capture loop — state machine (idle/screencast), audio + video
+    screencast.py           Portal-based multi-monitor recording (xdg-desktop-portal + GStreamer)
+    audio_recorder.py       Stereo audio recording (mic + system via soundcard)
+    audio_detect.py         Audio device detection via ultrasonic tone
+    audio_mute.py           PulseAudio mute state detection
+    activity.py             Cross-desktop activity detection (screen lock, power save) via DBus
+    monitor_positions.py    Monitor position assignment from geometry
+    session_env.py          Desktop session environment checks and recovery
+    streams.py              Stream name derivation (hostname-based)
+    sync.py                 Background sync service — uploads completed segments to server
+    upload.py               HTTP upload client for solstone ingest server
+    recovery.py             Crash recovery for orphaned .incomplete segments
+
+tests/                      pytest test suite
+contrib/                    Reference icons for development fallback
+```
+
+## Architecture
+
+The observer runs a single asyncio event loop with three concurrent concerns:
+
+1. **Capture loop** (`observer.py`) — Checks activity status every 5 seconds, records audio continuously, manages screencast recording via GStreamer. Creates 5-minute segments in `~/.local/share/solstone-linux/captures/YYYYMMDD/stream/HHMMSS_DDD/`. Segment directories start as `.incomplete` and are renamed on finalization.
+
+2. **Sync service** (`sync.py`) — Background asyncio task that walks the captures directory, queries the server for existing segments, and uploads missing ones. Circuit breaker pattern with error-type-aware thresholds.
+
+3. **Chat bridge** (`chat_bridge.py`) — Background asyncio task that consumes server-sent callosum chat events, mirrors request/clear messages to an optional local FIFO, and fires click-capturing `notify-send` subprocesses when server opt-in allows Linux desktop notifications.
+
+State machine has two modes: `screencast` (screen active, recording video) and `idle` (screen inactive). Mode transitions, mute state changes, and 5-minute intervals all trigger segment boundaries.
+
+The capture loop never makes network calls. It writes locally; sync handles all uploads.
+
+## Commands
+
+```bash
+make install        # Create venv, install package + dev tools (pytest, ruff) via uv
+make test           # Run all tests
+make test-only TEST=tests/test_config.py  # Run specific test
+make format         # Auto-format with ruff
+make ci             # Lint + format check + tests
+make install-service  # Smart install-or-upgrade: guards against cross-repo contamination; runs CI in upgrade mode
+make service-restart  # systemctl restart wrapper
+make service-status   # systemctl status wrapper
+make service-logs     # systemctl log tail wrapper
+make uninstall-service  # Disable + remove unit + pipx uninstall
+make clean          # Remove build artifacts and caches
+make versions       # Show installed package versions
+```
+
+## Releasing
+
+solstone-linux ships to PyPI via `scripts/release.sh`. The operator runs the
+release from a clean checkout; there is no CI publish path.
+
+```bash
+make release-test   # upload to TestPyPI (requires TESTPYPI_TOKEN)
+make release        # upload to PyPI (requires PYPI_TOKEN)
+```
+
+The script refuses to run on a dirty tree, builds an sdist + a
+`py3-none-any` wheel with `uv build`, runs `uvx twine check`, uploads,
+tags the commit `vX.Y.Z`, pushes the tag, and creates a matching GitHub
+Release with the artifacts attached and the CHANGELOG block as release
+notes.
+
+Before releasing, bump the version in BOTH `pyproject.toml` (`[project].version`)
+and `src/solstone_linux/__init__.py` (`__version__`) — they must match — and add
+a `## [X.Y.Z] - YYYY-MM-DD` block to `CHANGELOG.md`.
+
+Set `RELEASE_DRY_RUN=1` to walk the full flow without uploading, tagging,
+pushing, or publishing a GitHub Release; the build and `twine check` still
+run for real.
+
+## Development Principles
+
+- **Simple code.** Prefer plain functions over classes. Use dataclasses for structured data. Only use classes when managing stateful lifecycle (Observer, Screencaster, SyncService, AudioRecorder).
+- **Async by default.** The main loop is asyncio. DBus calls, subprocess management, and sync all use async. Audio recording uses a dedicated thread because soundcard is blocking.
+- **No network in the capture loop.** The observer writes segments locally. The sync service uploads asynchronously. This keeps capture reliable even when the server is down.
+- **Atomic directory operations.** Segments start as `HHMMSS.incomplete/`, are renamed to `HHMMSS_DDD/` on completion, or `HHMMSS.failed/` on recovery failure.
+- **System site-packages required.** PyGObject and GStreamer bindings come from system packages. The venv (and pipx) must use `--system-site-packages`.
+
+## File Headers
+
+All `.py` source files must include this header as the first two lines:
+
+```python
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+```
+
+Add this header to new `.py` files in `src/solstone_linux/` and `tests/`. Do not add headers to markdown, TOML, or config files.
+
+## Runtime Dependencies
+
+System packages (not pip-installable):
+- `python3-gobject` / `python3-gi` — PyGObject for GTK4 and GDK
+- GStreamer with PipeWire plugin (`gst-launch-1.0 pipewiresrc`)
+- PipeWire running
+- `pactl` (PulseAudio utils) for mute detection
+- xdg-desktop-portal with ScreenCast support
+
+Python packages (in pyproject.toml):
+- `requests` — HTTP upload client
+- `numpy` — Audio buffer manipulation and RMS computation
+- `soundfile` — FLAC encoding
+- `soundcard` — Audio device enumeration and recording
+- `dbus-next` — Async DBus client for portal and activity detection
+- `PyGObject` — GDK monitor geometry (installed from system)
+
+## Data Paths
+
+- Config: `~/.local/share/solstone-linux/config/config.json`
+- Captures: `~/.local/share/solstone-linux/captures/`
+- State: `~/.local/share/solstone-linux/state/`
+- Restore token: `~/.local/share/solstone-linux/config/restore_token`
+- Install source marker: `~/.config/solstone-linux/.install-source` (tracks which repo clone owns the pipx install)
+
+## Key Patterns
+
+- **Activity detection is cross-desktop.** Uses ordered DBus fallback chains for screen lock (freedesktop.org ScreenSaver → GNOME ScreenSaver) and power save (Mutter DisplayConfig → KDE Solid PowerManagement). All backends degrade gracefully to safe defaults.
+- **Audio is stereo-interleaved.** Left channel = microphone, right channel = system audio. When muted, channels are split into separate mono FLAC files.
+- **Screencast uses xdg-desktop-portal.** Session persistence via restore tokens avoids re-prompting the user. GStreamer subprocess (`gst-launch-1.0`) handles the actual PipeWire recording.
+- **Crash recovery runs on startup.** `recovery.py` scans for orphaned `.incomplete` directories older than 2 minutes and finalizes or marks them as failed.
+
+## Testing
+
+Tests use pytest with standard mocking. No system dependencies required for tests — audio devices, DBus, and GStreamer are mocked. Run `make test` to execute the full suite.
+
+## Brand canon
+
+- **solstone-linux is an observer.** Owner-facing canon describes solstone as observers + journal; sol is the keeper who lives in and tends your journal. In engineering architecture, `observers + sol agent + journal` is the running software this repo's code talks to. This repo implements one of those observers.
+- **The canon lives elsewhere.** Owner-facing terminology comes from sol pbc's internal brand canon (system anatomy + voice terminology guides). This repo's branded prose follows it; the canon itself is not vendored here.
+- **Use co-experience language in branded prose.** In README, INSTALL, onboarding text, settings copy, and error messages, describe solstone-linux as something that experiences screen and audio along with the owner. Never describe it as watching, recording, monitoring, or tracking the owner.
+- **Keep code language in code-only contexts.** Internal architecture terms such as `Capture loop`, the capture pipeline, module names, and data-path names are canon-permitted here and must not be renamed just to match branded prose.
+- **Edit with the surface in mind.** If the owner sees the string, follow the canon. If the text is naming code, pipelines, modules, or storage artifacts for engineers, the existing internal vocabulary stays.
+
+Canon source of truth: sol pbc's internal brand canon (system-anatomy guide).
+
+## License
+
+AGPL-3.0-only -- Copyright (c) 2026 sol pbc

solstone_linux-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to solstone-linux are documented here.
+The format is based on Keep a Changelog (https://keepachangelog.com/),
+and this project adheres to Semantic Versioning.
+
+## [0.1.0] - 2026-05-19
+
+First public release of solstone-linux — the Linux desktop observer
+for your solstone journal.
+
+solstone-linux runs as a systemd user service in your GNOME Wayland
+session. It experiences screen and audio along with you, holds short
+segments locally, and uploads them to your journal in the background.
+
+### Install paths
+
+- From PyPI: `pipx install --system-site-packages solstone-linux`,
+  then `solstone-linux install-service` to register the systemd unit.
+- From a clone: `git clone` this repo and run `make install-service`
+  for development or unreleased changes.
+
+Both paths rely on host packages for PyGObject, GStreamer with the
+PipeWire plugin, PipeWire itself, `pactl`, and `xdg-desktop-portal`
+with ScreenCast support. PyGObject and the GStreamer bindings ride
+along from system site-packages — that is why `--system-site-packages`
+matters.

solstone_linux-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

solstone_linux-0.1.0/INSTALL.md

@@ -0,0 +1,153 @@
+# installing solstone-linux
+
+these instructions are for a coding agent and human working together. solstone-linux is a standalone observer that experiences your screen and audio along with you on linux desktops using PipeWire and GStreamer, and uploads to your solstone journal.
+
+solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
+
+> **most users should run `sol observer install` from the solstone host instead of following this file by hand.** that one command handles the clone, the system-package preflight, the build, the registration, and the systemd unit — including a `--dry-run` mode to preview every step. the instructions below are for developers building from source or troubleshooting the install.
+
+## before you begin
+
+if `sol` is not in PATH, check `~/.local/bin/sol`.
+
+check if solstone-linux is already installed and running:
+
+```
+systemctl --user status solstone-linux
+sol remote list
+```
+
+if it's already active and connected, you're done.
+
+## what to sort out together
+
+- **system dependencies.** the observer needs PyGObject, GStreamer, and PipeWire bindings from system packages. installing these requires sudo.
+- **stream name.** this identifies this observer's stream. the machine's hostname is the typical choice.
+
+### remote sol
+
+The observer connects to your solstone journal over HTTPS — colocation is optional. For remote-sol setups:
+
+- clone anywhere; the `$(sol root)/observers` path in step 2 only applies when sol is installed locally.
+- `solstone-linux setup` will prompt for the journal URL (since local `sol remote list` isn't available) and auto-register the observer with your journal via HTTP, persisting the returned key. No manual key handoff is needed if the journal's observer-registration endpoint is reachable.
+- otherwise, the install sequence below is the same.
+
+## install sequence
+
+1. install system dependencies for your distro, including `pipx`. if you need sudo, walk your human through it.
+
+   **fedora:**
+   ```
+   sudo dnf install python3-gobject gtk4 gstreamer1-plugins-base gstreamer1-plugin-pipewire pipewire-gstreamer alsa-lib-devel pulseaudio-utils pipewire-pulseaudio xdg-desktop-portal pipx
+   ```
+
+   **debian / ubuntu:**
+   ```
+   sudo apt install python3-gi gir1.2-gdk-4.0 gir1.2-gtk-4.0 gstreamer1.0-pipewire libasound2-dev pulseaudio-utils pipewire-pulse xdg-desktop-portal pipx
+   ```
+
+   **arch:**
+   ```
+   sudo pacman -S python-gobject gtk4 gstreamer gst-plugin-pipewire libpulse alsa-lib xdg-desktop-portal pipx
+   ```
+
+   **opensuse:**
+   ```
+   sudo zypper install python3-gobject python3-gobject-Gdk typelib-1_0-Gtk-4_0 \
+     gtk4-tools gstreamer-plugins-base gstreamer-plugin-pipewire \
+     pipewire-pulseaudio pulseaudio-utils alsa-devel \
+     xdg-desktop-portal python3-pipx
+   ```
+   note: package names diverge from Fedora — `typelib-1_0-Gtk-4_0` (not `gtk4`), `gstreamer-plugin-pipewire` (singular), and `alsa-devel` (not `alsa-lib-devel`).
+
+2. If you have local sol, cloning into `$(sol root)/observers` keeps observers colocated with your solstone journal. For remote-sol setups, clone anywhere — the observer runs independently of your journal at runtime:
+   ```
+   cd "$(sol root)/observers"
+   git clone https://github.com/solpbc/solstone-linux.git
+   cd solstone-linux
+   make install-service
+   ```
+   `make install-service` is a smart install-or-upgrade: detects fresh-install vs upgrade via a marker file, runs CI in upgrade mode, guards against cross-repo contamination.
+
+3. run the interactive setup:
+   ```
+   solstone-linux setup
+   ```
+   this prompts for the journal URL and auto-registers via `sol` when available.
+
+4. verify the service is running:
+   ```
+   systemctl --user status solstone-linux
+   ```
+
+## updating after a code change
+
+```
+git pull && make install-service
+```
+
+## notes
+
+- activity detection (idle timeout, screen lock, power save) works on both GNOME and KDE. on other desktops the observer still experiences your screen and audio fine, but activity-based segment boundaries won't trigger.
+- the tray icon uses the StatusNotifierItem (SNI) D-Bus protocol. it works on KDE natively and GNOME with the AppIndicator extension. if no SNI host is available, the observer runs normally without a tray icon.
+
+## appendix: GNOME tray support
+
+the system tray icon appears automatically when the observer starts in a graphical session. on KDE Plasma this works out of the box. on GNOME, the AppIndicator extension is required.
+
+GNOME removed native system tray support. the AppIndicator extension restores it via the same StatusNotifierItem protocol KDE uses. without it, the observer runs fine but has no tray icon.
+
+**ubuntu:** already installed and enabled by default — skip this step.
+
+**fedora:**
+```
+sudo dnf install gnome-shell-extension-appindicator
+```
+then log out and back in, or restart GNOME Shell (Alt+F2, type `r`, enter). enable the extension in GNOME Extensions app if not auto-enabled.
+
+**arch:**
+```
+sudo pacman -S gnome-shell-extension-appindicator
+```
+
+**other distros (openSUSE, etc.):**
+
+if your distro doesn't ship an AppIndicator extension package, install it from extensions.gnome.org via the CLI:
+
+```
+curl -LO https://extensions.gnome.org/extension-data/appindicatorsupportrgcjonas.gmail.com.v64.shell-extension.zip
+gnome-extensions install appindicatorsupportrgcjonas.gmail.com.v64.shell-extension.zip
+gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
+```
+
+then restart GNOME Shell — on Wayland, log out and back in; on X11, press Alt+F2 and type `r`. v64 supports GNOME Shell 45–50; check https://extensions.gnome.org/extension/615/appindicator-support/ for a newer build if you're on a later shell.
+
+to check if it's working: `gnome-extensions list | grep appindicator` should show it. if the tray icon still doesn't appear, verify it's enabled: `gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com`
+
+## Troubleshooting
+
+Common install-time errors and their fixes:
+
+- **`pkg-config: command not found` or `cairo` pkg-config failure**
+  - fedora: `sudo dnf install pkgconf-pkg-config cairo-devel`
+  - debian/ubuntu: `sudo apt install pkg-config libcairo2-dev`
+  - arch: `sudo pacman -S pkgconf cairo`
+  - opensuse: `sudo zypper install pkgconf-pkg-config cairo-devel`
+
+- **`girepository-2.0` missing or `pygobject` build failure**
+  - fedora: `sudo dnf install gobject-introspection-devel`
+  - debian/ubuntu: `sudo apt install libgirepository1.0-dev`
+  - arch: `sudo pacman -S gobject-introspection`
+  - opensuse: `sudo zypper install gobject-introspection-devel`
+
+- **`Python.h: No such file or directory`**
+  - fedora: `sudo dnf install python3-devel`
+  - debian/ubuntu: `sudo apt install python3-dev`
+  - arch: already bundled in `python` package
+  - opensuse: `sudo zypper install python3-devel`
+
+- **`pipx: command not found`**
+  - fedora: `sudo dnf install pipx`
+  - debian/ubuntu: `sudo apt install pipx`
+  - arch: `sudo pacman -S python-pipx`
+  - opensuse: `sudo zypper install python3-pipx`