@spfn/core 0.3.0-beta.2 → 0.3.0-beta.4

package/dist/server/index.js

@@ -11,11 +11,13 @@ import { setDefaultSafeFetchPolicy } from '@spfn/core/security';
 import { streamSSE } from 'hono/streaming';
 import { randomBytes, createHash } from 'crypto';
 import { Agent, setGlobalDispatcher } from 'undici';
-import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, migrationTargets, closeDatabase } from '@spfn/core/db';
+import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, closeDatabase, migrationTargets } from '@spfn/core/db';
 import { initCache, getCache, closeCache } from '@spfn/core/cache';
+import { FormatRegistry, Type } from '@sinclair/typebox';
 import { serve } from '@hono/node-server';
 import PgBoss from 'pg-boss';
 import { networkInterfaces } from 'os';
+import { pathToFileURL } from 'url';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -1076,6 +1078,12 @@ async function runMigrationBootGate(config, cwd = process.cwd()) {
   );
 }
 
+// src/server/namespace.ts
+var CORE_NAMESPACE = "/_core";
+var CORE_HEALTH_PATH = `${CORE_NAMESPACE}/health`;
+var CORE_TIME_PATH = `${CORE_NAMESPACE}/time`;
+var LEGACY_HEALTH_PATH = "/health";
+
 // src/server/shutdown-manager.ts
 var DEFAULT_HOOK_TIMEOUT = 1e4;
 var DEFAULT_HOOK_ORDER = 100;
@@ -1308,7 +1316,7 @@ async function readMigrationHealth() {
     targets: migrationTargets(snapshot.status)
   };
 }
