uptimely-core 0.1.0.dev0__tar.gz → 0.2.0.dev1__tar.gz

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: uptimely-core
-Version: 0.1.0.dev0
-Summary: Declarative numerical analytics with complex dependencies at scale
+Version: 0.2.0.dev1
+Summary: Manage data-driven numerical analytics with complex dependencies at scale
 License-Expression: MIT
 License-File: LICENSE
 Keywords: analytics,declarative,industrial,feature-engineering,polars
@@ -24,15 +24,18 @@ Requires-Dist: numpy (>=1.26,<3.0)
 Requires-Dist: polars (>=1.0,<2.0)
 Requires-Dist: pydantic (>=2.10,<3.0)
 Project-URL: Documentation, https://uptimely-ai.github.io/uptimely-core
-Project-URL: Homepage, https://github.com/uptimely-ai/uptimely-core
+Project-URL: Homepage, http://uptimely.ai/core/
 Project-URL: Repository, https://github.com/uptimely-ai/uptimely-core
 Description-Content-Type: text/markdown
 
 # Uptimely Core
 
-Uptimely Core is an open source Python package for declarative numerical analytics with complex dependencies at scale.
+Uptimely Core is an open source Python package for declarative numerical
+analytics with complex dependencies at scale.
 
-It describes analytics workflows in a specification similar to OpenAPI, uses a declarative model inspired by Kubernetes. The framework generates plans, graphs, and documentation from that specification.
+Analytics definitions describe workflows in JSON, using a declarative model
+inspired by OpenAPI and Kubernetes. The compiler generates plans from the
+analytics; the package can also render dependency graphs and documentation.
 
 Ships with simple engine and plans to integrate to common execution backends.
 
@@ -53,15 +56,29 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 
 ## Quick start
 
-Install the package, download examples and run.
+Python 3.13 or newer is required. Install the package, download the examples
+and run.
+
+With pip:
 
 ```sh
 pip install uptimely-core
-uptimely examples download
-python examples/run_all.py
+uptimely examples download --output examples
+uptimely project build --project-root examples/pump_analytics
+uptimely engine run --project-root examples/pump_analytics
+uptimely explorer serve --project-root examples/pump_analytics
+```
+
+With Poetry, from your Poetry project:
+
+```sh
+poetry add uptimely-core
+poetry run uptimely examples download --output examples
+poetry run uptimely project build --project-root examples/pump_analytics
+poetry run uptimely engine run --project-root examples/pump_analytics
+poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 
@@ -74,7 +91,7 @@ Explore the [documentation site](https://uptimely-ai.github.io/uptimely-core/).
 | [`docs/`](docs/index.md) | Architecture, specification, and development documentation. |
 | [`examples/`](examples/README.md) | Runnable examples and generated artifacts. |
 | [`scripts/`](scripts) | Code snippets for repository management |
-| [`src/uptimely/`](src/uptimely/) | Package implementation for specifications, compilation, dependencies, documentation, and engine. |
+| [`src/uptimely/`](src/uptimely/) | Package implementation for analytics, compilation, dependencies, documentation, and execution. |
 | [`tests/`](tests/) | Automated tests for the package and examples. |
 
 ## Development

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "uptimely-core"
-version = "0.1.0.dev0"
-description = "Declarative numerical analytics with complex dependencies at scale"
+version = "0.2.0.dev1"
+description = "Manage data-driven numerical analytics with complex dependencies at scale"
 authors = [{ name = "Mikael Ahonen", email = "mikael.ahonen@uptimely.ai" }]
 license = "MIT"
 license-files = ["LICENSE"]
@@ -39,12 +39,12 @@ uptimely = "uptimely.cli.cli:main"
 uptimely-mcp = "uptimely.mcp.server:main"
 
 [project.urls]
-Homepage = "https://github.com/uptimely-ai/uptimely-core"
+Homepage = "http://uptimely.ai/core/"
 Repository = "https://github.com/uptimely-ai/uptimely-core"
 Documentation = "https://uptimely-ai.github.io/uptimely-core"
 
 [dependency-groups]
-test = ["pytest>=8.0", "pytest-cov>=5.0"]
+test = ["pytest>=8.0", "pytest-cov>=5.0", "pytest-xdist (>=3.6,<4.0)"]
 dev = ["pre-commit>=3.0", "ruff>=0.8"]
 docs = ["mkdocs>=1.6,<2.0", "mkdocs-material>=9.7,<10.0", "mkdocstrings[python]>=1.0,<2.0"]
 
@@ -68,7 +68,7 @@ convention = "google"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--strict-markers --strict-config"
+addopts = "--strict-markers --strict-config -n 4"
 markers = [
   "integration: end-to-end tests using example projects",
 ]

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev1}/readme.md

@@ -1,8 +1,11 @@
 # Uptimely Core
 
-Uptimely Core is an open source Python package for declarative numerical analytics with complex dependencies at scale.
+Uptimely Core is an open source Python package for declarative numerical
+analytics with complex dependencies at scale.
 
-It describes analytics workflows in a specification similar to OpenAPI, uses a declarative model inspired by Kubernetes. The framework generates plans, graphs, and documentation from that specification.
+Analytics definitions describe workflows in JSON, using a declarative model
+inspired by OpenAPI and Kubernetes. The compiler generates plans from the
+analytics; the package can also render dependency graphs and documentation.
 
 Ships with simple engine and plans to integrate to common execution backends.
 
@@ -23,15 +26,29 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 
 ## Quick start
 
-Install the package, download examples and run.
+Python 3.13 or newer is required. Install the package, download the examples
+and run.
+
+With pip:
 
 ```sh
 pip install uptimely-core
