feat(cli): add 'orb server ui-export' to copy the SPA bundle to a directory

Adds a new `orb server ui-export --dest <dir>` subcommand under the existing
`server` group. It locates the compiled SPA bundle via the shared
`_resolve_static_dir()` seam in `orb.ui.app` (same source of truth used by
the embedded-server route) and copies it with `shutil.copytree`.

This lets operators export the built frontend to any local directory they
can then push to a CDN, S3, GCS, or any static host using their own tooling
(aws s3 cp --recursive, gsutil rsync, rsync, etc.) — keeping the command
provider-agnostic and trivial.

- `--dest` (required): target directory
- `--force`: allow overwrite into a non-empty / pre-existing destination
- Returns a success dict with dest path and file count, or a clear error
  when the bundle is missing (hint: pip install 'orb-py[ui]' + make ui-build)
- Four unit tests covering: happy path, missing bundle, non-empty-without-force,
  and non-empty-with-force
- pyright: 0 errors on all touched files

Author: fgogolli

src/orb/cli/args.py

@@ -608,6 +608,22 @@ def _add_server_start_args(p):
     )
     add_global_arguments(server_reload_cmd)
 
+    server_ui_export = server_subparsers.add_parser(
+        "ui-export",
+        help="Copy the compiled SPA bundle to a local directory for CDN / static-host serving",
+    )
+    add_global_arguments(server_ui_export)
+    server_ui_export.add_argument(
+        "--dest",
+        required=True,
+        help="Target directory to copy the SPA bundle into",
+    )
+    server_ui_export.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow overwriting into a non-empty or already-existing destination",
+    )
+
     # Infrastructure
     infrastructure_parser = subparsers.add_parser("infrastructure", help="Infrastructure discovery")
     resource_parsers["infrastructure"] = infrastructure_parser

src/orb/cli/registry.py

@@ -180,6 +180,7 @@ async def _handle_mcp_tools(args: argparse.Namespace) -> Any:
         handle_server_start,
         handle_server_status,
         handle_server_stop,
+        handle_server_ui_export,
     )
 
     register("server", "start", handle_server_start)
@@ -188,6 +189,7 @@ async def _handle_mcp_tools(args: argparse.Namespace) -> Any:
     register("server", "restart", handle_server_restart)
     register("server", "reload", handle_server_reload)
     register("server", "logs", handle_server_logs)
+    register("server", "ui-export", handle_server_ui_export)
 
     # --- templates ---
     from orb.interface.template_command_handlers import (

src/orb/interface/server_command_handlers.py

@@ -417,3 +417,64 @@ async def handle_server_logs(args) -> dict[str, Any]:
         "log_file": log_file,
         "tail": daemon_mod.tail_log(log_file=log_file, lines=int(lines)),
     }
+
+
+def _ui_resolve_static_dir():
+    """Thin wrapper around ``orb.ui.app._resolve_static_dir``.
+
+    Importing lazily keeps the heavy Reflex/page graph out of the CLI process
+    when the UI extras are not installed.  The wrapper lives in this module so
+    tests can patch ``orb.interface.server_command_handlers._ui_resolve_static_dir``
+    without having to import ``orb.ui.app`` (and its reflex/page side-effects).
+    """
+    from orb.ui.app import _resolve_static_dir
+
+    return _resolve_static_dir()
+
+
+@handle_interface_exceptions(context="server_ui_export", interface_type="cli")
+async def handle_server_ui_export(args) -> dict[str, Any]:
+    """Copy the compiled SPA bundle to a local directory for CDN / static-host serving.
+
+    Locates the bundle via ``orb.ui.app._resolve_static_dir()`` (single source
+    of truth shared with the embedded server route) and copies it with
+    ``shutil.copytree``.
+
+    # ponytail: local dir only; users pipe to s3/gcs with their own tooling
+    """
+    import shutil
+    from pathlib import Path
+
+    dest_arg: str = getattr(args, "dest", None) or ""
+    force: bool = getattr(args, "force", False)
+
+    static_dir: Path | None = _ui_resolve_static_dir()
+    if static_dir is None:
+        return {
+            "status": "error",
+            "message": (
+                "UI bundle not found — no compiled SPA is available. "
+                "Install the UI extras and build the bundle: "
+                "pip install 'orb-py[ui]' then run 'make ui-build'."
+            ),
+        }
+
+    dest = Path(dest_arg).resolve()
+    if dest.exists() and any(dest.iterdir()) and not force:
+        return {
+            "status": "error",
+            "message": (
+                f"Destination '{dest}' already exists and is not empty. "
+                "Use --force to overwrite."
+            ),
+        }
+
+    shutil.copytree(str(static_dir), str(dest), dirs_exist_ok=force)
+
+    file_count = sum(1 for _ in dest.rglob("*") if _.is_file())
+    return {
+        "status": "ok",
+        "dest": str(dest),
+        "file_count": file_count,
+        "message": f"SPA bundle exported to '{dest}' ({file_count} files).",
+    }

