safekeep 0.2.0__tar.gz

safekeep-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foxhound87
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

safekeep-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: safekeep
+Version: 0.2.0
+Summary: Selective always-on backups for macOS: fswatch-driven copy of allow-listed files, never deletes
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/foxhound87/safekeep
+Project-URL: Repository, https://gitlab.com/foxhound87/safekeep
+Keywords: backup,macos,fswatch,sync,allow-list,launchd
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# safekeep
+
+**Selective always-on backups for macOS**: watches source folders with
+[fswatch](https://github.com/emcrisostomo/fswatch) and copies only the files you
+chose to their destinations — an **allow-list** model that **never deletes**
+anything in the backup (a file removed or renamed at the source stays in the
+backup).
+
+## Features
+
+- **Allow-list**: a file is copied only if it matches at least one `include:`;
+  no match → not copied. Unmatched directories are still traversed, while
+  directories with an *excluded* verdict are pruned together with their subtree.
+- **Atomic copy, never a half-written file**: the temp file lives in the
+  destination's own directory, followed by `fsync` + `os.replace` → a reader
+  sees either the old file or the new one, never a partial copy.
+- **Reconcile** at startup, every 24h, on remount, and on `sync-once`: copies
+  whatever differs by size/mtime, idempotently — lost events, crashes and reboots
+  don't matter, the next reconcile brings everything back in sync.
+- **Unmounted volumes**: missing destination → `pending` state with exponential
+  backoff (1s → 60s cap), then a reconcile once the mount is back.
+- **launchd at boot**: an agent with `RunAtLoad` + `KeepAlive` keeps the process
+  alive and restarts it if it dies.
+- **`.sync` carries rules only, destinations live only in `~/.safekeep`**: a
+  `.sync` file can neither add nor remove destinations (a `dest:` line is an
+  invalid line), so a repo cloned from a third party can't redirect the backup
+  somewhere else.
+
+## Installation
+
+```bash
+pipx install safekeep     # recommended for a CLI
+# or
+pip install safekeep
+```
+
+**Requirements**: macOS, Python >= 3.9 and
+[fswatch](https://github.com/emcrisostomo/fswatch):
+
+```bash
+brew install fswatch
+```
+
+The **launchd agent** (daemon at boot) is installed from a checkout of this
+repository with `./install.sh` — not from the wheel — see
+[Agent (launchd)](#agent-launchd) below.
+
+## Agent (launchd)
+
+```bash
+git clone https://gitlab.com/foxhound87/safekeep.git
+cd safekeep
+
+# only external dependency, if not installed yet
+brew install fswatch
+
+# copies the example into ~/.safekeep, renders the plist, runs preflight checks
+bash install.sh
+```
+
+Then:
+
+1. Fill `~/.safekeep` with your real `dest:` entries — and, optionally, `source:`
+   (the example ships with placeholders — see
+   [`examples/safekeep.example`](examples/safekeep.example));
+2. drop a `.sync` file in the root of every project you want to follow (see
+   [`examples/sync.example`](examples/sync.example)); a directory **without** a
+   `.sync` is not tracked;
+3. load the agent:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.safekeep.agent.plist
+# unload with: launchctl bootout gui/$(id -u)/com.safekeep.agent
+```
+
+Once you have granted TCC/FDA (Full Disk Access) permissions to the Python
+interpreter and to `fswatch`, run `safekeep doctor` for diagnostics.
+
+## Quickstart
+
+`~/.safekeep` (the only place where destinations live):
+
+```bash
+# observed roots: only directories containing a .sync are followed
+source: ~/Code
+source: ~/Projects
+
+# destination for ALL projects
+dest: ~/Backup/safekeep
+
+# relative (default): <dest>/<path relative to the source root>
+#   ~/Code/myapp/docs/a.md → ~/Backup/safekeep/myapp/docs/a.md
+layout: relative
+
+log_level: info
+```
+
+`source:` is **optional**. With it present (source mode) the watched roots are
+exactly those entries, as always. Without it safekeep switches to
+**auto-discovery**: it scans `$HOME` for `.sync` files (skipping hidden
+directories, `Library`, `.Trash`, `.cache`, `node_modules`, `.git`, `.venv`,
+`__pycache__`, `venv`), watches `$HOME`, and picks up any `.sync` created after
+startup. `dest:` stays mandatory in both modes.
+
+`~/Code/myapp/.sync` (rules only, no destinations):
+
+```bash
+name: myapp
+
+# allow-list semantics: without these lines NOT A SINGLE file would be copied
+*.md
+.env
+!secrets/old.env      # ! = exclude
+```
+
+Rules can be written as bare gitignore-style lines — **the inverse of gitignore**:
+a line lists what to **copy**, not what to ignore (`*.md` includes markdown here,
+excludes it in a `.gitignore`), and a leading `!` turns it into an `exclude:`.
+Bare lines share the same ordered list as the explicit `include:`/`exclude:`
+keys, so last-match-wins works the same way (see
+[`examples/sync.example`](examples/sync.example)).
+
+Dry run first, then start the daemon:
+
+```bash
+safekeep sync-once --dry-run   # prints what would be copied, copies nothing
+safekeep run                   # daemon: watch + copy (foreground)
+```
+
+## CLI commands
+
+```
+safekeep <command> [--config PATH] [-v]
+```
+
+| Command | What it does |
+|---|---|
+| `run` | daemon: initial reconcile, fswatch loop, event dispatch, 24h timer |
+| `sync-once [--dry-run] [--project PATH] [--prune]` | a single pass: walks the source and copies whatever differs (`--dry-run` only prints what it would copy; `--prune` also removes dest files whose source still exists but is no longer included) |
+| `status` | read-only: config, sources, discovered projects with N rules, destination states |
+| `doctor` | diagnostics: config, fswatch, TCC, launchd plist — exits non-zero if a fatal check fails |
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Stdlib (`unittest`) suite, zero dependencies: 156 tests covering the matcher,
+config, atomic copy, volumes, daemon, auto-discovery and CLI. `fswatch` is not
+needed to run the tests.
+
+## Documentation
+
+Everything in detail (config format, pattern semantics, event → sync flow,
+atomic copy, launchd, edge cases) lives in [`SPEC.md`](SPEC.md); commented
+examples in [`examples/`](examples/).
+
+## License
+
+MIT — see [LICENSE](LICENSE)

safekeep-0.2.0/README.md

@@ -0,0 +1,161 @@
+# safekeep
+
+**Selective always-on backups for macOS**: watches source folders with
+[fswatch](https://github.com/emcrisostomo/fswatch) and copies only the files you
+chose to their destinations — an **allow-list** model that **never deletes**
+anything in the backup (a file removed or renamed at the source stays in the
+backup).
+
+## Features
+
+- **Allow-list**: a file is copied only if it matches at least one `include:`;
+  no match → not copied. Unmatched directories are still traversed, while
+  directories with an *excluded* verdict are pruned together with their subtree.
+- **Atomic copy, never a half-written file**: the temp file lives in the
+  destination's own directory, followed by `fsync` + `os.replace` → a reader
+  sees either the old file or the new one, never a partial copy.
+- **Reconcile** at startup, every 24h, on remount, and on `sync-once`: copies
+  whatever differs by size/mtime, idempotently — lost events, crashes and reboots
+  don't matter, the next reconcile brings everything back in sync.
+- **Unmounted volumes**: missing destination → `pending` state with exponential
+  backoff (1s → 60s cap), then a reconcile once the mount is back.
+- **launchd at boot**: an agent with `RunAtLoad` + `KeepAlive` keeps the process
+  alive and restarts it if it dies.
+- **`.sync` carries rules only, destinations live only in `~/.safekeep`**: a
+  `.sync` file can neither add nor remove destinations (a `dest:` line is an
+  invalid line), so a repo cloned from a third party can't redirect the backup
+  somewhere else.
+
+## Installation
+
+```bash
+pipx install safekeep     # recommended for a CLI
+# or
+pip install safekeep
+```
+
+**Requirements**: macOS, Python >= 3.9 and
+[fswatch](https://github.com/emcrisostomo/fswatch):
+
+```bash
+brew install fswatch
+```
+
+The **launchd agent** (daemon at boot) is installed from a checkout of this
+repository with `./install.sh` — not from the wheel — see
+[Agent (launchd)](#agent-launchd) below.
+
+## Agent (launchd)
+
+```bash
+git clone https://gitlab.com/foxhound87/safekeep.git
+cd safekeep
+
+# only external dependency, if not installed yet
+brew install fswatch
+
+# copies the example into ~/.safekeep, renders the plist, runs preflight checks
+bash install.sh
+```
+
+Then:
+
+1. Fill `~/.safekeep` with your real `dest:` entries — and, optionally, `source:`
+   (the example ships with placeholders — see
+   [`examples/safekeep.example`](examples/safekeep.example));
+2. drop a `.sync` file in the root of every project you want to follow (see
+   [`examples/sync.example`](examples/sync.example)); a directory **without** a
+   `.sync` is not tracked;
+3. load the agent:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.safekeep.agent.plist
+# unload with: launchctl bootout gui/$(id -u)/com.safekeep.agent
+```
+
+Once you have granted TCC/FDA (Full Disk Access) permissions to the Python
+interpreter and to `fswatch`, run `safekeep doctor` for diagnostics.
+
+## Quickstart
+
+`~/.safekeep` (the only place where destinations live):
+
+```bash
+# observed roots: only directories containing a .sync are followed
+source: ~/Code
+source: ~/Projects
+
+# destination for ALL projects
+dest: ~/Backup/safekeep
+
+# relative (default): <dest>/<path relative to the source root>
+#   ~/Code/myapp/docs/a.md → ~/Backup/safekeep/myapp/docs/a.md
+layout: relative
+
+log_level: info
+```
+
+`source:` is **optional**. With it present (source mode) the watched roots are
+exactly those entries, as always. Without it safekeep switches to
+**auto-discovery**: it scans `$HOME` for `.sync` files (skipping hidden
+directories, `Library`, `.Trash`, `.cache`, `node_modules`, `.git`, `.venv`,
+`__pycache__`, `venv`), watches `$HOME`, and picks up any `.sync` created after
+startup. `dest:` stays mandatory in both modes.
+
+`~/Code/myapp/.sync` (rules only, no destinations):
+
+```bash
+name: myapp
+
+# allow-list semantics: without these lines NOT A SINGLE file would be copied
+*.md
+.env
+!secrets/old.env      # ! = exclude
+```
+
+Rules can be written as bare gitignore-style lines — **the inverse of gitignore**:
+a line lists what to **copy**, not what to ignore (`*.md` includes markdown here,
+excludes it in a `.gitignore`), and a leading `!` turns it into an `exclude:`.
+Bare lines share the same ordered list as the explicit `include:`/`exclude:`
+keys, so last-match-wins works the same way (see
+[`examples/sync.example`](examples/sync.example)).
+
+Dry run first, then start the daemon:
+
+```bash
+safekeep sync-once --dry-run   # prints what would be copied, copies nothing
+safekeep run                   # daemon: watch + copy (foreground)
+```
+
+## CLI commands
+
+```
+safekeep <command> [--config PATH] [-v]
+```
+
+| Command | What it does |
+|---|---|
+| `run` | daemon: initial reconcile, fswatch loop, event dispatch, 24h timer |
+| `sync-once [--dry-run] [--project PATH] [--prune]` | a single pass: walks the source and copies whatever differs (`--dry-run` only prints what it would copy; `--prune` also removes dest files whose source still exists but is no longer included) |
+| `status` | read-only: config, sources, discovered projects with N rules, destination states |
+| `doctor` | diagnostics: config, fswatch, TCC, launchd plist — exits non-zero if a fatal check fails |
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Stdlib (`unittest`) suite, zero dependencies: 156 tests covering the matcher,
+config, atomic copy, volumes, daemon, auto-discovery and CLI. `fswatch` is not
+needed to run the tests.
+
+## Documentation
+
+Everything in detail (config format, pattern semantics, event → sync flow,
+atomic copy, launchd, edge cases) lives in [`SPEC.md`](SPEC.md); commented
+examples in [`examples/`](examples/).
+
+## License
+
+MIT — see [LICENSE](LICENSE)

safekeep-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+# Packaging per PyPI: package stdlib-only, un solo console script.
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "safekeep"
+dynamic = ["version"]
+description = "Selective always-on backups for macOS: fswatch-driven copy of allow-listed files, never deletes"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+keywords = ["backup", "macos", "fswatch", "sync", "allow-list", "launchd"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Archiving :: Backup",
+]
+# zero runtime dependencies: solo stdlib (fswatch è un binario esterno)
+
+[project.urls]
+Homepage = "https://gitlab.com/foxhound87/safekeep"
+Repository = "https://gitlab.com/foxhound87/safekeep"
+
+[project.scripts]
+safekeep = "safekeep.cli:main"
+
+[tool.setuptools]
+# NO auto-discovery: bin/ e tests/ farebbero errore di build
+packages = ["safekeep"]
+
+[tool.setuptools.dynamic]
+version = {attr = "safekeep.__version__"}

safekeep-0.2.0/safekeep/__init__.py

@@ -0,0 +1,6 @@
+"""safekeep — motore di backup event-driven per macOS (vedi SPEC.md)."""
+import logging
+
+logging.getLogger('safekeep').addHandler(logging.NullHandler())
+
+__version__ = '0.2.0'

safekeep-0.2.0/safekeep/cli.py

@@ -0,0 +1,272 @@
+"""CLI di safekeep: `run`, `sync-once`, `status` e `doctor` (SPEC.md §9).
+
+Entry point del package (`safekeep.cli:main`): `bin/safekeep.py` è solo lo
+shim che usano launchd e i test.
+"""
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+
+from safekeep.config import ConfigError, discover_projects, parse_sync
+from safekeep.copier import TMP_INFIX
+from safekeep.daemon import Daemon, setup_logging
+from safekeep.volumes import dest_state
+
+# Radice del repo quando si gira da checkout; in un install pip punta altrove
+# (site-packages) e i riferimenti a file del repo degradano (vedi cmd_doctor).
+REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+EXAMPLE = os.path.join(REPO, 'examples', 'safekeep.example')
+REPO_URL = 'https://gitlab.com/foxhound87/safekeep'
+
+
+def build_parser():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument('--config', metavar='PATH',
+                        help='config globale (default: ~/.safekeep)')
+    common.add_argument('-v', action='store_true', help='log verboso (debug)')
+
+    parser = argparse.ArgumentParser(
+        prog='safekeep',
+        description='safekeep — backup event-driven per macOS (vedi SPEC.md)')
+    sub = parser.add_subparsers(dest='comando', required=True)
+    sub.add_parser('run', parents=[common],
+                   help='daemon: reconcile iniziale + watch fswatch + dispatch eventi + timer 24h')
+    once = sub.add_parser('sync-once', parents=[common],
+                          help='un singolo passaggio: walk sorgente, copia ciò che differisce, esce')
+    once.add_argument('--project', metavar='PATH',
+                      help='solo questo progetto (path della root o name)')
+    once.add_argument('--dry-run', action='store_true',
+                      help='stampa cosa copierebbe, senza copiare')
+    once.add_argument('--prune', action='store_true',
+                      help='rimuove dalla dest i file il cui sorgente esiste ancora ma '
+                           'non è più incluso dal matcher (default: mai cancellare)')
+    sub.add_parser('status', parents=[common],
+                   help='config, progetti e stato delle dest — sola lettura')
+    sub.add_parser('doctor', parents=[common],
+                   help='diagnostica: config, fswatch, TCC, plist — exit ≠ 0 se un check fatale fallisce')
+    return parser
+
+
+def cmd_sync_once(args):
+    daemon = Daemon(args.config)
+    daemon.load_config()
+    setup_logging('debug' if args.v else daemon.cfg.log_level)
+    daemon.validate_dests()               # CR-02: dest dentro source/$HOME → exit ≠ 0
+    daemon.load_projects()
+    rows = daemon.sync_once(dry_run=args.dry_run, only=args.project,
+                            prune=args.prune)
+    if args.project and not rows:
+        print(f'progetto non trovato: {args.project}', file=sys.stderr)
+        return 1
+    if not rows:
+        print('nessun progetto trovato (nessun .sync scoperto)', file=sys.stderr)
+    for project, stats, absent in rows:
+        if args.dry_run:
+            for src, dst in stats.get('pianificati', []):
+                print(f'  {src} -> {dst}')
+        verb = 'da copiare' if args.dry_run else 'copie'
+        line = (f'{project.name}: {stats.get("copiati", 0)} {verb}, '
+                f'{stats.get("skippati", 0)} già aggiornati, '
+                f'{stats.get("esclusi", 0)} esclusi, '
+                f'{stats.get("errati", 0)} errori, dest assenti: {absent}')
+        if args.prune:
+            verb = 'da rimuovere' if args.dry_run else 'rimossi'
+            line += f', {verb}: {stats.get("rimossi", 0)}'
+        print(line)
+    return 0
+
+
+def cmd_status(args):
+    """Sola lettura: config, modalità, source/progetti con N regole, dest con dest_state."""
+    daemon = Daemon(args.config)
+    daemon.load_config()
+    print(f'config    {daemon.config_path}')
+    print(f'layout    {daemon.cfg.layout}')
+    if daemon.cfg.sources:
+        print('modalità  source')
+        for src in daemon.cfg.sources:
+            print(f'source    {src}')
+    else:
+        print(f'modalità  auto-discovery da {os.path.expanduser("~")}')
+    daemon.load_projects()
+    for project in sorted(daemon.projects, key=lambda p: p.root):
+        print(f'progetto  {project.name} — {len(project.matcher.rules)} regole '
+              f'— {project.root}')
+    if not daemon.projects:
+        print('progetto  nessuno (.sync non trovato)')
+    for dest in daemon.cfg.dests:
+        print(f'dest      {dest} [{dest_state(dest)}]')
+    return 0
+
+
+def check_sync_files(daemon):
+    """SPEC.md §9.2 (CR-03): ogni `.sync` scoperto deve parsificare e avere
+    ≥1 regola valida. Non fatale: il conteggio delle righe scartate diventa
+    un warning di `doctor`.
+
+    → (progetti totali, `.sync` rotti con motivo, righe scartate totali)."""
+    roots, auto = daemon.discovery_roots()
+    total, broken, discarded = 0, [], 0
+    for root in discover_projects(roots, auto=auto):
+        total += 1
+        path = os.path.join(root, '.sync')
+        try:
+            with open(path, encoding='utf-8') as fh:
+                text = fh.read()
+        except (OSError, UnicodeError) as e:   # OSError + UnicodeDecodeError
+            broken.append(f'{path}: {e}')
+            continue
+        # log_level fisso a info: il parse di doctor NON deve mai essere fatale
+        sync = parse_sync(text, log_level='info', origin=path)
+        discarded += sync.discarded
+        if not (sync.rules or sync.defaults):
+            broken.append(f'{path}: nessuna regola valida')
+    return total, broken, discarded
+
+
+def cmd_doctor(args):
+    """Un check per riga con esito ✔/✗; exit 1 se almeno un check fatale fallisce."""
+    fatal = False
+
+    def out(ok, msg, is_fatal=False):
+        nonlocal fatal
+        print(('✔ ' if ok else '✗ ') + msg)
+        if not ok and is_fatal:
+            fatal = True
+
+    cfg_path = os.path.expanduser(args.config or '~/.safekeep')
+    cfg = None
+    daemon = None
+    if not os.path.exists(cfg_path):
+        if os.path.exists(EXAMPLE):
+            hint = f'creala: cp {EXAMPLE} {cfg_path}'
+        else:
+            # install pip: niente repo, niente esempi → hint degradato
+            hint = (f'clone {REPO_URL} and copy examples/safekeep.example to '
+                    f'{cfg_path}')
+        out(False, f'config assente: {cfg_path} ({hint})',
+            is_fatal=bool(args.config))
+    else:
+        try:
+            daemon = Daemon(cfg_path)
+            cfg = daemon.load_config()
+        except ConfigError as e:
+            daemon = None
+            out(False, f'config non valida: {e}', is_fatal=True)
+        else:
+            # nessuna `source` → auto-discovery da $HOME: info, non warning (SPEC §6)
+            mode = (f'{len(cfg.sources)} source' if cfg.sources
+                    else f'auto-discovery da {os.path.expanduser("~")}')
+            out(True, f'config valida: {cfg_path} ({mode}, {len(cfg.dests)} dest)')
+
+    if daemon is not None:
+        # base = source, oppure $HOME in auto-mode: copre anche "dest dentro $HOME"
+        try:
+            daemon.validate_dests()
+        except ConfigError as e:
+            out(False, str(e), is_fatal=True)
+        else:
+            out(True, 'dest non annidate nelle source/$HOME (nessun loop di copia)')
+
+    if daemon is not None:
+        total, broken, discarded = check_sync_files(daemon)
+        if broken:
+            detail = f' ({discarded} righe scartate)' if discarded else ''
+            out(False, '.sync non validi: ' + '; '.join(broken) + detail
+                + ' — warning non fatale')
+        elif discarded:
+            out(False, f'.sync: {discarded} righe scartate in {total} progetto/i '
+                       '— warning non fatale')
+        elif total:
+            out(True, f'.sync: {total} progetto/i parsificati con regole valide')
+        else:
+            out(True, '.sync: nessun progetto scoperto (niente da validare)')
+
+    exe = shutil.which('fswatch')
+    if exe is None:
+        out(False, 'fswatch non trovato — installa con: brew install fswatch',
+            is_fatal=True)
+    else:
+        version = None
+        try:
+            proc = subprocess.run([exe, '--version'], capture_output=True,
+                                  text=True, timeout=15)
+            lines = (proc.stdout + proc.stderr).strip().splitlines()
+            version = lines[0] if lines else None
+        except (OSError, subprocess.SubprocessError):
+            pass
+        out(version is not None,
+            f'fswatch: {version}' if version else 'fswatch --version senza output',
+            is_fatal=True)
+        try:
+            monitors = subprocess.run([exe, '-M'], capture_output=True,
+                                      text=True, timeout=15)
+            has_fsevents = 'fsevents_monitor' in monitors.stdout
+        except (OSError, subprocess.SubprocessError):
+            has_fsevents = False
+        out(has_fsevents,
+            'fswatch monitor: fsevents_monitor presente' if has_fsevents else
+            'fswatch monitor: fsevents_monitor ASSENTE in `fswatch -M`',
+            is_fatal=True)
+
+    out(sys.version_info >= (3, 9),
+        f'python {sys.version.split()[0]} (≥ 3.9)', is_fatal=True)
+
+    docs = os.path.expanduser('~/Documents')
+    if not os.path.isdir(docs):
+        out(True, 'TCC (Transparency, Consent and Control): ~/Documents assente — probe saltato')
+    else:
+        try:
+            os.listdir(docs)
+        except PermissionError:
+            out(False, 'TCC: PermissionError su ~/Documents — serve FDA '
+                       '(Full Disk Access) per i progetti in cartelle protette')
+        else:
+            out(True, 'TCC: ~/Documents leggibile')
+
+    if cfg is not None:
+        residui = [os.path.join(dirpath, name)
+                   for dest in cfg.dests
+                   for dirpath, _, names in os.walk(dest)
+                   for name in names
+                   if TMP_INFIX in name]
+        out(not residui,
+            'residui *.safekeep.tmp.*: nessuno' if not residui else
+            'residui *.safekeep.tmp.*: ' + ', '.join(residui))
+
+    plist = os.path.expanduser('~/Library/LaunchAgents/com.safekeep.agent.plist')
+    if not os.path.exists(plist):
+        out(True, 'plist non installato (nessun agent da validare)')
+    elif shutil.which('plutil') is None:
+        out(True, 'plutil assente — lint del plist saltato')
+    else:
+        try:
+            lint = subprocess.run(['plutil', '-lint', plist],
+                                  capture_output=True, text=True, timeout=15)
+            detail = (lint.stdout + lint.stderr).strip() or plist
+            out(lint.returncode == 0, f'plist lint: {detail}', is_fatal=True)
+        except (OSError, subprocess.SubprocessError) as e:
+            out(False, f'plist lint non eseguibile: {e}', is_fatal=True)
+
+    return 1 if fatal else 0
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        if args.comando == 'run':
+            return Daemon(args.config).run(verbose=args.v)
+        if args.comando == 'status':
+            return cmd_status(args)
+        if args.comando == 'doctor':
+            return cmd_doctor(args)
+        return cmd_sync_once(args)
+    except ConfigError as e:
+        print(f'errore di config: {e}', file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())