@farm.js/core 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/nitro-QO5LV6QK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/nitro/index.ts"],"sourcesContent":["import type { NitroConfig } from \"nitro/config\";\nimport type { ResolvedFarmConfig } from \"../config\";\nimport type { RouteManager } from \"../routing/route-manager\";\nimport type { APIRouteManager } from \"../api/route-manager\";\nimport type { ServerRenderer } from \"../server/renderer\";\nimport { createNitroAPIHandler } from \"./api-handler\";\nimport { createNitroSSRHandler } from \"./ssr-handler\";\nimport path from \"path\";\nimport { prepareFarmWorkflowsForNitro } from \"../workflows\";\nimport {\n  createFarmCronCloudflareConfig,\n  mergeScheduledTasks,\n  prepareFarmCronForNitro,\n} from \"../cron\";\nimport { routeRulesToNitroRouteRules } from \"../route-rules\";\n\n/**\n * Create Nitro configuration for Farm.js\n * Based on https://nitro.build/config\n */\nexport async function createNitroConfig(\n  config: ResolvedFarmConfig,\n  routeManager: RouteManager,\n  apiRouteManager: APIRouteManager,\n  serverRenderer: ServerRenderer,\n  preset = \"node-server\",\n): Promise<NitroConfig> {\n  const root = config.root || process.cwd();\n  const srcDir = config.srcDir || \"src\";\n  const distDir = \".farm\";\n  // Nitro build directory - where Nitro does its work (temporary)\n  // We use .nitro as a working directory, but ensure output goes to .farm/.output\n  const nitroBuildDir = path.join(root, distDir, \".nitro\");\n  // Final output directory - where the deployable output goes\n  // This MUST be .farm/.output (not .nitro/.output) for consistency\n  const outputDir = path.join(root, distDir, \".output\");\n  // Server directory for handlers (inside build dir, will be copied to output)\n  const serverDir = path.join(nitroBuildDir, \"server\");\n\n  // Ensure Nitro doesn't create its own .output inside .nitro\n  // By explicitly setting output.dir, Nitro will use our specified directory\n\n  // Create server directory structure for Nitro to discover routes\n  // According to Nitro docs: https://nitro.build/deploy/providers/vercel\n  // Routes should be in server/api/[...].ts and server/routes/[...].ts\n  const { mkdir, writeFile } = await import(\"fs/promises\");\n  await mkdir(serverDir, { recursive: true });\n  await mkdir(path.join(serverDir, \"api\"), { recursive: true });\n  await mkdir(path.join(serverDir, \"routes\"), { recursive: true });\n  const farmWorkflows = await prepareFarmWorkflowsForNitro({\n    ...config,\n    distDir,\n  });\n  const farmCron = await prepareFarmCronForNitro({\n    ...config,\n    distDir,\n  });\n  const scheduledTasks = mergeScheduledTasks(farmWorkflows.scheduledTasks, farmCron.scheduledTasks);\n  const cloudflareCronConfig = createFarmCronCloudflareConfig(farmCron.jobs);\n\n  // Create a runtime registry file to store route managers\n  // This will be populated at runtime through Nitro hooks\n  const registryFile = path.join(serverDir, \"farm-registry.ts\");\n\n  // Serialize route paths for SSR module loading\n  const routePaths: Record<string, string> = {};\n  for (const [pattern, entry] of routeManager.getRoutes()) {\n    const bundledPath = entry.modulePath\n      .replace(/.*\\/src\\/app\\//, \"\")\n      .replace(/\\.(tsx?|jsx?)$/, \".js\");\n    routePaths[pattern] = bundledPath;\n  }\n\n  // Load client manifest path for reference\n  const clientManifestPath = path.join(root, distDir, \"client\", \"farm-client-manifest.json\");\n\n  await writeFile(\n    registryFile,\n    `\n// Auto-generated by Farm.js\n// Runtime registry for route managers and renderers\nexport const farmRegistry: {\n  apiRouteManager?: any;\n  routeManager?: any;\n  serverRenderer?: any;\n  env?: any;\n  deploymentId?: string;\n  basePath?: string;\n  clientManifest?: any;\n  routePaths?: Record<string, string>;\n} = {\n  env: ${JSON.stringify(config.env || { server: {}, public: {} }, null, 2)},\n  deploymentId: ${JSON.stringify(config.deploymentId)},\n  basePath: ${JSON.stringify(config.basePath)},\n  routePaths: ${JSON.stringify(routePaths, null, 2)},\n};\n`,\n    \"utf-8\",\n  );\n\n  // Create API route handler file\n  // For Vercel, Nitro expects routes in server/api/[...].ts format\n  // This catch-all will handle all /api/* requests\n  const apiHandlerFile = path.join(serverDir, \"api\", \"[...].ts\");\n  await mkdir(path.dirname(apiHandlerFile), { recursive: true });\n  await writeFile(\n    apiHandlerFile,\n    `\n// Auto-generated by Farm.js\n// This handler intercepts all /api/* requests\nimport { defineEventHandler, getHeaders, readBody, sendWebResponse, setResponseStatus, getRequestURL } from 'h3';\nimport type { H3Event } from 'h3';\nimport { farmRegistry } from '../farm-registry';\n\nexport default defineEventHandler(async (event: H3Event) => {\n  // Get URL using H3's abstraction (works in all environments)\n  const url = getRequestURL(event);\n  const urlPath = url.pathname;\n  \n  // Only handle API routes - for Vercel, Nitro routes /api/* to this handler\n  // According to https://nitro.build/deploy/providers/vercel\n  // This handler should process all /api/* routes\n  if (!urlPath.startsWith('/api/')) {\n    // Return undefined to let Nitro's routing system handle non-API routes\n    return undefined;\n  }\n  \n  // Ensure registry is populated (lazy initialization)\n  // In serverless environments, the registry needs to be initialized at runtime\n  if (!farmRegistry.apiRouteManager) {\n    // Try to initialize from global if available (set during build)\n    if (typeof globalThis !== 'undefined' && (globalThis as any).__FARM_REGISTRY__) {\n      Object.assign(farmRegistry, (globalThis as any).__FARM_REGISTRY__);\n    }\n    // If still not available, try the init function (if it exists)\n    if (!farmRegistry.apiRouteManager && (farmRegistry as any).__INIT__) {\n      (farmRegistry as any).__INIT__();\n    }\n  }\n  \n  const apiRouteManager = farmRegistry.apiRouteManager;\n  if (!apiRouteManager) {\n    console.error('API route manager not initialized. Registry keys:', Object.keys(farmRegistry));\n    setResponseStatus(event, 500);\n    return { error: 'API route manager not initialized. Please check server logs.' };\n  }\n  \n  const startTime = Date.now();\n  const method = event.method || 'GET';\n  const host = url.host || 'localhost';\n  \n  // Log API request (only in development)\n  if (process.env.NODE_ENV === 'development' || !process.env.NODE_ENV) {\n    try {\n      const pc = await import('picocolors');\n      const log = [\n        pc.default.dim('[') + pc.default.bold(pc.default.blue('FARM')) + pc.default.dim(']'),\n        pc.default.dim('[') + pc.default.bold(pc.default.white(method.padEnd(3))) + pc.default.dim(']'),\n        pc.default.cyan('[API]'),\n        pc.default.gray(\\`\\${url.protocol}//\\${host}\\${urlPath}\\`),\n      ].join(' ');\n      console.log(log);\n    } catch {\n      // picocolors not available, use simple log\n      console.log(\\`[FARM] [\\${method}] [API] \\${urlPath}\\`);\n    }\n  }\n  \n  try {\n    // Convert H3 event to Web Request using H3 abstractions\n    const protocol = url.protocol.replace(':', '') || 'http';\n    const host = url.host || 'localhost';\n    const fullUrl = url.toString();\n    \n    const headers = new Headers();\n    const h3Headers = getHeaders(event);\n    \n    for (const [key, value] of Object.entries(h3Headers)) {\n      if (value) {\n        headers.set(key, Array.isArray(value) ? value.join(', ') : String(value));\n      }\n    }\n    \n    // Get body\n    let body: string | undefined;\n    const method = event.method || 'GET';\n    if (method !== 'GET' && method !== 'HEAD') {\n      const bodyData = await readBody(event).catch(() => undefined);\n      if (bodyData) {\n        body = typeof bodyData === 'string' ? bodyData : JSON.stringify(bodyData);\n      }\n    }\n    \n    // Create Web Request\n    const request = new Request(fullUrl, {\n      method,\n      headers,\n      body: body || undefined,\n    });\n    \n    // Call better-call handler\n    const betterCallHandler = apiRouteManager.getHandler();\n    if (!betterCallHandler) {\n      setResponseStatus(event, 404);\n      return { error: 'API handler not found' };\n    }\n    \n    const response = await betterCallHandler(request);\n    \n    // Log API response (only in development)\n    if (process.env.NODE_ENV === 'development' || !process.env.NODE_ENV) {\n      const duration = Date.now() - startTime;\n      const status = response.status;\n      try {\n        const pc = await import('picocolors');\n        let statusColor = pc.default.green;\n        if (status >= 500) statusColor = pc.default.red;\n        else if (status >= 400) statusColor = pc.default.yellow;\n        else if (status >= 300) statusColor = pc.default.cyan;\n\n        const log = [\n          pc.default.dim('[') + pc.default.bold(pc.default.blue('FARM')) + pc.default.dim(']'),\n          status >= 400 ? pc.default.red('✗') : pc.default.green('✓'),\n          pc.default.cyan('[API]'),\n          pc.default.gray(urlPath),\n          pc.default.dim('-'),\n          statusColor(status.toString()),\n          pc.default.dim(\\`(\\${duration}ms)\\`),\n        ].join(' ');\n        console.log(log);\n      } catch {\n        // picocolors not available, use simple log\n        console.log(\\`[FARM] [\\${method}] [API] \\${urlPath} - \\${response.status} (\\${duration}ms)\\`);\n      }\n    }\n    \n    return sendWebResponse(response);\n  } catch (error: any) {\n    console.error('API handler error:', error);\n    setResponseStatus(event, 500);\n    return {\n      error: error.message || 'Internal Server Error',\n    };\n  }\n});\n`,\n    \"utf-8\",\n  );\n\n  // Create SSR catch-all route handler\n  // For Vercel, Nitro expects routes in server/routes/[...].ts format\n  const ssrHandlerFile = path.join(serverDir, \"routes\", \"[...].ts\");\n  await mkdir(path.dirname(ssrHandlerFile), { recursive: true });\n  await writeFile(\n    ssrHandlerFile,\n    `\n// Auto-generated by Farm.js\n// This handler handles all page routes (SSR)\nimport { defineEventHandler, setResponseStatus, getRequestURL, setHeader, getHeaders, readBody, sendWebResponse, setCookie } from 'h3';\nimport type { H3Event } from 'h3';\nimport { farmRegistry } from '../farm-registry';\nimport React from 'react';\nimport { renderToString } from 'react-dom/server';\n\nexport default defineEventHandler(async (event: H3Event) => {\n  try {\n    // Ensure registry is populated (lazy initialization)\n    // In serverless environments, the registry needs to be initialized at runtime\n    if (!farmRegistry.routeManager || !farmRegistry.serverRenderer) {\n      // Try to initialize from global if available (set during build)\n      if (typeof globalThis !== 'undefined' && (globalThis as any).__FARM_REGISTRY__) {\n        Object.assign(farmRegistry, (globalThis as any).__FARM_REGISTRY__);\n      }\n      // If still not available, try the init function (if it exists)\n      if ((!farmRegistry.routeManager || !farmRegistry.serverRenderer) && (farmRegistry as any).__INIT__) {\n        (farmRegistry as any).__INIT__();\n      }\n    }\n    \n    const routeManager = farmRegistry.routeManager;\n    const serverRenderer = farmRegistry.serverRenderer;\n    \n    if (!routeManager || !serverRenderer) {\n      console.error('Route manager or renderer not initialized. Registry keys:', Object.keys(farmRegistry));\n      setResponseStatus(event, 500);\n      setHeader(event, 'Content-Type', 'text/html; charset=utf-8');\n      return '<!DOCTYPE html><html><head><title>Error</title></head><body><h1>500 Internal Server Error</h1><p>Route manager or renderer not initialized. Please check server logs.</p></body></html>';\n    }\n    \n    // Get URL from H3 event\n    const url = getRequestURL(event);\n    const pathname = url.pathname;\n    const redirectMatch = routeManager.matchRedirect(pathname);\n    if (redirectMatch) {\n      setResponseStatus(event, redirectMatch.statusCode);\n      setHeader(event, 'Location', redirectMatch.destination);\n      return \\`Redirecting to \\${redirectMatch.destination}\\`;\n    }\n    const apiRouteManager = farmRegistry.apiRouteManager;\n\n    if (apiRouteManager?.matchRoute(pathname)) {\n      const handler = apiRouteManager.getHandler();\n      if (!handler) {\n        setResponseStatus(event, 404);\n        return { error: 'API handler not found' };\n      }\n\n      const headers = new Headers();\n      const h3Headers = getHeaders(event);\n      for (const [key, value] of Object.entries(h3Headers)) {\n        if (value) {\n          headers.set(key, Array.isArray(value) ? value.join(', ') : String(value));\n        }\n      }\n\n      let body: string | undefined;\n      const method = event.method || 'GET';\n      if (method !== 'GET' && method !== 'HEAD') {\n        const bodyData = await readBody(event).catch(() => undefined);\n        if (bodyData) {\n          body = typeof bodyData === 'string' ? bodyData : JSON.stringify(bodyData);\n        }\n      }\n\n      const response = await handler(new Request(url.toString(), {\n        method,\n        headers,\n        body: body || undefined,\n      }));\n\n      return sendWebResponse(response);\n    }\n\n    // Skip API routes - let the API handler process them\n    if (pathname.startsWith('/api/')) {\n      // Return undefined to let Nitro's API handler process\n      return undefined;\n    }\n    \n    // Skip static assets - let Nitro serve them\n    // Only skip if it's clearly a static file (has extension and not in root)\n    if (pathname.startsWith('/assets/') || (pathname.includes('.') && !pathname.startsWith('/api/'))) {\n      // Check if it's a static file by extension\n      const staticExtensions = ['.js', '.css', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'];\n      const hasStaticExtension = staticExtensions.some(ext => pathname.toLowerCase().endsWith(ext));\n      if (hasStaticExtension) {\n        return; // Let Nitro's static file handler process\n      }\n    }\n    \n    // Try to use Node.js req/res if available (for node-server preset)\n    if (event.node && event.node.req && event.node.res) {\n      await serverRenderer.renderPage(event.node.req as any, event.node.res as any);\n      return undefined; // Response already sent\n    }\n\n    if (farmRegistry.deploymentId) {\n      setHeader(event, 'x-farm-deployment-id', farmRegistry.deploymentId);\n      setCookie(event, '__farm_deployment', farmRegistry.deploymentId, {\n        httpOnly: true,\n        sameSite: 'lax',\n        secure: url.protocol === 'https:',\n        path: farmRegistry.basePath || '/',\n      });\n    }\n    \n    // For serverless (Vercel), render to string and send HTML\n    try {\n      // Match route\n      const { route, params, layouts } = routeManager.matchRoute(pathname);\n      \n      if (!route) {\n        setResponseStatus(event, 404);\n        setHeader(event, 'Content-Type', 'text/html; charset=utf-8');\n        return '<!DOCTYPE html><html><head><title>404 Not Found</title></head><body><h1>404 Not Found</h1></body></html>';\n      }\n      \n      // Get search params\n      const searchParamsObject: Record<string, string | string[] | undefined> = {};\n      url.searchParams.forEach((value, key) => {\n        const existing = searchParamsObject[key];\n        if (existing) {\n          if (Array.isArray(existing)) {\n            existing.push(value);\n          } else {\n            searchParamsObject[key] = [existing, value];\n          }\n        } else {\n          searchParamsObject[key] = value;\n        }\n      });\n      \n      // Load route module - in production, use bundled SSR output\n      // Get bundled path from registry or construct it\n      let routeModule;\n      const routePaths = farmRegistry.routePaths || {};\n      const bundledPath = routePaths[pathname] || route.modulePath\n        .replace(/.*\\\\/src\\\\/app\\\\//, '')\n        .replace(/\\\\.(tsx?|jsx?)$/, '.js');\n      \n      try {\n        // Try to load from bundled SSR output (copied to Nitro's server/farm directory)\n        // Nitro bundles everything, so we need to use the correct import path\n        routeModule = await import('./farm/' + bundledPath);\n      } catch (importError) {\n        // Fallback: try route manager's load method (for node-server preset)\n        try {\n          routeModule = await routeManager.loadRouteModule(route.modulePath);\n        } catch (loadError) {\n          // Last resort: try just the filename\n          const bundledName = bundledPath.split('/').pop() || 'page.js';\n          try {\n            routeModule = await import('./farm/' + bundledName);\n          } catch {\n            throw new Error(\\`Failed to load route module: \\${route.modulePath}. Tried: ./farm/\\${bundledPath}, ./farm/\\${bundledName}\\`);\n          }\n        }\n      }\n      \n      if (!routeModule.default) {\n        throw new Error(\\`Route module \\${route.modulePath} does not export a default component\\`);\n      }\n      \n      // Load layout modules\n      const layoutModules = await Promise.all(\n        layouts.map(async (layout) => {\n          const bundledPath = layout.modulePath\n            .replace(/.*\\\\/src\\\\/app\\\\//, '')\n            .replace(/\\\\.(tsx?|jsx?)$/, '.js');\n          \n          try {\n            // Try to load from bundled SSR output\n            return await import('./farm/' + bundledPath);\n          } catch {\n            // Fallback to route manager's load method\n            try {\n              return await routeManager.loadLayoutModule(layout.modulePath);\n            } catch {\n              // Last resort: try just the filename\n              const bundledName = bundledPath.split('/').pop() || 'layout.js';\n              try {\n                return await import('./farm/' + bundledName);\n              } catch {\n                // Return a dummy layout if all fails\n                return { default: ({ children }: any) => children };\n              }\n            }\n          }\n        })\n      );\n      \n      // Create page props\n      const rawPageProps = {\n        params,\n        searchParams: Promise.resolve(searchParamsObject),\n        path: pathname,\n      };\n      const pageProps = routeModule.__farmResolveRouteProps\n        ? await routeModule.__farmResolveRouteProps(rawPageProps)\n        : (() => {\n            const routeSchemas = routeModule.__farmRouteParsesProps\n              ? {}\n              : routeModule.__farmRouteSchemas || {};\n            const parsedParams = routeSchemas.params?.parse\n              ? routeSchemas.params.parse(params)\n              : params;\n            const parsedSearch = routeSchemas.search?.parse\n              ? routeSchemas.search.parse(searchParamsObject)\n              : searchParamsObject;\n            return {\n              ...rawPageProps,\n              params: parsedParams,\n              search: parsedSearch,\n              searchParams: Promise.resolve(parsedSearch),\n            };\n          })();\n      \n      // Create page element\n      const PageComponent = routeModule.default;\n      let pageElement;\n      if (PageComponent.constructor.name === \"AsyncFunction\" || PageComponent.toString().includes(\"async\")) {\n        pageElement = await PageComponent(pageProps);\n      } else {\n        pageElement = React.createElement(PageComponent, pageProps);\n      }\n      \n      // Wrap with layouts\n      for (let i = layoutModules.length - 1; i >= 0; i--) {\n        const layoutModule = layoutModules[i];\n        const LayoutComponent = layoutModule.default;\n        pageElement = React.createElement(LayoutComponent, {\n          children: pageElement,\n          params,\n        } as any);\n      }\n      \n      // Render to string\n      const html = renderToString(pageElement);\n      \n      // Get client script path from manifest\n      const clientManifest = farmRegistry.clientManifest || {};\n      // Find the client script for this route - check manifest structure\n      let clientScript = '/assets/page-wbYjx1yQ.js'; // Default fallback\n      if (clientManifest && typeof clientManifest === 'object') {\n        // Manifest structure: { \"assets/page-xxx.js\": { ... } }\n        const manifestEntry = Object.values(clientManifest).find((entry: any) => \n          entry && entry.name === 'page'\n        ) as any;\n        if (manifestEntry && manifestEntry.chunks && manifestEntry.chunks[0]) {\n          clientScript = '/' + manifestEntry.chunks[0];\n        } else if (Object.keys(clientManifest).length > 0) {\n          // Fallback to first asset in manifest\n          clientScript = '/' + Object.keys(clientManifest)[0];\n        }\n      }\n      \n      // Build full HTML\n      const serializedDeploymentId = JSON.stringify(farmRegistry.deploymentId || '').replace(/</g, '\\\\u003c');\n      const fullHtml = \\`<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <link rel=\"icon\" href=\"data:,\">\n  <title>Farm.js App</title>\n  <script>\n    window.__FARM_DEPLOYMENT_ID__ = \\${serializedDeploymentId};\n    window.__FARM_PROPS__ = \\${JSON.stringify(pageProps)};\n    window.__FARM_PATH__ = \\${JSON.stringify(pathname)};\n  </script>\n</head>\n<body>\n  <div id=\"root\">\\${html}</div>\n  <script type=\"module\" src=\"\\${clientScript}\"></script>\n</body>\n</html>\\`;\n      \n      setHeader(event, 'Content-Type', 'text/html; charset=utf-8');\n      return fullHtml;\n      \n    } catch (renderError: any) {\n      setResponseStatus(event, 500);\n      setHeader(event, 'Content-Type', 'text/html; charset=utf-8');\n      return \\`<!DOCTYPE html><html><head><title>Error</title></head><body><h1>Error</h1><p>\\${renderError.message || 'Internal Server Error'}</p></body></html>\\`;\n    }\n  } catch (error: any) {\n    setResponseStatus(event, 500);\n    setHeader(event, 'Content-Type', 'text/html; charset=utf-8');\n    return \\`<!DOCTYPE html><html><head><title>Error</title></head><body><h1>Error</h1><p>\\${error.message || 'Internal Server Error'}</p></body></html>\\`;\n  }\n});\n`,\n    \"utf-8\",\n  );\n\n  // Create Nitro config according to https://nitro.build/config\n  // Compatibility date is required in Nitro v3\n  const nitroConfig: NitroConfig = {\n    preset,\n    // rootDir must be the project root for Nitro to correctly resolve paths\n    rootDir: root,\n    // srcDir should point to where source files are (for scanning)\n    // But we're using scanDirs to point to our server directory\n    srcDir: root,\n    // buildDir is where Nitro builds (temporary working directory)\n    buildDir: nitroBuildDir,\n    // output.dir is where the final deployable output goes\n    // This ensures everything ends up in .farm/.output\n    compatibilityDate: \"2024-12-01\",\n    // Vercel-specific configuration\n    ...(preset === \"vercel\"\n      ? {\n          vercel: {\n            // Ensure proper function configuration\n            config: {},\n          },\n        }\n      : {}),\n    // Tell Nitro to scan the server directory we created\n    // This ensures our handlers are discovered by Nitro\n    scanDirs: [serverDir],\n    tasks: {\n      ...farmWorkflows.tasks,\n      ...farmCron.tasks,\n    },\n    scheduledTasks,\n    ...(preset === \"cloudflare-module\" && cloudflareCronConfig\n      ? {\n          cloudflare: cloudflareCronConfig,\n        }\n      : {}),\n    handlers: farmWorkflows.handlerPath\n      ? [\n          {\n            route: `${config.workflows.route}/**`,\n            handler: farmWorkflows.handlerPath,\n          },\n        ]\n      : [],\n    // Route rules for Vercel\n    routeRules: {\n      \"/api/**\": {\n        cors: true,\n        headers: {\n          \"Access-Control-Allow-Origin\": \"*\",\n          \"Access-Control-Allow-Methods\": \"*\",\n          \"Access-Control-Allow-Headers\": \"*\",\n        },\n      },\n      \"/**\": {\n        prerender: false,\n      },\n      ...routeRulesToNitroRouteRules(config.routeRules),\n    },\n\n    // // Exclude certain directories from scanning\n    // scanDirsExclude: [\n    //   '**/node_modules/**',\n    //   '**/.git/**',\n    //   '**/.output/**',\n    //   '**/.nitro/**',\n    // ],\n    output: {\n      // CRITICAL: All output MUST go to .farm/.output (NOT .nitro/.output)\n      // This ensures consistency and that deployment always uses .farm/.output\n      // By explicitly setting dir, serverDir, and publicDir, we prevent Nitro\n      // from creating its own .output directory inside .nitro\n      dir: outputDir, // .farm/.output\n      serverDir: path.join(outputDir, \"server\"), // .farm/.output/server\n      publicDir: path.join(outputDir, \"public\"), // .farm/.output/public\n    },\n    // Use Nitro hooks to populate the runtime registry\n    // This allows us to pass complex objects (route managers, renderers) at runtime\n    hooks: {\n      \"build:before\": async (nitro: any) => {\n        // Import and populate the registry at build time\n        const registryPath = path.join(serverDir, \"farm-registry.ts\");\n        const { farmRegistry } = await import(/* @vite-ignore */ registryPath);\n\n        // Store route paths (serializable)\n        const routePaths: Record<string, string> = {};\n        for (const [pattern, entry] of routeManager.getRoutes()) {\n          const bundledPath = entry.modulePath\n            .replace(/.*\\/src\\/app\\//, \"\")\n            .replace(/\\.(tsx?|jsx?)$/, \".js\");\n          routePaths[pattern] = bundledPath;\n        }\n        farmRegistry.routePaths = routePaths;\n\n        // Load and store client manifest for SSR\n        try {\n          const clientManifestPath = path.join(\n            root,\n            distDir,\n            \"client\",\n            \"farm-client-manifest.json\",\n          );\n          const { readFile } = await import(\"fs/promises\");\n          const manifestContent = await readFile(clientManifestPath, \"utf-8\");\n          farmRegistry.clientManifest = JSON.parse(manifestContent);\n        } catch (error) {\n          // Manifest not critical, continue without it\n          farmRegistry.clientManifest = {};\n        }\n\n        // CRITICAL: Store managers in a way that persists to runtime\n        // In serverless, we can't serialize complex objects, so we store them\n        // in a module-level variable that will be available at runtime\n        // The handlers will access them through the registry\n        // We use a closure to capture the managers\n        (farmRegistry as any).__INIT__ = () => {\n          farmRegistry.apiRouteManager = apiRouteManager;\n          farmRegistry.routeManager = routeManager;\n          farmRegistry.serverRenderer = serverRenderer;\n          farmRegistry.env = config.env || { server: {}, public: {} };\n          farmRegistry.deploymentId = config.deploymentId;\n          farmRegistry.basePath = config.basePath;\n        };\n\n        // Also store in global for runtime access (works in serverless)\n        // This ensures they're available even if module state is reset\n        if (typeof globalThis !== \"undefined\") {\n          (globalThis as any).__FARM_REGISTRY__ = {\n            apiRouteManager,\n            routeManager,\n            serverRenderer,\n            env: farmRegistry.env,\n            deploymentId: farmRegistry.deploymentId,\n            basePath: farmRegistry.basePath,\n            clientManifest: farmRegistry.clientManifest,\n            routePaths: farmRegistry.routePaths,\n          };\n        }\n      },\n    },\n    // API base URL (default is /api)\n    apiBaseURL: \"/api\",\n    // Include public directory and client build\n    publicAssets: [\n      {\n        baseURL: \"/\",\n        dir: path.join(root, \"public\"),\n      },\n      // Include client build assets\n      {\n        baseURL: \"/\",\n        dir: path.join(root, distDir, \"client\"),\n      },\n    ],\n    // Build configuration\n    minify: process.env.NODE_ENV === \"production\",\n    sourceMap: true,\n    // Bundle all dependencies to avoid workspace issues on Vercel\n    // This ensures all farm package code is bundled into the serverless function\n    // so it doesn't need to resolve workspace dependencies at runtime\n    // This is similar to how Next.js and Nuxt bundle their core packages\n    // bundle: true,\n    // External dependencies that should NOT be bundled (provided by runtime)\n    // We exclude React/ReactDOM to reduce bundle size (they're in node_modules)\n    externals: {\n      external: [\"react\", \"react-dom\"],\n      // Keep React external - it's in the serverless function's node_modules\n      // This reduces bundle size significantly\n    },\n    // Runtime config\n    runtimeConfig: {\n      public: {},\n    },\n    // Experimental features\n    experimental: {\n      tasks: farmWorkflows.workflows.length > 0 || farmCron.jobs.length > 0,\n      wasm: false, // Disable for now to avoid issues\n    },\n  };\n\n  return nitroConfig;\n}\n\n/**\n * Get Nitro preset from config\n */\nexport function getNitroPreset(preset?: string): string {\n  return preset || \"node-server\";\n}\n"],"mappings":"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AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;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","names":["routePaths","clientManifestPath"]}