-uptimely examples download
-python examples/run_all.py
+uptimely examples download --output examples
+uptimely project build --project-root examples/pump_analytics
+uptimely engine run --project-root examples/pump_analytics
+uptimely explorer serve --project-root examples/pump_analytics
+```
+
+With Poetry, from your Poetry project:
+
+```sh
+poetry add uptimely-core
+poetry run uptimely examples download --output examples
+poetry run uptimely project build --project-root examples/pump_analytics
+poetry run uptimely engine run --project-root examples/pump_analytics
+poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 
@@ -44,7 +61,7 @@ Explore the [documentation site](https://uptimely-ai.github.io/uptimely-core/).
 | [`docs/`](docs/index.md) | Architecture, specification, and development documentation. |
 | [`examples/`](examples/README.md) | Runnable examples and generated artifacts. |
 | [`scripts/`](scripts) | Code snippets for repository management |
-| [`src/uptimely/`](src/uptimely/) | Package implementation for specifications, compilation, dependencies, documentation, and engine. |
+| [`src/uptimely/`](src/uptimely/) | Package implementation for analytics, compilation, dependencies, documentation, and execution. |
 | [`tests/`](tests/) | Automated tests for the package and examples. |
 
 ## Development

uptimely_core-0.2.0.dev1/src/uptimely/__init__.py

@@ -0,0 +1,40 @@
+"""Public package namespace for uptimely."""
+
+from .compiler import CallableGraph, CallableNode, Compiler, ExecutionPlan
+from .engine import Engine
+from .spec import (
+    Call,
+    Dimension,
+    Entity,
+    FeatureGraph,
+    Function,
+    PreparedSpec,
+    PythonSpec,
+    Spec,
+    SubGraph,
+    from_python,
+    load_spec,
+    prepare_spec,
+    write_document,
+)
+
+__all__ = [
+    "Spec",
+    "Call",
+    "CallableGraph",
+    "CallableNode",
+    "Compiler",
+    "Dimension",
+    "Entity",
+    "ExecutionPlan",
+    "Function",
+    "PythonSpec",
+    "PreparedSpec",
+    "from_python",
+    "load_spec",
+    "prepare_spec",
+    "write_document",
+    "SubGraph",
+    "FeatureGraph",
+    "Engine",
+]

uptimely_core-0.2.0.dev1/src/uptimely/cli/cli.py

@@ -0,0 +1,38 @@
+"""Entry point for the Uptimely command-line interface."""
+
+import argparse
+
+from uptimely.cli import engine, examples, explorer, project, spec
+
+download_examples = examples.download_examples
+serve_explorer = explorer.serve_explorer
+
+
+def main() -> None:
+    """Run the Uptimely command-line interface."""
+    parser = argparse.ArgumentParser(prog="uptimely")
+    commands = parser.add_subparsers(dest="command", required=True)
+    examples.configure_parser(commands.add_parser("examples", help="Manage example projects"))
+    explorer.configure_parser(
+        commands.add_parser("explorer", help="Explore spec, lineage, and execution plans")
+    )
+    spec.configure_parser(
+        commands.add_parser("spec", help="Inspect specs and feature dependencies")
+    )
+    project.configure_parser(commands.add_parser("project", help="Build project resources"))
+    engine.configure_parser(commands.add_parser("engine", help="Run analytics workflows"))
+    args = parser.parse_args()
+    if args.command == "examples":
+        examples.run(args, parser)
+    elif args.command == "explorer":
+        explorer.run(args, parser)
+    elif args.command == "spec":
+        spec.run(args, parser)
+    elif args.command == "project":
+        project.run(args, parser)
+    else:
+        engine.run(args, parser)
+
+
+if __name__ == "__main__":
+    main()

uptimely_core-0.2.0.dev1/src/uptimely/cli/common.py

@@ -0,0 +1,38 @@
+"""Shared project paths and spec loading for CLI commands."""
+
+import argparse
+import pathlib
+
+from uptimely import spec
+from uptimely.project.build import prepare_project_root
+
+
+def configure_project_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add spec, import-root, feature-selection, and diagnostic options."""
+    parser.add_argument(
+        "--spec",
+        type=pathlib.Path,
+        help="Spec JSON to inspect (default: spec from the active project build)",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Root for importing function entrypoints and resolving default paths",
+    )
+    parser.add_argument(
+        "--features", nargs="+", help="Select output features and their dependencies"
+    )
+    parser.add_argument("--verbose", action="store_true", help="Print diagnostic details")
+
+
+def project_path(
+    path: pathlib.Path | None, project_root: pathlib.Path | None, default: pathlib.Path
+) -> pathlib.Path:
+    """Resolve a default beneath the project root, preserving explicit paths."""
+    return path if path is not None else (project_root or pathlib.Path()) / default
+
+
+def load_spec(path: pathlib.Path, project_root: pathlib.Path) -> spec.Spec:
+    """Load a spec document with project functions on the import path."""
+    prepare_project_root(project_root)
+    return spec.load_spec(path)

uptimely_core-0.2.0.dev1/src/uptimely/cli/engine.py

@@ -0,0 +1,83 @@
+"""Command-line tools for executing analytics workflows."""
+
+import argparse
+import pathlib
+import typing
+
+import pydantic
+
+from uptimely import engine as engine_module
+from uptimely import project
+from uptimely.cli import common, plan
+
+
+class EngineSettings(pydantic.BaseModel):
+    """Validated engine.json backend configuration and runtime bindings."""
+
+    model_config = pydantic.ConfigDict(extra="forbid")
+
+    backend: engine_module.EngineConfig = pydantic.Field(default_factory=engine_module.EngineConfig)
+    bind: dict[str, dict[str, dict[str, typing.Any]]] = pydantic.Field(default_factory=dict)
+
+
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure the engine run action."""
+    actions = parser.add_subparsers(dest="action", required=True)
+    execute = actions.add_parser("run", help="Execute the active project's saved build")
+    execute.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Project root containing the active build and function entrypoints",
+    )
+    execute.add_argument(
+        "--verbose", action="store_true", help="Print execution stages and dataset details"
+    )
+    execute.add_argument(
+        "--config",
+        type=pathlib.Path,
+        help=(
+            "Backend settings and runtime bindings "
+            f"(default: {project.ENGINE_CONFIG_FILE} under --project-root)"
+        ),
+    )
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Execute the active saved plan and report failures explicitly."""
+    root = args.project_root or pathlib.Path.cwd()
+    config = common.project_path(args.config, args.project_root, project.ENGINE_CONFIG_FILE)
+    try:
+        common.prepare_project_root(root)
+        with project.read_build_bundle(root) as bundle:
+            settings = EngineSettings.model_validate_json(config.read_text(encoding="utf-8"))
+            execution_plan = bundle.execution_plan
+            result = engine_module.Engine(
+                execution_plan, config=settings.backend, bind=settings.bind
+            ).execute()
+            if result.failures:
+                failures = "; ".join(result.failures.values())
+                raise RuntimeError(f"Engine flow failed: {failures}")
+    except (OSError, ValueError, ImportError, AttributeError, TypeError, RuntimeError) as error:
+        parser.exit(1, f"uptimely: error: {error}\n")
+    calculated_features = sorted({feature_id for _, _, feature_id in result.calculated_outputs})
+    scope = (
+        "all features"
+        if bundle.manifest.features is None
+        else f"selected features: {', '.join(bundle.manifest.features)}"
+    )
+    print("Engine completed the flow")
+    print(f"Build scope: {scope}")
+    print(f"{len(execution_plan.callables)} callables")
+    print("Calculated features: " + ", ".join(calculated_features))
+    if args.verbose:
+        plan.print_stages(execution_plan)
+        print("\nDataset registry")
+        datasets = execution_plan.plan.resources.get("datasets", {})
+        for entity_id, dataset_id in dict.fromkeys(
+            (callable.entity_id, callable.dataset_id) for callable in execution_plan.callables
+        ):
+            dataset = datasets.get(dataset_id)
+            if dataset is None:
+                print(f"Dataset({entity_id}, {dataset_id}): feature metadata unavailable")
+                continue
+            print(f"Dataset({entity_id}, {dataset_id}): {len(dataset['features'])} features")

uptimely_core-0.1.0.dev0/src/uptimely/cli/cli.py → uptimely_core-0.2.0.dev1/src/uptimely/cli/examples.py

@@ -1,33 +1,36 @@
-"""Command-line tools for working with Uptimely."""
+"""Command-line tools for downloading example projects."""
 
 import argparse
+import pathlib
 import re
 import shutil
 import stat
-from http.client import HTTPException
-from importlib.metadata import PackageNotFoundError, metadata
-from pathlib import Path
-from tempfile import TemporaryDirectory, TemporaryFile
-from urllib.error import URLError
-from urllib.parse import quote, urlsplit
-from urllib.request import urlopen
-from zipfile import BadZipFile, ZipFile
+import tempfile
+import zipfile
+from http import client
+from importlib import metadata
+from urllib import error as urllib_error
+from urllib import parse, request
 
 EXAMPLES_FOLDER: str = "examples"
+DISTRIBUTION_NAME: str = "uptimely-core"
+RELEASE_TAG_PREFIX: str = "v"
+EXAMPLES_DOWNLOAD_TIMEOUT: int = 30
+TEMPORARY_DIRECTORY_PREFIX: str = ".uptimely-"
 
 
 def _repository_url() -> str:
     """Read the repository URL from the installed distribution metadata."""
-    for entry in metadata("uptimely-core").get_all("Project-URL", []):
+    for entry in metadata.metadata(DISTRIBUTION_NAME).get_all("Project-URL", []):
         label, separator, url = entry.partition(",")
         if separator and label.strip().lower() == "repository":
             return url.strip()
-    raise ValueError("Installed uptimely-core metadata has no Repository URL")
+    raise ValueError(f"Installed {DISTRIBUTION_NAME} metadata has no Repository URL")
 
 
 def _archive_url(repository: str, ref: str) -> str:
     """Build a GitHub archive URL for a repository and revision."""
-    parsed = urlsplit(repository)
+    parsed = parse.urlsplit(repository)
     match = re.fullmatch(r"/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?", parsed.path)
     if (
         parsed.scheme != "https"
@@ -40,10 +43,10 @@ def _archive_url(repository: str, ref: str) -> str:
     if not ref.strip():
         raise ValueError("The Git revision must not be empty")
     owner, name = match.groups()
-    return f"https://codeload.github.com/{owner}/{name}/zip/{quote(ref, safe='')}"
+    return f"https://codeload.github.com/{owner}/{name}/zip/{parse.quote(ref, safe='')}"
 
 
-def _extract_examples(archive: ZipFile, destination: Path) -> None:
+def _extract_examples(archive: zipfile.ZipFile, destination: pathlib.Path) -> None:
     """Copy regular files under EXAMPLES_FOLDER relative to the repository root."""
     source_parts = EXAMPLES_FOLDER.split("/")
     prefix_length = 1 + len(source_parts)
@@ -73,12 +76,14 @@ def _extract_examples(archive: ZipFile, destination: Path) -> None:
         raise ValueError("The repository archive contains no example files")
 
 
-def download_examples(output: Path, ref: str = "HEAD") -> Path:
+def download_examples(output: pathlib.Path, ref: str | None = None) -> pathlib.Path:
     """Download the public repository's examples into a new directory.
 
     Args:
         output: Destination for the contents of the repository's examples directory.
