slots-cli 0.1.0__tar.gz

slots_cli-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: slots-cli
+Version: 0.1.0
+Summary: Save slots for coding projects.
+Home-page: https://slots.hohohocch.com
+Author: hohohocch
+Requires-Python: >=3.10
+Requires-Dist: colorama
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]; extra == "mcp"
+Dynamic: author
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

slots_cli-0.1.0/README.md

@@ -0,0 +1,186 @@
+![Slots repo banner](repo_banner.png)
+
+# Slots
+
+Save slots for your local directory - Checkpoint your progress along the way with no commitment.
+
+Slots is a small CLI for creating save slots inside a coding project. It is useful when you want to attempt a refactor, compare approaches, or let an AI coding agent make changes while keeping an easy restore point.
+
+## Installation
+
+```powershell
+pip install slots-cli
+```
+
+For MCP support:
+
+```powershell
+pip install "slots-cli[mcp]"
+```
+
+## Quickstart
+
+Create a save slot before making risky changes:
+
+```powershell
+slots init
+slots save before-refactor
+```
+
+Make your edits, then check what changed:
+
+```powershell
+slots status
+```
+
+```diff
+Difference from base state
+3 changed: 1 added, 1 modified, 1 removed
+
+Added (1)
++  new_feature.py
+
+Modified (1)
+!  app.py
+
+Removed (1)
+-  old_utils.py
+```
+
+Restore the save slot if you want to go back:
+
+```powershell
+slots load before-refactor
+```
+
+Undo the most recent load if you change your mind:
+
+```powershell
+slots revert
+```
+
+## Commands
+
+### Initialize
+
+```powershell
+slots init
+```
+
+Creates `.slots/` and records the base state. All saves are tied to the same base state.
+
+Refresh the base state:
+
+```powershell
+slots init --refresh
+```
+
+This clears existing save slots and aligns the base state with the current respository.
+
+### Save
+
+```powershell
+slots save before-refactor
+```
+
+Creates a named save slot from the current project state.
+
+### Status
+
+```powershell
+slots status
+```
+
+Shows differences between the current project and the base state.
+
+```powershell
+slots status --latest
+```
+
+Shows differences between the current project and the most recent save slot.
+
+### List
+
+```powershell
+slots list
+```
+
+Lists save slots.
+
+### Load
+
+```powershell
+slots load before-refactor
+```
+
+Loads added and modified files from a save slot.
+
+```powershell
+slots load before-refactor --remove-files
+```
+
+Also removes files that were deleted in the save slot.
+
+### Revert
+
+```powershell
+slots revert
+```
+
+Reverts the most recent load using the automatic pre-load backup.
+
+### Delete
+
+```powershell
+slots delete before-refactor
+```
+
+Deletes a save slot.
+
+### Reset
+
+```powershell
+slots reset
+```
+
+Deletes all Slots data from the project.
+
+## MCP Support
+
+Slots includes a MCP server so AI coding tools can create and restore save slots.
+
+Install with MCP support:
+
+```powershell
+pip install "slots-cli[mcp]"
+```
+
+Then run the MCP server:
+
+```powershell
+slots-mcp
+```
+
+### Common Installation commands:
+
+**Codex**
+
+```powershell
+codex mcp add slots -- slots-mcp
+```
+
+**Claude Code**
+
+```powershell
+claude mcp add slots -- slots-mcp
+```
+
+## Notes
+
+Slots is not a replacement for Git - it is designed to work alongside it as a lightweight local checkpoint tool.
+
+Before loading a slot, Slots creates a backup in `.slots/backups/`. You can restore the latest load with:
+
+```powershell
+slots revert
+```

slots_cli-0.1.0/setup.cfg

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

slots_cli-0.1.0/setup.py

@@ -0,0 +1,22 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="slots-cli",
+    version="0.1.0",
+    packages=find_packages(),
+    description="Save slots for coding projects.",
+    author="hohohocch",
+    url="https://slots.hohohocch.com",
+    python_requires=">=3.10",
+    install_requires=["colorama"],
+    entry_points={
+        "console_scripts": [
+            "slots = slots.__main__:main",
+            "slots-mcp = slots.slots_mcp:main",
+        ],
+    },
+    extras_require={
+        "dev": ["pytest"],
+        "mcp": ["mcp[cli]"],
+    },
+)

