deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/upgrade.py

@@ -0,0 +1,185 @@
+"""``deepcell upgrade`` — the upgrade check's switch, its state, and how to upgrade.
+
+The group deliberately does **not** install anything. Running ``pip`` from
+inside the running CLI would have to guess how this copy was installed (pip,
+pipx, uv, a venv, the system package manager) and would rewrite the very
+process executing the command. So the CLI reports and prints the exact
+command; the human runs it.
+
+Bare ``deepcell upgrade`` shows status rather than erroring, because that is
+what someone typing it is asking — "am I current, and if not, what do I run?"
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+import click
+
+from deepcell_cli import __version__
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_success
+from deepcell_cli import upgrade_check
+
+
+def _report() -> dict:
+    """Everything the two read-only views show, in one shape."""
+    state = upgrade_check.read_state()
+    latest = state.get("latest")
+    checked_at = state.get("checked_at")
+    known_newer = upgrade_check.is_newer(latest)
+    install_command = (
+        state.get("install_command")
+        or f"pip install --upgrade {upgrade_check.PACKAGE_NAME}"
+    )
+    return {
+        "current": __version__,
+        "latest_known": latest if isinstance(latest, str) else None,
+        "upgrade_available": known_newer,
+        "auto_check_enabled": upgrade_check.config_enabled(),
+        "silenced_by_env": upgrade_check.env_silenced(),
+        "last_checked": (
+            time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(checked_at))
+            if isinstance(checked_at, (int, float)) and not isinstance(checked_at, bool)
+            else None
+        ),
+        "check_interval_hours": upgrade_check.CHECK_INTERVAL_SECONDS // 3600,
+        # Only when there is something to install. Printing an install line
+        # to someone already current reads as "you should run this".
+        "install_command": install_command if known_newer else None,
+    }
+
+
+def _render(report: dict) -> list[str]:
+    lines = [f"deepcell {report['current']}"]
+    if report["latest_known"] is None:
+        lines.append("  Latest     unknown — run `deepcell upgrade check`")
+    elif report["upgrade_available"]:
+        lines.append(f"  Latest     {report['latest_known']} — upgrade available")
+    else:
+        lines.append(f"  Latest     {report['latest_known']} — up to date")
+
+    if report["silenced_by_env"]:
+        state = f"silenced by {upgrade_check.ENV_DISABLE}"
+    elif report["auto_check_enabled"]:
+        state = f"on — at most once every {report['check_interval_hours']}h, in the background"
+    else:
+        state = "off — run `deepcell upgrade enable` to turn it back on"
+    lines.append(f"  Auto-check {state}")
+    lines.append(f"  Last check {report['last_checked'] or 'never'}")
+    if report["install_command"]:
+        lines.append("")
+        lines.append(f"  {report['install_command']}")
+    return lines
+
+
+def _emit(ctx: Ctx, report: dict) -> None:
+    if ctx.fmt == "json":
+        click.echo(json.dumps(report, indent=2))
+        return
+    for line in _render(report):
+        click.echo(line)
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def upgrade(ctx: click.Context) -> None:
+    """Check whether a newer deepcell CLI has been published.
+
+    The check runs by itself at most once a day, in a background thread, and
+    prints a one-line notice on stderr when a newer version exists. It never
+    installs anything and never delays a command — it tells you what to run.
+
+    It is on by default. Turn it off persistently with `deepcell upgrade
+    disable`, or for one process with `DEEPCELL_NO_UPGRADE_CHECK=1`.
+
+    \b
+    Examples:
+      deepcell upgrade                  # am I current, and what do I run?
+      deepcell upgrade check            # ask the index right now
+      deepcell upgrade disable          # stop the automatic notice
+    """
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(status)
+
+
+@upgrade.command("status")
+@pass_ctx
+def status(ctx: Ctx) -> None:
+    """Show the setting and the last cached answer. Never touches the network.
+
+    \b
+    Examples:
+      deepcell upgrade status
+      deepcell upgrade status --format json
+    """
+    _emit(ctx, _report())
+
+
+@upgrade.command("check")
+@click.option(
+    "--timeout",
+    type=float,
+    default=upgrade_check.FETCH_TIMEOUT_SECONDS,
+    show_default=True,
+    metavar="SECONDS",
+    help="How long to wait for each package index.",
+)
+@pass_ctx
+def check(ctx: Ctx, timeout: float) -> None:
+    """Ask the package index right now and update the cached answer.
+
+    Runs even when the automatic check is disabled — asking explicitly is not
+    the thing that was turned off. Exits 0 whether or not an upgrade exists;
+    an unreachable index is reported, not raised.
+
+    \b
+    Examples:
+      deepcell upgrade check
+      deepcell upgrade check --timeout 10
+    """
+    state = upgrade_check.refresh(timeout)
+    report = _report()
+    if ctx.fmt == "json":
+        _emit(ctx, report)
+        return
+    if not state.get("ok"):
+        click.echo(
+            "Could not reach the package index — showing the last known answer.",
+            err=True,
+        )
+    _emit(ctx, report)
+
+
+@upgrade.command("enable")
+def enable() -> None:
+    """Turn the automatic upgrade check on (the default).
+
+    \b
+    Examples:
+      deepcell upgrade enable
+    """
+    upgrade_check.set_enabled(True)
+    echo_success("Automatic upgrade check enabled.")
+    if upgrade_check.env_silenced():
+        click.echo(
+            f"Note: {upgrade_check.ENV_DISABLE} is set in this environment, "
+            "which still silences the notice here.",
+            err=True,
+        )
+
+
+@upgrade.command("disable")
+def disable() -> None:
+    """Turn the automatic upgrade check off.
+
+    Nothing is checked and no notice is printed until `deepcell upgrade
+    enable`. `deepcell upgrade check` still works when asked directly.
+
+    \b
+    Examples:
+      deepcell upgrade disable
+    """
+    upgrade_check.set_enabled(False)
+    echo_success("Automatic upgrade check disabled.")

deepcell_cli/commands/variant.py

@@ -0,0 +1,353 @@
+"""Variant commands: list, create, checkout, diff, merge."""
+
+from __future__ import annotations
+
+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,
+    output,
+    output_mutation,
+)
+from deepcell_cli.sync_state import find_sync_root, load_sync_state, save_sync_state
+
+
+def _require_sync_root_for_variant():
+    """Locate sync root from CWD or raise a ClickException."""
+    from pathlib import Path
+
+    root = find_sync_root()
+    if root is None:
+        raise click.ClickException(
+            "Not inside a synced workspace. Run `deepcell clone <slug>` first."
+        )
+    return root, load_sync_state(root)
+
+
+def _dirty_files(root, state) -> set[str]:
+    """Return tracked files that are missing/changed plus untracked files.
+
+    Mirrors how `status` computes A/M/D (added + modified + deleted).
+    """
+    from deepcell_cli.commands.sync import scan_local_files
+
+    local = scan_local_files(root, tracked=state.file_checksums)
+    changed_or_deleted = {
+        n for n, ck in state.file_checksums.items()
+        if n not in local or local[n] != ck.local_hash
+    }
+    untracked = {n for n in local if n not in state.file_checksums}
+    return changed_or_deleted | untracked
+
+
+def _sync_branch_files(client, slug: str, root, state, variant: str | None) -> None:
+    """Atomically reconcile the working tree to the target branch's files.
+
+    The switch is all-or-nothing: ALL target-branch file contents are downloaded
+    into memory FIRST, and only once every download has succeeded do we touch the
+    disk — writing files, rebuilding checksums, and removing stranded files. If any
+    download fails, we abort having written NOTHING to disk and leaving
+    ``state.file_checksums`` unchanged; the caller never reaches ``save_sync_state``,
+    so sync.json keeps pointing at the previous branch. This prevents a partial
+    switch where files 1..k-1 already hold the target branch's content on disk while
+    sync.json still claims the old branch — which a later main-mode push would
+    happily upload onto main (silent cross-branch corruption).
+
+    Files that were tracked on the previous branch but are absent from the target
+    branch are deleted from disk, so switching branches does not leave orphan files
+    behind (which would otherwise resurface as untracked/added on the next status
+    or push and get re-uploaded onto the wrong branch). Callers must ensure the
+    working tree is clean first (checkout refuses on uncommitted changes), so every
+    local file at this point is tracked — untracked user files are never removed.
+    """
+    from deepcell_cli.commands.sync import _download_branch_file, _get_remote_files
+    from deepcell_cli.sync_state import FileChecksum, compute_local_hash
+
+    previously_tracked = set(state.file_checksums)
+    remote_files = _get_remote_files(client, slug, variant=variant)
+
+    # Phase 1 — download everything into memory. A failure here propagates before
+    # any disk mutation, so the previous branch stays fully intact on disk.
+    downloaded: list[tuple[str, str, str]] = []  # (fname, content, git_sha)
+    for f in remote_files:
+        fname = f["filename"]
+        content = _download_branch_file(client, slug, fname, variant=variant)
+        downloaded.append((fname, content, f.get("git_sha", "")))
+
+    # Phase 2 — commit. Every download succeeded; write each file to a hidden
+    # temp sibling FIRST, then atomically rename it into place. A mid-write
+    # failure (ENOSPC/EACCES) therefore leaves no final file holding the target
+    # branch's content — without this, files 1..k-1 would already be switched on
+    # disk while sync.json still claimed the old branch, which a later main-mode
+    # push would upload onto main (silent cross-branch corruption). Temp names
+    # are dot-prefixed so scan_local_files ignores any that a crash leaves behind.
+    import os
+
+    new_checksums: dict[str, FileChecksum] = {}
+    staged: list[tuple] = []  # (temp_path, final_path)
+    temp_paths: list = []
+    try:
+        for fname, content, git_sha in downloaded:
+            final = root / fname
+            tmp = final.with_name(f".{final.name}.tmp")
+            final.parent.mkdir(parents=True, exist_ok=True)
+            tmp.write_text(content, encoding="utf-8")
+            temp_paths.append(tmp)
+            staged.append((tmp, final))
+            new_checksums[fname] = FileChecksum(
+                git_sha=git_sha,
+                local_hash=compute_local_hash(content),
+            )
+        # All temps written — promote them (fast, per-file atomic).
+        for tmp, final in staged:
+            os.replace(tmp, final)
+    finally:
+        # Remove any temp not promoted (a write failed mid-loop).
+        for tmp in temp_paths:
+            tmp.unlink(missing_ok=True)
+
+    # Remove files tracked on the old branch but not present on the target branch.
+    for stale in previously_tracked - set(new_checksums):
+        (root / stale).unlink(missing_ok=True)
+
+    state.file_checksums = new_checksums
+
+
+@click.group()
+def variant() -> None:
+    """Manage variants (what-if branches).
+
+    Variants let you create parallel assumption sets for the same model —
+    e.g. Base Case, Best Case, Worst Case — without duplicating files.
+    """
+
+
+@variant.command("list")
+@pass_ctx
+def variant_list(ctx: Ctx) -> None:
+    """List variants in the workspace."""
+    slug = ctx.require_workspace()
+    data = ctx.client.get(f"/workspaces/{slug}/variants")
+    output(data, ctx.fmt)
+
+
+@variant.command("create")
+@click.argument("name")
+@pass_ctx
+def variant_create(ctx: Ctx, name: str) -> None:
+    """Create a new variant branch."""
+    slug = ctx.require_workspace()
+    data = ctx.client.post(f"/workspaces/{slug}/variants/{name}", json={})
+    output_mutation(data, ctx.fmt, plain_key="variant_name")
+    echo_success(f"Variant '{name}' created")
+
+
+@variant.command("checkout")
+@click.argument("name", required=False, default=None)
+@click.option("--main", "use_main", is_flag=True, default=False,
+              help="Switch back to the main branch (clear active variant).")
+@pass_ctx
+def variant_checkout(ctx: Ctx, name: str | None, use_main: bool) -> None:
+    """Check out a variant branch for local edits.
+
+    \b
+    deepcell variant checkout exp-1   # switch to variant exp-1
+    deepcell variant checkout main    # return to main
+    deepcell variant checkout --main  # same as above
+    """
+    from deepcell_cli.commands.sync import _get_head_sha
+
+    root, state = _require_sync_root_for_variant()
+    slug = state.workspace_slug
+    target_main = use_main or name == "main"
+
+    # Refuse to switch with uncommitted local changes — a branch switch
+    # overwrites the working tree, so dirty state would be silently clobbered.
+    dirty = _dirty_files(root, state)
+    if dirty:
+        raise click.ClickException(
+            "You have uncommitted local changes: "
+            + ", ".join(sorted(dirty))
+            + ". Push or discard them before switching branches."
+        )
+
+    if target_main:
+        # Pin the optimistic-lock baseline to main's HEAD. Hard-fail on an empty
+        # SHA rather than falling back to the variant's last_sync_sha (which would
+        # leave the baseline pointing at the variant after switching to main and
+        # cause spurious "Remote has new changes" on the next push).
+        main_head = _get_head_sha(ctx.client, slug)
+        if not main_head:
+            raise click.ClickException(
+                "Could not determine main HEAD SHA — cannot set lock baseline. "
+                "Try again, or run `deepcell pull` first."
+            )
+        state.active_variant = ""
+        state.last_sync_sha = main_head
+        _sync_branch_files(ctx.client, slug, root, state, variant=None)
+        save_sync_state(root, state)
+        echo_success("Switched to main branch")
+        return
+
+    if not name:
+        raise click.ClickException("Provide a variant name or use --main to return to main.")
+
+    # Validate the variant exists (404 → APIError → ClickException).
+    try:
+        detail = ctx.client.get(f"/workspaces/{slug}/variants/{name}")
+    except Exception as e:
+        raise click.ClickException(
+            f"Variant '{name}' does not exist (or is unreachable): {e}. "
+            f"Create it with `deepcell variant create {name}`."
+        )
+
+    if not isinstance(detail, dict) or not detail.get("head_sha"):
+        raise click.ClickException(
+            f"Variant '{name}' response missing head_sha — cannot set lock baseline."
+        )
+    state.active_variant = name
+    state.last_sync_sha = detail["head_sha"]
+    _sync_branch_files(ctx.client, slug, root, state, variant=name)
+    save_sync_state(root, state)
+    echo_success(f"Switched to variant '{name}'")
+
+
+@variant.command("diff")
+@click.argument("name", required=False, default=None)
+@click.option("--file", "file_path", default=None, help="Limit the diff to a single file.")
+@pass_ctx
+def variant_diff(ctx: Ctx, name: str | None, file_path: str | None) -> None:
+    """Show diff between a variant branch and main.
+
+    NAME defaults to the currently checked-out variant (active_variant).
+    """
+    root, state = _require_sync_root_for_variant()
+    slug = state.workspace_slug
+
+    variant_name = name or state.active_variant
+    if not variant_name:
+        raise click.ClickException(
+            "No variant name given and no active variant. "
+            "Run `deepcell variant checkout <name>` first, or pass a name."
+        )
+
+    params = {"filename": file_path} if file_path else None
+    data = ctx.client.get(f"/workspaces/{slug}/variants/{variant_name}/diff", params=params)
+    output(data, ctx.fmt)
+
+
+@variant.command("merge")
+@click.argument("name", required=False, default=None)
+@click.option(
+    "--resolve",
+    type=click.Choice(["ours", "theirs"]),
+    default=None,
+    help="Conflict resolution strategy: 'ours' keeps main, 'theirs' keeps variant.",
+)
+@pass_ctx
+def variant_merge(ctx: Ctx, name: str | None, resolve: str | None) -> None:
+    """Merge a variant branch back into main.
+
+    NAME defaults to the currently checked-out variant (active_variant).
+
+    On merge conflicts, re-run with --resolve ours or --resolve theirs.
+    """
+    root, state = _require_sync_root_for_variant()
+    slug = state.workspace_slug
+
+    variant_name = name or state.active_variant
+    if not variant_name:
+        raise click.ClickException(
+            "No variant name given and no active variant. "
+            "Run `deepcell variant checkout <name>` first, or pass a name."
+        )
+
+    data = ctx.client.post(
+        f"/workspaces/{slug}/variants/{variant_name}/merge",
+        json={"resolve": resolve},
+    )
+
+    def _warn_skipped(d: dict) -> None:
+        skipped_nd = d.get("skipped_non_deepcell") or []
+        skipped_del = d.get("skipped_deletes") or []
+        unmerged = d.get("unmerged_items") or []
+        if skipped_nd:
+            echo_warning(
+                "Not merged (non-.deepcell files — copy them onto main manually): "
+                + ", ".join(skipped_nd)
+            )
+        if skipped_del:
+            echo_warning(
+                "Not merged (files deleted on the variant — delete them on main "
+                "manually if intended): " + ", ".join(skipped_del)
+            )
+        if unmerged:
+            echo_warning(
+                "Not merged (items the value-merge could not carry over — add them "
+                "to main manually): " + ", ".join(unmerged)
+            )
+
+    if isinstance(data, dict) and data.get("success"):
+        commit_sha = data.get("commit_sha") or ""
+        echo_success(f"Merged variant '{variant_name}' into main ({commit_sha[:8] if commit_sha else 'ok'})")
+        _warn_skipped(data)
+        # The merge recomputes and validates each merged .deepcell before
+        # committing. It commits either way, so invalid content must be
+        # reported here or it lands on main behind a success message.
+        # Report BOTH before exiting: these are independent failures and the
+        # data-loss message names work the user has to redo by hand. Exiting on
+        # the first one swallowed the second whenever they coincided — the same
+        # swallowed-signal class this sweep exists to close.
+        invalid = echo_validation_map(data.get("validation"))
+        if invalid:
+            echo_error(
+                f"Merge committed, but {len(invalid)} merged file(s) have validation "
+                f"errors: {', '.join(invalid)} — fix them on main"
+            )
+        if data.get("had_data_loss"):
+            echo_error(
+                "Merge committed but some changes were NOT carried over (see warnings "
+                "above). Apply them on main manually."
+            )
+        if invalid or data.get("had_data_loss"):
+            raise click.exceptions.Exit(1)
+        return
+
+    # Not successful — show conflicts.
+    # Keys mirror the backend's _serialise_conflict: file, item_ref, context_ref,
+    # status_ref, base_value, ours_value (main), theirs_value (variant).
+    conflicts = data.get("conflicts", []) if isinstance(data, dict) else []
+    if conflicts:
+        echo_error(f"Merge conflict in variant '{variant_name}':")
+        for c in conflicts:
+            fname = c.get("file", "?")
+            item = c.get("item_ref", "?")
+            cref = c.get("context_ref") or ""
+            sref = c.get("status_ref") or ""
+            coords = ", ".join(p for p in (cref, sref) if p)
+            loc = f"{item}[{coords}]" if coords else item
+
+            def _val(v: object) -> str:
+                return "(absent)" if v is None else str(v)
+
+            click.echo(
+                f"  {fname} {loc}: ours(main)={_val(c.get('ours_value'))} "
+                f"theirs(variant)={_val(c.get('theirs_value'))}",
+                err=True,
+            )
+    else:
+        echo_error(f"Merge failed for variant '{variant_name}'")
+
+    if isinstance(data, dict):
+        _warn_skipped(data)
+
+    click.echo(
+        "Hint: re-run with --resolve ours (keep main) or --resolve theirs (keep variant).",
+        err=True,
+    )
+    raise click.exceptions.Exit(1)