veryfront 0.1.81 → 0.1.83

package/src/src/platform/adapters/fs/veryfront/adapter.ts

@@ -9,7 +9,7 @@ import type {
   InvalidationCallbacks,
   ResolvedContentContext,
 } from "./types.js";
-import type { FileInfo } from "../../base.js";
+import type { FileInfo, ResolveFileOptions } from "../../base.js";
 import { VeryfrontApiClient } from "../../veryfront-api-client/index.js";
 import type { Project } from "../../veryfront-api-client/index.js";
 import { FileCache } from "../cache/file-cache.js";
@@ -142,6 +142,24 @@ export class VeryfrontFSAdapter implements FSAdapter {
 
         return result;
       },
+      hasCachedFileList: async () => {
+        if (!this.contentContext) {
+          logger.debug("hasCachedFileList: no contentContext");
+          return false;
+        }
+
+        const cacheKey = buildFileListCacheKey(this.contentContext);
+        const result = await this.cache.getAsync<Array<{ path: string }>>(cacheKey);
+        const hasResult = Array.isArray(result) && result.length > 0;
+
+        logger.debug("hasCachedFileList lookup", {
+          cacheKey,
+          hasResult,
+          resultSize: result?.length ?? 0,
+        });
+
+        return hasResult;
+      },
       isPersistentCacheInvalidated: (prefix: string) => this.isPersistentCacheInvalidated(prefix),
       isReleaseBeingInvalidated: (releaseId: string) =>
         this.isPersistentCacheInvalidated(
@@ -410,9 +428,12 @@ export class VeryfrontFSAdapter implements FSAdapter {
     return this.statOps.exists(path);
   }
 
-  async resolveFile(basePath: string): Promise<string | null> {
+  async resolveFile(
+    basePath: string,
+    options?: ResolveFileOptions,
+  ): Promise<string | null> {
     await this.ensureInitialized();
-    return this.statOps.resolveFile(basePath);
+    return this.statOps.resolveFile(basePath, options);
   }
 
   dispose(): void {

package/src/src/platform/adapters/fs/veryfront/multi-project-adapter.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { logger as baseLogger } from "../../../../utils/index.js";
 import { INITIALIZATION_ERROR } from "../../../../errors/index.js";
 import type { DirectoryEntry, FSAdapter, FSAdapterConfig } from "./types.js";
-import type { FileInfo } from "../../base.js";
+import type { FileInfo, ResolveFileOptions } from "../../base.js";
 import { ProxyFSAdapterManager } from "./proxy-manager.js";
 import type { VeryfrontFSAdapter } from "./index.js";
 import { runWithCacheBatching } from "../../../../cache/request-cache-batcher.js";
@@ -213,9 +213,12 @@ export class MultiProjectFSAdapter implements FSAdapter {
     }
   }
 
-  async resolveFile(basePath: string): Promise<string | null> {
+  async resolveFile(
+    basePath: string,
+    options?: ResolveFileOptions,
+  ): Promise<string | null> {
     const adapter = await this.getAdapter();
-    return adapter.resolveFile(basePath);
+    return adapter.resolveFile(basePath, options);
   }
 
   dispose(): void {

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

@@ -41,6 +41,7 @@ export interface ContentContextProvider {
       updated_at?: string;
     }> | undefined
   >;
+  hasCachedFileList?: () => Promise<boolean>;
   /** True if cache prefix is being deleted - skip persistent cache reads */
   isPersistentCacheInvalidated?: (prefix: string) => boolean;
   /** Back-compat: release-scoped invalidation */

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

@@ -1,6 +1,6 @@
 import { logger as baseLogger } from "../../../../utils/index.js";
 import { isFrameworkSourcePath } from "../../../../utils/path-utils.js";
-import type { FileInfo } from "../../base.js";
+import type { FileInfo, ResolveFileOptions } from "../../base.js";
 import type { ProjectFile } from "../../veryfront-api-client/index.js";
 import { VeryfrontOperationsBase } from "./base-operations.js";
 import { createError, toError } from "../../../../errors/index.js";
@@ -326,6 +326,125 @@ export class StatOperations extends VeryfrontOperationsBase {
     return files;
   }
 
+  private buildResolveSearchPatterns(
+    normalizedPath: string,
+    options?: ResolveFileOptions,
+  ): string[] {
+    const patterns = new Set<string>();
+    const pathWithoutExt = stripKnownExtension(normalizedPath, EXTENSION_PRIORITY);
+    const allowPagesPrefix = options?.allowPagesPrefix !== false;
+    const addPattern = (pattern: string): void => {
+      if (pattern.length > 0) patterns.add(pattern);
+    };
+
+    if (EXTENSION_PRIORITY.some((ext) => normalizedPath.endsWith(ext))) {
+      addPattern(normalizedPath);
+      return [...patterns];
+    }
+
+    addPattern(`${pathWithoutExt}.*`);
+    if (allowPagesPrefix && !pathWithoutExt.startsWith("pages/")) {
+      addPattern(`pages/${pathWithoutExt}.*`);
+    }
+
+    addPattern(`${pathWithoutExt}/index.*`);
+    if (allowPagesPrefix && !pathWithoutExt.startsWith("pages/")) {
+      addPattern(`pages/${pathWithoutExt}/index.*`);
+    }
+
+    return [...patterns];
+  }
+
+  private normalizeMatchedPaths(
+    matches: Array<{ path: string }>,
+  ): Array<{ path: string }> {
+    return matches.map((match) => ({
+      path: normalizeIndexedFilePath(match as ProjectFile).normalizedPath,
+    }));
+  }
+
+  private async tryResolveViaApiSearch(
+    normalizedPath: string,
+    options?: ResolveFileOptions,
+  ): Promise<string | null | undefined> {
+    if (isFrameworkSourcePath(normalizedPath)) {
+      logger.debug("Skipping API search for framework path", { normalizedPath });
+      return null;
+    }
+
+    if (!this.apiSearchCircuitBreaker.canSearch()) {
+      logger.warn("API search circuit breaker open, skipping", { normalizedPath });
+      return undefined;
+    }
+
+    const patterns = this.buildResolveSearchPatterns(normalizedPath, options);
+    let sawSuccessfulSearch = false;
+
+    for (const pattern of patterns) {
+      try {
+        const matches = await this.client.searchFiles(pattern);
+        sawSuccessfulSearch = true;
+        this.apiSearchCircuitBreaker.recordSuccess();
+
+        const normalizedMatches = this.normalizeMatchedPaths(matches);
+        if (pattern === normalizedPath) {
+          const exactMatch = normalizedMatches.find((match) => match.path === normalizedPath);
+          if (exactMatch) {
+            logger.debug("resolveFile found exact file via API search", {
+              normalizedPath,
+              pattern,
+            });
+            return exactMatch.path;
+          }
+          continue;
+        }
+
+        const sortedMatches = sortPathsByExtensionPriority(normalizedMatches, EXTENSION_PRIORITY);
+        const first = sortedMatches[0];
+        if (first) {
+          logger.debug("resolveFile found via API search", {
+            normalizedPath,
+            pattern,
+            resolvedPath: first.path,
+          });
+          return first.path;
+        }
+      } catch (error) {
+        const result = this.apiSearchCircuitBreaker.recordFailure();
+        if (result.tripped) {
+          logger.warn("API search circuit breaker tripped", {
+            failures: result.failures,
+          });
+          return undefined;
+        }
+        logger.error("API pattern search failed", { pattern, error });
+      }
+
+      if (!this.apiSearchCircuitBreaker.canSearch()) {
+        logger.warn("API search circuit breaker open, aborting remaining patterns", {
+          normalizedPath,
+        });
+        return undefined;
+      }
+    }
+
+    if (sawSuccessfulSearch) {
+      logger.debug("resolveFile not found via API search", { normalizedPath, patterns });
+      return null;
+    }
+
+    return undefined;
+  }
+
+  private async hasCachedFileList(): Promise<boolean> {
+    if (this.contextProvider?.hasCachedFileList) {
+      return await this.contextProvider.hasCachedFileList();
+    }
+
+    const files = await this.contextProvider?.getFileList?.();
+    return Array.isArray(files) && files.length > 0;
+  }
+
   async exists(path: string): Promise<boolean> {
     const normalizedPath = this.normalizer.normalize(path);
     try {
@@ -337,7 +456,7 @@ export class StatOperations extends VeryfrontOperationsBase {
     }
   }
 
-  async resolveFile(basePath: string): Promise<string | null> {
+  async resolveFile(basePath: string, options?: ResolveFileOptions): Promise<string | null> {
     const resolveStart = performance.now();
     const normalizedPath = this.normalizer.normalize(basePath);
     const ctx = this.contextProvider?.getContentContext();
@@ -349,6 +468,36 @@ export class StatOperations extends VeryfrontOperationsBase {
       cacheKey,
     });
 
+    const cached = await this.cache.getAsync<string>(cacheKey);
+    if (cached === NOT_FOUND_SENTINEL) {
+      logger.debug("resolveFile cached negative result", { normalizedPath });
+      return null;
+    }
+
+    if (cached !== undefined) {
+      logger.debug("resolveFile cache hit", {
+        normalizedPath,
+        cached,
+      });
+      return cached;
+    }
+
+    const hasCachedFileList = await this.hasCachedFileList();
+    const attemptedApiResolve = !hasCachedFileList;
+
+    if (!hasCachedFileList) {
+      const apiResolved = await this.tryResolveViaApiSearch(normalizedPath, options);
+      if (typeof apiResolved === "string") {
+        this.cache.set(cacheKey, apiResolved);
+        return apiResolved;
+      }
+
+      if (apiResolved === null) {
+        this.cache.set(cacheKey, NOT_FOUND_SENTINEL);
+        return null;
+      }
+    }
+
     const indexStart = performance.now();
     await this.ensureIndexBuilt();
     const indexMs = Math.round(performance.now() - indexStart);
@@ -382,7 +531,7 @@ export class StatOperations extends VeryfrontOperationsBase {
       return resolvedDirect;
     }
 
-    if (!pathWithoutExt.startsWith("pages/")) {
+    if (options?.allowPagesPrefix !== false && !pathWithoutExt.startsWith("pages/")) {
       const resolvedPages = resolveByExtensionPriority(
         fileIdx,
         `pages/${pathWithoutExt}`,
@@ -410,6 +559,15 @@ export class StatOperations extends VeryfrontOperationsBase {
       return indexPath;
     }
 
+    if (attemptedApiResolve) {
+      logger.debug("resolveFile not found after pre-index API search", {
+        normalizedPath,
+        indexMs,
+      });
+      this.cache.set(cacheKey, NOT_FOUND_SENTINEL);
+      return null;
+    }
+
     if (isFrameworkSourcePath(normalizedPath)) {
       logger.debug("Skipping API search for framework path", { normalizedPath });
       return null;
@@ -425,32 +583,10 @@ export class StatOperations extends VeryfrontOperationsBase {
       return null;
     }
 
-    const cacheCheckStart = performance.now();
-    const cached = await this.cache.getAsync<string>(cacheKey);
-    const cacheCheckMs = Math.round(performance.now() - cacheCheckStart);
-
-    if (cached === NOT_FOUND_SENTINEL) {
-      logger.debug("resolveFile cached negative result", {
-        normalizedPath,
-        cacheCheckMs,
-      });
-      return null;
-    }
-
-    if (cached !== undefined) {
-      logger.debug("resolveFile cache hit (unexpected)", {
-        normalizedPath,
-        cached,
-        cacheCheckMs,
-      });
-      return cached;
-    }
-
     const searchPattern = `${pathWithoutExt}.*`;
     logger.debug("Searching for file via API", {
       pattern: searchPattern,
       normalizedPath,
-      cacheCheckMs,
     });
 
     try {

package/src/src/platform/adapters/fs/veryfront/types.ts

@@ -1,3 +1,4 @@
+import type { ResolveFileOptions } from "../../base.js";
 import type { Project } from "../../veryfront-api-client/index.js";
 import type { GitHubConfig } from "../github/types.js";
 import type { DirectoryEntry } from "../shared-types.js";
@@ -26,7 +27,7 @@ export interface FSAdapter {
   initialize?(): Promise<void>;
   shutdown?(): Promise<void>;
 
-  resolveFile?(basePath: string): Promise<string | null>;
+  resolveFile?(basePath: string, options?: ResolveFileOptions): Promise<string | null>;
 }
 
 export interface ContextualFSAdapter extends FSAdapter {

package/src/src/platform/adapters/fs/wrapper.ts

@@ -1,4 +1,11 @@
-import type { DirEntry, FileInfo, FileSystemAdapter, FileWatcher, WatchOptions } from "../base.js";
+import type {
+  DirEntry,
+  FileInfo,
+  FileSystemAdapter,
+  FileWatcher,
+  ResolveFileOptions,
+  WatchOptions,
+} from "../base.js";
 import type { ContextualFSAdapter, DirectoryEntry, FSAdapter } from "./veryfront/types.js";
 
 export interface ExtendedFileSystemAdapter extends FileSystemAdapter {
@@ -224,9 +231,9 @@ export class FSAdapterWrapper implements ExtendedFileSystemAdapter {
     };
   }
 
-  resolveFile(basePath: string): Promise<string | null> {
+  resolveFile(basePath: string, options?: ResolveFileOptions): Promise<string | null> {
     if (!this._fsAdapter.resolveFile) throw new NotSupportedError("resolveFile", this.adapterType);
-    return this._fsAdapter.resolveFile(basePath);
+    return this._fsAdapter.resolveFile(basePath, options);
   }
 
   async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {

package/src/src/rendering/app-route-resolver.ts

@@ -127,14 +127,6 @@ async function tryLoadPageFile(
   slug: string,
   adapter: RuntimeAdapter,
 ): Promise<EntityInfo | null> {
-  try {
-    const info = await adapter.fs.stat(file);
-    if (!info.isFile) return null;
-  } catch (_) {
-    /* expected: file may not exist */
-    return null;
-  }
-
   let raw: string;
   try {
     raw = await adapter.fs.readFile(file);

package/src/src/rendering/orchestrator/file-resolver/index.ts

@@ -6,6 +6,7 @@
  * @module rendering/orchestrator/file-resolver
  */
 
+import { join } from "../../../platform/compat/path/index.js";
 import { rendererLogger as logger } from "../../../utils/index.js";
 import type { RuntimeAdapter } from "../../../platform/adapters/base.js";
 import { buildCandidatePaths, findFirstExisting } from "./candidates.js";
@@ -48,6 +49,24 @@ export async function findSourceFile(
   projectDir: string,
   adapter: RuntimeAdapter,
 ): Promise<string | null> {
+  if (adapter.fs.resolveFile) {
+    const directBases = [join(projectDir, basePath)];
+    const withoutComponents = basePath.replace(/^components\//, "");
+    if (withoutComponents !== basePath) {
+      directBases.push(join(projectDir, withoutComponents));
+    }
+
+    for (const candidateBase of directBases) {
+      const resolved = await adapter.fs.resolveFile(candidateBase, {
+        allowPagesPrefix: false,
+      });
+      if (resolved) {
+        logger.debug("[FileResolver] Found file via resolveFile:", resolved);
+        return resolved;
+      }
+    }
+  }
+
   const candidates = buildCandidatePaths(projectDir, basePath, SOURCE_EXTENSIONS);
 
   const withoutComponents = basePath.replace(/^components\//, "");

package/src/src/rendering/orchestrator/module-loader/index.ts

@@ -21,8 +21,7 @@ import {
   setCachedTransformAsync,
 } from "../../../transforms/esm/transform-cache.js";
 import { TRANSFORM_DISTRIBUTED_TTL_SEC } from "../../../utils/constants/cache.js";
-import { ensureHttpBundlesExist } from "../../../transforms/esm/http-cache.js";
-import { validateBundleGroup } from "../../../transforms/esm/bundle-manifest.js";
+import { validateCachedBundlesByManifestOrCode } from "../../../transforms/esm/cached-bundle-validation.js";
 import { getHttpBundleCacheDir, getMdxEsmCacheDir } from "../../../utils/cache-dir.js";
 import { dirname, join, normalize } from "../../../platform/compat/path/index.js";
 import { hashCodeHex } from "../../../utils/hash-utils.js";
@@ -32,7 +31,6 @@ import {
   lookupMdxEsmCache,
   saveModulePathCache,
 } from "../../../transforms/mdx/esm-module-loader/cache/index.js";
-import { extractHttpBundlePaths } from "../../../modules/react-loader/ssr-module-loader/http-bundle-helpers.js";
 
 const logger = rendererLogger.component("module-loader");
 
@@ -344,28 +342,22 @@ export async function transformModuleWithDeps(
   const cacheDir = getHttpBundleCacheDir();
   let bundlesValid = true;
 
-  if (transformResult.cacheHit && transformResult.bundleManifestId) {
-    const validation = await validateBundleGroup(transformResult.bundleManifestId, cacheDir);
+  if (transformResult.cacheHit) {
+    const validation = await validateCachedBundlesByManifestOrCode(
+      transformedCode,
+      transformResult.bundleManifestId,
+      cacheDir,
+    );
     if (!validation.valid) {
-      logger.warn("Bundle manifest validation failed, re-transforming", {
+      logger.warn("Cached HTTP bundle validation failed, re-transforming", {
         filePath,
-        manifestId: transformResult.bundleManifestId.slice(0, 12),
+        manifestId: transformResult.bundleManifestId?.slice(0, 12),
         failedHashes: validation.failedHashes,
+        reason: validation.reason,
+        source: validation.source,
       });
       bundlesValid = false;
     }
-  } else {
-    const bundlePaths = extractHttpBundlePaths(transformedCode);
-    if (bundlePaths.length > 0) {
-      const failed = await ensureHttpBundlesExist(bundlePaths, cacheDir);
-      if (failed.length > 0) {
-        logger.warn("HTTP bundle recovery failed, re-transforming", {
-          filePath,
-          failed,
-        });
-        bundlesValid = false;
-      }
-    }
   }
 
   if (!bundlesValid) {

package/src/src/rendering/page-resolution/page-resolver.ts

@@ -7,7 +7,11 @@ import type { RuntimeAdapter } from "../../platform/adapters/base.js";
 import type { VeryfrontConfig } from "../../config/index.js";
 import type { EntityInfo } from "../../types/index.js";
 import { getEntityBySlug } from "../../types/entities/getEntityInfo.js";
-import { detectAppRouter, getAppRouteEntity } from "../router-detection.js";
+import {
+  detectAppRouter,
+  getAppRouteEntity,
+  primeRouterDetectionCache,
+} from "../router-detection.js";
 
 const PAGE_EXTENSIONS = /\.(mdx|md|tsx|jsx|ts|js)$/;
 const APP_ROUTER_PAGE_PATTERN = /^page\.(mdx|md|tsx|jsx|ts|js)$/;
@@ -61,39 +65,44 @@ export class PageResolver {
     return withSpan(
       "routing.resolve_page",
       async () => {
-        const useAppRouter = await detectAppRouter(
-          this.projectDir,
-          this.config,
-          this.adapter,
-          { projectId: this.projectId },
-        );
-
         const appDirName = this.config.directories?.app ?? "app";
+        const cacheKey = this.projectId ?? this.projectDir;
 
         let pageInfo: EntityInfo | null | undefined;
 
-        if (useAppRouter) {
+        if (this.config.router === "app") {
+          pageInfo = await getAppRouteEntity(
+            this.projectDir,
+            slug,
+            this.adapter,
+            appDirName,
+          );
+          if (pageInfo) {
+            primeRouterDetectionCache(cacheKey, "app");
+          }
+        } else if (this.config.router === "pages") {
+          pageInfo = await getEntityBySlug(this.projectDir, slug, this.adapter);
+          if (pageInfo) {
+            primeRouterDetectionCache(cacheKey, "pages");
+          }
+        } else {
+          // Auto mode stays structural: a single resolved route must not pin router mode
+          // for projects that are still transitioning between app/ and pages/.
           pageInfo = await getAppRouteEntity(
             this.projectDir,
             slug,
             this.adapter,
             appDirName,
           );
-
           if (!pageInfo) {
-            logger.debug(
-              "App Router resolution failed, falling back to Pages Router",
-              { slug },
-            );
+            pageInfo = await getEntityBySlug(this.projectDir, slug, this.adapter);
           }
         }
 
-        pageInfo ??= await getEntityBySlug(this.projectDir, slug, this.adapter);
-
         if (!pageInfo) {
           throw FILE_NOT_FOUND.create({
             detail: `Page not found: ${slug}`,
-            context: { slug, useAppRouter },
+            context: { slug, router: this.config.router ?? "auto" },
           });
         }
 

package/src/src/rendering/router-detection.ts

@@ -49,6 +49,13 @@ export function clearRouterDetectionCacheForProject(projectId: string): void {
   routerDetectionCache.delete(projectId);
 }
 
+export function primeRouterDetectionCache(
+  projectKey: string,
+  mode: "app" | "pages",
+): void {
+  routerDetectionCache.set(projectKey, mode === "app");
+}
+
 export interface DetectAppRouterOptions {
   /** Project ID for cache isolation in multi-tenant deployments */
   projectId?: string;

package/src/src/transforms/esm/bundle-manifest.ts

@@ -38,10 +38,13 @@ interface BundleManifest {
   ttlSeconds: number;
 }
 
+export type ManifestValidationReason = "manifest_missing" | "bundle_missing";
+
 /** Result of manifest validation. */
-interface ManifestValidationResult {
+export interface ManifestValidationResult {
   valid: boolean;
   failedHashes: string[];
+  reason?: ManifestValidationReason;
 }
 
 /**
@@ -148,7 +151,7 @@ export async function validateBundleGroup(
     logger.debug(`${LOG_PREFIX} Manifest not found in distributed cache`, {
       manifestId: manifestId.slice(0, 12),
     });
-    return { valid: false, failedHashes: [] };
+    return { valid: false, failedHashes: [], reason: "manifest_missing" };
   }
 
   const missingBundles: Array<{ path: string; hash: string }> = [];
@@ -178,7 +181,7 @@ export async function validateBundleGroup(
       manifestId: manifestId.slice(0, 12),
       unrecoverable: unrecoverableHashes,
     });
-    return { valid: false, failedHashes: unrecoverableHashes };
+    return { valid: false, failedHashes: unrecoverableHashes, reason: "bundle_missing" };
   }
 
   logger.info(`${LOG_PREFIX} All missing bundles recovered successfully`, {

package/src/src/transforms/esm/cached-bundle-validation.ts

@@ -0,0 +1,40 @@
+import { extractHttpBundlePaths } from "../../modules/react-loader/ssr-module-loader/http-bundle-helpers.js";
+import { ensureHttpBundlesExist } from "./http-cache.js";
+import { type ManifestValidationReason, validateBundleGroup } from "./bundle-manifest.js";
+
+export interface CachedBundleValidationResult {
+  valid: boolean;
+  failedHashes: string[];
+  reason?: ManifestValidationReason;
+  source: "manifest" | "code";
+}
+
+export async function validateCachedBundlesByManifestOrCode(
+  code: string,
+  bundleManifestId: string | undefined,
+  cacheDir: string,
+): Promise<CachedBundleValidationResult> {
+  if (bundleManifestId) {
+    const validation = await validateBundleGroup(bundleManifestId, cacheDir);
+    if (validation.valid || validation.reason === "bundle_missing") {
+      return { ...validation, source: "manifest" };
+    }
+  }
+
+  const bundlePaths = extractHttpBundlePaths(code);
+  if (bundlePaths.length === 0) {
+    return { valid: true, failedHashes: [], source: "code" };
+  }
+
+  const failedHashes = await ensureHttpBundlesExist(bundlePaths, cacheDir);
+  if (failedHashes.length === 0) {
+    return { valid: true, failedHashes: [], source: "code" };
+  }
+
+  return {
+    valid: false,
+    failedHashes,
+    reason: "bundle_missing",
+    source: "code",
+  };
+}