deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/version.py

@@ -0,0 +1,445 @@
+"""Version control commands: log, diff, restore."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.errors import APIError
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_error, echo_info, echo_success, echo_warning, output, output_mutation, print_plain,
+)
+
+
+def _handle_invalid_revision(e: APIError) -> None:
+    """Format invalid-revision API errors with structured output."""
+    detail = e.detail
+    # Parse the structured error from the API
+    # Format: "Invalid revision 'REV'. ERROR. Recent revisions: r1, r2. Use 'deepcell log'..."
+    if "Invalid revision" in detail:
+        # Extract parts for structured display
+        parts = detail.split(". ")
+        echo_error(parts[0])  # "Invalid revision 'REV'"
+        if len(parts) > 1:
+            echo_info(f"  {parts[1]}")  # error detail
+        for part in parts[2:]:
+            if part.startswith("Recent revisions:"):
+                echo_info(f"  {part}")
+            elif "deepcell log" in part:
+                echo_info(f"  Hint: {part}")
+        raise SystemExit(1)
+    raise e
+
+
+@click.command()
+@click.argument("filename_pos", metavar="[FILENAME]", required=False)
+@click.option("--file", "filename", default=None, help="Filter by filename.")
+@click.option("-n", "--limit", default=20, help="Number of entries to show.")
+@click.option(
+    "--after",
+    "after_sha",
+    default=None,
+    help="Pagination cursor: start AFTER this commit sha. Pass the last sha "
+         "of the previous page to read the next one.",
+)
+@pass_ctx
+def log(
+    ctx: Ctx,
+    filename_pos: str | None,
+    filename: str | None,
+    limit: int,
+    after_sha: str | None,
+) -> None:
+    """Show version history for the workspace (like git log).
+
+    The filename filter can be positional (`log model.deepcell`, the form
+    every read command uses) or `--file` — flag-only was a measurable trap
+    (eval U5).
+
+    \b
+    Paging back through a long history:
+      deepcell log -n 20                 # newest 20
+      deepcell log -n 20 --after <sha>   # the 20 after that page's last sha
+    """
+    if filename_pos and filename:
+        raise click.UsageError("Pass FILENAME positionally or via --file, not both.")
+    filename = filename_pos or filename
+    slug = ctx.require_workspace()
+    params: dict = {"max_count": limit}
+    if filename:
+        params["filename"] = filename
+    # Key matches the `after_sha` query param on GET /workspaces/{slug}/versions.
+    if after_sha:
+        params["after_sha"] = after_sha
+    data = ctx.client.get(f"/workspaces/{slug}/versions", params=params)
+    output(data, ctx.fmt)
+
+
+@click.command()
+@click.argument("revision_a")
+@click.argument("revision_b", required=False)
+@click.option("--file", "filename", default=None, help="Filter diff by filename.")
+@pass_ctx
+def diff(ctx: Ctx, revision_a: str, revision_b: str | None, filename: str | None) -> None:
+    """Show diff between two revisions (like git diff).
+
+    \b
+    deepcell diff abc123            # compare revision to HEAD
+    deepcell diff abc123 def456     # compare two revisions
+    """
+    slug = ctx.require_workspace()
+    params: dict = {"from_rev": revision_a}
+    if revision_b:
+        params["to_rev"] = revision_b
+    if filename:
+        params["filename"] = filename
+
+    try:
+        data = ctx.client.get(f"/workspaces/{slug}/versions/diff", params=params)
+    except APIError as e:
+        if e.status_code == 400:
+            _handle_invalid_revision(e)
+        raise
+
+    # If the response is a string (unified diff), print as plain text
+    if isinstance(data, str):
+        print_plain(data)
+    elif isinstance(data, list) and ctx.fmt == "plain":
+        _print_diff_plain(data)
+    else:
+        output(data, ctx.fmt)
+
+
+def _print_diff_plain(entries: list[dict]) -> None:
+    """Format semantic diff results for plain-text display."""
+    if not entries:
+        echo_info("No differences found.")
+        return
+
+    for entry in entries:
+        file_path = entry.get("file_path", "")
+        change_type = entry.get("change_type", "modified")
+        click.echo(click.style(f"--- {file_path} ({change_type})", bold=True), err=False)
+
+        sd = entry.get("semantic_diff")
+        if sd:
+            _print_semantic_diff(sd)
+        elif entry.get("patch"):
+            print_plain(entry["patch"])
+        click.echo("")  # blank line between files
+
+
+# Section keys emitted by the backend's compute_semantic_diff
+# (backend/src/services/git_service.py). Contract: the shared fixture
+# cli/tests/fixtures/semantic_diff_contract.json is generated from the real
+# backend output and both suites test against it — see
+# cli/tests/test_commands/test_version.py and
+# backend/tests/test_semantic_diff_contract.py. If the backend adds a
+# section, regenerate the fixture and add a renderer branch here.
+SEMANTIC_DIFF_SECTIONS = (
+    "items_added",
+    "items_removed",
+    "contexts_added",
+    "contexts_removed",
+    "contexts_changed",
+    "value_changes",
+    "formula_changes",
+    "format_changes",
+    "presentation_changes",
+    "deck_changes",
+    "document_changes",
+    "reasoning_changes",
+    "source_changes",
+    "scenario_changes",
+    "status_changes",
+    "metadata_changes",
+)
+
+
+def _sd_label(entry: dict, id_key: str, name_key: str) -> str:
+    """Format `id (name)`, collapsing to `id` when the name adds nothing."""
+    eid = str(entry.get(id_key, "?"))
+    name = entry.get(name_key)
+    if name and str(name) != eid:
+        return f"{eid} ({name})"
+    return eid
+
+
+def _print_added_removed(sd: dict, added_key: str, removed_key: str, noun: str, name_key: str) -> None:
+    """Render a pair of added/removed sections (items or contexts)."""
+    added = sd.get(added_key, [])
+    if added:
+        click.echo(f"  {noun} Added:")
+        for e in added:
+            click.echo(click.style(f"    + {_sd_label(e, 'id', name_key)}", fg="green"))
+    removed = sd.get(removed_key, [])
+    if removed:
+        click.echo(f"  {noun} Removed:")
+        for e in removed:
+            click.echo(click.style(f"    - {_sd_label(e, 'id', name_key)}", fg="red"))
+
+
+def _echo_old_new(prefix: str, old, new) -> None:
+    """Render `prefix: old -> new` with the old value red and new green."""
+    click.echo(f"{prefix}: ", nl=False)
+    click.echo(click.style(str(old) if old is not None else "(none)", fg="red"), nl=False)
+    click.echo(" -> ", nl=False)
+    click.echo(click.style(str(new) if new is not None else "(none)", fg="green"))
+
+
+def _print_semantic_diff(sd: dict) -> None:
+    """Format a semantic diff section with colored output.
+
+    Renders the sections emitted by the backend's compute_semantic_diff
+    (see SEMANTIC_DIFF_SECTIONS above for the shared-fixture contract).
+    """
+    _print_added_removed(sd, "items_added", "items_removed", "Items", "name")
+    _print_added_removed(sd, "contexts_added", "contexts_removed", "Contexts", "label")
+
+    ctx_changed = sd.get("contexts_changed", [])
+    if ctx_changed:
+        click.echo("  Contexts Changed:")
+        for cc in ctx_changed:
+            prefix = f"    ~ {cc.get('id', '?')} {cc.get('field', '?')}"
+            _echo_old_new(prefix, cc.get("old"), cc.get("new"))
+
+    # Split the values section by cause. A run that edits three assumptions and
+    # recalculates fifty-seven cells printed sixty indistinguishable lines, and
+    # the three worth reading were somewhere in the middle. `derived` is the
+    # backend's answer (a CalcDef governs the cell); an entry without the key
+    # predates it and is shown as an edit, which is the safe way to be wrong —
+    # it over-reports what to read, never under-reports.
+    value_changes = sd.get("value_changes", [])
+    if value_changes:
+        edited = [cv for cv in value_changes if not cv.get("derived")]
+        recalculated = [cv for cv in value_changes if cv.get("derived")]
+
+        def _echo_cells(heading: str, entries: list) -> None:
+            if not entries:
+                return
+            click.echo(heading)
+            for cv in entries:
+                item = cv.get("item", "?")
+                ctx = cv.get("context", "?")
+                status = cv.get("status")
+                cell = f"{item}[{ctx}]" + (f" ({status})" if status else "")
+                _echo_old_new(f"    {cell}", cv.get("old"), cv.get("new"))
+
+        _echo_cells("  Changed Values:", edited)
+        _echo_cells("  Recalculated:", recalculated)
+
+    formula_changes = sd.get("formula_changes", [])
+    if formula_changes:
+        click.echo("  Changed Formulas:")
+        for fc in formula_changes:
+            calc_id = fc.get("id", "?")
+            item = fc.get("item")
+            label = f"{calc_id} ({item})" if item and item != calc_id else str(calc_id)
+            click.echo(f"    {label}:")
+            old_f = fc.get("old_formula")
+            new_f = fc.get("new_formula")
+            if old_f is not None:
+                click.echo(click.style(f"      - {old_f}", fg="red"))
+            if new_f is not None:
+                click.echo(click.style(f"      + {new_f}", fg="green"))
+
+    format_changes = sd.get("format_changes", [])
+    if format_changes:
+        click.echo("  Format Changes:")
+        for fc in format_changes:
+            details = fc.get("details")
+            line = f"    ~ {fc.get('format_id', '?')}: {fc.get('change_type', '?')}"
+            if details:
+                line += f" — {details}"
+            click.echo(line)
+
+    pres_changes = sd.get("presentation_changes", [])
+    if pres_changes:
+        click.echo("  Presentation Changes:")
+        for pc in pres_changes:
+            change_type = pc.get("change_type", "?")
+            target = pc.get("block_id") or pc.get("sheet_id") or "?"
+            name = pc.get("name")
+            line = f"    ~ {change_type}: {target}"
+            if name and name != target:
+                line += f" ({name})"
+            if pc.get("field"):
+                click.echo(line, nl=False)
+                _echo_old_new(f" {pc['field']}", pc.get("old"), pc.get("new"))
+            else:
+                click.echo(line)
+
+    for section_key, id_key, noun in (
+        ("scenario_changes", "scenario_id", "Scenario"),
+        ("status_changes", "status_id", "Status"),
+    ):
+        changes = sd.get(section_key, [])
+        if changes:
+            click.echo(f"  {noun} Changes:")
+            for sc in changes:
+                sign = "+" if sc.get("change_type") == "added" else "-"
+                color = "green" if sign == "+" else "red"
+                click.echo(click.style(f"    {sign} {_sd_label(sc, id_key, 'label')}", fg=color))
+
+    _print_deliverable_changes(sd)
+
+    meta_changes = sd.get("metadata_changes", [])
+    if meta_changes:
+        click.echo("  Metadata Changes:")
+        for mc in meta_changes:
+            _echo_old_new(f"    ~ {mc.get('field', '?')}", mc.get("old"), mc.get("new"))
+
+
+#: Which id a deliverable entry is addressed by, most specific first. A slide
+#: entry carries both a deck id and a slide id; the slide is what changed.
+_DELIVERABLE_ID_KEYS = (
+    "binding_id",
+    "slide_id",
+    "block_id",
+    "claim_id",
+    "assumption_id",
+    "evidence_id",
+    "argument_id",
+    "source_id",
+    "doc_id",
+    "deck_id",
+)
+
+#: Entries that REMOVE something, rendered red with a `-`. `binding_removed` is
+#: on this list and is the one worth spotting: it is Detach, the single action
+#: that costs a number its provenance.
+_DELIVERABLE_REMOVALS = frozenset(
+    {
+        "deck_removed",
+        "slide_removed",
+        "document_removed",
+        "block_removed",
+        "claim_removed",
+        "binding_removed",
+        # The reasoning graph. `argument_removed` is on this list for the same
+        # reason `binding_removed` is: it is a retraction. An edge that stops
+        # existing is a conclusion that stops being held up by something, and
+        # nothing else in the diff says so.
+        "assumption_removed",
+        "evidence_removed",
+        "argument_removed",
+        "source_removed",
+    }
+)
+
+_DELIVERABLE_ADDITIONS = frozenset(
+    {
+        "deck_added",
+        "slide_added",
+        "document_added",
+        "block_added",
+        "claim_added",
+        "binding_added",
+        "assumption_added",
+        "evidence_added",
+        "argument_added",
+        "source_added",
+    }
+)
+
+
+def _print_deliverable_changes(sd: dict) -> None:
+    """Render the deck, document and reasoning sections.
+
+    One renderer for three sections because the entries share a shape: a
+    `change_type`, an id, and an optional `old`/`new` pair. Three near-identical
+    branches would drift the first time one of them gained a field.
+    """
+    for section_key, noun in (
+        ("deck_changes", "Deck"),
+        ("document_changes", "Document"),
+        ("reasoning_changes", "Reasoning"),
+        ("source_changes", "Source"),
+    ):
+        changes = sd.get(section_key, [])
+        if not changes:
+            continue
+        click.echo(f"  {noun} Changes:")
+        for entry in changes:
+            change_type = entry.get("change_type", "?")
+            target = next(
+                (str(entry[key]) for key in _DELIVERABLE_ID_KEYS if entry.get(key)),
+                "?",
+            )
+            # `@id` on an <Argument> is optional, so an edge entry may carry no
+            # id at all. Its address is the (from, rel, to) triple, and printing
+            # "?" for the one element kind that routinely has no id would make
+            # every retracted edge unreadable.
+            if target == "?" and entry.get("rel"):
+                target = (
+                    f"{entry.get('from', '?')} -{entry['rel']}-> {entry.get('to', '?')}"
+                )
+            if change_type in _DELIVERABLE_ADDITIONS:
+                sign, color = "+", "green"
+            elif change_type in _DELIVERABLE_REMOVALS:
+                sign, color = "-", "red"
+            else:
+                sign, color = "~", None
+            name = entry.get("name") or entry.get("label")
+            line = f"    {sign} {change_type}: {target}"
+            if name and str(name) != target:
+                line += f" ({name})"
+            if entry.get("field"):
+                line += f" {entry['field']}"
+            styled = click.style(line, fg=color) if color else line
+            # `old`/`new` carry the whole content of a rebind, so print them
+            # where they exist rather than leaving "binding_modified: b3" as
+            # the entire account of a number that changed what it points at.
+            if entry.get("old") is not None or entry.get("new") is not None:
+                click.echo(styled, nl=False)
+                _echo_old_new("", entry.get("old"), entry.get("new"))
+            else:
+                click.echo(styled)
+
+
+@click.command()
+@click.argument("revision")
+@click.option("--file", "filename", default=None, help="Restore specific file only.")
+@click.option("-y", "--yes", is_flag=True, help="Skip confirmation prompt.")
+@pass_ctx
+def restore(ctx: Ctx, revision: str, filename: str | None, yes: bool) -> None:
+    """Restore the workspace to a previous revision (like git checkout).
+
+    Restores every file unless --file names one. A full restore rebuilds the
+    tree from the target revision alone, so **files added after it are
+    deleted** — the response lists any it removed. Restoring is itself a new
+    commit, so nothing is lost for good: restore a newer revision to undo it.
+
+    This moves the workspace on the server. Local folders are untouched until
+    you `deepcell pull`.
+    """
+    if not yes:
+        click.confirm("Are you sure you want to restore this revision?", abort=True)
+    slug = ctx.require_workspace()
+    body: dict = {"target_version": revision}
+    if filename:
+        body["filename"] = filename
+
+    try:
+        data = ctx.client.post(f"/workspaces/{slug}/versions/restore", json=body)
+    except APIError as e:
+        if e.status_code == 400:
+            _handle_invalid_revision(e)
+        raise
+
+    output_mutation(data, ctx.fmt, plain_key="sha")
+    echo_success(f"Restored to revision {revision[:8]}")
+
+    # A whole-workspace restore rebuilds the tree from the target alone, so
+    # every file added after it is deleted. Nothing said so — the command
+    # printed a sha and exited 0 while the files were gone.
+    deleted = (data or {}).get("files_deleted") or []
+    if deleted:
+        echo_warning(
+            f"{len(deleted)} file(s) added after {revision[:8]} were DELETED: "
+            + ", ".join(str(f) for f in deleted)
+        )
+        echo_warning(
+            "Recover them from a newer revision (`deepcell log`, then "
+            "`deepcell download <file> --revision <sha>`)."
+        )

deepcell_cli/commands/viewer.py

@@ -0,0 +1,54 @@
+"""``deepcell viewer`` — print the browser URL to open a workspace file.
+
+A local URL constructor (no API call of its own — resolving the active
+workspace may still hit ``GET /workspaces``): signed-in sessions get the
+authenticated workbench route (``/agent?assistantId=deepcell&workspaceSlug=…
+&file=…``) where they operate with full auth — editing, agent chat, history.
+Anonymous sessions can't sign into the browser as the CLI's device-keyed
+identity, so the command points them at ``share create`` / ``login`` instead.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+import click
+
+from deepcell_cli.config import frontend_base_url, is_anonymous_session
+from deepcell_cli.context import Ctx, pass_ctx
+
+
+def workbench_url(slug: str, filename: str) -> str:
+    """The authenticated workbench deep link for *filename* in *slug*."""
+    query = urlencode(
+        {"assistantId": "deepcell", "workspaceSlug": slug, "file": filename}
+    )
+    return f"{frontend_base_url()}/agent?{query}"
+
+
+@click.command()
+@click.argument("filename")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@click.option("--open", "launch", is_flag=True, help="Open the URL in the default browser.")
+@pass_ctx
+def viewer(ctx: Ctx, filename: str, workspace_slug: str | None, launch: bool) -> None:
+    """Print the browser URL to open FILENAME in the web workbench.
+
+    Requires a signed-in session — the workbench authenticates as your
+    account. Otherwise create a public view link with
+    `deepcell share create <file>` instead, or run `deepcell login` first.
+    """
+    # Check anonymity before resolving the workspace: require_workspace()
+    # would otherwise auto-provision a scratch workspace for an anon session
+    # only for this command to error out anyway.
+    if is_anonymous_session():
+        raise click.ClickException(
+            "The browser can't sign in as this CLI session.\n"
+            f"To view the file, create a view link: deepcell share create {filename}\n"
+            "For the full workbench (edit, agent chat), run `deepcell login` first."
+        )
+    slug = workspace_slug or ctx.require_workspace()
+    url = workbench_url(slug, filename)
+    click.echo(url)
+    if launch:
+        click.launch(url)

