caspian-native 0.0.1__py3-none-any.whl

caspian_native/__init__.py

@@ -0,0 +1,8 @@
+"""Native WebView packaging for Caspian applications."""
+
+from .config import NativeConfig
+
+__all__ = ["NativeConfig", "__version__"]
+
+__version__ = "0.0.1"
+

caspian_native/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()
+

caspian_native/backend.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import NativeError
+from .project import CaspianProject
+
+
+def rust_host_triple() -> str:
+    result = subprocess.run(
+        ["rustc", "-vV"], capture_output=True, text=True, check=False, encoding="utf-8"
+    )
+    if result.returncode:
+        raise NativeError("rustc is required to name the Tauri sidecar target")
+    for line in result.stdout.splitlines():
+        if line.startswith("host: "):
+            return line.removeprefix("host: ").strip()
+    raise NativeError("rustc did not report a host target triple")
+
+
+def build_backend(project: CaspianProject) -> Path:
+    uv = shutil.which("uv")
+    if uv is None and shutil.which("pyinstaller") is None:
+        raise NativeError(
+            "embedded backend builds require uv (the normal Caspian environment manager) "
+            "or PyInstaller in the current Python environment"
+        )
+    public = project.root / "public"
+    files_list = project.root / "settings" / "files-list.json"
+    if not public.is_dir():
+        raise NativeError("the Caspian project has no public directory; run its build first")
+    if not files_list.is_file():
+        raise NativeError("settings/files-list.json is missing; run the Caspian project build first")
+
+    work = project.native_dir / ".backend-build"
+    dist = work / "dist"
+    spec = work / "spec"
+    binaries = project.native_dir / "binaries"
+    work.mkdir(parents=True, exist_ok=True)
+    binaries.mkdir(parents=True, exist_ok=True)
+    launcher = work / "launcher.py"
+    launcher.write_text(
+        "from caspian_native.runner import main\n\nif __name__ == '__main__':\n    main()\n",
+        encoding="utf-8",
+    )
+
+    add_data = [
+        (project.root / "main.py", "app"),
+        (project.root / "src", "app/src"),
+        (public, "app/public"),
+        (project.root / "caspian.config.json", "app"),
+        (files_list, "app/settings"),
+    ]
+    component_map = project.root / "settings" / "component-map.json"
+    if component_map.is_file():
+        add_data.append((component_map, "app/settings"))
+
+    separator = ";" if os.name == "nt" else ":"
+    if uv:
+        command = [
+            uv,
+            "run",
+            "--project",
+            str(project.root),
+            "--with",
+            "pyinstaller>=6",
+            "python",
+            "-m",
+            "PyInstaller",
+        ]
+    else:
+        command = [sys.executable, "-m", "PyInstaller"]
+    command.extend(
+        [
+        "--noconfirm",
+        "--clean",
+        "--onefile",
+        "--name",
+        "caspian-server",
+        "--distpath",
+        str(dist),
+        "--workpath",
+        str(work / "work"),
+        "--specpath",
+        str(spec),
+        "--paths",
+        str(project.root),
+        "--paths",
+        str(Path(__file__).resolve().parents[1]),
+        "--hidden-import",
+        "main",
+        "--collect-submodules",
+        "src",
+        "--collect-submodules",
+        "caspian_native",
+        "--collect-all",
+        "casp",
+        ]
+    )
+    for source, destination in add_data:
+        command.extend(["--add-data", f"{source}{separator}{destination}"])
+    command.append(str(launcher))
+
+    result = subprocess.run(command, cwd=project.root, check=False)
+    if result.returncode:
+        raise NativeError("PyInstaller failed to build the Caspian backend")
+
+    suffix = ".exe" if os.name == "nt" else ""
+    built = dist / f"caspian-server{suffix}"
+    if not built.is_file():
+        raise NativeError(f"PyInstaller completed but did not produce {built}")
+    target = binaries / f"caspian-server-{rust_host_triple()}{suffix}"
+    shutil.copy2(built, target)
+    return target

