build(site): build landing data and docs from the latest uptide release

[lucasbraum]

The landing page's data and the docs are now built from the latest published release of uptide, not from main.

Build log (this branch, run locally)

uptide source: uptide 0.6.1: npm latest, tag v0.6.1 (7df8235)
docs: 41 pages from https://github.com/uptide-dev/uptide@7df8235 (v0.6.1)
[build] Complete!
site: /home/user/uptide-dev.github.io/_site (landing at /, docs at /docs/)
site: built from uptide 0.6.1: npm latest, tag v0.6.1 (7df8235)
site: 4 verified packs (ai, react, stripe, zod)
site: deployable: yes
links: 2668 internal links on 45 pages, none broken

The step outputs it writes for the workflow:

version=0.6.1
ref=v0.6.1
sha=7df82351c5c53eac78949b472966dceb8a0a169c
release=true

How the release is resolved

docs-site/scripts/release.mjs:

1. Version: asks npm for the latest dist-tag of uptide (/-/package/uptide/dist-tags). Today that is 0.6.1, published 2026-10-10.
2. Tag: looks up tag v<version> with an anonymous git ls-remote. A missing tag fails the build, and nothing falls back to main:

   fetch-docs: uptide 9.9.9 is the latest release on npm, but https://github.com/uptide-dev/uptide.git has no tag v9.9.9. The site is built from release tags only and does not fall back to main: push the tag, or run the Pages workflow by hand with a `ref` to preview another ref.
   

   (That message is from a real run against a local registry answering latest: 9.9.9.) npm being unreachable, a non-200 answer, or no usable latest also fails the build, with the URL in the message.
3. Checkout: a shallow fetch of exactly refs/tags/v<version>.
4. Consistency: the tag's packages/cli/package.json must say the same version as npm.

Where the version shows

• Build log: the lines above, plus a job summary in Actions ("uptide 0.6.1 (v0.6.1)").
• Meta tags: every built page (landing, 404 and all docs pages) carries:

  <meta name="uptide-version" content="0.6.1">
  <meta name="uptide-ref" content="v0.6.1">
  <meta name="uptide-commit" content="7df82351c5c53eac78949b472966dceb8a0a169c">

• Docs links: links into the repository now point at blob/v0.6.1/…. "Edit page" still opens main, since a tag can't be edited.

Workflow

• Triggers: unchanged. Push to main, daily at 05:23 UTC (a new release reaches the site within a day), and workflow_dispatch.
• New ref input: workflow_dispatch takes an optional ref (default empty) for previews: a branch, tag or commit of uptide-dev/uptide.
• Two jobs: pages.yml is now split into build and deploy:
  • build has contents: read only. It builds, checks links, and uploads the github-pages artifact.
  • deploy has pages: write / id-token: write, and its only step is actions/deploy-pages. It runs only if needs.build.outputs.release == 'true' && (github.event_name != 'workflow_dispatch' || inputs.ref == '').
• Two independent guards against deploying a preview:
  • The build itself reports release=true only when it built from the npm release tag. UPTIDE_REF or a local checkout gives release=false.
  • Any manual run with a ref is refused by the condition, whatever the build says.
• Ref handling: the input reaches the build only through env: UPTIDE_REF: ${{ inputs.ref }}, never pasted into a script. It is validated as a ref name, so main\nrelease=true is rejected. release= is also written last to $GITHUB_OUTPUT.
• Concurrency: previews use their own group, so they don't queue behind deploys.

Checks

• Build: the full build and link check against 0.6.1 (above). The terminal blocks and packs table pass their source checks against the v0.6.1 tag.
• Preview path: run for real with UPTIDE_REF=main. It builds, the meta tag says uptide-ref="main", and the output is release=false.
• Lighthouse accessibility: unchanged at 100 on /, /404.html, /docs/ and /docs/commands/fix/, in light and dark, with mobile and desktop presets.
• Tests: node --test 'test/*.test.mjs' passes 28 tests. The new test/release.test.mjs covers:
  • version resolution: from a mocked npm response, including 503, non-JSON, missing latest, a non-version latest, and offline;
  • the tag lookup: v0.6.10 does not pass for v0.6.1;
  • the missing-tag failure: naming the version and tag, with no fallback to main;
  • previews: they never ask npm and are never deployable; bad refs are rejected;
  • the meta tags;
  • the deploy guard: asserted from pages.yml. I checked the assertions by weakening the guard three ways (dropping the release check, dropping needs: build, hardcoding UPTIDE_REF); each mutation fails the tests.

Notes

• Previews: a manual run with ref shows "Preview built from …: uploaded as an artifact, not deployed." in the job summary. The site is in the run's github-pages artifact.
• CI: the site job in ci.yml is unchanged and now builds PRs against the release too.
• Blocked deploys: if a release is published to npm before its tag is pushed, daily and push deploys fail until the tag exists. The live site keeps showing the previous release in the meantime.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VcwhsQvN6vtpRCe4uwfe8z

---

Generated by Claude Code