SaraSuite/README.md

# SaraSuite

Installs, updates and removes Sara programs (SaraSortd, SaraSort, SaraFem, SaraTag and the SaraView desktop client).
It's one AppImage file: download it, run it, pick a program.

- **Install**: downloads the program's latest commit from its git repo, copies it into
  `~/.local/share/SaraSuite/Programs/<Name>/` with its own Python venv, places its configs in
  `~/.config/SaraSuite/<Name>/`, and writes its desktop entries, systemd user units, D-Bus
  services and so on.
- **Update**: shown when the repo has a newer commit. Program files and integration files are
  replaced; configs are *merged*: your edits always win, defaults you never touched follow the
  new version, new keys are added (see `ConfigMerge.py`).
- **Remove**: takes out everything the install placed (it's all recorded in a receipt) plus
  everything the program made by itself while running. Configs are only removed when
  "Remove configs" is ticked. Your own files are never removed: folders that might hold them
  are only removed when empty. Files that existed before SaraSuite installed over them are put back.

## Sources

Programs come straight from git over HTTPS, no `git` binary needed: the latest commit is read
from `<repo>.git/info/refs` and the files from `<repo>/archive/<commit>.tar.gz`, which GitHub and
Gitea both serve the same way. Repos must be public (no login support yet).

The host is one setting in `~/.config/SaraSuite/SaraSuite/Config.toml`; manifests refer to it as
`{GitHost}`. It defaults to the Gitea on SpineS:

```toml
GitHost = "https://git.srhtnin.garden/sarah"
```

The only thing a program needs from the system is `python3` (for its venv).

## Shared settings

Settings every SaraSuite program shares live in `~/.config/SaraSuite/Config.toml`:

```toml
Theme = "CatppuccinMocha"        # a file in ~/.config/SaraSuite/Themes/
FontFamily = "Fixedsys Excelsior" # the bundled font, or any installed font family
HideWindowTitleBar = false
```

Each program's own `~/.config/SaraSuite/<Program>/Config.toml` has the same three keys plus
`UseSharedSettings` (default `true`). With it on, the program reads the shared file; with it
off, it uses its own values instead. Both SaraSuite (the gear button, Shared and SaraSuite
tabs) and SaraFem (its Settings, SaraSuite and General tabs) can edit them. Whichever program
starts first creates the shared file from its own values.

## SaraSuite's own settings

The gear button also holds the git host and, in one tab per program, what that program's
install dialog starts with: which option boxes are ticked and the default answers (e.g.
SaraSortd's root folder). They're stored in `~/.config/SaraSuite/SaraSuite/Config.toml` as
`[OptionDefaults.<Program>]` and `[AnswerDefaults.<Program>]`, and override the manifest's
defaults.

## Changing options after installing

Installed programs with options (e.g. SaraFem's file picker) get an **Options** button. Turning
an option off takes out what it placed and puts back any file it had replaced; turning it on
places it. It reapplies the installed commit, so the program itself isn't updated. The
**Update** button only shows up when there's an update (or a broken install to repair).

## Running and building

- AppImage: `Packaging/BuildAppImage.sh` builds `dist/SaraSuite-x86_64.AppImage`
  (PyInstaller one-file build + `appimagetool`, like SaraFem's). When run as an AppImage,
  the header has an "Add to app menu" button.
- From source: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`, then
  `Packaging/Launch.sh`.
- Without a desktop (e.g. a server), the same file works from a terminal:

  ```
  SaraSuite-x86_64.AppImage list
  SaraSuite-x86_64.AppImage install SaraSortd --set RootDir=~/Sorting --option Autostart=on
  SaraSuite-x86_64.AppImage update SaraSortd
  SaraSuite-x86_64.AppImage options SaraFem                         # list them
  SaraSuite-x86_64.AppImage options SaraFem --option FilePicker=off
  SaraSuite-x86_64.AppImage remove SaraSortd [--configs] [--keep-runtime]
  ```

## Where things live

| Path | What |
| --- | --- |
| `~/.local/share/SaraSuite/Programs/<Name>/` | installed program (`App/`) and its `.venv/` |
| `~/.local/share/SaraSuite/Receipts/<Name>.toml` | everything the install placed |
| `~/.local/share/SaraSuite/Pristine/<Name>/` | the default configs as last installed (the merge base) |
| `~/.local/share/SaraSuite/Backups/<Name>/` | files that were moved aside, and configs from before a merge |
| `~/.cache/SaraSuite/Downloads/` | downloaded source, removed after installing |
| `~/.config/SaraSuite/<Name>/` | the program's configs |

## Adding a program

Make `Programs/<Name>/Manifest.toml`. Templates go in `Programs/<Name>/Templates/`.
Manifests are bundled into the AppImage, so a new or changed manifest means rebuilding it
(installed programs then show an update, even without a new commit).
Anything the manifest can't describe goes in an optional `Programs/<Name>/Hooks.py`.

Targets, templates and `Set` values can use `{Variables}`: `Name`, `GitHost`, `Home`, `ConfigHome`,
`DataHome`, `CacheHome`, `SystemdUserDir`, `ApplicationsDir`, `DBusServicesDir`, `ProgramDir`,
`AppDir`, `Python` (the venv's python), `ConfigDir`, `DesktopName` (e.g. `COSMIC`),
`Desktop` (e.g. `cosmic`), plus every Question's `Id`.

```toml
Name = "Example"
Description = "Shown on the program's card."
Parent = "SaraSortd"            # optional: listed (indented) under that program
RestartUnits = ["xdg-desktop-portal.service"]  # try-restarted after install/update/remove

[Version]                      # optional, shown on the card
File = "Example.py"
Pattern = 'Version = "([^"]+)"'

[Source]
Git = "{GitHost}/Example"
Branch = "main"                            # optional, default: the repo's default branch
Include = ["*.py", "assets/**"]            # default: everything
Exclude = ["Packaging"]                    # .git, .venv, build, ... are always excluded

[Python]
RequirementsFile = "requirements.txt"      # or: Requirements = ["toml"]

[[Questions]]                  # asked at install time, usable as {RootDir}
Id = "RootDir"
Prompt = "Folder to use"
Default = "~/Somewhere"
Kind = "Path"                  # expanded to an absolute path

[[Options]]                    # checkboxes at install time
Id = "Autostart"
Label = "Start on login"
Default = true

[[Configs]]                    # placed once, merged on updates
Source = "Conf.toml"           # in the source checkout
Target = "{ConfigDir}/Conf.toml"
Set = { "Paths.RootDir" = "{RootDir}" }

[[Templates]]                  # owned by SaraSuite, rewritten on every update
Source = "Example.service"     # in Templates/
Target = "{SystemdUserDir}/Example.service"
Option = "Autostart"           # optional: only while the option is ticked
Root = false                   # true: outside $HOME, written through pkexec
Executable = false

[[Services]]                   # systemd --user units, enabled + started
Unit = "Example.service"
Option = "Autostart"

[[IniEdits]]                   # one key in a file SaraSuite doesn't own; restored on removal
File = "{ConfigHome}/mimeapps.list"
Section = "Default Applications"
Key = "inode/directory"
Value = "Example.desktop"

[[Leftovers]]                  # made by the program itself, only touched on removal
Path = "{CacheHome}/Example"   # globs allowed
Kind = "Runtime"               # or "Config"
Mode = "Remove"                # or "IfEmpty"
Note = "thumbnail cache"
```

`Hooks.py` can define `Leftovers(Context: dict) -> list[Manifests.Leftover]` for leftovers
that depend on the program's own config (see `Programs/SaraSortd/Hooks.py`).