fix(serve): hard-fail when build is stale vs current config

[sauravvarma]

Summary

• Tracks PUBLIC_STATIC_ASSET_URL and PUBLIC_STATIC_ASSET_PATH in BUILD_OUTPUT_PATH/build-meta.json at build time (the values webpack embeds into the client bundle via publicPath + DefinePlugin).
• On catalyst serve startup, compares the embedded values against the current config/config.json and exits with a clear diff message on mismatch.
• Missing build-meta.json (older builds) emits a warning and proceeds — no break for existing deployments.

Closes #251.

Why

catalyst serve currently re-reads config.json for the boot log and NODE_SERVER_HOSTNAME/PORT, but the asset host that ends up in the served HTML was frozen at build time. When config changes between build and serve (common when local IP changes), serve logs Local: http://<new-host> while the HTML still references chunks at the old host. On a device this looks like "page loads, no JS/CSS" with no signal from the serve process.

Behavior

Before (config changed from A to B after the build, then npm run serve):

Local: http://B:3005

…and the HTML embeds http://A:3005/assets/runtime.*.js. Silent stale serve.

After:

[serve] Build is stale relative to config/config.json.

The following values were baked into the build but differ from the current config:

  PUBLIC_STATIC_ASSET_URL
    built with: http://A:3005
    config now: http://B:3005

These values are embedded into client assets at build time, so serving this build
would reference assets at the old host. Run npm run build to rebuild.

Exit code 1.

Test plan

• npm run build in a fixture app writes build/build-meta.json with current PUBLIC_STATIC_ASSET_URL / PUBLIC_STATIC_ASSET_PATH.
• npm run serve with matching config starts normally.
• Mutate PUBLIC_STATIC_ASSET_URL in config/config.json and re-run npm run serve — exits non-zero with the diff message above, no server process spawned.
• Delete build/build-meta.json and re-run npm run serve — emits the "skipping check" warning and proceeds (backwards-compat with builds from prior versions).

Notes / open questions

• Hard-fail is intentional: the bug is precisely that the broken state was silent. Happy to convert to warn-and-continue or gate behind a --allow-stale-build flag if maintainers prefer.
• Currently only the two PUBLIC_STATIC_ASSET_* keys are tracked. CLIENT_ENV_VARIABLES values are also embedded via DefinePlugin; extending the check to those is a small follow-up if desired.

🤖 Generated with Claude Code

[deputydev-agent]

DeputyDev will no longer review pull requests automatically.To request a review, simply comment #review on your pull request—this will trigger an on-demand review whenever you need it.