veryfront 0.1.87 → 0.1.89

package/src/src/transforms/esm/http-cache-wrapper.ts

@@ -16,6 +16,7 @@ import { rendererLogger } from "../../utils/index.js";
 import { VERSION } from "../../utils/version.js";
 import { getCacheBaseDir } from "../../utils/cache-dir.js";
 import { CacheBackends, createDistributedCacheAccessor } from "../../cache/backend.js";
+import type { CacheBackend } from "../../cache/types.js";
 import { HTTP_MODULE_DISTRIBUTED_TTL_SEC } from "../../utils/constants/cache.js";
 import type {
   BundleHash,
@@ -44,6 +45,26 @@ const getDistributedCache = createDistributedCacheAccessor(
   "HTTP-CACHE-WRAPPER",
 );
 
+let testDistributedCacheAccessor: (() => Promise<CacheBackend | null>) | null = null;
+
+function resolveDistributedCache(): Promise<CacheBackend | null> {
+  return testDistributedCacheAccessor ? testDistributedCacheAccessor() : getDistributedCache();
+}
+
+export function __setDistributedCacheAccessorForTests(
+  accessor: (() => Promise<CacheBackend | null>) | null,
+): void {
+  testDistributedCacheAccessor = accessor;
+}
+
+export async function initializeHttpModuleDistributedCache(): Promise<boolean> {
+  const distributed = await resolveDistributedCache();
+  if (!distributed) return false;
+
+  logger.info("Initialized distributed cache backend", { backend: distributed.type });
+  return true;
+}
+
 /**
  * Generate versioned cache key for HTTP bundles.
  * Format: {VERSION}:{prefix}:{hash}
@@ -158,7 +179,7 @@ class HttpBundleCache {
    * @returns Result containing local code or failure reason
    */
   async getCodeByHash(hash: BundleHash | string): Promise<GetCodeResult> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) {
       return { code: null, wasGzipped: false, failReason: "not_found" };
     }
@@ -214,7 +235,7 @@ class HttpBundleCache {
    * @returns Result containing local code or failure reason
    */
   async getCodeByUrl(hash: BundleHash | string): Promise<GetCodeResult> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) {
       return { code: null, wasGzipped: false, failReason: "not_found" };
     }
@@ -265,7 +286,7 @@ class HttpBundleCache {
     url: NormalizedUrl | string,
     ttl: number = HTTP_MODULE_DISTRIBUTED_TTL_SEC,
   ): Promise<void> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) return;
 
     const hashStr = typeof hash === "string" ? hash : (hash as unknown as string);
@@ -305,7 +326,7 @@ class HttpBundleCache {
   async getBatchCodes(
     hashes: Array<BundleHash | string>,
   ): Promise<Map<string, LocalModuleCode>> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) return new Map();
 
     const results = new Map<string, LocalModuleCode>();
@@ -357,7 +378,7 @@ class HttpBundleCache {
    * @returns Original URL or null
    */
   async getOriginalUrl(hash: BundleHash | string): Promise<string | null> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) return null;
 
     const hashStr = typeof hash === "string" ? hash : (hash as unknown as string);
