deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/example.py

@@ -0,0 +1,161 @@
+"""``deepcell example`` — complete, valid documents, indexed by mechanic.
+
+The anti-guessing surface. Models are complicated to build, and an agent that
+guesses at the format gets rejected by the parser; give it a shape that is
+already valid and it copies that instead. See ``docs/cli-agent-surface.md`` §7.
+
+Three layers per example, read in order — skeleton, full, transcript — and the
+transcript is the point. Agents rarely get the XML wrong once they have seen
+one; they routinely get the *verb order* wrong.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import output, print_plain
+
+
+@click.group(invoke_without_command=True)
+@click.option("--pack", default=None, help="Core examples plus this pack's.")
+@pass_ctx
+def example(ctx: Ctx, pack: str | None) -> None:
+    """Complete, valid documents to copy the shape from.
+
+    \b
+    List them:        deepcell example
+    Read the build:   deepcell example show ops/headcount-plan transcript
+    Seed a file:      deepcell example get ops/headcount-plan --into plan.deepcell
+
+    Indexed by the hard feature each demonstrates, not by industry — one
+    example per mechanic, each in a different domain.
+    """
+    if click.get_current_context().invoked_subcommand is not None:
+        return
+    _print_example_list(ctx, pack)
+
+
+def _print_example_list(ctx: Ctx, pack: str | None = None) -> None:
+    """Print every example name and the mechanic it demonstrates."""
+    data = ctx.client.get("/examples", params={"pack": pack} if pack else None)
+    examples = data.get("examples", []) if isinstance(data, dict) else data
+
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    if not isinstance(examples, list) or not examples:
+        print_plain("No examples available.")
+        return
+
+    width = max(len(str(e.get("name", ""))) for e in examples)
+    lines = [
+        f"{str(e.get('name', '')):<{width}}  {e.get('mechanic', '')}"
+        f"  [{' + '.join(str(s).title() for s in e.get('surfaces', []))}]"
+        f"  [{','.join(e.get('journeys', []))}]"
+        f"{'  [' + e['pack'] + ' pack]' if e.get('pack') else ''}"
+        for e in examples
+    ]
+    lines += [
+        "",
+        "Read the build order:  deepcell example show <name> transcript",
+        "Seed a file:           deepcell example get <name> --into <file>",
+    ]
+    print_plain("\n".join(lines))
+
+
+@example.command("list")
+@click.option("--pack", default=None, help="Core examples plus this pack's.")
+@pass_ctx
+def example_list(ctx: Ctx, pack: str | None) -> None:
+    """List every example name — the same output as bare `deepcell example`.
+
+    An alias, and a deliberate one: every other surface with a listing has a
+    verb (`ref search`, `defs list`, `workspace list`), so `example list` is
+    the natural guess, and it used to fail with a bare `No such command`.
+    """
+    _print_example_list(ctx, pack)
+
+
+@example.command("show")
+@click.argument("name", required=False)
+@click.argument("layer", required=False, default="full")
+@pass_ctx
+def example_show(ctx: Ctx, name: str | None, layer: str) -> None:
+    """Print one layer of an example: skeleton, full, or transcript.
+
+    Defaults to `full`. `transcript` is the one worth reading first — it is
+    the ordered command sequence that produced the document, which is the part
+    agents most need and never get.
+
+    With no NAME it lists the examples. Omitting the argument was the one case
+    that got *less* help than getting it wrong — a wrong name has always come
+    back with every legal name and a did-you-mean, while no name at all raised
+    a bare `Missing argument 'NAME'`. Two of eleven tasks in the 2026-08-02 CLI
+    eval hit that, and an empty argument is the clearer request for a list.
+    """
+    if not name:
+        _print_example_list(ctx)
+        return
+    data = ctx.client.get(f"/examples/{name}/layer/{layer}")
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    content = data.get("content", "") if isinstance(data, dict) else str(data)
+    print_plain(content.rstrip())
+
+
+@example.command("get")
+@click.argument("name")
+@click.option(
+    "--into",
+    "into",
+    required=True,
+    type=click.Path(dir_okay=False, writable=True),
+    help="Local path to write the document to.",
+)
+@click.option(
+    "--layer",
+    default="full",
+    type=click.Choice(["skeleton", "full"]),
+    show_default=True,
+    help="Which document to seed from.",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing file.")
+@pass_ctx
+def example_get(ctx: Ctx, name: str, into: str, layer: str, force: bool) -> None:
+    """Write an example document to a local file.
+
+    The file is guaranteed to parse — that is the whole point of seeding from
+    one rather than writing XML from memory. Upload it with
+    `deepcell write <workspace-file> --file <local-file>`, then edit it in
+    place.
+    """
+    target = Path(into)
+    if target.exists() and not force:
+        # Refuse rather than clobber: `--into` is a local path and the caller
+        # may have pointed it at real work.
+        raise click.ClickException(
+            f"{target} already exists. Pass --force to overwrite it."
+        )
+
+    data = ctx.client.get(f"/examples/{name}/layer/{layer}")
+    content = data.get("content", "") if isinstance(data, dict) else str(data)
+    if not content.strip():
+        raise click.ClickException(f"Example {name}/{layer} is empty.")
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+
+    if ctx.fmt == "json":
+        output({"name": name, "layer": layer, "path": str(target),
+                "bytes": len(content.encode("utf-8"))}, ctx.fmt)
+        return
+    print_plain(
+        f"Wrote {target} ({len(content.encode('utf-8'))} bytes) from "
+        f"example {name}/{layer}.\n"
+        f"Upload it:  deepcell write {target.name} --file {target}\n"
+        f"See how it was built:  deepcell example show {name} transcript"
+    )

deepcell_cli/commands/export.py

@@ -0,0 +1,81 @@
+"""``deepcell to-excel`` — export .deepcell files to Excel."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_conversion_warnings, echo_success
+
+
+@click.command()
+@click.argument("filename")
+@click.option("-o", "--output", "out_path", default=None, help="Output file path (default: <filename>.xlsx).")
+@click.option("--formulas", is_flag=True, help="Export with live Excel formulas.")
+@click.option("--recalculate", is_flag=True, help="Recompute formula values via the LibreOffice service (requires --formulas).")
+@click.option("--scenario", "scenario_id", default=None, help="Document scenario ID to export (applies its VariableOverrides; omit for the default scenario).")
+@click.option(
+    "--variant",
+    "variant_id",
+    default=None,
+    hidden=True,
+    help="(removed) Never worked — see --scenario for document scenarios.",
+)
+@pass_ctx
+def to_excel(ctx: Ctx, filename: str, out_path: str | None, formulas: bool, recalculate: bool, scenario_id: str | None, variant_id: str | None) -> None:
+    """Export a .deepcell file to Excel format.
+
+    The exported workbook is shaped by two optional definition sections:
+    PresentationDefinitions (tab/block layout) and FormatDefinitions (cell
+    styling). Run `deepcell guide present/layout` or `deepcell ref format` for
+    details.
+
+    A workbook carries the MODEL: cells, formats and text blocks. It does not
+    carry charts or the SourceDefinitions provenance footnotes — the export
+    reports both as conversion warnings rather than dropping them silently.
+    Read sources with `deepcell ref source`, and take charts to a deck with
+    to-pptx or to the web viewer; see `deepcell guide present/deliver`.
+    """
+    if variant_id is not None:
+        raise click.UsageError(
+            "--variant was removed: the backend's /to-excel has no variant field, "
+            "so the flag silently exported the base model. To export a document "
+            "scenario (Bull/Bear/... defined via `deepcell defs add-scenario`) use "
+            "--scenario SCENARIO_ID. Workspace variants are git branches "
+            "(`deepcell variant list`); to-excel always exports the file content "
+            "of the current variant."
+        )
+
+    if recalculate and not formulas:
+        raise click.UsageError(
+            "--recalculate requires --formulas: the LibreOffice pass recomputes "
+            "the workbook's live formulas, so without --formulas the server "
+            "silently skips it."
+        )
+
+    slug = ctx.require_workspace()
+
+    # Determine output filename
+    if not out_path:
+        base = filename.rsplit(".", 1)[0] if "." in filename else filename
+        out_path = f"{base}.xlsx"
+
+    body: dict = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "filename": out_path,
+        "export_formulas": formulas,
+        "should_recalculate": True,
+        "recalculate": recalculate,
+    }
+    if scenario_id:
+        body["scenario_id"] = scenario_id
+
+    # Server-side recalculation can exceed the default 30s client timeout.
+    resp = ctx.client.post_raw("/to-excel", json=body, timeout=300.0)
+
+    with open(out_path, "wb") as fh:
+        fh.write(resp.content)
+
+    echo_conversion_warnings(resp)
+    echo_success(f"Exported to {out_path} ({len(resp.content)} bytes)")

