claude-memory-sync 0.2.0__py3-none-any.whl

claude_memory_sync/config.py

@@ -0,0 +1,245 @@
+"""Configuration management for Claude Memory Sync."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from .paths import get_config_dir
+
+
+CONFIG_FILE = "config.json"
+
+DEFAULT_CONFIG = {
+    "device_name": "",
+    "github_repo": "",
+    "conflict_strategy": "merge",
+}
+
+
+def _config_path() -> Path:
+    return get_config_dir() / CONFIG_FILE
+
+
+def load_config() -> dict:
+    """Load config from disk. Returns empty dict if no config file exists."""
+    path = _config_path()
+    if not path.exists():
+        return {}
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_config(config: dict) -> None:
+    """Save config dict to disk."""
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2)
+
+
+def get_token() -> str:
+    """Resolve GitHub token from environment or gh CLI.
+
+    Resolution order:
+    1. CLAUDE_MEMORY_SYNC_TOKEN env var
+    2. GH_TOKEN env var
+    3. `gh auth token` subprocess call
+
+    Raises RuntimeError if no token is found.
+    """
+    # 1. Dedicated env var
+    token = os.environ.get("CLAUDE_MEMORY_SYNC_TOKEN", "").strip()
+    if token:
+        return token
+
+    # 2. GH_TOKEN env var
+    token = os.environ.get("GH_TOKEN", "").strip()
+    if token:
+        return token
+
+    # 3. gh CLI
+    try:
+        result = subprocess.run(
+            ["gh", "auth", "token"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            token = result.stdout.strip()
+            if token:
+                return token
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    raise RuntimeError(
+        "No GitHub token found. Set CLAUDE_MEMORY_SYNC_TOKEN or GH_TOKEN, "
+        "or authenticate with `gh auth login`."
+    )
+
+
+def is_configured() -> bool:
+    """Check if the tool has been configured."""
+    config = load_config()
+    return bool(config.get("device_name") and config.get("github_repo"))
+
+
+def setup_wizard() -> None:
+    """Interactive setup wizard to configure the tool."""
+    print("=== Claude Memory Sync Setup ===\n")
+
+    config = load_config()
+
+    # Device name
+    default_device = config.get("device_name", "")
+    prompt = f"Device name [{default_device}]: " if default_device else "Device name: "
+    device_name = input(prompt).strip() or default_device
+    if not device_name:
+        print("Error: Device name is required.")
+        return
+
+    # GitHub repo
+    default_repo = config.get("github_repo", "")
+    prompt = f"GitHub repo (owner/repo) [{default_repo}]: " if default_repo else "GitHub repo (owner/repo): "
+    github_repo = input(prompt).strip() or default_repo
+    if not github_repo or "/" not in github_repo:
+        print("Error: GitHub repo must be in 'owner/repo' format.")
+        return
+
+    # Validate token
+    token = None
+    try:
+        token = get_token()
+        print(f"GitHub token found ({token[:4]}...)")
+    except RuntimeError as e:
+        print(f"Warning: {e}")
+        print("You can set a token later via environment variables.")
+
+    # Save basic config
+    config.update({
+        "device_name": device_name,
+        "github_repo": github_repo,
+        "conflict_strategy": config.get("conflict_strategy", "merge"),
+    })
+    save_config(config)
+    print(f"\nConfig saved to {_config_path()}")
+
+    # Cross-device alias setup (only if we have a token)
+    if token is None:
+        return
+
+    print("\n=== Cross-Device Setup ===\n")
+    try:
+        _setup_cross_device_aliases(config, token, github_repo)
+    except Exception as e:
+        print(f"Cross-device setup skipped: {e}")
+
+
+def _setup_cross_device_aliases(config: dict, token: str, repo: str) -> None:
+    """Interactive cross-device alias mapping during setup."""
+    from .alias import (
+        add_alias,
+        get_remote_project_dirnames,
+        list_aliases,
+        sync_aliases_from_remote,
+        sync_aliases_to_remote,
+    )
+    from .discovery import discover_projects
+    from .github_api import GitHubAPI
+    from .paths import project_dirname_to_display
+
+    api = GitHubAPI(repo, token)
+
+    # Pull existing remote aliases
+    sync_aliases_from_remote(api)
+    aliases = list_aliases()
+
+    # Discover local projects with memory files
+    local_projects = [p for p in discover_projects() if p["has_memory"]]
+    if not local_projects:
+        print("No local projects with memory files found.")
+        return
+
+    # Get remote project dirnames
+    remote_dirnames = get_remote_project_dirnames(api)
+
+    # Find local projects not yet mapped to any alias
+    unmapped_local = []
+    for p in local_projects:
+        mapped = False
+        for dirnames in aliases.values():
+            if p["dirname"] in dirnames:
+                mapped = True
+                break
+        if not mapped:
+            unmapped_local.append(p)
+
+    # Find remote dirnames not yet mapped to any alias
+    all_mapped_dirnames = set()
+    for dirnames in aliases.values():
+        all_mapped_dirnames.update(dirnames)
+    unmapped_remote = [d for d in remote_dirnames if d not in all_mapped_dirnames]
+
+    if not unmapped_local and not unmapped_remote:
+        print("All projects are already aliased.")
+        return
+
+    if unmapped_remote:
+        print("Remote projects not yet mapped to local:")
+        for i, d in enumerate(unmapped_remote, 1):
+            display = project_dirname_to_display(d)
+            print(f"  {i}. {d} ({display})")
+        print()
+
+    if unmapped_local:
+        print("Local projects without an alias:")
+        for p in unmapped_local:
+            display = project_dirname_to_display(p["dirname"])
+            print(f"  {p['dirname']} ({display})")
+        print()
+
+    # Interactive mapping
+    for p in unmapped_local:
+        display = project_dirname_to_display(p["dirname"])
+        print(f"\nMap '{p['dirname']}' ({display}):")
+
+        # Show options: existing aliases + remote unmapped dirnames + new alias
+        options = []
+        if aliases:
+            print("  Existing aliases:")
+            for i, (name, dirnames) in enumerate(aliases.items(), 1):
+                print(f"    {i}. {name}")
+                options.append(("existing", name))
+
+        new_idx = len(options) + 1
+        print(f"    {new_idx}. Create new alias")
+        print(f"    s. Skip")
+
+        choice = input("  Choice: ").strip().lower()
+        if choice == "s":
+            continue
+        try:
+            idx = int(choice)
+            if 1 <= idx <= len(options):
+                _, alias_name = options[idx - 1]
+                add_alias(alias_name, p["dirname"])
+                print(f"  Added '{p['dirname']}' to alias '{alias_name}'.")
+            elif idx == new_idx:
+                alias_name = input("  New alias name: ").strip()
+                if alias_name:
+                    add_alias(alias_name, p["dirname"])
+                    print(f"  Created alias '{alias_name}'.")
+                    aliases = list_aliases()  # refresh
+        except (ValueError, IndexError):
+            print("  Skipped.")
+
+    # Push updated aliases to remote
+    updated_aliases = list_aliases()
+    if updated_aliases:
+        push_choice = input("\nPush aliases to remote? [Y/n]: ").strip().lower()
+        if push_choice != "n":
+            sync_aliases_to_remote(api)
+            print("Aliases pushed to remote.")

claude_memory_sync/discovery.py

@@ -0,0 +1,54 @@
+"""Discover local Claude memory directories."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .paths import get_projects_dir, path_to_project_dirname
+
+
+def discover_projects() -> list[dict]:
+    """Scan ~/.claude/projects/ for directories containing memory files.
+
+    Returns a list of dicts with keys:
+        dirname: str — the project directory name
+        path: Path — full path to the project directory
+        has_memory: bool — whether a memory/ subdirectory exists with .md files
+        memory_files: list[Path] — list of .md files in the memory/ subdirectory
+    """
+    projects_dir = get_projects_dir()
+    if not projects_dir.exists():
+        return []
+
+    results = []
+    for entry in sorted(projects_dir.iterdir()):
+        if not entry.is_dir():
+            continue
+        memory_dir = entry / "memory"
+        memory_files = sorted(memory_dir.glob("*.md")) if memory_dir.is_dir() else []
+        results.append({
+            "dirname": entry.name,
+            "path": entry,
+            "has_memory": len(memory_files) > 0,
+            "memory_files": memory_files,
+        })
+    return results
+
+
+def get_project_memory_dir(project_dirname: str) -> Path:
+    """Return the path to the memory directory for a specific project."""
+    return get_projects_dir() / project_dirname / "memory"
+
+
+def get_current_project() -> str | None:
+    """Detect the current project dirname based on the current working directory.
+
+    Returns None if the CWD doesn't map to a known project.
+    """
+    cwd = os.getcwd()
+    dirname = path_to_project_dirname(cwd)
+    project_dir = get_projects_dir() / dirname
+    if project_dir.is_dir():
+        return dirname
+    return None

