brawny 0.1.13__py3-none-any.whl

brawny/cli/commands/health.py

@@ -0,0 +1,112 @@
+"""Health check command."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+import click
+
+from brawny.cli.helpers import get_db, print_json
+
+
+@click.command()
+@click.option("--format", "fmt", default="json", help="Output format (json or text)")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def health(fmt: str, config_path: str | None) -> None:
+    """Health check endpoint."""
+    from brawny.config import Config, get_config
+    from brawny._rpc import RPCManager
+
+    try:
+        if config_path:
+            config = Config.from_yaml(config_path)
+            config, _ = config.apply_env_overrides()
+        else:
+            config = get_config()
+    except Exception as e:
+        if fmt == "json":
+            print_json({"status": "unhealthy", "error": f"Config error: {e}"})
+        else:
+            click.echo(f"UNHEALTHY: Config error: {e}")
+        sys.exit(1)
+
+    db = get_db(config_path)
+    result: dict[str, Any] = {
+        "status": "healthy",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "components": {},
+    }
+
+    try:
+        db_stats = db.get_database_stats()
+        result["components"]["database"] = {
+            "status": "ok",
+            "type": db_stats.get("type", "unknown"),
+        }
+
+        try:
+            rpc = RPCManager.from_config(config)
+            rpc_health = rpc.get_health()
+            result["components"]["rpc"] = {
+                "status": "ok" if rpc_health["healthy_endpoints"] > 0 else "degraded",
+                "healthy_endpoints": rpc_health["healthy_endpoints"],
+                "total_endpoints": rpc_health["total_endpoints"],
+                "circuit_breaker_open": rpc_health["circuit_breaker_open"],
+            }
+
+            try:
+                block_number = rpc.get_block_number()
+                chain_id = rpc.get_chain_id()
+                result["components"]["chain"] = {
+                    "chain_id": chain_id,
+                    "head_block": block_number,
+                }
+            except Exception as e:
+                result["components"]["chain"] = {
+                    "status": "error",
+                    "error": str(e)[:100],
+                }
+                result["status"] = "degraded"
+        except Exception as e:
+            result["components"]["rpc"] = {
+                "status": "error",
+                "error": str(e)[:100],
+            }
+            result["status"] = "degraded"
+
+        block_states = db_stats.get("block_states", [])
+        if block_states and "chain" in result["components"]:
+            result["components"]["chain"]["last_processed_block"] = block_states[0].get(
+                "last_block"
+            )
+
+        intents_by_status = db_stats.get("intents_by_status", {})
+        result["intents"] = {
+            "pending": intents_by_status.get("pending", 0),
+            "claimed": intents_by_status.get("claimed", 0),
+            "created": intents_by_status.get("created", 0),
+        }
+
+    except Exception as e:
+        result["status"] = "unhealthy"
+        result["error"] = str(e)[:200]
+    finally:
+        db.close()
+
+    if fmt == "json":
+        print_json(result)
+    else:
+        click.echo(f"Status: {result['status'].upper()}")
+        click.echo(f"Timestamp: {result['timestamp']}")
+        for name, component in result.get("components", {}).items():
+            status = component.get("status", "unknown")
+            click.echo(f"  {name}: {status}")
+
+    if result["status"] != "healthy":
+        sys.exit(1)
+
+
+def register(main) -> None:
+    main.add_command(health)

brawny/cli/commands/init_project.py

@@ -0,0 +1,86 @@
+"""Project initialization command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from brawny.cli.helpers import (
+    _check_directory_empty,
+    _write_agents,
+    _print_success,
+    _validate_project_name,
+    _write_config,
+    _write_env_example,
+    _write_examples,
+    _write_gitignore,
+    _write_monitoring,
+    _write_pyproject,
+)
+
+
+@click.command()
+@click.argument("project_name", required=False, default=None)
+@click.option("--force", "-f", is_flag=True, help="Initialize even if directory is not empty")
+def init(project_name: str | None, force: bool) -> None:
+    """Initialize a new brawny project in the current directory.
+
+    PROJECT_NAME defaults to the current directory name if not provided.
+
+    Examples:
+
+        brawny init              # Use current directory name
+
+        brawny init my_keeper    # Use 'my_keeper' as project name
+
+        brawny init -f           # Force init in non-empty directory
+    """
+    project_dir = Path.cwd()
+
+    if project_name is None:
+        project_name = project_dir.name
+
+    _validate_project_name(project_name)  # Validates name is usable
+
+    if not force:
+        _check_directory_empty(project_dir)
+
+    try:
+        # Normalize project name to valid Python package name
+        package_name = project_name.lower().replace("-", "_").replace(" ", "_")
+
+        # Create package_name, jobs, interfaces, and data structure
+        package_dir = project_dir / package_name
+        jobs_dir = project_dir / "jobs"
+        interfaces_dir = project_dir / "interfaces"
+        data_dir = project_dir / "data"
+        package_dir.mkdir(parents=True, exist_ok=True)
+        jobs_dir.mkdir(parents=True, exist_ok=True)
+        interfaces_dir.mkdir(parents=True, exist_ok=True)
+        data_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create __init__.py files
+        (package_dir / "__init__.py").touch()
+        (jobs_dir / "__init__.py").write_text(
+            '"""Job definitions - auto-discovered from ./jobs."""\n'
+        )
+
+        _write_pyproject(project_dir, project_name, package_name)
+        _write_config(project_dir, package_name)
+        _write_env_example(project_dir)
+        _write_agents(project_dir)
+        _write_gitignore(project_dir)
+        _write_examples(jobs_dir / "_examples.py")
+        _write_monitoring(project_dir)
+
+    except click.ClickException:
+        raise
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    _print_success(project_name, package_name)
+
+
+def register(main) -> None:
+    main.add_command(init)

