deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup Node
      uses: actions/setup-node@v4
      with:
        node-version: 22

    # Deploy-time reference-doc generation: clone the public wizardsofodd
    # reference impl, run `meta docs` (published @metaobjectsdev/cli), and drop the
    # browsable site into www/reference/ so it publishes with the site. Regenerates
    # on every deploy (push to main / workflow_dispatch) — no cross-repo secrets.
    # --ignore-scripts skips wizardsofodd's wrangler postinstall (not needed for
    # docs). --prompts data/templates surfaces the actual prompt TEXT.
    # A REAL PROJECT documented by `meta docs` — not "the reference". It lives at
    # /reference/example because a self-referential metamodel page cannot show that the
    # tool works on somebody's actual model, which is the only thing this demonstrates.
    # /reference itself is the metamodel, copied in the next step.
    #
    # The `rm` is narrowed to this subdirectory. It used to remove the whole of
    # www/reference, which — now that the metamodel lands there too — would delete the
    # reference and leave only the example behind, on every deploy.
    - name: Generate the example project's docs (a real model, documented by meta docs)
      run: |
        git clone --depth 1 https://github.com/Draagon/wizardsofodd.git /tmp/woo
        cd /tmp/woo
        npm ci --ignore-scripts
        npx meta docs . --site --prompts data/templates --out /tmp/woo-docs
        rm -rf "$GITHUB_WORKSPACE/www/reference/example"
        mkdir -p "$GITHUB_WORKSPACE/www/reference/example"
        cp -r /tmp/woo-docs/site/* "$GITHUB_WORKSPACE/www/reference/example/"

    # Snippet injection: clone metaobjects at its latest npm RELEASE TAG — not main —
    # and inject its committed site-payload.json into this site's data-snippet
    # placeholders. Pinning to the tag matters: an unrelated site edit triggers a deploy,
    # and against main that deploy would publish unreleased snippets.
    #
    # `node`, never `bun`: setup-node above is this workflow's ONLY toolchain step and
    # ubuntu-latest carries no bun, so a bun line would be `command not found` and — from
    # here, before "Upload artifact" — would fail the entire deploy. The injector is plain
    # Node ESM with zero dependencies for exactly that reason, so there is no install step
    # (a root `bun install` would fetch 16 workspace packages to run a regex replace).
    - name: Inject generated snippets
      run: |
        set -euo pipefail
        git clone --filter=blob:none https://github.com/metaobjectsdev/metaobjects.git /tmp/mo
        cd /tmp/mo
        # The repo carries TWO tag lines: v0.x (npm lockstep) and v7.x (JVM). An
        # unfiltered `git tag -l 'v*' | sort -V | tail -1` returns v7.20.12 — a Maven-only
        # cut — and always will, because 7 sorts above 0. That tree has no
        # examples/showcase, so an unfiltered pin would break forever. Filter to the npm
        # line. (Never `git fetch --all`: it deletes local release tags.)
        TAG=$(git tag -l 'v0.*' | grep -E '^v0\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
        test -n "$TAG" || { echo "no v0.x release tag found"; exit 1; }
        git checkout --quiet "$TAG"
        # The agent-facing mirrors, from the SAME clone — do not clone twice. They are
        # maintained in the metaobjects repo and merely SERVED from here; keeping a second
        # editable copy in this repo is how the two drifted, because an edit landed on
        # whichever copy the editor happened to open and the other one won at deploy. They
        # are gitignored here for that reason.
        #
        # This runs BEFORE the injector guard below, deliberately. The copy does not depend
        # on the injector, and because the mirrors are no longer tracked in this repo, a
        # skipped copy means www/llms.txt does not exist at all — a 404 on a documented URL,
        # which is worse than a stale file. A missing SOURCE warns rather than failing, for
        # the same reason the injector guard does: one absent text file must not take down
        # the whole site.
        if [ -f docs/llms/llms.txt ] && [ -f docs/llms/llms-full.txt ]; then
          cp docs/llms/llms.txt      "$GITHUB_WORKSPACE/www/llms.txt"
          cp docs/llms/llms-full.txt "$GITHUB_WORKSPACE/www/llms-full.txt"
          echo "copied llms mirrors from metaobjects $TAG"
        else
          echo "::warning::metaobjects $TAG has no docs/llms mirrors — /llms.txt will 404."
        fi

        # A release older than the injection program has neither the injector nor the
        # payload. Skip rather than fail: the pages still carry their placeholders, and a
        # hard failure here would take down the whole deploy — including unrelated prose
        # edits — for every push until the next release. Loud, and self-extinguishing.
        if [ ! -f scripts/site-inject-ci.mjs ] || [ ! -f examples/showcase/site-payload.json ]; then
          echo "::warning::metaobjects $TAG predates snippet injection — skipping. Code blocks will render EMPTY until the next release."
          exit 0
        fi
        echo "injecting snippets from metaobjects $TAG"
        node scripts/site-inject-ci.mjs --site "$GITHUB_WORKSPACE/www"

        # The metamodel reference at /reference — every type, subtype and attribute the
        # loader accepts, rendered in the metaobjects repo and carried by the tag. It is
        # NOT rendered here: this workflow has setup-node and nothing else, the metaobjects
        # clone gets no install step, and keeping it that way is what stops a site deploy
        # from depending on that workspace resolving.
        #
        # A plain copy, never `rm -rf www/reference` — the previous step has already
        # written www/reference/example, and removing the parent would delete it on every
        # deploy. Nothing stale can accumulate anyway: www/reference is gitignored, so each
        # run starts from a checkout that does not contain it.
        if [ -d site-reference ]; then
          mkdir -p "$GITHUB_WORKSPACE/www/reference"
          cp -r site-reference/. "$GITHUB_WORKSPACE/www/reference/"
          echo "copied the metamodel reference from metaobjects $TAG"
        else
          echo "::warning::metaobjects $TAG has no site-reference/ — /reference will show only the example."
        fi

    - name: Setup Pages
      uses: actions/configure-pages@v4

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: './www'

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4