build: fail when the committed web bundle is stale

apps/pythinker-code/dist-web is generated from apps/pythinker-web and read by
no other gate, so editing the web UI without rebuilding shipped a CLI whose
embedded UI silently lagged its own source, with nothing red anywhere. The
existing check only asserted the bundle was present, and nothing invoked it.

copy-web-assets now records a fingerprint of every build input in the bundle
and check-web-assets recomputes it, so a stale bundle fails. It runs in
pre-push, in the CLI build, and on prepack. `pnpm run build:web` rebuilds and
restages in one step.

Author: elkaix

AGENTS.md

@@ -69,7 +69,7 @@ Adding an OpenAI-compatible provider requires **zero code changes** — just add
 | `packages/pi-tui` | Vendored TUI library | Upstream fork with local divergences; tests run with `node --test`, not vitest. See its `AGENTS.md`. |
 | `packages/protocol` | Shared REST + WS protocol schemas | Envelope, error codes, pagination, WS-control types. |
 
-The web bundle: `apps/pythinker-code/dist-web` is the committed, prebuilt bundle of `apps/pythinker-web` (built with `pnpm --filter @pymodel/pythinker-web run build` and copied via `scripts/copy-web-assets.mjs`). `apps/pythinker-code/scripts/check-web-assets.mjs` guards packaging against a missing bundle — sync and commit the bundle in the same change whenever the web UI should ship differently. `packages/server` and `packages/server-e2e` are empty leftover directories excluded from the workspace — not packages.
+The web bundle: `apps/pythinker-code/dist-web` is the committed, prebuilt bundle of `apps/pythinker-web` (built with `pnpm --filter @pymodel/pythinker-web run build` and copied via `scripts/copy-web-assets.mjs`). `apps/pythinker-code/scripts/check-web-assets.mjs` fails when the bundle is missing **or stale** (it compares a fingerprint of every `apps/pythinker-web` build input against the one recorded at copy time); it runs in pre-push, in the CLI `build`, and on `prepack`. Whenever you touch the web UI, run `pnpm run build:web` and commit the restaged bundle in the same change. `packages/server` and `packages/server-e2e` are empty leftover directories excluded from the workspace — not packages.
 
 ## Environment
 

apps/pythinker-code/package.json

@@ -50,7 +50,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "pnpm -C ../pythinker-web run build && tsdown && tsdown --config tsdown.dist-worker.config.ts && node scripts/copy-native-assets.mjs && node scripts/copy-web-assets.mjs",
+    "build": "pnpm -C ../pythinker-web run build && tsdown && tsdown --config tsdown.dist-worker.config.ts && node scripts/copy-native-assets.mjs && node scripts/copy-web-assets.mjs && node scripts/check-web-assets.mjs",
     "prebuild": "node scripts/build-vis-asset.mjs",
     "catalog:update": "node scripts/update-catalog.mjs --out dist/built-in-catalog.json",
     "smoke": "node scripts/smoke.mjs",
@@ -75,7 +75,8 @@
     "test": "pnpm -w run build:packages && vitest run",
     "e2e": "pnpm -w run build:packages && PYTHINKER_E2E=1 vitest run test/e2e",
     "e2e:real": "pnpm -w run build:packages && PYTHINKER_E2E_REAL=1 vitest run test/e2e/real-llm-smoke.e2e.test.ts",
