SaraSort/README.md

# SaraSort

A GUI for configuring [SaraSortd](https://git.srhtnin.garden/sarah/SaraSortd), built with Flet.
SaraSort doesn't sort anything itself: SaraSortd stays the backend, and SaraSort reads and edits its
configs and controls its systemd user service (or, without systemd, the service SaraSuite runs
for it: see SaraSuite's README).

Needs SaraSortd **7.1** or newer for arrows with their own patterns (per-entry `ValidInputDirs`).

## Pages

- **Flow**: every input (red), output (blue) and both (purple) directory as a box, with arrows labelled
  with the file patterns that travel along them. Click a label to see all of its patterns. Boxes start in
  columns and can be dragged (positions are kept in `Layout.toml`).
  In **Edit mode**: click a directory, then the one it should sort into, and type the patterns. Each
  pattern becomes its own `[[Files]]` entry in the output's config, with its own `ValidInputDirs`, and
  the other settings come from `OutputDirConf.toml` (the template). Click a label to edit its rules
  (pattern, NewFileName, case-sensitive, overwrite), add or remove patterns, remove the arrow, or save it
  as a template. A rule other inputs use too is split when you change it, so only this arrow changes.
  The bin on a box deletes the directory from SaraSortd: it leaves GlobalConf.toml and other outputs'
  rules, and its config and history files are deleted. The folder and its files stay.
  **Right-click** works like in SaraFem, in or out of edit mode. A box: Details, Connect From Here, Edit
  Config, Test a File, Make It an Input/Output Too, Open Folder, Copy Path, Delete. An arrow's label: Show
  Patterns, Edit Rules, Add Patterns, Copy Patterns, Save as Template, Edit Output Config, Remove Arrow.
  The background: Add Directory, Edit Mode, Tidy Layout, Reload.
- **Service**: running/stopped, start/stop/restart, start on login, SaraSortd's version (and the
  SaraSuite install it came from), and its logs: its own log files, or the systemd journal (the
  service log, where SaraSuite runs it: Windows, and Linux without systemd).
- **Configs**: `GlobalConf.toml`, the two templates and every directory's own config, as a form (with
  help text, a live NewFileName preview and variable buttons) or as raw TOML. Saving only writes the
  values you changed, so SaraSortd's own NextNum/NextChar/LastFile updates aren't overwritten.
- **Templates**: ready-made connections (Pictures, Videos, Music, Documents, Archives, Git repositories,
  Logs, 3D printing, Installers, Backup copy) that only ask for an input and an output. Your own templates
  are TOML files in `~/.config/SaraSuite/SaraSort/Templates/`.
- **Tools**: warnings about the setup (Unset values, version mismatches, outputs nothing reaches, inputs
  without outputs, entries shadowed by a catch-all), a filename tester that shows where a file would go
  and why, and the files in FailedDir with a retry button.

The gear button opens **Settings**, laid out like SaraFem's and SaraSuite's: the shared SaraSuite
appearance and export/import (same file format as SaraFem's, `[SaraSuite]` plus `[SaraSort]`), SaraSort's
own settings, and where SaraSortd lives. The SaraSortd tab also exports and imports all of SaraSortd's
configs as one file: GlobalConf.toml, both templates and every directory's own config, comments included.
Importing backs the current configs up to `~/.config/SaraSuite/SaraSort/Backups/` first. If directories it
uses don't exist, you can cancel, give any of them a new path (the configs and arrows follow), or have them
made. The same tab sets where SaraSortd keeps directory configs (7.2): inside each directory, or all
in one folder like SaraTag's Lexicons (`DirConfDir`, e.g. `Pictures_CatsConfig.toml`), and moves the
existing configs and history files there so no rules are lost. Single directories can also get their own
file through `[DirConfs]` in GlobalConf.toml, which SaraSort reads and edits like any other config.
Run as an AppImage, the header also has an "Add to app menu"
button, like SaraSuite's.

After a change to `GlobalConf.toml` (new inputs or outputs) SaraSort restarts SaraSortd, since SaraSortd
only reads that file when it starts. That can be turned off in Settings.

## Where things live

| Path | What |
| --- | --- |
| `~/.config/SaraSuite/Config.toml` | shared SaraSuite settings (theme, font, title bar) |
| `~/.config/SaraSuite/Themes/` | the themes |
| `~/.config/SaraSuite/SaraSort/Config.toml` | SaraSort's own settings |
| `~/.config/SaraSuite/SaraSort/Layout.toml` | where flowchart boxes were dragged to |
| `~/.config/SaraSuite/SaraSort/Templates/` | your own templates |
| `~/.config/SaraSuite/SaraSort/Backups/` | SaraSortd's configs from before each import |
| `~/.config/SaraSuite/SaraSortd/` | SaraSortd's configs, as SaraSuite installs them (changeable in Settings) |

## Running and building

- From source: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`, then `Packaging/Launch.sh`.
- AppImage: `Packaging/BuildAppImage.sh` builds `dist/SaraSort-x86_64.AppImage` (PyInstaller one-file
  build + `appimagetool`, like SaraSuite's and SaraFem's).
- SaraSuite: `Packaging/SaraSuite/` is a ready manifest (`Manifest.toml` + `Templates/`) to copy into
  SaraSuite's `Programs/SaraSort/`.

## Files

| File | What |
| --- | --- |
| `Main.py` | window, navigation |
| `Core.py` | paths, palette/theme, settings, export/import |
| `Sortd.py` | SaraSortd's configs: the graph, edits, the filename simulator, warnings |
| `Service.py` | systemctl and journalctl |
| `Templates.py` | built-in and your own templates |
| `Settings.py` | the Settings dialog |
| `SortdTransfer.py` | exporting/importing all of SaraSortd's configs |
| `Widgets.py` | the shared App context and small controls |
| `*Page.py` | one per page |