deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/deck.py

@@ -0,0 +1,594 @@
+"""``deepcell deck`` — the Deck surface's front door.
+
+A .deepcell file connects four surfaces: Reasoning (ideas), Spreadsheet
+(calculations), Document (prose) and Deck (slides). Three of them had an
+authoring command group. Deck had none — twelve deck and slide ops sat in
+``test_op_reachability.py``'s ``_DELIBERATELY_UNREACHABLE`` under one shared
+justification:
+
+    the payloads carry whole HTML/CSS documents — flags are the wrong shape
+
+Checked against the committed ``openapi.json`` the reachability test itself
+reads from, that is true of **three** of the twelve. ``add_presentation_slide``
+carries ``html``, ``set_presentation_slide_html`` carries ``html``, and
+``set_presentation_deck_style`` carries ``style``. Those three stay on ``defs
+apply``, where a heredoc is the right shape for a document-sized argument.
+
+The other nine take ids, names and indices — ``deckId``, ``slideId``,
+``newName``, ``toIndex`` — which is exactly what flags are for. They are wired
+here. The allowlist's own header says why this is the right direction:
+*"Adding an entry is a deliberate act: prefer wiring the op up."*
+
+So: **structure here, content through `defs apply`.** Creating a deck, naming
+it, ordering its slides, removing one, and pointing a binding at a value are
+all structural. Writing the slide's HTML is not.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from deepcell_cli.commands.defs import _DefsGroup, _apply
+from deepcell_cli.context import Ctx, pass_ctx
+
+#: Mirrors ``UpsertPresentationBindingOp.bindingKind`` in
+#: ``backend/jingwei_api/routers/defs/models/_presentation.py``, which declares
+#: it as a ``Literal``. Declared here as a ``Choice`` so a typo is refused
+#: locally rather than coming back as a 422 — the same standard
+#: ``test_deck_op_shape.py`` applies to the required fields. That test pins
+#: both tuples to the committed schema, so neither can drift silently.
+BINDING_KINDS = (
+    "value", "series", "chart", "document_stat", "reasoning", "source",
+    "htmlblock",
+)
+
+#: Mirrors the same op's ``metric``. These count elements of the document's
+#: provenance and reasoning graphs; they are not derived from the values the
+#: binding reads, which is what this flag's help used to say.
+BINDING_METRICS = (
+    "dataSourceCount",
+    "claimCount",
+    "assumptionCount",
+    "evidenceCount",
+)
+
+#: Mirrors ``AddPresentationDeckOp.aspectRatio``, which is an enum with a
+#: server-side default of ``16:9``. Free text here meant `--aspect-ratio 16:10`
+#: reached the server as a 422 the CLI already had everything to refuse.
+ASPECT_RATIOS = ("16:9", "4:3")
+
+
+def _slug(ctx: Ctx, workspace_slug: str | None) -> str:
+    return workspace_slug or ctx.require_workspace()
+
+
+@click.group(cls=_DefsGroup)
+def deck() -> None:
+    """Build and reorder decks and slides — the Deck surface.
+
+    \b
+    Structure lives here:   deepcell deck add-slide report.deepcell --deck d1 --name "Outlook"
+    Content goes through:   deepcell defs apply report.deepcell --ops '[{"kind": "set_presentation_slide_html", ...}]'
+
+    A slide's HTML and a deck's CSS are document-sized arguments, so they stay
+    on `defs apply` rather than becoming shell flags. Everything structural —
+    creating, naming, ordering, deleting, binding — is here.
+
+    Every command here posts to the same endpoint `defs` does, so every one
+    takes `--dry-run` to pre-flight it and `-m` to name the commit it writes.
+
+    Read `deepcell guide present/decks` for how a deck stays linked to the
+    values it presents.
+    """
+
+
+# ── Decks ───────────────────────────────────────────────────
+
+
+@deck.command("add")
+@click.argument("filename")
+@click.option("--deck-id", default=None, help="Deck id. Omit to let the server assign one.")
+@click.option("--name", required=True, help="Display name for the deck.")
+@click.option(
+    "--aspect-ratio",
+    default=None,
+    type=click.Choice(ASPECT_RATIOS),
+    help="Slide aspect ratio. Omit for the format default (16:9).",
+)
+@click.option("--index", type=int, default=None, help="Position among decks (0-based).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_deck(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str | None,
+    name: str,
+    aspect_ratio: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a Deck to a .deepcell file.
+
+    The deck starts empty. Add slides with `deepcell deck add-slide`, then set
+    each slide's HTML with `defs apply`.
+    """
+    op: dict[str, Any] = {"name": name}
+    if deck_id is not None:
+        op["deckId"] = deck_id
+    if aspect_ratio is not None:
+        op["aspectRatio"] = aspect_ratio
+    if index is not None:
+        op["index"] = index
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [{"kind": "add_presentation_deck", **op}],
+        revision=revision,
+    )
+
+
+@deck.command("rename")
+@click.argument("filename")
+@click.argument("deck_id")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_deck(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change a deck's display NAME. The deckId is unchanged.
+
+    Renaming the id instead would redirect every reference that points at it.
+    """
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "rename_presentation_deck",
+                "deckId": deck_id,
+                "newName": new_name,
+            }
+        ],
+        revision=revision,
+    )
+
+
+@deck.command("reorder")
+@click.argument("filename")
+@click.argument("deck_id")
+@click.argument("to_index", type=int)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_decks(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a deck to TO_INDEX in the deck order (0-based)."""
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "reorder_presentation_decks",
+                "deckId": deck_id,
+                "toIndex": to_index,
+            }
+        ],
+        revision=revision,
+    )
+
+
+@deck.command("delete")
+@click.argument("filename")
+@click.argument("deck_id")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_deck(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a deck and every slide on it.
+
+    This removes the slides' HTML with them. Pass --dry-run first if you are
+    not sure which deck the id names — `deepcell describe` lists them.
+    """
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [{"kind": "delete_presentation_deck", "deckId": deck_id}],
+        revision=revision,
+    )
+
+
+# ── Slides ──────────────────────────────────────────────────
+
+
+@deck.command("add-slide")
+@click.argument("filename")
+@click.option("--deck", "deck_id", required=True, help="Deck to add the slide to.")
+@click.option("--slide-id", default=None, help="Slide id. Omit to let the server assign one.")
+@click.option("--name", required=True, help="Display name for the slide.")
+@click.option("--index", type=int, default=None, help="Position within the deck (0-based).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_slide(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    slide_id: str | None,
+    name: str,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add an empty slide to a deck.
+
+    The slide's HTML is a document-sized argument, so this command never takes
+    it. Set it afterwards, or create and fill the slide in one op — the same
+    `add_presentation_slide` op also accepts `html` on `defs apply`. Start
+    the body from a `deepcell ref deck-layout` entry: class-only HTML on the
+    vocabulary every style pack defines.
+
+    \b
+      deepcell defs apply FILE --ops '[{"kind": "set_presentation_slide_html",
+        "deckId": "d1", "slideId": "s1", "html": "<section>...</section>"}]'
+      deepcell defs apply FILE --ops '[{"kind": "add_presentation_slide",
+        "deckId": "d1", "slideId": "s2", "name": "Risks", "html": "<section>...</section>"}]'
+    """
+    op: dict[str, Any] = {"deckId": deck_id, "name": name}
+    if slide_id is not None:
+        op["slideId"] = slide_id
+    if index is not None:
+        op["index"] = index
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [{"kind": "add_presentation_slide", **op}],
+        revision=revision,
+    )
+
+
+@deck.command("rename-slide")
+@click.argument("filename")
+@click.argument("slide_id")
+@click.argument("new_name")
+@click.option("--deck", "deck_id", required=True, help="Deck the slide belongs to.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_slide(
+    ctx: Ctx,
+    filename: str,
+    slide_id: str,
+    new_name: str,
+    deck_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change a slide's display NAME. The slideId is unchanged."""
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "rename_presentation_slide",
+                "deckId": deck_id,
+                "slideId": slide_id,
+                "newName": new_name,
+            }
+        ],
+        revision=revision,
+    )
+
+
+@deck.command("reorder-slide")
+@click.argument("filename")
+@click.argument("slide_id")
+@click.argument("to_index", type=int)
+@click.option("--deck", "deck_id", required=True, help="Deck the slide belongs to.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_slide(
+    ctx: Ctx,
+    filename: str,
+    slide_id: str,
+    to_index: int,
+    deck_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a slide to TO_INDEX within its deck (0-based)."""
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "reorder_presentation_slides",
+                "deckId": deck_id,
+                "slideId": slide_id,
+                "toIndex": to_index,
+            }
+        ],
+        revision=revision,
+    )
+
+
+@deck.command("delete-slide")
+@click.argument("filename")
+@click.argument("slide_id")
+@click.option("--deck", "deck_id", required=True, help="Deck the slide belongs to.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_slide(
+    ctx: Ctx,
+    filename: str,
+    slide_id: str,
+    deck_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete one slide, and the HTML on it."""
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "delete_presentation_slide",
+                "deckId": deck_id,
+                "slideId": slide_id,
+            }
+        ],
+        revision=revision,
+    )
+
+
+# ── Bindings ────────────────────────────────────────────────
+
+
+@deck.command("bind")
+@click.argument("filename")
+@click.option("--deck", "deck_id", required=True, help="Deck the binding lives on.")
+@click.option("--binding-id", required=True, help="Binding id. Reusing one updates it in place.")
+@click.option(
+    "--binding-kind",
+    required=True,
+    type=click.Choice(BINDING_KINDS),
+    help="What the binding renders. Decides which address flag it takes.",
+)
+@click.option(
+    "--field",
+    default=None,
+    help="Which text of the addressed thing to render, not an address itself.",
+)
+@click.option("--ref", default=None, help="Single coordinate the binding reads.")
+@click.option(
+    "--refs",
+    default=None,
+    help=(
+        "Comma-separated coordinates — the address a `series` binding takes. "
+        "Single-quote an item id that contains a comma."
+    ),
+)
+@click.option(
+    "--metric",
+    default=None,
+    type=click.Choice(BINDING_METRICS),
+    help="For --binding-kind document_stat only: which element type to count.",
+)
+@click.option(
+    "--number-format",
+    default=None,
+    help=(
+        "Excel-style number pattern the value renders with — `#,##0.0`, `0.0%`, "
+        "`#,##0;(#,##0)`. It labels the stored value and never divides it."
+    ),
+)
+@click.option("--prefix", default=None, help="Text rendered before the value.")
+@click.option("--suffix", default=None, help="Text rendered after the value.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def bind(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    binding_id: str,
+    binding_kind: str,
+    field: str | None,
+    ref: str | None,
+    refs: str | None,
+    metric: str | None,
+    number_format: str | None,
+    prefix: str | None,
+    suffix: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Point a slide at a live value, or update an existing binding.
+
+    A binding is what keeps a slide honest: the number on the slide is read
+    from the model rather than typed, so changing the model changes the deck.
+    Create and update are one command — passing an existing --binding-id
+    updates it in place.
+
+    \b
+    Which address flag the kind takes — the server rejects the other one:
+      series                        --refs (comma-separated, ordered)
+      document_stat                 no address; --metric instead
+      value / chart / reasoning / source
+                                    --ref
+      htmlblock                     --ref deepcell:doc/<docId>#<blockId>
+
+    An `htmlblock` shows a designed exhibit authored in a document's prose —
+    a margin bridge, a comparison card. It addresses a `doc` because that is
+    where a block lives; the block stays one thing in one place, so editing
+    the memo changes the slide.
+
+    `--field` selects which text an already-addressed thing renders
+    (`label` / `body` / `excerpt` on reasoning, `title` / `locator` on a
+    source). It is not an address.
+    """
+    op: dict[str, Any] = {
+        "deckId": deck_id,
+        "bindingId": binding_id,
+        "bindingKind": binding_kind,
+    }
+    for key, value in (
+        ("field", field),
+        ("ref", ref),
+        ("metric", metric),
+        ("numberFormat", number_format),
+        ("prefix", prefix),
+        ("suffix", suffix),
+    ):
+        if value is not None:
+            op[key] = value
+    if refs is not None:
+        # Verbatim, and deliberately so. Two things are true here and the
+        # first draft got both wrong.
+        #
+        # It is a STRING on the wire: `UpsertPresentationBindingOp.refs` is
+        # `Optional[str]` and its comment calls it "an ordered comma-separated
+        # list". Sending a split list 422'd on every `--refs` call, which a
+        # mocked test cannot see — hence the schema validation in
+        # `test_deck_op_shape.py`.
+        #
+        # And the splitting is not ours to do. A comma is legal *inside* an
+        # item id when the id is single-quoted
+        # (`deepcell:cell/'Cost,Net'[FY26]`), so the separator can only be
+        # found by a quote-aware scan — `core.refs.binding_ref.split_ref_list`,
+        # which the file validator and the render builder also call. Splitting
+        # and rejoining here strips the space out of `'Cost, Net'` and changes
+        # which item the reference names.
+        op["refs"] = refs
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [{"kind": "upsert_presentation_binding", **op}],
+        revision=revision,
+    )
+
+
+@deck.command("unbind")
+@click.argument("filename")
+@click.argument("binding_id")
+@click.option("--deck", "deck_id", required=True, help="Deck the binding lives on.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def unbind(
+    ctx: Ctx,
+    filename: str,
+    binding_id: str,
+    deck_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Remove a binding, leaving whatever the slide's HTML says in its place."""
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "delete_presentation_binding",
+                "deckId": deck_id,
+                "bindingId": binding_id,
+            }
+        ],
+        revision=revision,
+    )
+
+
+def _parse_role_assignments(pairs: tuple[str, ...]) -> dict[str, str]:
+    roles: dict[str, str] = {}
+    for pair in pairs:
+        role, sep, colour = pair.partition("=")
+        if not sep or not role.strip() or not colour.strip():
+            raise click.BadParameter(f"expected ROLE=#RRGGBB, got {pair!r}", param_hint="--set")
+        roles[role.strip()] = colour.strip()
+    return roles
+
+
+@deck.command("brand")
+@click.argument("filename")
+@click.option("--deck", "deck_id", required=True, help="Deck to recolour.")
+@click.option(
+    "--set",
+    "assignments",
+    multiple=True,
+    metavar="ROLE=#RRGGBB",
+    help="Colour-role override, repeatable: --set accent=#0A5C3B --set ink=#111111. "
+    "Roles are the pack's colour names — accent, ink, series-1 … (`deepcell ref deck-style/hooks`).",
+)
+@click.option("--clear", is_flag=True, help="Remove the brand; the pack's own palette shows again.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def brand(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str,
+    assignments: tuple[str, ...],
+    clear: bool,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Recolour a deck by ROLE without touching its stylesheet.
+
+    A style pack paints through colour roles (`accent`, `ink`, `series-1` …,
+    the `dc-` custom properties it declares). A brand is a set of overrides for those roles, written
+    as `<Brand accent="#0A5C3B"/>` and emitted after the pack's CSS by every
+    renderer, so `deck brand` and a later pack swap compose: the brand
+    survives the restyle. The whole brand is replaced on each call — resend
+    every role you want kept, or `--clear` to drop it.
+    """
+    if clear and assignments:
+        raise click.UsageError("--clear takes no --set; pass one or the other.")
+    if not clear and not assignments:
+        raise click.UsageError("Pass at least one --set ROLE=#RRGGBB, or --clear.")
+    _apply(
+        ctx,
+        _slug(ctx, workspace_slug),
+        filename,
+        [
+            {
+                "kind": "set_presentation_deck_brand",
+                "deckId": deck_id,
+                "roles": {} if clear else _parse_role_assignments(assignments),
+            }
+        ],
+        revision=revision,
+    )