package/dist/observability.cjs

@@ -0,0 +1,186 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/observability.ts
+var observability_exports = {};
+__export(observability_exports, {
+  configureFarmObservability: () => configureFarmObservability,
+  emitFarmEvent: () => emitFarmEvent,
+  normalizeFarmObservabilityConfig: () => normalizeFarmObservabilityConfig,
+  onFarmEvent: () => onFarmEvent,
+  resetFarmObservability: () => resetFarmObservability
+});
+module.exports = __toCommonJS(observability_exports);
+var runtimeHandlers = /* @__PURE__ */ new Set();
+var observabilityState = {
+  logs: false,
+  handlers: []
+};
+function configureFarmObservability(config) {
+  observabilityState = normalizeFarmObservabilityConfig(config);
+}
+__name(configureFarmObservability, "configureFarmObservability");
+function normalizeFarmObservabilityConfig(config) {
+  if (config === void 0 || config === false) {
+    return { logs: false, handlers: [] };
+  }
+  if (config === true) {
+    return { logs: true, handlers: [] };
+  }
+  const handlers = config.onEvent ? Array.isArray(config.onEvent) ? [...config.onEvent] : [config.onEvent] : [];
+  return {
+    logs: config.logs ?? false,
+    handlers,
+    events: config.events ? new Set(config.events) : void 0
+  };
+}
+__name(normalizeFarmObservabilityConfig, "normalizeFarmObservabilityConfig");
+function onFarmEvent(handler) {
+  runtimeHandlers.add(handler);
+  return () => {
+    runtimeHandlers.delete(handler);
+  };
+}
+__name(onFarmEvent, "onFarmEvent");
+function resetFarmObservability() {
+  runtimeHandlers.clear();
+  observabilityState = {
+    logs: false,
+    handlers: []
+  };
+}
+__name(resetFarmObservability, "resetFarmObservability");
+function emitFarmEvent(input) {
+  const event = {
+    timestamp: Date.now(),
+    level: inferFarmEventLevel(input.type),
+    ...input
+  };
+  if (!shouldEmitFarmEvent(event)) {
+    return event;
+  }
+  if (observabilityState.logs) {
+    logFarmEvent(event);
+  }
+  for (const handler of [...observabilityState.handlers, ...runtimeHandlers]) {
+    try {
+      Promise.resolve(handler(event)).catch((error) => {
+        console.warn(`[farm:observability] event handler failed: ${formatError(error)}`);
+      });
+    } catch (error) {
+      console.warn(`[farm:observability] event handler failed: ${formatError(error)}`);
+    }
+  }
+  return event;
+}
+__name(emitFarmEvent, "emitFarmEvent");
+function shouldEmitFarmEvent(event) {
+  if (!observabilityState.logs && observabilityState.handlers.length === 0 && runtimeHandlers.size === 0) {
+    return false;
+  }
+  if (observabilityState.events && !observabilityState.events.has(event.type)) {
+    return false;
+  }
+  return true;
+}
+__name(shouldEmitFarmEvent, "shouldEmitFarmEvent");
+function inferFarmEventLevel(type) {
+  if (type === "error" || type.endsWith(".error") || type.endsWith(".failed")) {
+    return "error";
+  }
+  if (type.endsWith(".bypass") || type.endsWith(".invalidated") || type.endsWith(".stale") || type.endsWith(".notFound")) {
+    return "warn";
+  }
+  if (type.endsWith(".hit") || type.endsWith(".miss") || type.endsWith(".start") || type.endsWith(".shellReady")) {
+    return "debug";
+  }
+  return "info";
+}
+__name(inferFarmEventLevel, "inferFarmEventLevel");
+function logFarmEvent(event) {
+  const message = `[farm:${event.level}] ${event.type}${formatFarmEventDetails(event)}`;
+  switch (event.level) {
+    case "error":
+      console.error(message);
+      break;
+    case "warn":
+      console.warn(message);
+      break;
+    default:
+      console.log(message);
+      break;
+  }
+}
+__name(logFarmEvent, "logFarmEvent");
+function formatFarmEventDetails(event) {
+  const details = [];
+  const record = event;
+  for (const key of [
+    "route",
+    "pathname",
+    "method",
+    "status",
+    "key",
+    "tag",
+    "path",
+    "reason",
+    "durationMs",
+    "integration",
+    "operation",
+    "plugin",
+    "hook",
+    "target",
+    "count"
+  ]) {
+    const value = record[key];
+    if (value !== void 0) {
+      details.push(`${key}=${formatDetailValue(value)}`);
+    }
+  }
+  return details.length > 0 ? ` ${details.join(" ")}` : "";
+}
+__name(formatFarmEventDetails, "formatFarmEventDetails");
+function formatDetailValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+__name(formatDetailValue, "formatDetailValue");
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+__name(formatError, "formatError");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configureFarmObservability,
+  emitFarmEvent,
+  normalizeFarmObservabilityConfig,
+  onFarmEvent,
+  resetFarmObservability
+});
+//# sourceMappingURL=observability.cjs.map

