mascope_cli 2026.7.28__py3-none-any.whl

mascope_cli/__init__.py

@@ -0,0 +1 @@
+

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/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/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/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/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/cmd/demo/__init__.py

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

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/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."
+    )

mascope_cli/cmd/demo/_seed.py

@@ -0,0 +1,170 @@
+"""
+Seed the demo runtime env from a cached bundle's database snapshot.
+
+This is the "instant" path: restore the pre-built ``pg_dump`` into the
+``mascope_demo`` database and copy the bundle's filestore tree into the demo
+env so the backend can serve the stored files. No instrument pipeline runs.
+
+The slower ``--rebuild`` path (ingest raw through the real file-converter) lives
+in ``_rebuild.py`` and is what the reproducibility test drives.
+"""
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+from mascope_cli.cmd.demo import bundles
+from mascope_cli.pg import dirs, drop_database, pg_restore
+from mascope_cli.runtime import runtime
+
+
+# The demo always uses a dedicated env so it never touches a developer's work.
+DEMO_ENV = "demo"
+_MODE = "dev"
+
+
+def env_dir(env: str = DEMO_ENV) -> Path:
+    """Return the runtime directory for an env (may not exist yet)."""
+    return Path(os.environ["MASCOPE_PATH"]) / ".runtime" / "env" / env
+
+
+def _resolve(version: str | None, source_dir: "Path | None") -> tuple[Path, dict]:
+    """Resolve the bundle root and load its manifest (published cache or local)."""
+    if source_dir:
+        root = Path(source_dir)
+        manifest_path = root / bundles.MANIFEST_NAME
+        if not manifest_path.is_file():
+            raise FileNotFoundError(
+                f"No {bundles.MANIFEST_NAME} in {root}. A snapshot restore needs a "
+                "built bundle; for a raw-only local directory use 'mascope demo "
+                "--rebuild --local <dir>'."
+            )
+        return root, json.loads(manifest_path.read_text(encoding="utf-8"))
+    return bundles.bundle_dir(version), bundles.load_manifest(version)
+
+
+def has_block(
+    block: str, version: str | None = None, source_dir: "Path | None" = None
+) -> bool:
+    """
+    Report whether a manifest block (``"seed"`` or ``"snapshot"``) is available.
+
+    Returns ``False`` (rather than raising) when there is no manifest - e.g. a
+    raw-only ``--local`` directory - so callers can fall back gracefully.
+
+    :param block: Manifest key, ``"seed"`` or ``"snapshot"``.
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param source_dir: Local bundle directory override.
+    :return: ``True`` if the block's dump exists on disk.
+    """
+    try:
+        root, manifest = _resolve(version, source_dir)
+    except FileNotFoundError:
+        return False
+    dump_rel = manifest.get(block, {}).get("dump")
+    return bool(dump_rel) and (root / dump_rel).is_file()
+
+
+def _restore_block(
+    block: str, version: str | None = None, source_dir: "Path | None" = None
+) -> None:
+    """
+    Restore a manifest dump block into the ``mascope_demo`` database.
+
+    Stages the dump into the dev backups directory (bind-mounted into the
+    PostgreSQL container), then drops/recreates the demo database and restores
+    into it. Assumes the dev PostgreSQL container is running and the demo env
+    exists.
+
+    :param block: Manifest key, ``"seed"`` (reference data) or ``"snapshot"``
+                  (full state).
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param source_dir: Local bundle directory override.
+    :raises FileNotFoundError: If the bundle or the block's dump is missing.
+    :raises RuntimeError: If the restore fails.
+    """
+    # Lazy import: keeps `mascope demo fetch` from pulling the dev.db graph.
+    from mascope_cli.cmd.dev.db import create_database
+
+    root, manifest = _resolve(version, source_dir)
+    dump_rel = manifest.get(block, {}).get("dump")
+    if not dump_rel:
+        raise FileNotFoundError(
+            f"Bundle manifest has no '{block}' dump. Build it with "
+            f"'mascope demo snapshot --{block if block == 'seed' else 'update'}'."
+        )
+
+    src_dump = root / dump_rel
+    if not src_dump.is_file():
+        raise FileNotFoundError(f"{block} dump not found: {src_dump}")
+
+    db_cfg = runtime.full_config.backend.database
+    container = db_cfg.get_postgres_container_name(mode=_MODE)
+    database = db_cfg.get_postgres_database_name(DEMO_ENV)
+
+    # Stage the dump where pg_restore expects it (bind-mounted backups dir).
+    backups_dir, mount = dirs(transfer=False, mode=_MODE)
+    backups_dir.mkdir(parents=True, exist_ok=True)
+    staged = backups_dir / src_dump.name
+    shutil.copy2(src_dump, staged)
+
+    try:
+        runtime.logger.info(f"Dropping and recreating '{database}'...")
+        drop_database(container, db_cfg.user, database)
+        if not create_database(DEMO_ENV):
+            raise RuntimeError(f"Failed to recreate database '{database}'")
+
+        runtime.logger.info(f"Restoring {block} into '{database}'...")
+        pg_restore(container, db_cfg.user, database, staged, mount)
+    finally:
+        staged.unlink(missing_ok=True)
+
+    runtime.logger.success(f"Demo database '{database}' restored from {block}")
+
+
+def restore_snapshot(
+    version: str | None = None, source_dir: "Path | None" = None
+) -> None:
+    """Restore the full ``snapshot`` dump (instant path). See :func:`_restore_block`."""
+    _restore_block("snapshot", version, source_dir)
+
+
+def restore_seed(version: str | None = None, source_dir: "Path | None" = None) -> None:
+    """
+    Restore the reference ``seed`` dump (ionization modes, instrument config,
+    calibration/diagnostic collections, demo user) before a rebuild ingests raw.
+    See :func:`_restore_block`.
+    """
+    _restore_block("seed", version, source_dir)
+
+
+def restore_filestore(
+    version: str | None = None, source_dir: "Path | None" = None
+) -> None:
+    """
+    Copy the bundle's filestore tree into the demo env's filestore directory.
+
+    Mirrors ``snapshot/filestore/`` from the bundle into
+    ``.runtime/env/demo/filestore/`` so the restored database rows resolve to
+    real files on disk. Existing demo filestore contents are replaced.
+
+    :param version: Bundle version tag. Defaults to the registry default.
+    :param source_dir: Local bundle directory to use instead of the published cache.
+    """
+    root, manifest = _resolve(version, source_dir)
+    snapshot = manifest.get("snapshot", {})
+    filestore_rel = snapshot.get("filestore", "snapshot/filestore")
+    src = root / filestore_rel
+
+    if not src.is_dir():
+        runtime.logger.warning(
+            f"Bundle has no filestore tree at {src}; skipping filestore restore"
+        )
+        return
+
+    dest = env_dir() / "filestore"
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+    runtime.logger.success(f"Demo filestore restored to {dest}")