feat(desktop): vouch review-ui AppImage for Ubuntu (stacked on #195) by plind-junior · Pull Request #203 · vouchdev/vouch

plind-junior · 2026-06-12T00:01:50Z

Summary

bundles vouch review-ui (from #195) into a self-contained ubuntu x86_64 .AppImage (~33 MB) using python-appimage. one binary, no apt install, double-click to launch the browser review console. first-run auto-inits ~/.vouch/ if absent.

stacks on top of feat/194-review-ui (PR #195) — the review-ui module is what the launcher wraps, so this PR needs #195 to merge first.

What changed

desktop/ — appdir for python-appimage:
- vouch-review-ui.desktop — linux menu entry (Categories=Development;Office;Utility; Terminal=false)
- vouch-review-ui.svg — scalable monograph icon (vermillion checkmark + ink V on cream paper)
- entrypoint.sh — auto-inits $VOUCH_KB_PATH (default $HOME) on first run, then exec python -m vouch review-ui --kb "$KB_ROOT" "$@"
- requirements.txt — local+vouch (working-tree bundle) + the [web]-extra deps explicit until vouch-kb cuts a release with the [web] extra
- README.md — build + launch instructions
src/vouch/__main__.py — one-liner shim so python -m vouch works (the AppImage entrypoint uses it instead of the console-script shim that would need to be on PATH)
.github/workflows/desktop.yml — builds + smoke-tests the AppImage on push to main / release branches, and attaches it as a release asset on v* tags

Why

the existing pipx install vouch-kb story is great for power users but assumes a working python + pipx. "release the desktop app" implies a single download that runs anywhere modern ubuntu lives. AppImage is the right shape: one file, runs on 18.04+ without elevated permissions, integrates with file managers and menu entries via the bundled .desktop file. python-appimage is a thin builder (~50 LoC of recipe) that doesn't introduce electron/tauri or a node toolchain.

Tests

local build + smoke test:

$ python -m python_appimage build app desktop/ --python-version 3.12
# → vouch-x86_64.AppImage (33 MB)

$ VOUCH_KB_PATH=/tmp/vouch-test-kb ./vouch-x86_64.AppImage --no-open-browser --bind 127.0.0.1:8851 &
$ curl -s http://127.0.0.1:8851/healthz
{"ok":true,"kb":"/tmp/vouch-test-kb","pending":0}
$ curl -s http://127.0.0.1:8851/ | head -3
<!doctype html>
<html lang="en">
<head>

the desktop.yml workflow re-runs the same smoke test in CI so any regression that breaks the launch path fails the workflow.

Not included (follow-ups)

system-tray quit menu / auto-start on login — needs a native shell (tauri/electron), deferred
.deb package — AppImage is the ubuntu story for v1; .deb lands once we have a downstream packager
snap / flatpak — needs separate confinement work
arm64 / aarch64 builds — --linux-tag manylinux2014_aarch64 once we have a runner
auto-update via AppImageUpdate — easy add once the release workflow is stable

Stacking note

this PR's diff includes the review-ui changes from #195 because it branches off feat/194-review-ui. once #195 merges, github will narrow the diff automatically. if you'd rather see the desktop changes in isolation: git diff f4c5c64..feat/desktop-appimage shows the 7 files added by this PR.

Closes nothing directly (the desktop app isn't a tracked issue yet); related to #194.

bundles a relocatable cpython 3.12 + the [web] extra + the working-tree vouch source into a single ~33 mb .AppImage that double-clicks to launch the review-ui in the browser. first-run auto-inits ~/.vouch/ if absent. uses python-appimage as the builder; appdir lives at desktop/ alongside adapters/. ships .github/workflows/desktop.yml that builds and smoke-tests the AppImage on every push to main / release branch + attaches it as a release asset on version tags. adds src/vouch/__main__.py so the appimage entrypoint can call `python -m vouch review-ui` without depending on the console-script shim being on PATH. stacks on top of feat/194-review-ui (#195) — the review-ui module is the thing the desktop launcher wraps.

coderabbitai · 2026-06-12T00:01:58Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 418d6863-3ffc-4c63-82c0-9917932086ee

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/desktop-appimage

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

plind-junior · 2026-06-17T10:27:41Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e8890f2364

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-17T10:41:24Z

+            --python-version 3.12 \
+            --linux-tag manylinux2014_x86_64
+          # python-appimage names the output after the appdir basename:
+          mv desktop-x86_64.AppImage vouch-review-ui-x86_64.AppImage || true


Rename the AppImage name that python-appimage actually emits

I checked python-appimage's build code and appimagetool behavior: when no explicit destination is supplied, the output name is derived from the bundled desktop entry's Name= field (this recipe sets Name=vouch), so this build produces vouch-x86_64.AppImage, not desktop-x86_64.AppImage. Because this mv is allowed to fail, the following smoke test and release upload still look for vouch-review-ui-x86_64.AppImage, causing the desktop workflow/tag release to fail before publishing the artifact.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-17T10:41:24Z

+local+vouch
+
+# [web] extra (explicit until vouch-kb's published version ships it)
+fastapi>=0.115


Avoid unquoted version specifiers in AppImage requirements

For python-appimage recipes, each requirement is passed through python_appimage.utils.system(), which joins arguments into a shell command and runs it with shell=True; as a result fastapi>=0.115 is parsed by the shell as the package name fastapi with stdout redirected to =0.115. This means the AppImage build silently ignores the intended version bounds for these dependencies and can bundle future incompatible releases even though the requirements file appears constrained.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-17T10:41:24Z

+
+      - name: smoke test (boots and serves /healthz)
+        run: |
+          ./vouch-review-ui-x86_64.AppImage --no-open-browser --bind 127.0.0.1:8851 &


Install FUSE before executing the AppImage

On ubuntu-latest (now Ubuntu 24.04), the runner image's documented apt package list does not include libfuse2/libfuse2t64, while AppImages still require FUSE/libfuse to execute normally. After the filename issue is fixed, this direct smoke-test launch will fail on the hosted runner with the usual libfuse.so.2/FUSE error unless the workflow installs the FUSE 2 compatibility package or runs the extracted AppRun instead.

Useful? React with 👍 / 👎.

chatgpt-codex-connector Bot reviewed Jun 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(desktop): vouch review-ui AppImage for Ubuntu (stacked on #195)#203

feat(desktop): vouch review-ui AppImage for Ubuntu (stacked on #195)#203
plind-junior wants to merge 1 commit into
feat/194-review-uifrom
feat/desktop-appimage

plind-junior commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026

Review skipped

Uh oh!

plind-junior commented Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

plind-junior commented Jun 12, 2026

Summary

What changed

Why

Tests

Not included (follow-ups)

Stacking note

Uh oh!

coderabbitai Bot commented Jun 12, 2026

Review skipped

Uh oh!

plind-junior commented Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant