ad-sdl/madsci/madsci-cli

madsci (AliasedGroup)
  ├── Global options: --lab-url, -v, -q, --no-color, --json, --version
  ├── Context: MadsciContext (lazy), Console, verbosity flags
  └── Commands (lazy-loaded via _LAZY_COMMANDS):
      ├── version, doctor (doc), status (s), logs (l)
      ├── tui (ui), registry, migrate, new (n)
      ├── start, stop, validate (val)
      ├── run, completion, backup, add
      ├── commands (cmd), config (cfg)
      └── [aliases resolve via AliasedGroup]

# In cli/__init__.py
_LAZY_COMMANDS = {
    "version": ("madsci.client.cli.commands.version", "version"),
    "doctor": ("madsci.client.cli.commands.doctor", "doctor"),
    "status": ("madsci.client.cli.commands.status", "status"),
    "logs": ("madsci.client.cli.commands.logs", "logs"),
    "tui": ("madsci.client.cli.commands.tui", "tui"),
    "registry": ("madsci.client.cli.commands.registry", "registry"),
    "migrate": ("madsci.client.cli.commands.migrate", "migrate"),
    "new": ("madsci.client.cli.commands.new", "new"),
    "start": ("madsci.client.cli.commands.start", "start"),
    "stop": ("madsci.client.cli.commands.stop", "stop"),
    "validate": ("madsci.client.cli.commands.validate", "validate"),
    "run": ("madsci.client.cli.commands.run", "run"),
    "completion": ("madsci.client.cli.commands.completion", "completion"),
    "backup": ("madsci.client.cli.commands.backup", "backup"),
    "commands": ("madsci.client.cli.commands.commands", "commands"),
    "config": ("madsci.client.cli.commands.config", "config"),
    "workflow": ("madsci.client.cli.commands.workflow", "workflow"),
    "resource": ("madsci.client.cli.commands.resource", "resource"),
    "location": ("madsci.client.cli.commands.location", "location"),
    "node": ("madsci.client.cli.commands.node", "node"),
    "experiment": ("madsci.client.cli.commands.experiment", "experiment"),
    "campaign": ("madsci.client.cli.commands.campaign", "campaign"),
    "data": ("madsci.client.cli.commands.data", "data"),
    "events": ("madsci.client.cli.commands.events", "events"),
    "add": ("madsci.client.cli.commands.add", "add"),
}

class AliasedGroup(click.Group):
    _aliases: ClassVar[dict[str, str]] = {
        "n": "new",
        "s": "status",
        "l": "logs",
        "doc": "doctor",
        "val": "validate",
        "ui": "tui",
        "cmd": "commands",
        "cfg": "config",
        "wf": "workflow",
        "res": "resource",
        "loc": "location",
        "nd": "node",
        "exp": "experiment",
        "camp": "campaign",
        "dt": "data",
        "ev": "events",
    }

# src/madsci_client/madsci/client/cli/commands/my_command.py
import click
@click.command()
@click.pass_context
def my_command(ctx: click.Context):
    """One-line description shown in --help."""
    # Lazy imports for heavy dependencies
    from madsci.client.cli.utils.output import get_console, success
    console = get_console(ctx)
    success(console, "Command executed successfully")

# In cli/__init__.py, add to _LAZY_COMMANDS dict:
_LAZY_COMMANDS = {
    ...
    "my_command": ("madsci.client.cli.commands.my_command", "my_command"),
}

# In AliasedGroup._aliases:
_aliases = {
    ...
    "mc": "my_command",
}

from madsci.client.cli.utils.output import (
    get_console,      # Get Rich Console from click context
    output_result,    # Handles json/yaml/text output
    success,          # Green checkmark message
    error,            # Red X message (with optional details)
    warning,          # Yellow warning message
    info,             # Blue info message
    print_panel,      # Rich Panel with border
    format_url,       # Rich link format
)
# Usage pattern:
console = get_console(ctx)
success(console, "Operation completed")
error(console, "Failed to connect", details="Connection refused on port 8001")
# JSON-aware output:
if ctx.obj.get("json"):
    output_result(console, data, format="json")
else:
    output_result(console, data, format="text", title="Results")

madsci start              # docker compose up (foreground)
madsci start -d           # detached + health polling
madsci start --build      # rebuild images first
madsci start --services event resource  # specific services
madsci stop               # docker compose down
madsci stop --volumes     # remove volumes (data loss!)

madsci start --mode=local     # All 7 managers in-process, in-memory backends
madsci start --mode=local -d  # Background with PID tracking

madsci start manager event -d     # Start Event Manager in background
madsci start node ./my_node.py -d # Start node in background
madsci stop manager event         # Stop background Event Manager
madsci stop node my_node          # Stop background node

from click.testing import CliRunner
from madsci.client.cli import madsci
def test_version_command():
    runner = CliRunner()
    result = runner.invoke(madsci, ["version"])
    assert result.exit_code == 0
    assert "madsci" in result.output
def test_version_json():
    runner = CliRunner()
    result = runner.invoke(madsci, ["version", "--json"])
    assert result.exit_code == 0
    import json
    data = json.loads(result.output)
    assert "packages" in data
def test_command_alias():
    runner = CliRunner()
    result = runner.invoke(madsci, ["s"])  # alias for "status"
    # Will fail to connect but should parse correctly
    assert result.exit_code in (0, 1)

@pytest.mark.parametrize("cmd", ["version", "doctor", "status", ...])
def test_command_help(cmd):
    runner = CliRunner()
    result = runner.invoke(madsci, [cmd, "--help"])
    assert result.exit_code == 0