Validate-only Excel inbox; add updater

Make the inbox workflow validation-only: remove promotion/commit steps and INBOX_PROMOTE_STRATEGY, tighten checks and messages, and avoid writing back to PR branches (checkout no longer persists credentials). Improve Python/JS formatting and capture of round-trip output. Add a new update_excel workflow that runs on pushes to main to regenerate docs/assets/coremeta4cat_vocabulary.xlsx from the schema and commit it (with contents: write permission). This separates validation (safe for forks/PRs) from the single authoritative post-merge update that writes the generated workbook.

Author: HendrikBorgelt

.github/workflows/excel_inbox.yaml

@@ -1,43 +1,24 @@
 # .github/workflows/excel_inbox.yaml
 #
-# Excel Inbox — PR validation pipeline
-# =====================================
-# Triggered when a pull request adds or modifies a file inside the
-# inbox/ directory.  The expected contributor flow is:
+# Excel Inbox — PR validation
+# ============================
+# Triggered when a pull request adds or modifies a file inside inbox/.
 #
-#   1. Contributor downloads docs/assets/coremeta4cat_vocabulary.xlsx,
-#      edits the vocabulary (adds/changes rows), and opens a PR placing
-#      the updated file in:
+# This workflow only validates — it never pushes anything back to the branch.
+# That keeps it safe for both same-repo and fork PRs.
 #
-#         inbox/coremeta4cat_vocabulary.xlsx
+# Contributor flow:
+#   1. Download docs/assets/coremeta4cat_vocabulary.xlsx.
+#   2. Edit it locally.
+#   3. Open a PR placing the file at inbox/coremeta4cat_vocabulary.xlsx.
+#   4. This workflow validates the file and posts a comment with the result.
+#   5. On merge to main, the update_excel workflow regenerates
+#      docs/assets/coremeta4cat_vocabulary.xlsx from the schema automatically.
 #
-#   2. This workflow runs automatically and:
-#      a. Validates the workbook structure (sheets, columns).
-#      b. Runs the round-trip diff (excel-to-schema): checks that every
-#         top-level slot in the workbook exists in the schema with the
-#         correct M/R/O value.
-#      c. Posts a summary comment on the PR with the outcome.
-#      d. On success: moves the file to docs/assets/ and commits it back
-#         to the PR branch, OR deletes it and lets schema-to-excel
-#         regenerate it (see INBOX_PROMOTE_STRATEGY below).
-#      e. On failure: leaves the inbox file in place and marks the
-#         workflow as failed so the PR cannot be merged.
-#
-# INBOX_PROMOTE_STRATEGY
-# ──────────────────────
-# Two strategies are supported, controlled by the env var below:
-#
-#   "move"       — The validated inbox file is moved to docs/assets/ and
-#                  committed back.  Use this when contributors may have
-#                  added rows that the schema-to-excel script would not
-#                  regenerate (e.g. manually curated descriptions).
-#
-#   "regenerate" — The inbox file is deleted and schema-to-excel is run
-#                  to produce a fresh docs/assets/ workbook from the
-#                  schema.  Use this when the Excel is purely derived
-#                  output and should always mirror the schema exactly.
-#
-# Set the strategy in the env block below.
+# Note: the inbox file is NOT promoted to docs/assets/ here.
+# The ground truth is always the schema; the Excel is derived output.
+# If the contributor's edits require schema changes, those should be made to
+# the YAML source files and the workbook will be regenerated on merge.
 ---
 name: Excel inbox validation
 
@@ -48,26 +29,22 @@ on:  # yamllint disable-line rule:truthy
 
 env:
   FORCE_COLOR: "1"
-  INBOX_PROMOTE_STRATEGY: "regenerate"   # "move" or "regenerate"
   INBOX_FILE: "inbox/coremeta4cat_vocabulary.xlsx"
-  DOCS_FILE: "docs/assets/coremeta4cat_vocabulary.xlsx"
 
 permissions:
-  contents: write        # needed to push the commit back to the PR branch
   pull-requests: write   # needed to post the summary comment
 
 jobs:
   validate-inbox:
     runs-on: ubuntu-latest
-    # Only run when the inbox file is actually present in the PR
+
     steps:
 
-      - name: Check out PR branch
+      - name: Check out repository
         uses: actions/checkout@v6.0.3