-        ref: GitHub branch, tag, or commit. HEAD selects the default branch.
+        ref: GitHub branch, tag, or commit. If omitted, use the release tag
+            matching the installed package version (v<version>).
+            Explicit HEAD selects the default branch.
 
     Returns:
         Absolute path to the downloaded examples.
@@ -86,7 +91,8 @@ def download_examples(output: Path, ref: str = "HEAD") -> Path:
     Raises:
         FileExistsError: The destination already exists.
         PackageNotFoundError: The distribution metadata is not installed.
-        ValueError: Repository metadata, revision, or archive entries are invalid.
+        ValueError: Repository metadata, revision, or archive entries are invalid,
+            or the matching release tag is unavailable.
         URLError: GitHub cannot be reached or rejects the download.
         BadZipFile: The downloaded archive is invalid.
         OSError: The files cannot be written.
@@ -94,16 +100,27 @@ def download_examples(output: Path, ref: str = "HEAD") -> Path:
     output = output.absolute()
     if output.exists() or output.is_symlink():
         raise FileExistsError(f"Destination already exists: {output}")
-    url = _archive_url(_repository_url(), ref)
+    revision = f"{RELEASE_TAG_PREFIX}{metadata.version(DISTRIBUTION_NAME)}" if ref is None else ref
+    url = _archive_url(_repository_url(), revision)
     output.parent.mkdir(parents=True, exist_ok=True)
