shadow-sentinel 1.0.1__tar.gz

shadow_sentinel-1.0.1/LICENSE

@@ -0,0 +1,18 @@
+Creative Commons Attribution-ShareAlike 3.0 Germany (CC BY-SA 3.0 DE)
+
+Copyright (c) 2026 automatician (Torsten Frieser), Germany / Saxony / Zittau.
+
+You are free to:
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material for any purpose, even commercially.
+
+Under the following terms:
+  Attribution — You must give appropriate credit, provide a link to the license,
+  and indicate if changes were made. You may do so in any reasonable manner, but
+  not in any way that suggests the licensor endorses you or your use.
+
+  ShareAlike — If you remix, transform, or build upon the material, you must
+  distribute your contributions under the same license as the original.
+
+No additional restrictions — You may not apply legal terms or technological measures
+that legally restrict others from doing anything the license permits.

shadow_sentinel-1.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: shadow-sentinel
+Version: 1.0.1
+Summary: Autonomous OS-level revision & backup guard with decentralized marker control and loop-coupling
+Author-email: automatician <235166879+automatician@users.noreply.github.com>
+License-Expression: CC-BY-SA-3.0
+Project-URL: Homepage, https://github.com/automatician/shadow-sentinel
+Project-URL: Bug Tracker, https://github.com/automatician/shadow-sentinel/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🛡️ Shadow Sentinel
+
+**Autonomous OS-Level Revision & Backup Daemon with Decentralized Marker Control and Loop-Coupling.**
+
+Shadow Sentinel monitors directory trees in real-time via the Linux kernel (`inotify`), captures
+atomic `.bak` revisions and unified diffs (`.diff`) on every file modification, and provides
+instant 1-command restores with loop-coupling safety.
+
+---
+
+## 🚀 Key Features
+
+1. **Decentralized Marker Control (`sentinel_marker`)**:
+   - No tedious editing of central configuration files.
+   - Simply run `sentinel init [MB]` in any directory or place a `sentinel_marker` file.
+   - The daemon automatically scans the system on startup and binds all marked roots.
+
+2. **Dynamic File-Size Ceiling (Self-Pruning Vault)**:
+   - The value inside `sentinel_marker` sets the protected size ceiling (e.g. `5` for 5 MB).
+   - If a file (such as a runaway logfile) exceeds this ceiling, it is automatically ejected
+     from the shadow vault. Small scripts, configurations, and source code stay 100% protected.
+
+3. **Loop-Coupling (Undo-Safe Restore)**:
+   - Restoring a file with `sentinel restore <ID>` overwrites the target file.
+   - The running inotify daemon immediately intercepts this write and seals the overwritten
+     version into a brand-new backup revision. Mistaken restores can instantly be undone!
+
+4. **Flapping & Cooldown Debounce**:
+   - Rapid consecutive writes are debounced with a 3-second quiet window to prevent spam.
+
+5. **Zero Dependencies**:
+   - Pure Python standard library with native `ctypes` bindings directly to `libc.so.6`.
+   - No external tools like `inotifywait` or background Git daemons required.
+
+---
+
+## 🧹 Automated Disk Sanitation & Retention Doctrine
+
+Sentinel guarantees that it will never exhaust disk space through a 4-tier automated policy:
+
+1. **Version Cap per File (Max 10 Revisions)**:
+   Only the 10 most recent `.bak` and `.diff` files per target are kept. Older versions are deleted.
+
+2. **Version Age Expiration (14 Days)**:
+   Revisions older than 14 days are automatically pruned.
+
+3. **Log Expiration (30 Days)**:
+   Daily audit diff logs (`diff-YYYYMMDD.log`) are removed after 30 days.
+
+4. **Emergency Storage Ceiling (500 MB Cap)**:
+   If total backup directory size exceeds 500 MB, an emergency purge trims the oldest backups
+   across all files until total disk usage drops back down to 80% (400 MB).
+
+5. **Active Vault Ejection**:
+   Files that grow beyond the MB ceiling in `sentinel_marker` are immediately removed from
+   the `.shadow_vault` to recover disk space instantly.
+
+*The pruning engine runs automatically every 6 hours and immediately upon service startup.*
+
+---
+
+## 📦 Installation
+
+```bash
+pip install shadow-sentinel
+```
+
+Set up and start the systemd background service in one step:
+```bash
+sudo sentinel service install
+```
+
+---
+
+## 🛠️ Usage
+
+### Protect a Directory
+Navigate to the directory and run:
+```bash
+sentinel init 5
+```
+*(Creates `sentinel_marker` with a 5 MB file size limit).*
+
+### List Backups
+Simply type in any terminal:
+```bash
+sentinel
+```
+Automatically detects the nearest marker upwards and lists all protected revisions.
+
+### Restore a File
+```bash
+sentinel restore 3
+```
+
+### View Unified Diff
+```bash
+sentinel diff 3
+```
+
+### List All Active Markers on System
+```bash
+sentinel markers
+```
+
+### Full Interactive Manual
+```bash
+sentinel help
+```
+
+---
+
+## ⚙️ Storage & Configuration
+
+### Linux FHS Standard Paths:
+- **Root Daemon:** `/var/lib/shadow-sentinel/`
+- **User Daemon:** `~/.local/share/shadow-sentinel/`
+
+### Custom Storage Redirection (`/etc/shadow-sentinel/config.json`):
+To store backups, vaults, and indices in a custom directory, create:
+`/etc/shadow-sentinel/config.json` (for root) or `~/.config/shadow-sentinel/config.json` (for user):
+
+```json
+{
+    "storage_dir": "/custom/path/to/backups"
+}
+```
+
+### Environment Variable Override:
+```bash
+export SENTINEL_STORAGE_DIR=/custom/path/to/backups
+```