brawny/cli/commands/intents.py

@@ -0,0 +1,130 @@
+"""Transaction intent commands."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from brawny.cli.helpers import get_db
+
+
+@click.group()
+def intents() -> None:
+    """Manage transaction intents."""
+    pass
+
+
+@intents.command("list")
+@click.option("--status", help="Filter by status")
+@click.option("--job", help="Filter by job ID")
+@click.option("--limit", default=50, help="Limit results")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def intents_list(status: str | None, job: str | None, limit: int, config_path: str | None) -> None:
+    """List transaction intents."""
+    db = get_db(config_path)
+    try:
+        intents_data = db.list_intents_filtered(status=status, job_id=job, limit=limit)
+        if not intents_data:
+            click.echo("No intents found.")
+            return
+
+        click.echo("\nTransaction Intents:")
+        click.echo("-" * 120)
+        click.echo(f"{'Intent ID':<38} {'Job':<20} {'Status':<12} {'Created':<20} {'Retry After':<20}")
+        click.echo("-" * 120)
+        for intent in intents_data:
+            intent_id = str(intent["intent_id"])[:36]
+            job_id = intent["job_id"][:18]
+            created = str(intent["created_at"])[:19]
+            retry_after = str(intent.get("retry_after") or "")[:19]
+            click.echo(f"{intent_id:<38} {job_id:<20} {intent['status']:<12} {created:<20} {retry_after:<20}")
+        click.echo(f"\n(Showing {len(intents_data)} of {limit} max)")
+    finally:
+        db.close()
+
+
+@intents.command("show")
+@click.argument("intent_id")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def intents_show(intent_id: str, config_path: str | None) -> None:
+    """Show intent details."""
+    from uuid import UUID
+
+    db = get_db(config_path)
+    try:
+        intent = db.get_intent(UUID(intent_id))
+        if not intent:
+            click.echo(f"Intent '{intent_id}' not found.", err=True)
+            sys.exit(1)
+
+        click.echo(f"\nIntent: {intent.intent_id}")
+        click.echo("-" * 60)
+        click.echo(f"  Job ID: {intent.job_id}")
+        click.echo(f"  Chain ID: {intent.chain_id}")
+        click.echo(f"  Status: {intent.status.value}")
+        click.echo(f"  Signer: {intent.signer_address}")
+        click.echo(f"  To: {intent.to_address}")
+        click.echo(f"  Value: {intent.value_wei} wei")
+        click.echo(f"  Idempotency Key: {intent.idempotency_key}")
+        click.echo(f"  Min Confirmations: {intent.min_confirmations}")
+        if intent.deadline_ts:
+            click.echo(f"  Deadline: {intent.deadline_ts}")
+        if intent.retry_after:
+            click.echo(f"  Retry After: {intent.retry_after}")
+        if intent.retry_count > 0:
+            click.echo(f"  Retry Count: {intent.retry_count}")
+        if intent.claim_token:
+            click.echo(f"  Claim Token: {intent.claim_token}")
+        click.echo(f"  Created: {intent.created_at}")
+        click.echo(f"  Updated: {intent.updated_at}")
+
+        attempts = db.get_attempts_for_intent(intent.intent_id)
+        if attempts:
+            click.echo(f"\n  Attempts ({len(attempts)}):")
+            for att in attempts:
+                status = att.status.value
+                tx_hash = att.tx_hash[:20] + "..." if att.tx_hash else "N/A"
+                click.echo(f"    - {att.attempt_id}: {status} (tx: {tx_hash})")
+        click.echo()
+    finally:
+        db.close()
+
+
+@intents.command("cancel")
+@click.argument("intent_id")
+@click.option("--force", is_flag=True, help="Force cancel even if in-flight")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def intents_cancel(intent_id: str, force: bool, config_path: str | None) -> None:
+    """Cancel an intent."""
+    from uuid import UUID
+
+    db = get_db(config_path)
+    try:
+        intent = db.get_intent(UUID(intent_id))
+        if not intent:
+            click.echo(f"Intent '{intent_id}' not found.", err=True)
+            sys.exit(1)
+
+        if intent.status.value in ("confirmed", "abandoned"):
+            click.echo(f"Intent is already {intent.status.value}.", err=True)
+            sys.exit(1)
+
+        if intent.status.value in ("sending", "pending") and not force:
+            click.echo(
+                f"Intent is {intent.status.value}. Use --force to cancel in-flight intents.",
+                err=True,
+            )
+            sys.exit(1)
+
+        if db.abandon_intent(UUID(intent_id)):
+            click.echo(f"Intent '{intent_id}' cancelled.")
+        else:
+            click.echo("Failed to cancel intent.", err=True)
+            sys.exit(1)
+    finally:
+        db.close()
+
+
+def register(main) -> None:
+    main.add_command(intents)

brawny/cli/commands/job_dev.py

@@ -0,0 +1,254 @@
+"""Developer utilities for individual jobs."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from brawny.cli.helpers import print_json
+
+
+@click.group()
+def job() -> None:
+    """Developer utilities for a single job."""
+    pass
+
+
+@job.command("run")
+@click.argument("job_id")
+@click.option("--at-block", type=int, help="Run check/build against this block")
+@click.option("--dry-run", is_flag=True, help="Run check only (skip build_intent)")
+@click.option(
+    "--jobs-module",
+    "jobs_modules",
+    multiple=True,
+    help="Additional job module(s) to load",
+)
+@click.option("--config", "config_path", default="./config.yaml", help="Path to config.yaml")
+def job_run(
+    job_id: str,
+    at_block: int | None,
+    dry_run: bool,
+    jobs_modules: tuple[str, ...],
+    config_path: str,
+) -> None:
+    """Run check/build for a single job without sending transactions."""
+    import time
+    from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeout
+
+    from brawny._context import _job_ctx, _current_job
+    from brawny.config import Config
+    from brawny.db import create_database
+    from brawny.alerts.contracts import ContractSystem
+    from brawny.jobs.kv import DatabaseJobKVStore
+    from brawny.jobs.registry import get_registry
+    from brawny.jobs.discovery import auto_discover_jobs, discover_jobs
+    from brawny.logging import get_logger, setup_logging
+    from brawny.model.enums import LogFormat
+    from brawny.model.types import BlockInfo, JobContext, idempotency_key
+    from brawny._rpc import RPCManager
+    from brawny.scripting import set_job_context
+
+    if not config_path or not os.path.exists(config_path):
+        click.echo(
+            f"Config file is required for job run and was not found: {config_path}",
+            err=True,
+        )
+        sys.exit(1)
+
+    config = Config.from_yaml(config_path)
+    config, overrides = config.apply_env_overrides()
+
+    log_level = os.environ.get("BRAWNY_LOG_LEVEL", "INFO")
+    setup_logging(log_level, LogFormat.JSON, config.chain_id)
+    log = get_logger(__name__)
+    log.info(
+        "config.loaded",
+        path=config_path,
+        overrides=overrides,
+        config=config.redacted_dict(),
+    )
+
+    db = create_database(
+        config.database_url,
+        pool_size=config.database_pool_size,
+        pool_max_overflow=config.database_pool_max_overflow,
+        pool_timeout=config.database_pool_timeout_seconds,
+        circuit_breaker_failures=config.db_circuit_breaker_failures,
+        circuit_breaker_seconds=config.db_circuit_breaker_seconds,
+    )
+    db.connect()
+
+    try:
+        rpc = RPCManager.from_config(config)
+        contract_system = ContractSystem(rpc, config)
+
+        modules = list(jobs_modules)
+        if modules:
+            discover_jobs(modules)
+        else:
+            auto_discover_jobs()
+
+        registry = get_registry()
+        job_obj = registry.get(job_id)
+        if job_obj is None:
+            click.echo(f"Job '{job_id}' not found. Did you register it?", err=True)
+            sys.exit(1)
+
+        if at_block is not None:
+            block_number = at_block
+        else:
+            with ThreadPoolExecutor(max_workers=1, thread_name_prefix="job_dev") as executor:
+                number_future = executor.submit(rpc.get_block_number, timeout=5)
+                try:
+                    block_number = number_future.result(timeout=10)
+                except FuturesTimeout:
+                    click.echo("Timed out fetching latest block number.", err=True)
+                    sys.exit(1)
+        block_hash = "0x0"
+        timestamp = 0
+
+        with ThreadPoolExecutor(max_workers=1, thread_name_prefix="job_dev") as executor:
+            block_future = executor.submit(rpc.get_block, block_number, False, 5)
+            try:
+                block_data = block_future.result(timeout=10)
+            except FuturesTimeout:
+                block_data = None
+
+        if block_data:
+            block_hash = block_data.get("hash", "")
+            if hasattr(block_hash, "hex"):
+                block_hash = f"0x{block_hash.hex()}"
+            timestamp = block_data.get("timestamp", 0)
+        else:
+            click.echo(
+                f"Warning: timed out loading block {block_number}; using fallback data.",
+                err=True,
+            )
+
+        block = BlockInfo(
+            chain_id=config.chain_id,
+            block_number=block_number,
+            block_hash=block_hash,
+            timestamp=timestamp,
+        )
+
+        job_config = db.get_job(job_id)
+        ctx = JobContext(
+            block=block,
+            rpc=rpc,
+            logger=log.bind(job_id=job_id),
+            state={},
+            job_config=job_config,
+            kv=DatabaseJobKVStore(db, job_id),
+            job_id=job_id,
+            contract_system=contract_system,
+            hook_name="check",
+        )
+
+        def _call_check():
+            # Set contextvars for implicit context
+            ctx_token = _job_ctx.set(ctx)
+            job_token = _current_job.set(job_obj)
+            set_job_context(True)
+            try:
+                return job_obj.check()
+            finally:
+                set_job_context(False)
+                _job_ctx.reset(ctx_token)
+                _current_job.reset(job_token)
+
+        with ThreadPoolExecutor(max_workers=1, thread_name_prefix="job_dev") as executor:
+            start = time.time()
+            future = executor.submit(_call_check)
+            try:
+                trigger = future.result(timeout=job_obj.check_timeout_seconds)
+            except FuturesTimeout:
+                click.echo(
+                    f"check() timed out after {job_obj.check_timeout_seconds}s",
+                    err=True,
+                )
+                sys.exit(1)
+
+        elapsed = time.time() - start
+
+        if not trigger:
+            click.echo(f"No trigger (check completed in {elapsed:.2f}s).")
+            return
+
+        idem_parts = list(trigger.idempotency_parts) or [block.block_number]
+        idem_key = idempotency_key(job_id, *idem_parts)
+
+        click.echo("\nTrigger:")
+        print_json(
+            {
+                "reason": trigger.reason,
+                "tx_required": trigger.tx_required,
+                "idempotency_parts": idem_parts,
+                "idempotency_key": idem_key,
+                "check_seconds": round(elapsed, 3),
+            }
+        )
+
+        if dry_run or not trigger.tx_required:
+            if dry_run:
+                click.echo("Dry run enabled; skipping build_intent.")
+            return
+
+        ctx_build = JobContext(
+            block=block,
+            rpc=rpc,
+            logger=log.bind(job_id=job_id),
+            state={"trigger": trigger},
+            job_config=job_config,
+            kv=DatabaseJobKVStore(db, job_id),
+            job_id=job_id,
+            contract_system=contract_system,
+            hook_name="build_intent",
+        )
+
+        def _call_build():
+            # Set contextvars for implicit context
+            ctx_token = _job_ctx.set(ctx_build)
+            job_token = _current_job.set(job_obj)
+            set_job_context(True)
+            try:
+                return job_obj.build_intent(trigger)
+            finally:
+                set_job_context(False)
+                _job_ctx.reset(ctx_token)
+                _current_job.reset(job_token)
+
+        with ThreadPoolExecutor(max_workers=1, thread_name_prefix="job_dev") as executor:
+            future = executor.submit(_call_build)
+            try:
+                spec = future.result(timeout=job_obj.build_timeout_seconds)
+            except FuturesTimeout:
+                click.echo(
+                    f"build_intent() timed out after {job_obj.build_timeout_seconds}s",
+                    err=True,
+                )
+                sys.exit(1)
+
+        click.echo("\nTxIntentSpec:")
+        print_json(
+            {
+                "signer_address": spec.signer_address,
+                "to_address": spec.to_address,
+                "data": spec.data,
+                "value_wei": spec.value_wei,
+                "gas_limit": spec.gas_limit,
+                "max_fee_per_gas": spec.max_fee_per_gas,
+                "max_priority_fee_per_gas": spec.max_priority_fee_per_gas,
+                "min_confirmations": spec.min_confirmations,
+                "deadline_seconds": spec.deadline_seconds,
+            }
+        )
+    finally:
+        db.close()
+
+
+def register(main) -> None:
+    main.add_command(job)