gui: Add semantic version checks when downloading Unfurl Gui web app …

…releases.

Introduce UNFURL_GUI_DIST_URL and UNFURL_GUI_DIST_DIR environment variables.

docs/conf.py

@@ -5,15 +5,12 @@
 sys.path.insert(0, os.path.abspath(".."))
 import unfurl
 
-VERSION = unfurl.__version__()
-
-
 # -- Project information -----------------------------------------------------
 
 project = "Unfurl"
-copyright = "2025, OneCommons Co."
+copyright = "2024, OneCommons Co."
 author = "Adam Souzis"
-release = VERSION
+release = unfurl.semver_prerelease()
 
 # -- General configuration ---------------------------------------------------
 

docs/projects.rst

@@ -343,14 +343,14 @@ You can also use a cloudmap url like ``cloudmap:<package_id>``, which will resol
 
 ``<dest>`` is a file path. If ``<dest>`` already exists and is not inside an Unfurl project, clone will exit in error. If omitted, the destination name is derived from the source and created in the current directory. 
 
-Depending on the ``<source>``, use to clone to accomplish one of the following:
+Depending on the ``<source>``, use the clone command to accomplish one of the following:
 
 Clone a project
 ---------------
 
 If ``<source>`` points to a project, the project will be cloned.
 
-If the source project is a blueprint project (i.e. it doesn't contain any ensembles) a new ensemble will also be created (see below) in the cloned project -- use the ``--empty`` option to skip creating the new ensemble.
+If the source project is a blueprint project (i.e. it doesn't contain any ensembles) a new ensemble will also be created (`see below<Create a new ensemble from source>`) in the cloned project -- use the ``--empty`` option to skip creating the new ensemble.
 
 The exception to this is when source is also a local file path and ``<dest>`` is an existing project, in that case the source project will just be registered with the destination project instead of cloned, and a new ensemble will be created (see below). Use an URL like ``file:path/to/project`` as the source to force cloning.
 
@@ -372,7 +372,7 @@ Either scenario allows you to put local specific settings in a local or home pro
 Create a new project from a CSAR archive
 ----------------------------------------
 
-* ``<source>`` is a TOSCA Cloud Service Archive (CSAR) (a file path with a .csar or .zip extension) and ``<dest>`` isn't inside an existing project, a new Unfurl project will be created with the contents of the CSAR copied to the root of the project. A new ensemble will also created unless the ``--empty`` flag is used.
+* If ``<source>`` is a TOSCA Cloud Service Archive (CSAR) (a file path with a .csar or .zip extension) and ``<dest>`` isn't inside an existing project, a new Unfurl project will be created with the contents of the CSAR copied to the root of the project. A new ensemble will also created unless the ``--empty`` flag is used.
 
 Create a new ensemble from source
 ----------------------------------
@@ -384,7 +384,7 @@ A new ensemble is created when:
 * ``<source>`` is a blueprint project (ie. a project that contains no ensembles but does have an ``ensemble-template.yaml`` file) and the ``--empty`` flag wasn't used.
 * ``<source>`` is a TOSCA Cloud Service Archive (CSAR) (a file path with a .csar or .zip extension) and the ``--empty`` flag wasn't used.
 
-If ``dest`` is omitted or doesn't exist, the project that ``<source>`` is in will be cloned and the new ensemble created in the cloned project. If ``dest`` points to an existing project and ``<source>`` is a git url and not a local file path, the source repository will be cloned into the existing project.  If ``dest`` points to an existing project and ``<source>`` is a TOSCA Cloud Service Archive (CSAR) (a file path with a .csar or .zip extension), the contents of the CSAR will be copied to ensemble's directory.
+If ``dest`` is omitted or doesn't exist, the project that ``<source>`` is in will be cloned and the new ensemble created in the cloned project. If ``dest`` points to an existing project and ``<source>`` is a git url and not a local file path, the source repository will be cloned into the existing project.  If ``dest`` points to an existing project and ``<source>`` is a TOSCA Cloud Service Archive (CSAR) (a file path with a .csar or .zip extension), the contents of the CSAR will be copied to the ensemble's directory.
 
 Notes
 -----
@@ -407,6 +407,11 @@ Notes
 
 * This step can be skipped if your project is hosted on `Unfurl Cloud`_, clone will retrieve the value password from `Unfurl Cloud`_. 
 
+Browser-based Admin User Interface
+==================================
+
+.. automodule:: unfurl.server.gui
+
 Unfurl Home
 ===========
 

tests/test_server.py

@@ -205,6 +205,10 @@ def test_server_version(runner: Process):
     assert res.status_code == 200
     assert re.match(rb"^1\..+\+\w+$", res.content) is not None
 
+def test_gui_release():
+    assert re.match(gui.release_url_pattern, gui.RELEASE_URL).group(1) == gui.TAG
+    assert is_semver_compatible_with(gui.TAG, "v0.1.0-alpha.1")
+
 def test_server_authentication(runner: Process):
     res = requests.get("http://localhost:8090/health")
     assert res.status_code == 401

unfurl/__main__.py

@@ -1683,7 +1683,7 @@ def help(ctx, cmd=""):
     "--secret",
     envvar="UNFURL_SERVE_SECRET",
     show_envvar=True,
-    help="Secret required to access the server",
+    help='Require secret as Authorization: Bearer <secret> header or "secret" URL parameter.',
 )
 @click.option(
     "--clone-root",
@@ -1720,7 +1720,7 @@ def serve(
     gui,
     **options,
 ):
-    """Run Unfurl as a server."""
+    """Run Unfurl's built-in web server."""
     options.update(ctx.obj)
     # env vars need to set before importing serve
     if cors:

unfurl/packages.py

@@ -91,6 +91,15 @@ def is_semver(revision: Optional[str], include_unreleased=False) -> bool:
         and TOSCAVersionProperty.VERSION_RE.match(revision) is not None
     )
 
+def is_semver_compatible_with(expected: str, test: str) -> bool:
+    """
+    Return true if ``expected`` and ``test``'s major versions are equal and ``expected``'s minor version is less than or equal to ``test``'s minor version.
+    Raise an InvalidTOSCAVersionPropertyException if either ``expected`` or ``test`` doesn't match the semantic version syntax.
+    """
+    return TOSCAVersionProperty(expected).is_semver_compatible_with(
+        TOSCAVersionProperty(test)
+    )
+
 
 class Package_Url_Info(NamedTuple):
     package_id: Optional[str]

unfurl/server/cache.py

@@ -1,3 +1,5 @@
+# Copyright (c) 2023 Adam Souzis
+# SPDX-License-Identifier: MIT
 from typing import (
     Dict,
     List,