induscode 0.1.0__py3-none-any.whl

induscode/console_slash/contract.py

@@ -0,0 +1,185 @@
+"""Slash framework contracts — the frozen types the registry, resolver, and
+every command group are written against.
+
+Port of the slash portion of TS ``src/console/contract.ts`` (the
+``SlashOutcome`` / ``SlashContext`` / ``SlashCommand`` / ``SlashRegistry``
+types). Discriminated unions become frozen dataclasses carrying ``ClassVar``
+``Literal`` kind tags (the framework house style); the rest are mechanical
+snake_case renames.
+
+Two deliberate deltas from the TS shape, both locked by the port plan:
+
+- **All ``run`` callables are async.** TS allowed
+  ``SlashOutcome | Promise<SlashOutcome>``; the Python dispatcher awaits one
+  uniform calling convention (``async def run(ctx) -> SlashOutcome``), which
+  makes busy→info status sequences deterministic and lets tests flush with
+  ``await asyncio.sleep(0)`` instead of ``setTimeout(0)``.
+- **:class:`SlashContext` is a dataclass of callables**, not an interface of
+  methods: a scripted recorder test builds one from plain lambdas, mirroring
+  the TS recorder-fake ergonomics 1:1.
+
+Cross-milestone notes: ``conductor`` is typed :data:`typing.Any` until the
+``SessionConductor`` protocol lands with M2 (``induscode.conductor``); the
+``dispatch`` event union and the ``ModalKind`` literal belong to the M5
+console contract — here ``open_modal`` takes the kind as ``str`` through the
+:class:`OpenModal` protocol so the framework stays a pure M1 leaf.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal, Protocol, TypeAlias
+
+from indusagi.react_ink import StatusMessage, UiDisplayBlock
+
+__all__ = [
+    "Handled",
+    "OpenModal",
+    "Prompt",
+    "SlashCommand",
+    "SlashContext",
+    "SlashOutcome",
+    "SlashRegistry",
+    "SlashRun",
+    "Unknown",
+]
+
+
+# ---------------------------------------------------------------------------
+# SlashOutcome — what a handler reports back to the dispatcher
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Handled:
+    """The command ran; nothing further is needed."""
+
+    kind: ClassVar[Literal["handled"]] = "handled"
+
+
+@dataclass(frozen=True, slots=True)
+class Prompt:
+    """The command produced text to be submitted as a normal turn."""
+
+    kind: ClassVar[Literal["prompt"]] = "prompt"
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class Unknown:
+    """The command name did not match; the dispatcher falls through to
+    templates / plugin commands / a literal prompt."""
+
+    kind: ClassVar[Literal["unknown"]] = "unknown"
+
+
+#: The result a :attr:`SlashCommand.run` resolves to (TS ``SlashOutcome``).
+SlashOutcome: TypeAlias = Handled | Prompt | Unknown
+
+
+# ---------------------------------------------------------------------------
+# SlashContext — the command's whole world
+# ---------------------------------------------------------------------------
+
+
+class OpenModal(Protocol):
+    """Raise a modal overlay: ``open_modal(kind, payload=None)``.
+
+    ``kind`` is one of the console's ``ModalKind`` literals (M5 contract);
+    ``payload`` is opaque at this layer — each dialog narrows it at its own
+    boundary, exactly as the TS contract left it ``unknown``.
+    """
+
+    def __call__(self, kind: str, payload: object | None = None) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SlashContext:
+    """The capabilities a :attr:`SlashCommand.run` is handed to act on the
+    console (TS ``SlashContext``).
+
+    The context is the command's whole world: it drives the session
+    conductor, mutates UI state through ``dispatch``, raises overlays, and
+    surfaces status. Keeping every effect behind this object keeps handlers
+    pure with respect to the TUI host and lets tests pass a scripted fake
+    built from plain recording lambdas.
+    """
+
+    # The raw argument string after the command name (may be empty).
+    args: str
+    # The session this console drives (SessionConductor; protocol lands M2).
+    conductor: Any
+    # Dispatch a reducer event to mutate console state (ConsoleEvent union
+    # lands with the M5 console contract; opaque here).
+    dispatch: Callable[[Any], None]
+    # Raise a modal overlay.
+    open_modal: OpenModal
+    # Drop the active overlay.
+    close_modal: Callable[[], None]
+    # Ask the host process to leave the interactive console (/quit, /exit).
+    request_exit: Callable[[], None]
+    # Show a transient status message.
+    set_status: Callable[[StatusMessage], None]
+    # Replace the composer buffer (e.g. to pre-fill a follow-up).
+    set_buffer: Callable[[str], None]
+    # Append an out-of-band display block.
+    append_block: Callable[[UiDisplayBlock], None]
+
+
+# ---------------------------------------------------------------------------
+# SlashCommand — one row in the registry
+# ---------------------------------------------------------------------------
+
+
+#: The uniform handler signature: every command is ``async`` and the
+#: dispatcher awaits it (locked cross-cutting rule; see module docstring).
+SlashRun: TypeAlias = Callable[["SlashContext"], Awaitable[SlashOutcome]]
+
+
+@dataclass(frozen=True, slots=True)
+class SlashCommand:
+    """One row in the slash registry (TS ``SlashCommand``).
+
+    A command is pure data plus a ``run``: ``name`` is its canonical token
+    (without the leading slash), ``summary`` is the one-line description the
+    completion window shows, ``aliases`` are alternate tokens, and ``family``
+    groups related commands for listing. ``run`` performs the effect through
+    a :class:`SlashContext`.
+    """
+
+    # Canonical command token, without the leading slash.
+    name: str
+    # One-line description shown in the completion window.
+    summary: str
+    # Execute the command against the console (always awaited).
+    run: SlashRun
+    # Alternate tokens that resolve to this command.
+    aliases: tuple[str, ...] = ()
+    # The family this command belongs to, for grouped listing.
+    family: str | None = None
+    # Whether the command accepts a trailing argument string.
+    takes_args: bool = False
+
+
+# ---------------------------------------------------------------------------
+# SlashRegistry — the resolved command table
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SlashRegistry:
+    """The registry the dispatcher resolves a typed slash line against
+    (TS ``SlashRegistry``).
+
+    A flat, ordered list of :class:`SlashCommand` rows plus a derived index.
+    The dispatcher walks the list once (the index is the fast path for
+    exact/alias lookups), so adding a command is appending a row — never
+    editing a branch. Built by :func:`induscode.console_slash.build_registry`;
+    never assembled by hand.
+    """
+
+    # Every registered command, in listing order.
+    commands: tuple[SlashCommand, ...]
+    # Name/alias → command, for O(1) exact resolution (read-only mapping).
+    index: Mapping[str, SlashCommand]

induscode/console_slash/registry.py

@@ -0,0 +1,140 @@
+"""Slash registry assembly — fold a command list into the resolved registry.
+
+Port of TS ``src/console/slash/registry.ts``. The slash subsystem keeps
+exactly one hand-maintained list of commands (the catalog, assembled by the
+M5 console's explicit ``build_catalog``); everything a consumer needs to
+resolve, complete, or list a command is *derived* from that list here:
+
+- :func:`build_registry` indexes the list by canonical name *and* by every
+  alias, so :func:`induscode.console_slash.resolve.resolve_slash` is an O(1)
+  mapping lookup rather than a scan. It also guards the one invariant a flat
+  list cannot: two rows must not claim the same token (a duplicate name or
+  alias is a programming error, surfaced loudly at assembly time, not
+  silently shadowed).
+- :func:`match_prefix` powers the completion window: given the partial token
+  the user has typed, it returns the rows whose name or alias starts with it,
+  in registry order.
+- :func:`commands_in_family` / :func:`list_families` project the ``family``
+  field for grouped listing (the ``/help`` overlay, the completion grouping).
+
+No effects, no TUI, no conductor — the registry is a value, and these are
+pure derivations over it. The dispatcher consumes the registry; it is not
+built here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from types import MappingProxyType
+
+from .contract import SlashCommand, SlashRegistry
+
+__all__ = [
+    "build_registry",
+    "commands_in_family",
+    "find_command",
+    "list_families",
+    "match_prefix",
+    "tokens_of",
+]
+
+
+def tokens_of(command: SlashCommand) -> list[str]:
+    """Every token a command answers to: its canonical name plus any aliases.
+
+    The single place name/alias enumeration happens, so the index builder and
+    the prefix matcher agree on what counts as "a token for this command".
+
+    :param command: the command to enumerate tokens for
+    """
+    return [command.name, *command.aliases]
+
+
+def build_registry(commands: Sequence[SlashCommand]) -> SlashRegistry:
+    """Fold an ordered command list into a resolved :class:`SlashRegistry`.
+
+    Preserves the input order in :attr:`SlashRegistry.commands` (it is the
+    listing order the completion window and ``/help`` render in) and derives
+    the :attr:`SlashRegistry.index` by mapping every token — canonical and
+    alias — to its owning command. Tokens are lower-cased on the way in so
+    resolution can be case-insensitive without the resolver re-normalising.
+
+    Raises :class:`ValueError` when two rows claim the same token: a flat
+    list cannot express "these names are disjoint", so the invariant is
+    enforced here, at the one point the table is assembled, instead of
+    letting a later row silently shadow an earlier one.
+
+    :param commands: the ordered command list (the single source of truth)
+    """
+    index: dict[str, SlashCommand] = {}
+    for command in commands:
+        for token in tokens_of(command):
+            key = token.lower()
+            existing = index.get(key)
+            if existing is not None and existing is not command:
+                raise ValueError(
+                    f'slash registry: token "{key}" is claimed by both '
+                    f'"{existing.name}" and "{command.name}"'
+                )
+            index[key] = command
+    return SlashRegistry(commands=tuple(commands), index=MappingProxyType(index))
+
+
+def find_command(registry: SlashRegistry, token: str) -> SlashCommand | None:
+    """Resolve a single token (canonical or alias) to its command, or ``None``.
+
+    A thin, case-insensitive read of :attr:`SlashRegistry.index` so call
+    sites do not re-implement the lower-casing the registry index expects.
+
+    :param registry: the registry to read
+    :param token:    a canonical name or alias, with or without a leading slash
+    """
+    bare = token[1:] if token.startswith("/") else token
+    return registry.index.get(bare.lower())
+
+
+def match_prefix(registry: SlashRegistry, partial: str) -> list[SlashCommand]:
+    """The commands whose name or alias begins with a partial token, in
+    registry order — the candidate set the completion window renders.
+
+    Matching is case-insensitive and prefix-based against *every* token a
+    command answers to, but each command appears at most once even when
+    several of its tokens match. An empty partial returns the whole list (the
+    bare-``/`` case where the user has opened the completion window but typed
+    nothing yet).
+
+    :param registry: the registry to search
+    :param partial:  the partial command token (without a leading slash)
+    """
+    needle = partial.lower()
+    if len(needle) == 0:
+        return list(registry.commands)
+    return [
+        command
+        for command in registry.commands
+        if any(token.lower().startswith(needle) for token in tokens_of(command))
+    ]
+
+
+def list_families(registry: SlashRegistry) -> list[str]:
+    """The distinct family labels present in the registry, in first-seen order.
+
+    Commands without a ``family`` are omitted; the result drives the grouped
+    headings in ``/help`` and the completion window.
+
+    :param registry: the registry to scan
+    """
+    seen: list[str] = []
+    for command in registry.commands:
+        if command.family is not None and command.family not in seen:
+            seen.append(command.family)
+    return seen
+
+
+def commands_in_family(registry: SlashRegistry, family: str) -> list[SlashCommand]:
+    """The commands belonging to a family, in registry order.
+
+    :param registry: the registry to filter
+    :param family:   the family label to select
+    """
+    return [command for command in registry.commands if command.family == family]

induscode/console_slash/resolve.py

@@ -0,0 +1,194 @@
+"""Slash line resolution — parse a typed line, then match it against the registry.
+
+Port of TS ``src/console/slash/resolve.ts``. This module is the pure front
+half of the slash subsystem: it takes the raw string a user typed into the
+composer and decides three things, in order:
+
+1. **Is this a slash line at all?** A line is a slash invocation only when
+   its first non-blank character is ``/`` and what follows is a
+   command-shaped token (so a bare ``/`` or a ``/path/to/file`` literal is
+   *not* hijacked as a command). :func:`parse_slash` reports this without
+   consulting the registry.
+2. **Which command does the token resolve to?** :func:`resolve_slash` folds
+   a :class:`~induscode.console_slash.contract.SlashRegistry` in: it splits
+   the line into a name and a trailing argument string, then resolves the
+   name (and its aliases) through the registry's index. Resolution is
+   case-insensitive on the command token.
+3. **What should the dispatcher do?** The result is a discriminated
+   :data:`SlashResolution`: :class:`NotSlash` (treat as a normal prompt /
+   bash escape), :class:`Match` (run this command with these args), or
+   :class:`Miss` (it looked like a command but no row owns the token — fall
+   through to templates, plugin commands, or a literal prompt).
+
+Nothing here touches the TUI, the conductor, or I/O — the whole module is a
+pair of pure functions over a string and a registry. The effectful half
+(actually calling a command's ``run``) is the dispatcher's job.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import ClassVar, Final, Literal, TypeAlias
+
+from .contract import SlashCommand, SlashRegistry
+
+__all__ = [
+    "Match",
+    "Miss",
+    "NotSlash",
+    "SLASH_PREFIX",
+    "SlashLine",
+    "SlashResolution",
+    "looks_like_slash",
+    "parse_slash",
+    "resolve_slash",
+]
+
+
+# ---------------------------------------------------------------------------
+# The parsed shape of a slash line
+# ---------------------------------------------------------------------------
+
+
+#: The leading character that marks a line as a slash invocation.
+#:
+#: A single constant so the prefix is defined in exactly one place and the
+#: tests assert against the same literal the parser reads.
+SLASH_PREFIX: Final = "/"
+
+
+@dataclass(frozen=True, slots=True)
+class SlashLine:
+    """The lexical split of a slash line into its command token and argument
+    tail.
+
+    Produced by :func:`parse_slash` before the registry is consulted, so the
+    two concerns — "did the user type a command-shaped line" and "does a
+    command own that token" — stay separable. ``name`` is the bare token with
+    no leading slash and folded to lower case for case-insensitive matching;
+    ``args`` is everything after the first run of whitespace, with the single
+    separating space removed but interior spacing preserved.
+    """
+
+    # The command token, lower-cased, without the leading slash.
+    name: str
+    # The trailing argument string (may be empty), interior spacing preserved.
+    args: str
+
+
+#: The shape a command token must have: it starts with an ASCII letter and
+#: then carries only letters, digits, hyphens, or a single namespacing colon
+#: (e.g. ``model``, ``scoped-models``, ``skill:lint``). A second slash
+#: anywhere in the token disqualifies the line, which is what tells a command
+#: apart from a filesystem path. The token runs to the first whitespace or
+#: end-of-line. (Pattern kept verbatim from the TS source.)
+_COMMAND_TOKEN: Final = re.compile(r"^[a-zA-Z][a-zA-Z0-9:-]*(?:\s|$)")
+
+#: First-whitespace finder for the token/args split (TS ``body.search(/\s/)``).
+_WHITESPACE: Final = re.compile(r"\s")
+
+
+def looks_like_slash(input: str) -> bool:
+    """Whether a typed line is shaped like a slash command at all.
+
+    A line qualifies only when, after trimming leading blanks, it begins with
+    the :data:`SLASH_PREFIX` *and* what follows up to the first whitespace is
+    a clean command token. This deliberately rejects a lone ``/``, a
+    ``//comment``, and a ``/usr/local/bin`` style path (whose embedded slash
+    breaks the token shape) so those reach the prompt untouched.
+
+    :param input: the raw composer line
+    """
+    trimmed = input.lstrip()
+    if not trimmed.startswith(SLASH_PREFIX):
+        return False
+    return _COMMAND_TOKEN.match(trimmed[len(SLASH_PREFIX) :]) is not None
+
+
+def parse_slash(input: str) -> SlashLine | None:
+    """Split a slash line into its :class:`SlashLine` token/argument pair, or
+    ``None`` when the line is not shaped like a command.
+
+    The token runs from just after the slash up to the first whitespace (or
+    end-of-line); the argument tail is whatever follows that whitespace,
+    trimmed only at its outer edges. The token is lower-cased so resolution
+    can be case-insensitive without the caller pre-normalising.
+
+    :param input: the raw composer line
+    """
+    if not looks_like_slash(input):
+        return None
+    body = input.lstrip()[len(SLASH_PREFIX) :]
+    gap = _WHITESPACE.search(body)
+    if gap is None:
+        return SlashLine(name=body.lower(), args="")
+    return SlashLine(
+        name=body[: gap.start()].lower(),
+        args=body[gap.start() + 1 :].strip(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Resolving a parsed line against the registry
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class NotSlash:
+    """The line is not a command invocation; the dispatcher should hand it on
+    as a normal prompt (or a ``!``/``!!`` bash escape)."""
+
+    kind: ClassVar[Literal["not-slash"]] = "not-slash"
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    """The token resolved to ``command``; run it with ``args`` (the raw
+    trailing string) via a
+    :class:`~induscode.console_slash.contract.SlashContext`."""
+
+    kind: ClassVar[Literal["match"]] = "match"
+    command: SlashCommand
+    args: str
+
+
+@dataclass(frozen=True, slots=True)
+class Miss:
+    """The line *was* command-shaped but no row owns the token; the dispatcher
+    falls through to templates / plugin commands / a literal prompt. The
+    offending ``name`` is reported so a caller can surface "unknown command"."""
+
+    kind: ClassVar[Literal["miss"]] = "miss"
+    name: str
+
+
+#: The outcome of resolving a typed line against a registry
+#: (TS ``SlashResolution``).
+SlashResolution: TypeAlias = NotSlash | Match | Miss
+
+
+def resolve_slash(input: str, registry: SlashRegistry) -> SlashResolution:
+    """Resolve a raw composer line against the registry to a
+    :data:`SlashResolution`.
+
+    Parses the line (:func:`parse_slash`); a non-command line resolves to
+    :class:`NotSlash`. A command-shaped line's token is looked up in the
+    registry index (which already carries both canonical names and aliases),
+    yielding :class:`Match` with the owning command and the raw argument
+    string, or :class:`Miss` when no row claims the token.
+
+    This is the single entry point a dispatcher calls; it performs no effects.
+
+    :param input:    the raw composer line
+    :param registry: the registry to resolve against
+    """
+    line = parse_slash(input)
+    if line is None:
+        return NotSlash()
+
+    command = registry.index.get(line.name)
+    if command is None:
+        return Miss(name=line.name)
+
+    return Match(command=command, args=line.args)

induscode/console_slash/shared.py

@@ -0,0 +1,172 @@
+"""Shared slash-command helpers — the small, pure toolkit every command group
+is written against.
+
+Port of TS ``src/console/slash/commands/shared.ts``. The console's slash
+catalog is split into topic groups (transcript control, the workbench
+pickers, the integration bridges — they land with M5). Each group is its own
+module exporting a ``list[SlashCommand]``; this file holds the handful of
+helpers they all lean on so the groups stay free of duplicated wiring and
+the family sub-command dispatch lives in exactly one place.
+
+Two stances every group keeps:
+
+1. **Handlers are thin.** A ``run(ctx)`` never reaches into the TUI, the
+   filesystem, or a provider SDK; every effect goes through the injected
+   :class:`~induscode.console_slash.contract.SlashContext`. The handler
+   decides *which* effect to raise.
+2. **Families are tables, not ladders.** A command with sub-verbs (e.g.
+   ``/memory status|on|off``) is built from a :class:`SubCommand` table via
+   :func:`family_runner`, never a hand-written ``if``-chain.
+
+Per the locked calling convention, every generated ``run`` — including a
+:class:`SubCommand`'s — is ``async`` and awaited by the dispatcher.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Final, NamedTuple
+
+from indusagi.react_ink import StatusMessage
+
+from .contract import Handled, SlashContext, SlashOutcome, SlashRun
+
+__all__ = [
+    "FAMILY",
+    "FamilyLabels",
+    "HANDLED",
+    "SubCommand",
+    "VerbSplit",
+    "family_runner",
+    "info",
+    "split_verb",
+    "warn",
+]
+
+
+# ---------------------------------------------------------------------------
+# Family labels
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class FamilyLabels:
+    """The family labels the catalog groups commands under for ``/help`` and
+    completion. Named constants (not bare strings scattered across rows) so
+    the grouping a command declares and the grouping the help view renders
+    cannot drift apart."""
+
+    composio: str = "composio"
+    memory: str = "memory"
+    scoped_models: str = "models-for"
+    # parity: `theme` is declared but the TS catalog ships no /theme command
+    # (the scheme picker is reached via the settings overlay). Kept verbatim.
+    theme: str = "theme"
+
+
+#: The one shared label record (TS ``FAMILY``).
+FAMILY: Final = FamilyLabels()
+
+
+# ---------------------------------------------------------------------------
+# Outcome + status helpers
+# ---------------------------------------------------------------------------
+
+
+#: The settled "command ran, nothing more to do" outcome.
+HANDLED: Final[SlashOutcome] = Handled()
+
+
+def info(text: str) -> StatusMessage:
+    """Mint an info-tone status toast."""
+    return StatusMessage(kind="info", text=text)
+
+
+def warn(text: str) -> StatusMessage:
+    """Mint a warning-tone status toast (used for usage hints on bad args)."""
+    return StatusMessage(kind="warning", text=text)
+
+
+# ---------------------------------------------------------------------------
+# Family sub-command dispatch (table, not ladder)
+# ---------------------------------------------------------------------------
+
+
+class VerbSplit(NamedTuple):
+    """The (verb, rest) pair :func:`split_verb` returns; unpacks in place."""
+
+    verb: str
+    rest: str
+
+
+#: First-whitespace finder for the verb/rest split (TS ``trimmed.search(/\s/)``).
+_WHITESPACE: Final = re.compile(r"\s")
+
+
+def split_verb(args: str) -> VerbSplit:
+    """Split a family command's argument string into a leading sub-command
+    verb and the remainder, both trimmed. An empty argument string yields an
+    empty verb so a family command can show its own usage when invoked bare.
+
+    :param args: the raw trailing argument string from ``SlashContext.args``
+    """
+    trimmed = args.strip()
+    if len(trimmed) == 0:
+        return VerbSplit(verb="", rest="")
+    gap = _WHITESPACE.search(trimmed)
+    if gap is None:
+        return VerbSplit(verb=trimmed.lower(), rest="")
+    return VerbSplit(
+        verb=trimmed[: gap.start()].lower(),
+        rest=trimmed[gap.start() + 1 :].strip(),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class SubCommand:
+    """One sub-command of a command family — its verb, a one-line description
+    for the usage list, and the thin action it runs through the
+    :class:`~induscode.console_slash.contract.SlashContext`."""
+
+    # The sub-command verb, lower-cased (e.g. `add`, `list`, `clear`).
+    verb: str
+    # One-line description rendered in the family's usage toast.
+    describe: str
+    # Run the sub-command; `rest` is the argument tail after the verb.
+    run: Callable[[SlashContext, str], Awaitable[SlashOutcome]]
+
+
+def family_runner(family: str, subs: Sequence[SubCommand]) -> SlashRun:
+    """Build a family command's ``run`` from a sub-command table.
+
+    The family handler is a single thin coroutine function whose branch
+    structure is *generated* from the table: it splits the verb, looks it up,
+    and awaits the matching action — falling back to a usage toast (assembled
+    from the table's descriptions) when the verb is missing or unknown.
+
+    :param family: the family label, used in the usage header
+    :param subs:   the sub-command table for this family
+    """
+    table = {sub.verb: sub for sub in subs}
+
+    def usage() -> StatusMessage:
+        return warn(
+            f"/{family} expects: "
+            + ", ".join(f"{sub.verb} ({sub.describe})" for sub in subs)
+        )
+
+    async def run(ctx: SlashContext) -> SlashOutcome:
+        verb, rest = split_verb(ctx.args)
+        if len(verb) == 0:
+            ctx.set_status(usage())
+            return HANDLED
+        sub = table.get(verb)
+        if sub is None:
+            ctx.set_status(warn(f'/{family}: unrecognised action "{verb}".'))
+            ctx.set_status(usage())
+            return HANDLED
+        return await sub.run(ctx, rest)
+
+    return run