From 6c4d6d6aefca0d6c2db816bcf5ff086b1af1c80f Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Thu, 19 Mar 2026 15:57:50 -0400 Subject: [PATCH] feat: formalize platform runtime contracts --- .github/workflows/binaries.yml | 16 + .github/workflows/ci.yml | 36 +++ Dockerfile | 12 +- README.md | 12 +- RELEASE.md | 8 +- ci/test-e2e.sh | 6 + docs/ar/docker.md | 9 +- docs/ar/troubleshooting.md | 15 + docs/de/docker.md | 9 +- docs/de/troubleshooting.md | 15 + docs/en/docker.md | 9 +- docs/en/troubleshooting.md | 15 + docs/en/usage.md | 16 +- docs/es/docker.md | 9 +- docs/es/troubleshooting.md | 15 + docs/fa/docker.md | 9 +- docs/fa/troubleshooting.md | 15 + docs/fr/docker.md | 9 +- docs/fr/troubleshooting.md | 15 + docs/he/docker.md | 9 +- docs/he/troubleshooting.md | 15 + docs/he/usage.md | 16 +- docs/hi/docker.md | 9 +- docs/hi/troubleshooting.md | 15 + docs/ja/docker.md | 9 +- docs/ja/troubleshooting.md | 15 + docs/platform-support-matrix.md | 51 +++ docs/pt/docker.md | 9 +- docs/pt/troubleshooting.md | 15 + docs/roadmap-platform-parity.md | 270 ++++++++++++++++ docs/ru/docker.md | 9 +- docs/ru/troubleshooting.md | 15 + docs/sw/docker.md | 9 +- docs/sw/troubleshooting.md | 15 + docs/templates/docker.md | 9 +- docs/templates/troubleshooting.md | 15 + docs/templates/usage.md | 16 +- docs/tr/docker.md | 9 +- docs/tr/troubleshooting.md | 15 + docs/zh/docker.md | 9 +- docs/zh/troubleshooting.md | 15 + gui/README.md | 3 + gui/electron/index.html | 75 +++++ gui/electron/main.js | 122 ++++---- gui/electron/preload.js | 1 + install.ps1 | 44 ++- install.sh | 54 ++++ packaging/build_appimage.sh | 2 + packaging/build_deb.sh | 2 + packaging/build_dmg.sh | 2 + .../chocolatey/tools/chocolateyInstall.ps1 | 1 + packaging/flatpak/org.voxvera.VoxVera.yml | 1 + packaging/homebrew/voxvera.rb | 2 +- scripts/check.sh | 5 + scripts/platform-smoke.sh | 142 +++++++++ support-matrix.json | 156 ++++++++++ tests/test_cli.py | 274 +++++++++++++++- tests/test_integrity.py | 37 +++ voxvera-install.sh | 56 ++++ voxvera/build.py | 2 +- voxvera/cli.py | 294 ++++++++++++------ voxvera/platforms/__init__.py | 17 + voxvera/platforms/base.py | 137 ++++++++ voxvera/platforms/linux.py | 194 ++++++++++++ voxvera/platforms/macos.py | 90 ++++++ voxvera/platforms/windows.py | 54 ++++ 66 files changed, 2356 insertions(+), 230 deletions(-) create mode 100644 docs/platform-support-matrix.md create mode 100644 docs/roadmap-platform-parity.md create mode 100644 scripts/platform-smoke.sh create mode 100644 support-matrix.json create mode 100644 voxvera/platforms/__init__.py create mode 100644 voxvera/platforms/base.py create mode 100644 voxvera/platforms/linux.py create mode 100644 voxvera/platforms/macos.py create mode 100644 voxvera/platforms/windows.py diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml index c7b4786..8778b8d 100644 --- a/.github/workflows/binaries.yml +++ b/.github/workflows/binaries.yml @@ -74,6 +74,22 @@ jobs: --name "${{ matrix.artifact_name }}" \ voxvera/cli.py + - name: Validate built binary contract surface (Linux/macOS) + if: matrix.os != 'windows-latest' + shell: bash + run: | + ./dist/${{ matrix.artifact_name }} platform-status --json + ./dist/${{ matrix.artifact_name }} doctor --json + ./dist/${{ matrix.artifact_name }} autostart status --json + + - name: Validate built binary contract surface (Windows) + if: matrix.os == 'windows-latest' + shell: pwsh + run: | + & ".\dist\${{ matrix.artifact_name }}" platform-status --json + & ".\dist\${{ matrix.artifact_name }}" doctor --json + & ".\dist\${{ matrix.artifact_name }}" autostart status --json + - name: Build .deb (Linux) if: matrix.os == 'ubuntu-22.04' run: | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4349dda..afbb387 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,3 +23,39 @@ jobs: run: flake8 voxvera tests --exclude=voxvera/vendor --ignore=E501,W503,W293,E402,E306,E704,E261,F841,E302,F401,E401,F541 - name: Test run: pytest tests/ -v + - name: Platform smoke + run: bash scripts/platform-smoke.sh linux-cli + + platform-contract: + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + include: + - os: macos-latest + smoke_target: macos-cli + - os: windows-latest + smoke_target: windows-cli + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Install dependencies + shell: bash + run: | + python -m pip install --upgrade pip + pip install -e ".[test]" + - name: Verify smoke target listing + shell: bash + run: bash scripts/platform-smoke.sh list + - name: Validate platform-status JSON + shell: bash + run: python -m voxvera.cli platform-status --json + - name: Validate doctor JSON + shell: bash + run: python -m voxvera.cli doctor --json + - name: Validate autostart JSON + shell: bash + run: python -m voxvera.cli autostart status --json diff --git a/Dockerfile b/Dockerfile index 02e9b1e..53be4c9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,8 @@ FROM python:3.11-slim +# Experimental container path: Linux systemd remains the supported +# persistent-host deployment target. + # Install system dependencies (only runtime) RUN apt-get update && apt-get install -y \ tor onionshare-cli \ @@ -13,10 +16,9 @@ WORKDIR /opt/voxvera RUN pip install . # Prepare flyers volume -RUN mkdir /flyers && ln -s /flyers /opt/voxvera/host +RUN mkdir /flyers +ENV VOXVERA_DIR=/flyers VOLUME /flyers -# VoxVera expects to run in /opt/voxvera for local assets -WORKDIR /opt/voxvera - -CMD ["voxvera", "quickstart"] +# Seed a default config when the volume is empty, then retry startup periodically. +CMD ["sh", "-lc", "mkdir -p /flyers && if [ ! -f /flyers/config.json ]; then cp /opt/voxvera/voxvera/src/config.json /flyers/config.json; fi && voxvera quickstart --non-interactive && while true; do sleep 300; voxvera start-all || true; done"] diff --git a/README.md b/README.md index 8496020..21df3e8 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,16 @@ Generate printable flyers with QR codes linking to Tor (.onion) hidden services. VoxVera is designed for maximum portability and censorship resistance. +Linux with systemd is the supported persistent-host deployment target. +Windows, macOS, Docker, Flatpak, AppImage, Homebrew, and Chocolatey remain experimental until their background Tor hosting and auto-recovery paths are validated end-to-end. + +See [docs/platform-support-matrix.md](docs/platform-support-matrix.md) for the canonical platform status table and [docs/roadmap-platform-parity.md](docs/roadmap-platform-parity.md) for the parity plan. + ### 1. Standalone Binaries (Recommended) -Download the zero-dependency executable for your OS: +Download the executable for your OS: - 🐧 [**Linux**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-linux) -- 🪟 [**Windows**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-windows.exe) -- 🍏 [**macOS**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-macos) +- 🪟 [**Windows (Experimental)**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-windows.exe) +- 🍏 [**macOS (Experimental)**](https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera-macos) ### 2. Universal Mirroring (The "Viral" Method) If you found a physical VoxVera flyer, scan it and click **"Download"**. You will receive a `voxvera-portable.zip` containing the full tool, all dependencies, and all 14 languages—ready to run offline. @@ -23,6 +28,7 @@ If you found a physical VoxVera flyer, scan it and click **"Download"**. You wil ```bash curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash ``` +On Linux, this now installs the recurring `systemd --user` recovery timer used to retry hidden-service startup after boot or offline periods. On macOS, the installer path is still experimental. ### 4. Developer / Python Install ```bash diff --git a/RELEASE.md b/RELEASE.md index ebed75c..9269ffd 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -46,7 +46,9 @@ python3 -m voxvera.cli build-site ## 3. Build Distribution Binaries -Standardized binaries and AppImages must be generated for the current platform. +Linux CLI delivery is the supported deployment target today. Other package formats should be treated as experimental release artifacts until their Tor/OnionShare background-hosting behavior is validated end-to-end. +Capture platform evidence before promoting any support tier: run `bash scripts/platform-smoke.sh linux-cli` locally for the supported Linux path, and keep CI/workflow evidence aligned with the same command. +As other runtime targets mature, use `bash scripts/platform-smoke.sh macos-cli`, `bash scripts/platform-smoke.sh windows-cli`, or `bash scripts/platform-smoke.sh docker-cli` on their native environments before changing their support labels. ### Standard Binary Generates an architecture-specific binary (e.g., `voxvera-linux-x86_64`) in `voxvera/resources/bin/`. @@ -60,24 +62,28 @@ Wraps the standard binary into a self-contained AppImage. ```bash ./packaging/build_appimage.sh ``` +Experimental package surface. ### Flatpak (Linux) Generates a standalone `.flatpak` bundle. Requires `flatpak-builder`. ```bash ./packaging/build_flatpak.sh ``` +Experimental package surface. ### Debian Package (Linux) Generates a `.deb` package for Debian/Ubuntu systems. ```bash ./packaging/build_deb.sh ``` +Experimental package surface unless its runtime dependencies and recovery behavior are explicitly validated for the release. ### DMG (macOS) Generates a `.dmg` installer for macOS (must be run on macOS). ```bash ./packaging/build_dmg.sh ``` +Experimental package surface. ## 4. Release Execution diff --git a/ci/test-e2e.sh b/ci/test-e2e.sh index f67fdc6..2e7bb15 100755 --- a/ci/test-e2e.sh +++ b/ci/test-e2e.sh @@ -26,6 +26,9 @@ fi echo "VoxVera command: $voxvera_cmd" +echo "Checking platform contract before workflow..." +bash scripts/platform-smoke.sh linux-cli + # Generate demo flyer echo "Initializing demo flyer..." "$voxvera_cmd" --lang en init --template voxvera <