safekeep 0.2.0__py3-none-any.whl

safekeep/matcher.py

@@ -0,0 +1,161 @@
+"""Matcher gitignore-like con semantica last-match-wins (SPEC.md §4.3 e §5).
+
+Ordine di priorità dei layer (dal basso all'alto): builtin → globali →
+defaults del progetto → regole del `.sync`. L'ultima regola che matcha il
+path (o un suo genitore directory) decide il verdict; nessun match →
+semantica allow-list: file NON copiato, directory attraversata.
+"""
+import re
+
+
+def strip_comment(line):
+    """Rimuove i commenti: `# ...` a inizio riga (escape `\\#`) o ` # ...` inline."""
+    if line.lstrip().startswith('#'):
+        return ''
+    return re.split(r'\s#', line, maxsplit=1)[0]
+
+
+def _charclass(pat, i):
+    """`[abc]`/`[!abc]` a pat[i] → (regex, indice dopo) o None se malformed."""
+    j = i + 1
+    neg = False
+    if j < len(pat) and pat[j] in '!^':
+        neg = True
+        j += 1
+    if j < len(pat) and pat[j] == ']':   # ']' come primo carattere è letterale
+        j += 1
+    while j < len(pat) and pat[j] != ']':
+        j += 1
+    if j >= len(pat):
+        return None
+    body = re.sub(r'([\\\[\]])', r'\\\1', pat[i + 1:j])
+    return ('[^' + body + ']' if neg else '[' + body + ']'), j + 1
+
+
+def _glob(pat):
+    """Pattern gitignore → corpo di regex (ancorata dal chiamante)."""
+    out = []
+    i, n = 0, len(pat)
+    while i < n:
+        if pat[i] == '\\' and i + 1 < n:        # \x escape generico
+            out.append(re.escape(pat[i + 1]))
+            i += 2
+        elif pat[i:i + 2] == '**':
+            if pat[i:i + 3] == '**/':           # a/**/b → segmenti multipli opzionali
+                out.append('(?:[^/]+/)*')
+                i += 3
+            else:
+                out.append('.*')                # ** → qualsiasi segmenti (include /)
+                i += 2
+        elif pat[i] == '*':                     # * entro un singolo segmento
+            out.append('[^/]*')
+            i += 1
+        elif pat[i] == '?':
+            out.append('[^/]')
+            i += 1
+        elif pat[i] == '[':
+            cls = _charclass(pat, i)
+            if cls is None:
+                out.append('\\[')
+                i += 1
+            else:
+                out.append(cls[0])
+                i = cls[1]
+        else:
+            out.append(re.escape(pat[i]))
+            i += 1
+    return ''.join(out)
+
+
+class Rule:
+    """Singola regola `include:`/`exclude:` con pattern gitignore-like."""
+
+    def __init__(self, pattern, include):
+        if '\0' in pattern:
+            # un pattern con NUL arriva da un `.sync` non attendibile e finirebbe
+            # in argv di fswatch → ValueError "embedded null byte" (CR-03)
+            raise ValueError(f'pattern contiene un carattere NUL: {pattern!r}')
+        self.pattern = pattern
+        self.include = include
+        self.dir_only = pattern.endswith('/')          # foo/ → solo directory
+        p = pattern[:-1] if self.dir_only else pattern
+        self.anchored = '/' in p                       # /foo o slash interna → alla root
+        if p.startswith('/'):
+            p = p[1:]
+        # dir/** matcha anche dir stessa, così il pruning la esclude per intero
+        body = _glob(p[:-3]) + '(?:/.*)?' if p.endswith('/**') else _glob(p)
+        try:
+            self._re = re.compile('(?:' + body + r')\Z')
+        except re.error as e:
+            # `re.error` NON è un ValueError: un pattern malevolo/esotico
+            # (es. `[z-a]*`) va convertito così il parser lo gestisce come
+            # riga invalida invece di far crashare il daemon (CR-03)
+            raise ValueError(f'pattern regex non valido: {pattern!r} ({e})') from None
+
+    def matches(self, path, is_dir=False):
+        path = path.strip('/')
+        if not path:
+            return False
+        parts = path.split('/')
+        last = len(parts) - 1
+        for i, part in enumerate(parts):
+            if i == last and self.dir_only and not is_dir:
+                continue                             # foo/ non matcha un file chiamato foo
+            candidate = '/'.join(parts[:i + 1]) if self.anchored else part
+            if self._re.match(candidate):
+                return True                          # path o genitore directory
+        return False
+
+
+def parse_rule(line):
+    """Rule da `include: <pattern>`/`exclude: <pattern>`; None per riga vuota/commento."""
+    s = strip_comment(line).strip()
+    if not s:
+        return None
+    m = re.match(r'(include|exclude)\s*:\s*(.*)\Z', s)
+    if not m:
+        raise ValueError(f'riga non valida (atteso include:/exclude:): {line.strip()!r}')
+    pattern = m.group(2).strip()
+    if not pattern:
+        raise ValueError(f'pattern vuoto: {line.strip()!r}')
+    return Rule(pattern, m.group(1) == 'include')
+
+
+def parse_rules(lines, origin='<rules>'):
+    """Layer di regole da una lista di righe; riga invalida → errore con numero di riga."""
+    rules = []
+    for lineno, raw in enumerate(lines, 1):
+        try:
+            rule = parse_rule(raw)
+        except ValueError as e:
+            raise ValueError(f'{origin}:{lineno}: {e}') from None
+        if rule is not None:
+            rules.append(rule)
+    return rules
+
+
+class Matcher:
+    """Layer di regole in ordine di priorità (bassa → alta), last-match-wins."""
+
+    def __init__(self, *layers):
+        self.rules = [rule for layer in layers for rule in layer]
+
+    def evaluate(self, relpath: str, is_dir: bool = False) -> bool:
+        """True = copiare. Ultima regola che matcha decide; nessun match →
+        allow-list (SPEC.md §4.3): file → False (non copiato), directory →
+        True (attraversata: si pota solo su un'esclusione esplicita)."""
+        for rule in reversed(self.rules):
+            if rule.matches(relpath, is_dir):
+                return rule.include
+        return is_dir
+
+
+# Regole builtin (bassa priorità, sempre presenti — SPEC.md §5)
+BUILTIN_RULES = parse_rules([
+    'exclude: .git/',
+    'exclude: node_modules/',
+    'exclude: .venv/',
+    'exclude: __pycache__/',
+    'exclude: .DS_Store',
+    'exclude: *.swp',
+], origin='builtin')

