studyctl 2.0.0__py3-none-any.whl

studyctl/shared.py

@@ -0,0 +1,425 @@
+"""Cross-machine state sync using agent-session-tools infrastructure.
+
+Uses the existing session-sync merge logic (SQLite + rsync) rather than
+reinventing sync. The Mac Mini acts as the hub — all machines push/pull to it.
+
+Config lives at ~/.config/studyctl/config.yaml
+
+Host schema:
+  hosts:
+    macmini:
+      hostname: Andys-Mac-Mini
+      ip_address:
+        primary: 192.168.125.22
+        secondary: 192.168.125.12   # optional, fallback for wifi
+      user: ataylor
+      state_json: ~/.config/studyctl/state.json
+      sessions_db: ~/.config/studyctl/sessions.db
+
+Local machine is auto-detected by matching socket.gethostname() against
+the hostname field in each host entry.
+"""
+
+from __future__ import annotations
+
+import socket
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from .settings import load_settings
+
+CONFIG_PATH = Path.home() / ".config" / "studyctl" / "config.yaml"
+
+
+def _get_default_user() -> str:
+    """Get default sync user lazily (avoids import-time os.getlogin failure)."""
+    return load_settings().sync_user
+
+
+def _load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    return yaml.safe_load(CONFIG_PATH.read_text()) or {}
+
+
+def _resolve_hosts(config: dict) -> tuple[str | None, dict, dict[str, dict]]:
+    """Resolve local and remote hosts from unified hosts config.
+
+    Returns:
+        (local_name, local_host_config, remote_hosts_dict)
+    """
+    hosts = config.get("hosts", {})
+
+    # Auto-detect local machine by hostname
+    current_hostname = socket.gethostname().split(".")[0]
+    local_name: str | None = None
+    local_config: dict = {}
+    remotes: dict[str, dict] = {}
+
+    for name, host in hosts.items():
+        if host.get("hostname") == current_hostname:
+            local_name = name
+            local_config = host
+        else:
+            remotes[name] = host
+
+    return local_name, local_config, remotes
+
+
+def _get_host_ip(host_config: dict) -> str:
+    """Get the primary IP address for a host."""
+    ip = host_config.get("ip_address", {})
+    if isinstance(ip, dict):
+        return ip.get("primary", "")
+    return str(ip) if ip else ""
+
+
+def _get_host_ips(host_config: dict) -> list[str]:
+    """Get all IP addresses for a host (primary first, then secondary)."""
+    ip = host_config.get("ip_address", {})
+    if isinstance(ip, dict):
+        ips = []
+        if ip.get("primary"):
+            ips.append(ip["primary"])
+        if ip.get("secondary"):
+            ips.append(ip["secondary"])
+        return ips
+    return [str(ip)] if ip else []
+
+
+def _rsync_with_fallback(
+    args_template: list[str], host_config: dict, user: str
+) -> subprocess.CompletedProcess:
+    """Run rsync trying primary IP, falling back to secondary."""
+    ips = _get_host_ips(host_config)
+    last_result = None
+    for ip in ips:
+        # Replace {dest} placeholder with actual user@ip
+        args = [a.replace("{HOST}", f"{user}@{ip}") for a in args_template]
+        last_result = subprocess.run(args, capture_output=True, text=True)
+        if last_result.returncode == 0:
+            return last_result
+    # Return last failure if all IPs failed
+    return last_result or subprocess.CompletedProcess(args_template, 1)
+
+
+def push_state(remote: str | None = None) -> list[str]:
+    """Push studyctl state + sessions DB to remote machine(s).
+
+    Uses rsync for state.json and session-sync for the sessions DB
+    (which handles intelligent merging, FTS rebuild, etc.)
+    """
+    config = _load_config()
+    if not config:
+        raise FileNotFoundError(f"No config at {CONFIG_PATH}. Run 'studyctl state init'.")
+
+    _, local_config, remotes = _resolve_hosts(config)
+    if remote:
+        remotes = {remote: remotes[remote]} if remote in remotes else {}
+
+    pushed = []
+    state_json = Path(local_config.get("state_json", "~/.config/studyctl/state.json")).expanduser()
+
+    for name, r in remotes.items():
+        user = r.get("user", _get_default_user())
+        remote_state = r.get("state_json", "~/.config/studyctl/state.json")
+
+        # Push state.json via rsync (with IP fallback)
+        if state_json.exists():
+            result = _rsync_with_fallback(
+                ["rsync", "-az", str(state_json), f"{{HOST}}:{remote_state}"],
+                r,
+                user,
+            )
+            if result.returncode == 0:
+                pushed.append(f"state.json → {name}")
+
+        # Push sessions DB via session-sync (handles merge)
+        sessions_db = Path(local_config.get("sessions_db", "")).expanduser()
+        if sessions_db.exists():
+            remote_db = r.get("sessions_db", "")
+            if remote_db:
+                ip = _get_host_ip(r)
+                dest = f"{user}@{ip}:{remote_db}"
+                result = subprocess.run(
+                    ["session-sync", "push", dest],
+                    capture_output=True,
+                    text=True,
+                )
+                if result.returncode == 0:
+                    pushed.append(f"sessions.db → {name}")
+
+    return pushed
+
+
+def pull_state(remote: str | None = None) -> list[str]:
+    """Pull state from remote machine(s). Sessions DB uses merge logic."""
+    config = _load_config()
+    if not config:
+        raise FileNotFoundError(f"No config at {CONFIG_PATH}")
+
+    _, local_config, remotes = _resolve_hosts(config)
+    if remote:
+        remotes = {remote: remotes[remote]} if remote in remotes else {}
+
+    pulled = []
+    state_json = Path(local_config.get("state_json", "~/.config/studyctl/state.json")).expanduser()
+    state_json.parent.mkdir(parents=True, exist_ok=True)
+
+    for name, r in remotes.items():
+        user = r.get("user", _get_default_user())
+        remote_state = r.get("state_json", "~/.config/studyctl/state.json")
+
+        # Pull state.json (with IP fallback)
+        result = _rsync_with_fallback(
+            ["rsync", "-az", "--update", f"{{HOST}}:{remote_state}", str(state_json)],
+            r,
+            user,
+        )
+        if result.returncode == 0:
+            pulled.append(f"state.json ← {name}")
+
+        # Pull + merge sessions DB
+        remote_db = r.get("sessions_db", "")
+        if remote_db:
+            ip = _get_host_ip(r)
+            src = f"{user}@{ip}:{remote_db}"
+            result = subprocess.run(
+                ["session-sync", "pull", src],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                pulled.append(f"sessions.db ← {name} (merged)")
+
+    return pulled
+
+
+def sync_status() -> dict:
+    """Check config and connectivity."""
+    config = _load_config()
+    if not config:
+        return {"configured": False, "config_path": str(CONFIG_PATH)}
+
+    local_name, _, remotes = _resolve_hosts(config)
+
+    status: dict = {
+        "configured": True,
+        "local": local_name or "unknown",
+        "remotes": {},
+    }
+    for name, r in remotes.items():
+        ips = _get_host_ips(r)
+        user = r.get("user", _get_default_user())
+        reachable = False
+        connected_ip = ""
+
+        for ip in ips:
+            result = subprocess.run(
+                [
+                    "ssh",
+                    "-o",
+                    "ConnectTimeout=3",
+                    "-o",
+                    "BatchMode=yes",
+                    f"{user}@{ip}",
+                    "echo ok",
+                ],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                reachable = True
+                connected_ip = ip
+                break
+
+        status["remotes"][name] = {
+            "host": connected_ip or (ips[0] if ips else "?"),
+            "reachable": reachable,
+        }
+    return status
+
+
+def init_interactive_config(console: object) -> Path:
+    """Run interactive configuration wizard asking core setup questions.
+
+    Asks about:
+    1. Knowledge bridging — leverage familiar topics for analogies
+    2. NotebookLM integration
+    3. Obsidian vault path
+    """
+    from rich.console import Console
+    from rich.panel import Panel
+
+    if not isinstance(console, Console):
+        console = Console()
+
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load existing config or start fresh
+    existing: dict = {}
+    if CONFIG_PATH.exists():
+        existing = yaml.safe_load(CONFIG_PATH.read_text()) or {}
+        console.print(f"[dim]Existing config found at {CONFIG_PATH} — updating.[/dim]\n")
+
+    console.print(
+        Panel(
+            "[bold]Socratic Study Mentor — Interactive Setup[/bold]\n\n"
+            "This will configure your study environment.\n"
+            "Press Enter to accept defaults shown in [dim]brackets[/dim].",
+            title="🧠 studyctl config init",
+            border_style="cyan",
+        )
+    )
+
+    # ── Question 1: Knowledge bridging ──────────────────────────────────────
+    console.print("\n[bold cyan]1/3 — Knowledge Bridging[/bold cyan]")
+    console.print(
+        "The study mentor can draw analogies between topics you already know well\n"
+        "and new topics you're studying (e.g. networking → data engineering).\n"
+    )
+
+    use_bridging = _prompt_yn(
+        "Do you want to leverage a topic you are already very familiar with\n"
+        "  so we can draw comparisons with an area you already know well\n"
+        "  to topics you are studying?",
+        default=True,
+    )
+
+    knowledge_domains: dict = existing.get("knowledge_domains", {})
+    if use_bridging:
+        current_primary = knowledge_domains.get("primary", "")
+        primary_domain = _prompt_text(
+            "  What is your primary area of expertise?",
+            default=current_primary or "networking",
+        )
+        knowledge_domains["primary"] = primary_domain
+
+        console.print(
+            f"\n  [dim]Great — the mentor will use {primary_domain} analogies"
+            " to teach new concepts.[/dim]"
+        )
+        console.print(
+            "  [dim]You can add specific anchor concepts later with: studyctl bridge add[/dim]\n"
+        )
+    else:
+        knowledge_domains = {}
+        console.print("  [dim]Skipped — no knowledge bridging configured.[/dim]\n")
+
+    # ── Question 2: NotebookLM integration ──────────────────────────────────
+    console.print("[bold cyan]2/3 — Google NotebookLM Integration[/bold cyan]")
+    console.print(
+        "NotebookLM can be used as a knowledge source — sync your notes into\n"
+        "notebooks for AI-generated audio overviews and enhanced study sessions.\n"
+    )
+
+    use_notebooklm = _prompt_yn(
+        "Do you want to integrate with Google's NotebookLM to use new and\n"
+        "  existing Notebooks as a source of knowledge?",
+        default=bool(existing.get("notebooklm", {}).get("enabled")),
+    )
+
+    notebooklm_config: dict = existing.get("notebooklm", {})
+    if use_notebooklm:
+        notebooklm_config["enabled"] = True
+        console.print("\n  [dim]NotebookLM enabled. Map notebooks to topics via:[/dim]")
+        console.print(
+            "  [dim]  studyctl sync <topic>  — syncs Obsidian notes to a NotebookLM notebook[/dim]"
+        )
+        console.print("  [dim]  Requires: uv pip install 'studyctl[notebooklm]'[/dim]\n")
+    else:
+        notebooklm_config["enabled"] = False
+        console.print("  [dim]Skipped — NotebookLM integration disabled.[/dim]\n")
+
+    # ── Question 3: Obsidian vault ──────────────────────────────────────────
+    console.print("[bold cyan]3/3 — Obsidian Vault Integration[/bold cyan]")
+    console.print(
+        "The study mentor can read your Obsidian vault for study notes,\n"
+        "course materials, and knowledge base content.\n"
+    )
+
+    current_obsidian = str(existing.get("obsidian_base", "~/Obsidian"))
+    use_obsidian = _prompt_yn(
+        "Do you want to integrate with an existing Obsidian vault for sources\n  of information?",
+        default=True,
+    )
+
+    obsidian_base = current_obsidian
+    if use_obsidian:
+        obsidian_base = _prompt_text(
+            "  Base path of your Obsidian vault",
+            default=current_obsidian,
+        )
+        resolved = Path(obsidian_base).expanduser()
+        if resolved.exists():
+            console.print(f"  [green]✓ Found vault at {resolved}[/green]\n")
+        else:
+            console.print(
+                f"  [yellow]⚠ Path {resolved} does not exist yet — "
+                f"you can create it later.[/yellow]\n"
+            )
+    else:
+        obsidian_base = ""
+        console.print("  [dim]Skipped — no Obsidian vault configured.[/dim]\n")
+
+    # ── Write config ────────────────────────────────────────────────────────
+    config = dict(existing)
+    if obsidian_base:
+        config["obsidian_base"] = obsidian_base
+    elif "obsidian_base" in config:
+        del config["obsidian_base"]
+
+    if knowledge_domains:
+        config["knowledge_domains"] = knowledge_domains
+    elif "knowledge_domains" in config:
+        del config["knowledge_domains"]
+
+    config["notebooklm"] = notebooklm_config
+
+    # Ensure topics key exists
+    config.setdefault("topics", [])
+
+    CONFIG_PATH.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+    return CONFIG_PATH
+
+
+def _prompt_yn(question: str, default: bool = False) -> bool:
+    """Prompt for yes/no with a default."""
+    suffix = " [Y/n] " if default else " [y/N] "
+    reply = input(question + suffix).strip().lower()
+    if not reply:
+        return default
+    return reply in ("y", "yes")
+
+
+def _prompt_text(question: str, default: str = "") -> str:
+    """Prompt for text input with a default."""
+    suffix = f" [{default}] " if default else " "
+    reply = input(question + suffix).strip()
+    return reply or default
+
+
+def init_config() -> Path:
+    """Create default config file with unified hosts schema."""
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if CONFIG_PATH.exists():
+        return CONFIG_PATH
+
+    hostname = socket.gethostname().split(".")[0]
+    default = {
+        "hosts": {
+            hostname.lower().replace(" ", "-"): {
+                "hostname": hostname,
+                "ip_address": {
+                    "primary": "",
+                },
+                "user": _get_default_user(),
+                "state_json": "~/.config/studyctl/state.json",
+                "sessions_db": "~/.config/studyctl/sessions.db",
+            },
+        },
+    }
+    CONFIG_PATH.write_text(yaml.dump(default, default_flow_style=False, sort_keys=False))
+    return CONFIG_PATH

studyctl/state.py

@@ -0,0 +1,120 @@
+"""Sync state — tracks what's been synced to prevent duplication."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .settings import get_state_dir, get_state_file
+
+
+@dataclass
+class SyncedSource:
+    """A file that has been synced to NotebookLM."""
+
+    path: str  # Relative to home
+    content_hash: str
+    source_id: str  # NotebookLM source ID
+    synced_at: str
+    notebook_id: str
+
+
+@dataclass
+class TopicState:
+    """State for a single topic/notebook."""
+
+    topic_name: str
+    notebook_id: str | None = None
+    notebook_title: str = ""
+    sources: dict[str, SyncedSource] = field(default_factory=dict)  # path → SyncedSource
+    last_sync: str = ""
+    last_audio_generated: str = ""
+
+
+class SyncState:
+    """Persistent state for the sync pipeline."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = {"version": 1, "topics": {}}
+        self._load()
+
+    def _load(self) -> None:
+        if get_state_file().exists():
+            try:
+                self._data = json.loads(get_state_file().read_text())
+            except json.JSONDecodeError:
+                import sys
+
+                print(
+                    f"[studyctl] Corrupt state file {get_state_file()}, using defaults",
+                    file=sys.stderr,
+                )
+
+    def save(self) -> None:
+        import os
+
+        get_state_dir().mkdir(parents=True, exist_ok=True)
+        get_state_file().write_text(json.dumps(self._data, indent=2) + "\n")
+        os.chmod(get_state_file(), 0o600)
+
+    def get_topic(self, name: str) -> TopicState:
+        raw = self._data.setdefault("topics", {}).get(name, {})
+        sources = {}
+        for path, s in raw.get("sources", {}).items():
+            sources[path] = SyncedSource(**s)
+        return TopicState(
+            topic_name=name,
+            notebook_id=raw.get("notebook_id"),
+            notebook_title=raw.get("notebook_title", ""),
+            sources=sources,
+            last_sync=raw.get("last_sync", ""),
+            last_audio_generated=raw.get("last_audio_generated", ""),
+        )
+
+    def set_topic(self, state: TopicState) -> None:
+        self._data.setdefault("topics", {})[state.topic_name] = {
+            "notebook_id": state.notebook_id,
+            "notebook_title": state.notebook_title,
+            "sources": {p: asdict(s) for p, s in state.sources.items()},
+            "last_sync": state.last_sync,
+            "last_audio_generated": state.last_audio_generated,
+        }
+
+    def set_notebook_id(self, topic_name: str, notebook_id: str, title: str) -> None:
+        ts = self.get_topic(topic_name)
+        ts.notebook_id = notebook_id
+        ts.notebook_title = title
+        self.set_topic(ts)
+
+    def record_sync(
+        self, topic_name: str, path: str, content_hash: str, source_id: str, notebook_id: str
+    ) -> None:
+        ts = self.get_topic(topic_name)
+        ts.sources[path] = SyncedSource(
+            path=path,
+            content_hash=content_hash,
+            source_id=source_id,
+            synced_at=datetime.now(UTC).isoformat(),
+            notebook_id=notebook_id,
+        )
+        ts.last_sync = datetime.now(UTC).isoformat()
+        self.set_topic(ts)
+
+    def needs_sync(self, path: Path) -> bool:
+        """Check if a file has changed since last sync."""
+        rel = str(path.relative_to(Path.home()))
+        current_hash = file_hash(path)
+        for topic_data in self._data.get("topics", {}).values():
+            for synced_path, source in topic_data.get("sources", {}).items():
+                if synced_path == rel and source.get("content_hash") == current_hash:
+                    return False
+        return True
+
+
+def file_hash(path: Path) -> str:
+    """SHA256 of file content."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:16]