veryfront 0.1.82 → 0.1.83

package/esm/src/rendering/page-resolution/page-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-resolver.d.ts","sourceRoot":"","sources":["../../../../src/src/rendering/page-resolution/page-resolver.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAgCvD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,EAAE,mBAAmB;IAOxC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiDxC,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAoCxB,sBAAsB;IAoD9B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY1C,aAAa,IAAI,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC;CAShD"}
+{"version":3,"file":"page-resolver.d.ts","sourceRoot":"","sources":["../../../../src/src/rendering/page-resolution/page-resolver.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAoCvD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,EAAE,mBAAmB;IAOxC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsDxC,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAoCxB,sBAAsB;IAoD9B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY1C,aAAa,IAAI,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC;CAShD"}

package/esm/src/rendering/page-resolution/page-resolver.js

@@ -4,7 +4,7 @@ import { VeryfrontError } from "../../errors/index.js";
 import { FILE_NOT_FOUND } from "../../errors/error-registry.js";
 import { withSpan } from "../../observability/tracing/otlp-setup.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)$/;
 function isPageFile(name) {
@@ -40,20 +40,33 @@ export class PageResolver {
     }
     resolvePage(slug) {
         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;
-            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" },
                 });
             }
             return pageInfo;

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

@@ -21,6 +21,7 @@ export declare function clearRouterDetectionCache(): void;
  * @param projectId - The project ID used as cache key. Falls back to projectDir for local dev.
  */
 export declare function clearRouterDetectionCacheForProject(projectId: string): void;