deepcell_cli/commands/export_docx.py

@@ -0,0 +1,57 @@
+"""``deepcell to-docx`` — export a `<Document>` prose section to Word."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_conversion_warnings, echo_success
+
+
+@click.command()
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Document ID (required when the file has multiple documents).")
+@click.option("--scenario", "scenario_id", default=None, help="Document scenario ID to export.")
+@click.option("-o", "--output", "out_path", default=None, help="Output path (default: <filename>.docx).")
+@click.option("--bundle", "bundle", is_flag=True, default=False, help="Link to sibling .xlsx / .pptx exports written alongside this one.")
+@pass_ctx
+def to_docx(
+    ctx: Ctx,
+    filename: str,
+    doc_id: str | None,
+    scenario_id: str | None,
+    out_path: str | None,
+    bundle: bool,
+) -> None:
+    """Export one document's prose as a Word file.
+
+    Links resolve against what is actually in the export: a bookmark inside
+    this file, a relative link to a sibling artifact written alongside it, and
+    otherwise an absolute viewer URL. Pass ``--bundle`` when the .xlsx and
+    .pptx are being written next to this file, so a cell reference lands on the
+    workbook cell rather than the hosted viewer.
+    """
+    slug = ctx.require_workspace()
+    base = filename.rsplit(".", 1)[0] if "." in filename else filename
+    if not out_path:
+        out_path = f"{base}.docx"
+    body: dict = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "filename": out_path,
+    }
+    if doc_id:
+        body["doc_id"] = doc_id
+    if scenario_id:
+        body["scenario_id"] = scenario_id
+    if bundle:
+        xlsx_name = f"{base}.xlsx"
+        pptx_name = f"{base}.pptx"
+        body["bundle_files"] = [xlsx_name, pptx_name]
+        body["xlsx_name"] = xlsx_name
+        body["pptx_name"] = pptx_name
+    resp = ctx.client.post_raw("/to-docx", json=body, timeout=120.0)
+    with open(out_path, "wb") as fh:
+        fh.write(resp.content)
+    echo_conversion_warnings(resp)
+    echo_success(f"Exported to {out_path} ({len(resp.content)} bytes)")

deepcell_cli/commands/export_pdf.py

@@ -0,0 +1,66 @@
+"""``deepcell to-pdf`` — export a document or a deck as PDF."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_conversion_warnings, echo_success
+
+
+@click.command()
+@click.argument("filename")
+@click.option(
+    "--from", "source", type=click.Choice(["deck", "doc"]), default="deck",
+    show_default=True,
+    help="Which surface to render: the presentation deck, or the prose document.",
+)
+@click.option("--deck", "deck_id", default=None, help="Deck ID (required when the file has multiple decks).")
+@click.option("--doc", "doc_id", default=None, help="Document ID (required when the file has multiple documents).")
+@click.option("--scenario", "scenario_id", default=None, help="Document scenario ID to export.")
+@click.option("-o", "--output", "out_path", default=None, help="Output path (default: <filename>_<deck|doc>.pdf).")
+@pass_ctx
+def to_pdf(
+    ctx: Ctx,
+    filename: str,
+    source: str,
+    deck_id: str | None,
+    doc_id: str | None,
+    scenario_id: str | None,
+    out_path: str | None,
+) -> None:
+    """Export a deck or a document as a PDF.
+
+    The PDF is the PowerPoint or Word export rendered one step further, so it
+    shows exactly what those files show — including anything wrong with them,
+    which is what makes it useful for checking an export you cannot open.
+
+    Needs a server with the LibreOffice service configured; without one the
+    command reports that PDF export is unavailable rather than writing a file.
+    """
+    slug = ctx.require_workspace()
+    base = filename.rsplit(".", 1)[0] if "." in filename else filename
+    if not out_path:
+        # The surface is part of the default name: one file can yield both a deck
+        # PDF and a document PDF, and a shared default would make the second
+        # export silently overwrite the first.
+        out_path = f"{base}_{source}.pdf"
+    body: dict = {
+        "source": source,
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "filename": out_path,
+    }
+    if deck_id:
+        body["deck_id"] = deck_id
+    if doc_id:
+        body["doc_id"] = doc_id
+    if scenario_id:
+        body["scenario_id"] = scenario_id
+    # Two services in series (deck export, then conversion), so the deadline is
+    # the sum rather than either one's.
+    resp = ctx.client.post_raw("/to-pdf", json=body, timeout=240.0)
+    with open(out_path, "wb") as fh:
+        fh.write(resp.content)
+    echo_conversion_warnings(resp)
+    echo_success(f"Exported to {out_path} ({len(resp.content)} bytes)")

