@faapi/faapi 6.21.1 → 6.23.0

package/dist/index.js

@@ -2046,14 +2046,14 @@ var ValidationError = class extends FaapiError {
   issues;
 };
 var RouteNotFoundError = class extends FaapiError {
-  constructor(path31) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path31}`, 404);
+  constructor(path32) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path32}`, 404);
     this.name = "RouteNotFoundError";
   }
 };
 var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path31, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path31}`, 405);
+  constructor(method, path32, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path32}`, 405);
     this.allowedMethods = allowedMethods;
     this.name = "MethodNotAllowedError";
   }
@@ -3442,13 +3442,14 @@ function buildAliasPlugins(rootDir) {
 }
 
 // src/cli/compileSourceFiles.ts
+var SOURCE_IGNORE = ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts", `${APP_DIR}/resources/**`];
 async function compileSourceFiles(options) {
   const { rootDir, dist, files, logLevel = "silent", production, atomicWrite } = options;
   const entryPoints = files ?? await fg2([`${APP_DIR}/**/*.ts`], {
     cwd: rootDir,
     onlyFiles: true,
     absolute: true,
-    ignore: ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts"]
+    ignore: SOURCE_IGNORE
   });
   if (entryPoints.length === 0) {
     return { compiledFiles: [] };
@@ -4353,8 +4354,8 @@ function loadEnv(rootDir) {
 }
 
 // src/cli/createAppCore.ts
-import fs21 from "fs";
-import path26 from "path";
+import fs22 from "fs";
+import path27 from "path";
 
 // src/router/sortRoutes.ts
 function sortRoutes(routes) {
@@ -4418,7 +4419,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path19 from "path";
+import path20 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -4460,25 +4461,25 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path31) {
+function matchRoute(routes, method, path32) {
   const index = getHttpIndex(routes);
   const upper = method.toUpperCase();
-  const hit = matchByMethod(index, upper, path31);
+  const hit = matchByMethod(index, upper, path32);
   if (hit) return hit;
   if (upper === "HEAD") {
-    return matchByMethod(index, "GET", path31);
+    return matchByMethod(index, "GET", path32);
   }
   return null;
 }
-function matchByMethod(index, method, path31) {
-  const staticHit = index.static.get(`${method}|${path31}`);
+function matchByMethod(index, method, path32) {
+  const staticHit = index.static.get(`${method}|${path32}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   if (index.dynamics.length === 0) {
     return null;
   }
-  const pathSegments = path31.split("/").filter(Boolean);
+  const pathSegments = path32.split("/").filter(Boolean);
   for (const entry of index.dynamics) {
     const route = entry.route;
     if (route.method !== method) {
@@ -4491,31 +4492,31 @@ function matchByMethod(index, method, path31) {
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path31) {
+function matchWsRoute(wsRoutes, path32) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path31);
+  const staticHit = index.static.get(path32);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path31, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path32, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path31) {
+function findAllowedMethods(routes, path32) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path31);
+  const staticMethods = index.methodsByStaticPath.get(path32);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
     }
   }
   if (index.dynamics.length > 0) {
-    const pathSegments = path31.split("/").filter(Boolean);
+    const pathSegments = path32.split("/").filter(Boolean);
     for (const entry of index.dynamics) {
       const params = matchSegments(
         entry.segments,
@@ -4533,10 +4534,10 @@ function findAllowedMethods(routes, path31) {
   }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path31, paramNames, isCatchAll) {
+function matchDynamicPath(pattern, path32, paramNames, isCatchAll) {
   return matchSegments(
     pattern.split("/").filter(Boolean),
-    path31.split("/").filter(Boolean),
+    path32.split("/").filter(Boolean),
     paramNames,
     isCatchAll
   );
@@ -4782,13 +4783,28 @@ function encodeSseEvent(event) {
   return out;
 }
 function createSseWriter(options = {}) {
-  const { onFirstWrite } = options;
+  const { onFirstWrite, keepOpen = false } = options;
   const encoder = new TextEncoder();
   let controller = null;
   let closed = false;
   let aborted = false;
   let firstWriteTriggered = false;
   let drainWaiters = [];
+  let closeCallbacks = [];
+  let closeCallbacksFired = false;
+  const safeRunCallback = (callback) => {
+    try {
+      callback();
+    } catch {
+    }
+  };
+  const runCloseCallbacks = () => {
+    if (closeCallbacksFired) return;
+    closeCallbacksFired = true;
+    const callbacks = closeCallbacks;
+    closeCallbacks = [];
+    for (const callback of callbacks) safeRunCallback(callback);
+  };
   const resolveDrainWaiters = () => {
     const waiters = drainWaiters;
     drainWaiters = [];
@@ -4812,6 +4828,7 @@ function createSseWriter(options = {}) {
         aborted = true;
         closed = true;
         controller = null;
+        runCloseCallbacks();
         resolveDrainWaiters();
       }
     },
@@ -4854,6 +4871,7 @@ function createSseWriter(options = {}) {
     close() {
       if (closed) return;
       closed = true;
+      runCloseCallbacks();
       resolveDrainWaiters();
       if (controller) {
         try {
@@ -4863,6 +4881,13 @@ function createSseWriter(options = {}) {
         controller = null;
       }
     },
+    onClose(callback) {
+      if (closeCallbacksFired) {
+        safeRunCallback(callback);
+        return;
+      }
+      closeCallbacks.push(callback);
+    },
     get closed() {
       return closed;
     },
@@ -4879,6 +4904,9 @@ function createSseWriter(options = {}) {
     get aborted() {
       return aborted;
     },
+    get keepOpen() {
+      return keepOpen;
+    },
     get response() {
       return response;
     }
@@ -5012,10 +5040,18 @@ function formatSetCookie(name, value, options) {
   if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
   return cookie;
 }
-function createContext(request, params, config = {}, ip = "", registries) {
-  return createContextFromUrl(request, new URL(request.url), params, config, ip, registries);
+function createContext(request, params, config = {}, ip = "", registries, resourcesDir) {
+  return createContextFromUrl(
+    request,
+    new URL(request.url),
+    params,
+    config,
+    ip,
+    registries,
+    resourcesDir
+  );
 }
-function createContextFromUrl(request, url, params, config = {}, ip = "", registries) {
+function createContextFromUrl(request, url, params, config = {}, ip = "", registries, resourcesDir) {
   const meta = { headers: {}, setCookies: [] };
   const parsedCookies = parseCookies(request.headers.get("cookie") ?? "");
   const cookiesObj = {};
@@ -5043,6 +5079,9 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
     ua: request.headers.get("user-agent") ?? "",
     cookies: cookiesObj,
     config,
+    // 运行时资源根目录（HTTP/WS 链路由 createServer/handleWsUpgrade 传入；
+    // testing 直调未传时为 undefined，见 contextTypes.resourcesDir 注释）
+    resourcesDir,
     meta,
     setStatus(status) {
       meta.status = status;
@@ -5088,10 +5127,15 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
      * 接入底层连接——流式期间字节即产即达（见 createServer.md「SSE 提前接管」）。
      * 无钩子场景（app.inject / 测试直调 invokeHandler）回落为 handler 返回后交出。
      *
+     * `{ keepOpen: true }` 声明流生命周期独立于 handler 返回：handler 返回后框架
+     * 不自动 close（长连接订阅模式，清理推送源用 writer.onClose）；handler 抛错
+     * 的兜底 close 不受影响。详见 runtime/sse.md「长连接订阅模式」。
+     *
      * 与 ctx.json / ctx.html 互斥：一个 handler 只能用一种响应方式。
      */
-    sse() {
+    sse(options) {
       const writer = createSseWriter({
+        keepOpen: options?.keepOpen,
         onFirstWrite: (response) => {
           ctx.__earlyRespond?.(response);
         }
@@ -5491,7 +5535,7 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
   const pickSseAndAutoClose = () => {
     const sseWriter = ctx.__sseWriter;
     if (!sseWriter) return null;
-    if (!sseWriter.closed && !sseWriter.aborted) {
+    if (!sseWriter.keepOpen && !sseWriter.closed && !sseWriter.aborted) {
       sseWriter.close();
     }
     return mergeMeta(sseWriter.response, meta);
@@ -5632,9 +5676,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue);
-    const path31 = issue.path.map(String).join(".") || "";
+    const path32 = issue.path.map(String).join(".") || "";
     return {
-      path: path31,
+      path: path32,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -5855,9 +5899,17 @@ function etag(options = {}) {
 }
 
 // src/server/handleWsUpgrade.ts
-import fs16 from "fs";
+import fs17 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
+import path19 from "path";
+
+// src/cli/copyResources.ts
 import path18 from "path";
+import fs16 from "fs";
+var RESOURCES_OUTPUT_DIR = "resources";
+function resolveResourcesDir(rootDir, dist) {
+  return path18.resolve(rootDir, dist, RESOURCES_OUTPUT_DIR);
+}
 
 // src/server/serverUtils.ts
 function nodeHttpToWebHeaders(req) {
@@ -5997,7 +6049,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs16.existsSync(sourcePath)) {
+      if (sourcePath && fs17.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -6095,6 +6147,7 @@ function attachWebSocket(options) {
     trustedProxy = false,
     registries
   } = options;
+  const resourcesDir = resolveResourcesDir(rootDir, dist);
   const wss = new WebSocketServer({ noServer: true });
   server.on("upgrade", async (req, socket, head) => {
     try {
@@ -6126,12 +6179,19 @@ function attachWebSocket(options) {
     const host = req.headers.host ?? "localhost";
     const fullUrl = new URL(`http://${host}${req.url ?? "/"}`);
     const request = new Request(fullUrl.toString(), { method: "GET", headers });
-    const ctx = createContext(request, params, config, getClientIp(req, trustedProxy), registries);
+    const ctx = createContext(
+      request,
+      params,
+      config,
+      getClientIp(req, trustedProxy),
+      registries,
+      resourcesDir
+    );
     const meta = ctx.meta;
     let upgraded = false;
     const finalHandler = async () => {
       const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
-      if (fs16.existsSync(schemaPath)) {
+      if (fs17.existsSync(schemaPath)) {
         if (isDevOnDemandEnabled()) {
           const devDist = getDevDist();
           if (devDist) {
@@ -6170,7 +6230,7 @@ function attachWebSocket(options) {
       }
       let handlers;
       try {
-        const absoluteFilePath = path18.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path19.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -6330,6 +6390,7 @@ function createServer(options) {
     trustedProxy = false
   } = options;
   const routesRef = { current: routes, wsCurrent: wsRoutes ?? [] };
+  const resourcesDir = resolveResourcesDir(rootDir, dist);
   const configMiddlewares = [];
   if (compressionOption) {
     const compOpts = typeof compressionOption === "object" ? compressionOption : {};
@@ -6376,7 +6437,8 @@ function createServer(options) {
       bodyLimit,
       trustedProxy,
       registries,
-      routesRef.wsCurrent
+      routesRef.wsCurrent,
+      resourcesDir
     ).catch((err) => {
       console.error("[faapi] Request pipeline failed after error response attempt:", err);
       try {
@@ -6402,7 +6464,7 @@ function createServer(options) {
   });
   return { server, routesRef };
 }
-function prepareRequest(req, request, url, config, trustedProxy, registries, preMatched) {
+function prepareRequest(req, request, url, config, trustedProxy, registries, preMatched, resourcesDir) {
   const method = request.method.toUpperCase();
   const urlPath = url.pathname;
   const ctx = createContextFromUrl(
@@ -6411,7 +6473,8 @@ function prepareRequest(req, request, url, config, trustedProxy, registries, pre
     preMatched?.params ?? {},
     config,
     getClientIp(req, trustedProxy),
-    registries
+    registries,
+    resourcesDir
   );
   const meta = ctx.meta;
   return { request, url, ctx, meta, method, urlPath };
@@ -6430,7 +6493,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path19.resolve(rootDir, route.filePath),
+      absFilePath: path20.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -6553,7 +6616,7 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
     }
   }
 }
-async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries, wsRoutes) {
+async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries, wsRoutes, resourcesDir) {
   let meta = { headers: {}, setCookies: [] };
   let ctx;
   let sseEarlySent = false;
@@ -6573,7 +6636,8 @@ async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares,
       config,
       trustedProxy,
       registries,
-      preMatched
+      preMatched,
+      resourcesDir
     );
     ctx = prepared.ctx;
     meta = prepared.meta;
@@ -6649,8 +6713,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs17 from "fs";
-import path20 from "path";
+import fs18 from "fs";
+import path21 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -6694,18 +6758,18 @@ function createIdleTaskDriver() {
 }
 
 // src/cli/loadPlugins.ts
-import path22 from "path";
-import fs19 from "fs";
+import path23 from "path";
+import fs20 from "fs";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
-import path21 from "path";
-import fs18 from "fs";
+import path22 from "path";
+import fs19 from "fs";
 async function compileProjectModules(entryPoints, rootDir, dist) {
   const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const absDist = path21.resolve(rootDir, dist);
+  const absDist = path22.resolve(rootDir, dist);
   await esbuild.build({
     entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
@@ -6719,7 +6783,7 @@ async function compileProjectModules(entryPoints, rootDir, dist) {
     logLevel: "silent"
   });
   if (insideFiles.length > 0) {
-    const appOutbase = path21.resolve(rootDir, "src");
+    const appOutbase = path22.resolve(rootDir, "src");
     await esbuild.build({
       entryPoints: insideFiles,
       outdir: absDist,
@@ -6800,30 +6864,30 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
 var TS_EXTS = /\.(ts|tsx|mts|cts)$/;
 var JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path22.isAbsolute(specifier) ? specifier : path22.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs19.existsSync(base)) return base;
+  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs20.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs19.existsSync(base + ext)) return base + ext;
+    if (fs20.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs19.existsSync(base + indexExt)) return base + indexExt;
+    if (fs20.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path22.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path22.isAbsolute(specifier)) {
+  if (!isRelative && !path23.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path22.resolve(baseDir, dist) : null;
+  const distDir = dist ? path23.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs19.existsSync(productPath) && (sourcePath === null || isProductFresh(sourcePath, productPath))) {
+  if (productPath !== null && fs20.existsSync(productPath) && (sourcePath === null || isProductFresh(sourcePath, productPath))) {
     return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
@@ -6832,13 +6896,13 @@ async function importPluginModule(specifier, baseDir, dist) {
         `Local plugin "${specifier}" has no up-to-date build artifact (dist is stale or missing). Run "faapi build" first, or use "faapi dev" for on-demand compilation.`
       );
     }
-    const relFromRoot = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs19.existsSync(productPath)) {
+    if (productPath && fs20.existsSync(productPath)) {
       return import(pathToFileURL3(productPath).href);
     }
   }
@@ -6850,7 +6914,7 @@ async function importPluginModule(specifier, baseDir, dist) {
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path22.isAbsolute(c) ? c : path22.join(baseDir, c));
+  ].map((c) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -6875,11 +6939,11 @@ function resolveDeclaration(decl) {
 }
 
 // src/cli/manifestLoader.ts
-import fs20 from "fs";
-import path25 from "path";
+import fs21 from "fs";
+import path26 from "path";
 
 // src/cli/generateAgentArtifacts.ts
-import path23 from "path";
+import path24 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts11 from "typescript";
@@ -7159,9 +7223,9 @@ function validateAgentList(metadata) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path23.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path24.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path23.resolve(rootDir, manifest.filePath);
+    const absPath = path24.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
@@ -7177,14 +7241,14 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   }
   validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path23.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
 // src/cli/generateTaskArtifacts.ts
 init_generateZodArtifacts();
-import path24 from "path";
+import path25 from "path";
 init_createProgram();
 init_atomicWrite();
 init_extractHandlerTypes();
@@ -7222,7 +7286,7 @@ function collectTaskSchemaSources(tasks, rootDir) {
   const tasksByFile = /* @__PURE__ */ new Map();
   for (const task of tasks) {
     if (!task.inputTypeName) continue;
-    const absPath = path24.resolve(rootDir, task.filePath);
+    const absPath = path25.resolve(rootDir, task.filePath);
     let list = tasksByFile.get(absPath);
     if (!list) {
       list = [];
@@ -7279,9 +7343,9 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
   if (manifests.length > 0) {
-    const programByFile = createPrograms(manifests.map((m) => path24.resolve(rootDir, m.filePath)));
+    const programByFile = createPrograms(manifests.map((m) => path25.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
-      const absPath = path24.resolve(rootDir, manifest.filePath);
+      const absPath = path25.resolve(rootDir, manifest.filePath);
       const result = extractToolMetadata(programByFile.get(absPath), absPath, "run", {
         name: manifest.name,
         filePath: manifest.filePath
@@ -7292,7 +7356,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
     }
   }
   const serialized = serializeTasks(manifests, dist);
-  const tasksPath = path24.resolve(rootDir, dist, TASKS_FILE);
+  const tasksPath = path25.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
   if (metadata.length === 0) {
     return hydrateTasks(serialized);
@@ -7314,8 +7378,8 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
 var TOOLS_FILE2 = "faapi-tools.js";
 var AGENTS_FILE2 = "faapi-agents.js";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path25.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs20.existsSync(toolsPath)) {
+  const toolsPath = path26.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs21.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -7324,8 +7388,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path25.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs20.existsSync(agentsPath)) {
+  const agentsPath = path26.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs21.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -7340,8 +7404,8 @@ function getTaskDriverOptions(config) {
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
-  const tasksPath = path25.resolve(rootDir, dist, TASKS_FILE);
-  if (!fs20.existsSync(tasksPath)) {
+  const tasksPath = path26.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs21.existsSync(tasksPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(tasksPath);
@@ -7533,8 +7597,9 @@ function logStartupSummary(routes, wsRoutes, tools, agents, taskMetas, p) {
 async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
-  const routesPath = path26.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs21.existsSync(routesPath)) {
+  const resourcesDir = resolveResourcesDir(rootDir, dist);
+  const routesPath = path27.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs22.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
@@ -7613,6 +7678,8 @@ async function createAppBase(options) {
     routes: sorted,
     wsRoutes,
     rootDir,
+    dist,
+    resourcesDir,
     tasks: taskQueue,
     async listen(listenPort) {
       const envPort = process.env.PORT ? Number(process.env.PORT) : void 0;
@@ -7624,7 +7691,8 @@ async function createAppBase(options) {
             routes: sorted,
             server,
             registries,
-            tasks: taskQueue
+            tasks: taskQueue,
+            resourcesDir
           });
           console.log("- onBoot hook executed");
         } catch (err) {
@@ -7659,7 +7727,8 @@ async function createAppBase(options) {
               routes: sorted,
               server,
               registries,
-              tasks: taskQueue
+              tasks: taskQueue,
+              resourcesDir
             });
             console.log("- onReady hook executed");
           }
@@ -7683,7 +7752,8 @@ async function createAppBase(options) {
           routes: sorted,
           server,
           registries,
-          tasks: taskQueue
+          tasks: taskQueue,
+          resourcesDir
         });
       }
       registries.tool.clear();
@@ -7745,21 +7815,21 @@ async function createAppBase(options) {
 }
 
 // src/cli/createDevApp.ts
-import path30 from "path";
+import path31 from "path";
 
 // src/router/scanRoutes.ts
 import fg3 from "fast-glob";
-import path27 from "path";
-import fs22 from "fs";
+import path28 from "path";
+import fs23 from "fs";
 
 // src/router/constants.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var HTTP_METHOD_SET = new Set(HTTP_METHODS);
 
 // src/utils/normalizePath.ts
-function normalizePath(path31) {
-  if (!path31) return "";
-  let result = path31.replace(/\\/g, "/");
+function normalizePath(path32) {
+  if (!path32) return "";
+  let result = path32.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -7820,34 +7890,34 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path27.dirname(routeFilePath);
-  const resolvedRoot = path27.resolve(rootDir);
+  const routeDir = path28.dirname(routeFilePath);
+  const resolvedRoot = path28.resolve(rootDir);
   const paths = [];
-  let currentDir = path27.resolve(rootDir, routeDir);
+  let currentDir = path28.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path27.join(currentDir, "middlewares.ts");
-      const mwJsPath = path27.join(currentDir, "middlewares.js");
-      const absTsPath = path27.resolve(rootDir, mwTsPath);
-      const absJsPath = path27.resolve(rootDir, mwJsPath);
-      const absMwPath = fs22.existsSync(absTsPath) ? absTsPath : fs22.existsSync(absJsPath) ? absJsPath : null;
+      const mwTsPath = path28.join(currentDir, "middlewares.ts");
+      const mwJsPath = path28.join(currentDir, "middlewares.js");
+      const absTsPath = path28.resolve(rootDir, mwTsPath);
+      const absJsPath = path28.resolve(rootDir, mwJsPath);
+      const absMwPath = fs23.existsSync(absTsPath) ? absTsPath : fs23.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path27.relative(rootDir, absMwPath);
-        const prodAbsPath = path27.resolve(rootDir, toProdFilePath(relMwPath, dist));
+        const relMwPath = path28.relative(rootDir, absMwPath);
+        const prodAbsPath = path28.resolve(rootDir, toProdFilePath(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path27.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path27.resolve(rootDir, mwPath);
-        if (fs22.existsSync(absMwPath)) {
+        const mwPath = path28.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path28.resolve(rootDir, mwPath);
+        if (fs23.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
         }
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path27.dirname(currentDir);
+    const parentDir = path28.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -7866,7 +7936,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path27.resolve(rootDir, normalizedFile);
+      const absPath = path28.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -7879,7 +7949,7 @@ async function scanRoutes(rootDir, patterns, dist) {
         const mwPaths = collectMiddlewarePaths(normalizedFile, rootDir);
         middlewareBundle = await loadMergedMiddlewares(mwPaths);
       }
-      const source = await fs22.promises.readFile(absPath, "utf8").catch(() => "");
+      const source = await fs23.promises.readFile(absPath, "utf8").catch(() => "");
       const exportNames = extractExportsFromSource(source);
       const methods = HTTP_METHODS.filter((m) => exportNames.has(m));
       for (const method of methods) {
@@ -7915,8 +7985,8 @@ async function scanRoutes(rootDir, patterns, dist) {
 
 // src/tools/scanTools.ts
 import fg4 from "fast-glob";
-import path28 from "path";
-import fs23 from "fs";
+import path29 from "path";
+import fs24 from "fs";
 var TOOL_PATTERNS = ["src/tools/**/*.ts"];
 var TOOL_EXPORT_RE = new RegExp(
   String.raw`export\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)\s*(?:\(|=)`,
@@ -7966,8 +8036,8 @@ async function scanTools(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path28.resolve(rootDir, normalizedFile);
-    const source = await fs23.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path29.resolve(rootDir, normalizedFile);
+    const source = await fs24.promises.readFile(absPath, "utf8").catch(() => "");
     const exportNames = extractToolExportsFromSource(source);
     const namespace = filePathToToolNamespace(normalizedFile);
     for (const fnName of exportNames) {
@@ -7991,8 +8061,8 @@ async function scanTools(rootDir, patterns) {
 
 // src/agents/scanAgents.ts
 import fg5 from "fast-glob";
-import path29 from "path";
-import fs24 from "fs";
+import path30 from "path";
+import fs25 from "fs";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
 var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
 function extractAgentNameFromPath(filePath) {
@@ -8024,8 +8094,8 @@ async function scanAgents(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path29.resolve(rootDir, normalizedFile);
-    const source = await fs24.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path30.resolve(rootDir, normalizedFile);
+    const source = await fs25.promises.readFile(absPath, "utf8").catch(() => "");
     const { hasRun } = detectAgentExports(source);
     const name = extractAgentNameFromPath(normalizedFile);
     const prevFile = seen.get(name);
@@ -8096,7 +8166,7 @@ async function createDevApp(options) {
     if (!suppressProgramInvalidation) invalidateProgramCache();
     const tasks = await scanTasks(ctx.rootDir, TASK_PATTERNS);
     for (const task of tasks) {
-      await ensureCompiled(path30.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
+      await ensureCompiled(path31.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
     }
     await generateTaskArtifacts(tasks, ctx.rootDir, ctx.dist);
     ctx.taskQueue.invalidateModules();