-    "postinstall": "node scripts/postinstall.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepack": "node scripts/check-web-assets.mjs"
   },
   "optionalDependencies": {
     "@mariozechner/clipboard": "^0.3.9",

apps/pythinker-code/scripts/check-web-assets.mjs

@@ -1,17 +1,23 @@
-// Verify the built web bundle is present before packaging.
+// Verify the committed web bundle is present AND current.
 //
 // This repo keeps the web UI source at apps/pythinker-web. The bundle is
 // staged at apps/pythinker-code/dist-web by scripts/copy-web-assets.mjs after
-// a web build. This check only asserts the staged bundle is in place, so a
-// packaging run never silently ships a CLI without the web UI.
+// a web build. Presence alone is not enough: no other gate reads the bundle,
+// so editing the web source without rebuilding ships a CLI whose embedded UI
+// lags its own source, with nothing red to show for it. Compare the source
+// fingerprint recorded at copy time against the current source.
 
-import { readdir, stat } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { MANIFEST_NAME, computeWebInputHash } from './web-bundle-manifest.mjs';
+
 const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const target = resolve(appRoot, 'dist-web');
 
+const REBUILD = 'Run `pnpm run build:web` to rebuild and restage it.';
+
 async function assertWebAssets() {
   try {
     const info = await stat(resolve(target, 'index.html'));
@@ -27,6 +33,30 @@ async function assertWebAssets() {
   }
 }
 
+async function assertWebAssetsCurrent() {
+  const manifestPath = resolve(target, MANIFEST_NAME);
+  let recorded;
+  try {
+    recorded = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch {
+    throw new Error(
+      `The staged web bundle has no ${MANIFEST_NAME}, so it cannot be checked ` +
+        `against apps/pythinker-web. ${REBUILD}`,
+    );
+  }
+  const { hash, fileCount } = await computeWebInputHash();
+  if (recorded.sourceHash !== hash) {
+    throw new Error(
+      'The committed web bundle is stale: apps/pythinker-web has changed since ' +
+        `it was built (bundle ${String(recorded.sourceHash).slice(0, 12)}, ` +
+        `source ${hash.slice(0, 12)}; ${recorded.sourceFileCount} -> ${fileCount} files). ` +
+        REBUILD,
+    );
+  }
+  return hash;
+}
+
 await assertWebAssets();
+const sourceHash = await assertWebAssetsCurrent();
 const files = await readdir(target, { recursive: true });
-console.log(`Web assets OK: ${target} (${files.length} entries)`);
+console.log(`Web assets OK: ${target} (${files.length} entries, source ${sourceHash.slice(0, 12)})`);

apps/pythinker-code/scripts/copy-web-assets.mjs

@@ -1,7 +1,9 @@
-import { cp, rm, stat } from 'node:fs/promises';
+import { cp, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { MANIFEST_NAME, computeWebInputHash } from './web-bundle-manifest.mjs';
+
 const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repoRoot = resolve(appRoot, '../..');
 const source = resolve(repoRoot, 'apps/pythinker-web/dist');
@@ -21,7 +23,14 @@ async function assertBuiltWeb() {
 }
 
 await assertBuiltWeb();
+// Fingerprint the source that produced this bundle, so check-web-assets.mjs
+// can tell a stale committed bundle from a current one.
+const { hash, fileCount } = await computeWebInputHash();
 await rm(target, { recursive: true, force: true });
 await cp(source, target, { recursive: true });
+await writeFile(
+  resolve(target, MANIFEST_NAME),
+  `${JSON.stringify({ sourceHash: hash, sourceFileCount: fileCount }, null, 2)}\n`,
+);
 
-console.log(`Copied Pythinker web assets to ${target}`);
+console.log(`Copied Pythinker web assets to ${target} (source ${hash.slice(0, 12)}, ${fileCount} files)`);

apps/pythinker-code/scripts/web-bundle-manifest.mjs

@@ -0,0 +1,60 @@
+// Shared fingerprint of the web UI's build inputs.
+//
+// The committed bundle at apps/pythinker-code/dist-web is generated from
+// apps/pythinker-web. Nothing in the type-check, lint, or test gates reads the
+// bundle, so editing the web source and forgetting to rebuild ships a CLI whose
+// embedded UI silently lags the source — a class of bug that reaches users and
+// leaves no trace in CI. copy-web-assets.mjs stamps this fingerprint into the
+// bundle; check-web-assets.mjs recomputes it and fails on a mismatch.
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { globSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const repoRoot = resolve(appRoot, '../..');
+export const webRoot = resolve(repoRoot, 'apps/pythinker-web');
+export const bundleRoot = resolve(appRoot, 'dist-web');
+export const MANIFEST_NAME = '.web-bundle-manifest.json';
+
+// Everything the Vite build reads. `public/` is copied verbatim into the
+// bundle, and the configs decide how the source is compiled, so a change to
+// any of them makes the committed bundle stale.
+const INPUT_GLOBS = [
+  'src/**/*',
+  'public/**/*',
+  'index.html',
+  'vite.config.ts',
+  'tsconfig.json',
+  'package.json',
+];
+
+/** Sorted list of build-input paths, relative to apps/pythinker-web. */
+export function webInputFiles() {
+  const seen = new Set();
+  for (const pattern of INPUT_GLOBS) {
+    for (const file of globSync(pattern, { cwd: webRoot })) {
+      const normalized = file.split('\\').join('/');
+      if (statSync(resolve(webRoot, normalized)).isFile()) seen.add(normalized);
+    }
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Content hash over every build input. Path-and-content, so a rename with
+ * identical bytes still changes the fingerprint.
+ */
+export async function computeWebInputHash() {
+  const files = webInputFiles();
+  const digest = createHash('sha256');
+  for (const file of files) {
+    digest.update(file);
+    digest.update('\0');
+    digest.update(await readFile(resolve(webRoot, file)));
+    digest.update('\0');
+  }
+  return { hash: digest.digest('hex'), fileCount: files.length };
+}

package.json

@@ -11,6 +11,8 @@
     "dev:cli": "pnpm -C apps/pythinker-code run dev",
     "dev:desktop": "pnpm -C apps/desktop run dev",
     "dev:web": "pnpm -C apps/pythinker-web run dev",
+    "build:web": "pnpm --filter @pymodel/pythinker-web run build && node apps/pythinker-code/scripts/copy-web-assets.mjs",
+    "check:web": "node apps/pythinker-code/scripts/check-web-assets.mjs",
     "package:desktop": "pnpm -C apps/desktop run package",
     "dist:mac:desktop": "pnpm -C apps/desktop run dist:mac",
     "dist:win:desktop": "pnpm -C apps/desktop run dist:win",

scripts/pre-push.sh

@@ -65,11 +65,17 @@ step "sherif" pnpm run sherif || fail "sherif" "monorepo dependency versions are
 # 3. oxlint (CI: `pnpm run lint`).
 step "lint" pnpm run lint || fail "lint" "oxlint reported errors"
 
-# 4. Nix fetchPnpmDeps hash freshness proxy (CI: nix build).
+# 4. Committed web bundle freshness. apps/pythinker-code/dist-web is generated
+#    from apps/pythinker-web and read by no other gate, so a web source edit
+#    without a rebuild ships a stale embedded UI with nothing red to show for it.
+step "web-bundle-freshness" node apps/pythinker-code/scripts/check-web-assets.mjs ||
+  fail "build" "apps/pythinker-web changed without restaging dist-web (run 'pnpm run build:web')"
+
+# 5. Nix fetchPnpmDeps hash freshness proxy (CI: nix build).
 step "nix-hash-freshness" node scripts/check-nix-hash-fresh.mjs ||
   fail "nix build (flake.nix)" "pnpm-lock.yaml changed without refreshing flake.nix's pnpmDeps hash"
 
-# 5. Typecheck, scoped to packages changed since $base_ref (CI: `pnpm run
+# 6. Typecheck, scoped to packages changed since $base_ref (CI: `pnpm run
 #    typecheck`). Full typecheck builds every package first and takes
 #    minutes — not affordable pre-push, so this narrows to what pnpm's own
 #    dependency graph says was actually touched.
@@ -81,7 +87,7 @@ else
   echo "[pre-push] run 'pnpm run typecheck' manually before pushing if you touched types."
 fi
 
-# 6. Tests, scoped via vitest's own changed-file impact analysis (CI: `pnpm test`).
+# 7. Tests, scoped via vitest's own changed-file impact analysis (CI: `pnpm test`).
 if [[ -n "$base_ref" ]]; then
   step "test (changed)" pnpm exec vitest run --changed "$base_ref" --passWithNoTests ||
     fail "test" "tests affected by changed files are failing"