-    with TemporaryDirectory(prefix=".uptimely-", dir=output.parent) as temporary:
-        staging = Path(temporary) / "examples"
+    with tempfile.TemporaryDirectory(
+        prefix=TEMPORARY_DIRECTORY_PREFIX, dir=output.parent
+    ) as temporary:
+        staging = pathlib.Path(temporary) / "examples"
         staging.mkdir()
-        with TemporaryFile() as downloaded:
-            with urlopen(url, timeout=30) as response:
-                shutil.copyfileobj(response, downloaded)
+        with tempfile.TemporaryFile() as downloaded:
+            try:
+                with request.urlopen(url, timeout=EXAMPLES_DOWNLOAD_TIMEOUT) as response:
+                    shutil.copyfileobj(response, downloaded)
+            except urllib_error.HTTPError as error:
+                if error.code == 404 and ref is None:
+                    raise ValueError(
+                        f"Matching examples release tag {revision!r} is unavailable. "
+                        "Use --ref to select a revision compatible with your installed package."
+                    ) from error
+                raise
             downloaded.seek(0)
-            with ZipFile(downloaded) as archive:
+            with zipfile.ZipFile(downloaded) as archive:
                 _extract_examples(archive, staging)
         if output.exists() or output.is_symlink():
             raise FileExistsError(f"Destination already exists: {output}")
