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

claude_memory_sync/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Memory Sync - Sync Claude Code memory files across machines via GitHub."""
+
+__version__ = "0.2.0"

claude_memory_sync/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m claude_memory_sync`."""
+
+from .cli import main
+
+main()

claude_memory_sync/alias.py

@@ -0,0 +1,122 @@
+"""Cross-platform project aliasing for matching projects across machines."""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+
+from .config import load_config, save_config
+from .github_api import GitHubAPI
+from .paths import project_dirname_to_display
+
+
+REMOTE_ALIASES_PATH = "_meta/aliases.json"
+
+
+def _get_aliases(config: dict | None = None) -> dict[str, list[str]]:
+    if config is None:
+        config = load_config()
+    return config.get("aliases", {})
+
+
+def add_alias(alias: str, dirname: str | None = None) -> None:
+    """Add a project dirname to an alias. Creates alias if new."""
+    if dirname is None:
+        from .discovery import get_current_project
+        dirname = get_current_project()
+        if dirname is None:
+            raise RuntimeError("Cannot detect current project. Specify a dirname explicitly.")
+
+    config = load_config()
+    aliases = config.setdefault("aliases", {})
+    dirnames = aliases.setdefault(alias, [])
+    if dirname not in dirnames:
+        dirnames.append(dirname)
+    save_config(config)
+
+
+def remove_alias(alias: str) -> None:
+    """Remove an alias entirely."""
+    config = load_config()
+    aliases = config.get("aliases", {})
+    if alias in aliases:
+        del aliases[alias]
+        save_config(config)
+
+
+def list_aliases() -> dict[str, list[str]]:
+    """Return all aliases as alias -> list of dirnames."""
+    return _get_aliases()
+
+
+def resolve_alias(dirname: str) -> str:
+    """Given a project dirname, return its alias (or dirname if no alias)."""
+    aliases = _get_aliases()
+    for alias, dirnames in aliases.items():
+        if dirname in dirnames:
+            return alias
+    return dirname
+
+
+def resolve_dirname(alias: str) -> list[str]:
+    """Given an alias, return all associated dirnames."""
+    aliases = _get_aliases()
+    return aliases.get(alias, [])
+
+
+def suggest_aliases(dirnames: list[str]) -> dict[str, list[str]]:
+    """Auto-match heuristic: group dirnames that share the same leaf directory name.
+
+    For example, if two machines both have projects ending in "my-project",
+    they likely refer to the same project.
+    """
+    by_leaf: dict[str, list[str]] = defaultdict(list)
+    for dirname in dirnames:
+        # Get the last path component from the display path
+        display = project_dirname_to_display(dirname)
+        leaf = display.rstrip("/").rsplit("/", 1)[-1]
+        by_leaf[leaf].append(dirname)
+
+    # Only suggest aliases for groups with more than one dirname
+    return {leaf: dns for leaf, dns in by_leaf.items() if len(dns) > 1}
+
+
+def sync_aliases_to_remote(api: GitHubAPI) -> None:
+    """Push local aliases to _meta/aliases.json in the repo."""
+    aliases = _get_aliases()
+    content = json.dumps(aliases, indent=2)
+
+    existing = api.get_file(REMOTE_ALIASES_PATH)
+    sha = existing["sha"] if existing else None
+    api.put_file(
+        REMOTE_ALIASES_PATH,
+        content,
+        "Update aliases",
+        sha=sha,
+    )
+
+
+def get_remote_project_dirnames(api: GitHubAPI) -> list[str]:
+    """List all project directory names on the remote repo."""
+    items = api.list_dir("projects")
+    return [item["name"] for item in items if item["type"] == "dir"]
+
+
+def sync_aliases_from_remote(api: GitHubAPI) -> None:
+    """Pull remote aliases and merge into local config."""
+    existing = api.get_file(REMOTE_ALIASES_PATH)
+    if existing is None:
+        return
+
+    remote_aliases = json.loads(existing["content"])
+    config = load_config()
+    local_aliases = config.setdefault("aliases", {})
+
+    # Merge: union of dirnames for each alias
+    for alias, dirnames in remote_aliases.items():
+        local_list = local_aliases.setdefault(alias, [])
+        for d in dirnames:
+            if d not in local_list:
+                local_list.append(d)
+
+    save_config(config)

