deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/stages.py

@@ -0,0 +1,223 @@
+"""The one authored place a command's stage lives.
+
+The root help carried 51 commands in 13 subsystem sections ordered by nothing,
+plus an ``Other`` catch-all that ``docs/cli-help-review.md`` dimension 6
+forbids by name. Three more hand-maintained groupings of the same command set
+existed alongside it — the MCP tool description, ``docs/cli-commands.md``, and
+the generated manifest, which carried no grouping at all — and they disagreed:
+``changes`` was Version Control in one, Sync in another, and uncategorized in
+``--help``. Nothing tested any of them.
+
+This module is the fix. A command's stage is declared here once; ``main.py``
+renders the index from it, ``surface.py`` emits it into the manifest, and the
+other catalogs derive rather than restate. :func:`assert_fully_staged` turns an
+unstaged command into a loud failure instead of an ``Other`` row.
+
+**The stages are guide's stages**, in guide's order — see
+``backend/src/core/guide/staged.py``. That is the point: an agent that just
+read ``guide generate/calcs`` should already know where ``defs add-calc``
+lives. Two vocabularies for one workflow is the problem this removes.
+
+**Three tiers are deliberately not stages.** Signing in, syncing, and looking
+something up are not steps in building a piece of work — they surround it. A
+seventh "stage" for them would be a lie about the shape of the work, so they
+render as collapsed name runs under their own heading instead.
+"""
+
+from __future__ import annotations
+
+#: Display order. Not alphabetical — it is the order the work happens in, and
+#: an index listing `generate` after `present` would teach the wrong shape.
+STAGE_ORDER: list[str] = [
+    "orient",
+    "ingest",
+    "generate",
+    "revise",
+    "verify",
+    "present",
+]
+
+#: One line per stage, shown as the section header. Kept in step with
+#: ``guide``'s own stage summaries — the wording differs only where a command
+#: index needs to say something a topic index does not.
+STAGE_SUMMARY: dict[str, str] = {
+    "orient": "look at what exists before adding to it",
+    "ingest": "external data in (skip for from-scratch work)",
+    "generate": "create one file, then build only the surfaces the work needs",
+    "revise": "change a premise and reassess what depends on it",
+    "verify": "change one thing, see everything it affects",
+    "present": "deliver the work to someone else",
+}
+
+#: The non-stage tiers, in display order.
+TAIL_ORDER: list[str] = ["session", "sync", "learn"]
+
+TAIL_SUMMARY: dict[str, str] = {
+    "session": "who you are and where your work lands",
+    "sync": "local <-> cloud",
+    "learn": "the five reference surfaces",
+}
+
+#: Every top-level command, and the tier it renders under. A command missing
+#: from this table fails :func:`assert_fully_staged` — which is the whole
+#: reason the table exists, since the old catch-all made "unassigned" invisible.
+#:
+#: Placement notes for the ones that are genuinely arguable:
+#:
+#: * ``cell-meta`` is orient, not verify. It answers "what does this cell rest
+#:   on", which is inspection; ``relationships`` answers "what rests on this",
+#:   which is the impact question verify owns.
+#: * ``download`` is sync, not present. It moves a file to local disk, which is
+#:   what ``clone`` and ``pull`` do; ``share`` and the exports hand work to a
+#:   person.
+#: * ``rm`` is revise, not generate. Deleting is a change to existing work.
+COMMAND_TIER: dict[str, str] = {
+    # ORIENT — look first.
+    "ls": "orient",
+    "cat": "orient",
+    "describe": "orient",
+    "query": "orient",
+    "cell-meta": "orient",
+    "grep": "orient",
+    # INGEST — external data in.
+    "import": "ingest",
+    "ingest": "ingest",
+    # GENERATE — one file, then the surfaces the work needs. The four
+    # surfaces of a .deepcell file each have their authoring command here:
+    # reasoning (ideas), defs/edit (calculations), doc (documents),
+    # deck (slides).
+    "write": "generate",
+    "reasoning": "generate",
+    "defs": "generate",
+    "edit": "generate",
+    "doc": "generate",
+    "deck": "generate",
+    # REVISE — change a premise, reassess what depends on it.
+    "replace": "revise",
+    "variant": "revise",
+    "changes": "revise",
+    "log": "revise",
+    "diff": "revise",
+    "restore": "revise",
+    "rm": "revise",
+    # VERIFY — the connectedness story: change one thing, see what it affects.
+    "relationships": "verify",
+    "claim": "verify",
+    "assumption": "verify",
+    "reasoning-diff": "verify",
+    # `impact` is the whole of that story in one call. The four above each
+    # answer a narrower question and still do; this one is the only one that
+    # carries a change through to the Document sections and Deck slides
+    # instead of stopping at the reasoning node.
+    "impact": "verify",
+    # PRESENT — deliver.
+    "viewer": "present",
+    "share": "present",
+    "to-excel": "present",
+    "to-docx": "present",
+    "to-pptx": "present",
+    "to-pdf": "present",
+    # SESSION — surrounds the work rather than being a step in it.
+    "login": "session",
+    "register": "session",
+    "logout": "session",
+    "whoami": "session",
+    "verify-email": "session",
+    "account": "session",
+    "project": "session",
+    "doctor": "session",
+    "upgrade": "session",
+    # SYNC — local <-> cloud.
+    "clone": "sync",
+    "status": "sync",
+    "pull": "sync",
+    "push": "sync",
+    "commit": "sync",
+    "merge": "sync",
+    "download": "sync",
+    # LEARN — the five reference surfaces.
+    "help": "learn",
+    "guide": "learn",
+    "rules": "learn",
+    "ref": "learn",
+    "example": "learn",
+}
+
+#: Commands whose one-line summary is worth the vertical space in the index,
+#: because a reader choosing between them picks the wrong *tool* otherwise —
+#: ``docs/cli-help-review.md`` dimension 6. Everything else collapses to a name
+#: run, which is what buys the index its one-screen budget back.
+#:
+#: The sets are the sibling groups themselves: inspect-a-file, write-a-value,
+#: and hand-it-over.
+DISAMBIGUATED: frozenset[str] = frozenset(
+    {
+        "describe",
+        "query",
+        "grep",
+        "cell-meta",
+        "edit",
+        "defs",
+        "replace",
+        "write",
+        "reasoning",
+        "doc",
+        "deck",
+        "viewer",
+        "share",
+        "relationships",
+        "changes",
+    }
+)
+
+ALL_TIERS: list[str] = STAGE_ORDER + TAIL_ORDER
+
+TIER_SUMMARY: dict[str, str] = {**STAGE_SUMMARY, **TAIL_SUMMARY}
+
+
+def tier_for(command: str) -> str | None:
+    """The tier ``command`` renders under, or ``None`` if it is unstaged."""
+    return COMMAND_TIER.get(command)
+
+
+def commands_in(tier: str) -> list[str]:
+    """Every command in ``tier``, in declaration order.
+
+    Declaration order, not alphabetical: within a stage the commands are
+    listed in the order the work uses them, so ``write`` precedes the surface
+    authoring commands rather than sorting after ``reasoning``.
+    """
+    return [name for name, t in COMMAND_TIER.items() if t == tier]
+
+
+def assert_fully_staged(command_names: object) -> None:
+    """Raise if any live command has no tier, or any tier names a dead command.
+
+    Both directions matter. An unstaged command used to fall into an ``Other``
+    bucket and nobody noticed for two releases; a stale entry here would keep
+    a deleted command in the index just as quietly.
+    """
+    live = {str(n) for n in command_names}  # type: ignore[union-attr]
+    declared = set(COMMAND_TIER)
+
+    unstaged = sorted(live - declared)
+    if unstaged:
+        raise AssertionError(
+            "Commands with no tier in stages.COMMAND_TIER: "
+            f"{', '.join(unstaged)}. Add each to a stage — there is no "
+            "catch-all bucket to fall into."
+        )
+
+    stale = sorted(declared - live)
+    if stale:
+        raise AssertionError(
+            "stages.COMMAND_TIER names commands that no longer exist: "
+            f"{', '.join(stale)}."
+        )
+
+    bad_tier = sorted(n for n, t in COMMAND_TIER.items() if t not in ALL_TIERS)
+    if bad_tier:
+        raise AssertionError(
+            f"Commands assigned to an unknown tier: {', '.join(bad_tier)}. "
+            f"Valid tiers: {', '.join(ALL_TIERS)}."
+        )