feat: Merge pull request #17 from elabit/feat/osmatrix

Feat/osmatrix

Author: simonmeggle

.github/scripts/sync-examples.sh

@@ -1,24 +1,27 @@
 #!/usr/bin/env bash
-# sync-examples.sh — Pushes each examples/<name>/ as a snapshot to robotmk/example-<name>
-#                    and each labs/<name>/ as a snapshot to robotmk/<name>.
+# sync-examples.sh — Pushes each examples/<name>/ as a snapshot to robotmk/example-<name>,
+#                    each labs/<name>/ as a snapshot to robotmk/lab-<name>,
+#                    and each os/<slug>/ as a snapshot to robotmk/os-<slug>.
 #
 # Requires:
 #   - GH_TOKEN env var with a PAT that has Contents+Administration write on the robotmk org
 #   - gh CLI (available on GitHub Actions runners)
 #   - git configured with user.name and user.email
 #
 # Usage:
-#   .github/scripts/sync-examples.sh [<example-name>] [--lab <lab-name>]
+#   .github/scripts/sync-examples.sh [<example-name>] [<lab-name>] [<os-slug>]
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 EXAMPLES_DIR="${REPO_ROOT}/examples"
 LABS_DIR="${REPO_ROOT}/labs"
+OS_DIR="${REPO_ROOT}/os"
 ORG="robotmk"
 EXAMPLE_FILTER="${1:-}"
 LAB_FILTER="${2:-}"  # passed as second arg from workflow (--lab value handled by caller)
+OS_FILTER="${3:-}"
 SOURCE_SHA="${GITHUB_SHA:-$(git -C "${REPO_ROOT}" rev-parse HEAD)}"
 SOURCE_REPO="${GITHUB_REPOSITORY:-elabit/robotmk-starter}"
 
@@ -31,6 +34,7 @@ EXCLUDE=(
   "output.xml"
   "browser"
   "playwright-log.txt"
+  "report.md"
 )
 
 # ─── Helper ──────────────────────────────────────────────────────────────────
@@ -101,6 +105,20 @@ build_lab_footer() {
 EOF
 }
 
