"""Example green-eye plugin.

Load it explicitly with ``--plugin plugins/example_plugin.py`` (the bundled
``plugins/`` directory is discovered automatically), or set
``GREENEYE_PLUGINS=/path/to/plugins``.

It demonstrates the three plugin extension points:
  * a CLI command (``gehits``),
  * runtime instrumentation (a hook on ``rpc_state`` logging transitions),
  * session notes / event stream contributions.
"""
from __future__ import annotations


def register(ge):
    ge.log("example plugin loaded")

    state_seen: list[int] = []

    def on_state(hit):
        state_seen.append(hit.retval or 0)
        ge.recorder.event(
            "plugin_state_transition",
            plugin="example",
            step=len(state_seen),
            result=hit.retval,
            a0=hit.arg(0),
        )

    sym = ge.symbols.get("rpc_state")
    if sym is not None:
        ge.hook("rpc_state", on_leave=on_state)
        ge.log("hooked rpc_state for transition logging")
    else:
        ge.log("rpc_state not in symbol DB; hook skipped")

    def cmd_gehits(session, args):
        """gehits -- print plugin-observed state transitions."""
        print(f"  observed {len(state_seen)} rpc_state transitions: {state_seen}")
        directory = getattr(session.recorder, "dir", None)
        if directory:
            print(f"  session: {directory}")
        return 0

    ge.add_command("gehits", cmd_gehits, help="print plugin-observed rpc_state transitions")