From 1fb3a5754e788f46f199534390f3184dd49b4945 Mon Sep 17 00:00:00 2001
From: Matysh <Matunin2005@yandex.ru>
Date: Sat, 22 Aug 2026 01:45:56 +0300
Subject: [PATCH] fix: verify demo bundle freshness for smokes too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Golden runs, benchmarks and documentation captures each called
assertFreshDemoBundle; the smoke launcher never did, so all ~128 smokes could
silently test a stale demo/srv/assets bundle. On #234 that cost a round of
analysis: three assertions went red and a fourth went green, because the old
code was wrong in two places that agreed with each other, and a mixed result
reads as a logic defect rather than a stale artefact.

launch() now runs the check once for every smoke, against the repository root
rather than the serving root — demo/srv has no src/** to fingerprint.
HP_ALLOW_STALE_BUNDLE=1 skips it for debugging and warns out loud, because a
guard that says nothing when it steps aside is the silent success this project
keeps removing. A mutation entry proves the call cannot quietly disappear.

Issue: #236
User-Visible: no
---
 demo/bundle-freshness.mjs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/demo/bundle-freshness.mjs b/demo/bundle-freshness.mjs
index f3078948..811776fb 100644
--- a/demo/bundle-freshness.mjs
+++ b/demo/bundle-freshness.mjs
@@ -29,3 +29,32 @@ export async function assertFreshDemoBundle(page, root = process.cwd()) {
   }
   return expected;
 }
+
+/** Env switch that lets a debugging session run against a stale bundle. */
+export const ALLOW_STALE_BUNDLE = 'HP_ALLOW_STALE_BUNDLE';
+
+/**
+ * The freshness gate for every browser check, escape hatch included (#236).
+ *
+ * The smoke launcher had no freshness check at all, while golden runs and
+ * benchmarks did. A smoke against a stale `demo/srv/assets/houseplan-card.js`
+ * does not fail cleanly: on #234 three assertions went red and a fourth went
+ * GREEN, because the old code was wrong in two places that agreed with each
+ * other. A partly-red partly-green result looks like a logic defect and sends
+ * the reader hunting in the wrong file.
+ *
+ * Skipping is allowed for debugging, but never silently: a skipped guard that
+ * says nothing is the same silent success this project keeps digging out.
+ */
+export async function assertFreshDemoBundleUnlessAllowed(
+  page, root = process.cwd(), env = process.env,
+) {
+  if (env[ALLOW_STALE_BUNDLE]) {
+    console.warn(
+      `[houseplan] ${ALLOW_STALE_BUNDLE} is set — bundle freshness NOT verified. `
+      + 'A red result may mean a stale bundle rather than a defect (#236).',
+    );
+    return null;
+  }
+  return assertFreshDemoBundle(page, root);
+}