tests/unit/interface/test_server_ui_export.py

@@ -0,0 +1,100 @@
+"""Unit tests for the ``orb server ui-export`` CLI handler."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+def _args(dest: str, force: bool = False) -> argparse.Namespace:
+    return argparse.Namespace(dest=dest, force=force)
+
+
+@pytest.mark.asyncio
+async def test_export_copies_bundle_to_dest(tmp_path: Path) -> None:
+    """Handler copies the bundle to the destination and reports file count."""
+    # Build a minimal fake static bundle in a source tmp dir.
+    source = tmp_path / "static"
+    source.mkdir()
+    (source / "index.html").write_text("<html/>")
+    (source / "assets").mkdir()
+    (source / "assets" / "main.js").write_text("// js")
+
+    dest = tmp_path / "export"
+
+    from orb.interface.server_command_handlers import handle_server_ui_export
+
+    with patch(
+        "orb.interface.server_command_handlers._ui_resolve_static_dir", return_value=source
+    ):
+        result = await handle_server_ui_export(_args(str(dest)))
+
+    assert result["status"] == "ok"
+    assert result["dest"] == str(dest)
+    assert result["file_count"] == 2
+    assert (dest / "index.html").is_file()
+    assert (dest / "assets" / "main.js").is_file()
+
+
+@pytest.mark.asyncio
+async def test_export_returns_error_when_bundle_missing() -> None:
+    """Handler returns a clear error dict when _resolve_static_dir() returns None."""
+    from orb.interface.server_command_handlers import handle_server_ui_export
+
+    with patch(
+        "orb.interface.server_command_handlers._ui_resolve_static_dir", return_value=None
+    ):
+        result = await handle_server_ui_export(_args("/tmp/irrelevant"))
+
+    assert result["status"] == "error"
+    assert "bundle not found" in result["message"].lower()
+    assert "pip install" in result["message"]
+
+
+@pytest.mark.asyncio
+async def test_export_rejects_non_empty_dest_without_force(tmp_path: Path) -> None:
+    """Handler refuses to overwrite a non-empty destination unless --force is set."""
+    source = tmp_path / "static"
+    source.mkdir()
+    (source / "index.html").write_text("<html/>")
+
+    dest = tmp_path / "existing"
+    dest.mkdir()
+    (dest / "stale.txt").write_text("old content")
+
+    from orb.interface.server_command_handlers import handle_server_ui_export
+
+    with patch(
+        "orb.interface.server_command_handlers._ui_resolve_static_dir", return_value=source
+    ):
+        result = await handle_server_ui_export(_args(str(dest), force=False))
+
+    assert result["status"] == "error"
+    assert "--force" in result["message"]
+    # Original content should be untouched.
+    assert (dest / "stale.txt").is_file()
+
+
+@pytest.mark.asyncio
+async def test_export_overwrites_non_empty_dest_with_force(tmp_path: Path) -> None:
+    """Handler merges/overwrites into an existing destination when --force is set."""
+    source = tmp_path / "static"
+    source.mkdir()
+    (source / "index.html").write_text("<html/>")
+
+    dest = tmp_path / "existing"
+    dest.mkdir()
+    (dest / "stale.txt").write_text("old content")
+
+    from orb.interface.server_command_handlers import handle_server_ui_export
+
+    with patch(
+        "orb.interface.server_command_handlers._ui_resolve_static_dir", return_value=source
+    ):
+        result = await handle_server_ui_export(_args(str(dest), force=True))
+
+    assert result["status"] == "ok"
+    assert (dest / "index.html").is_file()