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
        # Pin to the newest tag on the NPM RELEASE LINE — the line every registry has cut
        # together since the 0.20.14 lockstep ruling. Two other lines sit in this repo's
        # history and BOTH outrank it under `sort -V`: v7.x, the JVM-only cuts made before
        # that ruling (they stop at v7.20.12, a tree with neither examples/showcase nor
        # site-reference), and the `-rc.*` prereleases.
        #
        # The filter is deliberately NOT a hardcoded major. It used to be `v0.*`, which
        # stopped matching the day 1.0 shipped — and the failure was SILENT: the deploy
        # would have kept pinning to v0.25.0 and publishing 0.25.0 coordinates, snippets,
        # llms mirrors and metamodel reference under a 1.0 announcement, with every step
        # green. Instead, test the property that actually defines the line: a release tag
        # is on the npm line exactly when the CLI package it carries is versioned AS that
        # tag. v1.0.0 ships cli 1.0.0; v7.20.12 ships cli 0.20.11. Nothing to maintain at
        # the next major. (Never `git fetch --all`: it deletes local release tags.)
        TAG=""
        for t in $(git tag -l 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -rV); do
          v=$(git show "$t:server/typescript/packages/cli/package.json" 2>/dev/null \
              | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) || true
          if [ "v$v" = "$t" ]; then TAG="$t"; break; fi
        done
        test -n "$TAG" || { echo "no npm-line release tag found"; exit 1; }
        echo "pinned to metaobjects $TAG"
        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

        # /assess.md is the SAME text as the fit-assessment skill, minus the skill's YAML
        # frontmatter and the maintainer comment above its first heading — so it is copied
        # here for exactly the reason the llms mirrors are. It was hand-maintained instead,
        # and drifted to 519 lines against the skill's 565, still telling every reader it
        # was grounded against npm `0.15.x` / Maven `7.7.x`. That page is the acquisition
        # surface: it is what an evaluator's agent fetches before adopting anything.
        #
        # `sed` from the first top-level heading, rather than matching the title text, so a
        # retitle does not silently truncate the page. An empty result means the skill was
        # restructured — warn, and leave the page missing rather than publish a blank one.
        SKILL=agent-context/skills/metaobjects-fit-assessment/SKILL.md
        if [ -f "$SKILL" ] && sed -n '/^# /,$p' "$SKILL" > /tmp/assess.md && [ -s /tmp/assess.md ]; then
          cp /tmp/assess.md "$GITHUB_WORKSPACE/www/assess.md"
          echo "copied assess.md from metaobjects $TAG ($(wc -l < /tmp/assess.md) lines)"
        else
          echo "::warning::metaobjects $TAG has no usable fit-assessment skill — /assess.md 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