From 6ef21337604dab035d3149d37c68bc84d48ab383 Mon Sep 17 00:00:00 2001 From: andwati Date: Wed, 12 Aug 2026 14:50:12 +0300 Subject: [PATCH] Refactor README for distro install docs, fix release archive Trim intro fluff, add per-distro dependency install commands, and make the Chrome Web Store the primary extension install path with unpacked install demoted to a dev-only section. Also switch the release workflow to archive the whole repo instead of just extension/, since install.sh and native-host/ are now what the README points users at downloading. --- .github/workflows/release.yml | 10 ++- README.md | 165 ++++++++++++++++++---------------- 2 files changed, 96 insertions(+), 79 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0d43eb5..36e5040 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,10 +15,12 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Package extension - run: | - cd extension - zip -r "../kget-capture-${GITHUB_REF_NAME}.zip" . + - name: Package source + # Users need the whole repo (install.sh, native-host/, keys/), not + # just extension/ -- the extension itself now ships via the Chrome + # Web Store. git archive only includes tracked files, so the + # gitignored private key (never committed) can't end up in it. + run: git archive --format=zip -o "kget-capture-${GITHUB_REF_NAME}.zip" HEAD - name: Create release uses: softprops/action-gh-release@v2 diff --git a/README.md b/README.md index d3cb200..66af2ef 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,84 @@ # KGet Capture -A Chrome (and other Chromium-browser) extension that sends downloads to -[KGet](https://apps.kde.org/kget/), KDE's download manager, instead of (or in -addition to) the browser's built-in downloader. +A Chromium browser extension that sends downloads to +[KGet](https://apps.kde.org/kget/), KDE's download manager, instead of the +browser's built-in downloader. -- Right-click any link, image, video, or audio element and choose - **"Download with KGet"** to send it straight to KGet — it starts - downloading immediately into your Downloads folder, no dialog. -- A toolbar toggle enables **auto-capture**: while on, every download Chrome - starts is cancelled and handed off to KGet the same way, automatically, - with the correct filename (resolved by Chrome itself, so it's right even - for URLs whose path is just an opaque ID). Defaults to ON. -- A "Download complete" desktop notification appears once a capture actually - finishes downloading. This is driven by the extension itself (not KGet's - own per-transfer notification, which KGet silently skips for downloads - that finish very quickly — see Troubleshooting), so it fires reliably - regardless of file size or speed. +- Right-click a link/image/video/audio and choose **"Download with KGet"**. +- Or toggle **auto-capture** from the toolbar so every download is handed off + automatically, with the correct filename. +- A desktop notification fires when a capture finishes downloading. ## Requirements -- Linux with KGet installed (and running, or set to autostart) -- One of: Google Chrome, Chromium, Brave, Vivaldi, Microsoft Edge -- `python3` and `dbus-send` on `PATH` (standard on virtually all Linux/KDE - systems already) -- `notify-send` (ships with most Linux desktops via libnotify) — optional, - only used for the download-complete notification; captures still work - without it, just silently -- `kwriteconfig6` (ships with KDE Plasma) — optional, only used to disable - KGet's own unreliable per-transfer notification so it doesn't double up - with the extension's; install still works without it +- Linux with KGet installed and running (or set to autostart) +- A Chromium-based browser: Chrome, Chromium, Brave, Vivaldi, or Edge +- `python3`, `dbus-send` +- `notify-send`, optional, for the completion notification +- `kwriteconfig6` (KDE Frameworks), optional, silences KGet's own duplicate + notification + +Install everything on your distro: + +**Fedora** +```bash +sudo dnf install kget python3 dbus-tools libnotify kf6-kconfig +``` + +**Arch / Manjaro** +```bash +sudo pacman -S kget python dbus libnotify kconfig +``` + +**Debian / Ubuntu / KDE neon** +```bash +sudo apt install kget python3 dbus-bin libnotify-bin kf6-kconfig-bin +``` + +**openSUSE** +```bash +sudo zypper install kget python3 dbus-1 libnotify-tools kconfig-tools +``` + +(`notify-send` and `kwriteconfig6` package names shift around between distro +versions. If a command above fails, drop that one package and search your +package manager for the binary name instead. Everything else still works +without them.) ## Install +1. Install the extension from the Chrome Web Store: **``** + *(placeholder, fill in once the listing is live)*. +2. Install the native messaging host that lets the extension talk to KGet. + Download and extract the latest release from the + [Releases page](https://github.com/andwati/kget-capture/releases), then + from inside that folder: + ```bash + ./install.sh + ``` +3. Open your browser's download settings (`chrome://settings/downloads`, + `brave://settings/downloads`, etc.) and turn **off** "Ask where to save + each file before downloading". Chrome shows this dialog itself, before the + extension gets a chance to intercept the download, so this one-time change + is required. + +`install.sh` registers the native host for every supported browser it finds +installed and prints any remaining setup warnings. + +### Building from source + +Contributing, or want to run an unreleased version? Load the extension +unpacked instead of step 1 above: + ```bash -git clone kget-capture +git clone https://github.com/andwati/kget-capture.git cd kget-capture ./install.sh ``` -`install.sh` registers a native messaging host for every supported browser it -finds installed, then prints the extension's fixed ID and next steps: - -1. Open `chrome://extensions` (or your browser's equivalent). -2. Enable **Developer mode** (top-right toggle). -3. Click **Load unpacked** and select this repo's `extension/` directory. -4. Confirm the loaded extension's ID matches the one `install.sh` printed. -5. Open `chrome://settings/downloads` (or your browser's equivalent, e.g. - `brave://settings/downloads`, `edge://settings/downloads`) and turn **off** - "Ask where to save each file before downloading". Chrome shows this dialog - itself, before the extension ever gets a chance to intercept the download — - no extension API can read or suppress it, so this one-time setting change - is required for captures to work without an extra prompt. +Then in `chrome://extensions`: enable **Developer mode**, click **Load +unpacked**, and select this repo's `extension/` directory. `install.sh` +prints the extension's fixed ID so you can confirm it loaded correctly. ## Usage @@ -64,44 +92,33 @@ finds installed, then prints the extension's fixed ID and next steps: ./uninstall.sh ``` -This removes the native messaging host registrations and the installed host -script. You'll still need to remove the unpacked extension yourself via -`chrome://extensions` — that step can't be scripted. +Removes the native messaging host registrations and installed host script. +Remove the extension itself via `chrome://extensions` (or the Chrome Web +Store listing); that step can't be scripted. ## Releases -Pushing a tag matching `v*.*.*` (e.g. `v1.0.0`) triggers a GitHub Actions -workflow ([.github/workflows/release.yml](.github/workflows/release.yml)) -that zips `extension/` and publishes it as a GitHub Release with -auto-generated release notes. Bump `"version"` in `extension/manifest.json` -before tagging so the packaged extension's version matches. - -```bash -git tag v1.0.0 -git push origin v1.0.0 -``` +Prebuilt releases are published on the +[Releases page](https://github.com/andwati/kget-capture/releases); each +`vX.Y.Z` tag push builds and publishes one automatically. ## Known limitations - **`blob:`/`data:`/`file:`/`filesystem:` URLs can't be captured.** There's - no real network URL to hand to KGet — this includes saving a page you - navigated to directly via `file://` (Ctrl+S on it is still a "download" as - far as Chrome is concerned) — so these downloads proceed normally through - Chrome (a console warning is logged in the extension's service worker). + no real network URL to hand to KGet, so these proceed normally through + Chrome. - **Auto-capture has a brief head start.** Manifest V3 removed blocking `webRequest`, so Chrome begins the download before the extension can cancel it. A small/partial temp file may transiently appear before it's erased. - **No editable dialog.** Captures start immediately with no chance to - rename the file or pick a different folder beforehand — rename/move it - afterward in KGet or your file manager if needed. This is intentional: KGet - only skips its interactive "New Download" dialog when given a real - destination path up front, so instant capture and an editable prompt are - mutually exclusive given KGet's D-Bus API. -- **Chrome may still show its own "Save As" dialog** if you skipped step 5 of - Install above — see there for why and how to fix it. -- **KGet must already be running.** If it's not, captures fail silently from - the user's perspective — check the service worker console for the actual - error (see Troubleshooting). + rename the file or pick a folder beforehand: KGet only skips its + interactive dialog when given a destination path up front, so instant + capture and an editable prompt are mutually exclusive. +- **Chrome may still show its own "Save As" dialog** if you skipped step 3 of + Install above. +- **KGet must already be running.** If it's not, captures fail silently; + check the service worker console for the actual error (see + Troubleshooting). ## Troubleshooting @@ -118,19 +135,17 @@ git push origin v1.0.0 ``` If this fails with `ServiceUnknown`, KGet isn't running. - **Download-complete notification not showing?** Confirm `notify-send` is - installed (`command -v notify-send`) — without it, `kget_capture_host.py` + installed (`command -v notify-send`); without it, `kget_capture_host.py` skips the notification entirely rather than erroring. Otherwise, check that the transfer actually reached 100%: `kget_capture_host.py` polls `org.kde.kget.transfer.percent` on the new transfer's D-Bus object path (e.g. `/KGet/Transfers/9`, printed by the `addTransfer` call above) until it - hits 100, so a stuck/erroring transfer never fires one. Note this - notification is separate from KGet's own built-in "Download Finished" - event — `install.sh` disables that one (`kwriteconfig6 --file knotifyrc - --group "Event/kget/finished" --key Action None`) because KGet only fires - it for transfers it observed in a non-finished state at least once, so it - silently skips small/fast downloads that complete before that first - observation. + hits 100, so a stuck/erroring transfer never fires one. This notification + is separate from KGet's own built-in "Download Finished" event. + `install.sh` disables that one because KGet only fires it for transfers it + observed in a non-finished state at least once, so it silently skips + small/fast downloads that complete before that first observation. ## License -MIT — see [LICENSE](LICENSE). +MIT, see [LICENSE](LICENSE).