+build_os_footer() {
+  local slug="$1"
+  cat <<EOF
+> ---
+>
+> **This repository is automatically synced from [${SOURCE_REPO}](https://github.com/${SOURCE_REPO}/tree/main/os/${slug}).**
+> Do not edit files here directly — changes will be overwritten on the next sync.
+> Last sync: [\`${SOURCE_SHA:0:7}\`](https://github.com/${SOURCE_REPO}/commit/${SOURCE_SHA})
+
+---
+
+EOF
+}
+
 prepare_workdir() {
   local repo="$1"
   local tmpdir="$2"
@@ -244,6 +262,61 @@ sync_lab() {
   rm -rf "${tmpdir}"
 }
 
+sync_os() {
+  local name="$1"
+  local src="${OS_DIR}/${name}"
+  local repo="${ORG}/os-${name}"
+  local tmpdir
+  tmpdir="$(mktemp -d)"
+
+  echo ""
+  echo "══ Syncing os ${name} → ${repo} ══"
+
+  ensure_repo "${repo}" "Robotmk OS install verification target (synced from ${SOURCE_REPO})"
+
+  local repo_id
+  repo_id="$(gh api "repos/${repo}" --jq '.id')"
+  echo "  ✓ Repo ID: ${repo_id}"
+
+  local has_devcontainer="false"
+  [[ -d "${src}/.devcontainer" ]] && has_devcontainer="true"
+
+  # Prepare workdir: fetch existing content or init empty for brand-new repos
+  prepare_workdir "${repo}" "${tmpdir}"
+
+  # Wipe tracked content so we do a clean snapshot
+  if git -C "${tmpdir}" rev-parse HEAD &>/dev/null; then
+    git -C "${tmpdir}" rm -rf . --quiet
+  fi
+
+  rsync -a "${src}/" "${tmpdir}/"
+
+  for item in "${EXCLUDE[@]}"; do
+    rm -rf "${tmpdir:?}/${item}"
+  done
+
+  # README.md is committed and static (Copier-rendered at generate time, see
+  # _dev/_shared/README-os.md.jinja) -- unlike examples/labs it isn't
+  # generated by a separate build step, so it's already present in ${src}.
+  if [[ -f "${tmpdir}/README.md" ]]; then
+    prepend_header "${tmpdir}/README.md" "$(build_header "${name}" "${repo_id}" "${has_devcontainer}")"
+    append_footer  "${tmpdir}/README.md" "$(build_os_footer "${name}")"
+  else
+    echo "  ❌ No README.md found — skipping header/footer injection."
+  fi
+
+  git -C "${tmpdir}" add -A
+  if git -C "${tmpdir}" diff --cached --quiet; then
+    echo "  No changes — skipping push."
+  else
+    git -C "${tmpdir}" commit -m "sync: from ${SOURCE_REPO}@${SOURCE_SHA:0:7}"
+    git -C "${tmpdir}" push -u origin main
+    echo "  ✓ Pushed."
+  fi
+
+  rm -rf "${tmpdir}"
+}
+
 # ─── Main ────────────────────────────────────────────────────────────────────
 
 echo "=== Syncing examples/ ==="
@@ -265,5 +338,16 @@ if [[ -d "${LABS_DIR}" ]]; then
   done
 fi
 
+echo ""
+echo "=== Syncing os/ ==="
+if [[ -d "${OS_DIR}" ]]; then
+  for dir in "${OS_DIR}"/*/; do
+    name="$(basename "${dir}")"
+    if [[ -z "${OS_FILTER}" || "${name}" == "${OS_FILTER}" ]]; then
+      sync_os "${name}"
+    fi
+  done
+fi
+
 echo ""
 echo "Sync complete."

.github/scripts/update_suite_table.py

@@ -12,6 +12,7 @@
     GITHUB_REPOSITORY  — e.g. "myorg/robotmk-starter"  (optional, updates badge URL)
 """
 
+import json
 import os
 import re
 import sys
@@ -112,6 +113,38 @@ def build_table(repo_root: Path, parent: str) -> str:
     return "\n".join([header, sep] + rows)
 
 
+def build_os_table(repo_root: Path) -> str:
+    """Build the os/ target table, reading each instance's pinned base image
+    from its already-rendered devcontainer.json rather than versions.env, so
+    the table reflects what was actually last generated (AD-12: distinct
+    build function, os/ has no conda.yaml/robot-doc to parse like build_table
+    expects)."""
+    header = "| OS | Base Image | Repository Link |"
+    sep    = "|---|---|---|"
+    rows = []
+    os_dir = repo_root / "os"
+    if os_dir.exists():
+        for slug_dir in sorted(os_dir.iterdir()):
+            if not slug_dir.is_dir() or slug_dir.name.startswith("."):
+                continue
+            slug = slug_dir.name
+            devcontainer_json = slug_dir / ".devcontainer" / "devcontainer.json"
+            image = "—"
+            if devcontainer_json.exists():
+                # devcontainer.json is JSONC (// comments allowed) -- strip
+                # line-comments before parsing, same approach run-suites.yml's
+                # "os" job already uses to read the same file.
+                text = re.sub(r"//.*", "", devcontainer_json.read_text())
+                try:
+                    image = json.loads(text).get("image", "—")
+                except json.JSONDecodeError:
+                    image = "—"
+            rows.append(
+                f"| [{slug}](os/{slug}) | `{image}` | [try out](https://github.com/robotmk/os-{slug}) |"
+            )
+    return "\n".join([header, sep] + rows)
+
+
 def replace_between_markers(content: str, start: str, end: str, replacement: str) -> tuple[str, bool]:
     pattern = rf"({re.escape(start)}).*?({re.escape(end)})"
     new_content, count = re.subn(
@@ -163,7 +196,15 @@ def main():
         "<!-- LABS-TABLE-END -->",
         build_table(repo_root, "labs"),
     )
-    if t1 or t2 or t3:
+    # Update os table
+    content, t4 = replace_between_markers(
+        content,
+        "<!-- OS-TABLE-START -->",
+        "<!-- OS-TABLE-END -->",
+        build_os_table(repo_root),
+    )
+
+    if t1 or t2 or t3 or t4:
         print("Suite tables updated.")
         changed = True
 

.github/workflows/run-suites.yml

@@ -6,10 +6,12 @@ on:
     paths:
       - "examples/**"
       - "templates/**"
+      - "os/**"
   pull_request:
     paths:
       - "examples/**"
       - "templates/**"
+      - "os/**"
   workflow_dispatch:
     inputs:
       suite:
@@ -154,3 +156,60 @@ jobs:
           name: rf-output-${{ steps.suite-env.outputs.safe_name }}-${{ matrix.os }}
           path: ${{ matrix.suite }}/log.html
           if-no-files-found: ignore
+
+  # ── Stage 3: os content type (provision + verify + report) ────────────────
+  # Independent of the detect-changes/test pair above: exactly one job per OS
+  # family, added deliberately one epic at a time (Story 1.5 adds debian;
+  # Stories 2.2/3.2/4.2 each add one more matrix entry), never auto-detected
+  # from a directory listing the way the examples/templates matrix is.
+  os:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        slug: [debian, ubuntu, rhel, sles]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read pinned image from the generated devcontainer.json
+        id: os-env
+        run: |
+          # devcontainer.json is JSONC (allows // comments, per the Dev
+          # Container spec) -- jq can't parse that directly, so strip
+          # line-comments before feeding it to a JSON parser.
+          IMAGE=$(python3 -c "
+          import json, re
+          text = open('os/${{ matrix.slug }}/.devcontainer/devcontainer.json').read()
+          text = re.sub(r'//.*', '', text)
+          print(json.loads(text)['image'])
+          ")
+          echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
+
+      - name: Provision, verify, and report
+        run: |
+          # Mount ONLY os/<slug> (not the full repo root) -- this instance is
+          # self-contained (its own copy of the shared Ansible role + RF
+          # suite via populate.yaml, AD-3/AD-4), so this deliberately mirrors
+          # exactly what a standalone extracted repo would see, proving the
+          # self-containment property in CI rather than assuming it.
+          # No devcontainer CLI in CI (AD-9), so its onCreateCommand/
+          # postCreateCommand split isn't applied automatically here -- chain
+          # the same two scripts explicitly instead. `&&` gives the identical
+          # halt-then-propagate semantics the Dev Container lifecycle gives
+          # the interactive path: postcreate.sh only runs if oncreate.sh
+          # succeeded, and the final exit code reflects whichever of the two
+          # actually failed.
+          docker run --rm \
+            -v "${{ github.workspace }}/os/${{ matrix.slug }}:/workspace" \
+            -w "/workspace" \
+            "${{ steps.os-env.outputs.image }}" \
+            bash -c "bash .devcontainer/oncreate.sh && bash .devcontainer/postcreate.sh"
+
+      - name: Upload install report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: os-report-${{ matrix.slug }}
+          path: os/${{ matrix.slug }}/report.md
+          if-no-files-found: ignore

.github/workflows/sync-examples.yml

@@ -17,6 +17,10 @@ on:
         description: "Single lab to sync (leave empty for all)"
         required: false
         default: ""
+      os:
+        description: "Single os/ slug to sync (leave empty for all)"
+        required: false
+        default: ""
 
 jobs:
   sync:
@@ -40,4 +44,4 @@ jobs:
           GITHUB_SHA: ${{ github.sha }}
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
-          bash .github/scripts/sync-examples.sh "${{ github.event.inputs.example }}" "${{ github.event.inputs.lab }}"
+          bash .github/scripts/sync-examples.sh "${{ github.event.inputs.example }}" "${{ github.event.inputs.lab }}" "${{ github.event.inputs.os }}"

.gitignore

@@ -15,6 +15,7 @@ report.html
 output.xml
 browser/screenshot/
 playwright-log.txt
+os/*/report.md
 
 # RCC holotree (local environment cache)
 .robocorp/
@@ -36,3 +37,4 @@ nohup.out
 
 __pycache__/*
 *.pyc
+.claude

README.md

@@ -88,6 +88,23 @@ To try them out, just click on "*try out*" which opens the repository, where you
 
 ---
 
+### 🐧 Folder "/os"
+
+Proof that each target OS can be provisioned from a stock install (via Ansible, in a devcontainer) and actually run a Robot Framework web test end-to-end — not just "packages installed", but "the browser test passes".
+
+<!-- OS-TABLE-START -->
+
+| OS | Base Image | Repository Link |
+|---|---|---|
+| [debian](os/debian) | `debian:13` | [try out](https://github.com/robotmk/os-debian) |
+| [rhel](os/rhel) | `rockylinux/rockylinux:10` | [try out](https://github.com/robotmk/os-rhel) |
+| [sles](os/sles) | `registry.suse.com/suse/sle15:15.7` | [try out](https://github.com/robotmk/os-sles) |
+| [ubuntu](os/ubuntu) | `ubuntu:24.04` | [try out](https://github.com/robotmk/os-ubuntu) |
+
+<!-- OS-TABLE-END -->
+
+---
+
 ## For maintainers
 
 Examples and templates are generated from Copier sources in `_dev/`.

TODO.md

@@ -0,0 +1,2 @@
+- Labs README shoul dhave a clear instruction (shown in VS Code after start)
+-