@smilintux/skcapstone 0.1.0

package/src/skcapstone/skills/syncthing_setup.py

@@ -0,0 +1,297 @@
+"""
+Syncthing auto-setup skill for skcapstone / OpenClaw agents.
+
+Detects, installs, and configures Syncthing for sovereign P2P
+memory synchronization. Generates device IDs, shared folder config,
+and optional QR codes for easy pairing.
+"""
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Optional
+
+
+SYNC_DIR = Path.home() / ".skcapstone" / "sync"
+SYNCTHING_CONFIG_DIR = Path.home() / ".config" / "syncthing"
+SYNCTHING_CONFIG_FILE = SYNCTHING_CONFIG_DIR / "config.xml"
+SHARED_FOLDER_ID = "skcapstone-sync"
+
+
+def detect_syncthing() -> Optional[str]:
+    """Check if Syncthing is installed and return its path.
+
+    Returns:
+        Optional[str]: Path to syncthing binary, or None.
+    """
+    return shutil.which("syncthing")
+
+
+def get_install_instructions() -> str:
+    """Return OS-appropriate install instructions for Syncthing.
+
+    Returns:
+        str: Human-readable install instructions.
+    """
+    system = platform.system().lower()
+    if system == "linux":
+        distro = _detect_linux_distro()
+        if distro in ("ubuntu", "debian"):
+            return (
+                "Install Syncthing on Debian/Ubuntu:\n"
+                "  sudo apt install syncthing\n"
+                "Or via official repo:\n"
+                "  curl -s https://syncthing.net/release-key.gpg | "
+                "sudo gpg --dearmor -o /usr/share/keyrings/syncthing-archive-keyring.gpg\n"
+                '  echo "deb [signed-by=/usr/share/keyrings/syncthing-archive-keyring.gpg] '
+                'https://apt.syncthing.net/ syncthing stable" | '
+                "sudo tee /etc/apt/sources.list.d/syncthing.list\n"
+                "  sudo apt update && sudo apt install syncthing"
+            )
+        elif distro in ("arch", "manjaro"):
+            return "Install Syncthing on Arch/Manjaro:\n  sudo pacman -S syncthing"
+        elif distro in ("fedora", "centos", "rhel"):
+            return "Install Syncthing on Fedora/RHEL:\n  sudo dnf install syncthing"
+        else:
+            return "Install Syncthing:\n  https://syncthing.net/downloads/"
+    elif system == "darwin":
+        return "Install Syncthing on macOS:\n  brew install syncthing"
+    elif system == "windows":
+        return (
+            "Install Syncthing on Windows:\n"
+            "  winget install SyncthingFoundation.Syncthing\n"
+            "Or download from: https://syncthing.net/downloads/"
+        )
+    return "Install Syncthing from: https://syncthing.net/downloads/"
+
+
+def _detect_linux_distro() -> str:
+    """Detect the Linux distribution family.
+
+    Returns:
+        str: Distribution identifier (e.g., 'ubuntu', 'arch').
+    """
+    try:
+        with open("/etc/os-release") as f:
+            for line in f:
+                if line.startswith("ID="):
+                    return line.strip().split("=")[1].strip('"').lower()
+                if line.startswith("ID_LIKE="):
+                    like = line.strip().split("=")[1].strip('"').lower()
+                    if "arch" in like:
+                        return "arch"
+                    if "debian" in like:
+                        return "debian"
+    except FileNotFoundError:
+        pass
+    return "unknown"
+
+
+def get_device_id() -> Optional[str]:
+    """Get the local Syncthing device ID.
+
+    Returns:
+        Optional[str]: The device ID string, or None if not available.
+    """
+    st = detect_syncthing()
+    if not st:
+        return None
+    try:
+        result = subprocess.run(
+            [st, "--device-id"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    # Fallback: parse config.xml
+    if SYNCTHING_CONFIG_FILE.exists():
+        try:
+            tree = ET.parse(SYNCTHING_CONFIG_FILE)
+            root = tree.getroot()
+            for device in root.iter("device"):
+                if device.get("name") == platform.node():
+                    return device.get("id")
+        except ET.ParseError:
+            pass
+    return None
+
+
+def ensure_shared_folder() -> Path:
+    """Create the skcapstone sync shared folder if it doesn't exist.
+
+    Returns:
+        Path: The shared folder path.
+    """
+    for subdir in ("outbox", "inbox", "archive"):
+        (SYNC_DIR / subdir).mkdir(parents=True, exist_ok=True)
+    return SYNC_DIR
+
+
+def configure_syncthing_folder() -> bool:
+    """Add the skcapstone sync folder to Syncthing config.
+
+    Returns:
+        bool: True if configuration was added/updated.
+    """
+    if not SYNCTHING_CONFIG_FILE.exists():
+        return False
+
+    try:
+        tree = ET.parse(SYNCTHING_CONFIG_FILE)
+        root = tree.getroot()
+    except ET.ParseError:
+        return False
+
+    for folder in root.iter("folder"):
+        if folder.get("id") == SHARED_FOLDER_ID:
+            return True
+
+    folder_elem = ET.SubElement(root, "folder")
+    folder_elem.set("id", SHARED_FOLDER_ID)
+    folder_elem.set("label", "SKCapstone Sync")
+    folder_elem.set("path", str(SYNC_DIR))
+    folder_elem.set("type", "sendreceive")
+    folder_elem.set("rescanIntervalS", "60")
+    folder_elem.set("fsWatcherEnabled", "true")
+    folder_elem.set("fsWatcherDelayS", "10")
+
+    tree.write(str(SYNCTHING_CONFIG_FILE), xml_declaration=True)
+    return True
+
+
+def start_syncthing() -> bool:
+    """Start Syncthing as a background process or systemd service.
+
+    Returns:
+        bool: True if started successfully.
+    """
+    # Reason: try systemd user service first, then fall back to direct launch
+    result = subprocess.run(
+        ["systemctl", "--user", "start", "syncthing.service"],
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode == 0:
+        return True
+
+    st = detect_syncthing()
+    if not st:
+        return False
+
+    subprocess.Popen(
+        [st, "--no-browser", "--no-restart"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return True
+
+
+def generate_qr_code(device_id: str) -> Optional[str]:
+    """Generate a QR code for the device ID.
+
+    Args:
+        device_id: Syncthing device ID string.
+
+    Returns:
+        Optional[str]: ASCII QR code string, or None if qrcode not installed.
+    """
+    try:
+        import qrcode
+        from io import StringIO
+
+        qr = qrcode.QRCode(box_size=1, border=1)
+        qr.add_data(device_id)
+        qr.make(fit=True)
+
+        buf = StringIO()
+        qr.print_ascii(out=buf)
+        return buf.getvalue()
+    except ImportError:
+        return None
+
+
+def add_remote_device(device_id: str, name: str = "peer") -> bool:
+    """Add a remote device to Syncthing config for pairing.
+
+    Args:
+        device_id: The remote device's Syncthing device ID.
+        name: Friendly name for the device.
+
+    Returns:
+        bool: True if device was added.
+    """
+    if not SYNCTHING_CONFIG_FILE.exists():
+        return False
+
+    try:
+        tree = ET.parse(SYNCTHING_CONFIG_FILE)
+        root = tree.getroot()
+    except ET.ParseError:
+        return False
+
+    for device in root.iter("device"):
+        if device.get("id") == device_id:
+            return True
+
+    device_elem = ET.SubElement(root, "device")
+    device_elem.set("id", device_id)
+    device_elem.set("name", name)
+    device_elem.set("compression", "metadata")
+    device_elem.set("introducer", "false")
+
+    # Also add this device to the shared folder
+    for folder in root.iter("folder"):
+        if folder.get("id") == SHARED_FOLDER_ID:
+            dev_ref = ET.SubElement(folder, "device")
+            dev_ref.set("id", device_id)
+            break
+
+    tree.write(str(SYNCTHING_CONFIG_FILE), xml_declaration=True)
+    return True
+
+
+def full_setup() -> dict:
+    """Run the complete Syncthing setup flow.
+
+    Returns:
+        dict: Setup result with device_id, folder_path, status.
+    """
+    result = {
+        "syncthing_installed": False,
+        "device_id": None,
+        "folder_path": str(SYNC_DIR),
+        "folder_configured": False,
+        "started": False,
+        "qr_code": None,
+        "install_instructions": None,
+    }
+
+    st_path = detect_syncthing()
+    if not st_path:
+        result["install_instructions"] = get_install_instructions()
+        return result
+
+    result["syncthing_installed"] = True
+
+    ensure_shared_folder()
+    result["folder_configured"] = configure_syncthing_folder()
+
+    result["started"] = start_syncthing()
+
+    device_id = get_device_id()
+    result["device_id"] = device_id
+
+    if device_id:
+        result["qr_code"] = generate_qr_code(device_id)
+
+    return result

package/src/skcapstone/sync/__init__.py

@@ -0,0 +1,14 @@
+"""
+Sovereign Sync -- encrypted agent state synchronization.
+
+The vault never travels naked. Every push encrypts with CapAuth PGP.
+Every pull verifies the signature before restoring.
+
+Backends: Syncthing (real-time P2P), GitHub, Forgejo, Google Drive, local filesystem.
+The human picks the pipe. The agent secures the payload.
+"""
+
+from .engine import SyncEngine
+from .vault import Vault
+
+__all__ = ["SyncEngine", "Vault"]

package/src/skcapstone/sync/backends.py

@@ -0,0 +1,330 @@
+"""
+Sync storage backends -- where the vault travels.
+
+Each backend knows how to push and pull vault archives.
+The engine picks which one(s) to use based on config.
+
+Syncthing: Real-time P2P. Vault lands in sync/outbox, peers grab it.
+GitHub/Forgejo: Git-based. Vault is committed and pushed.
+GDrive: Google Drive API. Vault uploaded to a folder.
+Local: Plain filesystem copy. For USB drives, NAS, etc.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .models import SyncBackendConfig, SyncBackendType
+
+logger = logging.getLogger("skcapstone.sync.backends")
+
+
+class SyncBackend(ABC):
+    """Abstract sync transport backend."""
+
+    @abstractmethod
+    def push(self, vault_path: Path, manifest_path: Path) -> bool:
+        """Push a vault archive to the backend.
+
+        Args:
+            vault_path: Path to the vault archive file.
+            manifest_path: Path to the accompanying manifest.
+
+        Returns:
+            True if push succeeded.
+        """
+
+    @abstractmethod
+    def pull(self, target_dir: Path) -> Optional[Path]:
+        """Pull the latest vault from the backend.
+
+        Args:
+            target_dir: Where to download the vault.
+
+        Returns:
+            Path to the downloaded vault, or None if nothing available.
+        """
+
+    @abstractmethod
+    def available(self) -> bool:
+        """Check if this backend is currently usable."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable backend name."""
+
+
+class SyncthingBackend(SyncBackend):
+    """Syncthing-based real-time P2P sync.
+
+    Pushes vaults to the Syncthing-watched outbox directory.
+    Syncthing handles the actual peer-to-peer transfer.
+    Pulls by checking the inbox for incoming vaults.
+    """
+
+    def __init__(self, config: SyncBackendConfig, agent_home: Path):
+        self.config = config
+        self.sync_dir = agent_home / "sync"
+        self.outbox = self.sync_dir / "outbox"
+        self.inbox = self.sync_dir / "inbox"
+        self.archive = self.sync_dir / "archive"
+
+        for d in (self.outbox, self.inbox, self.archive):
+            d.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def name(self) -> str:
+        return "syncthing"
+
+    def push(self, vault_path: Path, manifest_path: Path) -> bool:
+        """Copy vault to Syncthing outbox for P2P distribution."""
+        try:
+            shutil.copy2(vault_path, self.outbox / vault_path.name)
+            shutil.copy2(
+                manifest_path, self.outbox / manifest_path.name
+            )
+
+            state_file = self.sync_dir / "sync-state.json"
+            state = {}
+            if state_file.exists():
+                try:
+                    state = json.loads(state_file.read_text())
+                except json.JSONDecodeError:
+                    pass
+
+            state["last_push"] = datetime.now(timezone.utc).isoformat()
+            state["seed_count"] = len(list(self.outbox.glob("*.tar.gz*")))
+            state_file.write_text(json.dumps(state, indent=2))
+
+            logger.info(
+                "Vault pushed to Syncthing outbox: %s", vault_path.name
+            )
+            return True
+        except OSError as exc:
+            logger.error("Syncthing push failed: %s", exc)
+            return False
+
+    def pull(self, target_dir: Path) -> Optional[Path]:
+        """Check Syncthing inbox for incoming vaults."""
+        vaults = sorted(
+            self.inbox.glob("vault-*.tar.gz*"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        if not vaults:
+            logger.info("No vaults in Syncthing inbox")
+            return None
+
+        latest = vaults[0]
+        dest = target_dir / latest.name
+        shutil.copy2(latest, dest)
+
+        shutil.move(str(latest), str(self.archive / latest.name))
+
+        logger.info("Vault pulled from Syncthing inbox: %s", latest.name)
+        return dest
+
+    def available(self) -> bool:
+        return shutil.which("syncthing") is not None
+
+
+class GitBackend(SyncBackend):
+    """Git-based sync backend (GitHub, Forgejo, Gitea, etc).
+
+    Commits vault archives to a dedicated branch in a git repo.
+    """
+
+    def __init__(self, config: SyncBackendConfig, agent_home: Path):
+        self.config = config
+        self.agent_home = agent_home
+        self._repo_dir = agent_home / "sync" / "git-cache"
+        self._repo_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def name(self) -> str:
+        backend_label = (
+            "forgejo"
+            if self.config.backend_type == SyncBackendType.FORGEJO
+            else "github"
+        )
+        return backend_label
+
+    def _ensure_repo(self) -> bool:
+        """Clone or verify the git repository."""
+        if not self.config.repo_url:
+            logger.error("No repo_url configured for git backend")
+            return False
+
+        git_dir = self._repo_dir / ".git"
+        if git_dir.exists():
+            return True
+
+        env = os.environ.copy()
+        if self.config.token_env_var:
+            token = os.environ.get(self.config.token_env_var, "")
+            if token:
+                env["GIT_ASKPASS"] = "echo"
+                env["GIT_TOKEN"] = token
+
+        result = subprocess.run(
+            ["git", "clone", "--depth", "1",
+             "-b", self.config.branch,
+             self.config.repo_url, str(self._repo_dir)],
+            capture_output=True, text=True, check=False, env=env,
+        )
+        return result.returncode == 0
+
+    def push(self, vault_path: Path, manifest_path: Path) -> bool:
+        if not self._ensure_repo():
+            return False
+
+        try:
+            shutil.copy2(
+                vault_path, self._repo_dir / vault_path.name
+            )
+            shutil.copy2(
+                manifest_path, self._repo_dir / manifest_path.name
+            )
+
+            cmds = [
+                ["git", "add", "-A"],
+                [
+                    "git", "commit", "-m",
+                    f"vault: {vault_path.name} "
+                    f"[{datetime.now(timezone.utc).isoformat()}]",
+                ],
+                ["git", "push", "origin", self.config.branch],
+            ]
+            for cmd in cmds:
+                result = subprocess.run(
+                    cmd, capture_output=True, text=True,
+                    check=False, cwd=str(self._repo_dir),
+                )
+                if result.returncode != 0:
+                    logger.error(
+                        "Git command failed: %s -> %s",
+                        " ".join(cmd), result.stderr,
+                    )
+                    return False
+
+            logger.info("Vault pushed to %s", self.name)
+            return True
+        except OSError as exc:
+            logger.error("Git push failed: %s", exc)
+            return False
+
+    def pull(self, target_dir: Path) -> Optional[Path]:
+        if not self._ensure_repo():
+            return None
+
+        result = subprocess.run(
+            ["git", "pull", "origin", self.config.branch],
+            capture_output=True, text=True, check=False,
+            cwd=str(self._repo_dir),
+        )
+        if result.returncode != 0:
+            logger.error("Git pull failed: %s", result.stderr)
+            return None
+
+        vaults = sorted(
+            self._repo_dir.glob("vault-*.tar.gz*"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        if not vaults:
+            return None
+
+        latest = vaults[0]
+        dest = target_dir / latest.name
+        shutil.copy2(latest, dest)
+        logger.info("Vault pulled from %s: %s", self.name, latest.name)
+        return dest
+
+    def available(self) -> bool:
+        return (
+            shutil.which("git") is not None
+            and self.config.repo_url is not None
+        )
+
+
+class LocalBackend(SyncBackend):
+    """Local filesystem backend for USB, NAS, or mounted drives."""
+
+    def __init__(self, config: SyncBackendConfig, agent_home: Path):
+        self.config = config
+        self.target = (
+            config.local_path.expanduser()
+            if config.local_path
+            else agent_home / "sync" / "local-backup"
+        )
+        self.target.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def name(self) -> str:
+        return "local"
+
+    def push(self, vault_path: Path, manifest_path: Path) -> bool:
+        try:
+            shutil.copy2(vault_path, self.target / vault_path.name)
+            shutil.copy2(
+                manifest_path, self.target / manifest_path.name
+            )
+            logger.info("Vault pushed to local: %s", self.target)
+            return True
+        except OSError as exc:
+            logger.error("Local push failed: %s", exc)
+            return False
+
+    def pull(self, target_dir: Path) -> Optional[Path]:
+        vaults = sorted(
+            self.target.glob("vault-*.tar.gz*"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        if not vaults:
+            return None
+
+        latest = vaults[0]
+        dest = target_dir / latest.name
+        shutil.copy2(latest, dest)
+        logger.info("Vault pulled from local: %s", latest.name)
+        return dest
+
+    def available(self) -> bool:
+        return self.target.exists()
+
+
+def create_backend(
+    config: SyncBackendConfig, agent_home: Path
+) -> SyncBackend:
+    """Factory function to create the appropriate backend.
+
+    Args:
+        config: Backend configuration.
+        agent_home: Agent home directory.
+
+    Returns:
+        Instantiated SyncBackend.
+
+    Raises:
+        ValueError: If backend type is not supported.
+    """
+    factories = {
+        SyncBackendType.SYNCTHING: SyncthingBackend,
+        SyncBackendType.GITHUB: GitBackend,
+        SyncBackendType.FORGEJO: GitBackend,
+        SyncBackendType.LOCAL: LocalBackend,
+    }
+    factory = factories.get(config.backend_type)
+    if not factory:
+        raise ValueError(f"Unsupported backend: {config.backend_type}")
+    return factory(config, agent_home)