mascope_cli 2026.7.28__tar.gz

mascope_cli-2026.7.28/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.3
+Name: mascope_cli
+Version: 2026.7.28
+Summary: Mascope's operations CLI: install, launch and back up a Mascope deployment.
+Author: Karsa Oy
+Author-email: Karsa Oy <support@karsa.fi>
+License: Apache-2.0
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: mascope-runtime[logs]>=2026.7.28
+Requires-Dist: typer>=0.27.0,<0.28
+Requires-Dist: rich>=15.0.0,<16
+Requires-Dist: pandas>=2.0.0 ; extra == 'demo'
+Requires-Dist: requests>=2.32.0,<3 ; extra == 'demo'
+Requires-Dist: alembic>=1.18.1 ; extra == 'dev'
+Requires-Dist: sqlalchemy~=2.0 ; extra == 'dev'
+Requires-Dist: psycopg2-binary>=2.9.12 ; extra == 'dev'
+Requires-Dist: pyyaml>=6,<7 ; extra == 'dev'
+Maintainer: Oskari Kausiala
+Maintainer-email: Oskari Kausiala <oskari.kausiala@karsa.fi>
+Requires-Python: >=3.12, <3.13
+Project-URL: homepage, https://karsa.fi/
+Project-URL: repository, https://github.com/karsa-oy/mascope
+Project-URL: Bug Tracker, https://github.com/karsa-oy/mascope/issues
+Provides-Extra: demo
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Mascope CLI
+
+The operations CLI for [Mascope](https://karsa.fi/), Karsa's mass-spectrometry
+analysis platform. It installs, launches, backs up and manages a Mascope
+deployment — the application itself runs as Docker containers pulled from the
+project's registry.
+
+## Requirements
+
+- Python 3.12
+- Docker (with the compose plugin)
+
+## Quickstart
+
+```sh
+pip install mascope-cli
+
+mascope init        # create a runtime home: config, compose files, secrets
+mascope cert gen    # self-signed TLS cert (or install real certs)
+mascope prod up     # pull and start the production stack
+```
+
+`mascope init` creates the runtime home at `~/.mascope`
+(`%LOCALAPPDATA%\Mascope` on Windows) — configuration TOMLs you can edit,
+docker compose files, and generated application secrets. Set `MASCOPE_PATH`
+to place it elsewhere. Re-running `init` is safe: existing files are kept and
+secrets are never regenerated.
+
+To try Mascope without a deployment, the self-contained demo stack ships in
+the runtime home as well:
+
+```sh
+docker compose -f docker-compose.demo.yaml up -d
+# then open http://localhost:8080 — login demo@mascope.app / mascope-demo
+```
+
+## Everyday operations
+
+```sh
+mascope prod ps                  # container status
+mascope prod logs --follow       # stream logs
+mascope prod update              # update the stack to the latest release
+mascope prod db backup           # dump the database
+mascope prod db restore --yes    # restore the latest dump
+mascope logs query --grep error  # search the application's file logs
+mascope env list                 # manage runtime environments
+```
+
+Run `mascope --help` or `mascope <command> --help` for the full reference.
+
+`mascope prod update` pulls the target release images, restarts the stack
+with them and runs any pending database migrations (preceded by an automatic
+pre-migration dump). Move to a specific release with
+`mascope prod update --version v1.2.0`, or pin the deployed version for all
+commands with `MASCOPE_VERSION`; without a pin the stack follows the
+`latest` release images.
+
+## Development
+
+The Mascope source checkout exposes additional developer commands (`dev`,
+`test`, `agent`, `backend`) that operate on the monorepo; they are not part
+of the standalone install. See the
+[repository](https://github.com/karsa-oy/mascope) for the developer guide.

mascope_cli-2026.7.28/README.md

@@ -0,0 +1,63 @@
+# Mascope CLI
+
+The operations CLI for [Mascope](https://karsa.fi/), Karsa's mass-spectrometry
+analysis platform. It installs, launches, backs up and manages a Mascope
+deployment — the application itself runs as Docker containers pulled from the
+project's registry.
+
+## Requirements
+
+- Python 3.12
+- Docker (with the compose plugin)
+
+## Quickstart
+
+```sh
+pip install mascope-cli
+
+mascope init        # create a runtime home: config, compose files, secrets
+mascope cert gen    # self-signed TLS cert (or install real certs)
+mascope prod up     # pull and start the production stack
+```
+
+`mascope init` creates the runtime home at `~/.mascope`
+(`%LOCALAPPDATA%\Mascope` on Windows) — configuration TOMLs you can edit,
+docker compose files, and generated application secrets. Set `MASCOPE_PATH`
+to place it elsewhere. Re-running `init` is safe: existing files are kept and
+secrets are never regenerated.
+
+To try Mascope without a deployment, the self-contained demo stack ships in
+the runtime home as well:
+
+```sh
+docker compose -f docker-compose.demo.yaml up -d
+# then open http://localhost:8080 — login demo@mascope.app / mascope-demo
+```
+
+## Everyday operations
+
+```sh
+mascope prod ps                  # container status
+mascope prod logs --follow       # stream logs
+mascope prod update              # update the stack to the latest release
+mascope prod db backup           # dump the database
+mascope prod db restore --yes    # restore the latest dump
+mascope logs query --grep error  # search the application's file logs
+mascope env list                 # manage runtime environments
+```
+
+Run `mascope --help` or `mascope <command> --help` for the full reference.
+
+`mascope prod update` pulls the target release images, restarts the stack
+with them and runs any pending database migrations (preceded by an automatic
+pre-migration dump). Move to a specific release with
+`mascope prod update --version v1.2.0`, or pin the deployed version for all
+commands with `MASCOPE_VERSION`; without a pin the stack follows the
+`latest` release images.
+
+## Development
+
+The Mascope source checkout exposes additional developer commands (`dev`,
+`test`, `agent`, `backend`) that operate on the monorepo; they are not part
+of the standalone install. See the
+[repository](https://github.com/karsa-oy/mascope) for the developer guide.

mascope_cli-2026.7.28/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "mascope_cli"
+version = "2026.7.28"
+description = "Mascope's operations CLI: install, launch and back up a Mascope deployment."
+classifiers = [
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+authors = [{ name = "Karsa Oy", email = "support@karsa.fi" }]
+maintainers = [
+    { name = "Oskari Kausiala", email = "oskari.kausiala@karsa.fi" },
+]
+license.text = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+# Operator surface only (init, prod, env, demo, logs, cert). Developer
+# commands live behind the `dev` extra and a source-checkout gate in main.py.
+dependencies = [
+    # >=2026.7.28: `logs query` passes the service/json_output kwargs added
+    # to RuntimeLogging.query in that release.
+    "mascope_runtime[logs]>=2026.7.28",
+    "typer>=0.27.0,<0.28",
+    "rich>=15.0.0,<16",
+]
+
+[project.scripts]
+mascope = "mascope_cli.main:app"
+
+[project.optional-dependencies]
+# `mascope dev migrate` / `mascope dev db` / `mascope fleet` — monorepo
+# development only.
+dev = [
+    "alembic>=1.18.1",
+    "sqlalchemy~=2.0",
+    "psycopg2-binary>=2.9.12",
+    "pyyaml>=6,<7",
+]
+# `mascope demo build-bundle` / `verify` peak comparison (imported lazily).
+demo = [
+    "pandas>=2.0.0",
+    "requests>=2.32.0,<3",
+]
+
+[project.urls]
+homepage = "https://karsa.fi/"
+repository = "https://github.com/karsa-oy/mascope"
+"Bug Tracker" = "https://github.com/karsa-oy/mascope/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"

mascope_cli-2026.7.28/src/mascope_cli/__init__.py

@@ -0,0 +1 @@
+

mascope_cli-2026.7.28/src/mascope_cli/checkout.py

@@ -0,0 +1,38 @@
+"""
+Monorepo source-checkout detection.
+
+The CLI has two audiences: developers running it editable from the monorepo,
+and operators running it from a wheel. Developer commands (`dev`, `test`,
+`agent`, `backend`) drive the source tree itself and are only registered when
+the CLI actually runs from a checkout.
+"""
+
+from pathlib import Path
+
+
+def source_checkout(anchor: Path | None = None) -> Path | None:
+    """
+    Repo root of the Mascope checkout the CLI runs from, if any.
+
+    An editable install resolves ``mascope_cli`` inside the checkout
+    (``<root>/tooling/cli/src/mascope_cli``); a wheel install resolves it in
+    site-packages, where walking up never lands in the monorepo.
+
+    :param anchor: Location of the mascope_cli package; defaults to the
+                   imported package. Overridable for testing.
+    :type anchor: Path, optional
+    :return: The checkout root, or None when not running from source.
+    :rtype: Path | None
+    """
+    if anchor is None:
+        import mascope_cli
+
+        anchor = Path(mascope_cli.__file__).resolve().parent
+    # <root>/tooling/cli/src/mascope_cli -> root is 4 levels up.
+    parents = anchor.parents
+    if len(parents) < 4:
+        return None
+    root = parents[3]
+    if (root / "pyproject.toml").is_file() and (root / "tooling" / "cli").is_dir():
+        return root
+    return None

mascope_cli-2026.7.28/src/mascope_cli/cmd/__init__.py

@@ -0,0 +1,10 @@
+# flake8: noqa
+# Operator command groups — always available, wheel and checkout alike.
+# Developer groups (dev, test, agent, backend) are imported by main.py only
+# when running from a source checkout: they drive the monorepo itself and
+# pull in the `dev` extra's dependencies (alembic, sqlalchemy, psycopg2).
+from .cert import cert_app
+from .demo import demo_app
+from .env import env_app
+from .logs import logs_app
+from .prod import prod_app

mascope_cli-2026.7.28/src/mascope_cli/cmd/agent.py

@@ -0,0 +1,25 @@
+from typing import List, Optional
+
+import typer
+from typing_extensions import Annotated
+
+from mascope_cli.cmd import lib
+from mascope_cli.runtime import runtime
+
+
+agent_app = typer.Typer(add_help_option=False)
+
+
+@agent_app.callback(
+    invoke_without_command=True, context_settings={"ignore_unknown_options": True}
+)
+def main(args: Annotated[Optional[List[str]], typer.Argument()] = None) -> None:
+    """
+    Run a Mascope agent
+    """
+    if len(args) != 1:
+        runtime.logger.error("mascope agent requires exactly 1 argument: file or tof")
+        return
+    lib.run(
+        command=f"uv run mascope-{args[0]}-agent", cwd=runtime.path("agents", args[0])
+    )

mascope_cli-2026.7.28/src/mascope_cli/cmd/backend.py

@@ -0,0 +1,19 @@
+from typing import List, Optional
+
+import typer
+from typing_extensions import Annotated
+
+import mascope_cli.cmd.lib as lib
+
+
+backend_app = typer.Typer(add_help_option=False)
+
+
+@backend_app.callback(
+    invoke_without_command=True, context_settings={"ignore_unknown_options": True}
+)
+def main(args: Annotated[Optional[List[str]], typer.Argument()] = None) -> None:
+    """
+    Run a Mascope backend service.
+    """
+    lib.run(command=f"uv run mascope-backend {' '.join(args)}")

mascope_cli-2026.7.28/src/mascope_cli/cmd/cert.py

@@ -0,0 +1,64 @@
+import shutil
+from pathlib import Path
+
+import typer
+
+import mascope_cli.cmd.lib as lib
+from mascope_cli.runtime import runtime
+
+
+cert_app = typer.Typer()
+
+
+@cert_app.callback()
+def main():
+    """
+    Manage Mascope SSL certificates
+    """
+
+
+@cert_app.command()
+def gen():
+    """
+    Generate a self-signed SSL certificate
+
+    Writes mascope.app.key + mascope.app.pem into .runtime/secrets/. Use for
+    local HTTPS prod testing or a small LAN deployment (clients see a
+    self-signed warning). For a localhost-only trial, prefer the HTTP demo
+    stack (docker-compose.demo.yaml) instead.
+    """
+    secrets_dir = Path(runtime.path(".runtime", "secrets"))
+    secrets_dir.mkdir(parents=True, exist_ok=True)
+
+    key_path = secrets_dir / "mascope.app.key"
+    pem_path = secrets_dir / "mascope.app.pem"
+
+    # Docker creates an empty DIRECTORY at a missing `file:` secret source, which
+    # then blocks openssl from writing the file. Clear any such placeholders.
+    for path in (key_path, pem_path):
+        if path.is_dir():
+            shutil.rmtree(path)
+
+    # Use forward-slash (posix) paths: lib.run shlex-splits the command, which
+    # mangles Windows backslashes. openssl accepts forward slashes on Windows.
+    command = (
+        "openssl req "
+        + "-x509 "
+        + "-nodes "
+        + '-subj "/CN=mascope.app" '
+        + '-addext "subjectAltName=DNS:mascope.app" '
+        + "-days 365 "
+        + "-newkey rsa:2048 "
+        + f'-keyout "{key_path.as_posix()}" '
+        + f'-out "{pem_path.as_posix()}"'
+    )
+    lib.run(command)
+
+    if pem_path.is_file() and key_path.is_file():
+        runtime.logger.success(f"Wrote self-signed certificate to {secrets_dir}")
+    else:
+        runtime.logger.error(
+            "Certificate generation did not produce both files. On Windows you "
+            "may need to set OPENSSL_CONF, e.g. "
+            '$env:OPENSSL_CONF="C:\\Program Files\\Git\\usr\\ssl\\openssl.cnf".'
+        )

mascope_cli-2026.7.28/src/mascope_cli/cmd/demo/__init__.py

@@ -0,0 +1,2 @@
+# flake8: noqa
+from .main import demo_app

mascope_cli-2026.7.28/src/mascope_cli/cmd/demo/_fetch.py

@@ -0,0 +1,147 @@
+"""
+Download and verify a published demo bundle into the local cache.
+
+Pure download/extract/verify logic - no Typer concerns. The CLI command in
+``main.py`` wraps these helpers with user-facing messaging.
+"""
+
+import shutil
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from mascope_cli.cmd.demo import bundles
+from mascope_cli.runtime import runtime
+
+
+def _extract_archive(archive: Path, dest: Path) -> None:
+    """
+    Extract a ``.zip`` or ``.tar.gz`` archive into ``dest``.
+
+    The archive is expected to contain the bundle contents at its top level
+    (``manifest.json``, ``raw/``, ``snapshot/`` ...). If it instead wraps them in
+    a single top-level directory, that directory's contents are flattened into
+    ``dest`` so the layout is consistent regardless of how it was packed.
+
+    :param archive: Path to the downloaded archive.
+    :param dest: Target bundle directory (created/overwritten by the caller).
+    :raises ValueError: If the archive format is unsupported.
+    """
+    staging = dest.parent / f"{dest.name}.staging"
+    if staging.exists():
+        shutil.rmtree(staging)
+    staging.mkdir(parents=True)
+
+    if zipfile.is_zipfile(archive):
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(staging)
+    elif tarfile.is_tarfile(archive):
+        with tarfile.open(archive) as tf:
+            tf.extractall(staging)
+    else:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise ValueError(f"Unsupported archive format: {archive.name}")
+
+    # Flatten a single wrapping directory if present.
+    entries = list(staging.iterdir())
+    root = entries[0] if len(entries) == 1 and entries[0].is_dir() else staging
+
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.move(str(root), str(dest))
+    shutil.rmtree(staging, ignore_errors=True)
+
+
+def _download(url: str, dest: Path) -> None:
+    """
+    Stream a URL to a local file, logging coarse progress.
+
+    :param url: Source URL.
+    :param dest: Destination file path (parent created automatically).
+    :raises OSError: On network/IO failure (propagated from urllib).
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    runtime.logger.info(f"Downloading {url}")
+
+    with urllib.request.urlopen(url) as response:  # noqa: S310 - trusted Zenodo URL
+        total = int(response.headers.get("Content-Length", 0))
+        read = 0
+        next_mark = 10
+        with dest.open("wb") as out:
+            for chunk in iter(lambda: response.read(1 << 20), b""):
+                out.write(chunk)
+                read += len(chunk)
+                if total:
+                    pct = read * 100 // total
+                    if pct >= next_mark:
+                        runtime.logger.info(f"  ...{pct}%")
+                        next_mark = pct - (pct % 10) + 10
+
+
+def fetch(version: str | None = None, force: bool = False) -> Path:
+    """
+    Ensure a demo bundle is present and verified in the local cache.
+
+    If already cached and intact, returns immediately unless ``force`` is set.
+    Otherwise downloads the archive from the registered URL, extracts it, and
+    verifies every file against the manifest checksums.
+
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param force: Re-download even if a valid cached copy exists.
+    :raises RuntimeError: If the bundle has no published URL, the download
+                          fails, or checksum verification fails.
+    :return: Path to the verified bundle directory.
+    """
+    bundle = bundles.get_bundle(version)
+    dest = bundles.bundle_dir(version)
+
+    if bundles.is_cached(version) and not force:
+        problems = bundles.verify_manifest(version)
+        if not problems:
+            runtime.logger.success(f"Demo bundle '{bundle.version}' already cached")
+            return dest
+        runtime.logger.warning(
+            f"Cached bundle '{bundle.version}' failed verification; re-fetching"
+        )
+
+    if not bundle.url:
+        raise RuntimeError(
+            f"Demo bundle '{bundle.version}' has no published download URL yet. "
+            "Build one locally with 'mascope demo snapshot', or set its URL in "
+            "tooling/cli/src/mascope_cli/cmd/demo/bundles.py once published."
+        )
+
+    archive = bundles.cache_root() / f"{bundle.version}{_suffix(bundle.url)}"
+    _download(bundle.url, archive)
+
+    if bundle.archive_md5:
+        actual = bundles.md5_file(archive)
+        # Case-insensitive: hashlib emits lowercase, but a checksum pasted from
+        # Zenodo (or PowerShell's Get-FileHash) may be uppercase.
+        if actual.lower() != bundle.archive_md5.lower():
+            raise RuntimeError(
+                f"Archive checksum mismatch for '{bundle.version}': "
+                f"expected {bundle.archive_md5[:12]}..., got {actual[:12]}..."
+            )
+
+    runtime.logger.info("Extracting bundle...")
+    _extract_archive(archive, dest)
+    archive.unlink(missing_ok=True)
+
+    problems = bundles.verify_manifest(version)
+    if problems:
+        raise RuntimeError(
+            "Bundle verification failed after download:\n  - " + "\n  - ".join(problems)
+        )
+
+    runtime.logger.success(f"Demo bundle '{bundle.version}' fetched and verified")
+    return dest
+
+
+def _suffix(url: str) -> str:
+    """Return the archive suffix (``.zip`` or ``.tar.gz``) implied by a URL."""
+    lowered = url.lower()
+    if lowered.endswith(".tar.gz") or lowered.endswith(".tgz"):
+        return ".tar.gz"
+    return ".zip"

mascope_cli-2026.7.28/src/mascope_cli/cmd/demo/_rebuild.py

@@ -0,0 +1,148 @@
+"""
+Rebuild path: ingest the bundle's raw files through the real upload pipeline.
+
+Instead of dropping files into the file-converter's watch directory (which has
+no auth/context and never registers a file context), this uploads each raw file
+to the real ``/api/sample/files/upload`` endpoint - exactly what the File Agent
+does. The endpoint registers the file context (auth) and writes the file to
+``filestreams``, where the file-converter ingests it and runs the full
+``RawProcessor`` -> peak detection -> matching pipeline.
+
+Uploads are driven from a background thread because the app is launched in the
+foreground; the thread waits for the backend HTTP server, then uploads.
+"""
+
+import threading
+import time
+from pathlib import Path
+
+from mascope_cli.cmd.demo import bundles
+from mascope_cli.cmd.demo._seed import DEMO_ENV  # noqa: F401 - re-exported convenience
+from mascope_cli.runtime import runtime
+
+
+# The fixed file-agent token + service name the demo seeds (mirror
+# server seed_demo.DEMO_TOKENS["file-agent"]). Using the file-agent service
+# replicates the File Agent's exact upload request.
+_UPLOAD_TOKEN = "mascope_demo_file_agent_token"
+_UPLOAD_SERVICE = "file-agent"
+_UPLOAD_PATH = "sample/files/upload"
+
+
+def _raw_dir(version: str | None, source_dir: "Path | None") -> Path:
+    """Resolve the bundle's raw/ directory (published cache or local override)."""
+    root = Path(source_dir) if source_dir else bundles.bundle_dir(version)
+    src = root / "raw"
+    if not src.is_dir():
+        raise FileNotFoundError(f"No raw/ directory found at: {src}")
+    return src
+
+
+def _wait_for_backend(url: str, timeout: float = 300.0, poll: float = 2.0) -> bool:
+    """
+    Poll the backend until it serves HTTP.
+
+    Probes a public, always-present endpoint (the first-owner status route)
+    rather than the OpenAPI schema, which is disabled outside dev mode.
+
+    :param url: Backend base URL (e.g. ``http://localhost:8090``).
+    :param timeout: Max seconds to wait.
+    :param poll: Seconds between attempts.
+    :return: ``True`` once ready, ``False`` on timeout.
+    """
+    import requests
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            resp = requests.get(f"{url}/api/users/first-owner/status", timeout=5)
+            if resp.status_code == 200:
+                return True
+        except requests.RequestException:
+            pass
+        time.sleep(poll)
+    return False
+
+
+def upload_raw(version: str | None = None, source_dir: "Path | None" = None) -> int:
+    """
+    Upload the bundle's raw files to the real sample-file upload endpoint.
+
+    Replicates the File Agent's request (bearer ``file-agent`` token +
+    ``X-Service-Name: file-agent``) so the server registers context, stores the
+    file, and the converter ingests it.
+
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param source_dir: Local bundle directory override (see module docstring).
+    :return: Number of files successfully uploaded.
+    """
+    import mascope_sdk
+    from mascope_sdk import api_post_file
+    from mascope_sdk.exceptions import MascopeError
+
+    src = _raw_dir(version, source_dir)
+    url = f"http://localhost:{runtime.meta.api_port}"
+
+    # Match the File Agent's service header for the upload request.
+    mascope_sdk.SERVICE_NAME = _UPLOAD_SERVICE
+
+    raw_files = sorted(p for p in src.iterdir() if p.suffix.lower() == ".raw")
+    total = len(raw_files)
+    runtime.logger.info(f"Uploading {total} raw file(s) to {url}/api/{_UPLOAD_PATH}")
+
+    uploaded = 0
+    for i, raw in enumerate(raw_files, 1):
+        try:
+            api_post_file(
+                url=url,
+                path=_UPLOAD_PATH,
+                access_token=_UPLOAD_TOKEN,
+                filepath=str(raw),
+            )
+            uploaded += 1
+        except MascopeError as e:
+            runtime.logger.error(f"Upload of {raw.name} failed: {e}")
+        if i % 25 == 0 or i == total:
+            runtime.logger.info(f"  uploaded {uploaded}/{total}")
+
+    if uploaded == total:
+        runtime.logger.success(f"Uploaded all {total} raw file(s); ingestion proceeds")
+    else:
+        runtime.logger.warning(
+            f"Uploaded {uploaded}/{total} raw file(s); {total - uploaded} failed "
+            "(see errors above)"
+        )
+    return uploaded
+
+
+def upload_raw_deferred(
+    version: str | None = None, source_dir: "Path | None" = None
+) -> None:
+    """
+    Upload raw files once the backend is serving, from a background daemon thread.
+
+    The app is launched in the foreground, so this defers the uploads to a thread
+    that first waits for the backend HTTP server to come up.
+
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param source_dir: Local bundle directory override.
+    """
+
+    def _worker() -> None:
+        url = f"http://localhost:{runtime.meta.api_port}"
+        if not _wait_for_backend(url):
+            runtime.logger.error(
+                "Backend did not become ready in time; skipping raw upload. "
+                "Once it is up, re-run 'mascope demo --rebuild' or upload manually."
+            )
+            return
+        try:
+            upload_raw(version, source_dir=source_dir)
+        except Exception as e:  # noqa: BLE001 - background thread, just log
+            runtime.logger.error(f"Deferred raw upload failed: {e}")
+
+    threading.Thread(target=_worker, name="demo-upload-raw", daemon=True).start()
+    runtime.logger.info(
+        "Raw files will be uploaded to the server once the backend is ready; "
+        "ingestion then proceeds in the background."
+    )