clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/cli.py

@@ -0,0 +1,549 @@
+"""CLM CLI — Canonical Layer 4 Human Interaction Surface.
+
+This module is the single canonical entry point for all CLI interactions
+with the CLM kernel.  It unifies:
+  - The sovereign executor pipeline (evaluate, memorize-mcard, init-tridb, etc.)
+  - The argparse-based front-end (run, status, list, flow, launch)
+
+Usage:
+    clm <clm_file>                        # sovereign evaluate
+    clm evaluate <clm_file> [extra_args]   # sovereign evaluate (explicit)
+    python -m clm run <file.yaml>          # argparse front-end
+    python -m clm status --verbose         # runtime status
+    python -m clm launch                   # sovereign node
+
+Sprint 382: Consolidated from clm.layer3.cli → clm.layer4.cli.
+"""
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from clm.layer1.engine import PTREngine
+from clm.layer1.engine_async import AsyncPTREngine
+from clm.layer1.runtimes import RuntimeFactory
+
+# ---------------------------------------------------------------------------
+# Sprint 382: Re-export the sovereign executor pipeline from Layer 4.
+# The full implementation lives in _sovereign_executor.py (moved from
+# layer3/cli.py).  These two symbols are the public contract consumed by
+# clm/__init__.py, clm/__main__.py, layer3/__init__.py and pyproject.toml.
+# ---------------------------------------------------------------------------
+from clm.layer4._sovereign_executor import (  # noqa: F401, E402
+    evaluate_cmd,
+)
+from clm.layer4.runner import CLMRunner
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Setup and Utilities
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure basic logging for CLI output."""
+    logging.basicConfig(
+        level=level, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+
+
+def parse_context(ctx_str: str) -> dict[str, Any]:
+    """Parse JSON context string into dictionary."""
+    if not ctx_str or ctx_str == "{}":
+        return {}
+    try:
+        return json.loads(ctx_str)
+    except json.JSONDecodeError as e:
+        print(f"❌ Error parsing context JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Commands
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def run_command(args: argparse.Namespace) -> None:
+    """Execute a CLM/PCard file or all CLMs in a directory."""
+    file_path = Path(args.file)
+
+    if file_path.is_dir():
+        _run_directory(file_path, args)
+    else:
+        _run_single_file(file_path, args)
+
+
+def _run_single_file(file_path: Path, args: argparse.Namespace) -> None:
+    """Execute a single CLM/PCard file."""
+    context = parse_context(args.context)
+    if file_path.exists():
+        context["pcard_dir"] = str(file_path.parent.absolute())
+
+    try:
+        print(f"📄 Loading CLM from: {file_path}")
+        if getattr(args, "use_async", False):
+            runner = CLMRunner()
+            report = asyncio.run(
+                asyncio.to_thread(runner.run_file, str(file_path), context)
+            )
+        else:
+            runner = CLMRunner()
+            report = runner.run_file(str(file_path), context=context)
+
+        if args.test:
+            _display_test_results(report)
+        else:
+            print(json.dumps(report, indent=2, default=str))
+
+        if report["status"] != "success":
+            sys.exit(1)
+
+    except FileNotFoundError:
+        print(f"❌ File not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+    except (ValueError, TypeError, RuntimeError, yaml.YAMLError) as e:
+        print(f"❌ Execution failed: {str(e)}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(1)
+
+
+def _run_directory(dir_path: Path, args: argparse.Namespace) -> None:
+    """Execute all CLM files in a directory."""
+    excluded_dirs = {"test_data", "__pycache__", "node_modules", ".git", ".venv"}
+    yaml_files = sorted(
+        f
+        for f in (
+            list(dir_path.rglob("*.yaml"))
+            + list(dir_path.rglob("*.yml"))
+            + list(dir_path.rglob("*.clm"))
+        )
+        if not any(part in excluded_dirs for part in f.parts)
+        and not f.name.startswith("_")
+    )
+
+    if not yaml_files:
+        print(f"❌ No YAML files found in: {dir_path}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"📁 Running {len(yaml_files)} CLM files in: {dir_path}")
+    print("=" * 60)
+
+    passed = 0
+    failed = 0
+    skipped = 0
+    failures: list[str] = []
+
+    for i, f in enumerate(yaml_files, 1):
+        rel = f.relative_to(dir_path.parent) if dir_path.parent != Path(".") else f
+        print(f"\n[{i}/{len(yaml_files)}] {rel}")
+
+        try:
+            with open(f) as fh:
+                raw = yaml.safe_load(fh)
+            if isinstance(raw, dict):
+                meta = raw.get("clm", {}).get("metadata", {})
+                if meta.get("skip_in_suite"):
+                    reason = (
+                        "requires_server"
+                        if meta.get("requires_server")
+                        else "skip_in_suite"
+                    )
+                    print(f"         ⏭️  SKIPPED ({reason})")
+                    skipped += 1
+                    continue
+        except (yaml.YAMLError, OSError):
+            pass
+
+        context = parse_context(args.context)
+        context["pcard_dir"] = str(f.parent.absolute())
+
+        try:
+            if getattr(args, "use_async", False):
+                runner = CLMRunner()
+                report = asyncio.run(
+                    asyncio.to_thread(runner.run_file, str(f), context)
+                )
+            else:
+                runner = CLMRunner()
+                report = runner.run_file(str(f), context=context)
+
+            if args.test:
+                _display_test_results(report)
+
+            if report.get("status") == "success":
+                print("         ✅ PASS")
+                passed += 1
+            else:
+                print("         ❌ FAIL")
+                failed += 1
+                failures.append(str(rel))
+
+        except (
+            FileNotFoundError,
+            ValueError,
+            TypeError,
+            RuntimeError,
+            yaml.YAMLError,
+            OSError,
+        ) as e:
+            print(f"         ❌ FAIL — {e}")
+            failed += 1
+            failures.append(str(rel))
+
+    print(f"\n{'=' * 60}")
+    skip_str = f", {skipped} skipped" if skipped else ""
+    print(
+        f"📊 Summary: {passed} passed, {failed} failed{skip_str} (total: {len(yaml_files)})"
+    )
+    if failures:
+        print("\nFailures:")
+        for name in failures:
+            print(f"  - {name}")
+    print()
+
+    if failed > 0:
+        sys.exit(1)
+
+
+def _display_test_results(report: dict[str, Any]) -> None:
+    """Display test results in human-readable format."""
+    result = report.get("result", {})
+
+    print(f"\n{'=' * 60}")
+    print(f"📊 Test Results: {report.get('chapter_title', 'Unknown')}")
+    print(f"{'=' * 60}")
+
+    if isinstance(result, dict):
+        examples = result.get("examples", [])
+        if examples:
+            passed = sum(1 for ex in examples if ex.get("consensus", False))
+            total = len(examples)
+
+            for i, ex in enumerate(examples, 1):
+                status = "✅" if ex.get("consensus", False) else "❌"
+                desc = ex.get("description", f"Example #{i}")
+                print(f"{status} {desc}")
+
+                if not ex.get("consensus", False):
+                    if "error" in ex:
+                        print(f"   Error: {ex['error']}")
+                    if "results" in ex:
+                        print(f"   Results: {ex['results']}")
+
+            print(f"\n{'=' * 60}")
+            print(f"Summary: {passed}/{total} PASSED")
+        else:
+            success = result.get(
+                "consensus",
+                result.get("success", report.get("status") == "success"),
+            )
+            status = "✅ PASSED" if success else "❌ FAILED"
+            print(f"Result: {status}")
+            if "output" in result:
+                print(f"Output: {result['output']}")
+    else:
+        print(f"Result: {result}")
+
+    print()
+
+
+def status_command(args: argparse.Namespace) -> None:
+    """Display polyglot runtime status."""
+    print("\n🌐 Polyglot Runtime Status")
+    print("=" * 60)
+    RuntimeFactory.print_status(verbose=args.verbose)
+    print()
+
+
+def list_command(args: argparse.Namespace) -> None:
+    """List available CLM files."""
+    print("\n📚 Available CLM Files")
+    print("=" * 60)
+
+    search_paths = [
+        Path("sample_pcards"),
+        Path("tests/chapters"),
+        Path("chapters"),
+    ]
+
+    found = False
+    for search_dir in search_paths:
+        if search_dir.exists():
+            files = sorted(
+                list(search_dir.rglob("*.yaml"))
+                + list(search_dir.rglob("*.clm"))
+                + list(search_dir.rglob("*.yml"))
+            )
+
+            if files:
+                print(f"\n📁 {search_dir}/")
+                for f in files:
+                    rel_path = (
+                        f.relative_to(search_dir.parent)
+                        if search_dir.parent != Path(".")
+                        else f
+                    )
+                    print(f"   • {rel_path}")
+                found = True
+
+    if not found:
+        print("❌ No CLM files found in sample_pcards/ or chapters/")
+
+    print("\n💡 Usage: python -m mcard.cli run <file>")
+    print()
+
+
+def flow_command(args: argparse.Namespace) -> None:
+    """Execute a Flow spec YAML via PTREngine/AsyncPTREngine."""
+    file_path = Path(args.file)
+    target_hash = args.target
+    if not target_hash:
+        print("❌ --target is required for flow execution", file=sys.stderr)
+        sys.exit(1)
+
+    inputs = parse_context(getattr(args, "inputs", "{}"))
+    if file_path.exists():
+        inputs["pcard_dir"] = str(file_path.parent.absolute())
+
+    try:
+        print(f"🧭 Executing Flow from: {file_path} -> target: {target_hash}")
+        if getattr(args, "use_async", False):
+            aengine = AsyncPTREngine()
+            report = asyncio.run(
+                aengine.run_flow_file_async(
+                    str(file_path), target_hash=target_hash, inputs=inputs
+                )
+            )
+        else:
+            engine = PTREngine()
+            report = engine.run_flow_file(
+                str(file_path), target_hash=target_hash, inputs=inputs
+            )
+
+        print(json.dumps(report, indent=2, default=str))
+        if report.get("status") != "success":
+            sys.exit(1)
+
+    except FileNotFoundError:
+        print(f"❌ File not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+    except (ValueError, TypeError, RuntimeError, yaml.YAMLError) as e:
+        print(f"❌ Flow execution failed: {str(e)}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(1)
+
+
+def launch_command(args: argparse.Namespace) -> None:
+    """Launch the Sovereign Node (Discovery + API)"""
+    import random
+
+    try:
+        from clm.layer4.api import start_api_server
+    except ImportError:
+        start_api_server = None
+
+    node_id = (
+        getattr(args, "node_id", None) or f"did:key:pkc_user_{random.randint(100, 999)}"
+    )
+    from clm.cross_cutting.config.config_constants import DEFAULT_PYTHON_API_PORT
+
+    port = getattr(args, "port", DEFAULT_PYTHON_API_PORT)
+
+    print("🚀 Launching Sovereign PKC Node (Python Kernel)")
+    print(f"[Kernel] Initialized core execution environment for {node_id}")
+
+    if start_api_server:
+        print(f"[API] Booting backend interface on port {port}...")
+        try:
+            start_api_server()
+        except KeyboardInterrupt:
+            print("\nShutting down...")
+            sys.exit(0)
+    else:
+        print("[API] API server module not configured.")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main Entry Point
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="MCard CLI - Sovereign CLM and Coordination Engine",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m mcard.cli run my_clm.yaml
+  python -m mcard.cli run my_clm.yaml --context '{"a": 1}'
+  python -m mcard.cli run my_clm.yaml --test --verbose
+  python -m mcard.cli status --verbose
+  python -m mcard.cli list
+""",
+    )
+
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose output"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # Run Command
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Execute a CLM Chapter/PCard",
+        description="Execute a CLM specification from a YAML file.",
+    )
+    run_parser.add_argument("file", help="Path to the CLM/YAML file")
+    run_parser.add_argument(
+        "--context",
+        "-c",
+        default="{}",
+        help="JSON string for execution context (default: {})",
+    )
+    run_parser.add_argument(
+        "--test", "-t", action="store_true", help="Display results in test format"
+    )
+    run_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose output"
+    )
+    run_parser.add_argument(
+        "--async",
+        dest="use_async",
+        action="store_true",
+        help="Use AsyncPTREngine for async execution",
+    )
+
+    # Status Command
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show polyglot runtime status",
+        description="Display the status of all polyglot runtimes (Python, JS, Rust, etc.)",
+    )
+    status_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Show detailed status"
+    )
+
+    # List Command
+    list_parser = subparsers.add_parser(
+        "list",
+        help="List available CLM files",
+        description="List CLM files in sample_pcards/ and chapters/ directories.",
+    )
+    list_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Show detailed listing"
+    )
+
+    # Launch Command
+    launch_parser = subparsers.add_parser(
+        "launch",
+        help="Start the Sovereign Node (Discovery + API)",
+        description="Start local API background processes.",
+    )
+    from clm.cross_cutting.config.config_constants import DEFAULT_PYTHON_API_PORT
+
+    launch_parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=DEFAULT_PYTHON_API_PORT,
+        help="Port to broadcast on mDNS",
+    )
+    launch_parser.add_argument(
+        "-n", "--node-id", type=str, help="DID or Node ID for the Mesh"
+    )
+
+    # Flow Command
+    flow_parser = subparsers.add_parser(
+        "flow",
+        help="Execute a Flow spec YAML",
+        description="Run a declarative PCard flow (with optional nested subflows)",
+    )
+    flow_parser.add_argument("file", help="Path to the Flow YAML file")
+    flow_parser.add_argument(
+        "--target",
+        "-t",
+        required=True,
+        help="Target MCard hash for the flow",
+    )
+    flow_parser.add_argument(
+        "--inputs",
+        "-i",
+        default="{}",
+        help="JSON string for flow inputs (default: {})",
+    )
+    flow_parser.add_argument(
+        "--async",
+        dest="use_async",
+        action="store_true",
+        help="Use AsyncPTREngine for async flow execution",
+    )
+
+    args = parser.parse_args()
+
+    if hasattr(args, "verbose") and args.verbose:
+        setup_logging(logging.DEBUG)
+    else:
+        setup_logging(logging.WARNING)
+
+    if args.command == "run":
+        run_command(args)
+    elif args.command == "status":
+        status_command(args)
+    elif args.command == "list":
+        list_command(args)
+    elif args.command == "launch":
+        launch_command(args)
+    elif args.command == "flow":
+        flow_command(args)
+    else:
+        parser.print_help()
+        print("\n💡 Try: clm run --help")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+
+# Register evaluate_cmd with Layer 1 callback registry (Dependency Inversion)
+try:
+    from clm.layer1.eval_callback import register_evaluate_callback
+
+    register_evaluate_callback(evaluate_cmd)
+except ImportError:
+    pass
+
+# Aliasing for clm.layer4.cli.tridb_admin submodule compatibility (DEL-387-03)
+try:
+    from clm.layer4 import tridb_admin
+    sys.modules["clm.layer4.cli.tridb_admin"] = tridb_admin
+except ImportError:
+    pass
+
+# Aliasing for clm.layer4.cli.mcard_commands submodule compatibility (DEL-392-03)
+try:
+    from clm.layer4 import mcard_commands
+    sys.modules["clm.layer4.cli.mcard_commands"] = mcard_commands
+except ImportError:
+    pass
+
+# Aliasing for clm.layer4.cli action and diff submodules (DEL-396-01)
+try:
+    from clm.layer4 import action_commands
+    sys.modules["clm.layer4.cli.action_commands"] = action_commands
+    from clm.layer4 import diff_commands
+    sys.modules["clm.layer4.cli.diff_commands"] = diff_commands
+except ImportError:
+    pass