poncho-wonky-flatpak/README.md

# Patchwork Flatpak

Flatpak packaging for [Poncho Wonky](https://github.com/soapdog/patchwork), the
Secure Scuttlebutt (SSB) desktop client. This is a **release-wrapper** Flatpak:
it repackages the official upstream `tar.gz` build from the
[GitHub releases page](https://github.com/soapdog/patchwork/releases) instead of
building from source, so no native modules are recompiled inside the sandbox.

The packaging files in this repository (manifest, launcher, build scripts) are
licensed under CC0-1.0 (see `LICENSE`). The packaged application itself remains
AGPL-3.0, as declared in `nz.scuttlebutt.Patchwork.metainfo.xml`.

## Layout

| File | Purpose |
|------|---------|
| `nz.scuttlebutt.Patchwork.yaml` | `flatpak-builder` manifest |
| `patchwork.sh` | Launcher that runs the app through `zypak-wrapper` (Electron sandbox) |
| `nz.scuttlebutt.Patchwork.metainfo.xml` | AppStream metadata for software centers |
| `build.sh` | One-shot build + install helper |
| `flathub.json` | Flathub build config |

## Prerequisites

On Debian/Ubuntu:

```bash
sudo apt install flatpak flatpak-builder
flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo
```

Alternatively, `flatpak-builder` can be installed as a Flatpak:

```bash
flatpak install flathub org.flatpak.Builder
```

If you use `org.flatpak.Builder`, you'll need to run builds with:

```bash
flatpak run --command=flatpak-builder org.flatpak.Builder \
  --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml
```

## Build and install

```bash
./build.sh
```

or manually:

```bash
flatpak install -y flathub \
  org.freedesktop.Platform//24.08 \
  org.freedesktop.Sdk//24.08 \
  org.electronjs.Electron2.BaseApp//24.08

flatpak-builder --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml

flatpak --user remote-add --if-not-exists --no-gpg-verify patchwork-repo repo
flatpak --user install -y patchwork-repo nz.scuttlebutt.Patchwork
```

Run it:

```bash
flatpak run nz.scuttlebutt.Patchwork
```

The launcher (`patchwork.sh`) forces Electron onto Wayland whenever a Wayland
socket is available, so it also works from terminals that are not part of the
desktop session (local TTY, SSH) where `DISPLAY`/`WAYLAND_DISPLAY` would
otherwise be unset and Electron would fail with `Missing X server or $DISPLAY`.
On X11-only systems it falls back to Electron's default X11 platform.

## Updating to a new release

All pinned versions live in `versions.sh`. Bump the app version first:

1. Note the new version tag (e.g. `v5.5.0`) and download the new assets:

   ```bash
   wget https://github.com/soapdog/patchwork/releases/download/v5.5.0/ponchowonky-5.5.0.tar.gz
   wget https://github.com/soapdog/patchwork/releases/download/v5.5.0/ponchowonky-5.5.0-arm64.tar.gz
   sha256sum ponchowonky-5.5.0.tar.gz ponchowonky-5.5.0-arm64.tar.gz
   ```

2. Update `APP_VERSION`, `APP_SHA256_X86_64` and `APP_SHA256_AARCH64` in
   `versions.sh`, then run `./check-versions.sh` — it verifies the manifest
   URLs/checksums and the metainfo release entry still match.
3. Update `url`/`sha256` in `nz.scuttlebutt.Patchwork.yaml`. No
   `build-commands` change is needed: flatpak-builder strips the archive's
   top-level directory (default `strip-components: 1`) into the `app/` source
   directory.
4. Add a new `<release>` entry in `nz.scuttlebutt.Patchwork.metainfo.xml`.

To bump the Flatpak environment, update `RUNTIME_VERSION` in `versions.sh` (used
for the freedesktop runtime, SDK and Electron BaseApp — they always move
together).

## Automated updates

`update-version.sh` performs the app-version bump above automatically: it
fetches the latest upstream release, downloads both `tar.gz` assets to compute
their sha256, and updates `versions.sh`, the manifest and the metainfo
(including the release date). Run it locally with `--dry-run` to preview, or
plain to apply (requires `curl` and `jq`).

Two GitHub Actions drive the workflow:

- **`.github/workflows/update.yml`** — on a daily schedule (or
  `workflow_dispatch`) runs `update-version.sh`, commits the bump as
  `github-actions[bot]`, pushes a branch and opens a PR labeled `automerge`.
- **`.github/workflows/build.yml`** — on every PR and push to `main` validates
  the shell scripts and pinned versions, then builds the Flatpak in the
  `freedesktop-24.08` Flathub CI container (installing the Electron BaseApp
  first). A `merge` job auto-merges the bump PR with `--squash` once both jobs
  pass; if the build fails the PR stays open for manual review.

Runtime bumps are never automated — only the app version is.

## Notes

- **Why `tar.gz` and not the AppImage?** The upstream `tar.gz` assets are the
  unpacked `electron-builder` build. Using them avoids the `--appimage-extract`
  step and keeps the manifest architecture-agnostic.
- **Runtime vs. Electron version.** The app ships its own Electron binary inside
  the `tar.gz`, so the runtime is not tied to Electron's version — it only needs
  to satisfy the host glibc/GTK stack that Electron requires. `RUNTIME_VERSION`
  should be bumped to the next freedesktop branch only when a newer Electron
  stops working on the current one (the manifest change is one line plus a
  rebuild).
- **SSB data.** Patchwork resolves its data directory from the real user home
  (`getpwuid`), not `$HOME`, so it writes to `~/.ssb` on the host even from
  inside the sandbox. A non-Flatpak install shares the same data — no migration
  needed. (Flatpak still redirects `~/.cache`, `~/.config` and `~/.local` for
  this app to `~/.var/app/nz.scuttlebutt.Patchwork/`.)
- **Network.** SSB uses LAN multicast discovery, DHT and direct TCP/UDP;
  `--share=network` covers this. `--device=all` is granted for webcam support
  and can be removed from `finish-args` if you do not want it.
- **Flathub.** The metainfo `<screenshots>` section is omitted because the
  upstream screenshot URL currently returns 404. Add screenshots hosted on a
  stable CDN before submitting to Flathub.