Skip to content

Detect stale docs.livestore.dev deploys via version meta tag - #1290

Draft
schickling-assistant wants to merge 1 commit into
mainfrom
schickling-assistant/2026-06-03-health-docs-version
Draft

Detect stale docs.livestore.dev deploys via version meta tag#1290
schickling-assistant wants to merge 1 commit into
mainfrom
schickling-assistant/2026-06-03-health-docs-version

Conversation

@schickling-assistant

Copy link
Copy Markdown
Collaborator

Problem

`https://docs.livestore.dev\` can fall behind the latest LiveStore release if the Netlify deploy fails or never runs. Nothing currently surfaces a stale docs deploy until a user complains.

Solution

  1. Docs build emits `<meta name="livestore-version" content="…">` from `docs/astro.config.ts` (Starlight `head` option). This is a stable, machine-readable marker reserved for the health check so renaming the site title can't accidentally break the probe.
  2. Daily workflow (09:15 Europe/Berlin) + GitHub Release `published` hook + manual dispatch fetches the docs landing page, parses the meta tag, and compares it against npm `latest`.

Behaviour:

  • match: `::notice::docs version matches npm latest`.
  • release-triggered mismatch within 30m of `published_at`: notice only (lets the docs deploy catch up).
  • otherwise: opens (or warms) a `bug docs` issue titled `docs.livestore.dev version drifted from npm latest`.

Deferred sub-features

  • Auto-trigger docs redeploy on mismatch: the spec mentioned dispatching `deploy-prod.yml` with `target=docs`; this workflow does not exist in the repo today (docs go through Netlify), so the check escalates by opening an issue instead of silently re-triggering deploys.
  • Discord `#release-alerts` notification: no Discord webhook secret is configured in the repo (`gh secret list` confirmed), so the check relies on the GitHub issue alone. If a webhook is added later, hook it in alongside `openIssue()` in `scripts/src/commands/health/docs-version.ts`.

Observation about existing version markers

Today the docs site only exposes the version through `og:site_name` (`LiveStore (0.4.0)`), which doubles as the human-readable site title. Tying a health check to a render-cosmetic string is fragile — hence the dedicated `livestore-version` meta tag.

Validation

  • `bun scripts/src/commands/health/docs-version.ts --trigger=workflow_dispatch --dry-run` runs locally; it correctly detects that production currently lacks the meta tag (it will once this PR ships).
  • `devenv tasks run lint:check` passes.
  • `devenv tasks run genie:run --mode before --no-tui` regenerates the workflow cleanly.

Files

  • `docs/astro.config.ts` — adds the `head` option emitting the meta tag.
  • `.github/workflows/health-docs-version.yml.genie.ts` — workflow source.
  • `scripts/src/commands/health/docs-version.ts` — fetch + compare + issue management.
  • `CHANGELOG.md` — entry under `### Internal Changes > Development Tooling`.

🤖 Generated with Claude Code

Adds a `<meta name="livestore-version" content="…">` tag to the docs
site build (via `docs/astro.config.ts`) and a daily health workflow
that compares it against npm `latest`. Mismatch outside a 30m grace
window after a GitHub Release opens (or warms) a `bug`-labelled issue.

The check also runs on release `published` events so a freshly cut
release that never made it to docs is surfaced quickly instead of
silently lagging behind npm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
agent-session-id: c1934b02-14a7-4f20-a3e4-9e7b987c77ab
agent-tool: Claude Code
agent-tool-version: 2.1.145
agent-model: claude-opus-4-7
tooling-profile: dotfiles@unknown-dirty
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant