veryfront 0.1.86 → 0.1.88

package/src/src/cache/module-cache.ts

@@ -17,6 +17,11 @@ const logger = rendererLogger.component("module-cache");
 let moduleCache: LRUCache<string, string> | null = null;
 let esmCache: LRUCache<string, string> | null = null;
 
+export interface ModuleCacheMap extends Map<string, string> {
+  getOrInsert(key: string, value: string): string;
+  getOrInsertComputed(key: string, callback: (key: string) => string): string;
+}
+
 interface ModuleCacheStats {
   moduleCache: {
     size: number;
@@ -89,71 +94,104 @@ export function getEsmCache(): LRUCache<string, string> {
   return getOrInitPodCache(esmPodCacheOptions);
 }
 
-export function createModuleCache(): Map<string, string> {
+export function createModuleCache(): ModuleCacheMap {
   return createMapInterface(getModuleCache());
 }
 
-export function createEsmCache(): Map<string, string> {
+export function createEsmCache(): ModuleCacheMap {
   return createMapInterface(getEsmCache());
 }
 
-function createMapInterface(cache: LRUCache<string, string>): Map<string, string> {
-  const map: Map<string, string> = {
-    get(key: string): string | undefined {
-      return cache.get(key);
-    },
-    set(key: string, value: string): Map<string, string> {
-      cache.set(key, value);
-      return map;
-    },
-    has(key: string): boolean {
-      return cache.has(key);
-    },
-    delete(key: string): boolean {
-      return cache.delete(key);
-    },
-    clear(): void {
-      cache.clear();
-    },
-    get size(): number {
-      return cache.size;
-    },
-    keys(): MapIterator<string> {
-      return cache.keys() as unknown as MapIterator<string>;
-    },
-    values(): MapIterator<string> {
-      const keysIter = cache.keys();
-      const cacheRef = cache;
-      return (function* () {
-        for (const key of keysIter) {
-          const value = cacheRef.get(key);
-          if (value !== undefined) yield value;
-        }
-      })() as unknown as MapIterator<string>;
-    },
-    entries(): MapIterator<[string, string]> {
-      const keysIter = cache.keys();
-      const cacheRef = cache;
-      return (function* () {
-        for (const key of keysIter) {
-          const value = cacheRef.get(key);
-          if (value !== undefined) yield [key, value] as [string, string];
-        }
-      })() as unknown as MapIterator<[string, string]>;
-    },
-    forEach(callback: (value: string, key: string, map: Map<string, string>) => void): void {
-      for (const key of cache.keys()) {
-        const value = cache.get(key);
-        if (value !== undefined) callback(value, key, map);
+function createMapInterface(cache: LRUCache<string, string>): ModuleCacheMap {
+  return new LRUBackedMap(cache);
+}
+
+class LRUBackedMap implements ModuleCacheMap {
+  readonly [Symbol.toStringTag] = "Map";
+
+  constructor(private readonly cache: LRUCache<string, string>) {
+  }
+
+  get(key: string): string | undefined {
+    return this.cache.get(key);
+  }
+
+  set(key: string, value: string): this {
+    this.cache.set(key, value);
+    return this;
+  }
+
+  has(key: string): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  getOrInsert(key: string, value: string): string {
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+
+    this.cache.set(key, value);
+    return value;
+  }
+
+  getOrInsertComputed(key: string, callback: (key: string) => string): string {
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+
+    const value = callback(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  keys(): MapIterator<string> {
+    return this.cache.keys() as unknown as MapIterator<string>;
+  }
+
+  values(): MapIterator<string> {
+    const keysIter = this.cache.keys();
+    const cacheRef = this.cache;
+    return (function* () {
+      for (const key of keysIter) {
+        const value = cacheRef.get(key);
+        if (value !== undefined) yield value;
       }
-    },
-    [Symbol.iterator](): MapIterator<[string, string]> {
-      return map.entries();
-    },
-    [Symbol.toStringTag]: "Map",
-  };
+    })() as unknown as MapIterator<string>;
+  }
 
-  return map;
+  entries(): MapIterator<[string, string]> {
+    const keysIter = this.cache.keys();
+    const cacheRef = this.cache;
+    return (function* () {
+      for (const key of keysIter) {
+        const value = cacheRef.get(key);
+        if (value !== undefined) yield [key, value] as [string, string];
+      }
+    })() as unknown as MapIterator<[string, string]>;
+  }
+
+  forEach(
+    callback: (value: string, key: string, map: Map<string, string>) => void,
+    thisArg?: unknown,
+  ): void {
+    for (const [key, value] of this.entries()) {
+      callback.call(thisArg, value, key, this);
+    }
+  }
+
+  [Symbol.iterator](): MapIterator<[string, string]> {
+    return this.entries();
+  }
 }
 
 export function getModuleCacheStats(): ModuleCacheStats {

package/src/src/platform/adapters/fs/veryfront/content-metrics.ts

@@ -8,7 +8,12 @@ import {
 const logger = baseLogger.component("content-metrics");
 
 type FileType = "page" | "layout" | "component" | "api" | "data" | "config" | "other";
-export type MissReason = "cold_start" | "not_in_filelist" | "invalidation" | "no_filelist_cache";
+export type MissReason =
+  | "cold_start"
+  | "not_in_filelist"
+  | "invalidation"
+  | "no_filelist_cache"
+  | "indexed_without_content";
 
 interface PerRequestMetrics {
   startTime: number;
@@ -52,7 +57,13 @@ function createFreshRequestMetrics(): PerRequestMetrics {
     networkFetches: 0,
     networkMs: 0,
     fetchesByType: { page: 0, layout: 0, component: 0, api: 0, data: 0, config: 0, other: 0 },
-    missReasons: { cold_start: 0, not_in_filelist: 0, invalidation: 0, no_filelist_cache: 0 },
+    missReasons: {
+      cold_start: 0,
+      not_in_filelist: 0,
+      invalidation: 0,
+      no_filelist_cache: 0,
+      indexed_without_content: 0,
+    },
     isPreviewMode: null,
     filesAccessed: new Set(),
   };

package/src/src/platform/adapters/fs/veryfront/file-list-index.ts

@@ -7,6 +7,13 @@ interface FileListCacheEntry {
   content?: string;
 }
 
+export interface FileListMatchResult {
+  status: "unavailable" | "missing" | "present_without_content" | "hit";
+  fresh: boolean;
+  path?: string;
+  content?: string;
+}
+
 function hashPreview(content: string): number {
   return content
     .slice(0, 100)
@@ -22,8 +29,10 @@ const INDEX_STALENESS_LIMIT_MS = 5 * 60 * 1000; // 5 minutes
 
 export class FileListIndex {
   private index: Map<string, string> | null = null;
+  private pathSet: Set<string> | null = null;
   private indexKey: string | null = null;
   private indexBuiltAt = 0;
+  private indexFresh = false;
   private readyPromise: Promise<void> | null = null;
 
   constructor(
@@ -39,8 +48,10 @@ export class FileListIndex {
 
     const indexedWithContent = this.index.size;
     this.index = null;
+    this.pathSet = null;
     this.indexKey = null;
     this.indexBuiltAt = 0;
+    this.indexFresh = false;
     logger.debug("Cleared file list index", { indexedWithContent });
   }
 
@@ -56,21 +67,39 @@ export class FileListIndex {
   }
 
   async lookup(normalizedPath: string): Promise<string | undefined> {
+    const match = await this.match(normalizedPath);
+    return match.status === "hit" ? match.content : undefined;
+  }
+
+  async match(normalizedPath: string): Promise<FileListMatchResult> {
     await this.ensureReady();
 
-    const index = await this.getOrBuild();
-    if (!index) {
+    const snapshot = await this.getOrBuild();
+    if (!snapshot) {
       logger.debug("No file list cache available");
-      return undefined;
+      return { status: "unavailable", fresh: false };
     }
 
-    const content = index.get(normalizedPath);
-    if (!content) {
+    if (!snapshot.paths.has(normalizedPath)) {
       logger.debug("Content not in file list index", {
         path: normalizedPath,
-        indexSize: index.size,
+        indexSize: snapshot.content.size,
+        fresh: snapshot.fresh,
       });
-      return undefined;
+      return { status: "missing", fresh: snapshot.fresh };
+    }
+
+    const content = snapshot.content.get(normalizedPath);
+    if (!content) {
+      logger.debug("File list index contains path without inline content", {
+        path: normalizedPath,
+        fresh: snapshot.fresh,
+      });
+      return {
+        status: "present_without_content",
+        fresh: snapshot.fresh,
+        path: normalizedPath,
+      };
     }
 
     logger.debug("FILE_LIST_CACHE_HIT - serving from file list cache", {
@@ -80,26 +109,60 @@ export class FileListIndex {
       contentPreview: previewText(content, 200).replace(/\n/g, "\\n"),
     });
 
-    return content;
+    return {
+      status: "hit",
+      fresh: snapshot.fresh,
+      path: normalizedPath,
+      content,
+    };
   }
 
   async findFirstWithContent(
     normalizedPaths: string[],
   ): Promise<{ path: string; content: string } | undefined> {
+    const match = await this.findFirstMatch(normalizedPaths);
+    if (match.status !== "hit" || !match.path || !match.content) return undefined;
+    return { path: match.path, content: match.content };
+  }
+
+  async findFirstMatch(
+    normalizedPaths: string[],
+  ): Promise<FileListMatchResult> {
     await this.ensureReady();
 
-    const index = await this.getOrBuild();
-    if (!index) return undefined;
+    const snapshot = await this.getOrBuild();
+    if (!snapshot) return { status: "unavailable", fresh: false };
 
     for (const path of normalizedPaths) {
-      const content = index.get(path);
-      if (content) return { path, content };
+      if (!snapshot.paths.has(path)) continue;
+
+      const content = snapshot.content.get(path);
+      if (content) {
+        return {
+          status: "hit",
+          fresh: snapshot.fresh,
+          path,
+          content,
+        };
+      }
+
+      return {
+        status: "present_without_content",
+        fresh: snapshot.fresh,
+        path,
+      };
     }
 
-    return undefined;
+    return { status: "missing", fresh: snapshot.fresh };
   }
 
-  private async getOrBuild(): Promise<Map<string, string> | null> {
+  private async getOrBuild(): Promise<
+    {
+      content: Map<string, string>;
+      paths: Set<string>;
+      fresh: boolean;
+    } | null
+  > {
     if (!this.getFileListCache) {
       logger.debug("getOrBuildFileListIndex: no getFileListCache function");
       return null;
@@ -118,7 +181,12 @@ export class FileListIndex {
             indexSize: this.index.size,
             indexAgeMs: age,
           });
-          return this.index;
+          this.indexFresh = false;
+          return {
+            content: this.index,
+            paths: this.pathSet ?? new Set<string>(),
+            fresh: false,
+          };
         }
         logger.debug("getOrBuildFileListIndex: in-memory index too stale, discarding", {
           indexSize: this.index.size,
@@ -126,7 +194,9 @@ export class FileListIndex {
           staleLimitMs: INDEX_STALENESS_LIMIT_MS,
         });
         this.index = null;
+        this.pathSet = null;
         this.indexKey = null;
+        this.indexFresh = false;
       }
       logger.debug(
         "[ReadOperations] getOrBuildFileListIndex: getFileListCache returned null/undefined",
@@ -146,19 +216,28 @@ export class FileListIndex {
     const indexKey = `${fileList.length}:${fileList[0]?.path ?? ""}:${
       fileList[fileList.length - 1]?.path ?? ""
     }`;
-    if (this.index && this.indexKey === indexKey) {
+    if (this.index && this.pathSet && this.indexKey === indexKey) {
       this.indexBuiltAt = Date.now();
-      return this.index;
+      this.indexFresh = true;
+      return {
+        content: this.index,
+        paths: this.pathSet,
+        fresh: true,
+      };
     }
 
     const index = new Map<string, string>();
+    const pathSet = new Set<string>();
     for (const file of fileList) {
+      pathSet.add(file.path);
       if (file.content) index.set(file.path, file.content);
     }
 
     this.index = index;
+    this.pathSet = pathSet;
     this.indexKey = indexKey;
     this.indexBuiltAt = Date.now();
+    this.indexFresh = true;
 
     const sampleFile = fileList.find((f) => /welcome/i.test(f.path));
     const sampleContent = sampleFile?.content;
@@ -171,6 +250,10 @@ export class FileListIndex {
       sampleContentPreview: sampleContent?.slice(0, 200)?.replace(/\n/g, "\\n"),
     });
 
-    return index;
+    return {
+      content: index,
+      paths: pathSet,
+      fresh: true,
+    };
   }
 }

package/src/src/platform/adapters/fs/veryfront/read-operations-helpers.ts

@@ -6,6 +6,8 @@ import type { ResolvedContentContext } from "./types.js";
 
 export { READ_OPERATION_EXTENSION_PRIORITY };
 
+export type NotFoundLikeError = Error & { code?: string };
+
 interface ReadContextProviderLike {
   isProductionMode: () => boolean;
   isPersistentCacheInvalidated?: (prefix: string) => boolean;
@@ -78,6 +80,10 @@ export function getResolvedCacheKey(
   return `${cacheKeyPrefix}:${normalizedResolvedPath}`;
 }
 
+export function buildExtensionCandidatePaths(basePath: string): string[] {
+  return READ_OPERATION_EXTENSION_PRIORITY.map((ext) => `${basePath}${ext}`);
+}
+
 export function splitKnownFileExtension(
   apiPath: string,
 ): { originalExtension: string; basePath: string } | null {
@@ -95,3 +101,7 @@ export function isNotFoundLikeError(error: unknown): boolean {
   const errorMessage = error instanceof Error ? error.message : String(error);
   return errorMessage.includes("404") || errorMessage.includes("Not Found");
 }
+
+export function createNotFoundLikeError(path: string): NotFoundLikeError {
+  return Object.assign(new Error(`404 Not Found: ${path}`), { code: "ENOENT" });
+}

package/src/src/platform/adapters/fs/veryfront/read-operations.ts

@@ -3,13 +3,15 @@ import { withSpan } from "../../../../observability/tracing/otlp-setup.js";
 import type { VeryfrontApiClient } from "../../veryfront-api-client/index.js";
 import { FileCache } from "../cache/file-cache.js";
 import { logContentMetric, type MissReason } from "./content-metrics.js";
-import { FileListIndex } from "./file-list-index.js";
+import { FileListIndex, type FileListMatchResult } from "./file-list-index.js";
 import { InFlightRequestDeduper } from "./in-flight-dedupe.js";
 import { getRequestScopedFile, setRequestScopedFile } from "./multi-project-adapter.js";
 import { PathNormalizer } from "./path-normalizer.js";
 import {
   assertProjectSourcePath,
+  buildExtensionCandidatePaths,
   buildReadFetchState,
+  createNotFoundLikeError,
   getResolvedCacheKey,
   isNotFoundLikeError,
   READ_OPERATION_EXTENSION_PRIORITY as EXTENSION_PRIORITY,
@@ -184,17 +186,23 @@ export class ReadOperations {
     skipPersistentCaches: boolean,
     isPreviewMode: boolean,
     ctx: ResolvedContentContext | null,
-  ): Promise<string | null> {
+  ): Promise<FileListMatchResult> {
     // File list cache is enabled for BOTH preview and production modes.
     // The file list is an in-memory index built from API response at init, updated by WebSocket pokes.
     // This is safe because:
     // - File list is refreshed on every WebSocket poke (websocket-manager.ts:483-500)
     // - Request-scoped cache ensures consistency within a single render
     // - Persistent cache is only written for production mode (to avoid staleness risk in preview)
-    if (!skipPersistentCaches) {
-      const fileListContent = await this.fileListIndex.lookup(normalizedPath);
-      if (!fileListContent) return null;
+    if (skipPersistentCaches) {
+      logger.debug("Skipping file list cache due to invalidation", {
+        path: normalizedPath,
+        cacheKeyPrefix,
+      });
+      return { status: "unavailable", fresh: false };
+    }
 
+    const match = await this.fileListIndex.match(normalizedPath);
+    if (match.status === "hit" && match.content) {
       logContentMetric("FILE_LIST_HIT", {
         path: normalizedPath,
         mode: ctx?.sourceType ?? "unknown",
@@ -204,24 +212,12 @@ export class ReadOperations {
       // Only cache to persistent storage for production mode
       // Preview mode uses file list cache directly without persisting (fresher, WebSocket-driven)
       if (isProduction) {
-        this.cache.set(cacheKey, fileListContent);
+        this.cache.set(cacheKey, match.content);
       }
-      setRequestScopedFile(cacheKey, fileListContent);
-      return fileListContent;
+      setRequestScopedFile(cacheKey, match.content);
     }
 
-    // Skip only happens during cache invalidation (both preview and production)
-    logContentMetric("CACHE_MISS", {
-      path: normalizedPath,
-      mode: ctx?.sourceType ?? "unknown",
-      missReason: "invalidation" as MissReason,
-      isPreviewMode,
-    });
-    logger.debug("Skipping file list cache due to invalidation", {
-      path: normalizedPath,
-      cacheKeyPrefix,
-    });
-    return null;
+    return match;
   }
 
   private setupInFlightFetch(
@@ -232,6 +228,7 @@ export class ReadOperations {
     isProduction: boolean,
     isPreviewMode: boolean,
     ctx: ResolvedContentContext | null,
+    missReason: MissReason,
   ): Promise<string> {
     const cleanupResult = this.inFlightRequests.cleanup();
     if (cleanupResult) {
@@ -249,11 +246,10 @@ export class ReadOperations {
     }
 
     // Track why we're making a network fetch (for optimization analysis)
-    const hasFileListCache = !!this.getFileListCache;
     logContentMetric("CACHE_MISS", {
       path: normalizedPath,
       mode: ctx?.sourceType ?? "unknown",
-      missReason: (hasFileListCache ? "not_in_filelist" : "no_filelist_cache") as MissReason,
+      missReason,
       isPreviewMode,
     });
 
@@ -377,10 +373,10 @@ export class ReadOperations {
     isProduction: boolean,
     ctx: ResolvedContentContext | null,
     isPreviewMode: boolean,
-  ): Promise<string | null> {
-    const candidatePaths = EXTENSION_PRIORITY.map((ext) => `${normalizedPath}${ext}`);
-    const resolved = await this.fileListIndex.findFirstWithContent(candidatePaths);
-    if (!resolved) return null;
+  ): Promise<FileListMatchResult> {
+    const candidatePaths = buildExtensionCandidatePaths(normalizedPath);
+    const resolved = await this.fileListIndex.findFirstMatch(candidatePaths);
+    if (resolved.status !== "hit" || !resolved.path || !resolved.content) return resolved;
 
     const resolvedCacheKey = getResolvedCacheKey(cacheKeyPrefix, resolved.path);
 
@@ -402,7 +398,7 @@ export class ReadOperations {
 
     this.cacheResolvedContent(cacheKey, resolvedCacheKey, resolved.content, isProduction);
 
-    return resolved.content;
+    return resolved;
   }
 
   private cacheResolvedContent(
@@ -472,7 +468,7 @@ export class ReadOperations {
     );
     if (persistentCached) return persistentCached;
 
-    const fileListCached = await this.getFileListCacheHit(
+    const fileListMatch = await this.getFileListCacheHit(
       normalizedPath,
       cacheKeyPrefix,
       cacheKey,
@@ -481,7 +477,19 @@ export class ReadOperations {
       isPreviewMode,
       ctx,
     );
-    if (fileListCached) return fileListCached;
+    if (fileListMatch.status === "hit" && fileListMatch.content) return fileListMatch.content;
+    if (fileListMatch.status === "present_without_content") {
+      return this.setupInFlightFetch(
+        normalizedPath,
+        apiPath,
+        cacheKey,
+        isPublished,
+        isProduction,
+        isPreviewMode,
+        ctx,
+        "indexed_without_content",
+      );
+    }
 
     if (!hasKnownExt) {
       if (!skipPersistentCaches) {
@@ -493,7 +501,47 @@ export class ReadOperations {
           ctx,
           isPreviewMode,
         );
-        if (resolvedFromFileList) return resolvedFromFileList;
+        if (resolvedFromFileList.status === "hit" && resolvedFromFileList.content) {
+          return resolvedFromFileList.content;
+        }
+
+        if (
+          resolvedFromFileList.status === "present_without_content" &&
+          resolvedFromFileList.path
+        ) {
+          const resolvedCacheKey = getResolvedCacheKey(cacheKeyPrefix, resolvedFromFileList.path);
+          const resolvedApiPath = this.getOriginalApiPath?.(resolvedFromFileList.path) ??
+            resolvedFromFileList.path;
+          const fetchedResolved = await this.setupInFlightFetch(
+            resolvedFromFileList.path,
+            resolvedApiPath,
+            resolvedCacheKey,
+            isPublished,
+            isProduction,
+            isPreviewMode,
+            ctx,
+            "indexed_without_content",
+          );
+
+          this.extensionResolutionCache.set(normalizedPath, resolvedFromFileList.path);
+          this.cacheResolvedContent(
+            cacheKey,
+            resolvedCacheKey,
+            fetchedResolved,
+            isProduction && !skipPersistentCaches,
+          );
+
+          return fetchedResolved;
+        }
+
+        if (
+          fileListMatch.status === "missing" &&
+          fileListMatch.fresh &&
+          resolvedFromFileList.status === "missing" &&
+          resolvedFromFileList.fresh
+        ) {
+          throw createNotFoundLikeError(normalizedPath);
+        }
       }
 
       const resolved = await this.tryResolveExtensionlessPath(
@@ -506,6 +554,10 @@ export class ReadOperations {
       if (resolved) return resolved;
     }
 
+    if (fileListMatch.status === "missing" && fileListMatch.fresh) {
+      throw createNotFoundLikeError(normalizedPath);
+    }
+
     return this.setupInFlightFetch(
       normalizedPath,
       apiPath,
@@ -514,6 +566,11 @@ export class ReadOperations {
       isProduction,
       isPreviewMode,
       ctx,
+      skipPersistentCaches
+        ? "invalidation"
+        : fileListMatch.status === "missing" && fileListMatch.fresh
+        ? "not_in_filelist"
+        : "no_filelist_cache",
     );
   }