deepcell_cli/commands/workspace.py

@@ -0,0 +1,101 @@
+"""Project commands: list, use, info, create.
+
+The Click-visible name is ``project``; ``workspace`` stays as a hidden
+alias registered in ``main``. The MODULE keeps its name so it still
+mirrors ``backend/jingwei_api/routers/workspaces.py`` 1:1, and so do the
+function names and the ``active_workspace`` config key — renaming that
+key would silently drop every existing user's active selection.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.config import get_active_workspace, set_active_workspace
+from deepcell_cli.errors import EmailVerificationRequired
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_error, echo_info, echo_success, output, output_mutation
+
+
+@click.group("project")
+def project() -> None:
+    """Manage projects.
+
+    A project is a container for .deepcell files, version history, and
+    variants. Most commands require an active project — set one with
+    `deepcell project use <slug>`.
+    """
+
+
+@project.command("list")
+@pass_ctx
+def workspace_list(ctx: Ctx) -> None:
+    """List projects you belong to."""
+    data = ctx.client.get("/workspaces")
+    active = get_active_workspace()
+    for ws in data:
+        if isinstance(ws, dict):
+            ws["active"] = ws.get("slug") == active
+    output(data, ctx.fmt)
+
+
+@project.command("use")
+@click.argument("slug")
+@pass_ctx
+def workspace_use(ctx: Ctx, slug: str) -> None:
+    """Set the active project for subsequent commands."""
+    # Validate the project exists and user has access
+    ctx.client.get(f"/workspaces/{slug}")
+    set_active_workspace(slug)
+    echo_success(f"Active project set to '{slug}'")
+
+
+@project.command("info")
+@click.argument("slug", required=False)
+@pass_ctx
+def workspace_info(ctx: Ctx, slug: str | None) -> None:
+    """Show project details."""
+    slug = slug or ctx.require_workspace()
+    data = ctx.client.get(f"/workspaces/{slug}")
+    output(data, ctx.fmt)
+
+
+@project.command("create")
+@click.argument("name")
+@click.option(
+    "--slug",
+    help=(
+        "URL-friendly slug. Derived from the name by the server, with a short "
+        "random suffix, if omitted — slugs are unique across all projects."
+    ),
+)
+@click.option("--description", default="", help="Project description.")
+@pass_ctx
+def workspace_create(ctx: Ctx, name: str, slug: str | None, description: str) -> None:
+    """Create a new project."""
+    # Omitted `--slug` is sent as nothing at all, and the server derives one.
+    # It is the only party that can: slugs are globally unique while
+    # `GET /workspaces` returns only your own, so anything derived here is a
+    # guess against a namespace this process cannot read. Deriving locally also
+    # could not name a CJK project at all — stripping non-ASCII left "", under
+    # the server's 3-character floor, so the command refused a name the server
+    # is perfectly able to slug.
+    body: dict = {"name": name, "description": description}
+    if slug:
+        body["slug"] = slug
+    try:
+        data = ctx.client.post("/workspaces", json=body)
+    except EmailVerificationRequired:
+        echo_info("Email verification is required to create projects.")
+        from deepcell_cli.commands.auth import _run_verification_flow
+
+        if _run_verification_flow(ctx):
+            # Retry after successful verification
+            data = ctx.client.post("/workspaces", json=body)
+        else:
+            echo_error("Email verification failed. Cannot create project.")
+            raise SystemExit(1)
+    output_mutation(data, ctx.fmt, plain_key="slug")
+    echo_success(f"Project '{data.get('slug', name)}' created")
+
+