claude_memory_sync/github_api.py

@@ -0,0 +1,134 @@
+"""GitHub REST API client for Contents API operations."""
+
+from __future__ import annotations
+
+import base64
+
+import requests
+
+
+class GitHubAPIError(Exception):
+    """Raised when a GitHub API call fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class GitHubAPI:
+    """Minimal client for GitHub Contents API."""
+
+    BASE_URL = "https://api.github.com"
+
+    def __init__(self, repo: str, token: str):
+        self.repo = repo
+        self.token = token
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"token {token}",
+            "Accept": "application/vnd.github.v3+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        })
+
+    def _contents_url(self, path: str = "") -> str:
+        path = path.strip("/")
+        return f"{self.BASE_URL}/repos/{self.repo}/contents/{path}"
+
+    def _check_rate_limit(self, resp: requests.Response) -> None:
+        if resp.status_code == 403:
+            remaining = resp.headers.get("X-RateLimit-Remaining", "")
+            if remaining == "0":
+                raise GitHubAPIError(
+                    "GitHub API rate limit exceeded. Wait a few minutes and retry.",
+                    status_code=403,
+                )
+
+    def _check_response(self, resp: requests.Response, context: str = "") -> None:
+        self._check_rate_limit(resp)
+        if resp.status_code >= 400:
+            msg = f"GitHub API error ({resp.status_code})"
+            if context:
+                msg += f" {context}"
+            try:
+                body = resp.json()
+                msg += f": {body.get('message', '')}"
+            except ValueError:
+                pass
+            raise GitHubAPIError(msg, status_code=resp.status_code)
+
+    def get_file(self, path: str) -> dict | None:
+        """Get a file's content and metadata.
+
+        Returns dict with keys: content (str, decoded), sha (str), encoding.
+        Returns None if the file does not exist (404).
+        """
+        resp = self.session.get(self._contents_url(path))
+        if resp.status_code == 404:
+            return None
+        self._check_response(resp, f"getting {path}")
+        data = resp.json()
+        content = base64.b64decode(data["content"]).decode("utf-8")
+        return {
+            "content": content,
+            "sha": data["sha"],
+            "encoding": data.get("encoding", "base64"),
+        }
+
+    def put_file(
+        self, path: str, content: str, message: str, sha: str | None = None
+    ) -> dict:
+        """Create or update a file. sha is required for updates."""
+        encoded = base64.b64encode(content.encode("utf-8")).decode("ascii")
+        payload: dict = {
+            "message": message,
+            "content": encoded,
+        }
+        if sha is not None:
+            payload["sha"] = sha
+        resp = self.session.put(self._contents_url(path), json=payload)
+        self._check_response(resp, f"putting {path}")
+        return resp.json()
+
+    def delete_file(self, path: str, sha: str, message: str) -> dict:
+        """Delete a file from the repo."""
+        payload = {
+            "message": message,
+            "sha": sha,
+        }
+        resp = self.session.delete(self._contents_url(path), json=payload)
+        self._check_response(resp, f"deleting {path}")
+        return resp.json()
+
+    def list_dir(self, path: str = "") -> list[dict]:
+        """List contents of a directory.
+
+        Returns list of dicts with keys: name, path, type, sha.
+        Returns empty list if path doesn't exist.
+        """
+        resp = self.session.get(self._contents_url(path))
+        if resp.status_code == 404:
+            return []
+        self._check_response(resp, f"listing {path}")
+        data = resp.json()
+        if not isinstance(data, list):
+            return []
+        return [
+            {"name": item["name"], "path": item["path"], "type": item["type"], "sha": item["sha"]}
+            for item in data
+        ]
+
+    def get_tree(self, path: str = "") -> list[dict]:
+        """Recursively list all files under a path."""
+        results = []
+        items = self.list_dir(path)
+        for item in items:
+            if item["type"] == "file":
+                results.append(item)
+            elif item["type"] == "dir":
+                results.extend(self.get_tree(item["path"]))
+        return results
+
+    def test_connection(self) -> bool:
+        """Verify the repo exists and the token has access."""
+        resp = self.session.get(f"{self.BASE_URL}/repos/{self.repo}")
+        return resp.status_code == 200

claude_memory_sync/hooks.py

@@ -0,0 +1,214 @@
+"""Claude Code hooks for automatic memory sync."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _get_settings_path() -> Path:
+    """Return path to ~/.claude/settings.json."""
+    return Path.home() / ".claude" / "settings.json"
+
+
+def _load_settings() -> dict:
+    """Load Claude Code settings."""
+    path = _get_settings_path()
+    if path.exists():
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return {}
+
+
+def _save_settings(settings: dict) -> None:
+    """Save Claude Code settings."""
+    path = _get_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2)
+
+
+HOOK_PULL = {
+    "matcher": "SessionStart",
+    "hooks": [
+        {
+            "type": "command",
+            "command": "claude-memory-hook-pull",
+        }
+    ],
+}
+
+HOOK_PUSH = {
+    "matcher": "Stop",
+    "hooks": [
+        {
+            "type": "command",
+            "command": "claude-memory-hook-push",
+        }
+    ],
+}
+
+
+def _get_shim_dir() -> Path:
+    """Return a directory on PATH where we can place command shims.
+
+    Tries ~/.local/bin, ~/bin, then falls back to creating ~/.local/bin.
+    """
+    candidates = [
+        Path.home() / ".local" / "bin",
+        Path.home() / "bin",
+    ]
+    # Prefer a directory that already exists AND is on PATH
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    for candidate in candidates:
+        if candidate.is_dir() and any(
+            Path(p).resolve() == candidate.resolve()
+            for p in path_dirs
+            if p
+        ):
+            return candidate
+
+    # Prefer a directory that exists even if not on PATH
+    for candidate in candidates:
+        if candidate.is_dir():
+            return candidate
+
+    # Default: create ~/.local/bin
+    default = Path.home() / ".local" / "bin"
+    default.mkdir(parents=True, exist_ok=True)
+    return default
+
+
+def install_shims() -> list[str]:
+    """Create command shims for Windows (Microsoft Store Python PATH workaround).
+
+    Returns list of created shim paths.
+    """
+    if sys.platform != "win32":
+        return []
+
+    shim_dir = _get_shim_dir()
+    shim_dir.mkdir(parents=True, exist_ok=True)
+
+    shims = {
+        "claude-memory.cmd": '@echo off\npython -m claude_memory_sync %*\n',
+        "claude-memory-hook-pull.cmd": '@echo off\npython -c "from claude_memory_sync.hooks import hook_auto_pull; hook_auto_pull()" %*\n',
+        "claude-memory-hook-push.cmd": '@echo off\npython -c "from claude_memory_sync.hooks import hook_auto_push; hook_auto_push()" %*\n',
+    }
+
+    created = []
+    for name, content in shims.items():
+        path = shim_dir / name
+        path.write_text(content)
+        created.append(str(path))
+
+    return created
+
+
+def install_hooks() -> None:
+    """Add auto-sync hooks to Claude Code settings."""
+    # On Windows, ensure command shims exist for PATH reliability
+    if sys.platform == "win32":
+        created = install_shims()
+        if created:
+            print(f"  Created command shims in {Path(created[0]).parent}")
+
+    settings = _load_settings()
+    hooks = settings.setdefault("hooks", [])
+
+    # Check if hooks already installed
+    existing_commands = set()
+    for hook_entry in hooks:
+        for h in hook_entry.get("hooks", []):
+            existing_commands.add(h.get("command", ""))
+
+    added = []
+    if "claude-memory-hook-pull" not in existing_commands:
+        hooks.append(HOOK_PULL)
+        added.append("pull (SessionStart)")
+    if "claude-memory-hook-push" not in existing_commands:
+        hooks.append(HOOK_PUSH)
+        added.append("push (Stop)")
+
+    if added:
+        _save_settings(settings)
+        for a in added:
+            print(f"  Installed hook: {a}")
+    else:
+        print("  Hooks already installed.")
+
+
+def remove_hooks() -> None:
+    """Remove auto-sync hooks from Claude Code settings."""
+    settings = _load_settings()
+    hooks = settings.get("hooks", [])
+    if not hooks:
+        print("  No hooks to remove.")
+        return
+
+    hook_commands = {"claude-memory-hook-pull", "claude-memory-hook-push"}
+    new_hooks = [
+        entry for entry in hooks
+        if not any(
+            h.get("command", "") in hook_commands
+            for h in entry.get("hooks", [])
+        )
+    ]
+
+    removed = len(hooks) - len(new_hooks)
+    if removed:
+        settings["hooks"] = new_hooks
+        _save_settings(settings)
+        print(f"  Removed {removed} hook(s).")
+    else:
+        print("  No memory sync hooks found.")
+
+
+def hook_auto_pull() -> None:
+    """Entry point for SessionStart hook — pull memory from remote."""
+    from .config import get_token, is_configured, load_config
+    from .github_api import GitHubAPI
+    from .sync_engine import SyncEngine
+
+    if not is_configured():
+        return
+
+    try:
+        config = load_config()
+        token = get_token()
+        api = GitHubAPI(config["github_repo"], token)
+        engine = SyncEngine(config, api)
+        result = engine.pull()
+        if result.pulled:
+            print(f"[claude-memory] Pulled: {', '.join(result.pulled)}", file=sys.stderr)
+        if result.errors:
+            for err in result.errors:
+                print(f"[claude-memory] Error: {err}", file=sys.stderr)
+    except Exception as e:
+        print(f"[claude-memory] Pull failed: {e}", file=sys.stderr)
+
+
+def hook_auto_push() -> None:
+    """Entry point for Stop hook — push memory to remote."""
+    from .config import get_token, is_configured, load_config
+    from .github_api import GitHubAPI
+    from .sync_engine import SyncEngine
+
+    if not is_configured():
+        return
+
+    try:
+        config = load_config()
+        token = get_token()
+        api = GitHubAPI(config["github_repo"], token)
+        engine = SyncEngine(config, api)
+        result = engine.push()
+        if result.pushed:
+            print(f"[claude-memory] Pushed: {', '.join(result.pushed)}", file=sys.stderr)
+        if result.errors:
+            for err in result.errors:
+                print(f"[claude-memory] Error: {err}", file=sys.stderr)
+    except Exception as e:
+        print(f"[claude-memory] Push failed: {e}", file=sys.stderr)