caspian_native/cli.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+from .backend import build_backend
+from .config import BackendConfig, NativeConfig, SecurityConfig, WindowConfig
+from .doctor import inspect
+from .errors import NativeError
+from .project import CaspianProject
+from .scaffold import write_generated
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="caspian-native")
+    root.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    root.add_argument("--project", type=Path, help="Caspian project root")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="create or refresh the native Tauri shell")
+    init.add_argument("--identifier", required=True)
+    init.add_argument("--product-name")
+    init.add_argument("--app-version", default="0.0.1")
+    init.add_argument("--windows", action="store_true")
+    init.add_argument("--android", action="store_true")
+    init.add_argument("--remote-url")
+    init.add_argument("--desktop-mode", choices=("embedded", "remote"), default="embedded")
+    init.add_argument("--force", action="store_true")
+
+    doctor = commands.add_parser("doctor", help="check native packaging prerequisites")
+    doctor.add_argument("--target", choices=("windows", "android"), default="windows")
+
+    backend = commands.add_parser("backend", help="build the embedded Caspian sidecar")
+    backend.add_argument("action", choices=("build",))
+
+    dev = commands.add_parser("dev", help="run the generated Tauri application")
+    dev.add_argument("--target", choices=("windows", "android"), default="windows")
+
+    build = commands.add_parser("build", help="build a native installer or Android package")
+    build.add_argument("--target", choices=("windows", "android"), default="windows")
+    build.add_argument("--debug", action="store_true")
+    return root
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parser().parse_args(argv)
+    try:
+        project = (
+            CaspianProject.from_root(args.project)
+            if args.project
+            else CaspianProject.discover()
+        )
+        if args.command == "init":
+            _init(project, args)
+        elif args.command == "doctor":
+            _doctor(project, args.target)
+        elif args.command == "backend":
+            print(build_backend(project))
+        elif args.command in {"dev", "build"}:
+            _tauri(project, args.command, args.target, getattr(args, "debug", False))
+    except NativeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+
+def _init(project: CaspianProject, args: argparse.Namespace) -> None:
+    targets = [target for target, enabled in (("windows", args.windows), ("android", args.android)) if enabled]
+    if not targets:
+        targets = ["windows"]
+    product = args.product_name or project.name.replace("-", " ").title()
+    config = NativeConfig(
+        product_name=product,
+        identifier=args.identifier,
+        version=args.app_version,
+        targets=targets,
+        window=WindowConfig(title=product),
+        backend=BackendConfig(desktop_mode=args.desktop_mode, remote_url=args.remote_url),
+        security=SecurityConfig(loopback_token=True),
+    )
+    config.validate()
+    for path, outcome in write_generated(project, config, force=args.force):
+        print(f"{outcome:9} {path}")
+
+
+def _doctor(project: CaspianProject, target: str) -> None:
+    config = NativeConfig.load(project.native_config)
+    checks = inspect(project, config, target)
+    for check in checks:
+        print(f"{'OK' if check.ok else 'MISSING':7} {check.name}: {check.detail}")
+    if not all(check.ok for check in checks):
+        raise NativeError(f"{target} prerequisites are incomplete")
+
+
+def _tauri(project: CaspianProject, action: str, target: str, debug: bool) -> None:
+    config = NativeConfig.load(project.native_config)
+    if target not in config.targets:
+        raise NativeError(f"target {target} is not enabled in caspian.native.json")
+    if target == "android" and not config.backend.remote_url:
+        raise NativeError("Android requires backend.remoteUrl in caspian-native 0.0.1")
+    if target == "windows" and config.backend.desktop_mode == "embedded":
+        build_backend(project)
+
+    command = ["cargo", "tauri"]
+    if target == "android":
+        command.extend(["android", action])
+    else:
+        command.append(action)
+    if debug and action == "build":
+        command.append("--debug")
+    result = subprocess.run(command, cwd=project.native_dir, check=False)
+    if result.returncode:
+        raise NativeError(f"Tauri {action} failed for {target}")
+
+
+if __name__ == "__main__":
+    main()

