deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/guide.py

@@ -0,0 +1,431 @@
+"""``deepcell guide`` — how DeepCell itself works, served from the topic registry.
+
+The topic index is never restated here or in the command help: ``deepcell guide``
+with no argument prints it from the registry. A hand-maintained copy would rot
+the moment a topic is added. See docs/agent-skills-redesign.md.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.config import get_active_workspace
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.errors import APIError
+from deepcell_cli.output import output, print_plain
+from deepcell_cli.stages import STAGE_ORDER
+
+
+#: Printed above `--all`'s listing, because `--all` is an INDEX and does not
+#: read like one. The 2026-08-27 prompt_stock eval is the case in point: a
+#: worker ran `guide --all`, got every topic name on one screen, and went
+#: straight to writing calcs — never opening `calc-specificity`, the one page
+#: carrying the selector syntax its task needed. The output is ~11k of one-line
+#: descriptions, so an agent that has read it has plausibly "read the guidance"
+#: by every signal except the one that matters.
+#:
+#: One string with real newlines rather than a list of fragments: the list form
+#: needed two source lines per output line and so read as four elements with
+#: missing commas — the exact shape of a real bug, and CodeQL flagged it as
+#: one. Prose belongs in a block that looks like the prose it prints.
+_ALL_TOPICS_BANNER = """\
+{count} topics. These are one-line SUMMARIES, not the guidance itself —
+the syntax, the procedure and the worked examples are in the page, not in
+this index. Open the topics your task touches before you write calcs,
+reasoning or a deck."""
+
+
+def _resolve_frontend_url(content: str) -> str:
+    """Replace ``${FRONTEND_URL}`` / ``${WORKSPACE_SLUG}`` placeholders.
+
+    The frontend URL comes from the ``FRONTEND_URL`` / ``DEEPCELL_FRONTEND_URL``
+    env vars when set, otherwise it is derived from the configured API URL.
+    """
+    from deepcell_cli.config import frontend_base_url
+
+    url = frontend_base_url().rstrip("/")
+    content = content.replace("${FRONTEND_URL}", url).replace(
+        "${DEEPCELL_FRONTEND_URL}", url
+    )
+    return content.replace("${WORKSPACE_SLUG}", get_active_workspace() or "<slug>")
+
+
+@click.command()
+@click.argument("topic", required=False)
+@click.option("--stage", default=None, help="Only this stage's topics (e.g. generate).")
+@click.option(
+    "--pack",
+    default=None,
+    help="One domain pack: its vocabulary page, then its topics (e.g. finance).",
+)
+@click.option("--packs", "list_packs_flag", is_flag=True, help="List the domain packs.")
+@click.option(
+    "--capabilities",
+    "capabilities_flag",
+    is_flag=True,
+    help="Show the Jingwei/CLI/reference/transport capability contract.",
+)
+@click.option("--all", "all_topics", is_flag=True,
+              help="Also show the long-form reference pages and domain packs.")
+@click.option("--search", default=None, metavar="TEXT",
+              help="Topics whose name or description matches, across both catalogs.")
+@pass_ctx
+def guide(
+    ctx: Ctx,
+    topic: str | None,
+    stage: str | None,
+    pack: str | None,
+    list_packs_flag: bool,
+    capabilities_flag: bool,
+    all_topics: bool,
+    search: str | None,
+) -> None:
+    """Explain how DeepCell itself works.
+
+    Topics cover the .deepcell format, calc semantics, built-in functions,
+    layout and decks, and reasoning structure.
+
+    \b
+    List the topics:   deepcell guide
+    One stage:         deepcell guide --stage generate  (a bare stage name works too)
+    Read one:          deepcell guide <topic>
+    Find by keyword:   deepcell guide --search scenario
+    Domain packs:      deepcell guide --packs
+    Capability map:    deepcell guide --capabilities
+    One pack:          deepcell guide --pack finance
+    Everything:        deepcell guide --all
+
+    The listing is generated from the topic registry, so it is always the
+    complete and current set — this help text deliberately does not repeat it.
+    It shows the staged index by default: the work in the order it happens,
+    one screen. `--all` adds two more catalogs — the long-form reference pages
+    behind each stage, and the domain packs.
+    """
+    if capabilities_flag:
+        data = ctx.client.get("/guide/capabilities/index")
+        if ctx.fmt == "json":
+            output(data, ctx.fmt)
+            return
+        operations = data.get("operations", []) if isinstance(data, dict) else []
+        lines = [
+            "Jingwei endpoint -> CLI capability contract",
+            "",
+        ]
+        for operation in operations:
+            commands = operation.get("commands") or []
+            if commands:
+                disposition = ", ".join(commands)
+            else:
+                exception = operation.get("exception") or {}
+                disposition = f"EXEMPT ({exception.get('reason', 'unclassified')})"
+            lines.append(
+                f"{operation.get('method', '?'):<6} "
+                f"{operation.get('path', ''):<72} {disposition}"
+            )
+        lines += [
+            "",
+            f"{len(operations)} operations. As data: deepcell guide "
+            "--capabilities -f json",
+        ]
+        print_plain("\n".join(lines))
+    elif topic and _stage_alias(topic) in STAGE_ORDER and not stage:
+        # A bare stage name is the documented entry point half-typed:
+        # `guide orient` for `guide --stage orient`. Every transcript that
+        # tried it exited 1 with a did-you-mean naming `reit`. The stage
+        # names are the CLI's own (`deepcell_cli.stages` mirrors the guide's,
+        # and a test pins them equal), so no round trip decides this.
+        _list_topics(
+            ctx, stage=_stage_alias(topic), pack=pack,
+            all_topics=all_topics, search=search,
+        )
+    elif topic:
+        data = ctx.client.get(f"/guide/{topic}")
+        # The endpoint returns {"topic": "...", "content": "..."}
+        content = data.get("content", "") if isinstance(data, dict) else str(data)
+        content = _resolve_frontend_url(content)
+        if ctx.fmt == "plain":
+            # Human default: the Markdown body without a metadata wrapper.
+            print_plain(content)
+        else:
+            if isinstance(data, dict) and "content" in data:
+                data["content"] = content
+            output(data, ctx.fmt)
+    elif list_packs_flag:
+        data = ctx.client.get("/guide/packs/index")
+        packs = data.get("packs", []) if isinstance(data, dict) else data
+        if ctx.fmt == "json" or not isinstance(packs, list) or not packs:
+            output(data, ctx.fmt)
+            return
+        width = max(len(str(p.get("name", ""))) for p in packs)
+        lines = [
+            f"{str(p.get('name','')):<{width}}  {p.get('summary','')}"
+            f"  [{_pack_counts(p)}]"
+            for p in packs
+        ]
+        lines += [
+            "",
+            "One pack: deepcell guide --pack <name>",
+            "A pack is a vocabulary over the format, not a different format.",
+        ]
+        print_plain("\n".join(lines))
+    elif pack and not (search or stage or all_topics):
+        # Only the bare `--pack <name>`: combined with `--stage`, `--all` or
+        # `--search` it is a filter on the listing, as it always was.
+        _show_pack(ctx, pack)
+    else:
+        _list_topics(
+            ctx, stage=stage, pack=pack, all_topics=all_topics, search=search
+        )
+
+
+def _stage_alias(topic: str) -> str:
+    """`guide orient/` is `guide orient`: the staged topic names are
+    `orient/start`, so a reader who has seen them types the slash."""
+    return topic.strip().lower().rstrip("/")
+
+
+def _pack_counts(pack: dict) -> str:
+    """`3 topics, 1 example` — so a reader knows a thin pack is thin before
+    opening it, rather than reading an empty listing as a broken command."""
+    topics = len(pack.get("topics") or [])
+    examples = len(pack.get("examples") or [])
+    return (
+        f"{topics} topic{'s' if topics != 1 else ''}, "
+        f"{examples} example{'s' if examples != 1 else ''}"
+    )
+
+
+def _show_pack(ctx: Ctx, pack: str) -> None:
+    """`--pack <name>`: the vocabulary page, then the pack's topics.
+
+    Two reads, on purpose. The listing is what tells an unknown pack apart
+    from a thin one (404 naming the known packs, against a real answer), and
+    the page is the content: three of the four packs are *only* their
+    vocabulary page and one worked example, so a topic listing alone printed
+    `(empty)` for them and the reader stopped there. `-f json` keeps the bare
+    topic list the endpoint returns — the vocabulary row in it names the page
+    to read next.
+    """
+    data = ctx.client.get("/guide", params={"pack": pack})
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    topics = data if isinstance(data, list) else data.get("topics", [])
+    topics = [t for t in topics if isinstance(t, dict)]
+    page_name = f"pack:{pack}"
+    try:
+        page = ctx.client.get(f"/guide/{page_name}")
+    except APIError as exc:
+        # A server without the `pack:<name>` route (older than the vocabulary
+        # page) answers "Unknown topic". The listing above already succeeded,
+        # so the pack is real: render what that server has — the topic rows
+        # — rather than failing a command that used to work against it.
+        if exc.status_code != 404:
+            raise
+        page = None
+    lines: list[str] = []
+    if page is not None:
+        content = page.get("content", "") if isinstance(page, dict) else str(page)
+        lines += [_resolve_frontend_url(content).rstrip("\n"), ""]
+
+    rows = [t for t in topics if t.get("name") != page_name]
+    if rows:
+        width = max(len(str(t.get("name", ""))) for t in rows)
+        lines.append(f"TOPICS  — the {pack} pack's guide pages")
+        lines += [
+            f"  {str(t['name']):<{width}}  {_describe(t)}".rstrip() for t in rows
+        ]
+        lines += ["", "Read a topic: deepcell guide <topic>"]
+    else:
+        # Not `(empty)`: the page above is the whole pack, and saying so is
+        # what stops the reader looking for a listing that does not exist.
+        examples = page.get("examples") if isinstance(page, dict) else None
+        if page is not None:
+            lines.append(
+                f"No guide topics of its own — the {pack} pack is this "
+                "vocabulary page plus its worked example."
+            )
+        else:
+            lines.append(
+                f"No guide topics of its own — the {pack} pack is its worked "
+                "example."
+            )
+        if examples:
+            lines.append(
+                "Worked example: deepcell example show "
+                f"{examples[0]} transcript"
+            )
+        else:
+            lines.append(f"Worked examples: deepcell example --pack {pack}")
+    print_plain("\n".join(lines))
+
+
+def _list_topics(
+    ctx: Ctx,
+    *,
+    stage: str | None,
+    pack: str | None,
+    all_topics: bool,
+    search: str | None,
+) -> None:
+    """The index, narrowed by whatever the caller passed."""
+    params: dict = {}
+    if pack:
+        params["pack"] = pack
+    if stage:
+        params["stage"] = stage
+    if all_topics:
+        params["all"] = "true"
+    if search:
+        params["search"] = search
+    data = ctx.client.get("/guide", params=params or None)
+
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+
+    topics = data if isinstance(data, list) else data.get("topics", [])
+    if not isinstance(topics, list) or not topics:
+        if search:
+            # An empty list rendered as `[]` reads as a broken command
+            # rather than a real answer, and leaves the reader without the
+            # next thing to try — the guide searches names, not bodies.
+            print_plain(
+                f"No topic name or description matches '{search}'.\n"
+                "Browse the full index: deepcell guide --all\n"
+                "Legal values and enumerations: deepcell ref search "
+                f"{search}"
+            )
+            return
+        if stage:
+            # A stage the CLI knows and the server does not list is a
+            # version skew, not a typo; name the stages the server has.
+            print_plain(
+                f"No topics in stage '{stage}'.\n"
+                "Stages with topics: deepcell guide"
+            )
+            return
+        output(data, ctx.fmt)
+        return
+
+    # The generic plain formatter collapses {name, description} rows to
+    # names only — useless for picking a topic — so format it here.
+    width = max(len(str(t.get("name", ""))) for t in topics)
+    lines: list[str] = []
+    if all_topics:
+        # Before the names rather than after them: a reader who needs the
+        # warning is about to skim past the footer. No trailing blank —
+        # the stage loop below opens each band with one whenever `lines`
+        # is already non-empty.
+        lines += _ALL_TOPICS_BANNER.format(count=len(topics)).split("\n")
+    # Group by stage: the sections *are* the index's structure, and a flat
+    # list would throw away the ordering that makes the stages worth
+    # having. The server returns topics already in stage order, so first
+    # appearance is the right order to render them in.
+    current: str | None = "\x00"
+    for t in topics:
+        band = _band_of(t)
+        if band != current:
+            current = band
+            stage_name = t.get("stage")
+            if stage_name:
+                if lines:
+                    lines.append("")
+                header = stage_name.upper()
+                summary = t.get("stage_summary") or ""
+                lines.append(f"{header}  — {summary}" if summary else header)
+            elif all_topics or search:
+                # The appendix used to open with no header at all: 60
+                # unexplained names, which is what made `--all` read as a
+                # second competing catalog rather than an appendix. Say
+                # what it is once, at the top of it — and say it separately
+                # for the two catalogs that were sharing one heading, since
+                # "LEGACY" over `dcf` and `balance-sheet` advises a reader
+                # away from the only page that covers them.
+                if lines:
+                    lines.append("")
+                lines.append(_appendix_header(band))
+        prefix = "  " if t.get("stage") else ""
+        lines.append(
+            f"{prefix}{str(t['name']):<{width}}  {_describe(t)}".rstrip()
+        )
+        # A snippet means the description above does NOT contain the search
+        # term — the match is in the topic's body. Showing the line it
+        # matched on is what makes such a row legible; without it the
+        # reader sees a description with none of their words in it.
+        if t.get("snippet"):
+            lines.append(f"{prefix}{'':<{width}}  ↳ {t['snippet']}")
+
+    lines += ["", "Read a topic: deepcell guide <topic>"]
+    if all_topics:
+        # The other half of the same miss: the worker needed a formula
+        # SELECTOR, which is an enumeration and so has never lived in the
+        # guide at all. Naming `ref` here costs one line and covers the
+        # case where the reader is on the wrong surface entirely.
+        lines.append("Legal values and formula syntax: deepcell ref")
+    if not all_topics and not stage and not search:
+        lines.append(
+            "Long-form reference and domain packs: deepcell guide --all"
+        )
+    print_plain("\n".join(lines))
+
+
+#: The core reference band. Not `LEGACY`: these pages average 2.6x the bytes of
+#: the staged topic that replaced their procedure (`reasoning` is 34,630
+#: against `revise/reasoning`'s 5,122), and the redirect banner they serve says
+#: so — "this page is the full reference and stays authoritative for the detail
+#: below". A heading that called them legacy contradicted the banner printed
+#: underneath them, and told a reader to prefer the shorter page.
+_REFERENCE_HEADER = (
+    "REFERENCE  — the long-form detail behind the staged procedure, still "
+    "authoritative; `→` names the staged topic that owns the procedure"
+)
+
+
+def _band_of(topic: dict) -> str:
+    """Which heading a row belongs under.
+
+    Bands, not stages, because the appendix holds two unrelated catalogs and
+    used to print one heading over both. A stage name is its own band so the
+    staged index still breaks per stage, and a pack is keyed by name so a
+    second pack with topics gets its own heading rather than being folded into
+    finance's.
+    """
+    if topic.get("stage"):
+        return str(topic["stage"])
+    if topic.get("legacy"):
+        return "reference"
+    return f"pack:{topic.get('pack') or 'unknown'}"
+
+
+def _appendix_header(band: str) -> str:
+    """The heading for one appendix band."""
+    if band == "reference":
+        return _REFERENCE_HEADER
+    name = band.split(":", 1)[1]
+    return (
+        f"PACK: {name.upper()}  — domain templates and vocabulary, not part of "
+        f"the core path; list them alone with `deepcell guide --pack {name}`"
+    )
+
+
+def _describe(topic: dict) -> str:
+    """A row's description, plus where its procedure went if it moved.
+
+    A legacy topic and the staged topic that replaced it are the same subject
+    under two names, and `--all` listed both with nothing saying so — leaving
+    the reader to guess whether `items` or `orient/concepts` was the one to
+    open. The server already knows: `replaced_by` is the alias table it has
+    always had. Rendering it turns the appendix from a second, competing
+    catalog into a set of forwarding addresses.
+
+    `guide:` pointers print bare because they are the common case and the
+    prefix is noise; anything else keeps its namespace, since `ref function`
+    and `rules R1` are read with different commands.
+    """
+    description = topic.get("description", "") or ""
+    pointer = topic.get("replaced_by")
+    if not pointer:
+        return description
+    shown = pointer[len("guide:"):] if pointer.startswith("guide:") else pointer
+    return f"{description}  → {shown}".strip()