chore: add CI workflow and local development tooling

.github/workflows/run-paragon-plugin-tests.yml

@@ -0,0 +1,33 @@
+# Workflow dedicated to testing the tutor-contrib-paragon plugin only
+name: Test - tutor-contrib-paragon
+
+on:
+  pull_request:
+    paths:
+      # Trigger this workflow only if files change inside this plugin folder
+      - 'plugins/tutor-contrib-paragon/**'
+
+jobs:
+  test-paragon:
+    name: Run tests for tutor-contrib-paragon
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        # All steps will run from this directory
+        working-directory: plugins/tutor-contrib-paragon
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          make dev-requirements
+
+      - name: Run tests
+        run: make run-tests

plugins/tutor-contrib-paragon/.gitignore

@@ -0,0 +1,7 @@
+.*.swp
+!.gitignore
+TODO
+__pycache__
+*.egg-info/
+/build/
+/dist/

plugins/tutor-contrib-paragon/.hatch_build.py

@@ -0,0 +1,21 @@
+# https://hatch.pypa.io/latest/how-to/config/dynamic-metadata/
+
+import os
+import typing as t
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+HERE = os.path.dirname(__file__)
+
+
+class MetaDataHook(MetadataHookInterface):
+    def update(self, metadata: dict[str, t.Any]) -> None:
+        about = load_about()
+        metadata["version"] = about["__version__"]
+
+
+def load_about() -> dict[str, str]:
+    about: dict[str, str] = {}
+    with open(os.path.join(HERE, "tutorparagon", "__about__.py"), "rt", encoding="utf-8") as f:
+        exec(f.read(), about)  # pylint: disable=exec-used
+    return about

plugins/tutor-contrib-paragon/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tutorparagon/patches *
+recursive-include tutorparagon/templates *

plugins/tutor-contrib-paragon/Makefile

@@ -0,0 +1,36 @@
+.DEFAULT_GOAL := help
+.PHONY: docs
+SRC_DIRS = ./tutorparagon
+BLACK_OPTS = --exclude templates ${SRC_DIRS}
+
+# Warning: These checks are not necessarily run on every PR.
+test: test-lint test-types test-format  # Run some static checks.
+
+test-format: ## Run code formatting tests
+	black --check --diff $(BLACK_OPTS)
+
+test-lint: ## Run code linting tests
+	pylint --errors-only --enable=unused-import,unused-argument --ignore=templates --ignore=docs/_ext ${SRC_DIRS}
+
+test-types: ## Run type checks.
+	mypy --exclude=templates --ignore-missing-imports --implicit-reexport --strict ${SRC_DIRS}
+
+format: ## Format code automatically
+	black $(BLACK_OPTS)
+
+isort: ##  Sort imports. This target is not mandatory because the output may be incompatible with black formatting. Provided for convenience purposes.
+	isort --skip=templates ${SRC_DIRS}
+
+unittest: ## Run code tests cases
+	pytest tests
+
+dev-requirements: ## Install dev requirements
+	pip install -e .[dev]
+
+run-tests: test unittest  # Run static analysis and unit tests
+
+ESCAPE = 
+help: ## Print this help
+	@grep -E '^([a-zA-Z_-]+:.*?## .*|######* .+)$$' Makefile \
+		| sed 's/######* \(.*\)/@               $(ESCAPE)[1;31m\1$(ESCAPE)[0m/g' | tr '@' '\n' \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[33m%-30s\033[0m %s\n", $$1, $$2}'

plugins/tutor-contrib-paragon/README.rst

@@ -0,0 +1,63 @@
+Paragon plugin for `Tutor <https://docs.tutor.edly.io>`__
+###########################################################
+
+Facilitates the generation and static hosting of Paragon-based CSS themes for Open edX Micro-Frontend (MFE) applications using `Paragon <https://openedx.github.io/paragon/>`__.
+
+This plugin provides a local folder structure to manage theme source files and compile them into CSS, enabling flexible customization of Open edX MFEs via Tutor.
+
+Installation
+************
+
+.. code-block:: bash
+
+    pip install git+https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon
+
+For development:
+
+.. code-block:: bash
+
+    cd openedx-tutor-plugins/plugins/tutor-contrib-paragon
+    pip install -e .
+
+Enable the plugin:
+
+.. code-block:: bash
+
+    tutor plugins enable paragon
+
+Directory Structure
+*******************
+
+The plugin will create the following structure inside your Tutor environment:
+
+.. code-block::
+
+    tutor/env/plugins/paragon/
+    ├── theme-sources/           # Place your style dictionary folders here (e.g. theme-xyz/)
+    └── compiled-themes/         # Compiled CSS files go here, ready for static hosting
+
+Each theme inside `theme-sources/` should follow the Style Dictionary folder structure.
+Only themes listed in `PARAGON_ENABLED_THEMES` will be compiled.
+
+The `compiled-themes/` folder is designed to be exposed via static web servers such as **nginx** or **Caddy**, or can be uploaded to cloud hosting providers like **Amazon S3** or **Cloudflare Pages**.
+
+Configuration
+*************
+
+All configuration variables can be overridden via `tutor config save`:
+
+.. code-block:: yaml
+
+    PARAGON_THEME_SOURCES_PATH: "env/plugins/paragon/theme-sources"
+    PARAGON_COMPILED_THEMES_PATH: "env/plugins/paragon/compiled-themes"
+    PARAGON_ENABLED_THEMES:
+      - theme-1
+      - theme-2
+    PARAGON_SERVE_COMPILED_THEMES: true
+
+You may customize paths or theme names to suit your deployment.
+
+License
+*******
+
+This software is licensed under the terms of the AGPLv3.

plugins/tutor-contrib-paragon/pyproject.toml

@@ -0,0 +1,62 @@
+# https://packaging.python.org/en/latest/tutorials/packaging-projects/
+# https://hatch.pypa.io/latest/config/build/
+
+[project]
+name = "tutor-contrib-paragon"
+description = "Facilitates the generation and static hosting of Paragon-based theme CSS files for Open edX MFEs using Tutor."
+authors = [
+  { name = "Alejandro Cardenas"},
+  { email = "[email protected]" },
+]
+license = { text = "AGPL-3.0-only" }
+
+readme = {file = "README.rst", content-type = "text/x-rst"}
+requires-python = ">= 3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+
+]
+dependencies = [
+    "tutor>=19.0.0,<20.0.0",
+]
+
+optional-dependencies = { dev = ["tutor[dev]>=19.0.0,<20.0.0", "pytest>=8.3.4"] }
+
+# These fields will be set by hatch_build.py
+dynamic = ["version"]
+
+# https://packaging.python.org/en/latest/specifications/well-known-project-urls/#well-known-labels
+[project.urls]
+Documentation = "https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon#readme"
+Issues = "https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon/issues"
+Source = "https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# hatch-specific configuration
+[tool.hatch.metadata.hooks.custom]
+path = ".hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tutorparagon"]
+
+[tool.hatch.build.targets.sdist]
+# Disable strict naming, otherwise twine is not able to detect name/version
+strict-naming = false
+include = [ "/tutorparagon", ".hatch_build.py"]
+exclude = ["tests*"]
+
+[project.entry-points."tutor.plugin.v1"]
+paragon = "tutorparagon.plugin"