+        # No ref override — uses the PR merge commit, works for forks too.
         with:
-          ref: ${{ github.head_ref }}
-          token: ${{ secrets.GITHUB_TOKEN }}
-          fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
@@ -90,7 +67,7 @@ jobs:
             echo "Inbox file found: ${{ env.INBOX_FILE }}"
           else
             echo "present=false" >> "$GITHUB_OUTPUT"
-            echo "No inbox file found — skipping validation."
+            echo "No inbox file found at ${{ env.INBOX_FILE }} — nothing to validate."
           fi
 
       - name: Validate workbook structure
@@ -102,10 +79,14 @@ jobs:
           import openpyxl
 
           path = "${{ env.INBOX_FILE }}"
-          expected_sheets = {"Introduction", "Legend", "CoreMeta4Cat",
-                             "Synthesis", "Characterization", "Reaction", "Simulation"}
-          expected_headers = ["label", "type", "domain", "M / R / O",
-                              "range", "uri", "description"]
+          expected_sheets = {
+              "Introduction", "Legend", "CoreMeta4Cat",
+              "Synthesis", "Characterization", "Reaction", "Simulation",
+          }
+          expected_headers = [
+              "label", "type", "domain", "M / R / O",
+              "range", "uri", "description",
+          ]
           data_sheets = ["Synthesis", "Characterization", "Reaction", "Simulation"]
 
           errors = []
@@ -116,12 +97,10 @@ jobs:
               print(f"::error::Cannot open workbook: {e}")
               sys.exit(1)
 
-          # Check sheet presence
           missing = expected_sheets - set(wb.sheetnames)
           if missing:
               errors.append(f"Missing sheets: {', '.join(sorted(missing))}")
 
-          # Check headers on data sheets
           for sheet_name in data_sheets:
               if sheet_name not in wb.sheetnames:
                   continue
@@ -130,28 +109,29 @@ jobs:
               if header != expected_headers:
                   errors.append(
                       f"Sheet '{sheet_name}' header mismatch.\n"
-                      f"  Expected: {expected_headers}\n  Got: {header}"
+                      f"  Expected: {expected_headers}\n  Got:      {header}"
                   )
 
           if errors:
               for e in errors:
                   print(f"::error::{e}")
               sys.exit(1)
 
-          print("Workbook structure is valid.")
+          print("Workbook structure OK.")
           PYEOF
 
       - name: Run round-trip diff (excel-to-schema)
         if: steps.inbox_check.outputs.present == 'true'
         id: roundtrip
         run: |
-          # Run excel_to_schema against the inbox file and capture output.
-          # The script exits 0 even with diffs, so we parse its output.
           OUTPUT=$(uv run python scripts/excel_to_schema.py "${{ env.INBOX_FILE }}" 2>&1)
           echo "$OUTPUT"
-          echo "roundtrip_output<<EOF" >> "$GITHUB_ENV"
-          echo "$OUTPUT" >> "$GITHUB_ENV"
-          echo "EOF" >> "$GITHUB_ENV"
+
+          {
+            echo "roundtrip_output<<EOF"
+            echo "$OUTPUT"
+            echo "EOF"
+          } >> "$GITHUB_ENV"
 
           if echo "$OUTPUT" | grep -q "OK Schema and workbook are fully aligned"; then
             echo "status=ok" >> "$GITHUB_OUTPUT"
@@ -167,15 +147,26 @@ jobs:
           script: |
             const status = "${{ steps.roundtrip.outputs.status }}";
             const output = process.env.roundtrip_output || "(no output)";
-            const icon   = status === "ok" ? "✅" : "❌";
-            const title  = status === "ok"
+            const icon  = status === "ok" ? "✅" : "❌";
+            const title = status === "ok"
               ? "Excel inbox — round-trip validation **passed**"
               : "Excel inbox — round-trip validation **failed**";
