Fix CI/CD

Author: N2D4

.claude/CLAUDE-KNOWLEDGE.md

@@ -394,3 +394,6 @@ A: The environment override endpoint validates the new environment override agai
 
 ## Q: Why can `pnpm run dev` fail with `ERR_MODULE_NOT_FOUND` for `@stackframe/stack/dist/esm/index.js` during OpenAPI docs generation?
 A: Root `dev` starts the OpenAPI docs watcher at the same time as package `dev` watchers. If a package `dev` script removes `dist` before `tsdown --watch` recreates it, the docs generator can import `apps/backend/src/stack.tsx` while `@stackframe/stack`'s ESM entrypoint is temporarily missing. Package watch scripts should update `dist` in place, and eager generators should wait for package imports to resolve before running.
+
+## Q: How do SDK source tests replace the compile-time client version sentinel?
+A: `packages/template/vitest.config.ts` installs a Vite transform plugin for Vitest that replaces `STACK_COMPILE_TIME_CLIENT_PACKAGE_VERSION_SENTINEL` with `js <package-name>@<version>` from the local package.json. Keep the plugin in `packages/template` so `pnpm pre`/`scripts/generate-sdks.ts` propagates it to `packages/js`, `packages/react`, and `packages/stack`; otherwise tests importing `common.ts` throw `Client version was not replaced` before test collection.

packages/template/vitest.config.ts

@@ -1,7 +1,50 @@
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { defineConfig, mergeConfig } from 'vitest/config'
 import sharedConfig from '../../vitest.shared'
 
+const SOURCE_FILE_PATTERN = /\.(jsx?|tsx?)$/;
+const CLIENT_VERSION_SENTINEL = "STACK_COMPILE_TIME_CLIENT_PACKAGE_VERSION_SENTINEL";
+const ENFORCE_PRE: "pre" = "pre";
+
+function getPackageVersionLabel() {
+  const packageJson: unknown = JSON.parse(fs.readFileSync(fileURLToPath(new URL("./package.json", import.meta.url)), "utf-8"));
+  if (
+    typeof packageJson !== "object"
+    || packageJson === null
+    || !("name" in packageJson)
+    || typeof packageJson.name !== "string"
+    || !("version" in packageJson)
+    || typeof packageJson.version !== "string"
+  ) {
+    throw new Error("Expected package.json to include string name and version fields.");
+  }
+
+  return `js ${packageJson.name}@${packageJson.version}`;
+}
+
+const replaceCompileTimeClientVersion = () => {
+  const packageVersionLabel = getPackageVersionLabel();
+  return {
+    name: 'stackframe vitest client version replacement',
+    enforce: ENFORCE_PRE,
+    transform(code: string, id: string) {
+      const filePath = id.split(/[?#]/, 1)[0];
+      if (!SOURCE_FILE_PATTERN.test(filePath) || !code.includes(CLIENT_VERSION_SENTINEL)) {
+        return null;
+      }
+
+      return {
+        code: code.replaceAll(CLIENT_VERSION_SENTINEL, packageVersionLabel),
+        map: null,
+      };
+    },
+  };
+};
+
 export default mergeConfig(
   sharedConfig,
-  defineConfig({}),
+  defineConfig({
+    plugins: [replaceCompileTimeClientVersion()],
+  }),
 )