deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/doctor.py

@@ -0,0 +1,257 @@
+"""``deepcell doctor`` — what this machine's DeepCell setup currently is.
+
+An agent that has just installed the CLI needs four facts before it can act:
+the CLI runs, the server answers, who it is signed in as (if anyone), and which
+workspace its next command will land in. Those used to be scattered across
+``--version``, ``whoami``, ``workspace list`` and the Status block appended to
+``--help`` — four calls, three of which fail in exactly the situation you are
+trying to diagnose.
+
+Two rules shape this command:
+
+* **It never changes anything.** In particular it does not mint an anonymous
+  session, which every other authenticated command does on first use. A
+  diagnostic that creates the identity it is reporting on cannot tell you
+  whether you had one.
+* **It always exits 0.** "Not signed in" is an answer, not a failure. Reserving
+  a non-zero exit for "doctor itself could not run" keeps it usable as the
+  first probe in a script that branches on the result.
+
+``--format json`` is the form to parse: ``next_command`` says what to run, so
+an agent can act on the report without reading English. ``problem_kind`` says
+*why* — ``unreachable``, ``auth`` or ``workspace`` — because the same Problem
+line has three different fixes and only one of them is ``deepcell login``.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+import httpx
+
+from deepcell_cli import __version__, upgrade_check
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.errors import AccountRequiredError, AuthError, SessionExpiredError
+from deepcell_cli.errors import ConnectionError as CLIConnectionError
+
+
+def _probe_server(api_url: str, timeout: float) -> tuple[bool, str | None]:
+    """Is the API answering? Unauthenticated, so it works before sign-in."""
+    try:
+        resp = httpx.get(f"{api_url}/health", timeout=timeout)
+    except Exception as exc:  # network, DNS, TLS — all mean "cannot reach it"
+        return False, type(exc).__name__
+    if resp.status_code >= 500:
+        return False, f"HTTP {resp.status_code}"
+    return True, None
+
+
+def _collect(ctx: Ctx, timeout: float, *, probe: bool = True) -> dict:
+    """Gather the setup facts. ``probe=False`` skips the network health check.
+
+    ``--help`` collects the same report but does not show server state, and it
+    is typed far more often than `doctor` is run — one avoidable round trip
+    there is latency on the most-used command in the CLI.
+    """
+    from deepcell_cli import config
+
+    api_url = config.get_api_url()
+    reachable, reason = _probe_server(api_url, timeout) if probe else (True, None)
+
+    token = config.get_access_token()
+    anonymous = config.is_anonymous_session()
+    creds = config.load_credentials()
+
+    if not token:
+        identity = "none"
+    elif anonymous:
+        identity = "anonymous"
+    else:
+        identity = "account"
+
+    # Cached answer only — `doctor` must not add a network hop to the package
+    # index on top of the server probe it already makes.
+    latest = upgrade_check.read_state().get("latest")
+    upgrade_available = upgrade_check.is_newer(latest)
+
+    report: dict = {
+        "cli_version": __version__,
+        "latest_version": latest if isinstance(latest, str) else None,
+        "upgrade_available": upgrade_available,
+        "api_url": api_url,
+        "server_reachable": reachable,
+        "identity": identity,
+        "email": None if identity != "account" else creds.get("email"),
+        "workspace": ctx.workspace or config.get_active_workspace(),
+        "files": None,
+        "problems": [],
+        "problem_kind": None,
+        "available_workspaces": None,
+        "next_command": None,
+    }
+    if not reachable:
+        report["problem_kind"] = "unreachable"
+        report["problems"].append(
+            f"Cannot reach {api_url}"
+            + (f" ({reason})" if reason else "")
+            + ". Check DEEPCELL_API_URL and your network."
+        )
+
+    # Only ask the server about the workspace when there is both a server to ask
+    # and a token to ask with — an unauthenticated call here would 401 and read
+    # as a workspace problem rather than the sign-in state it actually is.
+    if reachable and token and report["workspace"]:
+        try:
+            files = ctx.client.get(f"/workspaces/{report['workspace']}/files")
+            report["files"] = len(files) if isinstance(files, list) else None
+        except click.ClickException as exc:
+            report["problem_kind"] = _classify(exc)
+            report["problems"].append(exc.format_message())
+        except Exception as exc:
+            report["problem_kind"] = "other"
+            report["problems"].append(str(exc))
+
+    # A workspace the server does not know (or will not show you) is a stale
+    # slug in config, not a sign-in problem — `whoami` still works. The fix is
+    # to pick a workspace that exists, so fetch the list once and let
+    # `next_command` name the slug when there is only one to name.
+    if report["problem_kind"] == "workspace":
+        try:
+            workspaces = ctx.client.get("/workspaces")
+        except Exception:
+            workspaces = None
+        if isinstance(workspaces, list):
+            report["available_workspaces"] = [
+                w["slug"] for w in workspaces if isinstance(w, dict) and w.get("slug")
+            ]
+
+    report["next_command"] = _next_command(report)
+    report["ok"] = reachable and not report["problems"]
+    return report
+
+
+def _classify(exc: click.ClickException) -> str:
+    """Which fix a failed workspace probe calls for.
+
+    Decided from the exception type and status code, never from the English of
+    the message — the server rewords ``detail`` freely, and matching on it is
+    how a stale slug came to be answered with ``deepcell login`` for months.
+    """
+    if isinstance(exc, CLIConnectionError):
+        return "unreachable"
+    if isinstance(exc, (AuthError, SessionExpiredError, AccountRequiredError)):
+        return "auth"
+    status = getattr(exc, "status_code", None)
+    if status == 401:
+        return "auth"
+    if status in (403, 404):
+        # Not found, or found but not yours: either way the account is fine
+        # and the slug is what needs changing.
+        return "workspace"
+    return "other"
+
+
+def _next_command(report: dict) -> str:
+    """The single most useful thing to run next, given this report.
+
+    Ordered by what blocks what: an unreachable server makes every other
+    answer moot, and a missing workspace blocks work that a missing account
+    does not — anonymous sessions are a supported way to start, not a fault.
+    """
+    if not report["server_reachable"] or report["problem_kind"] == "unreachable":
+        return "deepcell doctor"
+    if report["problem_kind"] == "workspace":
+        # The saved slug is stale; the account is fine. Name the replacement
+        # when there is exactly one, otherwise show the list and let the
+        # caller choose — guessing among several writes work somewhere else.
+        available = report.get("available_workspaces")
+        if available is not None and len(available) == 1:
+            return f"deepcell project use {available[0]}"
+        if available == [] and report["identity"] == "account":
+            return 'deepcell project create "My Project"'
+        return "deepcell project list"
+    # Only a full account has to create a workspace by hand. With no token the
+    # first command mints an anonymous session, and an anonymous session with no
+    # workspace gets a scratch one provisioned for it — telling either of them
+    # to run `workspace create` would be advice the CLI contradicts one command
+    # later.
+    if report["workspace"] is None and report["identity"] == "account":
+        return 'deepcell project create "My Project"'
+    if report["problem_kind"] == "auth":
+        return "deepcell login"
+    if report["problems"]:
+        # Something the probe could not classify (a 5xx on one route, a
+        # malformed body). Re-running is the honest advice: it is not a
+        # sign-in problem, and `login` is a browser round trip that cannot
+        # fix it.
+        return "deepcell doctor"
+    # Not `guide quick-start`: that topic was a finance template index that
+    # opened by redirecting the reader here, and has since been deleted.
+    return "deepcell guide orient/start"
+
+
+def _render_plain(report: dict) -> list[str]:
+    version_line = f"deepcell {report['cli_version']}"
+    if report.get("upgrade_available"):
+        version_line += (
+            f"  ({report['latest_version']} available — deepcell upgrade)"
+        )
+    lines = [version_line, f"  API        {report['api_url']}"]
+    lines.append(
+        f"  Server     {'reachable' if report['server_reachable'] else 'UNREACHABLE'}"
+    )
+
+    if report["identity"] in ("none", "anonymous"):
+        lines.append("  Identity   not signed in")
+    else:
+        lines.append(f"  Identity   {report['email'] or 'signed in'}")
+
+    if report["workspace"]:
+        count = report["files"]
+        suffix = "" if count is None else f" ({count} file{'s' if count != 1 else ''})"
+        lines.append(f"  Workspace  {report['workspace']}{suffix}")
+    else:
+        lines.append("  Workspace  none yet — one is created for you on first use")
+
+    for problem in report["problems"]:
+        lines.append(f"  Problem    {problem}")
+
+    available = report.get("available_workspaces")
+    if available:
+        shown = ", ".join(available[:5])
+        if len(available) > 5:
+            shown += f", … ({len(available)} total)"
+        lines.append(f"  Available  {shown}")
+
+    lines.append(f"\nNext: {report['next_command']}")
+    return lines
+
+
+@click.command()
+@click.option(
+    "--timeout",
+    type=float,
+    default=10.0,
+    show_default=True,
+    metavar="SECONDS",
+    help="How long to wait for the server probe.",
+)
+@pass_ctx
+def doctor(ctx: Ctx, timeout: float) -> None:
+    """Check this machine's setup: version, server, identity, workspace.
+
+    Reports what is configured and what to run next. Changes nothing, and exits
+    0 even when nothing is set up yet — "not signed in" is an answer.
+
+    \b
+    Examples:
+      deepcell doctor
+      deepcell doctor --format json     # next_command says what to run
+    """
+    report = _collect(ctx, timeout)
+    if ctx.fmt == "json":
+        click.echo(json.dumps(report, indent=2))
+        return
+    for line in _render_plain(report):
+        click.echo(line)

deepcell_cli/commands/download.py

@@ -0,0 +1,36 @@
+"""Download command: save a workspace file to the local filesystem."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_success
+
+
+@click.command()
+@click.argument("filename")
+@click.option("-o", "--output", "out_path", default=None, help="Output file path (default: same as filename).")
+@click.option("--revision", default=None, help="Download file at specific revision.")
+@pass_ctx
+def download(ctx: Ctx, filename: str, out_path: str | None, revision: str | None) -> None:
+    """Download a file from the workspace to the local filesystem."""
+    slug = ctx.require_workspace()
+    params: dict = {}
+    if revision:
+        params["revision"] = revision
+    data = ctx.client.get(f"/workspaces/{slug}/files/{filename}", params=params or None)
+    if not (isinstance(data, dict) and isinstance(data.get("content"), str)):
+        # Never write a repr of the response envelope to disk as if it were
+        # the file — that's a corrupt download masquerading as success.
+        raise click.ClickException(
+            f"Unexpected response for '{filename}' — no file content returned."
+        )
+    content = data["content"]
+    if not content:
+        raise click.ClickException(f"File '{filename}' is empty or not found.")
+    if not out_path:
+        out_path = filename
+    with open(out_path, "w") as fh:
+        fh.write(content)
+    echo_success(f"Downloaded to {out_path} ({len(content)} bytes)")