shadow_sentinel-1.0.1/README.md

@@ -0,0 +1,132 @@
+# 🛡️ Shadow Sentinel
+
+**Autonomous OS-Level Revision & Backup Daemon with Decentralized Marker Control and Loop-Coupling.**
+
+Shadow Sentinel monitors directory trees in real-time via the Linux kernel (`inotify`), captures
+atomic `.bak` revisions and unified diffs (`.diff`) on every file modification, and provides
+instant 1-command restores with loop-coupling safety.
+
+---
+
+## 🚀 Key Features
+
+1. **Decentralized Marker Control (`sentinel_marker`)**:
+   - No tedious editing of central configuration files.
+   - Simply run `sentinel init [MB]` in any directory or place a `sentinel_marker` file.
+   - The daemon automatically scans the system on startup and binds all marked roots.
+
+2. **Dynamic File-Size Ceiling (Self-Pruning Vault)**:
+   - The value inside `sentinel_marker` sets the protected size ceiling (e.g. `5` for 5 MB).
+   - If a file (such as a runaway logfile) exceeds this ceiling, it is automatically ejected
+     from the shadow vault. Small scripts, configurations, and source code stay 100% protected.
+
+3. **Loop-Coupling (Undo-Safe Restore)**:
+   - Restoring a file with `sentinel restore <ID>` overwrites the target file.
+   - The running inotify daemon immediately intercepts this write and seals the overwritten
+     version into a brand-new backup revision. Mistaken restores can instantly be undone!
+
+4. **Flapping & Cooldown Debounce**:
+   - Rapid consecutive writes are debounced with a 3-second quiet window to prevent spam.
+
+5. **Zero Dependencies**:
+   - Pure Python standard library with native `ctypes` bindings directly to `libc.so.6`.
+   - No external tools like `inotifywait` or background Git daemons required.
+
+---
+
+## 🧹 Automated Disk Sanitation & Retention Doctrine
+
+Sentinel guarantees that it will never exhaust disk space through a 4-tier automated policy:
+
+1. **Version Cap per File (Max 10 Revisions)**:
+   Only the 10 most recent `.bak` and `.diff` files per target are kept. Older versions are deleted.
+
+2. **Version Age Expiration (14 Days)**:
+   Revisions older than 14 days are automatically pruned.
+
+3. **Log Expiration (30 Days)**:
+   Daily audit diff logs (`diff-YYYYMMDD.log`) are removed after 30 days.
+
+4. **Emergency Storage Ceiling (500 MB Cap)**:
+   If total backup directory size exceeds 500 MB, an emergency purge trims the oldest backups
+   across all files until total disk usage drops back down to 80% (400 MB).
+
+5. **Active Vault Ejection**:
+   Files that grow beyond the MB ceiling in `sentinel_marker` are immediately removed from
+   the `.shadow_vault` to recover disk space instantly.
+
+*The pruning engine runs automatically every 6 hours and immediately upon service startup.*
+
+---
+
+## 📦 Installation
+
+```bash
+pip install shadow-sentinel
+```
+
+Set up and start the systemd background service in one step:
+```bash
+sudo sentinel service install
+```
+
+---
+
+## 🛠️ Usage
+
+### Protect a Directory
+Navigate to the directory and run:
+```bash
+sentinel init 5
+```
+*(Creates `sentinel_marker` with a 5 MB file size limit).*
+
+### List Backups
+Simply type in any terminal:
+```bash
+sentinel
+```
+Automatically detects the nearest marker upwards and lists all protected revisions.
+
+### Restore a File
+```bash
+sentinel restore 3
+```
+
+### View Unified Diff
+```bash
+sentinel diff 3
+```
+
+### List All Active Markers on System
+```bash
+sentinel markers
+```
+
+### Full Interactive Manual
+```bash
+sentinel help
+```
+
+---
+
+## ⚙️ Storage & Configuration
+
+### Linux FHS Standard Paths:
+- **Root Daemon:** `/var/lib/shadow-sentinel/`
+- **User Daemon:** `~/.local/share/shadow-sentinel/`
+
+### Custom Storage Redirection (`/etc/shadow-sentinel/config.json`):
+To store backups, vaults, and indices in a custom directory, create:
+`/etc/shadow-sentinel/config.json` (for root) or `~/.config/shadow-sentinel/config.json` (for user):
+
+```json
+{
+    "storage_dir": "/custom/path/to/backups"
+}
+```
+
+### Environment Variable Override:
+```bash
+export SENTINEL_STORAGE_DIR=/custom/path/to/backups
+```

shadow_sentinel-1.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shadow-sentinel"
+version = "1.0.1"
+authors = [
+  { name="automatician", email="235166879+automatician@users.noreply.github.com" },
+]
+description = "Autonomous OS-level revision & backup guard with decentralized marker control and loop-coupling"
+readme = "README.md"
+license = "CC-BY-SA-3.0"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: System :: Archiving :: Backup",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+"Homepage" = "https://github.com/automatician/shadow-sentinel"
+"Bug Tracker" = "https://github.com/automatician/shadow-sentinel/issues"
+
+[project.scripts]
+sentinel = "shadow_sentinel.core:cli_main"

shadow_sentinel-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shadow_sentinel-1.0.1/shadow_sentinel/__init__.py

@@ -0,0 +1,7 @@
+"""
+Shadow Sentinel - Autonomous OS-Level Revision & Backup Daemon
+"""
+__version__ = "1.0.1"
+__author__ = "automatician (Torsten Frieser)"
+__copyright__ = "Copyright (c) 2026 automatician (Torsten Frieser), Germany / Saxony / Zittau"
+__license__ = "CC-BY-SA-3.0"