study-sync 1.0.2__py3-none-any.whl

study_sync-1.0.2.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: study_sync
+Version: 1.0.2
+Summary: Offline-first, distributed workspace synchronisation CLI for developers.
+Author-email: Adinath <adinarayan.is23@bmsce.ac.in>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/studysync
+Project-URL: Documentation, https://github.com/yourusername/studysync#readme
+Project-URL: Bug Tracker, https://github.com/yourusername/studysync/issues
+Project-URL: Changelog, https://github.com/yourusername/studysync/releases
+Keywords: sync,cli,workspace,distributed,version-control,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"

study_sync-1.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+studysync/__init__.py,sha256=WQzSeHGy6cXWOZB3LggOyYU0_REVbByfThkGpArhTa4,52
+studysync/constants.py,sha256=plWVYDCAgYjmxvIybxYyZmyjjzedj_IButm0wrA-KRM,865
+studysync/local_state.py,sha256=hp8gKCmENs3pPONnp6np5hWNGbjlMfhD1hz7TE9gIyk,5750
+studysync/main.py,sha256=A6OwZkohasoPIPPbXxlMgoldkgKFXJUiGabB9oNkjUM,7829
+studysync/sync_engine.py,sha256=MVsuUOucIuiXQNc3zHy7f6OuNbvnXudXWSxgLqY5oMQ,21555
+study_sync-1.0.2.dist-info/METADATA,sha256=T-sYR24ciWwdMi4ZBVivSyq9mNHfqzioe7WvbiDrq1A,1538
+study_sync-1.0.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+study_sync-1.0.2.dist-info/entry_points.txt,sha256=DvLnzQ-Gyy5mxQWLikJDLrg-UYeKVJBoRb6FxlIw0fQ,45
+study_sync-1.0.2.dist-info/top_level.txt,sha256=0LsVKlsecuVpDNNp5xCLfkGnvEwjrNXH4hjVuFEZLZY,10
+study_sync-1.0.2.dist-info/RECORD,,

study_sync-1.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

study_sync-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+study = studysync.main:app

study_sync-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+studysync

studysync/__init__.py

@@ -0,0 +1,3 @@
+"""StudySync CLI package."""
+
+__version__ = "0.1.0"

studysync/constants.py

@@ -0,0 +1,18 @@
+"""
+constants.py — Package-wide constants for StudySync CLI.
+
+PRODUCTION_SERVER_URL is the single source of truth for the default backend.
+It is used as the fallback in every network call so users who install via
+`pip install studysync` can run `study join <TOKEN>` immediately — no
+--server flag required.
+
+Advanced users hosting their own backend can override this at any point:
+    study workspace create my-ws --server http://192.168.1.42:8000
+    study join <TOKEN>           --server https://my-own-instance.com
+The chosen URL is persisted to ~/.study/config.json after the first use,
+so subsequent commands pick it up automatically.
+"""
+
+# The public StudySync backend.  Update this constant when the production
+# deployment URL changes and bump the package version accordingly.
+PRODUCTION_SERVER_URL: str = "https://studysync-backend-pfft.onrender.com"

studysync/local_state.py

