feat: add Paragon build-tokens command using tutor custom jobs

.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,166 @@
+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 **design token-based theme source files** (see `Paragon Design Tokens <https://github.com/openedx/paragon/?tab=readme-ov-file#design-tokens>`__) 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 Paragon-based theme folders here (e.g., theme-xyz/)
+    └── compiled-themes/         # Output CSS files are generated here and ready for static hosting
+
+Only themes listed in `PARAGON_ENABLED_THEMES` will be compiled.
+
+Themes placed in `theme-sources/` are compiled into CSS using `Paragon's theme build process <https://github.com/openedx/paragon/?tab=readme-ov-file#paragon-cli>`_. The resulting CSS files in `compiled-themes/` are intended to be served statically and can be linked using the `PARAGON_THEME_URLS` setting.
+
+This structure is optimized for design token–based themes (see `Paragon Design Tokens <https://github.com/openedx/paragon/?tab=readme-ov-file#design-tokens>`__), but it is also flexible. If site operators need to include small amounts of additional CSS (not handled via tokens), we recommend doing so via extensions in the theme source directory, so they are included during the Paragon build—rather than manually editing the compiled output.
+
+.. note::
+
+   A link to the official Open edX or Paragon documentation will be added here once it is published.
+
+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
+    PARAGON_BUILDER_IMAGE: "paragon-builder:latest"
+
+You may customize paths or theme names to suit your deployment.
+
+Usage
+*****
+
+Prerequisites
+-------------
+
+- A built Paragon CLI image:
+
+  .. code-block:: bash
+
+      tutor images build paragon-builder
+
+- A theme source directory structured as follows:
+
+  .. code-block:: text
+
+      theme-sources/
+      ├── core/
+      │   └── ... (token files)
+      └── themes/
+          ├── light/     # example theme variant
+          │   └── ... (light theme token files)
+          └── dark/      # example theme variant
+          └── ... (dark theme token files)
+
+  In this structure:
+
+  - The ``core/`` directory contains base design tokens common across all themes.
+  - The ``themes/`` directory contains subdirectories for each theme variant (e.g., ``light``, ``dark``), each with tokens specific to that theme.
+
+Building Themes
+---------------
+
+Invoke the build process via Tutor:
+
+.. code-block:: bash
+
+    tutor local do build-tokens [OPTIONS]
+
+Available options:
+
+- ``--source-tokens-only``  
+  Include only source design tokens in the build.
+
+- ``--output-token-references``  
+  Include references for tokens with aliases to other tokens in the build output.
+
+- ``--themes <theme1,theme2>``  
+  Comma-separated list of theme names to compile. Defaults to the list defined in ``PARAGON_ENABLED_THEMES`` if not provided.
+
+- ``-v, --verbose``  
+  Enable verbose logging.
+
+Examples
+--------
+
+.. code-block:: bash
+
+    # Compile all themes listed in PARAGON_ENABLED_THEMES
+    tutor local do build-tokens
+
+    # Compile only specific themes
+    tutor local do build-tokens --themes theme-1,theme-2
+
+    # Compile with full debug logs
+    tutor local do build-tokens --verbose
+
+    # Compile only source tokens for a single theme
+    tutor local do build-tokens --themes theme-1 --source-tokens-only
+
+Output
+------
+
+Artifacts will be written to the directory specified by ``PARAGON_COMPILED_THEMES_PATH`` (default: ``env/plugins/paragon/compiled-themes``).
+
+Troubleshooting
+***************
+
+- **No custom themes built or only default tokens generated**  
+  Ensure that your custom theme directories exist under ``PARAGON_THEME_SOURCES_PATH`` and that their names exactly match those in ``PARAGON_ENABLED_THEMES`` or passed via ``--themes``. If no custom tokens are found, Paragon will fall back to its built-in defaults.
+
+- **Themes are not picked up when using --themes:**  
+  The value for ``--themes`` must be a comma-separated list (no spaces), e.g. ``--themes theme-1,theme-2``.
+
+- **Write permission denied**  
+  Verify that Docker and the Tutor process have write access to the path defined by ``PARAGON_COMPILED_THEMES_PATH``. Adjust filesystem permissions if necessary.
+
+- **Error: "Expected at least 4 args"**  
+  This occurs when the build job is invoked directly inside the container. Always run via Tutor:
+
+  .. code-block:: bash
+
+      tutor local do build-tokens [OPTIONS]
+
+- **Other issues**  
+  Re-run the build with ``--verbose`` to obtain detailed logs and identify misconfigurations or missing files.
+
+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/patches/local-docker-compose-jobs-services

@@ -0,0 +1,8 @@
+# Paragon Builder
+paragon-builder-job:
+    image: {{ PARAGON_BUILDER_IMAGE }}
+    environment:
+      - PARAGON_ENABLED_THEMES={{ PARAGON_ENABLED_THEMES | join(',') }}
+    volumes:
+      - "./../../{{ PARAGON_THEME_SOURCES_PATH }}:/theme-sources"
+      - "./../../{{ PARAGON_COMPILED_THEMES_PATH }}:/compiled-themes"