render-topologies

name	render-topologies
description	Local visual regression check for layout or rendering changes. Renders all gallery examples, pixel-diffs against main, and opens changed renders as BEFORE/AFTER pairs. In most cases the CI render preview on a PR is sufficient - use this skill only for pre-push confidence on risky changes or when the user explicitly asks for a local diff.
disable-model-invocation	true
allowed-tools	Bash(rm -rf *), Bash(python *), Bash(open *), Bash(cd *), Bash(git *), Bash(source *), Bash(pip *), Bash(cp *)

Render Topologies

Local pixel-diff of all gallery renders between the current branch and origin/main. Uses scripts/build_gallery.py (the same script CI runs), so local results match the PR render preview.

Conventions (substitute if your setup differs):

• Local nf-metro checkout: ~/projects/nf-metro
• Baseline env: nf-metro-main; branch env: nf-metro (or nf-metro-fix-<N> in worktree mode)
• CI render preview is published at the upstream's GitHub Pages site (seqeralabs.github.io/nf-metro/_pr/<N>/); if you ship from a fork with Pages enabled, the URL will track your fork's owner

In most cases you don't need this. Push to a PR and review the CI-generated render preview at https://seqeralabs.github.io/nf-metro/_pr/<PR_NUMBER>/ instead. Use this skill only when:

• You want pre-push confidence before creating a PR
• The user explicitly asks for a local visual comparison
• You're iterating on a change and want fast feedback without pushing

Step 1: Detect context

Determine the working mode:

• Worktree mode: A worktree exists at /tmp/nf-metro-fix-<N> with a matching nf-metro-fix-<N> env. Use the worktree path and env for branch renders.
• Standalone mode: Working from the main repo at ~/projects/nf-metro. Use the nf-metro env for branch renders. Stash or commit any uncommitted changes first.

Step 2: Render baseline from main

Update the main repo checkout and render using the shared nf-metro-main baseline environment. Install with [docs] extras (same as CI).

cd ~/projects/nf-metro && git fetch origin main && git checkout main && git pull origin main
source ~/.local/bin/mm-activate nf-metro-main && pip install -e "$HOME/projects/nf-metro[docs]" -q
cd ~/projects/nf-metro && python scripts/build_gallery.py
# SVGs are in docs/assets/renders/ → copy to a baseline dir
rm -rf /tmp/nf_metro_renders_main && mkdir -p /tmp/nf_metro_renders_main
cp docs/assets/renders/*.svg /tmp/nf_metro_renders_main/

Step 3: Render from the current branch

Switch back to the branch first (standalone mode) or use the worktree path:

# Standalone: switch back to the branch
cd ~/projects/nf-metro && git checkout <branch-name>
source ~/.local/bin/mm-activate nf-metro && pip install -e ".[docs]" -q
python scripts/build_gallery.py
rm -rf /tmp/nf_metro_renders_branch && mkdir -p /tmp/nf_metro_renders_branch
cp docs/assets/renders/*.svg /tmp/nf_metro_renders_branch/

# Worktree: use worktree path and env
source ~/.local/bin/mm-activate nf-metro-fix-<N> && pip install -e "/tmp/nf-metro-fix-<N>[docs]" -q
cd /tmp/nf-metro-fix-<N> && python scripts/build_gallery.py
rm -rf /tmp/nf_metro_renders_branch && mkdir -p /tmp/nf_metro_renders_branch
cp /tmp/nf-metro-fix-<N>/docs/assets/renders/*.svg /tmp/nf_metro_renders_branch/

Step 4: Diff and open the report

Use scripts/build_render_diff.py — the same script the CI render-preview workflow uses — to compare the two SVG directories. It writes a self-contained HTML page (index.html) showing side-by-side before/after for changed examples only, grouped by section.

cd ~/projects/nf-metro
rm -rf /tmp/render_diff && mkdir -p /tmp/render_diff
python scripts/build_render_diff.py \
  /tmp/nf_metro_renders_main \
  /tmp/nf_metro_renders_branch \
  /tmp/render_diff
open /tmp/render_diff/index.html

Exit codes: 0 = changes detected and report written, 2 = no changes (skip open), 1 = error. The report works directly on SVGs, so no PNG conversion is needed.

Step 5: Report

• Whether any examples changed (the script's exit code tells you)
• For changed examples, point the user at /tmp/render_diff/index.html
• If zero changed, say so and skip open

Notes

• Render script: scripts/build_gallery.py (same as CI PR render preview workflow).
• Diff script: scripts/build_render_diff.py (also matches CI), so local results match the PR render preview.
• Nextflow fixtures (tests/fixtures/nextflow/*.mmd) are included in the gallery.
• Baseline always uses nf-metro-main env + main repo updated to origin/main.
• Install with [docs] extras (not [dev]) to match CI dependencies.
• After a PR is created, CI renders the authoritative diff at https://seqeralabs.github.io/nf-metro/_pr/<PR_NUMBER>/.
• To render a single file: python -m nf_metro render <file.mmd> -o /tmp/output.svg