safekeep 0.2.0__py3-none-any.whl

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/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())

safekeep/config.py

@@ -0,0 +1,266 @@
+"""Config globale `~/.safekeep` e file `.sync` di progetto (SPEC.md §3 e §4).
+
+Le destinazioni vivono SOLO nel config globale: un `.sync` contiene solo
+regole — le chiavi `name:`/`defaults:`/`include:`/`exclude:` e le righe nude
+stile gitignore (una riga nuda = `include:`, `!riga` = `exclude:`, SPEC.md §4.2).
+Una riga a forma di chiave non nota (`dest:`, `-dest:`, …) resta invalida: con
+`log_level: info` genera solo un warning e viene saltata, con `log_level: debug`
+è fatale (SPEC.md §4.2). Il config globale è invece sempre fail-fast.
+"""
+import logging
+import os
+import re
+
+from .matcher import BUILTIN_RULES, Matcher, parse_rule, strip_comment
+
+log = logging.getLogger('safekeep')
+
+
+class ConfigError(ValueError):
+    """Errore di config: il messaggio contiene sempre l'origine e la riga."""
+
+
+class GlobalConfig:
+    def __init__(self):
+        self.sources = []             # radici osservate (ripetibili, opzionali)
+        self.dests = []               # destinazioni globali (ripetibili) — le UNICHE
+        self.layout = 'relative'      # relative | full
+        self.defaults = []            # regole a bassa priorità (list[Rule])
+        self.log_level = 'info'       # debug | info | warn | error
+
+
+class SyncConfig:
+    def __init__(self):
+        self.name = None
+        self.defaults = []            # defaults: <regola> (list[Rule])
+        self.rules = []               # include:/exclude: in ordine (list[Rule])
+        self.discarded = 0            # righe scartate come invalide (per doctor)
+
+
+_SYNC_KEY = re.compile(r'(name|defaults|include|exclude)\s*:\s*(.*)')
+_CONF_KEY = re.compile(r'([A-Za-z_]+)\s*:\s*(.*)')
+# Riga a forma di chiave (`dest:`, `-dest:`, `foo:`): NON è una riga nuda.
+_KEY_SHAPE = re.compile(r'[A-Za-z_-][A-Za-z0-9_-]*\s*:')
+
+
+def bare_rule(line):
+    """Riga nuda stile gitignore → regola (SPEC.md §4.2): `pattern` include,
+    `!pattern` exclude. Attenzione: è l'**inverso di gitignore** — qui la riga
+    elenca i file da COPIARE. None se il pattern è vuoto."""
+    neg = line.startswith('!')
+    pat = line[1:].strip() if neg else line
+    if not pat:
+        return None
+    return parse_rule(f'{"exclude" if neg else "include"}: {pat}')
+
+
+def parse_sync(text, *, log_level='info', origin='<.sync>'):
+    """Parse di un file `.sync` → SyncConfig. Nessuna dest: le destinazioni
+    vivono solo in `~/.safekeep`, quindi `dest:`/`-dest:` restano righe invalide
+    (SPEC.md §4.2)."""
+    cfg = SyncConfig()
+
+    def invalid(lineno, detail):
+        cfg.discarded += 1
+        msg = f'{origin}:{lineno}: {detail}'
+        if log_level == 'debug':
+            raise ConfigError(msg)
+        log.warning('%s', msg)
+
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = strip_comment(raw).strip()
+        if not line:
+            continue
+        m = _SYNC_KEY.match(line)
+        if not m:
+            if _KEY_SHAPE.match(line):
+                # chiave ignota / dest: → riga invalida (SPEC.md §4.2)
+                invalid(lineno, f'riga non valida: {raw.strip()}')
+                continue
+            try:
+                rule = bare_rule(line)      # riga nuda stile gitignore
+            except ValueError as e:
+                # pattern da `.sync` non attendibile (regex invalida, NUL, …):
+                # warning + skip con info, ConfigError con debug (CR-03)
+                invalid(lineno, str(e))
+                continue
+            if rule is None:
+                invalid(lineno, 'pattern vuoto')
+                continue
+            cfg.rules.append(rule)          # stessa lista, stesso ordine
+            continue
+        key, val = m.group(1), m.group(2).strip()
+        if key in ('include', 'exclude', 'defaults'):
+            try:
+                rule = parse_rule(val if key == 'defaults' else line)
+            except ValueError as e:
+                invalid(lineno, str(e))
+                continue
+            if rule is None:
+                invalid(lineno, 'regola vuota')
+                continue
+            (cfg.defaults if key == 'defaults' else cfg.rules).append(rule)
+        elif key == 'name':
+            if val:
+                cfg.name = val
+            else:
+                invalid(lineno, 'name vuoto')
+        elif not val:
+            invalid(lineno, f'{key} senza valore')
+    return cfg
+
+
+def parse_config(text, origin='config'):
+    """Parse del config globale → GlobalConfig. Errori fatali sempre (fail-fast).
+
+    `source` è opzionale (nessuna riga → modalità auto-discovery da `$HOME`,
+    SPEC.md §6); `dest` è obbligatoria: è l'unico posto dove vivono le
+    destinazioni (SPEC.md §3)."""
+    cfg = GlobalConfig()
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = strip_comment(raw).strip()
+        if not line:
+            continue
+        m = _CONF_KEY.match(line)
+        if not m:
+            raise ConfigError(f'{origin}:{lineno}: riga non valida: {raw.strip()}')
+        key, val = m.group(1), m.group(2).strip()
+        if '\0' in val:
+            # un valore con NUL dal config globale esploderebbe più avanti in
+            # modo opaco (os.path/Popen): fail-fast qui, con numero di riga (CR-03)
+            raise ConfigError(f'{origin}:{lineno}: valore con carattere NUL: {key}')
+        if key == 'source':
+            if not val:
+                raise ConfigError(f'{origin}:{lineno}: source vuota')
+            cfg.sources.append(os.path.expanduser(val))
+        elif key == 'dest':
+            if not val:
+                raise ConfigError(f'{origin}:{lineno}: dest vuota')
+            cfg.dests.append(os.path.expanduser(val))
+        elif key == 'layout':
+            if val not in ('relative', 'full'):
+                raise ConfigError(f'{origin}:{lineno}: layout non valido: {val!r} (relative|full)')
+            cfg.layout = val
+        elif key == 'defaults':
+            try:
+                rule = parse_rule(val)
+            except ValueError as e:
+                raise ConfigError(f'{origin}:{lineno}: {e}') from None
+            if rule is None:
+                raise ConfigError(f'{origin}:{lineno}: defaults senza regola')
+            cfg.defaults.append(rule)
+        elif key == 'log_level':
+            if val not in ('debug', 'info', 'warn', 'error'):
+                raise ConfigError(f'{origin}:{lineno}: log_level non valido: {val!r}')
+            cfg.log_level = val
+        else:
+            raise ConfigError(f'{origin}:{lineno}: chiave sconosciuta: {key}')
+    if not cfg.dests:
+        raise ConfigError(f'{origin}: nessuna dest: serve almeno una riga '
+                          f'`dest: <path>` (esempio: examples/safekeep.example)')
+    return cfg
+
+
+def source_root_for(sources, path):
+    """La `source` configurata più profonda che contiene `path`; `path` se nessuna.
+
+    È la radice da cui si calcola il path dest in layout `relative` (SPEC.md §4.3):
+    il path dest include così il segmento del progetto (`backup/myapp/docs/a.md`)
+    e due progetti sotto la stessa sorgente non si sovrappongono.
+    """
+    p = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
+    best, best_len = p, -1
+    for src in sources:
+        s = os.path.realpath(os.path.abspath(os.path.expanduser(src)))
+        if (p == s or p.startswith(s + os.sep)) and len(s) > best_len:
+            best, best_len = s, len(s)
+    return best
+
+
+def dest_path(dest_root, source_root, relpath, layout):
+    """Path di destinazione (SPEC.md §4.3): relative → dest/<relativo alla
+    radice `source>`, full → dest/<path assoluto senza / iniziale>.
+
+    `source_root` è la radice `source` del config che contiene il progetto
+    (`source_root_for`), NON la root del progetto: con una dest condivisa,
+    `~/Code/myapp/docs/a.md` → `backup/myapp/docs/a.md` e due progetti
+    (`projA`, `projB`) con lo stesso file relativo non si sovrappongono.
+    """
+    if layout not in ('relative', 'full'):
+        raise ValueError(f'layout non valido: {layout!r} (relative|full)')
+    src = os.path.abspath(os.path.expanduser(source_root))
+    p = relpath if os.path.isabs(relpath) else os.path.join(src, relpath)
+    p = os.path.abspath(os.path.expanduser(p))
+    rel = os.path.relpath(p, os.sep) if layout == 'full' else os.path.relpath(p, src)
+    return os.path.normpath(os.path.join(os.path.expanduser(dest_root), rel))
+
+
+def validate_dests(sources, dests):
+    """Errore se una dest è dentro una sorgente → loop di copia infinito (SPEC.md §11)."""
+    def real(p):
+        return os.path.realpath(os.path.abspath(os.path.expanduser(p)))
+    for dest in dests:
+        d = real(dest)
+        for src in sources:
+            s = real(src)
+            if d == s or d.startswith(s + os.sep):
+                raise ConfigError(f'dest {d} è dentro la sorgente {s}: loop di copia infinito')
+
+
+# Modalità auto-discovery (SPEC.md §6): dir da potare durante lo scan di $HOME.
+# Le nascoste (iniziano con `.`) sono potate a monte, qui elencate per chiarezza
+# `.Trash` e `.cache` (e per `venv`, non coperto dai builtin).
+# Ultime sette: cartelle protette dalla privacy di macOS (TCC = Transparency,
+# Consent and Control). Senza "Accesso completo al disco" l'`opendir()` su una
+# di queste resta bloccato nel kernel — niente errore, niente prompt per un
+# agent launchd — e il discovery non finirebbe mai (SPEC.md §6).
+HOME_PRUNE_DIRS = frozenset({
+    'Library', '.Trash', '.cache', 'node_modules', '.git', '.venv',
+    '__pycache__', 'venv', 'Applications',
+    'Desktop', 'Documents', 'Downloads', 'Movies', 'Music', 'Pictures',
+    'Public',
+})
+
+
+def home_prune(rel):
+    """Pruning dell'auto-discovery: True = non scendere in questa directory.
+
+    `rel` è il path relativo alla radice con `/` come separatore; la radice
+    stessa (rel '.') non viene mai potata.
+    """
+    name = rel.rsplit('/', 1)[-1]
+    return name.startswith('.') or name in HOME_PRUNE_DIRS
+
+
+def discover_projects(sources, auto=False):
+    """Directory che contengono `.sync` sotto ogni radice (scan con pruning).
+
+    `auto=True` (modalità auto-discovery, scan della `$HOME`): si pota su
+    `home_prune` — nessuna directory nascosta e niente `Library`/`.Trash`/…,
+    così `.sync` dentro una di queste NON diventa progetto (SPEC.md §6).
+    `auto=False` (modalità source): si pota sul verdict *esclusa* delle regole
+    builtin. Scan ordinato (root prima dei sotto-progetti): i `.sync` annidati
+    restano progetti a sé (SPEC.md §4.1).
+    Il pruning è applicato ai *figli* prima di scendere: `os.walk` apre la
+    directory (`opendir`) solo quando ci si entra, così una dir potata — in
+    particolare una cartella protetta da TCC — non viene mai nemmeno aperta.
+    """
+    builtin = Matcher(BUILTIN_RULES)
+    prune = home_prune if auto else (lambda rel: not builtin.evaluate(rel, True))
+    found = []
+    for src in sources:
+        root = os.path.abspath(os.path.expanduser(src))
+        if not os.path.isdir(root):
+            log.warning('source inesistente o non è una directory: %s', src)
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            rel = os.path.relpath(dirpath, root).replace(os.sep, '/')
+            if '.sync' in filenames:
+                found.append(dirpath)   # dir senza .sync non è progetto
+            # pota i figli PRIMA di scendere: os.walk apre (opendir) una dir
+            # solo quando ci si entra, così una dir esclusa — in particolare
+            # una cartella protetta da TCC — non viene mai nemmeno aperta
+            dirnames[:] = sorted(
+                name for name in dirnames
+                if not prune(name if rel == '.' else rel + '/' + name))
+    return found