deepcell_cli/commands/export_pptx.py

@@ -0,0 +1,45 @@
+"""``deepcell to-pptx`` — export an HTML deck to editable PowerPoint."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_conversion_warnings, echo_success
+
+
+@click.command()
+@click.argument("filename")
+@click.option("--deck", "deck_id", default=None, help="Deck ID (required when the document has multiple decks).")
+@click.option("--scenario", "scenario_id", default=None, help="Document scenario ID to export.")
+@click.option("-o", "--output", "out_path", default=None, help="Output path (default: <filename>.pptx).")
+@pass_ctx
+def to_pptx(
+    ctx: Ctx,
+    filename: str,
+    deck_id: str | None,
+    scenario_id: str | None,
+    out_path: str | None,
+) -> None:
+    """Export one document-defined HTML deck as editable PowerPoint objects."""
+    slug = ctx.require_workspace()
+    if not out_path:
+        base = filename.rsplit(".", 1)[0] if "." in filename else filename
+        out_path = f"{base}.pptx"
+    body: dict = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "filename": out_path,
+        "should_recalculate": True,
+    }
+    if deck_id:
+        body["deck_id"] = deck_id
+    if scenario_id:
+        body["scenario_id"] = scenario_id
+    # Export recalculates and renders every slide in headless Chromium
+    # server-side — far slower than the default 30s client timeout allows.
+    resp = ctx.client.post_raw("/to-pptx", json=body, timeout=300.0)
+    with open(out_path, "wb") as fh:
+        fh.write(resp.content)
+    echo_conversion_warnings(resp)
+    echo_success(f"Exported to {out_path} ({len(resp.content)} bytes)")