caspian-native 0.0.1__tar.gz

caspian_native-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Caspian Native contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

caspian_native-0.0.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: caspian-native
+Version: 0.0.1
+Summary: Optional Tauri packaging for Caspian applications
+Author: Caspian Native contributors
+License-Expression: MIT
+Keywords: caspian,pulsepoint,tauri,desktop,webview
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: build
+Requires-Dist: pyinstaller>=6; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: ruff>=0.8; extra == "test"
+Requires-Dist: pyright>=1.1; extra == "test"
+Dynamic: license-file
+
+# caspian-native
+
+Optional Tauri packaging for applications built with the Caspian framework and
+PulsePoint. Version `0.0.1` packages the existing application in a system
+WebView; it does not translate HTML into operating-system widgets.
+
+## Support in 0.0.1
+
+| Target | Backend | Status |
+| --- | --- | --- |
+| Windows | Embedded Python sidecar | Initial support |
+| Windows | Remote Caspian server | Initial support |
+| Android | Remote Caspian server | Initial support |
+| Android | Embedded Python | Not supported yet |
+
+Android embedded Python is deliberately refused. A Caspian application may
+depend on native Python wheels such as `asyncpg`, `cryptography`, or Pillow;
+shipping an APK without proving every wheel for every ABI would produce a
+package that builds unreliably or fails on launch.
+
+## Install for development
+
+```text
+python -m pip install -e ".[test,build]"
+```
+
+Tauri's CLI is installed separately so it can match the version selected by
+the generated application's `native/Cargo.toml`:
+
+```text
+cargo install tauri-cli --version "^2" --locked
+```
+
+## Add native packaging to a Caspian project
+
+From a directory containing `caspian.config.json`:
+
+```text
+caspian-native init --identifier com.example.myapp --windows
+caspian-native doctor --target windows
+caspian-native backend build
+caspian-native dev --target windows
+caspian-native build --target windows
+```
+
+For an Android thin client backed by a deployed Caspian server:
+
+```text
+caspian-native init \
+  --identifier com.example.myapp \
+  --windows --android \
+  --remote-url https://app.example.com
+caspian-native doctor --target android
+caspian-native build --target android
+```
+
+The generated files live under `native/`. Re-running `init` never overwrites a
+changed generated file unless `--force` is supplied.
+
+## Configuration
+
+`caspian.native.json` is the source of truth:
+
+```json
+{
+  "$schema": "./caspian.native.schema.json",
+  "schema": 1,
+  "productName": "My App",
+  "identifier": "com.example.myapp",
+  "version": "0.0.1",
+  "targets": ["windows"],
+  "window": {
+    "title": "My App",
+    "width": 1200,
+    "height": 800,
+    "resizable": true
+  },
+  "backend": {
+    "desktopMode": "embedded",
+    "remoteUrl": null
+  },
+  "security": {
+    "loopbackToken": true
+  }
+}
+```
+
+## Runtime model
+
+Embedded desktop mode builds `main.py`, the Caspian runtime, project modules,
+route index, and `public/` into a one-file sidecar. The sidecar:
+
+1. restores a per-installation `AUTH_SECRET` from application data;
+2. imports the project's `main.app` in production mode;
+3. binds `127.0.0.1` on an operating-system-assigned port;
+4. prints the protected launch URL to the Tauri host;
+5. serves the normal Caspian ASGI application with Uvicorn.
+
+The WebView receives a per-launch token once. The native middleware exchanges
+it for an `HttpOnly; SameSite=Strict` cookie and refuses documents, assets,
+RPCs, uploads, streams, and WebSocket handshakes without that cookie.
+
+Caspian's production session cookie normally has the `Secure` flag. A packaged
+loopback server intentionally uses `http://127.0.0.1`, so the adapter changes
+only that middleware option before Starlette constructs the stack. The app
+otherwise remains in production mode.
+
+## Native bridge
+
+Pages may capability-check `window.caspianNative`:
+
+```javascript
+const native = window.caspianNative;
+if (native?.has("open-external")) {
+  await native.invoke("open_external", { url: "https://example.com" });
+}
+```
+
+The bridge allowlist is intentionally short: platform, application version,
+application data directory, external HTTP/HTTPS/mail links, and a user-driven
+file picker. An XSS can reach every bridge command, so commands must remain
+safe even when the calling page is compromised.
+
+## Current limitations
+
+- The first embedded-backend implementation uses PyInstaller and has only been
+  designed for Windows packaging.
+- Dynamic route discovery requires project Python sources and
+  `settings/files-list.json` to be bundled.
+- Secrets from `.env` are never embedded. Remote database credentials and
+  third-party credentials must be provisioned outside the package.
+- Android remote mode requires connectivity and a deployed Caspian server.
+- Installer signing and Android store signing are not automated in `0.0.1`.
+

caspian_native-0.0.1/README.md