caspian_native/config.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import NativeError
+
+SCHEMA_VERSION = 1
+TARGETS = frozenset({"windows", "android"})
+MODES = frozenset({"embedded", "remote"})
+IDENTIFIER_RE = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)+$")
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$")
+
+
+@dataclass(slots=True)
+class WindowConfig:
+    title: str = "Caspian"
+    width: int = 1200
+    height: int = 800
+    resizable: bool = True
+
+
+@dataclass(slots=True)
+class BackendConfig:
+    desktop_mode: str = "embedded"
+    remote_url: str | None = None
+
+
+@dataclass(slots=True)
+class SecurityConfig:
+    loopback_token: bool = True
+
+
+@dataclass(slots=True)
+class NativeConfig:
+    product_name: str
+    identifier: str
+    version: str = "0.0.1"
+    targets: list[str] = field(default_factory=lambda: ["windows"])
+    window: WindowConfig = field(default_factory=WindowConfig)
+    backend: BackendConfig = field(default_factory=BackendConfig)
+    security: SecurityConfig = field(default_factory=SecurityConfig)
+    schema: int = SCHEMA_VERSION
+    schema_ref: str = "./caspian.native.schema.json"
+
+    def validate(self) -> None:
+        if self.schema != SCHEMA_VERSION:
+            raise NativeError(
+                f"caspian.native.json schema {self.schema} is unsupported; expected {SCHEMA_VERSION}"
+            )
+        if not self.product_name.strip():
+            raise NativeError("productName cannot be blank")
+        if not IDENTIFIER_RE.fullmatch(self.identifier):
+            raise NativeError(
+                "identifier must be reverse-DNS with legal Java identifiers, "
+                "for example com.example.myapp"
+            )
+        if not VERSION_RE.fullmatch(self.version):
+            raise NativeError("version must be a semantic version such as 0.0.1")
+        if not self.targets or any(target not in TARGETS for target in self.targets):
+            raise NativeError("targets must contain windows, android, or both")
+        if self.backend.desktop_mode not in MODES:
+            raise NativeError("backend.desktopMode must be embedded or remote")
+        if self.backend.remote_url and not self.backend.remote_url.startswith(("https://", "http://")):
+            raise NativeError("backend.remoteUrl must be an http or https URL")
+        if "android" in self.targets and not self.backend.remote_url:
+            raise NativeError(
+                "Android requires backend.remoteUrl in caspian-native 0.0.1; "
+                "an embedded Android Python runtime is not shipped yet"
+            )
+        if self.backend.desktop_mode == "remote" and not self.backend.remote_url:
+            raise NativeError("remote desktop mode requires backend.remoteUrl")
+        if self.window.width < 320 or self.window.height < 320:
+            raise NativeError("window width and height must be at least 320")
+
+    @classmethod
+    def load(cls, path: Path) -> NativeConfig:
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise NativeError(f"native configuration not found: {path}") from exc
+        except (OSError, json.JSONDecodeError) as exc:
+            raise NativeError(f"cannot read {path}: {exc}") from exc
+        if not isinstance(raw, dict):
+            raise NativeError(f"{path} must contain a JSON object")
+        return cls.from_dict(raw)
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> NativeConfig:
+        window_raw = _mapping(raw.get("window"), "window")
+        backend_raw = _mapping(raw.get("backend"), "backend")
+        security_raw = _mapping(raw.get("security"), "security")
+        config = cls(
+            product_name=_string(raw.get("productName"), "productName"),
+            identifier=_string(raw.get("identifier"), "identifier"),
+            version=_string(raw.get("version", "0.0.1"), "version"),
+            targets=list(raw.get("targets", ["windows"])),
+            window=WindowConfig(
+                title=str(window_raw.get("title", raw.get("productName", "Caspian"))),
+                width=int(window_raw.get("width", 1200)),
+                height=int(window_raw.get("height", 800)),
+                resizable=bool(window_raw.get("resizable", True)),
+            ),
+            backend=BackendConfig(
+                desktop_mode=str(backend_raw.get("desktopMode", "embedded")),
+                remote_url=_optional_string(backend_raw.get("remoteUrl")),
+            ),
+            security=SecurityConfig(
+                loopback_token=bool(security_raw.get("loopbackToken", True))
+            ),
+            schema=int(raw.get("schema", SCHEMA_VERSION)),
+            schema_ref=str(raw.get("$schema", "./caspian.native.schema.json")),
+        )
+        config.validate()
+        return config
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "$schema": self.schema_ref,
+            "schema": self.schema,
+            "productName": self.product_name,
+            "identifier": self.identifier,
+            "version": self.version,
+            "targets": self.targets,
+            "window": {
+                "title": self.window.title,
+                "width": self.window.width,
+                "height": self.window.height,
+                "resizable": self.window.resizable,
+            },
+            "backend": {
+                "desktopMode": self.backend.desktop_mode,
+                "remoteUrl": self.backend.remote_url,
+            },
+            "security": {"loopbackToken": self.security.loopback_token},
+        }
+
+    def write(self, path: Path) -> None:
+        path.write_text(json.dumps(self.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+
+def _mapping(value: object, name: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise NativeError(f"{name} must be a JSON object")
+    return value
+
+
+def _string(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise NativeError(f"{name} must be a non-empty string")
+    return value
+
+
+def _optional_string(value: object) -> str | None:
+    if value is None or value == "":
+        return None
+    if not isinstance(value, str):
+        raise NativeError("backend.remoteUrl must be a string or null")
+    return value.rstrip("/")
+

caspian_native/doctor.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+from .config import NativeConfig
+from .project import CaspianProject
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    name: str
+    ok: bool
+    detail: str
+
+
+def inspect(project: CaspianProject, config: NativeConfig, target: str) -> list[Check]:
+    checks = [
+        Check("Caspian config", (project.root / "caspian.config.json").is_file(), "caspian.config.json"),
+        Check("ASGI entry", (project.root / "main.py").is_file(), "main.py exports app"),
+        Check("routes", (project.root / "src" / "app").is_dir(), "src/app"),
+        Check("public assets", (project.root / "public").is_dir(), "public/"),
+        executable_check("cargo", ["cargo", "--version"]),
+        executable_check("rustc", ["rustc", "--version"]),
+        executable_check("Tauri CLI", ["cargo", "tauri", "--version"]),
+    ]
+    if target == "windows" and config.backend.desktop_mode == "embedded":
+        checks.extend(
+            [
+                executable_check("uv", ["uv", "--version"]),
+                Check(
+                    "route index",
+                    (project.root / "settings" / "files-list.json").is_file(),
+                    "run the Caspian project build to generate settings/files-list.json",
+                ),
+            ]
+        )
+    if target == "android":
+        checks.append(
+            Check(
+                "remote backend",
+                bool(config.backend.remote_url),
+                "Android is remote-backend only in caspian-native 0.0.1",
+            )
+        )
+        checks.append(executable_check("ADB", ["adb", "version"]))
+    return checks
+
+
+def executable_check(name: str, command: list[str]) -> Check:
+    executable = command[0]
+    if shutil.which(executable) is None:
+        return Check(name, False, f"{executable} was not found on PATH")
+    result = subprocess.run(command, capture_output=True, text=True, check=False)
+    detail = (result.stdout or result.stderr).splitlines()
+    return Check(name, result.returncode == 0, detail[0] if detail else "available")

caspian_native/errors.py

@@ -0,0 +1,3 @@
+class NativeError(RuntimeError):
+    """A user-actionable native packaging failure."""
+

caspian_native/project.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import NativeError
+
+
+@dataclass(frozen=True, slots=True)
+class CaspianProject:
+    root: Path
+    name: str
+
+    @property
+    def native_config(self) -> Path:
+        return self.root / "caspian.native.json"
+
+    @property
+    def native_dir(self) -> Path:
+        return self.root / "native"
+
+    @classmethod
+    def discover(cls, start: Path | None = None) -> CaspianProject:
+        current = (start or Path.cwd()).resolve()
+        for candidate in (current, *current.parents):
+            config_path = candidate / "caspian.config.json"
+            if config_path.is_file():
+                return cls.from_root(candidate)
+        raise NativeError(
+            "not inside a Caspian project: no caspian.config.json was found in this directory "
+            "or its parents"
+        )
+
+    @classmethod
+    def from_root(cls, root: Path) -> CaspianProject:
+        root = root.resolve()
+        required = [root / "caspian.config.json", root / "main.py", root / "src" / "app"]
+        missing = [str(path.relative_to(root)) for path in required if not path.exists()]
+        if missing:
+            raise NativeError(f"not a complete Caspian project; missing: {', '.join(missing)}")
+        try:
+            raw = json.loads((root / "caspian.config.json").read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise NativeError(f"cannot read caspian.config.json: {exc}") from exc
+        name = str(raw.get("projectName") or root.name)
+        return cls(root=root, name=name)
+