@@ -111,38 +128,33 @@ def download_examples(output: Path, ref: str = "HEAD") -> Path:
     return output
 
 
-def main() -> None:
-    """Run the Uptimely command-line interface."""
-    parser = argparse.ArgumentParser(prog="uptimely")
-    commands = parser.add_subparsers(dest="command", required=True)
-    examples = commands.add_parser("examples", help="Manage example projects")
-    actions = examples.add_subparsers(dest="action", required=True)
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure the examples command and its download action."""
+    actions = parser.add_subparsers(dest="action", required=True)
     download = actions.add_parser("download", help="Download examples from public GitHub")
     download.add_argument(
         "--output",
-        type=Path,
-        default=Path("examples"),
+        type=pathlib.Path,
+        default=pathlib.Path("examples"),
         help="Destination directory (default: examples)",
     )
     download.add_argument(
         "--ref",
-        default="HEAD",
-        help="Branch, tag, or commit (default: the repository's default branch)",
+        help="Branch, tag, or commit (default: v<installed package version>)",
     )
-    args = parser.parse_args()
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Download examples using parsed command-line arguments."""
     try:
         destination = download_examples(args.output, args.ref)
     except (
         OSError,
-        URLError,
-        HTTPException,
-        BadZipFile,
+        urllib_error.URLError,
+        client.HTTPException,
+        zipfile.BadZipFile,
         ValueError,
-        PackageNotFoundError,
+        metadata.PackageNotFoundError,
     ) as error:
         parser.exit(1, f"uptimely: error: {error}\n")
     print(f"Downloaded examples to {destination}")