+export declare function primeRouterDetectionCache(projectKey: string, mode: "app" | "pages"): void;
 export interface DetectAppRouterOptions {
     /** Project ID for cache isolation in multi-tenant deployments */
     projectId?: string;

package/esm/src/rendering/router-detection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router-detection.d.ts","sourceRoot":"","sources":["../../../src/src/rendering/router-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;4BAO4B;AAK5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAY5D;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC,CA6BlB"}
+{"version":3,"file":"router-detection.d.ts","sourceRoot":"","sources":["../../../src/src/rendering/router-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;4BAO4B;AAK5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAY5D;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,GAAG,OAAO,GACpB,IAAI,CAEN;AAED,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC,CA6BlB"}

package/esm/src/rendering/router-detection.js

@@ -38,6 +38,9 @@ export function clearRouterDetectionCache() {
 export function clearRouterDetectionCacheForProject(projectId) {
     routerDetectionCache.delete(projectId);
 }
+export function primeRouterDetectionCache(projectKey, mode) {
+    routerDetectionCache.set(projectKey, mode === "app");
+}
 /**
  * Detect if app router should be used based on config and directory structure.
  *

package/esm/src/types/entities/getEntityInfo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getEntityInfo.d.ts","sourceRoot":"","sources":["../../../../src/src/types/entities/getEntityInfo.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAU,UAAU,EAAe,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAWtE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6I5B;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA+L5B;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyE5B"}
+{"version":3,"file":"getEntityInfo.d.ts","sourceRoot":"","sources":["../../../../src/src/types/entities/getEntityInfo.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAU,UAAU,EAAe,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAWtE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAmJ5B;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwM5B;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyE5B"}

package/esm/src/types/entities/getEntityInfo.js

@@ -29,37 +29,42 @@ export async function getEntityInfo(filePath, adapter) {
             }
         }
         try {
+            const shouldReadDirectly = adapter
+                ? isExtendedFSAdapter(adapter.fs) && adapter.fs.isVeryfrontAdapter()
+                : false;
+            let content;
             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 (!stat.isFile)
+                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;
+                    }
                 }
-                catch (error) {
-                    entityInfoScope.runSync(() => {
-                        throw error;
-                    }, { path: filePath, details: { reason: "stat-failed" } }, undefined);
-                    return null;
-                }
+                content = await withFallback(() => adapter.fs.readFile(normalizedPath), () => fs.readTextFile(filePath), { operationName: "readFile:getEntityInfo", logError: false });
             }
             else {
                 const exists = await fs.exists(filePath);
                 if (!exists)
                     return null;
+                content = await fs.readTextFile(filePath);
             }
-            const content = adapter
-                ? await withFallback(() => adapter.fs.readFile(normalizedPath), () => fs.readTextFile(filePath), { operationName: "readFile:getEntityInfo", logError: false })
-                : await fs.readTextFile(filePath);
             const ext = pathHelper.extname(filePath).toLowerCase();
             let frontmatter = {};
             let body = content;
@@ -120,23 +125,27 @@ export async function getEntityInfo(filePath, adapter) {
 }
 export async function getEntityBySlug(projectDir, slug, adapter) {
     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 === "") {
+                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,
             });
             const pathResults = await parallelMap(basePaths, async (basePath) => {
@@ -153,12 +162,13 @@ export async function getEntityBySlug(projectDir, slug, adapter) {
                 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
@@ -194,25 +204,25 @@ export async function getEntityBySlug(projectDir, slug, adapter) {
                     /* expected: directory may not exist or readDir may fail */
                 }
             }
-            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`));
+            possiblePaths.unshift(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"), pathHelper.join(projectDir, "pages", "index.tsx"), pathHelper.join(projectDir, "pages", "index.ts"));
         }
         const pathResults = await parallelMap(possiblePaths, async (p) => {
@@ -222,7 +232,7 @@ export async function getEntityBySlug(projectDir, slug, adapter) {
             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
@@ -267,7 +277,11 @@ export async function getEntityBySlug(projectDir, slug, adapter) {
             }
         }
         return null;
-    }, { "entity.slug": slug, "entity.projectDir": projectDir });
+    }, {
+        "entity.slug": slug,
+        "entity.normalized_slug": normalizeSlug(slug),
+        "entity.projectDir": projectDir,
+    });
 }
 export async function getLayoutEntity(projectDir, layoutName, adapter) {
     return await withSpan("types.getLayoutEntity", async () => {
@@ -345,3 +359,6 @@ function getSlugFromPath(filePath) {
     const parentDir = parts[parts.length - 2];
     return parentDir === "pages" ? "" : parentDir ?? "";
 }
+function normalizeSlug(slug) {
+    return slug === "/" ? "" : slug.replace(/^\/+/, "").replace(/\/+$/, "");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/platform/adapters/base.ts

@@ -117,7 +117,11 @@ export interface FileSystemAdapter {
   makeTempDir(prefix: string): Promise<string>;
   watch(paths: string | string[], options?: WatchOptions): FileWatcher;
   /** Resolve a file path with extension fallback (e.g., pages/test → pages/test.mdx) */
-  resolveFile?(basePath: string): Promise<string | null>;
+  resolveFile?(basePath: string, options?: ResolveFileOptions): Promise<string | null>;
+}
+
+export interface ResolveFileOptions {
+  allowPagesPrefix?: boolean;
 }
 
 export interface DirEntry {

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

@@ -1,6 +1,7 @@
 import { logger } from "../../../../utils/index.js";
 import { CONFIG_INVALID } from "../../../../errors/index.js";
 import { getEnv } from "../../../compat/process.js";
+import type { ResolveFileOptions } from "../../base.js";
 import { FileCache } from "../cache/file-cache.js";
 import type { FSAdapter, FSAdapterConfig } from "../veryfront/types.js";
 import { GitHubApiClient } from "./github-api-client.js";
@@ -115,9 +116,9 @@ export class GitHubFSAdapter implements FSAdapter {
     return this.dirOps.readdir(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);
   }
 
   getCacheStats(): {

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

@@ -5,6 +5,7 @@ import {
   buildGitHubStatCacheKey,
   buildGitHubTreeCacheKey,
 } from "../../../../cache/index.js";
+import type { ResolveFileOptions } from "../../base.js";
 import type { FileCache } from "../cache/file-cache.js";
 import type { GitHubApiClient } from "./github-api-client.js";
 import type { FileIndexEntry, FileInfo, GitHubTreeEntry, ResolvedGitHubConfig } from "./types.js";
@@ -176,7 +177,7 @@ export class GitHubStatOperations {
     }
   }
 
-  async resolveFile(basePath: string): Promise<string | null> {
+  async resolveFile(basePath: string, options?: ResolveFileOptions): Promise<string | null> {
     await this.ensureIndex();
 
     const normalizedPath = normalizeGitHubPath(basePath, this.projectDir);
@@ -185,7 +186,7 @@ export class GitHubStatOperations {
     if (cached !== undefined) return cached;
 
     const resolved = this.tryResolve(normalizedPath) ??
-      this.tryResolveWithPagesPrefix(normalizedPath);
+      (options?.allowPagesPrefix === false ? null : this.tryResolveWithPagesPrefix(normalizedPath));
 
     this.cache.set(cacheKey, resolved);
     return resolved;

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 */