fleetmesh-node 0.2.0__py3-none-any.whl

node/commands/adapter.py

@@ -0,0 +1,210 @@
+"""CLI Adapter: bridge declarative Compartment Commands to the operator CLI.
+
+Converts declarative `Command` and `Parameter` definitions into argparse
+subcommands and arguments, and provides table-driven action dispatching.
+"""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+from typing import Any, Callable, Mapping, MutableMapping, Optional, Sequence
+
+from ..compartment import Command, CommandError
+from ..config.parameter import Parameter
+from .base import _ask, emit, fail
+
+
+def add_parameter_argument(
+    parser: argparse.ArgumentParser,
+    param: Parameter[Any],
+    help_prefix: str = '',
+    require_flag: bool = False,
+) -> None:
+    """Register a Parameter on an ArgumentParser.
+
+    Uses `cli_name`, `short`, and `positional` if specified, otherwise derives
+    long option as `--<param.key_with_dashes>`. Skips if `param.cli` is False
+    or if the flag is already registered on the parser.
+    """
+    if not getattr(param, 'cli', True):
+        return
+
+    # Check already registered option strings
+    existing_opts = {opt for action in parser._actions for opt in action.option_strings}
+    existing_dests = {action.dest for action in parser._actions}
+
+    doc = f"{help_prefix}{param.description}" if help_prefix else param.description
+
+    if getattr(param, 'positional', False):
+        dest = param.cli_name or param.key
+        if dest in existing_dests:
+            return
+        kwargs: MutableMapping[str, Any] = {'help': doc}
+        if param.type in (int, float, str):
+            kwargs['type'] = param.type
+        if param.choices:
+            kwargs['choices'] = param.choices
+        if getattr(param, 'nargs', ''):
+            kwargs['nargs'] = param.nargs
+        elif not getattr(param, 'required', False):
+            kwargs['nargs'] = '?'
+        parser.add_argument(dest, **kwargs)
+        return
+
+    # Flag option
+    long_flag = param.cli_name if (param.cli_name and param.cli_name.startswith('--')) else (
+        '--' + (param.cli_name or param.key.replace('_', '-')).lstrip('-')
+    )
+    flags: list[str] = []
+    if getattr(param, 'short', ''):
+        short_flag = '-' + param.short.lstrip('-')
+        if short_flag not in existing_opts:
+            flags.append(short_flag)
+    if long_flag in existing_opts:
+        return
+    flags.append(long_flag)
+
+    dest = param.key
+    kwargs = {'help': doc, 'dest': dest}
+
+    if param.type is bool:
+        kwargs['action'] = 'store_true'
+    elif getattr(param, 'nargs', ''):
+        kwargs['nargs'] = param.nargs
+    elif param.type in (list, tuple):
+        kwargs['action'] = 'append'
+    else:
+        if param.type in (int, float, str):
+            kwargs['type'] = param.type
+        if param.choices:
+            kwargs['choices'] = param.choices
+        # Only set default if it's not a factory and not falsy empty
+        val = param.value() if hasattr(param, 'value') else None
+        if val is not None and not callable(param.default) and val not in ('', 0, False, [], (), {}):
+            kwargs['default'] = val
+
+    if require_flag and getattr(param, 'required', False) and not getattr(param, 'positional', False):
+        kwargs['required'] = True
+
+    parser.add_argument(*flags, **kwargs)
+
+
+@dataclasses.dataclass
+class ActionDef:
+    """Definition of one action in a multi-action command group."""
+    name: str
+    command: Optional[Command] = None
+    human: Optional[Callable[..., None]] = None
+    timeout: float = 10.0
+    handler: Optional[Callable[[argparse.Namespace], int]] = None
+    arg_map: dict[str, str] = dataclasses.field(default_factory=dict)
+    parameters: tuple[Parameter[Any], ...] = ()
+
+
+class CommandDispatcher:
+    """Table-driven multi-action dispatcher and argument builder for CLI subcommands."""
+
+    def __init__(self, subsystem: str, default_action: str = 'status', action_dest: str = 'action') -> None:
+        self.subsystem = subsystem
+        self.default_action = default_action
+        self.action_dest = action_dest
+        self.actions: dict[str, ActionDef] = {}
+
+    def add_command(
+        self,
+        action_name: str,
+        command: Command,
+        human: Optional[Callable[..., None]] = None,
+        timeout: float = 10.0,
+        arg_map: Optional[Mapping[str, str]] = None,
+        extra_parameters: Sequence[Parameter[Any]] = (),
+    ) -> ActionDef:
+        """Register an action backed directly by a compartment Command."""
+        all_params = tuple(command.parameters) + tuple(extra_parameters)
+        act = ActionDef(
+            name=action_name,
+            command=command,
+            human=human,
+            timeout=timeout,
+            arg_map=dict(arg_map or {}),
+            parameters=all_params,
+        )
+        self.actions[action_name] = act
+        return act
+
+    def add_custom(
+        self,
+        action_name: str,
+        handler: Callable[[argparse.Namespace], int],
+        parameters: Sequence[Parameter[Any]] = (),
+    ) -> ActionDef:
+        """Register an action with custom client-side handling logic."""
+        act = ActionDef(
+            name=action_name,
+            handler=handler,
+            parameters=tuple(parameters),
+        )
+        self.actions[action_name] = act
+        return act
+
+    def register_arguments(
+        self,
+        parser: argparse.ArgumentParser,
+        action_choices: Sequence[str] | None = None,
+        action_dest: str | None = None,
+    ) -> None:
+        """Register the action positional argument and all action parameters."""
+        choices = tuple(action_choices) if action_choices is not None else tuple(self.actions.keys())
+        dest = action_dest if action_dest is not None else self.action_dest
+        parser.add_argument(
+            dest,
+            choices=choices,
+            default=self.default_action,
+            nargs='?',
+        )
+        for act in self.actions.values():
+            for p in act.parameters:
+                add_parameter_argument(parser, p)
+
+    def dispatch(self, a: argparse.Namespace) -> int:
+        """Execute the requested action from parsed namespace."""
+        action_name = getattr(a, self.action_dest, None) or getattr(a, 'action', self.default_action) or self.default_action
+        act = self.actions.get(action_name)
+        if not act:
+            fail(f'unknown action {action_name!r}')
+
+        if act.handler is not None:
+            return act.handler(a)
+
+        if act.command is None:
+            fail(f'action {action_name} has no command or handler')
+
+        # Gather arguments declared on the Command
+        raw_args = {}
+        for p in act.command.parameters:
+            dest = act.arg_map.get(p.key, p.key)
+            val = getattr(a, dest, None)
+            if p.required and (val is None or val == ''):
+                flag = p.cli_name or ('--' + p.key.replace('_', '-'))
+                placeholder = ' <name>' if p.key == 'domain' else f' <{p.key}>'
+                fail(f'{action_name} requires {flag}{placeholder}')
+            if val is not None:
+                raw_args[p.key] = val
+
+        try:
+            valid_args = act.command.validate_args(raw_args)
+        except CommandError as e:
+            fail(f'{action_name}: {e}')
+
+        res = _ask(a.dir, f'{self.subsystem}.{act.command.key}', timeout=act.timeout, **valid_args)
+        if act.human is not None:
+            human_fn = act.human
+            import inspect
+            try:
+                sig = inspect.signature(human_fn)
+                human_cb: Any = (lambda r: human_fn(r, a)) if len(sig.parameters) >= 2 else human_fn
+            except (ValueError, TypeError):
+                human_cb = human_fn
+        else:
+            human_cb = None
+        return emit(a, res, human_cb)