deepcell_cli/commands/edit.py

@@ -0,0 +1,384 @@
+"""Edit command: single/batch value edit of .deepcell files.
+
+String replacement lives in ``commands/replace.py`` — it is its own command
+(``deepcell replace``) because its exit-1 means something else entirely. The
+``--replace`` flag here is a deprecated alias kept for existing scripts.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from deepcell_cli.commands._batch_input import read_batch_payload
+from deepcell_cli.commands._write_opts import NegativeNumberWriteCommand
+from deepcell_cli.commands._version_display import echo_version_history
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_error,
+    echo_info,
+    echo_query_back_hint,
+    echo_success,
+    echo_warning,
+    output,
+)
+
+# Mirrors BatchEditRequest.change_details max_length in
+# backend/jingwei_api/routers/jingwei.py — keep in sync.
+MAX_CHANGES_PER_BATCH = 1000
+
+# Accepted snake_case spellings of the camelCase wire fields on a batch row
+# (BatchEditRequest / CellRef declare literal camelCase names, no aliases).
+_SNAKE_TO_CAMEL_KEYS = {
+    "item_ref": "itemRef",
+    "context_ref": "contextRef",
+    "status_ref": "statusRef",
+    "scenario_ref": "scenarioRef",
+    "custom_dimensions": "customDimensions",
+    "new_value": "newValue",
+    "is_force_editable": "isForceEditable",
+}
+
+
+@click.command(cls=NegativeNumberWriteCommand)
+@click.argument("filename")
+@click.argument("item_ref", required=False)
+@click.argument("context_ref", required=False)
+@click.argument("new_value", required=False)
+@click.option("--force", is_flag=True, help="Type over a calculated cell, REMOVING the formula that computed it (no in-document undo).")
+@click.option(
+    "--clear",
+    "clear_cell",
+    is_flag=True,
+    help="Remove the literal value cell (NEW_VALUE omitted) so a CalcDef can re-govern it.",
+)
+@click.option("--status", "status_ref", default=None, help="Status reference (e.g. 'projected').")
+@click.option("--scenario", "scenario_ref", default=None, help="Scenario dimension — must be a defined scenarioId (omit for the base cell).")
+@click.option(
+    "--custom-dimensions",
+    "custom_dimensions",
+    default=None,
+    help="Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na;product_line:ent'.",
+)
+@click.option(
+    "--batch",
+    "batch_file",
+    help="Batch edits as a JSON file path, '-' for stdin, or inline JSON "
+    "(a value starting with '[' or '{').",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option(
+    "-m",
+    "--message",
+    "--rationale",
+    "commit_message",
+    default=None,
+    help=(
+        "Why this edit was made. Written as the commit message body (and a "
+        "trailer), so history reads as the decision instead of "
+        "'[batch-edit] Item[Ctx]'. Sent as `rationale`; `-m` / `--message` are "
+        "aliases of `--rationale`."
+    ),
+)
+@click.option(
+    "--title",
+    "commit_title",
+    default=None,
+    help="Short commit subject (e.g. 'Q3 actuals update'). Combined with "
+         "--rationale as 'title: rationale'.",
+)
+@click.option("--auto-create-context", is_flag=True, help="Auto-create missing context definitions.")
+@click.option("--replace", "replace_mode", is_flag=True, help="DEPRECATED alias for `deepcell replace FILE OLD NEW` — still works, will be removed in a future release. Note the exit codes listed here are `edit`'s: in replace mode, exit 1 means the replacement IS already in the file and the document is invalid.")
+@click.option("--replace-all", is_flag=True, help="Replace all occurrences (with the deprecated --replace).")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def edit(
+    ctx: Ctx,
+    filename: str,
+    item_ref: str | None,
+    context_ref: str | None,
+    new_value: str | None,
+    force: bool,
+    clear_cell: bool,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    batch_file: str | None,
+    revision: str | None,
+    commit_message: str | None,
+    commit_title: str | None,
+    auto_create_context: bool,
+    replace_mode: bool,
+    replace_all: bool,
+    workspace_slug: str | None,
+) -> None:
+    """Write literal cell values (assumptions, historical actuals).
+
+    \b
+    Editing modes — pick the right tool:
+      Values (this command)      hardcoded inputs: assumptions, historicals
+      Structure / formulas       `deepcell defs add-calc / add-item / ...`
+      Raw XML                    `deepcell replace FILE OLD NEW`
+
+    \b
+    Derived metrics belong in a CalculationDefinition, NOT here. The
+    backend recomputes every CalcDef on read — see `deepcell guide
+    calc-engine` for the paradigm.
+
+    \b
+    Value mode (default):
+      deepcell edit model.deepcell Revenue_Growth FY2025E 0.12
+      deepcell edit model.deepcell ResearchSpend FY2025E -166667   # negatives work
+      deepcell edit model.deepcell --batch changes.json
+      deepcell edit model.deepcell --batch '[{"itemRef":"Revenue","contextRef":"FY2025E","newValue":"120"}]'
+
+    \b
+    Record WHY, not just what — the rationale becomes the commit message, so
+    `deepcell log` reads as the decision rather than the coordinates:
+      deepcell edit model.deepcell Price FY2025E 42 -m "wk3 price decision"
+
+    \b
+    Scenario / custom-dimension cells (omit the flag to target the base cell):
+      deepcell edit model.deepcell Revenue FY2025E 120 --scenario bull
+      deepcell edit model.deepcell Revenue FY2025E 80 --custom-dimensions "geography:na"
+
+    \b
+    In batch mode, --scenario/--status/--custom-dimensions are per-row
+    defaults: they fill every row that does not set the key itself, and a
+    row-level scenarioRef/statusRef/customDimensions always wins (an
+    explicit null targets the base cell):
+      deepcell edit model.deepcell --batch rows.json --scenario low
+
+    \b
+    Clear mode (remove a literal cell so a CalcDef can re-govern it):
+      deepcell edit model.deepcell Cash FY2025E --clear
+      deepcell edit model.deepcell Revenue FY2025E --clear --scenario bull
+
+    \b
+    Replace mode is DEPRECATED — `deepcell edit FILE --replace OLD NEW` is now
+    `deepcell replace FILE OLD NEW`. The alias still works and warns.
+
+    \b
+    --force types over a CalcDef-computed cell, and REMOVES the formula that
+    computed it: the CalcDef is deleted when the cell is all it drives, or the
+    cell's period is dropped from its contextRefs when it drives more. Where
+    neither can be expressed the edit is refused and the reason is reported.
+    There is no in-document undo — the removed formula is echoed back, and
+    `git` has the rest. Use it rarely; usually the fix is to correct the
+    CalcDef instead. Manually edited values do not carry <Source> provenance.
+
+    \b
+    Two ways to set scenario values:
+      --scenario ID    writes one scenario-specific cell; ID must exist in
+                       ScenarioDefinitions (ids are case-sensitive)
+      VariableOverride formula/bulk overrides, managed via ScenarioDefinitions
+                       (`deepcell guide revise/scenarios`)
+    Base-case values stay untagged — don't pass the default scenario's id;
+    a sheet's default-scenario column reads the untagged cell directly, and
+    a non-default column inherits it wherever the scenario stores no cell.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+
+    if replace_mode:
+        # Deprecated alias. `replace` is its own command because its exit-1
+        # sense ("written, then found invalid") is not `edit`'s ("partially
+        # applied") — see cli/src/deepcell_cli/surface.py:EXIT_SENSE_RULES.
+        from deepcell_cli.commands.replace import do_replace
+
+        echo_warning(
+            "`edit --replace` is deprecated — use "
+            f"`deepcell replace {filename} OLD NEW` instead. The alias still "
+            "works and will be removed in a future release."
+        )
+        do_replace(
+            ctx, slug, filename, item_ref, context_ref, batch_file, replace_all,
+            revision, commit_title, commit_message,
+            usage="deepcell edit FILE --replace OLD NEW",
+        )
+        return
+
+    if batch_file:
+        # Batch mode (inline JSON, stdin, or file path)
+        raw = read_batch_payload(batch_file)
+        try:
+            changes = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(f"Batch JSON does not parse — {exc}") from exc
+        if not isinstance(changes, list):
+            raise click.UsageError("Batch input must be a JSON array of change objects.")
+        # Mirrors BatchEditRequest.change_details max_length. Checked here so a
+        # 2000-cell import says how to fix it instead of failing wholesale with
+        # a raw pydantic 422.
+        if len(changes) > MAX_CHANGES_PER_BATCH:
+            raise click.ClickException(
+                f"{len(changes)} changes exceeds the server limit of "
+                f"{MAX_CHANGES_PER_BATCH} per request. Split the file into "
+                f"batches of {MAX_CHANGES_PER_BATCH} rows and edit each in turn."
+            )
+        # The wire shape is camelCase — BatchEditRequest / CellRef declare
+        # literal field names, no aliases. Agents routinely spell rows in
+        # snake_case (an eval worker's entire edit died on `item_ref` vs
+        # `itemRef` and the starter model shipped unchanged), and the intent
+        # is unambiguous, so normalize client-side instead of 422ing.
+        for row in changes:
+            if not isinstance(row, dict):
+                continue
+            for snake, camel in _SNAKE_TO_CAMEL_KEYS.items():
+                if snake in row:
+                    value = row.pop(snake)
+                    row.setdefault(camel, value)
+        # --scenario/--status/--custom-dimensions/--force/--clear act as
+        # per-row defaults: a row that sets the key itself (even to null,
+        # meaning the base cell) wins. `--force`/`--clear` used to be dropped
+        # here, so `--batch rows.json --force` was accepted and every
+        # calculated-cell edit failed with "cell is calculated".
+        flag_defaults = {
+            "statusRef": status_ref,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "isForceEditable": True if force else None,
+            "clear": True if clear_cell else None,
+        }
+        for key, flag_value in flag_defaults.items():
+            if flag_value is None:
+                continue
+            for row in changes:
+                if isinstance(row, dict) and key not in row:
+                    row[key] = flag_value
+    elif clear_cell and item_ref and context_ref:
+        # Clear a single literal cell — NEW_VALUE is omitted.
+        change = {
+            "itemRef": item_ref,
+            "contextRef": context_ref,
+            "clear": True,
+        }
+        if status_ref:
+            change["statusRef"] = status_ref
+        # scenario / customDimensions are added only when provided so the body
+        # stays byte-minimal for base-cell edits (keys match the pydantic
+        # field names — see docs/backend-cli-contract.md).
+        if scenario_ref:
+            change["scenarioRef"] = scenario_ref
+        if custom_dimensions:
+            change["customDimensions"] = custom_dimensions
+        changes = [change]
+    elif item_ref and context_ref and new_value is not None:
+        # Single edit
+        change: dict = {
+            "itemRef": item_ref,
+            "contextRef": context_ref,
+            "newValue": new_value,
+            "isForceEditable": force,
+        }
+        if status_ref:
+            change["statusRef"] = status_ref
+        if scenario_ref:
+            change["scenarioRef"] = scenario_ref
+        if custom_dimensions:
+            change["customDimensions"] = custom_dimensions
+        changes = [change]
+    else:
+        raise click.UsageError(
+            "Provide ITEM_REF CONTEXT_REF NEW_VALUE for single edit, "
+            "ITEM_REF CONTEXT_REF --clear to clear a cell, or --batch for batch."
+        )
+
+    body: dict = {
+        "workspace_slug": slug,
+        "filename": filename,
+        "change_details": changes,
+    }
+    if revision:
+        body["expected_revision"] = revision
+    if auto_create_context:
+        body["auto_create_context"] = True
+    # Keys match BatchEditRequest.title / .rationale (docs/backend-cli-contract.md).
+    if commit_title:
+        body["title"] = commit_title
+    if commit_message:
+        body["rationale"] = commit_message
+
+    from deepcell_cli.errors import APIError
+    from deepcell_cli.revision import raise_if_stale
+
+    try:
+        data = ctx.client.post("/batch-edit", json=body)
+    except APIError as exc:
+        # This command sends expected_revision but never rendered the 409 it
+        # earns, so a conflict arrived as a bare one-line "Conflict: …" with no
+        # statement of whether the edit was saved and no revision to re-read
+        # at — on the command an agent is most likely to run concurrently.
+        raise_if_stale(exc, filename=filename)
+        raise
+    output(data, ctx.fmt)
+
+    # Show summary
+    if isinstance(data, dict):
+        n_ok = len(data.get("results", []))
+        n_err = len(data.get("errors", []))
+        auto = data.get("auto_created_contexts", [])
+        if auto:
+            echo_info(f"auto-created {len(auto)} context(s): {', '.join(auto)}")
+        if n_err:
+            echo_error(f"{n_ok} edit(s) applied, {n_err} error(s)")
+            # Hint: if any errors are context-not-found and flag wasn't used, suggest it
+            if not auto_create_context:
+                has_ctx_error = any(
+                    "not found" in e.get("error", "") and "Context" in e.get("error", "")
+                    for e in data.get("errors", [])
+                )
+                if has_ctx_error:
+                    echo_info("hint: use --auto-create-context to auto-create missing contexts")
+            has_scenario_error = any(
+                "not found" in e.get("error", "") and "Scenario" in e.get("error", "")
+                for e in data.get("errors", [])
+            )
+            if has_scenario_error:
+                echo_info(
+                    "hint: scenario ids are case-sensitive; define scenarios first "
+                    "with 'deepcell defs add-scenario'"
+                )
+        elif ctx.fmt != "plain":
+            # In plain mode the stdout summary from _format_plain_dict already
+            # reads "N edit(s) applied  rev:abc12345" — don't duplicate on stderr.
+            echo_success(f"{n_ok} edit(s) applied")
+
+        # A clear reports how many cells it removed; 0 means the coordinates
+        # matched nothing (e.g. --scenario bull when the literal is stored
+        # untagged on the base cell). The row is still status="success", so
+        # without this the no-op read exactly like a successful clear.
+        for r in data.get("results", []):
+            if not isinstance(r, dict) or "cleared" not in r:
+                continue
+            if r.get("cleared"):
+                continue
+            coords = " ".join(
+                str(p) for p in (r.get("itemRef"), r.get("contextRef")) if p
+            )
+            echo_warning(
+                f"nothing was cleared for {coords or 'the requested cell'} — "
+                f"no matching value cell at those coordinates. Check "
+                f"--scenario / --status / --custom-dimensions: a literal "
+                f"stored on the base cell is not matched by a scoped clear."
+            )
+
+        # Show warnings (skip formula-mismatch noise)
+        for w in data.get("warnings", []):
+            if "mismatched values" in w:
+                continue
+            echo_warning(f"{w}")
+
+        # Eval S1 / R4: a value just changed — surface the query-back on the
+        # exact cell written, at the one moment it is due.
+        if not n_err and changes:
+            echo_query_back_hint(
+                filename,
+                item=changes[0].get("itemRef"),
+                context=changes[0].get("contextRef"),
+            )
+
+        echo_version_history(data)
+
+        if n_err:
+            raise click.exceptions.Exit(1)