WIP: Flathub distribution (Flatpak manifest + AppStream metainfo, ADR 0034)

[Kyle-Falconer]

Draft. Adds a fifth Linux channel — Flathub — alongside the ADR 0022 native bundles, reusing the same app ID, .desktop file, and icon set. Flathub builds and hosts from its own manifest, so release.yml is untouched.

What's here

• flatpak/com.circuitstitch.apps.janitor.yml — the manifest. Builds offline against the freedesktop runtime + rust-stable SDK extension; vendors all 769 crates via cargo-sources.json.
• flatpak/cargo-sources.json — generated vendor set (1527 entries, all crates.io — no git deps, so generation is network-free).
• flatpak/gen-cargo-sources.sh + flatpak/README.md — regen wrapper (rerun on any Cargo.lock change) + local-build / submission how-to.
• janitor-gui/assets/com.circuitstitch.apps.janitor.metainfo.xml — AppStream metainfo (mandatory for Flathub; also installed by the rpm).
• janitor-gui/Cargo.toml — metainfo wired into the generate-rpm assets.
• docs/adr/0034-flathub-distribution.md — the decision record.

Sandbox

Tight by default (the threat model gives this for free — nothing secret on disk, config is per-app): --share=network + Slint's GUI sockets only. No --filesystem, no extra talk-names.

• The OAuth loopback survives the sandbox: --share=network shares the host netns, so the host browser's 127.0.0.1:5369x/oauth/callback redirect reaches the in-app listener.
• Browser launch routes through the OpenURI portal automatically.
• ⚠️ Casualty: ADR 0033's CommandBrowser incognito-isolation opener can't see host binaries in the sandbox (would need flatpak-spawn --host, deliberately not granted). DefaultBrowser works; documented in the ADR.

Validation

• appstreamcli validate — clean except one expected warning (screenshot file not yet committed; see follow-ups).
• desktop-file-validate — pass.
• Manifest YAML + cargo-sources.json parse.
• ⚠️ No real flatpak-builder run yet (not available in the authoring env) — see follow-ups.

Follow-up work (blocks merge / submission)

• Commit a real screenshot at docs/screenshots/matrix.png (or repoint the metainfo <image> URL) — clears the last validator warning.
• Run flatpak-builder --user --install --force-clean build-dir flatpak/com.circuitstitch.apps.janitor.yml and confirm the app launches, signs in (loopback), and renders the matrix.
• Pin the manifest's git source to a release tag and its commit sha.
• Bump runtime-version (24.08) to whatever freedesktop runtime is current at submission.
• Open the PR to flathub/flathub (the new-pr branch); reviewers confirm domain control of circuitstitch.com for the com.circuitstitch.* ID.

Optional / nice-to-have

• Add a CLAUDE.md "Latest:" banner for ADR 0034 (matches the existing per-ADR convention).
• Ship the metainfo via the .deb too (cargo-packager has no clean file-map; rpm + Flatpak cover it today).

🤖 Generated with Claude Code