@@ -0,0 +1,134 @@
+# caspian-native
+
+Optional Tauri packaging for applications built with the Caspian framework and
+PulsePoint. Version `0.0.1` packages the existing application in a system
+WebView; it does not translate HTML into operating-system widgets.
+
+## Support in 0.0.1
+
+| Target | Backend | Status |
+| --- | --- | --- |
+| Windows | Embedded Python sidecar | Initial support |
+| Windows | Remote Caspian server | Initial support |
+| Android | Remote Caspian server | Initial support |
+| Android | Embedded Python | Not supported yet |
+
+Android embedded Python is deliberately refused. A Caspian application may
+depend on native Python wheels such as `asyncpg`, `cryptography`, or Pillow;
+shipping an APK without proving every wheel for every ABI would produce a
+package that builds unreliably or fails on launch.
+
+## Install for development
+
+```text
+python -m pip install -e ".[test,build]"
+```
+
+Tauri's CLI is installed separately so it can match the version selected by
+the generated application's `native/Cargo.toml`:
+
+```text
+cargo install tauri-cli --version "^2" --locked
+```
+
+## Add native packaging to a Caspian project
+
+From a directory containing `caspian.config.json`:
+
+```text
+caspian-native init --identifier com.example.myapp --windows
+caspian-native doctor --target windows
+caspian-native backend build
+caspian-native dev --target windows
+caspian-native build --target windows
+```
+
+For an Android thin client backed by a deployed Caspian server:
+
+```text
+caspian-native init \
+  --identifier com.example.myapp \
+  --windows --android \
+  --remote-url https://app.example.com
+caspian-native doctor --target android
+caspian-native build --target android
+```
+
+The generated files live under `native/`. Re-running `init` never overwrites a
+changed generated file unless `--force` is supplied.
+
+## Configuration
+
+`caspian.native.json` is the source of truth:
+
+```json
+{
+  "$schema": "./caspian.native.schema.json",
+  "schema": 1,
+  "productName": "My App",
+  "identifier": "com.example.myapp",
+  "version": "0.0.1",
+  "targets": ["windows"],
+  "window": {
+    "title": "My App",
+    "width": 1200,
+    "height": 800,
+    "resizable": true
+  },
+  "backend": {
+    "desktopMode": "embedded",
+    "remoteUrl": null
+  },
+  "security": {
+    "loopbackToken": true
+  }
+}
+```
+
+## Runtime model
+
+Embedded desktop mode builds `main.py`, the Caspian runtime, project modules,
+route index, and `public/` into a one-file sidecar. The sidecar:
+
+1. restores a per-installation `AUTH_SECRET` from application data;
+2. imports the project's `main.app` in production mode;
+3. binds `127.0.0.1` on an operating-system-assigned port;
+4. prints the protected launch URL to the Tauri host;
+5. serves the normal Caspian ASGI application with Uvicorn.
+
+The WebView receives a per-launch token once. The native middleware exchanges
+it for an `HttpOnly; SameSite=Strict` cookie and refuses documents, assets,
+RPCs, uploads, streams, and WebSocket handshakes without that cookie.
+
+Caspian's production session cookie normally has the `Secure` flag. A packaged
+loopback server intentionally uses `http://127.0.0.1`, so the adapter changes
+only that middleware option before Starlette constructs the stack. The app
+otherwise remains in production mode.
+
+## Native bridge
+
+Pages may capability-check `window.caspianNative`:
+
+```javascript
+const native = window.caspianNative;
+if (native?.has("open-external")) {
+  await native.invoke("open_external", { url: "https://example.com" });
+}
+```
+
+The bridge allowlist is intentionally short: platform, application version,
+application data directory, external HTTP/HTTPS/mail links, and a user-driven
+file picker. An XSS can reach every bridge command, so commands must remain
+safe even when the calling page is compromised.
+
+## Current limitations
+
+- The first embedded-backend implementation uses PyInstaller and has only been
+  designed for Windows packaging.
+- Dynamic route discovery requires project Python sources and
+  `settings/files-list.json` to be bundled.
+- Secrets from `.env` are never embedded. Remote database credentials and
+  third-party credentials must be provisioned outside the package.
+- Android remote mode requires connectivity and a deployed Caspian server.
+- Installer signing and Android store signing are not automated in `0.0.1`.
+

caspian_native-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "caspian-native"
+version = "0.0.1"
+description = "Optional Tauri packaging for Caspian applications"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Caspian Native contributors" }]
+keywords = ["caspian", "pulsepoint", "tauri", "desktop", "webview"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Environment :: Win32 (MS Windows)",
+  "Framework :: FastAPI",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.optional-dependencies]
+build = ["pyinstaller>=6"]
+test = ["pytest>=8", "ruff>=0.8", "pyright>=1.1"]
+
+[project.scripts]
+caspian-native = "caspian_native.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "basic"
+pythonVersion = "3.11"

caspian_native-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

caspian_native-0.0.1/src/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-0.0.1/src/caspian_native/__main__.py

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

caspian_native-0.0.1/src/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-0.0.1/src/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()