deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/sync.py

@@ -0,0 +1,804 @@
+"""Sync commands: clone, pull, push, status, commit.
+
+Git-like sync between a local folder and a cloud DeepCell workspace.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_error,
+    echo_info,
+    echo_success,
+    echo_validation_map,
+    echo_warning,
+)
+from deepcell_cli.sync_state import (
+    FileChecksum,
+    SyncState,
+    compute_local_hash,
+    find_sync_root,
+    load_sync_state,
+    save_sync_state,
+    scan_local_files,
+)
+
+
+# -- Helpers -------------------------------------------------------------------
+
+
+def _require_sync_root(ctx: Ctx | None = None) -> tuple[Path, SyncState]:
+    """Locate sync root from CWD or raise, and reject a contradictory --workspace.
+
+    `--workspace` is a root option documented as overriding the active
+    workspace for the invocation. It cannot do that here: a clone directory is
+    bound to one workspace by its sync state, and honouring the flag would
+    pull one workspace's files into another's checkout, or push them there.
+
+    So the flag was ignored — silently, which is the worse of the two failures
+    it could have. A reader who passes it believes they are inspecting the
+    workspace they named while looking at the one on disk, and `status` gives
+    them a clean bill of health for a workspace it never contacted.
+
+    Naming the same workspace is not a contradiction and passes through: a
+    script that sets `DEEPCELL_WORKSPACE` globally and then cds into that
+    workspace's clone is doing nothing wrong.
+    """
+    root = find_sync_root()
+    if root is None:
+        raise click.ClickException(
+            "Not inside a synced workspace. Run `deepcell clone <slug>` first."
+        )
+    state = load_sync_state(root)
+    requested = getattr(ctx, "workspace", None) if ctx is not None else None
+    if requested and requested != state.workspace_slug:
+        raise click.UsageError(
+            f"--workspace {requested!r} does not apply to a sync command: "
+            f"{root}/ is a clone of workspace {state.workspace_slug!r} and "
+            f"every sync command reads that binding from .deepcell-sync. "
+            f"Run this from a clone of {requested!r}, or "
+            f"`deepcell clone {requested}` to make one."
+        )
+    return root, state
+
+
+def _get_head_sha(client, slug: str, variant: str | None = None) -> str:
+    """Fetch the HEAD commit SHA for a workspace (or a variant branch)."""
+    if variant:
+        data = client.get(f"/workspaces/{slug}/variants/{variant}")
+        if isinstance(data, dict) and data.get("head_sha"):
+            return data["head_sha"]
+        return ""
+    # Try head_sha on workspace detail first (fast path)
+    ws = client.get(f"/workspaces/{slug}")
+    if isinstance(ws, dict) and ws.get("head_sha"):
+        return ws["head_sha"]
+    # Fallback: fetch latest version entry
+    versions = client.get(f"/workspaces/{slug}/versions", params={"max_count": 1})
+    if versions and isinstance(versions, list):
+        return versions[0].get("sha", "")
+    return ""
+
+
+def _get_remote_files(
+    client, slug: str, variant: str | None = None, *, include_uploaded: bool = False
+) -> list[dict]:
+    """Fetch the remote file list with git_sha per file (variant-aware).
+
+    Uploaded attachments (`file_type == "uploaded"`) live in object storage,
+    not git: they carry no git_sha and the file-read route 404s on them. Every
+    sync path here downloads what it lists, so they are filtered out by
+    default — `clone` filtered them at its own call site but `pull` and
+    `variant checkout` did not, and a single attachment uploaded in the web UI
+    then broke every later pull permanently. Pass *include_uploaded* only to
+    report on them.
+    """
+    if variant:
+        files = client.get(f"/workspaces/{slug}/variants/{variant}/files")
+    else:
+        files = client.get(f"/workspaces/{slug}/files")
+    if include_uploaded:
+        return files
+    return [f for f in files if f.get("file_type") != "uploaded"]
+
+
+def _download_file(client, slug: str, filename: str, *, revision: str | None = None) -> str:
+    """Download a single file's content from the workspace (main branch)."""
+    params = {"revision": revision} if revision else None
+    data = client.get(f"/workspaces/{slug}/files/{filename}", params=params)
+    if isinstance(data, dict) and "content" in data:
+        return data["content"]
+    return str(data)
+
+
+def _download_branch_file(
+    client, slug: str, filename: str, *, variant: str | None = None, revision: str | None = None
+) -> str:
+    """Download a single file's content from a branch (variant-aware).
+
+    When *variant* is set, hits the variant read route; otherwise the main route.
+    """
+    if not variant:
+        return _download_file(client, slug, filename, revision=revision)
+    if revision:
+        # The variant read route declares no `revision` param, so FastAPI
+        # dropped it and answered with the branch HEAD — the caller silently
+        # got different bytes than it asked for. Commit SHAs are
+        # branch-independent, so read a pinned revision via the main route.
+        raise ValueError(
+            f"Cannot read revision {revision!r} from variant '{variant}': the "
+            f"variant file route only serves branch HEAD. Read the pinned "
+            f"revision through the main branch instead (commit SHAs are "
+            f"branch-independent)."
+        )
+    data = client.get(
+        f"/workspaces/{slug}/variants/{variant}/files/{filename}"
+    )
+    if isinstance(data, dict) and "content" in data:
+        return data["content"]
+    return str(data)
+
+
+def _try_merge(client, base_xml: str, ours_xml: str, theirs_xml: str, filename: str) -> dict | None:
+    """Attempt a 3-way merge via the merge API. Returns response dict or None on failure."""
+    try:
+        return client.post("/merge/preview", json={
+            "base_xml": base_xml,
+            "ours_xml": ours_xml,
+            "theirs_xml": theirs_xml,
+            "filename": filename,
+        })
+    except Exception:
+        return None
+
+
+# -- clone ---------------------------------------------------------------------
+
+
+@click.command()
+@click.argument("slug")
+@click.argument("directory", required=False)
+@pass_ctx
+def clone(ctx: Ctx, slug: str, directory: str | None) -> None:
+    """Clone a workspace to a local folder.
+
+    \b
+    deepcell clone my-workspace              # creates ./my-workspace/
+    deepcell clone my-workspace ./local-dir  # creates ./local-dir/
+    """
+    client = ctx.client
+
+    # 1. Validate workspace access
+    ws = client.get(f"/workspaces/{slug}")
+    workspace_id = str(ws.get("id", ""))
+
+    # 2. Get remote file list
+    remote_files = _get_remote_files(client, slug, include_uploaded=True)
+
+    # 3. Get HEAD SHA
+    head_sha = _get_head_sha(client, slug)
+
+    # 4. Determine target directory
+    target = Path(directory) if directory else Path(slug)
+    pre_existing = target.exists()
+    if pre_existing and any(target.iterdir()):
+        raise click.ClickException(f"Directory '{target}' already exists and is not empty.")
+    target.mkdir(parents=True, exist_ok=True)
+
+    # 5. Download each file. Uploaded attachments live in object storage, not
+    # git: they carry file_type="uploaded" and no git_sha, and the git read
+    # route 404s on them. Downloading them aborted the clone mid-way and left
+    # a partial directory that blocked every retry.
+    git_files = [f for f in remote_files if f.get("file_type") != "uploaded"]
+    non_git = [f["filename"] for f in remote_files if f.get("file_type") == "uploaded"]
+
+    checksums: dict[str, FileChecksum] = {}
+    try:
+        for f in git_files:
+            fname = f["filename"]
+            git_sha = f.get("git_sha", "")
+            echo_info(f"  Downloading {fname}")
+            content = _download_file(client, slug, fname)
+            (target / fname).write_text(content, encoding="utf-8")
+            checksums[fname] = FileChecksum(
+                git_sha=git_sha,
+                local_hash=compute_local_hash(content),
+            )
+    except Exception:
+        # Leave no half-written directory behind: a retry would fail on
+        # "already exists and is not empty" instead of re-cloning.
+        if not pre_existing:
+            import shutil
+
+            shutil.rmtree(target, ignore_errors=True)
+        raise
+
+    # 6. Write sync state
+    from deepcell_cli.config import get_api_url
+
+    state = SyncState(
+        workspace_slug=slug,
+        workspace_id=workspace_id,
+        api_url=get_api_url(),
+        last_sync_sha=head_sha,
+        file_checksums=checksums,
+    )
+    save_sync_state(target, state)
+
+    echo_success(
+        f"Cloned workspace '{slug}' to {target}/ "
+        f"({len(git_files)} file(s), HEAD {head_sha[:8]})"
+    )
+    if non_git:
+        echo_warning(
+            f"{len(non_git)} uploaded attachment(s) not cloned (they are not in "
+            f"git): {', '.join(non_git)} — open the workspace in the Workbench "
+            f"to download them. `deepcell download` reads the git route, which "
+            f"404s on these."
+        )
+
+
+# -- status --------------------------------------------------------------------
+
+
+@click.command("status")
+@pass_ctx
+def sync_status(ctx: Ctx) -> None:
+    """Show local changes vs last sync.
+
+    \b
+    A  filename   — added locally
+    M  filename   — modified locally
+    D  filename   — deleted locally
+
+    Which workspace this reports on comes from the clone's `.deepcell-sync`,
+    not from `--workspace` — a clone directory is bound to one workspace. The
+    root `--workspace` flag is rejected here when it names a different one
+    rather than being quietly ignored.
+    """
+    root, state = _require_sync_root(ctx)
+    active_variant = state.active_variant or None
+    local_files = scan_local_files(root, tracked=state.file_checksums)
+
+    added: list[str] = []
+    modified: list[str] = []
+    deleted: list[str] = []
+
+    # Check for modifications and deletions
+    for name, ck in state.file_checksums.items():
+        if name not in local_files:
+            deleted.append(name)
+        elif local_files[name] != ck.local_hash:
+            modified.append(name)
+
+    # Check for additions
+    for name in local_files:
+        if name not in state.file_checksums:
+            added.append(name)
+
+    if not added and not modified and not deleted:
+        echo_info("Clean — no local changes since last sync.")
+    else:
+        for name in sorted(added):
+            click.echo(click.style("A  ", fg="green") + name)
+        for name in sorted(modified):
+            click.echo(click.style("M  ", fg="yellow") + name)
+        for name in sorted(deleted):
+            click.echo(click.style("D  ", fg="red") + name)
+
+    # Optionally check remote
+    try:
+        client = ctx.client
+        head_sha = _get_head_sha(client, state.workspace_slug, variant=active_variant)
+        if head_sha and state.last_sync_sha and head_sha != state.last_sync_sha:
+            echo_info(f"Remote has new commit(s) since last sync (HEAD {head_sha[:8]})")
+    except Exception:
+        pass  # offline is fine
+
+
+# -- pull ----------------------------------------------------------------------
+
+
+@click.command()
+@pass_ctx
+def pull(ctx: Ctx) -> None:
+    """Fetch latest cloud changes to the local folder.
+
+    Downloads remote changes and detects conflicts when a file was modified
+    both locally and on the server.
+
+    Which workspace it pulls from comes from the clone's `.deepcell-sync`, not
+    from `--workspace`; passing a different one is a usage error, not a
+    redirect. Run it from a clone of the workspace you mean.
+    """
+    root, state = _require_sync_root(ctx)
+    client = ctx.client
+    slug = state.workspace_slug
+    active_variant = state.active_variant or None
+
+    # 1. Check remote HEAD (of the ACTIVE branch — variant or main)
+    head_sha = _get_head_sha(client, slug, variant=active_variant)
+    if head_sha == state.last_sync_sha:
+        echo_info("Already up to date.")
+        return
+
+    # 2. Get remote file list (of the active branch)
+    remote_files = _get_remote_files(client, slug, variant=active_variant)
+    remote_map: dict[str, dict] = {f["filename"]: f for f in remote_files}
+
+    # 3. Scan local state
+    local_files = scan_local_files(root, tracked=state.file_checksums)
+
+    # 4. Diff remote vs stored checksums
+    new_checksums: dict[str, FileChecksum] = {}
+    conflicts = 0
+
+    # Process remote files (new or modified)
+    for fname, finfo in remote_map.items():
+        remote_git_sha = finfo.get("git_sha", "")
+        stored = state.file_checksums.get(fname)
+
+        if stored and stored.git_sha == remote_git_sha:
+            # Remote unchanged — keep current local state
+            local_hash = local_files.get(fname, stored.local_hash)
+            new_checksums[fname] = FileChecksum(
+                git_sha=remote_git_sha,
+                local_hash=local_hash,
+            )
+            continue
+
+        # Remote changed (or new file)
+        local_modified = (
+            stored is not None
+            and fname in local_files
+            and local_files[fname] != stored.local_hash
+        )
+
+        if local_modified:
+            # Conflict: both sides changed
+            local_content = (root / fname).read_text(encoding="utf-8")
+            theirs_content = _download_branch_file(
+                client, slug, fname, variant=active_variant,
+            )
+
+            # Try semantic merge for .deepcell files
+            merged = False
+            if fname.endswith(".deepcell") and state.last_sync_sha:
+                try:
+                    # The merge BASE is pinned to a commit SHA (last_sync_sha),
+                    # which is branch-independent. The variant file route reads
+                    # only at the variant branch HEAD and ignores any `revision`
+                    # param, so read the base via the MAIN route by SHA.
+                    base_content = _download_file(
+                        client, slug, fname, revision=state.last_sync_sha,
+                    )
+                    result = _try_merge(
+                        client, base_content, local_content, theirs_content, fname,
+                    )
+                    if result and result.get("success") and result.get("merged_xml"):
+                        from deepcell_cli.commands.merge import echo_merge_data_loss
+
+                        # `success` counts conflicts only — an apply-time drop
+                        # still comes back clean, so check before discarding
+                        # the pre-merge local copy.
+                        lossy = echo_merge_data_loss(result)
+                        (root / fname).write_text(result["merged_xml"], encoding="utf-8")
+                        new_checksums[fname] = FileChecksum(
+                            git_sha=remote_git_sha,
+                            # Baseline is what the SERVER holds (theirs), not
+                            # the merge result: the merged content exists only
+                            # on disk and still has to be pushed. Recording the
+                            # merged hash made `push` say "Nothing to push" and
+                            # `status` say Clean, and the next pull took the
+                            # git_sha fast path — the merge was stranded with
+                            # no command left to reveal it.
+                            local_hash=compute_local_hash(theirs_content),
+                        )
+                        auto_count = result.get("auto_resolved_count", 0)
+                        if lossy:
+                            # Keep the pre-merge local copy and count it as a
+                            # conflict so the pull exits 1 instead of reading
+                            # as a clean auto-merge.
+                            (root / f"{fname}.local").write_text(
+                                local_content, encoding="utf-8"
+                            )
+                            conflicts += 1
+                            echo_error(
+                                f"INCOMPLETE MERGE: {fname} (pre-merge local saved "
+                                f"as {fname}.local)"
+                            )
+                        else:
+                            echo_info(f"  Auto-merged {fname} ({auto_count} change(s) resolved)")
+                        merged = True
+                    elif result and not result.get("success"):
+                        # Merge has conflicts — fall back to .local but show details
+                        conflict_list = result.get("conflicts", [])
+                        for c in conflict_list[:5]:
+                            item = c.get("item_ref", "?")
+                            cref = c.get("context_ref", "")
+                            ours_val = c.get("ours", "")
+                            theirs_val = c.get("theirs", "")
+                            echo_warning(
+                                f"  {item}[{cref}]: ours={ours_val} vs theirs={theirs_val}"
+                            )
+                        if len(conflict_list) > 5:
+                            echo_warning(f"  ... and {len(conflict_list) - 5} more conflict(s)")
+                except Exception:
+                    pass  # graceful degradation — fall back to .local
+
+            if not merged:
+                conflicts += 1
+                local_backup = root / f"{fname}.local"
+                local_backup.write_text(local_content, encoding="utf-8")
+                (root / fname).write_text(theirs_content, encoding="utf-8")
+                new_checksums[fname] = FileChecksum(
+                    git_sha=remote_git_sha,
+                    local_hash=compute_local_hash(theirs_content),
+                )
+                echo_error(f"CONFLICT: {fname} (local saved as {fname}.local)")
+                if fname.endswith(".deepcell"):
+                    echo_info(f"  Hint: run `deepcell merge resolve {fname}` to resolve")
+            continue
+
+        # Download remote version (no conflict)
+        echo_info(f"  Updating {fname}")
+        content = _download_branch_file(client, slug, fname, variant=active_variant)
+        (root / fname).write_text(content, encoding="utf-8")
+        new_checksums[fname] = FileChecksum(
+            git_sha=remote_git_sha,
+            local_hash=compute_local_hash(content),
+        )
+
+    # Handle remote deletions (file in stored checksums but not in remote)
+    for fname, stored in state.file_checksums.items():
+        if fname in remote_map:
+            continue
+        local_modified = (
+            fname in local_files
+            and local_files[fname] != stored.local_hash
+        )
+        if local_modified:
+            # Remote deleted, local modified — keep local
+            echo_info(f"  Keeping locally modified {fname} (deleted on remote)")
+            new_checksums[fname] = FileChecksum(
+                git_sha="",
+                local_hash=local_files[fname],
+            )
+        elif fname in local_files:
+            # Remote deleted, no local changes — delete locally
+            echo_info(f"  Deleting {fname}")
+            (root / fname).unlink()
+
+    # Preserve locally added files not tracked by sync
+    for fname in local_files:
+        if fname not in new_checksums and fname not in state.file_checksums:
+            # Locally added file — not in remote, keep it
+            new_checksums[fname] = FileChecksum(
+                git_sha="",
+                local_hash=local_files[fname],
+            )
+
+    # 5. Update sync state. Never overwrite a known baseline with a blank HEAD
+    # (a malformed 200 response with no head_sha): that would silently disarm the
+    # optimistic-lock guard on the next push (symmetric to the push guard). Keep
+    # the prior baseline armed and warn instead.
+    if head_sha:
+        state.last_sync_sha = head_sha
+    elif state.last_sync_sha:
+        echo_info(
+            "Pulled, but the server did not report a HEAD SHA; keeping the "
+            "previous sync baseline so the next push stays guarded."
+        )
+    else:
+        state.last_sync_sha = head_sha
+    state.file_checksums = new_checksums
+    save_sync_state(root, state)
+
+    if conflicts:
+        echo_warning(
+            f"Pulled with {conflicts} unresolved conflict(s). "
+            "Resolve with `deepcell merge resolve <file>` or edit .local files manually."
+        )
+        # Sync state is already saved; exit nonzero so a scripted
+        # `deepcell pull && deepcell push` never proceeds on a conflicted tree.
+        raise click.exceptions.Exit(1)
+    echo_success(f"Pulled latest changes (HEAD {head_sha[:8]})")
+
+
+# -- push ----------------------------------------------------------------------
+
+
+@click.command()
+@click.option("-m", "--message", default="", help="Commit message for the push.")
+@pass_ctx
+def push(ctx: Ctx, message: str) -> None:
+    """Upload local changes to the cloud workspace.
+
+    Rejects if the remote has changed since your last sync.
+    Run `deepcell pull` first to incorporate remote changes.
+    """
+    root, state = _require_sync_root(ctx)
+    client = ctx.client
+    slug = state.workspace_slug
+    active_variant = state.active_variant or None
+
+    # 1. Check remote HEAD matches our last sync (against the ACTIVE branch)
+    head_sha = _get_head_sha(client, slug, variant=active_variant)
+    if head_sha and state.last_sync_sha and head_sha != state.last_sync_sha:
+        raise click.ClickException(
+            "Remote has new changes. Run `deepcell pull` first."
+        )
+
+    # 2. Compute local changes
+    local_files = scan_local_files(root, tracked=state.file_checksums)
+    added: list[str] = []
+    modified: list[str] = []
+    deleted: list[str] = []
+
+    for name in local_files:
+        if name not in state.file_checksums:
+            added.append(name)
+        elif local_files[name] != state.file_checksums[name].local_hash:
+            modified.append(name)
+
+    for name in state.file_checksums:
+        if name not in local_files:
+            deleted.append(name)
+
+    if not added and not modified and not deleted:
+        echo_info("Nothing to push.")
+        return
+
+    # 3. Upload changes
+    commit_msg = message or "Sync from CLI"
+    if not message:
+        import sys
+        print(
+            "Warning: no commit message given (-m). Proceeding with 'Sync from CLI'. "
+            "Run `deepcell push -m '<message>'` to describe your changes.",
+            file=sys.stderr,
+        )
+
+    # Variant deletions can't be applied (no backend route), so they're skipped.
+    # Tracked separately so they don't inflate the pushed count and so the still-
+    # on-server files stay in the tracked checksums (else they resurface as new
+    # on the next pull).
+    skipped_deletes: list[str] = []
+
+    # Files the server committed but flagged with validation errors. The push
+    # is real either way (the server persists invalid .deepcell content on
+    # purpose), but it must not read as a clean success or exit 0.
+    invalid_files: list[str] = []
+
+    def _surface_validation(fname: str, validation: object) -> None:
+        if not isinstance(validation, dict):
+            return
+        for w in validation.get("warnings") or []:
+            echo_warning(f"{fname}: {w}")
+        errors = validation.get("errors") or []
+        for e in errors:
+            echo_error(f"{fname}: Error: {e}")
+        if errors:
+            invalid_files.append(fname)
+
+    # Set only by the main-branch batch path; the per-file variant path has no
+    # batch response to read committed hashes from.
+    batch_result: dict | None = None
+
+    if active_variant:
+        # Variant mode: commit each changed file individually via the variant file endpoint.
+        # (No batch variant endpoint exists; per-file is the v1 approach.)
+        # Deleted files on a variant have no backend route — warn and skip.
+        last_commit_sha = ""
+        for fname in added + modified:
+            content = (root / fname).read_text(encoding="utf-8")
+            echo_info(f"  Pushing {fname} → variant '{active_variant}'")
+            result = client.post(
+                f"/workspaces/{slug}/variants/{active_variant}/files/{fname}",
+                json={"content": content, "commit_message": commit_msg},
+            )
+            if isinstance(result, dict) and result.get("commit_sha"):
+                last_commit_sha = result["commit_sha"]
+            if isinstance(result, dict):
+                _surface_validation(fname, result.get("validation"))
+
+        if deleted:
+            skipped_deletes = list(deleted)
+            for fname in deleted:
+                echo_warning(
+                    f"  Skipping deletion of {fname} on variant — "
+                    "no backend route for variant file-deletes (deferred)"
+                )
+
+        new_head = last_commit_sha or _get_head_sha(client, slug, variant=active_variant)
+    else:
+        # Main mode: single atomic batch commit
+        files_payload: dict[str, str] = {}
+        for fname in added + modified:
+            content = (root / fname).read_text(encoding="utf-8")
+            echo_info(f"  Staging {fname}")
+            files_payload[fname] = content
+
+        for fname in deleted:
+            echo_info(f"  Deleting {fname}")
+
+        batch_result = client.post(
+            f"/workspaces/{slug}/files:batch",
+            json={
+                "files": files_payload,
+                "deletes": deleted,
+                "commit_message": commit_msg,
+                # Optimistic-lock guard: the server rejects with 409 if main HEAD
+                # advanced past the revision we synced against. None on first sync
+                # (no baseline yet) so the server skips the CAS.
+                "expected_parent": state.last_sync_sha or None,
+            },
+        )
+
+        new_head = (
+            batch_result.get("commit_sha")
+            if isinstance(batch_result, dict) and batch_result.get("commit_sha")
+            else _get_head_sha(client, slug)
+        )
+        if isinstance(batch_result, dict) and isinstance(
+            batch_result.get("validation"), dict
+        ):
+            for fname, v in batch_result["validation"].items():
+                _surface_validation(fname, v)
+    remote_files = _get_remote_files(client, slug, variant=active_variant)
+    remote_map = {f["filename"]: f for f in remote_files}
+
+    # The server normalizes and recomputes .deepcell content before
+    # committing, so what landed in git may differ from what we sent.
+    # Recording the on-disk hash as the baseline made `status` report "Clean"
+    # while the two differed, and `pull` (which compares git SHAs) never
+    # reconciled it. Pull back exactly the files whose committed hash differs.
+    committed_hashes = (
+        batch_result.get("content_hashes")
+        if isinstance(batch_result, dict) else None
+    ) or {}
+    rewritten: list[str] = []
+    # Files we could not reconcile: baseline them against the server's hash so
+    # the drift stays visible instead of being papered over as Clean.
+    baseline_overrides: dict[str, str] = {}
+    for fname, committed_hash in committed_hashes.items():
+        if fname not in local_files or local_files[fname] == committed_hash:
+            continue
+        try:
+            server_content = _download_branch_file(
+                client, slug, fname, variant=active_variant,
+            )
+        except Exception:
+            # Leave the local copy alone, but baseline it against what the
+            # server committed so `status` actually reports the drift. Keeping
+            # the on-disk hash here made the baseline match the file and
+            # `status` say Clean — reinstating the very bug this reconcile
+            # exists to fix, just on the error path.
+            baseline_overrides[fname] = committed_hash
+            continue
+        (root / fname).write_text(server_content, encoding="utf-8")
+        local_files[fname] = compute_local_hash(server_content)
+        rewritten.append(fname)
+
+    new_checksums: dict[str, FileChecksum] = {}
+    for fname in local_files:
+        remote_info = remote_map.get(fname, {})
+        new_checksums[fname] = FileChecksum(
+            git_sha=remote_info.get("git_sha", ""),
+            local_hash=baseline_overrides.get(fname, local_files[fname]),
+        )
+
+    # Skipped variant deletions are still on the server: keep them tracked (with
+    # their server git_sha) so the next pull sees them as unchanged rather than
+    # re-downloading them as "new". They remain locally deleted — status keeps
+    # showing D until a real variant delete route exists.
+    for fname in skipped_deletes:
+        remote_info = remote_map.get(fname)
+        if remote_info is None:
+            continue  # genuinely gone from the server — let it drop from tracking
+        prev = state.file_checksums.get(fname)
+        new_checksums[fname] = FileChecksum(
+            git_sha=remote_info.get("git_sha", ""),
+            local_hash=prev.local_hash if prev else "",
+        )
+
+    # Never persist a blank baseline. An empty new_head (no commit_sha AND the
+    # HEAD fallback also returned "") would silently disable the optimistic-lock
+    # guard on the next push. The upload/commit already succeeded above, so fail
+    # loudly and tell the user to re-sync rather than corrupting the baseline.
+    if not new_head:
+        raise click.ClickException(
+            "Push completed but could not determine the new HEAD SHA. "
+            "Run `deepcell pull` to re-sync before pushing again."
+        )
+
+    state.last_sync_sha = new_head
+    state.file_checksums = new_checksums
+    save_sync_state(root, state)
+
+    # Skipped variant deletions weren't applied, so they don't count as pushed.
+    total = len(added) + len(modified) + (len(deleted) - len(skipped_deletes))
+    echo_success(
+        f"Pushed {total} change(s) to '{slug}' (HEAD {new_head[:8]})"
+    )
+    if rewritten:
+        echo_info(
+            f"  {len(rewritten)} file(s) updated locally to match server "
+            f"normalization/recalculation: {', '.join(rewritten)}"
+        )
+    if skipped_deletes:
+        echo_warning(
+            f"{len(skipped_deletes)} deletion(s) skipped "
+            "(no variant delete route — files remain on the server)"
+        )
+    if invalid_files:
+        echo_warning(
+            f"Push committed, but {len(invalid_files)} file(s) have validation "
+            f"error(s): {', '.join(invalid_files)} — fix the errors above and "
+            "push again"
+        )
+        raise click.exceptions.Exit(1)
+
+
+# -- commit (server-side pending) ---------------------------------------------
+
+
+@click.command()
+@click.option("-m", "--message", default=None, help="Commit message.")
+@pass_ctx
+def commit(ctx: Ctx, message: str | None) -> None:
+    """Commit changes staged on the server by something other than you.
+
+    You almost certainly do not need this. `defs`, `edit`, `write` and
+    `reasoning` each commit their own change with their own `-m` — there is no
+    staging area they queue into. This commits what a *different* actor left
+    pending on the server, such as files created by an agent session.
+
+    Nothing staged is a no-op, not an error.
+    """
+    root, state = _require_sync_root(ctx)
+    slug = state.workspace_slug
+
+    # `-m` is no longer `required=True`, so this reaches the server even when
+    # the caller gave no message. The server checks "is anything staged"
+    # first and answers the no-op; a commit that will actually write still
+    # 422s without a message, and that is re-raised below as a usage error.
+    #
+    # It used to be rejected by Click during parsing, so a worker whose defs
+    # ops had each already committed and who reasonably tried to finalize got
+    # "Missing option '-m' / '--message'" — an argument-syntax error for a
+    # command with nothing to do. That is what the 2026-08-02 CLI eval hit.
+    data = ctx.client.post(
+        f"/workspaces/{slug}/versions/commit",
+        json={"message": message or ""},
+    )
+
+    # A commit with nothing staged is a benign no-op (the endpoint answers
+    # 200 with committed=false, sha=null) — report it instead of slicing a
+    # null sha.
+    if isinstance(data, dict) and data.get("committed") is False:
+        echo_info(
+            "Nothing to commit — no pending changes. `defs`, `edit`, `write` "
+            "and `reasoning` each commit their own change, so there is "
+            "normally nothing here to finalize."
+        )
+        return
+
+    sha = (data.get("sha") or "")[:8] if isinstance(data, dict) else ""
+    # Staged content is committed either way (the server persists invalid
+    # .deepcell on purpose), so report the errors rather than letting a clean
+    # "Committed" line stand in for them — parity with write/push.
+    invalid = echo_validation_map(
+        data.get("validation") if isinstance(data, dict) else None
+    )
+    if invalid:
+        echo_warning(
+            f"Committed ({sha}), but {len(invalid)} file(s) have validation "
+            f"error(s): {', '.join(invalid)} — fix the errors above"
+        )
+        raise click.exceptions.Exit(1)
+    echo_success(f"Committed ({sha}): {message}")