her-sync

Linux-native Sync-Tool für Agent-Share-Filesysteme (BDE, Email, CalDAV).
CLI-Befehl: her

Installation

pipx install "her-sync[watch]"

Aus Git:

pipx install --force "git+https://gitea.example.com/you/her-sync@main#egg=her-sync[watch]"

Entwicklung: pip install -e ".[watch,dev]"

Konfiguration

~/.her/

~/.her/
├── config.yml
├── profiles/bde-work/
│   ├── profile.yml       # share, event_handlers
│   ├── crm.yml           # bde: { ... }   (CRM/BDE-API)
│   ├── mail.yml          # email: { ... }
│   ├── calendar.yml      # caldav: { ... }
│   ├── files.yml         # files: { collections: [...] }
│   └── local.yml         # optional: Overrides (alphabetisch später = gewinnt)
├── state/bde-work/
└── share-bde/            # optional — Share kann auch woanders liegen

Alle .yml-Dateien im Profilordner werden alphabetisch geladen und deep-gemergt. Welches Plugin aktiv ist, ergibt sich nur aus dem YAML-Key (bde:, email:, caldav:, files:) — der Dateiname spielt keine Rolle. Fehlender Key = Plugin deaktiviert.

# profile.yml — Querverdrahtung zwischen Plugins
event_handlers:
  email:
    changed:
      debounce_seconds: 10
      handlers:
        - email: { command: sync }
        - caldav: { command: sync }

# local.yml — optional, überschreibt Teile aus calendar.yml o.ä.
caldav:
  months_past: 6

her profile init bde-work
her profile migrate-env --env-file .env --name bde-work
her secrets set bde-work/bde-password
her --profile bde-work status

CLI

her profile list|show|init|migrate-env|validate
her secrets set|delete|test
her daemon run|start|stop|status
her status

her bde collect cashflows
her bde collect cashflow-history --force
her bde apply cost-centers --dry-run

her files copy                 # alle Sammlungen kopieren
her files copy receipts        # nur eine Sammlung
her files move receipts        # verschieben statt kopieren

her email sync
her caldav ls
her caldav sync

Files-Plugin

Generisches Kopieren von Quellordnern ins Share-FS. Jede Sammlung definiert source, dest (relativ zum Share-Root oder absolut), optionale allow/deny-Glob-Muster und optional flat: true (nur Dateiname im Ziel, ohne Unterordner).

files:
  enabled: true
  collections:
    - name: receipts
      source: ~/Documents/Belege/incoming
      dest: inbox/receipts
      flat: true
      allow: ["*.pdf", "*.png", "*.jpg"]
      deny: ["*.tmp", "archiv/**"]

Paketstruktur

src/her_sync/
├── cli.py, profile.py, runtime.py, config.py   # Root: CLI + Profile + Facade
├── share_fs/layout.py                          # Share-Pfade (Agent-Vertrag)
├── io/paths.py                                 # Shared Pfad-Hilfen
├── events/                                     # Event-Orchestrierung (Daemon)
└── plugins/
    ├── bde/          # CRM: api/, collect/, apply/, schemas, config
    ├── files/        # Datei copy/move, config, collections
    ├── email/        # Mail-Sync (mbox/msf), filters, watcher
    └── caldav/       # Kalender-Sync, client, filters

Daemon

Start/Stop/Autostart laufen über systemd user — die Unit wird beim ersten her daemon start automatisch installiert (kein separates Install-Skript nötig).

her daemon start --profile bde-work              # starten
her daemon start --profile bde-work --autostart  # + Autostart beim Login
her daemon stop --profile bde-work
her daemon enable --profile bde-work           # nur Autostart an
her daemon disable --profile bde-work          # nur Autostart aus
her daemon status --profile bde-work           # Status + Log-Befehle

# Debug im Vordergrund (ohne systemd):
her daemon run --profile bde-work

Logs (Ausgabe auch bei daemon start / daemon status):

journalctl --user -u her@bde-work.service -f

Release (Repo-Checkout)

her secrets set release/her-pypi-token   # einmalig lokal
./scripts/her-release release --bump patch --pypi
pipx upgrade "her-sync[watch]"
# Falls Version nicht gefunden: python3 -m pip cache purge
#   pipx install --force --pip-args='--no-cache-dir' "her-sync[watch]"

Details: deploy/DISTRIBUTION.md