-            const body = `## ${icon} ${title}\n\n<details><summary>Full diff output</summary>\n\n\`\`\`\n${output}\n\`\`\`\n</details>\n\n${
-              status === "ok"
-                ? "The workbook is aligned with the schema. The file will be promoted to `docs/assets/` automatically."
-                : "Differences were found between the inbox workbook and the schema. Please review the output above and either update the workbook or open a schema issue."
-            }`;
+            const advice = status === "ok"
+              ? "The workbook is aligned with the schema. Once this PR is merged, `docs/assets/coremeta4cat_vocabulary.xlsx` will be regenerated automatically from the schema."
+              : "Differences were found between the inbox workbook and the schema.\n\nIf your changes require additions to the schema, please update the YAML source files and include those changes in this PR. The workbook is derived output — the schema is the ground truth.";
+
+            const body = [
+              `## ${icon} ${title}`,
+              "",
+              "<details><summary>Full diff output</summary>",
+              "",
+              "```",
+              output,
+              "```",
+              "</details>",
+              "",
+              advice,
+            ].join("\n");
 
             await github.rest.issues.createComment({
               owner: context.repo.owner,
@@ -189,41 +180,5 @@ jobs:
           steps.inbox_check.outputs.present == 'true' &&
           steps.roundtrip.outputs.status != 'ok'
         run: |
-          echo "::error::Round-trip validation failed. See PR comment for details."
+          echo "::error::Round-trip validation failed. See the PR comment for details."
           exit 1
-
-      # ── Promotion step: move or regenerate ───────────────────────────────
-
-      - name: Promote inbox file (strategy = move)
-        if: >
-          steps.inbox_check.outputs.present == 'true' &&
-          steps.roundtrip.outputs.status == 'ok' &&
-          env.INBOX_PROMOTE_STRATEGY == 'move'
-        run: |
-          mv "${{ env.INBOX_FILE }}" "${{ env.DOCS_FILE }}"
-          echo "Moved inbox file to docs/assets/."
-
-      - name: Promote inbox file (strategy = regenerate)
-        if: >
-          steps.inbox_check.outputs.present == 'true' &&
-          steps.roundtrip.outputs.status == 'ok' &&
-          env.INBOX_PROMOTE_STRATEGY == 'regenerate'
-        run: |
-          rm "${{ env.INBOX_FILE }}"
-          just schema-to-excel
-          echo "Removed inbox file; regenerated docs/assets/ from schema."
-
-      - name: Commit promotion back to PR branch
-        if: steps.inbox_check.outputs.present == 'true' && steps.roundtrip.outputs.status == 'ok'
-        run: |
-          git config user.name  "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add "${{ env.DOCS_FILE }}"
-          # Stage inbox deletion if still present (move strategy leaves nothing to stage)
-          git add "${{ env.INBOX_FILE }}" 2>/dev/null || true
-          if git diff --cached --quiet; then
-            echo "Nothing to commit."
-          else
-            git commit -m "chore: promote validated inbox Excel to docs/assets [skip ci]"
-            git push
-          fi

.github/workflows/update_excel.yaml

@@ -0,0 +1,69 @@
+# .github/workflows/update_excel.yaml
+#
+# Post-merge Excel update
+# ========================
+# Runs after every push to main (i.e. after a PR is merged).
+# Regenerates docs/assets/coremeta4cat_vocabulary.xlsx from the current
+# schema and commits it back if anything changed.
+#
+# This is the only place that writes the workbook — keeping write access
+# out of PR workflows entirely, which avoids fork permission issues.
+---
+name: Update Excel vocabulary
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [main]
+    paths:
+      # Only regenerate when something that affects the workbook changes.
+      - "src/coremeta4cat/schema/**"
+      - "scripts/schema_to_excel.py"
+      - "scripts/generate_schema_docs.py"
+
+env:
+  FORCE_COLOR: "1"
+
+permissions:
+  contents: write   # needed to commit the regenerated workbook
+
+jobs:
+  update-excel:
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: Check out repository
+        uses: actions/checkout@v6.0.3
+        with:
+          # Use a token with write access so the commit push works.
+          # GITHUB_TOKEN is sufficient for same-repo pushes.
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install project
+        run: uv sync --dev
+
+      - name: Install just
+        run: uv tool install rust-just
+
+      - name: Regenerate Excel vocabulary from schema
+        run: just schema-to-excel
+
+      - name: Commit updated workbook if changed
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/assets/coremeta4cat_vocabulary.xlsx
+          if git diff --cached --quiet; then
+            echo "Workbook unchanged — nothing to commit."
+          else
+            git commit -m "chore: regenerate vocabulary workbook from schema [skip ci]"
+            git push
+          fi