-function createHealthCheckHandler(detailed) {
+function createHealthCheckHandler(detailed, infrastructure) {
   return async (c) => {
     const shutdownManager = getShutdownManager();
     if (shutdownManager.isShuttingDown()) {
@@ -1322,23 +1330,29 @@ function createHealthCheckHandler(detailed) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     if (detailed) {
+      const databaseDisabled = infrastructure?.database === false;
+      const redisDisabled = infrastructure?.redis === false;
       let dbStatus = "unknown";
       let dbError;
-      try {
-        const db = getDatabase();
+      if (databaseDisabled) {
+        dbStatus = "disabled";
+      } else {
         try {
-          await db.execute("SELECT 1");
-          dbStatus = "connected";
+          const db = getDatabase();
+          try {
+            await db.execute("SELECT 1");
+            dbStatus = "connected";
+          } catch (error) {
+            dbStatus = "error";
+            dbError = error instanceof Error ? error.message : String(error);
+          }
         } catch (error) {
-          dbStatus = "error";
-          dbError = error instanceof Error ? error.message : String(error);
+          dbStatus = "not_initialized";
+          dbError = "Database not available";
         }
-      } catch (error) {
-        dbStatus = "not_initialized";
-        dbError = "Database not available";
       }
-      const redis = getCache();
-      let redisStatus = redis ? "unknown" : "not_initialized";
+      const redis = redisDisabled ? null : getCache();
+      let redisStatus = redisDisabled ? "disabled" : redis ? "unknown" : "not_initialized";
       let redisError;
       if (redis) {
         try {
@@ -1438,7 +1452,7 @@ function buildStartupConfig(config, timeouts) {
   const middlewareConfig = config.middleware ?? {};
   const healthCheckConfig = config.healthCheck ?? {};
   const healthCheckEnabled = healthCheckConfig.enabled !== false;
-  const healthCheckPath = healthCheckConfig.path ?? "/health";
+  const healthCheckPath = healthCheckConfig.path;
   const healthCheckDetailed = healthCheckConfig.detailed ?? env.NODE_ENV === "development";
   return {
     middleware: {
@@ -1449,6 +1463,7 @@ function buildStartupConfig(config, timeouts) {
     },
     healthCheck: healthCheckEnabled ? {
       enabled: true,
+      corePath: CORE_HEALTH_PATH,
       path: healthCheckPath,
       detailed: healthCheckDetailed
     } : { enabled: false },
@@ -1467,6 +1482,378 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  /**
+   * Create a new RouteBuilder with copied properties and optional overrides
+   */
+  clone(overrides) {
+    const builder = new _RouteBuilder();
+    builder._method = this._method;
+    builder._path = this._path;
+    builder._input = overrides?.input ?? this._input;
+    builder._interceptor = overrides?.interceptor ?? this._interceptor;
+    builder._middlewares = overrides?.middlewares ?? this._middlewares;
+    builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
+    return builder;
+  }
+  /**
+   * Define input schemas
+   *
+   * @example
+   * ```ts
+   * route.get('/users/:id')
+   *   .input({
+   *     params: Type.Object({ id: Type.String() }),
+   *     query: Type.Object({ page: Type.Number() }),
+   *     headers: Type.Object({ authorization: Type.String() })
+   *   })
+   *   .handler(async (c) => {
+   *     const { params, query, headers } = await c.data();
+   *     // params = { id: string }
+   *     // query = { page: number }
+   *     // headers = { authorization: string }
+   *   })
+   * ```
+   */
+  input(input) {
+    return this.clone({ input });
+  }
+  /**
+   * Define fields injected by interceptors
+   *
+   * These fields are:
+   * - Available in the handler (merged with input)
+   * - Excluded from client types (codegen uses only input)
+   * - Not validated by route input schema (injected by middleware)
+   *
+   * Use this when middleware/interceptors add fields to the request
+   * before it reaches the handler.
+   *
+   * @example
+   * ```ts
+   * // Auth interceptor injects crypto key fields
+   * route.post('/_auth/login')
+   *   .input({
+   *     body: Type.Object({
+   *       email: Type.String(),
+   *       password: Type.String()
+   *     })
+   *   })
+   *   .interceptor({
+   *     body: Type.Object({
+   *       publicKey: Type.String(),
+   *       keyId: Type.String(),
+   *       fingerprint: Type.String()
+   *     })
+   *   })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     // body type: { email, password, publicKey, keyId, fingerprint }
+   *     // Client only sees: { email, password }
+   *     return loginService(body);
+   *   });
+   * ```
+   */
+  interceptor(interceptor) {
+    return this.clone({ interceptor });
+  }
+  /**
+   * Add middlewares to the route
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  middleware(middlewares) {
+    return this.clone({ middlewares });
+  }
+  /**
+   * Add middlewares to the route (alias for `.middleware()`)
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  use(middlewares) {
+    return this.middleware(middlewares);
+  }
+  /**
+   * Skip server-level named middlewares
+   *
+   * Useful for public endpoints that should bypass auth or rate limiting
+   *
+   * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+   *
+   * @example
+   * ```ts
+   * // Skip specific middlewares
+   * route.get('/status')
+   *   .skip(['auth', 'rateLimit'])
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   *
+   * // Skip only auth (still apply rate limiting)
+   * route.get('/public-data')
+   *   .skip(['auth'])
+   *   .handler(async (c) => { ... });
+   *
+   * // Skip all middlewares
+   * route.get('/public-health')
+   *   .skip('*')
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   * ```
+   */
+  skip(middlewareNames) {
+    return this.clone({ skipMiddlewares: middlewareNames });
+  }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
+  /**
+   * Define handler function
+   *
+   * Response type is automatically inferred from the return value.
+   * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+   *
+   * @example
+   * ```ts
+   * // Direct return - type inferred from data
+   * route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { params } = await c.data();
+   *     return await getUser(params.id); // Type: User
+   *   })
+   *
+   * // Using c.created() - returns data with 201 status, type preserved
+   * route.post('/users')
+   *   .input({ body: Type.Object({ name: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     return c.created(await createUser(body)); // Type: User
+   *   })
+   *
+   * // Using c.paginated() - returns PaginatedResult<T>
+   * route.get('/users')
+   *   .handler(async (c) => {
+   *     const users = await getUsers();
+   *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+   *   })
+   *
+   * // Using c.noContent() - returns void
+   * route.delete('/users/:id')
+   *   .handler(async (c) => {
+   *     await deleteUser(params.id);
+   *     return c.noContent(); // Type: void
+   *   })
+   *
+   * // Using c.json() - returns Response (type inference lost)
+   * // Use only when you need custom status codes not covered by helpers
+   * route.get('/custom')
+   *   .handler(async (c) => {
+   *     return c.json({ data }, 418); // Type: Response
+   *   })
+   * ```
+   */
+  handler(fn) {
+    return {
+      method: this._method,
+      path: this._path,
+      input: this._input,
+      interceptor: this._interceptor,
+      middlewares: this._middlewares,
+      skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
+      handler: fn,
+      _input: {},
+      _interceptor: {},
+      _response: {}
+    };
+  }
+};
+function createMethodRoute(method) {
+  return (path) => {
+    const builder = new RouteBuilder();
+    builder._method = method;
+    builder._path = path;
+    return builder;
+  };
+}
+var route = {
+  get: createMethodRoute("GET"),
+  post: createMethodRoute("POST"),
+  put: createMethodRoute("PUT"),
+  patch: createMethodRoute("PATCH"),
+  delete: createMethodRoute("DELETE")
+};
+
+// src/route/router.ts
+function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
+  return {
+    routes,
+    _routes: routes,
+    _packageRouters: packageRouters,
+    _globalMiddlewares: globalMiddlewares,
+    _contractVersion: contractVersion,
+    packages(routers) {
+      const newPackageRouters = [...this._packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      return createRouterInstance(
+        this.routes,
+        newPackageRouters,
+        this._globalMiddlewares,
+        this._contractVersion
+      );
+    },
+    use(middlewares) {
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        [...this._globalMiddlewares, ...middlewares],
+        this._contractVersion
+      );
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        this._globalMiddlewares,
+        version
+      );
+    }
+  };
+}
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
+function defineRouter(routes) {
+  return createRouterInstance(routes);
+}
+
+// src/route/validation.ts
+FormatRegistry.Set(
+  "email",
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+);
+FormatRegistry.Set(
+  "uri",
+  (value) => /^https?:\/\/.+/.test(value)
+);
+FormatRegistry.Set(
+  "uuid",
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+);
+FormatRegistry.Set(
+  "date",
+  (value) => /^\d{4}-\d{2}-\d{2}$/.test(value)
+);
+FormatRegistry.Set(
+  "date-time",
+  (value) => !isNaN(Date.parse(value))
+);
+
+// src/server/server-time.ts
+var CORE_TIME_OPERATION_ID = "core.time";
+var ServerTimeResponseSchema = Type.Object({
+  serverTimeMillis: Type.Integer()
+}, { additionalProperties: false });
+var systemServerClock = {
+  now: () => Date.now()
+};
+function createCoreTimeRoute(clock = systemServerClock) {
+  return route.get(CORE_TIME_PATH).skip("*").contract({
+    since: "0.3.0",
+    auth: "none",
+    requiresSession: false,
+    response: ServerTimeResponseSchema
+  }).handler(async (c) => {
+    const response = {
+      serverTimeMillis: clock.now()
+    };
+    c.raw.header("Cache-Control", "no-store");
+    return response;
+  });
+}
+var CORE_TIME_ROUTE = createCoreTimeRoute();
+function createCoreTimeRouter(clock) {
+  return defineRouter({
+    [CORE_TIME_OPERATION_ID]: createCoreTimeRoute(clock)
+  });
+}
+
 // src/server/create-server.ts
 var rateLimitApplied = /* @__PURE__ */ new WeakSet();
 async function createServer(config) {
@@ -1509,12 +1896,16 @@ async function createAutoConfiguredApp(config) {
   applyDefaultMiddleware(app, config, enableLogger, enableCors);
   await applyProxyGuard(app, config);
   applyRateLimit(config);
+  registerCoreTimeEndpoint(app, config);
   if (Array.isArray(config?.use)) {
     config.use.forEach((mw) => app.use("*", mw));
   }
-  registerHealthCheckEndpoint(app, config);
+  registerCoreHealthEndpoint(app, config);
   await executeBeforeRoutesHook(app, config);
-  await loadAppRoutes(app, config);
+  const appRoutes = await loadAppRoutes(app, config);
+  registerMovedHealthSignpost(app, config, appRoutes);
+  warnOnShadowedOptInPath(config, appRoutes);
+  warnOnCoreNamespaceRoutes(appRoutes);
   await registerSSEEndpoint(app, config);
   await executeAfterRoutesHook(app, config);
   if (enableErrorHandler) {
@@ -1555,7 +1946,10 @@ async function applyProxyGuard(app, config) {
       serverLogger.warn("Proxy-guard nonce: cache module unavailable \u2014 using in-memory store (single instance only)");
     }
   }
-  const autoSkip = [config?.healthCheck?.path ?? "/health"];
+  const autoSkip = [CORE_HEALTH_PATH, CORE_TIME_PATH, LEGACY_HEALTH_PATH];
+  if (config?.healthCheck?.path) {
+    autoSkip.push(config.healthCheck.path);
+  }
   if (config?.events) {
     autoSkip.push(config.eventsConfig?.path ?? "/events/stream");
   }
@@ -1598,15 +1992,79 @@ function applyOutboundFetch(config) {
   const policy = config?.outboundFetch ?? { blockPrivateIps: env.SAFE_FETCH_BLOCK_PRIVATE_IPS };
   setDefaultSafeFetchPolicy(policy);
 }
-function registerHealthCheckEndpoint(app, config) {
+function resolveHealthCheck(config) {
   const healthCheckConfig = config?.healthCheck ?? {};
-  const healthCheckEnabled = healthCheckConfig.enabled !== false;
-  const healthCheckPath = healthCheckConfig.path ?? "/health";
-  const healthCheckDetailed = healthCheckConfig.detailed ?? process.env.NODE_ENV === "development";
-  if (healthCheckEnabled) {
-    app.get(healthCheckPath, createHealthCheckHandler(healthCheckDetailed));
-    serverLogger.debug(`Health check endpoint enabled at ${healthCheckPath}`);
+  return {
+    enabled: healthCheckConfig.enabled !== false,
+    // No default. An unset `path` means the endpoint answers at
+    // CORE_HEALTH_PATH and nowhere else — a default here is what used to put
+    // it on /health without anyone asking.
+    path: healthCheckConfig.path,
+    detailed: healthCheckConfig.detailed ?? process.env.NODE_ENV === "development"
+  };
+}
+function registerCoreTimeEndpoint(app, config) {
+  registerRoutes(app, createCoreTimeRouter(config?.serverTime?.clock));
+  serverLogger.debug(`Server time endpoint enabled at ${CORE_TIME_PATH}`);
+}
+function registerCoreHealthEndpoint(app, config) {
+  const { enabled, path, detailed } = resolveHealthCheck(config);
+  if (!enabled) {
+    return;
+  }
+  const handler = createHealthCheckHandler(detailed, config?.infrastructure);
+  app.get(CORE_HEALTH_PATH, handler);
+  serverLogger.debug(`Health check endpoint enabled at ${CORE_HEALTH_PATH}`);
+  if (path && path !== CORE_HEALTH_PATH) {
+    app.get(path, handler);
+    serverLogger.debug(`Health check endpoint also answering at ${path}, as configured`);
+  }
+}
+function registerMovedHealthSignpost(app, config, appRoutes) {
+  const { enabled, path } = resolveHealthCheck(config);
+  if (!enabled || path === LEGACY_HEALTH_PATH) {
+    return;
+  }
+  if (appRoutes.some((r) => r.method === "GET" && r.path === LEGACY_HEALTH_PATH)) {
+    return;
+  }
+  let warned2 = false;
+  app.get(LEGACY_HEALTH_PATH, (c) => {
+    if (!warned2) {
+      warned2 = true;
+      serverLogger.warn(
+        `\u26A0\uFE0F  GET ${LEGACY_HEALTH_PATH} is answering 410: @spfn/core no longer serves it. Point your readiness probe, Dockerfile HEALTHCHECK and load balancer at ${CORE_HEALTH_PATH}, or restore this path with healthCheck({ path: '${LEGACY_HEALTH_PATH}' }). This notice is removed in the next release.`
+      );
+    }
+    return c.json({
+      error: "health endpoint moved",
+      movedTo: CORE_HEALTH_PATH,
+      detail: `@spfn/core no longer serves ${LEGACY_HEALTH_PATH}. Point your readiness probe, Dockerfile HEALTHCHECK and load balancer at ${CORE_HEALTH_PATH}, or restore this path with healthCheck({ path: '${LEGACY_HEALTH_PATH}' }).`
+    }, 410);
+  });
+}
+function warnOnShadowedOptInPath(config, appRoutes) {
+  const { enabled, path } = resolveHealthCheck(config);
+  if (!enabled || !path || path === CORE_HEALTH_PATH) {
+    return;
+  }
+  const shadowed = appRoutes.filter((r) => r.method === "GET" && r.path === path);
+  if (shadowed.length === 0) {
+    return;
   }
+  serverLogger.warn(
+    `\u26A0\uFE0F  ${shadowed.map((r) => r.name).join(", ")} never runs: GET ${path} is served by the built-in health endpoint, which healthCheck({ path }) asked for and which is registered before app routes. Drop that option, or move the route to a path your app owns.`
+  );
+}
+function warnOnCoreNamespaceRoutes(appRoutes) {
+  const inside = appRoutes.filter((r) => r.path === CORE_NAMESPACE || r.path.startsWith(`${CORE_NAMESPACE}/`));
+  if (inside.length === 0) {
+    return;
+  }
+  const names = inside.map((r) => `${r.name} (${r.method} ${r.path})`).join(", ");
+  serverLogger.warn(
+    `\u26A0\uFE0F  ${names} never runs: ${CORE_NAMESPACE}/ belongs to @spfn/core and its endpoints are registered before app routes. Move the route to a path your app owns.`
+  );
 }
 async function executeBeforeRoutesHook(app, config) {
   if (config?.lifecycle?.beforeRoutes) {
@@ -1618,9 +2076,12 @@ async function loadAppRoutes(app, config) {
   if (config?.routes) {
     const routes = registerRoutes(app, config.routes, config.middlewares);
     logRegisteredRoutes(routes, debug);
-  } else if (debug) {
+    return routes;
+  }
+  if (debug) {
     serverLogger.warn("\u26A0\uFE0F  No routes configured. Use defineServerConfig().routes() to register routes.");
   }
+  return [];
 }
 function logRegisteredRoutes(routes, debug) {
   if (routes.length === 0) {
@@ -2285,6 +2746,45 @@ function printBanner(options) {
   }
   console.log("");
 }
+var PORT_DEFAULTS = {
+  server: 8790
+};
+var HOST_DEFAULT = "localhost";
+var CONFIG_FILE_NAMES = [
+  "spfn.config.js",
+  "spfn.config.mjs"
+];
+async function loadAppConfig(cwd = process.cwd()) {
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const fullPath = join(cwd, fileName);
+    if (!existsSync(fullPath)) {
+      continue;
+    }
+    try {
+      const module = await import(pathToFileURL(fullPath).href);
+      return module.default ?? {};
+    } catch (error) {
+      console.warn(
+        `\u26A0\uFE0F  ${fileName} could not be imported \u2014 falling back to defaults for ports and host. ${error instanceof Error ? error.message : String(error)}`
+      );
+      return {};
+    }
+  }
+  return {};
+}
+function resolveServerAddress(config, deprecated = {}, env6 = process.env) {
+  return {
+    port: readPort(env6.SPFN_PORT) ?? config.ports?.server ?? deprecated.port ?? PORT_DEFAULTS.server,
+    host: env6.SPFN_HOST || config.host || deprecated.host || HOST_DEFAULT
+  };
+}
+function readPort(value) {
+  if (!value) {
+    return void 0;
+  }
+  const port = Number(value);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : void 0;
+}
 
 // src/server/validation.ts
 function validateServerConfig(config) {
@@ -2333,10 +2833,12 @@ var TIMEOUTS = {
   REDIS_CLOSE: 5e3};
 var CONFIG_FILE_PATHS = [
   ".spfn/server/server.config.mjs",
+  ".spfn/server/server.config.js",
   ".spfn/server/server.config",
   "src/server/server.config",
   "src/server/server.config.ts"
 ];
+var AUTHORED_CONFIG_PATH = "src/server/server.config.ts";
 var processHandlersRegistered = false;
 async function startServer(config) {
   loadEnv();
@@ -2400,8 +2902,7 @@ async function startServer(config) {
     throw error;
   }
 }
-async function loadAndMergeConfig(config) {
-  const cwd = process.cwd();
+async function loadAndMergeConfig(config, cwd = process.cwd()) {
   let fileConfig = {};
   let loadedConfigPath = null;
   for (const configPath of CONFIG_FILE_PATHS) {
@@ -2419,16 +2920,37 @@ async function loadAndMergeConfig(config) {
   }
   if (loadedConfigPath) {
     serverLogger.debug(`Loaded configuration from ${loadedConfigPath}`);
+  } else if (existsSync(join(cwd, AUTHORED_CONFIG_PATH))) {
+    serverLogger.warn(
+      `\u26A0\uFE0F  ${AUTHORED_CONFIG_PATH} exists but no configuration was loaded, so this server is running on defaults: no middlewares, no routes and no infrastructure settings from it. Run "spfn build" so the compiled config lands in .spfn/server/.`
+    );
   } else {
     serverLogger.debug("No configuration file found, using defaults");
   }
+  const appConfig = await loadAppConfig(cwd);
+  warnOnDeprecatedAddress(config, fileConfig);
+  const address = resolveServerAddress(appConfig, {
+    port: config?.port ?? fileConfig?.port,
+    host: config?.host ?? fileConfig?.host
+  });
   return {
     ...fileConfig,
     ...config,
-    port: config?.port ?? fileConfig?.port ?? env.PORT,
-    host: config?.host ?? fileConfig?.host ?? env.HOST
+    port: address.port,
+    host: address.host
   };
 }
+function warnOnDeprecatedAddress(config, fileConfig) {
+  const used = [
+    (config?.port ?? fileConfig?.port) !== void 0 ? ".port()" : null,
+    (config?.host ?? fileConfig?.host) !== void 0 ? ".host()" : null
+  ].filter(Boolean);
+  if (used.length > 0) {
+    serverLogger.warn(
+      `\u26A0\uFE0F  ${used.join(" and ")} in server.config is deprecated and will be removed. Move the address to spfn.config.js \u2014 \`ports: { next, server }\` and \`host\` \u2014 so the Dockerfile, the compose file and next.config can read the same value.`
+    );
+  }
+}
 function getInfrastructureConfig(config) {
   return {
     database: config.infrastructure?.database !== false,
@@ -3088,6 +3610,15 @@ var ServerConfigBuilder = class {
     this.config.healthCheck = healthCheck;
     return this;
   }
+  /**
+   * Supply the clock used by the built-in `GET /_core/time` capability.
+   * Production servers normally keep the default `Date.now()` clock; this is
+   * exposed so tests can assert an exact wire value without replacing globals.
+   */
+  serverTime(serverTime) {
+    this.config.serverTime = serverTime;
+    return this;
+  }
   /**
    * Configure infrastructure initialization
    */
@@ -3184,6 +3715,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { PendingMigrationsError, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, PendingMigrationsError, ServerTimeResponseSchema, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map