Freebuff Focus for Desktop - Linux
====================================

Tool version 1.8.3. Blocks the ads Freebuff Desktop renders from the
orchestrator process it ships inside its own application directory.

WHAT IS IN THIS ZIP
-------------------

  freebuff-focus-linux.sh   the tool
  INSTALL-linux.txt           this file

Nothing else, and nothing to install first. It is a POSIX shell script that uses
the perl and pgrep your distribution already has - both are present on a normal
desktop install. `doctor` says so if either is missing.


BEFORE YOU START: THE APPIMAGE RULE
-----------------------------------

Freebuff for Linux ships as an AppImage: one executable holding a read-only
filesystem. There is no file inside it to patch, and this tool will never write
to your download - it cannot, and it does not try.

So it does the next best thing, which works out better in practice:

  1. it extracts the image using the runtime the image itself carries (no FUSE,
     no squashfs-tools, no root, nothing to install),
  2. it patches the extracted copy, which lives in
       ~/.local/share/freebuff-focus/freebuff-<version>/
  3. and it stops the image and starts that copy for you - or prints its AppRun
     path when there was nothing running to replace.

Your .AppImage is left exactly as it was - same bytes, same signature. Keep it as
the unpatched fallback: running it still shows ads, which is how you check the
difference.

If you point --app at an ordinary directory instead - an AppDir you extracted
yourself, or a system install such as /opt/Freebuff - it patches in place, exactly
like the macOS tool.


RUN IT
------

  sh freebuff-focus-linux.sh

That is `install`: it reports what it found, writes a pristine backup, patches,
and starts the patched copy (or prints its AppRun path, if Freebuff was closed).
Afterwards:

  ~/.local/share/freebuff-focus/freebuff-0.0.164/squashfs-root/AppRun

If it could not find your AppImage, pass it yourself:

  sh freebuff-focus-linux.sh install --app ~/Applications/Freebuff-0.0.164-linux-x86_64.AppImage

It looks in ~/Applications, ~/Downloads, ~/.local/bin, ~/bin, ~/Desktop, /opt,
/usr/local/bin and the current directory, for a file named *Freebuff*.AppImage.


FOCUS
-----

Three ways to ask, and only what ends them differs:

  sh freebuff-focus-linux.sh focus          quiet until you run unfocus
  sh freebuff-focus-linux.sh focus 25m      quiet until the deadline
  sh freebuff-focus-linux.sh focus session  quiet until Freebuff quits

All three patch the copy first, so a failed install is a failed focus. A plain
`focus` writes no deadline: closing Freebuff and opening it again keeps the ads
off, because the patched file is still on disk, and only `unfocus` restores it.

`focus 25m` - or 90m, 2h, 45, 45s - starts one small watcher, a detached `sh`,
that restores the original file when the deadline passes, so the next start of
the patched copy is ads-on again. `focus session` starts the same watcher waiting
on Freebuff itself: when that process exits, the original file goes back.

The watcher is the only thing this tool leaves running, and it writes nothing at
all if the file changed since the patch - a new AppImage or a fresh install makes
it stand down rather than overwrite. `unfocus` stops it, and so does a second
`focus`. `status` says which mode is on and what will end it.


AFTER YOU RUN IT
----------------

1. Start the patched copy, not the original image (the path is printed for you).
   The orchestrator is read once at launch, so the patch only takes effect on the
   next start.

2. Check what it loaded:

     sh freebuff-focus-linux.sh verify

   That waits for something to be running the patched file and then compares two
   times - when the patch was written, and when the running process started.
   Ctrl-C stops the wait at any time, and an interrupted wait prints no verdict.

3. After a Freebuff update, run `install` again. An update is a new AppImage, and
   the patched copy is left behind by it. For a newer version of this tool itself,
   run `freebuff-focusmode update` once it is installed.


INSTALL IT AS A COMMAND
-----------------------

Run this once and you stop naming a file:

  sh freebuff-focus-linux.sh setup

It copies the tool to ~/.local/share/freebuff-focus, writes
`freebuff-focusmode` into ~/.local/bin, and prints the one line to add that
folder to your PATH if it is not there already. `setup --add-path` edits your
shell rc instead of telling you to. After that:

  freebuff-focusmode status     report what is applied - changes nothing
  freebuff-focusmode focus      keep the ads off until you end it
  freebuff-focusmode focus 25m  keep them off until the deadline
  freebuff-focusmode focus session  keep them off until Freebuff quits
  freebuff-focusmode unfocus    end it now, and bring the ads back
  freebuff-focusmode update     fetch a newer tool, replace this copy, patch again
  freebuff-focusmode uninstall  remove the command; the patch stays

The one-liner on the install page does this for you.


OTHER COMMANDS
--------------

  sh freebuff-focus-linux.sh status    report what is applied - changes nothing
  sh freebuff-focus-linux.sh scan      list every anchor this build has - changes nothing
  sh freebuff-focus-linux.sh revert    restore the pristine backup
  sh freebuff-focus-linux.sh doctor    environment report, for a bug report

`status` and `scan` extract a temporary copy and remove it when they finish, so
they never leave anything behind. `install`, `revert` and `verify` use the copy
under ~/.local/share/freebuff-focus, which is the one they can agree on.


WHAT IT DOES, AND WHAT IT DOES NOT
----------------------------------

It forces the ad auction to return no ads and cuts the ad client off before it
sends, at two anchors in the orchestrator. Nothing else in the file changes.

It refuses to touch a build whose anchors it does not recognise, prints the counts
it saw, and leaves the file alone - a Freebuff release that renames a function is
a refusal to read, not a half-patched app. `scan` prints every candidate site, so
re-anchoring is a report to read instead of a dead end.

It never asks for a password, never uses sudo, and never changes a file outside
the copy it manages.


IF SOMETHING GOES WRONG
-----------------------

Nothing is written until every anchor is counted and matched. If a write does not
check out afterwards, the pristine backup goes straight back.

A system install under /opt or /usr belongs to root, so patching it needs root.
The tool says that rather than escalating by itself - and the AppImage path above
never needs it.

Get the original back:

  sh freebuff-focus-linux.sh revert

Full source, issues and the macOS and Windows tools:
  https://freebuff-focusmode.vercel.app

MIT licensed. See LICENSE.