plugins/tutor-contrib-paragon/tests/check_version_test.py

@@ -0,0 +1,10 @@
+"""
+Tutor paragon plugin tests
+"""
+
+from tutorparagon import __about__
+
+def test_version_exists():
+    assert hasattr(__about__, "__version__")
+    assert isinstance(__about__.__version__, str)
+    assert __about__.__version__ != ""

plugins/tutor-contrib-paragon/tutorparagon/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

plugins/tutor-contrib-paragon/tutorparagon/plugin.py

@@ -0,0 +1,94 @@
+import os
+from glob import glob
+
+import click
+import importlib_resources
+from tutor import hooks
+from tutor import config as tutor_config
+
+from .__about__ import __version__
+
+########################################
+# CONFIGURATION
+########################################
+
+hooks.Filters.CONFIG_DEFAULTS.add_items(
+    [
+        # Plugin version (used for compatibility or debugging)
+        ("PARAGON_VERSION", __version__),
+        # Directory where users will place style-dictionary source files
+        # Each subfolder inside will represent a theme (e.g., "theme-abc/")
+        ("PARAGON_THEME_SOURCES_PATH", "env/plugins/paragon/theme-sources"),
+        # Directory where compiled CSS themes will be stored after transformation
+        # One subfolder per compiled theme (e.g., "theme-abc/core.min.css")
+        ("PARAGON_COMPILED_THEMES_PATH", "env/plugins/paragon/compiled-themes"),
+        # List of enabled themes to compile and serve
+        # Only themes listed here will be processed, even if others exist in sources
+        ("PARAGON_ENABLED_THEMES", []),
+        # Whether Tutor should expose the compiled themes to be served (e.g. via nginx, cady or static server)
+        ("PARAGON_SERVE_COMPILED_THEMES", True),
+    ]
+)
+
+
+# Create directories for build and host
+@hooks.Actions.PROJECT_ROOT_READY.add()
+def create_paragon_folders(project_root: str) -> None:
+    config = tutor_config.load(project_root)
+
+    # Paths from config (always have defaults)
+    theme_sources_path = os.path.join(
+        project_root, str(config["PARAGON_THEME_SOURCES_PATH"])
+    )
+    compiled_themes_path = os.path.join(
+        project_root, str(config["PARAGON_COMPILED_THEMES_PATH"])
+    )
+
+    for path, label in [
+        (theme_sources_path, "Theme Shources"),
+        (compiled_themes_path, "Compiled Themes"),
+    ]:
+        if os.path.exists(path):
+            print(f"[paragon] {label} folder already exists at: {path}")
+        else:
+            os.makedirs(path, exist_ok=True)
+            print(f"[paragon] Created {label} folder at: {path}")
+
+
+########################################
+# TEMPLATE RENDERING
+# (It is safe & recommended to leave
+#  this section as-is :)
+########################################
+
+hooks.Filters.ENV_TEMPLATE_ROOTS.add_items(
+    # Root paths for template files, relative to the project root.
+    [
+        str(importlib_resources.files("tutorparagon") / "templates"),
+    ]
+)
+
+hooks.Filters.ENV_TEMPLATE_TARGETS.add_items(
+    # For each pair (source_path, destination_path):
+    # templates at ``source_path`` (relative to your ENV_TEMPLATE_ROOTS) will be
+    # rendered to ``source_path/destination_path`` (relative to your Tutor environment).
+    # For example, ``tutorparagon/templates/paragon/build``
+    # will be rendered to ``$(tutor config printroot)/env/plugins/paragon/build``.
+    [
+        ("paragon/build", "plugins"),
+        ("paragon/apps", "plugins"),
+    ],
+)
+
+
+########################################
+# PATCH LOADING
+# (It is safe & recommended to leave
+#  this section as-is :)
+########################################
+
+# For each file in tutorparagon/patches,
+# apply a patch based on the file's name and contents.
+for path in glob(str(importlib_resources.files("tutorparagon") / "patches" / "*")):
+    with open(path, encoding="utf-8") as patch_file:
+        hooks.Filters.ENV_PATCHES.add_item((os.path.basename(path), patch_file.read()))