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

Author: Ang-m4

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"

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

@@ -27,6 +27,9 @@
         ("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),
+        # Paragon Builder Docker image
+        # This image is used to compile themes and should be built with `tutor images build paragon-builder`
+        ("PARAGON_BUILDER_IMAGE", "paragon-builder:latest"),
     ]
 )
 
@@ -55,6 +58,22 @@ def create_paragon_folders(project_root: str) -> None:
             print(f"[paragon] Created {label} folder at: {path}")
 
 
+########################################
+# DOCKER IMAGE MANAGEMENT
+########################################
+
+hooks.Filters.IMAGES_BUILD.add_items(
+    [
+        (
+            "paragon-builder",  # Image name used with 'tutor images build myservice'
+            ("plugins", "paragon", "build", "paragon-builder"),  # Path to Dockerfile
+            "{{ PARAGON_BUILDER_IMAGE }}",  # Docker image tag
+            (),  # Build arguments
+        ),
+    ]
+)
+
+
 ########################################
 # TEMPLATE RENDERING
 # (It is safe & recommended to leave
@@ -92,3 +111,60 @@ def create_paragon_folders(project_root: str) -> None:
 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()))
+
+
+########################################
+# CUSTOM JOBS (a.k.a. "do-commands")
+########################################
+
+
+@click.command()
+@click.option(
+    "--source-tokens-only",
+    is_flag=True,
+    default=False,
+    help="Include only source design tokens in the build.",
+)
+@click.option(
+    "--output-token-references",
+    is_flag=True,
+    default=False,
+    help="Include references for tokens with aliases to other tokens in the build output.",
+)
+@click.option("--themes", help="Comma-separated list of themes to build.")
+@click.option(
+    "-v", "--verbose", is_flag=True, default=False, help="Enable verbose logging."
+)
+def build_tokens(
+    themes: str,
+    source_tokens_only: bool,
+    output_token_references: bool,
+    verbose: bool,
+) -> list[tuple[str, str]]:
+    """
+    Build theme token files using Paragon.
+
+    Args:
+        source_tokens_only (bool): Only source design tokens.
+        output_token_references (bool): Output token references.
+        themes (str): Comma-separated list of themes.
+        verbose (bool): Verbose logging.
+
+    Returns:
+        list[tuple[str, str]]: List of commands to run.
+    """
+    args = []
+    if source_tokens_only:
+        args.append("--source-tokens-only")
+    if output_token_references:
+        args.append("--output-token-references")
+    if themes:
+        args.append("--themes")
+        args.append(themes)
+    if verbose:
+        args.append("--verbose")
+
+    return [("paragon-builder", " ".join(args))]
+
+
+hooks.Filters.CLI_DO_COMMANDS.add_item(build_tokens)

plugins/tutor-contrib-paragon/tutorparagon/templates/paragon/build/paragon-builder/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:18-alpine
+
+COPY entrypoint.sh /entrypoint.sh
+
+RUN npm install --save @openedx/paragon && \
+    chmod +x /entrypoint.sh
+
+ENTRYPOINT ["sh", "/entrypoint.sh"]
+
+CMD []

plugins/tutor-contrib-paragon/tutorparagon/templates/paragon/build/paragon-builder/entrypoint.sh

@@ -0,0 +1,60 @@
+#!/bin/sh
+set -e
+
+SOURCE_DIR="/theme-sources" # Volume mounted by Paragon plugin
+FINAL_BUILD_DIR="/compiled-themes" # Volume mounted by Paragon plugin
+TMP_BUILD_DIR="$(mktemp -d /tmp/paragon-build.XXXXXX)"
+
+
+has_themes() {
+    # This function checks if the --themes flag is present in the arguments
+    # Returns 0 if --themes is found, 1 otherwise
+    # Usage: has_themes "$@"
+
+    for arg in "$@"; do
+        [ "$arg" = "--themes" ] && return 0
+    done
+    return 1
+}
+
+parse_args() {
+    # This function parses arguments injected by Tutor.
+    # Tutor runs jobs via `sh -e -c '…'`, reserving $1–$3 for its wrapper and
+    # bundling all user flags into $4. The function then extracts the raw flags
+    # string from $4, shifts off the wrapper args, and verifies—or appends—the
+    # selected themes definition.
+
+    if [ "$#" -lt 4 ]; then
+        echo "Error: Expected at least 4 args, got $#. Must run via tutor."
+        exit 1
+    fi
+
+    shift 3
+
+    if ! has_themes "$@"; then
+        if [ -n "${PARAGON_ENABLED_THEMES:-}" ]; then
+            echo "Using PARAGON_ENABLED_THEMES: ${PARAGON_ENABLED_THEMES}"
+            set -- "$@" --themes "${PARAGON_ENABLED_THEMES}"
+        fi
+    fi
+
+    printf '%s\n' "$@"
+}
+
+set -- $(parse_args "$@")
+
+# Executes the Paragon CLI to build themes.
+# It uses a temporary directory to avoid volume permissions issues
+npx paragon build-tokens \
+    --source "$SOURCE_DIR" \
+    --build-dir "$TMP_BUILD_DIR" \
+    "$@"
+
+# Moves the built themes to the final volume directory.
+mkdir -p "$FINAL_BUILD_DIR"
+cp -a "$TMP_BUILD_DIR/." "$FINAL_BUILD_DIR/"
+
+# Clean up
+rm -rf "$TMP_BUILD_DIR"
+
+exit 0