deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/help_cmd.py

@@ -0,0 +1,348 @@
+"""``deepcell help`` — the whole command tree as one document.
+
+``--help`` answers a human's question, one command at a time. An agent
+planning a twelve-step build would pay twelve ``--help`` round trips before it
+could write step one; ``deepcell help -f json`` makes planning a single call,
+and gives the agent something it can cache for the rest of the session.
+
+Everything is local — the Click tree and the surface data both live in this
+package — so this works with no network and no workspace, which is what makes
+it usable as the *first* call rather than one that needs setup first.
+
+See ``docs/cli-agent-surface.md`` §3.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+import click
+
+from deepcell_cli.capabilities import (
+    get_command_capability,
+    load_capability_contract,
+)
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import output, print_plain
+from deepcell_cli.surface import build_commands, build_globals
+
+#: Exit 1 with no command-specific sense. Kept out of the manifest's
+#: ``exit_codes`` map — an explicit "nothing special here" value would look
+#: like a sixth sense of exit 1, and there are five.
+_GENERIC_EXIT_1 = "the command failed"
+
+
+def _render_command(entry: dict) -> str:
+    lines = [entry["name"], "=" * len(entry["name"]), ""]
+    if entry.get("summary"):
+        lines += [entry["summary"], ""]
+
+    lines.append(f"Usage: {entry['example']}")
+    if entry.get("example_source") == "derived":
+        # Never let a derived example pass for a tested one.
+        lines.append("       (shape derived from the signature, not a tested run)")
+    lines.append("")
+
+    if entry["args"]:
+        lines.append("Arguments:")
+        for arg in entry["args"]:
+            suffix = "..." if arg.get("variadic") else ""
+            need = "" if arg["required"] else " (optional)"
+            lines.append(f"  {arg['name']}{suffix}: {arg['type']}{need}")
+        lines.append("")
+
+    if entry["flags"]:
+        lines.append("Flags:")
+        for flag in entry["flags"]:
+            names = ", ".join(flag["flags"])
+            bits = [flag["type"] if not flag["is_flag"] else "flag"]
+            if flag.get("choices"):
+                bits.append("one of: " + "|".join(map(str, flag["choices"])))
+            if "default" in flag:
+                bits.append(f"default {flag['default']}")
+            if flag["required"]:
+                bits.append("required")
+            lines.append(f"  {names}  ({'; '.join(bits)})")
+            if flag.get("help"):
+                lines.append(f"      {flag['help']}")
+        lines.append("")
+
+    lines.append("Exit codes:")
+    for code in sorted(entry["exit_codes"]):
+        lines.append(f"  {code}  {entry['exit_codes'][code]}")
+    if "1" not in entry["exit_codes"]:
+        lines.append(f"  1  {_GENERIC_EXIT_1}")
+    lines.append("  2  malformed input — the command was never attempted")
+
+    if entry["see_also"]:
+        lines += ["", "See also: " + " · ".join(entry["see_also"])]
+        lines.append("Read one: deepcell ref <id>")
+
+    capability = entry.get("capability")
+    if capability:
+        lines += ["", "Availability:"]
+        for transport in ("cli", "mcp", "in_process"):
+            policy = capability["transports"][transport]
+            label = transport.replace("_", "-")
+            if policy["available"]:
+                lines.append(f"  {label}: available")
+            else:
+                lines.append(f"  {label}: unavailable ({policy['reason']})")
+        endpoints = capability.get("endpoints") or []
+        if endpoints:
+            rendered = ", ".join(
+                f"{row['method']} {row['path']}" for row in endpoints
+            )
+            lines.append(f"  Jingwei: {rendered}")
+        elif capability.get("endpoint_exception"):
+            lines.append(
+                "  Jingwei: none "
+                f"({capability['endpoint_exception']['reason']})"
+            )
+
+    return "\n".join(lines)
+
+
+def _render_group(
+    path: str, children: list[str], commands: dict, *, titled: bool = True
+) -> str:
+    """A group as an index of its subcommands, one summary line each.
+
+    ``titled=False`` when this is appended to the group's *own* command help —
+    the heading is already on the page, and repeating it reads as two answers
+    to one question.
+    """
+    lines = [path, "=" * len(path), ""] if titled else []
+    lines += [f"{len(children)} subcommand(s):", ""]
+    width = max(len(c) for c in children)
+    lines += [
+        f"  {name:<{width}}  {commands[name].get('summary', '')}".rstrip()
+        for name in children
+    ]
+    lines += ["", f"One command: deepcell help {children[0]}"]
+    return "\n".join(lines)
+
+
+@lru_cache(maxsize=128)
+def _needle_pattern(needle: str) -> "re.Pattern[str] | None":
+    """Whole-word, separator-flexible matcher — the CLI half of one rule.
+
+    The authority is ``src.core.search_text.needle_pattern``; this package
+    cannot import the backend, so the rule is restated here the same way the
+    two ``guide`` index renderers restate their headings. Keep them in step:
+    whole words because `lag` must not match *flag*, flexible separators
+    because "order mode" is spelled `--order-mode`, and the word guard applied
+    per end only where that end is a word character — `--order-mode` and
+    `.deepcell` start on punctuation that is its own boundary.
+    """
+    words = [p for p in re.split(r"[\s\-_]+", needle) if p]
+    if not words:
+        return None
+    core = r"[\s\-_]+".join(re.escape(w) for w in words)
+    head = r"(?<!\w)" if re.match(r"\w", words[0]) else ""
+    tail = r"(?!\w)" if re.search(r"\w\Z", words[-1]) else ""
+    return re.compile(head + core + tail, re.IGNORECASE)
+
+
+def _detail_hit(text: str, needle: str) -> bool:
+    """Whether *needle* appears as a whole word in *text*."""
+    pattern = _needle_pattern(needle)
+    return bool(pattern and text and pattern.search(text))
+
+
+def _detail_text(entry: dict) -> str:
+    """The parts of a command a name-and-summary search cannot see.
+
+    Flag names and their help, the worked example, and the argument names —
+    all already in memory from `build_commands()`, so widening the index here
+    costs no IO at all. This is where a caller's actual words live: nothing is
+    *summarised* as "sensitivity sweep", but a flag's help says it, and
+    `deepcell help --search` answering "No command matches" to a word the CLI
+    itself prints is the surface calling its own vocabulary unknown.
+    """
+    parts: list[str] = [str(entry.get("example") or "")]
+    for flag in entry.get("flags") or ():
+        parts.append(str(flag.get("name") or ""))
+        parts.append(str(flag.get("help") or ""))
+    for arg in entry.get("args") or ():
+        parts.append(str(arg.get("name") or ""))
+    return "\n".join(p for p in parts if p)
+
+
+def _matching(commands: dict, search: str) -> dict:
+    """Commands matching *search*, name and summary hits first.
+
+    Ordered, not merely filtered: a detail hit may only ever append below the
+    name and summary hits, so widening the index cannot push the command you
+    typed the name of below one that merely mentions it in a flag's help. The
+    same invariant `ref search` and `guide --search` hold, for the same reason.
+    """
+    needle = search.lower()
+    named, detailed = {}, {}
+    for name, entry in commands.items():
+        if needle in name.lower() or needle in (entry.get("summary") or "").lower():
+            named[name] = entry
+        elif _detail_hit(_detail_text(entry), search):
+            detailed[name] = entry
+    return {**named, **detailed}
+
+
+@click.command("help")
+@click.argument("command", nargs=-1)
+@click.option(
+    "--stage",
+    default=None,
+    metavar="NAME",
+    help="Only this stage's commands (e.g. generate). Same stages as `deepcell guide`.",
+)
+@click.option(
+    "--search",
+    default=None,
+    metavar="TEXT",
+    help="Commands whose name or summary matches TEXT.",
+)
+@pass_ctx
+def help_cmd(
+    ctx: Ctx,
+    command: tuple[str, ...],
+    stage: str | None,
+    search: str | None,
+) -> None:
+    """Every command, flag, exit code and example as one document.
+
+    \b
+    The whole tree:   deepcell help
+    One stage:        deepcell help --stage generate
+    Find one:         deepcell help --search sensitivity
+    One command:      deepcell help defs add-calc
+    As data:          deepcell help -f json
+
+    `-f json` is the form to parse: it is the same structure the published
+    command reference is rendered from, so what you read here and what the
+    docs say cannot disagree.
+
+    This answers what to TYPE. For what to DO next — the procedure, in the
+    order the work happens — run `deepcell guide`. The two use the same six
+    stage names, so a stage that reads well in one filters the other.
+    """
+    commands = {
+        name: {
+            **entry,
+            "capability": get_command_capability(name),
+        }
+        for name, entry in build_commands().items()
+    }
+
+    if (stage or search) and command:
+        raise click.ClickException(
+            "--stage/--search filter the listing; they do not apply when you "
+            "have already named a command. Drop the filter, or drop the "
+            f"command: deepcell help {' '.join(command)}"
+        )
+
+    if stage:
+        from deepcell_cli.stages import ALL_TIERS
+
+        if stage not in ALL_TIERS:
+            raise click.ClickException(
+                f"Unknown stage: {stage}. One of: {', '.join(ALL_TIERS)}."
+            )
+        commands = {n: e for n, e in commands.items() if e.get("stage") == stage}
+    if search:
+        commands = _matching(commands, search)
+        if not commands:
+            raise click.ClickException(f"No command matches: {search}")
+
+    if command:
+        path = " ".join(command)
+        entry = commands.get(path)
+        if entry is None:
+            # `build_commands()` keys leaf commands only, so a group path misses
+            # the table. Asking what is under `defs` is a well-formed question
+            # and answering it with a non-zero exit made an agent treat the group
+            # as nonexistent — so render the group's leaves instead. Kept here
+            # rather than in `build_commands()`, whose output is a codegen source
+            # for the surface manifest.
+            children = sorted(
+                name for name in commands if name.startswith(f"{path} ")
+            )
+            if children:
+                if ctx.fmt == "json":
+                    output({"group": path, "commands": children}, ctx.fmt)
+                else:
+                    print_plain(_render_group(path, children, commands))
+                return
+            near = [name for name in commands if name.startswith(path)]
+            hint = f" Did you mean: {', '.join(near[:5])}?" if near else ""
+            raise click.ClickException(f"Unknown command: {path}.{hint}")
+        # A command that is *also* a group (`example`) needs both halves: what
+        # running it bare does, and what lives under it. Rendering only the
+        # command would hide the subcommands that were the whole reason to
+        # look it up.
+        children = sorted(name for name in commands if name.startswith(f"{path} "))
+        if ctx.fmt == "json":
+            output({**entry, "commands": children} if children else entry, ctx.fmt)
+        else:
+            rendered = _render_command(entry)
+            if children:
+                rendered += "\n\n" + _render_group(
+                    path, children, commands, titled=False
+                )
+            print_plain(rendered)
+        return
+
+    if ctx.fmt == "json":
+        contract = load_capability_contract()
+        output(
+            {
+                "commands": commands,
+                "globals": build_globals(),
+                "capabilities": {
+                    "schema_version": contract["schema_version"],
+                    "operation_count": len(contract["operations"]),
+                    "reader": "deepcell guide --capabilities",
+                },
+            },
+            ctx.fmt,
+        )
+        return
+
+    # Grouped by stage, not alphabetical. 161 leaf commands in one A-Z run is
+    # not an index, it is a search problem — the same conclusion the guide
+    # restructure reached about 55 flat topics. The stage names are guide's,
+    # so a reader who oriented there lands in the right block here.
+    from deepcell_cli.stages import ALL_TIERS, TIER_SUMMARY
+
+    width = max(len(name) for name in commands)
+    lines: list[str] = []
+    for tier in ALL_TIERS:
+        block = [(n, e) for n, e in commands.items() if e.get("stage") == tier]
+        if not block:
+            continue
+        if lines:
+            lines.append("")
+        lines.append(f"{tier.upper()} — {TIER_SUMMARY[tier]}")
+        lines += [f"  {name:<{width}}  {entry['summary']}" for name, entry in block]
+    # A command whose top-level name is not staged cannot silently disappear
+    # from the catalog just because the index has no home for it.
+    unstaged = [(n, e) for n, e in commands.items() if e.get("stage") not in ALL_TIERS]
+    if unstaged:
+        lines += ["", "UNSTAGED — no stage declared in deepcell_cli.stages"]
+        lines += [f"  {name:<{width}}  {entry['summary']}" for name, entry in unstaged]
+    # Printed once, at the end, because they apply to every line above — and
+    # because they are declared on the root group, so they appear in no
+    # command's own flag list no matter which one you read.
+    lines += ["", "Global options — valid on any command, before or after it:"]
+    for option in build_globals():
+        names = ", ".join(option["flags"])
+        kind = "flag" if option["is_flag"] else option["type"]
+        lines.append(f"  {names}  ({kind})")
+        if option.get("help"):
+            lines.append(f"      {option['help']}")
+    lines += [
+        "",
+        f"{len(commands)} commands. Read one: deepcell help <command>",
+        "As data (one call, cacheable): deepcell help -f json",
+    ]
+    print_plain("\n".join(lines))