node/commands/base.py

@@ -0,0 +1,278 @@
+"""Common helpers and base structures for meshnode CLI command providers."""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import sys
+import time
+from typing import Any, Callable, Mapping, NoReturn, Optional, Sequence
+from node.interfaces import HealthStatusDict, NodeStatusDict
+from node import app as app_mod, storage
+from node.app import socket as control
+from fleetmesh_core.wire import validate
+from fleetmesh_core.identity.did import node_of_did
+from node.storage import grants as grants_mod
+from fleetmesh_core.crypto.bech32 import bech32_decode, bech32_encode, bech32_polymod  # noqa: F401  (command modules import them from here)
+
+TIERS: tuple[str, ...] = ('probation', 'member', 'trusted', 'anchor')
+
+# Exit codes. Every command returns an int; meshnode.main exits with it.
+OK = 0
+# Something the operator asked for could not be done: a missing argument, a
+# peer this node does not know, a daemon that is not running, a reply the
+# daemon refused. Two rather than one so that it reads as "the request was
+# wrong or could not be met" in the same register as argparse's own usage
+# errors; one is reserved for commands whose job is to answer a yes/no
+# question (`check`, `enclave verify`, `fips probe`) and said no.
+FAILED = 2
+
+
+def fail(msg: str, code: int = FAILED) -> NoReturn:
+    """Say why on stderr and stop with `code`. The one way a command gives up."""
+    print(msg, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def emit(a: argparse.Namespace, payload: Any, human: Callable[[Any], None] | None = None,
+         indent: int | None = 2) -> int:
+    """Print `payload` as JSON under --json, otherwise hand it to `human`.
+
+    The JSON side is the contract scripts read, so it is produced here and
+    nowhere else: `json.dumps(payload, indent=indent)` on one line of stdout
+    per call. A command whose human rendering is long may pass no `human`,
+    test `a.json` itself and `return emit(a, payload)` from the JSON branch.
+    """
+    if getattr(a, 'json', False):
+        print(json.dumps(payload, indent=indent))
+    elif human is not None:
+        human(payload)
+    return OK
+
+
+def load_json_arg(value: str, what: str = 'argument',
+                  on_error: Callable[[str], Any] | None = None) -> Any:
+    """A JSON argument given inline or as `@path` to a file holding it.
+
+    A value that is not JSON fails the command naming `what`, unless
+    `on_error` is given, in which case it decides what the raw text means.
+    """
+    if value.startswith('@'):
+        with open(value[1:], encoding='utf-8') as _fh:
+            raw = _fh.read()
+    else:
+        raw = value
+    try:
+        return json.loads(raw)
+    except ValueError as e:
+        if on_error is not None:
+            return on_error(raw)
+        fail('%s is not JSON: %s' % (what, e))
+
+
+def load_doc(path: str) -> Any:
+    with open(path, encoding='utf-8') as _fh:
+        text = _fh.read()
+    if path.endswith(('.yaml', '.yml')):
+        try:
+            import yaml
+        except ImportError:
+            fail('reading %s needs pyyaml; give the manifest as JSON instead' % path)
+        return yaml.safe_load(text)
+    return json.loads(text)
+
+
+def render_table(headers: Sequence[str], rows: Sequence[Sequence[Any]]) -> None:
+    str_rows = [[str(c) for c in r] for r in rows]
+    widths = [max(len(h), *(len(r[i]) for r in str_rows)) if str_rows else len(h) for i, h in enumerate(headers)]
+    line = '  '.join(h.ljust(w) for h, w in zip(headers, widths))
+    print(line.rstrip())
+    for r in str_rows:
+        print('  '.join(c.ljust(w) for c, w in zip(r, widths)).rstrip())
+
+
+def format_when(epoch: int, window: int = 3600) -> str:
+    return time.strftime('%Y-%m-%d %H:%M', time.gmtime(epoch * window))
+
+
+def short_pk(pk: str | None) -> str:
+    return (pk or '')[:16]
+
+
+def get_grants_store(directory: str) -> grants_mod.GrantStore:
+    return grants_mod.GrantStore(os.path.join(directory, 'grants.sqlite'))
+
+
+def resolve_peer_arg(directory: str, arg: str) -> str:
+    """A peer, from a pubkey, a DID, an npub, or an unambiguous prefix of a known one."""
+    arg = arg.strip()
+    if arg.lower().startswith('did:'):
+        try:
+            return node_of_did(arg.lower())
+        except ValueError as e:
+            fail(str(e))
+    if arg.lower().startswith('npub1'):
+        raw = bech32_decode('npub', arg.lower())
+        if raw is not None and len(raw) == 32:
+            return raw.hex()
+        fail('%r is not a valid npub' % arg)
+    if validate.hex64(arg.lower()):
+        return arg.lower()
+    known = set()
+    try:
+        known |= {g['peer'] for g in get_grants_store(directory).list()}
+    except storage.store_errors():
+        pass
+    try:
+        cfg = app_mod.load_config(directory)
+        known |= {p['pubkey'] for p in cfg.get('peers', []) if isinstance(p, dict) and 'pubkey' in p}
+        known |= {pk for pk in (cfg.get('trust') or {}) if validate.hex64(pk)}
+    except (OSError, ValueError):
+        pass
+    hits = sorted(pk for pk in known if pk.startswith(arg.lower()))
+    if len(hits) == 1:
+        return hits[0]
+    if not hits:
+        fail('%r is not a pubkey, a did:nostr, an npub, or a prefix of a peer this node knows' % arg)
+    fail('%r matches %d peers: %s' % (arg, len(hits), ', '.join(h[:16] for h in hits)))
+
+
+def resolve_peer_or_raw(a: argparse.Namespace, arg: str) -> str:
+    """resolve_peer_arg when the command has a node directory to ask, else the
+    argument as given. For transport commands, which also run without a node."""
+    directory = getattr(a, 'dir', None)
+    if directory and os.path.exists(directory):
+        return resolve_peer_arg(directory, arg)
+    return arg
+
+
+_DAEMON_CALLER: Optional[Callable[..., Any]] = None
+
+
+def set_daemon_caller(caller: Optional[Callable[..., Any]]) -> None:
+    """Set custom daemon caller implementation for testing without monkeypatching."""
+    global _DAEMON_CALLER
+    _DAEMON_CALLER = caller
+
+
+def reset_daemon_caller() -> None:
+    """Clear custom daemon caller implementation."""
+    global _DAEMON_CALLER
+    _DAEMON_CALLER = None
+
+
+@contextlib.contextmanager
+def override_daemon(caller: Callable[..., Any]) -> Any:
+    """Context manager to cleanly override daemon calls for tests."""
+    global _DAEMON_CALLER
+    prev = _DAEMON_CALLER
+    _DAEMON_CALLER = caller
+    try:
+        yield
+    finally:
+        _DAEMON_CALLER = prev
+
+
+def ask_daemon(directory: str, cmd: str, **args: Any) -> Any:
+    """One call over the control socket, or exit with the daemon's complaint.
+
+    Can be cleanly intercepted in tests via `override_daemon(fake)` or `set_daemon_caller(fake)`.
+    """
+    if _DAEMON_CALLER is not None:
+        return _DAEMON_CALLER(directory, cmd, **args)
+    try:
+        return control.call(directory, cmd, **args)
+    except control.ControlError as e:
+        fail('%s' % e)
+
+
+def _ask(directory: str, cmd: str, **args: Any) -> Any:
+    return ask_daemon(directory, cmd, **args)
+
+
+def try_ask(directory: str, cmd: str, **args: Any) -> Any:
+    """One call over the control socket, or None when the node is not there
+    or declined. For best-effort fan-out, where one silent node must not stop
+    the command."""
+    if not control.running(directory):
+        return None
+    try:
+        return control.call(directory, cmd, **args)
+    except control.ControlError:
+        return None
+
+
+def _live(a: argparse.Namespace, cmd: str, args: Mapping[str, Any] | None = None, timeout: float = 10) -> Any:
+    """Ask the running node, or fall back to what it last wrote."""
+    if control.running(a.dir):
+        try:
+            return control.call(a.dir, cmd, timeout=timeout, **(args or {}))
+        except control.ControlError:
+            pass
+    return None
+
+
+def read_status_file(directory: str) -> NodeStatusDict:
+    path = os.path.join(directory, 'status.json')
+    if not os.path.exists(path):
+        fail('no status.json in %s; is the node running?' % directory)
+    with open(path, encoding='utf-8') as _fh:
+        return json.load(_fh)
+
+
+def status_health(directory: str) -> HealthStatusDict:
+    """The health block of the last status.json, or {} when it has none."""
+    return read_status_file(directory).get('health') or {}
+
+
+def extract_trouble(health: HealthStatusDict | Mapping[str, Any] | None) -> list[str]:
+    h = health or {}
+    out = list(h.get('subsystem_trouble') or [])
+    if h.get('config_error'):
+        out.append('config.json rejected, last good one in force: %s' % h['config_error'])
+    for k in ('handler_failures', 'tick_failures'):
+        if h.get(k):
+            out.append('%s: %d%s' % (k.replace('_', ' '), h[k],
+                                     (' (last: %s)' % h['last_tick_error']) if k == 'tick_failures' and h.get('last_tick_error') else ''))
+    if h.get('rejected'):
+        out.append('messages rejected at the door: %d' % sum(h['rejected'].values()))
+    if h.get('subsystem_trouble') is not None:
+        return out
+    down = [u for u, r in (h.get('relays') or {}).items() if not r.get('connected')]
+    if down:
+        out.append('relay subscription down: %s' % ', '.join(down))
+    if h.get('sessions_refused'):
+        out.append('sync sessions refused: %d' % h['sessions_refused'])
+    if h.get('receipts_refused'):
+        out.append('receipts refused over a grant disagreement: %d - every window this peering '
+                   'closes will be active silence until it is resolved' % len(h['receipts_refused']))
+    return out
+
+
+# The short names the command modules were written against. They are defined
+# once, here; nothing else re-exports them (meshnode.py used to, and a test
+# reaching through that copy is what kept a sys.modules hack alive in _ask).
+_load_doc = load_doc
+_bech32 = bech32_encode
+_bech32_decode = bech32_decode
+_bech32_polymod = bech32_polymod
+_table = render_table
+_when = format_when
+_short = short_pk
+_grants = get_grants_store
+_peer = resolve_peer_arg
+_status_file = read_status_file
+_trouble = extract_trouble
+
+
+def add_command(sub: argparse._SubParsersAction, name: str, fn: Any, help: str,
+                peer: bool = False, js: bool = False) -> argparse.ArgumentParser:
+    p = sub.add_parser(name, help=help)
+    p.add_argument('dir')
+    if peer:
+        p.add_argument('peer', help='pubkey, did:nostr, or a prefix of a peer this node knows')
+    if js:
+        p.add_argument('--json', action='store_true', help='print the structure, for scripts')
+    p.set_defaults(fn=fn)
+    return p

node/commands/cluster_cmds.py

@@ -0,0 +1,183 @@
+"""The `cluster` subcommand: a local multi-node testnet on one machine.
+
+Owns the command body and its place in the operator's parser, like every other
+module under node/commands. The body used to sit at the bottom of
+node/testnet/cluster.py; the cluster engine now knows nothing about argparse or how
+its status is printed.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Any, TypedDict
+
+from node.config.parameter import Parameter
+from node.testnet import LocalCluster
+from .adapter import CommandDispatcher
+from .base import add_command, emit, fail, try_ask
+
+
+class ClusterFipsStatus(TypedDict, total=False):
+    active: bool
+    listeners: int
+
+
+class ClusterNodeSummary(TypedDict, total=False):
+    index: int
+    name: str
+    pubkey: str
+    peers: list[Any]
+    event_count: int
+    face: str
+
+
+class ClusterMeta(TypedDict, total=False):
+    node_count: int
+    topology: str
+    cluster_dir: str
+    running: bool
+    enable_fips: bool
+    relays: list[str]
+
+
+class ClusterStatusSummary(TypedDict, total=False):
+    node_count: int
+    topology: str
+    cluster_dir: str
+    running: bool
+    active_peering_edges: int
+    relays: list[str]
+    fips: ClusterFipsStatus
+    nodes: list[ClusterNodeSummary]
+
+
+PARAM_NODES = Parameter(
+    key='nodes', name='nodes', description='number of nodes in the cluster (default: 3)',
+    type=int, default=3,
+)
+PARAM_TOPOLOGY = Parameter(
+    key='topology', name='topology', description='peering topology',
+    type=str, default='mesh', choices=('mesh', 'star', 'ring', 'line'),
+)
+PARAM_RELAYS = Parameter(
+    key='relays', name='relays', description='relay URLs for cluster',
+    type=list, default=None, nargs='*',
+)
+PARAM_SHARD = Parameter(
+    key='shard', name='shard', description='shard name for sync',
+    type=str, default='bristol',
+)
+PARAM_FIPS = Parameter(
+    key='fips', name='fips', description='enable FIPS native datagram transport in cluster',
+    type=bool, default=False,
+)
+
+
+def _meta(cluster_dir: str) -> ClusterMeta:
+    """cluster.json, or exit when the directory holds none."""
+    meta_path = os.path.join(cluster_dir, 'cluster.json')
+    if not os.path.exists(meta_path):
+        fail(f"No cluster.json in {cluster_dir}.")
+    with open(meta_path, encoding='utf-8') as _fh:
+        return json.load(_fh)
+
+
+def _render_cluster_summary(status: ClusterStatusSummary) -> None:
+    print("\n=======================================================")
+    print(f" MeshNode Cluster: {status['node_count']} nodes | Topology: {status['topology'].upper()}")
+    print(f" Directory:        {status['cluster_dir']}")
+    print(f" Status:           {'RUNNING' if status['running'] else 'STOPPED'}")
+    print(f" Active Peerings:  {status['active_peering_edges']}")
+    if status.get('relays'):
+        print(f" Shared Relays:    {', '.join(status['relays'])}")
+    if status.get('fips'):
+        print(f" FIPS Transport:   {'ACTIVE' if status['fips'].get('active') else 'INACTIVE'} (listeners: {status['fips'].get('listeners', 0)})")
+    print("-------------------------------------------------------")
+    print(f" {'#':<3} {'Name':<10} {'Class':<8} {'Pubkey':<18} {'Peers':<6} {'Events':<7} {'Face'}")
+    print(" --- ---------- -------- ------------------ ------ ------- -------------------------")
+    for n in status.get('nodes', []):
+        pk_short = (n.get('pubkey') or '')[:16] + '…'
+        peers_cnt = len(n.get('peers', []))
+        events_cnt = n.get('event_count', 0)
+        face = n.get('face') or '-'
+        print(f" {n['index']:<3} {n['name']:<10} {n.get('class', '-'):<8} {pk_short:<18} {peers_cnt:<6} {events_cnt:<7} {face}")
+    print("=======================================================\n")
+
+
+def _handle_start(args: argparse.Namespace) -> int:
+    cluster_dir = getattr(args, 'dir', None) or os.path.abspath('cluster-testnet')
+    count = int(getattr(args, 'nodes', 3))
+    topo = getattr(args, 'topology', 'mesh')
+    relays = getattr(args, 'relays', None) or []
+    enable_fips = bool(getattr(args, 'fips', False))
+    cl = LocalCluster(base_dir=cluster_dir, node_count=count, topology=topo, relay_urls=relays, enable_fips=enable_fips)
+    print(f"Starting {count}-node cluster ({topo}) in {cluster_dir}...")
+    cl.start()
+    print(f"Cluster active. Relay: {cl.relay_urls[0] if cl.relay_urls else 'nostr'} | FIPS: {'enabled' if enable_fips else 'disabled'}")
+    return emit(args, cl.get_status(), _render_cluster_summary)
+
+
+def _handle_status(args: argparse.Namespace) -> int:
+    cluster_dir = getattr(args, 'dir', None) or os.path.abspath('cluster-testnet')
+    if not os.path.exists(cluster_dir):
+        fail(f"Cluster directory {cluster_dir} does not exist.")
+    meta = _meta(cluster_dir)
+    enable_fips = bool(meta.get('enable_fips', False))
+    cl = LocalCluster(base_dir=cluster_dir, node_count=meta['node_count'], topology=meta['topology'], enable_fips=enable_fips)
+    return emit(args, cl.get_status(), _render_cluster_summary)
+
+
+def _handle_stop(args: argparse.Namespace) -> int:
+    cluster_dir = getattr(args, 'dir', None) or os.path.abspath('cluster-testnet')
+    if not os.path.exists(cluster_dir):
+        fail(f"Cluster directory {cluster_dir} does not exist.")
+    meta_path = os.path.join(cluster_dir, 'cluster.json')
+    if os.path.exists(meta_path):
+        meta = _meta(cluster_dir)
+        # Ask each node to retire; one that is already gone is no error.
+        for i in range(meta.get('node_count', 3)):
+            try_ask(os.path.join(cluster_dir, f'node_{i}'), 'retire', reason='cluster stop')
+        meta['running'] = False
+        with open(meta_path, 'w', encoding='utf-8') as _fh:
+            json.dump(meta, _fh, indent=2)
+    print(f"Cluster in {cluster_dir} stopped.")
+    return 0
+
+
+def _handle_sync(args: argparse.Namespace) -> int:
+    cluster_dir = getattr(args, 'dir', None) or os.path.abspath('cluster-testnet')
+    meta = _meta(cluster_dir)
+    shard = getattr(args, 'shard', 'bristol')
+    print(f"Triggering cluster-wide sync for shard {shard!r}...")
+    for i in range(meta.get('node_count', 3)):
+        ndir = os.path.join(cluster_dir, f'node_{i}')
+        peers = try_ask(ndir, 'peers')
+        if peers is None:
+            print(f"  node_{i} sync notice: node is not answering")
+            continue
+        for p in peers:
+            if try_ask(ndir, 'pull', peer=p['peer'], shard=shard) is None:
+                print(f"  node_{i} sync notice: pull from {p['peer'][:16]} declined")
+    print("Sync triggered across cluster.")
+    return 0
+
+
+CLUSTER_DISPATCHER = CommandDispatcher('cluster', default_action='status', action_dest='cluster_action')
+CLUSTER_DISPATCHER.add_custom('start', _handle_start, parameters=(PARAM_NODES, PARAM_TOPOLOGY, PARAM_RELAYS, PARAM_FIPS))
+CLUSTER_DISPATCHER.add_custom('status', _handle_status)
+CLUSTER_DISPATCHER.add_custom('stop', _handle_stop)
+CLUSTER_DISPATCHER.add_custom('sync', _handle_sync, parameters=(PARAM_SHARD,))
+
+
+def cmd_cluster(args: argparse.Namespace) -> int:
+    return CLUSTER_DISPATCHER.dispatch(args)
+
+
+class ClusterCommandProvider:
+    """Registers the local testnet cluster command."""
+
+    @classmethod
+    def register(cls, sub: argparse._SubParsersAction) -> None:
+        cl = add_command(sub, 'cluster', cmd_cluster, 'manage a local multi-node testnet cluster', js=True)
+        CLUSTER_DISPATCHER.register_arguments(cl, action_choices=('start', 'status', 'stop', 'sync'), action_dest='cluster_action')