-
-
-if __name__ == "__main__":
-    main()

uptimely_core-0.2.0.dev1/src/uptimely/cli/explorer.py

@@ -0,0 +1,92 @@
+"""Command-line tools for building and serving the analytics explorer."""
+
+import argparse
+import functools
+import pathlib
+from http import server as http_server
+
+from uptimely import project
+
+
+def serve_explorer(
+    directory: pathlib.Path,
+    host: str = "127.0.0.1",
+    port: int = 8001,
+    scope: str = "all features",
+) -> None:
+    """Serve a saved analytics explorer website for local preview.
+
+    Args:
+        directory: Saved website directory containing an index.html file.
+        host: Address to bind; defaults to localhost.
+        port: TCP port; defaults to 8001. Zero selects an available port.
+        scope: Human-readable scope of the saved execution plan.
+
+    Raises:
+        NotADirectoryError: The website directory does not exist or is not a directory.
+        FileNotFoundError: The website index is missing.
+        ValueError: The port is outside the valid TCP range.
+        OSError: The server cannot bind to the requested address.
+    """
+    directory = directory.resolve()
+    if not directory.is_dir():
+        raise NotADirectoryError(f"Website directory does not exist: {directory}")
+    index = directory / project.EXPLORER_INDEX_FILE.name
+    if not index.is_file():
+        raise FileNotFoundError(
+            f"Website index not found: {index}. Generate it with 'uptimely project build'."
+        )
+    if not 0 <= port <= 65535:
+        raise ValueError("Port must be between 0 and 65535.")
+    handler = functools.partial(http_server.SimpleHTTPRequestHandler, directory=str(directory))
+    with http_server.ThreadingHTTPServer((host, port), handler) as server:
+        print(
+            f"Serving analytics explorer from {directory} at "
+            f"http://{host}:{server.server_port}/ (build scope: {scope}; Ctrl+C to stop)",
+            flush=True,
+        )
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            print("\nSpec explorer server stopped.")
+
+
+def _port(value: str) -> int:
+    """Parse a valid TCP port for the CLI."""
+    try:
+        port = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("Port must be an integer.") from error
+    if not 0 <= port <= 65535:
+        raise argparse.ArgumentTypeError("Port must be between 0 and 65535.")
+    return port
+
+
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure the Explorer serve action."""
+    actions = parser.add_subparsers(dest="action", required=True)
+    serve = actions.add_parser("serve", help="Serve the active build's saved website")
+    serve.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Project root containing the active build",
+    )
+    serve.add_argument("--host", default="127.0.0.1", help="Bind address (default: 127.0.0.1)")
+    serve.add_argument(
+        "--port", type=_port, default=8001, help="TCP port (default: 8001; 0 selects a free port)"
+    )
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Serve the active build's validated, saved Explorer website."""
+    project_root = (args.project_root or pathlib.Path.cwd()).resolve()
+    try:
+        with project.read_build_bundle(project_root) as bundle:
+            scope = (
+                "all features"
+                if bundle.manifest.features is None
+                else f"selected features: {', '.join(bundle.manifest.features)}"
+            )
+            serve_explorer(bundle.explorer_path, args.host, args.port, scope)
+    except (OSError, ValueError, RuntimeError) as error:
+        parser.exit(1, f"uptimely: error: {error}\n")

uptimely_core-0.2.0.dev1/src/uptimely/cli/plan.py

@@ -0,0 +1,18 @@
+"""Display execution plan stages in the CLI."""
+
+from uptimely.compiler import plan as plan_module
+
+
+def print_stages(plan: plan_module.ExecutionPlan) -> None:
+    """Print execution stages and their function dependencies."""
+    callables_by_id = {callable.id: callable for callable in plan.callables}
+    print("\nExecution stages")
+    for stage_number, stage in enumerate(plan.execution_stages, 1):
+        print(f"Stage {stage_number}")
+        for callable in stage:
+            dependencies = [
+                callables_by_id[dependency_id].function_id
+                for dependency_id in callable.dependency_ids
+            ]
+            suffix = f" <- [{', '.join(dependencies)}]" if dependencies else ""
+            print(f"  {callable.function_id}({callable.entity_id}) -> {callable.output}{suffix}")