package/dist/observability.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/observability.ts"],"sourcesContent":["export type FarmEventLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport interface FarmEventBase {\n  type: string;\n  timestamp: number;\n  level: FarmEventLevel;\n  requestId?: string;\n  route?: string;\n  pathname?: string;\n}\n\nexport type FarmServerEvent =\n  | (FarmEventBase & {\n      type: \"server.start\";\n      mode: \"dev\" | \"preview\" | \"production\";\n      port?: number;\n    })\n  | (FarmEventBase & { type: \"server.ready\"; url?: string })\n  | (FarmEventBase & { type: \"server.shutdown\"; reason?: string });\n\nexport type FarmRouteEvent =\n  | (FarmEventBase & { type: \"route.discovered\"; route: string; filePath: string })\n  | (FarmEventBase & {\n      type: \"route.matched\";\n      pathname: string;\n      route: string;\n      params?: Record<string, string>;\n    })\n  | (FarmEventBase & { type: \"route.notFound\"; pathname: string })\n  | (FarmEventBase & { type: \"route.redirect\"; from: string; to: string; status?: number })\n  | (FarmEventBase & { type: \"route.rewrite\"; from: string; to: string });\n\nexport type FarmRenderEvent =\n  | (FarmEventBase & { type: \"render.start\"; route: string; pathname?: string })\n  | (FarmEventBase & {\n      type: \"render.complete\";\n      route: string;\n      durationMs: number;\n      status?: number;\n    })\n  | (FarmEventBase & { type: \"render.error\"; route?: string; error: unknown })\n  | (FarmEventBase & { type: \"render.stream.start\"; route: string })\n  | (FarmEventBase & { type: \"render.stream.shellReady\"; route: string; durationMs: number })\n  | (FarmEventBase & { type: \"render.stream.complete\"; route: string; durationMs: number });\n\nexport type FarmCacheEvent =\n  | (FarmEventBase & {\n      type: \"cache.hit\";\n      key: string;\n      route?: string;\n      tags?: readonly string[];\n      revalidate?: number | false;\n      stale?: boolean;\n    })\n  | (FarmEventBase & { type: \"cache.miss\"; key: string; route?: string; reason?: string })\n  | (FarmEventBase & {\n      type: \"cache.set\";\n      key: string;\n      route?: string;\n      tags?: readonly string[];\n      revalidate?: number | false;\n    })\n  | (FarmEventBase & { type: \"cache.dedupe\"; key: string })\n  | (FarmEventBase & { type: \"cache.bypass\"; key?: string; route?: string; reason: string })\n  | (FarmEventBase & {\n      type: \"cache.stale\";\n      key: string;\n      route?: string;\n      tags?: readonly string[];\n      revalidate?: number | false;\n    })\n  | (FarmEventBase & { type: \"cache.revalidatePath\"; path: string; count: number })\n  | (FarmEventBase & {\n      type: \"cache.revalidateTag\";\n      tag: string;\n      profile?: unknown;\n      count: number;\n    })\n  | (FarmEventBase & { type: \"cache.updateTag\"; tag: string; count: number })\n  | (FarmEventBase & {\n      type: \"cache.invalidated\";\n      key?: string;\n      route?: string;\n      tag?: string;\n      reason?: string;\n      count?: number;\n    })\n  | (FarmEventBase & { type: \"cache.delete\"; key: string; deleted: boolean })\n  | (FarmEventBase & { type: \"cache.clear\"; count: number })\n  | (FarmEventBase & {\n      type: \"cache.error\";\n      key?: string;\n      operation: \"get\" | \"set\" | \"delete\" | \"revalidate\";\n      error: unknown;\n    });\n\nexport type FarmPPREvent =\n  | (FarmEventBase & { type: \"ppr.shell.hit\"; route: string; key: string })\n  | (FarmEventBase & { type: \"ppr.shell.miss\"; route: string; key: string })\n  | (FarmEventBase & {\n      type: \"ppr.shell.cached\";\n      route: string;\n      key: string;\n      revalidate?: number;\n    })\n  | (FarmEventBase & { type: \"ppr.shell.bypass\"; route: string; reason: string })\n  | (FarmEventBase & {\n      type: \"ppr.shell.invalidated\";\n      route: string;\n      reason?: string;\n      count?: number;\n    })\n  | (FarmEventBase & { type: \"ppr.suspense.holeDetected\"; route: string })\n  | (FarmEventBase & { type: \"ppr.refresh.start\"; route: string })\n  | (FarmEventBase & { type: \"ppr.refresh.complete\"; route: string; durationMs: number })\n  | (FarmEventBase & { type: \"ppr.refresh.error\"; route: string; error: unknown });\n\nexport type FarmAPIEvent =\n  | (FarmEventBase & { type: \"api.request.start\"; route: string; method: string })\n  | (FarmEventBase & {\n      type: \"api.request.complete\";\n      route: string;\n      method: string;\n      status: number;\n      durationMs: number;\n    })\n  | (FarmEventBase & {\n      type: \"api.validation.failed\";\n      route: string;\n      method: string;\n      issues?: unknown;\n    })\n  | (FarmEventBase & { type: \"api.error\"; route: string; method: string; error: unknown });\n\nexport type FarmIntegrationEvent =\n  | (FarmEventBase & { type: \"integration.registered\"; name: string })\n  | (FarmEventBase & { type: \"integration.config.validated\"; name: string })\n  | (FarmEventBase & { type: \"integration.ready\"; name: string })\n  | (FarmEventBase & { type: \"integration.disposed\"; name: string })\n  | (FarmEventBase & {\n      type: \"integration.api.call.start\";\n      integration: string;\n      operation: string;\n    })\n  | (FarmEventBase & {\n      type: \"integration.api.call.complete\";\n      integration: string;\n      operation: string;\n      durationMs: number;\n    })\n  | (FarmEventBase & {\n      type: \"integration.api.call.error\";\n      integration: string;\n      operation: string;\n      error: unknown;\n    })\n  | (FarmEventBase & { type: \"integration.webhook.received\"; integration: string; event?: string })\n  | (FarmEventBase & { type: \"integration.webhook.verified\"; integration: string; event?: string })\n  | (FarmEventBase & { type: \"integration.webhook.failed\"; integration: string; reason: string });\n\nexport type FarmMiddlewareEvent =\n  | (FarmEventBase & { type: \"middleware.start\"; route?: string; name?: string })\n  | (FarmEventBase & {\n      type: \"middleware.complete\";\n      route?: string;\n      name?: string;\n      durationMs: number;\n    })\n  | (FarmEventBase & {\n      type: \"middleware.shortCircuit\";\n      route?: string;\n      name?: string;\n      status?: number;\n    })\n  | (FarmEventBase & { type: \"middleware.error\"; route?: string; name?: string; error: unknown });\n\nexport type FarmStorageEvent =\n  | (FarmEventBase & { type: \"storage.query.start\"; integration?: string; operation: string })\n  | (FarmEventBase & {\n      type: \"storage.query.complete\";\n      integration?: string;\n      operation: string;\n      durationMs: number;\n    })\n  | (FarmEventBase & {\n      type: \"storage.query.error\";\n      integration?: string;\n      operation: string;\n      error: unknown;\n    })\n  | (FarmEventBase & { type: \"storage.schema.ready\"; integration?: string })\n  | (FarmEventBase & { type: \"storage.schema.error\"; integration?: string; error: unknown });\n\nexport type FarmBuildEvent =\n  | (FarmEventBase & { type: \"build.start\"; target?: string })\n  | (FarmEventBase & { type: \"build.complete\"; target?: string; durationMs: number })\n  | (FarmEventBase & { type: \"build.error\"; target?: string; error: unknown })\n  | (FarmEventBase & { type: \"routes.generated\"; pageCount: number; apiCount?: number })\n  | (FarmEventBase & { type: \"types.generated\"; filePath: string })\n  | (FarmEventBase & { type: \"manifest.generated\"; routeCount: number });\n\nexport type FarmPluginEvent =\n  | (FarmEventBase & { type: \"plugin.hook.start\"; plugin: string; hook: string })\n  | (FarmEventBase & {\n      type: \"plugin.hook.complete\";\n      plugin: string;\n      hook: string;\n      durationMs: number;\n    })\n  | (FarmEventBase & { type: \"plugin.hook.error\"; plugin: string; hook: string; error: unknown });\n\nexport type FarmErrorEvent = FarmEventBase & {\n  type: \"error\";\n  source: string;\n  error: unknown;\n  route?: string;\n};\n\nexport type FarmEvent =\n  | FarmServerEvent\n  | FarmRouteEvent\n  | FarmRenderEvent\n  | FarmCacheEvent\n  | FarmPPREvent\n  | FarmAPIEvent\n  | FarmIntegrationEvent\n  | FarmMiddlewareEvent\n  | FarmStorageEvent\n  | FarmBuildEvent\n  | FarmPluginEvent\n  | FarmErrorEvent;\n\nexport type FarmEventType = FarmEvent[\"type\"];\nexport type FarmEventHandler = (event: FarmEvent) => void | Promise<void>;\n\nexport type FarmEventInput = FarmEvent extends infer T\n  ? T extends FarmEvent\n    ? Omit<T, \"timestamp\" | \"level\"> & Partial<Pick<T, \"timestamp\" | \"level\">>\n    : never\n  : never;\n\nexport type FarmObservabilityUserConfig =\n  | boolean\n  | {\n      logs?: boolean;\n      onEvent?: FarmEventHandler | readonly FarmEventHandler[];\n      events?: readonly FarmEventType[];\n    };\n\nexport interface FarmResolvedObservabilityConfig {\n  logs: boolean;\n  handlers: FarmEventHandler[];\n  events?: Set<FarmEventType>;\n}\n\nconst runtimeHandlers = new Set<FarmEventHandler>();\nlet observabilityState: FarmResolvedObservabilityConfig = {\n  logs: false,\n  handlers: [],\n};\n\nexport function configureFarmObservability(config: FarmObservabilityUserConfig | undefined): void {\n  observabilityState = normalizeFarmObservabilityConfig(config);\n}\n\nexport function normalizeFarmObservabilityConfig(\n  config: FarmObservabilityUserConfig | undefined,\n): FarmResolvedObservabilityConfig {\n  if (config === undefined || config === false) {\n    return { logs: false, handlers: [] };\n  }\n\n  if (config === true) {\n    return { logs: true, handlers: [] };\n  }\n\n  const handlers = config.onEvent\n    ? Array.isArray(config.onEvent)\n      ? [...config.onEvent]\n      : [config.onEvent]\n    : [];\n\n  return {\n    logs: config.logs ?? false,\n    handlers,\n    events: config.events ? new Set(config.events) : undefined,\n  };\n}\n\nexport function onFarmEvent(handler: FarmEventHandler): () => void {\n  runtimeHandlers.add(handler);\n  return () => {\n    runtimeHandlers.delete(handler);\n  };\n}\n\nexport function resetFarmObservability(): void {\n  runtimeHandlers.clear();\n  observabilityState = {\n    logs: false,\n    handlers: [],\n  };\n}\n\nexport function emitFarmEvent(input: FarmEventInput): FarmEvent {\n  const event = {\n    timestamp: Date.now(),\n    level: inferFarmEventLevel(input.type),\n    ...input,\n  } as FarmEvent;\n\n  if (!shouldEmitFarmEvent(event)) {\n    return event;\n  }\n\n  if (observabilityState.logs) {\n    logFarmEvent(event);\n  }\n\n  for (const handler of [...observabilityState.handlers, ...runtimeHandlers]) {\n    try {\n      Promise.resolve(handler(event)).catch((error) => {\n        console.warn(`[farm:observability] event handler failed: ${formatError(error)}`);\n      });\n    } catch (error) {\n      console.warn(`[farm:observability] event handler failed: ${formatError(error)}`);\n    }\n  }\n\n  return event;\n}\n\nfunction shouldEmitFarmEvent(event: FarmEvent): boolean {\n  if (\n    !observabilityState.logs &&\n    observabilityState.handlers.length === 0 &&\n    runtimeHandlers.size === 0\n  ) {\n    return false;\n  }\n\n  if (observabilityState.events && !observabilityState.events.has(event.type)) {\n    return false;\n  }\n\n  return true;\n}\n\nfunction inferFarmEventLevel(type: FarmEventType): FarmEventLevel {\n  if (type === \"error\" || type.endsWith(\".error\") || type.endsWith(\".failed\")) {\n    return \"error\";\n  }\n  if (\n    type.endsWith(\".bypass\") ||\n    type.endsWith(\".invalidated\") ||\n    type.endsWith(\".stale\") ||\n    type.endsWith(\".notFound\")\n  ) {\n    return \"warn\";\n  }\n  if (\n    type.endsWith(\".hit\") ||\n    type.endsWith(\".miss\") ||\n    type.endsWith(\".start\") ||\n    type.endsWith(\".shellReady\")\n  ) {\n    return \"debug\";\n  }\n  return \"info\";\n}\n\nfunction logFarmEvent(event: FarmEvent): void {\n  const message = `[farm:${event.level}] ${event.type}${formatFarmEventDetails(event)}`;\n  switch (event.level) {\n    case \"error\":\n      console.error(message);\n      break;\n    case \"warn\":\n      console.warn(message);\n      break;\n    default:\n      console.log(message);\n      break;\n  }\n}\n\nfunction formatFarmEventDetails(event: FarmEvent): string {\n  const details: string[] = [];\n  const record = event as unknown as Record<string, unknown>;\n\n  for (const key of [\n    \"route\",\n    \"pathname\",\n    \"method\",\n    \"status\",\n    \"key\",\n    \"tag\",\n    \"path\",\n    \"reason\",\n    \"durationMs\",\n    \"integration\",\n    \"operation\",\n    \"plugin\",\n    \"hook\",\n    \"target\",\n    \"count\",\n  ]) {\n    const value = record[key];\n    if (value !== undefined) {\n      details.push(`${key}=${formatDetailValue(value)}`);\n    }\n  }\n\n  return details.length > 0 ? ` ${details.join(\" \")}` : \"\";\n}\n\nfunction formatDetailValue(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n  if (typeof value === \"number\" || typeof value === \"boolean\") {\n    return String(value);\n  }\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\nfunction formatError(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":"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","names":[]}

package/dist/observability.d.mts

@@ -0,0 +1,335 @@
+type FarmEventLevel = "debug" | "info" | "warn" | "error";
+interface FarmEventBase {
+    type: string;
+    timestamp: number;
+    level: FarmEventLevel;
+    requestId?: string;
+    route?: string;
+    pathname?: string;
+}
+type FarmServerEvent = (FarmEventBase & {
+    type: "server.start";
+    mode: "dev" | "preview" | "production";
+    port?: number;
+}) | (FarmEventBase & {
+    type: "server.ready";
+    url?: string;
+}) | (FarmEventBase & {
+    type: "server.shutdown";
+    reason?: string;
+});
+type FarmRouteEvent = (FarmEventBase & {
+    type: "route.discovered";
+    route: string;
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "route.matched";
+    pathname: string;
+    route: string;
+    params?: Record<string, string>;
+}) | (FarmEventBase & {
+    type: "route.notFound";
+    pathname: string;
+}) | (FarmEventBase & {
+    type: "route.redirect";
+    from: string;
+    to: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "route.rewrite";
+    from: string;
+    to: string;
+});
+type FarmRenderEvent = (FarmEventBase & {
+    type: "render.start";
+    route: string;
+    pathname?: string;
+}) | (FarmEventBase & {
+    type: "render.complete";
+    route: string;
+    durationMs: number;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "render.error";
+    route?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "render.stream.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "render.stream.shellReady";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "render.stream.complete";
+    route: string;
+    durationMs: number;
+});
+type FarmCacheEvent = (FarmEventBase & {
+    type: "cache.hit";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+    stale?: boolean;
+}) | (FarmEventBase & {
+    type: "cache.miss";
+    key: string;
+    route?: string;
+    reason?: string;
+}) | (FarmEventBase & {
+    type: "cache.set";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.dedupe";
+    key: string;
+}) | (FarmEventBase & {
+    type: "cache.bypass";
+    key?: string;
+    route?: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "cache.stale";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.revalidatePath";
+    path: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.revalidateTag";
+    tag: string;
+    profile?: unknown;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.updateTag";
+    tag: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.invalidated";
+    key?: string;
+    route?: string;
+    tag?: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "cache.delete";
+    key: string;
+    deleted: boolean;
+}) | (FarmEventBase & {
+    type: "cache.clear";
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.error";
+    key?: string;
+    operation: "get" | "set" | "delete" | "revalidate";
+    error: unknown;
+});
+type FarmPPREvent = (FarmEventBase & {
+    type: "ppr.shell.hit";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.miss";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.cached";
+    route: string;
+    key: string;
+    revalidate?: number;
+}) | (FarmEventBase & {
+    type: "ppr.shell.bypass";
+    route: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.invalidated";
+    route: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "ppr.suspense.holeDetected";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.complete";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.error";
+    route: string;
+    error: unknown;
+});
+type FarmAPIEvent = (FarmEventBase & {
+    type: "api.request.start";
+    route: string;
+    method: string;
+}) | (FarmEventBase & {
+    type: "api.request.complete";
+    route: string;
+    method: string;
+    status: number;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "api.validation.failed";
+    route: string;
+    method: string;
+    issues?: unknown;
+}) | (FarmEventBase & {
+    type: "api.error";
+    route: string;
+    method: string;
+    error: unknown;
+});
+type FarmIntegrationEvent = (FarmEventBase & {
+    type: "integration.registered";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.config.validated";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.ready";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.disposed";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.start";
+    integration: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.complete";
+    integration: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "integration.api.call.error";
+    integration: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "integration.webhook.received";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.verified";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.failed";
+    integration: string;
+    reason: string;
+});
+type FarmMiddlewareEvent = (FarmEventBase & {
+    type: "middleware.start";
+    route?: string;
+    name?: string;
+}) | (FarmEventBase & {
+    type: "middleware.complete";
+    route?: string;
+    name?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "middleware.shortCircuit";
+    route?: string;
+    name?: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "middleware.error";
+    route?: string;
+    name?: string;
+    error: unknown;
+});
+type FarmStorageEvent = (FarmEventBase & {
+    type: "storage.query.start";
+    integration?: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "storage.query.complete";
+    integration?: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "storage.query.error";
+    integration?: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "storage.schema.ready";
+    integration?: string;
+}) | (FarmEventBase & {
+    type: "storage.schema.error";
+    integration?: string;
+    error: unknown;
+});
+type FarmBuildEvent = (FarmEventBase & {
+    type: "build.start";
+    target?: string;
+}) | (FarmEventBase & {
+    type: "build.complete";
+    target?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "build.error";
+    target?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "routes.generated";
+    pageCount: number;
+    apiCount?: number;
+}) | (FarmEventBase & {
+    type: "types.generated";
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "manifest.generated";
+    routeCount: number;
+});
+type FarmPluginEvent = (FarmEventBase & {
+    type: "plugin.hook.start";
+    plugin: string;
+    hook: string;
+}) | (FarmEventBase & {
+    type: "plugin.hook.complete";
+    plugin: string;
+    hook: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "plugin.hook.error";
+    plugin: string;
+    hook: string;
+    error: unknown;
+});
+type FarmErrorEvent = FarmEventBase & {
+    type: "error";
+    source: string;
+    error: unknown;
+    route?: string;
+};
+type FarmEvent = FarmServerEvent | FarmRouteEvent | FarmRenderEvent | FarmCacheEvent | FarmPPREvent | FarmAPIEvent | FarmIntegrationEvent | FarmMiddlewareEvent | FarmStorageEvent | FarmBuildEvent | FarmPluginEvent | FarmErrorEvent;
+type FarmEventType = FarmEvent["type"];
+type FarmEventHandler = (event: FarmEvent) => void | Promise<void>;
+type FarmEventInput = FarmEvent extends infer T ? T extends FarmEvent ? Omit<T, "timestamp" | "level"> & Partial<Pick<T, "timestamp" | "level">> : never : never;
+type FarmObservabilityUserConfig = boolean | {
+    logs?: boolean;
+    onEvent?: FarmEventHandler | readonly FarmEventHandler[];
+    events?: readonly FarmEventType[];
+};
+interface FarmResolvedObservabilityConfig {
+    logs: boolean;
+    handlers: FarmEventHandler[];
+    events?: Set<FarmEventType>;
+}
+declare function configureFarmObservability(config: FarmObservabilityUserConfig | undefined): void;
+declare function normalizeFarmObservabilityConfig(config: FarmObservabilityUserConfig | undefined): FarmResolvedObservabilityConfig;
+declare function onFarmEvent(handler: FarmEventHandler): () => void;
+declare function resetFarmObservability(): void;
+declare function emitFarmEvent(input: FarmEventInput): FarmEvent;
+
+export { type FarmAPIEvent, type FarmBuildEvent, type FarmCacheEvent, type FarmErrorEvent, type FarmEvent, type FarmEventBase, type FarmEventHandler, type FarmEventInput, type FarmEventLevel, type FarmEventType, type FarmIntegrationEvent, type FarmMiddlewareEvent, type FarmObservabilityUserConfig, type FarmPPREvent, type FarmPluginEvent, type FarmRenderEvent, type FarmResolvedObservabilityConfig, type FarmRouteEvent, type FarmServerEvent, type FarmStorageEvent, configureFarmObservability, emitFarmEvent, normalizeFarmObservabilityConfig, onFarmEvent, resetFarmObservability };