safekeep/volumes.py

@@ -0,0 +1,28 @@
+"""Destinazioni non montate: stato, backoff e split (SPEC.md §8.3)."""
+import os
+
+BACKOFF_CAP = 60          # secondi massimi fra due retry (niente busy-loop)
+
+
+def dest_state(path) -> str:
+    """`ok` se il mountpoint esiste (volume montato), `absent` altrimenti.
+
+    Solo `os.path.exists`: nessun processo figlio, nessun `mount` da scrapare.
+    """
+    return 'ok' if os.path.exists(path) else 'absent'
+
+
+def backoff_schedule():
+    """1, 2, 4, 8, 16, 32, 60, 60, … — iteratore infinito con cap a 60s."""
+    delay = 1
+    while True:
+        yield min(delay, BACKOFF_CAP)
+        delay *= 2
+
+
+def partition_dests(dests):
+    """Split delle dest in (ready, absent) sullo stato corrente del mountpoint."""
+    ready, absent = [], []
+    for d in dests:
+        (ready if dest_state(d) == 'ok' else absent).append(d)
+    return ready, absent

safekeep-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+safekeep/__init__.py,sha256=JYMz2afeGarcNRe9G1XF17PKF70cYS75cIh3EAt8ndU,178
+safekeep/cli.py,sha256=b4JuHhuuKFukCl1wgXxYppF2UCcKvGhmBcnOPWipUY0,11392
+safekeep/config.py,sha256=oAwUw5KITp8oyYQx8X9yF_ftRTh65CMRR4BmxjFrgwc,11668
+safekeep/copier.py,sha256=KdGZe3lwKWepA_3qVX52BjFHfsmbQUsls_CVBKU9s4g,13750
+safekeep/daemon.py,sha256=dXjJox00KXcjB6Hmsmy8BvLwSjbkASapFWg9W4USjRo,30394
+safekeep/matcher.py,sha256=EwkE378Wo9-n56hw_wnD3un5UdRy0aG1Q-KM5nETvdQ,6008
+safekeep/volumes.py,sha256=v3fBGp7Ir_IVBR2PQSU44_Oxk6DE3griBntPbTOwicQ,849
+safekeep-0.2.0.dist-info/licenses/LICENSE,sha256=1WM2NMXTKpFlFQ2JItrUnblhj4Hybdo9U6gzipCh-Fs,1067
+safekeep-0.2.0.dist-info/METADATA,sha256=T4oxx1D_mtY35n1df0egZJEKBv8yft_lQKyn4ZOHbfk,6457
+safekeep-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+safekeep-0.2.0.dist-info/entry_points.txt,sha256=5XT-DVH6stDI99sx0dzDGsqP3zHTd92GBo8XhczThHg,47
+safekeep-0.2.0.dist-info/top_level.txt,sha256=ZNrpaPE43W6IK3vPTA-U_R_RYt8f0T2J5-DS_NOKN6M,9
+safekeep-0.2.0.dist-info/RECORD,,

safekeep-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

safekeep-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+safekeep = safekeep.cli:main

safekeep-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+safekeep