xcorecli 1.0.0__py3-none-any.whl

xcli/plugin/scaffold.py

@@ -0,0 +1,213 @@
+from pathlib import Path
+
+import yaml
+
+# ── Templates src/main.py ─────────────────────────────────────
+
+_TRUSTED_TEMPLATE = '''\
+from xcore.kernel.api.contract import TrustedBase, error, ok
+
+
+class Plugin(TrustedBase):
+    """
+    {description}
+    Execution mode : trusted — full service injection via self.get_service().
+    """
+
+    async def on_load(self) -> None:
+        # Access services here, e.g.:
+        #   self.db    = self.get_service("db")
+        #   self.cache = self.get_service("cache")
+        pass
+
+    async def on_reload(self) -> None:
+        pass
+
+    async def on_unload(self) -> None:
+        pass
+
+    async def handle(self, action: str, payload: dict) -> dict:
+        match action:
+            case "ping":
+                return ok(message="pong")
+            case _:
+                return error(f"unknown action: {{action!r}}")
+
+    def get_router(self):
+        """Expose custom HTTP routes under /plugin/{name}/."""
+        from fastapi import APIRouter
+
+        router = APIRouter(prefix="/", tags=["{name}"])
+
+        @router.get("/")
+        async def index():
+            return {{"plugin": "{name}", "status": "ok"}}
+
+        return router
+'''
+
+_SANDBOXED_TEMPLATE = '''\
+from xcore.kernel.api.contract import error, ok
+
+
+class Plugin:
+    """
+    {description}
+    Execution mode : sandboxed — runs in an isolated subprocess.
+    No direct service injection; use IPC if needed.
+    """
+
+    _config: dict = {{}}
+
+    async def handle(self, action: str, payload: dict) -> dict:
+        match action:
+            case "ping":
+                return ok(message="pong")
+            case _:
+                return error(f"unknown action: {{action!r}}")
+'''
+
+_LEGACY_TEMPLATE = '''\
+from xcore.kernel.api.contract import error, ok
+
+
+class Plugin:
+    """
+    {description}
+    Execution mode : legacy — duck-typed, minimal lifecycle hooks.
+    """
+
+    _config: dict = {{}}
+
+    async def on_init(self) -> None:
+        pass
+
+    async def on_start(self) -> None:
+        pass
+
+    async def on_stop(self) -> None:
+        pass
+
+    async def handle(self, action: str, payload: dict) -> dict:
+        match action:
+            case "ping":
+                return ok(message="pong")
+            case _:
+                return error(f"unknown action: {{action!r}}")
+'''
+
+_TEMPLATES = {
+    "trusted": _TRUSTED_TEMPLATE,
+    "sandboxed": _SANDBOXED_TEMPLATE,
+    "legacy": _LEGACY_TEMPLATE,
+}
+
+
+# ── Manifest builder ──────────────────────────────────────────
+
+def _build_manifest(cfg: dict) -> dict:
+    manifest: dict = {
+        "name": cfg["name"],
+        "version": cfg["version"],
+        "author": cfg["author"],
+        "description": cfg["description"],
+        "framework_version": cfg["framework_version"],
+        "execution_mode": cfg["execution_mode"],
+        "entry_point": cfg["entry_point"],
+    }
+
+    if cfg.get("allowed_imports"):
+        manifest["allowed_imports"] = cfg["allowed_imports"]
+
+    if cfg.get("requires"):
+        manifest["requires"] = cfg["requires"]
+
+    if cfg.get("env"):
+        manifest["env"] = cfg["env"]
+        manifest["envconfiguration"] = {"inject": True, "env_file": ".env"}
+
+    resources: dict = {}
+    if cfg.get("timeout_seconds", 10) != 10:
+        resources["timeout_seconds"] = cfg["timeout_seconds"]
+    if cfg.get("max_memory_mb", 128) != 128:
+        resources["max_memory_mb"] = cfg["max_memory_mb"]
+    if cfg.get("max_disk_mb", 50) != 50:
+        resources["max_disk_mb"] = cfg["max_disk_mb"]
+    rl_calls = cfg.get("rate_limit_calls", 100)
+    rl_period = cfg.get("rate_limit_period", 60)
+    if rl_calls != 100 or rl_period != 60:
+        resources["rate_limit"] = {"calls": rl_calls, "period_seconds": rl_period}
+    if resources:
+        manifest["resources"] = resources
+
+    runtime: dict = {}
+    if not cfg.get("healthcheck_enabled", True):
+        runtime["health_check"] = {"enabled": False}
+    if cfg.get("retry_attempts", 1) > 1:
+        runtime.setdefault("retry", {})["max_attempts"] = cfg["retry_attempts"]
+    if runtime:
+        manifest["runtime"] = runtime
+
+    allowed_paths = cfg.get("filesystem_allowed", ["data/"])
+    denied_paths = cfg.get("filesystem_denied", ["src/"])
+    if allowed_paths != ["data/"] or denied_paths != ["src/"]:
+        manifest["filesystem"] = {
+            "allowed_paths": allowed_paths,
+            "denied_paths": denied_paths,
+        }
+
+    if cfg.get("permissions"):
+        manifest["permissions"] = cfg["permissions"]
+
+    return manifest
+
+
+# ── File writer ───────────────────────────────────────────────
+
+def scaffold(cfg: dict, target_dir: Path) -> list[Path]:
+    """Generate the plugin directory structure and return created paths."""
+    cfg = {
+        "version": "0.1.0",
+        "author": "unknown",
+        "description": "",
+        "framework_version": ">=2.0",
+        "entry_point": "src/main.py",
+        "allowed_imports": [],
+        "requires": [],
+        "env": {},
+        "permissions": [],
+        **cfg,
+    }
+    created: list[Path] = []
+
+    def write(path: Path, content: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        created.append(path)
+
+    # plugin.yaml
+    manifest = _build_manifest(cfg)
+    write(
+        target_dir / "plugin.yaml",
+        yaml.dump(manifest, default_flow_style=False, allow_unicode=True, sort_keys=False),
+    )
+
+    # src/__init__.py
+    write(target_dir / "src" / "__init__.py", "")
+
+    # src/main.py
+    template = _TEMPLATES[cfg["execution_mode"]]
+    write(
+        target_dir / "src" / "main.py",
+        template.format(name=cfg["name"], description=cfg["description"] or ""),
+    )
+
+    # data/.gitkeep
+    write(target_dir / "data" / ".gitkeep", "")
+
+    # .env (only if env vars defined)
+    if cfg.get("env"):
+        env_lines = "\n".join(f'{k}={v}' for k, v in cfg["env"].items())
+        write(target_dir / ".env", env_lines + "\n")
+
+    return created

xcli/sandbox/cli.py

@@ -0,0 +1,124 @@
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from typer import Typer
+
+from xcli._run import ns, run
+
+_CTX = {"help_option_names": ["-h", "--help"]}
+app = Typer(help="Sandbox inspection and runtime.", context_settings=_CTX)
+console = Console()
+err = Console(stderr=True)
+
+
+# ── run ───────────────────────────────────────────────────────
+
+@app.command("run")
+def sandbox_run(name: str) -> None:
+    """Launch a plugin in an isolated sandbox."""
+    from xcore.cli.sandbox_cmd import handle_sandbox
+    run(handle_sandbox(ns(subcommand="run", name=name)))
+
+
+# ── call ──────────────────────────────────────────────────────
+
+@app.command("call")
+def sandbox_call(
+    name: str,
+    action: str,
+    payload: str = typer.Option("{}", "--payload", "-p", help="JSON payload"),
+) -> None:
+    """Start a plugin sandbox, call one action, print the result, then stop."""
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as e:
+        err.print(f"[red]Invalid JSON payload:[/red] {e}")
+        raise typer.Exit(1)
+
+    async def _run():
+        from xcore.configurations.loader import ConfigLoader
+        from xcore.kernel.sandbox.process_manager import SandboxConfig, SandboxProcessManager
+        from xcore.kernel.security.validation import ManifestValidator
+        from xcli._xcore import _NullCtx
+
+        cfg = ConfigLoader.load(None)
+        plugin_dir = Path(cfg.plugins.directory) / name
+
+        if not plugin_dir.is_dir():
+            err.print(f"[red]Plugin '[cyan]{name}[/cyan]' not found in {cfg.plugins.directory}[/red]")
+            raise typer.Exit(1)
+
+        try:
+            manifest, _, _ = ManifestValidator().load_and_validate(plugin_dir)
+        except Exception as e:
+            err.print(f"[red]Invalid manifest:[/red] {escape(str(e))}")
+            raise typer.Exit(1)
+
+        if manifest.execution_mode.value != "sandboxed":
+            err.print(
+                f"[yellow]⚠[/yellow] Plugin '[cyan]{name}[/cyan]' is mode "
+                f"[magenta]{manifest.execution_mode.value}[/magenta], not sandboxed. "
+                f"Use [dim]xcli plugin call[/dim] instead."
+            )
+            raise typer.Exit(1)
+
+        config = SandboxConfig(
+            timeout=manifest.resources.timeout_seconds,
+            max_restarts=0,
+            startup_timeout=5.0,
+        )
+        mgr = SandboxProcessManager(manifest, _NullCtx(), config)
+
+        try:
+            with console.status(f"Starting sandbox [cyan]{name}[/cyan]..."):
+                await mgr.start()
+
+            console.print(f"[dim]→ {name}.{action}({payload})[/dim]")
+            resp = await mgr._channel.call(action, data)
+
+            if resp.success:
+                console.print(Panel(
+                    json.dumps(resp.data, indent=2, ensure_ascii=False),
+                    title=f"[green]{name}.{action}[/green]",
+                    border_style="green",
+                ))
+            else:
+                console.print(Panel(
+                    escape(str(resp.data)),
+                    title=f"[red]{name}.{action} — error[/red]",
+                    border_style="red",
+                ))
+        finally:
+            await mgr.stop()
+            console.print(f"[dim]Sandbox {name} stopped.[/dim]")
+
+    run(_run())
+
+
+# ── limits / network / fs ─────────────────────────────────────
+
+@app.command("limits")
+def limits(name: str) -> None:
+    """Show resource limits declared in the plugin manifest."""
+    from xcore.cli.sandbox_cmd import handle_sandbox
+    run(handle_sandbox(ns(subcommand="limits", name=name)))
+
+
+@app.command("network")
+def network(name: str) -> None:
+    """Show the network policy for a plugin."""
+    from xcore.cli.sandbox_cmd import handle_sandbox
+    run(handle_sandbox(ns(subcommand="network", name=name)))
+
+
+@app.command("fs")
+def fs(name: str) -> None:
+    """Show the filesystem policy for a plugin."""
+    from xcore.cli.sandbox_cmd import handle_sandbox
+    run(handle_sandbox(ns(subcommand="fs", name=name)))