@@ -378,7 +399,7 @@ class HttpBundleCache {
    * @returns true if deletion was attempted, false if cache unavailable
    */
   async deleteCode(hash: BundleHash | string): Promise<boolean> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     if (!distributed) return false;
 
     const hashStr = typeof hash === "string" ? hash : (hash as unknown as string);
@@ -403,7 +424,7 @@ class HttpBundleCache {
    * Check if distributed cache is available.
    */
   async isAvailable(): Promise<boolean> {
-    const distributed = await getDistributedCache();
+    const distributed = await resolveDistributedCache();
     return distributed !== null;
   }
 }

package/src/src/transforms/mdx/esm-module-loader/cache/index.ts

@@ -18,9 +18,9 @@ import {
   type FileSystem,
   isNotFoundError,
 } from "../../../../platform/compat/fs.js";
-import { VERSION } from "../../../../utils/version.js";
 import { LOG_PREFIX_MDX_LOADER } from "../constants.js";
 import { LRUCache } from "../../../../utils/lru-wrapper.js";
+import { buildMdxEsmPathCacheKey, MDX_ESM_ALL_FILE_URL_PATTERN_SOURCE } from "../cache-format.js";
 
 export type CacheLookupResult =
   | { status: "hit"; path: string }
@@ -33,8 +33,6 @@ export const verifiedModuleDeps = new LRUCache<string, true>({
   maxEntries: MAX_VERIFIED_MODULE_DEPS,
 });
 
-const FILE_PATH_PATTERN = /file:\/\/([^"'\s]+)/gi;
-
 /**
  * Check if cached code has file:// paths from a different environment.
  * Checks both HTTP bundle paths and MDX ESM cache paths.
@@ -43,7 +41,7 @@ function hasIncompatibleCachePaths(code: string): boolean {
   const localCacheBaseDir = getCacheBaseDir();
   const localHttpCacheDir = getHttpBundleCacheDir();
   const localMdxCacheDir = getMdxEsmCacheDir();
-  const pattern = new RegExp(FILE_PATH_PATTERN.source, "gi");
+  const pattern = new RegExp(MDX_ESM_ALL_FILE_URL_PATTERN_SOURCE, "gi");
 
   let match: RegExpExecArray | null;
   while ((match = pattern.exec(code)) !== null) {
@@ -87,7 +85,7 @@ function hasIncompatibleCachePaths(code: string): boolean {
  */
 async function findMissingFileDependencies(code: string): Promise<string[]> {
   const localFs = getLocalFs();
-  const pattern = new RegExp(FILE_PATH_PATTERN.source, "gi");
+  const pattern = new RegExp(MDX_ESM_ALL_FILE_URL_PATTERN_SOURCE, "gi");
   const missing: string[] = [];
   let match;
   while ((match = pattern.exec(code)) !== null) {
@@ -335,7 +333,7 @@ function toMdxEsmCacheKey(filePath: string, projectDir?: string): string {
   relativePath = relativePath.replace(/^\/+/, "");
   const jsPath = relativePath.replace(/\.(tsx?|jsx|mdx)$/, ".js");
 
-  return `v${VERSION}:_vf_modules/${jsPath}`;
+  return buildMdxEsmPathCacheKey(`_vf_modules/${jsPath}`);
 }
 
 export async function lookupMdxEsmCache(
@@ -429,9 +427,9 @@ export async function lookupMdxEsmCache(
     }
 
     // Note: We intentionally skip contentHash validation for MDX-ESM cached files.
-    // The MDX-ESM cache uses transformed-code hashes in filenames (vfmod-v{VERSION}-{hash}.mjs),
+    // The MDX-ESM cache uses transformed-code hashes in namespaced filenames,
     // while the SSR loader provides source-code hashes. These will never match.
-    // The cache version in the key (v{VERSION}:) provides sufficient staleness protection,
+    // The cache namespace in the key provides sufficient staleness protection,
     // and the file's existence confirms it's a valid transform for this codebase.
     // This allows both loaders to share the same module instance, preventing
     // duplicate React contexts which break hooks like useContext.

package/src/src/transforms/mdx/esm-module-loader/cache-format.ts

@@ -0,0 +1,121 @@
+import { hashCodeHex } from "../../../utils/hash-utils.js";
+import { createCacheNamespace } from "../../../utils/cache-namespace.js";
+import { UNRESOLVED_VF_MODULES_PATTERN } from "./constants.js";
+import { hashString } from "./utils/hash.js";
+
+const ALL_FILE_URL_PATTERN_SOURCE = /file:\/\/([^"'\s]+)/.source;
+const MJS_FILE_URL_PATTERN_SOURCE = /file:\/\/([^"'\s]+\.mjs)/.source;
+const CACHE_NAMESPACE_SENTINEL = "__vf_cache_namespace__";
+
+function formatMdxEsmTransformCacheKey(
+  namespace: string,
+  projectId: string,
+  normalizedPath: string,
+  contentHash: string,
+): string {
+  return `${namespace}:${projectId}:${normalizedPath}:${contentHash}:ssr`;
+}
+
+function formatMdxEsmPathCacheKey(namespace: string, normalizedPath: string): string {
+  return `${namespace}:${normalizedPath}`;
+}
+
+function formatMdxEsmModuleFileName(namespace: string, contentHash: string): string {
+  return `vfmod-${namespace}-${contentHash}.mjs`;
+}
+
+function formatMdxJsxCacheFileName(namespace: string, filePath: string): string {
+  return `jsx-${namespace}-${hashString(filePath)}.mjs`;
+}
+
+function formatFrameworkVfModuleCacheFileName(
+  namespace: string,
+  pathHash: string,
+  envKey: string,
+  contentHash: string,
+): string {
+  return `vfmod-${namespace}-${pathHash}-${envKey}-${contentHash}.mjs`;
+}
+
+function buildMdxEsmCacheSchemaSample() {
+  return {
+    transformKey: formatMdxEsmTransformCacheKey(
+      CACHE_NAMESPACE_SENTINEL,
+      "__vf_project__",
+      "_vf_modules/pages/index.js",
+      "deadbeef",
+    ),
+    pathKey: formatMdxEsmPathCacheKey(CACHE_NAMESPACE_SENTINEL, "_vf_modules/pages/index.js"),
+    moduleFile: formatMdxEsmModuleFileName(CACHE_NAMESPACE_SENTINEL, "deadbeef"),
+    jsxFile: formatMdxJsxCacheFileName(CACHE_NAMESPACE_SENTINEL, "/tmp/project/Button.tsx"),
+    unresolvedVfModulesPattern: UNRESOLVED_VF_MODULES_PATTERN.source,
+    allFileUrlPattern: ALL_FILE_URL_PATTERN_SOURCE,
+    mjsFileUrlPattern: MJS_FILE_URL_PATTERN_SOURCE,
+    sourceHashing: [
+      hashString("_vf_modules/pages/index.jsexport default 1;"),
+      hashString("/tmp/project/Button.tsx"),
+    ],
+  };
+}
+
+function buildFrameworkVfModuleCacheSchemaSample() {
+  return {
+    moduleFile: formatFrameworkVfModuleCacheFileName(
+      CACHE_NAMESPACE_SENTINEL,
+      hashCodeHex("_vf_modules/_veryfront/react/components/Head.js"),
+      hashCodeHex("/app/.cache/veryfront-mdx-esm").slice(0, 8),
+      hashCodeHex("export default function Head() {}"),
+    ),
+  };
+}
+
+export const MDX_ESM_ALL_FILE_URL_PATTERN_SOURCE = ALL_FILE_URL_PATTERN_SOURCE;
+export const MDX_ESM_MJS_FILE_URL_PATTERN_SOURCE = MJS_FILE_URL_PATTERN_SOURCE;
+
+export const MDX_ESM_CACHE_NAMESPACE = createCacheNamespace(
+  "mdx-esm",
+  buildMdxEsmCacheSchemaSample(),
+);
+
+export const FRAMEWORK_VF_MODULE_CACHE_NAMESPACE = createCacheNamespace(
+  "vf-framework",
+  buildFrameworkVfModuleCacheSchemaSample(),
+);
+
+export function buildMdxEsmTransformCacheKey(
+  projectId: string,
+  normalizedPath: string,
+  contentHash: string,
+): string {
+  return formatMdxEsmTransformCacheKey(
+    MDX_ESM_CACHE_NAMESPACE,
+    projectId,
+    normalizedPath,
+    contentHash,
+  );
+}
+
+export function buildMdxEsmPathCacheKey(normalizedPath: string): string {
+  return formatMdxEsmPathCacheKey(MDX_ESM_CACHE_NAMESPACE, normalizedPath);
+}
+
+export function buildMdxEsmModuleFileName(contentHash: string): string {
+  return formatMdxEsmModuleFileName(MDX_ESM_CACHE_NAMESPACE, contentHash);
+}
+
+export function buildMdxJsxCacheFileName(filePath: string): string {
+  return formatMdxJsxCacheFileName(MDX_ESM_CACHE_NAMESPACE, filePath);
+}
+
+export function buildFrameworkVfModuleCacheFileName(
+  pathHash: string,
+  envKey: string,
+  contentHash: string,
+): string {
+  return formatFrameworkVfModuleCacheFileName(
+    FRAMEWORK_VF_MODULE_CACHE_NAMESPACE,
+    pathHash,
+    envKey,
+    contentHash,
+  );
+}

package/src/src/transforms/mdx/esm-module-loader/import-transformer.ts

@@ -11,7 +11,6 @@ import { join } from "../../../platform/compat/path/index.js";
 import { rendererLogger as logger } from "../../../utils/index.js";
 import { transformImportsWithMap } from "../../../modules/import-map/index.js";
 import type { ImportMapConfig } from "../../../modules/import-map/index.js";
-import { VERSION } from "../../../utils/version.js";
 import { replaceSpecifiers } from "../../esm/lexer.js";
 import { getLocalReactPaths, isReactSpecifier } from "../../../platform/compat/react-paths.js";
 import {
@@ -23,7 +22,7 @@ import {
   REACT_IMPORT_PATTERN,
 } from "./constants.js";
 import { getLocalFs } from "./cache/index.js";
-import { hashString } from "./utils/hash.js";
+import { buildMdxJsxCacheFileName } from "./cache-format.js";
 import { rewriteDntImports } from "./module-fetcher/index.js";
 import { ensureCachedJsxModulePatched } from "./jsx-cache.js";
 import type { ESMLoaderContext } from "./types.js";
@@ -128,7 +127,7 @@ export async function transformJsxImports(
   const transformResults = await Promise.all(
     importsToProcess.map(async ({ fullMatch, importClause, filePath, ext }) => {
       try {
-        const transformedFileName = `jsx-v${VERSION}-${hashString(filePath)}.mjs`;
+        const transformedFileName = buildMdxJsxCacheFileName(filePath);
         const transformedPath = join(esmCacheDir, transformedFileName);
 
         try {

package/src/src/transforms/mdx/esm-module-loader/module-fetcher/cache-keys.ts

@@ -4,7 +4,7 @@
  * @module transforms/mdx/esm-module-loader/module-fetcher/cache-keys
  */
 
-import { VERSION } from "../../../../utils/version.js";
+import { buildMdxEsmPathCacheKey, buildMdxEsmTransformCacheKey } from "../cache-format.js";
 
 /**
  * Build cache key for transformed module.
@@ -18,9 +18,9 @@ export function getTransformCacheKey(
   normalizedPath: string,
   contentHash: string,
 ): string {
-  return `v${VERSION}:${projectId}:${normalizedPath}:${contentHash}:ssr`;
+  return buildMdxEsmTransformCacheKey(projectId, normalizedPath, contentHash);
 }
 
 export function getVersionedPathCacheKey(normalizedPath: string): string {
-  return `v${VERSION}:${normalizedPath}`;
+  return buildMdxEsmPathCacheKey(normalizedPath);
 }

package/src/src/transforms/mdx/esm-module-loader/module-fetcher/framework-validator.ts

@@ -13,6 +13,7 @@ import { FRAMEWORK_ROOT, LOG_PREFIX_MDX_LOADER } from "../constants.js";
 import { getLocalFs } from "../cache/index.js";
 import { extractHttpBundlePaths } from "../../../../modules/react-loader/ssr-module-loader/http-bundle-helpers.js";
 import { ensureHttpBundlesExist } from "../../../esm/http-cache.js";
+import { MDX_ESM_MJS_FILE_URL_PATTERN_SOURCE } from "../cache-format.js";
 
 /**
  * Check if cached code has file:// paths that are incompatible with this environment.
@@ -110,7 +111,7 @@ export async function findMissingFileDependenciesInCode(
   log: Logger,
 ): Promise<string[]> {
   const localFs = getLocalFs();
-  const pattern = /file:\/\/([^"'\s]+\.mjs)/gi;
+  const pattern = new RegExp(MDX_ESM_MJS_FILE_URL_PATTERN_SOURCE, "gi");
   const missing: string[] = [];
   const checked = new Set<string>();
 

package/src/src/transforms/mdx/esm-module-loader/module-fetcher/module-cache.ts

@@ -10,11 +10,10 @@
 import { join } from "../../../../platform/compat/path/index.js";
 import * as posix from "../../../../../deps/jsr.io/@std/path/1.1.4/posix/mod.js";
 import type { Logger } from "../../../../utils/logger/logger.js";
-import { VERSION } from "../../../../utils/version.js";
 import { LOG_PREFIX_MDX_LOADER } from "../constants.js";
 import { getLocalFs, saveModulePathCache } from "../cache/index.js";
 import { hashString } from "../utils/hash.js";
-import { getVersionedPathCacheKey } from "./cache-keys.js";
+import { buildMdxEsmModuleFileName, buildMdxEsmPathCacheKey } from "../cache-format.js";
 import { hasUnresolvedImports } from "./nested-imports.js";
 import { recordModuleToSession } from "./render-sessions.js";
 
@@ -60,13 +59,14 @@ export async function cacheModule(
   }
 
   const contentHash = hashString(normalizedPath + moduleCode);
-  const cachePath = join(esmCacheDir, `vfmod-v${VERSION}-${contentHash}.mjs`);
+  const cachePath = join(esmCacheDir, buildMdxEsmModuleFileName(contentHash));
+  const pathCacheKey = buildMdxEsmPathCacheKey(normalizedPath);
 
   const localFs = getLocalFs();
   try {
     const stat = await localFs.stat(cachePath);
     if (stat?.isFile) {
-      pathCache.set(getVersionedPathCacheKey(normalizedPath), cachePath);
+      pathCache.set(pathCacheKey, cachePath);
       log.debug(`${LOG_PREFIX_MDX_LOADER} Content cache hit: ${normalizedPath}`);
       recordModuleToSession(normalizedPath);
       return cachePath;
@@ -77,7 +77,7 @@ export async function cacheModule(
 
   await localFs.mkdir(esmCacheDir, { recursive: true });
   await localFs.writeTextFile(cachePath, moduleCode);
-  pathCache.set(getVersionedPathCacheKey(normalizedPath), cachePath);
+  pathCache.set(pathCacheKey, cachePath);
   await saveModulePathCache(esmCacheDir);
   log.debug(`${LOG_PREFIX_MDX_LOADER} Cached vf_module: ${normalizedPath} -> ${cachePath}`);
 

package/src/src/transforms/pipeline/stages/ssr-vf-modules/transform.ts

@@ -15,7 +15,6 @@ import { hashCodeHex } from "../../../../utils/hash-utils.js";
 import { getHttpBundleCacheDir, getMdxEsmCacheDir } from "../../../../utils/cache-dir.js";
 import { cacheHttpImportsToLocal } from "../../../esm/http-cache.js";
 import { loadImportMap } from "../../../../modules/import-map/index.js";
-import { VERSION } from "../../../../utils/version.js";
 import { buildReactUrl, getReactImportMap } from "../../../import-rewriter/url-builder.js";
 import { findRelativeImports } from "./import-finder.js";
 import { resolveRelativeFrameworkImport, resolveVeryfrontSourcePath } from "./path-resolver.js";
@@ -30,6 +29,7 @@ import {
   transformingFiles,
   veryfrontTransformCache,
 } from "./constants.js";
+import { buildFrameworkVfModuleCacheFileName } from "../../../mdx/esm-module-loader/cache-format.js";
 
 const DENO_CONFIG_STUB_CODE = `export default ${JSON.stringify(denoConfig)};`;
 
@@ -46,10 +46,10 @@ export function isCyclePlaceholder(code: string): boolean {
 /**
  * Cache transformed framework code and return the file:// path.
  *
- * Cache key format: vfmod-{VERSION}-{pathHash}-{envKey}-{contentHash}.mjs
+ * Cache key format: vfmod-{namespace}-{pathHash}-{envKey}-{contentHash}.mjs
  *
  * Cache invalidation is handled by:
- * - VERSION prefix: Auto-invalidates on framework releases
+ * - namespace prefix: Auto-rolls when the framework vfmod cache shape changes
  * - envKey (FRAMEWORK_ROOT hash): Prevents cross-environment contamination
  *   (compiled binary vs source have different FRAMEWORK_ROOT values)
  * - contentHash: Content-based invalidation
@@ -66,7 +66,7 @@ export async function cacheTransformedCode(
   const envKey = hashCodeHex(FRAMEWORK_ROOT).slice(0, 8);
   const contentHash = hashCodeHex(transformed);
   const pathHash = hashCodeHex(vfModulePath);
-  const fileName = `vfmod-${VERSION}-${pathHash}-${envKey}-${contentHash}.mjs`;
+  const fileName = buildFrameworkVfModuleCacheFileName(pathHash, envKey, contentHash);
   const frameworkCacheDir = join(cacheDir, "framework");
   const cachePath = join(frameworkCacheDir, fileName);
 

package/src/src/utils/cache-namespace.ts

@@ -0,0 +1,42 @@
+import { fnv1aHash } from "./hash-utils.js";
+
+type CacheNamespaceValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly CacheNamespaceValue[]
+  | { readonly [key: string]: CacheNamespaceValue };
+
+function serializeCacheNamespaceValue(value: CacheNamespaceValue): string {
+  if (value === null) return "null";
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => serializeCacheNamespaceValue(entry)).join(",")}]`;
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+    return `{${
+      entries
+        .map(([key, entry]) => `${JSON.stringify(key)}:${serializeCacheNamespaceValue(entry)}`)
+        .join(",")
+    }}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+/**
+ * Build a deterministic cache namespace from a declarative schema description.
+ * Keep the schema close to the cache builders so format changes roll the
+ * namespace automatically instead of relying on a manually bumped constant.
+ */
+export function createCacheNamespace(
+  scope: string,
+  schema: CacheNamespaceValue,
+  length = 10,
+): string {
+  const serialized = serializeCacheNamespaceValue(schema);
+  return `${scope}-${fnv1aHash(serialized).slice(0, length)}`;
+}

package/src/src/utils/version.ts

@@ -1,6 +1,6 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.87";
+export const VERSION = "0.1.89";
 
 export const SERVER_START_TIME: number = Date.now();