claude_memory_sync/cli.py

@@ -0,0 +1,454 @@
+"""CLI entry point for Claude Memory Sync."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def _is_tty() -> bool:
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _bold(text: str) -> str:
+    return f"\033[1m{text}\033[0m" if _is_tty() else text
+
+
+def _green(text: str) -> str:
+    return f"\033[32m{text}\033[0m" if _is_tty() else text
+
+
+def _red(text: str) -> str:
+    return f"\033[31m{text}\033[0m" if _is_tty() else text
+
+
+def _yellow(text: str) -> str:
+    return f"\033[33m{text}\033[0m" if _is_tty() else text
+
+
+def _require_config() -> bool:
+    """Check if the tool is configured. Print error and return False if not."""
+    from .config import is_configured
+    if not is_configured():
+        print(_red("Not configured. Run `claude-memory setup` first."))
+        return False
+    return True
+
+
+def _make_engine():
+    """Create a SyncEngine from current config."""
+    from .config import get_token, load_config
+    from .github_api import GitHubAPI
+    from .sync_engine import SyncEngine
+
+    config = load_config()
+    token = get_token()
+    api = GitHubAPI(config["github_repo"], token)
+    return SyncEngine(config, api)
+
+
+def _print_sync_result(result) -> None:
+    """Print a SyncResult in a readable format."""
+    if result.pushed:
+        print(_green(f"  Pushed: {', '.join(result.pushed)}"))
+    if result.pulled:
+        print(_green(f"  Pulled: {', '.join(result.pulled)}"))
+    if result.conflicts:
+        print(_yellow(f"  Conflicts: {', '.join(result.conflicts)}"))
+    if result.skipped:
+        print(f"  Skipped (no changes): {', '.join(result.skipped)}")
+    if result.errors:
+        for err in result.errors:
+            print(_red(f"  Error: {err}"))
+    if not any([result.pushed, result.pulled, result.conflicts, result.errors]):
+        print("  Everything up to date.")
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    """Run setup wizard."""
+    from .config import setup_wizard
+    setup_wizard()
+    # Auto-install shims on Windows
+    import sys as _sys
+    if _sys.platform == "win32":
+        from .hooks import install_shims
+        created = install_shims()
+        if created:
+            from pathlib import Path
+            print(f"\nCommand shims installed in {Path(created[0]).parent}")
+            print("You can now run `claude-memory` from any terminal.")
+
+
+def cmd_setup_path(args: argparse.Namespace) -> None:
+    """Fix PATH issues on Windows by creating command shims."""
+    import sys as _sys
+    if _sys.platform != "win32":
+        print("This command is only needed on Windows.")
+        return
+    from .hooks import install_shims
+    created = install_shims()
+    if created:
+        from pathlib import Path
+        print(_green(f"Created command shims in {Path(created[0]).parent}:"))
+        for path in created:
+            print(f"  {Path(path).name}")
+        print("\nYou can now run `claude-memory` from any terminal.")
+    else:
+        print("No shims needed.")
+
+
+def cmd_push(args: argparse.Namespace) -> None:
+    """Push local memory to GitHub."""
+    if not _require_config():
+        sys.exit(1)
+    engine = _make_engine()
+    if args.dry_run:
+        print(_bold("Dry run — no changes will be made."))
+    result = engine.push(alias=args.project, dry_run=args.dry_run)
+    _print_sync_result(result)
+    if result.errors:
+        sys.exit(1)
+
+
+def cmd_pull(args: argparse.Namespace) -> None:
+    """Pull memory from GitHub."""
+    if not _require_config():
+        sys.exit(1)
+    engine = _make_engine()
+    if args.dry_run:
+        print(_bold("Dry run — no changes will be made."))
+    result = engine.pull(alias=args.project, dry_run=args.dry_run)
+    _print_sync_result(result)
+    if result.errors:
+        sys.exit(1)
+
+
+def cmd_sync(args: argparse.Namespace) -> None:
+    """Bidirectional sync."""
+    if not _require_config():
+        sys.exit(1)
+    engine = _make_engine()
+    if args.dry_run:
+        print(_bold("Dry run — no changes will be made."))
+    result = engine.sync(alias=args.project, dry_run=args.dry_run)
+    _print_sync_result(result)
+    if result.errors:
+        sys.exit(1)
+
+
+def cmd_alias(args: argparse.Namespace) -> None:
+    """Manage project aliases."""
+    from .alias import (
+        add_alias,
+        get_remote_project_dirnames,
+        list_aliases,
+        remove_alias,
+        suggest_aliases,
+        sync_aliases_from_remote,
+        sync_aliases_to_remote,
+    )
+    from .discovery import discover_projects
+    from .paths import project_dirname_to_display
+
+    if args.alias_command == "add":
+        add_alias(args.name, dirname=args.dirname)
+        print(_green(f"Added alias '{args.name}'."))
+    elif args.alias_command == "remove":
+        remove_alias(args.name)
+        print(f"Removed alias '{args.name}'.")
+    elif args.alias_command == "list":
+        aliases = list_aliases()
+        if not aliases:
+            print("No aliases configured.")
+            return
+        for name, dirnames in aliases.items():
+            print(_bold(name))
+            for d in dirnames:
+                display = project_dirname_to_display(d)
+                print(f"  {d} ({display})")
+    elif args.alias_command == "suggest":
+        # Gather dirnames from local projects and remote
+        local_dirnames = [p["dirname"] for p in discover_projects() if p["has_memory"]]
+        remote_dirnames = []
+        if _require_config():
+            from .config import get_token, load_config
+            from .github_api import GitHubAPI
+            config = load_config()
+            try:
+                token = get_token()
+                api = GitHubAPI(config["github_repo"], token)
+                remote_dirnames = get_remote_project_dirnames(api)
+            except RuntimeError:
+                pass
+        all_dirnames = list(set(local_dirnames + remote_dirnames))
+        suggestions = suggest_aliases(all_dirnames)
+        if not suggestions:
+            print("No alias suggestions found.")
+            return
+        print(_bold("Suggested aliases:"))
+        for alias, dirnames in suggestions.items():
+            print(f"\n  {_bold(alias)}:")
+            for d in dirnames:
+                display = project_dirname_to_display(d)
+                print(f"    {d} ({display})")
+    elif args.alias_command == "auto":
+        local_dirnames = [p["dirname"] for p in discover_projects() if p["has_memory"]]
+        remote_dirnames = []
+        if not _require_config():
+            sys.exit(1)
+        from .config import get_token, load_config
+        from .github_api import GitHubAPI
+        config = load_config()
+        token = get_token()
+        api = GitHubAPI(config["github_repo"], token)
+        remote_dirnames = get_remote_project_dirnames(api)
+        all_dirnames = list(set(local_dirnames + remote_dirnames))
+        suggestions = suggest_aliases(all_dirnames)
+        if not suggestions:
+            print("No alias suggestions found.")
+            return
+        if args.dry_run:
+            print(_bold("Dry run — would create these aliases:"))
+            for alias, dirnames in suggestions.items():
+                print(f"  {alias}: {dirnames}")
+            return
+        for alias, dirnames in suggestions.items():
+            for d in dirnames:
+                add_alias(alias, d)
+            print(_green(f"Created alias '{alias}' with {len(dirnames)} dirnames."))
+        sync_aliases_to_remote(api)
+        print(_green("Aliases pushed to remote."))
+    elif args.alias_command == "sync":
+        if not _require_config():
+            sys.exit(1)
+        from .config import get_token, load_config
+        from .github_api import GitHubAPI
+        config = load_config()
+        token = get_token()
+        api = GitHubAPI(config["github_repo"], token)
+        if args.push:
+            sync_aliases_to_remote(api)
+            print(_green("Aliases pushed to remote."))
+        elif args.pull:
+            sync_aliases_from_remote(api)
+            print(_green("Aliases pulled from remote."))
+        else:
+            sync_aliases_from_remote(api)
+            sync_aliases_to_remote(api)
+            print(_green("Aliases synced (pull then push)."))
+    elif args.alias_command == "migrate":
+        if not _require_config():
+            sys.exit(1)
+        engine = _make_engine()
+        result = engine.migrate_to_alias(args.dirname, args.alias)
+        if result["migrated"]:
+            print(_green(f"Migrated: {', '.join(result['migrated'])}"))
+        if result["errors"]:
+            for err in result["errors"]:
+                print(_red(f"Error: {err}"))
+            sys.exit(1)
+        if not result["migrated"] and not result["errors"]:
+            print("Nothing to migrate.")
+    else:
+        print("Use: alias {add,remove,list,suggest,auto,sync,migrate}")
+
+
+def cmd_hooks(args: argparse.Namespace) -> None:
+    """Manage auto-sync hooks."""
+    from .hooks import install_hooks, remove_hooks
+
+    if args.hooks_command == "install":
+        print(_bold("Installing Claude Code hooks..."))
+        install_hooks()
+        print(_green("Done. Memory will auto-sync on session start/stop."))
+    elif args.hooks_command == "remove":
+        print(_bold("Removing Claude Code hooks..."))
+        remove_hooks()
+        print("Done.")
+    else:
+        print("Use: hooks {install,remove}")
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    """Show sync status."""
+    if not _require_config():
+        sys.exit(1)
+
+    from .config import load_config
+    from .discovery import discover_projects
+    from .paths import get_state_file
+
+    config = load_config()
+    print(_bold("Configuration:"))
+    print(f"  Device: {config.get('device_name', 'not set')}")
+    print(f"  Repo:   {config.get('github_repo', 'not set')}")
+    print(f"  Strategy: {config.get('conflict_strategy', 'merge')}")
+    print()
+
+    projects = discover_projects()
+    memory_projects = [p for p in projects if p["has_memory"]]
+    print(_bold(f"Local projects with memory: {len(memory_projects)}"))
+    for p in memory_projects:
+        files = [f.name for f in p["memory_files"]]
+        print(f"  {p['dirname']}: {', '.join(files)}")
+    print()
+
+    engine = _make_engine()
+    if engine.state:
+        print(_bold("Sync state:"))
+        for key, info in sorted(engine.state.items()):
+            last_sync = info.get("last_sync", "never")
+            print(f"  {key}: last synced {last_sync}")
+    else:
+        print("No sync history yet.")
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Diagnose issues."""
+    from .config import get_token, is_configured, load_config
+    from .discovery import discover_projects
+    from .github_api import GitHubAPI
+
+    checks_passed = 0
+    checks_total = 0
+
+    # Check 1: Config exists
+    checks_total += 1
+    if is_configured():
+        print(_green("[OK] Configuration found."))
+        checks_passed += 1
+    else:
+        print(_red("[FAIL] Not configured. Run `claude-memory setup`."))
+
+    # Check 2: Token available
+    checks_total += 1
+    try:
+        token = get_token()
+        print(_green(f"[OK] GitHub token found ({token[:4]}...)."))
+        checks_passed += 1
+    except RuntimeError as e:
+        print(_red(f"[FAIL] {e}"))
+        token = None
+
+    # Check 3: Repo accessible
+    checks_total += 1
+    config = load_config()
+    repo = config.get("github_repo", "")
+    if token and repo:
+        api = GitHubAPI(repo, token)
+        if api.test_connection():
+            print(_green(f"[OK] Repository '{repo}' is accessible."))
+            checks_passed += 1
+        else:
+            print(_red(f"[FAIL] Cannot access repository '{repo}'."))
+    else:
+        print(_yellow("[SKIP] Cannot test repo access (missing token or repo)."))
+
+    # Check 4: Local memory dirs
+    checks_total += 1
+    projects = discover_projects()
+    memory_projects = [p for p in projects if p["has_memory"]]
+    if memory_projects:
+        print(_green(f"[OK] Found {len(memory_projects)} project(s) with memory files."))
+        checks_passed += 1
+    else:
+        print(_yellow("[WARN] No local projects with memory files found."))
+
+    print(f"\n{checks_passed}/{checks_total} checks passed.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="claude-memory",
+        description="Sync Claude Code memory files across machines via GitHub.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # setup
+    subparsers.add_parser("setup", help="Run interactive setup wizard")
+
+    # setup-path
+    subparsers.add_parser("setup-path", help="Fix PATH issues on Windows (create command shims)")
+
+    # push
+    push_parser = subparsers.add_parser("push", help="Upload local memory to GitHub")
+    push_parser.add_argument("--dry-run", action="store_true", help="Show what would be done")
+    push_parser.add_argument("--project", type=str, default=None, help="Project alias or dirname")
+
+    # pull
+    pull_parser = subparsers.add_parser("pull", help="Download memory from GitHub")
+    pull_parser.add_argument("--dry-run", action="store_true", help="Show what would be done")
+    pull_parser.add_argument("--project", type=str, default=None, help="Project alias or dirname")
+
+    # sync
+    sync_parser = subparsers.add_parser("sync", help="Bidirectional sync")
+    sync_parser.add_argument("--dry-run", action="store_true", help="Show what would be done")
+    sync_parser.add_argument("--project", type=str, default=None, help="Project alias or dirname")
+
+    # alias
+    alias_parser = subparsers.add_parser("alias", help="Manage project aliases")
+    alias_sub = alias_parser.add_subparsers(dest="alias_command")
+    add_parser = alias_sub.add_parser("add", help="Add an alias")
+    add_parser.add_argument("name", help="Alias name")
+    add_parser.add_argument("--dirname", type=str, default=None, help="Project dirname (default: current)")
+    remove_parser = alias_sub.add_parser("remove", help="Remove an alias")
+    remove_parser.add_argument("name", help="Alias name to remove")
+    alias_sub.add_parser("list", help="List all aliases")
+    alias_sub.add_parser("suggest", help="Show suggested alias mappings")
+    auto_parser = alias_sub.add_parser("auto", help="Auto-create aliases from suggestions")
+    auto_parser.add_argument("--dry-run", action="store_true", help="Show what would be done")
+    sync_alias_parser = alias_sub.add_parser("sync", help="Sync aliases to/from remote")
+    sync_alias_parser.add_argument("--push", action="store_true", help="Push aliases to remote")
+    sync_alias_parser.add_argument("--pull", action="store_true", help="Pull aliases from remote")
+    migrate_parser = alias_sub.add_parser("migrate", help="Migrate remote data to alias path")
+    migrate_parser.add_argument("--dirname", required=True, help="Source dirname on remote")
+    migrate_parser.add_argument("--alias", required=True, help="Target alias name")
+
+    # hooks
+    hooks_parser = subparsers.add_parser("hooks", help="Manage auto-sync hooks")
+    hooks_sub = hooks_parser.add_subparsers(dest="hooks_command")
+    hooks_sub.add_parser("install", help="Install Claude Code auto-sync hooks")
+    hooks_sub.add_parser("remove", help="Remove Claude Code auto-sync hooks")
+
+    # status
+    subparsers.add_parser("status", help="Show sync status")
+
+    # doctor
+    subparsers.add_parser("doctor", help="Diagnose configuration issues")
+
+    return parser
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    commands = {
+        "setup": cmd_setup,
+        "setup-path": cmd_setup_path,
+        "push": cmd_push,
+        "pull": cmd_pull,
+        "sync": cmd_sync,
+        "alias": cmd_alias,
+        "hooks": cmd_hooks,
+        "status": cmd_status,
+        "doctor": cmd_doctor,
+    }
+
+    handler = commands.get(args.command)
+    if handler:
+        handler(args)
+    else:
+        parser.print_help()