slots_cli-0.1.0/slots/__init__.py

@@ -0,0 +1,3 @@
+from slots.slots import Slots
+
+__all__ = ["Slots"]

slots_cli-0.1.0/slots/__main__.py

@@ -0,0 +1,66 @@
+import argparse
+from slots.slots import Slots
+
+def main():
+    slots = Slots()
+
+    parser = argparse.ArgumentParser(description="Slots - Save slots for coding projects.")
+
+    subparsers = parser.add_subparsers(title="Commands", dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Initialize slots")
+    init_parser.add_argument("--refresh", action="store_true", help="Update base to current repository state.")
+
+    save_parser = subparsers.add_parser("save", help="Save current repository.")
+    save_parser.add_argument("name")
+
+    reset_parser = subparsers.add_parser("reset", help="Destroys all slot-related files and folders.")
+
+    load_parser = subparsers.add_parser("load", help="Load a save slot.")
+    load_parser.add_argument("name")
+    load_parser.add_argument("--remove-files", action="store_true", help="Remove files that were deleted in the slot.")
+
+    delete_parser = subparsers.add_parser("delete", help="Delete a save slot.")
+    delete_parser.add_argument("name")
+
+    list_parser = subparsers.add_parser("list", help="List save slots.")
+
+    revert_parser = subparsers.add_parser("revert", help="Revert the last load.")
+
+    status_parser = subparsers.add_parser("status", help="View differences between current repository and base state.")
+    status_parser.add_argument("--latest", action="store_true", help="Compare current repository to the most recent save.")
+
+    args = parser.parse_args()
+
+    match args.command:
+        case "init":
+            slots.init(args)
+        
+        case "save":
+            slots.save(args)
+        
+        case "reset":
+            slots.reset()
+
+        case "load":
+            slots.load(args)
+        
+        case "list":
+            slots.list()
+
+        case "delete":
+            slots.delete(args)
+
+        case "revert":
+            slots.revert()
+        
+        case "status":
+            slots.status(args)
+
+        case _:
+            print("Command not found. Use --help for list of commands.")
+
+
+if __name__ == "__main__":
+    main()
+

slots_cli-0.1.0/slots/load.py

@@ -0,0 +1,214 @@
+import json
+import shutil
+from datetime import datetime, timezone
+
+from colorama import Fore
+
+from slots.save import save_current_directory
+from slots.utils import atomic_json, copy_to_destination, remove_file_path, safe_project_path, safe_storage_path
+
+def read_slot_layout(path):
+    with open(path, "r", encoding="utf-8") as file:
+        try:
+            layout = json.load(file)
+        except json.JSONDecodeError:
+            print(Fore.RED + f"Cannot load slot: {path.name} is malformed.")
+            return None
+
+    for key in ("added", "modified", "removed"):
+        if not isinstance(layout.get(key), list):
+            print(Fore.RED + f"Cannot load slot: layout.json missing '{key}' list.")
+            return None
+
+    return layout
+
+def create_load_backup(root, base_dir, backups_dir, slot_name, touched_paths):
+    backups_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+
+    backup_name = f"pre-load-{slot_name}-{timestamp}"
+    if not save_current_directory(root, backup_name, base_dir, backups_dir):
+        return None
+
+    restore_path = backups_dir / backup_name / "restore.json"
+
+    atomic_json(restore_path, {"touched": sorted(set(touched_paths))})
+    
+
+    return backup_name
+
+def load_save(name, saves_dir, base_dir, backups_dir, root, removeFiles=False):
+    save_dir = saves_dir / name
+    layout_path = save_dir / "layout.json"
+
+    if not layout_path.exists() or not (base_dir / "layout.json").exists():
+        print(Fore.RED + f"Cannot load slot '{name}': layout.json missing.")
+        return False
+
+    layout = read_slot_layout(layout_path)
+    if layout is None:
+        return False
+
+    paths_to_copy = layout["added"] + layout["modified"]
+    paths_to_remove = layout["removed"] if removeFiles else []
+
+    try:
+        copy_operations = []
+        saved_files_dir = save_dir / "files"
+        for file_path in paths_to_copy:
+            destination = safe_project_path(root, file_path)
+            source = safe_storage_path(saved_files_dir, file_path)
+            copy_operations.append((source, destination))
+
+        remove_operations = [safe_project_path(root, file_path) for file_path in paths_to_remove]
+    except ValueError as error:
+        print(Fore.RED + str(error))
+        return False
+
+    for source, _ in copy_operations:
+        if not source.exists():
+            print(Fore.RED + f"Cannot load slot: saved file missing: {source}")
+            return False
+
+    for path in remove_operations:
+        if path.exists() and path.is_dir():
+            print(Fore.RED + f"Refusing to remove directory during load: {path}")
+            return False
+
+    try:
+        backup_name = create_load_backup(root, base_dir, backups_dir, name, paths_to_copy + paths_to_remove)
+    except (OSError, json.JSONDecodeError) as error:
+        print(Fore.RED + f"Cannot create pre-load backup: {error}")
+        return False
+
+    if backup_name is None:
+        return False
+
+    try:
+        for source, destination in copy_operations:
+            copy_to_destination(source, destination)
+
+        for path in sorted(remove_operations, key=lambda item: len(item.parts), reverse=True):
+            remove_file_path(path)
+
+    except (OSError, shutil.Error) as error:
+        print(Fore.RED + f"Load failed: {error}")
+        print(Fore.YELLOW + f"Run 'slots revert' to restore backup '{backup_name}'.")
+        return False
+
+    return True
+
+def find_latest_backup(backups_dir):
+    latest_backup = None
+    latest_time = None
+
+    for backup in backups_dir.iterdir():
+        info_path = backup / "info.json"
+
+        if not backup.is_dir() or not info_path.exists():
+            continue
+
+        with open(info_path, "r", encoding="utf-8") as file:
+            try:
+                info = json.load(file)
+            except json.JSONDecodeError:
+                continue
+
+        try:
+            saved_time = datetime.fromisoformat(info["time"])
+        except (KeyError, TypeError, ValueError):
+            continue
+
+        if latest_time is None or saved_time > latest_time:
+            latest_backup = backup
+            latest_time = saved_time
+
+    return latest_backup
+
+def read_restore_manifest(path):
+    if not path.exists():
+        print(Fore.RED + "Cannot revert: restore.json missing.")
+        return None
+
+    with open(path, "r", encoding="utf-8") as file:
+        try:
+            manifest = json.load(file)
+        except json.JSONDecodeError:
+            print(Fore.RED + "Cannot revert: restore.json is malformed.")
+            return None
+
+    if not isinstance(manifest.get("touched"), list):
+        print(Fore.RED + "Cannot revert: restore.json missing 'touched' list.")
+        return None
+
+    return manifest
+
+def revert_latest(root, base_dir, backups_dir):
+    backup = find_latest_backup(backups_dir)
+
+    if backup is None:
+        print(Fore.RED + "No load backup found.")
+        return False
+
+    layout = read_slot_layout(backup / "layout.json")
+    if layout is None:
+        return False
+
+    manifest = read_restore_manifest(backup / "restore.json")
+    if manifest is None:
+        return False
+
+    try:
+        with open(base_dir / "layout.json", "r", encoding="utf-8") as file:
+            base_layout = json.load(file)
+    except (OSError, json.JSONDecodeError) as error:
+        print(Fore.RED + f"Cannot revert: base layout unavailable: {error}")
+        return False
+
+    backup_paths = set(layout["added"] + layout["modified"])
+    removed_before_load = set(layout["removed"])
+
+    try:
+        copy_operations = []
+        remove_operations = []
+        backup_files_dir = backup / "files"
+        base_files_dir = base_dir / "files"
+
+        for file_path in manifest["touched"]:
+            destination = safe_project_path(root, file_path)
+
+            if file_path in backup_paths:
+                source = safe_storage_path(backup_files_dir, file_path)
+                copy_operations.append((source, destination))
+            elif file_path in removed_before_load or file_path not in base_layout:
+                remove_operations.append(destination)
+            else:
+                source = safe_storage_path(base_files_dir, file_path)
+                copy_operations.append((source, destination))
+
+    except ValueError as error:
+        print(Fore.RED + str(error))
+        return False
+
+    for source, _ in copy_operations:
+        if not source.exists():
+            print(Fore.RED + f"Cannot revert: backup file missing: {source}")
+            return False
+
+    for path in remove_operations:
+        if path.exists() and path.is_dir():
+            print(Fore.RED + f"Refusing to remove directory during revert: {path}")
+            return False
+
+    try:
+        for source, destination in copy_operations:
+            copy_to_destination(source, destination)
+
+        for path in sorted(remove_operations, key=lambda item: len(item.parts), reverse=True):
+            remove_file_path(path)
+
+    except OSError as error:
+        print(Fore.RED + f"Revert failed: {error}")
+        return False
+
+    return True

slots_cli-0.1.0/slots/save.py

@@ -0,0 +1,108 @@
+import json
+import shutil
+from datetime import datetime, timezone
+
+from colorama import Fore
+
+from slots.utils import (
+    copy_to_destination,
+    create_layout,
+    safe_project_path,
+    safe_storage_path,
+    should_ignore,
+    slots_dir_name,
+    atomic_json
+)
+
+def create_base(root):
+    base_dir = root / slots_dir_name / "base"
+    base_files_dir = base_dir / "files"
+
+    for item in root.iterdir():
+        if should_ignore(item, root) or item.is_symlink():
+            continue
+
+        destination = base_files_dir / item.name
+
+        if destination.exists():
+            continue
+
+        try:
+            copy_to_destination(item, destination)
+        except PermissionError:
+            print(Fore.RED + f"Skipped {item} - Currently in use or no permission.")
+
+def refresh_base(root):
+    base_dir = root / slots_dir_name / "base"
+    base_files_dir = base_dir / "files"
+
+    if base_dir.exists():
+        shutil.rmtree(base_dir)
+
+    base_files_dir.mkdir(parents=True, exist_ok=True)
+    create_base(root)
+
+    base_layout = create_layout(base_files_dir)
+
+    atomic_json(base_dir / "layout.json", base_layout)
+
+def save_current_directory(root, name, base_dir, saves_dir):
+    current_layout = create_layout(root)
+
+    with open(base_dir / "layout.json", "r", encoding="utf-8") as base_layout_file:
+        base_layout = json.load(base_layout_file)
+
+    try:
+        for file_path in base_layout:
+            safe_project_path(root, file_path)
+    except ValueError as error:
+        print(Fore.RED + f"Cannot save: {error}")
+        return False
+
+    base_paths = set(base_layout)
+    current_paths = set(current_layout)
+
+    added = current_paths - base_paths
+    removed = base_paths - current_paths
+    shared = base_paths & current_paths
+
+    modified_files = []
+
+    for file_path in shared:
+        if base_layout[file_path]["hash"] != current_layout[file_path]["hash"]:
+            modified_files.append(file_path)
+
+    current_save_dir = saves_dir / name
+    saved_files_dir = current_save_dir / "files"
+    current_save_dir.mkdir(parents=True, exist_ok=True)
+    saved_files_dir.mkdir(parents=True, exist_ok=True)
+
+    atomic_json(current_save_dir / "info.json", {
+            "name": name,
+            "time": datetime.now(timezone.utc).isoformat()
+        })
+    
+    atomic_json(current_save_dir / "layout.json", {
+            "added": sorted(added),
+            "removed": sorted(removed),
+            "modified": sorted(modified_files)
+        })
+
+    # TODO: switch to diff saving instead of saving entire files
+    for file_path in list(modified_files) + list(added):
+        try:
+            source = safe_project_path(root, file_path)
+            destination = safe_storage_path(saved_files_dir, file_path)
+        except ValueError as error:
+            print(Fore.RED + f"Cannot save: {error}")
+            return False
+
+        if not source.exists():
+            continue
+
+        try:
+            copy_to_destination(source, destination)
+        except PermissionError:
+            print(Fore.RED + f"Skipped {source} - Currently in use or no permission.")
+
+    return True