veryfront 0.1.82 → 0.1.83

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/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/types/entities/getEntityInfo.ts

@@ -43,49 +43,55 @@ export async function getEntityInfo(
       }
 
       try {
+        const shouldReadDirectly = adapter
+          ? isExtendedFSAdapter(adapter.fs) && adapter.fs.isVeryfrontAdapter()
+          : false;
+
+        let content: string;
         if (adapter) {
-          try {
-            const stat = await withFallback(
-              () => adapter.fs.stat(normalizedPath),
-              async () => {
-                const exists = await fs.exists(filePath);
-                if (!exists) {
-                  throw toError(
-                    createError({
-                      type: "file",
-                      message: "File not found",
-                      context: { path: filePath, operation: "read" },
-                    }),
-                  );
-                }
-                return await fs.stat(filePath);
-              },
-              { operationName: "stat:getEntityInfo", logError: false },
-            );
+          if (!shouldReadDirectly) {
+            try {
+              const stat = await withFallback(
+                () => adapter.fs.stat(normalizedPath),
+                async () => {
+                  const exists = await fs.exists(filePath);
+                  if (!exists) {
+                    throw toError(
+                      createError({
+                        type: "file",
+                        message: "File not found",
+                        context: { path: filePath, operation: "read" },
+                      }),
+                    );
+                  }
+                  return await fs.stat(filePath);
+                },
+                { operationName: "stat:getEntityInfo", logError: false },
+              );
 
-            if (!stat.isFile) return null;
-          } catch (error) {
-            entityInfoScope.runSync(
-              () => {
-                throw error;
-              },
-              { path: filePath, details: { reason: "stat-failed" } },
-              undefined,
-            );
-            return null;
+              if (!stat.isFile) return null;
+            } catch (error) {
+              entityInfoScope.runSync(
+                () => {
+                  throw error;
+                },
+                { path: filePath, details: { reason: "stat-failed" } },
+                undefined,
+              );
+              return null;
+            }
           }
-        } else {
-          const exists = await fs.exists(filePath);
-          if (!exists) return null;
-        }
 
-        const content = adapter
-          ? await withFallback(
+          content = await withFallback(
             () => adapter.fs.readFile(normalizedPath),
             () => fs.readTextFile(filePath),
             { operationName: "readFile:getEntityInfo", logError: false },
-          )
-          : await fs.readTextFile(filePath);
+          );
+        } else {
+          const exists = await fs.exists(filePath);
+          if (!exists) return null;
+          content = await fs.readTextFile(filePath);
+        }
 
         const ext = pathHelper.extname(filePath).toLowerCase();
 
@@ -171,26 +177,30 @@ export async function getEntityBySlug(
   return await withSpan(
     "types.getEntityBySlug",
     async () => {
-      const isVeryfrontRoute = slug.startsWith(".veryfront/") || slug === ".veryfront";
+      const normalizedSlug = normalizeSlug(slug);
+      const isVeryfrontRoute = normalizedSlug.startsWith(".veryfront/") ||
+        normalizedSlug === ".veryfront";
       const resolveFile = adapter?.fs.resolveFile;
 
       logger.debug("START", {
         slug,
+        normalizedSlug,
         projectDir,
         isVeryfrontRoute,
         hasResolveFile: !!resolveFile,
       });
 
       if (resolveFile) {
-        const basePaths = [pathHelper.join(projectDir, "pages", slug)];
+        const basePaths = [pathHelper.join(projectDir, "pages", normalizedSlug)];
 
-        if (isVeryfrontRoute) basePaths.unshift(pathHelper.join(projectDir, slug));
-        if (slug === "index" || slug === "") {
+        if (isVeryfrontRoute) basePaths.unshift(pathHelper.join(projectDir, normalizedSlug));
+        if (normalizedSlug === "index" || normalizedSlug === "") {
           basePaths.unshift(pathHelper.join(projectDir, "pages", "index"));
         }
 
         logger.debug("Checking paths (resolveFile branch)", {
           slug,
+          normalizedSlug,
           basePaths,
         });
 
@@ -208,13 +218,14 @@ export async function getEntityBySlug(
           if (info?.entity.isPage) {
             logger.debug("Found page via resolveFile", {
               slug,
+              normalizedSlug,
               path: info.entity.path,
             });
             return info;
           }
         }
 
-        const slugParts = slug.split("/");
+        const slugParts = normalizedSlug === "" ? [] : normalizedSlug.split("/");
         for (let depth = slugParts.length - 1; depth >= 0; depth--) {
           const parentPath = slugParts.slice(0, depth).join("/");
           const pagesDir = parentPath
@@ -259,33 +270,33 @@ export async function getEntityBySlug(
           }
         }
 
-        logger.debug("No page found via resolveFile branch", { slug });
+        logger.debug("No page found via resolveFile branch", { slug, normalizedSlug });
         return null;
       }
 
       const possiblePaths = [
-        pathHelper.join(projectDir, "pages", `${slug}.mdx`),
-        pathHelper.join(projectDir, "pages", `${slug}.md`),
-        pathHelper.join(projectDir, "pages", `${slug}.tsx`),
-        pathHelper.join(projectDir, "pages", `${slug}.jsx`),
-        pathHelper.join(projectDir, "pages", `${slug}.ts`),
-        pathHelper.join(projectDir, "pages", `${slug}/index.mdx`),
-        pathHelper.join(projectDir, "pages", `${slug}/index.md`),
-        pathHelper.join(projectDir, "pages", `${slug}/index.tsx`),
-        pathHelper.join(projectDir, "pages", `${slug}/index.jsx`),
-        pathHelper.join(projectDir, "pages", `${slug}/index.ts`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}.mdx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}.md`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}.tsx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}.jsx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}.ts`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}/index.mdx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}/index.md`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}/index.tsx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}/index.jsx`),
+        pathHelper.join(projectDir, "pages", `${normalizedSlug}/index.ts`),
       ];
 
       if (isVeryfrontRoute) {
         possiblePaths.unshift(
-          pathHelper.join(projectDir, `${slug}.mdx`),
-          pathHelper.join(projectDir, `${slug}.md`),
-          pathHelper.join(projectDir, `${slug}.tsx`),
-          pathHelper.join(projectDir, `${slug}.ts`),
+          pathHelper.join(projectDir, `${normalizedSlug}.mdx`),
+          pathHelper.join(projectDir, `${normalizedSlug}.md`),
+          pathHelper.join(projectDir, `${normalizedSlug}.tsx`),
+          pathHelper.join(projectDir, `${normalizedSlug}.ts`),
         );
       }
 
-      if (slug === "index" || slug === "") {
+      if (normalizedSlug === "index" || normalizedSlug === "") {
         possiblePaths.unshift(
           pathHelper.join(projectDir, "pages", "index.mdx"),
           pathHelper.join(projectDir, "pages", "index.md"),
@@ -302,7 +313,7 @@ export async function getEntityBySlug(
         if (info?.entity.isPage) return info;
       }
 
-      const slugParts = slug.split("/");
+      const slugParts = normalizedSlug === "" ? [] : normalizedSlug.split("/");
       for (let depth = slugParts.length - 1; depth >= 0; depth--) {
         const parentPath = slugParts.slice(0, depth).join("/");
         const pagesDir = parentPath
@@ -356,7 +367,11 @@ export async function getEntityBySlug(
 
       return null;
     },
-    { "entity.slug": slug, "entity.projectDir": projectDir },
+    {
+      "entity.slug": slug,
+      "entity.normalized_slug": normalizeSlug(slug),
+      "entity.projectDir": projectDir,
+    },
   );
 }
 
@@ -448,3 +463,7 @@ function getSlugFromPath(filePath: string): string {
   const parentDir = parts[parts.length - 2];
   return parentDir === "pages" ? "" : parentDir ?? "";
 }
+
+function normalizeSlug(slug: string): string {
+  return slug === "/" ? "" : slug.replace(/^\/+/, "").replace(/\/+$/, "");
+}