@@ -0,0 +1,183 @@
+"""
+local_state.py — filesystem layout, hashing, manifest, and config I/O.
+
+Directory structure
+-------------------
+~/.study/
+    config.json          — active workspace config (token, server URL, …)
+    manifest.json        — local state: {file_path: {version, checksum}}
+    workspaces/
+        <workspace_name>/
+            …            — local copies of synced files (mirror of remote)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Root paths
+# ---------------------------------------------------------------------------
+
+STUDY_DIR: Path = Path.home() / ".study"
+CONFIG_PATH: Path = STUDY_DIR / "config.json"
+MANIFEST_PATH: Path = STUDY_DIR / "manifest.json"
+WORKSPACES_DIR: Path = STUDY_DIR / "workspaces"
+
+
+def ensure_dirs() -> None:
+    """Create the ~/.study/ directory tree if it does not already exist."""
+    STUDY_DIR.mkdir(parents=True, exist_ok=True)
+    WORKSPACES_DIR.mkdir(parents=True, exist_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# Hashing
+# ---------------------------------------------------------------------------
+
+HASH_CHUNK_SIZE = 65_536  # 64 KiB
+
+
+def sha256_file(path: Path) -> str:
+    """
+    Return the lowercase SHA-256 hex digest of the file at *path*.
+
+    Reads in chunks to handle arbitrarily large files without loading
+    everything into memory.
+    """
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(HASH_CHUNK_SIZE), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Config  (~/.study/config.json)
+# ---------------------------------------------------------------------------
+
+def load_config() -> dict:
+    """Return the config dict, or {} if it has not been created yet."""
+    if not CONFIG_PATH.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def save_config(config: dict) -> None:
+    ensure_dirs()
+    CONFIG_PATH.write_text(json.dumps(config, indent=2), encoding="utf-8")
+
+
+def get_config_value(key: str) -> Optional[str]:
+    return load_config().get(key)
+
+
+# ---------------------------------------------------------------------------
+# Manifest  (~/.study/manifest.json)
+# ---------------------------------------------------------------------------
+#
+# Schema:
+# {
+#   "src/main.py": {"version": 3, "checksum": "abcdef..."},
+#   "docs/README.md": {"version": 1, "checksum": "123456..."}
+# }
+
+def load_manifest() -> dict:
+    """Return the manifest dict, or {} if not yet initialised."""
+    if not MANIFEST_PATH.exists():
+        return {}
+    try:
+        return json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def save_manifest(manifest: dict) -> None:
+    ensure_dirs()
+    MANIFEST_PATH.write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def get_manifest_entry(file_path: str) -> Optional[dict]:
+    """Return the manifest entry for *file_path*, or None if untracked."""
+    return load_manifest().get(file_path)
+
+
+def update_manifest_entry(file_path: str, version: int, checksum: str) -> None:
+    """
+    Upsert a single manifest entry after a successful push or pull.
+    Thread-safety note: for a single-user CLI this is fine; no locking needed.
+    """
+    manifest = load_manifest()
+    manifest[file_path] = {"version": version, "checksum": checksum}
+    save_manifest(manifest)
+
+
+def remove_manifest_entry(file_path: str) -> None:
+    """Remove a file from the manifest (e.g. after a local delete)."""
+    manifest = load_manifest()
+    manifest.pop(file_path, None)
+    save_manifest(manifest)
+
+
+# ---------------------------------------------------------------------------
+# Workspace file paths
+# ---------------------------------------------------------------------------
+
+def workspace_root(workspace_name: str) -> Path:
+    """Return (and create) the local directory for the given workspace."""
+    p = WORKSPACES_DIR / workspace_name
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def local_file_path(workspace_name: str, file_path: str) -> Path:
+    """
+    Translate a workspace-relative *file_path* (e.g. "src/main.py") to its
+    absolute path on disk (e.g. ~/.study/workspaces/my-ws/src/main.py).
+    """
+    return workspace_root(workspace_name) / file_path
+
+
+def to_relative_path(workspace_name: str, absolute_path: Path) -> str:
+    """
+    Convert an absolute path inside the workspace directory to a
+    workspace-relative POSIX string (e.g. "src/main.py").
+    """
+    root = workspace_root(workspace_name)
+    return absolute_path.relative_to(root).as_posix()
+
+
+def all_local_files(workspace_name: str) -> list[Path]:
+    """Return absolute Paths for every file currently in the local workspace."""
+    root = workspace_root(workspace_name)
+    if not root.exists():
+        return []
+    return [p for p in root.rglob("*") if p.is_file()]
+
+
+def normalize_file_path(raw: str) -> str:
+    """
+    Normalise a user-supplied path into a workspace-relative POSIX string.
+
+    Strips leading slashes, collapses '..' (no escapes above root), and
+    converts backslashes to forward slashes.
+    """
+    p = Path(raw.replace("\\", "/"))
+    parts: list[str] = []
+    for seg in p.parts:
+        if seg in ("", ".", "/"):
+            continue
+        if seg == "..":
+            if parts:
+                parts.pop()
+        else:
+            parts.append(seg)
+    return "/".join(parts)

studysync/main.py

@@ -0,0 +1,261 @@
+"""
+main.py — Typer CLI entry point for the StudySync `study` command.
+
+Install:
+    cd cli && pip install -e .
+
+Usage:
+    study workspace create <name> [--server <url>]
+    study join <token>            [--server <url>]
+    study pull
+    study push <file_path>
+    study status
+    study config
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from .constants import PRODUCTION_SERVER_URL
+from .local_state import (
+    WORKSPACES_DIR,
+    ensure_dirs,
+    load_config,
+    save_config,
+    workspace_root,
+)
+from .sync_engine import SyncEngine
+
+# ---------------------------------------------------------------------------
+# App skeleton
+# ---------------------------------------------------------------------------
+
+app = typer.Typer(
+    name="study",
+    help="[bold]StudySync[/bold] — offline-first CLI workspace synchronisation.",
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+workspace_app = typer.Typer(
+    help="Manage workspaces (create, list).",
+    no_args_is_help=True,
+)
+app.add_typer(workspace_app, name="workspace")
+
+console = Console()
+
+# Default gateway — points at the public production backend so users who
+# install via `pip install studysync` work immediately without --server.
+# Override with --server for self-hosted deployments.
+DEFAULT_SERVER = PRODUCTION_SERVER_URL
+
+
+# ===========================================================================
+# study workspace create <name>
+# ===========================================================================
+
+@workspace_app.command("create")
+def workspace_create(
+    name: str = typer.Argument(..., help="Unique workspace name to create on the server."),
+    server: str = typer.Option(
+        DEFAULT_SERVER,
+        "--server",
+        "-s",
+        help="Base URL of the StudySync server.",
+        envvar="STUDYSYNC_SERVER",
+    ),
+) -> None:
+    """
+    Create a new workspace on the server and save the returned token locally.
+
+    The printed token is the only credential for joining this workspace —
+    share it with collaborators.
+    """
+    ensure_dirs()
+    engine = SyncEngine(server_url=server)
+
+    with console.status(f"[blue]Creating workspace '[bold]{name}[/bold]'…[/blue]"):
+        result = engine.create_workspace(name)
+
+    token: str = result["access_token"]
+    workspace_id: str = result["workspace_id"]
+
+    save_config(
+        {
+            "server_url": server,
+            "workspace_name": name,
+            "workspace_id": workspace_id,
+            "workspace_token": token,
+        }
+    )
+    workspace_root(name)  # ensure local directory exists
+
+    console.print(
+        Panel(
+            f"[green]Workspace '[bold]{name}[/bold]' created.[/green]\n\n"
+            f"[bold]Token[/bold]   [yellow]{token}[/yellow]\n\n"
+            f"Share this token with collaborators:\n"
+            f"  [cyan]study join {token}[/cyan]",
+            title="✓ Workspace Created",
+            border_style="green",
+            padding=(1, 2),
+        )
+    )
+
+
+# ===========================================================================
+# study join <token>
+# ===========================================================================
+
+@app.command()
+def join(
+    token: str = typer.Argument(..., help="Workspace access token (UUID)."),
+    server: str = typer.Option(
+        DEFAULT_SERVER,
+        "--server",
+        "-s",
+        help="Base URL of the StudySync server.",
+        envvar="STUDYSYNC_SERVER",
+    ),
+) -> None:
+    """
+    Validate a workspace token and set it as the active workspace.
+
+    Run [cyan]study pull[/cyan] afterwards to download existing files.
+    """
+    ensure_dirs()
+    engine = SyncEngine(server_url=server)
+
+    with console.status("[blue]Validating token…[/blue]"):
+        result = engine.join_workspace(token)
+
+    workspace_name: str = result["name"]
+    workspace_id: str = result["workspace_id"]
+
+    save_config(
+        {
+            "server_url": server,
+            "workspace_name": workspace_name,
+            "workspace_id": workspace_id,
+            "workspace_token": token,
+        }
+    )
+    workspace_root(workspace_name)
+
+    console.print(
+        Panel(
+            f"[green]Joined workspace '[bold]{workspace_name}[/bold]'.[/green]\n\n"
+            f"Run [cyan]study pull[/cyan] to download all files.",
+            title="✓ Joined",
+            border_style="green",
+            padding=(1, 2),
+        )
+    )
+
+
+# ===========================================================================
+# study pull
+# ===========================================================================
+
+@app.command()
+def pull() -> None:
+    """
+    Pull all new or updated files from the remote workspace.
+
+    Compares the remote file tree (versions + checksums) against the local
+    manifest and downloads only what has changed.  Local file hashes are
+    verified after download.
+    """
+    SyncEngine().pull()
+
+
+# ===========================================================================
+# study push <file_path>
+# ===========================================================================
+
+@app.command()
+def push(
+    file_path: str = typer.Argument(
+        ...,
+        help=(
+            "Path to the file to push.  "
+            "Can be workspace-relative ('src/main.py') "
+            "or an OS path ('/home/user/project/main.py')."
+        ),
+    ),
+) -> None:
+    """
+    Push a local file to the remote workspace.
+
+    Enforces Optimistic Concurrency Control — if the remote has a newer
+    version than your local base, the push is rejected with a [red]CONFLICT[/red]
+    warning and you must run [cyan]study pull[/cyan] first.
+    """
+    SyncEngine().push(file_path)
+
+
+# ===========================================================================
+# study status
+# ===========================================================================
+
+@app.command()
+def status() -> None:
+    """
+    Show the sync status of every file in the local workspace.
+
+    [green]CLEAN[/green]     — matches the last-known server version.
+    [yellow]MODIFIED[/yellow]  — changed locally since last push/pull.
+    [red]DELETED[/red]   — tracked but missing on disk.
+    [blue]UNTRACKED[/blue] — on disk but not yet pushed.
+    """
+    SyncEngine().status()
+
+
+# ===========================================================================
+# study config
+# ===========================================================================
+
+@app.command()
+def config() -> None:
+    """Show the current workspace configuration stored in ~/.study/config.json."""
+    cfg = load_config()
+    if not cfg:
+        console.print(
+            "[yellow]No workspace configured.  "
+            "Run [cyan]study workspace create <name>[/cyan] or "
+            "[cyan]study join <token>[/cyan].[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    lines = [
+        f"[bold]Workspace   [/bold] {cfg.get('workspace_name', 'N/A')}",
+        f"[bold]Server      [/bold] {cfg.get('server_url', 'N/A')}",
+        f"[bold]Token       [/bold] [yellow]{cfg.get('workspace_token', 'N/A')}[/yellow]",
+        f"[bold]Workspace ID[/bold] {cfg.get('workspace_id', 'N/A')}",
+        f"[bold]Local path  [/bold] {WORKSPACES_DIR / cfg.get('workspace_name', '')}",
+    ]
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title="StudySync Config  (~/.study/config.json)",
+            border_style="blue",
+            padding=(1, 2),
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Entry point (for `python -m studysync.main`)
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    app()

studysync/sync_engine.py

@@ -0,0 +1,595 @@
+"""
+sync_engine.py — Networking, OCC logic, and S3 streaming.
+
+All HTTP calls to the StudySync server and all direct S3 streaming live here.
+The Typer commands in main.py are thin wrappers that call into SyncEngine.
+
+Key design decisions
+--------------------
+* Streaming uploads:  We open the local file as a binary file object and wrap
+  it in a progress-tracking shim.  `requests` reads the wrapper's `.read()`
+  method and forwards the Content-Length header we set explicitly, which is
+  required for S3 presigned PUT URLs.
+* Streaming downloads: `requests` streaming GET + chunk-writing gives us a
+  constant memory footprint regardless of file size.
+* No retries: This is v1.  Production systems should add exponential backoff
+  with `tenacity` or `urllib3.Retry`.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+
+from .constants import PRODUCTION_SERVER_URL
+from pathlib import Path
+from typing import Optional
+
+import requests
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+from rich.table import Table
+
+from .local_state import (
+    all_local_files,
+    load_config,
+    load_manifest,
+    local_file_path,
+    sha256_file,
+    to_relative_path,
+    update_manifest_entry,
+    workspace_root,
+    WORKSPACES_DIR,
+)
+
+console = Console(stderr=False)
+
+UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024    # 8 MiB
+DOWNLOAD_CHUNK_SIZE = 8 * 1024 * 1024  # 8 MiB
+HTTP_TIMEOUT = 20                       # seconds for metadata calls
+STREAM_TIMEOUT = 600                    # seconds for S3 streaming
+
+
+# ---------------------------------------------------------------------------
+# Progress-aware file wrapper for streaming uploads
+# ---------------------------------------------------------------------------
+
+class _ProgressReader:
+    """
+    File-like wrapper that reports bytes read to a Rich Progress task.
+
+    requests calls `.read(size)` on whatever you pass as `data=`, so this
+    wrapper intercepts those reads and advances the progress bar.  Exposing
+    `__len__` lets requests set the Content-Length header automatically, which
+    is mandatory for S3 presigned PUT URLs.
+    """
+
+    def __init__(
+        self,
+        fh,
+        total: int,
+        progress: Progress,
+        task_id,
+    ) -> None:
+        self._fh = fh
+        self._total = total
+        self._progress = progress
+        self._task_id = task_id
+
+    def read(self, size: int = -1) -> bytes:
+        chunk = self._fh.read(size)
+        if chunk:
+            self._progress.update(self._task_id, advance=len(chunk))
+        return chunk
+
+    def __len__(self) -> int:
+        return self._total
+
+
+# ---------------------------------------------------------------------------
+# SyncEngine
+# ---------------------------------------------------------------------------
+
+class SyncEngine:
+    """
+    Encapsulates all network operations for the StudySync CLI.
+
+    Parameters override config.json values — useful for workspace create/join
+    where config hasn't been saved yet.
+    """
+
+    def __init__(
+        self,
+        server_url: Optional[str] = None,
+        workspace_token: Optional[str] = None,
+        workspace_name: Optional[str] = None,
+    ) -> None:
+        config = load_config()
+        raw_url = server_url or config.get("server_url", PRODUCTION_SERVER_URL)
+        self.server_url = raw_url.rstrip("/")
+        self.workspace_token = workspace_token or config.get("workspace_token")
+        self.workspace_name = workspace_name or config.get("workspace_name")
+
+    # ------------------------------------------------------------------
+    # Guard
+    # ------------------------------------------------------------------
+
+    def _require_workspace(self) -> None:
+        if not self.workspace_token or not self.workspace_name:
+            console.print(
+                "[red]No active workspace.  "
+                "Run [bold]study workspace create <name>[/bold] or "
+                "[bold]study join <token>[/bold] first.[/red]"
+            )
+            sys.exit(1)
+
+    # ------------------------------------------------------------------
+    # Workspace management
+    # ------------------------------------------------------------------
+
+    def create_workspace(self, name: str) -> dict:
+        resp = requests.post(
+            f"{self.server_url}/workspaces",
+            json={"name": name},
+            timeout=HTTP_TIMEOUT,
+        )
+        if resp.status_code == 409:
+            console.print(
+                f"[red]A workspace named '[bold]{name}[/bold]' already exists on the server.[/red]"
+            )
+            sys.exit(1)
+        _raise_for_status(resp)
+        return resp.json()
+
+    def join_workspace(self, token: str) -> dict:
+        resp = requests.post(
+            f"{self.server_url}/workspaces/join",
+            json={"token": token},
+            timeout=HTTP_TIMEOUT,
+        )
+        if resp.status_code in (401, 404):
+            console.print("[red]Invalid token — workspace not found.[/red]")
+            sys.exit(1)
+        _raise_for_status(resp)
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Remote state
+    # ------------------------------------------------------------------
+
+    def get_remote_state(self) -> list[dict]:
+        self._require_workspace()
+        resp = requests.get(
+            f"{self.server_url}/sync/state/{self.workspace_token}",
+            timeout=HTTP_TIMEOUT,
+        )
+        _raise_for_status(resp)
+        return resp.json()["files"]
+
+    # ------------------------------------------------------------------
+    # pull
+    # ------------------------------------------------------------------
+
+    def pull(self) -> None:
+        """
+        Compare remote state to the local manifest and download every file
+        that is absent or outdated locally.
+
+        A file is considered up-to-date if:
+        1. Its manifest entry version matches the remote version, AND
+        2. The physical file on disk still matches the manifest checksum.
+
+        Condition 2 catches the edge case where someone manually edited the
+        file without going through `study push`.
+        """
+        self._require_workspace()
+        assert self.workspace_name  # guarded by _require_workspace
+
+        console.print(
+            f"[blue]Fetching remote state for workspace "
+            f"'[bold]{self.workspace_name}[/bold]'…[/blue]"
+        )
+
+        remote_files = self.get_remote_state()
+        if not remote_files:
+            console.print("[green]Workspace is empty.  Nothing to pull.[/green]")
+            return
+
+        manifest = load_manifest()
+        to_download: list[dict] = []
+
+        for rf in remote_files:
+            file_path: str = rf["file_path"]
+            remote_version: int = rf["latest_version"]
+            remote_checksum: str = rf.get("latest_checksum") or ""
+
+            local_entry = manifest.get(file_path)
+            dest = local_file_path(self.workspace_name, file_path)
+
+            if local_entry and local_entry["version"] == remote_version:
+                # Version matches — verify the physical file hasn't drifted.
+                if dest.exists():
+                    if sha256_file(dest) == remote_checksum:
+                        continue  # Truly up to date
+                    # File was modified locally without a push — pull wins.
+                    console.print(
+                        f"[yellow]  Overwriting locally-modified "
+                        f"'[bold]{file_path}[/bold]' with remote v{remote_version}[/yellow]"
+                    )
+
+            to_download.append(rf)
+
+        if not to_download:
+            console.print("[green]✓ Everything is up to date.[/green]")
+            return
+
+        console.print(f"[blue]Downloading [bold]{len(to_download)}[/bold] file(s)…[/blue]")
+
+        success = 0
+        for rf in to_download:
+            file_path = rf["file_path"]
+            remote_version = rf["latest_version"]
+            remote_checksum = rf.get("latest_checksum") or ""
+            size_bytes: Optional[int] = rf.get("size_bytes")
+
+            console.print(f"  → [cyan]{file_path}[/cyan]  [dim]v{remote_version}[/dim]")
+            try:
+                dl_info = self._request_download(file_path)
+                dest = local_file_path(self.workspace_name, file_path)
+                self._stream_download(dl_info["presigned_url"], dest, size_bytes)
+
+                # Integrity check
+                actual_checksum = sha256_file(dest)
+                if actual_checksum != remote_checksum:
+                    console.print(
+                        f"  [red]✗ Checksum mismatch for '{file_path}'.  "
+                        f"Expected {remote_checksum[:12]}… got {actual_checksum[:12]}…  "
+                        "File deleted.[/red]"
+                    )
+                    dest.unlink(missing_ok=True)
+                    continue
+
+                update_manifest_entry(file_path, remote_version, remote_checksum)
+
+                # ----------------------------------------------------------
+                # Checkout phase: copy from vault → current working directory
+                # ----------------------------------------------------------
+                cwd = Path(os.getcwd())
+                checkout_dest = cwd / file_path
+                checkout_dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(dest, checkout_dest)
+
+                console.print(
+                    f"  [green]✓ {file_path}[/green]  "
+                    f"[dim]→ ./{Path(file_path).as_posix()}[/dim]"
+                )
+                success += 1
+
+            except Exception as exc:
+                console.print(f"  [red]✗ Failed to download '{file_path}': {exc}[/red]")
+
+        console.print(
+            f"[green]Pull complete — [bold]{success}/{len(to_download)}[/bold] file(s) "
+            f"updated in vault and checked out to [bold]{os.getcwd()}[/bold].[/green]"
+        )
+
+    # ------------------------------------------------------------------
+    # push
+    # ------------------------------------------------------------------
+
+    def push(self, file_path_arg: str) -> None:
+        """
+        Push a single file to the remote workspace.
+
+        Accepts either:
+        * A workspace-relative path  ("src/main.py")
+        * An absolute/relative OS path — the file is copied into the workspace
+          directory if it lives outside it.
+
+        OCC flow:
+        1. Hash the local file.
+        2. Read base_version from the manifest (0 if untracked/new).
+        3. POST /sync/upload-request → 409 means remote has diverged → abort.
+        4. Stream PUT to the presigned S3 URL.
+        5. POST /sync/commit-upload.
+        6. Update manifest.
+        """
+        self._require_workspace()
+        assert self.workspace_name
+
+        ws_root = workspace_root(self.workspace_name)
+
+        # Resolve the file and its workspace-relative key
+        abs_path, relative = self._resolve_push_path(file_path_arg, ws_root)
+
+        console.print(f"[blue]Hashing [bold]{relative}[/bold]…[/blue]")
+        checksum = sha256_file(abs_path)
+        size_bytes = abs_path.stat().st_size
+
+        # Check against manifest: skip if nothing changed
+        manifest = load_manifest()
+        local_entry = manifest.get(relative)
+        if local_entry and local_entry["checksum"] == checksum:
+            console.print(
+                f"[yellow]No changes detected in '[bold]{relative}[/bold]'.  Nothing to push.[/yellow]"
+            )
+            return
+
+        base_version = local_entry["version"] if local_entry else 0
+
+        # --- OCC gate ---
+        console.print(
+            f"[blue]Requesting upload slot  "
+            f"[dim](base_version={base_version})[/dim]…[/blue]"
+        )
+        resp = requests.post(
+            f"{self.server_url}/sync/upload-request",
+            json={
+                "workspace_token": self.workspace_token,
+                "file_path": relative,
+                "base_version": base_version,
+                "checksum": checksum,
+                "size_bytes": size_bytes,
+            },
+            timeout=HTTP_TIMEOUT,
+        )
+
+        if resp.status_code == 409:
+            detail = resp.json().get("detail", "Remote has diverged.")
+            console.print(
+                f"\n[bold red]⚠  CONFLICT — Remote has changes.  Pull first.[/bold red]\n"
+                f"[red]{detail}[/red]\n"
+                f"  Run: [cyan]study pull[/cyan]\n"
+            )
+            sys.exit(1)
+
+        _raise_for_status(resp)
+        upload_info = resp.json()
+
+        upload_id: str = upload_info["upload_id"]
+        presigned_url: str = upload_info["presigned_url"]
+        new_version: int = upload_info["new_version"]
+
+        # --- Stream to S3 ---
+        console.print(f"[blue]Uploading to S3  [dim]({size_bytes:,} bytes)[/dim]…[/blue]")
+        try:
+            self._stream_upload(presigned_url, abs_path, size_bytes)
+        except Exception as exc:
+            console.print(f"[red]✗ S3 upload failed: {exc}[/red]")
+            console.print(
+                "[yellow]The upload slot has been allocated but the file was not written.  "
+                "You can retry — the slot will expire automatically.[/yellow]"
+            )
+            sys.exit(1)
+
+        # --- Commit ---
+        console.print("[blue]Committing…[/blue]")
+        try:
+            commit_resp = requests.post(
+                f"{self.server_url}/sync/commit-upload",
+                json={"upload_id": upload_id},
+                timeout=HTTP_TIMEOUT,
+            )
+            _raise_for_status(commit_resp)
+        except Exception as exc:
+            console.print(
+                f"[red]✗ Commit failed: {exc}\n"
+                "The file was uploaded to S3 but the server did not record it.  "
+                "Contact your administrator with upload_id=[bold]{upload_id}[/bold].[/red]"
+            )
+            sys.exit(1)
+
+        # --- Update manifest ---
+        update_manifest_entry(relative, new_version, checksum)
+        console.print(
+            f"[green]✓ Pushed '[bold]{relative}[/bold]' → v{new_version}[/green]"
+        )
+
+    # ------------------------------------------------------------------
+    # status
+    # ------------------------------------------------------------------
+
+    def status(self) -> None:
+        """
+        Compare every tracked file's on-disk SHA-256 against the manifest.
+
+        States:
+        CLEAN     — matches manifest checksum
+        MODIFIED  — exists on disk but checksum differs
+        DELETED   — tracked in manifest but missing on disk
+        UNTRACKED — present on disk but not in manifest
+        """
+        self._require_workspace()
+        assert self.workspace_name
+
+        manifest = load_manifest()
+        ws_root = workspace_root(self.workspace_name)
+
+        table = Table(
+            title=f"Workspace: [bold]{self.workspace_name}[/bold]",
+            show_lines=False,
+            header_style="bold",
+        )
+        table.add_column("File", style="cyan", no_wrap=True)
+        table.add_column("Status", justify="center")
+        table.add_column("Ver", justify="right", style="dim")
+        table.add_column("Checksum", style="dim", no_wrap=True)
+
+        tracked_paths: set[str] = set(manifest.keys())
+        rows: list[tuple] = []
+
+        for file_path, entry in manifest.items():
+            dest = local_file_path(self.workspace_name, file_path)
+            ver = str(entry["version"])
+            if not dest.exists():
+                rows.append((file_path, "[red]DELETED[/red]", ver, entry["checksum"][:14] + "…"))
+            else:
+                current = sha256_file(dest)
+                if current == entry["checksum"]:
+                    rows.append((file_path, "[green]CLEAN[/green]", ver, current[:14] + "…"))
+                else:
+                    rows.append((file_path, "[yellow]MODIFIED[/yellow]", ver, current[:14] + "…"))
+
+        # Untracked files
+        for abs_path in all_local_files(self.workspace_name):
+            rel = to_relative_path(self.workspace_name, abs_path)
+            if rel not in tracked_paths:
+                rows.append((rel, "[blue]UNTRACKED[/blue]", "-", "-"))
+
+        if not rows:
+            console.print(
+                f"[yellow]Workspace '[bold]{self.workspace_name}[/bold]' is empty locally.  "
+                "Run [cyan]study pull[/cyan] to download files.[/yellow]"
+            )
+            return
+
+        for row in sorted(rows, key=lambda r: r[0]):
+            table.add_row(*row)
+
+        console.print(table)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request_download(self, file_path: str) -> dict:
+        resp = requests.get(
+            f"{self.server_url}/sync/download-request",
+            params={
+                "workspace_token": self.workspace_token,
+                "file_path": file_path,
+            },
+            timeout=HTTP_TIMEOUT,
+        )
+        _raise_for_status(resp)
+        return resp.json()
+
+    def _stream_download(
+        self,
+        presigned_url: str,
+        dest: Path,
+        file_size: Optional[int] = None,
+    ) -> None:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+
+        with requests.get(presigned_url, stream=True, timeout=STREAM_TIMEOUT) as resp:
+            resp.raise_for_status()
+            total = int(resp.headers.get("Content-Length", file_size or 0)) or None
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                DownloadColumn(),
+                TransferSpeedColumn(),
+                TimeRemainingColumn(),
+                console=console,
+                transient=True,
+            ) as progress:
+                task = progress.add_task(dest.name, total=total)
+                with open(dest, "wb") as fh:
+                    for chunk in resp.iter_content(chunk_size=DOWNLOAD_CHUNK_SIZE):
+                        if chunk:
+                            fh.write(chunk)
+                            progress.update(task, advance=len(chunk))
+
+    def _stream_upload(
+        self,
+        presigned_url: str,
+        local_path: Path,
+        size_bytes: int,
+    ) -> None:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(),
+            console=console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task(local_path.name, total=size_bytes)
+
+            with open(local_path, "rb") as fh:
+                reader = _ProgressReader(fh, size_bytes, progress, task)
+                resp = requests.put(
+                    presigned_url,
+                    data=reader,
+                    headers={
+                        "Content-Length": str(size_bytes),
+                        "Content-Type": "application/octet-stream",
+                    },
+                    timeout=STREAM_TIMEOUT,
+                )
+                resp.raise_for_status()
+
+    def _resolve_push_path(
+        self,
+        file_path_arg: str,
+        ws_root: Path,
+    ) -> tuple[Path, str]:
+        """
+        Return (absolute_path, workspace_relative_posix_key).
+
+        Tries the arg as:
+        1. A path relative to the workspace root.
+        2. An absolute OS path — if the file is inside the workspace root,
+           derive the relative key.  If outside, copy it into the workspace
+           root (top-level, using the filename only).
+        """
+        import shutil
+
+        # Attempt 1: relative to workspace root
+        candidate = ws_root / file_path_arg
+        if candidate.exists():
+            return candidate, file_path_arg.replace("\\", "/")
+
+        # Attempt 2: treat as an OS path
+        os_path = Path(file_path_arg).expanduser().resolve()
+        if not os_path.exists():
+            console.print(f"[red]File not found: {file_path_arg}[/red]")
+            sys.exit(1)
+
+        try:
+            # File is already inside the workspace directory
+            relative = os_path.relative_to(ws_root).as_posix()
+            return os_path, relative
+        except ValueError:
+            pass
+
+        # File is outside the workspace — copy it in
+        relative = os_path.name
+        dest = ws_root / relative
+        console.print(
+            f"[yellow]File is outside the workspace.  "
+            f"Copying to '[bold]{relative}[/bold]' inside workspace.[/yellow]"
+        )
+        shutil.copy2(os_path, dest)
+        return dest, relative
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+def _raise_for_status(resp: requests.Response) -> None:
+    """Raise with a helpful message on HTTP errors."""
+    if not resp.ok:
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        raise requests.HTTPError(
+            f"HTTP {resp.status_code}: {detail}",
+            response=resp,
+        )