dennisonbertram Deploy Check
Instrument a frontend app with subtle version fingerprinting — a <meta> tag in the HTML and a /__version JSON endpoint — so automated testing (ux-walker, CI, curl) can confirm the correct build is deployed before testing begins.
Usage
/deploy-check [--install] [--verify url] [--expected-sha sha]
| Parameter | Default | Notes |
|---|---|---|
| --install | Auto-detect | Instrument the current project with version fingerprinting |
| --verify url | None | Check a running app and report what version is deployed |
| --expected-sha sha | Current HEAD | Fail if the deployed SHA doesn't match |
If no flags given, auto-detect: if the project already has fingerprinting, run --verify; otherwise run --install.
What Gets Installed
1. Meta Tag
A <meta> tag injected into the HTML <head> at build time:
<meta name="build-version" content="sha:a1b2c3d timestamp:2026-06-08T12:00:00Z" />
Invisible to users. Readable by agent-browser:
agent-browser snapshot -i | grep 'build-version'
# or via JavaScript:
agent-browser js "document.querySelector('meta[name=build-version]')?.content"
2. Version Endpoint
A /__version route returning JSON:
{
"git_sha": "a1b2c3d",
"git_branch": "main",
"build_timestamp": "2026-06-08T12:00:00Z",
"version": "1.2.3",
"dirty": false
}
Readable by curl, fetch, or any HTTP client:
curl -s http://localhost:3000/__version | jq .
3. Build-time Script
A scripts/version-stamp.sh that generates a version.json at build time:
#!/usr/bin/env bash
set -euo pipefail
cat > "${1:-public/version.json}" <<JSON
{
"git_sha": "$(git rev-parse --short HEAD)",
"git_branch": "$(git rev-parse --abbrev-ref HEAD)",
"build_timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"version": "$(node -p "require('./package.json').version" 2>/dev/null || echo "0.0.0")",
"dirty": $(git diff --quiet && echo false || echo true)
}
JSON
Install Mode (--install)
Detect the framework and instrument accordingly. The orchestrator performs all steps directly — no sub-agents needed.
Step 1: Detect Framework
Read package.json and project structure to identify the framework:
| Signal | Framework |
|---|---|
next in dependencies |
Next.js |
vite in devDependencies |
Vite (React/Vue/Svelte) |
@remix-run/dev in dependencies |
Remix |
@angular/core in dependencies |
Angular |
gatsby in dependencies |
Gatsby |
astro in dependencies |
Astro |
nuxt in dependencies |
Nuxt |
| None of the above | Generic static / Express |
Step 2: Create Version Stamp Script
Write scripts/version-stamp.sh (see template above). Make it executable.
Step 3: Framework-Specific Instrumentation
Next.js
Meta tag — add to the root layout (app/layout.tsx or pages/_document.tsx):
import versionData from '../../public/version.json';
// In the <head>:
<meta name="build-version" content={`sha:${versionData.git_sha} timestamp:${versionData.build_timestamp}`} />
Endpoint — create app/api/__version/route.ts (App Router) or pages/api/__version.ts (Pages Router):
import { NextResponse } from 'next/server';
import versionData from '../../../public/version.json';
export async function GET() {
return NextResponse.json(versionData);
}
Build hook — add to package.json scripts:
{
"prebuild": "bash scripts/version-stamp.sh public/version.json",
"predev": "bash scripts/version-stamp.sh public/version.json"
}
Vite (React / Vue / Svelte)
Meta tag — add to index.html:
<!-- In <head>, replaced at build time by vite plugin or prebuild -->
<meta name="build-version" content="__BUILD_VERSION__" />
Create or update vite.config.ts to replace the placeholder:
import { defineConfig } from 'vite';
import fs from 'fs';
export default defineConfig({
define: {
__BUILD_VERSION__: JSON.stringify(
(() => {
try {
const v = JSON.parse(fs.readFileSync('public/version.json', 'utf-8'));
return `sha:${v.git_sha} timestamp:${v.build_timestamp}`;
} catch { return 'unknown'; }
})()
),
},
});
Endpoint — Vite dev server middleware via plugin, or just serve public/version.json directly at /__version via a simple redirect/rewrite.
Build hook:
{
"prebuild": "bash scripts/version-stamp.sh public/version.json",
"predev": "bash scripts/version-stamp.sh public/version.json"
}
Remix
Meta tag — add to app/root.tsx via the meta export or a direct <meta> in the <head>.
Endpoint — create app/routes/__version.ts:
import { json } from '@remix-run/node';
import versionData from '../../public/version.json';
export function loader() {
return json(versionData);
}
Generic / Express / Static
Meta tag — find the main HTML file (index.html, public/index.html) and inject the meta tag.
Endpoint — if Express detected (express in dependencies), add middleware:
import versionData from './public/version.json';
app.get('/__version', (req, res) => res.json(versionData));
If static site, the public/version.json file is the endpoint — instruct the user to access it at /version.json.
Step 4: Update .gitignore
Add public/version.json to .gitignore — it's generated at build time, not committed.
Step 5: Verify Installation
# Generate the version stamp
bash scripts/version-stamp.sh public/version.json
# Check it was created
cat public/version.json
Report what was installed and which files were modified.
Verify Mode (--verify)
Check a running app to confirm the deployed version matches expectations. This is what ux-walker calls before walking.
Step 1: Read Version from Meta Tag
agent-browser open "{url}"
agent-browser js "document.querySelector('meta[name=\"build-version\"]')?.content"
Parse sha:XXXXXX timestamp:YYYY-MM-DDTHH:MM:SSZ from the result.
Step 2: Read Version from Endpoint
curl -s "{url}/__version" 2>/dev/null || curl -s "{url}/version.json" 2>/dev/null
Parse the JSON response.
Step 3: Compare Against Expected
If --expected-sha was provided, compare. Otherwise compare against git rev-parse --short HEAD.
Output:
Deploy Check Results
────────────────────
Meta tag SHA: a1b2c3d ✓
Endpoint SHA: a1b2c3d ✓
Expected SHA: a1b2c3d ✓
Branch: main
Build timestamp: 2026-06-08T12:00:00Z
Dirty: false
Status: VERIFIED — correct version deployed
If mismatch:
Deploy Check Results
────────────────────
Meta tag SHA: a1b2c3d ✗
Expected SHA: f4e5d6c
Status: MISMATCH — deployed version does not match HEAD
The app is running an older build. Rebuild and redeploy,
or pass --expected-sha a1b2c3d to accept this version.
Step 4: Return Verdict
Return a structured result that callers (ux-walker, CI) can act on:
{
"status": "verified",
"deployed_sha": "a1b2c3d",
"expected_sha": "a1b2c3d",
"match": true,
"branch": "main",
"build_timestamp": "2026-06-08T12:00:00Z",
"dirty": false
}
Integration with UX Walker
When ux-walker runs its Phase 0 Preflight, it should call deploy-check verify:
Phase 0 — Preflight
├── 0.1 URL Check (existing)
├── 0.1.5 Deploy Check ← NEW
│ └── curl {url}/__version or read meta tag
│ └── Compare SHA against git rev-parse --short HEAD
│ └── If mismatch: warn but continue (don't block — the user may be testing an older deploy intentionally)
│ └── If missing: note "No version fingerprint found — run /deploy-check --install to add one"
├── 0.2 Catalog Check (existing)
└── ...
The version check is advisory, not blocking — if the fingerprint is missing or mismatched, ux-walker warns but proceeds. The user can install fingerprinting with /deploy-check --install when ready.
Constraints
- Never commit
public/version.json— it's build-time generated - The meta tag must be invisible to end users (no visible UI element)
- The
/__versionendpoint must not leak sensitive information (no env vars, no secrets, no internal paths) - Framework detection must not modify files outside the project
- The version stamp script must work on macOS and Linux (use portable
dateflags) - If the project already has version fingerprinting (e.g., Sentry release, DataDog RUM version), detect it and integrate rather than duplicate